配置版本管理与密钥

🔵 config/ 树可以作为 git 仓库保存：通过主机（builder、模块开关、提供程序、密钥）所做的任何配置更改都会成为一个版本——可以在历史中看到、可以比较、可以回滚。密钥存储在同一个仓库中，但以加密形式保存。

文件访问和 git 保留在主机上，位于敏感端口 agent_os.Versioning 之后；HTTP 和 UI 界面由功能模块 versioning 提供。

44.1 模型：checkpoint、seal、auto-seal

写入分为两个层级，以便历史既可靠又有意义：

层级	由谁执行	是什么
checkpoint	自动，主机	每次配置更改后的机械提交。重复的 checkpoint 会合并为一个提交（`--amend`），直到下一次 seal。
seal	管理员/代理	一个带有有意义消息的提交，将自上次 seal 以来的所有 checkpoint 合并（`git reset --soft`）。
auto-seal	主机	空闲时 seal，如果设置了 `autoseal_idle_secs`。

每个提交都带有机器可读的尾部标记 Agent / Session / Source；消息正文为人类可读：

Add currency tool to felix

Agent: admin
Session: 4f2a9c…
Source: tool:config_commit

checkpoint 仅在 seal 之间用于保存；在 seal 后的最终历史中，每个有意义的修改只保留一个提交。

44.2 启用

# config/server.yaml
versioning:
  enabled: true          # по умолчанию выключено
  branch: config         # ветка записи (для git-источника — ветка из --config-ref)
  remote: origin         # опционально, для push
  push: false            # push после seal
  autoseal_idle_secs: 300
  secrets:
    mode: mixed          # sealed | mixed | plaintext
    key_file: ~/.agent-os/config.key

模块 versioning 必须已启用（id versioning 在 config/modules.enabled 或 server.yaml → modules.enabled 中）。首次以 enabled: true 启动时，会在配置根目录创建仓库（.git、.gitignore）以及第一个提交 Initial config version。

44.3 Git 源（`--config-repo`）

当配置从 git 克隆时（参见服务器配置），版本管理在此克隆之上工作：

克隆是完整的（非 shallow），并且位于本地分支（--config-ref）上，而不是 detached HEAD——否则无法提交和推送；
配置轮询器执行 merge --ff-only，在出现差异时执行 rebase，也就是说本地提交不会被覆盖；冲突仅记录日志；
外部更新后，baseline seal 会重新绑定，以免 seal 合并他人的提交；
push: true 在 seal 之后将分支推送到 remote（需要 remote 访问权限）。

git -c user.name/email 为提交在本地设置（Agent OS <agent-os@localhost>), core.autocrlf=false——配置文件逐字节一致。

44.4 密钥

密钥存储在 config/secrets.yaml 中，作为 { enc: … } / { plain: … } 节点：

scopes:
  global:
    OPENAI_API_KEY: { enc: "v1:…" }   # зашифровано (AES-256-GCM)
  admin:
    region:         { plain: "eu" }   # открытый текст (если политика разрешает)

加密：对称 AES-256-GCM，每个值一个 nonce；仅在内存中解密。在磁盘和 git 中为密文。
密钥：AGENT_OS_CONFIG_KEY（base64 或 hex，32 字节）或文件 versioning.secrets.key_file（默认 ~/.agent-os/config.key，在首次 sealed 值时创建）。密钥不纳入版本管理。
mode 策略：
- sealed — 仅 { enc: … }，明文被拒绝；
- mixed — 按值（默认）；
- plaintext — 无密钥（dev/CI/单主机）。
值对外从不返回：list_secrets 仅返回 scope/key/mode。

版本管理的例外：.env 和 env.overrides.yaml（机器本地状态）。keys/deploy_key 仍是有意保留的公开例外。

44.5 HTTP API (ACCESS_ADMIN)

方法	路径	作用
GET	`/v1/versioning/status`	`{ enabled, initialized, branch, head, dirty, remote, push }`
GET	`/v1/versioning/log?path=&limit=`	提交历史（最新在前）
GET	`/v1/versioning/diff?from=&to=&path=`	修订版本之间的 unified diff
GET	`/v1/versioning/show?rev=&path=`	某修订版本上的文件
POST	`/v1/versioning/commit`	`{ message }` — seal
POST	`/v1/versioning/restore`	`{ rev, path? }` — 回滚
POST	`/v1/versioning/push`	推送到 `remote`
GET	`/v1/versioning/secrets?scope=`	密钥列表（不含值）
POST	`/v1/versioning/secrets`	`{ scope?, key, value, mode? }`

restore 会覆盖工作树文件；live reload 无需重启即可拾取更改。

44.6 UI

页面 /platform/versions（菜单 Platform →「配置版本」，所有者 agent_os_versioning）：提交列表、所选提交的 diff、手动固定（seal）、restore、push。

44.7 代理工具

工程师代理（admin，通过 tool_call）可使用：config_versions、config_version_show、config_version_diff、config_version_restore（需确认！）、config_commit、secrets_list、secrets_set。

44.8 备份

当版本管理启用时，builder 不会将完整副本写入 config/agents/.backups/——它们由 git 历史取代。禁用时——保持原有行为。