DeepSeek Harness 内置 dsh-badge 徽章 skill：设计决策、启用方式与源码实现解析

DeepSeek Harness 内置 dsh-badge 徽章 skill设计决策、启用方式与源码实现解析【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness本文围绕 DeepSeek Harness 中的deepseek-ai/dsh-skill-badge插件展开讲解官方「powered by dsh」徽章 skill 是如何以内置提供方bundled provider的形式随 CLI 交付、默认禁用并支持显式选择加入的。读完本文你将掌握该插件的设计动机与决策过程、在组合配置中启用它的准确写法、dsh-badgeskill 提供的 Markdown 片段与随包 PNG 资源以及其底层基于 Cordis 插件与 skill 注册表的不可变提供方实现原理。问题背景官方徽章有展示、无复用入口Cordis 教程的各个页面都在页尾使用官方的「powered by dsh」徽章用于标识这些文档由 DeepSeek Harness 生成。但交付的 CLI 存在一个明显的缺口既没有一条可复用的指令让模型在其他位置例如用户自己的 PR、Merge Request 或其他文档应用同样的署名徽章也没有一个可显式选择加入opt-in的提供方让部署方按需把该能力暴露给 agent。换句话说徽章看得见但拿不走——官方徽章的标记代码与 PNG 资源散落在文档与网站资产中模型无法像加载普通 skill 那样凭名称发现并遵循其指令。这就是本设计决策要解决的问题。决策一个原生 Cordis 插件注册不可变的内置提供方设计决策的核心是新增包deepseek-ai/dsh-skill-badge。它是一个原生 Cordis 插件会在ctx.skills上注册一个不可变的内置提供方职责划分如下该提供方负责dsh-badge的摘要summary、指令正文skill body和 PNG 资源基底resource basedsh-tool-skill仍然是面向模型的目录catalog与 loader 渲染的唯一归属方——即提供方只管供给 skill目录与加载渲染统一由 tool-skill 消费。这一分工与 skill 子系统文档 中的整体架构一致注册表ctx.skills合并各提供方的目录提供方贡献本地或随包 skillConsumerdsh-tool-skill拥有面向模型的目录与skill工具。dsh-skill-badge正是文档中点名的可选的随包提供方之一。默认禁用启用即显式选择加入交付的 CLI 组合将skill-badge声明为禁用。在基础组合 packages/bundle/base/cordis.patch.yml 中可以清楚看到- id: skill-badge name: deepseek-ai/dsh-skill-badge disabled: true这条设计带来两个重要推论启用这个现有配置行就是显式选择加入。修改为disabled: false或在自定义组合中直接以不带disabled的行覆盖即可激活该提供方禁用它的安装实例不会公开任何徽章 skill也不会获得任何模型可见内容。插件默认不产生任何目录条目、正文或 KV 前缀变化对请求零影响。从源码结构看这种随包但不启用的组合行 disabled门控模式并非孤例同一文件中bash-sandbox、pwsh-sandbox等行也使用disabled: !!js表达式按平台门控说明组合层具备成熟的显式启停约定。启用插件组合行即全部配置该插件没有配置面package.json中除包元数据外不包含任何配置声明源码中也没有读取配置的逻辑。启用只需要把组合行加入组合- name: deepseek-ai/dsh-skill-badge在随附 CLI 组合里由于该行以disabled: true存在因此需要显式启用。一个真实的启用示例见 apps/cli/tests/fixtures/dsh-badge/cordis.yml- id: skill-badge disabled: false - id: skill-filesystem config: watch: false启用后dsh-badge会出现在会话目录的可用 skill 中模型可以像加载任何其他 skill 一样凭名称加载它并遵循其指令添加「powered by dsh」徽章。该插件默认禁用、启用前不增加任何东西——当徽章与部署无关时跳过即可。何时选择该提供方当满足以下条件时选择它用 DeepSeek Harness 生成的内容应当携带官方署名徽章且部署方希望该徽章 skill 对 agent 可用同时无需把 skill 文件手工存入本地 skill 目录如~/.dsh/skills或项目.dsh/skills。徽章 skill 提供什么启用后dsh-badgeskill 向模型暴露两类资源完整定义见随包正文 packages/skill/skill-badge/assets/dsh-badge.mdMarkdown 片段。面向 GitHub/GitLab Markdown 的官方徽章标记指令分为带链接与不带链接两种形式[](https://github.com/deepseek-ai/deepseek-harness)随包分发的 PNG 资源。dsh-badge.png726×120 源图按 121×20 渲染供飞书等无法可靠导入远程图片的系统使用。正文同时给出了明确的使用规则模型加载后必须遵循GitHub 或 GitLab Markdown 使用 Shields.io URL 并链接到项目地址除非用户要求不带链接飞书等远程图片导入不可靠的系统上传随包的dsh-badge.png而不是另造一个徽章保留徽章 121×20 的尺寸与宽高比除非用户指定其他位置否则把徽章放在被署名文档或章节的末尾不得替换颜色、logo、标签或项目 URL。源码级实现不可变提供方的接线方式插件入口 packages/skill/skill-badge/src/index.ts 完整展示了提供方的实现核心要素如下要素实现提供方名称PROVIDER_NAME dsh-badge固定候选项一个SkillCandidatename: dsh-badge、source: bundledrankBUNDLED_SKILL_RANK随包内置 rank即 600资源基底{ kind: directory, path: 包内 assets/ 绝对路径 }正文定位器指向../assets/dsh-badge.md的 URL调用策略{ modelInvocable: true, userInvocable: true }提供方对象本身极其简洁——list()直接Promise.resolve([CANDIDATE])返回唯一候选项get()则通过readFile从随包目录实时读取dsh-badge.md作为content与CANDIDATE的元数据拼成完整的SkillDefinitionexport const name skill-badge export const inject [skills] export function apply(ctx: Context): void { ctx.skills.registerProvider(() provider) }这里有几个值得注意的实现细节同步注册。apply()期间通过ctx.skills.registerProvider()同步注册工厂函数符合 skill 子系统文档 中注册是同步的远程初始化与发现属于list()的 await 阶段的约定注入依赖。插件声明inject: [skills]确保在ctx.skills注册表可用后才挂载包内资源基底。RESOURCE_BASE通过fileURLToPath(new URL(../assets/, import.meta.url))解析为随包assets/目录的绝对路径使正文中的相对引用如dsh-badge.png能被 skill 加载工具正确解析实时读正文。注册表不缓存完整定义每次get()都会重新读取当前正文因此包内正文的修改会在下一次加载时生效。优先级与覆盖约定内置 rank 让位于用户来源该提供方使用排在项目、自定义及用户文件系统来源之后的内置 rank 注册。对照 skill 子系统文档 的本地发现优先级表RankSourceRoot100project-dshprojectRoot/.dsh/skills200project-agentsprojectRoot/.agents/skills300customConfig.customSkillDirs400user-dshdshHome/skills500user-agentsagentsHome/skills600bundled配置了Config.bundledSkillDir时使用该目录dsh-badge正落在 rank 600 的 bundled 档位。这意味着用户自有的dsh-badge定义项目、自定义或用户目录中的同名 skill可以通过注册表的常规优先级约定覆盖内置版本——单层内重名时 rank 越小越优先因此任何本地来源都能赢过内置徽章 skill。文档同时说明该提供方不可变、无配置面且提供方释放dispose时注册表拥有的 effect 会移除该贡献恢复原始状态。曾考虑的替代方案及其否决理由设计过程中曾考虑过另一种实现路径通过dsh-skill-filesystem挂载随包文件把dsh-badge.md与 PNG 作为随包目录交给文件系统提供方发现。该方案被否决理由明确文件系统发现、解析和监视会引入一整套生命周期机制watcher、目录变更失效、git-root 探测等而一个不可变的单一 skill 提供方并不需要这些机制。这正是选择专用 Cordis 插件 不可变提供方的根本原因——用最小的机制面解决最小的需求面。后果与验证测试如何固定行为设计后果徽章指令和源 PNG随 DSH 一同纳入版本管理并通过以随包目录为基础的资源基底解析不依赖外部服务该提供方没有配置面不存在配置错误或误配置空间包测试固定提供方生命周期和官方 PNG 的字节内容无密钥keyless的组装应用快照则固定启用后的目录和已加载的 skill 正文。单元测试packages/skill/skill-badge/tests/skill-badge.spec.ts 中有两条关键测试注册与释放生命周期在new Context()上依次挂载SkillRegistry与SkillBadge后ctx.skills.list()应恰好返回一个dsh-badge候选项校验其名称、描述、调用策略、provider、source 与 resourceBasectx.skills.get(dsh-badge)应能读到包含Preserve the badges 121×20 dimensions的正文fiber.dispose()后list()恢复为空——精确对应提供方释放时注册表 effect 移除该贡献的决策PNG 字节固定读取随包dsh-badge.png断言 PNG 头部的宽高字段为 726×120并校验其 SHA-256 哈希为固定值确保官方资源不被篡改或漂移。组装应用快照E2Eapps/cli/tests/dsh-badge.expected.e2e.ts 通过snapshot.ts脚本对比禁用与启用两种组装结果禁用时模型侧目录不出现任何徽章条目加载dsh-badge会得到Error: skill dsh-badge is unknown or no longer available启用时available_skills中出现dsh-badge条目及其描述加载后skill_content完整呈现正文Assets、两种 Markdown 形式、使用规则并附带以随包assets/目录为基底的资源引导。这组快照从端到端角度验证了本文开头的问题解决闭环默认不可见、启用即可用、资源可解析。已知限制根据包文档 packages/skill/skill-badge/README.zh.md该提供方存在两条明确限制是当前包约束而非任务积压固定一个 skill无运行时自定义——提供方恰好贡献dsh-badge这一个 skill需要其他徽章变体的部署请自行编写 skill例如通过本地 skill 目录以更高优先级覆盖远程 Markdown 依赖 Shields.io——远程徽章标记内嵌 Shields.io 图片目标环境无法可靠获取远程图片时请使用随包分发的 PNG。进一步探索如需深入该提供方所在的注册表与模型渲染链路推荐阅读以下文档与源码skill 子系统参考——该提供方实现的注册表、提供方约定、rank 与目录快照语义skill 包参考——提供方注册到的ctx.skills注册表以及已加载 skill 的共享渲染tool-skill 包——徽章 skill 如何进入会话目录并渲染给模型基础组合配置 packages/bundle/base/cordis.patch.yml——查看skill-badge在交付 CLI 中的默认禁用行组合文档 apps/cli/composition.md——skill-badge在 DSH Base Composition 中的位置。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考