@hupan56/wlkj 3.1.32 → 3.3.0

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

@@ -20,11 +20,22 @@ User input: $ARGUMENTS (commit message)
 5. Commit with message
 6. Pull latest from remote (sync)
 7. Push to remote
-8. Record to learning system
+8. 回流平台：提交 + push 后执行回流，把本次 commit 沉淀到平台知识层
+   ```bash
+   python -m domain.integration.return_to_platform commit --last
+   ```
+   - 自动取 HEAD commit（sha/message/author/时间）→ POST 平台 `/api/git/commits/record`
+   - message 里的 `[#REQ-xxx]` / `[#<禅道号>]` 平台自动解析，建 commit→需求 边
+   - 失败只告警不阻塞（回流是增强，主流程 commit 已落地）
 
 ## Pre-commit Quality Gate
 Before committing, check:
 - [ ] All tests pass (if /wl-test was run)
 - [ ] No TODO/FIXME left in code
 - [ ] Commit tagged [ai-generated] or [ai-assisted]
+- [ ] Commit message 含需求标记 `[#REQ-xxx]` 或 `[#<禅道号>]`（关联平台需求，回流自动建边；多需求 `[#REQ-aaa][#REQ-bbb]`）
 - [ ] Amount fields use BigDecimal (if applicable)
+
+## 下一步
+- 提交回流成功后，更新任务状态：`/wl-task finish <REQ-ID>`（标记开发完成，同步禅道）
+- 查看本次提交在需求链路的位置：平台资产中心 → 需求 → 变更史

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

@@ -1,6 +1,6 @@
 ---
 name: wl-design
-description: "设计工序入口: import 录入设计稿→spec.json(默认) / generate 按设计spec出原型 / review 评审原型。"
+description: "设计工序站: 预览(蓝湖稿→HTML预览,默认) / 扫描(看现有系统页面组件风格) / 评审(检查原型是否用系统真源)。"
 argument-hint: "[预览|扫描|评审] <蓝湖链接或功能名>"
 auto-approve: true
 allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
@@ -28,7 +28,7 @@ User input: $ARGUMENTS
 
 **场景**：设计师在蓝湖画完 UI，发链接给你，AI 一键转成 HTML 预览给产品确认交互。
 
-### 流程（2 步，走 lanhu MCP）
+### 流程（3 步，lanhu MCP + RAG 接地）
 
 **Step 1：列设计稿**
 ```
@@ -37,12 +37,35 @@ cap.mcp.call("lanhu_get_designs", {"url": "<蓝湖链接>"})
 - 蓝湖链接含 `pid`（项目 ID），如 `https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx`
 - 返回设计稿列表（名称 + 序号）
 
-**Step 2：分析出 HTML**
+**Step 2：RAG 预取真实字段/组件 + 设计 token（生成 HTML 前必做，让 HTML 接地）**
+
+生成 HTML 前，先用 RAG 把这个功能在系统里的真实字段名、组件名、设计 token 拉出来，确保生成的 HTML 用真源不瞎编：
+```python
+from capability import resolve
+cap = resolve()
+# ① rag_search 语义召回：真实字段名 / 已有同类页面 / 组件用法（词不必精确匹配）
+rag = cap.mcp.call("rag_search", {"query": "<功能名>", "top_k": 10})
+# ② 设计系统 token：主色/字号/间距/组件规范（不是随便填的色值）
+ds = cap.mcp.call("get_design_system", {"platform": "web"})   # 或 "app"
+```
+- 从 rag_search 结果里抠出：**真实字段名**（如 `vehicleNo`/`maintainDate`）、**已有同类页面**参考、**可复用组件**
+- 从 get_design_system 抠出：**颜色 token / 字号 / 间距 / 组件规范**
+- 这些是 Step 3 生成 HTML 的"真源清单"，HTML 里用到的字段名/色值必须从这里来
+
+**Step 3：分析出 HTML**
 ```
 cap.mcp.call("lanhu_get_ai_analyze_design_result", {"url": "<蓝湖链接>", "design_names": "<名称或序号或all>"})
 ```
 - 返回 **HTML+CSS 代码**（工具原文："GET VISUAL CONTENT + HTML CODE"）
 - AI 把返回的 HTML 存成文件：`workspace/members/{developer}/drafts/prototype-{feature}.html`
+- ⚠️ **接地**：HTML 里的字段名/表单项用 Step 2 rag_search 召回的真实字段名（不是蓝湖稿上的占位文字），色值/间距用 get_design_system 的 token
+
+### 🎯 接地铁律（生成 HTML 必须遵守）
+
+**HTML 里的每个字段名、每个色值、每个组件，都要有 rag_search / get_design_system 的来源，不瞎编：**
+- 表单字段 → 用 rag_search 召回的真实字段名（如 `vehicleNo` 不是"车牌号输入框"占位）
+- 颜色 → 用 get_design_system 的 token（如 `#1677ff` 不是随便填的 `#1890ff`）
+- 组件 → 用系统里已有的（Ant Design Vue / Vant），不用 emoji 当图标
 
 ### 完成后提示
 ```
@@ -62,9 +85,16 @@ cap.mcp.call("lanhu_get_ai_analyze_design_result", {"url": "<蓝湖链接>", "de
 
 **场景**：画 UI 前想看现有系统有哪些页面、用什么风格、有哪些组件可复用。
 
-### 流程（1 次调用取全）
-```
-cap.mcp.call("context_pack", {"keyword": "<功能名>", "platform": "web"})
+### 流程（RAG 语义召回 + 全上下文，1 次取全）
+
+**优先 rag_search（语义召回最全）+ context_pack，不要只靠 search_code 关键词。**
+```python
+from capability import resolve
+cap = resolve()
+# ① rag_search 语义召回：同类页面 / 字段 / 组件用法（召回最全）
+rag = cap.mcp.call("rag_search", {"query": "<功能名>", "top_k": 10})
+# ② context_pack 一次取全 8 段
+ctx = cap.mcp.call("context_pack", {"keyword": "<功能名>", "platform": "web"})
 ```
 返回 8 段：相关代码 + 同类页面 + 字段 + API + 风格 token + 组件 + 数据库表结构。
 
