@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/hooks/stop-eval.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""stop-eval.py - Stop hook: Agent 说"完成"时强制 eval 门禁 (治"说做完了没真评测")
+
+吸收宿主确定性 hook 能力: 把 EVA 门禁 (PRD 发布前 eval≥80%) 从"靠 AI 自觉跑"
+升级为"Agent 准备结束回复时宿主拦住"。AI 说"PRD 做完了"但没跑 eval → 被拦回继续。
+
+阻断契约: exit 0 放行; exit 2 阻断(stderr 反馈, 强制 Agent 续修)。
+
+防递归 (关键!): Stop hook 被 exit 2 阻断后, Agent 续修完再次 Stop 会再次触发本 hook →
+死循环。必须检查 stdin 的 stop_hook_active: 为 true 时直接 exit 0 放行 (Agent 已在本轮
+被拦过一次, 不再二次拦)。
+
+判断逻辑 (保守, 只拦明确场景):
+  - 本会话最近产出过 PRD 文件 (扫描 workspace/members/*/drafts + tasks/*/prd.md,
+    找近 10 分钟内 mtime 的 prd*.md)
+  - 且该 PRD 没有对应的 eval 记录 (eval-history.jsonl 里查不到该 prd 名)
+  → exit 2 强制 eval
+  其它情况一律 exit 0 (绝不误拦普通对话/非 PRD 工作)。
+
+stdin 字段名官方未公开, 兼容 stop_hook_active / hook_active 等多种写法。
+"""
+import json
+import os
+import sys
+import time
+from datetime import datetime
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+HOOK_ERRORS_LOG = os.path.join(BASE, '.qoder', '.runtime', 'hook-errors.log')
+EVAL_HISTORY = os.path.join(BASE, 'data', 'learning', 'eval-history.jsonl')
+RECENT_WINDOW = 600  # 10 分钟内产出的 PRD 视为本轮产物
+
+
+def _is_reentry(stdin_data):
+    """是否二次进入 (防递归)。兼容多字段名。"""
+    if not isinstance(stdin_data, dict):
+        return False
+    for k in ('stop_hook_active', 'hook_active', 'is_reentry'):
+        v = stdin_data.get(k)
+        if v in (True, 'true', 'True', 1, '1'):
+            return True
+    return False
+
+
+def _read_stdin():
+    try:
+        if sys.stdin.isatty():
+            return {}
+        raw = sys.stdin.read().strip()
+        if not raw:
+            return {}
+        return json.loads(raw)
+    except Exception:
+        return {}
+
+
+def _is_prd_filename(fn):
+    """判断文件名是否是 PRD 产物。
+
+    真实 PRD 有两类命名 (与 eval-history.jsonl 记录的 'prd' 字段对齐):
+      1. workspace/tasks/<task>/prd.md              (任务级 PRD, 文件名含 prd)
+      2. workspace/members/<dev>/drafts/REQ-2026-XXX-<feature>.md
+         (AI 产出的 PRD 草稿, 命名 REQ-<id>-<feature>.md, 不含 'prd' 字样)
+    只匹配 'prd' 会漏掉第 2 类 (绝大多数真实产出) → 门禁形同虚设。
+    这里两类都认: 文件名含 'prd' 或 以 'REQ-' 开头 (eval-history 的真实记录格式)。
+    """
+    low = fn.lower()
+    if not low.endswith('.md'):
+        return False
+    return 'prd' in low or low.startswith('req-')
+
+
+def _recent_prd_files():
+    """找近 RECENT_WINDOW 秒内产出的 PRD 文件 (绝对路径)。扫描 drafts + tasks。"""
+    now = time.time()
+    candidates = []
+    search_roots = [
+        os.path.join(BASE, 'workspace', 'members'),
+        os.path.join(BASE, 'workspace', 'tasks'),
+        os.path.join(BASE, 'data', 'docs', 'prd'),
+    ]
+    for root in search_roots:
+        if not os.path.isdir(root):
+            continue
+        for dirpath, dirs, files in os.walk(root):
+            # 跳过无关大目录
+            dirs[:] = [d for d in dirs if d not in ('node_modules', '.git', '__pycache__', '.secrets')]
+            for fn in files:
+                if not _is_prd_filename(fn):
+                    continue
+                fp = os.path.join(dirpath, fn)
+                try:
+                    if now - os.path.getmtime(fp) <= RECENT_WINDOW:
+                        candidates.append(fp)
+                except OSError:
+                    continue
+    return candidates
+
+
+def _evald_prds():
+    """读 eval-history.jsonl, 返回【已通过门禁】的 prd 文件名集合。
+
+    门禁定义 (与消息承诺一致): 该 PRD 最近一次 eval 记录 passed=True 或 score_pct>=80。
+    只"跑过 eval 但没过线"的不算通过 → 仍需拦回去重测。
+    eval-history.jsonl 是 append-only, 同一 PRD 可能有多条 → 取最后一条为准。
+    """
+    last = _last_record_by_prd()
+    done = set()
+    for key, r in last.items():
+        passed = r.get('passed')
+        score = r.get('score_pct')
+        is_ok = (passed is True) or (isinstance(score, (int, float)) and score >= 80)
+        if is_ok:
+            done.add(key)
+    return done
+
+
+def _last_record_by_prd():
+    """读 eval-history.jsonl, 返回 {prd_basename: 最后一条记录}。
+
+    append-only 文件, 后出现的记录覆盖前面的 → 取每个 PRD 的最新 eval。
+    被门禁诊断复用 (区分"没跑过 eval" vs "跑了但没过线")。
+    """
+    last_by_prd = {}
+    if not os.path.isfile(EVAL_HISTORY):
+        return last_by_prd
+    try:
+        with open(EVAL_HISTORY, encoding='utf-8', errors='replace') as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    r = json.loads(line)
+                    p = r.get('prd')
+                    if p:
+                        last_by_prd[os.path.basename(str(p))] = r
+                except Exception:
+                    continue
+    except Exception:
+        pass
+    return last_by_prd
+
+
+def main():
+    try:
+        data = _read_stdin()
+        # 防递归: 二次进入直接放行
+        if _is_reentry(data):
+            sys.exit(0)
+
+        # 找近 10 分钟产出的 PRD, 检查是否已【通过】门禁
+        recent = _recent_prd_files()
+        if not recent:
+            sys.exit(0)  # 本轮没产 PRD, 放行
+        evald = _evald_prds()
+        last_records = _last_record_by_prd()
+        # 区分两种未过门禁: 从没跑过 eval / 跑了但没过线
+        not_run = [p for p in recent if os.path.basename(p) not in last_records]
+        failed = [p for p in recent
+                  if os.path.basename(p) in last_records
+                  and os.path.basename(p) not in evald]
+        if not not_run and not failed:
+            sys.exit(0)  # 全部通过门禁, 放行
+
+        # 有未过门禁的近期 PRD → 阻断, 给出可操作指引
+        parts = []
+        if not_run:
+            parts.append('未跑评测: ' + ', '.join(os.path.basename(p) for p in not_run[:3]))
+        if failed:
+            details = []
+            for p in failed[:3]:
+                rec = last_records.get(os.path.basename(p), {})
+                s = rec.get('score_pct')
+                details.append('%s (最近 %s)' % (os.path.basename(p),
+                                                 ('%s%%' % s) if s is not None else '未过'))
+            parts.append('评测未过线: ' + ', '.join(details))
+        sys.stderr.write(
+            '【EVA 门禁】检测到近期产出的 PRD 未通过质量门禁 (要求 eval ≥80%%):\n'
+            '  %s\n'
+            '修复: python .qoder/scripts/orchestration/wlkj.py eval <PRD> [原型]\n'
+            '      针对评测报告的扣分项改 PRD, 重跑 eval 到 ≥80%% 再结束。\n'
+            % '; '.join(parts))
+        sys.exit(2)
+    except SystemExit:
+        raise
+    except Exception as e:
+        try:
+            os.makedirs(os.path.dirname(HOOK_ERRORS_LOG), exist_ok=True)
+            with open(HOOK_ERRORS_LOG, 'a', encoding='utf-8') as f:
+                f.write('[{}] stop-eval: {}\n'.format(
+                    datetime.now().strftime('%Y-%m-%d %H:%M:%S'), str(e)[:200]))
+        except Exception:
+            pass
+        sys.exit(0)  # 铁律: hook 崩溃绝不阻塞
+
+
+if __name__ == '__main__':
+    main()

package/templates/qoder/hooks/user-prompt-submit.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""user-prompt-submit.py - UserPromptSubmit hook: /wl-prd-* 必须先问平台 (代码硬墙)
+
+吸收宿主确定性 hook 能力: 把 CRITICAL RULE #1 "先问平台" 从"靠 LLM 自觉"
+升级为"宿主在用户提交时拦截"。AI 想忘都忘不了。
+
+历史教训 (REFACTOR_PROGRESS M4): 旧版 UserPromptSubmit hook 因"激进注入上下文"被删。
+本次只做一件事 —— 命中 /wl-prd-* 且无平台词时 exit 2 阻断, 不注入任何 stdout 文本,
+保持非侵入式。未命中 / 自然语言一律放行 (exit 0)。
+
+阻断契约 (照搬 platform_guard.py, Qoder 镜像 Claude Code hook 体系):
+  - exit 0 = 放行
+  - exit 2 = 阻断, stderr 作为反馈展示给 Agent/用户, 停住等用户答平台
+
+stdin 字段名: 官方未公开, 此处兼容多种可能 (prompt / user_input / message / text),
+首字段命中即用。若都取不到 → 保守放行 (绝不误阻断)。
+"""
+import json
+import os
+import re
+import sys
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+NL = chr(10)
+BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+HOOK_ERRORS_LOG = os.path.join(BASE, '.qoder', '.runtime', 'hook-errors.log')
+
+# 命中 /wl-prd-* 的正则 (full/quick/review 等子命令都覆盖)
+PRD_CMD_RE = re.compile(r'/wl-prd-', re.IGNORECASE)
+# 平台已声明词 (任一出现即视为已问平台, 放行)
+PLATFORM_WORDS = ('web', 'app', 'pc', 'h5', '管理端', '移动端', '两端', 'fywl-ui', 'carmg', '两端都要')
+# 明确"正在问平台"的措辞 (避免 AI 把问平台的话本身当成已选)
+ASKING_PHRASES = ('请选择', '哪个平台', '请选择 (1/2/3)', '选 (1/2/3)')
+
+
+def _read_prompt():
+    """从 stdin 读用户输入文本。兼容多种字段名 + 纯文本兜底。取不到返回 None。"""
+    raw = None
+    try:
+        if not sys.stdin.isatty():
+            raw = sys.stdin.read()
+    except Exception:
+        return None
+    if not raw:
+        return None
+    raw = raw.strip()
+    # 1. 尝试 JSON (宿主喂的结构化输入)
+    try:
+        data = json.loads(raw)
+        if isinstance(data, dict):
+            for key in ('prompt', 'user_input', 'message', 'text', 'content', 'input'):
+                v = data.get(key)
+                if isinstance(v, str) and v.strip():
+                    return v
+            # 嵌套 messages[-1].content 等
+            msgs = data.get('messages')
+            if isinstance(msgs, list) and msgs:
+                last = msgs[-1]
+                if isinstance(last, dict):
+                    c = last.get('content') or last.get('text')
+                    if isinstance(c, str):
+                        return c
+    except (ValueError, TypeError):
+        pass
+    # 2. 纯文本兜底
+    return raw if raw else None
+
+
+def _should_block(prompt_text):
+    """是否阻断: 命中 /wl-prd-* 且无平台词 且 不是在问平台本身。"""
+    if not prompt_text:
+        return False
+    if not PRD_CMD_RE.search(prompt_text):
+        return False
+    low = prompt_text.lower()
+    # AI 正在问平台 (这段 prompt 是 AI 发的提问) → 不拦, 让它继续问
+    if any(p in prompt_text for p in ASKING_PHRASES):
+        return False
+    # 已含平台词 → 放行
+    if any(w.lower() in low for w in PLATFORM_WORDS):
+        return False
+    return True
+
+
+def _record_violation():
+    """best-effort 上报一次 rule_violation (不阻塞拦截本身)。注意避开 learn import 断链。"""
+    try:
+        learn_dir = os.path.join(BASE, '.qoder', 'scripts', 'domain', 'learning')
+        if learn_dir not in sys.path:
+            sys.path.insert(0, learn_dir)
+        # bootstrap foundation 路径
+        foundation_dir = os.path.join(BASE, '.qoder', 'scripts', 'foundation')
+        if foundation_dir not in sys.path:
+            sys.path.insert(0, foundation_dir)
+        from learn import record_feedback  # noqa
+        record_feedback('rule_violation', {
+            'rule': 'ask_platform_first',
+            'skill': 'wl-prd (UserPromptSubmit hook)',
+            'detail': '用户提交 /wl-prd-* 未含平台词, hook 已阻断',
+        })
+    except Exception:
+        pass
+
+
+def main():
+    try:
+        prompt = _read_prompt()
+        if _should_block(prompt):
+            _record_violation()
+            sys.stderr.write(
+                '【平台硬墙】/wl-prd-* 必须先问平台 (Web管理端 / APP移动端 / 两端都要)。\n'
+                '参考 AGENTS.md CRITICAL RULE #1: 先问平台, 不自动判断, 不跳过。\n'
+                '已记录一次规则违规。请先回答平台选择, 再继续。\n')
+            sys.exit(2)  # 阻断
+        sys.exit(0)  # 放行
+    except SystemExit:
+        raise
+    except Exception as e:
+        # 铁律: hook 崩溃绝不阻塞会话 → 保守放行 + 落盘日志
+        try:
+            os.makedirs(os.path.dirname(HOOK_ERRORS_LOG), exist_ok=True)
+            with open(HOOK_ERRORS_LOG, 'a', encoding='utf-8') as f:
+                from datetime import datetime
+                f.write('[{}] user-prompt-submit: {}\n'.format(
+                    datetime.now().strftime('%Y-%m-%d %H:%M:%S'), str(e)[:200]))
+        except Exception:
+            pass
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/templates/qoder/rules/wl-pipeline.md

