Fabric/PLAN.md

Fabric 项目规划 v0.1

1. 项目目标

Fabric：一个可自部署的类 Discord 聊天系统，核心目标是提供稳定、低摩擦的沟通渠道。

MVP 成功标准

• 支持多人频道聊天 + 私聊
• 支持基础权限与审计日志
• 提供 Docker Compose 一键部署
• 单机可稳定服务 50~200 并发在线（MVP 目标）

2. 项目定位（一句话）

一个可自部署、类 Discord 的实时聊天系统；本体保持平台中立，通过插件生态对接外部系统。

3. MVP 必要功能

1. 账号与组织
   • 用户注册/登录（由中心服务负责）
   • Guild 归属到某个中心服务（非全局单体）
2. 聊天模型（明确范围）
   • Guild（工作区）
   • Channel（公开/私有频道）
   • DM（1v1 私聊）
   • 消息回复、编辑、删除、@提及
   • 附件、表情、引用
   • 不做 Thread（明确排除）
   • 不做已读回执（明确排除）
3. 实时通信
   • WebSocket 实时消息推送
   • 在线状态、输入中、消息同步
   • 客户端检测到消息序号断片时，通过 API 按 range 回补
4. 插件友好设计（本体中立）
   • 本体不内置 OpenClaw 专属逻辑
   • 提供稳定事件模型（消息创建/编辑/删除、成员事件、权限变更）
   • 提供清晰 API 边界（鉴权、幂等、分页、速率限制、错误码）
   • 为外部插件保留扩展点（Webhook、Bot Token、Outbound 回调）
5. 权限与审计
   • 当前策略：所有用户无权限差别，均可增删改查 guild/channel/dm/聊天记录
   • 审计日志保留时间/大小由每个 guild 自行配置

4. 建议技术栈（v0.1）

• API：NestJS（REST + WS）
• Realtime：WebSocket Gateway
• DB：PostgreSQL
• Cache/Queue：Redis（会话态 + 异步任务）
• Storage：MinIO（附件）
• Deploy：Docker Compose（app + pg + redis + minio）

4.1 部署与边界模型（新增决策）

• 采用“两套后端”模型：
  • 中心服务（Identity Hub）：管理用户身份与登录态
  • Guild 服务（Guild Node）：管理 Guild/Channel/DM/消息数据
• 一个中心服务可挂载多个 Guild 服务
• 不同中心服务彼此完全独立（A 的用户无法登录 B）
• 一个 Guild 服务只能注册到一个中心服务
• Guild 服务注册时需证明持有中心服务 secret（共享密钥握手）

5. 模块拆分（对应仓库）

• Fabric.Backend.Center
  • 用户身份与登录（Identity Hub）
  • Guild Node 注册与鉴权（共享密钥握手）
  • 中心级配置与审计
• Fabric.Backend.Guild
  • Workspace/Guild/Channel/DM
  • Chat Core（消息、回复、编辑、删除、@；不含 Thread）
  • Integration Surface（Webhook、Bot Token、扩展回调）
  • Guild 级权限与审计
• Fabric.Frontend
  • 工作区/频道 UI
  • 消息流、输入框、回复/编辑/删除/@
  • 平台中立 UI（不内置 OpenClaw 专属交互）
• Fabric.OpenclawPlugin
  • OpenClaw 侧适配与路由配置
  • 会话映射、回执状态、错误处理
  • 工具调用卡片与审批流（approve/reject）
  • Webhook + Gateway 双模式（MVP 先做 Webhook）
• Fabric.Desktop
  • Desktop 客户端壳（后续）
• Fabric.Android
  • Android 客户端壳（后续）

6. 里程碑（6 周参考）

注：OpenClaw 集成能力仅在 Fabric.OpenclawPlugin 实现，Fabric 本体不承担 OpenClaw 专属逻辑。

Week 1：需求冻结 + 架构设计

• PRD 冻结
• 架构图、数据模型、接口草案

Week 2：基础业务 API

• Center：登录注册、Guild Node 注册鉴权 API
• Guild：工作区、频道、消息 REST API
• 基础前端页面（频道列表 + 消息流）

Week 3：实时通信

• WebSocket 推送
• 在线状态、输入中、消息同步

Week 4：插件集成（在 Fabric.OpenclawPlugin）

• Agent 绑定配置
• 消息路由与回写
• 工具状态卡片（running/success/error）
• approve/reject 审批流

Week 5：权限与运维

• 角色权限（admin/member）
• 审计日志
• 健康检查、日志聚合、Compose 完善

Week 6：稳定性与发布

• 压测与性能调优
• Bug 修复
• MVP 发布文档与部署指南

7. 仓库组织

• Fabric（主仓库）
  • 挂载子模块：
    • Fabric.OpenclawPlugin
    • Fabric.Backend.Center
    • Fabric.Backend.Guild
    • Fabric.Frontend
    • Fabric.Desktop
    • Fabric.Android

7.1 消息编号与顺序语义（已定）

• 每个 Guild 服务为其管理的每个 Channel/DM 独立分配递增消息序号 seq（从 1 开始）
• 消息主键使用 message_id（UUID/ULID 均可），排序与断片检测以 seq 为准
• 服务端返回消息默认按 seq ASC
• 客户端允许短暂乱序显示，但收到 seq 断片时必须触发 range 回补
• 回补接口：GET /channels/:id/messages?seq_from=<a>&seq_to=<b>（DM 同理）
• 一致性目标：同一 Channel/DM 的最终可见顺序与服务端 seq 一致

7.2 插件扩展契约 v1（已定）

本契约为平台中立能力，Fabric.OpenclawPlugin 只是其中一个实现方。

A) 出站事件（Fabric -> Plugin）

• 采用 Webhook POST（MVP）
• 事件信封固定字段：
  • event_id（全局唯一）
  • event_type（如 message.created / message.updated / message.deleted）
  • occurred_at（ISO 时间）
  • guild_id / channel_id / actor_id
  • data（事件载荷）
• 鉴权：X-Fabric-Signature（HMAC-SHA256，密钥为每个插件独立 secret）
• 幂等：消费端以 event_id 去重

B) 入站调用（Plugin -> Fabric）

• 使用 Bot Token（Bearer）访问 Fabric API
• 写接口支持 Idempotency-Key，重复提交返回同一结果
• 标准错误码：
  • 400 参数错误
  • 401/403 鉴权或权限失败
  • 404 资源不存在
  • 409 冲突（如 seq 窗口不匹配）
  • 429 限流
  • 5xx 服务端错误

C) 重试与限流

• Webhook 非 2xx 视为失败，指数退避重试：1s / 2s / 4s / 8s / 16s（最多 5 次）
• API 限流采用令牌桶，返回 429 + Retry-After

8. 当前状态

• 所有仓库已创建为 Public
• Fabric.* 已作为子模块挂载到 Fabric
• 本体保持平台中立：不包含 OpenClaw 专属业务逻辑
• OpenClaw 相关能力集中在 Fabric.OpenclawPlugin
• 已确定：Guild 可分布在不同服务器；中心服务/ Guild 服务双层架构
• 已确定：消息顺序一致性细则、插件扩展契约 v1
• 本文件为第一版规划，后续按里程碑持续细化