科研助手 keepkeen/dsh-research

🔬 dsh-research

把 DeepSeek Harness 变成你的科研助手

一套装完即用的科研插件:查文献、读 PDF、记实验、防引用幻觉、编译 LaTeX、盯投稿死线、做组会 PPT。

License: MIT
Tests
Platform
dsh
Zero Deps

安装 · 能干什么 · 怎么用 · 工作流图 · FAQ

DeepSeek Harness(dsh)是 DeepSeek 开源的 Agent 框架,自带的是"标准/极简/创造"这些写代码的模式。这个仓库给它加一个「科研模式」:你在聊天框里说"帮我调研一下 XX 方向""把这周的实验整理成组会 PPT",Agent 就会用真实的论文库、你自己的实验记录和 git 历史来干活——每个数字有出处,每篇引用先核验,编造不出来。

不 fork、不改 dsh 一行代码:所有东西通过 dsh 官方的插件机制(agent preset + 补丁层 + 技能)从外部挂进去,dsh 升级不受影响。

✨ 你会得到什么

| 科研阶段 | 工具 / 技能 | 一句话说明 |
| 📚 查文献 | paper_search paper_get | 搜 arXiv / OpenAlex / Semantic Scholar,拿标题、作者、引用数、摘要、PDF 链接 |
| 🕸️ 顺藤摸瓜 | paper_citations | 从一篇种子论文出发:谁引用了它(找后续 SOTA)/ 它引用了谁(还原相关工作) |
| 📄 读论文 | pdf_extract | 给个 arXiv 链接或本地 PDF,转成文本存到工作区,Agent 自己去精读 |
| 🛡️ 防引用幻觉 | verify_citations + 写入守门 | 往文档里写没核验过的 arXiv id / DOI 会被直接拒绝;编造的 id 会被标 MISSING |
| 🧪 记实验 | exp_record exp_list exp_compare | 实验台账(JSONL),自动记 git 提交号/脏状态/环境;对比跑法一张表出来 |
| 📊 BibTeX | paper_bibtex | arXiv id / DOI 一键出参考文献条目 |
| ✍️ 写论文 | latex_compile | 编译 LaTeX,返回带行号的错误、未定义引用、overfull、页数和字数(查页限) |
| 🔍 看评审 | openreview_search | 查论文在 OpenReview 的接收档位("ICLR 2021 Oral");全文搜评审意见备战 rebuttal |
| ⏰ 盯死线 | conf_deadlines | NeurIPS/ICML/ICLR/CVPR/OSDI… 下个截稿日还剩几天(时区/AoE 自动换算,带 CCF 等级) |
| 🎤 组会汇报 | meeting_material + group-meeting 技能 | 一键聚合本周台账/提交/笔记/读过的论文,对照上周承诺,出 PPT + 讲稿(见下) |
| 🧠 研究记忆 | 记忆 MCP 服务器 | 跨会话记住你的研究偏好和结论(知识图谱,存本地) |
| 💻 持久分析 | terminal_ | 开一个不退出的 Python/IPython 会话做数据分析,画图后 Agent 自己看图改图 |
| 🕰️ 跨会话检索 | session_search | "我上周那个扫描实验在哪个会话跑的?"——直接搜历史会话 |

外加三个工作流技能约束 Agent 按科研纪律干活:literature-review(综述必须逐篇留笔记)、experiment-protocol(不许凭记忆报数)、repl-analysis(图必须自己看过才算画完)。

🚀 三分钟装好

前置:装好 DeepSeek Harness(npm install -g @deepseek-ai/dsh,自带 Node.js 环境)和 git。

一条命令,三个平台通用(macOS / Linux 的终端,或 Windows 的 PowerShell):

git clone https://github.com/keepkeen/dsh-research.git && cd dsh-research && node install.mjs

装完之后,三种打开方式任选:

| 方式 | 命令 | 适合 |
| 🌐 Web UI | dsh web → 新建会话选「科研模式」 | 日常主力,功能最全(预设切换、会话管理) |
| 💻 交互式 TUI | node client/research-tui.mjs | 不想离开终端;流式输出、工具审批、提问全在终端里答 |
| 🖥️ 桌面窗口 | node client/research-app.mjs | 想要"客户端"的感觉:独立 app 窗口(借用你已装的 Chrome/Edge),关窗自动收拾 |
| ⚡ 一次性任务 | dsh --profile research "帮我查XX论文" | 脚本/管道里跑单个任务，跑完即走 |

TUI 里：回复按 markdown 流式渲染（标题/加粗/行内代码/列表着色，代码块原样保留、可干净复制，diff 块按行着色）；等待时有 spinner + 耗时 + 中断提示；工具行带参数摘要、耗时和成败图标，长输出自动截断（失败看尾部），/last 查看最近一次工具完整输出。输入 / 立刻弹出命令菜单，Tab 补全；\+Enter 或 Ctrl+J 多行输入，多行粘贴不会被拆成多条消息。运行中直接输入 = 实时改指令（steer）；Esc 中断当前回合（保留已生成内容），空闲时 Esc Esc 清空草稿；Ctrl+C 运行中=中断、有草稿=清空、空闲连按两次=退出；/new 新会话，/exit 退出；工具审批（y/N）和模型提问都在终端里直接回答。TUI 和桌面窗口会自动找正在运行的服务器，没有就自己拉一个、退出时自己关掉。

安装器都干了什么？（点开看）

1. 检查 dsh 和 git 在不在；
2. 克隆可选的 PPT 引擎（open-kimi-ppt-skill，约 150MB，不想要加 --no-ppt），并把它的技能链接到它约定的位置 ~/.agents/skills/open-kimi-ppt；
3. 把「科研模式」预设（填好本机绝对路径）写到 ~/.dsh/.agent-presets/research/；
4. 用 dsh 自己的 dsh plugin 命令补装两个官方工具包（持久终端、会话检索）；
5. 装 web profile 补丁（定时提醒、时间感知、会话全文索引）；
6. 建终端专用的 research profile（dsh --profile research "任务" 直接用，科研插件全量可用）。

全程幂等，重复跑只会更新自己的东西；你自己改过的配置会跳过并提示手动合并。卸载见 FAQ。

🗺️ 整体工作流

flowchart LR
subgraph lit ["📚 文献"]
A["paper_searchpaper_citations"] --> B["pdf_extract精读 + 笔记"]
B --> C["verify_citations核验后才能写进文档"]
end
subgraph exp ["🧪 实验"]
D["bash / terminal跑实验"] --> E["exp_record台账 + git 指纹"]
E --> F["exp_compare对比出结论"]
end
subgraph out ["✍️ 产出"]
G["latex_compile论文"]
H["group-meeting组会 PPT"]
end
C --> G
F --> G
F --> H
C --> H
H -->|"报告归档下周自动对照"| E
Z["conf_deadlines / openreview_search⏰ 投稿节奏"] -.-> G

核心思想一句话：汇报和写作不靠回忆，靠台账。实验数字出自 exp_record 的记录，文献结论出自真实检索，引用先过核验——Agent 想编都编不出来。

📖 每个能力怎么用

下面全是你在聊天框里说的话，不用记任何命令。

📚 文献调研

"帮我调研一下 KV cache 压缩的最新进展，列 10 篇，按引用数排。"

Agent 会用 paper_search 跨 arXiv/OpenAlex 搜，给你带引用数和摘要的清单。接着说：

"第 3 篇顺藤摸瓜：引用它的高引论文有哪些？它自己又引了谁？"

这就是 paper_citations。要精读：

"把 arXiv:2401.12345 下载下来精读，整理成笔记放 .research/notes/ 里。"

pdf_extract 会把全文转成文本，Agent 逐段读。最后：

"把这次调研写成 survey.md，引用都带 arXiv id，再生成 references.bib。"

写入前 Agent 必须先 verify_citations——没核验的 id 直接写不进去（守门会拒绝并教它怎么补救）；核验发现不存在的 id 会标 MISSING。paper_bibtex 负责出参考文献。