@@ -34,50 +34,44 @@ test -f .qoder/.developer && echo "已初始化" || echo "未初始化"
 > "写个需求"，但身份没初始化会导致命令静默失败。50 人团队里新成员第一句话
 > 就撞这个的概率很高，必须在规则层兜住。
 
-## 规则 0：自然语言 → 技能 路由表（全端通用）
-
-所有 Qoder 产品（IDE 编辑器 / Quest 模式 / QoderWork 桌面端 / CLI）都支持两种触发方式：
-1. **斜杠命令**：输入 `/wl-prd-full` `/wl-search` 等（commands 和 skills 都可用 `/` 触发）
-2. **自然语言**：直接说"写个需求""查一下代码"，AI 按下表自动映射到对应 skill
-
-> 注意：Quest/QoderWork 里 `/` 会同时列出 commands（如 `/wl-prd-full`）和 skills（如 `/prd-generator`）。
-> 两者功能等价，优先用 `/wl-*` 命令（更稳定，参数提示更全）。
-
-| 用户说什么 | 触发的 skill/command |
-|------------|---------------------|
-| "写个需求""生成PRD""做个原型""新模块""保单这块加个功能" | `/wl-prd-full` 或 prd-generator + prototype-generator |
-| "加个字段""加个导出按钮""改下文案""小改动" | `/wl-prd-quick`（快档，零星需求）|
-| "查一下""代码在哪""搜保险""考勤的API""字段含义" | `/wl-search` 或 wl-search |
-| "建任务""排优先级""这个任务做完了""开始做这个" | `/wl-task` 或 wl-task |
-| "项目怎么样""进度""健康度""路线图" | `/wl-status` 或 wl-status |
-| "写日报""周报""我这周干了啥""今天做了什么" | `/wl-report` 或 wl-report |
-| "调研""竞品""对标""规划""路线图""接下来做什么""发现个机会""探讨需求" | `/wl-insight` 或 wl-insight（探索站：发现/调研/规划）|
-| "生成规格""写spec""技术方案" | `/wl-spec` 或 spec-generator |
-| "开始写代码""按规格实现""实现这个接口" | `/wl-code` 或 spec-coder |
-| "跑测试用例""执行测试任务""回归测试任务" | `/wl-test`（测试工作流）或 wl-test |
-| "写单元测试""补单测""生成test" | `/wl-test unit` 或 test-generator |
-| "评审PRD""PRD质量怎么样""检查需求文档" | `/wl-prd-review`（评审 PRD 质量）|
-| "提交代码""commit""推上去""保存代码" | `/wl-commit` 或 wl-commit |
-| "初始化""换开发者""环境检查""我是谁" | `/wl-init` 或 wl-init |
-| **"出个原型""画个界面""做个 mockup""改个页面"** | **`/wl-design-draw`（画界面）** |
-| **"XX 有哪些页面""XX 操作流程""系统什么风格""改XX影响什么"** | **`/wl-design-scan`（审视现状）** |
-| **"录入设计稿""评审原型""检查原型""Figma 稿""蓝湖稿""蓝湖链接""lanhu"** | **`/wl-design-spec`（设计交付，蓝湖链接优先用 `mcp__lanhu__*` 直读）** |
-| "测试覆盖""哪些功能有测试""哪些没测试""回归盲区" | `/wl-design-scan` 或 MCP `coverage_matrix()` |
-| "这个功能完整吗""XX功能画像" | `/wl-design-scan` 或 MCP `feature_overview(feature='XX')` |
-| "改XX会影响什么""改这个接口影响哪些页面" | `/wl-design-scan` 或 MCP `get_impact(endpoint='XX')` |
-| "XX函数谁调用了""XX的调用链" | MCP `context_360(symbol='XX')` |
-
-> 知识图谱 13 个能力（`kg.py`）**全系列通用**：QoderWork 环境 AI 也可直接调
-> MCP 工具（`mcp__qoder-knowledge-graph__*`），非 MCP 环境跑 kg.py，数据一致。
-> 能力清单见 `/wl-search`。
-
-**找不到明确匹配时：先问用户意图，不要乱跑**（"你是想写 PRD、查代码、还是建任务？"）。
+## 规则 0：触发方式（非侵入式 — v3.0 改造）
+
+工作流**只在显式调用时启动**，不主动干预用户的普通对话。
+
+**两种触发方式（且仅此两种）：**
+1. **斜杠命令**：输入 `/wl-prd-full` `/wl-search` `/wl-req` 等 → 启动工作流
+2. **npx**：`npx @hupan56/wlkj init/update` → 启动安装/同步
+
+**自然语言不触发工作流。** 用户说"写个需求""查下代码"等，AI 正常回答，不自动拉入工作流。
+（工作流启动后的过程内交互 — 如选平台、确认需求 — 仍可用自然语言。）
+
+> Quest/QoderWork 里 `/` 会列出 commands 和 skills，优先用 `/wl-*` 命令。
+> 命令一览见本文档底部"用户侧命令一览"。
+
+> 知识图谱能力（`kg.py`）全系列通用：QoderWork 用 MCP，非 MCP 跑 kg.py。
+
 注意：用户说"同步/保存产出"通常指 team_sync（push），不是 git commit；
 用户说"提交/commit 代码"才是 wl-commit。
 
