# @ai-development-environment/control-agent 中文文档

规范地址：https://npmcn.com/package/%40ai-development-environment/control-agent/

版本：0\.0\.145
npm 元数据更新时间：2026-11-06T18:14:04.509Z
中文译文更新时间：2026-11-06T07:29:30.645Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-development-environment/control-agent
原文对照：https://npmcn.com/package/%40ai-development-environment/control-agent/?lang=original
项目主页：https://github.com/bludesign/ai-development-environment#readme
源码仓库：https://github.com/bludesign/ai-development-environment

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

- 包体积（解压后）：2.5 MB，3 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.16\.0 \<25
- 运行依赖：4 个
- 首次发布：2026-07-18T23:27:53.462Z
- 最新版本发布：2026-11-06T18:14:04.045Z
- 近 30 天下载量：4154（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：117（近 12 个月 117 个）

## 中文简介

AI开发环境控制剂

## 安装

```sh
npm install @ai-development-environment/control-agent
```

也可以使用：`pnpm add @ai-development-environment/control-agent`、`yarn add @ai-development-environment/control-agent`、`bun add @ai-development-environment/control-agent`

## README

# @ai-development-environment/ control-agent(开发-环境/控制代理)

控制剂 [AI 发展环境](https://github.com/bludesign/ai-development-environment)它使经认证的HTTP和GraphQL WebSocket连接到控制平面;管理中的机器不会暴露一个监听端口.

## 安装

```bash
npm install -g @ai-development-environment/control-agent
```

要求节点24(`>=24.16.0 <25`) (中文(简体) ). 已保存的命令使用代理用户的登录外壳,不需要额外的运行时间.

## 使用量

打开服务器 **探员** 页面并创建一次性的入学命令,然后在目标机上运行(在省略时服务器默认为同一计算机):

```bash
control-agent enroll \
  --server http://127.0.0.1:3090 \
  --enrollment-token <one-time-token>
control-agent run
```

### 本地和远程终点

一个控制平面经常可以在两个地址被到达——一个在办公桌的局域网地址和一个在其他地方的公共或VPN地址. 配置两者,代理更喜欢本地的一款,当本地地址停止接听,而远程地址被确认为接听时,移动到远程一款. 控制飞机坠落 _每个_ 已配置的地址不是故障: 代理机会话和运行在其下的工作, 并在服务器返回时重新连接 .

```bash
control-agent enroll \
  --server http://192.168.1.10:3090 \
  --remote-server https://control.example.com \
  --enrollment-token <one-time-token>
```

更改已注册代理的地址, 或不通过标记来打印当前地址 :

```bash
control-agent endpoints
control-agent endpoints --remote-server https://control.example.com
control-agent endpoints --clear-remote
```

每个端点的websocket地址均取自其服务器 URL,除非 `--websocket-server` 或者说 `--remote-websocket-server` 明确设置.

更改一个服务器地址会重新定义它的websocket地址,因为一个存储在旧服务器上的地址不再指向任何有用的地方. 如果从别的地方提供网锁 `/graphql` 在同一主机和端口上——在反向代理后,如出一辙——与新的服务器地址一起通过:

```bash
control-agent endpoints --server http://192.168.1.20:3090 --websocket-server ws://192.168.1.20:3092/graphql
```

### 注册

```bash
control-agent enrollment
control-agent unenroll
```

`enrollment` 报告此机器是否注册,以及是否每个配置的端点答案. `unenroll` 删除本地证书;控制平面仍然列出代理,直到在那里被删除.

诊断:

```bash
control-agent status
control-agent doctor
```

## 打开代码 2

OpenCode 集成要求 OpenCode `>=2.1.1 <3`。该剂使用 `@opencode/client` 2.1.1; Docker图像包括: `@opencode/cli` 2.1.1. 运输. 在运行控制代理的每台机器上安装 CLI :

```bash
npm install -g @opencode/cli@2.1.1
# Or, on macOS:
brew install anomalyco/tap/opencode-v2
opencode --version
```

打开代码 1's `opencode-ai` 软件包和前一个 `@opencode-ai/sdk/v2` 切入点 不提供这种整合。 删除套件管理的 OpenCode 1 安装 在安装 OpenCode 2 之前,因为两者都显示 `opencode` 命令。 设定 `CONTROL_AGENT_OPENCODE_EXECUTABLE` 当代理服务器时, 返回完整可执行路径 应使用特定装置。 无效的覆盖明显失败 .

使用 OpenCode 连接提供者 `/connect` 接口或 `opencode auth login`。 。 。 . 每个已注册的工作树的模型、证书和变体都得到解决. 代理商开始与私人状态进行回路验证服务 它的配置目录。 使用控制飞机的运行 MCP 工具接收其 自己的服务和连接头。 代理机不启动或停止用户的 共享 OpenCode 服务 .

支持现有配置和 `.opencode/skills` 文件可以保留在 地点 本地 v2 MCP 配置组连接 `mcp.servers`。 。 。 . OpenCode 1 插件执行需要移植到新的插件 API; 终端首选项迁移到全球 `cli.json`审查官员 [移徙指南](https://opencode.ai/v2/docs/migrate-v1/) 财务报告和审定财务报表 [MCP 配置](https://opencode.ai/v2/docs/mcp-servers/)。 。 。 .

在 OpenCode 本地历史迁移待决时进行历史同步重试 报告迁移出错,而不替换已保存的记录。 完全本地形式 支持键入字段、默认值、有条件可见度、验证、外部步骤 承认和取消。 一个被拒绝的本地答案仍然可以编辑 .

在升级代理之前部署服务器及其添加剂数据库迁移. 现有问答保留其原始代表性 字段与它并存.

从寄存器根中校验整合:

```bash
npm run agent:test:run
npm run test:opencode-v2
```

本土烟雾测试需要CLI. 它使用临时 XDG 目录和 a 确定本地模式终点,然后关闭其自有服务并删除 临时数据.

证书和稳定剂 ID储存在 `~/.config/control-agent/config.json`。 。 。 .

## 另见

-   [`@ai-development-environment/server`](https://www.npmjs.com/package/@ai-development-environment/server) -控制飞机服务器.
-   这个 [土生土长水龙头](https://github.com/bludesign/homebrew-ai-development-environment) —— 将代理设备运行为 `brew services` 守护进程 .

## 常见问题

### @ai-development-environment/control-agent 是什么？

AI开发环境控制剂

### 如何安装 @ai-development-environment/control-agent？

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

### @ai-development-environment/control-agent 支持 TypeScript 吗？

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

### @ai-development-environment/control-agent 支持 ESM 还是 CommonJS？

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

### @ai-development-environment/control-agent 需要什么版本的 Node\.js？

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

### @ai-development-environment/control-agent 可以商用吗？

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

### @ai-development-environment/control-agent 的下载量有多少？

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

### @ai-development-environment/control-agent 还在维护吗？

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