Skip to Content
卡片 SDK清单文件参考

清单文件参考

每张卡片的文件夹根目录都有一个 neurosquad-card.json。应用在安装时读取它，清单检查不通过的卡片会被拒绝； npx @neurosquad/card-sdk validate 会在你的电脑上运行完全相同的检查。

想在编辑器里获得补全，可以把 $schema 指向 SDK 自带的 schema： ./node_modules/@neurosquad/card-sdk/schema/neurosquad-card.v1.json（React 模板）或 ./vendor/neurosquad-card.schema.json（纯 HTML 模板）。它也以 @neurosquad/card-sdk/schema.json 导出。

完整示例

{
  "$schema": "./node_modules/@neurosquad/card-sdk/schema/neurosquad-card.v1.json",
  "manifestVersion": 1,
  "name": "test-radar",
  "displayName": { "en": "Test radar", "ru": "Радар тестов", "zh": "测试雷达" },
  "version": "1.0.0",
  "protocol": 1,
  "description": "Runs the test suite in a connected terminal and shows what broke.",
  "author": { "name": "Acme", "url": "https://acme.dev" },
  "license": "MIT",
  "homepage": "https://acme.dev/test-radar",
  "keywords": ["tests", "ci"],
  "icon": "icon.png",
  "minAppVersion": "0.1.100",
  "entry": "dist/index.html",
  "card": {
    "defaultSize": { "w": 460, "h": 340 },
    "minSize": { "w": 320, "h": 220 }
  },
  "permissions": [
    "agents.read",
    "terminals.write",
    { "id": "fs.read", "reason": "Reads the JUnit report" },
    { "id": "network", "hosts": ["api.github.com"], "reason": "Links failures to GitHub issues" },
    { "id": "clipboard.write", "optional": true }
  ],
  "settings": [
    { "key": "command", "type": "string", "label": "Test command", "default": "npm test" },
    { "key": "githubToken", "type": "secret", "label": "GitHub token", "scope": "package" }
  ],
  "ports": {
    "inputs": [{ "id": "run", "label": "Run", "type": "ns:trigger", "default": true }],
    "outputs": [
      { "id": "failures", "label": "Failures", "type": "ns:tasks", "retain": true },
      { "id": "summary", "label": "Summary", "type": "ns:markdown" }
    ]
  },
  "tools": [
    {
      "name": "run_tests",
      "title": "Run the tests",
      "description": "Runs the project's tests and returns failing test names with messages.",
      "inputSchema": {
        "type": "object",
        "properties": { "filter": { "type": "string", "maxLength": 200 } }
      },
      "timeoutMs": 120000
    }
  ]
}

身份信息

字段必填规则含义
$schema字符串给编辑器用，应用会忽略。
manifestVersion是1清单格式版本。
name是a-z、数字和 -，以字母开头，2–48 个字符包的短名。它是卡片工具名的前缀，也是自定义端口类型的命名空间。保留名（内置卡片和工具族）：neurosquad、neurosquad-card、custom、canvas、browser、terminal、agent、note、todo、kanban、host、system、telegram、image、reference、ports、web-watch、watch、timer、sticky、standup、squad、mcp、skill、official。
displayName是多语言文本，≤ 80卡片在菜单、标题栏和安装对话框中显示的名称。
version是SemVer（1.2.0、1.2.0-beta.1）仅供参考——安装锁定的是提交，而不是版本号。但还是要递增它：用户在更新时会看到。
protocol是整数你开发时所针对的卡片协议——目前是 1。为比应用更新的协议开发的卡片会被拒绝，并提示“needs a newer NeuroSquad”。
description多语言文本，≤ 300显示在安装对话框和卡片选择器中。
author{ "name", "url"? }url 必须是 https://。显示时标注为自称。
license字符串 ≤ 100SPDX 标识符，例如 MIT。
homepagehttps:// URL
keywords≤ 20 个不重复字符串，每个 ≤ 40 个字符
icon包内 .png 或 .webp 的路径正方形，≤ 128 KB（128×128 或更大会更清晰）。安装时会按文件字节检查。没有图标时卡片显示一块拼图。
minAppVersionSemVer能运行这张卡片的最低 NeuroSquad 版本。
entry.html 文件路径，默认 index.html加载到卡片中的页面。

