@hupan56/wlkj 3.2.0 → 3.3.1

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

@@ -19,6 +19,35 @@ 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（强制门禁 · 非建议）
+
+> ⚠️ **代码写完必须过 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（强制前置 · 非侵入式）
 
 > ⚠️ **核心门禁**：没有 `status: confirmed` 的 spec，**绝不动手写代码**。
@@ -30,7 +59,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 +113,70 @@ 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 语义召回，不只关键词）
+
+**改代码前用 rag_search 找相关函数/API（语义召回最全），精确符号定位才用 search_code。**
 
-Run: $PY "$R/.qoder/scripts/orchestration/wlkj.py" search <keyword>
+```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
+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,
+})
+# ③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字段/前端表单"
+# ④ 涉及数据库改动的，查真表结构（引擎自己的 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:
@@ -98,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:
@@ -108,4 +197,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

@@ -1,102 +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 增量更新, 只处理变更文件 |
-| 全新机器 | 克隆仓库 + 全量构建一次, 之后永远增量 |
-| 团队其他人已更新图谱 | 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` 自动跑 |