dbskill 更新机制解读：dbs-update 的双渠道同步、旧入口清理与版本契约校验-育师

dbskill 更新机制解读：dbs-update 的双渠道同步、旧入口清理与版本契约校验

【免费下载链接】dbskilldontbesilent 的商业诊断 Skills项目地址: https://gitcode.com/gh_mirrors/db/dbskill

dbskill 是 dontbesilent 的商业诊断 Skills 工具箱，由 34 个业务 Skill、2 个兼容入口与 1 个更新入口组成。本文只盯住那个唯一的更新入口dbs-update：它负责把本地版本同步到官方最新。读完你能独立判断一次「更新 dbskill」到底动了哪些文件、哪些绝不该碰，以及失败后该做什么。

定位：它在工具箱里的位置

dbskill 的组成可以一句话概括：34 个业务单元 + 2 个兼容入口 + 1 个系统更新入口。前者负责诊断、创作、决策等实际工作，dbs-update则是唯一负责「自我维护」的入口，不掺任何业务逻辑。

它在插件市场里的官方定义如下（见 .claude-plugin/marketplace.json）：

字段	值	说明
`name`	`dbs-update`	与目录`skills/dbs-update`一一对应
`source`	`./skills/dbs-update`	插件源码所在目录
`category`	`workflow-infrastructure`	归入「工作流基础设施」，而非业务诊断类
`keywords`	`dbskill, update, upgrade, maintenance, chinese`	命中「更新 / 升级 / 维护」意图的检索词
`version`	`3.0.3`	与仓库根目录 VERSION 完全一致

触发方式只有一种口语形态：对任意 Agent 说「更新 dbskill」「升级 dbskill」，或在收到更新提醒后回复1；斜杠命令为/dbs-update。注意1只有在上一条回复确实包含更新提醒时才代表执行，没有这个上下文，数字不会被解释成更新意图。

核心流程：更新走的 4 步

dbskill 支持两条安装渠道，且可能同时存在。dbs-update会先探测实际装了哪条，再分别处理，避免给同一用户装出两套副本。

步骤一：识别安装渠道

判断逻辑是两条并列线索：

Claude Code 插件渠道：本 Skill 所在路径包含/.claude/plugins/，或claude plugin list里出现以@dontbesilent-skills结尾的插件；
Skills CLI 渠道：~/.agents/skills/、~/.claude/skills/等目录里有dbs等官方 Skill，且不在插件目录下。

之所以先分渠道，是因为两条渠道的更新命令互不通用——插件用户若误跑 CLI 安装，会凭空多出一套本地副本。

步骤二：按渠道执行同步

插件渠道先刷新市场、再逐个更新，命令形如：

claude plugin marketplace update dontbesilent-skills claude plugin update dbs@dontbesilent-skills

Skills CLI 渠道则走一条幂等的重同步命令：

npx -y skills add dontbesilent2025/dbskill -g --all

这里的设计意图值得点破：「安装」与「更新」走的是同一条同步链路。-g表示全局安装，--all表示拉取全部正式 Skill。把更新实现成「重新同步」，本地就永远和官方仓库一致，命令可反复执行而不产生副作用。两种渠道都检测不到时，兜底执行这条 CLI 命令。

步骤三：清理已下线的旧入口

官方历史版本里有三个 Skill 已退役：dbs-hook、dbs-xhs-title、dbs-agent-migration。名单连同各自的官方历史版本指纹，记录在本 Skill 的references/retired-skills.json中。清理规则极其克制——只移除能确认来自官方的副本：插件渠道按名单逐个claude plugin uninstall；本地目录则运行scripts/cleanup_retired_skills.py，它只删失效链接或指向官方旧版本的链接，与官方旧版完全一致的目录会被移到~/.dbs/retired-skills/<时间>/备份，用户改过或同名的自有 Skill 一律保留。环境没有 Python 时跳过脚本，只在回复里列出名单请用户自查。

步骤四：标记时间并确认结果

命令成功后会写入一个时间戳，避免当前对话仍加载着旧 Skill 时反复提醒：

mkdir -p "$HOME/.dbs" && date +%s > "$HOME/.dbs/update_check_at"

随后按渠道提醒重载：插件渠道提示运行/reload-plugins，其余渠道提示新建一次对话。失败时只回一句原因，并把完整终端日志藏起来，除非用户主动索要。

安全边界：5 条硬规则

更新会改写文件，所以边界是这个 Skill 真正的安全核心。skills/dbs-update/SKILL.md 用五条规则钉死了范围：

