hanafubuki-agent

架构

hanafubuki-agent 是怎样组成的:crate 与分层、内核与轮次、插件宿主、上下文与压缩、存储、模型 API、思考、终端界面,以及不明显的设计选择背后的原因。

本页面向第一次读这份代码的人,说明各部分如何协作,以及那些从代码里看不出来的选择为什么这样做。必须遵守的规则在插件规则和仓库的 AGENTS.md;嵌入方式在嵌入 Agent;本页背后的确切上限、失败规则和文件格式见内部细节。

目标

Agent 是一个内核(hanafubuki-agent-kernel),拥有会话、轮次、历史和每个步骤的快照;能力由 kardia 上的插件提供。内核只通过 hanafubuki-agent-contracts 中的注册表接触插件。设计服务于三个目标:

  • 故障隔离。 故障限制在它的所有者之内:工具调用失败是模型可见的错误;插件故障停止并重启那个插件;MCP 服务器故障让那台服务器进入 Failed 再重新连接。只有内核故障才会重建整个 Agent,而 Agent 失败从不让宿主应用停止。
  • 可扩展。 新能力是一个插件加一行清单;内核、契约和前端都不用改。
  • 固定模型看到的内容。 golden 测试记录每个模型可见的面;模型能看到的变化要有意地重新生成它们。

crate 与分层

依赖只向下指。cargo xtask check-dependencies 按层表(xtask/src/dependencies.rs 的 LAYERS)检查每个成员只依赖它那一行允许的成员。

层crate作用
中性机制foundation、tool-contracts、process、runtime、host路径、取消、阻塞边界、panic 隔离、设置词汇;工具规格类型;进程所有权;被隔离的 Tokio 运行时;通用模块宿主(注册表、租约、故障、重启策略)
领域approval、skills、web-search、model-api、workspace-fs、execution、mcp、memory、worktree、hooks、sandbox、compression、packages各自独立、可单独测试的能力
插件 APIcontracts注册表与扩展点契约;重新导出 host 的注册与故障机制,插件只依赖它
内核与历史kernel、history会话、轮次循环、工具规划与流水线、请求组装、世界状态、压缩与分层压缩、审批流程、恢复;JSONL 历史与 SQLite 索引
插件plugin-web、plugin-workspace-fs、plugin-execution、plugin-mcp、plugin-worktree、plugin-hooks、plugin-packages每个把一个领域 crate 绑定到扩展点,或作为服务提供给门面的调用;plugin-packages 是访客宿主,在进程外或以 WebAssembly 运行已安装插件的代码
配置configAgent 自己的配置(AgentConfig):三个 TOML 文件,独立模式下分层
门面hanafubuki-agent(crates/agent)组合:插件宿主与清单、Agent 自己的插件、槽位、服务 API、宿主接口、独立运行时、数据目录锁、日志
界面tui、update、cli终端界面(只依赖门面);二进制的自更新(只依赖 foundation,只有 CLI 使用它);hanafubuki-agent 二进制(依赖门面、终端界面与自更新)

(表中省略了 hanafubuki-agent- 前缀。)门面和终端界面的行都不含 update,所以嵌入 Agent 的宿主永远不会链接自更新。除了层表,检查还执行与表无关的规则:不依赖任何 Hanafubuki crate(任何来源);内核不依赖任何插件;插件依赖插件 API,不依赖内核、门面或其他插件;每个插件 crate 都是门面的依赖(门面挂载它);只有门面依赖配置 crate;host 只依赖 foundation;kardia 只出现在 host、插件 API、内核、插件和门面中,它的加载器和访客桥(kardia-loader、kardia-hmr)只出现在访客宿主(plugin-packages)中,而且从不使用 kardia 门面 crate(它带有 WASM/dylib 热重载)。

三条边界承载了大部分设计:

  • 内核和插件只在契约中相遇。 内核不依赖插件,插件不依赖内核、组合或其他插件。内核不注入任何插件可以替换的东西,所以替换插件从不重启内核,也不丢失会话。
  • 模型 API 只是线路。 它把 ModelInputItem::ContextFragment { role, kind, content } 原样发送,kind 只是标签。段的包装文字属于拥有它的插件;check-model-api-context 检查模型 API 的源码不出现任何上下文段类型。
  • Agent 不知道宿主的领域。 宿主的东西(在 Hanafubuki 里是实例、任务中心、界面上下文、它那部分指令)通过宿主接口到达 Agent。

插件宿主

宿主(例如 Hanafubuki 的模块宿主)
└── AgentSlot                 每次启动的运行时、内核故障重启、崩溃循环停止
    └── AgentHost = ModuleHost<AgentPlugins>
        ├── Core:       agent-host-services(BlockingService)
        │               agent-kernel(发布 AgentKernelRegistries)
        │               agent-wake(唤醒调度器)
        ├── Capability: web、workspace-fs、view-image、execution、mcp、memory、skills、titles、
        │               recap、goal、subagents、worktree、hooks
        ├── 宿主行:     Hanafubuki 的 tasks、instances(Capability)、ui-context(Context)
        └── Context:    workspace-context、permission-mode
  • AgentSlot 保存 Agent 的状态(Disabled、Starting、Running、Faulted、Stopping、Failed、Stopped)并监督它:每次启动构建自己的被隔离运行时,构造并恢复服务,启动插件,然后在后台连接 MCP 服务器。持有者每次调用时重新解析槽位,所以没有旧的 Agent 能被继续访问。
  • AgentHost 是通用 ModuleHost 的 Agent 配置:两个核心行,然后是清单(host/manifest.rs,它以第三个核心行 agent-wake 开头)中每个启用的行,宿主的行在其中;每行在前一行就绪或超时(PLUGIN_START_TIMEOUT,20 秒)后挂载。配置从 Agent 的设置和宿主的代理派生,启用状态来自 disabledPlugins。
  • 注册表在运行时启动前由内核创建,agent-kernel 插件发布它们;插件注入并注册条目。共十个:工具、工具源、上下文贡献者、上下文渲染器、轮次准入、提示贡献者、审批规则、继续钩子、工具生命周期钩子、观察者。内核在固定的时刻读取每个注册表的快照(每个采样步骤、每个请求、轮次准入、提交之后)。
  • 注册是调用者的副作用。 条目属于注册它的插件并随它离开:停止中的插件先把条目从新快照中隐藏,等待租用中的调用(DRAIN_GRACE),再取消它们。无法接受的注册(重复的 ID、保留或冲突的工具名、同一类型的第二个贡献者或渲染器)让注册的插件启动失败,不影响任何轮次。

故障

三类所有者,三种结果:

故障由谁捕获结果
插件代码 panic内核调用插件时的守卫(RegistryEntry::guard、PluginFaults::guard);kardia 守卫 apply、effect 与 disposer那次调用自己的错误路径;插件的 PluginFault;宿主停止插件,按 RestartPolicy 重新挂载(2 秒、10 秒、30 秒,10 分钟内三次,之后 failed 直到重试)
功能调用 panic门面功能辅助函数(AgentApplicationService::feature)中的 PluginFaults::guard_async该调用返回 FeatureUnavailable;提供该功能的行的 PluginFault,宿主像上面一样停止并重新挂载它;其他功能和 Agent 继续运行
MCP 服务器的工具调用 panicMcpTool::invoke 中的 catch_panic_async那次调用的“internal error”;那台服务器 Failed 并重连;mcp 插件和其他服务器继续运行
内核代码 panic轮次任务、命令守卫、Agent 的工作线程组、宿主任务(spawn_kernel_task)报告给实例的 AgentKernelFaultSink;槽位把 Agent 标为 Faulted,停止它,2 秒、10 秒、30 秒后启动新实例,从磁盘重建会话

功能插件失败只损失它的功能。 门面作为调用提供的功能(概要、标题建议、工作树、钩子的列表与信任)由它的插件行提供的服务承担,每次调用时解析;该行关闭、启动中、失败或重启时,调用返回带原因的 FeatureUnavailable,其他一切不变(宿主、配置与状态)。

为什么内核故障要重建整个 Agent: 锁不会中毒(全部使用 parking_lot),所以 panic 后什么都不会回滚,内存中的会话状态可能只改了一半;磁盘上的历史才是一致的副本。

这一切依赖展开。进程的 panic hook 只允许已知会被捕获的 panic 展开:Agent 的线程运行在被隔离的运行时(ContainedRuntime,线程名 agent-rt)和被隔离的工作线程组上,守卫也做标记。这些标记在 Agent 自己的 foundation 里,所以宿主的 hook 必须询问 hanafubuki_agent::panic::is_panic_contained(panic hook 桥)。kardia-hmr 的访客线程自己捕获 panic,并在 kardia-hmr 中标记自己;访客宿主把这个检查注册到 foundation,所以同一个函数也为它们回答。

启动与关闭

启动领取一个代次,构建运行时和进程所有者组,回收上一次运行留下的进程组(process-groups.json),在运行时的阻塞池上构造服务(构造时启动模型发现,在后台列出默认 Provider 的模型)并运行恢复,启动插件,安排 MCP 连接(同时最多四个,各有自己的超时),然后把服务装为 Running。崩溃循环标记(start-marker.json)在三次未完成的启动后停止自动启动。关闭在 20 秒预算内按固定阶段进行:关闭槽位、停止轮次、MCP、插件(一次性释放 kardia 根)、记忆、历史与执行、进程组、运行时。插件不拥有 MCP、记忆、历史或执行的生命周期,所以它们拆除的顺序无关紧要。

