@hupan56/wlkj 3.2.0 → 3.3.1

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

@@ -1,276 +1,276 @@
----
-name: wl-insight
-description: "需求澄清对焦 + 可选调研 + 未来规划。流水线的'上游探索站'。最高频场景:用户描述模糊/产品听不懂时,快速对焦(必要时出原型图帮助理解),对齐后再问要不要调研/规划。把'到底要什么'想清楚,结论交给 /wl-prd 落地。"
-argument-hint: "[主题]"
-auto-approve: true
-allowed-tools: [Read, Glob, Grep, Bash, Write, Edit, Agent, WebSearch]
----
-
-# /wl-insight - 需求澄清对焦（默认）/ 调研 / 规划
-
-User input: $ARGUMENTS
-
-> **流水线的上游探索站**。但"上游探索"不是一股脑深挖——
-> **最高频的场景是:产品听不懂用户在说什么,需要快速对焦**。
->
-> **核心原则:让用户听懂,不在于简短。**
-> 听不懂就升级手段(文字→原型),直到对齐。
-> 每一步都停下来等用户确认,绝不擅自往下深挖。
-
----
-
-## 🔧 环境自检（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)
-```
-> 后续脚本统一用 `$PY "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
-
----
-
-## 🔒 语言锁（最高优先级）
-
-**全部输出必须简体中文。** 含理解复述、原型标注、结论、建议。
-禁止任何英文句子（技术专有名词如 MCP/JTBD/Kano 可保留英文缩写）。
-
----
-
-## STEP 0: 路由（看用户说了什么 / 没说什么）
-
-| 信号 | 走哪段 | 说明 |
-|------|--------|------|
-| **任何输入**（含无主题）/ "听不懂""不确定""他说的是啥" / 模糊描述 | **【默认】clarify 对焦** | 最高频,最高优先级。先对焦,别急着分析 |
-| "调研竞品""对标 XX""行业都怎么做""看看别人" | research 调研 | **但即便用户主动说调研,也先 clarify 确认要调研的是什么** |
-| "接下来做什么""下个版本""路线图""MVP 范围""规划" | plan 规划 | 同上,先对齐现状再规划 |
-
-> ⚠️ **路由铁律:clarify 是必经的第一段。** 即便用户说"调研竞品",
-> 也要先 30 秒确认"你要调研的这个东西,我理解对了吗?"。
-> 一股脑直接深挖 = 失败。
-
----
-
-## 🔒 通用前置（所有段必做）
-
-1. **身份**：读 `.qoder/.developer`，缺失 → 停下提示 `/wl-init`
-2. **现状锚点**：`$PY "$R/.qoder/scripts/orchestration/wlkj.py" context <关键词> --platform <web|app>`（必跑,秒级）
-3. **历史参考**：扫 `data/docs/prd/` 看已做过的，扫历史 insight 报告看是否聊过
-
----
-
-## 【默认段】clarify（需求澄清对焦）—— 三级升级
-
-**目标:让用户听懂"产品对他的需求的理解",并对齐。不在于简短,在于听懂。**
-**听不懂就升级手段,直到对齐为止。**
-
-### 升级阶梯(从①开始,听懂了就停,不越级)
-
-#### 第①级:文字对焦(默认起点)
-
-跑 context_pack 秒扫现状后,**立刻**输出给用户看:
-
-```
-我理解你要的是:
-  ① {一句话复述需求的核心}
-  ② {如果有第二层,补充}
-
-现状:
-  - {项目里已有什么,context_pack 命中: 文件/模块}
-  - {还没有什么}
-
-我拿不准的点(请逐条确认/纠正):
-  Q1. {第一个不确定的细节}  → 你的意思是 A 还是 B?
-  Q2. {第二个}             → ?
-  Q3. {第三个}             → ?
-
-你看我理解对了吗?哪条偏了?
-```
-
-→ **停。等用户回答。** 别往下走。
-→ 用户确认对齐了 → 进【第 2 段:问要不要调研】
-→ 用户说"还是没懂"或反复说不清 → 进第②级
-
-#### 第②级:文字说不明白 → 快速原型图(对齐工具,不是产出)
-
-**当文字反复解释用户仍听不懂/拿不准时,出一张原型图当"视觉问句"。**
-用项目真实风格,让用户直观看到"你想要的是不是大概这样":
-
-```bash
-# Web 管理端
-$PY "$R/.qoder/scripts/orchestration/wlkj.py" fill-prototype "<刚才对焦到的业务关键词>" --platform web
-# APP 移动端
-$PY "$R/.qoder/scripts/orchestration/wlkj.py" fill-prototype "<刚才对焦到的业务关键词>" --platform app
-```
-> fill-prototype 会按 platform 自动选 prototype-web.html / prototype-app.html 模板,
-> 用知识图谱里的真实字段/组件把模板填满, 输出到 drafts/。
-
-原型要求:
-- **项目真实风格**(Web=Vben Admin+Ant Design / App=Vant),不是草稿线框图
-- **聚焦你要对焦的那一个点**(不是完整功能,是对焦用的最小可视)
-- 用真实图标系统(`data/index/icon-reference.json`),**绝不 emoji**
-- 标注清楚:"这是帮你确认理解的草图,不是最终设计"
-
-给用户看时说:
-```
-为了确认我理解对了,出了张草图(用咱们项目风格):
-{原型路径}
-
-你想要的是不是大概这样?哪里不对?
-```
-
-⚠️ **这个原型是"沟通草稿",不进 PRD,不入 team_sync,不归档。**
-   它是即用即弃的对焦工具,就像白板上画的图。
-   **除非用户强烈说"这个挺好,留下进 PRD"** → 才提示转 `/wl-design` 走正式原型链路。
-
-→ 用户看懂并确认 → 进【第 2 段】
-→ 用户看了还是不懂/方向不对 → 进第③级
-
-#### 第③级:兜底 —— 回到现状深挖重解释
-
-极少数情况:原型也说不通。说明对现状的理解有偏差。
-- 重跑 context_pack,**换关键词**,深挖用户提的模块到底怎么运作
-- 把"现状到底是怎么回事"用最朴素的话重新讲一遍
-- 问用户:"是我对现状理解错了,还是你要的跟现状差很远?"
-- 最多 2 轮,然后请用户用他自己的话再描述一次需求
-
----
-
-## 【第 2 段】对齐后:问要不要调研(必须问,不擅自做)
-
-**clarify 对齐后,不要直接一股脑做调研。问用户要不要。**
-
-```
-需求对齐了 👍
-
-接下来要不要我做外部调研?(看看竞品/行业怎么做,给咱们参考)
-  A. 要调研 —— 我派几个 agent 并行去看(竞品对标/技术方案/用户场景),
-                大概 X 分钟,产出调研报告
-  B. 不用调研,需求清楚了直接往下走
-
-选 A 还是 B?
-```
-
-→ **用户选 A** → 进 research 段(派多 agent)
-→ **用户选 B** → 直接进【第 3 段:出结论 + 衔接】
-
-> 这一步的存在意义:调研耗时,且很多时候用户心里已经有数(只是没说清楚)。
-> 强行调研 = 浪费时间。**把"要不要调研"的决定权还给用户。**
-
----
-
-## research 段（仅当用户选 A）—— 多 agent 调研
-
-**目标**：用成熟方法论框架,对标外部,给已对齐的需求提供外部参考。
-
-### 方法论框架(每个 agent 按视角选合适的)
-- **竞品对标** → 竞品矩阵(功能对比表) + 差异化机会
-- **技术方案** → 技术选型对比(方案A vs B,成本/风险/成熟度)
-- **用户场景** → JTBD("用户在完成什么 job")+ Kano(基础/期望/兴奋需求分类)
-- **行业趋势** → 趋势时间线 + 机会窗口
-
-### 流程（目标 4-6 轮）
-
-**第 1 步｜确定调研视角**(2-4 个,按主题选)
-**第 2 步｜并行派多 agent**（核心）
-**同一条消息**派 2-4 个 Agent，每个一个视角 + 一个方法论框架,并发跑：
-```
-每个 Agent 的任务：
-  - 视角：{竞品对标/技术方案/用户场景/行业趋势}
-  - 方法论：{对应框架,见上}
-  - 用 WebSearch 搜 3-5 个权威源（官方文档/行业报告/技术博客/公开案例）
-  - 写中间产物：workspace/members/{dev}/drafts/research-agent-{N}-{视角}.md
-  - 含：关键发现 / 对本项目的启发 / Gap 信号(外部做得好而我们没做的) / 来源链接
-```
-> 派 Agent 时给**具体的视角描述 + 方法论 + 本项目现状摘要**，让调研有针对性。
-
-**第 3 步｜合并 + Gap 提取**
-1. 读所有 `research-agent-*.md`
-2. 合并成一份调研报告，按视角组织
-3. 对每个发现标：**本项目现状 vs 外部做法 → Gap**
-4. 列"机会信号"
-
-**第 4 步｜清理中间产物 + 与用户确认 + 出报告**
-```bash
-rm -f workspace/members/{dev}/drafts/research-agent-*.md
-```
-1. 把调研发现 + Gap + 机会信号**一次性编号列清**
-2. 问："这个调研对吗？哪个机会值得跟进？"
-3. 确认后写报告
-
-### 输出结构
-```markdown
-# 外部调研 - {主题}（{date}）
-
-## 调研视角与方法
-{本次派了哪几个视角,各用什么方法论}
-
-## 现状锚定
-{context_pack 摘要}
-
-## 调研发现（按视角）
-### 视角 1：竞品对标（竞品矩阵）
-| 竞品 | 做法摘要 | 我们的 Gap | 来源 |
-...
-
-## 机会信号
-1. {外部做得好而我们没做的}
-
-## 下一步
-要跟进哪个机会?说"转 PRD"或"继续规划"。
-```
-
----
-
-## 【第 3 段】出结论 + 衔接（所有路径必经）
-
-无论走的是 clarify 直接对齐(B 路径)还是 clarify+research(A 路径),
-最后都要:
-1. 把**对齐的需求**(+可选调研结论)整理成简短结论(1 段话 + 要点)
-2. 问用户:"转 PRD 落地?还是先做规划(roadmap)?还是就到这?"
-
-### 如果用户要规划 → plan 段（Gap + roadmap）
-1. 现状(context_pack) vs 理想态(用户描述/research 结论) 建 Gap 表
-2. Gap 按**业务价值 × 可行性**打分排序
-3. 拆 MVP(本期人力能做完的) + Roadmap(后续版本,标依赖)
-4. **与用户确认** Gap 表 + MVP + roadmap
-5. 存 `workspace/members/{dev}/drafts/insight-plan-{topic}-{date}.md`
-
-### 如果用户要转 PRD
-提示:
-```
-要落地?说"转 PRD"我把它作为现状输入,进 /wl-prd 参考模式落地成可执行 PRD。
-```
-用户说"转 PRD" → 触发 `/wl-prd 参考：{报告路径}`
-
----
-
-## 🛡️ 故障降级表
-
-| 故障现象 | 检测信号 | 降级动作 | 绝不能 |
-|---------|---------|---------|--------|
-| **context_pack 零命中** | 返回"(无命中)" | clarify 照做,现状段标"索引无先例,基于用户口述" | ❌ 编现状细节 |
-| **web 搜索失败** | Agent 返回空 | 标"外部调研暂不可用,基于内部信息";或问用户跳过调研 | ❌ 凭训练记忆编竞品数据 |
-| **多 agent 派发失败** | Agent 工具不可用 | 改单线程串行调研(主 agent 自己跑 WebSearch) | ❌ 因此中断 |
-| **原型生成失败** | 脚本报错 | 回退到第①级文字对焦,标"原型暂不可用" | ❌ 卡住不前 |
-| **平台没指定** | 用户没说 web/app | clarify 阶段**不强制问平台**(对焦时不关键);出原型时**必须问**(原型风格依赖平台) | ❌ 出错风格的原型 |
-| **用户对结论全盘否定** | 用户说"不对" | 回 clarify 第①级重新对焦,问"哪里理解偏了" | ❌ 无限循环 / ❌ 强行出报告 |
-
----
-
-## 鲁棒性清单（出结论前自检）
-
-- [ ] clarify 真的对齐了吗?(用户明确确认过,不是 AI 单方面认定)
-- [ ] 调研是用户**同意做**才做的吗?(不是擅自深挖)
-- [ ] 每个发现/Gap 都附了**证据来源**?
-- [ ] research 的中间产物 `research-agent-*.md` 清理了吗?
-- [ ] 原型(如果出了)标注了"对焦草图,非交付"了吗?
-
----
-
-## How to Use Results
-
-洞察结论可流转:**说"转 PRD" → /wl-prd 参考模式**（把对齐的需求作为现状输入落地）。
-
-> insight 是对焦/探索站,prd 是落地站。两者分开,思路才不混。
-> **insight 绝不直接生成 PRD。** 即便出了对焦原型,也不进 PRD 链路(除非用户强烈要求)。
+---
+name: wl-insight
+description: "需求上游探索站。默认澄清(产品听不懂时对焦,必要时出原型帮理解); discover(发现机会) / research(调研竞品) / plan(规划roadmap)。说'转PRD'落地。"
+argument-hint: "[主题]"
+auto-approve: true
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit, Agent, WebSearch]
+---
+
+# /wl-insight - 需求澄清对焦（默认）/ 调研 / 规划
+
+User input: $ARGUMENTS
+
+> **流水线的上游探索站**。但"上游探索"不是一股脑深挖——
+> **最高频的场景是:产品听不懂用户在说什么,需要快速对焦**。
+>
+> **核心原则:让用户听懂,不在于简短。**
+> 听不懂就升级手段(文字→原型),直到对齐。
+> 每一步都停下来等用户确认,绝不擅自往下深挖。
+
+---
+
+## 🔧 环境自检（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)
+```
+> 后续脚本统一用 `$PY "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
+
+---
+
+## 🔒 语言锁（最高优先级）
+
+**全部输出必须简体中文。** 含理解复述、原型标注、结论、建议。
+禁止任何英文句子（技术专有名词如 MCP/JTBD/Kano 可保留英文缩写）。
+
+---
+
+## STEP 0: 路由（看用户说了什么 / 没说什么）
+
+| 信号 | 走哪段 | 说明 |
+|------|--------|------|
+| **任何输入**（含无主题）/ "听不懂""不确定""他说的是啥" / 模糊描述 | **【默认】clarify 对焦** | 最高频,最高优先级。先对焦,别急着分析 |
+| "调研竞品""对标 XX""行业都怎么做""看看别人" | research 调研 | **但即便用户主动说调研,也先 clarify 确认要调研的是什么** |
+| "接下来做什么""下个版本""路线图""MVP 范围""规划" | plan 规划 | 同上,先对齐现状再规划 |
+
+> ⚠️ **路由铁律:clarify 是必经的第一段。** 即便用户说"调研竞品",
+> 也要先 30 秒确认"你要调研的这个东西,我理解对了吗?"。
+> 一股脑直接深挖 = 失败。
+
+---
+
+## 🔒 通用前置（所有段必做）
+
+1. **身份**：读 `.qoder/.developer`，缺失 → 停下提示 `/wl-init`
+2. **现状锚点**：`$PY "$R/.qoder/scripts/orchestration/wlkj.py" context <关键词> --platform <web|app>`（必跑,秒级）
+3. **历史参考**：扫 `data/docs/prd/` 看已做过的，扫历史 insight 报告看是否聊过
+
+---
+
+## 【默认段】clarify（需求澄清对焦）—— 三级升级
+
+**目标:让用户听懂"产品对他的需求的理解",并对齐。不在于简短,在于听懂。**
+**听不懂就升级手段,直到对齐为止。**
+
+### 升级阶梯(从①开始,听懂了就停,不越级)
+
+#### 第①级:文字对焦(默认起点)
+
+跑 context_pack 秒扫现状后,**立刻**输出给用户看:
+
+```
+我理解你要的是:
+  ① {一句话复述需求的核心}
+  ② {如果有第二层,补充}
+
+现状:
+  - {项目里已有什么,context_pack 命中: 文件/模块}
+  - {还没有什么}
+
+我拿不准的点(请逐条确认/纠正):
+  Q1. {第一个不确定的细节}  → 你的意思是 A 还是 B?
+  Q2. {第二个}             → ?
+  Q3. {第三个}             → ?
+
+你看我理解对了吗?哪条偏了?
+```
+
+→ **停。等用户回答。** 别往下走。
+→ 用户确认对齐了 → 进【第 2 段:问要不要调研】
+→ 用户说"还是没懂"或反复说不清 → 进第②级
+
+#### 第②级:文字说不明白 → 快速原型图(对齐工具,不是产出)
+
+**当文字反复解释用户仍听不懂/拿不准时,出一张原型图当"视觉问句"。**
+用项目真实风格,让用户直观看到"你想要的是不是大概这样":
+
+```bash
+# Web 管理端
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" fill-prototype "<刚才对焦到的业务关键词>" --platform web
+# APP 移动端
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" fill-prototype "<刚才对焦到的业务关键词>" --platform app
+```
+> fill-prototype 会按 platform 自动选 prototype-web.html / prototype-app.html 模板,
+> 用知识图谱里的真实字段/组件把模板填满, 输出到 drafts/。
+
+原型要求:
+- **项目真实风格**(Web=Vben Admin+Ant Design / App=Vant),不是草稿线框图
+- **聚焦你要对焦的那一个点**(不是完整功能,是对焦用的最小可视)
+- 用真实图标系统(`data/index/icon-reference.json`),**绝不 emoji**
+- 标注清楚:"这是帮你确认理解的草图,不是最终设计"
+
+给用户看时说:
+```
+为了确认我理解对了,出了张草图(用咱们项目风格):
+{原型路径}
+
+你想要的是不是大概这样?哪里不对?
+```
+
+⚠️ **这个原型是"沟通草稿",不进 PRD,不入 team_sync,不归档。**
+   它是即用即弃的对焦工具,就像白板上画的图。
+   **除非用户强烈说"这个挺好,留下进 PRD"** → 才提示转 `/wl-design` 走正式原型链路。
+
+→ 用户看懂并确认 → 进【第 2 段】
+→ 用户看了还是不懂/方向不对 → 进第③级
+
+#### 第③级:兜底 —— 回到现状深挖重解释
+
+极少数情况:原型也说不通。说明对现状的理解有偏差。
+- 重跑 context_pack,**换关键词**,深挖用户提的模块到底怎么运作
+- 把"现状到底是怎么回事"用最朴素的话重新讲一遍
+- 问用户:"是我对现状理解错了,还是你要的跟现状差很远?"
+- 最多 2 轮,然后请用户用他自己的话再描述一次需求
+
+---
+
+## 【第 2 段】对齐后:问要不要调研(必须问,不擅自做)
+
+**clarify 对齐后,不要直接一股脑做调研。问用户要不要。**
+
+```
+需求对齐了 👍
+
+接下来要不要我做外部调研?(看看竞品/行业怎么做,给咱们参考)
+  A. 要调研 —— 我派几个 agent 并行去看(竞品对标/技术方案/用户场景),
+                大概 X 分钟,产出调研报告
+  B. 不用调研,需求清楚了直接往下走
+
+选 A 还是 B?
+```
+
+→ **用户选 A** → 进 research 段(派多 agent)
+→ **用户选 B** → 直接进【第 3 段:出结论 + 衔接】
+
+> 这一步的存在意义:调研耗时,且很多时候用户心里已经有数(只是没说清楚)。
+> 强行调研 = 浪费时间。**把"要不要调研"的决定权还给用户。**
+
+---
+
+## research 段（仅当用户选 A）—— 多 agent 调研
+
+**目标**：用成熟方法论框架,对标外部,给已对齐的需求提供外部参考。
+
+### 方法论框架(每个 agent 按视角选合适的)
+- **竞品对标** → 竞品矩阵(功能对比表) + 差异化机会
+- **技术方案** → 技术选型对比(方案A vs B,成本/风险/成熟度)
+- **用户场景** → JTBD("用户在完成什么 job")+ Kano(基础/期望/兴奋需求分类)
+- **行业趋势** → 趋势时间线 + 机会窗口
+
+### 流程（目标 4-6 轮）
+
+**第 1 步｜确定调研视角**(2-4 个,按主题选)
+**第 2 步｜并行派多 agent**（核心）
+**同一条消息**派 2-4 个 Agent，每个一个视角 + 一个方法论框架,并发跑：
+```
+每个 Agent 的任务：
+  - 视角：{竞品对标/技术方案/用户场景/行业趋势}
+  - 方法论：{对应框架,见上}
+  - 用 WebSearch 搜 3-5 个权威源（官方文档/行业报告/技术博客/公开案例）
+  - 写中间产物：workspace/members/{dev}/drafts/research-agent-{N}-{视角}.md
+  - 含：关键发现 / 对本项目的启发 / Gap 信号(外部做得好而我们没做的) / 来源链接
+```
+> 派 Agent 时给**具体的视角描述 + 方法论 + 本项目现状摘要**，让调研有针对性。
+
+**第 3 步｜合并 + Gap 提取**
+1. 读所有 `research-agent-*.md`
+2. 合并成一份调研报告，按视角组织
+3. 对每个发现标：**本项目现状 vs 外部做法 → Gap**
+4. 列"机会信号"
+
+**第 4 步｜清理中间产物 + 与用户确认 + 出报告**
+```bash
+rm -f workspace/members/{dev}/drafts/research-agent-*.md
+```
+1. 把调研发现 + Gap + 机会信号**一次性编号列清**
+2. 问："这个调研对吗？哪个机会值得跟进？"
+3. 确认后写报告
+
+### 输出结构
+```markdown
+# 外部调研 - {主题}（{date}）
+
+## 调研视角与方法
+{本次派了哪几个视角,各用什么方法论}
+
+## 现状锚定
+{context_pack 摘要}
+
+## 调研发现（按视角）
+### 视角 1：竞品对标（竞品矩阵）
+| 竞品 | 做法摘要 | 我们的 Gap | 来源 |
+...
+
+## 机会信号
+1. {外部做得好而我们没做的}
+
+## 下一步
+要跟进哪个机会?说"转 PRD"或"继续规划"。
+```
+
+---
+
+## 【第 3 段】出结论 + 衔接（所有路径必经）
+
+无论走的是 clarify 直接对齐(B 路径)还是 clarify+research(A 路径),
+最后都要:
+1. 把**对齐的需求**(+可选调研结论)整理成简短结论(1 段话 + 要点)
+2. 问用户:"转 PRD 落地?还是先做规划(roadmap)?还是就到这?"
+
+### 如果用户要规划 → plan 段（Gap + roadmap）
+1. 现状(context_pack) vs 理想态(用户描述/research 结论) 建 Gap 表
+2. Gap 按**业务价值 × 可行性**打分排序
+3. 拆 MVP(本期人力能做完的) + Roadmap(后续版本,标依赖)
+4. **与用户确认** Gap 表 + MVP + roadmap
+5. 存 `workspace/members/{dev}/drafts/insight-plan-{topic}-{date}.md`
+
+### 如果用户要转 PRD
+提示:
+```
+要落地?说"转 PRD"我把它作为现状输入,进 /wl-prd 参考模式落地成可执行 PRD。
+```
+用户说"转 PRD" → 触发 `/wl-prd 参考：{报告路径}`
+
+---
+
+## 🛡️ 故障降级表
+
+| 故障现象 | 检测信号 | 降级动作 | 绝不能 |
+|---------|---------|---------|--------|
+| **context_pack 零命中** | 返回"(无命中)" | clarify 照做,现状段标"索引无先例,基于用户口述" | ❌ 编现状细节 |
+| **web 搜索失败** | Agent 返回空 | 标"外部调研暂不可用,基于内部信息";或问用户跳过调研 | ❌ 凭训练记忆编竞品数据 |
+| **多 agent 派发失败** | Agent 工具不可用 | 改单线程串行调研(主 agent 自己跑 WebSearch) | ❌ 因此中断 |
+| **原型生成失败** | 脚本报错 | 回退到第①级文字对焦,标"原型暂不可用" | ❌ 卡住不前 |
+| **平台没指定** | 用户没说 web/app | clarify 阶段**不强制问平台**(对焦时不关键);出原型时**必须问**(原型风格依赖平台) | ❌ 出错风格的原型 |
+| **用户对结论全盘否定** | 用户说"不对" | 回 clarify 第①级重新对焦,问"哪里理解偏了" | ❌ 无限循环 / ❌ 强行出报告 |
+
+---
+
+## 鲁棒性清单（出结论前自检）
+
+- [ ] clarify 真的对齐了吗?(用户明确确认过,不是 AI 单方面认定)
+- [ ] 调研是用户**同意做**才做的吗?(不是擅自深挖)
+- [ ] 每个发现/Gap 都附了**证据来源**?
+- [ ] research 的中间产物 `research-agent-*.md` 清理了吗?
+- [ ] 原型(如果出了)标注了"对焦草图,非交付"了吗?
+
+---
+
+## How to Use Results
+
+洞察结论可流转:**说"转 PRD" → /wl-prd 参考模式**（把对齐的需求作为现状输入落地）。
+
+> insight 是对焦/探索站,prd 是落地站。两者分开,思路才不混。
+> **insight 绝不直接生成 PRD。** 即便出了对焦原型,也不进 PRD 链路(除非用户强烈要求)。

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

