# agents-relay 中文文档 规范地址：https://npmcn.com/package/agents-relay/ 版本：2\.0\.202 npm 元数据更新时间：2026-11-03T00:58:25.445Z 中文译文更新时间：2026-11-03T03:12:12.464Z 软件包许可：未声明 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/agents-relay 原文对照：https://npmcn.com/package/agents-relay/?lang=original 项目主页：https://github.com/lalalic/agents-relay#readme 源码仓库：https://github.com/lalalic/agents-relay ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.6 MB，232 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：1 个 - 首次发布：2026-09-19T22:54:29.129Z - 最新版本发布：2026-11-03T00:58:25.071Z - 已发布版本数：381（近 12 个月 381 个） ## 中文简介 通过GitHub拉取请求协调的持久异步代理作业 ## 安装 ```sh npm install agents-relay ``` 也可以使用：`pnpm add agents-relay`、`yarn add agents-relay`、`bun add agents-relay` ## README # 代理继电器 Agents Relay是一个TypeScript运行时，用于由SQLite和规范工作流图驱动的持久异步代理作业。EventBus唤醒和解；EventBus消息或GitHub PR评论永远不是生命周期权威。作业、计划、任务、回顾、执行、租约和恢复状态在SQLite中守护进程重启后仍然有效。 V2使用只读的本地SQLite Job Registry进行发现。不可变的jobId即使在prNumber为0时也选择Job Store；生命周期转换是跨流程的原子性转换。GitHub是 **audit-only**它的PR/head/publish事件被持久化用于报告，而不会被用于启动、停止或完成本地工作流。本地Git交付及其确认的合并收据—而不是远程PR合并事实门图完成。作业创建和本地任务操作不需要GitHub身份验证或PR。 规范的V2体系结构契约是 [DESIGN-PRINCIPLES.md](https://npmcn.com/package/agents-relay/DESIGN-PRINCIPLES.md)． 下面的README部分描述了 运行时;他们没有替换合同。 有关权威性任务解除阻止、解决方案所有权、计划器拒绝反馈和故障恢复，请参见 [解除阻塞和解决工作流程](https://npmcn.com/package/agents-relay/docs/unblock-resolution-workflow.md) 以其 [美人鱼图](https://npmcn.com/package/agents-relay/docs/diagrams/unblock-resolution-end-to-end.mmd). ## V2架构 “‘美人鱼 流程图LR Human\[Human / orchestrator\]—> CLI\[CLI / Dashboard\] 命令行—> Store\[（SQLite / WAL . xml） 工作任务计划检讨真相)\] Worker\[Workers / adapter\]——> Events\[EventBus . net Wake +观测\] Events—> Coordinator\[reconcilcoordinator\] Store——>协调器 协调器—> Graphs\[Canonical Mermaid Graph Engine\] 图表—> Effects\[无状态动作/效果\] 效果——>存储 Store—> Views\[Dashboard / Recovery\] 效果—> Outbox\[持久的外部动作发件箱\] Outbox—> GH\[GitHub提交/ PR /审查/合并API\] GH—> Facts\[已确认的外部事实\] 事实——>商店 ' ' ' SQLite拥有唯一的生命周期权限；图形引擎选择每个转换。 GitHub操作由适配器显式请求和确认，从未使用过 发现或重建作业/任务状态。EventBus交付唤醒和解； 它不能代替持久的SQLite记录。 ### 工作流图导航 | 区域 | 规范的图 | | --- | --- | | 工作周期 | [`workflow/job-lifecycle.mmd`](https://npmcn.com/package/agents-relay/workflow/job-lifecycle.mmd) | | 任务生命周期 | [`workflow/task-lifecycle.mmd`](https://npmcn.com/package/agents-relay/workflow/task-lifecycle.mmd) | | 回顾生命周期 | [`workflow/review-lifecycle.mmd`](https://npmcn.com/package/agents-relay/workflow/review-lifecycle.mmd) | | 规划师触发 | [`workflow/planner-trigger.mmd`](https://npmcn.com/package/agents-relay/workflow/planner-trigger.mmd) | | 计划编制 | [`workflow/planner-orchestration.mmd`](https://npmcn.com/package/agents-relay/workflow/planner-orchestration.mmd) | | 拦截器分辨率 | [`workflow/blocker-resolution.mmd`](https://npmcn.com/package/agents-relay/workflow/blocker-resolution.mmd) | | 权威的疏通 | [`workflow/authoritative-unblock.mmd`](https://npmcn.com/package/agents-relay/workflow/authoritative-unblock.mmd) | | 排忧解难 | [`workflow/troubleshooter.mmd`](https://npmcn.com/package/agents-relay/workflow/troubleshooter.mmd) | | 升级 | [`workflow/escalation.mmd`](https://npmcn.com/package/agents-relay/workflow/escalation.mmd) | | 相关任务操作策略 | [`workflow/task-related-action.mmd`](https://npmcn.com/package/agents-relay/workflow/task-related-action.mmd) | 这些路径总是表示当前规范图。历史图形定义可以通过Git的历史记录、标记和提交获得，而不是通过并行的版本文件 `workflow/`． 看到 [`docs/workflow-engine.md`](https://npmcn.com/package/agents-relay/docs/workflow-engine.md) 用于可执行概要文件和运行时边界。 ### 结构化运行时可观察性 `src/observability.ts` 是记录生命周期或投影决策发生的原因的单一结构化日志/事件边界。一个相关的记录链(`wake -> graph -> transition -> store commit -> projection outcome`)允许操作符重构具有代表性的任务生命周期，而无需特别的标准错误解析。记录只是观察性的，从来没有第二个持久存储；它们通过存储库/PR/作业/任务/执行相互关联，将失败分类为确定性的 `conflict` vs `transient` 重试vs `terminal`，编辑秘密/提示，绑定大型有效负载，并将例程空闲/无操作周期保持在默认水平。看到 [`docs/structured-observability.md`](https://npmcn.com/package/agents-relay/docs/structured-observability.md) 对于唱片合同，字段，噪音政策和编校规则。 ## 快速启动 对于新工作，通过代理中继创建本地Job。使用 `job adopt` 绑定没有GitHub访问的已知遗留PR号；外部GitHub投影在第一次有意义的代码提交后创建一个显示PR。任务是针对SQLite Job进行验证的，而不是针对GitHub标记。 ```sh cat > job.md <<'EOF' # Goal Standalone Job context. Put a Mermaid block first when a workflow/state/architecture diagram helps. EOF npx agents-relay job create --repo OWNER/REPO \ --id job-1 --title "Objective" --objective-file job.md # The orchestrator decides the initial batch separately cat > task.md <<'EOF' # Work Implement this phase using the Job objective as context. EOF npx agents-relay task create --repo OWNER/REPO --id job-1 \ --task-id initial --output task-pr --input-file task.md npx agents-relay task create --repo OWNER/REPO --id job-1 \ --task-id child --output task-pr \ --input "Implement the described child task and publish a terminal event." npx agents-relay reconcile --repo OWNER/REPO --pr 12 --id job-1 npx agents-relay job show --repo OWNER/REPO --pr 12 --id job-1 ``` 任务准备是明确的： `DRAFT` 表示持久任务存在，但还不能执行； `QUEUED` 表示Relay现在可以执行它； `RUNNING` 表示工作线程执行已经开始。开始使用依赖项创建任务 `DRAFT` 并成为 `QUEUED` 当这些依赖成功时。创建的无依赖项任务 `--draft` 一直坚持到 `task update --queue`． 任务运行后，外部等待表示为 `BLOCKED`，永远不会由返回 `DRAFT`. 可变的草稿/排队/可重试的任务字段可以在不替换持久任务标识的情况下进行更改。 `task update` 拒绝 `RUNNING`， `SUCCEEDED`, `CANCELLED` 不能重写活动执行和终端历史记录的任务。例如: ```sh npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child \ --adapter chatgpt --provider chatgpt --model gpt-5.6-sol --reasoning high \ --capabilities model,chatgpt,browser-harness # Explicitly release a held DRAFT task npx agents-relay task update --repo OWNER/REPO --pr 12 --id job-1 --task-id child --queue ``` 作业将持久生命周期与派生的运行时状态分开。持久生命周期是 `DRAFT | ACTIVE | COMPLETED | CANCELLED`：新创建的Job是DRAFT，创建可执行的工作或启动Planner会激活它。运行时状态(`IDLE`， `WAITING`， `QUEUED`， `RUNNING`， `BLOCKED`， `FAILED`， `REVIEWING`， `MERGE_PENDING`， `MERGED`，或者 `CANCELLED`)是从Tasks、Review和本地确认的合并事实中计算出来的，并且永远不会作为生命周期事实被持久化。 生命周期转换授权存在于链接的可直接呈现的规范流程图源中 [工作流图导航](https://npmcn.com/package/agents-relay/#readme-workflow-graph-navigation)． Git历史记录拥有先前的图形版本；工作树只包含当前的图集。 规范的Mermaid图引擎是权威的持久工作流决策路径。作业/任务生命周期转换以及Review、Planner、Blocker/Unblock和Troubleshooter编排分支由规范化工作流图定义，并通过共享图运行时执行。TypeScript提供事实和基本的动作/效果实现；它不能将这些工作流分支复制为第二个过程状态机。 工作目标和任务输入是Markdown。更喜欢 `--objective-file` / `--input-file` (使用 `-` 对于stdin)，用于持久的长格式上下文；内联 `--objective` / `--input` 保留为短/简单文本，并且与文件变体互斥。当一个图表实质性地阐明了工作时，首先是美人鱼，然后是Markdown detail。新创建的Job必须捕获足够的上下文，以便独立于原始聊天完成。它的PR主体只包含一个隐藏的 `agents-relay:job:v1` 元数据标记，然后是目标Markdown；没有单独的求职评论重复求职目标。目标和工作元数据更新重写相同的PR主体。遗留的作业注释标记仍然可读，并在下一个作业保存时迁移到PR主体中。 每一份工作都是目标驱动的。 `job create` 只有持久的工作才会持久 创建可执行任务。调用者可以直接创建工作 `task create` 或显式地调用Planner `plan`． 直接 编排器创建的任务是直接持久化的，而不是包装在 综合计划。 `agents-relay plan` 立即着手零任务的草稿工作， 激活它，坚持真实 `plan-N` 计划轮询，并实现验证 `next_tasks`． 和解不会为未碰过的人发明第一轮 零任务DRAFT Job；一旦工作开始，以后每个Job都会自动创建 计划轮询，直到最新的计划满意为止。 手动规划语法： ```sh npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt "Plan the implementation from the durable objective" npx agents-relay plan --repo OWNER/REPO --pr 12 --id job-1 --prompt-file guidance.md ``` 可选提示符是额外的圆形引导；它不能取代持久的工作目标。新的规划回合使用 `plan-N`;历史 `planner-N` 记录保持可读。 持久状态JSON和仪表板显示计划来源。运行时使用捆绑的 `skills/agents-relay/agents/planner.agent.md` 默认情况下; `--planner-command` 是可选的覆盖 快照作为JSON在stdin上，必须返回 `{ "objective_status": "in_progress"|"satisfied", "assessment": "...", "next_tasks": [...] }`. planner创建的任务使用稳定的id和现有的父/子任务树，因此 重试和重启守护进程不会创建重复的工作。 任务生成器必须遵循 `skills/agents-relay/contracts/task-job-contract.md`;共享的技能契约定义了故事大小、生命周期事件、评审和自动合并语义。 执行路由是代码驱动的：Relay根据权威的运行时/模型/资源事实构建完整的可执行worker+模型路由，将配置文件默认值与用户的显式合并 `[choices]`，对它们进行重复数据删除，仅通过硬门删除不可能的路由，然后调用泛型类型 `decide(request, contract)` 边界只有一次，一个合并的选择列表和 `[routing-instruction]` 逐字转发文本。任务/资源/能力信号和路由指令是软决策事实；决策失败确定地退回到可用的Codex默认路由。看到 [执行路由器和输入的决定](https://npmcn.com/package/agents-relay/docs/worker-model-routers.md). 所有任务生成器使用相同的故事大小契约： `S`≈5分钟, `M`≈15分钟 `L`≈45分钟不活动，与 `M` 作为默认值。 `high` 推理是不活动窗口的两倍。接受 `task.started` 和新 `task.progress` 当前执行的事件将重置它。ChatGPT浏览器Worker启动-ack超时派生为有效非活动超时的三分之一，限制在1到5分钟之间。组织者和策划者应该做出选择 `storySize`，而不是原始超时毫秒； `--timeout` 仅保留为显式兼容性/调试覆盖。 没有作业调度或cron支持。调和从持久状态恢复目标计划，包括在错过唤醒或重新启动之后。看到 [objective-driven工作](https://npmcn.com/package/agents-relay/docs/objective-driven-jobs.md). GitHub投影在有意义的源代码分支提交后创建或重用显示PR； `job adopt` 为现有遗留PR绑定保留。重新运行它是幂等的：它重用PR并只维护一个可信代理-relay:job:v1标记。作业创建总是只创建，并且总是启用自动合并； `--no-auto-merge` 不是。 `job create` 选择。现有作业仍然可以使用 `job update`． 任务执行选项属于 `task create`，编排器可以根据用户意图创建零个、一个或多个初始任务。 要在现有的非托管PR上创建Job，请使用显式的 `job adopt` 兼容性行动: ```sh npx agents-relay job adopt --repo OWNER/REPO --pr 6 --id job-6 --title "Existing objective" ``` 使用 `job update` 对于已运行正常的作业标记/绑定上的部分可变元数据更改： ```sh npx agents-relay job update --repo OWNER/REPO --pr 6 --id job-6 --priority P0 --no-auto-merge ``` 请求一个合格的新审查 `npx agents-relay review request --repo OWNER/REPO --pr NUMBER --id JOB_ID`. 通过可选的 `--thread-id THREAD_ID` 将查看器线程覆盖保存为后续的 检查路由。如果没有它，Relay使用存储的审阅者线程，然后是创建者线程， 或者当两者都不存在时的遗留审查路径。这个请求唤醒图所有的 检查编排;这不是送货收据。 审查目的地是持久的工作事实。 `job create` 和 `job update` 接受 `--reviewer-thread-id` 和 `--creator-thread-id`;审阅者ID优先 超过创建者/起源ID。本地运行时调用可以通过 `--thread-id` 作为一个明确的一次运行审查覆盖。当目的地存在时， final-review路由需要一个ChatGPT/webhelm worker并提交 审核请求作为一个验证 `new-turn` 到具有Job ID的现有线程， PR号，和不变的审核头SHA。失败依然如故 查看任务重试/恢复路径；传输故障永远不会被视为 审查交付。 `job update` 首先验证受信任的作业标记。丢失、畸形、重复、不匹配或冲突的绑定无法进行精确诊断，并且无法隐式修复。编排器根据Job契约显式地处理异常修复，然后重试更新。 `job show` 读一个Job和 `job list` 在存储库中列出被管理的任务。 管理GitHub任务创建/更新/显示/列表/重试/取消和调和/服务命令也需要一个持久的Job标记。编排器不需要原始的GitHub命令来进行正常的作业创建或元数据更新：代理中继在内部使用其经过身份验证的GitHub客户端。 为了向后兼容，仍然支持原始的init命令： ```sh npx agents-relay init --repo OWNER/REPO --pr 1 --id job-1 --title "Objective" ``` ## npm出版 推到 `main` 运行 `.github/workflows/publish.yml`：安装，测试，选择下一个NPM版本，包检查，发布，并创建匹配 `vX.Y.Z` 标签。特性分支不编辑 `package.json` 版本。如果 `agents-relay` 还没有发布第一个版本是什么 `1.0.0`;以后的版本只增加NPM注册表中的补丁版本。存储库必须提供 `NPM_TOKEN` 行为保密，经许可公开发表 `agents-relay` 包中。 普通消费者应该使用 `npx agents-relay ...` (或 `npx agents-relayd ...`）。 成功发布后，工作流记录一个幂等函数 `agents-relay:package-published:v1` 使用本地合并作业元数据标记注释。它使用封闭显示PR时，否则可重复使用 `[Agents Relay] Publication events` 问题。GitHub的 `issue_comment` webhook将嵌入的作业ID解析回它的持久SQLite作业，并发出一个相关的 `package.published` events-总线事件，包含存储库、包、版本、注册表、提交SHA、PR号和webhook交付ID。它的源身份是GitHub交付(`github//delivery/`)，而不是工作执行标识。 `package.published` 是一个发布事实，而不是一个服务管理命令。agent Relay不拉取包、重启PM2或决定哪个本地服务使用包。外部部署订阅者可以侦听此事件、验证确切的版本是否可提取、更新/重新启动受影响的服务、验证其运行版本和运行状况，并发布其自己的部署结果事件。 这将发布、部署和健康运行作为独立的事实，并消除了协调器线程同步等待npm准备就绪的需要。 对于显式本地演示/测试模式： ```sh npm install npm run build node dist/cli.js init --file .agents-relay.json --title "Dogfood" --id demo node dist/cli.js task create --file .agents-relay.json --task-id hello --output task-pr --input "Complete the described task" node dist/cli.js reconcile --file .agents-relay.json npx agents-relay serve --file .agents-relay.json ``` ### 选择加入临时聊天质量检查 正常的 `npm test` 套件不打开浏览器或发送ChatGPT消息。 对于一次性临时聊天路径的显式实时检查，请使用 通过身份验证的浏览器会话并运行： ```sh npm run test:chatgpt-temp-quality ``` 这个小的实时套件包含两个临时聊天提交门：一个普通文本 提示和带有附件的提示。它不执行工人生命周期 事件、持久线程重用、恢复或重试行为。 在本地主机端口8787上打开仪表板。标记格式故意是公开的，并且对追加内容友好。守护进程/工作区操作使用 `ProjectedDurableStore` 通过SQLite RelayStore加上认证GitHub投影适配器；GitHubStore不是守护进程运行状态数据库。 确定性投影冲突是安全且可观察的。一个id相同/不同的定义 `append_task`/`append_plan` 是一次性分类成耐用的吗 `conflict` 状态，停止消耗重试预算，保留结构化分歧证据，并且永远不会自动覆盖。检查与 `agents-relay projection conflicts --repo OWNER/REPO --pr NUMBER` 并明确地修复 `agents-relay projection resolve --repo OWNER/REPO --pr NUMBER --projection-id ID --action requeue|discard-local`． 看到 [文档/ architecture-v2.md](https://npmcn.com/package/agents-relay/docs/architecture-v2.md). 外部产品反馈使用可重用 `src/feedback.ts` 合同。看到 [文档/ feedback-intake.md](https://npmcn.com/package/agents-relay/docs/feedback-intake.md) 模式、附件限制、隐私规则、物化路径，以及以后的作业/任务/ pr的来源信封。 协调租约和启动就绪任务，而无需在运行时调度程序中等待；命令行只需要等待足够长的时间，以便其启动的工人能够持久保存结果。Agents-relayd（或等效的NPX agents-relay服务）是看门狗/仪表板模式。模型支持的工作者需要——事件属性；事件传输携带权威终端工作者事件以及唤醒/进程流量。看到 [文档/ service.md](https://npmcn.com/package/agents-relay/docs/service.md)． ——file PATH仅为显式本地演示/测试模式。 路由器规则存储在 `~/.agents-relay/execution-router-rules.md` 默认和使用 `[choices]` 加上 `[routing-instruction]` 章节（参见Execution Router文档）。 `agents-relayd --execution-router-rules PATH` 为守护进程选择一个不同的文件；显式的CLI路径优先于 `AGENTS_RELAY_EXECUTION_ROUTER_RULES`，为了兼容性，仍然支持它。 `agents-relayd` 没有 `--pr`/`--id` 默认情况下在工作空间模式下运行：它发现嵌套的Git存储库 `~/Workspace`，只保留GitHub `origin` 并将他们管理的PR工作聚合到一个仪表板和工作池中。通过 `--workspace PATH` 用另一个词根 `--repo OWNER/REPO` 保持单存储库池模式。 对于自动化，代理中继可以使用GitHub App安装认证通过 `AGENTS_RELAY_GITHUB_APP_ID`， `AGENTS_RELAY_GITHUB_APP_INSTALLATION_ID`, `AGENTS_RELAY_GITHUB_APP_PRIVATE_KEY_FILE` （或匹配CLI标志）。Webhook模式是本地优先的：目标Webhook协调是主要的，仪表板自动刷新读取从SQLite RelayStore状态恢复的一次性进程内视图，并且广泛的看门软件下降到30分钟的回退。不维护单独的持久化仪表板作业缓存。看到 [文档/ github-app-rate-limit.md](https://npmcn.com/package/agents-relay/docs/github-app-rate-limit.md). 为每个作业运行一个逻辑调节权限。 `ReconcileCoordinator` 序列化进程中的工作；在多个独立的协调程序拥有相同的作业之前，使用分布式原子租约。不要在PR-body Job标记或PR-comment Task标记中放置秘密、凭据、私有提示或大型私有有效负载；只存储摘要和工件引用。 模型支持的任务在启动前由Relay路由。普通任务生成器会忽略适配器/提供者/模型；显式路由标志仍然是兼容性/调试约束。看到 [文档/ architecture.md](https://npmcn.com/package/agents-relay/docs/architecture.md) 和 [技能/ agents-relay / SKILL.md](https://npmcn.com/package/agents-relay/skills/agents-relay/SKILL.md). XChat和其他编排器可以使用Relay的精确共享发现实现，而无需复制文件系统搜索逻辑： ```sh npx agents-relay context resolve --project-path ~/Workspace/agents-relay --role orchestrator ``` 该命令只解析当前执行的具体路径。使用 `--skills` / `--agents` 用于显式选择；没有解析过的绝对路径写入持久任务状态。 最小的代理网络表面是机器驱动的注册和发现。 `agent-register` 将代理身份、职责边界、声明的功能、端点/运行时、可用性和路由元数据保存在可信的PR标记中； `agent-discover` 应用硬过滤并返回有证据支持的候选人。适配器仍然是运行时，而不是代理标识。看到 [文档/ architecture.md](https://npmcn.com/package/agents-relay/docs/architecture.md) 用于受约束的未来远程提交契约。 ### 代理工作者生命周期 托管任务是代理的描述性工作，而不是shell命令。使用 `codex` 或者 `chatgpt` 对于worker任务。诸如测试、构建工具、Markad Vision、ffmpeg和其他cli之类的命令由编排器或执行代理调用；它们不是工作者适配器。 每个模型支持的任务都声明一个持久输出 `--output task-pr` 或者 `--output file --output-path PATH`． agent Relay用托管的PR URL、持久的任务注释URL、作业/任务标识、项目、输出合同和强制的终端事件合同来引导worker；worker从GitHub中获取任务意图，而不是接收存储任务提示符的副本。 对于Codex和ChatGPT， **相关的工作者事件是权威的生命周期输入**，而不是单独的耐用品店。事件发布使用规范的Neo `events-bus` 表面(`events__publish` 对于沙盒/托管worker，或 `NEO_EVENTS_EMIT` 本地直接工人)；代理中继订阅，验证相关性，应用图形转换，在RelayStore中持久化结果，并将它们投射到GitHub。继电器发布 `task.process.launched` 只有在适配器成功启动后； `task.started` 职工所有，必须是一个新的、相关的开始承认。食典委发布 `task.process.exited` 当它的同步运行时退出时，而ChatGPT则发布 `task.process.async_exited` 在一次性提交后，运行时退出；两者都不能代替 `task.completed`， `task.failed`， `task.blocked`，或者 `task.cancelled`． 执行代理必须准确地发布一个相关的终端事件。Relay仅从该终端事件持久化匹配的持久状态。模型支持的任务需要事件总线，如果没有终端事件到达，则显式超时。 外部执行使用单个全局变量 `webhelm` 安装的可执行文件 WebHelm技能。在启动中继之前，请通过代理安装该技能 正常的技能机制，并按照自己的设置说明 `SKILL.md`． 技能可以存在于任何目录中；它的安装程序将 全球 `webhelm` 命令到技能启动器。继电器调用 `webhelm platform profile chatgpt` 在浏览器工作区初始化之前。 Relay不会发现Skill目录或调用单独的运行时。 ChatGPT适配器使用Relay的 `agents/chatgpt-worker.agent.md` 生命周期的合同。新员工使用 `webhelm platform run chatgpt new-thread --session-id SESSION_ID --config ` 在呼叫者拥有的会话中。这是一个常规的持久ChatGPT线程，它支持已验证帐户中连接的Neo MCP。Relay在提交后关闭会话，但ChatGPT线程保留在历史记录中。现有线程的审查和移交继续进行 `new-turn`． 文件路径包含在工作消息中供Neo MCP读取；它们不会作为浏览器附件上传。提交收据保留 `status: submitted`;事件总线拥有任务完成。 ```sh npx agents-relay task create --repo OWNER/REPO --pr 5 --id job-1 \ --task-id research-ui --adapter chatgpt \ --capabilities model,chatgpt,browser-harness \ --provider openai --model MODEL \ --output file --output-path runs/research-ui.md \ --input "Research the dashboard UX and write the final report to the declared output file." ``` GitHub PR状态对于终端生命周期是权威的：合并的PR将其管理的工作调和为 `COMPLETED`;一个封闭的、未合并的PR对应于 `CANCELLED` 并且不能启动排队工作。仪表板显示 `/api/jobs` 并分别显示PR状态、持久作业生命周期和派生的运行时状态。合并的PR将生命周期调整为 `COMPLETED`;封闭的、未合并的PR将生命周期调和为 `CANCELLED`. Relay没有用于新工作的协调器工作者适配器。编排器是创建/计划持久任务的外部客户端；执行路由器选择一个真实的工作路由(`codex` 或者 `chatgpt`）. CLI和指示板并不只公开手动编排器 `task start`， `task complete`，或合成的 `record` 路径。 历史商店可能仍然包含 `adapter: orchestrator`． 协调只将该值视为遗留迁移证据：从未启动的排队工作可以适当地转换为正常的工人需求；具有未知结果的正在运行的工作被隔离为BLOCKED而不是重播；仅显式持久 `externalCompletionVerified` 证据可以在不执行的情况下完成遗留工作。新任务创建和任务更新拒绝该适配器。 对于托管作业，GitHub PR主体是规范的协作表面，而SQLite仍然是生命周期权威。 ### 自动任务故障排除 当活动作业包含当前运行时 `FAILED` 任务时，协调可能会创建一个p优先级 `troubleshooter` 针对那个失败尝试的恢复任务。 `BLOCKED` 工作不是故障排除程序所拥有的：它一直处于阻止状态，直到权威解除阻止将其转换为 `UNBLOCKED`． 恢复任务被路由到具有存储库/工具访问权限的本地codex工作人员，并在捆绑的疑难解答代理合同下运行。故障排除程序的诊断是事件优先的：在对根本原因进行分类或重试之前，它必须检查失败任务的任务范围生命周期事件历史（包括排序、重复/缺失/延迟事件、源和阶段数据）。 疑难解答程序在重试之前进行诊断。任务本地或暂态执行原因被狭窄地修复；通过拥有的存储库的P0/自作业工作流修复共享的工作者/运行时/工具缺陷。可疑的人为/外部阻塞者进入规范 [`workflow/escalation.mmd`](https://npmcn.com/package/agents-relay/workflow/escalation.mmd) 图通过 `agents-relay escalation`;疑难解答程序本身不决定升级结果分支。 ```mermaid flowchart LR Failed[Failed task] --> Troubleshooter Troubleshooter -->|technical| Repair[Repair / retry] Troubleshooter -->|suspected human blocker| Escalation[Escalation graph] Escalation --> Invoke[neo escalation] Invoke --> Codex[Escalation Agent + elevated Local Codex] Codex -->|resolved| Resume[Resume recovery] Codex -->|failed| Technical[Technical recovery evidence] Codex -->|needs_user| User[Notify user + task.blocked] User --> Unblock[Authoritative unblock] Unblock --> Repair ``` 升级图是Neo返回后发生的事情的权威： `resolved` 选择恢复， `failed` 选择技术故障处理，且仅 `needs_user` 选择block for user操作。通知机制始终保持调用者描述 `--on-needs-user`;中继不绑定微信、Discord、iMessage或其他通道。只有在故障原因修复后，故障排除程序才会重试原始的FAILED任务并验证持久进度。历史已解决的失败不会产生重复的恢复工作，并且确定性协调不会为相同的失败尝试复制疑难解答任务。 ### 权威解锁和规划器历史记录 依赖释放和运行时解除阻塞是两个不同的概念。依赖完成只是简单地释放DAG工作。运行时/外部阻塞仍然存在 `BLOCKED` 直到 `task unblock`， `job unblock`，或阻塞作业解决方案记录阻塞的基线/当前证据并发出 `task.unblocked`，将任务转换为 `UNBLOCKED`. 对于每个作业，解锁证据都成为持久的恢复上下文。Relay重新尝试相同的授权故障排除程序，而普通工作则在必要时使用planner拥有的恢复。每一轮规划师都是一流的 `agents-relay:plan:v1` 记录。它在生成任务之前被持久化，然后使用Planner评估和生成的任务id更新。遗留的工作 `changeCycle` 数据仅作为兼容性输入而不被当前模型写入。 ### 浏览器工作区产品边界 代理中继拥有持久性 `Relay` 浏览器工作区作为产品基础结构。在守护进程启动时，它运行 `webhelm status`，动态导入返回的绝对值 `admin_helper`，和呼叫 `ensureWorkspace("Relay", 6)`． 这个引导是最好的努力：浏览器工作区发现/帮助器失败被记录并跳过，因此它们不会阻止 `agents-relayd` 从开始;在浏览器工作区恢复之前，ChatGPT浏览器工作可能仍然不可用。新的ChatGPT工人使用relay拥有的浏览器会话，并在验证提交后关闭它。现有线程 `new-turn` 消息直接使用持久异步队列，而无需创建浏览器会话。Relay不通过CLI生命周期命令创建或删除工作区。 ## 共享出版物报告 具有现有已验证发布/发布工作流的存储库可以将最终结果报告给代理中继，并在此存储库中使用可重用操作： ```yaml permissions: contents: read issues: write pull-requests: read - name: Report verified publication uses: lalalic/agents-relay/.github/actions/report-publication@publication-v1 with: token: ${{ github.token }} artifact: my-package-or-artifact version: ${{ steps.release.outputs.version }} channel: https://registry.npmjs.org - name: Report release failure if: ${{ failure() }} continue-on-error: true uses: lalalic/agents-relay/.github/actions/report-publication-failure@publication-v1 with: token: ${{ github.token }} stage: release workflow ``` 调用者必须只报告它实际验证过的发布。对于本地优先的作业，操作从权威的本地合并提交消息中读取作业ID和可选的显示PR，并发布兼容的 `agents-relay:package-published:v1` 或发布失败标记到该显示PR或可重用发布问题。历史github合并的PR相关性仍然作为后备支持。标记和GitHub webhook仅用于传输/关联：代理中继解析原始作业并通过持久保存发布事实 `RelayStore.recordPublication(...)` 到权威的SQLite `publication_delivery` 和 `publication_state` 表。发布成功或失败不会改变已完成作业的生命周期状态。 `artifact` 可以识别npm/PyPI包，Chrome扩展，GitHub发布工件或自定义发布工件。 `channel` 标识注册中心/存储/发布通道，并显示为发布元数据。相同工件/版本的重复报告是幂等的。 ### 项目范围代理Markdown继承 代理查找有两层：内置中继 `skills/agents-relay/agents/` 和 `/agents/`. `job.projectPath` 选择存储库中的上下文根（包括单线程内容项目）；没有搜索工作空间/全局代理回退。项目代理前台可指定 `extends: relay/planner`， `mode: extend`, `sections: { replace: [Heading/Subheading], extend: [Other Heading] }` 使用标题路径，或 `mode: replace` 为了一个完整的行为替代。relay拥有的生命周期、Job/Task和事件契约是单独注入的，不能被项目代理所取代。未扩展本地代理是一个独立的定义。解析器发出一个确定性的SHA-256组合Markdown；缺失的节或不支持的父节失败，而不是静默地丢弃指令。 ## 常见问题 ### agents-relay 是什么？ 通过GitHub拉取请求协调的持久异步代理作业 ### 如何安装 agents-relay？ 在项目目录运行 npm install agents-relay，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agents-relay、agents-relayd，可以用 npx agents-relay 直接运行。 ### agents-relay 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agents-relay 是否存在。 ### agents-relay 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### agents-relay 可以商用吗？ agents-relay 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### agents-relay 还在维护吗？ 最新版本 2\.0\.202 发布于 2026/11/03（今天）；至今共发布 381 个版本，其中过去 12 个月发布了 381 个；首次发布于 2026/09/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。