会话与轮次

  • 会话有配置(Provider、协议、模型、指令、模式、推理强度、上下文窗口、压缩设置)、模式(Default 或 Plan)、生命周期(Available、Archived)、标题、记忆贡献模式和角色。会话可以在某个轮次之前或在头部分叉。配置在一个地方规范化(normalize_session_config):创建、每次更新和恢复时。
  • 能力范围。 会话创建时(create_session(mode, role),没有角色时为 default)或在轮次之间切换到(set_session_role)的角色给它一个范围(AgentCapabilityScope)和该角色的指令,保存在它的配置中:之后编辑或删除角色文件不会改变已有它的会话,恢复也不读取角色文件。范围只收窄,内核在本来就取快照的地方应用它:工具计划、工具来源、上下文与轮次准入贡献者、提示贡献者、继续钩子,以及每个轮次冻结的模式;审批规则、工具生命周期钩子、观察者和渲染器始终适用(能力范围)。子会话的范围是父会话的范围再被它自己的收窄;分叉保留源会话的范围。
  • 谱系。 会话在创建时记录它所在的工作区(主根目录及其 Git 分支);如果它是子会话,还记录它的父会话和来源(Side、Subagent、Review)。分叉和子会话沿用来源的工作区。create_child_session 用父会话的模型和配置创建子会话(它的范围是父会话的范围再按请求的范围收窄,从不更宽;它的角色指令是赋予它的角色的指令,否则是父会话的),可以是空的,也可以从父会话最近的回合边界开始(它的头部,或正在运行的轮次之前的状态),并在创建时一并提交给它的上下文条目(继续上下文)。
  • 临时会话和其他会话在同一个会话表里,运行轮次的方式也完全一样,区别只在历史存储。内核的存储是 SessionStores:它按会话 ID 把每个会话的提交和读取分到持久存储,或分到内存中的 EphemeralAgentHistoryStore。所有 ID 都由持久存储分配,两者从不共用;会话列表和恢复只读持久存储,所以临时会话从不被列出或恢复,close_ephemeral_session(或进程结束)会丢弃它。它的记录只包含它自己提交的内容,而它的模型历史从继承来的内容开始;继承来的图片通过它们所属的持久会话读取。在每条提交路径上加标志会改动每一条路径;改为路由存储则一条也不用改。
  • 轮次作为托管的 Tokio 任务运行,经过 Sampling、RunningTools、WaitingForUserInput,以 Completed、Cancelled、Failed 或 Interrupted 结束。循环的每次迭代可能自动压缩,用冻结的工具计划对模型采样,运行工具(每个都在适用于它的工具生命周期钩子之间),消费 steering 输入,并询问继续钩子。轮次自身工作中的 panic 让轮次以 Failed(InternalFailure)结束,会话接受下一个轮次。
  • 会话驱动器。 AgentSessionDriver 是应用驱动子会话的窄端口:创建子会话、为它命名、为它选择模型(门面的 set_session_model 是同一段代码)、列出父会话的子会话、把父会话的权限模式交给子会话、运行一个轮次并等待结果、引导或中断这个轮次、读取最后的回答、关闭(停止它的后台终端,临时会话则丢弃)。外观层接受的每个轮次也由它准备(会话的 Provider、权限模式、世界状态和轮次扩展),所以它运行的轮次和用户的轮次准备得一样。旁路对话和 subagents 插件使用它;评审插件以后也会使用它。
  • 子代理。 subagents 插件的工具把子代理做成持久的子会话(来源 Subagent,标题是任务名),在 Agent 运行时上由它自己的任务用 run_turn 运行它的轮次,所以父会话的工具调用立即返回,wait_agent 只等待该任务在轮次结束时发出的通知:父会话的轮次从不占着子会话的轮次需要的东西,两者在运行时上并排运行。插件跟踪的内容(运行中的轮次、留给空闲子代理下一个轮次的消息)保存在内存中,在同一个 Agent 实例内插件重启后仍然保留;子代理有哪些则从内核读取(父会话的子会话),所以之前运行留下的子代理仍会被列出、能收到消息。中断使用内核的确认取消,只有在该子代理之后没有开始新的轮次时才记录轮次的结果;完成或错误排入父会话的持久唤醒队列,wait_agent 从中取用,所以没有被等待取走的状态在重启后仍然保留。子代理的角色(spawn_agent 的 agent_type)通过 AgentRoleCatalogReader 读取,这是应用基于它的角色目录构造的第二个窄端口,插件每次调用时读取它,所以派生看到的是当时的角色,插件自己不保留目录:子会话在一次提交中带着角色的范围和指令创建(由内核收窄范围)。它的 Provider、模型和推理强度在它创建之前由会话驱动(resolve_child_model)逐项解析:取 spawn_agent 的参数,否则取角色的,否则取父会话的。传入的 Provider 必须已启用(它的 ID,或某一个 Provider 的显示名称);传入的模型或 Provider 不发请求,对照该 Provider 已知的情况检查:它已记录的模型列表(内核的 listed_models)加上为它配置的模型,没有已记录的列表时放行;传入的推理强度对照模型已知的档位检查(ModelMetadata::known_reasoning,即 /effort 提供选项的规则)。被拒绝时是指明字段的工具错误,什么都不创建,所以不会有空闲的子会话占着任务名。然后 apply_child_model 把解析出的组合(Provider 和模型)与父会话的比较:组合不同时是一次模型选择,在同一次提交中设置推理强度,使用新 Provider 的端点、全局策略、新模型的窗口和图片输入能力;组合相同时只设置不同的推理强度。之后的每个轮次都把子会话绑定到它自己的 Provider(activate_provider_session)。指引在每一步列出可派生的角色,且只在该步骤的计划提供 spawn_agent 时出现(内核的 PromptStep.tools),所以略去这个工具的角色也略去指引;spawn_agent 的描述符在注册时固定,不列出任何角色而是指向指引,所以从不过时。在角色之下,指引列出 provider、model 和 reasoning_effort 可以传入的值:由会话驱动的 spawn_model_catalog 在该步骤的 prepare 中、在阻塞服务上构建,读取缓存的 Provider 注册表和内核的模型元数据,不发请求,所用的已知模型(known_models)和档位(known_reasoning)与检查所用的相同,并略去 model 无法接受的 ID,所以它列出的值派生都会接受;插件负责限定和措辞(models.rs,与拒绝的文字放在一起)。它是按变化持久化的提示快照,所以它的文字只取决于 Provider 设置、已记录的模型列表、学到的推理参数拒绝以及会话自己的 Provider 和模型,从不取决于观察顺序,只在模型元数据让它读取的事实过期时才取决于时间(学到的拒绝、已不在列表中的模型上报的档位,各在 7 天后):变化时追加新快照,不重写先前位置。
  • 唤醒。 在子代理工作时结束了轮次的会话不占用任何轮次、任务或线程;它们报告时,会话自行恢复。每个事件(子代理的结束、它发给父会话的消息)排入内核中会话的持久唤醒队列(唤醒事件):正在运行的轮次在下一步读到它,空闲的会话被唤醒。唤醒由 Agent 决定,轮次由宿主提交:调度器(核心行 agent-wake 的观察者)告知宿主在启动时安装的 AgentBackgroundEventSink(Woken),宿主用它选择的 sink 提交被唤醒的轮次,因为只有宿主知道会话是否正在显示、哪个 sink 仍然有效(终端界面为它显示的会话提交,exec 为它自己的会话提交)。每条路径都止于内核的准入,它最多投递一次队列,所以信号可以竞争、可以重复。选项 wakeOnBackgroundTasks 在激活时给每个会话策略;指引跟随轮次的策略(TurnWake),所以只有在模型会被恢复时,才告诉它结束轮次。用户的中断和失控上限会暂停根会话的唤醒,直到用户的下一条消息。
  • 持久化先于可见。 每次修改先持久提交到历史,才对外可见;提交失败恢复内存状态。提交在会话单元(cell)的锁下暂存,当追加被确认时结算:发布持久化的修订号或回滚,然后才发出事件。结算在历史写入线程上的确认中运行,而不是在等待的 future 里,所以 future 被丢弃时它照样发生。
  • 会话之间从不互相等待。 SessionTable 只在查找、插入或删除时持有它的锁;每个单元有自己的锁,只在内存中工作时持有,从不跨越 await、历史追加或其他 I/O,也从不同时持有另一个单元的锁。
  • 取消先协作,再中止任务,并在 5 秒内确认。被重启打断的轮次在恢复时变为 Interrupted。恢复拒绝的会话被隔离而不是致命:不改写也不删除它的任何文件,其他会话照常打开。
  • 独立运行时工作区可以移动。 AgentRuntime::set_working_directory 不新建实例就改变独立模式的工作区(它的根目录在一把锁后面):文件工具的 WorkspaceFsPolicy 按新的根目录重建,没有 workdir 的命令在新的第一个根目录中运行,所以活着的会话保持活着,每个会话在下一个轮次的 workspace_roots 段中看到新的根目录,不需要别的提示。有轮次、压缩或后台终端在运行时它被拒绝,因为它们都是在旧工作区中启动和批准的。配置的项目层仍是启动时读取的那一个。嵌入的宿主拥有自己的 WorkspaceRootsPort,所以这个调用只用于独立模式。工作树(hanafubuki-agent-worktree,由 worktree 行提供)是数据目录下的分离检出,使用者用这种方式移入其中。
  • 限制(AgentHardLimits):maximum_sampling_steps 和 turn_deadline 默认为 None,不设采样次数和整轮时长的默认上限。宿主可以用 Some 设置其中任一限制:采样次数超限时以 budget_exceeded 失败(之前的输出都已提交);到期时像用户取消一样取消轮次,以 deadline_exceeded 失败。这些可选限制不让模型看到。单项操作超时、轮次资源预算和手动取消仍然生效。内核对插件的调用若没有自己的上限(上下文、轮次准入、工具源或提示 prepare 的贡献,工具的 permission),就在 plugin_call_deadline(10 秒)内运行,所以挂起的内置、宿主或客体插件只损失它的贡献,从不拖住轮次(插件调用的上限)。

工具

每个步骤的计划

每个采样步骤构建一个不可变的 AgentToolPlan:内核的核心工具(new_context、update_plan、request_user_input,会话的压缩策略为 hierarchical 时还有五个压缩工具),注册的工具(每个处理器对这一步的 availability),每个工具源为这一步提供的工具,以及有工具被延迟时的 search_tools 和 tool_list。随后会话的能力范围排除它不允许的每个插件工具,它关闭的插件的工具源不会被询问;被排除的工具与未知工具一样不存在,也不算遗漏(能力范围)。内核自己的工具和工具发现工具从不被排除。计划同时冻结该步骤的审批规则快照和工具源的计划租约;调用针对宣告它的那个计划运行,租约让工具规划时依赖的东西(例如一个 MCP 连接)存活到步骤结束。计划模式只在范围保留的工具中保留 ReadOnly 工具、request_user_input 和压缩工具。

线路上的名字

工具在 Agent 内部的身份是 ToolName(命名空间段和本地名),注册表按扁平形式 namespace__name 索引它,这个字符串从不被反向解析。线路名按请求选择(ProviderToolTable):Responses 接受命名空间,带命名空间的函数保留命名空间和本地名;其他协议使用扁平名。每个名字被适配到协议的上限(Responses 与 Anthropic Messages 为 128 字节,Chat Completions 为 64 字节);后来者发生冲突或过长时被截断,并加上 _ 和它 (provider id, tool id) 哈希的 12 位十六进制,每一步都相同。返回的调用按 (namespace, name) 查找解析,历史记录两者。

schema 遵循同样的按协议规则:支持 strict_json_schema 的协议(Responses)收到完整 schema,其他协议收到所有 OpenAI 兼容端点都接受的关键字(portable_model_schema)。从不发送 strict,内核无论如何都按完整 schema 校验参数。

注册拒绝,规划改名。 注册时就能拒绝的都拒绝(保留名、已注册的扁平名、过长的名字),所以只有来自外部目录的工具源工具会在规划时冲突,它们被确定性地改名,而不是让步骤失败:拒绝一个冲突的注册只让一个插件失败一次,而让步骤失败会让每个轮次都失败,直到插件被关闭。

暴露与延迟工具

ToolExposure 是 Direct、Deferred、DirectModelOnly 或 Hidden。直接目录超出预算时,只有工具源的直接工具会被延迟,并在各提供者之间公平分配。延迟的工具通过 search_tools(精确列举名称只选择该工具,其他查询使用对名称、说明和 schema 的 BM25 索引)找到;搜索提交它的输出,然后提交一个 ConversationItem::ToolSelection。规划器接受上次压缩以来模型上下文中的选择,所以选择跨轮次有效,直到下次压缩。

tool_list 浏览当前步骤的延迟工具索引,不选择任何工具。它在所有协议中都是普通只读函数,包括支持原生工具搜索的 Responses:输出只有适配协议后的工具名和分页信息,不含说明或 schema。可选的 source 按提供者 ID 精确筛选,offset 从零开始,limit 默认为 50 并收敛到 1–50。名称排序后返回,next_offset: null 表示最后一页。被模式、能力范围或提供者能力排除的工具不出现在搜索或列举结果中。列举不会提交 ToolSelection;模型仍需通过 search_tools 获取定义后调用。所有协议都提供普通函数 search_tools,Responses 中它与原生 tool_search 同时存在;不同名称避免同一请求中的普通函数与原生工具重名。普通搜索结果包含每个匹配工具的 specification,其中有输入 schema。两条搜索路径提交相同的选择;选择工具会将它提升为直接暴露,同时清除线上的延迟标记,供下一次请求使用。普通搜索不依赖网关理解原生 tool_search_output。

调用流水线

内核拥有流水线,插件不能改变它的顺序:

流式接收并提交。 响应流到结束,每个工具调用在运行之前提交到历史。

处置。 未知、隐藏或未被接受的名字,或无法解析、过大的参数,变成模型可见的错误输出,轮次继续。

参数按工具的输入 schema 规范化(整数形式的浮点数和数字字符串变为数字,去掉不可为空的可选 null,在 additionalProperties: false 下去掉未声明的键),再由处理器容错解码。

门。 调用取得步骤的门:一个在途许可,然后对 ConcurrentRead 工具取得读访问,否则取得独占访问,先到先得。在门下运行模式策略、工具源工具的 schema 检查和处理器的 permission(在插件调用期限内,超过即为工具错误),所以分类能看到同一步骤之前的调用做了什么。

审批路由。 任何规则 Deny 就拒绝;否则任何 RequireUser 就询问用户;否则会话对该工具的许可授权;否则由轮次的权限模式决定(Manual 询问,AutoReview 询问审查模型,FullAccess 允许)。等待中的决定释放门,批准后再取回,所以同一步骤的其他调用可以继续。

调用在条目租约和子取消令牌下进行,受 ToolDescriptor::timeout 或轮次的工具空闲超时(10 分钟)限制。invoke 重新检查审批与它要运行的调用一致。

按调用顺序提交,每个尽早提交。 一个输出在之前每个调用的输出都提交后提交。以错误结束的调用(包括取消)不提交;其他调用照常完成并提交,因为它们的效果已经发生。取消时只有未完成的调用得到合成的“已中断”输出。

没有流式分派。 调用在响应流完、其条目提交之后才开始。像 Codex 那样每个条目完成就开始调用能缩短某些步骤;提交与取消的规则写成了以后可以加上它而不必改变,但目前没有需要。

模型请求中的工具结果保持连续。 一个工具可以在自身输出后立即提交 Skill 指令等上下文,此时同一响应中的其他调用可能还没有结果。普通采样和压缩请求会将这些插入的条目延后到所有待完成调用的输出之后,保持它们彼此的相对顺序。这使各协议中的 assistant 调用和对应结果保持连续,也适用于将 Responses 转成 Chat Completions 的网关。重新打开的会话同样使用这一投影;持久化历史保留原始顺序。

审批

AgentPermissionMode 是 Manual(默认)、AutoReview 或 FullAccess,每个轮次冻结:会话被设置了自己的模式时(set_session_permission_mode,与会话的许可一样只在运行时状态中)取它,否则取设置。每个工具调用由处理器的 permission 分类为一个 ApprovalAction(类型、风险等级、规范化摘要)。规则只能收紧。用户可以对 Manual 模式的提示回答 AllowForSession:之后同一工具(按 (provider id, tool id, generation))在会话剩余时间内不再询问,只保存在运行时状态中,所以重启、分叉和改变了的工具都会重新询问(对 MCP 工具来说是服务器的配置、凭据或目录条目改变了;未改变的服务器重新连接后,许可仍然有效)。审批产生一次性的 AuthorizedAction;修改型工具在 invoke 中重新计算动作并要求它们完全一致。审批决定由谁允许一个命令,沙箱决定它能触及什么。请求离开沙箱的动作带有 sandbox_escalation(它在规范化摘要中,所以沙箱内命令的批准不能让它在沙箱外运行):FullAccess 拒绝它,与 Codex 的 never 一样;它的 AllowForSession 只允许同一个动作再次运行(按工具和动作的详情区分),与工具的许可分开。用户事后批准的 AutoReview 拒绝(approve_denied_action,会话最近十个被拒绝的 PermissionReview 条目之一,在轮次之间)成为内核的 ContinuationContext 说明,provider 为 kernel,hook 为 approved-denied-action:模型把它读作可信的上下文,审查证据把它作为 user approval 条目与用户的消息一起保留。它本身不授权任何东西,所以重试仍会再次审查;历史格式不变。

执行环境

命令环境选择、POSIX 启动快照和 MCP 继承见环境变量。foundation::environment_policy 共享选择规则,execution 持有按会话缓存的内存 Shell 快照,并通过现有进程管理服务在命令沙箱中捕获。内核通过强类型轮次扩展提供当前权限模式,执行插件在过滤之后加入调用身份。

上下文

段、槽位与渲染器

模型可见、既不是历史也不是工具的所有内容都是某个 ContextSectionKind(一个开放的标识符,按蛇形命名持久化)的上下文段:

  • 世界状态段在轮次准入时由 ContextContributor 产生,按类型与内容的 SHA-256 定版本,只把变化作为 WorldStateUpdate 提交。内核每个步骤自己写 tool_catalog_omissions,steering 在轮次中替换它携带的宿主上下文。
  • 提示片段每个请求由 PromptContributor 产生:先 prepare(异步,每步一次,可以 I/O),再 contribute(纯函数)。skills 插件渲染 Skill 目录(skill_catalog),memory 插件渲染记忆摘要(agent_memory)。

