# 权限

> 卡片的十三项权限——每项的风险、用户在安装时看到的原话、它解锁的能力，以及应用强制执行的范围规则。

Source: https://docs.neurosquad.ai/zh/card-sdk/permissions

没有任何权限的卡片可以在自己的方框里绘制、使用[存储](https://docs.neurosquad.ai/zh/card-sdk/api/storage-settings)、读取自己的设置、设置自己的标题栏，
但不能和任何人交换任何东西。其余一切都是你在[清单文件](https://docs.neurosquad.ai/zh/card-sdk/manifest#permissions)中声明、由用户授予的权限。

授权的工作方式：

- **按卡片包授予，每次请求都检查。** 用户把权限授予你的卡片包（它在所有画布上的每一份副本）。
应用会在每一次调用时检查授权——检查发生在应用里，而不是在 SDK 或你的卡片里。
- **必需权限在安装时要么全给、要么不装。** 安装对话框把它们按高风险在前的顺序列出。拒绝就意味着不安装。
- **可选权限在运行时申请**（`"optional": true`）。在卡片显示在屏幕上时调用
[`card.permissions.request()`](https://docs.neurosquad.ai/zh/card-sdk/api/environment#permissions)；应用会用它自己覆盖整个窗口的对话框询问，用户可以拒绝。
- **有些权限包含其他权限。** `fs.write` 包含 `fs.read`；`agents.output`、`agents.prompt` 和 `terminals.write` 包含 `agents.read`。
- **用户可以随时撤销**任何权限（在 **Settings → Custom cards** 中）。卡片的页面会以缩小后的授权重新加载，
并收到 `permissions.changed` 事件；代码要做好防御。
- **新增权限或网络主机的更新**需要用户同意后才会生效。你去掉的权限会被撤销。
- **箭头就是对数据的同意。** 涉及另一张卡片、智能体或终端的权限，只对通过[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)与你的卡片相连的卡片生效——
方向不限，除非另有说明。

缺少权限时调用会以 `PERMISSION_DENIED` 失败（`error.permission` 会给出缺的是哪一项）。

## 一览

| 权限 | 风险 | 解锁 |
| --- | --- | --- |
| `agents.read` | 低 | `agents.list/get`、状态/轮次/变更事件、智能体的 `status` 端口 |
| `agents.output` | 高 | 读取**相连**智能体和终端的屏幕与回复 |
| `agents.prompt` | 高 | 向**相连**的 AI 智能体发送提示词 |
| `terminals.write` | 高 | 在**相连**的终端中运行命令 |
| `cards.connected` | 中 | 读取和修改**相连**的笔记、待办清单、任务看板、便签 |
| `network` + 主机 | 中 | 对列出的主机使用 `net.fetch` |
| `network.local` | 高 | 对本机上的服务器使用 `net.fetch` |
| `fs.read` | 高 | 读取工作区文件夹中的文件 |
| `fs.write` | 高 | 写入工作区文件夹中的文件（包含 `fs.read`） |
| `clipboard.write` | 低 | 把文本复制到剪贴板 |
| `canvas.spawn` | 低 | 在自己旁边添加最多 4 张卡片 |
| `background` | 低 | 没人看时也保持运行 |
| `usage.read` | 低 | 工作区的令牌用量和费用 |

## 逐项说明

### `agents.read` — low

**用户看到：** *See the agents on this canvas.*（查看此画布上的智能体）它们的名称、运行的工具，以及正在工作、等待你还是已完成。

**解锁：** [`card.agents.list()` / `get()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents)、事件 `agents.status`、`agents.turn`、`agents.changed`，
以及内置智能体的 `status` 输出端口。

**范围：** 卡片所在工作区的 AI 智能体和终端。其他卡片不是智能体，不会被列出。

### `agents.output` — high

**用户看到：** *Read what agents and terminals connected to it print.*（读取与其相连的智能体和终端的输出）
用箭头与它相连的智能体和终端卡片屏幕上的所有内容，包括其中显示的任何机密信息。

**解锁：** `card.agents.readScreen()`、`card.agents.lastReply()`、用 `card.agents.onOutput()` 获取实时输出，
以及智能体的 `reply` 和终端的 `exit` 输出端口。

**范围：** 仅限用箭头相连的智能体和终端。包含 `agents.read`。

### `agents.prompt` — high

**用户看到：** *Give instructions to agents connected to it.*（向与其相连的智能体下达指令）
向用箭头与它相连的 AI 智能体输入并发送提示词。智能体可以编辑文件和运行命令，所以此卡片可以让它做智能体能做的任何事。

**解锁：** [`card.agents.prompt()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#prompting) 和智能体的 `prompt` 输入端口。

**范围：** 用箭头相连的 **AI** 智能体（不含终端）。提示词会经过提示词队列和工作区[预算](https://docs.neurosquad.ai/zh/cards/budget)，
每张卡片每分钟最多 6 条（该方法和智能体的 `prompt` 端口合并计数）；每条都会显示在箭头上并记入箭头日志。
发给[危险模式](https://docs.neurosquad.ai/zh/agents/dangerous-mode)下智能体的每条提示词，都要等用户在卡片上确认。包含 `agents.read`。

### `terminals.write` — high

**用户看到：** *Run commands in terminals connected to it.*（在与其相连的终端中运行命令）
在用箭头与它相连的终端卡片中输入并运行命令——任何你自己能运行的命令。

**解锁：** [`card.terminals.run()` 和 `write()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#terminals)，以及终端的 `command` 输入端口。

**范围：** 用箭头相连的终端卡片（bash、PowerShell、cmd）。每张卡片每分钟最多 30 条命令，`run` 和终端的 `command` 端口合并计数；
`write` 每分钟最多 60 次。每条命令都会显示在箭头上。包含 `agents.read`。

### `cards.connected` — medium

**用户看到：** *Read and change cards connected to it.*（读取和修改与其相连的卡片）用箭头与它相连的笔记、清单、任务看板和便签。

**解锁：** 笔记、待办清单、任务看板和便签的[内置卡片端口](https://docs.neurosquad.ai/zh/card-sdk/api/ports#built-in-cards)——向笔记追加内容、添加任务、读取清单。

**范围：** 用箭头相连的这四类卡片。

### `network` — medium, needs `hosts`

**用户看到：** *Connect to `api.github.com`, `*.example.com`.*（连接到这些主机）只与这些互联网地址收发数据。
卡片能看到的任何内容都可能被发送到那里。

**解锁：** 通过 `https` 对这些主机使用 [`card.net.fetch()`](https://docs.neurosquad.ai/zh/card-sdk/api/network)。

**范围：** 严格限于声明的主机模式，且只允许公网地址——解析到私有、回环或云元数据地址的主机会被拒绝，每次重定向也同样检查。
第 1 版中，卡片无法申请“任意主机”。

### `network.local` — high

**用户看到：** *Connect to servers on this computer.*（连接到本机上的服务器）访问在 localhost 上监听的程序，例如开发服务器和本地数据库。

**解锁：** 通过 `http` 或 `https` 对 `localhost`、`127.0.0.1` 和 `::1` 使用 `card.net.fetch()`。

**范围：** 除 NeuroSquad 自己的服务器以外的任何端口：它的 MCP 服务器、远程访问服务器、开发者链接服务器、
每张浏览器卡片中 Chrome 的调试端口，以及应用自身的开发服务器。发往本机的请求永远不会填入[密钥占位符](https://docs.neurosquad.ai/zh/card-sdk/api/network#secrets)。

### `fs.read` — high

**用户看到：** *Read files in the workspace folder.*（读取工作区文件夹中的文件）此工作区项目文件夹中的任何文件，包括 `.env` 等文件中保存的机密。

**解锁：** [`card.fs.stat/list/read*/watch()`](https://docs.neurosquad.ai/zh/card-sdk/api/files)，以及 `card.workspace` 中工作区的绝对路径 `path`。

**范围：** 工作区文件夹。路径相对于它；`..` 和绝对路径会被拒绝，指向文件夹外部的链接也会被拒绝。
如果工作区文件夹是用户的主文件夹、某个磁盘的根目录，或包含 NeuroSquad 自己的数据文件夹，所有文件调用都会被拒绝。

### `fs.write` — high

**用户看到：** *Change files in the workspace folder.*（修改工作区文件夹中的文件）在此工作区的项目文件夹中创建、覆盖文件或将其移入回收站。
此工作区的智能体会读取并运行这些文件，因此此卡片可以让它们执行命令。受保护：.git、智能体设置（.claude、.mcp.json、CLAUDE.md、AGENTS.md 等）以及 NeuroSquad 自身的数据。

**解锁：** `card.fs.writeText/writeBytes/mkdir/trash()`。

**范围：** 同 `fs.read`，但不包括[受保护的路径](https://docs.neurosquad.ai/zh/card-sdk/api/files#protected)：任何 `.git`、智能体和编辑器的设置、CI 工作流。
没有彻底删除——`trash` 会移入系统回收站。包含 `fs.read`。

### `clipboard.write` — low

**用户看到：** *Copy to your clipboard.*（复制到剪贴板）用卡片中的文本替换剪贴板内容。

**解锁：** [`card.copyText()`](https://docs.neurosquad.ai/zh/card-sdk/api/files#clipboard)，每秒一次。无法读取剪贴板。

### `canvas.spawn` — low

**用户看到：** *Add cards next to itself.*（在旁边添加卡片）在画布上它的旁边放置最多 4 张新卡片。

**解锁：** [`card.spawn()`](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#spawn)——你的卡片的另一份副本，或一篇笔记、待办清单、任务看板、便签，并用箭头与它相连。

**范围：** 每张卡片 4 张、每分钟 4 张，并受工作区卡片数量上限约束。

### `background` — low

**用户看到：** *Keep running when you are not looking.*（在你不看时继续运行）在其工作区隐藏时保持活动。会消耗更多内存和电量。

**解锁：** 卡片在隐藏时不会被[暂停](https://docs.neurosquad.ai/zh/card-sdk/api/environment#lifecycle)。

**范围：** 整个应用中最多 8 张这样的卡片在后台运行；超出后，最久未被看到的仍会被暂停。

### `usage.read` — low

**用户看到：** *See token usage and costs.*（查看令牌用量和费用）此工作区的智能体用了多少令牌以及花费多少。

**解锁：** [`card.usage()`](https://docs.neurosquad.ai/zh/card-sdk/api/files#usage)，以及对用箭头连接的智能体使用 [`card.agents.usage()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#usage)。

**范围：** 卡片自己所在的工作区。

## 安装对话框中除权限外还列出什么

以下内容由清单推导得出，并不是权限：卡片向相连智能体提供的[工具](https://docs.neurosquad.ai/zh/card-sdk/api/tools)名称，以及它有多少个输入和输出端口。
可选权限出现在 **It may ask later for** 之下。

> 只申请你需要的最少权限。每一行高风险都会让谨慎的用户犹豫，而缺少 `reason` 会让他们只能去猜。
> 如果某个功能只是偶尔需要一项强权限，就把它设为可选，等用户真正要用这个功能时再申请。