@hupan56/wlkj 3.1.32 → 3.3.0

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

@@ -1,6 +1,6 @@
 ---
 name: wl-task
-description: "任务管理 + RICE 优先级 + 依赖排期。7 站流水线的'任务'站，产品在这里把 PRD 落成任务。Task management with RICE prioritization. "
+description: "任务管理 + 禅道同步。把 PRD 落成任务、看我的活、改状态、记工时(本地+禅道双写)。动作词: 建任务/我的任务/开始/完成/归档。自然语言问'我的Bug''看#301'直连禅道回答。"
 argument-hint: "[动作] [任务名或ID]  动作: create/list/show/start/finish/archive/rank/plan"
 auto-approve: true
 allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
@@ -147,7 +147,7 @@ python -c "import sys; sys.path.insert(0,r'$R/.qoder/scripts'); from foundation.
 
 **A. PRD 衔接（准的保障：不丢字段）**
 
-如果刚跑完 `/wl-prd-full`（或用户说"把刚才那个需求建成任务"），先确认 PRD 在哪：
+如果刚跑完 `/wl-prd`（或用户说"把刚才那个需求建成任务"），先确认 PRD 在哪：
 ```bash
 # 找最近的 PRD 草稿（当前开发者的）
 ls workspace/members/<developer>/drafts/REQ-*.md 2>/dev/null
@@ -550,7 +550,7 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" task remove-subtask <A任务名> <
 
 ## 🔒 三道质量检查（create 时全跑，其它动作跳过）
 
-对齐 `/wl-prd-full` 的质量锁理念，保证任务不"飘"：
+对齐 `/wl-prd` 的质量锁理念，保证任务不"飘"：
 
 | 检查 | 查什么 | 不过怎么办 |
 |------|--------|-----------|

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

@@ -1,7 +1,7 @@
 ---
 name: wl-test
-description: "测试工作流: 意图式用例 + Playwright MCP 执行 + 锚点缓存。"
-argument-hint: "[quick|browser|unit] <描述或任务>"
+description: "测试: quick(意图式用例,默认) / browser(Playwright浏览器) / unit(单元) / coverage(测试覆盖矩阵)。"
+argument-hint: "[quick|browser|unit|coverage] <描述或任务>"
 auto-approve: false
 allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
 ---
@@ -91,6 +91,10 @@ $PY "$R/.qoder/scripts/orchestration/wlkj.py" test quick \
 $PY "$R/.qoder/scripts/orchestration/wlkj.py" test quick --record '{"Q-1":"pass","Q-2":"fail"}'
 ```
 
+### 下一步
+- 用例全过 → `/wl-commit <[#REQ-xxx] message>` 提交回流（双通飞轮：quick 测 → commit 回流 → `/wl-task finish <REQ-ID>` 收尾）
+- 有失败 → 列原因，修复后重跑 quick，再 commit
+
 ---
 
 ## browser 基于任务的浏览器测试（需先有任务）
@@ -124,6 +128,17 @@ python -c "import json; d=json.load(open('$R/data/index/test-pages.json')); prin
 输出：哪些功能/页面有测试用例（test-pages.json + test-assertions.json），哪些是空白。
 AI 据此建议"优先补 XX 功能的测试"。
 
+### 改动驱动的必跑测试（提交前门禁 · S4 覆盖推理）
+
+改完代码要确定"必跑哪些测试"时，用覆盖推理四件套（已注册 MCP）：
+```python
+cap.mcp.call("impact_coverage", {"entity_ids": ["<改动实体id1>", "<id2>"]})  # 改动集→必跑测试
+cap.mcp.call("find_tests_of", {"entity_id": "<某实体id>"})          # 查某实体的测试
+cap.mcp.call("find_coverage_of", {"req_id": "<REQ-ID>"})            # 查某需求的覆盖
+```
+- `impact_coverage` 拿"这次改动必须跑哪些测试"——提交前用它圈定回归范围，不漏不改崩。
+- 改动实体 id 从 `rag_search`/`search_code` 命中里取。
+
 ---
 
 ## unit 单元测试

package/templates/qoder/contracts/CHANGELOG.md