段通过它类型的 ContextRenderer 展示给模型:一个槽位、槽位内的顺序、一个角色、前言、后记和是否带版本。渲染器是数据,渲染不运行插件代码,所以它不需要守卫、租约或超时,请求也不会因它失败。每一串相邻的段按槽位(Instructions、WorldState、Capabilities、Memory)排序,再按渲染器的 order,再按类型名;稳定的槽位在前,每步都可能变化的记忆摘要在最后,以保持缓存的前缀尽量长。顺序是显式的,按所有者分段(内核 0,Agent 的能力插件从 100 起,宿主的 500–599,Agent 的上下文插件从 700 起,已安装插件 900;上下文渲染器),而不是注册顺序,所以插件重新启动不会改变请求的顺序、让提供方缓存的前缀失效,清单的顺序也不会被模型看到。

变化检测: 普通请求在历史位置保留世界状态更新。替换明确说明同类型的旧段已被取代,移除则加入明确的撤销说明。提示快照也只追加变化后的值或撤销,而不是从请求前缀删除旧指引。当前含义由最新适用的快照决定;在有意的历史转换之前,更早的字节保持稳定。

稳定的请求前缀

模型、配置和工具不变的普通续接,不会仅因为新增轮次或工具结果就重写已经发送的上下文。提示贡献者仍按每步 prepare/contribute 收集;内核将渲染后的角色和内容作为 PromptContext 持久化快照,仅在对应 kind 改变或撤销时追加,任务计划也走同一路径。采样步骤先提交这些变化再发送,估算请求投影同样的待提交变化;重新打开会话继续使用这些快照。压缩窗口的 canonical initial context 不会仅因新轮次开始就被丢弃;若压缩移除了提示快照,下一个准备好的请求会重新追加当前值。

历史工具输出按模型窗口派生每条结果的投影预算,并受 canonical 最小值和配置最大值限制。预算不再按不断增加的结果数平分,因此追加结果不会缩小旧结果。准入与压缩仍约束整个请求/窗口及历史总量。

这是请求构造契约,不保证提供方缓存命中率。有意的压缩、历史编辑或替换,以及模型、配置、指令、渲染器和工具暴露变化,都可能合理地改变前缀。提供方的缓存路由、保留时间与最小可缓存长度不受 Agent 控制。思考回传仍遵循各协议:Chat 的 reasoning_content 跨轮保留,Anthropic 的签名思考仅在本轮发送。本契约不承诺所有协议的完整消息始终严格保持前缀,也不改变既有图像降级行为。实现细节见持久化投影。

AGENTS.md

workspace-context 插件的 workspace_instructions 段在每次轮次准入时读取:先读用户自己的文件(数据目录下的 AGENTS.override.md,否则 AGENTS.md),再读每个工作区根目录从根一直到宿主选中的目录中的文件,所有文件共用 32 KiB 预算,每组公平分配(每组最多 16 KiB)。因为每个轮次都重新读取并按摘要比较,会话中途的编辑会到达下一个轮次。

上下文窗口与 token 估算

会话的 context_window_tokens 在创建会话或选择模型时、记录它的 Provider 的列表时、每个轮次开始时以及每个回答提交时解析:配置的窗口,否则模型元数据对该模型所知的窗口(从拒绝中学到的窗口,仅在它更小时;Provider 的模型列表报告的窗口;打开 models.dev 时它给出的窗口;否则一张已知模型系列的小表);都没有就不做自动压缩。整个 Agent 只有一种 token 估算(hanafubuki_agent_contracts::tokens,字节数 / 4)。计数之所以一致,是因为它们数的是同一个请求:准入检查、步骤的请求和自动压缩对下一个请求的检查都用 step_model_request 构建请求,用 estimate_model_request_tokens 计数,工具和记忆都包括在内。步骤的计数按组得出(compose_request:每组是其自身序列化部分的估算,其余部分是不属于任何组的内容,合起来就是请求的估算),会话保留它(从不持久化),并在响应提交时记下 Provider 对该请求的报告,供 /context(session_context)使用;压缩安装时丢弃它,在下一个请求发送之前,/context 按压缩检查时的方式估算那个请求。

自动压缩与后台压缩以上游最后报告的提示总 token 数为基准,只加上此后请求原始估算值的正增长量,不再用偏大的「字节数 / 4」估算覆盖已知的实际用量。usage.contextEstimatedTokens 与 contextConsumedTokens 一起持久化该估算基准,重启会话后仍能校准;响应未报告用量时保留此前的这一对值。没有可用基准时才估算整个请求。安装压缩结果或切换模型路由后清除估算基准,等待新的响应报告用量。图片按图片 token 估算参与请求增长计算,不按 Base64 数据大小计数。

默认保留历史内容的字节上限为 16 MiB,与模型 token 窗口相互独立。它约束当前活动历史保留的内容,不是整个历史数据库或图片文件的大小。超过该上限仍会拒绝追加;模型窗口更大不会关闭这项资源限制。

图片正文由历史存储的内容寻址附件保存,不在 rollout 和 SQLite 投影中反复内嵌。用户附件和工具返回的预处理图片原本已使用引用;内嵌工具图片(包括 MCP 图片资源)在工具输出限额处理后也会被提取,保留原始编码。持久化内容保留顺序和元数据,图片数据字段置空,由引用指出原内容位置,构造模型请求时再填回正文。同一会话内相同字节共享一个附件文件,分支继续引用来源会话的附件。临时会话也使用 SHA-256 内容标识,避免同长度图片互相覆盖。已有内嵌记录仍可读取,不会被重写。

模型元数据

Agent 对它访问的每个模型所知道的内容,是内核的 ModelMetadataRegistry,每个 Agent 一个,按路由(ModelRouteKey:协议、规范化的 base URL 和模型 ID,所以提供同一模型 ID 的两个 Provider 互不混淆)存放。每项事实(上下文窗口、最大输出、推理及其强度、图片输入、结构化输出的档位)都可以未知,并带有来源和观察到的时间(ModelMetadata)。注册表为每个路由保存两种来源,另有一份按模型 ID 查找的 models.dev 目录副本,逐项事实分别解析,顺序如下:

  1. 配置:用户设置的值,由调用方传入(注册表不读配置)。会话把它保存在 AgentSessionConfig.configured_facts 中(AgentConfiguredModelFacts:窗口、最大输出、图片输入、推理档位),facade 在会话创建、选择模型以及为每个轮次激活时,从 providers.toml 中模型自己的设置(providers[].models."<id>")以及(对窗口而言)策略的 contextWindowTokens 填入,所以修改会在会话的下一个轮次到达。策略的 imageInput = "disabled" 是凌驾于这一切之上的配置“不支持”。
  2. 学到的,来自 Provider 的拒绝,且只朝安全的方向:学到的窗口只在小于其他来源给出的窗口时采用,学到的“不支持”优先于报告的“支持”。学到的事实保留 7 天。
  3. 报告的,来自该路由自己的模型列表(list_provider_models,每个条目整条记录)。
  4. 目录:models.dev 的目录,在 modelMetadata.modelsDev 打开时使用,显示为 models.dev。它只补充其他来源都没说的事实,并且只做加法:它的“不支持”从不保留。模型 ID 先规范化(小写,去掉 vendor/ 前缀、-latest 和 -YYYYMMDD 日期),优先在该 Provider 自己的条目下查找:ModelProviderNames(Provider 的 id 和其端点的主机名),内核在每次拿到 Provider 的 id 及其 base URL 时(创建会话、选择模型或激活会话;model_metadata;model_context_window)按端点记下它,只在本次运行中保留。没有自己的条目时,合并所有提供商对该 ID 的条目:取最小的限制和任何一个“是”(hanafubuki-agent-model-api 的 models_dev.rs)。
  5. 内置:窗口表。

列表的事实。 list_provider_models 给出列表中每个模型已知的信息(AgentListedModel:列表的条目及其 ModelMetadata),在调用之内解析:每个 Provider 的任务在它的列表返回并记录之后,通过一次内核调用(AgentService::resolve_listing)解析它的全部条目,Provider 及其模型自己的设置取自这次调用对 providers.toml 的那一次读取。注册表的锁只取一次,用来复制每个列出路由学到的事实、models.dev 副本和 Provider 的名称,条目在锁外解析,所以一千个模型的列表相对列表请求本身几乎不增加开销。报告的来源是条目本身,而不是注册表为它记录的内容:否则收缩保护暂不采信的列表(内部细节),或被上限淘汰的路由,会给出旧的事实或什么都没有。所以收缩的列表暂不采信期间,模型列表显示它所说的,会话则保留已存的事实,直到下一次列表被采信。各处用同样的词说这些事实,即 hanafubuki-agent-model-api 的 ModelMetadataSource::label(configured、learned、reported、models.dev、built-in)以及 ModelMetadata::supports_reasoning 和 supports_image_input(是、否,未知时为 None;任何事实说模型推理,它就推理,不论档位是否已知;配置的、报告的或学到的事实说它不接受推理时,它就不接受):/status、模型策略的窗口摘要、doctor --online 和模型列表。

目前据此行事的有:窗口,在创建会话、选择模型、列表、每个轮次开始和每个回答提交时(见下文);从“请求过长”的拒绝中学到的窗口(见下文);最大输出,用于阈值压缩为回复留出的空间(压缩),以及 Anthropic 带思考时的 max_tokens;图片输入和推理(都见下文)。内核从不访问数据目录:它的所有者注入一个 ModelMetadataStore,注册表启动时加载一次,每次变化后把快照交给它。facade 的存储是 model-metadata.json(数据目录);内核的其他构造方式只在本次运行中保留这些事实。列表的合并、过期和文件格式见内部细节。

模型发现。 facade 自己列出各 Provider 的模型,所以在任何人打开模型列表之前,列表报告的事实就已知道(model_discovery.rs)。Agent 的 worker 组里有一个 worker,带自己的运行时,从通道接收请求,一次列出一个 Provider,经由内核的 list_provider_models:用该 Provider 的端点、令牌和请求头,与它的请求相同,列表也像其他列表一样被记录。构建服务时请求一次(默认 Provider);此后每当会话绑定到某个 Provider 时都请求:在它上面创建会话,选用它的模型(/model、角色的模型),或为一个轮次激活会话,这也覆盖了在另一个 Provider 上恢复的会话。请求只是往通道发送一条消息,所以从不延迟会话的创建、模型选择或轮次。一个端点只有在它最近一次记录的列表已满一天,并且在本次运行中距它上次列出已满一天、或距上次失败的列出已满 15 分钟时,才会再次列出。这一天从模型元数据保存的列出时间(listedAtMs)算起,所以新的运行(包括每次 exec)不会再列一次,用户自己请求的列表也计算在内;失败只在本次运行中记住。失败以 warn 级别记录 Provider 的 id,从不记录它的回答(那是它的内容,可能回显凭据),也从不让轮次失败。关闭时 worker 组会取消进行中的列出;被取消的列出不记录任何东西。modelMetadata.discovery = "off"(配置参考)让所有请求都不被执行;用户自己请求的列表(模型列表、Provider 的测试、doctor --online)仍会记录。同一个 worker 在同样的请求下、不论 discovery 的值,在 modelMetadata.modelsDev 打开时下载 models.dev 的目录(fetch_models_dev:独立的客户端,经过 Provider 的代理(内核的 model_proxy,facade 在启动和每次设置变化时从宿主的 NetworkSettingsPort 设置它),User-Agent 为 hanafubuki-agent/<version>,不带任何 Provider 的凭据或请求头,最多一分钟、32 MiB,关闭时取消),并记入注册表(record_models_dev_catalog):副本满一天后再下载,失败后满 15 分钟再试。副本存入快照,使用一周;失败以 debug 级别记录失败的环节,从不记录 models.dev 的回答,副本继续使用。关闭时 worker 丢弃副本(forget_models_dev_catalog)。facade 的测试构造方式无论设置如何都不运行模型发现,测试用 Provider(test_support::configure_test_provider)也会关掉它,所以脚本化的模型服务器只看到测试自己的请求。

延后解析。 会话以创建时已知的信息创建,从不等待列表。内核在会话的锁内、在一次提交中再次解析会话的路由(service/context_window.rs):list_provider_models 记录列表之后,对该端点上每个已加载的会话各做一次提交,提高修订号但不改 updated_at(列表不是活动,而会话列表按它排序),有暂存提交的会话跳过;每个轮次被接纳时,在接纳它的提交中;以及每个回答的提交中,所以暂存提交期间到达的列表会在下一步的压缩检查之前被采用。值或来源不同的窗口会替换 context_window_tokens,会话记录的用量(以及该回答的用量)也在同一次提交中改用这个窗口计量,所以恢复时“用量与窗口一致”的检查仍然成立。session_model_metadata(/status)显示会话的窗口,会话还没有窗口时(未绑定到 Provider 的会话)显示解析出的窗口。会话记住窗口的来源(AgentSessionConfig.context_window_source,未知时省略,所以之前写入的会话保持不变)。配置的窗口是 configured_facts 中的窗口,它优先;没有来源的窗口(宿主给的,或在记录来源之前写入的会话)视为配置的,会话创建或加载时被纳入 configured_facts;没有窗口的会话采用已知的窗口。路由完全解析不出窗口时(报告它的列表已过期,也没有其他来源知道这个模型),会话保留已有的窗口,除非它被记录为配置的、学到的或来自 models.dev 的(没有来源的窗口会保留):配置不再写明窗口、学到的窗口被遗忘、models.dev 被关闭或其副本过期时,会话的窗口变为未知。尚未绑定到 Provider 的会话没有路由,不会被解析,所以内置表不会单独替换 Provider 报告的窗口。

