# @coda-console/claude 中文文档

规范地址：https://npmcn.com/package/%40coda-console/claude/

版本：1\.11\.0
npm 元数据更新时间：2026-11-09T16:47:25.483Z
中文译文更新时间：2026-11-10T05:27:50.250Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40coda-console/claude
原文对照：https://npmcn.com/package/%40coda-console/claude/?lang=original
项目主页：https://github.com/coda-console/coda-plugins#readme
源码仓库：https://github.com/coda-console/coda-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：138 kB，26 个文件
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2026-10-21T05:22:42.891Z
- 最新版本发布：2026-11-09T16:47:25.114Z
- 近 30 天下载量：4866（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

克劳德探员SDK

## 安装

```sh
npm install @coda-console/claude
```

也可以使用：`pnpm add @coda-console/claude`、`yarn add @coda-console/claude`、`bun add @coda-console/claude`

## README

# Claude

Claude SDK Agent：Coda 基于 Claude Agent SDK 写的 ACP 入口，一个进程一个 SDK 会话；资源页的「Claude」显示会话报告的额度，可从 Coda 登录。

## 认不出的东西

Claude Code 会自己长出新东西：SDK 升级带来新的消息类型，服务端让模型返回新的内容块，模型多了新的原生工具。 入口不认识时若悄悄丢掉，用户就看不到本该看到的。入口为此有三层防范：

1.  **登记**（`agent/registry.mjs`）：锁定的 SDK 的每种消息（`SDKMessage` 的类型与子类型，如 `system/init`）、助手消息与用户消息里的每种内容块， 各注明转给 Coda 还是明确不显示，附一句原因。SDK 没有声明、却照样转来的几种内部消息（`system/post_turn_summary` 等）也登记为不显示。
2.  **升级检查**（`test/plugins/claude/sdk-registry.mjs`，`npm test` 里跑）：用 TypeScript 编译器的类型检查器（仓库的 devDependency `typescript`） 读锁定 SDK 入口导出的 `SDKMessage`，展开联合取每个成员 `type`、`subtype` 的字面量，再顺着助手、用户消息 `message.content` 的元素类型 展开内容块的联合取 `type`，有没登记的就失败并列出来。别名、交叉类型、再导出与泛型都由检查器解析；`type`、`subtype` 不全是字符串字面量的 （比如 `string`）判失败并说出是哪个成员，不会悄悄放过。
3.  **运行时报告**：Coda 在 `initialize` 的 `clientCapabilities._meta.coda.unrecognized` 里表示收，入口才发 `_coda/unrecognized` （协议 5.4.0，`docs/agent-protocol.md`「没适配的东西」），同一会话同一 `name` 只报一次；没表示就什么都不发，下面的后备显示照旧。
    -   没登记的消息报 `sdk:<type>/<subtype>`（没有子类型的报 `sdk:<type>`），没登记的内容块报 `block:<type>`，都是 `kind: output`。 消息和助手消息里的内容块带文字的（`text`，字符串或文字块的 `content`，消息的 `message.content`）照常显示成 Claude 的回复，报 `lost: false`； 没有文字的报 `lost: true` 并附一句说明。结果、助手与用户消息、流式事件、额度事件不论子类型都按类型处理，子类型没登记也报 `lost: false`。
    -   用户消息是给模型的输入（工具结果、Claude Code 补的说明等），不是 Claude 说的话：里面没登记的内容块只报不显示，`lost: true`， 会话里留一条「没有显示」的说明。
    -   每轮开始的 `system/init` 列出模型能用的工具，和已知清单 `agent/known-tools.json` 对照，清单里没有的报 `tool:<名字>`（`kind: tool`、`lost: false`）。 MCP 工具（`mcp__` 开头）是用户配的，不比。清单是锁定 SDK 在本入口的启动选项下 `system/init` 列出的工具，加上入口另外认识的 （`agent/tools.mjs` 里的、旧版 Claude Code 的）。

### 升级 SDK 时

1.  升 `@anthropic-ai/claude-agent-sdk` 的 PR（Dependabot 开的，或手动改版本并更新 `package-lock.json`）先要让 `npm test` 里的升级检查通过： `node test/plugins/claude/sdk-registry.mjs` 列出新 SDK 有、登记表没有的消息类型与内容块。
2.  逐个看新 SDK 的 `sdk.d.ts` 与它带的 `@anthropic-ai/sdk`：要显示的在 `agent/session.mjs` 里处理，再登记为转给 Coda；不显示的登记并写明原因。 检查读不出声明时，按报错补读法或改登记，不要跳过。
3.  用新 SDK 跑一轮真实会话，把新出现的原生工具加进 `agent/known-tools.json`（会话里没登记的工具会报成 `tool:<名字>`，遥测按 Agent 版本计数）； 要按读写、命令等显示的，同时在 `agent/tools.mjs` 里归类。

## 常见问题

### @coda-console/claude 是什么？

克劳德探员SDK

### 如何安装 @coda-console/claude？

在项目目录运行 npm install @coda-console/claude，或使用 pnpm add / yarn add / bun add。

### @coda-console/claude 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/coda-console\_\_claude 是否存在。

### @coda-console/claude 可以商用吗？

@coda-console/claude 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @coda-console/claude 的下载量有多少？

根据 npm 官方下载统计，@coda-console/claude 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,866 次，日均约 162 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @coda-console/claude 还在维护吗？

最新版本 1\.11\.0 发布于 2026/11/10（今天）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/10/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。