典型应用场景

OCTO 文档中心 · 场景与案例

01-product/OCTO是什么.md v2.0
01-product/核心能力概览.md v2.0
02-architecture/OCTO总体架构.md v2.0
02-architecture/权限模型与鉴权体系.md v0.1
01-product/模块说明/各模块文档v0.3（Docs/Drive/Fleet/Marketplace/Speech/Summary/Search/我的）
03-deployment-ops/OCTO部署形态总览.md v1.1
03-deployment-ops/生产资源规格建议-v1.0.md v1.0
06-api-integration/Bot-API概览.md v0.4

OCTO 典型应用场景 v1.0

⚠️ 声明：本文档为基于 OCTO 产品能力推导的典型应用场景，非具体客户案例。售前使用时需结合客户实际需求调整，所有产品能力描述以知识库 active 级文档为准。未确认/私有仓部分已明确标注，不得作为承诺口径。

🔴 PS-06/PS-07纠偏（Round3源码确认）：①本文档所有人数档位（S/M/L/XL）均为经验估算，无官方证据，售前不得作为承诺报出，实际规模需压测；②OCTO的AI是平台能力（Bot/Expert/Squad/Skill编排框架），不是开箱即用办公助手——"自动写周报/做PPT/分析Excel"需要配置Expert/开发Skill实现，不是内置成品功能，售前不得把"能构建"说成"点一下就有"。

文档概述

#	场景	核心价值	推荐档位	部署形态	关键模块
1	企业内部 AI 协作办公平台	IM+文档+网盘+搜索+AI助手一体化，私有化数据安全	L 档起	K8s 多节点全模块	WuKongIM + octo-server + Docs + Drive + Search + Marketplace + Fleet
2	智能客服与 Bot 自动化平台	开放 Bot API + 卡片交互 + Webhook 集成，快速构建智能客服与业务自动化	M 档	Docker 单机 PoC 起步	octo-server + Bot API + Adaptive Cards + 文件服务
3	私有化 AI Agent 运行时平台	技能分发 + 多 Agent 协作编排 + 本地运行时，企业级 AI Agent 落地	L~XL 档	K8s 多节点	Fleet + Marketplace + Docs + daemon + CLI

场景一：企业内部 AI 协作办公平台

1.1 场景描述

1.2 客户痛点

痛点维度	具体表现
IM 碎片化	员工同时使用多个 IM 工具（微信/钉钉/飞书/Slack），消息分散在不同平台，信息无法统一检索和归档；外部工具无法私有化，敏感讨论存在合规风险
文档协作分散	文档散落在 Confluence/Notion/共享盘/本地文件夹，版本混乱、权限不清、协作效率低；文档更新无法及时同步给相关人员
AI 能力孤岛	各部门自行采购或搭建 AI 工具（ChatGPT/文心一言/自建模型），Prompt 和技能无法沉淀复用，AI 使用门槛高，数据散落在各 AI 平台
数据外泄风险	使用公有云 SaaS 工具（飞书/钉钉/企微/Slack），核心业务数据、客户信息、技术文档存储在第三方服务器，无法满足等保/数据安全合规要求
知识检索困难	历史消息、文档、文件无法统一搜索，找信息靠翻聊天记录、问人，新人上手成本高，组织知识无法有效沉淀
移动端效率低	外出/通勤时输入不便，语音消息无法快速转文字；群聊信息量大，无法快速获取关键内容

1.3 OCTO 能力对应

客户需求	OCTO 能力	能力说明
统一即时通讯	IM 消息 + 群组 + Thread 讨论	实时消息（文本/Markdown/富文本/图片/文件/语音）、群组管理、子区 Thread 话题讨论；支持已读回执、消息编辑撤回；Web/iOS/Android/PC 全端覆盖
实时文档协作	Docs 文档协同	基于 Tiptap + Yjs CRDT 的多人实时协同；5 类文档表面（富文本/表格 Sheet/白板 Board/HTML/PPT）；docx/Markdown 双向导入导出；评论分级、版本历史、两版本对比恢复
企业文件管理	Drive 企业网盘	个人空间 + 共享空间两级管理；文件上传/下载/分享（支持组织外访问，即Space外访问）；聊天文件一键转存网盘；云文档挂载统一访问
全库知识检索	Search 全文搜索	Kafka + OpenSearch（IK 中文分词）三层管道；覆盖消息全文、文档正文、网盘文件正文（Apache Tika 提取）；权限控制 + Bot OBO 搜索；高亮 + cursor 分页
语音效率提升	Speech 智能语音	语音输入（全端支持，Web 端语音编辑模式）+ 语音消息自动转写（@mention 识别、口语化书面语优化、情感 emoji 标注）；4 种转写引擎自动降级
会话智能总结	Summary 智能摘要	手动一键总结 / 定时日周月自动总结 / Agent 驱动触发；按群/按人模式，24h/7d/30d 时间范围；map-reduce 处理长会话，SSE 流式返回
AI 助手集成	AI Bot 助手（龙虾/Lobster）	Agent 作为会话一等参与者；@Agent 派发任务；通过 openclaw-channel-octo 插件接入自建/第三方 Agent；Bot 可通过评论区 @Mention 操作文档
技能复用扩展	Marketplace 技能市场	技能包 + 专家 + 插件分发市场；企业可发布内部技能供全员安装使用；MCP 连接器形态接入外部工具
数据安全可控	私有化部署 + 角色体系 + SSO	全栈私有化部署（数据不出内网）；Space 级逻辑隔离；OIDC SSO 对接企业 IdP；Space成员/群/系统三层角色体系（硬编码枚举，无自定义RBAC）