学到的窗口。 Provider 以超出窗口为由拒绝某一步的请求时(ProviderContextWindowExceeded,在 hanafubuki-agent-model-api 中分类:内部细节),路由会学到一个窗口,这发生在 run_sampling_request 中、轮次循环压缩并重试之前:拒绝中写明的窗口(context_limit_in),否则被拒请求自己的估算(estimate_model_request_tokens),作为上界;两者都只在 1024 到 20,000,000 token 之间才采用(PLAUSIBLE_CONTEXT_WINDOW)。路由在学到的窗口有效期内(7 天)保留其中最小的一个,解析时只在它小于其他来源给出的窗口时采用。被拒的会话立即采用它:在会话的锁内单独提交一次,与延后解析走同一个改写(refresh_context_window,所以配置的窗口不变,用量随窗口一起改),并在它采用的是学到的窗口时记录 ModelContextWindowLearned { tokens, previous };于是拒绝之后的压缩、重试以及之后的每一步都按它压缩。此后该路由上的每个会话都从它开始,本次运行和下次运行都一样(model-metadata.json)。无论自动压缩是否开启都会学习;只从轮次的请求中学习(压缩自己的请求过长时照旧被裁剪,不学习),轮次被取消后也不再学习。

图片输入。 会话是否向模型发送图片(effective_input_capabilities,从不持久化),由用户的策略和路由的图片输入事实共同决定(service/image_capability.rs)。imageInput = "disabled" 优先,它作为配置的“不支持”传给注册表,否则取模型自己的 imageInput(configured_image_input,在 service/model_facts.rs 中);配置的“支持”优先于学到的“不支持”,所以在它之下拒绝会让那次请求回退(仍会学到),下一次请求再次发送图片。否则,“不支持”(列表报告的,或从拒绝中学到的;学到的“不支持”优先于报告的“支持”)会关闭图片;“支持”(包括 models.dev 的)或没有事实时图片照旧开启;models.dev 的“不支持”从不保留,因为它只做加法。会话在创建、选择模型或恢复时采用它(所以压缩在任何轮次之前读到的也是它),并在接纳轮次、接受插话、准备每个采样步骤、运行每个工具调用以及每次快照之前,在会话的锁内再取一次;传输层给不出路由的会话保留已有的值。图片关闭时,该步骤的工具计划不含 view_image(ToolPlanContext.image_input),请求构建时其中的图片被替换为占位文字(sanitize_images_for_unsupported_input),所以不会先有请求被拒绝;带图片的轮次开始或插话会被拒绝(InvalidInput)。轮次进行中变化的事实从下一步起生效,此前已计划的 view_image 调用在运行时被拒绝(ToolCallContext.image_input)。拒绝后的回退不变:用占位文字重试一次(ModelRetryScheduled { stage: ImageInputFallback }),之后路由学到“不支持”,保留 7 天,存入 model-metadata.json。未加载会话的快照没有传输层,只反映策略本身。

推理。 请求携带的推理强度按请求解析,从不保存(service/reasoning.rs):会话配置的推理强度,按路由解析出的推理事实收窄(hanafubuki-agent-model-api 的 request_reasoning_effort)。一无所知,或模型会推理但列表没有列出档位时:按配置发送。列出了档位时:配置的在列表中则用它,否则它的别名在列表中则用别名,否则用 minimal < low < medium < high < xhigh < max 上最近的档位(距离相同时取较低者),否则不发送。不接受推理参数的模型(列表报告的,或从拒绝中学到的,学到的优先于报告的“支持”):不发送。模型自己的 reasoningEfforts 是凌驾于两者之上的配置事实(空列表:不推理)。没有配置推理强度:不发送。步骤的请求(begin_sampling)和压缩自己的请求都采用它,并带上路由的最大输出,Anthropic 据此确定思考的大小;推理强度被收窄或去掉时,每个会话以 warn 级别记录一次日志(用日志而不是事件:活动跟踪器的事件分派是穷举的,且已到大小上限)。传输层给不出路由时,一无所知。Provider 拒绝该参数时(UnsupportedReasoning,内部细节),去掉它重试一次(ModelRetryScheduled { stage: ReasoningFallback }),与图片回退可以叠加,路由学到“不推理”,保留 7 天,存入 model-metadata.json。normalize_session_config 不再在任何协议上去掉推理强度:每种协议都会发送它(模型 API)。可选的范围比收窄所用的更窄:ModelMetadata::known_reasoning 只从配置的或报告的事实中给出档位,猜测(models.dev、内置表)不给出任何档位;/effort 和模型策略的 reasoningEffort 一行(SettingKind::ChoiceOrText)提供这些档位、Default 和手动输入的值。

结构化输出。 标题、标题建议、回顾、记忆提取和自动权限审查都向模型要一个 JSON 对象,沿同一条阶梯请求(hanafubuki-agent-model-api 的 request_json_object):协议原生的 JSON schema 输出、强制工具、纯文本。协议给出第一级(Responses 和 Chat Completions 为原生,Anthropic 为强制工具);路由只会更低,从某一级被拒绝(UnsupportedStructuredOutput、UnsupportedToolChoice)中学到,或在其他 400 或 422 之后从回答了的较低一级学到,保留 7 天,所以拒绝结构化输出的网关每周只多一个被拒绝的请求,而不是每个标题一个。阶梯在模型 API 中,事实在内核中:结构化请求所用的会话(create_private_model_session 给出的、审查者的)从注册表回答 structured_output_capability_for 和 learn_structured_output,所以只依赖模型 API 的记忆模块和门面的插件不必接触注册表也能学习。审查者没有强制工具这一级,并严格读取它的回答(内部细节)。

压缩

手动和在线自动压缩在运行、准备安装及结束时发布 CompactionUpdated。本地摘要运行期间,summary 是当前 assistant 项实际收到的累计文本;完成项会在安装前校正文本。流式更新只改变实时快照和有界事件日志,不逐片写入历史,因此重连可以读取当前部分摘要。取消或失败时,终态快照保留部分文本,但不安装它。createdAt 和 updatedAt 提供操作的真实时间。Responses 压缩没有可读摘要,只发布状态。后台预计算保持独立生命周期,在被采纳时呈现。

压缩用本地摘要或 Responses 的压缩替换历史,由会话的压缩能力选择。它在会话记录的克隆上暂存,并作为 Compacted { checkpoint } 边界安装,所以失败只丢弃克隆,历史不变。本地摘要的请求声明轮次的工具,工具选择为 none(回答里的工具调用是错误),就像重放的请求保留工具、只禁止调用它们一样:它与轮次有相同的指令和工具缓存前缀,而且在每种协议上,历史中的工具调用和结果都与产生它们的工具一起发送。它保留用户消息(最新的优先,在预算内)和摘要,从不摘要上下文段:下一个请求从注册表重新渲染每个段,所以轮次中途被压缩的窗口仍带有 Skill 目录和记忆。触发条件:轮次前和轮次中达到阈值、手动、Provider 报告上下文窗口错误之后。阈值(AgentContextTokenStatus::calculate)是窗口的 autoCompactThresholdPercent(默认 80%),当剩下的部分容不下一次回复时更低,源自 Hoshimi:min(window × percent / 100, window − headroom),其中 headroom 是路由的最大输出(未知时为 32,768),但不超过 max(4096, window / 10),也不超过 window / 2。最大输出在检查阈值的地方从模型元数据解析(会话不保存它),所以在默认的 80% 下,20,480 及以上的窗口按百分比压缩,更小的窗口更早(10,000 的窗口在 5,904)。同一个限值也界定后台压缩的区间和安装压缩后的下一个请求。错误触发有上限:每步一次压缩加重试,成功响应之前第二次出错则轮次失败(context_window_exceeded)。每次出错都会先让路由学到一个窗口(学到的窗口)。

压缩百分比只作用于当前上下文窗口,不作用于多次请求的累计模型用量。累计输入/输出 token、工具调用次数、工具输出字节数和钩子注入字节数仍会统计,但默认不会因此终止回合。显式设置的预算与上下文窗口相互独立:反复发送较小提示可能耗尽配置的预算,却没有填满上下文;预算压力不会触发压缩。重复步骤检查也仅在主动配置后启用,因为相同调用可能是正常轮询,而进展摘要并不比较工具返回的内容。独立应用的会话驱动在每个新回合前应用当前预算设置,恢复会话也一样,不会继续沿用历史快照中的旧默认值。

会话还有压缩策略(AgentSessionConfig.compaction_strategy):standard 即上面的压缩;background 在会话工作时对快照运行它,稍后安装结果;hierarchical 由模型自己把历史折叠成摘要,在请求时投影(源自 billion-context)。每种策略都以这种压缩为底线(手动、模型的 new_context、上下文错误后的重试)。facade 在每次模型操作前从 [compaction] 读取策略,并在会话空闲时应用(set_session_compaction_strategy);临时会话(/side)总是 standard;background.childSessions 关闭时,子会话(子代理的、评审的)以 standard 代替 background。同一次激活还把修改后的 remoteCompaction 写入会话的压缩能力,压缩会用它核对传输。

后台压缩(background,来自 Codex 的 async_compaction)运行会话自己的实现,三种中的任一种,适用任何 Provider。轮次在第一个请求之前和每个请求之后启动它,条件是:上下文达到或超过窗口的 [compaction.background] thresholdPercent(facade 把它放进轮次扩展)且低于前台阈值,之前已有完成的轮次,轮次没有被取消,并且自动压缩开着。它只压缩已完成的轮次,即当前轮次 TurnStart 之前的历史,所以它之后的部分总是从一个轮次开始,安装后的历史保持完整的轮次结构。它运行在会话拥有的任务上,而不是作为会话的操作:轮次、steering、/model 和其他所有更改照常进行,中断轮次只停止这个轮次的启动。它的槽位不持久化,所以重启丢弃它,不留下恢复义务。

结果在下一个检查点安装:步骤的自动压缩检查之前,或 /compact 之前。需要压缩时(阈值、Provider 的上下文错误、/compact),如果有一个仍在运行,就等待它而不发送自己的请求,直到轮次被中断;结果失败、不适用或过期时在线压缩,安装后的结果仍让下一个请求超过阈值时再在线压缩一次。模型请求的新上下文总是在线压缩。安装是变基(InstallMode::Rebase):窗口必须仍是它压缩的那个,历史必须仍以它读取的历史开头,之后添加的历史保留在替换之后。它的用量属于会话,在它结束时记录,无论是否安装,任何轮次的预算都不计入它。关闭、归档和删除会取消它并等待它的任务;策略或压缩能力的更改会取消它。

分层压缩(hierarchical)是 billion-context 的算法,移植为纯 crate compression,由内核驱动(service/compression/)。它从不改写历史:每个请求都从窗口历史的投影构建,投影中模型折叠的块代替它们覆盖的消息。用户、助手和工具输出的文本带有引用标签(<acp tokens="…" type="…">m00001</acp>),模型用它们指明要折叠的范围;工具调用的参数从不带标签。仍然有效的 compress 调用留在请求中,作为它的摘要的载体;载体已不在的块,在它的位置显示为 [Compressed conversation section] 摘要。压缩过的前缀和压缩摘要从不折叠。策略为 hierarchical 时,请求还带有:指令之后的算法静态提示,作为最后一条用户输入的提醒或状态行(从不持久化),以及五个内核核心工具:改变状态的 compress 和 decompress,只读取状态的 search_context、acp_status 和 acp_cache。decompress 从存储的历史返回一个块、它的一个范围或一条消息的图片(重新附在输出上),或通过历史存储把块写到会话的导出文件;search_context 搜索摘要和被折叠的原文。可选功能默认关闭,它们加入:absorb(模型用工具 absorb 提炼一个大的工具结果,此后它离开请求)、crush(在 absorb 要求之前,确定性地折叠 JSON、代码和日志)、内容存储(大的工具结果在到达时被替换为占位符,原文由 acp_retrieve 返回,保存在会话自己的一个文件中,位于其附件旁边,不在记录里)和 rules(模型用 acp_rule 记录的提醒,显示在指令中)。状态(引用、块、提醒的基线)增量持久化:每个改变了它的运行时检查点带一条链的一个链节,即快照或自上一个链节以来的差分,差分超过上次快照时写新的快照(PersistedAgentRuntimeState.compression_update);compress 或 decompress 在写入其输出的那次提交的锁下再应用一次,所以折叠和它的回执落在同一次提交中。分叉或子会话保留它持有其消息的那些块及其引用;缺失或无法读取的状态从窗口中的 compress 调用重建。

窗口由模型负责,所以阈值压缩(轮次前和轮次中)关闭。标准压缩仍是底线:Provider 的上下文窗口错误、/compact、new_context,以及最终出口(上下文连续三个请求超过紧急阈值,且已没有可折叠或可截短的内容)各运行一次。它压缩的是投影后的视图,摘要作为文本;安装后,被覆盖的条目已离开窗口,块随之失效。切换到 hierarchical 时从空状态开始,在当前窗口上生成引用。切换离开时,有效的块继续投影,标签和载体都保留,所以请求只在指令和工具上变化;不再有提示、提醒或工具产生新块,下一次标准压缩结束它们。对该 crate 的每次调用都在 catch_panic 下运行:投影中的 panic 让这个请求带完整历史发送,轮次剩下的部分按 standard 运行(下一轮次再尝试);compress 或 decompress 中的 panic 是这次调用的错误。

宿主在调用输出的那次提交中看到每次折叠的 ContextCompressed 事件(生成的块数、它们替换的 token 数、层级),投影的 panic 则是 ContextCompressionFailed。会话的快照带有活动块数和压缩的 token 数(compression),facade 的 compression_status 读取算法的状态面板和缓存报告,不改变会话。终端界面以折叠的形式显示 compress 调用(它的范围和回执的第一行),并提供 /compression 和状态栏的 compression 项。

思考

