@hupan56/wlkj 3.0.0 → 3.1.2

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

@@ -53,6 +53,26 @@ test -f .qoder/.developer && echo "已初始化" || echo "未初始化"
 注意：用户说"同步/保存产出"通常指 team_sync（push），不是 git commit；
 用户说"提交/commit 代码"才是 wl-commit。
 
+## 规则 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/原型需求必须先问平台（问了就停，不许边问边干）
 
 用户提出 PRD、原型、需求分析类请求时，第一步永远是问（绝不自动判断）：
@@ -73,8 +93,8 @@ test -f .qoder/.developer && echo "已初始化" || echo "未初始化"
 ## 规则 2：查代码索引优先，索引找不到才准 grep（又快又准的取数顺序）
 
 ```bash
-python .qoder/scripts/kg/kg.py context <业务关键词> --platform <web|app> [--role pm|design|dev|test]  # 一次取全(首选, 秒级)
-python .qoder/scripts/kg/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 个兄弟能力
@@ -83,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 搜索/脑暴。
+
+## 规则 2.5：工具调用能并发就并发（性能命门，串行 = 慢）
+
+**串行执行是工作流慢的最大元凶。** 每次工具调用都要等返回（图谱查询 2-3 秒、读文件 1 秒、
+命令行 3-5 秒），10 个串行步骤 = 白等 30-50 秒。MCP 工具调用**支持同一回合并发**，必须利用：
 
-**为什么这条是红线**：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 搜索/脑暴。
+**并发规则（全 /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：原型风格必须来自真源（含图标）
 
@@ -128,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/report/eval_prd.py <prd> [原型]` 必须 PASS (≥80%)
+- 发布前：`python .qoder/scripts/orchestration/wlkj.py eval <prd> [原型]` 必须 PASS (≥80%)
 - 发现确认采用批量方式（一个编号列表一轮确认），不要逐条问
 
 ## 规则 5：用户永不接触 git
 
-- 产出保存/发布后自动执行 `python .qoder/scripts/task/team_sync.py push`
-- 拉取团队最新：`python .qoder/scripts/task/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/setup/init_doctor.py`（加 --fix 自动修复，幂等增量，不会重头构建）
+`python .qoder/scripts/orchestration/wlkj.py doctor`（加 --fix 自动修复，幂等增量，不会重头构建）
 
 ## 规则 7：Repo Wiki 是补充知识源
 
@@ -188,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

@@ -1,139 +1,102 @@
-# .qoder/scripts/ — 引擎脚本目录
+# .qoder/scripts/ — 引擎脚本目录 (分层架构)
 
 > 引擎代码, 由 `npx @hupan56/wlkj init/update` 生成, **不进团队 git** (Trellis 化)。
-> 用户不需要直接碰这些文件 — 通过 `/命令` 和 `npx` 间接调用。
+> 用户不直接碰这些文件 — 通过 `/命令` 和 `npx` 间接调用。
 
-## 按职责分类 (命名前缀即分类)
+## 🏗️ 分层架构 (7 层)
 
-### 🔍 知识图谱 (`kg_*`, 9 个) — 代码/数据库图谱
-| 脚本 | 用途 |
-|------|------|
-| `kg.py` | **统一入口** (search/api/impact/feature), AI 和 /wl-search 都走这里 |
-| `kg_build_db.py` | 全量构建图谱 (管理员, 周五 cron) |
-| `kg_incremental.py` | 增量更新 (只处理 git diff 变更文件) |
-| `kg_duckdb.py` | DuckDB 存储层 (实体/边/工作流) |
-| `kg_mcp_server.py` | KG MCP server (QoderWork 连接) |
-| `kg_build.py` | 构建编排 |
-| `kg_link_db.py` | 数据库图谱链接 |
-| `kg_semantic.py` | 语义分析 |
-| `kg_auto_login.py` | 自动登录 |
-| `kg_test_runner.py` | 图谱测试 |
-
-### 🏗️ 索引构建 (`build_*`, 4 个)
-| 脚本 | 用途 |
-|------|------|
-| `build_style_index.py` | UI 风格索引 (表格/表单/字段映射) |
-| `build_entity_registry.py` | 实体注册 (功能+端点) |
-| `build_relations.py` | 关系边 (click→api, api→controller) |
-| `build_workflows.py` | 业务流程索引 |
+子目录化 (v3.0) 后, 脚本按职责分层, 顶层**无散落 .py**, 只有 7 个分层目录:
 
-### 🩺 诊断检查 (`check_*`, 4 个)
-| 脚本 | 用途 |
-|------|------|
-| `check_mcp.py` | MCP 配置检查 |
-| `check_mcp_launch.py` | MCP 启动诊断 (根治黄色) |
-| `check_carriers.py` | 规则载体检查 (Qoder 全系列兼容) |
-| `check_qoderwork_consistency.py` | QoderWork 一致性 |
+```
+scripts/
+├── orchestration/   编排层 — wlkj.py 统一入口 (载体收敛点)
+├── foundation/      基础层 — 共享库 (被所有层 import)
+├── domain/          领域层 — 业务逻辑 (kg/task/report/...)
+├── protocol/        协议层 — MCP server / 传输适配
+├── capability/      能力层 — 链式能力编排 / 冒烟测试
+├── validation/      验证层 — 测试 / 评测 / 基准
+└── deployment/      部署层 — 安装 / 体检 / 载体同步
+```
 