@@ -126,3 +156,37 @@ PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)`
 ```bash
 $PY "$R/.qoder/scripts/orchestration/wlkj.py" learn record review_done "{\"target\":\"$feature\",\"result\":\"$pass_or_issues\"}"
 ```
+
+---
+
+## 🔄 回流平台（原型生成后即执行，别漏）
+
+**铁律：HTML 预览生成后必须回流平台**（否则平台 AI回流 Tab 永远空，知识层↔引擎断裂）。
+回流走平台 MCP 写工具（`create_prototype` / `submit_return`），失败不影响主流程。
+
+原型存成文件后跑这一条（用前面定的 `$PY` / `$R` 变量）：
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" return prototype <原型HTML路径> "<功能名>" --platform <web|app>
+```
+- 内部优先调 `cap.mcp.call("create_prototype", {feature, platform, html_content})` 写 prototype 表 + 存 HTML；
+- 失败再 `submit_return`（return_type=prototype）写 returns 待审核；最后 HTTP 兜底（读 mcp_config.json 的 return_endpoint）。
+- 全程 try/except，回流失败原型仍在本地，主流程不阻塞。
+
+> 等价的 MCP 直调写法（脚本不可用时的兜底）：
+> `cap.mcp.call("create_prototype", {"feature": "<功能名>", "platform": "web", "html_content": "<完整HTML>"})`
+> 或 `cap.mcp.call("submit_return", {"title":"原型-<功能>", "return_type":"prototype", "source":"/wl-design", "content_full":"<HTML>"})`
+
+回流成功后输出一行：`✅ [回流] via=create_prototype/submit_return <message>`。
+
+## 🧠 学习沉淀（原型生成后即执行，反哺下次）
+
+生成原型时发现的设计规律/用户偏好/页面结构经验，调 learn 写回平台：
+```python
+cap.mcp.call("learn", {
+    "project_id": "<项目UUID>",
+    "category": "preference",    # preference=设计偏好 / rule=页面规律 / decision=组件选择
+    "pattern": "<学到的，如：车辆列表页用紧凑表格+状态色彩标签，搜索栏放右上角>",
+    "source": "wlkj/wl-design",
+})
+```
+- 至少写 1 条。try/except 不阻塞。

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

@@ -57,6 +57,33 @@ After doctor finishes:
 |------|------|
 | 本周已 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 直接拿到, 本机不用构建 |
 

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

@@ -13,8 +13,36 @@ User input: $ARGUMENTS
 > **写需求 / 评审需求，一个命令搞定。**
 > 模块契约：`.qoder/contracts/prd.md`
 
+## 🔧 工具优先级（宿主能力 × 知识层分工）
+| 步骤 | 用谁 | 原因 |
+|------|------|------|
+| 搜文件内容 | **Qoder Grep/Read** | 精确搜代码，原生更快 |
+| 取业务上下文 | **MCP context_pack** | 语义聚合8段(代码+API+字段+Wiki+PRD) |
+| 取团队记忆 | **MCP get_learnings** | 引擎积累的业务规则 |
+| 查真表结构 | **MCP query_schema** | 数据库真实列名 |
+| 生成 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 只是让结构更完整、不漏章节。
+
 ## 🚦 路由（看第一个词或描述特征）
 
