hanafubuki-agent

插件规则

Agent 插件组合的约束规则:crate 边界、组合规则、扩展点、工具与参数、上下文、审批、外部产出、宿主接口、编写与测试插件。

Agent 由 kardia(Cordis 的 Rust 实现)上的插件组合而成。本页是这套组合的规则:修改任何工具、上下文段、审批规则、继续钩子、工具生命周期钩子或观察者,修改插件宿主、它的清单和插件配置,修改 crate 边界或宿主接口,或修改 golden 测试之前,先读相关的小节;设计改变时更新本页。仓库级规则(锁、路径、解码严格度、内容日志、布局)见参与开发和 AGENTS.md;这些部分如何协作以及原因见架构。

crate 与依赖

crate作用可以依赖不能依赖
hanafubuki-agent-foundation、-process、-hostHanafubuki 的 hanafubuki-foundation、hanafubuki-process、hanafubuki-module-contracts 的 Agent 副本,裁剪到 Agent 用到的部分;类型与宿主的不同process 与 host 依赖 foundation;host 依赖 kardia-core、kardia-macros其他所有项目 crate
hanafubuki-agent-contracts扩展点契约:注册表服务、扩展点(ExtensionPoint)、各类契约、SelectableSkills、宿主服务;重新导出 host 的注册、故障与工作线程机制和 CancellationToken,插件只依赖它kardia-core、kardia-macros、host、foundation、approval、tool-contracts内核、门面、任何领域服务 crate、任何插件
hanafubuki-agent-kernel内核:会话、轮次、工具流水线与核心工具、请求组装、世界状态、Skill 选择、历史提交、压缩、审批流程;创建它读取的注册表(依赖 skills 只为 SkillId)契约、kardia-core、model-api、skills、approval、tool-contracts、foundation、compression任何插件、门面、process、web-search
hanafubuki-agent-plugin-<name>一项能力:把一个领域 crate 绑定到扩展点,或作为功能服务提供它契约、kardia-core/kardia-macros、approval、tool-contracts、foundation、它自己的领域 crate;web 还使用 process 管理可选本地辅助程序内核、门面、其他插件
hanafubuki-agent组合:插件宿主与清单、Agent 自己的插件、槽位、Executor 与 Skill 监视器、服务 API、宿主接口内核、契约、插件 crate、config、runtime、foundation/process/host 副本model-api、web-search
hanafubuki-agent-configAgent 自己的配置(AgentConfig)mcp(MCP 设置及其修复)、packages([plugins] 和 [marketplaces] 表)、foundation、toml、toml_edit、dirs内核、契约、插件、门面
hanafubuki-agent-packages已安装插件的包存储,属于领域层:标识、清单格式、市场、带版本的缓存、暂存安装、安装记录;不使用 kardiafoundation、process(通过 ExecutorManager 运行 git)其他所有项目 crate
hanafubuki-agent-plugin-packages访客宿主,属于插件 crate:在一棵 kardia-loader 子树中以 Kardia 访客运行已安装插件的代码:进程外的程序,每个都属于实例的执行器并受沙箱的插件配置约束,或者在 wasmtime 中按其限制运行的 WebAssembly 模块;按 RestartPolicy 重启;监视已链接包的目录(notify)契约、kardia-core、kardia-loader 和 kardia-hmr(用 process 和 wasm,两者都不带默认的 preserve-order,它会让 Agent 的每个 serde_json 映射按插入顺序排列)、host(RestartPolicy、访客日志器前缀)、packages、process、sandbox、foundation、approval 和 tool-contracts(其代理的工具)内核、门面、config、其他插件
hanafubuki-agent-runtime被隔离的运行时(ContainedRuntime)foundation其他所有项目 crate
hanafubuki-agent-compressionbillion-context 的分层上下文压缩,纯函数:compress 参数解析、折叠的应用、投影视图、提醒、解压、搜索和报告;没有 I/O、没有异步,生产代码与插件一样不 panicserde、serde_json其他所有项目 crate
hanafubuki-agent-update二进制的自更新,只有 CLI 使用:在 GitHub 上查询发布、版本规则、发布资产的名称、安装方式及更新它的办法foundation、reqwest、semver其他所有项目 crate
hanafubuki-agent-tui、hanafubuki-agent-cli终端界面;hanafubuki-agent 二进制tui:门面;cli:门面、tui 与 update其他所有项目 crate
宿主的集成(Hanafubuki:hanafubuki-agent-integration)在本仓库之外:宿主的插件行和端口门面、契约、approval、tool-contracts、config(宿主的设置导入)内核、model-api 和这里的其他所有 crate

cargo xtask check-dependencies 检查这张表的 Cargo 部分:不依赖任何 Hanafubuki crate(任何来源);每个成员的内部依赖都在层表(LAYERS)它那一行之内;kardia 只出现在 host、契约、内核、插件 crate(名为 hanafubuki-agent-plugin-* 的成员)和门面中,kardia-loader 和 kardia-hmr 只出现在访客宿主(hanafubuki-agent-plugin-packages)中,且从不使用 kardia 门面 crate;host 只依赖 foundation;只有门面依赖 config;每个插件依赖契约,不依赖内核、门面或其他插件;每个插件 crate 都是门面的依赖。check-plugin-panics 在插件 crate、门面自己的插件(crates/agent/src/plugins)和压缩 crate(crates/compression)中执行下面的 panic 规则;宿主检查它自己的插件。model-api 不能依赖契约,check-model-api-context 检查它的生产源码不出现任何上下文段类型。其余靠评审。

