CI 已经绿了，为什么你的 Agent 还在用旧规则？

升级一个 Agent 工具，最容易被忽略的不是 npm install 失败，而是安装成功之后的"半更新"。

包管理器里已经是新版本，某个 Agent 目录下的 SKILL.md 却还是旧版本；项目里的 .boss 事件流末尾多了一行残缺 JSON；CI 只跑了测试，没有人知道本机到底装成了什么状态。

这类问题很少在发布当天暴露。它们通常出现在几天后的复盘里：同一个命令，在两台机器上给出不同结果。

Boss Skill 3.10.1 的一个小改动很值得单独看：CI 在 build 后运行 boss doctor --json，而 doctor 不只检查 Node 和 Git，还会检查已安装 skill 的版本、.boss 事件流完整性和孤儿 lock。它没有把环境问题包装成"自动修复"，只是把漂移变成可见、可机器读取的诊断结果。

"包是新的"不等于"运行时是新的"

packages/boss-cli/src/commands/doctor.ts 在启动时读取当前包的 package.json 版本。接着 checkInstalls() 遍历支持的 Agent 安装目标：

ts 复制代码

const skillMd = path.join(dest, 'SKILL.md');
const installedVersion = readSkillVersion(skillMd);
const versionMatch = installedVersion === pkg.version;

checks.push({
  name: `install:${agent.name}`,
  status: versionMatch ? 'ok' : 'warn',
  detail: versionMatch
    ? `已安装 v${installedVersion}（与当前包一致）`
    : `已安装 v${installedVersion ?? '未知'}，当前包为 v${pkg.version}（建议重装）`,
});

注意它检查的是"目标目录里的实际文件"，不是 npm lockfile。因为 Boss 的运行规则最终会从安装目录被 Agent 读取；lockfile 只能说明你下载了什么，不能证明每个 Agent 的 SKILL.md 已经同步。

这条判断对所有会把规则复制到多个宿主的工具都适用：包版本是供应链状态，安装目录版本才是执行状态。

flowchart LR A[包管理器里的 3.10.1] --> B[Agent 安装目录] B --> C[读取实际 SKILL.md 版本] C --> D[boss doctor --json] D -->|ok| E[继续执行] D -->|warn| F[人工确认并重装]

为什么 doctor 把版本漂移标成 warn

doctor 返回三种状态：ok、warn、error。安装缺失或版本不一致是 warn，事件流中间行损坏才是 error；最终只有 error 才让命令以非零码退出。

这不是放松检查，而是把"能继续工作"和"不能相信结果"分开：

某个 Agent 没安装 Boss，可能只是你没有启用它，跳过即可；
已经检测到 Agent，但目录里是旧 SKILL.md，应该提醒重装；
.boss/<feature>/.meta/events.jsonl 中间行损坏，投影无法可靠重建，才需要阻断。

如果把三种情况都当 error，CI 会因为一台没有安装某 Agent 的 runner 频繁失败；如果全都当 ok，版本漂移只能等用户自己发现。

事件流末尾损坏，和中间篡改不是一回事

Boss 的 feature 状态来自 .boss/<feature>/.meta/events.jsonl。checkFeatures() 用 tolerant reader 读取它：

ts 复制代码

const { records, corruptTail } = readJsonlTolerant(eventsFile);
if (corruptTail !== undefined) {
  // 疑似写入中途崩溃：提示并跳过末尾残片
  status = 'warn';
} else {
  status = 'ok';
}

如果损坏只在文件末尾，常见解释是进程写入 JSON 的过程中被杀掉。doctor 会报告"末尾有损坏行"，让投影器跳过这段残片；如果中间行损坏，代码会返回 error，因为这更像磁盘错误、篡改或不可恢复的结构破坏。

这两个状态不能混在一起。末尾残片可以保留人工检查的机会，中间缺口会让后续事件的顺序失去可信度。

孤儿 lock 也值得被报出来