+### 🔴 命令优先铁律（最重要，先读）
+**只要用户打了 `/wl-prd`，就必须产出 PRD，绝不跨命令跑去别处。**
+哪怕描述含"报错/无法提交/bug/异常"这类词（如"养护计划无法提交，时间报错"——这是要为修复写需求），也走本命令出 PRD，**不准**跑去 `/wl-test`（测试）/ `/wl-code`（直接改码）/ 排查。
+- 用户要写需求 → 本命令（不管描述像 bug 还是新功能）
+- 用户要直接改代码 → 那是 `/wl-code`，但前提是用户打的是 `/wl-code`
+- 判断不准 → 问一句，不要擅自换命令
+
 | 用户说 | 模式 | 走哪个 |
 |--------|------|--------|
 | "完整""深度""正经需求" 或 描述含"新模块/新业务/新流程" | **完整** | prd-full-template（13 章）|
@@ -29,32 +57,84 @@ User input: $ARGUMENTS
 
 ---
 
+## 🔧 仓库根定位（完整档/快速档共用，进任何模式前先跑这一条）
+
+> QoderWork 桌面端 cwd 不在仓库根（在 `.qoderwork/workspace/xxx`），相对路径
+> `.qoder/scripts/...` **必然失败**（真实踩坑：连续 2 条命令报错浪费一轮）。
+> 进模式前**必须先定位仓库根**。Mac 只有 python3，两个都试：
+
+```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/..."` 都用这两个变量。**不准自己编 `cd /d` / 裸相对路径**。
+
+---
+
 ## 完整模式（13 章 PRD）
 
 **新模块/新业务/新流程用这个。** 支持衔接 insight：`参考:<报告路径>`
 
 **铁律：平台必问。** 先问：
-``
+```
 这个需求是针对哪个平台？
 1. Web 管理端 (fywl-ui)
 2. APP 移动端 (Carmg-H5)
 3. 两端都要
 请选择 (1/2/3):
-``
+```
 
-### 取上下文（1 次调用取全 8 段）
-先定位仓库根（Mac 只有 python3, 两个都试）:
-``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)
-``
-``bash
+### 取上下文（context_pack Fast Path 为主 + rag_search/context_360 兜底 — 语义召回最全，接地写 PRD）
+
+**写 PRD 前必做的知识预取：Fast Path 用 context_pack 一次取全（代码+API+字段+风格+相关PRD），替代 rag_search+context_360 两次往返；再叠 ask_corpus（业务流程）+ get_learnings（之前学到的）+ query_schema（真库表结构）。不要只靠 search_code 关键词。**
+
+```python
+from capability import resolve
+cap = resolve()
+# ⓪ req_trace 查同需求历史画像（防重复造轮子）：有 REQ-ID 时先查这个需求已有哪些 PRD/代码/表
+if <有 REQ-ID>:
+    cap.mcp.call("req_trace", {"req_id": "<REQ-ID>"})  # 返回 PRD+代码+表+测试，避免重复写已有功能
+# ① context_pack Fast Path（1 次往返取全上下文：代码+API+字段+风格+相关PRD）
+#    等价于 rag_search + context_360 合并，轮次减半（原 5 次 → 3 次）
+pack = cap.mcp.call("context_pack", {"query": "<业务词或需求描述>", "project_id": "<项目UUID>"})
+# ①b 召回不够（缺某类/命中为空）时单独补 rag_search 一次（语义召回兜底，fallback）
+if not pack.get("items"):
+    rag = cap.mcp.call("rag_search", {"query": "<业务词或需求描述>", "top_k": 10})
+# ①c 仍需某核心业务对象的完整关联（代码+页面+字段+API）时，补 context_360（fallback）
+if <需要某符号的全上下文>:
+    ctx = cap.mcp.call("context_360", {"symbol": "<核心业务对象>"})
+# ② 有"业务流程整体怎么运转"的疑问时，补 ask_corpus 拿 GraphRAG 答案
+flow = cap.mcp.call("ask_corpus", {"q": "<业务词>的业务流程是什么", "top_k": 3})
+# ③ get_learnings 查之前学到的业务规则/偏好（反哺：上次踩的坑这次别犯）
+learnings = cap.mcp.call("get_learnings", {"project_id": "<项目UUID>", "limit": 10})
+# ④ query_schema 查真实数据库表结构（引擎自己的 MySQL MCP，拿到的真表回流平台）
+#    推断涉及哪些表（从 pack 命中里找表名），查真结构
+schema = cap.mcp.call("query_schema", {"table": "<表名>"})  # 引擎 qoder-mysql 工具
+# 查到后把真表结构回流平台（learn 写回，平台数据库知识就有了真实数据）
+if schema and schema.get("columns"):
+    cap.mcp.call("learn", {"project_id":"<项目UUID>", "category":"rule",
+        "pattern": f"数据库表<表名>结构: {json.dumps(schema.get('columns',[]), ensure_ascii=False)[:500]}",
+        "source": "wlkj/wl-prd+mysql"})
+# PRD 里的字段表优先用 query_schema 查到的真实列（最接地），其次用 context_pack 召回的代码字段
+```
+# 写 PRD 时参考 learnings 里的规则/偏好/决策，在相关章节体现
+```
+等价 CLI（脚本兜底）：
+```bash
 $PY "$R/.qoder/scripts/orchestration/wlkj.py" context <业务词> --platform <web|app>
