Skip to content

README.zh.md

Latest commit

 

History

History
169 lines (128 loc) · 7.69 KB

README.zh.md

File metadata and controls

169 lines (128 loc) · 7.69 KB

OCTO OCTO

OCTO —— 为人和 AI Agent 协作而生的开源工作平台。
让 龙虾（Lobster / OpenClaw-powered digital double agents）去「思」和「行」，让人专注于「品」。

🏠 OCTO 主页 · 🚀 快速开始 · 📦 生态 · 🤝 贡献

License English

🌐 语言: English · 简体中文

OCTO Server（简体中文）

Go 后端 —— OCTO 平台的中心节点：REST + WebSocket API、龙虾 Agent 编排、WuKongIM 控制面。

octo-server 是 OCTO 平台的心脏。它向 octo-web 与 octo-admin 提供 REST 与 WebSocket 接口，负责业务编排与龙虾（Lobster / AI Agent）调度， 并通过 WuKongIM 驱动实时消息底座。

🌟 为什么选 OCTO Server

  • 整个平台只有一个锚点。 客户端、adapter、matter、summary、admin 最终都汇聚到 octo-server。你只需部署与扩展一个后端，其它组件都走它。
  • 龙虾编排是一等公民。 OpenClaw 驱动的数字分身的路由、会话、工具调用都原生内置，不是外挂。Agent 在会话里是一等参与者。
  • 存储与 IM 均可替换。 内置 MySQL 兼容的 SQL 迁移脚本与对象存储适配；WuKongIM 通过一个薄的控制面边界驱动，底座可替换。

🚀 快速开始

git clone https://github.com/Mininglamp-OSS/octo-server.git
cd octo-server
go build -o octo-server .
./octo-server --config ./configs/tsdd.yaml

默认 dev 配置期望本地存在一个 WuKongIM 实例与一个 MySQL 兼容的数据库。 参考仓库自带的 configs/tsdd.yaml 模板获取单二进制运行路径，配合 QUICKSTART.md 与 BUILDING.md 获取完整步骤。

若需要一键拉起完整 OCTO 栈（server + admin + web + matter + smart-summary

  • WuKongIM + MySQL + Redis + MinIO + nginx），请使用官方 OOTB 部署仓库 Mininglamp-OSS/octo-deployment。 本仓库原有的 docker/octo/ 与 docker/tsdd/ compose 栈已下线，统一收口 到 octo-deployment，避免两份独立维护带来的偏移。

📦 模块与架构

顶层结构：

路径 作用
cmd/ 服务入口（octo-server 与子命令）
internal/api/ REST + WebSocket handler —— 会话 / 用户 / 群组 / 文件 / 组织 / Webhook
internal/service/ 业务逻辑 —— 访问控制、龙虾编排、IM 扩散
internal/repository/ SQL + 缓存仓储（MySQL / Redis）
internal/im/ WuKongIM 控制面客户端（频道 / 消息 / 在线状态）
internal/agent/ 龙虾路由、会话存储、工具调用执行
internal/adapter/ Adapter 注册与下发入口
configs/ YAML 配置 schema 与 dev / prod 示例
migrations/ SQL 迁移脚本
docs/ 架构文档、API 参考、图表

每次请求 server 做的事：

  1. Authenticate（认证） —— token / cookie / DH 加密的 WebSocket 帧。
  2. Authorise（授权） —— 按组织的 RBAC、频道级 ACL、Agent 身份闸门。
  3. Execute（执行） —— 运行业务逻辑，必要时孵化或续接龙虾会话。
  4. Fan out（扩散） —— 通过 WuKongIM 下发 IM 消息；若频道需要外部桥接则触发对应 adapter。
  5. Respond（响应） —— 统一的 JSON 信封（或 WebSocket 帧），附带 tracing 与 metrics 标签。

🔗 OCTO 生态

graph TD
  subgraph Clients[客户端]
    Web[octo-web<br/>Web / PC]
    Android[octo-android<br/>Android]
    iOS[octo-ios<br/>iOS]
  end

  subgraph Core[核心服务]
    Server[octo-server<br/>后端 API]
    Matter[octo-matter<br/>任务 / Todo]
    Summary[octo-smart-summary<br/>AI 摘要]
    Admin[octo-admin<br/>管理后台]
  end

  subgraph Shared[共享库与集成]
    Lib[octo-lib<br/>核心 Go 库]
    Adapters[octo-adapters<br/>第三方适配器]
  end

  Web --> Server
  Android --> Server
  iOS --> Server
  Admin --> Server
  Server --> Matter
  Server --> Summary
  Server --> Adapters
  Server -.uses.-> Lib
  Matter -.uses.-> Lib
  Adapters -.uses.-> Lib
Loading
仓库 语言 职责
octo-server Go 后端 API · 业务编排 · 龙虾 Agent 调度
octo-matter Go 任务 / Todo / Matter 微服务
octo-smart-summary Go 基于 LLM 的会话摘要服务
octo-web TypeScript / React Web 与 PC（Electron）客户端
octo-android Kotlin / Java 原生 Android 客户端
octo-ios Swift / Objective-C 原生 iOS 客户端
octo-admin TypeScript / React 管理后台（租户 / 组织 / 用户 / 频道管理）
octo-lib Go 共享核心库（协议 / 加密 / 存储 / HTTP）
octo-adapters TypeScript / Python 第三方集成（IM 桥接、AI 渠道）

🧭 设计哲学

OCTO 遵循三条共用原则 —— 这套矩阵里的每个仓都一致：

  1. 本地优先（Local-first）。 能跑在用户本机的一切（对话、向量、智能体）都应尽量在本机完成。你的数据属于你；云是可选项，不是前置条件。
  2. 人做「品」，AI 做「思」与「行」。 人聚焦在品味（什么重要、什么对、该发什么）。龙虾（OpenClaw 驱动的数字分身）承担思考与执行。
  3. Release-as-product（每次发布即产品）。 每一次开源切片都是一个自洽的产品，不是代码倾倒：一个 release 一次 squash，Apache 2.0，不夹带内部包袱，单仓即可复现。

🤝 贡献

欢迎提 Pull Request！开 PR 前请先读：

安全问题请按 SECURITY.zh.md 上报，不要走公开 issue。

📄 许可

Apache License 2.0 —— 完整文本见 LICENSE，第三方致谢见 NOTICE。

🙏 致谢

octo-server 是以下项目的衍生作品：

完整的 Go 模块许可证清单与第三方致谢见 NOTICE。

由 OCTO Contributors 🐙 共同开发 · Mininglamp-OSS