@hupan56/wlkj 3.0.0 → 3.1.2

package/templates/qoder/scripts/protocol/transports/stdio.py

@@ -0,0 +1,293 @@
+# -*- coding: utf-8 -*-
+"""
+transports.stdio —— 本地 stdio MCP 传输策略（现状默认）。
+
+设计模式: Strategy（策略模式的本地实现）
+
+机制：
+    通过 mcp_launcher.py spawn 本地 MCP server 子进程，
+    维持 stdin/stdout 长连接，复 JSON-RPC 2.0 协议。
+    复用 mcp_base.py 已有的协议骨架，不重造轮子。
+
+进程复用 (Flyweight/Pool)：
+    每个 server 名对应一个 StdioTransport 实例，子进程长驻，
+    多次 call_tool 复用同一进程，避免冷启开销（kg 有 duckdb 冷启）。
+    子进程崩溃 (poll() != None) 自动重启。
+
+线程安全：
+    每个 transport 内部一把锁，保证请求-响应串行配对
+    （MCP 协议要求 id 匹配，并发交错会乱）。
+
+协议（与 mcp_base.py _handle 对齐）：
+    1. initialize 握手 → capabilities
+    2. notifications/initialized 通知
+    3. tools/list → 缓存工具清单
+    4. tools/call → 返回 content[0].text
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Optional
+
+from .base import ToolResult
+
+
+# MCP 协议版本（与 mcp_base.py:PROTOCOL_VERSION 对齐）
+_PROTOCOL_VERSION = "2024-11-05"
+
+# 读超时 (秒)。冷启动 + 握手 + tools/list 的总等待上限。
+# 历史 bug: readline 无超时会永久阻塞 —— 并发冷启动竞态下某 server 响应迟迟不来,
+# 整个 _build_index 的 ex.map 卡死或时序错乱 → 间歇性 0 工具。加超时后超时即失败可重试。
+_READ_TIMEOUT = 30.0
+
+
+def _get_repo_root() -> Path:
+    """从 common.paths 获取仓库根（复用既有工具，不重复造轮子）。"""
+    try:
+        from foundation.core.paths import get_repo_root
+        return get_repo_root()
+    except Exception:
+        return Path(__file__).resolve().parent.parent.parent.parent
+
+
+class StdioTransport:
+    """本地 stdio MCP 传输策略。
+
+    Args:
+        server_name: MCP server 名（对应 mcp_launcher 的参数，如 'kg'/'zentao'）。
+        repo_root: 仓库根（定位 mcp_launcher.py），默认自动探测。
+        launcher_subprocess_name: launcher 接受的子名（多数情况同 server_name）。
+    """
+
+    def __init__(self, server_name: str, repo_root: Optional[Path] = None,
+                 launcher_subprocess_name: Optional[str] = None):
+        self._server = server_name
+        self._launcher_arg = launcher_subprocess_name or server_name
+        self._repo = repo_root or _get_repo_root()
+        self._proc: Optional[subprocess.Popen] = None
+        self._lock = threading.RLock()  # 可重入：_send_recv→_ensure_alive→_spawn 会递归加锁
+        self._tools_cache: Optional[list[dict]] = None
+        self._tool_index: Optional[set[str]] = None
+        self._req_id = 0
+        self._err: Optional[str] = None
+        self._handshook = False
+        self._stderr_lines: list[str] = []      # 排水收集（诊断用）
+        self._stderr_thread: Optional[threading.Thread] = None
+
+    @property
+    def available(self) -> bool:
+        """此 transport 是否可用（子进程能拉起 + 握手成功）。"""
+        if self._err is not None:
+            return False
+        return self._ensure_alive()
+
+    # ------------------------------------------------------------------
+    # 进程管理
+    # ------------------------------------------------------------------
+
+    def _launcher_path(self) -> Path:
+        return self._repo / ".qoder" / "scripts" / "protocol" / "mcp" / "mcp_launcher.py"
+
+    def _ensure_alive(self) -> bool:
+        """确保子进程存活且已握手。返回是否就绪。"""
+        if self._proc is not None and self._proc.poll() is None and self._handshook:
+            return True
+        return self._spawn()
+
+    def _spawn(self) -> bool:
+        """spawn 子进程并握手。失败记 _err。"""
+        launcher = self._launcher_path()
+        if not launcher.is_file():
+            self._err = "mcp_launcher.py 不存在: %s" % launcher
+            return False
+        try:
+            self._proc = subprocess.Popen(
+                [sys.executable, str(launcher), self._launcher_arg],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                cwd=str(self._repo),
+                bufsize=1,
+                encoding="utf-8",
+                errors="replace",
+                # 关键：关掉 Python 子进程的 stdin 缓冲，避免 launcher in-proc 模式下
+                # runpy.run_path 的 server 读 stdin 时和 pipe 缓冲交互异常。
+                # text 模式下 close_fds 在 Win 上受限，但 PIPE 已隔离。
+            )
+        except Exception as e:
+            self._err = "拉起失败: %s" % str(e)[:120]
+            self._proc = None
+            return False
+
+        # 排空 stderr：launcher/server 诊断输出多，不排会撑满 pipe 缓冲阻塞 server。
+        # 守护线程持续读（与裸 subprocess 复刻保持一致的极简形态，先保证不阻塞）。
+        proc_ref = self._proc  # 闭包捕获局部引用，避免 self._proc 重赋值竞态
+        stderr_ref = self._stderr_lines
+        def _drain():
+            assert proc_ref is not None and proc_ref.stderr is not None
+            try:
+                for line in proc_ref.stderr:
+                    stderr_ref.append(line.rstrip())
+                    if len(stderr_ref) > 200:
+                        del stderr_ref[:-100]
+            except Exception:
+                pass
+        self._stderr_thread = threading.Thread(target=_drain, daemon=True)
+        self._stderr_thread.start()
+
+        # 握手 initialize（直接底层收发，不走 _send_recv——避免 _ensure_alive 递归 _spawn）
+        with self._lock:
+            try:
+                req = {"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                       "params": {"capabilities": {}, "protocolVersion": _PROTOCOL_VERSION,
+                                  "clientInfo": {"name": "nexus", "version": "1.0"}}}
+                self._write(req)
+                resp = self._readline_matching(1)
+                if "result" not in resp:
+                    self._err = "initialize 无 result: %s" % str(resp)[:120]
+                    self._kill_unlocked()
+                    return False
+                # 发 initialized 通知（无 id，无响应）
+                self._write({"jsonrpc": "2.0", "method": "notifications/initialized"})
+                self._handshook = True
+                # 握手后重置 tools 缓存（新进程）
+                self._tools_cache = None
+                self._tool_index = None
+                return True
+            except Exception as e:
+                self._err = "握手失败: %s" % str(e)[:120]
+                self._kill_unlocked()
+                return False
+
+    def _kill_unlocked(self) -> None:
+        """_kill 的无锁版本（调用方已持锁，如 _spawn 内握手失败清理）。"""
+        if self._proc is not None:
+            try:
+                self._proc.stdin.close()
+            except Exception:
+                pass
+            try:
+                self._proc.terminate()
+                self._proc.wait(timeout=2)
+            except Exception:
+                try:
+                    self._proc.kill()
+                except Exception:
+                    pass
+            self._proc = None
+        self._handshook = False
+
+    def _kill(self) -> None:
+        """杀子进程（持锁版本，close/外部调用用）。"""
+        with self._lock:
+            self._kill_unlocked()
+
+    # ------------------------------------------------------------------
+    # JSON-RPC 收发
+    # ------------------------------------------------------------------
+
+    def _next_id(self) -> int:
+        self._req_id += 1
+        return self._req_id
+
+    def _write(self, obj: dict) -> None:
+        """写一行 JSON 到 stdin（调用方持锁）。"""
+        if self._proc is None or self._proc.stdin is None:
+            raise RuntimeError("子进程未就绪")
+        self._proc.stdin.write(json.dumps(obj, ensure_ascii=False) + "\n")
+        self._proc.stdin.flush()
+
+    def _readline_matching(self, rid: int, timeout: float = _READ_TIMEOUT) -> dict:
+        """读 stdout 直到拿到匹配 rid 的响应（跳过通知/其他行），带 wall-clock 超时。
+
+        实测结论 (2026-06): 用裸 subprocess 并发 spawn 4 个 server, 阻塞 readline 全部
+        在 2-5s 内成功 (kg/zentao/mysql/lanhu)。原版阻塞 readline 本身没问题。
+        故保持阻塞读, 仅加进程存活检查 (poll) + wall-clock 超时兜底 (防极端卡死):
+        - readline 返回空 (EOF) 且进程已死 → 立即失败
+        - 累计耗时超 timeout → 失败 (上层 _build_index 空索引可重试)
+        之前尝试的"后台 reader 线程"版反而在并发下引入竞态 (与 _drain stderr 线程争用),
+        导致全部 30s 超时, 已废弃。
+        """
+        import time
+        assert self._proc is not None and self._proc.stdout is not None
+        deadline = time.monotonic() + timeout
+        while True:
+            line = self._proc.stdout.readline()
+            if not line:
+                # EOF: 进程已退出或关连接
+                raise RuntimeError("MCP server 关闭连接 (EOF)")
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                resp = json.loads(line)
+            except json.JSONDecodeError:
+                continue  # 非 JSON 行（诊断输出等）跳过
+            if resp.get("id") == rid:
+                return resp
+            # 非 id 匹配（通知/其他响应）忽略，继续读
+            if time.monotonic() > deadline:
+                raise RuntimeError("读响应超时 (rid=%s)" % rid)
+
+    def _send_recv(self, method: str, params: dict | None = None,
+                   req_id: int | None = None) -> dict:
+        """发请求读响应（线程安全，持锁）。"""
+        with self._lock:
+            if not self._ensure_alive():
+                raise RuntimeError("transport 不可用: %s" % (self._err or "未知"))
+            rid = req_id if req_id is not None else self._next_id()
+            req = {"jsonrpc": "2.0", "id": rid, "method": method}
+            if params is not None:
+                req["params"] = params
+            try:
+                self._write(req)
+                return self._readline_matching(rid)
+            except Exception:
+                # 通信失败，标记进程可疑，下次 _ensure_alive 会重 spawn
+                self._handshook = False
+                raise
+
+    # ------------------------------------------------------------------
+    # Transport 接口实现
+    # ------------------------------------------------------------------
+
+    def list_tools(self) -> list[dict]:
+        """枚举工具（缓存，每个进程只查一次）。"""
+        if self._tools_cache is not None:
+            return self._tools_cache
+        resp = self._send_recv("tools/list")
+        tools = resp.get("result", {}).get("tools", [])
+        self._tools_cache = tools
+        self._tool_index = {t.get("name", "") for t in tools}
+        return tools
+
+    def has_tool(self, name: str) -> bool:
+        if self._tool_index is None:
+            try:
+                self.list_tools()
+            except Exception:
+                return False
+        return name in (self._tool_index or set())
+
+    def call_tool(self, name: str, args: dict | None = None) -> ToolResult:
+        try:
+            resp = self._send_recv("tools/call", {"name": name, "arguments": args or {}})
+        except Exception as e:
+            return ToolResult(text="transport 调用失败: %s" % str(e)[:120], is_error=True)
+
+        if "error" in resp:
+            msg = resp["error"].get("message", "unknown error")
+            return ToolResult(text=str(msg), is_error=True, raw=resp)
+
+        result = resp.get("result", {})
+        content = result.get("content", [])
+        text = content[0].get("text", "") if content else ""
+        return ToolResult(text=text, is_error=result.get("isError", False), raw=resp)
+
+    def close(self) -> None:
+        self._kill()  # _kill 内部自行加锁

package/templates/qoder/scripts/run_weekly_update.bat

@@ -1,22 +1,31 @@
 @echo off
-REM QODER Weekly Knowledge Graph Update
-REM Runs every Friday at 18:00
-REM %~dp0 = this script directory; project root is two levels up
-
+REM QODER Weekly Knowledge Graph Update (Windows)
+REM Runs every Friday at 18:00. %~dp0 = this script dir; project root = 2 levels up (安装后 .qoder/scripts/ 上2级)
+REM v3.x: 走 wlkj.py 单一真源调度器 (不再用扁平路径, 防引擎分层重组后断链)
+REM       重建后自动 commit + git gc (普通模式), 防松散对象膨胀 (见 ARCHITECTURE.md)
 cd /d "%~dp0..\.."
-
-echo [%date% %time%] Starting weekly update... >> .qoder\logs\weekly-update.log
-
-REM Step 1: Git pull + PRD collect + Index rebuild
-python .qoder\scripts\git_sync.py >> .qoder\logs\weekly-update.log 2>&1
-
-REM Step 2: Rebuild style index (layout fingerprint + module index + page patterns).
-REM git_sync only rebuilds keyword/api/module indexes; style index must be rebuilt
-REM separately so layout_fingerprint/module-index pick up code changes each week.
-python .qoder\scripts\build_style_index.py >> .qoder\logs\weekly-update.log 2>&1
-
+if not exist ".qoder\scripts\orchestration\wlkj.py" (
+  echo [ERROR] 引擎未安装, 请先 npx @hupan56/wlkj init
+  exit /b 1
+)
+set LOG=.qoder\logs\weekly-update.log
+if not exist ".qoder\logs" mkdir ".qoder\logs"
+echo [%date% %time%] Starting weekly update... >> "%LOG%"
+REM Step 1: Git pull + PRD collect
+python .qoder\scripts\orchestration\wlkj.py git-sync >> "%LOG%" 2>&1
+REM Step 2: 重建组件级 style index (ui-style.json, 被 search/context_pack 消费, 不可删)
+python .qoder\scripts\orchestration\wlkj.py style >> "%LOG%" 2>&1
+REM Step 3: 知识图谱全量重建
+python .qoder\scripts\orchestration\wlkj.py kg-build >> "%LOG%" 2>&1
 if errorlevel 1 (
-    echo [%date% %time%] UPDATE FAILED - check log above >> .qoder\logs\weekly-update.log
-) else (
-    echo [%date% %time%] Update complete. >> .qoder\logs\weekly-update.log
+  echo [%date% %time%] UPDATE FAILED - check log above >> "%LOG%"
+  exit /b 1
 )
+REM Step 4: 提交重建产物 + git gc (防松散对象膨胀, kg.duckdb delta 压缩有效)
+echo [%date% %time%] Committing rebuilt graph + git gc... >> "%LOG%"
+git add data\index\kg.duckdb data\index\kg_db.duckdb data\index\ui-style.json >> "%LOG%" 2>&1
+git commit -m "[kg] weekly rebuild %date%" >> "%LOG%" 2>&1
+git gc --quiet >> "%LOG%" 2>&1
+echo [%date% %time%] gc done (松散对象已打包) >> "%LOG%"
+echo [%date% %time%] Update complete. >> "%LOG%"
+exit /b 0

package/templates/qoder/scripts/run_weekly_update.sh

@@ -1,25 +1,34 @@
 #!/usr/bin/env bash
 # QODER Weekly Knowledge Graph Update (macOS / Linux)
 # Runs every Friday at 18:00 via cron (see setup_weekly_cron.sh)
+# v3.x: 走 wlkj.py 单一真源调度器 (不再用扁平路径, 防引擎分层重组后断链)
+#       重建后自动 commit + git gc (普通模式), 防松散对象膨胀
 set -u
 cd "$(dirname "$0")/../.." || exit 1
-
+WLKJ=".qoder/scripts/orchestration/wlkj.py"
+if [ ! -f "$WLKJ" ]; then
+  echo "[ERROR] 引擎未安装, 请先 npx @hupan56/wlkj init"
+  exit 1
+fi
 mkdir -p .qoder/logs
 LOG=.qoder/logs/weekly-update.log
-
 echo "[$(date '+%Y-%m-%d %H:%M:%S')] Starting weekly update..." >> "$LOG"
-
-python3 .qoder/scripts/git_sync.py >> "$LOG" 2>&1
-
-# Step 2: Rebuild style index (layout fingerprint + module index + page patterns).
-# git_sync only rebuilds keyword/api/module indexes; style index must be rebuilt
-# separately so layout_fingerprint/module-index pick up code changes each week.
-python3 .qoder/scripts/build_style_index.py >> "$LOG" 2>&1
+# Step 1: Git pull + PRD collect
+python3 "$WLKJ" git-sync >> "$LOG" 2>&1
+# Step 2: 重建组件级 style index (ui-style.json, 被 search/context_pack 消费, 不可删)
+python3 "$WLKJ" style >> "$LOG" 2>&1
+# Step 3: 知识图谱全量重建
+python3 "$WLKJ" kg-build >> "$LOG" 2>&1
 STATUS=$?
-
 if [ $STATUS -ne 0 ]; then
   echo "[$(date '+%Y-%m-%d %H:%M:%S')] UPDATE FAILED (exit $STATUS) - check log above" >> "$LOG"
-else
-  echo "[$(date '+%Y-%m-%d %H:%M:%S')] Update complete." >> "$LOG"
+  exit $STATUS
 fi
-exit $STATUS
+# Step 4: 提交重建产物 + git gc (防松散对象膨胀, kg.duckdb delta 压缩有效)
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] Committing rebuilt graph + git gc..." >> "$LOG"
+git add data/index/kg.duckdb data/index/kg_db.duckdb data/index/ui-style.json >> "$LOG" 2>&1
+git commit -m "[kg] weekly rebuild $(date +%Y-%m-%d)" >> "$LOG" 2>&1
+git gc --quiet >> "$LOG" 2>&1
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] gc done (松散对象已打包)" >> "$LOG"
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] Update complete." >> "$LOG"
+exit 0

package/templates/qoder/scripts/validation/eval/perf-report-2026-06-24.md

@@ -0,0 +1,139 @@
+# QoderWork 工作流性能报告（v2 — 聚焦工作流本身）
+
+> 剔除模型抖动（reason=error）和首 token 延迟，只看**工作流自身的效率**。
+> 数据：2026-06-24 用户手动实跑 `/wl-*` 命令的真实 transcript。
+
+## 核心结论：问题不在慢，在"碎"
+
+工作流最大的低效不是单次调用慢，而是 **AI 在用"挤牙膏"式串行摸索**——
+每个文件/脚本单独调一次 Bash，调完思考一轮，再调下一个。
+
+实测每个 skill 都在**重复调用同一个目标**：
+
+| Skill | 重复调用 | 次数 | 现象 |
+|-------|---------|------|------|
+| /wl-search | `kg.py`（知识图谱） | **×5** | 同一个脚本连调5遍 |
+| /wl-status | `ls 目录` | **×5** | 反复 ls 探路 |
+| /wl-status | `cat 文件` | **×5** | 配置/任务/反馈一个一个 cat |
+| /wl-task | `task.py` | **×3** | 同脚本3次 |
+| /wl-insight | `search_index.py` | ×2 | 同脚本2次 |
+
+**对比基线**：简单命令（prd-quick / prd-review）只需 **1 轮迭代、0 次工具调用**，44s 完成。
+复杂命令却要 **5-6 轮迭代、7-10 次调用**——多出来的全是碎片化摸索。
+
+## 碎片化的真实样子（/wl-status 为例）
+
+```
+轮1: TodoWrite(列计划)
+     Bash: repo_root.py        ← 找根目录(每次都找)
+     Bash: ls .qoder/          ← 探路
+轮2: TodoWrite(更新)
+     Bash: cat .developer      ← 查身份
+     Bash: ls tasks/           ← 列任务
+     Bash: cat feedback.jsonl  ← 查反馈
+     Bash: cat eval-history    ← 查评估
+     Bash: cat .index-meta     ← 查索引元数据
+轮3: TodoWrite(更新)
+     Bash: ls members/hupan56/ ← 查成员
+     Bash: ls patterns/        ← 查模式
+     Bash: cat config.yaml     ← 查配置
+轮4-5: ...
+```
+
+8 个 `cat`/`ls` 本可以**合并成 1 个脚本**一次拿全，却拆成 5 轮、10+ 次调用。
+
+## 迭代轮数 = 成本放大器
+
+每多一轮迭代，就多一次：
+- 完整的模型请求（输入 token = 之前所有上下文累加）
+- 工具往返延迟
+- TodoWrite 进度更新（本身也占一次调用）
+
+| 命令 | 迭代轮 | 工具调用 | vs 基线 |
+|------|--------|---------|---------|
+| prd-quick（基线） | **1** | 0 | — |
+| /wl-task | 2 | 1-2 | 2× |
+| /wl-report | 2 | 2 | 2× |
+| /wl-insight | 3 | 4 | 3× |
+| /wl-status | **5** | 10 | **5×** |
+| /wl-search | **6** | 7-9 | **6×** |
+
+迭代轮数和 token 消耗是**指数关系**——第 N 轮要把前 N-1 轮的所有内容重新喂给模型。
+6 轮迭代 ≈ 把上下文喂了 6 遍。
+
+## 优化方案（按收益排序）
+
+### P0：给每个 skill 写"一次拿全"的聚合脚本（砍 60-80% 调用）
+
+现状：AI 用 cat/ls 一个个摸。
+目标：一个脚本一次返回 skill 需要的所有数据。
+
+**`/wl-status` 示例**——合并成一个 `status_snapshot.py`：
+```python
+# 一次返回: 身份 + 任务 + 反馈 + 评估 + 索引 + 配置 + 成员
+# 现在: 8次 cat/ls + 5轮迭代
+# 优化后: 1次调用 + 1轮迭代
+```
+
+**`/wl-search` 示例**——kg.py 被调5次，应合并成一次：
+```python
+# 现在: kg.py search → kg.py api → kg.py impact → kg.py context → kg.py style (5次)
+# 优化: kg.py all-in-one "考勤" → 一次返回全部维度
+# (context_pack.py 本就是干这个的, 但 skill 没用足)
+```
+
+**预期**：迭代从 5-6 轮降到 1-2 轮，调用从 7-10 次降到 1-3 次。
+
+### P1：缓存"不变量"（身份/根目录/配置）
+
+`repo_root.py`、`cat .developer`、`cat config.yaml` 这些**会话内不变**的数据，
+每次命令都重新查。应缓存到环境变量或临时文件，session 内复用。
+
+现状 `/wl-status` 第一步永远是 `repo_root.py`——这是纯浪费。
+
+### P2：强制 skill 用 Fast Path（context_pack）
+
+AGENTS.md 已写了 Fast Path：
+> `context_pack.py <业务词>` 一次返回 代码+页面+字段+PRD+API+样式
+
+但实测 `/wl-search` 没用它，而是连调 5 次 `kg.py`。
+应在 skill 指令里**强制**：搜索类命令第一步必须调 `context_pack.py`，禁止拆开调。
+
+### P3：砍掉冗余 TodoWrite
+
+实测 TodoWrite 占了 12% 调用。在 search/status 这类只读命令里，
+TodoWrite 纯粹是"给用户看进度"，但每次更新都消耗一次工具往返 + 触发新一轮模型思考。
+**建议**：只读命令不用 TodoWrite，或合并到最后一次性输出。
+
+### P4：飞轮闭环（持续优化）
+
+```
+你跑命令 → transcript 自动记录
+    ↓
+每周: python transcript_timing.py <session目录> --json
+    ↓
+对比上周: 迭代轮数↓了没? 调用次数↓了没?
+    ↓
+没降 → 继续优化对应 skill
+```
+
+前 3 环已通（采集→分析→归因）。缺"自动对比上周"脚本，可后续补。
+
+## 预期收益
+
+| 优化 | 迭代轮数 | 工具调用 | token |
+|------|---------|---------|-------|
+| 现状（/wl-status） | 5 | 10 | 基准 |
+| +P0 聚合脚本 | 2 | 3 | -50% |
+| +P1 缓存不变量 | 2 | 2 | -55% |
+| +P3 砍 TodoWrite | 2 | 1 | -60% |
+| **全做** | **1-2** | **1-2** | **-60%** |
+
+> 注：token 收益主要来自减少迭代轮数（少喂几遍上下文），
+> 而非单次调用的大小。
+
+## 落地优先级
+
+1. **先改 /wl-search 和 /wl-status**（最碎的两个，收益最大）
+2. 每个写一个聚合脚本，skill 指令改成"只调聚合脚本"
+3. 改完用 transcript_timing.py 验证：迭代和调用数应该明显下降