CLI 参考

SDK 附带一个命令行工具 neurosquad-card。它只需要 Node.js 18.17+——没有其他依赖。无需安装即可运行：


npx @neurosquad/card-sdk <command>

或者，在已安装 @neurosquad/card-sdk 的项目中（React 模板就是如此）使用 npx neurosquad-card <command>。 --help 列出全部内容，--version 打印 SDK 版本。

`create`


neurosquad-card create <folder> [--template vanilla|react] [--name <slug>] [--display-name <text>] [--force]

从模板创建新卡片。

参数	含义
`--template`	`vanilla`（默认）：HTML + JS，无需构建，SDK 会被复制到 `vendor/`。`react`：React + Vite + TypeScript。
`--name`	清单的 `name`。默认由文件夹名生成（`My Card` → `my-card`）。
`--display-name`	清单的 `displayName`。默认由名称生成（`my-card` → `My card`）。
`--force`	允许写入非空文件夹。

`dev`


neurosquad-card dev [folder] [--user-data-dir <dir>] [--no-build] [--no-logs]

把文件夹链接到正在运行的应用，实时重载，并输出卡片日志。

找到 NeuroSquad 的数据文件夹——Windows 上是 %APPDATA%\NeuroSquad，macOS 上是 ~/Library/Application Support/NeuroSquad， Linux 上是 ~/.config/NeuroSquad；其他配置档可用 --user-data-dir 或环境变量 NEUROSQUAD_USER_DATA_DIR 指定——然后读取 card-dev.json，这是应用在开发者模式开启期间写入的文件（本地链接服务器的端口和一次性令牌）。
请求应用链接该文件夹。应用会显示一个包含文件夹路径和卡片名称的确认框，然后是常规的权限对话框。dev 最多等待 5 分钟让你确认。
如果 package.json 中有监视模式的构建脚本，就运行它：npm run watch，否则 npm run build -- --watch。--no-build 可跳过。这些是该文件夹自己的 npm 脚本——只对你信任的文件夹运行 dev，否则请传入 --no-build。
输出卡片日志——card.log.*、未捕获的错误、未处理的 Promise 拒绝——来自卡片的所有副本。--no-logs 可跳过。

应用会监视该文件夹，每次有改动都重新加载卡片的所有副本（它们的 launch 为 reloaded）。清单不再通过校验时，问题会显示在卡片上和你的终端里。按键：r 重新加载卡片，q（或 Ctrl+C）退出。退出后文件夹仍保持链接；可在 Settings → Custom cards → Developer mode 中取消链接。

如果 dev 提示开发者模式已关闭，请在 Settings → Custom cards 中打开它。链接服务器只监听 127.0.0.1，只在开发者模式开启时存在，并且每次链接都需要你在应用中确认。

`validate`


neurosquad-card validate [folder] [--json] [--app-version <x.y.z>]

在不安装的情况下运行安装程序会执行的检查：

清单：经过应用自己的校验器（先 schema，再做语义检查：尺寸、设置、端口、工具、schema、保留名称）；
文件：安装程序会拒绝的路径、超过 20 MB 的文件、超过 5 000 个文件或总计超过 100 MB、仅大小写不同的文件名、符号链接（安装程序会跳过）、残留的 .tgz；
图标：是否存在、按字节判断是否为 PNG 或 WebP、≤ 128 KB、是否为正方形（小于 64×64 时给出提示）；
入口页面：沙箱会拦截的内联 <script>、内联 on…= 处理器和外部 src/href；
提醒：没有图标、没有许可证、没有描述；名称或作者自称是 NeuroSquad、official 或 verified（对非官方卡片，应用会拒绝）。

对别人发给你的文件夹运行 validate 和 pack 是安全的：git 运行时会禁用该文件夹自己的钩子，卡片的文本在打印时会去掉转义序列和双向文本字符。

然后它会打印安装对话框预览——用户将被告知的内容，高风险在前，附上你的理由——出错时以非零状态退出。 --json 输出机器可读的报告；--app-version 还会用该版本检查 minAppVersion。


Install dialog preview:
Test radar (test-radar 1.0.0)
  by Acme (self-declared)
  Community code, not made or checked by NeuroSquad.
  It will be able to:
   high    Run commands in terminals connected to it
           Type and run commands in terminal cards you connect to it with an arrow — anything you could run yourself.
   high    Read files in the workspace folder
           Any file in this workspace’s project folder, including secrets stored in files like .env.
           Why: Reads the JUnit report
   low     See the agents on this canvas
           Their names, which tool they run, and whether they are working, waiting for you or finished.
  May ask later for:
   - Copy to your clipboard
  Tools for connected agents: test_radar_run_tests
  Ports: 1 in (run:ns:trigger), 2 out (failures:ns:tasks, summary:ns:markdown)

11 files, 236.7 KB (file list from the folder)
✔ valid

`pack`


neurosquad-card pack [folder] [--out <file.tgz>] [--dry-run] [--json] [--allow-secret-files]

执行 validate，并准确列出将被安装的内容：git 跟踪的文件，加上未被忽略的未跟踪文件——也就是你仓库的 GitHub 压缩包所包含的内容—— 附带大小，以及应用在安装时记录的树哈希（对每个文件的路径和 sha-256 计算的 sha-256）。然后写出一个可复现的 <name>-<version>.tgz （或 --out 指定的文件）；--dry-run 不写任何文件。

pack 会拒绝看起来像凭据的文件——.env*（.env.example、.sample、.template、.dist 除外）、*.pem、*.key、*.p12、*.pfx、id_rsa*、.npmrc、.git-credentials、.netrc——除非你传入 --allow-secret-files；经由符号链接或目录联接到达的内容一律跳过。


file                                size
README.md                           1.4 KB
icon.png                            4.1 KB
index.html                          1.6 KB
main.js                             7.5 KB
neurosquad-card.json                1.6 KB
…
11 files, 236.7 KB unpacked, 66.2 KB packed
tree hash  8315b0d598fee984f9144bfcaa03129de8d3be56fac57a1e4925efbb7b74842d
✔ dry run: the installer would accept this package

不在 git 仓库中时，文件列表就是文件夹的全部内容。

在打发布标签之前使用它：如果某个文件不在列表中（比如你忘了提交的构建产物），用户就拿不到它。

树哈希能让用户——或你自己——确认已安装的卡片与它声称的那个提交逐字节一致。