多语言文本可以是普通字符串，也可以是必须包含英文的对象： { "en": "Test radar", "ru": "Радар тестов", "zh": "测试雷达" }。应用会显示用户所用的语言，缺失时回退到英文。

文本规则。 名称、描述、标签、理由和工具描述中不能包含控制字符（描述中允许制表符和换行）、双向文本覆盖或隔离字符、 行分隔符、零宽字符或其他不可见字符。只有官方卡片（从 glmn-ai 组织发布）可以在 displayName 或 author 中 自称“NeuroSquad”“official”或“verified”——validate 会警告，应用会拒绝。

路径（entry、icon）相对于清单文件，使用 / 分隔——不能有 ..、不能以 / 开头、不能有反斜杠、 不能使用 Windows 设备名（con、nul……）、不能位于 __ns/ 之下（应用保留了它），最多 20 层、240 个字符。

大小——card

"card": {
  "defaultSize": { "w": 460, "h": 340 },
  "minSize": { "w": 320, "h": 220 },
  "maxSize": { "w": 1200, "h": 900 }
}

尺寸以画布单位计（100% 缩放时的 CSS 像素），为整数，宽 200–2400、高 120–1800，并满足 minSize ≤ defaultSize ≤ maxSize。 默认值：420×320，最小 200×120，最大 2400×1800。用户在最小和最大值之间调整大小； card.requestResize() 同样会被限制在这个范围内。

权限——permissions

权限 id 的列表（≤ 32 项），或带有附加信息的对象：

"permissions": [
  "agents.read",
  { "id": "network", "hosts": ["api.github.com", "*.example.com", "status.example.org:8443"] },
  { "id": "fs.read", "reason": { "en": "Reads the JUnit report", "ru": "Читает отчёт JUnit" } },
  { "id": "clipboard.write", "optional": true }
]
键含义
id权限页面列出的 id 之一。
hosts仅用于 network，且在那里必填：≤ 32 个主机模式。
reason多语言文本 ≤ 300，显示在安装对话框中该权限的下方。说明为什么需要。
optionaltrue = 安装时不询问；卡片在运行时通过 card.permissions.request() 申请。

必需权限在安装时要么全给、要么不装。同一个 id 列出两次会被合并（必需的条目优先于可选的）。

network 的主机模式：只能是小写主机名——api.example.com、api.example.com:8443（443 以外的端口）， 或 *.example.com（任意子域名，不含 example.com 本身）。不能写协议、路径、IP 地址、单独的 * 或 localhost—— 本机访问是单独的 network.local 权限。

设置表单——settings

最多 40 个字段。表单由应用绘制（从卡片的 ⋯ → Settings… 打开，或调用 card.settings.open()）；卡片读取其中的值。

"settings": [
  { "key": "command", "type": "string", "label": "Test command", "default": "npm test", "maxLength": 200 },
  { "key": "notes", "type": "text", "label": "Notes", "placeholder": "Anything the agents should know" },
  { "key": "interval", "type": "number", "label": "Check every (min)", "default": 5, "min": 1, "max": 60, "step": 1 },
  { "key": "compact", "type": "boolean", "label": "Compact view", "default": false },
  { "key": "branch", "type": "select", "label": "Branch", "default": "main",
    "options": [{ "value": "main", "label": "main" }, { "value": "dev", "label": "dev" }] },
  { "key": "accent", "type": "color", "label": "Accent", "default": "#22c55e" },
  { "key": "apiKey", "type": "secret", "label": "API key", "required": true, "scope": "package" }
]
键含义
key以字母开头；字母、数字、_、-；≤ 64。必须唯一。
typestring（单行）、text（多行）、number、boolean、select、color（#rrggbb）、secret。
label、description、placeholder多语言文本（≤ 80、≤ 300、≤ 80）。
default与字段类型一致。select 必须是选项之一，color 必须是 #rrggbb，number 必须在 min/max 之间。secret 不允许有默认值。
required不填就无法保存表单。
scopeinstance（默认）：画布上的每张卡片各一份。package：这个卡片包的所有卡片共享。
maxLength用于 string、text、secret。默认：string 为 2 000，text 为 20 000。
min、max、step用于 number。
options仅用于 select，1–50 个 { "value", "label" }。

