zcf 2.10.2 → 2.11.0

package/templates/zh-CN/workflow/bmad/commands/bmad-init.md

@@ -12,86 +12,89 @@
 ## 实现
 
 ```javascript
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
+const { execSync } = require('node:child_process')
+const fs = require('node:fs')
+const path = require('node:path')
 
 async function initBmad() {
   // 检查是否已安装并获取版本
-  const manifestPath = path.join(process.cwd(), '.bmad-core', 'install-manifest.yaml');
-  let needsInstall = true;
-  let currentVersion = null;
-  
+  const manifestPath = path.join(process.cwd(), '.bmad-core', 'install-manifest.yaml')
+  let needsInstall = true
+  let currentVersion = null
+
   if (fs.existsSync(manifestPath)) {
     try {
       // 简单版本检查 - 只检查文件是否存在
       // 完整的 YAML 解析需要 js-yaml 包
-      const manifestContent = fs.readFileSync(manifestPath, 'utf8');
-      const versionMatch = manifestContent.match(/version:\s*(.+)/);
+      const manifestContent = fs.readFileSync(manifestPath, 'utf8')
+      const versionMatch = manifestContent.match(/version:\s*(.+)/)
       if (versionMatch) {
-        currentVersion = versionMatch[1].trim();
+        currentVersion = versionMatch[1].trim()
       }
-      
+
       // 从 npm 获取最新版本
-      const latestVersion = execSync('npm view bmad-method version', { encoding: 'utf8' }).trim();
-      
+      const latestVersion = execSync('npm view bmad-method version', { encoding: 'utf8' }).trim()
+
       if (currentVersion === latestVersion) {
-        console.log(`✅ BMad-Method已是最新版本 (v${currentVersion})`);
-        console.log('您可以使用 BMad 命令开始工作流');
-        needsInstall = false;
-      } else {
-        console.log(`🔄 BMad-Method有更新可用：v${currentVersion} → v${latestVersion}`);
+        console.log(`✅ BMad-Method已是最新版本 (v${currentVersion})`)
+        console.log('您可以使用 BMad 命令开始工作流')
+        needsInstall = false
       }
-    } catch (error) {
-      console.log('⚠️  无法验证 BMad 版本，将重新安装');
+      else {
+        console.log(`🔄 BMad-Method有更新可用：v${currentVersion} → v${latestVersion}`)
+      }
+    }
+    catch (error) {
+      console.log('⚠️  无法验证 BMad 版本，将重新安装')
     }
   }
-  
+
   if (needsInstall === false) {
-    return;
+    return
   }
-  
+
   // 安装 BMad
-  console.log('🚀 正在安装 BMad-Method...');
+  console.log('🚀 正在安装 BMad-Method...')
   try {
     execSync('echo -e "1\\n" | npx bmad-method@latest install -f -d . -i claude-code', {
       stdio: 'inherit',
       cwd: process.cwd(),
       shell: true
-    });
-    
-    console.log('✅ BMad-Method已成功安装！');
-    console.log('');
-    console.log('═══════════════════════════════════════════════════════════════');
-    console.log('📌 重要提示：请重启 Claude Code 以加载 BMad 扩展');
-    console.log('═══════════════════════════════════════════════════════════════');
-    console.log('');
-    console.log('📂 安装详情：');
-    console.log('   • 所有代理和任务命令都已安装在：');
-    console.log('     .claude/commands/BMad/ 目录中');
-    console.log('');
-    console.log('🔧 Git 配置建议（可选）：');
-    console.log('   如果您不希望将 BMad 工作流文件提交到 Git，请将以下内容添加到 .gitignore：');
-    console.log('     • .bmad-core');
-    console.log('     • .claude/commands/BMad');
-    console.log('     • docs/');
-    console.log('');
-    console.log('🚀 快速开始：');
-    console.log('   1. 重启 Claude Code');
-    console.log('   2. 首次使用推荐运行：');
-    console.log('      /BMad:agents:bmad-orchestrator *help');
-    console.log('      这将启动 BMad 工作流引导系统');
-    console.log('');
-    console.log('💡 提示：BMad Orchestrator 将帮助您选择合适的工作流程，');
-    console.log('       并引导您完成整个开发过程。');
-  } catch (error) {
-    console.error('❌ 安装失败：', error.message);
-    console.log('请手动运行：npx bmad-method@latest install -f -d . -i claude-code');
+    })
+
+    console.log('✅ BMad-Method已成功安装！')
+    console.log('')
+    console.log('═══════════════════════════════════════════════════════════════')
+    console.log('📌 重要提示：请重启 Claude Code 以加载 BMad 扩展')
+    console.log('═══════════════════════════════════════════════════════════════')
+    console.log('')
+    console.log('📂 安装详情：')
+    console.log('   • 所有代理和任务命令都已安装在：')
+    console.log('     .claude/commands/BMad/ 目录中')
+    console.log('')
+    console.log('🔧 Git 配置建议（可选）：')
+    console.log('   如果您不希望将 BMad 工作流文件提交到 Git，请将以下内容添加到 .gitignore：')
+    console.log('     • .bmad-core')
+    console.log('     • .claude/commands/BMad')
+    console.log('     • docs/')
+    console.log('')
+    console.log('🚀 快速开始：')
+    console.log('   1. 重启 Claude Code')
+    console.log('   2. 首次使用推荐运行：')
+    console.log('      /BMad:agents:bmad-orchestrator *help')
+    console.log('      这将启动 BMad 工作流引导系统')
+    console.log('')
+    console.log('💡 提示：BMad Orchestrator 将帮助您选择合适的工作流程，')
+    console.log('       并引导您完成整个开发过程。')
+  }
+  catch (error) {
+    console.error('❌ 安装失败：', error.message)
+    console.log('请手动运行：npx bmad-method@latest install -f -d . -i claude-code')
   }
 }
 
 // 执行初始化
-initBmad();
+initBmad()
 ```
 
 ## 用法
