嵌入 Agent
把 hanafubuki-agent 作为 Rust 库嵌入宿主应用:依赖、组合、宿主端口、panic hook 桥、启动与关闭。
hanafubuki-agent 有两种运行方式,背后是同一套组合:
- 独立运行:
hanafubuki-agent命令行与终端界面。门面 crate 的AgentRuntime::standalone为每个宿主端口提供默认实现(工作目录作为工作区、操作系统钥匙串、配置文件里的代理)。 - 嵌入运行:宿主应用(例如 Hanafubuki)自己组合 Agent,通过宿主接口提供插件、工作区、上下文、指令、网络设置和密钥存储。Agent 不知道宿主的任何领域,也不依赖宿主的任何 crate;依赖方向只有一个:宿主依赖 Agent。
本页说明嵌入方式。编写宿主插件见宿主插件,各部分如何协作见架构。
添加依赖
[dependencies]
hanafubuki-agent = "0.10"
hanafubuki-agent-contracts = "0.10"
hanafubuki-agent-runtime = "0.10"
# 宿主插件的工具还需要:
hanafubuki-agent-approval = "0.10"
hanafubuki-agent-tool-contracts = "0.10"
kardia-core = "0.3.0"| crate | 用途 |
|---|---|
hanafubuki-agent | 门面:组合、槽位(slot)、服务 API、宿主接口、配置(AgentConfig 由它重新导出) |
hanafubuki-agent-contracts | 插件 API:注册表、工具与上下文契约、TurnExtensions(实现 WorkspaceRootsPort 需要它) |
hanafubuki-agent-runtime | ContainedRuntime:每个 Agent 实例的运行时,出现在 AgentConstructor 的签名里 |
hanafubuki-agent-approval | 宿主插件的工具需要的审批类型(ApprovalAction、PermissionRequirement、AuthorizedAction) |
hanafubuki-agent-tool-contracts | 工具名与工具规格类型(ToolName、ToolExposure、ToolExecutionClass) |
插件用 kardia 的 PluginDef 定义,所以需要 kardia-core。宿主不应依赖内核(hanafubuki-agent-kernel)、模型 API 或其他内部 crate;门面重新导出了宿主需要的类型。
版本
1.0 之前,次版本号的升级可以包含破坏性变更(Cargo 对 0.x 的规则),所以依赖写 "0.1"
这样的次版本要求,随每个次版本手动升级。首个版本发布到 crates.io 之前,宿主用 git 依赖固定一个
revision(Hanafubuki 目前就是这样)。
组合
嵌入时宿主自己组装独立模式也在用的几个部件:
| 部件 | 作用 |
|---|---|
AgentSlot | Agent 的状态机与监督者:启动、内核故障后的自动重启、崩溃循环停止、开关、状态 |
AgentStartMarker | 崩溃循环标记(start-marker.json),并持有数据目录锁 |
DesktopAgent | 槽位、标记和 Agent 子进程的环境;start 与 shutdown |
AgentLaunch | 构造每个 Agent 实例的闭包(AgentConstructor)和进程组台账的路径 |
AgentServiceInputs | 构造闭包交给 AgentApplicationService::open 的输入:配置、存储、Skill 根目录、阻塞池、事件 sink、宿主端口 |
AgentApplicationService | 运行中的 Agent 的服务 API:会话、轮次、设置、Provider、MCP、Skill、记忆、插件状态 |
构造闭包在每次启动时都会运行:首次启动、用户重启、内核故障后的自动重启、模块重新开启。所以宿主端口要在闭包里为每个实例重新构建:每个实例只挂载一次它拿到的插件行。
一个完整的最小例子:
use std::collections::{BTreeMap, HashMap};
use std::path::PathBuf;
use std::sync::Arc;
use std::time::{Duration, Instant};
use hanafubuki_agent::{
agent_workspace_roots_from, AgentApplicationService, AgentConfig, AgentConstructor, AgentEvent,
AgentEventKind, AgentEventSink, AgentHostInstructions, AgentHostPorts, AgentInstanceInputs,
AgentLaunch, AgentPluginDescriptor, AgentPluginGroup, AgentPluginRow, AgentProxy,
AgentServiceInputs,
AgentSessionMode, AgentSlot, AgentStartMarker, AgentStatusEventSink, AgentStoragePaths,
AgentTurnRequest, AgentWorkspaceRoots, DesktopAgent, NetworkSettingsPort, NoHostContext,
NoopAgentBackgroundEventSink, NoopAgentPluginEventSink, NoopMcpEventSink, SecretFuture,
SecretKey, SecretStore, SkillRoots, WorkspaceRootsPort, AGENT_SHUTDOWN_BUDGET,
};
use hanafubuki_agent_contracts::TurnExtensions;
use hanafubuki_agent_runtime::ContainedRuntime;
use parking_lot::Mutex;
fn main() -> Result<(), String> {
// 0. 最先、在任何线程启动之前:沙箱辅助进程(见下文)。
hanafubuki_agent::sandbox::helper_dispatch();
let config_dir = PathBuf::from("/var/lib/my-app/config/agent");
let storage = AgentStoragePaths::under(PathBuf::from("/var/lib/my-app/data/agent"));
let project = PathBuf::from("/srv/project");
// 1. 槽位与崩溃循环标记,然后是宿主旁边的 Agent。
let marker = AgentStartMarker::new(storage.start_marker_file.clone())
.with_crash_record(storage.crash_record_file.clone());
let slot = AgentSlot::new(marker.disabled_reason(true), Arc::new(LogStatus));
let agent = DesktopAgent::new(slot, marker, HashMap::new());
// 2. 构造每个 Agent 实例:首次启动和每次重启。
let process_groups_file = storage.process_groups_file.clone();
let construct: AgentConstructor = Arc::new(
move |runtime: &ContainedRuntime, instance: AgentInstanceInputs| {
let blocking = runtime.blocking_port();
AgentApplicationService::open(AgentServiceInputs {
config: AgentConfig::new(&config_dir),
storage_paths: storage.clone(),
skill_roots: SkillRoots {
system: storage.skills_root.join("system"),
user: storage.skills_root.join("packages"),
install_bundled_system_skills: true,
state_file: storage.skill_state_file.clone(),
},
blocking,
mcp_event_sink: Arc::new(NoopMcpEventSink),
plugin_event_sink: Arc::new(NoopAgentPluginEventSink),
background_event_sink: Arc::new(NoopAgentBackgroundEventSink),
host: AgentHostPorts {
plugins: vec![(
AgentPluginRow::unconfigured(
AgentPluginGroup::Capability,
app_info_plugin(),
),
AgentPluginDescriptor::new("app-info", "What My App is"),
)],
workspace: Arc::new(ProjectRoots(project.clone())),
steering_context: Arc::new(NoHostContext),
instructions: AgentHostInstructions {
identity: "You are My App's coding agent.".to_string(),
application: "My App".to_string(),
..AgentHostInstructions::default()
},
network: Arc::new(SystemProxy),
secrets: Arc::new(MemorySecrets::default()),
},
instance,
})
},
);
// 3. 启动,等待 Agent 运行。
agent.start(AgentLaunch {
construct,
process_groups_file,
});
let handle = agent
.slot()
.wait_until_started(Instant::now() + Duration::from_secs(120))
.map_err(|unavailable| unavailable.to_string())?;
// 4. 对 Agent 的每次调用都在它自己的运行时上执行。
let turn = handle
.runtime()
.block_on({
let handle = handle.clone();
async move {
let session = handle.create_session(AgentSessionMode::Default, None).await?;
let request = AgentTurnRequest {
text: "Summarize the README.".to_string(),
images: Vec::new(),
skills: Vec::new(),
host: TurnExtensions::default(),
};
handle
.submit_turn_with_sink(session.id, request, Arc::new(PrintEvents))
.await
}
})
.map_err(|failure| failure.to_string())??;
println!("turn {:?} accepted", turn.turn_id);
// 5. 在预算内关闭,调用方不在任何异步上下文中。
for diagnostic in agent.shutdown(AGENT_SHUTDOWN_BUDGET) {
eprintln!("{} did not stop: {}", diagnostic.worker, diagnostic.message);
}
Ok(())
}例子里的 ProjectRoots、SystemProxy、MemorySecrets(见宿主接口)与 LogStatus、PrintEvents(见事件与历史)是宿主自己的小类型,和上面的代码在同一个文件里,用的是上面的 use;app_info_plugin 是宿主插件一页的示例插件。
要点:
AgentSlot::new的第一个参数是Option<AgentDisabledReason>:None表示 Agent 会启动。AgentStartMarker::disabled_reason(module_enabled)在宿主关闭了 Agent,或者前几次启动都没有完成(崩溃循环,CRASH_LOOP_STARTS为 3)时给出停用原因。DesktopAgent::new的第三个参数是 Agent 子进程继承的环境(代替本进程的环境,HashMap<String, Option<String>>,None表示移除)。宿主的代理改变时用DesktopAgent::replace_child_environment替换最后应用的覆盖层。这两个操作直接保存条目,不校验变量名和值:new直接返回DesktopAgent,替换方法返回();进程启动失败由原生启动器报告。start立即返回:启动在 Agent 实例自己的运行时上进行(构造与恢复在它的阻塞池上,插件作为它的任务,MCP 服务器在后台连接)。失败时槽位变为Failed,不会影响宿主。wait_until_started返回运行中的AgentHandle,或者 Agent 为什么没有运行(AgentUnavailable,它的Display就是“the Agent is unavailable: …”)。AgentHandle解引用为AgentApplicationService。异步方法必须在handle.runtime()上运行(ContainedRuntime::block_on,或者在它的 handle 上spawn):kardia 与 Agent 的任务只能在那里运行,panic 也只在那里被隔离。
独立模式的同一组合
没有宿主时,AgentRuntime::standalone 组合同样的槽位、标记、DesktopAgent 和 AgentLaunch,并为每个端口提供默认值。命令行就是这样用的:
use std::time::Duration;
use hanafubuki_agent::{
logging, panic, AgentDirs, AgentRuntime, AgentRuntimeHost, AgentRuntimeOptions,
AgentStartOptions, ConfigOverrides, AGENT_SHUTDOWN_BUDGET,
};
fn main() -> Result<(), String> {
// 最先、在任何线程启动之前(见“沙箱辅助进程”)。
hanafubuki_agent::sandbox::helper_dispatch();
let runtime = AgentRuntime::standalone(
AgentRuntimeOptions {
dirs: AgentDirs::standalone()?,
bundled_skills: None,
cwd: std::env::current_dir().map_err(|error| error.to_string())?,
add_dirs: Vec::new(),
profile: None,
overrides: ConfigOverrides::default(),
start: AgentStartOptions::default(),
},
AgentRuntimeHost::default(),
)?;
panic::configure_crash_record(runtime.storage_paths().crash_record_file.clone());
panic::install_panic_hook(logging::logging_blocked);
runtime.start();
let agent = runtime
.wait_until_started(Duration::from_secs(120))
.map_err(|unavailable| unavailable.to_string())?;
// … 像嵌入时一样在 agent.runtime() 上调用 agent 的方法 …
drop(agent);
runtime.shutdown(AGENT_SHUTDOWN_BUDGET);
Ok(())
}AgentRuntimeOptions 是目录(AgentDirs,遵循 HANAFUBUKI_AGENT_HOME)、可选的 System Skills 目录、工作目录和 --add-dir、配置 profile、-c 覆盖和首次启动的选项。AgentRuntime::standalone 会立即读取一次分层配置,所以错误的 profile 在这里就失败。独立模式的首次启动总会运行:命令行启动 Agent 就是在请求它,之前未完成的启动不会让它保持关闭(崩溃标记仍然计数)。
AgentRuntime::set_working_directory(path) 在 Agent 运行时把 path(相对于当前工作目录,或绝对路径)设为工作目录,并返回新的根目录:它、它的 Git 根目录,然后是 --add-dir。运行中的 Agent 的文件工具和命令立即移到这些根目录,会话保持活着,每个会话在下一个轮次的上下文中看到新的根目录。有轮次、压缩或后台终端在运行时它被拒绝,什么都不改变,错误说明是哪一个。配置的项目层仍是启动时读取的那一个。它只用于独立模式:嵌入的宿主通过自己的 WorkspaceRootsPort 提供工作区。
AgentRuntimeHost 是独立模式的使用者可以替换的部分:
| 字段 | 默认值 | 说明 |
|---|---|---|
secrets | None:操作系统钥匙串(keyring 4) | 服务名 org.licyk.hanafubuki-agent.secrets |
status | NoopAgentStatusEventSink | 槽位状态改变时调用 status_changed(),不携带负载 |
plugin_events | NoopAgentPluginEventSink | 插件状态的提示,以及每次已安装插件的变化 |
mcp_events | NoopMcpEventSink | MCP 状态与工具目录变化 |
background | NoopAgentBackgroundEventSink | 为后台工作唤醒某个会话时的 Woken(见下) |
轮次与会话事件不经过这里,而是发给每次调用传入的 AgentEventSink(见事件与历史)。
宿主接口
宿主只能通过 AgentHostPorts 向 Agent 添加东西。接口只接受普通值(PathBuf、字符串、映射)或 Agent 自己的类型:Agent 带有自己的 foundation、process 和模块宿主的副本,与宿主的同名类型是不同的类型,宿主在边界处做转换。
| 字段 | 类型 | 作用 | 独立模式默认 |
|---|---|---|---|
plugins | Vec<(AgentPluginRow, AgentPluginDescriptor)> | 宿主插件行,各带其描述符 | 无 |
workspace | Arc<dyn WorkspaceRootsPort> | 工作区根目录、受保护的目录、指令查找的选中目录、文件搜索根目录 | 工作目录、它的 Git 根目录、--add-dir |
steering_context | Arc<dyn HostContextPort> | steering 消息携带的宿主上下文 | NoHostContext |
instructions | AgentHostInstructions | 身份、应用名,以及宿主加入基础指令的段落 | AgentHostInstructions::default() |
network | Arc<dyn NetworkSettingsPort> | Web 工具、MCP、OAuth、模型 Provider 与 models.dev 使用的代理 | 配置文件的 [network] proxy |
secrets | Arc<dyn SecretStore> | MCP OAuth 令牌的存放处 | 操作系统钥匙串 |
插件行
AgentPluginRow::unconfigured(group, plugin),group 为 AgentPluginGroup::Capability(工具、工具源及其规则)或 AgentPluginGroup::Context(世界状态段)。宿主行挂载在 Agent 自己的能力插件之后、上下文插件之前,所以宿主的世界状态段排在工作区根目录、环境和权限模式之前。宿主插件与 Agent 自己的插件遵守同一套规则:disabledPlugins 可以关闭它们,安全模式不挂载它们。写法见宿主插件。
每一行都带着它的 AgentPluginDescriptor:AgentPluginDescriptor::new(name, summary),name 是它的 PluginDef 的名字,summary 是一行说明它给模型或用户提供什么,plugin_status 和 /plugins 显示它。没有描述符的行,或 Agent 或另一行已经描述过的名字,会让 Agent 无法构建。有选项的行加上 .with_options(schema)(一个 PluginOptionSchema,每个选项带默认值),用 AgentPluginRow::from_settings(group, plugin, |settings| settings.options_value("名字")),并用 PluginDef::typed 解码它的配置;这些选项就是 Agent 配置中的 [pluginOptions.名字],按模式检查:它们是设置目录中的一节(pluginOptions.名字,在 Plugins 组中),用 write_setting_values 按键写入(pluginOptions.名字.键),或用 set_plugin_options 以补丁写入(插件选项)。宿主这样声明设置,不需要自己的设置页面:基于设置目录的页面会显示并写入它。
WorkspaceRootsPort
/// 一个项目目录就是整个工作区。
struct ProjectRoots(PathBuf);
impl WorkspaceRootsPort for ProjectRoots {
fn roots(&self) -> Result<AgentWorkspaceRoots, String> {
agent_workspace_roots_from([self.0.clone()]).ok_or_else(|| "no workspace".to_string())
}
fn protected_roots(&self) -> Vec<PathBuf> {
Vec::new()
}
fn selected(&self, _host: &TurnExtensions) -> Option<PathBuf> {
None
}
fn search_roots(&self, _host: &TurnExtensions) -> Result<Vec<(String, PathBuf)>, String> {
Ok(vec![("project".to_string(), self.0.clone())])
}
}roots()在每个轮次和每次 Skill 目录读取时重新读取;第一个根目录是相对路径请求的基准。文件工具的策略和没有workdir的命令运行的目录在构建 Agent 实例时从它取得,所以新的根目录随下一个实例(重启)到达工具。agent_workspace_roots_from去重(按路径身份),并去掉嵌套在前面某个根目录里的根目录。protected_roots():文件工具拒绝访问的目录,包括读取,即使它们位于工作区根目录之下;其下的请求在任何审批之前以ProtectedPath失败(Hanafubuki:应用的数据与日志目录,其凭据就在那里)。独立运行的 Agent 不指定任何目录。selected(host):轮次的宿主输入所选中的目录,AGENTS.md从根目录一直查找到这里(Hanafubuki:用户正在看的实例)。search_roots(host):@文件搜索要遍历的目录及其标签。- 每个方法都可能阻塞,Agent 在自己的阻塞池上调用它们。
HostContextPort
steering 消息(追加到正在运行的轮次的消息)携带的宿主上下文:steering_context(host) 返回 Option<AgentHostContext>(一个 ContextSectionKind 和内容,最多 MAXIMUM_HOST_CONTEXT_BYTES,4 KiB)。内核在它变化时把它作为该类型的段写入世界状态;这个类型的渲染器由宿主的插件注册。不需要时用 NoHostContext。
AgentHostInstructions
| 字段 | 作用 | 默认(独立模式) |
|---|---|---|
identity | 基础指令开头的句子(prompts/base.md 中的 {identity}) | You are a coding and operations agent. |
application | 环境段报告的应用名 | hanafubuki-agent |
sections | 放在工具说明之后的 Markdown 段落:宿主的工具与上下文怎么用 | 空 |
ownership | “Approval and ownership”一节结尾的段落:宿主拥有什么 | 空 |
各块之间用一个空行连接。这些文本是模型可见的,宿主应当用自己的 golden 测试固定它们(Hanafubuki 的在 hanafubuki-agent-integration)。
NetworkSettingsPort 与 SecretStore
struct SystemProxy;
impl NetworkSettingsPort for SystemProxy {
fn proxy(&self) -> Result<AgentProxy, String> {
Ok(AgentProxy::System)
}
}
/// 把 MCP OAuth 令牌放在内存里;真实的宿主使用平台的安全存储。
#[derive(Default)]
struct MemorySecrets(Mutex<BTreeMap<SecretKey, Vec<u8>>>);
impl SecretStore for MemorySecrets {
fn get<'a>(&'a self, key: &'a SecretKey) -> SecretFuture<'a, Option<Vec<u8>>> {
Box::pin(async move { Ok(self.0.lock().get(key).cloned()) })
}
fn set<'a>(&'a self, key: &'a SecretKey, value: Vec<u8>) -> SecretFuture<'a, ()> {
Box::pin(async move {
self.0.lock().insert(key.clone(), value);
Ok(())
})
}
fn delete<'a>(&'a self, key: &'a SecretKey) -> SecretFuture<'a, ()> {
Box::pin(async move {
self.0.lock().remove(key);
Ok(())
})
}
}NetworkSettingsPort::proxy()在 Agent 启动时读取,宿主调用AgentSlot::apply_saved_settings时再次读取;它必须从内存回答,不能阻塞。模型 Provider 在各会话的下一轮使用修改后的代理;代理变化时,MCP 的 stdio 服务器会重新启动,并在宿主进程此时得到的环境(它的覆盖层)中运行,Streamable HTTP 服务器会重新连接。AgentProxy是System、Disabled或Explicit(url)。SecretStore的调用可能阻塞(钥匙串),宿主应把它们放到 Agent 的阻塞池上(ContainedRuntime::blocking_port,配合run_blocking_operation),Hanafubuki 的KeyringSecretStore就是这样做的。- 锁使用
parking_lot:Agent 的 panic 会在被隔离的线程上展开,std 的锁会因此中毒。
宿主输入
AgentTurnRequest、AgentSteeringRequest 和 AgentFileSearch 都有一个 host: TurnExtensions 字段:宿主随消息或搜索提交的数据,按类型存放。Agent 原样传递、从不读取:它交给上下文贡献者(ContextRequest::turn)、HostContextPort 和 WorkspaceRootsPort。宿主的插件和端口读取它们自己放入的类型。
沙箱辅助进程
在 Linux 和 Windows 上,沙箱中的命令(沙箱)以嵌入 Agent 的那个程序运行:程序被再次启动,第一个参数是 --hanafubuki-agent-sandbox。在 Linux 上,这次运行先限制自身,再变成那个命令;在 Windows 上,它用受限令牌在一个随它结束的作业中启动命令,并以命令的退出状态退出。所以程序的 main 要最先、在启动任何线程之前调用 hanafubuki_agent::sandbox::helper_dispatch():
fn main() {
hanafubuki_agent::sandbox::helper_dispatch();
// ……程序其余部分不变……
}- 作为辅助进程启动时,这个调用不会返回。否则它记下这个程序(
std::env::current_exe())可以充当辅助进程,并立即返回。 - 不调用它,Agent 就没有沙箱:
AgentApplicationService::sandbox_status()(以及sandbox::Sandbox::detect().status())为Unavailable,沙箱模式不是完全访问的每个命令都会失败,不会运行。Linux 上sandboxMode的默认值是 workspace-write,所以不调用它的宿主必须配置sandboxMode = "full-access"才能运行命令。 ExecutorManager像启动其他命令一样启动辅助进程;不涉及宿主自己的进程代码。- 在 macOS 上不需要辅助进程:沙箱中的命令在
/usr/bin/sandbox-exec下运行,所以这个调用在那里只是返回。 - Windows 的
windows.sandbox选择unelevated或elevated。宿主可调用sandbox::setup_windows_sandbox()执行 UAC 初始化,只在成功后保存所选配置。helper_dispatch()同时分派初始化及账户运行器进程。Sandbox::with_windows_sandbox应用后端并检查就绪状态。
panic hook 桥
Agent 的故障隔离依赖展开(unwinding):插件或内核代码里的 panic 在被标记为“已隔离”的线程上展开到它的捕获点,变成一次工具错误、一个插件故障或一次内核重启。所以:
- 宿主不能用
panic = "abort"构建。 - 宿主如果安装了自己的 panic hook,并且 hook 对它认为没有被隔离的 panic 中止进程,就必须同时询问 Agent:Agent 在它自己的 foundation 里标记线程与守卫,宿主的 hook 看不到。
// 宿主 hook 判断 panic 是否被隔离时:
let contained = host_says_contained() || hanafubuki_agent::panic::is_panic_contained();WebAssembly 插件访客在宿主的进程内、在 wasmtime 中运行。加载第一个 WebAssembly 访客时,wasmtime 会为访客陷阱引发的信号安装自己的处理器(Unix 上是 SIGSEGV、SIGBUS、SIGILL 和 SIGFPE),并把不属于访客的信号交给在它之前安装的处理器。为这些信号安装自己处理器的宿主,应在此之前安装,或在替换时链接到被替换的处理器。
在 macOS 上,Agent 让 wasmtime 用这些信号处理陷阱,而不是通过 Mach 异常端口:在生成第一个 WebAssembly 引擎之前,访客宿主调用 kardia-hmr 的 set_macos_mach_ports(false)。信号是 Agent 的检查在 Linux 上走的路径,宿主也已经链接了它们(见上);Mach 端口会再加一套进程级机制,并且是 macOS CI 上第一个 WebAssembly 检查间歇性挂起(在一个已经启动过访客进程的进程中)的嫌疑原因。这个设置是进程级的,由第一个引擎固定:自己生成 wasmtime 引擎的宿主,也要用 Config::macos_use_mach_ports(false) 生成它们(之后的引擎请求另一种设置时 wasmtime 会 panic);如果宿主使用 Mach 端口的引擎先出现,Agent 的访客就沿用 Mach 端口,访客宿主记录一条警告。
kardia-hmr 自己的线程(进程访客的 guest-stdin、guest-stdout 和 guest-stderr,WebAssembly 的 wasm-epoch 线程)会捕获自己的 panic,并杀死它所服务的访客。访客宿主把 kardia-hmr 的检查注册到 Agent 的 foundation(register_containment_check),所以上面的 hanafubuki_agent::panic::is_panic_contained 在这些线程上也为真:宿主的 hook 不需要第三个检查。
没有这个桥,每个 Agent panic 都会中止宿主应用。Hanafubuki 在 platform::panic_hook 里安装了带第二个检查的 hook,并在子进程里测试两种结果(有桥时展开,没有时中止);这个测试是宿主的责任。
宿主的 hook 在致命 panic 中止进程前应写下崩溃记录,路径为 AgentStoragePaths::crash_record_file(<data>/crash-record.json):Agent 的崩溃循环标记会读它,判断上一次未完成的启动是不是因为宿主自己的致命 panic。没有自己 hook 的宿主可以直接安装 Agent foundation 的 hook,就像独立的二进制那样:panic::configure_crash_record(...),然后 panic::install_panic_hook(logging::logging_blocked)。
在 Agent 没有启动的线程上(例如终端界面的主线程)调用自己代码的前端,可以用 panic::catch_panic 或 panic::catch_panic_async 隔离一段代码:它们在 Agent 的 foundation 中把这段代码标记为受隔离,并把 panic 的消息作为错误返回。终端界面的每个命令模块都在它们之下运行。
数据目录锁
<data_dir>/.lock 是共享建议锁,从 Agent 的首次启动一直持有到关闭,嵌入与独立模式相同。多个 Agent 可以共用数据目录,同时运行不同会话。
- 宿主不需要为锁做任何事:启动标记持有它。仍持有目录独占锁的旧版 Agent 必须先退出,新实例才能启动。
- 每个已加载或修改的会话由
history/writers/<id>.lock保护,只允许一个实例写入。其他实例可以浏览历史,但在拥有者关闭前不能打开或修改该会话;新建会话可以立即运行。 - 启动恢复跳过其他活动实例拥有的会话和进程组。共享文件的修改使用各自的锁,SQLite 保留事务边界。
- 全局历史修复和暂存区清理仅在没有其他存储实例活动时执行。显式重建历史索引需要先停止其他 Agent。每个实例仍保留 Agent 原有的恢复和隔离机制。
启动、开关与关闭
槽位的状态(AgentStatus::availability)是 Disabled(setting 或 crashLoop)、Starting、Running、Faulted、Stopping、Failed { stage, reason }(construct、recover、start)或 Stopped。AgentStatusEventSink::status_changed() 不携带负载:收到后重新读取 AgentSlot::status()。状态还包含 generation(本次运行的第几个实例)、safe_mode、degraded(有插件失败、拆除卡住或带有警告)和被隔离的会话。
| 调用 | 作用 |
|---|---|
DesktopAgent::start(launch) | 交出启动组合并启动第一个实例;立即返回 |
AgentSlot::wait_until_started(deadline) | 等待启动结束,返回 AgentHandle 或原因 |
AgentSlot::agent() | 运行中的 Agent 或原因;持有者应在每次调用时重新解析,而不是缓存 handle |
AgentSlot::restart(options) | 用户的重启,可选安全模式(AgentStartOptions { safe_mode, rebuild_history_index }),并清空崩溃循环标记 |
AgentSlot::enable() / disable() | 打开 / 关闭 Agent;turn_off(deadline) 关闭并等待到期限 |
AgentSlot::apply_saved_settings() | 宿主的设置(例如代理)保存后调用:在 Agent 的运行时上重新配置插件,立即返回 |
AgentSlot::list_run_projections() | Agent 的运行(AgentRunProjection),供宿主的活动视图使用 |
DesktopAgent::shutdown(budget) | 在预算内关闭;阻塞调用方,调用方不能在异步上下文中 |
内核代码的 panic(轮次任务、Agent 的工作线程组、宿主任务)会让槽位把 Agent 标为 Faulted、停止它,并在 2 秒、10 秒、30 秒后启动新实例(10 分钟窗口内最多三次,AgentRestartPolicy),从磁盘重建会话。重启后旧实例上进行中的调用会失败;正在运行的 AgentHandle 的 generation() 与 status().generation 不同就说明 Agent 已经换了实例。
AGENT_SHUTDOWN_BUDGET 为 20 秒,关闭按固定阶段进行,每个阶段有自己的期限:
停止接受新轮次,取消轮次与压缩(包括后台压缩)并等待它们(5 秒):已完成的后台压缩先记录它的用量。
Agent 启动的进程归 Agent 所有:它有自己的 ExecutorManager,与宿主的进程分属两个所有权域。宿主不需要(也不能)替 Agent 终止它们。
宿主中的配置
嵌入模式的执行插件同样从 [pluginOptions.execution] 读取环境选择与 Shell 启动选项。直接调用 AgentExecutionService 时设置 ExecCommandRequest.shell_environment,其可选的 ExecutionEnvironmentContext 提供会话、轮次、工具调用及权限模式信息。ExecCommandRequest.login 的类型为 Option<bool>:Some(true) / Some(false) 启用 / 禁用 POSIX 登录启动或 PowerShell Profile;None 使用 POSIX 登录启动,或 PowerShell 的 shell_environment.use_profile 默认设置。MCP stdio 通过 McpStdioConfig.environment_variables 指定额外继承的名称。宿主最终的 ChildProcessEnvironment 覆盖仍然优先,见环境变量。
宿主为 Agent 指定一个配置目录,用 AgentConfig::new(dir) 打开(Hanafubuki 用 <app_data>/config/agent/)。目录里有三个 TOML 文件,各自是一个修订域、各有一把锁:
| 文件 | 内容 |
|---|---|
config.toml | 权限模式、沙箱、记忆、disabledPlugins、Web 搜索与抓取、[compaction]、[modelMetadata] |
providers.toml | Provider 注册表及其修订号,令牌原样保存(仅所有者可读) |
mcp.toml | MCP 服务器与凭据值及其修订号(仅所有者可读) |
与独立模式不同,嵌入的配置没有分层(没有 profile、项目文件和 -c),并忽略 [network] 与 logLevel(报告为未知键):代理和日志由宿主提供。宿主通过服务 API 读写设置(settings_view、write_settings、Provider 与 MCP 的方法),写入后服务会把设置应用到插件。设置页从设置目录读取每项设置的描述,不再自己维护一份。其中:
| 调用 | 作用 |
|---|---|
settings_catalog() | 现读的 SettingsCatalog { sections, collections }。各节(SettingsSection:id、标题、SettingsGroup、顺序、它的 SettingSpec,每个值是一个 SettingState,带 SettingSource 和问题)包括配置的各节(宿主的配置没有 network 和 tui 节)、每个有选项的插件行一节(包括宿主的行,pluginOptions.<row>),以及每个 configSchema 能降低为选项的已安装代码插件一节(plugins."<id>".settings)。集合(SettingsCollection)有 providers、providerModels、modelPolicy、mcp、mcpSecrets、pluginMcp、plugins、packages、packageDefaults、marketplaces、skills、sandboxMaintenance、hooks、roles 和 roleFiles(独立运行时还有 profiles、configLayers 和 projects),每个集合以 spec 描述一条记录的字段(其默认值是 add 写入的值),列出它的 SettingsRecord(readOnly 说明为什么某条记录只显示、不在这里写入)、SettingsAction(由用户命名记录的 add 带 namesRecord)、文件的修订号和无法读取的内容(issues)。集合记录省略机密字段的值,只列出哪些已设置(secretsSet);插件设置节可以返回机密值,其 spec 将字段标记为机密。Web 工具的表单就是 web 节 |
write_setting_values(write) | 按键写入一个 SettingsWrite(严格)中的设置和插件选项(pluginOptions.<row>.<key>),每项设置或重置,按它的 spec 检查,要么整体写入要么不写;然后把设置应用到插件。代码插件的设置(plugins."<id>".settings.<option>,由 package_setting_key 拼写)单独写入,一次一个插件,经由 set_package_settings。返回 SettingsWriteOutcome { written, shadowed, apply } |
run_settings_action(request) | 通过集合所有者的调用执行一个 SettingsActionRequest { collection, record, action, expectedRevision, values }(严格):add、save(值合并到已保存的记录上,省略的机密保持不变)、delete,以及所有者自己的动作(set_default、list_models、connect、trust 等);受修订号约束的集合,写入时带上读取时的修订号。返回 SettingsActionOutcome { record, message } |
list_provider_models(request) | 所列每个 Provider 的模型列表(AgentProviderModelCatalogRequest { providerIds },为 None 时是所有已启用的),每次都实时读取,同时进行,按显示名称排序:每个一份 AgentProviderModelCatalogResult { providerId, displayName, models, error },未能列出的 Provider 附上它的 error。每个模型是一个 AgentListedModel { entry, metadata }:列表的 ModelCatalogEntry 及该模型已知的信息,与 model_metadata 给出的相同,只是以这次列表作为报告的内容,解析时只读一次 providers.toml(模型元数据);它的 JSON 是条目的各字段,照旧平铺,旁边加上 metadata。所有请求的 Provider 都答复后调用才返回:要在每个 Provider 的模型到达时就显示它们的宿主,每个 Provider 发一个请求 |
test_provider_draft(draft) | 读取一个未保存 Provider 的模型目录,方式与 list_provider_models 读取已保存的相同,或返回 Provider 的错误;不写入任何设置(列表像其他列表一样记录到模型元数据中) |
model_metadata(provider_id, model) | 该 Provider 上的 model 已知的信息(ModelMetadata:窗口、最大输出、推理及其档位、图片输入),每项附上来源(Sourced、ModelMetadataSource):providers.toml 中模型自己的设置(不含策略的窗口)、它的拒绝教的、目录报告的、打开时 models.dev 给出的(Catalog)、内置窗口(按模型的设置)。ModelMetadata::known_reasoning()(KnownReasoning:档位及其默认值、不接受、或未知)按 /effort 的方式读取推理信息,档位只来自配置或目录;reasoning_effort_choices 把这些档位给成 SettingChoice,标出默认档位:即模型策略 reasoningEffort 的值,它是 SettingKind::ChoiceOrText(取其中一个值、手动输入的文本,或 null)。说这些事实的词是 ModelMetadataSource::label()(configured、learned、reported、models.dev、built-in)以及 ModelMetadata::supports_reasoning() 和 supports_image_input()(Option<bool>:是、否或未知),终端界面和 doctor 都用它们 |
session_model_metadata(session_id) | 会话的模型的同样信息,窗口取会话现有的窗口及其来源,与 /status 显示的一致 |
forget_learned_model_facts(provider_id, model) | 遗忘该 Provider 的拒绝教给 model(None:它的每个模型)的信息,存于 model-metadata.json;返回有多少个模型有可遗忘的信息。会话在下一个轮次采用(遗忘学到的信息) |
mcp_set_credential(key, value)、mcp_remove_credential(key) | 修改一个 MCP 凭据并保留其他凭据;删除启用的服务器依赖的凭据会被拒绝。McpCredentialKey::for_server_secret(server, name) 是表单保存秘密变量或请求头所用的键:服务器-名称,其他字符换成 _ |
mcp_oauth_login(server, open_url, cancelled) | MCP 服务器的 OAuth 登录:在 127.0.0.1 的空闲端口上监听,把授权 URL 交给 open_url 显示或打开,最多等待 5 分钟浏览器重定向到 /callback,或直到 cancelled future 完成;没有等到时取消这次登录 |
会话在每次模型操作(轮次、压缩、实现计划)之前按当前设置激活:[compaction] 的 strategy 通过内核的 set_session_compaction_strategy 应用到会话,模型策略的 remoteCompaction 随 Provider 的传输一起写入会话配置,为会话的模型配置的内容也一样(AgentSessionConfig.configured_facts,一个 AgentConfiguredModelFacts:providers.toml 中模型自己的设置,其窗口否则取策略的窗口),由 activate_model_session 接收、下一个轮次应用。两者都只在会话空闲时改变、都会持久化,但都不推进会话的 revision,所以调用方在调用前读到的 revision 仍然有效。轮次的扩展带有 [compaction.background] 的 thresholdPercent(AgentBackgroundCompactionThreshold),在轮次准入时读取;直接通过内核准入轮次的宿主需要自己放入它,否则这个轮次不会启动后台压缩。后台压缩运行期间或其结果等待安装时,会话的运行时快照会表明(backgroundCompaction:running 或 ready);它不是会话的操作,不拒绝任何东西。归档或删除会话会取消它并最多等待 5 秒,改变策略或 remoteCompaction 会取消它。
读取是容错的:无效值取默认值,未知键记录日志并保留在文件里,需要修复的文件先复制到 .recovery/ 再写入修复后的值;无法保留原件时,修复后的值只用在内存里,文件在重启前拒绝写入。每次修复都是一条 AgentConfigRecovery(文件、问题、是否只读、时间),AgentConfig::recoveries() 返回本次打开以来的修复(每个文件最近 20 条),宿主应当把它们展示给用户。键名、默认值和修复规则见配置与配置参考。
配置目录中还可以有角色:它的 agents/ 和其 config.toml 中的 [agents] 条目,这是嵌入的 Agent 唯一的配置角色来源,此外还有内置角色和开启期间的已安装插件的角色。roles() 返回服务最近一次读取的 AgentRoleCatalog(构建时读取,之后每次 reload_packages 再读):可用的角色(AgentResolvedRole,含继承链、合并后的字段、AgentCapabilityScope 和每个字段的来源)、不可用的角色及原因,以及问题;宿主应把这些问题与配置的问题放在一起展示。AgentRoleCatalog::load(&config, plugins_root, safe_mode) 不需要服务即可读取角色:配置中的角色,以及 plugins_root(AgentStoragePaths::plugins_root)下设置开启的已安装插件的角色(安全模式下没有),读取时不打开包存储,所以可以在 Agent 运行时使用;读取插件角色时略去的内容列在它的问题中,并写明该插件。会话在创建或切换时取得角色(会话与角色)。
Agent 会自己列出各 Provider 的模型(模型发现):构建服务时列出默认 Provider 的模型;每当在某个 Provider 上创建会话、选用它的模型或为一个轮次激活会话时,列出该 Provider 的模型,每个 Provider 每天最多一次(失败后每 15 分钟最多一次),使用该 Provider 自己的端点、令牌和请求头。所以宿主的 Agent 会在启动时和这些时候自己发出 GET {baseUrl}/models;它从不延迟任何调用,失败只记录日志,从不作为结果返回。它得知的信息是会话在下一个轮次采用的上下文窗口,会话的配置也记住窗口的来源(AgentSessionConfig.context_window_source,未知时为 None,此时不写入记录;自己构建配置的宿主传 None,由内核设置)。宿主在 Agent 的 config.toml 中设置 modelMetadata.discovery = "off" 即可关闭模型发现,可以手写,可以调用 AgentConfig::set_user_value("modelMetadata.discovery", "off"),也可以用设置补丁的 modelMetadata(AgentSettingsPatch::model_metadata)。宿主自己请求的 Provider 模型列表(list_provider_models、test_provider_draft)无论如何都会读取并记录。
除非宿主的配置打开了 models.dev(modelMetadata.modelsDev = true,即补丁的 AgentModelMetadataSettings.models_dev,补丁的 modelMetadata 现在在 discovery 之外也带着它),宿主的 Agent 从不访问它:打开后,同一个 worker 从宿主的机器下载 https://models.dev/api.json,这是对第三方的请求,每天最多一次。内核的 AgentService::model_metadata 和 model_context_window 接受 Provider 的 id,用它的名称优先选出该 Provider 自己的条目;record_models_dev_catalog、forget_models_dev_catalog 和 models_dev_fetched_at 管理副本。
从旧格式迁移设置是宿主自己的事:Hanafubuki 在 config.toml 不存在时(AgentConfig::exists),由它的构造闭包运行 import_legacy_agent_settings,用 AgentConfig::create 一次写入整份配置(config.toml 最后写,所以中途停止的导入会重来),旧文件保持不变。
Skill 管理
门面直接提供目录与创作操作,宿主的 Skill 编辑器不需要调用模型工具。使用目录返回的 SkillId 和 user_root,不要从展示的目录推算安装目标。发现与回合内采用规则见 Skill。
| 调用 | 用途 |
|---|---|
list_skills()、list_skills_for_session(session_id) | 读取当前目录,包括问题与 MCP 依赖可用性;后者使用该会话的工作区根目录 |
list_skills_with_force_reload(true) | 重新加载目录,不复用缓存 |
skill_session_state(session_id) | 返回 generation、revision、已启用且就绪的 Skill ID(available),以及当前回合已采用的 ID(current_turn_active) |
read_skill(id) | 读取条目和完整 SKILL.md |
read_skill_file(id, path) | 为编辑读取目录已收录的 UTF-8 文件,包括 SKILL.md;Skill 停用时也可读取 |
read_skill_resource(id, path) | 读取已启用 Skill 的非脚本 UTF-8 资源;这不是模型工具的分页或二进制响应 |
enable_skill(id)、disable_skill(id) | 改变启用状态并返回更新后的目录 |
inspect_skill_source(path) | 检查本地目录的元数据、资源和安装冲突,不执行安装 |
install_local_skill(LocalSkillInstallRequest) | 将 source_directory 安装到用户根目录;overwrite 明确允许覆盖同名文件夹 |
create_skill(SkillCreateRequest) | 按 name、description 创建用户 Skill 和初始 SKILL.md |
duplicate_skill(SkillDuplicateRequest) | 将任意来源的 source 复制为指定 name 的新用户 Skill |
write_skill_file(SkillWriteFileRequest) | 用 content 字节创建或替换 id 中的 path,每个文件最多 4 MiB |
delete_skill_file(SkillDeleteFileRequest)、delete_skill(id) | 删除用户 Skill 的文件或整个用户 Skill;文件删除拒绝 SKILL.md |
文件路径相对于所属 Skill,必须留在其目录内。创作与删除以用户 Skill 为目标;系统、仓库和插件 Skill 可以复制到用户根目录,但不原地编辑。启用状态与可编辑性是两回事。
MCP 管理
mcp_snapshot() 返回 McpApplicationSnapshot:设置及修订号、服务器与 OAuth 状态、工具与隐藏工具数、待处理的 elicitation、诊断、修复记录、默认值及插件提供的服务器。其中的设置包含供本地设置界面使用的凭据值。mcp_local_status(verbose) 是终端界面使用的状态投影:凭据只表示是否存在,详细输出还包括解析后的程序、能力、策略、工具和诊断。
mcp_write_server(McpServerWriteRequest) 和 mcp_delete_server(McpServerDeleteRequest) 接受设置的 expected_revision。用户服务器优先于同 ID 的插件服务器,修改会安排包重载。保存设置与连接是两个结果:连接失败记录在服务器状态中,因此应检查返回的快照,不能将写入成功视为连接就绪。
mcp_write_credentials(McpCredentialsWriteRequest) 在 expected_revision 下替换整份凭据映射,省略的键会被删除。只修改一个键时使用 mcp_set_credential 或 mcp_remove_credential。仍被已启用服务器使用的凭据不能删除;凭据变化后,使用它的服务器会重新连接。
mcp_connect(server_id) 按当前设置连接,mcp_refresh(server_id) 通过同一连接流程刷新,mcp_disconnect(server_id) 关闭连接但不把已保存的服务器设为停用。要让它重启后仍保持关闭,应修改启用设置。
宿主自行接收浏览器回调时,可使用底层 OAuth 流程代替 loopback 辅助方法 mcp_oauth_login:
- 调用
mcp_oauth_start(McpOAuthLoginRequest { server_id, redirect_uri }),打开返回的授权 URL。 - 保存返回的 flow ID,将完整回调 URL 交给
mcp_oauth_complete(McpOAuthCallbackRequest { server_id, flow_id, callback_url }),或用mcp_oauth_cancel(McpOAuthCancelRequest { server_id, flow_id })取消。 mcp_oauth_refresh(server_id)刷新已存授权并重新连接,刷新失败时保留原有材料;mcp_oauth_logout(server_id)确认断开连接后才删除授权材料。
服务器有待处理的 elicitation 时,展示快照中的请求,再把请求 ID 和用户决定传给 mcp_resolve_elicitation(request_id, decision)。
记忆管理
memory_status() 返回存储状态与 generation。memory_session_contribution(session_id) 返回 (mode, revision),将该 revision 传给 set_memory_session_contribution(session_id, expected_revision, enabled),即可修改会话是否贡献记忆。这是贡献状态的修订号,不是会话修订号。设置方法返回前,记忆观察者会记录已提交的变化并通知扫描。因外部内容被排除的会话不能重新选择贡献。
reset_memory(expected_generation) 重置派生记忆并返回重置后的 generation;参数使用 memory_status() 读取的 generation。它不删除对话历史,符合条件的会话之后可以再次提取。面向用户的行为见记忆。
事件与历史
struct LogStatus;
impl AgentStatusEventSink for LogStatus {
fn status_changed(&self) {
eprintln!("the Agent's status changed");
}
}
struct PrintEvents;
impl AgentEventSink for PrintEvents {
fn emit(&self, event: AgentEvent) {
if let AgentEventKind::TurnCompleted { .. } = event.kind {
println!("turn completed");
}
}
}- 轮次事件发给每次调用传入的
AgentEventSink:submit_turn_with_sink、submit_user_shell_command_with_sink、submit_wake_turn_with_sink、steer_turn_with_sink、submit_plan_implementation_with_sink、compact_session_with_sink。emit在 Agent 的线程上调用,只能做有界的工作(例如送进通道),不能阻塞。事件类型(AgentEventKind)与exec --json输出的相同,见JSON 事件。ExecutionProgress的update是AgentToolProgressUpdate;要流式显示进程输出的界面用render_plain_text渲染它的终端文本,要连颜色一起显示时用render_styled_text(同样的文字旁边有一个AgentStyledText,以及末尾仍然有效的样式,下一段从它开始),并用complete_prefix_len暂留一行中未结束的转义序列,这些都由门面重新导出(终端界面的流式输出)。伪终端的行在同一段文字中带着它的单元格的颜色,每个带样式的段放在它的 SGR 序列和一个重置之间;把文字渲染为纯文本的界面看不到任何变化。 - 用户的 shell 命令:
submit_user_shell_command_with_sink(session_id, command, sink)把用户输入的命令(终端界面的!命令)作为不询问模型的轮次运行,在会话的沙箱和工作目录中,以用户的输入作为批准(要求由人决定的审批规则仍会询问);cancel_turn停止它和它的进程。它的ToolStarted名为exec_command,调用 ID 为user-shell-<轮次>,历史条目是ConversationItem::UserShellCommand,模型从下一个请求起读到它,并以TurnCompleted { final_answer_message_id: None }结束。这一条目随轮次开始一起提交,内容是命令没有运行完,命令结束时就地补全,没有单独的事件:收到ToolCompleted之后再读取它(tool_display,或重新读取对话记录)。有轮次运行时和 Plan 模式下它被拒绝,它的轮次不读取补充消息(内部细节)。 - 唤醒事件:会话的后台工作(它的子代理和后台终端)报告的内容排在该会话上,并只到达模型一次:作为下一个轮次准入时(在其
TurnStart和世界状态之后、消息之前)或运行中轮次的某一步提交的ConversationItem::WakeEvents { events }。submit_wake_turn_with_sink(session_id, sink)启动投递它们的轮次:一个没有用户消息的Programmatic轮次,其请求以<background_events>片段结尾,并以AgentWakeTurnAccepted { turn, events }返回它(它投递的事件,界面可以把它们显示为轮次的第一项);队列已空、有轮次在运行(由那个轮次投递)或会话不被唤醒(wakeOnBackgroundTasks关闭、旁路对话、审查)时返回Ok(None)。每个AgentWakeEvent有一个source(AgentWakeSource::Subagent或Terminal,带AgentSubagentWake或AgentTerminalWake);summary()是给人看的一行,wake_events_record是模型读到的文本。子代理的结束和它发给父会话的消息排在父会话上;快照携带pending_wake_events和会话的wake_policy,每次激活时按wakeOnBackgroundTasks赋予(唤醒事件)。宿主显示对话记录时渲染这一条目,或跳过它。 - 唤醒会话:没有父会话的会话有排队的事件且没有轮次在运行时,Agent 告知启动时安装的
AgentBackgroundEventSink(AgentServiceInputs::background_event_sink;独立运行时为AgentRuntimeHost::background)AgentBackgroundEvent::Woken { session_id }。event在 Agent 的线程上调用,只做有界的工作。由宿主决定:用submit_wake_turn_with_sink和它选择的 sink 提交被唤醒的轮次(终端界面对它显示的会话这样做),或者忽略,事件留给会话的下一个轮次。同一批事件的Woken可能来两次,或在宿主还没看到上一个轮次结束时到来:找不到事件或遇到正在运行的轮次的提交返回Ok(None)。用户暂停了会话的唤醒时不发送(对其轮次的cancel_turn暂停唤醒,直到下一次submit_turn_with_sink;没有用户消息时连续 100 个被唤醒的轮次也会暂停);宿主自己的提交此时仍会运行。background_status(session_id)返回AgentBackgroundStatus { work, pending_wake_events, wake }:仍在工作的子代理(AgentBackgroundWork { agents, terminals })、尚未读到的事件,以及AgentWakeState::On、Paused { reason }(AgentWakePause::PersonInterrupted或RunawayBound)或Off;exec依据它等待,终端界面的等待行读取它。其中的子代理是本实例为该会话运行的子代理(一个子代理一直计数到它的结束排入队列为止,且先于队列读取,所以已结束的子代理要么被计数、要么已排队,不会两者皆非)。选项打开时(默认),会话的模型被告知子代理报告时它会被恢复,所以从不在Woken时提交的宿主(例如使用NoopAgentBackgroundEventSink,或只通过start_turn运行轮次的宿主)会让它一直等到下一个轮次:要么提交,要么关闭wakeOnBackgroundTasks,让模型像以前一样等待它的子代理。 - 审批与提问:
ApprovalRequested用resolve_approval回答,UserInputRequested用resolve_user_input回答,取消轮次用cancel_turn。 - 事件日志:每个会话保留一份有界的事件日志,
events_since(session, after)返回某个序号之后的AgentEventBatch,适合断开后补读;snapshot(session)返回会话当前的运行状态。 - 历史:
list_sessions_page(分页、可搜索)、open_session(会话及其最近的转录)、read_transcript_page和read_turn_page读取已提交的ConversationItem。recent_user_messages(limit, before)读取用户在顶层会话中发送过的内容,从最新的开始,相同的文字只出现一次,最多limit条,且不超过RECENT_USER_MESSAGES_MAX(1,000):消息、补充消息和!命令(!加命令);before(Unix 毫秒)只保留在它之前记录的内容。终端界面的 Ctrl-R 搜索的就是这些;请在界面线程之外调用。宿主自己的历史存储如果不维护索引,就没有这些内容:AgentHistoryStore::recent_user_messages默认返回空列表。工具调用显示的内容来自其工具的呈现器,从不是事件:tool_display(session_id, call_id)从历史中读回调用及其输出(在ToolCompleted到达之后、在界面线程之外调用),返回AgentToolCallDisplay { subject, display },display是一个AgentToolDisplay;present_tool_call(namespace, name, arguments, output)呈现已读到的转录页中的一个调用,output是ToolOutput条目的output和display_metadata(Some((&output, &display_metadata)))。Command显示的styled(Option<AgentStyledText>)是它的output的颜色:其字节的若干段(AgentStyleSpan { start, end, style }),每段一个AgentTextStyle(fg、bg为AgentTextColor::Indexed或Rgb,bold、dim、italic、underline、reverse);没有颜色的输出、被截短的输出或此前的会话为None;忽略它的界面像以前一样显示纯文本输出。补丁应用成功时,Patch显示的各文件带有hunk_starts(Vec<AgentPatchHunkStart>,每块在补丁前和补丁后的文件中的第一行),否则以及此前记录的调用为空;Content显示是逐项的输出(AgentOutputBlock),其中从不带图片或音频的数据。AgentToolDisplayMetadata在styled_output旁边有patch_hunk_starts。ToolStarted的presentation.subject是同一个主题,ExecutionProgress { call_id, update }指明报告它的进程属于哪个调用。列表只包含没有父会话的会话,除非请求的parent是AgentSessionParentFilter::ChildrenOf(session);不带这个字段的请求列出前者。AgentSessionSummary带有会话的parent_session_id和origin(AgentSessionOrigin:Side、Subagent、Review),以及创建时的cwd和branch,未知或在这些字段出现之前创建的会话为None;运行时快照带有parent_session_id、origin和ephemeral。思考内容是ConversationItem::Reasoning { text, duration_millis, sampling_step, truncated, replay }:其中text只用于展示,从不作为模型输入回放;replay是 Provider 要求回传的块(ModelReasoningReplay):类型化的条目带着它,加载的会话上 Chat Completions 的reasoning_content也一样,只有转录页的序列化略去它(思考)。 - 导出:
export_session_markdown(session)返回会话完整对话的 Markdown,读取其历史的全部页面:每条消息和计划一个## User、## Assistant或## Plan小节,每次工具调用一个## Activity小节(工具名和参数,以及输出的前几行),每个唤醒事件条目一个## Background updates小节(每个事件一行),不含思考过程(会话)。没有可显示内容的会话返回InvalidInput。它不提交任何内容;它会读取历史,所以要在异步运行时之外调用,与rename_session一样。 - 上下文:
session_context(session_id)(异步)读取/context显示的内容(终端界面),不提交任何内容:返回AgentSessionContext,其中有会话的窗口、用量(AgentModelUsage,其累计缓存数字给出会话的命中率)和request,即一个AgentContextRequest。Sent(AgentSentRequest)是本次运行中采样步骤最近发送的请求,在 Agent 运行期间为会话保留,从不持久化:包括它的composition、捕获时间,以及reported(AgentReportedPrompt:Provider 报告的提示总数和缓存读取、写入;在响应返回之前或没有统计时为None)。Next(composition)是对下一次请求的估算,用于本次运行还没有发送请求时或压缩之后:构建方式与压缩检查下一次请求时相同(启动插件宿主,不运行工具,不调用模型),不包含插件为采样步骤准备的内容,在回合之外也不包含上下文分段。Unavailable(reason)说明为什么连这也无法构建。AgentContextComposition包含每组的估算 token 数(指令;按 provider id 分组的工具,AgentContextTools;按类型分组的上下文分段,AgentContextSection;用户和助手消息、推理、工具调用及其输出、续接上下文、压缩摘要;图片及其数量;其余部分),它们相加等于total_tokens,即请求的估算。门面的panel模块重新导出 billion-context 的面板辅助函数(bar、cache_hit_stats、format_compact_tokens、format_hit_rate),供像终端界面那样绘制它的界面使用。 - 运行投影:
AgentSlot::list_run_projections与get_run_projection(活动 ID、轮次号、阶段、时间、错误),Hanafubuki 把它们映射到任务中心。
同一个后台 sink 还会收到 Changed { root }:这是合并后的变更提示,宿主应重新调用 background_tasks(root).await。快照包含 agents、terminals、pending_wake_events、wake(JSON 使用 camelCase)。代理字段与 subagents 相同,增加 state_since(stateSince,可选 Unix 毫秒时间),宿主据此计算经过时间,无须轮询。终端条目包含所属会话 id 和标题、状态、命令、工作目录及最近输出。终端生命周期变化刷新事件流,输出块不会。读取快照时,历史读取在 Agent 的阻塞池执行。代理开始或结束、标题或模型或推理强度变化、更新入队或投递、唤醒暂停或配置变化都会产生提示,流式增量不会。sink 可从不同 Agent 线程调用,只能排入有界工作,不能阻塞。Changed 与 Woken 不保证相对顺序,应读取当前快照,不应累计提示次数。忽略 Child 会让请求继续等待,忽略 Changed 会让任务显示过时。
会话与角色
| 调用 | 作用 |
|---|---|
create_session(mode, role)(async) | 以 mode 和 roles() 中的角色 role(None 即 default)新建会话:角色合并后的指令跟在基础指令之后,角色的模型和推理强度优先于 Provider 的,角色的收窄成为会话的 AgentCapabilityScope。没有任何来源定义的角色或不可用的角色被拒绝(一个列出可用角色的无效输入错误) |
set_session_role(session_id, role)(async) | 在轮次之间设置会话的角色:它的范围和指令作为新的修订持久提交,然后(角色设置了的话)通过 set_session_model 和 set_session_reasoning_effort 设置模型和推理强度;返回快照。有轮次运行时返回 TurnAlreadyRunning,有压缩运行时返回 CompactionAlreadyRunning。default 清除范围 |
快照(AgentSessionRuntimeSnapshot)带有会话的 role 和它范围的摘要(AgentCapabilityScopeSummary:多少个允许列表和模式、多少个拒绝模式、关闭的插件、上限);对 default 两者都是 None,在序列化的快照中不出现。会话把范围和角色的指令保存在自己的配置中,所以之后编辑或删除角色文件、或重启,都不改变什么。范围的作用见能力范围;宿主的会话除非提供角色,否则传 None。
权限
轮次的权限模式在它开始时确定:启动时给定的模式,否则是会话自己的模式(如果有),否则是配置的 permissionMode,再收紧到会话角色的 permissionModeCap。submit_turn_with_sink 和 submit_plan_implementation_with_sink 不给定模式;start_turn 给定它的输入中的模式(AgentTurnInput { text, images, skills, permission_mode },一个 Option<AgentPermissionMode>),由文本构造的输入(AgentTurnInput::from)不给定(None)。各模式和审批的行为见权限与审批。
| 调用 | 作用 |
|---|---|
set_session_permission_mode(session_id, mode) | 会话的模式,代替 permissionMode,随会话持久化,恢复时还原,但不随分叉复制。正在运行的轮次保持原来的模式,下一个轮次使用这个模式 |
session_permission_mode(session_id) | 会话被设置的模式;仍使用 permissionMode 时为 None |
set_session_sandbox_mode(session_id, mode) | 会话的 AgentSandboxMode(ReadOnly、WorkspaceWrite、FullAccess),代替 sandboxMode,随会话持久化,恢复时还原,但不随分叉复制;子代理沿用父会话的。正在运行的回合保持它的沙箱,下一个回合使用新的。与权限模式无关 |
session_sandbox_mode(session_id) | 会话被设置的沙箱模式;仍使用 sandboxMode(或平台默认值)时为 None |
sandbox_status() | SandboxStatus::Available { backend }(Linux 上为 "bubblewrap mount namespaces and seccomp",macOS 上为 "Seatbelt (/usr/bin/sandbox-exec)")或 Unavailable { reason },已应用配置的 [windows] sandbox:需要沙箱的命令能否运行(沙箱辅助进程) |
approve_denied_action(session_id, review_id) | 用户批准自动审查 review_id(来自 PermissionReviewCompleted { status: Denied })拒绝的操作,必须是会话最近十次拒绝之一:提交一条模型和下一次审查都会读到的上下文说明,并把不带轮次 ID 的 HistoryCommitted 发给会话最近一个轮次的 sink。它不开始轮次,也不执行任何操作;重试仍会再次审查 |
审查不是这些拒绝之一时,approve_denied_action 返回 ApprovalNotFound;轮次或压缩运行期间返回 TurnAlreadyRunning 或 CompactionAlreadyRunning。除只读取设置的 sandbox_status 外,这些调用可能加载会话的历史或等待它正在暂存的提交,所以要像 rename_session 和 set_session_mode 一样在异步运行时之外调用。
子会话
子会话记录它的父会话和创建它的原因;子会话和旁路对话是什么,见会话。
| 调用 | 作用 |
|---|---|
open_side_conversation(parent) | 父会话的旁路对话,以 AgentSessionRuntimeSnapshot 返回:从父会话最近的回合边界临时分叉出来,模型先读到旁路策略。再次打开返回已打开的那个。父会话还没有轮次时返回 InvalidInput |
close_side_conversation(side)(异步) | 中断旁路对话正在运行的轮次,停止它的后台终端并丢弃它;对不是旁路对话的会话返回 InvalidInput |
archive_session | 同时归档会话尚未归档的持久化后代(子会话在先),并关闭它存活的临时子会话 |
delete_session_confirmed | 在同一次删除中一并删除会话的持久化后代(不论是否已归档),并关闭它存活的临时子会话;任何一个不能释放,整个删除都会被拒绝 |
旁路对话上的轮次和其他会话一样,通过 submit_turn_with_sink 运行,使用各自的 AgentEventSink。临时会话从不被列出、归档(InvalidInput)或恢复;关闭它、归档或删除它的父会话、或 Agent 停止时,它就消失了。open_side_conversation 会阻塞,和 rename_session 一样,要在异步运行时之外调用。
编辑之前的消息
edit_from_turn(session_id, turn_id) 像终端界面的 Esc 那样编辑开始 turn_id 这个轮次的消息(见会话)。它在该轮次之前分叉会话(与 fork_session_before_turn 相同,使用会话当前的 generation 和 revision),归档原会话(与 archive_session 相同,因此连同它的持久化后代),并返回 AgentEditFromTurn { session, restored_prompt, restored_images }:分叉出的会话的运行时快照,以及这条消息的文本和图片附件,用于放回输入框。
turn_id是ConversationItem::TurnStart的turn_id,用read_transcript_page读取;它之后的UserMessage就是被恢复的消息。没有这样一条消息的轮次(不是由消息开始的)会被拒绝。- 对已归档的会话、会话中有轮次运行时、对子会话或临时会话、以及对会话中不存在的轮次,它返回
Err并说明原因。 - 如果分叉已经完成但原会话无法归档(例如某个后台终端停不下来),错误会说明这一点并给出分叉出的会话;两个会话都会保留。
- 文件不会恢复。它会阻塞,和
rename_session一样,要在异步运行时之外调用。
功能调用
list_background_terminals(session_id) 返回该会话所属的后台终端,供宿主展示并选择要关闭的终端。
close_subagent(child) 异步确认其存活子树的回合和终端都停止,清除被关闭会话的排队更新,只向所选子代理的父会话报告一次 ClosedByUser。关闭的子代理仍可接收后续任务。close_background_terminal(owner, execution_id: AgentExecutionId) 阻塞直到一个终端停止,然后向所属会话报告 StoppedByUser。stop_background_terminals_confirmed(owner) 对全部终端执行相同操作,把这些报告一起入队。阻塞的终端方法应在界面和异步运行时线程之外调用。归档、删除和关闭旁路对话时静默清理终端。
background_tasks(root) 按父代理在前的顺序列出整棵树;subagents(parent) 仍只列出直接子代理。Agent 的调度器自行恢复嵌套子代理,因此宿主只收到主对话的 Woken。resume_background_wakes(root) 清除暂停并重新检查所有后代,即使主对话自己没有排队更新。单独提交一次唤醒回合不会清除暂停。
有些功能由插件行承担,服务 API 每次调用时找到它们:
| 调用 | 返回 | 所属的行 |
|---|---|---|
recap_session(session_id) | AgentRecap { summary, next_action }:根据会话最近的往来生成的概要 | recap |
suggest_session_title(session_id) | 对话当前的标题建议,用户在 rename_session 之前接受或编辑它 | titles |
goal(session_id) | 会话的目标,Option<AgentGoal>:objective、status(AgentGoalStatus)、origin(AgentGoalOrigin:User、Model)、token_budget、time_budget_seconds、tokens_used、time_used_seconds、created_at 和 updated_at(毫秒) | goal |
set_goal(session_id, objective, budgets) | 带 AgentGoalBudgets { token_budget, time_budget_seconds } 的新活动目标,替换会话现有的目标;目标内容为空、超过 MAXIMUM_GOAL_OBJECTIVE_CHARS(4,000)、预算为零或会话是临时会话时返回 InvalidInput | goal |
pause_goal(session_id)、resume_goal(session_id) | 暂停目标(处于活动状态时),或让它重新活动(预算用尽时为 BudgetLimited);没有目标时返回 InvalidInput。恢复不会开始回合:会话的下一个回合继续推进目标 | goal |
clear_goal(session_id) | 移除目标;返回之前是否有目标 | goal |
worktree_create(owner) | AgentWorktree { path, head, branch, owner }:第一个工作区根目录所在仓库的新工作树,分离在它的 HEAD,给出 owner(一个会话)时绑定到它 | worktree |
worktree_list() | 该仓库在数据目录 worktrees/ 下的工作树 | worktree |
worktree_bind(path, session) | 把工作树绑定到会话;已属于另一个会话的被拒绝 | worktree |
worktree_remove(path) | 删除工作树,连同本地修改;第一个工作区根目录在其中时被拒绝 | worktree |
hooks_list() | AgentHooks { hooks, diagnostics }:现在重新读取的每个已配置钩子,形式为 AgentHook { key, event, matcher, handler, source, source_path, trust, enabled, current_hash }(HookEventName、HookSource、HookTrust),以及配置中无法使用的内容 | hooks |
set_hook_enabled(key, enabled) | 开启或关闭一个钩子 | hooks |
trust_hooks(keys) | 按当前定义信任每个钩子(传入所有键即全部信任);之后定义改变会收回信任 | hooks |
subagents(parent) | Vec<AgentSubagentStatus { session_id, parent_session_id, depth, title, status, provider_id, model, reasoning_effort, last_answer, state_since }>:父会话创建的子代理,按创建先后;status 是 Running、Waiting、Idle、Failed 或 Closed;parent_session_id 是直接父会话,depth 为 1 或 2,title 是任务名,provider_id、model 和 reasoning_effort 是它的会话当前运行的 Provider、模型和推理强度(reasoning_effort 为 None 表示 Provider 的默认值;JSON 中为 providerId、model、reasoningEffort),last_answer 是它最近一次回答的前 400 个字符 | subagents |
interrupt_subagent(session_id) | 中断子代理正在运行的回合(如有),等待中断得到确认;子代理保留,可以继续接受任务。不是子代理的会话返回 InvalidInput | subagents |
start_review(parent, target) | 在工作目录的仓库中运行对 target(AgentReviewTarget:UncommittedChanges、BaseBranch { branch }、Commit { sha, title }、Custom { instructions })的评审并等待它:AgentReviewOutput { findings, overall_correctness, overall_explanation, overall_confidence_score, child_session },每条发现是 AgentReviewFinding { title, body, confidence_score, priority, code_location };render_text() 给出它的文本形式 | review |
cancel_review(child) | 中断评审会话的回合并等待中断得到确认;它的 start_review 随后返回 Cancelled。不是评审的会话返回 InvalidInput | review |
review_targets() | AgentReviewTargets { branches, current_branch, commits }:工作目录的本地分支(main 或 master 在前)、当前分支(分离时为 None)和最近 100 个提交(AgentReviewCommit { sha, subject }) | review |
前两个在会话的对话之外询问会话的模型,不提交任何东西。该行关闭(disabledPlugins)、启动中、失败或重启时,调用返回 AgentError::FeatureUnavailable { feature, reason },reason 说明原因;调用期间该行代码中的 panic 只停止并重启这一行,调用返回同样的错误。没有可读请求的会话返回 InvalidInput,模型请求失败返回 Model。失败的工作树调用(不是 Git 仓库、不是 Agent 的工作树、属于另一个会话、git 失败)返回带原因的 InvalidInput。目标的变化,不论由谁做出,都是会话事件 SessionGoalUpdated { goal }(清除时为 None),发送给会话正在运行的回合的 sink(如果有)。独立模式的使用者用 AgentRuntime::set_working_directory 移入工作树。指定了没有钩子使用的键,或状态文件无法写入的钩子调用,返回 InvalidInput。在宿主中,钩子只从它的配置目录读取;它们的信任与启用状态在数据目录的 hooks-state.json 中。
评审是持久的子会话(来源 Review),start_review 一创建它,它就列在父会话的子会话中,界面借此在调用等待期间找到要显示或要 cancel_review 的会话。没有过回合的会话、空白的自定义请求,或 Git 仓库之外的基础分支,start_review 返回 InvalidInput;被中断或失败的评审会告知父会话并返回错误。父会话收到的说明是提供者 agent、钩子 review-exit 的 ContinuationContext;评审结束时父会话若正在运行回合或压缩,调用会等它结束。AgentReviewTarget 是带标签的对象({"type": "baseBranch", "branch": "main"}),拒绝未知字段。
子代理是持久的子会话(来源 Subagent);完整历史和事件日志仍属于它自己。由 subagents 插件驱动的回合只通过 AgentBackgroundEvent::Child { root, session_id, event } 转发 TurnStarted、审批和问题的请求及解决事件、回合结束事件(event 使用 Box)。用事件中的会话、回合和 generation 在子代理上回答请求。流式输出不转发;显示子代理时通过 events_since 读取。用户直接开始的回合使用传给 submit_turn_with_sink 的 sink。
已安装的插件
已安装的插件位于数据目录的 plugins/ 中,Agent 设置中的 [plugins] 说明哪些启用。服务在构建时读取它们,并在每次重新加载时再次读取:
reload_packages()按设置重新加载已安装的包,并在不重启的情况下更新 Agent:Skill 目录读取启用的包的 Skill,下一轮的钩子包含它们的钩子,它们的 MCP 服务器运行(返回时,新增或变更的服务器已经连接或失败;不再存在的已断开)。服务在write_settings、set_plugin_enabled、mcp_write_server和mcp_delete_server之后在后台调用它,plugins行在已链接包的目录改动之后也会调用它;以其他方式写入[plugins]或改变存储的宿主自己调用它。packages()返回Vec<AgentPackageStatus { id, version, format, display_name, description, source, enabled, content, hooks_to_trust, guest, issues }>:每个已安装的包,无论启用与否;source是它的安装来源(PackageSource,没有安装记录时为None);content(AgentPackageContent { skills, mcp_servers, hooks, roles })是它启用时贡献的内容(Skill ID、它运行的 MCP 服务器名称、钩子键、它的角色名<插件>:<角色>);hooks_to_trust是它等待信任的钩子的键(trust_hooks);guest是它的代码的状态,只有带运行时的本项目格式的包才有(AgentPackageGuest { runtime, permissions, granted_permissions, status, settings, config_schema },runtime是RuntimeKind(Process或Wasm),status是GuestStatus { state, error, last_exit, stderr_tail, restarts, process_id, issues };ungranted()是它请求但尚未授予的权限,WebAssembly 模块永远没有);issues是无法读取或使用的部分。package(id)是其中一个,未安装时为None。安全模式下这些包会被列出,但都不加载。grant_package_permissions(id, permissions)记录用户授予包的代码permissions(PackagePermissions { network, workspace, env },即同意时展示的权限),然后重新加载包;程序访客只在清单请求的权限都已授予后才启动,WebAssembly 访客什么也不请求。retry_package(id)以空的重启窗口再次启动失败的访客(代码插件)。set_package_settings(id, settings)替换包的代码的设置([plugins."<id>"].settings,一个 JSON 对象;null表示移除),按其清单的configSchema校验,然后重新加载包:它的访客以这些设置重新启动,并把它们视为自己的settings。AgentPackageGuest给出settings、config_schema,以及在status.issues中给出其声明的贡献中被略去的部分(代码插件)。validate_package(dir)是一个自由函数,在安装之前检查一个插件目录,与plugins validate相同(检查):像安装那样读取它的清单、它声明的路径,并像访客宿主运行它那样检查它的代码,但不启动任何东西。它返回AgentPackageValidation { name, version, format, manifest, code, issues };目录中没有安装能接受的清单时返回错误。- 访客在平台的沙箱中运行,而在 Linux 和 Windows 上沙箱就是程序自己作为沙箱辅助进程再次启动:不调用
helper_dispatch()的程序不运行任何访客。
生命周期调用通过服务打开的那个存储改变已安装的插件,写入设置,重新加载,并在结果生效后返回。每个调用都用包的 ID(<plugin>@<marketplace>)指明包;错误是 String。
| 调用 | 作用 |
|---|---|
install_package(AgentPackageSource) | Marketplace { marketplace, plugin } 安装已添加市场中的插件;Directory { path, marketplace } 安装目录中的包,归入 marketplace(为 None 时是 LOCAL_MARKETPLACE,即 local);Linked { path, marketplace } 则按引用链接这个目录:不复制、不固定,plugins 行运行期间跟随它,从不更新(链接)。启用它(enabled = true),返回 AgentPackageInstall { package, root, migrated_commands, issues, hooks_to_trust, permissions }:hooks_to_trust 是它的钩子(AgentHook),信任后才运行;permissions 是代码包的访客请求但尚未授予的权限(Option<PackagePermissions>,交给 grant_package_permissions),内容包或 WebAssembly 访客为 None |
uninstall_package(id, purge_data) | 删除它和它的 [plugins] 条目(已链接包的目录保留);只有 purge_data 时才删除数据目录。返回 AgentPackageUninstall { id, purged_data };未安装的包是错误 |
set_package_enabled(id, enabled) | 写入 [plugins."<id>"] enabled,合并进用户的文件(mcpServers 保留);返回包的状态。所属市场被关闭的包不能启用 |
update_package(id) | 从它已添加的市场(按市场当前的内容)重新安装,否则从它原来的目录;启用状态不变。返回 AgentPackageInstall;已链接的包是错误 |
retry_package(id) | 重新加载,访客失败时以空的重启窗口再次启动它,并返回包的状态 |
marketplaces() | Vec<AgentMarketplace { name, display_name, source_type, source, ref_name, sparse_paths, enabled, last_updated, last_revision, root, plugins, issues, error }>:已添加的市场([marketplaces])及其每个插件(AgentMarketplacePlugin { id, name, display_name, description, version, installable, installed, enabled });读不了的市场带 error |
add_marketplace(MarketplaceAddRequest { source, ref_name, sparse_paths }) | 本地目录(原地使用),或 git 仓库(URL、owner/repo[@ref]),克隆到 plugins/marketplaces/ 下;写入它的记录。返回 AgentMarketplaceAdded { name, root, already_added } |
upgrade_marketplace(name) | 把 git 市场 name(为 None 时是每个已添加的 git 市场)更新到远程的提交:返回 Vec<AgentMarketplaceUpgrade { name, upgraded, error }>;指定名字时,它的失败就是调用的失败 |
remove_marketplace(name) | 删除它的记录以及 git 市场的检出;从它安装的包仍然保留 |
对包的每个生命周期调用都会在重新加载之后告诉插件事件接收器:AgentPluginEventSink::package_changed(&AgentPackageChange { id, kind, error }),kind 为 Installed、Removed、Enabled、Disabled、Updated,或 Failed(调用失败,error 说明原因;包保持原样)。这个方法有空的默认实现,所以只在 plugins_changed 时刷新的接收器无需修改。retry_plugin(name) 重新启动失败的内置行或宿主行;命令行通过 --safe-mode(AgentStartOptions::safe_mode)进入安全模式。
- 插件的钩子由
hooks_list()列出,source为{"plugin": {"id", "root", "data"}}(HookSource::Plugin);用户和项目的钩子仍是"user"和"project"。 mcp_snapshot()把插件的服务器列为plugin_servers(McpPluginServerSnapshot { plugin, server, status });settings仍是mcp.toml的内容。plugin_status()中有plugins行,它把启用的包告诉模型。
日志
门面默认不安装日志器:宿主保留自己的 log 实现,Agent 的记录进入其中。独立二进制使用 logging::install_file_logger(hanafubuki-agent.log,超过 8 MiB 轮转到 .1….3)。Agent 自己的记录遵守内容日志规则:模型内容、推理、工具参数和工具结果只在 trace 级别出现,并截断到上限,从不记录请求头和凭据。所以宿主的日志级别就是用户选择 trace 的方式(Hanafubuki 的 log_level 设置)。
测试
- 在
[dev-dependencies]中为hanafubuki-agent打开test-supportfeature,得到hanafubuki_agent::test_support:mount(在一个提供注册表与PluginFaults的上下文中挂载插件)、test_host、脚本化的模型服务器与 MCP 服务器。给了模型列表时(FakeServer::with_listings、FakeListing),脚本化的模型服务器用它们回答GET …/models;否则像对待其他请求一样用下一个响应回答。测试用 Agent(new_with_host)不自己发现模型,configure_test_provider也会写入modelMetadata.discovery = "off",所以即使测试像宿主那样自己构建 Agent(AgentApplicationService::open),脚本化服务器也只看到测试自己的请求。 - 宿主应保留自己的 golden 测试,固定加上宿主插件与指令后模型收到的内容;Agent 一侧模型可见的变化也会改变它们,需要有意地重新生成。
- panic hook 桥由宿主在子进程中测试。
会话工作区与剪贴板图片
嵌入宿主通过 create_session_with_workspace(mode, role, path) 创建已绑定目录的会话,或用
set_session_workspace(AgentSessionWorkspaceRequest) 修改空闲会话;请求携带会话 id、generation、revision 和路径。
创建操作先解析目录,再提交会话。绑定持久保存,fork 和子会话继承。它与历史 cwd 元数据不同:
没有显式绑定的会话仍跟随宿主工作区,包括独立模式的 /cd。已绑定目录消失时操作失败,绝不回退到宿主目录。
该会话运行回合、压缩或后台终端时拒绝修改绑定;其他会话可以在各自目录继续运行。
回合准入冻结文件工具、命令 cwd 和沙箱策略、工作区指令、仓库 Skills、图片读取及 hooks 使用的根目录。 各会话的服务视图共享进程所有权注册表;切换会话不会改写运行中回合的全局工具策略。 配置层和已安装插件包仍属于运行中的 Agent;目录绑定不会隐式信任项目配置。
实际根目录通过 session_workspace_roots(id) 读取,文件引用通过 search_user_files_for_session(id, request) 搜索;list_skills_for_session(id) 读取会话目录的 Skill 列表,diff_for_session(id) 读取 Git 改动。
Review 使用父会话目录;review_targets_for_session、worktree_list_for_session、worktree_remove_for_session
接收会话 id;worktree_create(Some(owner)) 从该拥有者的工作区创建。全局版本保留给独立模式的工作区视图。
创建 worktree 不会自动迁移会话,宿主在创建后显式绑定。
import_image_bytes(session_id, bytes, display_name, detail) 无需中间文件即可接收剪贴板图片,
应用与选择文件相同的源文件大小、解码像素、支持格式和归一化限制,再暂存持久附件。
通过 read_image_preview 预览,并以 DesktopAgentImageInput.attachment 提交返回的引用。
宿主不直接写入附件目录,也不在丢弃草稿时自行删除存储文件。
嵌入宿主咨询与激活 Advisor
宿主与独立模式使用同一设置目录。通过 write_setting_values 一次写入 pluginOptions.advisor.provider 和 pluginOptions.advisor.model。宿主可提供单次咨询按钮,或由用户显式切换激活状态。
let answer = agent.consult_advisor(session_id, question, cancellation).await?;
agent.set_advisor_active(session_id, true).await?;需要提交草稿、具名文件或追问时使用 consult_advisor_with。