# 常见问题与排错

> 面向卡片用户和作者的解答，以及常见错误的修复方法——卡片连接不上、脚本被拦截、安装后文件缺失、权限与箭头错误、速率限制。

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

## 面向所有人

### 社区卡片安全吗？

它被封闭在自己的方框里，只能做你授权的事——应用会检查它的每一个请求。但权限本身可能很强：被允许向智能体发提示词或运行命令的卡片，
可以做那些智能体和终端能做的任何事。只安装你信任的人做的卡片，并仔细阅读对话框。参见[安装社区卡片](https://docs.neurosquad.ai/zh/card-sdk/community-cards)。

### 有张卡片在卡片里让我输入 API 密钥。我该输入吗？

不该。NeuroSquad 从不在卡片里索要密钥。做得好的卡片会在它的 **Settings…** 表单（应用自己的表单）中请求密钥，
密钥在那里会被加密保存，永远不会给卡片看到。输入到卡片正文里的任何内容都会交给卡片。

### 为什么卡片显示“Paused to save memory”？

一段时间没看的卡片会被暂停，以保持大画布的流畅。看一眼它——它会从中断的地方继续。

### 卡片显示“Not responding”。

它的代码已经忙了超过 15 秒。点击 **Reload**。如果反复出现，请在 **Settings → Custom cards** 中关闭这张卡片并告诉它的作者。画布上的其他东西都不受影响。

### 为什么我不能在手机上使用自定义卡片？

卡片代码只在电脑上运行；手机显示它的标题栏和摘要。参见[在手机上](https://docs.neurosquad.ai/zh/card-sdk/phone)。

### 安装时提示 GitHub 正在限流。

GitHub 会限制匿名下载。在 **Settings → Custom cards** 中添加 **GitHub token**——它也能让你从私有仓库安装。

## 面向作者

### `connect()` 以 `UNAVAILABLE` 失败。

- **在应用之外打开**（浏览器标签页）：这是预期行为。请像模板那样使用[模拟宿主](https://docs.neurosquad.ai/zh/card-sdk/testing)来预览。
- **在应用之内：** SDK 必须由入口脚本导入，这样它才能在页面加载完成前开始监听。延迟 `import()` SDK 可能会错过应用的握手。

### 我的脚本没有运行。控制台说它违反了内容安全策略。

卡片不能运行内联脚本或 `onclick="…"` 属性，也不能从互联网加载脚本、样式、字体或图片。把代码移到 `.js` 文件中、打包你的依赖、把字体放进卡片包。
`npx @neurosquad/card-sdk validate` 会指出入口页面中有问题的地方。参见[沙箱规则](https://docs.neurosquad.ai/zh/card-sdk/styling#sandbox-rules-for-pages)。

### 用 `dev` 时正常，但从 GitHub 安装后页面是空白的，或者缺文件。

安装的卡片就是你的仓库在那个提交时的内容。通常是构建产物没有提交（`.gitignore` 中有 `dist/`），或者资源用了绝对路径（`/assets/…`）
而不是相对路径（`./assets/…`；Vite：`base: './'`）。运行 `pack --dry-run` 查看用户会拿到什么。

### `validate` 提示某个文件“exists but would not be in the package (ignored by git?)”。

文件列表就是 git 会放进 GitHub 压缩包的内容：已跟踪的文件，加上未被忽略的未跟踪文件。提交这个文件，或取消对它的忽略。
当卡片文件夹位于另一个仓库中被忽略的文件夹内时也会出现这种情况——把它移出来，或者给它一个独立的仓库。

### `PERMISSION_DENIED`

清单中没有声明该权限、用户撤销了它，或者它是可选权限且尚未授予。`error.permission` 会给出是哪一项。声明它，或在卡片可见时用
`card.permissions.request()` 申请。对于链接的文件夹，修改清单中的权限后会再次询问你。

### `NOT_CONNECTED`

你要交互的智能体、终端或卡片没有通过箭头与你的卡片相连。请用户画一条——`card.ports.peers` 和 `agent.connected` 会告诉你哪些已相连。

### `emit` 返回 0。

没有任何下游对端有兼容的输入。检查箭头的方向（从你的卡片指向对端）、类型（参见[类型转换](https://docs.neurosquad.ai/zh/card-sdk/api/ports#conversion)），
以及对于内置卡片，你是否有 `cards.connected`。

### `NOT_VISIBLE`

对话框、链接、镜头聚焦、权限申请、设置表单，以及发给危险模式智能体的提示词，都需要卡片在屏幕上。请在用户操作时调用，或等待 `lifecycle.visibility` 变为 `visible`。

### `RATE_LIMITED`

等待 `error.retryAfterMs`。逐方法的限制：提醒每 10 秒、提示条每 2 秒、调整大小每 500 毫秒、剪贴板每秒一次、提示词每分钟 6 条、
命令每分钟 30 条、网络每分钟 120 个、端口输出每秒 20 条。参见[限制](https://docs.neurosquad.ai/zh/card-sdk/api/errors#limits)。

### `HOST_NOT_ALLOWED`

URL 的主机不在你的 `network` 主机列表中（子域名不会匹配精确主机——请用 `*.example.com`）、重定向跳到了别处，或者主机解析到了私有地址。
访问 `localhost` 请声明 `network.local`。

### 我的工具在智能体那里始终没出现。

- 只有通过箭头与卡片相连的智能体才能看到它的工具，而且只限支持 MCP 的智能体（Claude Code、Codex、Qwen Code）。
- 智能体可能需要新的一轮才会注意到工具列表的变化。
- 检查名称：智能体看到的是 `<card name with _>_<tool>`，例如 `test_radar_run_tests`。
- `card.tools.setEnabled(name, false)` 会对卡片的所有副本隐藏它。

### 在哪里能看到我的卡片的错误？

运行 `npx @neurosquad/card-sdk dev`：它会输出 `card.log.*`、未捕获的错误和被拒绝的 Promise。应用也会保留每个卡片包最近 256 KB 的日志。

### 我的卡片能在后台持续运行吗？

声明 `background` 权限。没有它时，所在工作区隐藏一分钟的卡片会被暂停：在 `card.lifecycle.onSuspend` 中保存，在 `launch === 'resumed'` 时恢复。

### 能用 `localStorage`、IndexedDB、Cookie、WebSocket、`window.open` 吗？

不能——沙箱没有可以存储的源（origin），也没有弹窗。请使用 `card.storage`、`card.net.fetch`（流式响应可以覆盖服务器发送事件；
第 1 版不支持 WebSocket）和 `card.openLink`。

### 卡片能读取剪贴板、使用摄像头或麦克风、选择文件吗？

第 1 版不能。卡片可以向剪贴板写入文本（`clipboard.write`），并处理工作区文件夹中的文件（`fs.read`、`fs.write`）。

### 有卡片市场吗？

还没有——卡片通过它们的 GitHub 地址分享。

### 我的表单既不重新加载，也不提交任何东西。

这是有意为之：`submit` 事件会触发，但卡片页面永远不会跳转或提交表单。请在你的 `submit` 处理函数中处理数据
（调用 `event.preventDefault()`）。参见[沙箱规则](https://docs.neurosquad.ai/zh/card-sdk/styling#sandbox-rules-for-pages)。

### 重新加载后卡片还在闪烁提醒。

页面上一次运行设置的提醒会在重新加载和更新后保留。启动时检查 `card.context.chrome?.attention`，
在原因消失后用 `card.attention('none')` 清除它。

### 我明明构建了，包里却没有 `dist/`。

父仓库的 `.gitignore` 可能忽略了 `dist`。在卡片自己的 `.gitignore` 中加入 `!dist/`（React 模板已经这样做了），
然后用 `pack --dry-run` 检查。

### 我的复制按钮没有反应。

页面无法通过 `copy` 事件或 `execCommand` 写入剪贴板。声明 `clipboard.write`（设为可选即可），并调用 `card.copyText(text)`。

### `new Worker('worker.js')` 失败。

卡片中只有 blob Worker 可用：获取脚本、生成一个 `Blob`，再用 `URL.createObjectURL(blob)` 启动 Worker。

### 我的卡片安装被拒绝：“only official cards may call themselves…”。

不是从官方组织发布的卡片，名称或作者中不能使用“NeuroSquad”“official”或“verified”。请改名。

### 我有 `fs.write`，写入却以 `FS_DENIED` 被拒绝。

该路径[受保护](https://docs.neurosquad.ai/zh/card-sdk/api/files#protected)（`.git`、智能体设置、CI 工作流、包管理器设置），
或者工作区是主文件夹或磁盘根目录——在那里卡片得不到任何文件访问权限。