dsh-socrates

Readme

# dsh-socrates

> 像苏格拉底一样，先问清楚问题再研究。  
> Socratic clarify-first deep research plugin for DeepSeek Harness.

## 一句话

`dsh-socrates` 是 DeepSeek Harness（DSH）的深度研究插件，主打**调查前澄清 + 自适应多轮研究 + 交叉验证 + 引用闭环**。不是固定提示词流水线，而是活的、可收敛的研究闭环。

## 核心特性

- 🔍 **调查前澄清（clarify）**：Planner 针对主题歧义生成 ≤3 个澄清问题，经 `userQuestions.ask` 提问；可选计划审批（plan-review 意图卡片，Gemini 式）
- 🔄 **自适应多轮研究**：每轮并行 researcher（flash）搜索→精读→逐字摘录入证据库；轮末收集 high-priority 缺口，边际增益验证；连续零增益即停 + 轮次硬上限 + token 预算三保险止损
- ✅ **交叉验证（verify）**：Verifier 声明级三分裁决（entailed / contradicted / baseless）+ coverage 独立核验 + 单跳回补 ≤2 任务 + 条件修订轮；未验证声明标 ⚠️ UNVERIFIED
- 📝 **引用闭环**：编号引用只能出自证据库逐字片段（≤100 字，含段落锚点）；非原文内容标 `model_knowledge`；程序化引用审计（编号存在性 + 摘录紧邻格式 + 逐字一致性 + 100 字上限）
- 🎓 **学术三源**：内置 arXiv / PubMed / Semantic Scholar 检索（免 key，按频度降级披露）
- 🗂️ **源策展（curate）**：depth≥2 默认启用，LLM 策展子代理剔除弱相关低质源
- ⚡ **模型分层降本**：Planner / Synthesizer / Reviewer → Pro；Researcher → Flash（provider deepseek-official）

## 安装

```bash
dsh plugin --profile web add dsh-socrates
```

重启 DSH 生效。

## 使用

对话中直接说人话，模型按工具描述自动触发：

- 「深度调研一下 MCP 生态现状，重点对比几家主流实现，出一份带引用的报告」
- 「按这份问题清单做研究：1. ... 2. ...」（已有清单 → 跳过自动拆解，直接并行研究）
- 「调研一下 A/B 方案，purpose 是决定我们选哪个」（用途越明确，答案空间越准）

复杂主题自动扩展轮次，简单主题一轮收敛。想要更严谨传 `depth: 3`，要引用纠错和覆盖度审计传 `review: true`。

## 工具参数

| 参数 | 必填 | 默认 | 说明 |
|---|---|---|---|
| `topic` | 是 | — | 研究主题 |
| `purpose` | 否 | — | 研究用途（支撑什么判断/决策），用于定义答案空间 |
| `questions` | 否 | — | 已有问题清单（每行一个），提供则跳过自动拆解 |
| `depth` | 否 | `2` | 精度：1=初步（3 子问题/2 轮上限）、2=深入（4 子问题/3 轮上限）、3=穷尽（6 子问题/4 轮上限） |
| `synthesize` | 否 | `true` | 综合子代理出最终报告；false 只返回三态证据 |
| `verify` | 否 | `true` | 交叉验证（可关以省成本） |
| `review` | 否 | `false` | 对抗性审查：引用纠错 + 覆盖度审计 + 矛盾/过度自信标注 |
| `clarify` | 否 | `true` | 调查前澄清提问 |
| `planReview` | 否 | `false` | 计划审批（人工确认计划后再研究） |

## 配置（可选）

| Key | 默认 | 说明 |
|---|---|---|
| `subagentProvider` | 引擎默认 `spawn` | 子代理 provider |
| `maxParallel` | `4` | 每轮研究并发上限 |
| `maxTotalAgents` | 动态计算 | `maxParallel×(depth+1)+5`（防引擎 cap） |
| `plannerModel` / `researcherModel` / `synthesizerModel` / `reviewerModel` | 继承父配置 | 模型分层 |

