rand0wn/dsh-minimal-anchor

dsh-minimal-anchor

CI

一个 DeepSeek Harness（dsh）插件，用于保护第一轮对话免受工具 schema 过载的影响。

为什么

一个全新的 dsh 会话会在第一条消息时就把整个已配置的工具集交给模型——文件编辑、bash、子代理、任务——即使第一条消息只是“看看这个仓库，告诉我发生了什么”。在第一轮使用更小、更聚焦的 schema，可以让模型的早期推理专注于探索，而不是过早行动，同时不影响后续任何轮次的行为。

dsh-minimal-anchor 挂钩 harness 自身的提示词组装流水线，以：

1. 仅在第一轮裁剪工具 —— 缩减到可配置的白名单（默认：read、glob、grep）。
2. 在同一轮前置一段简短的结构性前言，将本次会话定位为探索优先。
3. 从第二轮起不再干预 —— 该会话后续的每次组装都完全原样通过，完整工具集恢复。

安装

dsh plugin --profile  add dsh-minimal-anchor

或从本地检出安装：

dsh plugin --profile  add /path/to/dsh-minimal-anchor

这会将包添加为该 profile 的依赖，但本身并不会激活它 —— dsh 只会为列在该 profile 的 dsh.profile.bundles 中的包应用其 dsh.bundle 补丁。请将包名添加到 profiles//package.json 中的该列表：

{
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-headless",
"dsh-minimal-anchor"
]
}
}
}

使用 dsh --profile  --dump-config 确认它已被组合进去 —— 你应该会看到一个 minimal-anchor 条目。（另一种完全跳过 bundles 列表的等效方式：直接将其插入到你自己的 profiles//cordis.patch.yml 中 —— 参见配置。）

用法

无需调用任何东西 —— 它是一个被动插件。像往常一样启动你的 profile（dsh web、dsh --profile headless "..." 等），每个新会话的第一轮都会自动带着裁剪后的工具列表和前言发出。

配置

profiles//cordis.patch.yml
- insert:
- id: minimal-anchor
name: 'dsh-minimal-anchor'
config:
whitelistedTools: [read, glob, grep]
enforcePreamble: true
customPreamble: 'Your own turn-1 framing text.'

| 字段 | 默认值 | 描述 |
| --- | --- | --- |
| whitelistedTools | [read, glob, grep] | 第一轮保留的工具名称。必须与你的 profile 中注册的确切工具名称匹配 —— 如果不确定，请检查 dsh --profile  --dump-config，不同插件的名称各不相同。 |
| enforcePreamble | true | 是否在第一轮前置结构性前言部分。 |
| customPreamble | （内置的探索框架文本） | 前言文本，仅在 enforcePreamble 为 true 时使用。 |

是扩展而不是替换默认白名单？如果你是用 TypeScript 而不是 YAML 来组合配置，DEFAULT_WHITELISTED_TOOLS 和 DEFAULT_PREAMBLE 会从该包中导出。

工作原理

挂接来自 @deepseek-ai/dsh-system-prompt 的 system-prompt/assemble 瀑布流，该瀑布流每轮运行一次，并生成实际发送给模型的 PromptAssembly（sections、tools、contexts）。一个以 assembly 的 scope 为键的 WeakSet 会跟踪该 scope 之前是否已经组装过；第一次时，它会将 assembly.tools 过滤为白名单，并将前言 section 插入到最前面，然后调用 next()，以便瀑布流中的其他所有监听器仍能正常运行。之后针对该 scope 的每次组装都会直接短路到 next() —— 不进行任何变更，除了 WeakSet 条目之外不持久化任何按会话的状态，而该条目无需显式清理，因为它会随 scope 对象一起消亡。

真实的 harness 中不存在 agent/request 或按消息的 hook —— 本插件不使用它，这与同一想法的早期草稿不同，后者假设了 dsh 中并不存在的事件。

故障排除

第 1 轮的工具列表返回为空。 whitelistedTools 按注册工具的确切名称进行匹配 —— 这些名称会因 harness 安装以及你启用的其他插件而有所不同。使用 dsh --profile  --dump-config 查看真实名称，或者在 Web UI 中打开某个会话的 Trajectory 标签页，查看“Initial System Prompt”上的 Tools 面板。本插件的早期草稿附带的是猜测的名称（read_file、list_dir、search_files），这些名称在真实 harness 中并不存在 —— 白名单静默地匹配不到任何内容，并剪掉了所有工具。

插件似乎没有加载 / --dump-config 中没有 minimal-anchor 条目。 仅作为 profile 中列出的 dependency（例如在执行 dsh plugin add 之后）还不够 —— 该包还必须位于该 profile 的 dsh.profile.bundles 列表中（参见 Install），然后它的 dsh.bundle 补丁才会被应用。

在某个 fork 上，加载器崩溃并报 Cannot read properties of undefined (reading 'validate')。 Cordis 插件导出的 Config 必须是 schemastery schema（z.object({...})），而不是普通对象 —— 加载器会对 Config 导出的任何内容调用 .validate。

开发

npm install
npm run typecheck
npm test

已针对真实的本地 dsh 启动进行验证（而不仅仅是类型）：安装到一个临时 profile 中，打补丁进去，并针对一个实时模型运行 —— 第 1 轮的出站请求恰好携带了白名单中的工具和前言文本，第 2 轮则携带了完整工具集且没有前言。

许可证

MIT