@hupan56/wlkj 3.1.8 → 3.1.9

package/package.json

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

package/templates/qoder/scripts/capability/adapters/mcp.py

@@ -270,9 +270,13 @@ class McpMemoryProvider:
             import hashlib
             import json
             import time as _time
-            from foundation.protocol.duckdb_conn import get_db, init_schema
+            # ⚠ 不能 import init_schema! duckdb_conn 故意不导出它 (领域 DDL 留在各域)。
+            # 旧版 from ...duckdb_conn import init_schema → ImportError → 被下面 except 吞掉
+            # → INSERT 永不执行 → remember() 静默丢全部写入。
+            # learning_events 表已由 self.available 的 CREATE TABLE IF NOT EXISTS 保证存在,
+            # 这里直接 INSERT 即可。
+            from foundation.protocol.duckdb_conn import get_db
             con = get_db()
-            init_schema(con)
             eid = hashlib.md5(("%s:%s:%s" % (key, content, _time.time())).encode()).hexdigest()[:16]
             ts = _time.strftime("%Y-%m-%dT%H:%M:%S")
             data = json.dumps({"content": content}, ensure_ascii=False)

package/templates/qoder/scripts/capability/memory_chain.py

@@ -33,7 +33,9 @@ def build_memory_chain(host: str) -> ProviderChain:
     from .adapters.cli import FileMemoryCap
 
     providers: list = [McpMemoryProvider()]
-    if host == "qoderwork":
+    # ⚠ host 名是 "qoder-work" (带连字符, 见 registry.py:40 detect_host 返回值)。
+    # 旧版写成 "qoderwork" (无连字符) → 永不匹配 → QwMemoryCap 在所有 QoderWork 机器上都不激活。
+    if host == "qoder-work":
         from .adapters.qw import QwMemoryCap
         providers.append(QwMemoryCap())
     providers.append(FileMemoryCap())

package/templates/qoder/scripts/domain/kg/kg_capabilities.py

@@ -158,7 +158,9 @@ def wiki_query(kw):
         return ("wiki-index.json 不存在。请手动构建(一次性):\n"
                 "  python .qoder/scripts/domain/kg/search/search_index.py wiki")
     try:
-        from repowiki import search_wiki
+        # v3.x: repowiki 在 domain/kg/server/ 子包下, 不能裸 from repowiki import
+        # (sys.path 没含 server/, 永远 ModuleNotFoundError → search_wiki 永远报"模块缺失")
+        from domain.kg.server.repowiki import search_wiki
         from foundation.integrations.terms import get_cn_map_with_auto
     except ImportError as e:
         return "Wiki 搜索模块缺失: %s" % str(e)

package/templates/qoder/scripts/domain/kg/search/context_pack.py

@@ -10,7 +10,7 @@ for _ in range(10):
         break
 if _cp not in _s.path: _s.path.insert(0, _cp)
 from bootstrap import setup; setup()
