从本地数据揭秘WorkBuddy:插件四层加载 — 安装 ≠ 启用 ≠ 加载 ≠ 实例化

"

系列第 5 期。从 ~/.workbuddy/plugins/ 的真实本地数据出发，拆解 WorkBuddy 插件系统的四层加载机制。

引子：48 个插件，只有 10 个被"启用"

打开 ~/.workbuddy/settings.json，enabledPlugins 字段赫然在列：

{

  "weixinpay@workbuddy-builtin": true,

  "tencent-docs-plugin@workbuddy-builtin": true,

  "tencent-pptx@workbuddy-builtin": true,

  "agent-browser@codebuddy-plugins-official": true,

  "find-skills@codebuddy-plugins-official": true,

  "sheetagent@workbuddy-builtin": true,

  "tencent-docx@workbuddy-builtin": true,

  "document-skills@cb_teams_marketplace": true,

  "finance-data@cb_teams_marketplace": true,

  "playwright-cli@codebuddy-plugins-official": true

}

38 个已安装但未启用的插件，难道就是"死代码"？

01

数据现场：四个文件，四层真相

{

  "version": 2,

  "plugins": {

    "find-skills@codebuddy-plugins-official": [{

      "scope": "user",

      "installPath": "~/.workbuddy/plugins/cache/codebuddy-plugins-official/find-skills/1.0.0",

      "version": "1.0.0",

      "installedAt": "2026-08-24T07:38:32.237Z",

      "lastUpdated": "2026-09-13T05:31:42.328Z"

    }],

    "skill-ardot-slides@workbuddy-builtin": [{

      "scope": "user",

      "installPath": "~/.workbuddy/plugins/cache/workbuddy-builtin/skill-ardot-slides/5.5.6-...",

      "version": "5.5.6-wb.38337834...",

      "installedAt": "...",

      "lastUpdated": "..."

    }],

    ...

  }

}

{

  "weixinpay@workbuddy-builtin": true,

  "tencent-docs-plugin@workbuddy-builtin": true,

  ...

  "playwright-cli@codebuddy-plugins-official": true

}

~/.workbuddy/plugins/cache/workbuddy-builtin/

├── weixinpay/1.6.109/.in_use/

│   ├── 24239        ← 空文件，每个 agent 进程一个

│   └── 43783

├── tencent-docx/5.5.6-.../.in_use/

│   ├── 24239

│   └── 43783

├── interactionmode-craft/0.1.4/.in_use/

│   └── (当前为空——因为 craft 是默认模式，锁在活跃会话中)

├── prompt-common/0.1.2/.in_use/

│   └── (同上)

...

tools:

  - Read

  - Write

  - Edit

  - Bash

  - ...

  - Defer(SkillManage)

  - Defer(LSP)

  - Defer(ImageGen)

  - Defer(VideoGen)

  - Defer(TeamCreate)

  - Defer(TeamDelete)

  - Defer(conversation_search)

  - Defer(workbuddy_cloudstudio_deploy)

02

四层串联：一张图看完整生命周期

安装（Installation）

│  installed_plugins.json 登记 48 个

│  插件文件落盘 plugins/cache/<source>/<name>/<version>/

│

├─ 启用（Enablement）

│  │  settings.json → enabledPlugins: 仅 10 个 true

│  │  闸门条件：是否为"主动能力型"（需起 MCP / 注册连接器 / 注入 agent）

│  │

│  ├─ 被动常驻型（welcomemode / interactionmode / prompt-common）

│  │  │  不走 enabledPlugins 闸门

│  │  │  靠 .in_use/<pid> PID 锁标记"谁在用"

│  │  │  每个 agent 进程启动时自动加载

│  │  │

│  │  └─ 加载（Loading）

│  │     片段注入 system prompt（Jinja include）

│  │     工具白名单生效（interaction.md → function calling schema）

│  │

│  └─ 主动能力型（weixinpay / sheetagent / tencent-docx / ...）

│     │  enabledPlugins = true → 注册进运行时

│     │  MCP server 启动 / 连接器注入 / agent 注册

│     │

│     └─ 实例化（Instantiation）

│        部分能力 defer_loading：首次 function_call 才拉起

│        DeferExecuteTool 26 次 = 延迟实例化的运行时痕迹

│

└─ 按需加载型（28 个 skill-*）

   │  不走 enabledPlugins，不走 .in_use

   │  靠 Skill 工具 + 目录约定发现 SKILL.md

   │  云端 LLM 读 <available_skills> 列表 → 按 description 触发

   │

   └─ 实例化

      命中后读 SKILL.md 注入上下文

      后续该 skill 内的工具 / 脚本 / 命令可用

03

两种血统标记：.workbuddy-plugin vs .codebuddy-plugin

interactionmode-craft/0.1.4/.workbuddy-plugin/plugin.json   ← 瘦 schema

welcomemode-code/0.1.7/.workbuddy-plugin/plugin.json        ← 瘦 schema

prompt-common/0.1.2/.workbuddy-plugin/plugin.json           ← 瘦 schema

skill-ardot-slides/5.5.6-.../.codebuddy-plugin/plugin.json  ← 全 schema

weixinpay/1.6.109/.codebuddy-plugin/plugin.json             ← 全 schema

sheetagent/5.5.6-.../.codebuddy-plugin/plugin.json          ← 全 schema

04

被动常驻 vs 按需加载：为什么 skill-* 不进 enabledPlugins？

为什么？

05

对比：其他框架怎么做？

06

深层设计：能力生命周期管理

07

工程启示：造 Agent 工具时，从第一天就分层

不要把"安装"和"启用"混为一谈。

◆安装 = 文件落盘（磁盘成本）

◆启用 = 运行时注册（启动成本）

◆加载 = 上下文注入（上下文成本）

◆实例化 = 实际拉起（运行时成本）

01被动片段（提示词、行为协议）→ 加载层，不进启用层

02知识包（skill、领域知识）→ 实例化层，不进启用层也不进加载层

03运行时服务（MCP server、连接器）→ 启用层，冷启动注册

04重能力（图像生成、LSP、部署）→ 启用层 + defer_loading，首次触发才拉起

结语