Skip to content

PLAN.md

Latest commit

 

History

History
78 lines (58 loc) · 3.63 KB

PLAN.md

File metadata and controls

78 lines (58 loc) · 3.63 KB

Agent Handshake — 代码计划文档

一、目标

实现绕开中心化仓库、让两个本地 Agent 瞬间点对点连通的 WebSocket 路由服务器（MVP）。平台只做“信息传输”，不做计算；服务器作为信令/路由节点，维护「谁在哪个连接上」并转发带 target_id 的 JSON 消息。

二、技术选型与约束

项目 选择说明
语言/运行时 Node.js
WebSocket 库 ws（轻量、无框架）
地址 ws://localhost:8080（本地验证，暂不买服务器）
协议 JSON 消息体，含 target_id 等字段便于路由

约束：

  • 不引入复杂后端框架（Express/Fastify 等仅在有 HTTP 需求时再加）。
  • 首版不做鉴权、不做持久化，只做「连接注册 + 按 target 转发」。

三、目录结构

agent handshake/
├── PLAN.md              # 本计划文档
├── thought.txt          # 产品/构想来源
├── package.json         # 项目依赖与脚本
├── server/              # WebSocket 路由服务
│   ├── index.js         # 入口：创建 WebSocket 服务、连接管理、路由逻辑
│   └── router.js       #（可选）路由表与转发逻辑，便于后续扩展
├── docs/                # 设计/协议文档（后续补充）
└── clients/             #（后续）测试用简易客户端脚本

四、核心行为

  1. 连接建立

    • 客户端连接 ws://localhost:8080。
    • 服务端为每个连接分配唯一 agent_id（如 Agent-001），并可选择在连接时发送 { type: 'registered', agent_id } 给客户端。

  2. 路由表

    • 内存结构：Map<agent_id, WebSocket>（或 Map<agent_id, { ws, ... }>）。
    • 连接关闭时从表中移除。

  3. 消息转发

    • 收到文本帧且可解析为 JSON 时，读取 target_id（或等价字段）。
    • 若 target_id 在路由表中存在，则把该条消息原样转发给对应 WebSocket；否则可返回错误或忽略（由实现决定）。

  4. 消息格式（最小约定）

    • 至少包含：target_id（必填）、其余 payload 自由（如 event、payload 等，便于后续接 .ocl / skill_transfer）。
    • 示例：{ "target_id": "Agent-002", "event": "skill_transfer", "payload": { ... } }。

五、实现步骤（当前阶段）

  1. 建好文件夹（已完成：server/、docs/）。
  2. 编写计划文档（本文档）。
  3. 实现 WebSocket 路由服务器（server/index.js）：
    • 使用 ws 创建 WebSocketServer，监听 8080。
    • 维护 agent_id → WebSocket 的 Map。
    • 连接时分配 id 并回写；收到 message 时解析 JSON，按 target_id 转发；关闭时清理 Map。
  4. （可选） 在 package.json 中增加 npm run dev 或 node server/index.js 的启动脚本，便于本地跑通。

六、后续扩展（不做入本次 MVP）

  • 心跳/保活、断线重连策略。
  • 认证（Token / Trainer_ID）。
  • WSS（TLS）、部署到云服务器。
  • 与 OpenClaw 联机插件的对接（插件连本路由，收发 .ocl 包）。
  • 多房间/频道、广播等。

七、验收标准（MVP）

  • 启动服务后，两个测试客户端（如两个 wscat 或自写脚本）连上 ws://localhost:8080。
  • 各自收到服务端下发的 agent_id。
  • 客户端 A 发送 { "target_id": "<B 的 id>", "event": "ping", "payload": {} }，客户端 B 能收到该条消息。
  • 说明“点对点连通”已通过本路由服务器打通，可在此基础上接 OpenClaw 与 .ocl 协议。 SHA256:3/Jnf+mRKjchDrJmyuC/MbLM0TTAcnLpmCeumfSdPR0