-from foundation.core.paths import get_repo_root
+from foundation.core.paths import get_repo_root
 
 """
 QODER Context Pack - 一次调用返回写 PRD/原型所需的全部上下文
@@ -48,7 +48,7 @@ except (AttributeError, TypeError, OSError, IOError):
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from foundation.integrations.terms import CN_MAP, BUSINESS_PATH_MAP, CN_TO_EN, get_platform_map, expand_chinese_query
 
-BASE = get_repo_root()
+BASE = get_repo_root()
 INDEX_DIR = os.path.join(BASE, 'data', 'index')
 PLATFORM_MAP = get_platform_map()
 MIN_FUZZY_LEN = 4
@@ -309,7 +309,7 @@ def _compute_and_print(query, platform, page_type):
     code_dir = os.path.join(BASE, 'data', 'code')
     wiki_results = []
     try:
-        from repowiki import search_wiki, build_wiki_index
+        from domain.kg.server.repowiki import search_wiki, build_wiki_index
         from foundation.integrations.terms import get_cn_map_with_auto
         wiki_idx_path = os.path.join(BUILD_CACHE_DIR, 'wiki-index.json')
         if not os.path.isfile(wiki_idx_path):

package/templates/qoder/scripts/domain/kg/search/prefetch.py

@@ -296,7 +296,7 @@ def _print_merged(query, platform, primary_cn, en_words, collected):
     code_dir = os.path.join(BASE, 'data', 'code')
     wiki_results = []
     try:
-        from repowiki import search_wiki, build_wiki_index
+        from domain.kg.server.repowiki import search_wiki, build_wiki_index
         wiki_idx_path = os.path.join(BUILD_CACHE_DIR, 'wiki-index.json')
         if not os.path.isfile(wiki_idx_path):
             build_wiki_index(code_dir, wiki_idx_path)

package/templates/qoder/scripts/domain/kg/search/search_index.py

@@ -768,7 +768,7 @@ def show_vben():
 def search_wiki_cli(query):
     """搜 Repo Wiki (Qoder IDE 生成的语义级模块文档)。"""
     try:
-        from repowiki import search_wiki, build_wiki_index
+        from domain.kg.server.repowiki import search_wiki, build_wiki_index
         from foundation.integrations.terms import get_cn_map_with_auto
     except ImportError:
         print('Wiki 搜索不可用 (common.repowiki 模块缺失)')

package/templates/qoder/scripts/protocol/mcp/kg_mcp_server.py

@@ -86,6 +86,23 @@ def _ensure_imports():
 from foundation.protocol.mcp_base import BaseMCPServer, tool
 
 
+def _require_kgdb():
+    """检查 kg.duckdb 是否存在。存在返回 None; 不存在返回友好提示字符串。
+
+    防止 get_db() 创建空库后查询报 CatalogException (49 台没预建图谱的机器)。
+    """
+    try:
+        from foundation.core.paths import DATA_INDEX_DIR
+        db_path = DATA_INDEX_DIR / 'kg.duckdb'
+        if not db_path.is_file():
+            return ("知识图谱未构建 (kg.duckdb 不存在)。请管理员跑:\n"
+                    "  python .qoder/scripts/orchestration/wlkj.py kg-build\n"
+                    "或非管理员: npx @hupan56/wlkj update (会 git pull 拉团队已构建的 kg.duckdb)")
+    except Exception:
+        pass
+    return None
+
+
 class KnowledgeGraphMCPServer(BaseMCPServer):
     """知识图谱 MCP Server。
 
@@ -185,6 +202,11 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
         q = (args.get("module") or '').strip()
         if not q:
             return "请提供模块名。可选: assets/cost/hr/maintenance/operation/qualityAndSafety/veh/settings/dashboard/flow/systems/monitor/quasafe"
+        # ⚠ 先检查 kg.duckdb 存在! get_db() 会创建空库 → 查询报 CatalogException
+        # (49 台没预建图谱的机器会看到原始异常, 而非友好提示)。
+        _hint = _require_kgdb()
+        if _hint:
+            return _hint
         con = get_db()
         try:
             return workflow_query(con, q)
@@ -209,6 +231,9 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
         except (TypeError, ValueError):
             depth = 3
         depth = max(1, min(5, depth))
+        _hint = _require_kgdb()
+        if _hint:
+            return _hint
         con = get_db()
         try:
             return hop_query(con, sym, depth, multi_hop_fn=multi_hop)
@@ -236,6 +261,9 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
     def _t_search_field(self, args):
         from domain.kg.storage.kg_duckdb import get_db
         field = (args.get("field") or '').strip()
+        _hint = _require_kgdb()
+        if _hint:
+            return _hint
         con = get_db()
         try:
             rows = con.execute(
@@ -260,6 +288,9 @@ class KnowledgeGraphMCPServer(BaseMCPServer):
     def _t_list_modules(self, args):
         from domain.kg.storage.kg_duckdb import get_db
         platform = args.get("platform", "")
+        _hint = _require_kgdb()
+        if _hint:
+            return _hint
         con = get_db()
         try:
             if platform == 'web':

package/templates/root/AGENTS.md

@@ -1,275 +1,275 @@
-# 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 |
+# 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) — 本仓库知识图谱，17 个工具 (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 种载体功能等价。知识图谱 17 个能力（影响分析/
+> 覆盖矩阵/功能画像/业务流程/多跳遍历…）通过统一 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 |