@hupan56/wlkj 3.1.32 → 3.3.0

package/bin/cli.js

@@ -1249,6 +1249,10 @@ function doHelp() {
   console.log("  或斜杠: /wl-prd /wl-design /wl-task /wl-code /wl-test /wl-commit");
   console.log("  (提交/同步 /wl-task 和 /wl-commit 会自动做, 不用单独 npx sync)");
   console.log("");
+  console.log("=== 能力市场 ===");
+  console.log("  npx @hupan56/wlkj install skill <token> --host <url>  从市场装 Skill 到本地 IDE");
+  console.log("  npx @hupan56/wlkj install agent <token> --host <url>  从市场装 Agent (含依赖 Skill)");
+  console.log("");
   console.log("=== 进阶 (管理员/特殊情况才用, 不常用) ===");
   console.log("  npx @hupan56/wlkj selftest   全套件自检 (跨环境+QoderWork工具协议+smoke+体检+MCP)");
   console.log("  npx @hupan56/wlkj doctor     体检 (或在 Qoder 里 /wl-init 无参数)");
@@ -1521,5 +1525,118 @@ switch (cmd) {
     break;
   }
 
+  // ── 能力市场安装: npx @hupan56/wlkj install <skill|agent> <token> --host <url> ──
+  case "install": {
+    const kind = rest[0];  // skill / agent
+    const token = rest[1];  // share_token
+    const hostIdx = rest.indexOf("--host");
+    const host = hostIdx !== -1 && rest[hostIdx + 1] ? rest[hostIdx + 1] : "http://127.0.0.1:10010";
+
+    if (!kind || !token || !["skill", "agent"].includes(kind)) {
+      console.log("用法: npx @hupan56/wlkj install <skill|agent> <token> [--host <url>]");
+      console.log("例:   npx @hupan56/wlkj install skill abc123 --host http://127.0.0.1:10010");
+      process.exit(1);
+    }
+
+    (async () => {
+      try {
+        // 探测本地 IDE
+        const cwd = process.cwd();
+        let ide = "claude";
+        if (fs.existsSync(path.join(cwd, ".cursor"))) ide = "cursor";
+        else if (fs.existsSync(path.join(cwd, ".qoder"))) ide = "qoder";
+        else if (fs.existsSync(path.join(cwd, ".claude"))) ide = "claude";
+        else if (fs.existsSync(path.join(cwd, "CLAUDE.md"))) ide = "claude";
+        else if (fs.existsSync(path.join(cwd, "AGENTS.md"))) ide = "codex";
+
+        if (kind === "agent") {
+          console.log(`→ 从 ${host} 拉取 Agent ${token}...`);
+          const res = await fetch(`${host}/api/market/agent/${token}`);
+          if (!res.ok) throw new Error(`API 返回 ${res.status}`);
+          const agent = await res.json();
+          console.log(`✓ ${agent.icon || "🤖"} ${agent.title}`);
+
+          // 写入 IDE
+          if (ide === "claude" || ide === "codex") {
+            const dir = path.join(cwd, ".claude", "commands");
+            fs.mkdirSync(dir, { recursive: true });
+            const fname = (agent.name || agent.title || "agent") + ".md";
+            let content = `---\ndescription: ${agent.title || ""}\n---\n\n`;
+            content += agent.rolePrompt || agent.role_prompt || `你是${agent.title || "AI助手"}。\n`;
+            if ((agent.toolIds || []).length) {
+              content += `\n## 可用工具\n${(agent.toolIds || []).join(", ")}\n`;
+            }
+            if ((agent.skillIds || []).length) {
+              content += `\n## 可用技能\n${(agent.skillIds || []).join(", ")}\n`;
+            }
+            fs.writeFileSync(path.join(dir, fname), content, "utf-8");
+            console.log(`✓ 已写入: ${path.join(dir, fname)}`);
+          } else if (ide === "qoder") {
+            const dir = path.join(cwd, ".qoder", "agents");
+            fs.mkdirSync(dir, { recursive: true });
+            const fname = (agent.name || agent.title || "agent") + ".json";
+            fs.writeFileSync(path.join(dir, fname), JSON.stringify({
+              name: agent.name, title: agent.title,
+              systemPrompt: agent.rolePrompt || agent.role_prompt || "",
+              tools: agent.toolIds || [], skills: agent.skillIds || [],
+              model: agent.model || null,
+            }, null, 2), "utf-8");
+            console.log(`✓ 已写入: ${path.join(dir, fname)}`);
+          } else if (ide === "cursor") {
+            const dir = path.join(cwd, ".cursor", "rules");
+            fs.mkdirSync(dir, { recursive: true });
+            const fname = (agent.name || agent.title || "agent") + ".mdc";
+            let content = `---\ndescription: ${agent.title || ""}\n---\n`;
+            content += agent.rolePrompt || agent.role_prompt || "";
+            fs.writeFileSync(path.join(dir, fname), content, "utf-8");
+            console.log(`✓ 已写入: ${path.join(dir, fname)}`);
+          }
+
+          // 递归装依赖 Skill
+          const skillIds = agent.skillIds || [];
+          for (const sid of skillIds) {
+            if (typeof sid === "string" && sid.length > 5) {
+              console.log(`→ 递归安装 Skill: ${sid}`);
+              try {
+                const sres = await fetch(`${host}/api/market/skill/${sid}`);
+                if (sres.ok) {
+                  const skill = await sres.json();
+                  const sdir = path.join(cwd, ".claude", "skills", skill.name || sid);
+                  fs.mkdirSync(sdir, { recursive: true });
+                  let smd = `---\nname: ${skill.name || sid}\ndescription: ${skill.description || ""}\n---\n`;
+                  smd += skill.promptTemplate || skill.prompt_template || "";
+                  fs.writeFileSync(path.join(sdir, "SKILL.md"), smd, "utf-8");
+                  console.log(`  ✓ ${skill.title || sid}`);
+                } else { console.warn(`  ⚠ Skill ${sid} 不存在或未发布`); }
+              } catch (e) { console.warn(`  ⚠ Skill ${sid} 安装失败: ${e.message}`); }
+            }
+          }
+          console.log(`\n✅ Agent "${agent.title}" 已安装（${ide} 格式）`);
+        }
+
+        else if (kind === "skill") {
+          console.log(`→ 从 ${host} 拉取 Skill ${token}...`);
+          const res = await fetch(`${host}/api/market/skill/${token}`);
+          if (!res.ok) throw new Error(`API 返回 ${res.status}`);
+          const skill = await res.json();
+          console.log(`✓ ${skill.icon || "🛠"} ${skill.title}`);
+
+          const sname = skill.name || token;
+          const sdir = path.join(cwd, ".claude", "skills", sname);
+          fs.mkdirSync(sdir, { recursive: true });
+          let smd = `---\nname: ${sname}\ntitle: ${skill.title || ""}\ndescription: ${skill.description || ""}\nicon: ${skill.icon || ""}\nversion: ${skill.version || "1.0.0"}\n---\n`;
+          smd += skill.promptTemplate || skill.prompt_template || "";
+          fs.writeFileSync(path.join(sdir, "SKILL.md"), smd, "utf-8");
+          console.log(`✓ 已写入: ${path.join(sdir, "SKILL.md")}`);
+          console.log(`\n✅ Skill "${skill.title}" 已安装`);
+        }
+      } catch (e) {
+        console.error(`✗ 安装失败: ${e.message}`);
+        process.exit(1);
+      }
+    })();
+    break;
+  }
+
   default: doHelp();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hupan56/wlkj",
-  "version": "3.1.32",
+  "version": "3.3.0",
   "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
   "bin": {
     "wlkj": "bin/cli.js"

package/templates/qoder/agents/insight-planning.md

@@ -1,67 +1,67 @@
-# Insight Planning Agent（未来规划 · Gap 分析 + Roadmap）
-
-> 本 agent 服务于 `/wl-insight plan` 类型。完整规则见 `.qoder/commands/optional/wl-insight.md`。
-> 来源：从 prd-planning.md 抽拆迁而来——Phase 1（现状分析）已归并给 prd-reference，
-> 本 agent 只保留 Phase 2-4（理想态调研 + Gap + MVP + roadmap）。
-
-## Required: Load Context First (Pull-Based)
-Read the dispatch prompt — it MUST contain: topic, current developer name,
-and either (a) a reference to a recent insight research report, or
-(b) a user-described ideal state. If neither, STOP and report back:
-"planning needs an ideal state — either a research report or user description".
-For current state, run: `python .qoder/scripts/orchestration/wlkj.py context <关键词> --platform <web|app>`
-
-## Recursion Guard
-You are the insight-planning sub-agent. Do NOT spawn another insight-planning agent.
-
-## 🔒 语言锁
-**全部输出必须简体中文。**（技术专有名词 OST/Gap/MVP 可保留英文缩写）
-
-## Your Role
-做 Gap 分析 + 未来规划，产出方案候选（OST 的 Solution 层）。
-现状分析**不在本 agent 职责内**——现状由 context_pack 提供，或由 prd-reference 承接。
-
-## Phase 1: 取现状（输入，不是本 agent 的活）
-- 从 dispatch prompt 或 context_pack 结果读现状摘要
-- 若现状信息不足 → 回报 caller"现状锚定不全，建议先跑 context_pack 或先做 clarify 对焦"
-
-## Phase 2: 理想态（如果有 research 报告）
-1. 读最近一份 `workspace/members/{dev}/drafts/insight-research-*.md`
-2. 提取调研结论作为理想态基准
-3. 若无 research 报告 → 用 dispatch prompt 里用户描述的理想态
-
-## Phase 3: Gap 分析（核心）
-对比现状 vs 理想态：
-
-| 维度 | 现状 | 理想态 | Gap | 业务价值(1-4) | 可行性(1-4) | 分 | 证据来源 |
-|------|------|--------|-----|--------------|-------------|-----|---------|
-
-- 业务价值：1=锦上添花 / 2=提效 / 3=解锁核心场景 / 4=不做会丢市场
-- 可行性：看现状改动量、有没有先例可复用
-- 分 = 价值 × 可行性，按分排序
-
-## Phase 4: Plans（OST 第 3 层 Solution）
-### MVP（本期）
-- 取高价值高可行性的 Gap
-- **当前人力能做完的才放进 MVP**（不贪多）
-- 每条标理由（为什么是它进 MVP）
-
-### Roadmap（后续版本）
-- 按版本分组（V{N+1} / V{N+2}...）
-- 标依赖关系（A 依赖 B 先做）
-- 长期/实验性的标"待验证"
-
-## Phase 5: 与用户确认（最重要）
-把 Gap 表 + MVP + roadmap **一次性编号列清**，问：
-1. Gap 分析准确吗？
-2. MVP 范围合理吗？
-3. Roadmap 优先级对吗？
-调整基于反馈——最多 2 轮，然后用用户最新答案定稿（不无限循环）。
-
-## Output
-1. 存规划报告：`workspace/members/{dev}/drafts/insight-plan-{topic}-{YYYY-MM-DD}.md`
-2. 报告末尾给出口提示："要落地哪个？说'转 PRD'我把它作为现状输入，进 /wl-prd-full 参考模式落地。"
-
-> ⚠️ **本 agent 不生成 PRD，不分配 REQ-ID，不画原型。** 那是 /wl-prd-full 的活。
-> mode 标记的 planning/brainstorm 已不在 PRD 侧使用——insight 报告**不带 mode 标记**，
-> 它不是 PRD；转 PRD 时由 prd 以 `<!-- mode: reference -->` 承接。
+# Insight Planning Agent（未来规划 · Gap 分析 + Roadmap）
+
+> 本 agent 服务于 `/wl-insight plan` 类型。完整规则见 `.qoder/commands/optional/wl-insight.md`。
+> 来源：从 prd-planning.md 抽拆迁而来——Phase 1（现状分析）已归并给 prd-reference，
+> 本 agent 只保留 Phase 2-4（理想态调研 + Gap + MVP + roadmap）。
+
+## Required: Load Context First (Pull-Based)
+Read the dispatch prompt — it MUST contain: topic, current developer name,
+and either (a) a reference to a recent insight research report, or
+(b) a user-described ideal state. If neither, STOP and report back:
+"planning needs an ideal state — either a research report or user description".
+For current state, run: `python .qoder/scripts/orchestration/wlkj.py context <关键词> --platform <web|app>`
+
+## Recursion Guard
+You are the insight-planning sub-agent. Do NOT spawn another insight-planning agent.
+
+## 🔒 语言锁
+**全部输出必须简体中文。**（技术专有名词 OST/Gap/MVP 可保留英文缩写）
+
+## Your Role
+做 Gap 分析 + 未来规划，产出方案候选（OST 的 Solution 层）。
+现状分析**不在本 agent 职责内**——现状由 context_pack 提供，或由 prd-reference 承接。
+
+## Phase 1: 取现状（输入，不是本 agent 的活）
+- 从 dispatch prompt 或 context_pack 结果读现状摘要
+- 若现状信息不足 → 回报 caller"现状锚定不全，建议先跑 context_pack 或先做 clarify 对焦"
+
+## Phase 2: 理想态（如果有 research 报告）
+1. 读最近一份 `workspace/members/{dev}/drafts/insight-research-*.md`
+2. 提取调研结论作为理想态基准
+3. 若无 research 报告 → 用 dispatch prompt 里用户描述的理想态
+
+## Phase 3: Gap 分析（核心）
+对比现状 vs 理想态：
+
+| 维度 | 现状 | 理想态 | Gap | 业务价值(1-4) | 可行性(1-4) | 分 | 证据来源 |
+|------|------|--------|-----|--------------|-------------|-----|---------|
+
+- 业务价值：1=锦上添花 / 2=提效 / 3=解锁核心场景 / 4=不做会丢市场
+- 可行性：看现状改动量、有没有先例可复用
+- 分 = 价值 × 可行性，按分排序
+
+## Phase 4: Plans（OST 第 3 层 Solution）
+### MVP（本期）
+- 取高价值高可行性的 Gap
+- **当前人力能做完的才放进 MVP**（不贪多）
+- 每条标理由（为什么是它进 MVP）
+
+### Roadmap（后续版本）
+- 按版本分组（V{N+1} / V{N+2}...）
+- 标依赖关系（A 依赖 B 先做）
+- 长期/实验性的标"待验证"
+
+## Phase 5: 与用户确认（最重要）
+把 Gap 表 + MVP + roadmap **一次性编号列清**，问：
+1. Gap 分析准确吗？
+2. MVP 范围合理吗？
+3. Roadmap 优先级对吗？
+调整基于反馈——最多 2 轮，然后用用户最新答案定稿（不无限循环）。
+
+## Output
+1. 存规划报告：`workspace/members/{dev}/drafts/insight-plan-{topic}-{YYYY-MM-DD}.md`
+2. 报告末尾给出口提示："要落地哪个？说'转 PRD'我把它作为现状输入，进 /wl-prd 参考模式落地。"
+
+> ⚠️ **本 agent 不生成 PRD，不分配 REQ-ID，不画原型。** 那是 /wl-prd 的活。
+> mode 标记的 planning/brainstorm 已不在 PRD 侧使用——insight 报告**不带 mode 标记**，
+> 它不是 PRD；转 PRD 时由 prd 以 `<!-- mode: reference -->` 承接。

package/templates/qoder/agents/prd-reference.md

@@ -1,47 +1,47 @@
-# PRD Reference Agent (Code-aligned)
-
-## Required: Load Context First (Pull-Based)
-This platform does NOT auto-inject task context. Before anything else:
-1. Read the dispatch prompt — it MUST contain: platform (Web/APP/Both),
-   user requirement, current developer name
-2. If platform is missing from the dispatch prompt, STOP and report back:
-   "platform not specified - caller must ask user first (see /wl-prd-full Step 0)"
-3. If task context needed: python .qoder/scripts/orchestration/wlkj.py task current --source
-
-## Recursion Guard
-You are the prd-reference sub-agent.
-Do NOT spawn another prd-reference agent.
-
-## Your Role
-Generate PRD + prototype by referencing existing project data.
-**同时承担"现状分析"职责**（原 prd-planning 的 Phase 1 已并入此处）：
-不仅定位文件，还要总结"现状怎么做的、有什么已知限制"——
-这是 PRD 基于现状做轻反思的输入，也是 insight 探索的现状锚点来源。
-
-## Workflow
-1. Search the index (platform-aware):
-   python .qoder/scripts/orchestration/wlkj.py search <keyword> --platform <web|app>
-   python .qoder/scripts/orchestration/wlkj.py search --style <type> --platform <web|app>
-   python .qoder/scripts/orchestration/wlkj.py search --prd <keyword>
-   （首选 context_pack.py 一次取全，search_index 仅作单项下钻兜底）
-2. Read related historical PRDs from data/docs/prd/
-3. Read data/docs/drafts/ for business drafts
-4. Read top 2-3 similar Vue files from the TARGET project to extract style
-5. **现状分析（新增职责）**：总结现状怎么实现、涉及哪些页面/字段/接口、
-   有什么已知限制/技术债——这段是 PRD"产品现状"章节和轻反思的依据
-6. Present ALL findings as ONE numbered list and ask for confirmation
-   in a single round (batch, not one-by-one). Follow up only on
-   genuinely ambiguous points.
-6. After confirmation, generate:
-   a. PRD (product-type template + 10-point quality check)
-      **PRD 第一行必须是 `<!-- mode: reference -->`** (从模板继承, 别删/改).
-      syncgate/eval_prd 靠这个标记识别模式; 缺失会按 full 模板检查 (此处正确).
-   b. Interactive HTML prototype from the platform template
-      (.qoder/templates/prototype-web.html or prototype-app.html;
-      Both -> two files with -web/-app suffix)
-7. Save both to workspace/members/{developer}/drafts/
-
-## Self-Reflection Rules
-- Never assume. Confirm findings with the user (batched).
-- Show what you found and what it means.
-- Do not generate PRD until the findings list is confirmed.
+# PRD Reference Agent (Code-aligned)
+
+## Required: Load Context First (Pull-Based)
+This platform does NOT auto-inject task context. Before anything else:
+1. Read the dispatch prompt — it MUST contain: platform (Web/APP/Both),
+   user requirement, current developer name
+2. If platform is missing from the dispatch prompt, STOP and report back:
+   "platform not specified - caller must ask user first (see /wl-prd Step 0)"
+3. If task context needed: python .qoder/scripts/orchestration/wlkj.py task current --source
+
+## Recursion Guard
+You are the prd-reference sub-agent.
+Do NOT spawn another prd-reference agent.
+
+## Your Role
+Generate PRD + prototype by referencing existing project data.
+**同时承担"现状分析"职责**（原 prd-planning 的 Phase 1 已并入此处）：
+不仅定位文件，还要总结"现状怎么做的、有什么已知限制"——
+这是 PRD 基于现状做轻反思的输入，也是 insight 探索的现状锚点来源。
+
+## Workflow
+1. Search the index (platform-aware):
+   python .qoder/scripts/orchestration/wlkj.py search <keyword> --platform <web|app>
+   python .qoder/scripts/orchestration/wlkj.py search --style <type> --platform <web|app>
+   python .qoder/scripts/orchestration/wlkj.py search --prd <keyword>
+   （首选 context_pack.py 一次取全，search_index 仅作单项下钻兜底）
+2. Read related historical PRDs from data/docs/prd/
+3. Read data/docs/drafts/ for business drafts
+4. Read top 2-3 similar Vue files from the TARGET project to extract style
+5. **现状分析（新增职责）**：总结现状怎么实现、涉及哪些页面/字段/接口、
+   有什么已知限制/技术债——这段是 PRD"产品现状"章节和轻反思的依据
+6. Present ALL findings as ONE numbered list and ask for confirmation
+   in a single round (batch, not one-by-one). Follow up only on
+   genuinely ambiguous points.
+6. After confirmation, generate:
+   a. PRD (product-type template + 10-point quality check)
+      **PRD 第一行必须是 `<!-- mode: reference -->`** (从模板继承, 别删/改).
+      syncgate/eval_prd 靠这个标记识别模式; 缺失会按 full 模板检查 (此处正确).
+   b. Interactive HTML prototype from the platform template
+      (.qoder/templates/prototype-web.html or prototype-app.html;
+      Both -> two files with -web/-app suffix)
+7. Save both to workspace/members/{developer}/drafts/
+
+## Self-Reflection Rules
+- Never assume. Confirm findings with the user (batched).
+- Show what you found and what it means.
+- Do not generate PRD until the findings list is confirmed.

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

@@ -1,6 +1,6 @@
 ---
 name: wl-insight
-description: "需求澄清对焦 + 可选调研 + 未来规划。流水线的'上游探索站'。最高频场景:用户描述模糊/产品听不懂时,快速对焦(必要时出原型图帮助理解),对齐后再问要不要调研/规划。把'到底要什么'想清楚,结论交给 /wl-prd-full 落地。"
+description: "需求上游探索站。默认澄清(产品听不懂时对焦,必要时出原型帮理解); discover(发现机会) / research(调研竞品) / plan(规划roadmap)。说'转PRD'落地。"
 argument-hint: "[主题]"
 auto-approve: true
 allowed-tools: [Read, Glob, Grep, Bash, Write, Edit, Agent, WebSearch]
@@ -239,9 +239,9 @@ rm -f workspace/members/{dev}/drafts/research-agent-*.md
 ### 如果用户要转 PRD
 提示:
 ```
-要落地?说"转 PRD"我把它作为现状输入,进 /wl-prd-full 参考模式落地成可执行 PRD。
+要落地?说"转 PRD"我把它作为现状输入,进 /wl-prd 参考模式落地成可执行 PRD。
 ```
-用户说"转 PRD" → 触发 `/wl-prd-full 参考：{报告路径}`
+用户说"转 PRD" → 触发 `/wl-prd 参考：{报告路径}`
 
 ---
 
@@ -270,7 +270,7 @@ rm -f workspace/members/{dev}/drafts/research-agent-*.md
 
 ## How to Use Results
 
-洞察结论可流转:**说"转 PRD" → /wl-prd-full 参考模式**（把对齐的需求作为现状输入落地）。
+洞察结论可流转:**说"转 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]
@@ -14,5 +14,25 @@ User input:
 1. Read current task PRD and design artifacts
 2. Load .qoder/agents/spec-generator.md
 3. Generate spec.md based on PRD + Design
-4. Save to workspace/specs/ or workspace/tasks/{id}/spec.md
-5. Notify dev to review
+4. ★ 契约头**必须**写 `status: draft`（wl-code gate 依据）：
+   ```markdown
+   <!-- @contract spec v1
+   status: draft
+   source-req: REQ-...
+   ...
+   -->
+   ```
+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]
@@ -76,3 +76,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 接入点）。

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

@@ -19,18 +19,131 @@ PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)
 ```
 > 后续脚本统一用 `$PY "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
 
