# @cueloop/adapters 中文文档

规范地址：https://npmcn.com/package/%40cueloop/adapters/

版本：0\.1\.0-alpha\.115
npm 元数据更新时间：2026-11-03T09:52:20.886Z
中文译文更新时间：2026-11-11T06:19:29.356Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：355 kB，64 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2026-08-07T19:01:01.912Z
- 最新版本发布：2026-11-03T09:52:20.497Z
- 近 30 天下载量：3005（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：112（近 12 个月 112 个）

## 中文简介

编码代理的 Cueloop 适配器: Claude Code, pi, 和 Codex

## 安装

```sh
npm install @cueloop/adapters
```

也可以使用：`pnpm add @cueloop/adapters`、`yarn add @cueloop/adapters`、`bun add @cueloop/adapters`

## README

# 调适器

Cuelop拥有线条并审查生命周期. Claude Code, Codex, 和 pi 只使用代码 连接他们的会话生命周期和本地信息.

```text
Harness lifecycle event
        |
        v
Harness adapter
  - identify and bind the harness session
  - submit or revise the artifact
  - open cueloop threads
  - subscribe for Messages
  - send Messages through the harness
        |
        v
Shared cueloop Thread + UX core
  - canonical Thread state
  - review lifecycle
  - Message routing and durable delivery
        |
        v
Existing cueloop TUI
  - thread panel: plan, reply, prototype
  - changes panel: diff, review
```

## 主计长合同

`createHarnessThreadController().openWorkflow` 为所有六人的切入点 工作流程。 计划、答复和原型将Markdown提交线面板。 抖动 向更改面板提交工作树补丁 。 审查进口的公关信息, 打开更改面板,并将其信件放入伪造中。 精细分析 在提交代理起草的提案之前的线索作为计划线索. 审查和完善是工作流程,不是新的文物类型.

守护进程单独拥有线索状态,修订,说明,信件,装订, 和交货。 适应者不得坚持第二个审查模式,分析自己的 复制一件文物,或制作专门审查装置的UI。 一个新的适配器 执行会话身份、生命周期截取、线索提交 控制器、本地信件注入和重新装入调节。 用这个 相同的 TUI, 控制器合同测试, 和重复信件ID 抑制. Claude Code 使用所需的 Mod API, Codex 使用插件钩和 MCP,和pi使用它的扩展API.

## 线索表面

地表端口打开内置面板. 终端和多轮发射 执行属于它们的一体化.

`createTerminalThreadSurfacePort` 在幽灵里筑巢时选择赫德 否则会在macOS上使用Ghostty. 接受个人配置 `[integrations.herdr] thread_surface = "tab" | "pane" | "none"`; 标签是 默认。 幽灵接受 `[integrations.ghostty] thread_surface = "tab" | "pane" | "window" | "none"`,也默认为分页。 仓库配置无法触发 终端自动化. 右侧有一个宽度为50%的窗帘。 土著 手柄活在守护进程适配器抓取中,而不是在线索中。 如果打开失败, 控制器离开线索等待 返回时 `Open cueloop threads: cueloop <thread-id>` 带上绳子.

## 信件发送

守护进程在线条外继续捆绑和交付。 它的路径 a 向提交方发送的默认装订信件并重试未确认的 重新启动后发送。 一旦确认经批准的信件 计划可以一次不变地通过共享控制器。 适配器发送 信息通过它的配置 API,以信件 ID 来复制 `createDeliveredMessageStore`,然后确认交货。 原生注射剂 当被控制器支持时,将消息ID作为一等钥匙使用. 福尔吉 后退还需要信件ID日记. 外部侧面相撞 效果和记录ID可以重复;交付本身至少是一次. 同样的线索可以在以后将信件引导到另一个绑定的绑带上,而无需 改变TUI.

## 线程代理牵引原型

