@hupan56/wlkj 3.3.8 → 3.3.9

package/templates/qoder/hooks/pre-tool-use-commit.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""pre-tool-use-commit.py - P0-3 w3: wl-commit msg 门禁（PreToolUse on Bash git commit）
+
+stop-eval.py 里 _enforce_commit_msg_gate 的**正确落点**：pre-tool-use（commit 执行前验 msg），
+而非 stop-eval（后者 git log -1 不分"本轮 wl-commit" vs 平台开发/工具 commit → 误拦）。
+
+做法（确定性 + 不误拦其他）：
+  1. PreToolUse 命中 Bash + command 含 "git commit"
+  2. 提取 -m 消息（兼容 -m "x" / -m 'x' / --message=x / 多 -m）
+  3. 查需求关联标记 [#REQ-<uuid>] (S3) 或 [#<禅道号>] (S5.1)
+  4. 缺标记：
+     - 默认 ADVISORY（exit 0 + stdout 强提醒）—— 不阻断，避免误拦工具/平台/文档 commit
+     - 环境变量 WLCOMMIT_GATE_BLOCK=1 时 → exit 2 硬拦（wl-commit 强流程场景才开）
+
+铁律：永远 exit 0（除非 BLOCK 模式显式开）；失败 try/except 静默（hook 崩绝不阻塞）。
+非 git commit 命令 / 非 Bash → exit 0。
+"""
+import json
+import os
+import re
+import sys
+
+if sys.platform == 'win32':
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+NL = chr(10)
+BASE = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+HOOK_ERRORS_LOG = os.path.join(BASE, '.qoder', '.runtime', 'hook-errors.log')
+
+# 需求关联标记：[#REQ-xxx] 或 [#123]（禅道号）
+_REQ_TAG_RE = re.compile(r'\[#REQ-[\w-]+\]|\[#\d+\]')
+# 提取 git commit -m 的消息（兼容引号/多段/--message= / 组合短旗 -am）
+# (?:^|\s)-[a-zA-Z]*m  匹配 -m / -am / -cm 等（单 dash 短旗组合；空白前缀避 --message 误匹）
+_M_QUOTED = re.compile(r'''(?:^|\s)-[a-zA-Z]*m\s*(['"])(.*?)\1''', re.S)
+_M_BARE = re.compile(r'(?:^|\s)-[a-zA-Z]*m\s+(\S.*?)\s*(?=(?:^|\s)-[a-zA-Z]*m\s|$)', re.S)
+_MSG_EQ = re.compile(r'(?:^|\s)--message=(\S.*?)\s*(?:--|$)', re.S)
+
+
+def _read_stdin():
+    try:
+        raw = sys.stdin.read()
+        if raw and raw.strip():
+            return json.loads(raw)
+    except Exception:
+        pass
+    return {}
+
+
+def _extract_msg(command):
+    """从 git commit 命令里提取 commit message（拼多 -m）。提不到返 ''。"""
+    if "--message=" in command:
+        m = _MSG_EQ.search(command)
+        if m:
+            return m.group(1).strip()
+    # 所有 -m "..." / -m '...' 段拼接
+    parts = _M_QUOTED.findall(command)  # [(quote, msg), ...]
+    if parts:
+        return "\n".join(p[1] for p in parts).strip()
+    # 裸 -m word（无引号）
+    m = _M_BARE.search(command)
+    if m:
+        return m.group(1).strip()
+    return ""
+
+
+def _log_err(line):
+    from datetime import datetime
+    try:
+        os.makedirs(os.path.dirname(HOOK_ERRORS_LOG), exist_ok=True)
+        with open(HOOK_ERRORS_LOG, 'a', encoding='utf-8') as f:
+            f.write('[{}] pre-tool-use-commit: {}{}'.format(
+                datetime.now().strftime('%Y-%m-%d %H:%M:%S'), str(line)[:200], NL))
+    except Exception:
+        pass
+
+
+def main():
+    data = _read_stdin()
+    tool = data.get("tool_name") or data.get("tool") or ""
+    if tool.lower() not in ("bash", "shell", "execute_bash"):
+        sys.exit(0)
+    tinput = data.get("tool_input") or data.get("input") or {}
+    command = tinput.get("command") or tinput.get("cmd") or ""
+    if not isinstance(command, str) or "git commit" not in command:
+        sys.exit(0)
+    # 跳过 --amend 无 -m / 自动生成（如 merge commit）—— 只验带 -m 的显式 commit
+    msg = _extract_msg(command)
+    if not msg:
+        sys.exit(0)  # 提不到 -m（可能 -F 文件或 amend），不拦
+    if _REQ_TAG_RE.search(msg):
+        sys.exit(0)  # 含需求标记，放行
+
+    # 缺标记
+    block_mode = os.environ.get("WLCOMMIT_GATE_BLOCK", "").lower() in ("1", "true", "yes")
+    preview = msg.replace("\n", " ")[:100]
+    if block_mode:
+        sys.stderr.write(
+            '【wl-commit msg 门禁·硬拦】commit msg 缺需求关联标记:\n  %s\n'
+            '修复: git commit --amend 补 [#REQ-<uuid>] (S3) 或 [#<禅道号>] (S5.1 push 后)。\n'
+            '(此硬拦由 WLCOMMIT_GATE_BLOCK=1 开启；平台/工具/文档 commit 关该 env 或走非 wl-commit 流程。)\n'
+            % preview)
+        sys.exit(2)
+    # 默认 advisory：不阻断，强提醒
+    sys.stdout.write(
+        '⚠️ 【wl-commit msg 提醒】本次 commit msg 缺需求关联标记 [#REQ-xxx]/[#禅道号]:\n'
+        '  %s\n'
+        '若这是 /wl-commit 流程，建议 amend 补标记关联需求(F1 闭环数据)；'
+        '若是平台/工具/文档 commit 可忽略本提醒。\n' % preview)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as e:
+        _log_err("fatal: %s" % str(e)[:150])
+        sys.exit(0)  # 永不阻塞

package/templates/qoder/hooks/session-start.py

@@ -129,7 +129,7 @@ def get_index_info():
             recent = errors[-10:]  # 取最后 10 行检查
             if len(recent) >= 3:
                 lines.append('[WARN] hook 最近频繁失败 (%d 条错误), 详情见 .qoder/.runtime/hook-errors.log' % len(recent))
-                lines.append('  跑 python .qoder/scripts/setup/init_doctor.py --fix 排查')
+                lines.append('  跑 python .qoder/scripts/orchestration/wlkj.py doctor --fix 排查')
     except OSError:
         pass
 
@@ -289,6 +289,22 @@ def get_usability_summary():
     return NL.join(lines) if lines else ''
 
 
+def get_tool_guide():
+    """注入 tool_guide 精简版(共用工具用法关键执行位), 命令正文不再重复(单一信源, T1.2)。
+    完整版见 .qoder/scripts/tool_guide.md。纯静态文本, 失败绝不阻塞。"""
+    return NL.join([
+        '## Tool Guide (共用工具用法 · 完整见 .qoder/scripts/tool_guide.md)',
+        '环境自检(任何脚本前先跑, 定 R/$PY):',
+        '  R=$(python ~/.qoderwork/repo_root.py 2>/dev/null || python3 ~/.qoderwork/repo_root.py 2>/dev/null) || R=.',
+        '  PY=$(python --version >/dev/null 2>&1 && echo python || echo python3)',
+        '  后续统一 $PY "$R/.qoder/scripts/orchestration/wlkj.py" <命令>',
+        '接口三套名互通: wlkj.py / kg.py / MCP 名字都认(search/semantic/context/impact), 别因"未知子命令"慌',
+        '中文歧义词先提炼再查: 保险->车险/商业险/交强险 · 异常->告警/报错 · 计划->作业/养护',
+        '禁全盘扫: 不要 find / grep -r / findstr /s / os.walk data/code, 那是知识层 search 的活',
+        '优先级口诀: 精确搜用Grep · 语义找用rag_search · 取全用context_pack · 查库先list_envs · 影响用get_impact',
+    ])
+
+
 def main():
     parts = []
     parts.append('<qoder-context>')
@@ -345,6 +361,9 @@ def main():
         parts.append('')
         parts.append(style_info)
 
+    parts.append('')
+    parts.append(get_tool_guide())
+
     parts.append('</qoder-context>')
     # Hook-1: 健康标记 — AI 能感知 hook 是否真的跑了
     # QoderWork/Quest 里看不到 [hook-ok] 就知道 hook 没生效, 要自取上下文

package/templates/qoder/hooks/stop-eval.py

@@ -179,6 +179,127 @@ def _last_record_by_prd():
     return last_by_prd
 
 
+def _enforce_code_ac_gate():
+    """P0-3: wl-code spec AC 门禁。找近 spec + eval_code_ac.py 对账, AC<100% 阻断。
+
+    治"代码漏实现 spec AC"（wl-code 自检全打勾反例）。无 spec / 脚本缺失 / 崩溃 → 放行(不阻塞)。
+    """
+    import subprocess
+    qoder_script = os.path.join(BASE, '.qoder', 'scripts', 'validation', 'metrics', 'eval_code_ac.py')
+    pkg_script = os.path.join(BASE, 'packages', 'wlkj', 'templates', 'qoder',
+                              'scripts', 'validation', 'metrics', 'eval_code_ac.py')
+    script = qoder_script if os.path.isfile(qoder_script) else pkg_script
+    if not os.path.isfile(script):
+        return  # 脚本不在, 放行
+    try:
+        r = subprocess.run([sys.executable, script], cwd=BASE,
+                           capture_output=True, text=True, timeout=30)
+    except Exception:
+        return  # 崩溃绝不阻塞
+    if r.returncode != 2:
+        return  # exit 0 = 无 spec / AC 全覆盖, 放行
+    out_lines = [l for l in (r.stdout or '').split('\n') if l.strip()]
+    try:
+        data = json.loads(out_lines[-1]) if out_lines else {}
+    except Exception:
+        data = {}
+    missed = data.get('missed', []) or []
+    rate = data.get('rate', 0)
+    miss_str = '\n'.join('  - ' + str(m)[:80] for m in missed[:5])
+    sys.stderr.write(
+        '【wl-code AC 门禁】检测到 spec 验收标准未被代码覆盖 (覆盖率 %s%%):\n%s\n'
+        '修复: 对照 spec 第6章 PRD 验收标准映射表, 把未实现的 AC 补进代码, 重跑至 100%%。\n'
+        % (int(rate * 100), miss_str))
+    sys.exit(2)
+
+
+def _enforce_cases_lint_gate():
+    """P0-3 w2: wl-test cases 格式门禁。扫近 10min cases 文件(含 intent/action/anchor 键的 json),
+    跑 lint_cases.py，旧格式(action+CSS selector) → exit 2。无 cases/脚本缺/崩溃 → 放行(不阻塞)。"""
+    import subprocess
+    qoder_script = os.path.join(BASE, '.qoder', 'scripts', 'validation', 'metrics', 'lint_cases.py')
+    pkg_script = os.path.join(BASE, 'packages', 'wlkj', 'templates', 'qoder',
+                              'scripts', 'validation', 'metrics', 'lint_cases.py')
+    script = qoder_script if os.path.isfile(qoder_script) else pkg_script
+    if not os.path.isfile(script):
+        return
+    now = time.time()
+    cases_files = []
+    for root in (os.path.join(BASE, 'workspace', 'members'), os.path.join(BASE, 'workspace', 'tasks')):
+        if not os.path.isdir(root):
+            continue
+        for dirpath, dirs, files in os.walk(root):
+            dirs[:] = [d for d in dirs if d not in ('node_modules', '.git', '__pycache__', '.secrets')]
+            for fn in files:
+                if not fn.endswith('.json'):
+                    continue
+                fp = os.path.join(dirpath, fn)
+                try:
+                    if now - os.path.getmtime(fp) > 600:
+                        continue
+                except OSError:
+                    continue
+                try:
+                    head = open(fp, encoding='utf-8', errors='replace').read(2000)
+                except Exception:
+                    continue
+                if '"intent"' in head or '"action"' in head or '"anchor"' in head:
+                    cases_files.append(fp)
+    for fp in cases_files[:5]:
+        try:
+            r = subprocess.run([sys.executable, script, fp, '--json'], cwd=BASE,
+                               capture_output=True, text=True, timeout=15)
+        except Exception:
+            continue
+        if r.returncode != 2:
+            continue
+        out_lines = [l for l in (r.stdout or '').split('\n') if l.strip()]
+        try:
+            data = json.loads(out_lines[-1]) if out_lines else {}
+        except Exception:
+            data = {}
+        blocks = [v for v in (data.get('violations') or []) if v.get('severity') == 'BLOCK']
+        if blocks:
+            detail = '\n'.join('  - case#%s %s' % (v.get('idx'), str(v.get('detail', ''))[:60]) for v in blocks[:5])
+            sys.stderr.write(
+                '【wl-test cases 门禁】%s 检测到旧格式用例(action+CSS selector，新 Playwright 管线不认):\n%s\n'
+                '修复: 改 intent+anchor 格式，anchor={role,name}(来自 recall/snapshot)，凭据用 {{ask:key}}。\n'
+                % (os.path.basename(fp), detail))
+            sys.exit(2)
+
+
+def _enforce_commit_msg_gate():
+    """P0-3 w3: wl-commit msg 门禁。近 30min commit msg 须含 [#REQ-xxx] 或 [#禅道号]。
+
+    治"commit 不关联需求"（F1 闭环数据断）。memory commit-convention-zentao-id:
+    S3 [#REQ-<uuid8>] / S5.1 push 后 [#<禅道号>]。无标记 → exit 2 提示 amend。
+    """
+    import re as _re
+    import subprocess
+    try:
+        r = subprocess.run(['git', 'log', '-1', '--format=%B|||%ct'], cwd=BASE,
+                           capture_output=True, text=True, timeout=10)
+        out = (r.stdout or '').strip()
+    except Exception:
+        return  # 崩溃不阻塞
+    if '|||' not in out:
+        return
+    msg, _, ts_s = out.rpartition('|||')
+    try:
+        ts = int(ts_s)
+    except ValueError:
+        ts = 0
+    if ts and time.time() - ts > 1800:
+        return  # 非本轮 commit
+    if _re.search(r'\[#REQ-[\w-]+\]|\[#\d+\]', msg):
+        return  # 含需求标记, 放行
+    sys.stderr.write(
+        '【wl-commit msg 门禁】最近 commit msg 缺需求关联标记:\n  %s\n'
+        '修复: git commit --amend 补 [#REQ-<uuid>] (S3) 或 [#<禅道号>] (S5.1 push 后)。\n'
+        % msg.replace('\n', ' ')[:120])
+    sys.exit(2)
+
+
 def main():
     try:
         data = _read_stdin()
@@ -186,6 +307,14 @@ def main():
         if _is_reentry(data):
             sys.exit(0)
 
+        # ★ P0-3 wl-code spec AC 门禁（代码漏实现 AC 检测, 治自检全打勾）
+        _enforce_code_ac_gate()
+        # P0-3 w2 wl-test cases 格式门禁（旧 action+CSS selector → 拦）
+        _enforce_cases_lint_gate()
+        # w3 wl-commit msg 门禁: 应在 pre-tool-use（git commit 命令前验 msg）而非 stop-eval——
+        # stop-eval 的 git log -1 不分"本轮 wl-commit"vs 其他 commit, 会在平台开发等非 wl-commit
+        # 场景误拦。函数 _enforce_commit_msg_gate 已定义待 pre-tool-use 细化接入。
+
         # 找近 10 分钟产出的 PRD, 检查是否已【通过】门禁
         recent = _recent_prd_files()
         if not recent:

package/templates/qoder/scripts/capability/adapters/mcp.py

@@ -21,6 +21,7 @@ McpMemoryProvider：memory 职责链的 MCP provider，接通 kg.duckdb learning
 """
 from __future__ import annotations
 
+import json
 from typing import Any, Optional
 
 from ..registry_mcp import McpRegistry, _load_servers

package/templates/qoder/scripts/capability/registry.py

@@ -17,10 +17,7 @@ import os
 from typing import Any
 
 from .caps import (
-    NoOpCronCap,
-    NoOpNotifyCap,
     NoOpPresentCap,
-    NoOpSandboxCap,
 )
 
 

package/templates/qoder/scripts/domain/integration/return_to_platform.py

@@ -35,6 +35,7 @@ def _load_mcp_config() -> dict:
     except Exception:
         repo = Path(__file__).resolve().parent.parent.parent.parent.parent
     for cand in [
+        repo / ".qoder" / "mcp_config.json",  # ★ switch_project 写这里，优先查（否则读不到 token → 回流误报"无 X-Engine-Token"）
         repo / "mcp_config.json",
     ]:
         try:

package/templates/qoder/scripts/domain/integration/spec_upload.py

@@ -5,7 +5,7 @@
 契约: wlinkj-workspace/docs/SPEC-MCP-CONTRACT.md v1（create/confirm/update/get_spec）
 
 流程: 解析契约头 → 有platform_spec_id走update/无走create → confirm → 回写幂等锚
-传输: POST /mcp direct JSON-RPC + X-MCP-Token（同 engine/poller.py:_mcp_call）
+传输: POST /mcp direct JSON-RPC + X-MCP-Token 头
 """
 from __future__ import annotations
 import json, os, re, sys, urllib.request, urllib.error
@@ -24,8 +24,8 @@ def _load_mcp_config() -> dict:
         repo = get_repo_root()
     except Exception:
         repo = Path(__file__).resolve().parent.parent.parent.parent.parent
-    for cand in [repo / "mcp_config.json",
-                 repo / ".qoder" / "mcp_config.json"]:
+    for cand in [repo / ".qoder" / "mcp_config.json",  # ★ switch_project 写这里，优先（同 return_to_platform，否则可能读到 repo/ 旧文件）
+                 repo / "mcp_config.json"]:
         try:
             if cand.is_file():
                 with open(cand, encoding="utf-8") as f:

package/templates/qoder/scripts/domain/kg/build/build_entity_registry.py

@@ -1,17 +1,6 @@
 # -*- coding: utf-8 -*-
 """build_entity_registry.py — 从 ui-modules + code-api 构建 entity-registry.json。
 
-# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
-import os as _o, sys as _s
-_f = _o.path.abspath(__file__)
-for _ in range(10):
-    _f = _o.path.dirname(_f)
-    _cp = _o.path.join(_f, 'foundation')
-    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
-        break
-if _cp not in _s.path: _s.path.insert(0, _cp)
-from bootstrap import setup; setup()
-
 产出 data/index/_build_cache/entity-registry.json, 供 kg_duckdb 导入 entities/aliases 表,
 让 kg.py feature <功能名> 能返回功能画像。
 
@@ -34,6 +23,18 @@ from bootstrap import setup; setup()
 业务流程) 由 build_relations.py/build_features.py/build_workflows.py 补充,
 那些脚本未实现时不影响本脚本的 entity 基础层。
 """
+# v3.0 路径自举: 引导到 foundation/bootstrap, 统一 sys.path 逻辑
+# ⚠ 必须在 module docstring 之外! 旧版把这块包进 docstring → bootstrap 永不执行 → 跑死。
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
 import json
 import os
 import sys
@@ -41,7 +42,6 @@ from datetime import datetime
 
 # 路径自适应 (和兄弟脚本一致)
 THIS_DIR = os.path.dirname(os.path.abspath(__file__))
-sys.path.insert(0, os.path.join(THIS_DIR, '..'))
 from foundation.core.paths import DATA_INDEX_DIR, BUILD_CACHE_DIR
 
 

package/templates/qoder/scripts/domain/kg/build/build_relations.py

@@ -1,17 +1,6 @@
 # -*- coding: utf-8 -*-
 """build_relations.py — 从 trace-chain + code-api 推导关系边, 生成 relations.json。
 
-# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
-import os as _o, sys as _s
-_f = _o.path.abspath(__file__)
-for _ in range(10):
-    _f = _o.path.dirname(_f)
-    _cp = _o.path.join(_f, 'foundation')
-    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
-        break
-if _cp not in _s.path: _s.path.insert(0, _cp)
-from bootstrap import setup; setup()
-
 产出 data/index/_build_cache/relations.json, 供 kg_duckdb 导入 edges 表,
 让 kg.py feature 的端点/按钮数据非零, kg.py hop 多跳遍历有边可走。
 
@@ -32,13 +21,24 @@ from bootstrap import setup; setup()
   - code-api.json: {endpoint: controller_file} (api_to_controller 直接用)
   - test-assertions.json: tests (controller_to_tests 推导)
 """
+# v3.0 路径自举: 引导到 foundation/bootstrap, 统一 sys.path 逻辑
+# ⚠ 必须在 module docstring 之外! 旧版把这块包进 docstring → bootstrap 永不执行 → 跑死。
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
 import json
 import os
 import sys
 from datetime import datetime
 
 THIS_DIR = os.path.dirname(os.path.abspath(__file__))
-sys.path.insert(0, os.path.join(THIS_DIR, '..'))
 from foundation.core.paths import DATA_INDEX_DIR, BUILD_CACHE_DIR
 
 

package/templates/qoder/scripts/foundation/io/context_cache.py

@@ -0,0 +1,94 @@
+"""context_cache.py — 按 REQ-id 缓存 context_pack/rag_search 结果（T1.3 跨命令上下文缓存）。
+
+PRD→spec→code 链路里同一 REQ 反复拉同一份上下文（3 次 KG/MCP 往返）→ 缓存复用，省 token + 减反复搜。
+
+存储: workspace/specs/{REQ}/.context-cache.json
+结构: {query_hash: {"query":..., "text":..., "ts":...}}
+TTL 默认 24h（PRD/spec 改动后用 invalidate(req) 显式失效）。
+
+纯模块，无外部依赖；任何异常 fail-open（缓存坏了不影响主流程，调用方降级直拉）。
+"""
+import os
+import json
+import time
+import hashlib
+
+DEFAULT_TTL = 24 * 3600  # 24h
+
+
+def _repo_root():
+    """从本文件向上找含 workspace/ 或 .qoder/ 的目录作仓库根。"""
+    d = os.path.dirname(os.path.abspath(__file__))
+    for _ in range(7):
+        if os.path.isdir(os.path.join(d, "workspace")) or os.path.isdir(os.path.join(d, ".qoder")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            break
+        d = parent
+    return os.getcwd()
+
+
+def _sanitize(req_id):
+    return "".join(c for c in str(req_id) if c.isalnum() or c in "-_") or "unknown"
+
+
+def cache_path(req_id, base=None):
+    base = base or _repo_root()
+    return os.path.join(base, "workspace", "specs", _sanitize(req_id), ".context-cache.json")
+
+
+def _load(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+            return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save(path, data):
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        tmp = path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+        os.replace(tmp, path)  # 原子写
+        return True
+    except Exception:
+        return False
+
+
+def _qhash(query):
+    return hashlib.md5(query.strip().lower().encode("utf-8")).hexdigest()[:12]
+
+
+def get(req_id, query, ttl=DEFAULT_TTL, base=None):
+    """命中且未过期 → 返回 text；否则 None。"""
+    data = _load(cache_path(req_id, base))
+    entry = data.get(_qhash(query))
+    if not entry:
+        return None
+    if ttl and (time.time() - float(entry.get("ts", 0))) > ttl:
+        return None
+    return entry.get("text")
+
+
+def put(req_id, query, text, base=None):
+    """写一条缓存（覆盖同 query 旧值）。"""
+    path = cache_path(req_id, base)
+    data = _load(path)
+    data[_qhash(query)] = {"query": query, "text": text, "ts": time.time()}
+    return _save(path, data)
+
+
+def invalidate(req_id, base=None):
+    """清整个 REQ 的缓存（PRD/spec 改动后调）。"""
+    return _save(cache_path(req_id, base), {})
+
+
+def stats(req_id, base=None):
+    """缓存条数 + query 摘要（调试/观测命中率用）。"""
+    data = _load(cache_path(req_id, base))
+    return {"entries": len(data),
+            "queries": [str(e.get("query", ""))[:40] for e in data.values()]}

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

@@ -71,6 +71,7 @@ DISPATCH = {
     # ── 回流平台 (引擎产出 → 平台 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',
@@ -95,6 +96,7 @@ DISPATCH = {
     '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',
@@ -158,6 +160,95 @@ def _usage():
     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'):
@@ -170,6 +261,10 @@ def main():
     # 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 <脚本>')