apply-template

应用 ai-env 模板

将 Agentic 开发环境模板应用到当前仓库。

参数： ai-env 克隆仓库的可选路径。不提供参数 = 从 GitHub 克隆（主要路径）。

---

阶段 0 — 准备检查

检查工作区是否干净

运行 git status --porcelain。如果存在未提交的更改，提醒用户并询问是继续还是先暂存。工作区不干净会增加审查模板更改的难度。

---

阶段 1 — 源解析与发现

定位模板源

1. 如果提供了参数，使用该路径并确认它是干净的 Git 工作区
2. 如果未提供参数，从 GitHub 克隆： git clone --depth 1 https://github.com/camacho/ai-env.git /tmp/ai-env-template 并使用该目录
3. 如果默认本地路径 ~/projects/camacho/ai-env 存在且未提供参数，优先使用 GitHub 克隆（确保获取最新版本）
4. 如果都失败，告知用户并停止

读取清单

从模板源目录读取 apply-template.manifest.json。该文件将每个文件归类为 copy_if_absent、smart_merge 或 skip。

扫描目标

检查当前仓库（cwd）中是否已存在任何 copy_if_absent 和 smart_merge 文件。

对于目标中已存在的 copy_if_absent 文件：将对其进行智能合并（而非跳过），以获取模板中的新增内容，同时保留目标中的自定义内容。

呈现计划

向用户展示摘要：

Template Application Plan:
  Source: <path>
  Target: <cwd>

  Copy (new):        N files — <list>
  Smart merge (new): N files — <list of smart_merge files not in target>
  Smart merge (both): N files — <list of smart_merge files in both>
  Merge (existing copy_if_absent): N files — <list>
  Skipped:           N files (template-specific)

Proceed?

继续前等待用户确认。

---

阶段 2 — 复制

对于 copy_if_absent 中的每个条目：

• 目录（以 / 结尾的条目）：使用 mkdir -p 创建目标目录，然后递归复制所有文件。跳过已存在的单个文件。
• 文件：如果目标中不存在该文件，则原样复制。如果文件已存在，则应用阶段 3 中的相同智能合并逻辑（该文件已与模板版本不同——保留目标意图，同时添加模板新增内容）。

还要确保以下目录存在，即使它们为空：

• ai-workspace/plans/
• ai-workspace/decisions/

---

阶段 3 — 智能合并

对于 smart_merge 中的每个文件，读取模板版本和目标版本（如果存在）。如果目标文件不存在，则直接复制模板版本。如果两者都存在，则按照以下规则合并。

AGENTS.md — 语义合并

• 理解意图： 完整阅读两个版本。识别每个章节的用途。
• 保留目标内容： 完整保留 ## Stack、## Commands、## Architecture、## Gotchas 这些章节
• 模板中缺少时添加： ## Agent Roles & Dispatch、## Protected Files、## Conventions、## Workflow Reference、## Context Loading Rules
• 处理重复章节： 如果两者包含相同标题的章节，结构/约定类章节优先采用模板版本，项目特定章节优先采用目标版本
• 更新： 标题行——将项目名称替换为目标仓库的目录名称
• 保留： 目标中存在但模板没有的任何自定义章节
• 连贯性检查： 合并后阅读结果，确认各章节之间没有矛盾

tsconfig.json — 深度合并

• 以模板为基础： 使用模板版本作为基础
• 深度合并 compilerOptions： 将目标的 compilerOptions 覆盖到模板版本上。发生冲突时以目标为准。
• 保留目标内容： 保留 include、exclude、references 及其他任何顶层键
• 缺少时注入： 模板中的以下严格选项：strict、noUncheckedIndexedAccess、verbatimModuleSyntax、exactOptionalPropertyTypes、noImplicitOverride、noFallthroughCasesInSwitch
• 指出冲突： 如果模板和目标对同一选项存在相互矛盾的值（例如，strict: true 与 strict: false），向用户展示冲突并请其决定
• 连贯性测试： 合并后确认 compilerOptions 中没有相互矛盾的标志（例如，module: "commonjs" 与 verbatimModuleSyntax: true）

