读 Octop 源码(1):先摊开地图,看看这 45 万行堆在哪
上一篇把 Octop 装起来跑通了,这一篇换个方向:不碰功能,只读代码。
我读源码有个习惯,第一篇绝对不抠实现。先干三件事——它到底自己写了什么、代码重量压在哪、一次启动按什么顺序把东西搭起来。这三件事不清楚,后面看任何一个模块都会飘。
版本锚点:本文基于
octopv1.0.2(commitdd9dce4,tagv1.0.2)。这个项目改得很快,行号和目录结构随时会变,看之前先对一下自己手上的版本。文中所有数字都是在这份代码上跑出来的,统计命令我在最后一节列了,你可以自己复核。
环境准备
源码和运行环境上一篇已经铺好了,这里只补三样东西。
第一,把源码和依赖库都摊在同一个视野里。 Octop 的关键设计都藏在边界上——它自己做什么、不做什么,光看本仓库是看不出来的,得把 site-packages 里那几个 octop_* 包一起摊开。
cd ~/WorkBuddy/Claw/octop
# 本仓库规模
find src/octop -name "*.py" | wc -l
find src/octop -name "*.py" -exec cat {} + | wc -l
# 三个外部库装在哪、多大
.venv/bin/python -c "
import octop_harness, octop_gateway, octop_memory, os
for m in (octop_harness, octop_gateway, octop_memory):
p = os.path.dirname(m.__file__)
n = sum(len(open(os.path.join(r, f), encoding='utf-8', errors='ignore').readlines())
for r, _, fs in os.walk(p) for f in fs if f.endswith('.py'))
print(f'{m.__name__:16} {n:7} 行 {p}')
"
第二,准备一个"行数地图"的生成方式。 我不信任自己的直觉,读之前先让数字说话:
for d in src/octop/infra/*/; do
n=$(find "$d" -name "*.py" -exec cat {} + 2>/dev/null | wc -l)
echo "$n $(basename "$d")"
done | sort -rn | head -20
第三,先看两份文档,但别全信。 docs/architecture.md(168 行)是给人看的概览,AGENTS.md(30KB)是给 AI 代理看的操作手册——后者反而更狠,里面直接写了"硬性禁止"和模块边界。两份文档我都读了,但下面写的启动顺序和链路是我自己在代码里走了一遍才敢下笔的。至少有一处文档漏掉了关键信息:architecture.md 的分层图画得很漂亮,却没画出"首次运行时根本不建运行时树"这个分叉(见第三节),而那恰恰是 server.py 里最拧巴的部分。
流程
一、第一件要认清的事:它自己不写 AI 运行时
打开 pyproject.toml,依赖列表里有三个显眼的包:
dependencies = [
"fastapi>=0.110",
"uvicorn[standard]>=0.27",
...
"octop-harness[all]>=1.0.4",
"octop-memory>=1.0.2",
"octop-gateway>=1.0.3",
...
]
这三个不是普通工具库,是三个独立发布的子系统:
| 库 | 职责 | 规模 |
|---|---|---|
octop-harness | 基于 LangGraph 的对话运行时,Agent 本体、工具调用、流式事件的真正实现 | 210 文件 / 42,951 行 |
octop-memory | Agent 记忆的存储、召回、维护,连记忆表的 DDL 都归它管 | 108 文件 / 32,634 行 |
octop-gateway | IM 通道管道,消息接入、会话键、平台适配的通用层 | 43 文件 / 16,047 行 |
看清楚这件事,后面很多设计就顺了:Octop 本仓库是一个集成产品,不是一个大单体。
它自己写的是这些东西——用户与权限、Agent 注册表(谁拥有哪个 Agent、什么时候启动、什么时候回收)、HTTP/WebSocket API、IM 通道的平台适配(飞书、企业微信、钉钉各自怎么收发)、插件系统、知识库、定时任务、备份、前端。真正"让 AI 跑起来"和"让记忆活起来"的部分,全在外部库。
这有个实际影响,值得说在前面:你读 Octop 学不到"怎么实现一个 Agent 运行时",但能学到"怎么把运行时、通道、记忆、Web UI 组装成一个能自托管的产品"。 后者其实更稀缺——太多团队能写出 demo,写不出能交给客户部署的东西。
顺带一提,这个结构也解释了它为什么敢自称"单个 Python 进程":复杂度被切成了几个可独立演进的轮子,主仓库只负责拧螺丝。
二、代码地图:45 万行到底堆在哪
先看总账。这是我在本机实测的:
| 部分 | 文件数 | 行数 |
|---|---|---|
后端本体 src/octop/ | 692 | 159,149 |
前端 dashboard/src/(ts/tsx) | 1,023 | 197,904 |
octop-harness | 210 | 42,951 |
octop-memory | 108 | 32,634 |
octop-gateway | 43 | 16,047 |
| 合计 | 约 2,076 | 约 448,000 |
这里第一个意外就来了:前端比后端大。 我原本以为一个 Agent 平台的重心在调度和编排上,结果是 19.8 万行 TypeScript 压着 15.9 万行 Python。往下拆后端,能看到重心具体落在哪:
| 模块 | 行数 | 说明 |
|---|---|---|
infra/agents/experts | 21,780 | 内置专家库(含技能包与脚本),是内容不是逻辑 |
infra/agents/ 其余 | 24,577 | 含 manager.py 单个文件 4,187 行 |
api/routers/ | 29,308 | 64 个路由挂载、523 个端点 |
infra/gateway | 13,857 | IM 通道适配 + 会话线程状态机 |
infra/connectors | 9,732 | 第三方连接器 |
infra/db | 8,854 | 双后端 + 迁移 |
infra/utils | 4,838 | |
infra/auth | 3,585 | JWT / SSO / LDAP / 验证码 |
注意第一行。infra/agents/experts 那 2.18 万行占了后端 13.7%,但点进去看,全是打包进来的专家定义、技能 Markdown 和配套脚本。它是资产,不是逻辑。 把这块剔掉再排,真正的核心是三个地方:api/routers(对外契约)、infra/agents/manager.py(生命周期)、infra/gateway(输入输出)。
如果你只有一周时间读这个项目,我的建议是这三个,其他都往后放。
三、启动链:一次 octop run 做了什么
src/octop/launch.py 只有 166 行,看完就明白整个进程模型。它只干三件事,而且顺序不能换:
async def run_foreground(...):
srv = OctopServer() # 1. 建领域服务(自己的运行时树)
await srv.start()
cfg = srv.services.config if srv.services is not None else srv.config
plan = build_listen_plan(cfg, ...) # 2. 决定监听哪些端口、要不要 TLS
app = build_app(srv) # 3. 把 FastAPI 挂上去
servers.append(uvicorn.Server(single_config))
...
await asyncio.gather(*(_serve(s) for s in servers))
await srv.stop() # 4. 优雅收尾
模块开头的 docstring 写得很直白:“Composition root”——组合根。整个仓库里,只有它可以同时 import infra/server(领域层)和 api/app(接口层)。这条约束在 architecture.md 里被明确点名,是刻意的分层纪律。
真正的重量在 OctopServer.start()(infra/server.py,810 行)。我把它完整走了一遍,实际顺序是这样的:
paths.ensure_root() 建目录
↓
ensure_cli_path() / apply_env_file() 环境准备(PATH、.env)
↓
_setup_logging() / ensure_nofile_limit()
install_safe_grep_fallback() 打补丁:安全 grep、shell 输出解码
install_shell_output_decoding()
↓
config = ensure_mobile_capabilities_probed()
ExpertCatalog + SubagentCatalog 加载内置专家/子代理目录
PluginManager.seed_bundled() 种子插件(默认不启用)
PluginManager.load_installed() 加载已装插件
↓
【分叉点】should_defer_control_plane_db() ?
├─ 是 → 标记 _started=True,发一次性口令,直接 return
└─ 否 → open_database() → run_migrations() → build_shared_services()
↓
_ensure_jwt_secret()
↓
_boot_runtime(config)
_boot_runtime()(485 行开始)才是真正搭运行时树的地方,顺序是这样的:
AgentManager(registry) 全局 Agent 注册表(一个进程只有一个)
↓
TrajectoryStore / HistoryArchive 轨迹与版本化历史(可选)
↓
Gateway(...) + await gateway.boot() IM 通道 + WS hub
↓
CronDeliveryService → CronManager APScheduler,进程内定时
↓
install_auto_renewal_job() TLS 证书自动续期,挂在 cron 上
install_auto_backup_job() 自动备份,也挂在 cron 上
↓
registry.set_cron_manager() 回填依赖:注册表反过来拿到 cron
registry.set_team_processor() 多 Agent 协作处理器
registry.set_hitl_session_store() 人机协同会话策略
registry.set_proactive_scheduler() 主动关怀
↓
await registry.boot() 真正把 agent 行加载成运行时
registry.schedule_idle_reclaim_sweep() 空闲回收(SQLite 瘦身)
await gateway.refresh_media_backends()
↓
UserManager + boot() ← 注意:用户管理器最后才建
await proactive_scheduler.start_all()
↓
BridgeManager(...) 跨实例互联
↓
self.app_runtime = AppRuntime(...) 必填的五个单例装进一个 dataclass
有三处细节值得单独拎出来。
第一,用户管理器是最后建的。 直觉上用户系统应该最早起来,但这里是 registry.boot() 之后。原因是 UserManager 依赖 SharedServices,而 Agent 的加载又不需要用户上下文——顺序是按依赖排的,不是按重要性排的。
第二,cron 是最后才接上依赖的。 注意先 CronManager(...) 构造、再 install_auto_renewal_job() 和 install_auto_backup_job() 往它上面挂任务,最后才 registry.set_cron_manager(cron_mgr) 把 cron 反向注入给注册表。这种"先造对象、再挂任务、最后补依赖"的顺序,是为了避免循环依赖打结。
第三,那个分叉点值得多说两句。
OctopServer.start() 里有一句:
if should_defer_control_plane_db(config, self.paths):
self._started = True
self._emit_wizard_password(user_count=0)
logger.info("control-plane database deferred until setup wizard chooses a backend")
return
首次运行时,配置里还没有数据库后端,这时候不建运行时树,只把进程立起来,让前端弹一个选后端的向导。用户选完之后,请求进来触发 bind_control_plane(),才真正开门建库、跑迁移、_boot_runtime()。
这一个决定,把"单进程"的复杂度顶上去了:
- 需要
database_bound属性来判断"现在是半个启动状态还是完整状态"; - 需要
bind_control_plane()做二次绑定,还得写成幂等(已绑定就直接返回); - 需要
AppRuntime.replace_services()支持把五个单例整体换绑到新的SharedServices上——因为向导阶段可能先建了个库又换了; - 需要
deps.py里的require_database()给所有路由兜底,返回 503SETUP_REQUIRED而不是 500。
我在别的项目里见过太多"为了首次体验牺牲架构"的例子,通常做法是搞一个假的默认配置先跑起来。Octop 选了另一条路:承认存在"启动了一半"这个合法状态,并把它做成一等公民。 我个人觉得这个取舍是对的,代价是 server.py 里散着一堆 assert self.services is not None——那就是半个状态留下的痕迹。
四、依赖注入:没有魔法,就两级 state
读完启动链,自然要问:路由怎么拿到那些单例?
很多项目在这里上 dependency-injector 或者自己写容器,Octop 用的是最土的办法——两级 state。
第一级挂在 app 上,build_app() 里只有一行:
app.state.octop_server = server
第二级挂在请求上,由 JWT 中间件写入,Depends 读出来:
def get_server(request: Request) -> OctopServer:
server: OctopServer = request.app.state.octop_server
if not getattr(server, "_started", False):
raise OctopError(ErrorCode.INTERNAL_ERROR, "server not started")
return server
async def current_user(
request: Request,
server: OctopServer = Depends(get_server),
authorization: str | None = Header(None),
access_token: str | None = Query(None),
) -> User:
cached = getattr(request.state, "octop_user", None)
if cached is not None:
return cast("User", cached)
raw = extract_raw_token(authorization=authorization, access_token=access_token)
if not raw:
raise OctopError(ErrorCode.AUTH_FAILED, "missing credentials")
return resolve_user_from_token(server, raw)
request.state.octop_user 那层缓存是关键:中间件已经解过一次 token 了,Depends 直接复用,避免每个路由再解一遍。而权限控制是一个依赖工厂:
def require_permission(key: str) -> Callable[..., Awaitable[User]]:
if key not in PERMISSIONS: # 拼错在构造时就炸,不会静默放行
raise RuntimeError(f"unknown permission key: {key}")
async def _dep(user: User = Depends(current_user)) -> User:
if not user_has_permission(user, key):
raise OctopError(ErrorCode.FORBIDDEN, "permission required",
details={"permission": key})
return user
return _dep
require_permission("knowledge.write") 这样一个调用,就把鉴权和授权都串上了,而且拼错权限名会立刻报错——这个细节很能看出团队踩过坑。
那这些单例长什么样?infra/server.py 里有个 20 行的 dataclass 就是全部答案——五个必填,三个可选:
@dataclass
class AppRuntime:
"""Live singletons — constructed after boot."""
agent_registry: AgentManager
gateway: Gateway
cron_manager: CronManager
user_manager: UserManager
proactive_scheduler: ProactiveCareScheduler
trajectory_service: TrajectoryService | None = None
history_archive: Any | None = None
bridge_manager: Any | None = None
就这几个。一个进程的全部活状态,就是这个 dataclass。 我读到这儿的时候有点意外——40 万行的项目,运行时状态收敛到 8 个字段,剩下全是行为。这其实是个相当干净的边界。
五、一条消息的旅程
地图摊到这儿,最后补上最常走的那条路:你在网页里问一句话,代码怎么跑。
浏览器
│ WS /api/agents/{agent_id}/chat/ws?token=...
↓
routers/chat/ws.py :: dashboard_chat_ws
│ ① server = websocket.app.state.octop_server
│ ② resolve_user_from_token(server, token) ← 无 token 直接 close 4001
│ ③ assert_agent_access(server, agent_id, user) ← 行级归属校验,403/404
│ ④ gateway = server.app_runtime.gateway
↓
Gateway → ChannelManager / WebSocketHub
│ 帧从 WS 收进来,包成 InboundMessage
↓
process/processor.py :: GlobalProcessor
│ ⑤ build_harness_request(...) 组装 harness 请求(模型、知识库、MCP、会话模式)
│ ⑥ _begin_history(...) 先把这一轮的历史跟踪器挂上
│ ⑦ async for ev in project_stream(agent_manager, agent_id, request, ...)
│ └→ harness 跑 LangGraph,事件边产出边投影成帧
│ ⑧ 收尾分三路:成功 → _record_turn_history
│ 异常 → _persist_incomplete_turn
│ finally 兜底:中途断掉的轮次也要落库
↓
帧回推 WS → 浏览器渲染
project_stream() 是这里的分界线:往里是 octop-harness 的地盘(LangGraph 图怎么跑、工具怎么调),往外是 Octop 自己的地盘(帧怎么投影成前端认识的样子、历史怎么落、用量怎么记)。想读运行时就读 project_stream 的入参和返回值,那是两层之间的契约。
⑧ 那三路收尾值得单独看一眼,因为它暴露了这类系统真正的难点。写对话产品的人一开始都只处理"成功"这一条路,上线后才发现:用户中途关页面、模型超时、进程被 kill,每一种都会留下半截历史。代码里 failure_saved 这个标志位就是用来保证"异常分支已经落过库了,finally 别再落一遍"——这种地方没有文档能教你,全是线上事故教出来的。
这条链上有个反直觉的点,我觉得是理解 Octop 架构的钥匙:网页、CLI、IM 通道用的是同一个 GlobalProcessor。
不过"同一个"要说得精确一点,它不是一个函数通吃,而是一个类开了两个入口:
| 入口 | 方法 | 协议 |
|---|---|---|
| Dashboard / WS | iter_turn_chunks() | harness 原生 chunk(token / tool_result / done…) |
| IM 通道 | __call__() → project_stream → MessageEvent | 批处理过的事件,比如钉钉的 handle_inbound |
两条路在 build_harness_request() 之后合流,跑的是同一套 Agent、同一份记忆、同一套历史落库逻辑,区别只在"最后把事件包成什么形状"。architecture.md 里那张表说得更清楚——真正区分入口的只有会话键(session key)的拼法:
| 入口 | 会话键默认值 |
|---|---|
| Web UI | <aid>:dashboard:<user_id>:dm |
| CLI | <aid>:cli:<user_id>:dm |
| IM 通道 | <aid>:<channel_kind>:<platform_session>:<dm|group> |
也就是说,你在飞书里问它、在网页里问它、在终端里问它,跑的是同一个 Agent、同一套记忆、同一份工具配置,只是历史记录分了不同的 thread。这解释了为什么它敢叫"三端一致"——不是做了三套适配,而是从一开始就把入口收敛到一个类里。
同时这也解释了为什么 GlobalProcessor 会是整个 gateway 里最复杂的文件:它要同时应付三种输入的差异,还要把 slash 命令、人机协同中断(HITL)、多 Agent 协作(team)、轨迹记录全塞进同一轮对话里。__call__ 在 642 行,iter_turn_chunks 在 946 行,光这一个类就上千行。这是"收敛入口"必然要付的代价。
六、为什么敢全塞一个进程
最后聊一个架构问题。docs/adr/001-single-process-model.md 是这项目唯一的两份 ADR 之一(另一份是数据库双后端),标题就叫"单进程,无外部队列"。它写得很坦诚,连代价都列了:
| 好处 | 代价 |
|---|---|
| 零外部依赖 | 只能垂直扩容(一台机器) |
| 部署简单(一个进程一个端口) | 重 CPU 任务会阻塞事件循环 |
| 本地开发快 | 没有水平扩展 worker 的能力 |
理由也很实在:目标用户是自托管的人,你让他多装一个 Redis,运维成本直接翻倍;而 Agent 调用本质是 I/O 等待(等模型几秒到几分钟),asyncio 的并发模型刚好吃得住这种扇出。
但"重 CPU 阻塞事件循环"不是一句空话,它在代码里留下了痕迹。比如 launch.py 里这段:
def _schedule_linux_bubblewrap_ensure() -> asyncio.Task[None] | None:
if not sys.platform.startswith("linux"):
return None
return asyncio.create_task(
asyncio.to_thread(_ensure_linux_bubblewrap), # ← 必须扔到线程里
name="ensure-linux-bubblewrap",
)
装 bubblewrap 是阻塞 IO,所以哪怕只是"后台顺手做一下",也得 to_thread 包起来,还得 _cancel_background_task() 在退出时收掉。你在 infra/ 里会反复看到这种模式。
ADR 里还有一句我挺喜欢的补充:“未来要横向扩展,得把 worker 抽成独立进程加队列,而这条缝已经部分可见于 infra/gateway/processor.py"。为将来的拆分预留缝,但不提前拆——这是个很克制的位置。
总结
这篇只做了一件事:把地图摊开。五条我认为最该记住的:
- Octop 是集成产品,不是单体。 真正难的运行时(
octop-harness)、记忆(octop-memory)、IM 管道(octop-gateway)都是独立发布的库,主仓库负责组装。读懂这个边界,才知道哪些代码"不用读”。 - 复杂度重心在前端。 19.8 万行 TS/TSX 大于 15.9 万行 Python 后端。后端里还有 2.18 万行是内置专家库(内容非逻辑),真正要读的核心是
api/routers、infra/agents/manager.py、infra/gateway三处。 - 启动顺序是按依赖排的,不是按重要性排的。 用户管理器最后才建,cron 最后才接依赖。看启动链的时候别用直觉判断顺序。
- “启动了一半"是个一等公民状态。 首次运行的 setup 向导逼出了
database_bound/bind_control_plane()/replace_services()一整套机制。这是为了首次体验付的架构税,我认为付得值。 - 三个入口收敛成一个类。 网页、CLI、IM 通道共用
GlobalProcessor,只在最后一步把事件包成各自的形状,靠 session key 区分历史。这是"三端一致"的真正原因,也是GlobalProcessor上千行的原因。
按编号下一篇是数据层,但按重要性我建议先跳到 (5)Agent 运行时:AgentManager 怎么把一个数据库行变成一个活着的 Agent、空闲回收(reclaim)那套机制在防什么、以及 octop-harness 的边界到底在哪。
参考链接
- 仓库:https://github.com/TencentCloud/Octop(MIT)
- 本篇对应的架构文档:
docs/architecture.md、docs/adr/001-single-process-model.md - 面向贡献者的模块边界与硬性禁止:仓库根目录
AGENTS.md - 运行时依赖库:
octop-harness、octop-memory、octop-gateway(均在 PyPI,随pip install octop一起装)