Fx 牵引适配器(`src/fx/harness.ts`)将ACP翻译为"计划" `AgentHarnessAdapter` 合同。 CLI 提供给守护进程;守护进程从未导入此包. 提供方会话标识与适配方标识保持一致. 见 [原型说明](https://npmcn.com/package/examples/fx-thread) (b) 选择适用开发 [生命周期实验](https://npmcn.com/package/examples/agent-lifecycle) 检查的回收法。 Harness-addated 模型/合理选择和cueloop工具调用通过同一合同;JSON工具参数在守护进程边界被解析. [提交法](https://npmcn.com/package/examples/agent-submission) 检查队列、 不可改变的接受输入和重试行为.

### 线索代理诊断路径

适配器弹出 `AgentHarnessEvent`。 。 。 . `routeHarnessOutput` 发送诊断 通知私有边框日志 `<cueloop-home>/thread-agents/<encoded-thread-id>.diagnostics.ndjson`外边 线索历史和后期的模型上下文. 未知的诊断断裂 完好无损 咨询通知,包括严重性通知 `error`,不确定 转弯结果; 迅速的结果和运输失败仍然存在.

Fx 适配器发布 ACP v1 会话通知并处理结构化 `notice` 更新。 在观察了结构化通知后,它保留了助手块 没有文本匹配的连接。 检查的fx 0.012运输确实 不提供通知来源. `FxLegacyStartupMessages` 是一个孤立的倒计时 在已知的完整起动线上,最多有128个履带式身份证,每条32个KiB等待通知。 从来没有分类 整个信件 ID: 同一ID 下的 HTTP 后期错误仍然可见。 已更改 或未完成的通知措词得到保留。 一个确切的助理引文 遗留通知仍然可能被错误分类;上游结构来源 必须消除这种模糊性.

Pi 消费者可以导入 `parsePiHarnessOutput` 从 `@cueloop/adapters/pi/harness-output` 在他们的RPC或SDK边界。 它能验证 框,保留没有前缀匹配的助手文本,分离通知和 扩展错误,并区分取消、失败、活性,以及 `agent_settled`。呼叫者指定消息身份,跟踪整个消息转换结果 重复;既未迅速确认,也未 `agent_end` 表示转弯定了. 这提供了输出常态接合,而不是一个新的 pi 子进程控制器.

### 业主主持的持久对话

新线程代理使用Pi持久适配器. 每个线索都有一个哈妮丝 对话 `<cueloop-home>/pi-conversations/<session-id>`模型, 证书、耐用存储和执行Env是单独的主机依赖. 供应的环境运行在拥有的机器上;它不是一个沙盒. 现有的fx对话保留了它们的适配器和会话身份. 设定 `CUELOOP_AGENT_HARNESS=fx` 为新对话选择 fx .

皮适配器读主人的 `~/.pi/agent/auth.json` 全权证书及全权证书审查报告 提供商支持的环境证书。 继续刷新 cueloop的私人电话 `model-credentials.json`,使输入源保持不变. 证书从不包含在共享blobs或中继框中. 供应商登录仍然是一项当地业务.

与 `[experimental] herdr_acp = true` 和用户安装 `hc` 0.1.15或更新,fx ACP进程在草核终端内启动. 守护进程通过一个私人的中继插座来说出ACP,所以守护进程重启可以重新接上一个飞行中提示并让它完成. 国旗默认关闭. 失踪或以上 `hc` 保持ACP进程作为守护进程的孩子。 cueloop 不安装或更新 `hc`设置 `CUELOOP_HERDR_ACP=0` 保持孩子的过程 即使国旗上。 何时 `HC_SESSION` 设置, cueloop 使用草药会话。 否则它使用会话名称 `cueloop`,因此代理终端不参加默认会话。 删除线索会关闭中继器 。 在没有客户端附加的情况下,一个完成的继电器在60秒后退出(`HERDR_ACP_IDLE_MS`飞行中提示时间为10分钟(`HERDR_ACP_ABANDON_MS`)所以一个重新启动的守护进程可以重接. 完成 `hc` 终端被移除。 中继记录是模式 `0600`。 。 。 .

与 `[experimental] thread_agent = true`,共享向导提议 **允许代理 信件**,默认关闭。 允许合作者使用所有者的对话 和模型账户。 缩写+ 输入提交代理输入; 选项+ 输入保存注释 可内置和编辑。 一个被禁用的链接仍然支持普通的评论线索.

网关在显示其队列前坚持输入, 并将请求保存到 车主守护进程确认有连续的操作收据。 如果车主是 断开, 文物仍可读取, 线索显示 **所有者离线**。 。 。 . 认证的所有者连接收到请求 `cueloop-agent` 嘘, 将它们的注释合并到本地线索中, 溪流代理状态恢复 . 重新连接再利用操作ID;改变后的有效载荷不能再利用一个被接受的ID. 该网关没有运行模型或工作空间工具. 主办其他地方的处决 需要提供存储器,模型 和一个孤立的 EmpireEnv 在主机上.

## 常见问题

### @cueloop/adapters 是什么？

编码代理的 Cueloop 适配器: Claude Code, pi, 和 Codex

### 如何安装 @cueloop/adapters？

在项目目录运行 npm install @cueloop/adapters，或使用 pnpm add / yarn add / bun add。

### @cueloop/adapters 支持 TypeScript 吗？

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

### @cueloop/adapters 支持 ESM 还是 CommonJS？

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

### @cueloop/adapters 需要什么版本的 Node\.js？

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

### @cueloop/adapters 可以商用吗？

@cueloop/adapters 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cueloop/adapters 的下载量有多少？

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

### @cueloop/adapters 还在维护吗？

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