🧪 实验管理

"跑完了，把这次记一下：baseline-lr3e-4，命令是 python train.py --lr 3e-4，acc 0.91，checkpoint 在 ckpt/base.pt。"

exp_record 落一条台账（自动带上 git SHA、分支、有没有未提交改动）。之后：

"我都跑过哪些学习率？exp-xxx 和 exp-yyy 哪个好？"

exp_list 过滤，exp_compare 出参数/指标对照表。台账在 .research/experiments.jsonl，纯文本，自己 grep 也行。

✍️ 写作与投稿

"编译一下 paper/main.tex，看看有没有问题，现在几页了？"

latex_compile 返回：错误（带行号）、未定义引用/文献、overfull 数量、页数、字数。没装 TeX Live 也行——推荐 tectonic（自动下载宏包）。

"NeurIPS 下次截稿什么时候？ICLR 呢？"
"搜搜 OpenReview 上评审怎么讨论 rotary embedding 的，我准备 rebuttal。"

conf_deadlines 报剩余天数（AoE 时区自动算），openreview_search 直接搜评审原文。

🎤 组会汇报（重头戏）

"帮我准备这周的组会汇报，15 分钟的量。"

流程全自动走下来：

sequenceDiagram
participant U as 你 participant A as Agent participant W as 工作区 U->>A: 帮我准备这周组会 A->>W: meeting_material 聚合素材 Note over A,W: 实验台账 + git 提交 + 笔记+ 读过的论文 + 上次报告 A->>A: 对照上周"下周计划"逐条打钩 A->>U: 确认提纲(一次提问) U->>A: 确认 / 修改 A->>W: 写 report.md(每个数字带证据标签) A->>A: open-kimi-ppt 生成 PPTD → 截图自检(文字溢出? 元素出界?) → 修复 A->>W: 导出 deck.pptx + 讲稿 speaker-notes.md A->>U: 交付 .research/meetings/日期/ Note over W: report.md 归档,下次组会自动抽出"下周计划"来对照

PPT 引擎借鉴(实际是直接采用)了社区逆向 Kimi Slides 的 open-kimi-ppt-skill:YAML 中间格式、约 30 套设计系统、离线导出嵌字体 PPTX、导出截图自查排版问题后再交付。

闭环设计:每次的 report.md(含"下周计划")会归档,下次组会自动抽出来逐条对照——汇报从"回忆这周干了啥"变成"审计台账"。

🧠 记忆与回溯

"记住:我们的主线是低资源场景,BLEU 提升要在 zh-en 上验证。"
"上个月那个失败的蒸馏实验,当时结论是什么?"

前者进知识图谱记忆(跨会话、跨项目),后者用 session_search 翻历史会话、用 exp_list 翻台账。

🧩 架构(一句话版)

dsh(不动它)
├─ 「科研模式」agent preset ← Web 会话组合:一份 YAML 声明这个模式有哪些工具 │ ├─ 8 个插件(纯 ESM JS,零 npm 依赖,直连公开 API) │ ├─ 5 个技能(SKILL.md,教 Agent 按科研纪律干活;组会技能自带 pptd_lint.py) │ └─ 1 个记忆 MCP 服务器 ├─ research CLI profile ← 终端一次性任务:同一批插件的 headless 组合 └─ client/ ← TUI 与桌面窗口:走 dsh web 的 /api + WebSocket 事件流 ├─ research-tui.mjs 流式渲染、终端内审批/提问、steer(零依赖) ├─ research-app.mjs Chrome/Edge app 模式窗口(Win/mac/Linux) └─ lib/ harness(发现/RPC) · tui-render · tui-input

dsh 的哲学是 "everything is a plugin",这个仓库就是它的一次实践:新模式 = 一份预设 YAML + 一堆按官方接口写的插件;TUI/桌面客户端也没有私有协议,说的就是浏览器同款 API。插件零 npm 依赖(只用 Node 内建 + fetch),所以没有版本地狱;卸载 = 删两个目录,dsh 完好如初。

