@hupan56/wlkj 2.7.12 → 3.0.0

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

@@ -16,12 +16,12 @@ User input: $ARGUMENTS
 ```bash
 R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
-> 后续脚本统一用 `python "$R/.qoder/scripts/xxx.py"`。
+> 后续脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io）或 `python "$R/.qoder/scripts/wlkj.py" <命令>`。
 
 ## 双轨：MCP 优先（仅 QoderWork）/ kg.py 兜底（全系列通用）
 
 **QoderWork 环境**（有 `mcp__qoder-knowledge-graph`）：直接调 MCP 工具，更快。
-**其他 Qoder 载体**（IDE/Quest/CLI）：跑 `python "$R/.qoder/scripts/kg.py"`，功能等价。
+**其他 Qoder 载体**（IDE/Quest/CLI）：跑 `python "$R/.qoder/scripts/kg/kg.py"`，功能等价。
 
 不确定在哪个环境？先试 MCP；MCP 工具不存在就用 kg.py。
 
@@ -58,16 +58,16 @@ R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 这些 kg.py 未单独封装，直接跑：
 
 ```
-python "$R/.qoder/scripts/search_index.py" --field <字段名>
-python "$R/.qoder/scripts/search_index.py" --style <table|form|detail|modal|dashboard> [--platform web|app]
-python "$R/.qoder/scripts/search_index.py" --list        # Top50 关键词
-python "$R/.qoder/scripts/search_index.py" --modules     # 项目模块概览
-python "$R/.qoder/scripts/search_index.py" --components  # 组件使用统计
+python "$R/.qoder/scripts/kg/search_index.py" --field <字段名>
+python "$R/.qoder/scripts/kg/search_index.py" --style <table|form|detail|modal|dashboard> [--platform web|app]
+python "$R/.qoder/scripts/kg/search_index.py" --list        # Top50 关键词
+python "$R/.qoder/scripts/kg/search_index.py" --modules     # 项目模块概览
+python "$R/.qoder/scripts/kg/search_index.py" --components  # 组件使用统计
 ```
 
 ## 没给参数时
 
-如果用户没给关键词/子命令，先问意图，或跑 `python "$R/.qoder/scripts/search_index.py" --list` 列出热门关键词让用户选。
+如果用户没给关键词/子命令，先问意图，或跑 `python "$R/.qoder/scripts/kg/search_index.py" --list` 列出热门关键词让用户选。
 
 ## DO NOT grep the entire codebase
 

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

@@ -21,7 +21,7 @@ User input: $ARGUMENTS
 ```bash
 R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
-> 后续脚本统一用 `python "$R/.qoder/scripts/xxx.py"`（task.py / team_sync.py 等）。
+> 后续脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io）或 `python "$R/.qoder/scripts/wlkj.py" <命令>`（task.py / team_sync.py 等）。
 
 ---
 
@@ -90,7 +90,7 @@ ls data/docs/prd/REQ-*.md 2>nul
 
 **B. 建任务**
 ```bash
-python "$R/.qoder/scripts/task.py" create "<标题>" --priority <P0|P1|P2|P3>
+python "$R/.qoder/scripts/task/task.py" create "<标题>" --priority <P0|P1|P2|P3>
 ```
 - `--assignee` 不填则默认当前开发者（产品建的常指派给开发，可加 `--assignee 老李`）。
 - `--slug` 不填则自动从标题生成（中文标题也能生成，但建议给个英文 slug 如 `--slug login-export`）。
@@ -101,13 +101,13 @@ python "$R/.qoder/scripts/task.py" create "<标题>" --priority <P0|P1|P2|P3>
 2. **待排期池 >3 个任务时**，主动建议："要不要我跑个 rank 排下优先级？"
 3. 自动同步（用户永不碰 git）：
 ```bash
-python "$R/.qoder/scripts/team_sync.py" push
+python "$R/.qoder/scripts/task/team_sync.py" push
 ```
 
 ### list —— 看任务（一次取全，别串行）
 
 ```bash
-python "$R/.qoder/scripts/task.py" list [--mine] [--status <s>] [--ready] [--blocked]
+python "$R/.qoder/scripts/task/task.py" list [--mine] [--status <s>] [--ready] [--blocked]
 ```
 
 | flag | 用途 |
