codebee 0.1.69 → 0.1.70

package/app/core/flows.py

@@ -9,10 +9,12 @@
 """
 from __future__ import annotations
 
+import base64
 import hashlib
 import json
 import re
 import threading
+import time
 
 from . import paths, volumes
 
@@ -50,7 +52,7 @@ BUILTIN_FLOWS = [
      "threshold": 7.0, "rounds": 2,
      "serial": {"chapters": 8, "words_per_chapter": 2500},
      "goal_hint": "题材/受众/卖点 + 总字数（例：2 万字都市女频，可签约平台）",
-     "note": "大纲 → 逐章起草 → 每章多维评审修订 → 全局一致性评审 → 合并（可断点续跑）"},
+     "note": "大纲 → 逐章起草 → 签约质量门禁（开篇/推进/文风/情感/节奏）→ 全局一致性评审 → 合并（可断点续跑）"},
     {"id": "article", "name": "自媒体文章", "icon": "i-news", "engine": "review", "builtin": True,
      "manuscript": "article.md",
      "rubric": ["选题与标题", "开头吸引力", "结构节奏", "平台适配", "传播性"],
@@ -296,11 +298,13 @@ def flow_drift(task):
     return {"flow": cur.get("id") or "", "pinned": pinned, "current": current}
 
 
-def upsert_flow(payload):
+def upsert_flow(payload, source="manual"):
     """新增/更新流程。返回 (flow, 错误)。
 
     - 预置流程 id：写入 overrides（可编辑、可恢复默认）；