-**🧩 提问润色（可选增强，纯 Qoder IDE/CLI 用，QoderWork 有 MCP 不需要）**：
-非 MCP 环境下，用户输入含业务词时，可先跑 `python .qoder/scripts/enrich_prompt.py "<用户输入>"`
-做 <10ms 的极速关键词扩展，让用户确认后再走实际命令。MCP 环境下跳过（AI 直接调 MCP 工具已含扩展）。
+## 规则 0.5：数据库查询必须先问环境（安全红线，问了就停）
+
+AI 检测到需要查询**真实数据库**（调用 `mcp__qoder-mysql` 的 query_schema / query_data /
+query_distinct / list_databases / list_tables 等）时，**绝不能直接发查询**，必须：
+
+1. **先调 `mcp__qoder-mysql__list_envs()`** 取环境列表；
+2. **把可选环境列给用户，问"要查哪个环境"**，然后**停下等用户选**；
+3. 用户选定后，后续查询都带 `env=<用户选的标签>`。
+
+环境由 `.qoder/config.yaml` 的 `mysql.environments` 定义，标签可自定义
+（test/pre/prod 或 qa/staging…）。**禁止自行假定环境**，即便用户没明说，
+也要先问——这是为了杜绝误连生产库。
+
+查询结果自带环境声明（由 MCP 注入）：
+- 测试环境 → 数据是样本，不代表线上分布
+- 生产环境 → 🔴 真实数据，仅供核对字段含义/格式，**禁止作为业务结论外传**
+
+> 同一轮对话里用户已选过环境、追问同一库，可不再重复问。
+> 默认环境见 `mysql.default_env`（通常 test），但"首次仍问"是硬约束。
 
 ## 规则 1：PRD/原型需求必须先问平台（问了就停，不许边问边干）
 