@@ -106,4 +109,4 @@ initBmad();
 
 1. 在您的项目中安装 BMad-Method 框架
 2. 设置所有必要的配置
-3. 提供如何开始使用 BMad 工作流的指导
+3. 提供如何开始使用 BMad 工作流的指导

package/templates/zh-CN/workflow/common/agents/get-current-datetime.md

@@ -0,0 +1,29 @@
+---
+name: get-current-datetime
+description: 执行日期命令并仅返回原始输出。不添加格式、标题、说明或并行代理。
+tools: Bash, Read, Write
+color: cyan
+---
+
+执行 `date` 命令并仅返回原始输出。
+
+```bash
+date
+```
+
+不添加任何文本、标题、格式或说明。
+不添加 markdown 格式或代码块。
+不添加"当前日期和时间是："或类似短语。
+不使用并行代理。
+
+只返回原始 bash 命令输出，完全按其显示的样子。
+
+示例响应：`Mon 28 Jul 2025 23:59:42 CST`
+
+如果需要特定格式选项：
+
+- 文件名格式：添加 `+"%Y-%m-%d_%H%M%S"`
+- 可读格式：添加 `+"%Y-%m-%d %H:%M:%S %Z"`
+- ISO 格式：添加 `+"%Y-%m-%dT%H:%M:%S%z"`
+
+使用 get-current-datetime 代理来获取准确的时间戳，而不是手动编写时间信息。

package/templates/zh-CN/workflow/common/agents/init-architect.md

