更新项目

执行约束

1. 确定性步骤脚本化：managed / ejected 文件处理、注册表同步、配置更新 全部由 sync-templates.js 脚本执行，不得逐文件手工处理。 脚本保证原子性和幂等性。

2. 禁止委托子代理：阶段 B（merged 文件智能合并）必须在主会话中直接执行， 不得委托给子代理。子代理上下文有限，容易误判文件内容。

阶段 A：运行同步脚本（确定性）

执行以下命令，一次性处理所有确定性步骤：

node .agents/skills/update-agent-infra/scripts/sync-templates.js

脚本读取 .agents/.airc.json，并通过 npm 自动定位已安装的 @fitlab-ai/agent-infra/templates/ 目录。同步前会合并 templates.sources 中配置的外部模板源；相同文件以内置模板为准，多个外部源之间后者覆盖前者，冲突会写入报告。然后自动完成：

• 检测模板源版本
• 同步文件注册表（defaults.json → .agents/.airc.json）
• 处理所有 managed 文件（语言选择 → 排除 merged/ejected → 占位符渲染 → 写入；内建 guarded managed 文件使用来源基线三方比较）
• 处理 ejected 文件（仅首次安装时创建）
• 更新 .agents/.airc.json（templateVersion、文件列表）

脚本输出 JSON 到 stdout，解析并记录报告内容。

关键字段：

• error：错误信息（如非空则停止并报告）
• templateVersion：模板源包的精确 v 前缀 SemVer（可包含 prerelease 或 build metadata）
• templateRoot：模板文件根目录绝对路径
• templateSources.conflicts：外部模板源冲突列表；报告中必须显式展示，说明哪些文件因内置模板或后续外部源获胜而被忽略
• managed.written / managed.created：已更新/新建的 managed 文件
• managed.protected：检测到用户单边修改或删除、因此保留本地状态的 guarded managed 文件
• managed.conflicts：来源未知、双边修改或平台切换时无法证明官方所有权的 guarded managed 冲突；必须逐项展示 target、reason 与三方哈希
• managed.removed：被删除的 managed 文件（包括模板迁移时移除的旧路径）
• managed.skippedPlatform：因归属其他平台而被跳过的 managed / merged 条目
• managed.skippedTUI：因对应内建 Agent Client 的 agentClients[].enabled 为 false 而被跳过的 managed / merged 条目
• merged.pending：需要 AI 处理的 merged 文件列表
  • 每项包含 target（项目中的目标路径）和 template（模板根目录下的相对路径）
• registryAdded：新增的文件注册条目
• configUpdated：.agents/.airc.json 是否已更新

managed.conflicts 是逐文件冲突，不是整轮同步的中止条件。同步脚本会跳过冲突目标，并保留该目标的当前文件和 files.managedBaselines；其它无冲突的 managed / ejected 文件及配置照常处理。即使冲突列表非空，也继续阶段 B 处理全部 merged.pending，最后在阶段 C 汇总报告所有冲突。任何阶段都不得覆盖冲突文件或推进该文件的基线。

阶段 B：处理 merged 文件（AI 智能合并）

根据报告中 merged.pending 列表，逐个文件处理。对于每个条目：

1. 从 <templateRoot>/<template> 读取模板文件
2. 渲染占位符：将双花括号包裹的 project 和 org 占位符替换为 .agents/.airc.json 中的实际值
3. 读取本地当前文件（<项目根>/<target>）

如果本地文件不存在（首次安装），直接写入渲染后的模板，跳过合并。

如果本地文件存在，执行以下合并算法：

B.1 以模板为基底

使用渲染后的新模板作为输出的基底。模板代表最佳实践，其结构和内容具有权威性。

B.2 从本地文件萃取增量

扫描本地文件，找出比模板内容"多"的部分（用户增量）：

• 已填充的 TODO：模板中的 TODO 占位符在本地文件中被替换为实际内容
• 新增段落/章节：本地文件中存在但模板中不存在的内容
• 扩展内容：对模板现有内容的补充说明

B.3 合入新模板

将萃取的增量合入新模板的适当位置：

• 已填充的 TODO → 替换对应的 TODO 占位符
• 新增段落 → 插入最相关的位置
• 扩展内容 → 合入对应章节

B.4 通读验证

整体检查合并后文件的逻辑完整性，确保：

• 增量合入位置正确
• 无重复内容
• 文档结构连贯

B.5 冲突处理

当本地文件修改过的内容与模板新内容冲突时：

• 保留模板版本（模板权威性原则）
• 在报告中提示用户该冲突，以便用户确认

B.6 残余 TODO 提示

合并完成后，如果仍有模板 TODO 未被本地文件的内容填充，在报告中提示用户。

阶段 C：验证与输出报告

方向检查：用 git diff 抽查变更方向是否正确。 正确方向：模板新内容 → 本地；错误方向：将已渲染内容退化回占位符。 如果发现错误方向的变更，暂停并排查原因。

自身更新检测

检查 git diff 中是否包含 .agents/skills/update-agent-infra/SKILL.md 的变更。 如果该文件在本次更新中被修改，在报告末尾输出以下警告：

⚠ update-agent-infra 技能自身已更新。
  建议再次执行 /update-agent-infra 以确保所有新逻辑生效。

原因：本次执行使用的是旧版技能逻辑，新版技能可能包含额外的处理步骤。 再次执行可确保新逻辑完整应用。 用户也可以在执行前先运行 ai sync 来预先更新技能文件，避免需要两次执行。

输出报告

基于脚本报告和 merged 合并结果，输出完整的更新报告，包括：

• 模板版本变更
• 文件注册表新增条目
• 外部模板源冲突（如 templateSources.conflicts 非空，必须逐项列出）
• managed 文件变更明细（已更新、新建、跳过的 merged 文件）
• merged 文件合并结果（冲突、残余 TODO）
• ejected 文件处理
• 自身更新检测结果

如有变更需要提交，追加：

渲染下一步前先读取 .agents/rules/next-step-output.md，仅为已选场景调用统一 helper，并将 stdout 填入 {next-step-commands}。

使用 agent-infra-internal agent-client next-steps --skill commit 生成本场景的 {next-step-commands}。

下一步 - 提交代码：
{next-step-commands}

输出报告后停止，不要对项目做其他更改。