@zhuan-ai/zhuanspec 2.16.0 → 2.16.2

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

@@ -2,9 +2,9 @@ const baseGuardrails = `**约束条件**
 - **语言要求**：必须使用中文回答所有问题和输出所有内容（All responses MUST be in Chinese）。
 - 优先采用简单、最小化的实现，仅在请求或明确需要时添加复杂性。
 - 将更改严格限制在请求的结果范围内。
-- **工作区边界（强制）**：查找文档、检索工程代码、读取 \`.llm-wiki\`、执行 grep/glob/ls 时，范围必须限定在当前 ZhuanSpec 工作区内。禁止使用 \`../**\`、上级目录绝对路径或手动拼接到工作区外路径。Glob 返回相对路径时，必须以本次工具调用的 \`path\` 参数作为基准拼接绝对路径，不得误解为当前目录或上级目录。
+- **工作区边界（强制）**：查找文档、检索工程代码、执行 grep/glob/ls 时，范围必须限定在当前 ZhuanSpec 工作区内。禁止使用 \`../**\`、上级目录绝对路径或手动拼接到工作区外路径。Glob 返回相对路径时，必须以本次工具调用的 \`path\` 参数作为基准拼接绝对路径，不得误解为当前目录或上级目录。
 - **知识库参考**：开始任何阶段前，先检查 \`zhuanspec/knowledge/\` 目录。使用 \`rg "[关键词]" zhuanspec/knowledge/\` 搜索相关陷阱和最佳实践，避免重复踩坑。阅读 \`zhuanspec/knowledge/index.md\` 了解项目级知识摘要。
-- **工程代码检索顺序**：凡是需要检索工程代码、配置类、数据模型类或关键实现位置时，优先读取已定位服务目录下的 \`[service]/.llm-wiki/index.md\`。\`llmwiki query -e --token <token> "[关键词]"\` 中的 \`<token>\` 必须来自对应服务的 \`[service]/.llm-wiki/index.md\`；每次执行 \`llmwiki query\` 后，必须判断查询结果是否与当前请求诉求匹配，并将关键词、服务、匹配/不匹配结论、简要原因记录到对应服务的 \`[service]/.llm-wiki/result.log\`；查配置类、数据模型类、配置项归属时优先使用 \`llmwiki knowledge points "[关键词]"\`。仅当对应服务的 \`.llm-wiki/\` 不存在、llmwiki 无结果、结果与当前请求诉求不匹配、或结果明显偏差时，才回退到 \`grep/glob/ls\`。
+- **工程代码检索顺序**：凡是需要检索工程代码、配置类、数据模型类或关键实现位置时，必须先调用 \`@skill:load-project-knowledge\` 进行渐进式加载，使用返回的 search_priority 限定检索范围，按优先路径定位代码。仅当 Skill 无匹配结果时，才回退到 \`grep/glob/ls\`。
 - 如果需要额外的 ZhuanSpec 约定或澄清，请参考 \`zhuanspec/AGENTS.md\`（位于 \`zhuanspec/\` 目录内 - 如果看不到，请运行 \`ls zhuanspec\` 或 \`zhuanspec update\`）。`;
 const proposalGuardrails = `${baseGuardrails}\n- **强制澄清要求**：在创建任何提案文件之前，必须首先分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、优先级、验收标准等）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测、假设或创建提案。严禁要求用户手动输入大段文字来回答澄清问题。
 - 识别任何模糊或歧义的细节，使用带预设选项的选择题在编辑文件之前询问必要的后续问题。
@@ -66,13 +66,7 @@ const proposalSteps = `**步骤**
      * 获取：matched_services（涉及的服务列表）、search_priority（检索优先路径）、architecture_constraints（架构约束）
      * 使用：后续代码定位使用 search_priority 限定范围，方案设计检查 architecture_constraints
    - 审查 \`zhuanspec/project.md\`，运行 \`zhuanspec list\` 和 \`zhuanspec list --specs\`
-   - 检查已定位服务是否存在 \`[service]/.llm-wiki/\`：
-     * 若存在，先阅读对应服务目录下的 \`[service]/.llm-wiki/index.md\`
-     * \`llmwiki query -e --token <token> "[关键词]"\` 中的 \`<token>\` 必须来自对应服务的 \`[service]/.llm-wiki/index.md\`
-     * 功能/实现定位优先使用 \`llmwiki query -e --token <token> "[关键词]"\`
-     * 每次执行 \`llmwiki query\` 后，必须判断查询结果是否与当前请求诉求匹配，并将关键词、服务、匹配/不匹配结论、简要原因记录到对应服务的 \`[service]/.llm-wiki/result.log\`
-     * 配置类、数据模型类、配置项归属优先使用 \`llmwiki knowledge points "[关键词]"\`
-   - 检查相关代码或文档时，优先使用 llmwiki 的结果缩小范围；仅当对应服务的 \`.llm-wiki/\` 不存在、llmwiki 无结果、结果与当前请求诉求不匹配、或结果明显偏差时，才通过 \`rg\`/\`ls\`/\`glob\` 兜底；注意任何需要澄清的空白。
+   - **工程代码检索**：使用 \`@skill:load-project-knowledge\` 返回的 search_priority 限定检索范围，按优先路径定位代码；仅当 Skill 无匹配结果时，才通过 \`rg\`/\`ls\`/\`glob\` 兆底。
    - **TechDesign 目录识别**：
      * 扫描 changes/ 目录下的所有变更
      * 检查每个变更的 metrics/progress.json 的 phase 字段
@@ -428,7 +422,7 @@ const proposalSteps = `**步骤**
 const proposalReferences = `**参考**
 - 当验证失败时，使用 \`zhuanspec show <id> --json --deltas-only\` 或 \`zhuanspec show <spec> --type spec\` 检查详细信息。
 - 在编写新要求之前，使用 \`rg -n "Requirement:|Scenario:" zhuanspec/specs\` 搜索现有要求。
-- 探索代码库时，先检查已定位服务目录下是否存在 \`[service]/.llm-wiki/\`；若存在，先阅读 \`[service]/.llm-wiki/index.md\`，并使用其中提供的 token 执行 \`llmwiki query -e --token <token> <keyword>\`，随后判断查询结果是否与当前请求诉求匹配，并将关键词、服务、匹配/不匹配结论、简要原因记录到对应服务的 \`[service]/.llm-wiki/result.log\`；也可使用 \`llmwiki knowledge points <keyword>\` 缩小范围。仅在 llmwiki 不可用、未命中、或结果与当前请求诉求不匹配时，再使用 \`rg <keyword>\`、\`ls\` 或直接文件读取。`;
+- 探索代码库时，先调用 \`@skill:load-project-knowledge\` 进行渐进式加载，使用返回的 search_priority 限定检索范围，按优先路径定位代码。仅当 Skill 无匹配结果时，再使用 \`rg <keyword>\`、\`ls\` 或直接文件读取。`;
 const applySteps = `**步骤**
 将这些步骤作为待办事项跟踪，逐一完成。
 1. **检查知识库并确认 Phase**：
@@ -699,12 +693,15 @@ const archiveSteps = `**前置检查**：
    - \`progress.phaseDurations\` 必须关闭 review 段并开启 archive 段
 2. 通过运行 \`zhuanspec list\`（或 \`zhuanspec show <id>\`）验证变更 ID，如果变更缺失、已归档或尚未准备好归档，则停止。
 3. **验证 Review 门禁**：确认上述五个结果文件存在且全部通过（含轨道 4 的 \`closure-check-result.json\`）。
-4. 运行 \`zhuanspec archive <id> --yes\`，以便 CLI 移动变更并应用规范更新，无需提示（仅对仅工具类工作使用 \`--skip-specs\`）。
-5. 审查命令输出以确认目标规范已更新，并且变更已进入 \`changes/archive/\`。
-6. 使用 \`zhuanspec validate --strict\` 进行验证，如果看起来有问题，使用 \`zhuanspec show <id>\` 进行检查。
-7. **知识沉淀（手动补充）**：调用 \`@skill:zhuanspec:knowledge\` skill 从本次会话记忆中补充知识。
+4. **知识沉淀（手动补充，必须前置）**：调用 \`@skill:zhuanspec:knowledge\` skill（模式 A）从本次会话记忆中补充知识。
+   - 🔴 **红线（顺序不可调整）**：本步骤**必须**在执行 \`zhuanspec archive <id>\` 之前完成。\`zhuanspec archive\` 命令内部会按顺序执行 \`postArchiveHook\`（自动结构化提取） → \`pushArchiveResultToRemote\`（一次性同步 specs / archive / knowledge 三目录到远端）；如果把手动沉淀放在 archive 命令之后，新写入的 knowledge 文件**仅落本地**，不会被推送到远端模板仓库，团队其他成员将看不到。
+   - 🔴 **禁止 AI 自行决定沉淀内容**：必须严格按 zhuanspec:knowledge skill 模式 A 步骤 4 执行——先列候选清单，再调用 \`askUserQuestion\` 让用户多选确认，再写入。禁止默认全沉淀，禁止跳过询问。
    - CLI 已自动从变更目录提取结构化知识（design.md/proposal.md/tasks.md 中的决策、注意事项等）
    - AI 需从会话记忆补充无法自动提取的内容（如对话中发现的隐式约定、调试陷阱等）
+   - 用户选择「跳过本次沉淀」时，本步骤可不写入任何文件，但仍需经过显式确认环节，禁止默认跳过。
+5. 运行 \`zhuanspec archive <id> --yes\`，以便 CLI 移动变更并应用规范更新，无需提示（仅对仅工具类工作使用 \`--skip-specs\`）。**该命令将自动 push specs / archive / knowledge 三目录到远端**，因此必须在步骤 4 完成知识沉淀后才执行。
+6. 审查命令输出以确认目标规范已更新，并且变更已进入 \`changes/archive/\`，且 "推送到远端" 段输出 \`✅ 已推送归档结果到远端\`（如使用 \`--skip-specs\` 则跳过推送）。
+7. 使用 \`zhuanspec validate --strict\` 进行验证，如果看起来有问题，使用 \`zhuanspec show <id>\` 进行检查。
 8. **会话分析**：调用 \`@skill:session-analytics\` skill 分析本次会话的指标数据（工具调用、Token消耗、时长等）。
 9. **输出反馈链接**：告知用户填写使用反馈：
    📋 https://doc.weixin.qq.com/forms/AJ4AfQfgAAwACwAAwaVABsCNqDXIKn8sf`;
