@hupan56/wlkj 2.7.11 → 3.0.0

package/templates/qoder/skills/wl-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wl-test
 description: "测试工作流: 意图式用例 + Playwright MCP 执行 + 锚点缓存。触发: /wl-test 命令; 或自然语言里带'功能验证点'(如'测一下XX支不支持YY''验一下XX能不能ZZ''XX对不对')。纯随手看('打开XX页''看看登录')→不走本工作流。需确认(DANGEROUS)。"
-trigger: "/wl-test 命令; 或自然语言带具体功能验证点: '测一下XX支不支持YY''验一下XX能不能''XX功能对不对''回归XX'。仅'打开/看看/瞄一眼'等无验证点的不触发。"
+trigger: "user invokes /wl-* command explicitly"
 ---
 
 # wl-test — 测试工作流（/wl-test 命令 或 带功能验证点的自然语言触发）
@@ -32,9 +32,9 @@ trigger: "/wl-test 命令; 或自然语言带具体功能验证点: '测一下XX
 
 **① 必须用意图式格式（intent+anchor），禁止旧 action+selector 格式。**
 ```json
-// ✅ 对: 意图式, anchor 来自 recall
+// ✅ 对: 意图式, anchor 来自 recall 或 snapshot
 {"intent":"fill","desc":"账号输入框","value":"{{ask:登录账号}}","anchor":{"role":"textbox","name":"尊敬的管理员"}}
-// ❌ 错: 旧 action+CSS selector (脆弱, recall 锚点白沉淀)
+// ❌ 错: 旧 action+CSS selector (脆弱, 脆弱, recall 锚点白沉淀)
 {"action":"form_input","target":"input[placeholder*='账号']","value":"{{ask:测试账号}}"}
 ```
 
@@ -46,20 +46,48 @@ trigger: "/wl-test 命令; 或自然语言带具体功能验证点: '测一下XX
 **③ 用例 JSON 必须用 `--cases-file` 传文件，禁止内联 `--cases`。**
 ```bash
 # ✅ 对: 写文件再传路径(不截断)
-python "$R/.qoder/scripts/autotest.py" quick --cases-file <文件路径> --env test --platform web
+python "$R/.qoder/scripts/test/autotest.py" quick --cases-file <文件路径> --env test --platform web
 # ❌ 错: 内联(长JSON截断, 多条用例必丢)
-python "$R/.qoder/scripts/autotest.py" quick --cases '[{"case_id"...(超长)...}]'
+python "$R/.qoder/scripts/test/autotest.py" quick --cases '[{"case_id"...(超长)...}]'
 ```
 
-**④ 执行前必须 recall 查锚点。有锚点 → 直接填进 anchor，不调 LLM 匹配。**
+**④ 无锚点时必须先 snapshot 拿真实 anchor 再填，禁止预猜 CSS selector。**
 ```bash
-python "$R/.qoder/scripts/autotest.py" recall --url "/auth/login"
+# recall 空时 → 不预猜! 先 navigate + snapshot 拿到真实 a11y 树
+# 再把 snapshot 里看到的 role+name 填进 step.anchor
 ```
-recall 返回的每个锚点，直接用它的 role+name 填进 step.anchor。这步是**省模型调用**的根本。
+- recall 命中 → 直接用 recall 的 anchor（确定性命中，零 LLM）
+- recall 空（首次）→ **navigate + browser_snapshot → 从 a11y 树提取 anchor → 填进用例**
+- **绝不**在没看页面的情况下凭"登录页一般有账号框"去猜 selector
 