-``
+```
 - 第 4 段 = 历史 PRD（防重复）
 - 第 5 段 = 相关 API
 - 第 8 段 = 数据库表结构+真实字段
-- 涉及枚举字段时额外调 `cap.mcp.call("query_distinct`
+- 涉及枚举字段时额外调 `cap.mcp.call("query_distinct")`
+
+### 🎯 接地铁律（写 PRD 必须遵守）
+
+**用 rag_search 召回的知识写 PRD，每条功能/字段都要有 rag_search 命中的来源，不编造。**
+- PRD 里写的每个字段名 → 必须在 rag_search/context_360 结果里能找到（或来自 query_schema 真实表结构）
+- PRD 里写的每个 API → 必须在召回结果里有对应端点
+- 召回不到的字段/API → 标注"新增（待评估）"，不要假装已存在
+- 业务流程描述 → 优先采纳 ask_corpus 的 GraphRAG 回答（有全局视角），再用 rag_search 的事实补充
 
 ### 产出
 - PRD: `workspace/members/{dev}/drafts/REQ-{YYYY}-{NNN}-{标题}.md`（13 章）
@@ -63,7 +143,7 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" context <业务词> --platform <we
 
 ### 原型要不要画？（融入批量确认）
 
-**默认建议**（用户可一键改，详见 `.qoder/skills/wl-prd-full/SKILL.md` STEP 0.5）：
+**默认建议**（用户可一键改）：
 - 纯规则/接口/定时/参数/计算类 → **不画**（如"出交车点检固定为总部全局规则"）
 - 含页面/菜单/表单/弹窗/详情/向导/看板/大屏 → **画**
 - 加字段/按钮/文案/导出 → **不画**
@@ -75,9 +155,9 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" context <业务词> --platform <we
 eval 自动跳过 A2（满分从 100 降到 70，照样 PASS）；`/wl-design` `/wl-code` 据此跳过原型环节。
 
 ### 质量门禁
-``bash
+```bash
 $PY "$R/.qoder/scripts/orchestration/wlkj.py" eval <prd.md> [原型.html]
-``
+```
 ≥ 80% 才 PASS。完整模板见 `.qoder/templates/prd-full-template.md`。
 
 ---
@@ -88,9 +168,30 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" eval <prd.md> [原型.html]
 
 **平台必问**（同上）。
 
+### 取上下文（RAG 语义预取，禁止串行 search）
+
+**优先 rag_search（语义召回最全）+ prefetch，不要只靠逐个 search_code 关键词。**
+
+```python
+from capability import resolve
+cap = resolve()
+# ① rag_search 一次语义召回：代码/字段/API/Wiki 全拿到（按相关度排序）
+rag = cap.mcp.call("rag_search", {"query": "<需求描述>", "top_k": 8})
+```
+等价 CLI：
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" prefetch "<需求描述>" --platform <p>
+```
+prefetch/rag_search 一次返回代码/字段/API/Wiki/历史 PRD。**之后不要逐个 search/find/grep 查词**（会变 6+ 次串行往返，轮次爆炸根因）。不够才补调一次。
+
+**接地铁律（同完整模式）**：6 章里写的每个字段/API 必须在 rag_search 召回结果里有来源，召不到的标"新增（待评估）"，不编造。
+
 ### 产出
 - Mini-PRD: `workspace/members/{dev}/drafts/REQ-{YYYY}-{NNN}-{标题}.md`（6 章）
-- 6 章：功能入口 / 需求背景 / 需求说明 / 影响范围 / 验收标准 / 不在本次范围
+- **6 章缺一不可（铁律）**：功能入口 / 需求背景 / 需求说明 / 影响范围 / 验收标准 / 不在本次范围
+  > 🚫 **禁止只写 1-2 章就交差**（真实反面教材：海外考勤 PRD 只写了"功能入口"一段就停，6 章缺 5 章 → 残废品）。
+  > 即使是 bug 修复，也要写全 6 章（需求背景=bug 现象、需求说明=修复方案、验收标准=修复后行为）。
+  > 不涉及的章节写"不涉及"或一句话说明，**标题必须保留，不许整章省略**。Stop hook 会检测缺章并阻断。
 - 模板见 `.qoder/templates/prd-quick-template.md`
 
 ---
@@ -115,3 +216,117 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" eval <prd.md> [原型.html]
 ## 埋点
 
 PRD 生成/评审后自动记录到 learning（eval_prd.py 已内置）。
+
+**评审模式额外**：给出 PASS/FAIL 结论后立即记一条 `review_done`（可用性指标 F2 评审级数据唯一来源，不埋则该级永远为 0）：
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" learn record review_done "{\"prd\": \"<被评审PRD名>\", \"verdict\": \"PASS|FAIL\"}"
+```
+埋点失败不阻塞，但能埋一定要埋。
+
+---
+
+## 📤 发禅道（PRD 写完后的衔接，完整/快速档都问）
+
+PRD 产出后，**主动问一句**（不要默默结束）：
+```
+PRD 已写好: <路径>
+要发到禅道吗？(发禅道 = 建禅道需求 + 可选关联计划/版本)
+```
+
+### 用户说"发" → 交互式逐项确认（不要一次性全问，按需）
+
+用禅道 MCP 现查现选（QoderWork: `qw_mcp_call`）：
+
+**① 选产品（必选）**
+- `list_products()` → 列出现有产品 → 让用户选 product_id
+- 禅道需求必须挂产品，没产品发不了
+
+**② 关联计划？（可选，问一句）**
+```
+要关联到计划(迭代)吗？(可跳过)
+```
+- 用户要 → `list_plans(product_id=<上一步选的>)` → 选 plan_id
+- 跳过 → 不传 plan
+
+**③ 挂版本？（可选，问一句）**
+```
+要纳入某个版本(build)吗？(可跳过)
+```
+- 用户要 → `list_builds(project_id=N)` → 选 build_id（⚠️ builds 按项目维度查最常见，禅道无"全量版本"端点）
+- 跳过 → 不传 build
+
+**④ 执行发布**
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" req <REQ-ID> 发布 \
+    --product=<①> [--plan=<②>] [--build=<③>] --confirm
+```
+- 默认先 dry-run 预览，用户确认后再 `--confirm` 真发
+- 真发后禅道建好需求，PRD 末尾自动回写 `<!-- zentao: story=ID -->` 留痕
+
+> **禅道 story ID 回流平台**：建完禅道需求后，把 story ID 通过平台 MCP learn 工具写回：
+> ```python
+> cap.mcp.call("learn", {"project_id":"<项目UUID>","category":"decision",
+>     "pattern": f"PRD<{标题}> 已发禅道: story=#{story_id} product={product_id}",
+>     "source": "wlkj/wl-prd+zentao"})
+> ```
+> 这样平台知道这个 PRD 对应禅道哪个需求（跨系统关联）。
+
+> 用户说"不发" → 不勉强，PRD 留本地，后续可随时 `/wl-req <REQ-ID> 发布`。
+> 直连禅道 HTTP（脚本内部），AI 只触发一次，几乎不耗 token。
+
+---
+
+## 🔄 回流平台（PRD 写完即执行，别漏）
+
+**铁律：PRD 落地后必须回流平台**（否则平台 AI回流 Tab 永远空，知识层↔引擎断裂）。
+回流走平台 MCP 写工具（`create_prd` / `submit_return`），失败不影响主流程。
+
+PRD 写完后跑这一条（用前面定的 `$PY` / `$R` 变量）：
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" return prd <PRD文件路径> "<PRD标题>" --platform <web|app>
+```
+- 内部优先调 `cap.mcp.call("create_prd", {title, content_md})` 写 PRD 表 + 首版本；
+- 失败再 `submit_return` 写 returns 待审核；最后 HTTP 兜底（读 mcp_config.json 的 return_endpoint）。
+- 全程 try/except，回流失败 PRD 仍在本地，主流程不阻塞。
+
+> 等价的 MCP 直调写法（脚本不可用时的兜底）：
+> `cap.mcp.call("create_prd", {"title": "<标题>", "content_md": "<完整PRD正文>", "status": "planning"})`
+> 或 `cap.mcp.call("submit_return", {"title":"...", "return_type":"prd", "source":"/wl-prd", "content_preview":"...", "content_full":"..."})`
+
+回流成功后输出一行：`✅ [回流] via=create_prd/submit_return <message>`。
+
+## 🧠 学习沉淀（PRD 写完即执行，反哺下次）
+
+**铁律：写 PRD 过程中学到的业务规则/决策/用户偏好，必须调 `learn` 写回平台**（平台 learning_patterns 积累，下次引擎受益——越用越聪明）。
+
+写完 PRD 后，把学到的关键认知调 learn 写回：
+```python
+cap.mcp.call("learn", {
+    "project_id": "<项目UUID>",
+    "category": "rule",          # rule=业务规则 / preference=用户偏好 / decision=决策 / pitfall=踩坑
+    "pattern": "<学到的内容，如：车辆保养需关联驾驶员和车辆，按里程+时间双触发>",
+    "source": "wlkj/wl-prd",
+})
+```
+- 每次至少写 1 条（最关键的业务规则或决策）。
+- 多条可多次调用。
+- 全程 try/except，失败不阻塞主流程。
+
+输出：`✅ [学习] 沉淀 N 条认知到平台`。
+
+## 📊 工作流轨迹回写（若本次是被平台触发的）
+
+如果本次 /wl-prd 是平台 trigger 派来的（有 triggerId），执行完后回填轨迹：
+```python
+# 通过 PATCH /api/projects/{pid}/trigger/workflow/{triggerId} 回填
+# body: {status: "success", output_summary: "生成了<标题>PRD", knowledge_used: [...], mcp_tools_called: [...], duration_sec: N}
+```
+- knowledge_used：rag_search/search 命中的关键实体 id 列表
+- mcp_tools_called：本次调过的 MCP 工具名（rag_search/context_360/create_prd/learn 等）
+- 让平台"引擎活动看板"能看到本次执行全貌（取了什么知识→产出什么→学了什么）
+- try/except 不阻塞。
+
+## 下一步
+- PRD 定稿 → `/wl-task create <标题>` 落成任务（带 REQ-ID 衔接）+ 发禅道
+- 开工前 → `/wl-spec` 生成开发 Spec → 确认后 `/wl-code` 实现
+- 完整链：prd → task → spec → code → test → commit → task finish（双通飞轮）

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

@@ -14,7 +14,7 @@ argument-hint: "[REQ-ID] [发布]"
 |------|--------|
 | `/wl-req` | 列出所有需求 (跨草稿/产出/历史桶) |
 | `/wl-req REQ-2026-001` | 显示该需求的全部产出 |
-| `/wl-req REQ-2026-001 发布` | 草稿→产出→发禅道 (一步到位) |
+| `/wl-req REQ-2026-001 发布` | 草稿→产出→**真发禅道**(建需求+关联计划+纳入版本) |
 
 ## 实现层
 
@@ -29,10 +29,17 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" req
 # 看某需求全貌
 $PY "$R/.qoder/scripts/orchestration/wlkj.py" req REQ-2026-001
 
-# 发布 (promote + publish)
-$PY "$R/.qoder/scripts/orchestration/wlkj.py" req REQ-2026-001 发布
+# 发布 (promote + publish)。默认 dry-run 只预览, --confirm 才真写禅道
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" req REQ-2026-001 发布 --product=1
+# 真发(建需求→关联计划→纳入版本, 一步到位)
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" req REQ-2026-001 发布 --product=1 --plan=12 --build=8 --confirm
 ```
 
+> **产品/计划/版本从哪来**: 命令行 `--product/--plan/--build` 优先; 或在 PRD 顶部标
+> `<!-- zentao: product=1 plan=12 build=8 -->` 自动读取。缺产品ID会停(禅道需求必须挂产品)。
+> 发布后 PRD 末尾自动回写 `<!-- zentao: story=762 -->` 留痕, 防重复建。
+> 直连禅道 HTTP(不走MCP), AI 只触发一次 → 几乎不耗 token。
+
 ## 结构
 
 ```

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

@@ -1,12 +1,12 @@
 ---
 name: wl-search
 description: "查代码/业务/API/字段/PRD + 知识图谱(影响分析/覆盖矩阵/功能画像/业务流程/多跳遍历)的唯一入口。"
-argument-hint: "[keyword] or --api [path] or subcommand. 全系13个能力见下表"
+argument-hint: "[keyword] or --api [path] or subcommand. 全系15个能力见下表"
 auto-approve: true
 allowed-tools: [Read, Bash]
 ---
 
-# /wl-search - 搜索代码 & 知识图谱
+# /wl-search - 搜索代码 & 知识图谱 & RAG 语义检索
 
 User input: $ARGUMENTS
 
@@ -15,27 +15,71 @@ User input: $ARGUMENTS
 ```python
 from capability import resolve
 cap = resolve()
-result = cap.mcp.call("search_code", {"keyword": "保险", "platform": "web"})
+result = cap.mcp.call("rag_search", {"query": "车辆保养", "top_k": 8})
 ```
 
-自动路由：有 MCP 走 MCP（快），无 MCP 走 wlkj.py（CLI 降级）。零宿主感知。
+自动路由：有 MCP 走 MCP（直连平台知识层，快），无 MCP 走 wlkj.py（CLI 降级）。零宿主感知。
 
-## ⚡ 第一步：先判断问题类型，别一上来就 search
+## ⚡ 第一步：先判断问题类型，选对检索通道（3 路检索）
 
-| 问题类型 | 首选（一次到位） | ❌ 别这样 |
-|---------|-----------------|----------|
-| **"XX怎么实现的/怎么做的"** | `cap.mcp.call("context_pack", {"keyword": "XX", "role": "dev"})` | 不要一个个 search（会搜 5-7 次，慢费 token） |
-| **"XX代码在哪"** | `cap.mcp.call("search_code", {"keyword": "XX"})` | 不要 context（杀鸡用牛刀） |
-| **"改 XX 影响谁"** | `cap.mcp.call("get_impact", {"endpoint": "/XX"})` | — |
+**核心升级：本命令有 3 路检索，按问题类型选最合适的一路（不是无脑 search_code）。**
 
-> 理解一个功能怎么做的问题，`context_pack` 一条命令拿全代码+API+字段，绝大多数情况只需 Read 2-3 个文件就够，
-> 不用反复 search。Glob 找不到文件时用 search_code 兜底，**不准跑 find/findstr/dir /s**。
+| 问题类型 | 首选检索通道 | 为什么 |
+|---------|-------------|--------|
+| **"车辆保养"相关的代码/字段/API**（语义找相关，词不必一样） | `rag_search` 语义召回 | 能找到"维修记录"即使没共享词，召回最全 |
+| **"这个功能的业务流程是什么 / 整体怎么运转"**（全局问答） | `ask_corpus` GraphRAG 问答 | 用社区摘要直接答，不是堆代码片段 |
+| **"handleExport 这个符号在哪定义/调用"**（精确符号定位） | `search_code` 关键词 | 精确命中，找特定符号最快 |
+| **"XX怎么实现的/怎么做的"**（一次取全代码+API+字段） | `context_pack` | 一条命令拿全 8 段上下文 |
+| **"改 XX 影响谁"** | `get_impact` | 影响分析专用 |
 
-## 13 个能力（统一 cap.mcp.call 调用）
+> **顺序铁律**：理解/盘点类问题，**先 rag_search（语义召回最全）**；有"整体流程/业务怎么运转"的全局问题，**再补 ask_corpus（GraphRAG 答案级）**；只在精确找某个符号/特定字符串时才用 search_code。
+> Glob 找不到文件时用 search_code 兜底，**不准跑 find/findstr/dir /s**。
+
+### 三路检索详解（RAG 升级核心）
+
+**① rag_search — 语义召回（默认首选，召回最全）**
+```python
+# 语义检索：query 是自然语言/业务词，不必和代码里的词一样
+# 能找到"车辆保养"相关的"维修记录"，即使两者没共享词
+cap.mcp.call("rag_search", {"query": "车辆保养流程", "top_k": 8})
+```
+- 返回：相关代码片段 / 字段 / API，按语义相关度排序
+- 适用：写 PRD/改代码前找相关实现、盘点某业务有哪些代码、关键词搜索召回不全时
+- `top_k` 默认 8，要更全调到 12-15
+
+**② ask_corpus — GraphRAG 全局问答（答业务流程类问题）**
+```python
+# GraphRAG 社区摘要问答：直接给"答案"，不是堆代码片段
+# 能答"资产管理的业务流程是什么""这个功能整体怎么运转"
+cap.mcp.call("ask_corpus", {"q": "车辆保养的整体业务流程是什么", "top_k": 3})
+```
+- 返回：基于知识图谱社区摘要的自然语言回答
+- 适用：问"整体流程/业务怎么运转/这个功能是干嘛的"等全局问题
+- ⚠️ 引擎工具名是 `ask_corpus`，平台侧映射到 `graphrag_ask`（mcp_config.json 已配）
+
+**③ search_code — 精确关键词（找特定符号/字符串）**
+```python
+# 精确关键词：找特定函数名/类名/字符串字面量
+cap.mcp.call("search_code", {"keyword": "handleExport", "platform": "web"})
+```
+- 返回：精确命中的代码位置
+- 适用：已知符号名要定位、rag_search 召回了但要精确找某行
+
+### 输出整合（三路并用时）
+
+理解一个功能时，建议 **rag_search + ask_corpus 并用**：
+1. `rag_search` 拿到相关代码/字段/API（事实依据）
+2. `ask_corpus` 拿到业务流程的自然语言回答（全局视角）
+3. 整合：先讲业务流程（来自 ask_corpus），再列相关代码/字段（来自 rag_search）
+4. 精确符号定位才补 `search_code`
+
+## 知识图谱能力（20+，统一 cap.mcp.call 调用）
 
 | 用户要查什么 | 调用方式 |
 |-------------|---------|
-| 代码在哪 / 搜关键词 | `cap.mcp.call("search_code", {"keyword": "考勤", "platform": "web"})` |
+| **语义找相关代码/字段（首选，召回最全）** | `cap.mcp.call("rag_search", {"query": "车辆保养", "top_k": 8})` |
+| **GraphRAG 全局业务流程问答** | `cap.mcp.call("ask_corpus", {"q": "保养流程是什么", "top_k": 3})` |
+| 代码在哪 / 精确搜关键词 | `cap.mcp.call("search_code", {"keyword": "考勤", "platform": "web"})` |
 | API 端点 | `cap.mcp.call("search_api", {"keyword": "salary"})` |
 | 已有 PRD（防重复造轮子） | `cap.mcp.call("search_prd", {"keyword": "保险"})` |
 | 改某接口影响哪些页面 | `cap.mcp.call("get_impact", {"endpoint": "/asset"})` |
@@ -45,18 +89,25 @@ result = cap.mcp.call("search_code", {"keyword": "保险", "platform": "web"})
 | 功能完整画像 | `cap.mcp.call("feature_overview", {"feature": "资产管理"})` |
 | 业务流程链（几步） | `cap.mcp.call("get_workflow", {"module": "assets"})` |
 | 多跳遍历（关联实体） | `cap.mcp.call("multi_hop", {"symbol": "资产管理", "depth": 3})` |
+| **业务链路追踪（概念→PRD+代码+表+测试）** | `cap.mcp.call("business_trace", {"query": "保险理赔", "depth": 3})` |
+| **需求全貌（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": "保险单"})` |
+| **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"})` |
 
 ## 快速判断该用哪个
 
+- **"这个功能怎么实现 / 相关代码有哪些"** → 先 `rag_search`（语义最全），不够再 `search_code`
+- **"这个功能的业务流程是什么 / 整体怎么运转"** → `ask_corpus`（GraphRAG 问答）
 - **"这个功能已经有了吗"** → `prd` 查需求 + `feature` 看画像
 - **"改这个会影响谁"** → `impact`
 - **"哪些功能缺测试"** → `coverage`
-- **"盘点流程有几步"** → `workflow`
+- **"盘点流程有几步"** → `workflow` 或 `ask_corpus`
 - **"XX 谁调用了/调用链"** → `context360` 或 `hop`
-- **写 PRD 前一次取全** → `context_pack --role pm`
+- **写 PRD 前一次取全** → `rag_search` + `context_pack --role pm`
 - **出原型前** → `design_system` + `fill_prototype`
 
 ## 字段/页面风格/组件
@@ -107,13 +158,16 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" kg grep-text 车辆不存在 --ext
 
 ## How to Use Results
 
-1. Pick the most relevant files (2-3 max)
-2. Read ONLY those files directly
-3. Answer the user's question — 提炼后回答，别贴原始输出
+1. 三路检索并用时：先讲业务流程（ask_corpus），再列相关代码/字段（rag_search），精确符号补 search_code
+2. Pick the most relevant files (2-3 max)
+3. Read ONLY those files directly
+4. Answer the user's question — 提炼后回答，别贴原始输出
 
 ## Examples
 
-- `/wl-search 考勤` → `cap.mcp.call("search_code", {"keyword": "考勤"})`
+- `/wl-search 车辆保养` → 先 `rag_search({"query":"车辆保养","top_k":8})`（语义最全），有流程问题再 `ask_corpus({"q":"车辆保养流程"})`
+- `/wl-search 车辆保养的业务流程是什么` → `cap.mcp.call("ask_corpus", {"q": "车辆保养的业务流程是什么", "top_k": 3})`
+- `/wl-search handleExport 在哪` → `cap.mcp.call("search_code", {"keyword": "handleExport"})`（精确符号）
 - `/wl-search --api salary` → `cap.mcp.call("search_api", {"keyword": "salary"})`
 - `/wl-search 改 /asset 影响谁` → `cap.mcp.call("get_impact", {"endpoint": "/asset"})`
 - `/wl-search 哪些功能没测试` → `cap.mcp.call("coverage_matrix", {})`