-    - 新 id：创建自定义流程——**只需 name + engine**，其余字段留空走引擎默认。
+    - 新 id：创建自定义流程——**只需 name + engine**，其余字段留空走引擎默认；
+    - source：覆盖成因，进版本历史（manual=手动改 / import=分享码导入 /
+      restore=恢复操作顶下旧版）；语义与名字都相同则不产生历史噪音。
     """
     fid = str(payload.get("id") or "").strip()
     name = str(payload.get("name") or "").strip()
@@ -319,6 +323,7 @@ def upsert_flow(payload):
         ov.pop("id", None)
         ov["engine"] = base["engine"]   # 引擎不可改（避免语义错乱）
         merged = _apply_overrides(base, ov)
+        _push_history(fid, merged, source)
         with _LOCK:
             data = _read()
             ovs = data.get("overrides") if isinstance(data.get("overrides"), dict) else {}
@@ -362,6 +367,7 @@ def upsert_flow(payload):
     elif engine == "code":
         flow["verify_command"] = str(payload.get("verify_command") or "")[:200]
     # direct：无流程参数（目标+附件即全部输入）
+    _push_history(fid, flow, source)
     with _LOCK:
         data = _read()
         flows = data.get("flows") if isinstance(data.get("flows"), list) else []
@@ -399,3 +405,222 @@ def reset_flow(flow_id):
             data["overrides"] = ovs
             _write(data)
     return None
+
+
+# ---- 流程分享码（参考 Dify 模板中心 / n8n workflow 模板的可分发思路）----
+# 把「流程」变成可分发资产：导出为一段可粘贴的分享码，对方在任务类型管理里
+# 粘贴导入即装。码体 = 前缀 + urlsafe base64(JSON)，无签名——分享码本来就
+# 是明文可读的信封，导入时过 upsert_flow 全套规范化，坏数据进不来。
+
+_SHARE_PREFIX = "CBFLOW1."
+_SHARE_KIND = "codebee-flow"
+# 导出字段白名单：与 _EDITABLE 对齐 + 身份/展示字段。builtin 标记不导出
+# （对端是否预置由对端的 BUILTIN_FLOWS 决定，不能跨机携带）。
+_SHARE_FIELDS = ("id", "name", "engine", "icon", "goal_hint", "note",
+                 "manuscript", "rubric", "threshold", "rounds", "best_of",
+                 "serial", "draft_prompt", "critique_prompt", "verify_command")
+
+
+def export_flow_code(flow_id):
+    """导出流程为分享码。返回 (code, 错误)。"""
+    f = get_flow(str(flow_id or "").strip())
+    if not f:
+        return None, "流程不存在"
+    payload = {"kind": _SHARE_KIND, "v": 1,
+               "flow": {k: f.get(k) for k in _SHARE_FIELDS if k in f}}
+    blob = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+    return _SHARE_PREFIX + base64.urlsafe_b64encode(blob.encode("utf-8")).decode("ascii"), None
+
+
+def _decode_share_code(code):
+    """分享码 → (flow_in, 错误)。解码与校验共用（preview / import 两步走）。"""
+    if not isinstance(code, str) or not code.strip().startswith(_SHARE_PREFIX):
+        return None, "不是有效的 CodeBee 流程分享码（应以 %s 开头）" % _SHARE_PREFIX
+    raw = code.strip()[len(_SHARE_PREFIX):].strip()
+    try:
+        blob = base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4))
+        payload = json.loads(blob.decode("utf-8"))
+    except Exception:
+        return None, "分享码解析失败（可能被截断或篡改）"
+    if not isinstance(payload, dict) or payload.get("kind") != _SHARE_KIND:
+        return None, "分享码内容不是 CodeBee 流程"
+    flow_in = payload.get("flow")
+    if not isinstance(flow_in, dict):
+        return None, "分享码缺少流程定义"
+    if not str(flow_in.get("id") or "").strip():
+        return None, "分享码缺少流程 ID"
+    return flow_in, None
+
+
+def preview_flow_code(code):
+    """分享码两步导入的第一步：解析并预览，不落盘。
+
+    返回 (预览, 错误)：预览带流程定义摘要 + 与现有同 ID 流程的冲突提示。"""
+    flow_in, err = _decode_share_code(code)
+    if err:
+        return None, err
+    fid = str(flow_in.get("id") or "").strip()
+    existed = get_flow(fid)
+    preview = {"id": fid,
+               "name": str(flow_in.get("name") or "")[:20],
+               "engine": str(flow_in.get("engine") or "review"),
+               "rubric": flow_in.get("rubric") if isinstance(flow_in.get("rubric"), list) else [],
+               "threshold": flow_in.get("threshold"),
+               "rounds": flow_in.get("rounds"),
+               "has_prompts": bool(str(flow_in.get("draft_prompt") or "").strip()
+                                   or str(flow_in.get("critique_prompt") or "").strip()),
+               "serial": bool(isinstance(flow_in.get("serial"), dict)
+                              and flow_in.get("serial", {}).get("chapters")),
+               "exists": bool(existed),
+               "existing_name": (existed or {}).get("name") or "",
+               "builtin": bool(existed and existed.get("builtin"))}
+    return preview, None
+
+
+def import_flow_code(code):
+    """导入分享码。返回 (result, 错误)；result = {id, name, status, builtin}。
+
+    status：created=新建自定义流程；updated=覆盖已有定义（预置流程写
+    overrides，可「恢复默认」回滚）；noop=内容与现状完全一致。UI 走
+    preview_flow_code 预览确认后再进这里。"""
+    flow_in, err = _decode_share_code(code)
+    if err:
+        return None, err
+    fid = str(flow_in.get("id") or "").strip()
+    existed = get_flow(fid)
+    existed_digest = flow_digest(existed) if existed else ""
+    flow, err = upsert_flow(flow_in, source="import")
+    if err:
+        return None, err
+    if existed and flow_digest(flow) == existed_digest \
+            and flow.get("name") == existed.get("name"):
+        status = "noop"
+    else:
+        status = "updated" if existed else "created"
+    return {"id": fid, "name": flow.get("name"), "status": status,
+            "builtin": bool(existed and existed.get("builtin"))}, None
+
+
+# ---- 版本历史（Langfuse prompt management 借鉴）：提示词/参数改动可回滚 ----
+# 覆盖前的当前版自动快照进 data/flows_history.json（每流程 ≤_HISTORY_MAX 条），
+# 恢复=把历史版重新 upsert 回来；runs 已按 flow_revision（digest 前 16）对账，
+# 每版顺手给出实测战绩——「哪版提示词好用」不再靠感觉。
+
+_HISTORY_MAX = 10          # 每流程保留的历史版本数（新的顶旧的）
+
+
+def _history_read():
+    try:
+        data = json.loads((paths.DATA_DIR / "flows_history.json").read_text(encoding="utf-8"))
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _history_write(data):
+    paths.DATA_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = paths.DATA_DIR / "flows_history.json.tmp"
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    tmp.replace(paths.DATA_DIR / "flows_history.json")
+
+
+def _push_history(fid, new_flow, source):
+    """把「即将被覆盖的当前版」存进历史；语义与名字都相同则跳过（不产噪音）。"""
+    try:
+        cur = get_flow(fid)
+        if not cur:
+            return                                # 首次创建没有旧版可存
+        if flow_digest(cur) == flow_digest(new_flow) \
+                and cur.get("name") == new_flow.get("name"):
+            return
+        with _LOCK:
+            data = _history_read()
+            versions = data.get(fid) if isinstance(data.get(fid), list) else []
+            versions.insert(0, {"ts": time.strftime("%Y-%m-%d %H:%M:%S"),
+                                "source": str(source or "manual")[:16],
+                                "flow": {k: cur.get(k) for k in _SHARE_FIELDS if k in cur}})
+            data[fid] = versions[:_HISTORY_MAX]
+            _history_write(data)
+    except Exception:
+        pass                                       # 历史是增强，永远不挡保存
+
+
+_RUNS_PROVIDER = None      # main.py 启动注入 store.list_runs；flows(L0) 不反向
+                           # 依赖 store(L1)——静态图不成环（同 set_run_estimator 模式）
+
+
+def set_runs_provider(fn):
+    """注入 run 遍历器（应用入口传 store.list_runs）；未注入时版本无战绩。"""
+    global _RUNS_PROVIDER
+    _RUNS_PROVIDER = fn if callable(fn) else None
+
+
+def _flow_stats(digest16):
+    """该流程修订的实测战绩：任务数/通过率/均分（按 run 钉的 flow_revision 对账）。
+
+    均分分母只算有评分的 run；无记录返回 None。"""
+    try:
+        if not _RUNS_PROVIDER:
+            return None
+        runs = wins = scored_n = 0
+        total = 0.0
+        for run in (_RUNS_PROVIDER(limit=None) or []):
+            if not isinstance(run, dict):
+                continue
+            rev = str(((run.get("execution_snapshot") or {}).get("flow_revision")) or "")
+            if rev[:16] != digest16:
+                continue
+            runs += 1
+            v = run.get("verdict") or {}
+            if v.get("publishable") is True:
+                wins += 1
+            if isinstance(v.get("overall"), (int, float)):
+                total += float(v["overall"])
+                scored_n += 1
+        if not runs:
+            return None
+        return {"runs": runs, "pass_rate": round(wins / runs, 2),
+                "avg_overall": round(total / scored_n, 1) if scored_n else None}
+    except Exception:
+        return None
+
+
+def flow_versions(flow_id):
+    """给 UI 的版本清单：当前版在前，历史版新→旧；每版带 digest 与实测战绩。"""
+    fid = str(flow_id or "").strip()
+    out = []
+    cur = get_flow(fid)
+    if cur:
+        d = flow_digest(cur)[:16]
+        out.append({"current": True, "ts": "", "source": "current", "name": cur.get("name"),
+                    "digest": d, "stats": _flow_stats(d)})
+    for snap in _history_read().get(fid) or []:
+        d = flow_digest(snap.get("flow") or {})[:16]
+        out.append({"current": False, "ts": str(snap.get("ts") or ""),
+                    "source": str(snap.get("source") or "manual"),
+                    "name": (snap.get("flow") or {}).get("name"),
+                    "digest": d, "stats": _flow_stats(d)})
+    return out
+
+
+def restore_flow_version(flow_id, ts):
+    """恢复历史版本。返回 (flow, 错误)。
+
+    恢复动作本身也会把「被顶下来的当前版」存进历史（source=restore），
+    恢复错了还能再恢复回去；目标条目先从历史中消费掉再做 upsert——
+    ts 是秒级精度，顺序反了同秒快照会被误删。"""
+    fid = str(flow_id or "").strip()
+    ts = str(ts or "")
+    with _LOCK:
+        data = _history_read()
+        versions = data.get(fid) if isinstance(data.get(fid), list) else []
+        snap = next((s for s in versions if s.get("ts") == ts), None)
+        if snap:
+            data[fid] = [s for s in versions if s.get("ts") != ts]
+            _history_write(data)
+    if not snap:
+        return None, "历史版本不存在（可能已被消费）"
+    flow, err = upsert_flow(dict(snap.get("flow") or {}), source="restore")
+    if err:
+        return None, err
+    return flow, None

package/app/core/jobs.py

@@ -538,7 +538,11 @@ def cancel_event_for(run_id):
     return ev
 
 
-AUTO_RESUME_MAX = 3      # 连载任务自动续跑上限（超时/中断后自动接着写，无需人工）
+# 连载任务自动续跑上限（超时/中断后自动接着写，无需人工）。3 是 2026-09-25
+# 戍边骑奴 9-20·续2 案的上限：20 章连载 3 轮烧完次数后卡死在「任务总时限已到」
+# 等人工，而每轮都在稳定进章——止损已由零进度两轮同因止损兜底，上限只作
+# 最后保险（真烧钱还有日/月花费硬顶闸），10 轮足够 20 章慢链天跑完。
+AUTO_RESUME_MAX = 10
 AUTO_RESUME_DELAY_S = 300  # 自动续跑延迟入队秒数：网关限流/欠费窗口通常分钟级，
                            # 立即重排会撞在同一堵墙上把续跑次数烧光（2026-09-17 七猫实测）
 
@@ -589,6 +593,8 @@ def _maybe_auto_resume(run_id):
     终态写明死因，不再烧剩余的退避次数。超时例外：错误签名恒为同一句
     「任务总时限已到」，但每轮都在落章——本轮比上轮多过审了章就不算
     「同因无效重试」，续跑交给次数上限兜底；两轮一章未进则照常止损。
+    上限烧完时（超时且有进章）把已过审进度与断点续跑指引写进错误行，
+    别让执行结果卡读起来像白跑。
     """
     try:
         from . import store
