hanafubuki-agent

编写插件

编写带代码的可安装插件——用 Rust、Python 或任何语言写一个由 Agent 在进程外运行的程序,或一个由 Agent 在限制内运行的 WebAssembly 模块——然后校验它、在实时重载中开发它,并通过市场发布它。

可安装插件是一个包:一个带清单的目录,Agent 从一个目录或一个市场安装它(已安装插件)。Codex、Claude Code、Cursor 或 Agent Plugins 格式的插件提供内容(Skill、MCP 服务器、hook),不需要代码。本页讲的是本项目自己的格式 .hanafubuki-plugin/plugin.json:这种插件还可以带代码,即插件的访客(guest):一个由 Agent 在进程外启动、用沙箱限制的程序,或一个由 Agent 在燃料、时间和内存限制内运行的 WebAssembly 模块。Agent 为清单声明的工具、上下文段、提示片段、hook 和观察者调用它(代码插件)。访客崩溃或卡住,损失的只是它自己的贡献。

创建插件

hanafubuki-agent plugins new 名字 写出一个带代码、可以直接构建的插件:

hanafubuki-agent plugins new my-plugin                  # Rust,位于 ./my-plugin
hanafubuki-agent plugins new my-plugin --target wasm    # Rust,编译为 WebAssembly
hanafubuki-agent plugins new my-plugin --lang python --dir plugins/my-plugin
my-plugin/
├── Cargo.toml                          访客的 Cargo 项目(Rust),或 plugin.py(Python)
├── src/main.rs                         (WebAssembly 时为 src/lib.rs)
├── README.md                           如何构建、检查和运行它
└── package/                            Agent 安装的插件
    └── .hanafubuki-plugin/plugin.json

Rust 插件提供一个工具(greet)、一个上下文段(<名字>_status,它读取工作区)和一个观察者(turn_finished);WebAssembly 插件提供同样的内容,但它的上下文段不读取工作区——模块访问不到工作区;Python 插件提供一个工具(count_words)和一个提示片段。每个清单都声明了 configSchema,程序的清单还声明了权限。仓库的 examples/plugins/ 收有这三个插件,内容与 plugins new 写出的完全相同(hello-rust、hello-wasm、hello-python)。

package/ 特意与源码分开:安装会把整个包(.git 和符号链接除外)复制到数据目录并计算哈希,只有包仍是这个哈希时访客才会启动。如果构建目录(target/)在包里,每次安装都会复制它并计算哈希。构建时把程序或模块放进 package/:

cargo build --release && cp target/release/my-plugin package/                 # Rust
cargo build --release --target wasm32-unknown-unknown \
  && cp target/wasm32-unknown-unknown/release/my_plugin.wasm package/my-plugin.wasm  # WebAssembly
python3 -m pykardia.guest.export process plugin.py Plugin package/my-plugin.pyz  # Python

包

路径是什么
.hanafubuki-plugin/plugin.json清单
访客的程序或模块runtime.command 指定的文件(./my-plugin、./my-plugin.pyz),访客只能读它;或 runtime.module 指定的文件(./my-plugin.wasm)
skills/、.mcp.json、hooks/hooks.json、commands/内容,与 Codex 和 Claude Code 的格式相同(Skill、插件的服务器、插件的 hook)
agents/内容:角色文件(角色)

插件可以只有内容、只有代码,或两者都有。它的 ID 是 <名字>@<市场>;从目录安装的插件是 <名字>@local。程序运行时,工作目录是插件自己的数据目录(PLUGIN_DATA),也是它唯一能写的地方;PLUGIN_ROOT 是安装后的包。模块两者都没有。

清单

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "What it does.",
  "runtime": { "type": "process", "command": ["./my-plugin"], "protocol": "kardia-guest/2" },
  "contributes": {
    "tools": [
      {
        "name": "greet",
        "description": "Greets someone by name.",
        "inputSchema": {
          "type": "object",
          "properties": { "name": { "type": "string" } },
          "required": ["name"],
          "additionalProperties": false
        },
        "timeout": 10
      }
    ],
    "contextSections": [{ "kind": "my_plugin_status" }],
    "prompt": { "slot": "capabilities" },
    "toolLifecycleHooks": false,
    "continuationHooks": false,
    "observers": ["turn_finished"]
  },
  "permissions": { "network": false, "workspace": "read", "env": [] },
  "configSchema": {
    "type": "object",
    "properties": { "greeting": { "type": "string" } },
    "additionalProperties": false
  }
}

