@zhuan-ai/zhuanspec 2.16.0 → 2.16.2

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

@@ -112,6 +112,7 @@ export async function recoverProgressJsonForWrite(filePath) {
                 phaseDurations: [{
                         phase: recoveredPhase,
                         startedAt: '',
+                        lastUpdatedAt: '',
                         durationMs: 0,
                         taskCount: 0,
                         completedTaskCount: 0,
@@ -905,6 +906,15 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
                 progress.stats.durationMs.review = elapsedMs;
             if (phase === 'archive')
                 progress.stats.durationMs.archive = elapsedMs;
+            // v2.15.16：同步刷新活跃段的 phaseDurations 记录，进行中也能从单条直接读出
+            // 实时 durationMs / lastUpdatedAt。endedAt 仍仅在 phase 切换时填。
+            const activeEntry = [...progress.phaseDurations]
+                .reverse()
+                .find(pd => pd.phase === phase && !pd.endedAt);
+            if (activeEntry) {
+                activeEntry.durationMs = elapsedMs;
+                activeEntry.lastUpdatedAt = getBeijingTime();
+            }
         }
     }
     // === Auto-count tasks from tasks.md ===
@@ -1087,6 +1097,7 @@ function createNewProgress(changeId) {
         phaseDurations: [{
                 phase: initialPhase,
                 startedAt: getBeijingTime(),
+                lastUpdatedAt: getBeijingTime(),
                 durationMs: 0,
                 taskCount: 0,
                 completedTaskCount: 0,
@@ -1160,6 +1171,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
                 const prevPhaseDuration = progress.phaseDurations.find(pd => pd.phase === previousPhase && !pd.endedAt);
                 if (prevPhaseDuration) {
                     prevPhaseDuration.endedAt = timestamp;
+                    prevPhaseDuration.lastUpdatedAt = timestamp;
                     const startTime = new Date(prevPhaseDuration.startedAt.replace(' ', 'T')).getTime();
                     const endTime = new Date(timestamp.replace(' ', 'T')).getTime();
                     const ms = Number.isFinite(startTime) && endTime > startTime ? endTime - startTime : 0;
@@ -1181,6 +1193,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
                             phase: previousPhase,
                             startedAt: inferredStart,
                             endedAt: timestamp,
+                            lastUpdatedAt: timestamp,
                             durationMs: ms,
                             taskCount: 0,
                             completedTaskCount: 0,
@@ -1194,6 +1207,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
                 progress.phaseDurations.push({
                     phase: initialPhase,
                     startedAt: timestamp,
+                    lastUpdatedAt: timestamp,
                     durationMs: 0,
                     taskCount: 0,
                     completedTaskCount: 0,
@@ -1271,6 +1285,7 @@ function seedInitialPhase(progress, initialPhase, timestamp) {
         for (const entry of progress.phaseDurations) {
             if (!entry.endedAt && entry.phase !== initialPhase) {
                 entry.endedAt = timestamp;
+                entry.lastUpdatedAt = timestamp;
                 const startTime = new Date((entry.startedAt || timestamp).replace(' ', 'T')).getTime();
                 const endTime = new Date(timestamp.replace(' ', 'T')).getTime();
                 entry.durationMs = Number.isFinite(startTime) && endTime > startTime ? endTime - startTime : 0;
@@ -1279,6 +1294,7 @@ function seedInitialPhase(progress, initialPhase, timestamp) {
         progress.phaseDurations.push({
             phase: initialPhase,
             startedAt: timestamp,
+            lastUpdatedAt: timestamp,
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,

package/dist/core/hooks/summarize.js

@@ -263,40 +263,39 @@ async function runSummarize() {
         && progressData.askedPitfallSaved !== true) {
         pitfallAskPending = true;
         const n = progressData.corrections.length;
-        const previews = progressData.corrections
-            .filter(c => c.event === 'detected')
-            .slice(-3)
-            .map((c, i) => `  ${i + 1}. ${c.promptPreview || '(no preview)'}`)
-            .join('\n');
         pitfallAdditionalContext = [
             '## ⚠️ ZhuanSpec 知识沉淀询问（收尾必做）',
             '',
-            `本轮会话发生过 ${n} 次用户纠偏且尚未沉淀，必须按以下顺序处理（严禁跳步，严禁自行 Write 知识文件）：`,
+            `本轮会话发生过 ${n} 次用户纠偏且尚未沉淀，必须按以下顺序处理（严禁跳步、严禁仅根据最近 N 条摘要拍脑袋决策、严禁自行 Write 知识文件）：`,
             '',
             '### 必须执行的步骤',
             '',
-            `1. **用 askUserQuestion 询问用户**（二选一）：`,
-            '   - header: "踩坑沉淀"',
-            `   - question: "本轮 Apply 阶段发生过 ${n} 次用户纠偏，是否沉淀为项目知识？"`,
-            '   - 选项 1: "是，沉淀"',
-            '   - 选项 2: "否，跳过"',
+            `1. **先生成决策清单（必须）**：运行`,
+            '   ```bash',
+            `   zhuanspec progress list-corrections ${changeId}`,
+            '   ```',
+            '   CLI 会过滤 trivial 确认词（如 "是的/好的/ok"）+ 去重（完全重复 + 子串包含）+ 启发式分类，输出到 `zhuanspec/changes/<change-id>/review/pending-corrections.md`，并在 stdout 给出 **合计 / 有效 / 过滤** 三个计数。',
             '',
-            `2. **用户选"是"**：**必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`** （或等价的 \`/zhuanspec:knowledge\` slash command 并在交互中选择模式 B）完成沉淀。`,
-            `   - change-id 值为 \`${changeId}\``,
-            '   - **禁止直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**，禁止自行判定分类或文件名格式；所有写入由 skill 统一执行。',
-            '   - skill 将自动完成：读取 user_inputs.json（Level 1）或 summary 关键词批量扫描（Level 2）→ 分类决策树 → 去重扫描 → 套用统一 Front Matter → 写入对应分类目录 → 更新 index.md → 标记 resolve-correction。',
+            '2. **用 askUserQuestion 询问用户（三选项，禁止默认）**：',
+            '   - header: "踩坑沉淀"',
+            '   - question: "本轮有 M 条有效纠偏候选（已过滤 trivial / 去重，详见 review/pending-corrections.md），请选择沉淀范围："',
+            '   - 选项 1: "全部沉淀"',
+            '   - 选项 2: "选择性沉淀（请回复编号清单，例如 1,3,5）"',
+            '   - 选项 3: "跳过"',
             '',
-            `3. **用户选"否"**：运行 \`zhuanspec progress resolve-correction ${changeId} --mark-pitfall-saved\` 标记已处理，不写入任何知识文件。`,
+            `3. **用户选 "全部沉淀" 或 "选择性沉淀"**：必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\` （或 \`/zhuanspec:knowledge\` 模式 B）完成沉淀。change-id 值为 \`${changeId}\`。选择性沉淀时把用户回复的编号串以 \`--include <编号串>\` 透传给 skill。`,
+            '   - **禁止直接 Write/Edit 创建 `zhuanspec/knowledge/` 下的任何文件**，禁止自行判定分类或文件名格式；所有写入由 skill 统一执行。',
+            '   - skill 必须以 `pending-corrections.md` 作为商定范围的单一源，禁止从会话记忆里“发挥”额外条目。',
             '',
-            '### 纠偏记录摘要（最近 3 条 promptPreview）',
-            previews || '  (none)',
+            `4. **用户选 "跳过"**：运行 \`zhuanspec progress resolve-correction ${changeId} --mark-pitfall-saved\` 标记已处理，不写入任何知识文件。`,
             '',
             '### 红线提示',
             '- 禁止绕过 skill 直接 Write/Edit 知识文件（等同于绕过质量门禁）。',
+            '- 禁止跳过 list-corrections 一步，仅靠 promptPreview 拍脑袋决策。',
             '- 禁止新建 decisions/ 或三类目录以外的分类。',
             '- skill 模式 B 完成后会自动写入 askedPitfallSaved=true，无需人工重复调用 CLI。',
         ].join('\n');
-        systemMessage += `\n⚠️ 检测到 ${n} 次用户纠偏未沉淀——请按上方说明调 askUserQuestion，用户选是后必须调用 @skill:zhuanspec:knowledge 而非自行 Write。\n`;
+        systemMessage += `\n⚠️ 检测到 ${n} 次用户纠偏未沉淀——请先运行 zhuanspec progress list-corrections ${changeId}，再用 askUserQuestion 三选项决策，用户选「全部/选择性沉淀」后必须调用 @skill:zhuanspec:knowledge 而非自行 Write。\n`;
     }
     // === Task 0 路径 1：Stop 时按核心产出齐备度自动打 phase baseline ===
     // 幂等：已打标则跳过；先到先得（auto-file-complete 优于 auto-stop）

package/dist/core/init.d.ts

@@ -53,6 +53,11 @@ export declare class InitCommand {
     private fetchRemoteArchitectureFiles;
     private fetchRemoteArchitectureContent;
     private cloneRemoteArchitectureRepoToTemp;
+    /**
+     * Append a JSONL line to ~/.zhuanspec-init-debug.log for offline troubleshooting.
+     * Failures are swallowed to avoid breaking init.
+     */
+    private logInitDebug;
     private syncBusinessSpecTemplate;
     private syncBusinessClaudeAssets;
     private resolveBusinessDirectionRoot;

package/dist/core/init.js

@@ -1,6 +1,6 @@
 import path from 'path';
 import os from 'os';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync, readdirSync, readFileSync, rmSync, } from 'fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, realpathSync, writeFileSync, readdirSync, readFileSync, rmSync, appendFileSync, } from 'fs';
 import { createPrompt, isBackspaceKey, isDownKey, isEnterKey, isSpaceKey, isUpKey, useKeypress, usePagination, useState, } from '@inquirer/core';
 import chalk from 'chalk';
 import ora from 'ora';
@@ -806,15 +806,56 @@ export class InitCommand {
     }
     cloneRemoteArchitectureRepoToTemp() {
         const tempDir = mkdtempSync(path.join(os.tmpdir(), 'zhuanspec-arch-'));
+        const startedAt = Date.now();
         try {
-            execSync(`git clone --depth 1 --single-branch --branch ${ARCH_REPO_BRANCH} ${ARCH_REPO_URL} "${tempDir}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'ignore'] });
+            execSync(`git clone --depth 1 --single-branch --branch ${ARCH_REPO_BRANCH} ${ARCH_REPO_URL} "${tempDir}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            this.logInitDebug({
+                scope: 'cloneRemoteArchitectureRepoToTemp',
+                result: 'ok',
+                repo: ARCH_REPO_URL,
+                branch: ARCH_REPO_BRANCH,
+                tempDir,
+                elapsedMs: Date.now() - startedAt,
+            });
             return tempDir;
         }
-        catch {
+        catch (err) {
+            this.logInitDebug({
+                scope: 'cloneRemoteArchitectureRepoToTemp',
+                result: 'fail',
+                repo: ARCH_REPO_URL,
+                branch: ARCH_REPO_BRANCH,
+                tempDir,
+                elapsedMs: Date.now() - startedAt,
+                errorMessage: err?.message ?? String(err),
+                stderr: err?.stderr ? String(err.stderr).slice(0, 1000) : undefined,
+                stdout: err?.stdout ? String(err.stdout).slice(0, 500) : undefined,
+                status: err?.status,
+            });
             rmSync(tempDir, { recursive: true, force: true });
             return null;
         }
     }
+    /**
+     * Append a JSONL line to ~/.zhuanspec-init-debug.log for offline troubleshooting.
+     * Failures are swallowed to avoid breaking init.
+     */
+    logInitDebug(payload) {
+        try {
+            const line = JSON.stringify({
+                ts: new Date().toISOString(),
+                pid: process.pid,
+                cwd: process.cwd(),
+                businessDirection: this.businessDirection ?? null,
+                ...payload,
+            });
+            const logPath = path.join(os.homedir(), '.zhuanspec-init-debug.log');
+            appendFileSync(logPath, line + '\n', 'utf-8');
+        }
+        catch {
+            // ignore
+        }
+    }
     syncBusinessSpecTemplate(zhuanspecPath) {
         if (!this.businessDirection) {
             return { syncedSpecs: false, syncedChanges: false, syncedKnowledge: false };
@@ -851,10 +892,20 @@ export class InitCommand {
             dotClaude: { source: 'none', files: { added: [], overwritten: [], skipped: [] } },
         };
         if (!this.businessDirection) {
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'skip-no-business-direction',
+                projectPath,
+            });
             return fallbackResult;
         }
         const tempDir = this.cloneRemoteArchitectureRepoToTemp();
         if (!tempDir) {
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'skip-clone-failed',
+                projectPath,
+            });
             return fallbackResult;
         }
         try {
@@ -868,12 +919,50 @@ export class InitCommand {
             const resolvedClaudeMdSource = this.resolveClaudeAssetSource(businessClaudeMd, commonClaudeMd);
             // .claude directory: always from common directory (not business-specific)
             const commonDotClaude = path.join(commonClaudeRoot, '.claude');
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'start-copy',
+                projectPath,
+                tempDir,
+                specsRootExists: existsSync(specsRoot),
+                businessRoot,
+                commonClaudeRoot,
+                commonClaudeRootExists: existsSync(commonClaudeRoot),
+                commonDotClaude,
+                commonDotClaudeExists: existsSync(commonDotClaude),
+                commonDotClaudeHasFiles: existsSync(commonDotClaude)
+                    ? this.directoryHasAtLeastOneFile(commonDotClaude)
+                    : false,
+                commonDotClaudeTopEntries: existsSync(commonDotClaude)
+                    ? readdirSync(commonDotClaude)
+                    : [],
+            });
+            const claudeMdResult = this.copyClaudeFileIfNeeded(resolvedClaudeMdSource, path.join(projectPath, 'CLAUDE.md'));
+            const dotClaudeResult = this.copyClaudeDirectoryFromCommon(commonDotClaude, path.join(projectPath, '.claude'));
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'done',
+                projectPath,
+                claudeMd: claudeMdResult,
+                dotClaudeSource: dotClaudeResult.source,
+                dotClaudeAdded: dotClaudeResult.files.added.length,
+                dotClaudeOverwritten: dotClaudeResult.files.overwritten.length,
+                dotClaudeSkipped: dotClaudeResult.files.skipped.length,
+                dotClaudeAddedSample: dotClaudeResult.files.added.slice(0, 5),
+            });
             return {
-                claudeMd: this.copyClaudeFileIfNeeded(resolvedClaudeMdSource, path.join(projectPath, 'CLAUDE.md')),
-                dotClaude: this.copyClaudeDirectoryFromCommon(commonDotClaude, path.join(projectPath, '.claude')),
+                claudeMd: claudeMdResult,
+                dotClaude: dotClaudeResult,
             };
         }
-        catch {
+        catch (err) {
+            this.logInitDebug({
+                scope: 'syncBusinessClaudeAssets',
+                result: 'exception',
+                projectPath,
+                errorMessage: err?.message ?? String(err),
+                stack: err?.stack ? String(err.stack).slice(0, 500) : undefined,
+            });
             return fallbackResult;
         }
         finally {
@@ -991,13 +1080,30 @@ export class InitCommand {
             files: { added: [], overwritten: [], skipped: [] },
         };
         if (!sourceAsset) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                result: 'skip-no-source-asset',
+                targetPath,
+            });
             return emptyResult;
         }
         if (!existsSync(sourceAsset.path)) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                result: 'skip-source-not-exists',
+                sourcePath: sourceAsset.path,
+                targetPath,
+            });
             return { source: sourceAsset.source, files: { added: [], overwritten: [], skipped: [] } };
         }
         const repoRoot = this.findGitRootForPath(sourceAsset.path);
         if (!repoRoot) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                branch: 'fallback-fs-no-git-root',
+                sourcePath: sourceAsset.path,
+                targetPath,
+            });
             return this.copyClaudeDirectoryByFileSystem(sourceAsset, targetPath);
         }
         const canonicalRepoRoot = this.safeRealpath(repoRoot);
@@ -1008,13 +1114,38 @@ export class InitCommand {
             .join('/');
         if (relativeSourceDir.startsWith('..') ||
             path.isAbsolute(relativeSourceDir)) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                branch: 'fallback-fs-bad-relative',
+                canonicalRepoRoot,
+                canonicalSourcePath,
+                relativeSourceDir,
+                targetPath,
+            });
             return this.copyClaudeDirectoryByFileSystem(sourceAsset, targetPath);
         }
         const filesResult = this.copyGitTrackedDirectoryFiles(canonicalRepoRoot, relativeSourceDir, targetPath);
         const totalFiles = filesResult.added.length + filesResult.overwritten.length + filesResult.skipped.length;
         if (totalFiles === 0) {
+            this.logInitDebug({
+                scope: 'copyClaudeDirectoryIfNeeded',
+                branch: 'git-tracked-empty',
+                canonicalRepoRoot,
+                relativeSourceDir,
+                targetPath,
+            });
             return { source: sourceAsset.source, files: { added: [], overwritten: [], skipped: [] } };
         }