密钥（secret）只能在应用的表单中输入，加密保存，永远不会到达卡片：卡片只能知道它是否已设置， 并通过网络请求头中的 {{secret:<key>}} 占位符来使用它。

端口——ports

通过箭头的类型化数据连接：最多 16 个 inputs 和 16 个 outputs。完整指南：端口。

"ports": {
  "inputs": [
    { "id": "run", "label": "Run", "type": "ns:trigger", "default": true },
    { "id": "lookup", "label": "Look up", "type": "ns:text", "mode": "request",
      "response": { "type": "ns:json" } }
  ],
  "outputs": [
    { "id": "failures", "label": "Failures", "type": "ns:tasks", "retain": true },
    { "id": "coverage", "label": "Coverage", "type": "test-radar/coverage",
      "description": "Line coverage per file, 0..1",
      "schema": {
        "type": "object",
        "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 }
      } }
  ]
}
键适用于含义
id两者a-z、数字、-，以字母开头，≤ 32。同一方向内唯一。
label、description两者多语言文本（≤ 80、≤ 500）。会显示给用户、对端卡片以及探查该端口的智能体。
type两者知名的 ns:* 类型，或自定义的 <package-name>/<type-name>。
schema两者值还必须满足的额外 JSON Schema。自定义类型必须提供。
mode输入stream（默认）：发出即不管的消息。request：发送方会等待回复。
response请求型输入{ "type", "schema"? }——回复的类型。mode: "request" 时必填。
default输入当对端的某个输出可匹配多个输入时优先选用的输入。最多一个。
retain输出应用会保留最后一个值：对端随时可以读取，新连接的对端会收到一次。

允许使用另一个卡片包命名空间下的自定义类型（会给出警告）——两张卡片正是这样约定共享格式的。

工具——tools

最多 32 个可供与卡片相连的智能体调用的工具。指南：给智能体的工具。

键含义
namea-z、数字、_，以字母开头，≤ 40。智能体看到的是 <name with - → _>_<tool>，例如 test_radar_run_tests。这个对外名称不能与 NeuroSquad 的内置工具（canvas_spawn_card、terminal_send_keys……）同名，也不能包含 __。
title≤ 80，给人看的标题。
description≤ 2 000，写给模型看，用英文：它做什么、返回什么。
inputSchema"type": "object" 的 JSON Schema。属性 card 被保留（由应用添加）。
readOnly工具不会改变任何东西时设为 true——会作为提示展示给智能体。
timeoutMs1 000–120 000，默认 30 000。

你编写的 JSON Schema

端口 schema、回复 schema 和工具的 inputSchema 使用 JSON Schema 2020-12 的一个安全子集，安装时检查（≤ 500 个节点，嵌套 ≤ 16 层）：

  • 支持：type、enum、const、properties、required、additionalProperties、 minProperties、maxProperties、items、minItems、maxItems、uniqueItems、minLength、 maxLength、format、minimum、maximum、exclusiveMinimum、exclusiveMaximum、multipleOf、 anyOf、oneOf、$ref（# 或 #/$defs/<name>）、$defs。
  • 格式：uri、date-time、date、email、color、uuid。
  • 会被忽略的注解：$id、$schema、$comment、title、description、default、 examples、deprecated、readOnly、writeOnly。
  • 上限：enum ≤ 256 个选项、总计 ≤ 16 KB；const ≤ 4 KB。
  • 不允许：pattern（来自卡片的正则表达式会在应用中执行——存在拒绝服务风险），以及上面未列出的任何关键字。

schema 的 $id——https://neurosquad.ai/schemas/neurosquad-card.v1.json——只是一个标识符，并不能下载： 请把 $schema 指向 SDK 中的那份副本。

快速上手权限