@@ -0,0 +1,418 @@
+# 契约规范变更记录
+
+本文件记录 `.qoder/contracts/` 的演进，以及发现的「现状矛盾」何时被修复。
+
+格式：`[日期] 类型 - 描述`。类型：`added`（新增）/ `fixed`（修复矛盾）/ `gap`（待办）。
+
+---
+
+## 2026-06-18（已装同事升级路径修复：update 补装依赖 + 刷 MCP）
+
+### 问题
+- `wlkj update` 只刷新引擎文件，**不装 pip 依赖、不刷 launcher/mcp.json**。
+- 已装的同事跑 update 后，引擎代码是新的，但 duckdb/pymysql 还是没装 → 还是崩。
+- mcp.json 还是写死路径（C:\\Users\\HP\\...）→ 换机器/换用户名崩。
+
+### fixed
+- **cli.js doUpdate() 加两步**:
+  - Step 6: 自动 `pip install -r requirements.txt`（补齐依赖）
+  - Step 7: 复制 mcp_launcher.py 到 ~/.qoderwork/ + 调 `install_qoderwork.py --mcp-only` 刷 mcp.json
+- **install_qoderwork.py 加 --mcp-only 模式**: 只刷 launcher + mcp.json，不装 skill（update 时调，幂等轻量）。
+  - mcp.json 不存在时创建空骨架 + 自动补 kg/mysql/lanhu 条目。
+  - 路径用 _HOME 动态生成（不写死用户名）。
+
+### verified
+- `install_qoderwork.py --mcp-only` 实测: launcher 刷新 OK + mcp.json rewrite OK ✓
+- cli.js update 逻辑确认含 pip 补装 + launcher 刷新 + mcp.json 刷新 ✓
+
+### 老用户升级流程 (现在一条命令搞定)
+```bash
+npx @hupan56/wlkj update    # 刷新引擎 + 自动补 pip 依赖 + 刷 launcher/mcp.json
+```
+不再需要手动 pip install 或改 mcp.json 路径。
+
+---
+
+## 2026-06-18（全员可用性修复：依赖管理 + MCP 路径）
+
+### 问题 (全体同事用必崩)
+1. ❌ 无 requirements.txt — 同事不知装啥 pip 包
+2. ❌ init_doctor 不检查 pip 依赖 — duckdb/pymysql 没装图谱就崩
+3. ❌ install-env 只装 Node/Python/git — 不装任何 pip 包
+4. ❌ mcp_launcher.py 不在仓库 — 同事 clone 拿不到
+5. ❌ 全新机器 mcp.json 不自动创建 kg/mysql 条目
+
+### fixed
+- **requirements.txt**: 新建。9 个依赖按用途分组（核心/索引/测试/可选），标清版本+用途。
+- **init_doctor 加 check_dependencies()**: 检查 9 个 pip 包，核心缺失报 problem + 提示 pip install，--fix 自动装。
+- **install-env (cli.js) 加 pip install**: Node/Python/git 装完后自动 `pip install -r requirements.txt`。
+- **mcp_launcher.py 进仓库**: .qoder/scripts/protocol/mcp/mcp_launcher.py（随引擎分发），install 时复制到 ~/.qoderwork/。
+- **install_qoderwork.py 全新机器兜底**:
+  - mcp.json 不存在时创建空骨架（不再 return 跳过）
+  - kg/mysql/lanhu 条目不存在时自动创建（不再只改已有的）
+  - 路径用 _HOME 动态生成（不写死用户名）
+
+### verified
+- init_doctor 检查 9 依赖全 OK ✓
+- install check 正常 ✓
+- mcp_launcher.py 已在 .qoder/scripts/ + templates ✓
+
+### note
+- 同事上手流程现在是: install-env(自动装pip) → init(装引擎+launcher+生成mcp.json) → 直接用
+- MySQL 密码仍在 mcp.json 明文(测试库, 风险可控; 生产库绝不这样)
+
+---
+
+## 2026-06-18（全面审查：清理垃圾 + 修 MCP 命名一致性）
+
+### fixed (MCP 工具命名一致性)
+- **18+ 处 MCP 引用缺 server 段**：写成 `mcp__feature_overview` 而非完整 `mcp__qoder-knowledge-graph__feature_overview`。
+  - 影响 9 个文件：design-import/design-review/prototype-generator skill + wl-design-draw/scan/spec/wl-status/wl-prd-full/quick 命令。
+  - MCP 协议要求 `mcp__{server}__{tool}` 完整命名，简写在严格解析时断链。
+  - 全部修正为完整命名，已同步 templates。
+
+### cleaned (垃圾清理)
+- `.runtime/_*.py` ×7（临时测试脚本：_check_mysql/_test_mcp_client/_zcode_test_insurance 等）→ 删
+- `.runtime/search-cache-*.txt` ×2 + `last-pull` → 删
+- `.runtime/` 现在 0KB 干净。
+
+### verified (审查结论)
+- **脚本无语法错误**：全部 .py 通过 py_compile ✓
+- **eval_prd 新增函数无冲突**：_load_db_columns / _camel_to_snake 作用域正确 ✓
+- **MCP 无断链**：所有 `mcp__*` 引用都能在 TOOLS 列表对上 ✓
+- **gitignore 覆盖正确**：__pycache__/*.pyc 已忽略 ✓
+- **test-pages.json 非垃圾**：autotest.py 的锚点索引（350页/3897锚点），团队共享，保留 ✓
+
+### note (孤儿工具评估: 不删)
+- 9 个 MCP 工具定义了但无 skill 显式引用（search_code/search_api/get_impact/context_360/multi_hop/list_modules/list_databases/list_tables/search_field）。
+- **不删**：这些是 AI 按需调的基础能力/探索工具，不是每个都要被 skill 引用。留着按需用。
+
+---
+
+## 2026-06-18（kg_build_db 增量：库级签名对比，不再全量重扫）
+
+### fixed
+- **增量逻辑**：之前不带 --rebuild 会重复插入（数据翻倍 bug）；现在库级签名对比。
+  - 每个库算签名（表名列表 + 列总数）存 build_meta。
+  - 签名没变 = 跳过该库；变了才重建该库（只删该库旧数据 + 重插）。
+  - 比 MySQL update_time 准（后者数据行变更也刷新，不代表 schema 变）。
+
+### verified (两场景实测)
+- 无变化（全 10 库签名一致）：跳过 10 个，秒级完成，数据不变 ✓
+- 1 库变了（quality）：只重建 quality（101 表/1322 列），跳过其它 9 个 ✓
+- 总数据完整：仍 1049 表 / 17963 列 ✓
+
+---
+
+## 2026-06-18（三角色 MCP 增益接入：PM/开发/QA）
+
+### PM 增益 — prd-generator
+- 加 `search_prd`（防重复造轮子，查历史 PRD）
+- 加 `query_distinct`（字段真实枚举，别靠猜）
+- 加 `feature_overview`（需求范围评估，看现有端点/页面）
+
+### 开发增益 — wl-code
+- 加 `table_impact`（改前查影响：表→Entity→接口，防改崩）
+- 加 `query_schema`（真实字段核对，和 spec-coder 对齐）
+
+### QA 增益 — wl-test
+- 加 `query_data`（取真实测试数据，少手填）
+- 加 `query_distinct`（枚举边界覆盖，不漏分支）
+
+### note
+- 都是给 skill 加 MCP 调用说明，零逻辑改动、零风险。
+- 三个角色现在都能用图谱+数据库的完整能力。
+- 之前已接入的（spec-coder query_schema、wl-test coverage_matrix、prototype fill_prototype、design-review feature_overview）继续发挥。
+
+---
+
+## 2026-06-18（语义关联：打通代码层 ↔ 数据层，消除孤岛）
+
+### 问题
+kg_db.duckdb 有 1049 表/17963 列，但和代码图谱(kg.duckdb)是两个孤岛——
+表名子串匹配 endpoint 验证过 0 命中，不准。
+
+### 调研依据
+- FalkorDB 2026: "结构遍历 > 语义匹配"——别猜名字像不像，靠显式边遍历。
+- @TableName 注解是代码↔数据库唯一可靠的显式映射关系。
+
+### added
+- **kg_link_db.py**: 扫 9001 个 .java 的 @TableName 注解 → entity_table_map 表。
+  - 778 条 Entity→表映射, 705 张表匹配数据库真实表 (68%, 剩 32% 是代码引用了库范围外的表)。
+  - 含表名归一化 (camelCase→snake_case, 去库名前缀)。
+- **table_impact MCP 工具**: 改表影响分析, 跨层遍历 表→Entity→接口/Controller。
+  - 注册在 kg_mcp_server.py, AI 可调 mcp__qoder-knowledge-graph__table_impact。
+
+### verified (端到端走通)
+- quality_case 表 → QualityCase Entity → 代码图谱:
+  QualityCaseController / AppQualityCaseController + 5 个接口
+  (/getQualityCaseList /exportQualityCaseList /getQualityCaseTypeList 等)
+- 这正是之前"品质案件 SLA" PRD 提到的接口——改表影响分析能自动找到。
+- table_impact MCP 工具实测: 一条调用返回 表→字段+8个受影响接口。
+
+### note
+- entity_table_map 存 kg_db.duckdb (不动 kg.duckdb 写锁)。
+- 跨层查询靠 DuckDB ATTACH kg.duckdb (只读) 做 JOIN, 不引 Neo4j/FalkorDB。
+
+---
+
+## 2026-06-18（MySQL MCP 三层增益落地：spec/eval/图谱）
+
+### P0: skill 接入 MySQL MCP 说明
+- spec-generator / spec-coder SKILL.md 加：写表结构前调 `mcp__qoder-mysql__query_schema` 核对真实字段。
+- 替代缺失的 data-dictionary.md（动态真相源）。
+
+### P1: eval_prd A1 现实锚定升级为双层
+- score_reality() 加第二层：PRD 的 camelCase 字段 → 转 snake_case → 查数据库真实列名。
+- 验证：REQ-2026-007 评估报告显示 "(双层: 代码+数据库)，其中 2 个由数据库层确认"。
+- 安全：连不上/无 db_columns 表 → 自动降级纯代码层（空集），不影响评分。
+
+### P2: kg_build_db.py 数据层图谱
+- 扫 MySQL schema（10 库）→ 写 kg_db.duckdb（独立文件，不和 kg.duckdb 抢锁）。
+- **1049 表 / 17963 列**，秒级构建（JSONL COPY，比 executemany 快 5000 倍）。
+- 3 张表：db_tables / db_columns / db_table_fields。
+- eval_prd 的 P1 从 db_columns 读真实列名。
+- 性能坑修复：DuckDB 1.4 executemany 每行 22ms（bug），改 JSONL COPY 后万行 0.01s。
+
+### verified
+- P0: skill 已加 MCP 说明 ✓
+- P1: eval_prd 双层锚定，2 个字段由数据库层救回 ✓
+- P2: 全量构建 1049 表/17963 列，stats 正常 ✓
+
+## 2026-06-17（MySQL 只读 MCP：补工作流的数据真相层）
+
+### added
+- **mysql_mcp_server.py**：MySQL 只读 MCP 服务，5 个语义化工具（query_schema/query_data/query_distinct/list_databases/list_tables）。
+  注册在 ~/.qoderwork/mcp.json 的 qoder-mysql，账号密码进 env。测试环境 qas (10.54.6.9)。
+
+### 安全设计（3 层硬约束）
+1. 内网校验：每次调用 TCP 连 10.54.6.9:3306，不通则提示连内网。
+2. SQL 只读白名单：只允许 SELECT/SHOW/DESCRIBE/EXPLAIN/WITH；写操作全拒。
+3. LIMIT 强制注入：query_data 自动加 LIMIT 200。
+
+### verified (真实查询实测通过, 内网环境)
+- 内网连通: CONNECTED ✓
+- list databases: 11 个库 (fywl_ics_quality/salary/asset/...) ✓
+- list tables: fywl_ics_quality 库 101 张表 ✓
+- query_schema(quality_case): 48 列真实结构 + 中文注释 ✓
+  (process_status/limit_type/process_limit 等字段注释含枚举定义)
+- query_distinct(process_status): 真实分布 2=224条, 5=1条 ✓
+- 只读白名单: INSERT/UPDATE/DELETE/DROP 全拒；字段名含 delete 不误杀 ✓
+
+### note
+- 自研(复用 kg_mcp_server.py 范式),非社区版(默认允许写,不安全)。
+- 补的洞: data-dictionary.md 不存在 → MySQL MCP 成为数据字典的动态真相源。
+
+---
+
+
+---
+
+## 2026-06-17（埋点接入：learning 引擎自动捕获工作流事件）
+
+### changed
+- **eval_prd.py**：PRD 评估完成后自动埋点 `prd_accepted`（PASS）或 `prd_rejected`（FAIL），
+  记录分数 + A1/A2/A3 各维度。埋点失败不阻塞评估。
+- **task.py finish**：任务完成后自动埋点 `task_completed`，记录任务名 + 负责人 + 耗时。
+  埋点失败不阻塞任务完成。
+- **team_sync.py push**：推送成功后自动埋点 `commit_done`，记录文件数 + scope。
+  埋点失败不阻塞同步。
+- **design-review SKILL.md**：评审完成后 AI 调 `learn.py record review_done`，
+  记录评审对象 + 结果 + 问题清单。
+
+### verified (端到端实测)
+- eval_prd 埋点：跑完评估 → 自动写 `prd_rejected` 进 journal ✓（实测 FAIL 路径也触发）
+- task.py finish 埋点：任务完成 → 自动写 `task_completed` 进 journal ✓
+- learn_aggregate：journal 事件增量聚合到 kg.duckdb ✓（3 条：2 prd_rejected + 1 task_completed）
+- learning_stats 自动刷新：hupan, rejections=2, tasks_completed=1 ✓
+- team_sync import 链路：team_sync + learn.record_feedback import OK ✓
+  （未触发真实 push——有副作用操作，以代码审查 + import 验证替代）
+
+### note
+- 埋点模式统一：`try: from learn import record_feedback; record_feedback(...) except: pass`
+  保证埋点永不阻塞主流程。
+- 4 个埋点点覆盖核心工作流闭环：PRD 评审 → 任务完成 → 代码提交 → 设计评审。
+- 管理员定期跑 `learn_aggregate.py` 聚合到 kg.duckdb，团队学习数据成为单一真源。
+- design-review 是 skill（markdown 指令），埋点靠 AI 遵循；其余 3 个是脚本，自动触发。
+
+## 2026-06-17（learning 引擎重做：按人埋点 + 团队聚合到 kg.duckdb）
+
+### changed
+- **learn.py 重写**：存储从 `.qoder/learning/`（全局共享文件，多人 append 会 rebase 冲突）
+  改为 `workspace/members/{dev}/journal/feedback.jsonl`（按人分文件，进 git，不冲突）。
+  - 复用 paths.py 的 `get_developer_journal_dir()`，每条带 `dev` 字段。
+  - 统计计数同步到个人 `learning.yaml`。
+- **kg_duckdb.py 加 3 张 learning 表**：`learning_events`（聚合事件）、
+  `learning_stats`（每人统计快照）、`learning_patterns`（提炼模式，预留）。
+  - 复用 `init_schema` + `build_meta`，和代码图谱同构。
+- **.gitignore 修正**：个人 journal 文件（feedback.jsonl/learning.yaml）现在按人分，
+  不冲突 → 放开 git 跟踪，团队可见。旧 `.qoder/learning/` 的 feedback/preferences 保持忽略。
+
+### added
+- **learn_aggregate.py**：管理员聚合脚本，扫所有人的 journal → 增量写入 kg.duckdb。
+  - 同构 kg_build.py（扫 data/code → DuckDB）。
+  - 增量策略：记录 `build_meta` 的 `learning_last_aggregate`，只处理 mtime > last 的文件。
+  - 去重：event_id = hash(ts+dev+event+data)，重复事件不重写。
+  - `--rebuild` 全量重建；`query_summary()` 给 /wl-status 用。
+
+### verified (端到端实测通过)
+- 埋点：record prd_accepted/task_completed/prd_rejected/commit_done → 4 条写入 journal ✓
+- 聚合：learn_aggregate → 4 条进 kg.duckdb.learning_events ✓
+- 统计：learning_stats 自动刷新（hupan: prds=1, tasks=1, rejections=1）✓
+- 增量：再记 1 条后聚合，只处理新增（4→4累计，1新增）✓
+- 去重：无变化时聚合，0 新增 ✓
+
+### note
+- 数据流对称设计：个人埋点（journal/，进git）→ 团队聚合（kg.duckdb，单一真源）。
+- 和 kg.duckdb 同构：代码图谱扫 data/code，学习图谱扫 workspace/members/*/journal。
+- 待办：在 /wl-prd-full /wl-task /wl-commit 的 skill 里加 record_feedback() 调用（埋点接入）。
+
+---
+
+## 2026-06-17（提问润色：第 0 步，极速上下文定位）
+
+### added
+- **`enrich_prompt.py`**（`.qoder/scripts/`）：极速提示词润色脚本。
+  - 纯内存查表 + 中文分词（复用 common/terms.py），实测冷启动 <50ms / 热态 <10ms。
+  - 命中 keyword-index / api-index / prd-index 三类索引。
+  - 带噪声 token 黑名单（NOISE_KEYS），过滤 app/cs/fl/in 这类无意义短词。
+  - 输出 `is_business` 智能门：非业务消息（谢谢/继续）命中 0 → 自动放行不润色。
+  - 人类可读 + `--json` 机器可读两种输出。
+- **`prompt-enrich` skill**：把润色规则固化为「每条消息的第 0 步」。
+  - 用户提问 → 跑 enrich_prompt → 输出润色块 → 用户确认/改/拒 → 走原命令。
+  - 不改变意图，只补上下文。
+
+### verified
+- 三场景实测通过：
+  - 中文「保险批改异常统计」→ is_business=true, 19 代码符号 + 1 API
+  - 中英混合「薪资 BigDecimal」→ is_business=true, salary/wage/bigdecimal
+  - 「谢谢/继续」→ is_business=false, 自动放行
+- QoderWork 安装：21 skill 全绿，prompt-enrich 新建成功。
+
+### note
+- 用户原话：「用户提问后需要自动判断提示词、优化润色、给用户确认、快速」→ 本批落地。
+- **诚实说明**：ZCode/Qoder 对话模型没有「拦截消息暂停等确认」的原生 hook 机制。
+  本方案是 skill 层的**行为约束**——AI 读到 prompt-enrich 规则后,每条消息先跑润色再输出确认块。
+  这依赖 AI 遵循 skill 指令,不是平台级强制拦截。重启 QoderWork/新建对话后生效。
+
+---
+
+## 2026-06-16（第四批：commands 物理分层落地）
+
+### changed
+- **4 个可选命令归入 `optional/` 子目录**：
+  - `wl-spec.md` / `wl-status.md` / `wl-report.md` / `wl-insight.md`
+    → 移到 `.qoder/commands/optional/`
+  - 根目录留 8 个核心（init/prd/design/task/search/code/test/commit）
+  - Qoder IDE 按 Qoder 官方机制会按子目录归类显示，主次分明。
+- **install_qoderwork.py 修复**：`glob("wl-*.md")` → `rglob("*.md")`
+  - 原来只扫根目录，子目录里的命令 QoderWork 装不上
+  - 现在递归扫描，4 个 optional 命令照样能装到用户级（已 `--check` 验证）
+- **sync_templates.py 注释更新**：commands 说明改为「8 核心 + optional/ 4 个」+ 补 contracts 目录。
+
+### verified
+- `install_qoderwork.py --check` 确认能发现全部 12 个命令（含 optional/ 里的 4 个）。
+  输出：`commands: 0 新建 / 11 已存在`（仅新 wl-design.md 待装）。
+- 主仓库 + 模板包 commands 结构完全一致（根 8 + optional 4）。
+
+### synced（模板包同步）
+- `.qoder/commands/` 全目录（含 optional/）→ `packages/wlkj/templates/qoder/commands/`
+- `install_qoderwork.py` → `packages/wlkj/templates/qoder/scripts/`
+- AGENTS.md → `packages/wlkj/templates/root/AGENTS.md`
+
+### note
+- 用户原话：「那为什么 commands 文件夹还有这么多」→ 本批是物理层收敛。
+- 调研结论：Qoder IDE **递归扫描**子目录（官方文档「directory and its subdirectories」），
+  但子目录里的命令**仍出现在 `/` 列表**（只是归类）。所以子目录的作用是**分组**不是**隐藏**。
+- QoderWork 安装脚本是另一条路（`glob`），已修复为 `rglob` 保证不丢命令。
+
+---
+
+## 2026-06-16（第三批：AGENTS.md 小而美落地，7 核心定型）
+
+### fixed
+- **AGENTS.md 命令区重构**：从「11 Commands」平铺改为「7 Core + Optional」分层。
+  - 7 核心：init/prd/design/task/code/test/commit（每个带模式参数）
+  - 可选 5：search/spec/status/report/insight（按需启用）
+  - 新人只需记 7 个核心命令。
+- **自然语言路由表（规则 2.5）补 design 三模式**：
+  录入设计稿→import、按设计出原型→generate、评审原型→review。
+- **Workflow 行修正为契约网**：明确「非强制流水线」，模块可独立开机，
+  删除了原来 `→ prd → task → spec → code → test → commit → report` 的强顺序。
+- **Permission Model 补 /wl-design** 到 SAFE 层。
+- **wl-pipeline.md 用户侧命令一览**同步为 7 核心 + 模式参数表。
+
+### synced（模板包同步）
+- AGENTS.md → `packages/wlkj/templates/root/AGENTS.md`（验证完全一致）
+- wl-pipeline.md → `packages/wlkj/templates/qoder/rules/`
+
+### note
+- 这批是「重组」不是「新增」——把 12 个命令的认知负担收敛到 7 个核心。
+- 用户原话：「你不是说要小而美吗，怎么还有 11 个」——本批修正这个自相矛盾。
+
+---
+
+## 2026-06-16（第二批：命令/技能小而美落地）
+
+### added
+- 新增 `/wl-design` 命令（`.qoder/commands/wl-design.md`）：
+  三模式路由 `import`/`generate`/`review`，把 design 提升为工作流一等公民。
+- 新增 `wl-design` skill 入口（`.qoder/skills/wl-design/SKILL.md`）：
+  Quest/QoderWork 的 `/` 列表也能用 `/wl-design`。
+- README 新增「用户认知面：只需记 7 个 /wl-* 命令」+ 模式参数总表 + 「核心 vs 可选」分层。
+- 设计原则落地：**对外 7 个命令，对内保 19+ skill**，通过模式参数一个命令当多个用。
+
+### fixed
+- 4 个重复 skill 加「📌 主入口」标注，消除"用哪个"的认知犹豫：
+  - prd-generator → 主入口 /wl-prd-full
+  - spec-generator → 主入口 /wl-spec
+  - spec-coder → 主入口 /wl-code
+  - test-generator → 主入口 /wl-test unit
+
+### synced（模板包同步）
+- `.qoder/commands/wl-design.md` → `packages/wlkj/templates/qoder/commands/`
+- `.qoder/skills/wl-design/` → `packages/wlkj/templates/qoder/skills/`
+- `.qoder/contracts/` 全目录 → `packages/wlkj/templates/qoder/contracts/`
+- 4 个 skill 的主入口标注 → 同步到 templates 包对应文件
+- （spec 文件名修复已在前一批同步）
+
+### note
+- 本次新增 2 文件 + 改 5 文件（4 skill 标注 + README 扩充），未动任何脚本/索引。
+- 模式参数设计参考 `/wl-test`（quick/browser/unit）已有范例，`/wl-design` 沿用同构模式。
+
+---
+
+## 2026-06-16（第一批：契约中枢建立）
+
+### added
+- 首次建立 `.qoder/contracts/` 契约中枢目录
+- 新增 README.md：模块契约网架构 + 降级链路 + 七模块速查表 + 软契约原则
+- 新增 contract-header.md：`@contract` 契约头规范（软契约，缺字段只警告）
+- 新增 7 个模块契约：prd / design / task / spec / code / test / commit
+- 新增 fallback.md：语言描述兜底（全索引 + PRD 历史自检索流程）
+- 确立设计原则：**契约网，不是流水线**。模块认文件不认流程，可独立开机。
+
+### gap（已知现状矛盾，待修复）
+
+- [x] **spec 输出文件名不一致** ✅ 已修复 (2026-06-16)
+      - `spec-generator/SKILL.md` → `REQ-{ID}-{module}.spec.md`
+      - `wl-spec/SKILL.md` → `spec-{REQ-ID}-{desc}.md`（旧）
+      - **契约已统一为** `REQ-{ID}-{module}.spec.md`（与 prd 的 REQ-ID 一致）
+      - **已完成**：修正 `.qoder/skills/wl-spec/SKILL.md` + 加契约中枢引用
+      - **已完成**：同步修正 `packages/wlkj/templates/qoder/skills/wl-spec/SKILL.md`
+
+- [ ] **design spec.json 尚无实际产出**
+      - `data/style/` 当前只有 2 个 PDF（web端 + APP端设计规范）
+      - design-import 声明会产出 `{需求}-design-spec.json`，但还没有真实案例
+      - **影响**：在首个设计师录入前，design 模块只能走「代码真源」级降级
+      - **待办**：等首个真实设计录入后，验证 spec.json 格式是否需要调整
+
+- [ ] **多数模块无独立校验脚本**
+      - 只有 prd 有硬门禁（eval_prd.py ≥80%）
+      - task / spec / code / test / commit 全靠 skill 内自检清单
+      - **待办**（低优先）：哪个模块产出老是不合规，就给它补个校验脚本，从软契约升硬
+
+### note
+- 本次新增**纯新增文件**，未修改任何现有 skill / script / 索引。
+- 另一个窗口正在更新 `data/index/` 知识图谱，本目录不写入索引，互不干扰。
+- context_pack.py / search_index.py 是只读消费索引，兜底策略可直接复用。

