# 改了专家包却不生效：从源包到缓存的六层根因与五步修复链

## 一、症状：改了、重启了、回答还是旧的

先说一个具体场景。

你给自建的某个专家团补了一条硬性规则，比如"输出前必须先核对版本号"，写进了成员 MD 里。保存，重开会话，问同一个问题——回答还是旧逻辑。你怀疑是改错了地方，回去复读一遍，规则确实在那儿。你重开会话，还是旧的。你重启电脑，还是旧的。

到这里，大部分人会把结论落到"平台有 bug"。但真不是。

问题的实质是：**你改的那个目录，和平台运行时真正加载的那个目录，不是同一个目录。** 中间隔着一层缓存和一张注册表。你改了源，没动缓存，平台读的还是旧缓存里的那份。它工作得很正常，正常得让人以为是坏了。

结论先行：自建专家包的改动要生效，必须走一条固定的链路——改源包、升版本、覆盖缓存、重写注册表、彻底退出重开。少任何一步，现象都是"改了不生效"。下面按「症状 → 定位 → 根因 → 修复 → 复验」把这五段讲透，最后给一份可以直接照抄执行的 checklist 和脚本。

## 二、前提：自建 marketplace 本来就不自动更新

动手排查之前，先把预期校准一下，否则你会一直在找不存在的 bug。

WorkBuddy 的专家/插件来源大致分两类：

- **官方 marketplace**，例如 `cb_teams_marketplace`、`codebuddy-plugins-official`。这类在配置里带 `autoUpdate: true`，平台会自行拉取新版本，你几乎感知不到更新过程。
- **自建 marketplace**，本文涉及的 `my-experts` 就属这一类。它**没有自动更新**，完全靠你手动推进。

所以"改完不生效"不是故障，是这套机制的默认行为。官方源养出来的直觉——"改完刷新一下就能看到"——在自建源上不成立。接受这个前提，后面的排查才有意义：我们要做的不是修 bug，而是把人工更新链路走完整。

这三层的存在都有其理由：源包给你一个可编辑的稳定位置，注册表负责索引，缓存负责在会话启动时快速加载、也能随时回滚到某个历史版本。代价就是"改完即刻可见"这件事被牺牲掉了。理解了这一点，排查方向就不会跑偏——我们要找的不是"哪个配置写错了"，而是"哪一层还停留在旧状态"。

## 三、定位：三处路径，第三处最容易找错

排障的第一步是把路径摆清楚。自建专家包涉及三处，角色各不相同。

**源包（唯一真源）**

`~/.workbuddy/plugins/marketplaces/my-experts/plugins/<包名>/`

这是你日常编辑的地方，所有修改都应该只发生在这里。把它当成源码仓库：别处一律不改，改了一律会被覆盖掉。

**缓存包（运行时真正加载的那份）**

`~/.workbuddy/plugins/cache/my-experts/<包名>/<版本>/`

平台启动时从这里读成员定义和规则。**这一层承载了绝大多数"改了不生效"的物理根因。** 注意路径里带版本号，这个细节后面会用到。

**注册表**

`~/.workbuddy/plugins/marketplaces/my-experts/.codebuddy-plugin/marketplace.json`

这里最容易找错：它**不在** `my-experts` 的根目录，而在 `.codebuddy-plugin/` 子目录下。很多人翻遍根目录没找到，就判断"注册没写成功"，于是反复重试，时间全耗在假问题上。

三者的关系可以压缩成一句话：源包给你改，注册表告诉平台"有哪些包、在哪个版本"，缓存才是真正被读的那份。三层里任何一层断链，行为就停在旧版本，而表象完全一致——这也是这个问题难查的根本原因。

**一条快速判定命令**

怀疑哪一层是旧的，不用逐个文件打开看，直接比源包和缓存的差异：

```bash
diff -r ~/.workbuddy/plugins/marketplaces/my-experts/plugins/<包名>/agents \
        ~/.workbuddy/plugins/cache/my-experts/<包名>/<版本>/agents
```

没有输出说明两边一致，问题在别处；有输出且列出的正是你改过的那段规则，就坐实了"改了源、没动缓存"。把 `agents` 换成 `skills` 可以再查一遍技能目录。这条命令能在三十秒内把嫌疑范围缩到一层，比逐文件比对省事得多。

## 四、六层根因，按命中频率从高到低

### 根因 1：Team 型包根目录缺 settings.json（头号）

