@hupan56/wlkj 3.3.13 → 3.3.15

package/templates/qoder/scripts/orchestration/wlkj.py

@@ -1,306 +1,295 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-# Windows 控制台 UTF-8 修复（ctypes 直调 Windows API，非子shell chcp）
-import sys as _s
-if _s.platform == 'win32':
-    import ctypes as _ct, io as _io
-    try:
-        _ct.windll.kernel32.SetConsoleOutputCP(65001)
-        _ct.windll.kernel32.SetConsoleCP(65001)
-        _s.stdout = _io.TextIOWrapper(_s.stdout.buffer, encoding='utf-8', errors='replace')
-        _s.stderr = _io.TextIOWrapper(_s.stderr.buffer, encoding='utf-8', errors='replace')
-    except Exception:
-        pass
-"""
-wlkj.py - 工作流顶层调度器 (Facade 统一入口)
-
-角色: 所有 Qoder 载体 (commands/skills/rules 里写的脚本调用) 统一走本入口,
-由 DISPATCH 表路由到 scripts/ 下分层子目录的真实脚本。这样:
-  - 载体文件只认一个路径 (orchestration/wlkj.py); scripts/ 重组目录时
-    只需改 DISPATCH 一处, 载体文件不受影响 (根治"目录一重组就断链")。
-  - 脚本内部互调 (Python 进程间) 仍直接用分层路径, 不绕本入口 (避免 subprocess 嵌套)。
-
-用法:
-    python .qoder/scripts/orchestration/wlkj.py kg search 保险 --platform web
-    python .qoder/scripts/orchestration/wlkj.py task list
-    python .qoder/scripts/orchestration/wlkj.py doctor --fix
-    python .qoder/scripts/orchestration/wlkj.py search 考勤
-    python .qoder/scripts/orchestration/wlkj.py status
-
-分组 (逻辑导航, 非物理目录):
-    kg/*      知识图谱 (kg.py 的子命令直接透传)
-    task      任务系统
-    search    代码搜索
-    doctor    环境体检
-    status    项目状态
-    sync      团队同步
-    ...
-
-设计:
-  - 透明转发: 不改变任何子脚本的行为, 只是把 argv 转过去
-  - 单一真源: 脚本物理路径只在 DISPATCH 出现一次, 载体层不写死路径
-  - 零维护: 加新命令只需在 DISPATCH 表加一行
-"""
-
-import os
-import subprocess
-import sys
-
-# 命令 → 脚本 映射 (加新命令只需在此加一行)
-# v3.0: 脚本已分子目录, 路径更新为 子包/脚本
-DISPATCH = {
-    # ── 知识图谱 ──
-    'kg': 'domain/kg/kg.py',
-    'search': 'domain/kg/search/search_index.py',
-    'context': 'domain/kg/search/context_pack.py',
-    'prefetch': 'domain/kg/search/prefetch.py',
-    'kg-build': 'domain/kg/build/kg_build.py',
-    'kg-incremental': 'domain/kg/build/kg_incremental.py',
-    'kg-semantic': 'domain/kg/graph/kg_semantic.py',
-    'semantic': 'domain/kg/graph/kg_semantic.py',
-    # ★ MCP 名别名（AI 常把 MCP 工具名当 wlkj.py 命令调 → 未知命令。归一化后两边名都认）
-    'search_code': 'domain/kg/search/search_index.py',
-    'search_api': 'domain/kg/search/search_index.py',
-    'search_prds': 'domain/kg/search/search_index.py',
-    'search_field': 'domain/kg/search/search_index.py',
-    'search_style': 'domain/kg/search/search_index.py',
-    'rag_search': 'domain/kg/graph/kg_semantic.py',
-    'ask_corpus': 'domain/kg/graph/kg_semantic.py',
-    'context_pack': 'domain/kg/search/context_pack.py',
-    'context_360': 'domain/kg/search/context_pack.py',
-    'get_impact': 'domain/kg/search/search_index.py',
-    'style': 'domain/kg/build/build_style_index.py',
-    # ── 任务 / 同步 ──
-    'task': 'domain/task/task.py',
-    'sync': 'domain/task/team_sync.py',
-    'team-sync': 'domain/task/team_sync.py',
-    'git-sync': 'domain/task/git_sync.py',
-    'zentao-sync': 'domain/task/zentao_sync.py',
-    # ── 需求 / PRD ──
-    'req': 'domain/requirement/req.py',
-    'archive-prd': 'domain/requirement/archive_prd.py',
-    # ── 回流平台 (引擎产出 → 平台 AI回流Tab) ──
-    # 用法: wlkj.py return prd <路径> <标题> | return prototype <路径> <功能名> [--platform web]
-    'return': 'domain/integration/return_to_platform.py',
-    'spec-upload': 'domain/integration/spec_upload.py',
-    # ── 设计 ──
-    'fill-prototype': 'domain/design/fill_prototype.py',
-    'design-doc': 'domain/design/gen_design_doc.py',
-    # ── 评估 / 学习 (飞轮) ──
-    'eval': 'validation/metrics/eval_prd.py',
-    'eva': 'validation/metrics/eval_prd.py',
-    'usability': 'validation/metrics/usability_score.py',
-    'learn': 'domain/learning/learn.py',
-    'learn-aggregate': 'domain/kg/build/learn_aggregate.py',
-    # ── 报告 / 状态 ──
-    'status': 'domain/report/status.py',
-    'status-snapshot': 'domain/report/status_snapshot.py',
-    'report': 'domain/report/report.py',
-    'report-snapshot': 'domain/report/report_snapshot.py',
-    'session': 'domain/report/add_session.py',
-    'add-session': 'domain/report/add_session.py',
-    'role': 'domain/report/role.py',
-    'export': 'domain/report/export.py',
-    # ── 测试 ──
-    'test': 'validation/test/autotest.py',
-    'autotest': 'validation/test/autotest.py',
-    'autotest-batch': 'validation/test/autotest_batch.py',
-    'benchmark': 'validation/test/benchmark.py',
-    # ── 环境 / 初始化 ──
-    'switch-project': 'domain/kg/switch_project.py',
-    'doctor': 'deployment/setup/init_doctor.py',
-    'init': 'deployment/setup/setup.py',
-    'install-qw': 'deployment/setup/install_qoderwork.py',
-    'setup-lanhu': 'deployment/setup/setup_lanhu.py',
-}
-
-
-
-
-def _find_script_by_name(scripts_root, name):
-    """未知命令时, 当作脚本名在 scripts/ 下递归查找。
-    支撑 'wlkj.py <脚本名>' 万能跑 (cli.js 的 run 命令底层依赖)。
-    返回绝对路径或 None。"""
-    import glob
-    if not name.endswith('.py'):
-        name = name + '.py'
-    # 递归找 scripts/**/name
-    pattern = os.path.join(scripts_root, '**', name)
-    hits = glob.glob(pattern, recursive=True)
-    return hits[0] if hits else None
-
-def _usage():
-    lines = [
-        'wlkj.py — 工作流顶层调度器',
-        '',
-        '用法: python .qoder/scripts/orchestration/wlkj.py <命令> [参数...]',
-        '',
-        '命令分组 (转发到对应脚本):',
-        '  知识图谱:  kg <子命令>          (kg.py, 13+ 能力)',
-        '             search <词>          (search_index.py)',
-        '             context <词>         (context_pack.py)',
-        '             kg-build              (全量构建图谱)',
-        '             kg-incremental        (增量构建, 定时任务用)',
-        '  任务:      task <子命令>        (task.py, create/list/start/finish)',
-        '  同步:      sync pull|push       (team_sync.py)',
-        '  需求:      req <子命令>         (req.py, 需求生命周期)',
-        '             archive-prd          (PRD 归档)',
-        '  回流平台:  return prd|prototype <文件> <标题> [--platform web]  (PRD/原型回流到平台 AI回流Tab)',
-        '  设计:      fill-prototype <tpl> (真实数据预填原型)',
-        '             design-doc           (生成 DESIGN.md)',
-        '  评估/学习: eval <prd.md>        (eval_prd.py, EVA 评分)',
-        '             usability [--days N]  (usability_score.py, 工作流可用性: 采纳+流程)',
-        '             learn record/status  (个人埋点)',
-        '             learn-aggregate      (团队聚合 → kg.duckdb)',
-        '  状态/报告: status               (status.py, 健康度)',
-        '             report daily|weekly  (report.py)',
-        '             export <格式>        (export.py)',
-        '  测试:      test <子命令>        (autotest.py)',
-        '             autotest-batch <f>   (批量串测)',
-        '             benchmark            (性能基线)',
-        '  体检:      doctor [--fix]       (init_doctor.py)',
-        '',
-        '示例:',
-        '  wlkj.py kg search 保险 --platform web',
-        '  wlkj.py task create "登录优化"',
-        '  wlkj.py doctor --fix',
-        '  wlkj.py learn record prd_accepted \'{"req_id":"REQ-001","score":87}\'',
-        '',
-        '注: 所有 Qoder 载体 (命令/skills/rules) 统一走本入口; 脚本物理位置见 DISPATCH 表。',
-    ]
-    return '\n'.join(lines)
-
-
-def _ctx_cache_cmd(rest, scripts_root):
-    """wlkj.py ctx-cache <REQ-ID> <query> [--platform web|app] — 按 REQ 缓存 context_pack 结果（T1.3）。
-    HIT 回放缓存（省一次 KG/MCP 往返）；MISS 跑 context_pack 捕获 stdout 写缓存再回放。
-    wlkj.py ctx-cache <REQ-ID> --clear — 清该 REQ 缓存（PRD/spec 改动后失效）。
-    任何异常 fail-open 降级直拉（缓存坏了不影响主流程）。
-    """
-    do_clear = "--clear" in rest
-    rest = [a for a in rest if a != "--clear"]
-
-    req_id = None
-    query_parts, passthrough = [], []
-    i = 0
-    while i < len(rest):
-        a = rest[i]
-        if a == "--platform" and i + 1 < len(rest):
-            passthrough.extend([a, rest[i + 1]]); i += 2; continue
-        if a.startswith("-"):
-            passthrough.append(a); i += 1; continue
-        if req_id is None:
-            req_id = a; i += 1; continue
-        query_parts.append(a); i += 1
-    query = " ".join(query_parts).strip()
-    if not req_id or (not query and not do_clear):
-        sys.stderr.write("用法: wlkj.py ctx-cache <REQ-ID> <query> [--platform web|app] | ctx-cache <REQ-ID> --clear\n")
-        return 1
-
-    cc = None
-    try:
-        if scripts_root not in sys.path:
-            sys.path.insert(0, scripts_root)
-        from foundation.io import context_cache as _cc  # noqa
-        cc = _cc
-    except Exception as e:
-        sys.stderr.write("[cache] 模块导入失败, 降级直拉: %s\n" % str(e)[:80])
-
-    # --clear: 清该 REQ 缓存
-    if do_clear:
-        if cc is None:
-            sys.stderr.write("[cache] 模块不可用, 无法 clear\n"); return 1
-        cc.invalidate(req_id)
-        sys.stderr.write("[cache] CLEARED req=%s\n" % req_id)
-        return 0
-
-    if cc is not None:
-        try:
-            cached = cc.get(req_id, query)
-            if cached is not None:
-                sys.stdout.write(cached if cached.endswith("\n") else cached + "\n")
-                sys.stderr.write("[cache] HIT req=%s q=%s (省一次 context_pack 往返)\n" % (req_id, query[:30]))
-                return 0
-        except Exception as e:
-            sys.stderr.write("[cache] get 失败, 降级直拉: %s\n" % str(e)[:80])
-
-    # MISS / 降级：跑 context_pack，捕获 stdout，写缓存，回放
-    script_path = os.path.join(scripts_root, DISPATCH["context"])
-    r = subprocess.run([sys.executable, script_path, query] + passthrough, capture_output=True)
-    sys.stderr.write(r.stderr.decode(errors="replace"))
-    out = r.stdout.decode(errors="replace")
-    sys.stdout.write(out)
-    if out.strip() and cc is not None:
-        try:
-            cc.put(req_id, query, out)
-            sys.stderr.write("[cache] MISS+PUT req=%s q=%s\n" % (req_id, query[:30]))
-        except Exception as e:
-            sys.stderr.write("[cache] put 失败(不影响本次输出): %s\n" % str(e)[:80])
-    return r.returncode
-
-
-def _bf_score_cmd(rest, scripts_root):
-    """wlkj.py bf-score <prd|proto|code|search> <产物文件> [--feature 主题] — 业务保真打分（T1/FW12）。
-    转发 bf_score.py 对真命令产出文件打 BF 分（PRD→BF1/2, 原型→BF3/4, code/search→BF5/6）。
-    bf_score.py 跑在云容器(接真 db_tables/design_system/真PRD)；本地无业务数据时降级提示。"""
-    script = os.path.join(scripts_root, "validation", "eval", "bf_score.py")
-    if not os.path.isfile(script):
-        sys.stderr.write("[bf-score] bf_score.py 不在，跳过\n")
-        return 1
-    r = subprocess.run([sys.executable, script] + rest)
-    return r.returncode
-
-
-# 带 custom 逻辑的命令（在 DISPATCH 透明转发前拦截）
-SPECIAL = {
-    'ctx-cache': _ctx_cache_cmd,
-    'context-cache': _ctx_cache_cmd,
-    'bf-score': _bf_score_cmd,
-    'bfscore': _bf_score_cmd,
-}
-
-
-def main():
-    argv = sys.argv[1:]
-    if not argv or argv[0] in ('-h', '--help', 'help'):
-        print(_usage())
-        return 0
-
-    cmd = argv[0]
-    rest = argv[1:]
-
-    # scripts/ 根 = __file__ 的上两级 (orchestration/ -> scripts/)
-    scripts_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-
-    # T1.3 带 custom 逻辑的命令（如 ctx-cache 缓存）在透明转发前拦截
-    if cmd in SPECIAL:
-        return SPECIAL[cmd](rest, scripts_root)
-
-    script = DISPATCH.get(cmd)
-    if not script:
-        # Fallback: 当作脚本名在 scripts/ 下递归找 (支撑 'wlkj.py run <脚本>')
-        # 这样 cli.js 的 'run' 和直接 'wlkj.py xxx.py' 都能走单一入口, 不需另维护路径表
-        hit = _find_script_by_name(scripts_root, cmd)
-        if hit:
-            script_path = hit
-            r = subprocess.run([sys.executable, script_path] + rest)
-            return r.returncode
-        sys.stderr.write('未知命令: %s\n' % cmd)
-        sys.stderr.write('可用命令: %s\n' % ', '.join(sorted(DISPATCH.keys())))
-        sys.stderr.write('提示: 也可用 wlkj.py <脚本名.py> 递归查找脚本\n')
-        return 1
-
-    # scripts/ 根 = __file__ 的上两级 (orchestration/ → scripts/)
-    scripts_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-    script_path = os.path.join(scripts_root, script)
-    if not os.path.isfile(script_path):
-        sys.stderr.write('脚本不存在: %s\n' % script_path)
-        return 1
-
-    # 透明转发: 用当前 python 跑目标脚本, 透传所有参数和 exit code
-    r = subprocess.run([sys.executable, script_path] + rest)
-    return r.returncode
-
-
-if __name__ == '__main__':
-    sys.exit(main())
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+wlkj.py - 工作流顶层调度器 (Facade 统一入口)
+
+角色: 所有 Qoder 载体 (commands/skills/rules 里写的脚本调用) 统一走本入口,
+由 DISPATCH 表路由到 scripts/ 下分层子目录的真实脚本。这样:
+  - 载体文件只认一个路径 (orchestration/wlkj.py); scripts/ 重组目录时
+    只需改 DISPATCH 一处, 载体文件不受影响 (根治"目录一重组就断链")。
+  - 脚本内部互调 (Python 进程间) 仍直接用分层路径, 不绕本入口 (避免 subprocess 嵌套)。
+
+用法:
+    python .qoder/scripts/orchestration/wlkj.py kg search 保险 --platform web
+    python .qoder/scripts/orchestration/wlkj.py task list
+    python .qoder/scripts/orchestration/wlkj.py doctor --fix
+    python .qoder/scripts/orchestration/wlkj.py search 考勤
+    python .qoder/scripts/orchestration/wlkj.py status
+
+分组 (逻辑导航, 非物理目录):
+    kg/*      知识图谱 (kg.py 的子命令直接透传)
+    task      任务系统
+    search    代码搜索
+    doctor    环境体检
+    status    项目状态
+    sync      团队同步
+    ...
+
+设计:
+  - 透明转发: 不改变任何子脚本的行为, 只是把 argv 转过去
+  - 单一真源: 脚本物理路径只在 DISPATCH 出现一次, 载体层不写死路径
+  - 零维护: 加新命令只需在 DISPATCH 表加一行
+"""
+
+import os
+import subprocess
+import sys
+
+# 命令 → 脚本 映射 (加新命令只需在此加一行)
+# v3.0: 脚本已分子目录, 路径更新为 子包/脚本
+DISPATCH = {
+    # ── 知识图谱 ──
+    'kg': 'domain/kg/kg.py',
+    'search': 'domain/kg/search/search_index.py',
+    'context': 'domain/kg/search/context_pack.py',
+    'prefetch': 'domain/kg/search/prefetch.py',
+    'kg-build': 'domain/kg/build/kg_build.py',
+    'kg-incremental': 'domain/kg/build/kg_incremental.py',
+    'kg-semantic': 'domain/kg/graph/kg_semantic.py',
+    'semantic': 'domain/kg/graph/kg_semantic.py',
+    # ★ MCP 名别名（AI 常把 MCP 工具名当 wlkj.py 命令调 → 未知命令。归一化后两边名都认）
+    'search_code': 'domain/kg/search/search_index.py',
+    'search_api': 'domain/kg/search/search_index.py',
+    'search_prds': 'domain/kg/search/search_index.py',
+    'search_field': 'domain/kg/search/search_index.py',
+    'search_style': 'domain/kg/search/search_index.py',
+    'rag_search': 'domain/kg/graph/kg_semantic.py',
+    'ask_corpus': 'domain/kg/graph/kg_semantic.py',
+    'context_pack': 'domain/kg/search/context_pack.py',
+    'context_360': 'domain/kg/search/context_pack.py',
+    'get_impact': 'domain/kg/search/search_index.py',
+    'style': 'domain/kg/build/build_style_index.py',
+    # ── 任务 / 同步 ──
+    'task': 'domain/task/task.py',
+    'sync': 'domain/task/team_sync.py',
+    'team-sync': 'domain/task/team_sync.py',
+    'git-sync': 'domain/task/git_sync.py',
+    'zentao-sync': 'domain/task/zentao_sync.py',
+    # ── 需求 / PRD ──
+    'req': 'domain/requirement/req.py',
+    'archive-prd': 'domain/requirement/archive_prd.py',
+    # ── 回流平台 (引擎产出 → 平台 AI回流Tab) ──
+    # 用法: wlkj.py return prd <路径> <标题> | return prototype <路径> <功能名> [--platform web]
+    'return': 'domain/integration/return_to_platform.py',
+    'spec-upload': 'domain/integration/spec_upload.py',
+    # ── 设计 ──
+    'fill-prototype': 'domain/design/fill_prototype.py',
+    'design-doc': 'domain/design/gen_design_doc.py',
+    # ── 评估 / 学习 (飞轮) ──
+    'eval': 'validation/metrics/eval_prd.py',
+    'eva': 'validation/metrics/eval_prd.py',
+    'usability': 'validation/metrics/usability_score.py',
+    'learn': 'domain/learning/learn.py',
+    'learn-aggregate': 'domain/kg/build/learn_aggregate.py',
+    # ── 报告 / 状态 ──
+    'status': 'domain/report/status.py',
+    'status-snapshot': 'domain/report/status_snapshot.py',
+    'report': 'domain/report/report.py',
+    'report-snapshot': 'domain/report/report_snapshot.py',
+    'session': 'domain/report/add_session.py',
+    'add-session': 'domain/report/add_session.py',
+    'role': 'domain/report/role.py',
+    'export': 'domain/report/export.py',
+    # ── 测试 ──
+    'test': 'validation/test/autotest.py',
+    'autotest': 'validation/test/autotest.py',
+    'autotest-batch': 'validation/test/autotest_batch.py',
+    'benchmark': 'validation/test/benchmark.py',
+    # ── 环境 / 初始化 ──
+    'switch-project': 'domain/kg/switch_project.py',
+    'doctor': 'deployment/setup/init_doctor.py',
+    'init': 'deployment/setup/setup.py',
+    'install-qw': 'deployment/setup/install_qoderwork.py',
+    'setup-lanhu': 'deployment/setup/setup_lanhu.py',
+}
+
+
+
+
+def _find_script_by_name(scripts_root, name):
+    """未知命令时, 当作脚本名在 scripts/ 下递归查找。
+    支撑 'wlkj.py <脚本名>' 万能跑 (cli.js 的 run 命令底层依赖)。
+    返回绝对路径或 None。"""
+    import glob
+    if not name.endswith('.py'):
+        name = name + '.py'
+    # 递归找 scripts/**/name
+    pattern = os.path.join(scripts_root, '**', name)
+    hits = glob.glob(pattern, recursive=True)
+    return hits[0] if hits else None
+
+def _usage():
+    lines = [
+        'wlkj.py — 工作流顶层调度器',
+        '',
+        '用法: python .qoder/scripts/orchestration/wlkj.py <命令> [参数...]',
+        '',
+        '命令分组 (转发到对应脚本):',
+        '  知识图谱:  kg <子命令>          (kg.py, 13+ 能力)',
+        '             search <词>          (search_index.py)',
+        '             context <词>         (context_pack.py)',
+        '             kg-build              (全量构建图谱)',
+        '             kg-incremental        (增量构建, 定时任务用)',
+        '  任务:      task <子命令>        (task.py, create/list/start/finish)',
+        '  同步:      sync pull|push       (team_sync.py)',
+        '  需求:      req <子命令>         (req.py, 需求生命周期)',
+        '             archive-prd          (PRD 归档)',
+        '  回流平台:  return prd|prototype <文件> <标题> [--platform web]  (PRD/原型回流到平台 AI回流Tab)',
+        '  设计:      fill-prototype <tpl> (真实数据预填原型)',
+        '             design-doc           (生成 DESIGN.md)',
+        '  评估/学习: eval <prd.md>        (eval_prd.py, EVA 评分)',
+        '             usability [--days N]  (usability_score.py, 工作流可用性: 采纳+流程)',
+        '             learn record/status  (个人埋点)',
+        '             learn-aggregate      (团队聚合 → kg.duckdb)',
+        '  状态/报告: status               (status.py, 健康度)',
+        '             report daily|weekly  (report.py)',
+        '             export <格式>        (export.py)',
+        '  测试:      test <子命令>        (autotest.py)',
+        '             autotest-batch <f>   (批量串测)',
+        '             benchmark            (性能基线)',
+        '  体检:      doctor [--fix]       (init_doctor.py)',
+        '',
+        '示例:',
+        '  wlkj.py kg search 保险 --platform web',
+        '  wlkj.py task create "登录优化"',
+        '  wlkj.py doctor --fix',
+        '  wlkj.py learn record prd_accepted \'{"req_id":"REQ-001","score":87}\'',
+        '',
+        '注: 所有 Qoder 载体 (命令/skills/rules) 统一走本入口; 脚本物理位置见 DISPATCH 表。',
+    ]
+    return '\n'.join(lines)
+
+
+def _ctx_cache_cmd(rest, scripts_root):
+    """wlkj.py ctx-cache <REQ-ID> <query> [--platform web|app] — 按 REQ 缓存 context_pack 结果（T1.3）。
+    HIT 回放缓存（省一次 KG/MCP 往返）；MISS 跑 context_pack 捕获 stdout 写缓存再回放。
+    wlkj.py ctx-cache <REQ-ID> --clear — 清该 REQ 缓存（PRD/spec 改动后失效）。
+    任何异常 fail-open 降级直拉（缓存坏了不影响主流程）。
+    """
+    do_clear = "--clear" in rest
+    rest = [a for a in rest if a != "--clear"]
+
+    req_id = None
+    query_parts, passthrough = [], []
+    i = 0
+    while i < len(rest):
+        a = rest[i]
+        if a == "--platform" and i + 1 < len(rest):
+            passthrough.extend([a, rest[i + 1]]); i += 2; continue
+        if a.startswith("-"):
+            passthrough.append(a); i += 1; continue
+        if req_id is None:
+            req_id = a; i += 1; continue
+        query_parts.append(a); i += 1
+    query = " ".join(query_parts).strip()
+    if not req_id or (not query and not do_clear):
+        sys.stderr.write("用法: wlkj.py ctx-cache <REQ-ID> <query> [--platform web|app] | ctx-cache <REQ-ID> --clear\n")
+        return 1
+
+    cc = None
+    try:
+        if scripts_root not in sys.path:
+            sys.path.insert(0, scripts_root)
+        from foundation.io import context_cache as _cc  # noqa
+        cc = _cc
+    except Exception as e:
+        sys.stderr.write("[cache] 模块导入失败, 降级直拉: %s\n" % str(e)[:80])
+
+    # --clear: 清该 REQ 缓存
+    if do_clear:
+        if cc is None:
+            sys.stderr.write("[cache] 模块不可用, 无法 clear\n"); return 1
+        cc.invalidate(req_id)
+        sys.stderr.write("[cache] CLEARED req=%s\n" % req_id)
+        return 0
+
+    if cc is not None:
+        try:
+            cached = cc.get(req_id, query)
+            if cached is not None:
+                sys.stdout.write(cached if cached.endswith("\n") else cached + "\n")
+                sys.stderr.write("[cache] HIT req=%s q=%s (省一次 context_pack 往返)\n" % (req_id, query[:30]))
+                return 0
+        except Exception as e:
+            sys.stderr.write("[cache] get 失败, 降级直拉: %s\n" % str(e)[:80])
+
+    # MISS / 降级：跑 context_pack，捕获 stdout，写缓存，回放
+    script_path = os.path.join(scripts_root, DISPATCH["context"])
+    r = subprocess.run([sys.executable, script_path, query] + passthrough, capture_output=True)
+    sys.stderr.write(r.stderr.decode(errors="replace"))
+    out = r.stdout.decode(errors="replace")
+    sys.stdout.write(out)
+    if out.strip() and cc is not None:
+        try:
+            cc.put(req_id, query, out)
+            sys.stderr.write("[cache] MISS+PUT req=%s q=%s\n" % (req_id, query[:30]))
+        except Exception as e:
+            sys.stderr.write("[cache] put 失败(不影响本次输出): %s\n" % str(e)[:80])
+    return r.returncode
+
+
+def _bf_score_cmd(rest, scripts_root):
+    """wlkj.py bf-score <prd|proto|code|search> <产物文件> [--feature 主题] — 业务保真打分（T1/FW12）。
+    转发 bf_score.py 对真命令产出文件打 BF 分（PRD→BF1/2, 原型→BF3/4, code/search→BF5/6）。
+    bf_score.py 跑在云容器(接真 db_tables/design_system/真PRD)；本地无业务数据时降级提示。"""
+    script = os.path.join(scripts_root, "validation", "eval", "bf_score.py")
+    if not os.path.isfile(script):
+        sys.stderr.write("[bf-score] bf_score.py 不在，跳过\n")
+        return 1
+    r = subprocess.run([sys.executable, script] + rest)
+    return r.returncode
+
+
+# 带 custom 逻辑的命令（在 DISPATCH 透明转发前拦截）
+SPECIAL = {
+    'ctx-cache': _ctx_cache_cmd,
+    'context-cache': _ctx_cache_cmd,
+    'bf-score': _bf_score_cmd,
+    'bfscore': _bf_score_cmd,
+}
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv or argv[0] in ('-h', '--help', 'help'):
+        print(_usage())
+        return 0
+
+    cmd = argv[0]
+    rest = argv[1:]
+
+    # scripts/ 根 = __file__ 的上两级 (orchestration/ -> scripts/)
+    scripts_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+    # T1.3 带 custom 逻辑的命令（如 ctx-cache 缓存）在透明转发前拦截
+    if cmd in SPECIAL:
+        return SPECIAL[cmd](rest, scripts_root)
+
+    script = DISPATCH.get(cmd)
+    if not script:
+        # Fallback: 当作脚本名在 scripts/ 下递归找 (支撑 'wlkj.py run <脚本>')
+        # 这样 cli.js 的 'run' 和直接 'wlkj.py xxx.py' 都能走单一入口, 不需另维护路径表
+        hit = _find_script_by_name(scripts_root, cmd)
+        if hit:
+            script_path = hit
+            r = subprocess.run([sys.executable, script_path] + rest)
+            return r.returncode
+        sys.stderr.write('未知命令: %s\n' % cmd)
+        sys.stderr.write('可用命令: %s\n' % ', '.join(sorted(DISPATCH.keys())))
+        sys.stderr.write('提示: 也可用 wlkj.py <脚本名.py> 递归查找脚本\n')
+        return 1
+
+    # scripts/ 根 = __file__ 的上两级 (orchestration/ → scripts/)
+    scripts_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    script_path = os.path.join(scripts_root, script)
+    if not os.path.isfile(script_path):
+        sys.stderr.write('脚本不存在: %s\n' % script_path)
+        return 1
+
+    # 透明转发: 用当前 python 跑目标脚本, 透传所有参数和 exit code
+    r = subprocess.run([sys.executable, script_path] + rest)
+    return r.returncode
+
+
+if __name__ == '__main__':
+    sys.exit(main())