tako 文档 GitHub

05 · Octop 架构剖析与生长式复刻

性质:参考实现剖析 + 复刻方针。新系列第五篇,改写自旧《03-架构剖析与移植Plan》: Octop 的壳/芯分层、组件清单、规模数据原样保留(这些是"要什么"的地图), 把原来的"六阶段移植 Plan"和"L0–L8 学习阶梯"合并改写为产品能力路线(§4), 因为 2026-09-26 定案后仓库不再是分层学习对照,而是单入口产品形态。 依据:ref-agent/Octop(v0.9.33+,main 分支)+ harness-pkg/ 里的 orcakit_harness_agent 1.0.14 / harness_memory 0.9.11 / harness_gateway 0.9.9 源码。

1. 全局分层:Octop 是"壳",harness-* 是"芯"

┌─────────────────────────────────────────────────────────┐
│  入口                                                    │
│  Web Dashboard(React)  CLI  IM(飞书/钉钉/QQ/TG/企微)  Cron │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Octop 应用壳(src/octop,Python 单进程,约 13.1 万行)     │
│  ├── api/        FastAPI 路由层(60+ router,2.7 万行)    │
│  ├── infra/agents 每用户 Agent 管理(4.0 万行,最大模块)   │
│  ├── infra/gateway IM 渠道接入(1.1 万行)                │
│  ├── infra/{db,cron,auth,knowledge,skills,connectors...} │
│  └── launch.py   组合根:OctopServer + FastAPI + uvicorn │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  harness-agent(4.4 万行,pip 外部包)★ Agent 核心         │
│  HarnessAgent = deepagents.create_deep_agent 的门面封装   │
│  + 24 个中间件 + 子代理/团队/技能/MCP/安全/模型路由         │
├─────────────────────────────────────────────────────────┤
│  harness-memory(3.2 万行)分层记忆,ports & adapters      │
│  harness-gateway(1.4 万行)IM 通道统一管线                │
├─────────────────────────────────────────────────────────┤
│  deepagents → langgraph → langchain(Python 生态)        │
└─────────────────────────────────────────────────────────┘
        存储:SQLite(WAL)/PostgreSQL 控制面 + checkpoint
        前端:dashboard/ React18+Vite+AntD(选型无关,可复用)
        桌面:desktop/ Go 托盘外壳(2.6k 行)

1.1 运行时对象层级(README 官方描述)

OctopServer(单进程,启动时从控制面 DB 重建全部状态,可重启恢复)
 └─ HarnessAgentManager(按用户)
     └─ AgentRuntime(按 Agent)
         ├─ HarnessAgent      Agent 运行时(harness-agent)
         ├─ HarnessProcessor  统一入口路由:Web UI / IM / 定时任务
         └─ ChannelManager    IM 连接(harness-gateway)

关键设计:无外部 MQ,进程内 HarnessProcessor 统一路由所有入口; 无外部中间件依赖,默认 ~/.octop/octop.db SQLite 一把梭。 对 yk-tako 的启示:入口多不等于架构复杂——多入口收敛到一个处理器里,是后面"多入口统一路由"那一层的参考形状。

2. 组件清单与规模(工作量评估的地图)

2.1 Octop 应用壳(13.1 万行)

模块 行数 职责 MVP 需要?
infra/agents 39,852 Agent 管理器、运行时、专家库、子代理、团队、中间件装配、MBTI、记忆后端 ✅ 核心,但可砍 MBTI/teams
api 27,095 60+ REST/WS 路由 ✅ 按需裁剪(一半路由可砍)
infra/gateway 11,391 IM 渠道、HITL、WS、slash 命令 二期(MVP 只留 Web/CLI)
infra/connectors 7,727 OAuth + MCP 连接器(腾讯文档等) 二期
infra/db 7,645 SQLAlchemy 模型、迁移 ✅
cli 5,495 Click CLI、REPL 二期(我们现在只有 REPL)
infra/skills 3,141 技能包管理 ✅(简化版)
infra/setup 2,933 初始化向导、TLS ❌ 砍
infra/backup 2,383 备份恢复 ❌ 砍
infra/history 2,368 历史记录 ✅(简化版)
infra/auth 2,334 JWT 多用户 ✅(单用户简化)
infra/knowledge 2,275 RAG 知识库 二期
infra/cron 1,166 APScheduler 定时任务 ✅(核心卖点之一)
infra/desktop/mobile/voice/proactive/backend/browser/providers ~9,000 桌面/移动/语音/主动关怀/存储后端 ❌ MVP 全砍

