nav/Yonexus
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
8c475f259aa28a833f9ce20a0beaae2f524f20d0
Yonexus/TASKLIST.md

23 KiB
Raw Blame History

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 协议信封与类型枚举

状态

  • 已完成（2026-04-08）

目标

  • 把 PROTOCOL.md 里的 builtin envelope 转成共享 TypeScript 类型

子任务

  • 定义 BuiltinEnvelope
  • 定义所有 builtin type 的联合类型
  • 定义 payload 接口：HelloPayload、PairRequestPayload、PairConfirmPayload、PairSuccessPayload、AuthRequestPayload、HeartbeatPayload 等
  • 统一 timestamp 使用 UTC unix seconds

产出

  • Yonexus.Protocol 中的共享类型文件

验收标准

  • Server / Client 都能直接复用类型
  • 所有 builtin 消息都可被类型系统约束

已完成内容

  • 已在 Yonexus.Protocol/src/types.ts 落地 BuiltinEnvelope、builtin type 联合类型、各类 payload 接口与 BuiltinPayloadMap
  • 已增加 Yonexus.Protocol/src/index.ts 作为导出入口
  • 已同步更新 Yonexus.Protocol/README.md，让共享类型入口不再停留在 planned 状态

YNX-0102 实现协议编解码工具

状态

  • 已完成（2026-04-08）

目标

  • 提供统一的字符串协议解析与序列化能力

子任务

  • 实现 encodeBuiltin(envelope)
  • 实现 decodeBuiltin(raw)
  • 实现 rule message 的首段分隔解析
  • 确保 message content 中包含 :: 时不会被错误切碎
  • 为 malformed message 提供标准错误

验收标准

  • builtin::{json} 可稳定双向转换
  • rule::content 和 rule::sender::content 都能正确解析

已完成内容

  • 已新增 Yonexus.Protocol/src/codec.ts
  • 已实现 encodeBuiltin / decodeBuiltin 及类型安全的 envelope builders
  • 已实现 parseRuleMessage / parseRewrittenRuleMessage / encodeRuleMessage / encodeRewrittenRuleMessage
  • 已提供 CodecError 标准错误类及辅助函数 isBuiltinMessage
  • 已更新 Yonexus.Protocol/src/index.ts 导出 codec 模块

YNX-0103 定义协议错误码与错误对象

状态

  • 已完成（2026-04-08）

目标

  • 统一错误语义，避免 Server / Client 各自发明错误格式

子任务

  • 定义协议错误码枚举
  • 定义错误 envelope payload 结构
  • 区分：配置错误、协议错误、认证错误、配对错误、运行时错误

验收标准

  • 所有失败路径都能落到有限集合的错误码
  • 文档与代码错误码一致

已完成内容

  • 已在 Yonexus.Protocol/src/types.ts 固化 ProtocolErrorCode 与 ErrorPayload
  • 已新增 Yonexus.Protocol/src/errors.ts，提供 YonexusProtocolError、错误分类映射、payload/envelope 转换辅助函数
  • 已更新 Yonexus.Protocol/src/index.ts 导出错误模块，方便 Server / Client 统一复用

YNX-0104 编写协议级测试样例

状态

  • 已完成（2026-04-08）

目标

  • 在实现运行时前，先锁定协议行为

子任务

  • 为 hello / pair / auth / heartbeat / error 编写样例用例
  • 为 malformed、缺字段、错误 rule、保留字冲突编写反例
  • 为 :: 分隔边界编写测试

验收标准

  • 协议测试能独立运行
  • 后续实现可直接拿这些样例做回归

已完成内容

  • 已新增 Yonexus.Protocol/tests/codec.test.ts
  • 已覆盖 encodeBuiltin/decodeBuiltin、parseRuleMessage/encodeRuleMessage、服务器重写消息解析/编码
  • 已包含 malformed message、非法 rule identifier、保留字冲突等反例
  • 已提供完整的 hello flow、rule message flow 示例
  • 已配置 package.json、tsconfig.json、vitest.config.ts 测试基础设施

Phase 2 — Server 插件脚手架