模型流式输出的思考作为类型化事件传给使用者,并作为对话条目保存,其文本从不作为模型输入回放;Anthropic 签名的思考块在本轮内回传,Chat Completions 的 reasoning_content 从每一轮回传,都是各自协议的要求(见下文)。

  • 模型 API。 思考是 ModelEvent::ReasoningDelta { item_id, kind, index, delta }(kind 为 Summary 或 Raw),位于推理条目的开始与完成之间。Responses:reasoning_summary_text.delta 与 reasoning_text.delta,请求在设置了推理强度时发送 reasoning: {effort, summary: "auto"}(否则 OpenAI 不发送摘要)。Chat Completions:delta.reasoning_content 或 delta.reasoning,每段连续的思考一个条目。Anthropic Messages:thinking 块与 thinking_delta,以 display: "summarized" 的自适应思考(Claude 4.6 及以后)或思考预算请求(Provider 与模型)。
  • 内核。 每个推理条目得到内核自己的 ID(AgentReasoningId,提供者的 ID 从不离开流),依次发布 ReasoningStarted { reasoning_id, sampling_step }、ReasoningDelta { reasoning_id, delta }(Markdown)和 ReasoningCompleted { reasoning_id, duration_millis }。保留的文本是条目的摘要(有的话),否则是原始文本。条目在完成时结束;响应先转向回答或工具调用时,就在那里结束:Responses API 可能稍后才完成它,等到那时才停的计时会把回答也算作思考。它迟到的完成仍然提供保留的文本和推理块(内部机制)。
  • 单独的上限。 思考不计入 maximum_model_output_bytes:每个条目在 maximum_reasoning_text_bytes(256 KiB)处按字符边界截断,其余的既不显示也不保存。否则一个有 30 KB 思考的轮次会开始失败。
  • 历史。 步骤把每个条目作为 ConversationItem::Reasoning { text, duration_millis, sampling_step, truncated, replay } 与其他条目一起按模型产生的顺序提交。它的文本只用于展示:as_model_input 跳过它,token 估算不计它(只计 replay 从每一轮回传的内容),压缩丢弃它,权限审查和记忆从不读取它。提前停止的响应用已经流出的内容完成打开的条目。
  • 回传 Anthropic 的思考块。 手动思考(带预算的 type: "enabled")会拒绝这样的工具结果:它回应的助手消息不以思考块开头;也会拒绝任何被改动的思考块。所以解码器把每个 thinking 块连同 signature(signature_delta)完整保存,redacted_thinking 块保存其 data,作为条目的 replay(ModelReasoningReplay,每块最多 1 MiB,Debug 不显示内容)。它从不序列化:不进历史、不进快照、不进事件。步骤的请求把本轮(最后一个 TurnStart 之后)的思考块作为 ModelInputItem::Reasoning 放在它们之前的助手条目前面,Anthropic 编码器只在手动思考时发送它们;Responses 和 Chat Completions 略去它们。手动思考的请求若要接续的工具调用所在消息没有可回传的思考块(重启后恢复的轮次、轮次中途的压缩、没有思考的第一步),就不带思考发送,Anthropic 接受这样的请求。自适应思考不回传任何思考块:Anthropic 允许全部省略,而它 5.1 及以后的模型在系统提示、工具或思考块之前的任何消息变化后会拒绝该块,即使普通上下文变化现在追加快照,工具变化(例如 search_tools 添加工具)仍可能触发这一限制。
  • 回传 Chat 的 reasoning_content。 DeepSeek 的思考模式会拒绝(400)这样的带工具请求:其中某条之前的助手消息(任何一轮的)没有带上它产生时的 reasoning_content;不带工具时它忽略这个字段。所以 Chat 解码器把每个增量都以 reasoning_content 到达的一段思考完整保存为 ModelReasoningReplay::ReasoningContent { text }(最多 1 MiB;超过的,或以 reasoning(OpenRouter 的字段)到达的,不保存)。发送这个字段的服务器也接受它回传,所以不读取模型 id。这个变体超出它的轮次(ModelReasoningReplay::outlives_its_turn):请求从投影后历史的每一轮放入它,压缩的请求也一样;它随条目持久化,这一点与 Anthropic 的思考块不同,但不出现在转录页中。Chat 编码器(chat_completions/assistant.rs)把助手消息的文本或第一个工具调用之前那些推理的 reasoning_content 按到达顺序直接拼接(中间不加分隔,即非流式响应完整携带的文本),设在这条消息上,只有工具调用时 content 为 null,与 request.reasoning 无关;请求中后面没有消息的推理被略去,Anthropic 的思考块也被略去。hierarchical 投影让推理跟着它后面的消息:放在该消息之前的摘要之后,消息被折叠时随之丢弃。没有内容可回传的助手消息(此前的会话、超过上限的思考)不带这个字段发送;只要它还在窗口中,DeepSeek 就可能拒绝该会话的请求,包括压缩的请求,因为那个请求也带着工具。DeepSeek 的拒绝提到 reasoning_content,而它不是推理参数:它仍是远端错误(reasoning_refusal.rs),从不让路由学到“不支持推理”。Anthropic 编码器略去这个变体,手动思考的检查也不把它当作思考块;Responses 略去所有思考块。

存储

数据目录(嵌入时由宿主指定,Hanafubuki 是 <app_data>/data/agent)的内容见数据目录。

  • 历史(hanafubuki-agent-history,格式版本 5):每个会话一份 JSONL rollout,它是权威的;SQLite 索引是投影,需要时重建。新条目和字段都是增量添加的(ToolSelection、Reasoning、ToolCall 上可选的命名空间;运行时状态的 parentSessionId、origin、cwd 和 branch,旧记录中没有,读作空),移除的字段是被忽略的未知键。打开时无法接受的东西只损失它自己的会话:另一种格式的 rollout 移入 .recovery,无法投影的留在原处并在每次启动时重试修复,会话被隔离;其他会话和 Agent 照常打开。写入经过每个会话一个的写入线程,追加和它的投影写好后才确认。
  • 记忆(hanafubuki-agent-memory,移植自 Codex)分两阶段从会话历史中派生:阶段一用一个小模型提取每个空闲会话,阶段二由整合子 Agent 处理提取结果,发布 MEMORY.md 和 memory_summary.md。先判断资格再应用上限,两个阶段都有退避(30 秒翻倍到一天),发布先提交数据库再重命名文件。
  • Skill(hanafubuki-agent-skills):仓库 Skill 来自每个工作区根目录及其祖先直到 Git 根目录中的 .agents/skills,每次读取目录时重新计算;然后是用户根目录和内置的 System Skills。Skill 的正文作为 ConversationItem::SkillContext 每个轮次每个 Skill 只交付一次。Skill 从不注册或限制工具。
  • 配置(hanafubuki-agent-config):三个 TOML 文件,各自一个修订域和一把锁(config.toml、providers.toml、mcp.toml,后两者只有所有者可读)。读取逐字段解码,无效值取默认值,未知键保留,需要修复的文件先复制到 .recovery/;写入用 toml_edit 编辑磁盘上的文档(注释、布局和未知键得以保留),再原子重命名。独立模式下设置是分层的(profile、受信任的项目文件、-c),但自动修复只改用户文件。普通全局写入也以该文件为目标;设置中心明确选择层的操作可以编辑受信任的项目文件,配置档操作则编辑选中的配置档表(写入设置)。终端界面的设置中心是设置目录的视图:它通过门面的调用写入,自己不做任何配置解析。详见配置。
  • 共享数据目录:<data_dir>/.lock 允许多个实例并行。会话写锁阻止两个实例加载或修改同一会话,共享文件锁串行化修改,拥有者锁让恢复跳过活动的会话和进程。见数据目录锁。
  • 持久化格式是不稳定的。 规则是读取方容错解码,隔离它不能使用的东西,从不删除用户数据。

设置目录

每项设置由它的所有者用 hanafubuki-agent-foundation::settings 的词汇描述一次(SettingSpec:键、标签、摘要、类型、默认值、改动何时生效、visible_if、commit_group),设置页按描述渲染,不必为每项设置写代码。门面的 settings_catalog() 每次读取时构建它(SettingsCatalog { sections, collections }),自己不设注册表:每个所有者通过它已经公开的东西提供内容。

插件可以在选项描述中声明 picker。提供商选择器与模型策略共享已配置的提供商及其禁用原因。模型选择器通过 providerKey 指定同一节中的提供商字段。客户端可在用户打开模型字段时读取该提供商的模型列表,通过 write_setting_values 保存选中或手动输入的模型 ID。

覆盖范围也包括集合字段:角色继承与限制、MCP 公开 HTTP 请求头、已安装插件默认策略(packageDefaults)、市场启停与稀疏检出,以及配置档中的已注册插件选项。配置档复用所有者的描述但不填入默认值,通过 AgentConfig::write_profile_values 校验整批改动后一次写入。新增持久化用户选项应接入所有者的节、插件 schema 或集合,并通过目录的读写测试验证;独立的 TUI 表单不能成为另一套配置来源。文件所有的钩子定义和角色仍展示来源及已有管理动作;会话状态、启动参数和宿主提供的服务不属于全局设置。

  • 节(SettingsSection:id、标题、分组、顺序、spec 和值)来自配置(AgentConfig::settings_sections,spec 声明在各设置结构体旁边;宿主的配置没有 network 和 tui 节),每个描述符带选项的插件行一节(pluginOptions.<row>,属于 Plugins 分组,键为 pluginOptions.<row>.<option>),以及每个 configSchema 能转换成选项的已安装代码插件一节(plugins."<id>".settings,键为 plugins."<id>".settings.<option>,由 package_setting_key 拼写)。每个值(SettingState)注明它来自哪一层(SettingSource),以及某一层的值为何无法使用。
  • 集合(SettingsCollection)是逐条编辑的记录列表:Provider 和模型策略(providers.toml)、按模型的覆盖(providerModels,每个 PROVIDER/MODEL 一条记录)、MCP 服务器及其保密的环境变量和请求头(mcp.toml,保密的值在它的凭据中)、已安装插件的 MCP 服务器(pluginMcp:开或关、只用和不用哪些工具,写在 [plugins."<id>".mcpServers.<server>] 下)、插件行、已安装的插件(packages)、市场、钩子(各自的定义在摘要中)、角色、已安装插件默认策略(packageDefaults)、Skill(skills)、沙箱维护(sandboxMaintenance)、角色文件(roleFiles),以及独立模式下的 profile、配置层(configLayers)和项目信任。集合以 spec 给出一条记录的字段,默认值即省略该字段时 add 写入的值;列出它的记录(SettingsRecord:id、标签、摘要、状态、问题、值,以及 readOnly,即为何这条记录只显示、不在这里写入:角色文件、profile 或插件中的角色)和动作(SettingsAction:add、save、delete 以及所有者自己的动作,如 set_default、list_models、connect、trust;每个动作说明是否先询问,由用户命名新记录的 add 说明以什么命名,即 namesRecord);没有 save 的集合只显示、不写入。保存中的 null 取消设置一个字段(profile 的键、模型的某项信息、回到插件自己的工具过滤)。本地设置目录包含由字段 spec 标识的机密值,供用户查看和编辑,同时列出哪些已设置;保存时省略机密字段会保留原值。TUI 默认遮蔽这些值,编辑框获得焦点时可按 Ctrl+R 显示或隐藏,切换不写入设置。记录中的映射(MCP 服务器公开的环境变量和请求头及其按工具的策略、Provider 的请求头)是 NAME=VALUE 文本列表,所有者把它读回映射,某一项不是这种形式或同一名称出现两次时拒绝;Provider 的请求头按凭据检查,只按名称列出,只写名称的条目保留原来的值。模型策略的回合预算使用 Agent 的上限,除非打开 customTurnBudget,它的字段从 Agent 的上限开始;推理强度和窗口旁边,策略会写出默认模型已知的信息。受修订号约束的文件,其记录带上文件的修订号,写入时要带上它。
  • 写入。 write_setting_values 按键把设置和插件选项一次写入用户的文件,每个值按它的 spec 检查,然后把设置应用到插件;代码插件的设置单独写入,一次一个插件,经由 set_package_settings(按它的选项和 configSchema 检查,它的 guest 用新设置重新启动)。run_settings_action 通过所有者的调用执行集合的动作(write_provider、write_provider_model、write_model_policy、mcp_write_server、set_plugin_enabled、包的调用、trust_hooks 和 set_hook_enabled、市场的调用、AgentConfig::set_user_json,profile 的 write_profile_values,以及其他条目的 write_entry_values 和 remove_entry);保存把值合并到已保存的记录上,因此没有 spec 的字段保持不变。不属于动作的有:授予代码插件所请求的权限,这是针对宿主所显示内容的同意(grant_package_permissions);没有 configSchema 的代码插件的原始 JSON 设置(set_package_settings);MCP 的 OAuth 登录(mcp_oauth_login)。
  • 失败。 无法读取的所有者(hooks 行被关闭)让它的集合为空并说明原因;目录的其余部分照常。

已安装的插件