@@ -127,13 +127,13 @@ python "$R/.qoder/scripts/task.py" list [--mine] [--status <s>] [--ready] [--blo
 
 ### show —— 看单个任务详情
 ```bash
-python "$R/.qoder/scripts/task.py" show <任务名或目录>
+python "$R/.qoder/scripts/task/task.py" show <任务名或目录>
 ```
 任务名支持模糊匹配（脚本内部 `resolve_task_dir` 会解析）。读完把关键字段（状态/优先级/assignee/due/依赖/prd路径）整理给用户。
 
 ### start —— 启动任务（移交开发工位的信号）
 ```bash
-python "$R/.qoder/scripts/task.py" start <任务名>
+python "$R/.qoder/scripts/task/task.py" start <任务名>
 ```
 - 状态 `planning → in_progress`，成为活跃任务（`.current-task`）。
 - 这是产品→开发的交接点：start 后开发就能 `/wl-code` 了。
@@ -141,7 +141,7 @@ python "$R/.qoder/scripts/task.py" start <任务名>
 
 ### reassign —— 改派任务负责人（多角色协作必需）
 ```bash
-python "$R/.qoder/scripts/task.py" reassign <任务名> <新负责人>
+python "$R/.qoder/scripts/task/task.py" reassign <任务名> <新负责人>
 ```
 - 场景：PM 建任务（assignee 默认是自己）后，要转给开发老李做。
 - 改派后新负责人才能 `start`/`finish`（零信任 ACL 按 assignee 判定）。
@@ -150,7 +150,7 @@ python "$R/.qoder/scripts/task.py" reassign <任务名> <新负责人>
 
 ### finish —— 完成当前任务
 ```bash
-python "$R/.qoder/scripts/team_sync.py" push
+python "$R/.qoder/scripts/task/team_sync.py" push
 ```
 - 活跃任务状态 → `completed`，活跃指针清除。
 - 完成后提示：要不要 `archive` 归档？要不要看下个 `--ready` 的任务？
@@ -158,7 +158,7 @@ python "$R/.qoder/scripts/team_sync.py" push
 
 ### archive —— 归档（移到 .qoder/archive/{YYYY-MM}/）
 ```bash
-python "$R/.qoder/scripts/task.py" archive <任务名>
+python "$R/.qoder/scripts/task/task.py" archive <任务名>
 ```
 - 事务化：先 move 成功再改 status，move 失败原任务完好。
 - **自动清理孤儿依赖**：归档后，其它任务里对它的 `blocked_by/blocks/children/parent` 引用会被扫除（防止僵尸任务永远 blocked）。
@@ -172,7 +172,7 @@ python "$R/.qoder/scripts/task.py" archive <任务名>
 
 ### 一次取全（别逐个问）
 ```bash
-python "$R/.qoder/scripts/task.py" list --status planning
+python "$R/.qoder/scripts/task/task.py" list --status planning
 ```
 拿到所有待排任务，**一次性**评估，不要一个任务问四轮 R/I/C/E。
 
@@ -203,23 +203,23 @@ python "$R/.qoder/scripts/task.py" list --status planning
 
 ### 设置截止日期
 ```bash
-python "$R/.qoder/scripts/task.py" set-due <任务名> <YYYY-MM-DD>
+python "$R/.qoder/scripts/task/task.py" set-due <任务名> <YYYY-MM-DD>
 ```
 
 ### 依赖关系（谁挡谁）
 ```bash
 # A 被 B 阻塞（要等 B 完成）
-python "$R/.qoder/scripts/task.py" block <A任务名> <B任务名>
+python "$R/.qoder/scripts/task/task.py" block <A任务名> <B任务名>
 # 解除
-python "$R/.qoder/scripts/task.py" unblock <A任务名> <B任务名>
+python "$R/.qoder/scripts/task/task.py" unblock <A任务名> <B任务名>
 ```
 - **循环依赖自动检测**：脚本会 BFS 检查，发现环就拒绝（返回 1）。
 - 反向 `blocks` 关系自动维护（A 被 B 阻塞时，B 的 blocks 自动加 A）。
 
 ### 看甘特图
 ```bash
-python "$R/.qoder/scripts/team_sync.py" push
-python "$R/.qoder/scripts/task.py" gantt [--weeks 4]
+python "$R/.qoder/scripts/task/team_sync.py" push
+python "$R/.qoder/scripts/task/task.py" gantt [--weeks 4]
 ```
 - 只排有 `start_date`/`due_date` 的任务。
 - 没日期的任务 → 提示："用 `set-due` 给任务加截止日期，甘特图才会显示。"
@@ -231,8 +231,8 @@ python "$R/.qoder/scripts/task.py" gantt [--weeks 4]
 
 ```bash
 # 把大任务 A 拆出子任务 B
-python "$R/.qoder/scripts/task.py" add-subtask <A任务名> <B任务名>
-python "$R/.qoder/scripts/task.py" remove-subtask <A任务名> <B任务名>
+python "$R/.qoder/scripts/task/task.py" add-subtask <A任务名> <B任务名>
+python "$R/.qoder/scripts/task/task.py" remove-subtask <A任务名> <B任务名>
 ```
 - 父任务记录 `children`，子任务记录 `parent`。
 - 产品用：把一个大需求拆成"前端/后端/数据"几个子任务，各自指派。

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

@@ -18,7 +18,7 @@ User input: $ARGUMENTS
 ```bash
 R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 ```
-> 后续脚本统一用 `python "$R/.qoder/scripts/xxx.py"`。
+> 后续脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io）或 `python "$R/.qoder/scripts/wlkj.py" <命令>`。
 
 ## 🚦 第一步：路由（看用户输入，立刻决定走哪条线）
 
@@ -39,29 +39,55 @@ R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 +该页面的通用交互模式生成用例。平台/环境 AI 推断（web 默认、test 默认），
 **只在真不确定平台时才问一句**。不要问地址、不要问登录方式——这些 config/文档里都有。
 
-### 流程（3 步，不绕弯）
+### 🔴 quick 执行铁律（实测踩过的坑，违反 = 测试失败）
 
-**Step 1：AI 据用户描述生成用例 JSON。** 不搜代码。常见页面直接写：
-- 登录页：goto /auth/login → 填账号密码 → 点登录 → 断言跳转
+- **① 用意图式 intent+anchor 格式，禁止旧 action+CSS selector**（如 `input[placeholder*='账号']`）
+- **② 占位符精确用 `{{ask:登录账号}}`/`{{ask:登录密码}}`**（匹配个人文档 key，别写"测试账号"）
+- **③ `--cases-file` 传文件，禁止内联 `--cases`**（长 JSON 截断）
+- **④ recall 空时先 navigate+snapshot 拿真实 anchor 再填，禁止预猜 selector**
+- **⑤ URL 写 `{{base_url}}/auth/login`（带斜杠，base_url 已去尾斜杠）**
+- **⑥ recall 的 `--url` 用相对路径 `auth/login`**（前导斜杠会被 Windows Git-bash 转成 `/D:/.../Git/auth/login`）
+- **⑦ Playwright 工具批量加载，snapshot 结果直接读，不写文件再 Read**
+- **⑧ 验证码一气呵成（snapshot→截图→Read→type→点登录→删图），填完立刻提交**
+- **⑨ 用例一次生成全部（正向+异常），别一条一条**
+
+### 流程（4 步，不绕弯）
+
+**Step 0：recall 查锚点（用相对 URL）。**
+```bash
+python "$R/.qoder/scripts/test/autotest.py" recall --url auth/login
+```
+- 有锚点 → 直接填进用例 anchor（零 LLM）
+- 无锚点（首次）→ **先 navigate + snapshot 拿真实 a11y 树，从里面提取 anchor**，禁止预猜 selector
+
+**Step 1：AI 据用户描述 + 锚点生成用例 JSON。** 不搜代码。常见页面直接写：
+- 登录页：goto `{{base_url}}/auth/login` → 填账号密码 → 点登录 → 断言跳转
 - 列表页：goto 列表 → 断言表格加载 → 翻页/筛选
 - 表单页：goto → 填字段 → 提交 → 断言成功提示
-需要真实数据(账号/密码)用 `{{ask:描述}}` 占位，URL 用 `{{base_url}}`。
-正向 + 关键异常各一条。
+需要真实数据(账号/密码)用 `{{ask:描述}}` 占位，URL 用 `{{base_url}}/xxx`（**带斜杠**）。
+正向 + 关键异常各一条。**一次生成全部用例。**
+```json
+// ✅ 意图式格式 (anchor 来自 recall 或 snapshot)
+{"intent":"fill","desc":"账号框","value":"{{ask:登录账号}}","anchor":{"role":"textbox","name":"尊敬的管理员"}}
+// ❌ 禁止: 旧 action+CSS selector
+{"action":"fill","target":"input[placeholder*='账号']","value":"{{ask:测试账号}}"}
+```
 
 **Step 2：调脚本，注入数据 + 出执行计划：**
 ```bash
-python "$R/.qoder/scripts/autotest.py" quick \
-  --cases '<Step1生成的JSON>' \
+# AI 先把用例 JSON 写文件, 再传路径 (--cases-file, 不截断)
+python "$R/.qoder/scripts/test/autotest.py" quick \
+  --cases-file <文件路径> \
   --desc "<用户描述>" --platform <web|app>
 ```
 脚本自动：解析 test 环境域名 + 从个人文档注入账号密码 + 出执行计划。
 若提示"需要测试数据" → 逐项问用户，再用 `--data` 传。
 
-**Step 3：执行由 QoderWork 浏览器连接器承担（真实场景）。**
-脚本只出计划，不自己开浏览器。无连接器 → 降级人工核对清单。
+**Step 3：执行由 Playwright MCP 驱动（真实场景）。**
+脚本只出计划，不自己开浏览器。批量加载 browser_* 工具后按执行计划连发操作。
 跑完回传结果出报告：
 ```bash
-python "$R/.qoder/scripts/autotest.py" quick --record '{"Q-1":"pass","Q-2":"fail"}'
+python "$R/.qoder/scripts/test/autotest.py" quick --record '{"Q-1":"pass","Q-2":"fail"}'
 ```
 
 ---
@@ -71,11 +97,11 @@ python "$R/.qoder/scripts/autotest.py" quick --record '{"Q-1":"pass","Q-2":"fail
 用户明确给了任务名/回归某个任务时走这条。完整流程见 skill。
 
 ```bash
-python "$R/.qoder/scripts/task.py" list                     # 确认任务
-python "$R/.qoder/scripts/autotest.py" generate <task>      # 生成骨架
+python "$R/.qoder/scripts/task/task.py" list                     # 确认任务
+python "$R/.qoder/scripts/test/autotest.py" generate <task>      # 生成骨架
 # AI 读任务 PRD「验收标准」补全 steps/expected(真实数据用 {{ask:}})
-python "$R/.qoder/scripts/autotest.py" run <task>           # 注入+出执行计划
-python "$R/.qoder/scripts/autotest.py" run <task> --record '{"..":"pass"}'  # 回收结果
+python "$R/.qoder/scripts/test/autotest.py" run <task>           # 注入+出执行计划
+python "$R/.qoder/scripts/test/autotest.py" run <task> --record '{"..":"pass"}'  # 回收结果
 ```
 
 ---

package/templates/qoder/config.yaml

@@ -1,27 +1,43 @@
 # 角色定义 (与 kg.py ROLE_SECTIONS 的 5 角色对齐)
 # commands: 该角色建议主用的命令 (软引导, 不拦截 —— 任何角色都能跑任何命令)
-# permissions: 声明式权限 (当前未强制执行, 留作未来硬权限墙)
+# permissions: 声明式权限 (遗留字段, 向后兼容)
+#
+# ★ 能力边界 (v3.0+ 解耦核心) ★
+# can_produce: 该角色允许产出的契约类型 (guard.py 强制, 越权则降级)
+# can_consume: 该角色允许读取/消费的能力 (越权则只读降级)
+# 契约类型必须与 contracts/schemas/*.schema.json 的 type 对齐:
+#   prd / prototype / spec / design-spec / code / unit-test / test-report / task
 roles:
   pm:
     name: 产品经理
     permissions: [create_task, write_prd, approve_prd, review_spec]
     commands: [wl-init, wl-insight, wl-prd-full, wl-prd-quick, wl-prd-review, wl-design, wl-task, wl-search, wl-status, wl-report]
+    can_produce: [prd, prototype]
+    can_consume: ["*"]              # PM 需读代码做现状分析
   design:
     name: 设计师
     permissions: [upload_design, approve_design]
     commands: [wl-init, wl-design, wl-search, wl-status]
+    can_produce: [design-spec, prototype]
+    can_consume: [prd, code-search]
   dev:
     name: 开发
     permissions: [write_spec, implement, commit, review_code]
     commands: [wl-init, wl-spec, wl-code, wl-test, wl-search, wl-commit, wl-status]
+    can_produce: [spec, code, unit-test]
+    can_consume: [prd, prototype, task]
   test:
     name: 测试
     permissions: [run_test, review_acceptance]
     commands: [wl-init, wl-test, wl-search, wl-status]
+    can_produce: [test-report, test-cases, unit-test]
+    can_consume: [prd, task, prototype]
   admin:
     name: 管理员
     permissions: [manage_index, manage_members, all]
     commands: [wl-init, wl-status, wl-search, wl-report]
+    can_produce: ["*"]
+    can_consume: ["*"]
 
 pipeline:
   workspace_dir: workspace

package/templates/qoder/hooks/session-start.py

@@ -62,17 +62,8 @@ def _recent_hook_errors(hours=24, limit=3):
     except Exception:
         return []
 
-# Injected as REAL OUTPUT below (a comment here would never reach the AI)
-CRITICAL_RULE = NL.join([
-    '## CRITICAL RULE',
-    'When user asks for /wl-prd-full, ALWAYS ask platform 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.',
-])
+# v3.0 M4: 删 CRITICAL_RULE (会话开始主动推销工作流铁律 → 非侵入式改造)
+# 平台询问逻辑保留在 wl-pipeline.md 规则1 (命令启动后才生效, 不在会话开头强推)
 
 
 def load_json_safe(path):
@@ -138,14 +129,14 @@ def get_index_info():
             recent = errors[-10:]  # 取最后 10 行检查
             if len(recent) >= 3:
                 lines.append('[WARN] hook 最近频繁失败 (%d 条错误), 详情见 .qoder/.runtime/hook-errors.log' % len(recent))
-                lines.append('  跑 python .qoder/scripts/init_doctor.py --fix 排查')
+                lines.append('  跑 python .qoder/scripts/setup/init_doctor.py --fix 排查')
     except OSError:
         pass
 
     lines.append('## Knowledge Graph')
     lines.append('MCP工具 (QoderWork自动调用): search_code / get_impact / coverage_matrix / get_workflow 等11个')
-    lines.append('  python .qoder/scripts/search_index.py <keyword> [--platform web|app]')
-    lines.append('  python .qoder/scripts/context_pack.py <keyword>   # 一次打包全部上下文')
+    lines.append('  python .qoder/scripts/io/search_index.py <keyword> [--platform web|app]')
+    lines.append('  python .qoder/scripts/io/context_pack.py <keyword>   # 一次打包全部上下文')
 
     # DuckDB 知识图谱状态检查
     # Read role from .developer file
@@ -192,15 +183,15 @@ def get_index_info():
             # 管理员/开发: 能构建
             if code_newer or db_age_hours > 168:  # 7天 = 168小时
                 lines.append('  [WARN] 知识图谱过期! 代码有新变更.')
-                lines.append('  → 管理员请运行: python .qoder/scripts/kg_build.py')
-                lines.append('  → 完成后: python .qoder/scripts/team_sync.py push (共享给团队)')
+                lines.append('  → 管理员请运行: python .qoder/scripts/kg/kg_build.py')
+                lines.append('  → 完成后: python .qoder/scripts/io/team_sync.py push (共享给团队)')
             else:
                 lines.append('  ✓ 知识图谱最新')
         else:
             # 非管理员: 只拉取
             if code_newer or db_age_hours > 168:
                 lines.append('  [WARN] 知识图谱可能过期.')
-                lines.append('  → 运行: python .qoder/scripts/team_sync.py pull (获取管理员最新构建)')
+                lines.append('  → 运行: python .qoder/scripts/io/team_sync.py pull (获取管理员最新构建)')
             else:
                 lines.append('  ✓ 知识图谱最新')
 
@@ -220,9 +211,9 @@ def get_index_info():
     else:
         lines.append('  [MISSING] kg.duckdb 不存在!')
         if role in ('admin', 'dev'):
-            lines.append('  → 运行: python .qoder/scripts/kg_build.py')
+            lines.append('  → 运行: python .qoder/scripts/kg/kg_build.py')
         else:
-            lines.append('  → 运行: python .qoder/scripts/team_sync.py pull')
+            lines.append('  → 运行: python .qoder/scripts/io/team_sync.py pull')
 
     return NL.join(lines)
 
@@ -235,8 +226,8 @@ def get_style_info():
 
     lines = []
     lines.append('## UI Style Index')
-    lines.append('Style search: python .qoder/scripts/search_index.py --style <table|form|modal>')
-    lines.append('Field search: python .qoder/scripts/search_index.py --field <name>')
+    lines.append('Style search: python .qoder/scripts/io/search_index.py --style <table|form|modal>')
+    lines.append('Field search: python .qoder/scripts/io/search_index.py --field <name>')
 
     for proj, d in meta.get('projects', {}).items():
         vue = d.get('vue_files', 0)
@@ -283,7 +274,6 @@ def main():
             parts.append('  [' + t['status'] + '] ' + t['name'] + ' - ' + t['title'])
 
     parts.append('')
-    parts.append(CRITICAL_RULE)
 
     idx_info = get_index_info()
     if idx_info:

package/templates/qoder/nul

@@ -0,0 +1,4 @@
+dir: cannot access '/s': No such file or directory
+dir: cannot access '/b': No such file or directory
+dir: cannot access '*.py': No such file or directory
+dir: cannot access '*.md': No such file or directory

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

@@ -34,51 +34,25 @@ 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 工具已含扩展）。
-
 ## 规则 1：PRD/原型需求必须先问平台（问了就停，不许边问边干）
 
 用户提出 PRD、原型、需求分析类请求时，第一步永远是问（绝不自动判断）：
@@ -99,8 +73,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/kg/kg.py context <业务关键词> --platform <web|app> [--role pm|design|dev|test]  # 一次取全(首选, 秒级)
+python .qoder/scripts/kg/search_index.py <关键词> --platform <web|app>      # 单项搜索
 ```
 kg.py context（= context_pack）一条命令返回：相关代码文件 + 同类页面示例 + 字段规格 +
 相关 PRD + 设计 Token + 图标参考 + 模板路径。kg.py 还有 12 个兄弟能力
@@ -154,19 +128,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/report/eval_prd.py <prd> [原型]` 必须 PASS (≥80%)
 - 发现确认采用批量方式（一个编号列表一轮确认），不要逐条问
 
 ## 规则 5：用户永不接触 git
 
-- 产出保存/发布后自动执行 `python .qoder/scripts/team_sync.py push`
-- 拉取团队最新：`python .qoder/scripts/team_sync.py pull`
+- 产出保存/发布后自动执行 `python .qoder/scripts/task/team_sync.py push`
+- 拉取团队最新：`python .qoder/scripts/task/team_sync.py pull`
 - 出现 SYNC_CONFLICT 由 AI 按提示自行解决，绝不让用户跑 git 命令
 
 ## 规则 6：环境问题找 doctor
 
 任何"索引不对/搜不到/环境坏了"类问题：
-`python .qoder/scripts/init_doctor.py`（加 --fix 自动修复，幂等增量，不会重头构建）
+`python .qoder/scripts/setup/init_doctor.py`（加 --fix 自动修复，幂等增量，不会重头构建）
 
 ## 规则 7：Repo Wiki 是补充知识源
 

package/templates/qoder/scripts/README.md

@@ -0,0 +1,139 @@
+# .qoder/scripts/ — 引擎脚本目录
+
+> 引擎代码, 由 `npx @hupan56/wlkj init/update` 生成, **不进团队 git** (Trellis 化)。
+> 用户不需要直接碰这些文件 — 通过 `/命令` 和 `npx` 间接调用。
+
+## 按职责分类 (命名前缀即分类)
+
+### 🔍 知识图谱 (`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` | 业务流程索引 |
+
+### 🩺 诊断检查 (`check_*`, 4 个)
+| 脚本 | 用途 |
+|------|------|
+| `check_mcp.py` | MCP 配置检查 |
+| `check_mcp_launch.py` | MCP 启动诊断 (根治黄色) |
+| `check_carriers.py` | 规则载体检查 (Qoder 全系列兼容) |
+| `check_qoderwork_consistency.py` | QoderWork 一致性 |
+
+### 🔎 代码提取 (`extract_*`, 3 个)
+| 脚本 | 用途 |
+|------|------|
+| `extract_routes.py` | 路由提取 |
+| `extract_routes_tree.py` | 路由树 |
+| `extract_api_params.py` | API 参数提取 |
+
+### 🧪 测试 (`autotest_*`, 3 个)
+| 脚本 | 用途 |
+|------|------|
+| `autotest.py` | 自动测试入口 |
+| `autotest_batch.py` | 批量测试 |
+| `autotest_run.py` | 单次执行 |
+
+### 🚀 初始化与身份 (`init_*`/`setup`/`role`/`identity`)
+| 脚本 | 用途 |
+|------|------|
+| `setup.py` | **一键就绪** (npx init 调的主体) |
+| `init_doctor.py` | 环境体检 + 自愈 + 身份注册 |
+| `install_qoderwork.py` | QoderWork 技能/MCP 安装 |
+| `role.py` | 角色管理 |
+| `repo_root.py` | 仓库根探测 |
+
+### 🔄 同步与任务
+| 脚本 | 用途 |
+|------|------|
+| `team_sync.py` | **团队同步** (pull/push, /wl-task finish 调) |
+| `git_sync.py` | 源码仓库同步 + PRD 归档 |
+| `task.py` | **任务系统** (create/list/start/finish) |
+| `syncgate.py` | 提交前零信任门禁 |
+| `sync_carriers.py` | 规则载体同步 |
+
+### 📊 评测与报告
+| 脚本 | 用途 |
+|------|------|
+| `eval_prd.py` | **PRD 质量门禁** (EVA, >=80% 才发布) |
+| `report.py` | 日报/周报生成 |
+| `status.py` | 项目状态 |
+| `benchmark.py` | 性能基准 |
+
+### 🔧 上下文与搜索
+| 脚本 | 用途 |
+|------|------|
+| `search_index.py` | **代码搜索** (/wl-search) |
+| `context_pack.py` | **一键上下文** (/wl-code, /wl-prd 用) |
+| `enrich_prompt.py` | prompt 增强 |
+| `fill_prototype.py` | 原型填充 |
+
+### 🎨 设计与原型
+| 脚本 | 用途 |
+|------|------|
+| `gen_design_doc.py` | 设计文档生成 |
+| `setup_lanhu.py` | 蓝湖配置 |
+| `lanhu_stdio_wrapper.py` | 蓝湖 MCP wrapper |
+
+### 🔌 MCP 服务 (`*_mcp_server.py`, 4 个)
+| 脚本 | 用途 |
+|------|------|
+| `mcp_launcher.py` | **MCP 统一启动器** (根治黄色) |
+| `kg_mcp_server.py` | 知识图谱 MCP |
+| `mysql_mcp_server.py` | MySQL MCP (只读) |
+| `zentao_mcp_server.py` | 禅道 MCP |
+
+### 📚 学习与知识沉淀
+| 脚本 | 用途 |
+|------|------|
+| `learn.py` | **learning 引擎** (埋点/反馈) |
+| `learn_aggregate.py` | 学习聚合 |
+
+### 🛠️ 其它工具
+| 脚本 | 用途 |
+|------|------|
+| `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 工具 |
+
+## 设计原则
+
+1. **命名即分类**: `kg_*` / `build_*` / `check_*` / `extract_*` / `autotest_*` 前缀 = 隐式分组
+2. **统一入口**: `kg.py` 是图谱统一入口, `task.py` 是任务统一入口 (不是 60 个并列入口)
+3. **common/ 共享**: 通用逻辑抽到 common/, 不重复
+4. **幂等**: 所有脚本可重复跑, 不重头再来 (见 init_doctor 的增量保证)
+5. **降级不崩**: 缺依赖/缺数据时优雅降级, 绝不 sys.exit 崩溃 (见 mcp_launcher)