-**⑤ 验证码必须用 Playwright MCP 的 `browser_take_screenshot` 截图 → QoderWork 自带视觉识别 → `browser_type` 填入 → 删图。禁止用 Computer 截图（实测反复失败超时）、禁止瞎蒙默认值。**
-- `{{ask:}}` 占位符里**绝不出现验证码**——验证码不存个人文档，执行时实时识别。
-- 截图工具不可用时 → 用 JS 提取 base64 → 存图 → Read 看 → 算答案 → 填入 → **删图**。
+**⑤ URL 必须写成 `{{base_url}}/auth/login`（带斜杠）。**
+- base_url 已去尾斜杠（脚本行为），写 `{{base_url}}auth/login` 会拼成 `https://xxxauth/login` 坏地址。
+- 脚本会检测并告警，但 AI 应一次写对。
+
+**⑥ recall 的 `--url` 必须用相对路径（无前导斜杠），避开 Git-bash/MSYS 路径转换坑。**
+```bash
+# ✅ 对: 相对路径 (MSYS 不转换)
+python "$R/.qoder/scripts/test/autotest.py" recall --url auth/login
+# ❌ 错: 前导斜杠会被 Windows Git-bash 转成 /D:/.../Git/auth/login
+python "$R/.qoder/scripts/test/autotest.py" recall --url /auth/login
+```
+（脚本已加 normalize 兜底能修这个，但别依赖兜底——直接写相对路径最干净。）
+
+**⑦ Playwright 工具一次性批量加载，snapshot 结果直接用内存 a11y 树，禁止写文件再 Read。**
+```bash
+# ✅ 对: 一个回合里并发加载所有要用的 browser_* 工具描述
+# ✅ 对: browser_snapshot 返回的 a11y 树直接在对话里读, 不落地文件
+# ❌ 错: 用一个加载一个(调用数翻倍); snapshot 写 yml 文件 → 再 Read 读回来(每步2次调用)
+```
+
+**⑧ 验证码识别一气呵成（截图→Read→type→删图），不绕路、不预先纠结。**
+- 登录用例里**不写**验证码 step——点登录后若弹验证码，执行循环自动走 5 步。
+- 固定 5 步连发：`browser_snapshot` 找验证码图 → `browser_take_screenshot` 存图 → Read 看图算 → `browser_type` 填 → 删图。
+- 验证码有时效（1-2分钟），所以**填完立刻点登录**，别在中间插别的操作。
+- 自识别连失 2 次才交人。
+
+**⑨ 用例必须一次生成全部（正向+异常），禁止一条一条生成。**
+- 每生成一条 = 一次模型调用。一次写完 Q-1(正向) + Q-2(异常) + ... 全部。
 
 ## ⚙️ 自取上下文（Quest / QoderWork 无 hook 注入，必须自读）
 
@@ -70,8 +98,8 @@ recall 返回的每个锚点，直接用它的 role+name 填进 step.anchor。
 > R=$(python ~/.qoderwork/repo_root.py 2>/dev/null) || R=.
 > ```
 > `repo_root.py` 从 `~/.qoderwork/mcp.json` 反推仓库根；失败回退 `.`（IDE/CLI 工作目录即仓库根）。
-> **读到 1 次记住，后续所有脚本统一用 `python "$R/.qoder/scripts/xxx.py"`，不要再搜！**
-> 如果 `repo_root.py` 报错找不到，先在仓库里跑 `python "$R/.qoder/scripts/install_qoderwork.py"`。
+> **读到 1 次记住，后续所有脚本统一用 `python "$R/.qoder/scripts/<子包>/<脚本>.py"`（子包: kg/build/test/setup/io），不要再搜！**
+> 如果 `repo_root.py` 报错找不到，先在仓库里跑 `python "$R/.qoder/scripts/setup/install_qoderwork.py"`。
 
 - `<R>/.qoder/.developer` — 当前开发者
 - `<R>/.qoder/config.yaml` 的 `autotest:` 段 — 环境/域名
@@ -84,7 +112,7 @@ recall 返回的每个锚点，直接用它的 role+name 填进 step.anchor。
 
 **唯一正确做法**——1 条命令查 MySQL sys_menu 真实路由：
 ```bash
-python "$R/.qoder/scripts/search_index.py" --routes 保险
+python "$R/.qoder/scripts/kg/search_index.py" --routes 保险
 # → 保险管理 -> /veh/vehicle/vehAffair/insurance
 ```
 - 数据来自 MySQL `sys_menu` 表（后台动态菜单，**唯一事实源**）
@@ -131,12 +159,12 @@ coverage_matrix()
 
 **不要任务/PRD。零搜索。** 用意图+锚点格式（A方案），observe-act-extract 执行。
 
-### Step 0：先 recall 查有没有现成锚点（跳过 LLM）
+### Step 0：recall 查锚点（用相对 URL，避开 MSYS 坑）
 ```bash