@@ -712,8 +709,8 @@ const archiveReferences = `**参考**
 - 在归档之前使用 \`zhuanspec list\` 确认变更 ID。
 - 使用 \`zhuanspec list --specs\` 检查刷新的规范，并在移交之前解决任何验证问题。
 - 知识提取分工：
-  - **CLI 自动**：归档时从变更目录（proposal.md/tasks.md/design.md/specs/*.md）正则提取结构化知识
-  - **AI 手动**：调用 \`zhuanspec:knowledge\` skill 从会话记忆补充隐式约定、调试发现等
+  - **CLI 自动**（archive 命令内）：归档时从变更目录（proposal.md/tasks.md/design.md/specs/*.md）正则提取结构化知识，写入本地 \`zhuanspec/knowledge/\`，随后由同一条 archive 命令一并 push 到远端
+  - **AI 手动**（archive 命令前）：调用 \`zhuanspec:knowledge\` skill 从会话记忆补充隐式约定、调试发现等。**必须在 \`zhuanspec archive\` 命令之前**调用，否则补充内容仅落本地、不会进入远端推送
 - 会话分析 (\`session-analytics\`)：记录本次会话的效率指标，用于改进工作流。`;
 const designGuardrails = `${baseGuardrails}\n- **独立设计阶段**：techDesign 命令用于在 proposal 之前生成技术设计请求文档，不依赖变更提案。设计文档可作为后续提案的输入。
 - **需求澄清优先**：在生成设计请求前，必须确认需求来源（大神页面、需求描述文本等）。
@@ -868,26 +865,33 @@ const reviewGuardrails = `${baseGuardrails}\n- **门禁审查阶段**：review
 const reviewSteps = `**步骤**
 0. **⚠️ 纠偏沉淀优先检查（Phase 切换前强制执行）**：
    - **计数源（两级 fallback，新→旧）**：
-     - Level 1：读 \`zhuanspec/changes/<change-id>/metrics/user_inputs.json\`，筛选 \`correctionSignal.kind === 'hard' && postBaseline === true && resolution.triggeredFourOption === true\` 的条目作为纠偏明细
+     - Level 1：读 \`zhuanspec/changes/<change-id>/metrics/user_inputs.json\`，筛选 \`correctionSignal.kind === 'hard' && postBaseline === true\` 的条目作为纠偏明细
      - Level 2：\`user_inputs.json\` 存在但条目缺 \`correctionSignal\` → 按 \`inputs[*].summary\` 关键词扫描推断
    - **同时读** \`zhuanspec/changes/<change-id>/metrics/progress.json\`，检查：
      - 上述任一 Level 得到的纠偏条目数 N 是否 > 0
      - \`askedPitfallSaved\` 字段是否为 \`true\`
    - **如果满足条件（N > 0 且 askedPitfallSaved !== true）**：
-     - **立即调用 \`AskUserQuestion\` 工具**，以二选一方式询问用户：
-       \`\`\`
-       header: "踩坑沉淀"
-       question: "本轮 Apply 阶段发生过 N 次用户纠偏（N 为上述来源的实际长度，请列出最近 3 条摘要 —— Level 1 用 fullPrompt.slice(0,200)、Level 2 用 summary），是否沉淀为项目知识？"
-       选项 1: "是，沉淀"
-       选项 2: "否，跳过"
-       \`\`\`
-     - **用户选择"是"时**：
-       1. **必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`**（或等价的 \`/zhuanspec:knowledge\` slash command 并在交互中选择模式 B）来完成沉淀
-       2. 本 skill 将自动完成：读取 \`user_inputs.json\`（Level 1）或 summary 关键词扫描（Level 2）→ 分类决策树归入 \`troubleshooting/\` / \`best-practices/\` / \`implicit-conventions/\` → 去重扫描 → 套用统一 Front Matter → 写入知识文件 → 更新 \`knowledge/index.md\` → 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`
-       3. **红线**：**禁止主 agent 自行使用 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件**，禁止自行判定分类或文件名格式；禁止新建 \`decisions/\` 或三类目录以外的分类。
-     - **用户选择"否"时**：
-       - 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\` 标记已处理，不写入任何知识文件
-   - **如果不满足条件（无纠偏或已沉淀）**：直接进入下一步
+     1. **先生成决策清单（必须）**：运行
+        \`\`\`bash
+        zhuanspec progress list-corrections <change-id>
+        \`\`\`
+        CLI 会完成：读 user_inputs.json → 过滤 trivial 确认词（如“是的/好的/ok”）→ 去重（完全重复 + 子串包含）→ 启发式分类 → 写到 \`zhuanspec/changes/<change-id>/review/pending-corrections.md\`。并在 stdout 输出 **合计 / 有效 / 过滤** 三个计数。
+     2. **调用 \`AskUserQuestion\`（三选项，禁止默认）**：
+        \`\`\`
+        header: "踩坑沉淀"
+        question: "本轮有 M 条有效纠偏候选（已过滤 trivial / 去重，详见 review/pending-corrections.md），请选择沉淀范围："
+        选项 1："全部沉淀"
+        选项 2："选择性沉淀（请回复编号清单，例如 1,3,5）"
+        选项 3："跳过"
+        \`\`\`
+        🔴 **红线**：禁止跳过本次询问；禁止仅根据最近 N 条摘要就起心动念、绕过清单文件。
+     3. **用户选择 "全部沉淀" 或 "选择性沉淀"**：
+        - 必须调用 \`@skill:zhuanspec:knowledge --mode=correction --correction <change-id>\`（或 \`/zhuanspec:knowledge\` 交互模式 B）来完成沉淀。
+        - 选择性沉淀时，把用户回复的编号清单以 \`--include <编号串>\` 形式透传给 skill（例：\`--include 1,3,5\`），或在 skill 交互中照实转述编号。skill 必须以 \`pending-corrections.md\` 作为商定范围的单一源，禁止从会话记忆里“发挥”额外条目。
+        - skill 完成后会自动运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`。
+        🔴 **红线**：禁止主 agent 自行使用 Write/Edit 创建 \`zhuanspec/knowledge/\` 下的任何文件；禁止自行判定分类或文件名格式；禁止新建 \`decisions/\` 或三类目录以外的分类。
+     4. **用户选择 "跳过"**：运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\` 标记已处理，不写入任何知识文件。
+   - **如果不满足条件（无纠偏或已沉淀）**：直接进入下一步。
 
 1. **切换 Phase 到 review（第一步，必须立即执行）**：
    - 如果此提示已包含特定的变更 ID，请使用该值；否则运行 \`zhuanspec list\` 显示活跃变更并询问用户要审查哪个
@@ -1061,12 +1065,34 @@ const knowledgeSteps = `**步骤**
 3. **搜索**：
    - \`rg "<关键词>" zhuanspec/knowledge/\`
    - 结合 \`index.md\` 关键词段快速锁定
-4. **从会话添加**：
-   - 先按**分类决策树**判定归属目录；**禁止**凭习惯写到 decisions/
-   - 先 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\` 做去重扫描：若命中高度相似条目 → 在已有文件追加 \`## 追加：<日期>\` 章节，不新建文件
-   - 否则新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`，严格套用上面的 Front Matter 模板
+4. **从会话添加（强制：先列候选 → 用户确认 → 再写入）**：
+
+   🔴 **红线**：禁止 AI 自行判断 "哪些内容值得沉淀" 后直接 Write/Edit。必须严格走完 4.1 → 4.2 → 4.3 → 4.4 四个子步骤，缺一不可。
+
+   **4.1 列候选清单（不写入任何文件）**：
+   基于本次会话记忆，按【分类决策树】先列出所有 "待沉淀候选条目"，每条必须包含：
+   - 序号（1、 2、 3 …）
+   - 候选标题（≤ 30 字）
+   - 命中分类（\`troubleshooting\` / \`best-practices\` / \`implicit-conventions\`）
+   - 一句话理由（来自会话哪段对话 / 哪个修复 / 哪条纠偏）
+   - 拟用文件名（\`<YYYYMMDD>-<kebab-slug>.md\`）
+   - 重复检查结果：先对主关键词执行 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\`，命中需展示对应文件路径与拟采取动作（追加章节 vs 新建文件）
+
+   **4.2 调用 \`askUserQuestion\` 让用户决策（必须多选，禁止默认）**：
+   - 选项 A：全部沉淀
+   - 选项 B：选择性沉淀（用户回复编号清单，例如 \`1,3,5\`）
+   - 选项 C：跳过本次沉淀
+   - 🔴 **红线**：禁止「默认全沉淀」，禁止「跳过此询问」，禁止「合并多条后一次性写入」。askUserQuestion 未调用前不得启动任何 Write/Edit/MultiEdit 操作。
+
+   **4.3 按用户决策写入**：
+   - 用户未选中的条目一律不写入，不生成任何文件
+   - 命中重复的：在已有文件追加 \`## 追加：<日期>\` 章节，不新建文件
+   - 新条目：新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`，严格套用上面的 Front Matter 模板
    - **同步更新** \`zhuanspec/knowledge/index.md\`：在对应分区（\`## Troubleshooting\` / \`## Best Practices\` / \`## Implicit Conventions\`）追加一行 \`- [<标题>](<category>/<文件名>) — <关键词摘要>\`
 
+   **4.4 输出摘要**：
+   列出本轮新建 / 追加 / 被跳过的候选编号与路径，供用户复核。
+
 ---
 
 ## 模式 B：纠偏沉淀（Apply 阶段收尾 / Review 步骤 0 / PostToolUse 触发）
@@ -1075,15 +1101,14 @@ const knowledgeSteps = `**步骤**
    - 优先使用入参 \`--correction <change-id>\`
    - 否则读取 \`zhuanspec/changes/*/metrics/progress.json\`，定位 \`corrections.length > 0 && askedPitfallSaved !== true\` 的 change-id
    - 同时存在多个时，调用 \`askUserQuestion\` 让用户二选一，严禁随意选择
-2. **读取原始纠偏记录（两级 fallback，新→旧）**：
-   - **Level 1（优先，v2.15.15+）**：\`zhuanspec/changes/<change-id>/metrics/user_inputs.json\` 的 \`inputs\` 数组，筛选条件 \`correctionSignal.kind === 'hard' && postBaseline === true\`；每条取 \`fullPrompt\`（最长 2000 字）、\`correctionSignal.matchedKeywords\`、\`correctionSignal.isRequirementChange\`、\`resolution.path\`、\`timestamp\`
-   - **Level 2（中间版本兼容，v2.15.5~v2.15.14）**：\`user_inputs.json\` 存在但条目缺 \`correctionSignal\` 字段 → 对 \`inputs[*].summary\` 执行关键词扫描（参考 \`src/core/hooks/deviation-check.ts\` 的 \`USER_CORRECTION_KEYWORDS\` / \`REQUIREMENT_CHANGE_KEYWORDS\`）推断纠偏条目；无 \`fullPrompt\` 时用 \`summary\` 兜底
-   - 同时读 \`zhuanspec/changes/<change-id>/metrics/progress.json\` 的 \`corrections\` 数组作为纠偏计数交叉校验
-3. **用户二次确认（强制）**：
-   - 打印最近 3 条摘要：Level 1 用 \`fullPrompt.slice(0, 300)\`、Level 2 用 \`summary\`
-   - 调 \`askUserQuestion\`：\`是，沉淀 / 否，跳过\`
-   - 用户选"否"时，直接跳到步骤 7 只做 resolve-correction --mark-pitfall-saved，不写入任何文件
-4. **逐条分类**：对每条 correction 走上面的「分类决策树」，得到 \`<category>\`。
+2. **以 pending-corrections.md 为起点（商定范围的唯一源）**：
+   - 检查文件是否存在：\`zhuanspec/changes/<change-id>/review/pending-corrections.md\`。不存在则运行 \`zhuanspec progress list-corrections <change-id>\` 生成（CLI 已含 trivial 过滤 + 去重）。
+   - 清单已明确标出：有效候选编号 / 拟分类 / 拟用文件名 / 已过滤明细（trivial / 过短 / 重复 / 子串包含）。**模式 B 只从这份清单里取候选**，禁止从会话记忆里“发挥”额外条目。
+3. **范围决策（跟随 review 步骤 0 的三选项）**：
+   - 接收入参 \`--include <编号串>\`（如 \`--include 1,3,5\`）表示选择性沉淀；未传则默认 = 全部有效候选。
+   - 若未提供且不是从 review 步骤 0 / Stop hook 走进来，调 \`askUserQuestion\` 让用户三选一：\`全部沉淀 / 选择性沉淀（回复编号串） / 跳过\`。
+   - 选择“跳过”时，直接跳到步骤 7 只做 resolve-correction --mark-pitfall-saved，不写入任何文件。
+4. **逐条分类**：对选中的每条候选走上面的「分类决策树」，可参考清单里的「拟分类」作为起点，但决策树优先级更高。
 5. **去重扫描**：对每条（含其关键词）先执行 \`rg "<主关键词>" zhuanspec/knowledge/<category>/\`：
    - 命中相似条目 → 在已有文件追加 \`## 追加：<日期> — <change-id>\` 章节
    - 未命中 → 新建 \`zhuanspec/knowledge/<category>/<YYYYMMDD>-<kebab-slug>.md\`
@@ -1092,10 +1117,10 @@ const knowledgeSteps = `**步骤**
    - \`**来源变更**\` 字段固定写 \`<change-id>\`
    - \`## 背景\` / \`## 问题 / 经验\` / \`## 解决方案 / 建议\` 必须基于 user_inputs.json 的 fullPrompt / summary 与当次会话上下文还原，**禁止编造**
    - 同步更新 \`zhuanspec/knowledge/index.md\` 对应分区
-7. **标记已处理（强制收尾，无论步骤 3 用户选是/否）**：
+7. **标记已处理（强制收尾，无论步骤 3 用户选什么）**：
    - 运行 \`zhuanspec progress resolve-correction <change-id> --mark-pitfall-saved\`
    - 确认 \`progress.json.askedPitfallSaved === true\`，避免下次 Stop hook 重复询问
-8. **输出摘要**：列出本轮新建 / 追加的知识文件路径 + index.md 更新行；报告 \`<change-id>\` 的纠偏沉淀已完成。
+8. **输出摘要**：列出本轮新建 / 追加 / 被跳过的知识文件路径 + index.md 更新行；报告 \`<change-id>\` 的纠偏沉淀已完成。
 
 ---
 
@@ -1103,6 +1128,7 @@ const knowledgeSteps = `**步骤**
 - 所有写入 knowledge 目录的动作只能经本 skill 完成；禁止主 agent 或其他流程自行 Write。
 - 只能写入三类目录之一，禁止新建 decisions/。
 - 文件名、Front Matter、index.md 更新三者缺一不可。