@@ -99,8 +93,8 @@ test -f .qoder/.developer && echo "已初始化" || echo "未初始化"
 ## 规则 2：查代码索引优先，索引找不到才准 grep（又快又准的取数顺序）
 
 ```bash
-python .qoder/scripts/kg.py context <业务关键词> --platform <web|app> [--role pm|design|dev|test]  # 一次取全(首选, 秒级)
-python .qoder/scripts/search_index.py <关键词> --platform <web|app>      # 单项搜索
+python .qoder/scripts/orchestration/wlkj.py kg context <业务关键词> --platform <web|app> [--role pm|design|dev|test]  # 一次取全(首选, 秒级)
+python .qoder/scripts/orchestration/wlkj.py search <关键词> --platform <web|app>      # 单项搜索
 ```
 kg.py context（= context_pack）一条命令返回：相关代码文件 + 同类页面示例 + 字段规格 +
 相关 PRD + 设计 Token + 图标参考 + 模板路径。kg.py 还有 12 个兄弟能力
@@ -109,9 +103,34 @@ kg.py context（= context_pack）一条命令返回：相关代码文件 + 同
 **取数顺序（强制，违反 = 慢 + 凭空写 PRD）：**
 1. **先用索引**：任何 /wl-* 命令查代码，**第一步永远是 kg.py context**（查预建图谱，秒级，不碰文件系统）。绝大多数需求一次就够。
 2. **索引够用就停**：context 列出了相关文件/字段/API → 只用 Read 读那 1-2 个 .vue，**不要再用 Grep/Glob 去文件系统扫**。
