dsh-research-autoresearch

Readme

# dsh-research-autoresearch

AutoResearch 科研插件全家桶（单 bundle 发布）：

| 插件 | 工具 | 功能 |
|---|---|---|
| arxiv-search | `arxiv_search` | 文献 Recall（arXiv 检索+去重） |
| lit-score | `lit_score` | LQS 五维评分分桶 |
| research-state | `research_state` | 研究状态/进度面板（7 操作） |
| stall-check | `stall_check` | 停滞检测（pivot/escalate/cap 红绿灯） |
| peer-review | `peer_review` | 五人格中位数评审 |
| research-ui | `research_ui_switch` | 🎛️ 可视化总控台（运行时开关） |

## 结构（仿 dsh-github-manager 工程形态）

```
src/bundle.ts                  宿主半侧入口（6 字段扁平 config）
src/client/locales.ts          卡片双语字典
src/client/card-model.ts       React-free 控制器：staged drafts -> save -> settings scope
src/client/ResearchUiCard.tsx  设置页卡片组件（jsx-runtime + 宿主设计令牌）
src/client/index.ts            浏览器半侧入口（locale/slots/settingsScope）
src/client/shims.d.ts          外部模块环境声明（零 @types 依赖）
tsconfig.client.json           strict 类型检查（npm run typecheck:client）
build.mjs                      宿主半：strip-types -> lib/*.js
scripts/build-client.mjs       浏览器半：tsc transpileModule -> __ModuleLoader__ 信封
tests/smoke-test.mjs           宿主半冒烟（lossless 门 + settings 同步 + 卡门控）
tests/client-smoke.mjs         浏览器半回放（vm 沙箱跑完整 loader 契约）
```

构建：`npm run build`（两半都编译）；测试：`npm test`；类型：`npm run typecheck:client`。
`lib/client.js` 为生成物，勿手改。

## 可视化开关（三档）

1. **套件级**：config.enabled=false → 整个 bundle 不注册（重启生效）
2. **部署级**：`*Cards` 声明式注入各工具进度卡片（默认 false=关闭）
3. **会话级**：`research_ui_switch {feature, action: on|off|reset}` 即时开合；`defaultCards` 总闸播种

卡片关闭 = 展示器返回 undefined → DSH 通用回退，工具功能零影响。
运行时门控在 execute 时盖进 presentationMeta 持久化，会话日志回放永远一致。

## 设计灵感

