create-rabiroute-message-adapter

Files (2)

• SKILL.md
• authentication-and-credentials.md · references/

SKILL.md (first lines)

# 创建 RabiRoute 消息端适配器

## 目标

新增消息端时，不只是接收一段文本。必须让用户能在 WebGUI 里尽量自动完成配置、启动、检查和诊断：

1. 自动发现安装位置、运行状态、登录状态、WebUI/Dashboard、HTTP/WS 端口和可用实例。
2. 平台支持多账号/多实例时，必须按“实例列表”建模，不能把多个账号塞进一个输入框。
3. 能启动的后台要提供启动按钮；不能启动的要提供打开目录、打开管理页、复制启动命令或安装链接。
4. 能扫描的不要让用户手填；必须提供刷新、打开、检查、复制地址、健康检查等动作入口。
5. 运行态要能解释“为什么不可用”，不能只给一个空输入框或沉默失败。
6. 外部发送、群发、写平台消息默认必须有安全边界；配置/健康检查不能偷偷发送真实消息。
7. 添加消息端后必须显示“环境和依赖”清单：需要安装什么、当前识别到什么、缺什么、去哪下载/打开文档、下一步怎么配置。

需要认证的消息端还有一条不可绕过的产品合同：用户必须能从消息端卡片进入并完成登录、授权、重新授权或退出。全局设置页可以承载高级默认值，环境变量可以作为测试或迁移注入，但二者都不能成为正式产品唯一的授权入口。账号、Route 绑定、秘密凭据与运行时状态的归属，以及授权状态机和 API，按 [消息端授权与凭据合同](references/authentication-and-credentials.md) 执行。

NapCat / OneBot 是多实例消息端的基线：一个 route 可以配置多个 NapCat 实例，每个实例有自己的 WS 监听端口、HTTP 地址、WebUI、token、启动命令和工作目录。收到哪个实例的事件，就必须用哪个实例的 HTTP 地址发送回复，避免串号。

## 命名规范：不要把具体来源都叫 Webhook

`webhook` 是传输方式，不是多数用户要理解的消息端名称。除非新增的入口确实是“给开发者随便 POST 的通用 Webhook”，否则 WebGUI、配置项、日志、状态和文档都必须使用具体来源名：

- 小爱 / 小米音箱入口显示为“小米音箱”或“小爱音箱”，不要显示成“Webhook”。
- FenneNote 语音转写入口显示为“FenneNote”或“芬妮笔记”，不要显示成“Webhook”。
- Home Assistant、桌面语音、插件桥、平台回调等都按真实来源命名。
- 技术字段可以保留 `webhookUrl`、`webhookPath`、`adapterType: "webhook"` 这类底层兼容字段，但用户可见标题、按钮、日志标题和消息文件分组必须用具体来源名。

新增消息端前先回答两个问题：

1. 用户看到它时会把它理解成哪个“来源/设备/应用”？
2. 如果日志里出现三条事件，用户能不能一眼分清是“小米音箱”、 “芬妮笔记”还是“通用 Webhook”？

如果答案不清楚，就不要新增一个泛泛的 `Webhook` 卡片；应该新增具体消息端或至少在实例名中固定写明来源。

## 统一能力模型

每个消息端都要先声明能力，再决定 UI 显示什么字段：

```ts
type MessageAdapterCapability = {
  type: MessageAdapterType;
  label: string;
  maturity: "verified" | "experimental" | "stub";
  requiresInstall: boolean;
  requiresAuth: boolean;
  hasInstances: boolean;
  canListInstances: boolean;
  canLaunchInstance: boolean;
  hasDashboard: boolean;
  hasInboundHttp: boolean;
  hasInboundWebSocket: boolean;
  hasOutboundApi: boolean;
  canHealthCheck: boolean;
  canReadLoginInfo: boolean;
  canDryRun: boolean;
  authModes: readonly ("credentials" | "qr_code" | "device_code" | "browser_oauth" | "external_dashboard" | "local_session")[];
  credentialScope: "none" | "account" | "instance";
  canLogout: boolean;
  canRefreshAuth: boolean;
};
```

能力模型是产品合同：

