aios/docs/implementation-baseline-1.1/INSTALLATION.md

AIOS Implementation Baseline 1.1：安装、验证与回滚

本包交付架构修订、可执行代码、隔离验证闭环和源码变更工具。默认运行 isolated-validation profile；线上 Task/Job/Release 的实际写权威绑定、真实发布和生产业务验收仍须通过现场门禁。源码包安装完成不能作为生产发布完成的证据。

1. 先确认包身份和运行前提

提供的源码来自用户上传 ZIP，原始 ZIP SHA-256 为 fd28f8f065873c5600f17de0a536cae6f4bc18567687fd3f178d67ad8c1f931a。本地导入基线为 f5d015249604ce5bdacfd707608f83e8a3875f60；这是离线快照身份，不是远端 main 或当前 runtime 的证明。

最终包的顶层路径约定：

路径	用途
source/aios/	完整修改后源码；首先阅读根 README 和本文件
source-baseline.git.bundle	可离线恢复原始导入 commit 的 Git 对象
source-changes.zip	每文件 before/after hash、旧/新内容及 manifest
根目录校验清单与验收结果	本次实际生成的包身份及本地测试证据；以根 README 中的实际文件名为准

需要 Python 3.11+、Git，以及源码依赖清单中固定版本的 cryptography。运行测试需要 pytest。真实服务诊断需要 Linux/systemd 以及可读取状态的现存 .service。源码包工具只依赖 Python 标准库和 Git。使用包内依赖说明准备独立虚拟环境，不自动升级或覆盖正在运行的 AIOS Python 环境。

SHA-256 校验只证明字节完整性；它不证明 Owner 业务授权。使用可信的交付来源，并保留实际下载包的校验值。不要将测试生成的密钥、token 或 Grant 移入生产信任域。

2. 源码隔离部署：先 dry-run，再 stage

以下命令从已解压完整包的顶层执行。路径变量只用于这次安装；所有目标目录必须全新，父目录须存在。

export AIOS_PACKAGE_ROOT="$PWD"
export AIOS_BASE_REPO="$AIOS_PACKAGE_ROOT/clean-baseline"
export AIOS_STAGE="$AIOS_PACKAGE_ROOT/staged-baseline-1.1"

python3 "$AIOS_PACKAGE_ROOT/source/aios/tools/baseline_v1_1/bundle.py" verify \
  "$AIOS_PACKAGE_ROOT/source-changes.zip"

git init "$AIOS_BASE_REPO"
git -C "$AIOS_BASE_REPO" fetch "$AIOS_PACKAGE_ROOT/source-baseline.git.bundle" HEAD
git -C "$AIOS_BASE_REPO" checkout --detach FETCH_HEAD

python3 "$AIOS_PACKAGE_ROOT/source/aios/tools/baseline_v1_1/bundle.py" stage \
  "$AIOS_PACKAGE_ROOT/source-changes.zip" \
  --source "$AIOS_BASE_REPO" --destination "$AIOS_STAGE" --dry-run

python3 "$AIOS_PACKAGE_ROOT/source/aios/tools/baseline_v1_1/bundle.py" stage \
  "$AIOS_PACKAGE_ROOT/source-changes.zip" \
  --source "$AIOS_BASE_REPO" --destination "$AIOS_STAGE"

stage 不修改 --source。它校验源仓库 clean、HEAD、所有基线受跟踪文件的 hash/mode，再创建独立副本；应用 manifest 后保留基线 HEAD 和可审查的工作区差异。它拒绝既有目标、未知目标覆盖、符号链接、路径穿越、ZIP 未声明成员、缺失文件、错基线及字节篡改。不会启动 systemd、写线上权威库、启用 legacy global write 或运行仓库脚本。

已有真实仓库与导入基线不一致时，stage 拒绝是预期行为。不要使用 --force、重写线上 HEAD 或伪造 before hash。将包内变化在真实仓库的独立 worktree 中审查/移植，重新建立该仓库的源码与验收身份，再走原有变更治理链。本工具没有绕过开关。

Git 忽略文件不属于基线内容，不会复制到候选目录。不要在源目录依赖未声明的 overlay、运行态数据库或私有凭证。工具当前以普通文件和可执行普通文件为交付对象，遇到符号链接、Git submodule、异常文件布局或超限包会安全拒绝。

3. 执行本地验收

在已准备依赖的独立 Python 环境中运行：

cd "$AIOS_STAGE"
export PYTHONPATH="$AIOS_STAGE/active-runtime/app"
export PYTHONDONTWRITEBYTECODE=1
python3 -m pytest -q tests/baseline_v1_1

本地测试包含真实 SQLite、Ed25519 签名、临时 Git 仓库、HTTP transport 和受限子进程等行为测试；其中可控替身用于模拟远端系统和故障。测试通过不代表已连接用户主机、不代表主机断电与磁盘耗尽已现场复现，也不代表生产业务验收通过。具体 AT-01～AT-23 范围见 ACCEPTANCE_MATRIX.md 和本次实际测试结果。

保存测试命令、Python/依赖版本、源码身份、配置摘要和退出码；不要把 token 或私钥放进验收报告。任何源代码或运行配置变化后，旧证据不能无条件用于放行新候选。

4. 跑第一条真实非发布闭环

选择当前 Linux 主机中一个已存在、允许当前用户只读查询的服务，并将下方 YOUR_EXISTING_SERVICE.service 替换成准确的 unit 名。此步骤只调用固定的 systemctl show 状态读取；不重启服务。