这是一个多成员专家团最常见的硬伤。Team 型包必须**在包根目录**放一个 `settings.json`，内容是指定团长：

```json
{
  "agent": "<包名>-team-lead"
}
```

缺了它，`validate_expert.py` 会报 `Team type must have settings.json`，随后 register 直接拒绝执行。

容易被忽略的一点是：**源包根和缓存根两处都要有。** 只在源包放了，缓存里没有，运行时照样加载不起来，而且报错信息未必再出现——你会看到"成员不响应"这类更模糊的现象，很难联想到这个文件。

反过来也要注意：单人角色包不需要这个文件。只有团长加成员的 Team 型结构才依赖它指定入口，别给所有包都无脑加一个。

### 根因 2：版本号没 bump

`.codebuddy-plugin/plugin.json` 里的 `version` 字段没升。

回到上一节的缓存路径：`cache/my-experts/<包名>/<版本>/`。缓存是按版本号分子目录的。版本号不变，旧目录会被继续复用，你新写的内容根本没机会进去。

规则很简单：**改动内容必升版本**，哪怕只是 `0.9.0` 到 `0.9.1`。把这件事当成提交前的强制动作，不要靠记忆。

判断当前加载的是哪个版本也很直接：

```bash
ls ~/.workbuddy/plugins/cache/my-experts/<包名>/
```

列出的是历次生成的版本目录，最大的那个通常与 `plugin.json` 里的最新 version 对应。如果这里没有出现你刚改的版本号，说明第 3 步还没执行——不用往下查了，回到下面第五节的第 3 步。

### 根因 3：缓存覆盖不完整

最常见的偷懒方式是：手工把 README 和几个 MD 拷过去就算完。缺件会分别导致不同后果：

- 漏 `.codebuddy-plugin/` → 整个包不被识别为合法包，等于没拷
- 漏 `agents/` → 团长在，成员加载不到，表现为"只有一个角色在说话"
- 漏 `skills/` → 成员能登场，但拿不到技能脚本
- 漏 `settings.json` → 回到根因 1

必须全量覆盖，一个都不能少：`.codebuddy-plugin/`、`agents/`、`skills/`、`settings.json`、`README.md`。

### 根因 4：写入方式本身就不可靠

这一层最隐蔽，也最容易白花时间。有两个坑值得单独拎出来。

**坑一：Write 工具写 settings.json 的"假成功"。** 调工具写小配置文件，返回成功，但随后再查这个文件——查无此物。它确实没落盘。不要相信这类返回，改用在 Python 里直接直接落盘：

```python
from pathlib import Path
import json

pkg = Path.home() / ".workbuddy" / "plugins" / "marketplaces" / "my-experts" / "plugins" / "<包名>"
content = {"agent": "<包名>-team-lead"}

(pkg / "settings.json").write_text(
    json.dumps(content, ensure_ascii=False, indent=2) + "\n",
    encoding="utf-8",
)

# 复验：写完立刻读回来确认真的落盘了
assert json.loads((pkg / "settings.json").read_text(encoding="utf-8")) == content
print("settings.json written and verified")
```

最后两行的复验不是多余的——这类"假成功"只有回读才能发现。

**坑二：整包复制别用 Copy-Item 式的命令。** 包里含隐藏目录 `.codebuddy-plugin`，这类命令容易拷出嵌套子目录、漏掉 `settings.json`，严重时还会被保护钩子以 `SAFE_DELETE_FAIL_CLOSED` 拦下，留下一个半新半旧的残包。可靠做法是 Python 的 `shutil.copytree`：

```python
import shutil
from pathlib import Path

home = Path.home()
src = home / ".workbuddy" / "plugins" / "marketplaces" / "my-experts" / "plugins" / "<包名>"
cache_root = home / ".workbuddy" / "plugins" / "cache" / "my-experts" / "<包名>"
dst = cache_root / "<新版本号>"   # 例：0.9.1，必须与 plugin.json 里的 version 一致

if dst.exists():
    shutil.rmtree(dst)            # 全删再全拷，避免新旧混杂

shutil.copytree(
    src, dst,
    ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"),
)

# 复验：关键件是否齐全
for must in [".codebuddy-plugin", "agents", "skills", "settings.json", "README.md"]:
    assert (dst / must).exists(), f"missing: {must}"
print(f"cache refreshed at {dst}")
```

