@hupan56/wlkj 3.1.3 → 3.1.5

package/package.json

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

package/templates/qoder/commands/optional/wl-insight.md

@@ -23,7 +23,7 @@ User input: $ARGUMENTS
 
 **先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
 > 后续脚本统一用 `python "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
 

package/templates/qoder/commands/optional/wl-report.md

@@ -14,7 +14,7 @@ User input: $ARGUMENTS
 
 **先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
 > 后续脚本统一用 `python "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`；所有仓库内相对路径（workspace/、data/code/）都前置 `"$R/"`。
 
@@ -38,7 +38,7 @@ If no developer is set, refuse and say "Run /wl-init first".
 ### ⚡ Fast Path：一次拿全（必须先跑，禁止逐个 cat/ls/git log）
 
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 python "$R/.qoder/scripts/orchestration/wlkj.py" report-snapshot "$R"            # 日报(今天)
 python "$R/.qoder/scripts/orchestration/wlkj.py" report-snapshot "$R" --days 7   # 周报(近7天)
 ```

package/templates/qoder/commands/optional/wl-status.md

@@ -14,7 +14,7 @@ User input: $ARGUMENTS (default: show current status)
 
 **先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
 > 后续脚本统一用 `python "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`；仓库内相对路径都前置 `"$R/"`。
 

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

@@ -14,7 +14,7 @@ User input: $ARGUMENTS
 
 **先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
 > 后续脚本统一用 `python "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
 

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

@@ -120,6 +120,8 @@ cap.mcp.call("context_pack", {"keyword": "<功能名>", "platform": "web"})
 ## 埋点（评审完成后）
 
 评审输出后，记录到 learning：
+> 先定位仓库根 `R`（Mac 只有 python3, 两个都试）:
+> `R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.`
 ```bash
 python "$R/.qoder/scripts/orchestration/wlkj.py" learn record review_done "{\"target\":\"$feature\",\"result\":\"$pass_or_issues\"}"
 ```

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

@@ -17,7 +17,7 @@ Usage:
 
 **先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
 > `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。后续脚本统一用 `python "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
 

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

@@ -43,6 +43,10 @@ User input: $ARGUMENTS
 ``
 
 ### 取上下文（1 次调用取全 8 段）
+先定位仓库根（Mac 只有 python3, 两个都试）:
+``bash
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+``
 ``bash
 python "$R/.qoder/scripts/orchestration/wlkj.py" context <业务词> --platform <web|app>
 ``

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

@@ -17,6 +17,9 @@ argument-hint: "[REQ-ID] [发布]"
 
 ## 实现层
 
+> 先定位仓库根 `R`（Mac 只有 python3, 两个都试; 失败回退 `.` 即当前工作目录）:
+> `R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.`
+
 ```bash
 # 列需求
 python "$R/.qoder/scripts/orchestration/wlkj.py" req

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

@@ -97,6 +97,8 @@ cap.mcp.call("search_code", {"keyword": "--components"})         # 组件使用
 🚫 **绝对禁止**用 `findstr /s`、`grep -r`、`os.walk`、`subprocess` 全盘递归扫 data/code。
 
 **中文文案/报错溯源**（用户查的是中文短语），**唯一合法方式**：
+> 先定位仓库根 `R`（Mac 只有 python3, 两个都试）:
+> `R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.`
 ```bash
 # grep-text 走 CLI 降级（不是 MCP 工具）
 python "$R/.qoder/scripts/orchestration/wlkj.py" kg grep-text 车辆不存在 --ext java --limit 20

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

@@ -19,7 +19,7 @@ User input: $ARGUMENTS
 
 **先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
 > 后续脚本统一用 `python "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
 

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

@@ -16,7 +16,7 @@ User input: $ARGUMENTS
 
 **先确定仓库根 R**（QoderWork 桌面端工作目录不是仓库根，相对路径会失效）：
 ```bash
-R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
+R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
 > 后续脚本统一用 `python "$R/.qoder/scripts/orchestration/wlkj.py" <命令>`。
 

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/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 是只读消费索引，兜底策略可直接复用。