-3. **索引真找不到才 grep 兜底**：只有当 kg.py/search_index 明确返回"无匹配"或缺了某个具体点时，才回退到 Grep/Glob 直搜 —— 且**只搜 context 指向的范围**，不准对 data/code/（8973+ 文件）或整个 qoderAll 仓全库扫。
+3. **中文文案/报错溯源用 grep-text**：用户查的是中文短语（报错文案"车辆不存在"、字段标签"项目车号"、业务词），kg.py 的代码标识符索引天然查不到。**这时只能用 `kg.py grep-text <中文短语>`**（单进程 Python，限定 data/code，限定扩展名，秒回，不弹窗）。
+4. **🚫 硬性禁令（违反 = QoderWork 卡死 + 疯狂弹 cmd 窗口）**：
+   - **禁止**用 `findstr /s`、`grep -r`、`rg` 递归扫整个 data/code（8973+ 文件）或 qoderAll 仓
+   - **禁止**用 `os.walk` / `os.system` / `subprocess` 全盘递归搜文件
+   - **禁止**在 Bash 里手写 Python `-c "import os; for ... os.walk(...)"` 全库遍历
+   - 兜底搜索**唯一合法方式** = `kg.py grep-text`（已内置单进程、范围限定、命中上限）
+   - Grep/Glob 工具**只准搜 context/grep-text 已定位到的具体文件或单一小目录**，不准全库扫
+
+**为什么这条是红线**：QoderWork 自带 Agent 默认会用 Grep/Glob 直搜文件系统，它不懂"业务源码在 data/code/ 镜像里"，会搜整个 qoderAll 仓然后报"无匹配"，被迫凭空编字段/API。更糟的是 AI 兜底去跑 `findstr /s` 全盘扫描 → Windows 对 8973 文件递归 = 卡死 + 疯狂弹子进程窗口，用户只能强杀。**Agent 只准用来**：①读 context 列出的具体文件（Read）②**在 /wl-insight 里**做 web 调研（对标/竞品）和多视角探索脑暴。**绝不用 Agent 去"发现/搜索"代码——那是 kg.py 的活。** 注意：探索类 Agent 调研已集中到 `/wl-insight`，`/wl-prd-full` 不再派 Agent 做 web 搜索/脑暴。
 
