# 卡片 SDK

> 为 NeuroSquad 画布开发你自己的卡片——能观察并指挥智能体、通过箭头交换数据、为智能体提供新工具的小型 Web 应用——并在 GitHub 上分享。

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

**自定义卡片**是一个小型 Web 应用，和你的智能体、终端、笔记一起放在画布上。任何人都可以用卡片 SDK
（`@neurosquad/card-sdk`）开发一张卡片并推送到 GitHub，其他人只需把 `owner/repo` 粘贴进 NeuroSquad 就能安装。

本节面向两类读者：

- **所有想使用别人所做卡片的人**——请从[安装社区卡片](https://docs.neurosquad.ai/zh/card-sdk/community-cards)开始。那里说明了卡片能做什么、不能做什么，
安装对话框会告诉你哪些信息，以及如何收回授权。
- **想自己开发卡片的开发者**——请从[快速上手](https://docs.neurosquad.ai/zh/card-sdk/quick-start)开始：几分钟内就能在画布上跑起一张可用的卡片。

## 卡片能做什么

自定义卡片是画布上的“一等公民”：它有同样的标题栏，可以调整大小、加入[分组](https://docs.neurosquad.ai/zh/canvas/groups)、连接[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)，
缩小画布时显示概览图块，也和其他卡片一样出现在侧边栏中。在自己的方框里，它想画什么都行。借助 SDK，它可以：

  - **观察智能体**: 谁在工作、谁在等你、一轮何时开始和结束——在你连接之后，还能看到智能体输出了什么。
  - **向智能体发提示词**: 给与它相连的智能体发送指令。智能体工作时提示词会排队，并遵守工作区预算。
  - **与其他卡片通信**: 通过箭头上的类型化端口：卡片可以向笔记追加内容、往清单里添加任务，或为另一张自定义卡片提供数据。
  - **为智能体提供工具**: 声明一个工具并在卡片中实现它；相连的智能体通过应用的 MCP 服务器调用它。
  - **访问网络**: 从它声明过的主机获取数据——经由应用的代理，所用的密钥卡片自己永远看不到。
  - **处理项目文件**: 在你允许时，读写工作区文件夹中的文件。
  - **运行命令**: 在与它相连的终端卡片中运行命令，并拿到退出码和输出。
  - **设置与存储**: 由应用绘制的设置表单、重启后依然保留的卡片存储，以及应用的主题和语言。

## 卡片永远不会越出画布

社区代码不被信任，因此每张卡片都**被封闭在自己的方框里**运行：

- 它运行在单独的沙箱进程中。卡死或崩溃的卡片不会冻结画布，也不会连累其他任何东西。
- 它无法自行访问应用本身、你的其他卡片、Node.js、你的文件、Cookie 或互联网。一切都要经过 SDK，
而应用会把每一个请求与你的授权逐一核对。
- 它不能打开窗口或弹窗、进入全屏、弹出系统对话框、发送系统通知、下载文件，也不能让应用跳转到别处。它只能在自己的卡片里绘制。
- 当卡片需要你做决定时——确认操作、打开链接、授予权限、发给危险模式下智能体的提示词、API 密钥之类的机密——
由**应用**在它自己的对话框中询问你，这个对话框会**让整个窗口变暗**，包括侧边栏和标题栏。卡片无法在自己的方框之外绘制，
所以永远伪造不了这一点。卡片正文里的一切都属于卡片自己：NeuroSquad 从不在那里索要密钥。

## 用大白话讲安全模型

  - **由你决定它能做什么**: 卡片会列出它需要的[权限](https://docs.neurosquad.ai/zh/card-sdk/permissions)。在安装任何东西之前，你都能看到这些权限，高风险的排在最前。 没有任何权限的卡片只能在自己的方框里绘制。
  - **箭头就是同意**: 任何到达另一张卡片或智能体的东西——端口上的数据、提示词、命令、读取屏幕——都需要两张卡片之间有一条箭头， **并且**具备相应的权限。没有箭头，就没有数据。
  - **锁定到某个提交**: 一次安装就是“这个仓库的这个确切提交”——是仓库本身的提交，而不是某个分叉（fork）的提交。 不会有任何东西在你背后悄悄改变：更新从不自动进行；要求更多权限、或改变卡片向智能体提供的内容的更新，会再次征求你的同意。
  - **密钥留在应用里**: API 密钥只能在应用自己的对话框中输入，加密保存，并由应用添加到发往你授权的互联网主机的请求中。卡片本身永远看不到它们。
  - **有些文件碰不得**: 即使有文件访问权限，卡片也永远不能修改 `.git`、智能体的设置和指令（`.claude/`、`.mcp.json`、`CLAUDE.md`、`AGENTS.md`……） 或 CI 工作流——而如果工作区是你的主文件夹或整个磁盘，它根本得不到任何文件访问权限。
  - **一切都看得见**: 通过卡片发出的提示词或工具调用会点亮它所经过的箭头，并连同卡片名称记入[箭头日志](https://docs.neurosquad.ai/zh/canvas/arrows#arrow-log)。

> 社区卡片并非由 NeuroSquad 团队制作或审核。只安装你信任的人做的卡片，并仔细阅读权限列表——
> 能向智能体发提示词或运行命令的卡片，可以做那些智能体和终端能做的任何事。

## 本节内容

  - **[安装社区卡片](https://docs.neurosquad.ai/zh/card-sdk/community-cards)**: 面向用户：安装、审阅、撤销、更新和移除。
  - **[快速上手](https://docs.neurosquad.ai/zh/card-sdk/quick-start)**: 从空文件夹到画布上的卡片，再到 GitHub。
  - **[清单文件参考](https://docs.neurosquad.ai/zh/card-sdk/manifest)**: `neurosquad-card.json` 的每个字段。
  - **[权限](https://docs.neurosquad.ai/zh/card-sdk/permissions)**: 每项权限：用户看到什么、它解锁什么。
  - **[API 参考](https://docs.neurosquad.ai/zh/card-sdk/api)**: 每个方法和事件，附类型和示例。
  - **[React 绑定](https://docs.neurosquad.ai/zh/card-sdk/react)**: `CardProvider` 与各种 hook。
  - **[UI 套件与样式](https://docs.neurosquad.ai/zh/card-sdk/styling)**: 看起来像原生界面，或者随你设计。
  - **[测试](https://docs.neurosquad.ai/zh/card-sdk/testing)**: 用于测试和浏览器预览的内存宿主。
  - **[CLI 参考](https://docs.neurosquad.ai/zh/card-sdk/cli)**: `create`、`dev`、`validate`、`pack`。
  - **[发布与更新](https://docs.neurosquad.ai/zh/card-sdk/publishing)**: GitHub、版本，以及用户在更新时看到什么。
  - **[安全检查清单](https://docs.neurosquad.ai/zh/card-sdk/security)**: 分享卡片之前要检查什么。
  - **[常见问题与排错](https://docs.neurosquad.ai/zh/card-sdk/faq)**: 常见错误及修复方法。
  - **[更新日志](https://docs.neurosquad.ai/zh/card-sdk/changelog)**: 每个 SDK 版本的变化，以及它需要的 NeuroSquad 版本。

> 卡片 SDK 刚刚推出。这里描述的一切都基于卡片协议第 1 版；有几件事被有意留到以后——卡片市场、自动更新、
> 完全没有外框就能运行的卡片、文件选择器，以及在手机上运行卡片代码。在相关的地方都会一一注明。