清单按外部生产者的数据读取:无法使用的字段或列表中的条目会被略过并记为问题,其余部分照常使用。plugins validate 会列出所有问题。

字段含义
name插件的名字:它 ID 的第一部分、它的工具的命名空间,也是它的访客声明的名字
version、description、keywords、interface与 Codex 的清单相同;版本是安装副本的名字
skills、mcpServers、hooks、commands、agents内容,每个都是以 ./ 开头、留在包内的路径(mcpServers 和 hooks 也可以直接写在清单里);agents 是一个角色文件目录或单个文件,或它们的列表,用来代替 agents/(角色)
runtime.typeprocess(程序)或 wasm(WebAssembly 模块)
runtime.commandprocess:程序和参数;程序是包里的文件(./…),或者在 runtime.interpreter: true 时是一个解释器(绝对路径,或 Agent 的 PATH 上的名字),以包里的文件作为参数
runtime.protocolprocess:kardia-guest/2
runtime.modulewasm:模块,包里的一个二进制 .wasm 文件(./…)
runtime.limitswasm:每次调用可以使用多少,每项都可选:fuel(大约每条指令一个单位;未设置时不计燃料)、timeoutMs(最多 3600000;未设置时为它最长的调用:10 秒的调用期限或更长的工具 timeout)、memoryBytes(64 KiB 到 4 GiB;256 MiB)
contributes.tools[]name(ASCII 字母、数字、_、-)、description、inputSchema(JSON Schema 对象)、timeout(秒,大于 0 且不超过 3600;未设置时为 10 秒的调用期限)。模型看到的名字是 <插件>__<名字>;每次调用都要用户批准。界面按回退显示显示调用的结果:结构化结果的顶层键,否则显示它的文本
contributes.contextSections[]kind(小写字母、数字和 _,不能是 Agent 自己的种类);最多 7 个。插件的段在所在槽位中排在 Agent 和宿主的段之后,彼此按种类名排序(上下文渲染器)
contributes.prompt.slotinstructions、worldState、capabilities(默认)或 memory
contributes.toolLifecycleHooks、contributes.continuationHooks为 true 时,每次工具调用前后、每个候选最终回答都会询问它
contributes.observers要通知它的事件:turn_admitted、sampling_committed、turn_finished、memory_contribution_changed、session_archived、session_restored、wake_event_queued
permissions.network为 true 时可以访问网络(默认关闭)。这三项权限是程序的:模块不请求任何权限
permissions.workspacenone、read(默认)或 write
permissions.env访客会收到的 Agent 环境变量的名字
configSchema一个对象的 JSON Schema:插件的设置,降低为选项,plugins settings 和 /plugins 按这些选项检查设置,访客收到的设置也按它们检查过(configSchema)

每种声明变成什么、有哪些限制,见访客贡献什么。

角色

插件可以带来角色:只会收窄 Agent 的工作方式定义,会话或子代理随后以它们运行。本项目格式的插件以角色文件的形式提供它们:agents/(包括子目录)或清单中 agents 指定的路径里的 .toml 文件,可以使用角色文件的每一个键:

# agents/reviewer.toml
description = "审查一次改动并列出发现的问题;从不编辑。"
extends = "explorer"
instructions = "每个问题都给出文件和行号。"

每个角色以 <插件>:<角色> 命名,插件部分取自它 id 中的插件名(my-plugin:reviewer);extends 按角色目录中的名字引用角色(同一插件的角色写作 my-plugin:base)。插件开启期间这些角色才存在。读取它们时略去的内容是插件的问题:plugins validate 会列出它,插件安装并开启后 plugins info 也会列出。优先级、合并规则和会话见插件的角色。

Claude Code 代理文件

