Yu1Ko/dsh-reasoning-support

DSH Reasoning Support

针对 DSV4.1 的 DeepSeek Harness（DSH） 优化插件。目标是在保留完整 Agent 工具和工程流程的同时，让 DSV4.1 的推理表现更接近极简模式。

用途

同一个 DSV4.1，有时能在极简模式下解出问题，却在完整 Agent 的工具、技能和项目上下文中遗漏条件。这个项目针对这种表现落差：给模型一个简洁的研判环境，再让完整 Agent 执行，并在交付前检查结果。

可以用于日常问答、截图驱动的制作任务，以及带文档、代码或其他附件的工程任务。图片和附件会进入辅助流程；工程验收发现缺项时，可以让主 Agent 在同一轮中补检、修复并重新验收。

工作原理

插件由两条互相独立的链路组成：推理研判流水线（额外的模型调用，只影响文本输出）和自适应工具上下文（决定主 Agent 本轮能看到哪些工具）。两者可以分别关闭。

推理研判流水线

在完整 Agent 实施任务之前增加一次简洁研判，在最终答复之前增加一次复核。各阶段使用当前选中的 DSV4.1 模型路线。

flowchart LR
U["原始请求与图片／附件"] --> P["准备可读材料"]
P --> A["简洁上下文研判"]
U --> B["完整 Agent 执行"]
P --> B
A -->|"可错的参考"| B
U --> C["最终复核"]
A --> C
B -->|"草稿、工具结果与预览"| C
C -->|"通过"| D["最终答复"]
C -->|"补证据／修复，有次数限制"| B
C -->|"受阻或达到边界"| E["报告成果与未完成项"]

1. 准备材料：保留原图；直接读取可处理的文本附件。其他格式先由主 Agent 使用读取、解析或预览工具取得内容。
2. 简洁研判：围绕原始请求、相关上下文和已读材料，给出候选答案或简短执行思路、验收项。
3. 完整执行：主 Agent 使用原生工具、Skills 和项目规则完成任务，取得实际产物与检查结果。
4. 验收与修复：复核区分通过、缺少证据、需要修复和受阻。缺证据时先补检查；具体缺陷交回主 Agent 修复，再重新验收。

复核意见是可错的参考，不能扩大用户授权。工具循环不会反复运行前置研判；这条链路不修改主 Agent 的 tools 列表。

自适应工具上下文

adaptive-context.mjs 在组装系统提示时（system-prompt/assemble）重写本次请求的工具表，默认开启（预设条目 reasoning-support-adaptive-context 中为 allTools: false）：

- 首轮只暴露原生工具：NATIVE_TOOLS 中的内置工具，加上插件自注册的 tool_search 与 skill_search。三方插件、MCP 和领域工具默认不进入工具表。
- 按需检索：tool_search 在完整工具目录里按名称和描述匹配（单次最多返回 5 条），命中的非原生工具写入该 Agent 的选择集，下一步即以原生 schema 直接可调用。
- 选择集上限：默认保留最近 12 个（maxAdditionalTools，可配置 5–100）。
- 跨压缩恢复：上下文压缩后，从本会话成功的 tool_search 结果重建选择集。
- 按会话／Agent 隔离：选择集互不泄漏，一个会话检索出的工具不会出现在另一个会话。
- 技能只发现、不注入正文：skill_search 只返回技能名与描述，正文仍需用原生 skill 工具加载；此时原本自动注入的技能目录消息会被压缩为一句短提示。

要让工具表始终完整，把该预设条目的 allTools 改为 true，即关闭裁剪；插件写入的推理指导在此期间仍然生效。

图片与附件

- 图片：原图引用进入研判和复核；工具产生的截图、渲染图也能进入验收，并与原始参考图区分。上传图片后的文字追问继续支持辅助调用。
- 文本与代码附件：通过 DSH 附件服务完整读取并校验后提供正文。默认直接读取最多 2 MiB 的 UTF-8 文件；较长正文会明确标记为摘录。
- PDF、Office、模型文件、压缩包等：由主 Agent 使用环境中可用的解析工具处理，再读取正文或预览。写出解析文件、查询大小或列出页数，不等于模型已经看到了内容。
- 长输入：辅助上下文按预算摘录，并标明省略；主 Agent 的原始输入不被插件改写。单次辅助请求最多保留 16 张图片。

