@zhuan-ai/zhuanspec 2.16.2 → 2.16.4

package/dist/core/validation/report-schema.js

@@ -0,0 +1,254 @@
+/**
+ * Apply 阶段任务报告 schema 校验。
+ *
+ * 背景：编排 Agent 在长任务尾部容易"指令衰减"，跳过 Agent tool / spawn_agent
+ * 的 subagent 调用，自己在主线程顺手把任务做掉再补一份偷工的报告。这种偷工
+ * 报告会缺失 tdd-apply-agent.md / apply-agent.md 模板里强制的章节
+ * （TDD Phase / Verify RED / Verify GREEN / Mock Gate / Skill 调用记录 ...）。
+ *
+ * 本模块对 `zhuanspec/changes/<id>/reports/task-*.md` 做轻量结构校验：
+ * - 必备公共字段：`## 状态报告` / Status / Task ID / Report File / Agent 选择决策 / Agent 类型
+ * - 当 Agent 类型 = `tddApplyAgent`：再校验 TDD Phase / 上下文就绪摘要 /
+ *   验收点映射表 / TDD 执行过程（Verify RED + Verify GREEN）/ 测试运行结果 /
+ *   Self-Review 发现 / Issues
+ * - 当 Agent 类型 = `applyAgent`：校验实施内容 / 修改文件 / Self-Review 发现 / Issues
+ *
+ * 与 tasks.md 交叉对账：若任务在 tasks.md 里带 `@test-case:TC-XXX`，则该任务的
+ * 报告原则上必须由 `tddApplyAgent` 产出（除非报告里显式声明降级原因，对应
+ * apply-agent.md 中的"降级使用 applyAgent"路径）。
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+/** Common required fields for ANY task report (applyAgent or tddApplyAgent). */
+const COMMON_REQUIRED = [
+    '## 状态报告',
+    'Status',
+    'Task ID',
+    'Report File',
+    '### Agent 选择决策',
+    'Agent 类型',
+];
+/** Additional required sections when declaredAgentType === 'tddApplyAgent'. */
+const TDD_REQUIRED = [
+    'Wave',
+    'Execution Mode',
+    'TDD Phase',
+    '### 上下文就绪摘要',
+    '### Skill 调用记录',
+    '### 验收点映射表',
+    '### TDD 执行过程',
+    '#### Verify RED',
+    '#### Verify GREEN',
+    '#### Mock Gate',
+    '### 测试内容',
+    '### 测试运行结果',
+    '### Self-Review 发现',
+    '### Issues/Concerns',
+];
+/** Additional required sections when declaredAgentType === 'applyAgent'. */
+const APPLY_REQUIRED = [
+    '### 实施内容',
+    '### 修改文件',
+    '### Self-Review 发现',
+    '### Issues/Concerns',
+];
+const TASK_REPORT_FILE_RE = /^task-(\d+\.\d+(?:[a-z])?)-report\.md$/i;
+const AGENT_TYPE_LINE_RE = /\*\*Agent\s+类型\*\*\s*[:：]\s*([A-Za-z]+)/;
+const TASK_LINE_RE = /^-\s+\[[ xX]\]\s+(\d+\.\d+)\s+/;
+/**
+ * Inspect a single report file. Pure string-level checks — no side effects.
+ *
+ * @param taskId  The task id (derived from filename).
+ * @param content The raw markdown content of the report file.
+ * @param expected The agent type expected from tasks.md (default 'unknown').
+ */
+export function checkReportContent(taskId, filePath, content, expected) {
+    const declaredAgentType = detectAgentType(content);
+    const hasDowngradeJustification = /降级|不适合\s*TDD|TDD\s*适用性\s*[:：]\s*不适合/.test(content);
+    const missing = [];
+    const issues = [];
+    // 1) Common required fields/sections.
+    for (const token of COMMON_REQUIRED) {
+        if (!content.includes(token))
+            missing.push(token);
+    }
+    // 2) Type-specific required sections.
+    const typeRequired = declaredAgentType === 'tddApplyAgent'
+        ? TDD_REQUIRED
+        : declaredAgentType === 'applyAgent'
+            ? APPLY_REQUIRED
+            : [];
+    for (const token of typeRequired) {
+        if (!content.includes(token))
+            missing.push(token);
+    }
+    // 3) Aggregate ERROR-level issues from missing sections.
+    if (missing.length > 0) {
+        issues.push({
+            level: 'ERROR',
+            taskId,
+            message: `报告缺失必需章节/字段：${missing.join(', ')}`,
+        });
+    }
+    // 4) Cross-check against expected agent type.
+    if (expected === 'tddApplyAgent' &&
+        declaredAgentType === 'applyAgent' &&
+        !hasDowngradeJustification) {
+        issues.push({
+            level: 'ERROR',
+            taskId,
+            message: 'tasks.md 标注 @test-case 应使用 tddApplyAgent；报告声明 applyAgent 但未给出降级理由（"TDD 适用性: 不适合(...)"）',
+        });
+    }
+    if (declaredAgentType === 'unknown') {
+        issues.push({
+            level: 'ERROR',
+            taskId,
+            message: '报告未声明 Agent 类型（缺失 "Agent 类型: applyAgent | tddApplyAgent"）',
+        });
+    }
+    // 5) Heuristic: tddApplyAgent must show real test command output evidence.
+    if (declaredAgentType === 'tddApplyAgent') {
+        const hasTestEvidence = /mvn\s+test|npm\s+(?:test|run\s+test)|pnpm\s+test|yarn\s+test|gradle\s+test|vitest|jest/i.test(content);
+        if (!hasTestEvidence) {
+            issues.push({
+                level: 'ERROR',
+                taskId,
+                message: 'tddApplyAgent 报告缺少测试运行证据（未发现 mvn test / npm test / vitest / jest 等命令痕迹）',
+            });
+        }
+    }
+    const valid = issues.every((issue) => issue.level !== 'ERROR');
+    return {
+        taskId,
+        filePath,
+        declaredAgentType,
+        expectedAgentType: expected,
+        hasDowngradeJustification,
+        missing,
+        issues,
+        valid,
+    };
+}
+/**
+ * Validate all task reports under `<changeDir>/reports/`.
+ * Cross-checks against `<changeDir>/tasks.md` to detect missing reports and
+ * agent-type mismatches.
+ */
+export async function validateTaskReports(changeDir) {
+    const changeId = path.basename(changeDir);
+    const reportsDir = path.join(changeDir, 'reports');
+    // Read tasks.md to figure out the expected task list and agent type per task.
+    const expectedByTaskId = await parseExpectedAgentTypes(path.join(changeDir, 'tasks.md'));
+    let entries = [];
+    try {
+        entries = await fs.readdir(reportsDir);
+    }
+    catch {
+        // No reports directory at all — report every expected task as missing.
+        return {
+            changeId,
+            reportsDir,
+            totalReports: 0,
+            passedReports: 0,
+            failedReports: 0,
+            missingReports: Array.from(expectedByTaskId.keys()),
+            reports: [],
+            valid: expectedByTaskId.size === 0,
+        };
+    }
+    const reportFiles = entries
+        .filter((e) => TASK_REPORT_FILE_RE.test(e))
+        .sort();
+    const seenTaskIds = new Set();
+    const results = [];
+    for (const file of reportFiles) {
+        const match = file.match(TASK_REPORT_FILE_RE);
+        if (!match)
+            continue;
+        const taskId = match[1];
+        seenTaskIds.add(taskId);
+        const filePath = path.join(reportsDir, file);
+        let content;
+        try {
+            content = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            results.push({
+                taskId,
+                filePath,
+                declaredAgentType: 'unknown',
+                expectedAgentType: expectedByTaskId.get(taskId) ?? 'unknown',
+                hasDowngradeJustification: false,
+                missing: ['<file unreadable>'],
+                issues: [
+                    {
+                        level: 'ERROR',
+                        taskId,
+                        message: '报告文件无法读取',
+                    },
+                ],
+                valid: false,
+            });
+            continue;
+        }
+        const expected = expectedByTaskId.get(taskId) ?? 'unknown';
+        results.push(checkReportContent(taskId, filePath, content, expected));
+    }
+    // Tasks declared in tasks.md but never produced a report.
+    const missingReports = [];
+    for (const taskId of expectedByTaskId.keys()) {
+        if (!seenTaskIds.has(taskId))
+            missingReports.push(taskId);
+    }
+    const passedReports = results.filter((r) => r.valid).length;
+    const failedReports = results.length - passedReports;
+    return {
+        changeId,
+        reportsDir,
+        totalReports: results.length,
+        passedReports,
+        failedReports,
+        missingReports,
+        reports: results,
+        valid: failedReports === 0 && missingReports.length === 0,
+    };
+}
+/** Detect declared agent type from a report's body. */
+function detectAgentType(content) {
+    const m = content.match(AGENT_TYPE_LINE_RE);
+    if (!m)
+        return 'unknown';
+    const v = m[1].trim();
+    if (v === 'tddApplyAgent')
+        return 'tddApplyAgent';
+    if (v === 'applyAgent')
+        return 'applyAgent';
+    return 'unknown';
+}
+/**
+ * Parse `tasks.md` to determine the expected agent type for each task.
+ * Tasks tagged with `@test-case:TC-XXX` are expected to use `tddApplyAgent`;
+ * everything else defaults to `applyAgent`.
+ */
+async function parseExpectedAgentTypes(tasksFile) {
+    const result = new Map();
+    let content;
+    try {
+        content = await fs.readFile(tasksFile, 'utf-8');
+    }
+    catch {
+        return result;
+    }
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+        const m = line.match(TASK_LINE_RE);
+        if (!m)
+            continue;
+        const taskId = m[1];
+        const hasTestCase = /@test-case\s*:/.test(line);
+        result.set(taskId, hasTestCase ? 'tddApplyAgent' : 'applyAgent');
+    }
+    return result;
+}
+//# sourceMappingURL=report-schema.js.map

