内部细节
架构页没有展开的实现细节:持久提交与 drop guard、执行进度、请求中的图片、会话上的等待、历史存储的拒绝规则、MCP 设置的修复与诊断、Skill 文件的问题、Provider 流的容错解码、模型元数据、崩溃循环标记、分层压缩,以及 Agent 其余的内部机制。
架构说明各部分如何协作、为什么这样设计;本页记录设计没有规定细节的地方实际是怎么做的:确切的上限、每种失败的处理规则、Agent 保存的文件格式。内容都对照过 crates/ 中的代码;两者不一致时,以代码为准,本页需要修正。必须遵守的规则在插件规则。
暂存提交与 drop guard
会话的每次修改都先持久化才对外可见(会话与轮次)。具体做法如下(内核的 service/durable.rs、service/state/cell.rs):
- 会话记录把身份与五组状态分开保存:设置、状态、对话、事件日志和运行时(
service/state/record.rs)。回滚时整组恢复。 - 暂存。 修改在会话单元的锁下改动记录,并暂存为一个
StagedPersistence:要追加的检查点(AgentConversationCommit)或增量(AgentConversationDelta),以及回滚用的状态。有提交暂存时,记录的persisting_revision挡住其他所有写入者:它们只在没有暂存的提交时才锁定记录(lock_after_persistence)。 - 结算。 追加的确认(
AgentHistoryAppendAck)结算这次提交:成功则发布持久化的修订号(清除persisting_revision);失败则回滚记录,前提是记录的修订号仍是暂存的那一个。此后调用方才能发出这次提交的事件。存储未作回应就丢弃的确认会回滚记录,并以ShuttingDown失败。 - 异步调用方(轮次循环、它在内核
start_turn中的准入、压缩、执行进度)把追加排入队列(AgentHistoryStore::enqueue_commit或enqueue_delta),再等待结算的答复。结算在确认中运行,也就是在完成追加的那个历史写入线程上,而不是在等待的 future 里:即使 future 在此期间被丢弃,结算照样发生;等待这个会话的任何东西都不依赖轮次的运行时能否推进。 - 同步调用方在调用线程上追加(
append_commit或append_delta)并就地结算:宿主在异步运行时之外调用的服务会话修改,以及门面在其阻塞边界上运行的轮次提交(submit_turn_with_sink),这样轮次的准入和其托管任务的创建从不分开。
drop guard。 在结束之前被丢弃的轮次或压缩(任务被中止,或者 start_turn 在追加准入时被丢弃)通过它的 guard(TurnExecutionGuard、CompactionExecutionGuard)结束,guard 既不能 await 也不能阻塞。轮次的 guard 先中止该轮次待处理的审批。随后 guard 暂存取消,并把它交给存储,不由任何人等待(StagedPersistence::into_follow_up);确认在写入线程上发布它,然后自己让它可见:唤醒等待终态的调用方、发出事件、通知观察者(TurnFinished)。
如果 guard 被丢弃时已有提交暂存,guard 无法等它,就把自己的提交推迟到单元上(SessionCell::stage_or_defer)。无论什么结算了那次暂存的提交(发布或回滚),都会在同一把锁下暂存第一个仍然适用的推迟提交,确认再把它作为 AgentHistoryFollowUp 交回存储。写入线程在接下一条命令之前先追加这个后续提交,并依次确认,所以一串后续提交按顺序追加。停止追加的存储会让后续提交随它所跟随的提交一起失败。
读取运行时检查点时,历史存储先核验检查点修订号,再把载入状态的修订号设为会话最新已提交的修订号。仅历史增量可能已超过检查点;恢复必须从该头部继续,修复写入才不会被误判为过期。磁盘上的检查点及其完整性检查保持不变。
轮次中途压缩可能从模型上下文中移除当前轮次的 TurnStart 和全部原始条目。压缩后继续产生的思考、工具调用、结果、工具选择和权限审核仍是有效历史;恢复时,如果开始边界已被压缩,就在该压缩前缀及其后续内容中核验已完成轮次的最终回答。如果尚未提交新条目就失败或被中断,轮次收尾仍须持久化终态运行时检查点并发布结束事件,重启恢复也能写入中断状态。此时模型上下文中已没有可承载界面工作时长的本轮条目,不能为了存放时长而把仅供模型使用的替换条目插入对话记录。
持久化提示投影
内核以 ConversationItem::PromptContext { kind, role, content } 保存渲染后提示的变化;content: None 撤销此前的 kind。RequestContext::updates 将准备好的片段和任务计划与每种 kind 最近保存的快照比较,同 kind 的多个片段按稳定的原有顺序合成一个快照,角色由渲染器提供,不新增拒绝规则;未变则不追加。采样通过正常历史提交先持久化变化再发模型请求,估算也使用同样的待提交投影。这些条目沿用既有历史字节/条目上限与持久化路径,没有第二套缓存账本或历史格式重置。
普通请求投影按顺序保留早先世界状态替换并发出移除说明。取代措辞让模型知道当前快照,而无需删除旧前缀。压缩后的 canonical initial context 跨新轮次保留在窗口中;其固定包装明确这是窗口开始时的历史基线:mode/checklist 描述当时,当前模式由当前系统指令和工具决定,任务状态以最新任务计划为准。压缩的摘要请求跳过 PromptContext,避免把过时目录当作摘要证据;当前任务计划仍单独传入。新窗口的下一次已准备采样请求会重建当前目录快照。有意的压缩或历史编辑仍可改变模型视图。
project_model_tool_outputs 将由模型窗口派生的每条结果预算限制在 MINIMUM_CANONICAL_TOOL_OUTPUT_BYTES 与 maximum_tool_output_bytes 之间,不按历史结果数量平分;同一预算下增加工具结果不会改变旧输出投影。请求准入与压缩处理总量增长。这不改变提供方缓存策略,也不承诺命中;线路稳定性与实际返回的 cached-token 用量是两种独立证据。
执行进度
模型启动的执行以 id 和代次记录在会话运行时状态中。它的第一个终态把命令、耗时和末尾输出与状态放在同一份持久化检查点中排队。工具的释放报告在下一步读取队列前撤回该结束事件,也覆盖返回会话 id 后、提交调用结果前命令已经退出的情况。重复启动和状态报告不会重置跟踪。Agent 自身报告、Cancelled、! 命令及关闭的唤醒策略不产生结束事件。内部释放会保留已排队的结束事件,因为它没有向模型报告结果。跟踪不持久化:进程不会跨 Agent 运行存活。
工具通过 AgentToolProgressSink::report 报告进度(进程的启动、输出、状态、释放),这个调用保持同步:它从轮次异步工作线程上的工具调用中被调用,也可能来自比调用活得更久的监视线程。因此 report 只把更新排入会话单元的队列(service/progress.rs):
- 每个会话一个消费者。 报告时如果没有消费者在运行,就在创建这个 sink 的轮次的运行时上启动一个;它按顺序应用并提交排队的更新,逐个等待追加,队列空了就结束。队列未空就停止的消费者(被中止,或它的运行时已关闭)让它已取出的那条更新自行结算;下一次报告,或在自身运行时上的一次刷新,会启动新的消费者。
- 上限。 队列容纳 64 条更新(
EXECUTION_PROGRESS_QUEUE_CAPACITY)。超过之后,如果同一执行在队列中没有排在后面的更新,新的输出更新就合并进该执行已排队的输出:文本追加上去,只保留最新的 16 KiB(MAXIMUM_COALESCED_OUTPUT_BYTES),并从它们第一次能像原始输出那样渲染的位置开始:第一个换行之后,否则第一个完整的转义序列之后(terminal_text::aligned_start),所以保留的文本从不从序列中间开始。其他更新(执行的启动、状态、释放、清理失败)即使这时也照常排队,所以队列最多是容量加上这些更新,再加每条之后的一条输出。 - 与轮次的顺序。 轮次在终态提交之前等待之前排入的所有更新(
flush_execution_progress),所以它的调用报告的内容先提交。被丢弃的轮次无法等待,这时仍在排队的更新在它的取消之后提交,顺序不变。 - 应用自己的报告(后台终端的停止、启动时的恢复)经过
report_session_execution_progress,它最多等待 5 秒,让排在它之前的更新先完成,然后在调用线程上提交。 - 关闭。 会话被移除和
shutdown_history会关闭它的队列并中止消费者;此后report返回false。stop_operations先在关闭期限内刷新此前排入的内容。
请求中的图片
模型请求中的图片附件在不持有会话锁的情况下读取(service/sampling/images.rs)。采样步骤、自动压缩的估算和压缩都这样做:
释放锁,由历史存储加载它们(AgentHistoryStore::enqueue_image_attachment_load):文件存储在该会话的写入线程上读取附件,连同摘要与图片检查,并按顺序确认它们的字节,所以内核自己从不读取附件文件;对放在内存中的存储,trait
的默认实现直接内联加载;
历史引用了但没有加载到的附件,说明历史在此期间变了,请求以 StaleRevision 失败。附件按内容寻址,所以这个请求与在锁下读取所构建的请求逐字节相同。加载失败的附件只有在请求用到它时才让请求失败。压缩会保留它加载的图片,供远程替换(Responses 压缩)和对下一个请求的估算使用。
内嵌工具图片使用 AgentImageAttachmentRef.tool_output_index 记录原来的 ToolOutput.content 位置。Image 和图片 EmbeddedResource 的正文移至附件存储,MIME、detail、URI 和资源文本留在原位置。这些工具图片不会再次规范化,尺寸未知(为零);读取时校验长度和 SHA-256,规范化后的用户图片、预处理工具图片还会校验尺寸和 MIME。函数工具和自由格式工具都在构造请求时还原图片正文。分层压缩的图片恢复会清除原位置索引,因为图片将追加到另一个工具结果。工具展示直接使用引用中的字节长度,无需读取图片文件。现有引用扫描在清理、删除、索引重建和隔离时,与用户图片一样保护这些附件。
会话上的等待
会话单元有两个信号:persisted 在暂存的提交结算时推进,terminal 在轮次或压缩到达终态时推进。会话被移除时两者都推进,被移除的单元对仍持有它的调用方回答 SessionNotFound。每个信号都有异步的一侧(一个 watch 纪元)和阻塞的一侧(单元锁上的 Condvar);wait_until 在有提交暂存时等待 persisted,否则等待 terminal。
- 异步等待: 轮次循环、它的准入和压缩(
lock_after_persistence),取消的确认(Tokio 超时下的wait_until),以及需要压缩时对后台压缩的等待(wait_until,轮次的取消通过推进terminal唤醒它)。 - 阻塞等待只给异步运行时之外的调用方:宿主在阻塞工作线程上运行的同步服务方法,以及门面的阻塞边界(它也负责模型操作前的会话激活和轮次提交);
list_snapshots;flush_for_diagnostics;还有关闭线程上的stop_operations和shutdown,在那里每个会话的等待、它的进度刷新,以及之后对托管轮次任务和后台压缩任务(各自的Condvar)的等待共用一个期限。 - 从不阻塞: drop guard、执行进度和内核的异步
start_turn不在任何阻塞的一侧上等待。
cancel_turn_confirmed 请求取消后,先等待 500 毫秒让轮次协作地结束(COOPERATIVE_GRACE),然后中止它的托管任务(除非轮次已在记录的锁下暂存了它的结束:那次提交持久化后它才发出结束的事件,慢速磁盘可能让这超过宽限时间,此时中止会丢掉这些事件),并在 5 秒期限(CONFIRMATION_DEADLINE)的剩余时间里等待取消持久化;超过则返回 CancellationNotConfirmed。两次等待都是异步的,所以取消不占用阻塞工作线程。
唤醒事件
用户关闭终端时,先确认终止,再将状态、释放进度和替代原退出事件的 StoppedByUser 报告一起提交为一个检查点。只有被跟踪的模型终端报告关闭,前台 ! 命令不报告。整批只通知一次唤醒,所属会话的步骤无法在释放与替代事件之间读到退出。内部清理不排入这些报告。关闭子代理时占用准入许可,并将其存活子树标记为正在关闭,避免调度恢复或回合结束报告与确认清理交错;只有选中的子代理向父会话排入 ClosedByUser,被关闭会话的队列均清空。
执行活动持久化 ExecutionStarted 时的可选字段 execution.initiatingCallId;后续 stdin 调用和重复启动报告不会替换它。恢复用这个身份排除用户的 !command,同时仍报告同一会话中更早由模型启动的后台终端。字段缺失或无法解码时来源未知:旧活动仍可读取和修复,但不会猜测并生成终端 Lost。这是可选字段扩展,不改变历史格式版本。正常关闭也捕获运行时 SubagentRuns 树,包括只剩未读更新的 Waiting 子代理。
嵌套子代理共享主对话的工作数量上限和暂停状态。自身或后代的终端、代理仍工作或还有排队更新时,SubagentRuns 把完成回答保留为 Waiting;只有子树安静后 settle 才发布它。调度器每次处理信号都在故障保护下解析可选的 subagents 服务,通过 run_wake_turn 恢复子代理;普通回合和唤醒回合共享会话驱动的准备逻辑。用户下一条主对话消息或 resume_background_wakes 会重新检查暂停的后代。被唤醒的回合计入主对话的连续唤醒上限。
重启。 正常关闭先在取消回合前捕获仍在工作的子代理和模型启动的终端;回合停止后、历史仍打开时,门面静默记录 Lost。崩溃恢复只报告本次恢复修复的回合与执行活动(AgentRecoveryReport.interrupted_turns 和 interrupted_executions),不会再次报告旧的中断。需要时加载空闲的祖先:孙代理丢失会使其子代理父会话也视为丢失,只向根会话报告这个父会话;已丢失的子代理不会再收到独立的终端或子代理丢失报告。启动不会因此运行模型:这些报告等待所属会话的下一回合,子代理状态也可由 wait_agent 读取。已有排队事件保留;丢失报告替换同一工作的待交付状态,但不会覆盖已持久化的子代理 Completed:父会话的完成提交返回之前,运行记录仍可能计为存活,因此该完成结果优先于关闭时的取样。后续任务会在启动回合前撤回上一次完成结果。前一次恢复已经处理的工作不会在交付后再次报告。这不是跨会话事务:若进程在修复崩溃的子会话后、写入所属会话的丢失报告前再次中断,可能缺少该报告;报告写入失败会记日志,保留会话和历史。恢复的终端只在持久活动带有主题时显示命令,执行 id 仍然可用。
会话的后台工作(它的子代理和后台终端)发生的事,以唤醒事件的形式排在该会话上;某个轮次取走它们时,模型以一条历史条目读到它们,且只读一次。子代理的结束和它发给父会话的消息排在父会话上(subagents 插件);模型启动的后台终端退出、失败或超时时,由执行进度排入事件。测试支持可以手动排入(test_support::queue_wake_event 和 set_wake_policy)。
- 事件(
AgentWakeEvent,kernel/src/model/wake.rs):每会话的sequence、queued_at和一个来源。子代理的来源(session_id、任务名name)为Completed { answer, truncated }、Errored { error }、ClosedByUser、Lost(被重启中止)或Message { text };后台终端的来源(execution_id、command)为Ended { status, exit_code, duration_millis, output, truncated }、StoppedByUser { exit_code }或Lost。 - 队列(
AgentWakeQueue)属于会话的运行时,也属于它的检查点(PersistedAgentRuntimeState.wake_queue,从未排入事件的会话的记录不含此字段)。enqueue_wake_event和take_wake_events提交一个不增加修订号的检查点,与设置项相同。读取时逐个事件解码:无法解码的事件(未知种类、类型错误的字段)带警告丢弃,其余事件和会话保留;已提交条目中的事件同样如此。 - 键与上限。 子代理或终端的最终事件会替换同一
session_id或execution_id已排队的那一个,并排到末尾;消息则追加,第 17 条未读消息被拒绝(LimitExceeded,MAXIMUM_QUEUED_WAKE_MESSAGES为 16)。回答截断到 32 KiB(truncated),终端输出保留最后 4 KiB 并从其所在行的行首开始,命令截断到 1 KiB。 - 策略(
AgentWakePolicy,On或Off,set_session_wake_policy)只保存在内存中,在被赋予之前会话的策略为关闭;快照在pending_wake_events旁携带它。会话驱动在每次激活时按wakeOnBackgroundTasks赋予它(旁路对话和审查始终关闭),每个轮次把它冻结为扩展TurnWake,子代理指引读取它。策略关闭时不投递任何事件,也不接受唤醒轮次,只有子代理的最终状态会排队(其余事件enqueue_wake_event返回Disabled并丢弃),留给wait_agent。 - 子代理的结束(
SubagentRuns::finish):完成(带回答)在子树仍工作或有待处理更新时暂存;安静后,最终完成或错误在运行不再计为存活之前排入父会话,而wait_agent先读运行再读队列,所以发现没有运行的等待一定能找到最后一个排入的内容;中断(interrupt_agent、用户的中断)不排入任何东西。后续任务会撤回上一个轮次留下的状态(AgentWakeFilter::SubagentStatus)。wait_agent取走最终状态(AgentWakeFilter::SubagentStatuses):一个状态只告知一次,由等待或由投递。target为parent的send_message排入一个Message(最多 16 条未读;策略关闭时被拒绝)。 - 投递(策略开启时):每个会采样模型的轮次在准入时把整个队列取为一条
ConversationItem::WakeEvents,在TurnStart和发生变化的世界状态之后、消息之前提交;每一步在转向消息之后立即取走队列,轮次随后再走一步(AgentFollowUpReason::BackgroundEvents);若最终回答会留下排队的事件,轮次不会完成(WakeEventsPending),而是再走一步来投递它们。!命令的轮次不采样模型,什么也不取。 - 唤醒轮次(
TurnAdmission::Wake;内核和门面上的submit_wake_turn_with_sink):一个Programmatic轮次,唯一的开场是该条目(位于发生变化的世界状态之后),没有用户消息:它的请求以用户角色的事件结尾。队列为空或有轮次在运行时(由那个轮次投递)返回None,策略关闭时被拒绝。 - 进展:投递事件的后续步骤把最后投递的序号计入它的进展摘要(
wake_progress_digest),所以一串事件即使每次的回答相同,也不会被算作停滞的步骤。 - 调度器(
agent/src/wake,核心行agent-wake):它的观察者把每个WakeEventQueued、BackgroundWorkChanged和TurnFinished的会话记入一个集合并通知它的 worker,worker 每批对每个会话检查一次:有排队事件、没有轮次在运行、策略打开、此刻wakeOnBackgroundTasks打开(策略要到下次激活才跟上)、根会话的唤醒未暂停的会话被唤醒,根会话通过宿主的AgentBackgroundEventSink收到Woken,子代理通过 subagents 服务恢复。入队与轮次信号关闭了轮次结束时的竞态:排队和轮次的终止提交都要取得会话的锁,所以在提交之前排入的事件由那个轮次读到(某一步,或WakeEventsPending增加的一步),之后排入的事件找不到轮次而发出信号;任一信号都可能发现事件已被读到,找不到事件的提交返回None。旁路对话和审查不会被唤醒。启动时不唤醒任何会话:重启前排入的事件等待会话的下一个轮次。 - 暂停(
wake/pause.rs,按根会话保存在内存中):门面对根会话轮次的cancel_turn(用户的中断)暂停它的唤醒,自用户上一条消息以来第 100 个被唤醒的轮次也会暂停(MAXIMUM_WOKEN_TURNS,在submit_wake_turn_with_sink准入一个轮次时计数);它的来源为User的TurnAdmitted到来时,观察者清除这两者(计划的实施是Programmatic,不清除任何东西)。background_status从本实例保存的运行中计数会话的子代理(在spawn_agent返回之前标记为运行中,只在结束排入队列后才清除),并先于队列读取,所以宿主不会看到一个已结束的子代理既不在工作也没有报告;继续上下文的计数读取内核的轮次阶段,漏计只会让目标多走一步。暂停期间事件照常排队,不唤醒任何会话,下一条消息读到它们;宿主自己的提交仍会运行。background_status报告它(AgentWakeState::Paused)。 - 模型读到的内容:该条目被降为一个用户角色、种类为
background_events的上下文片段,即<background_events>,其中有一行说明这不是用户写的,然后按队列顺序每个事件一段(wake_events_record)。审查者把它读作名为background_events的工具结果,记忆把它读作同名调用的输出;分层压缩保留它的原样,标准压缩把它与其余内容一起摘要;/context把它计入工具调用及其输出;导出、sessions show和终端界面的回放为每个事件显示一行(AgentWakeSource::summary)。
后台事件流(wake/feed.rs)合并收到提示的会话 id,找到根会话,在阻塞池读取不含回答摘要的树快照。只有快照与上次读取不同才发送 Changed。提示来自运行记录、门面修改,以及唤醒事件持久地离开队列后发出的 BackgroundWorkChanged(准入、步骤投递、wait_agent 或撤回),还有已有的准入、结束和入队通知。通知时不持有会话锁。TUI 用这些提示替代原来每 400 毫秒的状态和审批轮询,子代理请求由转发 sink 送达。打开会话时只读取一次子代理待处理请求;若请求在读取后已解决则忽略。只有正在显示的子代理仍用 150 毫秒定时器跟随流式日志。exec 同样等待事件流,移除了原来每 500 毫秒的复查。
历史存储的拒绝规则
旁路会话历史允许在压缩前缀后附加可信 continuation context。分叉扫描区分模型历史与转录页:仅供转录展示的压缩摘要会被跳过,当前检查点则安装其模型替换内容。这让跨越多次压缩的分叉仍满足严格的回合边界。
FileAgentHistoryStore(hanafubuki-agent-history):每个会话一份 JSONL rollout,它是权威的;SQLite 索引(index.sqlite3)是 rollout 的投影(存储)。存储无法使用的东西只损失它自己的会话,从不损失整个存储,也从不损失文件。只有索引或布局(其 schema、SQL、目录 I/O)的问题会让存储打开失败,并因此让 Agent 的构造失败。
打开时无法接受的内容
| 打开时发现 | 处理方式 |
|---|---|
| 无法使用的索引 | 丢弃并从 rollout 重建,所有会话重新判断;open_rebuilding_index(带 rebuild_history_index 的重启)按请求丢弃它 |
另一种格式的 rollout(IncompatibleFormat) | 连同会话的附件目录一起移入旁边的 .recovery 目录(quarantine_file:<name>.<pid>.<n>.invalid,任何扫描都不读它);新路径记入日志,也写进会话的原因;移动失败则文件留在原处 |
| 无法投影的 rollout(无法解码,或没有通过会话、序号和检查点身份的记录检查,这些检查保持严格) | 留在原处,并记下一项待修复(agent_projection_repairs 表),以后每次启动都重试 |
| 文件缺失、同一会话在活动树和归档树中各有一份、路径在存储之外 | 保持原样;如果只是 rollout 的生命周期与所在的树不一致(归档中途停止),则把它移到正确的树中 |
| 已提交的条目或它引用的图片附件无法读取 | 保持原样 |
每个这样的会话都保留它的 ID(next_session_id 被抬到它之后,所以新会话从不与它共用 ID、rollout 名或附件),转录和运行时读取都会拒绝它(带原因的 ProjectionUnavailable),并作为失败交给恢复,由恢复隔离它;其他会话照常打开,Agent 也照常打开。它的任何内容都不改写、不删除。
被拒绝的会话
会话的投影不可用有两种原因(ProjectionLag),各由不同的事情清除:
- 追加的滞后。 记录已持久但投影失败的追加,只在它的写入线程再次投影 rollout 之前拒绝该会话的读取:在之后的某次追加时,或写入线程停止时。
- 拒绝。 索引无法接受的会话(打开时,或之后被会话列表拒绝)一直被拒绝,直到修复(
repair_session_projection)或下一次启动重新判断它。拒绝从不由写入线程清除。
会话列表略去摘要无法解码的行,并以同样方式拒绝那个会话。它只记录一次日志,并告知存储的 AgentHistoryRefusalSink(open_reporting_refusals),槽位通过它把该会话连同原因加入 Agent 状态中的已隔离会话;这一行在分页中保留位置,所以游标照样越过它,列表的其余部分照常返回。重建的索引会重新投影这个摘要。
附件清理
清理未被引用的附件 blob(打开时,以及轮次准入失败的会话)只做垃圾回收:只有当磁盘上仍在的会话文件都不引用某个 blob 时才删除它。
- blob 存放在暂存它的会话下,但任何会话都可能引用它(分叉出的子会话保留恢复的提示中图片的来源会话)。所以清理保留任何已投影条目引用的 blob,以及移入
.recovery的 rollout 中出现的每一串 64 位十六进制数字,不管 blob 属于哪个会话。这些文件每次打开时读取一次,按字节读,从不解码;有一个无法读取就保留所有 blob。这样保留的 blob 在那个文件被恢复或删除后释放。 - 只要有会话的投影不可用(那个会话的引用未知),清理就什么都不删;也不删索引中没有的会话的任何东西;无法清理的会话跳过并记录警告。会话 blob 中意外出现的文件保留。
删除会话
删除(delete_sessions_confirmed)在删除范围之外仍有会话需要其中某个会话时被拒绝:
ReferencedByFork:谱系表(agent_session_lineage)中不随之一起删除的分叉;ReferencedByQuarantinedSession:索引中没有的会话文件(移入.recovery的 rollout,或打开时被拒绝、带待修复项留在原处的 rollout),它从这个会话分叉(forkedFromSessionId或historyBase的sessionId),或提到了这个会话某个 blob 的摘要。错误中列出每个这样的文件及其会话。这些文件按字节读取、不解码(store/kept_files.rs),无法读取的文件会拒绝删除,因为它需要什么是未知的。
两边会话的任何内容都不改动。这样的分叉被恢复并打开后重新进入谱系表;被删除后则不再保留任何东西。内核的 prepare_session_deletion 先询问存储(check_sessions_deletable),所以被拒绝的删除在应用撤销会话的记忆或停止它的终端之前就停下,拒绝的原因就是删除命令的错误。
会话的持久化后代随它一起删除,在同一次 delete_sessions_confirmed 中:外观层通过索引的 parent_session_id 列出它们(两种生命周期,递归),逐个加载,并作为会话的 descendants 传给 prepare_session_deletion,它检查整个集合并把每个成员标记为正在释放。所以从父会话分叉出来的子会话从不阻止父会话的删除,而集合之外的分叉仍然会。外观层随后停止每个成员的终端、撤销它的记忆,任何一步失败都会取消整个删除。complete_session_deletion_confirmed 在删除任何东西之前,先确认每个成员仍处于准备好的状态、没有正在运行的轮次;有一个不满足就取消删除,什么都不删。归档则是逐个普通归档的级联,子会话先于父会话,已归档的跳过。两者都会先关闭每个成员仍然存活的临时子会话。
获准的删除先写一份删除记录(trash/delete-<millis>-<n>/obligation.json),把 rollout 和每个会话的整个附件目录移入该目录,在一个事务中删除会话的索引行,删除移入的文件,最后删除这份记录。中途停止的删除留下的记录在下次打开时完成;无法解码的记录被隔离。
写入线程
存储在加载、恢复或修改会话前取得 history/writers/<id>.lock,持有到关闭。恢复跳过其他活动存储拥有的会话。启动清理和索引重建需要独占历史存储;第二个存储不会清扫活动暂存区或重建共享索引。
写入经过每个会话一个的写入线程(agent-history-writer-<id>,队列容纳 64 条命令),它在追加和它的投影都写好之后确认这次追加。
append_commit和append_delta等待确认。enqueue_commit和enqueue_delta只找到或启动写入线程(没有运行时从索引读取会话的文件)并排队,持有会话闸门的时间不超过这些;写入线程的队列满了时,调用方要等到有空位。- 线程已结束的写入线程(panic,由它的
BackgroundWorkerGroup记录并作为内核故障报告)被撤下,由下一条持有会话闸门的命令换一个新的,所以一次写入失败不会让会话的历史停下。 shutdown(deadline)把每个写入线程的停止排在它已有的命令之后,等到期限为止;届时仍在忙的写入线程被报告(WriterDidNotStop)并放任其分离。持久的内容不会丢失:提交只在写入磁盘后才被确认,所以只有写入线程尚未确认的追加(对任何轮次都从未持久;恢复会还原最后确认的修订)没有写入。
MCP 设置的修复与诊断
修复
mcp.toml(它的键)是 Agent 自己的数据,所以 McpSettingsStore(hanafubuki-agent-config)通过 hanafubuki_agent_mcp::repair_settings 逐个条目地容错读取:
| 发现 | 修复(McpSettingsRepairKind) |
|---|---|
| 文件不是 TOML、不是 UTF-8 或超过 8 MiB | 用默认值替换(reset) |
五个超时之一不在 1–86400 内,maximumConcurrentCalls 或 toolMaximumConcurrentCalls 中的值不在 1–64 内,凭据的 generation 小于 1 或不是整数 | 移到最近的边界;范围内的小数截断为整数(value_clamped) |
第 64 个之后的服务器,无法解码的服务器,没有通过 McpServerConfig::validate 的服务器(带凭据或片段的 URL、公开与凭据的请求头或变量重叠、stdio 程序、参数与环境变量规则、过滤器与策略上限),同一 ID 的第二个服务器 | 只去掉那台服务器(server_dropped) |
| 键无效、无法解码或值不可用的凭据 | 只去掉那条凭据(credential_dropped) |
服务器没有写出的键取下文 serverDefaults 中的值(按工具的设置、参数、环境变量和请求头取空列表或空表),不算修复;ID、传输方式及其 type、程序或 URL 没有默认值。该是数字的地方不是数字时,留给解码器处理,解码器会去掉整个条目。未知的键记入日志并保留在文件中。写入修复后的值之前,原文件先保存在 .recovery/ 中(配置恢复)。写入保持严格:用户添加或编辑的服务器要通过校验,从不被调整。
每项修复是一个 McpSettingsRepair:类型、对象(条目带有有效 ID 时为服务器 ID 或凭据键)、调整改动的字段,以及原因,从不包含文件中的值。下一次读取看到的已是干净的文件,所以存储在打开它的 Agent 运行期间保留这些修复(最多 256 项,MAX_RETAINED_REPAIRS)。它们以 McpApplicationSnapshot.settingsRepairs 交给宿主(Hanafubuki 的 MCP 设置面板显示它们,直到用户关闭),独立二进制的 doctor 把它们列在配置的恢复记录中。快照中的 serverDefaults(McpServerDefaults::default():启用、非必需、旧版协议、超时 15/30/30/120/10 秒、4 个并发调用、ask、deferred、OAuth disabled)是宿主新建服务器表单的初始值,所以默认值不属于任何前端。
诊断
McpDiagnosticStore 为每台服务器保留最近 128 条诊断的环形缓冲(MCP_DIAGNOSTIC_CAPACITY):每条有阶段(spawn、initialize、discover_tools、tool_call、connection_lost 等)、结果(success、warning、error、cancelled、outcome_unknown)、代码、消息、传输、配置与连接的代次、工具、能否重试和下一步。消息截断到 2 KiB 并做清洗:Bearer 之后的词、以 token=、password: 或类似键(access_token、refresh_token、secret、authorization、code、verifier)开头的词,以及 URL 的查询部分,都替换为 [redacted]。stdio 服务器的标准错误保留最后 128 行、最多 16 KiB 的尾部,以同样方式清洗。
服务器的状态行是它的 McpDiagnosticSummary:它当前的诊断,即最近一次连接尝试开始(begin_attempt;第一次之前则是全部)以来记录的诊断,分别计为错误(error、outcome_unknown)和警告,并以其中最严重、同等严重中最近的一条作为标题。它带有当前的每一条,所以宿主可以把这一行展开为全部条目;整个环形缓冲保留在服务器的诊断快照中。它通过 McpApplicationSnapshot.diagnostics 交给宿主,每台已配置的服务器一项,按设置中的顺序。终端界面的 /mcp 显示每台服务器的阶段和最近的错误,不显示这个摘要。
Skill 文件的问题
SKILL.md 的 frontmatter 和 agents/openai.yaml 由人和其他工具编写,所以 hanafubuki-agent-skills 一次读取一个已知的键(yaml_fields.rs):类型不对的值只损失那个键,null 视为没有。用户写什么、有哪些字段见 Skill 页面;按字段的规则如下:
| 位置 | 发现 | 结果 |
|---|---|---|
SKILL.md | 不是 UTF-8,没有 --- frontmatter,frontmatter 不是映射 | Skill 加载失败 |
SKILL.md | frontmatter 不是合法的 YAML | 把看起来是文字、却被解析成 YAML 结构的标量加上引号后再读(值中带有 : ,或以 [、{、@、*、& 或反引号开头且无法解析);仍然无效则 Skill 加载失败 |
name、description | 不是字符串;没有 description | Skill 加载失败:这两个字段决定它能否被选中 |
name | 超过 96 个字符 | 截断,并记一个问题 |
description | 超过 4096 字节 | 按字符边界截断,并记一个问题 |
license、metadata、metadata.version、metadata.short-description | 类型不对 | 忽略那个键,并记一个问题(ignored metadata.version: expected a string, found a number) |
license、metadata.version | 超过 256 或 128 字节 | 去掉,不记问题 |
openai.yaml | 不是 UTF-8、不是 YAML、不是映射 | 忽略整个文件,记一个问题;Skill 照常从 SKILL.md 加载 |
openai.yaml | 超过 64 KiB、无法读取 | 忽略,不记问题 |
openai.yaml | interface.*、policy.allow_implicit_invocation、dependencies.tools 或其中某一项的类型不对 | 忽略那个字段,并记一个问题 |
openai.yaml | 超过 256 字节的显示名、超过 4096 字节的其他文字、绝对路径或越出 Skill 目录的图标路径、不是 #rrggbb 的品牌色 | 去掉,不记问题 |
openai.yaml | 类型不是 mcp 或服务器 ID 无效的依赖,第 32 个之后的依赖;依赖中不是 http(s) 的 URL、未知的传输 | 去掉该依赖或该字段,不记问题 |
| Skill 根目录 | 其下无法读取的目录 | 跳过,并记一个问题;无法读取的根目录让那个根目录失败 |
问题是 SkillCatalogSnapshot::issues 中的 SkillLoadIssue,带有文件或目录的路径和 severity:warning 表示照样加载了(某个字段被忽略或截断、Skill 被更近的同 ID Skill 遮蔽、监视器的诊断),error 表示有目录没有加载(加载失败的 Skill、无法读取的目录或根目录)。因此根目录下无法读取的目录是 error 问题,尽管它只损失自己。扫描最多深入 8 层目录,读取的 SKILL.md 最大 1 MiB。不解析 allowed-tools。
Provider 流的容错解码
Provider 的流是外部输入(模型 API):Agent 无法使用的值,只要响应的其余部分可用,就不让整个响应失败(hanafubuki-agent-model-api 的 tolerant_decode.rs 和各协议的解码器)。身份(响应、条目和调用的 ID)保持严格。
Responses 也接受含有顶层 error 对象但没有 type 的 SSE 帧:部分兼容网关在开始流式响应后遇到上游错误时会发送这种格式。Agent 会以分类后的远端错误结束流,保留上下文超限和能力拒绝的处理,而不是报缺少事件类型。错误消息和代码会限长并脱敏 Provider 的凭据。没有错误对象的无类型帧仍是协议错误。
| 位置 | 发现 | 读作 |
|---|---|---|
| 所有协议 | 空的或只有空白的工具参数 | {},即没有参数的调用 |
| 所有协议 | 不是 JSON 的工具参数(Responses 上还包括:不是字符串) | {} 加上带解析器消息和预览的 argument_error;调用仍与一个告诉模型出了什么问题的输出配对 |
| 所有协议 | 用量缺少某个计数或为 null | 该计数为 0,另一个保留 |
| 所有协议 | 用量不是对象、计数不是整数、两个计数都没有 | 没有用量 |
| 所有协议 | 缓存计数(Responses 的 input_tokens_details.cached_tokens;Chat Completions 的 prompt_tokens_details.cached_tokens,没有时用 DeepSeek 的 prompt_cache_hit_tokens;Anthropic 的 cache_read_input_tokens、cache_creation_input_tokens)缺失、为 null 或不是整数 | 没有该缓存计数(None),用量的其他计数保留 |
| Chat Completions | 没有 choices 的块(stream_options.include_usage) | 记录其用量;只读取 choice 0 |
| Chat Completions | 没有 index 的工具增量 | 接续最近的调用,除非它带有与那个调用不同的调用 ID,这时开始下一个调用;分片到达的 ID 拼接起来,重复发送的完整 ID 只保留一次 |
| Chat Completions | 正常结束但没有 [DONE] 的正文 | 收到过文本或工具调用则视为完成;没有内容则仍是 StreamInterrupted;在事件中间截断的正文仍是协议错误 |
| Chat Completions | reasoning_content 或 reasoning 中的推理 | 每个增量都以 reasoning_content 到达的一段还会完整保存在推理条目上(ModelReasoningReplay::ReasoningContent),供回传;有增量以 reasoning 到达、或超过 1 MiB 的一段照常显示,但不回传 |
| Chat、Anthropic | 没有结束或停止原因 | end_turn 未知;内核于是只根据工具调用决定是否继续 |
| Anthropic Messages | message_start 和 message_delta 中的用量 | 后来的计数替换先前的,缺失的保留先前的;输入是提示总量,即 input_tokens(不含缓存)加上两个缓存计数,在最后加一次 |
| Anthropic Messages | 工具的输入 | 流式的 input_json_delta,否则 content_block_start 的 input,否则 {};不是 JSON 对象的输入是 {} 加 argument_error |
| Anthropic Messages | thinking 块的 signature(块开始时的,再加每个 signature_delta)和 redacted_thinking 块的 data | 完整保存在推理条目上(ModelReasoningReplay,从不序列化),供回传;没有签名或数据、或超过 1 MiB 的块照常显示,但不回传 |
| Anthropic Messages | 未知的块类型或事件 | 忽略;以仍未关闭的块结束的流是协议错误 |
| Responses | response.output_text.done、未知的事件类型 | 忽略:由 response.output_item.done 完成条目 |
| Responses | response.incomplete | 终态的 ModelEvent::ResponseIncomplete { reason }:内核保留已完成的条目和已流出的文本(未完成的推理条目用已流出的内容完成,其他未完成的条目照样接受),以 warn 级别记录原因,只有什么都没产生时才失败 |
| Responses | 没有 response.output_item.added 就完成的条目 | 由内核先开始再完成 |
| Responses | 没有 summary_index 或 content_index 的推理增量 | 第 0 部分 |
| 所有协议 | 内容类型不是 text/event-stream 的 200 响应 | 当作 SSE 读取,除非第一个非空白字节是 {、[ 或 < |
| 模型列表 | 不是对象的条目,或 id/slug 缺失、不是字符串、为空白或超过 512 字节的条目 | 略去并计数:ModelCatalogListing::skipped,并以 warn 级别记录(model.catalog.entries_skipped),只记数量 |
| 模型列表 | max_input_tokens、context_length、max_model_len、context_window、contextWindow、top_provider.context_length、inputTokenLimit(Gemini)、max_context_length(Mistral)、model_info.context_window(阿里云)或 model_spec.availableContextTokens(Venice)中的上下文窗口 | 第一个正整数,否则未知 |
| 模型列表 | max_output_tokens、max_completion_tokens、maxTokens、top_provider.max_completion_tokens 或 max_tokens(Anthropic 的)中的最大输出 | 第一个正整数,否则未知 |
| 模型列表 | 图像输入:architecture.input_modalities、input_modalities 或 input 中的 "image"(不区分大小写);标志 vision、capabilities.vision 或 capabilities.image_input | 任一说是则是,否则任一说否则否,否则未知 |
| 模型列表 | 推理:supported_parameters 中的 reasoning 或 reasoning_effort;标志 reasoning、capabilities.reasoning 或 capabilities.thinking;报告的推理强度 | 任一说是则是,否则任一说否则否,否则未知 |
| 模型列表 | 推理强度:Codex 的 supported_reasoning_levels[].effort,否则 OpenRouter 的 reasoning.supported_efforts,否则 Anthropic 的 capabilities.effort.<level> 中 supported 为 true 的档位,否则 DeepSeek 的 effort.supported_levels,否则 Hoshimi 的 efforts[].id | 无法解析的推理强度(例如 none)略去;每个只列一次,最多前 32 个,按 minimal < low < medium < high < xhigh < max 排序,其他的排在后面 |
| 模型列表 | 默认推理强度:Codex 的 default_reasoning_level,否则 OpenRouter 的 reasoning.default_effort,否则 DeepSeek 的 effort.default_level,否则 Hoshimi 的 effort_default | 无法解析时为未知 |
| 模型列表 | 其他字段,或上面这些字段中类型不对的 | 忽略 |
空响应、认证错误和 HTTP 错误仍是错误。在模型列表中,标志是布尔值或 Anthropic 的 {"supported": boolean};空列表、不含字符串的列表或其他值不表示任何结论。“是”优先于“否”,因为错误的“是”只多一次被拒绝的请求,而错误的“否”会让能读图或能推理的模型拿不到图像或推理参数。某页的条目放在 data(OpenAI 兼容服务)或 models(Codex,以及 z.ai 的 Responses API)之下,两者都没有的页会让列表失败;Anthropic 的某页有 has_more 却没有 last_id 时,列表以已读到的内容结束。各协议的思考事件见思考。
模型元数据
注册表(模型元数据)在 kernel/src/model_metadata/;facade 的存储在 model_metadata_store.rs。
- 列表逐个模型合并。 列表列出的模型采用该条目的事实,包括它不再报告的(变为未知);列表没列出的模型保留之前列表报告的内容,直到最后一次被列出后 7 天,而最新列表列出的模型会一直保留,直到某次列表不再列出它。注册表记录的列表总是替换该端点(协议和 base URL)的模型清单。被列表撤回的事实只用于显示最后一次见到的内容,绝不决定能装下多少上下文:端点最新列表不再列出的模型,其窗口是未知的,因此该模型上的会话不会用提供方已不再背书、仍按撤回窗口计算出的阈值。唯一的例外是端点根本没有列表(还没取过,或已被淘汰):没有任何东西与之矛盾,事实继续有效。
- 缩水保护(来自 Hoshimi):如果一份列表的模型数不到该端点上次记录的列表的一半(更可能是列表被截断,而不是 Provider 下架了一半模型),它不会被记录,仅此一次;下一份列表无论内容如何都会记录,所以真的下架了模型的 Provider 第二次会被相信。只看数量:换成同样多个其他模型的列表(比如换了模型重启的本地服务)会立即记录。无论哪种情况,
list_provider_models都返回该列表。草稿 Provider 的列表(test_provider_draft)和其他列表一样会被记录。 - 过期与上限。 学到的事实从学到时起保留 7 天,除非在此之前被遗忘(
forget_learned,针对一个路由或一个端点的全部路由:providers forget、/model forget、facade 的forget_learned_model_facts):丢弃这些路由学到的事实,保留报告的事实,像其他变化一样保存(没有可遗忘的就不保存)。注册表最多保留 4096 个路由和 32 个端点的列表,超出时丢弃观察或列出时间最早的,但从不丢弃刚学到事实的路由。过期的事实在下一次变化时丢弃,在那之前被忽略。 - models.dev(
model-api/src/models_dev.rs)是外部数据,宽容读取:api.json逐个提供商读取;不是对象的提供商、不是对象的模型,以及类型不对的字段(limit.context、limit.output、reasoning、modalities.input)被略去或视为未知,1024 到 20,000,000 token 之外的窗口和为 0 的输出视为未知,略去的数量以 debug 级别记录。只有正文不是 JSON 对象或没有可用的模型、超过 32 MiB、超过一分钟或状态码不是 2xx 时才失败;这时继续使用已保存的副本。每个提供商保存的是其api的主机名,以及按规范化 ID 保存的窗口、最大输出和对推理、读图的“是”(不保存“否”);同一提供商中规范化后相同的两个 ID 像两个提供商的条目那样合并(取较小的限制和任何一个“是”)。副本自下载起有效一周(下载时间晚于当前时钟时从现在算起),过期后在下一次变化时丢弃;forget_learned从不动它。 - 文件(
model-metadata.json)的结构是{"version": 1, "routes": [...], "listings": [...], "modelsDev": {...}}:每个路由有它的键(端点的协议和baseUrlSha256,以及模型 ID)和它的reported、learned事实,每项事实有值、来源和observedAtMs;每个列表有它的端点、listedAtMs、models,以及是否正在held一份缩水的列表;models.dev 的副本(有的话)有它的fetchedAtMs和catalog,读不出的副本被略去(会重新下载)。文件只在构建 Agent 时读取一次:未知字段被忽略,读不出的路由或列表被略去,读不出的事实视为未知,事实的来源取自它所在的分组,时间不会晚于当前时间。超过 16 MiB、不是 JSON 对象或版本不是 1 的文件会被隔离到.recovery/,本次运行从一无所知开始。 - 写入不让任何调用方等待:注册表每次变化后把快照交给存储(在它的锁内,所以有序),存储再交给 Agent 工作线程组中的写入线程,它写入排队中最新的快照(先写临时文件再重命名覆盖),Agent 停止时写入最后一份。写入失败会以 warn 级别记录,不影响其他任何事情。没有记录任何内容的运行不写文件。
“请求过长”的拒绝
Provider 的错误是否以超出模型上下文窗口为由拒绝请求,由 hanafubuki-agent-model-api 判断(context_overflow.rs,源自 Hoshimi 的 core/failure.py),适用于每种协议的错误,无论是 HTTP 拒绝还是流中的错误(classify_remote_model_error,它先于图片拒绝询问这一判断)。依次读取:
| 步骤 | 规则 |
|---|---|
| 429 | 无论代码或消息是什么,都不算 |
| 代码 | context_length_exceeded、context_window_exceeded、prompt_too_long(不区分大小写):算,无论状态码 |
| 状态码 | 400、413、422 以外的都不算;流中的错误没有状态码,照常读取 |
| 限流或配额 | 消息或代码中有 rate limit、rate_limit、ratelimit、quota、tokens per min、requests per min、too many requests、限流、限速、额度:不算 |
| 代码和消息(转为小写) | 任一含有下列措辞之一时算(token_limit_exceeded 是 OpenRouter 的代码) |
这些措辞是:context_length_exceeded、context_window_exceeded、context window exceeded、maximum context、input exceeds the context window、exceeds the context length、exceed、exceeds 或 exceeded 后接 context limit 或 the context limit、prompt is too long、input is too long、too many tokens、too many input tokens、token limit exceeded、token_limit_exceeded、input token count、exceeds the maximum number of tokens、maximum input length、maximum prompt length、上下文长度、上下文窗口、超出最大长度、超过最大长度、超过了最大、输入过长、超出 之后至多六个字符内出现 长度限制,以及 token 后接 数 或 数量 再接 超过 或 超出(token 之后可有空格)。Hoshimi 中单独的 context length 和 context window 没有采用,因为关于别的事情的拒绝也可能提到窗口(context length must be a positive integer);request too large 也没有采用,因为 OpenAI 也这样描述每分钟的限流,按字节计的大小限制也这样措辞。这类错误照旧是 ModelError::Remote。
context_limit_in(message) 读取拒绝中写明的窗口。各模式依次尝试,每个只看第一处匹配;值不在 1024..=20,000,000(PLAUSIBLE_CONTEXT_WINDOW)之内时转到下一个模式;数字以一位数字开头,后面是数字和逗号,逗号忽略:
| 模式 | 示例 |
|---|---|
maximum context length is N(或 prompt、input length) | This model's maximum context length is 131072 tokens |
context window、length 或 limit,然后 of 或 is,然后 N | exceeds the context window of 200,000 tokens |
> N maximum | prompt is too long: 210000 tokens > 200000 maximum |
maximum number of tokens allowed、maximum allowed tokens、maximum input token(s),然后可有 is、( 或 :,然后 N | exceeds the maximum number of tokens allowed (1048576) |
limit 或 最大,之后至多十二个不含数字的字符,然后是至少四个字符的 N,然后 tok | 输入超过最大长度限制 32768 tokens |
内核据此学习(学到的窗口,service/context_window.rs):写明的窗口,否则被拒请求的估算,同样限定在这个范围内(不到 1024 token 的请求被当作过长拒绝,更可能是误读了拒绝)。注册表只在新窗口小于路由当前有效的学到的窗口时才保留它(learn_context_window;已过 7 天的不再计入,不更小的窗口不做更改也不保存)。被拒会话的提交改写它的窗口和用量的窗口;只有会话采用了学到的窗口时才记录事件 model_context_window_learned(exec --json 事件):配置了窗口的会话、学到的窗口比报告的大、会话已是这个窗口,这些情况都不提示。学习过程不写日志。
推理参数被拒
Provider 的错误是否拒绝了请求的推理参数,由 hanafubuki-agent-model-api 严格判断(reasoning_refusal.rs),在上下文溢出和图片拒绝之后(classify_remote_model_error):宽松的匹配会在无关的拒绝上重试,并让路由学到“不推理”。以下条件全部满足时才是 ModelError::UnsupportedReasoning:
| 步骤 | 规则 |
|---|---|
| 状态码 | 400 或 422;流中的错误没有状态码,从不计入 |
| 指名了参数 | 小写后的消息包含 reasoning、thinking、effort(因此也包括 reasoning_effort、reasoning.effort 和 output_config.effort)或 output_config |
| 是拒绝 | 代码是 unsupported_parameter 或 unsupported_value(不区分大小写),或消息包含 unsupported、not supported、does not support、doesn't support、do not support、unknown、unrecognized、unrecognised、not allowed、not permitted 或 unexpected keyword |
因此 OpenAI 的 Unsupported parameter: 'reasoning.effort' is not supported with this model.(见 openai/openai-python#2532 的报告)和 Anthropic 文档中的 adaptive thinking is not supported on this model 计入,而被拒的 temperature、因过小被拒的预算和 Anthropic 文档中的 Invalid signature in thinking block 不计入;测试中的其他措辞(无法识别或意外的参数、不允许的参数)只是示例,并非实际记录。被拒的档位(unsupported_value)也作为对该参数的拒绝计入。不匹配中文措辞:在 Provider 的拒绝中没有找到这样的例子。
内核(run_sampling_request)只在轮次请求携带了推理参数且轮次未被取消时,去掉推理参数重试一次,发出 ModelRetryScheduled { stage: ReasoningFallback },注册表把该路由的推理学为 Unsupported(learn_reasoning_unsupported,学到的“否”优先于报告的“是”,保留 7 天)。第二次拒绝,或对不带推理参数的请求的拒绝,会让轮次以 AgentError::UnsupportedReasoning 失败。压缩自己的请求不重试。传输层给不出路由时什么也学不到,所以它的每个请求都会被拒绝一次。
结构化请求的阶梯
标题、标题建议、回顾、记忆提取和自动权限审查都在对话之外向模型要一个 JSON 对象,经由 request_json_object(model-api/src/structured_request.rs)。要它的方式有三种,即三级(ModelStructuredOutputCapability),由好到差:
| 级别 | 请求 |
|---|---|
NativeJsonSchema | 协议的 JSON schema 输出(Responses 的 text.format、Chat Completions 的 response_format),不带工具 |
RequiredTool | 一个输入 schema 即该对象 schema 的工具,用 tool_choice 强制调用;调用方不提供工具或会话不能强制工具时跳过 |
Text | 不带工具也不带输出格式;指令多一句话,要求只回答一个符合该 schema 的 JSON 对象,并附上完整 schema(schema_in_text),权限审查也一样 |
- 从哪一级开始。 从协议的那一级(Responses 和 Chat Completions 为原生,Anthropic Messages 为强制工具,什么都没说的传输层为文本)开始,再按路由学到的级别(
ModelMetadata::structured_output)降低。从注册表回答它的会话是create_private_model_session给出的会话(标题、建议、回顾、提取)和审查者的会话(learning_model_session);给不出路由的传输层什么也学不到。 - 拒绝。
classify_remote_model_error严格地(structured_output_refusal.rs)把状态码为 400 或 422、小写后的消息指名text.format、response_format、json_schema、structured output或structured_output并带有拒绝(代码unsupported_parameter或unsupported_value,或推理参数被拒的某个措辞)的错误判为UnsupportedStructuredOutput,紧跟在上下文溢出之后、图片拒绝之前判断(图片拒绝会接收任何说模型只支持文本的 400)。指名tool_choice或tools并带有拒绝的错误是UnsupportedToolChoice,最后判断,在图片和推理拒绝之后,所以同时提到工具的轮次拒绝仍保留它的回退(Anthropic 的tool_choice: type "tool" and "any" are not supported for this model.就是一例)。网关报告的Structured output (`text.format`) is not supported by this stateless gateway.计入;Provider 认为无效的 schema(Invalid schema for response_format …)指名了参数却没有拒绝它,仍是远程错误(阶梯仍会试下一级,见下),5xx 也是。在轮次自己的采样中,两者都是普通的模型错误。 - 阶梯。 原生输出被拒时,路由学到下一级(强制工具,跳过时为文本),请求立即再发一次;强制工具被拒时学到文本。文本级之上的某一级被当作错误请求拒绝、而措辞不在分类器所认的范围内时(其他任何 400 或 422,包括无效的 schema、被误认作图片或推理拒绝的错误,但不含上下文溢出),也会试下一级,但此时什么也不学:之后回答的那一级才被学到,所以与该级无关的拒绝(每一级都失败)不会教出错误的事实。强制工具却得到文本回答(忽略
tool_choice的网关)时,按文本级的回答读取,除此之外什么也不学。其他任何失败都结束阶梯(401、403、404、429、5xx、上下文溢出、超时、取消),文本级的任何失败也是。调用方的时限覆盖整条阶梯:标题 30 秒,回顾 60 秒,提取 120 秒,审查 90 秒。每次重试以 debug 级别记录所用的级别,从不记录内容。 - 学到的级别是一项学到的事实(模型元数据):以
structuredOutput存入model-metadata.json,保留 7 天,除非被遗忘,并且只会降低,所以同时学习的两个请求保留较低的那个。两级都拒绝的网关每周付出两次被拒绝的请求,而不是每个标题都付出。 - 读取。 工具的参数就是该对象。审查者严格读取消息(
parse_assessment_text:无论来源如何,审批都保持严格),只有原生和文本两级。标题、建议、回顾和提取宽容地读取(json_object_text):以{开头的文本从那里读(字符串中的围栏属于内容),否则围栏代码块的内容,否则第一个配平的{…},否则整段文本;然后各自照旧解码字段。
崩溃循环标记
AgentStartMarker(数据目录中的 start-marker.json,用 write_atomic 写入,带缩进格式)记录从未完成的启动次数:
{
"unfinishedStarts": 2,
"pending": [{ "id": 1, "attempt": { "pid": 41237, "atUnixMillis": 1793260800000 } }]
}- 启动在构造之前持有
start-marker.owners/下自己的拥有者锁,并记录待完成的尝试。标记的修改由start-marker.lock串行化。拥有者锁仍被持有的尝试尚在运行,不计作失败;已失去拥有者的尝试折入unfinishedStarts。没有拿到数据目录锁的启动不记录尝试。 - 在 Agent 已
Running满AGENT_START_SETTLE(60 秒)后,或启动、实例有序停止时,删除自己的尝试并清空失败计数,保留其他活动尝试。没有记录过尝试的运行(Agent 处于关闭状态)不清除它,所以崩溃循环导致的停止在有序退出后依然有效。显式重置也保留其他活动尝试。 - 如果崩溃记录属于同一进程且不早于最后一次尝试,就不计入最后一次尝试:致命的 panic 从不发生在 Agent 的线程上(Agent 的线程都被隔离),所以那次运行不是死于 Agent。崩溃记录(
crash-record.json)在configure_crash_record指定它之后,由 panic hook 在致命 panic 中止进程之前写入:
{
"pid": 41237,
"atUnixMillis": 1793260803512,
"thread": "main",
"location": "src/main.rs:42:9",
"message": "…"
}- 计入的启动达到
CRASH_LOOP_STARTS(3)次时,AgentStartMarker::disabled_reason让槽位进入带crashLoop的Disabled,并记录一条提示。用户的重启,或者把 Agent 关闭再打开,会重置标记;单纯的挂载不改变崩溃循环导致的停止。无法读取的标记不计任何启动:它从不让 Agent 保持关闭。独立模式的第一次启动无论计数是多少都会运行(独立模式的同一组合)。
分层压缩
hierarchical 策略(压缩)是内核的 service/compression/(mod.rs 中的投影、adapter.rs 中的适配器、inherit.rs 中的分叉、runtime.rs 中的内容存储和中断、tools/ 与 receipts.rs 中的工具、status.rs 中的状态),建立在纯 crate hanafubuki-agent-compression 之上。
状态。 PersistedAgentRuntimeState.compression 保存该 crate 的 State,以 AgentCompressionState 重新导出:在窗口上生成的引用、块(只失效,从不删除)、token 快照和提醒的基线。它以追加为主:引用从不重新分配,块从不删除,其余部分(提醒、统计、锁存、计数器)很小。所以它写成一条链(model/compression/chain.rs),每个改变了它的运行时检查点带一个链节,即 PersistedAgentRuntimeState.compression_update(AgentCompressionUpdate,没有变化时省略,所以 standard 的记录没有新字段):
snapshot:整个状态,引用映射只写一个方向(by_raw;读取时推导出by_ref,不含BLOCKED和分叉的REF_FLOOR_ID)。它开始一条链。delta(AgentCompressionDelta):它在快照之后的位置(seq,从 1 开始)、新生成或改变的引用绑定、新建或除了年龄之外有变化的块(整个)、只是变老的块的年龄(survived:每个活动块每个请求老一步)、首次渲染的 token 计数和被去掉的计数,以及其他字段中有一个变化时的全部其他字段。dropped:状态结束了(切换离开并压缩过的会话)。
内核对照链头做差分(SessionRuntime.compression_head,conversation_commit 中的 next_link):它暂存的最后一个链节的状态和 seq。回滚连同运行时的其余部分一起恢复链头,所以下一个链节接在最后一个持久的链节之后。加载之后,或者对于新会话(分叉、子会话),没有链头,所以它们的第一个链节是快照;差分无法表达的变化(绑定或块消失、块重新排序)也写成快照;自上次快照以来的差分将超过快照本身时也写快照,这让读取链的开销与状态成正比。没有改变状态的检查点不带链节,所以一个步骤只写一次状态,而不是它的每个检查点各写一次。历史存储把链节保存在 agent_compression_links 中(每个链节一行,快照或 dropped 替换会话的所有行),并从 runtime_json 中去掉状态;加载运行时(load_runtime_state、恢复)时把这些行折叠(AgentCompressionChain)进 compression。内存存储以同样方式折叠。折叠不了的链(之前没有快照的差分、跳号的 seq、提到状态中不存在的块或 token 计数的差分、无法读取的链节 Unreadable)加载为没有状态,由内核重建(见下文)。链出现之前写入的记录在 compression 中带着整个状态,存储把它当作快照读取。历史格式及其版本没有变化;索引的模式版本是 6。切换到 hierarchical 时,如果还没有状态,就装入一个空状态。
分叉、子会话和加载。 条目 ID 在分叉中保留,所以状态映射的消息 ID 也保留。在头部创建的分叉,以及在父会话头部创建的子会话(包括 /side),原样沿用源会话的状态。在某个轮次之前创建的分叉(因此也包括 edit_from_turn),以及在父会话运行中的轮次之前创建的子会话,从源会话的状态中采纳(inherited_state,基于该 crate 的 adopt_fork_state,仿照 billion-context 的分叉采纳):覆盖的消息全部在分叉中的块被保留,并且是活动的,层级块消耗过的块作为原来那样的非活动记录随之保留;已展开或已被消耗的块,或覆盖了分叉中没有的消息的块,被丢弃。分叉持有的每条消息保留它的引用和冻结的 token 计数,源会话的最高引用被保留下来(引用映射中的 REF_FLOOR_ID),所以分叉自己的消息从它之上编号。孤立调用、截断、渲染延迟和视图的锁存随之保留;提醒的基线、统计和终止计数重新开始。空的子会话没有状态。源会话没有状态,或者会话加载时没有状态(没有写入,或者无法读取)时,通过重放窗口中的 compress 调用重建状态(rebuild_state),使用源会话最近一次的调优(加载时用默认值),并放宽压缩限制和最近区,因为这些调用已经通过过它们一次;回执表明失败、被拒绝或无操作的调用不重放。含有压缩(CompactionSummary、ProviderCompaction)的窗口不重建:压缩之后,引用从窗口里已经看不到的编号继续,重放可能折叠错误的消息。没有 compress 调用的窗口不得到状态,所以 standard 的分叉仍然没有状态。
哪些请求。 CompressionMode::of 按请求决定:策略为 hierarchical 时是 Hierarchical;已切换走的会话仍有有效的块时是 Carry,保留投影,但没有提示、提醒和工具;其余情况,以及轮次已回退时(compression_fallback),是 Off。
适配器。 MessageLog 把窗口的历史条目映射为该 crate 的消息:
| 历史条目 | 消息 |
|---|---|
UserMessage、SteeringMessage | 用户文本,图片作为附件句柄 |
AssistantMessage | 助手文本(有 model_text 时用它) |
ToolCall | 工具调用:调用 ID、名字、作为 JSON 文本的参数 |
ToolOutput | 以其调用的名字表示的工具结果:它的文本部分,结构化部分作为 JSON |
CompactionSummary、ProviderCompaction | 受保护的用户文本 |
TurnStart、WorldStateUpdate、SkillContext、ContinuationContext、PermissionReview、ToolSelection、CanonicalInitialContext、Reasoning | 无:条目在请求中保持它在投影条目之间的位置 |
窗口第一个 TurnStart 之前的每条消息(压缩过的前缀)也受保护:它从不折叠。消息的 ID 是 <来源会话 ID>:<条目 ID>,在会话的谱系内唯一。模型读到的引用(m00001……)不是这些 ID,因为压缩之后条目 ID 不再按历史顺序排列:该 crate 按历史顺序生成引用,从不重用。
投影。 regular_model_request 从 projected_history 构建输入,后者对消息日志、状态、配置和上下文大小(上一个响应中 Provider 报告的 context_consumed_tokens,否则是窗口历史的估算)运行该 crate 的 process_turn_with,并传入会话的内容存储(没有消息过滤器:Agent 没有任何过滤器)。apply_view 把该 crate 的视图变回条目:
- 被覆盖的条目被省略;
- 视图改变了文本的消息得到新文本:用户、助手或工具输出文本前面的
<acp tokens="…" type="…">mNNNNN</acp>标签(助手消息写入它的model_text;工具输出的文本部分合成一段文本,图片和资源保留),或者仍然有效的compress调用的参数被压缩到仍然有效的范围。工具调用的参数从不带标签; - 视图渲染的每个摘要(
[Compressed conversation section] — topic,对应没有可见载体的块)作为CompactionSummary条目插入到它的锚点处,模型 API 把它包装为用户文本。
保存的条目从不改变。随后 project_model_tool_outputs 像对任何请求一样限制历史工具输出的大小。在 Hierarchical 下,请求还在指令之后(计划模式的后缀之后)追加 build_compress_system_prompt 的文本(只构建一次,每个请求的字节都相同),并把提醒(在 Anthropic Messages 上用它的 Anthropic 措辞)或者状态行作为最后一条输入:一段用户文本,从不持久化。
哪个请求保留状态。 构建请求会在内存中推进状态:为新消息生成的引用、token 快照、提醒的基线。只有步骤自己的请求(在 begin_sampling 中构建)保留它:状态存到记录上,由步骤的提交持久化。自动压缩的估算和安装之后的检查构建同样的请求(step_model_request_projected),但丢弃状态,所以计算一个请求的大小从不改变状态。一个步骤仍只投影一次:投影连同它的输入保存在会话上(compression/cache.rs,只在内存中)——历史条目、状态和内容存储按身份比较,设置和 token 数按值比较——下一个由相同输入构建的请求(估算之后步骤自己的请求)直接取用它,不再重新投影。开启消息时间戳时,它标记的消息保留估算时的时间。
工具。 compress、decompress、search_context、acp_status 和 acp_cache 是 AgentCoreTool,在模式为 Hierarchical 时被规划(目录上下文中的 compression_tools,即 planned_tools 生成的列表),计划模式下也是;功能开启时,其后还有 absorb、acp_retrieve 和 acp_rule(见下文);这八个名字都在 RESERVED_TOOL_NAMES 中。每个工具都在会话记录的锁下对记录运行(execute_compression_tool),让它的钩子得到一个结果。随后,compress、decompress 和三个可选工具在写入其输出的那次提交的锁下(commit_history_with),针对那一刻的状态再应用一次:提交的输出就是提交的状态所对应的输出,像第一次运行的输出一样受限(canonicalize_tool_output),同一步骤中的两次调用按调用顺序应用。被拒绝的调用让状态保持原样。
compress用 billion-context 的回执回答:带摘要指纹的[Compressed …]、[Compression FAILED、[Compression no-op。decompress用 billion-context 宿主的措辞回答,有四种方式。默认把块的内容(上一层,或用full时的全部原文)作为输出原地返回,并把有效的块标记为已原地恢复(只有第一次恢复改变状态);之后对它的范围调用compress会以同一个 ID 原地重新折叠它。带startId和endId时(它们和imageRef一起出现在 schema 中,是宿主的扩展,见core_tools/compression_spec.rs),只返回块中引用落在范围内的消息,从历史读取(宿主为此需要它的内容存储;Agent 保留完整历史),且不改变任何东西。带非空的toFile时,文本改写到会话的导出文件:这个值只表示要一个文件,因为写到模型指定的位置就是一次未经批准的写入。工具提出请求(CompressionToolRun.export);execute_compression_tool在释放记录的锁之后通过AgentHistoryStore::write_session_export写入,输出给出路径;写入失败时说明这一点,并原地附上前 4 000 个字符。文件存储写history/attachments/<session>/exports/decompress-<block>[-full|-<start>-<end>].txt,同名的下一次导出替换它,删除会话时一并删除;不保存文件的存储(内存中的那个,因此每个临时会话都是)拒绝,这是该 trait 方法的默认行为。不像宿主那样在超过 10 000 个字符时不经请求就写到文件:请求会限制它的历史工具输出(project_model_tool_outputs),大的原地恢复也在内。带imageRef时取回图片:list列出窗口中每条带图片的消息(引用、类型、大小,最多 50 条);mNNNNN引用或摘要的 MEDIA REFS 列出的句柄(适配器作为消息图片句柄传入的附件 ID,crate 在折叠时把它追加到块的摘要中)把该消息的图片附在输出上。full恢复和范围恢复也附上它们返回的消息的图片。提交把输出和附在它上面的每张图片计入本轮的工具输出预算(maximum_tool_output_bytes),超出预算就使本轮失败,所以恢复按历史顺序附上图片,只附到它们连同输出还装得进提交应用它时剩余的预算为止。正文之前的一段说明按句柄列出每张未附上的图片及其类型、大小和尺寸(最多 50 张),供用imageRef逐张恢复,本轮没有余量时在之后的一轮中恢复;一张图片都装不下的imageRef恢复被拒绝,本轮继续。这些是历史自己的附件(CompressionToolRun.images,写入所提交的ToolOutput的images),所以之后的每个请求都像加载任何工具输出的图片一样加载它们,不接受图片输入的模型会被去掉它们;此时图片恢复被拒绝。search_context先搜索块摘要(包括有效的和已被折叠掉的),再搜索被折叠的原文(crate 的folded_message_inputs,即有效块覆盖的消息),两者都和 billion-context 的宿主一样按查询词的字面出现(Algorithm::Substring,最低分 1e-9):出现一次就是命中,没有出现就是不匹配,而混合搜索的模糊 n-gram 会把什么都不匹配的查询变成弱匹配。摘要行给出块覆盖的引用,以及它最有区分度的词周围的一段,用 【】 标出;原文行给出一个没有被摘要行列出的块、它最佳消息的引用和那一段;三个及以上词的查询,在某个词只有排名靠后的块包含时,得到宿主的提示。文档特征按会话缓存(SessionRuntime.compression_search,crate 的DocCache,最多 8 Mi 个 UTF-16 单元的文本),从不持久化。宿主的计划感知引导没有移植:它默认关闭,而 Agent 没有这样的设置。acp_status是该 crate 的状态报告。acp_cache根据 Agent 记录的内容报告:上一个响应的用量和各次折叠。其中输入是提示总量,缓存的 token 是 Provider 报告的缓存读取(ModelUsage::cache_read_tokens;缓存写入不算命中,Provider 未报告时没有 token 算作缓存)。
可选功能。 [compaction.hierarchical] 的 absorb、contentStore、crush 和 rules 设置该 crate 的 Config 中同名的部分(它们的其他设置保留该 crate 的默认值:4 000 个 token 的门槛、96 个字符的开头、50 条规则、每条 300 个字符),process_turn_with 按内核的顺序应用它们:内容存储、隐藏已吸收的调用和结果、crush(只在 absorb 开启时)、吸收要求。它们只在 Hierarchical 下起作用:已切换走的会话(Carry)仍隐藏已吸收的调用和结果,但重新显示已保存的原文,也不再有吸收要求,因为它们的工具已不再被规划。
absorb。 4 000 个 token 及以上、不受保护且不属于 ACP 工具的工具结果,在视图中被附加[ACP absorb]要求(从不保存),指令中加入build_absorb_system_prompt的一节。absorb调用(parse_absorb_input、apply_absorb)在状态中记录一条AbsorbRecord,从下一个请求起,目标的调用和结果被去掉;absorb调用本身留下作为记录。crush。 在决定是否要求吸收之前,大结果中的 JSON、代码或日志被确定性地折叠(apply_crush_to_messages);折叠后低于门槛的结果不再被要求吸收。- 内容存储。 大的工具结果第一次出现时,在视图中被替换为它的占位符(
📦 [acp-stored #mNNNNN · kind · tokens tok] …),一次折叠保存它的块所覆盖的原文(store_covered_originals,随compress在其提交时应用)。存储(AgentContentStore,即该 crate 的ContentStore)保存在SessionRuntime.compression_runtime中,不在记录里:与状态一样,只有步骤自己的请求保留它的投影返回的存储。在使它增长的提交之后(步骤开始、一次compress),内核在释放记录锁后,通过AgentHistoryStore::write_compression_store把它整个写出;文件存储写入history/attachments/<session>/compression-store.json(先暂存再发布),blob 清扫从不读取它,删除会话时将它移除。加载会话时用load_compression_store读取;无法读取的文件被移到一旁,名为compression-store.unreadable-<millis>.json,读作没有。分叉或子会话取得源会话的存储。每个条目只在状态把它的 ref 绑定到同一条消息时保留(从compress调用重建的状态可能编号不同)。存储是历史的缓存:占位符只由原文构建,所以丢失的条目(写入前崩溃、写入失败、被丢弃的条目)会在下一个显示该消息的请求中再次保存,逐字节相同;只有窗口已不再包含的被折叠原文会丢失,此时acp_retrieve回答该 ref 没有保存的原文。acp_retrieve(apply_retrieve、note_retrieval)把原文作为不可信数据内联返回,或者从 4 000 个 token 起把它写入会话的导出文件<ref>.txt(write_session_export,与decompress的toFile相同),并以build_retrieval_pointer给出路径;不保存文件的存储把它内联返回。 rules。acp_rule(execute_rule)在状态中记录、删除、清空或列出RuleRecord。指令中加入RULES_USAGE_PROMPT,有规则后再加入format_rules_for_prompt的列表,位于静态提示和吸收一节之后:规则改变之前字节相同。
被中断的轮次。 用户中断一个 hierarchical 轮次时,stage_terminal 记下它最后一个请求投影时的 token 数(CompressionRuntime,从不持久化)。之后的每次投影,一旦计数超过它,就用 NudgeState::absorb_aborted_turn_growth 把它记入提醒(billion-context 的 #5415):增长基准向前移动,从第二次中断起,跳过的增长作为欠账偿还。重启后它被遗忘。
此策略下的压缩。 在 Hierarchical 下,自动检查(maybe_auto_compact)不看阈值:它在投影报告最终出口时压缩(该 crate 统计的、超过紧急阈值且已没有可折叠或可截短内容的请求数达到三),并且只在 autoCompactionEnabled 开启时。标准压缩的来源是对有效块的投影(project_compaction_source:去掉被覆盖的条目,摘要作为文本,没有标签)。安装时,after_standard_compaction 在 hierarchical 下重新开始最终出口的计数,块所覆盖的条目已离开窗口,这些块在下一次投影时失效;已切换走的会话丢弃它的状态。
Panic。 对该 crate 的每次调用都在 catch_panic 下运行。请求投影中的 panic 让这个请求带完整历史发送,并设置轮次的 compression_fallback:轮次之后的步骤按 standard 运行(没有提示、工具和提醒,阈值恢复),这一步在它的 ReasoningUpdated 之后记录带 panic 消息(限制在 4 KiB 之内)的 ContextCompressionFailed,并记录一条警告日志,下一轮次再尝试。投影压缩来源时的 panic 让压缩读取完整历史。工具中的 panic 是这次调用的错误 [Compression FAILED: … (internal error)],状态保持原样。
设置。 facade 每个轮次读取 [compaction.hierarchical],作为 AgentHierarchicalCompression 放进轮次扩展;内核把它映射到该 crate 的 Config 上,以会话的上下文窗口作为模型的上限:maxContextLimitPercent 设定压力区间,emergencyThresholdPercent 设定紧急提醒和截短阈值(从不低于压力区间),nudgeGrowthTokens 设定增长步长,其余按名字映射。没有它的轮次取默认值;上下文窗口未知时什么都不施加压力。absorb、contentStore、crush 和 rules 开启该 crate 中同名的部分。
消息时间戳。 messageTimestamps 作为 AgentHierarchicalCompression.message_timestamps 到达内核,同时带有 utc_offset_seconds,即 facade 准入轮次时读取(chrono::Local)的本地偏移。历史条目不记录时间,所以消息的时间是首次所见的时间戳,与 billion-context 的纯内存通道相同:投影把时钟传给该 crate(TurnInput.clock:当前时刻,采用该轮次的偏移),process_turn 在分配引用之前,为引用映射尚不认识的每个消息 id 打上时间戳(State.ts_stamps,以消息 id 为键);映射已认识但没有时间戳的 id 是在开启该设置之前显示过的,永远不会得到时间戳。时间戳是一个 LocalTime(毫秒数和读取时的偏移),从不改变,所以标签在每个请求中、重启之后以及偏移改变(夏令时、出行)之后都渲染出相同的 time="yyyy-mm-dd hh:mm:ss"(format_tag_time,位于 type 之后);渲染只读取时间戳。只有该步骤自己的请求保留其投影的状态,所以发送的时间戳就是保留的时间戳。消息由它提交之后的下一个请求首次显示:轮次的最终回答取下一个轮次的时间。指令中的标签一节换成带时间的版本(缓存两份提示)。折叠的回执在每个块的指纹行后加上 [start – end],即它覆盖的消息以及其范围两端所指消息的最早和最晚时间戳;其中有一个没有时间戳时则不加(billion-context 的 blockCoverageTimes)。时间戳在链中作为增量里单独的一张映射传递(只含新的时间戳;有时间戳改变或消失时写快照),分叉或子会话保留它所含消息的时间戳,从 compress 调用重建的状态没有时间戳,所以它编号的消息不再显示时间。关闭该设置时不传时钟:不打时间戳也不显示,请求与没有时间戳时逐字节相同;重新开启后,已保存的时间戳再次显示。缓存报告的时刻使用同一偏移。没有移植:精简提示包的 TIMELINE("Occurred:")规则,因为 Agent 发送的是默认提示包,其中没有这条规则。
宿主看到的内容。 折叠了内容的 compress 调用在提交其输出的同一次提交中、紧跟该提交的 HistoryCommitted 之后记录 ContextCompressed(它的调用 ID、生成的块数、这些块替换的 token 数,以及它生成或重新折叠的块中最高的层级)(CompressionToolRun.fold,由 CompressionChange 带进 commit_history_with);什么也没折叠的调用不记录。快照的 compression(AgentCompressionSummary:活动块数和 Stats.tokens_compressed)在读取快照时从状态计算,没有状态时省略。AgentService::compression_status(facade 的同名调用,/compression 使用它)在记录的锁下复制窗口、状态、内容存储和用量;释放锁之后,像 billion-context 的 /acp 那样在状态的副本上重新决定提醒(process_turn_with,不加标签),所以上次请求之后的折叠也会显示,再生成 build_status_panel 的面板和完整的缓存报告。它使用轮次会得到的 [compaction.hierarchical] 设置,什么也不提交,其中的 panic 是 AgentError::Internal。既不运行 hierarchical、也没有保留状态的会话没有状态。compress_call_ranges 用该工具的宽松解析器读取 compress 调用的参数,供终端界面的折叠单元格使用。
已安装插件的内容
- **加载一次,然后各来源跟随。**一次加载读取
install.json、linked.json和缓存一次(已链接的包从其linked.json条目所指的目录读取;最早支持链接的版本写在install.json中、来源为linked的条目也按链接读取,存储的下一次写入把它移到linked.json;缓存中有的 id 即使linked.json也有,仍是缓存中的包),按键排序包,读取每个启用的包的清单和组件;两次加载之间不做缓存。它为每个启用的包创建数据目录,钩子和服务器会被告知这个目录。Skill 根目录在目录服务上替换(集合改变会丢弃缓存的扫描,与工作区改变相同),钩子来源在引擎上替换(下一轮的发现读取它们),plugins行的摘要被替换;然后协调 MCP 服务器,并把代码包以及启用的已链接包交给访客宿主(插件访客)。 - **重新加载是串行的。**一次重新加载从读取设置到最后一次更改都持有它的门,所以两次重新加载中后一次的集合会保留。写入设置会在后台启动一次重新加载,并不等待它。
- **MCP 一侧只改变有变化的部分。**在 MCP 配置门之下,不再存在、已改变或现已关闭的插件服务器被断开,除非用户的同名服务器已经接管了连接;新增或改变的服务器连接,最多同时四个,连接失败就是它的状态。未改变的服务器保持连接。之前和之后都没有插件服务器时,不获取这个门。
- **钩子的包在需要时才计算哈希。**每轮的运行时发现不计算包的哈希:凭定义哈希被信任的插件钩子是可运行的,运行时计算它的包的哈希(每个事件每个包一次),哈希不是被信任的那个时拒绝该钩子。列出钩子时每个包计算一次哈希,所以对改变了的包
/hooks显示modified;信任时从这次列出中记录两个哈希。无法计算哈希的包,其钩子列为不受信任,也不能被信任。 - 包的组件无法使用时,记为该包的问题:清单字段、读不了的 Skill 根目录(与任何根目录一样是 Skill 目录的问题)、MCP 文件或服务器、钩子文件(钩子诊断)。
插件访客
访客宿主(代码插件)的细节。
- 状态来自 fiber。 监督者(
plugin-guest-supervisor,与加载器同在plugin-guests之下)监听根上的StatusChanged、GuestStarted和GuestExited,通过加载器的条目把访客 fiber 对应到它的包,忽略条目已经替换掉的 fiber。Loading即starting,Active即running,Disposed即stopped;Failed在 fiber 自上次加载以来没有变为活动时是启动失败,否则是故障。GuestStarted保存进程的句柄(进程 id、stderr 尾部),GuestExited保存退出报告;启动失败时从句柄取退出报告,因为访客桥只在apply返回之后才监视退出。刚结束的进程会让访客暂时保持running(没有进程 id),直到它的 fiber 失败。 - 识别提前到达的通知。 loader 在创建 fiber 时同步发布
Loading,Active也可能早于entry.inner_fiber的保存。监督者通过条目和插件定义自身的guest:<id>名称识别访客,不使用可继承的 fiber 名称。loader 包装层和未命名的子任务不会被识别为访客;条目已有另一个存活的 inner fiber 时,仍忽略被替换访客的通知。 - 重启循环。 故障向访客的
RestartWindow询问下一次延迟。有延迟时访客进入restarting,一个任务交给监督者的 worker;延迟之后它检查此后没有对该访客做出新的决定(每个决定,新的包、重试或停止,都会改变它的纪元),并且条目的 fiber 仍是失败的那个;然后计入这次重启,用 fiber 自己的配置更新它而不保存(update_with(config, true):Kardia 的restart会让失败的 fiber 保持失败,而保存的更新会被写回树中)。没有延迟时访客保持failed。retry_package清空窗口并以同样方式更新失败的 fiber。关闭后再开启的包以空窗口启动。 - 进程。 启动器在每次启动时在阻塞池上运行(访客桥在异步 worker 之外实例化访客):它对包求哈希并与记录的哈希比较(已链接的包没有哈希,不比较),创建数据目录,解析命令(
./路径必须解析到包内;interpreter是绝对路径或 Agent 的PATH上的名字,之后访客也可读取它),把命令行包进插件配置,预留所有者,启动一个预留的管道执行器,并把它的 stdin、stdout 和 stderr 交给访客桥(start_reserved_pipe_executor;会话不在其上保留读写者)。访客桥的GuestChild是基于收据的适配器:kill即terminate_reserved_executor(向进程组发 SIGTERM,然后 SIGKILL;Windows 上为作业对象),try_wait和wait读取会话的结束(wait_reserved_executor,带真实的ExitStatus,包括信号),观察到结束之后释放执行器,从而释放所有者。访客桥在确认结束之前丢弃的子进程在丢弃它的线程之外被释放;已被所有者组清扫带走的则已不存在。 - 上限。 握手和每个导出(
apply、调用、dispose)都受plugin_call_deadline(10 秒)约束,除非调用者设置了自己的期限;超过它进程会被杀死。访客发来的一行至多 4 MiB。监督者的 worker 随它的插件停止:插件的释放器在 worker 的释放器之前丢弃重启通道,所以 worker 立即结束。 - WebAssembly 访客。 解析器为每个条目名保存一个单元,第一次解析时在阻塞线程池上填充它:内容检查,以及读取模块(一个在包内解析的
./路径),并在包的限制所对应的WasmSource上把它编译为 kardia-hmr 的WasmGuest(时间总是设置,所以引擎的 epoch 中断是开启的;内存;给出时还有燃料)。限制相同的访客共享这个 source,因而共享一个引擎和一个wasm-epoch线程;只要还有包需要这组限制,解析器就保留它的 source,运行中的访客在停止之前也会让自己的引擎保持存活。插件是带清单元数据(它的名字,提供plugin)的WasmGuest::plugin,改名为guest:<id>:生成它不实例化任何东西,每个实例启动时自己的元数据必须与之相符,否则启动失败;模块的deps从不被读取。无法读取或编译的模块解析为一个每次启动都以原因失败的插件,所以它的访客是failed,而不是停在starting。每个 fiber 在自己的 store 中实例化模块,所以重启从新的内存开始;它的调用在阻塞线程池上一次一个地运行,每次调用都有自己的燃料和 epoch 期限(它自己的期限与限制中较早的那个,以 10 毫秒为一格)。在生成引擎之前,访客宿主请求 kardia-hmr 在 macOS 上用信号处理陷阱(set_macos_mach_ports(false),在其他平台上不改变任何东西;见 panic hook 桥)。模块没有句柄、进程 ID、stderr 或退出报告。 - 失败的访客实例。 kardia-hmr 以带类型的
GuestFailure(Trap、OutOfFuel、Timeout、OutOfMemory、Exited、Killed、Panicked)交出实例的失败,GuestHost::call在调用的错误中找到它(GuestFailure::of),并以使 fiber 失败来回应,再由重启循环处理:除进程访客的Exited、Killed和Timeout以外的任何类型都如此;这三种情况下进程已经结束或被杀死,由 kardia-hmr 的退出监视器以退出报告使 fiber 失败。访客自己的错误(带消息、状态不为 0)不是GuestFailure:它只是那次调用的错误。无论哪种情况,调用的错误文本都是 kardia-hmr 的消息,保持不变。 - 辅助程序命令行上的插件配置。
--restrict-reads和每个根一个--readable-root跟在可写根之后。Landlock 随后只在平台目录(/bin、/sbin、/usr、/etc、/lib、/lib64、/nix/store、/run/current-system/sw,沿用 Codex)、可读设备(/dev/null、/dev/zero、/dev/random、/dev/urandom)、可读根和可写根之下授予读取,而不是在/之下。Seatbelt 在(allow file-read* (subpath …))中以参数命名每个根,加入 Codex 的受限读取平台默认值,并去掉偏好设置策略,因为它能触及读取根之外的数据。 - 日志。 访客的插件名为
guest:<id>,所以 kardia 为它记录的一切(它的 stderr 行、任何级别的log调用、可能引用其内容的 fiber 失败)都带有这个前缀,宿主的LogExporter只在trace级别转发这样的消息,并像任何内容一样截断(bounded_trace_content)。访客宿主以info和warn记录它自己的决定(运行、未启动、失败并重启、以何种状态退出或被杀死),不带访客的原话,原话跟在trace级别。 - 贡献。 监督者在
StatusChanged(Active)的监听器中、把访客标为running之前,通过访客 fiber 自己的上下文注册它的代理:plugin-guests插件声明了七个注册表和PluginFaults,所以访客的受检访问能找到它们,每次注册都是该 fiber 的副作用(所有者guest:<id>)。被略去的部分保存在访客的记录上,并与内核记在guest:<id>下的问题一起显示。访客不运行时代理立即回答(工具源失败,作为Optional被略去;钩子不生效)。调用每 50 毫秒检查一次调用者的取消,取消时丢弃(从而取消)对访客的调用。提示贡献者同时询问每个带提示的运行中访客(join_all),各自限制在调用期限的 80% 内,并按 kind 排序片段。观察者的 worker 是访客 fiber 的一个作用域 worker,读取一个容量为 64 个事件的通道。 - 宿主服务与提供。 每个包有两个 loader 条目:
<id>#host,其插件(guest-host:<id>)提供workspace(每次读取时序列化的视图,所以根总是最新的)和settings(它的配置);以及访客的条目,它把plugin隔离到私有 realm,把这两个服务以标签guest:<id>隔离,并inject它们,所以 kardia-loader 在一个外层 fiber 中暂缓它的启动,直到它们运行。访客不提供其他任何东西:kardia-hmr 拒绝其元数据未声明的键,所以访客提供的东西都不会到达共享 realm。 - 已链接的包。 门面在构建时以及每次重新加载时,把启用的已链接包(有代码或没有)交给访客宿主(
GuestHost::follow_linked);访客宿主从监督者启动到它的释放器运行期间监视它们,集合(按 id 和路径键)改变时替换监视。监视是实例的受控 worker 组中的一个线程(plugin-linked-watcher),它在每个存在的目录上建立递归的系统监视(notify),所以在它建立之前发生的改动看不到;不存在、被删除(收到它的Remove事件)或已消失的目录在每次检查时重试,一旦它重新成为目录就再次监视,这算作它的改动,所以替换整个目录的导出也能跟随;它每 100 毫秒检查一次令牌,所以 worker 组的关闭或访客宿主的停止都会结束它。事件按路径键归属:读取(Access)或目录的.git中的路径不算改动,不指向任何目录下路径的事件(溢出、重新扫描)算作所有目录都改动了。改动停止 500 毫秒后,每个改动过的目录修订号加一,GuestHost::linked_changes随之变化。plugins行的受控作用域 worker(plugins-linked)等待这个计数器,并在后台启动门面的重新加载(PackageReload,reload_packages运行的也是它:先读取包,再重建角色目录),所以重新加载期间发生的改动由下一次重新加载处理。重新加载的apply发现访客的修订号变了:新的纪元和新的条目名(被摘要的内容中加入linked <修订号>),kardia-loader 对此的处理是释放旧的 fiber 并启动新的插件,模块也重新编译。已安装包的名字不包含修订号,所以保持不变。 - 什么会进入设置。 组更新不写回任何东西,故障、重启或启动失败都不改变配置;只有加载器自己的写回(自行释放的插件)会以
enabled = false进入[plugins]。访客的环境仍带有执行器的最终覆盖(代理变量),这是宿主为每个子进程设置的。
更新可执行文件
hanafubuki-agent update(update)属于命令行,基于 hanafubuki-agent-update 这个 crate,其他 crate 都不链接它:门面以及嵌入 Agent 的宿主都没有这部分功能。可执行文件在命令开始时解析一次:一旦另一个进程替换了这个文件,Linux 会把本进程自己的路径读成 PATH (deleted)。
对发布的二进制,依次进行以下步骤,最后一步之前都不改动已安装的文件:
- 查询最新发布版本,按 semver 优先级比较(忽略构建元数据);只安装比当前构建新的稳定版本,或在
--force时安装相同版本。本目标平台的归档必须带有 SHA-256 摘要。 - 不等待地获取可执行文件旁边的锁
.NAME.update.lock(File::try_lock);锁被占用时立即失败。持有锁期间,删除被中断的更新留在可执行文件旁边的暂存目录,并在 Windows 上删除已经没有进程映射的NAME.NUMBER.outdated文件。 - 没有
--force时,询问已安装文件的--version:如果它已经是该发布版本(另一个进程更新了它),就到此为止。 - 把归档以流的方式写入可执行文件旁边新建的暂存目录(同一个文件系统,所以最后的重命名是原子的;从不使用系统临时目录),边接收边计算摘要和字节数:超过列出大小的字节会立即中止,字节不足则失败,60 秒没有收到字节也失败;没有总时间限制。最后比较摘要。只跟随指向 HTTPS 地址的重定向(调试构建的测试地址中允许回环
http),最多十次。 - 按确切名称从
.tar.gz(Unix)或.zip(Windows)中读取唯一的条目hanafubuki-agent-VERSION-TARGET/hanafubuki-agent[.exe],它必须是普通文件,大小不超过归档的 16 倍,并写到更新程序自己选择的文件名;归档中的其他内容一概不写,所以任何条目的名称都无法到达暂存目录之外。在 Unix 上它沿用已安装文件的权限。 - 用
--version运行新文件(关闭标准输入,最多读取 1 KiB 输出,在 Windows 上不弹出控制台窗口),10 秒后杀掉,它必须准确打印hanafubuki-agent VERSION。更新程序启动的进程属于它自己,只在没有 Agent 运行时启动,会等待其结束,并在超时后杀掉。 - Unix:对解析后的路径做一次
rename。Windows:把正在运行的文件重命名为NAME.UNIX_MS.outdated,把新文件重命名进来,失败时再把旧文件改回来;另一个程序占用文件时(例如杀毒软件扫描新文件),每次重命名会在两秒内重试,只针对错误 5 和 32。
暂存目录在任何路径上都会被删除;进程被杀时它会留给下一次更新的第二步。任何时候都不会为了释放文件而关闭或杀掉进程。
对 Unix 上的 cargo 安装,从 PATH 的绝对路径条目中查找 cargo,在新的临时目录中用用户的环境和终端运行它,然后询问已安装文件的版本;cargo 装到别处时文件仍是旧版本,这会被报告出来。
终端界面启动时,读取配置之后、Agent 启动之前,可执行文件同样只解析一次;在 Windows 上会删除它的 NAME.NUMBER.outdated 文件(读取一次目录;仍被映射的文件保留)。然后,如果检查开启、缓存中的版本比当前构建新且不是被跳过的版本、操作是替换或 cargo、命令行中也没有给出提示词,更新提示就接管终端:设置终端模式,读取并丢弃终端中已有的输入,由一个输入线程把输入读进提示自己的通道,在内联视口中以屏幕的高度绘制界面,第一帧之前该线程读到的内容也被丢弃;做出选择后清除视口并恢复终端模式(每条返回路径上都有守卫负责恢复,panic 钩子也会恢复,它只为提示和界面安装一次)。选择 Update now 时,安装信息交回命令行,命令行用自己的客户端(带 GITHUB_TOKEN)运行 update 的流程并以它的退出码结束;Agent 从未启动,所以数据目录的锁从未被获取。检查线程只在提示之后、界面继续启动时才启动。
沙箱辅助程序的命令行跨版本读取。 运行中的 Agent 在启动时记录自己可执行文件的路径,并为每个沙箱命令把它作为沙箱辅助程序启动(--hanafubuki-agent-sandbox 及其参数)。因此任何更新(update、cargo 或手动)之后,仍在运行的旧 Agent 会把新的可执行文件作为辅助程序启动,而新程序会拒绝它读不懂的命令行(退出码 126),这类命令会安全地失败,而不是在没有限制的情况下运行。从现在起,辅助程序的参数只增加,不修改也不删除;必须打破它们的版本会在发布说明中说明。
其他细节
实例、槽位与启动
- 运行时。 每个 Agent 实例的
ContainedRuntime有 2 到 4 个工作线程(机器的并行度,限制在这个范围内)和最多 128 个阻塞线程,都命名为agent-rt(AGENT_RUNTIME_THREAD_NAME)并标记为被隔离。槽位保存它(AgentSlot::take_runtime把它交给停止流程),实例停止时最后用ContainedRuntime::shutdown结束它,这是硬停止,丢弃实例仍在运行的一切(从未返回的插件apply、等待它的释放),不触及宿主。Agent 的BlockingOperationPort是ContainedRuntime::blocking_port。 - 每个实例的 sink。 每个实例通过绑定其代次的 sink 向槽位报告:内核故障经
AgentSlot::fault_sink(generation),历史拒绝经AgentSlot::refusal_sink(AgentInstanceInputs::history_refusals)。过时实例的报告被忽略,启动期间的故障让那次启动失败。已隔离的会话(启动时恢复跳过的,或之后被拒绝的)只加入状态一次并通知。状态中的generation计算本次运行中已领取的启动次数;degraded由插件状态推导。 - 内核故障来自轮次的任务(
execute_admitted_turn在循环外围捕获 panic,托管轮次任务的JoinError也会检查;sink 通过AgentService::without_default_model_reporting_faults注入内核)、宿主的命令守卫、Agent 工作线程组的成员(BackgroundWorkerGroup::contained_with_panic_handler:历史写入线程、记忆监督线程、MCP stdio 读取线程;以worker <name>报告),以及宿主和服务自己的任务(spawn_kernel_task:插件故障跟随任务、重新挂载、设置的后续处理、MCP 启动)。槽位把 Agent 标为Faulted,在它的监督线程(agent-supervisor)上停止它,并对 10 分钟内的前三次故障分别在 2 秒、10 秒、30 秒后启动下一个实例(AUTOMATIC_RESTART_DELAYS、AUTOMATIC_RESTART_WINDOW);此后它保持Faulted,没有nextRestartAt,直到用户重启,重启会清空这个窗口。 - 状态转换。
AgentSlot::restart(AgentStartOptions { safe_mode, rebuild_history_index })在 Agent 启动中、宿主关闭中和宿主关闭了 Agent 时(带setting的Disabled)被拒绝,但会启动因崩溃循环而停止的 Agent;enable和turn_off(先disable,再有界等待)是宿主的打开与关闭。每个转换都交给监督线程安排。重启用关闭的步骤和预算停止实例(stop_instance),清扫它的进程所有者组,停止它的运行时,重置崩溃循环标记(用户的重启时),然后重新启动。安全模式让该实例中核心以外的行都不挂载(AgentHostOptions::safe_mode;disabledPlugins不变)。disable取消正在进行的启动,留下带setting的Disabled。Skill 监视器在每个新实例的根目录上重新开始。 - 失去 Agent 的调用。
AgentSlot::interrupted(generation, command)为 Agent 已不再运行的调用给出错误:"the Agent was turned off;<command>did not finish"、"the Agent stopped after an internal error;<command>did not finish"(故障且没有安排重启),否则 "the Agent restarted;<command>did not finish"。 - 启动。
DesktopAgent::start加上 Agent 自己的ExecutorManager(基于构建DesktopAgent时给的子进程环境)和 Skill 监视器,把它们交给槽位供以后每个实例使用,并启动第一个实例。启动(startup)领取一个代次,构建运行时和进程所有者组(ProcessOwnerGroup::recorded_in),每次运行取一次数据目录锁,记录一次崩溃循环尝试,回收上一次运行留下的进程组(ProcessGroupRecord::reap_leftovers),在阻塞池上构造服务(AgentConstructor得到运行时和实例的AgentInstanceInputs,其中的 Executor 已限定在所有者组内),在那里运行recover(它也结算上一个进程留下的仍在运行的执行活动),启动插件,安排 MCP 连接,并把服务装为Running;随后 Skill 监视器在实例的根目录上启动。任一阶段失败都以 error 级别记录,让槽位进入Failed并清除这次尝试。 - 会让构造失败的: 设置(I/O 错误)、工作区根目录端口和工作区策略、网络端口的代理、MCP 设置文件(只有 I/O 错误;它会自我修复)和无效的 MCP 代理策略、历史存储的布局或索引,以及记忆存储。构造中途失败时会停止它已经启动的工作线程组。不会让构造失败的:无法打开的 Skill 目录(每个 Skill 命令返回原因,
skills插件以此失败)、没有连上的必需 MCP 服务器(体现在它的 MCP 状态Failed,以 error 级别记录;启动在报告前会尝试每一台服务器)、配置无法推导的web行(那一行的错误)。 - 取消启动。
AgentSlot::close(关闭时)和disable取消启动的令牌。构造和恢复是阻塞的,无法取消,所以启动在阶段之间检查令牌;插件的启动在原处被取消。已构建却不会运行的 Agent(恢复或启动失败,或在此期间启动被取消、槽位被关闭)先被退役:轮次、MCP(取消后台连接,释放它们的进程)、插件和工作线程按关闭顺序在RETIRE_BOUND(5 秒)内停止,这比关闭等待启动的时间(START_WAIT,8 秒)短,所以它的运行时只在拆除完成之后才停止。这时仍阻塞在构造或恢复中的启动还没有启动任何插件、连接或进程,所以运行时的硬停止只留下它分离的阻塞线程。
插件宿主
- 挂载。
AgentHost自己不创建注册表:组合创建AgentKernelRegistries,用它们构造内核(这样titles插件的AgentTitleApplication才能持有内核),再交给宿主。在PLUGIN_START_TIMEOUT内没有就绪的行以 "did not start within 20 s" 失败,它的 fiber 在后台释放,下一行接着挂载。每个模型操作(轮次、计划实施、压缩)在宿主尚未启动时启动它;内核从注册表快照做计划,从不等待宿主。宿主任务(故障跟随任务、重新挂载)中的 panic 是plugin host处的内核故障。 - 每个注册表都用内核唯一的
PluginFaults构建(AgentKernelRegistries::faults,也由内核插件发布),每个条目都持有它。自己组合条目的注册表对每个条目分别加守卫:ObserverRegistry::notify、ApprovalRuleSnapshot::verdict、PromptContributorSnapshot::fragments、ToolPresenterRegistry::subject与display。ExtensionPoint转换为故障的FaultPoint。最多可以注册 64 个继续钩子(MAXIMUM_CONTINUATION_HOOKS)。 - 应用设置。 宿主保存设置后,
AgentSlot::apply_saved_settings在运行中的 Agent 的运行时上安排apply_settings_to_plugins;Agent 自己的设置写入(write_settings、set_plugin_enabled)在写完后调用它。两者都不等待。宿主在它的插件锁下读取最新的设置,所以两次快速保存中后一次生效;释放disabledPlugins新列入的行;在先前的 fiber 停止后,用当前配置挂载不再列入的行;只在由设置派生的行的配置变化时调用Fiber::update。它不等待这些转换完成,每个结果都记入日志。尚未挂载的行在挂载时采用新的配置和启用状态。 - 设置 API。
settings_view返回一个AgentSettingsView:设置和它们的默认值;它们的描述在设置目录中。write_settings接受一个AgentSettingsPatch(权限模式、记忆、Web 搜索服务、searxngBaseUrl(null清除它,缺少这个键则保持不变)、webFetchUseJinaReader和webFetchResolveThroughProxy),这是拒绝未知字段的 IPC 请求,其中没有disabledPlugins,它由set_plugin_enabled单独写入文件,按键写入(write_setting_values)也可以写它。它要么整体应用补丁,要么完全不应用,然后让插件跟上新设置,并发出记忆扫描信号。Provider 注册表只能通过AgentConfig::mutate_providers并带上调用方预期的修订号来修改。 - MCP 代理的后续处理作为单独的任务运行:它在 MCP 配置闸门下读取最新的设置,代理策略变化时并发地重连已启用的 Streamable HTTP 服务器,所以挂起的重连既不占住命令,也不挡住之后的变化,后者在它之后应用。
- 上限。 重新启用的行只等待先前的 fiber
PLUGIN_STOP_BOUND(10 秒),之后以 "its previous instance has not stopped yet" 失败,直到拆除结束后的一次重试。 - 启用与状态。 核心行忽略
disabledPlugins;没有任何行使用的名字保留并忽略。set_plugin_enabled拒绝未知名字和核心名字,在阻塞边界上通过AgentConfig::set_plugin_disabled写入,由文件锁串行化。启动完成后,宿主把每个已启用但不是Active的插件记入日志。状态中的contributions从每个内核注册表的一份快照中按条目所有者读取:工具名、工具源 ID、上下文贡献者及其类型、轮次准入与提示贡献者 ID、审批规则 ID 和观察者 ID。restart是待进行的自动重启,或窗口已计入的次数。 - 插件事件 sink。 宿主在以下时刻通知它的
AgentPluginEventSink:启动完成时,某行被启用、禁用、重试或重新配置时,这样的转换完成时,被禁用的行拆除完毕时(这时它的注册才真正移除),以及插件的问题出现、变化或消失时(PluginFaults::set_issues_listener,所以每个轮次都以同样方式失败的贡献者不会再重复通知)。
会话与轮次
- 配置。
normalize_session_config在创建、每次更新和恢复时运行:协议不是 Responses 时远程压缩被去掉(ModelApiProtocol::supports_remote_compaction),会话尚未配置时推理强度和远程压缩被去掉,都给出警告(每种协议都携带推理强度);为零的上下文窗口变为未知;自动压缩阈值和流重试策略被限制在范围内。恢复会重新规范化较旧的会话,而不是隔离它;身份(Provider ID、模型)和完整性检查保持严格。会话的压缩策略,以及它的传输携带的压缩能力,在每次激活时于会话空闲时与设置对齐,提交时不产生新的修订号:快照不显示它们,所以调用方在操作前读到的修订号仍然有效。在压缩策略出现之前写入的配置,或带有本版本不认识的策略的配置,读作standard。 - 恢复(
service/recovery/:校验、持久化的记录、repair.rs中的重启修复)。校验拒绝持久化了某个内核之后会递增、且大于u64::MAX / 2的计数器的会话(修订号、代次、消息、历史条目、轮次、压缩和活动的 ID,steering 序号,模型会话代次,记忆贡献和历史条目的修订号;validation/counters.rs),所以内核的checked_add(1)预期是不变量。load_recovery_candidates分别加载每个候选,并把历史存储打开时拒绝的会话作为失败返回,无论它们的恢复状态如何;recover_sessions把每个跳过的会话以 error 级别记入日志后,返回一个AgentRecoveryReport(恢复的数量,以及带原因的AgentQuarantinedSession)。打开已隔离的会话会以它未解决的恢复义务或存储给出的原因失败,直到之后的某次启动恢复了它。记忆来源投影略去运行时无法解码的会话。只有读取历史索引失败才会让恢复失败。 - ID。 启动恢复和首次加载空闲会话时,Agent 都会将轮次及压缩计数器推进到已存 ID 之后。若压缩替换了模型上下文中最近一个已完成轮次的回答,恢复时会从该轮已提交的对话记录核对回答的消息 ID。
- 步骤无法运行的调用(
service/tool_execution/rejection.rs、CallDisposition):调用了步骤没有提供的名字时,历史把这个调用记在unavailable提供者和工具 ID 下。超过maximum_tool_argument_bytes(64 KiB)的参数以{}代替模型发送的内容保存(模型工具参数)。 - 工具搜索的选择。
ConversationItem::ToolSelection(call_id、选中的AgentToolSelection)不是模型输入:普通search_tools和原生tool_search都会将选中的工具在计划中提升为Direct;原生搜索还会回放搜索输出。工具已不存在或代次已变化的选择不匹配任何东西;这种条目出现之前的历史里自然没有它。 - 轮次限制给用户看的文字是:"agent turn stopped at its time limit of 30 minutes; send a message to continue"(
TurnDeadlineExceeded),以及 "the conversation is still too long for the model's context window after it was compacted; start a new conversation or attach less context"(ContextWindowExceededAfterCompaction)。 - 世界状态。 世界状态最多有 12 个段(
MAXIMUM_AGENT_WORLD_STATE_SECTIONS:每种已知类型一个,共 5 个,加上 7 个插件类型);一次持久化的更新最多可以提到它的两倍,即每种类型一次替换和一次删除。指令不是世界状态:会话配置的指令(默认是基础指令加上宿主的AgentHostInstructions),计划模式下再加上内核的plan.md。 - 内核负责包装的上下文条目。 内核包装那些属于历史而不是段的上下文条目:压缩后窗口的初始上下文、任务清单和选中 Skill 的指令(
SkillContext)。模型 API 只包装它自己的条目:继续上下文、压缩摘要和远程压缩条目。 - 宿主上下文。 恢复时,持久化的 steering 被限制在
MAXIMUM_HOST_CONTEXT_BYTES(4 KiB)之内。在宿主上下文还没有类型时记录的 steering(作为applicationContext)读回时不带上下文。 - 压缩。 独立的压缩在任何采样步骤之外,构建下一个请求本应有的工具计划和提示,但不做任何准备,所以它的请求没有记忆上下文(
PromptRequest::prepared为None)。 - 后台压缩(
service/compaction/background/)。槽位(SessionRuntime.background_compaction)保存上次尝试的输入(窗口、当前轮次之前的条目数、模型、实现),相同的输入不会再次启动,所以失败的运行要等另一个轮次完成后才会重试;还保存它的运行,通过Arc共享:回滚的提交会恢复记录的运行时状态,但结果(运行中、带着计划和样本就绪、正在安装、带着结果已安装、或已用掉)在运行里,任务不持有记录的锁写入它,然后推进terminal。取走结果的检查点把它标为正在安装,结束时标为已安装或已用掉,并推进terminal;正在等待的/compact发现结果已被期间接纳的轮次安装时,返回那次安装的结果,而不用它读到的修订号去压缩。任务在释放记录的锁之前登记到服务的managed_background集合,所以stop_operations要么看到要取消的槽位,要么启动看到服务已停止接受;关闭等待整个集合,归档和删除等待会话自己的条目(5 秒)。计划像轮次前压缩的计划一样构建,使用步骤的模型、工具计划和提示,不在runtime.compaction中预留任何东西,检查自己的取消令牌。它带着样本结束时,用量提交到会话的用量中(不是修订号,并保留context_consumed_tokens),所以安装不再添加。 - 变基安装(
InstallMode::Rebase)代替比较并交换:没有压缩在运行,窗口是快照的窗口,历史以快照的条目 ID(启动时的全部历史)开头。安装的历史是:未压缩部分开始处的世界状态(边界之前历史的full_world_state_checkpoint:之后的更新,包括删除,仍按顺序适用;计划把这个边界source_boundary与压缩读到的条目分开保存,因为有活动压缩块的会话读到的是投影后的历史,条目更少),替换内容,然后是从启动时当前轮次的TurnStart开始的历史,保留原来的 ID,就像轮次前安装保留当前轮次一样(在同样的检查点之后:该轮次开始处的世界状态)。检查点的截止点仍是展示摘要的 ID,所以每个替换 ID 都不大于它,恢复和分叉像对待任何压缩一样重放它;因此在它之后条目 ID 不再按历史顺序排列。安装记录阶段为background的Completed快照(触发automatic,原因context_limit,启动轮次的代号)及其事件,不计入任何轮次的预算,并用采用它的步骤的工具计划和提示估算下一个请求:在这里仍超过阈值不是错误,调用方会再在线压缩。没有减少上下文的结果和其他压缩一样被拒绝。 - 上下文窗口。 再次选择模型会重新解析它的窗口,并把已记录的用量移到新窗口上。
- 继续钩子。 因插件停止而被取消的钩子以
IgnoredFailure完成。 - 观察者。
TurnAdmitted带有轮次的来源(User或Programmatic),以及准入后由 Agent 给出的会话标题(automatic_title:准入提交的临时标题,或此前提交的标题);MemoryContributionChanged带有原因(Initial、User或Polluted)。start_turn和计划实施是Programmatic的。 !命令的轮次(TurnKind::UserShellCommand,service/tool_execution/user_shell.rs;门面的submit_user_shell_command_with_sink)。它和任何轮次一样准入(有轮次运行时和 Plan 模式下被拒绝),权限模式和轮次扩展(沙箱)的收集与消息相同,不采样模型。准入提交TurnStart和轮次的ConversationItem::UserShellCommand { call_id, command, cwd, exit_code, duration_millis, output, truncated },内容为The command did not finish.,像用户消息一样开启轮次;命令结束时把它做了什么就地写入这一项(条目快照,与权限审查完成时相同),所以中断、失败或重启留给模型的是这句话。内核像采样步骤一样规划会话的工具,通过execute_handler_tool_call运行计划中的exec_command处理器,调用 ID 为user-shell-<轮次>:没有ToolCall/ToolOutput对,也没有工具生命周期钩子,因为模型没有发起调用;但有调用的事件(ToolStarted、执行进度、ToolExecutionFinished、ToolCompleted),所以界面把它显示为命令,tool_display按它的调用 ID 从这一项回答。处理器的ToolCallContext.origin是ToolCallOrigin::User,来自轮次,从不来自参数:执行插件于是把动作记为ApprovalOrigin::User,等命令退出(而不是模型调用的 30 秒让出),调用被取消时(Esc、工具超时)终止命令,并在确认结束后释放它(stop_confirmed)。停止耗时超过取消的协作宽限期(500 毫秒)时,中止结束了轮次,停止却仍在确认;关闭时的执行清扫会在截止时间内等待这次释放,释放失败则自己释放该执行,否则说明是什么仍占着它。审批规则照常判断这个动作;没有结论时,route_approval在任何模式下立即以ApprovalDecisionSource::UserCommand授权。这一项读取呈现器的AgentToolDisplay::Command(与工具输出一样有上限);错误输出(被拒绝、启动失败、被停止)没有退出码,错误作为输出。模型把它读作用户角色的上下文片段,即 Codex 的<user_shell_command>(命令、退出码、耗时、输出);轮次以TurnCompleted { final_answer_message_id: None }结束,不读取补充消息(InvalidInput),它的片段在/context中与调用和输出计在一起。分层压缩保留它的全部,审查模型把它读作名为user_shell_command的工具结果,记忆把它读作这个名字的调用。- 子会话(
service/session/child.rs)。子会话沿用父会话的模型、配置、预算策略和工作区,它的范围再按请求的范围收窄;请求指定了角色时,它的角色指令是请求中的(它们不来自父会话,所以按会话的界限检查);从父会话头部开始的子会话还沿用它的标题,所以titles插件不会给它起标题;它的记忆贡献从默认值开始。持久子会话作为头部分叉(create_fork_at_head)或运行中轮次之前的分叉(create_fork)持久化,空的子会话作为新会话持久化。历史以轮次开始,所以上下文只能跟在继承来的历史之后:会以空历史开始却带有上下文的子会话会被拒绝(InvalidInput),不是继续上下文的上下文也一样。临时会话的临时子会话从最近的持久祖先读取图片。持久子会话像分叉一样初始化记忆贡献,临时子会话从不初始化。 - 临时会话。
close_ephemeral_session取消会话的轮次或压缩,中止它待处理的审批,最多等待 5 秒让它结算,然后移除单元、它的事件接收器和内存中的历史;到时仍未结算的轮次会因会话不存在而失败。归档或恢复临时会话会被拒绝(InvalidInput)。内存存储像持久存储一样对记录分页(降序时最新的在前,游标是下标),并按轮次 ID 过滤轮次页,但不保留修订号:一页总是会话最新的状态。 - 旁路对话的条目是两个
ContinuationContext条目,provider 为agent,钩子分别是side-conversation(策略,包在<side_conversation>标记中)和side-conversation-boundary(边界),代次为 1(crates/agent/src/side_conversation.rs,移植自 Codex 的context-fragments/src/side_conversation.rs)。外观层在一道闸门下从内核存活的临时子会话(ephemeral_children)中找父会话的旁路对话,所以同时打开两次也只会得到一个。
思考
思考之外的细节:
- 内核的
AgentReasoningId取自会话的消息计数器(service/sampling/stream/reasoning.rs)。 - 新的摘要部分随分隔它的空行一起到达。保留的文本是已完成条目的摘要(有的话),否则是原始文本,两者都优先取已完成条目中携带的内容,没有则取流出的内容;已完成条目比已显示内容多出的文本,在完成之前显示出来。
- 响应转向其他输出时(另一种条目开始或完成,工具调用在完成时才第一次出现,或回答文本到达)仍未结束的条目,就在那里关闭(
close_open_reasoning,service/sampling/stream/reasoning.rs):它的时长被固定,ReasoningCompleted和回合思考区间的结束(reasoning_item_completed)只发布一次,在那个输出自己的事件之前。Responses API 单独发送推理条目的output_item.done,可能在回答文本或工具调用开始之后;其他适配器都先完成推理。迟到的 done 以固定的时长完成条目(它的摘要、内容和replay),不发布任何事件;已关闭条目的推理增量保存进它的文本,不显示,并在 debug 级别记录(只记录大小)。所以提交的文本可能比显示的更多,恢复会话时可以看到。响应始终没有完成的已关闭条目,以流出的文本提交;响应结束时既未关闭也未完成的条目仍是协议错误。 - 只有推理的响应仍然不提交任何东西。
- 要回传的推理块作为
replay附在它的ConversationItem::Reasoning上,不计入历史的字节数。Anthropic 的思考块(Thinking、RedactedThinking)只在内存中:从不持久化,不出现在快照中。步骤的请求把本轮(最后一个TurnStart之后)的思考块作为ModelInputItem::Reasoning放入,只有使用思考预算的 Anthropic Messages 会发送它们;压缩的请求不带它们。 - Chat Completions 的
reasoning_content(ReasoningContent)超出它的轮次(ModelReasoningReplay::outlives_its_turn,由ConversationItem::reasoning_input读取):每个请求都从投影后历史的每一轮放入它,压缩的请求也一样;只有 Chat Completions 发送它,Responses 两种都略去。它随条目持久化,形如"replay": {"type": "reasoning_content", "text": "…"},没有时不写这个字段;无法解码、属于其他种类或超过 1 MiB 的replay读作没有,从不让条目失败。转录页(AgentTranscriptPage,sessions show --json输出的就是它)略去它,就像略去modelText。分叉或子会话复制条目,文本也随之复制,因为它们延续这段对话。条目的 token 估算(estimate_conversation_items_tokens:流的输出估算、压缩的计数、hierarchical的后备)计入它的字节;请求的估算本来就计入,因为它序列化整个请求。 - 计时快照(
ReasoningUpdated、AgentReasoningSnapshot)保存在条目旁边,供状态显示和恢复使用。
标题
- 门面的提交把轮次标为
User,对没有标题的会话,把提交的文本折成一行、截到 36 个字符,作为内核的AgentTurnInput::provisional_title传入。如果会话仍然没有标题,准入就把它随轮次一起提交(session_title_updated在turn_started和history_committed之后)。来源和临时标题都不随轮次持久化。 titles插件的观察者把会话标题由 Agent 给出(automatic_title)的每个User轮次的TurnAdmitted排入有界队列(try_send)。它的工作线程(spawn_scoped_worker,一次处理一个标题,随插件停止)通过BlockingService上的AgentTitleApplication,从记录中读取会话的第一条用户消息(AgentConversationReader::first_user_message,压缩不会改动记录),只在标题仍是这条消息的临时标题时继续(provisional_agent_title;没有自己的标题来源);再读取当前设置中该会话的 Provider。它让一个私有的模型会话根据第一条消息生成标题(提示截到 960 字节,30 秒),并用replace_automatic_session_title_if_expected提交,这是对临时标题的比较并交换,所以期间的重命名优先。生成失败时临时标题保留,由下一个用户轮次再试;模型或用户给出的标题从不被替换。本次运行中模型已给出标题的会话不再请求,即使该标题等于临时标题(第一条消息很短):重启后会再试一次。已查明标题不是临时标题的会话也不再请求。插件关闭时临时标题保留。- 生成的标题按 Codex 的
parse_thread_title规范化:去掉两端的引号、反引号和弯引号,去掉控制字符,合并空白,去掉末尾的.、?或!,截到 36 个字符;只有什么都不剩的标题才被拒绝。 - 这个请求是共用的结构化请求(
plugins/structured_request.rs,使用全部三级阶梯,宽容地读取消息),有时间上限,随插件停止而取消。概要和标题建议也使用它。 - 标题建议(
suggest_session_title)通过AgentConversationReader读取会话最近 8 条用户和助手消息(从记录中由新到旧),每条截到 960 字节的平均份额,不提交任何东西。 - 概要(
recap_session,recap插件)以同样的方式读取最近 8 次有回答的往来(引导并入它的请求,保留一个更新的未回答请求,不含工具输出和推理),提示在估算 8192 个 token 以内(先省略最旧的往来,再把每段文本摘录为保留首尾),返回AgentRecap { summary, next_action }(60 秒)。回答被宽容地读取:忽略未知字段,缺少next_action即为空,超过 700 个字符的摘要或超过 200 个字符的下一步会被截断。
存储布局
数据目录之外的细节:
history/active/YYYY/MM/DD/session-<YYYY-MM-DD>T<HH-MM-SS>-<id>.jsonl(创建时的本地时间)、history/archived/、history/attachments/<id>/blobs/<sha256>.blob、history/attachments/<id>/exports/(会话的导出文件,decompress的toFile)、history/trash/和history/index.sqlite3。分叉通过谱系表共享父会话的前缀,取的是该前缀所属会话最后拥有的模型上下文:某一段的会话压缩过时,它贡献的是检查点的替换内容及其后的条目,而不是被替换掉的转录;转录仍显示每一条,其分页也照旧翻过父会话的整段历史。索引的模式版本是 6:5 为会话列表的父会话过滤增加了agent_sessions.parent_session_id(带索引),6 增加了分层压缩链的agent_compression_links;其他版本的索引(包括更旧的)在打开时被丢弃,并从 rollout 重建一次。memory/memory.sqlite3、memory/ad-hoc-notes.jsonl(模型留下的笔记)、memory/artifacts/(发布的制品,包括MEMORY.md和memory_summary.md)、memory/staging/和memory/reset-trash/。
记忆存储
记忆之外的细节:
- 一轮处理按从新到旧分页浏览空闲的历史会话(
AgentMemoryHistoryQuery::older_than,每页 100 个,每轮最多 1000 个),最多领取maxSessionsPerPass个。会话能否被提取(参与贡献、有尚未提取的修订、没有退避、没有租约)由记忆存储决定,所以已经提取过的较新会话从不让较旧的会话一直等待。 - 阶段一的证据预算是提取模型的上下文窗口(按会话会得到的方式解析:
AgentService::model_context_window,即配置的值,否则模型元数据中的值,否则 160K)的 70%,最多 120K token。 - 退避从 30 秒翻倍到一天:阶段一按来源(
memory_sources.retry_count、next_retry_at),阶段二全局(memory_meta.global_retry_count、global_next_retry_at);成功或重置会清除它。引用用量的变化如果移动了正在进行的整合的排名截止点,会让那次发布因过时而失败,由退避重试。 - 发布先暂存并校验制品(
MEMORY.md最多 128 KiB,memory_summary.md最多 16 KiB 且以v1行开头),提交数据库(新代次这时就是已发布的代次),然后才换入制品。提交之后的崩溃或重命名失败会把它们留在staging/generation-<n>中,下次打开或下次整合领取时,在任何东西把制品读作基线之前安装它们。 - 打开时就地迁移版本 4 的数据库(它缺少阶段二的退避;丢弃路径还会删除已发布的制品)。只有当数据库不是数据库、已损坏(
SQLITE_CORRUPT、SQLITE_NOTADB)或是其他 schema 时,才连同派生的制品一起丢弃它;繁忙、被锁或 I/O 失败会让打开失败,于是 Agent 的构造带着原因失败,由重启再试。每个连接最多等待 5 秒获得锁(busy_timeout),与历史索引的连接相同。schema 版本是 5。memory reset是用户触发的唯一丢弃。 - 容错。 笔记日志跳过无法读取的行(按行号记录,从不记录内容);超过 64 MiB 的日志仍是
Corrupt。阶段一的输出忽略 schema 没有列出的字段:hasMemory: false是表示什么都不做的开关,优先于多余的字段;否则缺失的文本为空,过长的文本按字符边界截断,NUL 被去掉,不合格的rolloutSlug被改写为小写 kebab-case(什么都不剩时为memory);只有根本不是提取对象的输出才让任务失败。存储不认识的贡献模式读作disabled。 - 贡献模式只有一个类型
hanafubuki_agent_foundation::agent_settings::AgentMemoryContributionMode(默认Disabled),内核随会话持久化它,存储按来源保存它,契约和记忆 crate 重新导出它。 - 信号。
memory插件的观察者在轮次结束时发出扫描信号(所以一轮处理从不与正在进行的轮次争用模型),在回答提交后把引用用量排入队列,记录已提交的贡献变化(用户切换时以及会话停止贡献时发出扫描信号;开始贡献的新会话或分叉会话由之后的扫描处理),并在会话归档或恢复时发出扫描信号。记忆自己的操作(启动、笔记、重置、撤销会话)和设置变化直接发出扫描信号。
MCP 连接、目录与输出
- 启动。 Agent 的启动在后台连接已启用的服务器(
service/mcp/startup.rs),同时最多 4 个(MCP_CONNECT_CONCURRENCY),每个受它自己的连接和初始化超时限制,所以 Agent 在它们连上之前就已Running;挂起的服务器最终以 "MCP operation timed out" 进入failed。每次连接都观察 MCP 的生命周期令牌,关闭时最先取消它,被取消的连接会释放它创建的进程。 - 关闭连接。
McpManager::shutdown(deadline)关闭每个连接,每个在它的shutdown_timeout之内,全部在期限之前;没有确认关闭的连接保持退役,带着它的清理义务(状态中的cleanup_pending)。服务器一侧已结束的连接被退役,在没有步骤持有它之后,凭回执释放它的进程。 - 重连。 每台服务器一个重启窗口(
McpManager::with_reconnect_policy);状态带有reconnect(下一次尝试,用完后为空)。如果外部的连接、刷新或断开先到一步,重连就不再开始;关闭开始之后才完成的重连会释放它的进程,而不是装上它。stdio 服务器的原因会说明它是怎么结束的(the MCP server process exited with code 3)。 - panic。 工具调用的客户端路径中的 panic 让这次调用得到 "the tool failed with an internal error",
McpManager::fail_after_panic退役该连接并像上面一样重连服务器(以 "the MCP client panicked during a tool call:<message>" 进入failed,诊断代码tool_call_panicked)。 - 身份。 工具的代次是服务器配置、其凭据代次以及工具自己的目录条目和策略的摘要。未改变的服务器重连后它不变,所以会话对该工具的
AllowForSession在重连后依然有效;改变服务器的设置、凭据的generation或工具本身,才会重新询问。 - 目录。 从分页的
tools/list结果逐个工具构建。被跳过的工具(无效或过大的 schema、无法编码的名字、清理后重复的名字,例如my.tool变成my_tool)是一个McpCatalogIssue,作为警告记录,带工具名(每次列表最多 16 个),并附一条tool_discovery_partial摘要。工具、资源和资源模板列表不限制条目总数或页数。整个列表仍受配置的超时约束;重复游标会被拒绝,nextCursor: ""结束分页。超过 4 MiB 的页(包括无法解码的条目)或超过 64 KiB 的游标仍然是错误。调用按原始的远程名字发出。 - 列表与读取。
tools/list、两种资源列表和resources/read都通过Peer::send_request请求(listing.rs、request::read_resource),所以 rmcp 的类型化结构拒绝的结果以ServerResult::CustomResult到达,并逐个条目解码:无法解码的工具是tool_skipped_undecodable目录问题;无法解码的资源或模板被略去,并记一条resource_skipped_undecodable或resource_template_skipped_undecodable警告(每次列表最多 16 条),计入resource_discovery_partial;无法解码的读取条目是文本[unsupported MCP content: resource]。这些请求绕过 rmcp 的响应缓存。 - 输出。 带参数的 MIME 类型存为它的基本类型,接受没有填充的 base64,两者都以规范形式保存(
canonical_media_type、canonical_base64)。
执行与文件
Shell 启动捕获在精确审批通过后,经执行服务的预留、启动、等待和释放流程运行,与命令使用相同的沙箱和进程归属。缓存按会话保留一份内存快照,键包括解析后的目录与程序身份、环境选择、沙箱和宿主最终覆盖,不包含每次变化的调用 ID。捕获结果在终端渲染前按字节读取,保留 NUL 分隔的导出变量和多行值。捕获失败也缓存为回退结果;清理失败则保留精确的执行记录以供重试。
exec_command通过预留的 Executor 进程运行;execution插件的活动监视器作为执行的观察者挂上,释放已结束的执行时会有界地等待,直到监视器报告了最终的输出和状态。活动预览只提交以换行结尾的行,未完成的行临时显示。结果是纯文本:管道的输出经过render_plain_text,PTY 的输出经过每个执行各自的TerminalScreen(vt100),轮询一个、监视器一个;它分片喂入输出,并在回滚缓冲可能丢掉一行之前把屏幕状态重放到一个新的解析器中。一次轮询读取它尚未读取的全部输出(output_window):在上限之内就全部返回,否则返回在换行处截断的开头和结尾,中间是[… N bytes omitted …];一个会话保留 4 MiB(EXEC_RETAINED_OUTPUT_BYTES),从缓冲已不再保留的位置开始的读取会从它保留的第一个换行之后开始(resume_point),跳过的字节计入标记。通用的 argvstart只在test-support下存在。- 带样式的副本。 执行服务在每次轮询的纯文本旁边计算它的样式(
UnifiedExecResult.styles,#[serde(skip)],所以模型读到的 JSON 中没有它们的痕迹):TextStyles,纯文本字节的若干段(start、end、textBytes),每段带一个TextStyle(前景色、背景色、粗体、暗色、斜体、下划线、反显),只记录不是默认样式的段,最多 2,048 段(MAX_STYLE_SPANS;最后一段之后的文字按普通样式显示)。管道的样式来自render_styled_text,即纯文本渲染器自身的那一遍(同一个状态机:它的文字与render_plain_text的逐字节相同);一次轮询结束时仍然有效的样式是执行记录的pen,下一次轮询从它开始。伪终端的样式来自TerminalScreen的单元格:每一行的单元格按vt100写出这一行的方式拼出文字,拼出的文字不同时丢弃样式;只有样式变化的行不会再次取出。标记和每个空缺都是普通样式,空缺之后的部分从普通样式开始。轮询之间除了pen什么都不保留:样式由缓冲区已经保留的字节计算。执行插件把它们作为ToolResult.display_metadata(AgentToolDisplayMetadata.styled_output)返回;内核把它提交在输出旁边(ConversationItem::ToolOutput.display_metadata,!命令为UserShellCommand.styled),计入历史的字节数,从不转为模型输入,输出被截短时丢弃它,读回时容错(解码失败的字段视为不存在,条目保留);ToolPresenterRegistry::display把它加到output与之相符的Command显示上(AgentToolDisplay::with_metadata)。实时输出中,监视器把伪终端的行写成终端文本,每个带样式的段放在它的 SGR 序列和一个重置之间(styled_terminal_text),所以ExecutionOutput.text像管道的文本带着进程自己的序列那样带着它们;内核的活动预览像以前一样把它渲染为纯文本。 - 一个执行只由一个调用方释放:
dispose先认领它,对其他所有调用方而言,已被认领或已释放的执行就是不存在(NotFound),即使它们之前已取得其回执。因此被后台终端的停止抢先的模型等待以NotFound结束,或在等待先看到时以停止造成的终止结果结束,而不会是进程错误或清理错误。释放失败会放弃认领并保留该执行(仍欠清理),以便重试。 - 补丁应用到了哪里。
derive_updated_content在更新后文件的新内容旁边报告每一块在补丁前和补丁后的文件中的第一行(PatchHunkStart { old_line, new_line },从 1 开始):即这一块第一个保留或删除的行匹配到的行,再按文件中位于它之前的块增删的行数移动;纯新增的块位于文件末尾,无论它在补丁中的位置。apply_patch在PatchMutationResult.hunk_starts中返回它们,按补丁中的顺序每个文件一个列表(新增或删除的文件为空),并标记#[serde(skip)],所以模型读到的结果不变;workspace-fs 插件把它们作为AgentToolDisplayMetadata.patch_hunk_starts交给显示,内核像对待命令的样式一样把它与输出一起提交(输出被截短时丢弃)。审批的预览在补丁运行之前读取,没有这些位置。 WorkspaceFsService把每个请求解析为策略根目录内不可变的计划,在 I/O 之前重新校验,并原子地写入;preview_patch是纯函数。WorkspaceRootsPort::protected_roots指定的目录是策略的受保护根目录:每个文件工具,包括读取,都拒绝其下的路径("direct filesystem tools cannot access application-owned path …",ProtectedPath)。
关闭
关闭的各阶段之外的细节:
- 每个阶段在它自己的期限或预算结束时(以先到者为准)结束,错过期限的阶段会被报告,同时下一个阶段开始。只有
Running的 Agent 才经历关闭槽位之后的各阶段。 - 最坏情况也在 20 秒之内:正在进行的启动最多 8 秒,加上运行时的 2 秒;运行中的 Agent 最多 5 + 4 + 5 + 3 + 1 + 2 = 20 秒。Skill 监视器的线程通常立即结束;卡在目录失效处理中的线程从剩余时间中最多占用它的 2 秒。
- MCP 和插件阶段在 Agent 的运行时上运行,用
ContainedRuntime::block_on_until等待,这种等待不依赖运行时能否推进,所以工作线程全部阻塞的运行时也挡不住退出。 - 之后是宿主自己的拆除(Hanafubuki 随后停止它的展示分发器,有自己 2 秒的期限)。
终端界面
终端界面的移植改动之外的细节:
-
思考。 桥把
ReasoningStarted、ReasoningDelta和ReasoningCompleted映射到思考单元格(history_cell/thinking.rs),每个推理条目一个。它和工具调用一样是一个实时条目(LiveCell,history_cell/live.rs):聊天组件和转录共享它,每次变化都提高它的修订号,转录视图按条目的修订号、宽度和呈现方式缓存它的布局。它从开始起就在对话中并在原处就地更新,收到ReasoningCompleted时带上内核的durationMillis;在 Scrollback 中它位于尾部(app/scrollback.rs),完成(LiveEntryCompleted)并离开尾部时按显示的样子写入回滚区。轮次结束时,仍在进行的单元格以到那时为止的时间完成,因为在流中途失败的轮次不发送完成事件。没有更新排在流式输出的消息后面:会添加条目的更新先提交消息到那时为止的各行,两种呈现方式都是如此,Scrollback 的尾部按顺序写出它的条目。它的活动 ID 是thinking:{推理 ID},回放的条目为thinking:h{历史条目 ID},并且只在收到文本后才有:展开状态属于转录视图,只在本次运行内有效,从不持久化,所以 ID 只需从进行中保持到完成,而这在同一个条目中自然成立。折叠时它是标题行;展开时(expanded_lines)后面跟着文本。Ctrl-O 请求应用(AppCommand::ToggleThinking)在转录视图中展开它所显示的单元格(Fullscreen 的对话、Scrollback 的尾部)里的每一个thinking:ID,全部已展开时则全部折叠;正在阅读的位置保持视图顶部的条目不动。进行中标题的刷新间隔是 100 ms,工具调用旋转图标的是 600 ms。桥把ReasoningUpdated的AgentReasoningSnapshot转给状态行,状态行显示本轮的turn_completed_millis,条目进行中时再加上自active_since起的时间(纪元毫秒,收到时换算到单调时钟一次);回合成功完成后的分隔线取同一个总数。只有TurnUpdate::Ended(TurnEnd::Completed)才为调用过工具或更新过任务计划的回合输出一次分隔线;轮次中的助手消息可能是进度报告,也可能被续跑钩子接着运行,因此收到消息时不输出分隔线。转录分页器绘制每个单元格的transcript_lines,对思考单元格来说其中总是包含文本;恢复时的回放把ConversationItem::Reasoning映射为已完成的单元格。实时显示的是流出的文本:在少见的同时流出摘要和原始文本的条目中,提交的条目保留摘要,恢复的会话显示的是摘要。 -
展开与折叠。 还有更多内容可显示的条目有一个活动 id(
HistoryCell::activity_ids)和一个控件:tool:{call id}、thinking:…,以及本身没有标识的条目在每次运行中依次取得的编号,任务计划为plan:{n},你的消息为user:{n}(next_activity_id)。单元格说明它的详情增加了什么(activity_disclosure,按宽度):带说明或超过三个步骤的计划(紧凑行是三个步骤,进行中的在前),换行后超过 12 行的消息(紧凑时为前 12 行)。转录视图保存已展开的 id,在 Fullscreen 中、Scrollback 的尾部和 Ctrl-T 对话记录中都是如此。按下控件即切换。按下条目的标题行(TextLayout::header_row,第一行有文字的行)时记下条目的 id,松开时如果在同一个格子上、且该格子仍显示同一条目的标题行,才切换,所以变成拖动的按下会进行选择;Fullscreen 下按下也会开始选择,只有松开后没有选中文本时才切换,并结束多击计数,所以紧接着的第二次点击会再切换回来。Scrollback 的尾部除了按下也转发松开(尾部不做选择),Ctrl-T 对话记录接收 Ctrl-O(toggle_thinking)。 -
工具调用。 工具调用的条目(
ToolCallCell,history_cell/tool/)包含一个调用,或一组连续的探索、Skill 或 MCP 调用,每个调用带有它的结果和显示;每种AgentToolDisplay有一个视图(各占一个模块),给出标题、折叠时的行、展开后的行以及展开增加了什么,外框把这些行放在└之下。调用运行时,以及完成后到它的显示到达之前,标题取自它的名称和对象。调用在开始时按名称确定分组,此时还没有显示:探索(read_file、list_directory、search_text)、Skill(skills_list、skills_read、enable_skill、disable_skill)或 MCP(mcp__开头的名称及三个 MCP 资源工具)。聊天组件保存尚未结束的组(tool_group),只有同类调用才能加入;插入的任何其他条目(消息、思考、不同类工具、提示)都会结束它。Skill 和 MCP 即使只有一次调用也使用紧凑分组行,完整结果保留在详情中,失败预览保持可见;探索类保留原有的单次调用展示。聊天按调用 id 记录每个运行中的调用和每个已完成、等待显示的调用及其条目,只有当条目已经结束、且其中没有调用在运行或等待时,才告诉 Scrollback 的尾部它已完成,所以尾部永远不会写出一串还可能有调用加入的条目。回放按名称以同样的方式对一页中的调用分组;被页边界截断的一串是两个条目。 -
工具输出的格式(Codex
57a808a392的format_json_compact、MCP 结果和diff_render)。Text显示以及Content中每一项的文本是一个 JSON 值时会重新排版(text_formatting):先校验它是 JSON,但不构建它(serde::de::IgnoredAny,所以工作区中会对键排序的serde_json从不改变键的顺序),然后对文本本身重新排版,折叠时紧凑,展开时缩进;超过 1 MiB 的输入、超过 128 层的嵌套或缩进后超过 4 MiB 的结果按原样显示,/raw(Extent::raw)中的文本都按原样显示。content.rs根据各项的AgentOutputBlock写出摘要。差异(diff_render/):style是 Codex 的配色(主题、颜色深度、背景色以及行号、符号和内容的样式),wrap是它的行布局(wrap_styled_spans,按字素和显示宽度),color是它的对比度调整(readable_color_on),terminal_palette是颜色深度(supports-color)和 xterm 调色板(计算得出,不是表格)。上下文在每次渲染时读取一次(current_diff_render_style_context);测试中除非测试自己设置(with_diff_style_context),否则是 16 色,所以环境不会改变快照。 -
命令的流式输出。 桥接层把带调用 id 的执行输出转为
TurnUpdate::ToolOutput,把启动和状态更新转为ToolExecution。聊天组件用executing_tools保留原调用的实时条目,直到进程进入终态;它与running_tools、awaiting_display分别跟踪进程、工具调用和显示读取。因此,工具返回 session id 或模型结束本轮对话,都不会丢弃后续输出,也不会提前把条目写入 Scrollback。输出请求重绘,已有的帧节拍更新计时。history_cell/tool/execution.rs为转入后台的命令显示有界的实时输出,在进程终态冻结用时并显示失败状态。前台命令仍使用最终工具返回内容显示结果。门面在AgentToolProgressUpdate旁重新导出AgentExecutionProgressStatus。调用的实时缓冲区(history_cell/tool/live_output.rs,参照 Codex 的LiveCommandOutput)把仍在写入的行保留为原始文本,显示其中结束于转义序列之外的前缀(complete_prefix_len),由render_styled_text从这一行开始处有效的样式渲染,两者都由门面重新导出:\r重绘,以及监视器在再次发送的伪终端行之前加上的\r ESC[2K,都会替换这一行。已结束的行只渲染一次,成为带样式的片段(history_cell/tool/styled_output.rs,与完成后的显示的行使用同一个构造函数,所以两者显示相同的片段)并展开制表符,所以按布局时的宽度计量;行末有效的样式延续下去,空缺之后从普通样式开始。超过 16 KiB 上限而被折叠的未结束行,按它的样式写回为终端文本。它保留最前的 200 行和最新的 200 行以及中间的行数,并在 1 KiB 处截断一行,所以每次变化以及运行中命令 100 ms 的时钟引起的重新布局,即使展开也有上限;不增加定时器,由实时条目的帧节拍绘制。切换会话会清除这些实时引用;回放仍使用已经提交的工具结果。已知的限制来自监视器的伪终端预览:它只把最后一行标为重写,所以其上方各行的重绘会作为新行再次到达;一个换行了的未结束行在结束之前会被替换为它在屏幕上的最后一行。 -
稳定的布局。 调用的条目在变化时保持形状。在它的显示到达之前(
Outcome::shown:显示本身,或聊天组件告知不会有显示:回复为None、在原处打开了会话、回合结束),没有行的视图得到一个暗色的占位行(运行中的exec_command为(running…),其他情况为…),由第一段输出或显示替换。运行中命令的时钟不参与标题行的换行:先对标题换行,只有时间的最大宽度(CLOCK_COLUMNS,· 99h 59m 59s)放得进最后一行时才把时钟接在后面,所以是否显示从不取决于时间。剩下的变化:Running形式的最后一行超出不到四列的标题行,变为Ran时可能少一行;折叠后没有行的显示(读取、列目录、搜索、网页工具、移动、删除、没有输出的write_stdin)去掉占位行;行更多的显示增加其余的行和它的控件:大多数为两行加控件,输出没有流式显示的失败或转入后台的命令为三行(还有它的退出行),补丁每个文件一行。切换展开时条目的标题行保持在屏幕上原来的行:当顶行属于被切换的条目且不低于它的标题行时(两种形式在标题行以上的各行相同),disclosure_anchor保留顶行的文本,以前则把条目重新从标题行开始显示。等待消息的预览只按仍在等待的消息计算高度。引导消息被消费、排队消息被发送或取回编辑时,立即释放对应行,让状态行在任务继续运行时回到输入框附近。Scrollback 的尾部保持它的下限(T1b);超出下限的展开让视口向上增高,尾部的行随之移动。 -
自带工具分组。
ToolGroup::for_name还对终端交互(write_stdin、resize_execution)、记忆工具、read_thread和上下文管理分组,包括按功能开关提供的absorb、acp_retrieve、acp_rule。实时条目与回放使用同一分类。命令显示区分轮询和输入,非零退出码计入分组失败数。记忆呈现器逐项读取资源和匹配,某项异常不丢弃其他可用项;正文使用带行号的FileRead显示,便笺回执说明其正在等待整合。read_thread的呈现器显示数字会话 ID。未知插件工具名保持通用展示。 -
流式输出。
exec_command条目从开始到Outcome::shown始终提供通用展开控件,即使没有输出或只有几行;在第一段输出之前展开,之后输出到来时仍保持同一条目展开。 流的控制器(streaming/controller/,即 Codex 的StreamCore,按状态、提交和预览拆开)对到最后一个换行符为止的源码做增量渲染(streaming/render.rs:最后一个顶层块之前的块保留不变,每个换行符到达时只重新渲染最后一个块;出现引用定义时全部重新渲染;标明语言的、打开的顶层围栏走streaming/code_fence.rs,它保留 syntect 的状态,只高亮新加入的完整行,见render/highlight/streaming.rs,受普通的上限和主题修订版本约束)。可变尾部起点之前的行进入队列,每行记下入队时间;起点取以下最早者:表格的表头(streaming/table_holdback.rs,它的顶层块完成后释放)、最后一个块中的 Markdown 围栏,以及开启图表时的 Mermaid 围栏(渲染器的mutable_fence_start,经过展开的围栏映射回源码;Mermaid 围栏在结束符之前是代码,之后是图表,调整大小可能让它变回代码)、仍未闭合的独立公式所在的行(遮蔽器的pending_math_start,以同样方式映射;起点位于独立公式之内的顶层块,不论公式是否闭合,也不算已完成)、只有列表标记的最后一行、以本地链接目标结尾的最后一行(渲染器的trailing_local_link,:前的软换行会把下一行接上)。尾部是队列之后的行,加上未结束那一行的预览(streaming/prose_preview.rs:表格和围栏中除外,最多最后 8 KiB,链接的目标在)到达前不显示;在未闭合的独立公式中,或在以$$或\[开头的一行上,显示用 textwrap 换行的该行源码,不扣留任何内容)。提交节拍(streaming/commit_tick.rs)按AdaptiveChunkingPolicy(streaming/chunking.rs,Codex 的阈值:8 行或 120 ms 进入追赶,低于 2 行和 40 ms 持续 250 ms 后退出,退出后 250 ms 内不再进入,除非达到 64 行或 300 ms)清空队列:每个节拍一行,追赶时全部。应用的线程每MIN_FRAME_INTERVAL(8 ms)发送一个节拍,在某个节拍之后两个对话都没有排队的行时停止(流在仍有排队行时结束,线程不再一直运行下去);增量让行入队时,立即运行一个只在追赶时提交的节拍。每次变化是一个AppEvent::StreamUpdate(提交的行所在的单元格,以及尾部现在显示的内容),应用一次性处理它(app/message_consolidation.rs):流的第一次更新插入尾部条目,一个带有流的 id 的LiveCell<StreamTailCell>;提交的行插在它之前,在转录、Scrollback 的尾部和 Ctrl-T 对话记录中都是如此;最后一次更新把它清空并标记为完成,Scrollback 的尾部便可以放开它。流跟随聊天区的宽度:以另一宽度绘制一帧之后,set_width重新渲染,在尾部起点之前的行上保留已提交的行数,并重建队列。结束时源码再整体渲染一次;已提交行之后的行就是它最后的行;若已提交的行不是这次渲染开头的行(setext 下划线、后到的引用定义、调整了大小),Consolidation会要求修复,Scrollback 以重新写入执行。Fullscreen 流式输出时使用ListSpacing::Compact。 -
保存源码的消息与调整大小。 回答的流按当前宽度渲染并提交各行,放在带有流的
StreamId的AgentMessageCell中(计划的放在ProposedPlanStreamCell中)。流结束时交给应用一个Consolidation:一个保存流的 Markdown 和会话目录的AgentMarkdownCell(或ProposedPlanCell),它按被请求的宽度渲染,并为一种宽度和列表间距保留最近一次渲染(history_cell/markdown_cache.rs)。应用用它取代流从第一个到最后一个的单元格(app/message_consolidation.rs;插在其间的单元格排在它之后),在转录、Ctrl-T 对话记录和 Fullscreen 的视图中都是如此;TranscriptView::replace_entries让位于其中的读者保持它正在读的修订版本,与实时条目相同,否则重新开始搜索。在同一宽度下,这个单元格的各行与流的各行相同,所以 Scrollback 的尾部保留它尚未写入的行。回放直接构建这些单元格。Scrollback 的帧记录屏幕大小(Tail::note_size);大小变化时安排一次在REFLOW_DEBOUNCE(75 ms)之后进行的重新写入,之后的变化会把它推迟(app/resize_reflow.rs),在此之前的帧按新的大小绘制而不写入。重新写入取尾部之前的转录(Tail::first_unwritten:部分写入的条目按整个计算,转录中已不存在的条目,即已合并的流的行,被跳过),通过TranscriptView::scrollback_lines从最后一个条目向前排版,直到行数上限,清除终端(Tui::clear_scrollback,它把光标移到原点)并写入;尾部以剩下的部分重新开始,去掉它的下限。转录中有流的行时发生的调整大小或重新写入会再标记一次,由流的合并在下一帧执行。选择、保持的阅读位置和搜索的匹配在结束之前保持它们建立时的布局,按新的宽度重新换行(prepare_width)。 -
超链接。 一行的链接是一个
HyperlinkLine(terminal_hyperlinks/):行本身,以及每个网页目标覆盖的显示列,按 ratatui 绘制的方式逐个字形计量。Markdown 写入器在推入网页链接的标签时带上它的目标,正文中直接写出的 URL 则经过 Codex 的扫描(以空白分隔的词元,去掉两侧的标点,右括号只在不配对时去掉);每种换行都返回每一行在源文字中的字节范围(WrappedLine),remap_source_wrapped_line据此算出每一行包含的每个链接的部分,所以被换行拆开的链接在每一行上都链接到完整的目标;前缀、填充和追加会移动这些列。目标只在建立链接的地方清理一次(web_destination:不超过 8 KiB,去掉控制字符,然后必须是带主机名的http或https)。渲染 Markdown 的单元格(AgentMessageCell、StreamTailCell、AgentMarkdownCell、计划的两种单元格,以及转发它们的LiveCell)实现HistoryCell各方法的*_hyperlink_lines对应版本,其他单元格用它们的普通行来回答;Markdown 缓存、流的队列、它的StreamUpdate单元格以及结束时对已提交行的比较都持有HyperlinkLine,所以只有链接不同的一行也会要求修复。TextLayout保存每个显示行的链接(展开制表符时一起移动);比视图宽、带有链接的行按识别 URL 的方式换行,仍然更宽的行在宽度处截断。绘制时,每个带链接的单元格的符号被链接序列包住可见文字,并设为CellDiffOption::ForcedWidth(mark_hyperlink_cells);帧的差异按单元格的可见符号计量宽度,绘制时在一串属于同一链接的单元格之前打开链接,在任何光标移动或另一个链接之前关闭它。滚动历史的写入去掉一行文字中的控制字符后输出(与 ratatui 不把它们放进缓冲区相同),每个链接夹在它的序列之间(decorate_spans)。尾部、重新写入的scrollback_lines和Tui::insert_history_lines都传递HyperlinkLine。WebLinkDisplay::for_terminal在启动时根据terminal_detection::terminal_info()(可注入的环境)、标准输出是否为终端以及STY决定一次,与tui.rendering一起保存在markdown_render/preferences.rs中(测试中每个线程各有一份,默认是回退的显示方式);丢弃链接的渲染(思考)总是显示地址。 -
会话。 界面通过桥打开每个会话(
AgentBridge::open,基于open_session):新会话、resume指定的会话、最近的会话,或在恢复选择器中选中的会话。最新的转录条目在头部之后读回,作为聊天回放的内容(agent_bridge/replay.rs:消息、思考、计划、工具调用及其输出,以及从已提交条目读出的apply_patchdiff)。/new和/resume切换桥的会话,离开的会话的事件被忽略。 -
命令在
agent_bridge/commands.rs中映射到门面:/new对应create_session;/resume对应list_sessions_page(按标题搜索、按游标分页,选择器滚动时在循环上读取);/compact对应compact_session_with_sink;/model先用provider_registry_snapshot、settings_view和model_metadata取得立即显示的内容,再对每个已启用的 Provider 各调用一次list_provider_models,每个回答都带着列表的编号(agent_bridge/model_list.rs),然后是set_session_model;/mode对应set_session_mode;/status对应settings_view、provider_registry_snapshot和workspace_roots;/skills对应list_skills。设置中心只通过write_setting_values和run_settings_action写入(agent_bridge/catalog.rs),/raw以及主题、状态栏和标题页面也是(write_tui_settings);没有 spec 的按键映射和预设用write_tui_preferences写入[tui]。作为页面的浏览器也通过目录写入:插件浏览器(agent_bridge/plugins.rs)执行packages、marketplaces、plugins和hooks集合的动作,并按键写入选项,但授予代码插件的权限(grant_package_permissions,针对它所显示内容的同意)和没有configSchema的代码插件的原始 JSON 设置(set_package_settings)除外;钩子浏览器执行hooks集合的save和trust(agent_bridge/hooks.rs)。记忆存储页面保留会话的参与设置和重置。页面保存的内容除了写入对话记录,也会在设置中心中显示。需要读取动作不返回的内容的页面各有一个模块:Provider 的模型页面对应list_provider_models(agent_bridge/providers.rs),它的选择是设置中心执行的一次模型策略保存;/mcp verbose对应mcp_snapshot,MCP 服务器的登录对应在 Agent 运行时上执行的mcp_oauth_login,丢弃它的cancelledfuture 所等待的发送端即取消登录(agent_bridge/mcp.rs)。审批和回答的调用不会等待,在循环上运行。 -
压缩。 桥把每个状态为
completed的CompactionUpdated变成Context compacted单元格,无论压缩由什么启动,并刷新状态行。/compact的回复只带失败,所以手动压缩只显示一次,/compact从后台采用的压缩也是。状态为failed、触发为automatic的CompactionUpdated变成警告单元格,并保留在/warnings中(来源compaction);手动压缩的失败是/compact的回复,被取消的压缩不显示任何内容。消息流式输出期间,该单元格立即添加,放在消息到那时为止的内容之后。/status从它运行时读取的快照中读backgroundCompaction:后台槽位变化时修订号不变。 -
覆盖层。 转录分页器、
/diff分页器和恢复选择器占用备用屏幕;期间提交的单元格在 Scrollback 的尾部等待,覆盖层关闭前尾部不写入任何内容(调整大小后也不重新写入滚动历史:关闭后的第一帧会注意到大小的变化);有覆盖层打开时,终端的恢复会离开备用屏幕(致命 panic 时的恢复也是如此)。 -
文件搜索用
ignore遍历工作区根目录(嵌套在另一个根目录中的根目录作为它自己只遍历一次),送入在自己线程上运行的nucleo匹配器,随@token变化重新排序。 -
二进制像
exec一样组合并启动 Agent,使用界面的状态 sink(TuiEvents::status_sink),把运行中的句柄交给界面(hanafubuki_agent_tui::run),在界面恢复终端后用AGENT_SHUTDOWN_BUDGET关闭 Agent。轮次进行中 Agent 的状态变化(内核故障)会让exec结束,因为重启后的 Agent 有新的代次。 -
panic hook。 二进制传给
install_panic_hook的logging::logging_blocked说明线程是否在文件日志器内部;这时 hook 只写标准错误。
已知的限制
- 在步骤开始时第一次追加的
tool_catalog_omissions更新不在该步骤的准入估算之内。 - rmcp 的无标签
ServerResult会把带有_meta和无法解码条目的结果解码为CallToolResult,其中的条目已经丢失,所以这样的列表页仍会整页失败。
宿主的一侧
宿主围绕 Agent 构建的东西由宿主自己记录;Hanafubuki 的部分(src/agent/commands/guard.rs 中的命令守卫、它的事件 sink 和窗口事件、来自 AgentSlot::list_run_projections 的任务中心行、诊断包中来自 flush_for_diagnostics 和 plugin_status_for_diagnostics 的 app/agent-status.json 与 app/agent-plugins.json、它的 agent 模块行和退出顺序、旧设置文件的一次性导入)见它的 agent-integration.md。每个宿主的命令层都以同样的方式工作:每次调用时解析槽位,在 Agent 的运行时上运行调用,把其中的 panic 变成这次调用的错误和一次内核故障,并用 AgentSlot::interrupted 回答 Agent 在调用期间停止的调用。