sync-template

同步模板

将基于 blogic-template-ts 生成的下游项目与上游模板的最新状态同步。

以 blogic-cz/blogic-template-ts 为事实来源。

如果本地存在，优先使用此路径：

opensrc/repos/github.com/blogic-cz/blogic-template-ts/

在命令中将该路径引用为 $TPL。

先决条件

• 如果可用，请使用已通过身份验证的 gh CLI。
• 如果可用，请加载 debugging-with-opensrc 技能；否则直接运行等效的 opensrc / git 命令。
• 如果可用，请使用 agent-tools（gh-tool release list/view）；否则使用原生 gh release list/view。
• 如果可用，请使用 opensrc 克隆模板；否则将 https://github.com/blogic-cz/blogic-template-ts 克隆到临时本地目录，并将该路径用作 $TPL。

阶段 0：发现——模板有哪些变化

步骤 0：在本地准备模板源

进行差异比较前，先在本地准备模板仓库：

bun run opensrc:use blogic-cz/blogic-template-ts
ls opensrc/repos/github.com/blogic-cz/blogic-template-ts/

如果 opensrc 不可用，请使用 git clone 克隆，并将 $TPL 设置为该克隆路径。

步骤 1：检测项目当前的模板版本

检测当前模板版本标记：

• package.json（templateVersion、template-version、synced-from）
• .template-version
• 用于同步提交的 Git 历史
• CHANGELOG.md 中的同步条目

如果没有基准版本，请先向用户询问基准版本，再继续。

步骤 2：列出基准版本之后的上游变更

使用发行版、提交和 PR 元数据列出变更：

gh-tool release list --repo blogic-cz/blogic-template-ts
gh-tool release view <tag> --repo blogic-cz/blogic-template-ts
gh pr list --repo blogic-cz/blogic-template-ts --state merged --search "merged:>YYYY-MM-DD" --limit 50

如果 gh-tool 不可用，请将 gh-tool 命令替换为 gh release ... 命令。

步骤 3：对变更分类，以确定采用策略

将每项变更归入以下类别之一：

类别	描述	操作
基础设施	CI/CD、Docker、Helm、配置、工具	直接采用（替换名称）
依赖项	软件包版本升级、新依赖项	委托给 update-packages 技能
模式	代码模式、约定、lint 规则	适配后采用
功能	新应用功能、路由、服务	评估是否适用
修复	共享代码中的错误修复	如果项目中存在该错误，则采用

输出汇总表：

| # | Category | Change | Template Files | Effort | Priority |
|---|----------|--------|---------------|--------|----------|

---

阶段 1：优先更新软件包（必须执行）

在应用模板文件同步之前，先对齐软件包版本。

步骤 1：比较项目与模板的软件包版本

读取两棵目录树中的软件包清单，并构建版本差异表。

构建比较表：

| Package | Project Version | Template Version | Gap |
|---------|----------------|-----------------|-----|

步骤 2：执行软件包更新

如果软件包版本落后，优先使用 update-packages 技能。如果该技能不可用，请按照相同约束执行等效的手动更新。

按以下顺序执行：

1. 创建分支：chore/sync-template-packages-$(date +%y%m%d-%H%M)
2. 仅将已使用的软件包更新到模板版本或更高版本。
3. 在模板文件同步提交之前，单独提交软件包更新。
4. 继续之前，使用项目检查进行验证。

遵循以下规则：

• 必须先提交软件包更新，再进行任何模板变更
• 保持软件包组之间的协调（tanstack、trpc、effect、drizzle）
• 不要添加项目未使用的软件包——仅更新现有软件包

---

阶段 2：深度扫描与差异比较

逐个文件比较项目与模板，找出所有差异。

步骤 1：确定要采用的基础设施文件

加载 references/template-files.md，获取分类后的文件列表。

对于每个基础设施文件：

1. 检查项目中是否存在该文件
2. 如果存在，将其与模板版本进行差异比较
3. 如果不存在，将其标记为“项目中缺失”

git diff --no-index $TPL/<file> <file>

步骤 2：构建名称替换矩阵

根据 references/substitution-rules.md 构建替换矩阵。