.claude/settings.json

• **保留目标中的内容：**所有现有的 permissions.allow 和 permissions.deny 条目、defaultMode
• 并集合并：permissions.deny 数组——添加模板中尚未存在的条目（去重）
• **合并 hooks：**对于每个 hook 事件（PreToolUse、PostToolUse 等），保留目标中的所有 hooks。仅当目标中不存在具有相同 matcher 的 hook 时，才添加模板中的 hook
• **保留：**目标中的其他所有键（disabledMcpjsonServers、enabledPlugins 等）

package.json

• 保留目标中的内容：name、version、description、main、type、dependencies、repository、license、author——除 scripts 和 devDependencies 外的所有内容
• **合并 scripts：**添加模板中存在但目标中不存在的 scripts。发生冲突时以目标为准。
• **合并 devDependencies：**添加模板中存在但目标的 devDependencies 中不存在的包（commitlint 包、lefthook、@biomejs/biome、typescript）。绝不删除或降级现有依赖。
• 若缺失则添加：engines、packageManager

biome.json

• **保留目标中的内容：**所有现有规则、files 配置、formatter 配置
• **若缺失则添加：**模板中存在但目标中不存在的 linter 规则
• 绝不删除目标中已有的任何规则

.gitignore

• **并集合并：**合并两个文件中的所有唯一行并去重
• **保留：**两个文件中的分节注释（以 # 开头的行）和空行分组
• **顺序：**先放置目标中的行，然后在末尾的 # ai-env template 注释下追加模板中的新增行

skills-lock.json — 并集合并

• **并集合并 .skills 对象：**合并模板和目标中的所有技能条目。每个条目包含 source（git URL 或本地路径，取决于 sourceType）、sourceType（"git" 或 "local"）和 computedHash（SHA-256 完整性哈希）。
• **冲突时以模板为准：**如果两边存在同名技能，则使用模板中的条目（source、sourceType、computedHash 均取自模板）
• **绝不删除：**始终保留目标中模板未包含的技能——项目可能有自定义技能
• **顶层 version：**保留任一方中较大的整数（这是锁文件的架构版本，而非技能版本——单个技能没有版本字段）
• **合并后：**写入合并后的锁文件后，指示：“运行 npx skills install -a claude-code -a codex，为两个 Agent 安装所有新添加的技能”

合并逻辑示例：

Template:                                Target:
{ "version": 1, "skills": {             { "version": 1, "skills": {
    "validate": {                            "validate": {
      "source": "[email protected]",       "source": "[email protected]",
      "sourceType": "git",                     "sourceType": "git",
      "computedHash": "abc..."                 "computedHash": "abc..."
    },                                       },
    "reflect": {                             "custom-lint": {
      "source": "[email protected]",       "source": "local",
      "sourceType": "git",                     "sourceType": "local",
      "computedHash": "def..."                 "computedHash": "xyz..."
    }                                        }
}}                                       }}

                    ↓ merged result:
{ "version": 1, "skills": {
    "validate":    { ... },  ← kept (same in both)
    "custom-lint": { ... },  ← preserved (target-only)
    "reflect":     { ... }   ← added from template
}}

目录：.claude/agents/、.claude/rules/、.claude/skills/

• 递归处理每个目录
• **新文件：**从模板复制
• **现有文件：**进行语义合并——理解两个版本的意图，保留目标中的自定义内容，并添加模板中缺失的部分

阶段 4 — 应用后处理

1. 创建 ai-workspace/.template-version，内容为：

   version: <manifest version>
   applied: <ISO 8601 timestamp>
   source: <template source path>
   

2. **依赖检查：**如果向 package.json 添加了 devDependencies，则检测包管理器（pnpm-lock.yaml → pnpm、yarn.lock → yarn、package-lock.json → npm），并询问：“新增了 devDependencies。运行 <pm> install 吗？”

3. **工作流警告：**如果复制了任何 .github/workflows/ 文件，请检查是否存在此密钥：

   if command -v gh &> /dev/null && gh secret list 2>/dev/null | grep -q "CLAUDE_CODE_OAUTH_TOKEN"; then
     # Secret exists — no warning needed
   else
     warn: "GitHub workflows added. You'll need to set CLAUDE_CODE_OAUTH_TOKEN as a repo secret (Settings → Secrets → Actions)."
   fi
   