1.4 适用客户类型

维度	说明
客户规模	中大型企业（200~500 人起）、政企单位、有数据安全合规要求的组织
行业特征	金融、政府、军工、能源、制造业等对数据主权有强要求的行业；研发密集型企业（需要文档协作 + 知识管理）
核心诉求	替代/补充现有公有云协作工具，实现"IM + 文档 + 网盘 + 搜索 + AI"一体化私有化协作平台
IT 基础	具备 K8s 运维能力或愿意接受明略交付服务；有内网 LLM 或可访问外部 LLM API（摘要/语音功能依赖）

1.5 推荐部署档位

项目	建议
推荐档位	L 档（200~500 人，16 核 / 32 GiB / 500 GiB SSD 起步）
部署形态	Kubernetes 多节点部署（3 节点起步）；核心 7 件套 + 全内部模块
基础设施	MySQL 8 / Redis 7 / MinIO（或 S3 兼容存储如 COS/OSS）/ WuKongIM 必选；Kafka + OpenSearch 搜索基础设施按需；Fleet PostgreSQL（启用回路时）
可降级方案	50~200 人 M 档可先用 Docker Compose 单机（8 核 / 16 GiB / 200 GiB SSD），后续迁移 K8s

1.6 核心模块清单

模块	归属	必选/可选	功能	Profile 开关
WuKongIM	开源（必选底座）	✅ 必选	IM 长连接底座（WS/TCP），消息持久化与推送	默认启动
octo-server	开源（核心）	✅ 必选	单体 Go 后端，聚合消息/群/Thread/Bot/卡片/用户/文件等 40+ 模块	默认启动
octo-web	开源（必选）	✅ 必选	Web/PC 客户端（Electron），用户主入口	默认启动
octo-admin	开源（必选）	✅ 必选	管理后台（空间管理/后台管理）	默认启动
MySQL 8	必选基础	✅ 必选	主数据存储（octo 库 + 各模块独立库）；字符集 utf8mb4	默认启动
Redis 7	必选基础	✅ 必选	缓存/会话/限流/bot_task 队列/幂等	默认启动
MinIO / S3	必选基础	✅ 必选	对象存储（13 个 bucket，消息附件/文档/网盘/头像等）；可替换为 COS/OSS/AWS S3	默认启动
Docs（文档协同）	内部版	✅ 必选	Tiptap+Yjs 实时协同，5 类表面，评论@Bot，版本历史	`docs` + `docs-html`
Drive（企业网盘）	内部版	✅ 必选	个人+共享空间，聊天转存，云文档挂载，分享	`drive`
Search（全文搜索）	内部版	✅ 必选	Kafka+OpenSearch+IK 分词三层管道，消息+文档+网盘三类索引	`search` + `doc-index` + `drive-index`
Summary（智能摘要）	内部版	⚙️ 推荐	消息/会话智能总结（手动/定时/Agent 触发）；需 LLM API	`summary`
Speech（智能语音）	内部版	⚙️ 推荐	语音输入 + 语音消息转写，4 引擎降级；需 ASR API Key	`speech`
Marketplace（技能市场）	内部版	⚙️ 推荐	技能包/专家/插件分发；docker 默认启动	默认启动
Fleet/Loop（回路）	内部版	⚙️ 可选	AI 协作项目管理+本地运行时；需 PostgreSQL 16	`fleet` + `fleet-db`
nginx	必选	✅ 必选	两层路由（薄网关 + 厚应用），单端口对外，TLS 终结	默认启动

模块启动顺序建议：核心 7 件套 → smoke-test 通过 → summary → speech → docs + docs-html → drive → fleet → search → doc-index → drive-index。详见 [03-deployment-ops/OCTO部署形态总览.md §3.5.3](../03-deployment-ops/OCTO部署形态总览.md)。

1.7 部署形态建议

                    客户端（Web/iOS/Android/PC）
                              │
                    TLS 终结（反向代理/Ingress）
                              │
                    nginx（单端口 :443/:80）
                       ├─ /ws → WuKongIM（IM 长连接）
                       ├─ /docs-collab → docs-backend（Hocuspocus WS）
                       └─ 厚路由 → 各后端服务
                              │
          ┌───────────┬───────┼───────┬───────────┐
          ▼           ▼       ▼       ▼           ▼
     octo-server   docs    drive   summary    fleet
     (单体Go)    backend  :8080   api/wkr    :8080
      :8090       :3000                      │
          │                                   ▼
          │                            PostgreSQL 16
          │                            (Fleet 专用)
          ├──────────────────────────────────┐
          │                                  │
          ▼                                  ▼
   ┌─────────────┐                   ┌──────────────┐
   │   MySQL 8   │                   │  Redis 7     │
   │ (多库)       │                   │ (DB0+DB1)    │
   └─────────────┘                   └──────────────┘
          │                                  │
          ▼                                  ▼
   ┌─────────────┐                   ┌──────────────┐
   │ MinIO/S3    │                   │ Kafka+OS     │
   │ (13 bucket) │                   │ (搜索管道)    │
   └─────────────┘                   └──────────────┘

MinIO 是存储增长主力（消息附件 + 文档附件 + 网盘文件），建议初始 300 GiB 起，设置 70% 使用率告警
OpenSearch 索引约为原始文本的 1.5~3 倍，消息+文档+网盘三类索引初始 100 GiB 起
MySQL 文本消息增长约 1~3 KB/条，增长缓慢

