@zhuan-ai/zhuanspec 2.8.0 → 2.10.0

package/dist/core/hooks/record-progress.js

@@ -211,38 +211,80 @@ function extractMcpTool(toolName) {
     return parts.length >= 3 ? parts[2] : undefined;
 }
 /**
- * Detect active change from progress.json files
- * Scans changes directory metrics progress.json to find non-idle phase
- * Returns null if no active change found
+ * Detect active change from progress.json files.
+ *
+ * Strategy:
+ * 1. Primary — if filePath is under zhuanspec/changes/{changeId}/, extract changeId directly.
+ * 2. Fallback — scan all changes and return the most recently updated one
+ *    (by lastUpdatedAt field; stub files without it fall back to filesystem mtime).
  */
-async function detectActiveChange(cwd) {
+async function detectActiveChange(cwd, filePath) {
     const changesDir = path.join(cwd, 'zhuanspec', 'changes');
     if (!await FileSystemUtils.directoryExists(changesDir)) {
         return null;
     }
+    // Primary: derive changeId from the file being modified
+    if (filePath) {
+        const absFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+        const changesDirAbs = path.resolve(changesDir);
+        if (absFilePath.startsWith(changesDirAbs + path.sep)) {
+            const changeId = path.relative(changesDirAbs, absFilePath).split(path.sep)[0];
+            if (changeId && changeId !== 'archive') {
+                const progressPath = path.join(changesDirAbs, changeId, 'metrics', 'progress.json');
+                if (await FileSystemUtils.fileExists(progressPath)) {
+                    try {
+                        const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+                        if (progress.phase && progress.phase !== 'idle' && PHASE_ORDER.includes(progress.phase)) {
+                            return { changeId, phase: progress.phase };
+                        }
+                    }
+                    catch {
+                        // Fall through to fallback
+                    }
+                }
+            }
+        }
+    }
+    // Fallback: most recently updated active change
     const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const candidates = [];
     for (const entry of entries) {
         if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive')
             continue;
         const progressPath = path.join(changesDir, entry.name, 'metrics', 'progress.json');
-        if (await FileSystemUtils.fileExists(progressPath)) {
-            try {
-                const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
-                if (progress.phase && progress.phase !== 'idle' && PHASE_ORDER.includes(progress.phase)) {
-                    return { changeId: entry.name, phase: progress.phase };
-                }
+        if (!await FileSystemUtils.fileExists(progressPath))
+            continue;
+        try {
+            const progress = JSON.parse(await FileSystemUtils.readFile(progressPath));
+            if (!progress.phase || progress.phase === 'idle' || !PHASE_ORDER.includes(progress.phase))
+                continue;
+            let sortKey;
+            if (progress.lastUpdatedAt) {
+                // "2026-04-22 11:39:59" (Beijing time) — replace space with T for Date parsing
+                sortKey = new Date(progress.lastUpdatedAt.replace(' ', 'T')).getTime();
+                if (isNaN(sortKey))
+                    sortKey = 0;
             }
-            catch {
-                // Ignore parse errors
+            else {
+                // Stub files (e.g. techDesign) lack lastUpdatedAt — use filesystem mtime
+                const stat = await fs.stat(progressPath);
+                sortKey = stat.mtime.getTime();
             }
+            candidates.push({ changeId: entry.name, phase: progress.phase, sortKey });
+        }
+        catch {
+            // Ignore parse errors
         }
     }
-    return null;
+    if (candidates.length === 0)
+        return null;
+    candidates.sort((a, b) => b.sortKey - a.sortKey);
+    return { changeId: candidates[0].changeId, phase: candidates[0].phase };
 }
 async function runRecordProgress(filePath, toolName, success, stdinData) {
     const cwd = process.cwd();
-    // Priority: progress.json > environment variables
-    const activeChange = await detectActiveChange(cwd);
+    // Priority: filePath-derived > progress.json scan > environment variables
+    const activeChange = await detectActiveChange(cwd, filePath);
     const phase = activeChange?.phase || process.env.ZHUANSPEC_PHASE || 'idle';
     const changeId = activeChange?.changeId || process.env.ZHUANSPEC_CHANGE_ID || '';
     const currentTask = process.env.ZHUANSPEC_CURRENT_TASK || '';
@@ -641,7 +683,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
  */
 export async function recordHookTrigger(hookName, hookPhase, success, options) {
     const cwd = process.cwd();
-    const activeChange = await detectActiveChange(cwd);
+    const activeChange = await detectActiveChange(cwd, options?.filePath);
     const phase = activeChange?.phase || process.env.ZHUANSPEC_PHASE || 'idle';
     const changeId = activeChange?.changeId || process.env.ZHUANSPEC_CHANGE_ID || '';
     if (!changeId || phase === 'idle')

package/dist/core/hooks/review-hooks.js

@@ -16,7 +16,6 @@ import path from 'path';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { getBeijingTime } from './record-progress.js';
 // Output file paths for skill results
-const SKILL_OUTPUT_DIR = 'zhuanspec/.skill-outputs';
 const CODE_REVIEW_OUTPUT = 'code-review-result.json';
 const UNIT_TEST_OUTPUT = 'unit-test-result.json';
 const SPEC_CONSISTENCY_OUTPUT = 'spec-consistency-result.json';
@@ -205,7 +204,7 @@ export async function specConsistencyResultCheck(changeId, skillOutput) {
 // ============================================================
 async function readSkillOutput(changeId, filename) {
     const cwd = process.cwd();
-    const outputPath = path.join(cwd, SKILL_OUTPUT_DIR, changeId, filename);
+    const outputPath = path.join(cwd, 'zhuanspec', 'changes', changeId, 'review', filename);
     try {
         if (await FileSystemUtils.fileExists(outputPath)) {
             const content = await FileSystemUtils.readFile(outputPath);
@@ -276,7 +275,7 @@ export async function writeSpecConsistencyOutput(changeId, output) {
 export { writeSkillOutput };
 async function writeSkillOutput(changeId, filename, data) {
     const cwd = process.cwd();
-    const outputDir = path.join(cwd, SKILL_OUTPUT_DIR, changeId);
+    const outputDir = path.join(cwd, 'zhuanspec', 'changes', changeId, 'review');
     await FileSystemUtils.createDirectory(outputDir);
     const outputPath = path.join(outputDir, filename);
     await FileSystemUtils.writeFile(outputPath, JSON.stringify(data, null, 2));
@@ -337,7 +336,9 @@ ${results.codeReview.pass && results.unitTest.pass && results.specConsistency.pa
     // Write report to change directory
     const cwd = process.cwd();
     const changeDir = path.join(cwd, 'zhuanspec', 'changes', changeId);
-    const reportPath = path.join(changeDir, 'review-report.md');
+    const reviewDir = path.join(changeDir, 'review');
+    const reportPath = path.join(reviewDir, 'review-report.md');
+    await FileSystemUtils.createDirectory(reviewDir);
     await FileSystemUtils.writeFile(reportPath, report);
     return report;
 }

package/dist/core/hooks/review-orchestrator.js

@@ -25,7 +25,7 @@ function generateCodeReviewPrompt(changeId) {
 1. 执行 code-review-expert skill 进行代码审查
 2. 如果发现 Critical 问题，立即修复
 3. 修复后重新检查（最多3轮）
-4. 输出 code-review-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+4. 输出 code-review-result.json 报告到 zhuanspec/changes/${changeId}/review/
 
 ## 输出格式
 {
@@ -50,7 +50,7 @@ function generateUnitTestPrompt(changeId) {
 2. 运行单测，检查通过率和覆盖率
 3. 如果失败或不达标，立即修复
 4. 修复后重新测试（最多3轮）
-5. 输出 unit-test-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+5. 输出 unit-test-result.json 报告到 zhuanspec/changes/${changeId}/review/
 
 ## 输出格式
 {
@@ -76,7 +76,7 @@ function generateSpecConsistencyPrompt(changeId) {
 2. 检查代码实现是否覆盖每个 Scenario
 3. 如果发现未覆盖，立即补充代码或更新 Spec
 4. 修复后重新检查（最多3轮）
-5. 输出 spec-consistency-result.json 报告到 zhuanspec/.skill-outputs/${changeId}/
+5. 输出 spec-consistency-result.json 报告到 zhuanspec/changes/${changeId}/review/
 
 ## 输出格式
 {
@@ -100,7 +100,7 @@ export async function orchestrateReview(options) {
     const { changeId } = options;
     // Ensure output directory exists
     const cwd = process.cwd();
-    const outputDir = path.join(cwd, 'zhuanspec', '.skill-outputs', changeId);
+    const outputDir = path.join(cwd, 'zhuanspec', 'changes', changeId, 'review');
     await FileSystemUtils.createDirectory(outputDir);
     return {
         codeReviewPrompt: generateCodeReviewPrompt(changeId),

package/dist/core/init.js

@@ -314,7 +314,7 @@ export class InitCommand {
             }
             const specTemplateSpinner = this.startSpinner(`正在同步 ${this.businessDirection} 业务规范模板...`);
             const syncResult = this.syncBusinessSpecTemplate(zhuanspecPath);
-            if (syncResult.syncedSpecs || syncResult.syncedChanges) {
+            if (syncResult.syncedSpecs || syncResult.syncedChanges || syncResult.syncedKnowledge) {
                 const syncedParts = [];
                 if (syncResult.syncedSpecs) {
                     syncedParts.push('specs');
@@ -322,6 +322,9 @@ export class InitCommand {
                 if (syncResult.syncedChanges) {
                     syncedParts.push('changes');
                 }
+                if (syncResult.syncedKnowledge) {
+                    syncedParts.push('knowledge');
+                }
                 specTemplateSpinner.stopAndPersist({
                     symbol: PALETTE.white('▌'),
                     text: PALETTE.white(`已从远端模板同步 ${syncedParts.join('、')} 目录`),
@@ -791,28 +794,29 @@ export class InitCommand {
     }
     syncBusinessSpecTemplate(zhuanspecPath) {
         if (!this.businessDirection) {
-            return { syncedSpecs: false, syncedChanges: false };
+            return { syncedSpecs: false, syncedChanges: false, syncedKnowledge: false };
         }
         const tempDir = this.cloneRemoteArchitectureRepoToTemp();
         if (!tempDir) {
-            return { syncedSpecs: false, syncedChanges: false };
+            return { syncedSpecs: false, syncedChanges: false, syncedKnowledge: false };
         }
         try {
             const specsRoot = path.join(tempDir, 'specs');
             const businessRoot = this.resolveBusinessDirectionRoot(specsRoot);
             if (!businessRoot) {
-                return { syncedSpecs: false, syncedChanges: false };
+                return { syncedSpecs: false, syncedChanges: false, syncedKnowledge: false };
             }
             const templateRoot = this.findFirstTemplateSourceRoot(businessRoot);
             if (!templateRoot) {
-                return { syncedSpecs: false, syncedChanges: false };
+                return { syncedSpecs: false, syncedChanges: false, syncedKnowledge: false };
             }
             const syncedSpecs = this.copyDirectoryContentsIfExists(path.join(templateRoot, 'specs'), path.join(zhuanspecPath, 'specs'));
             const syncedChanges = this.copyDirectoryContentsIfExists(path.join(templateRoot, 'changes'), path.join(zhuanspecPath, 'changes'));
-            return { syncedSpecs, syncedChanges };
+            const syncedKnowledge = this.copyDirectoryContentsIfExists(path.join(templateRoot, 'knowledge'), path.join(zhuanspecPath, 'knowledge'));
+            return { syncedSpecs, syncedChanges, syncedKnowledge };
         }
         catch {
-            return { syncedSpecs: false, syncedChanges: false };
+            return { syncedSpecs: false, syncedChanges: false, syncedKnowledge: false };
         }
         finally {
             rmSync(tempDir, { recursive: true, force: true });
@@ -1254,6 +1258,17 @@ export class InitCommand {
                         ],
                     },
                 ],
+                UserPromptSubmit: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'zhuanspec-hook deviation-check --trigger post-prompt',
+                                statusMessage: 'Checking prompt vs proposal consistency...',
+                            },
+                        ],
+                    },
+                ],
                 PreToolUse: [
                     {
                         matcher: 'Write|Edit',
@@ -1276,10 +1291,15 @@ export class InitCommand {
                                 statusMessage: '📝 Recording progress...',
                                 async: false,
                             },
+                        ],
+                    },
+                    {
+                        matcher: 'Write|Edit',
+                        hooks: [
                             {
                                 type: 'command',
-                                command: 'zhuanspec-hook collect-knowledge',
-                                statusMessage: '📚 Collecting knowledge...',
+                                command: 'zhuanspec-hook collect-knowledge --json',
+                                statusMessage: '💡 Checking for knowledge to capture...',
                                 async: false,
                             },
                         ],

package/dist/core/templates/slash-command-templates.js

@@ -6,7 +6,7 @@ const baseGuardrails = `**约束条件**
 const proposalGuardrails = `${baseGuardrails}\n- **强制澄清要求**：在创建任何提案文件之前，必须首先分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、优先级、验收标准等）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测、假设或创建提案。严禁要求用户手动输入大段文字来回答澄清问题。
 - 识别任何模糊或歧义的细节，使用带预设选项的选择题在编辑文件之前询问必要的后续问题。
 - 在提案阶段不要编写任何代码。先完成 techDesign（需求技术方案）后再创建 proposal/specs/tasks，实施在批准后的应用阶段进行。
-- **TechDesign 目录识别**：proposal 阶段扫描 changes/ 目录，通过 progress.json 的 phase 字段识别 techDesign 目录，交互式确认复用。
+- **TechDesign 目录识别**：proposal 阶段扫描 changes/ 目录，通过 progress.json 的 phase 字段识别 techDesign 目录，**自动复用**（无需询问用户）。
 - **Phase 自动更新**：复用 techDesign 目录时，自动运行 \`zhuanspec progress set-phase <change-id> propose\` 更新 phase。`;
 const proposalOutputFormat = `**输出格式要求**
 每个步骤完成后，输出阶段性进度报告：
@@ -64,11 +64,9 @@ const proposalSteps = `**步骤**
    - **TechDesign 目录识别**：
      * 扫描 changes/ 目录下的所有变更
      * 检查每个变更的 metrics/progress.json 的 phase 字段
-     * 如果存在 phase=techDesign 的目录，列为候选
-     * 使用 AskQuestion 工具交互式确认：
-       - 选择复用现有 techDesign 目录（列出所有候选）
-       - 创建新目录
-       - 其他（手动指定）
+     * 如果存在 phase=techDesign 的目录，**直接复用该目录，无需询问用户**，并输出提示："techDesign 阶段已提前创建提案目录，直接复用该目录"
+     * 如果存在多个 phase=techDesign 目录，复用最新创建的目录
+     * 如果不存在 phase=techDesign 目录，创建新目录
    - **Phase 初始化**：
      * 如果复用 techDesign 目录：运行 \`zhuanspec progress set-phase <change-id> propose\`
      * 如果新建目录：目录创建时自动初始化 phase=propose
@@ -106,6 +104,13 @@ const proposalSteps = `**步骤**
     -如果复用了techDesign创建的提案目录，需要输出'techDesign阶段已经提前创建好提案目录，我将直接在该目录生成相关提案文件'
 3. 将变更映射为具体的功能或要求，将多范围的工作分解为具有明确关系和顺序的不同规范增量。
 4. 创建 \`design.md\`（必选），记录技术决策、最佳实践、隐式约定。归档时会自动提取这些内容沉淀到项目知识库。
+   - **如果用户已提供详细技术方案**，必须将以下内容系统性摄取到 design.md 对应章节，不得遗漏：
+     * 接口定义（方法签名、入参/出参字段、类型、枚举值）→ 写入 \`## 接口设计\`
+     * DB schema 变更、实体类字段 → 写入 \`## 数据模型\`
+     * 流程图/时序图 → 写入 \`## 业务流程\`
+     * 分层实现说明、关键逻辑 → 写入 \`## 实现细节\`
+     * 参数校验、错误码、异常处理 → 写入 \`## 边界条件 / 异常处理\`
+   - **摄取原则**：保留原始章节标题和结构，便于 apply 阶段按章节定位；不要压缩或省略具体字段定义
 5. 在 \`changes/<id>/specs/<capability>/spec.md\` 中起草规范增量（每个功能一个文件夹），使用 \`## ADDED|MODIFIED|REMOVED Requirements\`，每个要求至少包含一个 \`#### Scenario:\`，并在相关时交叉引用相关功能。
 6. **发现可用 Skill 并创建 tasks.md**：
    - 运行 \`zhuanspec skills list --json\` 获取当前环境中可用的 skill 列表及其 description
@@ -144,9 +149,7 @@ const proposalSteps = `**步骤**
      * 选择"提供测试 case"：
        - 启用 **TDD 模式**：先获取测试 case，再基于 case 设计 spec 和任务
        - **【强制】获取测试 case 的方式**：
-         * 如果用户提供的是**链接**（如 zzcase 平台 URL）：使用 \`@skill:zzcase-data-fetcher\` skill 直接读取
-         * 如果用户提供 **taskId/bicId**：使用 \`@skill:zzcase-data-fetcher\` skill 通过参数获取
-         * **禁止**使用 MCP 工具 \`zzcase_get_api_report_queryBaseCase\` 获取测试 case
+         * 如果用户提供的是**链接**（格式：\`https://zzcase.zhuanspirit.com/plan/taskDetail/module/{moduleId}/task/{taskId}\`）：从 URL 路径中提取 \`moduleId\`，调用 MCP 工具 \`mcp__caseweb__GET_get2\`，传入 \`moduleId\` 参数读取测试 case 数据
        - 或手动录入测试 case
        - **【强制】创建 test-cases.md 文件**：
          * 使用 \`getTestCasesTemplate\` 模板（从 \`src/core/templates/index.ts\` 导出）
@@ -228,11 +231,13 @@ const applySteps = `**步骤**
      → **Agent 类型选择**：根据任务是否标注 \`@test-case\` 选择：
        * 无 \`@test-case\` 标注 → 使用 \`applyAgent\`（普通代码实施）
        * 有 \`@test-case:TC-XXX\` 标注 → 使用 \`tddApplyAgent\`（TDD 模式）
-     → **Rules 和 Knowledge 注入**：编排 Agent MUST 在每个 subagent prompt 中注入：
+     → **Subagent 上下文注入（最小必要原则）**：编排 Agent 在每个 subagent prompt 中只注入：
+       * 当前任务描述（task 文本 + @skill + @test-case 标注）
+       * 变更目录路径：\`changes/<change-id>/\`（agent 按需 Read）
+       * 提案文件清单（列出目录下存在哪些文件，agent 知道可以读什么）
        * Rules：根据任务的 \`@skill\` 标注选择性注入 \`api-design.md\`、\`dao-standards.md\`、\`coding-standards.md\` 等
        * Knowledge：始终注入 \`knowledge/index.md\` 知识索引摘要
-       * Troubleshooting：注入与任务相关的踩坑警告
-     → Subagent 上下文隔离：仅注入当前任务、关联 skill、相关 spec、Rules/Knowledge
+       → **不预先注入提案文件全文**，由 subagent 按需 Read，避免无关文件消耗 token
    - **如果 tasks.md 无依赖声明**：
      → 按顺序执行（见下方步骤 3-5）
 3. **按顺序实施任务**（无依赖声明时）- 保持编辑最小化并专注于请求的变更。如果任务标注了 \`@skill:<skill-name>\`，直接调用对应 skill 获取指导后再实施。
@@ -242,10 +247,12 @@ const applySteps = `**步骤**
 4. **确认完成** - 在更新状态之前确保 \`tasks.md\` 中的每个项目都已完成。
 5. **更新清单** - 所有工作完成后，将每个任务设置为 \`- [x]\`，以便列表反映实际情况。
 6. **处理 Subagent 状态报告**（Wave 并行执行时）：
-   - **DONE**：继续下一任务
-   - **DONE_WITH_CONCERNS**：记录 concerns 并评估是否需要修复
-   - **BLOCKED**：评估 blocker 类型并决定处理策略（提供上下文/换更强模型/拆分任务）
-   - **NEEDS_CONTEXT**：提供缺失信息并重新启动 subagent
+   - **必须转发进度汇报**：每个 subagent 完成后，将其输出的 \`━━━ ✅ 任务完成\` 进度块原文转发输出给用户
+   - **DONE**：转发进度汇报 → 继续下一任务
+   - **DONE_WITH_CONCERNS**：转发进度汇报 → 记录 concerns 并评估是否需要修复
+   - **BLOCKED**：转发进度汇报 → 评估 blocker 类型并决定处理策略（提供上下文/换更强模型/拆分任务）
+   - **NEEDS_CONTEXT**：转发进度汇报 → 提供缺失信息并重新启动 subagent
+   - 所有任务报告文件均保存在 \`changes/<change-id>/reports/\` 目录，可告知用户按 task-id 查阅
 8. 需要额外上下文时，参考 \`zhuanspec list\` 或 \`zhuanspec show <item>\`。
 9. **触发审查门禁** - 所有任务完成后选项式提问用户是否进入 Review 阶段`;
 const applyGuardrails = `${baseGuardrails}\n- **Wave 并行执行**：当 tasks.md 包含 \`@depends\` 时，按 Wave 编号串行执行，Wave 内任务通过 Agent tool 并行启动 subagent。
@@ -339,7 +346,7 @@ const designReferences = `**参考**
 - 使用 \`zhuanspec techDesign --help\` 查看 CLI 命令选项（用于生成请求文档或验证现有设计）`;
 const reviewGuardrails = `${baseGuardrails}\n- **门禁审查阶段**：review 命令用于执行三轨并行校验并汇总结论。
 - **强制审查**：所有变更在归档前必须通过三轨门禁，确保代码质量、测试覆盖与 Spec-Code 一致性。
-- **Skill 触发要求**：必须触发 \`code-review-expert\`（代码审查轨）与 \`generate-mockito-unit-test-skill\`（单测轨）。`;
+- **Skill 触发要求**：必须触发 \`code-review-expert\`（代码审查轨）与 \`generate-mockito-unit-test\`（单测轨）。`;
 const reviewSteps = `**步骤**
 1. **确定变更 ID 并设置 Phase**：
    - 如果此提示已包含特定的变更 ID，请使用该值
@@ -349,15 +356,28 @@ const reviewSteps = `**步骤**
    - **轨道 A：Code Review 轨**
      - 使用 Skill 工具调用 \`code-review-expert\` skill
      - 输出 \`code-review-report.md\`，记录 Critical/Important 问题
+     - skill 完成后，**AI 将结果写入** \`changes/<id>/review/code-review-result.json\`，格式：
+       \`\`\`json
+       { "criticalCount": 0, "importantCount": 0, "infoCount": 0, "issues": [], "sonarStatus": "skip", "loopCount": 0 }
+       \`\`\`
    - **轨道 B：Unit Test 轨（Skill）**
-     - 使用 Skill 工具调用 \`generate-mockito-unit-test-skill\`
+     - 使用 Skill 工具调用 \`generate-mockito-unit-test\`
      - 对缺失场景补齐单测并执行测试命令，输出单测结果
+     - skill 完成后，**AI 将结果写入** \`changes/<id>/review/unit-test-result.json\`，格式：
+       \`\`\`json
+       { "testPassed": true, "passRate": 100, "coverage": 85, "coverageThreshold": 80, "newTestsGenerated": [], "failedTests": [], "loopCount": 0 }
+       \`\`\`
    - **轨道 C：Spec-Code 一致性轨**
      - 运行 \`zhuanspec validate <change-id> --strict\`
      - 确认 \`spec-code-consistent\` 规则通过
+     - validate 完成后，**AI 将结果写入** \`changes/<id>/review/spec-consistency-result.json\`，格式：
+       \`\`\`json
+       { "consistencyRate": 100, "totalRequirements": 0, "totalScenarios": 0, "coveredScenarios": 0, "uncoveredScenarios": [], "mapping": [], "loopCount": 0 }
+       \`\`\`
 3. **汇总执行 CLI Review**：
    - 运行 \`zhuanspec review <change-id>\`
-   - CLI 汇总三轨结果并生成 \`review-report.md\` 及 JSON 结果文件
+   - CLI 读取三个 JSON，生成 \`changes/<id>/review/review-report.md\`
+   - 如果 skill JSON 未写入，CLI 将打印缺失文件列表并退出
 4. **审查结果处理**：
    - **PASS**：三轨全部通过（CR=PASS、UT=PASS、Spec-Code=PASS）且 Critical=0，可以继续归档
    - **FAIL**：输出问题列表，需要修复后重新审查
@@ -369,9 +389,9 @@ const reviewSteps = `**步骤**
    - 提示可以使用 \`/zhuanspec:archive\` 进行归档`;
 const reviewReferences = `**参考**
 - 使用 \`zhuanspec review --help\` 查看完整选项
-- 审查报告包含：\`code-review-result.json\`、\`unit-test-result.json\`、\`spec-consistency-result.json\`、\`review-report.md\`
+- 审查报告文件均位于 \`changes/<id>/review/\` 目录下：\`code-review-result.json\`、\`unit-test-result.json\`、\`spec-consistency-result.json\`、\`review-report.md\`
 - 单元测试覆盖率阈值默认 80%，可通过 \`--coverage-threshold\` 调整
-- \`code-review-expert\` Skill 输出保存到 \`zhuanspec/changes/<id>/metrics/code-review-report.md\``;
+- \`code-review-expert\` Skill 结果由 AI 写入 \`changes/<id>/review/code-review-result.json\`，\`generate-mockito-unit-test\` Skill 结果由 AI 写入 \`changes/<id>/review/unit-test-result.json\``;
 const knowledgeGuardrails = `${baseGuardrails}\n- **知识管理阶段**：knowledge 命令用于管理项目级知识库（最佳实践、陷阱、隐式约定）。
 - **跨变更积累**：知识不绑定单个变更，是长期积累的项目资产。
 - **职责分离**：

package/dist/core/update.d.ts

@@ -1,4 +1,7 @@
 export declare class UpdateCommand {
     execute(projectPath: string): Promise<void>;
+    private syncDotClaudeFromRemote;
+    private cloneRemoteToTemp;
+    private syncDirectory;
 }
 //# sourceMappingURL=update.d.ts.map

package/dist/core/update.js

@@ -1,9 +1,14 @@
 import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+import { mkdtempSync, rmSync, readdirSync, readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { FileSystemUtils } from '../utils/file-system.js';
 import { ZHUANSPEC_DIR_NAME } from './config.js';
 import { ToolRegistry } from './configurators/registry.js';
 import { SlashCommandRegistry } from './configurators/slash/registry.js';
 import { agentsTemplate } from './templates/agents-template.js';
+const ARCH_REPO_URL = 'http://gitlab.zhuanspirit.com/zz-kf/spec_repo.git';
+const ARCH_REPO_BRANCH = 'spec_repo-feature-6612-2';
 export class UpdateCommand {
     async execute(projectPath) {
         const resolvedProjectPath = path.resolve(projectPath);
@@ -59,6 +64,8 @@ export class UpdateCommand {
                 console.error(`更新 ${slashConfigurator.toolId} 的斜杠命令失败：${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        // 4. Sync .claude/ from remote (rules, skills, agents)
+        const claudeSyncResult = this.syncDotClaudeFromRemote(resolvedProjectPath);
         const summaryParts = [];
         const instructionFiles = ['zhuanspec/AGENTS.md'];
         if (updatedFiles.includes('AGENTS.md')) {
@@ -70,10 +77,24 @@ export class UpdateCommand {
             summaryParts.push(`已更新 AI 工具文件：${aiToolFiles.join(', ')}`);
         }
         if (updatedSlashFiles.length > 0) {
-            // Normalize to forward slashes for cross-platform log consistency
             const normalized = updatedSlashFiles.map((p) => FileSystemUtils.toPosixPath(p));
             summaryParts.push(`已更新斜杠命令：${normalized.join(', ')}`);
         }
+        if (claudeSyncResult.synced) {
+            const { added, overwritten, skipped } = claudeSyncResult;
+            const total = added + overwritten + skipped;
+            const parts = [];
+            if (added > 0)
+                parts.push(`新增 ${added} 个`);
+            if (overwritten > 0)
+                parts.push(`更新 ${overwritten} 个`);
+            if (skipped > 0)
+                parts.push(`跳过 ${skipped} 个`);
+            summaryParts.push(`已同步 .claude/ 远端内容（${total} 个文件，${parts.join('，')}）`);
+        }
+        else if (claudeSyncResult.attempted) {
+            summaryParts.push('同步 .claude/ 远端内容失败（网络不可用或权限不足）');
+        }
         const failedItems = [
             ...failedFiles,
             ...failedSlashTools.map((toolId) => `斜杠命令刷新（${toolId}）`),
@@ -82,7 +103,69 @@ export class UpdateCommand {
             summaryParts.push(`更新失败：${failedItems.join(', ')}`);
         }
         console.log(summaryParts.join(' | '));
-        // No additional notes
+    }
+    syncDotClaudeFromRemote(projectPath) {
+        const tempDir = this.cloneRemoteToTemp();
+        if (!tempDir) {
+            return { attempted: true, synced: false, added: 0, overwritten: 0, skipped: 0 };
+        }
+        try {
+            const commonDotClaude = path.join(tempDir, 'specs', 'common', 'claude', '.claude');
+            if (!existsSync(commonDotClaude)) {
+                return { attempted: true, synced: false, added: 0, overwritten: 0, skipped: 0 };
+            }
+            const targetDotClaude = path.join(projectPath, '.claude');
+            const result = this.syncDirectory(commonDotClaude, targetDotClaude);
+            return { attempted: true, synced: true, ...result };
+        }
+        catch {
+            return { attempted: true, synced: false, added: 0, overwritten: 0, skipped: 0 };
+        }
+        finally {
+            rmSync(tempDir, { recursive: true, force: true });
+        }
+    }
+    cloneRemoteToTemp() {
+        const tempDir = mkdtempSync(path.join(os.tmpdir(), 'zhuanspec-update-'));
+        try {
+            execSync(`git clone --depth 1 --single-branch --branch ${ARCH_REPO_BRANCH} ${ARCH_REPO_URL} "${tempDir}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+            return tempDir;
+        }
+        catch {
+            rmSync(tempDir, { recursive: true, force: true });
+            return null;
+        }
+    }
+    syncDirectory(srcDir, dstDir) {
+        const result = { added: 0, overwritten: 0, skipped: 0 };
+        const sync = (src, dst) => {
+            mkdirSync(dst, { recursive: true });
+            for (const entry of readdirSync(src, { withFileTypes: true })) {
+                const srcPath = path.join(src, entry.name);
+                const dstPath = path.join(dst, entry.name);
+                if (entry.isDirectory()) {
+                    sync(srcPath, dstPath);
+                }
+                else {
+                    const srcContent = readFileSync(srcPath);
+                    if (existsSync(dstPath)) {
+                        if (Buffer.compare(srcContent, readFileSync(dstPath)) === 0) {
+                            result.skipped++;
+                        }
+                        else {
+                            writeFileSync(dstPath, srcContent);
+                            result.overwritten++;
+                        }
+                    }
+                    else {
+                        writeFileSync(dstPath, srcContent);
+                        result.added++;
+                    }
+                }
+            }
+        };
+        sync(srcDir, dstDir);
+        return result;
     }
 }
 //# sourceMappingURL=update.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",