4. **钩子警告：**如果 .claude/settings.json 引用了位于 ~/.claude/hooks/ 的钩子脚本，请检查每个脚本是否存在于磁盘上。对缺失的脚本发出警告。

5. **点文件同步：**询问用户是否要安装用户级配置：

   ai-env includes user-level configs for Claude and Codex (hooks, skills, profiles).
   Install them? Run: $AI_ENV_ROOT/dotfiles/sync.sh push
   (where $AI_ENV_ROOT is the template source directory)
   This copies dotfiles/claude/ → ~/.claude/ and dotfiles/codex/ → ~/.codex/
   

   如果用户同意，请从模板源目录（而非 cwd）运行 "$TEMPLATE_SOURCE/dotfiles/sync.sh" push。

6. 通过 TodoWrite 自动添加设置后待办事项：

   • “更新 AGENTS.md — 填写项目的 Stack、Commands、Architecture 和 Gotchas”
   • “更新 .claude/agents/ 描述，使其引用你的项目”
   • “运行 $TEMPLATE_SOURCE/dotfiles/sync.sh push，部署用户级配置（如果上面尚未完成）”
   • “检查 .claude/settings.json 钩子，并根据你的环境调整路径”

7. **摘要：**打印所有已创建、合并和跳过的文件列表。

---

阶段 5 — 上下文迁移（提示式，非自动）

此阶段会扫描目标仓库中的所有现有 AI 上下文、记忆和配置，并引导用户交互式完成迁移。绝不自动删除或覆盖上下文——每项操作都需要用户明确确认。

发现扫描

检查以下所有位置。如果均无内容，则完全跳过此阶段，并显示消息：“未发现现有 AI 上下文 — 跳过迁移。”

项目范围（仓库内）：

• ai-workspace/MEMORY.md — 项目记忆（检查是否包含种子模板以外的内容）
• ai-workspace/plans/ — 现有计划（尤其是已完成的 .done.md 计划）
• ai-workspace/decisions/ — 现有 ADR
• ai-workspace/scratchpad.md — 工作笔记
• ai-workspace/workflow.md — 自定义工作流（可能与模板不同）
• .claude/skills/ — 预先存在的技能（不由本次模板运行创建）
• .claude/agents/ — 预先存在的 Agent 定义
• .claude/rules/ — 预先存在的规则
• .claude/settings.json — 项目权限、钩子、拒绝规则
• .claude/settings.local.json — 仅本地覆盖项（未纳入版本控制）
• .codex/config.toml — 带配置档案的 Codex 配置
• CLAUDE.md — 现有 Claude 指令文件
• AGENTS.md — 现有通用指令文件
• GEMINI.md — Gemini 专用指令（如果存在）
• .cursorrules 或 .cursor/rules/ — Cursor 专用规则（如果存在）
• .claudeignore / .codexignore — 现有上下文排除规则
• .github/workflows/claude.yml 或 claude-code-review.yml — 现有 CI 工作流

用户范围（仓库外——只读，告知用户）：

• ~/.claude/projects/<path-encoded-cwd>/memory/ — Claude Code 为此项目自动生成的记忆
  • 路径编码：将 / 替换为 -，例如 -Users-patrickcamacho-projects-myapp
  • 每个 .md 文件都包含带有 name、description、type（user/feedback/project/reference）的 frontmatter
• ~/.claude/projects/<path-encoded-cwd>/MEMORY.md — 此项目的自动记忆索引
• ~/.claude/CLAUDE.md — 用户的全局指令（可能引用项目模式）
• ~/.claude/hooks/ — 项目钩子可能重复使用的全局钩子脚本
• ~/.claude/agents/ — 项目 Agent 可能会覆盖的全局 Agent 定义
• ~/.claude/commands/ — 全局斜杠命令（catchup、reflect 等）
• ~/.claude/plugins/ — 已安装的插件（检查 settings 中的 enabledPlugins）