1.8 售前注意事项（硬口径提醒）

🔴 以下为售前必须明确告知客户的产品边界，不得模糊或夸大：

安全与权限

序号	硬口径	说明
1	🔴 无自定义 RBAC	权限角色为代码硬编码枚举（Space 三档：member/admin/owner；群三档：普通/群主/管理员；系统四档：admin/superAdmin/dashboardReader/marketAdmin），不支持"自定义角色""细粒度权限点配置""可视化权限矩阵"。`marketAdmin` 源码注释明确写着 `"before general manager RBAC exists"`。
2	🔴 多租户为同库逻辑隔离	所有 Space 数据存于同一数据库实例、同一套表、同一套 OpenSearch 索引，通过 `space_id` 字段查询层过滤实现隔离。不是独立数据库/Schema/物理隔离。政企/金融强合规场景需采用"一客户一部署实例"方案。
3	🔴 SSO 仅支持 OIDC/OAuth2，不支持 SAML/LDAP 直连	原生支持标准 OIDC/OAuth2 授权码流，可对接 Google/Okta/Keycloak/Azure AD/Auth0 等。SAML 和 LDAP/AD 需通过 Keycloak 等 IdP 做协议桥接，不承诺原生开箱即用。不支持企微/钉钉/飞书扫码登录独立集成，不支持 SCIM 自动 provisioning。
4	无 organization 层级	顶层租户单元是 Space，不存在"组织→多 Space"层级结构。Space = organization = workspace。
5	权限变更最长 60s 缓存延迟	Space 成员资格缓存 60s TTL，高安全场景需评估。

功能边界

序号	硬口径	说明
6	🔴 网盘 Drive 仅 Web 端可用	iOS/Android 未实现网盘功能，移动端无法使用企业网盘。
7	🔴 回路 Loop/Fleet 仅 Web 端可用	移动端确认无回路功能（`dmloop_on` 未实现）。
8	语音模块是 ASR 转写，不是音视频会议	支持语音输入和语音消息转写（最大 60 秒/3MB），不支持实时通话/音视频会议/实时字幕/会议转写。TTS（语音合成）能力待验证，不做承诺。
9	不承诺性能 SLA	当前无官方性能基准数据（QPS/并发数/搜索延迟等），不得承诺具体性能数值。资源规格为经验推算，需实际压测验证。
10	删号无 GDPR 导出功能	当前无用户数据导出（GDPR right to data portability）功能，有合规需求的客户需走定制。
11	文档协同模块在演进中	具备 5 类表面基础能力，但与 Notion/Confluence 数十年积累的模板/数据库/插件生态相比仍在演进中，更适合"IM 原生协作文档"定位，非独立企业 Wiki 全套替代品。
12	搜索基础设施额外资源开销显著	Kafka + OpenSearch + indexer 三个组件合计约 8 核/12 GiB/200 GiB（L 档），需在资源规划时预留。首次启用需执行 search-upgrade.sh 初始化索引，不会自动回溯。

部署运维

序号	硬口径	说明
13	生产环境必须修改默认密码和 Token	OOTB 部署的 preflight 容器会拦截 `CHANGE_ME_*` 占位凭据，但仍需逐项确认密钥强度。Redis Docker 栈默认无密码，必须设置。
14	OpenSearch/Kafka 默认无认证	Docker 栈 `DISABLE_SECURITY_PLUGIN=true`，Kafka PLAINTEXT，生产环境必须启用安全配置。
15	摘要/语音依赖外部 LLM/ASR API	summary 默认调用 claude-sonnet-4-6，speech 默认 qwen，需客户提供可用的 LLM/ASR API Key 或内网部署模型。内网/离线场景需额外对接方案。

场景二：智能客服与 Bot 自动化平台

2.1 场景描述

2.2 客户痛点

痛点维度	具体表现
客服响应慢	人工客服排队时间长，常见问题重复回答，客服人力成本高，7×24 小时覆盖困难
Bot 编排困难	自建 Bot 平台需要处理消息通道、用户管理、权限鉴权、卡片渲染、多端适配等大量基础设施工作，开发周期长
系统集成复杂	客服 Bot 需要对接 CRM/工单/知识库/订单系统等多个后端，缺乏统一的消息出入口和事件回调机制
交互体验差	纯文本 Bot 无法承载表单、按钮、进度展示等丰富交互，用户体验差，业务流程无法闭环
多轮会话追踪困难	跨群/跨人/跨时段的会话上下文管理复杂，Bot 难以维护长期对话状态

2.3 OCTO 能力对应