已安装的插件是一个包:一个带清单的目录,从目录或市场安装,名字是 <插件>@<市场>。它不是插件宿主的一行。包存储(hanafubuki-agent-packages,移植自 Codex 的插件存储)把它们放在数据目录的 plugins/ 中(数据目录);配置中的 [plugins] 和 [marketplaces] 决定哪些启用(插件)。

  • 五种清单格式,按以下顺序探测:本项目的 .hanafubuki-plugin/plugin.json、Agent Plugins 1.0.0 的根 plugin.json(按 $schema 识别),然后是 Codex 的 .codex-plugin、Claude Code 的 .claude-plugin 和 Cursor 的 .cursor-plugin 中的 plugin.json。清单或其目录是符号链接或不是普通文件时,探测停止,这样无害的清单无法遮住另一个清单。我们的格式是 Codex 的清单加上供代码使用的 runtime、contributes、permissions 和 configSchema;存储保留它们,留给将来运行代码的部分。
  • 按外部来源读取。 无法使用的清单字段或组件路径会被略去并记录一个问题;只有不是 JSON 对象的清单,或无法读取的 Agent Plugins 名字或 $schema,才会失败。路径必须以 ./ 开头并留在包内。Codex 遇到某些类型错误的字段会让整个清单失败;这里只略去该字段。
  • 市场是 .agents/plugins/marketplace.json、.agents/plugins/api_marketplace.json、.claude-plugin/marketplace.json 或 .cursor-plugin/marketplace.json,支持本地、url 和 git-subdir 来源(不支持 npm)。无法使用的条目会被跳过;只有无法读取的文件才让它的市场失败。市场可以从目录添加(留在原处),也可以从 git 仓库添加(克隆到 plugins/marketplaces/);升级时取得远端的修订并替换检出。存储返回 [marketplaces] 记录,由调用方写入配置。
  • 安装先暂存再替换。 包被复制到暂存区(不含符号链接和 .git);没有清单时,把市场条目的字段写成它的清单;暂存的清单逐字节与来源核对;带描述的 commands/*.md 变成 Skill;然后把副本重命名为 plugins/cache/<市场>/<插件>/<版本>/,同一版本的旧副本保留到替换成功,更旧的版本被清理。使用中的版本:有 local 时用 local,否则用最高版本。包的数据目录在卸载后保留,除非清除。
  • 链接只是一条记录。 plugins link 按引用记录一个目录:它的条目在 linked.json 中,与缓存的 install.json 分开,所以旧版本重写 install.json 不会丢掉它;不复制任何东西,不计算内容哈希,也不向目录写入任何东西(它的命令不会变成 Skill)。存储在缓存中的包之后列出它,按目录当前的样子读取;同一 ID 的链接与安装互相拒绝,卸载删除记录并保留目录,update_package 拒绝它。
  • git 通过 Agent 的 ExecutorManager 运行,和工作树一样隔离:不继承仓库选择变量,不运行钩子,不提示,并有超时。

包是内容而不是代码:它贡献的东西流入各领域自己的来源,而这些来源本身已经是内置行。门面(crates/agent/src/packages,仿照 Codex 的 load_plugin)按键的顺序读取设置启用的已安装包,把每个包变成:

  • Skill 根目录:清单的 skills(否则是 skills/),以及(Agent Plugins 除外)由它的命令转换成的 Skill。它们的 ID 是 plugin:<plugin>@<marketplace>:<路径>,名称是 <清单名称>:<名称>,与 Codex 的命名相同(Skill 从哪里来)。Agent Plugins 包的 Skill 是其根目录的直接子目录。
  • 包拥有的 MCP 服务器(插件的服务器):.mcp.json(或清单的 mcpServers)或 Agent Plugins 的 mcp.json,从不写入 mcp.toml,由 [plugins."p@m".mcpServers] 限制,与用户的服务器在同一套监管下运行。同名时用户的服务器优先,其次是键的顺序中第一个包;让出的服务器记为该包的问题。
  • 钩子来源,排在用户和项目之后(HookSource::Plugin),凭定义和包的内容哈希被信任,每次运行前再次检查(插件的钩子)。与 Codex 相同,Agent Plugins 包的钩子从不运行。
  • 角色(packages/roles.rs):清单的 agents(没有时是 agents/)。本项目格式的包中是角色文件,由配置的角色读取器读取;Claude Code 包中是代理文件,由 packages crate 读取(read_claude_agents:frontmatter 逐键读取,Claude 工具名按固定对照表映射,一个不含任何我们工具的 tools 不允许任何工具,disallowedTools 作为禁止列表,permissionMode 作为权限模式上限,plan 还禁止计划模式去掉的写入类工具);Codex、Cursor 或 Agent Plugins 包没有角色。每个角色以 <插件>:<角色> 命名,插件部分取自 id 中的插件名;同一插件名的两个包中,id 在前的保留它,另一个包的角色记为它的问题。角色目录把它们排在内置角色之上、用户的角色之下,和所有角色一样经过合并和收窄(插件的角色);读取时略去的内容是该包的问题。

读不了的包,或包中读不了的组件,记为该包的问题;其他包照常加载。这一组包在构建 Agent 时加载(MCP 服务器随启动连接),并由 reload_packages 重新加载:门面在每次写入设置和 mcp.toml 之后运行它,每个生命周期调用也在变更后运行它;它替换 Skill 根目录和钩子来源,只连接或断开有变化的 MCP 服务器,并带着包的角色重建角色目录,无需重启。packages() 列出每个已安装的包及其版本、格式、启用状态、内容和问题(AgentPackageStatus)。

模型通过 plugins 行得知启用的包:当某个包向本轮的 Skill 目录贡献 Skill 或贡献 MCP 服务器时,Capabilities 槽位带有一个"可用插件"段落(Codex 的 PluginCapabilitySummary:显示名称、单行且至多 1,024 个字符的描述、Skill 前缀、MCP 服务器名称);没有这样的包就没有该段落,所以没有包的 Agent 的请求不变。该行拥有这份摘要并挂载访客宿主(代码插件),所以关闭它会隐藏摘要并停止所有访客,而内容仍经由 skills、mcp 和 hooks 行流入。安全模式下这些包会被列出,但都不加载。

生命周期由门面负责(参照 Codex 的插件管理器),并且只通过 Agent 打开的那一个包存储进行,因为再打开一个会清扫它的暂存区:

  • 安装(install_package,来自已添加的市场或一个目录;没有指定市场时归入 local)通过存储安装,写入 [plugins."<id>"] enabled = true(合并进用户的文件,所以条目中的 mcpServers 保留),重新加载,并返回这个包和它需要的东西:需要信任的钩子(对代码包还有需要授予的权限;内容包没有)。
  • 卸载删除包及其 [plugins] 条目;除非清除,它的数据目录会保留。启用和停用写入 enabled;所属市场被关闭的包不能启用。更新从它的市场(按市场当前的内容)或它的目录重新安装。重试重新加载,并以空的重启窗口再次启动失败的访客。
  • 市场(marketplaces、add_marketplace、upgrade_marketplace、remove_marketplace)只包括用户添加的那些([marketplaces]):不会从主目录或仓库中发现市场。每个调用写入它的记录并重新加载。
  • package_changed:对包的每个生命周期调用都会在重新加载之后告诉插件事件接收器(AgentPluginEventSink::package_changed)发生了什么:installed、removed、enabled、disabled、updated,或 failed 以及原因。它不在 exec --json 的事件流中,那里的事件属于会话;exec 回合期间没有任何东西改变这些包。

plugins 命令和 /plugins(终端界面)是这些调用的界面;mcp list 和 /mcp verbose 显示包的服务器并标明所属包,/warnings 显示包的问题和失败的访客。使用方法见插件。

代码插件:访客宿主

本项目格式的包还可以带代码:清单的 runtime 指明一个讲 Kardia 访客协议(kardia-guest/2,或版本 1)的程序,它在进程外运行,所以它的崩溃、中止或挂起都到不了 Agent 的进程;或者指明一个讲访客 ABI 的 WebAssembly 模块,它在 Agent 的进程内、在 wasmtime 中运行,受燃料、时间和内存的限制。访客宿主(hanafubuki-agent-plugin-packages)运行这两种访客,由 plugins 行挂载为其子 fiber(plugin-guests)。

  • 一棵 kardia-loader 子树。 访客宿主是一个 kardia-loader,它的树中每个代码包一个条目:条目的 id 就是包的 id,它的插件以启动所依赖的一切命名(版本、记录的内容哈希、命令、请求与授予的权限,以及已链接包的目录改动次数),任何一项变化都会重新启动它:新名字就是升级路径,kardia-loader 对此的处理是释放条目的 fiber 并启动新的插件。每次重新加载之后,门面把代码包(无论启用与否)交给访客宿主,访客宿主用一次组更新把它们应用到树上:安装时创建条目,包关闭时禁用条目,卸载时移除条目。树的 TreeBackend 把加载器自己做出的变更(自行释放的插件被写回为关闭)通过门面提供的设置端口写入 [plugins],交给门面的阻塞写入者排队,并且只在值不同时写入;组更新是设置的镜像,不写回任何东西。

  • 每个包版本一个解析器条目。 条目的名字解析为一个缓存的 kardia-hmr ProcessGuest,它的元数据来自清单(name,以及每个访客都在自己的领域中提供的服务 plugin),所以解析不会启动任何东西;访客启动时必须声明相同的元数据,否则启动失败。模块的条目在第一次解析时解析为一个 kardia-hmr WasmGuest:在阻塞线程池上,模块在它的限制所对应的引擎上编译(限制相同的访客共享一个引擎及其 epoch 线程),元数据同样来自清单,所以生成它不实例化任何东西;每个实例启动时都声明相同的元数据,否则启动失败;之后这个插件就属于这个名字。它的插件名为 guest:<插件>@<市场>,使访客在注册表和日志中区别于内置行。

  • 进程属于 Agent。 程序访客的启动器先预留所有者,再通过实例的 ExecutorManager 以预留的管道执行器启动进程,并把管道交给访客桥;访客桥只通过收据结束进程,确认进程结束后才释放执行器。进程属于实例的所有者组,记录在 process-groups.json 中,在实例停止时被清扫,在下次启动时被回收(进程)。

  • 启动需要什么。 对程序,清单请求的权限必须已授予(install.json 保存授权,已链接的包则是 linked.json,由 grant_package_permissions 记录);包的内容哈希必须仍是安装时记录的那个(每次启动进程时检查,模块则在编译前检查一次)。等待授权的访客处于 blocked;内容变化的包启动失败。已链接的包没有要保持的哈希:它按目录当前的样子启动,授权和沙箱配置与已安装的包相同。

  • 已链接的包跟随它的目录。 访客宿主运行期间,它在实例的受控 worker 组的一个线程上监视每个启用的已链接包(有代码或没有)的目录。某个目录改动并随后安静 500 毫秒,该包的修订号加一,访客宿主发出信号;plugins 行随即在后台运行门面对包的重新加载,也就是 reload_packages 运行的那一个,所以这个包的 Skill、MCP 服务器、钩子和角色被重新读取,它的访客以新的名字重新启动(插件访客)。

  • 模块什么也访问不到。 它能导入的只有访客 ABI 的宿主函数(view 和 invoke 与程序一样受限),所以它没有文件、网络、时钟或环境变量:清单的 permissions 被忽略并记为问题,它不需要授权(AgentPackageGuest::ungranted 为 None)也不需要沙箱,在所有平台上都能启动。它的限制(runtime.limits)约束每个导出:燃料、通过 epoch 中断实现的时间(默认为它最长的调用可能用的时间,每次调用自己的期限也同样生效)以及线性内存(默认 256 MiB)。

  • 插件配置。 进程以空环境启动,只带被授予的 env 变量、PLUGIN_ROOT 和 PLUGIN_DATA(在 Windows 上还有 SystemRoot),工作目录是它的数据目录,并受沙箱的插件配置(SandboxPolicy::Plugin)约束:它读取平台的系统目录和它的包,只写它的数据目录,按授权访问工作区(none、read 或 write),只有被授权时才能使用网络。Linux(bubblewrap 或旧 Landlock)和 macOS(Seatbelt)强制限制读取;Windows 的受限令牌不能拒绝读取,所以在那里访客能读它的用户能读的一切,workspace: "none" 不被强制。访客使用平台的沙箱,无论 [windows] sandbox 怎样设置(该设置管的是模型的命令);没有沙箱的地方(没有调用 helper_dispatch 的程序、无法初始化沙箱的宿主),访客不会启动。

  • 它的状态属于访客宿主:starting、running、restarting、failed、stopped 或 blocked,附带原因、最后一次退出报告(自行退出、被杀死或被释放,原因与状态)以及 stderr 的最后 16 KiB。packages() 连同请求与授予的权限一起显示它(AgentPackageStatus.guest)。

  • 重启。 运行之后失败的访客(进程退出或被杀死、调用超过期限、违反协议或发送超过 4 MiB 的帧;模块触发陷阱、用尽燃料或时间,或要把内存增长到超过限制,GuestHost::call 从调用的错误中识别这些情况)使它的 fiber 失败,即 Kardia 的 Failed;访客宿主随后按重启策略(2 秒、10 秒、30 秒之后,10 分钟内三次)通过更新失败的 fiber 来重启它,这不写任何配置。窗口内的第四次故障使它保持 failed,直到 retry_package。启动失败不会被重启。因故障停止不等于关闭:这些都不会写入 [plugins]。

  • 通过代理贡献。 访客贡献的是它的清单声明的东西(contributes),从不是访客自己说的:它的 fiber 变为活动时,访客宿主把代理注册为该 fiber 的副作用(一个工具源、每个上下文段 kind 一个上下文贡献者和渲染器、一个提示渲染器、一个工具生命周期钩子和一个继续钩子、一个观察者),所以它们随每次失败、停止或重启撤销,并随下一次启动回来。每个代理在比内核自身更短的期限内调用访客 plugin 服务的一个方法,所以挂起的访客会被终止并重启,而内核仍能及时走该调用的错误路径:一个工具错误、一个被略去的段或片段、一个没有发言权的钩子、一个被丢弃的事件。由于一个步骤准备好的值按类型区分,提示片段统一经过访客宿主的一个贡献者。审批规则和轮次准入不对访客开放。规则与协议见插件规则。

  • 访客能访问什么,以及它的设置。 在每个访客的 loader 条目旁边,一个宿主服务条目(<id>#host)在两者按标签共享的 realm 中提供 workspace 和 settings,访客的条目声明了它们;受检访问找不到访客能 view 或 invoke 的其他东西,kardia-hmr 拒绝访客提供 plugin 以外的任何服务(这个拒绝是访客自己的错误)。它的设置 [plugins."<id>"].settings 是两个条目的配置,所以 set_package_settings(按清单的 configSchema 校验)会以新设置重启它。

  • 编写代码插件。 plugins new 生成一个代码插件,plugins validate 像访客宿主运行它那样检查它(加 --run 时在临时主目录中启动它),plugins dev 在每次改动后重新安装它,plugins link 链接它的目录,运行中的 Agent 跟随这个目录;包、清单、SDK 和线路格式见编写插件。

MCP

McpManager(hanafubuki-agent-mcp)拥有连接(stdio 与 Streamable HTTP 传输、OAuth、工具目录、存活检测、重连、租约);mcp 插件只是它之上的工具源加三个资源工具。每个步骤,工具源绑定已连接服务器的目录(作为计划租约),为每个目录条目提供一个工具。

  • 目录逐个工具构建,一个坏工具只损失它自己;名字按字符清理为 [A-Za-z0-9_-]。
  • 注解是提示,不是授权。 readOnlyHint 且不带 destructiveHint: true 的工具是 ConcurrentRead、ReadOnly(计划模式可用);其余都是 Exclusive、Mutating。审批只读服务器或工具的策略和破坏性提示,缺失的提示视为破坏性的。
  • 存活与重连。 服务器一侧结束连接时,服务器变为 Failed 并附原因,它的条目退役(工具离开下一个计划),管理器按重启策略用打开时的配置和密钥重新连接它。
  • 连接就是目录修订。 步骤保留它规划时的连接;过期的调用只能是因为连接已关闭,这时返回 McpError::CatalogChanged,不请求审批,模型重新搜索或重试。用计数器会让被用户刷新退役、但仍在运行的连接上的调用失败,破坏“步骤保留它的连接”的保证。
  • 每台服务器一个故障所有者,而不是每台服务器一个子 fiber。 命名的子 fiber 会以宿主故障处理器不认识的名字出故障,只被记录而不被停止,于是每次调用都再 panic 一次;未命名的子 fiber 以 mcp 的名义出故障,停止整个插件。在调用处捕获就能隔离到服务器,而所有服务器本来就共享一个进程。

模型 API

hanafubuki-agent-model-api 实现三种协议:Responses、Chat Completions 和 Anthropic Messages,包括编码、流式解码、工具降级和模型列表。它用 ModelRouteKey(其中端点为 ModelEndpointKey)命名 Agent 访问的模型,端点取规范化 base URL 的 SHA-256 而不是 URL 本身,因为键会写入日志和磁盘,而 base URL 的查询串里可能带有凭据。它不知道任何插件和任何上下文段类型,也不依赖插件 API。Provider 的流是外部输入,容错解码:空的工具参数是 {};无法解析的是 {} 加 argument_error;缺失的用量计数是 0;没有结束原因的流以未知的 end_turn 结束;Responses 的 response.incomplete 保留已完成的条目和已流出的文本,只有什么都没产生时才失败。每种协议都发送推理强度,各用自己的字段(responses/encode.rs、chat_completions/reasoning.rs、anthropic_messages/thinking.rs;对照表见 Provider 与模型);Anthropic 用自适应思考还是预算,按模型 ID 判断,因为两类模型互相拒绝对方的形式。线路正文只按内容日志规则在 trace 级别、截断后记录。

提供商打开事件流后,如果在首个输出项之前返回限流错误,Agent 会按会话的流重试设置重发同一请求。推理、文本或工具输出项一旦开始,收到限流错误就结束该轮,以免重复输出。

终端界面与命令行

  • hanafubuki-agent-cli 是 hanafubuki-agent 二进制,位于门面之上,不依赖工作区的其他东西。每个命令从全局标志组合运行时,安装 panic hook 和日志文件;读写配置的命令(config、providers list、roles、离线的 doctor)从不启动 Agent,所以它们可以在 Agent 运行时使用;roles 和 doctor 用包存储的只读列举(PackageStore::read_installed:不清理暂存区、不隔离、不写入、不取锁)读取已安装插件的角色。exec 自带 sink:轮次的 AgentEventSink 和槽位的状态 sink 送入命令线程读取的同一个通道,所以它打印的事件就是门面自己的(--json 原样序列化 AgentEvent)。见命令行参考。
  • hanafubuki-agent-tui 是移植到门面之上的 Codex 终端界面(rust-v0.93.0),使用上游的 ratatui 0.30 与 crossterm 0.29(Codex 用 git 分支给它们打补丁,crates.io 不接受)。终端底部是内联视口,转录写入终端自己的回滚区。一个适配器(agent_bridge)把轮次的 AgentEvent 映射为聊天组件显示的内容,把界面的请求映射到门面;一个循环、一个通道:读终端的线程和 Agent 的 sink 都送到同一个通道,会等待的门面调用作为 Agent 运行时的任务运行并在通道上回报,所以循环从不阻塞在 Agent 上。见终端界面。

TUI 工作区分别保存选中的 agent 和旁路对话(app/workspace/child.rs、routing.rs)。获得焦点的对话由 App 持有,另一个面板及被选中子 agent 的主会话各自保留聊天组件、桥接层、草稿与输出流。事件按所属对话路由,所有活动对话都会收到提交时钟和 Agent 状态更新。切换 agent 不关闭旁路面板;Ctrl+/ 只切换焦点,不改变所选 agent。

终端界面的移植改动

新会话的装饰参照 Codex 空状态的行为,使用原创 Hana 素材与渲染代码(welcome)。每个聊天组件持有自己的显示资格和淡入淡出时钟,开始回合后禁用,直到打开新的空对话。Fullscreen 和 Scrollback 的绘制器只使用输入框上方的空白区域,装饰不会成为历史单元格。Scrollback 在退出时先移除它,再写出尾部;装饰临时占用的高度也不会计入运行中回合的视口高度下限。循环姿势来自生成的彩色图集,源图的归一化变形与 Lanczos 采样保持放平的手不动,并适应不同终端大小。见欢迎形象素材。

crates/tui 中派生自 Codex 的文件都带有说明这一点的标记行(许可证)。移植对 Codex 的终端界面做了这些改动:

  • 上游的 ratatui 与 crossterm。 Codex 用 git 分支给 ratatui 和 crossterm 打补丁,crates.io 不接受;移植使用上游的 ratatui 0.30(它的 scrolling-regions 特性让视口增长),通过 ratatui 的重新导出使用 crossterm 0.29,并去掉了终端调色板查询,改用 Codex 在没有它时回退到的固定主题。
  • 在门面之上。 agent_bridge 代替 Codex 的 ConversationManager 与 CodexConversation。工具事件既不带参数也不带输出:调用的标题取 tool_started 的主题,tool_completed 到达后,桥接层在 Agent 运行时的阻塞线程上向门面询问调用显示的内容(tool_display,来自其工具的呈现器),由它完成该条目;重新打开的会话中的调用按已读到的那一页呈现(present_tool_call)。apply_patch 调用的 diff 是 Agent 自己的解析器对补丁的读取,只有补丁新增的文件知道行号,所以只有这些行带行号;read_file 的行按其结果的 startLine 编号。命令的颜色随它的显示而来(Command.styled),由执行服务从输出的 SGR 序列读出,放在模型读到的纯文本旁边,实时输出中则在伪终端各行的终端文本里;Codex 把转义序列保留在它的 exec 单元格中并在那里解析(ansi-to-tui),Agent 提交的纯文本输出做不到这一点。斜杠命令映射到门面的调用;/diff 在第一个工作区根目录运行 git diff,这是界面自己的短生命进程,不是 Agent 的工具调用,所以不在 Agent 的进程所有权之内。
  • 提及。 统一的 @ 和 $ 选择器移植 Codex 57a808a392 的分类标签、匹配、条目布局、光标边界和完整引用行为,使用本项目的插件、Skill、MCP 服务器和任务目录。异步 file_search 模块用 nucleo 索引文件和目录,遵守忽略规则,并通过 pattern matcher 重新取得展示结果的分数。引用以带目标类型的链接保存在用户文本中;threads 插件注册 read_thread,分页读取任务当前的对话。终端沿用已有的回退配色;OpenAI 账户 Apps 由本项目的 MCP 目录承接。
  • 终端的恢复。 每次返回(一个 drop guard)和结束进程的 panic 都会恢复终端:界面的 hook 先恢复终端,再运行 Agent 的 hook。被隔离的 panic 让界面继续运行。
  • 斜杠命令是隔离的模块。 Codex 中平铺的 SlashCommand match 变成一张表(commands):每个命令的规格(名字、别名、说明、是否接受行内参数、回合中能否运行、是否需要会话)和它的分派,命令列表、/名字 参数 的查找和分派都来自这张表。每次分派,以及命令推入的每个视图(按键处理和绘制),都在 hanafubuki_agent::panic::catch_panic 中运行:panic 的命令失去它的视图,在本次运行的剩余时间内关闭,对话中显示一条错误,会话、输入框和其他命令照常工作。聊天本身(输入框、转录、流式输出)不是模块,那里的 panic 仍会结束进程。
  • 设置中心。 /config 全屏打开设置目录,按 Codex 的 /config 呈现设置的方式(标签页、标签 · 值 · 说明的行、跨标签页搜索、改动即保存),不为任何一项设置单独写代码:它是一个页面栈,包括标签页、集合的记录、以表单打开的记录或一起保存的一组设置、选项、列表,以及通用行无法表达的页面(主题、状态栏、标题、键位、预设、插件浏览器、钩子审查、记忆存储,以及记录的页面:Provider 的模型、MCP 服务器的登录),这些页面都是某个命令的界面,只显示在设置中心内:/theme、/mcp、/providers 等设置命令在设置中心打开它们。它的写入和动作在界面的事件循环之外进行,一次一个,每次的回复都带回重新读取的目录;写入被 profile、项目文件或 -c 覆盖时会说明。
  • Agent 工作时发送的消息。 Codex 的输入队列(Enter 引导回合、Tab 排队、Esc 中断并发送等待中的补充消息、Shift+Left 编辑最后一条排队的消息)放在聊天中,每个对话一个,建立在内核的 steering 之上:聊天一次只发送一条补充消息,让回合按顺序接收;每条消息的文本一直保留,直到回合的 SteeringConsumed 覆盖它被接受时的序号;回合结束后,要等每条补充消息都得到答复才处理队列,因为内核会丢弃被取消或失败的回合还没读到的内容,并拒收晚到的补充消息。用 Tab 输入的命令立即执行而不排队,Shift+Left 把消息放在草稿之前,而不是覆盖草稿。
  • 需要时才有会话。 Codex 启动时就开始一个线程;这里的桥在第一条消息或需要会话的命令创建会话之前不持有会话(期间提出的请求等它创建好),/new 回到没有会话的状态。创建失败(没有默认 Provider)是对话中的一条错误,而不是退出。
  • 语法高亮和状态显示。 render/highlight 保留 Codex 的 syntect 和 two-face 组合(Oniguruma 语法、32 个内置主题、自定义 .tmTheme 文件),但没有 Codex 自己的以模型命名的主题;由于不查询终端调色板,默认主题是 two-face 的 ansi,它用终端的调色板着色,取代 Codex 根据查询到的背景在 Catppuccin Mocha 和 Latte 之间的选择。主题选择器在列表旁边或下方的示例差异上预览。状态栏和标题去掉了 Codex 的账号、速率限制、费用和版本项目,增加了权限模式和目标;会话的值在事件改变它们时从门面的会话快照读取,Git 分支从 .git/HEAD 读取,而不是启动 git 进程。Codex 不恢复它最后设置的终端标题;这里把标题压入终端的标题栈,退出时弹出。
  • 工具输出的格式。 工具返回的 JSON 文本折叠时按 Codex 压缩 MCP 结果的方式压缩,展开时缩进,而 Codex 展开时按原样显示:计划要求缩进的 JSON。Codex 在界面中投影 MCP 结果(mcp_result.rs);这里由回退显示完成(AgentToolDisplay::Content),所以无论宿主是谁,媒体到达界面时都只有类型和大小,从不带数据。Codex 根据变更的统一差异为补丁的各行编号;这里由补丁应用器报告每一块应用到的位置,放在结果旁边而不在结果中(AgentToolDisplayMetadata::patch_hunk_starts),所以模型读到的与以前相同。差异的配色是 Codex 的;由于不查询终端的调色板(见上文),主题是深色的。
  • Markdown。 markdown_render 采用 Codex 57a808a392 的渲染器来处理管道表格(列宽分配、键值记录回退、把被表格吞掉的文字放到表格之后)、回答中 ```md 围栏的展开、任务列表、多行列表项之后的空行、网页链接和本地链接的显示,数学公式以及 Mermaid 图表,并由 tui.rendering.tables、tui.rendering.lists、tui.rendering.math 和 tui.rendering.mermaid 控制。它输出的行带着各自的网页链接(Codex 的超链接标注),没有 Codex 的复制来源和行内指令,正文使用固定样式而不是语法主题的样式(表头使用主题的类型颜色)。这里的 pulldown-cmark 是 0.13 版,它会给较短的行补上位于文字之后的空单元格;这些单元格会被去掉,所以表格后没有管道符的一行仍是文字,与 Codex 使用的 0.10 版相同。
  • 超链接与换行。 terminal_hyperlinks/ 采用 Codex 57a808a392 的实现:每一行在文字旁边记下每个网页目标覆盖的列(HyperlinkLine),经过渲染器、表格、流式输出、回答和计划的单元格、对话记录的行以及滚动历史的写入;OSC 8 序列只在文字到达终端的地方加上,所以从不计入宽度。标签后是否显示地址,由启动时识别出的终端决定(terminal_detection.rs,即 Codex codex-terminal-detection 中识别终端的部分,重新写入时的行数上限也读取它)。wrapping/ 是 Codex 能识别 URL 的换行,取代了旧版 Codex 基于 textwrap 的换行:像 URL 的词元保持完整,组合字形和半角浊音符按绘制时的宽度计算。与 Codex 的不同之处:OSC 8 与 Codex 一样写给所有终端,只有地址是否显示取决于终端;链接在每次光标移动时关闭,而 Codex 的帧会让链接跨行保持打开;比所在行还宽的 URL 在对话记录排版的地方截断,Scrollback 中也是如此,而 Codex 交给终端自动换行,尾部和重新写入的行数无法跟上它;换行时行的样式仍然优先于其中片段的样式,与滚动历史的写入合并它们的方式相同;思考中的链接显示为文字;没有受信任的文件链接(Codex 生成的可视化和工作区产物),输入框、弹出框和工具输出中也没有超链接。
  • 数学公式。 markdown_render/math/ 采用 Codex 57a808a392 的实现:一个遮蔽器在 Markdown 解析器读取源码之前找出 $…$、\(…\)、$$…$$ 和 \[…\](它先自己解析一遍,标出代码、HTML、链接和链接定义,其中的美元符号保持原样),在解析器读取的副本中把每个公式换成一串 $,再把公式的渲染结果或源码放回事件之中;以及 Codex 手写的、把一小部分 TeX 转换为 Unicode 的转换器,连同它的上限(32 层、16 行、256 列、每个公式 4 KiB)。没有加入新的 crate,pulldown-cmark 自己的数学公式(ENABLE_MATH)保持关闭,所以 Codex 的测试可以原样移植(D20)。与 Codex 不同之处:遮蔽器把每个公式作为 InlineMath 事件交给写入器,按文字显示,从不扫描其中的网页地址,而 Codex 把它作为会被扫描的文字(这里公式从不带链接);Codex 的复制来源和原始模式流的预览没有移植。tui.rendering.math 关闭时遮蔽器照样运行,每个公式保留源码,与 Codex 相同。
  • Mermaid。 mermaid/ 是 Codex 57a808a392 的 codex-mermaid crate,在这里作为终端界面的一个模块而不是单独的 crate,因为没有别的地方绘制图表(D22):它对流程图、时序图、状态图、类图和实体关系图子集的严格解析器,它的布局(节点按图的方向依次排列,每条边有自己的通道和端点,交叉处标为 ╪),它的上限(16 KiB 源码、16 个节点、24 条边、16 个成员、8 个参与者、64 个事件、4 层嵌套片段、每行标签 40 列、每张图 65,536 个单元格),以及对其他一切的拒绝,从不输出不完整的图。它是在 crate 已在使用的 unicode-width 之上手写的,没有加入依赖。markdown_render/mermaid.rs 是 Codex 的调用方:有结束围栏的 ```mermaid 围栏(pulldown-cmark 在输入结束处也会结束一个块)按宽度减去列表或引用前缀绘制,渲染没有宽度时按 120 列,方框使用主题的类型颜色,线条使用注释颜色,各行作为代码写入,所以既不换行,也不扫描其中的地址;无法绘制的围栏显示为一行暗色说明和它的代码。为了让函数不超过模块大小的上限,移植把 Codex 的时序图渲染拆成解析和绘制两部分,把类图与实体关系图的关系运算符从解析器中拆出,并为 2021 版改写了 let 链。流式输出期间,Mermaid 围栏是最后一个块中的可变围栏(mutable_fence_start),所以它的代码从不提交,它的图表(调整大小可能让它变回代码)在后面出现别的块之前一直属于尾部;打开的顶层围栏仍走增量的代码围栏路径,与 Codex 相同,所以很长的围栏也以线性时间流式输出。Codex 的复制来源和原始模式流部分没有移植。tui.rendering.mermaid 关闭时,围栏就是原来的代码块。
  • 流式输出。 流式输出的回答或计划采用 Codex 57a808a392 的两段式结构(streaming/):源码增量渲染(最后一个顶层块之前的块保留不变,打开的代码围栏逐行高亮),渲染出的行分为稳定部分和可变尾部;稳定部分按帧的节奏由提交节拍提交,积压时按 Codex 的追赶方式一次提交;可变尾部(从表头开始的表格、```md 或 ```mermaid 围栏、仍未闭合的独立公式、单独的列表标记、以本地链接结尾的一行)实时显示在稳定部分之后,后面是仍在到达的那一行的预览。Codex 把尾部显示在活动单元格的位置;这里它是对话中的一个实时条目(StreamTailCell),每次变化以一次更新到达应用(提交的行和尾部的新内容一起),所以不会有一帧把某行显示两次或漏掉。Codex 只在关闭表格时把 ```md 围栏保留为可变;这里开启表格时它在闭合前也保持可变,所以围栏中的文档不会先作为代码提交、再被展开。与最终渲染不同的已提交行(setext 下划线、后到的引用定义)会要求 Scrollback 重新写入,与 Codex 的 needs_scrollback_reflow 相同。Codex 的原始模式流、回放节拍、行内可视化和后续指令不在其中(这里原始输出是视图的显示方式)。
  • 重新排版自己的回答。 与 Codex 相同,结束的回答或计划是一个保存其 Markdown、按显示宽度渲染的单元格,它取代流的各个单元格(合并);调整大小后,Scrollback 的对话从单元格重新写入:清除终端的滚动历史和屏幕,在 75 ms 的静止期之后,按各终端的行数上限重新写入尾部之前的对话,被调整大小打断的流结束时再写入一次。上限由环境变量决定(TERM_PROGRAM、WT_SESSION 以及 Codex 的检测读取的其他变量,按它的顺序),没有设置项;Codex 的上限可以配置,也用于限制恢复的会话首次写入的行数。重新写入时每个条目按 Scrollback 的尾部写入它的方式写入,所以展开的条目仍然展开,尾部留在视口中。会重新排版条目的视图(Fullscreen、对话记录)对结束的回答中的列表使用统一间距,即 Codex 的 ListSpacing::Uniform;滚动历史保持流式输出时的间距。
  • 没有移植的: 转录分页器中的实时尾部与回溯、自定义提示、状态卡中的账号与速率限制,以及状态栏和标题设置界面中的搜索框。

设计选择

以下是读者可能想撤销、但有理由的选择:

  • 没有流式分派(见上文)。
  • 每台 MCP 服务器一个故障所有者,连接就是目录修订(见 MCP)。
  • Skill 正文作为 SkillContext,而不是工具输出。 压缩两者都不保留,所以不由它决定;$mention 路径没有工具输出,而 SkillContext 是每轮一次检查读取的类型化记录,所以无论 Skill 怎样被选中,正文只有一种形式。
  • MCP 工具总是 PollutesContribution,只读的也是:只读工具的输出仍是外部内容,与网页抓取一样。
  • 插件宿主关闭 module_faults、开启自动重启。 那个标志是关于应用的模块故障 sink 的,插件故障从不使用它,而是通过 PluginFaults 到达 Agent 的宿主。
  • 渲染器是数据,注册拒绝、规划改名(见上文)。
  • 轮次限制对模型不可见。 历史中没有失败轮次原因的条目;用户读轮次的错误消息,没有什么需要模型看到它。
  • 沙箱改写 argv;ExecutorManager 保留进程所有权。 回合冻结 SandboxSettings,执行层在启动受管理辅助进程前包装已批准的命令。Linux 使用内置 bubblewrap 命名空间和内部 seccomp 辅助进程,并提供显式旧 Landlock 选项。macOS 使用 /usr/bin/sandbox-exec,所有可写根授权之后统一拒绝元数据写入,嵌套 Seatbelt 会报告不可用。Windows 重新执行辅助进程:非提升模式限制当前令牌;提升模式登录已初始化的标准账户,连接私有标准输入输出管道,再以受限令牌和独立桌面启动命令。关闭即终止的作业保留子进程所有权。UAC 仅用于初始化账户和持久 WFP 网络规则,命令不会提升权限。无法隔离时拒绝执行(权限)。 限制 SID 列表不包含可复用的账户 SID。在 x86_64 上,提升辅助进程通过 Windows 调试事件跟踪其作业拥有的进程,在已加载 MSYS 运行时初始化前拦截 IPC ACL 导入函数,使其使用本次命令的新登录会话 SID。已安装的运行时不会被修改,文件系统检查仍使用每个根目录的能力 SID。当前用户无法打开或修改其 ACL 的路径保持原样,而不是拒绝命令,因此启动时的各项授权(运行器、用户配置目录、工作目录和每个可写根目录)都容忍属于其他所有者的 DACL;对已成功打开的 DACL 的调用失败仍然拒绝执行。参见 MSYS 兼容及剩余限制。
  • hierarchical 是内置策略,不是插件。 做成插件需要一个内核每次请求都调用的新注册表,于是每个请求都依赖插件可以替换的代码(组合规则 1),而且契约无法引用模型 API 的类型。所以算法是一个纯 crate(没有 I/O、没有异步,生产代码不 panic,与插件一样受检查),内核在 catch_panic 下调用它:那里的失败只损失一个请求的投影或一次工具调用,不会损失会话,这正是插件的隔离本来能给的。
  • 没有做的: 代码模式(用 JS 调用所有工具)、跨会话的 MCP 连接池、无论目录大小都延迟所有 MCP 工具、MCP 的 prompts/subscriptions/sampling/roots、Skill 注册的工具或 allowed-tools 的执行、从 Agent 单独安装一个 Skill(Skill 随携带它的插件一起安装,或者手动复制到某个 Skill 根目录),以及进程外的 Agent。

与 Codex(codex-rs)相比,Agent 的机制都对照过它:

方面Codexhanafubuki-agent
工具快照每步一个工具路由器每步一个工具计划,带计划租约
名字{namespace, name},只做查找相同;每个请求一张线路名表,按协议适配
延迟工具tool_search;选择保存在历史中search_tools 和原生 tool_search,通过 ToolSelection 条目直到压缩
Schema精简的关键字集合,从不 strict协议接受时发送完整 schema,否则可移植的,从不 strict
审批执行之前决定等待时在门外;AllowForSession
工具超时注册表层面没有按描述符,否则轮次的空闲超时
MCP 存活只对一个内置服务器重连每台服务器:Failed,然后有界重连
AGENTS.md每步读取;错过项目内的就地编辑每个轮次读取并按摘要比较;用户与项目文件
上下文段类型化的世界状态类型化的段,渲染器与槽位属于插件
压缩本地、remote 与 remote v2,在线或异步;重新渲染初始上下文本地摘要、Responses compact 与 v2,在线或在后台(background,变基安装);重新渲染每个段;有上限的重试
记忆两个阶段、租约、引用相同的设计,加上先判断资格再限量和两阶段退避
沙箱bubblewrap/seccomp、Seatbelt、受限令牌和提升初始化内置 bubblewrap/seccomp 及旧 Landlock、Seatbelt、Windows 受限令牌及账户/WFP 初始化;审批后可在沙箱外执行

已知的限制

  • 文件工具的策略根目录在构建 Agent 时固定;只有 Skill 根目录和上下文段按每次读取跟随工作区。
  • 会话的窗口只在列表、轮次开始和回答提交时重新解析:模型元数据完全不再知道的报告的窗口会一直保留,直到再次选择会话的模型。
  • MCP 重连复用打开连接时的密钥,所以过期的 OAuth 令牌会让重连失败,直到用户手动连接。
  • Skill 监视器只监视启动时存在的根目录;之后出现的根目录(包括之后启用的包的根目录)依靠读取时的标记。
  • 手动编辑 [plugins] 在下次启动或重新加载时生效;Agent 只在它自己写入设置之后重新加载包。
  • 在 Windows 上,程序访客的沙箱不限制读取。
  • WebAssembly 访客的实例失败只能由调用者等到结果的调用识别:在调用者已放弃的调用(被取消的轮次)中停止的访客,由它的下一次调用使其失败,而那次调用本身也会失败。每组在用的限制保留一个引擎,以及一个每 10 毫秒推进一次其 epoch 的线程。
  • 内置的上下文窗口只覆盖公开了上限的模型系列(GPT、o 系列、Claude、Gemini 2.5);其他模型需要 Provider 的列表或设置才能自动压缩。
  • 沙箱原生测试在 Linux、Windows 和 macOS 上运行。test/sandbox-platforms 分支的专用 Sandbox platforms 工作流只检查沙箱 crate,不等同于完整工作区 CI。
  • 在 Linux 之外未验证:notify 监视器的 macOS 与 Windows 后端、Skill 目录中显示的 Windows 路径、Windows 上 MCP stdio 的退出原因和已退出子进程的释放,以及 Windows 上记忆制品的安装重命名。

Web 插件 将 dsh-free-search v0.9.50(6ab5168)的引擎路由与冷却、原生适配器、抓取和有界研究移植到 web-search 领域。HTTP 与提取留在领域 crate;类型化 LocalWebRunner 端口将可选 CLI/浏览器进程交给 plugin-web,由它依赖 process 并在调用前核对匹配的沙箱提升审批。门面传入其所属执行器和数据目录缓存位置。每个服务实例独立管理密钥轮换、并发门、缓存和统计;持久化冷却使用密钥散列标识,无法读取的缓存文件保持原样。

浏览器流量通过有界的本地 HTTP/CONNECT 代理校验并固定公开目标,覆盖重定向与子资源连接。本地辅助程序使用独立临时目录及精确执行器凭据。研究的重试和各轮共享实际请求与提取预算,到时保留已完成证据。模型可见工具变化由 Agent 请求快照覆盖;协议替身测试不等于提供方在线或 Windows/macOS 实机验收。

TUI 维护操作由 CLI 通过 TuiMaintenance 提供,执行期间交还终端,完成后恢复;TUI 不依赖 update crate。Skills、钩子定义、角色源文件、显式配置层和沙箱初始化通过设置集合接入;插件定义的设置仍使用所属插件的 schema,并隐藏密钥值。

手动检查更新成功后会刷新自动检查使用的同一份缓存,并通过 TuiUpdateNotifier 通知当前 TUI。会话信息框是可更新的历史条目,更新提示会原地刷新它,暂停显示的对话也会同步。全屏模式依据条目修订号重新排版;回滚模式调度对话重绘,让已经输出的会话信息框也能刷新。

Advisor 证据与模型请求

咨询按固定修订号读取会话记录,配对工具调用及结果,应用披露策略,随后向选定提供商发送不带工具的请求。回复标明实际回答的模型,以及提供商返回的用量。适合回退的故障可尝试一次已配置的备用模型。取消会终止咨询。追问在短时间内复用内存中的已授权证据,受会话、工作区、信任和设置约束。

Git、具名文件、项目规则和图像分别控制。可选 Scout 将带编号的文本预览发给 Executor,在本地按返回的编号选择证据。选择无效时使用原有证据。Scout 的用量独立报告,图像像素只随最终咨询发给支持图片的 Advisor。

收到新的用户消息或引导消息后,上一条建议的追问资格失效。咨询与追问之间执行工具调用仍可沿用原建议。指定附件超过字节预算或图像数量限制时,证据会标明省略的文件,咨询继续处理其余附件。已跟踪文件的一次性授权在首个 Scout 或 Advisor 请求交给模型传输层时消耗。本地准备失败后,仍可更正请求并重试。

读取 Advisor 配置时,审查模型或执行模型的推理强度无效,仅该字段回退到提供商默认值。已选的提供商、模型及其他有效设置继续生效。

本页目录