167 lines
6.5 KiB
Markdown
167 lines
6.5 KiB
Markdown
# 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
|
||
- 本文件为第一版规划，后续按里程碑持续细化
|