边界	说明
只同步官方仓库	仅对齐`dontbesilent2025/dbskill`，不从任何第三方源拉取
保留`~/.dbs/`用户数据	存档、报告、决策记录全部原样保留，不覆盖
不动其他 Skill	用户自行安装的 Skill 不在同步范围
清理仅限官方副本	下线旧入口只处理能确认官方的，用户改过的或同名的自有项保留
不建后台任务	不创建定时任务或 Agent Hook，更新是一次性显式动作

其中「保留~/.dbs/」影响最大。dbskill 的dbs-save、dbs-restore、dbs-decision会把诊断状态与决策长期沉淀到本地，这是用户跨对话积累下来的资产。更新只覆盖 Skill 代码本身，绝不触碰这些数据。README.md 的「更新与帮助」小节同样写明这一承诺：

更新会同步官方 dbskill，保留~/.dbs/里的存档和记录，并自动清理已经下线的旧 Skill。

把数据安全写成显式承诺，而不是隐含假设，正是新手最该先确认的一条。

标准话术：成功与失败分别怎么回

为了体验一致，Skill 规定了两套固定模板，可直接照抄。

成功时：

dbskill 已更新完成（{更新的渠道}）。当前对话如果还没有读取到新能力，{插件渠道：运行/reload-plugins；其他渠道：新建一次对话}后即可使用。

若顺带清理了旧入口，追加一句：

已清理下线的旧入口：{名称与位置}。{有备份时：原文件备份在{备份目录}。}{有保留项时：{路径}与官方版本不一致，已保留。}

失败时：

dbskill 没有更新完成：{简短原因}。处理完 {权限或网络问题} 后，再说一次「更新 dbskill」。

这套话术的设计意图可以拆成三点：原因简短化（只给权限或网络两类，不堆日志）、处理对象明确化（指向具体该修的那件事）、恢复动作具体化（再说一次「更新 dbskill」即可重试）。用户不需要读终端，只需要知道下一步。

源码级兜底：发布侧靠什么保证可靠

用户侧只说一句话，可靠却建立在发布侧的两道校验脚本之上。

第一道是 tools/check-plugin-update-contract.py，专门校验「插件可升级的版本契约」：

VERSION必须符合MAJOR.MINOR.PATCH三段式；
市场里每个插件的version必须与VERSION相等；
所有.claude-plugin/plugin.json清单里的version不得与市场版本冲突，否则会覆盖市场版本导致升级错乱；
加--release参数时会对比上一个发布 tag：若某插件版本与上一发布相同，Claude Code 会直接跳过更新。

最后一条解释了为什么「每次升级都必须换版本号」——否则 Agent 侧的更新会因版本没变而静默失效。

第二道是 tools/check-release-versions.py，它把版本一致性从单一市场扩展到全部公开入口：VERSION、市场metadata.version、README 及所有语言翻译版的 Version Badge、主入口skills/dbs/SKILL.md里的DBS_LOCAL_VERSION、以及UPDATE.json的version与notice（20~80 字符且无首尾空白），必须全部指向同一个值。当前仓库VERSION为3.0.3，市场里全部插件的版本号也都是3.0.3，正是这套契约一次通过的落地结果。

两道脚本合起来意味着：用户看到的是「更新 dbskill」这一句话，背后是「版本号必变、多入口一致、契约可自动校验」的完整发布体系。

使用姿势：触发、误用与交接

容易踩错的点，用正误对照看得最清楚：

场景	正确做法
只问版本 / 更新内容 / 要不要更新	先回答问题，不执行命令
明确要检查并希望实际同步	按本 Skill 走更新流程
更新提醒后回复`1`	视为明确要求，直接执行，不再二次确认
想用`npx skills update`	禁用。该命令会连带更新用户装的其他 Skill，越出边界

关于「不二次确认」：只要用户说出了明确的更新指令，Agent 直接进入执行，不反问「你确定吗」。唯一例外是宿主权限——若需要 Shell 授权，由用户在宿主权限窗口里自行决定。

路由侧由主入口/dbs完成分工：skills/dbs/SKILL.md 明确「/dbs-update只在用户明确要求更新，或紧接更新提醒回复1时入选」。也就是说，无论你走/dbs主入口还是直接敲/dbs-update，最终都会汇入同一条更新流程——主入口只识别意图，具体执行全部交给dbs-update。docs/新手入门.md 的「怎样更新」一节也是同一套口径：安装后直接对当前 Agent 说「更新 dbskill」即可，无需复制任何命令。

收尾遵循「不替用户预设下一站」的原则：更新任务本身到此结束。新能力加载完成后，把球交还给主入口/dbs，由它读取你的最新目标，继续路由到该处理的业务 Skill。