本插件是 [Deli Chen（陈德里）](https://victorchen96.github.io/) **AutoResearch 框架协议**的 DSH 工具化实现：

- **灵感论文 / 案例研究**：Deli Chen, *从初稿到 Strong-Accept：一篇自我博弈综述如何被推到 8.6*（"From Draft to Strong-Accept: How a Self-Play Survey Hit 8.6"）—— [https://victorchen96.github.io/blog_self_play_story.html](https://victorchen96.github.io/blog_self_play_story.html)。
  该论文 16 轮评审的实证直接塑造了本插件三条核心设计：
  - `peer_review` 采用 **MEDIAN 而非均值**（防单人格抬分，对应其 V14→V16 中位数爬升）；
  - **诚实降分信号**（对应 V12：外部引用核查后框架主动把 8.5 降为 8.2，scoreDropped 字段即为此而设）；
  - `stall_check` 的 "**pivot structure, not tactics**"（结构转向而非战术调参）与 15 轮 / 30 分钟双上限。
- **协议全文**：[AutoResearch Framework Protocol（SKILL.md）](https://victorchen96.github.io/auto_research/framework.html) —— 五工具的状态文件、LQS 权重、五人格评审、行为约束（零交互 / ready-means-execute）逐条来自该协议。

## v0.4.0 编排层补全（诊断驱动）

发布后取证（解压宿主全部 83 个会话日志）发现：**六个工具被调用了 0 次**——插件"装着但没生效"。根因：AutoResearch 框架的原生形态是 **SKILL.md 协议（编排层）+ 工具（执行层）** 两件套，本包此前只有后者；模型对被动工具描述的自发调用率≈0。修复：

1. **注册 `autoresearch` runtime skill**（官方 `ctx.skills` 通道）：技能目录里带上中英触发描述，研究会话加载后即注入完整协议——任务目录约定、迭代循环、文献漏斗、五人格评审循环、stall 行动语义。skill 目录每会话只占 name+description 两个字段，正文按需加载（对 token 成本近乎零）。
2. **注册走 `ctx.get('skills')` 可选查找而非 inject**：skills 子系统缺席的 profile 依旧完整启动六工具（断言已锁进 smoke，本项目的 brick 教训不允许第二次）。
3. **五路可视化卡片默认改为开启**（原先全 false = 效果不可见是"没发挥作用"的放大器）；`enabled:false`、设置页总控台、`research_ui_switch` 三档退出路径不变。

## v0.3.0 文献驱动升级（2026-07）

用本插件自己的 Recall→Score 漏斗对 2024-09 ~ 2026-08 前沿文献（67 篇召回 / LQS 分桶）做了自省研究，两处实证缺陷已修复：

1. **lit_score · 引用窗口校正**：实测一批 22 篇 2026 前沿论文因 citation=0 全部被 dropped——新论文尚没时间积累引用，25% 引用权重系统性错杀最新文献。现在 <400 天论文按缺失指标标准处理：引用分量用其余分量均值插补，并以 `citationEmergingImputed` 字段透明标记（不失真、可审计）。回测：同批 22 篇 **22 dropped → 16 conditional + 6 合理淘汰**。参考做法：Citation-Constellation (cs.DL 2026)、缺失指标均值插补惯例。
2. **peer_review · 评审不确定性带**：2025-2026 LLM-as-a-judge 文献（*Bias and Uncertainty in LLM-as-a-Judge Estimation*、*Noisy but Valid*、Conformal Elo、*Breaking the Reviewer*）一致指出：点估计中位数过度自信、极化评审团可被攻破。新增 `judgeDisagreement`（极差）与 `scoreBand`（中位数 ± 1.4826×MAD 稳健区间，与中位数同族）；分歧 ≥4 自动打 `judge_disagreement` 弱点标签，且**极化的高分面板不能再直接 accept**（强制先收敛）。
3. **构建自含化**（发布规范修复）：6 个工具源码 vendor 进包内 `src/`，`prepare` 不再触碰包外路径——git 安装方可独立构建（publish.zh.md 的 self-contained 红线）。

## 测试成果

| 验证层 | 结果 |
|---|---|
| 宿主半冒烟（挂载 / 设置同步 / lossless 注册表门 / inject 契约 + 0.3.0 分歧门与插补回归） | **11 项含 2 条 0.3.0 新断言** |
| 浏览器半回放（vm 沙箱 + cordis 属性门模拟 + 暂存/保存链路） | **9/9** |
| 安装态稳定性探针（真实 profile 内直接执行 6 工具 + 输入卫生 + 重复循环） | **16/16** |
| 冷启动稳定性（隔离 DSH_HOME 连续三次 `dsh web`） | **3/3**（HTTP 200 + boot graph，3–7s，插件树零错误） |
| 真实网络往返（arXiv API / Semantic Scholar 引用数） | arxiv ≈1.0–1.3s 双次稳定；S2 ≈2.9–16.5s（服务端波动），分层计数精确守恒 |
| 类型检查 `tsc --noEmit`（strict, DOM） | 0 诊断 |
| 端到端科研模拟（research-sim harness） | 133/133 |

历史缺陷回归全部锁进断言：`inject ['tools']` 缺失、default 导出遮蔽 inject（曾两次 brick 宿主启动）、NaN 时间戳、空白方向标签。

## 安装

方式一（社区规范 · git 安装，需授权一次 prepare 构建；pnpm 的 allowBuilds 键绑 commit hash，上游推新 commit 后按提示更新一次）：

```bash
dsh plugin --profile web add github:<your-github-user>/dsh-research-autoresearch
```

方式二（预构建 tarball，免构建授权）：

```bash
npm run build && npm pack
dsh plugin --profile web add ./dsh-research-autoresearch-0.3.1.tgz
```

安装后在 profile 的 `cordis.patch.yml` 加 `- id: dsh-research-autoresearch` + `disabled: true` 可整体停用；Web 设置页「插件配置」的 **科研可视化总控台** 卡片可运行时切换五路可视化（zh/en 双语界面）。