package/dist/utils/line-diff.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 行级 diff 计算工具
+ *
+ * 用途：替代 record-progress.ts 中的 Math.max(newLines, oldLines)，
+ *      只统计真正发生变化的行数（增 + 删），不计入未修改的上下文锚点。
+ *
+ * 例：
+ *   old = "A\nB\nC\nD"
+ *   new = "A\nX\nC\nD"
+ *   max(4,4) = 4    ← 旧口径（含上下文）
+ *   diff     = 2    ← 新口径（B 删除 + X 新增）
+ *
+ * 算法：基于 LCS（Longest Common Subsequence）的行级最小编辑距离。
+ *      对小规模编辑（< 1000 行）足够快，且无外部依赖。
+ */
+/**
+ * 计算两段文本的行级净改动行数（添加行数 + 删除行数）。
+ *
+ * - 仅有 oldText：纯删除，返回旧文本行数
+ * - 仅有 newText：纯新增，返回新文本行数
+ * - 两者都有：基于 LCS 的最小编辑距离
+ *
+ * 注意：
+ * - 完全相同（无变化）返回 0
+ * - 修改一行 = 1 删 + 1 增 = 2
+ * - 与 unified diff 的 +/- 行数概念一致
+ *
+ * @param oldText 旧文本（Edit 的 old_string）
+ * @param newText 新文本（Edit 的 new_string）
+ * @returns 净改动行数（>= 0）
+ */
+export declare function countLineDiff(oldText: string | undefined | null, newText: string | undefined | null): number;
+//# sourceMappingURL=line-diff.d.ts.map

