快速上手

你需要 NeuroSquad 和 Node.js 18.17 或更高版本。不需要开发者账号；使用纯 HTML 模板时也不需要任何构建工具。

1. 创建卡片


npx @neurosquad/card-sdk create my-card                    # plain HTML + JS, no build step
npx @neurosquad/card-sdk create my-card --template react   # React + Vite + TypeScript

两个模板生成的是同一张可用的卡片：画布上的智能体及其实时状态、保存在卡片存储中的草稿区、一个输入和一个输出端口，以及一个相连智能体可以调用的工具。先读懂它，再动手修改。

纯 HTML 模板（vanilla）：


my-card/
  neurosquad-card.json   the manifest: name, size, permissions, settings, ports, tools
  index.html             the page loaded into the card
  main.js                the card's code
  style.css
  icon.png               square PNG or WebP, 128 KB at most
  vendor/                the SDK (card-sdk.js), the UI kit (ui.css), the mock host, the manifest schema

React 模板：同样的清单文件和图标，src/ 中有 main.tsx、App.tsx 和 i18n.ts，以及已为卡片配置好的 Vite （相对 URL、无内联脚本）。先运行 npm install；npm run build 会生成 dist/，应用加载的就是它。

2. 脱离应用预览

单独打开页面时，它会连接到一个模拟宿主，其中有示例智能体和一篇已连接的笔记，所以你可以在任何浏览器里调整外观：


npx serve .      # plain template, then open http://localhost:3000
npm run dev      # React template

在浏览器控制台里，可以用 mockHost 驱动它：mockHost.setAgentStatus('a2', 'working')、 mockHost.setLanguage('ru')、mockHost.sendPortMessage('text', 'hello')。参见用模拟宿主测试。

3. 在 NeuroSquad 中实时运行

打开开发者模式

在 NeuroSquad 中：Settings → Custom cards → Developer mode。它允许本机上的 CLI 请求链接一个文件夹；它只监听 127.0.0.1。

链接文件夹

在卡片文件夹中运行 npx @neurosquad/card-sdk dev。应用会请你确认链接，然后显示与普通用户看到的相同的权限对话框。接受即可。

添加卡片

在画布上：+ → Custom card…，选择你的卡片（它带有 Dev 徽章）。

编辑并保存

每次保存都会重新加载卡片。运行 dev 的终端会打印卡片日志——card.log.*、未捕获的错误和被拒绝的 Promise。按 r 手动重新加载，按 q 退出。

使用 React 模板时，dev 还会替你运行 npm run watch，每次保存都会重新构建 dist/。传入 --no-build 可以改用你自己的监视进程。

开发者模式不能绕过授权：链接的文件夹获得的正是它的清单文件所声明的权限，并且要经过同样的对话框。修改清单中的权限后，卡片会再次询问。

不用 CLI。 Settings → Custom cards → Link a folder… 也能链接文件夹——如果只是想试试别人以文件夹形式发给你的卡片，会很方便。

4. 像安装程序那样检查


npx @neurosquad/card-sdk validate

validate 会运行应用自己的清单检查和安装程序的文件规则，对沙箱会拦截的内容（内联脚本、外部文件）发出警告，并打印用户将看到的安装对话框。pack 更进一步，准确列出将被安装的文件，以及应用会记录的树哈希（tree hash）。参见 CLI 参考。

5. 发布到 GitHub

把卡片文件夹推送到一个 GitHub 仓库——可以是独立仓库，也可以是更大仓库中的一个文件夹。发布就这么简单。有几点要做对：

neurosquad-card.json 必须位于卡片文件夹的根目录。
提交构建产物。 应用直接从仓库安装，从不执行构建。React 模板的 .gitignore 特意没有忽略 dist/。
给发布版打标签（v1.0.0），别人就可以安装固定版本，或者跟随你的最新发布版。

更多内容见发布与更新。

6. 从 GitHub 安装

在 Settings → Custom cards → Install a card 中粘贴 your-name/my-card（仓库中 pomodoro 文件夹里的卡片用 your-name/my-cards/pomodoro，指定标签用 your-name/my-card@v1.0.0），然后点击 Install。你的用户也是这样做的；参见安装社区卡片。

最小的卡片

不需要模板，三个文件就够：

neurosquad-card.json


{
  "manifestVersion": 1,
  "name": "hello-card",
  "displayName": "Hello",
  "version": "0.1.0",
  "protocol": 1
}

index.html


<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <script type="module" src="main.js"></script>
  </head>
  <body>
    <h1 id="title">…</h1>
  </body>
</html>

main.js


// card-sdk.js is dist/card-sdk.js from the @neurosquad/card-sdk package, copied next to this file.
import { connect } from './card-sdk.js'
 
const card = await connect()
document.getElementById('title').textContent = `Hello from ${card.workspace.name}`
card.setStatus('Ready', { tone: 'success' })

它不申请任何权限，所以只能在自己的方框里绘制、保存存储和设置、设置自己的标题栏——这已经是一张有用的卡片了。

下一步