doctor 还扫描每个 feature 的 .meta 目录。残留的 *.lock 会被标成 warn，提示只有在确认没有运行中的进程后才能清理。

它没有直接删除 lock，也没有假定 lock 一定是坏的。诊断命令只告诉你："这里有一个需要判断的状态。"

这是一种很朴素的工程边界，却经常被自动化脚本破坏：把清理动作塞进健康检查，短期看起来干净，长期可能误删正在使用的锁。

CI 为什么要在 build 之后跑 doctor

公开提交 d7ebc91e335dc2e4120fb2ae5b3b5f02f0482bcd 在 .github/workflows/ci.yml 里增加了：

yaml 复制代码

- name: Build
  run: npm run build
- name: Doctor (version consistency)
  run: node packages/boss-cli/dist/bin/boss.js doctor --json
- name: Test
  run: npm test

顺序很有意思。doctor 调的是 dist/bin/boss.js，不是 TypeScript 源文件。这样检查到的是"刚刚构建出来、将要被打包的 CLI"，能顺便发现构建产物和源代码不一致的问题。

它放在测试前，也让安装/事件流诊断和单元测试分开。测试通过只说明测试场景通过；doctor 的 --json 输出则可以被 CI、发布脚本或其他 Agent 继续消费。

当前 npm 可核对的 Boss Skill 包 @blade-ai/boss-skill 是 3.10.1；仓库里的 packages/boss-cli/package.json 也声明 @blade-ai/boss-cli 3.10.1，但这不等于我已经核验了该 CLI 子包的独立公开发布。本文没有把 CI 的绿灯当成我本地重新跑出的 release 证明，重点只在公开代码里能核对的检查顺序和返回语义。

内置资产和项目资产，谁覆盖谁

同一提交还把插件、流水线包和 schema 当作 CLI 资产管理。packages/boss-cli/src/runtime/assets.ts 先读取内置目录，再读取项目 .boss/ 下的同名 manifest：

ts 复制代码

function mergeByName(builtin, project) {
  const byName = new Map();
  for (const item of builtin) byName.set(item.name, item);
  for (const item of project) byName.set(item.name, item);
  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
}

也就是说，项目资产会覆盖同名内置资产。这给团队定制留下空间，但也带来一个读者必须知道的边界：升级 Boss 并不会自动替你审查项目 .boss/plugins/ 下同名插件是否仍符合新 schema。

plugin-schema.json 至少把 name、version、type 设成必填，并限制插件类型为 gate、agent、pipeline-pack、reporter。真正接入时，版本、hook 路径和启用状态仍需要项目自己的验收。

把 doctor 接进自己的交付流程

如果你的 Agent 会把规则安装到多个目录，可以先采用三步：

bash 复制代码

# 构建后检查当前产物
node packages/boss-cli/dist/bin/boss.js doctor --json

# 只把 warn 当成需要人工处理，不要自动删 lock
# error 才阻断后续发布

然后把输出保存成构建工件，至少记录：当前包版本、每个 Agent 的安装版本、feature 事件流状态、孤儿 lock 数量。下次复盘时，你能回答"当时跑的到底是哪一套规则"，而不是只能猜机器上有没有执行过安装命令。

这套做法也适用于插件系统、编辑器扩展和 CI action：执行面越分散，越需要一个只读诊断命令把"声明版本"和"实际执行版本"放到同一张表里。

Boss doctor 不会替你修复旧安装，也不会替你判断一个孤儿 lock 能不能删。它做的事情更小：在 Agent 开始给出结论之前，先把环境里那些不值得信任的地方标出来。

源码依据 ：Boss Skill 3.10.1，公开提交 d7ebc91e335dc2e4120fb2ae5b3b5f02f0482bcd，packages/boss-cli/src/commands/doctor.ts、packages/boss-cli/src/runtime/assets.ts、packages/boss-cli/assets/plugin-schema.json、.github/workflows/ci.yml。