@hupan56/wlkj 2.6.0 → 2.7.0

package/templates/qoder/scripts/check_carriers.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+check_carriers.py - 四载体一致性守卫 (防 IDE/Quest/CLI/QoderWork 漂移)
+
+背景:
+  AGENTS.md 自己写了"改规则要同步更新它和 .qoder/rules/wl-pipeline.md"。
+  四个载体 (IDE commands / Quest skills / CLI AGENTS.md / QoderWork) 描述同一个
+  命令, 如果只改一个就漂移了 —— 比如 IDE 里 /wl-test 说要跑单测, 但 QoderWork 的
+  skill 还停在旧版。目前没有任何机制发现, git status 里的 sync_templates.py M 状态
+  就是手工同步的证据。
+
+  check_qoderwork_consistency.py 只查"裸相对路径"这一种退化。
+  本脚本查"内容一致性": 同名命令的描述是否对得上、AGENTS.md 命令表是否齐全。
+
+Usage:
+    python .qoder/scripts/check_carriers.py
+    python .qoder/scripts/check_carriers.py --strict   # 警告也算失败
+Exit:
+    0 = 四载体一致
+    1 = 发现漂移 (errors)
+"""
+import argparse
+import os
+import re
+import sys
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except (AttributeError, IOError):
+        pass
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from common.paths import get_repo_root
+
+BASE = get_repo_root()
+COMMANDS_DIR = BASE / '.qoder' / 'commands'
+SKILLS_DIR = BASE / '.qoder' / 'skills'
+AGENTS_MD = BASE / 'AGENTS.md'
+
+# description 相似度阈值 (改了标点/措辞不算漂移, 实质改变才算)
+DESC_SIMILAR_THRESHOLD = 0.6
+
+
+def _read_yaml_frontmatter(path):
+    """读 .md 的 YAML frontmatter, 返回 dict (无则空)。"""
+    try:
+        text = path.read_text(encoding='utf-8', errors='ignore')
+    except OSError:
+        return {}
+    if not text.startswith('---'):
+        return {}
+    parts = text.split('---', 2)
+    if len(parts) < 3:
+        return {}
+    fm = {}
+    for line in parts[1].splitlines():
+        line = line.strip()
+        if ':' in line:
+            k, _, v = line.partition(':')
+            fm[k.strip()] = v.strip().strip('"\'')
+    return fm
+
+
+def _similarity(a, b):
+    """两字符串的相似度 (0~1), 用SequenceRatio。None/空 = 0。"""
+    if not a or not b:
+        return 0.0
+    from difflib import SequenceMatcher
+    return SequenceMatcher(None, a.lower(), b.lower()).ratio()
+
+
+def _prefix_consistent(cmd_desc, skill_desc):
+    """判断 command description 是否是 skill description 的"精简前缀版本"。
+
+    设计意图: sync_carriers 把 skill 的 description 截断到触发词前, 写进 command。
+    所以 command = skill 的核心前缀, skill 后面挂触发词。这不是漂移, 是设计如此。
+
+    判定: command 是 skill 的前缀 (忽略大小写), 或 command 覆盖了 skill 的核心部分。
+    返回 True = 一致 (设计如此), False = 需进一步用相似度判断。
+    """
+    if not cmd_desc or not skill_desc:
+        return False
+    c, s = cmd_desc.lower().strip(), skill_desc.lower().strip()
+    # 1. command 是 skill 的前缀 (最常见: sync 后 command = skill 截断版)
+    if s.startswith(c):
+        return True
+    # 2. command 覆盖了 skill 的核心 (skill 去掉触发词后 == command)
+    #    触发词标记 (和 sync_carriers._condense_description 对齐)
+    for marker in ['。用户说', '；用户说', ' 用户说', '。触发:', ' 触发:', '；触发', '时触发']:
+        idx = s.find(marker)
+        if idx > 0:
+            skill_core = s[:idx + 1]  # 含句号/分号
+            if skill_core.startswith(c) or c.startswith(skill_core):
+                return True
+            # 核心部分相似度高也算 (措辞微调)
+            if _similarity(c, skill_core) >= 0.85:
+                return True
+    return False
+
+
+def check_command_skill_pairing():
+    """校验 commands/wl-X.md 和 skills/wl-X/SKILL.md 的 description 是否一致。
+    返回 (errors, warnings)。
+    """
+    errors = []
+    warnings = []
+
+    # 收集所有 command (含 optional/ 子目录)
+    commands = {}
+    if COMMANDS_DIR.is_dir():
+        for path in COMMANDS_DIR.rglob('*.md'):
+            name = path.stem  # wl-test
+            commands[name] = path
+
+    # 收集所有 skill
+    skills = {}
+    if SKILLS_DIR.is_dir():
+        for d in SKILLS_DIR.iterdir():
+            if d.is_dir() and (d / 'SKILL.md').is_file():
+                skills[d.name] = d / 'SKILL.md'
+
+    # 配对校验 (command 和 skill 同名才校验, 不同名是设计如此)
+    common_names = set(commands) & set(skills)
+    for name in sorted(common_names):
+        cmd_fm = _read_yaml_frontmatter(commands[name])
+        skill_fm = _read_yaml_frontmatter(skills[name])
+        cmd_desc = cmd_fm.get('description', '')
+        skill_desc = skill_fm.get('description', '')
+        if not cmd_desc or not skill_desc:
+            continue  # 没写的跳过
+        # 一致性判断: 不只用字符相似度, 还判断"command 是否是 skill 的精简前缀版本"
+        # (sync_carriers 产生的就是这个关系: command = skill 去掉触发词后的核心描述)
+        # 这样度量才符合设计意图, 不会把"故意精简"误报成漂移。
+        if _prefix_consistent(cmd_desc, skill_desc):
+            continue  # command 是 skill 的精简版 = 一致, 通过
+        sim = _similarity(cmd_desc, skill_desc)
+        if sim < DESC_SIMILAR_THRESHOLD:
+            errors.append((
+                name,
+                'description 严重不一致 (相似度 %.0f%%, 阈值 %d%%)' % (sim * 100, DESC_SIMILAR_THRESHOLD * 100),
+                'command: ' + cmd_desc[:60],
+                'skill:    ' + skill_desc[:60],
+            ))
+        elif sim < 0.85:
+            warnings.append((
+                name,
+                'description 有差异 (相似度 %.0f%%), 建议核对' % (sim * 100),
+            ))
+
+    return errors, warnings
+
+
+def check_agents_md_command_table():
+    """校验 AGENTS.md 的 7 核心命令表与实际文件是否对得上。
+    表里列了但文件不存在 = 漂移 (改了命令没改文档, 或反之)。
+    """
+    errors = []
+    if not AGENTS_MD.is_file():
+        return [('AGENTS.md', 'AGENTS.md 不存在 (CLI 载体缺失)', '', '')]
+    text = AGENTS_MD.read_text(encoding='utf-8', errors='ignore')
+
+    # 提取"7 Core Commands"表里的命令名 (形如 `/wl-init`)
+    # 表格行格式: | `/wl-init` | ... |
+    table_cmds = set()
+    in_core_table = False
+    for line in text.splitlines():
+        s = line.strip()
+        if '7 Core' in line or '核心命令' in line:
+            in_core_table = True
+        if in_core_table:
+            for m in re.finditer(r'`(/wl-[a-z-]+)`', s):
+                table_cmds.add(m.group(1)[1:])  # 去掉 / 前缀
+        if in_core_table and s.startswith('|') and '工序站' in text and s.count('|') >= 2:
+            # 表还在继续
+            pass
+
+    # 校验每个表里的命令文件存在
+    for cmd in sorted(table_cmds):
+        cmd_file = COMMANDS_DIR / (cmd + '.md')
+        skill_file = SKILLS_DIR / cmd / 'SKILL.md'
+        if not cmd_file.is_file() and not skill_file.is_file():
+            errors.append((
+                cmd,
+                'AGENTS.md 命令表列了 /%s 但 commands/ 和 skills/ 都没文件' % cmd,
+                '',
+                '',
+            ))
+
+    return errors
+
+
+def main():
+    ap = argparse.ArgumentParser(description='四载体一致性守卫 (防漂移)')
+    ap.add_argument('--strict', action='store_true', help='警告也算失败')
+    args = ap.parse_args()
+
+    print('=' * 64)
+    print('四载体一致性检查 (IDE commands / Quest skills / CLI AGENTS.md / QoderWork)')
+    print('=' * 64)
+
+    pair_errors, pair_warnings = check_command_skill_pairing()
+    table_errors = check_agents_md_command_table()
+
+    all_errors = pair_errors + table_errors
+
+    if pair_warnings:
+        print('\n🟡 描述差异 (建议核对, --strict 才算失败):')
+        for name, msg, *_ in pair_warnings:
+            print('  %s: %s' % (name, msg))
+
+    if all_errors:
+        print('\n🔴 载体漂移 (必修):')
+        for item in all_errors:
+            name = item[0]
+            print('  %s' % name)
+            for detail in item[1:]:
+                if detail:
+                    print('    %s' % detail)
+
+    if not all_errors and not pair_warnings:
+        print('✅ 四载体一致: 同名命令描述对得上, AGENTS.md 命令表齐全。')
+
+    print('-' * 64)
+    print('统计: 漂移 %d / 差异 %d' % (len(all_errors), len(pair_warnings)))
+    print('提示: 与 check_qoderwork_consistency.py 互补 ——')
+    print('  那个查裸相对路径, 这个查内容一致性。')
+
+    if all_errors:
+        return 1
+    if args.strict and pair_warnings:
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/templates/qoder/scripts/check_mcp.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+check_mcp.py - MCP 启动健康检查 (验证 init/download 后全系列可用)
+
+为什么需要它:
+  install_qoderwork.py --mcp-only 会写 mcp.json + launcher, 但"写了配置"不等于
+  "MCP 能起来"。50 人里有人 pip 没装齐、有人 .repo-root 写错、有人 lanhu venv 没建,
+  这些都要等用的时候才发现 MCP 挂了。本脚本主动验证每个 MCP 能否真正启动。
+
+  对应需求: "确保 MCP 等 init/download 后, 所有人 qoder 全系列正常运行"。
+
+检查什么 (不真启动 server, 只验证启动条件):
+  1. mcp.json 存在 + 各 server 注册了 launcher 模式
+  2. launcher 能定位仓库根 (.repo-root 锚点 / 环境变量 / 向上找)
+  3. 各 MCP 的依赖就绪:
+     - kg:    装了 duckdb 的 Python + kg_mcp_server.py 存在
+     - mysql: 装了 pymysql 的 Python + config.yaml 有 mysql 段
+     - lanhu: venv 建了 + 当前角色 cookie 配了
+     - playwright: node 在 + cli.js / npx 可用
+
+Usage:
+    python .qoder/scripts/check_mcp.py            # 全量检查
+    python .qoder/scripts/check_mcp.py --fix      # 检查 + 尝试修复 (.repo-root 等)
+Exit: 0 = 全部就绪, 1 = 有 MCP 未就绪
+"""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except (AttributeError, IOError):
+        pass
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from common.paths import get_repo_root
+
+BASE = get_repo_root()
+HOME = Path(os.environ.get('USERPROFILE') or os.path.expanduser('~'))
+QODERWORK_DIR = HOME / '.qoderwork'
+MCP_FILE = QODERWORK_DIR / 'mcp.json'
+REPO_ROOT_ANCHOR = QODERWORK_DIR / '.repo-root'
+
+OK_TAG = '[OK]  '
+WARN_TAG = '[WARN]'
+MISS_TAG = '[MISS]'
+BAD_TAG = '[BAD] '
+
+issues = []
+
+
+def say(tag, msg):
+    print('{} {}'.format(tag, msg))
+
+
+def problem(msg, hint=None):
+    issues.append(msg)
+    say(BAD_TAG, msg)
+    if hint:
+        print('       -> ' + hint)
+
+
+def _run(cmd, timeout=10):
+    """跑命令, 返回 (returncode, output)。"""
+    try:
+        r = subprocess.run(cmd, capture_output=True, text=True,
+                           encoding='utf-8', errors='replace', timeout=timeout)
+        return r.returncode, (r.stdout or '') + (r.stderr or '')
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return 1, ''
+
+
+def _find_python_with(mod):
+    """找一个装了指定模块的 Python。返回路径或 None。"""
+    # 当前 Python
+    try:
+        __import__(mod)
+        return sys.executable
+    except ImportError:
+        pass
+    # 其他 Python
+    import shutil
+    for name in ('python', 'python3', 'py'):
+        p = shutil.which(name)
+        if p and p != sys.executable:
+            rc, _ = _run([p, '-c', 'import %s' % mod], timeout=8)
+            if rc == 0:
+                return p
+    return None
+
+
+# ============================================================
+# 检查项
+# ============================================================
+
+def check_mcp_json(fix=False):
+    """1. mcp.json 存在 + launcher 模式。"""
+    print('\n--- 1. mcp.json 配置 ---')
+    if not MCP_FILE.is_file():
+        problem('mcp.json 不存在 (%s)' % MCP_FILE,
+                '跑: python .qoder/scripts/install_qoderwork.py --mcp-only')
+        return False
+    try:
+        cfg = json.loads(MCP_FILE.read_text(encoding='utf-8'))
+    except (ValueError, OSError):
+        problem('mcp.json 解析失败', '文件损坏, 重跑 install_qoderwork.py --mcp-only')
+        return False
+    servers = cfg.get('mcpServers', {})
+    if not servers:
+        problem('mcp.json 无 mcpServers', '重跑 install_qoderwork.py --mcp-only')
+        return False
+    say(OK_TAG, 'mcp.json 存在, 注册了 %d 个 server: %s' % (
+        len(servers), ', '.join(servers.keys())))
+    # 检查是否 launcher 模式 (command 用 mcp_launcher.py)
+    launcher_count = 0
+    for name, entry in servers.items():
+        args = entry.get('args', []) if isinstance(entry, dict) else []
+        if any('mcp_launcher.py' in str(a) for a in args):
+            launcher_count += 1
+    if launcher_count > 0:
+        say(OK_TAG, '%d 个 server 用 launcher 模式 (跨机器通用)' % launcher_count)
+    else:
+        say(WARN_TAG, '无 launcher 模式 server (可能写死路径), 升级: install_qoderwork.py --mcp-only')
+    return True
+
+
+def check_repo_root(fix=False):
+    """2. launcher 能定位仓库根 (.repo-root 锚点)。"""
+    print('\n--- 2. 仓库根定位 ---')
+    if REPO_ROOT_ANCHOR.is_file():
+        try:
+            root_val = REPO_ROOT_ANCHOR.read_text(encoding='utf-8').strip()
+            if (Path(root_val) / '.qoder' / 'scripts').is_dir():
+                say(OK_TAG, '.repo-root 锚点正确: %s' % root_val)
+                return True
+            else:
+                problem('.repo-root 指向的目录不是仓库根: %s' % root_val,
+                        '重跑 install_qoderwork.py --mcp-only 会用 PROJECT_ROOT 修正')
+        except OSError:
+            pass
+    # 锚点缺失或错误
+    if fix:
+        try:
+            REPO_ROOT_ANCHOR.parent.mkdir(parents=True, exist_ok=True)
+            REPO_ROOT_ANCHOR.write_text(str(BASE), encoding='utf-8')
+            say(OK_TAG, '.repo-root 锚点已修复: %s -> %s' % (REPO_ROOT_ANCHOR, BASE))
+            return True
+        except OSError as e:
+            problem('修复 .repo-root 失败: %s' % e)
+    else:
+        problem('.repo-root 锚点缺失或错误',
+                '加 --fix 自动修复, 或重跑 install_qoderwork.py --mcp-only')
+    return False
+
+
+def check_launcher_file(fix=False):
+    """3. launcher 脚本存在于 ~/.qoderwork/。"""
+    print('\n--- 3. MCP launcher ---')
+    launcher = QODERWORK_DIR / 'mcp_launcher.py'
+    if launcher.is_file():
+        say(OK_TAG, 'launcher 存在: %s' % launcher)
+        return True
+    problem('launcher 不存在: %s' % launcher,
+            '重跑 install_qoderwork.py --mcp-only (会复制 launcher)')
+    return False
+
+
+def check_kg():
+    """4. kg MCP: duckdb + kg_mcp_server.py。"""
+    print('\n--- 4. 知识图谱 MCP (kg) ---')
+    server = BASE / '.qoder' / 'scripts' / 'kg_mcp_server.py'
+    if not server.is_file():
+        problem('kg_mcp_server.py 不存在', '引擎不完整, 重跑 npx wlkj update')
+        return
+    py = _find_python_with('duckdb')
+    if py:
+        say(OK_TAG, 'kg 就绪 (python=%s, 装了 duckdb)' % py)
+    else:
+        problem('找不到装了 duckdb 的 Python',
+                'pip install duckdb 或 npx @hupan56/wlkj install-env')
+
+
+def check_mysql():
+    """5. mysql MCP: pymysql + config.yaml mysql 段。"""
+    print('\n--- 5. MySQL MCP ---')
+    server = BASE / '.qoder' / 'scripts' / 'mysql_mcp_server.py'
+    if not server.is_file():
+        problem('mysql_mcp_server.py 不存在')
+        return
+    py = _find_python_with('pymysql')
+    if not py:
+        problem('找不到装了 pymysql 的 Python', 'pip install pymysql')
+        return
+    # config.yaml mysql 段
+    cfg_path = BASE / '.qoder' / 'config.yaml'
+    has_mysql = False
+    if cfg_path.is_file():
+        try:
+            import yaml
+            d = yaml.safe_load(cfg_path.read_text(encoding='utf-8')) or {}
+            has_mysql = bool(d.get('mysql', {}).get('host'))
+        except Exception:
+            pass
+    if has_mysql:
+        say(OK_TAG, 'mysql 就绪 (config.yaml 已配连接信息)')
+    else:
+        say(WARN_TAG, 'mysql 依赖就绪, 但 config.yaml 无 mysql 段 (按需配)')
+
+
+def check_lanhu():
+    """6. lanhu MCP: venv + cookie。三态 (就绪/未装/未配)。"""
+    print('\n--- 6. 蓝湖 MCP (lanhu, 可选) ---')
+    venv = BASE / 'external' / 'lanhu-mcp' / '.venv'
+    server = BASE / 'external' / 'lanhu-mcp' / 'lanhu_mcp_server.py'
+    if not venv.is_dir() or not server.is_file():
+        say(WARN_TAG, 'lanhu 未安装 (团队不用蓝湖可忽略; 用的话: setup_lanhu.py)')
+        return
+    # venv python
+    venv_py = venv / ('Scripts' if sys.platform == 'win32' else 'bin') / ('python.exe' if sys.platform == 'win32' else 'python')
+    if not venv_py.is_file():
+        problem('lanhu venv python 不存在', '重装: setup_lanhu.py')
+        return
+    # 当前角色 cookie
+    try:
+        from common.paths import get_developer
+        dev = get_developer(BASE)
+    except Exception:
+        dev = None
+    if not dev:
+        say(WARN_TAG, 'lanhu venv 就绪, 但未初始化开发者 (跑 /wl-init)')
+        return
+    cookie_file = BASE / 'workspace' / 'members' / dev / '.secrets' / 'lanhu.env'
+    if cookie_file.is_file():
+        say(OK_TAG, 'lanhu 就绪 (角色=%s, cookie 已配)' % dev)
+    else:
+        say(WARN_TAG, 'lanhu venv 就绪, 但角色 %s 的 cookie 未配 (%s)' % (dev, cookie_file))
+
+
+def check_playwright():
+    """7. playwright MCP: node + cli.js/npx。"""
+    print('\n--- 7. Playwright MCP (浏览器测试) ---')
+    import shutil
+    node = shutil.which('node')
+    if not node:
+        problem('node 未安装 (playwright MCP 需要)', '装 Node.js: npx wlkj install-env')
+        return
+    # 优先 cli.js (快), 回退 npx (慢)
+    try:
+        out = subprocess.run('npm root -g', shell=True, capture_output=True,
+                             text=True, timeout=10)
+        root = out.stdout.strip()
+        cli = os.path.join(root, '@playwright', 'mcp', 'cli.js')
+        if os.path.isfile(cli):
+            say(OK_TAG, 'playwright 就绪 (node + cli.js, 快启动)')
+            return
+    except Exception:
+        pass
+    if shutil.which('npx'):
+        say(WARN_TAG, 'playwright 可用但走 npx (冷启动慢, 可能被 QoderWork 超时杀)')
+        say(WARN_TAG, '  建议全局装: npm i -g @playwright/mcp')
+    else:
+        problem('npx 不可用', '装 Node.js')
+
+
+def main():
+    fix = '--fix' in sys.argv
+    print('=' * 56)
+    print('MCP 健康检查 (验证 init/download 后全系列可用)')
+    print('=' * 56)
+
+    check_mcp_json(fix)
+    check_repo_root(fix)
+    check_launcher_file(fix)
+    check_kg()
+    check_mysql()
+    check_lanhu()
+    check_playwright()
+
+    print('\n' + '=' * 56)
+    if issues:
+        print('未就绪 (%d):' % len(issues))
+        for i in issues:
+            print('  - ' + i)
+        print('=' * 56)
+        print('一键修复: python .qoder/scripts/check_mcp.py --fix')
+        print('重配 MCP: python .qoder/scripts/install_qoderwork.py --mcp-only')
+        return 1
+    print('所有 MCP 就绪, Qoder 全系列可正常调用。')
+    print('=' * 56)
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())