插件权限
插件能做什么、Agentty 如何加以限制，以及写出配得上所申请权限的插件的规则。
插件以普通程序的身份运行，拥有你的文件与网络访问权限。Agentty 不会把它关进沙箱，而是把发送提示词、向终端输入、读取对话这些关键能力要求事先声明，并在安装前展示给你。
四种权限#
| 权限 | 允许的事 | 为什么重要 |
|---|---|---|
prompt.inject | 向智能体发送提示词 | 提示词通常会先在**发送到…**对话框中显示 |
terminal.write | 向已打开的窗格输入 | 文本可以不经对话框直接到达窗格 |
session.read | 读取 AI 对话 | 会话记录包含你讨论过的一切 |
workspace.read | 列出工作区，查看上下文中的文件夹与标题字段 | 会暴露你在哪里工作 |
没有相应权限的调用会以 -32001 失败。插件页面在安装前后的卡片上都会显示已声明的权限。
没有权限时插件能看到什么#
上下文会按声明的权限过滤。没有 workspace.read 就去掉文件夹与标题字段，没有 session.read 就去掉会话 id。剩下的是 id、kind、tool、status、running 和语言：足以知道哪个窗格处于焦点、是否在忙，但不知道你在哪里、在做什么。
json
{
"pane": { "id": 12, "kind": "claude", "tool": "claude", "status": "working", "running": true },
"language": "zh"
}对话框就是边界#
以 target: "ask" 调用 prompt.inject 会打开发送到…：你看到文本，选择智能体和目的地，在点击发送之前什么都不会发生。其他 target 会跳过这个对话框，所以依据外部输入行动的插件应始终使用 ask。
injectPrompt 永远不会替你在终端按回车——文本被输入后交由你决定。
链接被视为不可信#
agentty:// 链接可能来自任何地方，包括网页。在链接到达插件后的一分钟内，Agentty 会：
- 把该插件的
injectPrompt一律转到发送到…，无论它指定了什么 target； - 直接拒绝
sendToTerminal。
在链接打开的面板里点击也不会解除该限制。一次链接不会变成对终端的输入。
Important
如果你的插件处理链接，请校验每一个参数。例如 Cosmica 插件只打开位于 Cosmica 笔记文件夹内的 .md 文件，文件夹之外的路径一律拒绝。
编写规则#
- 只申请你会用到的权限。 每一项都会展示给用户，用不到的权限只会白白消耗信任。
- 绝不读取或发送凭据。 如果要读取其他应用的配置，只取你需要的字段——Cosmica 插件只读
notes.path和一个本地端口。 - 数据放在
AGENTTY_PLUGIN_DATA里。 创建其他应用会读取的文件时要小心，不要未经要求覆盖用户的文件。 - 只与
127.0.0.1通信，除非用户自己配置了别的端点。 - 输入前检查
pane.status。 不要打断working、permission或question。 - 校验一切来自外部的东西 —— 链接、文件、服务器响应，都不要直接当真。
速率限制与失控保护#
无论有意还是无意，Agentty 都会保护自己不被行为异常的插件拖垮。
| 限制 | 行为 |
|---|---|
| 面板重绘 | 最短间隔 50ms |
| 通知 | 最短间隔 700ms；超出的会被丢弃但正常应答 |
| 消息 | 每秒超过 240 条即视为失控并停止插件 |
| UI 树 | 2,000 个元素、12 层深度、每段文本 20,000 字符 |
| 行长度 | stdout 与 stderr 各 16MB |
安装别人的插件之前#
- 读卡片上的权限。一个笔记插件若要
terminal.write，应当说明理由。 - 优先选择源码可读的插件，卡片上的
links通常指向仓库。 - 安装后打开日志，可以快速看出它实际在做什么。
- 禁用立即生效，卸载会移除插件；其数据文件夹会保留到你自己删除为止。