- `verified`：真实跑通过安装/启动检查、接收事件、路由、失败诊断；如有外发 API，也验证了 dry-run 或受控发送。
- `experimental`：代码存在，但没有完成端到端验证；WebGUI 必须显示“实验/未验证”提示。
- `stub`：只是占位、打开页面或复制命令；不能默认启用。
- `hasInstances=true` 时 UI 必须是实例列表，可添加/删除/启用/检查/启动。
- `canLaunchInstance=false` 时不要显示“启动后台”，改显示启动说明或打开目录。
- `hasOutboundApi=false` 时不要显示“回复/发送已可用”，只显示接收能力。
- `canReadLoginInfo=false` 时健康检查不能伪装成已登录，只能显示连接可达。
- `requiresAuth=true` 时 `authModes` 不能为空，消息端卡片必须提供与这些模式一致的完成入口；只显示 `authorization_required`、环境变量名或外部说明不算完成入口。
- `credentialScope` 表达秘密凭据归属，不表达 Route 订阅关系。多个 Route 复用一个账号时，各 Route 只保存系统生成的 `endpointAccountId` 和自己的订阅策略，不能复制 token、cookie 或密码。
- `canLogout`、`canRefreshAuth` 必须来自真实平台能力；不支持时给出明确的替代动作，不能显示无效按钮。

## 登录授权、账号与 Route 的边界

需要认证时先完整读取 [消息端授权与凭据合同](references/authentication-and-credentials.md)，并在设计里明确以下四个拥有者：

1. **消息端账号或实例**拥有平台身份、授权状态和可复用连接。
2. **本机受保护凭据库**拥有 token、secret、cookie、refresh token 和密码等秘密；业务配置只保存不透明 `credentialId`。
3. **Route**只拥有 `endpointAccountId`、启用状态、事件过滤、目标角色和外发策略。
4. **Manager 当前 generation**拥有连接、挑战、轮询、刷新和健康状态；generation 更换后重新建立连接，不复用旧代瞬时挑战。

消息端卡片可以直接内嵌授权 UI，也可以打开该消息端贡献的对话框或子卡片，但用户必须从当前卡片完成闭环：创建或选择账号、开始授权、处理二维码/device code/浏览器回调/凭据输入、看到连接结果、重新授权或退出。禁止把“去系统环境变量里设置 token 并重启”当作正式产品流程。

可供多个 Route 使用的平台账号不要在每个 Route 复制一份凭据。卡片中显示账号选择器和连接状态；首次使用时可在原地创建并授权账号。全局设置页只维护与某个 Route 无关的高级默认值、共享资源或账号总览，不能成为唯一登录入口。

## 先判断消息端类型

实现前先确认目标消息端属于哪类：

- **平台机器人型**：QQ/NapCat、微信、飞书、Discord、Slack、Telegram；通常有账号、登录态、收消息和发消息 API。
- **OneBot/协议桥型**：NapCat、Lagrange、go-cqhttp 类；通常有 WS 事件入口和 HTTP action 出口。
- **Webhook 型**：外部系统 POST 到 RabiRoute；通常没有会话和登录态，但要有 secret、样例 payload 和 curl。
- **定时/内部触发型**：heartbeat、manual trigger；没有外部平台，但会主动制造内部事件。
- **语音/设备事件型**：FenneNote、小爱、Home Assistant；需要保留来源、转写、设备、附件或上下文路径。
- **平台框架插件型**：AstrBot 等框架内插件；可能由插件把平台事件转成 RabiRoute 事件。

不要为了统一 UI 强行显示不存在的字段。字段由能力决定。

## 先摸清真实 API

做任何消息端适配前，先用最小脚本或临时命令验证目标平台的真实能力。不要先写 WebGUI。

必须按这个顺序探测：

1. **安装/进程检查**：确认平台 app、协议桥、插件或服务是否存在。
2. **启动方式**：确认能否通过命令、服务、Shell、URL 或插件后台启动；记录启动命令和工作目录。
3. **认证/登录检查**：确认是否需要二维码、账号、token、cookie、device code、secret 或本机登录态。
4. **实例/账号检查**：如果支持多账号，确认实例 id、QQ/账号、端口、配置文件位置和 WebUI。
5. **入站事件测试**：用 mock 或真实平台测试收到一条无害事件，确认 raw payload 能落盘。
6. **事件规范化测试**：确认能转成 RabiRoute 的统一字段：来源、时间、目标、发送者、消息、回复链、附件。
7. **路由触发测试**：确认普通消息、@、直接回复、间接回复、私聊、Webhook、心跳等 route kind 正确。
8. **外发能力测试**：如果平台支持发送，先只测读取登录态或 dry-run；真实外发必须用户明确授权。
9. **同实例回路测试**：确认某实例收到的消息只会用同一实例的出口回复，不会串到另一个账号。
10. **重复事件/重连测试**：确认断线重连、重复 message id、重复 webhook 不会重复投递 Agent。

测试消息必须无害、可识别、可公开。真实平台外发测试必须先征得用户明确同意。

From vb2250158/RabiRoute, MIT.

More from vb2250158/RabiRoute