@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/root/AGENTS.md

@@ -1,237 +1,275 @@
-# QODER Pipeline
-
-## ⚠️ CRITICAL RULE #1: ALWAYS ASK PLATFORM FIRST
-
-**When user asks for PRD or prototype, you MUST ask this question FIRST:**
-
-```
-这个需求是针对哪个平台？
-
-1. **Web 管理端** (fywl-ui) - Ant Design Vue + VxeGrid 风格
-2. **APP 移动端** (Carmg-H5) - Vant 风格  
-3. **两端都要**
-
-请选择 (1/2/3):
-```
-
-**DO NOT skip this question. DO NOT auto-detect. ALWAYS ASK.**
-**Wait for user answer before doing ANYTHING else.**
-**DO NOT search/read/analyze in the same turn as asking — the reply MUST end after the question.**
-Asking platform + simultaneously searching code in the same response is a VIOLATION.
-
----
-
-## CRITICAL RULE #2: Use /wl-search to find code
-
-When user asks about code, business, API, feature:
-1. **ALWAYS** use `/wl-search <keyword>` command first
-2. Then read only the specific files returned
-3. **NEVER** grep the entire codebase directly
-
-Examples:
-- "考勤代码在哪" -> /wl-search attendance
-- "保险定时任务" -> /wl-search insurance
-- "薪资API" -> /wl-search --api salary
-
-## CRITICAL RULE #2.5: 自然语言 → 技能 路由（Quest / QoderWork 入口）
-
-Quest 与 QoderWork 没有斜杠命令，AI 必须按下表把用户自然语言映射到
-`.qoder/skills/` 下的技能（Qoder IDE 编辑器与 CLI 用 `/wl-*` 命令，同样适用）：
-
-| 用户说什么 | 触发 skill |
-|------------|-----------|
-| "写个需求""生成PRD""做个原型""新模块" | /wl-prd-full（完整档，正经需求）|
-| "加个字段""加个导出按钮""改下文案""小改动" | /wl-prd-quick（快档，零星需求）|
-| "评审PRD""检查需求文档""PRD质量怎么样""这个PRD合格吗" | /wl-prd-review（评审 PRD 质量）|
-| "录入设计稿""Figma稿录入""把这个设计录入" | wl-design import (design-import) |
-| "按设计出原型""按设计师规范出原型" | wl-design generate (prototype-generator) |
-| "评审原型""设计稿看一下""检查交互稿" | wl-design review (design-review) |
-| "查一下""代码在哪""搜保险""考勤API" | wl-search |
-| "建任务""排优先级""任务做完了" | wl-task |
-| "项目怎么样""进度""健康度" | wl-status |
-| "写日报""周报""我干了啥" | wl-report |
-| "调研""竞品""对标""规划""路线图""接下来做什么""发现个机会""探讨需求" | wl-insight（探索站）|
-| "生成规格""写spec" | spec-generator |
-| "开始写代码""按规格实现" | spec-coder |
-| "测一下XX支不支持YY""验一下XX能不能""XX功能对不对""跑测试用例""回归测试" | /wl-test（测试工作流, 命令或带验证点的自然语言触发） |
-| "写单元测试""补单测" | /wl-test unit（test-generator） |
-| "评审PRD" | prd-review |
-| "提交代码""commit""推上去" | wl-commit |
-| "初始化""换开发者""环境检查" | wl-init |
-
-找不到明确匹配 → 先问用户意图，不要乱跑。
-注意区分："同步/保存产出" = team_sync（push）；"提交/commit 代码" = wl-commit。
-
-## CRITICAL RULE #3: User NEVER touches git
-
-PMs on this team do not know git. ALL git operations are invisible:
-- After any publish/save action (/wl-prd-full publish, /wl-task create/finish,
-  /wl-report save), run: `python .qoder/scripts/team_sync.py push`
-- To get teammates' latest work: `python .qoder/scripts/team_sync.py pull`
-- If team_sync prints SYNC_CONFLICT, YOU (the AI) resolve the conflict
-  yourself (it tells you the commands). NEVER ask the user to run git.
-- When the user says 同步/保存/提交 in natural language -> team_sync, not raw git.
-
-## Platform Filtering
-
-After user selects platform, use it for search:
-
-```bash
-# Search by platform
-/wl-search 保险 --platform web      # Only fywl-ui (PC)
-/wl-search 保险 --platform app      # Only Carmg-H5 (Mobile)
-/wl-search 保险                       # Both platforms
-
-# Platform shortcuts
-web/pc/管理端 -> fywl-ui
-app/mobile/h5/移动端 -> Carmg-H5
-```
-
-## Commands: 7 Core (小而美) + Optional
-
-> 认知面只暴露 7 个核心命令，每个是一道工序站，每个带模式参数。
-> **一个命令当多个用**——记不住参数也没关系，自然语言一样路由。
-> 模块契约（输入/输出/校验）见 `.qoder/contracts/`。
-
-### 7 Core Commands（记住这 7 个就够）
-
-| Command | 工序站 | 模式参数（第一个词路由） | Auto | 背后 skill |
-|---------|--------|------------------------|------|-----------|
-| `/wl-init` | 身份 | （无） | YES | wl-init |
-| `/wl-prd-full` | 需求（完整档） | 支持 `参考:<报告>` 衔接 insight | YES | prd-generator |
-| `/wl-prd-quick` | 需求（小改动） | （无） | YES | prd-generator |
-| `/wl-prd-review` | 需求（评审） | （无） | YES | prd-review |
-| `/wl-design` | 设计 | `import`/`generate`/`review` 或默认(import) | YES | design-import/prototype-generator/design-review |
-| `/wl-task` | 任务 | `create`/`list`/`start`/`finish` | YES | wl-task |
-| `/wl-code` | 编码 | （无，按 spec 实现） | NO | spec-coder |
-| `/wl-test` | 测试 | `quick`/`browser`/`unit` 或默认(quick) | NO | wl-test / test-generator |
-| `/wl-commit` | 提交 | （无） | NO | wl-commit |
-
-### Optional Commands（长大了再开，非执行链路必经）
-
-> 物理上归在 `.qoder/commands/optional/` 子目录（Qoder IDE 会按子目录归类显示），
-> QoderWork 安装脚本已支持递归扫描，4 个照样能装到用户级。
-
-| Command | 用途 | 何时用 |
-|---------|------|--------|
-| `/wl-search` | 代码索引搜索 | 全员工具，按需，非工序站 |
-| `/wl-spec` | PRD→技术规格 | 需求复杂时（小团队可直接 `/wl-code`） |
-| `/wl-status` | 项目健康度/路线图 | 需要 PMO/汇报时 |
-| `/wl-report` | 日报周报 | 需要向上汇报时 |
-| `/wl-insight` | 需求探索/外部调研/未来规划 | 需求方向没定、要做调研或规划时（位于 /wl-prd-full 之前）|
-
-> **新人只需记 7 个核心命令**，能把活从需求干到提交。可选 5 个按场景启用。
-
-## Knowledge Index
-
-3 projects: Carmg-H5(1378 files), fywl-ics(8973 files, 3903 APIs), fywl-ui(3270 files)
-Search: /wl-search <keyword> returns compact results (~200 bytes)
-Weekly sync: python .qoder/scripts/git_sync.py
-
-### MCP Servers (QoderWork / Qoder IDE)
-注册在 `~/.qoderwork/mcp.json`，setup.py 一键配齐：
-- `qoder-knowledge-graph` (stdio) — 本仓库知识图谱，13 个工具 (search_code/api, get_impact, context_360, fill_prototype, get_design_system...)。自动拉起。
-- `playwright` (stdio) — 浏览器自动化，快且稳。自动拉起。
-- `qoder-mysql` (stdio) — 只读查真实数据库结构/数据。自动拉起。
-- `lanhu` (STDIO) — 蓝湖设计稿直读，设计师发链接 AI 提取颜色/尺寸/字体/切图。
-  **STDIO 模式：开 QoderWork 自动起、关自动停**（QoderWork 原生进程管理，无需手动 start）。
-  cookie 按角色隔离（UI 能改稿/PM 只读）：wrapper 读当前 `.developer` → 该角色的 `workspace/members/{dev}/.secrets/lanhu.env`（gitignored）。换角色改 `.developer` + 配该角色 cookie → 重启 QoderWork。首次配置跑 `python .qoder/scripts/setup_lanhu.py`。
-
-### Style Index (Prototype Reference)
-UI patterns from Vue files: Tables(718), Forms(301), Detail(129), Dashboard(90)
-Top components: Space(583), Modal(270), Select(172), Input(134)
-Form components: Input(2262), Select(1049), ApiSelect(725), DatePicker(265)
-Field map: 2383 entries
-
-Style search:
-  python .qoder/scripts/search_index.py --style table/form/modal/dashboard
-  python .qoder/scripts/search_index.py --field <field_name>
-  python .qoder/scripts/search_index.py --components
-  python .qoder/scripts/search_index.py --vben    # Vben Admin CSS variables
-
-Prototype templates:
-  .qoder/templates/prototype-web.html   # Web管理端 (Vben Admin + Ant Design)
-  .qoder/templates/prototype-app.html   # APP移动端 (Vant)
-
-Prototype output: workspace/members/{dev}/drafts/prototype-{feature}.html
-Style priority: Code > PDF > Default
-
-## Workflow: 契约网（非强制流水线）
-
-模块间**不强制顺序**，靠标准契约文件对接（详见 `.qoder/contracts/`）。
-完整链路**可以**这么走，但任何模块都能独立开机：
-
-```
-/wl-init → /wl-prd-full (ASK PLATFORM!) → /wl-design → /wl-task → /wl-code → /wl-test → /wl-commit
-  身份       需求        设计          任务        编码        测试        提交
-```
-
-**独立性**：每个模块认文件不认流程。缺上游 → 手动喂个契约文件，或用自然语言 +
-`context_pack.py` 让 AI 自检索补全（见 `.qoder/contracts/fallback.md`）。
-
-## Qoder 全系列兼容（IDE / Quest / CLI / QoderWork）
-
-This pipeline works on Windows + macOS, across the **whole Qoder family**.
-Each product loads rules from a different carrier — keep them in sync:
-
-| 产品/模式 | 规则载体 | 命令载体 |
-|-----------|---------|---------|
-| Qoder IDE 默认编辑器 | .qoder/rules/wl-pipeline.md (always_on) | .qoder/commands/wl-*.md |
-| Qoder Quest 模式 | .qoder/rules/ + .qoder/skills/ + .qoder/agents/ | 自然语言 -> skills |
-| Qoder CLI (qodercli) | 本文件 AGENTS.md | 自然语言 -> scripts |
-| QoderWork 桌面 Agent | 安装 .qoder/skills/ 下的技能 | 自然语言 -> skills |
-
-> 本流水线聚焦 Qoder 全系列，4 种载体功能等价。知识图谱 13 个能力（影响分析/
-> 覆盖矩阵/功能画像/业务流程/多跳遍历…）通过统一 CLI `python .qoder/scripts/kg.py`
-> 全系列触达；QoderWork 环境也可直接调 MCP 工具。
-
-## QoderWork Integration: Optional Enhancement Only (Progressive Enhancement)
-
-> 🔒 **核心原则：本流水线绝不强依赖 QoderWork。**
-> 团队里有人用 Qoder IDE、有人用 Qoder CLI、有人用 QoderWork —— 必须保证前两者开箱即用、功能完整。
-> QoderWork 的「连接器 / 专家套件 / 定时任务」只能是**可选增强**：有就锦上添花，没有就静默回退，绝不报错、绝不阻塞。
-
-具体落实：
-- **本地数据是唯一事实源**：task.json / git log / drafts / index 永远是真相，连接器只是它的"投影/补充"
-- **增强段统一标记 `🧩 QoderWork 增强（可选）`**：出现在 wl-report / wl-task / wl-status 三个 skill 里，每段都明确写"无连接器则自动回退 + 不影响纯 Qoder 使用"
-- **探测而非假设**：只在运行环境真正提供了「日历/待办/邮件」工具可读时才启用增强；看不到就跳过，补一句 `[xx 未启用：非 QoderWork 或未授权连接器]`
-- 已接入的增强点：
-  - `/wl-report` 读日历补"会议/评审"到日报（补 PM/设计岗无提交的空窗）
-  - `/wl-task` 把任务同步为待办 + finish 后标记完成（本地仍为准）
-  - `/wl-status` 用真实日历节点校准"按时交付""团队同步"两维健康度
-- 未来加任何 QoderWork 增强都必须遵循同样原则：**先保证纯 Qoder 可跑，再叠加可选层。**
-
-- THE rule file: `.qoder/rules/wl-pipeline.md` — 修改流程规则时同步更新它和本文件
-- Quest 修改 agents/skills 后需重启 Quest 窗口/新建对话才能生效（Qoder 已知限制）
-- **Repo Wiki** (`.qoder/repowiki/`, Qoder IDE 生成): 存在则作为模块级知识源,
-  写 PRD 前优先查相关模块页；可提交 git 团队共享。索引管"定位", Wiki 管"理解"。
-- All scripts are pure Python 3 + git, path-autodetecting (no hardcoded
-  drive letters). Invoke as `python` (Windows) or `python3` (macOS).
-- Weekly update: Windows -> scripts/setup_weekly_cron.bat,
-  macOS/Linux -> scripts/setup_weekly_cron.sh. Only ONE machine per team
-  needs this; everyone else gets the graph via /wl-init's auto pull.
-- Environment problems of any kind -> run:
-  `python .qoder/scripts/init_doctor.py` (add --fix to auto-repair).
-
-## Fast Path: one call to get all context
-
-`python .qoder/scripts/context_pack.py <业务词> --platform <web|app>` returns
-code files + page examples + field specs + PRDs + APIs + style/icon pointers
-in ONE call. Use it FIRST; fall back to search_index.py for drill-down.
-
-## Icons: NEVER emoji
-
-Prototypes use the projects' real icon systems (data/index/icon-reference.json):
-Web = Ant Design inline SVG, APP = Vant font icons. Emoji in a prototype = FAIL.
-
-## Quality Gate (EVA)
-
-Before publishing any PRD: `python .qoder/scripts/eval_prd.py <prd> [prototype]`
-must PASS (>=80%). Metrics definition: data/docs/constitution/eva-metrics.md
-
-## Permission Model
-
-| Level | Commands | Auto |
-|-------|---------|------|
-| SAFE | /wl-init, /wl-prd-full, /wl-prd-quick, /wl-prd-review, /wl-design, /wl-task, /wl-search, /wl-spec, /wl-status, /wl-insight, /wl-report | YES |
-| DANGEROUS | /wl-code, /wl-test, /wl-commit | NO |
+# QODER Pipeline
+
+## 🏗️ 架构: 引擎与数据分离 (Trellis 化)
+
+`.qoder/` 一分为二 (v2.8.0+):
+
+| 类别 | 内容 | 来源 | 进团队 git? |
+|------|------|------|------------|
+| **引擎代码** | `.qoder/scripts/` `skills/` `commands/` `agents/` `contracts/` `hooks/` `templates/` `rules/` | `npx @hupan56/wlkj init/update` 生成 | ❌ gitignore |
+| **团队数据** | `.qoder/config.yaml` `config.toml` `settings.json` `learning/` + `data/` (kg.duckdb/索引) + `workspace/` (PRD/任务) | git 跟踪, 团队共享 | ✅ |
+
+- 引擎代码**只由 npm 包生成**, 不再进团队 git → 彻底消除"引擎更新污染团队 git"和"新机 init 产生 unrelated histories"。
+- Qoder 全系列仍读 `.qoder/` (路径不变), 只是引擎来源从 git 变成 npm 生成。
+- 老团队升级 (管理员跑一次): `npx @hupan56/wlkj migrate`, 然后团队成员各自 `npx @hupan56/wlkj update`。
+
+---
+
+## ⚠️ CRITICAL RULE #1: ALWAYS ASK PLATFORM FIRST
+
+**When user asks for PRD or prototype, you MUST ask this question FIRST:**
+
+```
+这个需求是针对哪个平台？
+
+1. **Web 管理端** (fywl-ui) - Ant Design Vue + VxeGrid 风格
+2. **APP 移动端** (Carmg-H5) - Vant 风格  
+3. **两端都要**
+
+请选择 (1/2/3):
+```
+
+**DO NOT skip this question. DO NOT auto-detect. ALWAYS ASK.**
+**Wait for user answer before doing ANYTHING else.**
+**DO NOT search/read/analyze in the same turn as asking — the reply MUST end after the question.**
+Asking platform + simultaneously searching code in the same response is a VIOLATION.
+
+---
+
+## CRITICAL RULE #2: Use /wl-search to find code
+
+When user asks about code, business, API, feature:
+1. **ALWAYS** use `/wl-search <keyword>` command first
+2. Then read only the specific files returned
+3. **NEVER** grep the entire codebase directly
+
+Examples:
+- "考勤代码在哪" -> /wl-search attendance
+- "保险定时任务" -> /wl-search insurance
+- "薪资API" -> /wl-search --api salary
+
+## CRITICAL RULE #2.5: 触发方式（非侵入式 — v3.0）
+
+工作流**只在显式调用时启动**，不主动干预普通对话。
+
+**两种触发方式（且仅此两种）：**
+1. **斜杠命令**：`/wl-prd` `/wl-search` `/wl-req` 等 → 启动工作流
+2. **npx**：`npx @hupan56/wlkj init/update` → 安装/同步
+
+**自然语言不触发工作流。** 用户说"写个需求""查下代码"等，AI 正常回答，不自动拉入工作流。
+（工作流启动后的过程内交互 — 如选平台、确认需求 — 仍可用自然语言。）
+
+### 禅道自然查询（非命令，直接回答）
+
+用户随口问禅道（"我的任务""看下#301""Bug 状态""我的需求"）—— **直接用禅道 MCP 工具自然回答**，
+不拉入 `/wl-task` 工作流：
+- QoderWork: `qw_mcp_call("my_workbench", {})` 一行看全（任务+需求+Bug）
+- CLI/其他: `cap.mcp.call("my_workbench")`
+
+只有**显式工序**（`/wl-task` 建需求/记工时/改状态）才走工作流。
+> 工具用真实工具名，别拿需求冒充任务回答（问任务查 task 域，查不到如实说"没有"）。
+
+
+注意区分："同步/保存产出" = team_sync（push）；"提交/commit 代码" = wl-commit。
+
+## CRITICAL RULE #3: User NEVER touches git
+
+PMs on this team do not know git. ALL git operations are invisible:
+- After any publish/save action (/wl-prd publish, /wl-task create/finish,
+  /wl-report save), run: `python .qoder/scripts/task/team_sync.py push`
+- To get teammates' latest work: `python .qoder/scripts/task/team_sync.py pull`
+- If team_sync prints SYNC_CONFLICT, YOU (the AI) resolve the conflict
+  yourself (it tells you the commands). NEVER ask the user to run git.
+- When the user says 同步/保存/提交 in natural language -> team_sync, not raw git.
+
+## Platform Filtering
+
+After user selects platform, use it for search:
+
+```bash
+# Search by platform
+/wl-search 保险 --platform web      # Only fywl-ui (PC)
+/wl-search 保险 --platform app      # Only Carmg-H5 (Mobile)
+/wl-search 保险                       # Both platforms
+
+# Platform shortcuts
+web/pc/管理端 -> fywl-ui
+app/mobile/h5/移动端 -> Carmg-H5
+```
+
+## Commands: 7 Core (小而美) + Optional
+
+> 认知面只暴露 7 个核心命令，每个是一道工序站，每个带模式参数。
+> **一个命令当多个用**——记不住参数也没关系，自然语言一样路由。
+> 模块契约（输入/输出/校验）见 `.qoder/contracts/`。
+
+### 7 Core Commands（记住这 7 个就够）
+
+| Command | 工序站 | 模式参数（第一个词路由） | Auto | 背后 skill |
+|---------|--------|------------------------|------|-----------|
+| `/wl-init` | 身份 | （无） | YES | wl-init |
+| `/wl-prd` | 需求 | 语义路由: 完整档/小改动/评审 (原 wl-prd-full/quick/review 合并) | YES | prd-generator/prd-review |
+| `/wl-design` | 设计 | `import`/`generate`/`review` 或默认(import) | YES | design-import/prototype-generator/design-review |
+| `/wl-task` | 任务 | `create`/`list`/`start`/`finish` | YES | wl-task |
+| `/wl-code` | 编码 | （无，按 spec 实现） | NO | spec-coder |
+| `/wl-test` | 测试 | `quick`/`browser`/`unit` 或默认(quick) | NO | wl-test / test-generator |
+| `/wl-commit` | 提交 | （无） | NO | wl-commit |
+
+### Optional Commands（长大了再开，非执行链路必经）
+
+> 物理上归在 `.qoder/commands/optional/` 子目录（Qoder IDE 会按子目录归类显示），
+> QoderWork 安装脚本已支持递归扫描，4 个照样能装到用户级。
+
+| Command | 用途 | 何时用 |
+|---------|------|--------|
+| `/wl-search` | 代码索引搜索 | 全员工具，按需，非工序站（物理在 `commands/` 顶层） |
+| `/wl-req` | 需求 CRUD + 发布 | 需求生命周期管理（创建/编辑/发布/归档） |
+| `/wl-spec` | PRD→技术规格 | 需求复杂时（小团队可直接 `/wl-code`） |
+| `/wl-status` | 项目健康度/路线图 | 需要 PMO/汇报时 |
+| `/wl-report` | 日报周报 | 需要向上汇报时 |
+| `/wl-insight` | 需求澄清对焦(默认)/调研/规划 | 需求模糊听不懂、要做调研或规划时（位于 /wl-prd 之前）。最高频:产品听不懂用户时快速对焦(必要时出原型图帮助理解),对齐后再问要不要调研 |
+
+> **新人只需记 7 个核心命令**，能把活从需求干到提交。可选 6 个按场景启用。
+
+## Knowledge Index
+
+3 projects: Carmg-H5(1378 files), fywl-ics(8973 files, 3903 APIs), fywl-ui(3270 files)
+Search: /wl-search <keyword> returns compact results (~200 bytes)
+Weekly sync: python .qoder/scripts/task/git_sync.py
+
+### MCP Servers (QoderWork / Qoder IDE)
+注册在 `~/.qoderwork/mcp.json`，setup.py 一键配齐：
+- `qoder-knowledge-graph` (stdio) — 本仓库知识图谱，13 个工具 (search_code/api, get_impact, context_360, fill_prototype, get_design_system...)。自动拉起。
+- `playwright` (stdio) — 浏览器自动化，快且稳。自动拉起。
+- `qoder-mysql` (stdio) — 只读查真实数据库结构/数据。自动拉起。
+- `lanhu` (STDIO) — 蓝湖设计稿直读，设计师发链接 AI 提取颜色/尺寸/字体/切图。
+  **STDIO 模式：开 QoderWork 自动起、关自动停**（QoderWork 原生进程管理，无需手动 start）。
+  cookie 按角色隔离（UI 能改稿/PM 只读）：wrapper 读当前 `.developer` → 该角色的 `workspace/members/{dev}/.secrets/lanhu.env`（gitignored）。换角色改 `.developer` + 配该角色 cookie → 重启 QoderWork。首次配置跑 `python .qoder/scripts/setup/setup_lanhu.py`。
+
+### Style Index (Prototype Reference)
+UI patterns from Vue files: Tables(718), Forms(301), Detail(129), Dashboard(90)
+Top components: Space(583), Modal(270), Select(172), Input(134)
+Form components: Input(2262), Select(1049), ApiSelect(725), DatePicker(265)
+Field map: 2383 entries
+
+Style search:
+  python .qoder/scripts/kg/search_index.py --style table/form/modal/dashboard
+  python .qoder/scripts/kg/search_index.py --field <field_name>
+  python .qoder/scripts/kg/search_index.py --components
+  python .qoder/scripts/kg/search_index.py --vben    # Vben Admin CSS variables
+
+Prototype templates:
+  .qoder/templates/prototype-web.html   # Web管理端 (Vben Admin + Ant Design)
+  .qoder/templates/prototype-app.html   # APP移动端 (Vant)
+
+Prototype output: workspace/members/{dev}/drafts/prototype-{feature}.html
+Style priority: Code > PDF > Default
+
+## Workflow: 契约网（非强制流水线）
+
+模块间**不强制顺序**，靠标准契约文件对接（详见 `.qoder/contracts/`）。
+完整链路**可以**这么走，但任何模块都能独立开机：
+
+```
+/wl-init → /wl-prd (ASK PLATFORM!) → /wl-design → /wl-task → /wl-code → /wl-test → /wl-commit
+  身份       需求        设计          任务        编码        测试        提交
+```
+
+**独立性**：每个模块认文件不认流程。缺上游 → 手动喂个契约文件，或用自然语言 +
+`context_pack.py` 让 AI 自检索补全（见 `.qoder/contracts/fallback.md`）。
+
+## Qoder 全系列兼容（IDE / Quest / CLI / QoderWork）
+
+This pipeline works on Windows + macOS, across the **whole Qoder family**.
+Each product loads rules from a different carrier — keep them in sync:
+
+| 产品/模式 | 规则载体 | 命令载体 |
+|-----------|---------|---------|
+| Qoder IDE 默认编辑器 | .qoder/rules/wl-pipeline.md (always_on) | .qoder/commands/wl-*.md |
+| Qoder Quest 模式 | .qoder/rules/ + .qoder/skills/ + .qoder/agents/ | 自然语言 -> skills |
+| Qoder CLI (qodercli) | 本文件 AGENTS.md | 自然语言 -> scripts |
+| QoderWork 桌面 Agent | 安装 .qoder/skills/ 下的技能 | 自然语言 -> skills |
+
+> 本流水线聚焦 Qoder 全系列，4 种载体功能等价。知识图谱 13 个能力（影响分析/
+> 覆盖矩阵/功能画像/业务流程/多跳遍历…）通过统一 CLI `python .qoder/scripts/kg/kg.py`
+> 全系列触达；QoderWork 环境也可直接调 MCP 工具。
+
+## QoderWork Integration: Optional Enhancement Only (Progressive Enhancement)
+
+> 🔒 **核心原则：本流水线绝不强依赖 QoderWork。**
+> 团队里有人用 Qoder IDE、有人用 Qoder CLI、有人用 QoderWork —— 必须保证前两者开箱即用、功能完整。
+> QoderWork 的「连接器 / 专家套件 / 定时任务」只能是**可选增强**：有就锦上添花，没有就静默回退，绝不报错、绝不阻塞。
+
+具体落实：
+- **本地数据是唯一事实源**：task.json / git log / drafts / index 永远是真相，连接器只是它的"投影/补充"
+- **增强段统一标记 `🧩 QoderWork 增强（可选）`**：出现在 wl-report / wl-task / wl-status 三个 skill 里，每段都明确写"无连接器则自动回退 + 不影响纯 Qoder 使用"
+- **探测而非假设**：只在运行环境真正提供了「日历/待办/邮件」工具可读时才启用增强；看不到就跳过，补一句 `[xx 未启用：非 QoderWork 或未授权连接器]`
+- 已接入的增强点：
+  - `/wl-report` 读日历补"会议/评审"到日报（补 PM/设计岗无提交的空窗）
+  - `/wl-task` 把任务同步为待办 + finish 后标记完成（本地仍为准）
+  - `/wl-status` 用真实日历节点校准"按时交付""团队同步"两维健康度
+- 未来加任何 QoderWork 增强都必须遵循同样原则：**先保证纯 Qoder 可跑，再叠加可选层。**
+
+- THE rule file: `.qoder/rules/wl-pipeline.md` — 修改流程规则时同步更新它和本文件
+- Quest 修改 agents/skills 后需重启 Quest 窗口/新建对话才能生效（Qoder 已知限制）
+- **Repo Wiki** (`.qoder/repowiki/`, Qoder IDE 生成): 存在则作为模块级知识源,
+  写 PRD 前优先查相关模块页。索引管"定位", Wiki 管"理解"。
+  ⚠️ Wiki 由宿主从代码自动生成、会被重生成覆盖, **且 .gitignore 已排除** → 不可手写、不进团队 git
+  (团队共享知识走 `data/learning/patterns/` 和 `data/docs/`, 那里可写且进 git)。
+- All scripts are pure Python 3 + git, path-autodetecting (no hardcoded
+  drive letters). Invoke as `python` (Windows) or `python3` (macOS).
+- Weekly update: Windows -> scripts/setup_weekly_cron.bat,
+  macOS/Linux -> scripts/setup_weekly_cron.sh. Only ONE machine per team
+  needs this; everyone else gets the graph via /wl-init's auto pull.
+- Environment problems of any kind -> run:
+  `python .qoder/scripts/setup/init_doctor.py` (add --fix to auto-repair).
+
+## Fast Path: one call to get all context
+
+`python .qoder/scripts/kg/context_pack.py <业务词> --platform <web|app>` returns
+code files + page examples + field specs + PRDs + APIs + style/icon pointers
+in ONE call. Use it FIRST; fall back to search_index.py for drill-down.
+
+## Icons: NEVER emoji
+
+Prototypes use the projects' real icon systems (data/index/icon-reference.json):
+Web = Ant Design inline SVG, APP = Vant font icons. Emoji in a prototype = FAIL.
+
+## Quality Gate (EVA)
+
+Before publishing any PRD: `python .qoder/scripts/report/eval_prd.py <prd> [prototype]`
+must PASS (>=80%). Metrics definition: data/docs/constitution/eva-metrics.md
+
+## Workflow Usability (可用性)
+
+回答"这套工作流对真实团队用不用得起来"——EVA 管 PRD 写得好不好, 本指标管工作流有没有人用。
+```bash
+python .qoder/scripts/orchestration/wlkj.py usability [--days N]   # 或 --json
+```
+- 采纳(主): U1流程采纳率/U2一次过审率/U3返工轮数/U4规则违反率/U5绕过率/U6活跃度
+- 流程(辅): F1端到端闭环率/F2转化漏斗/F3单命令效率/F4流程断点
+- 每条指标标【自动/半自动/待埋点】, 算不了的明说不编造
+- `/wl-status health` 的健康分含「工作流采纳」维度(权重10%)
+- 指标定义 + 公式 + 阈值: `data/docs/constitution/workflow-usability-metrics.md`
+- **交互看板**: `wlkj.py usability --html` → QoderWork 嵌入对话流 / CLI 落盘 dashboard.html
+- **红灯自动沉淀**: 评测红/黄项自动 append 到 `data/learning/patterns/usability-patterns.md`(进 git 团队共享)
+
+## Deterministic Hooks (确定性钩子 · 吸收宿主能力)
+
+把"靠 AI 自觉"的规则升级为"宿主确定性执行"(不漂移、不依赖 LLM 服从性)。配置在 `.qoder/settings.json`:
+
+| Hook | 时机 | 作用 | 阻断? |
+|------|------|------|-------|
+| `SessionStart` | 开会话 | 注入项目上下文 + 可用性红灯到 `<qoder-context>` | 否 |
+| `UserPromptSubmit` | 用户提交 | `/wl-prd-*` 未带平台 → **exit 2 阻断**, 强制先问平台(治违规率) | 是 |
+| `PostToolUse` | 工具执行后 | 写完 PRD/建完任务 → **自动埋点**(治漏斗断链) | 否 |
+| `Stop` | Agent 说完成 | 产出 PRD 未跑 eval → **exit 2 阻断**, 强制 eval≥80%(带防递归) | 是 |
+
+> 钩子契约: `exit 0` 放行 / `exit 2` 阻断(原因写 stderr) / 失败绝不崩会话。脚本草稿在 `.qoder/hooks/`。
+
+## Permission Model
+
+| Level | Commands | Auto |
+|-------|---------|------|
+| SAFE | /wl-init, /wl-prd, /wl-design, /wl-task, /wl-search, /wl-req, /wl-spec, /wl-status, /wl-insight, /wl-report | YES |
+| DANGEROUS | /wl-code, /wl-test, /wl-commit | NO |

