codebee 0.1.95 → 0.1.97

package/app/core/builtin_agent.py

@@ -1,1680 +1,2055 @@
-# -*- coding: utf-8 -*-
-"""内置执行智能体：不经外部 CLI，直连供应商 API 完成直连（direct）任务。
-
-为什么：direct 是快档位，典型诉求是问答/轻量改写。拉起 codex/claude CLI 要付
-进程与框架开销，且 CLI 的事件流日志（启动命令、提示词回显、重连报错）会污染
-对话视图。内置智能体直接打 chat API + 工具循环：
-  - 模型选择：编排者配置（resolve_orchestrator）优先；未启用时扫首个可用供应商；
-  - 工具：list_files / read_file / write_file（锁死工作目录内）+ run_command
-    （本机全权执行命令，产品定位全信任，与 codex/claude 全权沙箱同档）；
-  - 协议：anthropic / openai 走原生工具循环；google 无工具协议（纯文本直答）。
-密钥冷却/多 KEY 展开复用 modelhub 既有记账（note_key_ok / note_key_error）。
-"""
-from __future__ import annotations
-
-import base64
-import fnmatch
-import io
-import json
-import mimetypes
-import os
-import re
-import shutil
-import threading
-import time
-import urllib.parse
-import urllib.request
-from pathlib import Path
-
-from . import modelhub, runner, tlsctx
-
-MAX_TOOL_ITERS = 32          # 单步工具循环上限（防模型打转；收尾另留 1 轮）
-READ_MAX_BYTES = 64 * 1024   # read_file 单次读取上限
-READ_HEAD_BYTES = 44 * 1024  # TokenJuice 借鉴（openhuman）：超限文件头尾保留、
-READ_TAIL_BYTES = 16 * 1024  # 中段省略——日志/代码的报错常在尾部，纯截头会丢关键信息
-LIST_MAX_ENTRIES = 200
-MAX_IMAGES = 8                 # 单次最多随消息传几张图（请求体防爆）
-IMAGE_MAX_EDGE = 1568          # 长边上限（视觉模型通行建议值，超出等比缩）
-IMAGE_JPEG_BYTES = 3500 * 1024   # 缩放后仍超此大小 → 转 JPEG q85
-IMAGE_MAX_BYTES = 5 * 1024 * 1024   # 单张最终字节硬上限（超出剔除并日志）
-THINK_MAX_CHARS = 20000        # 单次生成保留的思考正文上限（防超长思维链撑爆 run.json）
-STREAM_MAX_CHARS = 20000       # 运行中实时回答的保留上限（与 THINK_MAX_CHARS 同口径）
-BASE_MAX_TOKENS = 8000         # 单次生成输出预算（推理模型的思考 token 也计入此额度）
-MAX_TOKENS_CAP = 16000         # 思考撑爆预算后的提额上限（每轮 run 只提一次）
-THINK_EXHAUST_MIN_CHARS = 1500  # 零正文时思考达到此长度 ≈ 思考占满输出预算
-EMPTY_TEXT_MAX_STREAK = 3      # 连续零正文轮数上限（防同参数盲重试烧穿预算）
-
-CMD_DEFAULT_TIMEOUT = 600    # run_command 默认超时（与 CLI 停滞看门狗同口径）
-CMD_MAX_TIMEOUT = 1800       # 上限：模型传 timeout_sec 超过即钳到这
-CMD_OUT_HEAD = 24 * 1024     # 回灌给模型的输出：头 24K + 尾 8K（报错常在尾部）
-CMD_OUT_TAIL = 8 * 1024
-
-_SYSTEM_PROMPT = """你是 CodeBee 的内置执行智能体，直接完成用户交代的任务。用户的目标、背景与工作目录内的附件就是全部输入。
-
-## 工作方式
-- 需要读文件、看目录、写文件时调用工具；所有路径都是工作目录内的相对路径。
-- 改文件的优先级：小改动用 edit_file（精确查找替换，不必整份重写）＞追加用 append_file＞整份重建才用 write_file。删除/移动/重命名/复制用 fs_manage，不要绕 shell。
-- 大文件（超 64KB）默认只读头尾、中段省略；要看全用 read_file 的 offset/lines 分段读（返回头会提示下一段的 offset）。找内容用 search_content（带行号的 grep），找文件用 find_files，不要逐个文件读。
-- read_file 只能读文本文件；图片、压缩包等二进制文件读不了，如实告知用户即可，不要反复尝试。
-- 用户消息中的图片附件会直接出现在对话里，可直接看图作答，无需用工具读取。
-- run_command 直接在用户的电脑上执行命令并回传退出码与输出：诊断、修复、改配置、重启服务等操作会真实生效。命令跑完看输出再决定下一步，不要一次性罗列步骤让用户自己敲。
-- 当工具列表中提供 create_task 时，如果用户明确要求开始另一项 CodeBee 工作（例如“新建连载小说任务”“再开一个代码任务”），调用它发起独立任务；不要只在当前回答里描述应该怎么做。先从用户话里提取任务类型和目标，缺少关键目标时再追问。
-- Windows 上需要管理员权限的命令（flushdns、winsock reset、防火墙、系统服务等），用 powershell -Command "Start-Process <程序> -ArgumentList '<参数>' -Verb RunAs -Wait" 触发 UAC——用户屏幕会弹窗，点允许即提权执行；提权进程的输出拿不到，之后要用普通命令复核效果。macOS/Linux 用 sudo 并在输出里提示用户输密码不可行时改写临时脚本让用户跑。
-- 避免跑长驻/交互式命令（ping -t、top、要按键应答的安装器），它们会拖满超时被强杀。
-- 产出文件一律 UTF-8 编码。
-- 回答用户的语言与用户一致（默认中文）。直接给结论和内容，不要输出任何机器标记或协议行。
-- 核心产出完成后立即停止探索并总结；不要为“再确认一次”重复读取或重复写入。
-- 每次工具调用后都要判断是否已经达到目标；如果工具轮次即将耗尽，先完成已开始的操作，随后直接给出已完成内容、产出文件和未完成项。
-"""
-
-
-def resolve(provider_id="", model="", difficulty="default"):
-    """选内置智能体可用的 (provider, model)：编排者配置优先，否则首个可用供应商。
-
-    返回 {prov, model, provider_id, provider_name} 或 None（无可用供应商 → 调用方
-    回退 CLI 路径）。"""
-    provider_id = str(provider_id or "").strip()
-    model = str(model or "").strip()
-    if provider_id:
-        for p in modelhub.providers():
-            if p.get("id") != provider_id or not p.get("enabled", True) or not p.get("api_key"):
-                continue
-            selected = model
-            if selected:
-                try:
-                    enabled_names = [m.get("name") for m in modelhub._enabled_models(p)]
-                except Exception:
-                    enabled_names = []
-                if selected not in enabled_names:
-                    return None
-            if not selected:
-                selected = (p.get("model_hard") if difficulty == "hard" else
-                            p.get("model_easy") if difficulty == "easy" else
-                            p.get("model") or "").strip()
-            if not selected:
-                try:
-                    names = modelhub._enabled_models(p)
-                except Exception:
-                    names = []
-                selected = names[0]["name"] if names else ""
-            if selected:
-                return {"prov": p, "model": selected,
-                        "provider_id": p.get("id") or "",
-                        "provider_name": p.get("name") or p.get("id") or ""}
-        return None
-    orch = None
-    try:
-        orch = modelhub.resolve_orchestrator()
-    except Exception:
-        orch = None
-    if orch:
-        prov, model = orch
-        return {"prov": prov, "model": model,
-                "provider_id": prov.get("id") or "",
-                "provider_name": prov.get("name") or prov.get("id") or ""}
-    for p in modelhub.providers():
-        if not p.get("enabled", True) or not p.get("api_key"):
-            continue
-        m = ((p.get("model_hard") if difficulty == "hard" else
-              p.get("model_easy") if difficulty == "easy" else
-              p.get("model")) or "").strip()
-        if not m:
-            try:
-                names = modelhub._enabled_models(p)
-            except Exception:
-                names = []
-            m = names[0]["name"] if names else ""
-        if m:
-            return {"prov": p, "model": m, "provider_id": p.get("id") or "",
-                    "provider_name": p.get("name") or p.get("id") or ""}
-    return None
-
-
-# ---------------------------------------------------------------- 工作目录工具
-# 模型给的相对路径不可信：逐段拒绝 .. 与盘符，resolve() 归一后确认仍位于
-# 工作目录之下（base not in p.parents 即越界，同 skills/market 的守卫惯用法）。
-
-def _tool_list_files(workdir, args):
-    rel = str(args.get("path") or "").replace("\\", "/").strip("/")
-    if ".." in Path(rel).parts or any(":" in seg for seg in Path(rel).parts):
-        return "（非法路径: %s）" % rel
-    base = Path(workdir or ".").resolve()
-    p = (base / rel).resolve() if rel else base
-    if base not in p.parents and p != base:
-        return "（路径越界: %s）" % rel
-    if not p.is_dir():
-        return "（目录不存在: %s）" % (rel or ".")
-    out = []
-    for root, dirs, files in os.walk(str(p)):
-        dirs[:] = [d for d in dirs if d not in (".git", "__pycache__", "node_modules")]
-        for f in files:
-            fp = os.path.join(root, f)
-            relp = os.path.relpath(fp, str(base)).replace(os.sep, "/")
-            try:
-                size = os.path.getsize(fp)
-            except OSError:
-                size = -1
-            out.append("%s (%d B)" % (relp, size))
-            if len(out) >= LIST_MAX_ENTRIES:
-                return "\n".join(out) + "\n…（截断，共 200+ 项）"
-    return "\n".join(out) or "（空目录）"
-
-
-_BIN_MAGIC = (
-    (b"\x89PNG\r\n\x1a\n", "PNG 图片"),
-    (b"\xff\xd8\xff", "JPEG 图片"),
-    (b"GIF8", "GIF 图片"),
-    (b"%PDF-", "PDF 文档"),
-    (b"PK\x03\x04", "ZIP 压缩包"),
-    (b"\x1f\x8b", "GZIP 压缩包"),
-    (b"7z\xbc\xaf\x27\x1c", "7z 压缩包"),
-    (b"Rar!\x1a\x07", "RAR 压缩包"),
-    (b"\x00\x00\x01\x00", "ICO 图标"),
-    (b"OggS", "OGG 音频"),
-    (b"ID3", "MP3 音频"),
-)
-
-
-def _bin_format(head):
-    """常见二进制魔数 → 人类可读格式名（写进给模型的提示，让它立刻止损）。"""
-    if len(head) >= 12 and head[:4] == b"RIFF":
-        return {"WEBP": "WEBP 图片", "WAVE": "WAV 音频",
-                "AVI ": "AVI 视频"}.get(head[8:12].decode("ascii", "replace"),
-                                        "RIFF 媒体")
-    if len(head) >= 8 and head[4:8] == b"ftyp":
-        return "MP4/MOV 视频"
-    for magic, name in _BIN_MAGIC:
-        if head.startswith(magic):
-            return name
-    return "二进制文件"
-
-
-def _looks_binary(head):
-    """文本判定从宽：NUL 字节即判二进制（git 同款启发式），控制字符占比兜底
-    （部分二进制头 8KB 内无 NUL）。"""
-    if not head:
-        return False
-    if b"\x00" in head:
-        return True
-    sample = head[:8192]
-    ctrl = sum(1 for b in sample if b < 32 and b not in (9, 10, 12, 13))
-    return ctrl * 20 > len(sample)   # >5% 视为二进制
-
-
-def _trim_partial_utf8(chunk):
-    """头部截断可能把多字节字符切成两半：剥掉尾部不完整序列，否则 UTF-8
-    strict 失败会误落 GBK 解出错字（runner.tail_decoded 的头截断对偶）。"""
-    i = len(chunk) - 1
-    while i >= 0 and i >= len(chunk) - 3 and (chunk[i] & 0xC0) == 0x80:
-        i -= 1
-    if 0 <= i < len(chunk):
-        b = chunk[i]
-        need = 4 if (b & 0xF8) == 0xF0 else 3 if (b & 0xF0) == 0xE0 \
-            else 2 if (b & 0xC0) == 0xC0 else 1
-        if len(chunk) - i < need:
-            return chunk[:i]
-    return chunk
-
-
-def _guess_image_mime(path, raw=b""):
-    m = mimetypes.guess_type(str(path))[0]
-    if m:
-        return m
-    if raw.startswith(b"\x89PNG"):
-        return "image/png"
-    if raw.startswith(b"\xff\xd8"):
-        return "image/jpeg"
-    if raw.startswith(b"GIF8"):
-        return "image/gif"
-    if raw.startswith(b"RIFF"):
-        return "image/webp"
-    return "image/png"
-
-
-def _prep_images(paths, log=None):
-    """图片路径 → [(mime, b64)]。Pillow 可用时：长边超 1568px 等比缩（万级像素
-    原图既烧 token 又常被网关拒），仍超 3.5MB 转 JPEG q85；Pillow 缺失或解码
-    失败时原图直传，单张超 5MB 剔除并日志。最多 MAX_IMAGES 张。"""
-    try:
-        from PIL import Image
-    except Exception:
-        Image = None
-    out = []
-    for p in (paths or [])[:MAX_IMAGES]:
-        try:
-            raw = Path(p).read_bytes()
-        except OSError:
-            if log:
-                log("[图片] 跳过（读取失败）: %s" % os.path.basename(str(p)))
-            continue
-        mime = _guess_image_mime(p, raw)
-        data = raw
-        if Image is not None:
-            try:
-                im = Image.open(io.BytesIO(raw))
-                im.load()
-                w, h = im.size
-                edge = max(w, h, 1)
-                if edge > IMAGE_MAX_EDGE:
-                    r = IMAGE_MAX_EDGE / float(edge)
-                    im = im.resize((max(1, round(w * r)), max(1, round(h * r))),
-                                   Image.LANCZOS)
-                fmt = {"image/png": "PNG", "image/jpeg": "JPEG",
-                       "image/gif": "GIF", "image/webp": "WEBP"}.get(mime, "PNG")
-                buf = io.BytesIO()
-                im.save(buf, format=fmt)   # GIF 多帧仅存首帧，可接受
-                data = buf.getvalue()
-            except Exception:
-                data = raw                 # 解码/编码失败退回原始字节
-        if (Image is not None and mime != "image/jpeg"
-                and len(data) > IMAGE_JPEG_BYTES):
-            try:                           # 仍过大：转 JPEG q85（RGB 拍平 alpha）
-                im = Image.open(io.BytesIO(data)).convert("RGB")
-                buf = io.BytesIO()
-                im.save(buf, format="JPEG", quality=85)
-                data = buf.getvalue()
-                mime = "image/jpeg"
-            except Exception:
-                pass
-        if len(data) > IMAGE_MAX_BYTES:
-            if log:
-                log("[图片] 剔除（过大 %d MB）: %s"
-                    % (len(data) // (1024 * 1024), os.path.basename(str(p))))
-            continue
-        out.append((mime, base64.b64encode(data).decode("ascii")))
-    return out
-
-
-def _tool_read_file(workdir, args):
-    rel = str(args.get("path") or "").replace("\\", "/").strip("/")
-    if not rel or ".." in Path(rel).parts or any(":" in seg for seg in Path(rel).parts):
-        return "（非法路径: %s）" % rel
-    base = Path(workdir or ".").resolve()
-    p = (base / rel).resolve()
-    if base not in p.parents:
-        return "（路径越界: %s）" % rel
-    if not p.is_file():
-        return "（文件不存在: %s）" % rel
-    # 分段读取（P0 基础件）：offset/lines 任一非空即按行号范围读——超 64KB
-    # 被「头尾保留、中段省略」截断的大文件靠它读全（用户实测 _lessons_dump.txt
-    # 68KB 被截案）。行号 1-based；逐行切片后不强行拼回整份。
-    offset_raw = str(args.get("offset") or "").strip()
-    lines_raw = str(args.get("lines") or "").strip()
-    if offset_raw or lines_raw:
-        try:
-            size = p.stat().st_size
-        except OSError as e:
-            return "（读取失败: %s）" % e
-        if size > READ_EDIT_MAX_BYTES:
-            return ("（文件过大 %d MB，分段读取上限 %d MB；请用 run_command 处理）"
-                    % (size // (1024 * 1024), READ_EDIT_MAX_BYTES // (1024 * 1024)))
-        try:
-            offset = max(1, int(float(offset_raw or 1)))
-            lines = max(1, min(READ_SEGMENT_MAX_LINES,
-                               int(float(lines_raw or READ_SEGMENT_DEFAULT_LINES))))
-        except (TypeError, ValueError):
-            return "（offset/lines 须为整数行号）"
-        all_lines = runner.decode_output(p.read_bytes()).splitlines()
-        total = len(all_lines)
-        if total == 0:
-            return "（空文件）"
-        if offset > total:
-            return "（offset %d 超出文件总行数 %d）" % (offset, total)
-        seg = all_lines[offset - 1:offset - 1 + lines]
-        head = "第 %d–%d 行（共 %d 行；用 offset=%d 续读下一段）" % (
-            offset, offset - 1 + len(seg), total, offset + len(seg))
-        return head + "\n" + ("\n".join(seg) or "（该范围无内容）")
-    data = p.read_bytes()[:READ_MAX_BYTES + 1]
-    truncated = len(data) > READ_MAX_BYTES
-    if truncated:
-        # 头尾保留、中段省略（TokenJuice 借鉴）：头 44k 给结构/开头上下文，
-        # 尾 16k 给报错/结论（日志与代码的关键信息常在末尾），中段标注省略量
-        try:
-            size = p.stat().st_size
-        except OSError:
-            size = len(data)
-        with open(p, "rb") as fh:
-            head = fh.read(READ_HEAD_BYTES)
-            fh.seek(max(0, size - READ_TAIL_BYTES))
-            tail = fh.read(READ_TAIL_BYTES)
-        head = _trim_partial_utf8(head)
-        # 尾段开头的残缺多字节序列剥头（对偶于 _trim_partial_utf8 剥尾）
-        while tail:
-            try:
-                tail.decode("utf-8")
-                break
-            except UnicodeDecodeError:
-                tail = tail[1:]
-        text = runner.decode_output(head) \
-            + "\n…（中段省略 %d 字节；头 %dKB + 尾 %dKB 保留）\n" % (
-                max(0, size - READ_HEAD_BYTES - READ_TAIL_BYTES),
-                READ_HEAD_BYTES // 1024, READ_TAIL_BYTES // 1024) \
-            + runner.decode_output(tail)
-        return "…（文件超 64KB，已头尾保留读取）\n" + text
-    head = data
-    if not head:
-        return "（空文件）"
-    if _looks_binary(head):
-        try:
-            size = p.stat().st_size
-        except OSError:
-            size = len(head)
-        fmt = _bin_format(head)
-        if "图片" in fmt:
-            return ("（图片文件: %s — %s，%d B，无法按文本读取。用户以附件发来的图片会"
-                    "直接出现在对话中，无需用工具读取；若需要目录里这张图的内容，"
-                    "请提示用户把它作为附件发送。）" % (rel, fmt, size))
-        return ("（二进制文件，无法按文本读取: %s — %s，%d B。read_file 只支持文本文件；"
-                "请如实告知用户该文件内容无法以文本方式查看，不要反复重读。）"
-                % (rel, fmt, size))
-    text = runner.decode_output(head)
-    return text
-
-
-def _tool_write_file(workdir, args):
-    rel = str(args.get("path") or "").replace("\\", "/").strip("/")
-    if not rel or ".." in Path(rel).parts or any(":" in seg for seg in Path(rel).parts):
-        return "（非法路径: %s）" % rel
-    content = str(args.get("content") if args.get("content") is not None else "")
-    base = Path(workdir or ".").resolve()
-    dest = (base / rel).resolve()
-    if base not in dest.parents:
-        return "（路径越界: %s）" % rel
-    dest.parent.mkdir(parents=True, exist_ok=True)
-    # newline=""：不翻译换行——模型回写 read_file 读到的 CRLF 内容时，
-    # 默认翻译会二次翻成 \r\r\n
-    with dest.open("w", encoding="utf-8", newline="") as fh:
-        fh.write(content)
-    return "已写入 %s（%d 字符，UTF-8）" % (rel, len(content))
-
-
-def _tool_run_command(workdir, args, cancel_event=None, deadline=None):
-    """本机执行一条 shell 命令，返回 (退出码, 合并输出)。
-
-    薄适配层：执行/杀树/取消/解码全部复用 runner.run_process（shell_cmd 分支
-    → cmd /c 或 /bin/sh -c），仓库唯一的 shell 落点，不另起炉灶。全信任档
-    （用户拍板 2026-09-22）：无白名单无确认闸，与 codex/claude 全权沙箱同档。
-    提权靠模型自己包 Start-Process -Verb RunAs——UAC 必须人点，绕不过也不该绕。
-    输出按字符头尾截断（解码已在 run_process 完成，无残缺多字节问题）。"""
-    cmdline = str(args.get("command") or "").strip()
-    if not cmdline:
-        return "（命令为空，未执行）"
-    try:
-        timeout = int(float(args.get("timeout_sec") or CMD_DEFAULT_TIMEOUT))
-    except (TypeError, ValueError):
-        timeout = CMD_DEFAULT_TIMEOUT
-    r = runner.run_process(shell_cmd=cmdline, cwd=os.path.abspath(workdir or "."),
-                           timeout=max(5, min(timeout, CMD_MAX_TIMEOUT)),
-                           deadline=deadline, cancel_event=cancel_event)
-    out = runner.clean_cli_text(
-        (r.get("stdout") or "") + (("\n" + r["stderr"]) if r.get("stderr") else ""))
-    limit = CMD_OUT_HEAD + CMD_OUT_TAIL
-    if not out.strip():
-        body = "（无输出）"
-    elif len(out) <= limit:
-        body = out
-    else:
-        body = (out[:CMD_OUT_HEAD]
-                + "\n…（中段省略 %d 字符；头 %dK + 尾 %dK 保留）\n" % (
-                    len(out) - limit, CMD_OUT_HEAD // 1024, CMD_OUT_TAIL // 1024)
-                + out[-CMD_OUT_TAIL:])
-    if r.get("cancelled"):
-        note = "已取消，进程树已终止"
-    elif r.get("timed_out"):
-        note = "超时 %d 秒，进程树已强制终止" % timeout
-    else:
-        note = ""
-    prefix = ("（%s）\n" % note) if note else ""
-    code = r.get("exit_code")
-    return "%s退出码: %s\n%s" % (prefix, "未知" if code is None else code, body)
-
-
-# ---------------------------------------------------------------- P0 基础件扩展
-# 2026-09-25 用户实测反馈：改大文件只能整份读写、删/移/改名只能绕 shell、
-# 大文件 64KB 中段被截、找内容只能逐文件读——补齐四个基础件（局部编辑、
-# 文件管理、分段读取、全文搜索），全部锁死工作目录内。
-
-READ_EDIT_MAX_BYTES = 16 * 1024 * 1024   # edit/append 分段读全文解码上限
-SEARCH_MAX_FILE_BYTES = 2 * 1024 * 1024  # search_content 单文件参与搜索上限
-SEARCH_DEFAULT_RESULTS = 50              # 命中行默认上限
-READ_SEGMENT_DEFAULT_LINES = 200         # read_file 分段默认行数
-READ_SEGMENT_MAX_LINES = 2000            # read_file 分段行数上限
-
-_WALK_PRUNE = {".git", "__pycache__", "node_modules", ".venv", "venv",
-               "dist", "build", "target", ".idea", ".vscode", "__MACOSX",
-               ".pytest_cache", ".mypy_cache"}
-
-
-def _guard_rel(workdir, rel, allow_root=False):
-    """工作目录相对路径守卫（list/read/write 同款惯用法抽公共）。
-
-    返回 (resolve 后的 Path, 错误串)；合法时错误串为 None。空 rel 仅在
-    allow_root=True 时代表工作目录根。"""
-    rel = str(rel or "").replace("\\", "/").strip("/")
-    if (not rel and not allow_root) or ".." in Path(rel).parts \
-            or any(":" in seg for seg in Path(rel).parts):
-        return None, "（非法路径: %s）" % rel
-    base = Path(workdir or ".").resolve()
-    p = (base / rel).resolve() if rel else base
-    if base not in p.parents and p != base:
-        return None, "（路径越界: %s）" % rel
-    return p, None
-
-
-def _read_text_capped(p, limit=READ_EDIT_MAX_BYTES):
-    """读文本并识别编码（bytes 上限防巨型文件）。返回 (text, err)。"""
-    try:
-        size = p.stat().st_size
-    except OSError as e:
-        return "", "（读取失败: %s）" % e
-    if size > limit:
-        return "", ("（文件过大 %d MB，超过 %d MB 上限；请用 run_command 处理）"
-                    % (size // (1024 * 1024), limit // (1024 * 1024)))
-    data = p.read_bytes()
-    if _looks_binary(data[:8192]):
-        return "", "（二进制文件，%s 不适用: %s）" % ("文本编辑", _bin_format(data[:64]))
-    return runner.decode_output(data), None
-
-
-def _tool_edit_file(workdir, args):
-    """精确查找替换：old_text 逐字符匹配，默认仅允许 1 处命中。"""
-    p, err = _guard_rel(workdir, args.get("path"))
-    if err:
-        return err
-    old_text = str(args.get("old_text") or "")
-    new_text = str(args.get("new_text") if args.get("new_text") is not None else "")
-    if not old_text:
-        return "（old_text 不能为空；改全文请用 write_file 整份写入）"
-    if not p.is_file():
-        return "（文件不存在: %s）" % p.name
-    text, err = _read_text_capped(p)
-    if err:
-        return err
-    count = text.count(old_text)
-    crlf = False
-    if count == 0 and "\r\n" in text and "\r\n" not in old_text:
-        # Windows 文件 CRLF：按 LF 形态重试匹配，命中则在原文上以 CRLF 替换，
-        # 保持文件既有换行风格（否则整个文件换行符被翻转）
-        crlf_text = text.replace("\r\n", "\n")
-        count = crlf_text.count(old_text)
-        crlf = count > 0
-    if count == 0:
-        return ("（old_text 在文件中找不到逐字符匹配——read_file 超过 64KB 会"
-                "中段省略，请用 offset/lines 分段读全后重试）")
-    replace_all = str(args.get("replace_all") or "").strip().lower() in ("1", "true", "yes")
-    if count > 1 and not replace_all:
-        return ("（old_text 命中 %d 处；请补充更多上下文使命中唯一，"
-                "或传 replace_all=true 全部替换）" % count)
-    if crlf:
-        old_text = old_text.replace("\n", "\r\n")
-        new_text = new_text.replace("\n", "\r\n")
-    # newline="" 禁止 Python 的 \n→os.linesep 翻译：文件既有 CRLF 时会被
-    # 二次翻译成 \r\r\n（Windows 实测损坏案），写什么落什么
-    with p.open("w", encoding="utf-8", newline="") as fh:
-        fh.write(text.replace(old_text, new_text))
-    return "已替换 %d 处（%s）" % (count if replace_all else 1, p.name)
-
-
-def _tool_append_file(workdir, args):
-    """文件末尾追加（bytes 级追加，大文件不整份重写）；不存在则创建。"""
-    p, err = _guard_rel(workdir, args.get("path"))
-    if err:
-        return err
-    content = str(args.get("content") if args.get("content") is not None else "")
-    if not content:
-        return "（content 不能为空）"
-    if p.is_file():
-        with open(p, "rb") as fh:
-            head = fh.read(8192)
-        if _looks_binary(head):
-            return "（二进制文件，不能按文本追加: %s — %s）" % (p.name, _bin_format(head))
-    p.parent.mkdir(parents=True, exist_ok=True)
-    with open(p, "ab") as fh:
-        fh.write(content.encode("utf-8"))
-    return "已追加 %d 字符到 %s（UTF-8）" % (len(content), p.name)
-
-
-def _tool_fs_manage(workdir, args):
-    """删除 / 移动 / 重命名 / 复制（工作目录内；目标已存在一律拒绝防覆盖）。"""
-    action = str(args.get("action") or "").strip().lower()
-    if action not in ("delete", "move", "rename", "copy"):
-        return "（action 须为 delete/move/rename/copy）"
-    p, err = _guard_rel(workdir, args.get("path"))
-    if err:
-        return err
-    if not p.exists() and not p.is_symlink():
-        return "（不存在: %s）" % p
-    if action == "delete":
-        if p.is_dir() and not p.is_symlink():
-            shutil.rmtree(str(p))
-            return "已删除目录（含全部内容）: %s" % p.name
-        p.unlink()
-        return "已删除: %s" % p.name
-    dest, err = _guard_rel(workdir, args.get("dest"))
-    if err:
-        return err.replace("非法路径", "dest 非法路径").replace("路径越界", "dest 路径越界")
-    if dest.exists() or dest.is_symlink():
-        return "（目标已存在，拒绝覆盖: %s；先删除或换名）" % dest.name
-    dest.parent.mkdir(parents=True, exist_ok=True)
-    if action == "copy":
-        if p.is_dir():
-            shutil.copytree(str(p), str(dest))
-        else:
-            shutil.copy2(str(p), str(dest))
-        return "已复制 %s → %s" % (p.name, dest.name)
-    shutil.move(str(p), str(dest))
-    return "已%s %s → %s" % ("移动" if action == "move" else "重命名",
-                             p.name, dest.name)
-
-
-def _tool_search_content(workdir, args):
-    """grep 式内容搜索：正则（编译失败回退字面量），逐行命中带行号。"""
-    pattern = str(args.get("pattern") or "").strip()
-    if not pattern:
-        return "（pattern 不能为空）"
-    try:
-        rx = re.compile(pattern)
-    except re.error:
-        rx = re.compile(re.escape(pattern))
-        pattern_note = "（正则无效，已按字面量搜索）\n"
-    else:
-        pattern_note = ""
-    sub, err = _guard_rel(workdir, args.get("path"), allow_root=True)
-    if err:
-        return err
-    if not sub.is_dir():
-        return "（目录不存在: %s）" % args.get("path")
-    glob_pat = str(args.get("glob") or "").strip()
-    try:
-        max_results = max(1, min(200, int(float(args.get("max_results") or 0)
-                                        or SEARCH_DEFAULT_RESULTS)))
-    except (TypeError, ValueError):
-        max_results = SEARCH_DEFAULT_RESULTS
-    base = Path(workdir or ".").resolve()
-    out, hits, scanned = [], 0, 0
-    for root, dirs, files in os.walk(str(sub)):
-        dirs[:] = [d for d in dirs if d not in _WALK_PRUNE]
-        for f in files:
-            if glob_pat:
-                relp = os.path.relpath(os.path.join(root, f), str(base)).replace(os.sep, "/")
-                if not (fnmatch.fnmatch(f, glob_pat) or fnmatch.fnmatch(relp, glob_pat)):
-                    continue
-            fp = os.path.join(root, f)
-            try:
-                if os.path.getsize(fp) > SEARCH_MAX_FILE_BYTES:
-                    continue
-                with open(fp, "rb") as fh:
-                    head = fh.read(8192)
-                if _looks_binary(head):
-                    continue
-                with open(fp, "rb") as fh:
-                    data = fh.read()
-            except OSError:
-                continue
-            scanned += 1
-            rel = os.path.relpath(fp, str(base)).replace(os.sep, "/")
-            for i, line in enumerate(runner.decode_output(data).splitlines(), 1):
-                if rx.search(line):
-                    out.append("%s:%d: %s" % (rel, i, line.strip()[:200]))
-                    hits += 1
-                    if hits >= max_results:
-                        out.append("…（已达 %d 行上限，缩小 pattern/glob 或调大 max_results）"
-                                   % max_results)
-                        return pattern_note + "\n".join(out)
-    if not out:
-        return pattern_note + ("（无命中；已扫描 %d 个文本文件）" % scanned)
-    return pattern_note + "\n".join(out) + "\n（共 %d 行命中 / 扫描 %d 个文件）" % (hits, scanned)
-
-
-def _tool_find_files(workdir, args):
-    """文件名通配查找（fnmatch；pattern 不含 / 时匹配任意深度的文件名）。"""
-    pattern = str(args.get("pattern") or "").strip().replace("\\", "/")
-    if not pattern or ".." in pattern or ":" in pattern:
-        return "（非法 pattern: %s；示例 *.py 或 data/*.json）" % pattern
-    base = Path(workdir or ".").resolve()
-    match_name = "/" not in pattern
-    out = []
-    for root, dirs, files in os.walk(str(base)):
-        dirs[:] = [d for d in dirs if d not in _WALK_PRUNE]
-        for f in files:
-            rel = os.path.relpath(os.path.join(root, f), str(base)).replace(os.sep, "/")
-            if not (fnmatch.fnmatch(rel, pattern)
-                    or (match_name and fnmatch.fnmatch(f, pattern))):
-                continue
-            try:
-                size = os.path.getsize(os.path.join(root, f))
-            except OSError:
-                size = -1
-            out.append("%s (%d B)" % (rel, size))
-            if len(out) >= LIST_MAX_ENTRIES:
-                return "\n".join(out) + "\n…（截断，共 %d+ 项）" % LIST_MAX_ENTRIES
-    return "\n".join(out) or "（无匹配文件）"
-
-
-TOOLS_SPEC = [
-    {"name": "list_files", "description": "列出工作目录（或其子目录）下的文件",
-     "args": {"path": "子目录相对路径，留空=根目录"}},
-    {"name": "read_file", "description": "读取工作目录内一个文本文件（UTF-8/GBK 自动识别；默认超 64KB 时保留开头与结尾、中段省略，此时用 offset/lines 分段读全；图片等二进制文件无法读取）",
-     "args": {"path": "文件相对路径",
-              "?offset": "可选，起始行号（1-based），配合 lines 分段读取大文件",
-              "?lines": "可选，读取行数（默认 200，最大 2000）"}},
-    {"name": "edit_file", "description": "对文件做精确查找替换（局部编辑，不必整份重写）：old_text 必须与文件内容逐字符一致，默认要求命中唯一，配合 read_file 使用",
-     "args": {"path": "文件相对路径",
-              "old_text": "要被替换的原文（逐字符精确匹配）",
-              "new_text": "替换后的新文本（可为空串=删除）",
-              "?replace_all": "可选，true=替换全部命中（默认仅允许 1 处命中）"}},
-    {"name": "append_file", "description": "把文本追加到文件末尾（bytes 级追加，大文件不必整份重写）；文件不存在则创建。追加日志、逐条记录时优先用它",
-     "args": {"path": "文件相对路径", "content": "追加到末尾的文本"}},
-    {"name": "fs_manage", "description": "文件管理：删除 / 移动 / 重命名 / 复制（工作目录内；目标已存在一律拒绝覆盖，删目录会连内容一起删）",
-     "args": {"action": "delete | move | rename | copy",
-              "path": "源相对路径（目录或文件）",
-              "?dest": "move/rename/copy 的目标相对路径"}},
-    {"name": "search_content", "description": "全文内容搜索（grep 式）：在工作目录内逐文件逐行匹配正则，命中行带「路径:行号:」前缀返回；自动跳过二进制与依赖目录（node_modules/.git 等）",
-     "args": {"pattern": "搜索文本或正则表达式",
-              "?path": "可选，限定搜索的子目录，默认根目录",
-              "?glob": "可选，文件名过滤，如 *.py",
-              "?max_results": "可选，命中行数上限（默认 50，最大 200）"}},
-    {"name": "find_files", "description": "按文件名通配查找文件（如 *.py、data/*.json、report*.md）；pattern 不含 / 时匹配任意深度的文件名",
-     "args": {"pattern": "文件名通配模式"}},
-    {"name": "write_file", "description": "把文本内容写入工作目录内一个文件（UTF-8，整份覆盖，父目录自动创建；只改一小段请用 edit_file）",
-     "args": {"path": "文件相对路径", "content": "完整文本内容"}},
-    {"name": "run_command",
-     "description": "在本机执行一条 shell 命令，返回退出码与合并输出。诊断、修复、改配置、重启服务等操作真实生效；先跑命令看结果再定下一步。默认超时 600 秒，可用 timeout_sec 调整（5~1800）。Windows 需要管理员权限的命令（flushdns/防火墙/系统服务等）用 powershell -Command \"Start-Process <程序> -ArgumentList '<参数>' -Verb RunAs -Wait\" 触发 UAC（用户点允许后提权执行；提权进程输出拿不到，事后用普通命令复核）。避免长驻/交互式命令（ping -t、top、按键应答的安装器）。",
-     "args": {"command": "完整命令行（shell 语法，本机直接执行）",
-              "timeout_sec": "可选，超时秒数"}},
-]
-
-_TOOL_IMPL = {"list_files": _tool_list_files, "read_file": _tool_read_file,
-              "write_file": _tool_write_file, "run_command": _tool_run_command,
-              "edit_file": _tool_edit_file, "append_file": _tool_append_file,
-              "fs_manage": _tool_fs_manage, "search_content": _tool_search_content,
-              "find_files": _tool_find_files}
-
-
-CREATE_TASK_SPEC = {
-    "name": "create_task",
-    "description": "发起一个独立的 CodeBee 任务。用户要求开始另一类工作（例如创建连载小说、写代码或生成文档）时使用；任务会出现在任务列表并异步运行，不要把它当作当前对话里的普通回答。",
-    "args": {
-        "type": "任务类型 ID，例如 serial_novel、novel、code、doc、article",
-        "goal": "新任务的明确目标",
-        "?title": "新任务标题",
-        "?workdir": "绝对工作目录；留空沿用当前工作目录",
-        "?context": "补充背景或约束",
-        "?chapters": "serial_novel 首批章节数",
-        "?words_per_chapter": "serial_novel 每章目标字数",
-        "?start_chapter": "续写起始章节号",
-        "?variants": "连载同章候选稿数量（1-3）",
-        "?branches": "连载剧情分支数量（1-3）",
-        "?story_bible": "连载小说初始故事圣经",
-    },
-}
-
-
-def _tool_create_task(workdir, args, task_creator=None):
-    """Create a separate task through the caller-owned task boundary."""
-    if task_creator is None:
-        return "（当前对话不支持发起新任务）"
-    task_type = str(args.get("type") or "").strip().lower()
-    goal = str(args.get("goal") or "").strip()
-    if not task_type:
-        return "（type 不能为空；可用类型请使用 serial_novel、novel、code、doc 等）"
-    if not goal:
-        return "（goal 不能为空）"
-    payload = {
-        "type": task_type,
-        "goal": goal,
-        "title": str(args.get("title") or "").strip(),
-        "workdir": str(args.get("workdir") or workdir or "").strip(),
-        "context": str(args.get("context") or "").strip(),
-    }
-    if task_type == "serial_novel":
-        serial = {}
-        for key in ("chapters", "words_per_chapter", "start_chapter", "variants", "branches"):
-            if args.get(key) not in (None, ""):
-                serial[key] = args.get(key)
-        if serial:
-            payload["serial"] = serial
-        if args.get("story_bible") not in (None, ""):
-            payload["story_bible"] = str(args.get("story_bible") or "").strip()
-    try:
-        result = task_creator(payload)
-    except Exception as exc:
-        return "（发起任务失败：%s）" % str(exc)[:300]
-    if not isinstance(result, dict) or not result.get("task_id"):
-        return "（发起任务失败：未返回任务编号）"
-    return "已发起新任务：%s（运行编号：%s，类型：%s）" % (
-        result["task_id"], result.get("run_id") or "", task_type)
-
-
-def _exec_tool(workdir, name, args, cancel_event=None, deadline=None, task_creator=None):
-    if name == "create_task":
-        return _tool_create_task(workdir, args or {}, task_creator=task_creator)
-    if str(name or "").startswith("mcp__"):
-        # MCP 工具：透传给配置的服务器（stdio JSON-RPC）；超时给足但封顶
-        try:
-            from . import mcp_client
-            r = mcp_client.dispatch_full_name(name, args or {})
-            return r.get("text") or ("（MCP 工具失败: %s）" % r.get("error") if not r.get("ok") else "")
-        except Exception as e:
-            return "MCP 工具执行失败: %s" % e
-    fn = _TOOL_IMPL.get(name or "")
-    if fn is None:
-        return "（未知工具: %s）" % name
-    try:
-        if name == "run_command":
-            return fn(workdir, args or {}, cancel_event=cancel_event, deadline=deadline)
-        return fn(workdir, args or {})
-    except Exception as e:
-        return "工具执行失败: %s" % (e)
-
-
-# ---------------------------------------------------------------- 协议适配
-
-def _split_tool_args(t):
-    """args 键以 ? 开头 = 可选参数（模型侧名字去掉 ?，不进 required）。"""
-    props, required = {}, []
-    for k, v in t["args"].items():
-        opt = k.startswith("?")
-        props[k[1:] if opt else k] = {"type": "string", "description": v}
-        if not opt:
-            required.append(k)
-    return props, required
-
-
-def _mcp_specs():
-    """MCP 工具清单（带缓存）；取不到/未配置返回空表——增强不挡主流程。"""
-    try:
-        from . import mcp_client
-        return mcp_client.tool_specs_cached()
-    except Exception:
-        return []
-
-
-def _openai_tools(extra_specs=None):
-    out = []
-    for t in list(TOOLS_SPEC) + list(extra_specs or []):
-        props, required = _split_tool_args(t)
-        out.append({"type": "function", "function": {
-            "name": t["name"], "description": t["description"],
-            "parameters": {"type": "object", "properties": props,
-                           "required": required}}})
-    for m in _mcp_specs():
-        # MCP 工具自带 JSON Schema（透传，不套字符串化的 _split_tool_args）
-        out.append({"type": "function", "function": {
-            "name": m["full_name"],
-            "description": (m["description"] + "（MCP 工具，来自服务器 %s）" % m["server"]).strip(),
-            "parameters": m["input_schema"]}})
-    return out
-
-
-def _anthropic_tools(extra_specs=None):
-    out = []
-    for t in list(TOOLS_SPEC) + list(extra_specs or []):
-        props, required = _split_tool_args(t)
-        out.append({"name": t["name"], "description": t["description"],
-                    "input_schema": {"type": "object", "properties": props,
-                                     "required": required}})
-    for m in _mcp_specs():
-        out.append({"name": m["full_name"],
-                    "description": (m["description"] + "（MCP 工具，来自服务器 %s）" % m["server"]).strip(),
-                    "input_schema": m["input_schema"]})
-    return out
-
-
-def _post_json(url, headers, body, allow_private, timeout):
-    """传输层单点（测试在这里打桩）。"""
-    return modelhub._post_json_http(url, headers, body, allow_private, timeout=timeout)
-
-
-def _call_with_optional_deadline(fn, args, kwargs, deadline):
-    """Keep older test/integration transport shims source-compatible."""
-    if deadline is None:
-        return fn(*args, **kwargs)
-    try:
-        return fn(*args, **kwargs, deadline=deadline)
-    except TypeError as exc:
-        if "unexpected keyword argument 'deadline'" not in str(exc):
-            raise
-        return fn(*args, **kwargs)
-
-
-def _post_interruptible(url, headers, body, allow_private, timeout, cancel_event,
-                        deadline=None):
-    """可打断的模型调用：cancel_event 置位即刻放弃等待返回。
-
-    单次生成最长可跑满 timeout，取消不能陪跑到自然结束——HTTP 交给守护
-    线程自行收尾（响应被丢弃，socket 随线程结束释放），主流程立即返回。
-    服务端仍会把这次生成跑完（token 已花），但任务本身即刻终止。"""
-    box = {}
-
-    def _go():
-        try:
-            box["r"] = _post_json(url, headers, body, allow_private, timeout)
-        except Exception as e:
-            box["r"] = (0, None, repr(e))
-
-    th = threading.Thread(target=_go, daemon=True)
-    th.start()
-    wait_until = deadline if deadline is not None else time.monotonic() + timeout + 10
-    while th.is_alive():
-        if cancel_event is not None and cancel_event.is_set():
-            break
-        if time.monotonic() >= wait_until:
-            return 0, None, ("任务总时限已到" if deadline is not None else "响应超时")
-        th.join(0.5)
-    if cancel_event is not None and cancel_event.is_set():
-        return 0, None, "已取消"
-    return box.get("r") or (0, None, "无响应")
-
-
-# ---------------------------------------------------------------- 思考过程（流式）
-# 用户诉求（2026-09-22）：「把思考过程打印出来」——直连对话此前整轮只有三点
-# 打字动画，模型的思维链（DeepSeek/vLLM 系 reasoning_content、Anthropic
-# thinking 块）被 _sse_parse 明确丢弃。这里自带一份「认思考」的增量解析：
-# 边收边把思考与正文分别攒起来，交给调用方实时落盘 + 结束后存进步骤记录。
-
-def _reason_from_delta(proto, obj):
-    """从一条流式事件里取「思考增量」。三协议字段各异，取不到返回空串。
-
-    openai 兼容面最杂：reasoning_content（DeepSeek/vLLM/云知声实测）、
-    reasoning（部分网关）、reasoning_details[].text（OpenRouter 系）。
-    anthropic 是 thinking_delta（另有 redacted_thinking 不文本化，跳过）。"""
-    if proto == "openai":
-        total = ""
-        for ch in obj.get("choices") or []:
-            d = ch.get("delta") or {}
-            for k in ("reasoning_content", "reasoning"):
-                v = d.get(k)
-                if isinstance(v, str):
-                    total += v
-            for det in (d.get("reasoning_details") or []):
-                if isinstance(det, dict) and isinstance(det.get("text"), str):
-                    total += det["text"]
-        return total
-    if proto == "anthropic" and obj.get("type") == "content_block_delta":
-        d = obj.get("delta") or {}
-        if d.get("type") == "thinking_delta":
-            return d.get("thinking") or ""
-        return ""
-    if proto == "google":
-        total = ""
-        for cand in obj.get("candidates") or []:
-            for p in ((cand.get("content") or {}).get("parts") or []):
-                if isinstance(p, dict) and p.get("thought"):
-                    total += p.get("text") or ""
-        return total
-    return ""
-
-
-def _reason_from_message(proto, data):
-    """非流式响应里的思考字段（网关不支持流式时的兜底）。"""
-    if not isinstance(data, dict):
-        return ""
-    if proto == "anthropic":
-        return "\n".join(b.get("thinking", "") for b in (data.get("content") or [])
-                         if isinstance(b, dict) and b.get("type") == "thinking")
-    if proto == "google":
-        total = ""
-        for cand in data.get("candidates") or []:
-            for p in ((cand.get("content") or {}).get("parts") or []):
-                if isinstance(p, dict) and p.get("thought"):
-                    total += p.get("text") or ""
-        return total
-    msg = ((data.get("choices") or [{}])[0].get("message") or {})
-    total = ""
-    for k in ("reasoning_content", "reasoning"):
-        v = msg.get(k)
-        if isinstance(v, str):
-            total += v
-    for det in (msg.get("reasoning_details") or []):
-        if isinstance(det, dict) and isinstance(det.get("text"), str):
-            total += det["text"]
-    return total
-
-
-def _stream_accumulate(proto, obj, acc):
-    """把一条 SSE 事件并入累加器（就地改写 acc）。返回是否有「有意义的进展」。
-
-    acc = {text, reasoning, tools, usage}；工具参数按 index 归并——openai 的
-    function.arguments 与 anthropic 的 input_json_delta 都是分片到达的。"""
-    progress = False
-    if proto == "anthropic":
-        t = obj.get("type")
-        if t == "content_block_start":
-            blk = obj.get("content_block") or {}
-            if blk.get("type") == "tool_use":
-                idx = int(obj.get("index") or 0)
-                acc["tools"][idx] = {"id": blk.get("id") or "",
-                                     "name": blk.get("name") or "", "raw": ""}
-                progress = True
-        elif t == "content_block_delta":
-            d = obj.get("delta") or {}
-            if d.get("type") == "text_delta" and d.get("text"):
-                acc["text"] += d["text"]
-                progress = True
-            elif d.get("type") == "input_json_delta":
-                idx = int(obj.get("index") or 0)
-                slot = acc["tools"].setdefault(idx, {"id": "", "name": "", "raw": ""})
-                slot["raw"] += d.get("partial_json") or ""
-                progress = True
-        elif t == "message_start":
-            u = (obj.get("message") or {}).get("usage") or obj.get("usage") or {}
-            acc["usage"].update({"input": int(u.get("input_tokens") or 0),
-                                 "output": int(u.get("output_tokens") or 0),
-                                 "cached": (int(u.get("cache_read_input_tokens") or 0)
-                                            + int(u.get("cache_creation_input_tokens") or 0))})
-        elif t == "message_delta":
-            u = obj.get("usage") or {}
-            if u.get("output_tokens"):
-                acc["usage"]["output"] = int(u["output_tokens"])
-    elif proto == "google":
-        for cand in obj.get("candidates") or []:
-            for p in ((cand.get("content") or {}).get("parts") or []):
-                if not isinstance(p, dict):
-                    continue
-                if p.get("thought"):
-                    acc["reasoning"] += p.get("text") or ""
-                    progress = True
-                elif p.get("functionCall"):
-                    fc = p["functionCall"]
-                    acc["tools"][len(acc["tools"])] = {
-                        "id": "call_%d" % (len(acc["tools"]) + 1),
-                        "name": fc.get("name") or "",
-                        "raw": json.dumps(fc.get("args") or {}, ensure_ascii=False)}
-                    progress = True
-                elif p.get("text"):
-                    acc["text"] += p["text"]
-                    progress = True
-        u = obj.get("usageMetadata")
-        if isinstance(u, dict):
-            acc["usage"].update({"input": int(u.get("promptTokenCount") or 0),
-                                 "output": int(u.get("candidatesTokenCount") or 0),
-                                 "total": int(u.get("totalTokenCount") or 0)})
-    else:
-        for ch in obj.get("choices") or []:
-            d = ch.get("delta") or {}
-            if isinstance(d.get("content"), str) and d["content"]:
-                acc["text"] += d["content"]
-                progress = True
-            for i, tc in enumerate(d.get("tool_calls") or []):
-                if not isinstance(tc, dict):
-                    continue
-                idx = int(tc.get("index") if tc.get("index") is not None else i)
-                slot = acc["tools"].setdefault(idx, {"id": "", "name": "", "raw": ""})
-                if tc.get("id"):
-                    slot["id"] = tc["id"]
-                fn = tc.get("function") or {}
-                if fn.get("name"):
-                    slot["name"] = fn["name"]
-                if fn.get("arguments"):
-                    slot["raw"] += fn["arguments"]
-                progress = True
-        u = obj.get("usage")
-        if isinstance(u, dict):
-            acc["usage"].update({"input": int(u.get("prompt_tokens") or 0),
-                                 "output": int(u.get("completion_tokens") or 0),
-                                 "total": int(u.get("total_tokens") or 0),
-                                 "cached": int(((u.get("prompt_tokens_details") or {})
-                                                .get("cached_tokens")) or 0)})
-    return progress
-
-
-def _calls_from_acc(acc):
-    """累加器里的工具分片 → [{id, name, args}]（参数 JSON 解析失败给空对象）。"""
-    out = []
-    for idx in sorted(acc["tools"].keys()):
-        slot = acc["tools"][idx]
-        name = slot.get("name") or ""
-        if not name:
-            continue
-        try:
-            args = json.loads(slot.get("raw") or "{}")
-        except Exception:
-            args = {}
-        if not isinstance(args, dict):
-            args = {}
-        out.append({"id": slot.get("id") or ("call_%d" % (idx + 1)),
-                    "name": name, "args": args})
-    return out
-
-
-def _post_sse_stream(url, headers, body, allow_private, timeout, proto,
-                     on_reason=None, on_text=None, on_tick=None, cancel_event=None,
-                     deadline=None):
-    """流式（SSE）模型调用 → dict(status/text/reasoning/calls/usage/error/events)。
-
-    与 _post_interruptible 同款的可打断语义：读取放守护线程，cancel_event 置位
-    即刻放弃等待（socket 随线程结束释放）。三个回调：on_reason 每收到一段思考
-    增量（调用方据此实时打印「思考过程」），on_text 收到**累计**正文（只在真的
-    变长时触发，运行中直接当正文预览），on_tick 是无文本进展时的心跳。
-    events=0 表示网关根本没按流回（多半忽略了 stream 字段）——调用方据此回落
-    非流式；events>0 而正文为空则是模型真没说话，不该重发（白烧一次生成）。
-
-    首字延迟与吞吐（§07 体验面）：`first_token_ms` = 发出请求到第一个**带内容**
-    的增量（思考 / 正文 / 工具参数）之间的毫秒数；`tokens_per_sec` 用 output
-    token 除以「首个到末个内容增量」的窗口，窗口过短或拿不到 output 时记 0
-    （0 = 不可测，不是"一秒 0 个 token"）。两者只有走流式才有值，非流式回落
-    路径与 CLI 子进程路径都给 0。"""
-    acc = {"text": "", "reasoning": "", "tools": {}, "usage": {}}
-    box = {"status": 0, "err": "", "events": 0, "sent_text": None,
-           "first_ms": None, "last_ms": None}
-    lock = threading.Lock()
-
-    def _emit(cb, payload):
-        if cb is None:
-            return
-        try:
-            cb(payload)
-        except Exception:
-            pass
- 
-    def _go():
-        try:
-            parsed = urllib.parse.urlsplit(url)
-            if parsed.scheme not in ("http", "https"):
-                box["err"] = "协议必须是 http/https"
-                return
-            host, herr = modelhub._validate_host(url, allow_private)
-            if host is None:
-                box["err"] = herr
-                return
-            t_send = time.monotonic()      # 首字延迟基线：请求发出，不含 DNS/连接前准备
-            req = urllib.request.Request(
-                url, method="POST",
-                headers=dict(headers, **{"Content-Type": "application/json",
-                                         "Accept": "text/event-stream"}),
-                data=json.dumps(body).encode("utf-8"))
-            with modelhub._opener().open(req, timeout=timeout) as resp:
-                box["status"] = resp.status
-                if not 200 <= resp.status < 300:
-                    raw = resp.read(65536).decode("utf-8", "replace")
-                    box["err"] = "HTTP %s %s" % (resp.status, raw[:200])
-                    return
-                for raw in resp:
-                    line = raw.decode("utf-8", "replace").strip()
-                    if not line.startswith("data:"):
-                        continue
-                    payload = line[5:].strip()
-                    if not payload or payload == "[DONE]":
-                        continue
-                    try:
-                        obj = json.loads(payload)
-                    except Exception:
-                        continue          # 半行/坏行静默跳过，不中断整流
-                    if not isinstance(obj, dict):
-                        continue
-                    box["events"] += 1
-                    reason = _reason_from_delta(proto, obj)
-                    with lock:
-                        if reason:
-                            acc["reasoning"] += reason
-                        moved = _stream_accumulate(proto, obj, acc)
-                        text_now = acc["text"]
-                    if reason or moved:
-                        now_ms = (time.monotonic() - t_send) * 1000.0
-                        if box["first_ms"] is None:
-                            box["first_ms"] = now_ms
-                        box["last_ms"] = now_ms
-                    if reason:
-                        _emit(on_reason, reason)
-                    if text_now != box["sent_text"]:
-                        box["sent_text"] = text_now
-                        _emit(on_text, text_now)     # 累计正文（运行中实时打印）
-                    elif moved and not reason:
-                        _emit(on_tick, None)         # 只有工具/用量在推进的心跳
-                    if sum(len(x) for x in (acc["text"], acc["reasoning"])) > 4 * 1024 * 1024:
-                        break             # 防失控
-        except Exception as e:
-            box["err"] = box["err"] or tlsctx.humanize(repr(e)[:300])
-
-    th = threading.Thread(target=_go, daemon=True)
-    th.start()
-    wait_until = deadline if deadline is not None else time.monotonic() + timeout + 10
-    while th.is_alive():
-        if cancel_event is not None and cancel_event.is_set():
-            break
-        if time.monotonic() >= wait_until:
-            break
-        th.join(0.5)
-    with lock:
-        out = {"status": box["status"], "text": acc["text"],
-               "reasoning": acc["reasoning"], "usage": dict(acc["usage"]),
-               "calls": _calls_from_acc(acc), "events": box["events"],
-               "first_token_ms": round(box["first_ms"], 1) if box["first_ms"] is not None else 0.0,
-               "tokens_per_sec": 0.0, "error": box["err"]}
-        gen_s = 0.0
-        if box["first_ms"] is not None and box["last_ms"] is not None:
-            gen_s = (box["last_ms"] - box["first_ms"]) / 1000.0
-        out_tok = int(acc["usage"].get("output") or 0)
-        if gen_s > 0.2 and out_tok > 0:
-            out["tokens_per_sec"] = round(out_tok / gen_s, 2)
-    if cancel_event is not None and cancel_event.is_set():
-        out["error"], out["status"] = "已取消", 0
-        return out
-    if th.is_alive():
-        out["error"], out["status"] = ("任务总时限已到" if deadline is not None
-                                         else "响应超时"), 0
-        out["deadline_exceeded"] = deadline is not None
-    return out
-
-
-def _m_openai(m):
-    """内部消息 → openai 消息。tool_results: [(call_id, 结果文本)]。"""
-    if m["role"] == "assistant":
-        out = {"role": "assistant", "content": m.get("content") or ""}
-        if m.get("tool_calls"):
-            out["tool_calls"] = [{"id": tc["id"], "type": "function",
-                                  "function": {"name": tc["name"],
-                                               "arguments": json.dumps(tc["args"], ensure_ascii=False)}}
-                                 for tc in m["tool_calls"]]
-        return out
-    if m["role"] == "tool_results":
-        return [{"role": "tool", "tool_call_id": cid, "content": text}
-                for cid, text in m["tool_results"]]
-    imgs = m.get("images") or []
-    if imgs:   # 多模态：content 变数组，图跟在文本后（role=tool 只收文本，故图只走 user）
-        content = [{"type": "text", "text": m.get("content") or ""}]
-        content += [{"type": "image_url",
-                     "image_url": {"url": "data:%s;base64,%s" % (mime, b64)}}
-                    for mime, b64 in imgs]
-        return {"role": "user", "content": content}
-    return {"role": "user", "content": m.get("content") or ""}
-
-
-def _m_anthropic(m):
-    if m["role"] == "assistant":
-        blocks = []
-        if m.get("content"):
-            blocks.append({"type": "text", "text": m["content"]})
-        for tc in (m.get("tool_calls") or []):
-            blocks.append({"type": "tool_use", "id": tc["id"], "name": tc["name"],
-                           "input": tc["args"]})
-        return {"role": "assistant", "content": blocks or [{"type": "text", "text": ""}]}
-    if m["role"] == "tool_results":
-        return {"role": "user", "content": [
-            {"type": "tool_result", "tool_use_id": cid, "content": text}
-            for cid, text in m["tool_results"]]}
-    imgs = m.get("images") or []
-    if imgs:
-        blocks = [{"type": "text", "text": m.get("content") or ""}]
-        blocks += [{"type": "image",
-                    "source": {"type": "base64", "media_type": mime, "data": b64}}
-                   for mime, b64 in imgs]
-        return {"role": "user", "content": blocks}
-    return {"role": "user", "content": [{"type": "text", "text": m.get("content") or ""}]}
-
-
-def _build_request(proto, base, use_key, model, system, msgs, with_tools, stream=False,
-                   max_tokens=BASE_MAX_TOKENS, extra_specs=None):
-    """按协议构造 (url, headers, body)。msgs 为内部统一形状。
-
-    stream=True 时按协议打开流式：google 换 :streamGenerateContent?alt=sse，
-    openai/anthropic 置 stream 字段（openai 另要 include_usage，否则收尾
-    chunk 不带 usage，这一步的 token 记账会凭空少一截）。"""
-    base = (base or "").rstrip("/")
-    if proto == "google":
-        if base.endswith("/v1beta"):
-            prefix = base + "/models/%s"
-        else:
-            prefix = base + "/v1beta/models/%s"
-        url = (prefix + (":streamGenerateContent?alt=sse" if stream
-                         else ":generateContent")) % model
-        headers = {"x-goog-api-key": use_key}
-        contents = []
-        for m in msgs:
-            if m["role"] not in ("user", "assistant"):
-                continue
-            parts = [{"text": m.get("content") or ""}]
-            parts += [{"inline_data": {"mime_type": mime, "data": b64}}
-                      for mime, b64 in (m.get("images") or [])]
-            contents.append({"role": ("user" if m["role"] == "user" else "model"),
-                             "parts": parts})
-        body = {"contents": contents,
-                "systemInstruction": {"parts": [{"text": system}]},
-                "generationConfig": {"maxOutputTokens": max_tokens}}
-        return url, headers, body
-    path = "/messages" if proto == "anthropic" else "/chat/completions"
-    url = (base + path) if base.endswith("/v1") else (base + "/v1" + path)
-    if proto == "anthropic":
-        headers = {"x-api-key": use_key, "anthropic-version": "2023-06-01"}
-        body = {"model": model, "max_tokens": max_tokens, "system": system,
-                "messages": [_m_anthropic(m) for m in msgs]}
-        if with_tools:
-            body["tools"] = _anthropic_tools(extra_specs)
-        if stream:
-            body["stream"] = True
-        return url, headers, body
-    headers = {"Authorization": "Bearer " + use_key}
-    # tool_results 消息展开成多条 role=tool（_m_openai 对它返回列表，不能嵌套）
-    msgs_wire = []
-    for m in msgs:
-        w = _m_openai(m)
-        if isinstance(w, list):
-            msgs_wire.extend(w)
-        else:
-            msgs_wire.append(w)
-    body = {"model": model, "max_tokens": max_tokens,
-            "messages": [{"role": "system", "content": system}] + msgs_wire}
-    if with_tools:
-        body["tools"] = _openai_tools(extra_specs)
-    if stream:
-        body["stream"] = True
-        body["stream_options"] = {"include_usage": True}
-    return url, headers, body
-
-
-def _parse_reply(proto, data):
-    """从响应解析 → (文本, [tool_call], usage)。
-    tool_call = {id, name, args}；usage = {input, output, cached, total}。"""
-    usage = {"input": 0, "output": 0, "cached": 0, "total": 0}
-    if proto == "google":
-        cand = (data.get("candidates") or [{}])[0]
-        parts = (cand.get("content") or {}).get("parts") or []
-        text = "\n".join(p.get("text", "") for p in parts if isinstance(p, dict))
-        um = data.get("usageMetadata") or {}
-        usage["input"] = int(um.get("promptTokenCount") or 0)
-        usage["output"] = int(um.get("candidatesTokenCount") or 0)
-        usage["total"] = int(um.get("totalTokenCount") or 0)
-        return text.strip(), [], usage
-    if proto == "anthropic":
-        blocks = data.get("content") or []
-        text = "\n".join(b.get("text", "") for b in blocks
-                         if isinstance(b, dict) and b.get("type") == "text")
-        calls = [{"id": b.get("id") or "", "name": b.get("name") or "",
-                  "args": b.get("input") or {}}
-                 for b in blocks if isinstance(b, dict) and b.get("type") == "tool_use"]
-        u = data.get("usage") or {}
-        usage["input"] = int(u.get("input_tokens") or 0)
-        usage["output"] = int(u.get("output_tokens") or 0)
-        usage["cached"] = (int(u.get("cache_read_input_tokens") or 0)
-                           + int(u.get("cache_creation_input_tokens") or 0))
-        usage["total"] = usage["input"] + usage["output"] + usage["cached"]
-        return text.strip(), calls, usage
-    choice = (data.get("choices") or [{}])[0]
-    msg = choice.get("message") or {}
-    calls = []
-    for tc in (msg.get("tool_calls") or []):
-        fn = tc.get("function") or {}
-        try:
-            args = json.loads(fn.get("arguments") or "{}")
-        except Exception:
-            args = {}
-        if not isinstance(args, dict):
-            args = {}
-        calls.append({"id": tc.get("id") or ("call_%d" % (len(calls) + 1)),
-                      "name": fn.get("name") or "", "args": args})
-    u = data.get("usage") or {}
-    usage["input"] = int(u.get("prompt_tokens") or 0)
-    usage["output"] = int(u.get("completion_tokens") or 0)
-    usage["total"] = int(u.get("total_tokens") or 0) or (usage["input"] + usage["output"])
-    return (msg.get("content") or "").strip(), calls, usage
-
-
-# ---------------------------------------------------------------- 主循环
-
-def _norm_usage(usage):
-    """三协议 usage → {input, output, cached, total}（缺 total 用三项相加补齐）。"""
-    out = {"input": 0, "output": 0, "cached": 0, "total": 0}
-    for k in out:
-        try:
-            out[k] = int((usage or {}).get(k) or 0)
-        except Exception:
-            out[k] = 0
-    if not out["total"]:
-        out["total"] = out["input"] + out["output"] + out["cached"]
-    return out
-
-
-def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=None,
-        on_reason=None, on_stream=None, on_activity=None, stream=True, deadline=None,
-        task_creator=None):
-    """跑一次内置智能体（内部自带工具循环直到给出最终回答）。
-
-    bi: resolve() 的返回；prompt: 本轮完整输入（目标/续轮块由 pipeline 拼）；
-    images: 用户随本轮消息提供的图片绝对路径列表（任务附件/对话追话）；
-    log: 追加一行日志的回调（步骤日志）。返回 runner 风格统一结果：
-    {ok, text, usage, error, model, provider_name, provider_id, iterations,
-     cost_usd, reasoning}。
-
-    思考过程可视化（2026-09-22 用户诉求「把思考过程打印出来」）：stream=True 走
-    SSE，模型的思维链（reasoning_content / thinking 块）边收边经 on_reason 回调，
-    正文增量经 on_stream（累计值），工具活动经 on_activity——调用方据此在对话
-    时间线上实时打印，不再让用户干看三点打字动画。网关忽略 stream（零事件）时
-    自动回落非流式，思考字段仍从响应体兜底抽取（on_reason 补发一次）。"""
-    prov = bi["prov"]
-    model = bi["model"]
-    allow_private = bool(prov.get("allow_private"))
-    system = _SYSTEM_PROMPT + "\n\n## 工作目录\n%s" % os.path.abspath(workdir or ".")
-    imgs = _prep_images(images, log) if images else []
-    if imgs and not modelhub._model_image_in(prov, model):
-        # 能力闸门：模型未声明图片输入就不塞图（网关多半会拒），改为显式告知
-        if log:
-            log("[图片] 模型 %s 未开启图片输入，%d 张图不随消息发送" % (model, len(imgs)))
-        prompt = ("（用户提供了 %d 张图片，但当前模型未开启图片输入；请在回答开头提示用户"
-                  "到绑定页为该模型开启「图」开关，或改绑多模态模型。本条回答请基于"
-                  "文字部分完成。）\n\n%s" % (len(imgs), prompt))
-        imgs = []
-    msgs = [{"role": "user", "content": prompt, "images": imgs}]
-    candidates = list(modelhub._protocol_candidates(prov))
-    tools_ok = all(proto != "google" for proto, _ in candidates)   # google wire 无工具协议
-    total_usage = {"input": 0, "cached": 0, "output": 0, "total": 0}
-    text = ""
-    iters = 0
-    last_err = ""
-    ok = False
-    reasons = []            # 各迭代的思考正文（按迭代顺序拼接，供步骤记录展示）
-    max_tokens = BASE_MAX_TOKENS   # 思考占满预算时提额重试（跨迭代保持，见空正文分支）
-    escalated = False       # 本轮 run 是否已提额（只提一次，防无限翻倍）
-    empty_streak = 0        # 连续零正文轮数（拿到正文/工具即清零）
-    last_action_was_tools = False
-    repeat_tool_signature = ""
-    repeat_tool_streak = 0
-    repeat_stop = False
-    finalize_attempted = False
-    perf = {"ttft": [], "tps": []}   # 各次流式调用的首字延迟(ms)与吞吐(tok/s)
-
-    def _perf():
-        """本次 run 的体验指标：跨迭代取均值；无流式样本时返回空 dict。"""
-        if not perf["ttft"] and not perf["tps"]:
-            return {}
-        return {"first_token_ms": (round(sum(perf["ttft"]) / len(perf["ttft"]), 1)
-                                   if perf["ttft"] else 0.0),
-                "tokens_per_sec": (round(sum(perf["tps"]) / len(perf["tps"]), 2)
-                                   if perf["tps"] else 0.0)}
-
-    def _deadline_fail():
-        return {"ok": False, "text": "", "usage": dict(total_usage),
-                "error": "任务总时限已到", "model": model,
-                "provider_name": bi["provider_name"],
-                "provider_id": bi["provider_id"], "iterations": iters,
-                "cost_usd": 0.0, "reasoning": "\n\n".join(r for r in reasons if r)[:THINK_MAX_CHARS],
-                "raw": {"timed_out": True, "deadline_exceeded": True}}
-
-    def _fire(cb, *cb_args):
-        if cb is None:
-            return
-        try:
-            cb(*cb_args)
-        except Exception:
-            pass        # 可视化是增强：回调炸了不能拖垮生成
-
-    def _take_reason(reason):
-        """收一段思考：攒进本轮正文并实时回调（限长，防超长思维链撑爆 run.json）。"""
-        if not reason:
-            return
-        if not reasons:
-            reasons.append("")
-        if len(reasons[-1]) < THINK_MAX_CHARS:
-            reasons[-1] += reason
-        _fire(on_reason, reason)
-
-    def _fail(err):
-        return {"ok": False, "text": "", "usage": dict(total_usage), "error": err,
-                "model": model, "provider_name": bi["provider_name"],
-                "provider_id": bi["provider_id"], "iterations": iters, "cost_usd": 0.0,
-                "raw": _perf(),
-                "reasoning": "\n\n".join(r for r in reasons if r)[:THINK_MAX_CHARS]}
-
-    def _cancel_fail():
-        """取消终态带结构化标记：下游惩罚账（KEY 冷却/供应商健康/评测作废）靠标记
-        认出取消，不靠「已取消」字样匹配。"""
-        out = _fail("已取消")
-        out["cancelled"] = True
-        return out
-
-    # 工具上限后最多再给一次“只输出总结”的机会。这样最后一轮已经
-    # 成功写文件/抓数据但尚未总结时，不会把真实成果误报成失败。
-    for it in range(1, MAX_TOOL_ITERS + 2):
-        force_finalize = it > MAX_TOOL_ITERS or repeat_stop
-        if force_finalize and (finalize_attempted or not last_action_was_tools):
-            break
-        if force_finalize and not finalize_attempted:
-            finalize_attempted = True
-            msgs.append({"role": "user", "content":
-                         "请停止调用工具，只根据已经完成的操作直接给出最终答复。"
-                         "列出已完成内容、产出文件和仍未完成的事项；不要继续探索。"})
-            if log:
-                log("[收尾] 工具循环已到边界，发起一次无工具最终总结")
-            _fire(on_activity, "工具循环到边界，正在生成最终总结")
-        if deadline is not None and time.monotonic() >= deadline:
-            return _deadline_fail()
-        if cancel_event is not None and cancel_event.is_set():
-            return _cancel_fail()
-        reasons.append("")   # 每轮迭代各占一段思考（跨轮拼接时分段，join 时滤空段）
-        done = False
-        reBump = False         # 本轮要提额重试（同一迭代重跑，不烧迭代数）
-        stopit = False         # 本轮判死（连续零正文），直接终局不再空转
-        for _bump in range(2):                      # 第 2 圈 = 提额后的同轮重试
-            for proto, pbase in candidates:
-                keys = modelhub._chain_keys(prov) or [{"key": prov.get("api_key") or "", "id": ""}]
-                for kk in keys:
-                    got = False        # 本 KEY 拿到了响应（区别于 HTTP 失败换下家）
-                    stripped = False   # thinking 对象被网关 400 拒后已摘除重发
-                    while True:
-                        if deadline is not None and time.monotonic() >= deadline:
-                            return _deadline_fail()
-                        req_timeout = min(float(timeout), max(0.1, deadline - time.monotonic())) \
-                            if deadline is not None else timeout
-                        allow_tools = tools_ok and not force_finalize
-                        url, headers, body = _build_request(
-                            proto, pbase, kk["key"], model, system, msgs,
-                            allow_tools, max_tokens=max_tokens,
-                            extra_specs=[CREATE_TASK_SPEC] if task_creator else None)
-                        sbody = None
-                        if stream:
-                            # 流式体单独构造（+stream / include_usage）；非流式体留给回落重发
-                            _, _, sbody = _build_request(
-                                proto, pbase, kk["key"], model, system, msgs,
-                                allow_tools, stream=True, max_tokens=max_tokens,
-                                extra_specs=[CREATE_TASK_SPEC] if task_creator else None)
-                        effort = str(bi.get("reasoning_effort") or "").strip().lower()
-                        # reasoning_effort 是 OpenAI wire 字段；Anthropic thinking 使用
-                        # 另一套对象结构，向兼容网关硬塞该字段会直接得到 400。
-                        if effort in ("low", "medium", "high") and proto == "openai":
-                            body["reasoning_effort"] = effort
-                            if sbody is not None:
-                                sbody["reasoning_effort"] = effort
-                        if effort in ("low", "medium") and proto == "anthropic" \
-                                and not stripped:
-                            # 「思考程度」此前只对 openai 面生效；GLM 这类推理模型
-                            # 在 Anthropic 兼容面上默认全功率思考，能把 max_tokens
-                            # 整个烧光（2026-09-22 glm-5.3-flash 47 分钟零正文案）。
-                            # low/medium 显式给思考预算，high 留默认（模型自决=放开想）。
-                            body["thinking"] = {
-                                "type": "enabled",
-                                "budget_tokens": 1024 if effort == "low" else 4096}
-                            if sbody is not None:
-                                sbody["thinking"] = dict(body["thinking"])
-                        text, calls, usage = "", [], {}
-                        streamed = False
-                        if sbody is not None:
-                            part = _call_with_optional_deadline(
-                                _post_sse_stream,
-                                (url, headers, sbody, allow_private, req_timeout, proto),
-                                {"on_reason": _take_reason, "on_text": on_stream,
-                                 "cancel_event": cancel_event}, deadline)
-                            if part.get("deadline_exceeded"):
-                                return _deadline_fail()
-                            if part["error"] == "已取消":
-                                return _cancel_fail()
-                            if not part["error"] and part["events"]:
-                                # 网关确实按流回了：正文/工具取增量累加结果
-                                text, calls = part["text"], part["calls"]
-                                usage = part["usage"]
-                                streamed = True
-                                if part.get("first_token_ms"):
-                                    perf["ttft"].append(float(part["first_token_ms"]))
-                                if part.get("tokens_per_sec"):
-                                    perf["tps"].append(float(part["tokens_per_sec"]))
-                                if not reasons or not reasons[-1]:
-                                    # 调用方没挂实时回调（无可视化诉求）时思考只在
-                                    # 累加器里：这里兜底收进结果，落库口径一致
-                                    _take_reason(part["reasoning"])
-                            else:
-                                # 零事件（网关忽略 stream）或流式这一步失败（不认 stream 参数、
-                                # 断流等）：都退回同一条 wire 的非流式重发——比直接判死这家
-                                # 供应商稳妥；非流式也失败才走下面的记账/换链。
-                                last_err = part["error"]
-                        if not streamed:
-                            status, data, err = _call_with_optional_deadline(
-                                _post_interruptible,
-                                (url, headers, body, allow_private, req_timeout, cancel_event),
-                                {}, deadline)
-                            if err == "任务总时限已到":
-                                return _deadline_fail()
-                            if cancel_event is not None and cancel_event.is_set():
-                                # 取消先于一切记账：健康 KEY 不能因被放弃的请求背上冷却
-                                return _cancel_fail()
-                            if status == 0 or not (200 <= status < 300):
-                                msg = ""
-                                if isinstance(data, dict):
-                                    e = data.get("error")
-                                    msg = e.get("message", "") if isinstance(e, dict) else str(e)
-                                if status == 400 and isinstance(body.get("thinking"), dict) \
-                                        and "thinking" in str(msg).lower() and not stripped:
-                                    # 网关不认 thinking 对象：摘掉同 KEY 立即重发，
-                                    # 别让「思考程度」偏好把健康 KEY 送进冷却
-                                    body.pop("thinking", None)
-                                    if sbody is not None:
-                                        sbody.pop("thinking", None)
-                                    stripped = True
-                                    continue
-                                last_err = err or ("HTTP %s %s" % (status, str(msg)[:200]))
-                                try:
-                                    modelhub.note_key_error(bi["provider_id"], kk.get("id") or "", last_err)
-                                except Exception:
-                                    pass
-                                break            # 换下一个 KEY
-                            text, calls, usage = _parse_reply(proto, data)
-                            # 非流式响应里的思考字段：补发一次，可视化与流式路径同形
-                            _take_reason(_reason_from_message(proto, data))
-                        try:
-                            modelhub.note_key_ok(bi["provider_id"], kk.get("id") or "")
-                        except Exception:
-                            pass
-                        usage = _norm_usage(usage)
-                        for k in total_usage:
-                            total_usage[k] += int(usage.get(k) or 0)
-                        iters = it
-                        got = True
-                        break
-                    if not got:
-                        continue                 # 本 KEY 失败，换下一个
-                    if calls and force_finalize:
-                        # 收尾请求明确禁用工具；模型若仍返回 tool call，不能再
-                        # 开启新一轮，否则会绕过止损边界。
-                        last_err = "收尾时模型仍请求工具"
-                        last_action_was_tools = False
-                        done = True
-                        break
-                    if calls:
-                        sig = json.dumps(
-                            [(c.get("name"), c.get("args") or {}) for c in calls],
-                            ensure_ascii=False, sort_keys=True, separators=(",", ":"))
-                        if sig == repeat_tool_signature:
-                            repeat_tool_streak += 1
-                        else:
-                            repeat_tool_signature = sig
-                            repeat_tool_streak = 1
-                        if repeat_tool_streak >= 3:
-                            repeat_stop = True
-                            if log:
-                                log("[迭代 %d] 检测到同一工具调用连续重复，转入收尾" % it)
-                            _fire(on_activity, "检测到重复工具调用，正在收尾")
-                        if log:
-                            log("[迭代 %d] %s 请求工具: %s" % (
-                                it, model, ", ".join(c["name"] for c in calls)))
-                        _fire(on_activity, "请求工具: " + "、".join(c["name"] for c in calls))
-                        results = []
-                        for c in calls:
-                            out = _exec_tool(workdir, c["name"], c["args"], cancel_event,
-                                             deadline=deadline, task_creator=task_creator)
-                            # 运行期注入警示层：外部内容（网页/命令输出/文件）一律
-                            # 包围栏进上下文；检测命中升级强围栏（prompt_guard）。
-                            try:
-                                from . import prompt_guard
-                                out = prompt_guard.wrap_external(out, c["name"])
-                            except Exception:
-                                pass
-                            if log:
-                                brief = out if len(out) <= 120 else out[:120] + "…"
-                                log("[工具] %s → %s" % (c["name"], brief.replace("\n", " ⏎ ")))
-                            _fire(on_activity, "%s %s" % (
-                                c["name"], str(c["args"].get("path")
-                                               or c["args"].get("command") or "")[:80]))
-                            results.append((c["id"], out))
-                        msgs.append({"role": "assistant", "content": text, "tool_calls": calls})
-                        msgs.append({"role": "tool_results", "tool_results": results})
-                        empty_streak = 0
-                        last_action_was_tools = True
-                        done = True
-                        break
-                    if (text or "").strip():
-                        if log:
-                            log("[迭代 %d] 最终回答（%d 字）" % (it, len(text)))
-                        ok = True
-                        empty_streak = 0
-                        last_action_was_tools = False
-                        done = True
-                        break
-                    # —— 零正文零工具：分辨「思考占满输出预算」还是「模型真没说话」。
-                    # 推理模型的思考计入 max_tokens：想满了流会正常收，正文却是空的。
-                    last_action_was_tools = False
-                    rlen = len(reasons[-1] or "")
-                    out_tok = int(usage.get("output") or 0)
-                    exhausted = (rlen >= THINK_EXHAUST_MIN_CHARS
-                                 or out_tok >= int(max_tokens * 0.9))
-                    empty_streak += 1
-                    if exhausted and not escalated:
-                        # 同轮提额重试一次：8K 想不完的 16K 大多就想完了
-                        escalated = True
-                        old = max_tokens
-                        max_tokens = min(max_tokens * 2, MAX_TOKENS_CAP)
-                        last_err = ("模型思考占满输出预算（max_tokens=%d，思考 %d 字零正文）"
-                                    % (old, rlen))
-                        if log:
-                            log("[第 %d 轮] 思考 %d 字仍无正文/工具 → max_tokens %d→%d 同轮重试"
-                                % (it, rlen, old, max_tokens))
-                        _fire(on_activity, "思考占满输出预算，提高输出预算重试")
-                        reBump = True
-                        break
-                    if empty_streak >= EMPTY_TEXT_MAX_STREAK:
-                        last_err = ("模型思考连续占满输出预算（max_tokens 已提到 %d 仍无正文）"
-                                    % max_tokens) if exhausted else \
-                            ("模型连续 %d 轮零正文零工具" % empty_streak)
-                        done = True
-                        stopit = True
-                        break
-                    last_err = "模型未返回文本"
-                    if log:
-                        log("[第 %d 轮] 模型零正文零工具（思考 %d 字），重试" % (it, rlen))
-                    _fire(on_activity, "模型零正文，重试")
-                    done = True
-                    break
-                if done or reBump:
-                    break
-            if reBump:
-                continue        # 同一迭代用新预算重来
-            break               # 非提额路径一锤定音
-        if not done:
-            break   # 所有 wire/KEY 都失败
-        if ok or stopit:
-            break
-    if not ok and not text and finalize_attempted:
-        # 工具已经执行过且收尾调用也未能给正文：把真实执行结果作为“部分完成”
-        # 返回。pipeline 会按成功步骤落盘，用户可以继续追问而不是被迫重跑。
-        partial = _fail(last_err or "已完成工具操作，但未生成最终总结")
-        partial["ok"] = True
-        partial["partial"] = True
-        partial["text"] = ("部分完成：已执行部分操作，但未能生成最终总结。"
-                            "请检查工作目录中的产出文件，或继续追问以完成剩余事项。")
-        partial["error"] = last_err or "已完成工具操作，但未生成最终总结"
-        partial.setdefault("raw", {})["partial"] = True
-        return partial
-    if not ok and not text:
-        return _fail(last_err or "工具循环达上限仍无最终回答")
-    return {"ok": True, "text": (text or "").strip(), "usage": dict(total_usage),
-            "error": "", "model": model, "provider_name": bi["provider_name"],
-            "provider_id": bi["provider_id"], "iterations": iters, "cost_usd": 0.0,
-            "raw": _perf(),
-            "reasoning": "\n\n".join(r for r in reasons if r)[:THINK_MAX_CHARS]}
+# -*- coding: utf-8 -*-
+"""内置执行智能体：不经外部 CLI，直连供应商 API 完成直连（direct）任务。
+
+为什么：direct 是快档位，典型诉求是问答/轻量改写。拉起 codex/claude CLI 要付
+进程与框架开销，且 CLI 的事件流日志（启动命令、提示词回显、重连报错）会污染
+对话视图。内置智能体直接打 chat API + 工具循环：
+  - 模型选择：编排者配置（resolve_orchestrator）优先；未启用时扫首个可用供应商；
+  - 工具：list_files / read_file / write_file（锁死工作目录内）+ run_command
+    （本机全权执行命令，产品定位全信任，与 codex/claude 全权沙箱同档）；
+  - 协议：anthropic / openai 走原生工具循环；google 无工具协议（纯文本直答）。
+密钥冷却/多 KEY 展开复用 modelhub 既有记账（note_key_ok / note_key_error）。
+"""
+from __future__ import annotations
+
+import base64
+import fnmatch
+import io
+import json
+import mimetypes
+import os
+import re
+import secrets
+import shutil
+import stat
+import sys
+import threading
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from . import modelhub, runner, tlsctx
+
+MAX_TOOL_ITERS = 32          # 单步工具循环上限（防模型打转；收尾另留 1 轮）
+READ_MAX_BYTES = 64 * 1024   # read_file 单次读取上限
+READ_HEAD_BYTES = 44 * 1024  # TokenJuice 借鉴（openhuman）：超限文件头尾保留、
+READ_TAIL_BYTES = 16 * 1024  # 中段省略——日志/代码的报错常在尾部，纯截头会丢关键信息
+LIST_MAX_ENTRIES = 200
+MAX_IMAGES = 8                 # 单次最多随消息传几张图（请求体防爆）
+IMAGE_MAX_EDGE = 1568          # 长边上限（视觉模型通行建议值，超出等比缩）
+IMAGE_JPEG_BYTES = 3500 * 1024   # 缩放后仍超此大小 → 转 JPEG q85
+IMAGE_MAX_BYTES = 5 * 1024 * 1024   # 单张最终字节硬上限（超出剔除并日志）
+THINK_MAX_CHARS = 20000        # 单次生成保留的思考正文上限（防超长思维链撑爆 run.json）
+STREAM_MAX_CHARS = 20000       # 运行中实时回答的保留上限（与 THINK_MAX_CHARS 同口径）
+BASE_MAX_TOKENS = 8000         # 单次生成输出预算（推理模型的思考 token 也计入此额度）
+MAX_TOKENS_CAP = 16000         # 思考撑爆预算后的提额上限（每轮 run 只提一次）
+THINK_EXHAUST_MIN_CHARS = 1500  # 零正文时思考达到此长度 ≈ 思考占满输出预算
+EMPTY_TEXT_MAX_STREAK = 3      # 连续零正文轮数上限（防同参数盲重试烧穿预算）
+
+CMD_DEFAULT_TIMEOUT = 600    # run_command 默认超时（与 CLI 停滞看门狗同口径）
+CMD_MAX_TIMEOUT = 1800       # 上限：模型传 timeout_sec 超过即钳到这
+CMD_OUT_HEAD = 24 * 1024     # 回灌给模型的输出：头 24K + 尾 8K（报错常在尾部）
+CMD_OUT_TAIL = 8 * 1024
+TOOL_HISTORY_KEEP_ROUNDS = 4
+TOOL_HISTORY_OLD_RESULT_CHARS = 1200
+MAX_DIRECT_CONTEXT_CHARS = 48000  # ~12K tokens; keep direct chat within small model windows
+_TOOL_OUTPUT_MARKER_RE = re.compile(
+    r"\n…\[较早结果已卸载到本机；需查看全文请调用 read_tool_output，"
+    r"ref=([a-f0-9]{32}) \]…\n")
+
+_SYSTEM_PROMPT = """你是 CodeBee 的内置执行智能体，直接完成用户交代的任务。用户的目标、背景与工作目录内的附件就是全部输入。
+
+## 工作方式
+- 需要读文件、看目录、写文件时调用工具；所有路径都是工作目录内的相对路径。
+- 改文件的优先级：小改动用 edit_file（精确查找替换，不必整份重写）＞追加用 append_file＞整份重建才用 write_file。删除/移动/重命名/复制用 fs_manage，不要绕 shell。
+- 大文件（超 64KB）默认只读头尾、中段省略；要看全用 read_file 的 offset/lines 分段读（返回头会提示下一段的 offset）。找内容用 search_content（带行号的 grep），找文件用 find_files，不要逐个文件读。
+- read_file 只能读文本文件；图片、压缩包等二进制文件读不了，如实告知用户即可，不要反复尝试。
+- 较早工具结果若提示已卸载并给出 ref，使用 read_tool_output 按需读取（可传 offset 分段）；不要假设压缩标记就是完整结果。
+- 用户消息中的图片附件会直接出现在对话里，可直接看图作答，无需用工具读取。
+- run_command 直接在用户的电脑上执行命令并回传退出码与输出：诊断、修复、改配置、重启服务等操作会真实生效。命令跑完看输出再决定下一步，不要一次性罗列步骤让用户自己敲。
+- 当工具列表中提供 create_task 时，如果用户明确要求开始另一项 CodeBee 工作（例如“新建连载小说任务”“再开一个代码任务”），调用它发起独立任务；不要只在当前回答里描述应该怎么做。先从用户话里提取任务类型和目标，缺少关键目标时再追问。
+- Windows 上需要管理员权限的命令（flushdns、winsock reset、防火墙、系统服务等），用 powershell -Command "Start-Process <程序> -ArgumentList '<参数>' -Verb RunAs -Wait" 触发 UAC——用户屏幕会弹窗，点允许即提权执行；提权进程的输出拿不到，之后要用普通命令复核效果。macOS/Linux 用 sudo 并在输出里提示用户输密码不可行时改写临时脚本让用户跑。
+- 避免跑长驻/交互式命令（ping -t、top、要按键应答的安装器），它们会拖满超时被强杀。
+- 产出文件一律 UTF-8 编码。
+- 回答用户的语言与用户一致（默认中文）。直接给结论和内容，不要输出任何机器标记或协议行。
+- 核心产出完成后立即停止探索并总结；不要为“再确认一次”重复读取或重复写入。
+- 每次工具调用后都要判断是否已经达到目标；如果工具轮次即将耗尽，先完成已开始的操作，随后直接给出已完成内容、产出文件和未完成项。
+"""
+
+
+def resolve(provider_id="", model="", difficulty="default"):
+    """选内置智能体可用的 (provider, model)：编排者配置优先，否则首个可用供应商。
+
+    返回 {prov, model, provider_id, provider_name} 或 None（无可用供应商 → 调用方
+    回退 CLI 路径）。"""
+    provider_id = str(provider_id or "").strip()
+    model = str(model or "").strip()
+    if provider_id:
+        for p in modelhub.providers():
+            if p.get("id") != provider_id or not p.get("enabled", True) or not p.get("api_key"):
+                continue
+            selected = model
+            if selected:
+                try:
+                    enabled_names = [m.get("name") for m in modelhub._enabled_models(p)]
+                except Exception:
+                    enabled_names = []
+                if selected not in enabled_names:
+                    return None
+            if not selected:
+                selected = (p.get("model_hard") if difficulty == "hard" else
+                            p.get("model_easy") if difficulty == "easy" else
+                            p.get("model") or "").strip()
+            if not selected:
+                try:
+                    names = modelhub._enabled_models(p)
+                except Exception:
+                    names = []
+                selected = names[0]["name"] if names else ""
+            if selected:
+                return {"prov": p, "model": selected,
+                        "provider_id": p.get("id") or "",
+                        "provider_name": p.get("name") or p.get("id") or ""}
+        return None
+    orch = None
+    try:
+        orch = modelhub.resolve_orchestrator()
+    except Exception:
+        orch = None
+    if orch:
+        prov, model = orch
+        return {"prov": prov, "model": model,
+                "provider_id": prov.get("id") or "",
+                "provider_name": prov.get("name") or prov.get("id") or ""}
+    for p in modelhub.providers():
+        if not p.get("enabled", True) or not p.get("api_key"):
+            continue
+        m = ((p.get("model_hard") if difficulty == "hard" else
+              p.get("model_easy") if difficulty == "easy" else
+              p.get("model")) or "").strip()
+        if not m:
+            try:
+                names = modelhub._enabled_models(p)
+            except Exception:
+                names = []
+            m = names[0]["name"] if names else ""
+        if m:
+            return {"prov": p, "model": m, "provider_id": p.get("id") or "",
+                    "provider_name": p.get("name") or p.get("id") or ""}
+    return None
+
+
+# ---------------------------------------------------------------- 工作目录工具
+# 模型给的相对路径不可信：逐段拒绝 .. 与盘符，resolve() 归一后确认仍位于
+# 工作目录之下（base not in p.parents 即越界，同 skills/market 的守卫惯用法）。
+
+def _is_linklike(path):
+    """Treat symlinks and Windows junctions alike when enumerating a sandbox root."""
+    try:
+        if path.is_symlink() or (hasattr(path, "is_junction") and path.is_junction()):
+            return True
+        # Path.is_junction() was added in Python 3.12. On supported older
+        # Windows versions, detect all reparse points directly from lstat so
+        # junctions cannot bypass a narrowed allowed_roots policy.
+        attributes = getattr(path.lstat(), "st_file_attributes", 0)
+        reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+        return bool(attributes & reparse_point)
+    except OSError:
+        return True
+
+def _tool_list_files(workdir, args):
+    rel = str(args.get("path") or "").replace("\\", "/").strip("/")
+    if ".." in Path(rel).parts or any(":" in seg for seg in Path(rel).parts):
+        return "（非法路径: %s）" % rel
+    base = Path(workdir or ".").resolve()
+    p = (base / rel).resolve() if rel else base
+    if base not in p.parents and p != base:
+        return "（路径越界: %s）" % rel
+    if not p.is_dir():
+        return "（目录不存在: %s）" % (rel or ".")
+    out = []
+    for root, dirs, files in os.walk(str(p)):
+        dirs[:] = [d for d in dirs if d not in (".git", "__pycache__", "node_modules")
+                   and not _is_linklike(Path(root) / d)]
+        for f in files:
+            fp = os.path.join(root, f)
+            if _is_linklike(Path(fp)):
+                continue
+            relp = os.path.relpath(fp, str(base)).replace(os.sep, "/")
+            try:
+                size = os.path.getsize(fp)
+            except OSError:
+                size = -1
+            out.append("%s (%d B)" % (relp, size))
+            if len(out) >= LIST_MAX_ENTRIES:
+                return "\n".join(out) + "\n…（截断，共 200+ 项）"
+    return "\n".join(out) or "（空目录）"
+
+
+_BIN_MAGIC = (
+    (b"\x89PNG\r\n\x1a\n", "PNG 图片"),
+    (b"\xff\xd8\xff", "JPEG 图片"),
+    (b"GIF8", "GIF 图片"),
+    (b"%PDF-", "PDF 文档"),
+    (b"PK\x03\x04", "ZIP 压缩包"),
+    (b"\x1f\x8b", "GZIP 压缩包"),
+    (b"7z\xbc\xaf\x27\x1c", "7z 压缩包"),
+    (b"Rar!\x1a\x07", "RAR 压缩包"),
+    (b"\x00\x00\x01\x00", "ICO 图标"),
+    (b"OggS", "OGG 音频"),
+    (b"ID3", "MP3 音频"),
+)
+
+
+def _bin_format(head):
+    """常见二进制魔数 → 人类可读格式名（写进给模型的提示，让它立刻止损）。"""
+    if len(head) >= 12 and head[:4] == b"RIFF":
+        return {"WEBP": "WEBP 图片", "WAVE": "WAV 音频",
+                "AVI ": "AVI 视频"}.get(head[8:12].decode("ascii", "replace"),
+                                        "RIFF 媒体")
+    if len(head) >= 8 and head[4:8] == b"ftyp":
+        return "MP4/MOV 视频"
+    for magic, name in _BIN_MAGIC:
+        if head.startswith(magic):
+            return name
+    return "二进制文件"
+
+
+def _looks_binary(head):
+    """文本判定从宽：NUL 字节即判二进制（git 同款启发式），控制字符占比兜底
+    （部分二进制头 8KB 内无 NUL）。"""
+    if not head:
+        return False
+    if b"\x00" in head:
+        return True
+    sample = head[:8192]
+    ctrl = sum(1 for b in sample if b < 32 and b not in (9, 10, 12, 13))
+    return ctrl * 20 > len(sample)   # >5% 视为二进制
+
+
+def _trim_partial_utf8(chunk):
+    """头部截断可能把多字节字符切成两半：剥掉尾部不完整序列，否则 UTF-8
+    strict 失败会误落 GBK 解出错字（runner.tail_decoded 的头截断对偶）。"""
+    i = len(chunk) - 1
+    while i >= 0 and i >= len(chunk) - 3 and (chunk[i] & 0xC0) == 0x80:
+        i -= 1
+    if 0 <= i < len(chunk):
+        b = chunk[i]
+        need = 4 if (b & 0xF8) == 0xF0 else 3 if (b & 0xF0) == 0xE0 \
+            else 2 if (b & 0xC0) == 0xC0 else 1
+        if len(chunk) - i < need:
+            return chunk[:i]
+    return chunk
+
+
+def _guess_image_mime(path, raw=b""):
+    m = mimetypes.guess_type(str(path))[0]
+    if m:
+        return m
+    if raw.startswith(b"\x89PNG"):
+        return "image/png"
+    if raw.startswith(b"\xff\xd8"):
+        return "image/jpeg"
+    if raw.startswith(b"GIF8"):
+        return "image/gif"
+    if raw.startswith(b"RIFF"):
+        return "image/webp"
+    return "image/png"
+
+
+def _prep_images(paths, log=None):
+    """图片路径 → [(mime, b64)]。Pillow 可用时：长边超 1568px 等比缩（万级像素
+    原图既烧 token 又常被网关拒），仍超 3.5MB 转 JPEG q85；Pillow 缺失或解码
+    失败时原图直传，单张超 5MB 剔除并日志。最多 MAX_IMAGES 张。"""
+    try:
+        from PIL import Image
+    except Exception:
+        Image = None
+    out = []
+    for p in (paths or [])[:MAX_IMAGES]:
+        try:
+            raw = Path(p).read_bytes()
+        except OSError:
+            if log:
+                log("[图片] 跳过（读取失败）: %s" % os.path.basename(str(p)))
+            continue
+        mime = _guess_image_mime(p, raw)
+        data = raw
+        if Image is not None:
+            try:
+                im = Image.open(io.BytesIO(raw))
+                im.load()
+                w, h = im.size
+                edge = max(w, h, 1)
+                if edge > IMAGE_MAX_EDGE:
+                    r = IMAGE_MAX_EDGE / float(edge)
+                    im = im.resize((max(1, round(w * r)), max(1, round(h * r))),
+                                   Image.LANCZOS)
+                fmt = {"image/png": "PNG", "image/jpeg": "JPEG",
+                       "image/gif": "GIF", "image/webp": "WEBP"}.get(mime, "PNG")
+                buf = io.BytesIO()
+                im.save(buf, format=fmt)   # GIF 多帧仅存首帧，可接受
+                data = buf.getvalue()
+            except Exception:
+                data = raw                 # 解码/编码失败退回原始字节
+        if (Image is not None and mime != "image/jpeg"
+                and len(data) > IMAGE_JPEG_BYTES):
+            try:                           # 仍过大：转 JPEG q85（RGB 拍平 alpha）
+                im = Image.open(io.BytesIO(data)).convert("RGB")
+                buf = io.BytesIO()
+                im.save(buf, format="JPEG", quality=85)
+                data = buf.getvalue()
+                mime = "image/jpeg"
+            except Exception:
+                pass
+        if len(data) > IMAGE_MAX_BYTES:
+            if log:
+                log("[图片] 剔除（过大 %d MB）: %s"
+                    % (len(data) // (1024 * 1024), os.path.basename(str(p))))
+            continue
+        out.append((mime, base64.b64encode(data).decode("ascii")))
+    return out
+
+
+def _tool_read_file(workdir, args):
+    rel = str(args.get("path") or "").replace("\\", "/").strip("/")
+    if not rel or ".." in Path(rel).parts or any(":" in seg for seg in Path(rel).parts):
+        return "（非法路径: %s）" % rel
+    base = Path(workdir or ".").resolve()
+    p = (base / rel).resolve()
+    if base not in p.parents:
+        return "（路径越界: %s）" % rel
+    if not p.is_file():
+        return "（文件不存在: %s）" % rel
+    # 分段读取（P0 基础件）：offset/lines 任一非空即按行号范围读——超 64KB
+    # 被「头尾保留、中段省略」截断的大文件靠它读全（用户实测 _lessons_dump.txt
+    # 68KB 被截案）。行号 1-based；逐行切片后不强行拼回整份。
+    offset_raw = str(args.get("offset") or "").strip()
+    lines_raw = str(args.get("lines") or "").strip()
+    if offset_raw or lines_raw:
+        try:
+            size = p.stat().st_size
+        except OSError as e:
+            return "（读取失败: %s）" % e
+        if size > READ_EDIT_MAX_BYTES:
+            return ("（文件过大 %d MB，分段读取上限 %d MB；请用 run_command 处理）"
+                    % (size // (1024 * 1024), READ_EDIT_MAX_BYTES // (1024 * 1024)))
+        try:
+            offset = max(1, int(float(offset_raw or 1)))
+            lines = max(1, min(READ_SEGMENT_MAX_LINES,
+                               int(float(lines_raw or READ_SEGMENT_DEFAULT_LINES))))
+        except (TypeError, ValueError):
+            return "（offset/lines 须为整数行号）"
+        all_lines = runner.decode_output(p.read_bytes()).splitlines()
+        total = len(all_lines)
+        if total == 0:
+            return "（空文件）"
+        if offset > total:
+            return "（offset %d 超出文件总行数 %d）" % (offset, total)
+        seg = all_lines[offset - 1:offset - 1 + lines]
+        head = "第 %d–%d 行（共 %d 行；用 offset=%d 续读下一段）" % (
+            offset, offset - 1 + len(seg), total, offset + len(seg))
+        return head + "\n" + ("\n".join(seg) or "（该范围无内容）")
+    data = p.read_bytes()[:READ_MAX_BYTES + 1]
+    truncated = len(data) > READ_MAX_BYTES
+    if truncated:
+        # 头尾保留、中段省略（TokenJuice 借鉴）：头 44k 给结构/开头上下文，
+        # 尾 16k 给报错/结论（日志与代码的关键信息常在末尾），中段标注省略量
+        try:
+            size = p.stat().st_size
+        except OSError:
+            size = len(data)
+        with open(p, "rb") as fh:
+            head = fh.read(READ_HEAD_BYTES)
+            fh.seek(max(0, size - READ_TAIL_BYTES))
+            tail = fh.read(READ_TAIL_BYTES)
+        head = _trim_partial_utf8(head)
+        # 尾段开头的残缺多字节序列剥头（对偶于 _trim_partial_utf8 剥尾）
+        while tail:
+            try:
+                tail.decode("utf-8")
+                break
+            except UnicodeDecodeError:
+                tail = tail[1:]
+        text = runner.decode_output(head) \
+            + "\n…（中段省略 %d 字节；头 %dKB + 尾 %dKB 保留）\n" % (
+                max(0, size - READ_HEAD_BYTES - READ_TAIL_BYTES),
+                READ_HEAD_BYTES // 1024, READ_TAIL_BYTES // 1024) \
+            + runner.decode_output(tail)
+        return "…（文件超 64KB，已头尾保留读取）\n" + text
+    head = data
+    if not head:
+        return "（空文件）"
+    if _looks_binary(head):
+        try:
+            size = p.stat().st_size
+        except OSError:
+            size = len(head)
+        fmt = _bin_format(head)
+        if "图片" in fmt:
+            return ("（图片文件: %s — %s，%d B，无法按文本读取。用户以附件发来的图片会"
+                    "直接出现在对话中，无需用工具读取；若需要目录里这张图的内容，"
+                    "请提示用户把它作为附件发送。）" % (rel, fmt, size))
+        return ("（二进制文件，无法按文本读取: %s — %s，%d B。read_file 只支持文本文件；"
+                "请如实告知用户该文件内容无法以文本方式查看，不要反复重读。）"
+                % (rel, fmt, size))
+    text = runner.decode_output(head)
+    return text
+
+
+def _tool_write_file(workdir, args):
+    rel = str(args.get("path") or "").replace("\\", "/").strip("/")
+    if not rel or ".." in Path(rel).parts or any(":" in seg for seg in Path(rel).parts):
+        return "（非法路径: %s）" % rel
+    content = str(args.get("content") if args.get("content") is not None else "")
+    base = Path(workdir or ".").resolve()
+    dest = (base / rel).resolve()
+    if base not in dest.parents:
+        return "（路径越界: %s）" % rel
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    # newline=""：不翻译换行——模型回写 read_file 读到的 CRLF 内容时，
+    # 默认翻译会二次翻成 \r\r\n
+    with dest.open("w", encoding="utf-8", newline="") as fh:
+        fh.write(content)
+    return "已写入 %s（%d 字符，UTF-8）" % (rel, len(content))
+
+
+def _tool_run_command(workdir, args, cancel_event=None, deadline=None, sandbox=None):
+    """本机执行一条 shell 命令，返回 (退出码, 合并输出)。
+
+    薄适配层：执行/杀树/取消/解码全部复用 runner.run_process（shell_cmd 分支
+    → cmd /c 或 /bin/sh -c），仓库唯一的 shell 落点，不另起炉灶。全信任档
+    （用户拍板 2026-09-22）：无白名单无确认闸，与 codex/claude 全权沙箱同档。
+    提权靠模型自己包 Start-Process -Verb RunAs——UAC 必须人点，绕不过也不该绕。
+    输出按字符头尾截断（解码已在 run_process 完成，无残缺多字节问题）。"""
+    cmdline = str(args.get("command") or "").strip()
+    if not cmdline:
+        return "（命令为空，未执行）"
+    from . import policy
+    sandbox = sandbox or policy.normalize_sandbox({}, workdir)
+    timeout = _command_timeout(args, sandbox)
+    cwd = os.path.abspath(workdir or ".")
+    if not policy.path_allowed(cwd, sandbox):
+        return "（沙箱拒绝：工作目录不在允许范围内，命令未执行）"
+    # This process runner has no OS-level network/filesystem namespace. Do not
+    # imply network isolation when policy requests it; fail closed instead.
+    if sandbox.get("network") is False:
+        if os.name != "posix" or not shutil.which("bwrap"):
+            return "（沙箱拒绝：当前系统没有可用的网络隔离后端，命令未执行）"
+    # Enforce the declared filesystem boundary at the process boundary too.
+    # bubblewrap is the supported Linux backend. Windows/macOS without an
+    # equivalent backend fail closed rather than pretending cwd is a sandbox.
+    if os.name == "posix" and shutil.which("bwrap"):
+        argv = ["bwrap", "--die-with-parent", "--new-session", "--tmpfs", "/"]
+        # Mount only the runtime needed by ordinary commands. Do not expose the
+        # entire host root read-only: read access can still leak user secrets.
+        for system_path in ("/usr", "/bin", "/sbin", "/lib", "/lib64", "/etc"):
+            if os.path.exists(system_path):
+                argv.extend(["--dir", system_path, "--ro-bind", system_path, system_path])
+        for volatile_path in ("/proc", "/dev"):
+            argv.extend(["--dir", volatile_path])
+        argv.extend(["--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp"])
+        if sandbox.get("network") is False:
+            argv.append("--unshare-net")
+        for allowed_root in sandbox.get("allowed_roots") or []:
+            root_path = str(Path(allowed_root).resolve())
+            parents = list(reversed(Path(root_path).parents))
+            for parent in parents:
+                if str(parent) != "/":
+                    argv.extend(["--dir", str(parent)])
+            argv.extend(["--dir", root_path])
+            argv.extend(["--bind", root_path, root_path])
+        argv.extend(["--chdir", cwd, "--", "/bin/sh", "-lc", cmdline])
+    elif os.name == "posix" and sys.platform == "darwin":
+        return "（沙箱拒绝：当前 macOS 执行器尚未接入文件系统隔离后端，命令未执行）"
+    elif os.name != "posix":
+        return "（沙箱拒绝：当前 Windows 执行器尚未接入文件系统隔离后端，命令未执行）"
+    else:
+        return "（沙箱拒绝：未安装 bubblewrap 隔离后端，命令未执行）"
+    env_policy = dict(sandbox)
+    env_policy["env_allowlist"] = list(dict.fromkeys(
+        list(sandbox.get("env_allowlist") or [])
+        + ["PATH", "SYSTEMROOT", "WINDIR", "TEMP", "TMP", "COMSPEC", "HOME", "USERPROFILE"]))
+    r = runner.run_process(argv=argv, cwd=cwd,
+                           env=policy.filter_env(os.environ, env_policy),
+                           timeout=min(timeout, CMD_MAX_TIMEOUT),
+                           deadline=deadline, cancel_event=cancel_event)
+    out = runner.clean_cli_text(
+        (r.get("stdout") or "") + (("\n" + r["stderr"]) if r.get("stderr") else ""))
+    limit = min(CMD_OUT_HEAD + CMD_OUT_TAIL,
+                max(1024, int(sandbox.get("max_output_bytes") or CMD_OUT_HEAD + CMD_OUT_TAIL)))
+    if not out.strip():
+        body = "（无输出）"
+    elif len(out) <= limit:
+        body = out
+    else:
+        body = (out[:CMD_OUT_HEAD]
+                + "\n…（中段省略 %d 字符；头 %dK + 尾 %dK 保留）\n" % (
+                    len(out) - limit, CMD_OUT_HEAD // 1024, CMD_OUT_TAIL // 1024)
+                + out[-CMD_OUT_TAIL:])
+    if r.get("cancelled"):
+        note = "已取消，进程树已终止"
+    elif r.get("timed_out"):
+        note = "超时 %d 秒，进程树已强制终止" % timeout
+    else:
+        note = ""
+    prefix = ("（%s）\n" % note) if note else ""
+    code = r.get("exit_code")
+    return ("%s退出码: %s\n%s\n（注意：shell 命令副作用不纳入文件检查点，"
+            "不能保证可回滚）") % (prefix, "未知" if code is None else code, body)
+
+
+def _command_timeout(args, sandbox):
+    """Resolve the shell timeout without exceeding the task's sandbox budget."""
+    try:
+        requested = int(float((args or {}).get("timeout_sec") or CMD_DEFAULT_TIMEOUT))
+    except (TypeError, ValueError):
+        requested = CMD_DEFAULT_TIMEOUT
+    try:
+        policy_limit = int(float((sandbox or {}).get("timeout_s") or CMD_MAX_TIMEOUT))
+    except (TypeError, ValueError):
+        policy_limit = CMD_MAX_TIMEOUT
+    return max(1, min(requested, policy_limit, CMD_MAX_TIMEOUT))
+
+
+# ---------------------------------------------------------------- P0 基础件扩展
+# 2026-09-25 用户实测反馈：改大文件只能整份读写、删/移/改名只能绕 shell、
+# 大文件 64KB 中段被截、找内容只能逐文件读——补齐四个基础件（局部编辑、
+# 文件管理、分段读取、全文搜索），全部锁死工作目录内。
+
+READ_EDIT_MAX_BYTES = 16 * 1024 * 1024   # edit/append 分段读全文解码上限
+SEARCH_MAX_FILE_BYTES = 2 * 1024 * 1024  # search_content 单文件参与搜索上限
+SEARCH_DEFAULT_RESULTS = 50              # 命中行默认上限
+READ_SEGMENT_DEFAULT_LINES = 200         # read_file 分段默认行数
+READ_SEGMENT_MAX_LINES = 2000            # read_file 分段行数上限
+
+_WALK_PRUNE = {".git", "__pycache__", "node_modules", ".venv", "venv",
+               "dist", "build", "target", ".idea", ".vscode", "__MACOSX",
+               ".pytest_cache", ".mypy_cache"}
+
+
+def _guard_rel(workdir, rel, allow_root=False):
+    """工作目录相对路径守卫（list/read/write 同款惯用法抽公共）。
+
+    返回 (resolve 后的 Path, 错误串)；合法时错误串为 None。空 rel 仅在
+    allow_root=True 时代表工作目录根。"""
+    rel = str(rel or "").replace("\\", "/").strip("/")
+    if (not rel and not allow_root) or ".." in Path(rel).parts \
+            or any(":" in seg for seg in Path(rel).parts):
+        return None, "（非法路径: %s）" % rel
+    base = Path(workdir or ".").resolve()
+    p = (base / rel).resolve() if rel else base
+    if base not in p.parents and p != base:
+        return None, "（路径越界: %s）" % rel
+    return p, None
+
+
+def _read_text_capped(p, limit=READ_EDIT_MAX_BYTES):
+    """读文本并识别编码（bytes 上限防巨型文件）。返回 (text, err)。"""
+    try:
+        size = p.stat().st_size
+    except OSError as e:
+        return "", "（读取失败: %s）" % e
+    if size > limit:
+        return "", ("（文件过大 %d MB，超过 %d MB 上限；请用 run_command 处理）"
+                    % (size // (1024 * 1024), limit // (1024 * 1024)))
+    data = p.read_bytes()
+    if _looks_binary(data[:8192]):
+        return "", "（二进制文件，%s 不适用: %s）" % ("文本编辑", _bin_format(data[:64]))
+    return runner.decode_output(data), None
+
+
+def _tool_edit_file(workdir, args):
+    """精确查找替换：old_text 逐字符匹配，默认仅允许 1 处命中。"""
+    p, err = _guard_rel(workdir, args.get("path"))
+    if err:
+        return err
+    old_text = str(args.get("old_text") or "")
+    new_text = str(args.get("new_text") if args.get("new_text") is not None else "")
+    if not old_text:
+        return "（old_text 不能为空；改全文请用 write_file 整份写入）"
+    if not p.is_file():
+        return "（文件不存在: %s）" % p.name
+    text, err = _read_text_capped(p)
+    if err:
+        return err
+    count = text.count(old_text)
+    crlf = False
+    if count == 0 and "\r\n" in text and "\r\n" not in old_text:
+        # Windows 文件 CRLF：按 LF 形态重试匹配，命中则在原文上以 CRLF 替换，
+        # 保持文件既有换行风格（否则整个文件换行符被翻转）
+        crlf_text = text.replace("\r\n", "\n")
+        count = crlf_text.count(old_text)
+        crlf = count > 0
+    if count == 0:
+        return ("（old_text 在文件中找不到逐字符匹配——read_file 超过 64KB 会"
+                "中段省略，请用 offset/lines 分段读全后重试）")
+    replace_all = str(args.get("replace_all") or "").strip().lower() in ("1", "true", "yes")
+    if count > 1 and not replace_all:
+        return ("（old_text 命中 %d 处；请补充更多上下文使命中唯一，"
+                "或传 replace_all=true 全部替换）" % count)
+    if crlf:
+        old_text = old_text.replace("\n", "\r\n")
+        new_text = new_text.replace("\n", "\r\n")
+    # newline="" 禁止 Python 的 \n→os.linesep 翻译：文件既有 CRLF 时会被
+    # 二次翻译成 \r\r\n（Windows 实测损坏案），写什么落什么
+    with p.open("w", encoding="utf-8", newline="") as fh:
+        fh.write(text.replace(old_text, new_text))
+    return "已替换 %d 处（%s）" % (count if replace_all else 1, p.name)
+
+
+def _tool_append_file(workdir, args):
+    """文件末尾追加（bytes 级追加，大文件不整份重写）；不存在则创建。"""
+    p, err = _guard_rel(workdir, args.get("path"))
+    if err:
+        return err
+    content = str(args.get("content") if args.get("content") is not None else "")
+    if not content:
+        return "（content 不能为空）"
+    if p.is_file():
+        with open(p, "rb") as fh:
+            head = fh.read(8192)
+        if _looks_binary(head):
+            return "（二进制文件，不能按文本追加: %s — %s）" % (p.name, _bin_format(head))
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with open(p, "ab") as fh:
+        fh.write(content.encode("utf-8"))
+    return "已追加 %d 字符到 %s（UTF-8）" % (len(content), p.name)
+
+
+def _tool_fs_manage(workdir, args):
+    """删除 / 移动 / 重命名 / 复制（工作目录内；目标已存在一律拒绝防覆盖）。"""
+    action = str(args.get("action") or "").strip().lower()
+    if action not in ("delete", "move", "rename", "copy"):
+        return "（action 须为 delete/move/rename/copy）"
+    p, err = _guard_rel(workdir, args.get("path"))
+    if err:
+        return err
+    if not p.exists() and not p.is_symlink():
+        return "（不存在: %s）" % p
+    if action == "delete":
+        if p.is_dir() and not p.is_symlink():
+            shutil.rmtree(str(p))
+            return "已删除目录（含全部内容）: %s" % p.name
+        p.unlink()
+        return "已删除: %s" % p.name
+    dest, err = _guard_rel(workdir, args.get("dest"))
+    if err:
+        return err.replace("非法路径", "dest 非法路径").replace("路径越界", "dest 路径越界")
+    if dest.exists() or dest.is_symlink():
+        return "（目标已存在，拒绝覆盖: %s；先删除或换名）" % dest.name
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if action == "copy":
+        if p.is_dir():
+            shutil.copytree(str(p), str(dest))
+        else:
+            shutil.copy2(str(p), str(dest))
+        return "已复制 %s → %s" % (p.name, dest.name)
+    shutil.move(str(p), str(dest))
+    return "已%s %s → %s" % ("移动" if action == "move" else "重命名",
+                             p.name, dest.name)
+
+
+def _tool_search_content(workdir, args):
+    """grep 式内容搜索：正则（编译失败回退字面量），逐行命中带行号。"""
+    pattern = str(args.get("pattern") or "").strip()
+    if not pattern:
+        return "（pattern 不能为空）"
+    try:
+        rx = re.compile(pattern)
+    except re.error:
+        rx = re.compile(re.escape(pattern))
+        pattern_note = "（正则无效，已按字面量搜索）\n"
+    else:
+        pattern_note = ""
+    sub, err = _guard_rel(workdir, args.get("path"), allow_root=True)
+    if err:
+        return err
+    if not sub.is_dir():
+        return "（目录不存在: %s）" % args.get("path")
+    glob_pat = str(args.get("glob") or "").strip()
+    try:
+        max_results = max(1, min(200, int(float(args.get("max_results") or 0)
+                                        or SEARCH_DEFAULT_RESULTS)))
+    except (TypeError, ValueError):
+        max_results = SEARCH_DEFAULT_RESULTS
+    base = Path(workdir or ".").resolve()
+    out, hits, scanned = [], 0, 0
+    for root, dirs, files in os.walk(str(sub)):
+        dirs[:] = [d for d in dirs if d not in _WALK_PRUNE
+                   and not _is_linklike(Path(root) / d)]
+        for f in files:
+            if glob_pat:
+                relp = os.path.relpath(os.path.join(root, f), str(base)).replace(os.sep, "/")
+                if not (fnmatch.fnmatch(f, glob_pat) or fnmatch.fnmatch(relp, glob_pat)):
+                    continue
+            fp = os.path.join(root, f)
+            try:
+                if _is_linklike(Path(fp)):
+                    continue
+                if os.path.getsize(fp) > SEARCH_MAX_FILE_BYTES:
+                    continue
+                with open(fp, "rb") as fh:
+                    head = fh.read(8192)
+                if _looks_binary(head):
+                    continue
+                with open(fp, "rb") as fh:
+                    data = fh.read()
+            except OSError:
+                continue
+            scanned += 1
+            rel = os.path.relpath(fp, str(base)).replace(os.sep, "/")
+            for i, line in enumerate(runner.decode_output(data).splitlines(), 1):
+                if rx.search(line):
+                    out.append("%s:%d: %s" % (rel, i, line.strip()[:200]))
+                    hits += 1
+                    if hits >= max_results:
+                        out.append("…（已达 %d 行上限，缩小 pattern/glob 或调大 max_results）"
+                                   % max_results)
+                        return pattern_note + "\n".join(out)
+    if not out:
+        return pattern_note + ("（无命中；已扫描 %d 个文本文件）" % scanned)
+    return pattern_note + "\n".join(out) + "\n（共 %d 行命中 / 扫描 %d 个文件）" % (hits, scanned)
+
+
+def _tool_find_files(workdir, args):
+    """文件名通配查找（fnmatch；pattern 不含 / 时匹配任意深度的文件名）。"""
+    pattern = str(args.get("pattern") or "").strip().replace("\\", "/")
+    if not pattern or ".." in pattern or ":" in pattern:
+        return "（非法 pattern: %s；示例 *.py 或 data/*.json）" % pattern
+    base = Path(workdir or ".").resolve()
+    sub, err = _guard_rel(workdir, args.get("path"), allow_root=True)
+    if err:
+        return err
+    if not sub.is_dir():
+        return "（目录不存在: %s）" % (args.get("path") or ".")
+    match_name = "/" not in pattern
+    out = []
+    for root, dirs, files in os.walk(str(sub)):
+        dirs[:] = [d for d in dirs if d not in _WALK_PRUNE
+                   and not _is_linklike(Path(root) / d)]
+        for f in files:
+            rel = os.path.relpath(os.path.join(root, f), str(base)).replace(os.sep, "/")
+            if not (fnmatch.fnmatch(rel, pattern)
+                    or (match_name and fnmatch.fnmatch(f, pattern))):
+                continue
+            if _is_linklike(Path(root) / f):
+                continue
+            try:
+                size = os.path.getsize(os.path.join(root, f))
+            except OSError:
+                size = -1
+            out.append("%s (%d B)" % (rel, size))
+            if len(out) >= LIST_MAX_ENTRIES:
+                return "\n".join(out) + "\n…（截断，共 %d+ 项）" % LIST_MAX_ENTRIES
+    return "\n".join(out) or "（无匹配文件）"
+
+
+TOOLS_SPEC = [
+    {"name": "list_files", "description": "列出工作目录（或其子目录）下的文件",
+     "args": {"path": "子目录相对路径，留空=根目录"}},
+    {"name": "read_file", "description": "读取工作目录内一个文本文件（UTF-8/GBK 自动识别；默认超 64KB 时保留开头与结尾、中段省略，此时用 offset/lines 分段读全；图片等二进制文件无法读取）",
+     "args": {"path": "文件相对路径",
+              "?offset": "可选，起始行号（1-based），配合 lines 分段读取大文件",
+              "?lines": "可选，读取行数（默认 200，最大 2000）"}},
+    {"name": "edit_file", "description": "对文件做精确查找替换（局部编辑，不必整份重写）：old_text 必须与文件内容逐字符一致，默认要求命中唯一，配合 read_file 使用",
+     "args": {"path": "文件相对路径",
+              "old_text": "要被替换的原文（逐字符精确匹配）",
+              "new_text": "替换后的新文本（可为空串=删除）",
+              "?replace_all": "可选，true=替换全部命中（默认仅允许 1 处命中）"}},
+    {"name": "append_file", "description": "把文本追加到文件末尾（bytes 级追加，大文件不必整份重写）；文件不存在则创建。追加日志、逐条记录时优先用它",
+     "args": {"path": "文件相对路径", "content": "追加到末尾的文本"}},
+    {"name": "fs_manage", "description": "文件管理：删除 / 移动 / 重命名 / 复制（工作目录内；目标已存在一律拒绝覆盖，删目录会连内容一起删）",
+     "args": {"action": "delete | move | rename | copy",
+              "path": "源相对路径（目录或文件）",
+              "?dest": "move/rename/copy 的目标相对路径"}},
+    {"name": "search_content", "description": "全文内容搜索（grep 式）：在工作目录内逐文件逐行匹配正则，命中行带「路径:行号:」前缀返回；自动跳过二进制与依赖目录（node_modules/.git 等）",
+     "args": {"pattern": "搜索文本或正则表达式",
+              "?path": "可选，限定搜索的子目录，默认根目录",
+              "?glob": "可选，文件名过滤，如 *.py",
+              "?max_results": "可选，命中行数上限（默认 50，最大 200）"}},
+    {"name": "find_files", "description": "按文件名通配查找文件（如 *.py、data/*.json、report*.md）；pattern 不含 / 时匹配任意深度的文件名",
+     "args": {"pattern": "文件名通配模式",
+              "?path": "可选，限定搜索的子目录，默认根目录"}},
+    {"name": "read_tool_output", "description": "按 ref 重新读取本次运行中卸载到本机的较早工具输出；大结果可用 offset 分段读取",
+     "args": {"ref": "压缩提示提供的工具结果引用",
+              "?offset": "可选，字节偏移，默认 0",
+              "?limit": "可选，返回字符数，最大 20000"}},
+    {"name": "write_file", "description": "把文本内容写入工作目录内一个文件（UTF-8，整份覆盖，父目录自动创建；只改一小段请用 edit_file）",
+     "args": {"path": "文件相对路径", "content": "完整文本内容"}},
+    {"name": "run_command",
+     "description": "在本机执行一条 shell 命令，返回退出码与合并输出。诊断、修复、改配置、重启服务等操作真实生效；先跑命令看结果再定下一步。默认超时 600 秒，可用 timeout_sec 调整（5~1800）。Windows 需要管理员权限的命令（flushdns/防火墙/系统服务等）用 powershell -Command \"Start-Process <程序> -ArgumentList '<参数>' -Verb RunAs -Wait\" 触发 UAC（用户点允许后提权执行；提权进程输出拿不到，事后用普通命令复核）。避免长驻/交互式命令（ping -t、top、按键应答的安装器）。",
+     "args": {"command": "完整命令行（shell 语法，本机直接执行）",
+              "timeout_sec": "可选，超时秒数"}},
+]
+
+_TOOL_IMPL = {"list_files": _tool_list_files, "read_file": _tool_read_file,
+              "write_file": _tool_write_file, "run_command": _tool_run_command,
+              "edit_file": _tool_edit_file, "append_file": _tool_append_file,
+              "fs_manage": _tool_fs_manage, "search_content": _tool_search_content,
+              "find_files": _tool_find_files}
+
+
+CREATE_TASK_SPEC = {
+    "name": "create_task",
+    "description": "发起一个独立的 CodeBee 任务。用户要求开始另一类工作（例如创建连载小说、写代码或生成文档）时使用；任务会出现在任务列表并异步运行，不要把它当作当前对话里的普通回答。",
+    "args": {
+        "type": "任务类型 ID，例如 serial_novel、novel、code、doc、article",
+        "goal": "新任务的明确目标",
+        "?title": "新任务标题",
+        "?workdir": "绝对工作目录；留空沿用当前工作目录",
+        "?context": "补充背景或约束",
+        "?chapters": "serial_novel 首批章节数",
+        "?words_per_chapter": "serial_novel 每章目标字数",
+        "?start_chapter": "续写起始章节号",
+        "?variants": "连载同章候选稿数量（1-3）",
+        "?branches": "连载剧情分支数量（1-3）",
+        "?story_bible": "连载小说初始故事圣经",
+    },
+}
+
+
+def _tool_create_task(workdir, args, task_creator=None, sandbox=None):
+    """Create a separate task through the caller-owned task boundary."""
+    if task_creator is None:
+        return "（当前对话不支持发起新任务）"
+    task_type = str(args.get("type") or "").strip().lower()
+    goal = str(args.get("goal") or "").strip()
+    if not task_type:
+        return "（type 不能为空；可用类型请使用 serial_novel、novel、code、doc 等）"
+    if not goal:
+        return "（goal 不能为空）"
+    requested_workdir = str(args.get("workdir") or workdir or "").strip()
+    if sandbox and requested_workdir:
+        from . import policy
+        if not policy.path_allowed(requested_workdir, sandbox):
+            return "（沙箱拒绝：子任务工作目录超出允许范围，未创建）"
+    child_sandbox = dict(sandbox) if isinstance(sandbox, dict) else None
+    if child_sandbox and requested_workdir:
+        from . import policy
+        parent_root = Path(workdir or ".").expanduser().resolve()
+        child_root = Path(requested_workdir).expanduser().resolve()
+        if child_root != parent_root:
+            # The requested child directory is already checked against the
+            # parent's roots above. Rebase the inherited allowlist to that
+            # directory so task normalization cannot widen it back to a parent.
+            child_sandbox["allowed_roots"] = [str(child_root)]
+    payload = {
+        "type": task_type,
+        "goal": goal,
+        "title": str(args.get("title") or "").strip(),
+        "workdir": requested_workdir,
+        "context": str(args.get("context") or "").strip(),
+    }
+    if child_sandbox is not None:
+        payload["sandbox"] = child_sandbox
+    if task_type == "serial_novel":
+        serial = {}
+        for key in ("chapters", "words_per_chapter", "start_chapter", "variants", "branches"):
+            if args.get(key) not in (None, ""):
+                serial[key] = args.get(key)
+        if serial:
+            payload["serial"] = serial
+        if args.get("story_bible") not in (None, ""):
+            payload["story_bible"] = str(args.get("story_bible") or "").strip()
+    try:
+        result = task_creator(payload)
+    except Exception as exc:
+        return "（发起任务失败：%s）" % str(exc)[:300]
+    if not isinstance(result, dict) or not result.get("task_id"):
+        return "（发起任务失败：未返回任务编号）"
+    return "已发起新任务：%s（运行编号：%s，类型：%s）" % (
+        result["task_id"], result.get("run_id") or "", task_type)
+
+
+def _exec_tool(workdir, name, args, cancel_event=None, deadline=None, task_creator=None,
+               disabled_tools=None, sandbox=None, checkpoint_run_id="",
+               tool_output_run_id=""):
+    from . import policy
+    denied = set(policy.normalize_disabled_tools(disabled_tools))
+    if sandbox is None:
+        sandbox = policy.normalize_sandbox({}, workdir)
+    denied.update(sandbox.get("disabled_tools") or [])
+    if name in denied:
+        return "（工具已禁用，拒绝执行: %s）" % str(name or "")[:120]
+    # All built-in file tools are constrained to the task's allowed roots, not
+    # merely hidden from the model. Shell/MCP effects are handled separately.
+    if name in {"list_files", "read_file", "write_file", "edit_file", "append_file",
+                "fs_manage", "search_content", "find_files"}:
+        keys = ["path", "dest"]
+        # Enumeration tools default to the whole workspace. If policy grants
+        # only a narrower root, require an explicit in-scope path instead of
+        # silently exposing names/content outside that root.
+        if name in {"list_files", "search_content", "find_files"} \
+                and not (args or {}).get("path") \
+                and not policy.path_allowed(workdir or ".", sandbox):
+            return "（沙箱拒绝：此工具必须指定允许范围内的 path，未执行）"
+        for key in keys:
+            value = (args or {}).get(key)
+            if not value:
+                continue
+            candidate = Path(str(value)).expanduser()
+            if not candidate.is_absolute():
+                candidate = Path(workdir or ".") / candidate
+            if not policy.path_allowed(candidate, sandbox):
+                return "（沙箱拒绝：%s 超出允许工作目录，未执行）" % key
+    if name == "create_task":
+        return _tool_create_task(workdir, args or {}, task_creator=task_creator,
+                                 sandbox=sandbox)
+    if name == "read_tool_output":
+        from . import tool_outputs
+        result = tool_outputs.read(tool_output_run_id, (args or {}).get("ref"),
+                                   offset=(args or {}).get("offset", 0),
+                                   limit=(args or {}).get("limit", 20000))
+        if not result.get("ok"):
+            return "（%s）" % result.get("error", "工具结果不可用")
+        text = result.get("text") or ""
+        if result.get("next_offset") is not None:
+            text += "\n…[后续内容可继续 read_tool_output，offset=%s]…" % result["next_offset"]
+        return text
+    if str(name or "").startswith("mcp__"):
+        # MCP process launch enforces this policy through bubblewrap; platforms
+        # without the isolation backend fail closed in mcp_client._sandbox_launch.
+        remaining = None
+        if deadline is not None:
+            remaining = float(deadline) - time.monotonic()
+            if remaining <= 0:
+                return "（任务总时限已到，MCP 工具未执行）"
+        # MCP 工具：透传给配置的服务器（stdio JSON-RPC）；超时给足但封顶
+        try:
+            from . import mcp_client
+            timeout_s = min(float(sandbox.get("timeout_s") or CMD_MAX_TIMEOUT),
+                            remaining if remaining is not None else CMD_MAX_TIMEOUT)
+            r = mcp_client.dispatch_full_name(
+                name, args or {}, sandbox=sandbox, workdir=workdir,
+                disabled_tools=denied, timeout_s=timeout_s)
+            return r.get("text") or ("（MCP 工具失败: %s）" % r.get("error") if not r.get("ok") else "")
+        except Exception as e:
+            return "MCP 工具执行失败: %s" % e
+    fn = _TOOL_IMPL.get(name or "")
+    if fn is None:
+        return "（未知工具: %s）" % name
+    try:
+        snapshot_paths = []
+        if checkpoint_run_id and name in {"write_file", "edit_file", "append_file", "fs_manage"}:
+            action = str((args or {}).get("action") or "").lower()
+            src_value = (args or {}).get("path")
+            src = Path(str(src_value)).expanduser() if src_value else None
+            if src is not None and not src.is_absolute():
+                src = Path(workdir or ".") / src
+            if src is not None:
+                if name == "fs_manage" and src.is_dir() and not src.is_symlink():
+                    return "（检查点拒绝：目录级操作尚不支持完整快照，未执行；请明确改为逐文件操作）"
+                snapshot_paths.append(src)
+            if action in ("move", "rename", "copy") and (args or {}).get("dest"):
+                dest = Path(str(args["dest"])).expanduser()
+                if not dest.is_absolute():
+                    dest = Path(workdir or ".") / dest
+                snapshot_paths.append(dest)
+            # Keep first-touch order while avoiding duplicate writes.
+            snapshot_paths = list(dict.fromkeys(snapshot_paths))
+            try:
+                from . import checkpoints
+                for path in snapshot_paths:
+                    saved = checkpoints.capture_file(checkpoint_run_id, workdir, path)
+                    if not saved.get("ok"):
+                        return "（检查点拒绝：无法安全保存 %s 的原始版本（%s），未执行文件操作）" % (
+                            path.name, saved.get("reason") or "unknown")
+            except Exception:
+                return "（检查点拒绝：文件原始版本保存失败，未执行文件操作）"
+        if name == "run_command":
+            result = fn(workdir, args or {}, cancel_event=cancel_event,
+                        deadline=deadline, sandbox=sandbox)
+        else:
+            result = fn(workdir, args or {})
+        if snapshot_paths:
+            checkpoint_warning = ""
+            try:
+                from . import checkpoints
+                for path in snapshot_paths:
+                    if not checkpoints.mark_file_after(checkpoint_run_id, workdir, path):
+                        checkpoint_warning = "（检查点警告：操作后状态未能记账，此文件可能无法自动恢复）"
+            except Exception:
+                checkpoint_warning = "（检查点警告：操作后状态未能记账，此文件可能无法自动恢复）"
+            if checkpoint_warning:
+                result += "\n" + checkpoint_warning
+        return result
+    except Exception as e:
+        return "工具执行失败: %s" % (e)
+
+
+# ---------------------------------------------------------------- 协议适配
+
+def _split_tool_args(t):
+    """args 键以 ? 开头 = 可选参数（模型侧名字去掉 ?，不进 required）。"""
+    props, required = {}, []
+    for k, v in t["args"].items():
+        opt = k.startswith("?")
+        props[k[1:] if opt else k] = {"type": "string", "description": v}
+        if not opt:
+            required.append(k)
+    return props, required
+
+
+def _mcp_specs(sandbox=None, workdir=None):
+    """MCP 工具清单（带缓存）；取不到/未配置返回空表——增强不挡主流程。"""
+    try:
+        from . import mcp_client
+        return mcp_client.tool_specs_cached(sandbox=sandbox, workdir=workdir)
+    except Exception:
+        return []
+
+
+def _openai_tools(extra_specs=None, disabled_tools=None, sandbox=None, workdir=None):
+    disabled = set(disabled_tools or [])
+    out = []
+    for t in list(TOOLS_SPEC) + list(extra_specs or []):
+        if t["name"] in disabled:
+            continue
+        props, required = _split_tool_args(t)
+        out.append({"type": "function", "function": {
+            "name": t["name"], "description": t["description"],
+            "parameters": {"type": "object", "properties": props,
+                           "required": required}}})
+    for m in _mcp_specs(sandbox=sandbox, workdir=workdir):
+        if m["full_name"] in disabled:
+            continue
+        # MCP 工具自带 JSON Schema（透传，不套字符串化的 _split_tool_args）
+        out.append({"type": "function", "function": {
+            "name": m["full_name"],
+            "description": (m["description"] + "（MCP 工具，来自服务器 %s）" % m["server"]).strip(),
+            "parameters": m["input_schema"]}})
+    return out
+
+
+def _anthropic_tools(extra_specs=None, disabled_tools=None, sandbox=None, workdir=None):
+    disabled = set(disabled_tools or [])
+    out = []
+    for t in list(TOOLS_SPEC) + list(extra_specs or []):
+        if t["name"] in disabled:
+            continue
+        props, required = _split_tool_args(t)
+        out.append({"name": t["name"], "description": t["description"],
+                    "input_schema": {"type": "object", "properties": props,
+                                     "required": required}})
+    for m in _mcp_specs(sandbox=sandbox, workdir=workdir):
+        if m["full_name"] in disabled:
+            continue
+        out.append({"name": m["full_name"],
+                    "description": (m["description"] + "（MCP 工具，来自服务器 %s）" % m["server"]).strip(),
+                    "input_schema": m["input_schema"]})
+    return out
+
+
+def _post_json(url, headers, body, allow_private, timeout):
+    """传输层单点（测试在这里打桩）。"""
+    return modelhub._post_json_http(url, headers, body, allow_private, timeout=timeout)
+
+
+def _call_with_optional_deadline(fn, args, kwargs, deadline):
+    """Keep older test/integration transport shims source-compatible."""
+    if deadline is None:
+        return fn(*args, **kwargs)
+    try:
+        return fn(*args, **kwargs, deadline=deadline)
+    except TypeError as exc:
+        if "unexpected keyword argument 'deadline'" not in str(exc):
+            raise
+        return fn(*args, **kwargs)
+
+
+def _post_interruptible(url, headers, body, allow_private, timeout, cancel_event,
+                        deadline=None):
+    """可打断的模型调用：cancel_event 置位即刻放弃等待返回。
+
+    单次生成最长可跑满 timeout，取消不能陪跑到自然结束——HTTP 交给守护
+    线程自行收尾（响应被丢弃，socket 随线程结束释放），主流程立即返回。
+    服务端仍会把这次生成跑完（token 已花），但任务本身即刻终止。"""
+    box = {}
+
+    def _go():
+        try:
+            box["r"] = _post_json(url, headers, body, allow_private, timeout)
+        except Exception as e:
+            box["r"] = (0, None, repr(e))
+
+    th = threading.Thread(target=_go, daemon=True)
+    th.start()
+    wait_until = deadline if deadline is not None else time.monotonic() + timeout + 10
+    while th.is_alive():
+        if cancel_event is not None and cancel_event.is_set():
+            break
+        if time.monotonic() >= wait_until:
+            return 0, None, ("任务总时限已到" if deadline is not None else "响应超时")
+        th.join(0.5)
+    if cancel_event is not None and cancel_event.is_set():
+        return 0, None, "已取消"
+    return box.get("r") or (0, None, "无响应")
+
+
+# ---------------------------------------------------------------- 思考过程（流式）
+# 用户诉求（2026-09-22）：「把思考过程打印出来」——直连对话此前整轮只有三点
+# 打字动画，模型的思维链（DeepSeek/vLLM 系 reasoning_content、Anthropic
+# thinking 块）被 _sse_parse 明确丢弃。这里自带一份「认思考」的增量解析：
+# 边收边把思考与正文分别攒起来，交给调用方实时落盘 + 结束后存进步骤记录。
+
+def _reason_from_delta(proto, obj):
+    """从一条流式事件里取「思考增量」。三协议字段各异，取不到返回空串。
+
+    openai 兼容面最杂：reasoning_content（DeepSeek/vLLM/云知声实测）、
+    reasoning（部分网关）、reasoning_details[].text（OpenRouter 系）。
+    anthropic 是 thinking_delta（另有 redacted_thinking 不文本化，跳过）。"""
+    if proto == "openai":
+        total = ""
+        for ch in obj.get("choices") or []:
+            d = ch.get("delta") or {}
+            for k in ("reasoning_content", "reasoning"):
+                v = d.get(k)
+                if isinstance(v, str):
+                    total += v
+            for det in (d.get("reasoning_details") or []):
+                if isinstance(det, dict) and isinstance(det.get("text"), str):
+                    total += det["text"]
+        return total
+    if proto == "anthropic" and obj.get("type") == "content_block_delta":
+        d = obj.get("delta") or {}
+        if d.get("type") == "thinking_delta":
+            return d.get("thinking") or ""
+        return ""
+    if proto == "google":
+        total = ""
+        for cand in obj.get("candidates") or []:
+            for p in ((cand.get("content") or {}).get("parts") or []):
+                if isinstance(p, dict) and p.get("thought"):
+                    total += p.get("text") or ""
+        return total
+    return ""
+
+
+def _reason_from_message(proto, data):
+    """非流式响应里的思考字段（网关不支持流式时的兜底）。"""
+    if not isinstance(data, dict):
+        return ""
+    if proto == "anthropic":
+        return "\n".join(b.get("thinking", "") for b in (data.get("content") or [])
+                         if isinstance(b, dict) and b.get("type") == "thinking")
+    if proto == "google":
+        total = ""
+        for cand in data.get("candidates") or []:
+            for p in ((cand.get("content") or {}).get("parts") or []):
+                if isinstance(p, dict) and p.get("thought"):
+                    total += p.get("text") or ""
+        return total
+    msg = ((data.get("choices") or [{}])[0].get("message") or {})
+    total = ""
+    for k in ("reasoning_content", "reasoning"):
+        v = msg.get(k)
+        if isinstance(v, str):
+            total += v
+    for det in (msg.get("reasoning_details") or []):
+        if isinstance(det, dict) and isinstance(det.get("text"), str):
+            total += det["text"]
+    return total
+
+
+def _stream_accumulate(proto, obj, acc):
+    """把一条 SSE 事件并入累加器（就地改写 acc）。返回是否有「有意义的进展」。
+
+    acc = {text, reasoning, tools, usage}；工具参数按 index 归并——openai 的
+    function.arguments 与 anthropic 的 input_json_delta 都是分片到达的。"""
+    progress = False
+    if proto == "anthropic":
+        t = obj.get("type")
+        if t == "content_block_start":
+            blk = obj.get("content_block") or {}
+            if blk.get("type") == "tool_use":
+                idx = int(obj.get("index") or 0)
+                acc["tools"][idx] = {"id": blk.get("id") or "",
+                                     "name": blk.get("name") or "", "raw": ""}
+                progress = True
+        elif t == "content_block_delta":
+            d = obj.get("delta") or {}
+            if d.get("type") == "text_delta" and d.get("text"):
+                acc["text"] += d["text"]
+                progress = True
+            elif d.get("type") == "input_json_delta":
+                idx = int(obj.get("index") or 0)
+                slot = acc["tools"].setdefault(idx, {"id": "", "name": "", "raw": ""})
+                slot["raw"] += d.get("partial_json") or ""
+                progress = True
+        elif t == "message_start":
+            u = (obj.get("message") or {}).get("usage") or obj.get("usage") or {}
+            acc["usage"].update({"input": int(u.get("input_tokens") or 0),
+                                 "output": int(u.get("output_tokens") or 0),
+                                 "cached": (int(u.get("cache_read_input_tokens") or 0)
+                                            + int(u.get("cache_creation_input_tokens") or 0))})
+        elif t == "message_delta":
+            u = obj.get("usage") or {}
+            if u.get("output_tokens"):
+                acc["usage"]["output"] = int(u["output_tokens"])
+    elif proto == "google":
+        for cand in obj.get("candidates") or []:
+            for p in ((cand.get("content") or {}).get("parts") or []):
+                if not isinstance(p, dict):
+                    continue
+                if p.get("thought"):
+                    acc["reasoning"] += p.get("text") or ""
+                    progress = True
+                elif p.get("functionCall"):
+                    fc = p["functionCall"]
+                    acc["tools"][len(acc["tools"])] = {
+                        "id": "call_%d" % (len(acc["tools"]) + 1),
+                        "name": fc.get("name") or "",
+                        "raw": json.dumps(fc.get("args") or {}, ensure_ascii=False)}
+                    progress = True
+                elif p.get("text"):
+                    acc["text"] += p["text"]
+                    progress = True
+        u = obj.get("usageMetadata")
+        if isinstance(u, dict):
+            acc["usage"].update({"input": int(u.get("promptTokenCount") or 0),
+                                 "output": int(u.get("candidatesTokenCount") or 0),
+                                 "total": int(u.get("totalTokenCount") or 0)})
+    else:
+        for ch in obj.get("choices") or []:
+            d = ch.get("delta") or {}
+            if isinstance(d.get("content"), str) and d["content"]:
+                acc["text"] += d["content"]
+                progress = True
+            for i, tc in enumerate(d.get("tool_calls") or []):
+                if not isinstance(tc, dict):
+                    continue
+                idx = int(tc.get("index") if tc.get("index") is not None else i)
+                slot = acc["tools"].setdefault(idx, {"id": "", "name": "", "raw": ""})
+                if tc.get("id"):
+                    slot["id"] = tc["id"]
+                fn = tc.get("function") or {}
+                if fn.get("name"):
+                    slot["name"] = fn["name"]
+                if fn.get("arguments"):
+                    slot["raw"] += fn["arguments"]
+                progress = True
+        u = obj.get("usage")
+        if isinstance(u, dict):
+            acc["usage"].update({"input": int(u.get("prompt_tokens") or 0),
+                                 "output": int(u.get("completion_tokens") or 0),
+                                 "total": int(u.get("total_tokens") or 0),
+                                 "cached": int(((u.get("prompt_tokens_details") or {})
+                                                .get("cached_tokens")) or 0)})
+    return progress
+
+
+def _calls_from_acc(acc):
+    """累加器里的工具分片 → [{id, name, args}]（参数 JSON 解析失败给空对象）。"""
+    out = []
+    for idx in sorted(acc["tools"].keys()):
+        slot = acc["tools"][idx]
+        name = slot.get("name") or ""
+        if not name:
+            continue
+        try:
+            args = json.loads(slot.get("raw") or "{}")
+        except Exception:
+            args = {}
+        if not isinstance(args, dict):
+            args = {}
+        out.append({"id": slot.get("id") or ("call_%d" % (idx + 1)),
+                    "name": name, "args": args})
+    return out
+
+
+def _post_sse_stream(url, headers, body, allow_private, timeout, proto,
+                     on_reason=None, on_text=None, on_tick=None, cancel_event=None,
+                     deadline=None):
+    """流式（SSE）模型调用 → dict(status/text/reasoning/calls/usage/error/events)。
+
+    与 _post_interruptible 同款的可打断语义：读取放守护线程，cancel_event 置位
+    即刻放弃等待（socket 随线程结束释放）。三个回调：on_reason 每收到一段思考
+    增量（调用方据此实时打印「思考过程」），on_text 收到**累计**正文（只在真的
+    变长时触发，运行中直接当正文预览），on_tick 是无文本进展时的心跳。
+    events=0 表示网关根本没按流回（多半忽略了 stream 字段）——调用方据此回落
+    非流式；events>0 而正文为空则是模型真没说话，不该重发（白烧一次生成）。
+
+    首字延迟与吞吐（§07 体验面）：`first_token_ms` = 发出请求到第一个**带内容**
+    的增量（思考 / 正文 / 工具参数）之间的毫秒数；`tokens_per_sec` 用 output
+    token 除以「首个到末个内容增量」的窗口，窗口过短或拿不到 output 时记 0
+    （0 = 不可测，不是"一秒 0 个 token"）。两者只有走流式才有值，非流式回落
+    路径与 CLI 子进程路径都给 0。"""
+    acc = {"text": "", "reasoning": "", "tools": {}, "usage": {}}
+    box = {"status": 0, "err": "", "events": 0, "sent_text": None,
+           "first_ms": None, "last_ms": None}
+    lock = threading.Lock()
+
+    def _emit(cb, payload):
+        if cb is None:
+            return
+        try:
+            cb(payload)
+        except Exception:
+            pass
+ 
+    def _go():
+        try:
+            parsed = urllib.parse.urlsplit(url)
+            if parsed.scheme not in ("http", "https"):
+                box["err"] = "协议必须是 http/https"
+                return
+            host, herr = modelhub._validate_host(url, allow_private)
+            if host is None:
+                box["err"] = herr
+                return
+            t_send = time.monotonic()      # 首字延迟基线：请求发出，不含 DNS/连接前准备
+            req = urllib.request.Request(
+                url, method="POST",
+                headers=dict(headers, **{"Content-Type": "application/json",
+                                         "Accept": "text/event-stream"}),
+                data=json.dumps(body).encode("utf-8"))
+            with modelhub._opener().open(req, timeout=timeout) as resp:
+                box["status"] = resp.status
+                if not 200 <= resp.status < 300:
+                    raw = resp.read(65536).decode("utf-8", "replace")
+                    box["err"] = "HTTP %s %s" % (resp.status, raw[:200])
+                    return
+                for raw in resp:
+                    line = raw.decode("utf-8", "replace").strip()
+                    if not line.startswith("data:"):
+                        continue
+                    payload = line[5:].strip()
+                    if not payload or payload == "[DONE]":
+                        continue
+                    try:
+                        obj = json.loads(payload)
+                    except Exception:
+                        continue          # 半行/坏行静默跳过，不中断整流
+                    if not isinstance(obj, dict):
+                        continue
+                    box["events"] += 1
+                    reason = _reason_from_delta(proto, obj)
+                    with lock:
+                        if reason:
+                            acc["reasoning"] += reason
+                        moved = _stream_accumulate(proto, obj, acc)
+                        text_now = acc["text"]
+                    if reason or moved:
+                        now_ms = (time.monotonic() - t_send) * 1000.0
+                        if box["first_ms"] is None:
+                            box["first_ms"] = now_ms
+                        box["last_ms"] = now_ms
+                    if reason:
+                        _emit(on_reason, reason)
+                    if text_now != box["sent_text"]:
+                        box["sent_text"] = text_now
+                        _emit(on_text, text_now)     # 累计正文（运行中实时打印）
+                    elif moved and not reason:
+                        _emit(on_tick, None)         # 只有工具/用量在推进的心跳
+                    if sum(len(x) for x in (acc["text"], acc["reasoning"])) > 4 * 1024 * 1024:
+                        break             # 防失控
+        except Exception as e:
+            box["err"] = box["err"] or tlsctx.humanize(repr(e)[:300])
+
+    th = threading.Thread(target=_go, daemon=True)
+    th.start()
+    wait_until = deadline if deadline is not None else time.monotonic() + timeout + 10
+    while th.is_alive():
+        if cancel_event is not None and cancel_event.is_set():
+            break
+        if time.monotonic() >= wait_until:
+            break
+        th.join(0.5)
+    with lock:
+        out = {"status": box["status"], "text": acc["text"],
+               "reasoning": acc["reasoning"], "usage": dict(acc["usage"]),
+               "calls": _calls_from_acc(acc), "events": box["events"],
+               "first_token_ms": round(box["first_ms"], 1) if box["first_ms"] is not None else 0.0,
+               "tokens_per_sec": 0.0, "error": box["err"]}
+        gen_s = 0.0
+        if box["first_ms"] is not None and box["last_ms"] is not None:
+            gen_s = (box["last_ms"] - box["first_ms"]) / 1000.0
+        out_tok = int(acc["usage"].get("output") or 0)
+        if gen_s > 0.2 and out_tok > 0:
+            out["tokens_per_sec"] = round(out_tok / gen_s, 2)
+    if cancel_event is not None and cancel_event.is_set():
+        out["error"], out["status"] = "已取消", 0
+        return out
+    if th.is_alive():
+        out["error"], out["status"] = ("任务总时限已到" if deadline is not None
+                                         else "响应超时"), 0
+        out["deadline_exceeded"] = deadline is not None
+    return out
+
+
+def _m_openai(m):
+    """内部消息 → openai 消息。tool_results: [(call_id, 结果文本)]。"""
+    if m["role"] == "assistant":
+        out = {"role": "assistant", "content": m.get("content") or ""}
+        if m.get("tool_calls"):
+            out["tool_calls"] = [{"id": tc["id"], "type": "function",
+                                  "function": {"name": tc["name"],
+                                               "arguments": json.dumps(tc["args"], ensure_ascii=False)}}
+                                 for tc in m["tool_calls"]]
+        return out
+    if m["role"] == "tool_results":
+        return [{"role": "tool", "tool_call_id": cid, "content": text}
+                for cid, text in m["tool_results"]]
+    imgs = m.get("images") or []
+    if imgs:   # 多模态：content 变数组，图跟在文本后（role=tool 只收文本，故图只走 user）
+        content = [{"type": "text", "text": m.get("content") or ""}]
+        content += [{"type": "image_url",
+                     "image_url": {"url": "data:%s;base64,%s" % (mime, b64)}}
+                    for mime, b64 in imgs]
+        return {"role": "user", "content": content}
+    return {"role": "user", "content": m.get("content") or ""}
+
+
+def _m_anthropic(m):
+    if m["role"] == "assistant":
+        blocks = []
+        if m.get("content"):
+            blocks.append({"type": "text", "text": m["content"]})
+        for tc in (m.get("tool_calls") or []):
+            blocks.append({"type": "tool_use", "id": tc["id"], "name": tc["name"],
+                           "input": tc["args"]})
+        return {"role": "assistant", "content": blocks or [{"type": "text", "text": ""}]}
+    if m["role"] == "tool_results":
+        return {"role": "user", "content": [
+            {"type": "tool_result", "tool_use_id": cid, "content": text}
+            for cid, text in m["tool_results"]]}
+    imgs = m.get("images") or []
+    if imgs:
+        blocks = [{"type": "text", "text": m.get("content") or ""}]
+        blocks += [{"type": "image",
+                    "source": {"type": "base64", "media_type": mime, "data": b64}}
+                   for mime, b64 in imgs]
+        return {"role": "user", "content": blocks}
+    return {"role": "user", "content": [{"type": "text", "text": m.get("content") or ""}]}
+
+
+def _compact_old_tool_results(messages, keep_rounds=TOOL_HISTORY_KEEP_ROUNDS,
+                              old_result_chars=TOOL_HISTORY_OLD_RESULT_CHARS,
+                              run_id=""):
+    """Bound old tool output while preserving recent call/result pairs."""
+    result_indexes = [i for i, msg in enumerate(messages)
+                      if msg.get("role") == "tool_results"]
+    keep_rounds = max(0, int(keep_rounds))
+    compact_indexes = result_indexes[:max(0, len(result_indexes) - keep_rounds)]
+    for idx in compact_indexes:
+        msg = messages[idx]
+        compacted = []
+        for call_id, value in msg.get("tool_results") or []:
+            value = str(value or "")
+            if len(value) > old_result_chars:
+                existing_ref = _existing_tool_output_ref(value, run_id, call_id)
+                if existing_ref:
+                    # Idempotent across repeated context passes: never save the
+                    # already-truncated marker as a new "full" tool output.
+                    compacted.append((call_id, value))
+                    continue
+                head = old_result_chars * 2 // 3
+                tail = old_result_chars - head
+                try:
+                    from . import tool_outputs
+                    ref = tool_outputs.save(run_id, call_id, value) if run_id else ""
+                except Exception:
+                    ref = ""
+                if ref:
+                    marker = ("\n…[较早结果已卸载到本机；需查看全文请调用 read_tool_output，"
+                              "ref=%s ]…\n" % ref)
+                else:
+                    marker = "\n…[较早工具结果已压缩；需要时请重新读取对应文件/调用工具]…\n"
+                value = value[:head] + marker + value[-tail:]
+            compacted.append((call_id, value))
+        msg["tool_results"] = compacted
+
+
+def _existing_tool_output_ref(value, run_id, call_id):
+    """Return a ref only when a marker previews this call's stored full output.
+
+    Tool output is untrusted. A bare ``ref=<hex>`` substring is not evidence of a
+    CodeBee marker: require the complete framing and verify the opaque reference
+    against this call's stored full output before treating it as already unloaded.
+    """
+    match = _TOOL_OUTPUT_MARKER_RE.search(str(value or ""))
+    if not match or not str(run_id or "").strip():
+        return ""
+    try:
+        from . import tool_outputs
+        is_match = tool_outputs.matches_compacted_output(
+            run_id, call_id, match.group(1), value[:match.start()], value[match.end():])
+        return match.group(1) if is_match else ""
+    except Exception:
+        return ""
+
+
+def _direct_context_chars(messages):
+    return sum(len(json.dumps(msg, ensure_ascii=False, default=str)) for msg in messages)
+
+
+def _bound_direct_context(messages, *, max_chars=MAX_DIRECT_CONTEXT_CHARS,
+                          keep_rounds=TOOL_HISTORY_KEEP_ROUNDS, run_id=""):
+    """Fold complete old tool rounds when a direct-agent conversation grows large.
+
+    Unlike pipeline steps, direct chat has no session-log compaction surface. Keep the
+    original request and the newest tool interactions, but cap older outputs and replace
+    discarded call/result pairs with a bounded factual note. Full large outputs remain
+    available through read_tool_output references.
+    """
+    try:
+        max_chars = max(1000, int(max_chars))
+        keep_rounds = max(1, int(keep_rounds))
+    except (TypeError, ValueError):
+        max_chars, keep_rounds = MAX_DIRECT_CONTEXT_CHARS, TOOL_HISTORY_KEEP_ROUNDS
+    rounds = []
+    for index, msg in enumerate(messages[:-1]):
+        if msg.get("role") == "assistant" and msg.get("tool_calls") \
+                and messages[index + 1].get("role") == "tool_results":
+            rounds.append((index, index + 1))
+    if not rounds:
+        return
+    if _direct_context_chars(messages) <= max_chars:
+        return
+
+    # First compact all tool results; recent full output is useful only while the
+    # conversation has room. Oversized output is recoverable by its scoped ref.
+    result_budget = max(160, min(TOOL_HISTORY_OLD_RESULT_CHARS,
+                                 max_chars // max(1, keep_rounds * 8)))
+    _compact_old_tool_results(messages, keep_rounds=0,
+                              old_result_chars=result_budget, run_id=run_id)
+    note_index = 1 if messages and messages[0].get("role") == "user" else 0
+    previous_note = (messages[note_index].get("content") or "") \
+        if note_index < len(messages) \
+        and messages[note_index].get("_direct_compaction_note") else ""
+    folded = ([previous_note.split("\n", 1)[1]]
+              if previous_note.startswith("## 更早的工具轮次摘要\n") else [])
+    while len(rounds) > keep_rounds and _direct_context_chars(messages) > max_chars:
+        start, end = rounds.pop(0)
+        assistant, result_msg = messages[start], messages[end]
+        calls = assistant.get("tool_calls") or []
+        tools = ", ".join(str(call.get("name") or "tool")[:80] for call in calls[:8])
+        detail = str(assistant.get("content") or "").strip().replace("\n", " ")[:240]
+        refs = []
+        for call_id, output in (result_msg.get("tool_results") or [])[:5]:
+            value = str(output or "")
+            existing_ref = _existing_tool_output_ref(value, run_id, call_id)
+            if existing_ref:
+                refs.append(existing_ref)
+            elif run_id:
+                try:
+                    from . import tool_outputs
+                    ref = tool_outputs.save(run_id, call_id, value)
+                    if ref:
+                        refs.append(ref)
+                except Exception:
+                    pass
+        piece = "- 工具 %s；模型说明：%s%s" % (
+            tools or "unknown", detail or "（无）",
+            ("；全文 ref=" + ",".join(refs)) if refs else "")
+        folded.append(piece[:500])
+        del messages[start:end + 1]
+        # Tool payloads are untrusted external data: summarize call intent and refs,
+        # never copy output excerpts outside their prompt-guard fences.
+        note = "## 更早的工具轮次摘要\n" + "\n".join(folded)
+        note_limit = min(8000, max(1400, max_chars // 4))
+        if len(note) > note_limit:
+            note = note[-note_limit:]
+        insert_at = 1 if messages and messages[0].get("role") == "user" else 0
+        if insert_at < len(messages) and messages[insert_at].get("_direct_compaction_note"):
+            messages[insert_at]["content"] = note
+        else:
+            messages.insert(insert_at, {"role": "user", "content": note,
+                                        "_direct_compaction_note": True})
+        # Earlier deletions shift indices; rebuild complete pairs.
+        rounds = [(i, i + 1) for i, msg in enumerate(messages[:-1])
+                  if msg.get("role") == "assistant" and msg.get("tool_calls")
+                  and messages[i + 1].get("role") == "tool_results"]
+
+
+def _build_request(proto, base, use_key, model, system, msgs, with_tools, stream=False,
+                   max_tokens=BASE_MAX_TOKENS, extra_specs=None, disabled_tools=None,
+                   sandbox=None, workdir=None):
+    """按协议构造 (url, headers, body)。msgs 为内部统一形状。
+
+    stream=True 时按协议打开流式：google 换 :streamGenerateContent?alt=sse，
+    openai/anthropic 置 stream 字段（openai 另要 include_usage，否则收尾
+    chunk 不带 usage，这一步的 token 记账会凭空少一截）。"""
+    base = (base or "").rstrip("/")
+    if proto == "google":
+        if base.endswith("/v1beta"):
+            prefix = base + "/models/%s"
+        else:
+            prefix = base + "/v1beta/models/%s"
+        url = (prefix + (":streamGenerateContent?alt=sse" if stream
+                         else ":generateContent")) % model
+        headers = {"x-goog-api-key": use_key}
+        contents = []
+        for m in msgs:
+            if m["role"] not in ("user", "assistant"):
+                continue
+            parts = [{"text": m.get("content") or ""}]
+            parts += [{"inline_data": {"mime_type": mime, "data": b64}}
+                      for mime, b64 in (m.get("images") or [])]
+            contents.append({"role": ("user" if m["role"] == "user" else "model"),
+                             "parts": parts})
+        body = {"contents": contents,
+                "systemInstruction": {"parts": [{"text": system}]},
+                "generationConfig": {"maxOutputTokens": max_tokens}}
+        return url, headers, body
+    path = "/messages" if proto == "anthropic" else "/chat/completions"
+    url = (base + path) if base.endswith("/v1") else (base + "/v1" + path)
+    if proto == "anthropic":
+        headers = {"x-api-key": use_key, "anthropic-version": "2023-06-01"}
+        body = {"model": model, "max_tokens": max_tokens, "system": system,
+                "messages": [_m_anthropic(m) for m in msgs]}
+        if with_tools:
+            body["tools"] = _anthropic_tools(extra_specs, disabled_tools,
+                                              sandbox=sandbox, workdir=workdir)
+        if stream:
+            body["stream"] = True
+        return url, headers, body
+    headers = {"Authorization": "Bearer " + use_key}
+    # tool_results 消息展开成多条 role=tool（_m_openai 对它返回列表，不能嵌套）
+    msgs_wire = []
+    for m in msgs:
+        w = _m_openai(m)
+        if isinstance(w, list):
+            msgs_wire.extend(w)
+        else:
+            msgs_wire.append(w)
+    body = {"model": model, "max_tokens": max_tokens,
+            "messages": [{"role": "system", "content": system}] + msgs_wire}
+    if with_tools:
+        body["tools"] = _openai_tools(extra_specs, disabled_tools,
+                                      sandbox=sandbox, workdir=workdir)
+    if stream:
+        body["stream"] = True
+        body["stream_options"] = {"include_usage": True}
+    return url, headers, body
+
+
+def _parse_reply(proto, data):
+    """从响应解析 → (文本, [tool_call], usage)。
+    tool_call = {id, name, args}；usage = {input, output, cached, total}。"""
+    usage = {"input": 0, "output": 0, "cached": 0, "total": 0}
+    if proto == "google":
+        cand = (data.get("candidates") or [{}])[0]
+        parts = (cand.get("content") or {}).get("parts") or []
+        text = "\n".join(p.get("text", "") for p in parts if isinstance(p, dict))
+        um = data.get("usageMetadata") or {}
+        usage["input"] = int(um.get("promptTokenCount") or 0)
+        usage["output"] = int(um.get("candidatesTokenCount") or 0)
+        usage["total"] = int(um.get("totalTokenCount") or 0)
+        return text.strip(), [], usage
+    if proto == "anthropic":
+        blocks = data.get("content") or []
+        text = "\n".join(b.get("text", "") for b in blocks
+                         if isinstance(b, dict) and b.get("type") == "text")
+        calls = [{"id": b.get("id") or "", "name": b.get("name") or "",
+                  "args": b.get("input") or {}}
+                 for b in blocks if isinstance(b, dict) and b.get("type") == "tool_use"]
+        u = data.get("usage") or {}
+        usage["input"] = int(u.get("input_tokens") or 0)
+        usage["output"] = int(u.get("output_tokens") or 0)
+        usage["cached"] = (int(u.get("cache_read_input_tokens") or 0)
+                           + int(u.get("cache_creation_input_tokens") or 0))
+        usage["total"] = usage["input"] + usage["output"] + usage["cached"]
+        return text.strip(), calls, usage
+    choice = (data.get("choices") or [{}])[0]
+    msg = choice.get("message") or {}
+    calls = []
+    for tc in (msg.get("tool_calls") or []):
+        fn = tc.get("function") or {}
+        try:
+            args = json.loads(fn.get("arguments") or "{}")
+        except Exception:
+            args = {}
+        if not isinstance(args, dict):
+            args = {}
+        calls.append({"id": tc.get("id") or ("call_%d" % (len(calls) + 1)),
+                      "name": fn.get("name") or "", "args": args})
+    u = data.get("usage") or {}
+    usage["input"] = int(u.get("prompt_tokens") or 0)
+    usage["output"] = int(u.get("completion_tokens") or 0)
+    usage["total"] = int(u.get("total_tokens") or 0) or (usage["input"] + usage["output"])
+    return (msg.get("content") or "").strip(), calls, usage
+
+
+# ---------------------------------------------------------------- 主循环
+
+def _norm_usage(usage):
+    """三协议 usage → {input, output, cached, total}（缺 total 用三项相加补齐）。"""
+    out = {"input": 0, "output": 0, "cached": 0, "total": 0}
+    for k in out:
+        try:
+            out[k] = int((usage or {}).get(k) or 0)
+        except Exception:
+            out[k] = 0
+    if not out["total"]:
+        out["total"] = out["input"] + out["output"] + out["cached"]
+    return out
+
+
+def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=None,
+        on_reason=None, on_stream=None, on_activity=None, stream=True, deadline=None,
+        task_creator=None, sandbox=None, checkpoint_run_id=""):
+    """跑一次内置智能体（内部自带工具循环直到给出最终回答）。
+
+    bi: resolve() 的返回；prompt: 本轮完整输入（目标/续轮块由 pipeline 拼）；
+    images: 用户随本轮消息提供的图片绝对路径列表（任务附件/对话追话）；
+    log: 追加一行日志的回调（步骤日志）。返回 runner 风格统一结果：
+    {ok, text, usage, error, model, provider_name, provider_id, iterations,
+     cost_usd, reasoning}。
+
+    思考过程可视化（2026-09-22 用户诉求「把思考过程打印出来」）：stream=True 走
+    SSE，模型的思维链（reasoning_content / thinking 块）边收边经 on_reason 回调，
+    正文增量经 on_stream（累计值），工具活动经 on_activity——调用方据此在对话
+    时间线上实时打印，不再让用户干看三点打字动画。网关忽略 stream（零事件）时
+    自动回落非流式，思考字段仍从响应体兜底抽取（on_reason 补发一次）。"""
+    prov = bi["prov"]
+    model = bi["model"]
+    from . import policy
+    sandbox = policy.normalize_sandbox(sandbox, workdir)
+    disabled_tools = sandbox.get("disabled_tools") or []
+    allow_private = bool(prov.get("allow_private"))
+    system = _SYSTEM_PROMPT + "\n\n## 工作目录\n%s" % os.path.abspath(workdir or ".")
+    imgs = _prep_images(images, log) if images else []
+    if imgs and not modelhub._model_image_in(prov, model):
+        # 能力闸门：模型未声明图片输入就不塞图（网关多半会拒），改为显式告知
+        if log:
+            log("[图片] 模型 %s 未开启图片输入，%d 张图不随消息发送" % (model, len(imgs)))
+        prompt = ("（用户提供了 %d 张图片，但当前模型未开启图片输入；请在回答开头提示用户"
+                  "到绑定页为该模型开启「图」开关，或改绑多模态模型。本条回答请基于"
+                  "文字部分完成。）\n\n%s" % (len(imgs), prompt))
+        imgs = []
+    msgs = [{"role": "user", "content": prompt, "images": imgs}]
+    candidates = list(modelhub._protocol_candidates(prov))
+    tools_ok = all(proto != "google" for proto, _ in candidates)   # google wire 无工具协议
+    total_usage = {"input": 0, "cached": 0, "output": 0, "total": 0}
+    tool_output_run_id = checkpoint_run_id or secrets.token_hex(16)
+    text = ""
+    iters = 0
+    last_err = ""
+    ok = False
+    reasons = []            # 各迭代的思考正文（按迭代顺序拼接，供步骤记录展示）
+    max_tokens = BASE_MAX_TOKENS   # 思考占满预算时提额重试（跨迭代保持，见空正文分支）
+    escalated = False       # 本轮 run 是否已提额（只提一次，防无限翻倍）
+    empty_streak = 0        # 连续零正文轮数（拿到正文/工具即清零）
+    last_action_was_tools = False
+    repeat_tool_signature = ""
+    repeat_tool_streak = 0
+    repeat_stop = False
+    finalize_attempted = False
+    perf = {"ttft": [], "tps": []}   # 各次流式调用的首字延迟(ms)与吞吐(tok/s)
+
+    def _perf():
+        """本次 run 的体验指标：跨迭代取均值；无流式样本时返回空 dict。"""
+        if not perf["ttft"] and not perf["tps"]:
+            return {}
+        return {"first_token_ms": (round(sum(perf["ttft"]) / len(perf["ttft"]), 1)
+                                   if perf["ttft"] else 0.0),
+                "tokens_per_sec": (round(sum(perf["tps"]) / len(perf["tps"]), 2)
+                                   if perf["tps"] else 0.0)}
+
+    def _deadline_fail():
+        return {"ok": False, "text": "", "usage": dict(total_usage),
+                "error": "任务总时限已到", "model": model,
+                "provider_name": bi["provider_name"],
+                "provider_id": bi["provider_id"], "iterations": iters,
+                "cost_usd": 0.0, "reasoning": "\n\n".join(r for r in reasons if r)[:THINK_MAX_CHARS],
+                "raw": {"timed_out": True, "deadline_exceeded": True}}
+
+    def _fire(cb, *cb_args):
+        if cb is None:
+            return
+        try:
+            cb(*cb_args)
+        except Exception:
+            pass        # 可视化是增强：回调炸了不能拖垮生成
+
+    def _take_reason(reason):
+        """收一段思考：攒进本轮正文并实时回调（限长，防超长思维链撑爆 run.json）。"""
+        if not reason:
+            return
+        if not reasons:
+            reasons.append("")
+        if len(reasons[-1]) < THINK_MAX_CHARS:
+            reasons[-1] += reason
+        _fire(on_reason, reason)
+
+    def _fail(err):
+        return {"ok": False, "text": "", "usage": dict(total_usage), "error": err,
+                "model": model, "provider_name": bi["provider_name"],
+                "provider_id": bi["provider_id"], "iterations": iters, "cost_usd": 0.0,
+                "raw": _perf(),
+                "reasoning": "\n\n".join(r for r in reasons if r)[:THINK_MAX_CHARS]}
+
+    def _cancel_fail():
+        """取消终态带结构化标记：下游惩罚账（KEY 冷却/供应商健康/评测作废）靠标记
+        认出取消，不靠「已取消」字样匹配。"""
+        out = _fail("已取消")
+        out["cancelled"] = True
+        return out
+
+    # 工具上限后最多再给一次“只输出总结”的机会。这样最后一轮已经
+    # 成功写文件/抓数据但尚未总结时，不会把真实成果误报成失败。
+    for it in range(1, MAX_TOOL_ITERS + 2):
+        force_finalize = it > MAX_TOOL_ITERS or repeat_stop
+        if force_finalize and (finalize_attempted or not last_action_was_tools):
+            break
+        if force_finalize and not finalize_attempted:
+            finalize_attempted = True
+            msgs.append({"role": "user", "content":
+                         "请停止调用工具，只根据已经完成的操作直接给出最终答复。"
+                         "列出已完成内容、产出文件和仍未完成的事项；不要继续探索。"})
+            if log:
+                log("[收尾] 工具循环已到边界，发起一次无工具最终总结")
+            _fire(on_activity, "工具循环到边界，正在生成最终总结")
+        if deadline is not None and time.monotonic() >= deadline:
+            return _deadline_fail()
+        if cancel_event is not None and cancel_event.is_set():
+            return _cancel_fail()
+        reasons.append("")   # 每轮迭代各占一段思考（跨轮拼接时分段，join 时滤空段）
+        done = False
+        reBump = False         # 本轮要提额重试（同一迭代重跑，不烧迭代数）
+        stopit = False         # 本轮判死（连续零正文），直接终局不再空转
+        for _bump in range(2):                      # 第 2 圈 = 提额后的同轮重试
+            for proto, pbase in candidates:
+                keys = modelhub._chain_keys(prov) or [{"key": prov.get("api_key") or "", "id": ""}]
+                for kk in keys:
+                    got = False        # 本 KEY 拿到了响应（区别于 HTTP 失败换下家）
+                    stripped = False   # thinking 对象被网关 400 拒后已摘除重发
+                    while True:
+                        if deadline is not None and time.monotonic() >= deadline:
+                            return _deadline_fail()
+                        req_timeout = min(float(timeout), max(0.1, deadline - time.monotonic())) \
+                            if deadline is not None else timeout
+                        allow_tools = tools_ok and not force_finalize
+                        url, headers, body = _build_request(
+                            proto, pbase, kk["key"], model, system, msgs,
+                            allow_tools, max_tokens=max_tokens,
+                            extra_specs=[CREATE_TASK_SPEC] if task_creator else None,
+                            disabled_tools=disabled_tools, sandbox=sandbox,
+                            workdir=workdir)
+                        sbody = None
+                        if stream:
+                            # 流式体单独构造（+stream / include_usage）；非流式体留给回落重发
+                            _, _, sbody = _build_request(
+                                proto, pbase, kk["key"], model, system, msgs,
+                                allow_tools, stream=True, max_tokens=max_tokens,
+                                extra_specs=[CREATE_TASK_SPEC] if task_creator else None,
+                                disabled_tools=disabled_tools, sandbox=sandbox,
+                                workdir=workdir)
+                        effort = str(bi.get("reasoning_effort") or "").strip().lower()
+                        # reasoning_effort 是 OpenAI wire 字段；Anthropic thinking 使用
+                        # 另一套对象结构，向兼容网关硬塞该字段会直接得到 400。
+                        if effort in ("low", "medium", "high") and proto == "openai":
+                            body["reasoning_effort"] = effort
+                            if sbody is not None:
+                                sbody["reasoning_effort"] = effort
+                        if effort in ("low", "medium") and proto == "anthropic" \
+                                and not stripped:
+                            # 「思考程度」此前只对 openai 面生效；GLM 这类推理模型
+                            # 在 Anthropic 兼容面上默认全功率思考，能把 max_tokens
+                            # 整个烧光（2026-09-22 glm-5.3-flash 47 分钟零正文案）。
+                            # low/medium 显式给思考预算，high 留默认（模型自决=放开想）。
+                            body["thinking"] = {
+                                "type": "enabled",
+                                "budget_tokens": 1024 if effort == "low" else 4096}
+                            if sbody is not None:
+                                sbody["thinking"] = dict(body["thinking"])
+                        text, calls, usage = "", [], {}
+                        streamed = False
+                        if sbody is not None:
+                            part = _call_with_optional_deadline(
+                                _post_sse_stream,
+                                (url, headers, sbody, allow_private, req_timeout, proto),
+                                {"on_reason": _take_reason, "on_text": on_stream,
+                                 "cancel_event": cancel_event}, deadline)
+                            if part.get("deadline_exceeded"):
+                                return _deadline_fail()
+                            if part["error"] == "已取消":
+                                return _cancel_fail()
+                            if not part["error"] and part["events"]:
+                                # 网关确实按流回了：正文/工具取增量累加结果
+                                text, calls = part["text"], part["calls"]
+                                usage = part["usage"]
+                                streamed = True
+                                if part.get("first_token_ms"):
+                                    perf["ttft"].append(float(part["first_token_ms"]))
+                                if part.get("tokens_per_sec"):
+                                    perf["tps"].append(float(part["tokens_per_sec"]))
+                                if not reasons or not reasons[-1]:
+                                    # 调用方没挂实时回调（无可视化诉求）时思考只在
+                                    # 累加器里：这里兜底收进结果，落库口径一致
+                                    _take_reason(part["reasoning"])
+                            else:
+                                # 零事件（网关忽略 stream）或流式这一步失败（不认 stream 参数、
+                                # 断流等）：都退回同一条 wire 的非流式重发——比直接判死这家
+                                # 供应商稳妥；非流式也失败才走下面的记账/换链。
+                                last_err = part["error"]
+                        if not streamed:
+                            status, data, err = _call_with_optional_deadline(
+                                _post_interruptible,
+                                (url, headers, body, allow_private, req_timeout, cancel_event),
+                                {}, deadline)
+                            if err == "任务总时限已到":
+                                return _deadline_fail()
+                            if cancel_event is not None and cancel_event.is_set():
+                                # 取消先于一切记账：健康 KEY 不能因被放弃的请求背上冷却
+                                return _cancel_fail()
+                            if status == 0 or not (200 <= status < 300):
+                                msg = ""
+                                if isinstance(data, dict):
+                                    e = data.get("error")
+                                    msg = e.get("message", "") if isinstance(e, dict) else str(e)
+                                if status == 400 and isinstance(body.get("thinking"), dict) \
+                                        and "thinking" in str(msg).lower() and not stripped:
+                                    # 网关不认 thinking 对象：摘掉同 KEY 立即重发，
+                                    # 别让「思考程度」偏好把健康 KEY 送进冷却
+                                    body.pop("thinking", None)
+                                    if sbody is not None:
+                                        sbody.pop("thinking", None)
+                                    stripped = True
+                                    continue
+                                last_err = err or ("HTTP %s %s" % (status, str(msg)[:200]))
+                                try:
+                                    modelhub.note_key_error(bi["provider_id"], kk.get("id") or "", last_err)
+                                except Exception:
+                                    pass
+                                break            # 换下一个 KEY
+                            text, calls, usage = _parse_reply(proto, data)
+                            # 非流式响应里的思考字段：补发一次，可视化与流式路径同形
+                            _take_reason(_reason_from_message(proto, data))
+                        try:
+                            modelhub.note_key_ok(bi["provider_id"], kk.get("id") or "")
+                        except Exception:
+                            pass
+                        usage = _norm_usage(usage)
+                        for k in total_usage:
+                            total_usage[k] += int(usage.get(k) or 0)
+                        iters = it
+                        got = True
+                        break
+                    if not got:
+                        continue                 # 本 KEY 失败，换下一个
+                    if calls and force_finalize:
+                        # 收尾请求明确禁用工具；模型若仍返回 tool call，不能再
+                        # 开启新一轮，否则会绕过止损边界。
+                        last_err = "收尾时模型仍请求工具"
+                        last_action_was_tools = False
+                        done = True
+                        break
+                    if calls:
+                        sig = json.dumps(
+                            [(c.get("name"), c.get("args") or {}) for c in calls],
+                            ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+                        if sig == repeat_tool_signature:
+                            repeat_tool_streak += 1
+                        else:
+                            repeat_tool_signature = sig
+                            repeat_tool_streak = 1
+                        if repeat_tool_streak >= 3:
+                            repeat_stop = True
+                            if log:
+                                log("[迭代 %d] 检测到同一工具调用连续重复，转入收尾" % it)
+                            _fire(on_activity, "检测到重复工具调用，正在收尾")
+                        if log:
+                            log("[迭代 %d] %s 请求工具: %s" % (
+                                it, model, ", ".join(c["name"] for c in calls)))
+                        _fire(on_activity, "请求工具: " + "、".join(c["name"] for c in calls))
+                        results = []
+                        for c in calls:
+                            out = _exec_tool(workdir, c["name"], c["args"], cancel_event,
+                                             deadline=deadline, task_creator=task_creator,
+                                             disabled_tools=disabled_tools, sandbox=sandbox,
+                                             checkpoint_run_id=checkpoint_run_id,
+                                             tool_output_run_id=tool_output_run_id)
+                            # 运行期注入警示层：外部内容（网页/命令输出/文件）一律
+                            # 包围栏进上下文；检测命中升级强围栏（prompt_guard）。
+                            try:
+                                from . import prompt_guard
+                                out = prompt_guard.wrap_external(out, c["name"])
+                            except Exception:
+                                pass
+                            if log:
+                                brief = out if len(out) <= 120 else out[:120] + "…"
+                                log("[工具] %s → %s" % (c["name"], brief.replace("\n", " ⏎ ")))
+                            _fire(on_activity, "%s %s" % (
+                                c["name"], str(c["args"].get("path")
+                                               or c["args"].get("command") or "")[:80]))
+                            results.append((c["id"], out))
+                        msgs.append({"role": "assistant", "content": text, "tool_calls": calls})
+                        msgs.append({"role": "tool_results", "tool_results": results})
+                        _bound_direct_context(msgs, run_id=tool_output_run_id)
+                        empty_streak = 0
+                        last_action_was_tools = True
+                        done = True
+                        break
+                    if (text or "").strip():
+                        if log:
+                            log("[迭代 %d] 最终回答（%d 字）" % (it, len(text)))
+                        ok = True
+                        empty_streak = 0
+                        last_action_was_tools = False
+                        done = True
+                        break
+                    # —— 零正文零工具：分辨「思考占满输出预算」还是「模型真没说话」。
+                    # 推理模型的思考计入 max_tokens：想满了流会正常收，正文却是空的。
+                    last_action_was_tools = False
+                    rlen = len(reasons[-1] or "")
+                    out_tok = int(usage.get("output") or 0)
+                    exhausted = (rlen >= THINK_EXHAUST_MIN_CHARS
+                                 or out_tok >= int(max_tokens * 0.9))
+                    empty_streak += 1
+                    if exhausted and not escalated:
+                        # 同轮提额重试一次：8K 想不完的 16K 大多就想完了
+                        escalated = True
+                        old = max_tokens
+                        max_tokens = min(max_tokens * 2, MAX_TOKENS_CAP)
+                        last_err = ("模型思考占满输出预算（max_tokens=%d，思考 %d 字零正文）"
+                                    % (old, rlen))
+                        if log:
+                            log("[第 %d 轮] 思考 %d 字仍无正文/工具 → max_tokens %d→%d 同轮重试"
+                                % (it, rlen, old, max_tokens))
+                        _fire(on_activity, "思考占满输出预算，提高输出预算重试")
+                        reBump = True
+                        break
+                    if empty_streak >= EMPTY_TEXT_MAX_STREAK:
+                        last_err = ("模型思考连续占满输出预算（max_tokens 已提到 %d 仍无正文）"
+                                    % max_tokens) if exhausted else \
+                            ("模型连续 %d 轮零正文零工具" % empty_streak)
+                        done = True
+                        stopit = True
+                        break
+                    last_err = "模型未返回文本"
+                    if log:
+                        log("[第 %d 轮] 模型零正文零工具（思考 %d 字），重试" % (it, rlen))
+                    _fire(on_activity, "模型零正文，重试")
+                    done = True
+                    break
+                if done or reBump:
+                    break
+            if reBump:
+                continue        # 同一迭代用新预算重来
+            break               # 非提额路径一锤定音
+        if not done:
+            break   # 所有 wire/KEY 都失败
+        if ok or stopit:
+            break
+    if not ok and not text and finalize_attempted:
+        # 工具已经执行过且收尾调用也未能给正文：把真实执行结果作为“部分完成”
+        # 返回。pipeline 会按成功步骤落盘，用户可以继续追问而不是被迫重跑。
+        partial = _fail(last_err or "已完成工具操作，但未生成最终总结")
+        partial["ok"] = True
+        partial["partial"] = True
+        partial["text"] = ("部分完成：已执行部分操作，但未能生成最终总结。"
+                            "请检查工作目录中的产出文件，或继续追问以完成剩余事项。")
+        partial["error"] = last_err or "已完成工具操作，但未生成最终总结"
+        partial.setdefault("raw", {})["partial"] = True
+        return partial
+    if not ok and not text:
+        return _fail(last_err or "工具循环达上限仍无最终回答")
+    return {"ok": True, "text": (text or "").strip(), "usage": dict(total_usage),
+            "error": "", "model": model, "provider_name": bi["provider_name"],
+            "provider_id": bi["provider_id"], "iterations": iters, "cost_usd": 0.0,
+            "raw": _perf(),
+            "reasoning": "\n\n".join(r for r in reasons if r)[:THINK_MAX_CHARS]}