# agent-cloud-kit 中文文档

规范地址：https://npmcn.com/package/agent-cloud-kit/

版本：1\.0\.0-rc\.2
npm 元数据更新时间：2026-11-03T01:30:48.018Z
中文译文更新时间：2026-11-03T02:24:14.464Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/agent-cloud-kit
原文对照：https://npmcn.com/package/agent-cloud-kit/?lang=original
项目主页：https://github.com/ramon-sg/agent-cloud-kit#readme
源码仓库：https://github.com/ramon-sg/agent-cloud-kit

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

- 包体积（解压后）：208 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-11-02T14:50:59.479Z
- 最新版本发布：2026-11-03T01:30:47.645Z
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

零依赖CLI，准备Claude Code云会话。

## 安装

```sh
npm install agent-cloud-kit
```

也可以使用：`pnpm add agent-cloud-kit`、`yarn add agent-cloud-kit`、`bun add agent-cloud-kit`

## README

# agent-cloud-kit

一个零依赖的CLI [克劳德代码在网上](https://claude.ai/code) 云 会话。它安装一个repo pin的工具版本，启动Docker，完成部分 当保存的机器不是repo要求的机器时，它会告诉您 平台没有记录的云沙箱限制。

> 不隶属于Anthropic或由Anthropic认可的。作品与克劳德代码在网络上。
> 
> 继续 `@ramon-sg/claude-cloud` （它是1.0.0），没有自动迁移：安装这个包 和运行 `init` 再一次。

-   用TypeScript编写，发布编译， **无运行时依赖项**、节点 `>=20` (云 image附带Node 22，因此它在安装repo的任何工具之前运行)。
-   这个 **回购决定版本**： `.claude/cloud.json` 固定这个包的确切版本， 所以更新它是一个提交。

## 它解决了什么

安装Node和启动Docker需要几行shell。昂贵的部分是什么 平台不会告诉你：

-   出口代理阻止GitHub的发布和GitHub的GraphQL API，所以从 GitHub失败。 `agent-cloud-kit` 从nodejs.org安装Node；Bun, Deno， pnpm和Yarn from npm； 和来自PyPI的uv。
-   设置脚本从 `/home/user`，不从回购，和失败是沉默的。
-   超过5分钟的设置不会留下保存的机器。
-   两个 `apt` 同时运行在DPKG锁上发生冲突，因此apt工作是串联运行的。
-   `dockerd` 是关闭的，克隆是部分的(浅的，没有 `origin/<default branch>`）。
-   没有IPv6。
-   代理取代TLS，并且 `docker build` 不信任它的CA。
-   恢复的会话不会再次运行安装程序，更改安装程序也不会重新构建 保存机器。

## 流

1.  **安装代理工具** 使用agent-kitchen（配置，钩子和技能到达repo）。
2.  **运行 `npx agent-cloud-kit prepare`** 在本地终点站。它询问在哪里工作，与 与代理厨房相同的菜单(`--pr` 或者 `--here` 跳过):
    -   **En un PR nuevo** （默认）：在一个日期的分支上创建一个工作树 `origin`，所以你 分支和未提交的文件不受影响；运行 `init`，克劳德打开本地与 `cloud-ready` 技能让它可以和你一起写云准备，然后写手册， 提交、推送并打开PR草案。
    -   **En la drama actual, sin commit：** 在结帐时也这样做，然后停在那里；你审查 与 `git diff`，承诺，推动，然后跑 `npx agent-cloud-kit verify`.
3.  **在claude.ai中配置环境** 后 `docs/agent-cloud.md`,这 `prepare` 由你的 `.claude/cloud.json`． 文件不断增长：当技能，本地 或者在云中，发现一个域或环境变量缺失，它将其添加到 `.claude/cloud.json`，重新生成文档，并在会话中告诉您要添加哪些内容 claude.ai。
4.  **云端验证：** `prepare` （新公关）或 `verify` （当前分支，一次推送） 发射 `claude --cloud` 在那个分支上，运行一个真正的云会话 `cloud-ready verify`， 修复PR中失败和报告的内容 `npx agent-cloud-kit verify` 不管什么时候 改变环境。

`claude --cloud` 使用选定的环境 `/remote-env` 在 `claude`，以及Claude GitHub 应用程序必须安装在仓库（没有它的会话不能推送）。在云里， `gh api` (REST)作品;GraphQL (`gh pr list`， `gh pr create`)被阻塞。如果 `prepare` 被打断, `npx agent-cloud-kit prepare --resume` 继续在现有的工作树中。

## 对测试没有意见

这个包不强制任何测试方式，并且一个repo可能根本没有测试(那么 云计算只需要一台准备好的机器)。这个 `cloud-ready` Skill已经找到测试你的repo 告诉您哪些将在云中运行，并建议对云进行调整 准备或仅在需要时，它们的云变体。没有你的同意，什么也改变不了。

### 这个 `cloud-ready` 技能

`init` 复制到 `.agents/skills/cloud-ready` 链接到 `.claude/skills/cloud-ready`， 因为克劳德·科德没有发现 `.agents/skills`． 提交两个。 `cloud-ready configure` 运行 和你在一起； `cloud-ready verify` 在云会话中运行。技能和生成的 手册是用西班牙语写的。

## 设置claude.ai

在环境中形成at `https://claude.ai/code`：

1.  **网络访问:** 选择 _自定义_ 并保持 **还包括通用包的默认列表 经理** 检查。添加任何额外的域名 `apt` 需要Repos或设置步骤，每行一个。 运行 `agent-cloud-kit doctor` 在会话中查看哪些主机被阻塞（它使用它进行探测） `curl`， 所以它像设置一样通过代理)。如果安装程序从未运行过，请使用 `npx agent-cloud-kit doctor`.
    
2.  **设置脚本:** 云作为根运行它 `/home/user`在克劳德开始之前：
    
    ```bash
    #!/bin/bash
    npx -y agent-cloud-kit@1 setup
    ```
    
    这个 `@1` 只固定发射器。每个回购然后重新发布它所要求的确切版本，所以a 有意编辑此字段，采用新的启动器专业。强制保存的机器 重新构建，更改此字段中的任何内容（带有日期的注释可以工作）。
    
3.  在每次回购运行中 `npx agent-cloud-kit init`，然后承诺 `.claude/cloud.json`， `.claude/settings.json`， `.agents/skills/cloud-ready` 和 `.claude/skills/cloud-ready` 链接。
    

创建会话时读取环境更改：启动新会话以测试它们。一个 恢复的会话不会再次运行安装程序。

## `.claude/cloud.json`

它生活在 `.claude/` 而不是在 `package.json` 所以没有Node的repos可以使用它。一个JSON 模式随包(`schema.json`）. 未知字段被报告并被忽略 损坏的文件永远不会停止会话。

```json
{
  "$schema": "https://unpkg.com/agent-cloud-kit@1.0.0/schema.json",
  "version": "1.0.0",
  "aptRepos": ["https://example.com/setup.deb.sh"],
  "apt": ["direnv", "jq"],
  "domains": ["registry.example.com"],
  "docker": { "pull": "auto" },
  "setup": ["scripts/cloud-setup-extra.sh"],
  "session": ["scripts/worktree-setup.sh"],
  "requiredEnv": ["API_TOKEN"],
  "notes": ".claude/cloud-notes.md"
}
```

| 场 | 要求 | 意义 |
| --- | --- | --- |
| `version` | 是 | 要运行的包的确切版本（没有范围）。如果 `setup` 运行一个不同的程序，它用这个程序重新启动。 |
| `aptRepos` | 否 | 添加APT存储库的安装脚本的HTTPS url；每个都被下载并通过管道连接 `bash` 安装软件包前。 |
| `apt` | 否 | 要安装的Debian软件包。名称被验证并作为参数传递，而不是传递给shell。 |
| `domains` | 否 | 环境必须允许额外的主机； `doctor` 探查它们，手册列出它们。 |
| `docker.pull` | 否 | `"auto"` （默认）从撰写文件和 `FROM` 用 `@sha256`;一个图像名称列表提取这些； `false` 让Docker独自一人 `setup`. |
| `setup` | 否 | Shell命令运行一次 `setup`，在回购，与固定的工具首先上 `PATH`． 一个失败的命令被记录下来，其余的仍然运行。 |
| `session` | 否 | Shell命令在每个会话开始时运行，在repo中。它们的输出进入stderr（而不是Claude的上下文中），每一个都在2分钟后停止，并且报告一个失败的命令，而其他命令仍在运行。 |
| `requiredEnv` | 否 | 必须设置的环境变量；会议警告丢失的人。 |
| `notes` | 否 | 什么在云中运行，什么不在云中运行：自由文本，或者相对于repo的文本文件的路径（然后使用其内容）。在每次会议开始时打印并显示在手册中。 `prepare` 期望文件 `cloud-ready` 写的技能。 |

工具版本依次从 `.tool-versions`， `mise.toml`， `.nvmrc` 和 `package.json#packageManager`． 默认分支来自 `origin/HEAD`． 已安装好各个工具 下 `/opt/agent-cloud-kit/<tool>-<version>`，因此版本共存，并且是一个环境的仓库 共享文件夹。没有安装程序的工具会产生警告并被跳过。

不精确的Node版本(`22`， `22.1`， `lts/iron`， `lts/*` 或者 `node`)在 `setup` 到最新的匹配版本 `https://nodejs.org/dist/index.json` 安装在 `/opt/agent-cloud-kit/node-<exact version>`． 解析后的版本记录在机器状态中，因此 `session` 打开相同的文件夹 `PATH`.

## 命令

| 命令 | 它是做什么的 |
| --- | --- |
| `agent-cloud-kit setup [--repo <path>]` | 在Claude启动之前以root身份运行。对于home目录下的每个git repo (`/home/user`)用… `.claude/cloud.json` (或只 `<path>`)：安装工具、apt包和镜像，并将自身复制（没有npm，没有网络）到 `/opt/agent-cloud-kit/bin/agent-cloud-kit`，然后运行 `setup` 步骤并记录结果。没有该文件的回购会被通知跳过。它总是退出0：失败会被记录，但不会致命。 |
| `agent-cloud-kit session` | 从 `SessionStart` 钩子，在几秒钟内没有网络（除了完成克隆）。当安装程序未运行、步骤失败或机器已准备好其他配置时发出警告；写 `PATH` 然后，把固定的工具排成一行 `/opt/agent-cloud-kit/bin`,所以 `agent-cloud-kit` （它本身决定） `$CLAUDE_ENV_FILE`;码头工人开始;获取完整历史记录和 `origin/<default branch>`;运行 `session` 步骤。它不会在会话启动时失败。 |
| `agent-cloud-kit docker` | 开始 `dockerd` 断开连接，等待60秒等待应答。如果不存在，则立即退出1 `dockerd` 未安装。 |
| `agent-cloud-kit doctor` | 检查代理是否允许所需的主机通过，固定的工具是否安装，Docker是否应答，以及记录的状态（指纹和每个步骤）。如果任何检查失败，则退出1。 |
| `agent-cloud-kit init` | 创建 `.claude/cloud.json` 如果缺少，添加 `SessionStart` 钩, `.claude/settings.json` （保持钩子已经在那里），复制 `cloud-ready` 技能 `.agents/skills/cloud-ready` 当它的版本不同时，链接到 `.claude/skills/cloud-ready`． 再次安全运行。 |
| `agent-cloud-kit manual` | 写 `docs/agent-cloud.md` 从 `.claude/cloud.json`，确定性：确切的设置脚本(`agent-cloud-kit@<major>`（或发布候选版本的确切版本）、域、变量名、如何验证环境。 |
| `agent-cloud-kit prepare [--pr|--here|--resume]` | 仅本地，需要一个交互式终端：在没有提交的情况下为云、新PR或当前分支设置回购（当没有给出选项时询问；参见“流程”）。 `--resume` 继续在现有的工作树中。 |
| `agent-cloud-kit verify` | 仅本地，需要一个交互式终端：启动运行的云会话 `cloud-ready verify` 在当前的分支上，必须准备好并推动。 |

环境变量: `AGENT_CLOUD_KIT_DIR` 覆盖 `/opt/agent-cloud-kit` 和 `AGENT_CLOUD_KIT_HOME` 覆盖 `/home/user`;两者都主要用于测试。

### 这个 `SessionStart` 钩

`init` 加上这个钩子。在云会话之外，它什么也不做，它调用 包, `setup` 留在保存的机器上，所以它不需要网络，也不需要 `node_modules`：

```json
{
  "type": "command",
  "command": "[ \"$CLAUDE_CODE_REMOTE\" = true ] || exit 0; /opt/agent-cloud-kit/bin/agent-cloud-kit session || echo 'agent-cloud-kit: el setup del entorno no corrió; revisa con npx agent-cloud-kit doctor'",
  "timeout": 600
}
```

当repo锁定另一个版本而不是正在运行的版本并安装该版本时， `session` 交给它吧。

### 机器指纹

`setup` 存储配置、固定版本、图像和包的指纹 的版本。如果之后回购发生变化， `session` 警告“la máquina se preparó con” 其它configuracion”。保存下来的机器由克劳德重建。大约每7天，或者当你 编辑setup script字段。

## 代理CA和 `docker build`

云代理取代了TLS，所以 `docker build` 不相信它。 `session` 查找CA包 （`SSL_CERT_FILE`,然后 `NODE_EXTRA_CA_CERTS`,然后 `/root/.ccr/ca-bundle.crt`)，并输出其 路径为 `CLOUD_PROXY_CA`． 将其作为秘密传递给构建，仅当它被设置时：

```bash
docker build ${CLOUD_PROXY_CA:+--secret id=proxy_ca,src="$CLOUD_PROXY_CA"} -t app .
```

```dockerfile
RUN --mount=type=secret,id=proxy_ca \
    if [ -f /run/secrets/proxy_ca ]; then \
      export SSL_CERT_FILE=/run/secrets/proxy_ca NODE_EXTRA_CA_CERTS=/run/secrets/proxy_ca; \
    fi; \
    npm ci
```

## 它做不到的事

-   它并没有消除平台的限制：没有开放的端口或预览 `gh pr` 和 `gh issue` GitHub的GraphQL被阻止；使用 `gh api`）。 `gh pr ready` 失败;403年 为它命名一个REST路由(`POST /repos/{owner}/{repo}/pulls/{n}/ccr/ready_for_review`),而不是 然而,验证。
-   它不配置claude。对你来说：环境是你自己设置的，按照手册。
-   它不会从云端下载技能；他们住在仓库里。
-   它没有强加一种测试方法。
-   它不安装插件，或运行插件的挂钩，从您的机器。
-   它不安装来自GitHub版本的工具；代理阻止他们。
-   它不会在Docker内部运行Docker，也不会在本地会话中启动Docker守护进程 (钩子退出时 `CLAUDE_CODE_REMOTE` 不是 `true`）。
-   它不能保证秘密的安全：云环境的环境变量是可读的 任何使用它的人。
-   它不运行你的 `setup` 会议复会的步骤；只有新的会话才有。
-   `setup` 以root身份运行从NPM获取的代码。版本是固定在回购和重新启动 就用那个版本。

## 释放

维护人员。新闻稿由 `.github/workflows/publish.yml` 什么时候发布GitHub 发表;如果发布标签没有它的前导，工作流就会失败 `v`，不同于 `version` 在 `package.json`.

新包的第一次发布不能使用npm可信发布，因为可信发布 在已经存在的包上配置。手工出版第一版：

1.  要么跑 `npm ci && npm run build && npm publish --provenance=false` 从一台登录的机器上 至新公园(`npm login`)，并有出版的权利 `agent-cloud-kit` 包（来源）需要一个CI，并且 `package.json` 请求它)，或者使用 `NPM_TOKEN` 秘密 （`NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` 在发布步骤中)。
2.  在npmjs.com上，打开包设置并添加一个可信的发布者：这个GitHub存储库和 这个 `publish.yml` 工作流。
3.  删除 `NPM_TOKEN` 如果你创造了一个秘密。从那以后，磕磕碰碰 `version` 在 `package.json`、更新 `CHANGELOG.md`，并发布一个GitHub版本，标记为 `v<version>`。带有预发布后缀（）的版本`1.0.0-rc.1`)已在 `next` 标记一个稳定的版本 `latest`;在那之前它也变成 `latest`，所以工具可以阅读 `latest` （代理厨房）看。将其GitHub版本标记为预发布。

## 许可证

麻省理工学院

## 常见问题

### agent-cloud-kit 是什么？

零依赖CLI，准备Claude Code云会话。

### 如何安装 agent-cloud-kit？

在项目目录运行 npm install agent-cloud-kit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agent-cloud-kit，可以用 npx agent-cloud-kit 直接运行。

### agent-cloud-kit 支持 TypeScript 吗？

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

### agent-cloud-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### agent-cloud-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### agent-cloud-kit 可以商用吗？

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

### agent-cloud-kit 还在维护吗？

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