package/dist/utils/line-diff.js

@@ -0,0 +1,85 @@
+/**
+ * 行级 diff 计算工具
+ *
+ * 用途：替代 record-progress.ts 中的 Math.max(newLines, oldLines)，
+ *      只统计真正发生变化的行数（增 + 删），不计入未修改的上下文锚点。
+ *
+ * 例：
+ *   old = "A\nB\nC\nD"
+ *   new = "A\nX\nC\nD"
+ *   max(4,4) = 4    ← 旧口径（含上下文）
+ *   diff     = 2    ← 新口径（B 删除 + X 新增）
+ *
+ * 算法：基于 LCS（Longest Common Subsequence）的行级最小编辑距离。
+ *      对小规模编辑（< 1000 行）足够快，且无外部依赖。
+ */
+/**
+ * 计算两段文本的行级净改动行数（添加行数 + 删除行数）。
+ *
+ * - 仅有 oldText：纯删除，返回旧文本行数
+ * - 仅有 newText：纯新增，返回新文本行数
+ * - 两者都有：基于 LCS 的最小编辑距离
+ *
+ * 注意：
+ * - 完全相同（无变化）返回 0
+ * - 修改一行 = 1 删 + 1 增 = 2
+ * - 与 unified diff 的 +/- 行数概念一致
+ *
+ * @param oldText 旧文本（Edit 的 old_string）
+ * @param newText 新文本（Edit 的 new_string）
+ * @returns 净改动行数（>= 0）
+ */
+export function countLineDiff(oldText, newText) {
+    const oldStr = oldText ?? '';
+    const newStr = newText ?? '';
+    if (oldStr === newStr)
+        return 0;
+    if (!oldStr)
+        return newStr.split('\n').length;
+    if (!newStr)
+        return oldStr.split('\n').length;
+    const oldLines = oldStr.split('\n');
+    const newLines = newStr.split('\n');
+    const lcs = lcsLength(oldLines, newLines);
+    // 删除行数 = 旧行 - LCS；新增行数 = 新行 - LCS
+    return (oldLines.length - lcs) + (newLines.length - lcs);
+}
+/**
+ * 计算两个字符串数组的 LCS 长度（动态规划，O(n*m) 时间，O(min) 空间）。
+ *
+ * 内部辅助函数。使用滚动数组避免 O(n*m) 空间开销。
+ *
+ * @param a 数组 A（旧行）
+ * @param b 数组 B（新行）
+ * @returns 最长公共子序列长度
+ */
+function lcsLength(a, b) {
+    const n = a.length;
+    const m = b.length;
+    if (n === 0 || m === 0)
+        return 0;
+    // 让 b 作为短边，节省空间
+    const [shortArr, longArr] = m <= n ? [b, a] : [a, b];
+    const shortLen = shortArr.length;
+    const longLen = longArr.length;
+    // 滚动数组：prev / curr，长度 = shortLen + 1
+    let prev = new Array(shortLen + 1).fill(0);
+    let curr = new Array(shortLen + 1).fill(0);
+    for (let i = 1; i <= longLen; i++) {
+        for (let j = 1; j <= shortLen; j++) {
+            if (longArr[i - 1] === shortArr[j - 1]) {
+                curr[j] = prev[j - 1] + 1;
+            }
+            else {
+                curr[j] = Math.max(prev[j], curr[j - 1]);
+            }
+        }
+        // 滚动：把 curr 拷给 prev，curr 清零
+        const tmp = prev;
+        prev = curr;
+        curr = tmp;
+        curr.fill(0);
+    }
+    return prev[shortLen];
+}
+//# sourceMappingURL=line-diff.js.map