呈现发现结果

向用户显示分类摘要：

Context Migration — Found <N> items across <M> locations:

  Memory:
    - ai-workspace/MEMORY.md (42 lines, last updated 2026-03-15)
    - ~/.claude/projects/.../memory/ (6 files: 2 user, 2 feedback, 2 project)

  Plans & Decisions:
    - ai-workspace/plans/001-feature.done.md (completed, immutable)
    - ai-workspace/decisions/001-architecture.md

  Skills:
    - .claude/skills/deploy/SKILL.md (custom, not in template)
    - .claude/skills/validate/SKILL.md (CONFLICTS with template version)

  Agents & Rules:
    - .claude/agents/implementer.md (customized from template)
    - .claude/rules/feature-branches.md (matches template)

  Configuration:
    - .claude/settings.json (12 allow rules, 3 hooks, 2 deny rules)
    - .codex/config.toml (custom profiles: review, deploy)

  Instruction Files:
    - CLAUDE.md (project-specific, references @AGENTS.md)
    - AGENTS.md (customized — 5 sections differ from template)

  CI Workflows:
    - .github/workflows/claude.yml (existing, may need permission updates)

  User-scoped (informational):
    - ~/.claude/projects/.../memory/feedback_testing.md
    - ~/.claude/hooks/post-edit-format.sh (also referenced in project settings)

等待用户审核后，再继续迁移步骤。

1. 记忆 — ai-workspace/MEMORY.md

如果模板和目标中都存在包含实际内容的 ai-workspace/MEMORY.md：

合并策略（按语义合并，而非逐行合并）：

1. 完整阅读这两个文件。模板 MEMORY.md 具有以下种子结构：

   # Project Memory
   > Living document updated by /reflect after each task. 200-line limit.
   > Last updated: —
   
   ## Key Decisions
   ## Implementation Status
   ## Gotchas
   

2. 保留目标 MEMORY.md 中的全部内容——这些是积累的项目知识
3. 如果目标缺少模板种子中的部分章节（Key Decisions、Implementation Status、Gotchas），则在末尾添加这些空章节
4. 如果目标包含模板中没有的其他章节，则保留这些章节
5. 如果缺少模板中的 > Living document... 行，则更新文件头部注释，将该行添加进去
6. 展示合并后的结果，并请用户确认

**如果只有目标有内容：**保留目标内容，并添加缺少的模板章节。
**如果只有模板有内容：**复制模板种子（从头开始）。

2. 记忆 — Claude Code 自动记忆（~/.claude/projects/）

这些记忆属于用户级，由 Claude Code 内置的记忆系统管理。它们位于仓库之外，不会自动迁移。请改为告知用户：

• 列出每个记忆文件的 name、type 和 frontmatter 中的 description
• 说明：“这些是 Claude Code 按项目存储在 ~/.claude/projects/.../memory/ 的记忆。它们会在不同会话间保留，并影响 Claude 在此项目中的行为。”
• 询问：“其中有过时或不正确的内容吗？我可以标记出来供你检查，但不会在应用模板时修改它们。”
• 如果任何 project 或 reference 类型的记忆包含应放入 ai-workspace/MEMORY.md 的信息（以便其他 Agent 查看），建议用户手动迁移这些内容

3. 计划和决策

• 已完成的计划（*.done.md）：始终保留——这些是不可变的记录。告知用户这些文件存在。
• 进行中的计划（没有 .done.md 后缀）：询问是否仍在进行，或应将其标记为已完成。
• ADR：始终保留——提交后不可变。检查是否有 ADR 引用了模板会更改的模式（如有则提醒用户）。
• 模板（TEMPLATE.md）：如果版本不同，则替换为模板版本（这些是脚手架，不是内容）。
• scratchpad.md：如果文件非空，询问用户是要保留、归档还是重置。
• workflow.md：如果目标中有与模板不同的自定义工作流，展示两者并询问用户要保留哪一个（或合并）。

4. 技能

对于 .claude/skills/ 中的每个技能目录：