Claude Code 插件的代理文件,即它的 agents/(或清单中 agents)里的 .md 文件,也会作为角色读取。frontmatter 逐键读取,类型错误的键会被略去并记一条问题:

  • name:角色名,接在插件名之后(<插件>:<name>);无法作为角色名或者没有写时,改用文件名。
  • description:角色的描述,角色必须有它。
  • tools:角色只能使用的工具,逗号分隔的列表(Read, Grep, Glob)或 YAML 列表,按下面的工具对照表映射。表中没有的名字会被略去并记一条问题;因此一个全由表中没有的名字组成的列表不允许任何工具。没有 tools 时,角色不收窄工具。既不是文本也不是列表的 tools 会让角色不可用,因为略去它会允许所有工具。
  • disallowedTools:角色禁止的工具,写法与 tools 相同,按同一张表映射;禁止优先于允许。表中没有的名字(NotebookEdit)会被略去并记一条问题:本 Agent 没有这个工具可禁。整个 MCP 服务器(mcp__github)会禁止它的所有工具(mcp__github__*)。带限定的工具(Bash(git push:*))在这里无法表达,因为角色只能指名工具,不能指名它的调用,所以禁止整个工具(exec_command),并记一条问题。不是文本的列表项会被略去并记一条问题;既不是文本也不是列表的 disallowedTools 会让角色不可用。
  • permissionMode:角色的 permissionModeCap,按下面的模式对照表映射。不是文本时角色不可用。
  • model:inherit 沿用会话的模型。其他值(sonnet、opus、haiku)不是本 Agent 的任何模型,因此被忽略并记一条问题,模型同样沿用。
  • frontmatter 之后的正文:角色的指令。

其他键(color 之类)被忽略。没有 frontmatter 的文件,或者 frontmatter 即使给含有 : 的普通值加上引号后仍不是 YAML 的文件,会被略去并记一条问题。

Claude Code本 Agent
Readread_file
Grepsearch_text
Glob、LSlist_directory
Edit、MultiEdit、Writeapply_patch
Bashexec_command
WebFetchfetch_web_page
WebSearchweb_search
mcp__<服务器>__<工具>同名,即某个 MCP 服务器的工具
permissionMode角色
default上限为 manual
acceptEdits上限为 auto_review
bypassPermissions上限为 full_access,即不设上限
plan上限为 manual,并禁止写入类工具(见下)
dontAsk上限为 manual,并记一条问题:拒绝一切未允许的操作不是上限
其他值上限为 manual,并记一条问题

plan 禁止的是计划模式从默认会话中去掉的工具,即 Agent 自己的非只读工具:apply_patch、delete_path、move_path、exec_command、write_stdin、resize_execution、create_goal、update_goal、spawn_agent、followup_task、send_message、interrupt_agent、enable_skill、disable_skill 和 append_agent_memory_note。内核自己的工具(update_plan、new_context、request_user_input)保留,因为角色从不去掉它们。MCP 工具也会被禁止(mcp__*),除非代理写了 tools:这时角色只允许列出的工具,包括列出的 MCP 工具,禁止 mcp__* 会把它们去掉。与 计划模式保留标注为只读的 MCP 工具不同,plan 只保留 tools 列出的 MCP 工具;它也不禁止其他插件的工具:已安装插件的代码注册的工具,无论是否写入,都会保留,除非 tools 没有列出它。

Codex 格式的包没有角色。

访客

访客是一个在标准输入和输出上使用 Kardia 访客协议(kardia-guest/2)的程序:它的元数据恰好是清单中的 name,只提供一个服务 plugin;它的 apply 收到它的设置并提供 plugin;Agent 调用 plugin 的方法,每种贡献一个:tool、context、prompt、beforeToolUse、afterToolUse、continuation、observe。这些方法、参数和回答见访客协议;访客可以 view 什么(它的工作区和它的设置)见访客能访问什么。

标准输出属于协议:访客绝不能向它打印。它把日志写到标准错误,或通过宿主的 log 发送;Agent 保留它标准错误的最后 16 KiB 作为状态的一部分,并且只在 trace 级别记录访客的原话。

Rust

