Card SDK 更新日志

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

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

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

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

尚未发布

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

1.2.0 — 2026-10-04

需要 NeuroSquad 0.1.264 或更高版本。

新增

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

兼容性。 权限和范围与 agents.usage 相同——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?)：通过箭头连接的某个 AI 智能体在一个时间窗口内的运行情况——模型请求、按类型划分的词元、提示词、工作时间和总用时、费用（向上取整，附带 costPartial）、模型和提供方。也就是官方 Run Stats 卡片显示的内容。用时来自应用自己的状态历史，因此即使卡片处于暂停状态也是准确的。
• 类型 AgentUsage。
• 模拟宿主：agentUsage 选项和 setAgentUsage()。
• 已验证卡片目录的契约类型（VerifiedCatalog、VerifiedEntry、validateVerifiedCatalog 等）——1.0.0 之后首次进入包中。

行为

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

兼容性。 权限 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——已验证卡片目录。

1.0.0 — 2026-09-25

需要 NeuroSquad 0.1.123 或更高版本。首个公开版本：connect() 和包含完整 API 的类型化 Card、清单及其 JSON Schema、权限、React 绑定、可选的 UI 套件、模拟宿主以及 neurosquad-card 命令行工具。