MVP 实际需要面对的壳代码 ≈ 3~4 万行等效功能(重写,非翻译)。这些活都排在能力路线靠后(§4 第 8、9 项)。

2.2 harness-agent(4.4 万行)★ 复刻的核心目标

结论:harness-agent ≈ deepagents 配置层加中间件矩阵。 它的每一条中间件都是一层能力的「要什么」清单, 但实现方式不直接照抄——同一件事在 Eino 里可能落在完全不同的一层(例如"规划与执行的时序", harness 只能用中间件的软钩子,"Eino 的正式答案"是编图,见《08》)。

2.3 harness-memory(3.2 万行)

采用 ports & adapters 整洁架构:core / domain / application / pipeline / operations / adapters。 分层记忆 + 全文检索,记忆随工作区迁移。接口边界清晰,适合整体替换——这正是 T-Mem 二期可以插入的位置。

2.4 harness-gateway(1.4 万行)

channels(飞书/钉钉/QQ/Telegram/企微)+ manager + push_routing + hitl + media。 统一管线:各渠道的消息 → 归一化 → HarnessProcessor。二期再碰。

3. 为什么是"生长式复刻"而不是"移植"

原计划:读懂 22 万行存量 → 翻译到新语言("精读-规格化-翻译")
现计划:从一个能跑的主循环出发 → 逐层生长能力 → 参考实现只当"参考答案"
        最终功能对齐 Octop MVP,但每一行代码都知道为什么存在

4. 能力路线(产品视角)

每层都是"能给用户用的东西",不是"为学某个框架概念而写的 demo"。 参考实现一列只回答"要什么",具体设计按 Eino 的正式做法来。

# 能力 参考实现(harness-agent / Octop) 状态
1 主循环 + 工具(时间/计算/bash/文件) deepagents 核心 ✅
2 工具安全:命令守卫 / 文件守卫 / PII + 人工审批 security/tool_guard、middleware/{tool_guard,filesystem_guard,pii}.py ✅(实现于 internal/guard,见《06》)
3 任务看板:Plan / Tasks / Actions 三层分离 不照 write_todos 整表覆盖,自研记账工具 🔶 定案完成、实现进行中(见《01》《02》《07》)
4 上下文管理 compaction / media_offload / context_usage ✅ 上下文压缩已实现(算法见《12》第 9 节,任务见《13》)。media_offload 与 context_usage 仍未做
5 子代理 subagents/ + ADK ⬜
6 记忆 memory / memory_recall → 二期 T-Mem(见《04》§2) ⬜
7 断点恢复与流式 checkpoint / interrupt 🔶 内存 checkpoint + interrupt 审批已有。Web 事件已落 SQLite,断线可按 seq 回放;在途轮次崩溃后续跑仍未做(见《10》第 4.4 节)
8 多入口统一路由 HarnessProcessor(Web / IM / cron) 🔶 Web 入口有 SSE、审批、续传与显式停止;IM / cron 未动
9 多用户、多 Agent HarnessAgentManager + AgentRuntime ⬜

节奏与纪律:

5. 翻译原则(2026-09-24 定案)

复刻 Octop 是功能翻译,不是设计移植。每爬一层:

已经验证过一次:L2(任务规划)阶段曾依照 Octop 的 afterModel 设想手搓软约束线, 后来按 Eino 的方式收口(先编图),2026-09-26 定案又收敛为看板 + 单入口(见《07》《08》)。 反面教训是:硬翻 LangGraph 的防守思路在 Eino 里没有落脚点,那条路只会碰壁。

6. 资产归档位置

资产 位置
Octop 源码(功能参照物,只取"要什么") /Users/yuweikang/dev/ykcode/ref-agent/Octop
WeKnora 源码(Eino 缺失类库的 Go 参考) /Users/yuweikang/dev/ykcode/ref-agent/WeKnora
harness-* 包源码(含 wheel 归档) /Users/yuweikang/dev/ykcode/harness-pkg/
本系列文档 /Users/yuweikang/dev/ykcode/learn/yk-tako/doc/