# Yonexus — TASKLIST 基于 `FEAT.md`、`PLAN.md`、`PROTOCOL.md`、`README.md` 整理。 目标：把 Yonexus 从“规划完成、实现未开始”的状态，拆成可逐项交付、可验收、尽量低耦合的小任务列表。 --- ## 0. 任务拆分原则 - 先把**协议、边界、脚手架**固定，再做运行时逻辑 - 先做**可启动、可连接**，再做**配对/认证** - 先做**核心 happy path**，再做**失败路径和安全硬化** - 先做**Server / Client 各自最小闭环**，再做联调 - 每个任务尽量满足： - 范围明确 - 可以单独提交 - 有清晰验收标准 --- ## Phase 0 — 仓库与规范对齐 ### YNX-0001 统一仓库定位与术语 **目标** - 统一文档中对 Yonexus、Yonexus.Server、Yonexus.Client、Yonexus.Protocol 的描述 - 明确这是“umbrella + 三个独立仓库/子模块”的模型 **子任务** - 检查 `README.md`、`PLAN.md`、`FEAT.md`、`PROTOCOL.md` 术语是否一致 - 明确 `builtin`、`rule_identifier`、`identifier`、`secret`、`pairingCode` 等词汇定义 - 记录 v1 非目标，避免实现漂移 **验收标准** - 核心文档不存在角色冲突或架构冲突描述 - 协议字段名称在文档中保持一致 --- ### YNX-0002 定义 v1 实现边界 **目标** - 把“必须做”和“以后再说”彻底分开 **子任务** - 固化 v1 必做项：WebSocket、pairing、auth、heartbeat、rule dispatch、持久化 - 固化 v1 不做项：多服务器、离线消息队列、复杂规则匹配、管理 UI - 明确心跳 ack 是否默认开启 - 明确断线重连采用指数退避还是固定退避 **验收标准** - 有一份可执行的 v1 scope 列表 - 实现阶段不再反复讨论边界 --- ## Phase 1 — 协议落地与共享契约 ### YNX-0101 固化 builtin 协议信封与类型枚举 **目标** - 把 `PROTOCOL.md` 里的 builtin envelope 转成共享 TypeScript 类型 **子任务** - 定义 `BuiltinEnvelope` - 定义所有 builtin `type` 的联合类型 - 定义 payload 接口：`HelloPayload`、`PairRequestPayload`、`PairConfirmPayload`、`PairSuccessPayload`、`AuthRequestPayload`、`HeartbeatPayload` 等 - 统一 `timestamp` 使用 UTC unix seconds **产出** - `Yonexus.Protocol` 中的共享类型文件 **验收标准** - Server / Client 都能直接复用类型 - 所有 builtin 消息都可被类型系统约束 --- ### YNX-0102 实现协议编解码工具 **目标** - 提供统一的字符串协议解析与序列化能力 **子任务** - 实现 `encodeBuiltin(envelope)` - 实现 `decodeBuiltin(raw)` - 实现 rule message 的首段分隔解析 - 确保 message content 中包含 `::` 时不会被错误切碎 - 为 malformed message 提供标准错误 **验收标准** - `builtin::{json}` 可稳定双向转换 - `rule::content` 和 `rule::sender::content` 都能正确解析 --- ### YNX-0103 定义协议错误码与错误对象 **目标** - 统一错误语义，避免 Server / Client 各自发明错误格式 **子任务** - 定义协议错误码枚举 - 定义错误 envelope payload 结构 - 区分：配置错误、协议错误、认证错误、配对错误、运行时错误 **验收标准** - 所有失败路径都能落到有限集合的错误码 - 文档与代码错误码一致 --- ### YNX-0104 编写协议级测试样例 **目标** - 在实现运行时前，先锁定协议行为 **子任务** - 为 hello / pair / auth / heartbeat / error 编写样例用例 - 为 malformed、缺字段、错误 rule、保留字冲突编写反例 - 为 `::` 分隔边界编写测试 **验收标准** - 协议测试能独立运行 - 后续实现可直接拿这些样例做回归 --- ## Phase 2 — Server 插件脚手架 ### YNX-0201 创建 Yonexus.Server 最小插件骨架 **目标** - 让 Server 插件可被 OpenClaw 加载 **子任务** - 创建插件目录结构 - 创建 `package.json` - 创建 `openclaw.plugin.json` - 创建入口文件 `index.ts` - 添加基础构建配置 **验收标准** - 插件能被识别 - 启动时至少能加载但不报致命错误 --- ### YNX-0202 定义 Yonexus.Server 配置 schema **目标** - 让 Server 配置在启动前就能被校验 **子任务** - 校验 `followerIdentifiers` - 校验 `notifyBotToken` - 校验 `adminUserId` - 校验 `listenPort` - 校验 `listenHost` / `publicWsUrl` 可选字段 - 启动失败时返回明确错误 **验收标准** - 缺字段和非法字段会 fail fast - 错误信息足够定位问题 --- ### YNX-0203 实现 Server 生命周期 wiring **目标** - 在 gateway 启动时初始化 Server 内部组件 **子任务** - 初始化配置 - 初始化 registry - 初始化持久化层 - 初始化 rule registry - 注册 shutdown 清理逻辑 **验收标准** - 启停流程完整 - 不会留下悬挂 timer / socket --- ## Phase 3 — Client 插件脚手架 ### YNX-0301 创建 Yonexus.Client 最小插件骨架 **目标** - 让 Client 插件可被 OpenClaw 加载 **子任务** - 创建插件目录结构 - 创建 `package.json` - 创建 `openclaw.plugin.json` - 创建入口文件 `index.ts` - 添加基础构建配置 **验收标准** - 插件能被识别并加载 --- ### YNX-0302 定义 Yonexus.Client 配置 schema **目标** - 保证 Client 配置可启动前校验 **子任务** - 校验 `mainHost` - 校验 `identifier` - 校验 `notifyBotToken` - 校验 `adminUserId` - 规范 `mainHost` 是否允许裸 `host:port` **验收标准** - 配置错误可在启动时直接发现 --- ### YNX-0303 实现 Client 生命周期 wiring **目标** - 在 gateway 启动时初始化 Client 运行时 **子任务** - 加载本地状态 - 初始化连接管理器 - 初始化规则注册器 - 注册 shutdown 清理逻辑 **验收标准** - Client 可启动并在未连接状态下稳定运行 --- ## Phase 4 — 持久化与状态模型 ### YNX-0401 定义 Server 持久化记录结构 **目标** - 把 `PLAN.md` 中的 `ClientRecord` 落到代码 **子任务** - 定义 paired/unpaired/revoked/pending 状态 - 定义 heartbeat/liveness 字段 - 定义 pairing 通知字段 - 定义 recent nonce / recent attempts 窗口结构 - 定义 `createdAt` / `updatedAt` **验收标准** - 持久化结构足以支撑 pairing/auth/heartbeat --- ### YNX-0402 实现 Server 状态存储 **目标** - 让信任状态在重启后仍可恢复 **子任务** - 选择 JSON 文件或等价轻量持久化形式 - 实现加载、保存、原子写入 - 区分持久数据与内存态数据 - 明确 restart 后是否清空 rolling windows **验收标准** - 重启后 paired client 不丢失 - 损坏文件时有可恢复行为 --- ### YNX-0403 实现 Client 本地信任材料存储 **目标** - 持久化 Client 的 `identifier`、私钥、secret **子任务** - 定义本地 state 文件结构 - 实现加载 / 初始化 / 保存 - 缺失文件时自动初始化最小状态 - 标记敏感字段 **验收标准** - Client 重启后可恢复身份与 secret --- ## Phase 5 — Transport 最小闭环 ### YNX-0501 实现 Server WebSocket 启动与连接接入 **目标** - Server 能监听并接受连接 **子任务** - 启动 WebSocket server - 处理 connect / message / close / error - 记录连接与 identifier 绑定前的临时会话 **验收标准** - 可看到客户端连接进入 - 无协议时也不会崩 --- ### YNX-0502 实现 Client WebSocket 连接器 **目标** - Client 能主动连到 Server **子任务** - 建立 outbound 连接 - 处理 open / message / close / error - 提供连接状态机 **验收标准** - Client 能连上可用的 Server - Server 不可用时不会死循环刷日志 --- ### YNX-0503 实现 hello / hello_ack **目标** - 完成连接后的第一段协议握手 **子任务** - Client 连接后发送 `hello` - Server 验证 `identifier`、协议版本、payload 形状 - Server 返回 `hello_ack` - 根据状态决定 `nextAction` **验收标准** - 未配对客户端收到 `pair_required` - 已配对客户端收到 `auth_required` - 非 allowlist 客户端被拒绝 --- ### YNX-0504 实现基础重连策略 **目标** - Client 断线后可恢复连接 **子任务** - 设计退避策略 - 避免并发多次重连 - 在成功连接后重置退避计数 **验收标准** - 断线可自动恢复 - 不会形成高频重连风暴 --- ## Phase 6 — Pairing 主流程 ### YNX-0601 实现 Client 首次密钥生成 **目标** - Client 首次运行自动生成本地公私钥 **子任务** - 选定签名算法（建议 Ed25519） - 生成 keypair - 保存私钥 - 导出公钥供握手使用 **验收标准** - 首次启动可生成并持久化 keypair - 重启不会重复生成 --- ### YNX-0602 实现 Server pairing request 创建 **目标** - Server 可为待配对客户端创建 pairing 会话 **子任务** - 生成 pairing code - 生成 expiresAt / ttl - 将状态写入 registry - 更新 pairing 状态为 pending **验收标准** - 每次 pairing 会话有可验证的过期时间 - pairing code 不会通过 Yonexus WS 下发 --- ### YNX-0603 实现 Discord DM 配对通知 **目标** - Server 通过 `notifyBotToken` 向 `adminUserId` 发送 pairing code **子任务** - 封装 Discord DM 发送逻辑 - DM 内容包含 identifier、pairingCode、expiresAt/TTL - 处理发送失败 - 记录 pairing notification metadata **验收标准** - 通知成功时 Client 才能进入可确认状态 - 通知失败时不会继续配对成功路径 --- ### YNX-0604 实现 pair_request / pair_confirm / pair_success **目标** - 打通完整配对流程 **子任务** - Server 下发不含 code 的 `pair_request` - Client 接收并进入 pairing pending - Client 提交 `pair_confirm` - Server 校验 code 和 expiry - 成功后生成 secret - Server 返回 `pair_success` - Client 保存 secret **验收标准** - 正确 code 可完成配对 - 错误 code / 过期 code 会失败 --- ### YNX-0605 实现配对失败路径 **目标** - 补齐 pairing 相关失败逻辑 **子任务** - `invalid_code` - `expired` - `identifier_not_allowed` - `admin_notification_failed` - `internal_error` - 配对失败后的状态恢复策略 **验收标准** - 失败后不会留下脏状态导致后续无法重试 --- ## Phase 7 — Authentication 主流程 ### YNX-0701 固化 proof 构造与签名规范 **目标** - 明确签名输入，避免 Server / Client 不一致 **子任务** - 决定 canonical serialization 方案 - 明确签名字段：secret、nonce、timestamp - 定义签名编码格式（如 base64） **验收标准** - 同一输入在 Client 与 Server 上验证一致 --- ### YNX-0702 实现 Client auth_request **目标** - Client 能基于本地 secret 与私钥发起认证 **子任务** - 生成 24 字符 nonce - 生成 proofTimestamp - 构造签名 - 发送 `auth_request` **验收标准** - 报文字段完整 - nonce 格式符合协议要求 --- ### YNX-0703 实现 Server 认证校验 **目标** - Server 能验证 auth_request 真伪 **子任务** - 校验 identifier allowlist - 校验 paired 状态 - 校验 publicKey 匹配 - 校验 signature - 校验 secret - 校验 timestamp 漂移 - 校验 nonce 重放 - 校验 attempts 频率 **验收标准** - 正确认证返回 `auth_success` - 各类失败返回对应 `auth_failed` --- ### YNX-0704 实现 re_pair_required 机制 **目标** - 在不安全条件下强制重新配对 **子任务** - 检测 nonce collision - 检测 `>10 attempts / 10s` - 失效旧 secret 或标记 trust revoked - 返回 `re_pair_required` - Client 收到后切回 pairing_required **验收标准** - 不安全状态下不会继续接受旧信任材料 --- ## Phase 8 — Heartbeat 与在线状态 ### YNX-0801 实现 Client heartbeat loop **目标** - Client 在认证后按周期发心跳 **子任务** - 认证成功后启动 heartbeat timer - 断线或未认证时停止 timer - 发送 `heartbeat` **验收标准** - 默认每 5 分钟发送一次 - 状态切换时 timer 无泄漏 --- ### YNX-0802 实现 Server heartbeat 接收与记录 **目标** - Server 能更新客户端最近存活时间 **子任务** - 接收 heartbeat - 校验来源已认证 - 更新 `lastHeartbeatAt` - 可选返回 `heartbeat_ack` **验收标准** - 收到心跳后客户端状态可维持在线 --- ### YNX-0803 实现 Server liveness sweep **目标** - Server 能周期性评估 online / unstable / offline **子任务** - 增加 30~60s sweep timer - 7 分钟无心跳标记 unstable - 11 分钟无心跳标记 offline - offline 时发送 `disconnect_notice` 并断开连接 **验收标准** - 状态转移符合文档定义 --- ## Phase 9 — 规则消息与 API ### YNX-0901 实现 Client rule registry **目标** - Client 侧支持应用层规则分发 **子任务** - 实现 `registerRule(rule, processor)` - 禁止 `builtin` - 默认禁止重复注册 - 按 exact match 分发 **验收标准** - 命中规则时正确调用处理器 - 非法注册被拒绝 --- ### YNX-0902 实现 Server rule registry **目标** - Server 侧支持应用层规则分发 **子任务** - 实现 `registerRule(rule, processor)` - 禁止 `builtin` - 默认禁止重复注册 - 按 exact match 分发 **验收标准** - 规则注册与调用行为一致 --- ### YNX-0903 实现 `sendMessageToServer(message)` **目标** - 暴露 Client 到 Server 的发送 API **子任务** - 校验连接/认证状态 - 发送 `${rule_identifier}::${message_content}` - 未连接时返回明确错误 **验收标准** - 上层插件可直接调用 --- ### YNX-0904 实现 `sendMessageToClient(identifier, message)` **目标** - 暴露 Server 到指定 Client 的发送 API **子任务** - 校验目标 client 已知且在线 - 发送 `${rule_identifier}::${message_content}` - 离线时返回明确错误 **验收标准** - 上层插件可向指定客户端投递消息 --- ### YNX-0905 实现 Server 入站消息重写 **目标** - 把客户端来的消息重写成带 sender 标识的形式 **子任务** - 解析 `${rule_identifier}::${message_content}` - 重写为 `${rule_identifier}::${sender_identifier}::${message_content}` - 再进入 rule dispatch **验收标准** - Server 侧处理器能可靠识别消息来源 --- ## Phase 10 — 安全与鲁棒性 ### YNX-1001 实现敏感信息脱敏日志 **目标** - 避免 secret、私钥、proof 原文进入日志 **子任务** - 定义 redaction 工具 - 覆盖 pairing、auth、error 日志路径 - 对外只保留必要上下文 **验收标准** - 关键敏感值不会明文打印 --- ### YNX-1002 实现 malformed / unsupported / unauthorized 防御 **目标** - 所有非法输入都能被可控拒绝 **子任务** - malformed json - 缺字段 payload - unsupported protocol version - unauthorized identifier - 非法 builtin type **验收标准** - 错误不会导致进程崩溃 - 客户端能收到明确错误反馈或断开 --- ### YNX-1003 实现单 identifier 单活跃连接策略 **目标** - 同一 client identifier 只允许一个活跃认证连接 **子任务** - 定义旧连接替换策略 - 新连接成功认证后踢掉旧连接 - 避免竞态导致双在线 **验收标准** - 任意时刻同一 identifier 只有一个有效 session --- ### YNX-1004 实现重启恢复策略 **目标** - 重启后行为可预期且文档一致 **子任务** - 恢复 durable trust records - 清理或重建 rolling windows - 明确 pending pairing 如何恢复 - 明确 active connection 状态如何重建 **验收标准** - 重启后的认证/配对行为稳定可解释 --- ## Phase 11 — 测试与联调 ### YNX-1101 编写协议单元测试 **目标** - 覆盖编解码、字段校验、错误码 ### YNX-1102 编写 Server 单元测试 **目标** - 覆盖 registry、pairing、auth、heartbeat sweep ### YNX-1103 编写 Client 单元测试 **目标** - 覆盖状态机、keypair、auth 构造、heartbeat timer ### YNX-1104 编写 Server-Client 集成测试 **目标** - 覆盖首次配对、正常重连、认证失败、心跳超时、re-pair ### YNX-1105 编写失败路径测试矩阵 **目标** - 系统性覆盖 pairing/auth 失败路径 **重点场景** - pairing code 错误 - pairing 过期 - DM 发送失败 - stale timestamp - future timestamp - nonce collision - handshake rate limit - unknown identifier - duplicate connection **验收标准** - 核心安全路径都有自动化测试 --- ## Phase 12 — 文档与交付 ### YNX-1201 补齐 Server README **目标** - Server 仓库可独立被安装与使用 ### YNX-1202 补齐 Client README **目标** - Client 仓库可独立被安装与使用 ### YNX-1203 输出部署文档 **目标** - 写清楚单主多从部署方式、配置示例、配对流程 ### YNX-1204 输出运维排障文档 **目标** - 写清楚常见报错、状态含义、恢复步骤 ### YNX-1205 输出协议测试与验收清单 **目标** - 让后续改动有统一回归基线 --- ## 推荐执行顺序（最小闭环） ### Milestone A — 能启动 - YNX-0101 - YNX-0102 - YNX-0201 - YNX-0202 - YNX-0301 - YNX-0302 - YNX-0401 - YNX-0402 - YNX-0403 ### Milestone B — 能连接 - YNX-0203 - YNX-0303 - YNX-0501 - YNX-0502 - YNX-0503 - YNX-0504 ### Milestone C — 能配对认证 - YNX-0601 - YNX-0602 - YNX-0603 - YNX-0604 - YNX-0605 - YNX-0701 - YNX-0702 - YNX-0703 - YNX-0704 ### Milestone D — 能稳定通信 - YNX-0801 - YNX-0802 - YNX-0803 - YNX-0901 - YNX-0902 - YNX-0903 - YNX-0904 - YNX-0905 ### Milestone E — 能交付 - YNX-1001 - YNX-1002 - YNX-1003 - YNX-1004 - YNX-1101 - YNX-1102 - YNX-1103 - YNX-1104 - YNX-1105 - YNX-1201 - YNX-1202 - YNX-1203 - YNX-1204 - YNX-1205 --- ## 可直接开工的首批任务 如果要我给出“今天就能开始做”的第一批，我建议是： 1. YNX-0101 固化共享协议类型 2. YNX-0102 实现协议编解码工具 3. YNX-0201 创建 Yonexus.Server 插件骨架 4. YNX-0301 创建 Yonexus.Client 插件骨架 5. YNX-0401 定义 Server / Client 状态模型 6. YNX-0503 实现 hello / hello_ack 最小握手 这样最快能拿到一个“能启动、能连接、能判断下一步动作”的基础闭环。