如何为 Agent of Empires 编写自定义插件aoe-plugin 清单与 Worker 开发完整教程【免费下载链接】agent-of-empiresManage multiple Claude Code, OpenCode agents from either TUI or Web for easy access on mobile. Also supports Mistral Vibe, Codex CLI, Gemini CLI, Pi.dev, Copilot CLI, Factory Droid Coding.项目地址: https://gitcode.com/gh_mirrors/ag/agent-of-empiresAgent of Empires简称 AoE是一款管理 Claude Code、OpenCode、Codex CLI 等多个 AI 编程 Agent 的会话管理器。本文是面向新手的 Agent of Empires 自定义插件开发完整教程带你从零掌握aoe-plugin.toml插件清单的每个字段、能力capabilities授权模型以及用任意语言编写与宿主通信的 Worker 程序最终本地安装并发布你的第一个插件。什么是 Agent of Empires 插件AoE 的设计哲学是核心保持精简能力交给插件。会话、tmux、worktree 是内核其余可选功能都以插件形式按需启停。一个插件本质上就是一个目录里面包含两样东西aoe-plugin.toml清单插件的合同声明身份、贡献项命令、设置、UI 槽位和运行时需求Worker可选一个可执行文件宿主aoe serve守护进程会启动它通过 stdio 上的换行分隔 JSON-RPC 2.0通信。Worker 可以用 Python、Node、Rust 等任何语言编写宿主不链接你的代码。 官方文档入口docs/development/writing-plugins.md、docs/plugin-api.md三步搭建插件骨架不需要手写任何文件。官方提供 cookiecutter 模板一条命令生成完整的插件工程清单、Worker、测试、CI支持 Python / Node / Rust 三种语言cookiecutter gh:agent-of-empires/plugin-template生成的初始插件开箱即用能构建、测试通过、并且已经响应一个status命令。后续章节逐一解释模板生成了什么。aoe-plugin.toml 清单字段完全指南一份最小可用的清单长这样id dev.example.my-plugin name My Plugin version 0.1.0 api_version 13 aoe_version 1.11.0, 2.0.0 description 插件功能的简短描述。 capabilities [runtime.worker] [[commands]] id status title My Plugin: status清单解析是严格模式未知字段、非法 id、不支持的 API 版本都会被拒绝。清单类型的唯一事实来源是aoe-plugin-api独立 crate当前 schema 版本见 aoe-plugin-api/src/lib.rs#L18。身份与版本id 命名规则id必须是点分隔的小写 ASCII 标识符如dev.example.review-helper整段不超过 64 字节它同时命名空间化配置、事件和动作名aoe.*与agent-of-empires.*是保留命名空间社区插件不能冒用api_version指向清单 schema 版本当前为13aoe_version声明你实测过的宿主版本范围——宿主会拒绝安装不兼容的插件。capabilities 权限系统最小授权原则Worker 运行前必须逐项声明所需能力安装时一次性向用户申请并锁定到清单哈希——任何扩大权限的更新都必须重新审批。常用能力包括能力授权内容runtime.worker运行任何插件代码的前提必选net出站网络访问session.read/session.write读取 / 变更所附会话fs.read/fs.write插件目录外的文件读写notifications桌面 / TUI 通知acp.capabilities.read发现可用的 Agent 及其模型目录⚠️ 只声明真正用到的能力静态贡献命令、键位、主题、UI、状态栏不需要任何 capability。注意能力检查是 API 边界而非操作系统沙箱详见 docs/development/internals/plugin-system.md。命令、键位与设置插件可以贡献调色板/CLI 命令宿主会加命名空间为plugin.id.command-id、快捷键如CtrlShiftG以及在 TUI 和 Web 设置页渲染的声明式设置项文本、开关、整数、下拉、cron 表达式、对象列表等[[settings]] key refresh_secs label 刷新间隔秒 type integer default 120 min 0 max 86400用户填写的值保存在config.toml的[plugins.id.settings]下Worker 通过config.get宿主 RPC 读取。UI 槽位在宿主界面中占据一席通过[[ui]]声明渲染槽位后Worker 可用ui.state.set推送状态。常用槽位pane可停靠的工具窗口面板支持标题、块列表行、卡片、柱状图、迷你折线图等card/status-bar仪表盘概览卡片与状态栏分段row-badge/detail-badge会话行与会话详情页的徽章composer-actionACP 输入框旁的自定义按钮。Worker 开发JSON-RPC 通信协议宿主启动 Worker 后按行在 stdin 写入 JSON-RPC 请求、从 stdout 逐行读取响应stdin 到达 EOF 时 Worker 退出。一次最简交互{jsonrpc: 2.0, id: 1, method: my-plugin.status, params: {}} {jsonrpc: 2.0, id: 1, result: {ok: true, message: running}}协议要点新手最常踩的坑宿主把命令 id 映射为全命名空间方法plugin.id.command-id所以dev.example.my-plugin的 Worker 实际收到的是plugin.dev.example.my-plugin.status——按尾段分发让两种形式都能命中未知方法返回 code 为-32601的 JSON-RPC 错误永远不要响应没有id的消息那是通知。安装前可手工驱动 Worker 验证协议echo {jsonrpc:2.0,id:1,method:my-plugin.status,params:{}} | 你的worker可执行文件构建与启动runtime 配置入口点必须是插件相对路径绝不在守护进程的PATH上解析。构建产物统一放入.aoe-build/——宿主计算完整性哈希时会排除该目录所以 venv、node_modules都不会破坏校验[runtime] kind command command [.aoe-build/venv/bin/my-plugin-worker] [[runtime.build]] command [python3, -m, venv, .aoe-build/venv] platforms [linux, macos]构建步骤在安装和更新时各执行一次运行在用户的交互式 shell 中PATH可靠。编译型插件也可改用kind release-binary直接分发预编译产物。本地安装与测试清单aoe plugin install ./my-plugin # 执行构建步骤弹出权限确认 aoe plugin update my-plugin # 重新构建变更的授权需重新审批 aoe plugin uninstall my-plugin安装完成后在 TUI 命令面板的 Manage plugins、CLI 或 Web 设置页都可以管理插件。建议保留模板自带的worker 契约测试拉起 Worker → 发请求 → 断言响应——它是协议层最便宜的防线。发布进入 featured 精选索引打一个vX.Y.Z标签推送即可生成 GitHub Release用户通过aoe plugin install gh:your-org/my-plugin安装。若想进入 featured 精选列表并可申请保留命名空间需向主仓库提交 PR把你发布的源码树哈希加入 plugins/featured.toml。哈希用aoe plugin hash 插件目录在干净的 LF 行尾检出上生成。作为参考仓库内置的 Web 仪表盘插件清单 plugins/aoe-web/aoe-plugin.toml 展示了最精简的清单形态。延伸阅读与模块路径编写插件指南docs/development/writing-plugins.md插件 API 逐字段参考docs/plugin-api.md插件系统架构与安全模型docs/development/internals/plugin-system.md用户视角的插件管理docs/plugins.md清单 schema 类型定义aoe-plugin-api/src/lib.rs精选索引plugins/featured.toml按清单 → Worker → 构建 → 安装 → 发布这条主线走下来你的第一个 Agent of Empires 插件就可以跑起来了。【免费下载链接】agent-of-empiresManage multiple Claude Code, OpenCode agents from either TUI or Web for easy access on mobile. Also supports Mistral Vibe, Codex CLI, Gemini CLI, Pi.dev, Copilot CLI, Factory Droid Coding.项目地址: https://gitcode.com/gh_mirrors/ag/agent-of-empires创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考