create-rabiroute-agent-adapter

Files (5)

• SKILL.md
• openai.yaml · agents/
• host-onboarding-checklist.md · references/
• host-onboarding-checklist_en.md · references/
• owner-first-design-gate.md · references/

SKILL.md (first lines)

# 创建 RabiRoute Agent 端适配器

## 目标

新增 Agent 端时，不只接上一条 `deliver(message)`。必须让用户能在 WebGUI 里尽量自动完成配置：

1. 自动发现安装位置、运行状态、登录状态、插件状态、项目目录和会话。
2. 如果有项目概念，先选 Agent 路径或服务地址，再选项目目录，最后选会话。
3. 如果设置了项目目录，会话列表必须能显示项目归属并用于消歧。Codex Desktop 下拉显示全部任务，选择任务后自动采用其 cwd；其他 Agent 可按项目过滤。没有项目概念就隐藏项目目录。
4. 能扫描的不要让用户手填；必须提供刷新、安装、打开下载页、登录、部署/更新插件、健康检查等动作入口。
5. 添加 Agent 端后必须在 WebGUI 展示“环境和依赖”清单：安装状态、登录状态、插件/扩展、Endpoint、项目/会话发现、下载或文档入口、缺失项和下一步动作。
6. 运行态要能解释“为什么不可用”，不能只给一个空输入框或沉默失败。

所有带会话概念的 Agent 端还必须满足以下 P0 合同，缺一项都不能标记为 `verified`：

1. 已保存的完整任务 ID 存在且 owner 记录未归档时，直接投递到该任务，不创建新任务。owner 保存的默认 cwd、标题或 SQLite `title` 都不能否定有效 ID；本次执行目录由当前 Route 或计划绑定单独提供。保存 ID 指向已归档任务时，真实投递或保存提交点幂等创建新任务并持久化新 ID；不查找或复用其它同名任务。扫描、刷新和失焦仍只报告归档状态。
2. 目标不存在时，先按 RabiPC Manager 保存的明确名称 + workspace 查找；存在一个或多个匹配时按 `updatedAt` 降序绑定唯一最新任务，只有最新时间并列时才要求用户选择；零匹配才幂等创建一个会话，再把真实消息投给新会话，并发、重试和索引延迟期间仍只能创建一次。允许提供用户显式点击的“自动初始化会话”：它必须先完成同一保存/解析事务，再通过唯一 owner 投递一条携带角色文件、记忆、计划和必读项的角色初始化消息。
3. 真实消息必须通过 Agent 桌面应用实际使用的 owner 接口执行，保证桌面端统一可见并沿用同一任务的模型、工具、权限和状态；不得用第二 Runtime 冒充。
4. 用户在 Rabi 设置中选择已有会话或输入新名称后，点击保存必须完成解析/创建并持久化新的名称、完整 ID 和 workspace。
5. 完整任务 ID 是任务身份；workspace 是每次投递的执行目录，名称用于显示和无 ID 查找。Agent/Desktop 改名、默认 cwd 不同或首投后 `title` 自动变化时继续同一 ID；用户在 Rabi 端明确输入新名称时，UI 先清空旧 ID，再按新名称和 workspace 查找/创建并保存新 ID。
6. 项目和会话扫描只允许在进入设置界面时自动执行一次，或由用户点击扫描/刷新按钮显式触发；禁止定时轮询、展开面板、输入、`blur`、保存或普通状态刷新持续扫描。

Codex 目前的产品基线是 Desktop owner：RabiRoute 从 Codex Desktop 左侧栏共用的 `session_index.jsonl.thread_name` 读取用户可见 `Name`，再按完整 ID 合并本地状态提供的 cwd、归档、时间和 owner/rollout 状态，以“完整 ID + 工作目录”稳定绑定，并通过 Desktop IPC 把真实消息交给 Codex/ChatGPT Desktop 当前任务。SQLite `threads.title` 可能是首条 prompt，不得用于下拉名称或同名查找。Desktop 必须在线；任务无法加载就失败，禁止启动备用执行 Runtime。