package/dist/utils/phase-utils.d.ts

@@ -9,6 +9,19 @@
  */
 export type Phase = 'idle' | 'techDesign' | 'propose' | 'apply' | 'review' | 'archive';
 export declare const PHASE_ORDER: Phase[];
+/**
+ * v2.16+：阶段“活跃耗时”计算的空闲阈值。
+ *
+ * 设计背景：原本 progress.json 中的 phaseDurations[].durationMs / stats.durationMs 都是
+ * 墙钟差，中断/午休/过夜/AskUserQuestion 长时间挂起都会被当成阶段耗时。
+ * 从 v2.16 起，相邻两次 record-progress 心跳间隔 < PHASE_IDLE_THRESHOLD_MS 才计入
+ * 活跃耗时（durationMs）；超过阈值的 gap 被归类为空闲，计入 idleMs / idleSegments，
+ * 不计入 durationMs。
+ *
+ * 30 分钟阈值是取舍结果：避免误伤正常的本地阅读 / 思考 / 短暂离开，只剔除
+ * 明显的长时间中断、过夜、确认久未响应等场景。
+ */
+export declare const PHASE_IDLE_THRESHOLD_MS: number;
 export declare const PHASE_MARKERS: Partial<Record<Phase, string>>;
 /**
  * Set phase in progress.json with full data preservation

package/dist/utils/phase-utils.js

@@ -9,8 +9,21 @@
  */
 import path from 'path';
 import { FileSystemUtils } from './file-system.js';