客户需求	OCTO 能力	能力说明
开放 Bot 接入	*Bot API（/v1/bot/\）**	完整 REST API，Bearer bot_token 鉴权；支持发消息、编辑消息、群/Thread 管理、文件上传下载、typing 指示、已读回执
丰富消息交互	Adaptive Cards 交互卡片	展示卡、交互卡（Action.Submit 按钮回调）、进度卡、模板卡；能力探测自动降级；HMAC 签名回调保障安全
事件接收	HTTP 长轮询事件机制	Bot 通过 `POST /v1/bot/events` 长轮询接收消息/卡片回调等事件（cursor + ACK，at-least-once 投递）；另有出站 Webhook（HMAC-SHA256 签名）支持服务端事件推送
系统集成	Webhook + Incoming Webhook	出站 Webhook 接收 IM 事件回调（HMAC 签名），Incoming Webhook 支持外部系统单向推消息进群/子区（支持 GitHub/GitLab/企微/飞书等格式）
文件能力	文件上传/下载	Presigned URL 直传 S3/MinIO（不塞 base64），支持图片/文件/语音/视频；默认单文件 100MB；扩展名+魔数校验
用户身份集成	OBO 代用户操作	Bot 经用户授权后可代用户发送消息、搜索消息（OBO token，`obo_*` 前缀），实现"以用户身份"操作
动态消息更新	消息编辑 + 动态改卡	Bot 可编辑自己发的消息（`/v1/bot/message/edit`），实现进度更新、状态变更等动态卡片效果
@提及与群管理	@提及 + 群/Thread 管理	消息中 @用户/@Bot 触发事件；Bot 可创建群、拉人/踢人、设置群公告；Thread 子区全套 9 个管理端点
OAuth 授权	OpenAPI OAuth 授权码流	第三方应用通过标准 OAuth 授权码流以用户身份接入 OCTO

2.4 适用客户类型

维度	说明
客户规模	中小企业到中大型企业均可，PoC 阶段小团队即可启动
行业特征	需要客服自动化的行业（电商/金融/互联网）、IT 服务台、HR/行政内部服务 Bot、业务流程自动化场景
核心诉求	快速搭建智能客服/业务 Bot，与现有系统集成，降低人工成本，提升响应效率
IT 基础	有 Bot 开发能力（Node.js/Python/Go 等），现有业务系统可提供 REST API 供 Bot 调用

2.5 推荐部署档位

项目	建议
推荐档位（PoC/小规模）	M 档（50~200 人，8 核 / 16 GiB / 200 GiB SSD），Docker Compose 单机起步
推荐档位（生产）	视用户规模升级到 L 档 K8s 多节点；若仅作为 Bot 消息平台（不作为全员协作平台），M 档 Docker 单机可支撑中小规模客服场景
部署形态	Docker 单机 PoC → 验证通过后迁移 K8s；核心 7 件套 + Bot 相关能力即可，文档/网盘/回路等模块可暂不启用
必选基础设施	MySQL 8 / Redis 7 / MinIO / WuKongIM（核心 7 件套最小集）

2.6 核心模块清单

模块	归属	必选/可选	功能	Profile 开关
WuKongIM	开源（必选底座）	✅ 必选	IM 长连接，消息路由与推送	默认启动
octo-server	开源（核心）	✅ 必选	Bot API 全路由 + 消息/群/Thread/文件/卡片/Webhook	默认启动
octo-web	开源	✅ 必选	Web 客户端，用户与 Bot 交互入口	默认启动
octo-admin	开源	✅ 必选	管理后台，Bot 创建与管理（BotFather）	默认启动
MySQL 8	必选基础	✅ 必选	Bot/消息/用户/群数据	默认启动
Redis 7	必选基础	✅ 必选	bot_task 队列（DB0）/ 幂等去重 / 限流 / 缓存	默认启动
MinIO / S3	必选基础	✅ 必选	Bot 上传/发送的文件存储（chat/file bucket）	默认启动
nginx	必选	✅ 必选	反向代理 + 路由 + TLS	默认启动
Adaptive Cards	开源（内置）	✅ 必选	交互卡片渲染与回调（octo-server 内置 carddispatch）	默认启动
文件服务	开源（内置）	✅ 必选	Presigned URL 直传/下载，魔数校验	默认启动
Summary（智能摘要）	内部版	⚙️ 可选	Bot 可触发/引用会话总结（客服场景可用于自动生成对话摘要）	`summary`
Speech（语音转写）	内部版	⚙️ 可选	语音消息自动转文字（客服可自动处理语音咨询）	`speech`
Search（全文搜索）	内部版	⚙️ 可选	Bot OBO 搜索历史消息（`POST /v1/botfather/messages/search`）	`search`

注意：此场景下 Docs/Drive/Fleet/Marketplace 等内部模块非必需，可根据客户需求选择性启用，降低部署复杂度和资源消耗。开源版核心 7 件套已包含完整 Bot API 能力。

2.7 部署形态建议

              用户（Web/移动端）        Bot 开发者/业务系统
                    │                         │
                    ▼                         ▼
              nginx（单入口）          Bot 事件接收 + API 调用
                    │                    (长轮询 /v1/bot/events)
                    ▼                         │
              octo-server ◄───────────────────┘
              :8090
              ├─ bot_api 模块（API 路由 + 鉴权 + 限流）
              ├─ bot_task 模块（Redis 队列 + 幂等）
              ├─ carddispatch（卡片渲染 + 回调）
              ├─ webhook/incoming（系统集成）
              └─ message/group/thread/file
                    │
          ┌─────────┼─────────┐
          ▼         ▼         ▼
      WuKongIM    MySQL 8   Redis 7
      (IM底座)   (数据)    (队列/缓存)
                    │
                    ▼
                 MinIO/S3
               (文件存储)

2.8 售前注意事项（硬口径提醒）

🔴 以下为 Bot 场景售前必须明确告知的技术限制，开发团队需在设计阶段知晓：

Bot 事件与通信

