# @trinoris/agent-cli 中文文档

规范地址：https://npmcn.com/package/%40trinoris/agent-cli/

版本：0\.3\.1
npm 元数据更新时间：2026-11-02T16:50:28.373Z
中文译文更新时间：2026-11-02T18:15:22.272Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40trinoris/agent-cli
原文对照：https://npmcn.com/package/%40trinoris/agent-cli/?lang=original
源码仓库：https://github.com/trinoris/multi-agents

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

- 包体积（解压后）：176 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- 首次发布：2026-10-25T13:52:52.614Z
- 最新版本发布：2026-11-02T16:50:28.149Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

多代理协调CLI -范围锁定，切换，旧锁恢复

## 安装

```sh
npm install @trinoris/agent-cli
```

也可以使用：`pnpm add @trinoris/agent-cli`、`yarn add @trinoris/agent-cli`、`bun add @trinoris/agent-cli`

## README

# `@trinoris/agent-cli` 用户指南

`trinoris-agent` 在一个工作树中协调协作编码代理。它储备 已注册的范围，验证移交接收者，并记录接管尝试和结果。 它不验证代理、沙盒编辑器，也不防止直接的非协调写入。

## 体系结构

```text
 Agent session A                 Agent session B
 stable instance + generation    stable instance + generation
          |                               |
          +--------- trinoris-agent ------+
                          |
                     agent-sdk
                          |
        atomic mkdir: .trinoris/.mutation
                          |
          +---------------+---------------+
          |               |               |
    locks/<scope>/   handoff -> active/   incidents/
    holder.json      <instance>/         attempted/completed/failed
    generation       note + receipt      preserved stale state
                          |
                agent-core validation
                package-owned protocol
```

每个突变都使用相同的短文件系统保护，包括Git策略检查和 切换动作。忙碌的守卫返回争夺；代理商必须选择其他工作，而不是旋转。 从来不会因为车龄或PID而被偷。停下来的演员可能会把它留在后面； 显式操作员恢复保留了原因和操作身份。

## 最佳用途和界限

-   协调在同一签出中编辑不同作用域的多个代理。
-   通过指定的交接说明传递经过验证的上下文和后续步骤。
-   在安全接管前检查中断的工作。
-   在加载签出或更改挂载后验证实际的文件系统。

使用孤立的工作树或强制服务来对付敌对行为者、多台机器、 或者严格的写排除。进程可以在检查租约和编辑租约之间暂停； CLI无法保护该编辑。克隆的协调目录不协调克隆。

## 安装与采用

发布的消费者包和存储库构建/测试工具链需要Node.js 22+。 CI验证维护的LTS第22行和第24行；Node.js 18和20不再存在 支持。从源代码开始，在运行CLI之前构建工作区依赖项：

在每个新的代理会话中运行 `trinoris-agent doctor --runtime` 曾经看到过水流 运行时和捆绑咨询状态。CLI还对每个目录执行本地目录查找 启动和阻止普通命令与exit `78` 如果确切的Node.js补丁版本是 以有重要建议而闻名。查找不产生网络请求。目录是 通过审查的CLI版本进行更新，因此旧安装的CLI无法了解最新版本 报告; `doctor` 显示目录审查日期，并且从不将此脱机检查显示为 实时扫描。

```bash
pnpm install --frozen-lockfile --ignore-scripts --ignore-pnpmfile
pnpm build
node packages/cli/dist/bin.js setup --work-dir /path/to/repository
node packages/cli/dist/bin.js verify --work-dir /path/to/repository --trials 5 --concurrency 4
```

要在安装过程中设置非默认租赁策略，请忽略 `--lease-minutes <1..1440>` 和 `--grace-minutes <0..60>`。续订阈值设置为租期的三分之一。

安装程序安装一个完整的包拥有的协议和摘要。它保留了现有的规则 文件,除非 `--force` 是显式的，拒绝链接/特殊文件，并报告替换。 它从不从任意目标存储库复制指令 `specs/` 目录中。 审查生成 `.trinoris/PROTOCOL.md`， `AGENTS.md`，以及座席允许前的技能指针 到工作树中。强制设置拒绝保留锁；停止演员并先解决他们。

