@hupan56/wlkj 2.6.0 → 2.7.0

package/bin/cli.js

@@ -24,14 +24,81 @@ const LOCAL_STATE_FILES = new Set([
   ".developer", ".current-task", ".engine-version",
 ]);
 
+// 探测可用的 Python 命令 (python 或 python3)。
+// macOS 系统通常只有 python3, 硬编码 python 会让 Mac 全员失败。
+// 探测结果缓存到全局, 避免每次调用都 fork 进程。
+let _PY_CMD_CACHE = null;
+function detectPyCmd() {
+  if (_PY_CMD_CACHE) return _PY_CMD_CACHE;
+  for (const c of ["python", "python3"]) {
+    try {
+      execSync(`${c} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" });
+      _PY_CMD_CACHE = c;
+      return c;
+    } catch { /* try next */ }
+  }
+  _PY_CMD_CACHE = null;
+  return null;
+}
+
 function py(script, args = []) {
   const p = path.join(process.cwd(), ".qoder", "scripts", script);
   if (!fs.existsSync(p)) { console.log("请先运行: npx wlkj init"); process.exit(1); }
+  const pyCmd = detectPyCmd();
+  if (!pyCmd) { console.log("Python 未安装, 无法运行脚本。跑: npx @hupan56/wlkj install-env"); return ""; }
   try {
-    return execSync(`python "${p}" ${args.map(a => `"${a}"`).join(" ")}`, { cwd: process.cwd(), encoding: "utf-8", timeout: 15000 });
+    return execSync(`${pyCmd} "${p}" ${args.map(a => `"${a}"`).join(" ")}`, { cwd: process.cwd(), encoding: "utf-8", timeout: 15000 });
   } catch (e) { return (e.stdout || e.message); }
 }
 
+// 带镜像兜底的 pip 安装 —— 复用 Python 的 common/pip_install.py (单一事实源)
+// 为什么不复用 Python: 上一轮给 init_doctor 做了 common/pip_install.py (失败切清华/阿里/腾讯)。
+// cli.js 的 install-env/update 是独立 JS 路径, 之前没享受镜像兜底 → 50 人里弱网用户全崩。
+// 这里调用同一个 Python 工具, 保证两路径行为一致。
+//
+// 优先: 引擎已装 → 调 common.pip_install (有镜像兜底)
+// 回退: 引擎没装 → 裸 pip install (install-env 首次场景, 无 Python 工具可用)
+function installPipDeps(pyCmd, reqPath) {
+  const scriptsDir = path.join(process.cwd(), ".qoder", "scripts");
+  const hasTool = fs.existsSync(path.join(scriptsDir, "common", "pip_install.py"));
+  if (hasTool) {
+    // 调 Python 工具: install_with_fallback(['-r', reqPath]) → 输出结果
+    const prog = [
+      "import sys; sys.path.insert(0, '" + scriptsDir.replace(/\\/g, "\\\\") + "')",
+      "from common.pip_install import install_with_fallback",
+      "import json",
+      "r = install_with_fallback(['-r', " + JSON.stringify(reqPath) + "])",
+      "print(json.dumps(r, ensure_ascii=False))",
+    ].join("; ");
+    try {
+      const out = execSync(`${pyCmd} -c "${prog}"`, { encoding: "utf-8", timeout: 600000 });
+      // 最后一行是 JSON 结果
+      const lines = out.trim().split("\n");
+      const jsonLine = lines[lines.length - 1];
+      const result = JSON.parse(jsonLine);
+      if (result.ok) {
+        console.log(`  [OK] Python 依赖已装` + (result.source && result.source !== "default" ? ` (镜像源: ${result.source})` : ""));
+      } else {
+        console.log(`  [WARN] pip 安装失败 (尝试了所有镜像)`);
+        console.log(`  ${result.hint || ""}`.replace(/\n/g, "\n  "));
+      }
+      return result.ok;
+    } catch (e) {
+      console.log(`  [WARN] 调用镜像工具失败, 回退裸 pip: ${(e.message || "").slice(0, 80)}`);
+    }
+  }
+  // 回退: 裸 pip install (引擎未装, 或工具调用失败)
+  try {
+    execSync(`${pyCmd} -m pip install -r "${reqPath}"`, { stdio: "inherit", timeout: 300000 });
+    console.log("  [OK] Python 依赖已装");
+    return true;
+  } catch (e) {
+    console.log(`  [WARN] pip 安装失败: ${(e.message || "").slice(0, 80)}`);
+    console.log("  国内网络建议配镜像: pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple");
+    return false;
+  }
+}
+
 function cp(src, dest) {
   const s = path.join(T, src), d = path.join(process.cwd(), dest);
   if (!fs.existsSync(s)) return;
@@ -58,11 +125,99 @@ function gitOp(op) {
   catch (e) { console.log(e.stdout || e.message); }
 }
 
-function doInit(name) {
+// 快速环境检测 (init 前置): 缺 Python 致命退出, 缺 git 警告不阻塞
+// 目的: 杜绝"裸机没 Python 时 init 静默失败仍宣布成功"的假成功
+function checkEnvQuick() {
+  console.log("--- 环境检测 ---");
+  // Node 一定有 (npx 在跑), 输出 version 确认
+  console.log(`  Node.js: [OK] ${process.version}`);
+
+  // Python: python 或 python3 任一可用即可
+  let pyCmd = null, pyVer = null;
+  for (const c of ["python", "python3"]) {
+    try {
+      const v = execSync(`${c} --version`, { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
+      pyCmd = c; pyVer = v; break;
+    } catch { /* try next */ }
+  }
+  if (!pyCmd) {
+    console.log("  Python:  [缺失] (引擎必需)");
+    console.log("\n  ⚠ 没装 Python, 无法继续。请先装环境:");
+    console.log("    npx @hupan56/wlkj install-env");
+    console.log("    (自动装 Node/Python/git + pip 依赖; 装完重开终端再 init)\n");
+    return { ok: false, pyCmd: null };
+  }
+  console.log(`  Python:  [OK] ${pyVer} (${pyCmd})`);
+
+  // git: 可选, 缺了只警告 (与 init_doctor 口径一致)
+  try {
+    const gv = execSync("git --version", { encoding: "utf-8", timeout: 5000, stdio: "pipe" }).trim();
+    console.log(`  git:     [OK] ${gv}`);
+  } catch {
+    console.log("  git:     [缺失] (可选, 团队同步/源码克隆将禁用, 本地 PRD/搜索/任务仍可用)");
+    console.log("           想启用: npx @hupan56/wlkj install-env");
+  }
+  console.log("");
+  return { ok: true, pyCmd };
+}
+
+// 交互式问角色 (50 人团队角色各异, 不能写死 pm)
+// 支持的角色 (与 config.yaml / kg.py ROLE_SECTIONS 对齐)
+const ROLES = [
+  { key: "pm", label: "产品经理 (PM) — 写需求/PRD/任务" },
+  { key: "design", label: "设计师 (UI) — 录入设计稿/出原型" },
+  { key: "dev", label: "开发 (前端/后端) — 写代码/提交/测试" },
+  { key: "test", label: "测试 (QA) — 跑测试用例/验证" },
+  { key: "admin", label: "管理员 — 管理/维护工作流" },
+];
+
+function askRole() {
+  // 非交互环境 (CI/AI 调用) 默认 pm
+  if (!process.stdin.isTTY) {
+    console.log("  (非交互环境, 默认角色: pm)");
+    return "pm";
+  }
+  console.log("\n  你的角色是? (决定命令视角和建议)");
+  ROLES.forEach((r, i) => console.log(`    ${i + 1}. ${r.label}`));
+  const readline = require("readline").createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    readline.question("\n  选择 (1-5, 默认1): ", (ans) => {
+      readline.close();
+      const idx = parseInt(ans, 10) - 1;
+      const role = (idx >= 0 && idx < ROLES.length) ? ROLES[idx].key : "pm";
+      console.log(`  角色: ${role}\n`);
+      resolve(role);
+    });
+  });
+}
+
+// 校验角色参数合法性 (大小写无关: PM/pm/Dev/dev 都认)
+function normalizeRole(r) {
+  if (!r) return null;
+  const low = String(r).toLowerCase();
+  return ROLES.some(x => x.key === low) ? low : null;
+}
+
+async function doInit(name, roleArg) {
   const cwd = process.cwd();
   const hasExisting = fs.existsSync(path.join(cwd, ".qoder", "scripts", "setup.py"));
   console.log(`\nwlkj init -> ${cwd}${hasExisting ? " (已存在, 增量更新)" : ""}\n`);
 
+  // === 0. 环境前置检测 (避免裸机无 Python 时假成功) ===
+  const env = checkEnvQuick();
+  if (!env.ok) process.exit(1);
+  const { pyCmd } = env;
+
+  // === 0.5. 确定角色 (参数 > 交互式, 不再写死 pm)
+  // 50 人团队角色各异: 产品/UI/前后端/测试/管理, 每个角色的命令视角不同。
+  // 写死 pm = 设计师和开发拿不到匹配的上下文 (见 wl-prd-full 的 --role 适配)。
+  let role = normalizeRole(roleArg);
+  if (!role) {
+    role = await askRole();
+  } else {
+    console.log(`  角色: ${role} (来自参数)\n`);
+  }
+
   // === 1. 拷贝完整引擎 (镜像 .qoder/ 结构) ===
   // 源: templates/qoder/*  目标: .qoder/*
   // 注意: init 用 "update" 模式的保护逻辑更安全 —— 新装时目标文件不存在,
@@ -124,7 +279,7 @@ function doInit(name) {
   console.log(`\n--- 自动初始化 ---`);
   const setupPath = path.join(cwd, ".qoder", "scripts", "setup.py");
   if (fs.existsSync(setupPath)) {
-    const setupArgs = [name, "pm", "--skip-cron", "--skip-qoderwork"].filter(Boolean);
+    const setupArgs = [name, role, "--skip-cron", "--skip-qoderwork"].filter(Boolean);
     try {
       const cmd = `python "${setupPath}" ${setupArgs.map(a => `"${a}"`).join(" ")}`;
       console.log(`  运行: setup.py ${setupArgs.join(" ")}`);
@@ -133,8 +288,38 @@ function doInit(name) {
       console.log(`  setup 部分失败 (不阻塞): ${(e.message || "").slice(0, 100)}`);
       console.log(`  可重新运行: npx @hupan56/wlkj init ${name || "<你的名字>"}`);
     }
-  } else {
-    console.log(`  setup.py 未找到, 跳过自动初始化`);
+    } else {
+      console.log(`  setup.py 未找到, 跳过自动初始化`);
+    }
+
+  // === 6.5. 自动配 QoderWork MCP (新机关键: 否则 mcp.json 不生成, 4 个 MCP 全连不上) ===
+  // 复刻 doUpdate 第 7 步的逻辑: 拷 launcher + install_qoderwork --mcp-only
+  // setup.py 带了 --skip-qoderwork (offer_qoderwork 是交互式+装skill, 不适合 npx),
+  // 这里用 --mcp-only (纯文件操作, 无交互) 把 mcp.json 配好
+  if (pyCmd) {
+    console.log(`\n--- QoderWork MCP 自动配置 ---`);
+    const home = process.env.USERPROFILE || require("os").homedir();
+    const launcherSrc = path.join(cwd, ".qoder", "scripts", "mcp_launcher.py");
+    const launcherDst = path.join(home, ".qoderwork", "mcp_launcher.py");
+    try {
+      if (fs.existsSync(launcherSrc)) {
+        fs.mkdirSync(path.dirname(launcherDst), { recursive: true });
+        fs.copyFileSync(launcherSrc, launcherDst);
+        console.log(`  [OK] launcher 已装: ~/.qoderwork/mcp_launcher.py`);
+      }
+      const instScript = path.join(cwd, ".qoder", "scripts", "install_qoderwork.py");
+      if (fs.existsSync(instScript)) {
+        try {
+          execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "inherit", timeout: 20000 });
+          console.log(`  [OK] mcp.json 已生成 (kg/mysql/lanhu/playwright, launcher 模式)`);
+        } catch (e) {
+          console.log(`  [WARN] MCP 配置未完全成功 (不阻塞): ${(e.message || "").slice(0, 80)}`);
+          console.log(`         可手动补: ${pyCmd} .qoder/scripts/install_qoderwork.py`);
+        }
+      }
+    } catch (e) {
+      console.log(`  [WARN] MCP 配置跳过: ${(e.message || "").slice(0, 80)}`);
+    }
   }
 
   // === 7. 写版本戳 ===
@@ -146,6 +331,9 @@ function doInit(name) {
   console.log(`\n  现在可以开始了:`);
   console.log(`    在 Qoder 里说 "写个 XX 的需求"`);
   console.log(`    或输 / 看命令列表 (/wl-prd /wl-search /wl-task)`);
+  console.log(`\n  ✓ QoderWork MCP 已自动配好 (kg/mysql/lanhu/playwright)`);
+  console.log(`    用 QoderWork 桌面端想装技能(软链到 ~/.qoderwork/skills/)?`);
+  console.log(`    python .qoder/scripts/install_qoderwork.py`);
   console.log(`\n  看不到命令? 新建对话 / 重启 QoderWork`);
   console.log(`  环境问题? python .qoder/scripts/init_doctor.py --fix\n`);
 }
@@ -248,12 +436,23 @@ function doStatus() {
   console.log("");
   const dev = path.join(process.cwd(), ".qoder", ".developer");
   if (fs.existsSync(dev)) {
-    const line = fs.readFileSync(dev, "utf-8").split("\n")[0];
-    console.log("dev: " + line.split("=")[1]?.trim());
-  } else { console.log("dev: - (run: npx wlkj init <name>)"); }
-  
+    // 解析 .developer 的 name= 和 role= 行
+    const lines = fs.readFileSync(dev, "utf-8").split("\n");
+    const nameLine = lines.find(l => l.startsWith("name="));
+    const roleLine = lines.find(l => l.startsWith("role="));
+    const name = nameLine ? nameLine.split("=")[1]?.trim() : "?";
+    const role = roleLine ? roleLine.split("=")[1]?.trim() : "pm";
+    console.log(`dev: ${name} (角色: ${role})`);
+    if (!roleLine) {
+      console.log(`  ⚠ 角色未设置 (默认 pm)。重跑: npx @hupan56/wlkj init ${name} <pm|design|dev|test|admin>`);
+    }
+  } else {
+    console.log("dev: - (未初始化。跑: npx @hupan56/wlkj init <名字> <角色>)");
+    console.log("  角色: 产品(pm)/设计(design)/开发(dev)/测试(test)/管理(admin)");
+  }
+
   process.stdout.write(py("task.py", ["current", "--source"]));
-  
+
   const wsSpecs = path.join(process.cwd(), "workspace", "specs", "prd");
   if (fs.existsSync(wsSpecs)) {
     const n = fs.readdirSync(wsSpecs).filter(f => f.endsWith(".md")).length;
@@ -380,6 +579,38 @@ function doUpdate() {
     console.log(`  [清理] 废弃文件 ${cleaned} 个 + 过期缓存 ${cacheCleaned} 个`);
   }
 
+  // === 6. 补装 pip 依赖 (老用户升级时补齐, 走镜像兜底) ===
+  console.log(`\n--- Python 依赖补装 (失败自动切镜像) ---`);
+  const reqFile = path.join(cwd, "requirements.txt");
+  const pyCmd = detectPyCmd();
+  if (pyCmd && fs.existsSync(reqFile)) {
+    installPipDeps(pyCmd, reqFile);
+  } else if (!pyCmd) {
+    console.log(`  [跳过] Python 未装`);
+  } else {
+    console.log(`  [跳过] requirements.txt 不存在`);
+  }
+
+  // === 7. 刷新 launcher + mcp.json (老用户的可能是旧版/写死路径) ===
+  try {
+    const home = process.env.USERPROFILE || require("os").homedir();
+    const launcherSrc = path.join(cwd, ".qoder", "scripts", "mcp_launcher.py");
+    const launcherDst = path.join(home, ".qoderwork", "mcp_launcher.py");
+    if (fs.existsSync(launcherSrc)) {
+      fs.mkdirSync(path.dirname(launcherDst), { recursive: true });
+      fs.copyFileSync(launcherSrc, launcherDst);
+      console.log(`  [OK] launcher 已刷新`);
+    }
+    // 刷新 mcp.json 为 launcher 模式 (install_qoderwork.py 的 rewrite 逻辑)
+    const instScript = path.join(cwd, ".qoder", "scripts", "install_qoderwork.py");
+    if (pyCmd && fs.existsSync(instScript)) {
+      try {
+        execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "pipe", timeout: 15000 });
+        console.log(`  [OK] mcp.json 已刷新为动态路径`);
+      } catch { /* --mcp-only 可能不支持, 静默跳过 */ }
+    }
+  } catch (e) { /* 刷新失败不阻塞升级 */ }
+
   console.log(`\n${"=".repeat(50)}`);
   console.log(`  升级完成!  (v${PKG_VERSION})`);
   console.log(`${"=".repeat(50)}`);
@@ -562,6 +793,25 @@ function doInstallEnv(checkOnly = false, location = null) {
     console.log(`    或用命令: npx @hupan56/wlkj add-path "D:\\wldev\\nodejs"`);
   }
 
+  // Python pip 依赖 (知识图谱/MCP/测试需要)
+  console.log("\n--- Python 依赖 ---");
+  const pyCmd = check("python") ? "python" : (check("python3") ? "python3" : null);
+  if (pyCmd) {
+    // 找 requirements.txt: 引擎已安装则用 .qoder/scripts/../requirements.txt
+    const reqPaths = [
+      path.join(process.cwd(), "requirements.txt"),
+      path.join(process.cwd(), ".qoder", "..", "requirements.txt"),
+    ].filter(p => fs.existsSync(p));
+    if (reqPaths.length > 0) {
+      console.log(`  安装 pip 依赖: ${path.basename(reqPaths[0])} (失败自动切国内镜像)`);
+      installPipDeps(pyCmd, reqPaths[0]);
+    } else {
+      console.log("  [跳过] 未找到 requirements.txt (先 npx @hupan56/wlkj init 安装引擎)");
+    }
+  } else {
+    console.log("  [跳过] Python 未装, 无法装 pip 依赖");
+  }
+
   console.log("\n=== 结果 ===");
   if (need.length === 0) {
     console.log("  环境就绪! 下一步: npx @hupan56/wlkj init");
@@ -598,7 +848,7 @@ const [,, cmd, ...rest] = process.argv;
 const mapped = rest.map(a => a === "-p" ? "--priority" : a);
 
 switch (cmd) {
-  case "init": doInit(rest[0]); break;
+  case "init": doInit(rest[0], rest[1]); break;
   case "update": case "upgrade": doUpdate(); break;
   case "install-env": {
     const checkOnly = rest.includes("--check");

package/package.json

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

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

@@ -0,0 +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/context_pack.py <关键词> --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 或先做 discover"
+
+## 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 -->` 承接。

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

@@ -0,0 +1,61 @@
+# Insight Research Agent（外部调研 · 多视角脑暴）
+
+> 本 agent 服务于 `/wl-insight research` 类型。完整规则见 `.qoder/commands/optional/wl-insight.md`。
+> 来源：整体从 prd-research.md 搬迁而来（脑暴 + web 搜索能力归 insight）。
+
+## Required: Load Context First (Pull-Based)
+This platform does NOT auto-inject context. Before doing anything else:
+1. Read the dispatch prompt to get: assigned perspective, topic,
+   current state summary (from context_pack), developer name
+2. If perspective is missing from dispatch prompt, STOP and report back:
+   "perspective not specified - caller must assign one of: 竞品对标/行业趋势/技术方案/用户场景"
+
+## Recursion Guard
+You are the insight-research sub-agent.
+Do NOT spawn another insight-research agent.
+
+## 🔒 语言锁
+**全部输出必须简体中文。**（技术专有名词可保留英文）
+
+## Your Role
+你是 N 个调研 agent 中的一个，负责**一个特定视角**的外部调研。
+你的视角在 dispatch prompt 里指定。你的产出是**中间产物**——
+caller（/wl-insight research）会把所有 agent 的报告合并成一份调研报告，
+然后删除中间产物。
+
+## Workflow
+1. 从 dispatch prompt 读你的视角：竞品对标 / 行业趋势 / 技术方案 / 用户场景 之一
+2. 读 dispatch prompt 里的**本项目现状摘要**（让调研有针对性，不泛泛而谈）
+3. 用 WebSearch 搜 3-5 个权威源（官方文档 / 行业报告 / 技术博客 / 公开案例）
+4. 从你的视角分析，重点找：**外部做得好而我们没做的**（Gap 信号）
+5. 写到 `workspace/members/{dev}/drafts/research-agent-{N}-{视角}.md`
+
+> ⚠️ **不要凭训练记忆编数据**。搜不到就标"【待验证】"，不要编竞品功能/数据。
+> ⚠️ 每个发现必须附**来源链接**。
+
+## Output Format
+```markdown
+# 调研报告（中间产物）：{视角}
+
+## 视角
+{你负责的视角}
+
+## 本项目现状（来自 dispatch）
+{一句话摘要，让读者知道对标基准}
+
+## 关键发现
+1. {发现} —— 来源：{链接}
+   - 对本项目的启发：{...}
+   - Gap 信号：{外部做得好而我们没做的}
+2. ...
+
+## 风险
+- {采纳这个做法的风险/前提条件}
+
+## 机会建议
+- {值得跟进的机会点}
+```
+
+> ⚠️ **本 agent 不生成 PRD。** 你是 research 类型的子 agent，产出中间产物。
+> 合并后的调研报告也不带 mode 标记（它不是 PRD）。
+> caller 合并后会删除所有 `research-agent-*.md` 中间产物。

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

@@ -5,7 +5,7 @@ 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)"
+   "platform not specified - caller must ask user first (see /wl-prd-full Step 0)"
 3. If task context needed: python .qoder/scripts/task.py current --source
 
 ## Recursion Guard
@@ -14,16 +14,22 @@ 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/search_index.py <keyword> --platform <web|app>
    python .qoder/scripts/search_index.py --style <type> --platform <web|app>
    python .qoder/scripts/search_index.py --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. Present ALL findings as ONE numbered list and ask for confirmation
+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: