Changelog 存档

当前在开发的变更写在仓库根目录 CHANGELOG.md([Unreleased] + 最新发布版)。这里只放已经过期的发布说明,不要往这里追加新条目。


[1.5.1] - 2026-11-04

changes

  • 1.5.1 的 Desktop 安装包补打。 Windows 上 Git 自带的 GNU tar 不能解开带盘符的路径,改用 System32\tar.exe;macOS 上空的 CSC_LINK 被 electron-builder 当成证书路径,未签名构建直接失败;CPython 压缩包下载失败会再试两次。三条都只影响安装包,不影响已发布的 PyPI / npm 包。
  • 会话标题不再为了识别技能轮次去加载整个技能包。 SessionLog.session_preview 原来 from agentica.skills.skill import Skill,这会先执行 agentica.skills 的包初始化(loader、installer、curator)。识别逻辑挪到 agentica.utils.skill_invocation.invocation_label,Skill.invocation_label 改为调用它。
  • Gateway 拆成独立发行包 agentica-gateway,Web 产物改到 web/dist,一个 tag 统一发布全部产物(参照 deepseek-harness 的「按包拆源码、按家族统一版本」):
  • 两个 PyPI 包,同一个版本。 agentica 只剩 SDK + CLI,pip install agentica 不再装 fastapi、uvicorn、lark-oapi。服务端、Web UI、IM 渠道、cron 移到 gateway/,发布为 agentica-gateway(导入名 agentica_gateway),精确锁定同版本的 agentica,因为它用到核心包内部模块。agentica[gateway] 改为「同版本的 agentica-gateway[feishu]」,agentica[wechat] 等渠道 extra 照旧,README 里的 uv tool install "agentica[gateway]" 不用改。agentica-gateway 自己的 extra 是 [feishu]、[wechat]、[telegram]…和 [all];单装它不带飞书 SDK,飞书渠道缺 SDK 时日志会给出安装命令。
  • agentica-gateway 命令保住了。 uv 的 tool install 只暴露命令行上那个包的可执行文件,实测拆分后 uv tool install "agentica[gateway]" 只剩 agentica,老用户 uv tool upgrade agentica 也会丢掉这个命令。所以 agentica 包里保留同名命令 agentica.cli.gateway_command:装了网关就直接转过去,没装就提示装哪个包。四种安装方式(uv tool + extra、只装核心、只装网关、pip 同一 venv 装两个)都实测过。
  • 旧导入路径可用。 agentica.gateway.* 经 meta-path 别名指向 agentica_gateway.* 的同一模块对象(单例和 monkeypatch 目标共享),会给 DeprecationWarning,计划在 1.7 移除。python -m agentica.gateway.main 也还能跑,旧版 Desktop 依赖它。agentica.cron.scheduler._execute_job 改为公开的 execute_job,保留旧名。
  • Web 产物不再写进 Python 源码目录。 npm run build 输出 web/dist;gateway/hatch_build.py 构建 wheel 时把它放进 agentica_gateway/ui,sdist 里同样带一份(从 sdist 装不需要 Node);找不到 web/dist 时构建直接失败,要构建无 UI 的包须显式设 AGENTICA_GATEWAY_ALLOW_NO_UI=1。网关按 $AGENTICA_WEB_DIST → 包内 ui/ → checkout 的 web/dist 查找 UI,所以 editable 开发时 build 完刷新即可,不用拷文件。
  • 一个 tag 发布全部。 scripts/versions.py set X.Y.Z 一次改齐 18 处版本(两个 pyproject、互相锁定的依赖、Desktop 与 sdk-ts 的 package.json 和 lock),check 进 CI。新增 .github/workflows/release.yml:Web 只构建一次,两个 wheel 和 sdist 用 scripts/verify_dists.py 校验内容后,先发 agentica 再发 agentica-gateway(PyPI Trusted Publishing,不存 token),sdk-ts 发 npm(provenance),Desktop 调用 desktop.yml 并装同一批 wheel,最后把 wheel、sdist、安装包和 agentica-web-X.Y.Z.tar.gz 挂到 GitHub Release。Linux CI 拆成 versions / core / web / sdk-ts / gateway 五个 job,core 断言裸装不带服务端依赖、gateway 在仓库外的干净 venv 里装构建出来的 wheel 再跑测试。Dockerfile 改为构建两个 wheel 后安装。
  • 开发者注意:改为 pip install -e . -e ./gateway。pip install -e ".[gateway]" 会去 PyPI 解析 agentica-gateway,装不到本地网关代码。只 pip install -e . 的旧环境里,agentica-gateway 会打印安装提示,不再启动网关。
  • 发布前要做的一次性设置:在 PyPI 为 agentica 和 agentica-gateway 两个项目添加 Trusted Publisher(仓库 shibing624/agentica、workflow release.yml、environment pypi);仓库 secret NPM_TOKEN;GitHub environments pypi、npm。PyPI 上的 agentica-gateway 项目(0.1.1,2026-02)是本账号早先发布的,沿用这个名字。
  • Code review 修复(会话列表 / fork / 技能消息 / 文件编辑卡片):
  • 技能消息的普通文本不再被 chip 吞掉:parseSkillTurn 原来只认 Loading: … / Base directory: … 两行前缀,粘贴的 SKILL.md、日志或讨论文字会被整条替换且复制不到原文。现在要求调用尾部、已安装技能名或「目录末段与技能名一致」三者之一;找不到参数终止标记时不再把余下正文当参数。即使识别成 chip,也新增「查看原文」开关,footer 复制始终复制用户原文。
  • /tmp 下真实对话不再从 Web 消失:hide_temp_dirs 原来隐藏所有系统临时目录下的会话,用户自己选 /tmp/myproj 工作后聊完就再也找不回来。现在只隐藏没有真实用户轮次的残留(0 字节 stub、无 user 行的日志);运行中会话仍始终列出。
  • fork 不再静默产生错误分支:SessionLog.fork 原来跳过无法解析的行并照常返回成功。现在分两种:文件末行不完整(并发追加的半行)会短暂重读,仍不完整且分叉点还没读到时报错,而不是交出一个缺最新一轮的分支;中间的历史坏行保持原来的跳过,带旧损坏的日志仍可 fork。写任何东西之前先校验 at_uuid 存在,所以失败不会留下半成品,也不会往跨会话搜索索引里留孤儿行。没有给 fork 加会话锁:聊天在整个 run 期间持有该锁,发送时发现被占用会直接报 already has an active run,fork 持锁会让用户同时发消息时出错。补了半行、分叉点在坏尾行之前、旧日志中间坏行、未知 entry 不落盘、跨账号隔离的测试。
  • POST /api/open 的 app 改为枚举校验:未知值返回 422,不再静默退化成默认打开;Linux reveal 对相对路径不会执行 xdg-open ""。补了 reveal 与相对路径测试。
  • 新增接口的鉴权回归测试:fork / feedback / 单条记忆 / reveal 四个入口补了未带凭证 401 与「owner 取自凭证、忽略请求体」的用例。
  • Web / 桌面端会话列表与 CLI 分开,清掉测试残留;回复下方的文件卡片和 footer 重做:
  • CLI 会话默认不显示。 设置 › 常规新增开关「显示 CLI 会话」,默认关闭,按账号保存在 gateway prefs(show_cli_sessions)。GET /api/sessions 按这个开关过滤:关闭时只列出 gateway 发起的会话(Web、桌面端、IM)。打开后也只额外加入 source=cli 的会话,SDK 脚本和没有 source 的旧日志仍然不出现;正在运行的会话始终列出。scope=recent 时 CLI 会话仍只保留最近 recent_days 天。CLI 会话一旦在 Web 里继续聊,就算 gateway 会话。
  • 系统临时目录里的无内容残留不再列出。 工作目录在 /tmp、/private/tmp、/var/folders 或 $TMPDIR 下、且没有任何真实用户轮次的会话(VPet 等程序的测试和演示留下的 0 字节 stub、只有系统行的日志)会被隐藏;有过真实对话的会话照常列出,因为 Web 没有恢复入口。$AGENTICA_HOME 和 gateway 默认目录(含子目录)不受影响;运行中的会话始终列出。
  • 测试残留会话已移走。 Touch tmp/<ISO-timestamp>.txt in one run.、a much better thing 等只有一句话的会话,是 9 月至 10 月 5 日 cron 测试任务漏进真实 ~/.agentica/cron、被 CLI cron daemon 每分钟执行一次留下的。那条路径已经不再产生新会话:CLI runner 不写会话日志,gateway 的定时任务写入单独的 scheduled_ 会话且不列出。本机 361 个这类会话已移到 ~/.agentica/trash/junk-sessions-20261104/,跨会话提问索引里对应的 4,625 行也一并删除,避免 <session_recall> 再把它们召回。全部会话从 615 个降到 225 个,默认只显示 Web 会话时是 15 个。
  • 查看轨迹显示完整 work_dir。 不再缩写成 …/最后两级,可以直接选中,旁边加了复制按钮。
  • 技能轮次显示成技能名。 CLI 和 gateway 写进会话日志的是展开后的完整 SKILL.md 提示,回看历史时整份技能文本都塞在用户气泡里。现在识别 render_invocation() 的格式,气泡里只显示带下划线的技能名和参数,点击在右侧文件面板打开 SKILL.md(Markdown / 源码 / 纯文本,可刷新、用编辑器打开)。输入框里已安装技能的开头 /trigger 同样可点。刚发出、还没从日志读回的 /trigger 参数 也按同样方式显示。格式标记由 tests/skills/test_skill_invocation_markers.py 固定,改格式时 Web 不会悄悄退回长气泡。
  • 回复下方的文件卡片。 卡片铺满宽度;先列「已编辑 N 个文件」,按 apply_patch 的补丁统计每个文件的 +增 -删 行数(write_file 只计新写入的行数;失败的调用不计;原来 apply_patch 改过的文件根本不进卡片),再列回复里提到的其他文件。点击文件仍在侧边栏预览,行尾新增「用默认应用打开」和「打开所在文件夹」。后者对应 POST /api/open 新增的 app: "reveal":macOS 用 open -R,Windows 用 explorer /select,,Linux 打开所在目录。
  • 回复 footer。 改为:复制、点赞、点踩(弹出可选的问题说明)、从这里分叉,以及「用量 N tok」(悬停显示输入、缓存、输出、tok/s、费用)、耗时和时间。新增接口:
    • GET/POST /api/sessions/{id}/feedback:评价存在 sidecar 的 feedback 字段,以日志条目 uuid 为键,不写入 JSONL;再点一次已选中的赞或踩即撤销。
    • POST /api/sessions/{id}/fork:复用 SessionLog.fork,在同一项目里复制到该回复的最后一条日志,标记为 gateway 会话,名字加「(fork)」,然后直接打开。
    • 回放的消息现在带日志 uuid;刚流式输出完、还没有 uuid 的回复,会先从日志读回再执行分叉或评价。
  • 工作区只保留一个「New Chat」,记忆页能看正文:
  • 工作区行的 +、顶部 New chat、ensureSession()(发送时)以及「添加工作区」都会落到同一个空草稿;连点 N 次不再堆 N 个一模一样的 New Chat 行。复用按工作区目录判断,且只认本地未发送、无服务端日志的草稿(已发过消息、已重命名、归档、运行中和来自服务端的空会话都不会被合并);发现历史遗留的多个草稿时会保留最新一个并清掉其余。判定逻辑抽到 web/src/lib/sessionDrafts.ts,带单测。
  • 设置 › 记忆:常驻规则改回源码显示(之前用 Markdown 渲染,看不到 #、列表标记这些实际写进 system prompt 的内容),新增复制源码和打开文件按钮。
  • 生成对话记忆的条目可以点开:新增 GET /api/memory/entry?filename=…,只接受本账号 MEMORY.md 索引里列出的文件名(路径穿越和索引外文件一律 404),返回去掉 frontmatter 且脱敏后的正文、原始文件路径和来源工作目录。条目展开后显示源码、路径、复制和打开文件按钮,正文按需懒加载;未列出的文件读不到,避免把 AGENTS.md 之类的文件暴露给页面。
  • 区分「记忆文件坏了」和「gateway 是旧进程」:前端已 rebuild 但 gateway 没重启时,请求新路由会得到 404,页面原来笼统显示「无法读取这条记忆文件」,让人以为是文件损坏。现在 404 单独提示重启 agentica-gateway,并说明若已是新进程则意味着条目已从索引移除或文件被删。
  • CLI 启动从约 3.5–4.6 秒降到约 1 秒,import agentica 从 0.44 秒降到 0.31 秒(M3 Pro,2 个 MCP server:一个远程 HTTP,一个本地 stdio。测量方法:在 pty 里启动 CLI,计时到出现输入提示):
  • MCP 工具列表按 server 配置缓存。 原来每次建 agent(CLI 每次启动、gateway 每个会话)都要逐个连接全部 MCP server,只为拿工具列表,每个约 1 秒。而工具调用本来就是每次单独建连接,启动时这一步纯粹是取列表。现在 prepare_mcp_servers 先读 ~/.agentica/cache/mcp_tools/<hash>.json:键由 server 名、url/headers、command/args/env 计算,不包含进程环境变量;命中缓存就直接注册工具,不连接 server。启动 5 秒后,后台线程用新建的实例重新拉一次列表、写回缓存,当前会话的工具列表不变(工具 schema 在缓存的提示词前缀里),新列表从下一个会话开始生效。没有缓存的 server 改为并行连接,启动只等最慢的那个,不再是所有 server 耗时之和;连不上的 server 会跳过并打印 warning,不写缓存,下次启动重试。设 AGENTICA_MCP_TOOLS_CACHE=0 关闭缓存。实测:首次启动(无缓存)2.8 秒,之后约 1.0 秒;从缓存建 agent 用时 8 ms,通过缓存注册的工具做真实调用正常。
  • mcp SDK 改为用到时再导入。 agentica.mcp 的导出改为首次访问时加载(PEP 562);McpTool 只在真正连接时才导入 mcp,StdioServerParameters 也在首次连接时才构造。命中缓存时整个进程都不导入 mcp,省约 0.2 秒。未安装 [mcp] extra 时,导入 agentica.mcp 仍报原来的错误。
  • load_global_config 加缓存。 启动时会读 config.yaml 约 16 次,每次用 ruamel 解析约 20 ms。现在按 (路径, mtime_ns, 大小) 缓存解析结果,每次返回一份副本,调用方修改不影响缓存。自己写入(_save_commented)或其他程序改了文件,缓存都会失效。
  • import agentica 不再加载 bs4 / requests / markdownify。 UrlCrawlerTool 改为第一次抓取网页时才导入 bs4,knowledge 改为第一次读文件或 URL 时才导入 MarkdownConverter。from agentica import Agent, DeepAgent, OpenAIChat 从 0.68 秒降到 0.53 秒。
  • o200k 词表解析快约 30%。 改用 binascii.a2b_base64。这一步在 CLI 启动路径上,用来给状态栏算初始上下文。
  • Web/Desktop 侧栏改为「工作区」,并重做设置页(对照 deepseek-harness):
  • 工作区:侧栏分组改称工作区,标题行有搜索和「添加工作区」。添加时选一个本机已存在的文件夹(不会替你创建),加入后立刻新建一个对话;空工作区也会列出。每个工作区的 ⋯ 菜单可重命名(双击名称也行)和删除。重命名只是显示名,不动磁盘文件夹;删除会移除该工作区下的对话,工作区里有运行中的对话时拒绝,磁盘上的文件夹不受影响。工作区列表存在账号偏好 prefs.workspaces(PUT /api/prefs),新增项服务端校验目录存在,已有项重命名和移除不再复查,所以文件夹被删后条目仍能清理。
  • 侧栏:「新建对话」改为顶部按钮,插件、定时任务在下方;可拖拽右边缘调宽(220–480px,记在浏览器里,双击恢复默认);侧栏换成 dsh 的浅灰底与 hover 色。
  • 设置页:640px 标签页改成 800px 左右两栏(左侧导航带图标,右侧内容),常规页的主题、语言改为「左文案、右分段控件」的行,模型配置、记忆、个人助理、定时任务、归档保持原内容。窄屏退化为顶部横向导航。
  • Logo 改为圆角方形应用图标:Desktop 的 Dock/任务栏图标、网页侧栏和浏览器标签原来是一只方底的猫,后来改成纯圆底,现在换成 iOS 风格的圆角方形(squircle)浅蓝底板 + 猫,和常见 App 图标一致。desktop/make_icon.py 从 docs/assets/logo.png 一次生成四处资源(build/icon.png、app-icon.png、favicon.png、favicon.ico,并去掉原图的白底;ICO 只保留 16/32/48 三档,约 7KB)。侧栏 Logo 的 border-radius:50% 裁切同步去掉。
  • Desktop 安装包自带 Python 运行环境,免系统依赖,并支持自动更新:每个安装包把 python-build-standalone 的 CPython 3.12.16 和用本次提交构建的 agentica[gateway] 放进 <resources>/runtime(desktop/scripts/prepare-runtime.js,用 pip --platform --target 装依赖,一台 CI 机器可以组装另一种架构)。启动网关的优先级为 AGENTICA_GATEWAY_BIN → 内置解释器 → 本机 agentica-gateway / 托管 venv / 系统 Python / uv 引导;内置解释器带 PYTHONNOUSERSITE=1。新增 Help › Install 'agentica' Command in Terminal…(desktop/cli-shim.js)、electron-updater 自动更新(desktop/updater.js,未签名的 macOS 构建跳过检查)、macOS hardened runtime 权限,以及 CI 里按 secrets 可选的 macOS 签名公证和 Windows 签名。解压后约 377MB(lark_oapi 约 98MB)。
  • Web/Desktop 会话侧栏不再一次拉取全部历史会话:GET /api/sessions 新增 scope=recent|all(默认 recent)和 recent_days(默认 30),默认返回全部网页会话、最近 30 天的 CLI 会话、运行中和已归档会话。会话来源写入 .meta.json 的 source,旧会话缺省时用 last_read_at 判断,过滤发生在读取 preview 之前;preview 按文件版本缓存(上限 10000 条的 LRU)。5000 个会话下默认请求从约 5.5 秒 / 1.9MB 降到约 0.4 秒 / 12KB。侧栏项目分组默认显示 5 条,搜索覆盖标题、项目名和首条消息,加载失败不再清空已有列表,已加载且未变化的会话不再重放整份 Trace。
  • Web 聊天布局与首屏体积:空会话时欢迎语和输入框一起居中,Markdown/KaTeX、Trace、用户页按需加载,首屏主包由约 1.18MB 降到约 366KB。Desktop 记住窗口尺寸、位置和最大化状态,外接显示器被拔掉后自动回到可见区域,启动背景跟随系统暗色。
  • 修复 Web 端发不出消息:浏览器本地缓存写满后,发送流程中途抛错:侧栏的会话缓存 ag_s:<账号> 原来会把整份会话列表连同打开过的每个会话的完整对话一起写进 localStorage。本机有 5000 多个 CLI 会话,光列表就占了 1.9MB,再打开几个长会话就会超出浏览器约 5MB 的配额。之后每次 saveSessions() 都会抛 QuotaExceededError,而发送路径上就有这一步,所以点了发送没反应,消息留在输入框里。现在缓存里只存服务端不返回的 token/耗时计数,并且只存在本浏览器跑过对话的会话;标题、时间和对话内容每次都从服务端日志重新取。写缓存失败时只打一条警告,不再打断发送。
  • 修复网页端设置页报 'coroutine' object is not iterable:Workspace 里有两个同名的 list_memory_index_entries,原来的同步版本被后加的 async 版本覆盖了。gateway 的 read_memory_index 仍用 asyncio.to_thread 去调它,拿到的是一个没被 await 的 coroutine,FastAPI 序列化响应时抛错。现在删掉被覆盖的同步版本,调用方直接 await。
  • 修复退出时 hook 清理报 can't create new thread at interpreter shutdown:记忆这类 fire-and-forget 的 hook consumer 在进程退出时还没结束,atexit 里调用 HookProcess.kill(),它会起一个 reaper 线程回收僵尸进程,而较新的 Python 3.12 在这个阶段已经不允许创建线程。现在退出时只 kill 进程组、关闭管道,不再起线程:父进程退出后,子进程会被 init 回收。
  • Gateway IM 渠道的权限档位跟随 Web 端的选择:原来 IM 会话从不设置审批档位,固定是默认的 auto;IM 又没有审批卡,所以凡是需要审批的操作(改 work_dir 以外的文件等)都会直接被拒绝,也没有任何配置能改。现在每轮 IM 消息开始前,会读取该账号在 Web 输入框旁审批选择器里选的档位(~/.agentica/gateway/prefs/<账号>.json 的 approval_mode),在 Web 上选 allow-all,IM 也就是 allow-all。没选过时仍用 auto。偏好文件读不出来(写一半被中断、手工改坏)时按「没选过」处理并记 warning,不会让这台机器上每条 IM 消息都变成 error processing message。
  • apply_patch 能认出「只抄了长行开头」的 hunk:模型改 CHANGELOG、文档这类一行几百字的文件时,常只把某一行的开头当上下文发过来,而 hunk 按整行匹配,于是报 No line in the file matches it; read the file again before patching.。这句话是错的:那一行在文件里,只是 hunk 里没写完,重新读文件也修不好。现在文件里恰好有一行以这段文字开头(忽略行首缩进,手抄长行时截断和缩进错常一起出现)、并且更长时,改报 Line N starts with this text and continues past it; a hunk line must be the whole line. Send the full line exactly as the file has it, or anchor on a shorter line.。多行都以它开头时(例如 } 对多个 });)说不出是哪一行,仍报 absent。和其他诊断一样,只给行号,不把文件里那行原文发回去。
  • Gateway IM 渠道改为全双工:agent 正在干活时发的话直接插进这一轮:原来微信等 IM 渠道收到的消息进入每个会话的 FIFO,agent 跑一个几分钟的任务时,用户补一句「不对,改成方案 B」要等整轮结束才作为新一轮执行,期间模型还在按旧指令干。现在:
  • 运行中的纯文字消息走 steer(),在下一个 tool batch 边界交给模型,和 CLI 运行中打字、Web 端 /api/chat/steer 一致。只 steer 进本渠道 worker 自己发起的那一轮(回复回到同一个会话);队列里已有消息时不插队;带图片/语音的消息照旧排队,因为媒体要先经过 chat() 的媒体路由。steer() 返回 False(run 还没开始或刚好结束)时照旧排队,不丢消息。
  • 在最后一次推理期间发的话不再丢失。这类 steer 被 agent 停放(pop_undelivered_steer),每轮结束后取出作为下一轮,排在之后排队的消息前面。
  • 排队的消息合成一轮。worker 每次取出此刻队列里的全部消息,文字按顺序拼接、媒体全部附上,跑一轮、回一条,而不是逐条各跑一轮、各回一条。/skill 逐条展开,批里第二条是技能调用也照样生效;AgentService.steer_session() 同样展开 /skill(Web 端 steer 原来把 /skill 原样交给模型)。
  • CLI /compact 显示 session notes 的路径和改动 diff:原来结束只打印 New context window 1: 59 messages -> 2. Prior turns stay in the session log. Session notes rewritten.,看不出 notes 写在哪、写了什么。现在打印 Compacted 59 messages.;模型改写了 notes 时接着打印 Session notes updated (+N -M):,再用和 apply_patch 一样的 diff -- <路径> 格式显示改动,没有改写则提示 Session notes unchanged: <路径>。display_diff 与编辑工具改用同一个 build_file_diff(cli/display/messages.py),不再输出 --- a/ / +++ b/ 两行。同时去掉了窗口编号、59 -> 2 的消息数,以及末尾的 Workspace memory preserved.。
  • UserPromptSubmit 只对人发的消息生效,hook 的 stderr 不再可能卡住一轮:
  • 子 agent、自动轮次和 /goal 续跑不再触发召回和 hook。 task 派生的子 agent 拿到的是父模型写的任务描述,shell hooks 又是进程级的,于是外部记忆库会收到它(session_id 还是兜底值);后台命令回执、peer 消息、/goal 自己塞进队列的 [Continuing toward your standing goal] 也都会每轮跑一次外部 hook 和内置 memory_recall 辅助模型调用。现在 _parent_run_id 非空、automated_input、或以 goal 循环前缀开头的消息,跳过 <memory_recall> / <session_recall> 和 UserPromptSubmit。goal 循环的两种提示(续跑、预算收尾)同时在 runner 里标 automated,不再写进 session_index.db 的 turns、不进意图追踪和会话预览;CLI /goal 和 SDK run_goal 都走这一处。
  • stderr 改为后台线程持续读取。 原来 hook 退出后才同步 stderr.read(),没有超时:hook 留下的后台进程(例如检索完再拉起一次同步)继承了 stderr,管道一直不关,这一轮就卡死;hook 运行中往 stderr 写超过管道缓冲区的日志,也会阻塞到超时被杀。现在 stderr 与 stdout 一样由 daemon 线程读,只在退出码为 2 时才取(最多再等 0.5 秒)。hook 自己退出但后台进程仍占着 stdout 时(纯文本回复、退出码 2 没有 JSON 文档可以提前结束读取),stdout 最多再等 0.5 秒就关闭,保留已经收到的内容。
  • 纯文本回复不会被首行截断。 读 stdout 时判断「完整 JSON 文档已到」只认 JSON 对象;原来首行是 42、true 这类 JSON 标量的纯文本回复会在第一行就停止读取。
  • 被 hook 拒绝时不再提示 Ctrl+O shows raw provider error.,也不再把这一条记成 provider 错误写进日志。拒绝是策略决定,显示谁拒绝、为什么就够了。
  • 外部 shell hooks 按入口决定是否加载,SDK 进程不再读 ~/.agentica/config.yaml 的 settings.hooks:原来 hook_egress_dispatch / collect_prompt_context / start_hook_request 在首次调用时懒加载全局配置,于是同一台机器上任何 Agent / DeepAgent SDK 服务都会每轮跑 CLI 用户订阅的 UserPromptSubmit(把个人记忆注入别人的 prompt),run.completed 也会把服务里的对话交给用户的采集消费者。现在删除懒加载(ensure_hook_egress_installed 一并删除),改为各入口在进程启动时显式 install_hook_egress():
  • CLI:agentica.cli.main.main() 启动时安装,覆盖交互、--query/--print(含 delegate worker)、cron daemon、ACP。
  • Gateway(Web UI、IM 渠道、Desktop App):新增 settings.hooks.gateway,默认 false;为 true 时在 lifespan 里安装。默认关是因为 IM 渠道里的消息可能来自别人。
  • SDK:需要时自己调用 install_hook_egress()。
  • CLI 等人默认最多 5 分钟:提问没人答时,可逆的选择按推荐继续;审批卡没人答时,那一步不执行:
  • 为什么。 曾有一次 ask_user_question 挂了 6522 秒(约 1.8 小时),整个 turn 什么都没做。权限审批卡(ApprovalRegistry.wait)也一样没有截止时间,长程任务半夜弹一张卡,就会卡到天亮。
  • 一个配置管两处,按键盘空闲计时。 settings.human_wait_timeout,默认 300 秒,0 表示一直等。计时从最后一次按键算起(prompt_toolkit 的 before_key_press),用户正在看或正在打字时不会被截断。剩最后 20 秒时,提示框下方出现 continuing without an answer in Ns · any key to stay(审批卡上是 skipping this call in Ns),按任意键重新计时。斜杠命令(/resume、/cron 等)里的提问是用户自己在操作,不会超时。做法参考了 Claude Code 的 askUserQuestionTimeout(空闲计时加 20 秒倒计时)和 dialogExpiry(审批超时走不执行的安全默认);Claude Code 在 auto 模式下另有一个分类器,拦截模型本可以自己决定的提问,这里没有照搬,而是靠工具说明和 AGENTS.md 让模型少问。
  • 提问超时:沉默不等于同意。 工具返回 {"timed_out": true, "response": "", "note": ...},不替用户编答案。note 交给模型自己判断:如果是本地、可逆的选择,按自己标了推荐的选项继续,并在回复里写明选了哪个;如果涉及难以撤销或机器外可见的动作(push、部署、发消息、删除),这一步不做,其余工作做完,在回复里列为待用户处理。工具说明同时要求:能给出推荐的歧义直接按推荐做;不要用这个工具去问「能不能跑这个命令 / 改这个文件」,那是权限系统的事。
  • 审批超时:不执行,也不算用户拒绝。 这次调用不执行,不写入 deny-similar 规则。模型收到的不是 Tool call denied by user.,而是「没人回答审批,这既不是拒绝也不是同意;不要重试,也不要换个办法达到同样效果;把其余工作做完,并把这一步列为待用户处理」。transcript 里显示 ✗ not run (no answer within 300s),session log 的 approval_decision 带 reason="timeout",hook 的 needs.resolved 带 decided_by="timeout"。超时与按键或 hook 应答同时发生时,以 _InputRequest.submit 先成功的一方为准。
  • 等待时状态栏照常走表。 提问框或审批卡出现时,左下角显示 ⏸ waiting for your answer… (1m5s),表示已经等了多久;右下角本轮耗时 ⏱ 和累计 Σ 继续计时,原来会停在弹出那一刻不动。每秒只在显示的秒数变化时重绘一次。重绘不会干扰输入框,因为提问框是在 layout 里绘制的,不是从后台线程打印出来。另外修了一处:本轮在审批卡等待期间被取消时,卡片的空闲检查原来会每秒空转一直到超时,现在以 ApprovalRegistry.is_parked 为准,下一次检查就停。
  • /goal 不再因为歧义暂停。 update_goal 的说明、goal_continuation.md 和 goal_judge.md 都去掉了「需求有歧义就暂停 / 判为完成」:选最合理的方案继续,把假设写进最终答复。只有剩下的每一步都需要只有用户能给的东西(凭据、权限、对不可逆操作的批准)时,才 paused。
  • 新增 UserPromptSubmit hook:外部记忆库可以给每轮消息补充上下文,协议与 Claude Code 完全一致:
  • 为什么是这份协议。 Claude Code、Codex、CodeBuddy 用的是同一套 UserPromptSubmit:stdin 是 {hook_event_name, session_id, cwd, transcript_path, prompt},stdout 是 hookSpecificOutput.additionalContext(或纯文本),退出码 2 表示拒绝并可用 stderr 给出原因。照这个形状实现,为其中任何一家写的 hook 脚本在 agentica 上不用改就能跑;自己发明一套(比如按 agentica 内部事件名命名的 prompt.submit)会让每个外部记忆库为每个宿主各写一份。
  • 与内置记忆并存。 get_messages_for_run 里内置的 <memory_recall> / <session_recall> 与 hook 并发执行(asyncio.gather),hook 的上下文排在内置块之后、用户问题之前。hook 失败、超时或没有订阅者时只是这一段为空,内置召回不受影响;反过来也一样。
  • 进程内形态。 RunHooks.on_user_prompt 从「返回改写后的 message」改为「返回要追加的上下文」,多个 hook 的返回按顺序拼接,每个看到的都是原始 message。改写消息这条语义随之删除:要拒绝一条消息,用输入 guardrail(PromptBlocked 就是 InputGuardrailTripwireTriggered,被拒的一轮不调用模型,CLI 显示为 Prompt blocked by UserPromptSubmit,不按运行失败处理)。
  • 必须显式订阅。 events: {UserPromptSubmit: true}。这一轮要等它(上限 recall_timeout,默认 5 秒,超时的消费者被杀掉),已有的桌面通知类消费者不该因为升级被拉进每轮的等待里。
  • 修掉 5b2981fd..HEAD review 里指出的几处边角问题:历史回放统一丢弃 Message.images / audio / videos 附件字段,只保留文字内容,避免 analyze_image、浏览器截图、SDK/Gateway 上传图在后续轮次被重复编码发送;CLI 那个只处理显式上传图片的局部清理已删除。examples/memory/04_long_term_memory.py / 05_auto_memory.py 不再调用已经删除的 Workspace.get_relevant_memories()。Gateway cron 任务把 permission_mode / work_dir 清空时,现在会清掉该 job session 之前的覆盖值,避免继续沿用旧档位或旧目录。session_recall.selector_line 把 open intent 的 next_step 也交给 selector。cron 运行用量展示测试关闭 rich 颜色和高亮,避免 ANSI 拆字导致断言误判。
  • 记忆召回 selector 的 prompt 模板改为 import 时加载:recall_select.md / recall_select_work.md 和其它 memory prompt 一样在 agentica.prompts.memory import 时读入常量,get_memory_recall_select_prompt() 每轮只做 .format(),不再重新读磁盘。这样长驻 CLI 进程不会在开发期把旧 Python 代码和新磁盘模板混用,也少了每轮两次无意义的模板 I/O。
  • 定时任务按创建时的权限档位和工作目录运行;目录失效或任务自己卡住时带原因暂停,不再重试:
  • 原来的问题。 CronJob.permissions 会存下来,也会被传进运行上下文,但 CliAgentRunner 和 gateway 的 runner 都不读它,所以这个字段一直没有作用。CLI 的 job factory 持有的是宿主会话的 agent_config,而 /permissions 是原地改这个 dict。结果后台 daemon 线程到点时,按的是宿主当下的档位:创建时在 ask,后来切到 allow-all,任务就以 allow-all 无人值守地跑。工作目录也一样,跟着宿主走。
  • 授权快照。 permissions: dict 删除(没有任何读取方),换成 CronJob.permission_mode 和 CronJob.work_dir,DailyTaskSpec 同步修改;gateway 的请求体和返回体也把 permissions 换成了 permission_mode。通过 cronjob 工具创建时,记录的是调用它的 agent 的档位和目录。这两个值由运行时注入,不在 LLM schema 里。模型传 permission_mode 只能比当前会话更严,更宽会被拒绝;update 改档位同样以编辑方会话为上限,而且不会挪动 work_dir。/cron add 也记录当前会话的值。档位非法时,create_job 直接报错。CLI 和 gateway 的 runner 都按记录的值构建 agent。旧任务没有这两个值,行为不变(跟随 runner 默认)。
  • ask 就是试跑。 无人值守的 agent 用的是 deny-on-park 审批,所以 ask 档位下读取和汇报照常进行,写入、会改东西的命令和联网调用都会被拒绝。不再另加 observe 模式。
  • 暂停原因。 新增 CronJob.paused_reason。到点时 work_dir 已经不存在,调度器会暂停任务,不运行它,在运行记录里写一条 MandateError。任务的 agent 会通过 session guidance 拿到自己的 job id,遇到无法在无人值守的情况下继续的情况时,可以调 cronjob(action='pause', job_id=..., reason=...)。暂停的任务不再按 max_retries 重试;一次性任务暂停后保持暂停,不会被标成完成。手动暂停不带原因,resume 会清空原因。有原因的暂停任务会在 CLI 启动时各显示一行,/cron list 里也会显示(/cron list 现在包括已停用的任务)。没有这种任务时不输出任何内容。没有新增存储或命令。
  • 跨项目工作项改由同一次召回选择器语义判断,删除旧关键词记忆召回通道:<session_recall> 的「Related earlier work」不再用 search_intents / match_strength 按关键词和项目名过滤,也不再召回旧提问;现在把所有项目最近的工作项(最多 60 条,带项目路径与状态)交给现有 memory_recall 选择器,同一次调用同时返回记忆文件和工作项 id。这样其它项目的真实上下文仍可被带入,但不会因为 git push、commit、fix 这类通用词把无关仓库的待办塞进当前轮。第一轮的本项目 open items / recent asks 仍本地生成,选择器失败或超时时只缺「Related earlier work」。旧的 Workspace.get_relevant_memories() / _score_memory_entries() 关键词通道已删除,避免再被接到 LLM selector 前面做粗筛。
  • 启动不再因下载 tiktoken 词表卡住:CLI 画输入框之前要先估算上下文 token,tiktoken.get_encoding("o200k_base") 缓存未命中时会从 openaipublic.blob.core.windows.net 下载词表。这个请求没有超时,缓存又放在系统临时目录(macOS 重启或定期清理会清掉),所以网络慢时启动会卡好几分钟;原来「取不到就按字符估算」的兜底只在抛异常时生效,请求挂住时永远走不到。现在 o200k_base 词表(sha256 与 tiktoken 官方 expected_hash 一致,gzip 后约 1.6MB)随包附带在 agentica/utils/o200k_base.tiktoken.gz,本地直接构造 tiktoken.Encoding,运行时不联网。所有模型统一用 o200k 估算(原来 gpt-4 一类会映射到 cl100k,同样要下载),偏差由 ContextCalibration 按上游计费修正。按字符估算的兜底已删除。
  • 图片 / 音频的 base64 不再写进会话历史:add_images_to_message / add_audio_to_message 原来把多模态列表直接赋给历史里那条消息的 content,于是 OpenAI Chat、OpenAI Responses、LiteLLM 三条线上,第一次发请求后像素就成了这条消息的正文:回合结束清掉 message.images 也没用,之后每轮请求都重发,会话 JSONL 里也存成普通正文,/compact、/resume 读回来照样带着。现在两个函数返回副本,只有当次请求带图,历史消息保持原来的文字说明。
  • run(recall_query=...) 指定召回检索词:调用方把用户请求包在大段指令里时(如 IM 网关在每条消息前拼话术 SOP),记忆召回与跨会话召回默认拿整条消息检索,包装里的高频词会带出无关条目。显式传 recall_query 后两条召回都按它匹配,消息原文照常进 prompt;不传时行为不变。实测(真实 SOP + 一句提问,每组 6 次):无关记忆误召回 3/6 → 1/6。
  • 定时任务记录每次运行的 token 用量;deliver 不再接受不存在的投递目标:
  • 用量。 AgentRunner.run() 可以返回 CronRunOutput(content, usage);老的只返回 str 的 runner 照常工作,只是不记用量。TaskRun 新增 usage 字段,包括 input_tokens(含缓存命中)、output_tokens、cache_read_tokens、cache_write_tokens、api_calls、cost_usd;旧记录读出来是 None。CLI runner 从这次运行的 cost_tracker 取数;gateway 的 run_cron 返回 turn_usage,口径和聊天页脚一致。显示的地方:/cron runs 每行末尾,例如 43.0K in (31.2K cached) / 340 out · 3 calls · $0.0128;cronjob(action='runs') 和 /api/scheduler/runs 也返回 usage,后者还带 duration_ms。只统计主模型的请求;辅助模型调用(记忆召回挑选、记忆抽取)不在这次运行的 cost tracker 里,不计入。用真实模型测过(tmp/cron_usage_e2e.py):记录下来的输入和输出 token 与这次运行中 3 个主模型请求的上报之和完全一致,另有 1 个辅助请求按设计不计入。
  • deliver。 原来可以填 telegram、origin 等值,存下来以后什么也不会发送。现在只接受 local:create_job 和 cronjob 的 create/update 遇到其他值会报错,写明暂不支持投递到渠道;gateway 返回 400。工具说明去掉了 deliver 这个可选参数,并写明结果只保存在本地。
  • 记忆召回块标题给出记忆文件的完整路径:标题从 ### <title> (memory/<file>) 改为 ### <title> (~/.agentica/workspace/users/<user>/memory/<file>)(家目录缩写成 ~)。原来的 memory/<file> 是相对用户 workspace 的路径,不是相对当前工作目录,模型直接 read_file 打不开。新增 Workspace.get_user_memory_dir();render_recall_block 多一个 memory_dir 参数。去重仍按文件名,恢复的旧会话历史里 memory/<file> 形式的标题照样识别。
  • 系统提示词与工具说明精简,首轮附 git 快照:
  • 精简。 CLI 默认配置下,系统提示词从 26.7K 字减到 21.1K,17 个工具的 schema 从 22.0K 减到 18.7K(含新增的 forget_memory)。environment_context 去掉 Active skills 一行:它和冻结的 Session Guidance 技能目录重复,而且切换 /model 时会重建,会改变缓存前缀。增强路径不再重复 soul 里已有的「用 markdown」指令;没有 description 时也不再重复「Your name is」。
  • 两条路径统一。 默认路径和增强路径共用 _volatile_system_tail(),按同一顺序渲染:工作区记忆、经验、会话摘要、JSON 输出说明、日期。默认路径原来日期在 JSON 说明之前,摘要的说明文字也不一样。默认路径的「IMPORTANT … MUST call」改写成一句平实的话。
  • 记忆可改可删。 save_memory(replaces=<filename>) 更新已有条目;新增 forget_memory(filename) 删除条目。
  • git 快照(PromptConfig.add_git_snapshot,DeepAgent 默认开启)。 会话第一轮在用户消息前拼一个 <git_snapshot>:分支、git status --short(最多 20 行)、最近 3 个 commit,并注明执行前要先核实。不放进系统提示词,缓存前缀不变。不是 git 仓库、没装 git,或 2 秒内没返回时跳过。
  • get_skill_info 截断。 SKILL.md 正文超过 2 万字时,只返回前面部分(在行边界截断),并附上文件路径和 read_file 的行偏移,模型需要时再分页读取。本机就有一个 51K 的 SKILL.md。
  • 跨会话"上次停在哪":用户提问索引、工作项日志与 <session_recall>:
  • 问题。 长期记忆只抽事实,exclusion_spec 明确不存进行中的工作,所以「继续」「推一下」这类新会话的第一句话没有任何可检索的内容,它指向的上一个会话的收尾也不在任何地方。SessionIndex(FTS5)早就写好了,但没有任何调用方;search_session 和 list_user_questions 都只能查当前会话。
  • 索引。 SessionIndex 重写为每个用户一个 ~/.agentica/projects/<user>/session_index.db。表 turns 存每个会话里人写的提问,带 session_id / work_dir / uuid;自动轮次和换窗前缀不入索引。表 intents 存工作项,表 intent_pending 存待整理的轮次。全文检索对预分词后的列建 FTS5:英文 token 加中文双字切分,和 search_session 用的切分规则一致。SessionLog 只把 user 行同步写入索引,compact_boundary 摘要不再写入;Agent 有会话日志时自动接上索引。已有的会话日志由后台线程补进索引,按文件记录已读到的字节偏移,增量读取。实测 6091 条提问:首次 3.6 秒,再跑 0.04 秒,索引文件 7.9 MB。
  • 工作项(WorkspaceMemoryConfig.track_intents)。 新增 IntentTrackHooks:每轮结束把用户原话和回复(取首尾共 3000 字)写进 intent_pending,攒满 intent_every_n_turns 轮(默认 3)后,在后台调一次辅助模型(intent_track 任务)。模型拿到本项目最近 14 天的 open 工作项和新的几轮,返回新建和更新:同一件事更新原条目,不新建;做完的条目在这一步就改成 done,不会一直挂着"待确认"。每个条目记下来源轮次的 uuid。整理前先认领待整理的轮次,两个进程不会重复处理同一批;调用失败就释放,留给下次重试。会话没来得及整理就退出时,同一项目下一个会话的第一轮会先处理这些轮次(受 recall_timeout 限制)。
  • 会话召回(recall_sessions)。 每个人类回合前,在用户消息前面拼一个 <session_recall> 块(在 <memory_recall> 之前,用户原话仍在最后)。块分三栏,不调用模型:
    • 新会话第一轮:本项目最近 14 天的 open 工作项(3 条)。
    • 新会话第一轮:最近两个会话的最后 3 句提问。已被上面工作项引用的提问不再列出。
    • 每一轮:和这条消息有共同关键词的旧工作项和旧提问,最多 3 条。按 token 计分:id、路径、hash 记 3 分,4 个字母以上的英文词记 2 分,中文双字记 1 分,满 3 分才算相关。长提问只看首尾 400 字,和本条消息完全相同的旧提问跳过。其他项目的条目只在消息里提到那个项目的目录名时才出现。
    • 每行带 [intent:N] / [q:uuid8] 标记和会话 id。上下文里已有的标记不再召回;超过 14 天没更新的 open 条目标为 stale,不显示下一步。整块不超过 2000 字,只截整行。召回块不写入会话日志。
  • search_session。
    • 新增 scope:session(默认)/ project / all。后两个搜之前会话的提问和工作项,project 不带 query 时列出本项目最近 5 个会话的最后几句提问。
    • 新增 session_id:按 id 或前缀打开另一个会话的记录,可配合 query / role / uuid 使用。
    • 当前会话里找不到的 uuid 会去跨会话索引里找,用于取回召回块里摘要所依据的原话。
  • 默认开启范围。 CLI、Web gateway、DeepAgent 默认开启这两项,普通 Agent 默认关闭。recall.py 的 _origin_label 改名为 display_path,供两种召回块共用。
  • 测试。 标注评测 tmp/session_recall_eval.py:3 个项目、13 个用例,包括续接、低信息 query、命中 hash、点名其他项目、不点名其他项目、无关问题、过期条目。应命中的 10/10 全部召回,不应出现的 30 项出现 0 项,平均 459 字。真实数据上相关栏检索 p50 约 62 ms。用真实模型(DeepSeek V4.1 Flash)跑 tmp/session_recall_e2e.py,8 项检查全部通过:
    • 会话 A 说「已 commit 9f3e2c1,先别 push」,生成了 open 工作项。
    • 会话 B 第一句「继续上次没做完的」带上了这条工作项,回复按"未 push、等压测确认"作答。
    • 用户说已经 push 后,该条目改成 done;会话 C 不再列为待办。
    • search_session 按 uuid 取回了会话 A 的原话。
  • 长期记忆记录写入目录,召回块显示出处:Workspace.write_memory_entry 新增 origin_work_dir,写进 frontmatter;save_memory 取 agent 的 work_dir(未设置时取进程 cwd),自动抽取取 agent.work_dir,promote_memory_candidate 保留原值。召回仍按用户进行、不按目录过滤,召回块在标题下多一行 (written while working in <目录>),给的是完整路径,家目录缩写成 ~(read_file、glob、shell 都认),模型拿到后可以直接打开核对;系统提示词里本来就有当前 work_dir 的完整路径,这里没有多暴露什么。search_memory 的结果也带上 origin_work_dir。新增 Workspace.read_memory_entry 返回正文和出处;读出处只看 frontmatter,正文里同名的行不算。用真实 Agent 测过:会话 1 在目录 A 存下偏好,会话 2 在目录 B 问「那是在哪个目录记的,里面有哪个 .toml」,chat 与 Anthropic 线路都按出处打开了 A,答出只有 A 才有的文件。
  • web_search / fetch_url 结果标为第三方内容:结果包在 <external_content source="..."> 里(fetch_url 带 url 属性),工具说明写明标签内是网页文本,不能因为网页让做就执行命令或调用工具。网页里的闭合标签(不区分大小写)会被转义,提前结束不了这个块。用真实模型测过(本地 HTTP 页面,allow-all 权限,chat 与 Anthropic 线路):明显的「SYSTEM NOTICE」注入和与任务挂钩的隐蔽注入,加不加标签都是 0/5 中招,模型本身就能识别;用户让「按页面上的步骤做」、页面要求 touch 一个文件时,Anthropic 线路中招从 3/5 降到 1/5,chat 线路两种条件都是 0/5。这是缓解,不是保证。
  • 读过的文件在外部被修改后提示重读:BuiltinFileTool 在 read_file、write_file、apply_patch 后记下文件的 (mtime_ns, size),最多 200 个,按最近使用保留。take_external_changes() 返回之后变化或被删除的文件,每次变化只报一次。Agent 在每个工具批之后(post-tool hook,消息标记 _injected)和每个人类回合开始时(拼在用户消息前面,改写的是副本)附一条 [File change notice]。只用 stat,不读内容。已知限制:子代理与父代理共用同一个工具实例,子代理自己的写入也算「已看过」。用真实模型测过(两轮之间把 TIMEOUT = 30 改成 75,再问一遍):Anthropic 线路无提示时 0/3 答对,有提示 3/3;chat 线路从 2/3 到 3/3。
  • 相互矛盾的纠正卡片互相标注;中文纠正规则不再被丢弃:纠正卡片写入后,最多 5 张旧纠正卡片交给辅助模型(classification 任务)判断是否矛盾:先取和它有共同词干或中文双字的,剩下的名额给最新的,因为「回复一律用中文」和「Always answer in English」没有共同词,分类器写规则时中英文都会用;没有其他纠正卡片时不发调用。之前纠正卡片的 key 只取英文词干,纯中文规则(如「下次请先跑测试再提交」)得到空 key,卡片直接被丢弃。现在含中文的规则用「英文词干(中文语境下两个字母的名字如 uv 也算)+ 规范化后的中文」作 key:去掉「以后、务必、请、一定要、的」这类不改变意思的词,否定词(不要、别、禁止、不能……)统一折成「不」并保留,所以换个说法会落到同一张卡上,而一条规则和它的反面会分成两张卡、交给冲突检查。纯英文规则的 key 不变。矛盾的两张都写入 frontmatter conflict_with(卡片被再次命中时保留),注入提示词时附一句「两条规则冲突,按当前对话判断并向用户确认」。两张卡片都不覆盖。调用失败或超时(20 秒)时卡片照常保存,只是不标注。新增 agentica/experience/conflicts.py、CompiledExperienceStore.correction_rules / mark_conflict、compiler.rule_terms。用真实模型判了 12 组(英文 6 组、中文 5 组、中英混合 1 组,其中 6 组矛盾),chat 与 Anthropic 线路都 12/12;用真实 Agent 跑完整流程:「以后都用 uv 装依赖,不要用 pip」走 LLM 判定,「记住:用 pip 装依赖就行,别用 uv 了」走关键词预筛,两条线路都生成了两张卡、互相标注,新会话的系统提示词里带上了冲突说明。
  • cron skill 约定「无事可报」标记:bundled cron skill 新增一节:检查变化类任务的 prompt 应写明没有新情况时只回复 [NO_UPDATE],并给了示例。调度器、TaskRun 和界面都没改。
  • 记忆召回块改为前置,并覆盖 messages= 入参:
  • 位置。 <memory_recall> 块从拼在本轮用户消息末尾改为拼在开头,用户原文留在消息最底部。长上下文模型对中部注意力最弱,最新的问题应最后读到。历史消息仍不改动,前缀缓存不受影响;去重按块是否存在判断,与位置无关。
  • messages=[历史..., 本轮 user] 入参也触发召回。 IM 适配器这类每轮自己重建历史的调用方,以列表末尾的 user 消息作为召回 query,块只拼到这一条上。
  • 不改调用方的对象。 列表项可能是调用方保存在自己历史里、下一轮会再传进来的 Message 对象。直接改它的 content 会让召回块混进调用方历史、逐轮叠加,所以改为替换成副本。
  • 去重覆盖整个列表。 去重的上下文从"已组装的消息"扩展到列表里本轮之前的各项:调用方带回的上一轮召回块里已有的条目,不再重复召回。
  • 召回选择调用:超时从 10 秒降到 5 秒,连续失败 3 次后本会话停止召回;修复 Anthropic 线路选择调用必然失败的问题:
  • 超时依据实测。 走 CLI 用的同一网关,chat 线路 ds-v4.1-flash 和 Anthropic 线路 claude-haiku-5-5 各测了 50 次以上(交错调度)。正常调用都在 3.2 秒内完成,p95 分别为 1.7 秒和 2.9 秒;ds-v4.1-flash 约 4.5% 的调用是 7–11 秒的长尾。3 秒会切掉 haiku 的正常调用(50 次里有 2 次超过 3 秒),5 秒只切掉长尾。被切掉的那一轮只是不召回。
  • 熔断。 辅助模型持续不可用时,之前每一轮都要白等满超时。现在 RecallBreaker(挂在 Agent._recall_breaker)按会话计数:超时、异常、返回无法解析的内容都算失败;选出空列表算成功并清零。连续 3 次失败后本会话不再发起选择调用,换会话 id 后自动恢复。parse_selection 和 select_memories 改为失败时返回 None、有效的空选择返回 [],二者不再混为一谈。
  • Anthropic 线路。 选择调用沿用了主轮次的输出上限(模型目录上限)。Anthropic SDK 估计非流式请求可能超过 10 分钟时直接拒绝(Streaming is required for operations that may take longer than 10 minutes)。所以主模型是 Claude 且没配辅助模型时(如 Claude Haiku 走 Anthropic 线路的 profile),召回每轮都失败、没有一次成功。现在 Model.side_call_copy(max_output_tokens=2048) 为辅助调用单独设上限,新增 Model.set_output_cap,由 OpenAI Chat、Responses、Claude、LiteLLM 各自实现;Claude 使用固定思考预算时,上限取预算加 2048,保证预算始终低于 max_tokens。修复后 Anthropic 线路 74 次选择调用全部成功,且选对了条目。
  • 长期记忆每轮主动召回(WorkspaceMemoryConfig.recall_memories):之前系统提示词只带会话开始时冻结的 MEMORY.md 索引(标题 + hook),正文要模型自己想到去调 search_memory;它不知道有相关记忆时就不会去查,而且会话中途别的会话新存的记忆整场都看不到。Workspace.get_relevant_memories 能按 query 取正文,但没有任何生产调用方,get_workspace_memory_prompt 的 query 参数也是空置的。现在每个人类回合前,辅助模型(memory_recall 任务:task 覆盖 → auxiliary_model → 主模型)从实时索引里挑出这条消息需要的条目(max_memory_entries,默认 5),正文以 <memory_recall> 块追加到本轮用户消息末尾。系统提示词不变,历史只追加,不碰 provider 缓存;当前窗口里已有召回块的文件不再提供给选择器,换窗把旧块移出后可再次召回。选择请求不带工具 schema,也不进 cost tracker(新增 Model.side_call_copy);输出只接受索引里存在的文件名,解析失败、超时(recall_timeout,默认 5 秒)或网络错误时本轮照常进行,只是不召回。召回块不写入会话日志。CLI、Web gateway、DeepAgent 默认开启,普通 Agent 默认关闭;三处的 max_memory_entries 从 10 改为 5(该字段此前没有生效代码路径)。用真实模型测过(chat 与 Anthropic 线路各一个):会话 A 存下的端口,在之后才启动的会话 B 里被召回并直接答对,没有调用任何工具;无关的问题不召回;B 两轮的系统提示词逐字节相同。
  • 记忆写入前过滤密钥:redact_sensitive_text 新增 level="memory":在 high-confidence 规则之外,再屏蔽取值不是纯数字或字面量的凭据名赋值(XXX_API_KEY=...、token: ...;compact_token_limit=300000、max_tokens: 50 保留),以及同时含大小写和数字、熵 ≥ 4.2 bit 的 32 位以上无前缀 token(路径、十六进制 hash、小写标识符不受影响)。Workspace.write_memory_entry 写入前对 title / content / description 应用这一过滤,读取索引和正文时也再过一遍,覆盖过滤上线前写入的旧记忆。之前用户在对话里贴出的密钥会原样存进 memory/*.md,之后每个会话的提示词都会带上它。
  • 被淘汰的工具结果占位符带上 tool-call id,可用 search_session 取回原文:之前占位符只提示「重跑这个调用」,但重跑并不等价:execute 这类非幂等调用读到的状态已变,参数被 Layer 1 清掉的调用根本无法重跑。现在当 agent 有会话日志且工具集里有 search_session 时(recoverable),占位符附带 Original output: search_session(uuid="<tool-call id>");OpenAI 与 Anthropic 两种结果形态都取各自的 id。SessionLog.find_entries 先按 tool-call id 在原始日志里精确匹配,返回最早的一行(工具执行时写入的完整结果):换窗后保留尾部会被重写,搜索索引会剔除原始行,重写出的副本可能已是占位符,Anthropic 形态下还是不带 id 的 user 行,所以不能走索引;未命中再按 uuid 前缀匹配;search_session 的 uuid 说明同步更新。
  • Layer 1 淘汰记录释放量与前缀缓存代价:compact.evict 回调事件新增 freed_tokens、break_index、invalidated_tokens、tokens_after,debug 日志同步输出,可看出一次淘汰省了多少 token、从第几条消息起 provider 缓存要重写。淘汰后的重新计数移到回调之前。
  • Layer 0 工具批预算与 Layer 1/2 共用同一工作窗口:enforce_tool_batch_budget 之前用 provider 的 context_window,设了较小的 compact_token_limit 时单批工具结果仍按大窗口放行;现在用 working_context_window(context_window, compact_token_limit)。
  • 上游流式返回内部错误时重试,不再直接结束运行:Anthropic 在 HTTP 200 之后用 SSE error 事件报的 api_error(内部错误)之前被判为不可重试,也不切 fallback,headless 的 delegate worker 一碰到就以 [Run failed: ...] 退出,主模型只能自己重跑。现在它和 overloaded_error 一样按上游故障处理:首包前切 fallback,流中途在同一模型上重发。另外,SSE 帧解析失败(json.JSONDecodeError)此前只在流中途会重试,首包前也改为可重试。两处都按结构化信号(error.type、异常类型)判断,不看报错原文。
  • 交互 CLI 的 Ctrl+D 要连按两次才退出:此前按一次就离开会话。Ctrl+D 同时也是终端的 EOF,误触一下会把正在跑的回合和输入一起结束。现在第一次只在状态栏提示 Press Ctrl+D again to exit,0.8 秒内再按一次才退出;超时提示消失,下一次又从第一次算。/exit 仍是一次退出。
  • search_session / search_memory 的工具说明补上检索边界:search_session 写明旧工具结果用 role="tool" 再按命中的 [uuid] 取全文,notes 命中只是当前文件,重写后的上一份不在索引里。search_memory 写明不搜本会话 JSONL 和 notes。<context_window> 未加长。
  • save_memory 新增可选参数 description,作为 MEMORY.md 索引行的 hook:之前 hook 被写死成 title,索引每行都是「标题 — 标题」,看不出什么时候该打开。不传时用 content 的第一行。自动抽取的记忆也用同样的默认值。
  • search_memory 结果按来源分层排序:memory → memory_candidate → conversation,同层内按相关度排序。打分同时匹配 title + description,取较高者。此前几千字的对话归档块包含常见双字词的概率高,经常排在精炼记忆前面。
  • 记忆 prompt 补上仓库外的环境事实和实验结论:reference 涵盖服务端口、共享目录、重启脚本、外部 API 实测限制;project 涵盖费力得到、仓库中没有记录的实验结论。此前长程会话把这些事实只写进只属于本会话的 notes.md,换个会话就搜不到。
  • 换窗后从 <session>.notes.md 抽取跨会话记忆:MemoryExtractHooks.on_post_compact 把 notes 交给 aux 模型抽取,结果写入 memory_candidates/,evidence_refs 指向这个 notes 文件。notes 内容和上次抽取时相同就跳过(reactive compact、notes 重写失败的情况)。

fixes

  • 并行 analyze_image 不再把图片插进同一轮的 tool 结果中间:analyze_image 的像素走一条跟在自己结果后面的 role="user" 消息。同一条 assistant 还并行调用了别的工具时,图片就夹在两条 role="tool" 中间,网关转成 Anthropic 格式后报 400:tool_use ids were found without tool_result blocks immediately after。两条结果其实都在,只是不挨着,补占位修不了,恢复路径最后把整段工具历史剥掉了。现在 format_tool_results 按「结果、占位、图片等附带消息」的顺序写入;已经写进历史的这种形状,由每次请求前都会跑的 sanitize_messages 把本轮结果挪到最前,缺的结果在同一处补占位。
  • Langfuse 上传 analyze_image 的图片不再报 Incorrect padding:工具结果里的 data:image/...;base64,... 被 bound_langfuse_value 截到 4000 字再拼上 ...[truncated]。截断后的 payload 长度不是 4 的倍数,Langfuse 仍把它当媒体去 b64decode,终端打出 Error parsing base64 data URI。现在能解码的 data URI 原样上传(Langfuse 会换成短的 media reference);解不开的换成不含 data: 的占位,解析器不再打这条错误。
  • apply_patch 的 context not found 能说出是哪种不匹配,hunk 顺序反了也能应用:长程会话日志里 apply_patch 错误率 6.5%(29/446),其中 17 次是 context not found,返回给模型的只有它自己发的那一行,分不出缩进错、行不存在、还是块写在了上一个 hunk 之前,三种修法不同。现在报错附带分类和行号,但不引用模型没读过的文件内容:同样文字但缩进/空格不同时给出行号,整块逐字存在但都在上一个 hunk 之前时提示按文件顺序排,否则提示重读文件。块在文件里逐字只出现一次时,即使 hunk 顺序反了也直接应用(精确匹配,不做空白/引号 fuzz);出现多次仍报错,两个 hunk 改动重叠时由 applyDiff 拒绝。17 次里有 6 次属于这一类。同时修正「块不连续」提示里的行号,此前指向块的起始行而不是断开的那一行。
  • execute 及几个文件工具在长任务和慢盘上的明显错误:
  • POSIX 上命令改为经环境变量交给 /bin/sh(eval "$AGENTICA_COMMAND",执行前 unset),不再作为 sh -c 的 argv。Linux 的 pkill -f <pat> 会匹配到执行它的那个 sh -c '<cmd>',把自己的 shell 杀掉,pkill 之后的命令都不执行,返回 exit -15;日志里 18 次 -15 全是这种情况。OS 沙箱与后台命令同样处理,Windows 不变。
  • execute 超时不再丢掉已经打印的输出,TimeoutError 里带上超时前的输出。
  • read_file 的 256KB 上限改为限制本次返回窗口的大小,不再按文件大小拒绝:此前对超过 256KB 的文件,limit=1 也会被拒绝,并被引导去用 tail。超出上限时提示减小 limit。
  • glob / grep 超时时附上超时前已找到的结果;glob 超时后,后台遍历线程在下一个匹配处停止,不再在网络盘上继续扫描。
  • wait 传入未知 id 时只列出仍在运行的 id 和最近 5 个 id,不再列出本会话启动过的全部 id。
  • 长程任务里几类瞬时模型错误不再直接终止整轮 run:从长程会话日志逐条归因。① 流式请求以 SSE error 事件下发的失败不带错误状态码,现在按响应体结构化的 error.type 分类(server_error / overloaded_error / rate_limit* 等);流式消费端(首个 chunk 之后)此前只做文案匹配,现在和请求端共用同一个分类器,server_error、限流、StreamEndedError(Responses 流没收到终止事件)在本轮内重发,而 400 不再因为报错里碰巧有 timeout 之类字样被重发。② 上下文溢出补上 exceeds the context 措辞,能进 reactive compact。③ 429 优先按 Retry-After 等待,缺失时从 15s 起退避(封顶 120s),此前 1-3s 重试总落在同一个限流窗口里。④ 连接类故障发生在最后一个候选模型(含未配置 fallback)时,按可重试处理,而不是「切下一个 fallback」——那时已经没有下一个了。
  • 调错工具时的反馈能让模型自我纠正:调不存在的工具(日志里有 Bash、ToolSearch、patch)此前只回 Could not find function to call.,现在回被拒的名字和可用工具清单(unknown_tool_error)。参数名写错时不再把 pydantic 的 ArgsKwargs(...) 整个调用 repr 塞给模型,改为列出该工具接受的参数名。Ollama 此前把被拒的调用回成不带 id 的 user 消息,该 id 随后又被补一条「执行可能被中断」,模型同时收到两条矛盾反馈;现在和其他 provider 一样以 role="tool" 回答原 id。
  • 流式请求里以 SSE error 事件下发的 thinking 签名拒绝也能恢复:网关先回 HTTP 200 再推 error 事件时,SDK 抛出的是 status_code == 200 的 APIStatusError,上一条的「状态码 400」判定不成立,长任务整轮失败退出。现在请求被拒的判定同时接受异常 body 里结构化的 error.type == "invalid_request_error"(_is_request_rejected)。
  • thinking 签名被拒的恢复改按请求形状判定,不再匹配报错文案:e58210a5 靠报错里的 Invalid signature in thinking block 等字样识别,但不同上游和中转代理对同一种拒绝的措辞各不相同(例如 blocks in the latest assistant message cannot be modified),换一种说法就漏掉,整轮直接 400 退出。现在只看两件事:状态码是 400,且这次请求回放了 thinking / redacted_thinking 块(carries_signed_thinking)。满足时把历史改写成共用形状重发一次。改写后请求里已没有 thinking 块,所以每次调用最多恢复一次,再 400 原样抛出;同一 run 后面的工具轮如果回放新签发的 thinking 又被拒,仍可再恢复。由别的原因引起的 400 恰好撞上带 thinking 的请求时,代价是多发一次请求、丢掉 thinking 历史。删除只被测试读取的 LoopState.thinking_history_sanitized_done。
  • CLI 下的后台记忆抽取与纠错判定从未真正执行:CLI 每轮通过 run_stream_sync 用一次 asyncio.run 跑完;MemoryExtractHooks / ExperienceCaptureHooks 用 create_task 挂在这个 loop 上的后台任务,在本轮结束、loop 关闭时被取消,抽取还没发出 LLM 请求,memory_candidates/ 一直为空。现在后台任务提交到进程级常驻 loop(agentica/utils/background_loop.py),并使用 Model.detached_copy() 得到的独立模型副本,避免 Runner 在本轮结束时关闭 aux client 时连带关掉后台请求。flush_pending() 仍可从任意 loop 等待这些任务完成。
  • 空闲时手动 /compact(CLI 与 Web)不再跳过记忆/经验 hooks:两处都读取 agent._run_hooks,而它在每轮结束后就被清空,空闲时总是 None,on_pre_compact / on_post_compact 从未触发。改为读取 agent._default_run_hooks。

[1.5.0] - 2026-10-22

breaking

  • Langfuse 改为每次 Agent.run 一条根 Trace,删除 OpenAIChat.langfuse_trace_name:根 observation 类型为 AGENT,Input/Output 分别是用户请求与最终回答。每次真实模型请求(含 retry/fallback)是其子 GENERATION,每次真实工具执行是其子 TOOL。Hook 全部不上报:生命周期回调和模型、工具步骤重复,空实现还会撑开 Trace。这些子 Observation 都挂在同一条 Trace 下,不再另开 Trace,也不再汇总进根 metadata。OpenAIChat 使用标准 OpenAI client,不再使用 langfuse.openai.AsyncOpenAI。
  • num_history_turns(AGENTICA_NUM_HISTORY_TURNS / settings.num_history_turns)默认由 20 改为 None;WorkingMemory.get_messages_from_last_n_runs 的 truncate_tool_results 默认由 True 改为 False:add_history_to_context=True 且未显式设置轮数的 Agent / DeepAgent 不再只重放最近 20 轮,而是重放当前上下文窗口内的全部轮次,更早轮次的 tool 结果也不再每轮截成 2000 字符。单次请求的历史 token 会随窗口增长,统一交给 Layer 1(EVICT_THRESHOLD_RATIO = 0.8 的 evict_context)和 Layer 2(95% 的 auto_compact)按 token 水位回收;需要旧行为的调用方显式传 num_history_turns=20。此前窗口内满 20 轮后,runs[-20:] 会把带 <context_window> / <session_notes> / <dropped_span> 的窗口首轮静默滑出上下文,并且每轮都改写历史前缀,使 prompt cache 失效。docs/api/agent.md、docs/concepts/agent.md、docs/guides/config.md、.env.example 中过时的默认值一并修正。
  • 移除 Model.supports_replayed_tool_history;PersistMixin.repair_unanswered_tool_calls 去掉 anthropic_blocks 参数;history_filter.strip_tool_artifacts_from_memory / elided_tools_notice / summarize_elided_writes 删除,由 to_portable_history / make_history_portable 取代:见下方 fixes 第一条。自定义 Model 子类不再需要声明这个能力位;直接调用这几个函数的代码改用新函数。
  • 删除 Layer 2 的「先催模型写 notes、推迟换窗」机制:Runner._claim_notes_fallback、CompressionManager.fallback_claimed / compact_token_floor、token_budget.fallback_text、CompressionManager.window_started_at、notes.notes_are_fresh / can_author_notes / fallback_buffer_tokens / AUTO_COMPACT_FALLBACK_BUFFER_RATIO 一并移除;remaining_text / remaining_message 去掉 notes_path 参数。notes 改由 harness 在换窗时自动重写,见 fixes。

fixes

  • Langfuse 5.x tracing no longer fails before agent execution with 'LangfuseSpan' object has no attribute 'update_trace':langfuse_trace_context 改用 5.x 的 propagate_attributes(...),把 trace_name、session_id、user_id 和 tags 写到用户请求的根 span,最终回答直接写回同一个 span。agentica[langfuse] 的最低版本提升为 5.0.4;不再调用已删除的 LangfuseSpan.update_trace() 与 Langfuse.update_current_trace()。
  • /resume 列表直接标出 session 所属 project 与 work dir:普通项目内列表和 /resume all 现在每条都会显示项目目录名、完整工作目录(home 下路径缩写为 ~)以及已记录的 profile;旧 session 无法恢复目录时明确显示 unavailable,不再只靠问题预览猜它属于哪个项目。
  • /model 来回切换不再白白丢掉 thinking 签名和 prompt cache;切 profile 后 delegate、压缩阈值、工具上的模型都跟着走:此前 /model / /config set 一换模型就立刻把历史改写成共用形状(删掉签名过的 thinking、reasoning_content、provider_data),不可逆;A→B→A 中间一次请求都没发,回到 A 时历史已经被删过,签名回不来,整段上下文的缓存也作废。现在 ensure_history_portable 等 input guardrail 通过、且这次请求确实会回放 working memory 后才改写;被拦截的请求和显式 messages= 调用不再误删未发送的历史。Agent._history_model_identity 记录历史归属模型(适配器类型、id、base_url)。指针和配置仍在切换当下由 /model 与 /config set 共用的 _rebind_live_model 同步:compact_token_limit、delegate 的 _session_profile、继承 agent 模型的 Browser/Video 工具都会切到新 profile;状态栏重新测量 working window,不再拿 provider window 当分母。
  • 旧会话留下的超大 notes.md 不会再让换窗时的 notes 请求超长或卡住换窗:notes_instruction 把旧文件放进 <current_notes> 时没有截断,之前追加写到 47KB / 98KB 的文件在窗口 95% 时整份塞进去,请求超长失败,文件也就永远等不到那次能把它缩短的整份重写。现在和注入时一样按 _NOTES_INJECT_LIMIT 首尾截断;notes 重写最多等待 120 秒,超时直接保留旧文件并由 <dropped_span> 承接换窗。
  • Anthropic 在工具结果回送时拒绝刚返回的 thinking 签名,不再让整轮直接失败:通过 Anthropic 兼容代理实测出现同一 claude-opus-5-5 工具轮的下一次请求报 Invalid signature in thinking block;原样重试仍会确定性失败,整段剥掉工具历史又会丢失已经完成的读取和命令结果。现在 Runner 识别该结构错误后,把 working memory 与 in-flight 消息转换成共用的 portable shape:只移除绑定 provider 的 thinking、reasoning_content、provider_data / checkpoint,完整保留 assistant.tool_calls 及对应 tool results,然后在同一模型上重发一次;重建时同步映射原输入消息 ID,working_memory.messages 不再漏掉本轮工具轨迹;第二次仍失败时原样抛错,不进入循环。流式和非流式路径均覆盖。
  • 流式请求连不上主模型时会切到 fallback 模型:response_stream() 是惰性生成器,请求和连接错误、503、429 都发生在取第一个 chunk 时,而 _call_with_retry 只包住了创建生成器那一步,所以流式(CLI 默认)下 fallback 链从来没生效过,主模型断连直接报错。现在在 _call_with_retry 里先取到第一个 chunk 再返回,建流失败和非流式一样走重试与 fallback;已经输出第一个 chunk 之后的错误仍交给调用方,避免 fallback 重复输出。同时,超窗触发的 reactive compact 重发不再占用一次 max_api_retry 重试次数:此前在默认 max_api_retry=1 下,compact 成功后循环直接结束,报 LLM call failed across 1 model(s),压缩后的请求根本没发出去。
  • 长会话的自动压缩从不触发,最后撑爆窗口:压缩各层按本地 count_tokens(tiktoken 估算)判断水位,但这个估算看不到 provider 侧另外计入的部分,比如 OpenAI Responses 回放的加密 reasoning 项。线上一个跑了 9 天的会话(gpt-6.1-sol,1.05M 窗口),同一个请求本地估约 640K,网关计 1,047,795,所以 75% 提醒、0.8 evict、95% compact 一层都没触发。新增 agentica/compression/calibration.py:各 adapter 把 provider 报告的整段 prompt 大小(fresh + cache read + cache write)写进 Message.metrics["context_tokens"],ContextCalibration 用它和同一请求的本地估算求比例,之后的估算都乘上这个比例。比例只会往上调,本地估高了还是保持现状,最多早一点压缩。比例存在 Model 对象上,/model 换模型后从 1.0 重新开始。evict 仍按本地 tokenizer 计算能省多少,对应的窗口按同一比例缩小。context.usage 事件里报的也是校准后的数。
  • 流式 error 事件报上下文溢出时,没有进入 reactive compact:OpenAI SDK 把 Responses 流里的 error 事件抛成 APIError(message, body=error)。str(exc) 只有一句人读的话(Your input exceeds the context window of this model…),context_length_exceeded 放在 exc.code 上,所以 PROMPT_TOO_LONG_HINTS 匹配不到。线上因此连续报错 7 轮,卡了约 3.5 小时,最后靠用户手动 /compact 才恢复。现在由 LoopState.is_prompt_too_long 先看结构化的 code,再退回到原来的文本提示。流式和非流式两处判断都改用它。
  • CLI 内置的 cron job 跑在交互会话的 session 里:build_cli_agent_factory 把宿主的 agent_config 原样交给 create_agent,里面带着 session_id。每次 tick 都会把宿主的 JSONL 当成自己的历史回放(监控 job 一开局就是 100K–370K tokens),把自己的对话追加进宿主的 JSONL(一个 9 天的会话里混进了 419 条监控轮次,search_session 的「最近用户问题」被它们占满),还会在宿主正在进行的轮次上调用 seal_incomplete_turn(133 次),插入「Session ended before the assistant replied」。现在 job 拿到的是去掉 session_id / session_base_dir / _resume_at_uuid / _fork_session 的副本,并传 enable_session_log=False:job 的历史本来就在 cron 自己的运行记录里,没必要每次 tick 再写一份 JSONL 塞进 /resume 列表。宿主的 dict 也不会再被 create_agent 弹掉 fork 相关的 key。
  • 长 notes 注入时只看得到最旧的内容:模型维护的 notes 一般是追加式的,线上两份分别有 47KB 和 98KB,而 <session_notes> 只注入 4000 字符,头部还占 2/3,留给最新进展的大约只有 1.3K,所以每次切窗后模型都得先 read_file 读一遍整个文件。现在上限提到 8000 字符,头 30%、尾 70%(clip_head_tail 增加 head_ratio 参数,其他调用方仍是 2/3)。
  • 大量自动消息会把人发的指令挤出 <dropped_span> 和「最近用户问题」:后台命令完成通知、peer 消息、job 报告都标了 automated,此前和人写的指令同等对待。一个窗口里有 30 多条后台评测报告时,预算超限就先丢掉了人的指令。现在 <dropped_span> 的淘汰顺序是:带 tool_calls 的过程旁白 → automated user 消息 → 人的指令和最终回答。list_user_questions 里 automated 条目最多占一半槽位,并标上 (auto)。
  • cron 的说明文字补充了监控长任务的做法:cron skill、cronjob 工具描述和 /cron add 的 prompt 改写规则都说明了:等待本会话启动的训练、评测、构建或 tmux/nohup 任务时,用 execute(background=True) 盯退出标记(不耗 token,结束后结果回到本会话),不要建分钟级的 cron 轮询。确实需要用 cron 盯某个终止状态时,prompt 里要写明到达后 pause 掉这个 job。job 的 agent 没有 list_agents / send_message / ask_user_question,prompt 里不要让它去做这些事。线上的对照:一个每 6 分钟一次的 cron 监控跑了 400 多次,训练结束后又空转了四天。
  • Claude 上调用被拒的工具(参数被 Layer 1 清掉、工具不存在、参数解析失败)不再让整轮 400 退出:此前 Claude.get_function_calls_to_run / parse_tool_calls 把拒绝原因作为普通 user 文本追加,tool_use 没有对应的 tool_result,下一次请求被 Anthropic 以 tool_use ids were found without tool_result blocks 拒绝;兜底的 _sanitize_tool_history_after_error 剥掉工具记录后,in-flight 消息以本轮的 assistant 旁白结尾,又被以 This model does not support assistant message prefill 拒绝,run 直接失败(会话 692116c3 实际发生:模型把被清掉的 apply_patch 参数占位原样发回)。现在拒绝原因作为带 tool_call_id、tool_call_error=True 的 role="tool" 消息回答它自己的 id,由 format_messages 并进本轮的 tool_result 消息,format_function_call_results 不再为这些 id 补「执行被中断」占位,模型能看到真实原因;_sanitize_tool_history_after_error 剥离后去掉末尾的 assistant 消息,重试从用户消息重新开始本轮。
  • 工具历史被拒、剥离后重试成功,这一轮的回答不再丢失:_sanitize_tool_history_after_error 把 in-flight 消息剥成纯文本后,列表比本轮开始时短,回合结束仍按 messages_for_model[num_input_messages:] 切出本轮新增,结果是空列表——回答没进 run 历史(下一轮重放时上一轮只剩孤立的提问)、也没进 /history 归档。现在剥离时置 context_collapsed,与换窗共用「整段存活对话即本轮状态」的持久化路径;剥离重建的历史消息是新对象,记入 LoopState.input_message_ids,归档不会把整段历史再写一遍。非流式路径剥离后重置 message_checkpoint,重试失败时按剥离后的长度回滚。
  • 被拒的工具调用写进 session log 时保留 is_error 与 tool_name:流式路径上被拒的调用不经过工具执行,没有 run_response.tools 记录,落盘走最小条目,此前既不带 is_error 也不带工具名,/resume 后它重放成一次成功调用。现在各 provider 统一用 Model.refused_tool_result 构造拒绝结果(带工具名与 tool_call_error=True),最小条目也写入这两个字段。Anthropic 网关实测接受连续的同角色消息(服务端合并),剥离后相邻的 assistant 旁白不会 400,因此没有另加合并逻辑。
  • session notes 由 harness 在每次换窗时自动重写,模型和用户都不用记得写:此前 notes 全靠模型自觉——95% 处注入一段催写并把换窗推迟约 4%,但催写要折进最后一条消息,长工具循环里经常发不出去;模型也常常不写,或者要先被告知文件路径;手动 /compact 之前更是没有任何提示。本会话 compact 时 notes 文件一直不存在就是这个原因。现在 CompressionManager.auto_compact(notes_request=...) 在切窗前调用 compression/notes_author.author_session_notes:用主模型、该窗口最后一次请求发出的 messages(system 前缀、tools、tool_choice、thinking 配置不变)末尾追加一条指令,流式请求一次,以 run_tools=False 只取正文,整份替换 notes 文件(临时文件 + os.replace 原子写入),已有 notes 会作为 <current_notes> 交给模型修订。前缀不变,所以这次请求读缓存:Anthropic 接口实测一次 /compact 为 cache_read=3715、新写 639、输出 207 token,换窗后下一轮无需工具即准确答出端口和用户约束。自动换窗与 /compact(CLI、Web)都走这条路径;/compact 时工作记忆里没有 system prompt,由新增的 Agent.get_messages_for_notes 按下一轮的方式重建 system + 历史前缀,否则这次请求与上一轮没有公共前缀、整段重写缓存;prompt_too_long 后的被动换窗和跨 provider fallback 前的换窗不发这次请求(同一 prompt 会再被拒,或窗口里还带着失败 provider 的 checkpoint)。请求失败或返回空时 notes 保持原样,照常靠 <dropped_span> 交接,换窗不受影响。CLI 在这段时间显示 🗜 compacting context…,换窗提示和 /compact 结果会说明 notes 是否已重写;<context_window>、25% 剩余提醒与 <dropped_span> 标题不再要求模型自己更新 notes。这次请求的 token 照常计入 /usage。
  • resume 到 Claude、/model 或切 profile 后,工具历史不再被整段剥掉:此前 Claude.format_messages 直接跳过 role="tool",也不把 assistant 的 tool_calls 渲染成 tool_use 块,于是 session log 统一落盘的 OpenAI 形状工具轮次在 Anthropic 接口上回放不了,supports_replayed_tool_history=False 让 resume 时整段剥成纯文本,/model 和切 profile 则无论换没换模型都剥(只留 20 行 <elided-tools> 写文件摘要),读过的文件、grep 过的调用链、跑过的命令和报错全部丢失。现在 Claude 适配层把 tool_calls 转成 tool_use、把 role="tool" 合进紧跟其后的同一条 tool_result user 消息(与原生块、修复用的占位结果共用一条,后续 user 文本也并入,不产生连续两条 user),已回答的重复结果和孤儿结果不上线;参数不是合法 JSON 的截断调用以空 input 回放(它的结果本来就是错误)。经 Anthropic 接口实测,reasoning_effort 为 low 与 high 时模型都能准确引用回放的工具输出。换模型时 make_history_portable 把 Claude 原生块改写成共用形状,只丢掉绑定在原模型上的 thinking、reasoning_content、provider_data、provider_checkpoint,工具轮次保留;/model 与切 profile 共用 model_identity(适配器类型、model id、base_url),三者都没变时历史原样不动,签名过的 thinking 和已缓存的前缀都保住。所以不再产生 <elided-tools>;旧会话里已有的标记在 /resume、/history 回放时照旧隐藏。
  • 一轮内的跨 provider fallback(Claude → OpenAI chat / Responses / Gemini)不再 400:/model、resume 会在切换前把历史转成共用形状,但工具循环中途的 fallback 直接把 Claude 的 in-flight 数组交给了兜底模型——tool_use / tool_result / thinking 原生块上线后被 chat 接口以 type must not be null、Responses 以 Invalid value: 'thinking' 拒绝,run 中途失败。现在 OpenAIChat / OpenAIResponses.format_messages 在发送前只把带原生块的那些消息改写成共用形状(claude_blocks_to_shared_shape),其余消息原对象透传,Responses 的 provider_data 等回放状态不受影响;同一结果重复出现时只发一条。实测 Claude 主模型 fallback 到 chat、Responses、GLM、Gemini,以及反方向(chat / Responses / Gemini 主模型 fallback 到 Claude)都能带着本轮工具结果完成回答。
  • Responses 的 raw output 只回放给产出它的模型和端点:provider_data 里的 reasoning item 带 encrypted_content,只有签发的模型能解密;从一个端点的 gpt-5.6-terra resume 到另一个端点的 gpt-6.1-sol 时整条请求被拒(The encrypted content ... could not be verified)。现在 _replay_provider_data 记下 replay_origin(provider、model id、base_url),_assistant_items 只在三者都匹配时回放 raw output,否则从 content + tool_calls 重建该轮(与 provider_checkpoint 的判定一致);没有 replay_origin 的旧记录按外来处理。实测 6 个 profile 两两 resume 36/36 通过。
  • Gemini 的工具调用在流式与非流式下都能跑:非流式响应里 tool_call.type 为 null,而 get_function_call_for_tool_call 要求 "function",调用被丢掉、模型被告知「工具不存在」;流式路径 build_tool_calls 只读已知字段,把 Gemini 放在 delta 扩展里的 thought_signature / extra_content 丢了,多步工具任务第二次请求被拒(Function call is missing a thought_signature)。现在非流式把空 type 归一为 function,流式把 delta 的扩展字段一并带在存下的调用上(Gemini 自己的签名原样回传)。另外,没有 extra_content 的调用(即由其他模型签发的)在线路上带 Google 文档给的占位签名 skip_thought_signature_validator,Gemini 才肯接受跨模型回放的工具轮次;其余 chat 端点忽略该字段(opus / glm / deepseek / hy4 / gpt 的 chat 端点实测均正常)。
  • 多次 compact 不再丢掉本窗口的交接:此前 <session>.notes.md 一旦非空,rollover_handover 就不再生成 <dropped_span>,_claim_notes_fallback 也不再要求更新 notes;同时 _fold_budget_fragment 拒绝往开头是 <context_window> 的 user 消息上追加,导致同一次 run() 跨多个窗口(长 do all、delegate)时 75% 剩余提醒和 95% notes fallback 静默失效,第二次及以后的 compact 只注入旧 notes,刚结束的整个窗口直接丢失。现在:每次 compact 同时注入 <session_notes> 与 <dropped_span>,carried_rows 只接力上一份 <dropped_span>,不再把 notes 复制进摘要;75% 剩余提醒只追加到 messages[-1](字符串内容的 tool 结果,或不是 idle /compact 占位的 user 消息),否则留到下一次请求,不改写更早的历史;<dropped_span> 超出条数或字符预算时先淘汰带 tool_calls 的过程旁白,优先保留 user 指令和最终回答。另外,apply_idle_compact 在换窗前把 model._agent_ref 绑定到当前 agent,/resume 或 /model 换了 Model 对象后、尚未 run() 就执行 /compact,也能找到 <session>.notes.md。
  • search_session 能检索工具调用参数和 tool_audit 记录,并能按 uuid 取回整条记录:此前 _entry_text 只读 content,带 tool_calls 的 assistant 行 content 往往为空,搜文件路径、命令都是 0 命中;429 切 fallback 时写入的 tool_audit 行被 _conversation_rows 排除;persist.py 落盘时把 tool 输出截在 2000 字符。现在索引 assistant 的工具名与参数、tool / tool_audit 的 tool_name;role="tool" 包含 tool_audit;落盘上限对齐 Layer 0 的 DEFAULT_MAX_RESULT_SIZE_CHARS(50000 字符,超过的结果在 Layer 0 已换成预览加落盘路径);每条命中和最近用户问题都带 8 位 [uuid] 前缀,search_session(uuid=...) 按前缀取回完整文本,前缀匹配多条时报歧义而不是任选一条。
  • 本轮调过 save_memory 时,MemoryExtractHooks 仍归档原始对话供 search_memory 检索:此前 MemoryExtractHooks._flush 一看到本批有 save_memory 调用就直接 return,跳过了后面的 _archive_extract_evidence,导致 auto_archive=False(默认)时 conversations/YYYY-MM-DD.md 完全不写,search_memory 搜不到这批对话原文。现在先归档对话原文,再跳过辅助 LLM 的重复提取。
  • CLI 底部 context usage 不再按占用率变色:263.6K/512K 51% 等百分比始终使用普通状态栏样式,删除 50% 黄、80% 红、95% 加粗红的阈值配色;数字和百分比仍照常更新。
  • content_filter 不再被流式路径误判为空响应或正常完成:网关返回 finish_reason=content_filter 时,流式和非流式都不再重试同一模型,而是立即切到下一个 fallback;整条 fallback 链都被过滤时才抛出 ContentFilterError,如实显示 Response blocked by provider content filter。流式已输出部分文字后收到过滤结束原因,也不会再把该片段标为完整答案。已有 break_reason 时,CLI 不再紧接着重复打印 Agent returned no content.。
  • OpenAI-compatible Claude 网关的中途 system 位置 400 可定点修复:遇到 role 'system' must precede an 'assistant' message or end the array 时,若最终客户端 payload 确有非法中途 system,只把该指令移到下一条 assistant 前(或数组末尾),结构校验通过后原地重发一次;开头的 system 前缀不动。若客户端结构本来正常,则不盲目重试,并记录角色序列和 system 索引供定位网关转换层。
  • 空回复提前结束的提示变短,并带时间:连续空回复时 CLI 原先打印一整句 “The model provider returned an empty response… send a follow-up message”。现在是 ⚠ Run stopped early (empty_response) - YYYY-MM-DD HH:MM:SS,下一行 No reply 3 times. Type continue or 继续.。
  • OpenAI Chat Completions 的输出上限字段无需维护模型名名单:max_tokens 被服务端以结构化 unsupported_parameter 拒绝时,会保留原值改用 max_completion_tokens 重发;反方向同样支持。成功协商的字段按 (provider, base_url, model_id) 记忆,fallback 每轮创建的新模型实例会直接复用,未来新增模型名无需更新代码,也不会每轮多付一次 400 往返。Responses API 仍固定使用 max_output_tokens。
  • 状态栏上一轮耗时超过一分钟不再写成 1803.0s:⏱ 拆成 30m3s,整点分钟是 16m;超过一小时仍带秒,3723s 是 1h2m3s,当前这轮还在跑时秒数会走。一分钟以内仍保留一位小数(12.3s)。右边的 Σ 会话累计时长不变。
  • 耗时不再补前导 0,也不再写成钟点:状态栏 Σ、⏱、spinner、Web 里 execute 旁的耗时、/ps 和后台完成报告都用 5m13s。5 分 3 秒是 5m3s,不再是 5m03s 或 5:13 / 03:18。/usage 和 trace 是 15m5s,不再是 15m 5s;超过一小时同样不留空格(1h5m)。会话结束的 Worked for 仍是带空格的 15m 5s,只是不再补成 15m 05s。整分、整小时省略 0 单位(5m、1h);超过一小时的 ⏱ 不再写 1h0m0s,只有秒是 1h3s。每轮结束线上的耗时也不再是 480.6s,480.6 秒写成 8m1s;一分钟以内仍是 12.3s。消息上的钟点(09:05)仍补零。
  • fetch_url 回显不再把整页显示成 1 lines:结果是一行 JSON(url / content / save_path),以前按这个字符串的换行数计数,一篇 README 也是 1 lines。现在数 content 里的正文行,一行写成 1 line;抓取失败且没有正文时显示错误本身。
  • execute 的后台说明不再说「结果只报告给用户、不会给你」:交互式 CLI 默认(deliver_background_results: true)会把后台命令的退出码和日志尾部交回 agent,旧说明恰好说反,wait 的说明也一样。现在按实际配置二选一:开着时告诉模型结果会作为新消息回来、可以直接结束这一轮;关掉时保持原话。
  • tmux / nohup / setsid 里跑的长任务有了配套做法:这类任务要比会话活得久,但 /ps 看不到,跑完也没人通知。execute 说明里新增一段:启动时让任务把退出码写进标记文件,并在同一步起一个 background=True 的只读监视循环——标记出现就带着任务自己的退出码结束,会话消失却没有标记就以 2 退出并打印日志尾部。监视会随会话结束,任务不会;重开会话后先读标记文件。附带的示例命令有测试实际跑过这两种结局。
  • /resume、/history 和 resume 列表只显示人说的话:另一个 agent 会话发来的消息、后台命令 / delegate 的完成报告,以前作为一轮「You」原样出现在回放里,也计入 picker 的 turns 和最近请求。现在这类轮次在 session log 的 user 条目上记 "automated": true(新增 RunConfig.automated_input、Message.automated,不发给 provider),回放时跳过,agent 随后的回答并入上一段;模型侧历史不变,仍能看到这些消息。用户从另一个会话转发过来的话(/send-message、attach)仍是人发起的,照常显示。运行中到达的后台报告也不再被套上 [User guidance received while you were working]。
  • peer agent 消息在终端里弱化显示:另一个会话的 agent 发来的消息从和用户输入同款的面板,改成缩进的暗色 ↳ <name>: … 一行;用户本人从别处发来的话仍是 ❯ 面板。这类自动轮次也不再覆盖本会话对外公布的「正在做什么」。
  • peer 消息不再被当成派活渠道:list_agents / send_message 的说明和 multi-agent skill 重写——自己的任务自己做(直接做、task、delegate、后台命令),结果直接回到自己手里;send_message 用于和不属于自己的工作协调(别的仓库或 checkout、用户在做的另一件事)。收到 agent 消息时的提示由「If it handed you work」改为「If it asked you for something」。tmux 里起第二个 CLI 只留给用户想单独盯着或接手的场景。

[1.4.17] - 2026-10-15

breaking

  • 顶层模块按领域收进子包。from agentica import Agent / RunResponse / Workspace 等公开符号不变;from agentica.config import AGENTICA_HOME 与 from agentica.peers import PeerSession 也不变。变的是子模块路径:agentica.hooks → agentica.agent.hooks,agentica.goals / checkpoint / aux_session 同样进 agentica.agent;agentica.run_* → agentica.run.*(run_response → run.response,其余同理);agentica.global_config → agentica.config.profiles,agentica.project_store → agentica.config.project(环境变量常量仍在 agentica.config,实现在 config/env.py);agentica.cost_tracker / provider_registry / auxiliary_router / think_scrubber / media → agentica.model.cost / providers / auxiliary / think_scrubber / media;agentica.git_state / worktrees / peer_conflicts → agentica.peers.git_state / worktrees / conflicts;agentica.workflow / swarm / critic / handoff → agentica.orchestration.*;agentica.document → agentica.knowledge.document;agentica.learning_report → agentica.experience.learning_report;agentica.diagnostics / attach → agentica.cli.diagnostics / attach;agentica.lsp_diagnostics → agentica.tools.lsp_diagnostics。run_doctor 改为惰性导出:import agentica 不再因此加载 CLI。
  • worktree 不再搬家、不上锁、不销毁占坑目录:隔离靠每次调用的 work_dir / path,会话身份留在原目录。new 返回路径;read_file / write_file / apply_patch / execute 增加可选 work_dir(连同 execute 的 cwd / background / spill),glob / grep 继续用已有的 path。删掉 use / main 搬家、git worktree lock 协议、forget+rmtree 救援、Agent.rebind_work_dir。登记项不再是 checkout 时 new 拒绝(先 remove 或换名),不把占坑内容当垃圾删。merge / remove 都要带 name=,只对那条路径操作。--worktree 仍是新进程的初始目录。漏传 work_dir 会写到会话目录——可观察,比 cwd 蒸发好修。
  • settings.hooks 改为具名多消费者 consumers[],删除单槽 command/events 与 AGENTICA_HOOKS_COMMAND:每个 consumer 现在必须提供唯一 name、argv command,并可独立设置 enabled/events;环境变量统一为 JSON 数组 AGENTICA_HOOKS_CONSUMERS。旧环境变量曾用 command.split(),会把 macOS 的 Library/Application Support 等含空格可执行路径静默切碎;新协议不解析 shell 字符串,也不保留两套配置语义。

fixes

  • API 错误按状态码和异常类型决定重试还是切 fallback,不再只看报错原文:分类用到的 openai 异常在判断时才导入,import agentica 和 CLI 启动不会因此提前加载 openai SDK。408 / 409 / 429 / 504 同模型重试;其它 5xx 直接切下一个 fallback,不再在同一模型上空转;400–499(除上面三个)既不重试也不切 fallback,原样抛出。超时类型(APITimeoutError、httpx.TimeoutException、TimeoutError)即使消息里没有 timeout 字样也重试;连接类型(APIConnectionError、httpx.TransportError、ConnectionError)即使消息里没有 connection 字样也直接切 fallback。状态码优先于正文:401 的消息里写着 timeout 或 503 也不会被当成可重试。OpenAIChat.timeout 现在也可以传 httpx.Timeout。
  • 以文本文件路径开头的输入,回显不再自动加上 @:/path/to/file.md 解释 这种开头就是一个已存在文件的句子,以前会被改写成 @/path/to/file.md 解释 再画进对话。@ 只是让 parse_file_mentions 把文件内容注入给模型的语法,模型自己看到的正文里这个符号本来就会被剥掉。现在回显保持原文,文件内容仍注入给模型;图片和粘贴块沿用原来的附件、展开与 steer 行为。
  • 网关返回空的 200 不再悄悄结束这一轮:LLM 代理偶尔回 HTTP 200,但没有正文、推理、tool call,也不抛异常(一个 494 次请求的会话里出现 5 次,全在同一天,长时间空闲后的第一次请求出错率 13.6%,其他情况 0.5%)。三层重试都不会触发:没有异常,流里也没有错误,finish_reason 也不是 length。于是 loop 当成模型自己说完了:CLI 显示 <no reply>,一个要跑几小时的训练任务就停在半路,其中两次正好停在 wait 返回训练完成之后。现在 assistant turn 什么都没有时,原样重发同一个请求,最多重试 2 次,每次打 WARNING;空 turn 留在历史里(它记着这次调用的用量),发请求时会被略过,所以重发内容和失败那次完全一样。计数只算连续的空回复,中间有一次正常回复就清零,长任务里零星出现的空回复不会累计用完次数。连续 3 次都是空的,设 break_reason="empty_response"(新增 RunBreakReason.EMPTY_RESPONSE),CLI 显示「Run stopped early」,不再看起来和正常结束一样。只要有一个可见字符、只有推理或 thinking,或者 finish_reason == "length"(那条路有自己的恢复),都不算空回复,正常回答仍然只发一次请求。
  • 回答在 max_tokens 下始终写不完时,不再当作完整结果返回:恢复次数用完、最后一跳仍是 length,现在设置 break_reason="output_truncated"(新增 RunBreakReason.OUTPUT_TRUNCATED),is_complete 为 False,CLI 显示「Run stopped early」,subagent 的状态是 truncated。以前这种情况 is_complete=True,在真实 provider 上(opus-5-5 / glm-5.3 / deepseek-v4.1-flash,max_tokens=1500,15 道长答案题)有 5 次的 content 是空串,其中一次前面已经写出 5056 字。最后一跳只有推理、没有正文时,content 改用续写链里最后一段有正文的片段(只看最后一轮工具调用之后的部分)。各段不拼接:从三个 provider 收集到 11 个续写边界,全部断在句子中间;3 个把上一段结尾逐字重写了一遍(27–235 字,其中一处是整条列表项),3 个开头插了 ## 7. …(continued)、Continuing from where I left off. 这类元叙述。直接拼接,11 个边界里有 6 个能看到接缝;要去掉只能做字面匹配,而换个说法的复述连字面匹配也认不出来。只取单段至少不会自相重复。
  • 没配 max_tokens 时,OpenAI 兼容路径按模型目录的输出上限发请求,不再吃网关默认值:优先级是用户配置 > 模型目录 > 网关默认。目录来自 models.dev 的 limit.output,现在随 context_window 一起写进 model_pricing_cache.json(max_output_tokens),CLI 每次启动都会刷新。以前请求里根本不带上限,网关给 claude-opus-5-5 的默认值是 20000,高强度推理一跳就能把它花光、一个字都不输出。在出事那次委托的 144K 上下文上重放:20000 下 3 次里 2 次空转,目录的 128000 下 6/6 都正常给出 tool call。目录描述的是模型,不是具体部署:自建的 DeepSeek-V4-Flash(max_model_len=163840)会拒绝目录里的 393216。被拒时去掉上限重发一次;重发成功才说明是上限的问题,从此不再发;重发也失败就原样抛出真实错误,上限保留。用户自己配的上限永远原样发出,既不会被去掉也不会被调高。只出推理就被截断、且上限由 agentica 选择时,下一跳把上限翻倍(不超过目录上限)后原样重发,不再插提示;上限已到顶或是用户配置的,才退回「直接走下一步」的提示。
  • 输出额度全花在推理上时,下一跳不再被网关 message has no content(4000)掐掉:一次 max_tokens 打满(实测 20000)、既没有可见文字也没有 tool call 的 assistant 消息,发送前 reasoning_content 会被剥掉,线上只剩 {role: assistant, content: null}(content: "" 也一样被拒)。网关返回 400,整轮退出:一次 delegate 跑了 31 分钟,一行代码都没写成就停在这里。现在 OpenAI 兼容路径的 format_messages 发送时直接略过这种空 turn,和 Anthropic 路径一致;会话历史本身不改,带 tool_calls 的空 content 也照常发送。max_tokens recovery 也区分了两种情况:截断前有可见文字时,仍然提示「Continue from where you left off.」;只剩推理时,提示模型这一跳没有留下任何输出、不要从头再分析、直接调用工具或给出答案。这句提示不提「推理」:在网关上重放出事那次的完整上下文,提到推理的措辞有 8/30 次被 content_filter 拦下,其他措辞 0/38。
  • 交互 CLI 后台查 git 不再留下过期的 .git/index.lock:peer 循环大约每 10 秒跑一次 git status -sb --porcelain(git_state.collect),用来给别的会话发布分支和脏文件。git status 会顺手拿 index 锁刷新索引;CephFS 上这条命令要 2 秒左右,而超时只有 3 秒,subprocess 一到点就 SIGKILL,git 来不及删锁。之后在同一目录 git pull / commit 就报 File exists。现在这些后台调用带 --no-optional-locks(git_state._git 和 worktrees._git),不再为刷新索引占锁;状态采集的超时从 3 秒改为 10 秒。
  • 回答中输入以 / 开头的文件路径会进队列而不是 steer:/apdcephfs_qy3/share_7435715/data/models/Qwen3.5-4B-Base 是我刚下载的模型权重 这种路径不是 slash 命令。命令只能是单段 /name(/cron、/compact extra 仍排队);路径 token 里再出现 / 时 Enter 走 steer,补全菜单也不再把它当成命令(Tab 不会把缓冲区改写成 /agent)。
  • 缓存保活失败只写日志,不再冒进 CLI 对话:空闲时刷新 prompt cache 的后台 ping 如果被网关拒绝(4008),以前走 logger.warning,控制台 handler 或 /debug 会把原始 Error code: 400 画进已经答完的那一轮下面。现在 log_file_only 只交给文件 handler。回答本身不受影响。
  • Linux AppImage 在没有网、也没有 agentica-gateway 的机器上第一次打开,不再弹出写着 “could not start” 的错误框:AppImage 目录(appimage.github.io#5117)在 firejail --net=none 里截图,这句话会被判失败。现在留下说明窗口:第一次要下载 uv、Python 3.12 和 agentica[gateway],这次没下完;连上网再打开,或自己 pip install "agentica[gateway]"。uv 的安装也不再是 curl | sh:断网时 curl 失败、空的 sh 仍退出 0,于是报 uv installer finished but … is missing。现在先把安装脚本落到临时文件再执行,下载失败就是失败。
  • AppImage 不再依赖 libfuse2,文件名去掉 linux:electron-builder 26 默认的 runtime 要系统的 libfuse2 和 glibc。toolsets.appimage 固定为 1.0.3(静态 runtime)。产物名从 agentica-desktop-linux-x86_64.AppImage 改为 Agentica-x86_64.AppImage(目录认为文件名里的 Linux 没有信息量)。只给 AppImage 加 --no-sandbox:旧 runtime 本来就会加;静态 runtime 只在没有 user namespace 时加,而目录测试开了 user namespace 再套 firejail,chrome sandbox 起不来。deb 的文件名和 sandbox 不动。Electron 本体仍链接系统 glibc,这一条目录备注还会在。
  • Python 3.10 上 import agentica 直接 SyntaxError: unterminated string literal:agentica/agent/printer.py 打印工具调用行时,把一个跨多行的函数调用写在 f-string 的 {…} 里。这是 3.12 才允许的语法(PEP 701),而项目声明 requires-python = ">=3.10"。CI 只跑 3.12,所以一直没暴露。现在先算出调用行再插进 f-string。examples/self_evolution/01_self_evolution_e2e.py 在 f-string 表达式里写 '\u2713',同样只有 3.12 认,一并改成字符本身。
  • CLI 状态栏转圈耗时不再写成 execute (118s):超过一分钟拆成 1m58s / 16m / 1h2m,避免四位秒数看起来像任务编号。一秒以内的阶段仍是 2s。
  • worktree.root: sibling(以及绝对根)下,死登记项不再是 new / remove 互相指点:remove / check_removable 不再用 _entry_for_path 从树路径的父目录反查——sibling 树在仓库外,父目录不是 git 仓库,git worktree list 明明还列着(prunable)工具却说「不是登记项」,而 new 仍拒绝「先 remove」。现在 binder 把 find 到的 entry 和会话所在仓库传下去,exists 以仓库里的 listing 为准。清死登记项用 unlock + git worktree prune --expire now:prune 是仓库级的,会一并注销其它当前不可见的 checkout(挂载暂时不可用、目录被人挪走),不只是死掉的——文件与分支都保留,但那棵 checkout 回来后 .git 链接已失效,要 rm .git 再 worktree add 才能用。这个代价是有意接受的:此处分不清「此刻不在」和「永远没了」,而更窄的按路径 remove -f -f 会删掉路径上的残留文件,正是这条路径必须避免的。
  • worktree merge 不再把「已经并进 main」当成错误,也不再替 git 翻译一遍拒绝:merge 在 commits == 0 时是成功态(先前已合,或从没提交过),随后删掉 checkout。以前抛 has no commits that main does not already have,模型学到 merge 是死路,就用 execute 跑 git worktree remove。显式 remove 只拦所有权(wt/*),脏树交给 git;未合入的提交留在分支上(git branch -d 会拒)。git 原文原样透传(含它广告的 --force)。--worktree 启动的进程若 cwd 就是那棵树,remove 拒绝——删的是进程自己的目录。退出时的自动清理才用 has_unique_work(那是猜测,不是指令)。
  • 工具要说这是目录没了,不是命令写错:execute / 文件工具的 work_dir 不再甩 [Errno 2] No such file or directory: '<dir>'(模型会当成自己命令写错);_git 不再把 ENOENT 报成「git 没装」;ensure 从最近存活祖先解析仓库;status 不再把已删目录说成「不是 git 仓库」。
  • new(name="main") 拒绝;exists=False 的 remove 只清登记、不删路径:main / master 是本地基准分支名,不是任务。Worktree.exists 表示「该路径是一棵真 checkout」(toplevel == 路径):缺目录标 (directory gone),占坑裸目录标 (not a checkout)。new 拒绝而不是 rmtree 清坑。remove 对这类登记走 unlock + git worktree prune——git worktree remove 会 rc 128(缺 .git)或被遗留锁挡住,而 prune 不碰路径上的文件。先 remove 再 new:路径空了就能建;路径上还占着裸目录则改口「move it aside」,不再绕回 remove。
  • 会话 cwd 被删时 status 直说从主 checkout 重启:目录不在就报 gone 并指向 agentica --resume,不再假装还能在这里列 worktree。main_root 从最近存活祖先解析。
  • 回答过程中粘贴长文本 + 回车,模型只收到 [Pasted text #1: 7 lines -> …] 一行占位、不知道那是什么:粘贴块的展开发生在队列的消费端(app.py process loop),而 mid-run Enter 走 agent.steer() 直接绕过了那条路——所以 steer 收到的永远是裸占位符。实测现场:同一段文字 steer 进去模型说「只看到一行占位,内容请再发一次」,用户重发一遍(空闲轮入队)就是完整正文。排队那条路(Tab / 空闲回车)不受影响——它进 pending_queue,由 process loop 消费时照样展开,只是延迟到那一轮才发生;先前一版排查里「_queue_next_turn 也漏了展开」的判断是只看生产端得出的,不成立。修法不是在 steer 里也内联:占位符存在的理由就是粘贴块可能是几百行日志,而 steer 注入的是正在运行的 run,之后每一轮请求都会重放它,内联等于把这笔开销按轮计费。现在保留句柄、补一句说明它是什么(annotate_paste_refs):占位符带的是绝对路径,模型本来就能 read_file 读——缺的只是没人告诉它可以。顺带修掉同一条路上的第二个 bug:state.pasted_files 此前只由空闲轮 clear(),mid-run 粘贴会把条目留下,于是下一条手敲的消息被标成「(1 pasted block, 8 lines total)」而它根本没粘贴东西;steer 被拒(TOCTOU 回落入队)时不清,因为那笔账归即将入队的那一轮。占位符正则收归 attachments.PASTE_REF_RE 一份,两条输入路径不会再各拿一个同形状的 pattern 漂移。测试 tests/cli/test_cli_queue.py。
  • CLI 技能 slash 命令先回显输入,再打 Skill activated:/handoff 这类 auto-command 以前一匹配就 _cprint("Skill activated: …"),写在 display_user_message 前面,transcript 里先出现激活提示、后出现 ❯ /handoff。现在跟 steer/queue 一样:先画输入面板,状态行跟在下面。
  • agent 现在能自己看图:内置 analyze_image,不用再 @ 提及、也不会去写 OCR 代码:此前底模的读图能力只能由用户在输入时附加图片触发,模型手上没有任何读图工具——实测一条 session 里用户贴了张裸路径截图,k3(supports_images=True,能看图)因为上下文里只有一行路径、工具表里 23 个工具没有一个能读图,于是依次试了 tesseract(缺中文包)、自己写 tmp/ocr_vision.swift 调 macOS Vision 框架才读出文字。这不是模型蠢,是我们没给出路。现在 BuiltinVisionTool(tools/builtin/vision_tool.py)进默认工具集,analyze_image(image_path_or_url, question) 一个入口三级路由,按能力决定、不猜:底模能看图就把像素直接给它(0 次额外 LLM 调用);不能看则交给显式配置的 vision_model 描述;都没有才退到本地 imgocr 出文字。OCR 不单独暴露成 tool——走哪条路是能力问题,不该让模型替我们推理,它只问一次、拿到这套安装能给出的最好答案。
  • 图片经工具回到底模走「跟发 user 消息」,不塞进 role="tool":实测三个网关,把 image 块挂在 tool result 上的结果是——一个直接 400(each tool_use must have a single result),一个返回 200 而模型凭空编造了它从未见过的图的内容(把 TR-6620 说成 TF-920,还描述了字体颜色),只有一个真的转发了。「发一次看有没有报错」因此是不可用的探测,而按 provider 白名单走又要长期维护。现在工具返回 multimodal_tool_result 信封,Model.run_function_calls 把文字留在 tool result、图片挂到紧随其后的 role="user" 消息上——这是所有 vision API 的第一等公民用法,实测三端点 6/6 全中。底模不支持图片时只发 text_summary,不发图:被拒的 tool result 已经进了 canonical history,之后每一轮都会重放同一个失败。
  • Anthropic messages 接口上这条跟发消息曾被当成「丢了 id 的 tool 结果」吞掉:format_function_call_results 按到达顺序把没有 tool_call_id 的消息配给本轮的 tool_use id,而跟发的图片消息正好没有 id,于是被折进 tool_result block,像素根本没以 user turn 到达模型。实测 opus-4.8 当时的回答是「我看不到图片的像素内容……不想猜给你一个错的值」——它诚实地说了看不见,而同一形状在 chat_completions 上的另一个模型是直接编造。现在 Message._tool_media 标记这条消息,Anthropic 路径据此把它排除在 id 配对之外、作为独立 user 消息跟在 tool_result 之后。同时 Claude.add_image 补上两种它本来就该认的形状:{"url": ...} dict(gateway 与 analyze_image 都产出这个)和 data: URL(此前只认 http(s) 与本地路径,dict 直接 TypeError)。
  • 三条 wire 全部端到端实测通过(每条都用现成生成的图、随机验证码,并要求同时读出「字符串」与「图形形状」两个独立变量以排除蒙对):chat_completions(k3)读出 CC-3310;anthropic messages(opus-4.8)读出 AN-7142 / AM-8842;responses(gpt-5.5,wire_api: responses)读出 RS-9276,并在两组双变量用例里 PQ-4417+圆形、XL-6053+三角形全中。Responses 这条原本最可疑——它的 tool result 是单个 output 字符串字段、放不进图像——恰恰因为图片走的是跟发 user 消息、由 _content_for_responses 转成 input_image,所以无需为它特殊处理。回归测试分别锁在 tests/model/test_openai_responses.py(input_image 落地)与 tests/tools/test_vision_tool.py(Anthropic 不吞 media 消息)。
  • ImageAnalysisTool 的三个必错项随旧文件一起删除:model_name 硬编码 "gpt-4o"(llm 会从 agent 继承、model_name 不会,于是拿私有网关的 client 去请求一个叫 gpt-4o 的模型)、data URL 的 MIME 硬编码 image/jpeg(PNG/WebP 都被谎报,provider 按声明类型解码后拒绝)、注册名 image_analysis 与 super().__init__(name="read_image_tool") 不一致。新工具改走 Model.response 而非裸 get_client().chat.completions.create,配置的 provider/wire/base_url/auth 才是真正生效的那套;MIME 一律由 magic bytes 判定(media.get_image_type),不信后缀。两份重复的 imgocr 实现(OcrTool 与 CLI 的 _ocr_single_image)收归 utils/ocr.py 一份,字符预算留给调用方——那正是它们当初分叉的唯一原因。测试 tests/tools/test_vision_tool.py、tests/model/test_model_base.py。
  • read_file 读到图片/二进制不再返回整屏乱码,而是明确报错:file_tool.py 用 errors='ignore' 硬解码,一个 PNG 会回来 ~500 行带行号的 IHDR/iCCP mojibake(实测一张截图烧掉 1593 tokens),既污染上下文又诱导模型把 chunk 名当成内容去推理。现在读前先嗅探文件头:能认出格式就报格式("This is a PNG image, not text… 把图挂进对话让 vision 模型看"),认不出但含 NUL 字节就报 binary。判据是内容而非后缀——塞满 NUL 的 .txt 同样拒读,错命名成 .png 的纯文本照常能读;magic bytes 优先于 NUL,这样 header 里恰好没有 NUL 的 JPEG 也拦得住。tail 读路径绕过体积上限,但不绕过这道检查。magic-byte 嗅探从 utils/tokens.py 挪到 media.py 的 get_image_type()(两个无关调用方共用:token 计数要格式来解析尺寸,read_file 要格式来报错),不复制第二份。测试 tests/tools/test_builtin_file_tools.py。
  • 回答过程中 Ctrl+V 贴图 steer 立刻 'PosixPath' object has no attribute 'detail',整轮失败:_try_attach_clipboard_image 往 state.attached_images 追加的是 pathlib.Path,空闲轮在 _process_stream_response 里 str(Path(p).resolve()) 过一遍才交给 run(images=),而 mid-run Enter 把 Path 原样 Agent.steer(images=) → _inject_steering 挂到注入的 user message 上。下游一律按 str/bytes/dict/PIL 写的:count_image_tokens 一算 token 就 AttributeError(Layer 1 在构造请求之前就把整轮弄挂),即便不算 token,Model.process_image 也只会 warning「Unsupported image type」并把图默默丢掉——模型回答一张它根本没看见的截图。现在 Message 的 images / videos 加 validator,把 os.PathLike 统一 os.fspath 成路径字符串:一个字段一种形状,新写的 consumer 不会再漏这条;不在各 reader 里补 isinstance(Path) 分支,也不给 steer() 单独做一次 str 化(那只修一个调用点,run(images=[Path(...)]) 的 SDK 用法照样炸)。测试 tests/model/test_tokens.py、test_vision_capability.py、tests/agent/test_steer.py。
  • shell hook 的待答请求不会再串线或留下永久卡片:needs.approval / needs.input 现在都带必回传的 request_id,缺失或不匹配的答复直接忽略;终端、多个 consumer 与取消路径首个合法结果胜出,随后发 needs.resolved 并终止其余进程。以前 needs.input 无关联 id,终端先答后桌面也收不到请求已过期的信号。
  • HookProcess 不再把完整 JSON 答复误等到进程退出,也不会漏杀或漏回收 consumer 进程组:stdout 改为读取当前可用字节,一收到完整文档即可参与竞速;清理始终按已知 PGID 发信号,不再因原 hook 进程先退出而留下仍持有管道的孙进程。fire-and-forget notice 最长运行 30 秒后整组终止并回收,进程退出时 atexit 再杀一轮(daemon 清理线程活不过父进程,而 start_new_session 的子进程组会变成孤儿)。needs.* 的用户回答竞速仍不设时限。
  • needs.* 只认合法 JSON,退出码不参与裁决:曾经 returncode in (None, 0) 叠在早收 JSON 上,同一条「打印 allow 再 exit 1」的 consumer 会随机放行或忽略。没有合法 JSON 才是没答;已经写出的文档不因随后非零退出作废。
  • hook/notify 的 tool.* 元数据在截断前严格脱敏:命令、路径、查询、URL preview 与失败文本不会再把 API key、Authorization、URL token 等凭证带给外部 consumer;仍不外发完整工具参数或输出。
  • tool.started / tool.completed 改在真实执行边界外发:Runner 通过新增的 Model.run_function_calls(tool_event_callback=...) 接收执行回调;串行批次不再在首个工具运行前把后续工具全部标成 started,并行批次中先完成的工具立即发 completed;运行中取消也会补齐 completed,不再留下永久 working 状态。
  • 修正 _nothing_more_queued() 的反向 docstring 与 RunEventType 的虚假事件承诺:无 idle provider 或探测异常时实际且正确的行为一直是返回 True、正常上报 completion;文档若被照字面“修复”为 False,会让 SDK/脚本/cron 的 run.completed 永久 defer。run_events.py 也不再声称会发没有 emit site 的 tool.failed / subagent.spawned。
  • /clear 从「看运气的两条语义」收敛成「/new + 清屏」:/clear 之前是否重置会话,取决于 agent_config 里有没有 session_id——而只有 agentica resume <id> / /resume 会写那个字段,生成路径从不写回(cli/runtime.py 里 session_id = agent_config.get(...) or _generate_session_id())。于是全新会话里 /clear 换新 session、清空上下文;resume 进来后 /clear 却沿用同一个 SessionLog,继续往旧 transcript 追加,且 runner 第一轮把旧历史回放进"新"上下文(实测:resume 后 /clear,下一轮请求带 4 条消息,清屏前那轮仍在)。现在 /new 与 /clear 共用一个 _start_fresh_session()——无条件 pop("session_id") / pop("session_base_dir") 再重建,两条命令从此不可能再漂移。对齐三家:Codex 明写 /clear = 清终端 + 开新 chat(Ctrl+L 才是「只清屏」),Claude Code 与 opencode 干脆把 /clear 做成 /new 的别名。旧 transcript 不删,/resume 照样找得回。文案同步:registry / /help / examples/cli/01_cli_demo.py 由「Clear screen and reset conversation」改为「Clear screen and start a new session (same as /new)」,docs/getting-started/terminal.md 的 /clear 一节写清与 /resume 的关系。
  • 回答过程中贴图 + 文字会进 queue 而不是 steer:mid-run Enter 用 text.startswith("/") 把 /var/folders/...png 如图所示 当成 slash 命令,且带 attached_images 一律 queue(当时注释写 steer 只有文本)。空闲轮早就通过 _detect_file_drop + run(images=) 支持「插图 + 粘贴说明」。现在同样:剥掉开头的图片路径、Ctrl+V 附件一起 Agent.steer(images=),下一轮 inference 以带图的 user message 注入(图不能折进 tool result 字符串)。/cron 等已注册命令仍走 queue。
  • 打 / 不再列出两条 /cron(以及 /worktree):补全把 registry 当成 generator 传进 slash_command_rows,碰撞集合第二次迭代是空的,bundled skill 的 /cron (cron) / /worktree (worktree) 漏进菜单。选中仍插入 /cron,dispatch 走的是真正的 slash handler,skill 根本跑不到。/help 的 Skill Commands 同样跳过已占用的 slug。
  • 不透明超边长图不再因为「重编码没变小」而跳过缩边:_prepare_image_bytes 在 capped PNG 不小于原图时整张退回原图,于是少色截图(3000×2000 / 2400×1200)长边仍超过 VISION_MAX_IMAGE_EDGE(2000)。token 按解码几何计,这种图必须缩到 2000。只有真透明(JPEG 用不上)且 capped 拷贝也不更小,才保留原图。

[1.4.16] - 2026-09-15

breaking

  • MCP 只支持 mcp 2.x(extra 改为 mcp>=2,<3),连带修掉一处静默退化:Tool.inputSchema 在 2.x 变成 input_schema,属性访问只剩 snake_case(hasattr(tool, 'inputSchema') 恒为 False)。agentica/tools/mcp_tool.py 原来靠 hasattr 判断,于是整段参数 schema 分支被跳过 —— 所有 MCP 工具的参数变成空 properties,LLM 看不到任何参数,却不报错、不告警;而原有测试只断言 deferred,抓不到。现在直接读 input_schema,并补了断言 schema 内容(属性名与 required)的测试,另加一条用真 mcp.Tool 走一遍的用例 —— 把改法退回 v1 写法时,正是这几条值断言失败。同一轮按 2.x 现状改掉其余四处:CallToolResult.isError → is_error(agentica/mcp/client.py,不改会 AttributeError);streamable_http_client 不再收 headers/timeout/sse_read_timeout,改为构造 httpx2.AsyncClient 传进去(新 streamable_http_transport(),MCPServerStreamableHttp 与 McpTool 共用;client 由我们创建、SDK 不负责关闭,所以在自己的上下文里 enter 以保证连接池不泄漏);ClientSession 的第三个参数由 timedelta 改为秒数;streamablehttp_client / GetSessionIdCallback 双版本兜底与 read, write, *_ 的星号吸收一并删除(现在解包必须正好两个元素,SDK 再改形状就是响亮失败而不是错绑流)。MCPServerStreamableHttpParams 的 timeout / sse_read_timeout 相应改为秒数。示例与文档同步:FastMCP → from mcp.server.mcpserver import MCPServer,mcp.settings.host/port → mcp.run(host=, port=)(2.x 已无 mcp.settings,mcp.server.fastmcp 直接 ModuleNotFoundError)。新增 scripts/verify_mcp_v2_e2e.py:自己起 http/sse 两个 server(就用 examples 里那个,不另写替身),对三个传输 × MCPClient/McpTool 两条路径断言 20 项(含参数 schema 内容与 is_error 分支),跑完自己收进程。
  • 交互 CLI 有了 attach 入口:外部程序可以往一个正在跑的会话里发一条「用户消息」。此前没有任何入口能做到这件事 —— 会话的输入只有一个写者(键盘前的人),所以桌宠/快捷键脚本这类"替用户说一句"的需求只能绕道去写 peer mailbox 的私有格式(那条路已被判定为错误的抽象并删除,见下一条)。现在交互 CLI 在本机 unix socket 上提供 JSON-RPC 2.0(一行一个 JSON 文档),借用 ACP 的形态(session/* 方法名、session/prompt 里的 content blocks、换行分隔的 JSON-RPC)但不是 ACP 兼容:stdio 的 ACP 会新起一个 agent,而这条是附着到一个已经在 TUI 下跑着的会话;标准 ACP 客户端(Zed 等)接不上这个 socket,PROTOCOL_VERSION 是本通道自己的版本号、不代表能对上 ACP v1。方法子集:initialize(鉴权)/ session/load / session/prompt / session/cancel / ping。stdio 用不了:TUI(prompt_toolkit)自己占着 stdin/stdout,所以 ACP 标准的 stdio 传输在这里不成立;这用的是 ACP 允许的自定义传输,消息格式与生命周期照旧。送入的文本走的是和手敲一行完全相同的路径(hand_to_agent:会话在跑就插到下次 tool 边界、空闲就排成下一轮),因此它是用户本人的输入,不是 agent 之间的消息(后者是 send-message)。session/prompt 等这一轮结束才返回 stopReason(end_turn / cancelled / agentica_pending),拿不到结束就回 agentica_pending(并保留并列字段 agenticaPending: true),不再用 end_turn 冒充正常结束。寻址就是 socket 本身 —— 一个会话一个 socket,没有第二个寻址方式:不存在重名、前缀歧义,也不按 cwd 匹配(符号链接会让同一条路径有两种写法,那是端到端抓出来的坑)。默认关闭(settings.attach_enabled,或 AGENTICA_ATTACH_ENABLED=1);关掉时不建 socket、不起线程。安全上比只读的 notify sink 严一档(因为效力等同于用户本人输入):socket 与 token 都在 0700 目录、socket 0600、token 0600,每条连接都要 token,initialize 也不例外,没有 token 连方法列表都问不出来;initialize 响应里不给 authMethods(官方的"先谈方法再 auth/login"在这里不成立,回一个空列表会让懂 spec 的客户端理解成"不需要鉴权",而这条通道恰恰相反);会话退出时 socket 与 token 一起删除,并 set_attach_endpoint(None, None),避免拆完还往 notify envelope 里广播死路径。socket 路径刻意不放在缓存目录下 —— AF_UNIX 的 sun_path 有约 104 字节上限,缓存目录可由用户配置且常常很深,放那里会让 attach 点以 AF_UNIX path too long 静默消失(症状是"桌宠看不到我的会话",与真实原因毫不相干);现在用 <tempdir>/agentica-<uid>/(实测 31 字节),AGENTICA_ATTACH_DIR 可覆盖。可选:session/prompt 可带回 agenticaAnswer(这一轮最后一段回答),省客户端一次读取。只收文本块:任何这一层送不到的块都整条拒绝(-32602),不是跳过 —— [文本, 图片] 这种混合请求若把图跳过,就等于把「描述这张图」交给 agent 而图不在,换成了另一个问题且下游无从察觉;拒绝信息会点明哪些块类型没被送出。外部输入会先在终端回显(via <来源> 面板)—— 转述的输入本来不回声(__RELAYED__),那在调用方自己会打印到达块时是对的,但这条通道的调用方是另一个程序,不回显就会让终端显示一个问题不在屏幕上的回答(这条是 E2E 抓出来的:会话答了 PONG,但 pane 里找不到那句问话)。客户端从这里发现路径:优先读 notify 事件 transport 里的 attach_socket / peer_id(桌面 app 已经在收这些事件,且 launchd 起的 .app 没有能 import agentica 的 python3);其次是 presence 记录的 attach_socket(<cache>/peers/live/<peer_id>.json;/list-agents 与 list_agents 的 attach 行都渲染它,detail_rows() 已挂上,所以人和模型看到的是同一份字段),直接读它而不是自己拼(路径由 uid 与 TMPDIR 决定)。没有"列出 attach socket"的独立子命令 —— 会话列表就是这一份 live 记录。等到的是「吃下这句输入的那一轮」:inject 回报 steered / queued:queued 分三段(先等当前轮结束——那一轮没带这句——再等新轮开始,再等那一轮结束);settle 窗口(默认 1s,覆盖 steer() 吃进最后一次 inference、随后被 promote_late_steer 重入队)只对 steered 开 —— 套在 queued 上会让每条空闲 prompt 固定多等 1 秒,并把 goal 续跑 / 用户接着打的字收成 agenticaAnswer。session/cancel 必须另开一条连接发(session/prompt 占着原连接直到轮次结束,同连接上的 cancel 永远发不出去),接到 Agent.cancel(只停这一轮;不是 Ctrl+C 的整个 handler —— 那个键还会打中断提示、并给连按两次退出上膛),agenticaAnswer 接上最后一段回答,sessionId 改成每次请求现读(/resume / /fork 会换会话,快照会让客户端拿着新 id 被拒)。同一时刻只处理一条 session/prompt(两个客户端并在时,谁都可能把对方的轮次结束当成自己的)。新增 agentica/attach.py、tests/cli/test_cli_attach.py(56 项),含真 socket 客户端、鉴权、错帧、并发连接、退出清理)、scripts/verify_attach_e2e.py(真 tmux 会话 + 真客户端,14 条断言,含"那句问话确实出现在终端里"与"会话确实回答了它")、docs/getting-started/attach.md。
  • 删除 agentica peers list|send 与其 Python 入口 peers.send_to_live_peer()(以及 tests/cli/test_cli_peers_command.py、scripts/verify_peers_send_e2e.py):它是错误的抽象。peers 是 agent 之间说话的语汇,而那条通道的语义恰恰是"收件端把它当用户本人的输入"—— 名字把语义讲反了;agent 之间说话已经有 send-message。外部产品要"替用户说一句",正确形态是协议入口(attach / ACP),而不是"绕过去写别人的 mailbox"。参考三家实现均如此:cc-beeper 根本不做注入新 query(只有观察 + 答待答的问题走 hook 回话,唯一的"外部打字"是用 CGEvent 模拟键盘),codex 是 app-server 的 turn/start/turn/steer,hermes 是 ACP 的 session/prompt/tui_gateway 的 prompt.submit —— 都是协议里的一等方法。
  • 没有信箱的发送者不再被要求回复:format_for_model 对 from_peer_id 为空的发送者原本也会输出「report back with send_message to <name>」,而那个地址永远解析不到 —— 模型照做只会把结果送进无人读的信箱。现在改为明确说明「不在本机、没有回复地址,结果留在终端里」。有信箱的发送者(/send-message 转发、手机中继 peer_bridge)行为完全不变。修这条是因为它会在外部进程往会话里投递用户输入的任何形态下出现(如桌面 app 经 mailbox 投递),而不只是某一条入口。
  • 外部 hook 出口(settings.hooks),并删除 notify sink 的 /await:agentica 现在能像 Claude Code / codex / opencode 那样,在生命周期节点上运行用户自己配置的命令(settings.hooks.command,argv 列表、不经过 shell),把 JSON 喂 stdin 再从 stdout 收回答。六个事件:run.started / run.completed / run.failed / run.cancelled / needs.approval / needs.input;前四个非阻塞,后两个等回答。回答的四档 decision 词(allow / allow_prefix / deny / deny_prefix)与 answer 自由文本沿用原协议。两条语义照旧:不设等候上限(本层不写死时限,也没有 settings.hooks.timeout / AGENTICA_HOOKS_TIMEOUT 这种看起来能设、实际不生效的字段;命令可以自己设),终端与 hook 并行 race、先答的算(终端先答就 kill 掉 hook 进程组,晚到的是 race 不是错误)。失败阶梯与原 sink 一致:命令不存在 / spawn 失败 / 非零退出 / 空 stdout / 解析不了 / 词不认识 —— 一律「没有决定」,绝不合成 allow。新包 agentica/shell_hooks/,settings.hooks 默认关闭;enabled 与 command 都有才装上,关掉时不起线程不起进程。同时删除 notify sink 的 POST /await 回答半(agentica/notify/questions.py、agentica/notify/approvals.py 及其测试一并删除):sink 从此单向只看,回答统一走 hook。原因不是「hook 更优雅」,而是一条回答通道不该有两套实现 —— /await 要求桌宠为 agentica 单独实现一遍私有协议,而 hook 是各家 CLI 通用形态,桌宠不必为 agentica 写任何新代码。顺带修一个真实缺陷:wrap_ask_callback 是先问桌宠、再调终端(ask_via_desktop 在 inner(...) 之前同步执行),所以桌宠开着但没答时,终端 prompt 根本不会出现 —— 用户被锁在外面;needs.input 现在在终端 prompt 已 arm 之后、由 prompt 循环轮询 hook,两条路共用一个投递槽(与审批用 registry future 的 race 同一条道理,只是提问没有 future 可挂)。每轮 run 的事件现在也同时发给两个出口(notify_sink_dispatch 里 fan-out,goal 扣住 run.completed 的逻辑只有一份,不再按 transport 各写一遍)。新增 tests/shell_hooks/(config / protocol / process / egress / requests)与 tests/cli/test_cli_approval_hook.py、tests/cli/test_cli_ask_hook.py。文档:新增 docs/getting-started/shell-hooks.md,notify-sink.md 改为「只看不问」并指向新文档;写明删的是 agentica 的 /await 调用,桌宠端点仍服务 Claude Code 的 PermissionRequest。hook 先答审批时补打终端 transcript remnant(卡片在 layout 里,不重印会丢掉刚批准的命令)。Gateway IM 上空闲的 delivery=queue 会开下一轮,而不只是推到微信。
  • ask_user_question 的取舍从「运行时超时」改成「装配期不给工具」:ask_user_question 是用户行为,不是超时行为 —— 它一直等到人回答,这是工具本身的设计,不是可调的参数。此前无人值守的路径(cron / --print)被塞了同一个工具,再在运行时用一个写死的假答复顶上(cron/cli_runner.py 的 _noninteractive_input_callback 返回「no user is available to answer, pick a reasonable default」)——那等于替用户说话。现在改为在装配期决定:create_agent 的 include_ask_user_question 成为必填关键字参数,各调用点显式声明 —— 交互 CLI 及其重建路径(/model、/resume、/fork、/clear、技能重载)传 True;--query/--print、cron、/bg 传 False。delegate worker 是 agentica --query ... --print 子进程,因此自动没有该工具,不再依赖提示词约束模型。同时删掉 AskUserQuestionTool 的 timeout / default_on_timeout 两个构造参数:全仓没有任何地方读 self.timeout,而 default_on_timeout 只在 callback 抛异常和 EOFError 时生效、与超时无关(名字骗人)。manages_own_timeout = True 保留 —— 那才是「一直等」的实现点,也是唯一正确的语义。
  • /compact 与换窗前言不再提「摘要」:帮助文本由 Start a new context window (no summary) 收敛为 Start a new context window;WINDOW_CONTINUATION_MARK 由 New context window started without a conversation summary. 改为 New context window started.(哨兵作用不变——空闲 /compact 留下的 preamble 仍靠它被下一轮用户输入折叠),full_window_text 删掉 This window starts without a conversation summary.。旧行向模型解释一段并不存在的历史;新窗第一句只报事实。副作用:磁盘上带旧句子的行,其 preamble 不再被剥净,搜索索引会多出一行 chrome。
  • Layer 2 compact 不再做 LLM / native 摘要,改为空窗换窗(Codex TokenBudget / #29743):窗口满、/compact、prompt_too_long 后的 reactive 都只切同一 session_id 的新活动窗,写空 summary 的 compact_boundary。旧对话留在 JSONL,用 search_session 查;交接写旁边的 <session_id>.notes.md(已有文件工具,不新建目录)。/compact [instructions] 不再把指令交给摘要模型。should_native_compact 恒为 False,runner 不再调 /responses/compact。油表是独立的 <context_window> user 片段(每窗一次剩余提醒,不进冻结的 system 前缀)。
  • 删除 read_session_item:抄了 Codex history.read_item 的 item_id + offset_chars / limit_chars 分页,但本地 JSONL 一行通常短于 search snippet;模型拿着 id 去读「hi」只得到 type/timestamp/content。换窗后靠 search_session 的关键词命中 + 用户问题索引即可。
  • 删除 Serply 搜索(SearchSerplyTool / web_search 的 serply 引擎 / extra [serply] / CLI --tools search_serply):厂商自己合入的 vendor 营销,Google 搜索继续用 Serper。SERPLY_API_KEY 和 AGENTICA_SERPLY_SEARCH_TYPE 不再被读取。

features

  • 外部 hook 从“开始/结束提醒”升级为完整状态总线:新增 tool.started / tool.completed(共用工具执行出口,流式与普通 SDK run 都发)、session.started / session.ended、needs.resolved;/new、/clear、/resume、/fork 与退出都在状态实际切换、attach 元数据同步后发对应 session 生命周期,tool 失败带裁剪后的错误与耗时,session 启动带 model/profile/permission mode/transcript path。hook egress 在首次事件时幂等懒安装,所以 --query、SDK、cron 不再依赖交互 CLI 先 bootstrap。所有 hook payload 必发稳定 session_id,并与 notify sink 共用 transport(ppid/cwd/tty/attach)。
  • CLI 启动横幅打出本次 Session: id:交互 CLI 起来、以及 /new、/clear 重打横幅时,都在 Model 下面一行写出完整 session id,方便复制给 agentica resume <id> / /resume。以前只有退出摘要和 /list-agents 才看得到。
  • 换窗前言说明这是第几个窗、以及这次是不是「重置过」(对齐 Codex #29256 的 Previous context window id):<context_window> 以前只有 Current context window N.,第 1 个窗和第 5 个窗长得一样,换窗后模型没有信号知道「前面那些轮次已经不在了、该先去读 checkpoint」,于是下面那句 Recover prior facts with search_session. 读起来像套话。现在 window_id > 1(且有 session log)时多一行 This window follows a context reset: the earlier turns are not here.,第 1 个窗不写(没有丢东西可恢复),无 session log 也不写(那时 search_session 只会回「No session log on this agent」,与这段其余部分同一条规则:只提做不到的事)。window_id 是进程内计数器、resume 时从 1 重来,而 resume 并没有丢轮次(load() 会回放),所以那里保持沉默同样是对的。
  • fallback 催写不再邀请「继续干活」:fallback_text 原句 … write … now, then continue the task,在窗口已到 99%、只留约 4% reserve(512k 配 compact_token_limit 时是 20.5k)的当口,等于让模型拿这点余量去干活,notes 有写不完的风险。改为 … write … now — the next window starts without these turns.(Codex #33255 的意图:那个 reserve 是留给「把状态写下来」的)。没有照抄 Codex 的 Do not continue the task or give a final answer in this window:Codex 的 fallback 是 developer item、被 rollover 消费掉,而 agentica 的提示是折进当前用户轮的,自动换窗又保留该轮(keep_trailing_turn=True),照抄会在新窗里留一句「不许继续工作」去跟新窗自己的指令打架。同理不抄它那句 call functions.new_context(agentica 的 new_context 工具已删,投给它是死路)。
  • CLI 输入 / 列出全部 slash 命令,并做模糊匹配:以前补全只认前缀(/pn 对不上 /peername)。现在打 / 就弹出命令清单(带说明);继续打字按前缀 / 名字子串 / 子序列 / 说明里的词排序(说明匹配至少 3 个字,避免 /s 刷屏)。技能 auto-command 仍跟在后面。菜单长在输入框正上方——TUI 贴终端底,往下开的 Float 只剩状态栏那一行甚至 0 行,清单会被裁没。
  • /peername on|off 手动开关状态栏上的短 peer 名(如 vpetmac-c4)。以前只在同 cwd 另有 live session、或本 session 是 fork 时自动出现,没法强制显示/关掉。无参翻转,跟 /debug 一样写 session sidecar + 本 work_dir project.json,下次启动继续生效;从没设过则仍走自动规则。
  • CLI 正在跑的 execute 不再只留开头 80 字:live 窗口按终端宽度折行(最多 6 行),cd /很长的路径 && swift test … 这种以前只看得见 cd。Spinner 耗时写成 execute (16m36s),不再挂四位秒数。工作目录和 $HOME 在命令里缩成 . / ~。
  • CLI 会话/技能列表多展示一点正文:/resume 列表每个 session 给出最近 5 条用户请求(各前 250 字),不然只看第一条/名称看不出眼下在干什么;/rewind list 的 question 同样给前 250 字(以前截到 48)。/history 和 /resume <n> 回放只留问答,去掉 tool call 摘要;同一 run 里多轮 tool 之间的旁白和最后一轮回答并成一块,不再每跳复打一遍 Agent - run N。/tools 先列内置再按名排序外部工具。/skills 的 desc 展示开头 250 字。
  • send_message / /send-message 可选 steer 或 queue 投递:默认仍是 steer——对方正在跑时插到下一次 tool 边界(和本地 /steer 一样)。--queue / delivery=queue 等对方这轮干完再作为下一轮(和本地 /queue 一样)。人和模型同一套;闲着的会话两种都会立刻开一轮。Gateway IM 会话同样:空闲时 steer 仍推到聊天(给用户看的回复),落下的 queue 会开下一轮。
  • CLI 的 task / delegate 调用行显示实际会跑的模型:task 按 subagent_type 的 model_tier 定(auxiliary 用便宜模型、main 用主会话模型),delegate 按会话 profile + 调用里的 model 参数定,标签排在 meta 行最前面(live 窗口只留首行并截断,而 label 可能是一整句)。命中 config.yaml profile 的委托写成 model=<模型名> (profile <profile>),因为决定端点的是 profile 而不是会话 provider。标签来自工具实例现算(新增 Tool.model_label_for / Agent.describe_tool_model),不是模型传的参数:delegate 的启动决策抽成 _profile_for_choice 供 model_label_for 与 argv 共用,标签和子进程的 --profile 不可能各说各话。/model 切换后下一行即更新。只对 task / delegate 求值(要读 config.yaml,而 live 窗口每秒重绘数次),resolver 抛异常只丢标签、不影响调用行。其它工具不显示;web 聊天行没有 live session 可问,仍只显示模型自己传的 model 参数。
  • CLI 开关落盘:/reasoning、/statusbar、/debug、/peername、/permissions、/tools add 下次启动继续生效。这几项以前只活在当前进程里:下次开 CLI 回到默认,/permissions 更早就失效——/resume、/model、/newchat 从 agent_config 重建 agent,而 /permissions 只改了 live agent,档位于是静默回落到 allow-all(等于把审批护栏降级)。现在写两处:session sidecar <id>.meta.json 的 cli 块(记「这个会话」)和该 work_dir project.json 的 cli 块(记「这个目录」)。启动优先级:命令行 flag > 被 resume 的 session sidecar > 本 work_dir project.json > 默认值;/reasoning、/statusbar、/debug、/peername、/permissions 与 /tools add|remove 都走这一条。--permissions 默认值由 allow-all 改为 None,否则「用户显式要 allow-all」与「只是没写」无法区分,saved ask 会被默认值盖掉。/tools add-from 的模块不落盘(它在加载时执行任意 .py,且本来要人确认),/tools remove 会写回新集合,所以删掉最后一个工具不会再被下次启动复活;--tools 与 saved 集合取并集、不互相覆盖。/fork 把 cli 块带给新分支(同一段对话换个窗看,视角设置跟着走)。
  • /status 在 <session>.notes.md 非空时显示路径和大小:跟 Session log 并列。文件不存在或还是空的不占一行。
  • search_session 每次都带最近用户问题:换窗后「前面问了啥」对不上关键词,不该靠中/英套话表猜意图。每次结果附带 role=user 倒序最多 20 条(单条截断、总长封顶,跳过 <context_window> preamble);空 query 只返回这份索引。关键词路径不变(工单号 仍打中 工单 ZX-41827)。
  • 每个 Agent 自动挂 BuiltinContextTool:只挂 search_session,能搜到 compact_boundary 之前的 JSONL。不再挂 new_context(人用 /compact,省掉每轮 ~90 token 的 schema)。
  • notes.md 只留给模型写 standing state,不再落 transcript digest:对齐 Codex #33255——goals / constraints / IDs / decisions,不是第二份 JSONL。空窗 digest 只注入 <dropped_span>(#43335 第一跳不能只有路径),不写进 notes.md。写进去会让 notes_are_ready 变真,之后不再催写。
  • 空窗 fallback digest 按时间线写,不再拆成 User / Assistant 两个列表:旧写法丢掉问答顺序,也不记 tool。先 user/assistant 正文,再 tool 参数和结果;超长 result 仍留头尾。不写时间戳(created_at 在 load() 后不是 JSONL 的 timestamp)。search_session 用户问题索引用 JSONL 时间戳,并搜模型手写的 notes。
  • search_session 契约对齐 Codex history.search_contents:query 先按字面子串,中文问法再叠字(工单号 能打中 工单 ZX-41827),命中按相关度排序。不照抄纯字面搜(整句问题 0/10)。不照抄 history.read_item 分页器。
  • 内联图片长边超过 2000px 先在本地缩小再发给模型:token 按解码几何计,视网膜截图每轮原样重发浪费。cap 内原样通过;macOS 剪贴板那种全不透明的假 RGBA 去掉空 alpha;PNG 压不下来的照片才落 JPEG。data: URI 和 gateway 的 {"url": data:...} 同样走这道。解不出的格式(SVG)仍原样送;编码超过 100MB 或 Pillow 解压炸弹直接报错,不再吞掉后把原图发出去。
  • Claude 也认 cache_control_session_header,值按 CLI 会话换:聚合型代理不粘路由会打到不同后端,缓存冷、schema 400 也更多。header(如 X-Session-Id)注入当前 session_id,新开会话换路由;没有会话才回落到 ~/.agentica/cache/cache_routing.json 里按 base_url 存的 id。不再把第一次(还没 session)的 fallback 冻在实例上。get_model 不再只给 OpenAI chat 传这个字段;setup 对 anthropic 只问粘路由 header。
  • config.yaml 文档补上 prompt cache 与粘性路由:guides/config.md 的 Profile schema 表原来缺 enable_cache_control / cache_control_session_header / cache_control_messages / cache_keepalive / default_headers 五项(extra_headers 也没写明对 anthropic 不生效)。新增「代理网关的粘性路由」一节:账号级(default_headers 写死)与会话级(cache_control_session_header 按会话取值)的取舍、两者同配时显式值优先、以及换项目目录会重写缓存。

fixes

  • execute 的 schema 点名 rg -rn:只写「-r 是 --replace」不够,模型还是从 grep 肌肉记忆写成 rg -rn(每个匹配被换成字母 n,退出 0)。现在写明不要写 rg -rn,行号只用 -n。命令不改写、不拦截。
  • 阻断请求的报错带本地时间戳:CLI display_agent_execution_error(400/429/限流/畸形流等所有打断本轮的报错)写成 ● Error: Agent execution failed (400) - 2026-09-13 14:28:33,文件日志同一行;Web 聊天的 Error: 条同样附 YYYY-MM-DD HH:MM:SS,方便和网关的 spanId 对表。
  • reasoning_effort 不再白名单拦截:--reasoning_effort、agentica setup、_validate_profile、gateway create_model 以前只认 low/medium/high/max(Claude Opus 5 另有一份)。值原样发给端点,只检查是字符串。Kimi K3 的档位是 low/high/max,max 是合法值,CLI 不该拒,也不该替端点改写成别的档。
  • Layer 1 淘汰的 tool 参数不再是一段可拷贝的字符串:以前超长参数叶子被换成 <evicted-tool-arg chars=N>,它仍是 string,和 send_message / execute / write_file 的正文同型。长会话里模型把这段占位符原样再发给对端(对端只收到 <evicted-tool-arg chars=1183),或当 shell / 文件内容执行。根因不是「没匹配到字面量」,是占位符不该能当 payload。现在叶子改成 JSON 对象 {"$evicted": N};evict_context 还会把 JSONL 里已写成旧字符串的叶子升成对象,避免下一轮再被抄走。结果占位符在参数已被丢掉时不再写「Re-run the call」(那等于教模型用空 payload 重发 send_message)。get_function_call 对对象占位符、其 JSON 编码、以及旧字符串整值 fail-closed,错误里不回显占位符本身。命令里只是提到旧字符串的(grep -rn '<evicted-tool-arg chars=' .)照常执行。
  • Layer 1 不再被中途注入的 steering / peer 消息击穿:_inject_steering / _inject_peer_messages 在没有尾部 role="tool" result 可折叠时会 append 一条 user 消息——而这恰好发生在「调用还在飞」或「Anthropic 把 result 打包进 user 消息」两种情况下。这时 live_tool_round_start 会把这条注入消息当成尾巴,cutoff 抬到整轮之上,于是 Layer 1 把还没被模型看过的调用参数换成占位符、把刚返回的 result 淘汰掉。现在注入点给消息打 _injected 标记,live_tool_round_start 先跳过被标记的注入消息再定界。真实回合(用户真的问下一句)不受影响,旧轮仍按原样可淘汰。
  • delegate 的 model 只能是本会话的两个模型(repo 级约定,不只 CLI):真实事故:会话跑 ds-v4-1-flash profile(main = deepseek-v4.1-flash-official),模型自己填了 model="claude-opus-5"——那是另一个 profile 的 main 模型,而 model 的说明当时明确写着「A model that exactly one config.yaml profile runs is delegated on that profile」,等于在邀请跨 profile 委托;同一网关又正好能服务它,于是 worker 跑在了另一个 profile 的模型和账单上。现在会话可用的就是主模型 + auxiliary 模型(--auxiliary_model_name),model 只能填这两个之一,其它值在启动进程前按名字拒绝、错误信息列出可选的两个。规则不看有没有 profile,因此 CLI / SDK / gateway 一致:模型决定端点和账单,换模型只有用户能做(换会话 profile,或 SDK 构造时选 main/aux)。task 本来就没这个口子——它没有 model 参数,只能按 model_tier 在 main/aux 里选。另修一个真实串端点问题:会话自己的两个模型此前选 aux 时走 SDK 分支,会把父会话 base_url 交给子进程,aux 在别的端点就会跑错地方;现在两者都走 --profile + --model_name,落在会话 profile 上。aux 模型也因此首次显式传给工具(auxiliary_model=,此前只传了主模型),并在 /model 原地切 profile 时同步刷新(refresh_session_models)。gateway 侧无需改动:web/desktop 的 DeepAgent 不传 background_process_registry,本就没有 delegate 工具。
  • ask_user_question 的推荐选项标记回到 schema 里:17d20676 把调用形状从 system prompt 收进 options 的 schema description 时,旧文案「Put the choice you recommend first and say so in its label」只留下了前半句「放第一个」,于是模型不再有义务给标签加 (推荐)——真实对话里就出现过 4 个选项一个标记都没有。位置本身不足以表达推荐:用户按键位选,答复回到模型时只有「2」,是标签在说哪个是推荐的(工具刻意不自己加标记、不重排,那是模型的话)。补回后半句(含 (推荐) / (recommended) 两个例子,与仓库已有测试/提示用词一致),仍留在 schema、不回 system prompt。实测同一模型同一场景 16 次采样:旧文案 11/16 次带标记(5 次一个都没有),新文案 16/16。
  • 换窗交接的 digest 改为可累积,连续换窗不再逐轮丢事实:strip_window_preamble 会把 <dropped_span> / <session_notes> 一起剥掉(搜索索引需要这个,它不该把我们的 chrome 当第二次命中),但 digest 也走同一个函数,于是上一轮刚摘录的内容在下一轮被当成 chrome 丢弃。实测:第 1 次换窗后工单号 / 决定还在,第 2 次全部消失,第 3 次连待答问题都没了。而 SDK 不传 session_id 时 notes_path 和 _session_log 都是 None,注入 prompt 的这份 skim 就是唯一副本,丢了就真的没了(CLI / Web 还能靠 JSONL + search_session 找回)。改为 _collect 单独处理:把上一轮 digest / notes 的 - 行继承到本轮(只取正文行,丢掉旧 header 与分区标题,否则每轮叠一层变成 header 汤)。实测 10 轮结构保持扁平、长度线性有界、事实全程在位。
  • notes 提醒不再指向写不进去的文件:can_author_notes 以前只判 write_file / apply_patch 是否存在,不看有没有路径,于是 SDK 无 session_id(path 为 None)时 _claim_notes_fallback 照样发「把要点写进 session notes file」并为此推迟 4% 窗口,而那件事根本做不到。改为同时要求 notes_path 存在;fallback_text 无路径时返回空串,调用方不再折叠提醒。full_window_text 同理:没有 session log 时不提 search_session、不提 notes 文件(那两样在无 log 时一个 search_session 直接答「No session log on this agent」,一个没有路径),只保留油表与继承来的 digest。CLI / Web 有 session_id,两处提示与能力均不变。
  • 换窗 N≥2 次后问题索引不再重复,且不再误删跨窗的真实重复提问:连续换窗而中间没有已答复的轮次时,上一窗保留的尾巴本身就带着 <context_window>,下一次换窗再折一层,于是嵌套。strip_window_preamble 只剥最外层,内层文本与裸问题不再逐字相等,drop_shadowed_by_boundary 匹配不上,同一句在索引里出现 n 次。改为反复剥到不再变化(多轮 preamble 全部剥净)。同时把回溯范围限制在本窗(扫到上一个 compact_boundary 为止):旧实现无限回溯并拿原始文本比较,会把上一窗里字节相同、但已被答复过的真实重复提问当成影子丢掉,文字上等于吞掉一轮对话。两侧比较统一改用剥净后的正文。
  • 日志里的时间戳统一按本地时区渲染:JSONL 存 UTC、CLI 按本地打印,而 search_session 的命中/问题索引、/fork 的备选点、/resume 列表都把存下来的 UTC 文本原样截断输出,同一轮于是显示成两个时刻(工具结果 16:43 / 终端 00:43),模型无法把搜到的行和用户正在看的对话对齐。新增 SessionLog.local_turn_stamp 统一渲染(Z / epoch 按瞬间换算成本地,无时区裸文本按本地处理,解析不了的原文透传不丢),三处显示共用。JSONL 落盘仍是 UTC,未改。
  • CLI 文件体积不再甩原始字节:/status、/trace、/resume 列表共用 format_file_size(4.1MB / 4.8KB)。以前 /status 和 /trace 打 4,141,579 B,/resume 一律按 KB,4MB 会话会写成 4044KB。
  • 换窗交接不再把长 user / assistant 轮的结尾截掉:digest 里的一行以前只保留开头(head-only),而结尾往往正是那句在问的话——模型自问自答式收尾的「要我把行号一并订正吗?」被砍掉后,下一窗只看到一串推理,用户回的那句 ok 就没有可指的对象。改为两端都留(clip_head_tail,与长 tool 结果的 _clip 一致);<session_notes> / <dropped_span> 超过 4000 字符时同样保留尾部(notes 的最新状态写在最后)。search_session 用户问题索引的 snippet_head(空 query / 「前面问了啥」)同一处:长问题先贴素材、最后才问,以前索引里只剩开头。
  • 中途换窗不再把「正在问的那句」在 search_session 里列两遍:本轮 tool round 若已被 in-turn flush 写盘,append_post_compact_messages 会随 preserved tail 再写一份(这份是必需的,load() 只回放 boundary 之后的行)。两条都在搜索面上,问题索引于是出现两条同样的 user 问句。改为读取侧去重:boundary 后第一条 user 行的正文与 boundary 前最近一条不带 preamble 的 user 行相同,就丢掉前置那份,以及同 span 里被重写的 assistant / tool;原始行仍在 JSONL 里。只在 _conversation_rows 做这一趟(需要看见 compact_boundary)。
  • BuiltinContextTool 改为弱引用持有 agent:跟 Function._agent 一致。强引用会经 Agent -> Model -> functions -> Function.entrypoint -> tool -> Agent 成环(Function.entrypoint 是 bound method,本身就扣着 tool),test_model_functions_agent_weakref 因此失败。
  • search_session 不再命中换窗油表 / <dropped_span> 副本:preserved tail 折进 JSONL 后,ZX-41827 会打中原文和 skim 各一次。rank_entries 打在 strip_window_preamble 之后的正文上;纯油表行从 _conversation_rows 丢掉。折在 preamble 后面的 user 问题仍可搜、仍进问题索引。
  • 换窗 digest 不再整条跳过 preamble user:start_new_context_window 把油表折进 tail 第一条,is_window_preamble 会把「现在怎么办?」一起滤掉。改为剥前缀、留问题。
  • CLI / Web /compact 改为空窗,提示折进下一轮用户请求:空闲换窗不再 keep_trailing_turn(那会把油表叠在上一轮已答完的 user 上)。<context_window> + notes 作为 preamble 留下,下一句用户输入折叠进去,避免连续两条 user。自动 / reactive compact 仍保留正在问的尾巴。
  • CLI 换窗提示不再写「LLM-summarised」:Layer 2 已是空窗,重复换窗的警告改为 earlier turns left the window / search_session。
  • ask_user_question 第一次调用不再因 options 是字符串而失败:模型常把选项收成 '["A", "B"]',pydantic 报 Input should be a valid list,重试才过。schema 写明 options 是 string 数组而不是一段 JSON;docstring / system prompt 去掉会诱使模型照抄的 Python options=[...]。字符串化的数组在进 validate_call 之前解开(含 XML <parameter> 和带 fence 的 JSON)。
  • 带日期的模型快照按自己的单价计,不再套父模型:CostTracker._lookup_pricing 以前取 catalog 里第一个 startswith 命中,_FALLBACK_PRICING 又是宽名在前(gpt-4o 先于 gpt-4o-mini),于是 gpt-4o-mini-2024-07-18 按 2.50/10.00 而不是 0.15/0.60,状态栏和 RunResponse.cost_summary 都偏。现在前缀查找复用 _get_model_entry 的最长分隔符锚定规则,和 context_window 对同一个 id 不再各算各的。
  • Langfuse 不再把 SSE 的 data: {...} 当媒体:MediaManager 见 data: 就当 base64 data URI,会话里的流式帧和源码片段会打 Error parsing base64 data URI / Data is not base64 encoded。只有 data:...;base64,... 才解析。
  • CLI 状态栏思考强度只显示 high:OpenAI 兼容代理把 reasoning_effort 和 thinking_display 放进 extra_body 时,以前 describe_thinking_mode() 会拼成 on(reasoning_effort=high, display=omitted)。有强度就只显示强度,display= 不再进状态栏。
  • Anthropic 原生路径不再把可选参数全标成必填:Claude.get_tools() 自己按「type 里没有 null 就算 required」重算了一遍,而 get_json_schema 恰好相反——它用「不出现在 required 里」表达 Optional(type 数组好几家 provider 不收)。于是每个参数都被判成必填:read_file 要求同时传 offset/limit/tail,execute 要求传 timeout/parallel_safe。现在直接用 parameters["required"](签名默认值算出来的,或 parameters_override 给的),非 list 一律收敛成 [],properties 里没有的名字丢掉。只影响 model_provider: anthropic,OpenAI 路径发的是 Function.to_dict(),一直是对的。
  • Anthropic 工具 schema 不再抹掉 enum / items / 嵌套 properties:每个参数以前被压成 {"type","description"} 两个键,自动生成的 schema 里没有 per-param description,所以描述还都是空串。现在整份属性 schema 原样透传。
  • deferred 和不可用的工具不再进 Anthropic 的 tools:OpenAI 走 self.tools / get_tools_for_api(),这两道闸是白拿的;Anthropic 这条路径遍历 self.functions,两道都漏了,deferred=True 的 MCP 工具会连 schema 一起发出去,available_when 返回 False 的也照发。deferred 仍然可执行,只是不再出现在 schema 里。
  • 全可选的 response_model 不再让 Anthropic 请求 400:字段全带默认值时 pydantic 的 model_json_schema() 不会输出 required 键,合成的 structured_output 工具于是发出 "required": null,API 回 input_schema.required: Input should be a valid list。
  • mcp 2.x 仍能 import McpTool(当时):SDK 把 streamablehttp_client 改成了 streamable_http_client,并去掉 GetSessionIdCallback,于是认了两个名字。这一条已被本版「只支持 2.x」取代 —— 双版本兜底删掉了,mcp 1.x 不再可用。
  • grep 超长行只回匹配窗口,且遇大行不崩溃、中文列号不错位、单文件保持路径:超过 2000 字不再吐整行,格式是 file:line: col=N, line_len=M: ...window...。以前用贪婪的最后一个 :数字: 拆 rg 输出,JSONL 里的 "12:30:45" 会把行号和窗口抢走。超过 64 KiB 的行(大 JSONL)以前会让 StreamReader.readline() 报 LimitOverrunError 导致整个 grep 崩溃并被误当成「无匹配」,现用 _read_rg_line 分块消费并设 10 MiB 防护上限;rg --column 的字节列号转换为字符列号,避免 CJK 文本切片越界错失匹配;rg 搜单文件时追加 --with-filename,避免输出缺路径导致行号被误解析;匹配结束位置按正则真实宽度计算,不再被硬编码的 +1 截断。
  • grep 工作区内的路径改相对路径:rg 拿到的是绝对搜索根,以前每一行都重复整段 work dir,100 条匹配时前缀约占输出三成,还在后续每一跳里再计一次。工作区外的命中仍报绝对路径,模型才能原样喂给 read_file。参数仍是 pattern / path / limit,要看匹配附近几行用 execute 的 rg -C。
  • 会话日志的 event 行不再重复盖 cwd / version / git_branch:长会话里 event 占约八成行,这三个字段一轮内不变,重复写约占日志 8%。session_meta 仍单独盖一次,对话行不变;Trace 取第一次见到的值。
  • 技能注册改成一条 INFO 汇总:以前每个 skill 一行 INFO,load_all 在 reload / 切 profile / worktree 重绑时再跑一遍,一条进程日志里能堆出上百行。逐条降到 DEBUG,INFO 只在真有新注册时打一行。
  • apply_patch schema 写明按行匹配:超长单行(JSONL)这里改不了,那种情况自己做唯一字面替换。不改匹配引擎,也不往 tools.md 里教脚本。
  • CLI write_file / read_file / apply_patch 工作区外不再只显示文件名:以前 _display_path 对不上 work dir 就收成 basename,/tmp/dupprobe/probe.py 变成 probe.py,diff 头也是。工作区内仍是相对路径,区外保留调用时的路径。
  • /model / Claude resume 剥 tool 时留下写入摘要:切模型仍丢掉 thinking 和 tool 的 wire 格式(否则换 provider 会 400),但会追加一条 <elided-tools>:散文里的「写好了 193 行」不算证据,真正跑过的 write_file / apply_patch 列在下面。以前只留问答文本,下一轮就会接着演一遍没发生过的写文件。execute 输出不进摘要(会漏密钥)。摘要合进结尾那条 assistant 正文,不单独占一条消息:连续同角色轮次在部分上游和聚合代理上是 400 roles must alternate,而剥离本身就是为了别 400;合并同时让操作幂等,resume 之后再按 /model 不会叠第二份。判据是「历史里真有 tool 轮」而不是 provider 能力,纯聊天会话 resume 到 Claude 不再被塞一条「tool calls were dropped」的假话。/resume、/history 回放时不显示这个内部标记。
  • CLI 两个路径缩短器不再各说一套:_display_path 在工作区外直接返回未规范化的路径,../ 会留在绝对路径中间(/Users/me/proj/../other/x.py);现在和 _shorten_path 一样用 normpath 词法折叠(不用 resolve,否则 macOS 把 /tmp 变成 /private/tmp)。~ 保持写成 ~,不再展开成带用户名的绝对路径。
  • SDK print_response 的工具行按 agent 的 work dir 缩短:printer.py 没给 format_tool_display 传 work_dir,回落到 os.getcwd();delegate(work_dir=...) 或 SDK 嵌入时 agent 跑在别的目录,路径就按错的根算。
  • apply_patch 示例补上同文件多处:一条补丁里一个 *** Update File 下几个 @@ 改几处,不要拆成多次调用,也不要写两个同路径的 Update File。以前示例只有「一文件一 hunk」,模型就把同一文件拆成两次调用。
  • CLI 输入框折行后不再把上一行卷走:TextArea 按显示宽度(get_cwidth,中文两列)折行,prompt 只算在第一逻辑行;以前用 len(line) // (终端宽-2) 估高度,中文刚折到第 2 行时盒子仍是 1 行,光标把第一行顶没,再打约一行才长高回来。现在跟 prompt_toolkit 同一套折行算行数。
  • CLI ask_user_question 不再裁掉问题后半段:提问组件以前自己算预留行数,把整段 prompt 当成一行折行,短段落被低估,第 2 问和选项出了屏。现在原文倒出来(前面加 ?,空一行再列选项),窗口高度交给 prompt_toolkit。tool result 本身没截过。
  • 内置工具 schema 不再点名别的可选工具:grep 不提 execute,execute 不提 read_file / apply_patch,task / memory 也不再写对方的名字。delegate 可以提 wait(同一套后台 registry)。SDK 可以只装文件工具、不装 execute。tools.md 只在有文件工具时注入,同样不提 execute。按文件名过滤:收窄 grep 的 path。
  • grep 去掉 include:schema 里写 include= 等于每轮教 GNU grep 的 --include,模型再抄到 rg 上就炸。参数只留 pattern / path / limit。
  • execute 不再改写 rg --include:命令原样进 shell。过滤扩展名写 rg -g '*.py' / rg -t py,schema 也不再提 --include。
  • Claude 的工具结果终于落盘了:Anthropic 用 role="user" + tool_result 块回答工具调用,落盘只认 role="tool",所以每个原生 Claude 会话写下的都是 assistant(tool_calls) 后面什么都没有——真实工具输出一次也没进 jsonl,投影里全是孤儿 tool_use id。以前看不出来,是因为坏掉的 sanitize_messages 会注入「execution may have been interrupted」占位,那些占位恰好是 role="tool",于是成了 Claude 会话唯一的 tool 行(历史日志里 interrupted 占 tool 行 100%);上一条修掉占位后 tool 行直接归零。现在按 tool_use_id 拆成每块一行,tool_name/is_error 一并带上;in-turn flush 手里没有 FunctionCall 记录时,从发起那一轮的 tool_calls 取名字和参数。
  • trajectory_skeleton 认得 Claude 的工具回答:role="user" + tool_result 块归一成与 role="tool" 相同的轨迹步(每块一个 ("tool", id))。以前整轮 Claude 读起来是一串普通 user 消息,配对检查根本看不见结果——专门用来抓孤儿 tool_use 的那条不变式,在唯一会因此报 400 的 provider 上是瞎的。
  • 流式工具轮的旁白不再糊进终答:以前 model_response.content += chunk 跨过整轮工具往上累加,Claude 中间 assistant(tool_calls) 的 content 又是 block 列表,落盘 isinstance(str) else "" 写成空串,所有旁白(包括模型自己吐的单独一行 count)堆在 jsonl 最后一条。现在中间旁白留在对应的 assistant(tool_calls) 上(抽出 text block),终答只留最后一轮;Claude/Ollama 也不再在每轮流结束 yield \n\n。不滤 count——那是模型输出。
  • sanitize_messages 不再把 Claude 的成功结果标成中断:Claude 用 role=user + tool_result 块回答,以前只认 role=tool,每条成功调用前都插一句「execution may have been interrupted」。现在先吃掉这些块再判断缺没缺。format_tool_results 的缺 id 补齐落到 OpenAI/Ollama 基类,中断回合不再只靠下一跳 sanitize。
  • Claude 回合中断后不再留下孤儿 tool_use:Anthropic 要求每条 tool_use 都有对应 tool_result。以前按位置 zip,中断或乱序返回就会贴错 id,后续每跳都 400。现在按 tool_call_id 配对,缺的补一条 interrupted 错误;这类 400 走 transcript sanitize,不再原样重发。
  • delegate 不再偶发选错模型:不填 model 时子进程走当前会话的 profile(session_profile),不再按 model_name 扫 config.yaml 里第一个同名的。两个 profile 共用一个模型名时,对得上 base_url 才映射,对不上就带父会话的 --base_url,不猜。model 里带 / 的先当完整 id(代理的 openai/glm-5,或环境上下文的 provider/<id>),对不上再拆 provider/name。
  • read_file 的 tail=0 不再报错:模型把 tail=0 当成「从头读」,以前抛 tail must be >= 1 白烧一轮。0 / 省略都是从头按 offset/limit 分页;tail=N(N>=1)才是末尾 N 行,文件比 N 短就整份返回;负的 tail 当成末尾 |N| 行。docstring / tools.md 写明两套分页,不要用 tail=700 表示「从头读 700 行」(那是 limit=700)。
  • execute 的 docstring 不再教 grep:搜文本走 rg(rg -g '*.py' -n PAT),并写明 -r 在 rg 上是 --replace 而非递归。旧文案写 rg -g '*.py' -n PAT -- path || grep -n PAT path,把两者并列成可互换:grep 一侧指向目录时不带 -r 当场报 Is a directory,于是「补 -r」的习惯被搬到 rg 上写成 rg -rn——rg 没有 -r,它把输出里每个匹配静默替换成 n 且退出 0。实测会话里 133 次 rg -rn、结果被污染成 file:n,读的人(和模型自己)都看不出少了什么。命令不改写。
  • 切模型只留问答文本,OpenAI ↔ Claude 双向可跑:/model(含 /config set 真换了模型)把 thinking、tool call/result 都剥掉,只保留 user 问题和 assistant 回答。thinking 的 signature 绑签发模型,带着切就是 400;切模型本身是新一轮问答,那些内容也不值钱。能力按 wire 格式(OpenAIChat vs 原生 Claude),不按模型名猜。同会话里 cache_control 仍不准打在 thinking 上;Layer 1 缩过 tool_use.input 的旧回合同时丢掉旁边的 thinking。
  • Layer 1 不准动正在跑的那一轮工具(参数和 result 都不动):上下文一紧就把调用参数切成 …[truncated],或把刚返回的 tool result 换成淘汰占位符,agent loop 等于吃掉自己的证据。live_tool_round_start 按消息位置护住未返回的调用和末批 result,不认工具名:内置 write_file / execute / grep / glob、SDK tools=、CLI --tools、Web extra、MCP 都在这一轮里。更早回合的超长参数换成 {"$evicted": N} 对象,不是原文前缀,也不是一段可当正文的字符串。
  • execute cat 超大文件不再撑爆 live round:以前 communicate() 把整份 stdout 读进内存,Layer 1 又不能淘汰刚返回的那一轮,下一跳直接超 max context window,CLI 收尾再甩 Event loop is closed。现在管道按 max_output_length 落盘预览(硬顶 64MiB 后杀进程),结果只留 <persisted-output>;读文件走 read_file(offset/limit/tail),不要整文件 dump。硬上限截断的头文案写 INCOMPLETE,不再说 Full output / 去 read_file 当全文;开了 AGENTICA_REDACT_TOOL_OUTPUTS 时落盘副本也脱敏。主动 SIGKILL 不当作命令失败。Layer 0 失败也截断,不再把原文送进下一跳。OpenAI 客户端跟 Claude 一样绑当前 loop,close_client 先摘掉再 aclose,避免关 loop 后 httpx __del__。
  • CLI 退出 / 回合里的 EINTR 不再甩堆栈:macOS 上 Ctrl+C 会打断 getcwd 等系统调用,Python 抛的是 InterruptedError([Errno 4] Interrupted system call),不是 KeyboardInterrupt。以前回合里当成「provider 挂了」,finally 里无条件 worktree_binder.release()(没开 --worktree 也跑 git/getcwd)再中一次就跳过告别语。现在没进过托管 worktree 的会话退出是空操作;进过的也按用户中断处理,清理失败不挡正常结束。
  • 流式中途断流按 max_api_retry 同 turn 重发:SSE 被掐(incomplete chunked read)发生在已吐 chunk 之后,stream_with_retry / _call_with_retry 都接不住。Runner 消费点回滚本轮 model_response 内容并重开流,预算与同模型 API retry 共用(CLI 默认 2,即再打一次);耗尽照旧抛。已 yield 的 chunk 收不回——交互会重打一段,--print / delegate 的 stdout 会拼上半截。同时修了 _call_with_retry 分类:RETRYABLE(含 incomplete chunked read)先于 FALLBACK_ONLY(含 connection),否则这类断流永远走 fallback、从不在同模型上重试。
  • apply_patch 信封按 Codex/OpenCode 宽松提取:小模型常把补丁包进 ```patch 围栏、前面加说明、漏 *** End Patch,或写成 {"patch":"..."},以前一律报 Patch must start with '*** Begin Patch'。现在找出 Begin/End(或裸的 *** Update/Add/Delete File:)再解析;hunk 仍精确匹配,缺 File 头或行首不是空格/-/+ 照旧拒绝。
  • apply_patch 对不上时点出那一行:Hunk N: context not found: '…' 带上 hunk 里文件中不存在的那一行,不再只报一句 not found。不回 Expected/Actual 预览。
  • apply_patch 对不上时分清「行不存在」和「行在、但不连着」:hunk 里每行都能在文件里找到、只是中间跳过了几行时,以前把第一行 keep 报成 not found: '…'。模型刚 read_file 过那一行,以为工具在撒谎,再读一遍。现在写 not found as a contiguous block (line N). file: …, hunk: …。真缺的行仍报 not found: '…'。
  • apply_patch 找回忘了前导空格的 keep 行:无 /-/+ 前缀的行若与当前文件某行完全一致(或去行尾空白后只对应一种原文),当成 keep;对不上或多种原文仍报 Malformed patch,不做空白/缩进 fuzzy。

changes

  • 安装改推 uv tool install,不再把系统 pip install agentica 写成产品入口:CLI 用 uv tool install agentica,Web / Desktop 用 uv tool install "agentica[gateway]",装进隔离环境、不绑系统 Python。已经装过 CLI 再补 extras 是 uv tool install --force "agentica[gateway]",升级是 uv tool upgrade。uv add agentica 留给自己的项目当库用,pip install -e . 留给改本仓库。README / 安装页 / Gateway / API extras 同步改了。
  • CLI 去掉已废弃的 _GutteredConsole 和从未调用的 display_tool_call:左侧 gutter 早就不画了,代理类和 agentica.cli.display_tool_call 导出只剩死代码。
  • worktree 用法改走内置 skill,人用 /worktree:工具还在。以前每轮把整段 <worktrees> policy 塞进 system prompt。现在判断在 agentica/skills/bundled/worktree/,目录匹配才读;人用 /worktree status|new|merge|remove(和 --worktree 同一套 binder)。
  • peer 收信规则并进 multi-agent skill:list_agents / send_message 仍每轮注册。以前 PEER_MESSAGING_POLICY 每轮塞进 system prompt(授权头、证据用路径、peer 派的活不要 ask_user_question)。现在只在目录对上、模型去读 skill 时才进上下文。消息头 format_for_model 和 ask_user_question 的「这个框能到谁」仍每轮在。
  • cron 用法改走内置 cron skill:cronjob 工具还在。以前 CronTool.get_system_prompt() 每轮灌用法 + 按表面切换的 daemon_hint(CLI 写 /cron daemon on,gateway 写 cron.enabled)。现在判断在 agentica/skills/bundled/cron/,两种开 daemon 的办法写在同一份 skill 里按表面选;daemon_hint / CLI_DAEMON_HINT 删掉。人用 /cron(skill 同名 auto-command 让位给已有斜杠命令)。
  • apply_patch 默认形态改成一条补丁改多个文件:docstring 示例两个 *** Update File;要改的文件先并行 read_file,再一条补丁。以前示例只有 app.py、文案写「先读当前文件」,模型就读一个改一个。精确匹配没变。
  • multi-agent skill / 文档不再把「要并行」写成 delegate 的理由:task 一条消息里就可以并行多个(concurrency_safe)。对比表补上 Parallel 行;delegate 只为独立 context / 换目录 / 要写文件。
  • CLI / Web 的 apply_patch 调用行显示工作区相对路径:以前只报 Edited 1 file (+8 -3),看不出改了哪个文件。现在和 read_file / write_file 一样带上路径(apply_patch agentica/cli/commands/session.py - Edited 1 file (+8 -3));多文件逗号并列。
  • execute 不再规定必须一条长命令:依赖可用管道/&&,互不依赖可同一轮多条 execute(parallel_safe=True),怎么拆交给模型。不要用 shell 倒整份源码(cd && cat f.py 是 read_file),也不要用 execute 改仓库:同一替换是 rg 列出位点再一条多文件 apply_patch。路径 grounding 只卡 read_file / write_file / apply_patch;execute 可以复用已知路径、从 . 搜,或对候选加 2>/dev/null。以前写「prefer one long / 不要 N 个 grep」会把独立探查焊成一条超长脚本。
  • CLI / Web 的 write_file 调用行显示工作区相对路径:以前只留文件名(session.py),和 read_file 的 agentica/cli/commands/session.py 不一致。现在两边都走同一套缩短(cwd 下相对,工作区外保留原路径)。
  • 去掉 @agentica-ai/sdk 的 GitHub Actions 自动发布(删除 .github/workflows/npm-publish.yml):和 PyPI 一样改成仓库里手动 npm publish。v* tag 不再二次 PUT;1.4.15 已经 staged 过,Actions 再推一次会 E409,而 npm view 看不见 staged 版本,跳过检查拦不住。

[1.4.15] - 2026-09-01

breaking

  • CLI /export 默认导出 session JSONL,不再是对话瘦 JSON:以前 /export / /save 把 working_memory.messages 存成一份没有 event、没有工具正文的 JSON。现在默认拷贝磁盘上那份 <session_id>.jsonl(与 Web 轨迹同一文件)。旧行为改为 /export messages [path];/export analysis [path] 写出与 GET /api/sessions/{id}/trace/analysis 相同的 JSON。
  • apply_patch 只精确匹配上下文:不再对空白 / 引号做 fuzz。对不上就是 Hunk N: context not found。死的 SDK 类 PatchTool(双格式 unified/V4A)删除;补丁走 BuiltinFileTool.apply_patch,模块只留 apply_diff / parse_patch_envelope。
  • 删除 write_html 和 ShellTool:长报告用 write_file 写 HTML;shell 用 execute / BuiltinExecuteTool。get_builtin_tools / DeepAgent 去掉 include_html_report。
  • grep 只留 pattern / path / limit:去掉 include、output_mode、case_insensitive、fixed_strings、context_lines / before_context / after_context。按文件名过滤走 glob 或 execute 的 rg -g。
  • DeepAgent / get_builtin_tools 去掉 peer_conflict_checker:编辑成功后不再附「别的会话也改了这个文件」提醒。

features

  • npm 包 @agentica-ai/sdk(sdk-ts/):给跑着的 agentica-gateway 用的 TypeScript HTTP 客户端(session / chat SSE / 审批),不是 Python Agent 的移植。Web 启动路径不变,仍是 agentica-gateway;PyPI wheel 继续打进编译好的 UI。发布走 GitHub Actions:tag v* / sdk-v*(或手动 Run workflow)npm publish 到 https://registry.npmjs.org/@agentica-ai/sdk(org agentica-ai,secret NPM_TOKEN,npmjs 账户 shibing624-xm)。已经发布过的 version 会跳过,避免 Python 发版 tag 把同一版再推一次。
  • Gateway Docker 镜像:Dockerfile 用 Node stage 编 Web UI,再 pip install ".[gateway]"。仓库根 docker-compose.yml 一键起自托管服务;本机 pip / Desktop 不受影响。
  • explore / code 子代理会用只读 execute 管道:execute 本来就在 allowed_tools 里(execute_policy: read_only),但 explore 的 prompt 只提 glob/grep/read_file,包装后的说明也只写 git/测试,模型就不会 cd 到工作区外的树去 rg。现在 prompt 和只读 execute 说明都写上 rg/find/head 管道。
  • execute 输出里出现的路径也算 grounded:rg 等扫到的精确路径字符串可以直接给 read_file / apply_patch,不必再绕一次 glob。read_file 仍只 grounded 它打开的那一个文件。
  • web_search 新增 serply 引擎(SearchSerplyTool):Serply 的 Google 搜索 API,SERPLY_API_KEY,无额外依赖(pip install agentica[serply])。同一个 key 还覆盖 Google News / Google Scholar:SDK 传 SearchSerplyTool(search_type="news"|"scholar"),web_search 分发器路径用 AGENTICA_SERPLY_SEARCH_TYPE 切换,模型看到的工具名不变。CLI --tools search_serply。API 文档见 serply.io/docs。
  • apply_patch docstring 示例以 +# 插入注释开头:@@ 后第一行就是新增,避免模型先整文件空格拷贝造成空操作。空操作不再报 Malformed patch。首行已是 *** Update/Add/Delete File: 时自动补 Begin/End Patch(正文语法不变);markdown 围栏和其它缺信封仍拒绝。
  • CLI 并行工具改成 Kimi 式整块 flush:未完成的调用停在输入框上方的 live 窗口,按开始顺序等前缀都结束后才把「调用行 + 结果」一起打进 scrollback。以前 execute 一开始就打印调用行,并行的 grep / write_file 结果会插在调用和 ⎿ 之间,看起来像挂错工具;现在不再需要 ↳ 锚点。--print 不变。
  • CLI / SDK 与 Web 共用同一套 session 轨迹出口:一份 JSONL + SessionLog.analyze()。SDK:agent.session_log(公开句柄)、.format_trace()、.export()。CLI:/trace 打 rounds/tokens/工具(/trace <n> 展开一轮),/status 增加 Session log 路径(原 Log file 改名为 Debug log,避免和 jsonl 混淆)。Gateway /trace/analysis 改为调用 log.analyze(),不再手拼一份。公开 API 见 docs/API.md。
  • /goal 默认 token 预算不限:CLI /goal xxx 与 SDK run_goal() 不传 token_budget 时不再回落 500_000(DEFAULT_TOKEN_BUDGET 改为 None)。要限额度显式传 --tokens N / token_budget=N;-1 仍是不限。Web 目标芯片默认显示「预算不限」,点一下才打开 Token 预算输入(空=不限,支持 500k/2m),Escape 关掉输入框而不退出目标模式。

fixes

  • CLI 渲染工具输出 / 纯文本回答时不再把 [/xxx] 当成 Rich 闭合标记:execute 结果里的 [/usr/bin/cmake]、grep 路径、agent 纯文本里的 [/red] 以前走 console.print(..., markup=True),Rich 抛 MarkupError,整轮报 Agent execution failed。现在不受信任的正文 markup=False,拼进标记串的字段先 escape()。
  • Web 打开 CLI 会话(以及刷新后的网页对话)不再丢掉 tool call / 结果:hydrateSession 以前只把 session JSONL 里的 user / assistant 正文拼成气泡,assistant.tool_calls 和 type: "tool" 行直接丢掉,所以侧栏里点开 CLI 会话只剩问答、没有 WorkGroup。现在按 harness 同一条规则重建:一轮用户提问折成一条 assistant(思考 → 工具卡 → 终答),参数和结果走与实时 SSE 相同的 parts。打开会话时以服务端日志为准覆盖本地缓存(正在流式的会话不覆盖)。
  • search_memory 搜对话归档不再 NameError:按 --- 切 block 用了 re.split,模块顶上没 import re,一点到 conversation 源就炸。
  • apply_patch docstring 补回「改之前先 read_file」:Update/Delete hunk 必须对着当前文件原文,不能凭记忆拼上下文。
  • CLI 回答 ask_user_question 时能看到完整选项:提问组件和 live 窗口抢同一块底部高度,live 的 LIVE_MAX_ROWS=12 把选项挤出屏幕。有未决提问/审批时收起 live;选项折行按显示宽度(get_cwidth)预留行数,中文不再按 len 少算导致后几项被裁。
  • apply_patch 去掉误导性 Expected/Actual 预检预览:上下文对不上只报 Hunk N: context not found;缺 *** Begin Patch、hunk 行没以空格/-/+ 开头,报 Malformed patch,不再包装成「preflight + Actual from line N」。原子写入(失败不改任何文件)仍在。整函数重写用 write_file。
  • 工具结果不再塞启发式旁白:execute 非零退出只报 exit code(仍按命令决定要不要 raise),不再附 Note;write_todos 不再 verification nudge;空文件返回 File is empty: … 而不是 <system-reminder>;fetch_url 去掉四条 IMPORTANT;background=True 成功结果只留 id / pid / log。路径 grounded 政策只写在 tools.md。编辑后的 LSP/Pyright 诊断仍附在 write_file / apply_patch 结果上(--enable-diagnostics),缩进对不上时能直接看到。
  • CLI live 窗口跨线程读写加锁,provider 断流也会 flush 在飞工具块:spinner 每 120ms compose_live 与 turn 线程同时改 LiveToolStore 的 OrderedDict,迭代中增删会让 spinner 线程静默死掉、状态栏冻结。store 加锁、读侧快照,spinner 循环包异常;泛化 except Exception 与取消路径一样调 abandon_live()。
  • CLI live 窗口跟进:并行 task 按 description 绑 subagent;结果 id 对不上时先打完整 call+result;剥 Rich 标签不再吃正文 [...];删掉已无生产引用的 _ToolResultSequencer;行数上限 LIVE_MAX_ROWS=12 只定义一处。
  • Layer 2 空摘要不再当成压缩成功:auto_compact / _summarise_conversation 对摘要 strip(),空白或抽不出正文(含把空 resp str() 成对象 repr 的路径)整段放弃,不替换 messages、不写 compact_boundary。WorkingMemory 里的空白 session summary 不再走 SM-compact,回落到真正的摘要 LLM。
  • CLI 状态栏未配置的思考强度显示 default 而不是 off:config.yaml 没写 reasoning_effort / reasoning 时请求里根本不带这个字段,API 用它自己的内置强度;以前 describe_thinking_mode() 把「没写」当成关,状态栏就打出 opus-5-openoneapi openai/claude-opus-5 off。现在未覆盖是 default,只有显式 off/none/disabled 才显示 off。

[1.4.14] - 2026-08-25

breaking

  • agentica.subagent / agentica.subagent_loader 挪到 agentica.subagents:内置定义从 agentica/agents/*.md 改到 agentica/subagents/bundled/*.md(和 skills/bundled 同结构)。运行时 from agentica.subagents import SubagentRegistry;加载器是 agentica.subagents.loader。不留旧模块。用户/项目目录 .agentica/agents/、$AGENTICA_HOME/agents/ 和 /agents 斜杠命令不变。
  • SkillRegistry.get_skill_instruction() / generate_skills_prompt() 删除:生产 catalog 一直是 SkillTool.get_system_prompt()(自进化 spawn 也是写盘后再走这条)。两条是死 API,catalog 预算改挂在活路径上,不再维护第二套按注册序截断的 XML 列表。
  • GET /api/memory 不再返回用户级 AGENTS.md:payload 改为 {auto_extract, index_path, entries}(MEMORY.md 索引)。常驻规则改走 GET/PUT /api/user_agents_md。PUT /api/memory 删除(405),避免旧前端把 AGENTS.md 正文写进记忆结构。
  • 权限档 ask 改为 Codex「Ask for approval」:以前 ask 会从 schema 里藏掉写工具(write_file / execute / apply_patch 等,模型看到 Function not found);现在三个档工具都在,差别只在真正 execute 之前要不要停车等人。ask:读(含工作区外;文件工具 + 只读 shell,含 cd && git diff | head 包装)自动放行;写(write_file / apply_patch,含工作区内)、会改状态的 execute、web_search / fetch_url、硬不安全路径/命令停车。auto:再放行工作区内写、普通 execute 和网络。allow-all 不询问、不拒绝(含硬不安全;项目「拒绝类似」只约束 ask/auto)。删掉模型可见的 request_path_access,改由公开 grant_path_access 写入沙箱白名单。默认不变:CLI / SDK 仍是 allow-all,Web 仍是 auto。无人值守(无 LiveTurn:IM / cron / 非流式 POST /chat / --print)立即把工具结果写成 Tool call denied by user.,不 500、不 sibling-abort。
  • 审批增加 deny 路由和「拒绝类似」:classify 返回 allow | ask | deny。三档权限嵌套:auto ⊃ ask,allow-all 是 root。ask 下 web_search / fetch_url 和工作区内写文件弹卡;auto 放行网络和工作区内写,硬不安全仍弹卡。新增 deny_prefix(CLI x / 4,Web 拒绝按钮下拉「拒绝类似」),写入 project.json approvals.deny_command_prefixes 等,下次同类在 ask/auto 下不弹卡直接拒。allow-all 忽略项目拒绝,只 warning + 记 approval_decision(allow_all_ignore_deny / allow_all_hard_unsafe),命令照跑;进程用当前 OS 用户的权限,能 sudo 就能 sudo。用户在 ask/auto 点允许之后,执行时的 check_command_safety block / sandbox blocked_commands 不再跟卡打架。
  • 系统 skill 不再拷贝到 $AGENTICA_HOME/skills/.system/,改为包内原位加载:CLI / gateway 的 load_system_skills() 把搜索路径末尾直接指向包内 agentica/skills/bundled/,ensure_system_skills()、skills/.system、内容哈希指纹同步整套删除(同仓库 subagents/bundled 一直是这个模型)。拷贝本来就不是正确性前提(复制失败时回退的就是包路径),却让每次产品启动都扫树做 sha256、只读 home / 容器 / CI 走 OSError 降级、.system 与 bundled/ 双源难查、模型看到的 Path: 在 home 里像用户资产其实升级即被覆盖;SDK 侧「不捡到 CLI 残留」的隔离测试面也随之消失(.system 点开头,目录发现本来就不扫)。覆盖方式不变:~/.agentica/skills/<name>/ 同名 user skill 优先级更高;Web 插件 API 的 editable = (location == "user") 不受影响,bundled 依旧不可编辑。

fixes

  • 权限档文案与 classify() 对齐:ask 的读(含工作区外)与 auto 相同,只拦写、会改状态的 shell 和联网。CLI --permissions / /permissions、Web Permission 提示不再写成「只有工作区内读才自动」或「ask 只有只读工具」。
  • execute 超大输出改为落盘预览,不再静默丢掉中间段:原先 max_output_length(默认 20k)先做 40/60 头尾截断,中间直接丢;max_result_size_chars=50k 的 Layer 0 落盘永远触发不了。现在超过 20k 写入会话 tool-results/,上下文只留路径 + 行数 + 头尾预览,后续用 read_file/grep 查。成功与非零退出(失败命令的巨型 traceback)都走这条路——Layer 0 钩子挪到结果内容组装之后(错误文本先脱敏再落盘,spill 文件不碰密钥),原先挂在「仅成功」分支上,报错路径仍然丢中间。
  • SDK print_response_stream 不再把工具事件漏进回答:show_tool_calls=False 时原先不跳过 ToolCallStarted / ToolCallCompleted,Running tool: read_file 会被当成正文打印。现在走和 CLI / Web 同一套 classify_run_response,工具事件无论显不显示都不会进答案。
  • CLI 审批卡裁掉「拒绝」、两项时跳号:rm /path 这类不能「允许类似」的命令本来就只有允许/拒绝,但 TUI 把整段卡当成一行再多塞一个换行,高度少算一行,拒绝被裁掉,屏幕上只剩 1. Yes, proceed (y)。同时拒绝还写死成 3.,2 仍绑「允许类似」。现在按可见选项连续编号(两项就是 1 允许 / 2 拒绝;四项仍是允许、允许类似、拒绝、拒绝类似),数字键跟着走;长命令按终端宽度预留折行高度,不再把选项挤出屏幕。SDK / Web 同一套 options,没有类似可批时本来就不渲染那两个按钮。
  • CLI 拒绝文案不再催用户写原因,审批后命令留在 transcript:拒绝从 No, and tell the agent what to do differently (esc) 改成 No, deny (esc/n)(esc / n 都是直接拒,不追问理由)。审批卡画在输入区 layout 里,决定后整段卸掉,$ rm … 会跟着消失。现在卸卡之后把命令和 ✓ allowed / ✗ denied 打进 scrollback。
  • Web 审批卡按 Enter 会整轮「已中止」:卡上「允许一次」标了 ⏎,但焦点在输入框时 Enter 被当成「空输入为停止」。有未决审批时输入框禁用(附件 / slash / 粘贴也停),只留停止;Enter 允许一次、Esc 拒绝。残留草稿不再插入当前轮。
  • Web 侧栏会话状态与对话页被误删:deny_prefix 那次提交冲掉了 sessions.ts 的 lastTs / unread / syncSessionStatus,以及 ChatPage 的左侧 query 导航(ChatNav)、settleWork、已读 markSessionRead、以及 running 清位。已从上一版补回,审批卡仍带 deny_prefix。

features

  • 工具说明去掉二进制黑名单,改为正面能力描述:execute docstring、tools.md、ShellTool 不再写「not cat / not find / not sed -i / MUST avoid find」式禁令——实测这类禁令把强模型推向更差的绕行路径,且多处文案互相矛盾。管线正例只留程序输出整形(pytest | rg '^FAILED' | sort、rg … | head、git diff | tail),不点名、不示范 find / cat / ls / awk / sed -i。grep content 模式的 limit 是全局条数上限:stdout 读满 limit 行即杀掉 rg(不再用每文件 --max-count,也不再 communicate() 整棵树再切片)。read_file 支持 tail 和负 offset(offset=-50 即最后 50 行,配 limit 取窗口内最旧的若干行);tail/负 offset 不再被 256KB 守卫拦住(守卫只拦从头分页;报错只建议 tail,正 offset/limit 过不了守卫)。从尾扫描超过 20 秒超时。
  • SDK print_response / print_response_stream 默认展示工具,调用行跟 CLI 同一套文案:默认 show_tool_calls=True(仍可关掉)。工具行用 format_tool_display(read_file foo.py (L1-80),不再打原始 dict);read_file / glob / grep 成功时只留调用行,和 Web 一致。思考在工具之后再出现会再打一次 💭 THINKING,时间线是思考 → 工具 → 思考 → 回答。
  • Skills catalog 按模型上下文窗口的 2% 做 token 预算(无窗口时退回 8000 字符)。单条 description 硬帽 1024 字符(从前截)。超预算先从列表尾部丢掉 description(保留名字),仍超才 omit 并注明条数。卫生规则写进 prompt:匹配才用、当轮读完 get_skill_info、不跨轮携带、不深追 references。freeze_session_guidance() 仍然冻住整块,不每轮重排。
  • 粘贴/输入里的非法 UTF-8 不再打崩 CLI、Web、SDK:孤立 surrogate(例如 U+DCE5)以前在 .encode("utf-8") 上炸掉 Enter 写历史、agent 落盘和 Langfuse OTLP。CLI 入口、Agent.run / steer、Web ChatRequest / SteerRequest / GoalRequest 都换成 U+FFFD,相邻汉字不动。
  • Web 侧栏会话时间改为「多久没发起 query」:原先 agoStr 用的是 first_timestamp(会话第一次请求),所以一直聊的对话也会显示 7h。现在用 last_timestamp,有本地 transcript 时再取最后一条非 steer 用户消息;文案按界面语言粗粒度显示(刚刚 / 5 分钟一档 / x 小时前 / x 天前,英文 just now / 5 min ago / x hours ago / x days ago)。选中行的时间不再叠一层 background(原先 --bg2 盖在 --accent-soft 上会变成一块深色芯片)。组内会话按最近一次 query 排序;项目组顺序仍按该目录第一次对话。
  • Web 侧栏会话状态:回复中转圈 / 未读绿点 / 空闲时间:发完 query 切到别的会话时,原会话 title 右侧不再显示「刚刚」,AI 思考、tool call、压缩期间是转圈;回复结束后如果没打开过就是绿点,点进去看过才回到时间标签。last_read_at 写在 session sidecar,GET /api/sessions 带 unread / running,打开会话会 POST /api/sessions/{id}/read。旧会话没有 last_read_at 不当未读。
  • Web 对话左侧 query 导航条对齐 Codex minimap 设计:左侧留白区域默认只展示极窄短横刻度,鼠标悬浮短横时在右侧弹出不透明浮窗(圆角、边框),展示截断 query(前 50 字、最多两行);点击平滑直达对应问答轮次并带微光闪烁反馈;当浏览器宽度收窄(≤ 1024px)时自动隐藏,不侵占主对话区域。
  • 自动抽取的记忆带上会话证据,search_memory 回读 provenance:write_memory_entry(evidence_refs=) 原先只在手动写入时用得上,抽取结果没有来源。现在 MemoryExtractHooks 把抽取窗口归档后写入 evidence_refs;search_memory 每条结果带 title / memory_type / memory_source / evidence_refs。评测脚本在 evaluation/reconcile_mem/。
  • auto 只拦工作区外的文件写:读(含工作区外的 skill/SKILL.md)、工作区内写、全部 execute、网络、以及 self_manage / cronjob / skill 等内置工具(不看 action)一律过。ask 的读与 auto 对齐(含工作区外);拦写文件(含工作区内)、会改状态的 shell、以及 web_search / fetch_url。记忆、task / delegate、skill 和其它内置工具直接过。self_manage show 不再把 compact_token_limit 当成 secret;api_key 只藏中间(含 fallback_models / auxiliary_model 里的 key)。
  • 轨迹 approval_decision 带上审批卡和用户决定:停车才写。事件里有工具名、入参、question/preview、可选「允许类似」标签、档位、等待秒数(wait_s,两位小数)、以及用户点的 allow / allow_prefix / deny。选了允许类似时把写入 project.json 的 grant(命令类 / 路径前缀)记在同一条上,不再只剩 decision + tool_call_id。
  • 工具审批停车(CLI / Gateway / Web 同一套 ApproveFn):Runner 在 fc.execute() 之前、wait_for 120s 超时之外调用 Agent.approve。Gateway 的 ApprovalRegistry 只住在 LiveTurn 上(不是 Agent 缓存);SSE tool_call 带 tool_call_id,新事件 approval_request(刷新按 seq 回放并重推未决项,不看当时有没有 SSE 订阅者);POST /api/sessions/{session_id}/approvals/{tool_call_id} 提交 {decision: allow|allow_prefix|deny|deny_prefix}(按账号鉴权,未知 id 404)。取消或结束 deny_all;有未决审批的 Agent 不被 LRU 清掉。CLI 对齐 Codex 选项(y / p / esc / x),并行 tool_call 串行弹卡,Ctrl+C 拒绝全部。Web 底部固定一张卡(拒绝 Esc + 下拉「拒绝类似」/ 允许一次 Enter / 下拉「允许类似 rm -f 命令」),刷新按 tool_call_id 挂回工具行。allow_prefix / deny_prefix 批的是命令类(rm -f,不含文件名),写入该项目 project.json 的 approvals(与 work_dir / active_profile 同文件),重启 CLI / gateway 仍生效;「允许/拒绝一次」不落盘。复合命令不能「允许/拒绝类似」。/permissions 改为三档说明。
  • Web 对话 run 与 SSE 连接拆开:刷新 / 断网只断开订阅,后端继续跑。POST /api/chat/runs 立刻返回 run_id;GET /api/chat/runs/{id}/events?after= 按序号重连去重;GET /api/chat/runs/active 找回当前 session 的 run;POST /api/chat/runs/{id}/cancel 显式取消并等到 session lock 释放(已结束则幂等返回终态)。Stop 在 lock 释放前不允许发下一轮(新输入排队)。发送后立刻出现 WorkGroup「正在思考」转圈(有附件时是「正在准备附件」),不再空白等到首字。live_turn / Agent 缓存 / session lock / work_dir / 审批档都按 (账号, session_id) 分区,session_id 是客户端可控字段,不能让 B 账号的 409 或删除碰到 A 的 run。list_sessions 会并上该账号尚未落盘的 live run,刷新不会让刚发出的新对话从侧栏消失。
  • Web 工具调用入参跟 CLI 同一套展示:对话里不再 json.dumps 原始参数。read_file / glob / grep 一行路径;write_file / apply_patch 文件名或文件数(结果仍是 diff);execute 命令;write_todos 清单;web_search / fetch_url 查询或 URL;task / delegate / send_message 全文;list_agents 只显示名字;其余 key=value 摘要。轨迹页仍是原始 JSON。
  • Worktree 默认短命、落在仓库内:默认路径改为 <repo>/.agentica/worktrees/<任务>(不再是兄弟目录 ../<repo>-<任务>;settings.worktree.root: sibling 可回到旧布局)。worktree(action="merge") 合入本地 base 后删除 checkout 和 wt/<任务> 分支,会话回到主目录;进行中的同名 use 仍复用。新增 remove。会话绑定期间 git worktree lock(agentica pid=<pid>),活着的别人的锁和用户手加的锁都不抢;pid 已死才偷锁。删除前的安全标准是「agentica 的 wt/ 分支 + 没有独有工作」(干净且不 ahead 本地 main),不是「是否已 push」;detached / 手建 / Claude Code 的树一律不删。退出 CLI 时,没有独有工作的 wt/ worktree 自动清掉,有独有工作的保持 lock。.env 仍是 symlink。use 发现别人持锁时会点名 pid。工具 remove 先校验再搬家。
  • web_search 默认引擎从 baidu 换成 exa:走 Exa 公开 MCP(https://mcp.exa.ai/mcp),不设 EXA_API_KEY 用共享免费池(有限流),设了走自己的额度。和 OpenCode 同一条免费接入;AGENTICA_WEB_SEARCH=baidu 或 provider="baidu" 仍可选。环境变量配了需要 key 却没给 key 时,降级目标也跟着改成 Exa。
  • Web 对话回答列对齐 980px、正文 14px:原先 .msg-stack 再套一层 min(760px, 88%),宽窗口两侧留白,开着工作区面板时表格还被压到约 600px。现在 assistant 列跟 .msgs 同宽,用户气泡仍是聊天宽度;输入框 max-width:980px 与对话列对齐。段距 / 列表 / 表格 / 标题一起从 compact 终端密度调到网页可读。
  • glob / grep 硬超时从 3s 调到 20s(_GLOB_TIMEOUT / _GREP_TIMEOUT):3s 会误杀本地大仓、冷盘和没有 rg 时的 Python fallback;仍不暴露给模型。对齐 kimi-cli / Claude Code 的 ripgrep 20s 上限。glob 继续留超时:当前实现是 pathlib.glob 整树走完才返回,结果上限挡不住 NFS hang。
  • 设置 › 模型配置顶部只留 config.yaml 路径:去掉当前 profile / 模型 / effort / context / compact 那一行摘要,列表里本身就能看到谁在用。
  • compact_token_limit:压缩工作阈值,不改模型 context_window。1M 窗口可以配 300000,Layer 2 在 min(该值, 窗口×0.95) 触发摘要;Layer 1 的 0.8/0.5 相对 min(该值, 窗口)。不配则和现在一样(约 95% 窗口才摘要)。写在 config.yaml 的 profile 上,也可写 settings.compact_token_limit 做全局默认。CLI:/config set compact_token_limit 300000、--compact-token-limit。Web 模型配置有填才显示。SDK:ToolConfig(compact_token_limit=300000)。
  • 设置 › 记忆拆成两层:上半编辑用户级 AGENTS.md(常驻规则,进 system prompt);下半「生成对话记忆」开关仍接 auto_extract_memory,列出的是 MEMORY.md 索引条目,不再把 AGENTS.md 预览假装成抽取结果。CLI / SDK / Gateway 同一套注入:会话开头把 MEMORY.md 索引(标题+hook+相对路径,最多 60 行 / 4KB)冻进 prompt 并点名绝对路径,memory/*.md 正文按需 search_memory / read_file。抽取仍大约每 10 轮。已知限制:write_user_agents_md 会清掉共享 Workspace 上的 _context_snapshot,Gateway 下一轮所有会话会重建 AGENTS.md 前缀(快照应按会话持有,v1 不改)。
  • 「Profile」中文改叫「模型配置」。
  • 个人助理的 Web 地址可点:和 config.yaml 一样走 POST /api/open,用系统默认浏览器打开 http://127.0.0.1:8881/chat。
  • 个人微信默认就能扫码:WECHAT_TOKEN_FILE 默认 ~/.agentica/cache/wxbot_token.json,WECHAT_ALLOWED_USERS 默认空。gateway 启动不再弹码;网页点「配置」才生成二维码(过期约 120 秒)。没扫或过期显示「失败」;离开再进个人助理页,码是空的,要再点配置。
  • 微信 / 网页 / 桌面是同一个人:点「配置」扫码时登录的账号就是机主。IM 不再用微信 openid 另开 users/<openid>/ 分区;会话、记忆、AGENTS.md 都进这个账号。已连上的再点一次「配置」也会绑到当前登录账号。
  • 设置 › 个人助理:设置弹窗第二个 tab(常规旁边),展示本机 Web 地址和微信 / 企微 / QQ / 飞书等 IM 的接入状态与连接方法。账号菜单同一项打开这个 tab。/assistant 仍是同一套内容的独立页。GET /api/channels 增加 catalog / web_url / listen。
  • 桌面版第一次打开会自己装 Python runtime:安装包仍然不含解释器(壳最难更新)。找不到 agentica-gateway 时用 uv 在 Application Support 装 CPython 3.12 + agentica[gateway],不进 ~/.agentica;已经 pip 过的继续用原来的。AGENTICA_GATEWAY_BIN / AGENTICA_DESKTOP_NO_BOOTSTRAP 可跳过。
  • CLI 运行中输入提示改直白:Enter 插话显示 Steered the current query. Tip: Tab or /queue queues a request.;Tab 排队显示 Queued the next request. Enter steers the current query.。原先 Guidance added to the current task 没说清 steer 的是当前这一问,也没点出 /queue。
  • CLI 回答按 Markdown 块增量落屏:原先 stream_response 把整段缓冲到 finalize 才一次性 print(Markdown),长回答只能盯着 answering…。现在围栏感知的空行一旦闭合一块(标题/列表/代码/表格)就立刻渲进 scrollback,未完成的尾部仍等结束;不用 Rich Live,避免和 prompt_toolkit 抢光标。cli_markdown=off 仍整段纯文本。
  • 设置 › Profile 顶部是本地 config.yaml:原先「当前配置」和预览弹窗在常规页。现在这块在 Profile 最上面,路径是可点链接,走已有的 POST /api/open 用系统默认编辑器打开(本机 gateway / 桌面版);打不开就 toast。预览弹窗去掉。GET /api/config/file 仍给别的调用方打码读文件。
  • Web 思考与工具按真实调用顺序穿插:思考是组里一行(11px、和工具同行高),正在流式的那段默认展开、正文随页面贴底,不再用 max-height 把最新思考裁在卡片里。工具同样一行一卡。正文仍会打断分组,所以时间线是思考 → 工具 → 回答 → 思考 → 工具 → 回答。流式光标只留在最下面那一个气泡。
  • Web /goal 过程流式:原先 POST /api/goal 只推 status 条,正文等整轮 done 才一次性出现。现在每轮走 run_stream,和普通对话同一套 thinking / tool_call / tool_result / content SSE,工具组和吐字穿插出现;顶栏 tokens 进度仍用 status。停止按钮、插话 chip 也挂到这一轮 live 消息上。
  • Web /goal 只限 tokens,默认不限:原先网关硬编码 turns 15 / tokens 80,000 / wall 300s,状态条三项一起显示。现在对齐 CLI 主闸:只传 token_budget(GoalRequest.token_budget,-1 = 不限,网页默认)。输入 /goal 进入目标模式:先填 token 预算(空=不限,支持 k/m),再写目标。运行中状态条只显示 tokens used 或 tokens used/budget。CLI --turns / --wall 不动。
  • Web 流式吐字贴底跟滚:回答过程中每条 token 不再立刻重跑 Markdown / KaTeX / 高亮(那会把主线程卡住,看起来像输出冻住);按动画帧合并绘制,流式时用轻量渲染。用户没上翻时始终跟到底;程序化滚动不再被误判成「用户离开底部」。
  • Web 插话(steer):输入栏只有一个按钮。空内容是停止;有内容则发送(纯文本走 CLI 同一条 agent.steer())。要排到下一轮用 /queue <prompt>(/q 同义),和 CLI 一样;附件和其它斜杠命令仍排队。插话气泡带图标、虚线框。来不及送达的插话在本轮结束后自动改排队。API:POST /api/chat/steer、POST /api/chat/steer/take。
  • glob / grep 不再把 timeout 暴露给模型(grep 同时去掉 multiline):内部硬超时,不给模型覆盖。此前无上限的 timeout 让模型随手填 60 就能拆掉 fail-fast;跨行正则 fallback 又不支持,有 rg 和没 rg 会搜出两套结果。超时错误改为让模型收窄 path / include,不要原样重试或改走 execute。context_lines > 0 时忽略 before_context / after_context(与 rg -C 一致),写进 docstring。execute / wait 的 timeout 不动。
  • 文件工具去掉 ls / edit_file / undo_edit:编辑只留 apply_patch + write_file(read_file / glob / grep 仍在),方法本身也删了,schema 里不再出现。列目录改用 glob(pattern="*")——它本来就返回子目录,工具 docstring 和 tools.md 里点明了这一点,免得模型退回 execute("ls")。Web 默认审批档是 auto(ChatRequest.approval_mode),不是 ask。task、web_search、memory、list_agents / send_message 仍常驻。CLI / Gateway 不再保留对 ls / edit_file / undo_edit / multi_edit_file 的历史日志渲染分支。越权路径不再走模型可见的 request_path_access(已删除),改为审批卡停车后 grant_path_access。
  • 权限档以 Agent 为准,工具自己那份只在脱离 Agent 单用时生效:Agent 在接线工具时(_wire_tools_to_self)把 tool_config.permission_mode 灌给它持有的每个 BuiltinFileTool。get_builtin_tools() 因此不再有 permission_mode 参数——同一个决定不留两个入口。工作区外写入走审批卡 + grant_path_access,不再挂模型可见的 request_path_access。
  • Web / 桌面版变成真正的多账号产品,seed 的账号从 admin 改名 default:账号名同时是数据分区名(它命名 users/<id>/,也就是会话与记忆的落盘位置),叫 admin 就意味着首启动会凭空造出一个 users/admin/ 分区,而这台机器上已有的对话全在 users/default/ 下——同一个人换个入口进来看到的是空列表。现在默认账号名直接取 settings.default_user_id(即 default),并对已装过上一版的机器做一次性迁移:auth.json 里那条 admin 记录连密码带会话一起改名成 default,所以旧密码继续能登、开着的浏览器不掉线。左下角的账号入口显示用户名 + 角色(原先显示的是当前 profile 名——profile 是模型配置,和「我是谁」无关)。账号名会先规范化再当目录名(清理后 2–32 位、字母开头、仅字母数字下划线)。
  • 每个账号有自己独立的会话、归档与定时任务:AgentService 的每条入口(chat / chat_stream / run_goal、会话列删改归档、trace 读取)多一个 owner 参数,由服务端从会话 cookie 解析,agent 实例的缓存键也带上它。相应地 ChatRequest / GoalRequest / MemoryRequest / CronJobCreateRequest 删掉了 user_id 字段——请求体里的身份是客户端说了算的,等于任何登录用户都能把别人的 user_id 填进来。网页侧边栏只展示服务端返回的会话(不再把同一个浏览器里上一个账号的 localStorage 合并进来,那会让 kk 登录后看见 default 的对话)。定时任务按账号切开:/api/scheduler/jobs 只列出当前账号的任务,创建时把 cookie 里的账号名写进 CronJob.user_id,别人的任务 id 一律 404;调度器仍会执行所有到期任务,跑的时候用任务上的 user_id 作为数据分区。归档是会话上的标记,跟着会话走。「用户管理」是唯一的管理员专属功能(/api/auth/users* 非管理员一律 403):模型 profile、工作目录、技能、MCP 仍是这台机器的配置,任何账号都能改。删账号只吊销登录,users/<id>/ 的数据留在盘上。端到端验证 tmp/multi_account_smoke.py(真 gateway、真流式对话,两个账号互不可见、非管理员 403、管理员改密、删号后数据仍在)。
  • 用户管理从设置弹窗里拆成右侧独立页 /users,新增 / 改密改成完整表单:原先塞在设置 tab 里的一行输入框既看不清也做不全。现在主侧栏不变、右侧是账号表;新增用户是二级窗口:用户名会先规范化再当目录名(小写、空格/连字符变下划线、其它非法字符丢掉、数字开头加 u_、超长截断;清理后须 2–32 位且字母开头),初始密码(管理员自己填,至少 6 位)。规范化后与已有账号撞名则拒绝。用户名合法时提示将创建默认 Project <id>(不再带 -default_project 后缀,目录就是账号名)。只能新增用户角色——第二名管理员会把「谁能改谁的密码」搅成一团,seed 的那一个就是唯一管理员。去掉重置密码:改自己(内置管理员)要填当前管理员密码(提示写明初始密码打印在首次启动的终端里,形如 abcd-1234),改普通用户只填新密码 + 确认。改密只在用户管理页(以及设置 › 访问);左下角账号菜单改为 退出登录,方便切账号。
  • 网页去掉「让模型输出推理过程」开关,thinking 默认一直开:这不是给用户选的产品能力——支持 thinking 的模型本来就该把推理过程流出来,关掉只是让界面少一块;不支持的模型会忽略。删除 /api/config/thinking 与设置里的勾选,Gateway 构建主模型时固定传 thinking="enabled"。
  • 轨迹是会话的附属,不再是独立 tab:主侧栏去掉「轨迹」按钮,中间那列会话列表也去掉。唯一入口是对话标题右边的「查看轨迹」;轨迹页左上角「返回对话」回到该会话。直接打开 /traces(不带 sessionId)会回到聊天。
  • 对话页右侧「打开工作区」:顶栏去掉「目录: …」那一行,改成打开当前会话工作目录的文件面板(Web / Desktop 同一套 SPA)。面板标题是「文件」,工具条是「根目录」加详情 / 刷新 / 上传;点进文件可预览(文本 / Markdown 渲染与源码 / 图片 / PDF / HTML 沙箱),超过 256 KiB 截断并提示下载(源码高亮到 64 KiB 为止,更大的 Markdown 默认开源码视图以免卡主线程),预览页可返回、可下载。对话里提到的路径(行内代码、read_file/write_file/apply_patch 参数、上传附件)会聚成文件卡片,点「预览」打开同一块面板。路径必须落在工作目录内(.. 与 symlink 逃逸拒绝)。API:GET /api/workspace/files、/content、POST /stat、/upload。
  • 对话输入框右下角的上下文占用改成 CLI /usage 同款会话级拆分:鼠标悬停看到 Context Window(已用 / 窗口)、消息数、API 调用、费用、本会话输入/缓存命中/输出,以及 system prompt / 规则与工作区 / 技能 / 工具说明 / 工具定义 / 对话各自占用的 token。各行是并列拆分(加起来等于下一轮请求),不是父子:System prompt 是整段 system message 扣掉已归因块后的剩余,工具定义是 API schema、不在那段字符串里。分段只报 token 数,不再配百分比、进度条和缩进;/usage 同样去掉 % full, estimated 和 ▓ 条。数字来自同一条 measure_context 路径。API:GET /api/sessions/{id}/usage;流式 done 事件也带上这份快照,圆环百分比跟占用走。
  • 侧栏每个 Project 行右侧「+」在该项目下新建对话;不再显示 project 路径(工作区已经有路径)。工作区 Details 点外面或 Esc 关掉。Markdown 预览支持 HTML 标签(如 <p align="center">)和 LaTeX;源码 / 纯文本预览右上角可复制可见文本。每轮结束后,鼠标悬停答案显示日期、↑输入 / ↓输出 tokens、input cache tokens 与 cache hit(与 CLI footer 同一口径)、tok/s、费用、耗时和复制;footer 每一项都有 tooltip(费用是「成本(USD)」)。用户消息悬停只显示简写日期时间和复制。新建对话可在输入栏选择/更换 work dir(浏览上级目录、改用临时工作区)。输入 / 可触发 /goal、/compact 和已安装 skill。可粘贴/预览图片:底模能看图则直接附上,否则由 settings.media_model 配置的模型描述后转交(未配置时提示如何在 config.yaml 里写 media_model)。流式输出贴底滚动,上滑后页面中间出现下拉箭头可跳回最新。输入框随内容长高。
  • Web 读图提示不再写死 Gemini:底模不能看图时,tip 显示 settings.media_model 里实际配置的 model_name;未配置则说明在 config.yaml 里怎么写该块(需要 model_name,以及 model_provider 或 base_url)。GET /api/status 增加 media_model。IM 渠道未配置时的回复同样不再写「指向 Gemini」。
  • Web 输入栏、footer、/goal 与新建会话目录:去掉输入框上方的 Enter to send · … tip(换行/粘贴写进 placeholder)。每轮 footer 的 cache 改成数据库图标,夹在输入 tokens 和输出 tokens 中间。/goal 运行时输入框上方显示 CLI 同款状态(Goal [active]: … + tokens/turns),期间再发的消息进入队列而不是 409「already has an active run」。新建会话选目录时可直接输入绝对路径;路径不存在或无法访问时提示「目录不存在或无法访问,已回退」,仍停留在旧目录上可继续改。
  • 设置 › 默认工作目录:历史条目可单条删除;已不存在的路径(包括 pytest 留下的临时目录)打开设置时自动丢掉。输入绝对路径点应用 / 回车,非法路径同样提示「目录不存在或无法访问,已回退」。DELETE /api/config/dir_history?path=。
  • Web 偏好落盘到 gateway,localStorage 只做首屏缓存:主题、语言、审批档、上次打开的会话写入 $AGENTICA_HOME/gateway/prefs/<账号>.json(GET/PUT /api/prefs)。清浏览器缓存或换浏览器后仍能从本机读回;第一帧仍读 localStorage,登录后再对账。会话正文仍是 SessionLog,没有另起一份 SQLite。
  • 输入框 Skills / Permission 对齐可发现性:Skills 按钮(打开的书 + 下箭头)弹出带搜索的列表,展示技能名和描述,悬停 tip 是完整 desc。Permission 三档跟 agentica.agent.permissions 一致,不是 Codex 截图里的「每次询问」:ask 是征求批准(读含工作区外、只读 shell 自动;写文件 / 改状态的 shell / 联网停车)、auto 是代为批准、allow-all 是完全访问。图标按 Codex 习惯:眼睛 / 闪电 / 三角感叹号;按钮带下箭头,括号里跟英文 id。/ 斜杠菜单过长时列表可滚、键盘选中项滚进视口,技能行也用打开的书。
  • 源码预览按语言语法高亮:工作区打开 .md / .py / .yaml / .toml / .java 等文本文件(Markdown、HTML 切到「源码」也一样),以及对话里的围栏代码块,都画成带语言标签和复制按钮的代码卡片,用 highlight.js 着色(标题蓝、引用绿、跟常见 GitHub 主题同一套 token)。Markdown 渲染视图不变。源码卡片自己管横竖滚动(不再把纵向甩给外层、横向甩给 <pre>):两条都是 8px 细条、始终可见、可拖滑块,点轨道跳到对应位置。
  • 工作区预览上限从 12000 字符改成 256 KiB:原先一个普通源码文件就会被截成「请下载」。GET /api/workspace/content?preview=1 现在只读文件头 TEXT_PREVIEW_BYTES(256 KiB),不再整文件进内存再切;超过 64 KiB 关掉语法高亮,更大的 Markdown 默认开源码视图,避免卡主线程。

  • 查看轨迹后侧栏丢掉刚建的对话:进 /traces 会拆掉整棵 AppShell 再 GET /api/sessions 覆盖列表;而这个接口只列默认工作目录下的 session,刚在别的 project 里问完的对话(轨迹能打开,因为它按 session id 找)就不在列表里,覆盖时连 localStorage 一起冲掉。现在 chat/traces/users 共用一个 layout,切轨迹不再重拉列表;list_sessions 列出该账号下每一个 project,并带上 work_dir。

  • gateway 重启后「查看轨迹」提示盘上没有 jsonl:_session_work_dirs 是进程内存,重启后空了就去 settings.base_dir 找;对话其实写在另一个 project 下。session_log_for / 删改归档现在用 SessionLog.find_sessions 在该账号所有 project 里按 session id 定位。轨迹页 cache 改成与对话 footer 同一套数据库图标 + tip。
  • 轨迹时间线此前是一根实心条,现在是真的分段:thinking / text / tool_call 三种事件是在一次请求结束后才一并落盘的,时间戳几乎相同,于是分析出来的模型泳道要么只有一段、要么后面几段宽度为零——时间线看着像没坏,但它讲的不是这一轮实际发生的事。现在流式循环在推理段和正文段真正结束的那一刻记下 time.time(),SessionLog.append_event() 接受显式 timestamp,落盘前按发生顺序排序,所以「思考 2.3s、回复 36ms」这种分布才画得出来。
  • 工具泳道按工具名合并,图例五项:原先每个工具调用各占一条泳道,一轮里调 20 次 read_file 就是 20 条几乎一样的线;现在同名工具收进一条泳道(并发调用才在道内错开分层,道尾标调用次数),并且图例五个阶段常驻(思考 / 模型回复 / 工具参数生成 / 审批等待 / 工具执行)——只画本轮出现过的颜色,会让两轮之间的同一个颜色对应不同阶段。不再画「其它」:那是墙钟减去各段之后的残差,时间线上本来就没有对应的条。

  • Web 工作组在回答结束后不再显示「运行中」:思考切片的 ms 没冻住时,组头和「正在思考」按墙钟一直加,隔天变成 45h。现在所有未收口的思考都冻住(中间段用下一段工具/t0,不要用现在的墙钟);回合结束走 settleWork;已经不在流式的卡片即使旧数据缺 ms 也不再转圈。

  • 沙箱 blocked_commands 不再把 rm -rf / 当成所有绝对路径删除的前缀:以前只卡左侧边界,rm -rf /Users/.../__pycache__ 和 rm -rf /tmp/x 都被当成删根目录拦掉(测试还把这个漏洞写成预期)。现在按操作数匹配:/ 是完整路径,后面不能再接 Users;rm -rf /、rm -rf /*、echo x; rm -rf / 仍拦。对齐 Codex / OpenCode / Penguin:工作区内删除走审批或 OS 围栏,不用字符串前缀当禁令。
  • 工具审批分类器与「允许类似」:is_destructive 第三方工具(如 cronjob)在 ask 下停车,不再误落到兜底 allow;auto 下放行(只拦工作区外文件写)。命令「允许类似」按命令类(rm -f,不含路径/文件名),rm -f a 批过之后 rm -f b 不再问、git add 不会放行 git push;类短于 2 个 token 时不提供「允许类似」(bash deploy.sh 不能永久放行任意 bash -c);echo hi && rm 这类复合命令不能用首段越权,只提供允许一次。已写入 project.json 的单 token 前缀(["bash"])读取时忽略。ask 下工作区 write_file / apply_patch 也会弹卡。todo / memory / skills / ask_user_question 不弹卡。Web 输入框 Enter 不再误批。tool_result SSE 带 tool_call_id。真正停过车才写 approval_decision。
  • 输入栏弹出层点外面或 Esc 就关掉:模型 profile、权限档、Skills 打开后只能再点一次按钮才关。现在点对话区、输入框或其它按钮会立刻收起,Esc 也先关菜单(有菜单开着时不拿去停止生成)。
  • Web 生成中空 Enter 会停止,Stop 按钮一直在:placeholder 写着「空输入为停止」,但空 Enter 直接 return;输入框有草稿时按钮还会变成发送。busy 期间按钮恒为 Stop,空 Enter / Esc 都停止。
  • 创建 run 途中点 Stop 不再留下孤儿任务:POST /api/chat/runs 返回后若用户已停止,立刻 cancelRunApi,避免 UI 已 aborted、后端仍占 session lock。
  • SSE 空闲 15s 发 keepalive;干净 EOF 且未见 done/error/aborted 则按断线重连:前置代理闲置掐流不会再被当成回合完成。
  • 已结束的 live_turn 10 分钟后从注册表丢掉:完成/取消后仍可重连回放,超时释放事件缓冲,删会话立刻清掉。
  • live_turn 事件缓冲和订阅队列有上限:运行中不再按 token 数无限 append;连续 content/thinking delta 在缓冲里合并;慢订阅者队列满则断开,让客户端按 after=seq 重连,避免长 /goal + 多标签页把网关打到 OOM。
  • Steer 打断思考时上一张思考卡片停止计时:插话把思考切到下一张卡,但上一张 ms 没冻住,墙钟还在涨。现在插入 steer 或开新思考切片都会 finishThink。
  • Web 侧栏按会话创建时间排序:jsonl 首行 first_timestamp 是第一次请求。GET /api/sessions 和侧栏都按它倒序(新在上),发消息不再把老会话顶上去;「3d」小字也是创建时间,不是最后活动。Project 分组按该目录第一次出现会话的时间排,给旧项目加 New Chat 不会把它顶到最上面。CLI /resume 仍按 mtime 倒序。
  • Web 对话不再狂打 /api/workspace/stat:消息底部的文件卡片原先跟着流式正文每一帧重抽路径,数组换了引用就 POST 一次,长回答会打满日志。现在流式期间不查;路径集合没变也不查;同一帧里多条消息合并成一次请求。
  • Web 工具调用一开始就上屏:思考是流式的,但 execute 这类要跑一会儿的工具要等完成才出现——flushStream() 以前只在有挂起的 rAF 时才 bump(),思考停了之后那条 tool_call SSE 改了数据却不重绘。现在结构事件立刻绘制。
  • Web 回答过程闪屏:每 token 整段 Markdown 重挂载(components={{}} 每次新对象)、.bub pre{transition:all .2s} 让代码块从 0 高度动画出来。改成 120ms 节流、冻结的 ChatMarkdown(流式跳过高亮/KaTeX,结束后高亮一次)、光标改成独立 caret,去掉 pre 的全属性 transition。
  • Web 工作组耗时按思考 + 工具切片求和:组头原先用「第一刀到现在」的墙钟,思考 step 又不冻 ms,最后一轮在回答已经结束后仍因 isLast 每秒刷新,总时长跟着墙上的钟涨。现在每段思考结束就记下切片,组头 = 各思考耗时 + 各工具耗时;思考行也显示这段时长。回答生成时间不再算进运行过程。
  • Web tool result 不再 500 字截断:网关原先一律截成 500 字,前端再 slice(0, 8000) 且完成后默认折叠,所以 execute 的 stdout 看起来像没了。只有 read_file / glob / grep 成功时不展开结果(本地读文件,调用行够了);write_file / apply_patch / write_todos / web_search / fetch_url / save_memory / search_memory / execute / task 等展开时同时展示完整入参和结果(write_file / apply_patch 不再只送行数摘要),默认展开,只有超过 10 万字才截。task 不再收成只有 tool_count 的 _task_meta JSON,展开子 agent 的逐步调用和完整回答。出错的结果一律展示。
  • 没有 rg 时 grep 的 context 不再静默失效:纯 Python fallback 原先丢掉 context_lines / before_context / after_context,模型传了 -C 3 却只拿到匹配行。现在按 rg 同样的优先级切片(context_lines > 0 忽略 before/after,重叠窗口合并,组间 --)。
  • Web /compact 发出后立刻显示用户那一行,压缩完成前不能再发:以前要等压缩 API 回来才把 /compact 写进对话,期间发送按钮也不算 busy,于是用户以为没发出去再敲一次,第二条撞上 session 锁变成「already has an active run」。现在用户气泡马上出现;压缩期间 Enter / 发送键挡住(不是发出去再 409)。普通对话和 /skill 本来发出去就上屏,这条没改。
  • 对话 footer 和轨迹同一轮的 tok/s、耗时对不上:footer 用整段 chat_stream 墙钟(含建 agent)当分母,10 token / 3.6s 显示成 2.8 tok/s、耗时再四舍五入成 4s;轨迹用 jsonl 里 request 的 LLM 时间,同一轮是 5.3 tok/s / 1.90s。现在 done 带上 last_completed_round 的 duration_ms / llm_ms / tps(跟 View trace 同一套分析),footer 用 LLM 时间算 tok/s、用 round 墙钟显示耗时。两边共用 fmtDurationMs(不到 10s 两位小数)和 fmtTps(一位小数)。
  • 轨迹页顶栏的 git 分支和工作目录是会话自己的,不是 gateway 进程的:jsonl 原先每条都盖 os.getcwd() 和进程里的 git branch,网页会话于是一律显示 git:main 和 …/Codes/agentica。现在按会话 work_dir 打戳、在那个目录探分支;没有 git 就不显示 git:。已写出的旧记录打开轨迹时也用会话目录覆盖。

[1.4.13] - 2026-08-20

features

  • 新增 Desktop App 安装包(.github/workflows/desktop.yml,推 v* tag 时构建并挂到该 tag 的 Release):macOS dmg(Apple 芯片 / Intel 各一个)、Windows x64 NSIS 安装程序、Linux x86_64 AppImage 与 amd64 deb,命名统一为 agentica-desktop-<platform>-<arch>.<ext>,README 的下载链接走 releases/latest/download/… 因此永远指向最新版。三个 OS 各跑一个 runner 不是为了并行快——NSIS 装包要 Windows、deb/AppImage 要 Linux,一台 macOS 开发机最多只能出那两个 dmg,所以这件事只能在 CI 做。构建未签名(Apple / EV 证书是账号问题,不是构建问题),因此 README 给了三条一次性解除拦截的步骤:macOS 的 xattr -rd com.apple.quarantine、Windows SmartScreen 的「仍要运行」、Linux AppImage 的 chmod +x。安装包里没有 Python:桌面版是壳,服务端仍是 gateway,所以下载区把 pip install -U "agentica[gateway]" 写成前置要求而不是脚注。
  • 打包图标收敛成一个 1024² 母版(desktop/build/icon.png,由 desktop/make_icon.py 从 docs/assets/logo.png 裁出那只挥手猫重建)。electron-builder 从一个正方形母版派生所有平台的图标且拒收小于 512 的,所以既有的 256² cat.png 和 48² favicon.ico 都不够用;顺带把运行期的两文件分支(Windows 用 ICO、其它用 PNG)也合成这一个——nativeImage 只在 Windows 上解 ICO,拿错平台得到的是空图,而空图和「没配图标」看起来完全一样。打包后的应用不再从磁盘读图标:安装包已经把它放到平台真正会看的位置(.app bundle / exe 资源 / .desktop),而从 app.asar 里读图不是 nativeImage 承诺的能力。端到端验证 tmp/desktop_package_smoke.py(跑真实构建产物:bundle 元数据、asar 载荷、图标、启动、收尸,17 项)。
  • Web / 桌面版界面改为默认英文,设置 › 常规 › 语言可切简体中文:此前界面文案是中文硬编码在 JSX 里的,一个开源项目的默认入口不该假定读者的语言,而想改也无处可改。新增 web/src/i18n.ts:en 是唯一的字符串源,zh 用 const zh: Strings 声明成同一个类型,所以少一个键就是 tsc --noEmit 失败,而不是中文界面里冒出一个英文词(npm run build 已经先跑类型检查)。带数字或人名的条目一律写成函数(round: (n) => …),因为两种语言的语序不同——在调用点拼模板串是没法翻译的。选择存 localStorage.ag_lang(与主题同一套做法)并写到 <html lang>,切换即时生效、不用刷新;语言选项各用自己的语言标注(English / 简体中文),落错语言的人才读得懂怎么切回去。故意不翻的是标识符:日志事件类型(tool_call、request_begin)、配置字段名(base_url、max_tokens)、审批模式与 profile 名——这些用户也要照着敲和 grep。桌面壳自己那几句(启动失败弹窗、View 菜单)也改成英文并且不跟随这个设置:它们要么是 Electron 按系统语言自己本地化的 role,要么是 gateway 没起来时弹的框——那时根本没有渲染进程可以读这个偏好。端到端验证在 tmp/web_i18n_smoke.py(真实窗口里点真的那颗设置按钮,23 项)。
  • 首次启动自动建 admin 账号并生成密码,网页登录不再需要 ?token=:URL 里带令牌那套对个人本机是最差的一种进门方式——令牌进程级、一重启就换,粘错一个字符只会得到 401,而桌面版根本不需要它(壳自己用本机令牌换会话),于是同一个产品的两个入口体验完全不同。现在首启动幂等地 seed 一个 admin(AccountStore.seed_admin()),密码随机生成、以方框形式打进启动日志,同时写一份 0600 的 $AGENTICA_HOME/gateway/initial-password 明文——重启后日志滚走了还得有地方能查。密码最短 6 位(原先 8 位;这是本机个人服务,不是公网多租户),GET /api/auth/status 增加 account_id / password_is_initial / min_password_length 三个字段,前端的下限跟着服务端走而不是自己写死一份。改密(终端或网页)会把 password_is_initial 落成 false 并删掉那份明文,之后启动日志只提示怎么登录、不再复述密码。相应地 --host 非 loopback 的守卫从「没设密码就拒绝」收紧成「密码还是生成的那个就拒绝」——一个印在日志里的密码暴露到网络上和没有密码没什么区别。
  • /traces 与 /chat 合到同一个主页,「轨迹观测」改名「轨迹」:轨迹页原先是独占整屏、靠一个「返回」链接回聊天的独立页面,切过去等于离开产品。新抽出 web/src/components/AppShell.tsx(左侧导航 + 账号浮层 + 全局弹窗)由两个页面共用,会话选择器成为中间栏——和聊天的会话树同一个位置,所以「挑一个会话看它怎么跑的」不再需要先记住会话名。
  • 轨迹的耗时可视化从「按比例堆叠的阶段条」换成时序时间线:堆叠条只回答「思考占了几成」,回答不了「四个工具是并发还是排队」——而这正是看轨迹的主要目的。现在每轮画一条模型泳道加每个工具调用各一条泳道(按调用时刻排序、带序号),横轴是这一轮的真实时间,条的左边缘就是它开始的时刻,所以并发的批次一眼看得出是叠着的、串行的是错开的;轴上 5 个刻度标相对耗时,下方图例四色(思考 / 模型回复 / 工具参数生成 / 工具执行)。图例里不再重复各阶段的求和时长——它和横轴讲的是两件事,并排放只会让人把总和当成跨度读。此前唯一的进门方式是启动日志里那条 ?token=…,令牌是进程级的、一重启就变,也没法只吊销一个浏览器。现在 cookie 里装的是会话而不是令牌:会话存 $AGENTICA_HOME/gateway/auth.json(0600,只存 sha256 摘要),7 天有效、最后一天内的请求自动续期,重启 gateway 不掉线。密码用 hashlib.scrypt 存(scrypt$n$r$p$salt$hash,参数随 hash 走,以后调高成本不作废旧密码),连续失败 5 次后按 1s/2s/4s… 上限 60s 退避并返回 429 + Retry-After。设置方式两条:终端 agentica-gateway --set-password,或网页 设置 › 常规 › 访问(改密码会让其他所有浏览器退出登录——会用到改密码的场景就是「cookie 可能被人拿到了」)。首次启动自动建 admin 账号并生成一个密码(下一条),所以启动日志不再打印 ?token=…;未登录访问 /chat / /traces 会 302 到 /login,API 返 401 并由前端跳转。机器令牌保留但改为只用来兑换会话(脚本仍可直接 Authorization: Bearer),令牌持有者改密码不需要旧密码——能读 0600 文件的人已经拥有这台机器。新增免凭据端点 GET /api/auth/status(门自己不能锁在门后),以及 /api/auth/{login,logout,password}。
  • --host 不是 loopback 时,没设密码直接拒绝启动(退出码 2,提示怎么设)。原先 --host 0.0.0.0 只靠令牌门挡着,而令牌是打印在终端里、不重启改不了的凭据,不适合暴露到网络。GATEWAY_AUTH=false 不受这条约束:显式关门是明确意图,只给一条醒目告警——按项目既有的分工,显式参数可以报错,环境值只降级告警。
  • 带 cookie 的写请求要求 application/json 或 X-Agentica-Client 头(CSRF 第二道防线,主防线仍是 SameSite=Lax):HTML 表单只能发三种 Content-Type、也伪造不出自定义头,所以这一条挡住的正是「你打开的某个网页拿你的 cookie 调本机 API」。/api/upload 必须是 multipart,因此前端给它带上了这个头。用 header 递交令牌的脚本不受影响(curl -d 默认就是表单类型,而表单发不出 Authorization)。
  • Gateway 加本机 token 鉴权,默认开启:/api/* 和 /ws 现在要带令牌。/api 能切 profile、读任意路径、跑 execute,此前只要连得上端口就全都开着。取令牌的方式是 Jupyter 那套:启动日志打印 http://127.0.0.1:8881/chat?token=…,第一次打开时服务端把 query 换成会话 cookie(agentica_session,HttpOnly + SameSite=Lax),之后直接开 /chat 书签即可,令牌也不再留在地址栏。非浏览器客户端用 Authorization: Bearer <token> 或 X-Agentica-Token。令牌每次启动随机,AGENTICA_GATEWAY_TOKEN 可固定;GATEWAY_AUTH=false 整道门关掉。明确豁免(各有不得不豁免的理由):/webhook/*(飞书等第三方回调自带签名,无法携带我们的令牌,拦了等于让 IM 下线)、/health 与 /api/health(就绪探针在知道令牌之前就要跑)、/、/assets/*(编译产物,无用户数据)以及 CORS 预检的 OPTIONS(按规范不带凭据)。/ws 的 params.auth.token 一直写在协议里但从未校验,现在生效,另外也认 handshake 的 cookie / ?token=。CORS 同时收紧到 loopback:Starlette 对 allow_origins=["*"] + allow_credentials=True 的实现是把请求的 Origin 原样回显,令牌一进 cookie,任何你正好打开的网页就都能读这个 API 并调工具——这不是顺手加固,是这次改动必须一起做的部分。Vite 开发端口仍在放行的正则里。
  • Gateway --port 0 选空闲端口并把实际端口写出来,新增 --parent-pid:agentica-gateway 从只读环境变量改为有真正的命令行参数(--host / --port / --parent-pid)。--port 0 由持有 socket 的一方解析——先 bind 再回读端口号交给 uvicorn,而不是「问系统要个空闲端口再把号码传下去」(那样中间的空窗期会被别的进程抢走)。运行进程把 pid / host / port / token / url 写到 $AGENTICA_CACHE_DIR/gateway/runtime.json(0600,退出时删除,且只删自己那条),这样桌面壳或另一个终端才回答得出「这台机器上是否已经有 gateway、在哪个端口、令牌是什么」。--parent-pid <pid> 让 gateway 在指定进程消失后自杀(轮询,因为父进程被 SIGKILL 时它自己的清理代码根本不会运行),避免壳被强杀后留下一个占着端口和会话锁的孤儿。端口被占时报错会指出是哪个 pid 在服务哪个地址,而不是抛一段 traceback。
  • 新增 desktop/:Electron 薄壳(阶段二第一版,与 docs/learn_cc/web_v2.md 第 5 节一致)。壳只做机制:单实例锁、先 attach 再 spawn(同一 ~/.agentica 上已有 gateway 就连过去,不起第二个,也绝不在退出时杀掉不是自己起的那个)、拉起 agentica-gateway --port <上次那个> --parent-pid <自己>、等 runtime 记录与 /api/health 就绪、开窗口。窗口是普通浏览器:无 preload、无 IPC、nodeIntegration:false + sandbox:true,只有本实例自己的 origin 留在窗口里,其余(包括别的本机端口)交给系统浏览器。令牌先兑换成会话再通过 Electron 的 cookie API 注入,不拼进 URL,所以渲染进程读不到它。两个 GUI 特有的坑一并处理:从 Dock 启动的应用不继承 shell PATH(conda/venv 里的 agentica-gateway 因此找不到),所以走登录 shell 解析,AGENTICA_GATEWAY_BIN 可直接指定;GUI 启动没有有意义的 cwd(从 Finder 启动是 /,agent 会把文件系统根目录当项目目录),所以子进程的 cwd 固定为用户 home。cd desktop && npm install && npm start;打包成安装包不在本次范围。
  • 桌面壳:端口粘滞、崩溃退避重启、优雅收尸、原生菜单。四条都是「壳是全产品里最难更新的一层」的直接推论——这里的 bug 要等下一个安装包,所以能想到的都在第一版做掉:端口粘滞,SPA 的会话树/当前会话/主题都在 localStorage,而它按 origin 隔离、origin 就是 127.0.0.1:<port>,纯 --port 0 会让每次启动的侧边栏都是空的(会话还在盘上,只是这个 origin 没见过);壳把真正绑定成功的端口记在自己的 userData 里,下次优先要它,被占了才退回 0,不引入任何固定端口(写死 8881 会撞用户自己起的 gateway,症状是白窗)。崩溃重启退避 1s/2s/4s,三次放弃并弹窗,连续健康一分钟重置额度。退出先请求 POST /api/desktop/shutdown(仅限令牌持有者)再 SIGTERM 再 SIGKILL,且 before-quit 会等到子进程真的没了才放行——Windows 上 kill() 是硬 TerminateProcess,IM 渠道不会断开、peers 记录不会清理。菜单给回 reload / force-reload / DevTools:没有菜单的窗口根本没法刷新,而做成页面能调的 bridge 就等于加了一个只有桌面版才有的能力。渲染进程崩溃会自动重载。新增 AGENTICA_DESKTOP_SMOKE=1:壳自己打印一行 DESKTOP-SMOKE-RESULT {json}(窗口 URL / 标题 / 是 spawn 还是 attach / 子进程 pid / 探到的 SPA 元素)然后走正常退出路径退出,所以自动化验的收尸就是用户实际经历的那条。
  • README 前置评测图,强调 CLI / Web / Desktop:主 README 开篇放 Polyglot 与 DABench 两张对照图;去掉 /goal 长任务介绍;自进化流程图改到 Skills 文档。DABench 对照图补上准确率,配色与 Polyglot 图一致。
  • 评测页换成 DABench 全量 257 题对照:公开表用 Agentica 20260820-153724(220/257,均 12.6s,499 次工具,输入 3.87M)对 Codex 20260820-134628(215/257,均 25.7s)。results/ 入库该跑次的 summary.json / predictions.jsonl。同一 Responses + deepseek-v4-flash-official + reasoning.effort=high。
  • DABench 沿用 Polyglot 的评测 agent 面,并收紧 data-analysis prompt:核对过公开 DAEval validation(257 题):每题都有且只有一个 file_name(全是 csv),harness 把它拷进空 workdir,题面从不要求列目录或检索仓库。因此共用 build_coding_agent(无 todo,schema 去掉 ls / glob / grep)是按题目结构去的,不是照搬 Polyglot。prompt 点名 CSV、禁止多余清洗、算出 @tag 立刻停。Agentica / Codex 全量都走 Responses + 同一模型 + reasoning.effort=high(Codex 写进隔离 CODEX_HOME 的 wire_api / model_reasoning_effort;summary 两边都记下这两项,不再把 Codex 标成 wire_api: null)。
  • 评测增加 InfiAgent-DABench(data analysis):--bench dabench。公开 DAEval validation,agent 读 CSV 用 pandas/sklearn,@name[value] 封闭题判分(与官方 eval_closed_form.py 同口径)。--agent agentica|codex|claude 与 Polyglot 同一套 CLI 包装。--dry-run --bench dabench 不调 LLM、不下载。
  • 评测 Polyglot 默认 Responses,并收紧 coding agent 工具面:--agent agentica 默认 --wire-api responses。评测 agent 关掉 todo,并从 schema 去掉 ls / glob / grep / undo_edit / apply_patch / request_path_access。题目已经点名要改的文件和测试文件;prompt 要求直接读、pytest 全绿立刻停,不再 list、不再复读、不加额外测试。
  • 评测页换成 Responses 34 题对照:公开表与柱状图用 Agentica 20260819-195326(34/34,均 43.7s,139 次工具,输入 1.24M)对 Codex 20260817-215956。results/ 入库该跑次的 summary.json / predictions.jsonl。
  • Gateway Web 换成 Vite + React SPA,并加上 Session Trace:gateway/static 的 petite-vue 页面删除;源码在 web/,发版 npm run build 写入 agentica/gateway/ui/,pip install agentica[gateway] 运行时不需要 Node。/chat 书签仍进产品。Runner 往同一份 Session JSONL 追加 type=event 生命周期(request_begin/end、thinking/text/tool_call、token_usage),load() / resume 不把它们喂给模型。Gateway GET /api/sessions/{id}/trace/analysis 读时分析;SPA /traces 只画。旧 session 没有新事件时只给事件列表,不强行画时间轴。Desktop / Electron 不在本阶段。
  • Web SPA 补齐并超过旧 petite-vue 页面的功能面:旧页面的三块功能在第一版 SPA 里只剩壳子,等于换实现就把它们撤了,所以逐个补回并加长:Profiles 在设置弹窗里做全 CRUD(新建/编辑/切换/删除,provider·model·base_url·api_key·auxiliary model·tuning·ENV;api_key 回读时按 sk-d…xx1 掩码,留空即保持不改),Scheduled 全 CRUD(新建/编辑/删除/暂停/恢复/立即运行/运行历史),Plugins 分三页(Skills 全 CRUD 直接编辑 SKILL.md 正文、MCP 增删、Tools 检索,一个搜索框同时过滤三类)。共享层从组件里抽出来:web/src/data.ts(各面板刷新自己的列表)、web/src/sessions.ts(会话列表/归档/重放)、统一 askConfirm 确认弹窗(删除不再走浏览器原生 confirm)。npm run build 现在先 tsc --noEmit 再打包——类型错误以前只会在打出来的包里静默生效。
  • /traces 从「事件列表」重写成按会话分层的执行轨迹:左侧会话栏(同一工作目录下的 CLI 会话一并出现,Web 与 CLI 共用一份 session 日志),右侧全局统计(轮次、输入/输出 token 与缓存命中、成本、工具调用成功/失败、等待审批耗时、总耗时与模型耗时、输出 TPS),下面按轮(用户一次提问到终答)分卡片:分环节耗时条(思考 / 模型回复 / 工具参数生成 / 审批等待 / 工具执行 / 其它)、模型与每个工具各占一条的泳道图、以及本轮完整事件流。事件逐条可展开:system prompt 全文、thinking 推理正文、tool_call 的参数(格式化 JSON)、工具输出、token_usage 明细,另有「全部展开」和逐条复制。为此 Runner 的 type=event 补齐 session_meta(模型/provider/上下文窗口/工具数)、tool_list_ready、system_prompt(每会话去重一次),token_usage 的 input 改成与 cache_read 不重叠的口径,成本按模型 id 估算。轮次划分靠日志里的因果顺序,所以用户消息改为在 request_begin 之前落盘(原先在之后,一轮的事件会被算到下一个问题名下)。
  • 评测 --wire-api responses 与 Claude /v1/messages:--agent agentica --wire-api responses 走 OpenAIResponses。--agent claude 配 --base-url 时写隔离 CLAUDE_CONFIG_DIR + ANTHROPIC_BASE_URL(去掉 OpenAI 兼容地址尾部的 /v1,Claude Code 再拼 /v1/messages),并设 ANTHROPIC_AUTH_TOKEN(--bare 仍要 API key,Bearer 给走 Anthropic 协议的网关),不读 ~/.claude。
  • --agent codex 认 Responses 关思考写法:--extra-body '{"reasoning": {"effort": "none"}}' 写入隔离 CODEX_HOME 的 model_reasoning_effort。以前只读 reasoning_effort,缺这个键就默认 high,关思考传不进去。也认 thinking_enabled: false。
  • README 增加 Polyglot 评测对照,对比表去掉 Gemini CLI:数字与 docs/guides/benchmark.md 同一跑次(Agentica / Codex 各 34/34)。原始 summary.json / predictions.jsonl 在 evaluation/code_benchmark/results/。
  • 系统 skill 只在 CLI/gateway 物化到 $AGENTICA_HOME/skills/.system/:包内 agentica/skills/bundled/(agentica、multi-agent)仍是源;产品入口 load_system_skills() 按内容哈希同步到隐藏的 .system(升级覆盖)。SDK 的 load_skills() / Agent() / DeepAgent() / SkillTool(auto_load=True) 默认不扫 bundled、也不扫 .system,同机跑过 CLI 留下的文件不会漏进库调用。要覆盖内置:在 skills/<name>/ 写同名 user skill。
  • Layer 1 / Layer 2 压缩可关,默认仍开:ToolConfig.enable_evict(淘汰旧工具结果)和 ToolConfig.enable_auto_compact(窗口满时自动摘要,含原生 compact 与 prompt_too_long 后的 reactive)。SDK 传 ToolConfig(...);CLI --no-evict / --no-auto-compact(也认 --evict / --auto-compact),以及 config.yaml 的 settings.enable_evict / settings.enable_auto_compact(gateway 同样读)。关掉自动摘要后 /compact 仍可用,跨 provider fallback 仍会压 portable transcript。两层都关则超窗时把 provider 错误原样抛出。
  • 无 Docker 的 coding-agent 评测入口 evaluation/code_benchmark/:本机跑 Aider Polyglot(Python 子集,agent 改文件 + pytest 判分)、LiveCodeBench(单轮生成基线)、BigCodeBench、EvalPlus(HumanEval+ 管道 smoke)。官方 Aider runner 绑 Docker,这里只用 polyglot-benchmark 题目和本机 pytest,分数可对表但不能直接贴官方榜。run.py --dry-run 不调 LLM,用 stub/canonical 自检判分;正式跑把 AGENTICA_HOME 指到输出目录,不写 ~/.agentica。
  • coding-agent 评测补齐 TB2.1/Pro 风格指标:summary.json 除 accuracy 外必报 wall-clock/task、tool calls 与 API calls(分列,且 tasks[] 按题罗列)、crash/timeout rate、completion honesty(声称 tests pass 但判分未过);另报 false-edit collateral(git diff 任务无关文件/行)、error recovery、human intervention、cache hit rate,以及 model / input·fresh·cached·output tokens / cost。Polyglot 在题目目录 git init 快照 stub,agent 跑完再 diff。--agent claude|codex 用同一套 pytest 包 Claude Code / Codex CLI 的 headless JSON,墙钟和对错在外面量,API/token 从它们自己的 JSON 解析。--extra-body 把 OpenAI 兼容网关的 thinking_enabled / reasoning_effort 原样传给模型。--agent codex 配 --base-url 时写一份隔离的 CODEX_HOME(wire_api = "responses"),走网关的 Responses 接口,不碰 ~/.codex。

changes

  • Gateway Web 构建产物不再进 git:agentica/gateway/ui/ 是 Vite 每次 npm run build 都会换哈希的 dist(旧 hashed 文件还会在 git 里堆积),源码只留 web/。发版 / CI 在 python -m build 之前跑 cd web && npm ci && npm run build,MANIFEST.in 把该目录打进 sdist/wheel,所以 pip install agentica[gateway] 仍然不需要 Node。顺带修了 package-data 只收 js/html/css、KaTeX 字体和 png/ico 进不了 wheel 的问题。本地开发继续 npm run dev;没 build 时 :8881/chat 返回 503 并提示怎么 build。
  • 站点图标换成透明底的 logo 猫,并压小体积:docs/assets/favicon.ico 原先是整张白底 logo 塞进 ICO(约 226KB),现在是抠出的挥手猫、透明底、16/32/48 三档,约 7KB;同步恢复小体积 favicon.png 给 mkdocs。Web 侧栏、欢迎页和标签图标不再用蓝色圆形 SVG 猫头,改为同一只 logo 猫(web/src/assets/cat.png),去掉圆角裁切和白边。gateway 新增 GET /favicon.ico / /favicon.png 并列入免凭据路径——标签图标是从 origin 根请求的,/login 页在拿到会话之前也要能取到它。
  • 桌面壳用同一只猫做应用图标:窗口、任务栏和(开发运行时的)macOS dock 不再是 Electron 原子。两个文件不是冗余:Windows 要多尺寸 ICO,而 Electron 的 nativeImage 只在 Windows 上能解 ICO,在别处会解成一张空图——症状和「压根没配图标」一模一样,所以非 Windows 走 256² 透明 PNG。macOS 干脆忽略 BrowserWindow#icon(打包后图标来自 app bundle),因此那边只在未打包时显式 app.dock.setIcon。图标直接引用仓库里那两个文件,不在 desktop/ 下另存副本:多一份二进制就是多一只会漂移的猫。
  • Gateway 默认监听地址从 0.0.0.0 改为 127.0.0.1。这是行为变更:原先默认对整个局域网开放,且没有任何鉴权——同一个 WiFi 下的任何设备都能调 execute。要恢复局域网访问显式写 HOST=0.0.0.0 或 --host 0.0.0.0,并且必须先设密码(见上)。
  • SDK 可用 delegate:凭据随 Model 对象走,不依赖 config.yaml。delegate 的注册从 CLI 的 create_agent 移进 DeepAgent(cli/runtime.py 只在无进程 registry / 超深时负责移除),SDK 用户传 background_process_registry= 即获得该工具。CLI 之外没有 config.yaml 可读,所以工具直接接收调用方的 Model 对象:provider_for_model() 按类 MRO 推导 provider(所有 agentica.DeepSeekChat/ZhipuAIChat/… 工厂都返回 OpenAIChat 实例,统一落 openai;Azure/Claude 各自命中),base_url 非机密走 --base_url flag,api_key 经子进程环境变量传递(OPENAI_API_KEY/ANTHROPIC_API_KEY/…,ps 看不到)——子进程以 --model_provider/--model_name/--base_url + env key 完整重建模型。无环境变量可用的 provider(如 Azure)直接拒绝并建议用进程内 task 工具;model 覆盖命中 config.yaml profile 时仍优先 --profile。顺手修了 test_partial_payload_carries_next_action_hint_and_run_id 的 flaky 断言(assert "2" in hint 对 timeout=0.05 场景恒假,改为解析建议超时数值并断言严格更大)。
  • delegate 的 model 覆盖映射到 config.yaml profile,未配置的跨 provider 覆盖直接拒绝:覆盖的模型名命中某个 profile 的主模型时,子进程改用 --profile <name> 启动,base_url/api_key/调优参数整套随行;本会话自己的模型同样先查 profile。原来只传裸 --model_provider anthropic --model_name claude-opus-5,子进程 resolve_model_config 里 use_profile=False,base_url 落到 provider 公共预设端点(如 api.anthropic.com)、key 落到多半不存在的 ANTHROPIC_API_KEY,存储的凭据从未离开本机就 401 invalid x-api-key。命不中任何 profile 且 provider 与本会话不同的覆盖,现在返回列出可选模型的拒绝信息,不再放出必然认证失败的子进程;同 provider 的裸模型名维持 flags 行为(子进程由 active profile 供凭据)。
  • 代码、注释、帮助文案和文档不再出现第三方代理名:CLI --cache_control_session_header / setup 向导举例改为 X-Session-Id,评测隔离 CODEX_HOME 的 provider 标识改为 gateway。
  • Ctrl+O 展开 execute 时带上启动命令,且结果是完整的:前端只给命令/输出各留几行预览,展开页却经常只有输出(短命令根本不会单独入栈),用户对不上「哪条命令产出了这段」。现在同一次 execute 在 Ctrl+O 里是一块:$ 后面是完整启动命令,⎿ 后面是完整 stdout/stderr(含前端已经露出的那几行尾部),长命令先入栈、结果到达后原地升级,不会拆成两块。其它被折行的工具结果同样先写工具名和参数再写正文。
  • ask_user_question 不再用 auxiliary LLM 解析用户回答,原话直接交给模型:_parse_reply / _resolve_parse_model 整块删除,结果 JSON 收敛为 prompt / response / options 三个字段(raw_input 一并删除——response 就是原话,第二份拷贝没有意义)。读这段回答的主模型正在这一轮的上下文里,它比一个只看到「问题 + 选项 + 一行回复」的便宜模型更有条件判断用户想说什么;多这一跳换来的是一次额外延迟、一个 30s 超时兜底、以及一次把「3 , 100题, workers=10 是ok的吧」改写成别的东西的机会。CLI 输入回调里「把 1 映射成该选项原文」那段(interactive/app.py)同时删掉——它是键盘和模型之间最后一层转换,而模型手里的信息更全:问题、编号选项、用户那一行都在同一个 tool result 里,3 / C / 「最后一个」/「便宜那个」它都是照着用户看的同一份列表读的。CLI 结果块随之少一行 (your input: …),答案按用户键入的原样回放(敲 1 现在 transcript 里就是 A: 1)。工具因此不再持有 per-agent 状态,set_parent_agent / clone() 与 Agent._bind_tools_to_agent 里对应的分支一起删掉。
  • 推荐项是 prompt 约定,不是参数:把推荐的选项放 options 第一个、标签里自己写 (推荐) / (recommended) 即可(/cron 的确认框一直就是这么写的)。标记落在标签里无害——它只是给人看的文字;而「哪个是推荐」本来就是模型这一轮的判断,工具再记一份 recommended 字段既要校验(精确/忽略大小写匹配、不匹配报错)、又要维护带标记与不带标记两份列表,全是为了一句排序约定。
  • ask_user_question 结果块的 Q 带上候选项:翻回 transcript 时原先只看得到问题和最终答案,选项在提问组件消失后就没了,答案成了没上下文的标签。工具返回现在带上 options,结果块按 1. / 2. 列在 Q 下面(和提问组件同一套编号);旧 payload 没有 options 时回退读这次调用的 tool_args。
  • Responses API 的 provider_data 只留 replay 真正读的部分:单条 assistant 少扛 29KB 请求回显。_assistant_message 过去把 response.model_dump(exclude_none=True) 整包挂到 Message.provider_data 上并落盘,而这个 dump 绝大部分是请求回显:在一份 54MB 的存量 transcript 语料里,tools 一项占这些 blob 的 89.2%(395 条 assistant 条目共 11.7MB,全库只有 3 个 distinct schema 被逐条重复),其余是 temperature / tool_choice / truncation / store 这类请求参数。而它没有任何消费方:replay 侧 _assistant_items 只读 object 与 output(合计 7.9%),provider_data 是 local-only 字段、永不上 wire(Message.to_dict 白名单,由 tests/model/test_wire_payload_allowlist.py 钉住),Responses 的 stateful 链接走的是另一个字段 provider_checkpoint(单独落盘,previous_response_id 未被使用)。改成在生成处按白名单 {object, output} dump —— 不是把 tools 拉黑,这样将来新增的臃肿回显字段不会重新把日志撑大;内存里也不再扛这份拷贝。零信息损失:同文件既有的 replay 用例(reasoning → function_call → function_call_output 重建、encrypted_content 透传)原样通过。新增一条用例,构造带 8 个 500 字描述的工具 schema 的响应,断言 provider_data 键集恰为 {object, output} 且 replay 仍能重建;把白名单改回整包 dump 该用例立刻失败。
  • 两条 flaky 测试定位并修掉,全量套件从「偶发红」变成可连绿。都不是产品代码的问题,是断言写法对随机输入不成立: ① tests/cli/test_fork_command.py::test_an_unknown_fork_point_is_refused(实测 7/40 失败)。 /fork 的定位顺序是「先当索引、再当 uuid 前缀」,而 session fixture 用真实 uuid4()——只要某条目 uuid 恰好以 9 开头,本该越界被拒的 "9" 就会作为合法 uuid 前缀命中,fork 成功。改成在 fixture 里把 uuid4 patch 成确定的、字母开头的序列,数字前缀碰撞从此不可能。修后整文件 40/40 连绿。 ② tests/gateway/test_gateway_channel_wechat.py::test_hex_encoded_aes_key_decrypts_voice_payload(实测 2/30 失败)。 用例要验证「hex 包装的 key 被当成 AES-256 会 unpad 失败」,但 pycryptodome 对同一件事有两种措辞——长度字节越界时是 Padding is incorrect.,填充字节不符时是 PKCS#7 padding is incorrect.,随机 key 下两者都可能出现,而 match="Padding is incorrect" 是大小写敏感正则,匹配不上后者的小写 padding。改成 match="(?i)padding is incorrect"。修后 60/60 连绿。
  • 缓存写入单独计量,两条测试 bug 修掉。三件小事,都是上一条 session-log 改动的收尾: ① trajectory_stats() 新增 cache_write_tokens。 之前只统计两个「命中」计数(cached_tokens / cache_read_tokens),把写入缓存漏在外面——而 Anthropic 是按第三档单独计费的(写入 > 未命中输入 > 命中,Claude 那档是 $6.25 / $5 / $0.5 per 1M),漏掉它等于漏掉一整项成本。刻意不并进命中率:把写入算作命中,会把缓存支出报成缓存节省。取值口径与 split_prompt_usage / model/base.py 对齐——先读 prompt_tokens_details.cache_creation_tokens,回落到 cache_write_tokens,两个拼写是同一个量的别名所以取其一而非相加(provider 同时给出两者时相加会重复计费)。evaluation/run.py 同步追加 avg_cache_write_tokens。在 13 个真实 transcript 上验证过:抽 5 个逐字段与独立重算比对,cache_write / cache_read / cached / input 四项全部吻合(最大一个 426,433 写入 / 4,465,624 读取)。 ② tests/model/test_cache_observability.py 删掉 TestStatusBarCacheSegment。 e9b1edb 已经故意把状态栏的 cache NN% 段连同 build_status_bar_fragments(cache_hit_ratio=) 参数一起移除(同时更新了 tests/cli/test_usage_display.py),但漏删了这个文件里的两条用例,于是它们一直以 TypeError: unexpected keyword argument 'cache_hit_ratio' 挂着。事件层的 cache_hit_ratio 仍在,同文件其余用例保留。 ③ tests/utils/test_langfuse_shutdown.py::test_peek_failure_degrades_to_none 的假通过修掉。 它用 _BoomRM 伪造「私有 API 漂移」,但 _instances 写成了普通 @property,而被测代码是在类上取这个属性——类级取 property 只会拿到 property 对象本身(真值、不抛),于是根本没走到 except,而是继续调 get_client():隔离跑时它因未配置而抛异常,测试碰巧变绿。全量套件里前面的测试让 langfuse 可初始化后,get_client() 成功、真的 spawn 出一个常驻 langfuse-shutdown 线程,于是①本用例失败,②按字母序排在它后面的 test_returns_none_when_not_configured 也被这条残留线程带挂。改成把 _instances 放到 metaclass 上(类级访问真的抛),并补一条「降级为 None 时不得留下线程」的断言。全量套件从 3 failed 归零。
  • session log 从「回合末反推的镜像」升级为「可断言的轨迹」:日志一直是回合末遍历 run_response.messages 重建出来的,没有任何不变式保证「写进日志的 == 当时真发给模型的」——而这类 bug 已经发生过一次(runner/persist.py 的注释记着:上一版把所有 assistant 分组排在所有 tool 之前,resume 时 provider 400 messages with role 'tool' must be a response to a preceding message with 'tool_calls'),修好了却没留下断言,所以同类回归可以再次静默发生,且只在用户 resume 时才炸。四件事: ① 投影 + 等价断言。 新增 SessionLog.derive_messages()(薄封装 load();since_uuid= 切出本回合尾部;保存/恢复 _last_uuid,所以推导不扰动 append 链)与模块级 assert_trajectory_equivalent():只比结构——role 顺序、tool_calls id 的集合与顺序、每个 tool 结果必须应答紧邻它之前那个 assistant;不比 content(压缩、marker、synthesized 消息合法地改写 content)。两条归一化编码了「日志与内存之间合法的差异」:既无文本又无 tool_calls 的消息丢掉,连续的纯 user / 纯 assistant 折叠成一条(日志每回合只写一条 user 与一条终答)。runner/loop.py 在回合三段日志写完后挂上 _check_session_log_trajectory——DEBUG 才开、只 warning、整体 try/except:日志保真是可观测性问题,不该把用户正在进行的对话打挂;它真正的价值是让测试能抓住那类回归。负向测试手工构造「所有 assistant 在前、所有 tool 在后」的坏日志并断言能被检出(把校验函数改坏自检过:3 条负向用例确实会挂)。 ② 回合内增量落盘。 每轮工具跑完就写(_flush_turn_tool_rounds),不再等回合末——进程内 cancel/异常本来就有兜底,但 SIGKILL / OOM killer / 断电会把跑了几分钟、几十次工具调用的整个 turn 全丢。回合末原有写入点变成补齐:SessionLog.begin_turn() 记下本回合已落盘的 tool_call_id 与 assistant 轮次,_persist_assistant_tool_calls() 按 id 跳过,两条路径因此天然幂等(把去重关掉,端到端测试立刻看到同一个 tool 落盘三遍)。只写已应答的轮次(复用 _drop_unanswered_tool_calls):孤立的 assistant(tool_calls) 正是 provider 在 replay 时拒绝的形状。用户问题改由「本回合第一次落盘」写(而不是回合开始),所以顺序仍是 user → assistant(tool_calls) → tool → …,且被 input guardrail 挡下的输入不会留在日志里。fallback transaction 期间不增量写:那些结果最终要落成不可重放的 tool_audit,而这只在回合末才知道。 ③ 被硬杀的 turn 在 resume 前封口。 SessionLog.seal_incomplete_turn():日志尾部若是「有问无答」(或停在 tool 结果上),先追加一条 assistant 标记再回放,否则剥离 tool 工件后 wire 上会出现两个连续 user turn,strict provider 拒收(同族注释见 runner/steer.py)。append-only、幂等,只在 resume 路径调用。 ④ 轨迹指标从「写了没人读」变成指标。 SessionLog.trajectory_stats() 聚合日志里真实存在的字段:turn/step 数、tool 调用数、工具错误率(取 is_error——落盘用的是这个键名,_build_messages 读回来才叫 tool_call_error)、按 tool_name 分布、token(metrics.input_tokens/output_tokens/total_tokens)、缓存(metrics.prompt_tokens_details.cached_tokens 与 cache_read_tokens,前者 OpenAI 兼容、后者 Anthropic 风格)、completion_tokens_details.reasoning_tokens、compact_boundary 计数。字段名先在真实 transcript 上核过才实现,没有数据的指标就是 0,不估算。evaluation/run.py 每个实例落一份 transcript 并追加 trajectory_statistics(含工具错误率与缓存命中),accuracy 与既有 statistics 块一字未动,老 summary 仍可比。 测试:tests/memory/test_session_log.py(+25:derive 切片/边界、等价断言的 3 条负向用例、增量落盘幂等、硬杀后轨迹仍合法、封口幂等、指标聚合)、tests/runner/test_runner.py(+2 端到端:流式与非流式各驱动一个带工具调用的完整 turn,断言日志正好是 user/assistant/tool/assistant 一份不重)。
  • 派出去的活现在会自己回来:worker 完成回报的地址不再失效,header 也不再说「可以不回」。这三处凑在一起,效果是「手机派活 → 人必须自己去终端把结论抄回来」,也就是多会话协作里最费人的那一段: ① GatewayAgentPeers 的 peer 身份不再每次重建就换一个。 session_for 过去在缓存未命中时 new_peer_id(),而短名里嵌着 id 前两位(wecom-agentica-64),所以 LRU 赶出会话、delete_session、网关重启之后,同一个微信对话换了名字回来——CLI 半小时前被告知「做完回报给 wecom-agentica-64」,此时 send_message 直接是 no live session matches,报告发不出去,没人知道活干完了。现在 peer_id 由 session_id 派生(_stable_peer_id,sha1 前 8 位),名字成了这段对话的属性而不是缓存的属性。顺带修掉同一族的第二个漂移源:forget() 会把 note_route 记的回信路由一起丢掉,于是重建时渠道前缀退化成 web-,wecom-agentica-64 变 web-agentica-64——LRU 驱逐现在走 _unpublish()(只下线、保留路由),forget() 仍然整条清掉,留给真正的删除会话/停机。 ② 注入 worker 上下文的消息头改口。 format_for_model 过去以 reply with send_message to X if needed(用户转发)/ only if it is waiting on an answer(另一个 agent)结尾——派活方从来不是「看得出在等」的样子,所以 worker 干完活谁也不通知。PEER_MESSAGING_POLICY 里那句「做完或卡住要回报派活方」是常驻指令,斗不过每条消息自带的这句。现在两个分支都点名回信地址并要求「done or you stop 时回报」,纯告知类消息仍然明说不需要回复。 ③ 消息只带结论,证据发路径。 send_message 的 message 参数文档过去写「self-contained:接收方只看得到这段文字」,读起来就是「把 diff/日志粘进来」——而一条消息是直接注进对端上下文窗口的,粘 8k 字等于花掉对方用来干活的窗口。现在 docstring 与 policy 都写明:正文是指令要自洽(目标、边界、卡住怎么办),diff / 日志 / 长篇 review 落成文件、消息里给绝对路径(机器是共享的,对端要细节时自己读一次就行)。MAX_MESSAGE_CHARS = 40000 的硬顶不变,这条是让模型远在撞顶之前就走路径。 测试:tests/gateway/test_gateway_agent_peers.py、tests/peers/test_peers.py(新增用例在旧代码上确认失败)。端到端 smoke tmp/smoke_peer_reply_roundtrip.py 走完整链路(手机派活 → CLI 收到 header → 网关会话被驱逐 → 重建 → CLI 按原地址回报 → 结论推回微信),在改前的 agent_peers.py 上 4 条断言全挂,其中包括「回报根本发不出去」。
  • execute 收尸不再无界等待,界面上也不再出现 BaseSubprocessTransport.__del__ / Event loop is closed:起因是 node server.js & sleep 0.6; curl … 这类命令跑了几百秒不停止,Ctrl+C 之后一段 asyncio traceback 直接印在下一轮回答中间。三件事连成一串,逐个说: ① 卡住的原因是 stop() 看错了对象。 shell 把 node 丢到后台后自己退出,而 node 继承着我们的 stdout/stderr PIPE 写端——communicate() 等的是管道 EOF,不是子进程退出,所以永远等不到。120s 超时确实触发了,但 terminate_subprocess.stop() 第一行是 if process.returncode is not None: return:我们的直接子进程(shell)早已退出,于是 SIGTERM/SIGKILL 一个都没发出去,进程组照跑,接着 await process.communicate() 无界等待,整轮就停在那里。实测(tmp/probe_orphan_pipe_holder.py):这条路径要等后台进程自己寿终,脚本 45s 才返回;用户遇到的是几百秒。现在 killpg 打的是进程组,不再拿自己子进程的退出码当门禁;拆除阶段每次排空都有上限(DRAIN_TIMEOUT_SECONDS = 2),因为写端还可能被组外进程持有(setsid 出去的),EOF 只能尽力而为。 ② 顺带不再留孤儿。 超时/取消的命令连同它在后台起的进程一起被杀 —— 之前 node server.js 会继续占着 8899 端口活下去。 ③ traceback 是上面那次没排空干净的后果。 在收尸自己的排空里再按一次 Ctrl+C(CLI 就是提示"press Ctrl+C again"的),transport 会带着一个仍注册在 loop 上的读管道被丢下;下一轮 GC 时 __del__ 在已关闭的 loop 上 call_soon,CPython 把 Exception ignored in: BaseSubprocessTransport.__del__ / RuntimeError: Event loop is closed 写到 sys.stderr——而 prompt_toolkit.patch_stdout 把 stdout 和 stderr 都换成了 TUI proxy(上一条 changelog 说"只 patch stdout"是错的),所以它就印在回答中间。现在 transport 一律在活着的 loop 上 close(),__del__ 变成 no-op。正常读完的命令不受影响(管道已在 EOF 时自己关闭,__del__ 本来就是 no-op —— 这也是为什么只有异常路径会漏)。 收尸统一在 execute / grep / shell / verify_completion(test) 的 finally,条件从 returncode is None 改成 not drained("命令没被正常读完"才是要收尸的条件,进程已退出而管道还开着正是要覆盖的那一种)。asyncio.shield 去掉了:实测单次取消并不会打断 finally 里的 await,而 shield 会在 loop 关闭时留下一个悬挂 task,换一种漏法。始终不装 sys.unraisablehook。测试 tests/utils/test_async_utils.py(7 例,其中 5 例在修复前的代码上确认失败:整套跑完从 144s 降到 2.7s,因为旧代码是靠干等把后台进程熬死的)。断言用的是 sys.unraisablehook 记录而不是 stderr 内容——pytest 的 unraisableexception 插件会先把它变成 warning,盯 stderr 的断言在坏代码上照样通过。
  • Gateway agent 的 peer 名从超长 gw-wechat-<openid>-xx 改成 CLI 同款短名:此前 session_for 把 IM 的 channel_id(微信 openid)塞进发布名,list_agents 里出现 gw-wechat-o9cq8035jyckmmlzta33-mkm-41,CLI 要 send_message 把完整结果推回手机时 target 没法敲。现在形状是 {渠道}-{cwd 末级目录}-{peer_id 前 2 位}(微信从 agentica 仓库起就是 wechat-agentica-41,网页是 web-proj-0f);openid 仍记在 note_route 里当回信地址,不进名字。渠道前缀继续把这类名字挡在 CLI 的 <folder>-<xx> 和 bridge 端点的 <channel>-<sender> 之外。测试 tests/gateway/test_gateway_agent_peers.py。
  • Gateway 媒体路由改为「图片给底模,音视频给 Gemini」:删掉扫遍 config.yaml profile / 名字启发式(vl/4o/seed)/ modalities: 声明的三级探测——那套会让一张图静默落到随手加的某个 VL 上。现在两条规则:图片在底模 supports_images(或底模 id 是 Gemini)时挂 agent.run(images=),否则一次性让 settings.media_model 描述;语音/视频仅当底模是 Gemini 时直挂,否则同一 media_model 转写/描述。media_model 是 settings 里一个模型块(model_provider/base_url/api_key,model_name 省略则 gemini-3.6-flash);没配就回复里说明怎么配,不再猜。测试 tests/gateway/test_media_understanding.py。
  • Gateway 启动 banner 打印 Log File 路径,并写入与 CLI 同一套 pid 日志:SDK 默认不落盘(import agentica 不能在 ~/.agentica/logs/ 留文件),CLI 早就 opt-in 成 YYYYMMDD-<pid>.log,gateway 作为同样的长跑进程却只打 stdout——微信发图这类错误滚出终端就找不到。现在 lifespan 调同一入口 enable_process_file_logging(),banner 多一行 Log File (INFO): ~/.agentica/logs/20260814-65634.log;AGENTICA_LOG_FILE="" 仍是显式关闭。测试 tests/utils/test_process_file_logging.py。
  • 同文件多次写入不再把整份最终 diff 重复打三遍:tool_display_meta(每次调用自己的 before/after)只活在 chunk.tool_call 上,run_response.tools 累积列表刻意剥掉以免 session log 存整文件。CLI 完成事件却去读 chunk.tools,meta 全部丢失,展示层只好拿「批次开始时的磁盘」对「现在的磁盘」——于是 apply_patch 之后两次 edit_file 同一文件,三条都是从文件头到改完的同一份 diff。现在完成事件改读 chunk.tool_call,每个调用只显示自己那一刀。
  • /status 显示当前 CLI log 路径:启动 banner 里的 Log File 滚上去就找不到。log 是这个进程的运行时事实(pid 日志),不是 /config 管的可改配置,所以只出现在 /status,不进 /config / /config path。
  • CLI 的 execute 10 秒内不再显示耗时:完成行尾的时间戳把「多慢算慢」从统一 1s 改成按工具定(_MIN_ELAPSED_DISPLAY)——编译、跑测试合法地要花几秒,9.99s 还报 (9.99s) 纯噪音;execute 起报线 10s,其余工具保持 1s,subagent 的 verbose 完成行同规则。新增边界测试(0.5/1/9.99s 隐藏,10/65.4s 显示,grep 不受影响)。
  • apply_patch 预检失败不再贴文件头、也不再附带 read_file 教条:hunk 从文件开头搜不到时,以前 Actual from line 1 把文件头(encoding/@author)当成对照,模型会按这份无关文本重写 hunk;现在按期望上下文里独特的 def/class/长行定位真实区域,对不上就明说 None of the expected lines appear in the file.。末尾那句 Read or re-read each failed region… 已在工具 docstring 里,从错误正文里删掉。
  • apply_patch 预检失败的 Expected/Actual 预览不再把唯一的差异折掉:两个块各自硬切前 6 行,于是「前 6 行一致、第 7 行才不一样」的 hunk 打出两段逐字节相同的预览,真正对不上的那行藏在 ... (1 more context lines) 里——错误看起来自相矛盾(明明一样却说 context not found),模型只能瞎改重试。实测复现于 README 改动:上下文里那条很长的 v1.4.7 被写短了一截,报错却完全没显示它。匹配逻辑未动(_find_context 仍是整块精确比对 + 空白/引号 fuzz,这次失败本身是正确的),改的是 ContextFailure.render():先算出第一处不一致的下标,把 6 行窗口滑到能看见它(保留 2 行 lead-in,前面折掉的行注明 ... (N earlier lines match)),两个块用同一个窗口以便逐行对照,该行以 > 标出,末尾补一句 First difference at context line N (file line M);期望块比文件区域长(EOF 一带)时说明 the file region ends before the hunk does。短 hunk 的输出形状不变(不加窗口注记、不加 First difference 行)。
  • 路径不存在错误去掉 Next step 教条:read_file/grep/glob/edit_file 找不到路径时仍报 Resolved path 和 Nearest existing parent,不再附带 use ls/glob/grep… do not retry speculative absolute paths——怎么搜、别猜路径已经写在 tools.md 和工具 docstring 里,每条错误再复述一遍只占 CLI 和模型上下文。
  • Gateway 个人微信支持图片/语音/视频理解(多模态路由):此前微信收到的图片、语音、视频在 _process_channel_message 里被静默丢弃(只传文本)。现在两条规则、不扫 profile:图片在底模能看(supports_images,或底模是 Gemini)时挂 agent.run(images=) 让底模看像素;语音/视频仅当底模是 Gemini 时直挂(视频以 data:video/mp4;base64 内联块走 images=,Gemini OpenAI 兼容端点的惯例,SDK 并无模型消费原生 videos=)。其余一次性交给 settings.media_model(指向 Gemini,model_name 缺省 gemini-3.6-flash)描述/转写,注入用户文本并在回复加一行小注。未配置 media_model 则 warning + 回复说明怎么配。微信语音 silk 解码用 graiax-silkcoder(纯 Python,已加入 wechat extra)或 pilk,解不出时回复提示安装;>15MB 视频跳过(Gemini 内联上限 ~20MB)。新增 gateway/services/media_understanding.py(MediaUnderstandingService + 进程级单例,AgentService.chat(media=...) 透传)、channels/base.py 的 InboundMedia 与 Channel.fetch_media()(默认空,WeChat 实现 CDN 下载+解密)、wechat 的 extract_media_typed()(metadata["media"] 改存 {"kind", "media"} 类型化引用,视频缩略图不参与理解)。行为级测试 tests/gateway/test_media_understanding.py(底模直通、media_model 描述/转写、未配置、超大视频、silk 解码与缺库路径)+ wechat 渠道与 queue/agent_service 接线测试。
  • 多会话共用一个仓库:presence 带上 git 状态 + 一个任务一个 worktree(新增 agentica/git_state.py、agentica/worktrees.py、agentica/peer_conflicts.py、agentica/cli/worktree_binding.py、agentica/tools/worktree_tool.py):几个会话(终端 CLI、手机遥控的 CLI、网关 agent)改同一个仓库时,贵的不是合并冲突,而是互相覆盖和互相打听。分两条治: ① 不用问就知道对方在干什么。 每个会话在既有心跳里发布 git 位置(分支 / head / 相对基准分支的 +ahead/-behind / 脏文件列表),list_agents 与 /list-agents 直接显示 git: main @ 8ca321e · 3 dirty + dirty: a.py, b.py。基准分支取本地 main(无则 master)而不是 upstream——另一个会话提交到本地 main 还没 push 时 origin/main 看不见它,而那正是你要撞上的人。采集有 10s 缓存、心跳仍只在变化或 30s 到点时落盘,不会变成每秒三次 git 调用。dirty_count 用 Optional[int]:None=没采集过、0=真干净,老记录只显示 git: <branch> 而不会冒充 "clean"("clean" 是别人据以决定能否 rebase 的信息)。 ② 写文件时一次性提醒。 落盘那一刻若另一个 live 会话(同仓库,可以在别的 worktree)也把这个文件改脏了,写入结果追加一行点名是谁、在哪个分支哪个目录。只提醒不拦截(两个会话同改一个文件有时正是对的,拦住只会把 agent 逼死);只比同一个仓库(peer 发布 repo_root,否则满世界的 README.md 互相报警,而同仓库两个 worktree 仍会命中);同文件同 peer 只说一次(每次编辑都提醒等于训练模型忽略它)。 ③ 合并回去但不删 worktree。 顺序是刻意的:先在 worktree 里把基准分支合进来(冲突就留在写这段代码的会话手上、在它自己的目录里,而不是把半合并的 index 扔在所有会话共用的主 checkout),再在主 checkout 里 fast-forward。两个会话同时 merge 时 git 自己的 index.lock 就是互斥锁,只等它(重试 5 次),不另造锁。副产品正是长期可用的关键:合完后 worktree 与基准分支齐平,下次接着用不背旧历史。从不删除、没有自动清理——它值钱的就是暖好的 IDE 索引、装好的 venv 和一屏 shell 历史。 默认位置与配置:主 checkout 的兄弟目录 ../<repo>-<任务> + 分支 wt/<任务>(人可读、可 cd、和手工 git worktree add ../xxx 同一个直觉)。两种情况可改 settings.worktree.root:父目录塞了二十个仓库、或共享挂载父目录不可写(不可写时报错直接点名这个设置);写相对路径会落在仓库内(Claude Code 的 .claude/worktrees/ 形态)——支持但不默认,实测主 checkout 里一条 git clean -xdff 会把这棵被 gitignore 的树连同别的会话未提交的工作一起删(--dry-run 报 Would remove .agentica/),而这些 worktree 是要长期活着的。.env 等 gitignored 文件按 settings.worktree.link symlink 而非拷贝(轮换密钥一次生效、机器上只存一份;缺 .env 的症状是"会话起来了但连不上模型",和原因八竿子打不着)。 行为级测试 90 例(tests/peers/test_git_state.py / test_worktrees.py / test_worktree_binding.py / test_worktree_tool.py / test_peer_conflicts.py,全部用真 git 真目录):ahead/behind 取本地 main、老记录不冒充 clean、脏文件截断与计数、复用不重建 / 前台目录被手删后分支还能重新 checkout / 别人的同名目录只报错不清理、--git-common-dir 保证在 worktree 里再建 worktree 也落在主 checkout 旁、symlink 的四种边界、merge 的 6 种拒绝与冲突留在 worktree、冲突提醒的跨仓库精确性与去重、工具 dispatch 的各种拼法。文档见新增的 docs/multi-agent/worktrees.md(含 4 个实测坑,例如 agentica 命令永远跑主目录代码、而 python -m pytest 在 worktree 里跑的是 worktree 代码)。
  • 仓库内 worktree 布局(worktree.root: .agentica/worktrees)升级为一等支持:Claude Code 的 .claude/worktrees/ 形态,此前只是"相对路径也能用",现在选它不需要任何准备。三处修好:① 路径不再插冗余的仓库名(仓库已由位置隐含,<repo>/.agentica/worktrees/<任务>);② 自我忽略——首次创建时在 .agentica/worktrees/.gitignore 写一个 *,git status 干净且绝不改仓库里那个被跟踪的 .gitignore``**(共享文件,工具不该替人改;同 pip 缓存的做法);**③ 搜索工具跳过.agentica**——实测仓库内布局会让glob("/*.py")把每个文件返回 N+1 份(噪音是小事,**改到副本那一份**才是大事),grep走 ripgrep 本来就被 .gitignore 挡住,glob与 grep 的纯 Python 回退各自走自己的遍历、之前没挡。修的时候测试又逮到一个更严重的:排除规则原先匹配**整条绝对路径**的 parts,于是一个 work_dir 本身就在.agentica/worktrees/里的会话glob自己的文件会**返回空**——改成只匹配搜索根**以下**的相对路径(_in_noise_dir)。 默认仍是 sibling(../-<任务>),理由是错误代价不对称,且两条都实测过:git clean -xdf(单-f,最常打的那条)对嵌套 checkout 是Skipping repository→ **安全**;git clean -xdff(双-f)是Removing .agentica/→ 树连**别的会话未提交的改动**一起没,注册项变prunable。sibling 布局下这条命令完全无害。所以:sibling 选错 = 报错 + 加一行配置(可恢复、可见),仓库内选错 = 某次双-f清理顺手删掉三个会话的活(不可恢复)。仓库内布局的优点(父目录不被污染、只要仓库可写就能用、删仓库时 worktree 跟着走、与.cursor//.claude/同一心智)全部保留,一行配置即可切换。 搜索排除随后改成**问 git 要**(git worktree list,按仓库 10s 缓存)而不是按名字匹配:嵌套 worktree 不一定是 agentica 建的——本仓库当时就有另一个会话手建的临时.worktrees/wechat-media,实测主 checkout 里glob("**/peers.py")真的返回了它那一份副本。排除永不包含搜索根自身,所以绑定在该 worktree 里工作的会话照样看得见自己的文件;grep侧同时给 ripgrep 加--glob !<相对路径>/`(嵌套 worktree 不一定被 gitignore 挡住)。
  • 微信轮询循环把网络异常从 error 降为 warning:run_loop 的兜底错误日志对 requests.exceptions.RequestException(连接重置/超时等预期内网络抖动,退避后自愈)改走 logger.warning,其余异常仍为 logger.error;退避序列(2s/2s/30s)不变。行为级测试断言 ConnectionError 只产生一条 warning、无 error。
  • Gateway 自己的 agent 现在也能 list_agents / send_message 本机 CLI 会话(新增 gateway/services/agent_peers.py):此前 PeerMessagingTool 只在 cli/runtime.py:968 挂载,AgentService._build_agent 只加 cron + self_manage 工具——于是在微信里说「让本机所有 CLI 会话都把改动提交了」,接住这句话的 gateway agent 一个会话都看不见(实测调用 list_agents 返回 function not found)。能用的只有用户自己打 @<会话名> 逐个寻址的 bridge 路径,README 里「多个会话组成一支队伍 + 人可以离开现场」这条最大卖点,在离开机器时其实只剩半条。现在每个 gateway 会话(网页的、每个 IM 会话的)也是 peers 通道上的一个 peer,发布成短名(wechat-agentica-41:渠道 + cwd 末级目录 + 两位 id),拿到的就是 CLI 本来就有的那两个工具——没有新协议、没有为网关新造工具;反向也通了:CLI 会话可以主动 send_message 给 wechat-agentica-41 把结论推回手机。 卡住这个设计的几条:渠道前缀不是装饰——match_peers() 把名字前缀当地址,第三种名字形态({channel}-{folder}-{xx})必须既不遮蔽 CLI 的 <folder>-<xx> 也不遮蔽 bridge 端点的 <channel>-<sender>。邮箱谁来收取决于有没有在跑:agent 正在跑那一轮时由 Runner 收进上下文(agent.peer_session,与 CLI 同一边界——tool 批次之间,绝不打断正在执行的工具),空闲时由 1s 轮询推到对应 IM 会话(前缀 <发信会话名> ›);网页会话没有 IM 回信路径,邮件留在邮箱等下一轮,而不是被消费掉没处放。回信路由是记下来的、不是解析出来的:main.py::_handle_channel_message 同时知道 session_id 和会话,事后再把 agent:{agent_id}:{channel}:{channel_id} 拆回去是猜。live 记录不能比会话活得久:agent 是 LRU 缓存、淘汰时不通知任何人,所以轮询按 has_cached_session 反查并 unpublish(该查询走新增的 LRUAgentCache.contains,不能碰 LRU 顺序——否则轮询自己会把陈旧会话续命、把用户正在说话的那个挤掉),delete_session 则立即 unpublish。cron 不参与:它每次跑都是用完即弃的 agent,发布邮箱没人读。只有一个开关:PEER_BRIDGE=false 同时关掉两条路径,因为是同一个信任边界(网关能否往你的终端里敲字)。网关 agent 自己被排除在 @list 与 @ 寻址之外(不打 @ 就是在跟它说话,转发给它只会原样回声)。 行为级测试 tests/gateway/test_gateway_agent_peers.py(21 例):短名(渠道+目录+两位 id,不含 openid)与网页 web-<folder>-<xx>、note_turn 发布 task/busy、能给 CLI 发信且 from_kind="agent"、回信推到 IM 会话、忙时/无路由时不动邮箱、缓存淘汰后不再可寻址而在跑的会话不被误清、stop() 全部下线、bridge 的两处排除、_build_agent 挂上工具并设置 agent.peer_session(cron 会话不挂)、has_cached_session 不扰动 LRU,以及跑真实 lifespan 断言 deps.agent_peers 与 bridge 的 gateway_peer_ids 确实接上了。 顺带修掉一个只有真跑一遍才会暴露的坑:agent/permissions.py 的 READ_ONLY_TOOLS 是一份按名字硬编码的白名单,"ask" 模式下不在名单里的工具连 schema 都不发——而 ChatRequest.approval_mode 默认就是 "ask",于是网页/HTTP 侧问「有哪些会话在跑」,模型回的是「我没有 list_agents 工具」(实测复现,就是该模式 instruction 里警告的那种「function not found」形状)。list_agents 只读一个目录、什么都不改,加入白名单;send_message 仍然不在——它往别人邮箱里写、代表别人行事。端到端实测两条 surface(真实 lifespan + 真实模型):网页侧与 IM 侧都能 list_agents 到本机 3 个 CLI 会话,网关自己的 peer 按会话发布成 web-agentica-0f / wecom-agentica-f7 并在 shutdown 时全部下线。
  • 修复微信 session 过期后 getUpdates 死循环刷屏(err -14 session timeout,每 ~150ms 一条):bot token 过期后旧代码只清游标、不清 token、不退避,于是拿死 token 以服务器应答速度空转。按 iLink 协议规范(openclaw-weixin protocol-spec §4.4)重写错误路径:get_updates 对任何非零 errcode/ret 直接抛异常交给轮询循环退避(前 2 次 2s、第 3 次起 30s),不再 warn-and-return 制造热循环;-14 判定为 session 过期,同时清掉持久化的 token 与游标(此后即使只重启 gateway 也会直接走扫码登录,不必手动 rm token 文件),并抛 SessionExpiredError 由 run_loop 自动发起与首次 connect 相同的 QR 重登。重登限 3 次、每次间隔 60s——无人值守时不会无限弹二维码;3 次都没扫则停止轮询,错误日志写明人工修复办法:rm <token 文件>(按实际路径输出,默认 ~/.agentica/cache/wxbot_token.json)后重启 gateway。行为级测试覆盖:-14/ret=-14 清凭证并抛 SessionExpiredError、其它 errcode 抛 RuntimeError、退避序列 2s/2s/30s、过期自动重登、重登 3 次未果后停轮。
  • Peer bridge 默认开启(PEER_BRIDGE 默认 true),并删除 bridge 自建的「空 allowlist 拒绝转发」防护:个人助手定位下该防护属过度设计——channel 层的 allowed_users(若配置)本就会在消息到达 bridge 前完成过滤(如 wechat.py _on_native_message),bridge 不再叠加第二道门;需要限制谁能和 bot 说话时仍用 <CHANNEL>_ALLOWED_USERS,对 gateway agent 与 bridge 同一生效。默认开启的影响面:没打 @ 的消息照旧走 gateway 自己的 agent,不拿走任何东西;没装/没开 CLI 时 bridge 空转(无端点时 1s 轮询零开销),@list 回复「本机没有 live 会话」并给出所搜目录;显式 PEER_BRIDGE=false/0/no/off 关闭。可见范围表述从「this OS user」改为「this machine」:真正的约束是 gateway 与 CLI 共享同一个 AGENTICA_HOME(peers 树是其下的 per-install 状态),启动日志与空列表回复均按此口径命名所搜目录。docs/advanced/gateway.md 的 PEER_BRIDGE 节同步改写(默认开启、安全前提改为 channel 白名单单一门、去掉「同系统用户」表述)。
  • docs:gateway 补 PEER_BRIDGE 主打功能,个人微信渠道前移:docs/advanced/gateway.md 新增「手机遥控本机 CLI 会话(PEER_BRIDGE)」整节(@list / @<name> <text> / 裸文字续发 / @off 用法表、转发行按 from_kind="user" 投递的权限含义、必须与 CLI 同一 AGENTICA_HOME 的前提、"无新协议,bridge 只是 peers 通道上又一个 peer" 原理;默认开启与防护口径随上方行为变更条目同步改写);个人微信(扫码即用、最核心的接入)从文档末尾前移到各渠道小节之首(飞书之前),渠道一览表、安装 extras、适用场景列表、整体架构图的平台顺序同步把 WeChat 排第一。
  • docs:gateway「整体架构」图换为纯文本图:mkdocs 用的 readthedocs 主题不含 mermaid 渲染(无 mermaid.js、superfences 也未配 custom fence),站点上整段 flowchart 源码直接外露。docs/advanced/gateway.md 的 mermaid 块替换为等宽的纯文本架构图(```text),GitHub / 站点 / 编辑器预览三处均可正常显示,信息与连线关系不变。
  • CLI 退出提速(修 Langfuse atexit 阻塞):交互模式打印 Goodbye 后进程还要再等 ~2s+ 才真退(实测 1 turn 后 linger 2.87s)——python 解释器销毁时跑 langfuse 的 atexit shutdown:tracer_provider.force_flush()(网络上报缓冲的 OTEL spans)+ join 两个各 ~1s 轮询周期的 score/media 消费线程,空队列也照等;host 不可达时会被网络超时顶到更久。修复为退出路径先在 daemon 线程提前启动 shutdown(与 cron 停止、summary 打印重叠),最后按 0.8s 预算 join:健康网络上 force_flush ~0.1-0.3s 即可完成,被截断的只是 langfuse 的空转轮询 join;最多丢一个 flush 间隔内的 telemetry,shell 提示符立刻可用。agentica "query" 非交互路径同样接入有界关闭(utils.langfuse_integration.start_shutdown_thread / shutdown_langfuse_bounded),行为级测试见 tests/utils/test_langfuse_shutdown.py(不测时间,只测线程语义与 join 预算契约);SDK 进程同样受 langfuse atexit 影响——OpenAIChat.get_client() 无条件包装 LangfuseAsyncOpenAI(与 enable_tracing 无关),SDK 集成方应在自身 shutdown hook 调用 shutdown_langfuse_bounded()(模块 docstring 已补用法)。
  • CLAUDE.md 大幅瘦身(1167 → 786 行),derivable 架构内容拆到 docs/:按「CLAUDE.md 不是中央仓库」原则,删除模型 ls + read_file 即可推出的内容——Project Overview、Common Commands、Architecture 模块地图/key files/代码示例、Unified Configuration System、RAG & Knowledge System、Database/File/Media、Safety Mechanisms、Swarm、MCP、Tool System Expansion、Key Patterns。其中 Unified Config 和 Storage(DB/File/Media)docs 此前缺失,新建 docs/guides/config.md 与 docs/concepts/storage.md 收容(mkdocs nav 已加),其余 docs 已有对应文件(concepts/agent.md、concepts/rag.md、concepts/tools.md、advanced/run-config.md、advanced/mcp.md、multi-agent/swarm.md)。保留的是不可推导的 gotchas 与不变量:Context Compression 两层 + 形态差异、Compaction invariants(三 store 表 + 6 规则)、CLI/SDK assumptions table、Prefix-Cache 优化(marker/breakpoints/routing/cache cliff)、Recording-a-rule-is-not-a-tool、Forking/Delegate/Peer Messaging/Shell escape/Peer bridge、Concurrency is opt-in、Learnings/Code Style/Refactoring patterns。顶部加一句指针指向 docs/。
  • CLI 接入 SDK 已有的 cross-provider fallback 重试机制,config.yaml 适配 fallback_models:近期 LLM API 偶发不稳定,主模型重试(max_api_retry,CLI 默认 2 次)后仍失败则自动降级到 fallback_models 链重试,尽量保证 agent harness 稳定持续运行。profile 新增 fallback_models(模型块列表,字段与 auxiliary_model 同构:model_provider/model_name/base_url/api_key + 可选 tuning)与可选 max_api_retry;同 provider 的 fallback 继承主模型 endpoint/key,跨 provider 用自身 preset / 匹配 profile 的 key,绝不复用主模型 key。/model <profile>、/resume、agentica setup 重跑都会携带这两个字段不丢失;环境上下文新增 Fallback models: 一行便于观测。属临时加固行为,不新增 /model 管理 UI。
  • CLI 工具报错样式去黄色,与正常输出同色:edit_file/write_file/apply_patch 的 - error 后缀([yellow])及各工具错误正文的 dim yellow 统一改为 dim,⎿ ⚠ 前缀保留——工具报错探针(path not found、grep 无匹配)是 agent 正常试探流程的高频事件,不应以告警色打扰;execute 的 lint 诊断(is_diagnostics,非错误)保留 dim yellow。
  • README 三语重构:安装后新增「配置 / Configuration / 設定」章节(env / ~/.agentica/.env / agentica setup 三选一,指向安装文档);快速开始改为 CLI 优先(agentica + 截图),SDK 示例与 DeepAgent 紧随其后,删掉与「Agent 用例」重复的代码块;功能特性按核心引擎 / 长任务与协作 / 记忆与进化 / 集成四组重排;对比表从 LangChain/AutoGen/CrewAI/Pydantic AI 换成直接竞品 Claude Code / Codex CLI / Gemini CLI(模型选择、跨会话协作、/goal、Gateway、自进化 Skill、Python SDK、开源七个维度);News 移除未发版条目,只保留已发布版本;图片统一为 raw URL 并补 alt,LICENSE/CONTRIBUTING 等相对链接改绝对 GitHub URL(修复 PyPI 渲染时的 404 与裂图),badge 8 → 5,「引用」节补 BibTeX 与 CITATION.cff 指引;README_EN.md / README_JP.md 与中文版结构完全对齐,JP 版补上此前缺失的 task/delegate/peer 协作小节。
  • CLI 工具报错全文显示(execute 除外):edit_file/write_file 的错误原本裁成 80 字符尾部、apply_patch 裁成 8 行 tail + 120 字符行宽、其余工具走 4 行 tail 窗口——但这些内置工具的错误是单条诊断消息,病因("found 2 occurrences"、preflight 的失败文件/hunk、unknown config key)全在开头和中段,tail 窗口恰好只留下模板尾巴(... read_file, copy the exact current text into old_string, then retry the edit.),用户完全不知道为何失败。统一改为 _display_full_result_lines 全行全文输出(错误样式、⎿ ⚠ 前缀不变),并加 markup=False/highlight=False 防错误文本里的 [brackets] 被 Rich 当样式吞掉;task 的 subagent 错误同样去掉 120 字符截断。execute 保留 tail 窗口豁免——命令输出长度无界,诊断本就在尾部。
  • CLI diff 展示改为软换行,超长单行不再被屏幕右缘裁掉:edit_file / write_file / apply_patch 的 diff 用默认 word_wrap=False 的 Syntax 渲染——纵向确实是「FULL」从不折叠(注释也这么写),横向却把超宽行无声裁掉:CHANGELOG 一个条目就是 1.5KB 单行,-/+ 的差异点常年躺在第 300 列以外,用户看到的是两条一模一样的截断前缀,完全不知道改了什么。四处 diff 渲染点(stream.py 的 edit/write/patch 三处 + messages.display_diff)全部加 word_wrap=True,行为级测试用真实 60 列 Console 断言长行尾部 marker 留在输出里。
  • 修复 OpenAI 兼容代理偶发 data: data: {...} 双重包装导致的流式中途崩溃:代理把已是 SSE data 的内容又套了一层 data:,OpenAI SDK 只剥一个前缀,剩下的 data: {...} 被直接喂给 JSON parser,抛 json.JSONDecodeError: Expecting value: line 1 column 1 (char 0)——此时往往已输出过 chunk,stream_with_retry 按设计不能重试(重试会重复输出/重复工具调用),整轮任务挂在半路。合法 chat.completion.chunk payload 只会是 JSON 对象或 [DONE],绝不会以 data: 开头,所以这个 framing 错误可以无歧义地修复:新增 agentica/model/openai/sse_sanitize.py 的 TolerantSSETransport,OpenAIChat.get_client() 的默认 http client 改走该 transport,对 text/event-stream 响应按行重组字节流并折叠重复的 data: 前缀(跨 chunk 断行、CRLF、多重包装、data: data: [DONE] 均覆盖),非 SSE 响应(文件下载等二进制)字节级原样透传。SDK 的 create(stream=True) 调用路径不变——langfuse tracing、stream_with_retry 语义、CLI 的 raw error 展示全部保持原样;用户自己传的 http_client 不动。继承 OpenAIChat.get_client() 的子类(含 OpenAIResponses)自动获得修复。
  • CLI /usage 与每轮 footer 的 token/cost 口径对齐 + 修精度 bug:footer 领先字段从「本轮总 token(input+output)」改为「净新增 token(fresh input + cache write + output)」——旧值九成是缓存重读,+ 前缀却暗示"往上下文加了 84.3K",与真实上下文增长(仅 20.8K)矛盾,且 +84.3K 与紧邻的 in 83.9K · out 423 冗余。净新增只排除重读缓存:cache write 是首次发送且按溢价计费的内容,若一并排除,会话首轮/prefix break 后的重建轮(全场最贵)反而显示成最小的数。全缓存轮(净新增为 0)省略领先字段,与成本为 0 时的省略规则对齐。成本格式化统一为 format_cost_usd()(<1 分钱显示 4 位小数,否则 2 位;小到 4 位都留不住的非零成本显示 <$0.0001 而非继续"看着免费",该下限不带 + 号),修掉 footer +$0.00 与 /usage ~$0.0040 打架的精度 bug(stream.py 原本固定 :.2f,非零成本被渲染成"免费");footer 侧补了亚分成本的集成断言,避免只锁住格式化函数、接线仍可静默回退。删除死参数 cache_counts_inside_input 与按 model.__class__.__module__ 做模块名嗅探的 cache_counts_inside_input_for_model(判别逻辑早已在 split_prompt_usage 内靠 key 名完成,该参数从未被引用)。/usage 取本轮 usage entries 改用与 footer 相同的 turn-start baseline(_turn_usage_entry_baseline,交互主路径;无 tui_state 的非交互回退仍按 turns 切片,但夹到 0 以免 turns 计及 aux 模型调用时负索引混入上一轮)。/usage 面板重构:session 级指标(API calls / active time / cost)独立成 Session 分组,不再混在 Latest Turn 下;新增 Net new tokens (fresh + cache write + output) 行与 footer 领先字段对账、Total tokens 改标 Total tokens (billed) 以区分两种口径;Input tokens 行标注 (avg X/call)、API calls this turn 注明 (tool rounds + final answer) 以解释与 footer「N tools」差 1 的关系;Messages 移入 Context Window 分组。
  • 压缩投影补概念层:boundary 记 lineage + resume 校验回退 canonical:append_compact_boundary() 增加 model / lineage_key / covered_prefix_hash(hash 由压缩管理器对"被摘要替换的消息段"按 role+content 计算,观测用);SessionLog.lineage_key() = session|cwd|git_branch|model(刻意排除时间戳/条数/hash,Reasonix promptCacheKey 移植)。load(model=...) 时若最后 boundary 的 lineage 与当前会话不符(切模型/换分支),跳过陈旧 summary、回放完整 canonical transcript(summary 之前的内容物理上一直在盘上,新增 load_pre_boundary() 读取入口);无 lineage 的历史 boundary 与未传 model 的调用方保持原行为。runner 与 /resume 两条 resume 路径都传入当前 model。
  • 辅助任务独立 session(Reasonix planner/executor 分离模式的 judge 版):新增 agentica/aux_session.py 的 AuxSession——按用途持有界且与主对话完全隔离的小 history(system 首位恒定 + 每轮 append 一组问答 → 前缀自动缓存友好;超限按"最老一组"裁剪;reset() 随任务身份切换)。judge_goal 支持传入 session,解析成功的问答才入 history(解析失败/调用失败不污染);GoalManager 为 per-turn judge 持有 _judge_session,set() 新目标时重置防止跨目标锚定。不传 session 保持原无状态行为。
  • 缓存命中观测三件套(对齐 Reasonix CacheState):(1) Usage/RequestUsage 新增 cache_hit_ratio()(split_prompt_usage 归一化 OpenAI inclusive / Anthropic exclusive 两种口径,无缓存数据返回 None 而非误导性 0%);(2) 每请求的 context.usage 事件扩展携带上一条请求的命中率与本轮 prefix_break_index(对每条请求消息算 role+content+tool_calls 摘要、与上次请求 diff 出首个变化下标——append-only 为 None),TUI 状态栏新增 cache NN% 段、break 事件进 debug 日志;(3) SessionLog.cache_warmth_hint() 给出 resume 前 warm/cold/unknown 估计(无 boundary → unknown;lineage 不符或超 TTL → cold),/resume 时写入日志。
  • 开放唯一压缩策略旋钮 AGENTICA_EVICT_THRESHOLD_RATIO:Layer 1 evict 触发比例(默认 0.8)可通过环境变量做项目级 override(放 .env 即可);非法值回退默认并告警,越界值钳到 (0, 0.95) 内——必须严格低于 Layer 2 的 0.95,防止重开分层倒置。Layer 2 触发比例与 EVICT_TARGET_RATIO 刻意不暴露(前者一动就回到倒置陷阱,后者是独立的"压多狠"问题)。under_pressure() 每轮按生效值判定。
  • 缓存字节稳定性变成有测试守护的契约:新增 tests/agent/test_prompt_byte_stability.py(system prompt 两次构建逐字节相等 + volatile marker 前稳定区相等 + 跨 PYTHONHASHSEED 子进程相等——同进程 hash seed 固定会假绿,set 遍历/异步注册顺序漂移只有跨进程才现形)、tests/agent/test_tools_schema_stability.py(tools JSON 两次构建/跨 cwd/跨进程逐字节相等,cwd 泄漏即前缀漂移)、tests/model/test_wire_payload_allowlist.py(载满哨兵字段的 Message 经 OpenAI 与 Anthropic 两条路径的 wire payload 都不含 metrics/references/provider_data/thinking 等本地字段;Anthropic block 透传面显式钉住)。claude.py:format_messages 补注释钉清该边界。审计结论:to_model_dict() allowlist + claude 的属性直读均无可修泄漏,故只加守护不加新出口。
  • 修复 Anthropic 长请求下 auto-compact 摘要必然失败:_summarise_conversation 走非流式 invoke(),而 Anthropic SDK 对预计超过 10 分钟的请求直接报 Streaming is required for operations that may take longer than 10 minutes 并拒绝——需要压缩的会话恰恰是最大、最慢的那一类,等于摘要在最需要它的时候永远拿不到,只能落到 logger.warning + return None,再撞熔断器(连续 3 次失败后跳过压缩)。现在只对这一条错误消息做 fallback,改用 response_stream() 收集分片拼回摘要(_summarise_conversation_stream),其余异常行为不变;流式路径同样经过 redact_sensitive_text 并更新 _conversation_previous_summary,迭代摘要链不断。
  • 压缩触发双阈值改为纯窗口比例,修掉小窗模型每轮触发 auto-compact 的 bug:EVICT_THRESHOLD_RATIO 0.7 → 0.8(evict 起压点),Layer 2 should_auto_compact 从固定的 window - 13_000 改为 int(window * 0.95),随字段 _auto_compact_buffer_tokens 一并删除。原 13_000 是照抄 Claude Code 的绝对值(设计点是固定 200K 窗口,约 6.5%),套到本库 8192–1M 的窗口分布两头都错:小于 13K 的窗口(gpt-4=8192)threshold 变负导致 should_auto_compact 恒真、每轮烧一次 LLM summary——本次修复的核心 bug;1M 窗口则只留 1.3% 余量。行为变化:小窗模型不再每轮触发;200K 触发点 93.5% → 95%(略后)、1M 98.7% → 95%(略前)。两个比例取 0.8/0.95 而非 0.9/0.95 的理由:给 evict 压到 0.5 target 留 15% 缓冲(0.9 起跳要一轮腾出 40% 窗口的 tool result,文本为主的会话做不到,Layer 2 会在 5% 间隙内接力触发,等于同轮两次前缀破坏);且避开与 IRREDUCIBLE_PROMPT_RATIO = 0.9 的字面量撞车。两层同为纯比例后 layer1 < layer2 对任意窗口恒成立,此前"过原点比例 vs 带截距直线"的交点倒置隐患同步消失。
  • native compaction 限额同步去掉绝对 buffer,堵掉同族"小窗恒触发"地雷:Model.native_compaction_token_limit() 的默认实现 max(1, window - 13_000) 删除——声明 supports_native_compaction = True 的子类必须自己覆写,否则直接 NotImplementedError(旧默认在 window < 13K 时塌成 1,任何新 provider 置 flag 而不覆写就会每轮触发 native compaction,此前只是被"base flag 默认 False"掩盖);OpenAIResponses.native_compaction_token_limit() 的 max(1, window - output_limit - 8192) 同样会在小窗塌到 1,改为 max(int(window * 0.8), window - output_limit - 8192)——保留"为 compaction 响应预留输出空间"的语义,但地板对齐下游 should_native_compact min-cap 的 80%,塌缩点不再改变行为。新增 TestNativeCompactionLimits 覆盖:base 默认必须 raise;responses 限额在 8192–1M 全窗口 ≥80% 且 < window 并随窗口单调增长。
  • CLI 工具输出展示精简(对齐 codex 风格):工具报错不再用红色(改 dim yellow + ⚠),且一律「省略前头、保留后面」——单行错误消息保留末尾 77 字符(异常类型在结尾),apply_patch 错误体与通用错误结果保留末尾若干行;execute 输出从 head 10 + tail 10(最多 20 行)改为 tail-only 窗口(≤10 行全显,超长只留尾部 6 行、错误 12 行、diagnostics 8 行),折叠部分以一行 … +N lines (Ctrl+O to expand) 开头提示;工具耗时下限提到 1 秒——(47ms) 这类快调用不再显示,只有耗时较久的调用(主要是前台/后台长任务 execute)才带 (N.NNs)。
  • 本地 SDK/CLI 启动不再被 provider SDK 与远程 model catalog 拖慢:import agentica 不再 eager import openai/anthropic,CLI provider registry、Anthropic setup helper、图片 OCR fallback 都改为按需加载;agentica --version 这类非交互命令也不再提前加载 interactive UI。模型构造时查询 context window / vision 支持不再同步访问 https://models.dev/api.json:catalog lookup 只读新缓存、旧缓存和内置 fallback,CLI 在进入 agent 路径后用带 10 秒硬超时的 daemon 后台刷新,SDK 也公开 refresh_model_catalog() / refresh_model_catalog_in_background(),离线或 TLS 握手慢时不会把首屏卡 10 秒以上。console script 直接指向 agentica.cli.main:main,包根 main 在任意导入顺序下保持 callable;公开 MODEL_REGISTRY 继续返回 provider class/function,不把 lazy import tuple 泄漏给调用方。本机验证:真实交互首 prompt(--no-workspace)从约 12.9s 降到约 1.9s,create_agent() 从约 10.6s 降到约 1.15s,安装包 agentica --version 热启动约 0.87s。
  • CLI profile 改为 session 级持久化,/resume 不再被同目录其它会话的 project active profile 带偏。每个 session 的 <id>.meta.json 现在记录 profile_name/profile_source;agentica resume <id> 与交互式 /resume <id> 会优先恢复该 session 的 profile,再按 config.yaml 当前 profile 定义解析 provider/model/key/tuning,因此同一 work_dir 下用不同 profile 开发的 session 可以各自恢复原 profile。project.json.active_profile 继续保留为该 work_dir 新开 CLI 的最近 active profile,显式 /model <profile> 与 resume 成功恢复 session profile 后会刷新它;--profile/--model_name/... 启动时的显式模型参数仍优先,不会被 session sidecar 覆盖。顺手修正 /model --clear:清掉 project override 后应用 global/default profile,但不再立刻把同一个 fallback 写回 project override。
  • 反转执行中输入的默认语义:普通输入默认 steer 当前任务,/queue 才创建下一轮任务。此前执行中敲的字一律排队等当前 run 结束——纠偏("不是这个文件""报错其实是 503")赶到时 agent 已按旧条件改完,下一轮只能返工。现在普通文本经 Agent.steer() 在下一个 tool 批次边界注入当前 run(不中断正在执行的工具),接受时显示 ↪ Guidance added · /queue to always run next,若 run 先于消费结束则显示 ↪ Current task finished before using the guidance · queued next 并降级入队;/queue <prompt> 显式排队,/btw 并行问无关问题,行为不变。边界:带图片附件的输入与 /requesting-code-review ... 这类 skill 调用仍按新任务排队(steer 通道只承载文本)。可靠性契约"永不丢消息"随之补齐:steer() 已接受、但因到达于 run 的最后一次推理期间而未消费的文本,此前被 _end_steer_window() 静默清空,现在由 agent 暂存(pop_undelivered_steer()),CLI 在 run 结束后自动转成下一轮输入并插在 goal 续跑 prompt 之前;来源属性随 steer 缓冲全程携带(steer(..., relayed=True)),被 park 的 peer/后台消息降级时仍以 __RELAYED__ 标签入队,不会重新获得 slash 命令派发权。连续多条 steer 保持输入顺序、合并为一条在下个推理边界注入(原有行为)。/steer 命令保留为显式形式。
  • /stop 现在必须显式给目标,且只管后台任务:/stop <id|pid|#n> 停一个、/stop all 停全部,不带参数只打印用法并列出可选目标,什么都不停(此前空参数 = 停掉所有后台 agent 任务和后台终端命令——它和 /stop <id> 只差一个 token,又常常在别的任务正跑时被敲下,把"全停"当成缺参数的默认值代价太大)。当前这一轮的中止权收归 Ctrl+C 独有,/stop 刻意不做这件事:Ctrl+C 做的事比 Agent.cancel() 多(唤醒卡在 ask_user_question 上的线程、把常驻 goal 置为 paused 以免轮次钩子立刻续跑、连按第二次升级为强制退出),而且 agent 正等你回答问题时输入框里的任何一行都会被当成答案提交(tui.py 的 input_request 分支),/stop 那时根本到不了命令处理器——最需要停的时候它恰好不可用,再加一条更弱的取消路径只会在关键场景上和 Ctrl+C 分叉。同步改掉所有指路文案:/ps 页脚、状态栏后台提示(/stop <id> to close,窄栏变体不再单列 /stop)、/help 里的 /stop <id|all> 与 Ctrl+C: Interrupt the current task、命令注册表描述。
  • Ctrl+C 中断提示不再宣传 Ctrl+\ 这个当场按了没反应的键:prompt_toolkit 的 raw_mode 会清掉 ISIG(input/vt100.py:262),所以按 Ctrl+\ 在健康的事件循环下只是个被吞掉的 0x1c 字节(仓内没有任何 c-\ keybinding),压根不产生 SIGQUIT——而那条提示恰好只在「循环健康、你刚按了 Ctrl+C」时打印。实测(真 pty:raw 下子进程读到 b'\x1c',cooked 下收到 SIGQUIT)确认 app.py 装的 SIGQUIT 硬逃生口只在 run_in_terminal 的 cooked_mode 窗口内生效,也就是循环被后台写入饿死、正等用户回答那个状态。因此提示挪到 ask_user_question 提问组件下方(Enter to answer · Ctrl+C to cancel · Ctrl+\ if frozen),那里才是它成立的地方。顺带把提问组件的行文本抽成 _ask_prompt_lines,渲染与预留高度同源,不会再各算一套。
  • 修复同批次多次编辑同一文件时 CLI 重复展示最终 diff:edit_file、write_file、apply_patch 现在把工具执行时掌握的真实 before/after 快照作为 display-only 元数据随完成事件透传,CLI 不再根据批次开始/结束时的磁盘状态猜测,也不在展示层重放 edit_file 替换语义。每个调用只显示自己实际执行的变更;多文件 patch 同样使用原子预检得到的各文件快照。元数据不进入模型 API 内容。
  • 交互式 CLI 的 Ctrl+C 中断摘要精简:执行中按 Ctrl+C(含 AgentCancelledError 路径)现在只打 ⚡ Agent cancelled + Worked for … 分隔线,不再附带 Token usage 与 agentica resume <id> 提示——会话还在继续,这两样是噪音。完整摘要只在真正离开会话时打:退出(Ctrl+D//exit)、/new 切换、一次性模式(-p)中断退出。format_session_summary 新增 brief 参数。
  • 删除审查确认的死代码与重复 API 面(均先经全库调用点核实;均不在 docs/API.md 稳定 API 清单内,但属可外部 import 的面,下游若有使用需迁移):compression/tool_pairs.py 整删——sanitize_tool_pairs 唯一生产调用方曾是 context_overflow_threshold 的 FIFO 按位置丢弃,那条路径删掉后只剩测试在引用;Agent.from_parts 及四个 grouped config(AgentDefinition / AgentExecutionConfig / AgentMemoryConfig / AgentSafetyConfig)——同一套 flat 参数的三层包装,仓内唯一调用方是自己的测试,且已与持续扩张的 Agent(...) 参数面漂移;SubagentRegistry 的 listener 机制(on_complete 全库零调用方,且在 "running" 等非完成状态也会触发,契约本身不准确);Agent.clone() 对已声明字段的 getattr(self, "_tool_runtime_configs", {}) / _skill_runtime_configs 防御改为直接访问。连带删掉 CLAUDE.md 整个 Temporal 段落(agentica/temporal/ 已不存在)与 docs/advanced/compression.md 里 sanitize_tool_pairs 的条目。
  • PEER_MESSAGING_POLICY 大幅精简(agentica/tools/peer_tool.py,70 行 → 28 行),并补上 worker 完成回报的正向指令。旧 policy 里"只在 sender 等答案时才回""仅告知的消息无需回复""别发 bare acknowledgement"三条叠加,把 planner-worker 里 worker 做完该发的完成回报也压成了"无需回复的告知"——这正是最近改完 prompt 后 worker 不再主动回报的根因。新 policy 明写:work 做完或卡住时,把结果发回派活方(sender 看不到你的终端,"done" 是你发出去的、不是它能观察到的),同时保留 ask_user_question 相关的限制(peer 派的活,问题用 send_message 回派活方而非 ask_user_question,因为那个框只在你自己终端、没人看)。其余过度限制(label source、log_file/session_log 指引、never ask what permissions refused、when no session affected don't send 等)一律砍掉——LLM 自己能判断。multi-agent skill 的 "Talking to it" 同步精简并补上同一句完成回报。
  • 删除 workspace 根目录的 AGENTS.md:不再创建、不再注入 system prompt,Workspace.exists() 改看 users/ 目录、list_files() 改报这个 user 自己那份。常驻规则只认 users/{user_id}/AGENTS.md + 项目链(repo 根往上)——根目录那份随包发的模板本身就是 You are a helpful AI assistant / 默认 lint 配方这种零信号 boilerplate,而它和用户级那份注入成同一个 prompt 里相邻的两块,读的人无从区分谁说了算。预算顺序同时反过来:现在 users/…/AGENTS.md 排在项目链前面,挤爆时留下的是常驻规则(项目链就在仓库里,一个 read_file 的距离),此前反而是它先被丢。连带删掉 DEFAULT_GLOBAL_FILES 与 initialize(force=...)——force 唯一的作用就是重写那个模板,文件没了它就只是个不做事的参数。为兼容主流 coding agent,默认 CLI workspace 会把 ~/.agentica/AGENTS.md 维护成指向 ~/.agentica/workspace/users/default/AGENTS.md 的 symlink;非 default user 和自定义 workspace 不使用这个全局入口。
  • tool_error / success_pattern 卡片不再进 system prompt(CompiledExperienceStore.get_relevant 过滤,success_pattern 原本已过滤)。实测一个真实会话的 ## Learned Experiences 五条里五条都是 read_file_file_not_found、execute_command_timed_out、tmux no server running 这类我们自己工具的失败遥测——它们既不告诉模型用户要什么,还把真正会改变行为的用户纠正挤出了 top-k。捕获照旧开着(capture_tool_errors=True 不变):skill upgrade 正是拿 tool_error / tool_recovery 事件和卡片给生成的 SKILL.md 里的 gotchas 找依据,关掉捕获等于把那条流水线的证据源抽走,而用户抱怨的只是 prompt。判据写进 ExperienceConfig 的 docstring:capture 决定落盘,injection 决定进不进 prompt,两件事。

features

  • /rewind 端到端接线:一键回退到任意历史 turn(code + conversation),取代 /checkpoint(Reasonix Esc-Esc rewind 的命令形态,5.3 收尾):turn 循环在 _process_stream_response 里自动 checkpoint——每轮开头 begin_turn(记 msg_index = 当前会话长度)、TOOL_STARTED 事件在文件工具真正写入前(Model._run_function_calls_impl Phase 1 先 yield started、Phase 2 才执行)对 write_file/edit_file/apply_patch 的目标路径 first-touch snapshot、finally 里 finalize_turn(成功/取消/报错都落点)。/rewind list 列出历史 turn(号 + 时间 + prompt 预览 + 改动文件数),/rewind <n> 预览、/rewind <n> --yes 执行 RewindScope.BOTH——复用 CheckpointManager.restore 回滚文件(含删除本 turn 新建文件)并按 msg_index 截断会话重建 runs。这就是「agent 跑偏了,不知道它改了哪 20 个文件也能一键回退」的闭环。删除 /checkpoint(手动 list/create/diff/restore)及其测试;新增 agentica/cli/rewind.py(extract_rewrite_paths / truncate_conversation / get_turn_checkpointer)与 tests/cli/test_rewind_cli.py。Esc-Esc 键位:双 Esc 触发 /rewind list(不做交互式选择面板,CLI 不做重 TUI),/undo 弃用并重定向到 /rewind list;修复 /rewind <n> 数字语法解析与 usage 文案里 [list]/[--yes] 被 Rich markup 吞掉的问题。
  • per-turn 自动 checkpoint + rewind(Reasonix internal/checkpoint 移植,5.3,复用 CheckpointManager):新增 agentica/checkpoint.py::TurnCheckpointer——把 Reasonix 消解「per-edit 快照爆炸」的三个设计移植过来:per-turn 聚合(每个 user turn 一个 checkpoint,而非每个 edit 一个)、路径去重(同 turn 内 first-touch 才捕获,后续触碰忽略)、first-touch 捕获(在第一次触碰时读原文,rewind 恢复 turn 起点而非 mid-turn 状态)。配 RewindScope(code/conversation/both)与 RewindResult:code 复用 CheckpointManager.restore 回滚文件(含删除本 turn 新建的文件);conversation 返回 msg_index 会话截断边界(不写文件);both 两者。Checkpoint/manifest 向后兼容新增 turn/msg_index/prompt 字段。这是长时自治运行「可读、可撤销」产品主线的第一步——turn 边界 API 供 CLI prompt loop / Runner / 工具包装器调用,刻意不接进 BuiltinFileTool 编辑路径(同 base 原语的理由:自动捕获属于 turn 循环,不属于 per-edit 工具)。测试 tests/agent/test_turn_checkpoint.py(13 例:dedup、first-touch、多 turn 独立、三 scope、跨进程、无快照 turn 也记录边界)。
  • use_capability 稳定代理 + McpTool.defer_schema(Reasonix use_capability 移植,P0):新增 agentica/tools/use_capability_tool.py 的 UseCapabilityTool,一个 schema 恒定为 action(list|inspect|call|decline) + name + arguments 三字段的代理工具,模型经它发现/检查/调用/拒绝 deferred 工具;McpTool 新增 defer_schema 参数,置 True 时 MCP 函数以 deferred=True 注册——仍在 host registry 可执行,但不再展开进 provider 可见的 top-level 工具 schema。装上/刷新一个 MCP server 不再让 tools 数组漂移、不再从 tools 起点冷启动 prompt cache(v1 G2 里「MCP 漂移」那条 P0-2 刻意不 cover 的场景,由结构解决而非测试豁免)。默认 defer_schema=False 保持原行为,配 UseCapabilityTool 一起用才生效。测试 tests/tools/test_use_capability.py(proxy schema 固定三字段 + list/inspect/call/decline 派发 + deferred 不进 top-level)、tests/tools/test_mcp_defer_schema.py(defer_schema 标记 deferred / 默认展开)。
  • Cache-impact PR 门禁 + cache-guard(Reasonix 工程纪律移植,P0):新增 scripts/check-cache-impact.sh(改到 cache 敏感目录——prompt/tool 序列化、provider wire/cache-control、compression、session_log、cost_tracker——的 PR 必须在 body 里填 Cache-impact + Cache-guard,touch system prompt 面还要 System-prompt-review,empty/todo/tbd/n/a 拒绝)、scripts/cache-guard.sh(跑字节稳定 effect test:system prompt / tools schema / wire allowlist / use_capability)、scripts/check-cache-impact.test.sh(门禁自测)。.github/workflows/ubuntu.yml 新增独立 cache-guard job(仅 pull_request 触发),把「缓存稳定是一等契约」从「有测试」升级为「有流程门禁」。
  • agent 能自己维护常驻规则了,但没有为此加任何工具:memory 的 system prompt(以及 self_manage 的说明)现在写明 AGENTS.md 就是「每个后续会话都会全量注入 system prompt」的长期记忆,用户级在 <workspace>/users/{user_id}/AGENTS.md(CLI 就是 default user)、项目级在 repo 根,用 edit_file / write_file 追加一行即可,并明说链每会话冻结一次、所以下个会话才进 prompt(不说的话模型看本轮行为没变会以为写失败又写一遍)。此前用户说「记住:以后都要 X」时,agent 手上只有 save_memory——那存的是事实、按 query 相关性召回、可能永远不被召回;要真正常驻只能 write_file 一个它得自己猜的路径。注入的每个文件都带 <!-- 路径 --> 头,所以「在哪」本来就在上下文里,缺的只是「这文件是干什么的」。 同一轮里先写过一个 remember(text, scope) 工具又整个删掉(含 Workspace.remember_rule、<!-- agentica:rules:start --> 托管区块、去重、CLI 完整展示、subagent 黑名单):它解决的问题是模型不知道路径,而这一句 prompt 就够;工具那套路径解析、格式约束和幂等比较全是为此付的利息,而托管区块还等于要求人和 agent 在一个「谁都不必约定格式」的文件里约定格式。留下的判据:一个工具要能做到 read_file/edit_file 做不到的事才配存在——有 schema 要校验的文件(config.yaml 的 round-trip,self_manage)、压根没有文件工具的 surface、或者背后没有文件的操作(pip 升级);「模型不知道路径」不在其列。用户级路径在运行时解析(Workspace.user_agent_md_path(),原 _get_global_agent_md_path 转为公开——prompt 文本要点名这个文件,它就成了契约的一部分),不在 prompt 里写死 ~/.agentica/AGENTS.md:default CLI 会把它作为 symlink 兼容入口,但多用户 workspace 每个 user 仍有各自一份 canonical 文件,不能把 tenant 的规则写进 default user。 端到端实测(tmp/agents_md_rule_smoke.py,隔离 AGENTICA_HOME 起两次真实 CLI):第一次说「记住:改完代码要更新 CHANGELOG.md」→ 模型自己用文件工具建出并写进 workspace/users/default/AGENTS.md;随后清空同目录下其它文件(否则「记住」也会被 experience 捕获钩子记下,第 2 步会自己通过)→ 第二次全新会话被问起时直接复述出来。
  • 企微 / 微信 / 飞书 / Telegram 直连本机 CLI 会话(PEER_BRIDGE=true,新增 gateway/services/peer_bridge.py):手机上 @list 看本机有哪些 CLI 会话、@nlp-f1 <话> 说给它、之后裸文字继续发给同一个会话、@off 收手。没有新协议——bridge 就是已有 peers 通道上的又一个 peer(每个 IM 用户一个 PeerSession),所以 CLI 在 list_agents 里直接看到手机、用它本来就有的 send_message 回话,mailbox 顺序、背压、重复/限频刹车、「在 tool 批次边界投递」全部继承而非重写。没打 @ 的行照旧走网关自己的 agent,所以开了这个功能不拿走任何东西。 几条卡死的前提:转发的话按 from_kind="user" 发出,接收端当成在那个终端里敲的字——这正是目的(确实是用户在敲),也是为什么它默认关且空 allowlist 直接拒绝转发:Channel.check_allowlist 把「没配 allowed_users」当成所有人,用来和网关 agent 聊天没问题,用来往你的终端里敲字就是把机器交给任何找到这个 bot 的人(拒绝语里直接写该设哪个环境变量)。它必须和 CLI 同一个 AGENTICA_HOME,否则永远看到空的 live/,而症状和「没开会话」一模一样,所以启动日志和空列表回复都会报出搜索的目录。bridge 消息不进按会话的入站队列:它不跑 agent,而一条 @session 停 要是排在网关 agent 当前那一轮后面就失去了唯一的意义。自己的端点从所有列表与寻址里排除(每个 IM 用户都是已发布的 peer,否则会互相遮蔽真实会话的名字);未知或歧义的名字回的是实时会话列表——手机上你接着需要的是重试用的名字。
  • CLI 里 peer 消息的展示分清了谁在说话:用户从另一个终端(或手机)转发的指令走和你自己打字一样的 ❯ 面板——那个面板是 CLI 唯一的「人说的话」信号,而转发的指令带的正是这份权限;另一个会话的 agent 走不带面板的 Agent <name> › 行,两者再也不会混。此前两类消息都被塞进 ❯ 里,还连带把给模型看的 [Message from another agent session '…' — reply with …] 授权头印给了用户;现在那个头只留在 format_for_model(模型上下文)里,不进 transcript。
  • ask_user_question / confirm 的问答完整留痕:调用行不再重复一份被裁剪的问题(问题和选项在 TUI 的提问组件里已经完整渲染过,重复一遍等于同一个问题印两次、两次都不全),改由结果块完整回放 Q/A 两侧且不折行截断;工具返回里的 prompt 也不再截到 200 字符。提问组件活在 prompt_toolkit 的布局里、用户一答就消失,结果块是这次交互唯一的持久记录,几周后翻回去要能看到当时问了什么、用户怎么定的。
  • wait(timeout=...) 去掉 300 秒硬上限(_MAX_WAIT_SECONDS → _DEFAULT_WAIT_SECONDS,300 现在只是默认值)。此前传 400 会被静默夹到 300,返回一句「还在跑」——调用方并不知道自己的意图被改过。注:这使 1.4.12 里「单次上限 300 秒」的说法失效。
  • wait / delegate / 后台 execute 的命令与输出不再省略(_FULL_RESULT_TOOLS 增加 wait、delegate;后台 execute 的启动行与完成回执单独走完整显示)。这些结果的正文就是「哪条命令、日志在哪、退出码多少」——被折成一行 … 之后,用户既没法接着排查也没法把路径复制出来。
  • OpenAI 侧补上 prompt_cache_key(默认开启,enable_prompt_cache_key),取 session_id,没有会话时退到该端点的粘性路由 id。此前只有 cache_control_session_header 一条路径,那是部分代理的专有 header;跑原生 OpenAI / DeepSeek / Qwen 时走的是隐式缓存,一个路由提示都没传。而隐式缓存命中要同时满足两件事:前缀一致、且请求落到存着这份前缀的那台机器上——路由只哈希 prompt 前约 256 个 token,共享前缀的请求本来就会被摊到多台机器做负载均衡,缓存不会跟着走。prompt_cache_key 会并进这个哈希,官方案例里某编码客户接入后命中率从 60% 升到 87%,gpt-5.6 起更是用上更可靠匹配的前提。作用域按会话:官方建议单个 key 不超过约 15 请求/分钟,一个会话不可能超。 与 enable_cache_control 正交——后者是 Anthropic 的断点协议,这条只是路由亲和性,不认这个字段的端点忽略即可(已在真实兼容端点上验证不会 400),所以默认开启;遇到严格校验未知字段的端点可关。

  • list_agents / /list-agents 多报会话的配置与负载:profile、model(provider/name)、idle/busy、context 已用/窗口。这些字段从 peer 心跳每秒 tick 里带出,读的是状态栏同一份 tui_state——/model、/model --clear、/config set 都能改模型,靠各处 push 迟早漏一条;心跳本身只在值真变了才写盘,不会把 30s 的 presence 写成每秒一次。字段描述的是配置与代价,不是容量:忙着的会话仍会在 tool 间隙收信,将近满的窗口也只是「再塞东西会触发对方压缩」,不是拒收墙。

  • /debug [on|off] 改成会话内开关 verbose 日志(对标启动时的 --debug):无参翻转,on/off 显式设置;写回 agent_config 以便 /model、/resume 重建 agent 后仍在。原先打印的会话事实(model、history 条数等)本来就在 /status。

changes

  • README 重写,并删除 README_JP.md(日文版不再维护,语言切换只剩中 / 英)。开头改成居中的 logo + 一句话 + 下载入口,然后是「为什么选 Agentica」四条(评测、多会话成队、自进化、人可以离开现场),评测只放一张图加一句结论——逐项指标和复现命令本来就在评测页,README 里再抄一遍就是两份会各自过期的数字。「架构」整节移出 README(连同架构图与 agent loop 图)到 架构文档:读 README 的人在决定要不要装,五层抽象不是那个决定的输入。
  • 评测图换成一张纯英文、两个题库维度对齐的对照图,并入库生成脚本 evaluation/code_benchmark/plot_pk.py。原先是两张分别画的中文图(coding 4 个面板、data analysis 5 个面板),刻度和口径都不一样,没法一眼比;现在 2 行(Coding / Data analysis)× 3 列(Accuracy ↑ / Wall-clock ↓ / Input tokens ↓),两边都是实测数字。成本没有单独一列——两边跑的是同一个模型,成本差就是 token 差,而 Codex 侧 summary.json 里的 sum_cost_usd 是 0.0(没实测),单独立一列只能靠换算填。脚本从 results/<run-id>/summary.json 现读现画,不手抄:图和它旁边的表此前就漂过一次(重跑更新了表,图还在讲上周的结果)。字体钉死 DejaVu Sans(matplotlib 自带),所以本机和 CI 出的是同一张图。
  • 文档里的图片链接统一为 raw.githubusercontent.com/.../main/... 绝对路径。docs/guides/benchmark.md 用的是 github.com/.../blob/...png——那在 GitHub 上会重定向,但 mkdocs 站点里渲染成的是一个 HTML 页面而不是图,也就是文档站上那两张图一直是坏的;docs/index.md 用的 /raw/ 形式虽然能出图,但目录一挪就断。
  • .gitignore 里 Python 打包用的 build/ 与 dist/ 收紧为 /build/、/dist/,并补上 desktop/dist/。未锚定的 build/ 把 desktop/build/icon.png(打包图标母版)也一起吞了——和上一轮 lib/ 吞掉 web/src/lib/ 是同一个错:为仓库根写的打包规则,匹配了任意深度的同名目录。
  • DeepAgent.__init__ 不再收 **kwargs,Agent 的 41 个参数全部显式声明(同时删掉 kwargs.setdefault("enable_experience_capture", True) 那处 hack,改成签名里的默认值)。此前多出来的参数被收进 **kwargs 转发给 Agent.__init__——那边是纯 keyword-only 且没有 **kwargs,所以一个拼错或被上游改名的参数死在 Agent 里,报的那句 TypeError 从不提 DeepAgent;对按名字拼 kwargs 的服务来说这就是构造期崩、每个请求 500。现在原生 TypeError 直接点名 DeepAgent.__init__() 和那个参数,且发生在默认模型构造之前(不然会被「没配 key」盖掉)。参数齐备性由测试守住(test_deep_agent_declares_every_agent_parameter):给 Agent 加了参数却忘了加这里,等于让它在预设里静默不可达。 连带的判据:include_* 不是可以按名字拼 kwargs 的稳定契约。同一轮里提过 builtin_tools=False 这个「一键关掉全部 builtin」的总闸,没有采纳——它只管那 8 个 include_*,DeepAgent 仍然 auto_load_mcp=True(mcp_config.json 里有什么就加载什么)并注入 BuiltinMemoryTool,于是这个名字承诺了一个它兑现不了的保证,对白名单业务面比逐个列 include_* 更危险(tmp/deep_agent_no_kwargs_smoke.py 第 4 步就是把这个跑出来看)。真要白名单:用裸 Agent + 只声明需要的预设,再对最终工具表做一条构造期断言——那是唯一能拦住「上游新增一个默认开启的 builtin」的检查。
  • 用户级 AGENTS.md 改为按 user 存放:canonical 文件是 <workspace>/users/{user_id}/AGENTS.md(Workspace.user_agent_md_path();默认 CLI workspace 额外维护 ~/.agentica/AGENTS.md → ~/.agentica/workspace/users/default/AGENTS.md 的 symlink)。此前 default user 特例落在 AGENTICA_HOME、其他 user 落在 users/{id}/,一个概念两个位置:CLI 与 SDK 行为分叉,任何调用方想回答「这个 user 的偏好存在哪」都得先判断自己处于哪种模式。现在只有一套真实布局,CLI 不是例外,它就是 default user;home 入口只是兼容别的 coding agent 的文件系统别名。顺带删掉只在旧 home 模式下生效的 AGENT.md(单数)fallback。 手写过 ~/.agentica/AGENTS.md 的,第一次运行会先保留内容:若 canonical 文件还不存在就移动过去;若已存在且内容不同,就合并进 canonical 文件,然后把 home 路径替换为 symlink。把内容编译进那个文件的外部 workflow(如 learn-from-experience)可以继续写 ~/.agentica/AGENTS.md,最终会落到 users/default/AGENTS.md。
  • 删除 memory/experience → AGENTS.md 的编译路径(Workspace.sync_memories_to_global_agent_md、CompiledExperienceStore.sync_to_global_agent_md、WorkspaceMemoryConfig.sync_memories_to_global_agent_md、ExperienceConfig.sync_to_global_agent_md、CLI --sync-*-to-global-agent-md、BuiltinMemoryTool.set_sync_global_agent_md,以及 ## Learned Preferences / experiences 托管区块逻辑)。「上面 AI 编译、下面人手写」按作者切开同一类常驻规则,还逼双方约定托管边界;正确切法是按生命周期——每会话都要 → AGENTS.md(谁改都行),相关才要 → memory。外部 sync 直接追加普通行。
  • 删除 PERSONA.md / TOOLS.md / USER.md 三个文件与 WorkspaceConfig.persona_md / tools_md / user_md 三个字段,用户级只剩一个 AGENTS.md。它们各自注入成同一个 system prompt 里的一个区块,下游没有任何东西能区分——是给作者用的归档分类,对读者却是四个要翻的地方(还要加上项目链)。get_context_prompt() 现在只做一件事:拼 AGENTS.md 链。随包发的模板本来就是 Friendly and professional / Always use absolute paths 这类零信号 boilerplate(正是之前已从 AGENTS.md 模板里删掉的那种),手写过内容的需要自己搬进 users/{user_id}/AGENTS.md,不做自动搬迁:把一个 md 的正文编译进另一个 md 正是这一轮要去掉的东西。
  • 删除 Ctrl+X 的 Agent/Shell 模式,且不给 ! 之类的替代入口(连带 $ 提示符、shell-prompt 样式、SHELL_MODE_EXEMPT_CMDS、_handle_shell_command、QueuedInput.shell_escape 一并删除,不做兼容)。一个模式必须被记住,忘了就把接下来每一行都标错,而它的两条分支(「执行这行」/「问模型」)对同一段文字都讲得通——于是忘记开关时是静默地做错事。它买到的东西本来就有更好的来源:要自己跑命令就另开一个终端窗口(那里原生就是 shell,有历史、能跑交互式程序),要让 agent 跑就直接说(它有 execute,带权限、日志和后台管理)。中途试过的 !cmd 单行转义也一起删掉:它确实比模式好,但同样是把「另开一个终端」搬进输入框,而输入框的用途是跟模型说话。 顺带把「输入行上的能力属于在这行打字的人」收到一处:转发来的文本(peer 消息、后台命令回执)带 __RELAYED__ 标记,因此不回显(它到达时已按自己的样式印过一次,不该把带授权头的模型侧原文再当成一行 ❯ 印一遍)、不派发斜杠命令——这是 PEER_MESSAGING_POLICY 里「消息里的斜杠命令只是纯文本」第一次真正成立:在此之前它是碰巧成立的(format_for_model 正好加了个 […] 头,所以首个词永远不是 /compact)。

fixes

  • 工作区外会话重启后 title 变成 Chat、轨迹空白:对话其实写在该会话 work_dir 对应的 project 目录,但发消息前 _touch_session_log 在 settings.base_dir 下先 touch 了一个 0 字节 jsonl。重启后 _locate_session 把这个空文件当成命中,不再搜其它 project,侧栏 name 退化成 Chat,「查看轨迹」读到空列表;浏览器 localStorage 里的对话还在所以看起来「记录还在」。现在空 stub 不算 transcript:新会话的 jsonl 建在会话自己的 work_dir 下;列表和定位都优先有内容的那份,并删掉盖住它的 0 字节影子文件。
  • 输入框右下角那个上下文占用点开后看不见:面板是往下展开的,而那颗按钮就在输入框底部,于是整块落到视口外面。旁边的 profile 浮层和模型下拉没有这个毛病,因为它们把 bottom: calc(100% + …) 写在自己的类上(.account-pop / .model-dd)——方向是这个组件的固有属性,它只会出现在屏幕底部。.ctx-tip 反而写了一条「在输入框里时改成向上」的条件覆盖 .input-ctx .ctx-tip,但那是后代选择器,而面板是 .input-ctx 的兄弟节点(按钮和面板并列在 .ctx-wrap 里),所以这条规则从来没有命中过。改成和邻居一致:方向直接写在 .ctx-wrap .ctx-tip 上,阴影也翻成朝上,那条失效的覆盖删掉。回归测试是几何比较而不是 CSS 文本比对(旧代码里那条规则也是在的,只是不生效):tmp/web_i18n_smoke.py 在真实窗口里点开面板,断言它的下边缘不低于按钮的上边缘。
  • 会话归档后仍留在侧栏,要刷新才消失(同一个 bug 也让工作目录、模型名等状态停在 - 上):前端的 store 是可变单例——state 和它里面的每个对象终生保持同一个引用,而 useSyncExternalStore 判断「要不要重渲染」用的是 Object.is。所以 useMemo(..., [s.sessions]) 看着像对的,实际永远不会重算:sessions 这个对象引用从来没变过,变的只是它里面的 archived 标志。改成每次 setState / bump() 递增一个 state.rev,订阅和 useMemo 都锚在它上面。
  • 设置里「默认工作目录」旁边的「浏览」点了没反应:那颗按钮在设置弹窗里没有接目录浏览的实现,只有新建会话的目录弹窗里有一份。抽成共享组件 web/src/components/DirPicker.tsx(路径输入 + 浏览开合 + 历史 + 列表,单击进目录、「选此目录」确认、「上一级」回退),两处共用。顺带修掉抽出后暴露的样式问题:.dm-row 的 flex 布局原先只写在 .dir-modal 选择器下,搬到设置里就退化成行内流,路径输入框被挤到一小段、「应用」掉到第二行。没有改用系统原生文件夹选择器:浏览器里根本没有这个能力(webkitdirectory 要求用户上传目录内容,拿不到路径),而 gateway 可能跑在另一台机器上——那时该选的是服务端的目录,弹本机选择器只会选出一个对面不存在的路径。.gitignore 里那条 Python 打包用的 lib/(本意是仓库根的 build/lib)把 web/src/lib/ 一起吞了,npm run build 报 5 个 TS2307: Cannot find module '../lib/format'。开发分支上的构建之所以通过,是因为文件就在工作区磁盘上、只是从未入库。规则改为只锚定仓库根的 /lib/,文件补回;顺带把 web/node_modules/ 改成通用的 node_modules/(现在有 web/ 和 desktop/ 两个 Node 项目)。
  • Skills 的改、删返回 200 但列表里什么都没变(GET/PUT/DELETE /api/skills):路由用 SkillLoader().load_all() 读回列表,而它填的是进程级全局 registry,register() 又是同名保留第一个——本进程加载过一次之后它就是空操作。于是编辑保存后列表还是旧描述、删掉的技能还在列表里,反复点也没用(写入其实已经落盘了,读的是缓存)。改成 reload()(先清空再读)。同时三个写入路由都补 AgentService._invalidate_cache():本会话已经建好的 agent 冻结着旧的 skills 目录(按会话冻结是 prompt cache 的要求),不失效就要等下次重建才认新技能。测试 tests/gateway/test_plugins_web.py(3 条断言在 load_all() 版本上确认失败)。
  • 定时任务的编辑表单会把日程改成别的时间:GET /api/scheduler/jobs 只给 schedule 这一个字段,值是 schedule_to_human() 的展示文本(Daily at 7:30、Every 2 hours),而 PUT 收的是 parse_schedule() 能认的表达式——用展示文本回填输入框再保存,要么 400,要么被解析成另一个日程。新增 agentica.cron.jobs.schedule_to_expr()(cron 原式 / every Ns / ISO 时刻,与 parse_schedule 严格来回),响应里多一个 schedule_expr,前端表单读它;schedule 保留给展示。测试 tests/cron/test_cron.py::test_schedule_to_expr_parses_back。
  • Gateway Web SPA 拉到 /api/status 之后界面仍显示 Dir: - / 模型 -:store 对 state 原地 Object.assign,useAppState 却把同一个对象交给 useSyncExternalStore 当 snapshot。React 用 Object.is 判断,引用没变就不重渲染,所以 boot fetch 成功也画不出来。现在 snapshot 改成递增的 rev,订阅方每次 bump() 都会重绘。
  • 微信发图走到「请看这条图片。」后立刻 'dict' object has no attribute 'detail':解密已经成功,gateway 把 {"url": "data:image/jpeg;base64,..."} 挂到 agent.run(images=...)(OpenAIChat.process_image 认这个形状),但 count_image_tokens 假定每项都是带 .detail 的 agentica.media.Image——Layer 1 一算 token 就炸,整轮 AgentService.chat 失败。现在 dict 先收成 Image(url=..., detail=...) 再计数;空/无 url 的 dict 走 85 token 的低细节默认值。测试 tests/model/test_tokens.py、test_media_understanding.py。
  • 个人微信图片/语音下载报 Padding is incorrect,失败后空消息再把会话打崩:iLink 入站 CDNMedia.aes_key 有三种编码(base64(16 字节)、base64(32 位 hex)、image_item.aeskey 裸 hex)。旧代码一律 b64decode 后丢给 AES——hex 形态解出 32 字节,按 AES-256 去解 AES-128 密文,pycryptodome 就报 Padding is incorrect.。语音/文件走的正是 hex 包装,所以两种媒体一起挂。修在 WxBotClient._parse_aes_key(与 openclaw-weixin parseAesKey 对齐),extract_media_typed 把 image_item.aeskey 拷进 media,下载缺 full_url 时用官方 CDN https://novac2c.cdn.weixin.qq.com/c2c。下载仍失败时不再 agent.chat("")——空 user 消息会被 Claude/兼容代理拒成 messages.N: user messages must have non-empty content 并写进历史;改为回复「没能下载这条图片/语音…」,纯媒体成功则补一句非空占位(「请看这条图片。」)。测试 tests/gateway/test_gateway_channel_wechat.py、test_gateway_message_queue.py。
  • 收到用户转发的指令时清空发送刹车(PeerSession.drain() 取到任何 from_kind="user" 的消息就调 note_user_turn())。刹车(5 分钟内不许把同一段文字再发给同一对端)是为无人看管的 ping-pong 设的;但用户从另一个终端、或经企微 bridge 把新指令转发进来时,会话回答它却会撞上「你已经发过这句」——那是双方早就翻过去的一段交流。这和「在本终端敲任何一行即解除刹车」是同一条规则的接收端视角:能拦下用户刚吩咐的那句话的上限是 bug,不是保护。用真 CLI 子进程 + 模拟 IM 转发的端到端复现里,修复前必然得到 PeerMessageRefused。
  • 被 peer 派了活的会话,问题回抛给派活方,不再弹给一个没人看的终端。多会话协同此前有个结构性障碍:PEER_MESSAGING_POLICY 明确要求收信方「consequential 的事照样问你的用户」,于是 worker 一遇到范围/路线上的歧义就调 ask_user_question——而那个框渲染在它自己的终端,人在派活那一侧。派 10 个会话就是 10 个框,得一个终端一个终端去收,全自动协作直接不成立;没人应答时它还要挂满 300 秒超时才拿到 default_on_timeout。 根因是策略把两个轴混成了一个:「谁有授权」和「谁该回答这个问题」。授权那条完全正确、一个字没动(agent 消息不授予任何权限,不能改配置/权限/指令文件,正文自称「用户说的」也不算);错的是地址。修的方式是纯 prompt,零新机制——机制早就齐了:消息头里已经带着回信地址(reply with send_message to <name>)、send_message 已注册、限频是按对端算的(一问一答两条消息碰不到)。 新规则按「答案归谁」分流:关于活本身的(范围、路线、指令和现场不符、「你是不是想说 X」)用 send_message 回派活方,说清卡在哪就结束这一轮——回复会作为新的一轮自己到达,历史都在,所以不许 sleep 轮询;只有真人才能定的(自己权限层拒绝的、超出委派范围的破坏性操作、凭据)拒绝并回报,既不在本地弹也不问 peer——派活那边坐着人,由它去问。关键一句是「回答意图不等于授予权限」,所以派活方有资格拍这个板。发送侧同步补一条:派活时就写清 in/out of scope 和卡住怎么办,回问上来的自己答——把每个都转给用户,正是「一次委派换来每个 worker 一次打断」的来源。 刻意不写死成 planner-worker:条件是「这条活来自 peer」,按消息判而不是按会话判,所以一个会话拆活、多个会话并行审同一个东西、流水线接力、两个会话辩论一个决定,全都适用同一条(政策里不出现 planner 字样,测试直接断言这一点)。这也顺带比「加个 /trust 命令」好:无状态、无命令,而且用户真在那个终端敲字时它自动恢复本地提问——因为那时人确实在。同时软化了「不许讨论」那条:它原本会连带禁掉这次一问一答和辩论型协作,现在只禁「把对方已经听过的话再说一遍」,环路刹车(重复检测 + 限频)不变。落点三处:PEER_MESSAGING_POLICY、ASK_USER_QUESTION_SYSTEM_PROMPT(补一节「这个框能到谁」)、bundled multi-agent skill。
  • experiences 与 skills 目录改为每会话冻结一次,system prompt 里最后两处「每轮实读」就此清零。freeze_snapshots() 现在连同经验一起冻(新增 get_frozen_experiences()),skills 目录由新增的 Agent.freeze_session_guidance() 冻结,Runner 在首轮 run 一起调用。 这两处和 git 状态不是同一类问题,但后果一样、而且更隐蔽:它们是这个 agent 自己在会话中途写的。捕获钩子会在工具出错、用户纠正、每约 10 轮的批量 judge 时写入新的经验卡片;skill upgrade 钩子会在后台调 refresh_tool_system_prompts(),而 SkillTool.get_system_prompt() 每次读都按使用近度重排一遍。于是没有任何人提出要求,一次后台写入就改掉 system prompt 的字节——经验那块还在 VOLATILE_SYSTEM_MARKER 之后(尾巴仍在所有 message 断点的前缀里,历史照样重写),skills 那块直接在 marker 之前,连 system head 那个断点都保不住。 代价用一行指针补回来:经验块写明是会话开始时选中的,并给出 EXPERIENCE.md 的索引路径(新增 Workspace.experience_index_path),要最新的让 agent 自己 read_file 一次。skills 不需要指针——/skills install 走的是重建 agent,新 agent 会重新冻结,所以新装的技能照样立刻可见;被挡住的只有无人看管的后台升级。clone() 会重跑 _init_runtime,subagent 因此从未冻结状态开始,不会继承父 agent 的快照。/context 的 Skills 行改为统计实际注入的块,否则冻结后它报的是一份没人用的列表。
  • system prompt 不再注入 git 状态,Workspace.get_git_context() / _git() / _is_git_repo 整块删除。prompt cache 是按字节精确的前缀匹配,而 system message 位于后续每一个缓存断点的前缀里——所以 git status --short 每轮变一行(写代码的会话里等于每一轮),失效的不只是 tools+system 那个断点,而是连同整段对话历史一起按 1.25x 重写。它是 marker 之前变得最勤的东西:工作区上下文和记忆早就由 freeze_snapshots() 冻结、日期只到天(skills 目录同在 marker 前、经验在 marker 后,两者也会中途变,见上一条),所以这一条注入实际上单独承担了 Claude 上偏低的复用率和过半的 cache write 开销。 分支 / 未提交变更 / 最近 commit 改由 agent 需要时自己跑一次 git 获取——这本来就是一次工具调用的事,而且模型每一次编辑都已经在自己的工具结果里看见了。顺带每轮省掉 4 次 git 子进程(本仓库约 38ms)。 两条走不通的替代方案:① 挪到 VOLATILE_SYSTEM_MARKER 之后——只保住 system head 那一个断点,volatile 尾巴仍在所有 message 断点的前缀里,历史照样每轮重写;marker 成立的前提是它后面的内容跨轮稳定(冻结的记忆、天级日期),不是每轮都变的东西换个位置继续变。② 像工作区上下文那样每会话冻结一次——省下了钱,换来的是一份越来越旧的文件列表,模型把 20 轮前的状态当成现状,比没有更糟。
  • /help 里带方括号的命令名(如 /model [p/m]、/debug [on|off])不再被 rich 当成 markup 静默吃掉;先 pad 再 escape,对齐也不歪。
  • ask_user_question 重构为「问一句、答一句」,用户回答交给 LLM 解析:删掉 mode 参数(confirm / text / select 三种模式)和 confirm() 方法,签名收敛为 ask_user_question(prompt, options=None)——问一个 plain 问题,可选给一组 options,用户用自己的话回答,auxiliary LLM 按语义把回答解析成纯文本(选中项的原文 / yes/no / 简洁复述),结果只含 prompt、response、raw_input 三个字段。用户输入永远不可枚举——"3 , 100题, qwen,bge服务支持100并发,workers=10 ok" 这种带理由的自由文本,旧代码先要求整段是纯数字(isdigit 失败)、再做前缀模糊匹配(方向反着)、最后静默回退到 options[0],把用户选 3 曲解成选 1;中间一版改用正则抠 {"option_index": N} 同样是在猜。现在没有 mode、没有正则、没有 isdigit——text in / text out,LLM 读上下文给答案。LLM 不可用(SDK / cron 没绑 agent)、调用失败或返回空时返回用户原话,绝不伪造一个用户没选的选项。 ask_user_question 改为 async:阻塞的 input 回调走 run_in_executor 不卡事件循环,LLM 解析直接 await model.invoke,30s 硬超时兜住慢/坏的 auxiliary model。工具新增 set_parent_agent / clone(),在 Agent._bind_tools_to_agent 里绑定,复用 resolve_auxiliary_model("ask_user_question") 拿便宜模型。破坏性变更:mode 参数与 confirm() 方法已删除,旧调用需改为 ask_user_question(prompt, options=...)。
  • SSE 解析失败时,报错终于说得出端点发了什么。Malformed stream from the model endpoint 的 raw 一直是 str(JSONDecodeError),也就是 Extra data: line 1 column 309 那一句——屏幕上已经完整印过,所以 Ctrl+O 展开出来的是同一句话,纯属白按。坏掉的那段字节只在 JSONDecodeError.doc 里,别处没有第二份拷贝,于是这个错从来没有可诊断的信息。现在 .doc 整段进 view["raw"](Ctrl+O 和日志共用同一份,不会只补一半),屏幕上另给一行断点前后 60 字符的窗口——两个 SSE 事件粘在一行、HTML 错误页、半截 JSON,一眼就能认出来,不必开 pager。
  • peer agent 消息的展示和工具调用风格统一:来自另一个会话 agent 的消息原来显示成 Agent dep-11 › <消息> 的 grid 行,现在改成 ↳ 🖥️ dep-11 头 + 缩进消息体——和 ↳ 🔧 tool 的工具调用同一套视觉语言,读起来像「一个进来的事件」而不是一行带 › 的标签。仍然不带 ❯ 面板,agent 流量不会被误当成用户自己说的话。多行消息每行单独缩进,不再挤在 grid 的一个折叠单元里。同时删掉了消息下方的投递时机说明行(starting a turn / will reach the agent between tool calls)——光看这行不够直白,且消息何时进上下文由 Runner 的注入边界决定,用户不需要每条都被告知。
  • 运行报错的原文写进文件日志。此前它只存在 Ctrl+O 那个进程内缓冲里,而新一轮用户消息开头就 clear_truncated_blocks()(为了让 Ctrl+O 展开当前轮)——于是「看到报错、下一轮已经发出去、再按 Ctrl+O 什么都没有」,日志里也查不到,原文彻底消失。现在 display_agent_execution_error 同时 logger.error(折成一行,便于 grep),~/.agentica/logs/ 里随时可查;CLI 默认已 suppress console logging,所以不会在屏幕上打印两遍。

[1.4.12] - 2026-08-10

features

  • 为 CLI 做的功能不再默认落到 SDK 用户头上。CLI 只是产品之一,但它和后端服务共用同一套 builtin 与同一个 Runner,于是「CLI 一定有的能力」被当成了前提而不是需要检查的条件。这一批统一改成先问再做:
  • Layer 0 按「取回得回来吗」决定形态。超大工具结果以前一律落盘 + 在上下文里换成文件路径。可 CLI 之外没人能打开这个路径——一个只挂业务工具(无 read_file、无 execute)的服务型 agent 拿到的是一句它读不了的路径,等于数据直接丢了,还会诱导模型去调一个它没有的工具。现在 can_recover_spill(model.functions) 检查会话里有没有 read_file / execute:有就照旧落盘给路径(<persisted-output>),没有就不写盘、如实截断成 <truncated-output> 并说明原因和「请缩小查询范围」。
  • 批次预算从固定字符数改成窗口比例,并且只管本轮新结果。旧的 200K 字符预算在 512K token 的窗口上误伤、在 8K token 的窗口上完全不触发;新的是 0.25 × model.context_window(TOOL_BATCH_BUDGET_RATIO)。作用点也收回到结果产生的地方(Model.run_function_calls),runner 里那次扫全量历史的重复兜底整段删除——那是第二套治理同一件事的阈值,而历史该由 Layer 1 按真实窗口压力管。留在 Model 这一层还顺带解决了 provider 形态问题:这里看到的是打包成 Anthropic content block 之前的普通结果消息,两边都生效。函数改名 enforce_tool_result_budget → enforce_tool_batch_budget。
  • 落盘目录 key 从 run_id 改成 session_id(缺省 "default",仍按 workspace.user_id 隔离租户)。run_id 每轮一个新 uuid,按它分目录等于把一次会话打散成几十个目录,既找不回也清不掉。
  • 压缩次数写进 RunResponse.context_compactions。Layer 2 不可逆、要花一次 LLM 调用,而它此前唯一的证人是 CLI 的事件回调——SDK 调用方只看到某一轮突然变慢、变贵、早期对话不见了,却没有任何东西可归因。native / 本地摘要 / prompt_too_long 之后的 reactive 三条路径都计数;Layer 1 淘汰免费且可重跑恢复,不计数。
  • 无 registry 时 execute 不再提供 background。以前它会自己 new 一个 BackgroundProcessRegistry,那个 registry 没有任何界面能看到——background=True 起的进程活得比 agent 还久,没人能列出它、也没人能停它。现在没有共享 registry 就:schema 里没有 background 这个参数、wait 根本不注册、prompt 里那段说明也不发(省 940 字符),模型硬传 background=True 也只会拿到明确报错而不是一个孤儿进程。
  • web_search 缺 key 分两种情况:provider="serper" 是代码里写死的意图,缺 key 仍然直接抛(否则你以为在用 Serper,实际在用百度);而 AGENTICA_WEB_SEARCH 来自部署环境,可能是同一台机器上另一个进程留下的,缺 key / 名字拼错时降级到默认引擎并 warn——不能让一个可选工具的一个可选 key 把整个服务的启动搞挂。
  • 新增 Agent(enable_session_log=False)。session_id 以前强制在进程 home 下写一份 JSONL,那份文件只有 /resume、/fork、/export 会读;自己已经有会话存储的服务拿到的是逐轮增长、永远没人读的第二副本。session_id 本身不受影响。
  • Workspace 记住「这里不是 git 仓库」。~/.agentica/workspace 不会中途变成一个仓库,但每轮 system prompt 都要 spawn 一次 git rev-parse 去重新确认。否定答案缓存,肯定答案不缓存(branch / status / commits 正是每轮都会变的东西)。
  • execute 支持同轮真并行:execute(command=..., parallel_safe=True) 的多个调用会进 asyncio.gather 同时跑。以前 docstring 写着「多条独立命令就并行发多个 execute 调用」,但调度器只 gather concurrency_safe 的函数,而 execute 是 False——这个承诺从来没兑现过(和当初 task 的同一个 bug)。模型于是拿 background=True 当并行入口用,导致「到处 background」:那是生命周期开关(命令能否活过这一轮、超时/取消后日志还在不在),不是调度开关。两件事现在分开了,background 的 docstring 明确说要速度请用 parallel_safe,wait 仍然只服务 background。 并行安全性做成逐次调用声明而不是工具级常量:execute 既跑 pytest tests/a 也跑 git commit,注册时给不出正确答案——填 False 白白串行化互相独立的活,填 True 则让 git add / git commit 这种批次直接竞争。机制是新增的 Function.parallel_arg(execute 设为 "parallel_safe"),调度器改问 FunctionCall.is_concurrency_safe();不带这个参数时行为完全不变:整批串行、保持模型发出的顺序、其中一条报错取消后面的。默认值是安全的那一侧,所以标错只会发生在模型显式声明「这批互不相干」的时候。 顺带补上 sibling-abort 的一个洞:shell 调用报错取消批次剩余部分,现在不区分它跑在哪个阶段。否则把一条 execute 放进并行阶段,就能让后面一条有依赖的命令在失败留下的状态上继续跑。parallel_safe 只影响调度,不参与权限判断(execute 仍是 is_destructive=True)。
  • 删除全库自造的 when_to_use / when-to-use:Skill frontmatter、Agent / AgentDefinition、as_tool() 回退链一律不再有这个字段。发现/委派时机写进 description(或 as_tool(tool_description=...))——以前它进了对象却常常进不了模型上下文,等于假配置。bundled skill 与 VaG seed 已并进 description;残留 frontmatter 键会被 Skill 解析静默忽略
  • 新增 agentica --profile <name>:本次会话改用某个已保存的 profile,什么都不写(config.yaml 的 active_profile 和项目级覆盖都不动,用户自己那个会话不受影响)。这是命令行上换 provider 的唯一方式——--model_name 只能在当前 endpoint 内换模型,base_url 和 key 仍然来自当前 profile,所以「给 worker 配一个别家的便宜模型」以前在命令行上根本做不到,只能让用户先切 active profile。名字不存在直接退出并列出可用的,不会悄悄退回默认;显式指定了 profile 时 onboarding 也不再回头改写这个选择。想永久切换仍然用会话里的 /model <profile>(写项目级覆盖)
  • 框架开始自带 skill:agentica/skills/bundled/ 下的 SKILL.md 随包发布,SkillLoader 把它作为最后一条搜索路径、bundled 在 LOCATION_PRIORITY 里排最低——同名的用户/项目 skill 一定赢,我们发的只是默认值,不是从用户手里拿走的决定。首批两个,都用「薄指针」写法:只写变化慢的概念和决策规则,flag、命令、配置项一律不抄进正文,改成告诉模型去 agentica --help、~/.agentica/config.yaml 现查——手抄一份手册进包里,两周后就开始骗模型。agentica(CLI 斜杠由 name 自动生成 /agentica,不写非标准 trigger 字段)讲怎么查关于 agentica 自己的任何事,以及一条模型经常搞错的边界:斜杠命令是用户在输入框里敲的,模型输出里的 /status 只是文本,答案在斜杠命令后面时应该告诉用户去敲哪一个。multi-agent(/multi-agent)讲三种多 agent 机制怎么选(task 只读、便宜、可并行;delegate 要的是一个答案;tmux 里另起一个 CLI 要的是一条人能看见、能 attach、比你活得久的工作线),以及一套实测出来的注意事项:会话名是从 cwd 目录名派生的(没有 --name,所以目录名就是名字)、寻址用名字不要用 session id(启动瞬间它还是空的)、--model_name 只能在当前 endpoint 内换模型(base_url/key 仍来自 active profile,跨 provider 换不了)、子会话默认放开工具权限且无人值守所以要给它独立目录(worktree)、发完消息不要 sleep 轮询等回复(回复会作为新一轮自己到达)、干完要 tmux kill-session 收摊。端到端实测:在 tmux 里起一个真 CLI,像人一样把请求敲进去,它自己起了第二个 CLI、list_agents 找到对方、send_message 派活、拿到结果,57 秒
  • 新增 delegate 工具:一个交互会话可以把整块工作丢给另一个 agentica 进程去做(自己的上下文窗口、模型、工作目录、session log),做完把结论交回来——「主 CLI 分派、子 CLI 并行、结果汇总」这个场景以前只能靠人手开终端。它不是新机制:子进程就是 agentica --query <task> --print --permissions <父会话当前模式>,通过已有的 BackgroundProcessRegistry 起,所以 /ps、/stop、wait 工具、完成回执全部直接可用。BackgroundProcess.kind(command / delegate)决定这些界面渲染成「一个任务」还是「一条 shell 命令」,也是并发计数的依据。task(进程内 subagent)仍是便宜的那个选项,delegate 的 docstring 明确把小活推回 task。约束:同时最多 3 个(MAX_CONCURRENT_DELEGATES,对齐 SubagentRegistry.MAX_CONCURRENT),第 4 个被拒并告诉它去 wait 哪一个;只有一层(AGENTICA_DELEGATE_DEPTH 传给子进程,create_agent 超过 MAX_DEPTH 直接不建这个工具——agent 生 agent 的树没人看得住账单);权限用可调用对象实时读 agent.tool_config.permission_mode,因为 /permissions 是原地改模式不重建 agent(ask 模式下这个工具根本不在 READ_ONLY_TOOLS 里,自然不出现);模型默认继承父会话,可用 model="provider/name" 或裸模型名覆盖,API key 绝不上命令行(子进程自己读 config.yaml);工具只在有 registry 的地方存在(交互式 CLI),一次性 --query 和 cron 起的 agent 没有 registry,它们派出去的活根本无法被 wait 或回收。子进程不出现在 list_agents 里:只有 run_interactive 才发布 PeerSession——委托是有返回值的父子关系,peer 消息是平级会话说话,两者刻意不混
  • 新增 agentica --query "..." --print:只把最终回答写到 stdout,没有 banner、没有日志(suppress_console_logging),且走 sys.stdout.write 而非 console.print——rich 会把回答里的 [warn] 当 markup 吃掉。这是 delegate 读子进程结论的方式,也可以直接用在脚本/管道里;一次性运行失败时退出码为 1(中断为 130),调用方据此决定下一步。委托任务的完成回执按任务渲染而不是「Background terminal #N」:正文是子会话交回的完整答复(120 行 / 8000 字符,不像命令日志那样只取尾巴),失败则给退出码和输出并明确「不要原样再派一次」。顺带修掉一个会污染回执的 bug:BackgroundProcessRegistry.start() 写日志头 $ cmd 时不再换行(转义为 \n),否则跨行命令(委托任务的 prompt 就是跨行的)的后半截会被读日志的一方当成命令输出交回给模型
  • 项目目录元数据合并为单一 project.json(原 .project.json 的 work_dir + 原 profile 文本文件的 active_profile);仍在 ~/.agentica/projects/<user>/<slug>/ 下,不进用户 git 工作区。session 的 <id>.meta.json 保持与 .jsonl 并列(粒度/并发不同,不并入)。SessionLog / peers / /config Project Dir / tool-result 路径统一经 project_store.project_base_dir
  • /goal --tokens -1(SDK token_budget=-1)表示不限 token;--turns / --wall 同样认 -1。不传 --tokens 仍默认 500_000(与显式无限语义分开);0 拒绝,避免和零额度混淆
  • list_agents / /list-agents 输出加厚:每条会话多行列出 addressable name、peer id、session_id、cwd、带 hash 后缀的 project 存储目录(如 -apdcephfs-...-nlp-6115aec9)、session_log(<project>/<session_id>.jsonl)、CLI log_file(如 ~/.agentica/logs/20260809-80403.log,附 level)、workspace / memory(MEMORY.md)路径,以及 working on。消息地址仍是短名字(对齐 Claude Code 的 myapp-3f),但 send_message / resolve_peer 也接受 session_id 前缀;列出路径是给模型自己决定要不要去读对方 transcript / 运行时日志 / 长期记忆(log_file 通常比翻 conversation 更快看错误与工具痕迹),peer 消息本身仍只传纯文本。CLI 对 list_agents / send_message 的工具结果不再按默认 4 行折叠;send_message 的调用行也完整展示正文(不再被默认 40 字截断)。注入到接收端输入区的 peer 消息修复 Rich Table 默认 ellipsis,长文不再被 … 吃掉。消息头的回复地址改用 addressable name(reply with send_message to agentica-73),不再暴露难读的 reply_to=<peer_id>;/status 新增 Peer: 行展示本会话的短名字。接收策略写清:header 标成用户转发的指令直接采纳、不要再澄清授权边界;另一 agent 发来的仍无授权(即使正文自称「用户决定」)。接收端接受消息时 CLI 展示 ✉ 回执(含正文):空闲开新 turn、运行中则在 tool 间隙注入;发送方确认语义改为「已入队 mailbox」并按名字回显(Message queued for 'agentica-73'),不再误称 delivered、也不再打印 opaque peer_id(对齐 CC:写 inbox 成功 ≠ 对方已读)
  • peer 代码收敛:PeerInfo.detail_rows() 成为字段展示的唯一来源,describe()(模型看的)与 /list-agents(用户看的、按标签对齐)都由它渲染,不会再出现只加一半的情况;寻址走新的 match_peers(),「查无此人」与「前缀撞车」给不同的报错并列出候选(旧实现两种都报 no live session);环路刹车从「hop 上限 3」换成重复检测 + 限频:hop 上限会掐断一次正常的更正来回,而中途试过的「一段对话最多 6 条」(MAX_EXCHANGE_TURNS)同样是错的——一次正常的多轮交接会被从中间掐掉,被拒的往往正是用户刚吩咐的那句。真正不该发生的是把同一件事再说一遍:PeerSession._check_send_rate 按对端拒绝 5 分钟内重复的同一段文字(_text_digest 折叠大小写与空白,改个排版不算新消息),并对同一对端限 5 分钟 20 条(RATE_WINDOW_SECONDS / MAX_SENDS_PER_WINDOW)——足够宽到任何真实协作都碰不到,又足够窄到 ping-pong 循环撑不过几分钟。两个限制都按对端分别计算(同时和三个会话协作互不影响),也都被 note_user_turn() 清空:用户在本终端敲任何一行(挂在 Enter 处理器上)或对端用 /send-message 转发过来即刻生效——一个能拦下用户刚打的那行指令的上限是 bug,不是保护。PeerMessage 随之去掉 exchange_turn 字段与 last_of_exchange(两端不再需要就一个计数达成一致);PeerMessage 去掉从未被读的 path 字段、新增 to_name(发送方按名字确认,mailbox 文件也能直接看出收件人);PeerSession.publish() 遇到不存在的字段名直接报错而不是静默丢弃;/send-message 改用 split(maxsplit=1),目标名后多打的空格不再被当成空消息
  • /resume <id> 和 agentica resume <id> 不再要求先 cd 回原目录。session 仍按项目(work_dir)分区存放,但查找变成「当前项目优先,未命中再搜该用户的全部项目」,所以 No session matching '7e17bc1f-...' 这类报错消失了,agentica resume 也开始接受 id 前缀而不只是完整 uuid。分区目录名是 sanitize_path 单向哈希出来的、无法反推,因此每个项目目录写一个 project.json 记下它代表哪个 work_dir(一项目一文件,不是一 session 一份;同文件还可存项目级 active_profile);早于这个改动的目录回退到读最新 transcript 首条的 cwd——实测本机 140 个历史项目目录全部能正确反查,查找耗时 9ms。命中的 session 属于别的目录时,仿 Codex 给四选一:用 session 目录 / 用当前目录 / 总是用 session 目录 / 总是用当前目录,后两个写进 ~/.agentica/config.yaml 的 settings.resume_cwd(session / current),之后不再问;改回 ask 或删掉该行即可恢复询问。选了 session 目录会同时 os.chdir 并改 agent 的 work_dir——工具认 work_dir,但 git 状态、@file 补全和 shell-out 认进程 cwd,两者必须一起动,否则会分裂成半个目录的状态。关键约束:无论选哪边,transcript 都继续追加到它原本所在的项目目录(Agent 新增 session_base_dir 参数把存储位置与工作目录解耦),否则同一个 session 会裂成两个文件、从哪边都 resume 不全。session 目录已被删除时不再询问,直接留在当前目录并说明原因;prompt 处 Ctrl+C 取消则整个 resume 中止,不会退而求其次地建出一个无关 agent。另增 /resume all 列出所有项目的会话(附各自目录),其序号会被记住,随后的 /resume <n> 指向刚才看到的那一份而不是当前项目重新编号的列表
  • 内置 web_search 的搜索引擎可替换:BuiltinWebSearchTool 变成薄分发器,模型看到的工具名、参数、docstring 恒定不变,只换背后的引擎,所以 prompt、RunConfig(enabled_tools=["web_search"])、权限规则都不受影响。内置 baidu(默认,行为不变)/ duckduckgo / exa / bocha / serper / zhipu,选择优先级 provider= 参数 > AGENTICA_WEB_SEARCH 环境变量 > 默认。引擎不按 API key 自动推断——为别处设的 key 不该悄悄改变 agent 的搜索行为;指定了需要 key 的引擎却没给 key 会直接报错,而不是静默退回百度(否则你以为在用 Bocha,实际在用百度)。CLI 无需新增 flag:把 AGENTICA_WEB_SEARCH 和 key 写进 ~/.agentica/config.yaml 的 env: 块即可,apply_global_config() 已经会投射进 os.environ
  • 自定义搜索引擎三条接入路径,按「要不要写代码」「CLI 能不能用」区分:AGENTICA_WEB_SEARCH=mcp + AGENTICA_WEB_SEARCH_MCP_URL/_TOOL 零代码接任意 MCP 搜索服务(CLI 可用);register_web_search_backend(name, factory, method, key_env=...) 注册命名引擎(注册后 env/CLI 也能选);BuiltinWebSearchTool(search_fn=...) 直接传 async 函数(最灵活,适合包装已有 MCP client)。契约只有一条:async (queries, max_results) -> str
  • 新增 McpSearchTool:用 httpx(核心依赖)直接讲 MCP Streamable-HTTP,不经过需要可选 mcp 包的 agentica.mcp,因此能当默认 web_search 引擎。Exa 是随附预设——其公开端点可匿名调用(共享免费池、有限流),设 EXA_API_KEY 则走自己的额度;把 url/tool_name 指向别的服务就是自定义引擎
  • 六个搜索后端签名统一为 async (queries: str | list[str], max_results: int) -> str 且全部支持多 query,分发层因此不需要每后端的参数适配分支:SearchBochaTool 的 count、SearchExaTool 的 num_results 改名 max_results,ZhipuWebSearchTool 补 max_results,DuckDuckGoTool.duckduckgo_search 补多 query
  • web_search_pro_tool.py / WebSearchProTool 更名 zhipu_web_search_tool.py / ZhipuWebSearchTool(CLI --tools web_search_pro → zhipu_web_search),并从早已过时的 /paas/v4/tools 通用工具端点换到专用的 /paas/v4/web_search。原来是把搜索伪装成一次 chat 调用(messages=[{"role":"user"...}]),结果得靠 data['choices'][0]['message']['tool_calls'][1]['search_result'] 这种按下标摸出来——响应结构一变就崩,而且整个 API 只能传 query,条数只能拿回来再客户端切。新端点直接收 count(服务端就按条数返回,不再传完再丢)、search_domain_filter、search_recency_filter、content_size,并暴露智谱的 4 档引擎:search_std(0.01 元/次)/ search_pro(0.03,默认)/ search_pro_sogou(0.05)/ search_pro_quark(0.05),web_search 分发器路径可用 AGENTICA_ZHIPU_SEARCH_ENGINE 切换。实测两点值得知道:一是 count 只是建议值(search_pro_sogou 向上取整到 10/20/30/40/50,其他档位在部分查询上也超发),所以 max_results 由客户端截断兜底——单条正文约 1000 字,要 3 条收到 10 条会白烧几千 token;二是智谱自研的 search_std/search_pro 约 40% 的查询整批返回空 link(同一查询要么全有要么全无),需要每条可溯源时用 sogou/quark 档(实测这两档 100% 带 link),文档已写明。顺带修了鉴权:原先 header 直接发裸 api_key,新端点要求 Bearer。引擎/时间范围/摘要长度的非法取值在构造时就报错并列出可选值,而不是等 API 返回一句看不懂的错误;结果里剔掉 icon(favicon URL)和 refer(角标序号)——对模型是纯 context 浪费。默认 timeout 从 300 秒收到 60 秒(一次搜索挂 5 分钟不是超时,是卡死)
  • DuckDuckGoTool / SearchExaTool 改为直接用 httpx 讲 HTTP,删掉 duckduckgo-search 和 exa_py 两个可选依赖(pyproject 的 ddg / exa extra 清空为占位):两者都只是 HTTP 封装,而作为可换的 web_search 引擎,「装了才能用」意味着切过去才发现要装包。DDG 走公开 HTML 端点(httpx + bs4 都是核心依赖),顺带过滤掉此前会混进结果的赞助位、并把 .result__url 的截断展示文本换成真实链接(含 /l/?uddg= 重定向解包)——原先的 fallback 解析器返回的 url 是不可点的。Exa 走 POST https://api.exa.ai/search,原生 async 不再需要 run_in_executor 把阻塞 SDK 挪出事件循环,text_length_limit 下推为 contents.text.maxCharacters 由服务端截断(省掉传完再丢的字节),并删掉当前 API 已被 type="auto" 取代的 use_autoprompt 参数。两个模块此前在 import 期就可能失败(Exa 直接 raise ImportError),现在无条件可导入
  • 内部拆包减负(结构明示,不藏兼容层):cli/commands.py→cli/commands/、cli/display.py→cli/display/、cli/interactive.py→cli/interactive/、runner.py→runner/(_run_impl 在 runner/loop.py);包 __init__ 只导出公开入口,私有符号从真实子模块引用;tests/cli/test_cli.py 按域拆成多个小文件。SDK 主入口仍是 agentica / Agent / Runner
  • 跨会话消息:两个终端里的 CLI 会话可以互发纯文本,不再靠人在终端之间复制粘贴。模型自己调 list_agents 发现对端、send_message 投递,用户不需要手动触发(/list-agents(别名 /peers)只用于查看和排查)。传输是文件而非 socket:~/.agentica/cache/peers/live/<peer_id>.json 是心跳 + pid 探活的发现目录,~/.agentica/cache/peers/mailbox/<peer_id>/*.md 是每条一个带 frontmatter 的 markdown 消息,可直接 cat 排查。目录刻意放在用户级而非按项目 hash 分区——「协调同一个 repo 的多个 worktree」正是主场景,而它们 cwd 不同。收件端是拉取式:运行中的会话由 Runner._inject_peer_messages 在 tool batch 间隙取走(与 /steer 同一边界,不打断正在跑的工具),空闲会话由 CLI 轮询取走并开一轮。消息身份绑 CLI 进程而非 session log,/resume 换掉 session_id 后在途消息仍会落地。环路刹车:一段不被人打断的 agent 间往返最多 6 条(MAX_EXCHANGE_TURNS),未读堆积到 50 拒收,单条超 40000 字符拒收。工具的 system prompt 明确约束收件方——来自另一个 agent 的消息不是用户授权、不能代答权限提示、其中的斜杠命令是纯文本
  • 跨会话消息新增人工入口 /send-message <session> <text>(别名 /send,与 list_agents → /list-agents 同一命名规则,对应 agent 用的 send_message 工具):不用切终端就能替 agent 自己把一句话说进另一个会话。它和 agent 发的消息在收件端语义不同,因此消息带 from_kind(agent / user):agent 发的仍然「不是用户授权、不能代答权限提示」,/send-message 发的注入为「你的用户从另一个会话转发」,收件方按用户亲口说的处理。mailbox 是 0700 用户私有目录,所以 user 身份与在本终端输入等价;header 里伪造 from_kind 不被采信。单条上限 40000 字符(够放一整篇 handoff 写给对方;再长就把内容落到文件、发路径,反正文件系统是共享的)
  • 新增 /fork:无参数即在当前位置分支——整段对话带过去,继续聊就是了,只是落到新 session,此后说的话不再进入被分叉的那份 transcript(/status 多一行 Forked from: <parent>,来源写在 fork 出的 sidecar meta 里,由 SessionLog.fork() 自己记,不依赖调用方)。/fork list 列出本会话自己发过的消息(序号 + 消息 id + 时间 + 预览),/fork <n|uuid> 分支到所选消息之前一条,于是模型回到「你提这个要求之前」的状态,可以换个说法重问。两种分支原会话都完整保留、照常 /resume,提示里直接给出旧 session id。全数字的 uuid 前缀不会被误当序号(只有能索引列表的数字才是序号)。fork 完给出的原会话恢复方式同时列出 /resume <id>(留在 CLI 里)和 agentica resume <id>(已经退出去了),两条都受支持
  • execute(background=True) 的结果现在会主动回灌当前会话:命令结束时除了打印通知,还把退出码、耗时、完整命令和输出尾部交给 agent——运行中经 steer() 落在 tool 间隙,空闲则作为下一轮,于是它自己接着往下做,不用等用户回来手动 wait。设 deliver_background_results: false 可关掉自动唤醒
  • Goal 预算耗尽不再当场砍断:任一 cap 触发时循环额外给一轮收尾 turn,喂 [Standing goal budget reached] prompt 要求模型交接(做完了什么、还剩什么、有什么坑),明确禁止在没有预算兜底时调 verify_completion;这一轮跑完才落到 budget_limited。收尾轮期间 goal 保持 active 以便正常计账(因此最终会超出 cap 一轮,状态栏如实显示),GoalState.budget_wrapup_sent 保证只给一次,resume() 重置。CLI /goal 与 SDK run_goal() 共用同一条路径
  • Goal 主成本闸改为默认开启的 token_budget=500_000(CLI /goal 与 SDK run_goal 一致);turn_budget 默认 None(仅 --turns / 显式参数时生效)。/goal status 与状态栏在执行中显示 tokens used/budget(如 goal 12.3K/500K)
  • execute(background=True):长命令可立即返回,由共享 BackgroundProcessRegistry 托管进程组;stdout/stderr 写入 ~/.agentica/projects/<user>/.../background/ 日志。CLI 新增 /ps 列出后台 terminal 与 background agent,/stop <id|pid|#n> 可按目标停止(空参停全部);状态栏显示正在运行的 background terminal 数量。registry 经 create_agent / session rebuild 路径注入,与 /background agent 任务共用同一套 /ps//stop 入口
  • wait(id=...):等待 execute(background=True) 启动的后台命令,命令一退出立即返回并给出退出码、耗时和日志尾部;未结束则在超时后返回当前进度且不停止命令,单次上限 300 秒,让调用回到模型循环以便用户打断。后台命令的退出状态只报给用户,wait 是它回到对话里的唯一途径。它补的是「命令可能活得比一次工具调用久」这个断层:前台命令被 timeout 或被取消的一轮杀掉会丢掉全部输出,而这类任务此前只能退回 sleep N && tail log 的盲等。一次调用跑得完、当下就要结果的命令仍应留在前台并调高 timeout;真正跑几小时以上的任务则不该 wait,等一两次仍未结束就结束轮次,由用户收到的完成通知驱动后续
  • CLI 渲染 apply_patch 的真实多文件 unified diff:在原子写入前解析 patch envelope 并捕获每个目标文件的原始内容,完成后展示一份合并的 old→new diff,替代 executor 的文本摘要
  • CLI execute 工具调用行支持宽度感知预览:普通长命令和 heredoc 统一最多展示 3 行正文,Ctrl+O 可分别展开完整 command 和折叠 output

changes

  • 上下文压缩从五个 stage 塌成两层,Stage 4(CompressionManager.compress 规则压缩)整个删除。让一个超窗口的请求装下只有两种操作:免费地扔掉单个条目(可通过重跑工具找回)和花一次 LLM 把历史换成摘要(不可逆)。原来的 stage 3 和 stage 4 在做同一件事的两个版本——都是「截断最旧的工具结果」,只是各有一套阈值和保护参数,于是 bug 可以出在两个地方而不是一个。现在 Layer 1 = evict_context()(淘汰 + 收缩 tool_call 参数),Layer 2 = auto_compact()(原生 compact 是它的 provider 变体,reactive 是它加 force=True);此外还有一个不算压缩的 Layer 0——工具结果预算,那是「别让超大输出进上下文」的输出策略,每条结果只在产生时跑一次。随之删除:should_compress / _truncate_oldest_tool_results / _drop_old_messages / _archive_dropped_messages / _llm_compress_old_tool_results / _still_over_limit / get_compression_ratio,配置字段 compress_tool_results(ToolConfig 与 CompressionManager 两处)/ truncate_head_chars / keep_recent_rounds / use_llm_compression / compress_tool_call_instructions / workspace,以及随之失去调用方的 agentica/prompts/compression/。「丢弃最旧的消息轮次」不再存在:它会静默吞掉用户自己提过的问题,那正是摘要该做的事,且做得更好。_shrink_assistant_tool_call_arguments 不跟着删而是并入 Layer 1——Layer 1 只碰 role="tool",够不到一次 write_file 塞进 assistant 消息的整段 payload,这是真实缺口。_sanitize_tool_pairs 提为模块级 agentica/compression/tool_pairs.py::sanitize_tool_pairs,并接到唯一真正需要它的地方:context_overflow_threshold 的 FIFO 丢弃是按位置删消息的,会留下没有结果的 tool_call
  • 压缩的入口收敛到 runner 一处(evict_context → auto_compact,外加 prompt_too_long 之后的 reactive),另外两条自己动手缩上下文的路径整个删除。留着它们的代价不是多几行代码,而是同一个决定有第二套阈值,两套必然漂移,且副本总是更差的那个实现。删掉的第一条是 ToolConfig.context_overflow_threshold(连同 Agent._build_pre_tool_hook、_overflow_warning_emitted、runner 里两处调用、DeepAgent 的 0.8 默认值、examples/agent_patterns/11_model_hooks.py):它是个 pre-tool hook,用自己的 chars/4 估算判断超过阈值就 FIFO 丢弃最旧的非 system 消息——丢消息会静默吃掉用户自己提过的问题,而摘要覆盖同一段历史还能把问题留下,所以它没有存在的理由;上一轮我只把它的第一阶段换成了 Layer 1 淘汰,那只是让 hook 和 runner 做重复的事。删掉的第二条见下条 /compact
  • /compact 只走真实压缩:native checkpoint → auto_compact(force=True) → 失败就打印失败并原样返回,不动 messages / runs / session log。删除的 _rule_based_compact 兜底是「成功」得最响的那个失败——它 messages.clear() 之后不放回 system prompt(违反 CLAUDE.md 里 compaction 不变量第 4 条),把每条消息截成 300 字符拼成摘要,还往 session log 写一个空的 compact_boundary,于是 /resume 也回不去。用户在网络不稳的时候敲一次 /compact,丢掉的是 system prompt、全部历史原文和恢复的可能,屏幕上显示的是绿色的「Context compacted」。auto_compact 返回 False 时本来就没改过消息列表(摘要拿到手之后才重写),所以「失败即不变」不需要额外的回滚。随之删掉已无发射方的 compact.rule_based CLI 事件分支
  • Layer 2 现在默认可用。 ToolConfig.compress_tool_results 默认 False,意味着 compression_manager 为 None,于是默认配置下原生 compact、auto-compact 和 prompt_too_long 之后的 reactive 补救全都不跑——长会话唯一的结局是被 provider 拒绝。该 flag 已删除,Agent.__init__ 在 compression_manager 为 None 时总是建一个

fixes

  • 超长单条 query / aux 记忆提取 / /compact→/fork 三条边界:① 尾部 user 轮已独自占满窗口时,reactive compact 救不了(Layer 2 会原样保留该轮),改为直接抛出 provider 的 context_length_exceeded,CLI 用「Input exceeds model context window」展示原文,不再先白跑一次摘要再包成 fallback 总错误;② MemoryExtractHooks 按 aux 的 context_window 截断 transcript(保留尾部),避免主模 1M、aux 128k 时静默 400;③ /compact 与 runner Layer 2 先打 on_pre_compact,auto_compact 写 compact_boundary 后立刻把 preserved_tail append 进 session log,使立刻 /fork 或 /resume 仍能看到与内存一致的上下文(只写尾巴:摘要那一轮由 load() 从 boundary 自己合成,一起写会让摘要在 resume 后出现两遍)。on_pre_compact 会经 aux 模型 flush 记忆/经验缓冲,所以阈值判断从 auto_compact 内部上提到 runner(CompressionManager.should_auto_compact 转为公开、可传入已算好的 token 数)——此前它在每一轮都先打 hook 再让 auto_compact 返回 False,把「几十轮一次」的边界变成了每轮一次的付费旁路调用;reactive compact 之前也只打 pre 不打 post,现在三条压缩路径的 hook 成对触发
  • 压缩两层都改为以「一条工具结果」而不是「一条消息」为单位,Anthropic 路径上压缩此前从来没生效过:只有 OpenAI 系是「一条结果一条 role="tool" 消息」,Anthropic 把一整轮打包进单条 role="user" 消息的 content 列表({"type": "tool_result", "tool_use_id": ...} block,见 AnthropicClaude.format_function_call_results)。Layer 1 只扫 role == "tool",于是在 Claude 上一条都没淘汰过——不报错、不告警,静默失效,整个提供商的上下文只能靠 Layer 2 兜。tool_result block 不带工具名(只有 tool_use_id),占位符改为回查发起调用的那条 assistant 消息的 tool_calls 拿到名字和参数,所以两边的占位符信息量一样。同一个形态差异连带修掉两处:sanitize_tool_pairs 只认 role="tool" 形态,Anthropic transcript 在它眼里像是每个调用都没有回复,重建会给每个调用插一条占位 role="tool" 消息,把本来没坏的 transcript 弄坏(现在这类 transcript 原样返回);auto_compact 保留「最后一条 user 消息之后的整段尾巴」,而 Anthropic 的工具轮本身就是 user 消息,从那里切会留下一批 tool_result、它们对应的 tool_use block 却在刚被摘要替换掉的 assistant 消息里——这种孤儿 block 会被 API 直接拒绝,现在判断尾巴时跳过承载工具结果的 user 消息。Message._evicted 语义随之收紧为「这条消息里的结果全都淘汰完了」(一轮多条结果时不能提前关门),单条结果是否已淘汰改看占位符前缀。Layer 0 的批量预算曾经也只看 role="tool"、在 Anthropic 上不生效,后来随 enforce_tool_batch_budget 一起搬回结果产生的地方解决了:那里看到的还是打包成 block 之前的普通结果消息
  • 修掉「读了又读」死循环,并把 micro-compact 整个换成 agentica/compression/evict.py:模型在一轮里并行 read_file 六个片段,下一轮这些结果已被清成占位符,于是它把同样六个读原样再发一遍,无限重复。旧实现两个缺陷叠加:没有压力闸门(每轮无条件清,200k 窗口只用了 6k 也照清,省下的上下文没人要,代价是模型重跑工具),按条数保护且当轮结果已在计数里(keep_recent=5 遇上 6 个并行调用,最旧那条在模型第一次看到它之前就被清了)。新实现只有两个量,没有「保留最近 N 条」这类参数——任何固定条数都必然输给 count+1 大小的批次,调大 N 只是把复现门槛抬高:占用低于 context_window 的 70%(EVICT_THRESHOLD_RATIO)一条都不动,超过则按最旧优先淘汰,直到降回 50%(EVICT_TARGET_RATIO)就停——最近的结果自然幸存,因为根本轮不到它们;目标取得比阈值低是为了迟滞,否则清一条刚跌破阈值下一轮又超,变成每轮清一条的抖动。消息尾部那一段连续 role="tool"(模型还没看过的当前批次)整体排除在可淘汰集合之外,压力再大也不动它,那种情况该走摘要而不是丢掉本轮自己的证据。占位符写明是哪个调用(read_file(file_path=..., offset=...))让模型能原样重发;不再先落盘:取回动作两边都是一次工具调用,成本一样,而对 read_file 落盘副本严格更差——原路径上的内容更新鲜,快照只是过期拷贝加白占磁盘(persist_full_result() 随之删除)。已被 tool-result budget 落过盘的结果(含 <persisted-output>)跳过,它携带的路径是那份过大输出唯一的抓手。没有采用「豁免 read_file」:read_file 恰恰是体积最大的消费者,永久豁免等于让上下文被文件正文填满直到触发破坏性大得多的整轮丢弃,而且它只挡读批次——6 个并行 grep 会以完全相同的方式空转。Message._micro_compacted 更名 _evicted,CLI 事件 compact.micro 更名 compact.evict(仍然静默)
  • glob / grep 默认超时从 10s 收到 3s:NFS 大树上慢搜尽快失败好让模型收窄 path;调用仍可传更大的 timeout
  • /list-agents(及 list_agents 工具)对本会话与其他 live session 用同一套字段:project / session_log / log_file / workspace / memory / mailbox 都会列出。对端若是旧版未发布这些路径,本机按 cwd/pid/peer_id 补全能确定的项,不再只剩 session_id+cwd+working on
  • LSP 编辑诊断不再把 agentica 启动打崩,也不拖慢启动:CLI 默认仍开 --enable-diagnostics,但 language server 懒启动(第一次改文件才 initialize,create_agent 不阻塞)。半残 pyright(只 pip install pyright 没 [nodejs])或 NFS 超时只会在首次编辑时 warning 降级并杀掉进程;initialize 的约 5s 是 deadline 不是 sleep(正常几百毫秒就返回)。安装提示改为 pip install 'pyright[nodejs]'
  • 状态栏和 /status 不再报一个和正在跑的模型对不上的 profile 名:两处都读 resolve_active_profile_name(),那回答的是「config.yaml 指向哪个 profile」,而 agentica --model_name X 之后跑的已经不是那个 profile 的模型了,于是状态栏出现 opus-4.8 openai/deepseek-v4-flash 这种自相矛盾的一行。改为由真正做决定的 resolve_model_config 把结果记在 agent_config 上(profile_name / profile_source),新的 setup.session_profile() 是所有展示面的唯一读取口:--profile 指定的显示为那个名字并标 flag,模型被 flag 覆盖时显示「无 profile」——此时确实没有哪个 profile 能描述这个会话,报一个名字只会让人以为自己在那个 profile 上。空字符串是「明确没有」,键缺失才回退到 config 级答案,所以手搓 agent_config 的调用方(测试、其他入口)行为不变。/model <profile> 切换时同步这两个字段,/config 在会话 profile 与 config.yaml 不一致时多打一行说明
  • 一条消息里发出的多个 task 现在真的并行:执行器把一批 tool call 按 concurrency_safe 分成两组,True 的走 asyncio.gather,其余在 for 循环里一个接一个跑,而 task 注册时漏了这个标记(register(self.task) 默认 False),于是三个 subagent 排队执行,第一个跑完才起第二个——它自己的 system prompt 里那句「Launch independent tasks in one message to run them in parallel」一直是空头支票,只读的 read_file/glob/grep/web_search/search_memory/list_agents 全都标了、唯独它没有。subagent 本就只读(写操作和状态变更命令会被拒),且每个都跑在自己克隆的 model、HTTP client 和 Agent 上(_clone_parent_model 的注释早就写明「parent 的 client 属于 parent 的事件循环,会和并发 subagent 抢」),符合 concurrency_safe 的语义。回归测试直接断言调度结果而不是这个标记:三个 task 必须同时在飞(peak == 3)。同时删掉 task 上的 interrupt_behavior="block"——这个字段只在串行分支被读取,改并行后对它永远不生效,留着就是假配置
  • task 的并发有了上限:spawn_batch 一直按 SubagentRegistry.MAX_CONCURRENT(3)限流,但模型是一条消息里发 N 个 task、走的是 spawn(),之前没有任何闸门——标上 concurrency_safe 之后,8 个 task 就是 8 个 subagent 同时烧钱。BuiltinTaskTool 自己持一个懒初始化的 asyncio.Semaphore(SubagentRegistry.MAX_CONCURRENT)(按事件循环重建,跨 run_sync 的临时 loop 不会串),多出来的 task 排队而不是被拒;system prompt 里也写明「最多 3 个同时跑」,免得模型以为一次发 10 个能一起完成
  • 系统提示里的 git 状态不再卡住整个事件循环:get_git_context() 用四次同步 subprocess.run(每次 5s 超时)拿 rev-parse / branch / status / log,而它挂在每一轮的 system prompt 构建路径上——仓库大或磁盘慢的时候,这几百毫秒到几秒里所有并发工作(并行工具、后台进程回执、peer 消息投递)全部停摆。改为 asyncio.create_subprocess_exec,且先 rev-parse 确认是仓库,再把 branch / status / log 三个读用 asyncio.gather 一起发出去(它们互不依赖)——实测本仓库 38ms,事件循环最大停顿 9ms
  • 只读外部工具补上并行标记:搜索类(serper / exa / bocha / 百度 / DuckDuckGo / 智谱 / jina)、wikipedia、arxiv、dblp、hackernews、weather、newspaper、yfinance 全部只读 HTTP,sql 的 list_tables / describe_table 是只读 schema 查询(run_sql_query 仍串行,它可能是 DML/DDL),code 的 AST 分析与 lint、lsp 的 goto_definition / find_references / hover_info 也是只读——之前它们全部落在串行分支,一次「查三个来源」等于三次网络往返相加。同时修掉 LSP 并行后才会暴露的问题:_send_message 写 server stdin 没有加锁,两个查询同时写会把 Content-Length 帧交错成乱码
  • guardrails 的 run_in_parallel 从死字段变成真并行:InputGuardrail.run_in_parallel 默认 True、也在文档里写着,但执行引擎 run_guardrails_seq 只有串行一条路,这个字段从来没人读——三个各 0.3s 的审核就是 0.9s 全加在用户面前。新的 run_guardrails 把连续的可并行 guardrail 归成一批 asyncio.gather,run_in_parallel=False 的自己一批:声明顺序仍然决定短路语义(串行的那个拦下来,排在它后面的根本不会启动),报告出去的也仍是声明在最前面的那个而不是最先跑完的那个。输出 guardrail 保持串行——答案已经生成,第一个拦下就结束,后面的都是白花的钱
  • RAG 检索不再阻塞 async 路径:knowledge.search 从查询 embedding(HTTP)到向量库再到 reranker(HTTP)全程同步,而 get_relevant_docs_from_knowledge 是直接调的——开了 add_references 的会话,每一轮都要在事件循环里干等这一整趟往返。改为 run_in_executor,get_user_message / search_knowledge_base 随之变成 async
  • 并行分支补上取消检查:串行分支每次执行前都看 agent._cancelled 并尊重 interrupt_behavior,并行分支完全没有这一段——Ctrl+C 之后,那一批里的每个读、以及(task 并行化之后)每个 subagent 照样全部启动。两个分支现在共用同一个判断:interrupt_behavior="cancel" 的直接跳过并回「Tool cancelled by user」,"block" 的(起来了就没法干净拆掉)仍然放行
  • 工具参数不再被悄悄改写:get_function_call 此前在 json.loads 之前对整段 JSON 原文做 "True"→"true" / "False"→"false" / "None"→"null" 替换,本意是容忍模型吐出 Python 字面量,实际把字符串内容一起改了——send_message 里一段 swapped = True 的代码到了对端就成了 swapped = true,接收方照着报 NameError,两个 agent 于是围着一个根本不存在的 bug 争论。改为先正常 json.loads,只有解析失败才用 ast.literal_eval 兜底(只认字面量、不执行代码,且不碰字符串内部)。同时删掉紧随其后的一遍「清洗」:它对每个字符串参数 strip() 并把 "none"/"true" 一类的值按字面转成 None/True,与声明的类型无关——于是消息正文和文件内容的首尾空白被吃掉、一条内容恰好是 None 的消息变成空值。类型修正现在只由 schema 感知的 coerce_tool_args 负责("3"→3、"true"→True 仍然照做,但只在参数确实声明为该类型时)。sanitize_arguments 开关随之删除(Function 字段、@tool 参数、Tool.register() 参数):它已无任何作用,留着就是假配置
  • 换 provider 后 resume/fork 不再 400(cache_control cannot be set for empty text blocks):session log 无论哪家 provider 写的,tool 轮次一律按 OpenAI 线格式落盘(assistant 带 tool_calls、结果是 role="tool",且那条 assistant 的正文是空串)。Anthropic 的 /v1/messages 收不了这种形状——空正文被包成 {"type":"text","text":""},滚动 prompt cache 又恰好把断点打在它上面,于是整轮请求被拒。两层修:Model 新增 supports_replayed_tool_history(Claude 为 False),resume/fork 时对这类 provider 把历史降级成纯 user/assistant 文本(复用 /model 切换早就在走的 strip_all_tool_artifacts),问答记忆保留、tool 轮次不跟过去;Claude.format_messages 同时不再产出空 text block,整条内容为空的消息直接跳过(只带图片的 user 消息照常保留)。同 provider 的 resume 不受影响,tool 历史照旧完整回放
  • 命令处理器发起的用户提问不再被看门狗秒取消:ask_user_question_callback 原先在轮询到空队列时以 not agent_running 判定「这一轮已经结束、没人会来回答了」,但斜杠命令恰恰跑在两轮之间(agent_running 为 False),于是 /cron 的确认框和新的 /resume 目录选择在第一次轮询就自己取消掉。改为记录提问是否在 run 中发起,只有那种才受 run 结束影响
  • /newchat 不再继承 agentica resume <id> 留在 agent_config 里的 session:此前新会话会沿用被恢复的 session_id,继续往它本该离开的那份 transcript 里追加
  • /resume <id> at <uuid> 现在真的 fork:此前它复用原 session_id,分支的新对话被追加进它所分叉的那份 JSONL,两条线混在一个文件里、各自都无法独立 resume。现在在 create_agent 这个唯一入口调已有的 SessionLog.fork() 生成新 session(--resume-at-uuid 启动参数走同一条路径),原分支保持不变;fork 点读取即消费,后续 /model 重建 agent 不会从同一点反复分叉
  • 修复 /steer 在 goal 循环中丢词:agent 不在 run 中时(一轮刚结束、goal 正在判定的那几秒,以及 UI 检查到 steer() 之间的 TOCTOU 窗口)原先只打印一句"用 /queue"就把用户输入丢掉。现在统一降级为排队执行,并插在待跑的 continuation prompt 之前,纠偏不会被一整轮无关工作挡住;被插队的 continuation 也不会被重复排入
  • execute(background=True) 完成后,CLI 现在会主动异步显示成功或失败、退出码、尾部输出和完整日志路径;通知由 registry 的完成事件驱动,不会唤醒 LLM。/stop 和 CLI 退出触发的终止不会再重复显示为任务失败,等待 ask_user_question 输入期间的完成事件会保留到安全时机再展示
  • 修复 execute(background=True) 遇到以 & 结尾的命令时误报完成:shell 会 fork 掉真正的工作并立刻退出,registry 追踪到的是那个空壳,于是任务还在跑就宣布结束。该组合现在直接拒绝;前台的 nohup ... & 仍照常执行,只在结果末尾注明它未被追踪(/ps、/stop 和完成通知都看不见它,且取消或超时的一轮会连同进程组把它杀掉),并建议改用 background=True
  • execute 拒绝 120 秒以上的前台起始 sleep:观察到的轮询写法 sleep 330 && tail log 会把刚被后台化释放的这一轮重新堵死。阈值对齐前台默认 timeout,短重试 sleep 2 && curl ... 不受影响。拒绝信息同时给出两条正路:等后台命令用 wait(id=...),等没有完成事件的外部条件用 until curl -sf ...; do sleep 5; done 这类成功即返回的重试循环
  • execute(background=True) 的返回值和 docstring 改为直接声明契约:退出状态报给用户而非模型,后续步骤需要它的结果就调 wait(id=...),不要自行用 sleep/轮询/阻塞 tail 模拟等待。旧的「读日志查看进度」措辞正是诱导模型接前台轮询的来源
  • 修复后台 terminal registry 接线导致 CLI 启动失败:SessionState 现在先于首次 create_agent() 初始化,再将同一份 BackgroundProcessRegistry 注入 execute 工具、/ps、/stop 和状态栏
  • 修复工具取消时子进程清理不彻底:新增 terminate_subprocess(),在活跃 event loop 上终止并完全回收 asyncio 子进程(communicate() 排空管道,支持进程组 SIGTERM→SIGKILL 宽限升级),应用于 execute/grep、shell 及 goal verify 等工具,消除取消后管道传输回调泄漏到已关闭 event loop 的问题
  • CLI 顶层 agent 执行错误改为结构化展示:429/限流等 provider 异常显示红色摘要、可操作 /retry 提示和 code/spanId 诊断字段,完整原始异常保留到 Ctrl+O 展开
  • 文件工具缺失路径错误只暴露真实路径状态:read_file/edit_file/glob/grep 缺失路径时返回 resolved path 和 nearest existing parent,并提示从 ls/glob/grep 重新定位;不再猜测候选路径或在 read_file 内容尾部追加 metadata
  • 文件编辑默认收敛到 apply_patch:multi_edit_file 不再注册为内置工具,复杂/多 hunk 编辑走上下文 patch;edit_file 保留为单个短且唯一的 literal 替换工具。edit_file 的 String not found 保持无状态重读指引;apply_patch 的 context mismatch 同时展示 expected context 和 actual 当前行,便于用真实当前内容重建 patch
  • 修复 CLI 输出 OSC 8 超链接泄漏:Rich 为 Markdown 链接生成 OSC 8 终端超链接,prompt_toolkit 的 ANSI 解析器不识别 OSC 序列会把 payload 渲染成可见文本,渲染前剥离不支持的 OSC 8 包装(保留链接样式文本)
  • 修复 Ctrl+O 分页器在输出含控制字符时停在 less 的 binary-file 确认提示:less 调用统一加 -f 强制打开
  • /compact 原生压缩失败的回退提示改为 logger.warning,不再向终端打印打断对话流
  • 拆包后清理机械复制遗留的死 import:runner/(compress/core/loop/persist/retry_fallback/steer/stream)与 cli/commands/(context/cron_cmd/goal/helpers/model_config/runtime/session/tools_skills)各文件只保留本地真实引用,删掉约 680 行从原单文件带过来的未用 import;tests/cli/test_cli_configuration.py 的 4 个 patch(reset_skill_registry/load_skills/get_skill_registry/create_agent)从 cli_tools_skills 改到 cli_helpers——拆包后实际调用点在 helpers._refresh_skills_session,原 patch 打在错模块是无副作用的 no-op,autoflake 删掉未用 import 后才暴露
  • tools/buildin_tools.py(2154 行)拆成 tools/builtin/ 包:file_tool.py(BuiltinFileTool+path guards+_GLOB/_GREP_TIMEOUT)、execute_tool.py(BuiltinExecuteTool+exit-code helpers+_MAX_WAIT_SECONDS)、__init__.py(get_builtin_tools+re-export 7 个工具类);原 task_state_tools.py/web_tools.py 已在包内。agentica/__init__.py 与 tools/__init__.py 改从 agentica.tools.builtin 取,所有直接引用者(tests/examples/docs/agent/acp/gateway/evaluation)改到新路径,测试 patch 字符串(_GREP_TIMEOUT/shutil.which/asyncio.create_subprocess_exec/terminate_subprocess→file_tool;_MAX_WAIT_SECONDS→execute_tool;_detect_python_error_hint/_interpret_exit_code/_is_blocked_device/_check_sensitive_write_path→对应子模块)同步更新
  • agent/base.py(2091 行)抽出 goal 闭环到 agent/goal_mixin.py(GoalMixin:get_goal_manager/enable_goal_tool/run_goal/run_goal_step),Agent 继承链加 GoalMixin;base.py 降到 1794 行,只留公开 run API 面与薄委托,不再内嵌 goal 闭环。MRO 透明,所有 agent.run_goal() 调用无需改动

docs

  • apply_patch docstring 明确要求 Update/Delete 操作前必须先 read_file,禁止凭记忆构造上下文
  • README News 区重构:旧版本条目折叠进 <details> 区块
  • 终端文档更新 /new 命令别名说明及退出 CLI 后按 session ID 恢复的用法
  • 文档与 README 补充 CLI task / delegate / peer 选型:docs/getting-started/terminal.md、docs/multi-agent/choosing.md、docs/concepts/tools.md、docs/multi-agent/subagent.md;中/英/日 README News + 协作对照表
  • CLI 对 task / delegate(及结果锚点)完整展示任务正文,不再 40/80 字截断;子 agent 启动行同样全文

[1.4.11] - 2026-08-04

Added

  • OpenAI Responses API support. The new top-level OpenAIResponses model supports sync and streaming text, reasoning summaries and encrypted reasoning-state replay, image input, function tools, parallel tool calls, and structured output. CLI and Gateway profiles select it with OpenAI-only wire_api: responses; profile max_tokens maps to max_output_tokens, and Responses reasoning uses reasoning instead of reasoning_effort.
  • Provider-native Responses compaction. OpenAIResponses now calls /responses/compact before destructive local compression, replays the returned canonical window unchanged, persists opaque checkpoints across session resume, and retains a portable transcript for cross-provider fallback. Endpoint failures and prompt_too_long recovery use the existing local summary/rule-based pipeline; manual /compact [instructions] follows the same priority.
  • Markdown-configured subagents and CLI management. Packaged explore / research / code definitions now live in agentica/agents/*.md. Projects can add or override definitions in .agentica/agents/, users can share definitions through ~/.agentica/agents/, and /agents list|create|reload|remove manages the effective configuration. The default review subagent was removed so code review stays with the main agent and its full context; partial runs retain bounded tool inputs for resume.
  • Built-in apply_patch can update multiple files in one tool call. One strict patch envelope may add, update, or delete several text files. Agentica validates every path and hunk before writing, reuses the existing sandbox and sensitive-path guards, and keeps multi_edit_file unchanged for established single-file batch edits. CLI and Gateway summaries report the aggregated file and line counts.

Changed

  • Shell tools preserve the model's exact command string. execute and ShellTool no longer normalize arguments, rewrite Python literals, or convert python -c commands into heredocs. Safety policies may block a command and secret redaction may sanitize returned output, but the command sent to the shell is otherwise unchanged.
  • CLI now warns after successful main-agent context compaction. Automatic compaction recommends /new when long-session accuracy may degrade, repeated successful auto-compactions escalate the warning with a session-local count, and reactive recovery explains that compaction happened before retrying. Spinner lifecycle events, failed attempts, manual /compact, and subagent compactions do not affect the count.
  • Removed the read_file freshness/staleness machinery entirely (codex-style simplification): FileReadState, _file_read_state, _record_file_read, mark_read_context_stale, mark_all_read_context_stale, _edit_freshness_tip, Agent.mark_evicted_file_reads, Agent.append_evicted_file_read_notice, and the [Context maintenance] eviction notices are gone. Edits return the absolute path + diagnostics only; a failed edit_file ("String not found") remains the natural signal to re-read.
  • Default model context_window raised from 128k to 200k across Model base, OpenAIChat, LiteLLM, Ollama, and Claude, reducing premature tool-result compaction that caused repeated read_file calls.
  • Prompt and tool-schema token cost reduced. File-tool guidance is gated on registered file tools (no phantom tool names); dead # Available Tools table generation is removed; parallel/batch call guidance is restored; grep/glob docstrings are slimmed; task policy lives only in the tool system prompt; write_todos clarifies steps vs tool calls and returns a short status ack instead of echoing the full list.
  • write_todos keeps per-step progress updates. Completions are still not batched (one sync per finished step) so the CLI progress bar stays live; only the tool-result payload shrank.

Fixed

  • CLI resume restores both model context and the visible transcript. Resumed JSONL history is hydrated into canonical run-response messages used by later prompts, while user, assistant, tool-call, and tool-result entries are replayed in the terminal. Session summaries now print the executable agentica resume <id> command, and patch failures retain actionable multi-line details instead of collapsing the error to one short line.
  • CLI context usage now reflects the current session prompt instead of a token watermark. The status bar is updated from each main-agent request's actual messages and tool schemas, re-measured after each completed turn or /compact, and ignores subagent/auxiliary LLM calls. Per-turn footer tokens remain cumulative API consumption across retries and tool loops, so they no longer share a misleading data path with context occupancy.
  • Quote-tolerant file edits no longer rewrite unrelated punctuation. edit_file and multi_edit_file now use normalized quote text only to locate a match, then apply replacements against the original content so curly quotes elsewhere in the file remain unchanged.
  • Stale model_pricing_cache.json is no longer discarded. Catalog loading previously treated TTL expiry as "no cache" and, when the network refresh failed, silently fell back to the hardcoded pricing table — so new models (e.g. claude-opus-5, 1M context) never resolved. Refresh failures now fall back to the stale-but-valid cache file.
  • CLI resize no longer leaves repeated Enter to send ghost lines. The _resize_collapsed flag (meant to shrink the bottom frame to a single row during a terminal resize) was set but never read by the layout, so the full multi-row frame redrew on every SIGWINCH and multiplied ghost copies in scrollback. The collapse is now actually wired across the input prompt, queue bar, status bar, and input height, and the post-resize restore does a clean erase + absolute-cursor redraw instead of a diff invalidate().
  • File tools now expose clearer recovery signals. edit_file / multi_edit_file append one stateless "read or re-read the relevant region" action after String not found, without tracking session read state or blocking edits. grep now documents that path accepts either a file or directory, supports file paths in its Python fallback, and reports missing inputs as Path not found.
  • Learned Experiences no longer accumulate frontmatter debris. strip_frontmatter parses line-based --- delimiters (values containing --- no longer truncate the body); bumping a card refreshes its body from the new content; injected card bodies are capped; captured tool errors keep head+tail within a fixed budget instead of parking whole tracebacks in the system prompt.

[1.4.10] - 2026-07-24

Added

  • Native image capability routing. Model image support is now resolved from models.dev catalog metadata, with explicit supports_images overrides for private or aliased endpoints. Vision-capable base models receive original images directly; text-only models use the external OCR fallback.
  • Simplified session naming. CLI /rename <name> replaces /session rename, and /resume accepts a session number, name, or ID prefix.

Fixed

  • Pillow is declared as a core dependency. The model and default provider import paths use Pillow for PIL image inputs and image format detection, so the 1.4.10 wheel now installs Pillow>=10.0 automatically.
  • Wheel installation is validated without checkout shadowing. CI imports both the latest PyPI release and the newly built wheel outside the repository root, and verifies that the current wheel installs and imports Pillow.

[1.4.9] - 2026-07-21

Added

  • Unified 3-tier tool permission model (ask / auto / allow-all) across SDK, CLI, and Web/Gateway, centralized in agentica/agent/permissions.py. ask exposes only read-only tools; auto allows reads everywhere + writes restricted to work_dir (sandbox-enforced); allow-all is unrestricted. ToolConfig.permission_mode carries the mode; Agent.set_permission_mode() flips it at runtime without rebuilding the agent. CLI --permissions and /permissions command, Gateway per-session approval mode, and the SDK constructor all share one source of truth. Removed legacy yolo/full/strict naming.
  • Claude-over-OpenAI-compatible <invoke> tool-call compatibility in OpenAIChat: when a Claude model is reached through an OpenAI-compatible proxy that leaks antml:invoke blocks into text content (instead of structured tool_calls), the model layer now buffers the turn, parses the XML, and rewrites it into standard OpenAI function calls — so the tool actually executes and neither the leaked XML nor stray preamble (e.g. course) enters assistant history or the CLI. Native Anthropic (model_provider="anthropic") and standard OpenAI/DeepSeek/Qwen paths are unchanged.

Changed

  • Subagents are read-only by design. All built-in subagent types (explore/research/code) now deny write_file/edit_file/multi_edit_file/execute; the task tool's default subagent_type changed from code to explore, and its system prompt states subagents are read-only and the main agent does all edits. This fixes the root cause of "the LLM delegated my query to a task subagent and the cheap auxiliary model wrote garbage code" — subagents run on the auxiliary model and can no longer edit. User-registered custom subagents are untouched.
  • edit_file / multi_edit_file freshness checks are advisory tips, not hard blocks. Stale/unread/externally-modified files now produce a freshness_tip appended to the result (or included in a String not found error) instead of rejecting the edit. Sensitive-path writes still hard-fail. File version tracking is lazy (content hash only when mtime+size match) and _record_file_read hashes in-memory content to avoid re-reading just-written files.
  • Evicted read_file results are surfaced to the LLM. When compression / context-overflow evicts a read_file tool result, a [Context maintenance] user message is appended naming the affected paths and advising a re-read before editing — so the agent no longer silently edits from stale memory.

Fixed

  • CLI ask_user_question freeze. A callback-less AskUserQuestionTool could fall back to bare input() and deadlock against prompt_toolkit's stdin ownership. Added a process-wide default-callback registry (set_default_ask_user_question_callback) the TUI registers at startup, a watchdog that aborts/re-arms the prompt if the agent's turn ends or the request is overwritten, a _cprint freeze while an ask prompt is active, and a SIGQUIT (Ctrl+\) hard-escape that calls os._exit(1).

[1.4.8] - 2026-07-07

Fixed

  • TaskAnchor no longer leaks agent.run(message)'s first message into the system prompt every turn. TaskAnchor gains a source: Literal["message", "goal"] = "message" field that gates to_prompt_block(). Only explicit goal entry points — Agent.run_goal(), CLI /goal, and an active session-log goal — produce source="goal" anchors that render as ## Original Task. Ordinary agent.run(message) produces source="message" anchors that are still used as the retrieval query but stay out of the system prompt. This restores pre-1.4.0 prompt behavior for plain agent.run() callers (e.g. private chat seed, workflow handoff, session resume) where the "first message" is a transcript / replay / dump and pinning it system-wide was a bug. Callers that need long-task drift defense should use Agent.run_goal() or set agent.task_anchor = TaskAnchor(..., source="goal") explicitly.

Changed

  • Claude max_tokens resolution (ported from hermes-agent's anthropic_adapter.py):
  • Default changed from max_tokens: int = 8192 to max_tokens: Optional[int] = None. When None, a per-model output ceiling is looked up from _ANTHROPIC_OUTPUT_LIMITS (Opus 4.6/4.7 → 128K, Sonnet 4.5/4.6 → 64K, 3.5 Sonnet → 8192, etc.). Previously every model was capped at 8K which starved thinking-enabled models (thinking tokens count toward the limit).
  • Resolved cap is clamped to max(context_window - 1, 1) for small custom endpoints whose context window is smaller than the model's native output ceiling. No-op for full-size native models.
  • Positive-finite guard rejects locally: max_tokens=0 / -1 / 0.5 / NaN / True no longer leak to the API and 400 — they fall back to the model ceiling.
  • Claude auto-recovery from "max_tokens too large given prompt": Claude.invoke() and invoke_stream() now parse the API error message for available_tokens: N and retry once with max_tokens = N - 64 (safety margin). Prompt-too-long errors are NOT touched — that path still flows through _learn_context_limit_from_error. New module: agentica/model/anthropic/_max_tokens.py with resolve_anthropic_messages_max_tokens + parse_available_output_tokens_from_error (28 unit tests).

Removed (Breaking)

  • agentica.model.providers module deleted (ProviderConfig, create_provider, list_providers, register_provider, PROVIDER_REGISTRY). The registry indirection had a single concrete output (OpenAILike(**config)) so every OpenAI-compatible factory now directly constructs OpenAIChat with hardcoded base_url / api_key_env / default_model / context_window.
  • agentica.OpenAILike deleted. Was a 22-line subclass of OpenAIChat whose only behavior was a placeholder-api_key warning. Use OpenAIChat(id=..., api_key=..., base_url=...) for custom OpenAI-compatible endpoints.
  • agentica.model.openai.like deleted. AzureOpenAIChat now subclasses OpenAIChat directly.

Changed (Breaking)

  • Each XxxChat is now a thin top-level factory in agentica/__init__.py (e.g. DeepSeekChat, ZhipuAIChat, QwenChat, ArkChat, …). Added 5 previously-only-by-slug factories: NvidiaChat, SambanovaChat, OpenRouterChat, FireworksChat, InternLMChat.
  • New agentica.PROVIDER_FACTORIES: dict[str, Callable] exposes slug → factory dispatch for gateway / multi-tenant code (replaces PROVIDER_REGISTRY lookups).
  • agentica.model.defaults.create_default_model() now uses an inline env-var table + PROVIDER_FACTORIES.
  • agentica.gateway.services.model_factory.create_model() dispatches via PROVIDER_FACTORIES instead of create_provider.

Migration

# Before
from agentica.model.providers import create_provider
model = create_provider("deepseek", id="deepseek-v4-pro", api_key="sk-...")

# After
from agentica import DeepSeekChat
model = DeepSeekChat(id="deepseek-v4-pro", api_key="sk-...")
# Custom OpenAI-compatible endpoint
# Before:
from agentica import OpenAILike
model = OpenAILike(id="my-model", api_key="sk-...", base_url="https://...")
# After:
from agentica import OpenAIChat
model = OpenAIChat(id="my-model", api_key="sk-...", base_url="https://...")

Added

  • Standing-goal loop judge hardening (hermes-validated + beyond):
  • Tool-call summary fed to judge: Agent.run_goal() extracts (tool_name, is_error) pairs from each turn's RunResponse.tool_calls and passes them to judge_goal. Judge prompt now includes a Tools used this turn: edit_file, run_pytest(error), ls line so it can distinguish "answered with no tools" from "actually did work". Zero extra LLM calls — names + flags only. New optional tool_calls param on GoalManager.evaluate_after_turn() and judge_goal().
  • Tool-stuck auto-pause: GoalState.consecutive_tool_failures counts consecutive turns where every tool call errored. After MAX_CONSECUTIVE_TOOL_FAILURES = 3 the loop auto-pauses with paused_reason="tool-stuck". Any successful tool call resets; turns with no tool calls do NOT reset (a "just thinking while stuck" turn shouldn't get a free pass).
  • Subgoal "find evidence" rule: when subgoals are present, judge prompt now demands concrete evidence for each criterion (file excerpt / command output / result value) and explicitly rejects vague summaries like "all requirements met". Borrowed from hermes-agent's hard-won production prompt.
  • JSON parsing accepts weak-model output: _parse_judge_response now coerces "yes", "true", "1", "done", "y" strings and numeric 1 to done=true (small chat models and some reasoning models don't always emit JSON booleans).
  • Static prompts lifted to agentica/prompts/base/md/: goal_judge.md (judge system prompt) and goal_continuation.md (continuation template) now live alongside soul.md / heartbeat.md for consistency. New module agentica/prompts/base/goal.py exposes GOAL_JUDGE_SYSTEM_PROMPT, GOAL_CONTINUATION_PROMPT_TEMPLATE, and render_goal_continuation_prompt(). The dynamic per-turn user prompt stays in goals.py (it's conditional logic, not a static template).
  • Reasoning-judge guidance documented, no magic in code: judge models that need a large output budget (DeepSeek-Reasoner, o-series, qwq) must be constructed with max_completion_tokens set explicitly by the caller. The prior in-place mutation helper _ensure_judge_output_budget was removed — it was opaque, surprising, and mutated user-owned state. See docs/advanced/goals.md "Reasoning judge 的特别注意" for the recipe.

  • Standing-goal loop P0 + P1 (S + A tiers):

  • Ergonomic SDK surface on Agent:
    • Agent.run_goal(objective, *, turn_budget=..., token_budget=..., wall_clock_budget_sec=..., attach_goal_tool=True, event_callback=...) -> GoalRunResult — one-liner that drives the whole loop. Replaces the previous low-level GoalManager(agent._session_log, judge_model=...) + hand-written driver loop.
    • Agent.get_goal_manager(...) for power users who want to drive turns by hand without touching SessionLog.
    • Agent.enable_goal_tool() attaches GoalTool.update_goal so the model can self-mark complete / paused.
    • Agent._session_log and Agent.goal_manager are now formally declared dataclass fields (no getattr speculation).
    • New agentica.goals.GoalRunResult(status, reason, run_response, goal, turns_used) with response_content convenience property.
  • Runner._run_impl early-loads any persisted active GoalState from SessionLog and binds TaskAnchor to the goal objective — SDK paths now get goal-aware retrieval automatically, not just the CLI.
  • GoalState gains token_budget / tokens_used / wall_clock_budget_sec / wall_clock_used_sec and a new budget_limited status (semantically distinct from paused). Hard budget caps take precedence over tool short-circuit and judge.
  • agentica.tools.goal_tool.GoalTool.update_goal(status, reason): receive-only model tool letting the agent self-mark complete or paused (cannot rewrite the objective). CLI auto-attaches on /goal set and detaches on goal termination.
  • RunEventType.goal_set / goal_continuing / goal_completed / goal_paused events emitted through an optional GoalManager.event_callback.
  • New example examples/cli/03_goal_loop_demo.py: 4-scenario SDK tutorial (run_goal() one-liner / budgets / event_callback / manual loop) against a real LLM.

Changed

  • GoalManager.evaluate_after_turn now charges turn counters (turns_used, tokens_used, wall_clock_used_sec) BEFORE any short-circuit branch so per-turn cost is always tracked, even when a tool ends the loop. Decision priority is now: budget cap > tool signal > judge.
  • GoalRunResult field renamed final_response → run_response (typed Optional[RunResponse], was untyped Any) and the convenience property final_text → response_content, to align with Agentica's existing Agent.run_response / RunResponse.content terminology. final_* was an LLM-style modifier that didn't add information.
  • agentica.goals.DEFAULT_TURN_BUDGET bumped 20 → 100. Rationale: with token_budget and wall_clock_budget_sec now acting as the real hard caps, turn_budget is the safety-net against runaway loops; aggressive values (20–50) tripped accidentally on real coding workflows. Token / wall-clock budgets still bound actual cost, so a loose default is safe.

Changed

  • Top-level lazy imports (e.g. from agentica import Knowledge, Claude, SqliteDb, Swarm, ...) no longer emit DeprecationWarning. They are now treated as stable v1.x public API alongside the sub-module paths. The DEPRECATED_TOP_LEVEL registry has been removed; the planned v2.0 forced migration is dropped.
  • SearchSerperTool: fix misuse of logger.warning(..., DeprecationWarning) for the serper_api_key alias (the extra arg was silently ignored).

[1.4.5] - 2026-05-13

Fixed

  • search_memory now falls back to recent long-term memories when keyword search has no high-confidence matches.
  • Langfuse tracing now preserves Agent user_id and session_id on both root traces and OpenAI wrapper metadata.

[1.4.2] - 2026-05-10

Fixed

  • Default model resolution now preserves OpenAI priority when OPENAI_API_KEY is configured, falls back to Anthropic when ANTHROPIC_API_KEY is configured, and then checks OpenAI-compatible provider keys.
  • Agent-owned LLM tools now reuse the parent agent model before resolving a fallback provider, avoiding accidental OpenAI usage when another main provider is configured.
  • Experience capture and skill upgrade LLM calls continue to follow the agent auxiliary model or main model instead of creating a separate provider.

[1.4.0] - 2026-04-23

Added — Gateway IM Channels

  • agentica.gateway.channels.QQChannel: 接入 QQ 开放平台机器人(qq-botpy WebSocket,C2C 私聊 + 群 @ 消息),自动缓存最新 msg_id 用于回包;新增 extras agentica[qq]
  • agentica.gateway.channels.WeComChannel: 接入企业微信智能机器人(wecom_aibot_sdk WSClient),按 chat_id 缓存入站 frame 用于 reply_stream;新增 extras agentica[wecom]
  • agentica.gateway.channels.DingTalkChannel: 接入钉钉机器人(dingtalk-stream Stream 长连接 + HTTP 回包),自动管理 accessToken 缓存与续期;区分 1-to-1(channel_id=staffId)与群(channel_id="group:<openConversationId>");新增 extras agentica[dingtalk]
  • agentica.gateway.channels.WeChatChannel: 接入个人微信(内联 WxBotClient 走 ilinkai 私有 HTTP 长轮询,QR 扫码登录 + token 持久化),后台线程跑阻塞 loop,跨线程 call_soon_threadsafe 派发到主事件循环;新增 extras agentica[wechat]
  • ChannelType: 扩展 QQ 与 WECOM 两个枚举值
  • Settings: 新增 qq_* / wecom_* / dingtalk_* / wechat_* 字段及对应环境变量加载(QQ_APP_ID / WECOM_BOT_ID / DINGTALK_CLIENT_ID / WECHAT_TOKEN_FILE …)
  • docs/advanced/gateway.md: 新增 Gateway 完整文档,覆盖架构图、所有 IM 渠道的环境变量配置、HTTP API、自定义渠道、故障排查
  • 34 个新单测: tests/test_gateway_channel_{qq,wecom,dingtalk,wechat}.py,全部 mock 各家 SDK,无外部依赖

Changed

  • agentica/gateway/main.py::_setup_channels():按需注册 4 个新渠道,凡是缺关键凭据自动跳过并打日志
  • agentica/gateway/channels/__init__.py:re-export 新增的 4 个 Channel 类
  • 版本号:1.3.6rc1 → 1.4.0(按 SemVer:新增公共 Channel 类 → minor bump)

Notes

  • 所有新渠道都遵循"懒加载 SDK + 缺失依赖时抛清晰 ImportError"的现有模式
  • WeChat 渠道走的是非公开私有协议(ilinkai),仅推荐个人 / 内部场景使用

Added (Stage 2 + Stage 3)

  • _DEPRECATED_TOP_LEVEL mapping in agentica/__init__.py: 35+ symbols flagged for v2.0 migration
  • DeprecationWarning emitted when accessing top-level deprecated paths like from agentica import Knowledge / Claude / VectorDb / SqliteDb / Swarm etc., guiding users to explicit sub-module imports
  • agentica.workspace package: Split monolithic workspace.py (1402 lines) into a package structure for incremental modularization

Changed (Stage 2 + Stage 3)

  • agentica/__init__.py docstring: rewritten with v1.3.6+ recommended import style guide + backward-compat note
  • agentica/workspace.py → agentica/workspace/base.py (file move, zero business code change)
  • agentica/workspace/__init__.py re-exports Workspace, WorkspaceConfig, plus module-level constants for test mocking
  • tests/test_workspace.py: updated 3 patch paths from agentica.workspace.AGENTICA_HOME → agentica.workspace.base.AGENTICA_HOME (reflects new package structure)
  • tests/test_skill_lazy_loading.py: updated importlib.reload target from agentica.workspace → agentica.workspace.base

Compatibility

  • 100% backward compatible: all top-level imports still work; only emit DeprecationWarning
  • from agentica.workspace import Workspace path is unchanged for all 11 internal usages and external users

[1.3.6] - 2026-04-18 (sdk-dev branch)

Added

  • pyproject.toml: 新打包配置,对标 agno 细粒度 extras 风格 + 超级组合 extras
  • docs/API.md: Public API Tier 1/2/3 稳定度合约
  • 20+ 细粒度 extras: agentica[rag] / [qdrant] / [chroma] / [gateway] / [mcp] / [acp] / [arxiv] / [yfinance] / [browser] / [ddg] / [exa] 等
  • 8 个超级组合 extras: [tools-search] / [tools-research] / [tools-finance] / [tools-media] / [tools-browser] / [vectordbs] / [storage] / [models] / [tracing] / [full]
  • agentica.model.anthropic.Claude: Anthropic 直接默认装(核心 provider)
  • 友好 ImportError 提示:未安装对应 extras 时,agentica.gateway / agentica.mcp / agentica.acp / agentica.db.SqliteDb 等会抛出带 pip install agentica[xxx] 命令提示的清晰错误

Changed

  • 依赖瘦身:默认 install_requires 从 23 个 → 19 个(M1-核心 A+ 方案;瘦身 17%)
  • 默认产品化能力保留:Workspace / CLI / DeepAgent 内置工具(web_search, fetch_url, file, shell, todo, task)全部默认可用
  • 核心新增 6 个:beautifulsoup4 / lxml / markdownify / requests / puremagic / tqdm,确保 agentica CLI 和 DeepAgent 默认工作
  • setup.py → pyproject.toml(PEP 621 标准)
  • requirements.txt:更新为核心 19 个依赖的参考清单,实际以 pyproject.toml 为准
  • agentica/__init__.py lazy loading:增加 _LAZY_ATTR_OVERRIDES 修复 LiteLLM / DeepSeek / Moonshot 等 alias 的延迟加载(pre-existing bug)

Fixed

  • test_lazy_loading.py::test_all_public_names_accessible:修正对缺失 extras 时的友好 ImportError 处理,不再误报
  • CLI 默认可用性:之前一度把 bs4 移到 [crawl] extras 导致 agentica --query crash;本版通过把 6 个工具依赖纳入核心保证 CLI / DeepAgent 默认开箱即用

Removed

  • 无(1.3.6 是内部收敛 + 打包优化,不删除 Public API)

Migration Notes

  • 向后兼容 100%:装 pip install agentica 即可获得 v1.3.5 的"开箱即用 DeepAgent + CLI"完整体验
  • pip install agentica[full] 等价于 v1.3.5 完整能力(含 RAG / Gateway / MCP / 40+ 第三方工具)
  • 仍使用 setup.py 等旧安装方式的场景需迁移到 pyproject.toml(PEP 621 自 Python 3.10 标准)

[1.3.5]

Added

  • MemoryType enum — four-type memory classification (user, feedback, project, reference) for workspace memory entries
  • MemoryEntry Pydantic model — typed memory entry with name, description, memory_type, file_path, content fields
  • Workspace.write_memory_entry() — write a typed memory as an individual .md file with YAML frontmatter, auto-updates MEMORY.md index
  • Workspace.get_relevant_memories() — relevance-based recall: parses MEMORY.md index, scores entries by keyword overlap against current query, loads only top-k content files; supports already_surfaced set for session-level dedup
  • Workspace._update_memory_index() — enforces MEMORY.md hard limits (200 lines / 25KB); FIFO eviction of oldest entries
  • Workspace._score_memory_entries() — hybrid keyword scoring (word-level + char 2-gram) supporting both English and CJK queries
  • Workspace._strip_frontmatter() — strips YAML frontmatter before injecting memory content into system prompt
  • Memory drift-defense note — appended to all injected memory to guard against stale file/function references
  • WorkspaceMemoryConfig.max_memory_entries — max memory entries to inject per run (default: 5); replaces removed memory_days
  • Agent._surfaced_memories — session-level set tracking surfaced memory filenames, prevents cross-turn re-injection of same entries
  • Agent.get_workspace_memory_prompt(query) — now accepts query parameter, passes it to get_relevant_memories() for query-aware recall
  • CompressionManager.auto_compact(working_memory=...) — reuses WorkingMemory.summary directly when available, skipping LLM summarization call; faster and cheaper with no information loss
  • SandboxConfig.allowed_commands — optional command whitelist for execute tool (prefix-matched on first token)
  • Agent._running flag — concurrent reuse of the same Agent instance now logs a warning
  • WorkingMemory.max_messages — soft FIFO eviction limit (default: 200) to prevent unbounded memory growth
  • Message.role field validator — rejects invalid roles at construction time (system, user, assistant, tool only)

Changed

  • Workspace.get_memory_prompt(days=N) removed — replaced by get_relevant_memories(query, limit, already_surfaced); full-dump memory injection is no longer the default behavior
  • WorkspaceMemoryConfig.memory_days removed — no longer needed; relevance-based recall replaces time-window-based loading
  • System prompt memory zone: both _build_default_system_message and _build_enhanced_system_message now extract self.run_input as query and pass it to get_workspace_memory_prompt(query=...)

Fixed

  • update_model() now clears model.functions and model.tools before each run, preventing tool accumulation on reused Agent instances
  • OpenAIChat.response() raises ValueError instead of IndexError when choices is empty
  • AnthropicChat.response() raises ValueError instead of crashing when content is empty
  • FunctionCall.execute() generator result concatenation now uses str(item) to prevent TypeError on non-string generators
  • OpenAILike warns at construction time when api_key is still the placeholder "not-provided"
  • _load_mcp_tools removed redundant if/else branch (both branches were identical)
  • task() recursion depth capped at 5 levels via _task_depth context propagation

Added (Tests)

  • tests/test_workspace.py::test_get_memory_prompt updated to cover write_memory_entry() + get_relevant_memories() with and without query
  • tests/test_hooks.py — AgentHooks, RunHooks, _CompositeRunHooks, ConversationArchiveHooks
  • tests/test_runner.py — empty message guard, concurrent warning, run_timeout, structured output fallback
  • tests/test_swarm.py — parallel mode, partial failure, duplicate name detection
  • tests/test_model_validation.py — empty choices, usage=None, Message role validator, structured output fallback

[1.3.2] — 2026-03-17

Added

  • Swarm — multi-agent parallel autonomous collaboration (agentica/swarm.py)
  • ConversationArchiveHooks — auto-archives conversations to workspace after each run
  • _CompositeRunHooks — internal wrapper for composing multiple RunHooks instances
  • RunConfig.enabled_tools / enabled_skills — per-run tool/skill whitelisting
  • Agent.disable_tool() / enable_tool() / disable_skill() / enable_skill() — agent-level runtime control
  • Agent._load_runtime_config() — loads tool/skill enable/disable from .agentica/runtime_config.yaml
  • SandboxConfig.blocked_commands — command-level blacklist for execute tool
  • examples/agent_patterns/08_swarm.py — Swarm usage example
  • examples/agent_patterns/09_runtime_config.py — Runtime config example
  • examples/agent_patterns/10_subagent_demo.py — SubAgent example

Changed

  • deep_agent.py renamed to tools/buildin_tools.py; DeepAgent now uses BuiltinFileTool, BuiltinExecuteTool, BuiltinWebSearchTool etc.
  • Runner._run_impl — removed duplicate auto-archive logic; archive is now handled exclusively by ConversationArchiveHooks

[1.3.1] — 2026-03 (v3 post-merge cleanup)

Added

  • WebSearchAgent with search enhancement modules (search/orchestrator.py, query_decomposer.py, evidence_store.py, answer_verifier.py)
  • Extended thinking support for Claude and KimiChat models
  • Kimi provider integration (model/kimi/)

Fixed

  • Preserve tool call messages in multi-turn conversation history
  • Deduplicate Model layer, unify RunConfig signatures

[1.3.0] — 2026-03 (v3 architecture refactor)

Changed (Breaking — internal architecture, public API preserved)

  • Phase 1: Removed 19 thin provider directories; unified via model/providers.py registry factory
  • Phase 2: Converted Model hierarchy from Pydantic BaseModel to @dataclass
  • Phase 3: Async interface consistency + structured output for all providers
  • Phase 4: Added @tool decorator and global tool registry (tools/registry.py)
  • Phase 5: Extracted Runner from RunnerMixin; Agent now delegates execution via self._runner
  • Phase 6: Unified guardrails with core.py abstraction layer
  • Phase 7: Simplified __init__.py lazy loading
  • Phase 8: 35 new v3 tests

Added

  • AgentHooks, RunHooks lifecycle hooks system
  • RunConfig per-run configuration overrides
  • SubAgent for isolated ephemeral task delegation
  • Skill system (skills/) — Markdown+YAML frontmatter skill injection
  • ACP server for IDE integration (Zed, JetBrains)

[1.2.x] and earlier

See git log for historical changes prior to the v3 refactor.