@@ -601,6 +607,21 @@ def _maybe_auto_resume(run_id):
         if run.get("cancelled_by_user") or run.get("status") == "cancelled":
             return False   # 用户主动取消的运行绝不自动续跑
         if int(run.get("auto_resumes") or 0) >= AUTO_RESUME_MAX:
+            # 上限烧完不再续跑。但「任务总时限已到」+本轮有进章时，错误行必须
+            # 带上进度与续跑方式——不然执行结果卡只写「任务总时限已到」，读起来
+            # 像白跑（2026-09-25 续2 案：用户看到 64/64 步+超时以为续跑没生效）。
+            if run.get("status") == "timeout" and _serial_progress(run) > 0:
+                try:
+                    total = int((task.get("serial") or {}).get("chapters") or 0)
+                    where = ("/" + str(total) + " 章") if total > 0 else " 章"
+                    store.update_run(
+                        run_id,
+                        error=(run.get("error") or "")
+                        + "｜自动续跑次数已用完，已过审 "
+                        + str(_serial_progress(run)) + where
+                        + "；点重试将从断点继续，已过审章不会重写")
+                except Exception:
+                    pass
             return False
         prev_id = run.get("auto_resumed_from")
         if prev_id:

package/app/core/manager.py

@@ -2089,6 +2089,27 @@ def check_updates_async(force=False):
     return len(entries)
 
 