+- **模式 A 写入前必须走完「列候选（4.1） + askUserQuestion 多选确认（4.2）」双步骤**；禁止 AI 自行判断「哪些内容值得沉淀」后直接写入，禁止默认全沉淀，禁止跳过询问环节。
 - 模式 B 必须以 \`resolve-correction --mark-pitfall-saved\` 收尾。`;
 const knowledgeReferences = `**参考**
 - 参考样例（格式基准）：项目 \`zhuanspec/knowledge/best-practices/oms-call-pattern.md\`、\`zhuanspec/knowledge/troubleshooting/20260506-apply-pitfalls.md\`、\`zhuanspec/knowledge/implicit-conventions/outbound-cis-inventory-lock.md\`

package/dist/utils/phase-utils.js

@@ -79,6 +79,7 @@ export async function setPhase(changeDir, phase) {
                 phaseDurations: [{
                         phase,
                         startedAt: timestamp,
+                        lastUpdatedAt: timestamp,
                         durationMs: 0,
                         taskCount: 0,
                         completedTaskCount: 0,
@@ -114,6 +115,7 @@ export async function setPhase(changeDir, phase) {
             phaseDurations: [{
                     phase,
                     startedAt: timestamp,
+                    lastUpdatedAt: timestamp,
                     durationMs: 0,
                     taskCount: 0,
                     completedTaskCount: 0,
@@ -129,6 +131,7 @@ export async function setPhase(changeDir, phase) {
         progress.phaseDurations.push({
             phase,
             startedAt: timestamp,
+            lastUpdatedAt: timestamp,
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,
@@ -145,6 +148,7 @@ export async function setPhase(changeDir, phase) {
         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).getTime();
             const endTime = new Date(timestamp).getTime();
             prevPhaseDuration.durationMs = endTime > startTime ? endTime - startTime : 0;
@@ -153,6 +157,7 @@ export async function setPhase(changeDir, phase) {
         progress.phaseDurations.push({
             phase,
             startedAt: timestamp,
+            lastUpdatedAt: timestamp,
             durationMs: 0,
             taskCount: 0,
             completedTaskCount: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.16.0",
+  "version": "2.16.2",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -39,6 +39,26 @@
     "!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"
   },
@@ -60,23 +80,5 @@
     "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"
   }
-}
+}