发布插件

通过 Git 仓库或文件夹分享插件、为它编号版本，并在 Agentty 演进时保持可用。

没有中央注册表。插件就是一个带清单的文件夹，所以发布意味着把这个文件夹放到别人能拿到的地方。

用 Git 仓库分享#

把 agentty-plugin.json 放在仓库根目录。用户在自己构建 → 从 Git 安装中粘贴 https:// 地址。

text

your-plugin/
├── agentty-plugin.json
├── main.mjs
├── agentty-plugin.mjs     随包携带的 SDK
├── README.md
└── LICENSE

Important

把运行所需的一切都打包进去，包括 SDK 和任何 node_modules。 Agentty 不会执行 npm install，它直接启动你的入口点。缺少依赖的插件会在用户机器上因找不到模块而失败，只在日志里留下错误。

尽量写无依赖的代码。SDK 本身没有依赖，正是出于这个原因。

用文件夹分享#

从文件夹安装… 会把文件夹复制到 ~/.agentty/plugins/。解压后得到正确名称文件夹的 zip 也一样可用——文件夹名必须与清单中的 id 相同。

版本#

version 采用 major.minor.patch。Agentty 会把它显示在卡片上，并在内置插件随新版本一起更新时据此提示更新。

从 Git 或文件夹安装的插件由用户重新安装来更新。请在 README 里说明你期望的方式，并让清单的 links 指向可以查看变更记录的页面。

apiVersion 表示你依据哪个插件 API 版本编写，目前是 1。请填写你实际测试过的版本，而不是盲目跟随最新数字。

有用的 README#

商店卡片会显示 description 和最多六个 links，其余信息都应写进 README：

它与什么集成，需要先装好什么才能工作
申请了哪些权限，以及为什么 —— 这是你能写下的最有用的一行
它保存什么、保存在哪里
遇到问题去哪里反馈

如果你的插件与其他应用集成，请声明出来，好让卡片显示检测结果：

json

{
  "requires": {
    "name": "Cosmica",
    "url": "https://www.cosmica.ink/",
    "note": "Needed to read and write notes"
  },
  "detect": ["~/Applications/Cosmica.app", "/Applications/Cosmica.app"]
}

当 detect 命中时，卡片会对该用户标记为推荐。

发布前的测试#

链接开发文件夹… 直接运行你的工作副本，改完按重启即可，无需重新安装。
卡片上的日志显示 stderr、协议错误、崩溃和退出码。
用测试程序直接驱动它：它只是一个从 stdin 读取 JSON 行、向 stdout 写出的普通程序，测试可以发送 initialize 和你想验证的通知，再断言返回内容。
用你实际声明的权限来测试。没有权限的调用会以 -32001 失败，而开发时权限更多很容易忽略这一点。
两种主题和长面板都要看一遍。面板宽 360px 且可滚动。

保持可用#

处理 shutdown 并退出；1.5 秒后仍存活会被强制终止。
除协议消息外不要写 stdout，请用 plugin.log(...) 或 console.error(...)。
把上下文的每个字段都当作可选。里面有什么由权限和窗口状态决定。
后续版本可能出现新的 UI 元素和上下文字段。遇到不认识的就忽略，不要报错失败。

内置插件#

随 Agentty 一起发布的插件会跟着应用更新，并在其集成的应用已安装时在卡片上显示推荐。如果你认为自己的插件适合成为其中之一，请在 Agentty 发布仓库开一个 issue，说明它做什么、为谁而做。