export AIOS_VALIDATION_DIR="$AIOS_PACKAGE_ROOT/validation-run"
python3 -m aios_baseline.cli init-validation \
  --directory "$AIOS_VALIDATION_DIR" \
  --service-unit YOUR_EXISTING_SERVICE.service

python3 -m aios_baseline.cli preflight --config "$AIOS_VALIDATION_DIR/server.json"
python3 -m aios_baseline.cli grant-import \
  --config "$AIOS_VALIDATION_DIR/server.json" --grant "$AIOS_VALIDATION_DIR/grant.json"

init-validation 仅为新建的本地验证实例生成测试身份和一个最多 20 个 effect、限定 service-status/sample/staging 的 Grant。它不会覆盖既有目录。实际部署使用已安装的信任身份和明确签署的业务授权，不复用这里生成的密钥。preflight 返回 CONFIG_VALID 仅表示配置检查通过，同时会明确 online_authority=NOT_VERIFIED、production_activation=BLOCKED。

在终端 A 启动服务：

python3 -m aios_baseline.cli server --config "$AIOS_VALIDATION_DIR/server.json"

在已设置相同路径变量和 PYTHONPATH 的终端 B 提交目标并运行真实 Worker：

python3 -m aios_baseline.cli goal-submit \
  --token-file "$AIOS_VALIDATION_DIR/user.token" \
  --request "$AIOS_VALIDATION_DIR/goal.json" \
  --idempotency-key first-service-diagnostic

python3 -m aios_baseline.cli worker \
  --config "$AIOS_VALIDATION_DIR/worker.json" --once

python3 -m aios_baseline.cli goal-explain \
  --token-file "$AIOS_VALIDATION_DIR/user.token" \
  --mission-id validation-mission

关联链应包含 Task、effect/job 和经验证的诊断 receipt；这是非发布任务，不应虚构 Release/Deployment/Acceptance。进程完成“诊断”与被诊断服务 healthy=true 是两个不同事实。服务不健康时仍须返回真实 observation，不能将诊断执行成功冒充组件健康。

常驻 Worker 使用相同命令去掉 --once。聊天中的 GPT 没有此 Worker 的常驻身份、heartbeat 或 transport，不是 fallback worker。将受信 Worker 配置的 fallback_executor 设为 true 后，调度按 readiness 时间扩大其 eligibility，仍走同一 CAS、lease 和 fencing。

5. systemd 验证实例与现场门禁

候选 unit 位于 deploy/baseline-v1.1/，均以 .example 结尾。API 与 Worker 使用独立 UID、各自 credential projection、固定 loopback transport 和有限资源。替换 @RELEASE_ROOT@ 和 @PYTHON_EXECUTABLE@（已验收的独立 Python 环境）、配置只读发行目录、既有信任身份与独立状态目录之后，先执行 systemd-analyze verify 检查已渲染 unit。详细凭证名称及隔离规则见该目录的 CREDENTIALS.md。

本包不会自动创建系统用户、复制凭证、安装或启用 unit。上述操作由实际安装角色在已批准的主机范围内完成。它们是配置绑定与部署行为，不要求重新签署仍有效的业务 Grant；若实际组件、环境、破坏性级别或预算超出授权，才进入真实 Owner 边界。

将 ACTIVATION_GATES.json 复制为本次验收记录并逐项填入证据引用。不得把 NOT_RUN 批量改成 PASS。生产接入需要另外完成官方 Task authority adapter、Release recipe 的实际受治理 operation adapter、可信业务验收 verifier、单一活跃写权威切换和恢复演练。本地 validation profile 明确拒绝 production 配置。

6. 回滚与存储恢复

仅回滚隔离候选源码：

python3 "$AIOS_PACKAGE_ROOT/source/aios/tools/baseline_v1_1/bundle.py" rollback \
  --directory "$AIOS_STAGE" --dry-run

python3 "$AIOS_PACKAGE_ROOT/source/aios/tools/baseline_v1_1/bundle.py" rollback \
  --directory "$AIOS_STAGE"

工具在首次写入前检查所有受影响文件当前仍为已部署 after hash/mode，并要求 HEAD 未产生后续提交；发现本地修改、符号链接或对象冲突即拒绝，不覆盖后改内容。回滚只恢复包内源码，不撤销远端副作用、不回退数据库、不修改 systemd。执行回滚前停止使用该候选目录的验证进程；对运行中的发行目录不使用本工具原地回滚。

源码回退与业务补偿是不同操作。Release 是否允许回退由目标 artifact、数据兼容性和已验证 rollback operation 决定。存储恢复需先停止新 effect 准入，使用 SQLite backup API 或停止写者后的完整一致副本，同时恢复 Git/receipt/关联身份；只复制活跃 SQLite 主 DB 文件不构成可靠备份。恢复后先对账未决 effect，再恢复调度，记录实测 RPO/RTO。无法可靠记录 intent/lease/receipt 时，不得继续产生新副作用。

7. 重新生成变更包

由维护者在受审查的修改后源码仓库中执行；输出必须位于源码目录之外，且不能覆盖既有文件：

python3 tools/baseline_v1_1/bundle.py create \
  --repo "$AIOS_STAGE" \
  --base f5d015249604ce5bdacfd707608f83e8a3875f60 \
  --output "$AIOS_PACKAGE_ROOT/reviewed-source-changes.zip"

输出 manifest 保存每个 added/modified/deleted 文件的 before/after SHA-256 与 mode，并包含精确的旧、新内容。重新生成后须重新验收和记录新包身份；不能沿用旧包的验收结论。