@zhuan-ai/zhuanspec 2.16.0 → 2.16.3

package/dist/core/corrections/select-candidates.js

@@ -0,0 +1,357 @@
+/**
+ * Pending corrections candidate selection.
+ *
+ * 责任：把 `zhuanspec/changes/<id>/metrics/user_inputs.json` 里的纠偏 prompt 加工成
+ * "可读、去毛刺、去重、带建议分类" 的候选清单，给 review 阶段的踩坑沉淀决策使用。
+ *
+ * 不写文件、不改 progress.json，只做"读 + 计算 + 返回结构"。
+ */
+import path from 'path';
+import { promises as fs } from 'fs';
+import { USER_CORRECTION_KEYWORDS, REQUIREMENT_CHANGE_KEYWORDS, PITFALL_KEYWORDS, BEST_PRACTICE_KEYWORDS, IMPLICIT_CONVENTION_KEYWORDS, } from '../hooks/deviation-check.js';
+// ---------- Internals ----------
+/**
+ * 规范化字符串——用于过滤与去重的"语义指纹"。
+ * 1) 转小写（英文）
+ * 2) 把中英文标点 / 空白合并成单空格
+ * 3) trim
+ * 注意：保留中文字符本身（不做拼音/分词），只去标点和空白。
+ */
+function normalize(text) {
+    return text
+        .toLowerCase()
+        // 中英文标点 + 各类空白统一替换为空格
+        .replace(/[\s\p{P}\p{S}]+/gu, ' ')
+        .trim();
+}
+/** 纯确认/招呼类 prompt，不具备沉淀价值 */
+const TRIVIAL_ACK_SET = new Set([
+    '是', '是的', '好', '好的', '嗯', '嗯嗯', '对', '行', '可以', '确认',
+    '同意', '继续', '没问题', '明白', '了解', '知道了', '收到', '辛苦', '辛苦了',
+    'ok', 'okay', 'k', 'yes', 'y', 'yep', 'yeah', 'sure', 'fine', 'cool',
+    'go', 'go on', 'plan approved', 'continue', 'thanks', 'thx',
+]);
+/** 拟用文件名 slug 长度上限 */
+const SLUG_MAX_LEN = 48;
+function toKebabSlug(text) {
+    // 取规范化后的前若干字 → 把空格转 -，并去掉非字母数字中文
+    const base = normalize(text);
+    // 仅保留字母数字 / 中文 / 空格，再把空格转 -
+    const cleaned = base.replace(/[^a-z0-9\u4e00-\u9fa5\s]/g, '').replace(/\s+/g, '-');
+    return cleaned.slice(0, SLUG_MAX_LEN).replace(/^-+|-+$/g, '') || 'untitled';
+}
+function formatDate(ts) {
+    // user_inputs.timestamp 已经是北京时间字符串 "YYYY-MM-DD HH:mm:ss"
+    if (ts && /^\d{4}-\d{2}-\d{2}/.test(ts))
+        return ts.slice(0, 10).replace(/-/g, '');
+    const now = new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, '0');
+    const dd = String(now.getDate()).padStart(2, '0');
+    return `${yyyy}${mm}${dd}`;
+}
+function buildPreview(text, maxLen = 200) {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    if (oneLine.length <= maxLen)
+        return oneLine;
+    return oneLine.slice(0, maxLen - 1) + '…';
+}
+function detectKeywords(text) {
+    const lower = text.toLowerCase();
+    const hits = new Set();
+    for (const kw of USER_CORRECTION_KEYWORDS) {
+        if (lower.includes(kw.toLowerCase()))
+            hits.add(kw);
+    }
+    if (hits.size > 0) {
+        return { hits: Array.from(hits).slice(0, 6), isRequirementChange: false };
+    }
+    const reqHits = new Set();
+    for (const kw of REQUIREMENT_CHANGE_KEYWORDS) {
+        if (lower.includes(kw.toLowerCase()))
+            reqHits.add(kw);
+    }
+    if (reqHits.size > 0) {
+        return { hits: Array.from(reqHits).slice(0, 6), isRequirementChange: true };
+    }
+    return { hits: [], isRequirementChange: false };
+}
+const BEST_PRACTICE_HINTS = [
+    '后续', '之后都', '都要这么', '必须', '一律', '统一', '永远', '今后',
+    'always', 'going forward', 'from now on',
+];
+const TROUBLESHOOTING_HINTS = ['错了', '不对', '有问题', 'bug', 'wrong', 'incorrect'];
+function classifyCandidate(text, hits, isReqChange) {
+    const lower = text.toLowerCase();
+    // 1) 命中显式 PITFALL → troubleshooting
+    if (PITFALL_KEYWORDS.some((k) => lower.includes(k.toLowerCase())))
+        return 'troubleshooting';
+    // 2) 显式纠错动词 → troubleshooting（覆盖大多数纠偏 prompt）
+    if (TROUBLESHOOTING_HINTS.some((k) => lower.includes(k.toLowerCase())))
+        return 'troubleshooting';
+    // 3) 显式约定关键词
+    if (IMPLICIT_CONVENTION_KEYWORDS.some((k) => lower.includes(k.toLowerCase())))
+        return 'implicit-conventions';
+    // 4) 显式最佳实践 / 长期生效 hint
+    if (BEST_PRACTICE_KEYWORDS.some((k) => lower.includes(k.toLowerCase())))
+        return 'best-practices';
+    if (BEST_PRACTICE_HINTS.some((k) => lower.includes(k.toLowerCase())))
+        return 'best-practices';
+    // 5) 需求变更类 → 暂归 best-practices（"决策类输出归并到 best-practices/"）
+    if (isReqChange)
+        return 'best-practices';
+    // 6) 命中纠偏关键词但没显式陷阱词 → 默认踩坑
+    if (hits.length > 0)
+        return 'troubleshooting';
+    return 'troubleshooting';
+}
+function isTrivialAck(text) {
+    const norm = normalize(text);
+    if (norm.length === 0)
+        return true;
+    if (TRIVIAL_ACK_SET.has(norm))
+        return true;
+    // 仅由若干个字符 + 标点构成的极短 prompt（如 "好。"、"!!" 已被 normalize 干掉标点）
+    if (norm.length <= 2)
+        return true;
+    return false;
+}
+/**
+ * 从 user_inputs.json 抽取候选 raw entries。
+ * - Level 1: correctionSignal.kind === 'hard' && postBaseline === true
+ * - Level 2: 条目缺 correctionSignal → 用 summary 关键词扫描兜底
+ */
+async function loadRawEntries(cwd, changeId) {
+    const userInputsPath = path.join(cwd, 'zhuanspec', 'changes', changeId, 'metrics', 'user_inputs.json');
+    let raw;
+    try {
+        raw = await fs.readFile(userInputsPath, 'utf8');
+    }
+    catch {
+        return { entries: [], level: null, notice: `user_inputs.json 不存在或不可读：${userInputsPath}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { entries: [], level: null, notice: 'user_inputs.json 解析失败（JSON 损坏），请人工检查。' };
+    }
+    const inputs = Array.isArray(parsed.inputs) ? parsed.inputs : [];
+    if (inputs.length === 0)
+        return { entries: [], level: null };
+    const hasSignal = inputs.some((i) => i && typeof i === 'object' && 'correctionSignal' in i);
+    const level = hasSignal ? 1 : 2;
+    const out = [];
+    for (const entry of inputs) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const inputId = entry['inputId'] || undefined;
+        const timestamp = entry['timestamp'] || undefined;
+        const phase = entry['phase'] || undefined;
+        const fullPrompt = entry['fullPrompt'] || '';
+        const summary = entry['summary'] || '';
+        const text = (fullPrompt || summary || '').toString();
+        if (level === 1) {
+            const sig = entry['correctionSignal'];
+            const postBaseline = entry['postBaseline'] === true;
+            if (!sig || sig.kind !== 'hard' || !postBaseline)
+                continue;
+            out.push({
+                inputId,
+                timestamp,
+                phase,
+                text,
+                fromLevel: 1,
+                signalKeywords: Array.isArray(sig.matchedKeywords) ? sig.matchedKeywords : [],
+                isRequirementChange: sig.isRequirementChange === true,
+            });
+        }
+        else {
+            // Level 2: 用 summary 推断
+            const lower = (summary || text).toLowerCase();
+            const hitCorrection = USER_CORRECTION_KEYWORDS.some((k) => lower.includes(k.toLowerCase()));
+            const hitReq = REQUIREMENT_CHANGE_KEYWORDS.some((k) => lower.includes(k.toLowerCase()));
+            if (!hitCorrection && !hitReq)
+                continue;
+            out.push({ inputId, timestamp, phase, text, fromLevel: 2, isRequirementChange: hitReq && !hitCorrection });
+        }
+    }
+    return { entries: out, level };
+}
+// ---------- Public API ----------
+/**
+ * 从 change 目录抽取并加工纠偏候选。
+ */
+export async function selectCorrectionCandidates(cwd, changeId) {
+    const { entries, level, notice } = await loadRawEntries(cwd, changeId);
+    const totalRaw = entries.length;
+    const accepted = [];
+    const dropped = [];
+    // 已接受候选的 normalized 文本，用于做"完全相等 / 子串包含"去重
+    const acceptedNormalized = [];
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        const rawIndex = i + 1;
+        const preview = buildPreview(e.text || '');
+        // Step 1: 空内容
+        if (!e.text || e.text.trim().length === 0) {
+            dropped.push({ rawIndex, inputId: e.inputId, timestamp: e.timestamp, reason: 'empty', preview });
+            continue;
+        }
+        // Step 2: trivial 确认
+        if (isTrivialAck(e.text)) {
+            dropped.push({ rawIndex, inputId: e.inputId, timestamp: e.timestamp, reason: 'trivial-acknowledgement', preview });
+            continue;
+        }
+        // Step 3: 关键词命中 + 长度兜底
+        const { hits: detectedHits, isRequirementChange: detectedReq } = detectKeywords(e.text);
+        const matchedKeywords = e.signalKeywords && e.signalKeywords.length > 0 ? e.signalKeywords : detectedHits;
+        const isReqChange = e.isRequirementChange ?? detectedReq;
+        const norm = normalize(e.text);
+        if (norm.length < 6 && matchedKeywords.length === 0) {
+            dropped.push({ rawIndex, inputId: e.inputId, timestamp: e.timestamp, reason: 'too-short-no-keyword', preview });
+            continue;
+        }
+        // Step 4: 去重——完全相等 或 子串包含（短的被吸收）
+        let dupRefIdx;
+        let dupReason;
+        for (const prev of acceptedNormalized) {
+            if (prev.norm === norm) {
+                dupRefIdx = prev.idx;
+                dupReason = 'duplicate-of';
+                break;
+            }
+            // 子串包含：当前是已接受的真子串（且当前更短至少 4 字）
+            if (norm.length >= 4 && prev.norm.includes(norm) && norm.length < prev.norm.length) {
+                dupRefIdx = prev.idx;
+                dupReason = 'subset-of';
+                break;
+            }
+            // 反向：当前比已接受的长，且包含已接受 → 替换语义；保守处理：仅在长包含短时把短的标记为 subset。
+            // 不修改已接受集，避免编号漂移。
+        }
+        if (dupRefIdx && dupReason) {
+            dropped.push({
+                rawIndex,
+                inputId: e.inputId,
+                timestamp: e.timestamp,
+                reason: dupReason,
+                refIndex: dupRefIdx,
+                preview,
+            });
+            continue;
+        }
+        // Step 5: 收编为有效候选
+        const idx = accepted.length + 1;
+        const suggestedCategory = classifyCandidate(e.text, matchedKeywords, isReqChange);
+        const slug = toKebabSlug(e.text);
+        const suggestedFilename = `${formatDate(e.timestamp)}-${slug}.md`;
+        accepted.push({
+            index: idx,
+            inputId: e.inputId,
+            timestamp: e.timestamp,
+            phase: e.phase,
+            text: e.text,
+            preview,
+            matchedKeywords,
+            isRequirementChange: isReqChange,
+            suggestedCategory,
+            suggestedFilename,
+        });
+        acceptedNormalized.push({ idx, norm });
+    }
+    return { changeId, level, totalRaw, candidates: accepted, dropped, notice };
+}
+/**
+ * 把候选结果渲染成 markdown，用于落到 review/pending-corrections.md。
+ */
+export function renderPendingCorrectionsMarkdown(result) {
+    const { changeId, level, totalRaw, candidates, dropped, notice } = result;
+    const droppedByReason = {
+        trivial: dropped.filter((d) => d.reason === 'trivial-acknowledgement').length,
+        empty: dropped.filter((d) => d.reason === 'empty').length,
+        short: dropped.filter((d) => d.reason === 'too-short-no-keyword').length,
+        duplicate: dropped.filter((d) => d.reason === 'duplicate-of' || d.reason === 'subset-of').length,
+    };
+    const lines = [];
+    lines.push(`# Pending Corrections — ${changeId}`);
+    lines.push('');
+    lines.push(`> 由 \`zhuanspec progress list-corrections\` 生成。review 阶段「踩坑沉淀」请基于此清单做选择性沉淀决策，禁止靠最近 N 条做盲选。`);
+    lines.push('');
+    lines.push(`- **数据源**: ${level === 1 ? 'Level 1 — user_inputs.correctionSignal' : level === 2 ? 'Level 2 — summary 关键词推断' : '无（user_inputs.json 缺失或无候选）'}`);
+    lines.push(`- **原始条目**: ${totalRaw}`);
+    lines.push(`- **有效候选**: ${candidates.length}`);
+    lines.push(`- **已过滤**: ${dropped.length}（trivial=${droppedByReason.trivial}、空=${droppedByReason.empty}、过短=${droppedByReason.short}、去重=${droppedByReason.duplicate}）`);
+    if (notice) {
+        lines.push('');
+        lines.push(`> ⚠️ ${notice}`);
+    }
+    lines.push('');
+    if (candidates.length === 0) {
+        lines.push('## 候选列表');
+        lines.push('');
+        lines.push('（无有效候选，可直接在 review 步骤 0 选 "跳过"。）');
+        lines.push('');
+    }
+    else {
+        lines.push('## 候选列表');
+        lines.push('');
+        for (const c of candidates) {
+            lines.push(`### ${c.index}. ${c.preview.length > 60 ? c.preview.slice(0, 57) + '…' : c.preview}`);
+            lines.push('');
+            lines.push(`- **拟分类**: \`${c.suggestedCategory}\``);
+            lines.push(`- **拟用文件名**: \`${c.suggestedCategory}/${c.suggestedFilename}\``);
+            if (c.timestamp)
+                lines.push(`- **时间**: ${c.timestamp}`);
+            if (c.phase)
+                lines.push(`- **phase**: ${c.phase}`);
+            if (c.inputId)
+                lines.push(`- **inputId**: ${c.inputId}`);
+            if (c.matchedKeywords.length > 0)
+                lines.push(`- **关键词命中**: ${c.matchedKeywords.join(', ')}`);
+            if (c.isRequirementChange)
+                lines.push('- **类型**: 需求变更（非 AI 做错）');
+            lines.push('');
+            lines.push('```');
+            // 全文截断 800 字，避免超长 prompt 把清单撑爆
+            const body = (c.text || '').length > 800 ? c.text.slice(0, 797) + '…' : c.text;
+            lines.push(body);
+            lines.push('```');
+            lines.push('');
+        }
+    }
+    if (dropped.length > 0) {
+        lines.push('## 已过滤候选（不沉淀）');
+        lines.push('');
+        lines.push('| 原始# | 原因 | 引用候选# | 摘要 |');
+        lines.push('|------:|------|----------:|------|');
+        for (const d of dropped) {
+            const reasonLabel = d.reason === 'duplicate-of'
+                ? '重复'
+                : d.reason === 'subset-of'
+                    ? '子串包含'
+                    : d.reason === 'trivial-acknowledgement'
+                        ? '纯确认/无内容'
+                        : d.reason === 'too-short-no-keyword'
+                            ? '过短且未命中关键词'
+                            : '空';
+            const ref = d.refIndex ? `#${d.refIndex}` : '—';
+            const safePreview = (d.preview || '').replace(/\|/g, '\\|');
+            lines.push(`| ${d.rawIndex} | ${reasonLabel} | ${ref} | ${safePreview} |`);
+        }
+        lines.push('');
+    }
+    lines.push('## 操作指引');
+    lines.push('');
+    lines.push('在 review 阶段，主 agent 会用 `askUserQuestion` 询问以下三选项：');
+    lines.push('');
+    lines.push('- **A. 全部沉淀**：将上述 N 条有效候选全部交给 `@skill:zhuanspec:knowledge` 沉淀。');
+    lines.push('- **B. 选择性沉淀**：回复编号清单（例如 `1,3,5`），仅沉淀指定候选。');
+    lines.push('- **C. 跳过**：本轮不沉淀，仅运行 `zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved`。');
+    lines.push('');
+    lines.push('> 注意：「拟分类 / 拟用文件名」仅为启发式建议，最终由 skill 模式 B 的分类决策树确认。');
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=select-candidates.js.map

package/dist/core/hooks/collect-knowledge.js

@@ -155,12 +155,21 @@ export async function runCollectKnowledge(filePath) {
         ...(correctionHints.length > 0 ? [...correctionHints, ''] : []),
         ...phaseGuide,
         '',
-        '询问方式：',
-        '> "这次改动是否值得记录为项目知识？（回复是/否）"',
+        '🔴 **硬性流程（顺序不可跳）**：',
+        '1. 先向用户询问「这次改动是否值得记录为项目知识？（是/否）」。',
+        '2. 用户回复「是」后，**必须调用 \`@skill:zhuanspec:knowledge\`（模式 A）**，由 skill 严格按以下顺序执行：',
+        '   - 4.1 **列候选清单**（不写入任何文件）',
+        '   - 4.2 **调用 \`askUserQuestion\` 多选确认**（A全部 / B选择性 / C跳过）',
+        '   - 4.3 按用户选择写入，未选中的条目一律不写',
+        '   - 4.4 输出摘要',
+        '3. 用户回复「否」时，本次不写入任何知识文件。',
         '',
-        `用户确认后，**必须调用 \`@skill:zhuanspec:knowledge\` （模式 A）** 完成写入，由 skill 统一完成分类决策树、去重扫描、Front Matter 模板套用、index.md 更新。`,
-        `**禁止绕过 skill 直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**；${knowledgeRef}。`,
-        '如果本次只是常规代码修改，忽略此提示即可。',
+        '🔴 **红线（违反等同于绕过质量门禁）**：',
+        `- **禁止绕过 skill 直接 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**；${knowledgeRef}。`,
+        '- **禁止默认全沉淀**：不允许 AI 自行判定 "哪些内容值得沉淀" 后一次性写入多个文件。',
+        '- **禁止跳过询问**：未调用 askUserQuestion 完成多选确认前，不得启动任何写入动作。',
+        '',
+        '如果本次只是常规代码修改，忽略此提示即可（用户回复「否」也会跳过）。',
     ].join('\n');
     return {
         continue: true,

package/dist/core/hooks/post-archive.js

@@ -3,6 +3,7 @@ import { FileSystemUtils } from '../../utils/file-system.js';
 import { readdirSync, rmSync } from 'fs';
 import chalk from 'chalk';
 import { getBeijingTime, getBeijingTimeForFilename } from './record-progress.js';
+import { scanKnowledgeEntries, rebuildIndexContent, } from './knowledge-index.js';
 export async function postArchiveHook(options) {
     const output = await runPostArchiveHook(options.archived || '');
     if (options.json) {
@@ -19,21 +20,11 @@ async function runPostArchiveHook(archivedChange) {
     const repoRoot = process.cwd();
     const zhuanspecDir = path.join(repoRoot, 'zhuanspec');
     const knowledgeDir = path.join(zhuanspecDir, 'knowledge');
-    // 1. Update archive log
-    console.log(chalk.gray('  → 更新知识索引...'));
-    await FileSystemUtils.createDirectory(knowledgeDir);
     const indexPath = path.join(knowledgeDir, 'index.md');
-    const line = `- ${getBeijingTime()} archived: ${archivedChange}`;
-    if (await FileSystemUtils.fileExists(indexPath)) {
-        const existing = await FileSystemUtils.readFile(indexPath);
-        await FileSystemUtils.writeFile(indexPath, `${existing.trimEnd()}\n${line}\n`);
-    }
-    else {
-        await FileSystemUtils.writeFile(indexPath, `# Knowledge Index\n\n## Archive Log\n${line}\n`);
-    }
-    // 2. Collect change knowledge (extract best practices, implicit conventions)
+    // 1. Collect change knowledge (extract best practices, implicit conventions)
     // 注意：知识库只保留三类目录 troubleshooting / best-practices / implicit-conventions，
     // 原“决策类”内容合并进 best-practices；踩坑类走 zhuanspec:knowledge skill 单独沉淀。
+    await FileSystemUtils.createDirectory(knowledgeDir);
     console.log(chalk.gray('  → 提取设计文档中的知识记录...'));
     const knowledgeResult = await collectChangeKnowledge(zhuanspecDir, archivedChange, knowledgeDir);
     if (knowledgeResult.bestPractices > 0) {
@@ -42,7 +33,28 @@ async function runPostArchiveHook(archivedChange) {
     if (knowledgeResult.implicitConventions > 0) {
         console.log(chalk.gray(`    - 隐式约定：${knowledgeResult.implicitConventions} 条`));
     }
-    // 3. Cleanup temp files
+    // 2. Reindex 三分区（修复：archive 前的 refreshBusinessTemplateFromRemote 会用远端 index.md
+    //    覆盖本地，导致 review/knowledge skill 期间 appendIndexEntry 的登记行丢失。
+    //    这里基于本地 troubleshooting/ best-practices/ implicit-conventions/ 实际文件重建三分区，
+    //    保留远端拉来的 ## Archive Log 既有内容。）
+    console.log(chalk.gray('  → 重建知识索引（三分区 + Archive Log）...'));
+    const scan = await scanKnowledgeEntries(knowledgeDir);
+    const existingIndex = (await FileSystemUtils.fileExists(indexPath))
+        ? await FileSystemUtils.readFile(indexPath)
+        : null;
+    const rebuilt = rebuildIndexContent(scan, existingIndex);
+    await FileSystemUtils.writeFile(indexPath, rebuilt);
+    console.log(chalk.gray(`    - troubleshooting=${scan.entries.filter((e) => e.category === 'troubleshooting').length}, ` +
+        `best-practices=${scan.entries.filter((e) => e.category === 'best-practices').length}, ` +
+        `implicit-conventions=${scan.entries.filter((e) => e.category === 'implicit-conventions').length}`));
+    if (scan.warnings.length > 0) {
+        console.log(chalk.yellow(`    ⚠ Front Matter 不完整 ${scan.warnings.length} 条，建议补齐关键词/适用场景`));
+    }
+    // 3. Append 本次 archive log 行
+    const archiveLogLine = `- ${getBeijingTime()} archived: ${archivedChange}`;
+    const afterReindex = await FileSystemUtils.readFile(indexPath);
+    await FileSystemUtils.writeFile(indexPath, `${afterReindex.trimEnd()}\n${archiveLogLine}\n`);
+    // 4. Cleanup temp files
     console.log(chalk.gray('  → 清理临时文件...'));
     const tempFilesCleaned = await cleanupTempFiles(zhuanspecDir);
     if (tempFilesCleaned > 0) {

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

@@ -32,6 +32,20 @@ export declare function getBeijingTime(): string;
  * Returns format: "2026-04-21 18-35-22" (文件名安全格式)
  */
 export declare function getBeijingTimeForFilename(): string;
+/**
+ * v2.16+ 活跃耗时累加器
+ *
+ * 每次 PostToolUse 心跳到达时调用，根据 gap = now - lastActiveAt 判断：
+ *   gap < PHASE_IDLE_THRESHOLD_MS → 活跃，累加到 durationMs
+ *   gap >= PHASE_IDLE_THRESHOLD_MS → 空闲，累加到 idleMs 并 push idleSegments
+ *
+ * 同步刷新 wallClockMs、lastActiveAt、lastUpdatedAt。
+ * 返回本次增量便于调用方决定是否刷新 stats。
+ */
+export declare function tickActivePhaseDuration(entry: PhaseDurationRecord, nowEpoch?: number, nowTimestamp?: string): {
+    activeDelta: number;
+    idleDelta: number;
+};
 interface RecordProgressOptions {
     json?: boolean;
     file?: string;
@@ -143,14 +157,32 @@ interface ClarificationRecord {
 }
 /**
  * Phase duration record for tracking time spent in each phase
+ *
+ * v2.16+：字段语义反转
+ *   - durationMs：覆盖为“活跃耗时”（剔除空闲段，PHASE_IDLE_THRESHOLD_MS 内累加），
+ *     业务主指标，与上报/采集口径保持一致。
+ *   - wallClockMs：原 durationMs 的语义（endedAt|lastUpdatedAt - startedAt 墙钟差），
+ *     仅作审计/调试参考，迁移期老 progress.json 会把老的 durationMs 复制到此字段。
+ *   - idleMs / idleSegments：活跃耗时之外被剔除的空闲明细（可观测）。
+ *   - lastActiveAt：最后一次 hook 心跳的北京时间字符串，下次心跳到达时计算 gap。
  */
 export interface PhaseDurationRecord {
     phase: Phase;
     startedAt: string;
     endedAt?: string;
+    lastUpdatedAt?: string;
     durationMs: number;
     taskCount: number;
     completedTaskCount: number;
+    wallClockMs?: number;
+    idleMs?: number;
+    lastActiveAt?: string;
+    _lastActiveEpoch?: number;
+    idleSegments?: Array<{
+        from: string;
+        to: string;
+        durationMs: number;
+    }>;
 }
 /**
  * Proposal change record for tracking modifications to proposal files
@@ -321,6 +353,20 @@ export interface ProgressData {
             review: number;
             archive: number;
         };
+        wallClockMs?: {
+            techDesign: number;
+            propose: number;
+            apply: number;
+            review: number;
+            archive: number;
+        };
+        idleMs?: {
+            techDesign: number;
+            propose: number;
+            apply: number;
+            review: number;
+            archive: number;
+        };
     };
     proposalChanges: ProposalChangeRecord[];
     corrections?: CorrectionRecord[];