-python "$R/.qoder/scripts/autotest.py" recall --url "/auth/login"
+python "$R/.qoder/scripts/test/autotest.py" recall --url auth/login
 ```
 - **有锚点** → 生成用例时直接把 anchor 填进 step（确定性命中，快、零 LLM）
-- **无锚点** → 用意图式生成（首次会调 LLM 匹配，执行后 learn 沉淀，下次就快）
+- **无锚点（首次）** → **先 navigate + snapshot 拿真实锚点，再生成用例**（见 Step 0.6）
 
 ### Step 0.5：用知识图谱 MCP 增强用例（1 次调用取全）
 
@@ -146,15 +174,42 @@ python "$R/.qoder/scripts/autotest.py" recall --url "/auth/login"
 
 > 图谱无数据 → 跳过，按通用模式生成。**不要再单独调 feature_overview**（信息重叠，浪费一轮）。
 
+### Step 0.6：recall 空时，先 snapshot 拿真实锚点（🔴 首次跑关键，禁止预猜 selector）
+
+**recall 返回空 = 第一次测这页。此时绝不能凭"登录页一般有账号框"去猜 CSS selector。**
+正确做法：先用 Playwright 打开页面拿一次 a11y 树，从里面提取真实 anchor：
+
+```bash
+# 1. 批量加载要用的 browser_* 工具描述 (一次并发, 别一个一个加载)
+#    最少: browser_navigate, browser_snapshot, browser_click, browser_type,
+#          browser_take_screenshot, browser_evaluate
+
+# 2. browser_navigate 到 {{base_url}}/auth/login (base_url 从 config 取, 已去尾斜杠)
+# 3. browser_snapshot 一次 → 拿到 a11y 树 (直接读对话里的内容, 不写文件)
+```
+snapshot 返回形如：
+```
+- textbox "尊敬的管理员，请输入您的账号" [ref=e36]
+- textbox "请输入您的密码" [ref=e42]
+- textbox "验证码" [ref=e56]
+- button "login" [ref=e64]: 登录
+```
+**把这里的 role+name 直接填进用例的 anchor**：
+```json
+{"intent":"fill","desc":"账号输入框","value":"{{ask:登录账号}}","anchor":{"role":"textbox","name":"尊敬的管理员，请输入您的账号"}}
+```
+> 这一步把"首次跑要靠 LLM 兜底匹配"变成"确定性命中"，是省调用的根本。
+> 拿到锚点后继续 Step 1。
+
 **🎯 知道页面名/URL 时，AI 先查按钮+接口画像（最精准，1 条命令拿到所有交互点）：**
 ```bash
