@hupan56/wlkj 2.7.11 → 3.0.0

package/templates/qoder/scripts/setup/__init__.py

@@ -0,0 +1,11 @@
+# 子包初始化: 注入 scripts/根 + 所有子包到 sys.path
+# 让跨包 import (旧式不带前缀) 仍可用, 兼容现有代码
+import os as _os, sys as _sys
+_root = _os.path.dirname(_os.path.dirname(_os.path.abspath(__file__)))
+if _root not in _sys.path:
+    _sys.path.insert(0, _root)
+# 注入所有子包目录 (兼容旧式 import xxx)
+for _sub in ('kg', 'build', 'test', 'setup', 'io'):
+    _subdir = _os.path.join(_root, _sub)
+    if _os.path.isdir(_subdir) and _subdir not in _sys.path:
+        _sys.path.insert(0, _subdir)

package/templates/qoder/scripts/setup/carriers.py

@@ -0,0 +1,662 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""carriers.py - 四载体一致性 (Facade 外观模式)
+
+v3.0 合并自: check_carriers + check_qoderwork_consistency + sync_carriers。
+四载体: Qoder IDE / Quest / CLI / QoderWork。三者都是"四载体"这一个领域,
+对外应是 1 个 carriers 命令的子操作 (Facade: 多个细粒度检查统一入口)。
+
+用法:
+    python carriers.py check          全套一致性 (内容+路径)
+    python carriers.py check-paths    只查裸相对路径
+    python carriers.py sync [--dry-run] 同步 description
+"""
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+import os, sys, re, json, argparse, difflib
+try:
+    import yaml
+except ImportError:
+    yaml=None
+from common.paths import get_repo_root
+BASE = str(get_repo_root())
+COMMANDS_DIR = os.path.join(BASE, '.qoder', 'commands')
+SKILLS_DIR = os.path.join(BASE, '.qoder', 'skills')
+AGENTS_MD = os.path.join(BASE, 'AGENTS.md')
+
+# ==================== 来自 check_carriers.py ====================
+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_check_carriers():
+    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
+
+
+
+
+# ==================== 来自 check_qoderwork_consistency.py ====================
+from common.paths import get_repo_root  # noqa: E402
+
+# 扫描目标: commands 全部 .md + skills 的 SKILL.md
+SCAN_GLOBS = [
+    ('commands', '.qoder/commands', '*.md'),
+    ('skills', '.qoder/skills', 'SKILL.md'),
+]
+
+# 裸相对路径调用: `python .qoder/scripts/xxx` 但前面没有 cd "$R" 或 "$R/ 前缀
+# 匹配 `python .qoder/scripts/` 或 `python3 .qoder/scripts/`, 不带 $R 引号包裹
+BARE_PAT = re.compile(r'(?<![\"\$])\bpython3?\s+\.qoder/scripts/([A-Za-z0-9_./-]+)')
+
+# 已安全模式: cd "$R" && python .qoder/scripts/...
+SAFE_CD_PAT = re.compile(r'cd\s+["\']?\$R["\']?\s*&&\s*python3?\s+\.qoder/scripts/')
+
+# 仓库根定位块存在的标志
+ROOT_LOCATOR_PAT = re.compile(r'repo_root\.py|R=\$\(python.*repo_root')
+
+# 在 install_qoderwork.py 提示行里的相对路径(说明性文字, 非真实调用), 豁免
+HINT_CTX = 'install_qoderwork.py'
+
+
+def scan_file(path, strict):
+    """扫一个文件, 返回 (errors, warnings, root_block_present)。
+    errors = 裸相对路径真实调用(必修); warnings = 无 R 块等(建议修)。
+    """
+    errors = []
+    warnings = []
+    try:
+        with open(path, encoding='utf-8') as f:
+            lines = f.readlines()
+    except (OSError, IOError):
+        return errors, warnings, True
+
+    root_block = bool(ROOT_LOCATOR_PAT.search(''.join(lines)))
+
+    for i, line in enumerate(lines, 1):
+        # 豁免: 说明性文字里提到 install_qoderwork.py 的相对路径(这是"找不到时跑这个"的指引)
+        if HINT_CTX in line:
+            continue
+        # 豁免: 已安全的 cd "$R" && python 模式
+        if SAFE_CD_PAT.search(line):
+            continue
+        # 找裸相对路径
+        for m in BARE_PAT.finditer(line):
+            script = m.group(1)
+            # 过滤掉明显是文字描述(行里既无 bash 代码块上下文也无命令感)
+            # 简化: 只要匹配到就算(宁可误报让 reviewer 看一眼)
+            errors.append((i, line.rstrip(), script))
+
+    # 无 R 块但文件里有 $R 引用 → 警告
+    if not root_block and '$R' in ''.join(lines):
+        warnings.append((0, '(无 R 定位块, 但文件里用了 $R)', ''))
+
+    return errors, warnings, root_block
+
+
+def main_check_paths():
+    ap = argparse.ArgumentParser(description='检查命令/skills 是否含裸相对路径(防 ZCode/QoderWork 割裂)')
+    ap.add_argument('--strict', action='store_true', help='警告也算失败')
+    args = ap.parse_args()
+
+    repo = get_repo_root()
+    total_errors = 0
+    total_warnings = 0
+    files_with_errors = []
+    files_with_warnings = []
+
+    for label, rel_dir, pattern in SCAN_GLOBS:
+        scan_dir = repo / rel_dir
+        if not scan_dir.is_dir():
+            continue
+        for dirpath, dirnames, filenames in os.walk(str(scan_dir)):
+            for fn in filenames:
+                import fnmatch
+                if not fnmatch.fnmatch(fn, pattern):
+                    continue
+                path = os.path.join(dirpath, fn)
+                errors, warnings, root_block = scan_file(path, args.strict)
+                rel = os.path.relpath(path, str(repo))
+                if errors:
+                    files_with_errors.append((rel, errors))
+                    total_errors += len(errors)
+                if warnings:
+                    files_with_warnings.append((rel, warnings))
+                    total_warnings += len(warnings)
+
+    # 输出
+    print('=' * 64)
+    print('QoderWork 一致性检查 (防 ZCode 行 / QoderWork 挂 的割裂)')
+    print('=' * 64)
+
+    if files_with_errors:
+        print()
+        print('🔴 裸相对路径调用 (QoderWork 必挂, 必修):')
+        for rel, errs in files_with_errors:
+            print('  ' + rel)
+            for lineno, line, script in errs:
+                snippet = line.strip()[:80]
+                print('    L%d: %s' % (lineno, snippet))
+
+    if files_with_warnings:
+        print()
+        print('🟡 警告 (建议修, --strict 才算失败):')
+        for rel, ws in files_with_warnings:
+            print('  ' + rel)
+            for lineno, line, script in ws:
+                print('    %s' % line)
+
+    if not files_with_errors and not files_with_warnings:
+        print('✅ 全部通过: 命令/skills 无裸相对路径调用, ZCode ≡ QoderWork 一致。')
+
+    print('-' * 64)
+    print('统计: 错误 %d (文件 %d) / 警告 %d (文件 %d)'
+          % (total_errors, len(files_with_errors), total_warnings, len(files_with_warnings)))
+    print()
+    print('规约: 脚本调用必须二选一:')
+    print('  ① python "$R/.qoder/scripts/xxx.py" ...    (R = repo_root.py 输出)')
+    print('  ② cd "$R" && python .qoder/scripts/xxx.py ...')
+
+    if total_errors > 0:
+        return 1
+    if args.strict and total_warnings > 0:
+        return 1
+    return 0
+
+
+
+
+# ==================== 来自 sync_carriers.py ====================
+from common.paths import get_repo_root
+
+BASE = get_repo_root()
+COMMANDS_DIR = BASE / '.qoder' / 'commands'
+SKILLS_DIR = BASE / '.qoder' / 'skills'
+
+
+def _read_frontmatter(path):
+    """读 .md 的 frontmatter, 返回 (fm_dict, body, raw_fm_text)。
+    raw_fm_text 用于精确替换 (保留原始格式)。
+    """
+    text = path.read_text(encoding='utf-8', errors='ignore')
+    if not text.startswith('---'):
+        return {}, text, ''
+    parts = text.split('---', 2)
+    if len(parts) < 3:
+        return {}, text, ''
+    fm_raw = parts[1]
+    body = parts[2]
+    return _parse_fm(fm_raw), body, fm_raw
+
+
+def _parse_fm(fm_text):
+    """解析 YAML frontmatter (简化版, 不引外部库)。返回 dict。
+    处理带引号的值和裸值。
+    """
+    fm = {}
+    for line in fm_text.splitlines():
+        line = line.rstrip()
+        if not line.strip() or line.strip().startswith('#'):
+            continue
+        if ':' not in line:
+            continue
+        key, _, val = line.partition(':')
+        key = key.strip()
+        val = val.strip()
+        # 去引号
+        if (val.startswith('"') and val.endswith('"')) or \
+           (val.startswith("'") and val.endswith("'")):
+            val = val[1:-1]
+        fm[key] = val
+    return fm
+
+
+def _condense_description(desc):
+    """skill 的 description 往往很长 (含触发词列举), command 的该简洁。
+    截取策略: 保留到"用户说"或"触发"或第一个句号之前的核心描述。
+    保留中英双语部分 (英文描述通常是核心)。
+    """
+    if not desc:
+        return desc
+    # 找截断点: "用户说" / "触发" / "时触发"
+    for marker in ['。用户说', '；用户说', ' 用户说', '。触发:', ' 触发:', '；触发', '。时触发', ' 时触发']:
+        idx = desc.find(marker)
+        if idx > 0:
+            return desc[:idx + 1]  # 含句号
+    # 没找到截断点 → 原样返回 (可能本就简洁)
+    return desc
+
+
+def _find_command_file(name):
+    """在 commands/ 和 commands/optional/ 下找命令文件。返回 Path 或 None。"""
+    for cand in [COMMANDS_DIR / (name + '.md'),
+                 COMMANDS_DIR / 'optional' / (name + '.md')]:
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _find_skill_file(name):
+    """skills/wl-X/SKILL.md。"""
+    p = SKILLS_DIR / name / 'SKILL.md'
+    return p if p.is_file() else None
+
+
+def sync_one(name, dry_run=False):
+    """同步一个命令。返回 ('synced'/'skipped'/'error', 详情)。"""
+    skill_path = _find_skill_file(name)
+    cmd_path = _find_command_file(name)
+    if not skill_path:
+        return 'error', 'skill 不存在: %s' % skill_path
+    if not cmd_path:
+        return 'error', 'command 不存在: %s' % cmd_path
+
+    skill_fm, _, _ = _read_frontmatter(skill_path)
+    skill_desc = skill_fm.get('description', '')
+    if not skill_desc:
+        return 'skipped', 'skill 无 description 字段'
+
+    cmd_fm, cmd_body, cmd_fm_raw = _read_frontmatter(cmd_path)
+    cmd_desc = cmd_fm.get('description', '')
+
+    # 精简 skill desc (command 不该塞一堆触发词)
+    condensed = _condense_description(skill_desc)
+
+    if cmd_desc == condensed:
+        return 'skipped', '已一致'
+
+    # dry-run 只预览
+    if dry_run:
+        return 'would-sync', '  旧: %s\n  新: %s' % (cmd_desc[:70], condensed[:70])
+
+    # 精确替换 frontmatter 里的 description 行
+    new_fm = _replace_desc_in_fm(cmd_fm_raw, condensed)
+    if new_fm is None:
+        return 'error', '无法解析 command frontmatter 的 description 行'
+
+    new_text = '---' + new_fm + '---' + cmd_body
+    cmd_path.write_text(new_text, encoding='utf-8')
+    return 'synced', condensed[:70]
+
+
+def _replace_desc_in_fm(fm_raw, new_desc):
+    """在 frontmatter 原文里替换 description 行。保留其他行原样。
+    返回新的 fm_raw 或 None (无法替换)。
+    """
+    # 匹配 description: 开头的行 (可能带引号)
+    # 用 json.dumps 保证引号转义正确 (description 含特殊字符)
+    escaped = _yaml_escape(new_desc)
+    pat = re.compile(r'^(\s*description:\s*)(.*)$', re.MULTILINE)
+    new_fm, n = pat.subn(lambda m: m.group(1) + escaped, fm_raw, count=1)
+    if n == 0:
+        # 没有 description 行 → 插一行 (在 name: 之后)
+        if re.search(r'^\s*name:', fm_raw, re.MULTILINE):
+            new_fm = re.sub(
+                r'^(\s*name:\s*.*)$',
+                r'\1\ndescription: ' + escaped,
+                fm_raw, count=1, flags=re.MULTILINE)
+        else:
+            return None
+    return new_fm
+
+
+def _yaml_escape(s):
+    """YAML 字符串转义: 含特殊字符(: # 等)用双引号包裹, 内部双引号转义。
+    简化: 一律用双引号 + JSON 转义 (最安全)。
+    """
+    import json
+    return json.dumps(s, ensure_ascii=False)
+
+
+def find_drifted_commands():
+    """找出所有 command↔skill 配对且 description 漂移的命令名。
+    (复用 check_carriers 的相似度判断)
+    """
+    from difflib import SequenceMatcher
+    drifted = []
+    if not SKILLS_DIR.is_dir():
+        return drifted
+    for d in sorted(SKILLS_DIR.iterdir()):
+        if not d.is_dir() or not (d / 'SKILL.md').is_file():
+            continue
+        name = d.name
+        cmd = _find_command_file(name)
+        if not cmd:
+            continue
+        skill_fm, _, _ = _read_frontmatter(d / 'SKILL.md')
+        cmd_fm, _, _ = _read_frontmatter(cmd)
+        sd, cd = skill_fm.get('description', ''), cmd_fm.get('description', '')
+        if not sd or not cd:
+            continue
+        sim = SequenceMatcher(None, sd.lower(), cd.lower()).ratio()
+        if sim < 0.85:
+            drifted.append(name)
+    return drifted
+
+
+def main_sync():
+    ap = argparse.ArgumentParser(description='四载体 description 自动同步 (skill -> command)')
+    ap.add_argument('command', nargs='?', default=None,
+                    help='只同步指定命令 (如 wl-search); 不传则同步所有漂移的')
+    ap.add_argument('--dry-run', action='store_true', help='只预览不写文件')
+    args = ap.parse_args()
+
+    print('=' * 56)
+    print('四载体 description 同步 (skill -> command)')
+    print('=' * 56)
+
+    if args.command:
+        names = [args.command]
+    else:
+        names = find_drifted_commands()
+        if not names:
+            print('✅ 无漂移, 所有 command/skill description 已一致。')
+            return 0
+        print('发现 %d 个漂移命令: %s' % (len(names), ', '.join(names)))
+        print()
+
+    synced, skipped, errors = [], [], []
+    for name in names:
+        status, detail = sync_one(name, dry_run=args.dry_run)
+        if status == 'synced':
+            synced.append(name)
+            print('  [✓] %s' % name)
+            print('      %s' % detail)
+        elif status == 'would-sync':
+            synced.append(name)
+            print('  [~] %s (dry-run)' % name)
+            print('%s' % detail)
+        elif status == 'skipped':
+            skipped.append(name)
+        else:
+            errors.append((name, detail))
+            print('  [✗] %s: %s' % (name, detail))
+
+    print()
+    verb = '将同步' if args.dry_run else '已同步'
+    print('%s: %d 同步 / %d 跳过 / %d 错误'
+          % (verb, len(synced), len(skipped), len(errors)))
+    if not args.dry_run and synced:
+        print('提示: 重跑 check_carriers.py 验证一致性。')
+    if errors:
+        return 1
+    return 0
+
+
+
+
+# ============================================================
+# Facade: 统一入口分发
+# ============================================================
+def main_all():
+    """M4.2: 全系列同步 (一处改→4载体全生效)。
+
+    串联现有3个同步动作:
+    1. sync description (skill→command)
+    2. sync_templates (npm 镜像 .qoder→packages/wlkj/templates)
+    3. install_qoderwork (投影 skills/commands→~/.qoderwork/)
+
+    用法: python carriers.py all
+    改了规则/技能后跑一次, 4载体全同步。
+    """
+    import subprocess, os
+    SCRIPTS = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    BASE = os.path.dirname(os.path.dirname(SCRIPTS))
+    print('=' * 56)
+    print('全系列同步 (4载体: IDE/Quest/CLI/QoderWork)')
+    print('=' * 56)
+
+    # 1. sync description (skill→command)
+    print('\n[1/3] 同步 description (skill→command)...')
+    sys.argv = [sys.argv[0]]  # 清参数
+    try:
+        main_sync()
+    except SystemExit:
+        pass
+
+    # 2. sync_templates (npm 镜像)
+    print('\n[2/3] 同步 npm 镜像 (.qoder→packages/wlkj/templates)...')
+    sync_script = os.path.join(BASE, 'packages', 'wlkj', 'sync_templates.py')
+    if os.path.isfile(sync_script):
+        r = subprocess.run([sys.executable, sync_script], capture_output=True, text=True, encoding='utf-8')
+        print(r.stdout.strip().split('\n')[-1] if r.stdout else '  (无输出)')
+    else:
+        print('  跳过 (sync_templates.py 不存在)')
+
+    # 3. install_qoderwork (投影 ~/.qoderwork/)
+    print('\n[3/3] 投影 QoderWork (skills/commands→~/.qoderwork/)...')
+    install_script = os.path.join(SCRIPTS, 'setup', 'install_qoderwork.py')
+    if os.path.isfile(install_script):
+        r = subprocess.run([sys.executable, install_script, '--force-commands'],
+                           capture_output=True, text=True, encoding='utf-8', timeout=60)
+        print('  QoderWork 投影完成' if r.returncode == 0 else '  ⚠️ 投影失败: %s' % r.stderr[:80])
+    else:
+        print('  跳过 (install_qoderwork.py 不存在)')
+
+    print('\n✓ 全系列同步完成。4载体已对齐:')
+    print('  IDE/Quest: .qoder/rules + skills + commands')
+    print('  CLI:       AGENTS.md (需手动同步规则正文, 或 M5 自动化)')
+    print('  QoderWork: ~/.qoderwork/skills + commands')
+    print('  npm:       packages/wlkj/templates/')
+    return 0
+
+
+def main():
+    cmd = sys.argv[1] if len(sys.argv) > 1 else 'check'
+    rest = sys.argv[2:]
+    # 所有分支: 把子命令从 argv 去掉, 让各 main() 的 argparse 正确解析剩余参数
+    sys.argv = [sys.argv[0]] + rest
+    if cmd == 'check':
+        sys.exit(main_check_carriers())
+    elif cmd in ('check-paths', 'paths'):
+        sys.exit(main_check_paths())
+    elif cmd == 'sync':
+        sys.exit(main_sync())
+    elif cmd == 'all':
+        sys.exit(main_all())
+    else:
+        print('用法: carriers.py [check|check-paths|sync|all]')
+        print('  check        全套一致性检查 (内容)')
+        print('  check-paths  查裸相对路径')
+        print('  sync         同步 description (支持 --dry-run)')
+        print('  all          全系列同步 (4载体一键对齐)')
+
+if __name__ == '__main__':
+    main()