+def upgrade_all_targets():
+    """「一键升级全部」的目标条目，按目录顺序返回。
+
+    只收同时满足：已安装 + 配了 upgrade 命令（op=upgrade 硬依赖该字段，
+    没配的跟单条一样不出「升级」按钮）+ 更新检查不是「已是最新」。
+    检查结果为 unknown（还没查）/ unsupported（渠道查不了）的也升级——
+    npm/pip 的升级命令幂等，宁可空跑一次也不漏升；唯一跳过「已是最新」，
+    防无谓重装（重装易撞 EBUSY 文件锁）。
+    """
+    detected = detect_all()
+    out = []
+    for e in catalog.load():
+        det = (detected or {}).get(e["id"]) or {}
+        if not det.get("installed") or not e.get("upgrade"):
+            continue
+        if update_info(e).get("status") == "current":
+            continue
+        out.append(e)
+    return out
+
+
 def catalog_view():
     """管理页数据：catalog + 检测 + 版本 + 模型 + 编排启用状态。"""
     from . import registry

package/app/core/market_remote.py

@@ -1039,6 +1039,15 @@ def preview_remote(entry_id):
         _PREVIEW_CACHE[token] = {"entry_id": entry_id, "files": files,
                                  "stripped": stripped, "ts": time.time()}
         file_list = sorted(files.items(), key=lambda kv: kv[0])