-**为什么这条是红线**：QoderWork 自带 Agent 默认会用 Grep/Glob 直搜文件系统，它不懂"业务源码在 data/code/ 镜像里"，会搜整个 qoderAll 仓然后报"无匹配"，被迫凭空编字段/API。**Agent 只准用来**：①读 context 列出的具体文件（Read）②**在 /wl-insight 里**做 web 调研（对标/竞品）和多视角探索脑暴。**绝不用 Agent 去"发现/搜索"代码——那是 kg.py 的活。** 注意：探索类 Agent 调研已集中到 `/wl-insight`，`/wl-prd-full` 不再派 Agent 做 web 搜索/脑暴。
+## 规则 2.5：工具调用能并发就并发（性能命门，串行 = 慢）
+
+**串行执行是工作流慢的最大元凶。** 每次工具调用都要等返回（图谱查询 2-3 秒、读文件 1 秒、
+命令行 3-5 秒），10 个串行步骤 = 白等 30-50 秒。MCP 工具调用**支持同一回合并发**，必须利用：
+
+**并发规则（全 /wl-* 命令强制）：**
+1. **多个独立的 search/Read → 同一 assistant 回合一起发**，不要"发一个、等返回、再发下个"。
+   确定要读 3 个文件后，一个回合同时发 3 个 Read。
+2. **多个独立搜索可并发**：要搜 `OSS` + `upload` 两个关键词，一次发 2 个 search_code。
+3. **只有"后步依赖前步结果"才串行**：先 search 拿路径才能 Read（必须串行）；但路径已知后，
+   多个 Read 必须**并发**。
+4. **一轮思考塞满**：能同回合发的工具调用全发出去，等它们一起回来，别"一回合一个"。
+
+**反例（禁止）**：search A → 等 → Read X → 等 → search B → 等 → Read Y → 等 ...
+**正例（正确）**：[search A + search B] 并发 → 等 → [Read X + Read Y + Read Z] 并发 → 答
+
+> 这是工作流比原生慢的根因——原生 AI 本能地并发，工作流却被"逐步执行"的文档节奏带成了串行。
+> 把串行变并发，同样工作量耗时可砍到 1/3。MCP server（kg/mysql/zentao）都支持 JSON-RPC 并发请求。
 
 ## 规则 3：原型风格必须来自真源（含图标）
 
@@ -154,19 +173,19 @@ PM /wl-prd-full → AI 出初稿 PRD + 原型
 ## 规则 4：PRD 必须套团队模板 + 过 EVA 门禁
 
 - 完整需求用 .qoder/templates/prd-full-template.md，零星需求用 prd-quick-template.md
-- 发布前：`python .qoder/scripts/eval_prd.py <prd> [原型]` 必须 PASS (≥80%)
+- 发布前：`python .qoder/scripts/orchestration/wlkj.py eval <prd> [原型]` 必须 PASS (≥80%)
 - 发现确认采用批量方式（一个编号列表一轮确认），不要逐条问
 
 ## 规则 5：用户永不接触 git
 
-- 产出保存/发布后自动执行 `python .qoder/scripts/team_sync.py push`
-- 拉取团队最新：`python .qoder/scripts/team_sync.py pull`
+- 产出保存/发布后自动执行 `python .qoder/scripts/orchestration/wlkj.py sync push`
+- 拉取团队最新：`python .qoder/scripts/orchestration/wlkj.py sync pull`
 - 出现 SYNC_CONFLICT 由 AI 按提示自行解决，绝不让用户跑 git 命令
 
 ## 规则 6：环境问题找 doctor
 
 任何"索引不对/搜不到/环境坏了"类问题：