序号	硬口径	说明
1	🔴 Bot 事件接收方式是 HTTP 长轮询，不是 WebSocket	Bot 通过 `POST /v1/bot/events` 长轮询拉取事件（cursor + ACK，at-least-once 投递），不提供 per-bot WebSocket 推送。出站 Webhook 是平台级 `/v1/webhook`、`/v2/webhook`（HMAC-SHA256 签名），不是 Bot 独占通道。
2	🔴 Bot Token 前缀区分两类 Bot	`bf_` 前缀 = User Bot（可入群，群聊 Bot 主力）；`app_` 前缀 = App Bot（仅 DM 私聊，完全拒绝群端点）。开发者容易混淆，接入前务必确认 Bot 类型。
3	🔴 Bot 收不到 reaction 事件	当前 Bot 事件中不包含表情回应（reaction）事件，如需此能力需走产品规划。
4	Bot 收不到成员变动事件	群成员加入/退出等事件是否推送给 Bot，当前无明确文档支持，不做承诺。
5	🔴 App Bot 仅支持 DM（私聊）	`pkg/authtree/authtree.go` 对 App Bot 调用群相关 API 直接拒绝，App Bot 只能发私聊消息，不能进群。群聊场景必须使用 User Bot（`bf_`）。

OBO 与循环防护

序号	硬口径	说明
6	🔴 OBO（代发）三重防循环机制	Bot 代用户发消息时需注意避免无限循环（Bot 发消息 → 触发事件 → Bot 再处理 → 再发消息）。OCTO 有防循环机制，但 Bot 侧也必须设计幂等和循环检测。
7	消息发送为单目标单条	`sendMessage` 无批量/多目标字段，一次只能给一个 channel 发一条消息。
8	Bot 只能编辑自己发的消息	`/v1/bot/message/edit` 仅允许编辑 Bot 自己发出的消息，不能编辑其他用户/Bot 的消息。

API 与权限

序号	硬口径	说明
9	🔴 无标准 OAuth2 scope 体系	App Bot 只有 `platform`（全平台）/ `space`（单 Space）两档粗粒度 scope，没有"只读消息""只发消息""管文件不管用户"等细粒度权限控制。OBO token 权限等同于被代理用户+应用授权上下文，也非标准 scope 矩阵。
10	Bot 是普通群成员，非超管	Bot 加入群后是普通成员身份，不是全局管理员；不能跨群操作，`GET /v1/bot/groups` 只返回 Bot 自己加入的群。
11	Bot 无 Space 座位	Bot 不占 `space_member` 行，不占用"人头数"，通过 token scope + authtree 路由守卫获得访问权。
12	无 OpenAPI/Swagger 规范文件	octo-server 仓库没有 openapi.yaml/json/swagger 规范文档，API 对接需参考 Bot-API 概览文档和源码。
13	限流三桶	按 bot 身份分桶：business（业务主配额）/ heartbeat（保活独立配额）/ register（换 token），具体阈值可配置但无公开默认值承诺。

文件与卡片

序号	硬口径	说明
14	文件上传走 Presigned URL，不塞 base64	文件类消息（type=8）需先请求 presigned URL 直传 MinIO/S3，再发送消息引用 URL；默认单文件 100MB。
15	卡片需做能力探测	发送交互卡片前建议调用 `GET /v1/bot/card/profile` 探测客户端能力，不支持时自动降级纯文本。

场景三：私有化 AI Agent 运行时平台

3.1 场景描述

3.2 客户痛点

痛点维度	具体表现
AI Agent 部署困难	每个 Agent 需要单独配置运行环境、API Key、依赖库，部署和维护成本高；Agent 升级和版本管理缺乏统一机制
技能分发无体系	Agent 的技能包（Skills）、Prompt 模板、工具配置分散在各开发者本地，无法统一分发、版本管理、安装升级；新员工/新 Agent 无法快速获取已有技能
多 Agent 协作缺乏编排	复杂任务需要多个 Agent 协作（如"研究员+写手+审核员"流水线），但缺乏统一的任务派发、状态追踪、结果验收机制；Agent 之间无法有效协作
本地运行时安全	Agent 需要访问本地文件系统、执行命令、操作开发工具，但缺乏安全沙箱、权限管控、审计日志；云端 Agent 无法访问本地资源（代码仓库/内部系统/本地文件）
审批与治理缺失	Agent 执行敏感操作（删除文件、发送消息、调用生产 API）缺乏人工审批环节，存在误操作风险；Agent 的行为无法审计和回溯
移动端无法运行 Agent	Agent 通常需要 PC/服务器环境运行，移动端无法管理和监控 Agent 执行状态

3.3 OCTO 能力对应

客户需求	OCTO 能力	能力说明
技能分发与管理	Marketplace 技能/专家市场	技能包（Skill）、专家（Expert）、专家团（Expert Team/Squad）的分发市场；支持浏览/安装/评分/自动审核策略；MCP 以连接器形态接入；安装技能包=给专家分配技能，自动去重/失败重试
多 Agent 协作	Expert（专家）+ Expert Team（专家团/Squad）	专家 = 跑在 runtime/daemon 上的 AI 协作体；专家团 = 多个专家组成的协作组（如 Squad leader 统筹 + member 分工）；支持在回路中派任务给专家/专家团执行
AI 项目管理	Loop 回路	任务→助理整理为结构化 Issue→派发给专家/专家团→执行→用户验收→归档/退回的完整闭环；类似 Linear/Jira 的 AI-native 版本；支持语音/文字发起任务
运行时编排	Fleet 运行时管理服务	独立 Go 服务，负责 Daemon 注册/心跳、Bot 编排置备（managed_bots）、运行时清单管理（哪个 daemon 上跑哪些 Agent）；与 matter 协同任务分发
本地设备执行	octo-daemon 本地运行时	用户本地电脑上的 npm 包；自动检测本地 AI Agent CLI（Claude Code / Codex / OpenClaw / Hermes）；WebSocket 长连接连到 Fleet；上报本地 Agent 状态；执行回路任务；支持一键远程升级
CLI 工具链	Loop CLI（octo-daemon 内置）	命令行工具支持回路操作；可从运行时导入技能到云端工作区
人工审批	回路验收机制	任务执行完成后需用户验收（通过/退回），形成人在回路（Human-in-the-loop）的安全闸门
文档协作	Docs 文档协同	Agent 执行结果可输出为云文档（富文本/HTML 报告）；用户在文档中评论 @Bot 触发继续执行

