# Card SDK 更新日志

> @neurosquad/card-sdk 和卡片契约的逐版本变化——新 API、所需的 NeuroSquad 版本、权限以及迁移说明。

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

`@neurosquad/card-sdk` 及其使用的卡片契约的变化，最新的在前。同样的内容也作为 `CHANGELOG.md` 随包发布。

卡片作者需要关注三个版本：

- **SDK / 契约版本**（`SDK_VERSION`）——即下面的各个标题。新的方法和事件在次版本中加入。
- **通信协议**（`CARD_PROTOCOL_VERSION`，仍为 **1**）——为更新协议构建的卡片会被旧版应用以 `PROTOCOL_MISMATCH` 拒绝。
- **NeuroSquad 版本**——即宿主。使用较新的方法前请检查 `card.host.supports('<方法>')`；如果卡片离不开该方法，可以设置 [`minAppVersion`](https://docs.neurosquad.ai/zh/card-sdk/manifest)。

下文中的 NeuroSquad 版本是首个包含该变化的公开发布版本。

## 尚未发布

**宿主变化，NeuroSquad 0.1.264。** 卡片的页面进程自行崩溃时（通常是电脑内存不足），会被自动重新加载，而不是一直显示为灰色方块；新页面以 `launch: 'reloaded'` 启动。10 分钟内这样重新加载三次后，卡片会显示*卡片停止工作*和 **Reload** 按钮。你的卡片无需修改；需要在重新加载后保留的内容请放在[存储](https://docs.neurosquad.ai/zh/card-sdk/api/storage-settings)中。

## 1.2.0 — 2026-10-04

需要 NeuroSquad **0.1.264** 或更高版本。

**新增**

- [`card.agents.timeline(agentId, since, until?)`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#timeline)：通过箭头连接的某个 AI 智能体的模型请求（完成时间；智能体日志有记录时还包括发送时间；词元；工具调用）、以连续区段表示的状态，以及它的回合——也就是官方 [Agent Pulse](https://docs.neurosquad.ai/zh/cards/agent-pulse) 卡片绘制的内容。`requestTimes` 为 `start-end`、`end` 或 `none`；最多 2000 个请求（保留最新的，并设置 `truncated`）。
- 类型 `AgentTimeline`、`AgentRequestSpan`、`AgentTurnSpan`。
- [模拟宿主](https://docs.neurosquad.ai/zh/card-sdk/testing)：`agentTimeline` 选项和 `setAgentTimeline()`。

**兼容性。** 权限和范围与 `agents.usage` 相同——[`usage.read`](https://docs.neurosquad.ai/zh/card-sdk/permissions#usage-read) 加上连接到 AI 智能体的箭头；没有新权限。每张卡片每分钟最多 60 次调用。旧版应用会返回 `METHOD_NOT_FOUND`：请检查 `card.host.supports('agents.timeline')`。

## 1.1.0 — 2026-10-04

需要 NeuroSquad **0.1.264** 或更高版本。

**新增**

- [`card.agents.usage(agentId, since, until?)`](https://docs.neurosquad.ai/zh/card-sdk/api/agents#usage)：通过箭头连接的某个 AI 智能体在一个时间窗口内的运行情况——模型请求、按类型划分的词元、提示词、工作时间和总用时、费用（向上取整，附带 `costPartial`）、模型和提供方。也就是官方 [Run Stats](https://docs.neurosquad.ai/zh/cards/run-stats) 卡片显示的内容。用时来自应用自己的状态历史，因此即使卡片处于暂停状态也是准确的。
- 类型 `AgentUsage`。
- [模拟宿主](https://docs.neurosquad.ai/zh/card-sdk/testing)：`agentUsage` 选项和 `setAgentUsage()`。
- [已验证卡片](https://docs.neurosquad.ai/zh/card-sdk/verified-cards)目录的契约类型（`VerifiedCatalog`、`VerifiedEntry`、`validateVerifiedCatalog` 等）——1.0.0 之后首次进入包中。

**行为**

- 未报告的词元数为 `null`，而不是 `0`：智能体日志中没有该数字、智能体命令行工具没有可读的用量日志（Amp、Cursor：`usageReadable: false`）、用户自己的模型服务器发来的缓存计数为零、非 Anthropic API 下的缓存写入为零。请显示为“未报告”。
- 没有已知价格的模型（包括用户自己服务器上的模型）的 `costMicroUsd` 为 `null`，而不是 0。
- `prompts` 不计入没有任何模型请求就结束的回合（状态闪动）。

**兼容性。** 权限 [`usage.read`](https://docs.neurosquad.ai/zh/card-sdk/permissions#usage-read)（1.0 中已有；现在它也为通过箭头连接的智能体开放此方法）。未连接——`NOT_CONNECTED`；shell——`INVALID_PARAMS`。每张卡片每分钟最多 60 次调用。旧版应用会返回 `METHOD_NOT_FOUND`：请检查 `card.host.supports('agents.usage')`。协议仍为 1，用 1.0.0 构建的卡片无需修改即可运行；升级时把依赖改为 `^1.1.0`（或 `^1.2.0`）即可，不需要改代码。

### 契约 1.0 期间的宿主变化

在 SDK 1.0.0 与 1.1.0 之间发布，SDK 版本未变；列在这里是因为它们可能改变卡片看到的内容。

- **0.1.253、0.1.230、0.1.160、0.1.141、0.1.138**——保留了更多清单 `name` 值：Graphify、记忆、Context7、Code Graph、RTK 和 caveman 插件的工具族，画布连线工具（`canvas_connect`、`canvas_disconnect`、`canvas_list`），以及 `agent_set_model` 和 `neurosquad_models`。使用这些名称的清单无法通过验证。
- **0.1.214**——`fs.*` 拒绝写入更多会在下次 push 时运行代码的文件：GitLab、Jenkins、CircleCI、Buildkite、Travis、Bitbucket、Drone、AppVeyor 和 Azure Pipelines 的配置。WSL 中的工作区，`workspace.path` 是这台电脑看到的路径；SSH 工作区的该值为空，`fs.*` 返回 `UNAVAILABLE`。`usage.summary` 对费用向上取整，极小的计价费用不会显示为 0。`neurosquad-card dev` 需要打开开发者模式。
- **0.1.128**——`agents.lastReply` 适用于所有有可读对话记录的智能体命令行工具，而不仅是 Claude Code；智能体内置的 `reply` 端口也会为它们发送最终回答。
- **0.1.125**——[已验证卡片](https://docs.neurosquad.ai/zh/card-sdk/verified-cards)目录。

## 1.0.0 — 2026-09-25

需要 NeuroSquad **0.1.123** 或更高版本。首个公开版本：`connect()` 和包含完整 API 的类型化 `Card`、[清单](https://docs.neurosquad.ai/zh/card-sdk/manifest)及其 JSON Schema、[权限](https://docs.neurosquad.ai/zh/card-sdk/permissions)、[React 绑定](https://docs.neurosquad.ai/zh/card-sdk/react)、可选的 [UI 套件](https://docs.neurosquad.ai/zh/card-sdk/styling)、[模拟宿主](https://docs.neurosquad.ai/zh/card-sdk/testing)以及 [`neurosquad-card` 命令行工具](https://docs.neurosquad.ai/zh/card-sdk/cli)。

> 使用了较新的方法，但又希望卡片能安装到旧版应用上？不要设置 `minAppVersion`，改为检查 `card.host.supports()`，在方法不可用时显示一句简短的“请更新 NeuroSquad 以使用此视图”。