首页 产品 为什么选 OCTO 解决方案 文档 关于
文档中心 / 模块详解 / Loop 回路
← 返回文档中心

Loop 回路

OCTO 文档中心 · 模块详解

  • 内部部署仓库 docker-compose.yaml / Helm values.yaml(deployment-fleet.yaml/statefulset-fleet-postgres.yaml)/ nginx 路由配置 / fleet-preflight(2026-09-21 阶段一解析)
  • OCTO知识库建设组父群 / 2026-09-21 14:32 / Octo 产品管家回答 (message_id:2101922421924597760)
  • 00-inbox/product-bot-answers/2026-09-21-P0扩展-FleetLoop回路模块回答.md
  • 知识库 loop-tutorial + feature-map(产品管家引用来源)
  • 00-inbox/product-bot-answers/2026-09-22-P1-r1-Q2-FleetLoop深度回答.md
  • 可读源码:octo-server/.octospec brief + octo-cli skills + octo-marketplace(2026-09-22 P1-r1 Q2源码确认)

回路Loop与Fleet模块说明 v0.3

回路(Loop/OctoLoop)与 Fleet 是 OCTO 内部版独有的两个紧密关联的模块:Loop = 项目管理+AI协作平台(面向用户的工作流层),Fleet = Bot编排与运行时管理服务(底层基础设施层)。octo-daemon 是用户本地运行时,是两者的连接点。

⚠️ 私有仓边界声明

  1. Fleet/daemon 运行时执行逻辑:daemon 拉取任务后的实际执行逻辑、文件读写权限边界、命令执行沙箱、进程管理能力
  2. Expert 调度执行:Squad leader/member 的调度策略、并发控制、超时处理、failover
  3. Expert vs Bot 权限模型:Expert 能否调用所有 Bot API、权限差异、资源限制

🔴 以上三点标记为「待私有仓源码确认」,绝不能写成「不存在」——只能说「可访问开源仓源码中未找到证据」。

一、模块定位(一句话口径)

Loop(回路)= OCTO内置项目管理+AI协作平台(类似Linear/Jira),把long-running task变成可派发、可追踪、可验收的流水线;入口Web左侧「回路」图标,`dmloop.enabled`门控。

Fleet = Bot编排与运行时管理服务(从octo-server拆出),负责Daemon注册/心跳/运行时清单/managed_bots/与matter协同分发;定位偏本地设备+运行时管理。

octo-daemon = 用户本地运行时监控服务(npm包octo-daemon)+ Loop CLI工具;自动检测本地AI Agent CLI(Claude Code/Codex/OpenClaw/Hermes),space-scoped API key认证,私聊BotFather发`/daemon`获取安装命令。

1.1 回路 Loop(产品概念层)

Loop = Octo 内置的项目管理 + AI 协作平台(类似 Linear/Jira 的 AI-native 版本)。

  • 核心价值:把"说不清、盯不住、验不了"的 long-running task 变成可派发、可追踪、可验收的流水线
  • 闭环流程:用户发语音/文字 → 助理整理成结构化 Issue → 专家/专家团执行 → 用户验收 → 归档或退回
  • 产品性质:更接近多 Agent 协作 + 工作流/任务编排回路,不是设备-云通信回路那种底层概念
  • 入口:Web 左侧「回路」图标
  • Profile 开关:dmloop.enabled(管理员控制开启)

1.2 Fleet(服务/基础设施层)

Fleet = Bot 编排与运行时管理服务(从 octo-server 拆出的独立服务)。

  • Fleet 负责:
  • Daemon 注册与心跳(本地运行时接入管理)
  • Bot 编排与置备(managed_bots)
  • 运行时清单(哪个 daemon 上跑哪些 Agent)
  • 与 octo-matter 协同任务分发
  • 定位偏「本地设备/运行时管理 + Bot 编排」,不是纯工作流引擎(工作流语义在 Loop 层)

1.3 octo-daemon(本地运行时)