YNX-0201 创建 Yonexus.Server 最小插件骨架

状态

  • 已完成（2026-04-08）

目标

  • 让 Server 插件可被 OpenClaw 加载

已完成内容

  • 已补齐 plugin/、servers/、skills/、scripts/ 目录骨架
  • 已创建 package.json、tsconfig.json
  • 已写入 plugin/openclaw.plugin.json
  • 已补齐 wiring-only plugin/index.ts
  • 已补齐最小 scripts/install.mjs

验收标准

  • 插件能被识别
  • 启动时至少能加载但不报致命错误

YNX-0202 定义 Yonexus.Server 配置 schema

状态

  • 已完成（2026-04-08）

目标

  • 让 Server 配置在启动前就能被校验

子任务

  • 校验 followerIdentifiers
  • 校验 notifyBotToken
  • 校验 adminUserId
  • 校验 listenPort
  • 校验 listenHost / publicWsUrl 可选字段
  • 启动失败时返回明确错误

验收标准

  • 缺字段和非法字段会 fail fast
  • 错误信息足够定位问题

已完成内容

  • 已新增 Yonexus.Server/plugin/core/config.ts
  • 已实现 validateYonexusServerConfig() 与 YonexusServerConfigError
  • 已覆盖 followerIdentifiers、notifyBotToken、adminUserId、listenPort、listenHost、publicWsUrl 的基础约束与默认值处理
  • 已从 plugin/index.ts 导出配置类型与校验入口，方便后续 lifecycle wiring 复用

YNX-0203 实现 Server 生命周期 wiring

目标

  • 在 gateway 启动时初始化 Server 内部组件

子任务

  • 初始化配置
  • 初始化 registry
  • 初始化持久化层
  • 初始化 rule registry
  • 注册 shutdown 清理逻辑

验收标准

  • 启停流程完整
  • 不会留下悬挂 timer / socket

Phase 3 — Client 插件脚手架

YNX-0301 创建 Yonexus.Client 最小插件骨架

状态

  • 已完成（2026-04-08）

目标

  • 让 Client 插件可被 OpenClaw 加载

已完成内容

  • 已补齐 plugin/、servers/、skills/、scripts/ 目录骨架
  • 已创建 package.json、tsconfig.json
  • 已写入 plugin/openclaw.plugin.json
  • 已补齐 wiring-only plugin/index.ts
  • 已补齐最小 scripts/install.mjs

验收标准

  • 插件能被识别并加载

YNX-0302 定义 Yonexus.Client 配置 schema

状态

  • 已完成（2026-04-08）

目标

  • 保证 Client 配置可启动前校验

子任务

  • 校验 mainHost
  • 校验 identifier
  • 校验 notifyBotToken
  • 校验 adminUserId
  • 规范 mainHost 是否允许裸 host:port

验收标准

  • 配置错误可在启动时直接发现

已完成内容

  • 已新增 Yonexus.Client/plugin/core/config.ts
  • 已实现 validateYonexusClientConfig() 与 YonexusClientConfigError
  • 已覆盖 mainHost、identifier、notifyBotToken、adminUserId 的必填校验，并限定 mainHost 为 ws:// / wss://
  • 已从 plugin/index.ts 导出配置类型与校验入口，方便后续 lifecycle wiring 直接接入

YNX-0303 实现 Client 生命周期 wiring

目标

  • 在 gateway 启动时初始化 Client 运行时

子任务

  • 加载本地状态
  • 初始化连接管理器
  • 初始化规则注册器
  • 注册 shutdown 清理逻辑

验收标准

  • Client 可启动并在未连接状态下稳定运行

Phase 4 — 持久化与状态模型

YNX-0401 定义 Server 持久化记录结构

状态

  • 已完成（2026-04-08）

目标

  • 把 PLAN.md 中的 ClientRecord 落到代码

子任务

  • 定义 paired/unpaired/revoked/pending 状态
  • 定义 heartbeat/liveness 字段
  • 定义 pairing 通知字段
  • 定义 recent nonce / recent attempts 窗口结构
  • 定义 createdAt / updatedAt