末尾那段断言把根因 3 挡在了门外：缺件会当场报错，而不是等到运行时才发现成员加载不到。

### 根因 5：validate 的三条硬约束

脚本校验比想象中严，具体卡在这三条：

- `tags` **必须恰好 3 个**。多一个、少一个都会报 error，不是警告。
- `displayDescription.zh` 建议 **40–50 字**。过短被判信息不足，过长会被截断、在列表里显示不全。
- `defaultInitPrompt.zh` 必须与 `quickPrompts[0].zh` **完全一致**，包括标点和空格。写岔一个字符，validate 不过。

这三条报错信息通常很清楚，照着改即可，麻烦的是它们往往在你想改的是别的内容时一起冒出来，容易把人带偏。先把这三条清干净，再回头看自己的实质改动。

### 根因 6：最容易被误判为失败的那条

`register_expert.py` **只写 `marketplace.json`，不写 `installed_plugins.json`。**

所以你在 `installed_plugins.json` 里看到的仍然是旧版本号——**这属于正常行为**，不代表注册失败。真正的成功标志只有一个：register 的输出里出现 `Registered in marketplace.json`。

见过太多人因为对这个现象理解反了，反复 register、反复改版本，把一个本来一次到位的流程搞成一小时的拉锯。请把这条单独记下来。

## 五、修复：五步链 checklist

下面是可以照抄执行的完整链路。顺序不能颠倒，每一步都有前置依赖。

```text
[ ] 第 1 步  改源包
      · 只改 ~/.workbuddy/plugins/marketplaces/my-experts/plugins/<包名>/
      · bump .codebuddy-plugin/plugin.json 的 version
      · Team 型包：确认源包根目录有 settings.json，内容为 {"agent":"<包名>-team-lead"}
      · 顺手核对 tags 恰好 3 个、displayDescription.zh 40–50 字、
        defaultInitPrompt.zh 与 quickPrompts[0].zh 完全一致

[ ] 第 2 步  validate（传源包绝对路径）
      · 目标：输出 ✅ valid 为止，不要在报错状态下继续往下走

[ ] 第 3 步  全量覆盖缓存
      · 目标目录 ~/.workbuddy/plugins/cache/my-experts/<包名>/<新版本号>/
      · 必须用 shutil.copytree，先删旧版目录，含隐藏目录 .codebuddy-plugin
      · 拷完断言 .codebuddy-plugin / agents / skills / settings.json / README.md 齐全

[ ] 第 4 步  register（传源包绝对路径）
      · 确认输出 Registered in marketplace.json
      · 不看 installed_plugins.json 的版本号，那里不更新是正常的

[ ] 第 5 步  彻底退出 WorkBuddy 后重开
      · 重开会话无效：平台会 resume 原会话，加载的还是旧上下文
      · 重启电脑同样无效，原因同上
      · 可行做法：完全退出应用进程再启动；或从左侧栏「专家」入口重新选中该团、
        开一个全新会话
```

第 2 步和第 4 步用平台自带的 Python 跑，两个脚本在同一目录：

```bash
# 平台自带解释器
PY="C:/Users/admin/.workbuddy/binaries/python/versions/3.13.12/python.exe"

# 脚本目录
SCRIPTS="C:/Users/admin/.workbuddy/plugins/marketplaces/workbuddy-builtin/skills/expert-manager/scripts"

# 源包绝对路径（注意是源包，不是缓存）
PKG="C:/Users/admin/.workbuddy/plugins/marketplaces/my-experts/plugins/<包名>"

# 校验
"$PY" "$SCRIPTS/validate_expert.py" "$PKG"

# 注册
"$PY" "$SCRIPTS/register_expert.py" "$PKG"
```

两个脚本都传**源包绝对路径**，不传缓存路径。validate 出现 ✅ valid、register 出现 `Registered in marketplace.json`，这两步才算完成。

## 六、复验：怎么确认真的生效了

改完别急着用，按下面四条逐项确认，任何一条不过都说明链路走漏了：

- **缓存版本号对了没**：`cache/my-experts/<包名>/` 下的子目录名，是不是这次 bump 的新版本号。
- **缓存内容齐了没**：新版本目录里 `settings.json`、`agents/`、`skills/`、`.codebuddy-plugin/` 是否都在。
- **注册表更新了没**：`my-experts/.codebuddy-plugin/marketplace.json` 里有没有指向新版本的记录。
- **行为确实变了没**：在**全新会话**里，提一个只有新规则才能触发的问题，比对回答是否符合新约束。别在旧会话里测，旧会话会被 resume，测出来永远是旧的。

