@hupan56/wlkj 2.7.2 → 2.7.4

package/bin/cli.js

@@ -51,6 +51,18 @@ function py(script, args = []) {
   } catch (e) { return (e.stdout || e.message); }
 }
 
+// 透传执行: 直接 spawn (不捕获输出, 实时显示, 支持长超时和交互式)
+// 用于 kg_build/eval_prd/autotest 等耗时脚本, 以及需要交互的场景
+function runScript(scriptName, args = [], timeoutMs = 600000) {
+  const p = path.join(process.cwd(), ".qoder", "scripts", scriptName);
+  if (!fs.existsSync(p)) { console.log("脚本不存在: " + scriptName + "。跑: npx wlkj init"); process.exit(1); }
+  const pyCmd = detectPyCmd();
+  if (!pyCmd) { console.log("Python 未安装。跑: npx @hupan56/wlkj install-env"); process.exit(1); }
+  const { spawnSync } = require("child_process");
+  const r = spawnSync(pyCmd, [p, ...args], { cwd: process.cwd(), stdio: "inherit", timeout: timeoutMs, encoding: "utf-8" });
+  process.exit(r.status || 0);
+}
+
 // 带镜像兜底的 pip 安装 —— 复用 Python 的 common/pip_install.py (单一事实源)
 // 为什么不复用 Python: 上一轮给 init_doctor 做了 common/pip_install.py (失败切清华/阿里/腾讯)。
 // cli.js 的 install-env/update 是独立 JS 路径, 之前没享受镜像兜底 → 50 人里弱网用户全崩。
@@ -241,13 +253,14 @@ async function doInit(name, roleArg) {
   }
   console.log(`  引擎: ${copied} 个文件 (${hasExisting ? "更新" : "新建"})`);
 