@@ -0,0 +1,114 @@
+---
+name: init-architect
+description: 自适应初始化：根级简明 + 模块级详尽；分阶段遍历并回报覆盖率
+tools: Read, Write, Glob, Grep
+color: orange
+---
+
+# 初始化架构师（自适应版）
+
+> 不暴露参数；内部自适应三档：快速摘要 / 模块扫描 / 深度补捞。保证每次运行可增量更新、可续跑，并输出覆盖率报告与下一步建议。
+
+## 一、通用约束
+
+- 不修改源代码；仅生成/更新文档与 `.claude/index.json`。
+- **忽略规则获取策略**：
+  1. 优先读取项目根目录的 `.gitignore` 文件
+  2. 如果 `.gitignore` 不存在，则使用以下默认忽略规则：`node_modules/**,.git/**,.github/**,dist/**,build/**,.next/**,__pycache__/**,*.lock,*.log,*.bin,*.pdf,*.png,*.jpg,*.jpeg,*.gif,*.mp4,*.zip,*.tar,*.gz`
+  3. 将 `.gitignore` 中的忽略模式与默认规则合并使用
+- 对大文件/二进制只记录路径，不读内容。
+
+## 二、分阶段策略（自动选择强度）
+
+1. **阶段 A：全仓清点（轻量）**
+   - 以多次 `Glob` 分批获取文件清单（避免单次超限），做：
+     - 文件计数、语言占比、目录拓扑、模块候选发现（package.json、pyproject.toml、go.mod、Cargo.toml、apps/_、packages/_、services/_、cmd/_ 等）。
+   - 生成 `模块候选列表`，为每个候选模块标注：语言、入口文件猜测、测试目录是否存在、配置文件是否存在。
+2. **阶段 B：模块优先扫描（中等）**
+   - 对每个模块，按以下顺序尝试读取（分批、分页）：
+     - 入口与启动：`main.ts`/`index.ts`/`cmd/*/main.go`/`app.py`/`src/main.rs` 等
+     - 对外接口：路由、控制器、API 定义、proto/openapi
+     - 依赖与脚本：`package.json scripts`、`pyproject.toml`、`go.mod`、`Cargo.toml`、配置目录
+     - 数据层：`schema.sql`、`prisma/schema.prisma`、ORM 模型、迁移目录
+     - 测试：`tests/**`、`__tests__/**`、`*_test.go`、`*.spec.ts` 等
+     - 质量工具：`eslint/ruff/golangci` 等配置
+   - 形成"模块快照"，只抽取高信号片段与路径，不粘贴大段代码。
+3. **阶段 C：深度补捞（按需触发）**
+   - 触发条件（满足其一即可）：
+     - 仓库整体较小（文件数较少）或单模块文件数较少；
+     - 阶段 B 后仍无法判断关键接口/数据模型/测试策略；
+     - 根或模块 `CLAUDE.md` 缺信息项。
+   - 动作：对目标目录**追加分页读取**，补齐缺项。
+
+> 注：如果分页/次数达到工具或时间上限，必须**提前写出部分结果**并在摘要中说明"到此为止的原因"和"下一步建议扫描的目录列表"。
+
+## 三、产物与增量更新
+
+1.  **写入根级 `CLAUDE.md`**
+    - 如果已存在，则在顶部插入/更新 `变更记录 (Changelog)`。
+    - 根级结构（精简而全局）：
+      - 项目愿景
+      - 架构总览
+      - **✨ 新增：模块结构图（Mermaid）**
+        - 在"模块索引"表格**上方**，根据识别出的模块路径，生成一个 Mermaid `graph TD` 树形图。
+        - 每个节点应可点击，并链接到对应模块的 `CLAUDE.md` 文件。
+        - 示例语法：
+
+          ```mermaid
+          graph TD
+              A["(根) 我的项目"] --> B["packages"];
+              B --> C["auth"];
+              B --> D["ui-library"];
+              A --> E["services"];
+              E --> F["audit-log"];
+
+              click C "./packages/auth/CLAUDE.md" "查看 auth 模块文档"
+              click D "./packages/ui-library/CLAUDE.md" "查看 ui-library 模块文档"
+              click F "./services/audit-log/CLAUDE.md" "查看 audit-log 模块文档"
+          ```
+
+      - 模块索引（表格形式）
+      - 运行与开发
+      - 测试策略
+      - 编码规范
+      - AI 使用指引
+      - 变更记录 (Changelog)
+
+2.  **写入模块级 `CLAUDE.md`**
+    - 放在每个模块目录下，结构建议：
+      - **✨ 新增：相对路径面包屑**
+        - 在每个模块 `CLAUDE.md` 的**最顶部**，插入一行相对路径面包屑，链接到各级父目录及根 `CLAUDE.md`。
+        - 示例（位于 `packages/auth/CLAUDE.md`）：
+          `[根目录](../../CLAUDE.md) > [packages](../) > **auth**`
+      - 模块职责
+      - 入口与启动
+      - 对外接口
+      - 关键依赖与配置
+      - 数据模型
+      - 测试与质量
+      - 常见问题 (FAQ)
+      - 相关文件清单
+      - 变更记录 (Changelog)
+3.  **`.claude/index.json`**
+    - 记录：当前时间戳（通过参数提供）、根/模块列表、每个模块的入口/接口/测试/重要路径、**扫描覆盖率**、忽略统计、是否因上限被截断（`truncated: true`）。
+
+## 四、覆盖率与可续跑
+
+- 每次运行都计算并打印：
+  - 估算总文件数、已扫描文件数、覆盖百分比；
+  - 每个模块的覆盖摘要与缺口（缺接口、缺测试、缺数据模型等）；
+  - 被忽略/跳过的 Top 目录与原因（忽略规则/大文件/时间或调用上限）。
+- 将"缺口清单"写入 `index.json`，下次运行时优先补齐缺口（**断点续扫**）。
+
+## 五、结果摘要（打印到主对话）
+
+- 根/模块 `CLAUDE.md` 新建或更新状态；
+- 模块列表（路径+一句话职责）；
+- 覆盖率与主要缺口；
+- 若未读全：说明"为何到此为止"，并列出**推荐的下一步**（例如"建议优先补扫：packages/auth/src/controllers、services/audit/migrations"）。
+
+## 六、时间格式与使用
+
+- 路径使用相对路径；
+- 时间信息：使用通过命令参数提供的时间戳，并在 `index.json` 中写入 ISO-8601 格式。
+- 不要手动编写时间信息，使用提供的时间戳参数确保时间准确性。