验收标准

  • 持久化结构足以支撑 pairing/auth/heartbeat

已完成内容

  • 已新增 Yonexus.Server/plugin/core/persistence.ts
  • 已实现 ClientRecord、ClientSession、ServerRegistry 接口
  • 已实现 SerializedClientRecord、ServerPersistenceData 持久化结构
  • 已提供 createClientRecord、serializeClientRecord、deserializeClientRecord 工厂函数
  • 已提供 isPairable、hasPendingPairing、isPairingExpired、canAuthenticate 状态检查函数
  • 已更新 Yonexus.Server/plugin/index.ts 导出 persistence 模块

YNX-0402 实现 Server 状态存储

状态

  • 已完成（2026-04-08）

目标

  • 让信任状态在重启后仍可恢复

子任务

  • 选择 JSON 文件或等价轻量持久化形式
  • 实现加载、保存、原子写入
  • 区分持久数据与内存态数据
  • 明确 restart 后是否清空 rolling windows

验收标准

  • 重启后 paired client 不丢失
  • 损坏文件时有可恢复行为

已完成内容

  • 已新增 Yonexus.Server/plugin/core/store.ts，采用 JSON 文件作为 v1 持久化载体
  • 已实现 loadServerStore() / saveServerStore() 与 createYonexusServerStore()
  • 已使用 *.tmp + rename 的原子写入策略
  • 已在加载阶段校验文件结构，并在损坏/版本不匹配时抛出明确 corruption error
  • 已明确 rolling security windows 通过 deserializeClientRecord() 在重启后清空

YNX-0403 实现 Client 本地信任材料存储

状态

  • 已完成（2026-04-08）

目标

  • 持久化 Client 的 identifier、私钥、secret

子任务

  • 定义本地 state 文件结构
  • 实现加载 / 初始化 / 保存
  • 缺失文件时自动初始化最小状态
  • 标记敏感字段

验收标准

  • Client 重启后可恢复身份与 secret

已完成内容

  • 已新增 Yonexus.Client/plugin/core/state.ts
  • 已定义 YonexusClientState / YonexusClientStateFile，覆盖 identifier、privateKey、publicKey、secret 与关键时间戳
  • 已实现 loadYonexusClientState() / saveYonexusClientState() / createYonexusClientStateStore()
  • 已支持 state 文件缺失时自动创建最小初始状态
  • 已补充 hasClientSecret() 与 hasClientKeyPair()，方便后续 handshake wiring 判断本地信任材料是否齐备

Phase 5 — Transport 最小闭环

YNX-0501 实现 Server WebSocket 启动与连接接入

状态

  • 已完成（2026-04-08）

目标

  • Server 能监听并接受连接

子任务

  • 启动 WebSocket server
  • 处理 connect / message / close / error
  • 记录连接与 identifier 绑定前的临时会话

验收标准

  • 可看到客户端连接进入
  • 无协议时也不会崩

已完成内容

  • 已新增 Yonexus.Server/plugin/core/transport.ts
  • 已实现 YonexusServerTransport，支持 start/stop、send/broadcast、连接管理
  • 已实现临时连接追踪、已认证连接管理、单 identifier 单连接策略
  • 已更新 plugin/index.ts 导出 transport 模块

YNX-0502 实现 Client WebSocket 连接器

状态

  • 已完成（2026-04-08）

目标

  • Client 能主动连到 Server

子任务

  • 建立 outbound 连接
  • 处理 open / message / close / error
  • 提供连接状态机

验收标准

  • Client 能连上可用的 Server
  • Server 不可用时不会死循环刷日志

已完成内容

  • 已新增 Yonexus.Client/plugin/core/transport.ts
  • 已实现 YonexusClientTransport，支持 connect/disconnect/send
  • 已实现指数退避重连策略（max 10 次，1s~30s 退避）
  • 已实现心跳 timer 基础设施
  • 已更新 plugin/index.ts 导出 transport 模块

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 最小握手

这样最快能拿到一个“能启动、能连接、能判断下一步动作”的基础闭环。

Reference in New Issue View Git Blame Copy Permalink