agent-infra: Skill for Claude Code

更新项目

执行约束

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>）