octo-daemon = 用户本地电脑上的运行时监控服务 + Loop CLI 工具。

  • 是什么:OctoPush 的本地运行时监控服务
  • 运行位置:用户本地电脑
  • 功能:自动检测本地安装的 AI Agent CLI(Claude Code / Codex / OpenClaw / Hermes),向服务端上报状态,Web 端「Runtimes」页面可查看管理
  • 安装方式:私聊 BotFather 发 /daemon 获取安装命令
  • 形态:独立安装的 npm 包(octo-daemon),不是 OpenClaw Runtime 的一部分(但能检测到本地 OpenClaw)
  • 同时也是 Loop 的 CLI 工具
  • 「添加电脑」认证流程(1.0.x 新版):走 space-scoped API key 模式
  • 用户私聊 BotFather 发 /daemon → 拿到 server URL + 该 Space 专用 API key
  • daemon 用 API key 去服务端验证通过后写入 ~/.octo-daemon/config.json
  • 这个 API key 不是 GitHub token,也不是 OpenClaw key
  • Daemon 是否直接「接收云端任务本地执行」「提供 Shell/文件访问」——Loop 概念里 Runtime 是"跑命令、执行任务、保存中间产物"的环境,但 daemon 具体暴露多少本地能力(Shell/文件),需查源码
  • 添加电脑流程是否有扫码/配对码 UI 形式——产品管家确认的是 API key 模式,其他 UI 形式待确认
  • 认证机制除 API key 外,是否涉及 JWT/Loop 凭证/设备证书——API key 已确认,其他待确认(见 FL-03)

1.4 三层关系总结

Loop(回路)是面向用户的 AI 协作项目管理平台,Fleet 是底层的 Bot 编排+运行时管理服务,octo-daemon 是跑在用户电脑上的本地运行时载体;Fleet 管着 daemon 的注册/心跳/清单,并与 matter 协同分发任务,Loop 在其上提供可派单可验收的工作流语义。

1.5 Multica 口径纠偏

  • feature-map 中:Multica 是 Octo 群消息机器人(Incoming Webhook)支持的平台适配器之一(v2026.06.27),通过 Webhook 把 Multica 通知推送到群聊
  • Fleet 部署配置中:MULTICA_APP_URL / MULTICA_PUBLIC_URL 指向 /fleet 前端路径
  • 产品管家明确:同名是否指同一个东西不能断言,标待确认(FL-07)。可能是 Fleet 前端跳转的关联应用地址。
  • 入库处理原则:配置事实保留(配置项存在),功能归属不明,待查源码/产品确认。

二、部署与基础设施硬事实(来源:内部部署仓库配置)

2.1 octo-fleet 主服务

项目 事实 来源
服务镜像 mininglamposs/octo-fleet:latest(tag未pin) docker-compose
容器端口 8080(HTTP API + WebSocket) docker-compose
Profile fleet(+fleet-db 用内置PostgreSQL) docker-compose profiles
宿主机端口 127.0.0.1:28089(loopback默认) docker-compose
数据库 PostgreSQL 16(OCTO内部唯一使用PG而非MySQL的模块)——内置 fleet-postgres 或外部 FLEET_DATABASE_URL docker-compose / statefulset-fleet-postgres
Redis Redis DB 1(复用redis实例,非默认DB 0) docker-compose env
依赖服务 fleet-preflight、fleet-postgres(可选,required:false)、redis、octo-server docker-compose depends_on
启动等待 start_period: 300s(数据库迁移最长可能需5分钟) docker-compose healthcheck
健康检查 wget http://localhost:8080/healthz docker-compose
宿主机安全 容器端口绑定 127.0.0.1 loopback(不暴露公网) docker-compose ports
默认注册 ALLOW_SIGNUP=false(受控/邀请制,不开放自助注册) 环境变量
存储卷 ./certs/fullchain.pem → /etc/octo-fleet-certs/fullchain.pem:ro(自签HTTPS Webhook信任) docker-compose

2.2 核心环境变量