+        this.logInitDebug({
+            scope: 'copyClaudeDirectoryIfNeeded',
+            branch: 'git-tracked-ok',
+            canonicalRepoRoot,
+            relativeSourceDir,
+            targetPath,
+            added: filesResult.added.length,
+            overwritten: filesResult.overwritten.length,
+            skipped: filesResult.skipped.length,
+        });
         return {
             source: sourceAsset.source,
             files: filesResult,
@@ -1139,8 +1270,25 @@ export class InitCommand {
                 .map((line) => line.trim())
                 .filter((line) => line.length > 0);
             if (trackedFiles.length === 0) {
+                this.logInitDebug({
+                    scope: 'copyGitTrackedDirectoryFiles',
+                    result: 'empty-tracked-files',
+                    gitRoot,
+                    sourceDirRelativeToGitRoot,
+                    targetDir,
+                    rawOutputPreview: output.slice(0, 200),
+                });
                 return result;
             }
+            this.logInitDebug({
+                scope: 'copyGitTrackedDirectoryFiles',
+                result: 'tracked-files-loaded',
+                gitRoot,
+                sourceDirRelativeToGitRoot,
+                targetDir,
+                trackedCount: trackedFiles.length,
+                sample: trackedFiles.slice(0, 5),
+            });
             // 确保目标目录存在，但不删除已有内容
             mkdirSync(targetDir, { recursive: true });
             trackedFiles.forEach((repoFilePath) => {
@@ -1178,7 +1326,17 @@ export class InitCommand {
             });
             return result;
         }
-        catch {
+        catch (err) {
+            this.logInitDebug({
+                scope: 'copyGitTrackedDirectoryFiles',
+                result: 'exception',
+                gitRoot,
+                sourceDirRelativeToGitRoot,
+                targetDir,
+                errorMessage: err?.message ?? String(err),
+                stderr: err?.stderr ? String(err.stderr).slice(0, 500) : undefined,
+                status: err?.status,
+            });
             return result;
         }
     }