`verify --json` 报告 `structureOk`， `configOk`， `protocolOk`， `gitignoreOk`， `atomicityOk`, `ready`. 只有 `ready: true` 通过采用。缺少/分歧的协议独立地阻碍了准备工作 mkdir结果的。沙盒限制是不确定的(`atomicityOk: null`)，不是证据 mkdir是非原子的。在具有工作者权限的同一文件系统上重复此操作。

## 租赁周期

每个有状态命令都需要显式的 `--agent-class` 和 `--instance` 值。重用 会话使用同一对。Acquire返回new **一代**； 保留并传递给 每次后续的租赁操作。不读取当前持有者并采用别人的 作为给你的那一代的替代品。

```bash
trinoris-agent acquire --work-dir /repo --agent-class codex-gpt-6 \
  --instance codex-session-a --scope api --task 'Validate requests' --json

# Copy the generation from the acquisition response.
trinoris-agent check --work-dir /repo --instance codex-session-a \
  --scope api --generation <generation>
trinoris-agent renew --work-dir /repo --instance codex-session-a \
  --scope api --generation <generation>
trinoris-agent release --work-dir /repo --instance codex-session-a \
  --scope api --generation <generation>
```

在每批编辑之前立即检查。一份租约在确切的期满时刻是有效的； 之后检查和续订失败。Grace延迟接管，不授权继续 编辑。Release只能安全地删除过期的租约及其匹配的生成。 在协议3中，单独的标识字符串不会授权检查/更新/释放。

注册令管理收购。 `acquire-many --scopes api,tests --instance SESSION` 按照这个顺序排序，如果有任何范围被争用，就回滚它的新租约。获得一个 低范围持有高范围失败。保守的 `git` 范围涵盖所有Git mutations：对等编辑租约会阻止它，而对等Git租约会阻止新的编辑租约。 实际的Git命令仍然要求代理遵循该协议。

## 传递

在下面写一个协议说明 `.trinoris/handoff/drafts/`，验证它，释放 作者的作用域，然后将其发布到收件人收件箱。已发布的通知使用 它的 `to_class` 字段。收件人可以通过以下方式列出、检查、索赔并完成其备注 CLI:

```bash
trinoris-agent handoff validate --work-dir /repo --note review.md --json
trinoris-agent handoff publish --work-dir /repo --agent-class codex \
  --instance codex-session-a --note review.md --json
trinoris-agent handoff list --work-dir /repo --agent-class claude \
  --instance claude-session-b --json
trinoris-agent handoff show --work-dir /repo --agent-class claude \
  --note review.md --location inbox
trinoris-agent handoff claim --work-dir /repo --agent-class claude \
  --instance claude-session-b --note review.md --json
trinoris-agent handoff show --work-dir /repo --agent-class claude \
  --instance claude-session-b --note review.md --location active
trinoris-agent handoff complete --work-dir /repo --agent-class claude \
  --instance claude-session-b --note review.md --outcome 'Review passed.' --json
trinoris-agent handoff wait --work-dir /repo --agent-class codex \
  --instance codex-session-a --note review.md --timeout-seconds 1800
```

`list` 需要类和实例，所以它可以包括实例的活动笔记。 `show --location active` 仅限于所提供的实例。 `show` 默认为 类的收件箱; `--location universal` 读取明确通用的收件箱。这些操作 不要接受任意路径。

出版和完成在移动文件前写收据。如果中断，请重试 具有相同身份和内容/结果的相同文件名；冲突的内容被拒绝。 收件人必须在完成前索赔。完成将结果记录在存档文件中 注意并添加一个存档索引条目。 `claim --note ...` 作为一种兼容性仍然可用 别名 `handoff claim`.

发布之后，发送方可以显式地等待那个确切的移交生命周期：

```bash
trinoris-agent handoff wait --work-dir /repo --agent-class codex \
  --instance codex-session-a --note review.md --until completed \
  --timeout-seconds 1800 --interval-seconds 2
```