-`python .qoder/scripts/init_doctor.py`（加 --fix 自动修复，幂等增量，不会重头构建）
+`python .qoder/scripts/orchestration/wlkj.py doctor`（加 --fix 自动修复，幂等增量，不会重头构建）
 
 ## 规则 7：Repo Wiki 是补充知识源
 
@@ -214,3 +233,20 @@ PM /wl-prd-full → AI 出初稿 PRD + 原型
 > 环境/域名在 config.yaml `autotest:` 配，`--url` 可临时覆盖。
 
 用户用自然语言表达即可，AI 负责映射到命令和脚本。
+
+---
+
+## 工作流可用性自检（吸收宿主能力：会话上下文注入）
+
+会话开头 `<qoder-context>` 里的 **Workflow Usability** 段是宿主 SessionStart hook
+自动注入的"近7天红灯"（一次过审率/规则违反率不达标）。**见到红灯时遵守：**
+
+1. **红灯 = 工作流某环节没跑起来**，不是忽略它继续干活。
+2. 一次过审率低（<60%）：写 PRD 前先读 `data/learning/patterns/prd-patterns.md` 避坑。
+3. 规则违反率高（>10%）：`/wl-prd-*` 启动**必须先问平台**（铁律1），不问就是新增违规。
+4. 想看全貌：`python .qoder/scripts/orchestration/wlkj.py usability` 或 `/wl-status health`（健康分含 adoption 维度）。
+5. 指标定义/公式/阈值：`data/docs/constitution/workflow-usability-metrics.md`。
+
+> 这套指标评"工作流用没用起来"，与 EVA（评 PRD 质量）分工不同——EVA 卡发布门禁，
+> 可用性指标卡"工具该不该继续投入"。
+

package/templates/qoder/scripts/README.md

