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

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

体系结构

 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 显示目录审查日期，并且从不将此脱机检查显示为实时扫描。

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 一代；保留并传递给每次后续的租赁操作。不读取当前持有者并采用别人的作为给你的那一代的替代品。

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:

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.

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

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。该命令不具有范围租约而等待。它要求相同的本地工作树对代理和不会放松锁争用或声明冲突的不重试规则。

检查现状和事故

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. 其首页必须标识发件人、收件人、范围和确认 locks_released: true. 在交接文本中保留秘密：共享结帐不是秘密存储。

---
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`

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/ 目的地不再被接受。

接管和运营商恢复

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，然后显式恢复：

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 -参见许可证.

版本	发布日期	距今
`0.3.1`latest	2026/11/03	今天
`0.3.0`	2026/10/29	5 天前
`0.2.0`	2026/10/27	7 天前
`0.1.1`	2026/10/25	8 天前
`0.1.0`	2026/10/25	8 天前
`0.0.0-stage`	2026/10/25	8 天前

@trinoris/agent-cli

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

体系结构

最佳用途和界限

安装与采用

租赁周期

传递

检查现状和事故

交接通知格式

接管和运营商恢复

配置、限制和兼容性

出口代码和自动化

版本与发布记录

关于 @trinoris/agent-cli 的常见问题

@trinoris/agent-cli 是什么？

如何安装 @trinoris/agent-cli？

@trinoris/agent-cli 支持 TypeScript 吗？

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

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

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

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

@trinoris/agent-cli

@trinoris/agent-cli 用户指南

体系结构

最佳用途和界限

安装与采用

租赁周期

传递

检查现状和事故

交接通知格式

接管和运营商恢复

配置、限制和兼容性

出口代码和自动化

版本与发布记录

关于 @trinoris/agent-cli 的常见问题

@trinoris/agent-cli 是什么？

如何安装 @trinoris/agent-cli？

@trinoris/agent-cli 支持 TypeScript 吗？

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

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

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

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

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