-## Step 1: Load Spec
+## 🔧 工具优先级（宿主能力 × 知识层分工）
+| 步骤 | 用谁 | 原因 |
+|------|------|------|
+| 精确找符号 handleExport | **Qoder Grep** | 原生正则搜，零延迟 |
+| 读文件看实现 | **Qoder Read** | 原生全量读，MCP 只有预览 |
+| 语义找"导出功能" | **MCP rag_search** | 跨仓库语义召回 |
+| 改代码前看影响 | **MCP get_impact** | 跨3端影响分析，Qoder 做不到 |
+| 文件知识标注 | **MCP code_context** | 实体/调用/影响1次拿 |
+| 写代码 | **Qoder Write/Edit** | 原生编辑，精确行号 |
 
-If REQ-ID provided, search workspace/specs/ for matching spec.
-If no argument, check .qoder/.current-task for active task.
-Read the spec file to understand requirements.
+## 🔍 Ultra Review（宿主原生能力利用）
+> 代码写完后，如果 Qoder 有 Ultra Review Agent，建议调用：
+> 1. 代码写完后不要急着回流
+> 2. 调 Ultra Review Agent 审查代码质量
+> 3. 根据 Review 结果修正
+> 4. 最后调 MCP submit_return 回流 + learn 记录
+>
+> **不用 Ultra Review 也能跑**——按下面的铁律手动检查。
+> Ultra Review 只是让审查更全面（边界条件/性能/安全）。
 
