# NeuroSquad Docs > NeuroSquad 是一款适用于 Windows 和 macOS 的免费桌面应用，可以把 AI 编程智能体的命令行工具——Claude Code、Codex CLI、Gemini CLI、OpenCode 以及另外 15 个——作为实时终端卡片并排运行在同一张画布或网格中。从智能体画一条箭头到另一张卡片，智能体就获得那张卡片的工具：浏览器、终端、笔记、MCP 服务器或另一个智能体。智能体完成或需要你回应时它会提醒你，可以从手机操作，并精确显示每个智能体的花费。这里是它的用户指南。 - 下载 Windows 或 macOS 版: https://neurosquad.ai/zh/download/ - 产品网站（关键信息、常见问题、智能体命令行工具、插件、更新日志）: https://neurosquad.ai/zh/llms.txt 简短目录: https://docs.neurosquad.ai/zh/llms.txt --- ## NeuroSquad 是什么 > 用两分钟了解 NeuroSquad 能做什么，以及它背后的几个核心理念。 Source: https://docs.neurosquad.ai/zh/getting-started NeuroSquad 是一款适用于 Windows 和 macOS 的免费桌面应用，用来和 AI 编程智能体一起工作——Claude Code、Codex、Gemini CLI、Qwen Code 以及[另外 15 个智能体命令行工具](https://docs.neurosquad.ai/zh/agents)。你不必再在一堆终端窗口之间来回切换， 而是拥有**一张大画布**：每个智能体都住在自己的卡片里，旁边就是它要用的工具。点击播放，看它完成一轮工作： ### 四个概念，就能掌握整个应用 - **工作区**: 一个项目文件夹。你添加到工作区的每个智能体都在这个文件夹里工作。侧边栏列出了你的所有工作区。 - **卡片**: 画布上的任何东西：智能体、终端、浏览器、笔记、任务看板，以及[更多](https://docs.neurosquad.ai/zh/cards)。你可以随意拖动、调整大小、编组。 - **箭头**: 从一张卡片连到另一张卡片的线。从智能体出发的箭头会**赋予它使用**另一张卡片的能力——在那个浏览器里浏览、 在那个终端里运行命令、在那篇笔记里写字，或者把工作交给那个智能体。[详细了解箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。 - **提醒**: 当智能体完成工作，或停下来问你问题时，NeuroSquad 会告诉你：提示音、发光的卡片、桌面通知。 你尽可以去忙别的，也不会错过。 ### 它不是什么 - **不是一个新的 AI。** NeuroSquad 运行的是你已经在用的智能体，用的是你自己的账号。它不会取代它们。 - **不是存放你代码的云服务。** 智能体、项目和文件都留在你的电脑上。你用免费的 NeuroSquad 账号登录，应用会发送使用统计——只有计数，绝不包含代码、文件或提示词。参见[账号与登录](https://docs.neurosquad.ai/zh/getting-started/account)。 ### 下一步 - **[安装](https://docs.neurosquad.ai/zh/getting-started/installation)**: 下载安装程序，运行安装向导，完成。 - **[你的第一个工作区](https://docs.neurosquad.ai/zh/getting-started/first-workspace)**: 把 NeuroSquad 指向一个项目。 --- ## 安装 > 下载 Windows 版 NeuroSquad 安装程序，选好安装位置，其余一切交给首次运行的设置向导。 Source: https://docs.neurosquad.ai/zh/getting-started/installation NeuroSquad 提供适用于 **Windows 10 和 11（64 位）** 的现成安装程序。下载的是一个小巧的在线安装程序（160 KB）： 它会获取最新版本（约 100 MB），校验 SHA-256 校验和，然后启动安装。无需自行构建， 也不用碰终端。Mac 用户请参阅[在 macOS 上安装](https://docs.neurosquad.ai/zh/getting-started/macos)；Linux 版本稍后推出。 [前往下载页面](https://neurosquad.ai/zh/download/) **1. 下载 NeuroSquad-Installer.exe** 打开我们网站上的[下载页面](https://neurosquad.ai/zh/download/)，点击 **下载 Windows 版**。 运行后，它会下载最新版本的 NeuroSquad，校验后打开安装界面。 **2. 运行它——并通过 SmartScreen** 安装程序目前还没有代码签名，所以 Windows 可能会弹出蓝色的 **Windows protected your PC** （“Windows 已保护你的电脑”）窗口。点击 **More info**（“更多信息”），确认应用是 `NeuroSquad-Installer.exe`，然后点击 **Run anyway**（“仍要运行”）。 **3. 选择安装位置** **安装位置**已经预先填好：`%LOCALAPPDATA%\Programs\NeuroSquad`。可以保留，也可以用 **浏览…** 选择其他文件夹——下方一行会显示 NeuroSquad 需要多少空间（369 MB）以及磁盘剩余空间。 想在桌面放一个 NeuroSquad 图标，就让 **桌面快捷方式** 保持开启。 安装到默认文件夹时，NeuroSquad 只为你当前的 Windows 账户安装，窗口底部会显示 **无需管理员权限**。如果选择 Program Files 这类文件夹，底部会改为 **此文件夹需要管理员权限 · Windows 会请求授权**——点击“安装”后，Windows 会弹窗请求授权。 **4. 点击“安装”** 窗口会显示当前步骤、已解压的文件数量和进度条。**显示日志** 会打开安装日志：每个文件的大小和校验和， 并附有时间戳。解压文件期间可以随时点击 **取消**，已复制的文件会被删除。 **5. 启动 NeuroSquad** 看到 **NeuroSquad 已安装** 后，点击 **启动 NeuroSquad**。之后可以从开始菜单启动它（如果保留了快捷方式， 桌面上也有）。 > 对于任何尚未使用证书签名的新应用，SmartScreen 都会显示这个警告。请只从我们的[下载页面](https://neurosquad.ai/zh/download/)下载安装程序。 ### 从终端安装 同一个安装程序，无界面运行：只为你的 Windows 账户安装，无需管理员权限。每种方式在运行前都会用 SHA-256 校验和核对下载的文件；无论用哪种方式安装，之后 NeuroSquad 都会自动更新。 **winget**——Windows 程序包管理器，Windows 10 和 11 自带： ```powershell winget install NeuroSquad.NeuroSquad ``` **Scoop**——先添加 NeuroSquad 的软件仓库，再安装到 Scoop 的应用文件夹： ```powershell scoop bucket add neurosquad https://github.com/glmn-ai/scoop-neurosquad scoop install neurosquad ``` **PowerShell**——下载最新版本，安装到 `%LOCALAPPDATA%\Programs\NeuroSquad` 并启动 NeuroSquad （Windows PowerShell 5.1 或 PowerShell 7）： ```powershell irm https://neurosquad.ai/install.ps1 | iex ``` ### 登录 首次启动时，NeuroSquad 会请你登录 NeuroSquad 账号——账号是免费的。浏览器会打开 app.neurosquad.ai：用发送到邮箱的验证码或 Google 登录，点击 **Connect**，应用就会接上。在此之前，应用只显示登录界面。详细步骤，以及登录期间应用发送哪些内容，见[账号与登录](https://docs.neurosquad.ai/zh/getting-started/account)。 ### 设置向导 登录后，NeuroSquad 会检查你的电脑上已经有什么，并提议安装缺少的部分。在你点击按钮之前什么都不会改变， 而且每一步都可以跳过——唯一的例外是 Node.js（见下文）。 **1. 智能体 CLI** 你的卡片将要运行的 AI 智能体。如果你已经装好了，向导会告诉你。如果还没有，选择 Claude Code、Codex CLI、OpenCode 或 Kilo Code，然后点击 **Install it for me**——向导会用 npm 安装， 并准确显示运行的是哪条命令。还没有 npm？智能体 CLI 离不开它，所以向导会自动安装 Node.js LTS： 来自 nodejs.org 的官方压缩包，并校验其公布的 SHA-256，仅为你的账户安装，无需管理员权限。 在 Windows 上，如果缺少 Node.js，安装程序在安装时就已完成这一步；已有的 Node.js 永远不会被改动。 **2. 终端与 Git** Git for Windows 自带 Git Bash，终端卡片和隔离工作树都要用到它。向导会用 `winget` 安装它——并且总是先征求你的同意。 **3. 语音输入** 语音输入所用的语音模型不包含在安装程序中，需要单独下载。选择一个模型并点击 **Download**， 或者直接跳过这一步：语音输入是可选功能，其他功能都不依赖它。之后也可以在 **Settings → Dictation** 中下载；在此之前，状态栏会显示 **Dictation: download the model**。参见[语音模型](https://docs.neurosquad.ai/zh/dictation/models)。 **4. 就绪** 点击 **Start working**。你随时可以在 **Settings → Setup** 中重新打开这些步骤。 > 你仍需按常规方式登录每个智能体——在它的卡片里运行一次，按照它自己的登录提示操作即可。NeuroSquad 从不索要你的密钥。 ### 更新 NeuroSquad 会自动更新。如需手动更新，再次运行[下载页面](https://neurosquad.ai/zh/download/)上的 `NeuroSquad-Installer.exe` 即可——它总是获取最新版本。安装程序会自动识别已安装的版本：安装位置指向现有的安装文件夹，按钮变为 **更新**，并有一条提示说明工作区、 智能体和设置都会保留——它们存放在 `%APPDATA%\NeuroSquad`，而不在应用自己的文件夹里。 如果 NeuroSquad 仍在运行，安装程序会显示 **NeuroSquad 仍在运行**，并按名称和 PID 列出占用其文件的每个进程—— 应用本身以及它的卡片终端。你可以自己关闭 NeuroSquad 后点击 **重新检查**，或者点击 **结束并继续** （NeuroSquad 卡片中打开的终端将会停止）。 新版本会先解压到旧版本旁边，完整解压后才替换旧版本。如果更新失败或被取消，原来的版本不会受到任何影响。 ### 卸载 打开 **Windows 设置 → 应用**，找到 **NeuroSquad** 并选择 **卸载**（或运行安装文件夹中的 `Uninstall NeuroSquad.exe`）。卸载只会删除安装程序装上的文件、快捷方式和应用列表中的条目。 你自己放进安装文件夹的文件会保留。 你的数据也会保留——除非打开 **同时删除我的 NeuroSquad 数据**（默认关闭）。这会删除 `%APPDATA%\NeuroSquad`：工作区列表、智能体、设置、听写模型以及智能体的隔离工作树——其中未提交的工作将会丢失。 你的项目文件夹永远不会被改动。参见[你的数据存放在哪里](https://docs.neurosquad.ai/zh/help/data)。 ### 无人值守安装 供 IT 管理员和脚本使用，安装程序可以不显示窗口运行。最新版本的完整安装程序位于 `https://neurosquad.ai/downloads/NeuroSquad-Setup.exe`；在线安装程序会把同样的参数传给它。 ```text NeuroSquad-Setup.exe --silent [--dir <文件夹>] [--no-desktop] [--launch] [--close-app] ``` - `--dir`——安装位置（默认为 `%LOCALAPPDATA%\Programs\NeuroSquad`，或现有安装所在的文件夹） - `--no-desktop`——不创建桌面快捷方式 - `--launch`——安装完成后启动 NeuroSquad - `--close-app`——结束正在运行的 NeuroSquad 进程，而不是直接失败 退出代码：`0` 已安装，`1` 失败，`2` 文件被占用（NeuroSquad 正在运行且未传入 `--close-app`）。 无人值守卸载： ```text "Uninstall NeuroSquad.exe" --silent [--delete-data] ``` ### 如果出了问题 失败页面会用通俗的话说明发生了什么，并显示详细信息和日志，还提供 **重试** 按钮。如果安装在替换文件之前就失败了， 原来的版本仍可正常使用。 安装程序会把每次运行的完整日志保存在 `%TEMP%\NeuroSquad-Setup-<日期>.log`，并在安装文件夹中另存一份 `install.log`。日志面板中有 **复制日志** 和 **打开日志文件** 按钮——报告问题时请附上日志。 ### 下一步 - **[你的第一个工作区](https://docs.neurosquad.ai/zh/getting-started/first-workspace)**: 把 NeuroSquad 指向一个项目文件夹——或者先逛逛演示工作区。 --- ## 在 macOS 上安装 > 在 Apple 芯片或 Intel 的 Mac 上安装 NeuroSquad——在终端里一行命令，或者用 .dmg——以及首次打开时 macOS 会询问什么。 Source: https://docs.neurosquad.ai/zh/getting-started/macos NeuroSquad 支持 **macOS 12 Monterey 及更新版本**，**Apple 芯片**（M1、M2、M3、M4 及更新）和 **Intel** 芯片的 Mac 各有一个版本。不确定你的 Mac 是哪种？打开苹果菜单 → **关于本机**： “芯片：Apple M…”是 Apple 芯片，“处理器：Intel”是 Intel。 [前往下载页面](https://neurosquad.ai/zh/download/#macos) ### 在终端中安装（推荐） 一行命令会选择适合你 Mac 的版本，按公布的 SHA-256 校验和进行校验，把 **NeuroSquad.app** 放进 **应用程序**并打开： ```bash curl -fsSL https://neurosquad.ai/install.sh | bash ``` 如果你的账户无法写入 `/Applications`，脚本会改为安装到 `~/Applications`——两种情况都不需要管理员 密码。这样安装的副本可以直接打开，连下文所说的首次打开询问都不会出现。再次运行这行命令即可更新已安装的版本。 ### 使用 Homebrew 安装 如果你使用 [Homebrew](https://brew.sh)，可以从我们自己的 tap 安装 NeuroSquad： ```bash brew install --cask glmn-ai/neurosquad/neurosquad ``` 它会安装适合你芯片的版本，按 SHA-256 校验和进行校验，并去掉下载标记，因此打开应用时不会出现 首次打开询问。之后 NeuroSquad 会自行更新，所以 `brew upgrade` 不会动它（`brew upgrade --greedy` 也会更新它）。`brew uninstall --cask neurosquad` 会删除应用；加上 `--zap` 还会删除你的 NeuroSquad 数据。 ### 使用 .dmg 安装 **1. 下载适合你 Mac 的 .dmg** 在[下载页面](https://neurosquad.ai/zh/download/#macos)中，点击 **Apple 芯片**或 **Intel** 下方的 **下载 .dmg**（页面会高亮浏览器报告的那一个）。直接链接： [Apple 芯片](https://neurosquad.ai/downloads/NeuroSquad-arm64.dmg)、 [Intel](https://neurosquad.ai/downloads/NeuroSquad-x64.dmg)；校验和见 [SHA256SUMS-mac.txt](https://neurosquad.ai/downloads/SHA256SUMS-mac.txt)。 **2. 把 NeuroSquad 拖进“应用程序”** 打开 .dmg，把 **NeuroSquad** 拖到旁边的 **Applications** 文件夹上。 **3. 首次打开：点击“打开”** NeuroSquad 使用 Apple Developer ID 签名并经过 Apple 公证。首次打开通过浏览器下载的副本时，macOS 会像对待任何从互联网下载的应用一样询问：**“NeuroSquad”是从互联网下载的应用。你确定要打开它吗？** ——并说明 Apple 已检查过它，未发现恶意软件。点击**打开**即可，之后 macOS 不会再问。 > 这个询问与下载方式有关，而不是应用本身：浏览器会把每个下载的文件标记为“来自互联网”。终端安装、 > Homebrew 和 NeuroSquad 自身的更新下载时不带这个标记，所以连这个询问都不会出现。 #### 如果 macOS 仍然无法打开 0.1.218 之前的版本没有经过公证。如果 macOS 提示未打开“NeuroSquad”、Apple 无法验证它，或者提示它已损坏， 你手上很可能是这样的旧副本：把它移到废纸篓，从[下载页面](https://neurosquad.ai/zh/download/#macos)重新下载 .dmg，或者用上文的终端命令或 Homebrew 安装。你的数据不会受影响。 ### 听写所需的权限 语音听写需要 macOS 的两项权限。**设置 → 听写**会显示还缺少什么，并提供**允许**按钮和打开系统设置对应页面的入口： - **麦克风**——用于录制你的声音。第一次听写时 macOS 会询问。 - **辅助功能**——用于在任何应用中都有效的全局听写快捷键。请在**系统设置 → 隐私与安全性 → 辅助功能** 中打开 **NeuroSquad**；允许后快捷键立即生效。 更新后这些权限会保留。只有一个例外：如果你安装过 0.1.214（第一个 Mac 版本），更新到 0.1.218 后 macOS 会再询问一次麦克风和辅助功能权限，因为从这个版本起应用的签名换成了 Apple Developer ID。 ### 登录和设置向导 其余步骤与 Windows 相同——请参阅[安装](https://docs.neurosquad.ai/zh/getting-started/installation)中关于登录和设置向导的部分。 在 Mac 上，向导通过 npm 安装智能体命令行工具；没有 npm 时，会把 Node.js LTS 安装到 `~/.neurosquad/node` （不修改 shell 配置文件）；Git 无法无人值守安装，向导会给出它的下载页面（使用 Homebrew：`brew install git`）。终端卡片使用你的登录 shell（`$SHELL`，默认是 zsh）； 即使从程序坞启动的应用只拿到最小的 `PATH`，NeuroSquad 也能找到通过 Homebrew、npm、bun、cargo 等安装的命令行工具。 ### 更新 和 Windows 一样，NeuroSquad 会自动更新：新版本在后台下载，按 SHA-256 校验和校验，并在重启时安装——应用会在 原文件夹中被替换并重新打开。菜单栏中的 **NeuroSquad → 检查更新…** 可以立即检查。 如果 NeuroSquad 无法写入自己所在的文件夹（例如它在 `/Applications` 中，而你的账户不是管理员），它会把更新 解压到**下载**文件夹并在访达中显示：退出 NeuroSquad，把新的副本拖进“应用程序”并替换旧版本。 ### 关闭和退出 红色关闭按钮只会隐藏窗口：NeuroSquad 和它的智能体继续运行，点击程序坞中的图标即可找回窗口。用 **Cmd+Q** （或 **NeuroSquad → 退出 NeuroSquad**）退出——这会停止智能体的终端。 ### 卸载 退出 NeuroSquad，把 **NeuroSquad.app** 从“应用程序”移到废纸篓。你的数据——工作区、智能体、设置、听写模型—— 保存在 `~/Library/Application Support/NeuroSquad`；如果想全部清除，也请删除该文件夹。你的项目文件夹永远不会被改动。 参见[数据存放在哪里](https://docs.neurosquad.ai/zh/help/data)。 --- ## 账号与登录 > NeuroSquad 为什么需要登录、应用内如何登录、套餐与设备、离线使用，以及应用到底发送哪些使用统计。 Source: https://docs.neurosquad.ai/zh/getting-started/account NeuroSquad 需要一个 **NeuroSquad 账号**。账号是免费的：每个账号都是 **Free** 套餐，没有限制。每台电脑只需在浏览器里登录一次， 用发送到邮箱的验证码或 Google 均可。 你的代码、文件、提示词和终端都留在你的电脑上——账号不会改变这一点。它只改变两件事：应用会要求你登录；登录期间，应用会发送**使用统计**—— 只有计数，没有内容。完整清单见[下文](#what-the-app-sends)。 ### 为什么需要账号 - **套餐属于你本人**，而不是某一台电脑。 - **你能看到所有使用你账号的电脑**，并可以让其中任何一台退出登录。 - **我们能了解 NeuroSquad 的使用情况**——用了哪些智能体、卡片和功能——从而知道下一步该做什么。 ### 在应用中登录 在你登录之前，NeuroSquad 只显示登录界面：没有画布，也不会启动任何智能体。 **1. 浏览器自动打开** 应用会在默认浏览器中打开 **app.neurosquad.ai**，并显示一个短代码，例如 `ABCD-EFGH`。 **2. 在页面上登录** 输入邮箱，再填入我们发给你的 6 位验证码（10 分钟内有效），或点击 **Google**。新邮箱会直接创建新账号——没有单独的注册步骤。 **3. 连接这台电脑** 页面会询问是否在你的电脑（显示其名称）上连接 NeuroSquad，并显示同一个代码。确认它与应用中的代码一致后，点击 **Connect**。 页面随后显示 **Done — return to NeuroSquad**。 **4. 回到应用** 应用会在几秒内自动发现你已登录——也可以点击 **I've signed in** 立即检查。不小心关掉了标签页？**Open the browser again** 会重新打开它。代码 10 分钟内有效，过期后请重新开始。 > 只为你在自己的 NeuroSquad 窗口中看到的代码点击 **Connect**。连接别人的代码，等于让*别人的*电脑登录*你的*账号。 ### 你的套餐 应用会显示你登录的账号及其套餐。目前每个账号都是 **Free——无限制**。 ### 切换账号或退出登录 退出登录会让应用回到登录界面。电脑上的任何内容都不会被删除：工作区、智能体、笔记和设置都原样保留，再次登录后依然都在——无论是同一个账号还是另一个账号。 ### 在网页上管理账号 在任意浏览器中打开 [app.neurosquad.ai/account](https://app.neurosquad.ai/account)，用同样的方式登录。你可以在那里： - **修改名字和头像。** 头像支持 PNG、JPEG 或 WebP，最大 2 MB；会被重新编码为 256×256 并去除元数据。没有头像时， 会显示一个带你姓名缩写的圆形——应用和网页上都一样。 - **查看你的设备**——每台电脑的名称、系统、应用版本和最后在线时间——并让其中任何一台**退出登录**。那台电脑会回到登录界面。 - **删除账号。** 需要用发送到邮箱的验证码确认。账号及其使用统计会被删除；你电脑上的任何内容都不受影响。 ### 离线使用 登录需要联网。之后即使无法连接 NeuroSquad Cloud，NeuroSquad 也会继续工作：应用照常运行，并显示一个不显眼的 **offline** 提示。从应用最后一次连上云端算起，这样可以持续 **7 天**；之后会要求你重新登录。 如果这台电脑的会话结束了——例如你在网页上让它退出了登录——应用会回到登录界面。电脑上的数据不受影响。 ### 应用发送的内容 在你登录期间，应用会向 NeuroSquad Cloud（`api.neurosquad.ai`）发送以下使用统计——除此之外什么都不发送。你的电脑用一个随机的安装 ID 标识，每个工作区用为它随机生成的 ID 标识，绝不使用它的文件夹或名称。这些统计与你的账号关联，NeuroSquad 团队可以按账号查看。 | 何时 | 内容 | | --- | --- | | 应用运行期间每分钟一次 | 应用版本、操作系统、窗口是否处于焦点、打开了几个工作区、每种智能体命令行工具各有几个智能体在运行 | | 应用启动时 | 应用版本、操作系统及其版本、应用语言；新安装的首次启动会单独标记 | | 打开工作区时，之后每 30 分钟一次 | 各类卡片、各命令行工具的智能体、箭头和分组各有多少 | | 智能体启动时 | 哪个智能体命令行工具、使用自己的登录还是 OpenRouter、危险模式和画布模式是否开启 | | 使用某些功能时 | 功能名称，来自应用内置的固定列表 | | 每次语音输入时 | 录音时长、使用的语音模型和引擎（CPU 或 GPU）、是否识别出文字——绝不包含文字本身 | | 登录时，以及随上述每项一起 | 你所在的国家——服务器根据你的 IP 地址推断；IP 地址本身不保存 | 单条事件保存 90 天；由它们汇总出的每日总数（例如当天的活跃人数）会在此之后继续保存。 #### 绝不发送 - 代码、文件内容、文件名、文件夹路径、仓库地址 - 工作区、卡片和智能体的名称 - 提示词、智能体的回答、终端输出 - 环境变量、密码、令牌和 API 密钥 服务器会拒绝任何不在其清单上的字段，因此即使应用出现错误，也无法夹带内容。智能体本身仍像往常一样直接与各自的 AI 服务通信——不经过 NeuroSquad。完整的隐私说明见 [neurosquad.ai/zh/privacy](https://neurosquad.ai/zh/privacy/)。 ### 下一步 - **[你的第一个工作区](https://docs.neurosquad.ai/zh/getting-started/first-workspace)**: 把 NeuroSquad 指向一个项目文件夹——或者先看看演示。 - **[数据存放在哪里](https://docs.neurosquad.ai/zh/help/data)**: 哪些内容留在你的电脑上，以及如何备份。 --- ## 你的第一个工作区 > 为项目文件夹创建一个工作区，或者先打开现成的演示工作区和 Launch day 工作区四处看看。 Source: https://docs.neurosquad.ai/zh/getting-started/first-workspace **工作区**就是一个项目文件夹。其中的每个智能体都在这个文件夹里启动，所以它天然知道“代码”指的是什么。 ### 先看看演示工作区 在全新安装时，NeuroSquad 会创建一个小小的 **NeuroSquad demo** 工作区：一个已经连好终端的 **Lead** Claude Code 智能体、一篇 **Start here** 笔记、一个 **Try these** 待办清单， 外加一个任务看板和一篇讲解箭头如何工作的笔记。智能体里已经输入好了第一条提示词， 只等你按下 Enter。它位于一个临时文件夹中——不会动到你的任何东西。如果你删掉了它又想找回来， 空画布上有一个按钮可以重新打开它。 ### 一次看全：“Launch day” 想看一套完整的配置？打开侧边栏底部的 **What's new**，点击 **Open Launch day**。你会得到一家正在筹备上线的小型网店，分成五个带边框的章节： - **Start here**——一张便签、一篇指南笔记和一个待办清单形式的导览。 - **Build squad**——三个 Claude Code 智能体（**Lead**、**Frontend**、**Backend**），以及一个任务看板， 上面的任务已经分派给它们。点击 **Start** 开始。 - **Dev tools**——一个开发服务器终端、一个浏览器和一张开发服务器卡片。 - **Business desk**——几篇笔记、一张 Telegram 机器人卡片和一张带设计稿的参考资料卡片。 - **Mission control**——站会、预算、网页监视和专注计时器。 和演示工作区一样，它也位于临时文件夹中。删掉它不会有任何损失。 ### 创建工作区 **1. 点击侧边栏中 Workspaces 旁边的 +** **Create workspace** 对话框随即打开。 **2. 起个名字** 取一个对你有意义的名字——“网店”“博客”“客户 X”。 **3. 选择项目文件夹** 点击 **Browse…**，选择你的项目所在的文件夹。智能体将在那里工作。 **4. 选一个强调色（可选）** 当你有好几个工作区时会很方便——它会在侧边栏中标记这个工作区。 > 删除工作区只会把它从 NeuroSquad 中移除。文件夹和你的文件原封不动地留在原处。 ### 可选的附加设置 如果你的智能体将在[隔离工作树](https://docs.neurosquad.ai/zh/agents/worktrees)中工作，工作区的编辑对话框还允许你添加**初始化命令** （例如安装依赖）、复制到每个新工作树中的**文件**（比如 `.env`），以及一条**运行命令**， 用来启动你的项目并在浏览器卡片中打开它。同一个对话框里还有[指令文件](https://docs.neurosquad.ai/zh/agents/instructions)镜像设置。 ### 下一步 - **[你的第一个智能体](https://docs.neurosquad.ai/zh/getting-started/first-agent)**: 添加一个智能体，给它发一条提示词。 --- ## 你的第一个智能体 > 添加一张智能体卡片，发送你的第一条提示词，并在它完成时收到通知。 Source: https://docs.neurosquad.ai/zh/getting-started/first-agent 每张卡片都从同一个菜单开始。主按钮会添加你上次用过的智能体；旁边的箭头则打开其余所有选项。 把鼠标指向其中任意一项： **1. 打开添加菜单** 打开一个工作区后，点击画布右上角的 **Add Claude Code**（或它旁边的箭头）、侧边栏中工作区下方的添加行， 或者空画布上的按钮。无论在哪里，都是同一个菜单。 **2. 选择一个智能体** 从你已安装的 AI 智能体中选一个——比如 **Claude Code**。一张带实时终端的卡片随即出现， 智能体在你的项目文件夹中启动。想先选模型或角色？ 选择 **New agent… (provider, model, role)**——参见 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter) 和 [角色](https://docs.neurosquad.ai/zh/agents/roles)。 **3. 输入你的提示词** 点进卡片直接输入，就像在普通终端里一样。试试：*“看看这个项目，告诉我它是做什么的。”* **4. 去忙别的** 切换到其他事情上。当智能体完成工作——或者需要你回答时——你会听到提示音， 卡片会发光，桌面通知会写明是哪个智能体。参见 [已完成 / 需要你输入](https://docs.neurosquad.ai/zh/agents/notifications)。 卡片的标题会根据智能体正在做的事自动填写。点击标题即可给它起你自己的名字。 > 如果智能体询问是否可以信任该文件夹，NeuroSquad 会替你回答——你在创建工作区时就已经选定了这个文件夹。 ### 接下来 - **[赋予它能力](https://docs.neurosquad.ai/zh/canvas/arrows)**: 用一条箭头连接浏览器或终端。 - **[通知](https://docs.neurosquad.ai/zh/agents/notifications)**: “已完成”与“需要你输入”的区别。 - **[智能体卡片的全部功能](https://docs.neurosquad.ai/zh/agents/card-menu)**: 标题栏和 ⋯ 菜单，逐项说明。 - **[添加第二个智能体](https://docs.neurosquad.ai/zh/squads)**: 并让第一个来主导。 --- ## 熟悉界面 > 侧边栏及其五个分区、画布、顶栏和状态栏——各部分分别在哪里。 Source: https://docs.neurosquad.ai/zh/getting-started/the-window 把鼠标指向蓝色圆点，看看窗口各部分分别是做什么的： ### 侧边栏 侧边栏顶部的一排五个按钮用于切换各个分区。按钮上的徽标分别统计正在工作的智能体、等待你的智能体以及未完成的任务。 逐个点点看： - **Workspaces**: 你的项目，以及每个项目里的智能体和分组。智能体图标周围有旋转的圆环，表示它此刻正在工作。 - **Agents**: 所有工作区中的全部 AI 智能体，按当前状态分组：**Needs input**、**Working**、 **Finished**、**Idle**、**Not running**。可按名称、工作区或智能体类型筛选。 - **Inbox**: 所有在等你的事情——已完成的智能体，或停下来问你问题的智能体。处理完后点击 **Mark all seen**。 - **Tasks**: 所有工作区中每个[任务看板](https://docs.neurosquad.ai/zh/cards/kanban)和[待办清单](https://docs.neurosquad.ai/zh/cards/todo)里的任务。 - **Integrations**: 你的 [Telegram 卡片](https://docs.neurosquad.ai/zh/integrations/telegram)和[模型提供商](https://docs.neurosquad.ai/zh/providers)。 底部依次是：**Features**（提醒收件箱、模板、崩溃日志、活动与命令历史）、**Usage**、**What's new** 和 **Settings**。 拖动侧边栏的边缘可以调宽或调窄。 ### 窗口的其余部分 - **画布（中间）**: 卡片所在的地方。平移、缩放、移动卡片、绘制箭头。参见[画布基础](https://docs.neurosquad.ai/zh/canvas)。 - **顶栏**: 显示你所在的位置（工作区 › 分组），然后是远程访问按钮、通知铃铛、[“团队”看板](https://docs.neurosquad.ai/zh/squads)按钮、语音输入历史按钮和窗口按钮。 - **状态栏（底部）**: 有多少智能体正在运行或等待、应用版本号（点击可查看新功能），以及语音输入状态。 - **语音输入历史（右侧）**: 你最近口述的所有内容，可以随时再次复制。参见[语音输入历史](https://docs.neurosquad.ai/zh/dictation/history)。 ### 常用快捷键 | 快捷键 | 作用 | | --- | --- | | `Ctrl Shift P` | 按名称跳转到任意智能体 | | `Ctrl Shift J` | 飞到等你最久的那个智能体 | | `Ctrl Shift F` | 搜索所有智能体的输出 | | `Ctrl Shift Space` | 开始或停止语音输入 | | `F5` | 逐张卡片演示画布 | 完整列表见[键盘快捷键](https://docs.neurosquad.ai/zh/help/shortcuts)。 --- ## 画布基础 > 画布是一块无限延伸的白板，你的智能体和它们的工具以卡片的形式存在于其上。 Source: https://docs.neurosquad.ai/zh/canvas 每个工作区都有自己的**画布**——一块可以平移和缩放的无限白板。你添加到工作区的一切都会以**卡片**的形式出现在上面。 切换到另一个工作区不会中断任何东西：其他工作区中的智能体会在后台继续工作，侧边栏会显示哪些智能体正忙。 - **[添加与排列卡片](https://docs.neurosquad.ai/zh/canvas/cards)**: 添加、移动、调整大小、重命名和删除卡片。 - **[箭头赋予能力](https://docs.neurosquad.ai/zh/canvas/arrows)**: 连接卡片，让智能体能够使用它们。 - **[分组](https://docs.neurosquad.ai/zh/canvas/groups)**: 把相关的卡片放进一个带名称的框里。 - **[缩放、平移与撤销](https://docs.neurosquad.ai/zh/canvas/moving-around)**: 在大画布中自如移动；缩小时显示概览磁贴。 - **[画布工具](https://docs.neurosquad.ai/zh/canvas/tools)**: 对齐参考线、小地图、颜色标签、演示模式、箭头日志、模板。 --- ## 添加与排列卡片 > 如何在画布上添加、移动、调整大小、重命名、选择和删除卡片。 Source: https://docs.neurosquad.ai/zh/canvas/cards ### 添加卡片 点击画布右上角的 **Add Claude Code**（名称是你上一次添加的智能体），或点击它旁边的箭头查看其他所有选项。 侧边栏的添加行和空白画布打开的也是同一个菜单： - **AI agents**（AI 智能体）——Claude Code、OpenCode、Hermes Agent、Kilo Code、Codex CLI、Pi、omp、Cursor CLI、 Qwen Code 和 Crush，另有 **New agent…**，可先选择提供商、模型和角色。 - **Terminals**（终端）——系统默认 shell、Windows PowerShell、PowerShell 7、命令提示符和 Bash（只列出你电脑上已有的）。 - **Cards**（卡片）——浏览器、笔记、待办清单、预算、任务看板、Telegram 机器人、参考资料、开发服务器、网页监视、 专注计时器、便签和站会。参见[全部卡片](https://docs.neurosquad.ai/zh/cards)。 新卡片会出现在上一张卡片的右侧。智能体为自己创建的卡片则会出现在该智能体周围。 ### 移动、调整大小、重命名 - **移动**：拖动卡片的标题栏。 - **调整大小**：拖动卡片的边缘或角落。 - **重命名**：点击标题栏中的标题，直接输入。 - **展开**：标题栏中的展开按钮会让卡片铺满画布，再按一次即可恢复。 ### 选择多张卡片 按住 `Shift` 在空白画布上拖动，画出选择框；或按住 `Shift` 或 `Ctrl` 逐个点击卡片。 然后就可以一起拖动它们。 ### 删除 选中一张或多张卡片，按 `Delete`。智能体的 **Delete agent** 位于其 ⋯ 菜单的最后一行；其他卡片的标题栏中有删除按钮。 NeuroSquad 总会先征求确认，因为删除智能体会结束它正在运行的会话。 > 删除卡片永远不会删除你项目中的文件。 ### 弹出到新窗口 智能体卡片可以弹出到独立窗口（⋯ 菜单中的 **Pop out to new window**），在第二块显示器上很方便。 它仍是同一个智能体，只是同时显示在两个地方。 --- ## 箭头赋予能力 > 从智能体向另一张卡片画一条箭头，智能体就能使用那张卡片。 Source: https://docs.neurosquad.ai/zh/canvas/arrows 这是 NeuroSquad 中最重要的理念：**从智能体指向某张卡片的箭头，赋予该智能体使用这张卡片的能力。** 从第一条箭头一直看到箭头日志： ### 画一条箭头 把鼠标悬停在卡片上，卡片边缘会出现小圆点。从圆点拖到另一张卡片上再松开即可。 要删除箭头，选中它后按 `Delete`，或者双击它。 ### 每种箭头带来什么 | 从智能体指向…… | 箭头标签 | 智能体可以…… | | --- | --- | --- | | [浏览器](https://docs.neurosquad.ai/zh/cards/browser) | 浏览器工具 | 打开网页、点击、输入，读取屏幕上和控制台中的内容 | | [终端](https://docs.neurosquad.ai/zh/cards/terminal) | 终端工具 | 运行命令并读取输出 | | [笔记](https://docs.neurosquad.ai/zh/cards/note) | 共享笔记 | 读写这篇笔记 | | [待办清单](https://docs.neurosquad.ai/zh/cards/todo) | 待办清单 | 写下自己的计划并逐项勾选 | | [任务看板](https://docs.neurosquad.ai/zh/cards/kanban) | 任务看板 | 添加任务并推进自己的任务 | | 另一个智能体 | 小队连接 | 给它分派任务并读取它的回答——参见[智能体小队](https://docs.neurosquad.ai/zh/squads) | 其他卡片同样可以配合箭头使用：[开发服务器](https://docs.neurosquad.ai/zh/cards/dev-servers)卡片会告诉连接的智能体哪些服务器正在运行， [参考资料](https://docs.neurosquad.ai/zh/cards/reference)卡片让它能阅读你的设计稿和需求文档，[网页监视](https://docs.neurosquad.ai/zh/cards/web-watch)会在网页变化时通知它， 而 [Telegram](https://docs.neurosquad.ai/zh/integrations/telegram) 卡片会把你的消息转给它，并让它回复。 ### 实时查看 智能体使用某张卡片时，箭头会“活”起来，显示它正在做什么——“Opening”“Clicking”“Running”“Adding to the note”。 你始终能看到哪个智能体在操作什么。 ### 箭头日志 点击箭头即可打开它的 **Arrow log**（箭头日志）：经过这条箭头的每一条命令、每一次网页访问、每一条笔记或委派任务， 都附带时间，重启后依然保留。**Clear log** 可清空日志。 > 每个受支持的智能体都能使用连接的卡片——**aider** 和 **Pi** 没有自己的 MCP 客户端，通过 NeuroSquad > 扩展来使用。每个智能体还能获得哪些功能，参见[支持的智能体](https://docs.neurosquad.ai/zh/agents)。 --- ## 网格模式 > 让智能体在整齐、可调整大小的网格中并排显示——随时切回画布。 Source: https://docs.neurosquad.ai/zh/canvas/grid-mode 画布适合搭建团队：卡片随意摆放、画箭头、分组。而当团队只是在*工作*时，你往往想要相反的东西—— 所有智能体的终端同时在屏幕上，整齐排列。这就是**网格模式**。 用标题栏中的 **画布 / 网格** 开关切换，或按 `Ctrl` `Shift` `G` （Mac 上为 `⌘` `Shift` `G`）。每个工作区会记住自己的模式。 > 切换不会重启任何东西。同一批终端在画布和网格之间移动——会话继续运行，屏幕上的内容保持原样。 ### 布局 网格上方的工具栏用于选择布局： | 布局 | 效果 | | --- | --- | | 全部格子 | 所有智能体，按窗口大小整齐排列 | | 单个格子 | 一个智能体占满区域 | | 左右两个 | 两个智能体，左右并排 | | 2 × 2 | 四个智能体 | | 3 × 2 | 六个智能体 | | 主格加侧栏 | 左侧一个大格，右侧最多三个叠放 | 当布局的位置少于智能体数量时，其余的会在网格下方的**不在视图中**栏里等待。点击其中一个即可把它 换进来——它会占据你正在使用的格子的位置。 格子不会小到无法阅读：智能体很多而窗口较小时，网格会滚动，而不是继续压缩格子。工具栏里的**添加**按钮无需离开网格即可添加智能体或卡片（在分组中，新卡片会加入该分组）。 ### 整理格子 - **调整大小：** 拖动两个格子之间的细线。双击细线可恢复均分。 - **整理：** 让当前布局中的所有格子大小一致。 - **交换：** 拖住格子的标题栏（名称处也可以）放到另一个格子上。 - **最大化：** 格子标题栏中的展开按钮（或 `Ctrl` `Alt` `Enter`）让一个智能体 占满网格；再按一次恢复。 - **在格子之间移动：** `Ctrl` `Alt` 加方向键——到达的终端可以直接输入。 - **撤销：** 在终端之外按 `Ctrl` `Z` 可撤销网格布局的更改。 ### 连接关系 每个格子下方有一排标签，显示它的[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)：它领导或向其汇报的智能体，以及它使用的 卡片——笔记、浏览器、MCP 服务器、技能、插件。标签上的小箭头表示方向。 - 鼠标悬停在格子上，与它相连的格子会亮起。 - 点击另一个智能体的标签，跳到该智能体的格子。 - 点击其他卡片的标签，查看它是什么、与什么相连，并可点击**在画布上显示**。 箭头在画布上绘制和删除；网格负责展示它们。 ### 筛选 - **仅显示智能体** 隐藏终端、笔记、浏览器和其他所有卡片，只留下 AI 智能体。 - **卡片** 显示或隐藏侧边栏，其中是所有不作为格子的卡片：笔记、待办、浏览器、MCP 和技能卡片。 悬停在卡片上可看到它与哪些格子相连；侧边栏可收起为一列图标。 - **团队** 按钮打开或关闭右侧的团队面板。 网格跟随侧边栏：选择一个分组，就只显示该分组的智能体。 --- ## 分组 > 把相关的卡片放进一个带名称、带颜色的框里，一键缩放到它。 Source: https://docs.neurosquad.ai/zh/canvas/groups **分组**是画布上一个带名称、带颜色的框。用它把一个小队、一项功能或一次实验归拢在一起。 - **创建**：点击画布顶部的 **New group**（或侧边栏中工作区旁边的文件夹按钮），为它起个名字并选择框的颜色。 - **添加卡片**：把卡片拖进框内。拖出框外即可移出分组。 - **整体移动**：拖动框，框内的所有内容会随之移动。 - **聚焦**：在侧边栏中点击分组，画布会缩放到该框。 - **重命名或删除**：在分组的编辑对话框中进行。删除分组会保留其中的卡片，它们只是不再属于任何分组。 --- ## 缩放、平移与撤销 > 在大画布中移动、缩小时的概览磁贴，以及撤销布局更改。 Source: https://docs.neurosquad.ai/zh/canvas/moving-around | 操作 | 效果 | | --- | --- | | 拖动空白画布 | 平移 | | 在空白画布上滚动 | 缩放 | | 在卡片上滚动 | 滚动该卡片的内容 | | 在终端上按住 `Ctrl` 滚动 | 放大或缩小终端文字 | | `Ctrl Z` / `Ctrl Shift Z` | 撤销 / 重做卡片的移动、调整大小或排列 | 画布左下角的按钮可以放大、缩小、让所有内容适配屏幕，还能把所有卡片**一键排列**成整齐的网格。 ### 缩小时的概览磁贴 缩得足够小时，每张卡片都会变成一块醒目易读的**磁贴**：显示卡片名称和它最关键的一项信息——智能体的状态和吉祥物、 待办清单的进度、看板各列的任务数、预算占上限的比例、计时器的剩余时间。与此同时一切照常运行：智能体继续工作， 磁贴实时更新。放大回去，完整的卡片仍原样待在原处。 **Settings → Canvas** 中有 **Card overview when zoomed out**（开启或关闭）和 **Switch to the overview below**——卡片切换为磁贴时的缩放比例。 ### 直接跳转 - `Ctrl Shift P`——按名称查找任意工作区中的任意智能体。 - `Ctrl Shift J`——飞到等待你最久的那个智能体。 - 点击通知——画布会飞到对应卡片，卡片闪烁绿光。 - 在侧边栏中点击分组——画布会缩放到该分组。 对齐参考线、吸附、小地图和演示模式，请参见[画布工具](https://docs.neurosquad.ai/zh/canvas/tools)。 --- ## 画布工具 > 对齐参考线与吸附、小地图、颜色标签、演示模式、吉祥物、箭头日志和工作区模板。 Source: https://docs.neurosquad.ai/zh/canvas/tools 这些功能大多位于**画布工具**菜单中——画布右上角的滑块按钮。在这里开关它的 **View** 选项： 同样的开关也在 **Settings → Canvas** 中。 ### 让卡片整齐排列 - **Alignment guides**（对齐参考线）——拖动卡片时，它会吸附到附近卡片的边缘和中心，并显示一条参考线标出对齐位置。 - **Snap to grid**（吸附到网格）——卡片按点阵网格的步长移动，行和列会自动对齐。 ### 小地图 角落里的整张画布缩略图。拖动或在上面滚动即可移动视图。默认关闭；在工具菜单中打开 **Minimap** 即可。 ### 颜色标签 右键点击任意卡片的标题栏，选择一个 **Colour tag**，卡片就会带上彩色边框（智能体卡片还可以在 ⋯ 菜单中使用 **Color tag**）。 **Remove tag** 可移除标签。 ### 跳到正在等你的智能体 `Ctrl Shift J` 会把镜头移到等待你最久的智能体。再按一次跳到下一个。 ### 演示你的画布 按 `F5`（或工具菜单中的 **Present cards**）即可像幻灯片一样逐张浏览卡片——非常适合向同事展示你的小队完成了什么。 用箭头按钮或方向键切换，按 **End presentation** 退出。[便签卡片](https://docs.neurosquad.ai/zh/cards/sticky)很适合做标题页。 ### 智能体吉祥物 每张 AI 智能体卡片上都有一个小机器人，让你一眼看出它处于 **Working**、**Waiting for you**、**Finished**、 **Idle** 还是 **Stopped** 状态。如果你想要更安静的画布，可以在工具菜单中关闭 **Agent mascots**。 ### 箭头日志 点击箭头即可打开它的 **Arrow log**：经过这条箭头的每一条命令、每一次网页访问、每一条笔记或委派任务，都附带时间， 重启后依然保留。**Clear log** 可清空日志。（双击箭头仍然会删除它。）实际效果请见[箭头赋予能力](https://docs.neurosquad.ai/zh/canvas/arrows)。 ### 工作区模板 搭好了满意的布局？**Save as template…** 会保存其中的卡片、布局、箭头和分组框，以及卡片名称、颜色标签和工作区的初始化命令。 对话、终端历史、笔记和清单内容不会保存。 要复用它：选择 **New workspace from template…**，填写名称和项目文件夹，就能得到一套相同的、开箱即用的布局。 #### 把模板添加到已有工作区 模板不一定需要单独的工作区。**插入模板…**（在画布工具菜单中；添加卡片菜单底部的 **模板…**）会为当前工作区打开模板。 在工作区打开时开始的任何导入——市场中的 **使用模板**、文件、链接——默认也是 **现有工作区**，切换到 **新工作区** 只需点一下。 - 工作区的文件夹和运行位置（本机、WSL 或 SSH）保持不变，因此对话框只列出能在那里运行的内容；不能运行的智能体会在确认前列出。 - 新卡片按模板自身的布局一起放在画布现有内容旁边；如果模板没有自己的框架，会放进一个以模板命名的新框架。原有内容不会移动，正在运行的智能体不会重启。 - 工作区只需要一份的卡片——小队、预算、Code Graph、RTK，以及设置相同的记忆、caveman、Context7、MCP 或技能卡片——会被复用：模板的箭头连接到你已有的卡片，而不是再添加一份。 - 需要独立 worktree 的智能体只有在文件夹是 git 仓库时才会获得；否则直接在该文件夹中工作，对话框会提示。 - 添加后提示中的 **撤销** 只会移除刚添加的卡片和框架。为模板安装的组件会保留。 --- ## 支持的智能体 > NeuroSquad 能运行哪些 AI 编程智能体，以及各自支持哪些功能。 Source: https://docs.neurosquad.ai/zh/agents **智能体卡片**运行的是真正的 AI 编程智能体——就是你在终端里运行的同一个程序，使用你自己的账号。NeuroSquad 支持其中十九种，另外还支持普通终端。 - **Claude Code**: 支持最完整：精确区分“已完成”与“需要你的输入”、上下文指示器、工作日志。 - **Codex CLI**: 准确区分“已完成”和“等待你的输入”（并说明在问什么）、箭头、画布模式、从上次中断处继续、上下文指示器、工作日志、OpenRouter 模型。 - **Qwen Code**: 准确区分“已完成”和“等待你的输入”，并说明它在问什么；箭头、画布模式、能从上次中断处继续、上下文指示器、工作日志、OpenRouter 模型。 - **Gemini CLI**: 准确区分“已完成”和“等待你的输入”，并说明它在问什么；箭头（新箭头无需重启即可生效）、画布模式、技能、能从上次中断处继续、上下文指示器、Compact、工作日志、按卡片统计的令牌、通过 NeuroSquad 使用 OpenRouter 模型。 - **Kimi Code**: 准确区分“已完成”和“等待你的回答”并显示它在问什么，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、Compact、工作日志、按卡片统计的用量和 OpenRouter 模型。 - **GitHub Copilot CLI**: 准确区分“已完成”和“等待你的输入”，并说明它在问什么；箭头、画布模式、技能、能从上次中断处继续、上下文指示器、Compact、工作日志，无需 Copilot 订阅也能使用 OpenRouter 模型。 - **Hermes Agent**: 准确区分“已完成”和“等待你的回答”，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、工作日志和 OpenRouter 模型。 - **OpenCode**: 准确区分“已完成”和“等待你的回答”，支持箭头、画布模式，能接着上次继续；免费模型无需密钥。 - **Kilo Code**: 准确区分“已完成”和“等待你的回答”，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、工作日志和 OpenRouter 模型。 - **omp**: 准确区分“已完成”和“等待你的回答”（并说明它在问什么），支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、工作日志和 OpenRouter 模型。 - **Pi**: 准确区分“已完成”和“等待你的回答”，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、工作日志和 OpenRouter 模型。 - **aider**: 准确区分“已完成”和“等待你的回答”并显示它问的内容，通过 NeuroSquad 扩展支持箭头和画布模式、技能，能接着上次继续，并有上下文指示器、Compact、工作日志和 OpenRouter 模型。 - **Factory Droid**: 准确区分“已完成”和“等待你的回答”并显示它问的内容，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、Compact、工作日志，无需 Factory 账户即可使用 OpenRouter 模型。 - **Amp**: 通过 NeuroSquad 插件准确区分“已完成”和“等待你的回答”，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、工作日志。使用你自己的 Amp 账户——模型由 Amp 服务端提供，因此不支持 OpenRouter，也没有按卡片统计的费用。 - **Auggie**: 准确区分“已完成”和“等待你的输入”，并显示它询问的命令；箭头、画布模式、技能、从上次中断处继续、上下文指示、日志、按卡片统计的 token。运行在你自己的 Augment 账户上——模型由 Augment 提供，因此不支持 OpenRouter。 - **Cursor CLI**: 区分“已完成”和“等待你的输入”，并显示它询问的命令；箭头（应用自身的工具已预先批准）、画布模式、技能、从上次中断处继续、上下文指示、Compact、日志、交接。运行在你自己的 Cursor 账户上——模型由 Cursor 提供，因此不支持 OpenRouter，也没有按卡片统计的费用。 - **Goose**: 准确区分“已完成”和“等待你的回答”并显示它在问什么，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、Compact、工作日志、按卡片统计的费用和 OpenRouter 模型。 - **Cline CLI**: 通过 NeuroSquad 插件准确区分“已完成”和“等待你的回答”并显示它在问什么，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、Compact、工作日志、按卡片统计的费用和 OpenRouter 模型。 - **Crush**: 通过它自己的状态通道准确区分“已完成”和“等待你的回答”并显示它在问什么，支持箭头、画布模式、技能，能接着上次继续，并有上下文指示器、Compact、工作日志、按卡片统计的费用和 OpenRouter 模型。 | 智能体 | 箭头赋予能力 | 从上次中断处继续 | 危险模式 | | --- | --- | --- | --- | | **Claude Code** | Yes | Yes | Yes | | **Codex CLI** | Yes | Yes | Yes | | **Qwen Code** | Yes | Yes | Yes | | **Gemini CLI** | Yes | Yes | Yes | | **Kimi Code** | Yes | Yes | Yes | | **GitHub Copilot CLI** | Yes | Yes | Yes | | **Cursor CLI** | Yes | Yes | Yes | | **OpenCode** | Yes | Yes | Yes | | **Hermes Agent** | Yes | Yes | Yes | | **Kilo Code** | Yes | Yes | Yes | | **Pi** | Yes | Yes | No | | **omp** | Yes | Yes | Yes | | **Crush** | Yes | Yes | Yes | | **aider** | Yes | Yes | Yes | | **Factory Droid** | Yes | Yes | Yes | | **Amp** | Yes | Yes | Yes | | **Auggie** | Yes | Yes | Yes | | **Goose** | Yes | Yes | Yes | | **Cline CLI** | Yes | Yes | Yes | - **箭头赋予能力**: 智能体可以使用相连的浏览器、终端、笔记和其他智能体，并能在[画布模式](https://docs.neurosquad.ai/zh/squads/canvas-mode)下工作。参见[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。 - **从上次中断处继续**: 重启 NeuroSquad 后，智能体会继续同一段对话。不支持此功能的智能体每次都会开始一段新对话。 - **危险模式**: 智能体可以跳过权限询问。参见[危险模式](https://docs.neurosquad.ai/zh/agents/dangerous-mode)。 **Claude Code**、**Codex CLI**、**Hermes Agent**、**OpenCode**、**Kilo Code** 和 **Qwen Code** 的支持最完整：它们会准确告诉 NeuroSquad 自己何时在[等待你的回答](https://docs.neurosquad.ai/zh/agents/notifications)，并且拥有上下文指示器、Compact 和工作日志。Claude Code、Codex CLI、OpenCode、Kilo Code、Hermes Agent、Qwen Code、Pi 和 omp 的 token 用量会显示在[用量与费用](https://docs.neurosquad.ai/zh/usage)中。 Claude Code、Codex CLI、OpenCode、Kilo Code、Qwen Code 和 Hermes Agent 也可以不使用你自己的登录，而是运行 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter) 上的模型。 **GitHub Copilot CLI** 获得同样深度的支持：它自己的钩子会告诉 NeuroSquad 它何时在工作、已完成或在等待你的回答——并附上它想运行的命令或它提出的问题。新箭头无需重启即可生效，画布模式在危险模式下依然有效，重启后继续同一段对话，并有上下文指示器、Compact、工作日志和按卡片统计的用量。它使用你的 Copilot 订阅运行——完全没有订阅时，也可以运行 OpenRouter 上的模型。 **Pi** 通过它启动时加载的一个 NeuroSquad 小扩展获得同样深度的支持：它会报告自己何时在工作、已完成或在等待你的回答，支持箭头和画布模式，并有上下文指示器、Compact、工作日志和 OpenRouter 模型。Pi 在运行工具前从不请求许可，所以没有需要打开的危险模式——它本来就是这样工作的。 **omp** 获得同样深度的支持：它自带 MCP 客户端，启动时加载的 NeuroSquad 小扩展会报告它何时在工作、已完成或在等待你的回答——包括它想运行哪个工具、在问什么。它支持箭头和画布模式（即使在危险模式下也保持生效），重启后接着同一段对话，并有上下文指示器、Compact、工作日志和 OpenRouter 模型。 ### 终端 你也可以添加普通终端——系统默认 shell、Windows PowerShell、PowerShell 7、命令提示符或 Bash（Git Bash）。参见[终端卡片](https://docs.neurosquad.ai/zh/cards/terminal)。 > 不确定自己装了哪些智能体？**Settings → Harnesses** 会列出 NeuroSquad 在你电脑上找到的智能体，**Settings → Setup** 可以帮你安装。 --- ## 已完成 / 需要你的输入 > NeuroSquad 如何告诉你某个智能体已完成，或正在等你回答。 Source: https://docs.neurosquad.ai/zh/agents/notifications 你不必一直盯着智能体。当其中某个需要你时，NeuroSquad 会告诉你——而且能区分两种情况： ### 两种信号 - **Done**: 智能体已完成本轮工作，正在等你的下一条提示词。状态标签变为绿色。 - **Needs input**: 智能体中途停下，正在问你问题——通常是请求许可，比如“我可以运行这条命令吗？”。标签变为琥珀色，卡片会闪烁。通知会显示它在问什么，并且会一直停留在屏幕上直到你回答，因为被卡住的智能体不会自己解除阻塞。 你回答之后，通知会自动消失。 > Claude Code、OpenCode、Kilo Code 和 Hermes Agent 会准确告诉 NeuroSquad 属于哪一种情况。对于其他智能体，NeuroSquad 会察觉智能体何时安静下来，并将其视为已完成。 ### 提醒方式 - 一声短促的**提示音**（Chime、Ping 或 Marimba）， - 卡片**发光**，侧边栏中该智能体旁出现一个圆点， - 一条**桌面通知**——点击后画布会直接飞到那张卡片， - 顶栏的**通知铃铛**会记录发生过的事件， - 可选：通过 webhook 向 **Slack 或 Discord** 发送消息， - 可选：向 [Telegram](https://docs.neurosquad.ai/zh/integrations/telegram) 发送消息——适合你不在电脑前的时候。 以上每一项都可以在 **Settings → Notifications** 中单独开关。 ### 快速跟进 - `Ctrl Shift J`——飞到等待最久的智能体。 - `Ctrl Shift A`——“需要关注”收件箱：所有等待中的智能体集中在一个列表里。 - 侧边栏的 **Inbox** 部分显示同样的列表。 需要安静一会儿？[专注计时器](https://docs.neurosquad.ai/zh/cards/flow-timer)会把“已完成”提醒暂缓到你的专注时段结束。 ### 会通知你哪些事 在 **设置 → 通知** 中，每种通知都有自己的开关：智能体**在等你**（附带它在问什么）、智能体**已完成**、触及**用量上限**，以及 NeuroSquad 为让智能体继续工作而**跳过的智能体 CLI 更新**（何时更新由你决定）。 **发送测试通知** 会立即显示一条通知。如果系统不显示通知——例如 Windows 为所有应用关闭了通知（设置 → 系统 → 通知）——NeuroSquad 会在那里提示你，并改为在自己窗口的右下角显示通知；**系统通知设置** 会打开可以重新开启通知的位置。Windows 的专注助手 / 请勿打扰也可能拦下通知。 ### 智能体 CLI 的更新不会打断智能体 有些智能体 CLI 会在启动时自动更新，有些会先询问（“立即更新 / 跳过”）——这会让卡片卡住，你和主导智能体都无法输入。在 NeuroSquad 卡片中这项功能已关闭（仅限 NeuroSquad 自己的卡片——你自己终端里的 CLI 保持原有设置），如果仍然弹出询问，会自动选择 **跳过**。有新版本发布时，NeuroSquad 每个版本只通知你一次，并附上在终端中更新的命令——何时更新由你决定。 --- ## 给智能体分配任务 > 把看板上的任务分配给特定的智能体，并让它们自行领取下一个任务。 Source: https://docs.neurosquad.ai/zh/agents/tasks 你随时都可以直接给智能体输入提示词。但对于需要多个智能体协作的大型工作，请改用[任务看板](https://docs.neurosquad.ai/zh/cards/kanban)——每个任务只有一个负责人，**Start** 只会把任务发给那个智能体： **1. 把任务放到看板上** 添加一个任务看板，每行添加一个任务——或者让主导智能体把工作拆解到看板上。 **2. 分配每个任务** 在任务上按 **Assign** 并选择智能体。只有该智能体会收到这个任务，其他智能体无法领取或移动它。**New agent for this task** 可一键为该任务创建一个新的智能体。 **3. 按 Start** 任务会作为提示词发送给对应的智能体，并移到 **Doing**。智能体完成后，把它移到 **Review** 或 **Done**。 ### 让它自动运转 - **Depends on**——任务会处于 **Blocked** 状态，直到它所依赖的任务都变为 **Done**。 - **Auto-dispatch**（看板标题栏中的闪电按钮）——智能体完成本轮工作时，它的任务会移到 **Review**，并自动发送它下一个就绪的任务。 - **Give unassigned tasks to any idle connected agent**——未分配的任务会交给任何空闲的智能体。 在自动运转的看板旁放一张[预算卡片](https://docs.neurosquad.ai/zh/cards/budget)，这样你不在时它也不会超支。 ### 在一处查看所有任务 侧边栏的 **Tasks** 部分汇集了你所有工作区中每个任务看板和待办清单里的任务。 --- ## 提示词队列与每日提示词 > 为忙碌的智能体排好接下来的提示词，或每天发送同一条提示词。 Source: https://docs.neurosquad.ai/zh/agents/queue ### 提示词队列 智能体还在忙，你已经想好了下一个任务？把它放进队列。 **1. 在智能体卡片的 ⋯ 菜单中打开 Queue** 输入消息并按 **Add to queue**。想加多少就加多少，用箭头调整顺序，点击某一条即可编辑。 **2. 继续忙你自己的事** 智能体一完成本轮工作，下一条消息就会自动发送——每轮一条。 关闭工作区或应用后，队列依然保留。如果智能体没有在运行，消息会一直等待。 ### 每日提示词 智能体卡片 ⋯ 菜单中的 **Schedule** 会在每天的固定时间向该智能体发送一条提示词——例如“每天早上 9 点检查新的 issue”。每条定时提示词都有自己的开关。 --- ## 角色 > 一键给智能体一份工作说明——评审者、测试者、研究者等。 Source: https://docs.neurosquad.ai/zh/agents/roles **角色**告诉智能体它负责哪类工作。NeuroSquad 内置了现成的角色——**Reviewer**、**Tester**、**Researcher**、**Architect**、**Writer**——也可以选择 **Custom**，用你自己的话描述角色。 ### 分配角色 - **创建智能体时**——在 **New agent** 对话框中选择一个角色。它会作为第一条提示词输入到新智能体中；在其终端里按 Enter 即可发送。 - **给已在运行的智能体**——在它的 ⋯ 菜单中选择 **Role**，选好后按 **Send role**。 角色只发送一次，就是一条你能看到的普通提示词。NeuroSquad 绝不会在背后修改或重新发送它。卡片会在智能体名称旁显示其角色。 **适用场景**：每个智能体各司其职的小队——一个写代码，一个测试，一个评审。 --- ## 长时间会话 > 关注上下文、压缩上下文、在用量上限后自动继续、交接给新的智能体，以及记录工作日志。 Source: https://docs.neurosquad.ai/zh/agents/long-sessions 连续工作数小时的智能体会碰到限制：它的记忆（即**上下文**）会被填满，你套餐的**用量上限**也会耗尽。NeuroSquad 能帮你应对这两种情况。 ### 上下文指示器与 Compact 智能体卡片标题栏中的小圆环显示上下文的占用程度，超过 80% 会变成琥珀色。点击它可以查看 token 明细，并且可以： - **Compact**——让智能体总结到目前为止的对话，并基于总结继续工作。 - 或者**交接**给一个新的智能体（见下文）。 ### 用量上限后自动继续 当智能体因“已达用量上限”的提示而停下时，标题栏会显示距离额度重置的倒计时。 打开 **Auto-resume after a usage limit**（在该标签的弹出框中，或在卡片的 ⋯ 菜单中），NeuroSquad 就会在那个时间向智能体发送“continue”——这样通宵任务可以自己接着跑。 **Resume now** 和 **Dismiss** 也在同一处。 ### 交接给新的智能体 ⋯ 菜单中的 **Hand off to a new agent…** 会在当前智能体旁边启动一个新的智能体，位于同一文件夹，可以使用任意你喜欢的智能体程序。它会带上到目前为止的工作总结——按 **Ask the agent to write it** 让智能体来写，或者自己编写和修改。总结只会被输入到新智能体中而不会发送，你可以先检查，再按 Enter。 ### 工作日志 在 ⋯ 菜单中打开 **Journal to linked note**，每个完成的回答都会被追加到相连的[笔记卡片](https://docs.neurosquad.ai/zh/cards/note)中——形成一份智能体工作的持续记录。 > 上下文指示器、Compact 和工作日志适用于 Claude Code、OpenCode、Kilo Code 和 Hermes Agent。 --- ## 统一的指令文件 > 在 AGENTS.md 中写一次项目指令，所有智能体都能读到。 Source: https://docs.neurosquad.ai/zh/agents/instructions 不同的智能体程序从不同的文件读取项目指令：Codex 等许多程序读取 `AGENTS.md`，Claude Code 读取 `CLAUDE.md`，Qwen Code 读取 `QWEN.md`，Gemini 读取 `GEMINI.md`。 手动让它们保持同步非常繁琐。 NeuroSquad 让你只维护**一个**文件——`AGENTS.md`——并把它镜像到 `CLAUDE.md`、`GEMINI.md` 和 `QWEN.md`。 **1. 打开工作区的编辑对话框** **Instructions file** 部分列出每个文件及其状态：**Missing**、**In sync** 或 **Differs**。 **2. 勾选要镜像的文件** 选择 **Copy**（完整副本）或 **@import**（一个指向 `AGENTS.md` 的简短文件），然后按 **Write**。 如果某个文件已有不同内容，NeuroSquad 绝不会悄悄覆盖它：**Review…** 会准确展示将要改动的内容，只有点击 **Overwrite** 才会替换。 还没有 `AGENTS.md`？可以用 **Create AGENTS.md from** 从现有文件（例如你的 `CLAUDE.md`）创建。 --- ## 隔离的工作树 > 给智能体一份独立的项目副本，让多个智能体互不干扰对方的修改——并添加一个使用不同 AI 的评审者。 Source: https://docs.neurosquad.ai/zh/agents/worktrees 当多个智能体在同一个文件夹中工作时，它们可能会覆盖彼此的修改。**隔离**的智能体会在自己的分支上获得一份独立的项目副本（git 工作树，即 worktree），因此它可以随意修改，而不会打扰你或其他智能体。 ### 开启 在侧边栏工作区下方的添加行中，先打开 **Isolate in git worktree**（叠放方块图标的按钮），再添加智能体。副本准备期间卡片会显示 **Preparing**，之后智能体启动。 > 你的项目必须是一个 git 仓库。如果你还没有安装 Git，安装向导可以帮你安装。 ### 自动准备好副本 新的副本里既没有已安装的依赖，也没有你的私有文件。在工作区的编辑对话框中，你可以设置： - **Setup command for isolated agents**——在每个新副本中、智能体启动之前运行一次，例如 `npm install`。运行时输出会显示在卡片中。 - **Files to copy into a new worktree**——git 不跟踪但智能体需要的文件，例如 `.env`。 - **Run command**——从智能体卡片启动你的项目（其 ⋯ 菜单中的 **Run this project**）；一旦项目打印出本地地址，就会打开一张指向你应用的浏览器卡片。 ### 添加评审者 当工作看起来已经完成时，在智能体的 ⋯ 菜单中选择 **Add a reviewer**。第二个智能体会在同一个工作树中启动——如果你装有其他 AI，就会使用**不同的 AI**——并有一条从作者指向它的箭头，它被要求阅读改动且**不做任何编辑**。 ### 把成果合并回来 智能体的修改保存在它自己的分支上。满意之后，可以在[终端卡片](https://docs.neurosquad.ai/zh/cards/terminal)中合并该分支——或者直接让智能体提交并合并它的工作。 --- ## 危险模式 > 让智能体无需停下来请求许可就能工作——以及什么时候不该这样做。 Source: https://docs.neurosquad.ai/zh/agents/dangerous-mode 通常，智能体在执行有风险的操作——运行命令、编辑文件——之前会先询问你。 **危险模式**会关闭这些询问，让智能体不间断地工作。 ### 开启 打开智能体卡片的 ⋯ 菜单，选择 **Enable dangerous mode**。卡片标题栏会出现一个琥珀色三角。此设置按卡片生效——绝不会一次作用于所有智能体。在同一位置选择 **Disable dangerous mode** 即可关闭。 - **Claude Code** 会立即切换，开关皆然：下一次审批就按新设置处理——无需重启，对话不变。 - **其他智能体** 在启动时读取该模式。NeuroSquad 会提供 **立即重启**：智能体重启后继续同一段对话。选择 **稍后** 则在下次启动时生效。 > 在危险模式下，智能体可以不经询问就删除文件、运行任何命令。请只在已备份的项目上使用，最好同时配合[隔离的工作树](https://docs.neurosquad.ai/zh/agents/worktrees)和[预算](https://docs.neurosquad.ai/zh/cards/budget)。 Pi 不提供此模式——它运行工具前本来就不会询问。普通终端也不需要它。 --- ## 智能体卡片详解 > 智能体卡片的标题栏及其 ⋯ 菜单，逐项说明。 Source: https://docs.neurosquad.ai/zh/agents/card-menu 标题栏展示的是你隔着整张画布就需要看到的信息：这是谁、它在做什么，以及任何会改变其行为的长期状态。你要对智能体*执行*的一切操作都在 **⋯** 菜单里。 先把鼠标指向那几个点，再打开菜单： ### 标题栏 - **图标**: 智能体自己的图标，工作时外圈会转动。 - **名称**: 根据智能体正在做的事自动填写。点击即可输入你自己的名称——你起的名字始终优先。 - **角色或会话标题**: 名称后的小字：智能体的[角色](https://docs.neurosquad.ai/zh/agents/roles)，或它正在忙的事情。 - **状态**: **Working**、**Needs input**、**Done**、**Exited**、**Crashed**……空闲时什么都不显示。参见[已完成 / 需要你的输入](https://docs.neurosquad.ai/zh/agents/notifications)。 - **用量上限与上下文**: 当智能体因用量上限而停下时显示倒计时，以及上下文指示器。参见[长时间会话](https://docs.neurosquad.ai/zh/agents/long-sessions)。 - **模型**: 当智能体运行在你选定的模型上时，显示该模型的标签。参见 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter)。 - **标记**: 琥珀色三角表示[危险模式](https://docs.neurosquad.ai/zh/agents/dangerous-mode)，绿色边框表示[画布模式](https://docs.neurosquad.ai/zh/squads/canvas-mode)。 - **展开与 ⋯**: 让卡片铺满画布；打开菜单。 AI 智能体的卡片顶部还坐着一个小[吉祥物](https://docs.neurosquad.ai/zh/canvas/tools#agent-mascots)，实时反映它的状态。 ### ⋯ 菜单 - **会话**: **Restart session**（开启一段全新对话，卡片位置不变）、**Pop out to new window**、**Minimize**，以及当工作区设置了运行命令时出现的 **Run this project**（参见[隔离的工作树](https://docs.neurosquad.ai/zh/agents/worktrees)）。 - **智能体**: **Provider and model**、**Enable dangerous mode**、**Enable canvas mode**、**Role**、**Journal to linked note**、**Auto-resume after a usage limit**、**Hand off to a new agent…**、**Clone agent** 和 **Add a reviewer**。 - **提示词**: **Queue** 和 **Schedule**——参见[提示词队列与每日提示词](https://docs.neurosquad.ai/zh/agents/queue)。 - **整理**: **Color tag**、私人 **Notes**（可以用语音输入）、**Issue/PR link**，以及钉在输出中特定位置的 **Annotations**。 - **对话记录**: **Copy transcript**、**Export transcript**、**Export as HTML**、**Open last mentioned file**、**Save snapshot** 以及你的 **Snapshots**。 - **删除智能体**: 最后一行，单独放置。删除前会先询问——而且绝不会动你的文件。 ### 在终端中 - 右键可使用 **Copy**、**Paste** 和 **Select all**。 - `Ctrl F` 在输出中搜索。 - `Ctrl` + 滚轮调整文字大小。 - 从资源管理器（Mac 上是访达）把文件拖到卡片上，即可把文件路径输入到提示词中。 ### 如果智能体崩溃 NeuroSquad 会自动重启它几次（设置 → General 中的 **Auto-reconnect**）。如果仍然无法恢复，卡片上会出现 **Reconnect** 按钮，侧边栏 **Features** 下的 **Crash log** 会记录发生了什么。 ### 模板 把常用的智能体配置——智能体类型、颜色、起始提示词——保存为**模板**（侧边栏中的 **Features → Templates**）。之后你的模板会出现在添加菜单的底部。 --- ## 全部卡片 > 你可以放到画布上的每一种卡片，以及它们各自的用途。 Source: https://docs.neurosquad.ai/zh/cards 除了智能体，画布上还能放许多其他卡片。任何一种都可以从添加菜单中添加。大多数卡片在你用[箭头](https://docs.neurosquad.ai/zh/canvas/arrows) 把智能体连接到它们之后会更加有用。下面是每张卡片缩小后的样子： ### 工作 - **[终端](https://docs.neurosquad.ai/zh/cards/terminal)**: 真实的 shell——供你使用，也可供智能体在其中运行命令。 - **[浏览器](https://docs.neurosquad.ai/zh/cards/browser)**: 智能体可以看见并点击操作的真实浏览器。 - **[笔记](https://docs.neurosquad.ai/zh/cards/note)**: Markdown 共享笔记——你和智能体共用。 - **[待办清单](https://docs.neurosquad.ai/zh/cards/todo)**: 你和智能体一起勾选的清单。 - **[任务看板](https://docs.neurosquad.ai/zh/cards/kanban)**: 把任务分配给智能体，让它们自动领取下一个。 - **[便签](https://docs.neurosquad.ai/zh/cards/sticky)**: 用醒目的标题来组织画布。 - **[专注计时器](https://docs.neurosquad.ai/zh/cards/flow-timer)**: 专注时段内暂缓非紧急提醒。 - **[参考资料](https://docs.neurosquad.ai/zh/cards/reference)**: 供智能体使用的链接、图片、PDF 和文件夹。 - **[开发服务器](https://docs.neurosquad.ai/zh/cards/dev-servers)**: 正在运行的开发服务器，一键在浏览器卡片中打开。 ### 监控 - **[预算](https://docs.neurosquad.ai/zh/cards/budget)**: 整个工作区的 token 上限。 - **[网页监视](https://docs.neurosquad.ai/zh/cards/web-watch)**: 网页发生变化时通知你的智能体。 - **[站会](https://docs.neurosquad.ai/zh/cards/standup)**: 每个智能体今天做了什么。 ### 集成 - **[Telegram 机器人](https://docs.neurosquad.ai/zh/integrations/telegram)**: 在 Telegram 中与你的智能体对话。 --- ## 终端卡片 > 画布上的真实 shell——供你使用，也可供智能体在其中运行命令。 Source: https://docs.neurosquad.ai/zh/cards/terminal **终端卡片**是在你项目文件夹中打开的普通 shell：Windows PowerShell、PowerShell 7、命令提示符、Bash（Git Bash） 或系统默认 shell。在添加菜单的 **Terminals** 下选择一个即可。 ### 自己使用 像在任何终端中一样输入命令。右键可使用 Copy / Paste / Select all，按 `Ctrl F` 搜索，按住 `Ctrl` 滚动可调整文字大小。 ### 让智能体使用 从智能体向终端画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。智能体就会在**这里**运行命令，让你看得见，而不是藏在它自己的窗口里。 长时间运行的任务——开发服务器、测试监听——最好各自使用一张终端卡片。 **适用场景**：启动你的应用、运行测试、在智能体工作时查看日志。 --- ## 浏览器卡片 > 画布上的真实浏览器，智能体可以看见并使用它。 Source: https://docs.neurosquad.ai/zh/cards/browser **浏览器卡片**是卡片里的一个真实浏览器，带有后退、前进、刷新按钮和地址栏。你可以自己在里面浏览—— 通过[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)连接的智能体也能打开网页、点击、输入，并读取屏幕上的内容。 > 首次使用时，NeuroSquad 会下载一个专用浏览器（默认是 Chrome，约 200 MB），它与你日常使用的浏览器相互独立。 > 下载完成后卡片会自动启动。你可以在 **Settings → Browser** 中切换为 Firefox。 你在浏览器卡片中登录过的网站会被记住，因此只需登录一次，之后就可以让智能体在那里工作。 **适用场景**：检查智能体刚修改过的应用、复现 bug、填写网页表单、做调研。 --- ## 笔记卡片 > Markdown 共享笔记——你和智能体共用。 Source: https://docs.neurosquad.ai/zh/cards/note **笔记卡片**存放 Markdown 文本：标题、列表、表格、代码。空笔记会直接进入编辑状态；有内容的笔记会显示排版后的文本—— 点击即可编辑，按 `Esc` 结束编辑。 用[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)连接一个智能体，它也能读写这篇笔记。卡片会显示最新版本是谁写的。 **适用场景**：智能体边工作边记录的发现日志、希望多个智能体共享的说明、当前任务的草稿本。 --- ## 待办清单卡片 > 你和智能体一起保持更新的清单。 Source: https://docs.neurosquad.ai/zh/cards/todo 一份你和智能体共用的**待办清单**。每个任务都有一个状态圆点： | 圆点 | 含义 | | --- | --- | | 灰色圆环 | 未开始 | | 旋转圆环 | 进行中 | | 绿色圆点 | 已完成 | | 红色圆点 | 失败 | - 在底部那一行**添加**任务。 - **点击圆点**，把任务切换到下一个状态。 - **点击文字**进行编辑。 用[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)连接一个智能体，它就会把计划写在这里，并边做边勾选——让你一眼看清进度。清单的数量不限。 --- ## 任务看板卡片 > 为你的小队准备的看板——把每个任务分配给一个智能体，让下一个任务自动开始。 Source: https://docs.neurosquad.ai/zh/cards/kanban **任务看板**有四列：**To do**、**Doing**、**Review** 和 **Done**。你可以自己添加任务并在各列之间移动，也可以交给智能体来做。 ### 把任务交给指定的智能体 - **Assign**——选择负责这个任务的智能体。只有这个智能体会收到它；其他智能体无法移动或删除它。 - **Start**——把任务发送给对应的智能体，并将其移到 **Doing**。 - **New agent for this task**（在同一列表中）——一键为这个任务创建一个新的智能体。 ### 依赖其他任务的任务 **Depends on** 让你勾选必须先处于 **Done** 状态的任务。在此之前，该任务会被标记为 **Blocked**，并显示它在等待什么。 ### 自动派发 打开 **Auto-dispatch**（看板标题栏中的闪电按钮），看板就会自动运转：智能体完成一轮后，它的任务会移到 **Review**， 下一个就绪的任务会自动发送给它。打开 **Give unassigned tasks to any idle connected agent** 后，未分配的任务会交给任意一个空闲的已连接智能体。 通过[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)连接的智能体也可以添加任务并推进自己的任务。完整说明请参见[给智能体分派任务](https://docs.neurosquad.ai/zh/agents/tasks)。 **适用场景**：小队处理一长串待办事项，而你想一眼看清谁在做什么。 --- ## 便签卡片 > 用醒目的标题和标签来组织和说明你的画布。 Source: https://docs.neurosquad.ai/zh/cards/sticky **便签**是一个醒目的大号标签：一个标题加一个可选的副标题，有六种颜色可选。双击即可书写。 用便签把大画布划分成若干章节——“Build”“Marketing”“Watching”——或者给下一个打开这个工作区的人留言。 它们在[演示模式](https://docs.neurosquad.ai/zh/canvas/tools#present-your-canvas)中效果尤其好。 --- ## 专注计时器卡片 > 一个专注计时器，在专注时段结束前暂缓智能体的“已完成”提醒。 Source: https://docs.neurosquad.ai/zh/cards/flow-timer 智能体一个接一个地完成任务，很容易让人无法集中注意力。**专注计时器**为你提供一个专注时段——**25 / 5**、 **50 / 10** 或自定义分钟数——并在运行期间减少打扰。 - 按 **Start focus**。卡片会显示剩余时间以及时段结束的时间。 - 打开 **Hold agent pings while focusing** 后，“已完成”通知会等到时段结束再发出。 “需要你输入”的通知则始终会送达——被卡住的智能体不应该因为疏忽而一直等你。 - 时段结束时，**While you focused** 会用一个列表展示期间发生的事情。 卡片还会统计你今天完成了多少个专注时段。 --- ## 参考资料卡片 > 希望智能体随时参考的链接、图片、PDF 和文件夹。 Source: https://docs.neurosquad.ai/zh/cards/reference **参考资料卡片**是为智能体准备的资料板：网页链接、图片、PDF、文档，或整个文件夹。 - **Add a link**——粘贴链接后按 Enter。 - **Add files**，或者直接把文件拖到卡片上；用 **Reference a folder** 指向一个文件夹，而不是复制它。 - 点击某一项即可 **Open**。 每个通过[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)连接的智能体都能看到卡片上的内容，并在需要时读取——这样你就不必在每条提示词里重复粘贴同样的设计稿或需求文档。 **适用场景**：设计稿、产品需求文档、品牌规范、API 文档。 --- ## 开发服务器卡片 > 列出你电脑上正在运行的所有开发服务器——一键在浏览器卡片中打开。 Source: https://docs.neurosquad.ai/zh/cards/dev-servers 智能体很喜欢启动开发服务器——然后你只能去猜它用的是哪个端口。**开发服务器卡片**会列出你电脑上正在运行的每一个， 每隔几秒更新一次。 - **Open in a browser card**——一键即可在该地址上打开一张[浏览器卡片](https://docs.neurosquad.ai/zh/cards/browser)。 - **Copy URL**，或者用完后 **Stop process**。（系统进程和 NeuroSquad 本身无法在这里停止。） - 如果想看到开发服务器以外的更多内容，可以打开 **Show every listening port**。 连接的智能体也可以向这张卡片询问哪些服务器正在运行。 **适用场景**：多个智能体同时开发一个 Web 项目时，随时掌握哪些服务在运行。 --- ## 预算卡片 > 为整个工作区设置 token 上限，超出时暂停其中的智能体。 Source: https://docs.neurosquad.ai/zh/cards/budget **预算卡片**显示本工作区所有智能体已使用的 token 数量，按智能体细分，并与你设定的上限进行对比。 - **Set limit**——选择一个 token 上限（250K、1M、5M、20M 或自定义）。接近上限时，圆环会变成琥珀色——**Near limit**。 - **超出上限时**，工作区会被暂停：每个智能体都会被中断（不是关闭——对话会保留），自动提示词——队列、每日提示词、 看板上的任务、其他智能体发来的消息——全部停止。 - **你自己手动输入仍然可以**——预算只会停止自动的部分。 - **要继续**，按 **Resume**，或者用 **Raise limit** 把上限提高到已花费的数额之上。 token 数量与[用量与费用](https://docs.neurosquad.ai/zh/usage)来自同一数据源，因此 NeuroSquad 能读取用量的每个智能体都会被计入。 **适用场景**：让小队通宵运行，又不会收到意外的账单。 --- ## 网页监视卡片 > 监视一个网页，在它发生变化时通知你的智能体。 Source: https://docs.neurosquad.ai/zh/cards/web-watch **网页监视卡片**按计划检查某个网页，并在它发生变化时发现变化——更新日志、价格、状态页、竞争对手的定价。 **1. 输入网页地址** 粘贴地址，并选择检查频率。 **2. 选择比较范围** **Whole page**（整个页面）、仅比较两个短语 **Between**（之间）的部分（例如“Latest release”与“Older releases”之间）， 或者某个模式的匹配结果。 **3. 开始监视** 第一次检查作为基准。此后每次变化都会被记录下来，包括新增和删除的内容。 打开 **Tell connected agents when it changes** 后，每个通过[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)连接的智能体都会收到一条关于变化的消息—— 这样智能体就能自行响应：比如为新版本的库更新文档，或者给你写一份摘要。 **Check now**、**Pause** 和 **Resume** 随时可用。卡片读取的是服务器返回的页面内容，因此页面上由脚本后续渲染的文字不会被看到。 --- ## 站会卡片 > 每日摘要，汇总工作区中每个智能体今天做了什么。 Source: https://docs.neurosquad.ai/zh/cards/standup **站会卡片**回答“今天大家都做了什么？”这个问题。对于工作区中的每个智能体，它会显示： - 进行了多少轮、工作了多长时间， - 改动了哪些文件、用了多少 token， - 最后一次收到了什么请求，最后一次回答了什么。 用 **Copy as Markdown** 把摘要粘贴到聊天中，或用 **Send to note** 把它放进已连接的[笔记卡片](https://docs.neurosquad.ai/zh/cards/note)。 Claude Code、OpenCode、Kilo Code 和 Hermes Agent 智能体的记录是完整的。对于其他智能体，卡片只显示 NeuroSquad 启动以来发生的事情。 --- ## 什么是智能体小队 > 多个智能体在同一张画布上协同工作，由箭头相连。 Source: https://docs.neurosquad.ai/zh/squads **智能体小队**是一组协同工作的智能体。一个智能体可以担任主导并分派工作，其他智能体负责各个部分，浏览器、终端和笔记把它们全部连接起来。只需添加卡片并绘制[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)，就能组建一支小队。助手智能体不必和主导智能体使用同一种 AI： 分配工作有两种方式——让主导智能体通过箭头分派，或者把任务放到[任务看板](https://docs.neurosquad.ai/zh/cards/kanban)上，并把每个任务交给特定的智能体： - **[负责分派任务的主导智能体](https://docs.neurosquad.ai/zh/squads/lead-agent)**: 一个智能体把任务交给其他智能体，并汇总结果。 - **[分配给特定智能体的任务](https://docs.neurosquad.ai/zh/agents/tasks)**: 任务看板上的分配、启动、依赖与自动派发。 - **[画布模式](https://docs.neurosquad.ai/zh/squads/canvas-mode)**: 智能体自己创建所需的卡片。 - **[小队配方](https://docs.neurosquad.ai/zh/squads/recipes)**: 可直接照搬的现成配置。 ### “团队”看板 每个工作区都有一张 **“团队”** 卡片：把其中所有 AI 智能体放在一个看板上——谁在等你、谁在工作以及工作了多久、谁已完成——并显示每个智能体的类型和模型。点击某一行，镜头就会飞到该智能体。 顶部栏的 **“团队”** 按钮会把同一个看板作为**右侧边栏**打开，显示当前打开的工作区；切换工作区时它保持不动，即使你删除了卡片也一样。拖动边缘可调整宽度。看板在侧边栏中时，画布上的卡片只会提示这一点（看板不会显示两次）；**“移回画布”** 会把它放回去——如果卡片被删除，也会重新创建。 --- ## 负责分派任务的主导智能体 > 让一个智能体把任务交给其他智能体，并收集它们的回答。 Source: https://docs.neurosquad.ai/zh/squads/lead-agent **从**一个智能体**向**另一个智能体画一条箭头。前者成为**主导智能体**，后者成为它的**助手智能体**。现在，主导智能体可以给助手发送任务、等待其完成，并读取回答。 **1. 添加两个智能体** 例如，用 Claude Code 作主导，Codex 作助手。它们可以是不同的 AI。 **2. 从主导智能体向助手智能体画箭头** 方向很重要：箭头从分派工作的一方指向执行工作的一方。 **3. 告诉主导智能体你想要什么** “*修复结账流程的 bug。你修复的同时，让助手为它编写测试。*”每当主导智能体与助手通信时，箭头就会亮起，你还可以在助手自己的卡片里看着它工作。 一个主导智能体可以有多个助手，助手也可以再主导自己的助手。 > 主导智能体必须是 Claude Code、OpenCode、Kilo Code、Hermes Agent、Codex CLI 或 Qwen Code——也就是[箭头能赋予能力](https://docs.neurosquad.ai/zh/canvas/arrows)的智能体。助手可以是任何智能体。 ### 让主导者自己组建团队 主导者也可以自己创建助手，并为每个助手选择运行方式。比如对它说：*“按四名开发者的团队规划这个项目：为每人选好工具和模型，然后创建他们。”* 主导者会： - 看到**这台电脑上已安装**的智能体——你没有安装的，它无法创建； - 看到每个智能体**自带的模型**（例如 Claude Code 的 `opus` 或 `sonnet`），以及——如果你连接了 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter)——可以使用 OpenRouter 模型，并附带价格和上下文大小；它永远看不到你的密钥； - 为每个助手指定工具、模型、角色和第一个任务，并直接用箭头连到自己。 助手的模型会显示在它的卡片和“团队”看板上。在助手未运行时，主导者可以更改它所创建助手的模型。 ### 把需要的卡片交给助手 助手只能看到连接到**它自己**卡片上的卡片——而不是主导者的。所以当主导者分派需要某张卡片的工作（写着任务说明的笔记、终端、浏览器、任务看板）时，它会自己把助手连到那张卡片：可以直接创建一个已连好你笔记的助手，也可以在工作进行中从现有助手画一条箭头过去。新箭头会出现在画布上，短暂显示是谁画的，并保存在[箭头日志](https://docs.neurosquad.ai/zh/canvas/arrows#arrow-log)里。已经在运行的助手会立即获得新能力。 主导者能连接什么是有意限制的，因为箭头会赋予能力： - 只能是**同一工作区**的卡片； - 未开启[画布模式](https://docs.neurosquad.ai/zh/squads/canvas-mode)时，箭头的一端必须是主导者自己或它创建的卡片；开启画布模式后，任意两张卡片都可以； - **你**自己设置的**终端**、**浏览器**、MCP 服务器、Telegram 或自定义卡片，只有在你先把它连到主导者之后才能被转交——主导者无法自行接触你的终端； - 助手不能反过来指挥自己的主导者，也不能剪断主导者联系它的那条箭头； - 工作区[预算](https://docs.neurosquad.ai/zh/cards/budget)暂停时不能连线；每个智能体每分钟最多改动 30 条箭头。 主导者无法以此删除卡片——移除箭头后，两张卡片都会留在原处。 --- ## 卡片模式 > 智能体通过卡片工作——它会自己打开终端、浏览器、笔记和助手智能体。 Source: https://docs.neurosquad.ai/zh/squads/canvas-mode 通常由你来设置卡片和箭头。在**卡片模式**下，智能体会自己动手：它通过画布上的卡片工作，而不是藏在自己的窗口里。 完整的分步演示以及这种工作方式带来的好处，见 [neurosquad.ai/zh/canvas-mode](https://neurosquad.ai/zh/canvas-mode/)。 - 它会为命令打开**终端卡片**——每个长时间运行的进程一张。 - 需要上网时，它会打开**浏览器卡片**。 - 它会把日志记在**笔记卡片**里。 - 对于可以并行的工作，它会创建**助手智能体**。 - 它会把**助手连到**任务所需的卡片——你的笔记、终端、浏览器、任务看板——因为助手只能看到连到它自己卡片上的卡片。在卡片模式下，它可以连接工作区中任意两张卡片（[它能连接什么](https://docs.neurosquad.ai/zh/squads/lead-agent#give-helpers-cards)）。 它所做的一切都摆在画布上，一目了然。处于卡片模式的卡片带有淡淡的绿色光晕。 ### 开启 智能体卡片菜单 → **启用卡片模式**。凡是能使用 NeuroSquad 卡片工具的 AI CLI 都有这一项——全部 19 个：Claude Code、Codex CLI、OpenCode、Kilo Code、Hermes Agent、Qwen Code、Gemini CLI、GitHub Copilot CLI、Factory Droid、Amp、Auggie、Cursor CLI、Cline CLI、Goose、Kimi Code、Crush、aider、Pi 和 omp。 卡片工具和说明会立即切换，即使智能体正在运行。此外，NeuroSquad 还会收走 CLI **自带**的 shell 和网页工具，让智能体真正去用卡片。每个 CLI 的做法各不相同： | CLI | 如何切断它自带的 shell 和网页 | 危险模式下是否仍然有效 | 生效时间 | | --- | --- | --- | --- | | Claude Code | 启动时禁用 `Bash`、`WebSearch`、`WebFetch`；危险模式不会批准它们 | 是 | 下次启动 | | Codex CLI | 关闭 shell 工具和网页搜索——不再提供给模型 | 是 | 下次启动 | | OpenCode、Kilo Code | 在卡片的配置中拒绝 `bash`、`webfetch`、`websearch` | 是 | 下次启动 | | Hermes Agent | 禁用 `terminal`、`code_execution`、`web`、`search` 和 `browser` 工具集 | 是 | 下次启动 | | Qwen Code | 禁用并拒绝 `run_shell_command`、`monitor`、`web_fetch`、`web_search` | 是 | 下次启动 | | Gemini CLI | 排除 `run_shell_command`、后台进程工具、`web_fetch`、`google_web_search` | 是 | 下次启动 | | GitHub Copilot CLI | 排除 bash/PowerShell 工具、`web_fetch` 和 `web_search`，并拒绝 shell | 是 | 下次启动 | | Factory Droid | 由钩子拒绝 `Execute`、`Script`、`WebSearch`、`FetchUrl` | 是 | 下次启动 | | Amp | NeuroSquad 插件在每次调用时拒绝它的 shell 工具、`web_search` 和 `read_web_page` | 是 | 下次启动 | | Auggie | 移除进程类工具、`web-fetch` 和 `web-search` | 是 | 下次启动 | | Cursor CLI | 由钩子拒绝 `Shell`、`WebFetch`、`WebSearch`——每次调用时读取卡片的当前状态 | 是 | 立即 | | Cline CLI | NeuroSquad 插件移除并拒绝 `run_commands`、`fetch_web_content`、`web_search` | 是 | 下次启动 | | Goose | `developer` 扩展只保留文件工具（没有 `shell`）；`code_execution` 和 `computercontroller` 不提供任何工具 | 是¹ | 下次启动 | | Kimi Code | 禁用 `Bash`、`WebSearch`、`FetchURL`，另有钩子拦截 | 是 | 下次启动 | | Crush | 禁用 `bash`、后台任务工具、`download`、`fetch`、`agentic_fetch`、`sourcegraph` | 是 | 下次启动 | | aider | 不再建议 shell 命令，也不再抓取聊天中的 URL² | 是 | 下次启动 | | Pi | 排除 `bash` 和 `powershell`；Pi 本身没有网页工具 | 是 | 下次启动 | | omp | 拦截 `bash`、`eval`、`web_search` 和 URL 读取，并对模型隐藏 | 是 | 下次启动 | ¹ Goose 的扩展管理器仍然保留，所以刻意为之的模型可以启用其他扩展。² `/run` 和 `/web` 仍可由你自己输入。 “下次启动”指卡片重新启动时 CLI 才会应用；在此之前，正在运行的会话保留原有工具。危险模式会跳过审批提示，但不会把卡片模式收走的工具还回去。 > 卡片模式不是沙盒。智能体仍然用自己的工具读取和编辑项目文件，它在终端卡片里运行的是你电脑上真实的命令。 --- ## 小队配方 > 可以直接照搬到画布上的现成小队配置。 Source: https://docs.neurosquad.ai/zh/squads/recipes ### 开发者与测试者 **卡片**：一个智能体、一个运行开发服务器的终端、一个浏览器。 **箭头**：智能体 → 终端，智能体 → 浏览器。 提问：“*添加一个订阅新闻通讯的表单，然后在浏览器中打开页面，检查它是否正常工作。*” 智能体会修改代码，在浏览器中查看结果，并修复出问题的地方。 ### 主导者与助手 **卡片**：一个主导智能体、两个助手智能体、一个[任务看板](https://docs.neurosquad.ai/zh/cards/kanban)。 **箭头**：主导 → 每个助手，三者都 → 任务看板。 让主导智能体把工作拆分成看板上的任务并分派出去。你可以看着任务从 **To do** 移到 **Done**。 ### 作者与评审者 **卡片**：一个[隔离的](https://docs.neurosquad.ai/zh/agents/worktrees)智能体。 然后在智能体的菜单中选择 **Add a reviewer**——第二个使用不同 AI 的智能体会阅读改动，但不做任何编辑。你阅读两者的输出，把意见反馈给作者，然后合并它的分支。 ### 夜班 **卡片**：一个[隔离的](https://docs.neurosquad.ai/zh/agents/worktrees)智能体、一张[预算](https://docs.neurosquad.ai/zh/cards/budget)卡片。 智能体菜单中的 **Schedule** 会在夜里启动工作，预算确保它不会超支；而且由于智能体在自己的分支上工作，早上你可以合并满意的部分，丢弃不想要的部分。 --- ## 手机上的智能体 > 在手机上查看和操控 NeuroSquad——无论在家还是在外。 Source: https://docs.neurosquad.ai/zh/remote 启动了一个耗时很长的任务，然后走开了？**远程访问**让你在手机上打开 NeuroSquad：查看哪些智能体正在工作或在等待，阅读它们的屏幕，发送提示词，并在有智能体需要你时听到提示音。 所有工作都由你的电脑完成——手机只是一扇看向电脑的窗口。无需应用商店，手机上也无需登录：扫描二维码，再把页面添加到主屏幕即可。 - **[配对手机](https://docs.neurosquad.ai/zh/remote/pairing)**: 打开远程访问并扫码——需在同一个 Wi-Fi 下。 - **[不在家时](https://docs.neurosquad.ai/zh/remote/internet)**: 通过 Cloudflare 经互联网访问你的电脑。 - **[在手机上能做什么](https://docs.neurosquad.ai/zh/remote/on-the-phone)**: 工作区、卡片、提示词和提醒。 ### 有人连接时，你总会知道 只要有手机连接着，NeuroSquad 窗口顶部就会出现一条**绿色横条**：“iPhone is connected remotely on your network”。它无法关闭——远程访问能做窗口能做的一切，所以你永远不必特意去找。顶栏中的 **Remote access** 按钮会列出已连接的设备，并可关闭远程访问。 > 任何拿到你配对链接的人都能读取你的终端，并向你的智能体发送提示词。不要分享这个链接或二维码的截图。如果已经分享过，请按 **Regenerate**——所有已配对的手机都会立即断开连接。 --- ## 配对手机 > 打开远程访问，用手机扫描二维码。 Source: https://docs.neurosquad.ai/zh/remote/pairing **1. 打开 Remote access** 点击顶栏中的 **Remote access** 按钮（或进入 **Settings → Remote access**）并将其打开。 **2. 选择 Local network** 手机必须和电脑连接同一个 Wi-Fi。如果电脑连接了多个网络，请选择手机所在的那个。 **3. 扫描二维码** 用手机相机对准二维码，打开链接。这样就连上了。 **4. 添加到主屏幕** 在手机浏览器中使用 **Share → Add to Home Screen**（分享 → 添加到主屏幕）。之后它就会像应用一样打开。 > 在 **Settings → Remote access** 中保持端口不变，主屏幕快捷方式才能一直可用。 ### 取消配对 在 **Settings → Remote access** 中，按 **Pairing link** 旁边的 **Regenerate**。所有用旧链接配对的手机会立即失效，需要重新扫描新的二维码。 --- ## 不在家时 > 通过免费的 Cloudflare 隧道，在移动数据或其他网络下访问 NeuroSquad。 Source: https://docs.neurosquad.ai/zh/remote/internet 在同一个 Wi-Fi 下，手机会直接与电脑通信。要从移动数据或其他网络访问电脑，请把 **Share access over** 切换为 **Internet**。NeuroSquad 会通过 **Cloudflare 隧道**连接——无需在路由器上做任何设置。 ### 两种隧道 - **快速隧道（无需账号）**: 免费，无需注册。你会得到一个随机的 https 地址。每次 NeuroSquad 启动时地址都会变化，所以重启后需要重新扫码。第一次使用时，NeuroSquad 会下载 Cloudflare 的小型辅助程序（约 55 MB）。 - **自己的 Cloudflare 隧道**: 使用你自己域名的固定地址。在 Cloudflare 控制台中创建一个隧道，然后把它的公共主机名和隧道 token 粘贴到 **Settings → Remote access** 中。 > 这会把 NeuroSquad 暴露在公共互联网上。配对链接是陌生人与你的智能体之间唯一的屏障——千万不要分享它。流量是加密的，并会经过 Cloudflare。 ### 局域网还是互联网？ | | 局域网 | 互联网 | | --- | --- | --- | | 可用范围 | 同一个 Wi-Fi 下 | 任何地方 | | 设置 | 无需设置 | 无需设置（快速隧道）或需要 Cloudflare 账号（自己的隧道） | | 地址 | 保持不变 | 快速隧道：重启后变化 | --- ## 在手机上能做什么 > 工作区、智能体实时屏幕、提示词、新卡片和提醒——都能在手机上完成。 Source: https://docs.neurosquad.ai/zh/remote/on-the-phone - **查看所有工作区**——每个工作区有多少张卡片，多少正在工作，多少在等你。 - **打开工作区**——一张画布地图，显示每张卡片及其状态。 - **阅读智能体的屏幕**——实时显示，可缩放。 - **发送提示词**——在手机上输入，或使用手机自带的语音键盘。 - **添加卡片**或**创建工作区**——直接在手机上选择电脑中的文件夹。 - **接收提醒**——页面打开期间，每当有智能体完成或需要你时，它会发出提示音并列出来。 > 卡片只有在其工作区于电脑上打开时才会运行。如果你打开的卡片所在的工作区没有在电脑上打开，手机会提示你先在桌面端打开它。 > 目前还不支持向锁屏的手机推送通知——这需要一个固定的 https 地址。保持页面打开才能听到提示音。 --- ## 用说话代替打字 > 按下快捷键，开口说话，你的话就会变成文字——全程在你自己的电脑上处理。 Source: https://docs.neurosquad.ai/zh/dictation 把任务说出来，往往比打出来更快。NeuroSquad 内置了语音输入功能，在电脑上的任何地方都能用，而不仅限于 NeuroSquad 内部。 **1. 按下快捷键** `Ctrl Shift Space`。一个黑色小胶囊会出现，表示正在聆听。 **2. 开口说话** 想说什么就说什么，说多久都行。 **3. 再按一次快捷键** 文字会被复制到剪贴板。如果 NeuroSquad 在前台，文字还会直接输入到你正在使用的智能体中。 **轻按**快捷键开始和停止，或者说话时**按住**不放，说完松开即可。 > 语音永远不会离开你的电脑。语音模型在本地运行，音频只在转换成文字所需的时间内保留。 ### 更改快捷键 依次进入 **Settings → Dictation → Dictation shortcut → Change**，然后按下新的组合键。你还可以选择胶囊在屏幕上出现的位置（**Overlay position**）。 - **[语音模型](https://docs.neurosquad.ai/zh/dictation/models)**: 更快，或者更准——由你选择。 - **[语音输入历史](https://docs.neurosquad.ai/zh/dictation/history)**: 你说过的一切，随时可以再次复制。 --- ## 语音模型 > 在默认语音模型和更大、更准确的模型之间进行选择。 Source: https://docs.neurosquad.ai/zh/dictation/models 在 **Settings → Dictation** 中选择模型。所有模型都在你的电脑上运行。安装程序中不包含任何模型： 每个模型都只需下载一次，可以在首次运行的设置向导中下载，也可以直接在设置中下载。在模型下载到本地之前， 状态栏会显示 **Dictation: download the model**。 - **Parakeet（默认）**: 需要一次性下载，默认使用。在任何电脑上都很快，准确度足以应对日常语音输入。支持英语和主要欧洲语言，包括俄语。 - **Whisper large-v3-turbo**: 需要一次性下载。对口音、背景噪音和标点的处理明显更好，但在普通处理器上速度较慢。 - **Whisper GPU 版（faster-whisper）**: 同样的 Whisper 模型，借助 NVIDIA 显卡提速：十分钟的语音几秒钟就能转完。需要额外进行一次性安装，直接在设置中即可完成。仅限 Windows。 没有 NVIDIA 显卡？继续用 Parakeet 就好——对大多数人来说，它就是正确的选择。 --- ## 语音输入历史 > 你口述过的所有内容都在侧边面板里，随时可以再次复制。 Source: https://docs.neurosquad.ai/zh/dictation/history 你口述的所有内容都会以文字形式保存在窗口右侧的**语音输入历史**面板中。打开它就能再次复制之前的口述内容——当文字被送到了错误的窗口时尤其方便。 - 一键 **Copy**（复制）某一条记录。 - **Delete** 删除单条记录，或用 **Clear** 清空全部历史。 只保存文字，从不保存音频，而且所有内容都只留在你的电脑上。 --- ## 用量与费用 > 精确查看智能体用了多少 token、花了多少钱——按智能体、工作区、智能体类型、模型和提供商分类。 Source: https://docs.neurosquad.ai/zh/usage AI 智能体按 token 计费。侧边栏中的 **Usage** 部分会告诉你，你的 token——以及你的钱——都花在了哪里。 ### 选择时间段 选择 **Today**、**7 days**、**30 days**、**This month**、**Last month** 或 **All time**，也可以任选 **Date range**。每个数字都会与上一个等长时间段做对比。用筛选器可以缩小到某个工作区或某个智能体。 **Include usage outside cards** 还会统计你在 NeuroSquad 之外、在自己的终端里运行的会话。 ### 你能看到什么 - 顶部是该时间段的 **Tokens and cost**（token 数与费用）。 - **Tokens over time**，按智能体堆叠；以及 **What the tokens were**——新输入、从缓存重新读取的上下文、写入缓存的上下文、输出。 - **When the tokens go out**——一张“星期 × 小时”热力图，显示智能体最忙的时段。 - **Every agent**——一张可排序的表格，给出精确数字：请求数、输入、缓存、输出、总计、峰值上下文、费用和占比。 分类标签页把同一组数字按 **By agent**、**By workspace**、**By harness**、**By model** 和 **By provider** 拆分。点击某个智能体或工作区即可跳转过去。 ### 比较模型 **Compare models** 会把多个模型并排比较：费用、token、每次请求的费用、每 1,000 个输出 token 的费用、 在该时间段中的占比，以及每个模型的标价。 ### 精确的数字，以及它们的来源 费用按精确值计算，只在屏幕上显示时才取整。各行加起来永远等于总计。每项费用要么是智能体程序自己记录的金额， 要么按模型的标价计算——通过 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter) 发出的请求则按 OpenRouter 自己的目录定价。 > 用量读取自智能体自己的日志：**Claude Code**、**Codex CLI**、**OpenCode**、**Kilo Code**、**Hermes Agent**、**Pi** 和 > **omp**。这一部分会告诉你哪些智能体没有被统计。如果你用的是订阅而非按 token 付费，显示的费用是同样的工作按标价计算的金额。 ### 导出 **Export CSV** 会把表格保存下来，可以用 Excel 或 Google Sheets 打开。 ### OpenRouter 如果你使用 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter)，**By provider** 标签页会显示 OpenRouter 为你的密钥报告的数据： 今天、本周、本月和全部时间的花费，以及你的额度上限。这是整个密钥的数据——包括使用它的每个智能体和其他所有应用。 ### 控制成本 - 智能体卡片会显示 Claude Code、OpenCode、Kilo Code 或 Hermes Agent 智能体的上下文已占用多少。 - [Budget 卡片](https://docs.neurosquad.ai/zh/cards/budget)为整个工作区设定 token 上限，一旦超出就暂停其中的智能体。 --- ## 模型提供商 > 选择每个智能体运行在哪个 AI 模型上——使用你自己的登录，或通过 OpenRouter 这样的提供商。 Source: https://docs.neurosquad.ai/zh/providers 默认情况下，每个智能体都运行在你登录的账号上——Claude Code 用你的 Claude 订阅，Codex 用你的 OpenAI 账号，依此类推。在 NeuroSquad 中，这被称为 **Default (harness login)**。 **模型提供商**让你可以自己选择模型：在 **Settings → Providers** 中连接一次提供商，然后为每个智能体选择提供商和模型。想在某个任务上试试别的模型，或在日常工作中用更便宜的模型，都很方便。 - **[OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter)**: 一个密钥即可使用众多 AI 实验室的数百个模型——适用于 Claude Code、Codex CLI、OpenCode、Kilo Code、Qwen Code、Hermes Agent 和 Pi。 - **[CLI 账号与套餐限额](https://docs.neurosquad.ai/zh/providers/accounts)**: 并排保留多个 Claude Code 或 Codex 登录，每个套餐都有计量，一键交接到另一个账号。 智能体卡片上的小标签会显示它使用的提供商和模型，每个模型的花费可在[用量与费用](https://docs.neurosquad.ai/zh/usage)中查看。 ### 智能体自身登录下的模型 即使不用任何提供商，也可以选择智能体使用它**自己的**哪个模型：打开卡片的 ⋯ 菜单 → **提供商和模型**，保持 **Default (harness login)**，然后选择或输入模型——例如 Claude Code 的 `opus`，或 OpenCode 的 `anthropic/claude-sonnet-4-5`。下次启动时生效。Crush 和 Amp 会自行选择模型，因此没有这个选项。 --- ## OpenRouter > 用一个 OpenRouter 密钥，让 Claude Code、Codex CLI、OpenCode、Kilo Code、Qwen Code、Gemini CLI、GitHub Copilot CLI、Hermes Agent、Pi、omp、Factory Droid 或 Crush 运行在数百个模型上。 Source: https://docs.neurosquad.ai/zh/providers/openrouter [OpenRouter](https://openrouter.ai) 让你用一个密钥就能使用众多 AI 实验室的模型，费用从你的 OpenRouter 余额中扣除。NeuroSquad 可以通过它运行 **Claude Code**、**Codex CLI**、**OpenCode**、**Kilo Code**、**Qwen Code**、**Gemini CLI**、**GitHub Copilot CLI**、**Hermes Agent**、**Pi**、**omp**、**Factory Droid** 和 **Crush** 智能体（Factory Droid 为此无需 Factory 账户）。 ### 1. 连接你的密钥 **1. 打开 Settings → Providers** 如果你还没有密钥，按 **Get a key**——它会打开 OpenRouter 的网站。 **2. 粘贴密钥并按 Save and test** 你会看到 **Key works**。密钥由你的操作系统加密，只会交给你指定使用它的智能体。 连接之后，同一页面会显示你今天、本周和本月的花费（**Spent**）、你在 OpenRouter 上设置的限额（如果有），以及可用模型列表（**Models**）。 ### 2. 创建使用指定模型的智能体 在添加菜单中选择 **New agent… (provider, model, role)**。对话框会询问： - **Harness**——运行哪个智能体程序（Claude Code、Codex CLI、OpenCode、Kilo Code、Qwen Code、Gemini CLI、GitHub Copilot CLI、Hermes Agent、Pi、omp、Factory Droid 或 Crush）。 - **Provider**——**OpenRouter**，或 **Default (harness login)**。 - **Model**——在目录中搜索；每个模型都会显示上下文长度和每百万 token 的价格。保持 **Harness default** 则由智能体自行选择。 - **Role**（可选）——参见[角色](https://docs.neurosquad.ai/zh/agents/roles)。 - **Name**（可选）。 智能体卡片上会出现一个显示其提供商和模型的小标签。 ### 之后再修改 在智能体卡片的菜单中打开 **Provider and model**，选择新的值并按 **Apply**。更改会在智能体下次启动时生效。 ### 没有密钥时 如果没有保存密钥，就不会向 OpenRouter 发送任何内容：智能体只会使用它的**默认登录**运行，其小标签会变成琥珀色来提醒你。**New agent** 对话框也会给出警告，并提供 **Open settings**。 > 只有在 Anthropic 自己的模型上，Claude Code 才能保证正常工作。在其他模型上，它的工具可能无法正常使用——模型选择器会提醒你。 --- ## CLI 账号与套餐限额 > 并排保留多个 Claude Code 或 Codex 登录，查看每个套餐的限额用了多少，一键在另一个账号上继续工作。 Source: https://docs.neurosquad.ai/zh/providers/accounts 如果你有不止一个 Claude 或 ChatGPT 订阅（比如个人的和工作的），NeuroSquad 会把各个登录分开保存， 并显示每个套餐用了多少。 ### 套餐计量 **Claude Code** 或 **Codex CLI** 卡片的标题栏里有一个小圆环，显示套餐中最满的那个窗口的用量，例如 `7d 80%`。点击它可以看到所有窗口及其重置时间： - **Claude Code**（Pro 和 Max）：5 小时窗口和每周窗口。 - **Codex CLI**（ChatGPT 套餐）：你的套餐所含的窗口，例如 5 小时和一周。 用量达到 80% 时圆环变黄，达到 95% 时变红。在这两个节点你还会收到通知，可以在 **设置 → 通知 → 智能体触及用量上限** 中关闭。 所有计量也集中在一处： - **用量 → 套餐限额** 列出所有账号。 - **团队** 看板为其智能体使用的每个账号显示一行。 这些数字来自 CLI 本身： - **Claude Code** 在每次回答后把它们交给自己的状态栏。 - **Codex** 把它们写入自己的会话日志。 NeuroSquad 从不读取你的登录，也不会自行向服务查询用量。因此： - Claude Code 的计量在卡片第一次回答后出现。 - 没有 Claude Code 卡片运行时，它保持最后的数值，并标明这些数字的时间。 - 重置时间已过的窗口显示为重新开始。 #### 你的 Claude Code 状态栏照常工作 为了接收这些数字，Claude Code 卡片会把状态栏经过 NeuroSquad。如果你有自己的状态栏，NeuroSquad 仍会运行你的命令并显示其输出；没有的话，状态栏显示计量，例如 `5h 6% · 7d 80%`。 如果想让 Claude Code 的状态栏完全保持原样，关闭 **设置 → CLI 账号 → Claude Code 套餐计量** 即可。 这样 Claude Code 卡片就没有计量。 其他 CLI 不向本地工具提供套餐数据，因此没有计量。它们的花费可以在 [用量与成本](https://docs.neurosquad.ai/zh/usage) 中查看。 ### 同一个 CLI 的多个账号 打开 **设置 → CLI 账号**，在 Claude Code 或 Codex CLI 下点击 **添加账号**，起个名字，例如 *工作*。 - 每个账号为该 CLI 的登录、设置和历史使用独立的文件夹。 - **你的账号**（平常的登录）保持原位不动。 - 新账号从空白开始：不会复制你的设置。 要使用某个账号，在以下任一位置为卡片选择它： - 卡片的 ⋯ 菜单 → **提供商和模型** → **账号**。 - **新建智能体…** 对话框。 从卡片下次启动起生效。第一次使用时，在**卡片内**用 CLI 自己的登录流程登录： - 在 Claude Code 中运行 `/login`。 - Codex 会自己显示登录界面。 > NeuroSquad 从不读取、复制或发送 CLI 保存在账号文件夹中的内容。登录始终在 CLI 本身中完成。 删除账号会删除它的文件夹，也就是该登录及其上的对话。使用它的卡片在下次启动时回到你的账号。 ### 在另一个账号上继续 当卡片的套餐快用完或已触及限额时，打开计量或限额标签，点击 **在另一个账号上继续…**。这会打开 [交接](https://docs.neurosquad.ai/zh/agents/long-sessions) 对话框：选择账号，检查摘要，然后创建新卡片。新卡片出现在旧卡片旁边，位于同一文件夹， 摘要已填好。 账号绝不会自动切换。每个账号都按其套餐允许的方式使用，迁移工作始终由你决定。 如果该账号从未在 NeuroSquad 中登录过，新卡片会先打开 CLI 的登录，摘要会复制到剪贴板，登录后粘贴即可。 ### 按账号查看用量 **用量 → 按账号** 按付费的登录拆分 token 和费用。每个 CLI 自己的登录显示为 *你的账号*，每个添加的账号 单独占一行。 --- ## 集成 > 把你的智能体连接到 Telegram，以及已保存的 token 和密钥是如何存放的。 Source: https://docs.neurosquad.ai/zh/integrations 集成的用法和其他卡片完全一样：添加卡片，连接一次你的账号，然后从智能体向它拉一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。之后智能体就能使用这项服务——而每一次调用你都能在箭头上看到。 - **[Telegram 机器人](https://docs.neurosquad.ai/zh/integrations/telegram)**: 在 Telegram 里和你的智能体对话，并在它们完成时收到通知。 ### 你的密码和 token 是安全的 密码、token 和密钥由你的操作系统加密，并保存在你的电脑上。一旦保存，就不会再被显示出来——无论是在应用中，还是通过[远程访问](https://docs.neurosquad.ai/zh/remote)在手机上。删除卡片时，它保存的密钥也会一并删除。 > 侧边栏的 **Integrations** 部分会列出所有工作区中的 Telegram 卡片，以及你的[模型提供商](https://docs.neurosquad.ai/zh/providers)。 --- ## Telegram 机器人 > 在 Telegram 中给智能体发消息并收到它们的回复——它们完成时还会提醒你。 Source: https://docs.neurosquad.ai/zh/integrations/telegram **Telegram 卡片**把你自己的 Telegram 机器人连接到你的智能体。用手机给机器人发消息，消息就会送达通过[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)连接到这张卡片的智能体。它们也可以在同一个聊天中回复你。 它在你的电脑上运行——无需搭建任何服务器。 ### 设置 **1. 创建机器人** 在 Telegram 中打开 **@BotFather**（卡片上有对应的按钮），发送 `/newbot` 并起一个名字。BotFather 会回复一个 token。 **2. 粘贴 token** 添加一张 Telegram 卡片，粘贴 token，然后按 **Connect**。 **3. 给机器人发消息，然后按 Allow** 向你的机器人发送 `/start`。卡片会在 “Wants to talk to your agents” 下显示这个聊天——按 **Allow**。 > 只有你 **Allow** 的聊天才能到达你的智能体。其他发现你机器人的人都会被忽略。 ### 在 Telegram 中接收通知 **Tell me in Telegram when a connected agent finishes or needs input** 会向每个已允许的聊天发送消息——这样你离开座位后，也知道什么时候该回来。 你还可以直接在卡片里以机器人的身份输入消息，并选择由哪个已连接的智能体接收。 --- ## 技能与 MCP > 来自 skills.sh 的技能和任意 MCP 服务器的工具——安装一次，用箭头交给指定的智能体。 Source: https://docs.neurosquad.ai/zh/skills-mcp 有两类扩展能让智能体更擅长某项工作，NeuroSquad 都能替你安装： - **MCP 服务器**: 一个小程序或网络服务，为智能体提供**新工具**：读取 Figma 文件、打开 GitHub issue、查询数据库、获取最新的库文档。 它使用 Model Context Protocol——所有主流编码智能体都支持的标准。 - **技能**: 一个包含**专家指引**的文件夹（`SKILL.md`，有时还带脚本和参考文件），告诉智能体如何把某类任务做好： 动手前先梳理想法、设计有辨识度的界面、写出像样的测试计划。 ### 工作方式 **1. 在目录中找到它** **Skills & MCP** 边输入边搜索官方 **MCP Registry**（约 35,000 个服务器）和 **skills.sh** （最受欢迎的 20,000 个技能，附安装次数和安全扫描）。参见[目录与安装](https://docs.neurosquad.ai/zh/skills-mcp/catalog)。 **2. 安装一次** 下载任何东西之前，你都能看到具体会运行什么，并需确认。所有内容都装进 NeuroSquad 自己的文件夹—— 不做全局安装，也不会改动你自己的智能体设置。 **3. 在画布上放一张卡片，再画一条箭头** **MCP server** 卡片或 **Skill** 卡片代表一个已安装的项目。从它画一条箭头到智能体，那个智能体就拥有了它。 参见[交给智能体](https://docs.neurosquad.ai/zh/skills-mcp/cards)。 > **只有连上的智能体能看到。** 没有箭头连到 MCP 或技能卡片的智能体，看不到你安装的任何东西—— > 甚至不知道它们存在。五个智能体可以共用一个服务器，也可以各用各的。 ### 哪些智能体可以使用 | 智能体 | 技能与 MCP 服务器 | 画好箭头之后 | | --- | --- | --- | | **Claude Code** | 是 | 立即生效，无需重启 | | **Hermes Agent** | 是 | 立即生效，无需重启 | | **Kilo Code** | 是 | 立即生效，无需重启 | | **GitHub Copilot CLI** | 是 | 立即生效，无需重启 | | **Pi** | 是 | 立即生效，无需重启 | | **omp** | 是 | 立即生效，无需重启 | | **aider** | 是 | 立即生效，无需重启 | | **Factory Droid** | 是 | 立即生效，无需重启 | | **Amp** | 是 | 立即生效，无需重启 | | **Auggie** | 是 | 立即生效，无需重启 | | **Goose** | 是 | 立即生效，无需重启 | | **Codex CLI** | 是 | 智能体下次启动时 | | **Qwen Code** | 是 | 智能体下次启动时 | | **Gemini CLI** | 是 | 立即 | | **Kimi Code** | 是 | 智能体下次启动时 | | **Cline CLI** | 是 | 智能体下次启动时 | | 其他智能体 | 否 | — | 卡片会在每个已连接的智能体旁显示同样的信息：**即时**、**下次启动**或**不可用**。最后一种表示 NeuroSquad 根本不会给这个智能体提供工具——也就是[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)无法赋予能力的那些智能体。 ### 智能体如何知道自己拥有什么 你不需要告诉智能体任何事。 - **技能：** 智能体的 `skill_load` 工具会列出每个已连接技能及其“何时使用”说明，所以智能体会在开始任务前 自己加载匹配的技能——和 Claude Code 自带的技能机制一样。 - **MCP 服务器：** 每个服务器的工具以服务器名开头，例如 `framelink__get_figma_data`，每条描述里都注明了服务器， 还附有服务器自己的使用说明。 - **`neurosquad_connections`**——智能体用来查看箭头另一端连着什么的工具——也会列出已连接的服务器和技能。 ### 须知 - **对已安装服务器的每次调用都由你批准。** 它的工具来自一个单独的服务器条目（`ns-connected`）， NeuroSquad 不会预先批准，因此 Claude Code、Codex 和 Qwen 在每次调用前都会询问——除非你把智能体切换到了自动批准一切的模式。Hermes Agent 自己从不询问，所以由 NeuroSquad 代为询问：**允许一次**、**本次会话内允许**或**拒绝**（五分钟内未回复视为拒绝）。 服务器之后更改工具时，卡片上会出现变更提示；在你接受之前，智能体看不到新增或更改的工具。 - **这是第三方代码。** 你安装的服务器运行在你的电脑上（或是一个互联网服务）；技能的文本会直接进入智能体的指令。 只安装你信任的内容——目录会展示来源、确切的命令，以及技能的安全扫描结果。 - **目前并非所有服务器都能安装。** 只以 MCPB 包、NuGet 或 Cargo 包发布的服务器，以及会启动本地 Web 服务器的包， 会显示但无法安装。 - **有些登录只允许经过批准的应用。** 例如 Figma 官方的远程服务器会拒绝未经批准的应用登录。请改用接受个人令牌的服务器—— **Framelink Figma MCP**（`FIGMA_API_KEY`）可以使用你自己的 Figma 令牌。 --- ## 目录与安装 > 搜索 MCP Registry 和 skills.sh，看清将要运行的内容，把服务器和技能安装到 NeuroSquad 自己的文件夹。 Source: https://docs.neurosquad.ai/zh/skills-mcp/catalog **技能、MCP 与插件**是一个窗口，有四个标签页：**MCP 服务器**、**技能**、**插件**和**已安装**。可以从侧边栏打开 （**集成 → 技能、MCP 与插件**），也可以在空的 MCP 或技能卡片上点 **Browse**——这样装好的内容会直接放到这张卡片上。 添加卡片菜单中的 **插件…** 会直接打开“插件”标签页。 ### 搜索 边输入边出结果。整个目录保存在你的电脑上并在后台更新，所以搜索是即时的，离线也能用。 - **MCP 服务器**来自官方 **MCP Registry**——那里发布的所有服务器。可以按运行方式筛选：**本地**（在你电脑上运行的包）、 **远程**（互联网上的服务）和**免配置**（无需填写任何内容）。 - **技能**来自 **skills.sh**——最受欢迎的智能体技能目录。安装最多的排在前面；联网时还会合并它自己的搜索结果和安装次数。 - **已安装**是你的库：这台电脑上的所有内容，含设置、更新和卸载。 ### 安装 MCP 服务器 **1. 选择运行方式** 很多服务器有多种运行方式——**npm** 包（需要 Node.js）、**PyPI** 包（需要 uv 或 Python）、**Docker** 镜像 （需要 Docker），或通过 HTTPS 访问的**远程**服务。NeuroSquad 暂不支持的方式会置灰并注明原因。 **2. 填写设置** 密钥和令牌（Figma 令牌、API 密钥）填在密码框里。它们使用系统钥匙串加密，**永远不会展示给智能体**—— 智能体只能拿到工具。 **3. 阅读“What will run”** 确切的命令、包及其固定版本，以及会传给它的设置名称。如果 Docker 镜像要求访问你的文件、网络或设备，会给出警告。 **4. 确认并安装** 勾选确认框并点击 **Install**。输出会显示在按钮下方。随后 NeuroSquad 会启动服务器一次以列出它的工具，然后就绪。 > 所有内容都装进 NeuroSquad 自己的数据文件夹——每个包一份独立副本、独立的 Python 环境。不做全局安装， > `~/.claude`、`~/.codex` 等智能体设置保持不变。Docker 镜像例外：它们一如既往地存放在 Docker 中。 安装后，在**已安装**中打开它，可以： - **测试**——重新启动并重新读取工具。 - **显示日志**——服务器无法启动时它输出了什么。 - **登录 / 退出登录**——适用于使用你账号（OAuth）的远程服务器。登录页面会在浏览器中打开；令牌加密保存。 - 修改**设置**——已保存的密钥会一直保留，除非你输入新的。 - **卸载**——删除它的文件、设置和已保存的密钥。使用它的卡片会留在画布上，并提示选择其他项。 服务器只在智能体第一次需要时启动，由所有连接它的智能体共用，闲置十分钟后停止。 ### 安装技能 **5. 打开它** 你会看到完整渲染的 `SKILL.md`、文件与大小、许可证，以及 skills.sh 发布的安全扫描结果（Snyk、Socket 等）。 **6. 留意脚本** 如果技能自带脚本，会明确提示：遵循该技能的智能体可能会运行它们。 **7. 确认并安装** 勾选“我已阅读此技能”并点击 **Install**。安装的正是你刚读过的内容——如果技能在此期间有变化，会请你重新查看。 在**已安装**中，可以在有新版本时**更新**技能、**打开文件夹**查看文件，或**卸载**它。 ### 添加插件 插件内置于 NeuroSquad——列出它们无需下载任何东西。每个插件都是一张卡片，会改变连接到它的智能体的工作方式； 第一个是 [RTK-AI Token Saver](https://docs.neurosquad.ai/zh/plugins/rtk-ai-token-saver)，它会压缩智能体 shell 命令的输出。 1. 在添加卡片菜单中选择 **插件…**（在菜单搜索框输入 `token` 或 `rtk` 也能找到），或打开目录的 **插件** 标签页。 2. 选择一个插件：可以看到它的作用、用法以及支持哪些智能体。 3. 点击 **添加到画布**。卡片会出现在打开菜单时所在工作区的画布上（从侧边栏打开时：当前显示的工作区）。 然后从智能体画一条箭头连到它。 ### 安全 - **目录里的一切都是第三方内容。** MCP 服务器是以你账户权限运行的程序，或是智能体与之通信的网络服务。只安装你本来就会安装的东西。 - **技能文本会成为智能体的指令。** 技能可以让智能体做任何事——安装前请先阅读；目录完整展示它正是为此。 - 远程服务器**仅限 HTTPS**。密钥永远不会出现在命令行或日志中。 --- ## 交给智能体 > MCP 服务器卡片和技能卡片——用箭头连到智能体；只有连上的智能体才能获得。 Source: https://docs.neurosquad.ai/zh/skills-mcp/cards 已安装的服务器或技能通过画布上的卡片交给智能体。从[添加菜单](https://docs.neurosquad.ai/zh/canvas/cards)添加一张——**MCP server** 或 **Skill**——然后选择它代表什么：**Browse** 打开目录，已经安装的也可以直接在卡片上选。 ### 用箭头连接 在卡片和智能体之间画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。就这么简单： - 智能体获得服务器的工具或技能——**其他智能体都不会**。 - 一张卡片可以连到多个智能体；一个智能体也可以有多张卡片。 - 删除箭头，智能体就会再次失去它。 每张卡片都会列出它已提供给哪些智能体，以及对每个智能体意味着什么： - **即时**: 智能体立即获得，即使在对话进行中。Claude Code、Kilo Code 和 Hermes Agent 就是这样。 - **下次启动**: 智能体在启动时读取工具列表：重启它才能用上新的箭头。Codex CLI 和 Qwen Code 是这样。 - **不可用**: NeuroSquad 不向这类智能体提供工具。 点击卡片上的智能体名称，视图会飞到它那里。 ### MCP 服务器卡片 - **标题栏：** 服务器名称、工具数量，以及一个状态点——运行中、空闲（首次调用时启动）、正在启动、启动失败或等待登录。 - **工具：** 服务器提供的每个工具。智能体最近调用的那个会高亮，卡片会短暂显示“by Designer”。 - **问题就地显示：** “服务器未能启动”附日志最后一行和 **Try again**；“需要登录”附 **Sign in** 按钮。 - **Settings** 在目录中打开它；**Change server** 把卡片换成另一个服务器。 ### 技能卡片 - 技能名称、来源、文件以及是否包含脚本，还有它的描述——也就是智能体看到的“何时使用”说明。 - 最近是谁加载了它、共加载了几次。 - 展开卡片即可阅读完整的 `SKILL.md`。 - **Details** 在目录中打开它（更新、打开文件夹、卸载）；**Change skill** 把卡片换成另一个技能。 缩小画布时，卡片会变成磁贴：服务器显示工具数和智能体数，技能显示名称。 > 智能体会在开始任务**之前**自己加载匹配的技能——它的 `skill_load` 工具列出了每个已连接技能及其使用时机。 > 如果你无论如何都想用某个技能，直接说出来即可：“用 brainstorming 技能”。 --- ## 插件 > 内置的附加功能，用箭头连接到智能体即可使用——无需重启，也不改动 CLI 自身的设置。 Source: https://docs.neurosquad.ai/zh/plugins 插件会改变已连接智能体的工作方式。从添加卡片菜单中添加——**插件…** 会打开目录的 **插件** 标签页， 在那里搜索并选择——然后用 [箭头](https://docs.neurosquad.ai/zh/canvas/arrows) 把它连接到智能体。智能体在下一步操作时就会用上它； 移除箭头即停止。 插件随 NeuroSquad 一起提供，进入列表前都经过检查。CLI 自身的设置不会被改动：插件是 NeuroSquad 为这一张智能体卡片添加的一层。 - **[RTK-AI Token Saver](https://docs.neurosquad.ai/zh/plugins/rtk-ai-token-saver)**: 压缩智能体 shell 命令的输出——更少 token，事实不变。 - **[Caveman](https://docs.neurosquad.ai/zh/plugins/caveman)**: 让智能体回答简短——没有废话，代码和错误信息保持原样。 - **[记忆 (mem0)](https://docs.neurosquad.ai/zh/plugins/mem0-memory)**: 智能体跨会话共享的长期记忆——保存在你的电脑上。 - **[Context7 — 最新文档](https://docs.neurosquad.ai/zh/plugins/context7-docs)**: 为智能体提供最新、匹配版本的库文档，而不是过时的训练数据。 - **[代码图谱](https://docs.neurosquad.ai/zh/plugins/code-graph)**: 代码的知识图谱——智能体直接查找调用者、被调用者和定义，不再 grep。 - **[Graphify](https://docs.neurosquad.ai/zh/plugins/graphify)**: 代码的实时地图——智能体向它提出结构性问题，每次查询都会在地图上亮起。 更多插件即将推出。技能和 MCP 服务器也以同样的方式通过目录中各自的标签页连接——参见 [技能与 MCP](https://docs.neurosquad.ai/zh/skills-mcp)。 --- ## RTK-AI Token Saver > 把智能体连接到它，它的 git、ls、grep 和测试命令的输出就会被压缩——token 更少，事实不变。 Source: https://docs.neurosquad.ai/zh/plugins/rtk-ai-token-saver 智能体会读取大量命令输出：每一次 `git status`、`git log`、目录列表和测试运行都会进入它们的上下文。 **RTK-AI Token Saver** 插件让智能体的 shell 命令经过 [RTK](https://github.com/rtk-ai/rtk)——一个开源工具， 保留事实、去掉噪音：`git status` 变成简洁的已修改文件列表，全部通过的测试变成一行。 ### 如何使用 1. 在添加卡片菜单中选择 **插件…**，在 **插件** 标签页打开 **RTK-AI Token Saver**，点击 **添加到画布**。 2. 如果尚未安装 RTK，点击 **下载 RTK**。NeuroSquad 会从 GitHub 下载官方构建（约 4.5 MB）， 并与 GitHub 公布的校验和核对；没有校验和就不会下载。已经装了 RTK（`winget install rtk-ai.rtk`、 `brew install rtk`）？它会被自动找到。 3. 从智能体向卡片画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。 就这样——智能体的**下一条**命令就会经过 RTK，无需重启。删除箭头后，下一条命令又会照常运行。 ### 卡片显示什么 - 已连接的智能体少读了**多少输出**（百分比），以及大约节省了多少 token。 - 每个已连接的智能体：它自己的节省量和最近一次被压缩的命令，例如 `git status → rtk git status`。 - 正在使用的 RTK 版本，以及它是你自己的安装还是下载的版本。 每条被压缩的命令也会在箭头上闪现，并记录在箭头日志中。 > RTK 按字节 ÷ 4 估算 token，因此百分比准确，token 数为近似值。RTK 只压缩 shell 命令的输出—— > 你的提示词、智能体自己读取的文件以及它的回答都不会改变。 ### 支持哪些智能体 实时支持 **Claude Code**、**Cursor CLI**、**OpenCode** 和 **Kilo Code**。其他智能体也可以连接， 但卡片会标记为 **不支持**——它们的 CLI 目前还无法在命令运行前改写命令。 - **危险模式**——压缩每一条受支持的命令。 - **普通模式（Claude Code）**——只读命令（`git status`、`git log`、`ls`、`cat`、`grep`）会被压缩且 不弹出确认，和以前一样直接运行。本来就会询问的命令（`git push`、`cargo test`…）仍只询问一次—— 你批准的是 `rtk` 版本。其他命令原样运行。RTK 不会增加确认，也不会批准任何本应询问的命令。 - **普通模式（Cursor、OpenCode、Kilo）**——无法从外部预测它们的权限确认，因此 RTK 仅在危险模式下 对它们生效。 - **画布模式**——智能体没有自己的 shell，没有可压缩的内容。 如果 RTK 不存在、出错或不认识某条命令，原始命令会原样运行。需要某条命令完整输出的智能体， 只需在命令前加上 `RTK_DISABLED=1`。 ### 隐私 RTK 在你的电脑上运行。NeuroSquad 会为它启动的每个智能体关闭 RTK 自带的（需主动开启的）遥测， 并把 RTK 的历史按智能体分别保存在 NeuroSquad 的数据文件夹中。你的 RTK 设置保持不变。 RTK 由 rtk-ai 开发，采用 Apache 2.0 许可证发布。 --- ## Caveman > 把智能体连接到它，回答就会变短——没有废话，代码、命令和错误信息保持原样。 Source: https://docs.neurosquad.ai/zh/plugins/caveman 智能体喜欢解释：客气的开场、复述、“我建议……”。**Caveman** 插件把 [caveman](https://github.com/JuliusBrussee/caveman)（Julius Brussee 的开源项目）的回复规则交给已连接的 智能体：去掉废话，保留每一个技术事实。用作者的话说，caveman 让变小的不是大脑，而是“嘴”。 同一个问题，来自 caveman 自己的 README（英文）： - **不用 caveman：**“The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object.” - **用 caveman（Full）：**“New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`.” ### 如何使用 1. 在添加卡片菜单中选择 **插件…**，在 **插件** 标签页中打开 **Caveman**，点击 **添加到画布**。 2. 在卡片上选择级别： - **Lite**——去掉废话和含糊其辞，保留完整句子。 - **Full**——经典 caveman 风格，也是作者的默认级别。 - **Ultra**——最简洁：连接词也省略，每个事实只说一次。 - **文言文**——以上三个级别的文言文版本。 3. 从智能体画一条 [箭头](https://docs.neurosquad.ai/zh/canvas/arrows) 到卡片。 完成——智能体的 **下一个** 回答就会遵循这些规则。无需重启，也不会往 CLI 里安装任何东西。更换级别后， 下一轮就会使用新级别。移除箭头后，下一轮会收到一条“恢复正常回答”的简短提示。 ### 哪些内容保持原样 代码、命令、文件路径和错误信息绝不缩写——只精简它们周围的文字。安全警告和不可撤销操作的确认会用完整 句子。智能体编写的代码、提交信息、文档和 pull request 描述保持正常行文。回答语言保持与你一致。 ### 卡片显示什么 - 当前级别，以及 caveman 为该级别给出的示例回答（和不用 caveman 时的同一回答）。 - 每个已连接的智能体：是否实时生效，最近收到的是什么（规则、提醒或恢复提示），以及有多少轮带上了规则。 - 规则的成本：它们是模型的输入——每个会话发送一次完整规则（约 1,400 个 token），之后每轮发送一段简短 提醒（约 60 个 token）。两者都是按每 4 个字符 1 个 token 估算的。 > 更短的回答意味着更少的 **输出** token，但规则本身是额外的 **输入** token，而且模型的思考过程不会被缩短。 > 问题非常简短时，规则的成本可能超过节省——caveman 的作者也这么说。请在自己的工作中试一试，只在划算的地方使用。 ### 支持哪些智能体 实时支持 **Claude Code**、**Codex** 和 **Qwen Code**：规则通过每轮开始前运行、并且可以为模型添加文字的钩子 发送。其他智能体也可以连接，但卡片会标记为 **不支持**——它们的 CLI 目前还不提供从外部为某一轮添加文字的方式。 危险模式和卡片模式在这里没有影响：插件改变的是智能体怎么写，而不是它能做什么。 ### 来源 规则来自 caveman 本身——它的 `caveman` 技能文本和每轮提醒——从固定版本原样复制到 NeuroSquad 中，按 MIT 许可证使用。NeuroSquad 不下载任何东西，不向任何地方发送数据，也不修改你的 CLI 设置。caveman 另外的代理和 引擎不属于这个插件。 --- ## 记忆 (mem0) > 智能体跨会话共享的长期记忆：它们保存事实和决定，之后再回忆起来。保存在你的电脑上。 Source: https://docs.neurosquad.ai/zh/plugins/mem0-memory 会话一结束，智能体就会忘记一切。**记忆**插件为已连接的智能体提供长期记忆：它们保存值得记住的 内容——一个决定、一项约定、你的偏好、关于项目的事实——并在之后的会话中、在其他智能体里、在重启之后 再次找到它。 它基于 [mem0](https://github.com/mem0ai/mem0)，一个开源记忆引擎（Apache-2.0），内置于 NeuroSquad。 记忆保存在你的电脑上、NeuroSquad 的数据文件夹中。无需创建账号，也无需运行服务器。 ### 使用方法 1. 在添加卡片菜单中选择 **插件…**，在 **插件** 标签页打开 **记忆 (mem0)**，然后点击 **添加到画布**。 2. 从智能体向卡片画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。 现在智能体拥有了记忆工具。让它记住点什么（"记住：只通过 GitHub Actions 部署"），或者照常工作—— 智能体会被提示在可能依赖先前决定的工作之前先搜索记忆，并保存长期有效的事实。移除箭头，工具随之消失； 记忆仍保留在卡片上。 大多数智能体会立即获得这些工具，无需重启。Codex、Kimi Code、Cursor 和 Crush 只在启动时读取一次工具 列表，因此它们从一开始就能看到记忆工具，由箭头决定调用能否通过。Qwen Code 和 Cline 会在下次启动时获得它们。 ### 智能体能做什么 | 工具 | 作用 | | --- | --- | | `memory_search` | 查找与问题相关的记忆，最相关的在前 | | `memory_add` | 保存一个事实（或一段需要从中提取事实的对话） | | `memory_list` | 列出记忆，最新的在前 | | `memory_get` | 读取一条记忆 | | `memory_update` | 更正一条已经过时的记忆 | | `memory_delete` | 遗忘一条记忆 | 智能体只能修改或删除**自己**保存的记忆。若要允许智能体编辑任何记忆——你的和其他智能体的——请在 卡片设置中打开 **智能体可以修改任何记忆**。 ### 卡片 卡片显示共有多少条记忆，最新的在前，以及每条由谁、何时保存。智能体刚写入的记忆会短暂高亮。你可以 搜索、用 **+** 自己添加记忆、编辑或删除任何记忆、把全部记忆导出为 JSON 文件，以及清空记忆。 ### 谁的记忆：范围 打开设置（卡片上的滑块图标），选择一个 **范围**： - **此工作区**（默认）——此工作区中连接到记忆卡片的所有智能体共享同一份记忆。 - **所有工作区**——所有工作区共用一份记忆：适合处处适用的内容，例如你的偏好和约定。 - **每个智能体独立**——每个已连接的智能体都有自己的私有记忆；卡片会显示全部。 记忆属于范围，而不属于卡片：删除卡片后再添加一张同一范围的新卡片，记忆仍然在。设置中的 **清空** 会删除它们。 ### 搜索：按词语或按语义 开箱即用时，卡片按**关键词**搜索——共同的词语及词片段，所以 "postgres" 能找到 "PostgreSQL"。 它无需任何设置、可离线使用，但不会关联同义词（"汽车" 和 "轿车"）。 若要**按语义**搜索，请在卡片上的**智能搜索**中点击**下载 150 MB**（或在 设置 → 搜索 中选择它）。 它只需下载一次一个小型多语言模型——在你的电脑上离线运行，理解中文、英文、俄文等数十种语言， 所以用中文提问也能找到用英文写下的记忆。每个文件都会校验其校验和。 你也可以使用来自 [OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter) 的嵌入模型，或你在 设置 → 提供商 中添加的、 支持 OpenAI API 的[模型服务器](https://docs.neurosquad.ai/zh/providers)——例如带 `nomic-embed-text` 的 Ollama，或 LM Studio。 该选择对所有记忆卡片生效。切换时，所有记忆会重建索引；卡片会显示进度，智能体会等待完成。 ### 事实提取 默认情况下，记忆按原文保存。在 **事实提取** 中选择一个模型后，mem0 会把智能体保存的内容整理成简短 事实，并跳过已知的内容。每次保存会向该模型发送一次请求。 ### 自动记忆 设置中有两个开关，默认都关闭： - **自动回忆**——在你的每个提示之前，把最相关的记忆作为笔记附加到智能体的这一轮。适用于 **Claude Code**、**Codex**、**Qwen Code**、**OpenCode**、**Kilo Code**、**Gemini CLI**、**pi** 和 **omp**。其他智能体会自己用 `memory_search` 搜索。 - **自动保存**——已连接的智能体结束一轮时，你的提示和它的最终回答会交给事实提取模型，模型只保留 长期有效的事实（常常一条也没有）。需要事实提取模型。 ### 历史、导出与导入 - 记忆上的时钟按钮会显示它的历史：何时添加，以及每次编辑和编辑前的文字。 - 设置中的**导出**会把卡片的记忆保存为 JSON 文件。**导入**读取这样的文件，显示有多少是新的、多少已经 存在（会被跳过），让你选择范围，然后添加新的记忆。卡片上的**撤销**只删除上一次导入添加的内容。 ### WSL 和 SSH 工作区 位于 WSL 内或 SSH 主机上的工作区中的智能体以同样方式使用此卡片：箭头为它们提供 `memory_*` 工具，自动回忆通过提示钩子到达那里的 Claude Code。记忆本身保存在这台电脑上 NeuroSquad 的数据文件夹中——另一侧不存储任何内容——"此工作区"范围照常将各工作区的记忆分开。 ### 删除工作区或智能体 删除工作区时，为它保存的记忆也会一并删除；删除智能体时，会删除它的私有记忆（“每个智能体独立” 范围）。确认对话框会写明数量。所有工作区共享的记忆会保留。 > 你的密钥留在 NeuroSquad 中：它们只会随每次请求发送给你选择的提供商。不会向 mem0 发送任何内容—— > 引擎自带的使用情况上报已关闭。 > 记忆是过去的笔记，而不是指令：它们可能已经过时。不要让智能体记住密码或密钥。 --- ## Context7 — 最新文档 > 把智能体连接到它，智能体就会查阅所用库的最新、匹配版本的文档，而不是依赖训练时记住的内容。 Source: https://docs.neurosquad.ai/zh/plugins/context7-docs 模型只知道训练时的库。而 API 一直在变：Hook 换了签名、配置项改了名、框架换了新路由。**Context7** 插件为连接的智能体提供 [Context7](https://github.com/upstash/context7)（Upstash 的开源项目）的两个工具： 查找库，然后阅读它当前的文档和代码示例——针对项目实际使用的版本。 ### 如何使用 1. 在添加卡片菜单中选择 **插件…**，在 **插件** 标签页打开 **Context7 — 最新文档**，点击 **添加到画布**。 2. 从智能体向卡片画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。 智能体就有了两个工具： - `context7_resolve_library_id`——按名称（“React”“Next.js”“Django”）查找库，列出匹配项及其 Context7 id （`/reactjs/react.dev`）、代码示例数量、来源可信度和已索引的版本。 - `context7_query_docs`——针对一个具体问题（“useEffect cleanup function”）返回某个库的文档和示例。 当任务涉及库的 API 时，大多数智能体会自己调用它们。你也可以直接要求：“先查一下 Next.js 文档”，或在 提示词里加上 **use context7**。移除箭头，工具随之消失。大多数 CLI 无需重启，也不会向 CLI 安装任何东西。 ### 无需账号 Context7 的文档索引是免费的托管服务。没有密钥时请求限额较低；从 [Context7 控制台](https://context7.com/dashboard) 获取免费 API 密钥可以提高限额。把密钥粘贴到卡片的 **密钥与缓存** 面板——它加密保存在你的电脑上，不会再次 显示，也绝不会写入文件或命令行。所有 Context7 卡片共用一个密钥。 卡片会显示剩余请求数和限额重置时间。限额用完时，卡片显示 **已达限额**，智能体收到清楚的提示而不是错误， 并且在重置前不再发送请求——缓存中的答案仍然可用。 ### 缓存 每个答案在你的电脑上保存 24 小时。两个智能体问了同一个问题，或同一个智能体再问一次，答案直接来自缓存， 不消耗请求。**密钥与缓存** 面板显示缓存了多少答案、服务了多少次查询，并可清除缓存。 ### 自动文档 在卡片上打开 **自动文档**，智能体会在你的每条提示词之前得到帮助： - 提示词提到项目的某个依赖（来自 `package.json`、`requirements.txt`、`pyproject.toml`、`Cargo.toml` 或 `go.mod`）时，智能体会收到一行提示：这个库有最新文档可查——并附上项目声明的版本。这一步不发送请求， 所以回合开始得一样快。同一个库每半小时最多提示一次。 - 提示词里有 **context7**（“use context7”）并提到某个依赖或库 id（`/vercel/next.js`）时，文档本身会直接 加入本轮。NeuroSquad 最多等待约一秒半；如果 Context7 更慢，智能体会收到提示，答案会缓存下来供下次使用。 自动文档支持 **Claude Code**、**Codex**、**Qwen Code**、**OpenCode**、**Kilo Code**、**pi**、**omp** 和 **Gemini CLI**。其他通过箭头连接的智能体同样获得这两个工具。 ### WSL 和 SSH 工作区 位于 WSL 内或 SSH 主机上的工作区中的智能体照常通过箭头获得这两个工具——查询由这台电脑上的 NeuroSquad 发出。自动文档会从 WSL 或通过 SSH 连接读取项目的 `package.json` 和其他清单文件。 ### 卡片显示什么 - 服务状态——**就绪**、**已达限额**、**离线** 或 **错误**——以及剩余请求数和重置日期。 - **试一次查询**：输入库和问题，看看智能体会得到什么。 - **最近的查询**：哪个库、什么问题、哪个智能体、什么时候，以及是否来自缓存。 > 库名和问题会发送到 Context7 的服务器（由 Upstash 运营）。不要在问题中写入机密、密码或专有代码——工具 > 描述也这样告诉智能体。项目的其余部分留在你的电脑上：自动文档在本地读取依赖列表，只发送库名和问题。 ### 来源 这两个工具来自 Context7 官方 MCP 服务器（`@upstash/context7-mcp`，MIT 许可证），沿用其描述；NeuroSquad 直接调用同一个 Context7 API，因此不需要额外安装或启动任何东西。文档索引本身是 Context7 的托管服务。 如果你需要完全不离开电脑的文档查询，可以改为从目录的 **MCP** 标签页添加一个自托管的文档 MCP 服务器。 --- ## 代码图谱 > 把智能体连接到它，智能体就能按结构找代码——谁调用了某个函数、它又调用了什么、某个符号在哪里定义——而不是一遍遍 grep、一个个读文件。 Source: https://docs.neurosquad.ai/zh/plugins/code-graph 要回答“谁调用了 `processOrder`？”，智能体通常会 grep、打开一个文件、再 grep、再打开下一个——在用不上的代码上花掉成千上万个 token。**代码图谱**插件借助 DeusData 的开源引擎 [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)，把工作区的代码索引成知识图谱——函数、类、方法、调用、导入、路由。连接的智能体直接查询图谱，一次调用就能得到答案。 ### 如何使用 1. 在添加卡片菜单中选择 **插件…**，在 **插件** 标签页打开 **代码图谱**，然后点击 **添加到画布**。 2. 在卡片上点击 **下载**。NeuroSquad 会从 GitHub 下载 codebase-memory-mcp 的官方版本（约 40 MB，解压后约 300 MB），并与应用内固定的校验和比对——不匹配的文件会被删除。只需下载一次。 3. 点击 **构建图谱**。大多数项目只需几秒，超大项目需要几分钟。 4. 从智能体画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)到卡片。 现在智能体拥有了图谱工具。大多数 CLI 无需重启即可使用；移除箭头，工具随之消失。 ### 智能体能做什么 | 工具 | 回答什么问题 | | --- | --- | | `codegraph_search_graph` | 按名称、模式或语义查找函数、类等符号 | | `codegraph_trace_path` | 谁调用了这个函数、它又调用了什么，可追溯多层 | | `codegraph_get_code_snippet` | 单个符号的源码，无需打开整个文件 | | `codegraph_query_graph` | 只读 Cypher 查询，用于多步问题 | | `codegraph_get_architecture` | 语言、包、入口点、路由、热点 | | `codegraph_search_code` | 按图谱排序的文本搜索 | | `codegraph_get_file_outline` | 一个文件中声明的所有内容 | | `codegraph_detect_changes` | 未提交的改动影响了哪些符号 | | `codegraph_get_graph_schema`、`codegraph_index_status`、`codegraph_check_index_coverage` | 图谱里有什么、有多完整 | | `codegraph_reindex` | 刚改完代码，立即重新索引 | 你也可以直接说：“用代码图谱找出所有调用 `validateOrder` 的地方”。 ### 卡片 - **核心数据**——图谱中有多少符号，以及文件、调用和关系的数量，是否已是最新。 - **搜索框**——输入名称，看看它定义在哪里。 - **包含内容**——函数、接口、类、类型，以及项目使用的语言。 - **使用它的智能体**，以及每个智能体最近一次查询图谱。 ### 始终保持最新 开启 **自动更新**（默认开启）后，卡片会发现文件变化，几秒后重新索引——只处理变化的部分，所以很快。已连接的智能体结束一个回合后，它也会刷新图谱。关闭后可以用 **立即更新** 手动更新。 > 图谱基于工作区文件夹构建。在隔离 worktree 中工作的智能体查询的仍是主文件夹的图谱。 ### WSL 和 SSH 工作区 对于 WSL 内或 SSH 主机上的工作区，引擎在**那里**、在代码旁边运行。卡片会显示位置——**WSL · Ubuntu** 或 **SSH · 你的主机**： - **下载**会获取引擎的 Linux 版本（x86-64 或 ARM64，按主机 CPU 选择）并在本机校验；第一次**构建图谱**时把它复制到那一侧 NeuroSquad 自己的文件夹（`~/.neurosquad`），再次校验并在那里解压——每个发行版或主机只需一次。 - 图谱也保存在该文件夹中。不会往那边的项目或主目录其他位置写入任何内容，代码也不会传到这台电脑：智能体只得到查询的答案。 - 保持最新：对于位于 Windows 磁盘（`/mnt/c/…`）上的 WSL 项目，卡片照常监视文件；其他情况下在已连接智能体的回合结束后以及点击**立即更新**时更新。 - 删除卡片（或工作区）会删除那一侧的图谱；退出 NeuroSquad 会停止那里的引擎。 引擎只在 Linux 上运行：运行 macOS 的 SSH 主机会显示"此主机没有引擎版本"。 ### 隐私与存储 一切都在你的电脑上运行。codebase-memory-mcp 不向任何地方发送数据——无需账号、没有遥测，代码不会离开本机。引擎和图谱保存在 NeuroSquad 的数据文件夹中：不会往你的项目或主目录写入任何内容；如果你自己装了 codebase-memory-mcp，它会继续独立工作。删除卡片，它的图谱也会一并删除。 codebase-memory-mcp 由 DeusData 开发，基于 MIT 许可证发布。 --- ## Graphify > 代码结构的实时地图。已连接的智能体向它提出结构性问题而不是 grep，每次查询都会在地图上实时亮起。 Source: https://docs.neurosquad.ai/zh/plugins/graphify 像“请求是怎么到达数据库的？”或“改了 `parseConfig` 会影响什么？”这样的问题，智能体通常要靠一长串 grep 和读文件才能回答。**Graphify** 插件用 Graphify-Labs 的开源工具 [graphify](https://github.com/Graphify-Labs/graphify) 把工作区转换为知识图谱：文件、函数、类、调用、 导入、Markdown 章节以及 `NOTE:` / `WHY:` 注释，并按子系统分组。已连接的智能体用自然语言或符号名向图谱 提问，一次调用就能得到图谱中相关的部分，每个结果都带有文件和行号。 卡片把图谱画成一张地图，智能体的每次查询都会在上面实时回放：你能看到智能体问了什么、从哪些节点出发、 搜索如何扩散、找到了什么。 ### 如何使用 1. 在添加卡片菜单中选择**插件…**，在**插件**标签页中打开 **Graphify**，然后点击**添加到画布**。 2. 点击卡片上的**安装**（每台电脑一次）。NeuroSquad 从 GitHub 下载 [uv](https://github.com/astral-sh/uv) 0.12.22，并按应用中固定的校验和进行核对；uv 配置独立的 Python 3.12，然后从 PyPI 安装 graphify 0.9.74， 每个包都按哈希固定（`--require-hashes`，仅使用二进制包）。约 250 MB，全部放在应用的数据文件夹中。 不会使用或修改你自己的 Python、uv 或 pip 设置。 3. 随后卡片会自动构建**整个工作区**的图谱，并显示已读取的文件数、总数和预计剩余时间。 4. 从智能体向卡片画一条[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)。 现在智能体就拥有了图谱工具。大多数 CLI 无需重启即可使用；删除箭头后工具随之消失。 ### 智能体能做什么 | 工具 | 回答什么 | | --- | --- | | `graphify_query` | 用自然语言或符号名提问 → 相关子图（符号、带行号的文件、调用和导入关系） | | `graphify_neighbors` | 某个符号调用了什么、被谁调用、导入了什么、被谁导入，以及每处使用的文件和行号 | | `graphify_path` | 两处之间最短的调用/导入链 | | `graphify_affected` | 修改的影响范围：所有直接或间接依赖某个符号或文件的内容 | | `graphify_node` | 某个符号的位置、类型和所属子系统 | | `graphify_community` | 某个子系统的全部成员 | | `graphify_god_nodes` | 连接最多的符号——代码库的核心 | | `graphify_stats` | 图谱规模，以及有多少关系是直接从代码中读出的 | | `graphify_reindex` | 立即更新图谱，以反映刚刚的修改 | 首次构建尚未完成时，工具会回答当前进度（“仍在构建：37%，已读 461 个文件中的 170 个…”），智能体可以先用 常规搜索，稍后再问。 ### 如何引导智能体使用图谱 拥有图谱工具的智能体并不总会用它：模型习惯了 grep。Graphify 增加了三层轻量引导，任何一层都不会阻止操作： - **工具描述**会说明何时图谱更合适（“当问题与结构有关时，先于 grep 使用”），以及何时文本搜索仍然是对的 （字符串字面量、日志信息、配置值）。在 Claude Code 中，`graphify_query`、`graphify_neighbors` 和 `graphify_affected` 始终加载，而不是藏在工具搜索后面。 - **首个回合的说明。** 带有箭头的会话的第一个回合会附上一段简短、客观的说明：图谱是什么、哪个工具回答 哪类问题、何时 grep 仍然合适。之后，当提示与代码结构有关时（以及无论如何每五个回合一次），会附上一行 提醒。删除箭头后，下一个回合会收到一条说明，告知这些工具已不可用。Claude Code、Codex 和 Qwen Code 通过提示钩子接收；OpenCode、Kilo Code、pi、omp 和 Gemini CLI 通过 NeuroSquad 的插件、扩展或钩子桥接接收。 其他 CLI 只获得工具。 - **文本搜索前的提示（Claude Code）。** 当智能体准备对看起来像符号名的内容执行 `Grep`、`Glob`，或 `grep` / `rg` / `find` 命令时，会收到一行上下文，指向 `graphify_neighbors` 和 `graphify_query`。 搜索仍会按原样执行：不做任何权限决定，你的 allow / deny 规则和确认提示照常生效。智能体使用图谱后的 两分钟内不会提示，之后最多每 45 秒、每四次搜索提示一次。 在卡片设置中关闭**引导智能体使用图谱**，即可只保留工具。 ### 地图 - **文件**显示为圆点，大小取决于内容多少，颜色取决于子系统。放大（或点击**显示符号**）即可看到每个文件 周围的函数和类。 - **实时查询。** 智能体查询图谱时，起始节点会泛起涟漪，搜索沿着经过的关系逐跳扩散，结果面板列出找到的 内容及文件和行号。点击结果可将地图定位到该处，或在编辑器中打开文件。 - 底部的**时间线**：最近的查询及提问者。点击即可重新回放。 - 在角落的输入框中自己**搜索**图谱，匹配项同样会亮起。 - **点击节点**查看详情和关系；**适应视图**让所有内容回到视野中。 - **展开**卡片，以大视图查看地图。 用鼠标拖动地图，用滚轮缩放；当你缩放画布或卡片不在屏幕上时，地图动画会暂停。 ### 始终保持最新 开启**自动更新**（默认开启）时，卡片会发现更改过的文件，并在最后一次更改约 4 秒后更新图谱。已连接的 智能体完成一个回合后，以及每次打开应用时，也会更新一次。graphify 会缓存读过的每个文件，因此更新只会重新 读取有变化的部分。关闭后可用**立即更新**手动更新。 ### 设置 卡片标题栏中的设置按钮： - **自动更新**和**引导智能体使用图谱**（见上文）。 - **语言**：从图谱中排除整门语言。 - **额外忽略**：额外的模式，每行一个，`.gitignore` 语法。项目中的 `.gitignore` 和 `.graphifyignore` 始终生效。 - **包含 git 忽略的文件**：适用于应进入图谱的生成代码。 更改索引范围会重新构建图谱。 ### WSL 和 SSH 工作区 - **WSL**：graphify 在 Windows 上运行，通过 Windows 路径读取发行版中的文件。位于 Windows 磁盘上的项目 （`/mnt/c/…`）照常监视文件；位于发行版自身磁盘上的项目，会在已连接智能体完成回合后以及点击**立即更新** 时更新。 - **SSH**：不支持，卡片会注明。请使用[代码图谱](https://docs.neurosquad.ai/zh/plugins/code-graph)插件，它会在 SSH 主机上运行自己的引擎。 ### Graphify 还是代码图谱？ 两者都会索引代码，但擅长回答的问题不同，可以同时使用。 | | 代码图谱 | Graphify | | --- | --- | --- | | 擅长 | 精确导航：调用者和被调用者、代码片段、只读 Cypher、语义搜索 | 用自然语言提问 → 相关子图、事物之间如何关联、修改会影响什么 | | 还会映射 | 路由、包 | 子系统、Markdown 章节、`NOTE:` / `WHY:` 注释 | | 卡片上 | 索引统计和搜索框 | 实时地图，动画展示每次查询 | | WSL / SSH | 在 WSL 内和 SSH 主机上运行 | WSL 通过 Windows 路径；不支持 SSH | > 图谱基于工作区文件夹构建。在隔离 worktree 中工作的智能体查询的仍是主文件夹的图谱。 ### 隐私与存储 一切都在你的电脑上运行。Graphify 只读取代码（不处理需要语言模型的文档、图片等内容），从不使用语言模型， 也不会向它传递任何 API 密钥。graphify 没有遥测，其可选的查询日志已关闭。引擎位于应用的数据文件夹中，每个 图谱位于其中的 `graphify/projects/<文件夹>-<哈希>/`。不会向你的项目或主目录写入任何内容。删除某个文件夹的 最后一张卡片会删除其图谱。 graphify 由 Graphify-Labs 开发，以 Apache License 2.0 发布。 ### 故障排除 - **在代理后安装失败。** uv 使用应用环境中的 `HTTPS_PROXY` / `HTTP_PROXY`；在启动 NeuroSquad 之前设置它， 然后再次点击**安装**。 - **安装失败，提示 “no matching distribution”。** 某个包没有适用于你系统的二进制包；graphify 不会从源码 构建。卡片会显示 uv 的消息。 - **“仍在构建”。** 非常大的工作区首次构建需要一些时间；卡片会显示进度，智能体提问时也会得到同样的进度。 - **智能体仍在使用 grep。** 检查箭头是否存在、**引导智能体使用图谱**是否开启，以及智能体的 CLI 是否属于 接收指引的那些（其他 CLI 会被卡片标为“仅工具”）。也可以直接要求它：“用 graphify 查找…”。 - **地图为空或缺少文件。** 检查设置中的**语言**和**额外忽略**，以及项目的 `.gitignore`。 - **卡片提示不支持 SSH。** SSH 工作区请使用代码图谱插件。 --- ## 设置 > NeuroSquad 设置中可以调整的内容，逐节说明。 Source: https://docs.neurosquad.ai/zh/settings 在侧边栏底部打开 **Settings**。所有更改立即生效。 - **Language**: English、Русский 或 中文——整个应用的界面语言。切换即时生效；在你选择之前，NeuroSquad 跟随系统语言。 - **General**: **Auto-reconnect**——智能体意外退出时自动重启。默认开启。 - **System**: **Keep agents running when the window is closed**——关闭窗口时 NeuroSquad 会隐藏到系统托盘而不是退出， 智能体继续工作，照样会通知你。默认关闭。 - **Notifications**: **Sound**（Chime、Ping 或 Marimba）、**Highlight**（及其颜色）、**System notifications**，以及可选的 用于 Slack 或 Discord 的 **Webhook**。参见[已完成 / 需要你输入](https://docs.neurosquad.ai/zh/agents/notifications)。 - **Dictation**: 语音转文字模型、CPU 或 GPU、**Dictation shortcut**，以及录音胶囊的 **Overlay position**。 参见[语音输入](https://docs.neurosquad.ai/zh/dictation)。 - **Canvas**: **Card overview when zoomed out** 及其切换时的缩放比例、**Alignment guides**、**Snap to grid**、**Minimap** 和 **Agent mascots**。参见[画布工具](https://docs.neurosquad.ai/zh/canvas/tools)。 - **Browser**: 浏览器卡片使用哪种浏览器——Chrome（默认）或 Firefox——以及下载或移除它。 - **Harnesses**: NeuroSquad 在你电脑上找到了哪些 AI 智能体。刚装了新的？按 **Check again**。 - **Setup**: 与首次启动向导相同的步骤：安装智能体、Git 或语音模型。 - **Providers**: 你的 OpenRouter 密钥、已花费的金额，以及模型目录。参见[模型提供商](https://docs.neurosquad.ai/zh/providers)。 - **Remote access**: 从手机远程访问——配对链接、端口、网络地址、互联网隧道。参见[远程访问](https://docs.neurosquad.ai/zh/remote)。 - **Shortcuts**: 键盘快捷键列表（`Ctrl Shift /`）。参见[键盘快捷键](https://docs.neurosquad.ai/zh/help/shortcuts)。 ### 在其他地方设置 - **Dangerous mode** 和 **canvas mode**——按智能体设置，在智能体卡片的 ⋯ 菜单中。 - **终端文字大小**——在任意终端上按住 `Ctrl` 滚动鼠标滚轮。 - **初始化命令、要复制的文件、运行命令、指令文件**——在每个工作区的编辑对话框中。 --- ## 卡片 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)**: 常见错误及修复方法。 > 卡片 SDK 刚刚推出。这里描述的一切都基于卡片协议第 1 版；有几件事被有意留到以后——卡片市场、自动更新、 > 完全没有外框就能运行的卡片、文件选择器，以及在手机上运行卡片代码。在相关的地方都会一一注明。 --- ## 安装社区卡片 > 什么是社区卡片，如何从 GitHub 安装，如何读懂权限对话框，以及如何更新、关闭、撤销权限或移除卡片。 Source: https://docs.neurosquad.ai/zh/card-sdk/community-cards 社区卡片是其他人用[卡片 SDK](https://docs.neurosquad.ai/zh/card-sdk) 开发并分享在 GitHub 上的卡片。它们集中在 **Settings → Custom cards** 中， 安装后就能像其他卡片一样从画布上添加。 ### 安装卡片 **1. 打开 Settings → Custom cards** 在 **Install a card** 下粘贴别人给你的 GitHub 地址。以下写法都可以： `owner/repo`、`owner/repo@v1.2.0`（标签、分支或提交）、`owner/repo/cards/pomodoro`（子文件夹中的卡片）， 或完整的 `https://github.com/…` 链接——包括 `/tree//` 或 `/releases/tag/` 形式的链接。 **2. 点击 Install 并阅读对话框** NeuroSquad 会下载这个确切的提交并进行检查，然后告诉你这张卡片是什么、要求做哪些事。此时还没有安装。 **3. 在对话框中点击 Install** 或者点击 **Cancel**——下载的内容会被丢弃。 **4. 把它添加到画布** 在添加菜单（画布或侧边栏上的 **+**）中选择 **Custom card…**，再选中它。 你想放几份都行，每一份都有自己的设置和数据。 > 想找已经有人检查过的卡片？[已验证卡片](https://docs.neurosquad.ai/zh/card-sdk/verified-cards)列表收录了经 NeuroSquad 团队审核的社区卡片， > 可以在 **Custom card…** 选择器的 **Verified** 标签页中直接安装。 ### 读懂安装对话框 - **名称、作者、版本**: 作者是**自称**的——卡片自己说是谁做的，没有人核实过。要信任的是仓库地址，而不是名字。 只有官方卡片可以自称“NeuroSquad”“official”或“verified”；其他卡片这样做会被应用拒绝。 - **来源与提交**: GitHub 仓库和将要安装的确切提交，并附有 **View source** 可查看那份代码。安装会锁定在这个提交上， 而且该提交必须属于仓库本身（位于它的默认分支上）：只存在于某个分叉中的提交会被拒绝。 改过名或迁移过的仓库，必须用它的新名称安装。 - **Community 或 Official**: 每张卡片都会标注 **Community code, not made or checked by NeuroSquad**（社区代码，非 NeuroSquad 制作或审核）—— 只有 NeuroSquad 团队在 GitHub 的 `glmn-ai` 组织下发布的卡片例外（按 GitHub 自己的账号 id 核对，而不只是看名称）， 它们带有 **Official** 徽章。 - **This card will be able to**: 它需要的[权限](https://docs.neurosquad.ai/zh/card-sdk/permissions)，**高风险的排在最前**，并且显示在卡片自己的描述之前，每项都有通俗的解释，通常还附有作者给出的理由。 这些权限要么全给、要么不装：安装卡片就意味着授予全部权限。 - **It may ask later for**: 可选权限。安装时**不会**授予；卡片需要时会在屏幕上询问，你可以拒绝。 - **工具与端口**: 它向你连接的智能体提供的工具，以及它有多少个用于箭头的数据端口。 > 最需要留意的是标为 **High risk** 的几行。能**向智能体下达指令**或**在终端中运行命令**的卡片， > 可以做那些智能体和终端能做的任何事——改你的代码、删文件、推送到 git。一张既能**读取文件**、 > 又能访问**任意网络地址**的卡片，就可能把你的项目文件发送出去。 ### 卡片永远做不到的事 无论它要求什么权限，卡片都被封闭在自己的方框里运行。它不能打开窗口，不能直接接触应用或其他卡片， 不能超出授权去读取你的文件或联网，不能显示系统通知，也不能在卡片之外绘制。应用会在每次调用时检查卡片发出的每一个请求。 参见[卡片永远不会越出画布](https://docs.neurosquad.ai/zh/card-sdk#cards-never-leave-the-canvas)。 **真正的 NeuroSquad 询问会让整个窗口变暗。** 每当卡片需要你做决定——确认操作、链接、权限、发给危险模式下智能体的提示词、 密钥——应用都会在它自己的对话框中询问，对话框标题为 **NeuroSquad is asking**，背后的遮罩连侧边栏和标题栏也一起变暗。 卡片只能在自己的方框里绘制，所以无法模仿这一点。卡片自己的文字在这种对话框里只会以引用的形式出现，而 **Cancel** 永远是应用的按钮。 **卡片正文里的一切都属于卡片自己。** NeuroSquad 从不在卡片里索要密码或 API 密钥。 卡片需要密钥时，你要通过卡片的 **Settings…** 输入（密钥字段会打开应用的对话框）——密钥会被加密保存， 只发送到你授权的互联网地址，卡片永远看不到它。 **你的智能体设置和仓库受到保护。** 即使卡片被允许修改文件，它也碰不到 `.git`、智能体的设置和指令 （`.claude/`、`.codex/`、`.cursor/`、`.mcp.json`、`CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`QWEN.md`……）、 编辑器和 CI 配置（`.vscode/`、`.idea/`、`.github/workflows/`、`.husky/`……）以及包管理器设置（`.npmrc`、`.yarnrc`……）。 而当工作区文件夹是你的主文件夹、某个磁盘的根目录，或包含 NeuroSquad 自己的数据时，任何卡片都得不到文件访问权限。 ### 使用卡片 - **箭头。** 大多数卡片在连接后能做更多事。卡片和智能体之间的箭头让卡片可以查看该智能体的屏幕或给它发提示词 （前提是有相应权限），也让智能体可以调用卡片的工具。两张卡片之间的箭头让数据沿端口从箭头尾部流向箭头头部。 - 卡片 **⋯** 菜单中的 **Settings…** 会打开卡片的设置（如果有的话）。有些设置由这张卡片的所有副本共享（表单中会标明）。 - **发给危险模式下智能体的提示词**总是需要你确认：应用会显示卡片想发送的内容，由你点击 **Send prompt** 或 **Cancel**。 如果你删掉箭头、撤销权限，或把智能体切换到危险模式，卡片为该智能体排队的提示词会被丢弃；队列中会显示每条提示词来自哪张卡片。 - 卡片想打开的**链接**会先完整显示出来；只允许 `https://` 链接，并且要在你点击 **Open link** 之后才会打开。 - **限制。** 无论以什么方式发送，一张卡片每分钟最多发送 6 条提示词和 30 条终端命令。 - **提醒。** 卡片需要你时会闪烁并出现在收件箱（Inbox）中——就像一个正在等待的智能体。它不能发出声音或系统通知。 - **暂停的卡片。** 一段时间没看的卡片（它所在的工作区已隐藏一分钟，或打开的卡片太多）会被暂停以节省内存， 回来时从中断的地方继续。拥有 **Keep running when you are not looking** 权限的卡片不会被暂停。 ### 更新 NeuroSquad 会在启动一分钟后检查新版本，之后每天检查一次（或在你点击 **Check for updates** 时检查）。 跟随分支安装的卡片会更新到该分支的最新提交；从发布版（release）安装的卡片跟随最新发布版；锁定到标签或提交的卡片永不更新。 **没有任何东西会自动更新。** 有可用更新时，**Settings → Custom cards** 中会显示 **Update**，卡片上也会出现一个小圆点。 点击它会显示变化内容——**新权限**、**将要连接的新地址**、**不再需要**的权限，以及它所提供内容的变化： 提供给智能体的新**工具**或措辞改变的工具、新增或改了类型的**端口**、新的**密钥设置**、变更的**名称、作者或主页**—— 并附有查看 GitHub 上代码改动的链接。只要更新涉及其中任何一项，它就会等你同意；在此之前旧版本照常运行。 ### 关闭、撤销、移除 在 **Settings → Custom cards** 中，每张已安装的卡片都有： - **Turned on** 开关——关闭后它的所有副本都会停止（卡片上显示“This card is turned off”），它的工具从智能体那里消失， 但不会删除任何东西。 - **权限**——点击任意权限旁的 **Revoke** 可以收回它。该卡片包的所有卡片会在没有这项权限的情况下重新加载。 - **Uninstall**——移除卡片包。你可以选择是否**同时从所有画布删除它的卡片**（默认勾选；否则它们会保留为 “package missing”占位卡片），以及是否**同时删除它保存的数据和密钥**（默认不勾选）。 ### 私有仓库与 GitHub 限流 GitHub 会限制未登录用户的下载频率。如果安装或检查更新时提示 GitHub 正在限流——或者你想从私有仓库安装—— 请在 **Settings → Custom cards** 中添加 **GitHub token**。它会被加密保存，永远不会给卡片看到。 ### 手机上的自定义卡片 使用[远程访问](https://docs.neurosquad.ai/zh/remote)时，自定义卡片在手机上显示为它的标题栏和摘要图块，并附有“Open on the computer to use this card”。 它的代码只在电脑上运行——你在手机上查看时，它的工具、端口和提示词依然在电脑上照常工作。 --- ## 已验证卡片 > 经 NeuroSquad 团队审核的社区卡片列表——在哪里找到它、Verified 徽章代表什么又不代表什么、已验证更新如何工作，以及作者如何提交卡片审核。 Source: https://docs.neurosquad.ai/zh/card-sdk/verified-cards 任何人都可以在 GitHub 上发布[社区卡片](https://docs.neurosquad.ai/zh/card-sdk/community-cards)，安装之前没有人检查过它。 **已验证卡片**（verified）是例外：它们是 NeuroSquad 团队阅读并试用过的社区卡片，每次审核的都是一个确切的版本。 这些卡片收录在一个公开目录中，应用可以直接从目录安装。 这个目录就是公开仓库 [glmn-ai/neurosquad-cards](https://github.com/glmn-ai/neurosquad-cards) 中的 `verified.json` 文件。每个条目都记录了审核的内容： - 卡片的名称和描述（英文、俄文和中文）、作者和许可证； - 它所在的位置——GitHub 仓库 `owner/repo`，以及可选的仓库内文件夹； - 审核的**版本**、审核的确切**提交**，以及该提交下卡片文件夹的**树哈希**（tree hash）； - 卡片使用的权限和网络地址； - 标签和分类——智能体、效率、开发工具、数据、集成、娱乐或其他； - 审核人、审核日期，以及审核备注。 应用会在启动时、每 6 小时一次以及你点击 **Refresh** 时下载这个列表。离线时，它显示上一次下载的副本； 全新安装时，则显示应用自带的副本。 ### 查找并安装已验证卡片 列表出现在两个地方：添加菜单（画布或侧边栏上的 **+**）中 **Custom card…** 选择器的 **Verified** 标签页， 以及 **Settings → Custom cards** 中的 **Verified cards** 部分。 搜索直接在你的电脑上进行，会匹配三种语言的名称、描述和标签。你也可以按分类筛选。 每一行显示卡片的图标、名称、描述、作者、分类和权限摘要，并带有一个按钮：**Install**、**Installed** 或 **Verified update**。 **1. 找到卡片** 打开 **Verified** 标签页或 **Verified cards** 部分，搜索或选择一个分类。 **2. 点击 Install** NeuroSquad 会下载**正好是审核过的那个提交**——而不是仓库里最新的代码——并把文件的树哈希与审核时的哈希比对。 如果不一致，安装会被拒绝：“文件与审核时的内容不同”。 **3. 阅读权限对话框并确认** 你会看到与其他卡片相同的[安装对话框](https://docs.neurosquad.ai/zh/card-sdk/community-cards#reading-the-install-dialog)。 已验证并不会跳过你的同意：卡片能否获得它要求的权限，仍然由你决定。 你仍然可以像以前一样，通过 GitHub 地址安装任何卡片。目录只是额外提供了一份有人看过的卡片列表。 ### Verified 徽章 已验证卡片带有 **Verified** 徽章——一个带对勾的盾牌：出现在目录行、安装对话框、**Settings → Custom cards** 中已安装的卡片上，以及卡片的 **About** 面板里。 它和 **Official** 徽章不同。Official 表示卡片由 NeuroSquad 团队从其 GitHub 上的 `glmn-ai` 组织发布； Verified 表示团队审核过这个版本。一张卡片可以同时拥有两个徽章。 只有以下三项都与列表中的当前条目一致时，才会显示徽章： - 卡片的来源——同一个仓库和文件夹； - 安装时所用的提交； - 文件的树哈希，与审核时的一致。 因此，从本地文件夹链接的卡片、从其他提交安装的卡片（例如某个分支的最新提交），或文件有差异的卡片，都不会显示徽章—— 即使它的另一个版本已经通过验证。 > **Verified** 的含义是：NeuroSquad 团队在某日审核过它的 X 版本。它不保证卡片没有缺陷或永远安全， > 也不代表其他任何版本。请像对待其他卡片一样认真阅读权限对话框。 ### 已验证更新 当列表把某张卡片指向一个更新的已审核版本时，**Settings → Custom cards** 会为它显示 **Verified update available**。 点击后，会通过常规的[更新对话框](https://docs.neurosquad.ai/zh/card-sdk/community-cards#updates)安装正好是那个已审核的提交，对话框会显示卡片权限有哪些变化。 任何更新都不会自动进行。 如果某张卡片从列表中移除，它的徽章会消失，并显示一条中性的提示，说明它已不在已验证列表中。 卡片仍然保持安装并继续工作；是否保留由你决定。 ### 在手机上 通过[远程访问](https://docs.neurosquad.ai/zh/remote)，你可以在手机上浏览已验证列表，但不能从中安装：只能在电脑上安装。 ### 面向卡片作者：让你的卡片通过验证 验证方式是向 [glmn-ai/neurosquad-cards](https://github.com/glmn-ai/neurosquad-cards) 提交一个 pull request， 在 `verified.json` 中添加你的卡片条目。确切的规则和条目格式见该仓库的 [CONTRIBUTING.md](https://github.com/glmn-ai/neurosquad-cards/blob/HEAD/CONTRIBUTING.md)——提交 pull request 之前请先阅读。 **4. 发布卡片** 卡片必须位于**公开**的 GitHub 仓库中，并在**默认分支**上。参见[发布与更新](https://docs.neurosquad.ai/zh/card-sdk/publishing)。 **5. 获取提交和树哈希** 选定你希望审核的确切提交。要获取树哈希，在该提交下对卡片文件夹运行 [`neurosquad-card pack`](https://docs.neurosquad.ai/zh/card-sdk/cli#pack)——它会打印出应用在安装时记录的树哈希。 **6. 提交 pull request** 按 CONTRIBUTING.md 的说明，把你的条目加入 `verified.json`——名称和描述、仓库和文件夹、版本、提交、树哈希、 权限、网络地址、标签、分类、许可证。 **更新已验证卡片**需要再提交一个 pull request，更新版本、提交和树哈希。每个版本都会重新审核； 在新版本被接受之前，用户的徽章仍停留在已审核的版本上，这期间你推送的代码不会作为已验证更新提供给用户。 #### 审核时检查什么 - 该提交下的全部源代码。不允许混淆代码，也不允许只有压缩代码而没有源代码。 - 权限和网络地址是卡片所需的最小集合，并且与条目一致。 - 工具和端口的描述真实可信。 - 清单文件与条目一致——名称和版本。 - 树哈希可以复现。 - 卡片带有许可证。 - 它能在当前版本的应用上安装并正常工作。 - 它不冒充 NeuroSquad 或任何其他品牌。 - 除已声明的内容外，它不做任何追踪。 [安全检查清单](https://docs.neurosquad.ai/zh/card-sdk/security)涵盖了其中大部分内容——提交之前请逐项检查。 --- ## 快速上手 > 用模板创建卡片，在 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"

