@hupan56/wlkj 2.7.12 → 3.0.0

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

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

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

@@ -16,7 +16,7 @@ User input: $ARGUMENTS
 ```bash
 R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
-> 后续脚本统一用 `python "$R/.qoder/scripts/xxx.py"`；所有仓库内相对路径（workspace/、data/code/）都前置 `"$R/"`。
+> 后续脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io）或 `python "$R/.qoder/scripts/wlkj.py" <命令>`；所有仓库内相对路径（workspace/、data/code/）都前置 `"$R/"`。
 
 ## CRITICAL: Data Isolation
 
@@ -44,7 +44,7 @@ This name is used to filter ALL data below.
 ### 2. My Tasks (workspace/tasks/)
 ```bash
 # Find tasks where creator OR assignee = current developer
-python "$R/.qoder/scripts/task.py" list --mine
+python "$R/.qoder/scripts/task/task.py" list --mine
 ```
 Only show tasks where task.json has:
 - `creator` == current developer, OR
@@ -102,7 +102,7 @@ Output:
 ```
 
 Save to: workspace/members/{developer}/journal/daily-{date}.md
-Then auto-sync (user never touches git): `python "$R/.qoder/scripts/team_sync.py" push`
+Then auto-sync (user never touches git): `python "$R/.qoder/scripts/task/team_sync.py" push`
 
 ---
 
@@ -151,7 +151,7 @@ Output:
 ```
 
 Save to: workspace/members/{developer}/journal/weekly-{week}.md
-Then auto-sync (user never touches git): `python "$R/.qoder/scripts/team_sync.py" push`
+Then auto-sync (user never touches git): `python "$R/.qoder/scripts/task/team_sync.py" push`
 
 ---
 

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

@@ -16,7 +16,7 @@ User input: $ARGUMENTS (default: show current status)
 ```bash
 R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
-> 后续脚本统一用 `python "$R/.qoder/scripts/xxx.py"`；仓库内相对路径都前置 `"$R/"`。
+> 后续脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io）或 `python "$R/.qoder/scripts/wlkj.py" <命令>`；仓库内相对路径都前置 `"$R/"`。
 
 ## Scopes
 - (no arg or "current") -> Current sprint status
@@ -69,7 +69,7 @@ Calculate from:
 | EVA quality trend | 25% | tail .qoder/learning/eval-history.jsonl (avg score_pct, target >=80) |
 | Index freshness | 20% | data/index/.index-meta.json last_sync (<=7 days) + verify checks |
 | On-time delivery | 20% | task completion dates |
-| Sync health | 15% | python "$R/.qoder/scripts/team_sync.py" status (ahead/behind/dirty) |
+| Sync health | 15% | python "$R/.qoder/scripts/task/team_sync.py" status (ahead/behind/dirty) |
 | Pipeline flow | 10% | PRD->Spec->Code conversion |
 | Learning growth | 10% | learning/patterns/ entries |
 

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

@@ -16,7 +16,7 @@ User input: $ARGUMENTS
 ```bash
 R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
-> 后续脚本统一用 `python "$R/.qoder/scripts/xxx.py"`。
+> 后续脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io）或 `python "$R/.qoder/scripts/wlkj.py" <命令>`。
 
 ## Step 1: Load Spec
 
@@ -26,7 +26,7 @@ Read the spec file to understand requirements.
 
 ## Step 2: Search Related Code
 
-Run: python "$R/.qoder/scripts/search_index.py" <keyword>
+Run: python "$R/.qoder/scripts/kg/search_index.py" <keyword>
 Find existing code that this implementation relates to.
 Read relevant files for context.
 

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

@@ -1,6 +1,6 @@
 ---
 name: wl-design
-description: "设计工序: 预览(蓝湖稿→HTML) / 扫描(看系统现状) / 评审(检查合规)。设计师在蓝湖画完,一条链接出预览。"
+description: "设计工序入口: import 录入设计稿→spec.json(默认) / generate 按设计spec出原型 / review 评审原型。"
 argument-hint: "[预览|扫描|评审] <蓝湖链接或功能名>"
 auto-approve: true
 allowed-tools: [Read, Glob, Grep, Bash, Write, Edit, mcp__qoder-knowledge-graph, mcp__lanhu, mcp__qoder-mysql]
@@ -121,5 +121,5 @@ mcp__qoder-knowledge-graph__context_pack(keyword='<功能名>', platform='web')
 
 评审输出后，记录到 learning：
 ```bash