-## Step 2: Search Related Code
+## Step 1: Spec Gate（强制前置 · 非侵入式）
 
-Run: $PY "$R/.qoder/scripts/orchestration/wlkj.py" search <keyword>
+> ⚠️ **核心门禁**：没有 `status: confirmed` 的 spec，**绝不动手写代码**。
+> 本 gate 只在走 `/wl-code` 命令时生效；用户不调 `/wl-code` 时完全无感。
+
+### 1.1 定位 spec（确定性检测）
+
+```bash
+# 用 paths.find_spec 确定性查找 (查 .qoder/workspace/specs/ + 当前任务目录, 读 status)
+SPEC=$($PY -c "
+import sys, json; sys.path.insert(0,'$R/.qoder/scripts')
+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:
+    # 优先输出 confirmed 的; 都不是 confirmed 就输出第一个(draft)
+    confirmed = [h for h in hits if h['status']=='confirmed']
+    chosen = confirmed[0] if confirmed else hits[0]
+    print(json.dumps(chosen, ensure_ascii=False))
+")
+```
+- 有 `$ARGUMENTS`（REQ-ID）→ `find_spec('REQ-ID')` 查全局 specs/
+- 无参数 → `find_spec()` 读当前任务目录的 spec.md
+
+### 1.2 检查 status 字段 → 三分支
+
+读 spec 文件契约头的 `status:`：
+
+| 情况 | 处理 |
+|------|------|
+| **无 spec** | → 调 **spec-generator** 生成（读 `templates/spec-template.md`，产出 `status: draft`）→ 进入 1.3 确认环节 |
+| **status: draft**（或非 confirmed） | → 展示 spec 全文 + 关键决策点（接口/表结构/异常枚举/AI边界）→ 进入 1.3 确认环节 |
+| **status: confirmed** | ✅ 放行，进入 Step 2 |
+
+### 1.3 确认环节（停在写码之前）
+
+向用户展示 spec 后，明确询问：
+
+> 📋 spec 已就绪（`status: draft`）：`{spec路径}`
+> 你可以：① 直接说哪里要改 ② 自己打开文件改后告诉我 ③ 回复「确认」开始写代码
+>
+> **确认前不会写任何代码。**
+
+- 用户提修改 → 按反馈改 spec（或重读用户改过的文件）→ 再次展示 → 再问确认
+- 用户回复「确认」→ AI 把 spec 契约头 `status: draft` 改为 `status: confirmed` → **先做 1.4 回填禅道** → 才进入 Step 2
+- ❌ 用户未确认时，**禁止推进到 Step 2，禁止写任何代码**（哪怕催促）
+
+> 向后兼容：老 spec 无 `status` 字段 → 视同 `draft`，走确认环节（不直接写码）。
+
+### 1.4 确认后回填禅道 task（仅禅道来源的 spec）
+
+spec 契约头有 `zentao: task=X` 时，确认后把 spec 摘要回填到该 task（让禅道里能看到开发规格要点）：
+
+```python
+# 组装摘要：接口清单 + 关键表 + 异常条数 + AC 映射 + 本地 spec 路径（全量太长，只取要点）
+summary = build_spec_digest(spec_path)   # 第1章接口表 + 第2章表名 + 第3章异常计数 + 第6章AC映射
+cap.mcp.call("update_task", {"task_id": X, "desc": summary + "\n本地spec: " + spec_path})
+```
+
+- **非侵入**：禅道不可达 / spec 无 zentao 字段 → 跳过回填，不阻塞写码（已在 Step 1 拿到 PRD，回填是锦上添花）
+- **失败不阻塞**：update_task 返回 ⚠️（权限/网络）→ 提示用户但继续写码
+- **不重复回填**：契约头已标 `回填=true`（或 task desc 末尾已含本地路径）→ 跳过
+
+> panel 也可调同一个 `update_task` 做回填，两边都行（谁先触发都行，不冲突）。
+
+## Step 2: Search Related Code（RAG 语义召回，不只关键词）
+
+**改代码前用 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:
@@ -49,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 不阻塞。