• 模板中没有（自定义技能）：保持原样。告知用户该技能已保留。
• 与模板技能同名（例如，两者都包含 validate/SKILL.md）：
  • 对比两个版本
  • 向用户展示差异
  • 可选方案：保留目标版本、替换为模板版本，或合并（由用户检查合并后的输出）
• 模板中有而目标中没有的新技能：这些技能已在第 2 阶段复制。只需告知用户。

5. Agent、规则和命令

对于 .claude/agents/ 和 .claude/rules/ 中的每个文件：

• **两者中都存在同一文件：**对比文件。如果目标版本有自定义内容（模型更改、额外指令、项目专属背景信息），则展示差异。默认情况下：Agent 保留目标版本（它们通常经过定制），规则保留模板版本（它们的结构性更强）。
• **模板新增的文件：**已在第 2 阶段复制。告知用户。
• **仅目标中存在的文件（自定义）：**保留。告知用户。

检查全局 Agent 与项目 Agent 之间是否存在覆盖：

• 如果 ~/.claude/agents/architect.md 和 .claude/agents/architect.md 都存在，请指出项目版本优先。

6. 设置和权限

对于 .claude/settings.json：

• 此文件已在第 3 阶段完成智能合并。总结新增或更改的内容。
• 请特别指出：
  • 钩子： 列出全局（~/.claude/settings.json）和项目中都有哪些钩子。根据钩子放置规则：全局钩子 = 个人工作流，项目钩子 = 代码库约定。如果同一个钩子同时出现在两处，请提醒用户（重复配置会导致昂贵的钩子不必要地运行两次）。
  • 拒绝规则： 模板新增的拒绝模式
  • 允许规则： 新增的允许模式（用户应审核这些规则）
  • 插件： 如果存在 enabledPlugins 或 disabledMcpjsonServers，请列出

对于 .claude/settings.local.json：

• 绝不修改。告知用户该文件存在及其内容。

对于 .codex/config.toml：

• 如果目标中有自定义配置档案，请保留。合并所有不冲突的新模板配置档案。

7. 指令文件（CLAUDE.md、AGENTS.md、GEMINI.md、.cursorrules）

• AGENTS.md： 已在第 3 阶段完成合并。总结新增或保留了哪些章节。
• CLAUDE.md： 如果目标中有自定义的 CLAUDE.md，且内容不只是 @AGENTS.md：
  • 阅读该文件。区分项目专属指令与样板内容。
  • 保留项目专属内容。补充缺失的模板样板章节。
• GEMINI.md： 如果存在，请告知用户。模板不提供此文件——这是用户的自定义文件。保留该文件。
• .cursorrules： 如果存在，请告知用户 AGENTS.md 是首选的通用格式。询问是否应将 .cursorrules 内容合并到 AGENTS.md，还是单独保留。

8. CI 工作流

如果应用模板之前就存在 .github/workflows/claude.yml 或 claude-code-review.yml：

• 与模板版本进行差异比较
• 指出权限差异（contents: read 与 write、缺少 allowed_tools）
• 如果目标工作流的权限较弱，请提供升级路径

9. 上下文排除项（.claudeignore、.codexignore）

• .claudeignore：与 .gitignore 分开处理。检查目标中是否存在该文件。如果存在，则合并两者的规则（采用与 .gitignore 相同的策略）。如果不存在，则复制模板版本。
• .codexignore：如果存在，请保留。模板不提供此文件。

总结提示

展示所有发现后，询问：

Ready to apply these migration decisions? (y/n)

You can also:
  - "skip" to skip migration entirely (all files from Phases 2-4 are already applied)
  - "details <item>" to see the full diff for any item above

核心原则： 此阶段仅提供信息和建议。每项决策都由用户最终决定。说明现有内容、解释模板的预期，并提出建议，但未经确认绝不采取行动。

---

重新应用

在已包含 ai-workspace/.template-version 的仓库中运行时：

• 如果 copy_if_absent 文件已存在，则对其进行智能合并（加入模板新增内容，同时保留自定义内容）
• 始终重新合并 smart_merge 文件（模板更新通过此方式传递）
• 如果用户传入 --force，则完全覆盖 copy_if_absent 文件，而不是合并