@hupan56/wlkj 3.2.0 → 3.3.0

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

@@ -19,6 +19,26 @@ PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
 ```
 > 后续脚本统一用 `$PY "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
 
+## 🔧 工具优先级（宿主能力 × 知识层分工）
+| 步骤 | 用谁 | 原因 |
+|------|------|------|
+| 精确找符号 handleExport | **Qoder Grep** | 原生正则搜，零延迟 |
+| 读文件看实现 | **Qoder Read** | 原生全量读，MCP 只有预览 |
+| 语义找"导出功能" | **MCP rag_search** | 跨仓库语义召回 |
+| 改代码前看影响 | **MCP get_impact** | 跨3端影响分析，Qoder 做不到 |
+| 文件知识标注 | **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 只是让审查更全面（边界条件/性能/安全）。
+
 ## Step 1: Spec Gate（强制前置 · 非侵入式）
 
 > ⚠️ **核心门禁**：没有 `status: confirmed` 的 spec，**绝不动手写代码**。
@@ -30,7 +50,7 @@ PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
 # 用 paths.find_spec 确定性查找 (查 .qoder/workspace/specs/ + 当前任务目录, 读 status)
 SPEC=$($PY -c "
 import sys, json; sys.path.insert(0,'$R/.qoder/scripts')
-from bootstrap import setup; setup()
+from foundation.bootstrap import setup; setup()
 from foundation.core.paths import find_spec, get_spec_status
 hits = find_spec('$ARGUMENTS') if '$ARGUMENTS' else find_spec()
 if hits:
@@ -84,12 +104,46 @@ cap.mcp.call("update_task", {"task_id": X, "desc": summary + "\n本地spec: " +
 
 > panel 也可调同一个 `update_task` 做回填，两边都行（谁先触发都行，不冲突）。
 
-## Step 2: Search Related Code
+## Step 2: Search Related Code（RAG 语义召回，不只关键词）
 
-Run: $PY "$R/.qoder/scripts/orchestration/wlkj.py" search <keyword>
+**改代码前用 rag_search 找相关函数/API（语义召回最全），精确符号定位才用 search_code。**
+
+```python
+from capability import resolve
+cap = resolve()
+# ① rag_search 语义召回：找和需求相关的函数/API/字段（词不必一样，召回最全）
+rag = cap.mcp.call("rag_search", {"query": "<需求关键词或功能描述>", "top_k": 10})
+# ② 需要精确找某个已知符号（如 handleExport）才用 search_code
+precise = cap.mcp.call("search_code", {"keyword": "<精确符号名>"})
+# ③ 影响分析（必跑）：改这些符号会影响谁/依赖谁，按项目仓库隔离，避免改一处崩一片
+#    project_id 从 mcp_config.json 的 WLKJ_PROJECT_ID 取（绑当前项目）
+#    get_impact 返回分层 upstream(谁依赖我→改动影响范围)/downstream(我依赖谁)+byType
+impact = cap.mcp.call("get_impact", {
+    "project_id": "<项目UUID>",   # mcp_config.json 的 WLKJ_PROJECT_ID
+    "entity": "<要改的核心符号: 如 handleExport / C:FlowOperationController>",
+    "depth": 2,
+})
+# 影响面大（upstream 跨多个页面/API）时，先在回复里提示风险再动手
+# ③b 涉及字段改动（加列/改类型/表单字段）：追字段全链路（表单→接口→Java字段→DB列），改一处看全链
+if <涉及字段层>:
+    cap.mcp.call("trace_dataflow", {"field": "<字段名>"})  # 防"改了DB列没改对应Java字段/前端表单"
+# ④ 涉及数据库改动的，查真表结构（引擎自己的 MySQL MCP，别猜列名）
+if <涉及数据库层>:
+    schema = cap.mcp.call("query_schema", {"table": "<表名>"})  # qoder-mysql 工具
+    # 真表结构回流平台
+    cap.mcp.call("learn", {"project_id":"<项目UUID>","category":"rule",
+        "pattern": f"真表结构<表名>: {json.dumps(schema.get('columns',[]),ensure_ascii=False)[:400]}",
+        "source":"wlkj/wl-code+mysql"})
+```
+等价 CLI（脚本兜底）：
+```bash
+$PY "$R/.qoder/scripts/orchestration/wlkj.py" search <keyword>
+```
 Find existing code that this implementation relates to.
 Read relevant files for context.
 
+**接地铁律**：实现时调用的函数名/字段名/API 路径必须来自 rag_search 召回结果（系统里真有的），不编造不存在的 API。改码前用 get_impact 拿分层影响范围（谁依赖我/我依赖谁），影响面大先提示风险再动手，避免改一处崩一片。
+
 ## Step 3: Implement
 
 Follow the spec strictly:
@@ -108,4 +162,22 @@ After implementation:
 
 ## Step 5: Report
 
-Tell user what was implemented and suggest /wl-test next.
+Tell user what was implemented and suggest next:
+- `/wl-test <描述>` — 跑测试验证（改动大时先 `impact_coverage` 圈必跑范围）
+- 验过后 `/wl-commit <message>` — 提交+push+回流平台（自动 record_commit）
+
+## 下一步
+- 实现 → `/wl-test` 验证 → `/wl-commit` 提交回流 → `/wl-task finish <REQ-ID>` 收尾（双通飞轮）
+
+## 🧠 学习沉淀（改完代码即执行，反哺下次）
+
+改代码过程中发现的业务规则/架构约定/踩坑经验，调 learn 写回平台：
+```python
+cap.mcp.call("learn", {
+    "project_id": "<项目UUID>",
+    "category": "pitfall",       # pitfall=踩坑 / rule=业务规则 / decision=架构决策
+    "pattern": "<学到的，如：VehicleController 的 save 方法必须先校验驾驶员是否存在>",
+    "source": "wlkj/wl-code",
+})
+```
+- 至少写 1 条最有价值的认知。try/except 不阻塞。

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

@@ -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,6 +13,27 @@ 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 只是让结构更完整、不漏章节。
+
 ## 🚦 路由（看第一个词或描述特征）
 
 ### 🔴 命令优先铁律（最重要，先读）
@@ -63,14 +84,57 @@ PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
 请选择 (1/2/3):
 ```
 
-### 取上下文（1 次调用取全 8 段）
+### 取上下文（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 章）
@@ -104,11 +168,23 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" eval <prd.md> [原型.html]
 
 **平台必问**（同上）。
 
-### 取上下文（1 次 prefetch，禁止串行 search）
+### 取上下文（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 一次返回代码/字段/API/Wiki/历史 PRD。**之后不要逐个 search/find/grep 查词**（会变 6+ 次串行往返，轮次爆炸根因）。不够才补调一次。
+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 章）
@@ -187,5 +263,70 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" req <REQ-ID> 发布 \
 - 默认先 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-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", {})`