@hupan56/wlkj 2.7.6 → 2.7.7

package/bin/cli.js

@@ -313,10 +313,24 @@ async function doInit(name, roleArg) {
       console.log(`  setup.py 未找到, 跳过自动初始化`);
     }
 
+  // === 6.4. 装 pip 依赖 (必须在配 MCP 之前!)
+  // 顺序关键: 先装依赖 → 再写 mcp.json → mcp.json 选到"装了依赖的Python" → MCP 秒绿
+  // 旧版 init 不装依赖直接配 mcp.json → 新机 MCP 全黄 (没装 duckdb/pymysql)
+  console.log(`\n--- Python 依赖安装 (失败自动切镜像) ---`);
+  const reqFileInit = path.join(cwd, "requirements.txt");
+  if (pyCmd && fs.existsSync(reqFileInit)) {
+    installPipDeps(pyCmd, reqFileInit);
+  } else if (!pyCmd) {
+    console.log(`  [跳过] Python 未装`);
+  } else {
+    console.log(`  [跳过] requirements.txt 不存在`);
+  }
+
   // === 6.5. 自动配 QoderWork MCP (新机关键: 否则 mcp.json 不生成, 4 个 MCP 全连不上) ===
-  // 复刻 doUpdate 第 7 步的逻辑: 拷 launcher + install_qoderwork --mcp-only
+  // 复刻 doUpdate 第 6 步的逻辑: 拷 launcher + install_qoderwork --mcp-only
   // setup.py 带了 --skip-qoderwork (offer_qoderwork 是交互式+装skill, 不适合 npx),
   // 这里用 --mcp-only (纯文件操作, 无交互) 把 mcp.json 配好