AstrBot 这类服务型 Agent 必须显示服务健康、认证状态和可选会话。当前 AstrBot 合同只允许绑定明确的 ChatUI 会话并调用 `/api/chat/send`；没有 `ASTRBOT_SESSION_ID` 时失败，不再部署或回退到 `rabiroute_agent` 插件。

先读 `../../docs/agent-adapter-standard-requirements.md` 和 `../../docs/agent-adapter-integration-lessons.md`。前者定义标准 Agent 端应达到的能力与验收合同；后者记录 Desktop IPC 未唤醒 owner、隔离 app-server 不实时/缺桌面工具，以及共享 4510 导致 Desktop `ECONNREFUSED` 的历史。涉及 Codex/Desktop、会话绑定或工具注册时，还必须读 `../../docs/codex-desktop-agent-acceptance.md`，不能跳过。

新增任何带 Runtime、会话、桌面可见性或工具注入的 Agent 端时，还必须读 [owner-first-design-gate.md](references/owner-first-design-gate.md)，并在实现前完成其中的设计门。不要等实现失败后才补所有权说明。

## 负一号关卡：冻结用户可观察合同

写探测、后端或 UI 前，先把需求改写成可验收事实：

- 消息必须出现在哪里，多久可见，谁能看到运行状态和结果。
- 哪个 task/session owner 必须执行真实消息。
- 模型、工具、权限和审批由谁注入。
- Agent、宿主和 RabiRoute 缺席时各自应如何启动、失败和退出。
- 新建、续投、重名、失效 ID、active turn 分别是什么行为。
- 哪些行为明确禁止，例如第二执行 Runtime、模糊换会话、持久化修改宿主启动配置。

把它写成“要求 / 真源 / 验收证据 / 禁止替代”表。用户未确认前，不得为了让错误消失而改变可观察合同。协议无法满足时保持 `experimental` 并报告缺口，不得私自增加 fallback。

历史反复修改暴露了六类设计异味，看到任一项就停止实现并回到设计门：

1. 用连接成功、记录可读或构建通过代替用户界面中的真实结果。
2. 把同一个 session ID 误当成同一个 live owner、实时事件流和工具集合。
3. 用 fallback 掩盖 owner 未加载、身份错误或协议不完整。
4. 为追求“一个 Runtime”而让宿主依赖 RabiRoute 的端口、环境变量或进程。
5. 把本机交互式 Desktop 与远端无人值守 Agent 当成同一生命周期。
6. 在一个大改动里同时迁移 Runtime、UI、配置、打包和文档，导致测试只验证实现自洽。

一个 adapter 只能有一条真实消息执行路径。发现必须靠第二条路径才能“可用”时，先判断产品要求是否其实包含两种不同 adapter；拆分产品边界，不做模式切换。

## 零号审查：所有权和启动独立性

写探测脚本或 UI 前，先列出：Agent、宿主、Runtime、Transport、Session、Tool 分别由谁拥有，谁启动、谁停止、故障会影响谁。没有这张清单就不实施。

硬性边界：

