@zhuan-ai/zhuanspec 2.6.0 → 2.8.0

package/dist/core/hooks/record-progress.d.ts

@@ -8,13 +8,27 @@
  */
 import { Phase } from '../../utils/phase-utils.js';
 /**
- * Get Beijing time (UTC+8) as ISO string format
- * Returns format: "2026-04-19T18:35:22.934+08:00"
+ * Atomic write JSON file: write to temp file first, then rename
+ * This prevents half-written files during crashes or concurrent writes
+ * @param filePath - Target file path
+ * @param data - Data to write (will be JSON stringified)
+ */
+export declare function atomicWriteJson(filePath: string, data: unknown): Promise<void>;
+/**
+ * Recover damaged progress.json for write operations
+ * Uses same three-tier strategy as read side
+ * @param filePath - Path to progress.json
+ * @returns Recovered ProgressData or null
+ */
+export declare function recoverProgressJsonForWrite(filePath: string): Promise<ProgressData | null>;
+/**
+ * Get Beijing time (UTC+8) as display format
+ * Returns format: "2026-04-21 18:35:22" (北京时间)
  */
 export declare function getBeijingTime(): string;
 /**
  * Get Beijing time date string for session ID and filenames
- * Returns format: "2026-04-19T18-35-22"
+ * Returns format: "2026-04-21 18-35-22" (文件名安全格式)
  */
 export declare function getBeijingTimeForFilename(): string;
 interface RecordProgressOptions {
@@ -23,6 +37,156 @@ interface RecordProgressOptions {
     tool?: string;
     success?: string;
 }
+interface ToolCallRecord {
+    callId: string;
+    tool: string;
+    input: {
+        file_path?: string;
+        content?: string;
+        pattern?: string;
+        path?: string;
+        command?: string;
+        skill?: string;
+        args?: string;
+        agent_type?: string;
+        mcp_server?: string;
+        mcp_tool?: string;
+    };
+    output: {
+        success: boolean;
+        lines?: number;
+        matches?: number;
+        exit_code?: number;
+        result?: string;
+    };
+    timestamp: string;
+    durationMs?: number;
+    phase: string;
+    taskId?: string;
+}
+interface DeviationRecord {
+    deviationId: string;
+    detectedAt: string;
+    triggerType: 'task-complete' | 'phase-complete' | 'user-input';
+    userInput?: string;
+    specChanged: string[];
+    codeChanged: string[];
+    resolvedAt?: string;
+}
+interface ReviewStats {
+    loopCount: number;
+    criticalFixes: number;
+    testFixes: number;
+    consistencyFixes: number;
+}
+interface PhaseTransition {
+    from: string;
+    to: string;
+    timestamp: string;
+    triggeredBy: string;
+}
+/**
+ * Skill 调用记录
+ */
+interface SkillCallRecord {
+    callId: string;
+    skill: string;
+    args?: string;
+    description?: string;
+    triggeredAt: string;
+    phase: string;
+    durationMs?: number;
+    success: boolean;
+    outputSummary?: string;
+}
+/**
+ * Hook 触发记录
+ */
+interface HookTriggerRecord {
+    hookId: string;
+    hookName: string;
+    hookPhase: string;
+    triggeredAt: string;
+    phase: string;
+    toolName?: string;
+    filePath?: string;
+    success: boolean;
+    durationMs?: number;
+    message?: string;
+}
+/**
+ * 咨询问题记录 (AskQuestion)
+ */
+interface ClarificationRecord {
+    clarificationId: string;
+    questions: Array<{
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect: boolean;
+    }>;
+    answers: Record<string, string>;
+    annotations?: Record<string, {
+        notes?: string;
+        preview?: string;
+    }>;
+    askedAt: string;
+    answeredAt?: string;
+    phase: string;
+    context?: string;
+}
+/**
+ * Phase duration record for tracking time spent in each phase
+ */
+export interface PhaseDurationRecord {
+    phase: Phase;
+    startedAt: string;
+    endedAt?: string;
+    durationMs: number;
+    taskCount: number;
+    completedTaskCount: number;
+}
+export interface ProgressData {
+    changeId: string;
+    sessionId: string;
+    startedAt: string;
+    lastUpdatedAt: string;
+    phase: string;
+    currentNode: string;
+    currentTask: string;
+    completedTasks: string[];
+    totalTasks: number;
+    toolCalls: ToolCallRecord[];
+    skillCalls: SkillCallRecord[];
+    hookTriggers: HookTriggerRecord[];
+    clarifications: ClarificationRecord[];
+    filesModified: string[];
+    linesAdded: number;
+    linesRemoved: number;
+    deviationCount: number;
+    deviationRecords: DeviationRecord[];
+    reviewStats: ReviewStats;
+    phaseTransitions: PhaseTransition[];
+    phaseDurations: PhaseDurationRecord[];
+    stats: {
+        tokenUsageTotal: number;
+        contextLoad: number;
+        durationMs: {
+            propose: number;
+            apply: number;
+            review: number;
+            archive: number;
+        };
+    };
+    events?: Array<{
+        event: string;
+        timestamp: string;
+    }>;
+    lastEvent?: string;
+}
 export declare function recordProgressHook(options: RecordProgressOptions): Promise<void>;
 /**
  * Initialize progress.json at phase start

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

@@ -17,7 +17,7 @@ const fs = fsPromises;
  * @param filePath - Target file path
  * @param data - Data to write (will be JSON stringified)
  */
-async function atomicWriteJson(filePath, data) {
+export async function atomicWriteJson(filePath, data) {
     const tmpPath = `${filePath}.tmp`;
     const content = JSON.stringify(data, null, 2);
     try {
@@ -43,7 +43,7 @@ async function atomicWriteJson(filePath, data) {
  * @param filePath - Path to progress.json
  * @returns Recovered ProgressData or null
  */
-async function recoverProgressJsonForWrite(filePath) {
+export async function recoverProgressJsonForWrite(filePath) {
     try {
         const content = await FileSystemUtils.readFile(filePath);
         // Layer 1: Standard JSON parse
@@ -83,13 +83,14 @@ async function recoverProgressJsonForWrite(filePath) {
         const changeIdMatch = content.match(/"changeId"\s*:\s*"([^"]+)"/);
         const sessionIdMatch = content.match(/"sessionId"\s*:\s*"([^"]+)"/);
         if (phaseMatch || changeIdMatch) {
+            const recoveredPhase = phaseMatch?.[1] || 'unknown';
             return {
                 changeId: changeIdMatch?.[1] || '',
                 sessionId: sessionIdMatch?.[1] || '',
                 startedAt: '',
                 lastUpdatedAt: '',
-                phase: phaseMatch?.[1] || 'unknown',
-                currentNode: phaseMatch?.[1] || 'unknown',
+                phase: recoveredPhase,
+                currentNode: recoveredPhase,
                 currentTask: '',
                 completedTasks: [],
                 totalTasks: 0,
@@ -104,6 +105,13 @@ async function recoverProgressJsonForWrite(filePath) {
                 deviationRecords: [],
                 reviewStats: { loopCount: 0, criticalFixes: 0, testFixes: 0, consistencyFixes: 0 },
                 phaseTransitions: [],
+                phaseDurations: [{
+                        phase: recoveredPhase,
+                        startedAt: '',
+                        durationMs: 0,
+                        taskCount: 0,
+                        completedTaskCount: 0,
+                    }],
                 stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { propose: 0, apply: 0, review: 0, archive: 0 } },
             };
         }
@@ -114,8 +122,8 @@ async function recoverProgressJsonForWrite(filePath) {
     return null;
 }
 /**
- * Get Beijing time (UTC+8) as ISO string format
- * Returns format: "2026-04-19T18:35:22.934+08:00"
+ * Get Beijing time (UTC+8) as display format
+ * Returns format: "2026-04-21 18:35:22" (北京时间)
  */
 export function getBeijingTime() {
     const now = new Date();
@@ -123,19 +131,18 @@ export function getBeijingTime() {
     const utcMs = now.getTime() + now.getTimezoneOffset() * 60 * 1000;
     const beijingMs = utcMs + 8 * 60 * 60 * 1000;
     const beijingTime = new Date(beijingMs);
-    // Format as ISO string with +08:00 timezone
+    // Format: yyyy-MM-dd hh:mm:ss
     const year = beijingTime.getFullYear();
     const month = String(beijingTime.getMonth() + 1).padStart(2, '0');
     const day = String(beijingTime.getDate()).padStart(2, '0');
     const hours = String(beijingTime.getHours()).padStart(2, '0');
     const minutes = String(beijingTime.getMinutes()).padStart(2, '0');
     const seconds = String(beijingTime.getSeconds()).padStart(2, '0');
-    const ms = String(beijingTime.getMilliseconds()).padStart(3, '0');
-    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${ms}+08:00`;
+    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
 }
 /**
  * Get Beijing time date string for session ID and filenames
- * Returns format: "2026-04-19T18-35-22"
+ * Returns format: "2026-04-21 18-35-22" (文件名安全格式)
  */
 export function getBeijingTimeForFilename() {
     const now = new Date();
@@ -149,7 +156,7 @@ export function getBeijingTimeForFilename() {
     const hours = String(beijingTime.getHours()).padStart(2, '0');
     const minutes = String(beijingTime.getMinutes()).padStart(2, '0');
     const seconds = String(beijingTime.getSeconds()).padStart(2, '0');
-    return `${year}-${month}-${day}T${hours}-${minutes}-${seconds}`;
+    return `${year}-${month}-${day} ${hours}-${minutes}-${seconds}`;
 }
 export async function recordProgressHook(options) {
     // Read stdin for Claude Code hook input
@@ -277,6 +284,7 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
                 consistencyFixes: 0,
             };
             progress.phaseTransitions = progress.phaseTransitions || [];
+            progress.phaseDurations = progress.phaseDurations || [];
             progress.stats = progress.stats || {
                 tokenUsageTotal: 0,
                 contextLoad: 0,
@@ -375,8 +383,14 @@ async function runRecordProgress(filePath, toolName, success, stdinData) {
     progress.currentNode = process.env.ZHUANSPEC_CURRENT_NODE || phase;
     progress.currentTask = currentTask || progress.currentTask;
     progress.toolCalls.push(toolCall);
-    if (filePath && !progress.filesModified.includes(filePath)) {
-        progress.filesModified.push(filePath);
+    const WRITE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit']);
+    if (filePath && WRITE_TOOLS.has(toolName) && !progress.filesModified.includes(filePath)) {
+        // Exclude ZhuanSpec internal files (spec/metrics/doc files inside zhuanspec/ dir)
+        const absFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+        const zhuanspecDirPrefix = path.resolve(process.cwd(), 'zhuanspec') + path.sep;
+        if (!absFilePath.startsWith(zhuanspecDirPrefix)) {
+            progress.filesModified.push(filePath);
+        }
     }
     // Try to estimate lines from content
     const content = stdinData.tool_input?.content;
@@ -486,13 +500,14 @@ function generateProgressBar(percentage, blocks) {
 }
 function createNewProgress(changeId) {
     const sessionId = `sess-${getBeijingTimeForFilename()}`;
+    const initialPhase = process.env.ZHUANSPEC_PHASE || 'idle';
     return {
         changeId,
         sessionId,
         startedAt: getBeijingTime(),
         lastUpdatedAt: getBeijingTime(),
-        phase: process.env.ZHUANSPEC_PHASE || 'idle',
-        currentNode: process.env.ZHUANSPEC_CURRENT_NODE || process.env.ZHUANSPEC_PHASE || 'idle',
+        phase: initialPhase,
+        currentNode: process.env.ZHUANSPEC_CURRENT_NODE || initialPhase,
         currentTask: '',
         completedTasks: [],
         totalTasks: 0,
@@ -512,6 +527,13 @@ function createNewProgress(changeId) {
             consistencyFixes: 0,
         },
         phaseTransitions: [],
+        phaseDurations: [{
+                phase: initialPhase,
+                startedAt: getBeijingTime(),
+                durationMs: 0,
+                taskCount: 0,
+                completedTaskCount: 0,
+            }],
         stats: {
             tokenUsageTotal: 0,
             contextLoad: 0,
@@ -538,12 +560,60 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
     // Ensure metrics directory exists
     await FileSystemUtils.createDirectory(metricsDir);
     const progressPath = path.join(metricsDir, 'progress.json');
+    const timestamp = getBeijingTime();
     // Create or update progress file (with recovery support)
     let progress;
     if (await FileSystemUtils.fileExists(progressPath)) {
         const recovered = await recoverProgressJsonForWrite(progressPath);
         if (recovered) {
             progress = recovered;
+            // Fill missing fields with defaults
+            progress.toolCalls = progress.toolCalls || [];
+            progress.skillCalls = progress.skillCalls || [];
+            progress.hookTriggers = progress.hookTriggers || [];
+            progress.clarifications = progress.clarifications || [];
+            progress.filesModified = progress.filesModified || [];
+            progress.completedTasks = progress.completedTasks || [];
+            progress.deviationRecords = progress.deviationRecords || [];
+            progress.phaseTransitions = progress.phaseTransitions || [];
+            progress.phaseDurations = progress.phaseDurations || [];
+            progress.reviewStats = progress.reviewStats || {
+                loopCount: 0,
+                criticalFixes: 0,
+                testFixes: 0,
+                consistencyFixes: 0,
+            };
+            progress.stats = progress.stats || {
+                tokenUsageTotal: 0,
+                contextLoad: 0,
+                durationMs: { propose: 0, apply: 0, review: 0, archive: 0 },
+            };
+            const previousPhase = progress.phase;
+            if (previousPhase !== initialPhase) {
+                // Record phase transition
+                progress.phaseTransitions.push({
+                    from: previousPhase,
+                    to: initialPhase,
+                    timestamp,
+                    triggeredBy: 'initializeProgress',
+                });
+                // Update previous phase duration
+                const prevPhaseDuration = progress.phaseDurations.find(pd => pd.phase === previousPhase && !pd.endedAt);
+                if (prevPhaseDuration) {
+                    prevPhaseDuration.endedAt = timestamp;
+                    const startTime = new Date(prevPhaseDuration.startedAt).getTime();
+                    const endTime = new Date(timestamp).getTime();
+                    prevPhaseDuration.durationMs = endTime > startTime ? endTime - startTime : 0;
+                }
+                // Add new phase duration
+                progress.phaseDurations.push({
+                    phase: initialPhase,
+                    startedAt: timestamp,
+                    durationMs: 0,
+                    taskCount: 0,
+                    completedTaskCount: 0,
+                });
+            }
             progress.phase = initialPhase;
             progress.currentNode = initialPhase;
         }
@@ -558,7 +628,7 @@ export async function initializeProgress(changeId, initialPhase = 'propose') {
         progress.phase = initialPhase;
         progress.currentNode = initialPhase;
     }
-    progress.lastUpdatedAt = getBeijingTime();
+    progress.lastUpdatedAt = timestamp;
     await atomicWriteJson(progressPath, progress);
 }
 /**

package/dist/core/hooks/summarize.js

@@ -227,6 +227,7 @@ function parseTasks(content) {
     const tasks = [];
     const lines = content.split('\n');
     let currentWave = 0;
+    let autoId = 0;
     for (const line of lines) {
         // Match wave headers: ### Wave 1, ### Wave 2, etc.
         const waveMatch = line.match(/^###\s*Wave\s*(\d+)/i);
@@ -234,17 +235,35 @@ function parseTasks(content) {
             currentWave = parseInt(waveMatch[1], 10);
             continue;
         }
-        // Match task lines: - [ ] X.Y description or - [x] X.Y description
-        const taskMatch = line.match(/^-\s*\[([x ])\]\s*(\d+\.\d+)\s*(.+)/);
-        if (taskMatch) {
-            const statusChar = taskMatch[1];
-            const taskId = taskMatch[2];
-            tasks.push({
-                taskId,
-                status: statusChar === 'x' ? 'completed' : 'pending',
-                wave: currentWave,
-            });
+        // Match any checkbox line: - [ ] ... or - [x] ...
+        const checkboxMatch = line.match(/^-\s*\[([x ])\]\s*(.+)/);
+        if (!checkboxMatch)
+            continue;
+        const statusChar = checkboxMatch[1];
+        const rest = checkboxMatch[2].trim();
+        // Skip review gate lines (legacy tasks.md files)
+        if (rest.includes('zhuanspec review') || rest.includes('审查门禁'))
+            continue;
+        // Extract task ID from multiple formats:
+        // Format 1: "1.1 description" or "1.1: description"
+        const numericIdMatch = rest.match(/^(\d+\.\d+)[:\s]/);
+        // Format 2: "T1: description" or "T1 description"
+        const tPrefixIdMatch = rest.match(/^(T\d+)[:\s]/i);
+        let taskId;
+        if (numericIdMatch) {
+            taskId = numericIdMatch[1];
+        }
+        else if (tPrefixIdMatch) {
+            taskId = tPrefixIdMatch[1].toUpperCase();
+        }
+        else {
+            taskId = `task-${++autoId}`;
         }
+        tasks.push({
+            taskId,
+            status: statusChar === 'x' ? 'completed' : 'pending',
+            wave: currentWave,
+        });
     }
     return tasks;
 }