kardia-guest 实现了这个协议:实现它的 Guest trait,在 main 中调用 serve。

use kardia_guest::{json, Guest, Host, Map, Meta, Request, Result, Value};

struct Plugin;

impl Guest for Plugin {
    type Config = Value;

    fn meta() -> Meta {
        Meta::plugin("my-plugin").provide("plugin")
    }

    fn apply(host: &Host, _settings: Value, _imports: Map<String, Value>) -> Result<Self> {
        host.provide("plugin", &json!({}))?;
        Ok(Plugin)
    }

    fn call(&mut self, _host: &Host, request: Request) -> Result<Value> {
        match request.method.as_str() {
            "tool" => {
                let name = request.args["arguments"]["name"].as_str().unwrap_or("world");
                Ok(json!(format!("Hello, {name}!")))
            }
            method => Err(format!("no method {method}").into()),
        }
    }
}

fn main() {
    kardia_guest::serve::<Plugin>();
}

调用中的 panic 会被捕获,成为该调用的错误。

Python

pykardia 的访客 SDK 用 Python 实现了这个协议:继承 pykardia.guest.Guest,再把这个类导出为进程访客——一个打包了 SDK 的 zipapp,可在任何 Python 3.10 及以上版本运行:

python3 -m pip install git+https://github.com/licyk/pykardia
python3 -m pykardia.guest.export process plugin.py Plugin package/my-plugin.pyz

清单用 Agent 的 PATH 上的解释器运行它:"command": ["python3", "./my-plugin.pyz"], "interpreter": true。在沙箱中,访客只能读系统目录(/usr、/lib 等)、它的包和它的解释器程序本身,所以解释器必须是系统的:主目录下的虚拟环境或版本管理器的 Python 在那里读不到自己的标准库。这个 SDK 从其仓库的 main 开始使用 kardia-guest/2;PyPI 上的 0.1.0 版本更早。

SDK 的许可证

kardia-guest 和 pykardia 的访客 SDK(pykardia/guest/ 以及导出时一并打包的模块)采用 MIT OR Apache-2.0 许可证,所以链接或打包它们的插件可以自行选择许可证;导出的 zipapp 附带它们的许可证文件。Kardia 和 pykardia 的其余部分以及 Agent 本身是 GPL-3.0-only;访客是一个独立的程序,Agent 运行它并通过管道与它通信。

WebAssembly

访客也可以是一个 WebAssembly 模块("runtime": {"type": "wasm", "module": "./my-plugin.wasm"}),Agent 用 wasmtime 在自己的进程内运行它。它通过访客 ABI 的导出和宿主函数而不是管道使用同样的方法,并且由同一份 Rust 源码构建:在 cdylib crate 中用 kardia_guest::export!(Plugin) 代替 main,再用 cargo build --target wasm32-unknown-unknown 构建(plugins new --target wasm 会写出这样的 crate)。

  • **它访问不到自身以外的任何东西。**它能导入的函数只有访客 ABI 的函数(read、write、log、provide、view、invoke,来自模块 cordis 或 kardia):没有文件、网络、时钟或环境变量。导入其他任何东西(例如 WASI)的模块无法加载。所以它不请求任何权限,不需要授权也不需要沙箱,安装并启用后即在所有平台上启动;它的 workspace 视图报告 {"access": "none", "roots": []},settings 视图与程序一样是它的设置。
  • 它的限制约束每次调用(runtime.limits):燃料(指令数)、时间(调用自己的期限,且不超过 timeoutMs)和线性内存(memoryBytes,默认 256 MiB)。燃料或时间用尽的调用、要增长到超过限制的内存,以及任何陷阱(Rust 访客的 panic 就是一个陷阱),都会让该调用和访客的实例失败:访客像崩溃的程序一样重启。访客自己报告的错误只属于该调用。
  • **每个版本只加载一次。**访客第一次启动时编译模块,此时不实例化任何东西:元数据取自清单。重启使用同一个已编译模块的新实例(新的内存)。每个实例的元数据必须恰好是清单中的名字、只提供 plugin,否则它不会启动;它声明的其他模块(deps)不会被加载。
  • 所有平台共用一个文件,市场原样发布它。