@@ -0,0 +1,102 @@
+# .qoder/scripts/ — 引擎脚本目录 (分层架构)
+
+> 引擎代码, 由 `npx @hupan56/wlkj init/update` 生成, **不进团队 git** (Trellis 化)。
+> 用户不直接碰这些文件 — 通过 `/命令` 和 `npx` 间接调用。
+
+## 🏗️ 分层架构 (7 层)
+
+子目录化 (v3.0) 后, 脚本按职责分层, 顶层**无散落 .py**, 只有 7 个分层目录:
+
+```
+scripts/
+├── orchestration/   编排层 — wlkj.py 统一入口 (载体收敛点)
+├── foundation/      基础层 — 共享库 (被所有层 import)
+├── domain/          领域层 — 业务逻辑 (kg/task/report/...)
+├── protocol/        协议层 — MCP server / 传输适配
+├── capability/      能力层 — 链式能力编排 / 冒烟测试
+├── validation/      验证层 — 测试 / 评测 / 基准
+└── deployment/      部署层 — 安装 / 体检 / 载体同步
+```
+
+## 🚪 统一入口: `orchestration/wlkj.py` (Facade)
+
+**所有 Qoder 载体 (commands/skills/rules) 的脚本调用都走这个入口**, 由 DISPATCH 表路由到
+分层路径。这样 scripts/ 重组目录时只改 DISPATCH 一处, 载体不受影响。
+
+```bash
+python .qoder/scripts/orchestration/wlkj.py <命令> [参数...]
+# 例: wlkj.py kg search 保险 | wlkj.py task list | wlkj.py doctor --fix
+```
+
+完整命令表见 `wlkj.py` 的 DISPATCH (kg/search/context/task/sync/req/eval/learn/status/report/test/doctor 等 36 条)。
+脚本内部互调 (Python 进程间) 直接用分层路径, 不绕 wlkj (避免 subprocess 嵌套)。
+
+## 各层职责 + 关键脚本
+
+### 🎼 orchestration/ — 编排
+| 脚本 | 用途 |
+|------|------|
+| `wlkj.py` | **统一调度入口**, DISPATCH 透明转发到各层脚本 |
+
+### 🧱 foundation/ — 基础 (共享库, 不含业务)
+| 模块 | 用途 |
+|------|------|
+| `bootstrap.py` | sys.path 自举 (子目录化后定位 scripts/ 根) |
+| `core/paths.py` | **路径管理** (PROJECT_ROOT / get_repo_root / get_developer) |
+| `identity/` | 身份 (identity.py / developer.py / roles.py 角色章节) |
+| `io/` | 原子 IO (atomicio.py) / 文件锁 (filelock.py) |
+| `protocol/mcp_base.py` | MCP server 基类 (@tool 装饰器 + 元类注册) |
+| `integrations/` | 术语扩展 (terms.py) / 禅道客户端 (zentao_client.py, 单一真源) |
+| `utils/eval_api.py` | 评测 API |
+
+### 🎯 domain/ — 领域 (业务逻辑)
+| 子包 | 关键脚本 | 用途 |
+|------|---------|------|
+| `kg/` | `kg.py` (**图谱统一入口**, 13+ 能力) | 知识图谱 |
+| `kg/search/` | search_index.py / context_pack.py / prefetch.py | 代码搜索 / 一键上下文 |
+| `kg/build/` | kg_build.py / kg_build_db.py / kg_incremental.py / build_style_index.py | 图谱构建 |
+| `kg/graph/` | kg_semantic.py / kg_link_db.py | 语义 / 数据库图谱链接 |
+| `kg/storage/` | kg_duckdb.py | DuckDB 存储层 |
+| `kg/server/` | kgd.py (常驻服务) / perf_bench.py | 语义加速服务 |
+| `task/` | task.py (**任务系统**) / team_sync.py / git_sync.py / zentao_sync.py / syncgate.py | 任务 + 同步 |
+| `requirement/` | req.py / archive_prd.py | 需求生命周期 |
+| `report/` | report.py / status.py / role.py / export.py / *_snapshot.py | 报告 / 状态 |
+| `design/` | fill_prototype.py / gen_design_doc.py | 原型填充 / 设计文档 |
+| `learning/` | learn.py | 学习飞轮 (埋点) |
+
+### 🔌 protocol/ — 协议
+| 子包 | 脚本 | 用途 |
+|------|------|------|
+| `mcp/` | mcp_launcher.py (**统一启动器**) / kg_mcp_server.py / mysql_mcp_server.py / zentao_mcp_server.py / lanhu_stdio_wrapper.py / mcp_doctor.py | 4 个自有 MCP server |
+| `transports/` | cli.py | CLI 传输适配 |
+
+### 🧩 capability/ — 能力编排
+| 脚本 | 用途 |
+|------|------|
+| `chain.py` / `memory_chain.py` | 链式能力编排 |
+| `adapters/` (cli.py / qw.py / mcp.py) | 能力适配器 (CLI/QoderWork/MCP) |
+
+### 🧪 validation/ — 验证
+| 子包 | 关键脚本 | 用途 |
+|------|---------|------|
+| `test/` | autotest.py / smoke_all_commands.py / benchmark.py / kg_test_runner.py | 自动测试 / 冒烟 / 基准 |
+| `metrics/` | eval_prd.py / usability_score.py | **PRD 质量门禁** (EVA, ≥80%) + **工作流可用性** (采纳+流程) |
+| `eval/` | 性能评测报告 | |
+
+### 🚀 deployment/ — 部署
+| 脚本 | 用途 |
+|------|------|
+| `setup.py` | **一键就绪** (npx init 调的主体) |
+| `init_doctor.py` | 环境体检 + 自愈 + 身份注册 |
+| `install_qoderwork.py` | QoderWork 技能/MCP 安装 |
+| `carriers.py` | **载体一致性** (check/check-paths/sync/all, 4 载体对齐) |
+| `repo_root.py` | 仓库根探测 (QoderWork 桌面端用) |
+| `setup_lanhu.py` / `platform_doctor.py` | 蓝湖配置 / 平台体检 |
+
+## 设计原则
+
+1. **分层即分类**: 物理目录 = 职责分层 (foundation/domain/protocol/...), 取代旧的命名前缀
+2. **单一入口**: `orchestration/wlkj.py` 是载体层唯一收敛点; `domain/kg/kg.py` 是图谱入口; `domain/task/task.py` 是任务入口
+3. **foundation/ 共享**: 通用逻辑抽到 foundation/, 领域无关 (路径/身份/IO/协议基类)
+4. **载体与引擎解耦**: 载体 (commands/skills) 只认 wlkj.py 一个路径, 引擎目录重组不波及载体
+5. **降级不崩**: 缺依赖/缺数据时优雅降级, 绝不 sys.exit 崩溃 (见 protocol/mcp/mcp_launcher.py)

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

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+"""
+nexus —— 宿主能力抽象层（Capability Nexus）。
+
+工作流不问宿主是谁，只问它有什么能力。
+QoderWork / ZCode / Codex / ClaudeCode 有 memory / cron / mcp 就用，
+没有就静默回退（Null Object），绝不报错。
+
+主轴: 能力契约（Capability Protocol）+ MCP 优先 + 职责链（Provider Chain）
+
+用法:
+    from capability import resolve
+    cap = resolve()
+    cap.mcp.call("list_executions", {...})   # L1 已有 MCP（禅道/知识图谱...）
+    cap.memory.remember("本周", "73/74/75")   # L2 职责链（MCP→QW→文件→NoOp）
+
+诊断:
+    python .qoder/scripts/capability               # 打印当前宿主 + 各能力状态
+
+设计文档: .qoder/data/docs/architecture/nexus-capability-layer.md
+"""
+from .registry import resolve, detect_host, Nexus, HOST_TABLE
+
+__all__ = ["resolve", "detect_host", "Nexus", "HOST_TABLE"]
+
+__version__ = "0.1.0"