组合规则

  1. 内核不依赖任何插件可以替换的东西。 被注入的服务被替换时 kardia 会重启插件,而内核重启会丢失所有活动会话。内核插件不注入任何东西;它发布在运行时启动前创建的注册表,内核按轮次或采样步骤读取它们的快照。
  2. 注册是调用者的副作用。 通过注入的注册表服务上的 hanafubuki_agent_contracts::Register 贡献条目。条目属于调用的插件(Svc::caller),在它停止时移除;插件从不保留撤销注册的句柄。被拒绝的注册(RegistrationError,例如重复的 ID)让插件失败。
  3. 运行中的调用让条目的插件存活,但有界限。 调用从快照条目取得 EntryLease 并观察它的取消。工具源规划的工具租用工具源的条目,工具源贡献时也一样。停止中的插件先把条目从新快照中隐藏,等待 DRAIN_GRACE 让租用的调用结束,取消它们,等待 RETIRE_CANCEL_BOUND,然后继续拆除。
  4. 内核只通过契约注册表接触插件。 改变结果的钩子是内核拥有的注册表,带有文档化的排序与组合方式(只拒绝、只收紧、首个匹配、按优先级和 ID 排序),从不是 kardia 事件:内核不持有 kardia 上下文。结果从不依赖注册顺序,因为插件并发启动。新的扩展点随它的第一个真实使用者一起添加。
  5. effect 体里没有长时间的异步工作。 kardia 从不取消 apply 或异步 effect,那里的循环会阻止插件和它的每个祖先停止;宿主只能限制损害(行在 PLUGIN_START_TIMEOUT 后失败,fiber 一直卡住直到它的 Agent 实例的运行时停止)。apply 校验配置、注册、生成任务;长期工作通过 spawn_scoped_worker(插件注入内核插件提供的 PluginFaults::NAME),或放在插件从 ctx.defer 释放器中停止的工作线程组里(execution 插件的活动监视器)。
  6. 不受检查的根访问留在宿主里。 只有拥有 kardia 根的模块宿主(hanafubuki-agent-host,由门面的 AgentHost 配置)和门面从根读取插件状态。插件声明它们用到的东西(PluginDef::inject);领域从不看到 kardia 上下文。
  7. 插件返回错误,从不 panic。 插件的生产源码不含 .unwrap() 和 .expect(;失败的 apply 让插件进入 Failed,由宿主报告,配置更新或 retry_plugin 重启它。panic 是 bug,但它留在插件里(宿主在退避后重启插件):kardia 在 apply、effect 体、释放器和事件监听器中捕获它,内核守卫它对插件代码的每次调用。发布构建也是如此:它们展开,panic hook 让 Agent 线程上的 panic 展开到它的捕获点。锁用 parking_lot,从不用 std 的。
  8. 每次 kardia 修改都在 Agent 运行时上运行。 kardia 在环境运行时上 spawn,没有运行时就 panic;挂载或更新插件的宿主方法是异步的,调用方把它们发到 Agent 运行时。

Agent 代码在哪里运行

Agent 运行的所有东西都在 panic 被隔离的线程上:panic hook 让它在那里展开到捕获点,在其他任何地方中止进程。

  • Agent 运行时(hanafubuki-agent-runtime 的 ContainedRuntime,线程名 agent-rt),每个 Agent 实例一个:槽位的启动构建它,槽位一直保留它,直到实例停止(关闭、重启、关闭 Agent)时最后停止它。它运行宿主对 Agent 的每次调用、整个启动(构造与恢复在它的阻塞池上,插件的启动,MCP 的后台启动)、异步的关闭阶段,以及这些生成的东西:轮次与压缩、kardia 的 effect 与释放、作用域工作线程、宿主的故障/退役/重新挂载/重新配置任务、MCP 与模型客户端。它的阻塞池运行 BlockingService 和 Agent 的每次 BlockingOperationPort 调用。
  • 由 Agent 自己的 foundation 隔离。 这些标记和守卫是 hanafubuki-agent-foundation 的线程局部变量,宿主的 foundation 看不到。所以宿主的 panic hook 必须把 hanafubuki_agent::panic::is_panic_contained 作为第二个隔离检查:任一 foundation 说被隔离,panic 就被隔离。
  • Agent 的工作线程全部在 BackgroundWorkerGroup::contained 组中:历史写入线程、MCP stdio 读取线程、记忆监督者(它自己的当前线程运行时也标记它的阻塞池)、execution 插件的活动监视器和 Skill 目录监视器;以及槽位的监督线程(agent-supervisor)。

不是 Agent 线程的地方,panic 仍会中止进程:宿主的线程,以及 Agent 调用的服务的线程(执行器的读取与等待线程)。kardia-hmr 自己的线程(进程访客的 guest-stdin、guest-stdout 和 guest-stderr,WebAssembly 引擎推进 epoch 的 wasm-epoch 线程)会捕获自己的 panic,并杀死它所服务的访客(退出报告给出原因,访客像任何故障之后那样重启);kardia-hmr 自己标记这些线程,访客宿主在构建时用 foundation 的 register_containment_check 注册 kardia-hmr 的检查(kardia_hmr::is_panic_contained),所以 is_panic_contained 在这些线程上也为真。WebAssembly 访客的代码本身在 Agent 运行时的阻塞线程池上运行,陷阱在那里是错误而不是 panic。Agent 代码里新的 spawn 必须落在环境运行时或被隔离的组中,从不落在普通线程上。

扩展点

注册表插件注册唯一性内核何时读取组合方式
ToolRegistryAgentToolHandler扁平工具名,保留名除外(工具名)每个采样步骤,随工具计划内核的流水线
ToolSourceRegistryAgentToolSource工具源 ID每个采样步骤在核心与注册的工具之后规划;失败的工具源按它的信任级别处理
ContextRegistryContextContributor贡献者 ID,且每种类型一个贡献者轮次准入时按类型名收集;按渲染器槽位展示
ContextRendererRegistryContextRenderer(数据)段类型每个模型请求一次快照槽位,然后渲染器的 order,然后类型名
TurnAdmissionRegistryTurnAdmissionContributor贡献者 ID轮次准入时按 rank 与 ID 合并进轮次的 TurnExtensions;失败或返回已有类型的贡献者被略过
PromptContributorRegistryPromptContributor贡献者 ID每个采样步骤一次快照,准备一次,每个请求询问准备的值按 rank 与 ID 合并(重复的类型被略过);片段按槽位加入对话开头的段
ApprovalRuleRegistryApprovalRule规则 ID随每个步骤的工具计划冻结拒绝 > 需要用户 > 会话许可 > 模式
ContinuationHookRegistryAgentContinuationHookRegistration(提供者 ID、钩子 ID);最多 MAXIMUM_CONTINUATION_HOOKS每个采样步骤按优先级、提供者 ID、钩子 ID
ToolLifecycleHookRegistryToolLifecycleHookRegistration(提供者 ID、钩子 ID);最多 MAXIMUM_TOOL_LIFECYCLE_HOOKS随每个步骤的工具计划冻结按优先级、提供者 ID、钩子 ID:调用之前,第一个拒绝即拒绝;调用之后,每个钩子的上下文(工具生命周期钩子)
ToolPresenterRegistryAgentToolPresenter工具名,即它的 tools() 列出的每一个界面询问时:调用开始时,以及调用结束后该工具唯一的呈现器,否则回退显示(工具呈现器)
ObserverRegistryAgentObserver观察者 ID每次持久提交之后全部,按提交顺序

会话的能力范围在该会话中排除它关闭的插件的工具、工具来源、上下文与轮次准入贡献者、提示贡献者和继续钩子;审批规则、工具生命周期钩子、观察者、渲染器和工具呈现器始终适用。

插件代码中的 panic

内核只在守卫下调用插件代码:RegistryEntry::guard 或 guard_async(条目知道它的所有者),或在手头没有条目时用 PluginFaults::guard 与 guard_async;门面的功能调用也是如此(宿主、配置与状态)。那里的 panic 以 error 级别记录,作为条目所有者的 PluginFault(插件、ExtensionPoint、有界的 panic 消息)报告给 PluginFaults,并变成 PluginPanicked,由调用方转为那次调用自己的错误路径:

调用panic 意味着
工具 availability(注册或来源)该工具在这一步被略去(Omitted)
工具 permission、invoke工具错误“the tool failed with an internal error”,与任何失败的工具相同
工具源 contribute工具源失败:由它的信任级别决定(Optional 的被略去)
上下文与轮次准入 contribute该贡献者在这次准入中被略过
提示 prepare该贡献者的值被略过,附警告
提示 contribute该贡献者不渲染片段
审批规则 evaluate一个指名插件的拒绝:规则失败时关闭,从不是“没有意见”
继续钩子钩子失败:由它的失败策略决定
工具生命周期钩子钩子失败,没有发言权:调用照常运行,输出保留
钩子的 applies(继续或工具生命周期)该钩子不适用
观察者 observe跳过该观察者;其他观察者照常通知,提交的线程从不展开
工具呈现器 subject、display它不给主题(保留计划中工具自己的),或回退显示
spawn_scoped_worker 的主体工作线程结束,带标签记录
功能调用(feature call)该调用返回 FeatureUnavailable

panic 消息进入日志和插件状态,从不进入模型。mcp 插件自己隔离一种 panic:McpTool::invoke 在 catch_panic_async 下运行服务器调用,所以那里的 panic 是那次调用的错误和那台服务器的故障,从不是插件的。内核从不跨守卫调用持有锁,所以守卫不改变加锁顺序。身份访问器(id、descriptor、kinds、rank、trust、呈现器的 tools)是数据,不被守卫。

故障之后:插件被停止并报告 failed(panicked in <extension point>: <message>),宿主在重启策略的下一个延迟后自动再次挂载它(2 秒、10 秒、30 秒,10 分钟内三次);超过之后直到 retry_plugin、新配置或重新开关它(在拆除结束之后)。启动失败(而不是 panic)的插件不会自动重启。

Kardia 0.3 的恢复策略保持默认的 Manual,包括已安装 Guest 的 loader 条目。自动重启只由 Agent 自己的宿主和 Guest 监督器按照 RestartPolicy 调度,不同时开启 Kardia 的自动恢复。

插件调用的上限

内核对插件的异步调用都不能无限期地拖住一个轮次:每个都有期限;超过期限,内核取消调用的令牌、丢弃它的 future,走那次调用的错误路径,所以挂起的插件只损失它本该贡献的东西。内核自己设定的期限是 AgentHardLimits::plugin_call_deadline(10 秒):

调用上限超过上限
上下文与轮次准入 contributeplugin_call_deadline;准入的取消,或丢弃准入该贡献者被略过,记为插件的问题;被取消的准入失败
工具源 contributeplugin_call_deadline工具源失败:由它的信任级别决定(Optional 的被略去,Required 的让计划失败)
提示 prepareplugin_call_deadline该贡献者的值被略过,附警告
工具 permissionplugin_call_deadline工具错误“the tool's permission check did not finish within N s and was stopped”
工具 invokeToolDescriptor::timeout,否则轮次的 tool_idle_timeout(10 分钟)工具错误“the tool did not finish within N s and was stopped”
继续钩子、工具生命周期钩子轮次的 tool_idle_timeout继续钩子由它的失败策略决定;工具生命周期钩子没有发言权
工具 availability、钩子的 applies、提示 contribute、审批规则 evaluate、观察者 observe、工具呈现器 subject 与 display无:同步、纯函数,按约定有界(在这里挂起会阻塞调用方;这些调用不做 I/O)

轮次自己的取消也结束轮次中的每个调用;上下文与轮次准入的调用在轮次存在之前运行,所以它们观察准入令牌的子令牌,准入被丢弃时它也被取消。内置行和宿主行与其他插件一样受这些上限约束:按时回答的插件行为不变。插件的启动和停止有各自的上限(宿主、配置与状态)。

工具

  • 工具的 ToolDescriptor 在注册期间(工具源的工具:在这个步骤中)固定模型可见的规格、暴露方式、执行类别、效果(注册或来源的 ReadOnly 工具是计划模式中仅有的工具)、活动动作、记忆效果和超时。availability 可以把它作为自由格式工具提供,或在某一步略去它(ToolPlanContext)。
  • 内核拥有流水线,插件不能改变它的顺序:模式策略、permission、需要时审批(审批规则,然后会话的许可,然后权限模式的流程),然后带一次性审批的 invoke。invoke 重新检查审批与它要运行的调用一致。
  • 流水线在步骤的门下运行:一个在途许可,然后 ConcurrentRead 工具取得读访问,否则独占访问,先到先得,所以 permission 能看到同一步骤之前的调用做了什么。等待的审批(用户或审查模型)释放门,批准后再取回;同一步骤的其他调用同时运行,用户在每个步骤中一次只被问一个提示。等待期间其他调用运行后,批准的动作可能已经过期;invoke 中的重新检查(verify_tool_approval,领域自己的检查)把它变成调用的错误,从不运行未经批准的东西。轮次被取消之后才被接受的调用不会开始。
  • invoke 在 ToolDescriptor::timeout 内运行,为 None 时在轮次的 tool_idle_timeout(10 分钟)内;permission(它自己受 plugin_call_deadline 约束,见插件调用的上限)和审批等待都不计时。超时的调用被取消、future 被丢弃,模型读到“the tool did not finish within N s and was stopped”;轮次继续。调用留在 BlockingService 上的工作观察取消并自行结束。自身上限在等待用户时暂停的工具把超时设在那个上限之上:MCP 工具的超时是服务器的调用超时加一次 elicitation 等待(MAXIMUM_MCP_ELICITATION_WAIT)。
  • 输出按调用顺序提交,每个都在之前每个调用的输出提交后尽早提交。以错误结束的调用(包括轮次的取消)不提交;同一步骤的其他调用照常运行到结束并提交,因为它们的效果已经发生,然后步骤返回第一个错误。取消时只有未完成的调用得到合成的中断输出,模型在它的调用之后立即读到。
  • AgentHardLimits::maximum_sampling_steps 和 turn_deadline 默认为 None:不限制采样次数和整轮时长。宿主可以设置 Some(count),使超过次数的下一次采样以 LimitExceeded { "sampling steps" }(budget_exceeded)失败,之前的输出都已提交;也可以设置 Some(duration),到期时内核像用户取消一样取消轮次(挂起的审批与提问被中止,完成的调用被提交),以 TurnDeadlineExceeded(deadline_exceeded)结束。这些可选限制不让模型看到。单项操作超时、轮次资源预算和手动取消仍然生效。
  • AgentHardLimits::maximum_history_items 默认为 None。宿主可以主动设置历史条数上限,保留历史的字节限制仍然有效。大量短工具调用不应仅因上下文超过 1,024 条记录而失败。
  • AgentTurnBudgetPolicy 中的累计输入/输出 token、工具调用次数、工具输出字节数和钩子片段字节数均为可选限制,默认全部为 None。maximum_consecutive_stalled_steps 也默认为 None,因为重复调用可能是正常轮询。显式预算仍须为正数并会执行;不限制时也继续统计用量。并发调用、待处理输入和操作空闲超时仍保留限制。独立应用的会话驱动会在每个新回合前应用当前配置,包括从历史恢复的会话。
  • 阻塞工作在注入的 BlockingService 上运行;调用观察 ToolInvocation::cancellation。ToolInvocation::progress 只排队(report 从不等待),可以来自调用或比它存活更久的监视线程;内核按顺序提交会话的进度。
  • 只在 Agent 外部某物提供时存在的工具(MCP 服务器的目录、记忆设置)来自 AgentToolSource。内核每个采样步骤用 ToolSourceStep 询问每个工具源一次,它返回 SourcedTool:为这一步构建的 AgentToolHandler,加上计划记录的身份(提供者 ID、工具 ID、代次、命名空间说明、活动主题)和它的 ToolSourceTrust。工具不变时保持身份稳定,工具变了就改变身份:延迟工具的选择(ToolSelection 历史条目)按身份命名,内核按身份只校验一次工具的 schema 和规格(AgentToolSpecCache)。
  • 工具源的工具与注册的工具一样规划和运行,有两点不同:内核在 permission 之前按它的 schema 检查参数;它的信任是外部的:无法规划的 Optional 工具被略去(在 tool_catalog_omissions 中报告),Required 的让计划失败。名字冲突两者都不是(见工具名)。被询问时插件正在停止的工具源被略去,无论信任级别,所以关闭插件从不让步骤失败;在 plugin_call_deadline 内没有回答的工具源与返回错误的工具源一样失败。直接目录超出预算时只延迟工具源的工具。
  • 工具源可以随贡献返回 ToolPlanLease;计划保留每个租约,每个调用以 ToolInvocation::plan_leases 收到它们。用 ToolInvocation::plan_lease::<T>() 找自己的,从不向下转换 Arc。
  • 调用由谁发起见 ToolInvocation::context.origin:ToolCallOrigin::Model,或者用户输入的命令(! 命令)为 User;它由内核根据轮次设置,任何参数都不能设置它。User 调用由内核直接批准,除非有审批规则要求由人决定;执行工具把它记为 ApprovalOrigin::User,等它的命令退出,并在调用被取消时终止命令。
  • 轮次数据以 ToolInvocation::turn(按类型存放的 TurnExtensions)到达调用:轮次准入贡献者为轮次冻结的内容。用 turn.get::<T>() 读取,缺失的值视为工具错误。契约只命名内核自己读取的值(SelectableSkills)。
  • 工具通过随 ToolResult 返回 ToolContextFragment 向对话加入指令。内核在输出之后立即把它作为 source 指名的 Skill 的上下文提交,每个轮次每个 Skill 一次,不是 Skill ID 的 source 变成工具错误。
  • 内核自己的工具(AgentCoreTool:new_context、update_plan、request_user_input,以及压缩工具 compress、decompress、search_context、acp_status、acp_cache、absorb、acp_retrieve、acp_rule)作用于轮次或会话的压缩状态,不是插件;压缩工具只在会话的压缩策略为 hierarchical 时被规划,计划模式下也是,最后三个还要求各自的功能开启。search_tools 和 tool_list(计划对延迟工具的发现工具)也不是插件。连同原生 tool_search,这十四个名字是 RESERVED_TOOL_NAMES:插件不能用其中任何一个注册工具。
  • 活动动作是开放的标识符(AgentActivityAction);界面为认识的名字加标签,否则显示通用的工具标签,所以新工具不需要前端改动。

工具仍可返回内嵌图片。内核在完成输出限额处理后将图片正文存入历史附件并持久化引用,保留内容顺序和资源元数据;Provider 仍会收到图片正文。宿主的历史存储通过 stage_tool_image_attachment 保存这些已校验、未经再次规范化的工具图片。读取转录并调用 present_tool_call 的界面再以已提交条目的图片引用调用 with_image_attachments,即可显示原始媒体大小而无需读取图片文件;tool_display 会自动完成这一步。

工具名

  • 每条工具路径都使用共享名称接口:注册名称使用 ToolName::parse / ToolName::namespaced 和 flattened_alias();返回或持久化的调用转换成文本时使用 flattened_tool_call_name(namespace, name)。范围包括审查证据、记忆与压缩、导出、CLI/TUI 显示、诊断和拒绝提示。该函数位于 model-api,由内核和门面重新导出;使用方不手工拼接 namespace__name,也不丢弃命名空间。持久化保留原始二元组,执行匹配和进度身份也区分该二元组与扁平别名;不通过去前缀或拆分扁平名称猜测另一个工具。
  • 内部模型请求遵循相同的身份规则。没有命名空间的强制结果工具(标题、回顾、记忆提取)和记忆工作区工具只接受对应的精确顶层名称。权限审查不提供工具,并拒绝工具调用形式的回答。纯文本结构化请求附带完整输出 schema;审批的严格解析规则不变。
  • 工具的名字是它的 ToolName(命名空间段与本地名)。注册表与规划器按扁平形式(namespace__name)索引它,这个字符串从不被反向解析。
  • ToolRegistry::admit 拒绝扁平名是保留名、已经注册或长于工具 ID(128 字节)的注册。RegistrationError 让注册的插件在启动时失败,什么都不注册;其他插件和轮次不受影响。
  • 线路名按请求决定:assign_provider_names 在为步骤的协议构建计划时把它写进每个计划工具的提供者规格。协议接受命名空间时(Responses),带命名空间的函数保留命名空间与本地名;其他情况,以及命名空间已被另一个提供者使用时,名字被扁平化。每个名字适配到 ToolProviderCapabilities::maximum_tool_name_bytes(Responses 128,按 namespace__name 计;Anthropic Messages 128;Chat Completions 64,OpenAI 的函数名上限)。
  • 名字按扁平形式唯一,tool_search、search_tools 和 tool_list 为计划的工具发现保留。按规划顺序(信任,然后名字、提供者 ID、工具 ID)第一个工具保留名字;之后冲突或过长的被截断,并以 _ 加它 (provider id, tool id) 哈希的 12 位十六进制结尾,每一步都相同。冲突(只有工具源的工具会冲突,因为注册拒绝其他的)在 tool_catalog_omissions 中以“renamed to <name>”报告,工具仍被规划。名字从不让步骤失败。
  • 返回的调用按它的 (namespace, name) 在计划中查找解析(AgentToolPlan::resolve_call);请求中没有的名字是未知工具。解码器把提供者的命名空间与名字分开返回,历史记录两者,所以 Responses 以命名空间回放调用,没有命名空间的协议以 namespace__name 回放。
  • schema 按同样的按协议规则降级:设置了 strict_json_schema 能力的协议(Responses)收到完整 schema;没有的收到可移植的关键字(portable_model_schema)。工具从不发送 strict。内核无论如何按完整 schema 校验参数。

模型的工具参数

模型的参数被容错读取;错误是模型作为工具结果读回的、指明字段的错误,从不是失败的轮次。

  • 没有参数类型使用 deny_unknown_fields,没有辅助函数拒绝它不认识的键:未知键被忽略。忽略它从不扩大运行的范围,因为能力(审批、回执、已解析的路径、执行器 ID)从来不是参数,调用仍然经过 permission 和审批。唯一的例外是属于同一工具另一个动作的值:Hanafubuki 的 provision_instance 拒绝所选动作不接受的非空属性,因为它的动作会创建和删除实例。
  • 缺失或为 null 的可选字段视为未提供。语义上必需的字段(cmd、path、delete_path 的 recursive)保持必需。
  • 超出范围的上限被夹紧到边界内并附说明(clamped_u64/clamped_usize、ArgumentNotes,由 ToolResult::with_argument_notes 附在结果后);保护安全的上限(字节或深度上限)夹紧到上限,从不超过;省略的取默认值。包含关系不是上限:路径按原样传入,由领域解析和包含。
  • decode_arguments 指明错误所在的字段(invalid tool argument plan[1].status: ...)。
  • 工具源工具的参数按它的 schema 检查(validate_dynamic_tool_arguments);检查不认识的 type 不约束任何东西,整数形式的数字是 integer。
  • 步骤无法运行的调用会被回答,从不是协议失败,它的输出对每种协议都保持调用/输出配对有效:步骤没有提供的名字(未知、Hidden、模式隐藏、与提供者不兼容)得到同一个错误“no tool named <name> is available in this step”,所以隐藏的工具与不存在的无法区分;尚未接受的延迟工具得到带 search_tools 恢复方法的发现错误;无法解析或超过 maximum_tool_argument_bytes 的参数得到带 512 字节预览的错误;格式错误的 search_tools 或 tool_list 得到指明字段的错误。

工具呈现器

界面如何显示一个工具的调用,归它的插件管:ToolPresenterRegistry 中的一个 AgentToolPresenter,负责它的 tools() 列出的工具(扁平化后的名字)。它对模型不可见:请求不变,golden 保持不变。

  • subject(tool, arguments) 是调用作用的对象:命令行、路径、查询。内核在调用开始时询问它,用的是工具收到的参数(按其 schema 规范化后),并把它作为 tool_started 的 presentation.subject(exec --json 事件)以及活动的呈现发送出去:取第一行,截到 200 个字符(MAX_TOOL_SUBJECT_CHARS)。没有时保留计划中工具自己的主题(来源工具的活动主题,search_tools 和 tool_list 的 tool discovery)。
  • display(tool, arguments, output) 是调用结束后显示的内容,一个从已提交的 ToolOutput 读出的 AgentToolDisplay:Command、Patch(AgentPatchPreview)、FileRead、Listing、Search、WebSearch、WebPage、Mutation(移动或删除的路径)、Text、Fields 或 Content(逐项的输出,AgentOutputBlock:Text,按媒体类型和解码后字节数 bytes 描述的 Image 和 Audio,Link,Resource;从不带图片、音频或二进制资源的数据)。它从不是事件,因为事件会进入日志并由 exec --json 打印,而显示内容可能和输出一样大:界面向门面询问,AgentHandle::tool_display(session, call_id) 从历史中读回调用及其输出(在界面自己的线程之外),对已经读到的转录则用 present_tool_call。处理器在 ToolResult.display_metadata 中返回的内容(AgentToolDisplayMetadata,例如命令输出的颜色 styled_output)与输出一起提交、从不发给模型,由注册表加到显示上:Command 的 output 与之相符时成为它的 styled;Patch 的文件和块与之相符时,patch_hunk_starts(每个文件的每一块应用到的位置,AgentPatchHunkStart { old_line, new_line },由 apply_patch 返回)成为各文件的 hunk_starts,即各行的行号。
  • 回退显示。 宽容地解码,读不了的(工具返回的错误、形状不同的输出)返回 None。此时调用显示 AgentToolDisplay::fallback:内容中带有结构化值时(ToolOutput::json 就是这样生成的)显示结构化输出的顶层键(Fields,嵌套值只给摘要),否则逐项显示它的内容(Content):MCP 的结果显示它的文本项,这些文本项重复了它的结构化内容。structured_output 读取结构化值,排在 with_argument_notes 追加的参数说明之前。没有呈现器的工具(MCP 服务器的、guest 的)显示回退内容,恢复的会话中插件已关闭的调用也一样。
  • 从历史读取时,调用的参数按当时以该名字注册的工具的 schema 规范化;没有这样的工具时就是模型自己的参数。
  • ArgumentSubjects 是那些回退显示已足够的工具的呈现器:每次调用的主题是按工具指定的一个字符串参数。
  • 每个工具名只有一个呈现器:第二个是 RegistrationError,会让它的插件失败。内核在创建注册表时注册它自己的 compress 的呈现器(它的范围和主题,然后是回执和摘要)。
  • subject 和 display 是同步、纯函数且有界的,从不 panic;注册表在 ExtensionPoint::ToolPresenter 处守卫它们。

上下文

  • ContextContributor 声明它产生的类型(ContextSectionKind),每个声明的类型最多返回一个 ContextSection。两个贡献者声明同一类型,或贡献者声明 tool_catalog_omissions(内核每个采样步骤自己写),都让注册的插件失败。
  • 轮次准入时从一个注册表快照收集段(collect_world_state;贡献者在条目租约下依次运行,每个都在 plugin_call_deadline 内)。失败的贡献者(错误、panic、期限内没有回答、插件正在停止)在那个轮次被略过;未声明的类型、已经产生的类型,或超过 MAXIMUM_AGENT_PLUGIN_WORLD_STATE_SECTIONS(7,宿主的类型在内;Agent 自己的六种已知类型有自己的位置)的插件类型的段也被略过。每种情况都记为插件的问题(PluginFaults::set_issue),插件状态以 warning 显示(Agent 显示为降级),直到那个贡献者再次成功或插件被重新挂载;轮次从不因此被拒绝。没有贡献者返回的类型在那个轮次从世界状态中移除,所以启动失败的贡献者插件让它的段缺席,而不是让每个轮次失败。
  • 宿主上下文从不拒绝它随附的消息或 steering:这个版本无法使用的被带警告地丢弃,超过 MAXIMUM_HOST_CONTEXT_BYTES(4 KiB)的在 UTF-8 边界上截断。
  • 结果按类型名排序收集,所以历史每次都以同样的方式记录;模型按渲染器的顺序看到它们。
  • ContextRequest 携带会话 ID、会话模式、轮次的权限模式、提交轮次时用户消息的文本(user_message,没有消息的轮次为 None,例如实施计划)和宿主输入的 TurnExtensions,Agent 原样传递、从不读取,只是门面会加入轮次的 SandboxPolicy(sandbox 段由它渲染)。缺失的值视为“这个轮次没有提供”。长时间的工作在 BlockingService 上运行。
  • 由 JSON 渲染的文本经过 ContextSection::from_json,它对对象键排序,使版本摘要稳定。
  • 每段最多 32 KiB,合计 64 KiB。

上下文渲染器

  • 模型可见、既不是历史也不是工具的所有内容都是某个 ContextSectionKind 的上下文段:世界状态段(持久化,来自 ContextContributor)或提示片段(每个请求,来自 PromptContributor)。段通过它类型的 ContextRenderer 展示给模型,渲染器由拥有该类型的插件注册在 ContextRendererRegistry 中(每种类型一个;无效或重复的类型让注册的插件失败)。
  • 渲染器是数据:ContextSlot、它在槽位内的 order、ContextRole、preamble(这段是什么、它没有什么权威)、epilogue 和 versioned(把内容放进 <agent_world_state kind=".." version=".."> 元素)。类型的包装文字在拥有它的插件里,从不在 hanafubuki-agent-model-api 里,后者原样发送片段的角色和渲染后的文本,不匹配任何段类型。没有自己框架的段使用 WORLD_STATE_PREAMBLE。
  • 内核在构建注册表时注册它自己写的类型(tool_catalog_omissions)的渲染器;workspace-context、permission-mode、skills、memory、goal、subagents、review、hooks、plugins 插件、访客宿主和宿主的插件随它们的贡献者注册各自的渲染器。内核不知道任何宿主类型。
  • 内核为每个模型请求取一次渲染器快照。类型没有渲染器的段(插件已停止)不出现在那个请求中;世界状态段留在历史里,下一次准入在没有贡献者产生它时移除它。
  • 顺序:每一串相邻段按槽位(Instructions、WorldState、Capabilities、Memory)、渲染器 order、kind 排序,其他历史条目保留位置;挂载顺序不对模型可见。提示贡献者仍逐步 prepare/contribute,但内核只将变化后的渲染快照(含明确撤销)持久化为 PromptContext,不在每个请求重建开头的提示串。同 kind 的多个片段按原有顺序合成一个快照,角色由渲染器提供,不新增拒绝规则。世界状态替换和移除也保留历史位置,并明确取代或撤销旧段。相同输入应产生确定的贡献内容,除非上下文确实变化,不要加入时间戳或偶然的遍历顺序。前缀契约 不保证真实渲染器、配置或能力变化后的缓存命中。
  • 顺序值按所有者分段;渲染器在其所有者的区段中选一个空闲的值,放在它的段应在的位置,同一槽位有两个渲染器的插件给每个渲染器各自的值。区段是约定,注册时不检查。
order渲染器
0内核:tool_catalog_omissions
100–499Agent 的能力插件,按清单顺序 100、110、…:memory 100(agent_memory)、skills 110(skill_catalog)、goal 120(goal)、subagents 130(subagent_guidance)、review 140(review_instructions)、hooks 150(hook_context)、plugins 160(available_plugins)
500–599宿主的插件(宿主插件)
700–899Agent 的上下文插件:workspace-context 700(workspace_instructions、workspace_roots)和 701(environment),permission-mode 710(permission_mode)和 711(sandbox)
900已安装插件的代码:每个访客的上下文段和提示,所以它们排在 Agent 和宿主之后,彼此按类型名排序

轮次准入

  • TurnAdmissionContributor 在轮次被接受时产生一次按类型存放的 TurnExtensions。内核把它们冻结在轮次上,交给轮次的每个工具调用和提示贡献者;重启后恢复的轮次没有。
  • 贡献者在内核接受轮次之前按 (rank, id) 顺序在条目租约下依次运行,每个都在 plugin_call_deadline 内(collect_turn_extensions)。错误、panic、期限内没有回答、插件正在停止,或返回另一个贡献者已经返回的类型,都让那个贡献者在这个轮次被略过,像上下文贡献者一样记为问题;结果从不依赖注册顺序。仍会失败的唯一准入是用户明确引用了一个 Skill,而轮次无法解析它:没有 skills 插件的值时,它被拒绝(“the Skill catalog is unavailable”),而不是在没有它的情况下运行。
  • 内核自己只读一个值:SelectableSkills,即显式引用或 $mention 可以选择的 Skill,以及 mention_exclusions(普通 $mention 指向的不是 Skill 的名字)。

提示片段

  • PromptContributor 从轮次的 TurnExtensions、贡献者为这个请求的采样步骤准备的值和会话的上下文窗口(PromptRequest)渲染模型可见的片段。PromptFragment 有一个类型(同一插件注册了其渲染器的 ContextSectionKind)、可选的版本(只有带版本的渲染器显示)和内容。
  • prepare 是唯一异步、允许 I/O 的调用:每个采样步骤开始时一次,内核按 (rank, id) 顺序依次询问步骤快照中的每个贡献者,带 PromptStep(会话、轮次和步骤,以及 tools:该步骤的计划在模式和范围之后提供的工具的名字(即范围模式匹配的名字),所以关于某个工具的指引只在该工具存在时显示),在条目租约下,以轮次取消的子令牌,在 plugin_call_deadline 内。它返回类型化的值,合并进步骤准备的值。插件正在停止的贡献者什么都不准备;错误、期限内没有回答,或之前的贡献者已准备的类型,让那个贡献者的值带警告地被略过。只有轮次的取消让步骤失败。
  • contribute 是纯函数且有界(没有 I/O、不阻塞、没有每次调用的状态,从不调用内核),所以内核不带租约调用它。缺少它要渲染的东西时什么都不返回。需要的外部值在 prepare 中加载,从不在 contribute 中。
  • 内核从不在会话锁下运行贡献者:在锁下读取轮次的扩展与上下文窗口,释放锁,准备步骤并渲染片段,再在锁下构建请求。它在准备采样步骤时这样做一次,那一步计数的每个请求都使用这一次渲染。
  • 插件以 token 衡量的预算使用 hanafubuki_agent_contracts::{estimate_tokens, token_budget_bytes},即内核接受请求所用的估算。
  • 内核自己读取一个准备的值:AgentMemoryStep,步骤的记忆策略。没有它的步骤(memory 插件关闭)原样显示回答,不提交引用,也不标记污染。
  • 指令不是提示片段:会话的指令和内核的计划模式提示是会话配置。

审批规则

  • 拥有某个动作的插件用 ApprovalRule 收紧它的审批,与产生该动作的工具一起注册。没有单个插件拥有的规则留在内核里。
  • evaluate 检查 ApprovalAction 和发起请求的会话的来源(Option<AgentSessionOrigin>:没有父会话的会话为 None),所以一条规则可以只对某一种子会话生效(review 插件的规则)。它是纯函数且有界,所以内核不带租约调用它。一个步骤的每个调用都由步骤冻结的 ApprovalRuleSnapshot 判断,所以规则不会在仍在排空的调用之下消失。
  • 规则返回 None(没有意见)、RequireUser 或 Deny { reason }。组合是单调的:任何拒绝都以它的原因作为模型可见的错误拒绝调用(多个拒绝的不同原因排序后合并);否则任何 RequireUser 让动作成为 Manual,即使在 AutoReview 或 FullAccess 下;否则由轮次的权限模式决定。
  • 规则从不放宽审批。工具声明为 NotRequired 或 Forbidden 的动作从不到达规则;硬拒绝属于工具的 permission。
  • 用户可以对 Manual 模式的提示回答 AllowForSession:会话中同一工具((provider id, tool id, generation))之后的动作无需询问即被授权,无论轮次的模式如何,但只在规则没有意见时。规则的 Deny 仍然拒绝,它的 RequireUser 仍然询问,而那样的提示不提供 AllowForSession。许可只保存在会话的运行时状态中。

继续钩子

  • 钩子请求在候选的最终回答之后让轮次继续。内核在开始采样步骤时为注册表取快照;如果步骤以最终回答结束,就按顺序询问钩子。每次调用持有条目租约,观察轮次取消的子令牌,受轮次的工具空闲超时限制。插件正在停止的钩子被跳过。
  • Pass 询问下一个钩子,Stop 结束轮次而不询问其余钩子,Continue 返回 1 到 MAXIMUM_CONTINUATION_FRAGMENTS_PER_HOOK 个非空片段(每个最多 MAXIMUM_CONTINUATION_FRAGMENT_BYTES),内核把它们作为 ContinuationContext 提交后再次采样。失败或超时在 FailTurn 下让轮次失败,在 Ignore 下被跳过。hooks 插件为用户的 Stop 钩子注册一个(优先级 0),goal 插件注册一个让活动目标继续推进的钩子(优先级 100,所以结束轮次的 Stop 钩子在前);两者都是 Ignore。
  • 交给钩子的 AgentContinuationContext 携带 background,一个 AgentBackgroundWork { agents, terminals }:会话的后台工作尚在进行的部分,轮次结束后它会唤醒会话(仍在工作的子代理,两层,在已加载的会话中计数;终端从 R5 起),唤醒策略关闭时为空。goal 钩子在它不为空时放行,于是轮次结束,被唤醒的轮次继续推进目标。
  • applies(context) 是内核在取得租约之前询问的纯粹、有界的检查(默认适用):不适用的钩子既不被调用也不被报告,所以无事可决定的钩子不增加事件。
  • 内核自己在任何钩子和轮次之外提交一种 ContinuationContext:用户批准了自动权限审查拒绝的操作的说明(approve_denied_action),provider 为 kernel,hook 为 approved-denied-action。插件钩子不使用这两个 ID:权限审查把它们下的片段读作用户的授权(权限与审批)。

工具生命周期钩子

  • ToolLifecycleHook 在采样步骤的每个工具调用前后运行,只要这一步提供该工具且参数可用:注册的与来源的工具、内核自己的工具、search_tools 和 tool_list 都一样(被拒绝的调用没有)。内核随每个步骤的工具计划冻结注册表的有序快照,按 (priority, provider id, hook id) 排序,从不按注册顺序。
  • applies(phase, call) 是内核先问的纯粹、有界的检查,不带租约:不适用于某个调用的钩子既不被调用也不被报告,所以无事可做的插件不让调用付出任何代价,也不增加事件。
  • 调用之前(before_tool_use):在模式检查、permission 与审批之前,并在步骤的门外,所以慢的钩子不拖住其他调用。钩子按顺序询问,第一个 Deny { reason } 就结束询问:调用不运行,reason 是它模型可见的错误。组合是只拒绝的:钩子可以拒绝调用,从不能放行权限模式或审批规则不会放行的调用。
  • 调用之后(after_tool_use,带调用的输出,包括错误输出;被拒绝的调用没有):AddContext { fragments } 给出 1 到 MAXIMUM_CONTINUATION_FRAGMENTS_PER_HOOK 个非空片段,每个最多 MAXIMUM_CONTINUATION_FRAGMENT_BYTES,内核在这一步的每个输出都提交之后,以钩子的提供者与钩子 ID 把它们作为 ContinuationContext 提交:夹在两个输出之间的片段会拆开协议的一批工具结果。超出这些界限的片段算作钩子的失败。
  • 每次调用持有条目租约,观察轮次取消的子令牌,受轮次的工具空闲超时限制。失败、超时、panic 或插件正在停止的钩子没有发言权:调用照常运行,它的输出保留。钩子是用户的策略脚本,坏掉的脚本不应让 Agent 的工具停摆;必须失败即拒绝的规则是审批规则。轮次自己的取消结束轮次。
  • 每个被调用的钩子都报告到轮次的事件中:之前是 hook_started,之后是 hook_completed,带它的提供者与钩子 ID、调用 ID、事件(pre_tool_use 或 post_tool_use)和结果(passed、denied、added_context、failed、timed_out)(exec --json 事件)。
  • 钩子使用继续钩子的身份类型,因为它的片段以这些身份提交;它不使用内核的 kernel/approved-denied-action。

观察者

  • AgentObserver 通过 AgentNotification 得知内核提交了什么:TurnAdmitted(带轮次的 AgentTurnOrigin,以及准入后由 Agent 给出的会话标题 automatic_title)、SamplingCommitted(带回答的记忆引用)、TurnFinished、MemoryContributionChanged(带原因)、SessionArchived/SessionRestored、BackgroundWorkChanged(事件已持久地离开唤醒队列)、WakeEventQueued(会话的唤醒队列上排入了一个事件,核心行 agent-wake 的调度器据此唤醒空闲的会话)。通知随它的第一个使用者添加。
  • 内核在提交持久化且其事件发出之后通知,从不在会话锁下,按提交顺序。失败的提交不通知任何东西。
  • observe 是同步的,在提交线程上运行:它通知一个工作线程或做一个小的有界本地更新,从不等待内核。它不返回任何东西,所以不能改变结果;必须持久化或到达模型的东西不是观察。
  • 调用不持有租约:插件正在停止的观察者从它开始退役起就被跳过。
  • 观察者启动的后台工作在插件拥有的工作线程中运行,从 apply 用 spawn_scoped_worker 生成,通过观察者只 try_send 的有界通道喂给它;插件停止时工作线程被取消并等待。它通过应用构造的窄端口(titles 插件的 AgentTitleApplication)到达内核,从不通过门面;它做的内核修改是比较并交换,所以用户在此期间做的事优先。

能力范围

会话的能力范围(AgentCapabilityScope,保存在它的 AgentSessionConfig 中)是它的角色所收窄的东西:允许和拒绝哪些工具、关闭哪些插件的贡献、把权限模式限制在多严。它是内核拥有的数据,在内核本来就取快照的地方读取,不是扩展点:插件既看不到也设置不了它。

  • 只收窄,从不放宽。 范围只会移除工具和插件贡献、收紧模式。子会话的范围是父会话的范围再被它自己的收窄(两者的允许列表、任一方的拒绝模式和关闭的插件、更严的上限),所以子会话从不比父会话宽(子代理自己的范围是 spawn_agent 的 agent_type 指定的角色的范围);分叉保留源会话的范围。
  • 内核在哪里应用它,每处都是它本来就要取的快照:
位置规则
工具计划在模式策略之后,插件注册的或来源提供的工具,只有当它的插件没有关闭、每个允许列表都有匹配它的模式、且没有拒绝模式匹配它时才进入计划。内核自己的工具(RESERVED_TOOL_NAMES)和工具发现工具从不被过滤。 被排除的工具就是不存在:调用它得到 "no tool named <name> is available in this step",它不出现在搜索或列举结果中,也不出现在 tool_catalog_omissions 中(它是被有意排除的,不是丢失了)。历史中对它的延迟选择被忽略
工具来源关闭的插件的来源不会被询问
上下文贡献者、轮次准入关闭的插件的贡献者不会被询问:它的类型从会话的世界状态中移除、它的值缺失,与插件停止时一样
提示贡献者在会话的每个请求中(包括压缩的估算)既不准备也不询问
继续钩子不进入该步的快照
权限模式轮次冻结它的模式(会话的,或配置的)与上限中更严的那个。AllowForSession 不受影响:它本来就从不越过规则
  • 从不过滤,无论范围怎么写:
  • 所有者。 plugin:<owner> 模式和 plugins_off 的条目匹配注册表条目的所有者:一行的名字,或已安装插件代码的 guest:<id>。不指向任何插件的条目被保留,没有作用;核心行(agent-kernel、agent-host-services、agent-wake)从不关闭。
  • 唯一形式。 每次创建、更新和恢复都会规范化它(normalize_session_config):允许列表排序、各只一次,核心行从 plugins_off 中去掉。超过 128 个模式、或有一个超过 256 字节的工具范围,只允许内核自己的工具:去掉其中任何模式都可能放宽它。
  • 持久化在会话的配置中,逐字段读取:读不了的字段回退到默认值,本构建读不了的模式从它的列表中去掉。空范围(default)不写入记录,所以没有角色的会话写出的字节与角色出现之前相同,没有这个字段的历史以空范围打开。角色的指令保存在它旁边(role_instructions),在每个请求中追加在基础指令之后,所以选择模型会保留它们。
  • 内核读取其值的两个插件。 skills 关闭时轮次没有 SelectableSkills:显式的 Skill 引用被拒绝,提示 "the Skill catalog is unavailable"(轮次准入),$mention 不选中任何 Skill,Skill 工具缺失。memory 关闭时记忆摘要和记忆工具缺失,该步没有 AgentMemoryStep(回答原样显示,没有引用);会话仍按它的贡献模式贡献记忆,因为观察者从不被过滤。
  • 内核的 loop_contract 测试集(scope.rs,来源见 sources.rs)和门面的 tests/sessions/roles.rs 固定这些规则;explorer golden 固定一个有范围的请求(没有 spawn_agent,所以也没有子代理指引)。

外部产出:MCP 服务器、Skill、Web、记忆

MCP 服务器、Skill 作者或提取模型产生的东西被容错读取;一个坏条目只损失它自己,严格的规则(MCP 配置、凭据与 OAuth、路径包含、URL 校验、持久化格式)不变。

  • MCP 目录逐个工具构建。每个名字段按字符清理为 [A-Za-z0-9_-],仍超过 128 字节的被截断并加哈希后缀。schema 无效或过大、名字无法编码或之后重复的工具被跳过;超过 16 KiB 的说明在字符边界截断,无效的输出 schema 被丢弃。每种情况都是服务器的 Warning 诊断;服务器保持连接,即使没有可用的工具。
  • MCP 注解是用户配置的服务器给的提示,从不是授权。 readOnlyHint 为真且 destructiveHint 不为真的工具是 ConcurrentRead、ReadOnly;其余都是 Exclusive、Mutating。每个 MCP 工具的记忆效果都是 PollutesContribution。审批不读只读提示:服务器(或工具)的审批策略决定,Allow 只对 destructiveHint 为假的工具跳过审查,缺失的提示算作破坏性的。
  • MCP 存活:连接的传输知道 rmcp 的循环何时结束;服务器一侧结束时,服务器以原因 Failed,条目退役,管理器按模块宿主的 RestartPolicy 用关闭的连接打开时的配置和密钥重连它。来自外部的连接(用户的连接或刷新、设置、凭据或代理的变化)清空窗口,关闭取消已安排的重连。步骤保留它规划时的连接;租约的连接已关闭的调用返回 McpError::CatalogChanged,不请求审批。
  • MCP 输出:无法解码的内容块变成文本 [unsupported MCP content: <type>];超过 64 项的保留 63 项加一条说明;带参数的 MIME 类型取基础类型,接受无填充的 base64。
  • Skill:SKILL.md 的 frontmatter 与 openai.yaml 逐字段读取:可选键类型错误时丢弃该键并记录问题,超过 96 字符的名字或超过 4096 字节的说明被截断,根目录下无法读取的目录被跳过。name 与 description 的类型保持严格。allowed-tools 是未知键:Skill 从不增加或限制工具。声明的 MCP 服务器未就绪的 Skill 在轮次中不可用,列为不可用并附原因。
  • Web:服务无法使用的搜索端点配置让 web 行继续运行,只是每一步都略去 web_search;fetch_web_page 继续可用。
  • 记忆:无法读取的笔记行被跳过(按行号记录,从不记录内容)。阶段一的提取输出忽略 schema 未命名的字段,保留命名字段仍能给出的内容;只有完全不是提取对象的输出才让任务失败。整合 Agent 只能写发布会接受的内容,超出上限的写入是指明它的工具错误,让模型缩短后重试。

宿主、配置与状态

  • Agent 对宿主是可选的。它在宿主的界面打开后、在它的启动所构建的运行时上,由捕获的启动组合(AgentLaunch)构建;槽位保留启动组合,所以之后的每个实例(重启、自动重启、重新开启)都以同样的方式启动,代次递增。构造、恢复或启动失败让槽位进入 Failed。
  • 故障要么属于插件,要么属于内核(故障)。插件宿主自己任务(故障跟随者、重新挂载)中的 panic 作为 plugin host 处的内核故障报告给内核故障 sink,会重建 Agent。
  • 无法启动的能力让它的插件失败,而不是 Agent:没有打开的 Skill 目录让 skills 插件失败,没有连接上的必需 MCP 服务器是它的 MCP 状态,无法派生的 web 配置是那一行的错误。恢复拒绝的会话被隔离。
  • AgentHost 是通用模块宿主的 Agent 配置(AgentPlugins,它的 HostProfile):挂载顺序、上限、启用、重新配置、重试、安全模式、故障处理、状态和关闭都属于宿主。属于 Agent 的是:它的行及其描述符、从它自己的设置、宿主代理和各行选项派生的配置(AgentPluginSettings)、来自 disabledPlugins 的启用、它的分组、状态中的贡献、它的 AgentPluginEventSink。选项:module_faults 关闭(它的行是插件,不是应用模块,故障只通过 PluginFaults 到达),automatic_restarts 为默认的重启策略。
  • 行是 AgentPluginRow::unconfigured 或 AgentPluginRow::from_settings,声明它的 AgentPluginGroup:Capability(工具、工具源及其规则,以及门面调用的功能)或 Context(世界状态段)。不从设置派生的配置不存在;插件适配的服务在它的 PluginDef 构造函数中捕获(通过 AgentPluginInputs),不作为配置传递。
  • 描述符与选项。 每一行都恰有一个 AgentPluginDescriptor(crates/agent/src/host/descriptors.rs):它的名字,即它的 PluginDef 的名字;一行摘要,说明它给模型或用户提供什么;以及它接受的选项,一个 PluginOptionSchema(没有则为 None):一列 SettingSpec,即 hanafubuki-agent-foundation::settings 的设置词汇,每个都以行的表中的键为键。选项有标签、一行摘要、种类,行的选项还总有默认值;它是布尔值、有界的整数或数字、文本(是否为机密,是否可为空,长度有界)、路径、带标签的值中的选择,或文本列表。选择的值可以列出它以前的名字,读取时当作它、写入时从不使用,以及它现在不能被选的原因:写入会拒绝它,已经设置的值仍可读取。宿主的行带来它自己的描述符(AgentHostPorts::plugins);没有描述符的行,或被描述两次的名字,会让 Agent 无法构建。选项设在 config.toml 的 [pluginOptions.<row>] 中,按行和键分层(pluginOptions)。AgentPluginSettings 携带按模式解析后的选项,所以行用一个不捕获的闭包派生配置,AgentPluginRow::from_settings(group, plugin, |settings| settings.options_value("<row>")),即通用宿主的 SettingsConfig 函数指针,并用 PluginDef::typed 解码而不会失败:文件中不合适的值已被替换为默认值,整数或数字越界时被截取到边界,同时有一条配置警告,指明层、行和键(/warnings、AgentPluginStatus::options)。选项和 Agent 自己的设置一样是设置:每行的选项是设置目录中的一节(pluginOptions.<row>,在 Plugins 组中,键为 pluginOptions.<row>.<option>),设置页面无需该行的任何代码就能显示并写入它们。两个写入者,按键写入的 write_setting_values 和以补丁写入的 set_plugin_options,都按模式检查每个值,在写入任何内容之前带着原因拒绝写入。subagents 的选项是第一批(它的运行中代理上限和等待界限,在它代码保留的界限内选择),其次是 execution 的(它的命令超时;它的模式由门面用 hanafubuki-agent-plugin-execution 导出的界限和默认值构建,因为该 crate 不能依赖定义模式的 crate;插件通过 ctx.on_update 就地接受更改,因为重启会停止正在运行的终端的输出监视器);web 仍从共享设置派生(设置目录的 web 节)。
  • 从设置派生的插件跟随设置。设置写入后 apply_settings_to_plugins 被安排在运行中的 Agent 的运行时上;宿主从最新发布的设置重新配置它的行。disabledPlugins 是启用状态:重新启用的行只在它之前的 fiber 停止后才挂载,所以它的注册不会与旧的冲突。set_plugin_enabled 是唯一的写入者,拒绝未知名字和关闭核心行。关闭插件不是拒绝工具的方式:审批仍由规则和权限模式决定。
  • 功能调用。 门面作为自己的调用提供的功能(recap_session、suggest_session_title、目标调用、worktree_* 调用、hooks_list、set_hook_enabled、trust_hooks、subagents、interrupt_subagent、start_review、cancel_review、review_targets)属于某个插件行:该行以自己的名字提供一个服务(ctx.provide_arc_as(NAME, Arc<Service>),在 provides 中声明),门面每次调用时通过 ModuleHost::service::<T>(NAME) 解析它,从不保留这个 Arc,因为重试的行提供新的实例。每个这样的调用都经过同一个辅助函数 AgentApplicationService::feature:没有启动插件时先启动它们,把未运行的行变成 AgentError::FeatureUnavailable { feature, reason }(reason 说明原因:“the recap Agent plugin is unavailable: it is turned off”),并在 PluginFaults::guard_async 下运行服务调用,所以 panic 是该行的故障(panicked in feature call: ...)并让它重启,调用方得到 FeatureUnavailable。失去的只有这一个功能,从不是 Agent。功能服务通过应用构造的窄端口到达内核(概要和标题建议用 AgentConversationReader,目标用 AgentGoalApplication,它的写入是会话锁下的比较并交换,所以用户在此期间做的修改优先,子代理和评审用 AgentSessionDriver,派生子代理时的角色用 AgentRoleCatalogReader),插件停止时取消它的模型请求。插件 crate 的服务在该 crate 中声明(WorktreeService、HooksService):门面依赖每个插件 crate,所以不需要契约中的类型。
  • 无需重启就能吸收变化的插件注册 kardia 的更新钩子(Context::on_update,类型须是它的 PluginDef::typed 解码的类型,否则它永远收不到变化);否则插件重启,这会排空它运行中的调用。subagents 就地接受新的运行中代理上限,保留它的服务;新的等待界限则让它重启,因为 wait_agent 的规格写着这些界限;它跟踪的运行在两种情况下都会保留。工具的描述符在注册时固定,所以 spawn_agent 的规格不列出任何角色、Provider 或模型;指引和每次派生则每一步、每次调用都读取角色目录、Provider 及其模型的已知情况,这些变化都不会让插件重启。
  • plugin_status 返回每个插件的 AgentPluginStatus:名字、它描述符的 summary、分组、状态(pending/active/failed/disabled/disposed)、错误文本、活动插件的 warning、是否启用、锁(核心行为 core)、restart、它当前的贡献,以及有选项的插件的 options(AgentPluginOptionsStatus:模式、每个选项的值及设置它的层(默认值为 None),以及它的表中无法使用的设置)。
  • 上限:宿主限制它对 kardia 的每次等待:启动在 PLUGIN_START_TIMEOUT(20 秒)内,释放在 PLUGIN_STOP_BOUND(10 秒)内,重新挂载在释放的上限内。永久卡住的 fiber 随它的 Agent 实例的运行时一起丢弃。
  • 关闭一次性释放 kardia 根,受调用方的期限限制;那时仍在停止的插件作为 agent-plugins 关闭诊断报告。MCP 连接、记忆工作线程、历史和执行由应用拥有,在它自己的关闭步骤中停止,从不在插件的拆除中。

宿主接口

嵌入的应用(宿主)只通过 AgentHostPorts(AgentServiceInputs 的一个字段,每个 Agent 实例构建一次)向 Agent 添加东西。各端口的用法与默认值见嵌入 Agent;规则是:

  • 接口只接受普通值(PathBuf、字符串、映射)或 Agent 自己的类型,从不接受宿主的 foundation、process 或模块宿主类型:它们在两侧是不同的类型,宿主在边界处转换(例如 Agent 的关闭诊断在调用处映射为宿主的)。
  • 宿主插件行与其他插件一样,各带它的描述符:针对契约编写,本页的每条规则都适用,disabledPlugins 关闭它们,安全模式不挂载它们。它们挂载在 Agent 的能力插件之后、上下文插件之前。
  • 宿主输入(AgentTurnRequest、AgentSteeringRequest、AgentFileSearch 的 host)作为 TurnExtensions 原样传给上下文贡献者、HostContextPort 和 WorkspaceRootsPort。携带它的 IPC 输入是宿主的,在宿主一侧转换。
  • 数据目录锁从首次启动持有到关闭,两种模式相同;宿主不为它做任何事。
  • 宿主通过 AgentSlot::list_run_projections 与 get_run_projection 读取 Agent 的运行,映射到它自己的视图。

代码插件

已安装插件的代码是一个访客(代码插件):一个进程外的程序,或在 wasmtime 中运行的 WebAssembly 模块,Agent 只通过访客宿主根据其清单的 contributes 构建的代理来访问它,从不依据访客自己的说法。每个代理调用每个访客都提供的服务(plugin)的一个方法,并有一个期限;超过期限,访客被终止(模块被中断,与它触发陷阱或用尽燃料、内存时一样),并按重启策略重启,该调用走其扩展点的错误路径,所以失败或挂起的访客只损失它自己的贡献,从不让轮次失败。

访客贡献什么

访客的代理在其 fiber 变为活动时注册,作为该 fiber 的副作用(所有者为 guest:<id>,内核的问题与故障都以此命名):它失败、停止或重启时代理随之撤销,下一次启动再重新注册。访客的 fiber 活动后,只有代理注册完毕,它才是 running。宿主无法满足的声明会被略去,并记为该包的问题(AgentPackageGuest.status.issues,连同内核记在 guest:<id> 下的问题);其余照常注册。

声明(contributes)代理上限说明
tools一个 AgentToolSource(plugin:<id>,Optional),在访客运行时规划所声明的工具工具的 timeout(秒,至多 3600),否则为调用期限(plugin_call_deadline,10 秒);内核的上限比它长 2 秒命名为 <plugin>__<tool>(以插件名为命名空间),提供者为 plugin.<plugin>.<marketplace>;身份的 generation 是包版本与声明的哈希;Exclusive、Mutating、PollutesContribution;像 MCP 工具一样请求审批(plugin_tool_call,高风险)。内核按身份校验 schema,略去无法规划的工具,重命名冲突的工具,第三方工具不在 golden 之内。访客失败即该调用的错误,带着它的原话,模型会读到;调用按回退显示呈现,guest 没有呈现器
contextSections(kind、renderer)每个 kind 一个 ContextContributor 和一个渲染器,至多 7 个 kind调用期限的 80%槽位 WorldState、developer 角色、带版本,前言说明这是插件自己的输出、不授予任何东西;kind 必须有效,且不能是 Agent 自己写的 kind;已被其他插件占用的 kind 被拒绝;片段截断到 4 KiB;内核对所有插件合计 7 个插件 kind 的上限同样适用;renderer 会读取,但被忽略
prompt(slot)一个 kind 为 plugin_<name>、位于该槽位(instructions、worldState、capabilities(默认)或 memory)的渲染器调用期限的 80%由于准备好的值按类型区分,访客宿主(plugin-guests)的唯一一个 PromptContributor 同时为每个运行中的访客准备片段,各自有上限;片段截断到 4 KiB
toolLifecycleHooks、continuationHooks一个工具生命周期钩子(tool-use)和一个继续钩子(continuation,Ignore),提供者为 plugin.<plugin>.<marketplace>,优先级 200(排在用户的钩子与 goal 之后)调用期限钩子在其访客运行时生效;失败的钩子没有发言权
observers(事件种类)一个 AgentObserver每个事件一个调用期限种类为 turn_admitted、sampling_committed、turn_finished、memory_contribution_changed、session_archived、session_restored、wake_event_queued;observe 把所声明种类的事件排入队列(至多 64 个,其余丢弃),访客 fiber 的一个 worker 逐个交给访客,不等待结果

不提供(决策 5):审批规则和轮次准入。代理返回给内核(内核会记录)的错误是 Agent 自己的话;访客自己对失败的描述只在 trace 级别记录。

访客能访问什么

  • view 只能访问两个服务,各自位于访客的 loader 条目与其宿主服务条目(<id>#host,以标签 guest:<id> isolate)共享的 realm 中,访客的条目声明了它们(inject),所以访客在它们运行后才启动:workspace,即 { "access": "none" | "read" | "write", "roots": [...] },只在可读时给出 Agent 的工作区根(原生路径,每次 view 时读取;WebAssembly 模块不读任何文件,从不给出);以及 settings,即它的设置([plugins."<id>"].settings),也就是它的 apply 收到的配置。它的清单的 configSchema 降低成的选项同样是设置:设置目录中的一节(plugins."<id>".settings,键为 plugins."<id>".settings.<option>),按键写入,每次只写一个插件的,并按 set_package_settings 的方式检查(configSchema)。
  • 其余一律拒绝。 kardia 的受检访问只能找到访客的 fiber 链上提供或声明的东西,而这条链上没有其他东西带 JSON 视图(view)或是访客的服务(invoke);访客访问不到其他访客(决策 6)。
  • 访客只提供 plugin。 它的元数据必须恰好声明这一项(否则启动失败);kardia-hmr 拒绝它提供任何其他服务(cannot provide "<key>": the plugin does not declare it in provide),在任何东西到达所有插件共享的 realm 之前。这个拒绝是访客自己的错误,与任何宿主调用的错误一样:返回它的 apply 使启动失败;返回它的调用只让那次调用失败,访客继续运行,因为什么也没有被提供。

访客协议

访客是一个 Kardia 访客(程序用 kardia-guest/2,WebAssembly 模块用访客 ABI),元数据为 { "name": <清单中的 name>, "provide": ["plugin"] };它的 apply 收到 { config: <它的设置>, imports: {} } 并提供 plugin。Agent 以一个 camelCase 字段的 JSON 对象调用 plugin 的方法;id 为数字。访客未在清单中声明的方法从不会被调用。

方法参数回答
tool{ name, arguments, call: { sessionId, turnId, callId } }输出:字符串为文本,其他值为结构化内容;错误即该调用的错误
context{ kind, sessionId, mode, userMessage }该片段的文本,或 null(或空白字符串)表示没有
prompt{ sessionId, turnId, samplingStep }片段的文本,或 null
beforeToolUse{ call: { sessionId, turnId, callId, toolName, arguments } }null 表示放行,或 { "deny": 原因 }
afterToolUse{ call, output }(output 为工具输出:content、structuredContent、isError)null,或 { "context": [文本, …] }
continuation{ sessionId, turnId, samplingStep, candidateFinalAnswer }null 或 "pass"、"stop",或 { "continue": [文本, …] }
observe{ event, sessionId, turnId? }忽略

其他回答即该调用失败。同一个访客的调用逐个进行。这些方法之下的 SDK 和线路格式见编写插件。

日志

kardia 的日志通过宿主安装在根上的 LogExporter 到达 log facade。kardia 没有 trace 级别,所以内容日志规则限制在 trace 的内容从不通过 kardia 的日志器记录,访客除外:名为 guest:<id>(GUEST_LOGGER_PREFIX)的插件是已安装插件的代码,它的日志器写下的东西(它的 stderr、日志行、失败)是它的内容,导出器无论其 kardia 级别如何,只在 trace 级别转发并截断(插件访客)。

当前的插件

插件位置贡献
agent-host-services门面(host)BlockingService
agent-kernel内核十一个注册表;tool_catalog_omissions 的渲染器和 compress 的呈现器
agent-wake门面(wake)唤醒调度器:一个观察 WakeEventQueued 和 TurnFinished 的观察者,对没有父会话、有排队事件、没有轮次在运行、策略和 wakeOnBackgroundTasks 打开且唤醒未暂停的会话,告知宿主的 AgentBackgroundEventSink Woken,并在用户的轮次(来源为 User 的 TurnAdmitted)准入时清除会话的暂停;它的 worker agent-wake 对每个收到信号的会话检查一次。核心行,在清单中最先挂载:唤醒由选项关闭,从不由 disabledPlugins 关闭
webhanafubuki-agent-plugin-web搜索、研究、平台/专业数据、天气与抓取工具;类型化插件选项和呈现器;可选本地辅助程序使用 Agent 进程管理器及匹配的提升审批。
workspace-fshanafubuki-agent-plugin-workspace-fslist_directory、search_text、read_file、apply_patch(提供者支持时为自由格式)、move_path、delete_path;其工具的呈现器
view-image门面view_image(模型不接受图片输入和多模态工具输出时略去);其工具的呈现器
executionhanafubuki-agent-plugin-executionexec_command、write_stdin、resize_execution;活动监视器;提供 exec_command 且 TurnWake 打开时的 background_terminals 上下文片段(每一步读取当前超时);git clone 的审批规则;命令在回合的沙箱中运行(门面加入每个回合 TurnExtensions 的 SandboxSettings;没有它的回合不运行命令),模型请求时在沙箱外运行(sandbox_permissions,审批中的 sandbox_escalation);其工具的呈现器;它的环境和 Shell 启动选项,以及 commandTimeoutMinutes(ExecCommandRequest::timeout_ms,每次调用时取得,是其审批的一部分),就地接受更改
mcphanafubuki-agent-plugin-mcpMCP 工具源(每步一个 McpStepBinding 作为计划租约);list_mcp_resources、list_mcp_resource_templates、read_mcp_resource;其工具的呈现器
memory门面记忆摘要的提示片段(agent_memory,槽位 Memory)及其渲染器、步骤的记忆策略、记忆工具源、记忆观察者;其工具的呈现器
skills门面轮次准入:轮次的 Skill 目录与 SelectableSkills;目录片段(skill_catalog,槽位 Capabilities)及其渲染器;skills_list、skills_read、enable_skill、disable_skill(延迟);SkillManagement 的审批规则;其工具的呈现器
titles门面标题观察者与 agent-titles 工作线程:标题仍是临时标题时,在每个用户轮次为会话生成标题,直到模型给出;以自己的名字提供的标题建议(TitleService),即 suggest_session_title 背后的服务
recap门面以自己的名字提供的 RecapService,即 recap_session 背后的服务:根据会话最近的往来生成的概要
threads门面read_thread:分页读取所引用任务当前的用户和助手消息;只读,不复制思考和图片载荷
goal门面get_goal(只读)、create_goal、update_goal;世界状态段 goal(用户角色)及其渲染器;继续钩子 goal/continue(优先级 100,Ignore),在会话目标处于活动状态时适用(会话的后台工作仍在进行时放行,继续钩子),用继续提示、预算用尽通知或目标更新通知让每个最终回答之后继续;以自己的名字提供的 GoalService,即目标调用背后的服务(会话);其工具的呈现器
subagents门面基于 AgentSessionDriver 的 spawn_agent(它的 agent_type 是通过 AgentRoleCatalogReader 读取的可派生角色:子会话是父会话按角色收窄的结果,带着角色的指令;它的 model、reasoning_effort 和 provider 优先于角色和父会话的,由会话驱动在子会话创建之前检查,组合和推理强度在一次提交中设置)、send_message(子代理用 target parent 在父会话上排入一条消息,最多 16 条未读)、followup_task、wait_agent(取走排在会话上的最终状态)、list_agents(带每个子代理的角色,以及从其摘要读取的、它的会话当前运行的 Provider、模型和推理强度)、interrupt_agent;编排指引(subagent_guidance,槽位 Capabilities,按名字列出最多 16 个可派生角色,然后是已启用的 Provider 及其已知的模型和档位,最多 8 个、每个 8 个模型、共 4 KiB,由 prepare 通过会话驱动的 spawn_model_catalog 从派生检查所用的已知模型读取;只给步骤提供 spawn_agent 的顶层会话,spawn_agent 的规格则不列出任何角色)及其渲染器,它关于等待的那一条随轮次的 TurnWake 变化(策略打开时结束轮次并被恢复;关闭时等待);子代理的结束排入父会话的唤醒队列(带回答的完成、错误;中断不排入);以自己的名字提供的 SubagentService,即 subagents 和 interrupt_subagent 背后的服务;它的选项限定运行中的子代理数和等待时间;其工具的呈现器 默认允许两级嵌套,整棵树最多 8 个工作代理,包括等待中的父代理;子代理唤醒每次在插件故障保护下重新解析此服务。
review门面来源为 Review 的会话的评审准则(review_instructions,槽位 Capabilities)及其渲染器;让这种会话保持只读的审批规则;以自己的名字提供的 ReviewService,即 start_review、cancel_review 和 review_targets 背后的服务,基于 AgentSessionDriver 和工作树 crate 的 GitQueries
worktreehanafubuki-agent-plugin-worktree以自己的名字提供的 WorktreeService,即 worktree_* 调用背后的服务:数据目录下的 Git 工作树,每个 git 都经过 Agent 的执行器
hookshanafubuki-agent-plugin-hooks用户的钩子(hanafubuki-agent-hooks):PreToolUse 与 PostToolUse 作为工具生命周期钩子 hooks/tool-use,Stop 作为继续钩子 hooks/stop(Ignore),SessionStart 与 UserPromptSubmit 作为世界状态段 hook_context 及其渲染器;以自己的名字提供的 HooksService,即钩子调用背后的服务(钩子)
plugins门面轮次准入:启用的已安装插件的摘要;"可用插件"片段(available_plugins,槽位 Capabilities)及其渲染器,只在有插件贡献 Skill 或 MCP 服务器的轮次中出现;挂载访客宿主(plugin-guests,hanafubuki-agent-plugin-packages),它的 kardia-loader 为每个运行的代码包提供一个访客 fiber(guest:<id>)(代码插件),每个访客的代理作为其 fiber 的副作用注册,另有访客共用的唯一一个提示贡献者(代码插件);已链接包的目录改动之后在后台重新加载已安装的插件
workspace-context门面上下文与渲染器:workspace_instructions、workspace_roots、environment
permission-mode门面上下文与渲染器:permission_mode、sandbox(轮次的沙箱及离开它的方式)

这也是挂载顺序,宿主的行在 plugins 之后、workspace-context 之前。门面自己的插件在 crates/agent/src/plugins/ 中,因为它们使用 Agent 的服务。工具:8 个内核工具(3 个在每个计划中,5 个压缩工具只在 hierarchical 下)和 38 个注册的工具(3 个延迟);search_tools 和 tool_list 是计划自己的绑定。每一步,工具源加上已连接 MCP 服务器的工具和最多 4 个记忆工具。golden 的默认模式请求(没有 MCP 服务器、记忆关闭、图片输入开启)带 41 个工具:35 个直接注册的工具、3 个内核工具、普通 search_tools、原生搜索和 tool_list;计划模式的带 23 个只读注册工具和 request_user_input。

编写插件

本节讲的是编译进来的 Agent 自己的插件和宿主的插件。可安装插件——代码作为访客运行的包——的写法见编写插件。

先选择它放在哪里:

  • 插件 crate crates/plugin-<name>(hanafubuki-agent-plugin-<name>):绑定一个领域 crate,只需要契约类型(web、workspace-fs、execution、mcp;工具源也一样;还有 worktree 与 hooks,门面调用它们的服务)。
  • 门面里的插件,放在 crates/agent/src/plugins/ 下:需要 Agent 自己的服务时(图片规范化、AgentSkillApplication、AgentMemoryApplication、AgentTitleApplication、AgentConversationReader、AgentSessionDriver)。从 plugins/mod.rs 导出,不改 Cargo。
  • 宿主插件,放在宿主自己的 crate 里:需要宿主的领域时。只针对契约和门面的公开 API 编写,作为宿主在 AgentHostPorts::plugins 中的一行;本页的规则同样适用。见宿主插件。

检查清单:

crate:Cargo.toml 依赖 hanafubuki-agent-contracts、kardia-core,以及工具用到的 hanafubuki-agent-approval、hanafubuki-agent-tool-contracts 和领域 crate;src/lib.rs 只有模块声明和 pub use plugin::<name>_plugin;。
<name>_plugin() -> PluginDef:PluginDef::new(从设置派生配置时用 PluginDef::typed)、.name("<name>")、.inject(..) 带上它用到的每个注册表或宿主服务的 NAME(用 spawn_scoped_worker 时加 PluginFaults::NAME)。apply 用 ctx.get::<T>()? 取得每个服务,用 register(Arc::new(..))? 注册,用 spawn_scoped_worker 生成长期工作,然后返回。
每个工具:带 ToolName::parse 名字、additionalProperties: false 的 JSON schema、暴露方式、执行类别、效果、活动动作和记忆效果的 ToolDescriptor;permission 对读取返回 NotRequired,对修改返回它的 ApprovalAction;invoke 校验参数、观察取消、重新检查修改的审批(verify_tool_approval),在 BlockingService 上运行阻塞工作。
调用值得比回退显示更多内容的每个工具:为它注册的工具写一个 AgentToolPresenter,注册到 ToolPresenterRegistry(工具呈现器),并用录制的参数和输出测试。
生产源码中没有 .unwrap()/.expect(;错误映射为 kardia_core::Error。
接入:在根 Cargo.toml 的 [workspace.dependencies] 中加一项(同时带 path 和 version),在 crates/agent/Cargo.toml 中加依赖,在层表(xtask/src/dependencies.rs)中加一行,在 crates/agent/src/host/manifest.rs 中加一行(它适配的服务通过 AgentPluginInputs 的字段传入),并在 crates/agent/src/host/descriptors.rs 中加它的描述符,名字与它的 PluginDef 相同,带上摘要。Cargo.lock 随之更新。
选项,若它有可调项:模式写在描述符中,每个选项带默认值,并处在它代码作为硬上限保留的界限内;它的行用 from_settings 和 |settings| settings.options_value("<name>"),配置用 PluginDef::typed,能就地接受变化时用 ctx.on_update。设置中心把它们作为各自分节的行来编辑,无需界面代码。
按测试插件测试它;模型能看到这个变化时重新生成 golden。
写文档:架构中的 crate 行和本页当前的插件表与工具数量。
在仓库根目录用 cargo xtask check、cargo fmt --all --check、cargo test -p hanafubuki-agent-plugin-<name> 和 cargo test -p hanafubuki-agent --lib 验证。

新插件不需要改内核或契约的任何文件。

测试插件

  • 在一个新的 kardia_core::Context 上,把它挂载在一个提供它注入的注册表(以及用 spawn_scoped_worker 时的 PluginFaults)的插件之下(门面或宿主插件用 hanafubuki_agent::test_support::mount,它两者都提供),等待 settled(),断言 state():插件因缺少服务仍是 Pending 时 settled() 也会返回。
  • 断言它的注册,更新它的配置,释放它,断言每个注册都已移除。插件拒绝的配置让它保持 Failed,什么都不注册。
  • 不需要 kardia 的地方直接测试处理函数和领域逻辑。
  • 请求 golden(crates/agent/src/tests/golden.rs,在 Agent 自己的插件上,宿主不添加任何行、上下文或指令)固定模型收到的内容:默认与计划模式下、带 Skill 目录、工作区指令、记忆摘要、压缩之后、带来自脚本化进程内服务器的 MCP 工具、在 explorer 角色的会话中、围绕一次工具调用和一次原生 tool_search 的指令、工具目录和输入条目,以及一次工具往返的展示事件,并固定 workspace-context 重新启动后会话的第一个请求与默认模式的请求逐字节相同;compaction_golden.rs 和 compression_golden.rs 固定各种压缩,以及 hierarchical 策略的请求(它的提示词、工具、标签和提醒,一次折叠之后、一次第二层提炼之后、切换走之后)。模型能看到的变化有意地改变请求 golden:用 HANAFUBUKI_AGENT_UPDATE_GOLDEN=1 cargo test -p hanafubuki-agent --lib golden 重新生成并审查 fixture 的 diff。
  • 历史语料(golden/history/ 与 golden/history-reasoning/)只在有意的历史格式变化之后用 HANAFUBUKI_AGENT_UPDATE_GOLDEN_HISTORY=1 重新录制;否则它们持续证明旧的历史仍能打开。
  • 宿主保留它自己的、覆盖它的行的 golden(Hanafubuki 的在 hanafubuki-agent-integration),这里模型可见的变化也会改变它们。Linux、macOS 和 Windows 共用本仓库的 Agent 请求基线。

命令与更新规则见构建与测试。

回合冻结的会话工作区

TurnAdmissionRequest.workspace 携带准入会话的根目录;已绑定会话的文件和执行工具通过 ToolInvocation.turn 收到同一个不可变的 TurnWorkspace。工具在准备审批和实际执行时都使用 会话服务视图,不得通过修改共享服务的根目录切换会话。执行视图保留同一套进程注册表与 receipt。 宿主级的插件包配置与 guest 进程授权仍是宿主级状态;会话绑定不会重新配置运行中的 guest。

Advisor 插件贡献

advisor 能力行注册按会话规划的工具来源。插件运行、主提供商和模型已配置、用户显式激活三项同时成立后,才提供 ask_advisor。提示贡献检查本步骤实际可用的工具。可选反馈工具记录采纳和验证情况。

重复工具钩子比较同一会话连续调用的工具名称和参数。正常轮询也可能完全相同,所以默认没有触发阈值。显式设置阈值后,独立的 Advisor 请求返回裁决:proceed 放行,revise 拒绝当前调用,blocked 或无法解析时按所选策略处理。Simple 模式关闭工作流提示和自动审查。

本页目录