等待是可选择的，是有限制的。的发布收据和内容摘要 相同的文件名和发布身份；它不需要等待任意的注释或推断 从消失中完成。默认的 `--until completed` 返回已归档的 结果。 `--until claimed` 一旦符合条件的收件人认领该通知，将返回。 超时时间为1-86400秒（默认1800），轮询间隔为1-60秒（默认2）， timeout返回退出代码 `3`； ctrl - c的回报 `130`。该命令不具有范围租约 而等待。它要求相同的本地工作树对代理和 不会放松锁争用或声明冲突的不重试规则。

## 检查现状和事故

```bash
trinoris-agent status --work-dir /repo --json
trinoris-agent incidents list --work-dir /repo --json
trinoris-agent incidents list --work-dir /repo --scope api
trinoris-agent handoff list --work-dir /repo --agent-class codex \
  --instance codex-session-a --json
```

`status` 区分已登记的租契州(`free`， `held`， `expired`, `malformed`)，并将未注册的锁目录报告为 `unknown`. `incidents list` 读取 最多200个最新摘要，每个事件上限为16 KiB，最多扫描5000个事件 文件。它不呈现原始错误文本；原因字符串是终端转义的，上限为 256个字符。这些记录是本地协调历史，而不是经过身份验证的审计日志。

使用 `trinoris-agent --help`， `trinoris-agent <command> --help`, `trinoris-agent --version` 获取命令指导和安装包版本。与 `--json`，则在stderr上发出错误 `{ "error": { "code": "cli_error", "message": "..." } }`； 消息是有界的诊断，因此自动化应该根据退出代码而不是 错误文本。

### 交接通知格式