@@ -1,6 +1,6 @@
 ---
 name: wl-report
-description: "生成日报/周报，严格按当前开发者隔离。Generate daily/weekly work report, isolated by current developer. "
+description: "日报/周报,按当前开发者隔离。默认日报(今天); 说'周报'出本周。数据源: 任务+禅道工时+提交+PRD+日历(可选增强)。"
 argument-hint: "[daily/weekly] or empty for auto-detect"
 auto-approve: true
 allowed-tools: [Read, Bash]

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

@@ -1,6 +1,6 @@
 ---
 name: wl-spec
-description: "从已确认 PRD 生成开发 Spec 文档（/wl-spec 命令入口）。Generate or review technical Spec from PRD + Design. "
+description: "从已确认 PRD 生成开发 Spec(技术规格)。默认生成; 带 review 评审现有 spec。/wl-code 按此 spec 实现。"
 argument-hint: "[review]"
 auto-approve: true
 allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
@@ -24,3 +24,15 @@ User input:
    ```
 5. Save to workspace/specs/ or workspace/tasks/{id}/spec.md
 6. Notify dev to review — 提示用户审阅后回复"确认"，确认后改 `status: confirmed`
+7. ★ 用户确认后，上传 spec 到平台（按 zentao_id 反查需求挂载 → 资产中心随需求可见，无需发布）：
+   ```bash
+   python -m domain.integration.spec_upload <spec.md> --zentao-id <禅道story号> [--code-targets CtrlA,SvcB]
+   ```
+   - 契约头无 `platform_spec_id` → `create_spec(zentao_id,...)` 新建 + 平台反查 Requirement 挂上 → `confirm_spec` 进 confirmed → 回写 `platform_spec_id`（幂等锚）
+   - 契约头有 `platform_spec_id` → 自动走 `update_spec`（version+1，不重复建）
+8. 改 spec 重确认 → 再跑第 7 步 → 平台 spec 多一版本（幂等）
+9. 上传失败只警告不阻塞写码（spec 本地已落地，上传是增强）
+
+## 下一步
+- spec 已 confirmed → `/wl-code <REQ-ID>` 按 spec 严格实现（spec gate 放行）
+- 实现完 → `/wl-test` 验证 → `/wl-commit` 提交回流

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

@@ -1,6 +1,6 @@
 ---
 name: wl-status
-description: "项目状态/路线图/健康度。Project status: current sprint / roadmap / health score. "
+description: "项目状态看板。current(当前迭代进度,默认) / roadmap(路线图) / health(健康度,含工作流采纳分)。说哪个看哪个。"
 argument-hint: "[scope: current/roadmap/health]"
 auto-approve: true
 allowed-tools: [Read, Glob, Grep, Bash]
@@ -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)
@@ -76,3 +78,14 @@ Calculate from:
 
 Score: >=4 healthy / 3-4 at risk / <3 needs attention
 Also surface: 索引新鲜度天数、最近 3 次 EVA 分数、未同步产出数。
+
+### 富展示（健康看板 HTML · 复用 cap.present）
+
+健康分算完后，跑自包含看板 HTML（脚本内部已接 `cap.present.widget` + 落盘降级）：
+```bash
+$PY "$R/.qoder/scripts/validation/metrics/usability_score.py" --html
+```
+- **QoderWork 桌面端**（`cap.present.available=true`，探测 `qoder_show_widget` 可达）：HTML 经 widget 嵌入对话流，富展示取代纯文本表格
+- **CLI/IDE**（NoOp 自动降级）：落盘 `workspace/members/{dev}/journal/dashboard-{时间戳}.html`，输出路径供打开
+
+不用 cap.present 也能跑——上面的 Health Score 维度表本身是纯文本，富展示只是增强可视化（T244 cap.present 接入点）。