-import { recoverProgressJsonForWrite, getBeijingTime, atomicWriteJson, } from '../core/hooks/record-progress.js';
+import { recoverProgressJsonForWrite, getBeijingTime, atomicWriteJson, tickActivePhaseDuration, } from '../core/hooks/record-progress.js';
 export const PHASE_ORDER = ['idle', 'techDesign', 'propose', 'apply', 'review', 'archive'];
+/**
+ * v2.16+：阶段“活跃耗时”计算的空闲阈值。
+ *
+ * 设计背景：原本 progress.json 中的 phaseDurations[].durationMs / stats.durationMs 都是
+ * 墙钟差，中断/午休/过夜/AskUserQuestion 长时间挂起都会被当成阶段耗时。
+ * 从 v2.16 起，相邻两次 record-progress 心跳间隔 < PHASE_IDLE_THRESHOLD_MS 才计入
+ * 活跃耗时（durationMs）；超过阈值的 gap 被归类为空闲，计入 idleMs / idleSegments，
+ * 不计入 durationMs。
+ *
+ * 30 分钟阈值是取舍结果：避免误伤正常的本地阅读 / 思考 / 短暂离开，只剔除
+ * 明显的长时间中断、过夜、确认久未响应等场景。
+ */
+export const PHASE_IDLE_THRESHOLD_MS = 30 * 60 * 1000;
 export const PHASE_MARKERS = {
     techDesign: '.tech-design',
     apply: '.approved',
@@ -83,6 +96,10 @@ export async function setPhase(changeDir, phase) {
                         durationMs: 0,
                         taskCount: 0,
                         completedTaskCount: 0,
+                        wallClockMs: 0,
+                        idleMs: 0,
+                        lastActiveAt: timestamp,
+                        _lastActiveEpoch: Date.now(),
                     }],
                 proposalChanges: [],
                 stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { techDesign: 0, propose: 0, apply: 0, review: 0, archive: 0 } },
@@ -119,6 +136,10 @@ export async function setPhase(changeDir, phase) {
                     durationMs: 0,
                     taskCount: 0,
                     completedTaskCount: 0,
+                    wallClockMs: 0,
+                    idleMs: 0,
+                    lastActiveAt: timestamp,
+                    _lastActiveEpoch: Date.now(),
                 }],
             proposalChanges: [],
             stats: { tokenUsageTotal: 0, contextLoad: 0, durationMs: { techDesign: 0, propose: 0, apply: 0, review: 0, archive: 0 } },
@@ -135,6 +156,10 @@ export async function setPhase(changeDir, phase) {
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,
+            wallClockMs: 0,
+            idleMs: 0,
+            lastActiveAt: timestamp,
+            _lastActiveEpoch: Date.now(),
         });
     }
     if (previousPhase !== phase) {
@@ -144,14 +169,13 @@ export async function setPhase(changeDir, phase) {
             timestamp,
             triggeredBy: 'setPhase',
         });
-        // Update phaseDurations: fill endedAt for previous phase
+        // Update phaseDurations: close previous phase with tick
         const prevPhaseDuration = progress.phaseDurations.find(pd => pd.phase === previousPhase && !pd.endedAt);
         if (prevPhaseDuration) {
+            // 封段前 tick 一次，确保最后一段活跃时间被累加
+            const nowEpoch = Date.now();
+            tickActivePhaseDuration(prevPhaseDuration, nowEpoch, timestamp);
             prevPhaseDuration.endedAt = timestamp;
-            prevPhaseDuration.lastUpdatedAt = 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 record
         progress.phaseDurations.push({
@@ -161,6 +185,10 @@ export async function setPhase(changeDir, phase) {
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,
+            wallClockMs: 0,
+            idleMs: 0,
+            lastActiveAt: timestamp,
+            _lastActiveEpoch: Date.now(),
         });
     }
     progress.phase = phase;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.16.2",
+  "version": "2.16.4",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -39,26 +39,6 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/zhuanspec.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/postinstall.js",
-    "check:pack-version": "node scripts/pack-version-check.mjs",
-    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
-    "release": "pnpm run release:ci",
-    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
-    "changeset": "changeset"
-  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -80,5 +60,23 @@
     "ora": "^8.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhuanspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
   }
-}
+}