-python "$R/.qoder/scripts/autotest.py" page --kw 保险        # 按业务名查
-python "$R/.qoder/scripts/autotest.py" page --url /veh/insurance  # 按URL查
+python "$R/.qoder/scripts/test/autotest.py" page --kw 保险        # 按业务名查
+python "$R/.qoder/scripts/test/autotest.py" page --url /veh/insurance  # 按URL查
 ```
 （这是 AI 在 `/wl-test` 流程内部自动调用的工具，**用户只用 `/wl-test`，不碰此命令**。）
 输出每个按钮的 handler + 调用接口 + HTTP 方法 + 置信度，**直接对应到用例的 click→assert 断言点**。开发 `finish` 任务时也会自动生成 `test-handoff.md`，内容同此画像——交接场景直接读那份即可，不必重查。
 
-### Step 1：AI 据用户描述 + 图谱信息生成意图式用例 JSON（**一次生成全部用例**）
+### Step 1：AI 据用户描述 + 锚点生成意图式用例 JSON（**一次生成全部用例**）
 **意图+锚点格式**（A方案核心）：用 `intent` 表达"做什么"，用 `anchor` 精确定位（有锚点则确定性命中，无则 LLM 兜底）。
 ```json
 [{"case_id":"Q-1","title":"正确账号密码登录","platform":"web","env":"test",
@@ -181,7 +236,7 @@ python "$R/.qoder/scripts/autotest.py" page --url /veh/insurance  # 按URL查
 # AI 先写文件:
 #   写 workspace/members/{dev}/drafts/_autotest-cases.json
 # 再调:
-python "$R/.qoder/scripts/autotest.py" quick \
+python "$R/.qoder/scripts/test/autotest.py" quick \
   --cases-file workspace/members/{dev}/drafts/_autotest-cases.json \
   --desc "<用户描述>" --platform <web|app>
 ```
@@ -220,32 +275,40 @@ python "$R/.qoder/scripts/autotest.py" quick \
 > ⚠️ **导航是 `browser_navigate`（不是 BrowserNavigate / navigate）**。
 > 调用前对照上面清单，名字写错 = 工具不存在 = 整个测试失败。
 
+**🔴 调用效率（实测:一次登录测试不该超过 12 步调用）：**
+1. **工具批量加载**：进入执行阶段时，在一个回合里并发加载所有要用的 `browser_*` 工具描述（navigate/snapshot/click/type/take_screenshot/evaluate），不要用一个加载一个。
+2. **snapshot 不落地**：`browser_snapshot` 返回的 a11y 树**直接在对话里读**，禁止写 yml 文件再 Read 回来（每步省一次调用）。
+3. **有 anchor 连发不思考**：锚点已确定，`browser_type`/`browser_click` 直接按 role+name 操作，零模型调用。
+
 **对每个 step（用 Playwright MCP 工具，连着发，别每步深度思考）：**
 1. **intent=goto** → `browser_navigate`（1 次）
-2. **首次到新页面** → `browser_snapshot` **1 次**拿 a11y 树
+2. **首次到新页面** → `browser_snapshot` **1 次**拿 a11y 树（直接读，不写文件）
 3. **intent=click/fill**（锚点优先，**确定性匹配不思考**）：
    - **有 anchor** → snapshot 结果里按 `role+name`/`placeholder` 直接匹配 → 拿到元素 → `browser_type`/`browser_click`（**零模型调用，连着发**）
    - **无 anchor** → 用 `desc` 语义匹配（1 次模型调用）
    - 匹配失败 → self-heal：重新 `browser_snapshot` + 重试，最多 2 次
-4. **intent=extract** → 看 URL / read_page 判断（1 次模型调用）
+4. **intent=extract** → 看 URL / 当前页面判断（1 次模型调用）
 5. **intent=ask_human** → 暂停等人
 6. **intent=assert** → 确定性校验（零模型调用）
 
-### Step 3.5：验证码识别一条龙（数学题）
+### Step 3.5：验证码识别一条龙（数学题）— 一气呵成，别绕路
 
 > **🔴 验证码铁律（实测反复踩坑）：**
 > - **禁止用 Computer 截图 / zoom 截验证码**——实测反复失败、超时、浪费 5-6 步。
 > - **禁止填默认值/瞎蒙**（如 000000）。
 > - **唯一正确路径**：JS 提取 base64 → 存图 → Read 看 → 算答案 → 填 → 删图。固定 5 步，不偏离。
+> - **验证码有时效（1-2 分钟），所以填完立刻点登录，中间别插别的操作。**
 
-按这个**固定顺序**一次走完（用 Playwright MCP 工具，约 30 秒）：
-1. **`browser_snapshot`** 看页面元素，找到验证码图片元素
+按这个**固定顺序**一次走完（用 Playwright MCP 工具，约 30 秒，**连发不思考**）：
+1. **`browser_snapshot`**（如果刚才已经 snapshot 过且页面没变，可跳过）看页面元素，找到验证码图片元素
 2. **`browser_take_screenshot`** 截验证码图片 → 存临时文件（稳定，不像 Computer 截图会失败）
 3. **Read 工具看图 → 算出答案**（QoderWork 自带视觉，1 次模型调用，数学题识别率高）
 4. **`browser_type`** 填答案到验证码输入框
-5. **删掉临时图片**（bash `del _captcha.png`）
-> 验证码有时效（1-2 分钟），所以要快。过期了刷新重走一遍。
+5. **立刻 `browser_click` 点登录**（验证码刚填、还没过期，抓住窗口）
+6. **删掉临时图片**（bash `del _captcha.png`）
+> 验证码过期了（提示"验证码已失效"）→ 别纠结，直接刷新重走 1-5 步。
 > 识别完**必须删图**，不留垃圾。
+> 自识别连续失败 2 次或明显是短信/扫码类 → 才交人（见 Step A 铁律⑤）。
 
 ### Step 4：回收结果 + 自学习沉淀（🔴 必须，不做完不出报告）
 
@@ -254,7 +317,7 @@ python "$R/.qoder/scripts/autotest.py" quick \
 
 **执行方式**：把测试结果 + 测试中 `browser_snapshot` 看到的页面元素一起回传：
 ```bash
-python "$R/.qoder/scripts/autotest.py" quick \
+python "$R/.qoder/scripts/test/autotest.py" quick \
   --cases-file <之前的cases文件> \
   --record '{"Q-1":"pass","Q-2":"pass","Q-3":"pass"}' \
   --page-json '{"url":"/veh/vehicle/vehAffair/insurance","elements":[{"role":"textbox","name":"车牌号"},{"role":"button","name":"搜索"},{"role":"button","name":"新增"}]}'
@@ -275,11 +338,11 @@ python "$R/.qoder/scripts/autotest.py" quick \
 ## browser 基于任务的浏览器测试（用户明确给了任务名时）
 
 ```bash
-python "$R/.qoder/scripts/task.py" list                     # 确认任务存在
-python "$R/.qoder/scripts/autotest.py" generate <task>      # 生成骨架到 autotest-cases.jsonl
+python "$R/.qoder/scripts/task/task.py" list                     # 确认任务存在
+python "$R/.qoder/scripts/test/autotest.py" generate <task>      # 生成骨架到 autotest-cases.jsonl
 # 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"}'  # 回收结果
 ```
 
 **回归测试增强（图谱 MCP）**：测接口改动时，用 `get_impact` 查影响范围，自动覆盖受影响页面：
@@ -307,9 +370,9 @@ JUnit 测试（Mock + MockMvc，Given-When-Then，`@DisplayName`，AssertJ）→
   域名才放 config（全团队一致）。账号密码每人不同 → 个人文档。
 - **个人文档**：`workspace/members/{你的名字}/autotest-data.yaml`（gitignored，永不 push）
 ```bash
-python "$R/.qoder/scripts/autotest.py" init-data                          # 生成模板
-python "$R/.qoder/scripts/autotest.py" set-data 登录账号 test --env test   # 填(按环境/平台分块)
-python "$R/.qoder/scripts/autotest.py" list-data --env test                # 查看(密码脱敏)
+python "$R/.qoder/scripts/test/autotest.py" init-data                          # 生成模板
+python "$R/.qoder/scripts/test/autotest.py" set-data 登录账号 test --env test   # 填(按环境/平台分块)
+python "$R/.qoder/scripts/test/autotest.py" list-data --env test                # 查看(密码脱敏)
 ```
 run/quick 时按 env/platform 自动取最精确的值；`--data` 可临时覆盖。
 
@@ -319,7 +382,7 @@ run/quick 时按 env/platform 自动取最精确的值；`--data` 可临时覆
 
 **Step A：查登录态**
 ```bash
-python "$R/.qoder/scripts/autotest.py" login-state show
+python "$R/.qoder/scripts/test/autotest.py" login-state show
 ```
 
 **Step B：按登录态决定行为**
@@ -340,8 +403,8 @@ python "$R/.qoder/scripts/autotest.py" login-state show
 
 ```bash
 # 手动操作（一般不用，AI 会自动）:
-python "$R/.qoder/scripts/autotest.py" login-state mark --env pre --platform web   # 标记已登录
-python "$R/.qoder/scripts/autotest.py" login-state clear --env pre                 # 清除(强制重登录)
+python "$R/.qoder/scripts/test/autotest.py" login-state mark --env pre --platform web   # 标记已登录
+python "$R/.qoder/scripts/test/autotest.py" login-state clear --env pre                 # 清除(强制重登录)
 ```
 
 ## 🧩 QoderWork 增强：浏览器自动执行（可选 · 无连接器则自动回退）

package/templates/root/AGENTS.md

@@ -1,4 +1,19 @@
-# QODER Pipeline
+# QODER Pipeline
+
+## 🏗️ 架构: 引擎与数据分离 (Trellis 化)
+
+`.qoder/` 一分为二 (v2.8.0+):
+
+| 类别 | 内容 | 来源 | 进团队 git? |
+|------|------|------|------------|
+| **引擎代码** | `.qoder/scripts/` `skills/` `commands/` `agents/` `contracts/` `hooks/` `templates/` `rules/` | `npx @hupan56/wlkj init/update` 生成 | ❌ gitignore |
+| **团队数据** | `.qoder/config.yaml` `config.toml` `settings.json` `learning/` + `data/` (kg.duckdb/索引) + `workspace/` (PRD/任务) | git 跟踪, 团队共享 | ✅ |
+
+- 引擎代码**只由 npm 包生成**, 不再进团队 git → 彻底消除"引擎更新污染团队 git"和"新机 init 产生 unrelated histories"。
+- Qoder 全系列仍读 `.qoder/` (路径不变), 只是引擎来源从 git 变成 npm 生成。
+- 老团队升级 (管理员跑一次): `npx @hupan56/wlkj migrate`, 然后团队成员各自 `npx @hupan56/wlkj update`。
+
+---
 
 ## ⚠️ CRITICAL RULE #1: ALWAYS ASK PLATFORM FIRST
 
@@ -33,41 +48,25 @@ Examples:
 - "保险定时任务" -> /wl-search insurance
 - "薪资API" -> /wl-search --api salary
 
-## CRITICAL RULE #2.5: 自然语言 → 技能 路由（Quest / QoderWork 入口）
-
-Quest 与 QoderWork 没有斜杠命令，AI 必须按下表把用户自然语言映射到
-`.qoder/skills/` 下的技能（Qoder IDE 编辑器与 CLI 用 `/wl-*` 命令，同样适用）：
-
-| 用户说什么 | 触发 skill |
-|------------|-----------|
-| "写个需求""生成PRD""做个原型""新模块" | /wl-prd-full（完整档，正经需求）|
-| "加个字段""加个导出按钮""改下文案""小改动" | /wl-prd-quick（快档，零星需求）|
-| "评审PRD""检查需求文档""PRD质量怎么样""这个PRD合格吗" | /wl-prd-review（评审 PRD 质量）|
-| "录入设计稿""Figma稿录入""把这个设计录入" | wl-design import (design-import) |
-| "按设计出原型""按设计师规范出原型" | wl-design generate (prototype-generator) |
-| "评审原型""设计稿看一下""检查交互稿" | wl-design review (design-review) |
-| "查一下""代码在哪""搜保险""考勤API" | wl-search |
-| "建任务""排优先级""任务做完了" | wl-task |
-| "项目怎么样""进度""健康度" | wl-status |
-| "写日报""周报""我干了啥" | wl-report |
-| "调研""竞品""对标""规划""路线图""接下来做什么""发现个机会""探讨需求" | wl-insight（探索站）|
-| "生成规格""写spec" | spec-generator |
-| "开始写代码""按规格实现" | spec-coder |
-| "测一下XX支不支持YY""验一下XX能不能""XX功能对不对""跑测试用例""回归测试" | /wl-test（测试工作流, 命令或带验证点的自然语言触发） |
-| "写单元测试""补单测" | /wl-test unit（test-generator） |
-| "评审PRD" | prd-review |
-| "提交代码""commit""推上去" | wl-commit |
-| "初始化""换开发者""环境检查" | wl-init |
-
-找不到明确匹配 → 先问用户意图，不要乱跑。
+## CRITICAL RULE #2.5: 触发方式（非侵入式 — v3.0）
+
+工作流**只在显式调用时启动**，不主动干预普通对话。
+
+**两种触发方式（且仅此两种）：**
+1. **斜杠命令**：`/wl-prd-full` `/wl-search` `/wl-req` 等 → 启动工作流
+2. **npx**：`npx @hupan56/wlkj init/update` → 安装/同步
+
+**自然语言不触发工作流。** 用户说"写个需求""查下代码"等，AI 正常回答，不自动拉入工作流。
+（工作流启动后的过程内交互 — 如选平台、确认需求 — 仍可用自然语言。）
+
 注意区分："同步/保存产出" = team_sync（push）；"提交/commit 代码" = wl-commit。
 
 ## CRITICAL RULE #3: User NEVER touches git
 
 PMs on this team do not know git. ALL git operations are invisible:
 - After any publish/save action (/wl-prd-full publish, /wl-task create/finish,
-  /wl-report save), run: `python .qoder/scripts/team_sync.py push`
-- To get teammates' latest work: `python .qoder/scripts/team_sync.py pull`
+  /wl-report save), run: `python .qoder/scripts/task/team_sync.py push`
+- To get teammates' latest work: `python .qoder/scripts/task/team_sync.py pull`
 - If team_sync prints SYNC_CONFLICT, YOU (the AI) resolve the conflict
   yourself (it tells you the commands). NEVER ask the user to run git.
 - When the user says 同步/保存/提交 in natural language -> team_sync, not raw git.
@@ -126,7 +125,7 @@ app/mobile/h5/移动端 -> Carmg-H5
 
 3 projects: Carmg-H5(1378 files), fywl-ics(8973 files, 3903 APIs), fywl-ui(3270 files)
 Search: /wl-search <keyword> returns compact results (~200 bytes)
-Weekly sync: python .qoder/scripts/git_sync.py
+Weekly sync: python .qoder/scripts/task/git_sync.py
 
 ### MCP Servers (QoderWork / Qoder IDE)
 注册在 `~/.qoderwork/mcp.json`，setup.py 一键配齐：
@@ -135,7 +134,7 @@ Weekly sync: python .qoder/scripts/git_sync.py
 - `qoder-mysql` (stdio) — 只读查真实数据库结构/数据。自动拉起。
 - `lanhu` (STDIO) — 蓝湖设计稿直读，设计师发链接 AI 提取颜色/尺寸/字体/切图。
   **STDIO 模式：开 QoderWork 自动起、关自动停**（QoderWork 原生进程管理，无需手动 start）。
-  cookie 按角色隔离（UI 能改稿/PM 只读）：wrapper 读当前 `.developer` → 该角色的 `workspace/members/{dev}/.secrets/lanhu.env`（gitignored）。换角色改 `.developer` + 配该角色 cookie → 重启 QoderWork。首次配置跑 `python .qoder/scripts/setup_lanhu.py`。
+  cookie 按角色隔离（UI 能改稿/PM 只读）：wrapper 读当前 `.developer` → 该角色的 `workspace/members/{dev}/.secrets/lanhu.env`（gitignored）。换角色改 `.developer` + 配该角色 cookie → 重启 QoderWork。首次配置跑 `python .qoder/scripts/setup/setup_lanhu.py`。
 
 ### Style Index (Prototype Reference)
 UI patterns from Vue files: Tables(718), Forms(301), Detail(129), Dashboard(90)
@@ -144,10 +143,10 @@ Form components: Input(2262), Select(1049), ApiSelect(725), DatePicker(265)
 Field map: 2383 entries
 
 Style search:
-  python .qoder/scripts/search_index.py --style table/form/modal/dashboard
-  python .qoder/scripts/search_index.py --field <field_name>
-  python .qoder/scripts/search_index.py --components
-  python .qoder/scripts/search_index.py --vben    # Vben Admin CSS variables
+  python .qoder/scripts/kg/search_index.py --style table/form/modal/dashboard
+  python .qoder/scripts/kg/search_index.py --field <field_name>
+  python .qoder/scripts/kg/search_index.py --components
+  python .qoder/scripts/kg/search_index.py --vben    # Vben Admin CSS variables
 
 Prototype templates:
   .qoder/templates/prototype-web.html   # Web管理端 (Vben Admin + Ant Design)
@@ -182,7 +181,7 @@ Each product loads rules from a different carrier — keep them in sync:
 | QoderWork 桌面 Agent | 安装 .qoder/skills/ 下的技能 | 自然语言 -> skills |
 
 > 本流水线聚焦 Qoder 全系列，4 种载体功能等价。知识图谱 13 个能力（影响分析/
-> 覆盖矩阵/功能画像/业务流程/多跳遍历…）通过统一 CLI `python .qoder/scripts/kg.py`
+> 覆盖矩阵/功能画像/业务流程/多跳遍历…）通过统一 CLI `python .qoder/scripts/kg/kg.py`
 > 全系列触达；QoderWork 环境也可直接调 MCP 工具。
 
 ## QoderWork Integration: Optional Enhancement Only (Progressive Enhancement)
@@ -211,11 +210,11 @@ Each product loads rules from a different carrier — keep them in sync:
   macOS/Linux -> scripts/setup_weekly_cron.sh. Only ONE machine per team
   needs this; everyone else gets the graph via /wl-init's auto pull.
 - Environment problems of any kind -> run:
-  `python .qoder/scripts/init_doctor.py` (add --fix to auto-repair).
+  `python .qoder/scripts/setup/init_doctor.py` (add --fix to auto-repair).
 
 ## Fast Path: one call to get all context
 
-`python .qoder/scripts/context_pack.py <业务词> --platform <web|app>` returns
+`python .qoder/scripts/kg/context_pack.py <业务词> --platform <web|app>` returns
 code files + page examples + field specs + PRDs + APIs + style/icon pointers
 in ONE call. Use it FIRST; fall back to search_index.py for drill-down.
 
@@ -226,7 +225,7 @@ Web = Ant Design inline SVG, APP = Vant font icons. Emoji in a prototype = FAIL.
 
 ## Quality Gate (EVA)
 
-Before publishing any PRD: `python .qoder/scripts/eval_prd.py <prd> [prototype]`
+Before publishing any PRD: `python .qoder/scripts/report/eval_prd.py <prd> [prototype]`
 must PASS (>=80%). Metrics definition: data/docs/constitution/eva-metrics.md
 
 ## Permission Model

package/templates/qoder/hooks/inject-workflow-state.py

@@ -1,169 +0,0 @@
-# inject-workflow-state.py - Inject workflow state on every message
-import os, json, sys
-
-if sys.platform == 'win32':
-    try:
-        sys.stdout.reconfigure(encoding='utf-8')
-    except Exception:
-        pass
-
-NL = chr(10)
-BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-
-# mtime 缓存 (审计 H5: 每条用户消息都跑这个 hook, 缓存避免重复读盘)
-# 格式: {filepath: (mtime, parsed_value)}
-_CACHE = {}
-
-
-def _append_hook_error(log_path, line):
-    """写一行错误到 hook-errors.log, 超 100KB 截断保留最后 50KB (防无限膨胀)。
-
-    best-effort: 任何 IO 失败都静默 (不能让日志写入失败导致 hook 二次崩溃)。
-    """
-    from datetime import datetime
-    try:
-        os.makedirs(os.path.dirname(log_path), exist_ok=True)
-        # 轮转: 文件过大则截断
-        if os.path.isfile(log_path):
-            try:
-                if os.path.getsize(log_path) > 100 * 1024:
-                    with open(log_path, 'r', encoding='utf-8', errors='replace') as f:
-                        tail = f.read()[-50 * 1024:]
-                    with open(log_path, 'w', encoding='utf-8') as f:
-                        f.write(tail)
-            except OSError:
-                pass
-        with open(log_path, 'a', encoding='utf-8') as f:
-            f.write('[{}] inject-workflow-state: {}\n'.format(
-                datetime.now().strftime('%Y-%m-%d %H:%M:%S'), str(line)[:200]))
-    except Exception:
-        pass
-
-
-def _read_developer():
-    """读当前开发者名 (容错: UTF-8/GBK)."""
-    df = os.path.join(BASE, '.qoder', '.developer')
-    if not os.path.isfile(df):
-        return None
-    for enc in ('utf-8', 'gbk', 'utf-8-sig'):
-        try:
-            with open(df, encoding=enc) as f:
-                for line in f:
-                    line = line.strip()
-                    if line.startswith('name='):
-                        return line.split('=', 1)[1].strip()
-                    if line.startswith('name:') or ':' in line:
-                        # 容错 name: x 格式
-                        for sep in ('=', ':'):
-                            if sep in line:
-                                k, v = line.split(sep, 1)
-                                if k.strip() == 'name':
-                                    return v.strip()
-        except (OSError, UnicodeDecodeError):
-            continue
-    return None
-
-
-def _cached_read(path, parser):
-    """带 mtime 缓存的文件读。parser: callable(content_str) -> value."""
-    try:
-        mtime = os.path.getmtime(path)
-    except OSError:
-        return None
-    cached = _CACHE.get(path)
-    if cached and cached[0] == mtime:
-        return cached[1]
-    # 重读
-    for enc in ('utf-8', 'gbk', 'utf-8-sig'):
-        try:
-            with open(path, encoding=enc) as f:
-                content = f.read()
-            value = parser(content)
-            _CACHE[path] = (mtime, value)
-            return value
-        except (OSError, UnicodeDecodeError):
-            continue
-    return None
-
-
-def get_status():
-    # 优先读按开发者隔离的 current-task 文件
-    dev = _read_developer()
-    ct_candidates = []
-    if dev:
-        safe = ''.join(c for c in dev if c.isalnum() or c in '_-') or 'anon'
-        ct_candidates.append(os.path.join(BASE, '.qoder', '.runtime', 'current-task.' + safe))
-    ct_candidates.append(os.path.join(BASE, '.qoder', '.current-task'))  # 旧格式回退
-
-    rel = None
-    for ct in ct_candidates:
-        rel = _cached_read(ct, lambda c: c.strip() or None)
-        if rel:
-            break
-    if not rel:
-        return None, None
-
-    tj = os.path.join(BASE, rel, 'task.json')
-    if os.path.isfile(tj):
-        d = _cached_read(tj, lambda c: json.loads(c) if c.strip() else None)
-        if d:
-            return rel, d.get('status', 'unknown')
-    return rel, None
-
-
-# Statuses written by task.py: planning -> in_progress -> completed
-GUIDE = {
-    None: 'No active task. Use /wl-prd-full to start, or /wl-task create.',
-    'planning': 'Task in planning. Use /wl-prd-full to write the PRD, then /wl-task start.',
-    'in_progress': 'Dev in progress. /wl-spec to generate spec, /wl-code to implement.',
-    'completed': 'Task completed. /wl-task archive to archive, or start the next one.',
-}
-
-
-def main():
-    tp, st = get_status()
-    # Hook-2: 如果任务/状态没变, 输出空 (减少 token 消耗)
-    # 用 .runtime/.last-workflow-state 存上次输出, mtime 变了才重新注入
-    state_file = os.path.join(BASE, '.qoder', '.runtime', '.last-wf-state.txt')
-    current_sig = '{}|{}'.format(tp or '', st or '')
-    try:
-        os.makedirs(os.path.dirname(state_file), exist_ok=True)
-        if os.path.isfile(state_file):
-            last_sig = open(state_file, 'r', encoding='utf-8').read().strip()
-            if last_sig == current_sig:
-                # 状态没变, 不重复注入 (省 token), 但仍输出健康标记
-                # QoderWork 看不到任何输出时分不清"缓存跳过"还是"hook 没跑"
-                print('<!-- [hook-ok] inject-workflow-state: state unchanged (cached) -->')
-                return
-        open(state_file, 'w', encoding='utf-8').write(current_sig)
-    except OSError:
-        pass
-
-    g = GUIDE.get(st, 'Status "{}" - check task.json, expected planning/in_progress/completed.'.format(st))
-    parts = []
-    parts.append('<qoder-workflow>')
-    if tp:
-        parts.append('Task: ' + tp)
-    parts.append('Status: ' + str(st))
-    parts.append('Do: ' + g)
-    parts.append('</qoder-workflow>')
-    # Hook-1: 健康标记 — 与 session-start 一致, QoderWork 看不到说明 hook 没生效
-    parts.append('<!-- [hook-ok] inject-workflow-state hook ran -->')
-    print(NL.join(parts))
-
-
-if __name__ == '__main__':
-    try:
-        main()
-    except Exception as e:
-        # 落盘到日志 (stdout 一次性, 追溯用)
-        try:
-            from pathlib import Path
-            log_path = str(Path(__file__).resolve().parents[1] / '.runtime' / 'hook-errors.log')
-            _append_hook_error(log_path, str(e)[:200])
-        except Exception:
-            pass
-        print('<qoder-workflow>')
-        print('hook error: ' + str(e)[:200])
-        print('  (详情见 .qoder/.runtime/hook-errors.log)')
-        print('</qoder-workflow>')