-### 🔎 代码提取 (`extract_*`, 3 个)
-| 脚本 | 用途 |
-|------|------|
-| `extract_routes.py` | 路由提取 |
-| `extract_routes_tree.py` | 路由树 |
-| `extract_api_params.py` | API 参数提取 |
+## 🚪 统一入口: `orchestration/wlkj.py` (Facade)
 
-### 🧪 测试 (`autotest_*`, 3 个)
-| 脚本 | 用途 |
-|------|------|
-| `autotest.py` | 自动测试入口 |
-| `autotest_batch.py` | 批量测试 |
-| `autotest_run.py` | 单次执行 |
+**所有 Qoder 载体 (commands/skills/rules) 的脚本调用都走这个入口**, 由 DISPATCH 表路由到
+分层路径。这样 scripts/ 重组目录时只改 DISPATCH 一处, 载体不受影响。
 
-### 🚀 初始化与身份 (`init_*`/`setup`/`role`/`identity`)
-| 脚本 | 用途 |
-|------|------|
-| `setup.py` | **一键就绪** (npx init 调的主体) |
-| `init_doctor.py` | 环境体检 + 自愈 + 身份注册 |
-| `install_qoderwork.py` | QoderWork 技能/MCP 安装 |
-| `role.py` | 角色管理 |
-| `repo_root.py` | 仓库根探测 |
+```bash
+python .qoder/scripts/orchestration/wlkj.py <命令> [参数...]
+# 例: wlkj.py kg search 保险 | wlkj.py task list | wlkj.py doctor --fix
+```
 
-### 🔄 同步与任务
-| 脚本 | 用途 |
-|------|------|
-| `team_sync.py` | **团队同步** (pull/push, /wl-task finish 调) |
-| `git_sync.py` | 源码仓库同步 + PRD 归档 |
-| `task.py` | **任务系统** (create/list/start/finish) |
-| `syncgate.py` | 提交前零信任门禁 |
-| `sync_carriers.py` | 规则载体同步 |
+完整命令表见 `wlkj.py` 的 DISPATCH (kg/search/context/task/sync/req/eval/learn/status/report/test/doctor 等 36 条)。
+脚本内部互调 (Python 进程间) 直接用分层路径, 不绕 wlkj (避免 subprocess 嵌套)。
 
-### 📊 评测与报告
-| 脚本 | 用途 |
-|------|------|
-| `eval_prd.py` | **PRD 质量门禁** (EVA, >=80% 才发布) |
-| `report.py` | 日报/周报生成 |
-| `status.py` | 项目状态 |
-| `benchmark.py` | 性能基准 |
+## 各层职责 + 关键脚本
 
-### 🔧 上下文与搜索
+### 🎼 orchestration/ — 编排
 | 脚本 | 用途 |
 |------|------|
-| `search_index.py` | **代码搜索** (/wl-search) |
-| `context_pack.py` | **一键上下文** (/wl-code, /wl-prd 用) |
-| `enrich_prompt.py` | prompt 增强 |
-| `fill_prototype.py` | 原型填充 |
+| `wlkj.py` | **统一调度入口**, DISPATCH 透明转发到各层脚本 |
 
-### 🎨 设计与原型
-| 脚本 | 用途 |
+### 🧱 foundation/ — 基础 (共享库, 不含业务)
+| 模块 | 用途 |
 |------|------|