-python "$R/.qoder/scripts/learn.py" record review_done "{\"target\":\"$feature\",\"result\":\"$pass_or_issues\"}"
+python "$R/.qoder/scripts/report/learn.py" record review_done "{\"target\":\"$feature\",\"result\":\"$pass_or_issues\"}"
 ```

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

@@ -19,7 +19,7 @@ Usage:
 ```bash
 R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
-> `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。后续脚本统一用 `python "$R/.qoder/scripts/xxx.py"`。
+> `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。后续脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io）或 `python "$R/.qoder/scripts/wlkj.py" <命令>`。
 
 ## Engine: init_doctor.py (幂等, 增量, 永不重头再来)
 
@@ -28,7 +28,7 @@ R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 
 ### Case 1: /wl-init (no arguments)
 ```bash
-python "$R/.qoder/scripts/init_doctor.py"
+python "$R/.qoder/scripts/setup/init_doctor.py"
 ```
 Report the doctor's findings to the user in friendly language.
 If it found fixable issues, ask: "发现 N 个问题，要我自动修复吗？"
@@ -36,7 +36,7 @@ then run with --fix.
 
 ### Case 2/3: /wl-init 小王 [pm]
 ```bash
-python "$R/.qoder/scripts/init_doctor.py" --fix 小王 [pm]
+python "$R/.qoder/scripts/setup/init_doctor.py" --fix 小王 [pm]
 ```
 This single command does ALL of:
 1. 注册/切换开发者 (.qoder/.developer, key=value 格式) + 个人空间目录

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

@@ -44,7 +44,7 @@ User input: $ARGUMENTS
 
 ### 取上下文（1 次调用取全 8 段）
 ```bash
-python "$R/.qoder/scripts/context_pack.py" <业务词> --platform <web|app>
+python "$R/.qoder/scripts/kg/context_pack.py" <业务词> --platform <web|app>
 ```
 - 第 4 段 = 历史 PRD（防重复）
 - 第 5 段 = 相关 API
@@ -58,7 +58,7 @@ python "$R/.qoder/scripts/context_pack.py" <业务词> --platform <web|app>
 
 ### 质量门禁
 ```bash
-python "$R/.qoder/scripts/eval_prd.py" <prd.md> [原型.html]
+python "$R/.qoder/scripts/report/eval_prd.py" <prd.md> [原型.html]
 ```
 ≥ 80% 才 PASS。完整模板见 `.qoder/templates/prd-full-template.md`。
 

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

@@ -0,0 +1,43 @@
+---
+description: "需求管理: 看需求/看产出/发布"
+argument-hint: "[REQ-ID] [发布]"
+---
+
+# /wl-req 需求生命周期管理
+
+> 一个需求的所有产出(PRD/原型/任务/规格)聚合在 REQ-ID 容器, 一条命令看全貌。
+
+## 用法 (只需记 2 个姿势)
+
+| 输入 | 做什么 |
+|------|--------|
+| `/wl-req` | 列出所有需求 (跨草稿/产出/历史桶) |
+| `/wl-req REQ-2026-001` | 显示该需求的全部产出 |
+| `/wl-req REQ-2026-001 发布` | 草稿→产出→发禅道 (一步到位) |
+
+## 实现层
+
+```bash
+# 列需求
+python "$R/.qoder/scripts/report/req.py"
+
+# 看某需求全貌
+python "$R/.qoder/scripts/report/req.py" REQ-2026-001
+
+# 发布 (promote + publish)
+python "$R/.qoder/scripts/report/req.py" REQ-2026-001 发布
+```
+
+## 结构
+
+```
+workspace/members/{dev}/
+├── drafts/2026/06/W26/REQ-2026-001/   ← 草稿(私有)
+│   ├── prd.md
+│   ├── prototype.html
+│   └── tasks/
+├── outputs/2026/06/W26/REQ-2026-001/  ← 产出(团队可见, 发布后)
+│   └── exports/ (docx/pdf)
+```
+
+时间桶(YYYY/MM/Ww)内建: 本周=活动区, 历史=过去的桶, 无独立 archive。