package/templates/zh-CN/workflow/common/commands/init-project.md

@@ -0,0 +1,53 @@
+---
+description: 初始化项目 AI 上下文，生成/更新根级与模块级 CLAUDE.md 索引
+allowed-tools: Read(**), Write(CLAUDE.md, **/CLAUDE.md)
+argument-hint: <项目摘要或名称>
+---
+
+## 用法
+
+`/init-project <项目摘要或名称>`
+
+## 目标
+
+以"根级简明 + 模块级详尽"的混合策略初始化项目 AI 上下文：
+
+- 在仓库根生成/更新 `CLAUDE.md`（高层愿景、架构总览、模块索引、全局规范）。
+- 在识别的各模块目录生成/更新本地 `CLAUDE.md`（接口、依赖、入口、测试、关键文件等）。
+- ✨ **为了提升可读性，会在根 `CLAUDE.md` 中自动生成 Mermaid 结构图，并为每个模块 `CLAUDE.md` 添加导航面包屑**。
+
+## 编排说明
+
+**步骤 1**：调用 `get-current-datetime` 子智能体获取当前时间戳。
+
+**步骤 2**：调用一次 `init-architect` 子智能体，输入：
+
+- `project_summary`: $ARGUMENTS
+- `current_timestamp`: (来自步骤1的时间戳)
+
+## 执行策略（由 Agent 自适应决定，不需要用户传参）
+
+- **阶段 A：全仓清点（轻量）**
+  快速统计文件与目录，识别模块根（package.json、pyproject.toml、go.mod、apps/_、packages/_、services/\* 等）。
+- **阶段 B：模块优先扫描（中等）**
+  对每个模块做"入口/接口/依赖/测试/数据模型/质量工具"的定点读取与样本抽取。
+- **阶段 C：深度补捞（按需）**
+  若仓库较小或模块规模较小，则扩大读取面；若较大，则对高风险/高价值路径分批追加扫描。
+- **覆盖率度量与可续跑**
+  输出"已扫描文件数 / 估算总文件数、已覆盖模块占比、被忽略/跳过原因"，并列出"建议下一步深挖的子路径"。重复运行 `/init-project` 时按上次索引做**增量更新**与**断点续扫**。
+
+## 安全与边界
+
+- 只读/写文档与索引，不改源代码。
+- 默认忽略常见生成物与二进制大文件。
+- 结果在主对话打印"摘要"，全文写入仓库。
+
+## 输出要求
+
+- 在主对话中打印"初始化结果摘要"，包含：
+  - 根级 `CLAUDE.md` 是否创建/更新、主要栏目概览。
+  - 识别的模块数量及其路径列表。
+  - 每个模块 `CLAUDE.md` 的生成/更新情况。
+  - ✨ **明确提及"已生成 Mermaid 结构图"和"已为 N 个模块添加导航面包屑"**。
+  - 覆盖率与主要缺口。
+  - 若未读全：说明"为何到此为止"，并列出**推荐的下一步**（例如"建议优先补扫：packages/auth/src/controllers"）。