变量 默认/必填 说明 确认状态
PORT 8080 HTTP监听端口 ✅ 部署事实
DATABASE_URL 必填 PG连接串(postgres://fleet:***@fleet-postgres:5432/fleet) ✅ 部署事实
REDIS_URL redis://redis:6379/1 Redis(DB 1) ✅ 部署事实
JWT_SECRET 必填≥32hex JWT签名密钥 ✅ 部署事实
LOOP_CREDENTIAL_HMAC_KEY 必填≥32hex Loop凭证HMAC密钥 ✅ 部署事实;签发对象/用途 ⚠️ 待确认(FL-03)
OCTO_APP_SERVER_URL http://octo-server:8090 octo-server集成地址 ✅ 部署事实
MULTICA_APP_URL http://{domain}:{port}/fleet 前端应用URL ⚠️ Multica同名歧义,见§1.5(FL-07)
MULTICA_PUBLIC_URL http://{domain}:{port}/fleet 公开URL ⚠️ 同上
FRONTEND_ORIGIN / CORS_ALLOWED_ORIGINS http://{domain}:{port} CORS配置 ✅ 部署事实
ALLOW_SIGNUP false 不允许自助注册 ✅ 部署事实
DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS true 允许Webhook访问私有网络 ✅ 部署事实;动机/回调对象 ⚠️ 待确认(FL-02)🔴安全敏感
SSL_CERT_FILE /etc/octo-fleet-certs/fullchain.pem HTTPS Webhook自签证书信任 ✅ 部署事实

2.3 Nginx 路由(web 厚路由层)

URL路径 后端 协议 说明 确认状态
/fleet/api/daemon/ws fleet:8080 WebSocket Daemon长连接(无Connection strip,专门upgrade处理) ⚠️ 端点职责待确认(FL-04)
/fleet/api/v1/* fleet:8080 HTTP REST API(rewrite掉v1:/fleet/api/v1/x → /api/x) ✅ 路由事实
/fleet/api/* fleet:8080 HTTP API通用路径 ✅ 路由事实
/fleet/ws fleet:8080 WebSocket 另一个WebSocket端点 ⚠️ 端点职责待确认(FL-04)
/fleet/uploads/* fleet:8080 HTTP 文件上传 ✅ 路由事实;用途待确认(FL-10)
/fleet/auth/* fleet:8080 HTTP 认证相关 ✅ 路由事实
/fleet/(SPA fallback) fleet:8080 / web:80 — 前端应用路径,推测SPA ✅ 路由事实;前端具体功能待确认(FL-06)

2.4 fleet-postgres(内置数据库,可选)

项目 事实
镜像 postgres:16-alpine
容器端口 5432
Profile fleet-db
宿主机端口 127.0.0.1:25432
存储卷 fleet-postgres-data → /var/lib/postgresql/data
默认用户/库 fleet/fleet
说明 使用fleet-db profile时自动启动;也可配置外部PostgreSQL(FLEET_DATABASE_URL)

⚠️ Fleet是OCTO内部唯一使用PostgreSQL而非MySQL的模块,技术选型原因待确认(FL-08)。部署事实存在 ≠ 可解释其选型意图。

2.5 fleet-preflight(一次性初始化检查)

检查项 说明
FLEET_DATABASE_URL 或 fleet-db profile 二选一:外部PG URL或启用内置PG
FLEET_POSTGRES_PASSWORD 使用内置PG时必填,非CHANGE_ME
FLEET_JWT_SECRET ≥32hex,非CHANGE_ME
FLEET_LOOP_CREDENTIAL_HMAC_KEY ≥32hex,非CHANGE_ME

三、已确认能力(产品管家确认)

3.1 Daemon 已确认能力

  • Daemon 运行在用户本地电脑上,独立 npm 包(octo-daemon)
  • 自动检测本地 AI Agent CLI:Claude Code / Codex / OpenClaw / Hermes
  • 向服务端上报本地 Agent 运行时状态
  • Web 端「Runtimes」页面展示 daemon 上报的运行时状态
  • 支持一键远程升级插件
  • 「待 daemon 在线后才能 3 步建 Bot」——daemon 是 Bot 运行的前置条件之一
  • Daemon 同时是 Loop 的 CLI 工具
  • 添加电脑走 space-scoped API key 模式(详见§1.3)
  • Daemon 是运行时载体——任务真正执行的本地环境

3.2 Loop 工作流闭环

  1. 用户发语音/文字描述任务
  2. 助理整理成结构化 Issue
  3. 专家/专家团执行
  4. 用户验收
  5. 归档或退回

3.3 Fleet 服务职责

  • Daemon 注册与心跳
  • Bot 编排置备(managed_bots)
  • 运行时清单(哪个 daemon 上跑哪些 Agent)
  • 与 octo-matter 协同任务分发
  • 定位偏「本地设备/运行时管理 + Bot 编排」,不是纯工作流引擎

3.4 入口与门控

  • Web 左侧「回路」图标(Loop 入口)
  • 管理员需开启 dmloop.enabled 开关
  • Web「Runtimes」页面(运行时管理,对应「我的→运行时」)
  • 私聊 BotFather 发 /daemon 获取安装命令和 API key

3.5 数据流方向确认(源码级 ✅)

来源:octo-server/.octospec brief 源码搜索(2026-09-22 P1-r1 Q2)

  • octo-server 从不主动向 daemon 推送命令(无 server→daemon 命令下发通道证据)
  • server 向 Fleet 的唯一主动出站:POST /internal/project-workspace-events,推送 5 类项目生命周期事件(创建/更新/状态变更等)
  • 其余通信均为 daemon/Fleet 主动拉取模式

⚠️ 私有仓边界:daemon 拉取到任务后的实际执行逻辑(是否包含文件读写/命令执行/进程管理)位于私有仓 `geely-octo-fleet/daemon/cli`,待私有仓源码确认。可访问开源仓中未找到 server→daemon 下发命令的证据。

3.6 安全鉴权机制(源码级 ✅ + ⚠️)

来源:octo-server 源码中间件搜索(2026-09-22 P1-r1 Q2)

出站 SSRF 面(✅ 面小)
  • 出站地址复用 BotFather runtime-onboarding 推导的服务地址,不接受调用方自定义 URL
  • 结论:SSRF 攻击面较小,攻击者无法通过传入任意 URL 触发内网探测
入站 `/v1/internal` 鉴权链(✅ 多层防护)
防护层 机制 确认状态
Token X-Internal-Token 独立令牌,常量时间比较(防时序攻击) ✅ 源码确认
长度校验 Token 长度下限检查 ✅ 源码确认
Body 限制 请求 body 大小上限 ✅ 源码确认
IP 限流 StrictIPRateLimitMiddleware 按 IP 限流 ✅ 源码确认
IP 白名单 未找到显式 IP 白名单中间件 ⚠️ 源码中未发现证据

⚠️ 安全注意:`/v1/internal` 缺少显式 IP 白名单是一个潜在风险点。限流可防暴力破解但不能替代白名单。若部署在非隔离网络环境中需关注。

3.7 Loop Issue 状态机(源码级 ✅)

来源:octo-server/.octospec brief 源码搜索(2026-09-22 P1-r1 Q2)

backlog → in_progress → in_review → done
   ↓          ↓             ↓
   └──────────┴─────────────┴──→ cancelled
状态 类型 说明
backlog 初始态 待处理 Issue
in_progress 活动态 执行中,Expert 正在工作
in_review 活动态 待评审/待验收
done 终态 已完成验收
cancelled 终态 已取消
  • done / cancelled 为终态,不可回转
  • backlog → 活动态(in_progress / in_review)触发 Expert 运行(即派单执行)
  • ❌ 不支持自定义状态:状态机为固定枚举,源码中未找到自定义状态扩展点

3.8 Expert 与 Squad 模型(源码级 ✅ 部分确认)

来源:octo-marketplace 插件类型定义 + octo-server/.octospec(2026-09-22 P1-r1 Q2)

Expert(专家)= 单 Agent
  • plugin_type: expert
  • 单个 AI Agent,具备特定领域能力
  • 上限:30 个 Expert
Squad(专家团)= 多 Agent 组合
  • plugin_type: expert_team
  • 组成结构:
  • leader:组长 Agent,负责任务分解和分配
  • members:成员 Agent 列表
  • strategies:协作策略(上限 50)
  • dependencies:成员间依赖关系
  • 上限:30 个 Squad

⚠️ 私有仓边界:以下内容位于私有仓,待私有仓源码确认:

- Squad leader/member 的具体调度策略(如何分配任务、如何汇总结果)

- 并发控制、超时处理、failover 机制

- Expert vs Bot 权限模型:Expert 能否调用所有 Bot API、两者的权限差异和资源限制

3.9 Loop CLI 命令行工具(源码级 ✅)

来源:octo-cli skills 源码(2026-09-22 P1-r1 Q2)

  • 命令:octo-cli loop
  • 共 14 个 namespace(具体命名空间列表待进一步整理)
  • 载体:集成在 octo-daemon npm 包中(daemon 同时是 CLI 工具)
命令 功能
create 创建 Issue
list 列出 Issue
get 获取 Issue 详情
update 更新 Issue
comment 添加评论
quick-create 快速创建 Issue
  • Loop CLI 不能脱机使用,需 Fleet 在线鉴权
  • 即所有操作需连接服务端认证后执行

四、关键待确认项汇总(知识库行动项)

⚠️ 安全红线:涉及SSRF/私网webhook/本地能力边界的项,不得凭猜测写入知识库。部署配置存在 ≠ 可解释其设计意图,必须查源码/安全设计确认。

编号 待确认项 确认方式 优先级 安全敏感 状态
FL-01 Bot→Fleet→daemon 完整调度链路(主方向已确认为daemon拉取;执行逻辑在私有仓) 开源仓部分确认;daemon执行逻辑待私有仓 P1 否 🟡 部分关闭(主方向✅,执行逻辑待私有仓)
FL-02 DM_OUTBOUND_WEBHOOK_ALLOW_PRIVATE_NETWORKS 动机/回调对象🔴 源码确认出站面小(无自定义URL),⚠️无显式IP白名单 P0 是 🟡 部分关闭(SSRF面小✅,IP白名单缺失⚠️保留关注)
FL-03 LOOP_CREDENTIAL_HMAC_KEY 签发对象、用途、与JWT区别 查 octo-server modules/;或需内部仓 P1 是 🔴 待查
FL-04 两个WS端点职责划分:/fleet/api/daemon/ws vs /fleet/ws 查 octo-server 路由层 P1 否 🔴 待查
FL-05 Daemon 本地能力边界:Shell/文件/权限模型🔴 私有仓 geely-octo-fleet/daemon/cli P0 是 🔴 待私有仓源码确认
FL-06 /fleet 前端页面具体功能 查 octo-web 前端路由 P2 否 🔴 待查
FL-07 Multica 同名歧义:群消息适配器 vs Fleet MULTICA_APP_URL 查 octo-web + octo-adapters;后端handler查octo-server P2 否 🔴 待查
FL-08 Fleet 为何唯一使用PG(技术选型原因) 内部设计决策,需问Octo技术负责人 P2 否 🔴 待内部确认
FL-09 Fleet/Loop 模块成熟度(GA/Beta/开发中) 产品管家查changelog/feature-map P1 否 🔴 待查
FL-10 /fleet/uploads/ 文件上传用途 查 octo-server + octo-web P2 否 🔴 待查
FL-11 添加电脑流程是否有扫码/配对码UI 查 octo-web 前端 P2 否 🔴 待查
FL-12 Fleet/daemon运行时执行逻辑:任务拉取后执行模型、文件读写沙箱、命令执行边界🔴 私有仓 geely-octo-fleet/daemon/cli P0 是 🆕 待私有仓源码确认
FL-13 Expert调度执行逻辑:Squad leader/member调度策略、并发控制、超时处理🔴 私有仓 geely-octo-fleet/daemon/cli P1 否 🆕 待私有仓源码确认
FL-14 Expert vs Bot权限模型:API调用范围、权限差异、资源限制🔴 私有仓 geely-octo-fleet/daemon/cli P0 是 🆕 待私有仓源码确认
FL-15 /v1/internal 是否有部署层面IP白名单弥补(nginx/防火墙层) 查生产部署nginx配置/安全组 P1 是 🆕 部署层确认
FL-16 Loop CLI 14个namespace完整清单 查 octo-cli skills 源码枚举 P2 否 🆕 可查开源仓

✅ v0.3已关闭/部分关闭项:

- ~~FL-02(私网Webhook SSRF方向)~~:源码确认SSRF面小(出站地址不接受自定义URL),但⚠️入站`/v1/internal`无显式IP白名单保留为FL-15

- Loop Issue状态机(原FL-04关联):✅ 5状态枚举+终态+流转规则已确认(§3.7),无自定义状态

- 数据流主方向(原FL-01关联):✅ daemon拉取为主,server仅推项目生命周期事件(§3.5)

⚠️ 知识源能力更新:

- 已通过产品管家P1-r1源码确认(octo-server/.octospec + octo-cli skills + octo-marketplace):数据流方向、安全鉴权链、Loop状态机、Expert/Squad模型、Loop CLI

- 私有仓不可见项(FL-05/FL-12/FL-13/FL-14):需Octo内部开放 geely-octo-fleet/daemon/cli 仓或由内部技术人员确认

  • FL-02/FL-15(私网Webhook/IP白名单):源码确认SSRF出站面小(不接受自定义URL),但入站/v1/internal缺显式IP白名单。售前口径:"出站SSRF面可控,入站有Token+限流多层防护;部署层建议补IP白名单"——不得自行扩大或缩小风险描述。
  • FL-05/FL-12(Daemon本地能力/运行时执行):位于私有仓,可访问开源仓中未找到server→daemon下发文件读写/命令执行/进程管理的证据,但不能断言不存在。售前不得夸大为"可远程控制用户电脑",也不得说"无此能力"——准确口径是"待源码确认"。
  • FL-14(Expert vs Bot权限模型):位于私有仓,售前不得自行推断Expert权限范围。

五、与其他模块的关系

模块 关系 状态
octo-server Fleet 通过 OCTO_APP_SERVER_URL 集成;Fleet 是从 octo-server 拆出的独立服务 ✅ 已确认+部署事实
octo-matter Fleet 与 matter 协同任务分发 ✅ 产品管家确认
octo-daemon Fleet 管理 daemon 注册/心跳/运行时清单;daemon 是本地运行时载体 ✅ 已确认;调度链路待确认(FL-01);本地能力边界待确认(FL-05)
BotFather 通过 /daemon 命令下发安装指引和 space-scoped API key ✅ 已确认
「我的→运行时」(Runtimes) Web 端展示 daemon 上报状态、支持添加电脑/一键远程升级插件 ✅ 已确认;是否对应/fleet路由待确认(FL-06)
Redis Fleet 使用 Redis DB 1(非默认DB 0) ✅ 部署事实
PostgreSQL Fleet 是 OCTO 唯一使用 PG 的模块;内置16-alpine或外接 ✅ 部署事实;选型原因待确认(FL-08)
Multica 群消息Incoming Webhook平台适配器;与Fleet配置中MULTICA_APP_URL同名歧义 ⚠️ 待确认(FL-07)
Skills/插件 Daemon 支持一键远程升级插件;与「从运行时复制技能」功能关系待确认 ⚠️ 部分确认
Web 前端 Web 左侧「回路」入口(dmloop.enabled门控) ✅ 已确认
Docs/Drive 无直接证据表明联动 —

六、版本记录

  • v0.1(2026-09-21):基于内部部署仓库硬事实新建,confidence:low,功能描述全为推断待确认(已归档至99-archive/)
  • v0.3(2026-09-22):产品管家P1-r1 Q2源码确认级回答回填——①新增「⚠️私有仓边界声明」(Fleet/daemon运行时、Expert调度、权限模型三处明确标注);②新增§3.5数据流方向确认(daemon拉取为主,server仅推5类项目生命周期事件到POST /internal/project-workspace-events);③新增§3.6安全鉴权机制(SSRF面小+/v1/internal完整鉴权链:X-Internal-Token常量时间比较+长度下限+body上限+StrictIPRateLimitMiddleware IP限流+⚠️无显式IP白名单);④新增§3.7 Loop Issue状态机(5状态枚举backlog/in_progress/in_review/done/cancelled+终态规则+流转触发Expert运行+无自定义状态);⑤新增§3.8 Expert/Squad模型(plugin_type区分+leader/members/strategies/dependencies结构+上限30/30/50+调度/权限模型待私有仓确认);⑥新增§3.9 Loop CLI(octo-cli loop +14 namespace+create/list/get/update/comment/quick-create能力+非离线需Fleet鉴权);⑦§4待确认项更新:新增状态列,关闭/部分关闭FL-02(SSRF面确认)+状态机确认,新增FL-12(运行时执行)/FL-13(Expert调度)/FL-14(权限模型)/FL-15(IP白名单部署层)/FL-16(CLI namespace清单);⑧confidence从medium升至medium-high(可访问源码部分high,私有仓部分medium-low);⑨更新安全敏感项说明