+  // 注意: 此时依赖已装好(6.4步), install_qoderwork 会选到装了依赖的 Python
   if (pyCmd) {
     console.log(`\n--- QoderWork MCP 自动配置 ---`);
     const home = process.env.USERPROFILE || require("os").homedir();
@@ -332,7 +346,7 @@ async function doInit(name, roleArg) {
       if (fs.existsSync(instScript)) {
         try {
           execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "inherit", timeout: 20000 });
-          console.log(`  [OK] mcp.json 已生成 (kg/mysql/lanhu/playwright, launcher 模式)`);
+          console.log(`  [OK] mcp.json 已生成 (选装了依赖的Python, MCP 不会黄)`);
         } catch (e) {
           console.log(`  [WARN] MCP 配置未完全成功 (不阻塞): ${(e.message || "").slice(0, 80)}`);
           console.log(`         可手动补: ${pyCmd} .qoder/scripts/install_qoderwork.py`);
@@ -557,13 +571,27 @@ function doUpdate() {
     console.log(`  git: 跳过(${(e.message || "").slice(0, 50)})`);
   }
 
-  // === 3. 刷新 QoderWork commands（强制覆盖已存在的）===
+  // === 3. 补装 pip 依赖 (必须在刷 mcp.json 之前!)
+  // 顺序很关键: 先装依赖 → 再写 mcp.json → mcp.json 能选到"已装依赖的Python"
+  // 旧版顺序反了(先写mcp.json再装依赖), 导致 mcp.json 指向没装依赖的Python → MCP 黄。
+  console.log(`\n--- Python 依赖补装 (失败自动切镜像) ---`);
+  const reqFile = path.join(cwd, "requirements.txt");
+  const pyCmd = detectPyCmd();
+  if (pyCmd && fs.existsSync(reqFile)) {
+    installPipDeps(pyCmd, reqFile);
+  } else if (!pyCmd) {
+    console.log(`  [跳过] Python 未装`);
+  } else {
+    console.log(`  [跳过] requirements.txt 不存在`);
+  }
+
+  // === 4. 刷新 QoderWork commands（强制覆盖已存在的）===
   runQoderWorkInstall(cwd, true);
 
-  // === 4. 写版本戳 ===
+  // === 5. 写版本戳 ===
   writeEngineVersion(cwd);
 
-  // === 5. 清理旧版废弃文件 ===
+  // === 5b. 清理旧版废弃文件 ===
   const OBSOLETE_FILES = [
     // 旧脚本(已替代)
     ".qoder/workflow.md",                      // 被 rules/wl-pipeline.md 替代
@@ -669,19 +697,8 @@ function doUpdate() {
     console.log(`  [清理] 废弃文件 ${cleaned} 个 + 过期缓存 ${cacheCleaned} 个`);
   }
 
-  // === 6. 补装 pip 依赖 (老用户升级时补齐, 走镜像兜底) ===
-  console.log(`\n--- Python 依赖补装 (失败自动切镜像) ---`);
-  const reqFile = path.join(cwd, "requirements.txt");
-  const pyCmd = detectPyCmd();
-  if (pyCmd && fs.existsSync(reqFile)) {
-    installPipDeps(pyCmd, reqFile);
-  } else if (!pyCmd) {
-    console.log(`  [跳过] Python 未装`);
-  } else {
-    console.log(`  [跳过] requirements.txt 不存在`);
-  }
-
-  // === 7. 刷新 launcher + mcp.json (老用户的可能是旧版/写死路径) ===
+  // === 6. 刷新 launcher + mcp.json (老用户的可能是旧版/写死路径) ===
+  // 注意: pip 依赖已在第3步装好, 此处 install_qoderwork 会选到"已装依赖的Python"写进 mcp.json
   try {
     const home = process.env.USERPROFILE || require("os").homedir();
     const launcherSrc = path.join(cwd, ".qoder", "scripts", "mcp_launcher.py");
@@ -696,12 +713,12 @@ function doUpdate() {
     if (pyCmd && fs.existsSync(instScript)) {
       try {
         execSync(`${pyCmd} "${instScript}" --mcp-only`, { stdio: "pipe", timeout: 15000 });
-        console.log(`  [OK] mcp.json 已刷新为动态路径`);
-      } catch { /* --mcp-only 可能不支持, 静默跳过 */ }
+        console.log(`  [OK] mcp.json 已刷新 (选装了依赖的Python, 避免MCP黄)`);
+      } catch (e) { /* --mcp-only 可能不支持, 静默跳过 */ }
     }
   } catch (e) { /* 刷新失败不阻塞升级 */ }
 
-  // === 8. 自检: 关键文件到底齐不齐 ===
+  // === 7. 自检: 关键文件到底齐不齐 ===
   console.log(`\n--- 自检 (关键文件验证) ---`);
   const checks = [
     ["requirements.txt", path.join(cwd, "requirements.txt"), "依赖清单(没它pip装不了)"],

package/package.json

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

package/templates/qoder/scripts/autotest.py

@@ -1525,6 +1525,35 @@ def cmd_recall(args):
     return 0
 
 
+# ---------------------------------------------------------------------------
+# 子命令: page (页面按钮+接口画像, 开发→测试交接物)
+# ---------------------------------------------------------------------------
+
+def cmd_page(args):
+    """查页面按钮+接口画像。薄入口, 实际逻辑在 page_probe.py。
+    数据来自知识图谱 traces 表, 无图谱则静默提示。
+    """
+    try:
+        import page_probe
+    except ImportError:
+        # 直接当脚本跑时, 补一下 sys.path
+        sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+        import page_probe
+
+    profile = page_probe.build_page_profile(keyword=getattr(args, 'kw', None),
+                                            url=getattr(args, 'url', None))
+    label = args.kw or args.url
+    print('## 页面画像: %s' % label)
+    print()
+    print(page_probe.render_profile_md(profile))
+    if profile.get('ok'):
+        n_pages = len(profile['pages'])
+        n_btns = sum(len(pg['buttons']) for pg in profile['pages'])
+        print()
+        print('[page] %d 个页面, %d 个交互点' % (n_pages, n_btns))
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # 子命令: report
 # ---------------------------------------------------------------------------
@@ -1683,6 +1712,13 @@ def build_parser():
     prc.add_argument('--url', required=True, help='页面 URL 或路径(如 /auth/login)')
     prc.set_defaults(func=cmd_recall)
 
+    # page: 查页面按钮+接口画像 (开发→测试交接物, 数据来自知识图谱 traces 表)
+    ppg = sub.add_parser('page', help='查页面按钮+接口画像(开发交接给测试,照着写用例)')
+    ppg_grp = ppg.add_mutually_exclusive_group(required=True)
+    ppg_grp.add_argument('--kw', help='业务关键词(如 保险 / 排班)')
+    ppg_grp.add_argument('--url', help='页面 URL 或路径关键词(如 /veh/insurance)')
+    ppg.set_defaults(func=cmd_page)
+
     return p
 
 

package/templates/qoder/scripts/install_qoderwork.py

@@ -315,21 +315,68 @@ def setup_lanhu_mcp(dry=False):
 
 
 def detect_python_command():
-    """探测本机可用的 python 命令名 (跨平台)。
-    Windows: py > python (无 python3); mac/linux: python3 > python。
-    返回命令名字符串 (在 PATH 里的), 失败返回 None。"""
-    for cand in (('py', '-3'), ('python3', None), ('python', None)):
-        name, extra = cand
+    """探测本机可用的 python 命令名 (跨平台), 用于写进 mcp.json 的 command 字段。
+
+    ⚠️ 关键约束: 返回值必须是单个可执行文件名/路径, 不能含空格或参数。
+    旧版返回 'py -3' (带参数), MCP 客户端 spawn('py -3', args) 会把
+    'py -3' 当字面文件名 → 找不到可执行文件 → MCP 显示黄色(连接失败)。
+
+    优先级 (Windows): python > py > python3
+      - 故意把 python 放 py 前面: 'python' 是单文件名, 最稳;
+        'py' 需要配合 -3 参数, 但我们返回纯 'py' (不带 -3) 也通常能用
+        (py 启动器会选默认版本)。
+    优先级 (mac/linux): python3 > python
+
+    返回: 命令名字符串 (如 'python' / 'py' / 'python3'), 失败返回 None。
+    """
+    if sys.platform == 'win32':
+        candidates = ('python', 'py', 'python3')
+    else:
+        candidates = ('python3', 'python')
+    for name in candidates:
         if not shutil.which(name):
             continue
-        cmd = [name] + ([extra] if extra else []) + ['--version']
         try:
-            r = subprocess.run(cmd, capture_output=True, text=True,
+            r = subprocess.run([name, '--version'], capture_output=True, text=True,
                                encoding='utf-8', errors='replace')
             if r.returncode == 0:
-                # 返回完整调用前缀 (py -3 / python3 / python)
-                return ' '.join(cmd[:-1])
-        except (OSError, subprocess.SubprocessError):
+                return name  # 纯命令名, 不带参数
+        except (OSError, subprocess.SubprocessProcessError):
+            continue
+    return None
+
+
+def find_python_with_core_deps():
+    """找一个装了核心依赖 (duckdb/pymysql/yaml/requests) 的 Python 可执行文件。
+
+    用于写 mcp.json: 如果某个 Python 已经装了核心依赖, 直接用它当 command,
+    launcher 启动后 _find_python_with_deps 会秒命中 sys.executable, 不用再遍历。
+    解决"多 Python 共存, 装到了 A 但 mcp.json 指向 B"的常见问题。
+
+    返回: python 可执行文件路径(str) 或 None(没找到装了依赖的)。
+    """
+    # 先测当前 Python (install_qoderwork 正在跑的这个)
+    for mod in ('duckdb', 'pymysql', 'yaml', 'requests'):
+        try:
+            __import__(mod)
+        except ImportError:
+            break
+    else:
+        # 当前 Python 四个核心依赖都有 → 用它
+        return sys.executable
+
+    # 当前 Python 没装全, 找其它 Python
+    for name in ('python', 'python3', 'py'):
+        p = shutil.which(name)
+        if not p or p == sys.executable:
+            continue
+        try:
+            r = subprocess.run(
+                [p, '-c', 'import duckdb, pymysql, yaml, requests'],
+                capture_output=True, timeout=8)
+            if r.returncode == 0:
+                return p
+        except (OSError, subprocess.SubprocessProcessError):
             continue
     return None
 
@@ -357,7 +404,15 @@ def rewrite_mcp_json_for_launcher():
     if not isinstance(servers, dict):
         return
 
-    py_cmd = detect_python_command() or "python"
+    # 选 Python 写进 mcp.json:
+    # 优先级 1: 找一个已经装了核心依赖(duckdb/pymysql/yaml/requests)的 Python
+    #   → 这样 launcher 启动后秒命中, MCP 秒绿
+    # 优先级 2: 任意可用 python 命令名 (launcher 内部会再找)
+    py_with_deps = find_python_with_core_deps()
+    if py_with_deps:
+        py_cmd = py_with_deps  # 完整路径, 最可靠
+    else:
+        py_cmd = detect_python_command() or "python"
     launcher = str(_HOME / ".qoderwork" / "mcp_launcher.py")
     # MCP 名 → launcher 子命令
     name_map = {
@@ -374,9 +429,14 @@ def rewrite_mcp_json_for_launcher():
             servers[srv] = {"command": py_cmd, "args": [launcher, sub]}
             changed = True
             continue
-        # 已是 launcher 模式?
+        # 已是 launcher 模式? 检查 command 是否需要更新 (Python 路径可能变了)
         args = entry.get("args", []) if isinstance(entry, dict) else []
         if args and any("mcp_launcher.py" in str(a) for a in args):
+            # launcher 模式, 但 command 可能指向旧的/错的 Python → 更新
+            old_cmd = entry.get("command", "") if isinstance(entry, dict) else ""
+            if old_cmd != py_cmd:
+                servers[srv] = {"command": py_cmd, "args": [launcher, sub]}
+                changed = True
             continue
         # mysql env 抽离到独立文件
         if srv == "qoder-mysql" and isinstance(entry, dict) and entry.get("env"):
@@ -396,7 +456,11 @@ def rewrite_mcp_json_for_launcher():
             QODERWORK_MCP_FILE.write_text(
                 json.dumps(cfg, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
             print(f"\n--- mcp.json 重写为 launcher 模式 ---")
-            print(f"  [UPD]  kg/mysql/lanhu → command={py_cmd}, args=[mcp_launcher.py, <名>]")
+            if py_with_deps:
+                print(f"  [UPD]  kg/mysql/zentao/lanhu → command={py_cmd} (装了依赖的Python)")
+            else:
+                print(f"  [UPD]  kg/mysql/zentao/lanhu → command={py_cmd}")
+            print(f"         args=[mcp_launcher.py, <名>] (launcher 内部找装依赖的 Python)")
             print(f"         不再写死仓库路径/venv路径, 跨机器通用")
         except OSError as e:
             print(f"  [ERR]  mcp.json 重写失败: {e}")

package/templates/qoder/scripts/mcp_launcher.py

@@ -216,13 +216,15 @@ def launch_kg(repo):
     server = repo / '.qoder' / 'scripts' / 'kg_mcp_server.py'
     if not server.is_file():
         _log(f'kg server 不存在: {server}')
-        sys.exit(1)
+        _launch_disabled_mcp('qoder-knowledge-graph',
+            'kg_mcp_server.py 缺失。跑 npx @hupan56/wlkj update')
+        return
     py = _find_python_with_deps('duckdb')
     if not py:
         _log('⚠️ 找不到装了 duckdb 的 Python! 跑: pip install duckdb')
         _log('  或: npx @hupan56/wlkj install-env (自动装依赖)')
         _launch_disabled_mcp('qoder-knowledge-graph',
-            'duckdb 未装。跑 pip install duckdb 或 npx @hupan56/wlkj install-env')
+            'duckdb 未装。跑 npx @hupan56/wlkj install-env (自动装依赖)')
         return
     _log(f'启动 kg (python={py})')
     os.execv(py, [py, str(server)])
@@ -368,26 +370,42 @@ LAUNCHERS = {
 
 
 def main():
+    # ⚠️ 关键: 任何失败都走 _launch_disabled_mcp(), 绝不 sys.exit()。
+    # sys.exit(1) 会让进程退出 → QoderWork 显示黄色(连接错误), 用户以为坏了。
+    # _launch_disabled_mcp() 启动一个干净 stdio 循环响应 initialize →
+    # QoderWork 显示绿色(已连接, 0工具), 用户知道是"未启用"而非"坏了"。
     if len(sys.argv) < 2:
-        _log('用法: mcp_launcher.py <kg|mysql|lanhu>')
+        _log('用法: mcp_launcher.py <kg|mysql|zentao|lanhu>')
         _log(f'  argv={sys.argv}')
-        sys.exit(1)
+        _launch_disabled_mcp('qoder-mcp',
+            '启动参数缺失: mcp_launcher.py <kg|mysql|zentao|lanhu>')
+        return
     name = sys.argv[1].lower()
 
     repo = find_repo_root()
     if not repo:
         _log('无法定位 QODER 仓库根。')
         _log('  方式1: 设环境变量 QODER_REPO=<仓库根>')
-        _log('  方式2: 重跑 python .qoder/scripts/install_qoderwork.py (写 .repo-root)')
+        _log('  方式2: 重跑 npx @hupan56/wlkj update (刷新 .repo-root)')
         _log('  方式3: 在仓库目录内运行')
-        sys.exit(1)
+        _launch_disabled_mcp(name,
+            '未定位到 QODER 仓库根。跑 npx @hupan56/wlkj update')
+        return
     _log(f'仓库根: {repo}')
 
     fn = LAUNCHERS.get(name)
     if not fn:
         _log(f'未知 MCP 名: {name} (支持: {list(LAUNCHERS)})')
-        sys.exit(1)
-    fn(repo)
+        _launch_disabled_mcp(name,
+            '未知 MCP 名: %s (支持: %s)' % (name, ', '.join(LAUNCHERS)))
+        return
+    try:
+        fn(repo)
+    except Exception as e:
+        # 启动函数抛异常也不能让进程死 (死=黄, 捕获=绿)
+        _log(f'启动 {name} 时异常: {e}')
+        _launch_disabled_mcp(name,
+            '%s MCP 启动异常: %s。跑 npx @hupan56/wlkj update' % (name, e))
 
 
 if __name__ == '__main__':

package/templates/qoder/scripts/page_probe.py

@@ -0,0 +1,459 @@
+# -*- coding: utf-8 -*-
+"""
+page_probe.py - 页面按钮+接口画像 (开发→测试交接物)
+
+从 DuckDB 知识图谱的 traces 表查"某个页面有哪些按钮、点按钮调哪个接口",
+输出一份测试人员能照着写用例的画像。解决痛点:开发写完代码交接给测试时,
+测试不用再满仓库找页面/按钮/接口。
+
+数据源: data/index/kg.duckdb 的 traces 表
+        (vue_file, button, handler, api_fn, endpoint, verb, confidence)
+URL→Vue 映射: data/index/menu-routes.json (sys_menu 真实路由)
+
+非侵入: 无 DuckDB / 无 traces 表 → 静默回退, 只 print 提示, 不报错。
+
+Usage (作为库):
+    from page_probe import build_page_profile, render_profile_md
+    md = render_profile_md(build_page_profile(keyword='保险'))
+
+Usage (CLI):
+    python .qoder/scripts/page_probe.py --kw 保险
+    python .qoder/scripts/page_probe.py --url /veh/vehicle/vehAffair/insurance
+"""
+
+import json
+import os
+import sys
+from typing import Optional, List, Dict, Any
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except (AttributeError, IOError):
+        pass
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _THIS_DIR not in sys.path:
+    sys.path.insert(0, _THIS_DIR)
+_COMMON = os.path.join(_THIS_DIR, 'common')
+if _COMMON not in sys.path:
+    sys.path.insert(0, _COMMON)
+
+from common.paths import get_repo_root  # noqa: E402
+
+
+# ============================================================
+# 路径定位
+# ============================================================
+
+def _kg_db_path(repo_root: Optional[str] = None) -> str:
+    rr = repo_root or str(get_repo_root())
+    return os.path.join(rr, 'data', 'index', 'kg.duckdb')
+
+
+def _menu_routes_path(repo_root: Optional[str] = None) -> str:
+    rr = repo_root or str(get_repo_root())
+    return os.path.join(rr, 'data', 'index', 'menu-routes.json')
+
+
+# ============================================================
+# DuckDB 查询 (只读, 失败静默回退)
+# ============================================================
+
+def _query_traces(vue_pattern: str, repo_root: Optional[str] = None) -> List[Dict[str, Any]]:
+    """查 traces 表里 vue_file 匹配 pattern 的所有按钮+接口。
+    pattern 用 LIKE (大小写不敏感, 因为下面转 lower)。
+    返回 [{vue_file, button, handler, api_fn, endpoint, verb, confidence}, ...]
+    无 DuckDB / 无表 / 查询失败 → 返回 [] (静默)。
+    """
+    try:
+        import duckdb
+    except ImportError:
+        return []
+    db = _kg_db_path(repo_root)
+    if not os.path.isfile(db):
+        return []
+    try:
+        con = duckdb.connect(db, read_only=True)
+        # 确认 traces 表存在
+        tables = [r[0] for r in con.execute(
+            "SELECT table_name FROM information_schema.tables WHERE table_schema='main'"
+        ).fetchall()]
+        if 'traces' not in tables:
+            con.close()
+            return []
+        # LIKE 匹配 (vue_file 路径里有正斜杠, pattern 用 % 通配)
+        pat = '%' + vue_pattern.lower() + '%'
+        rows = con.execute(
+            "SELECT vue_file, button, handler, api_fn, endpoint, verb, confidence "
+            "FROM traces WHERE lower(vue_file) LIKE ? "
+            "ORDER BY CASE confidence "
+            "  WHEN 'high' THEN 0 WHEN 'medium' THEN 1 WHEN 'low' THEN 2 "
+            "  WHEN 'deferred' THEN 3 ELSE 4 END, button",
+            [pat],
+        ).fetchall()
+        con.close()
+        return [
+            {
+                'vue_file': r[0], 'button': r[1], 'handler': r[2],
+                'api_fn': r[3], 'endpoint': r[4], 'verb': r[5], 'confidence': r[6],
+            }
+            for r in rows
+            if r[1]  # button 不能为空
+        ]
+    except Exception:
+        return []
+
+
+def _trace_stats(repo_root: Optional[str] = None) -> Optional[Dict[str, int]]:
+    """traces 表的置信度统计 (用于画像末尾标注覆盖率)。失败返回 None。"""
+    try:
+        import duckdb
+    except ImportError:
+        return None
+    db = _kg_db_path(repo_root)
+    if not os.path.isfile(db):
+        return None
+    try:
+        con = duckdb.connect(db, read_only=True)
+        rows = con.execute(
+            "SELECT confidence, COUNT(*) FROM traces GROUP BY confidence"
+        ).fetchall()
+        con.close()
+        stats = {r[0]: int(r[1]) for r in rows}
+        stats['total'] = sum(stats.values())
+        resolved = stats.get('high', 0) + stats.get('medium', 0) + stats.get('low', 0)
+        stats['resolved'] = resolved
+        return stats
+    except Exception:
+        return None
+
+
+# ============================================================
+# URL → Vue 文件映射 (走菜单路由表)
+# ============================================================
+
+def _load_menu_routes(repo_root: Optional[str] = None) -> List[Dict[str, Any]]:
+    """读 menu-routes.json。格式: {total, source, routes: [{name, path, component}, ...]}"""
+    p = _menu_routes_path(repo_root)
+    if not os.path.isfile(p):
+        return []
+    try:
+        for enc in ('utf-8', 'utf-8-sig', 'gbk'):
+            try:
+                with open(p, encoding=enc) as f:
+                    data = json.load(f)
+                # 支持 {routes: [...]} 包装和裸 [...] 两种
+                if isinstance(data, dict):
+                    data = data.get('routes') or []
+                return data if isinstance(data, list) else []
+            except (OSError, IOError, UnicodeDecodeError, json.JSONDecodeError):
+                continue
+    except Exception:
+        return []
+    return []
+
+
+def _match_routes(keyword: str, routes: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """用关键词匹配菜单 (name/path/component 任一包含关键词, 大小写不敏感)。
+    返回匹配的菜单项 [{name, path, component}], 按相关度排序。
+    """
+    kw = keyword.lower().strip()
+    if not kw:
+        return []
+    hits = []
+    for r in routes:
+        name = (r.get('name') or r.get('menu_name') or '').lower()
+        path = (r.get('path') or r.get('url') or '').lower()
+        comp = (r.get('component') or r.get('component_path') or '').lower()
+        # 完全匹配 name 优先级最高, 其次 path, 最后 component
+        score = 0
+        if kw == name:
+            score = 100
+        elif kw in name:
+            score = 80
+        elif kw in path:
+            score = 60
+        elif kw in comp:
+            score = 40
+        if score > 0:
+            hits.append((score, r))
+    hits.sort(key=lambda x: -x[0])
+    return [h[1] for h in hits[:8]]  # 最多 8 个, 避免过多
+
+
+def _route_to_vue_hint(route: Dict[str, Any]) -> str:
+    """从菜单项推断 Vue 文件路径关键词 (用于 traces 查询)。
+    component 字段常是 'veh/vehicle/vehAffair/insurance/index' 这种相对路径。
+    """
+    comp = route.get('component') or route.get('component_path') or ''
+    # 取 component 里最后两段 (模块名), 如 'insurance/record'
+    parts = [p for p in comp.replace('\\', '/').split('/') if p and p != 'index']
+    if len(parts) >= 2:
+        return '/'.join(parts[-2:])
+    if parts:
+        return parts[-1]
+    # fallback: 用 path 的最后一段
+    path = route.get('path') or route.get('url') or ''
+    seg = [p for p in path.split('/') if p]
+    return seg[-1] if seg else ''
+
+
+# ============================================================
+# 核心: 构建页面画像
+# ============================================================
+
+def build_page_profile(
+    keyword: Optional[str] = None,
+    url: Optional[str] = None,
+    repo_root: Optional[str] = None,
+) -> Dict[str, Any]:
+    """构建页面画像。
+    输入: keyword (业务名如"保险") 或 url (/veh/insurance)。
+    返回:
+        {
+          'ok': True/False,
+          'reason': '失败原因' (ok=False 时),
+          'pages': [
+            {
+              'name': '保险记录', 'url': '/veh/...', 'vue_hint': 'insurance/record',
+              'buttons': [{button, handler, endpoint, verb, confidence, resolved}, ...],
+              'vue_files': [实际命中的 vue 文件路径, ...]
+            }, ...
+          ],
+          'stats': {total, resolved, ...} or None
+        }
+    """
+    rr = repo_root or str(get_repo_root())
+
+    # 1. 定位页面 (URL 直查 / 关键词查路由表)
+    routes = _load_menu_routes(rr)
+    matched_pages = []  # [{name, url, vue_hint}]
+
+    if url:
+        # URL 模式: 在路由表里找 path 匹配的, 找不到就用 url 自身做 vue 关键词
+        url_lower = url.lower()
+        hit = None
+        for r in routes:
+            rp = (r.get('path') or r.get('url') or '').lower()
+            if rp and (rp == url_lower or url_lower in rp or rp in url_lower):
+                hit = r
+                break
+        if hit:
+            matched_pages.append({
+                'name': hit.get('name') or hit.get('menu_name') or url,
+                'url': hit.get('path') or hit.get('url') or url,
+                'vue_hint': _route_to_vue_hint(hit),
+            })
+        else:
+            # 路由表没命中, 用 url 最后一段做 vue 关键词
+            seg = [p for p in url.split('/') if p]
+            matched_pages.append({
+                'name': url, 'url': url,
+                'vue_hint': seg[-1] if seg else url.strip('/'),
+            })
+    elif keyword:
+        kw_hits = _match_routes(keyword, routes)
+        # 整词匹配不到 → 尝试关键词的前缀子串 (保险异常管理 → 保险/保险异常)
+        # 中文业务名常是"业务词+修饰词", 菜单名通常只含业务词主体
+        if not kw_hits and len(keyword) >= 3:
+            for sublen in (len(keyword) - 1, len(keyword) - 2, 2):
+                if sublen < 2:
+                    break
+                sub = keyword[:sublen]
+                sub_hits = _match_routes(sub, routes)
+                if sub_hits:
+                    kw_hits = sub_hits
+                    break
+        if kw_hits:
+            for r in kw_hits:
+                matched_pages.append({
+                    'name': r.get('name') or r.get('menu_name') or keyword,
+                    'url': r.get('path') or r.get('url') or '',
+                    'vue_hint': _route_to_vue_hint(r),
+                })
+        else:
+            # 路由表没命中, 直接用关键词做 vue 关键词 (traces 表里搜)
+            # 注意: 中文搜 vue 英文路径会失败, 但留着兜底 (英文关键词场景)
+            matched_pages.append({
+                'name': keyword, 'url': '', 'vue_hint': keyword,
+            })
+    else:
+        return {'ok': False, 'reason': '需要提供 --kw 或 --url', 'pages': [], 'stats': None}
+
+    # 2. 每个页面查 traces
+    pages_result = []
+    for pg in matched_pages:
+        hint = pg['vue_hint']
+        if not hint:
+            continue
+        traces = _query_traces(hint, rr)
+        if not traces:
+            continue
+        # 按 vue_file 分组 (一个 hint 可能命中多个 vue 文件, 各自列按钮)
+        by_vue = {}
+        for t in traces:
+            by_vue.setdefault(t['vue_file'], []).append(t)
+        for vue_file, btns in by_vue.items():
+            # 去重: 同一按钮名 + 同一 endpoint 只留一个
+            seen = set()
+            dedup = []
+            for b in btns:
+                key = (b['button'], b.get('endpoint') or '')
+                if key in seen:
+                    continue
+                seen.add(key)
+                dedup.append({
+                    'button': b['button'],
+                    'handler': b['handler'],
+                    'endpoint': b['endpoint'],
+                    'verb': b['verb'],
+                    'confidence': b['confidence'],
+                    'resolved': bool(b['endpoint'] and b['endpoint'] != 'None'),
+                })
+            pages_result.append({
+                'name': pg['name'],
+                'url': pg['url'],
+                'vue_file': vue_file,
+                'buttons': dedup,
+            })
+
+    stats = _trace_stats(rr)
+
+    if not pages_result:
+        return {
+            'ok': False,
+            'reason': '知识图谱里没找到匹配的页面按钮 (可能页面未被索引, 或关键词不准)',
+            'pages': [],
+            'stats': stats,
+        }
+    return {'ok': True, 'pages': pages_result, 'stats': stats}
+
+
+# ============================================================
+# 渲染: Markdown 画像 (给测试人员看 / 写入 test-handoff.md)
+# ============================================================
+
+def render_profile_md(profile: Dict[str, Any]) -> str:
+    """把画像渲染成 Markdown。"""
+    if not profile.get('ok'):
+        lines = ['> ' + (profile.get('reason') or '无画像数据')]
+        stats = profile.get('stats')
+        if stats:
+            lines.append('> (知识图谱 traces 覆盖率 %.0f%%, 未覆盖的交互需现场确认)'
+                         % (100.0 * stats.get('resolved', 0) / max(1, stats.get('total', 1))))
+        return '\n'.join(lines)
+
+    lines = []
+    total_buttons = 0
+    for pg in profile['pages']:
+        btns = pg['buttons']
+        total_buttons += len(btns)
+        lines.append('### %s' % pg['name'])
+        if pg.get('url'):
+            lines.append('路由: `%s`' % pg['url'])
+        # vue_file 只取 data/code/ 之后的相对路径, 更短
+        vf = pg.get('vue_file', '')
+        vf_rel = vf.split('/data/code/')[-1] if '/data/code/' in vf else vf
+        lines.append('Vue: `%s`' % vf_rel)
+        lines.append('')
+        resolved_btns = [b for b in btns if b['resolved']]
+        unresolved_btns = [b for b in btns if not b['resolved']]
+
+        if resolved_btns:
+            lines.append('| 按钮 | handler | 接口 | 方法 | 置信度 |')
+            lines.append('|------|---------|------|------|--------|')
+            for b in resolved_btns:
+                ep = b['endpoint'] or '?'
+                lines.append('| %s | %s | %s | %s | %s |' % (
+                    b['button'], b['handler'] or '?', ep, (b['verb'] or '?').upper(),
+                    b['confidence']))
+            lines.append('')
+
+        if unresolved_btns:
+            lines.append('**未解析到接口的按钮** (交互意图已知, 接口需现场确认):')
+            for b in unresolved_btns:
+                lines.append('- %s → %s (%s)' % (
+                    b['button'], b['handler'] or '?', b['confidence']))
+            lines.append('')
+
+        # 测试建议 (按按钮类型自动给提示)
+        lines.append('**测试建议:**')
+        sugg = _test_suggestions(btns)
+        for s in sugg:
+            lines.append('- %s' % s)
+        lines.append('')
+
+    stats = profile.get('stats')
+    if stats:
+        cov = 100.0 * stats.get('resolved', 0) / max(1, stats.get('total', 1))
+        lines.append('> 📊 知识图谱 traces 覆盖率 %.0f%% (resolved %d/%d)。'
+                     '未覆盖的按钮交互需现场点击确认。' % (cov, stats.get('resolved', 0), stats.get('total', 1)))
+    return '\n'.join(lines)
+
+
+def _test_suggestions(btns: List[Dict[str, Any]]) -> List[str]:
+    """根据按钮文本自动生成测试建议。"""
+    sugg = []
+    btn_texts = [b['button'] for b in btns]
+    btn_set = set(btn_texts)
+    # 按常见按钮语义给建议
+    if any(k in btn_set for k in ('新增', '添加', '新建', '创建')):
+        sugg.append('新增类: fill 表单必填项 → click 新增按钮 → 断言接口返回成功 + 列表出现新记录')
+    if any(k in btn_set for k in ('编辑', '修改', '更新')):
+        sugg.append('编辑类: 选中记录 → click 编辑 → 断言表单回填 + 保存后接口 UPDATE 调用')
+    if any(k in btn_set for k in ('删除', '移除')):
+        sugg.append('删除类: click 删除 → 二次确认弹窗 → 断言接口 DELETE 调用 + 列表记录消失')
+    if any(k in btn_set for k in ('导出', '下载')):
+        sugg.append('导出类: click 导出 → 断言下载触发 (或接口 export 调用 + 文件生成)')
+    if any(k in btn_set for k in ('查询', '搜索', '筛选', '检索')):
+        sugg.append('查询类: fill 筛选条件 → click 查询 → 断言列表按条件刷新')
+    if any(k in btn_set for k in ('导入', '上传')):
+        sugg.append('导入类: upload 文件 → 断言解析结果 + 接口 import 调用')
+    if any(k in btn_set for k in ('提交', '保存', '确认')):
+        sugg.append('提交类: 填完表单 → click 提交 → 断言接口成功 + 状态流转')
+    # 异常场景 (通用)
+    if sugg:
+        sugg.append('异常场景: 必填项留空提交 → 断言校验提示; 接口超时/失败 → 断言错误提示')
+    else:
+        sugg.append('通用: 逐个点击按钮 → 断言对应接口被调用 + 页面反馈正确')
+    return sugg
+
+
+# ============================================================
+# CLI
+# ============================================================
+
+def main(argv=None):
+    import argparse
+    p = argparse.ArgumentParser(
+        prog='page_probe.py',
+        description='查页面按钮+接口画像 (开发→测试交接物)',
+    )
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument('--kw', help='业务关键词 (如 保险 / 排班)')
+    g.add_argument('--url', help='页面 URL (如 /veh/vehicle/vehAffair/insurance)')
+    p.add_argument('--repo', default=None, help='仓库根目录 (默认自动检测)')
+    args = p.parse_args(argv)
+
+    profile = build_page_profile(keyword=args.kw, url=args.url, repo_root=args.repo)
+
+    if not profile.get('ok'):
+        print('## 页面画像: %s' % (args.kw or args.url))
+        print()
+        print(render_profile_md(profile))
+        print()
+        sys.exit(0)
+
+    print('## 页面画像: %s' % (args.kw or args.url))
+    print()
+    print(render_profile_md(profile))
+    n_pages = len(profile['pages'])
+    n_btns = sum(len(pg['buttons']) for pg in profile['pages'])
+    print()
+    print('[page] %d 个页面, %d 个交互点' % (n_pages, n_btns))
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/templates/qoder/scripts/task.py

@@ -335,6 +335,13 @@ def cmd_finish(args: argparse.Namespace) -> int:
     if task_json_path.is_file():
         run_task_hooks("after_finish", task_json_path, repo_root)
 
+    # 🧩 测试交接画像 (可选增强): finish 后在任务目录生成 test-handoff.md,
+    # 列出涉及的页面/按钮/接口, 供测试人员照着写用例。失败绝不阻塞任务完成。
+    try:
+        _generate_test_handoff(task_dir, repo_root)
+    except Exception as e:
+        print("[测试交接画像] 跳过 (不阻塞): " + str(e)[:80])
+
     # 埋点: 任务完成反馈给 learning 引擎
     if _finish_ctx:
         try:
@@ -350,6 +357,177 @@ def cmd_finish(args: argparse.Namespace) -> int:
     return 0
 
 
+def _extract_keywords(task_dir: Path) -> list:
+    """从任务目录名 + task.json 标题 + PRD 正文提取业务关键词。
+    返回去重的关键词列表 (用于 page_probe 查页面画像)。
+    """
+    kws = []
+    # 1. 任务目录名: 06-11-智能排班-环卫行业 → 智能排班, 环卫行业
+    dirname = task_dir.name
+    # 去掉日期前缀 (MM-DD- 或 MM-DD-)
+    parts = dirname.split('-')
+    # 找到第一个非纯数字段开始
+    biz_parts = []
+    started = False
+    for p in parts:
+        if not started:
+            if p.isdigit() and len(p) <= 2:
+                continue  # 跳过 MM, DD
+            started = True
+        if p.strip():
+            biz_parts.append(p.strip())
+    if biz_parts:
+        kws.append(''.join(biz_parts))  # 整体: 智能排班环卫行业
+        if len(biz_parts) > 1:
+            kws.extend(biz_parts)  # 分开: 智能排班, 环卫行业
+
+    # 2. task.json 的 title 字段
+    title = ''
+    try:
+        tj = task_dir / FILE_TASK_JSON
+        if tj.is_file():
+            data = load_task_json(task_dir) or {}
+            title = data.get('title', '')
+            if title and title not in kws:
+                kws.append(title)
+    except Exception:
+        pass
+
+    # 2.5 从标题/目录名里切出短业务词 (保险异常筛选 → 保险, 异常, 筛选)
+    # page_probe 用 LIKE 查 vue 路径, 短词命中率更高
+    import re
+    cn_chunks = re.findall(r'[\u4e00-\u9fa5]+', (dirname + title))
+    short_words = set()
+    for chunk in cn_chunks:
+        # 2-4 字的连续子串都是有意义的业务词候选
+        if 2 <= len(chunk) <= 4:
+            short_words.add(chunk)
+        elif len(chunk) > 4:
+            # 长词切前4字、后4字、中间4字 (覆盖"智能排班系统"→智能排班/排班系统)
+            short_words.add(chunk[:4])
+            short_words.add(chunk[-4:])
+    # 去太泛的词
+    generic = {'功能', '系统', '管理', '模块', '页面', '需求', '设计', '实现',
+               '新增', '修改', '查询', '删除', '操作', '记录', '列表', '详情'}
+    for w in short_words:
+        if w not in generic and w not in kws:
+            kws.append(w)
+
+    # 3. PRD 正文里的业务关键词 (从标题和需求段落粗提)
+    try:
+        prd = task_dir / 'prd.md'
+        if prd.is_file():
+            content = prd.read_text(encoding='utf-8', errors='ignore')
+            import re
+            # 提取中文词组 (2-6 字连续中文)
+            cn_words = re.findall(r'[\u4e00-\u9fa5]{2,6}', content)
+            # 去停用词 + 高频词
+            stop = {'功能', '需求', '系统', '页面', '数据', '支持', '可以',
+                    '进行', '操作', '显示', '一个', '这个', '实现', '业务',
+                    '测试', '使用', '如果', '需要', '必须', '以及', '界面'}
+            from collections import Counter
+            freq = Counter(w for w in cn_words if w not in stop)
+            for w, _ in freq.most_common(5):
+                if w not in kws and len(w) >= 2:
+                    kws.append(w)
+    except Exception:
+        pass
+
+    # 去重保序, 过滤太短的
+    seen = set()
+    result = []
+    for k in kws:
+        if k and len(k) >= 2 and k not in seen:
+            seen.add(k)
+            result.append(k)
+    return result[:6]  # 最多 6 个, 避免查太多
+
+
+def _generate_test_handoff(task_dir: Path, repo_root) -> None:
+    """finish 后生成 test-handoff.md (开发→测试交接画像)。
+    从任务关键词查页面按钮+接口画像, 写入任务目录。无图谱/无匹配则跳过。
+    """
+    try:
+        import page_probe
+    except ImportError:
+        sys.path.insert(0, str(repo_root / '.qoder' / 'scripts'))
+        import page_probe
+
+    kws = _extract_keywords(task_dir)
+    if not kws:
+        print("[测试交接画像] 跳过: 任务无明确业务关键词")
+        return
+
+    # 用每个关键词查画像, 合并结果
+    all_pages = []
+    seen_vue = set()
+    used_kws = []
+    for kw in kws:
+        profile = page_probe.build_page_profile(keyword=kw, repo_root=str(repo_root))
+        if not profile.get('ok'):
+            continue
+        for pg in profile['pages']:
+            if pg['vue_file'] in seen_vue:
+                continue
+            seen_vue.add(pg['vue_file'])
+            all_pages.append(pg)
+        used_kws.append(kw)
+        if len(all_pages) >= 12:  # 够多了, 停止查更多关键词
+            break
+
+    handoff_path = task_dir / 'test-handoff.md'
+    if not all_pages:
+        # 没匹配到页面: 写一个提示性 handoff (让测试知道开发想覆盖什么)
+        lines = [
+            '# 测试交接: %s' % task_dir.name,
+            '',
+            '> 任务完成于 %s' % datetime.now().strftime('%Y-%m-%d %H:%M'),
+            '> 业务关键词: %s' % ', '.join(kws),
+            '',
+            '## ⚠️ 未能自动生成页面画像',
+            '',
+            '知识图谱里没有匹配这些关键词的页面按钮记录。可能原因:',
+            '- 功能是全新的, 代码还没被知识图谱索引',
+            '- 关键词与代码里的命名不一致',
+            '',
+            '**测试建议:** 手动确认涉及的页面, 或用 `autotest.py page --kw <准确关键词>` 重试。',
+        ]
+        handoff_path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
+        print("[测试交接画像] %s (无匹配页面, 已写提示)" % handoff_path.name)
+        return
+
+    # 渲染完整画像
+    total_btns = sum(len(pg['buttons']) for pg in all_pages)
+    lines = [
+        '# 测试交接: %s' % task_dir.name,
+        '',
+        '> 任务完成于 %s' % datetime.now().strftime('%Y-%m-%d %H:%M'),
+        '> 业务关键词: %s' % ', '.join(used_kws),
+        '> 共 %d 个页面, %d 个交互点' % (len(all_pages), total_btns),
+        '',
+        '> 💡 测试人员照此写用例, 不用自己找页面按钮。每行"按钮→接口"就是一个用例的核心断言点。',
+        '> 未解析到接口的按钮 (deferred/unresolved) 需现场点击确认实际调用。',
+        '',
+    ]
+
+    # 复用 page_probe 的渲染, 但按页面输出
+    fake_profile = {'ok': True, 'pages': all_pages, 'stats': page_probe._trace_stats(str(repo_root))}
+    lines.append(page_probe.render_profile_md(fake_profile))
+
+    lines.append('')
+    lines.append('---')
+    lines.append('')
+    lines.append('## 测试用例生成')
+    lines.append('拿到这份画像后, 直接说:')
+    lines.append('- "测一下 %s" → 走 /wl-test quick 自动生成用例' % (used_kws[0] if used_kws else '这个功能'))
+    lines.append('- 或 `/wl-test browser %s` → 按任务 PRD 生成回归用例' % task_dir.name)
+    lines.append('- 也可 `autotest.py page --kw <更精确的关键词>` 单独查某页画像')
+
+    handoff_path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
+    print("[测试交接画像] 已生成 %s (%d 页面, %d 交互点)"
+          % (handoff_path.name, len(all_pages), total_btns))
+
+
 def _cleanup_orphaned_refs(archived_task_name: str, repo_root) -> int:
     """归档任务后, 清理其它任务中对它的引用 (blocked_by/blocks/children/parent)。
 

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

@@ -108,6 +108,20 @@ RICE = Reach × Impact × Confidence ÷ Effort
 python "$R/.qoder/scripts/team_sync.py" push
 ```
 
+## finish 后：自动生成测试交接画像（可选增强）
+
+用户说"完成了"/"这个任务做完了"触发 `finish` 时，**自动**在任务目录生成 **`test-handoff.md`**（开发→测试交接物），用户什么都不用做：
+- 从任务目录名/标题/PRD 提取业务关键词
+- 查知识图谱，列出涉及的**页面 + 按钮 + handler + 接口 + 方法 + 置信度**
+- 自动给出**测试建议**（按按钮类型：新增/编辑/删除/导出…）
+
+测试人员拿到这份画像，照着写用例，**不用自己满仓库找页面按钮**。
+
+> **非侵入**：无知识图谱 / 关键词没匹配到页面 → 跳过或写提示，**绝不阻塞任务完成**。
+>
+> 测试人员想单独查某页画像：直接说 **"查一下保险页面的按钮和接口"** 或用 **`/wl-test`**，
+> AI 在后台调脚本产出画像，**用户永远不碰 python 命令**。
+
 ## 🧩 QoderWork 增强：待办双向同步（可选 · 无连接器则自动回退）
 
 > 依赖 **QoderWork 桌面端连接器**（Settings → Connectors，授权 Microsoft 365 待办 / OneNote，或 macOS 提醒事项）。

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

@@ -146,6 +146,14 @@ python "$R/.qoder/scripts/autotest.py" recall --url "/auth/login"
 
 > 图谱无数据 → 跳过，按通用模式生成。**不要再单独调 feature_overview**（信息重叠，浪费一轮）。
 
+**🎯 知道页面名/URL 时，AI 先查按钮+接口画像（最精准，1 条命令拿到所有交互点）：**
+```bash
+python "$R/.qoder/scripts/autotest.py" page --kw 保险        # 按业务名查
+python "$R/.qoder/scripts/autotest.py" page --url /veh/insurance  # 按URL查
+```
+（这是 AI 在 `/wl-test` 流程内部自动调用的工具，**用户只用 `/wl-test`，不碰此命令**。）
+输出每个按钮的 handler + 调用接口 + HTTP 方法 + 置信度，**直接对应到用例的 click→assert 断言点**。开发 `finish` 任务时也会自动生成 `test-handoff.md`，内容同此画像——交接场景直接读那份即可，不必重查。
+
 ### Step 1：AI 据用户描述 + 图谱信息生成意图式用例 JSON（**一次生成全部用例**）
 **意图+锚点格式**（A方案核心）：用 `intent` 表达"做什么"，用 `anchor` 精确定位（有锚点则确定性命中，无则 LLM 兜底）。
 ```json