## 输出

每次研究在 `runs/<topic-slug>/` 下生成：

- `evidence.jsonl`：逐字摘录证据库（URL + 段落锚点 + 质量分级 A-D）
- `report.md`：带编号引用的最终报告
- `state.json`：运行状态、覆盖度、验证统计
- `review.md`：审查意见（review=true 时）

> 注：runs 目录默认落在插件安装目录下。可通过环境变量 `DSH_SOCRATES_RUNS` 显式覆盖。

## 架构

```
DSH model ──tool call──▶ index.js（薄壳）
                              ├── deep_research：编排 workflow
                              └── deepresearch_fetch：网页抓取链
                                    Host 层 ──workflow 引擎桥──▶ 研究脚本
```

- 编排走 DSH 官方 workflow 引擎（`ctx.workflows`），worker 隔离、并发/总数 caps、取消传播
- 搜索/抓取走内置 `web_search` / `web_fetch`——插件零网络逻辑、零自研编排
- 证据落盘在插件宿主侧（`src/evidence-store.js`），workflow 脚本无 fs/网络能力

## 与同类插件对比

| | dsh-socrates | [dsh-deepresearch](https://github.com/havingautism/dsh-deepresearch) | [dsh-raven-research](https://github.com/wxxb789/dsh-raven-research) | [dsh-research-report](https://github.com/PerryLink/dsh-research-report) |
|---|---|---|---|---|
| 核心差异 | 苏格拉底式澄清 + 自适应多轮收敛 + 交叉验证 + 引用审计 | 证据管理 + Web 工作区 + deepResearch namespace | 中途 steer 纠偏 + 引用字节级验证 | 内容寻址证据账本 + 密封报告 |
| 多轮编排 | ✅ 自适应闭环（缺口驱动扩展） | ❌ 不自调度搜索 | ❌ 单 Task 渐进 | ❌ 无研究闭环 |
| 交叉验证 | ✅ 声明级三分裁决 + 单跳回补 | ❌ | ❌ | ✅ 验证裁决 |
| 引用审计 | ✅ 程序化（逐字一致性 + 100 字上限） | ❌ | ✅ 字节比对 | ❌ |
| 学术检索 | ✅ arXiv / PubMed / S2 | ❌ | ❌ | ❌ |
| 模型分层 | ✅ Pro/Flash 自动分层 | ❌ | ❌ | ❌ |

## 曾用名

本项目原名为 `dsh-deep-research`。为避免与 GitHub 上 [dsh-external/dsh-deep-research](https://github.com/dsh-external/dsh-deep-research) 同名仓库混淆，于 2026-08 更名为 `dsh-socrates`。

## 里程碑

- M0 探测 ✅（2026-08-17）
- M1 单轮闭环 ✅（2026-08-18）
- M2 多轮自适应 ✅（2026-08-18）：缺口驱动扩展、三层收敛、三保险止损
- M3 澄清+追问连贯 ✅（2026-08-19）：澄清提问、plan-review 审批、追问复用
- M4 交叉验证+引用闭环 ✅（2026-08-19）：三分裁决、单跳回补、条件修订、URL 抽查
- M5 打磨 ✅（2026-08-19）：学术三源、报告长度档、LLM 源策展、成本计量
- M5.1 修复包 ✅（2026-08-20）：verifier 空转降级、引用编号上限、source 字段全链路
- M5.2 空转根因修复 ✅（2026-08-20）：字段名容错 + prompt 强化

## 致谢

- 上游审读：[omdsh-dev/dsh-deep-research](https://github.com/omdsh-dev/dsh-deep-research)（MIT 许可，commit c0b329e），仅借鉴机制，未复制代码。
- DSH 官方 workflow 引擎、`web_search` / `web_fetch` 能力。

## 许可证

[MIT](LICENSE) © 2026 Cruciforms