使用中记录的协议3结构 [`specs/03-handoff-format.md`](https://npmcn.com/package/specs/03-handoff-format.md). 其首页必须标识发件人、收件人、范围和确认 `locks_released: true`. 在交接文本中保留秘密：共享结帐不是秘密存储。

```markdown
---
from_class: claude-opus-5
from_instance: claude-session-b
to_class: codex-gpt-6
to_instance: any
scopes: [api, tests]
locks_released: true
---

# Context Handoff

Updated: 2026-10-25 10:00 UTC
Task: Validate requests
Status: ready-for-review
Branch: main
Base commit: abc1234

## Goal

Requests need stricter validation.

## User Constraints

Keep the public schema compatible.

## Current State

Boundary checks remain.

## Changes

No changes yet.

## Decisions

No decisions.

## Verification

| Check | Result | Scope / limitations |
| --- | --- | --- |
| Existing route tests | PASS | Does not cover new boundary checks |

## Failed Attempts

Nothing.

## Blockers and Unknowns

Nothing.

## Next Actions

1. Add the boundary checks.

## Resume Instructions

1. Read the request route and its tests.

## References

- `specs/03-handoff-format.md`
```

```bash
trinoris-agent claim --work-dir /repo --agent-class codex-gpt-6 \
  --instance codex-session-a --note validate-requests.md --json
```

SDK验证接收者类/实例、主体状态、模式、注册范围等 范围的可用性。 `any` 仅在显式时支持，并且 `locks_released` 必须 真实的。重复或未知的标题，格式错误的时间戳，不支持的状态值， 不完整的部分无法验证。填妥的便条不能认领。要求做 未获得编辑作用域；在写作前分别获取这些信息。

目的地是 `active/<instance>/<filename>`。保留现有的活动内容 在冲突。摘要/请求人收据标识相同的重试并允许恢复 一个被打断的匹配移动。 `--from` 接受一个逻辑类inbox； `--to` 必须等于 索赔人的实例目录。不受限制的文件系统路径和共享 `active/` 目的地不再被接受。

## 接管和运营商恢复

```bash
trinoris-agent break --work-dir /repo --agent-class claude-opus-5 \
  --instance recovery-session --scope api --reason 'Prior actor confirmed stopped' --json
trinoris-agent diagnose --work-dir /repo --json
```

break需要过期加宽限期（或比宽限期更早的畸形目录）。它 序列化所有其他突变，保留陈旧状态，并返回新一代。 结构化事件 `attempted`， `completed`，或者 `failed`； 仅仅是一次尝试 没有成功收购的证据。收购暴露了最近的范围事件。 检查这些事件， `git status`，并在编辑中断工作之前进行相关测试。 原因是断言，而不是旧进程停止的证明。本地记录仍然可写 使用相同的文件系统原则；它们不是独立认证的审计证据。

如果进程崩溃并出现标记，请停止 **所有受影响的演员**，检查标记和 操作ID，然后显式恢复：

```bash
trinoris-agent recover --work-dir /repo --instance operator-session \
  --marker .mutation --operation <exact-operation-id> \
  --reason 'All affected actors stopped; retained state inspected' --confirm-stopped
```

对于不完整/损坏的标记， `diagnose` 报告丢失或无效的元数据；使用 `--operation unknown` 只有在同样的离线检查之后。剩下的恢复 `locks/<scope>.breaking` 和 `claims/<digest>.claim` 分别标记。恢复不 修改后的操作ID。一个废弃的 `.recovery` 标记需要离线操作人员检查 每个演员都停下来；它永远不会自动回收。

## 配置、限制和兼容性

规范配置是 `.trinoris/config.json`； 命令行和SDK只从 选择 `.trinoris/` 根。安装程序不创建外部配置镜像。它增加了 `/.trinoris/` 到目标存储库的 `.gitignore`，则局部协调状态为 提交。包所有的合同在 `.trinoris/PROTOCOL.md`； 生成的 `AGENTS.md` 克劳德的技能说明指向那里。自定义SDK根不继承 来自不相关父节点的配置。没有安装配置的SDK调用程序 使用内置的注册表；命令行需要安装配置。

租期：1-1440分钟。格蕾丝：0-60分钟。标识符：最多96个字符； 文件名：最多160个。记录/配置：最多64kib；备注：最多256 kb。 验证器：1-100次试验，2-32个工人，最多1024个工人启动，60秒 整体的最后期限。工人在等待时屈服，并在超时/中止时终止。

在协议3中不支持心跳和守护进程操作； `heartbeat.enabled` 必须 仍然错误。议定书1记录可在期满/宽限期后被检查和安全接管； 但是无代记录从不授权检查、更新或释放。停止所有旧的代理 但是无代记录从不授权检查、更新或释放。停止所有旧的代理 在升级之前。协议2使用了顶层 `coordination/` 路径;协议3使用 `.trinoris/`。停止所有参与者后，将旧目录移到外部的脱机备份中 工作树。审查并有选择地保存交接/存档/事件历史记录；不 恢复活动锁或突变标记。运行 `setup` 创造一种新鲜 `.trinoris/`、检查 它生成指令，然后运行 `verify` 在启动之前，只有协议3客户端。不 同时运行协议2和3客户端。

## 出口代码和自动化

| 退出 | 意义 | 调用者行动 |
| --- | --- | --- |
| 0 | 成功 | 保留退回的收据；继续在其范围内 |
| 1 | 无效输入、不完全准备、冲突或不确定I/O | 检查和纠正；不要想当然地认为会成功 |
| 3 | 争用或有界切换-等待超时 | 论争，挑其他作品；永远不会旋转。超时时，在决定做什么之前检查切换状态 |
| 130 | 切换等待被Ctrl-C打断 | 稍后恢复或检查交接 |
| 4 | 租约遗失或无法确认 | 停止编辑并安全地重新获取 |
| 78 | 确切的Node.js运行时匹配已知的关键警告 | 运行 `trinoris-agent doctor --runtime`，升级到列表中的固定版本，并重新启动CLI |

`--json` 给出结构化标准输出。错误使用有界转义标准错误。不让…知道秘密 所有任务/原因/备注字段。运行时测试和发布门与包代码一起存在。 安装的 `.trinoris/PROTOCOL.md` 是独立的;采用者不需要存储库规范。

Apache-2.0 -参见 [许可证](https://npmcn.com/package/%40trinoris/agent-cli/LICENSE).

## 常见问题

### @trinoris/agent-cli 是什么？

多代理协调CLI -范围锁定，切换，旧锁恢复

### 如何安装 @trinoris/agent-cli？

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

### @trinoris/agent-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @trinoris/agent-cli 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @trinoris/agent-cli 需要什么版本的 Node\.js？

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

### @trinoris/agent-cli 可以商用吗？

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

### @trinoris/agent-cli 还在维护吗？

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