写 Miyu 扩展用的两个小库:Python(python/miyu_ext.py)、Rust(rust/,crate miyu-ext)。两份的概念、名字一一对应。英文版:README.en.md。
扩展能做什么由协议定(核心仓库的 docs/reference/extensions.md),开发包不多给本事;它把每个扩展都要写一遍的那部分包起来:握手、一行一条的收发、几个调用同时来时照编号对着回、取消、配置推送、标准输入读到头就退、退出码 1 的规矩。
一个文件、只用标准库,Python 3.9 起。拷进你的包的 bin/,和程序放在一起:
hello/
├── package.toml
└── bin/
├── miyu-hello # 你的程序,第一行 #!/usr/bin/env python3
└── miyu_ext.py # 拷过来的开发包
#!/usr/bin/env python3
import os, sys
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from miyu_ext import Extension
ext = Extension("hello", "0.1.0")
@ext.tool("hello_greet", "Greet someone by name.",
{"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]},
access="read", display_name={"en": "Greet", "zh": "打招呼"}, subject="name")
def greet(args, call):
return f"{ext.config.get('hello.greeting', 'Hello')}, {args['name']}!"
if __name__ == "__main__":
ext.run()完整的例子在 python/examples/hello/,清单怎么写见核心仓库的 docs/authors/manifest.md。
三个平台一份文件:Linux、macOS 上照 #! 直接起(程序要有可执行权限);Windows 上核心照 #! 找解释器,python3 找的是 python(核心 0.8.0 起)。Miyu 不带 Python:请在包的说明里写上要装 Python 3.9 以上。
| 写什么 | 做什么 |
|---|---|
@ext.tool(name, description, schema, access=…) |
一件工具:函数收 (args, call),交回字、Reply 或者完整的回答。call.cancelled 是超时、人打断了没有 |
Reply(text, error, data, detail, sent, end_turn, state) |
完整的回答:data 只给 AI 在命令里用 miyu call 调到它的脚本(一行 JSON),detail 只给头画卡片,sent 是她发出去的图,end_turn 这一轮到此为止,state 是这个包在这个会话里的一份状态({} 清掉,None 当没写,出错的回答核心不收;照原样交) |
@ext.tool(…, paths=…, background_parameters=…, runs_commands=…) |
规格多的三格:哪几个参数是路径([{"parameter": "file_path", "write": True}])、只在会话能放后台时才给的参数、这件工具会跑命令。见下面「改文件、跑命令的工具」 |
@ext.tool(…, plugin=…, role=…, scope=…, result=…) |
规格另几格,不给的不写:场所插件(群、私聊里那个插件开着才给)、职能(read_file)、在 venues 之内再收窄的会话(any、local、local_main、local_main_attended、spawn)、data 的样子(一行字)。access 另有 install |
Reply(…).changed(path)、.read(path, lines)、.trashed(path, trash)、.todos(todos, done) |
回答里的 effects:改了、读了、删进回收站的文件,换上的待办。changed 可以带 before、after(content_hash(…))或 before_text、after_text 多核对一层 |
call.checked、call.channel、call.command_env() |
核心判过的真实路径(声明了 paths 的);miyu call 的通道(声明了 runs_commands 的)和设好通道的子进程环境 |
@ext.command(name) |
清单 [[slash]] 里的一条斜杠命令:交回给人看的那段话;函数跑着的时候 ext.language 是打命令的那个连接的语言 |
@ext.method(name, timeout_ms=None, later=False) |
后台页、界面块的按钮、头、别的包(照总线的名字或者包编号)调的方法:函数收 (params, caller);抛 MethodError(code, message) 回带码的错(码在错误的 data.code,data.reason 也是它);timeout_ms 是核心等多久(1000 到 600000,默认 30 秒);later=True 先不登记,等 ext.enable_methods([...])(比如模型下好了),ext.disable_methods([...]) 撤掉 |
@ext.on(method) |
别的反向调用、推送:user.append、search.query、widget.watch……;抛 MethodError(code, message) 回带码的错,核心读 data.reason(search.query 限额了回 limited) |
@ext.on_config、ext.config |
配置推送;握手时的配置在 ext.config |
@ext.ready |
握手、登记完以后在自己的线程里跑一次 |
ext.call(method, params) |
调核心的方法(blob.put、model.call……);被拒的抛 CoreError,reason 是原因码 |
ext.fatal(message) |
配置错、端口被占这类重启也没用的:写标准错误、退出码 1,核心不再重启 |
握手时核对协议的主版本,对不上照退出码 1 的规矩说清楚再退。能力照实写进清单:没声明的方法调了回 needs_approval。
测:不用起 Miyu,FakeCore 在进程里演核心:
from miyu_ext import FakeCore
core = FakeCore(ext, config={"hello.greeting": "Hi"})
assert core.call_tool("hello_greet", {"name": "Ann"})["blocks"][0]["text"] == "Hi, Ann!"
core.close()假核心照核心查规格的三格(写错的 bad_tool;会跑命令、approved 里没有 tools.commands 的 needs_approval,默认全批),被拒的在 core.refused。call_tool 照核心带 checked(声明的路径照 core.cwd、core.home 换成真实位置)和 channel(假的一份 core.channel,假核心不接),回答里的 effects 照核心查:收下的进 core.effects(路径是真实位置),丢掉的进 core.dropped,一条一个 {"tool", "kind", "why"}。
这个仓库自己的测试:python3 -m unittest discover -s python/tests。
crate miyu-ext:同步、只依赖 serde_json。处理函数里经 call.core()(命令、方法、别的处理函数直接收 &Core)调核心的方法、读配置,对应 Python 的 ext.call、ext.config。
use miyu_ext::{Extension, Reply, Tool};
use serde_json::{Value, json};
let mut ext = Extension::new("hello", "0.1.0");
ext.tool(
Tool::new("hello_greet", "Greet someone by name.")
.schema(json!({"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}))
.subject("name"),
|args, call| {
let config = call.core().config();
let greeting = config.get("hello.greeting").and_then(Value::as_str).unwrap_or("Hello");
Reply::text(format!("{greeting}, {}!", args["name"].as_str().unwrap_or("there")))
},
);
ext.run();完整的例子:rust/examples/hello.rs(cargo build --example hello,程序放进包的 bin/,叫 miyu-hello,Windows 上是 miyu-hello.exe)。FakeCore::start(ext, config) 同 Python 的假核心;测试:在 rust/ 下 cargo test。
两份的名字对照(下面一节用到的):
| Python | Rust |
|---|---|
@ext.tool(…, paths=[…], background_parameters=[…], runs_commands=True) |
Tool::paths(json!([…]))、.background_parameters(&[…])、.runs_commands(true) |
Reply(effects=[…]) |
Reply::effects(vec![…]) |
@ext.tool(…, plugin=…, role=…, scope=…, result=…) |
Tool::plugin(…)、.role(…)、.scope(…)、.result(…) |
Reply(state=…) |
Reply::state(json!(…)) |
@ext.on(method) 里 raise MethodError(code, message) |
ext.on_with(method, …) 回 Err(MethodError::new(code, message))(不回错的 ext.on 照旧) |
.changed(path)、.changed(path, before=…, after=…, before_text=…, after_text=…) |
.changed(path)、.changed_with(path, Change { before, after, before_text, after_text }) |
.read(path, lines=(1, 20))、.trashed(path, trash)、.todos(todos, done=None) |
.read(path, Some([1, 20]))、.trashed(path, trash)、.todos(todos, None) |
content_hash(data) |
content_hash(&data) |
call.persona(这一轮的人格编号,没有是 None)、call.read_only(核心 TC-1;调用没带权限的是 None:不知道,照最严的算,别当成能写) |
call.persona()、call.read_only()(Option<bool>) |
call.pictures(放图的目录,只给本机的会话,没有是 None)、call.permission(整格 {"level", "read_only"},没有是 None) |
call.pictures()、call.permission_level()(都是 Option<&str>) |
call.checked(列表)、call.channel(字典或 None) |
call.checked()(Vec<&str>)、call.channel()(Option<Channel>) |
call.command_env():整份环境(os.environ 的副本加上通道) |
call.command_env():只是要加的几项,给 Command::envs |
FakeCore(ext, approved=[…], cwd=…, home=…)、core.channel = … |
FakeCore::start_approved(ext, config, &[…])、set_cwd、set_home、set_channel |
core.refused、core.effects、core.dropped |
core.refused()、core.effects()、core.dropped()、clear_effects() |
@ext.method(name, timeout_ms=…, later=True)、raise MethodError(code, message) |
ext.method_with(Method::new(name).timeout_ms(…).later(), …)、Err(MethodError::new(code, message))(只写名字、回 Err(String) 的照旧) |
ext.enable_methods([…])、ext.disable_methods([…]) |
core.enable_methods(&[…])、core.disable_methods(&[…]) |
核心 XG-1 上、下(2490fb77、514bdc40)起。协议在核心仓库的 docs/reference/extensions.md(provide、tool.call 的「效果」「跑命令」),怎么写见 docs/authors/extensions.md 的「改文件的工具」「跑命令的工具」。
改文件的(编辑器、格式化、改名这类):想和内置的 edit 一样有差异、增删行数,AI 读过的文件被你改了不用重读。
- 规格写
paths,access写write:核心照它做权限检查(工作区外的写先问人,人点头以前你收不到调用)。 - 只写
call.checked里的位置:那是检查判过的真实位置,照参数里路径的先后。别自己拿参数里的路径去写(检查以后路径上的链接可能被换过)。 - 回答里报
changed(路径):只说哪个文件,内容核心自己读(改前在发调用以前、改后在你回答以后)。前后一样的、路径不在checked里的、只判了读却说改了删了的、不认识的种类、写法不对的,核心丢掉那一条,结果照常。
@ext.tool("replace_text", "Replace one exact piece of text in a file.", SCHEMA, access="write",
paths=[{"parameter": "file_path", "write": True}])
def replace(args, call):
path = call.checked[0]
... # 改 path
return Reply(text="Replaced.").changed(path)完整的例子:python/examples/replace/、rust/examples/replace.rs,测试照假核心跑它们。
跑命令的(换掉内置 shell、在容器里跑):清单的能力加 tools.commands,规格写 runs_commands=True。会话里有脚本能调的工具时,call.channel 是这次调用的通道;起命令时用 call.command_env() 当环境(设好 MIYU_CALL_SOCK、MIYU_CALL_TOKEN,bin 放 PATH 最前),命令里的 miyu call 就以这个会话的身份调工具。命令要是你的扩展进程起的(子孙进程),等它跑完再回答:一回答通道就关了。
subprocess.run(command, shell=True, cwd=call.cwd, env=call.command_env())std::process::Command::new("sh").args(["-c", command]).envs(call.command_env()).status()现在是 v0.1.0。发版打 vX.Y.Z 标签,python/miyu_ext.py 的 __version__、rust/Cargo.toml 的版本跟着改;两份在三个平台上的测试(.github/workflows/ci.yml)过了才打。Rust 照标签依赖:
[dependencies]
miyu-ext = { git = "https://github.com/miyu-agent/miyu-sdk", tag = "v0.1.0" }Apache-2.0,见 LICENSE(2026-10-26 起,以前是 MIT)。照着写的扩展用什么许可证都行:它们只经协议和 Miyu 说话,是独立的作品,Miyu 核心的 AGPL 管不到它们。