…

``` ```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)**: 在分享之前。 --- ## 清单文件参考 > neurosquad-card.json 的每个字段——身份信息、大小、权限、设置表单、端口和工具——以及应用会检查的规则。 Source: https://docs.neurosquad.ai/zh/card-sdk/manifest 每张卡片的文件夹根目录都有一个 `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` 导出。 ### 完整示例 ```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 个字符 | 包的短名。它是卡片[工具名](https://docs.neurosquad.ai/zh/card-sdk/api/tools)的前缀，也是自定义端口类型的命名空间。保留名（内置卡片和工具族）：`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` | | 字符串 ≤ 100 | SPDX 标识符，例如 `MIT`。 | | `homepage` | | `https://` URL | | | `keywords` | | ≤ 20 个不重复字符串，每个 ≤ 40 个字符 | | | `icon` | | 包内 `.png` 或 `.webp` 的路径 | 正方形，≤ 128 KB（128×128 或更大会更清晰）。安装时会按文件字节检查。没有图标时卡片显示一块拼图。 | | `minAppVersion` | | SemVer | 能运行这张卡片的最低 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` ```json "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()`](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#resize) 同样会被限制在这个范围内。 ### 权限——`permissions` 权限 id 的列表（≤ 32 项），或带有附加信息的对象： ```json "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` | [权限](https://docs.neurosquad.ai/zh/card-sdk/permissions)页面列出的 id 之一。 | | `hosts` | 仅用于 `network`，且在那里必填：≤ 32 个主机模式。 | | `reason` | 多语言文本 ≤ 300，显示在安装对话框中该权限的下方。说明为什么需要。 | | `optional` | `true` = 安装时不询问；卡片在运行时通过 [`card.permissions.request()`](https://docs.neurosquad.ai/zh/card-sdk/api/environment#permissions) 申请。 | 必需权限在安装时要么全给、要么不装。同一个 id 列出两次会被合并（必需的条目优先于可选的）。 `network` 的**主机模式**：只能是小写主机名——`api.example.com`、`api.example.com:8443`（443 以外的端口）， 或 `*.example.com`（任意子域名，不含 `example.com` 本身）。不能写协议、路径、IP 地址、单独的 `*` 或 `localhost`—— 本机访问是单独的 `network.local` 权限。 ### 设置表单——`settings` 最多 40 个字段。表单由应用绘制（从卡片的 **⋯ → Settings…** 打开，或调用 [`card.settings.open()`](https://docs.neurosquad.ai/zh/card-sdk/api/storage-settings#settings)）；卡片读取其中的值。 ```json "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。必须唯一。 | | `type` | `string`（单行）、`text`（多行）、`number`、`boolean`、`select`、`color`（`#rrggbb`）、`secret`。 | | `label`、`description`、`placeholder` | 多语言文本（≤ 80、≤ 300、≤ 80）。 | | `default` | 与字段类型一致。`select` 必须是选项之一，`color` 必须是 `#rrggbb`，`number` 必须在 `min`/`max` 之间。**`secret` 不允许有默认值。** | | `required` | 不填就无法保存表单。 | | `scope` | `instance`（默认）：画布上的每张卡片各一份。`package`：这个卡片包的所有卡片共享。 | | `maxLength` | 用于 `string`、`text`、`secret`。默认：`string` 为 2 000，`text` 为 20 000。 | | `min`、`max`、`step` | 用于 `number`。 | | `options` | 仅用于 `select`，1–50 个 `{ "value", "label" }`。 | **密钥**（secret）只能在应用的表单中输入，加密保存，永远不会到达卡片：卡片只能知道它是否已设置， 并通过[网络请求头](https://docs.neurosquad.ai/zh/card-sdk/api/network#secrets)中的 `{{secret:}}` 占位符来使用它。 ### 端口——`ports` 通过箭头的类型化数据连接：最多 16 个 `inputs` 和 16 个 `outputs`。完整指南：[端口](https://docs.neurosquad.ai/zh/card-sdk/api/ports)。 ```json "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:*` 类型，或自定义的 `/`。 | | `schema` | 两者 | 值还必须满足的额外 JSON Schema。**自定义类型必须提供。** | | `mode` | 输入 | `stream`（默认）：发出即不管的消息。`request`：发送方会等待回复。 | | `response` | 请求型输入 | `{ "type", "schema"? }`——回复的类型。`mode: "request"` 时必填。 | | `default` | 输入 | 当对端的某个输出可匹配多个输入时优先选用的输入。最多一个。 | | `retain` | 输出 | 应用会保留最后一个值：对端随时可以读取，新连接的对端会收到一次。 | 允许使用另一个卡片包命名空间下的自定义类型（会给出警告）——两张卡片正是这样约定共享格式的。 ### 工具——`tools` 最多 32 个可供与卡片相连的智能体调用的工具。指南：[给智能体的工具](https://docs.neurosquad.ai/zh/card-sdk/api/tools)。 | 键 | 含义 | | --- | --- | | `name` | `a-z`、数字、`_`，以字母开头，≤ 40。智能体看到的是 `_`，例如 `test_radar_run_tests`。这个对外名称不能与 NeuroSquad 的内置工具（`canvas_spawn_card`、`terminal_send_keys`……）同名，也不能包含 `__`。 | | `title` | ≤ 80，给人看的标题。 | | `description` | ≤ 2 000，**写给模型看**，用英文：它做什么、返回什么。 | | `inputSchema` | `"type": "object"` 的 JSON Schema。属性 `card` 被保留（由应用添加）。 | | `readOnly` | 工具不会改变任何东西时设为 `true`——会作为提示展示给智能体。 | | `timeoutMs` | 1 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/`）、`$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 中的那份副本。 --- ## 权限 > 卡片的十三项权限——每项的风险、用户在安装时看到的原话、它解锁的能力，以及应用强制执行的范围规则。 Source: https://docs.neurosquad.ai/zh/card-sdk/permissions 没有任何权限的卡片可以在自己的方框里绘制、使用[存储](https://docs.neurosquad.ai/zh/card-sdk/api/storage-settings)、读取自己的设置、设置自己的标题栏， 但不能和任何人交换任何东西。其余一切都是你在[清单文件](https://docs.neurosquad.ai/zh/card-sdk/manifest#permissions)中声明、由用户授予的权限。 授权的工作方式： - **按卡片包授予，每次请求都检查。** 用户把权限授予你的卡片包（它在所有画布上的每一份副本）。 应用会在每一次调用时检查授权——检查发生在应用里，而不是在 SDK 或你的卡片里。 - **必需权限在安装时要么全给、要么不装。** 安装对话框把它们按高风险在前的顺序列出。拒绝就意味着不安装。 - **可选权限在运行时申请**（`"optional": true`）。在卡片显示在屏幕上时调用 [`card.permissions.request()`](https://docs.neurosquad.ai/zh/card-sdk/api/environment#permissions)；应用会用它自己覆盖整个窗口的对话框询问，用户可以拒绝。 - **有些权限包含其他权限。** `fs.write` 包含 `fs.read`；`agents.output`、`agents.prompt` 和 `terminals.write` 包含 `agents.read`。 - **用户可以随时撤销**任何权限（在 **Settings → Custom cards** 中）。卡片的页面会以缩小后的授权重新加载， 并收到 `permissions.changed` 事件；代码要做好防御。 - **新增权限或网络主机的更新**需要用户同意后才会生效。你去掉的权限会被撤销。 - **箭头就是对数据的同意。** 涉及另一张卡片、智能体或终端的权限，只对通过[箭头](https://docs.neurosquad.ai/zh/canvas/arrows)与你的卡片相连的卡片生效—— 方向不限，除非另有说明。 缺少权限时调用会以 `PERMISSION_DENIED` 失败（`error.permission` 会给出缺的是哪一项）。 ### 一览 | 权限 | 风险 | 解锁 | | --- | --- | --- | | `agents.read` | 低 | `agents.list/get`、状态/轮次/变更事件、智能体的 `status` 端口 | | `agents.output` | 高 | 读取**相连**智能体和终端的屏幕与回复 | | `agents.prompt` | 高 | 向**相连**的 AI 智能体发送提示词 | | `terminals.write` | 高 | 在**相连**的终端中运行命令 | | `cards.connected` | 中 | 读取和修改**相连**的笔记、待办清单、任务看板、便签 | | `network` + 主机 | 中 | 对列出的主机使用 `net.fetch` | | `network.local` | 高 | 对本机上的服务器使用 `net.fetch` | | `fs.read` | 高 | 读取工作区文件夹中的文件 | | `fs.write` | 高 | 写入工作区文件夹中的文件（包含 `fs.read`） | | `clipboard.write` | 低 | 把文本复制到剪贴板 | | `canvas.spawn` | 低 | 在自己旁边添加最多 4 张卡片 | | `background` | 低 | 没人看时也保持运行 | | `usage.read` | 低 | 工作区的令牌用量和费用 | ### 逐项说明 #### `agents.read` — low **用户看到：** *See the agents on this canvas.*（查看此画布上的智能体）它们的名称、运行的工具，以及正在工作、等待你还是已完成。 **解锁：** [`card.agents.list()` / `get()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents)、事件 `agents.status`、`agents.turn`、`agents.changed`， 以及内置智能体的 `status` 输出端口。 **范围：** 卡片所在工作区的 AI 智能体和终端。其他卡片不是智能体，不会被列出。 #### `agents.output` — high **用户看到：** *Read what agents and terminals connected to it print.*（读取与其相连的智能体和终端的输出） 用箭头与它相连的智能体和终端卡片屏幕上的所有内容，包括其中显示的任何机密信息。 **解锁：** `card.agents.readScreen()`、`card.agents.lastReply()`、用 `card.agents.onOutput()` 获取实时输出， 以及智能体的 `reply` 和终端的 `exit` 输出端口。 **范围：** 仅限用箭头相连的智能体和终端。包含 `agents.read`。 #### `agents.prompt` — high **用户看到：** *Give instructions to agents connected to it.*（向与其相连的智能体下达指令） 向用箭头与它相连的 AI 智能体输入并发送提示词。智能体可以编辑文件和运行命令，所以此卡片可以让它做智能体能做的任何事。 **解锁：** [`card.agents.prompt()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#prompting) 和智能体的 `prompt` 输入端口。 **范围：** 用箭头相连的 **AI** 智能体（不含终端）。提示词会经过提示词队列和工作区[预算](https://docs.neurosquad.ai/zh/cards/budget)， 每张卡片每分钟最多 6 条（该方法和智能体的 `prompt` 端口合并计数）；每条都会显示在箭头上并记入箭头日志。 发给[危险模式](https://docs.neurosquad.ai/zh/agents/dangerous-mode)下智能体的每条提示词，都要等用户在卡片上确认。包含 `agents.read`。 #### `terminals.write` — high **用户看到：** *Run commands in terminals connected to it.*（在与其相连的终端中运行命令） 在用箭头与它相连的终端卡片中输入并运行命令——任何你自己能运行的命令。 **解锁：** [`card.terminals.run()` 和 `write()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#terminals)，以及终端的 `command` 输入端口。 **范围：** 用箭头相连的终端卡片（bash、PowerShell、cmd）。每张卡片每分钟最多 30 条命令，`run` 和终端的 `command` 端口合并计数； `write` 每分钟最多 60 次。每条命令都会显示在箭头上。包含 `agents.read`。 #### `cards.connected` — medium **用户看到：** *Read and change cards connected to it.*（读取和修改与其相连的卡片）用箭头与它相连的笔记、清单、任务看板和便签。 **解锁：** 笔记、待办清单、任务看板和便签的[内置卡片端口](https://docs.neurosquad.ai/zh/card-sdk/api/ports#built-in-cards)——向笔记追加内容、添加任务、读取清单。 **范围：** 用箭头相连的这四类卡片。 #### `network` — medium, needs `hosts` **用户看到：** *Connect to `api.github.com`, `*.example.com`.*（连接到这些主机）只与这些互联网地址收发数据。 卡片能看到的任何内容都可能被发送到那里。 **解锁：** 通过 `https` 对这些主机使用 [`card.net.fetch()`](https://docs.neurosquad.ai/zh/card-sdk/api/network)。 **范围：** 严格限于声明的主机模式，且只允许公网地址——解析到私有、回环或云元数据地址的主机会被拒绝，每次重定向也同样检查。 第 1 版中，卡片无法申请“任意主机”。 #### `network.local` — high **用户看到：** *Connect to servers on this computer.*（连接到本机上的服务器）访问在 localhost 上监听的程序，例如开发服务器和本地数据库。 **解锁：** 通过 `http` 或 `https` 对 `localhost`、`127.0.0.1` 和 `::1` 使用 `card.net.fetch()`。 **范围：** 除 NeuroSquad 自己的服务器以外的任何端口：它的 MCP 服务器、远程访问服务器、开发者链接服务器、 每张浏览器卡片中 Chrome 的调试端口，以及应用自身的开发服务器。发往本机的请求永远不会填入[密钥占位符](https://docs.neurosquad.ai/zh/card-sdk/api/network#secrets)。 #### `fs.read` — high **用户看到：** *Read files in the workspace folder.*（读取工作区文件夹中的文件）此工作区项目文件夹中的任何文件，包括 `.env` 等文件中保存的机密。 **解锁：** [`card.fs.stat/list/read*/watch()`](https://docs.neurosquad.ai/zh/card-sdk/api/files)，以及 `card.workspace` 中工作区的绝对路径 `path`。 **范围：** 工作区文件夹。路径相对于它；`..` 和绝对路径会被拒绝，指向文件夹外部的链接也会被拒绝。 如果工作区文件夹是用户的主文件夹、某个磁盘的根目录，或包含 NeuroSquad 自己的数据文件夹，所有文件调用都会被拒绝。 #### `fs.write` — high **用户看到：** *Change files in the workspace folder.*（修改工作区文件夹中的文件）在此工作区的项目文件夹中创建、覆盖文件或将其移入回收站。 此工作区的智能体会读取并运行这些文件，因此此卡片可以让它们执行命令。受保护：.git、智能体设置（.claude、.mcp.json、CLAUDE.md、AGENTS.md 等）以及 NeuroSquad 自身的数据。 **解锁：** `card.fs.writeText/writeBytes/mkdir/trash()`。 **范围：** 同 `fs.read`，但不包括[受保护的路径](https://docs.neurosquad.ai/zh/card-sdk/api/files#protected)：任何 `.git`、智能体和编辑器的设置、CI 工作流。 没有彻底删除——`trash` 会移入系统回收站。包含 `fs.read`。 #### `clipboard.write` — low **用户看到：** *Copy to your clipboard.*（复制到剪贴板）用卡片中的文本替换剪贴板内容。 **解锁：** [`card.copyText()`](https://docs.neurosquad.ai/zh/card-sdk/api/files#clipboard)，每秒一次。无法读取剪贴板。 #### `canvas.spawn` — low **用户看到：** *Add cards next to itself.*（在旁边添加卡片）在画布上它的旁边放置最多 4 张新卡片。 **解锁：** [`card.spawn()`](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#spawn)——你的卡片的另一份副本，或一篇笔记、待办清单、任务看板、便签，并用箭头与它相连。 **范围：** 每张卡片 4 张、每分钟 4 张，并受工作区卡片数量上限约束。 #### `background` — low **用户看到：** *Keep running when you are not looking.*（在你不看时继续运行）在其工作区隐藏时保持活动。会消耗更多内存和电量。 **解锁：** 卡片在隐藏时不会被[暂停](https://docs.neurosquad.ai/zh/card-sdk/api/environment#lifecycle)。 **范围：** 整个应用中最多 8 张这样的卡片在后台运行；超出后，最久未被看到的仍会被暂停。 #### `usage.read` — low **用户看到：** *See token usage and costs.*（查看令牌用量和费用）此工作区的智能体用了多少令牌以及花费多少。 **解锁：** [`card.usage()`](https://docs.neurosquad.ai/zh/card-sdk/api/files#usage)，以及对用箭头连接的智能体使用 [`card.agents.usage()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#usage)。 **范围：** 卡片自己所在的工作区。 ### 安装对话框中除权限外还列出什么 以下内容由清单推导得出，并不是权限：卡片向相连智能体提供的[工具](https://docs.neurosquad.ai/zh/card-sdk/api/tools)名称，以及它有多少个输入和输出端口。 可选权限出现在 **It may ask later for** 之下。 > 只申请你需要的最少权限。每一行高风险都会让谨慎的用户犹豫，而缺少 `reason` 会让他们只能去猜。 > 如果某个功能只是偶尔需要一项强权限，就把它设为可选，等用户真正要用这个功能时再申请。 --- ## connect() 与卡片对象 > 把卡片连接到 NeuroSquad、类型化的 Card 对象、它实时更新的上下文，以及调用任意方法、监听任意事件。 Source: https://docs.neurosquad.ai/zh/card-sdk/api 卡片做的一切都经过同一个对象——**card**，你从 `connect()` 得到它： ```ts import { connect } from '@neurosquad/card-sdk' const card = await connect() card.setStatus(`Hello, ${card.workspace.name}`, { tone: 'success' }) ``` `connect()` 会等待应用把卡片的专用通道交过来，完成自我介绍，然后返回一个 [`Card`](#the-card-object)。再次调用会返回同一个 card。 > **请在入口脚本中导入 SDK。** SDK 一加载就开始监听应用的握手消息。延迟加载 SDK 的卡片（例如在定时器之后动态 `import()`） > 可能会错过握手，并以 `UNAVAILABLE` 失败。 ### `connect(options?)` ```ts import { connect } from '@neurosquad/card-sdk' const card = await connect({ theme: true, // apply the app theme as --ns-* CSS variables on (default true) syncLang: true, // keep equal to the app language (default true) forwardErrors: true, // send uncaught errors and rejections to the card log (default true) timeoutMs: 10_000 // how long to wait for the app (default 10 000) }) ``` | 选项 | 默认值 | 含义 | | --- | --- | --- | | `theme` | `true` | 设为 `false` 则不改动你的 CSS；传入一个元素则把 `--ns-*` 变量写到该元素上，而不是 ``。参见[主题](https://docs.neurosquad.ai/zh/card-sdk/api/environment#theme)。 | | `syncLang` | `true` | 让 `` 始终与应用语言一致。 | | `forwardErrors` | `true` | 把 `error` 和 `unhandledrejection` 转发到[卡片日志](https://docs.neurosquad.ai/zh/card-sdk/api/environment#log)。 | | `timeoutMs` | `10000` | 等待应用通道、再等待应用应答的时长。 | | `port` | — | 使用这个通道，而不是等待应用——用于[模拟宿主](https://docs.neurosquad.ai/zh/card-sdk/testing)。 | 它会以 [`CardSdkError`](https://docs.neurosquad.ai/zh/card-sdk/api/errors) 拒绝： - `UNAVAILABLE`——页面不在 NeuroSquad 卡片里（在浏览器中单独打开）。要预览，请像模板那样使用[模拟宿主](https://docs.neurosquad.ai/zh/card-sdk/testing)。 - `PROTOCOL_MISMATCH`——应用比你的 SDK 使用的卡片协议旧。卡片会显示“needs a newer NeuroSquad”。 ### 卡片对象 | 成员 | 说明 | | --- | --- | | `card.context` | 应用告诉卡片的一切，[实时更新](#context)。 | | `card.setTitle / setStatus / setBadge / setOverview / attention / requestResize / openLink / focusCard / spawn` | [卡片外框](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui) | | `card.ui` | [提示条、确认对话框、卡片菜单](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#ui) | | `card.storage` | [每卡片与每卡片包的存储](https://docs.neurosquad.ai/zh/card-sdk/api/storage-settings#storage) | | `card.settings` | [设置表单的值](https://docs.neurosquad.ai/zh/card-sdk/api/storage-settings#settings) | | `card.agents` | [智能体、状态、输出和提示词](https://docs.neurosquad.ai/zh/card-sdk/api/agents) | | `card.terminals` | [在相连终端中执行命令](https://docs.neurosquad.ai/zh/card-sdk/api/agents#terminals) | | `card.ports` | [与相连卡片交换类型化数据](https://docs.neurosquad.ai/zh/card-sdk/api/ports) | | `card.tools` | [给相连智能体的工具](https://docs.neurosquad.ai/zh/card-sdk/api/tools) | | `card.net` | [经由应用代理的 HTTP](https://docs.neurosquad.ai/zh/card-sdk/api/network) | | `card.fs` | [工作区文件夹中的文件](https://docs.neurosquad.ai/zh/card-sdk/api/files) | | `card.permissions` | [授权状态、申请可选权限](https://docs.neurosquad.ai/zh/card-sdk/api/environment#permissions) | | `card.lifecycle` | [可见性、暂停、展开、调整大小](https://docs.neurosquad.ai/zh/card-sdk/api/environment#lifecycle) | | `card.log` | [写入卡片日志](https://docs.neurosquad.ai/zh/card-sdk/api/environment#log) | | `card.copyText / usage / getWorkspace / getTheme / getI18n` | [剪贴板、用量](https://docs.neurosquad.ai/zh/card-sdk/api/files)、获取最新快照 | | `card.host` | [功能检测](#feature-detection) | | `card.call / on / once / waitFor` | [任意方法、任意事件](#any-method-any-event) | | `card.close() / closed` | 关闭通道；之后的调用会以 `UNAVAILABLE` 失败。 | ### 上下文 `card.context` 是一个 `HostContext`：卡片连接时应用发来的内容，并**随每个事件更新**（可见性、大小、主题、语言、设置、权限、对端）。 每次变化时整个对象都会被替换，而不是原地修改——因此可以放心地配合 React 的 `useSyncExternalStore` 使用。 ```ts import type { HostContext } from '@neurosquad/card-sdk' function describe(context: HostContext): string { const { instance, workspace, visibility, i18n, launch } = context return `${instance.displayName} ${instance.version} in "${workspace.name}", ${visibility}, ${i18n.language}, started: ${launch}` } card.onContextChange((context) => render(describe(context))) ``` | 字段 | 类型 | 含义 | | --- | --- | --- | | `instance` | `CardInstanceInfo` | `instanceId`（这张卡片在画布上的 id）、`packageId`、`name`、`displayName`、`version`、`commit`（链接文件夹时为 `null`）、`title`、`size`、`dev`。 | | `workspace` | `WorkspaceInfo` | `id`、`name`，以及仅在有 `fs.read` 时提供的 `path`（绝对路径）。 | | `visibility` | `'visible'`、`'offscreen'`、`'overview'` 或 `'hidden'` | 参见[生命周期](https://docs.neurosquad.ai/zh/card-sdk/api/environment#lifecycle)。 | | `expanded` | `boolean` | 卡片是否已展开铺满画布。 | | `theme` | `ThemeSnapshot` | 应用的颜色、圆角和字体。 | | `i18n` | `{ language, locale }` | `en`、`ru` 或 `zh`，以及用于 `Intl` 的 locale。 | | `settings` | `SettingsSnapshot` | `values`，以及 `secrets`（哪些密钥已设置）。 | | `permissions` | `PermissionState[]` | 每项已声明的权限及其 `granted`、`optional`、`hosts`、`reason`。 | | `ports` | `{ inputs, outputs }` | 你自己的端口，标签已解析为当前语言。 | | `peers` | `PeerInfo[]` | 通过箭头相连的卡片。 | | `launch` | `'created'`、`'opened'`、`'resumed'`、`'reloaded'` 或 `'updated'` | 这次页面启动的原因。 | | `spawnInit` | JSON 或不存在 | [创建](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#spawn)这张卡片的卡片传来的数据，仅在首次启动时提供。 | | `chrome` | `CardChromeState` 或不存在 | 应用此刻为这张卡片显示的内容——`title`、`status`、`badge`、`overview`、`attention`——在重新加载之间保留。参见[卡片外框](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#attention)。旧版本的应用中不存在。 | | `appVersion` | `string` | NeuroSquad 的版本。 | | `limits` | `LIMITS` | 协议的所有限制，参见[限制](https://docs.neurosquad.ai/zh/card-sdk/api/errors#limits)。 | | `protocol` | `number` | 应用使用的卡片协议。 | card 上的快捷属性：`card.instanceId`、`card.instance`、`card.workspace`、`card.visibility`、`card.expanded`、`card.size`、 `card.theme`、`card.i18n`、`card.language`、`card.launch`、`card.spawnInit`、`card.limits`、`card.appVersion`。 **`launch`** 告诉你发生了什么：`created`（刚被添加到画布）、`opened`（打开了工作区）、`resumed`（[暂停](https://docs.neurosquad.ai/zh/card-sdk/api/environment#lifecycle)后恢复）、 `reloaded`（用户点了 Reload、开发模式下文件有改动，或某项权限被撤销）、`updated`（安装了你的卡片的新版本）。 ### 任意方法、任意事件 各个命名空间只是两个基本操作的语法糖，这两个操作都根据协议完整地带有类型： ```ts // Any method: params and result are typed from the method name. const { keys } = await card.call('storage.keys', { scope: 'instance', prefix: 'draft:' }) const info = await card.call('card.getInfo') // Any event: the payload is typed from the event name. Returns a function that removes the listener. const off = card.on('agents.turn', (turn) => { if (turn.phase === 'end') render(`${turn.agentId} finished a turn`) }) off() // Once, or as a promise. card.once('lifecycle.expanded', ({ expanded }) => render(expanded)) const next = await card.waitFor('agents.status', (e) => e.status === 'needs-input', { timeoutMs: 60_000 }) render(next.agentId) ``` 可订阅的主题（`agents.status`、`agents.turn`、`agents.changed`、`storage.changed`）会在至少有一个监听器时自动向应用订阅， 最后一个监听器移除时自动退订。`agents.output` 需要智能体 id——请使用 [`card.agents.onOutput()`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#output)。 如果某个主题需要你没有的权限，监听器只是收不到任何东西，同时卡片日志中会出现一条警告。 可能在你添加监听器之前就到达的事件——`ports.message`、`ui.menu`、`fs.changed`——会被暂存（最多 100 条）并交给第一个监听器， 所以在 `connect()` 和你的 `on()` 之间不会丢失任何东西。 #### 全部事件 | 事件 | 负载 | 何时发生 | | --- | --- | --- | | `lifecycle.visibility` | `{ state }` | 可见性变化。 | | `lifecycle.suspend` | `{ graceMs }` | 页面即将被卸载。请使用 `card.lifecycle.onSuspend`。 | | `lifecycle.expanded` | `{ expanded }` | 展开或还原。 | | `lifecycle.resized` | `{ w, h }` | 卡片大小被调整。 | | `settings.changed` | `SettingsSnapshot` | 设置改变（表单或 `settings.set`）。 | | `theme.changed` | `ThemeSnapshot` | 应用主题改变。 | | `i18n.changed` | `{ language, locale }` | 应用语言改变。 | | `permissions.changed` | `PermissionState[]` | 某项授权改变。 | | `ui.menu` | `{ id }` | 你添加的某个菜单项被选中。 | | `ports.message` | 见[端口](https://docs.neurosquad.ai/zh/card-sdk/api/ports#receiving) | 某个输入收到了值。 | | `ports.request` | 见[端口](https://docs.neurosquad.ai/zh/card-sdk/api/ports#requests) | 对端向请求型输入提问。请使用 `card.ports.onRequest`。 | | `ports.peersChanged` | `PeerInfo[]` | 箭头或对端发生变化。 | | `tools.call`、`tools.cancel` | 见[工具](https://docs.neurosquad.ai/zh/card-sdk/api/tools) | 智能体调用工具。请使用 `card.tools.handle`。 | | `net.chunk` | 见[网络](https://docs.neurosquad.ai/zh/card-sdk/api/network#streaming) | 流式响应的一个分块。请使用 `response.chunks()`。 | | `fs.changed` | `{ watchId, path, type }` | 被监视的文件发生变化。请使用 `card.fs.watch`。 | | `storage.changed` | `{ scope, key, byInstance }` | 卡片的另一份副本写入了包级键。主题。 | | `agents.status` | `{ agentId, status, at }` | 智能体状态变化。主题，需 `agents.read`。 | | `agents.turn` | `{ agentId, phase, at }` | 一轮开始或结束。主题，需 `agents.read`。 | | `agents.changed` | `{ agents }` | 智能体被添加、移除或重命名。主题，需 `agents.read`。 | | `agents.output` | `{ agentId, text, at }` | 相连智能体的输出。需 `agents.output`。 | | `host.ping` | `{ seq }` | 心跳——SDK 会替你应答。 | ### 功能检测 新方法和新事件会在同一协议版本内陆续加入。使用用户的应用可能还没有的功能之前，请先检查： ```ts if (await card.host.supports('usage.summary')) { const usage = await card.usage('today') render(usage.totalCostMicroUsd) } const { protocol, methods, events } = await card.host.capabilities() render(protocol, methods.length, events.length) // A method newer than your SDK's types: const result = await card.callUnchecked('some.newMethod', { any: 'params' }) render(result) ``` ### 约定 - **Id。** 卡片和智能体的 id 就是画布上的 id——与你从 `card.ports.peers`、`card.agents.list()` 或 `card.spawn()` 拿到的 `cardId` 相同。 - **相连**指两张卡片之间有一条箭头，方向不限。端口还会额外关心方向（参见[端口](https://docs.neurosquad.ai/zh/card-sdk/api/ports#direction)）。 - **每次调用都检查两遍。** SDK 用与应用相同的 schema 校验参数，出错时立即以 `INVALID_PARAMS` 失败并给出精确路径； 应用会再检查一遍，外加权限、可见性、箭头和速率限制。 - **只有 JSON 能跨越边界。** 不能传 `Blob` 或 `ArrayBuffer`：接受字节的辅助方法（`fs.writeBytes`、`net.fetch` 的请求体）会替你编码为 base64。 - **回复可能乱序到达；** 事件则按应用发送的顺序到达。 - **永远不要信任 `window` 的 `message` 事件。** 画布上的任何其他卡片都能对你的框架调用 `postMessage`。唯一可信的通道是 SDK 在 `connect()` 时从应用收到的那个； 不要自己添加根据收到的内容行事的 `message` 监听器。 --- ## 卡片外框与对话框 > 卡片的标题栏——标题、状态、徽章——概览图块、提醒、调整大小、链接、镜头聚焦和创建卡片；提示条、确认对话框和卡片菜单。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/card-ui 卡片的标题栏、概览图块和对话框都由**应用**绘制，而不是你的页面——因此它们看起来是原生的，在卡片暂停时依然有效，也会显示在手机上。你只负责设置内容。 **想调用多少次都行。** 应用会对这些更新限流（标题每分钟 30 次；状态、徽章和概览各每分钟 120 次；提醒每 10 秒一次）， 而 SDK 会替你消化这些限制：对于 `setTitle`、`setStatus`、`setBadge`、`setOverview` 和 `attention`，每个方法同一时间只发送一个调用， 期间发起的调用会合并成一个、只保留最新的值，应用返回 `RATE_LIMITED` 时还会重试最新的值。它们永远不会因为限流而抛出异常—— 每次渲染都更新也没问题。没有改变任何内容的更新不产生任何开销。 ### 标题 ```ts await card.setTitle('Checkout tests') // null clears it ``` 显示在标题栏、侧边栏和小队（Squad）卡片中的名称。如果用户给卡片改过名，以用户起的名字为准；两者都没有时显示清单中的 `displayName`。 ≤ 120 个字符；控制字符、双向文本字符和不可见字符会被去除。 ### 状态 ```ts await card.setStatus('Running tests…', { busy: true }) // spinner await card.setStatus('3 failed', { tone: 'danger' }) await card.setStatus(null) // clear ``` 标题栏中的一个标签，≤ 80 个字符。色调：`default`、`accent`、`success`、`warning`、`danger`。 ### 徽章 ```ts await card.setBadge(3) // a count await card.setBadge('NEW', { tone: 'accent' }) // or a short text, ≤ 12 characters await card.setBadge(null) // clear ``` ### 概览图块 当用户把画布缩小到超过概览阈值时，每张卡片都会显示一个展示其关键信息的图块，而不是正文。你的卡片显示的就是你在这里设置的内容—— 卡片暂停时、在[手机](https://docs.neurosquad.ai/zh/card-sdk/phone)上也会继续显示。应用会记住它。 ```ts await card.setOverview({ primary: '3 failing', // big line, ≤ 160 secondary: 'checkout, auth', // small line, ≤ 160 progress: 0.8, // 0..1, a progress bar; null hides it tone: 'danger', icon: 'bug-ant' }) ``` 请保持它是最新的：在繁忙的画布上，这是大多数人唯一会看到的你的卡片内容。 应用能绘制的**图标**（heroicons，outline 风格）：`academic-cap`、`arrow-path`、`beaker`、`bell`、 `bolt`、`book-open`、`bug-ant`、`calendar`、`camera`、`chart-bar`、`chart-pie`、 `chat-bubble-left-right`、`check-circle`、`clock`、`cloud`、`code-bracket`、`command-line`、 `cpu-chip`、`cube`、`currency-dollar`、`document-text`、`exclamation-triangle`、`film`、`fire`、 `flag`、`folder`、`globe-alt`、`heart`、`inbox`、`key`、`light-bulb`、`link`、`list-bullet`、`map`、 `megaphone`、`moon`、`musical-note`、`newspaper`、`paper-airplane`、`pause`、`photo`、`play`、 `puzzle-piece`、`rocket-launch`、`server`、`shield-check`、`signal`、`sparkles`、`star`、`stop`、 `sun`、`table-cells`、`tag`、`trash`、`trophy`、`users`、`wrench-screwdriver`（SDK 中的 `HOST_ICON_NAMES` 列表）。 在你自己的页面里，想画什么图标都可以。 ### 提醒 ```ts await card.attention('needs-input', 'Pick a branch to deploy') await card.attention('info') // a softer pulse await card.attention('none') // clear ``` `needs-input` 会让卡片像等待用户的智能体一样闪烁，并把它列入**收件箱（Inbox）**。每 10 秒最多一次。第 1 版中没有声音，也没有系统通知。 **当前显示的是什么。** 应用会在重新加载、暂停和更新之间保留卡片的标题、状态、徽章、概览和提醒。`card.context.chrome` 告诉你的页面当前保存着什么，所以在重新加载前发出过提醒的卡片可以清除过时的闪烁： ```ts const attention = card.context.chrome?.attention if (attention && !stillNeedsTheUser()) await card.attention('none') declare function stillNeedsTheUser(): boolean ``` 在旧版本的应用中没有 `chrome`——请把这种情况当作“未知”。 ### 调整大小 ```ts const applied = await card.requestResize({ w: 640, h: 480 }) render(applied.w, applied.h) ``` 会被限制在清单的 `minSize`/`maxSize` 之间；返回实际应用的大小。它会像手动调整大小一样进入画布的撤销历史。 每 500 毫秒最多一次。用户也随时可以调整大小——用 [`card.lifecycle.onResized`](https://docs.neurosquad.ai/zh/card-sdk/api/environment#lifecycle) 监听。 ### 打开链接 ```ts const opened = await card.openLink('https://github.com/acme/app/issues/42') ``` 应用会在它自己覆盖整个窗口的对话框中显示完整地址；只有在用户点击 **Open link** 之后，链接才会在用户的浏览器中打开。 只允许 `https://`，并且只能在卡片可见时调用（否则为 `NOT_VISIBLE`）。用户拒绝时返回 `false`。卡片不能让自己跳转，也不能打开窗口。 ### 飞到另一张卡片 ```ts await card.focusCard(cardId) ``` 把镜头移到同一工作区的另一张卡片——适合做“带我去看失败的智能体”这类按钮。只能在你的卡片可见时调用，每 5 秒最多一次。 ### 创建卡片 需要 [`canvas.spawn`](https://docs.neurosquad.ai/zh/card-sdk/permissions#canvas-spawn)。 ```ts // A note next to this card, connected with an arrow from this card. const noteId = await card.spawn('note', { title: 'Test report' }) await card.ports.send(noteId, 'summary', '# Report\n\nAll green.') // Another copy of this card, with data for its first start. await card.spawn('self', { init: { suite: 'e2e' }, connect: false }) ``` 类型：`self`（你的卡片包的另一张卡片，首次启动时会以 `card.spawnInit` 收到 `init`）、`note`、`todo`、`kanban`、`sticky`。 新卡片会放在你的卡片旁边，并用一条从你的卡片出发的箭头相连，除非传入 `connect: false`。每张卡片最多 4 张，每分钟最多 4 张。 ### 卡片信息 ```ts const info = await card.getInfo() // CardInstanceInfo, fresh from the app render(info.instanceId, info.packageId, info.commit ?? 'dev folder', info.size) ``` ### 提示条 ```ts await card.ui.toast('Copied', { tone: 'success', durationMs: 2000 }) ``` 卡片方框内的一条小提示，≤ 280 个字符，显示 1–15 秒，每 2 秒最多一条。 ### 确认对话框 在卡片沙箱中，`alert`、`confirm` 和 `prompt` 什么也不做。请改为让应用来询问： ```ts const ok = await card.ui.confirm({ title: 'Delete all saved runs?', message: 'This removes 42 runs from this card. It cannot be undone.', confirmLabel: 'Delete', cancelLabel: 'Keep', tone: 'danger' }) if (ok) await card.storage.clear() ``` 应用会把它显示为**覆盖整个窗口的它自己的对话框**，而不是在你的卡片里：一个固定的标题说明你的卡片在请求确认， 你的 `title` 和 `message` 以引用的形式出现，然后是你的 `confirmLabel`（如果它读起来像取消/否/拒绝、提到了 NeuroSquad 或包含控制字符，就会被替换为应用的“Confirm”），以及应用自己的 Cancel。只能在卡片可见时调用，每分钟最多 10 次。 多张卡片的对话框会排队。 ### 卡片菜单 在卡片的 **⋯** 菜单中，于应用自带的菜单项（Settings…、Reload、About…）之后添加最多 12 项。 ```ts await card.ui.setMenu([ { id: 'rerun', label: 'Run again', icon: 'arrow-path', onSelect: () => void rerun() }, { id: 'export', label: 'Copy report', icon: 'document-text', onSelect: () => void copyReport() }, { id: 'reset', label: 'Reset', tone: 'danger', disabled: true } ]) // Or handle every choice in one place: card.ui.onMenu((id) => card.log.info('menu', id)) declare function rerun(): Promise declare function copyReport(): Promise ``` 每次调用都会替换之前的菜单项（每分钟最多 30 次）。`onSelect` 留在你的卡片里——不会发送给应用。 标签 ≤ 60 个字符；`icon` 取自[宿主图标](#overview)。 > 本页中除对话框和链接以外的一切，在卡片不在屏幕上时同样有效。对话框、链接、镜头聚焦和权限申请需要用户正在看： > 否则会以 `NOT_VISIBLE` 失败。 --- ## 存储与设置 > 按卡片和按卡片包的持久化键值存储，以及读取和修改应用根据清单绘制的设置表单。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/storage-settings ### 存储 卡片页面没有 `localStorage`、`indexedDB` 或 Cookie——它的沙箱没有可以保存它们的源（origin）。`card.storage` 就是替代品： 由应用以原子方式保存在磁盘上的 JSON 值，在重新加载、暂停和重启之后依然存在。不需要任何权限。 ```ts // This card on the canvas (instance scope). const draft = await card.storage.get('draft', '') // string, '' when missing await card.storage.set('draft', `${draft}\nmore`) await card.storage.set('runs', [{ at: Date.now(), failed: 3 }]) const runs = await card.storage.get<{ at: number; failed: number }[]>('runs') // undefined when missing await card.storage.delete('draft') const keys = await card.storage.keys('run:') // keys starting with a prefix const { bytes, quota } = await card.storage.usage() render(runs?.length, keys, bytes, quota) // Shared by every copy of this card, on every canvas (package scope). await card.storage.package.set('lastSync', Date.now()) card.storage.onChange(({ key, byInstance }) => { if (key === 'lastSync') render(`updated by card ${byInstance}`) }) ``` | 方法 | 结果 | | --- | --- | | `get(key)` | 值，或 `undefined`。 | | `get(key, fallback)` | 值，或 `fallback`。结果的类型与 fallback 一致。 | | `set(key, value)` | 保存任意 JSON 值。 | | `delete(key)` | | | `keys(prefix?)` | `string[]` | | `clear()` | 删除该作用域下的所有键。 | | `usage()` | `{ bytes, quota, keys }` | | `onChange(handler)` | 这张卡片的另一份副本写入了**包级**键：`{ scope, key, byInstance }`。 | `card.storage.package` 上有同样的方法。 **限制：** 键 ≤ 256 个字符，值 ≤ 1 MB，≤ 10 000 个键；每张卡片 5 MB，每个卡片包 20 MB。超出时以 `QUOTA_EXCEEDED` 失败。 写入会在大约四分之一秒内落盘，应用退出时会全部刷写。 **它会怎样：** 实例存储随卡片一起删除。包级存储在卸载后依然保留，除非用户勾选 **Also delete its saved data and secrets**。 存储在更新后保留——请让新版本仍能读懂你存下的数据结构（如果以后可能改动，就存一个 `version` 字段）。 > 在被卸载前保存：隐藏一段时间的卡片会被暂停，它的页面会被丢弃。用 > [`card.lifecycle.onSuspend`](https://docs.neurosquad.ai/zh/card-sdk/api/environment#lifecycle) 把仍在内存中的内容写下来。 ### 设置 在清单的 [`settings`](https://docs.neurosquad.ai/zh/card-sdk/manifest#settings) 中声明字段；应用负责绘制表单（从卡片的 **⋯ → Settings…** 打开， 或在你调用 `card.settings.open()` 时打开）、校验并保存这些值。你的卡片读取它们： ```ts const command = card.settings.value('command') ?? 'npm test' const all = card.settings.values // defaults filled in, secrets never included const hasKey = card.settings.hasSecret('apiKey') // true when the user saved one card.settings.onChange((snapshot) => { render(snapshot.values['command'], snapshot.secrets['apiKey']) }) // Change your own non-secret settings (a toggle in your UI, say). Validated like the form. await card.settings.set({ compact: true }) // Open the form on the card (only while it is visible). if (!hasKey) await card.settings.open() render(command, all) ``` | 成员 | 说明 | | --- | --- | | `values` | 当前值，已填入默认值。实时更新。 | | `secrets` | `Record`：哪些密钥设置已填写。 | | `value(key)` | 单个值，类型由你指定。 | | `hasSecret(key)` | 某个密钥设置是否已填写。 | | `get()` | 从应用获取最新的 `SettingsSnapshot`。 | | `set(values)` | 修改非密钥设置；卡片的每份副本都会收到 `settings.changed`。无效值会以 `INVALID_PARAMS` 失败。每分钟最多 60 次。 | | `open()` | 在卡片上打开设置表单。卡片不在屏幕上时为 `NOT_VISIBLE`。 | | `onChange(handler)` | 用户保存了表单，或 `set` 改动了某些值。 | **作用域。** 带有 `"scope": "package"` 的字段对你卡片的所有副本只有一个值；其余字段按卡片各自保存。 **密钥。** `secret` 字段只能在应用自己的对话框中输入——在设置表单中，它那一行只显示“已设置”或“未设置”，并会打开那个覆盖整个窗口的对话框——并由应用加密保存。 卡片永远读不到它——无论通过 `values` 还是任何方法。要使用它，把 `{{secret:}}` 放进[网络请求头](https://docs.neurosquad.ai/zh/card-sdk/api/network#secrets)； 应用会在请求发出时填入，且只针对你的卡片被授权的互联网主机（永远不会针对 `localhost`）。 不要在卡片里自己做一个“粘贴你的 API 密钥”的输入框：那样一来泄露密钥的责任就在你身上，而且用户已被告知 NeuroSquad 从不在卡片里索要密钥。 --- ## 主题、语言与生命周期 > 实时跟随应用的主题和语言、可见性与暂停、工作区、运行时申请可选权限，以及卡片日志。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/environment ### 主题 `connect()` 会把应用的实时主题以 CSS 变量的形式写到你页面的 `` 上，并保持更新： - 每个令牌对应一个 `--ns-`：`background`、`background-secondary`、`background-tertiary`、 `foreground`、`muted`、`surface`、`surface-foreground`、`surface-secondary`、 `surface-secondary-foreground`、`surface-tertiary`、`surface-tertiary-foreground`、`overlay`、 `overlay-foreground`、`default`、`default-foreground`、`accent`、`accent-foreground`、 `accent-soft`、`accent-soft-foreground`、`success`、`success-foreground`、`success-soft`、 `warning`、`warning-foreground`、`warning-soft`、`danger`、`danger-foreground`、`danger-soft`、 `border`、`border-secondary`、`separator`、`focus`、`link`、`field-background`、 `field-foreground`、`field-placeholder`、`field-border`、`radius`、`field-radius`； - `--ns-font-sans`、`--ns-font-mono`——应用的字体栈（字体文件本身不共享：请自带字体或使用系统字体）； - `` 上的 `color-scheme` 和 `data-ns-scheme="dark"`。 ```css .panel { background: var(--ns-surface); color: var(--ns-surface-foreground); border: 1px solid var(--ns-border); border-radius: var(--ns-radius); font-family: var(--ns-font-sans); } .panel--alert { background: var(--ns-danger-soft); color: var(--ns-danger); } ``` 在代码中，`card.theme` 是实时更新的 `ThemeSnapshot`（`scheme`、`tokens`、`fontSans`、`fontMono`）； `card.on('theme.changed', …)` 会在它变化时通知你，`applyTheme(snapshot, element)` 可以把变量写到任何你想要的地方（例如 shadow root 中）。 > 应用目前是深色的，所以 `scheme` 始终是 `dark`——但不要把它写死：使用这些变量，将来推出浅色主题时就能直接适配。 > 样式指南：[UI 套件与样式](https://docs.neurosquad.ai/zh/card-sdk/styling)。 ### 语言 应用支持英语、俄语和简体中文，并可实时切换。`card.i18n` 是 `{ language: 'en' | 'ru' | 'zh', locale }` （`locale` 为 `en-US`、`ru-RU` 或 `zh-CN`，用于 `Intl`），`` 会跟随它，清单中的文本（`displayName`、标签、描述）由应用负责解析。 对于你自己的字符串，`createTranslator` 会实时跟随应用语言： ```ts import { createTranslator } from '@neurosquad/card-sdk' const t = createTranslator( { en: { title: 'Tests', failed_one: '{{count}} test failed', failed_other: '{{count}} tests failed' }, ru: { title: 'Тесты', failed_one: '{{count}} тест упал', failed_few: '{{count}} теста упало', failed_many: '{{count}} тестов упало', failed_other: '{{count}} теста упало' }, zh: { title: '测试', failed_other: '{{count}} 个测试失败' } }, card ) render(t('title'), t('failed', { count: 3 })) t.onChange(() => render(t('title'))) // re-render on a language switch const when = new Intl.DateTimeFormat(card.i18n.locale, { timeStyle: 'short' }).format(Date.now()) render(when) ``` - 键可以嵌套（`{ list: { empty: '…' } }` → `t('list.empty')`）；`en` 必填并作为回退，最后回退到键本身。 - `{{name}}` 占位符由第二个参数填充；数字会按 locale 格式化。 - 提供 `count` 时，复数形式 `key_one`、`key_few`、`key_many`、`key_other` 由 `Intl.PluralRules` 选择——俄语四种都用，中文只用 `_other`。 - `t.language`、`t.locale`、`t.onChange(fn)`、`t.setLanguage(lang)`、`t.dispose()`。 ### 生命周期与可见性 一块有 50 张卡片的画布无法让 50 个 Web 应用全速运行，所以应用会告诉你的卡片它身处何处，并在没人看得见时暂停它。 | `card.visibility` | 含义 | 该做什么 | | --- | --- | --- | | `visible` | 在屏幕上，正文可见。 | 正常运行。 | | `offscreen` | 它所在的工作区正在显示，但卡片在视野之外。 | 停止动画和轮询。 | | `overview` | 已缩小：应用显示你的[概览图块](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#overview)而不是正文。 | 停止动画；保持图块内容最新。 | | `hidden` | 它所在的工作区没有显示，或窗口已隐藏。 | 停止一切只为给人看的工作。 | ```ts card.lifecycle.onVisibility((state) => { if (state === 'visible') startAnimation() else stopAnimation() }) card.lifecycle.onSuspend(async (graceMs) => { // The page is about to be unloaded. You have graceMs (about a second) to save. await card.storage.set('draft', currentDraft()) }) card.lifecycle.onExpanded((expanded) => render(expanded ? 'big layout' : 'compact layout')) card.lifecycle.onResized(({ w, h }) => render(w, h)) if (card.launch === 'resumed') render('back from a pause — state restored from storage') declare function startAnimation(): void declare function stopAnimation(): void declare function currentDraft(): string ``` **暂停。** 所在工作区已隐藏一分钟的卡片会被暂停：它收到 `lifecycle.suspend`，有大约一秒（`graceMs`）的时间保存，然后页面被卸载。 应用会继续显示它的标题栏和[概览图块](https://docs.neurosquad.ai/zh/card-sdk/api/card-ui#overview)。用户再次查看时，页面重新启动，且 `card.launch === 'resumed'`。 整个应用同时最多运行 24 个卡片页面；超出后，最久未被看到的屏幕外或隐藏卡片也会被暂停。 拥有 [`background`](https://docs.neurosquad.ai/zh/card-sdk/permissions#background) 权限的卡片在隐藏时不会被暂停（整个应用最多 8 张）。 **延迟启动。** 卡片页面在该卡片第一次真正出现在当前显示的工作区中时才会创建，而不是在工作区打开时。 在此之前，正文显示占位内容，标题栏显示你上次设置的内容。 **其他须知** - 工具调用和请求型端口会**唤醒**暂停的卡片：应用会先启动它的页面（最多等待 10 秒）再送达调用。 发给暂停卡片的流式消息会被丢弃——请在输出上使用 `retain`，让卡片能通过 `ports.read` 补上。 - 画布被拖动或缩放时，你的卡片收不到鼠标事件。 - 在卡片内滚动鼠标滚轮只会滚动你的卡片，永远不会滚动画布。焦点在卡片内部时，应用的键盘快捷键不起作用。 - 连续 15 秒没有回应应用心跳的卡片会显示为 **Not responding**，并带有 Reload 按钮。SDK 会替你应答心跳；触发它的通常是你代码中长时间的同步循环。 - 每个不同的卡片包是一个浏览器进程（约 30–60 MB）；同一张卡片的多个副本共享这个进程。 **事件不会补发。** 当卡片页面没有运行时——尚未挂载、已暂停或已卸载——它会错过 `agents.turn` 等事件。启动时，请根据 `card.agents.list()` （`status`、`turnStartedAt`，以及 `lastTurn`——上一轮何时结束、如何结束）和保留的端口值重建显示内容，而不要假设自己收到了每一个事件。 ### 工作区 ```ts const workspace = await card.getWorkspace() // { id, name, path? } render(workspace.name, workspace.path ?? 'no fs.read — no path') ``` `card.workspace` 中保存着同样的信息，并实时更新。`path`（绝对路径）只有在拥有 `fs.read` 时才提供。 ### 运行时的权限 ```ts async function copyReport(text: string): Promise { if (!card.permissions.has('clipboard.write')) { // Declared with "optional": true in the manifest. Only while the card is visible. const granted = await card.permissions.request('clipboard.write') if (!granted.includes('clipboard.write')) return false } await card.copyText(text) return true } card.permissions.onChange((all) => render(all.filter((p) => p.granted).map((p) => p.id))) ``` | 成员 | 说明 | | --- | --- | | `all` | 每项已声明的权限：`{ id, granted, optional, hosts?, reason? }`。实时更新。 | | `has(id)` | 是否已授予，直接授予或被包含（`fs.write` 包含 `fs.read`）都算。 | | `list()` | 从应用获取最新列表。 | | `request(...ids)` | 向用户申请**可选的**已声明权限（在应用覆盖整个窗口的对话框中）。返回此次被授予的 id。只能在卡片可见时调用，每 5 秒一次；申请任何未声明为可选的权限都会以 `PERMISSION_DENIED` 失败。 | | `onChange(handler)` | 某项授权发生变化——用户授予了，或在设置中撤销了。 | ### 卡片日志 ```ts card.log.info('run started', { filter: 'checkout' }) card.log.warn('slow response', 1834, 'ms') card.log.error(new Error('parser failed')) ``` 日志行会写入应用中该卡片包的日志（`card-logs`，256 KB，循环覆盖），在你运行 `neurosquad-card dev` 时也会输出到你的终端。 参数的拼接方式与 `console.log` 相同（对象转为 JSON，错误带调用栈），每行 ≤ 2 000 个字符，每秒最多 50 行——超出的行会被丢弃， 并写入一条“N lines dropped”警告。未捕获的错误和未处理的 Promise 拒绝会自动以 `error` 级别记录（在 `connect()` 中传入 `forwardErrors: false` 可关闭）。 --- ## 智能体与终端 > 列出智能体及其实时状态、轮次事件、读取相连智能体的屏幕、发送提示词，以及在相连终端中运行命令。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/agents ### 列出智能体 需要 [`agents.read`](https://docs.neurosquad.ai/zh/card-sdk/permissions#agents-read)。 ```ts import type { AgentInfo } from '@neurosquad/card-sdk' const agents: AgentInfo[] = await card.agents.list() const waiting = agents.filter((a) => a.kind === 'ai' && a.status === 'needs-input') const one = await card.agents.get(agents[0].id) render(waiting.map((a) => a.name), one.model ?? 'default model') ``` 卡片所在工作区中的每个 AI 智能体和终端（其他卡片不是智能体）： | 字段 | 类型 | 含义 | | --- | --- | --- | | `id` | `string` | 这张卡片在画布上的 id。 | | `name` | `string` | 用户看到的名称。 | | `harness` | `string` | `claude-code`、`codex-cli`、`opencode`、`qwen-code`、`shell-bash`、`shell-powershell`、`shell-cmd`…… | | `kind` | `'ai'` 或 `'shell'` | AI 智能体还是终端。 | | `status` | `AgentStatus` | `working`、`needs-input`、`finished`、`idle` 或 `exited`。 | | `connected` | `boolean` | 是否有箭头把它和你的卡片相连。 | | `sessionTitle` | `string?` | 智能体给自己会话起的标题。 | | `turnStartedAt` | `number?` | 当前一轮开始的时间戳（毫秒），在 `working` 时提供。 | | `lastTurn` | `{ startedAt, endedAt, endedAs }?` | 应用启动以来最近一次结束的一轮：时间戳（毫秒，`startedAt` 可能为 `null`），`endedAs` 为 `finished` 或 `needs-input`——用来补上卡片未运行期间错过的轮次。 | | `model` | `string?` | 它运行的模型（已知时）。 | 状态来自与应用其他部分相同的跟踪器——对于 Claude Code，来自它自身的钩子（hook）（对于 OpenCode 和 Kilo Code，来自 NeuroSquad 插件；对于 Hermes Agent，来自它的生命周期 webhook），因此 `needs-input`（“等待你授权”）和 `finished` 能被准确区分。 ### 事件 ```ts card.agents.onStatus(({ agentId, status }) => render(agentId, status)) card.agents.onTurn(({ agentId, phase, at }) => render(agentId, phase, new Date(at))) card.agents.onChanged((agents) => render(agents.length)) // added, removed or renamed // Only one agent: card.agents.onStatus((e) => render(e.status), agentId) ``` - `agents.status`——状态变化时发送 `{ agentId, status, at }`。 - `agents.turn`——`{ agentId, phase: 'start' | 'end', at }`。提交提示词时一轮开始，智能体完成或需要输入时一轮结束。 - `agents.changed`——`{ agents }`，完整的新列表。 有监听器时 SDK 会自动订阅。每个方法都返回一个用于移除监听器的函数。 ### 读取输出 需要 [`agents.output`](https://docs.neurosquad.ai/zh/card-sdk/permissions#agents-output)，并且你的卡片与该智能体或终端之间要有一条**箭头**。 ```ts // The visible screen, as text (up to 500 lines). const screen = await card.agents.readScreen(agentId, 80) // The last reply, from the agent's own session log (Claude Code, OpenCode, Kilo Code, Hermes Agent). null for others. const { text, at } = await card.agents.lastReply(agentId) // Live output: ANSI colours stripped, delivered in chunks about every 100 ms. const stop = card.agents.onOutput([agentId, shellId], ({ agentId: from, text: chunk }) => { if (chunk.includes('FAIL')) render(`${from} printed a failure`) }) stop() // when you no longer need it render(screen, text, at) ``` 对没有箭头相连的智能体调用这些方法会以 `NOT_CONNECTED` 失败。对未在运行的智能体调用 `readScreen` 会以 `UNAVAILABLE` 失败。 ### 向智能体发送提示词 需要 [`agents.prompt`](https://docs.neurosquad.ai/zh/card-sdk/permissions#agents-prompt)，以及一条连到 **AI** 智能体的箭头（终端接收的是[命令](#terminals)）。 ```ts import { isCardSdkError } from '@neurosquad/card-sdk' try { const delivered = await card.agents.prompt(agentId, 'Run the checkout tests and fix what fails.') // 'sent' — submitted now // 'queued' — the agent is working; it goes out when the turn ends // 'inserted'— typed in only (submit: false); the user presses Enter card.ui.toast(delivered === 'queued' ? 'Queued after the current turn' : 'Sent') } catch (error) { if (isCardSdkError(error, 'NOT_CONNECTED')) card.ui.toast('Draw an arrow from me to an agent') else if (isCardSdkError(error, 'BUDGET_PAUSED')) card.ui.toast('The workspace is over its budget') else if (isCardSdkError(error, 'USER_CANCELLED')) card.ui.toast('Not sent') else throw error } ``` 选项——`card.agents.prompt(agentId, text, { submit, whenBusy })`： | 选项 | 默认值 | 含义 | | --- | --- | --- | | `submit` | `true` | `false` 只把文本输入到智能体的输入框而不按回车——由用户检查后发送。结果为 `inserted`。 | | `whenBusy` | `'queue'` | 智能体正在工作时：`queue` 放入智能体的[提示词队列](https://docs.neurosquad.ai/zh/agents/queue)（`queued`），`send` 照样提交（`sent`），`fail` 以 `BUSY` 拒绝。 | 应用对每条提示词都会： - 让它经过与提示词队列和[预算](https://docs.neurosquad.ai/zh/cards/budget)相同的路径：工作区超出预算时，以 `BUDGET_PAUSED` 失败（手动输入的人从不受限——受限的是你的卡片）。 - 在箭头及其[箭头日志](https://docs.neurosquad.ai/zh/canvas/arrows#arrow-log)中显示，并带上你的卡片名称。 - 对于处于[危险模式](https://docs.neurosquad.ai/zh/agents/dangerous-mode)的智能体，应用会先在它自己覆盖整个窗口的对话框中显示这条提示词，并等待 **Send prompt**；用户拒绝则为 `USER_CANCELLED`； 你的卡片不在屏幕上则为 `NOT_VISIBLE`。 - 每张卡片每分钟最多 6 条——与通过智能体 `prompt` 端口发送的提示词合并计数——每条 ≤ 20 000 个字符。 - 来自卡片的排队提示词每个智能体最多 10 条，会显示来自哪张卡片；如果箭头、权限、卡片或它的卡片包已不存在，或者智能体被切换到了危险模式，它们会在发出之前被丢弃。 > 提示词是发给一个能编辑文件、能运行命令的东西的指令。永远不要在未先展示给用户的情况下，把来自网页、文件或其他卡片的文本转发成提示词—— > 提示词注入就是这样发生的。文本不是你自己写的时，优先使用 `submit: false`。 ### 单个智能体的运行 自 NeuroSquad 0.1.254（SDK 1.1）起提供。需要 [`usage.read`](https://docs.neurosquad.ai/zh/card-sdk/permissions#usage-read) 权限，并有箭头连接到一个 AI 智能体。请先检查 `card.host.supports('agents.usage')`：旧版应用会返回 `METHOD_NOT_FOUND`。 ```ts const run = await card.agents.usage(agentId, since /* 毫秒时间戳 */, until /* 可选，默认现在 */) ``` 返回该智能体在时间窗口内的数据——与应用"用量"页面使用的数据相同。智能体工作时你的框架可能被暂停或卸载； 状态历史由应用自己记录，因此用时依然准确。 | 字段 | 含义 | | --- | --- | | `prompts` | 交给智能体的回合数。回答权限请求属于同一回合。 | | `requests` | 窗口内工具记录的模型请求（API 调用）次数。 | | `inputTokens` / `outputTokens` | 未缓存的输入；含推理的输出（`reasoningTokens` 为其中推理部分）。 | | `cacheReadTokens` / `cacheWriteTokens` | 缓存读写，仅在工具和服务商报告时提供。 | | `totalTokens` | 输入 + 输出 + 缓存读取 + 缓存写入。 | | `elapsedMs` | 从第一个提示到最后一次完成（回合进行中则到现在）。 | | `workingMs` | 智能体实际工作的时间，不含等待用户的时间。 | | `costMicroUsd` | 工具记录的费用，否则按标价；价格未知时为 `null`。 | | `model`、`provider`、`status`、`timingComplete` | 这些数字的上下文。 | > `null` 表示**未报告**：工具日志中没有该数字（有些不记录缓存写入或推理），本地服务器没有发送缓存计数， > 或应用根本无法读取该工具的用量日志（Amp、Cursor）。请显示"未报告"，不要显示 0。词元数为精确整数。 ### 终端 需要 [`terminals.write`](https://docs.neurosquad.ai/zh/card-sdk/permissions#terminals-write)，以及一条连到终端卡片（bash、PowerShell 或 cmd）的箭头。 ```ts // Run a command and wait for it to finish. const result = await card.terminals.run(shellId, 'npm test -- --reporter=dot', { timeoutMs: 120_000 }) if (result.timedOut) render('still running after 2 minutes') else render(result.exitCode === 0 ? 'passed' : `failed with ${result.exitCode}`, result.output) // Or just type into it (and press Enter). await card.terminals.write(shellId, 'git status', { submit: true }) ``` | | `run(agentId, command, { timeoutMs? })` | `write(agentId, text, { submit? })` | | --- | --- | --- | | 作用 | 运行一条命令并等待提示符返回 | 输入文本；`submit: true` 会在之后按回车 | | 返回 | `{ exitCode, output, truncated, timedOut }` | 无 | | 限制 | 超时 1–120 秒（默认 120），输出 ≤ 64 KB；每张卡片每分钟 30 条命令，与终端的 `command` 端口共享 | 每分钟 60 次 | 在 cmd 中 `exitCode` 为 `null`，因为 cmd 不报告退出码。用户能在终端本身和箭头上看到每条命令。 命令不受智能体预算限制——终端不是 AI 智能体——但它们以用户的完整权限运行：参见[安全检查清单](https://docs.neurosquad.ai/zh/card-sdk/security)。 --- ## 端口：卡片之间的通信 > 通过箭头的类型化输入和输出——知名类型和你自己用 JSON Schema 定义的类型、emit、send、请求/响应、保留值、探查相连卡片接收什么，以及内置笔记、待办清单、任务看板、便签、智能体和终端的端口。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/ports 端口让一张卡片与通过箭头相连的卡片交换**类型化数据**：你的测试雷达把失败项推送到待办清单，一篇笔记把正文喂给你的摘要卡片， 两张自定义卡片约定它们自己的格式。你在[清单文件](https://docs.neurosquad.ai/zh/card-sdk/manifest#ports)中声明端口；应用负责路由、转换并校验每一个值。 ### 方向 **从卡片 A 指向卡片 B** 的箭头把 A 的**输出**送到 B 的**输入**。双向相连的两张卡片，数据双向流动。（工具和智能体权限不关心方向；端口关心。） `card.ports.peers` 列出与你的卡片相连的每张卡片，并带有 `direction`： - `downstream`——你的卡片 → 对端：你的输出到达它的输入； - `upstream`——对端 → 你的卡片：它的输出到达你的输入； - `both`。 ### 类型 每个端口都有一个类型：**知名**的 `ns:*` 类型，或带有 JSON Schema 的**自定义** `/` 类型。 | 类型 | 值 | | --- | --- | | `ns:any` | 任意 JSON。作为输入时原样接受所有输出类型。 | | `ns:text` | 字符串（≤ 1 000 000）。 | | `ns:markdown` | Markdown 字符串（≤ 1 000 000）。 | | `ns:number` | 数字。 | | `ns:boolean` | `true` 或 `false`。 | | `ns:json` | 对象或数组。 | | `ns:url` | URI 字符串。 | | `ns:image` | `{ mimeType, data, alt? }`——base64 编码的 PNG、JPEG、WebP 或 GIF，最多约 700 KB。 | | `ns:file-ref` | `{ path, line? }`——工作区文件夹中的一个文件。收到它并不意味着获得文件访问权。 | | `ns:task` | `{ text, id?, status?, column?, assignee? }`——`status` 为 `pending`、`active`、`done` 或 `error`。 | | `ns:tasks` | 最多 200 个 `ns:task` 的数组。 | | `ns:task-patch` | `{ ref, text?, status?, column? }`——修改一个任务；`ref` 是它的 id 或确切文本。 | | `ns:table` | `{ columns: string[], rows: (string, number, boolean or null)[][] }` | | `ns:event` | `{ type, data?, at? }` | | `ns:trigger` | 空信号：`{}` 或 `null`。 | **自定义类型**以你的卡片包命名——例如 `test-radar/coverage`——并且必须带有 `schema`（[安全子集](https://docs.neurosquad.ai/zh/card-sdk/manifest#json-schema)，不允许 `pattern`）。 其他卡片可以声明同一个类型来与你的卡片互通。任何端口都可以在类型之外再加一个 `schema`；值必须同时满足两者。 ### 发送：`emit` ```ts const delivered = await card.ports.emit('failures', [ { text: 'checkout › pays with a saved card', status: 'error' }, { text: 'auth › logs in with SSO', status: 'error' } ]) if (delivered === 0) card.ui.toast('Connect me to a todo list to track these') ``` 值先按输出的 schema 校验，然后发送给**每个下游对端**中有兼容输入的那些。应用会在每个对端上挑选输入：标记为 `default` 的那个； 否则类型完全相同的那个；再否则第一个兼容的（`emit` 永远不会选中请求型输入）。类型不同时会进行转换（见下文），并按该输入的 schema 校验。 你会得到收到该值的对端数量。 要指定某一个对端，并可选地指定它的某个输入： ```ts await card.ports.send(noteId, 'summary', '## Nightly run\n\nAll green.', { input: 'replace' }) ``` ### 接收 ```ts card.ports.onMessage((text, message) => { render(`${message.fromKind} card ${message.from} sent ${message.type} on ${message.output}`, text) }, { input: 'notes' }) ``` `message` 是 `{ from, fromKind, output, input, type, sourceType, data, at }`——`type` 是**你的**输入的类型（转换之后），`sourceType` 是发送方声明的输出类型（转换之前；旧版本的应用中不存在）。省略 `input` 则在所有输入上接收。 在你订阅之前到达的消息会被暂存（最多 100 条），并交给你的第一个监听器。 ### 类型转换 只有存在转换规则时，一个输出才能到达不同类型的输入： | 输入类型 | 接受的输出类型 | 方式 | | --- | --- | --- | | 同一类型 | 同一类型 | 原样 | | `ns:any` | 任何类型 | 原样 | | `ns:text` | `markdown`、`url` | 原样 | | | `number`、`boolean` | `String(value)` | | | `json` | 格式化的 JSON | | `ns:markdown` | `text`、`url` | 原样 | | | `number` | `String(value)` | | | `json` | 一个 `json` 围栏代码块 | | | `table` | 一个 Markdown 表格 | | | `tasks` | 一个清单（`- [x] done`、`- [ ] open`） | | `ns:tasks` | `task` | 包装成数组 | | | `text`、`markdown` | 每个非空行一个任务（去掉列表标记和复选框） | | `ns:json` | `table`、`tasks`、`task`、`event`、`file-ref`、`task-patch` | 原样 | | `ns:trigger` | `event`、`text`、`number`、`boolean`、`json` | 变成 `{}`——“发生了某件事” | 自定义类型只匹配同一个自定义类型（或 `ns:any`）。如果你想自己判断，SDK 导出了辅助函数 `portsCompatible`、`portCoercion`、`coercePortValue` 和 `pickInputFor`。 ### 请求：提问与应答 带有 `"mode": "request"` 的输入用来回答问题。在 `response` 中声明回复的类型： ```json { "id": "lookup", "label": "Look up", "type": "ns:text", "mode": "request", "response": { "type": "ns:json" } } ``` ```ts // The answering card: card.ports.onRequest('lookup', async (query, request) => { const hits = await search(query, request.signal) // request.signal aborts at the deadline return { query, hits } // checked against response.type }) // The asking card (connected to it by an arrow, either direction): const answer = await card.ports.request<{ hits: string[] }>(peerId, 'lookup', 'flaky tests', { timeoutMs: 10_000 }) render(answer.hits) declare function search(q: string, signal: AbortSignal): Promise declare const peerId: string ``` 在处理函数中抛出异常会把错误发回去；提问方的 Promise 会被拒绝。在你注册处理函数之前到达的请求会一直等到接近截止时间，然后收到“no handler”。 默认超时 30 秒，最长 120 秒（`TIMEOUT`）。发给暂停卡片的请求会唤醒它（最多 10 秒），否则以 `UNAVAILABLE` 失败。 ### 保留值 把输出标记为 `"retain": true`，应用就会保留它的最后一个值（≤ 256 KB）： - **之后**才连接的对端会立即收到一次； - 任何相连的对端都可以随时读取它，无论箭头朝哪个方向： ```ts const last = await card.ports.read<{ text: string }[]>(todoId, 'items') if (last) render(`${last.data.length} items, as of ${new Date(last.at).toLocaleTimeString()}`) declare const todoId: string ``` 保留值是卡片在暂停之后补上进度的方式——卡片被卸载期间发送的流式消息不会排队。 ### 探查对端 卡片可以查明与它相连的卡片——包括内置卡片——输出什么、接收什么，并据此调整行为： ```ts import type { PeerInfo } from '@neurosquad/card-sdk' function describePeer(peer: PeerInfo): string { const ins = peer.inputs.map((p) => `${p.id}:${p.type}`).join(', ') || 'none' const outs = peer.outputs.map((p) => `${p.id}:${p.type}`).join(', ') || 'none' return `${peer.name} (${peer.kind}, ${peer.direction}) — in: ${ins}; out: ${outs}` } card.ports.peers.forEach((peer) => render(describePeer(peer))) card.ports.onPeersChanged((peers) => render(peers.map(describePeer))) // Is there a checklist downstream that takes tasks? const taskSink = card.ports.peers.find( (p) => p.direction !== 'upstream' && p.inputs.some((i) => i.type === 'ns:tasks') ) render(taskSink?.name ?? 'no task list connected') ``` `PeerInfo` 是 `{ cardId, kind, name, type?, direction, inputs, outputs }`。`kind` 为 `custom`、`note`、`todo`、`kanban`、`sticky`、`agent`、`terminal` 或 `other`（没有端口的卡片，例如浏览器）。对智能体和终端，`type` 是 harness；对自定义卡片，是包名。每个端口都是一个 `PortInfo`： `{ id, label, description?, type, schema?, mode, response?, retain, default, permission? }`——内置端口会设置 `permission`，表示**你的**卡片使用它需要什么权限。 你自己的端口：`card.ports.inputs`、`card.ports.outputs`，或 `card.ports.describe()`。 大多数卡片在发送之前需要的，这三个辅助方法都能满足： ```ts import { hasDownstreamPeer, permissionForPeer, requestPermissions } from '@neurosquad/card-sdk' async function sendSummary(text: string): Promise { if (!hasDownstreamPeer(card.ports.peers)) { card.ui.toast('Draw an arrow from this card to a note') return } // Which permission does sending Markdown to each peer need? (cards.connected for a note) const needed = card.ports.peers .map((peer) => permissionForPeer(peer, { outputType: 'ns:markdown' })) .filter((id) => id !== null) // Asks only for what is missing; never throws — resolves with what is usable now. const usable = await requestPermissions(card, ...needed) if (usable.length === needed.length) await card.ports.emit('summary', text) } ``` ### 内置卡片 应用自带的卡片通过适配器参与进来。使用它们需要最后一列所列的权限——在**你的**卡片上。 | 卡片 | 输入 | 输出 | 需要 | | --- | --- | --- | --- | | 笔记 | `append`（`ns:markdown`，默认）：在末尾追加一段 · `replace`（`ns:markdown`）：替换整篇笔记 | `text`（`ns:markdown`，保留）：笔记内容，每次变化时发送 | `cards.connected` | | 待办清单 | `add`（`ns:tasks`，默认）：添加条目 · `update`（`ns:task-patch`）：修改一个条目的文本或状态 | `items`（`ns:tasks`，保留）：所有条目，每次变化时发送 | `cards.connected` | | 任务看板 | `add`（`ns:tasks`，默认）：添加未分配的任务 · `update`（`ns:task-patch`）：移动或编辑一个任务 | `tasks`（`ns:tasks`，保留）：所有任务及其所在列 | `cards.connected` | | 便签 | `title`（`ns:text`，默认）：设置标题 | `title`（`ns:text`，保留） | `cards.connected` | | AI 智能体 | `prompt`（`ns:text`，默认）：发送提示词——与使用默认值的 [`agents.prompt`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#prompting) 完全相同 | `status`（`ns:event`，保留）：`{ type: "status", data: { status } }` | `agents.prompt` / `agents.read` | | | | `reply`（`ns:markdown`，保留）：一轮结束时的最终消息——仅限 Claude Code 和 Hermes Agent | `agents.output` | | 终端 | `command`（`ns:text`，默认）：运行一条命令 | `exit`（`ns:event`）：每条命令结束后发送 `{ type: "exit", data: { command, exitCode } }` | `terminals.write` / `agents.output` | 所以，有一条从你的卡片指向笔记的箭头时，`card.ports.emit('summary', '# Done')` 会在笔记末尾追加一段； 有一条从待办清单指向你的卡片的箭头时，你的 `ns:tasks` 输入会收到清单的每一次变化。 ### 限制 单个值 ≤ 1 MB（保留值 ≤ 256 KB）；每个输出每秒最多 20 条消息。不满足 schema 的值会以 `INVALID_PARAMS` 被拒绝并给出精确路径—— 应用永远不会投递与接收方声明不符的内容。 > 两张自定义卡片之间使用端口不需要任何权限：用户画出箭头就是同意。数据只沿箭头流动，只从声明的输出流向声明的输入，并且只沿箭头的方向。 --- ## 给智能体的工具（MCP） > 在清单中声明工具、在卡片中实现它，让相连的智能体通过 NeuroSquad 的 MCP 服务器调用——结果、图片、错误、进度、取消和超时。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/tools 卡片可以赋予智能体新的能力。在清单中声明一个工具并在卡片中实现它，所有通过箭头与卡片相连的智能体都会在工具列表中看到它—— 经由应用本来就为智能体运行的 MCP 服务器（Claude Code、Codex、Qwen Code）。不需要任何权限：用户画出的箭头就是同意。 ### 声明 ```json "tools": [ { "name": "run_tests", "title": "Run the tests", "description": "Runs the project's tests in the connected terminal and returns the failing tests with their messages, or 'All tests passed'.", "inputSchema": { "type": "object", "properties": { "filter": { "type": "string", "maxLength": 200, "description": "Only tests whose name contains this" } } }, "timeoutMs": 120000 } ] ``` 智能体看到的名称是 **`_`**——名为 `test-radar` 的卡片对应 `test_radar_run_tests`—— 参数是你的 `inputSchema`，外加应用添加的可选参数 `card`（id 或名称，用于在连了多张副本时指定其中一张）。 描述在交给模型时会加上前缀 `[Custom card "" by , community code]`。如果两个卡片包会产生同一个名称，先安装的那个保留它，后安装的会加上 `_2`、`_3`。 应用在安装时会拒绝的名称：与 NeuroSquad 自有工具（`canvas_spawn_card`、`terminal_send_keys`、`browser_navigate`……）相同的对外名称、 任何包含 `__` 的名称（为用户安装的 MCP 服务器保留），以及属于内置工具族的卡片 `name`，例如 `telegram`、`squad`、`ports` 或 `mcp` （参见[保留名](https://docs.neurosquad.ai/zh/card-sdk/manifest#identity)）。新增工具或改变工具描述措辞的更新会再次征求用户同意。 描述是写给模型看的：这个工具做什么、何时使用、返回什么。参数要少且有约束（`enum`、`maxLength`、`minimum`……）；应用会在你的卡片看到之前校验它们。 ### 实现 ```ts import { toolError } from '@neurosquad/card-sdk' card.tools.handle<{ filter?: string }>('run_tests', async ({ filter }, call) => { call.progress('running the tests…') // shown on the arrow const terminal = (await card.agents.list()).find((a) => a.kind === 'shell' && a.connected) if (!terminal) return toolError('Connect a terminal card to the Test radar card first.') const result = await card.terminals.run(terminal.id, `npm test -- ${filter ?? ''}`, { timeoutMs: 110_000 }) if (call.signal.aborted) return // the agent gave up; nothing is sent return result.exitCode === 0 ? 'All tests passed' : result.output }) ``` 处理函数会收到校验过的参数和一个 `call`： | `call.` | 说明 | | --- | --- | | `callId` | 本次调用的 id。 | | `tool` | 清单中的工具名。 | | `agent` | 发起调用的智能体的 `{ id, name }`。 | | `deadline` | 应用放弃等待的时间戳（毫秒）。 | | `signal` | 一个 `AbortSignal`，在取消或到达截止时间时中止。 | | `progress(message)` | 工作期间在箭头上显示的一行短文字（≤ 200）；限流为每秒 4 次。 | **你的返回值**就是工具结果： | 返回 | 智能体得到 | | --- | --- | | 字符串 | 这段文本 | | `undefined` | `OK` | | 其他任意 JSON 值 | 格式化后的 JSON 文本 | | `toolText(text)` | 文本（与返回字符串相同） | | `toolImage(base64, 'image/png', caption?)` | 一张图片，以及作为文本的说明文字 | | `toolError(message)` | 一个失败结果（`isError: true`），模型可以读到并作出反应 | | `ToolResultPayload` | 原样：`{ content: [{ type: 'text', text } or { type: 'image', data, mimeType }], isError? }`，1–16 个部分 | **抛出异常**也会把错误返回给智能体，内容为异常消息（并在卡片日志中写一条警告）。结果 ≤ 1 MB。 ### 时间 - 默认超时 30 秒，或工具的 `timeoutMs`（最长 120 秒）。到达截止时间时，应用告诉智能体调用超时，并向你的卡片发送 `tools.cancel`—— `call.signal` 会中止，你之后返回的任何内容都会被丢弃。 - 在你的处理函数注册之前到达的调用（例如卡片仍在加载数据时）会等待 `handle()`，直到截止时间。 - 调用页面已暂停的卡片会唤醒它（最多 10 秒）；如果它所在的工作区没有打开，智能体会被告知去打开包含这张卡片的工作区。 - 每次调用都会显示在箭头上：箭头标签显示工具名和你的进度文字，并记入[箭头日志](https://docs.neurosquad.ai/zh/canvas/arrows#arrow-log)。 ### 开关工具 ```ts await card.tools.setEnabled('run_tests', false) // hidden from agents (e.g. until the user signs in) await card.tools.setEnabled('run_tests', true) ``` 这会作用于你卡片的所有副本。 ### 配合 React ```tsx import { useTool } from '@neurosquad/card-sdk/react' export function Scratchpad({ text }: { text: string }) { useTool('read_scratchpad', () => text || '(empty)') // the latest `text` is always used return 
{text}
} ``` > 工具结果会直接进入智能体的上下文。你返回的任何来自网页、文件或用户的内容都应视为不可信：注明来源、保持简短， > 并且绝不要让智能体能调用的工具悄悄做出破坏性操作——先用 `card.ui.confirm` 询问用户。 --- ## 网络 > card.net.fetch——经由 NeuroSquad 代理访问卡片声明过的主机：JSON、二进制和流式响应、请求头中的密钥、重定向与限制。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/network 卡片页面本身完全无法访问网络——它的沙箱会拦截包外的每一个请求、图片和字体。`card.net.fetch` 改为经由应用中的代理，只放行用户授权的内容： - 带 `hosts` 的 [`network`](https://docs.neurosquad.ai/zh/card-sdk/permissions#network)：对这些主机的 `https` 请求； - [`network.local`](https://docs.neurosquad.ai/zh/card-sdk/permissions#network-local)：对 `localhost`、`127.0.0.1` 和 `::1` 的 `http` 或 `https` 请求——NeuroSquad 自己的本地服务器 （它的 MCP 服务器、远程访问、开发者链接、浏览器卡片中 Chrome 的调试端口）除外，它们无法访问。 ### 发起请求 ```ts const res = await card.net.fetch('https://api.github.com/repos/acme/app/issues?state=open', { headers: { accept: 'application/vnd.github+json' }, responseType: 'json' }) if (!res.ok) throw new Error(`GitHub said ${res.status} ${res.statusText}`) const issues = await res.json<{ number: number; title: string }[]>() render(issues.map((i) => `#${i.number} ${i.title}`)) ``` 它的用法和 `fetch` 很像，只有几处不同： | 选项 | 含义 | | --- | --- | | `method` | `GET`（默认）、`HEAD`、`POST`、`PUT`、`PATCH`、`DELETE`。有请求体但没指定方法时为 `POST`。 | | `headers` | 对象，或 `[name, value]` 对。可以包含 [`{{secret:}}`](#secrets)。 | | `body` | 字符串（原样发送）、字节（`Uint8Array`、`ArrayBuffer`），或其他任意 JSON 值（序列化后发送，除非你自己设置，否则带 `content-type: application/json`）。≤ 5 MB。 | | `responseType` | `text`（默认）、`json`（由应用解析）、`base64`（二进制）或 `stream`。 | | `timeoutMs` | 1 000–120 000，默认 30 000。 | | `signal` | 一个 `AbortSignal`；中止时会在应用中取消该请求。 | 结果是一个 `CardResponse`：`ok`、`status`、`statusText`、`url`（重定向之后）、`headers`（`get`、`has`、可迭代；名称为小写）、`truncated`， 以及读取正文的方法 `text()`、`json()`、`bytes()`、`arrayBuffer()`、`chunks()`、`lines()`——和 `Response` 一样，正文只能读取一次。 ```ts // POST JSON, read binary. const upload = await card.net.fetch('https://api.example.com/v1/render', { method: 'POST', body: { chart: 'coverage', width: 640 }, responseType: 'base64' }) const png = await upload.bytes() render(png.byteLength) ``` **条件请求与空响应体。** `If-None-Match`、`If-Modified-Since` 等条件请求头会被转发，除 `set-cookie` 外的所有响应头都会返回 （所以 `etag` 和限流相关的响应头都在）。空响应体——`304 Not Modified` 或 `204 No Content`——在 `responseType: 'json'` 时，`res.json()` 返回 `null`。 ### 请求头中的密钥 永远不要把 API 密钥放进卡片代码或存储里。声明一个 `secret` [设置](https://docs.neurosquad.ai/zh/card-sdk/manifest#settings)，让用户在应用的设置表单中输入，然后在**请求头的值**中引用它： ```ts if (!card.settings.hasSecret('apiKey')) { await card.settings.open() } else { const res = await card.net.fetch('https://api.example.com/v1/me', { headers: { authorization: 'Bearer {{secret:apiKey}}' }, responseType: 'json' }) render(await res.json()) } ``` 应用会在请求发出时把 `{{secret:apiKey}}` 替换为保存的密钥（先找这张卡片的，再找包级的）——只针对发往已授权**互联网**主机的请求， 永远不会针对本机（`network.local`）。你的卡片永远看不到这个值。 占位符只在请求头的值中有效——不能用于 URL 或请求体，因为它们会出现在服务器日志中——而且如果重定向指向另一个主机，带密钥的请求头会被**丢弃**。 引用用户尚未设置的密钥会以 `INVALID_PARAMS` 失败。 ### 流式响应 对于服务器发送事件（SSE）、NDJSON 或大文件下载，请请求流式响应。收到响应头后 Promise 就会返回；正文以分块形式到达（每块 ≤ 64 KB）： ```ts const controller = new AbortController() const stream = await card.net.fetch('https://api.example.com/v1/events', { headers: { accept: 'text/event-stream' }, responseType: 'stream', signal: controller.signal }) for await (const line of stream.lines()) { if (line.startsWith('data: ')) render(JSON.parse(line.slice(6))) } // controller.abort() ends it early. ``` `chunks()` 对文本分块返回字符串，对二进制分块返回 `Uint8Array`；`lines()` 按换行拆分；`for await (const chunk of response)` 也可以用。 流失败时会抛出 `NETWORK_ERROR`。同时最多打开 4 个流；流在 5 分钟没有数据或达到 256 MB 后会被关闭。第 1 版不支持 WebSocket。 ### 代理会强制执行的规则 1. **协议。** 只允许 `https`，唯一例外是在有 `network.local` 时对本机使用 `http`。URL 中不能带用户名或密码；`#fragment` 不会被发送。 2. **主机。** 严格匹配你声明的模式（`api.example.com`、`*.example.com`、`host.example.com:8443`）。其他任何主机都会以 `HOST_NOT_ALLOWED` 失败。 3. **地址。** 应用自己解析域名；对于公网主机授权，每个地址都必须是公网地址——私有网络、回环、链路本地和云元数据地址都会被拒绝， 并且请求会发往经过检查的那个地址（不会发生 DNS 重绑定）。 4. **请求头。** 你不能设置 `host`、`cookie`、`origin`、`referer`、`user-agent`、`content-length`、`connection`、`proxy-*`、`sec-*`、 `x-forwarded-*` 等。应用会发送 `User-Agent: NeuroSquad-Card/ ()`。Cookie 永远不会被保存或发送， `set-cookie` 也永远不会返回给你。 5. **重定向。** 由应用跟随，最多 5 次，每一跳都会按规则 1–4 重新检查。 6. **限制。** 请求体 ≤ 5 MB；响应 ≤ 10 MB（更长的 text 或 base64 正文会被截断并带有 `truncated: true`；更长的 JSON 正文以 `TOO_LARGE` 失败）； 同时 6 个请求；每分钟 120 个；超时最长 120 秒——而且超时涵盖读取整个正文，而不只是响应头。 错误：`HOST_NOT_ALLOWED`（主机或地址未授权）、`NETWORK_ERROR`（DNS、连接、TLS）、`TIMEOUT`、`TOO_LARGE`、`RATE_LIMITED`、 `PERMISSION_DENIED`（完全没有网络权限）。HTTP 错误状态码**不是**异常——请检查 `res.ok`。 > 安装对话框会告诉用户：你的卡片能看到的任何内容都可能被发送到你列出的主机。请让这个列表简短而具体： > 通配符或通用主机（粘贴板服务、短链接服务）会让谨慎的用户拒绝安装。 --- ## 文件、剪贴板与用量 > 读取、写入、列出和监视工作区文件夹中的文件；复制到剪贴板；工作区的令牌用量和费用。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/files ### 工作区文件夹中的文件 读取需要 [`fs.read`](https://docs.neurosquad.ai/zh/card-sdk/permissions#fs-read)，修改需要 [`fs.write`](https://docs.neurosquad.ai/zh/card-sdk/permissions#fs-write)。 每个路径都**相对于工作区文件夹**——也就是用户为工作区选择的项目文件夹——分隔符用 `/` 或 `\` 均可；`''` 或 `'.'` 表示文件夹本身。 ```ts // Read const pkg = JSON.parse(await card.fs.readText('package.json')) as { name: string } const logo = await card.fs.readBytes('public/logo.png') const info = await card.fs.stat('src/index.ts') // { path, type, size, mtimeMs } const { entries, truncated } = await card.fs.list('src', { recursive: true, maxEntries: 2000 }) render(pkg.name, logo.byteLength, info.size, entries.length, truncated) // Write (atomically: a temporary file, then a rename) await card.fs.writeText('reports/latest.md', '# Report\n', { createDirs: true }) await card.fs.mkdir('reports/archive') await card.fs.trash('reports/old.md') // to the OS trash; there is no hard delete // Write only if nobody changed it since you read it const before = await card.fs.stat('TODO.md') await card.fs.writeText('TODO.md', '- [ ] ship it\n', { ifMtimeMs: before.mtimeMs }) ``` | 方法 | 结果 | | --- | --- | | `stat(path)` | `{ path, type: 'file' or 'directory', size, mtimeMs }` | | `list(path?, { recursive?, maxEntries? })` | `{ entries: { path, type, size? }[], truncated }`——≤ 5 000 项；递归列出时会跳过 `.git` 和 `node_modules`，除非你列的就是它们内部 | | `readText(path, { maxBytes? })` | UTF-8 文本 | | `readBytes(path, { maxBytes? })` | `Uint8Array` | | `read(path, { encoding?, maxBytes? })` | `{ data, encoding, size, truncated }`——原始结果 | | `writeText(path, text, { createDirs?, ifMtimeMs? })` | 新的 `FsStat` | | `writeBytes(path, bytes, { createDirs?, ifMtimeMs? })` | 新的 `FsStat` | | `mkdir(path)` | `FsStat` | | `trash(path)` | 把文件或文件夹移入系统回收站（每分钟 60 次） | | `watch(path, handler, { recursive? })` | 返回一个用于停止监视的函数 | 每次读写最多 10 MB。 **监视：** ```ts const stop = await card.fs.watch('reports', ({ path, type }) => { render(`${path} ${type === 'rename' ? 'was added or removed' : 'changed'}`) }, { recursive: true }) // later await stop() ``` 变化会以 100 毫秒去抖；每张卡片最多 20 个监视器；卡片页面被卸载时监视器随之停止（在 `launch === 'resumed'` 之后重新监视）。 **边界。** 绝对路径和任何 `..` 都会被直接拒绝。之后，应用会解析目标的真实路径（对于新文件，则解析其最近的已存在文件夹）， 不在工作区文件夹之内就拒绝——所以指向外部的符号链接或目录联接（junction）也没用。 这些情况都以 `FS_DENIED` 失败；其他文件系统问题（找不到、不是文件夹……）以 `FS_ERROR` 失败，`ifMtimeMs` 检查不通过时以 `FS_ERROR` 失败并带有 `data.conflict`。 当工作区文件夹是用户的主文件夹、某个磁盘的根目录，或包含 NeuroSquad 自己的数据文件夹时，**完全没有文件访问权限**—— 每个 `fs.*` 调用都会以 `FS_DENIED` 失败。 #### 受保护的路径 对以下路径的写入、`mkdir` 和 `trash` 会被拒绝（`FS_DENIED`），无论位于哪一层，检查的既是你给出的路径，也是任何链接背后的真实路径—— 因为它们会让卡片借助 git、用户的智能体或他们的工具来运行代码： - 名为 `.git` 的文件夹中的任何内容（包括子模块或 worktree 的 `.git` 文件）、`.gitmodules`、`.gitattributes`； - 文件夹 `.claude`、`.codex`、`.cursor`、`.gemini`、`.qwen`、`.opencode`、`.kilocode`、 `.windsurf`、`.continue`、`.vscode`、`.idea`、`.husky`、`.devcontainer` 以及 `.github/workflows`； - 文件 `.mcp.json`、`CLAUDE.md`、`CLAUDE.local.md`、`AGENTS.md`、`GEMINI.md`、`QWEN.md`、 `.cursorrules`、`.windsurfrules`、`opencode.json`、`opencode.jsonc`、`.envrc`、`.npmrc`、`.yarnrc`、 `.yarnrc.yml`、`.pnpmfile.cjs`。 有 `fs.read` 时可以读取它们。 > 第 1 版没有文件选择器：卡片只能处理工作区文件夹。要让卡片处理某个文件，可以让用户在设置中输入路径，或通过端口接收一个 `ns:file-ref`。 ### 剪贴板 需要 [`clipboard.write`](https://docs.neurosquad.ai/zh/card-sdk/permissions#clipboard-write)——很适合设为可选权限。 ```ts await card.copyText('npm test -- --grep checkout') ``` 每秒最多一次，≤ 1 MB。浏览器自带的 `navigator.clipboard` 在卡片中不可用，而且完全无法读取剪贴板。 ### 令牌用量和费用 需要 [`usage.read`](https://docs.neurosquad.ai/zh/card-sdk/permissions#usage-read)。 ```ts const summary = await card.usage('7d') // 'today' (default), '7d' or '30d' const dollars = (summary.totalCostMicroUsd / 1_000_000).toFixed(2) render(`$${dollars}${summary.partial ? ' + unpriced models' : ''}`) for (const row of summary.rows) { render(row.name, row.harness, row.inputTokens, row.outputTokens, row.costMicroUsd ?? 'no price') } ``` 数字与应用的[用量](https://docs.neurosquad.ai/zh/usage)页面相同，针对卡片所在的工作区：`period`、`from` 和 `to`（按本地日期，结束日不含），以及每个智能体的 `inputTokens`、`outputTokens`、`cacheReadTokens`、`cacheWriteTokens` 和 `costMicroUsd`。金额以**整数微美元**计（1 000 000 = 1 美元）。 价格未知的模型 `costMicroUsd` 为 `null`——从不为 `0`——不计入 `totalCostMicroUsd`，并会把 `partial` 设为 `true`。 --- ## 错误与限制 > CardSdkError 和每个错误码、各自的成因与应对方法，以及卡片协议的全部限制一览表。 Source: https://docs.neurosquad.ai/zh/card-sdk/api/errors ### `CardSdkError` 每一次拒绝——无论来自应用，还是来自 SDK 在请求离开卡片之前的自检——都是一个 `CardSdkError`： ```ts import { CardSdkError, isCardSdkError } from '@neurosquad/card-sdk' async function saveReport(text: string): Promise { try { await card.fs.writeText('reports/latest.md', text, { createDirs: true }) } catch (error) { if (isCardSdkError(error, 'PERMISSION_DENIED')) { card.ui.toast(`This needs the ${error.permission} permission`) } else if (isCardSdkError(error, 'RATE_LIMITED')) { await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 1000)) return saveReport(text) } else if (error instanceof CardSdkError) { card.log.error(error.code, error.method, error.hostMessage, error.data) } else { throw error } } } ``` | 属性 | 说明 | | --- | --- | | `code` | 下列错误码之一。 | | `message` | `method: host message [CODE] — hint`，可直接写入日志。 | | `hostMessage` | 仅应用给出的消息（英文，供开发者看——给用户看的请用你自己的文字）。 | | `method` | 失败的方法（来自调用时）。 | | `data` | 详情：schema 问题、`{ permission }`、`{ retryAfterMs }`、`{ conflict }`…… | | `hint` | 一行建议，仅部分错误码有。 | | `permission` | `PERMISSION_DENIED` 时：缺少的权限。 | | `retryAfterMs` | `RATE_LIMITED` 时：需要等待多久。 | | `issues` | `INVALID_PARAMS` / `BAD_REQUEST` 时：`{ path, keyword, message }[]`——参数哪里不符合。 | `isCardSdkError(error, code?)` 是一个类型守卫，可选地只匹配某个错误码。 ### 错误码 | 错误码 | 含义 | 通常的处理 | | --- | --- | --- | | `BAD_REQUEST` | 消息格式错误，或参数不是纯 JSON。 | 参数里有 `Date`、`Map` 或类实例——请发送纯数据。 | | `INVALID_PARAMS` | 参数不符合该方法的 schema。 | 查看 `error.issues` 中的精确路径。端口值不符合 schema、或引用了未设置的 `{{secret:…}}` 时也是这个错误。 | | `METHOD_NOT_FOUND` | 应用不认识这个方法。 | 应用版本较旧——用 `card.host.supports()` 检查。 | | `PERMISSION_DENIED` | 卡片包缺少该权限。 | 在清单中声明它；如果是可选权限，用 `card.permissions.request()` 申请。 | | `NOT_CONNECTED` | 目标卡片或智能体没有通过箭头与你的卡片相连。 | 请用户画一条箭头。 | | `NOT_FOUND` | 没有这张卡片、智能体、键、文件或端口。 | | | `QUOTA_EXCEEDED` | 某项配额已用完：存储字节数或键数、创建的卡片、文件监视器、智能体已满的提示词队列。 | 删除旧数据、停止旧监视器、稍后再试。 | | `RATE_LIMITED` | 调用过于频繁。`data.retryAfterMs` 说明需要等多久。 | 合并、去抖或退避。（标题、状态、徽章、概览和提醒永远不会因此被拒绝——SDK 会合并并重试它们。） | | `TOO_LARGE` | 消息、值或响应超出限制。 | 参见[限制](#limits)。 | | `TIMEOUT` | 未能及时得到回应（端口请求、命令、网络请求）。 | | | `BUDGET_PAUSED` | 工作区已超出预算；程序发出的提示词会被拒绝。 | 由用户在[预算](https://docs.neurosquad.ai/zh/cards/budget)卡片中提高上限。 | | `BUSY` | 智能体正处于一轮中，而你指定了 `whenBusy: 'fail'`。 | | | `HOST_NOT_ALLOWED` | `net.fetch` 访问的主机不在授权范围内，或解析到了被屏蔽的地址。 | 把主机加入 `network` 权限。 | | `NETWORK_ERROR` | DNS、连接、TLS 或流失败。 | | | `FS_DENIED` | 路径在工作区文件夹之外、在 `.git/` 之内，或经过了指向外部的链接。 | 使用相对路径。 | | `FS_ERROR` | 其他任何文件问题；`ifMtimeMs` 不匹配时带有 `data.conflict`。 | | | `NOT_VISIBLE` | 需要卡片在屏幕上：对话框、链接、聚焦、权限申请、发给危险模式智能体的提示词。 | 在 `card.visibility === 'visible'` 时重试。 | | `USER_CANCELLED` | 用户拒绝了（确认框、发给危险模式智能体的提示词），或调用被取消。 | | | `UNAVAILABLE` | 目标未在运行、工作区未打开、卡片已暂停，或连接已关闭。 | | | `PROTOCOL_MISMATCH` | 卡片是为比应用更新的协议开发的。 | 由用户更新 NeuroSquad。 | | `NOT_READY` | 在握手完成之前就发起了调用。 | 等待 `connect()` 完成。 | | `INTERNAL` | 应用中的 bug。 | 附上卡片日志报告问题。 | ### 限制 所有限制都在 `card.limits` 中（SDK 的 `LIMITS` 常量）。SDK 会在发送前检查容易检查的那些；应用会强制执行全部限制。 | 方面 | 限制 | | --- | --- | | **消息** | 每条 ≤ 1 MB（`fs.write` 和 `net.fetch` 请求，以及 `fs.read`、`fs.list`、`net.fetch` 响应：≤ 12 MB）；同时进行中的调用 ≤ 64 个（超出的由 SDK 排队）；每秒 200 次调用，突发 400 次；值的嵌套 ≤ 64 层、≤ 200 000 个节点 | | **卡片包** | 压缩包 ≤ 50 MB；解压后 ≤ 100 MB；≤ 5 000 个文件；每个 ≤ 20 MB；路径 ≤ 240 个字符、20 层；清单 ≤ 256 KB；图标 ≤ 128 KB | | **清单** | ≤ 40 个设置；≤ 16 个输入和 16 个输出；≤ 32 个工具；≤ 32 个网络主机；schema ≤ 500 个节点、16 层，`enum` ≤ 256 个选项和 16 KB，`const` ≤ 4 KB | | **存储** | 键 ≤ 256 个字符；值 ≤ 1 MB；≤ 10 000 个键；每张卡片 5 MB，每个卡片包 20 MB | | **网络** | 请求体 ≤ 5 MB；响应 ≤ 10 MB；同时 6 个；每分钟 120 个；≤ 5 次重定向；超时 30 秒（最长 120 秒），包括读取正文；≤ 4 个流，每个在 5 分钟无数据或达到 256 MB 后关闭 | | **文件** | 读写 ≤ 10 MB；列出 ≤ 5 000 项；≤ 20 个监视器 | | **智能体** | 提示词 ≤ 20 000 个字符，每张卡片每分钟 6 条（方法和端口合并计数），每个智能体排队 ≤ 10 条；命令 ≤ 20 000 个字符；每张卡片每分钟 30 条命令（`run` 和终端端口合并计数，超时 ≤ 120 秒），`write` 每分钟 60 次；屏幕 ≤ 500 行；输出每 100 毫秒或每 64 KB 投递一次 | | **工具** | 结果 ≤ 1 MB；超时 30 秒（最长 120 秒）；进度每秒 4 次 | | **端口** | 每个输出每秒 20 条消息；保留值 ≤ 256 KB；请求超时 30 秒（最长 120 秒） | | **卡片 UI** | 标题 ≤ 120（每分钟 30 次）；状态 ≤ 80，状态/徽章/概览各每分钟 120 次；概览每行 ≤ 160；提示条 ≤ 280（每 2 秒一条）；确认文本 ≤ 1 000（每分钟 10 次）；≤ 12 个菜单项（每分钟 30 次修改）；`settings.set` 每分钟 60 次；`tools.setEnabled` 每分钟 30 次；`usage.summary` 每分钟 6 次；提醒每 10 秒；聚焦每 5 秒；调整大小每 500 毫秒；≤ 4 张创建的卡片；剪贴板每秒一次、≤ 1 MB | | **日志** | 每行 ≤ 2 000 个字符；每秒 50 行 | | **页面** | 整个应用同时运行的卡片页面 ≤ 24 个；其中后台运行的 ≤ 8 个；隐藏 60 秒后暂停，有 1 秒时间保存；心跳每 5 秒，15 秒无响应显示“not responding”；启动后 10 秒内必须就绪 | --- ## React 绑定 > CardProvider 以及 @neurosquad/card-sdk/react 的各种 hook——上下文、设置、存储、智能体、端口、工具、主题、语言和可见性。 Source: https://docs.neurosquad.ai/zh/card-sdk/react `@neurosquad/card-sdk/react` 用一个 provider 包裹卡片，并把它的实时状态以 hook 的形式提供出来。 React 18.2+ 或 19 是对等依赖（peer dependency）；React 模板已经把一切配置好了。 ```tsx import { createRoot } from 'react-dom/client' import { CardProvider, useCardContext, useStorage } from '@neurosquad/card-sdk/react' function App() { const { instance, workspace } = useCardContext() const [count, setCount] = useStorage('count', 0) return ( ) } createRoot(document.getElementById('root')!).render( Connecting…

}> ) ``` ### `CardProvider` | 属性 | 含义 | | --- | --- | | `card` | 你自己连接好的 card——例如来自[模拟宿主](https://docs.neurosquad.ai/zh/card-sdk/testing)。不提供时，provider 会调用 `connect()`。 | | `connectOptions` | 传给 `connect()` 的选项。 | | `fallback` | 连接期间渲染的内容。 | | `errorFallback` | `(error) => ReactNode`，连接失败时渲染。默认显示错误消息。 | React 模板会先完成连接，再传入 `card`——这样同一个入口既能在应用中运行，也能配合模拟宿主在浏览器中预览。 ### Hook | Hook | 返回 | | --- | --- | | `useCard()` | [`Card`](https://docs.neurosquad.ai/zh/card-sdk/api#the-card-object)——用于没有专门 hook 的一切操作。 | | `useCardContext()` | 实时的 [`HostContext`](https://docs.neurosquad.ai/zh/card-sdk/api#context)；任何变化都会重新渲染。 | | `useSettings()` | `[settings, setSettings]`——`settings.values`、`settings.secrets`；setter 修改非密钥值。 | | `useStorage(key, initial, { scope? })` | `[value, setValue, { loading, error }]`——和 `useState` 一样，但会持久化。setter 立即更新并在后台写入；也接受函数。`scope: 'package'` 会跟随卡片其他副本的写入。 | | `useAgents()` | `{ agents, loading, error, refresh }`——随状态和变更事件保持最新。需要 `agents.read`。 | | `useAgentStatus(agentId)` | 某个智能体的状态，或 `undefined`。 | | `usePort(input?)` | `{ data, message }`——某个输入（或任意输入）最后收到的值。 | | `useEmit(output)` | 一个稳定的 `(data) => Promise`，用于在某个输出上发送。 | | `usePortRequest(input, handler)` | 挂载期间应答某个请求型输入。 | | `usePeers()` | 相连的卡片及其端口，实时更新。 | | `useTool(name, handler)` | 挂载期间实现清单中的某个工具；总是调用最新的处理函数。 | | `useCardEvent(event, handler)` | 挂载期间监听任意事件；总是调用最新的处理函数。 | | `useTheme()` | 实时的 `ThemeSnapshot`（CSS 变量已经应用好了）。 | | `useLanguage()` | 实时的 `{ language, locale }`。 | | `useTranslator(catalog)` | 一个[翻译函数](https://docs.neurosquad.ai/zh/card-sdk/api/environment#i18n)，切换语言时会重新渲染。请在组件外定义 catalog。 | | `useVisibility()` | `visible`、`offscreen`、`overview` 或 `hidden`。 | | `usePaused()` | 没人能看到卡片正文时为 `true`——此时暂停动画和轮询。 | | `useExpanded()` | 卡片是否已展开。 | ### 更完整的示例 ```tsx import type { Catalog } from '@neurosquad/card-sdk' import { useAgents, useCard, useEmit, usePaused, usePort, useTool, useTranslator } from '@neurosquad/card-sdk/react' import { useEffect } from 'react' const catalog: Catalog = { en: { waiting_one: '{{count}} agent waits for you', waiting_other: '{{count}} agents wait for you' }, ru: { waiting_one: '{{count}} агент ждёт вас', waiting_few: '{{count}} агента ждут вас', waiting_many: '{{count}} агентов ждут вас', waiting_other: '{{count}} агента ждут вас' }, zh: { waiting_other: '{{count}} 个智能体在等你' } } export function Waiting() { const card = useCard() const t = useTranslator(catalog) const paused = usePaused() const { agents } = useAgents() const waiting = agents.filter((a) => a.status === 'needs-input') const { data: note } = usePort('notes') const emit = useEmit('digest') // Keep the overview tile and attention in step with the data. useEffect(() => { void card.setOverview({ primary: t('waiting', { count: waiting.length }), icon: 'bell' }) void card.attention(waiting.length > 0 ? 'needs-input' : 'none').catch(() => undefined) }, [card, t, waiting.length]) useTool('list_waiting', () => waiting.map((a) => a.name)) return (

{t('waiting', { count: waiting.length })}

{note ? 
{note}
: null}
) } ``` > 会调用应用的 hook（`useAgents`、`useStorage`）不会抛出异常，而是在它们的 `error` 字段中报告失败—— > 缺少权限时，那里会出现一个带 `PERMISSION_DENIED` 的 `CardSdkError`。 ### 使用本地 SDK 副本 如果卡片通过 `file:` 链接依赖 SDK，npm 会创建符号链接，Vite 可能在 SDK 旁边加载第二份 React——此时 hook 会报 “Invalid hook call”。 React 模板的 `vite.config.ts` 已经包含 `resolve: { dedupe: ['react', 'react-dom'] }`；在你自己的配置中请加上它，或在卡片的 `.npmrc` 中设置 `install-links=true`。 --- ## UI 套件与样式 > 随心所欲地设计卡片样式，或借助基于应用实时主题的可选 ui.css 套件呈现原生外观——类名、变量，以及沙箱对样式、字体和图片的规则。 Source: https://docs.neurosquad.ai/zh/card-sdk/styling 在自己的方框内，卡片就是一个普通网页：任何框架、任何 CSS、canvas、WebGL、WebAssembly 都行。设计样式有两种方式： - **原生外观**——可选的 `ui.css` 套件：一套基于应用实时主题的小型深色按钮、输入框、列表和徽章。用它做出的卡片看起来就像 NeuroSquad 的一部分，并跟随它的主题。 - **你自己的设计**——不用这个套件。主题变量依然存在，想借用某个颜色时随时可用。 ### UI 套件 ```html ``` ```ts import '@neurosquad/card-sdk/ui.css' // with a bundler (React template) ``` 在 `` 上加 `class="ns-kit"` 即可获得基础排版、背景和滚动条，然后使用这些类： ```html