用其他语言写的模块自己导出这个 ABI:memory、cordis_meta() -> i32、cordis_apply(len) -> i32、cordis_call(len) -> i32,以及可选的 cordis_dispose()(或同样功能、名为 kardia_* 的导出)。每个导出的输入是一条 len 字节的消息,read(ptr) 把它复制到模块的内存中;导出用 write(ptr, len) 设置结果(或错误,此时状态不为 0)。消息就是进程线路格式中各导出的 JSON(其他语言)。pykardia 可以把 Python 访客导出为 WASI 模块,它需要 WASI,因此不能在这里加载。

其他语言

用其他语言写的访客自己实现线路格式。每条消息都是一行上的一个 JSON 对象(最多 4 MiB):Agent 的消息写到访客的标准输入,访客的消息写到它的标准输出。

  1. Agent 先发送 {"export":"hello","input":{"protocol":"kardia-guest/2"}};访客回答 {"ready":"kardia-guest/2"}。
  2. 每个导出都带一个 id:{"export":"meta","id":1}、{"export":"apply","id":2,"input":{"config":{…},"imports":{}}}、{"export":"call","id":3,"input":{"key":"plugin","method":"tool","args":{…}}},最后是 {"export":"dispose","id":4}。
  3. 访客对一个导出最多回答一条 {"output":"<文本>","id":…}(结果的 JSON 文本,或错误消息),然后回答 {"done":0,"id":…};失败时回答 {"done":1,"id":…}。meta 的输出是 {"deps":[],"plugin":{"name":"my-plugin","inject":[],"provide":["plugin"]}}。
  4. 导出运行期间,访客可以用该导出的 id 调用宿主:{"call":"provide","key":"plugin","value":{}}(在 apply 中;其他任何键都会以错误被拒绝)、{"call":"view","key":"workspace"},Agent 回答 {"result":…} 或 {"error":"…"};以及 {"call":"log","level":2,"text":"…"}(0 为 error,3 为 debug),Agent 不回答它。
  5. Agent 随时可能发送 {"ping":n},访客应立即回答 {"pong":n};以及 {"cancel":id},此后该导出的结果会被丢弃。

检查

hanafubuki-agent plugins validate 目录 像安装那样读取插件,并像访客宿主运行它那样检查它的代码,但不安装也不启动任何东西:

  • 清单的问题(被略过的字段、超出范围的超时、未知的贡献),以及声明了却不存在的路径;
  • 它的角色略去的内容:角色文件中的键、Claude 代理文件中没有对应工具的工具名或它的 Claude model;
  • 运行时:对程序,检查协议、包里存在(且可执行)的程序,或 PATH 上的解释器,以及参数指定的包内文件;对模块,检查包里的文件是二进制 WebAssembly 模块,以及比 limits.timeoutMs 更长、会先被它截断的工具 timeout;
  • 注册时会被略过的内容:不是合法工具名的名字、过大或过深的 schema、不是插件种类的上下文种类、超过 7 个种类、不存在的提示槽位、没有观察者能收到的事件、重复声明的名字;
  • 不描述对象的 configSchema,以及其中不能成为选项的每个属性(configSchema)。

加上 --run 时,它接着把插件安装到一个临时主目录(它自己的配置和数据目录,事后删除),授予代码请求的权限,启动它的访客(程序在沙箱中启动;模块不需要沙箱,被编译并实例化),并报告访客的状态、启动时略过的内容、它的退出情况和标准错误:握手、元数据和 apply 都与在 Agent 中一样进行。有任何问题,或访客没有运行,它都会失败(退出码 1);--json 打印 {"validation": …, "started": …}。

开发

hanafubuki-agent plugins dev 目录 把插件安装为 <名字>@local 并启用,显示它的代码请求什么并授予(会先询问;--grant 不询问直接授予),然后打印访客的状态。之后它监视这个目录:一次改动(新的构建或导出)之后,文件安静片刻,它就重新安装插件,访客带着改动重新启动,授权和设置保持不变;请求更多权限的改动会再次询问。Ctrl+C 停止监视;插件仍保持安装(plugins remove <名字>@local 删除它)。

