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

文章目录

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

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

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

版本锚点:本文基于 octop v1.0.2(commit dd9dce4)、deepagents 0.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,可以照这个模板包进来。

总结

三个扩展层,四句话:

  1. 技能是最轻的:往目录里放 Markdown 就生效。 因为 deepagents 首轮会扫 skills/ 目录,Octop 只负责写文件。它本质是"prompt 工程的可持久化形式"——只能教,不能做。
  2. 知识库是唯一的数据流水线: parse → ocr → chunk → embed → index → retrieve → citations 七段。默认用本地 ONNX 嵌入而不是调 API——这个默认值决定了它到底算不算"自托管"。
  3. 插件是最重的,但上限也最高。 plugin.yaml 三个关键字段:kind(tool / channel)、requires(可声明 PyPI 依赖)、ui(能带自己的前端卡片)。正因为能带 UI,才有了第 4 篇那个 OctopUiOffload 中间件。
  4. 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 个中间件