codebee 0.1.69 → 0.1.70

package/app/core/builtin_agent.py

@@ -13,10 +13,13 @@
 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
@@ -25,7 +28,7 @@ from pathlib import Path
 
 from . import modelhub, runner, tlsctx
 
-MAX_TOOL_ITERS = 16          # 单步工具循环上限（防模型打转）
+MAX_TOOL_ITERS = 32          # 单步工具循环上限（防模型打转；收尾另留 1 轮）
 READ_MAX_BYTES = 64 * 1024   # read_file 单次读取上限
 READ_HEAD_BYTES = 44 * 1024  # TokenJuice 借鉴（openhuman）：超限文件头尾保留、
 READ_TAIL_BYTES = 16 * 1024  # 中段省略——日志/代码的报错常在尾部，纯截头会丢关键信息
@@ -50,13 +53,19 @@ _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"):
@@ -286,6 +295,35 @@ def _tool_read_file(workdir, args):
         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:
@@ -343,7 +381,10 @@ def _tool_write_file(workdir, args):
     if base not in dest.parents:
         return "（路径越界: %s）" % rel
     dest.parent.mkdir(parents=True, exist_ok=True)
-    dest.write_text(content, encoding="utf-8")
+    # 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))
 
 
@@ -388,12 +429,254 @@ def _tool_run_command(workdir, args, cancel_event=None, deadline=None):
     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 时保留开头与结尾、中段省略；图片等二进制文件无法读取）",
-     "args": {"path": "文件相对路径"}},
-    {"name": "write_file", "description": "把文本内容写入工作目录内一个文件（UTF-8，父目录自动创建）",
+    {"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、按键应答的安装器）。",
@@ -402,10 +685,78 @@ TOOLS_SPEC = [
 ]
 
 _TOOL_IMPL = {"list_files": _tool_list_files, "read_file": _tool_read_file,
-              "write_file": _tool_write_file, "run_command": _tool_run_command}
-
-
-def _exec_tool(workdir, name, args, cancel_event=None, deadline=None):
+              "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
@@ -419,23 +770,55 @@ def _exec_tool(workdir, name, args, cancel_event=None, deadline=None):
 
 # ---------------------------------------------------------------- 协议适配
 
-def _openai_tools():
-    return [{"type": "function", "function": {
-        "name": t["name"], "description": t["description"],
-        "parameters": {"type": "object",
-                       "properties": {k: {"type": "string", "description": v}
-                                      for k, v in t["args"].items()},
-                       "required": list(t["args"].keys())}}}
-        for t in TOOLS_SPEC]
+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 _anthropic_tools():
-    return [{"name": t["name"], "description": t["description"],
-             "input_schema": {"type": "object",
-                              "properties": {k: {"type": "string", "description": v}
-                                             for k, v in t["args"].items()},
-                              "required": list(t["args"].keys())}}
-            for t in TOOLS_SPEC]
+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):
@@ -822,7 +1205,7 @@ def _m_anthropic(m):
 
 
 def _build_request(proto, base, use_key, model, system, msgs, with_tools, stream=False,
-                   max_tokens=BASE_MAX_TOKENS):
+                   max_tokens=BASE_MAX_TOKENS, extra_specs=None):
     """按协议构造 (url, headers, body)。msgs 为内部统一形状。
 
     stream=True 时按协议打开流式：google 换 :streamGenerateContent?alt=sse，
@@ -857,7 +1240,7 @@ def _build_request(proto, base, use_key, model, system, msgs, with_tools, stream
         body = {"model": model, "max_tokens": max_tokens, "system": system,
                 "messages": [_m_anthropic(m) for m in msgs]}
         if with_tools:
-            body["tools"] = _anthropic_tools()
+            body["tools"] = _anthropic_tools(extra_specs)
         if stream:
             body["stream"] = True
         return url, headers, body
@@ -873,7 +1256,7 @@ def _build_request(proto, base, use_key, model, system, msgs, with_tools, stream
     body = {"model": model, "max_tokens": max_tokens,
             "messages": [{"role": "system", "content": system}] + msgs_wire}
     if with_tools:
-        body["tools"] = _openai_tools()
+        body["tools"] = _openai_tools(extra_specs)
     if stream:
         body["stream"] = True
         body["stream_options"] = {"include_usage": True}
@@ -943,7 +1326,8 @@ def _norm_usage(usage):
 
 
 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):
+        on_reason=None, on_stream=None, on_activity=None, stream=True, deadline=None,
+        task_creator=None):
     """跑一次内置智能体（内部自带工具循环直到给出最终回答）。
 
     bi: resolve() 的返回；prompt: 本轮完整输入（目标/续轮块由 pipeline 拼）；
@@ -982,6 +1366,11 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
     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():
@@ -1033,7 +1422,20 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
         out["cancelled"] = True
         return out
 
-    for it in range(1, MAX_TOOL_ITERS + 1):
+    # 工具上限后最多再给一次“只输出总结”的机会。这样最后一轮已经
+    # 成功写文件/抓数据但尚未总结时，不会把真实成果误报成失败。
+    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():
@@ -1053,15 +1455,18 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
                             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,
-                            tools_ok, max_tokens=max_tokens)
+                            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,
-                                tools_ok, stream=True, max_tokens=max_tokens)
+                                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。
@@ -1155,7 +1560,27 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
                         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)))
@@ -1163,7 +1588,7 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
                         results = []
                         for c in calls:
                             out = _exec_tool(workdir, c["name"], c["args"], cancel_event,
-                                             deadline=deadline)
+                                             deadline=deadline, task_creator=task_creator)
                             if log:
                                 brief = out if len(out) <= 120 else out[:120] + "…"
                                 log("[工具] %s → %s" % (c["name"], brief.replace("\n", " ⏎ ")))
@@ -1174,6 +1599,7 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
                         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():
@@ -1181,10 +1607,12 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
                             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
@@ -1225,6 +1653,17 @@ def run(bi, prompt, workdir, timeout=180, cancel_event=None, log=None, images=No
             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),