🖥️ 平台与可选依赖

核心功能(文献/实验/守门/组会素材/死线/OpenReview)开箱即用。两个能力需要可选的本地工具:

| 能力 | 依赖 | macOS | Windows |
| PDF 提取 | poppler(或 MinerU,装了优先用) | brew install poppler | scoop install poppler |
| LaTeX 编译 | tectonic(或 TeX Live) | brew install tectonic | winget install Tectonic.Tectonic |

缺了也不会坏:对应工具会返回清晰的安装提示。Windows 下持久终端(PTY)依赖 POSIX 环境,建议在 WSL 里用,其余功能不受影响。TUI 需要支持 ANSI 的终端(Windows Terminal / VS Code 终端都可以);桌面窗口在 Windows 上自动找 Chrome/Edge/Brave 的标准安装路径,都没有就退回默认浏览器打开。

🧪 测试

node --test "tests/.test.mjs" # 插件走真实公开 API;TUI 渲染/输入为纯函数单测

除单元测试外,每个工具都在真实的 dsh Web 会话里被真实模型端到端调用验证过(工具注册、模型调用、守门拒绝→自动补救→重试的完整闭环)。

❓ 常见问题

怎么卸载?

删 ~/.dsh/.agent-presets/research/、~/.dsh/profiles/research/、~/.agents/skills/open-kimi-ppt 和这个仓库目录;把 ~/.dsh/profiles/web/cordis.patch.yml 改回 []。dsh 本体不受任何影响。

PPT 引擎的版权是什么情况?

open-kimi-ppt-skill 是社区对 Kimi Slides 的逆向实现(MIT 协议),原作者后来因版权顾虑清空了自己的仓库,安装器克隆的是存活 fork。介意的话:装的时候加 --no-ppt,或事后删掉 vendor/ 和 ~/.agents/skills/open-kimi-ppt——组会技能会自动降级为只出 markdown 报告 + 讲稿。

组会 PPT 的"视觉质检"需要什么条件?

分两层:结构化校验(随 group-meeting 技能自带的 pptd_lint.py,查元素越界/表格行高失衡/全网格边框/文字溢出)零依赖、总是执行;截图目检需要 agent-browser + Chrome 能在会话里启动——沙箱环境通常起不来,技能会先探针、失败就明说"目检跳过,已做结构化校验",不会中途炸掉,也不会在会话里偷偷 npm install。

断网能用吗？

实验台账、组会素材聚合、LaTeX 编译（宏包已缓存时）不需要网。文献检索/核验需要网；断网时核验会把 id 标为 unverifiable 并放行，不会卡死你。

为什么写文档时 Agent 说“写入被拒绝”？

这是引用守门在工作：内容里有没核验过的 arXiv id / DOI。Agent 会自己调 verify_citations 然后重试；如果它想引用一个不存在的 id，核验会标 MISSING，它就得去找正确的。这个设计就是让“编造引用”这条路走不通。

能不能只装一部分？

能。预设就是一份 YAML（~/.dsh/.agent-presets/research/agent.cordis.yml），注释掉不想要的插件行即可；也可以在 dsh 的 Web 设置里复制这个预设改出自己的变体。

支持哪些模型？

跟着 dsh 走：DeepSeek 官方 API，或任何 OpenAI 兼容端点（在 dsh 的 Settings → Models 里配）。插件本身不挑模型，但守门/技能这套纪律对指令跟随好的模型效果最佳。

🙏 致谢

- DeepSeek Harness — “everything is a plugin” 的宿主框架
- open-kimi-ppt-skill（作者 binaryify）— PPT 引擎，Kimi Slides 的社区逆向
- ccfddl — 会议死线数据集
- OpenAlex / arXiv / Semantic Scholar / OpenReview — 公开学术数据

📄 License

MIT — 插件与技能部分。vendor 的 PPT 引擎按其自身 MIT 协议分发（不随本仓库，安装时克隆）。