四条里最后一条才是终判。前三条是必要条件，不是充分条件——目录对了但内容写歪的情况一样存在。

**关于旧版本目录**

`cache/my-experts/<包名>/` 下往往会同时存在好几个版本目录，这是正常的：每次 bump 都会留一份，方便回滚。它们不会互相干扰，但在复验时容易看花眼——请按 `plugin.json` 里的 version 认目录，不要想当然地挑"看起来最新"的那个。

顺带提醒一处容易被忽略的一致性：**注册表中记录的版本号，必须和你实际拷贝到的缓存目录名一致。** 如果 bump 到 `0.9.2` 却把文件拷进了 `0.9.1` 的目录，复验时"版本号是对的""文件是齐的"两条都能通过，但平台依然读不到新内容。真到这时候，`diff -r` 那条命令还是最快的解法。

## 七、症状反查

最后给一份反查清单，下次遇到直接对号入座，不用从头走一遍判断树。

**改了规则，行为完全没变**

- 缓存版本号还是旧的 → 第 3 步没做，或版本号没 bump
- 缓存是新版但没有 `agents/` → 覆盖不全，回到第 3 步重拷
- 以上都是新版且齐全 → 第 5 步没做，你还在被 resume 的旧会话里

**成员加载不到，只有一个角色在说话**

- 检查缓存包根目录是否有 `settings.json`
- 检查 `agents/` 是否随包拷过去

**validate 报 Team type must have settings.json**

- 源包根目录缺 `settings.json`
- 补充时注意：用 Python 写，写完回读确认

**register 之后 installed_plugins.json 显示旧版本**

- 正常现象，register 不写这个文件
- 只看 register 自身的输出是否出现 Registered in marketplace.json

**validate 一直报字段类错误**

- 数一遍 `tags` 是不是恰好 3 个
- 看 `displayDescription.zh` 是否在 40–50 字区间
- 比对 `defaultInitPrompt.zh` 与 `quickPrompts[0].zh` 是否逐字一致

**写了 settings.json，回头查却查不到**

- 别信工具返回的成功，用 Python 的 `open().write()` 落盘并回读校验

## 小结

把整件事压缩到最后，其实只有两句话。

第一句：**你改的是源包，平台读的是缓存，中间还隔着一张注册表。** 三方不通，"改了不生效"就是必然结果，跟平台稳不稳定没关系。

第二句：**改动要落地只有一条五步链**——改源包并 bump 版本、validate 到通过、整包覆盖缓存、register 写表、彻底退出重开。少一步都白改，顺序错了也白改。

理解了这条链路之后，自建专家包的维护成本会降一个数量级：不再是"改—重启—发现没变—怀疑人生"的循环，而是一份照着打勾就能收工的清单。真正的功夫不在改规则本身，在于把改动准确无误地送到那个会被加载的目录里去。


你给自建的某个专家团补了一条硬性规则，比如"输出前必须先核对版本号"，写进了成员 MD 里。保存，重开会话，问同一个问题——回答还是旧逻辑。你怀疑是改错了地方，回去复读一遍，规则确实在那儿。你重开会话，还是旧的。你重启电脑，还是旧的。

改了专家包却不生效：从源包到缓存的六层根因与五步修复链

改了自建专家包的成员规则，重开会话、重启电脑还是旧行为？问题不在平台，而在"源包—缓存包—注册表"三层结构。本文按症状→定位→六层根因→五步修复链→复验四条件，给出一条可打勾的排查链，含 Write 假成功、Copy-Item 失效两个写入陷阱的 Python 替代方案。

开发工具

职业发展

后端

自建专家包修改不生效的根因是源包与缓存目录不一致，中间隔着注册表。需沿五步修复链操作：改源包并升级版本号、validate校验通过、全量覆盖缓存、register写注册表、彻底退出重开新会话。本文详解六层根因排查与可执行checklist，助你一次修复到位。

代码解释

解释器

WorkBuddy 

Python

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

改了专家包却不生效：从源包到缓存的六层根因与五步修复链-腾讯云开发者社区-腾讯云

改了专家包却不生效：从源包到缓存的六层根因与五步修复链

改了专家包却不生效：从源包到缓存的六层根因与五步修复链

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