腾讯云 Octop 快速入门:一小时跑通一个自托管的多用户 Agent 平台

…

Octop 是腾讯云开源的、可以自己部署的多用户 Agent 平台,MIT 协议, 虽然叫Octop但是大家都叫他"开源版workbuddy"。单个 Python 进程就把对话、技能、知识库、IM 通道、定时任务和插件系统全装下了。这篇按「装、配、用、扩展、加固」的顺序,把一小时能跑通的路径完整走一遍,最后附一个从零写的插件。

投屏不是推流,是递个网址

…

想把微信里的视频投到客厅电视上,搜了一圈没找到顺手的工具,干脆自己写了一个。写的过程中发现,我对投屏这件事的理解从头到尾都是错的——我以为是我的电脑把视频传给了电视,实际上我只是把视频的网址写在纸条上递给它,真正下载数据的是电视自己。

读 Octop 源码(7):三个扩展层,三种完全不同的挂载方式

…

前面几篇讲的都是"系统怎么运转",这篇讲"能力怎么长出来"。

Octop 里给 Agent 加本事有三条路:技能、知识库、插件。三者的代码量差不多(3,337 / 2,325 / 4,089 行),但重量级差了三个数量级——最轻的那个只要往目录里放个 Markdown 文件就生效了,最重的那个是进程内加载的 Python 代码。

这个分层不是随便划的,它直接决定了"你想加的东西该放哪"。

读 Octop 源码(6):流式投影层,和「在纯文本 IM 里做单选题」

…

第 1 篇画链路的时候,画到这一行就收住了:

async for ev in project_stream(agent_manager, agent_id, request, ...):
    yield ev

当时我说「project_stream 是这里的分界线:往里是 harness 的地盘,往外是 Octop 的地盘」。这篇把它拆开。

顺带把 HITL(human-in-the-loop)也读了——那 1,393 行在解决一个比想象中更土的问题。

读 Octop 源码(4):9 个中间件,9 个被踩出来的坑

…

第 5 篇写 _start_agent 的时候,第 ⑦ 步我写的是「_post_start_agent:注入 gateway 工具、清洗 MCP 工具名、同步技能」,一句就过去了。

其实那一步里藏着整个项目我最喜欢的一部分:9 个中间件。

它们合计不到 900 行,每个都很小,但每一个都对应一个具体的、真实发生过的问题。

读 Octop 源码(3):配置、目录布局,和那个「先不建库」的判定

…

第 1 篇写启动链的时候,有个分叉我没敢展开:

if should_defer_control_plane_db(config, self.paths):
    self._started = True
    self._emit_wizard_password(user_count=0)
    return

OctopServer.start() 跑到这里就 return 了——进程立起来了,但运行时树一个都没建。

当时只说"这是为了首次运行弹选数据库的向导"。这篇把这件事讲完:判定条件是什么、向导阶段怎么授权、以及配置和目录布局这两个看起来最无聊的东西,其实藏着不少设计。

读 Octop 源码(9):Dashboard 其实是个「虚拟 IM 通道」

…

前几篇一直在往上走:进程怎么起、Agent 怎么活、谁能碰谁的数据。这篇横向切一刀,读 infra/gateway/——13,857 行,第二大模块,负责所有消息的进出口。

打开 ws_channel.py 的第一行,我笑了:

"""Virtual IM channel that delivers Dashboard chat over WebSocket."""

Dashboard 不是"主入口",它是一个虚拟 IM 通道。 网页聊天的消息也要包成 InboundMessage、走和飞书完全相同的管道。

这句话是整个模块的设计前提,也是我读完之后最想写的一点。

读 Octop 源码(8):多用户隔离,一层真边界和三层纸糊的

…

前面读了启动链路和 Agent 运行时,这篇读隔离。

之所以单独拎出来,是因为"多用户"这三个字在自托管项目里最容易含混:有的项目是"多用户登录",有的是"多租户隔离",两者差着十万八千里。 看 README 看不出来,只能读代码。

读完之后我的判断是:Octop 属于前者,而且它自己知道。