读 Octop 源码(7):三个扩展层,三种完全不同的挂载方式
前面几篇讲的都是"系统怎么运转",这篇讲"能力怎么长出来"。
Octop 里给 Agent 加本事有三条路:技能、知识库、插件。三者的代码量差不多(3,337 / 2,325 / 4,089 行),但重量级差了三个数量级——最轻的那个只要往目录里放个 Markdown 文件就生效了,最重的那个是进程内加载的 Python 代码。
这个分层不是随便划的,它直接决定了"你想加的东西该放哪"。
版本锚点:本文基于
octopv1.0.2(commitdd9dce4)、deepagents0.7.28。三个目录:infra/skills/3,337 行、infra/knowledge/2,325 行、infra/agents/plugins/4,089 行(含 27 个内置插件)。
环境准备
三层的东西都在磁盘上,先看清楚形态。
第一层:技能在 workspace 里长什么样。
cd ~/WorkBuddy/Claw/octop
ls .home/.octop/agents/aaaaa/.octop/
# AGENTS.md MEMORY.md SOUL.md skills/ ...
ls .home/.octop/agents/aaaaa/.octop/skills/
第二层:知识库在库里。
sqlite3 .home/.octop/octop.db "select id, name, created_at from knowledge_bases;"
ls .home/.octop/knowledge/ # 原始文件
ls .home/.octop/embedding_models/ # 本地嵌入模型
第三层:插件有独立的目录和清单文件。
ls .home/.octop/plugins/
cat .home/.octop/plugins/*/plugin.yaml | head -20
本机还装了两个 demo 插件(demo-toolkit、demo-greeting-skill),正好能对照看。
流程
一、三层的重量级差多少
先给结论,下面逐层展开:
| 技能 | 知识库 | 插件 | |
|---|---|---|---|
| 载体 | Markdown 文件 | 用户上传的文档 | Python 代码 + YAML |
| 怎么生效 | 落进 workspace,首轮扫描 | 过索引流水线 | 进程内 import |
| 要不要写代码 | 不用 | 不用 | 要 |
| 要重启吗 | 不用 | 索引是异步的 | 要重新加载插件 |
| 能带 UI 吗 | 不能 | 不能 | 能(ui/index.js) |
| 能拦截调用吗 | 不能 | 不能 | 能(贡献中间件) |
| 典型用途 | 教模型一套工作流程 | 让模型查自己的资料 | 接入外部服务 / 加工具 |
“越往上越像内容,越往下越像代码。” 这个分层最有价值的地方是:加一个能力时,你永远知道该往哪层放。
二、技能:最轻的那层,轻到有点意外
我原以为"技能"是个有注册表、有加载器、有生命周期的东西。实际读下来,它朴素到接近"没有实现":
async def sync_octop_builtin_skills(workspace: Any) -> list[str]:
"""Overwrite Octop-owned built-ins and remove superseded runtime copies."""
# DeepAgents scans both roots on the first turn. Keep the writable root
# present even before the user installs their first Skill so that scan is
# clean on fresh expert instances.
await workspace.amkdir("skills")
...
注释里那句是全部秘密:「DeepAgents scans both roots on the first turn.」
也就是说:技能能不能被模型看到,取决于 deepagents 库自己会不会去扫 skills/ 目录。Octop 做的只是"把文件放到该放的地方"——建目录、写文件、覆盖旧的内置版本。
模型看到的不是"调用某个 skill 工具",而是技能文档直接进了 system prompt 的上下文(deepagents 的扫描机制负责这一步)。
这就解释了为什么技能不需要代码执行、不需要注册、不需要重启:它本质上是 prompt 工程的可持久化形式。
好处很明显:
- 用户不用会编程就能给 Agent 加本事
- 改一个 Markdown 就能调整行为,不用动代码
- 天然可分享(一个目录拷过去就行)
代价是:技能只能"教",不能"做"。它能告诉模型"写周报要分三段",但没法帮模型真的调一次 API。要调 API,得往上走到插件那层。
附带说一句,第 5 篇那个 _post_start_agent 里,每个 Agent 启动都要 sync_octop_builtin_skills(ws) 一次——内置技能是"覆盖式同步",Octop 拥有的那几个会被强制更新,用户自己加的不动。这是"内置资产要能随版本升级"的常见做法。
三、知识库:一条七段流水线
infra/knowledge/ 2,325 行,拆开是 16 个模块,每个管一段:
| 模块 | 职责 |
|---|---|
parse.py | 把 PDF / Office / 图片转成文本 |
ocr.py | 扫描件兜底 OCR |
chunk.py | 切块(按语义还是按长度) |
embed.py | 向量化 |
index.py | 建索引 |
retrieve.py | 检索 |
citations.py | 引用溯源(回答里带"出自第 3 页") |
jobs.py | 异步任务(索引是后台跑的) |
gate.py | 开关与前置检查 |
hint.py | 提示模型"该查知识库了" |
service.py | 对外服务层 |
params.py / relpath.py / files.py / default_open.py / tools.py | 参数、相对路径、文件管理、默认打开方式、工具注册 |
这是三层里唯一一条真正的"数据处理流水线"。
有个细节值得单独说,在 embed.py 第一行:
"""Route knowledge-base embeddings to local ONNX or a configured provider."""
然后是:
backend = (settings.get("knowledge_embedding_backend") or "onnx").strip().lower()
默认 onnx,也就是本地推理。 不是"默认调 OpenAI",是"默认自己算"。
原因不难猜:知识库是自托管产品的核心功能,如果默认依赖外部 API,那"自托管"这件事就破了一半——你的文档还是得发给别人才能用。所以它带了一个本地嵌入模型,模型文件就放在 ~/.octop/embedding_models/。
代价是首次使用要下模型、本地推理慢、效果不如大厂 API。所以留了 knowledge_embedding_backend 这个开关,想用 API 也行。
“默认本地、可选云端"和"默认云端、可选本地"是两种完全不同的产品。 前者是自托管,后者是 SaaS 带个离线模式。这个默认值选得很对。
hint.py 那个模块也值得提一句——它就是第 4 篇里那 9 个中间件之一 KnowledgeSearchHintMiddleware 的来源。它的作用是在合适的时机提示模型去查知识库,而不是让模型自己想起来。
为什么需要这个?因为工具是"模型主动调用"的,模型不知道自己不知道。不提示的话,用户问公司内部的事,模型会自信地瞎编而不是去查。所以"提示去查"这件事得由中间件在合适的时机注入——这又是第 4 篇"中间件是产品意图的落点"的一个例子。
四、插件:最重的那层,但能带前端
infra/agents/plugins/ 4,089 行,bundled/ 下 27 个内置插件。
先看一个插件的实际结构(以 weather 为例):
weather/
├── plugin.yaml
├── main.py
├── icon.svg
└── ui/
├── index.js
└── manifest.json
plugin.yaml 全文不复杂:
id: weather
version: 0.2.2
name: 天气
description: 查询全球城市天气与未来预报,在聊天中展示天气卡片
icon: icon.svg
group: lifestyle
kind: tool
entry: main.py
requires:
- httpx>=0.27
ui:
entry: ui/index.js
manifest: ui/manifest.json
三个关键字段:
kind: tool —— 插件类型。我 grep 到的另一种是 channel(贡献一个新的 IM 通道),这类要算 _channel_fingerprint(plugin_dir),因为通道配置变了需要重载。
requires: [httpx>=0.27] —— 插件可以声明 Python 依赖。第 1 篇讲 PluginManager.load_installed(install_deps=True),那个 install_deps 就是在装这个。
ui: {entry, manifest} —— 插件可以带自己的前端资源。
第三点是这个插件系统最有意思的地方。它意味着一个插件能在聊天里渲染自定义卡片——天气插件不返回一段文字,而是返回一张天气卡片(图表、图标、温度)。
而这就是第 4 篇讲的 OctopUiOffloadMiddleware 存在的原因:
"""Offload oversized ``octop_ui`` tool payloads onto ``ToolMessage.artifact``."""
插件渲染卡片 → 卡片的数据可能很大 → 塞进消息里会撑爆上下文 → 必须卸载到 artifact。 三篇读下来,这几个设计终于接上了。
plugins/ 目录下还有四个官方 demo,正好对应四类能力:
| demo | 演示什么 |
|---|---|
demo-toolkit | 加一组工具 |
demo-greeting-skill | 加技能(对,插件也能装技能) |
demo-turn-logger | 加中间件(观察每一轮) |
demo-ui-card | 加前端卡片 |
插件是"能力上限最高、成本也最高"的那层:它能碰到工具、中间件、通道、前端——但也因此要跑在进程内,一个 bug 能拖垮整个服务。
五、27 个内置插件在干什么
把 bundled/ 列出来,能看出这个产品的定位:
air-quality arxiv-search bilibili-anime color-convert
daily-english fortune fun-facts github-trending
hot-topics ip-lookup market-quotes meme-maker
mini-games movie-search parcel-tracker pomodoro
qrcode server-status short-link slack-calendar
sports-scores tetris travel-inspire unit-convert
weather what-to-eat wiki-summary
27 个里,24 个是"生活/娱乐/小工具”,3 个是"运维/开发"(server-status、github-trending、ip-lookup)。
这个配比说明内置插件的目的不是"提供核心能力",而是**“把插件系统演示一遍”**——用户装完就能玩,玩着玩着就知道自己能写一个。
而且注意这些插件的性质:weather、market-quotes、ip-lookup、short-link 全是"调一个外部 API,把结果做成卡片"。它们是在示范"如何把外部服务包成 Agent 能力"这个模式,不是在提供不可替代的价值。
真正有价值的是插件系统本身:你有内部系统、有私有的 API,可以照这个模板包进来。
总结
三个扩展层,四句话:
- 技能是最轻的:往目录里放 Markdown 就生效。 因为
deepagents首轮会扫skills/目录,Octop 只负责写文件。它本质是"prompt 工程的可持久化形式"——只能教,不能做。 - 知识库是唯一的数据流水线:
parse → ocr → chunk → embed → index → retrieve → citations七段。默认用本地 ONNX 嵌入而不是调 API——这个默认值决定了它到底算不算"自托管"。 - 插件是最重的,但上限也最高。
plugin.yaml三个关键字段:kind(tool / channel)、requires(可声明 PyPI 依赖)、ui(能带自己的前端卡片)。正因为能带 UI,才有了第 4 篇那个OctopUiOffload中间件。 - 27 个内置插件里 24 个是生活娱乐,它们的作用是"把插件系统演示一遍",而不是提供核心能力。真正的价值在模板本身。
还有个跨篇的观察:这三层恰好对应我前面读过的三个中间件——KnowledgeSearchHintMiddleware(知识库那层)来自 knowledge/hint.py,OctopUiOffloadMiddleware(插件那层)为插件的 UI 卡片服务,而技能那层根本没有中间件,因为它不需要侵入运行时。
“需要的侵入越少,扩展成本越低。” 这大概就是这三层最本质的区别。
到这里这个系列的九篇就齐了。按编号往下是 (8)多用户隔离与配额、(9)gateway 与 IM 通道——前八篇讲的是"系统怎么运转",最后两篇是横向切的两刀。
参考链接
- 仓库:https://github.com/TencentCloud/Octop(MIT)
- 本文主读目录:
src/octop/infra/skills/(3,337 行,12 个模块)src/octop/infra/knowledge/(2,325 行,16 个模块)src/octop/infra/agents/plugins/(4,089 行,含bundled/27 个插件)src/octop/infra/agents/builtin_skills/(技能同步)
- 依赖机制:
deepagents首轮扫描skills/目录 - 前一篇:(6)流式投影层 · (4)9 个中间件
