# 安装社区卡片

> 什么是社区卡片，如何从 GitHub 安装，如何读懂权限对话框，以及如何更新、关闭、撤销权限或移除卡片。

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

社区卡片是其他人用[卡片 SDK](https://docs.neurosquad.ai/zh/card-sdk) 开发并分享在 GitHub 上的卡片。它们集中在 **Settings → Custom cards** 中，
安装后就能像其他卡片一样从画布上添加。

## 安装卡片

**1. 打开 Settings → Custom cards**

在 **Install a card** 下粘贴别人给你的 GitHub 地址。以下写法都可以：
`owner/repo`、`owner/repo@v1.2.0`（标签、分支或提交）、`owner/repo/cards/pomodoro`（子文件夹中的卡片），
或完整的 `https://github.com/…` 链接——包括 `/tree/<branch>/<folder>` 或 `/releases/tag/<tag>` 形式的链接。

**2. 点击 Install 并阅读对话框**

NeuroSquad 会下载这个确切的提交并进行检查，然后告诉你这张卡片是什么、要求做哪些事。此时还没有安装。

**3. 在对话框中点击 Install**

或者点击 **Cancel**——下载的内容会被丢弃。

**4. 把它添加到画布**

在添加菜单（画布或侧边栏上的 **+**）中选择 **Custom card…**，再选中它。
你想放几份都行，每一份都有自己的设置和数据。

> 想找已经有人检查过的卡片？[已验证卡片](https://docs.neurosquad.ai/zh/card-sdk/verified-cards)列表收录了经 NeuroSquad 团队审核的社区卡片，
> 可以在 **Custom card…** 选择器的 **Verified** 标签页中直接安装。

## 读懂安装对话框

  - **名称、作者、版本**: 作者是**自称**的——卡片自己说是谁做的，没有人核实过。要信任的是仓库地址，而不是名字。 只有官方卡片可以自称“NeuroSquad”“official”或“verified”；其他卡片这样做会被应用拒绝。
  - **来源与提交**: GitHub 仓库和将要安装的确切提交，并附有 **View source** 可查看那份代码。安装会锁定在这个提交上， 而且该提交必须属于仓库本身（位于它的默认分支上）：只存在于某个分叉中的提交会被拒绝。 改过名或迁移过的仓库，必须用它的新名称安装。
  - **Community 或 Official**: 每张卡片都会标注 **Community code, not made or checked by NeuroSquad**（社区代码，非 NeuroSquad 制作或审核）—— 只有 NeuroSquad 团队在 GitHub 的 `glmn-ai` 组织下发布的卡片例外（按 GitHub 自己的账号 id 核对，而不只是看名称）， 它们带有 **Official** 徽章。
  - **This card will be able to**: 它需要的[权限](https://docs.neurosquad.ai/zh/card-sdk/permissions)，**高风险的排在最前**，并且显示在卡片自己的描述之前，每项都有通俗的解释，通常还附有作者给出的理由。 这些权限要么全给、要么不装：安装卡片就意味着授予全部权限。
  - **It may ask later for**: 可选权限。安装时**不会**授予；卡片需要时会在屏幕上询问，你可以拒绝。
  - **工具与端口**: 它向你连接的智能体提供的工具，以及它有多少个用于箭头的数据端口。

> 最需要留意的是标为 **High risk** 的几行。能**向智能体下达指令**或**在终端中运行命令**的卡片，
> 可以做那些智能体和终端能做的任何事——改你的代码、删文件、推送到 git。一张既能**读取文件**、
> 又能访问**任意网络地址**的卡片，就可能把你的项目文件发送出去。

## 卡片永远做不到的事

无论它要求什么权限，卡片都被封闭在自己的方框里运行。它不能打开窗口，不能直接接触应用或其他卡片，
不能超出授权去读取你的文件或联网，不能显示系统通知，也不能在卡片之外绘制。应用会在每次调用时检查卡片发出的每一个请求。
参见[卡片永远不会越出画布](https://docs.neurosquad.ai/zh/card-sdk#cards-never-leave-the-canvas)。

**真正的 NeuroSquad 询问会让整个窗口变暗。** 每当卡片需要你做决定——确认操作、链接、权限、发给危险模式下智能体的提示词、
密钥——应用都会在它自己的对话框中询问，对话框标题为 **NeuroSquad is asking**，背后的遮罩连侧边栏和标题栏也一起变暗。
卡片只能在自己的方框里绘制，所以无法模仿这一点。卡片自己的文字在这种对话框里只会以引用的形式出现，而 **Cancel** 永远是应用的按钮。

**卡片正文里的一切都属于卡片自己。** NeuroSquad 从不在卡片里索要密码或 API 密钥。
卡片需要密钥时，你要通过卡片的 **Settings…** 输入（密钥字段会打开应用的对话框）——密钥会被加密保存，
只发送到你授权的互联网地址，卡片永远看不到它。

**你的智能体设置和仓库受到保护。** 即使卡片被允许修改文件，它也碰不到 `.git`、智能体的设置和指令
（`.claude/`、`.codex/`、`.cursor/`、`.mcp.json`、`CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`QWEN.md`……）、
编辑器和 CI 配置（`.vscode/`、`.idea/`、`.github/workflows/`、`.husky/`……）以及包管理器设置（`.npmrc`、`.yarnrc`……）。
而当工作区文件夹是你的主文件夹、某个磁盘的根目录，或包含 NeuroSquad 自己的数据时，任何卡片都得不到文件访问权限。

## 使用卡片

- **箭头。** 大多数卡片在连接后能做更多事。卡片和智能体之间的箭头让卡片可以查看该智能体的屏幕或给它发提示词
（前提是有相应权限），也让智能体可以调用卡片的工具。两张卡片之间的箭头让数据沿端口从箭头尾部流向箭头头部。
- 卡片 **⋯** 菜单中的 **Settings…** 会打开卡片的设置（如果有的话）。有些设置由这张卡片的所有副本共享（表单中会标明）。
- **发给危险模式下智能体的提示词**总是需要你确认：应用会显示卡片想发送的内容，由你点击 **Send prompt** 或 **Cancel**。
如果你删掉箭头、撤销权限，或把智能体切换到危险模式，卡片为该智能体排队的提示词会被丢弃；队列中会显示每条提示词来自哪张卡片。
- 卡片想打开的**链接**会先完整显示出来；只允许 `https://` 链接，并且要在你点击 **Open link** 之后才会打开。
- **限制。** 无论以什么方式发送，一张卡片每分钟最多发送 6 条提示词和 30 条终端命令。
- **提醒。** 卡片需要你时会闪烁并出现在收件箱（Inbox）中——就像一个正在等待的智能体。它不能发出声音或系统通知。
- **暂停的卡片。** 一段时间没看的卡片（它所在的工作区已隐藏一分钟，或打开的卡片太多）会被暂停以节省内存，
回来时从中断的地方继续。拥有 **Keep running when you are not looking** 权限的卡片不会被暂停。

## 更新

NeuroSquad 会在启动一分钟后检查新版本，之后每天检查一次（或在你点击 **Check for updates** 时检查）。
跟随分支安装的卡片会更新到该分支的最新提交；从发布版（release）安装的卡片跟随最新发布版；锁定到标签或提交的卡片永不更新。

**没有任何东西会自动更新。** 有可用更新时，**Settings → Custom cards** 中会显示 **Update**，卡片上也会出现一个小圆点。
点击它会显示变化内容——**新权限**、**将要连接的新地址**、**不再需要**的权限，以及它所提供内容的变化：
提供给智能体的新**工具**或措辞改变的工具、新增或改了类型的**端口**、新的**密钥设置**、变更的**名称、作者或主页**——
并附有查看 GitHub 上代码改动的链接。只要更新涉及其中任何一项，它就会等你同意；在此之前旧版本照常运行。

## 关闭、撤销、移除

在 **Settings → Custom cards** 中，每张已安装的卡片都有：

- **Turned on** 开关——关闭后它的所有副本都会停止（卡片上显示“This card is turned off”），它的工具从智能体那里消失，
但不会删除任何东西。
- **权限**——点击任意权限旁的 **Revoke** 可以收回它。该卡片包的所有卡片会在没有这项权限的情况下重新加载。
- **Uninstall**——移除卡片包。你可以选择是否**同时从所有画布删除它的卡片**（默认勾选；否则它们会保留为
“package missing”占位卡片），以及是否**同时删除它保存的数据和密钥**（默认不勾选）。

## 私有仓库与 GitHub 限流

GitHub 会限制未登录用户的下载频率。如果安装或检查更新时提示 GitHub 正在限流——或者你想从私有仓库安装——
请在 **Settings → Custom cards** 中添加 **GitHub token**。它会被加密保存，永远不会给卡片看到。

## 手机上的自定义卡片

使用[远程访问](https://docs.neurosquad.ai/zh/remote)时，自定义卡片在手机上显示为它的标题栏和摘要图块，并附有“Open on the computer to use this card”。
它的代码只在电脑上运行——你在手机上查看时，它的工具、端口和提示词依然在电脑上照常工作。