Test radar

3 failed
  • checkout › pays
  • auth › logs in
``` | 分组 | 类名 | | --- | --- | | 布局 | `ns-kit`、`ns-stack`（纵向）、`ns-row`（横向）、`ns-spread`（两端对齐）、`ns-grow`、`ns-scroll`、`ns-pad`、`ns-divider` | | 容器 | `ns-surface`、`ns-surface--inset`、`ns-callout`、`ns-callout--success`、`ns-callout--danger`、`ns-empty` | | 文本 | `ns-title`、`ns-subtitle`、`ns-muted`、`ns-small`、`ns-mono`、`ns-truncate`、`ns-kbd`、`ns-help`、`ns-error` | | 按钮 | `ns-btn` + `--primary`、`--secondary`、`--outline`、`--ghost`、`--danger`、`--sm`、`--lg`、`--icon` | | 表单 | `ns-field`、`ns-label`、`ns-input`、`ns-textarea`、`ns-select`、`ns-switch` | | 列表 | `ns-list`、`ns-list-item` | | 状态 | `ns-badge` + `--accent`、`--success`、`--warning`、`--danger`；`ns-dot` + 同样的修饰；`ns-spinner`、`ns-progress` | 在应用之外（浏览器预览中），套件会回退到应用的深色主题，所以预览效果也是正确的。 ### 主题变量 `connect()` 会把应用的实时主题以 `--ns-` 变量的形式写到 `` 上——`--ns-background`、`--ns-surface`、`--ns-foreground`、 `--ns-muted`、`--ns-accent`、`--ns-success`、`--ns-warning`、`--ns-danger`，以及它们的 `-foreground` 和 `-soft` 变体、`--ns-border`、 `--ns-focus`、`--ns-field-*`、`--ns-radius`、`--ns-font-sans`、`--ns-font-mono` 等（完整列表见[主题](https://docs.neurosquad.ai/zh/card-sdk/api/environment#theme)）。 在你自己的 CSS 中使用它们，卡片就会跟随应用： ```css :root { color-scheme: dark; } body { margin: 0; background: var(--ns-background, #0b0b0f); color: var(--ns-foreground, #fafafa); font: 13px/1.45 var(--ns-font-sans, system-ui, sans-serif); } .chip { border-radius: calc(var(--ns-radius, 0.5rem) * 2); background: var(--ns-accent-soft); color: var(--ns-accent-soft-foreground); } ``` 如果页面也需要在应用之外渲染，请像上面那样给变量设置回退值。想让你自己的颜色不受影响，请使用 `connect({ theme: false })` 连接。 ### 页面的沙箱规则 你的页面从它自己的卡片包中提供，并带有严格的内容安全策略（CSP）。实际上意味着： - **不能有内联脚本或 `onclick="…"` 属性**——把代码放进 `.js` 文件。`eval` 和 `new Function` 也被禁止（WebAssembly 允许）。 - **不能引用外部文件。** 脚本、样式、字体和图片都必须在卡片包内；`` 或 `` 会被拦截。 `data:` 和 `blob:` 图片可以用。远程数据请使用 [`card.net.fetch`](https://docs.neurosquad.ai/zh/card-sdk/api/network)，再把图片转成 `blob:` URL。 - **内联样式没问题**（`style="…"` 和 `