package/templates/root/requirements.txt

@@ -19,3 +19,6 @@ playwright>=1.40.0       # 浏览器自动化测试
 # ── 可选增强 (按需装) ──
 ddddocr>=1.4.7           # 验证码识别 (登录测试用)
 cryptography>=37.0.0     # 飞书集成加密 (用飞书通知才装)
+python-docx>=0.8.11      # PRD 导出 Word (export.py docx)
+markdown>=3.5            # PRD 导出 (md→html→pdf 的 md→html 步骤)
+sentence-transformers>=2.2.0  # 语义检索 (管理员装, 概念搜索"报销"命中 expense)

package/templates/root//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -108,7 +108,7 @@ npx @hupan56/wlkj init
    - "写个保险异常筛选的需求"
    - "查一下考勤代码在哪"
    - "建个任务：登录优化"
-3. 或输入 `/` 看所有命令（`/wl-prd-full` `/wl-search` 等）
+3. 或输入 `/` 看所有命令（`/wl-prd` `/wl-search` 等）
 
 **看不到 `/` 命令？**
 - Quest 模式：新建一个对话
@@ -130,8 +130,8 @@ python .qoder/scripts/report.py daily
 
 | 做什么 | 说什么 / 命令 |
 |--------|-------------|
-| 写完整需求 | "写个 XXX 的需求" 或 `/wl-prd-full` |
-| 写小改动 | "快速写个 XXX" |
+| 写完整需求 | "写个 XXX 的需求" 或 `/wl-prd` |
+| 写小改动 | "快速写个 XXX" (自动走 `/wl-prd` 快速档) |
 | 头脑风暴 | "脑暴一下 XXX" |
 | 画原型 | 随需求自动生成 |
 | 评审 PRD | "评审这个 PRD" |

package/templates/root//346/226/260/346/211/213/346/214/207/345/215/227.md

@@ -72,7 +72,7 @@ npx wlkj init
 
 | 命令 | 作用 |
 |------|------|
-| `/wl-prd-full` | 写需求 |
+| `/wl-prd` | 写需求 (完整/快速/评审自动路由) |
 | `/wl-search` | 查代码 |
 | `/wl-task` | 管任务 |
 | `/wl-status` | 看进度 |
@@ -174,7 +174,7 @@ npx wlkj init 你的名字
 
 ```
 新项目     → mkdir 文件夹 && cd 文件夹 && npx wlkj init
-写需求     → /wl-prd-full
+写需求     → /wl-prd
 查代码     → /wl-search
 建任务     → /wl-task
 看进度     → /wl-status