hanafubuki-agent

嵌入 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-runtimeContainedRuntime:每个 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 目前就是这样)。

组合

嵌入时宿主自己组装独立模式也在用的几个部件:

部件作用
AgentSlotAgent 的状态机与监督者:启动、内核故障后的自动重启、崩溃循环停止、开关、状态
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 是独立模式的使用者可以替换的部分:

字段默认值说明
secretsNone:操作系统钥匙串(keyring 4)服务名 org.licyk.hanafubuki-agent.secrets
statusNoopAgentStatusEventSink槽位状态改变时调用 status_changed(),不携带负载
plugin_eventsNoopAgentPluginEventSink插件状态的提示,以及每次已安装插件的变化
mcp_eventsNoopMcpEventSinkMCP 状态与工具目录变化
backgroundNoopAgentBackgroundEventSink为后台工作唤醒某个会话时的 Woken(见下)

轮次与会话事件不经过这里,而是发给每次调用传入的 AgentEventSink(见事件与历史)。

宿主接口

宿主只能通过 AgentHostPorts 向 Agent 添加东西。接口只接受普通值(PathBuf、字符串、映射)或 Agent 自己的类型:Agent 带有自己的 foundation、process 和模块宿主的副本,与宿主的同名类型是不同的类型,宿主在边界处做转换。

字段类型作用独立模式默认
pluginsVec<(AgentPluginRow, AgentPluginDescriptor)>宿主插件行,各带其描述符无
workspaceArc<dyn WorkspaceRootsPort>工作区根目录、受保护的目录、指令查找的选中目录、文件搜索根目录工作目录、它的 Git 根目录、--add-dir
steering_contextArc<dyn HostContextPort>steering 消息携带的宿主上下文NoHostContext
instructionsAgentHostInstructions身份、应用名,以及宿主加入基础指令的段落AgentHostInstructions::default()
networkArc<dyn NetworkSettingsPort>Web 工具、MCP、OAuth、模型 Provider 与 models.dev 使用的代理配置文件的 [network] proxy
secretsArc<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 秒,关闭按固定阶段进行,每个阶段有自己的期限:

停止 Skill 监视器(2 秒);关闭槽位,取消进行中的启动并最多等待 8 秒。

停止接受新轮次,取消轮次与压缩(包括后台压缩)并等待它们(5 秒):已完成的后台压缩先记录它的用量。

MCP:取消后台连接,关闭每个连接并确认其进程已退出(4 秒)。
停止插件:一次性释放 kardia 根(5 秒)。
停止记忆工作线程,关闭历史,停止服务工作线程(取消进行中的模型列出)与执行(3 秒)。
清理实例的进程所有者组:终止 Agent 自己启动、仍在运行的进程(1 秒)。
停止实例的运行时,阻塞池有 2 秒上限。

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.tomlProvider 注册表及其修订号,令牌原样保存(仅所有者可读)
mcp.tomlMCP 服务器与凭据值及其修订号(仅所有者可读)

与独立模式不同,嵌入的配置没有分层(没有 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:

  1. 调用 mcp_oauth_start(McpOAuthLoginRequest { server_id, redirect_uri }),打开返回的授权 URL。
  2. 保存返回的 flow ID,将完整回调 URL 交给 mcp_oauth_complete(McpOAuthCallbackRequest { server_id, flow_id, callback_url }),或用 mcp_oauth_cancel(McpOAuthCancelRequest { server_id, flow_id }) 取消。
  3. 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)、预算为零或会话是临时会话时返回 InvalidInputgoal
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)中断子代理正在运行的回合(如有),等待中断得到确认;子代理保留,可以继续接受任务。不是子代理的会话返回 InvalidInputsubagents
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。不是评审的会话返回 InvalidInputreview
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-support feature,得到 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。

本页目录