package/templates/zh-CN/workflow/git/commands/git-cleanBranches.md

@@ -32,6 +32,7 @@ argument-hint: [--base <branch>] [--stale <days>] [--remote] [--force] [--dry-ru
 ```
 
 ### Options
+
 - `--base <branch>`：指定清理的基准分支（默认为仓库的 `main`/`master`）。
 - `--stale <days>`：清理超过指定天数未提交的分支（默认不启用）。
 - `--remote`：同时清理远程已合并/过期的分支。
@@ -98,4 +99,4 @@ git config --get-all branch.cleanup.protected
 - ✅ **更灵活**：支持自定义基准分支，完美适配 `release` / `develop` 工作流。
 - ✅ **更兼容**：避免了在不同系统上行为不一的 `date -d` 等命令。
 - ✅ **更直观**：将复杂的 16 步清单，浓缩成一个带安全选项的、可直接执行的命令。
-- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。
+- ✅ **风格一致**：与 `/commit` 命令共享相似的参数设计与文档结构。

package/templates/zh-CN/workflow/git/commands/git-commit.md

@@ -50,31 +50,26 @@ argument-hint: [--no-verify] [--all] [--amend] [--signoff] [--emoji] [--scope <s
 ## What This Command Does
 
 1. **仓库/分支校验**
-
    - 通过 `git rev-parse --is-inside-work-tree` 判断是否位于 Git 仓库。
    - 读取当前分支/HEAD 状态；如处于 rebase/merge 冲突状态，先提示处理冲突后再继续。
 
 2. **改动检测**
-
    - 用 `git status --porcelain` 与 `git diff` 获取已暂存与未暂存的改动。
    - 若已暂存文件为 0：
      - 若传入 `--all` → 执行 `git add -A`。
      - 否则提示你选择：继续仅分析未暂存改动并给出**建议**，或取消命令后手动分组暂存。
 
 3. **拆分建议（Split Heuristics）**
-
    - 按**关注点**、**文件模式**、**改动类型**聚类（示例：源代码 vs 文档、测试；不同目录/包；新增 vs 删除）。
    - 若检测到**多组独立变更**或 diff 规模过大（如 > 300 行 / 跨多个顶级目录），建议拆分提交，并给出每一组的 pathspec（便于后续执行 `git add <paths>`）。
 
 4. **提交信息生成（Conventional 规范，可选 Emoji）**
-
    - 自动推断 `type`（`feat`/`fix`/`docs`/`refactor`/`test`/`chore`/`perf`/`style`/`ci`/`revert` …）与可选 `scope`。
    - 生成消息头：`[<emoji>] <type>(<scope>)?: <subject>`（首行 ≤ 72 字符，祈使语气，仅在使用 `--emoji` 时包含 emoji）。
    - 生成消息体：要点列表（动机、实现要点、影响范围、BREAKING CHANGE 如有）。
    - 将草稿写入 `.git/COMMIT_EDITMSG`，并用于 `git commit`。
 
 5. **执行提交**
-
    - 单提交场景：`git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG`
    - 多提交场景（如接受拆分建议）：按分组给出 `git add <paths> && git commit ...` 的明确指令；若允许执行则逐一完成。
 

package/templates/zh-CN/workflow/git/commands/git-rollback.md

@@ -10,7 +10,7 @@ argument-hint: [--branch <branch>] [--target <rev>] [--mode reset|revert] [--dep
 
 # Claude Command: Git Rollback
 
-**目的**：安全、可视地将指定分支回滚到旧版本。  
+**目的**：安全、可视地将指定分支回滚到旧版本。
 默认处于 **只读预览 (`--dry-run`)**；真正执行需加 `--yes` 或在交互中确认。
 
 ---