DeepSeek Harness 插件套件：质量门控、上下文丰富与 Markdown 工具集

前言¶

在 DeepSeek Harness (DSH) 的开发中，管理智能体运行的知识库健康度、上下文注入以及导航逻辑往往需要编写大量重复的钩子逻辑。直接在各个插件中抓取原始 hook 容易造成依赖混乱和状态管理困难。

@catheadowl/dsh-extras 是一套 DSH 插件套件，旨在通过封装常用的 DSH 钩子提供可组合的基础框架，并附带 Markdown 工具和路由功能，解决文档维护和上下文管理的问题。

这是什么¶

这是一套由 CatheadOwl 维护的 DSH 插件集合，通过 dsh plugin add 命令一次性安装。它将两个常用钩子封装为服务接口（ctx.gates 和 ctx.enrichment），而不是让每个插件都直接抓取底层 hook，从而提供结构化的质量门控、上下文丰富、Markdown 文件重命名以及知识库路由能力。

核心功能¶

该套件包含四个独立可切换的模块：

质量门控框架 (gates)：在回合结束时自动运行。开发者通过 ctx.gates 接口注册门控逻辑。模块 ID 为 gates。
上下文丰富框架 (enrichment)：在 agent/pre-step 阶段运行。它是一个提供者注册表，将路径提及转换为有预算限制的相关上下文。模块 ID 为 enrichment。
Markdown 工具 (markdown)：提供 md_rename 工具（移动 Markdown 文件并重写所有内部链接）以及 doc-link 门控，并内置了链接事务库。模块 ID 为 markdown。
知识路由工具 (routes)：提供 any_nav 工具（在 Markdown 知识库上创建路由视图）以及面包屑相关提供者。模块 ID 为 routes。

安装与启用¶

安装需要 dsh CLI，所有运行时依赖由 DSH 主机提供。

dsh plugin add @catheadowl/dsh-extras

安装后，所有模块作为一个组合行（composition row）出现。你可以通过禁用特定行来独立控制模块，而无需影响其他模块。

配置与使用¶

禁用模块¶

通过配置层禁用特定模块：

- id: gates
  disabled: true

配置 Enrichment 超时¶

enrichment 模块支持配置超时参数：

- id: enrichment
  config:
    providerTimeoutMs: 2000
    totalTimeoutMs: 5000
    renderBudgetChars: 4000

Gates 安全阀配置¶

gates 模块包含一个安全阀配置项 maxConsecutiveBlocks（默认值为 3）。当连续块数耗尽时，门控会降级为通过，这仅作为安全阀，而非正确性保证。

开发与测试¶

若需进行二次开发或验证代码，可使用以下命令：

# 从仓库根目录运行
pnpm run build                  # 构建四个模块库及客户端包
pnpm run test:gates             # 运行门控模块的单元测试
pnpm run verify:package-face    # 验证导出接口

注意事项¶

运行环境：该插件依赖 DSH CLI，且所有运行时依赖由主机提供。
状态隔离：各模块之间无共享状态，可以独立禁用，互不影响。
Web 配置限制：Web 配置页面目前仅支持 gates 和 enrichment 模块。
文档语言：项目根 README 为双语（英语 + 中文），模块文档和深度文档以中文优先。
版本管理：模块的增删通过包版本升级和 dsh plugin update 实现。