-| `gen_design_doc.py` | 设计文档生成 |
-| `setup_lanhu.py` | 蓝湖配置 |
-| `lanhu_stdio_wrapper.py` | 蓝湖 MCP wrapper |
-
-### 🔌 MCP 服务 (`*_mcp_server.py`, 4 个)
+| `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/ — 能力编排
 | 脚本 | 用途 |
 |------|------|
-| `mcp_launcher.py` | **MCP 统一启动器** (根治黄色) |
-| `kg_mcp_server.py` | 知识图谱 MCP |
-| `mysql_mcp_server.py` | MySQL MCP (只读) |
-| `zentao_mcp_server.py` | 禅道 MCP |
+| `chain.py` / `memory_chain.py` | 链式能力编排 |
+| `adapters/` (cli.py / qw.py / mcp.py) | 能力适配器 (CLI/QoderWork/MCP) |
 
-### 📚 学习与知识沉淀
-| 脚本 | 用途 |
-|------|------|
-| `learn.py` | **learning 引擎** (埋点/反馈) |
-| `learn_aggregate.py` | 学习聚合 |
+### 🧪 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/ — 部署
 | 脚本 | 用途 |
 |------|------|
-| `page_probe.py` | 页面探测 (浏览器测试) |
-| `platform_doctor.py` | 平台体检 |
-| `archive_prd.py` | PRD 归档 |
-| `export.py` | 导出 |
-| `add_session.py` | 会话管理 |
-
-### 📦 `common/` — 共享库 (被上述脚本 import)
-| 模块 | 用途 |
-|------|------|
-| `paths.py` | **路径管理** (PROJECT_ROOT 探测, cwd 优先) |
-| `developer.py` / `identity.py` | 身份 |
-| `filelock.py` | 文件锁 (防并发) |
-| `atomicio.py` | 原子 IO (防损坏) |
-| `search_engine.py` | 搜索引擎 |
-| `graph_traverse.py` | 图谱遍历 |
-| `eval_api.py` | 评测 API |
-| `terms.py` | 术语扩展 |
-| `feishu.py` | 飞书通知 |
-| `pip_install.py` | pip 镜像兜底 |
-| `platform_guard.py` | 平台守卫 |
-| `repowiki.py` | 仓库 Wiki |
-| `utf8.py` | UTF-8 工具 |
+| `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. **命名即分类**: `kg_*` / `build_*` / `check_*` / `extract_*` / `autotest_*` 前缀 = 隐式分组
-2. **统一入口**: `kg.py` 是图谱统一入口, `task.py` 是任务统一入口 (不是 60 个并列入口)
-3. **common/ 共享**: 通用逻辑抽到 common/, 不重复
-4. **幂等**: 所有脚本可重复跑, 不重头再来 (见 init_doctor 的增量保证)
-5. **降级不崩**: 缺依赖/缺数据时优雅降级, 绝不 sys.exit 崩溃 (见 mcp_launcher)
+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"

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+nexus CLI 入口 —— 诊断当前宿主能力。
+
+用法:
+    python .qoder/scripts/capability               # 打印宿主 + 各能力 available
+    python -m nexus                           # 等价（需 scripts 在 sys.path）
+
+输出 JSON，便于人或脚本消费。
+"""
+import json
+import os
+import sys
+
+
+def _ensure_scripts_on_path():
+    """确保父目录 scripts/ 在 sys.path，使 nexus 包可被 import。"""
+    here = os.path.dirname(os.path.abspath(__file__))
+    scripts_dir = os.path.dirname(here)
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+
+
+def main() -> int:
+    _ensure_scripts_on_path()
+    from capability.registry import resolve
+
+    cap = resolve()
+    desc = cap.describe()
+
+    # MCP server 详情
+    mcp_desc = cap.mcp.describe() if hasattr(cap.mcp, "describe") else {}
+
+    # memory 职责链详情
+    memory_chain = []
+    if hasattr(cap.memory, "providers_status"):
+        memory_chain = cap.memory.providers_status()
+        desc["memory_chain"] = memory_chain
+
+    # 格式化输出
+    print("宿主: %s" % desc.get("host", "?"))
+    print()
+    print("能力:")
+    for name, avail in desc.get("capabilities", {}).items():
+        icon = "✅" if avail else "❌"
+        print("  %s %s" % (icon, name))
+
+    if mcp_desc.get("servers"):
+        print()
+        print("MCP servers (tools=%d):" % mcp_desc.get("total_tools", 0))
+        for name, info in mcp_desc["servers"].items():
+            icon = "✅" if info.get("available") else "❌"
+            pid = " pid=%s" % info["spawn_pid"] if info.get("spawn_pid") else ""
+            latency = " latency=%sms" % info["latency_ms"] if info.get("latency_ms") is not None else ""
+            print("  %s %s: tools=%d%s%s" % (
+                icon, name, info.get("tools_indexed", 0), latency, pid))
+
+    if memory_chain:
+        print()
+        print("Memory 职责链:")
+        for p in memory_chain:
+            hit = " ← ACTIVE" if p.get("hit") else ""
+            print("  %s: available=%s%s" % (p["provider"], p["available"], hit))
+
+    print()
+    print(json.dumps(desc, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""
+nexus.adapters —— 各宿主/降级路径的 Cap 实现。
+
+设计模式: Adapter + Bridge（Cap 抽象 × 宿主实现 正交）
+
+新增宿主（扩展场景 D）= 新建一个文件（如 devin.py）实现其提供的 Cap，
+                         在 registry 的 _resolve_xxx 里按宿主名装配。
+                         核心 Facade、工作流代码零改动。
+
+文件:
+    mcp.py  —— L1 MCP 统一入口（复用禅道/知识图谱等已有 MCP）+ McpMemoryProvider（未来）
+    qw.py   —— QoderWork 原生能力
+    cli.py  —— 纯文件降级（核心能力兜底，无宿主依赖）
+"""
+from .mcp import McpCap, McpMemoryProvider
+from .qw import QwMemoryCap, is_qoderwork
+from .cli import (
+    FileRepoCap,
+    FileIdentityCap,
+    FileContextCap,
+    FileMemoryCap,
+)
+
+__all__ = [
+    "McpCap", "McpMemoryProvider",
+    "QwMemoryCap", "is_qoderwork",
+    "FileRepoCap", "FileIdentityCap", "FileContextCap", "FileMemoryCap",
+]