3.4 适用客户类型

维度	说明
客户规模	中大型企业（200 人起）、AI 研发团队、软件研发团队、知识工作密集型组织
行业特征	科技公司/AI 实验室（AI Agent 研发与应用）、咨询/法律/金融（知识密集型工作流）、软件研发团队（AI 辅助编码/代码审查/文档生成）
核心诉求	构建企业级 AI Agent 基础设施，实现技能沉淀复用、多 Agent 协作编排、本地安全执行、人在回路审批
IT 基础	具备 K8s 运维能力；员工 PC 可安装 npm 包（octo-daemon）；有内网 LLM 能力或可访问外部 LLM API

3.5 推荐部署档位

项目	建议
推荐档位	L 档~XL 档（经验估算，🔴无官方证据，不得作为承诺报出，实际需压测），L 档 16 核 / 32 GiB / 500 GiB SSD 起步；Agent 并发量大时上 XL 档
部署形态	Kubernetes 多节点部署（3~5 节点）；Fleet + Marketplace + Docs 为核心模块；基础设施建议独立部署（MySQL/Redis/PG/OS）
额外基础设施	PostgreSQL 16（Fleet 专用，OCTO 内部唯一使用 PG 的模块）；Redis DB 1（Fleet 专用）；Kafka + OpenSearch（技能搜索/文档索引）
客户端要求	用户 PC 需安装 Node.js（npm 安装 octo-daemon），支持 macOS/Linux/Windows（具体平台支持待确认）

3.6 核心模块清单

模块	归属	必选/可选	功能	Profile 开关
WuKongIM	开源（必选底座）	✅ 必选	IM 长连接，消息/通知推送	默认启动
octo-server	开源（核心）	✅ 必选	用户认证/消息/群/Bot API/Webhook/与 Fleet 集成	默认启动
octo-web	开源（必选）	✅ 必选	Web 客户端（回路入口/专家市场/运行时管理）	默认启动
octo-admin	开源（必选）	✅ 必选	管理后台	默认启动
MySQL 8	必选基础	✅ 必选	octo 主库 + marketplace 库 + docs 库	默认启动
Redis 7	必选基础	✅ 必选	DB0（缓存/队列）+ DB1（Fleet 专用）	默认启动
MinIO / S3	必选基础	✅ 必选	marketplace bucket（技能包资源）+ 文档附件 bucket	默认启动
Fleet（运行时管理）	内部版	✅ 必选	Daemon 注册/心跳/Bot 编排/运行时清单/任务分发	`fleet`
Fleet PostgreSQL	内部版	✅ 必选	Fleet 专用数据存储（唯一使用 PG 的模块）	`fleet-db`（内置）或外部 PG
Marketplace（市场）	内部版	✅ 必选	技能包/专家/专家团/插件分发市场	默认启动（docker）/ helm 需启用
Docs（文档协同）	内部版	✅ 必选	Agent 输出文档（HTML 报告/富文本文档）、评论@Bot 链路	`docs` + `docs-html`
octo-daemon	本地运行时	✅ 必选	用户本地 PC 上的运行时载体（npm 包），检测本地 AI Agent CLI，WS 连 Fleet	用户本地安装
nginx	必选	✅ 必选	Fleet WS 路由 + 市场 API 路由 + 文档 WS 路由	默认启动
Search（全文搜索）	内部版	⚙️ 推荐	技能/文档搜索能力	`search` + `doc-index`
Summary（智能摘要）	内部版	⚙️ 可选	Agent 可引用总结结果辅助任务执行	`summary`
Drive（网盘）	内部版	⚙️ 可选	Agent 可读写网盘文件（Bot API 能力待确认）	`drive`

注意：Fleet 启动较慢（`start_period: 300s`，数据库迁移最长需 5 分钟），healthcheck 需配置足够的初始化等待时间。Fleet 使用独立 PostgreSQL 16，不与 MySQL 共享。

3.7 部署形态建议

           用户（Web 端）                 开发者 PC（本地运行时）
                │                                │
                ▼                                │ octo-daemon
          nginx（单入口）                         │ npm 包
                │                                │ WebSocket 长连接
                │                    ┌───────────┘
                │                    │ /fleet/api/daemon/ws
                ▼                    ▼
     ┌─────────────────────────────────────┐
     │           Fleet :8080               │
     │  Daemon注册/心跳 │ Bot编排置备       │
     │  运行时清单      │ 任务分发          │
     │  JWT + HMAC 鉴权                     │
     └──────┬──────────────┬───────────────┘
            │              │
            ▼              ▼
     ┌────────────┐ ┌──────────────┐
     │PostgreSQL  │ │  Redis DB1   │
     │  16 (Fleet)│ │  (Fleet缓存) │
     └────────────┘ └──────────────┘
            │
            │ OCTO_APP_SERVER_URL
            ▼
     ┌─────────────────────────────────────┐
     │         octo-server :8090           │
     │  消息/认证/群组/Webhook/Bot API     │
     └──────┬──────────────┬───────────────┘
            │              │              │
            ▼              ▼              ▼
     ┌────────────┐ ┌────────────┐ ┌──────────────┐
     │ Marketplace│ │   Docs     │ │  MySQL/Redis │
     │  :8092     │ │ :300/:1234 │ │  (核心存储)   │
     │ 技能/专家   │ │ HTML/协同   │ └──────────────┘
     │ 分发市场    │ │ 文档输出    │
     └────────────┘ └────────────┘
                           │
                           ▼
                      MinIO/S3
                 (marketplace/docs buckets)