plugins dev 可以与同一数据目录下的终端界面或 exec 同时运行。每个 Agent 启动自己的插件进程;插件如有共享数据,需要自行协调写入。临时主目录能让开发中的插件不影响自己的配置和数据:开发和测试时使用同一个 HANAFUBUKI_AGENT_HOME。

hanafubuki-agent plugins link 目录 则是链接插件:它是 <名字>@local(或归入 --marketplace 名字),被启用,它的目录本身就是包。不复制进缓存,也没有内容哈希固定它,所以不需要像 plugins dev 那样让一个 Agent 一直运行:之后运行的 Agent(终端界面、exec、宿主)按目录当前的样子读取它。在内置的 plugins 行运行期间,这个 Agent 监视每个启用的已链接插件;某个链接目录改动之后文件安静 500 毫秒(读取文件不算改动,.git 中的改动也不算),它就重新加载已安装的插件:插件的 Skill、MCP 服务器、钩子和角色被重新读取,它的代码带着改动重新启动。

已链接的插件与已安装的插件受到完全相同的信任:它的代码在同样的授权和同样的沙箱配置下运行(它的目录只读),请求更多权限的改动会让它处于 blocked,直到 plugins grant;每次改动之后它的钩子都要重新信任,就像已安装插件的文件改变之后那样。plugins list 把它的来源显示为 linked 目录。它从不更新:plugins update 拒绝它,同一 ID 的 plugins add 在它被删除之前也会拒绝(link 同样拒绝一个已安装的 ID)。链接记录在数据目录的 plugins/linked.json 中,与已安装插件的 install.json 分开,所以不认识链接、会重写 install.json 的旧版 Agent 不会丢掉它(数据目录)。plugins remove <名字>@local 取消链接:它的记录和 [plugins] 条目被删除,目录保持原样(数据目录也保留,除非加 --purge-data)。链接不向目录写入任何东西,所以它的 commands/ 不会变成 Skill(安装才转换它们);目录不存在时,插件仍被列出并带有问题。

设置和权限

  • 权限由用户授予,插件自己永远不能授予:权限未被授予的程序处于 blocked 状态。plugins grant ID 授予清单请求的权限,/plugins 中插件页面的 Grant its permissions 也一样。请求更多权限的更新要等待新的授权。WebAssembly 模块什么也不请求,从不处于 blocked。
  • 沙箱的插件配置限制程序:它能读系统目录和它的包,只能写它的数据目录,按授予的权限访问工作区,只有被授予时才能访问网络;启动时环境为空,只有被授予的 env、PLUGIN_ROOT 和 PLUGIN_DATA。Linux 和 macOS 强制执行读取限制;Windows 无法禁止读取,所以那里不强制 workspace: "none"。没有沙箱的地方,访客不会启动。
  • 设置是 config.toml 中的 [plugins."ID"].settings:plugins settings ID --set '{"greeting": "Hi"}' 替换它们(按 configSchema 检查),--set null 删除它们,plugins settings ID 打印它们和 schema;/plugins 和设置中心也能编辑它们(configSchema)。它们是 apply 收到的配置,也是访客的 settings 视图;修改后访客会带着新设置重新启动。

configSchema

configSchema 会被强制执行。读取包时,它的 properties 中的每个属性被降低为一个选项,/plugins 中的选项表单(在插件上按 o)和设置中心 Plugins 标签页中该插件的分节显示这些选项,设置也按它们检查。它读取的关键字:

关键字变成
type: "boolean"开关
type: "integer"、"number"数字,给出 minimum 和 maximum 时在它们之间
type: "string"文本,给出 maxLength 时最多这么多个字符
字符串的 enum在它们之中选择,每个值以它自身为标签(带 type: "string" 或不带 type)
type: "array"、items: { "type": "string" }文本列表,最多 maxItems 项,每项最多为 items 的 maxLength
default选项的默认值,前提是它符合该选项
title选项的标签(没有时用它的键)
description选项的说明,取它的第一行

