dsh-extras

@catheadowl/dsh-extras

English | 中文

做 harness 就是做 docs。@catheadowl/dsh-extras 是一次 opinionated 的尝试：让 dsh agent 所依赖的知识做到文档健康与可导航。它把两个常用的 dsh hook 包装成可组合的基础框架——agent/turn-stopping（轮末）上的 gates 与 agent/pre-step 上的 enrichment，各给一个服务键注册面（ctx.gates / ctx.enrichment，消费插件经宿主软依赖注入接入），而不是每个插件各自裸挂 hook——并随包交付该立场的落地：Markdown 链接治理、按路径注入上下文、知识库路由视图。

dsh plugin add 一次全装，每个模块是组合里可独立开关的一行（按行 id 标识），不需要的行关掉即可，互不影响。本包与 dsh 宿主的关系、为什么要包装宿主 hook，见 docs/host.md。

安装

dsh plugin add @catheadowl/dsh-extras

要求：已安装 dsh CLI。所有运行时依赖由 dsh 宿主提供（peerDependencies，plugin add 时随宿主解析），本包自身只带少量纯 JS 工具依赖。

模块

扩展框架（面向消费插件的注册面）：

工具与消费行：

每个模块是宿主插件组合里可独立开关的一行：不共享状态，关掉任何一行，其余模块行为不变。

配置

在你的 profile patch 层按行 id 单关一个模块：

- id: gates
  disabled: true

带默认配置的模块可覆写。各行的全部配置键：

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

模块上下架走包版本更新：升级本包后 dsh plugin update 收缩/扩展组合行。

API 面

除组合行外，本包导出插件开发者消费的稳定子路径：

• @catheadowl/dsh-extras/markdown/gate-check——markdown 模块的仓库级 gates.yml 回退入口（通用 check）。

在 gates / enrichment 框架上构建的消费插件不 import 本包：经服务缝（ctx.gates.register(...) / ctx.enrichment provider 注册表）以宿主 ctx.inject 软依赖接入、不携带对本包的依赖——配方见各框架模块文档。 Web 配置页（插件页 gates / enrichment 行的 Configure 页）随本包内嵌合成装载，不需要单独安装。

模块间依赖拓扑与对外消费面（exports 对账）见 docs/dependencies.md。

开发

# 从仓库根目录
pnpm run build                  # 四模块 lib + client bundle
pnpm run test:gates             # 各模块单测（test:markdown / test:enrichment / test:routes）
pnpm run verify:package-face    # exports / facade 校验
pnpm run verify:publish-readiness  # 发布卫生校验（docs locality、host closure 等）

开发细节——宿主 checkout 摆放、工具链借用、peer junction 接线、host-closure 网络检查——见 docs/development.md。

已知限制

• 需要 dsh CLI（本包是插件载体，不是独立应用）；运行时 peer 全部由宿主闭包提供。
• 根 README 双语（英文主 + 中文），模块页与深度 docs 以中文为主。
• Web 配置页目前仅 gates / enrichment 两行有（插件页行级 Configure，随内置 client 子包 modules/client 合成装载，不单独发布）。
• gates 连续阻断上限（maxConsecutiveBlocks，默认 3）耗尽后降级放行——是安全阀不是正确性保证；markdown / routes 行无插件配置键。

License

MIT