环境准备：用户私聊 BotFather 发 `/daemon` 获取安装命令 → PC 上 `npm i -g octo-daemon` → 配置 server URL + space-scoped API key → daemon 自动检测本地 AI Agent CLI 并连入 Fleet
技能安装：Web 端「专家市场」浏览/安装技能包到自己的专家
任务派发：Web 端「回路」中发任务（语音/文字）→ 助理整理为 Issue → 派给专家/专家团
执行：Fleet 调度到在线 daemon → 本地 Agent 执行任务 → 进度实时回传
验收：用户在 Web 端查看执行结果（可输出为云文档）→ 验收通过归档 / 退回修改

3.8 售前注意事项（硬口径提醒）

🔴 以下为 AI Agent 场景售前必须明确告知的边界和限制：

安全与权限

序号	硬口径	说明
1	🔴 Marketplace 审核默认 auto-approve	技能/插件上架默认自动审核通过（auto-approve），企业若需要技能上架人工审核，需由Space管理员配置审核策略。不配置人审意味着任何用户都可以发布技能到Space内市场，存在安全风险。
2	🔴 运行期安全：seccomp 沙箱	octo-daemon 在本地运行 AI Agent 时，Agent 可访问本地文件系统和执行命令（具体边界待私有仓源码确认）。Fleet/Daemon 的本地能力权限模型（Shell 访问/文件读写/命令执行范围）位于私有仓，当前开源仓不可见，必须明确告知客户此项需以实际部署版本和交付团队确认为准。
3	权限声明模型在私有仓待确认	Agent/Expert 对本地资源的权限声明与隔离机制（哪些目录可访问、哪些命令可执行）完整实现在私有仓，公开资料中暂无详细说明。售前不得承诺"精细权限沙箱"能力。
4	Fleet outbound webhook 默认允许私网	`DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS=true` 默认开启，存在 SSRF 潜在风险，生产部署需评估。

运行时与端侧

序号	硬口径	说明
5	🔴 daemon 添加方式是复制命令行，不是扫码	用户添加本地电脑（安装 octo-daemon）的方式是：私聊 BotFather → 发 `/daemon` → 获取 npm 安装命令 + server URL + API key → 命令行执行安装配置。不是移动端扫码配对。对非技术用户有一定使用门槛。
6	🔴 移动端零运行时能力	iOS/Android 端确认无回路 Loop 功能（`dmloop_on` 未实现），移动端只能查看消息和通知，不能管理运行时、派发任务、查看执行状态。回路/运行时相关操作仅 Web 端可用。
7	Drive 仅 Web 端	企业网盘模块仅 Web 端可用，iOS/Android 未实现。
8	daemon 需要 Node.js 环境	octo-daemon 是 npm 包，用户 PC 需安装 Node.js（npm）才能安装运行。对非开发者员工可能需要 IT 协助部署。
9	daemon 连接依赖网络	daemon 通过 WebSocket 长连接连到 Fleet 服务端，PC 必须能访问 OCTO 服务器地址；离线状态下 daemon 无法接收新任务（已在执行的任务行为待确认）。

功能边界

序号	硬口径	说明
10	Marketplace 不是 Bot 市场	Marketplace 分发技能包/专家/专家团/插件，不分发 Bot。Bot 的创建/管理唯一入口是 BotFather。Expert（跑在 runtime/daemon 上）≠ User Bot（BotFather 创建），两条线完全独立。
11	技能包安装不创建 Bot 实例	安装技能包 = 给专家分配/写入技能（自动去重/失败重试），不会创建新的 Bot 实例。技能仅在回路工作区给专家使用。
12	审批流为验收制，非细粒度审批节点	当前回路的人工干预点在"验收"环节（通过/退回），不支持流程中每个步骤设置审批节点（如"执行删除前需审批"这类细粒度闸门）。如需精细审批需在 Agent 逻辑层自行实现。
13	Bot 操作文档走评论@Mention 链路	Agent/Bot 操作文档不是通过 Bot API 直接调用，而是通过文档评论区 @Mention 内部链路实现（docs-backend → octo-server `/v1/internal/bot-mentions` → bot_task → Bot 回复）。此链路为 MVP 阶段，灰度门控，仅支持 User Bot（不支持 App Bot），且 Bot 必须先被加为文档成员。
14	Fleet/daemon 调度链路部分在私有仓	Bot 如何通过 Fleet 调度 daemon 执行任务的完整链路、Squad leader/member 的调度策略、并发控制、超时处理、failover 等核心机制位于私有仓（`geely-octo-fleet/daemon/cli`），公开资料中细节有限，交付时以实际版本为准。

Marketplace 待确认项