自定义解析脚本可以把输出放在含原附件 SHA-256 哈希的临时路径中，再用 read、read_image 或显示正文的 Get-Content / cat 读取，方便关联原附件与解析结果。扫描 PDF 需要页面图片或 OCR；具体格式需要相应的本地工具。未读取、未解析或省略的部分不能作为已验证内容。

图片输入还需要当前 DSH 提供方路线声明图像能力。 使用 llm-pi-ai 时，在对应的既有 DSV4.1 模型条目中配置：

input: [text, image]

保留该条目原有的其他字段。插件会检查实际调用所绑定的路线能力；图片被替换成文字占位符时，不会记录为视觉验收成功。

安装与启用

需要 Node.js 24 或更新版本，以及已经配置好模型提供方的 DSH。已验证环境为 Windows、Node.js 24.18.0、DSH 0.1.5-rc.1。

本插件是一个 DSH profile bundle：预设随包提供（presets/reasoning-support/），安装后由 DSH 自动接入，不需要手动放置预设文件。

dsh plugin --profile  add dsh-reasoning-support

安装后重启 DSH 使新 bundle 生效，然后在新会话中选择 Reasoning Support 和 DSV4.1。

要把它设为新会话的默认预设，在 DSH 设置中指定 agent-presets.default: reasoning-support。

仓库内另附 install.mjs：它把预设与运行时写入 $DSH_HOME/.agent-presets/，作用范围是机器级，而不是单个 profile。

调用成本与边界

正常流程为 N 次主调用＋1 次前置研判＋1 次首次验收＋R 次复验，即 N＋2＋R。N 包含材料预读、工具循环、补检和修复；内部修复不会重跑前置研判。

默认最多允许 2 轮补检／修复后的复验。从首次验收开始，5 分钟后不再追加修复轮次；单次辅助调用超时为 150 秒。累计已报告的辅助用量达到 200,000 token 后不再发起辅助调用，每次输出上限为 32,768 token。这些限制控制插件增加的工作，不会强行终止正在执行的主 Agent 工具。

重复意见没有带来新的证据或产物变化时，会提前结束修复。取消、新用户要求、过期结果和解析失败也有独立处理。工程验收未完成时，由主 Agent 按原输出格式报告实际成果与未验证项。

里程碑检查默认关闭。 需要检查粗模、首个可运行页面等中间产物时，可在安装后 final-review.mjs 对应的 config 中设置 checkpoint: true。主 Agent 可调用 reasoning_support_checkpoint，每条用户请求最多增加一次里程碑复核；成本单独计为 K，总计 N＋2＋R＋K。

在当前请求中加入 “不要额外模型调用”，可临时关闭辅助流程。使用 “本会话一直不要额外模型调用” 可持续关闭，直到明确要求 “恢复额外模型调用”。子代理不叠加这套辅助流程。调用次数为逻辑调用计数；提供方内部重试及计费以其记录为准。

各阶段状态、答案、耗时和辅助用量记录在 DSH 数据目录的 storages/reasoning-support-audit。

适用模型

本项目针对 DSV4.1 启用辅助流程，支持以下标识：

- deepseek-v4.1、deepseek-v41 及其以 - 开头的后缀变体。
- 带路由前缀的对应标识，例如 codebuddy/deepseek-v4.1-flash。
- deepseek-official 提供方下的 deepseek-flash，在已验证的 DSH 模型目录中显示为 DeepSeek-V41-Flash。

其他模型不触发辅助调用。已测试范围和实际传输记录见验证记录。当前验证覆盖功能和集成路径，尚未给出等预算条件下的正确率或工程成功率提升数值。

卸载

dsh plugin --profile  remove dsh-reasoning-support

移除后重启 DSH。已有会话、运行时文件和调用记录不受影响。

开发与测试

npm test
npm run check
npm run test:native -- --dsh-package "/absolute/path/to/@deepseek-ai/dsh/package.json"

普通测试无需模型账户。原生集成测试使用真实 DSH 循环、文件工具和附件服务，以及确定性的本地测试提供方；PDF 用例需要 Python 与 pypdf。可用 DSH_TEST_PYTHON 指定 Python。运行时代码修改后执行 npm run manifest 更新校验清单。

实现细节与验收思路见设计记录。

许可

MIT。第三方组件声明见 THIRD_PARTY_NOTICES.md。