# 快速上手

> 用模板创建卡片，在 NeuroSquad 中实时运行并热重载，发布到 GitHub，再从那里安装。

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

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

## 1. 创建卡片

```bash
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
```

两个模板生成的是同一张可用的卡片：画布上的智能体及其实时状态、保存在卡片存储中的草稿区、一个输入和一个输出[端口](https://docs.neurosquad.ai/zh/card-sdk/api/ports)，
以及一个相连智能体可以调用的[工具](https://docs.neurosquad.ai/zh/card-sdk/api/tools)。先读懂它，再动手修改。

**纯 HTML 模板**（`vanilla`）：

```text
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. 脱离应用预览

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

```bash
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')`。参见[用模拟宿主测试](https://docs.neurosquad.ai/zh/card-sdk/testing)。

## 3. 在 NeuroSquad 中实时运行

**1. 打开开发者模式**

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

**2. 链接文件夹**

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

**3. 添加卡片**

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

**4. 编辑并保存**

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

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

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

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

## 4. 像安装程序那样检查

```bash
npx @neurosquad/card-sdk validate
```

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

## 5. 发布到 GitHub

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

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

更多内容见[发布与更新](https://docs.neurosquad.ai/zh/card-sdk/publishing)。

## 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**。
你的用户也是这样做的；参见[安装社区卡片](https://docs.neurosquad.ai/zh/card-sdk/community-cards)。

## 最小的卡片

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

```json filename="neurosquad-card.json"
{
  "manifestVersion": 1,
  "name": "hello-card",
  "displayName": "Hello",
  "version": "0.1.0",
  "protocol": 1
}
```

```html filename="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>
```

```js filename="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' })
```

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

## 下一步

  - **[清单文件参考](https://docs.neurosquad.ai/zh/card-sdk/manifest)**: 大小、权限、设置、端口、工具。
  - **[API 参考](https://docs.neurosquad.ai/zh/card-sdk/api)**: `card.*` 能做什么。
  - **[安全检查清单](https://docs.neurosquad.ai/zh/card-sdk/security)**: 在分享之前。