读 Octop 源码(1):先摊开地图,看看这 45 万行堆在哪

文章目录

上一篇把 Octop 装起来跑通了,这一篇换个方向:不碰功能,只读代码。

我读源码有个习惯,第一篇绝对不抠实现。先干三件事——它到底自己写了什么、代码重量压在哪、一次启动按什么顺序把东西搭起来。这三件事不清楚,后面看任何一个模块都会飘。

版本锚点:本文基于 octop v1.0.2(commit dd9dce4,tag v1.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-memoryAgent 记忆的存储、召回、维护,连记忆表的 DDL 都归它管108 文件 / 32,634 行
octop-gatewayIM 通道管道,消息接入、会话键、平台适配的通用层43 文件 / 16,047 行

看清楚这件事,后面很多设计就顺了:Octop 本仓库是一个集成产品,不是一个大单体。

它自己写的是这些东西——用户与权限、Agent 注册表(谁拥有哪个 Agent、什么时候启动、什么时候回收)、HTTP/WebSocket API、IM 通道的平台适配(飞书、企业微信、钉钉各自怎么收发)、插件系统、知识库、定时任务、备份、前端。真正"让 AI 跑起来"和"让记忆活起来"的部分,全在外部库。

这有个实际影响,值得说在前面:你读 Octop 学不到"怎么实现一个 Agent 运行时",但能学到"怎么把运行时、通道、记忆、Web UI 组装成一个能自托管的产品"。 后者其实更稀缺——太多团队能写出 demo,写不出能交给客户部署的东西。

顺带一提,这个结构也解释了它为什么敢自称"单个 Python 进程":复杂度被切成了几个可独立演进的轮子,主仓库只负责拧螺丝。

二、代码地图:45 万行到底堆在哪

先看总账。这是我在本机实测的:

部分文件数行数
后端本体 src/octop/692159,149
前端 dashboard/src/(ts/tsx)1,023197,904
octop-harness21042,951
octop-memory10832,634
octop-gateway4316,047
合计约 2,076约 448,000

这里第一个意外就来了:前端比后端大。 我原本以为一个 Agent 平台的重心在调度和编排上,结果是 19.8 万行 TypeScript 压着 15.9 万行 Python。往下拆后端,能看到重心具体落在哪:

模块行数说明
infra/agents/experts21,780内置专家库(含技能包与脚本),是内容不是逻辑
infra/agents/ 其余24,577含 manager.py 单个文件 4,187 行
api/routers/29,30864 个路由挂载、523 个端点
infra/gateway13,857IM 通道适配 + 会话线程状态机
infra/connectors9,732第三方连接器
infra/db8,854双后端 + 迁移
infra/utils4,838
infra/auth3,585JWT / 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() 给所有路由兜底,返回 503 SETUP_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 / WSiter_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"。为将来的拆分预留缝,但不提前拆——这是个很克制的位置。

总结

这篇只做了一件事:把地图摊开。五条我认为最该记住的:

  1. Octop 是集成产品,不是单体。 真正难的运行时(octop-harness)、记忆(octop-memory)、IM 管道(octop-gateway)都是独立发布的库,主仓库负责组装。读懂这个边界,才知道哪些代码"不用读”。
  2. 复杂度重心在前端。 19.8 万行 TS/TSX 大于 15.9 万行 Python 后端。后端里还有 2.18 万行是内置专家库(内容非逻辑),真正要读的核心是 api/routers、infra/agents/manager.py、infra/gateway 三处。
  3. 启动顺序是按依赖排的,不是按重要性排的。 用户管理器最后才建,cron 最后才接依赖。看启动链的时候别用直觉判断顺序。
  4. “启动了一半"是个一等公民状态。 首次运行的 setup 向导逼出了 database_bound / bind_control_plane() / replace_services() 一整套机制。这是为了首次体验付的架构税,我认为付得值。
  5. 三个入口收敛成一个类。 网页、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 一起装)