插件权限
五项权限、没有权限时插件能看到什么,以及为什么 WebAssembly 插件和一个程序完全是两回事。
插件能做什么,要事先写在 agentty-plugin.json 里,并在用户安装前展示给他们。没有对应权限的调用会以错误 -32001 失败。
五项权限#
| 权限 | 展示给用户的说法 | 方法 |
|---|---|---|
net.request | 向你给出的地址发送 HTTP 请求 | net/fetch |
prompt.inject | 启动智能体会话并发送提示词 | prompt/inject |
terminal.write | 向终端输入并回车 | terminal/send |
session.read | 读取 Agentty 中已打开 AI 会话的对话 | session/get |
workspace.read | 查看打开的工作区、标签页、文件夹和智能体状态 | workspace/list、host/revealPath、pane/status |
mcp.tools | 通过它提供的工具回应 Agentty 中运行的 AI 智能体 (MCP) | tools/call |
terminal.proxy | 让新开的终端经过插件的代理(需要 API 版本 6) | terminal/setProxy |
插件自己的存储和它的面板不需要权限。storage/get、storage/set 和 storage/keys 是它自己的文件夹(<数据目录>/plugin-data/<id>/storage.json,以 0600 创建),最多 64 个键、共 1 MB。WebAssembly 插件没有自己的文件,所以这是它记住任何东西的唯一办法。
net.request 与 session.read 或 workspace.read 同时出现,意味着这个插件可以读你的工作并把它送到别处。同时申请两者的插件,应当在描述里明确说清楚为什么需要;没说清楚的,市场会拒绝。
两种插件#
这是最重要的区分,插件页面的关于 → 运行方式会标明。
wasm | Agentty 自己运行这个模块。它没有文件、没有套接字、没有环境变量、没有进程——不管怎么写,都只能碰到协议允许的东西。 |
node、python、executable | 一个以你的身份运行的程序,拥有和你启动的任何东西一样的文件与网络访问权限。上面那些权限管的是它经由 Agentty 做的事;程序本身没人管。 |
所以那份权限清单在两种情况下含义不同。对 WebAssembly 插件来说,它就是这个插件能做的全部。对程序来说,它只是这个插件通过 Agentty 能做的全部——文件它本来就能自己打开。
程序型插件,只在你信任作者时才安装。插件市场只收录源码公开的 WebAssembly 模块,原因正在于此。
没有权限时插件能看到什么#
上下文会按插件声明的权限过滤。没有 workspace.read,文件夹和标题字段会被去掉;没有 session.read,会话 id 会被去掉。剩下的是 id、kind、tool、status、running 和语言——足以知道哪个窗格处于聚焦、是否正忙,但不知道你在哪里工作、在做什么。
{
"pane": { "id": 12, "kind": "claude", "tool": "claude", "status": "working", "running": true },
"language": "zh"
}提示词去了哪里,又是谁选的#
对话框并不是边界,这一点值得说明白。prompt.inject 允许插件不征求同意地开启自己的智能体会话并发送文本。这是有意为之:AgentOS 的全部工作就是通过自己开启的会话推进步骤,隔着一个对话框是做不到的。
插件也可以把选择权交给用户。用 target: "ask" 调用会打开发送到…:用户看到文本,挑好智能体和去处,在按下发送之前什么都不会发生。其余所有 target —— newTab、newWorkspace、active、pane、workspace —— 都会跳过它。所以凡是依据外部输入行事的插件都应该始终用 ask。由链接触发的插件则受到限制:newTab 和 newWorkspace 配上 Claude Code 或 Codex(或不指定智能体,默认为 Claude Code)会直接打开,但不按回车;其余所有情况走发送到…,也不按回车。
这两个调用的分水岭是回车,而这个差别就是 terminal.write 的全部:
injectPrompt不会替你在终端里按回车。它把文本输进去,剩下的交给用户。sendToTerminal是另一回事,它会按回车 —— 在 shell 里也一样,那就是执行命令。
链接不被信任#
agentty:// 链接可能来自任何地方,包括网页。一旦有链接到达某个插件,在这个插件运行期间:
prompt/inject的 target 若是newTab或newWorkspace且搭配 Claude Code 或 Codex(或不指定智能体,默认为 Claude Code),该新智能体标签或工作区会直接打开,文本输到提示词里但不按回车。这样直接打开的标签每隔几秒只有一个:连续打开链接的网页也只能得到一个,其余在发送到…中排队。其余所有情况——已打开的终端(active、pane、workspace);split;own;shell/终端智能体;或未指定 target —— 走发送到…,也不按回车。terminal/send在不按回车的情况下输入文本(submit被强制为 false),而且只输入到 Claude Code 或 Codex 终端,不输入到 shell——留在 shell 命令行上的文字会和用户接下来输入的命令一起执行。仅输入不会执行任何东西:文本去掉控制字符后粘贴,换行符用 bracketed paste 包裹或换成空格。- 当回车权留给用户时,两个调用都会用
submitted: false作答。
浏览器继续被拒绝(-32001)。host/openUrl 仍然是被链接触发的插件唯一还能伸到 Agentty 之外的东西,一次一个地址。在链接打开的那个面板里点击,并不等于同意运行插件输入的东西,等待也一样。能解除它的只有重启插件。
Agentty 分不出地址的好坏,所以这一段归你负责:把链接交给你的东西当作陌生人给的文本,绝不不加检查就打开它给出的地址。
如果你的插件处理链接,请校验每一个参数。Cosmica 插件只打开 Cosmica 笔记文件夹里的 .md 文件,文件夹之外的路径一律拒绝。
net.request 允许做什么#
net/fetch 是插件接触网络的唯一途径,Agentty 给它划了边界:
| 方法 | 在 http、https 上的 GET、HEAD、POST、PUT、PATCH、DELETE、OPTIONS |
| 请求头 | 最多 32 个,不得包含 Host、Content-Length、Transfer-Encoding、Connection、Upgrade、Expect,也不得含换行 |
| 请求体 | 1 MB |
| 响应 | 保留 4 MB(truncated 会说明是否还有更多) |
| 超时 | 默认 15 秒,最多 60 秒 |
| 并发 | 每个插件 4 个 |
请求里不会带上任何属于你的东西——没有 cookie,没有已保存的凭据,只有插件自己放进去的内容。每次调用都会以隐去 URL 的形式写进插件日志。
最多跟随 3 次重定向,每一个新地址都要过和原请求相同的检查:必须是 http 或 https,且不能是链路本地或元数据地址——否则服务器只要回一个 302 Location: http://169.254.169.254/… 就能绕过去。Authorization 和 Cookie 请求头不会被带到另一个主机;被重定向的 POST、PUT、PATCH 会变成不带请求体的 GET,除非响应是 307 或 308。
限流与失控保护#
无论是否出于本意,Agentty 都会保护自己不被行为异常的插件拖垮。
| 限制 | 结果 |
|---|---|
| 面板重绘 | 每 50 ms 最多一次 |
| 通知 | 每 700 ms 最多一次;多出来的照常响应后丢弃。消息在 300 字符处截断 |
| 打开 URL | 每 700 ms 最多一次;host/openUrl 和通知一样被限流 |
| 消息 | 每秒超过 240 条即视为失控并停止插件 |
| UI 树 | 2,000 个元素、12 层深、每个字符串 20,000 字符。choice 的选项和列表项的按钮也各自计入元素 |
| 行长度 | stdout 和 stderr 各 16 MB |
| WebAssembly | 模块 64 MB、内存 64 MB、每条消息 16 MB、处理一条消息期间 256 条消息 —— send 与 log 合计 |
AI 智能体的工具 (MCP)#
插件可以向 Agentty 中运行的 AI 智能体 (Claude Code、Codex) 提供工具。通过 Agentty 自带的 MCP 服务器(agentty-plugins MCP 服务器)工作。当至少一个启用的插件声明了 mcp.tools 权限并在 contributes.tools 下列出工具时,智能体会自动收到该服务器。
插件必须同时声明权限和工具。只有权限或只有工具是清单错误。mcp.tools 权限需要 API 版本 5。
不声明 mcp.tools 的插件不支持 MCP:智能体看不到它。它的插件页面显示"MCP 连接 — 不支持"。
声明了 mcp.tools 的插件的权限选项卡上有**"允许 MCP 连接"**开关,默认为 ON。用户关闭它时,智能体将无法再列出或调用该插件的工具。
每个插件最多 32 个工具。工具 name 是 1–48 个字符,仅限小写字母、数字、下划线,以字母开头。每个调用在 120 秒后超时。参数和发送给智能体的文本有大小限制——见协议详情。
插件的应答进入智能体上下文,应如同其他工具输出一样处理。每次调用都写进日志("日志"选项卡),显示调用它的面板。
终端代理#
插件可以请求把你打开的终端和 AI 会话经过它在本机(127.0.0.1)上运行的代理,这样插件就能看到它们连接了哪些主机、发送了多少数据。用户看到的权限名称是 让新终端经过它的代理。已经打开的终端不会改变;停止插件即结束代理。地址由 Agentty 根据端口生成,插件无法把终端指向别处,同一时间也只有一个插件能占用代理。
写一个配得上这些权限的插件#
- 只申请你用到的权限。 每一项都会展示给用户,用不到的只会削弱信任。
- 不要读取或发送凭据。 如果要读别的应用的配置,只取你需要的字段——Cosmica 插件只读
notes.path和一个端口。 - 数据放在插件自己的存储里。 创建别的应用会读的文件时要小心,不要擅自覆盖用户的文件。
- 只和
127.0.0.1通信,除非用户另行配置。 - 输入前先看
pane.status。 不要打断working、permission或question。 - 校验一切来自外部的东西——链接、文件、服务器响应。
安装别人的插件之前#
- 读卡片上的权限。一个笔记插件要
terminal.write,应该有个说得通的理由。 - 看一眼运行方式。WebAssembly 模块要你付出的信任,比一个程序小得多。
- 优先选源码能读到的插件;卡片上的链接通常指向仓库。
- 装完后看日志,能知道插件实际在做什么。
- 停用立刻生效,卸载会移除插件。数据文件夹会留到你自己删除为止。