-  // === 2. 根文件 (AGENTS.md, 新手指南.md) ===
-  ["root/AGENTS.md", "root/新手指南.md"].forEach(f => {
+  // === 2. 根文件 (AGENTS.md, 新手指南.md, requirements.txt) ===
+  ["root/AGENTS.md", "root/新手指南.md", "root/requirements.txt"].forEach(f => {
     const src = path.join(T, f);
     if (fs.existsSync(src)) {
       const dstName = path.basename(f);
       const dst = path.join(cwd, dstName);
-      if (!fs.existsSync(dst)) {
+      // requirements.txt 始终覆盖(版本可能更新), 其它不存在才拷
+      if (dstName === "requirements.txt" || !fs.existsSync(dst)) {
         fs.copyFileSync(src, dst);
       }
     }
@@ -520,14 +533,29 @@ function doUpdate() {
     console.log(`  config.yaml / settings.json: 已保护（未改动）`);
   }
 
-  // === 2. 根文件（文档类, 安全覆盖）===
-  ["root/AGENTS.md", "root/新手指南.md"].forEach(f => {
+  // === 2. 根文件（文档 + requirements.txt, 始终覆盖保证最新）===
+  ["root/AGENTS.md", "root/新手指南.md", "root/requirements.txt"].forEach(f => {
     const src = path.join(T, f);
     if (fs.existsSync(src)) {
       fs.copyFileSync(src, path.join(cwd, path.basename(f)));
     }
   });
-  console.log(`  根文档: 已更新`);
+  console.log(`  根文档 + requirements.txt: 已更新`);
+
+  // === 2.5. git pull 拉最新团队数据 (kg.duckdb/kg_db.duckdb/PRD等在git里) ===
+  try {
+    const { execSync: _es } = require("child_process");
+    const pullR = _es("git pull --no-rebase 2>&1", { cwd, encoding: "utf-8", timeout: 30000 });
+    if (pullR.includes("Already up to date") || pullR.includes("已经是最新")) {
+      console.log(`  git: 已是最新`);
+    } else if (pullR.includes("CONFLICT") || pullR.includes("conflict")) {
+      console.log(`  git: ⚠️ 有冲突, 跳过pull(不影响本地工作)`);
+    } else {
+      console.log(`  git: 已拉取最新`);
+    }
+  } catch (e) {
+    console.log(`  git: 跳过(${(e.message || "").slice(0, 50)})`);
+  }
 
   // === 3. 刷新 QoderWork commands（强制覆盖已存在的）===
   runQoderWorkInstall(cwd, true);
@@ -537,6 +565,7 @@ function doUpdate() {
 
   // === 5. 清理旧版废弃文件 ===
   const OBSOLETE_FILES = [
+    // 旧脚本(已替代)
     ".qoder/workflow.md",                      // 被 rules/wl-pipeline.md 替代
     ".qoder/scripts/code_index.py",            // 被 git_sync.py 替代
     ".qoder/scripts/notify.py",                // 被 common/feishu.py 替代
@@ -546,6 +575,35 @@ function doUpdate() {
     ".qoder/templates/qoder/scripts/code_index.py",
     ".qoder/templates/qoder/scripts/notify.py",
     ".qoder/templates/qoder/scripts/team.py",
+    // 旧命令(已合并进 /wl-prd 和 /wl-design)
+    ".qoder/commands/wl-prd-full.md",
+    ".qoder/commands/wl-prd-quick.md",
+    ".qoder/commands/wl-prd-review.md",
+    ".qoder/commands/wl-design-draw.md",
+    ".qoder/commands/wl-design-scan.md",
+    ".qoder/commands/wl-design-spec.md",
+    // 旧版索引JSON(已迁移到DuckDB, 残留在老用户的data/index/)
+    "data/index/keyword-index.json",
+    "data/index/api-index.json",
+    "data/index/prd-index.json",
+    "data/index/module-map.json",
+    "data/index/prd-code-map.json",
+    "data/index/callgraph.json",
+    "data/index/style-index.json",
+    "data/index/style-meta.json",
+    "data/index/vben-style-reference.json",
+    "data/index/chart-style-reference.json",
+    "data/index/icon-reference.json",
+    "data/index/wiki-index.json",
+    // 旧运行时缓存(自动重建)
+    "data/index/.file-keys.json",
+    "data/index/.inverted-cache.json",
+    "data/index/.api-table-cache.json",
+    // 旧learning空壳(未实现的功能占位)
+    ".qoder/learning/patterns/code-patterns.md",
+    ".qoder/learning/patterns/prd-patterns.md",
+    ".qoder/learning/patterns/review-fixes.md",
+    // 用户级旧命令(已合并的, 清理~/.qoderwork/commands/)
   ];
   let cleaned = 0;
   for (const f of OBSOLETE_FILES) {
@@ -563,6 +621,30 @@ function doUpdate() {
     }
   }
   // 清理 .new 临时文件 (上次升级生成的配置对比文件)
+  try {
+    for (const f of fs.readdirSync(path.join(cwd, ".qoder"))) {
+      if (f.endsWith(".new")) {
+        fs.unlinkSync(path.join(cwd, ".qoder", f));
+        cleaned++;
+      }
+    }
+  } catch { /* */ }
+
+  // 清理用户级旧命令 (已合并的, ~/.qoderwork/commands/)
+  const home = process.env.USERPROFILE || require("os").homedir();
+  const userCmdDir = path.join(home, ".qoderwork", "commands");
+  const OBSOLETE_USER_CMDS = [
+    "wl-prd-full.md", "wl-prd-quick.md", "wl-prd-review.md",
+    "wl-design-draw.md", "wl-design-scan.md", "wl-design-spec.md",
+  ];
+  for (const f of OBSOLETE_USER_CMDS) {
+    const fp = path.join(userCmdDir, f);
+    if (fs.existsSync(fp)) {
+      try { fs.unlinkSync(fp); console.log(`  [清理] 用户级旧命令: ${f}`); cleaned++; }
+      catch { /* */ }
+    }
+  }
+  // 清理 .new 临时文件 (上次升级生成的配置对比文件)
   try {
     for (const f of fs.readdirSync(path.join(cwd, ".qoder"))) {
       if (f.endsWith(".new")) {
@@ -619,6 +701,45 @@ function doUpdate() {
     }
   } catch (e) { /* 刷新失败不阻塞升级 */ }
 
+  // === 8. 自检: 关键文件到底齐不齐 ===
+  console.log(`\n--- 自检 (关键文件验证) ---`);
+  const checks = [
+    ["requirements.txt", path.join(cwd, "requirements.txt"), "依赖清单(没它pip装不了)"],
+    ["duckdb(pip)", null, "知识图谱核心依赖"],
+    ["kg.duckdb", path.join(cwd, "data", "index", "kg.duckdb"), "代码图谱(MCP需要)"],
+    ["kg_db.duckdb", path.join(cwd, "data", "index", "kg_db.duckdb"), "数据库图谱(table_impact需要)"],
+    [".qoder/commands/", path.join(cwd, ".qoder", "commands"), "斜杠命令"],
+  ];
+  let allOk = true;
+  for (const [label, p, desc] of checks) {
+    if (p === null) {
+      // duckdb 用 python 检测
+      try {
+        execSync(`${pyCmd || "python"} -c "import duckdb"`, { stdio: "pipe", timeout: 5000 });
+        console.log(`  [✓] ${label} - ${desc}`);
+      } catch {
+        console.log(`  [✗] ${label} 缺失! ${desc}`);
+        console.log(`       → 修复: pip install duckdb -i https://pypi.tuna.tsinghua.edu.cn/simple`);
+        allOk = false;
+      }
+    } else if (fs.existsSync(p)) {
+      console.log(`  [✓] ${label}`);
+    } else {
+      console.log(`  [✗] ${label} 缺失! ${desc}`);
+      if (label.includes("duckdb")) {
+        console.log(`       → 修复: npx @hupan56/wlkj run kg_build.py --rebuild`);
+      } else if (label.includes("commands")) {
+        console.log(`       → 修复: npx @hupan56/wlkj update`);
+      }
+      allOk = false;
+    }
+  }
+  if (!allOk) {
+    console.log(`\n  ⚠️ 有缺失项, 按上面的提示修复后重跑 update。`);
+  } else {
+    console.log(`  全部关键文件就绪 ✓`);
+  }
+
   console.log(`\n${"=".repeat(50)}`);
   console.log(`  升级完成!  (v${PKG_VERSION})`);
   console.log(`${"=".repeat(50)}`);
@@ -663,35 +784,24 @@ function doHelp() {
   console.log("");
   console.log(`wlkj - AI 产品研发工作流 (v${PKG_VERSION})`);
   console.log("");
-  console.log("=== 环境安装 (什么都没装时先跑这个) ===");
-  console.log("  npx @hupan56/wlkj install-env       检测+自动装 Node/Python/git");
-  console.log("  npx @hupan56/wlkj install-env --check  只检测不装");
-  console.log("  npx @hupan56/wlkj install-env --location D:\\wldev  指定安装目录");
-  console.log("  npx @hupan56/wlkj add-path D:\\wldev\\nodejs  把目录加到系统 PATH");
-  console.log("");
-  console.log("=== 一键安装 (装好环境后) ===");
-  console.log("  npx @hupan56/wlkj init [你的名字]    安装完整引擎 + 自动初始化");
-  console.log("");
-  console.log("=== 升级 (已装用户, 新版本发布后) ===");
-  console.log("  npx @hupan56/wlkj update              刷新引擎, 保护你的配置");
+  console.log("=== 5 个核心命令 (记住这 5 个就够) ===");
   console.log("");
-  console.log("=== 安装后怎么用 ===");
-  console.log("  在 Qoder (IDE/Quest/QoderWork) 里:");
-  console.log("    说中文: '写个 XX 的需求' '查一下 XX 代码' '建个任务'");
-  console.log("    或斜杠: /wl-prd /wl-search /wl-task /wl-status /wl-report");
+  console.log("  npx @hupan56/wlkj install-env    ① 装环境 (Node/Python/git/pip依赖)");
+  console.log("  npx @hupan56/wlkj init [名字]    ② 装引擎 + 初始化身份");
+  console.log("  npx @hupan56/wlkj update         ③ 升级 (刷新引擎+补依赖+刷MCP)");
+  console.log("  npx @hupan56/wlkj doctor         ④ 体检 (环境/依赖/图谱健康度)");
+  console.log("  npx @hupan56/wlkj sync           ⑤ 推送产出 (PRD/任务/原型)");
   console.log("");
-  console.log("=== 状态 ===");
-  console.log("  npx @hupan56/wlkj status            查看当前状态 + 引擎版本");
+  console.log("=== 万能跑 (想跑任何脚本) ===");
+  console.log("  npx @hupan56/wlkj run <脚本名> [参数]");
+  console.log("  例: npx wlkj run kg_build.py --rebuild");
+  console.log("      npx wlkj run eval_prd.py xxx.md");
   console.log("");
-  console.log("=== 环境修复 ===");
-  console.log("  python .qoder/scripts/init_doctor.py --fix   自动修复环境");
-  console.log("  python .qoder/scripts/setup.py               重新初始化");
+  console.log("=== Qoder 里怎么用 (日常就在这里干) ===");
+  console.log("  说中文: '写个XX的需求' '查XX代码' '建任务' '测一下XX'");
+  console.log("  或斜杠: /wl-prd /wl-design /wl-task /wl-code /wl-test /wl-commit");
   console.log("");
-  console.log("=== Git (中文命令) ===");
-  console.log("  npx @hupan56/wlkj 提交PRD           提交 PRD");
-  console.log("  npx @hupan56/wlkj 提交任务           提交任务");
-  console.log("  npx @hupan56/wlkj 提交               全部提交并推送");
-  console.log("  npx @hupan56/wlkj 拉取最新 / 同步    git pull");
+  console.log("  看不到命令? 新建对话 / 重启 QoderWork");
   console.log("");
 }
 
@@ -874,7 +984,27 @@ switch (cmd) {
   case "status": doStatus(); break;
   case "session": process.stdout.write(py("add_session.py", rest)); break;
   case "help": case "--help": case "-h": doHelp(); break;
-  case "提交": case "推送": case "拉取最新": case "同步":
+
+  // ── 核心 5 个: 装/升/体检/同步/万能跑 ──
+  case "doctor": case "体检":
+    runScript("init_doctor.py", rest); break;
+  case "sync": case "push": case "commit":
+    runScript("team_sync.py", ["push", ...rest.filter(a => a !== "push")]); break;
+  case "pull":
+    runScript("team_sync.py", ["pull"]); break;
+
+  // ── 万能透传: npx wlkj run <脚本名> [参数...] ──
+  // 任何 .qoder/scripts/ 下的脚本都能跑, 不用记命令名
+  // 例: npx wlkj run kg_build.py --rebuild
+  //     npx wlkj run eval_prd.py xxx.md
+  //     npx wlkj run autotest.py quick
+  case "run": {
+    if (!rest[0]) { console.log("用法: npx wlkj run <脚本名> [参数...]\n例: npx wlkj run kg_build.py --rebuild"); break; }
+    runScript(rest[0], rest.slice(1));
+    break;
+  }
+
+  case "提交": case "拉取最新": case "同步":
   case "查看状态": case "提交PRD": case "提交Spec": case "提交任务":
     gitOp(cmd); break;
   default: doHelp();

package/package.json

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

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

@@ -1,32 +1,125 @@
 ---
 name: wl-design
-description: "设计工序入口: import 录入设计稿→spec.json(默认) / generate 按设计spec出原型 / review 评审原型。"
-argument-hint: "<需求描述>"
+description: "设计工序: 预览(蓝湖稿→HTML) / 扫描(看系统现状) / 评审(检查合规)。设计师在蓝湖画完,一条链接出预览。"
+argument-hint: "[预览|扫描|评审] <蓝湖链接或功能名>"
 auto-approve: true
-allowed-tools: [Read, Bash, mcp__qoder-knowledge-graph, mcp__lanhu]
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit, mcp__qoder-knowledge-graph, mcp__lanhu, mcp__qoder-mysql]
 ---
 
-# /wl-design - 设计工序站（总入口）
+# /wl-design - 设计工序站
 
 User input: $ARGUMENTS
 
-> 三个子命令，覆盖 UI 工程师的全部工作：
-> - **scan**（看）→ 理解系统现状（功能模块/操作流程/设计风格/测试覆盖）
-> - **draw**（画）→ 产出界面（新页面/改页面/竞品参考/全新交互）
-> - **spec**（收）→ 设计交付（录入设计稿 + 评审原型）
+> **设计师在蓝湖画 UI，这个命令负责把蓝湖稿接入工作流。**
+> 模块契约：`.qoder/contracts/design.md`
 
-## 不带子命令时
+## 🚦 路由（看第一个词）
 
-如果用户直接 `/wl-design <描述>`（不带 -draw/-scan/-spec 后缀），AI 从描述判断：
+| 用户说 | 模式 | 干啥 |
+|--------|------|------|
+| "预览""出预览""蓝湖链接""看看设计稿" 或 含 lanhuapp.com | **预览** | 蓝湖稿 → HTML 预览 |
+| "扫描""看系统""有哪些页面""什么风格" | **扫描** | 看现有系统页面/组件/风格 |
+| "评审""检查""合规""颜色对不对" | **评审** | 检查 HTML 预览是否用了系统真源 |
+| 其他 / 不确定 | 先问：预览蓝湖稿、扫描系统、还是评审原型？ |
 
-| 描述特征 | 推荐 |
-|---------|------|
-| "出个""画个""做个""改个" | → `/wl-design-draw` |
-| "看看""有哪些""什么风格""影响什么" | → `/wl-design-scan` |
-| "录入""评审""检查""Figma" | → `/wl-design-spec` |
-| 判断不了 | 问一句："你要画原型(draw)、看系统现状(scan)、还是录入/评审(spec)？" |
+---
+
+## 预览：蓝湖稿 → HTML（核心能力）
+
+**场景**：设计师在蓝湖画完 UI，发链接给你，AI 一键转成 HTML 预览给产品确认交互。
+
+### 流程（2 步，走 lanhu MCP）
+
+**Step 1：列设计稿**
+```
+mcp__lanhu__lanhu_get_designs(url="<蓝湖链接>")
+```
+- 蓝湖链接含 `pid`（项目 ID），如 `https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=xxx`
+- 返回设计稿列表（名称 + 序号）
+
+**Step 2：分析出 HTML**
+```
+mcp__lanhu__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 预览已生成: workspace/members/{dev}/drafts/prototype-{feature}.html
+   来源: 蓝湖设计稿 → lanhu MCP → HTML+CSS
+   打开文件可直接预览交互。
+```
+
+### 注意
+- 蓝湖链接必须有 `pid`（项目 ID），分享链接先用 `lanhu_resolve_invite_link` 解析
+- 如果蓝湖 cookie 过期 → 提示"蓝湖登录态过期，重新配置：setup_lanhu.py"
+- 如果是 Axure 原型（非 UI 设计稿）→ 用 `lanhu_get_ai_analyze_page_result`（分析交互流程）
+
+---
+
+## 扫描：看系统现状（画之前用）
+
+**场景**：画 UI 前想看现有系统有哪些页面、用什么风格、有哪些组件可复用。
+
+### 流程（1 次调用取全）
+```
+mcp__qoder-knowledge-graph__context_pack(keyword='<功能名>', platform='web')
+```
+返回 8 段：相关代码 + 同类页面 + 字段 + API + 风格 token + 组件 + 数据库表结构。
+
+**重点关注**：
+- 第 2 段（同类页面示例）→ 看现有页面长什么样
+- 第 6 段（风格真源）→ 颜色/字号/间距 token
+- `get_design_system(platform='web')` → 拿 Vben Admin 设计系统详情
+
+### 完成后提示
+```
+📋 系统现状扫描完成:
+   - 现有页面: X 个同类页面（列出）
+   - 设计系统: 主色 #xxx, 组件 Space/Modal/Select...
+   - 可复用组件: 列出 top 5
+```
+
+---
+
+## 评审：检查合规
+
+**场景**：HTML 预览生成后，检查颜色/图标/间距是否用了系统真源（不是瞎编的）。
+
+### 检查项
+- [ ] 颜色来自 `data/index/ref-vben-style.json`（不是随便填的色值）
+- [ ] 图标来自 `data/index/ref-icon.json`（Web=Ant Design SVG / APP=Vant，**禁 emoji**）
+- [ ] 间距/字号符合设计系统 token
+- [ ] 组件用法和现有页面一致
+
+### 流程
+```
+读 HTML 预览文件 → 比对 get_design_system(platform='web') → 输出 PASS 或问题清单
+```
+
+输出：`✅ PASS` 或 `🔴/🟡 问题清单`（按严重程度分级）。
+
+---
+
+## 平台必问
+
+如果用户没说平台，先问：
+```
+这个设计是针对哪个平台？
+1. Web 管理端 (fywl-ui) - Ant Design Vue + Vben
+2. APP 移动端 (Carmg-H5) - Vant
+请选择 (1/2):
+```
+```
+（两端都要也行，但分别处理）
+```
+
+---
+
+## 埋点（评审完成后）
 
-> 但推荐用户直接用带后缀的命令（更准确）：
-> `/wl-design-draw 营业外合同`
-> `/wl-design-scan 资产管理`
-> `/wl-design-spec 录入`
+评审输出后，记录到 learning：
+```bash
+python "$R/.qoder/scripts/learn.py" record review_done "{\"target\":\"$feature\",\"result\":\"$pass_or_issues\"}"
+```

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

@@ -1,27 +1,99 @@
 ---
 name: wl-prd
-description: "[已废弃] 旧的单命令已拆分。请用 /wl-prd-full /wl-prd-quick /wl-prd-review"
+description: "需求: 完整(13章,新功能) / 快速(6章,小改动) / 评审(检查质量)。默认根据描述自动判断。"
+argument-hint: "[完整|快速|评审] [需求描述]  可选: 参考:<insight报告路径>"
 auto-approve: true
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit, mcp__qoder-knowledge-graph, mcp__qoder-mysql]
 ---
 
-# /wl-prd - 已废弃（拆分为 3 个独立命令）
+# /wl-prd - 需求工序站
 
-> ⚠️ **本命令已废弃。** `/wl-prd` 的单命令 + 参数路由（`快速`/`深度`/`探讨`）已拆成 3 个独立命令，
-> **只准 `/wl-prd-xx` 形式触发**。请改用：
+User input: $ARGUMENTS
 
-| 你要做什么 | 用哪个命令 |
-|-----------|-----------|
-| 写正经需求（新模块/新业务/新流程），完整 13 章 PRD + 原型 | **`/wl-prd-full`** |
-| 小改动（加字段/加按钮/改文案），极速 Mini-PRD | **`/wl-prd-quick`** |
-| 评审已有 PRD 的质量 | **`/wl-prd-review`** |
+> **写需求 / 评审需求，一个命令搞定。**
+> 模块契约：`.qoder/contracts/prd.md`
 
-## 旧用法对照
+## 🚦 路由（看第一个词或描述特征）
 
-| 旧用法（已废弃） | 新用法 |
-|----------------|--------|
-| `/wl-prd 快速：<需求>` | `/wl-prd-quick <需求>` |
-| `/wl-prd <需求>`（默认） | `/wl-prd-full <需求>` |
-| `/wl-prd 参考：<报告>`（衔接 insight） | `/wl-prd-full 参考：<报告>` |
-| `/wl-prd 深度` / `/wl-prd 探讨` | `/wl-prd-full`（探索类已归 `/wl-insight`） |
+| 用户说 | 模式 | 走哪个 |
+|--------|------|--------|
+| "完整""深度""正经需求" 或 描述含"新模块/新业务/新流程" | **完整** | prd-full-template（13 章）|
+| "快速""小改动""加个""改下" 或 加字段/按钮/文案/导出 | **快速** | prd-quick-template（6 章）|
+| "评审""检查""质量""合格吗" | **评审** | 7 项 checklist + EVA 评分 |
+| 判断不了 | **问一句**："是完整需求(新功能)还是小改动(加字段/按钮)？" |
 
-> 旧参数路由模式不再支持。输入 `/wl-prd-` 可看到 3 个新命令。
+### 默认规则
+- 没说模式 + 描述像新功能 → 默认**完整**
+- 没说模式 + 描述像小改动 → 默认**快速**
+- 给了 PRD 文件路径 → **评审**
+
+---
+
+## 完整模式（13 章 PRD）
+
+**新模块/新业务/新流程用这个。** 支持衔接 insight：`参考:<报告路径>`
+
+**铁律：平台必问。** 先问：
+```
+这个需求是针对哪个平台？
+1. Web 管理端 (fywl-ui)
+2. APP 移动端 (Carmg-H5)
+3. 两端都要
+请选择 (1/2/3):
+```
+
+### 取上下文（1 次调用取全 8 段）
+```bash
+python "$R/.qoder/scripts/context_pack.py" <业务词> --platform <web|app>
+```
+- 第 4 段 = 历史 PRD（防重复）
+- 第 5 段 = 相关 API
+- 第 8 段 = 数据库表结构+真实字段
+- 涉及枚举字段时额外调 `mcp__qoder-mysql__query_distinct`
+
+### 产出
+- PRD: `workspace/members/{dev}/drafts/REQ-{YYYY}-{NNN}-{标题}.md`（13 章）
+- 原型: `workspace/members/{dev}/drafts/prototype-{feature}.html`
+- 第一行必须带 `@contract` 头（platform/req-id/mode/acceptance）
+
+### 质量门禁
+```bash
+python "$R/.qoder/scripts/eval_prd.py" <prd.md> [原型.html]
+```
+≥ 80% 才 PASS。完整模板见 `.qoder/templates/prd-full-template.md`。
+
+---
+
+## 快速模式（6 章 Mini-PRD）
+
+**加字段/加按钮/改文案/加导出等零星需求专用。** 极速，不走 EVA。
+
+**平台必问**（同上）。
+
+### 产出
+- Mini-PRD: `workspace/members/{dev}/drafts/REQ-{YYYY}-{NNN}-{标题}.md`（6 章）
+- 6 章：功能入口 / 需求背景 / 需求说明 / 影响范围 / 验收标准 / 不在本次范围
+- 模板见 `.qoder/templates/prd-quick-template.md`
+
+---
+
+## 评审模式（7 项 checklist + EVA）
+
+**检查 PRD 完整性与质量。**
+
+### 流程
+1. 不给文件 → 列出最近的 PRD 让用户选
+2. 7 项 checklist 逐项检查：
+   - 验收标准是否可测
+   - 字段是否引用了真实数据库字段
+   - 影响范围是否评估
+   - 非功能性需求是否覆盖
+   - ...
+3. 跑 EVA 评分：`eval_prd.py <prd.md>`
+4. 输出：总分 + 7 项 ✓/✗ + 改进建议
+
+---
+
+## 埋点
+
+PRD 生成/评审后自动记录到 learning（eval_prd.py 已内置）。

package/templates/qoder/scripts/git_sync.py

@@ -199,7 +199,11 @@ def collect_prds():
             is_updated = not is_new and collected[key].get('mtime', 0) < prd['mtime']
 
             if is_new or is_updated:
-                dst = os.path.join(PRD_DIR, prd['file'])
+                # 按年月聚合: data/docs/prd/{YYYY-MM}/REQ-xxx.md
+                prd_year_month = datetime.now().strftime('%Y-%m')
+                prd_subdir = os.path.join(PRD_DIR, prd_year_month)
+                os.makedirs(prd_subdir, exist_ok=True)
+                dst = os.path.join(prd_subdir, prd['file'])
                 shutil.copy2(prd['path'], dst)
                 collected[key] = {
                     'user': prd['user'],