package/templates/qoder/contracts/README.md

@@ -0,0 +1,180 @@
+# 模块契约中枢（CONTRACTS）
+
+> 本目录是整个工作流的**单一事实源**：定义每个模块「吃什么 / 吐什么 / 怎么算合规」。
+> 模块之间**不依赖上游是否执行**，只依赖**一份符合契约的文件**。
+> 谁都能单独开机，靠标准文件互相对接。
+
+---
+
+## 设计原则：契约网，不是流水线
+
+```
+                 自然语言 / 截图（零输入也能开工）
+                       │
+            ┌──────────┼──────────┐
+            ▼          ▼          ▼
+         [prd]     [design]    [test]      ← 7 个独立黑盒
+            │          │          │          都能单独开机
+            ▼          ▼          ▼
+        REQ-*.md   *-spec.json  cases.json   ← 标准契约文件（唯一耦合点）
+            │    ↗     │     ↖
+            ▼  ╱       ▼       ╲ ▼
+         [task]    [spec]    [code]          ← 吃契约文件，不认上游
+            │          │          │
+            └──────────┼──────────┘
+                       ▼
+                   [commit]
+```
+
+- **箭头 = 可以消费**，不是必须等待。没有强制顺序。
+- **任何模块缺上游 → 手动喂个契约文件，照样开工。**
+- **文件就是接口**：上游是谁、跑没跑、人还是 AI，都不重要。
+
+---
+
+## 降级链路：从完整输入到「一句话」
+
+每个模块的输入都有一条降级链，越往下越能独立作战，代价是产出精度下降：
+
+```
+完整输入（契约文件）          产出最稳，可复现性最高
+   ↓ 降级 1
+部分契约（PRD 或 截图）
+   ↓ 降级 2
+一句话描述（口语需求）
+   ↓ 降级 3 ★ 最终兜底
+自然语言 + 全索引自检索       AI 自己用 context_pack / search_index 找上下文硬干
+```
+
+**降级 3 的做法**（本仓库特有）：
+模块没拿到任何契约文件时，AI 用业务关键词跑一次
+`python .qoder/scripts/orchestration/wlkj.py context <业务词> --platform <web|app>`，
+一次性拿到 7 段上下文（代码 / 页面示例 / 字段 / 历史 PRD / API / 设计 token / Wiki），
+再叠上 `search_index.py --prd <关键词>` 查历史 PRD，**自己凑出最小输入开工**。
+
+> 注：知识图谱（`data/index/`）正在持续更新，context_pack 会自动用最新索引，
+> 不需要等它跑完。索引是只读消费，这边不抢写资源。
+
+---
+
+## 七模块契约速查表
+
+| 模块 | 吃什么（Input） | 吐什么（Output） | 校验 | 详细契约 |
+|------|----------------|------------------|------|----------|
+| **prd** | 一句话需求 / 任意业务描述 | `REQ-{YYYY}-{NNN}-{标题}.md` + 原型 html | eval_prd.py ≥80% | [prd.md](prd.md) |
+| **design** | PRD / Figma 截图 / 一句话 | `{需求}-design-spec.json` + 原型 html | design-review checklist | [design.md](design.md) |
+| **task** | 任意一份 PRD | 任务目录 `task.json` + RICE | 无 | [task.md](task.md) |
+| **spec** | PRD（必需） | `REQ-{ID}-{module}.spec.md` | 无（待建） | [spec.md](spec.md) |
+| **code** | spec（必需）/ PRD（降级） | 源码写入 `data/code/` | 自检清单 | [code.md](code.md) |
+| **test** | PRD / spec / 一句话 | 用例 json / JUnit | 自检清单 | [test.md](test.md) |
+| **commit** | 任意改动文件 | git 提交 | 提交前门禁 | [commit.md](commit.md) |
+
+> 每个模块的 Output 契约 = 下游的 Input 契约。这是唯一的耦合方式。
+
+---
+
+## 用户认知面：只需记 7 个 /wl-* 命令
+
+小而美的核心——**对外只暴露 7 个命令，每个是一道工序站，每个带模式参数路由到背后的 skill。**
+
+| 命令 | 工序站 | 模式参数 | 背后的 skill | 自动批准？ |
+|------|--------|---------|-------------|-----------|
+| `/wl-init` | 身份 | （无） | wl-init | ✅ |
+| `/wl-prd` | 需求 | `完整`/`快速`/`评审` 语义路由；支持`参考:<报告>` | prd-generator/prd-review | ✅ |
+| `/wl-design` | 设计 | `预览`/`扫描`/`评审` 或默认(预览) | design-import/prototype-generator/design-review | ✅ |
+| `/wl-task` | 任务 | `create`/`list`/`show`/`start`/`finish`/`archive`/`rank`/`plan` | wl-task | ✅ |
+| `/wl-code` | 编码 | （无，按 spec 实现） | spec-coder | ⚠️ 需确认 |
+| `/wl-test` | 测试 | `quick`/`browser`/`unit`/`coverage` 或默认(quick) | wl-test / test-generator | ⚠️ 需确认 |
+| `/wl-commit` | 提交 | （无） | wl-commit | ⚠️ 需确认 |
+
+> **模式参数 = 一个命令当多个用。** 不记住参数也没关系，自然语言一样路由
+> （"快速加个字段" → prd 快速；"录入设计稿" → design import；"补单测" → test unit）。
+
+### 为什么是 7 个不是 11 个
+
+现有 11 个 `/wl-*` 命令里，有 4 个是「长大了再开」的可选层，不进主干认知：
+
+| 命令 | 为什么可选 | 何时启用 |
+|------|-----------|---------|
+| `/wl-search` | 全员共用基础设施（不是工序站，是工具） | 随时用，但不用专门记 |
+| `/wl-spec` | 小团队 PMD 直接给开发讲也行 | 需求复杂度上来再开 |
+| `/wl-status` | 需要管理汇报时 | 团队有 PMO/汇报需求 |
+| `/wl-report` | 写日报周报时 | 需要向上汇报 |
+| `/wl-insight` | 需要埋点数据 | 接了埋点/反馈源 |
+
+**核心 7 个是执行链路必经**，可选 5 个是按需开启。新人只记 7 个就能把活干完。
+
+---
+
+## 核心 skill vs 可选 skill
+
+skill 层保持完整（19+ 个），但分主次。**重复对已标注主入口**（skill 顶部 `📌 主入口`）：
+
+### 核心层（7 命令的实现层，必有）
+
+| 命令 | 主 skill | 实现 skill（被路由） |
+|------|---------|---------------------|
+| /wl-prd | wl-prd | prd-generator（完整/快速）、prd-review（评审） |
+| /wl-design | wl-design | design-import, prototype-generator, design-review |
+| /wl-task | wl-task | — |
+| /wl-code | wl-code | spec-coder |
+| /wl-test | wl-test | test-generator（unit 模式） |
+| /wl-commit | wl-commit | — |
+| /wl-init | wl-init | — |
+
+### 可选层（长大了再开）
+
+| skill | 用途 | 启用条件 |
+|-------|------|---------|
+| prd-review | PRD 质量评审 | PRD 量大 / 团队 >5 人 |
+| wl-insight | 反馈+埋点分析 | 接了数据源 |
+| wl-status | 项目健康度 | 有 PMO |
+| wl-report | 日报周报 | 需要汇报 |
+| spec-generator | 技术规格 | 需求复杂 |
+| wl-search | 代码搜索 | 全员工具（随时可用，非工序站） |
+
+---
+
+## 契约强度：软契约（warn 不 block）
+
+本工作流采用**软契约**：
+
+- 契约文件**应该**带一个 `@contract` 头（见 [contract-header.md](contract-header.md)）。
+- 缺关键字段时：**只警告（`⚠️ 缺少 platform 字段`），不拦截执行**。
+- 原因：软契约保证「独立作战时不被格式卡死」，下游能降级跑通。
+- 例外：**prd 模块是唯一硬门禁**（`eval_prd.py` < 80% 不让发布），因为它是最上游的契约源。
+
+> 如果你发现某个模块产出老是不合规，可以把它的契约从「软」升到「硬」——
+> 给它加个校验脚本即可（参考 eval_prd.py）。
+
+---
+
+## 给新人 / 新模块的两条铁律
+
+1. **写新模块前，先在这里登记它的 Input/Output 契约。** 没登记 = 不算工作流成员。
+2. **改某个模块的输出格式，必须同步改下游的 Input 契约。** 契约是双方签的，不能单方面改。
+
+---
+
+## 与现有文档的关系
+
+| 文档 | 角色 | 关系 |
+|------|------|------|
+| **本目录 CONTRACTS** | 模块间接口规范 | 「模块吃什么吐什么」的唯一事实源 |
+| `AGENTS.md` | 项目入口 + 命令清单 | 给人看的导航；细节回引这里 |
+| `.qoder/rules/wl-pipeline.md` | 工作流规则（always_on） | 执行约束；输出格式回引这里 |
+| `.qoder/skills/*/SKILL.md` | 单模块实现细节 | 每个 skill 顶部应声明「本模块契约见 `.qoder/contracts/{模块}.md`」 |
+
+**优先级**：契约冲突时，以本目录为准；本目录没覆盖的，以 skill 实际行为为准，并回填到这里。
+
+---
+
+## 待统一项（KNOWN GAPS）
+
+> 这些是现状里发现的矛盾，记在这里追踪，不掩盖：
+
+- [ ] **spec 输出文件名两处不一致**：`spec-generator` 用 `REQ-{ID}-{module}.spec.md`，
+      `wl-spec` 用 `spec-{REQ-ID}-{desc}.md`。→ 契约统一为 `REQ-{ID}-{module}.spec.md`。
+- [ ] **design spec.json 尚无实际产出**：`data/style/` 当前只有 2 个 PDF，
+      design-import 声明的 `{需求}-design-spec.json` 是预期而非现状。
+- [ ] **task / spec / code / test / commit 无独立校验脚本**：当前靠 skill 内自检清单。