第 3 步：识别并保留项目特有的差异

标记有意保留的业务逻辑差异：

• apps/web-app/src/routes/ — 项目特有的路由
• packages/services/src/ — 项目特有的服务
• packages/db/src/schema/ — 项目特有的架构（超出模板默认内容的部分）
• 特定环境的配置（Helm 值、CI 密钥）

遵循以下规则：

• 绝不使用模板默认内容覆盖项目特有的业务逻辑
• 应完整采用模板基础设施文件（lint、工具链、CI）
• 对同时包含基础设施变更和项目特有内容的文件，选择性合并

---

第 3 阶段：分类与规划

在 .sisyphus/plans/ 中生成分阶段实施计划。

第 1 步：创建计划文件

mkdir -p .sisyphus/plans

名称：.sisyphus/plans/YYMMDDHHMM-sync-template-vX.Y.Z.md

第 2 步：应用规范计划格式

加载并应用 references/plan-template.md。

第 3 步：组织波次

模板同步的标准波次模式：

Wave 0 (Sequential — foundation):
└── Package updates (if not done in Phase 1)

Wave 1 (Parallel — infrastructure):
├── Skills & tooling updates
├── Lint & formatter config
├── CI/CD pipeline updates
├── Docker & Helm updates
└── Config file updates (tsconfig, vitest, etc.)

Wave 2 (After Wave 1 — code changes):
├── Fix lint violations from new rules
├── Apply code pattern updates
└── Update docs (AGENTS.md, README)

Wave 3 (After Wave 2 — cleanup):
└── Final cleanup + verification

Wave FINAL (After ALL — verification):
├── Plan compliance audit
├── Code quality review
└── Scope fidelity check

第 4 步：向用户呈现计划

呈现摘要，并等待用户明确批准后再执行：

## Sync Template v<old> → v<new>

**Changes**: N commits, M PRs, K releases
**Waves**: 4 (+ verification)
**Tasks**: N total
**Estimated effort**: [Small/Medium/Large]

Approve to start execution?

---

第 4 阶段：执行

按波次执行计划。

有子 Agent 可用时，优先委派任务。

子 Agent 不可用时的备用方案：在主 Agent 中按顺序执行任务，保持相同的验收标准，并保留计划中的提交分组。

每项任务的执行流程

对于计划中的每项任务：

1. 将 TODO 标记为 in_progress
2. 执行任务（有可用子 Agent 时委派，否则直接执行）
3. 验证验收标准
4. 运行 QA 场景
5. 将 TODO 标记为 completed
6. 按计划要求提交

委派提示词模板

使用 references/plan-template.md 中的委派提示词。

每个波次结束后

bun run check
bun run test

解决所有失败后再进入下一波次。

---

第 5 阶段：验证与标记

运行 references/verification-recipes.md 中的验证流程。

应用 references/substitution-rules.md 中的替换策略。

---

防护规则

• 绝不覆盖项目特有的业务逻辑（路由、服务、超出默认内容的架构）
• 绝不在同步后的项目文件中留下 @blogic-template/ 或 blogic-template-ts 字符串，但 references/substitution-rules.md 中批准的例外除外
• 务必先通过 bun run opensrc:use blogic-cz/blogic-template-ts 克隆模板
• 务必对从模板复制的每个文件应用名称替换矩阵
• 务必先更新包，再应用基础设施变更
• 务必在每个波次后运行 bun run check && bun run test
• 务必保留项目特有的配置（Sentry 项目、Helm 命名空间、CI 密钥）
• 不要添加项目不需要的纯模板依赖项
• 不要应用项目尚未选择启用的模板功能
• 不要使用硬编码的绝对路径——始终使用相对路径 opensrc/repos/github.com/blogic-cz/blogic-template-ts/

完成标准

• bun run check 通过（0 个错误）
• bun run test 通过
• 同步后的项目文件中没有 @blogic-template/ 或 blogic-template-ts 字符串，但 references/substitution-rules.md 中批准的例外除外
• .template-version 文件已更新为新版本
• 所有计划任务均已标记为已完成
• 计划文件存在于 .sisyphus/plans/ 中