- 外部 Agent/服务拥有自己的生命周期；RabiRoute 只能探测或通过已验证接口连接。
- 如果要求消息实时出现在某个 UI 并使用该 UI 注入的工具，这个 UI 的任务 owner 必须执行真实轮次；恢复相同 session ID 的第二个 Runtime 不等价。
- Codex Desktop 是 transport 的 owner 和健康条件；RabiRoute 只连接 IPC，不启动/停止 Desktop，也不提供 fallback。
- Adapter 只有在“创建空任务、恢复用户名称”等不执行真实 prompt 的元数据操作中，才可短暂拥有隔离子进程；完成后立即回收，不能成为 fallback。
- 不得从普通 adapter 配置写用户级环境变量、注册表、桌面启动参数或固定 WebSocket 地址。
- 不得让 Agent/Desktop 的冷启动依赖 Manager、Gateway、托盘或某个固定 RabiRoute 端口。
- “一个 Runtime”指一个实际消息 owner，不是把 Desktop 强制连接到 RabiRoute 拥有的共享端口。
- 对 Codex/ChatGPT Desktop，`127.0.0.1:4510` 属于 Desktop 自己的生命周期。禁止写入进程、用户或机器级 `CODEX_APP_SERVER_WS_URL`，禁止让 RabiRoute 监听/接管 4510，禁止为了投递关闭或重启 Desktop。必须实测 RabiRoute 停止时 Desktop 仍可启动，避免再次出现 `connect ECONNREFUSED 127.0.0.1:4510`。

开始改代码前必须完成两个基线检查：

1. RabiRoute 全部停止时，目标 Agent/Desktop 能单独冷启动。
2. 目标 Agent/Desktop 全部停止时，RabiRoute Manager 能启动，并对该 adapter 给出可行动状态。

任一项失败，先修所有权，不继续增加回退模式。

## 统一 API Help 与敏捷兼容流程

Agent 适配器不得把 API、渠道或参数写死为长期真源。每次启动、Manager generation 变化、接口返回未知字段/错误，按以下顺序刷新：

1. 从 Host status 或结构化 READY 取得当前 Manager 地址，并用 `/meta` 核对 generation、instance 和健康边界。
2. 调用 `GET /api/agent/help`，按 `operationId` 或 `method + pathTemplate` 选择当前接口合同；发送渠道另调用 `GET /api/agent/send/capabilities`。
3. 只使用 help 返回的 path、query、body、response、errors、nextStep 和 capability；先检查 `contractLevel` 与 `coverage.missing`：`baseline` 不得当作精确 schema，缺失项必须回到 contractResource 或专用 capabilities；未知接口、渠道或字段 fail closed，不猜测、不自动换渠道。
4. 成功与失败都保存 HTTP 状态、JSON `code`、`errorCode`、`help`、`repair` 和 receipt/resource 标识。写请求超时、5xx、412 或 generation 变化时，保留原 body 和 delivery/idempotency key，先读回，不自动重放。
5. 新增接口或渠道时，先更新统一能力目录、help、真实路由声明、契约 fixture 和中英文导航；不得只改长文或 Agent skill。

`/api/lan-agent/capabilities` 应返回同一 operation help 摘要。Help 只描述当前 Manager 版本，不能缓存成永久合同；适配器应记录读取时的 generation 和 contract/schema 版本（若返回）。

## 统一能力模型

每个 Agent adapter 都要先声明自己支持哪些能力，再决定 UI 显示什么字段：

```ts
type AgentAdapterCapability = {
  type: AgentAdapterType;
  label: string;
  maturity: "verified" | "experimental" | "stub";
  requiresInstall: boolean;
  requiresAuth: boolean;
  hasAgentPath: boolean;
  hasServiceEndpoint: boolean;
  hasProject: boolean;
  hasSession: boolean;
  canListProjects: boolean;
  canListSessions: boolean;
  canFilterSessionsByProject: boolean;
  canDeployPlugin: boolean;
  canHealthCheck: boolean;
};
```

能力模型是产品合同，不只是类型定义：

- `verified`：本机或 CI 已验证扫描、配置、投递、失败诊断四条路径。
- `experimental`：代码存在，但没有完成端到端验证；WebGUI 必须显示“实验/未验证”提示。
- `stub`：只是占位或打开外部页面；不能默认启用，必须说明缺哪段能力。
- `hasProject=false` 时不要显示项目目录。
- `hasSession=false` 时不要显示会话输入框，要显示“该 Agent 无可选会话”。
- `canListSessions=false` 时不要伪装成下拉框；用说明和后续任务替代。

From vb2250158/RabiRoute, MIT.

More from vb2250158/RabiRoute