其他关键字在这里不做任何约束,与工具的 schema 一样;写入设置时仍会检查 required 和 additionalProperties: false。不符合其选项的 default 是包的一个问题,该选项没有默认值。没有关键字能让选项成为机密。不属于以上任何一种的属性(对象、非字符串的列表、多种类型的联合、非字符串或为空的 enum、minimum 大于 maximum)不是选项:它是包的一个问题(plugins validate 会列出它),它的值不经检查地到达访客。最多 64 个属性成为选项。

访客收到的设置按选项检查过:不符合其选项的值取选项的 default,模式没有给出默认值时则被省略,越界的整数或数字被截取到边界;每一项都是包的一个问题和日志中的一条警告,config.toml 保留原来写的内容。设置中省略的键仍然省略(访客自己的默认值生效),没有选项描述的键原样到达访客。写入是严格的:plugins settings --set、set_package_settings 和表单会带着原因拒绝不符合的设置,什么也不写。

所以插件只用 configSchema 声明它的设置,不需要设置页面:这些选项是 Agent 的设置目录中的设置,每个插件一节(plugins."ID".settings,在 Plugins 组中),键为 plugins."ID".settings.选项。设置中心把它们显示为行(/config plugins."ID".settings),宿主的设置页面像显示 Agent 自己的设置一样显示它们;写入它们(write_setting_values,键由 package_setting_key 拼出)时,把改动的键写在用户 config.toml 已有的设置之上,删除被重置的键,按 set_package_settings 的方式检查,并重启访客。一次写入只包含一个插件的设置,不含其他内容。值显示为由用户设置或为默认值;不会为它标出其他层。

出错时

发生了什么Agent 怎么做
清单或组件有误该字段或组件记为问题,其余照常加载;运行时无法运行的访客不会启动
访客在调用中 panicSDK 把它作为该调用的错误返回:给模型的工具错误、被略过的上下文段
调用超过期限杀死访客并重启它;本轮在没有这项贡献的情况下继续
访客退出、中止或内存耗尽它的贡献立即撤回,访客重启后重新注册
违反协议,或发送超过 4 MiB 的一行按崩溃处理:杀死并重启
模块触发陷阱、用尽燃料或时间,或内存超出限制该调用的错误;丢弃访客的实例,访客以新实例重启
一直失败分别在 2 秒、10 秒和 30 秒后重启;10 分钟内第四次失败后保持 failed,直到 plugins retry(或 /plugins 中的 Retry plugin);启动失败不会重启
安装后包里的文件被改动重新安装之前不会启动

Agent 的其余部分以及嵌入它的宿主都不受影响:程序是另一个进程,模块在 wasmtime 的沙箱中运行,陷阱或限制只会停止它自己的实例。plugins info ID 显示访客的状态和错误;/plugins 显示它的状态和问题,/warnings 显示它的问题,以及在重试之前它的失败。

发布

插件通过市场发布:一个目录或 git 仓库,其中的 marketplace.json 列出插件(.agents/plugins/marketplace.json,或 Claude Code 的 .claude-plugin/marketplace.json):

{
  "name": "my-marketplace",
  "plugins": [
    { "name": "my-plugin", "source": "./plugins/my-plugin/package" },
    {
      "name": "other-plugin",
      "source": {
        "source": "git-subdir",
        "url": "https://github.com/me/other-plugin",
        "path": "package",
        "ref": "v1.0.0"
      }
    }
  ]
}

来源可以是市场内的路径(./…)、{"source": "local", "path": …}、一个 git 仓库({"source": "url", "url": …})或其中的一个目录({"source": "git-subdir", "url": …, "path": …}),可选 ref 或 sha。用户添加市场并从中安装:

hanafubuki-agent plugins marketplace add me/my-marketplace
hanafubuki-agent plugins add my-plugin@my-marketplace
hanafubuki-agent plugins grant my-plugin@my-marketplace

带编译程序的插件把这个程序放在包内发布,为它支持的每个平台分别构建(WebAssembly 模块所有平台共用一个文件);没有任何签名,所以用户信任一个市场就像信任它的来源。plugins update 安装新版本,plugins marketplace upgrade 先获取 git 市场的改动。命令见命令行参考,配置见配置参考。

本页目录