+        # 内容安检（ClawHavoc 投毒案借鉴）：对全部技能文本跑危险模式扫描，
+        # 风险随预览返回——UI 高风险红字确认；发现列表给行号可定位。
+        try:
+            from . import skill_scan
+            risk_findings = skill_scan.scan_text(
+                "\n".join(str(v) for v in files.values()))
+            risk_label = skill_scan.risk_label(risk_findings)
+        except Exception:
+            risk_findings, risk_label = [], ""
         return {
             "token": token, "id": entry_id, "title": entry["title"],
             "source": entry["source_name"], "version": entry["version"],
@@ -1048,6 +1057,7 @@ def preview_remote(entry_id):
             "total_chars": sum(len(v) for v in files.values()),
             "file_list": [{"path": k, "chars": len(v)} for k, v in file_list[:60]],
             "stripped": sorted(stripped)[:40], "stripped_total": len(stripped),
+            "risk_label": risk_label, "risk_findings": risk_findings[:8],
             "expires_in": _PREVIEW_TTL,
         }, None
     except ValueError as e:

package/app/core/mcp_client.py

@@ -0,0 +1,287 @@
+# -*- coding: utf-8 -*-
+"""内置智能体的 MCP 客户端（Model Context Protocol，stdio 形态）。
+
+零依赖：JSON-RPC 2.0 走子进程 stdin/stdout（按行分帧——MCP stdio 传输约定）。
+每次工具调用重新拉起服务器进程：没有长驻会话要管，冷启动成本对内置智能体
+的低频工具循环可接受；进程用完即关（finally 杀树），绝不留孤儿。
+
+配置（settings.mcp_servers，JSON 数组字符串，≤4 个服务器）：
+  [{"name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fs", "C:/x"],
+    "env": {"KEY": "v"}}]
+name 用于工具名前缀（mcp__<name>__<tool>），必须 [a-z0-9_-]。
+
+安全口径：服务器命令是用户在本机自己配置的（与内置智能体 run_command 同一
+自主权级别）；本模块只做传输与解析，不校验工具语义。工具清单按服务器缓存
+（TTL 300s）——每次对话请求重建 tools 列表时不能每次都冷启动全量服务器。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import threading
+import time
+
+_LOCK = threading.RLock()
+_TOOLS_CACHE = {}          # server_key → (ts, tools)
+_TOOLS_TTL = 300.0
+
+MAX_SERVERS = 4
+MAX_MCP_TOOLS = 24         # 全部服务器合计注入内置智能体的工具数上限
+_NAME_RE = re.compile(r"^[a-z0-9_-]{1,24}$")
+_INIT_TIMEOUT = 15.0
+_CALL_TIMEOUT = 60.0
+_CALL_TIMEOUT_MAX = 300.0
+
+_CLIENT_INFO = {"name": "CodeBee", "version": "1.0"}
+
+
+def invalidate_tools_cache():
+    """服务器配置变化后丢弃已发现工具（插件启停等场景调用）。"""
+    with _LOCK:
+        _TOOLS_CACHE.clear()
+
+
+def parse_servers(text):
+    """settings.mcp_servers 文本 → 校验后的服务器配置列表。返回 (servers, 错误)。"""
+    raw = str(text or "").strip()
+    if not raw:
+        return [], None
+    try:
+        arr = json.loads(raw)
+    except Exception:
+        return None, "mcp_servers 不是合法 JSON"
+    if not isinstance(arr, list):
+        return None, "mcp_servers 必须是数组"
+    if len(arr) > MAX_SERVERS:
+        return None, "最多 %d 个 MCP 服务器" % MAX_SERVERS
+    out = []
+    for item in arr:
+        if not isinstance(item, dict):
+            return None, "MCP 服务器配置必须是对象"
+        name = str(item.get("name") or "").strip()
+        command = str(item.get("command") or "").strip()
+        if not _NAME_RE.match(name):
+            return None, "服务器名 %r 只能是小写字母/数字/-/_（≤24 位）" % name[:24]
+        if not command:
+            return None, "服务器 %s 缺 command" % name
+        args = item.get("args") if isinstance(item.get("args"), list) else []
+        args = [str(a) for a in args][:16]
+        env = item.get("env") if isinstance(item.get("env"), dict) else {}
+        env = {str(k): str(v) for k, v in list(env.items())[:16]}
+        out.append({"name": name, "command": command, "args": args, "env": env})
+    return out, None
+
+
+class _Session:
+    """一次性的 MCP 服务器会话：spawn → initialize → （list/call）→ 杀树。"""
+
+    def __init__(self, server):
+        self.server = server
+        self.proc = None
+        self.lines = None       # reader 线程产出的行队列
+        self.err = None
+
+    def _pump_err(self):
+        try:
+            for _ in self.proc.stderr:
+                pass
+        except Exception:
+            pass
+
+    def _pump_out(self):
+        try:
+            for raw in self.proc.stdout:
+                self.lines.put(raw.decode("utf-8", errors="replace").rstrip("\r\n"))
+        except Exception:
+            pass
+        finally:
+            self.lines.put(None)      # EOF 哨兵
+
+    def __enter__(self):
+        try:
+            self.proc = subprocess.Popen(
+                [self.server["command"]] + list(self.server.get("args") or []),
+                stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE, text=False,
+                env={**os.environ, **(self.server.get("env") or {})})
+        except Exception as e:
+            raise RuntimeError("MCP 服务器启动失败: %s" % e)
+        import queue as _queue
+        self.lines = _queue.Queue()
+        threading.Thread(target=self._pump_out, daemon=True).start()
+        threading.Thread(target=self._pump_err, daemon=True).start()
+        self._request("initialize", {
+            "protocolVersion": "2024-11-05", "capabilities": {},
+            "clientInfo": _CLIENT_INFO}, timeout=_INIT_TIMEOUT)
+        self._notify("notifications/initialized")
+        return self
+
+    def __exit__(self, *exc):
+        try:
+            if self.proc and self.proc.stdin:
+                try:
+                    self.proc.stdin.close()
+                except Exception:
+                    pass
+        finally:
+            try:
+                if self.proc:
+                    self.proc.kill()
+            except Exception:
+                pass
+        return False
+
+    def _send(self, obj):
+        data = json.dumps(obj, ensure_ascii=False).encode("utf-8") + b"\n"
+        self.proc.stdin.write(data)
+        self.proc.stdin.flush()
+
+    def _notify(self, method, params=None):
+        self._send({"jsonrpc": "2.0", "method": method, "params": params or {}})
+
+    def _request(self, method, params, timeout):
+        """单请求单响应；忽略通知与未知 id 的服务端请求。"""
+        rid = id({})
+        self._send({"jsonrpc": "2.0", "id": 1 if method == "initialize" else rid,
+                    "method": method, "params": params or {}})
+        deadline = time.time() + max(1.0, timeout)
+        while True:
+            remain = deadline - time.time()
+            if remain <= 0:
+                raise RuntimeError("%s 超时（%.0fs）" % (method, timeout))
+            try:
+                line = self.lines.get(timeout=remain)
+            except Exception:
+                raise RuntimeError("%s 超时（%.0fs）" % (method, timeout))
+            if line is None:
+                raise RuntimeError("MCP 服务器提前退出")
+            line = line.strip()
+            if not line.startswith("{"):
+                continue
+            try:
+                msg = json.loads(line)
+            except Exception:
+                continue
+            if not isinstance(msg, dict) or msg.get("id") is None:
+                continue                     # 通知/服务端请求：不匹配本调用
+            if msg.get("id") != (1 if method == "initialize" else rid):
+                continue
+            if msg.get("error"):
+                raise RuntimeError("MCP %s 失败: %s" % (
+                    method, json.dumps(msg["error"], ensure_ascii=False)[:200]))
+            return msg.get("result") or {}
+
+
+def list_tools(server):
+    """发现服务器工具。返回 {"ok", "tools":[{"name","description","input_schema"}], "error"}。"""
+    try:
+        with _Session(server) as sess:
+            res = sess._request("tools/list", {}, timeout=_INIT_TIMEOUT)
+        tools = []
+        for t in (res.get("tools") or [])[:16]:
+            if isinstance(t, dict) and isinstance(t.get("name"), str) and t["name"]:
+                tools.append({"name": t["name"],
+                              "description": str(t.get("description") or "")[:400],
+                              "input_schema": t.get("input_schema")
+                              if isinstance(t.get("input_schema"), dict) else
+                              {"type": "object", "properties": {}}})
+        return {"ok": True, "tools": tools, "error": ""}
+    except Exception as e:
+        return {"ok": False, "tools": [], "error": str(e)[:200]}
+
+
+def call_tool(server, tool_name, arguments, timeout_s=_CALL_TIMEOUT):
+    """调用一个工具。返回 {"ok", "text", "error", "is_error"}。"""
+    try:
+        timeout = min(_CALL_TIMEOUT_MAX, max(5.0, float(timeout_s or _CALL_TIMEOUT)))
+        with _Session(server) as sess:
+            res = sess._request("tools/call",
+                                {"name": tool_name,
+                                 "arguments": arguments if isinstance(arguments, dict) else {}},
+                                timeout=timeout)
+        parts = []
+        for c in res.get("content") or []:
+            if isinstance(c, dict) and c.get("type") == "text" and c.get("text"):
+                parts.append(str(c["text"]))
+        text = "\n".join(parts)[:20000]
+        is_err = bool(res.get("isError"))
+        return {"ok": bool(text) and not is_err, "text": text,
+                "error": "" if not is_err else (text or "工具返回 isError"),
+                "is_error": is_err}
+    except Exception as e:
+        return {"ok": False, "text": "", "error": str(e)[:200], "is_error": False}
+
+
+# ---- 面向 builtin_agent 的合并视图（带缓存） ----
+
+def tool_specs_cached(force=False):
+    """全部服务器的工具合并清单：[{server, name(原名), full_name, description,
+    input_schema}]。TTL 内走缓存；单个服务器失败跳过（error 挂在条目外不打断）。"""
+    with _LOCK:
+        if not force:
+            hit = True
+            for key, (ts, _t) in _TOOLS_CACHE.items():
+                if time.time() - ts > _TOOLS_TTL:
+                    hit = False
+                    break
+            if hit and _TOOLS_CACHE:
+                out = []
+                for _key, (_ts, tools) in _TOOLS_CACHE.items():
+                    out.extend(tools)
+                return out[:MAX_MCP_TOOLS]
+    servers, err = parse_servers(_settings_text())
+    if err or not servers:
+        return []
+    out = []
+    with _LOCK:
+        _TOOLS_CACHE.clear()
+    for srv in servers:
+        res = list_tools(srv)
+        if not res.get("ok"):
+            continue
+        specs = []
+        for t in res["tools"]:
+            specs.append({"server": srv["name"], "name": t["name"],
+                          "full_name": "mcp__%s__%s" % (srv["name"], t["name"]),
+                          "description": t["description"],
+                          "input_schema": t["input_schema"]})
+        with _LOCK:
+            _TOOLS_CACHE[srv["name"]] = (time.time(), specs)
+        out.extend(specs)
+        if len(out) >= MAX_MCP_TOOLS:
+            break
+    return out[:MAX_MCP_TOOLS]
+
+
+def dispatch_full_name(full_name, arguments, timeout_s=_CALL_TIMEOUT):
+    """mcp__<server>__<tool> → 找服务器配置并调用。返回 {"ok","text","error"}。"""
+    m = re.match(r"^mcp__([a-z0-9_-]{1,24})__(.+)$", str(full_name or ""))
+    if not m:
+        return {"ok": False, "text": "", "error": "非法 MCP 工具名"}
+    sname, tool = m.group(1), m.group(2)
+    servers, err = parse_servers(_settings_text())
+    if err:
+        return {"ok": False, "text": "", "error": err}
+    srv = next((s for s in servers if s["name"] == sname), None)
+    if not srv:
+        return {"ok": False, "text": "", "error": "MCP 服务器 %s 未配置" % sname}
+    return call_tool(srv, tool, arguments, timeout_s=timeout_s)
+
+
+_SETTINGS_TEXT = None     # main.py 启动注入（读 settings.mcp_servers）——本模块
+                           # 不直接依赖 settings(L0)，静态图保持干净（同 set_run_estimator 模式）
+
+
+def set_settings_text(fn):
+    """注入 MCP 服务器清单读取器；未注入时工具清单为空（MCP 功能关闭）。"""
+    global _SETTINGS_TEXT
+    _SETTINGS_TEXT = fn if callable(fn) else None
+
+
+def _settings_text():
+    try:
+        return str(_SETTINGS_TEXT() or "") if _SETTINGS_TEXT else ""
+    except Exception:
+        return ""