@hupan56/wlkj 3.3.0 → 3.3.2

package/package.json

@@ -1,29 +1,29 @@
-{
-  "name": "@hupan56/wlkj",
-  "version": "3.3.0",
-  "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
-  "bin": {
-    "wlkj": "bin/cli.js"
-  },
-  "files": [
-    "bin/",
-    "templates/",
-    "MAC-VERIFY.md"
-  ],
-  "keywords": [
-    "workflow",
-    "ai",
-    "prd",
-    "pipeline",
-    "qoder",
-    "product",
-    "team"
-  ],
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=16"
-  }
-}
+{
+  "name": "@hupan56/wlkj",
+  "version": "3.3.2",
+  "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
+  "bin": {
+    "wlkj": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "MAC-VERIFY.md"
+  ],
+  "keywords": [
+    "workflow",
+    "ai",
+    "prd",
+    "pipeline",
+    "qoder",
+    "product",
+    "team"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/templates/.qoder/.runtime/hook-errors.log

@@ -0,0 +1,4 @@
+[2026-07-15 11:55:41] pre-tool-use: stdin parse: Invalid \escape: line 1 column 50 (char 49)
+[2026-07-15 11:55:42] pre-tool-use: stdin parse: Invalid \escape: line 1 column 51 (char 50)
+[2026-07-15 11:55:42] pre-tool-use: stdin parse: Invalid \escape: line 1 column 50 (char 49)
+[2026-07-15 11:55:42] pre-tool-use: stdin parse: Expecting value: line 1 column 1 (char 0)

package/templates/qoder/commands/optional/wl-status.md

@@ -42,6 +42,8 @@ AI 据此判断"这个功能完整吗？还缺什么？"
 python -c "import json; d=json.load(open('$R/data/index/prd-features.json')); print(json.dumps(d,ensure_ascii=False,indent=2))"
 ```
 
+🎨 **富展示**（功能画像卡 HTML）：`$PY "$R/.qoder/scripts/validation/metrics/present_board.py" feature --feature <功能名> --project-id <UUID>`（端点+按钮+用例+页面+PRD 卡片，QoderWork 嵌入对话 / CLI 落盘 journal）
+
 ## Current Status (DEFAULT)
 Show:
 1. Active developer (from .qoder/.developer)

package/templates/qoder/commands/wl-code.md

@@ -29,15 +29,24 @@ PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
 | 文件知识标注 | **MCP code_context** | 实体/调用/影响1次拿 |
 | 写代码 | **Qoder Write/Edit** | 原生编辑，精确行号 |
 
-## 🔍 Ultra Review（宿主原生能力利用）
-> 代码写完后，如果 Qoder 有 Ultra Review Agent，建议调用：
-> 1. 代码写完后不要急着回流
-> 2. 调 Ultra Review Agent 审查代码质量
-> 3. 根据 Review 结果修正
-> 4. 最后调 MCP submit_return 回流 + learn 记录
->
-> **不用 Ultra Review 也能跑**——按下面的铁律手动检查。
-> Ultra Review 只是让审查更全面（边界条件/性能/安全）。
+## 🔍 Ultra Review（强制门禁 · 非建议）
+
+> ⚠️ **代码写完必须过 Ultra Review 才能回流**（不再是"建议"）。
+> 这是 Step 4 自检之后的硬门禁：过→回流；不过→列问题修，重跑；无 Ultra Review→手动 checklist 降级。
+
+### 强制流程（Step 4 自检后执行）
+1. 自检 4 项全 ✓ 后，**立即调 Ultra Review Agent**（宿主原生能力）审查本次改动
+2. **分支裁决**：
+   - ✅ **过** → 调 `submit_return` 回流 + `learn` 沉淀（见 Step 5 / 学习沉淀段）
+   - ❌ **不过** → 列出 Review 指出的问题（边界/性能/安全/规范），逐条修，**重跑 Ultra Review**，不过不回流
+3. **降级**（宿主无 Ultra Review Agent）：按下方手动 checklist 逐条过，全 ✓ 视同通过
+
+### 手动 checklist 降级（无 Ultra Review 时）
+- [ ] 边界条件：空值/越界/并发/大数量都处理了
+- [ ] 性能：无 N+1 查询、无循环里调 DB、大数据量分页
+- [ ] 安全：入参校验、权限校验、SQL 无拼接注入
+- [ ] 异常路径：Spec 定义的异常场景都有对应处理
+- [ ] 规范：与周围代码风格一致（命名/注释/分层）
 
 ## Step 1: Spec Gate（强制前置 · 非侵入式）
 
@@ -111,6 +120,10 @@ cap.mcp.call("update_task", {"task_id": X, "desc": summary + "\n本地spec: " +
 ```python
 from capability import resolve
 cap = resolve()
+# ⓪ 有 REQ-ID/禅道号时查这需求的历史代码变更（code_changes 按需求号→改过哪些函数/hunk）
+#    看这需求历史改过啥，避免重复改/沿用历史模式。与 code_history(按文件查) 互补。
+if <有 REQ-ID 或禅道号>:
+    changes = cap.mcp.call("code_changes", {"project_id": "<项目UUID>", "req_key": "<REQ-ID或XQ/WT号>"})
 # ① rag_search 语义召回：找和需求相关的函数/API/字段（词不必一样，召回最全）
 rag = cap.mcp.call("rag_search", {"query": "<需求关键词或功能描述>", "top_k": 10})
 # ② 需要精确找某个已知符号（如 handleExport）才用 search_code
@@ -123,7 +136,27 @@ impact = cap.mcp.call("get_impact", {
     "entity": "<要改的核心符号: 如 handleExport / C:FlowOperationController>",
     "depth": 2,
 })
-# 影响面大（upstream 跨多个页面/API）时，先在回复里提示风险再动手
+# ③a 改码前风险三件套（get_impact 看影响面 → risk_assessment 看风险等级 → code_history 看历史 → get_confidence 看证据置信）
+#    risk_assessment 返回 score/level(7项多证据：影响面/DB写/覆盖缺口/路径置信缺口/缺需求链路/历史不稳定/Agent变更)；
+#    code_history 返回这文件/函数被哪些需求(XQ/WT)改过、改了什么（反向：代码→需求）；
+#    get_confidence 返回路径置信度(0-1)+证据路径链。
+#    level=high/critical 或 confidence 低 → 先在回复里提示风险再动手。
+risk = cap.mcp.call("risk_assessment", {"project_id": "<项目UUID>", "entity": "<核心符号>", "depth": 2})
+history = cap.mcp.call("code_history", {"project_id": "<项目UUID>", "file_path": "<文件名或路径片段>"})
+conf = cap.mcp.call("get_confidence", {"project_id": "<项目UUID>", "entity": "<核心符号>"})
+# ③c 终极门禁裁决（合成 risk+coverage → block/warn/pass + 保形策略/alpha）
+#    gate.decision=block 须拦停问用户(高风险+裸改)；warn 可放行带提示；pass 放心改
+gate = cap.mcp.call("gate_check", {"project_id": "<项目UUID>", "entity": "<核心符号>"})
+# 影响面大 / risk level≥high / confidence 低 / gate=block 时，先提示风险再动手（block 须拦停问用户）
+# ③d 影响面大时多层并行审改动风险（宿主支持 Agent 并行 → 派 3 个 subagent 各审一层，合并风险清单）：
+#    - 前端层：谁调用这个接口/符号？改动会不会破坏调用方？
+#    - 后端层：实现逻辑/事务/调用链是否自洽？
+#    - DB层：涉及表/字段改动是否波及别处（trace_dataflow 已追全链）？
+#    不支持 Agent 并行 → 上面 risk_assessment 单点结果已够（串行降级）。
+# ③e 门禁前知识新鲜度（改码前看知识层是否过期，过期数据不可信）：
+#    check_freshness 返回模块 avg_age_days + 是否过期；过期(>threshold)→提示 refresh_knowledge 再动手
+fresh = cap.mcp.call("check_freshness", {"module": "<核心模块>", "threshold_days": 30})
+# fresh.verdict 含"过期" → 提示用户知识层陈旧，建议先 refresh_knowledge（跑构建脚本）再改码
 # ③b 涉及字段改动（加列/改类型/表单字段）：追字段全链路（表单→接口→Java字段→DB列），改一处看全链
 if <涉及字段层>:
     cap.mcp.call("trace_dataflow", {"field": "<字段名>"})  # 防"改了DB列没改对应Java字段/前端表单"
@@ -152,6 +185,8 @@ Follow the spec strictly:
 3. Follow team conventions from data/code/ patterns
 4. Write clean, commented code
 
+> **宿主 sub-agent 激活**：QoderWork 支持 sub-agent 时，dispatch 到 **`qoder-coder`** agent（`.qoder/agents/qoder-coder.toml`）——它内置 Spec 契约实现规范（数据层 Entity→Mapper→Service→Controller / 接口层 RESTful+校验+统一返回 / 异常按 Spec），递归守卫不二次 spawn。dispatch prompt 首行传 `Active Spec: <spec路径>`。不支持 sub-agent 时按上面 4 步手动实现。
+
 ## Step 4: Self-Check
 
 After implementation:

package/templates/qoder/commands/wl-init.md

@@ -1,129 +1,129 @@
----
-name: wl-init
-description: "初始化/切换开发者身份 + 环境体检。Initialize/switch developer identity + environment health check. "
-argument-hint: "[name] [role]"
-auto-approve: true
-allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
----
-
-# /wl-init - One-stop Init (Developer + Environment Doctor)
-
-Usage:
-  /wl-init              - 体检环境 + 显示状态
-  /wl-init 小王          - 切换/注册开发者 + 体检 + 自动修复
-  /wl-init 小王 pm       - 注册新开发者(带角色) + 体检 + 自动修复
-
-## 🔧 环境自检（QoderWork 桌面端 vs Qoder IDE/CLI）
-
-**先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
-```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
-PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
-```
-> `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。后续脚本统一用 `$PY "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
-
-## Engine: init_doctor.py (幂等, 增量, 永不重头再来)
-
-> **鲁棒性保证**：doctor 每项检查独立，**单项失败不阻塞其它项**；无 git 时优雅降级（团队同步/克隆禁用，但本地 PRD/搜索/任务/报告仍可用）。
-> **退出码**：`0` = 全部健康，`1` = 有未解决问题（`--fix` 能修的已自动修）。AI 据此判断"是否可直接开工"。
-
-### Case 1: /wl-init (no arguments)
-```bash
-$PY "$R/.qoder/scripts/orchestration/wlkj.py" doctor 2>/dev/null || python3 "$R/.qoder/scripts/orchestration/wlkj.py" doctor
-```
-Report the doctor's findings to the user in friendly language.
-If it found fixable issues, ask: "发现 N 个问题，要我自动修复吗？"
-then run with --fix.
-
-### Case 2/3: /wl-init 小王 [pm]
-```bash
-$PY "$R/.qoder/scripts/orchestration/wlkj.py" doctor 2>/dev/null || python3 "$R/.qoder/scripts/orchestration/wlkj.py" doctor --fix 小王 [pm]
-```
-This single command does ALL of:
-1. 注册/切换开发者 (.qoder/.developer, key=value 格式) + 个人空间目录
-2. 拉取团队最新 (team_sync pull - 拿到别人的 PRD 和最新知识图谱)
-3. 克隆缺失的源码仓库 (按 config.yaml git_sync.projects)
-4. 知识图谱: 7天内新鲜->跳过 / 过期->增量同步 / 缺失->全量构建(仅首次)
-5. 校验风格约束文件 + PRD 模板
-6. 检查周五自动构建状态, 给出本系统的设置命令
-
-After doctor finishes:
-- init_developer auto-registers identity (member.json + signing key)
-- No separate "team.py add" needed anymore
-
-## Incremental Guarantee (为什么不会重头再来)
-
-| 状态 | 行为 |
-|------|------|
-| 本周已 init 过 / 周五任务跑过 | 索引新鲜(≤7天) -> 全部跳过, 秒级完成 |
-| 周五任务没跑/失效 | 索引过期 -> git diff 增量更新, 只处理变更文件 |
-
-## 🔗 平台项目绑定（60 人各用各的项目）
-
-**每个开发者绑定自己的项目。** `/wl-init` 时选择 → 拉 token → 写 mcp_config.json。
-**切换项目 = 重跑 `/wl-init` 选另一个。** 60 人各自选自己的项目，token 绑定到项目，知识层自动隔离。
-
-### 已绑定？（探测多宿主路径）
-```bash
-grep -l WLKJ_PROJECT_ID "$R/wlinkj-workflow/mcp_config.json" "$R/.qoder/mcp_config.json" 2>/dev/null && echo "已绑定" || echo "未绑定"
-```
-
-### 未绑定或要切换？一行命令：
-```bash
-$PY "$R/.qoder/scripts/domain/kg/switch_project.py"
-```
-脚本会：
-1. 问邮箱+密码（或用 --email/--pw 参数）
-2. 连平台 `POST /api/auth/bind` 拉项目列表
-3. 列出你的所有项目，选一个
-4. 自动写 mcp_config.json（含该项目的 token + project_id）
-
-非交互模式（CI/自动化）：
-```bash
-$PY "$R/.qoder/scripts/domain/kg/switch_project.py" --email a@b.c --pw xxx --project-uuid <UUID>
-```
-
-**之后所有命令自动用该项目的知识层、token、回流地址。不同人选不同项目 = 完全隔离。**
-| 全新机器 | 克隆仓库 + 全量构建一次, 之后永远增量 |
-| 团队其他人已更新图谱 | team_sync pull 直接拿到, 本机不用构建 |
-
-## .developer File Format (MANDATORY)
-
-ALWAYS write `.qoder/.developer` in key=value format:
-```
-name=小王
-role=pm
-initialized_at=2026-06-12T10:00:00
-```
-Do NOT use `name: value` style. (Parsers accept both for legacy files,
-but new writes must use `=`.)
-
-## Git Author Check
-
-The doctor reports if `git config user.name` differs from the developer
-name (it breaks /wl-report's commit statistics). If the user agrees,
-run: `git config user.name {name}`. Do not change it without confirmation.
-
-## Status Display
-After any operation, show:
-```
-Developer: 小王 (pm)
-Team: 3 members (1 PM, 2 Dev)
-Active tasks: 2 (1 in progress, 1 draft)
-知识图谱: 2 天前更新 (新鲜)
-```
-
-## Safety Rules
-- NEVER delete workspace/ content
-- NEVER overwrite member.json or task.json
-- Full index build ONLY when index is completely missing (doctor handles this)
-
-## 产品常踩的坑（遇到时这样解释，别让产品卡住）
-
-| 现象 | 原因 | 怎么说 / 怎么办 |
-|------|------|----------------|
-| `/wl-init --fix` 卡在第 4 项几分钟 | 正在 clone 大源码仓库（fywl-ics 8973 文件） | 告诉用户"首次克隆大仓库要几分钟，属正常，耐心等"。clone 失败（网络/权限）只影响"搜索真实代码"，本地 PRD/任务/报告不受影响 |
-| 搜代码总返回 0 结果 / 生成原型字段全空 | `config.yaml` 的 `platforms.{xx}.project` 写的项目名在 `data/code/` 下不存在（管理员改了 git_sync URL 忘改 platforms） | doctor 第 4 项会报 `platforms.X.project = '...' 但无此目录`。让管理员核对 config.yaml 的 platforms 映射 |
-| `git user.name` 与开发者名不一致警告 | 影响后续 /wl-report 统计 + push 门禁 | doctor 已自动用 `--fix` 修正本仓库 git config。用户未带 `--fix` 时提示重跑 |
-| 没装 git | doctor 第 1 项报 WARN | 不阻塞：本地 PRD/搜索/任务/报告仍可用，只有团队同步/克隆禁用 |
-| 搜出来的代码是旧的 | 知识图谱 >7 天未更新 | doctor 第 5 项会增量同步，`--fix` 自动跑 |
+---
+name: wl-init
+description: "初始化/切换开发者身份 + 环境体检。Initialize/switch developer identity + environment health check. "
+argument-hint: "[name] [role]"
+auto-approve: true
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
+---
+
+# /wl-init - One-stop Init (Developer + Environment Doctor)
+
+Usage:
+  /wl-init              - 体检环境 + 显示状态
+  /wl-init 小王          - 切换/注册开发者 + 体检 + 自动修复
+  /wl-init 小王 pm       - 注册新开发者(带角色) + 体检 + 自动修复
+
+## 🔧 环境自检（QoderWork 桌面端 vs Qoder IDE/CLI）
+
+**先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
+```bash
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
+```
+> `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。后续脚本统一用 `$PY "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
+
+## Engine: init_doctor.py (幂等, 增量, 永不重头再来)
+
+> **鲁棒性保证**：doctor 每项检查独立，**单项失败不阻塞其它项**；无 git 时优雅降级（团队同步/克隆禁用，但本地 PRD/搜索/任务/报告仍可用）。
+> **退出码**：`0` = 全部健康，`1` = 有未解决问题（`--fix` 能修的已自动修）。AI 据此判断"是否可直接开工"。
+
+### Case 1: /wl-init (no arguments)
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" doctor 2>/dev/null || python3 "$R/.qoder/scripts/orchestration/wlkj.py" doctor
+```
+Report the doctor's findings to the user in friendly language.
+If it found fixable issues, ask: "发现 N 个问题，要我自动修复吗？"
+then run with --fix.
+
+### Case 2/3: /wl-init 小王 [pm]
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" doctor 2>/dev/null || python3 "$R/.qoder/scripts/orchestration/wlkj.py" doctor --fix 小王 [pm]
+```
+This single command does ALL of:
+1. 注册/切换开发者 (.qoder/.developer, key=value 格式) + 个人空间目录
+2. 拉取团队最新 (team_sync pull - 拿到别人的 PRD 和最新知识图谱)
+3. 克隆缺失的源码仓库 (按 config.yaml git_sync.projects)
+4. 知识图谱: 7天内新鲜->跳过 / 过期->增量同步 / 缺失->全量构建(仅首次)
+5. 校验风格约束文件 + PRD 模板
+6. 检查周五自动构建状态, 给出本系统的设置命令
+
+After doctor finishes:
+- init_developer auto-registers identity (member.json + signing key)
+- No separate "team.py add" needed anymore
+
+## Incremental Guarantee (为什么不会重头再来)
+
+| 状态 | 行为 |
+|------|------|
+| 本周已 init 过 / 周五任务跑过 | 索引新鲜(≤7天) -> 全部跳过, 秒级完成 |
+| 周五任务没跑/失效 | 索引过期 -> git diff 增量更新, 只处理变更文件 |
+
+## 🔗 平台项目绑定（60 人各用各的项目）
+
+**每个开发者绑定自己的项目。** `/wl-init` 时选择 → 拉 token → 写 mcp_config.json。
+**切换项目 = 重跑 `/wl-init` 选另一个。** 60 人各自选自己的项目，token 绑定到项目，知识层自动隔离。
+
+### 已绑定？（探测多宿主路径）
+```bash
+grep -l WLKJ_PROJECT_ID "$R/.qoder/mcp_config.json" 2>/dev/null && echo "已绑定" || echo "未绑定"
+```
+
+### 未绑定或要切换？一行命令：
+```bash
+$PY "$R/.qoder/scripts/domain/kg/switch_project.py"
+```
+脚本会：
+1. 问邮箱+密码（或用 --email/--pw 参数）
+2. 连平台 `POST /api/auth/bind` 拉项目列表
+3. 列出你的所有项目，选一个
+4. 自动写 mcp_config.json（含该项目的 token + project_id）
+
+非交互模式（CI/自动化）：
+```bash
+$PY "$R/.qoder/scripts/domain/kg/switch_project.py" --email a@b.c --pw xxx --project-uuid <UUID>
+```
+
+**之后所有命令自动用该项目的知识层、token、回流地址。不同人选不同项目 = 完全隔离。**
+| 全新机器 | 克隆仓库 + 全量构建一次, 之后永远增量 |
+| 团队其他人已更新图谱 | team_sync pull 直接拿到, 本机不用构建 |
+
+## .developer File Format (MANDATORY)
+
+ALWAYS write `.qoder/.developer` in key=value format:
+```
+name=小王
+role=pm
+initialized_at=2026-06-12T10:00:00
+```
+Do NOT use `name: value` style. (Parsers accept both for legacy files,
+but new writes must use `=`.)
+
+## Git Author Check
+
+The doctor reports if `git config user.name` differs from the developer
+name (it breaks /wl-report's commit statistics). If the user agrees,
+run: `git config user.name {name}`. Do not change it without confirmation.
+
+## Status Display
+After any operation, show:
+```
+Developer: 小王 (pm)
+Team: 3 members (1 PM, 2 Dev)
+Active tasks: 2 (1 in progress, 1 draft)
+知识图谱: 2 天前更新 (新鲜)
+```
+
+## Safety Rules
+- NEVER delete workspace/ content
+- NEVER overwrite member.json or task.json
+- Full index build ONLY when index is completely missing (doctor handles this)
+
+## 产品常踩的坑（遇到时这样解释，别让产品卡住）
+
+| 现象 | 原因 | 怎么说 / 怎么办 |
+|------|------|----------------|
+| `/wl-init --fix` 卡在第 4 项几分钟 | 正在 clone 大源码仓库（fywl-ics 8973 文件） | 告诉用户"首次克隆大仓库要几分钟，属正常，耐心等"。clone 失败（网络/权限）只影响"搜索真实代码"，本地 PRD/任务/报告不受影响 |
+| 搜代码总返回 0 结果 / 生成原型字段全空 | `config.yaml` 的 `platforms.{xx}.project` 写的项目名在 `data/code/` 下不存在（管理员改了 git_sync URL 忘改 platforms） | doctor 第 4 项会报 `platforms.X.project = '...' 但无此目录`。让管理员核对 config.yaml 的 platforms 映射 |
+| `git user.name` 与开发者名不一致警告 | 影响后续 /wl-report 统计 + push 门禁 | doctor 已自动用 `--fix` 修正本仓库 git config。用户未带 `--fix` 时提示重跑 |
+| 没装 git | doctor 第 1 项报 WARN | 不阻塞：本地 PRD/搜索/任务/报告仍可用，只有团队同步/克隆禁用 |
+| 搜出来的代码是旧的 | 知识图谱 >7 天未更新 | doctor 第 5 项会增量同步，`--fix` 自动跑 |

package/templates/qoder/commands/wl-prd.md

@@ -23,16 +23,20 @@ User input: $ARGUMENTS
 | 生成 PRD 正文 | **Qoder AI** | 宿主 AI 比我们调 qwen-plus 更强 |
 | 写文件 | **Qoder Write** | 原生文件操作 |
 
-## 🧠 Planning Agent（宿主原生能力利用）
-> 如果 Qoder 支持 Planning Agent 模式，PRD 生成时建议先 Planning：
-> 1. 切到 Planning Agent 模式（或在 Agent 模式下让 AI 先出计划）
-> 2. 输入需求 + MCP context_pack 结果
-> 3. AI 自动拆成章节计划（需求概述→字段→接口→非功能→里程碑）
-> 4. 逐章生成，每章参考 MCP 知识上下文
-> 5. 全部完成后调 MCP submit_return 回流平台
->
-> **不用 Planning 也能跑**——直接让 Agent 按下文步骤执行。
-> Planning 只是让结构更完整、不漏章节。
+## 🧠 Planning Agent（完整模式强制前置 · 非建议）
+
+> ⚠️ **完整模式必须先 Planning 再生成**（不再是"建议"）。
+> Planning 拆出 13 章计划 → 逐章生成有骨架不漏章；跳过 Planning 直接写易漏章节（真实反面：海外考勤 PRD 只写 1 章就交差）。
+
+### 强制流程（完整模式取完上下文后第一步）
+1. 取完上下文（context_pack）后，**先出 Planning**：把 13 章拆成计划（每章要点 + 引用哪条 MCP 知识命中）
+2. Planning 通过 → 逐章生成，每章参考 MCP 知识上下文
+3. 全部完成 → 调 MCP submit_return 回流平台
+
+### 降级（宿主无 Planning Agent 模式）
+手动按 13 章模板（`templates/prd-full-template.md`）逐章列要点，列完再写正文——等价于手动 Planning，**不跳过拆章这一步**。
+
+> 快速模式（6 章）不强制 Planning——章节少，直接 prd-quick agent 3 步出。
 
 ## 🚦 路由（看第一个词或描述特征）
 
@@ -75,6 +79,8 @@ PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
 
 **新模块/新业务/新流程用这个。** 支持衔接 insight：`参考:<报告路径>`
 
+> **宿主 sub-agent 激活**：QoderWork 支持 sub-agent 时，完整模式可 dispatch 到 **`prd-reference`** agent（`.qoder/agents/prd-reference.md`）——它承担"现状分析"（定位文件 + 总结现状怎么做/已知限制）+ 参考现有数据生成 PRD+原型，10 点质检内置。dispatch prompt 传 platform + 需求 + 开发者名。生成前先过上方 🧠 Planning 强制前置。不支持 sub-agent 则按下文手动取上下文流程。
+
 **铁律：平台必问。** 先问：
 ```
 这个需求是针对哪个平台？
@@ -94,6 +100,11 @@ cap = resolve()
 # ⓪ req_trace 查同需求历史画像（防重复造轮子）：有 REQ-ID 时先查这个需求已有哪些 PRD/代码/表
 if <有 REQ-ID>:
     cap.mcp.call("req_trace", {"req_id": "<REQ-ID>"})  # 返回 PRD+代码+表+测试，避免重复写已有功能
+# ⓪b find_similar_prds 找相似历史需求（防重复造轮子，跨项目）：无 REQ-ID 也能查
+#    输入需求描述 → 语义最相似的 top-K 历史需求(commit-mined)，看是否已有人做过类似功能
+#    返回 sim_label(高度相似/相关/弱相关)+借鉴的代码实体名；高度相似的先看再决定是否重写
+similar = cap.mcp.call("find_similar_prds", {"query": "<需求描述>", "top_k": 5})
+# 若两条需求高度相似，可 diff_requirements 对比它们 touched_entities 差异（共有/独有代码+Jaccard）
 # ① context_pack Fast Path（1 次往返取全上下文：代码+API+字段+风格+相关PRD）
 #    等价于 rag_search + context_360 合并，轮次减半（原 5 次 → 3 次）
 pack = cap.mcp.call("context_pack", {"query": "<业务词或需求描述>", "project_id": "<项目UUID>"})
@@ -166,6 +177,8 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" eval <prd.md> [原型.html]
 
 **加字段/加按钮/改文案/加导出等零星需求专用。** 极速，不走 EVA。
 
+> **宿主 sub-agent 激活**：QoderWork 支持 sub-agent 时，dispatch 到 **`prd-quick`** agent（`.qoder/agents/prd-quick.md`）——3 步极速（取上下文→生成 PRD+原型→一句话确认），≤5 轮工具调用，跳过 EVA。dispatch prompt 传 platform + 需求 + 开发者名。不支持则按下文手动流程。
+
 **平台必问**（同上）。
 
 ### 取上下文（RAG 语义预取，禁止串行 search）
@@ -202,12 +215,14 @@ prefetch/rag_search 一次返回代码/字段/API/Wiki/历史 PRD。**之后不
 
 ### 流程
 1. 不给文件 → 列出最近的 PRD 让用户选
-2. 7 项 checklist 逐项检查：
+2. 7 项 checklist 评审（★ 宿主支持 Agent 并行时，派 7 个 subagent 各审一项并发跑，合并 ✓/✗；不支持则串行逐项）：
    - 验收标准是否可测
    - 字段是否引用了真实数据库字段
    - 影响范围是否评估
    - 非功能性需求是否覆盖
-   - ...
+   - 接口/异常是否与现有系统自洽
+   - 是否有重复造轮子（查 req_trace / search_prd）
+   - 原型与 PRD 是否一致
 3. 跑 EVA 评分：`$PY "$R/.qoder/scripts/orchestration/wlkj.py" eval <prd.md>`（wlkj.py eval 内部映射 validation/metrics/eval_prd.py）
 4. 输出：总分 + 7 项 ✓/✗ + 改进建议
 

package/templates/qoder/commands/wl-search.md

@@ -73,6 +73,17 @@ cap.mcp.call("search_code", {"keyword": "handleExport", "platform": "web"})
 3. 整合：先讲业务流程（来自 ask_corpus），再列相关代码/字段（来自 rag_search）
 4. 精确符号定位才补 `search_code`
 
+### 盘点模式（多 agent 并行召回 · 宿主能力）
+
+"盘点某业务有哪些代码/字段/API/Wiki/PRD"这类要全量扫的，宿主支持 Agent 并行时**派多个 subagent 各召回一类并发跑**，再合并成一张盘点表：
+- agent①：`rag_search` 召回代码片段 + `search_code` 精确符号
+- agent②：`search_api` 召回相关端点
+- agent③：`search_wiki` 召回模块文档
+- agent④：`search_prd` / `search_prd_semantic` 召回历史 PRD
+- 合并：去重 + 按制品分组，输出"代码 N 处 / API M 个 / Wiki K 篇 / PRD J 份"
+
+不支持 Agent 并行 → 按上方三路检索串行跑（rag_search 一次召回最全，已够多数盘点）。
+
 ## 知识图谱能力（20+，统一 cap.mcp.call 调用）
 
 | 用户要查什么 | 调用方式 |
@@ -83,6 +94,11 @@ cap.mcp.call("search_code", {"keyword": "handleExport", "platform": "web"})
 | API 端点 | `cap.mcp.call("search_api", {"keyword": "salary"})` |
 | 已有 PRD（防重复造轮子） | `cap.mcp.call("search_prd", {"keyword": "保险"})` |
 | 改某接口影响哪些页面 | `cap.mcp.call("get_impact", {"endpoint": "/asset"})` |
+| **改动风险评估（7项多证据，score+level）** | `cap.mcp.call("risk_assessment", {"project_id":"<UUID>", "entity":"<符号>"})` |
+| **路径置信度（证据路径置信+路径链）** | `cap.mcp.call("get_confidence", {"project_id":"<UUID>", "entity":"<符号>"})` |
+| **文件/符号变更史（代码→需求，被哪些需求改过）** | `cap.mcp.call("code_history", {"project_id":"<UUID>", "file_path":"<文件名>"})` |
+| **需求代码变更切片（需求→代码，XQ/WT号查改过哪些函数）** | `cap.mcp.call("code_changes", {"project_id":"<UUID>", "req_key":"XQ1248"})` |
+| **禅道story反查平台spec（看需求已有开发规格）** | `cap.mcp.call("find_specs_by_zentao", {"project_id":"<UUID>", "zentao_id":"<story号>"})` |
 | 某函数/端点的完整关联 | `cap.mcp.call("context_360", {"symbol": "handleExport"})` |
 | 一次取全(代码+页面+字段+API) | `cap.mcp.call("context_pack", {"keyword": "车辆", "role": "pm"})` |
 | 哪些功能有/没测试 | `cap.mcp.call("coverage_matrix", {})` |
@@ -93,11 +109,27 @@ cap.mcp.call("search_code", {"keyword": "handleExport", "platform": "web"})
 | **需求全貌（REQ-ID→PRD+代码+表+测试）** | `cap.mcp.call("req_trace", {"req_id": "REQ-2026-042"})` |
 | **字段全链路（表单→接口→Java字段→DB列）** | `cap.mcp.call("trace_dataflow", {"field": "vehicleNo"})` |
 | **概念多源画像（PRD+代码+表+原型）** | `cap.mcp.call("anchor_view", {"concept": "保险单"})` |
+| **5制品全证据链（PRD+代码+表+测试+原型+强度+缺失提示）** | `cap.mcp.call("evidence_chain", {"concept": "保险单"})` |
 | **PRD 正文语义搜（搜正文，不只标题）** | `cap.mcp.call("search_prd_semantic", {"query": "异常筛选"})` |
 | Repo Wiki 模块文档 | `cap.mcp.call("search_wiki", {"keyword": "考勤"})` |
 | 原型预填（真实数据） | `cap.mcp.call("fill_prototype", {"keyword": "车辆", "platform": "web"})` |
 | 设计系统规范 | `cap.mcp.call("get_design_system", {"platform": "web"})` |
 
+## 🎨 富展示（看板 HTML · 复用 cap.present）
+
+get_impact / coverage_matrix / feature_overview 的结果可一键转富展示看板 HTML（QoderWork 嵌入对话 / CLI 落盘 journal）：
+```bash
+# 影响传播树（分层 upstream/downstream 可折叠）
+$PY "$R/.qoder/scripts/validation/metrics/present_board.py" impact --entity <符号> --project-id <UUID>
+# 测试覆盖热力图（功能×测试 有/无）
+$PY "$R/.qoder/scripts/validation/metrics/present_board.py" coverage --project-id <UUID>
+# 功能画像卡（端点+按钮+用例+页面+PRD）
+$PY "$R/.qoder/scripts/validation/metrics/present_board.py" feature --feature <功能名> --project-id <UUID>
+```
+- **QoderWork 桌面端**（cap.present.available）：HTML 嵌入对话流，富展示取代纯文本表格
+- **CLI/IDE**：落盘 `workspace/members/{dev}/journal/{name}-{ts}.html`，输出路径供打开
+- 不用 cap.present 也能跑——上面的能力表是纯文本调用，富展示只是增强可视化（T244 接入点）
+
 ## 快速判断该用哪个
 
 - **"这个功能怎么实现 / 相关代码有哪些"** → 先 `rag_search`（语义最全），不够再 `search_code`

package/templates/qoder/commands/wl-task.md

@@ -286,6 +286,7 @@ $PY "$R/.qoder/scripts/domain/task/task.py" list [--mine] [--status <s>] [--read
 "看需求#761详情"                 → get_story_detail(story_id=761)
 "需求改状态"(draft→reviewing等)  → change_story_status(story_id=?, status=?)
 "需求关联到计划/版本/执行"       → link_story_to_plan / link_story_to_build / link_story_to_execution
+"看需求的平台开发spec"           → find_specs_by_zentao(zentao_id=<story号>)  ← 反查平台 spec（这需求已有开发规格？避免重复设计）
 ```
 
 #### 建需求后主动问版本（★ 你们的版本=项目级 build，PM 最高频关联动作）
@@ -368,6 +369,8 @@ AI: ✅ 需求#761 已关联 build#22(本周) + #16(未来)
 | **Qoder IDE / Quest** | `mcp__qoder-zentao__工具名(参数)` |
 | **CLI / 其他** | `cap.mcp.call("工具名", {参数})` |
 
+> **★ cap.mcp.call 已进程复用**（`_REGISTRY` 单例 + `_pool` 缓存 transport，per server 不重复 spawn；实测同 server 第2次调用 3.07s→0.03s，100x）。QoderWork 下 `qw_mcp_call` 与 `cap.mcp.call` 等价（都复用进程），**统一推荐 `cap.mcp.call`**（跨宿主一致，零感知）。上表 qw_mcp_call 是 QoderWork 原生可选优化。
+
 #### 🎯 工序操作剧本（显式建/改，非查询）
 
 > 下面是 /wl-task 的**工序动作**（建需求/建任务/改状态/记工时），需要流程保障。
@@ -494,13 +497,14 @@ $PY "$R/.qoder/scripts/domain/task/task.py" list --status planning
 | **E 工作量** | 大概几个人周？看 PRD 的功能点数量 | 1=小 / 5=大 |
 
 ### 流程
-1. AI 对每个任务**先给一组 R/I/C/E 估算**（基于 PRD，标注信心来源）
-2. 算出 RICE 分，排序，展示给用户：
+1. ★ **任务 >5 个或依赖复杂时，先 Planning 拆任务依赖树**（宿主 Planning Agent 模式）：列出谁 block 谁、哪些能并行、哪些是关键路径，再排 RICE。无 Planning → 手动画依赖图（STEP 4 的 block 关系）降级，**不跳过依赖梳理**。
+2. AI 对每个任务**先给一组 R/I/C/E 估算**（基于 PRD，标注信心来源）
+3. 算出 RICE 分，排序，展示给用户：
    ```
    | 排名 | 任务 | R | I | C | E | RICE | 信心来源 |
    ```
-3. 问："要调整哪个的打分？" —— 用户改完，**写回每个 task.json 的 `rice` 字段**（Edit 工具），并据此重排优先级（`--priority`）。
-4. push 同步。
+4. 问："要调整哪个的打分？" —— 用户改完，**写回每个 task.json 的 `rice` 字段**（Edit 工具），并据此重排优先级（`--priority`）。
+5. push 同步。
 
 ### 排不动时的兜底
 - 任务都没有 PRD / PRD 太空 → 诚实说："这几个缺 PRD 背景，R/I 估不准。要不先补 PRD，或直接用优先级（P0-P3）手动排？"

package/templates/qoder/commands/wl-test.md

@@ -128,6 +128,8 @@ python -c "import json; d=json.load(open('$R/data/index/test-pages.json')); prin
 输出：哪些功能/页面有测试用例（test-pages.json + test-assertions.json），哪些是空白。
 AI 据此建议"优先补 XX 功能的测试"。
 
+🎨 **富展示**（覆盖热力图 HTML）：`$PY "$R/.qoder/scripts/validation/metrics/present_board.py" coverage --project-id <UUID>`（功能×测试 有/无 热力图，QoderWork 嵌入对话 / CLI 落盘 journal）
+
 ### 改动驱动的必跑测试（提交前门禁 · S4 覆盖推理）
 
 改完代码要确定"必跑哪些测试"时，用覆盖推理四件套（已注册 MCP）：
@@ -143,6 +145,8 @@ cap.mcp.call("find_coverage_of", {"req_id": "<REQ-ID>"})            # 查某需
 
 ## unit 单元测试
 
+> **宿主 sub-agent 激活**：QoderWork 支持 sub-agent 时，dispatch 到 **`qoder-test-gen`** agent（`.qoder/agents/qoder-test-gen.toml`）——自动定位实现代码 + 读 Spec → 生成 JUnit（Service 层 Mock 全依赖 Given-When-Then / Controller 层 MockMvc / @DisplayName / AssertJ / Builder 测试数据），输出 `tests/{包路径}/{类名}Test.java`。dispatch prompt 首行传 `Active Code: <实现文件路径>`。不支持则按下文 skill 手动生成。
+
 读 `.qoder/skills/test-generator/SKILL.md`：定位实现代码 → 读 spec → 生成
 JUnit 测试（Mock + MockMvc，Given-When-Then）→ 输出 `tests/{package}/{Class}Test.java`。
 （只有这条线才需要 search_index 找代码。）