序号	待确认项	说明
15	付费/私有市场能力待确认	Marketplace 是否支持付费技能、私有技能仓库（仅企业内部可见）、开发者上架权限管理等商业能力，当前无充分事实来源，不做承诺。
16	helm chart 默认 marketplace.enabled=false	Docker Compose 中 marketplace 默认启动，但 Helm values.yaml 中 `marketplace.enabled=false`，K8s 部署时需手动启用。

附录 A：三个场景对比总览

注¹：表中适用客户人数与推荐档位均为经验估算，无官方证据支撑（PS-06），售前不得作为承诺口径报出，实际规模需压测验证。

维度	场景一：企业内部 AI 协作办公平台	场景二：智能客服与 Bot 自动化平台	场景三：私有化 AI Agent 运行时平台
核心价值	IM+文档+网盘+搜索+AI 一体化协作	Bot API+卡片+Webhook 客服自动化	技能分发+多Agent协作+本地执行
适用客户	中大型企业/政企（200~500人起）¹	中小企业到中大型企业均可	中大型企业/AI研发团队（200人起）¹
推荐档位	L 档（16核32G）¹	M 档（8核16G）起步¹	L~XL 档（16核32G起）¹
部署形态	K8s 多节点，全模块	Docker 单机 PoC → K8s	K8s 多节点（3~5节点）
必选模块数	15+（含全部内部模块）	9（核心7件套+卡片+文件）	14+（Fleet+Marketplace+Docs+daemon）
额外基础设施	Kafka+OS（搜索）	无	PostgreSQL 16（Fleet专用）+ Kafka+OS
移动端支持	消息/语音/摘要可用；Drive/Loop 仅 Web	消息交互全端可用	零运行时能力（仅Web端操作回路）
是否需要LLM API	是（summary/speech依赖）	可选（Bot 可接自有LLM）	是（Agent执行依赖LLM）
开源版是否够用	不够（需内部版Docs/Drive/Search等）	够用（核心Bot API在开源版）	不够（需内部版Fleet/Marketplace）
数据安全重点	私有化+逻辑隔离+OIDC SSO	Bot token安全+Webhook HMAC	daemon本地权限+Marketplace审核

附录 B：售前硬口径速查卡

类别	硬口径	涉及场景
权限	无自定义 RBAC（角色硬编码枚举）	场景一
隔离	多租户同库逻辑隔离（space_id过滤），非物理隔离	场景一、三
SSO	仅 OIDC/OAuth2，不支持 SAML/LDAP/企微/钉钉/飞书扫码直连	场景一
Bot通信	事件接收是 HTTP 长轮询，非 WebSocket	场景二
Bot Token	`bf_`=User Bot（可入群）/`app_`=App Bot（仅DM）	场景二
Bot限制	App Bot 仅 DM；Bot 收不到 reaction/成员变动；无标准 OAuth2 scope	场景二
OBO	OBO 三重防循环；sendMessage 单目标单条	场景二
端侧限制	Drive/Loop 仅 Web 端；移动端零运行时能力	场景一、三
语音	ASR 转写（最大60s/3MB），不是音视频会议，TTS 待验证	场景一
性能	无官方 SLA/性能基准数据，资源规格为经验推算	全部
合规	删号无 GDPR 导出功能	场景一
Marketplace	默认 auto-approve（企业需配人审）	场景三
安全沙箱	daemon 本地能力权限模型在私有仓待确认	场景三
daemon安装	复制命令行（npm安装），非扫码配对	场景三
性能数据	不承诺固定并发/QPS/SLA	全部

附录 C：相关文档索引

文档	路径	用途
OCTO是什么	[01-product/OCTO是什么.md](../01-product/OCTO是什么.md)	产品定义、10大能力域、差异化定位
核心能力概览	[01-product/核心能力概览.md](../01-product/核心能力概览.md)	各能力域快速扫读
总体架构	[02-architecture/OCTO总体架构.md](../02-architecture/OCTO总体架构.md)	服务端分层、通信链路、Profile依赖
权限模型与鉴权	[02-architecture/权限模型与鉴权体系.md](../02-architecture/权限模型与鉴权体系.md)	三条安全硬口径、RBAC、SSO支持矩阵
部署形态总览	[03-deployment-ops/OCTO部署形态总览.md](../03-deployment-ops/OCTO部署形态总览.md)	Docker/K8s双形态、组件清单、端口映射
生产资源规格	[03-deployment-ops/生产资源规格建议-v1.0.md](../03-deployment-ops/生产资源规格建议-v1.0.md)	S/M/L/XL档位资源建议（经验推算）
Bot API 概览	[06-api-integration/Bot-API概览.md](../04-api-integration/Bot-API概览.md)	Bot API 端点、鉴权、消息模型、事件机制
卡片能力口径	[08-presales-delivery/](../08-presales-delivery/)	Adaptive Cards v1/v2 能力正式口径
模块说明文档	[01-product/模块说明/](../01-product/模块说明/)	各内部模块详细功能说明

版本记录

版本	日期	变更说明
v1.0	2026-09-22	初版。基于知识库 active/draft 级产品文档（OCTO是什么v2.0、核心能力概览v2.0、总体架构v2.0、权限模型v0.1、部署形态v1.1、资源规格v1.0、Bot API概览v0.4、各模块v0.3文档），编写三个核心场景（企业内部AI协作办公平台/智能客服Bot自动化/私有化AI Agent运行时平台），每个场景含痛点→能力对应→客户类型→部署档位→模块清单→部署架构→售前硬口径。