Ducktor

为什么做 Ducktor

在 Vibe Research 浪潮下，编码与科研 Agent 极大地压缩了从实验到成文的周期。但这也是我们在开源 Supervisor-Skills（）并获得学界与业界广泛认可后，愈发担忧的一个问题：当 AI 接管了执行细节，研究者（尤其是高年级本科生与低年级研究生）还能否从科研过程中习得真正的学术判断力？

在社区反馈中我们发现，许多研究者依赖 Supervisor-Skills 获取结构化的科研认知，但静态的技能库仍缺少伴随式的实时指导。与此同时，当前多数自动化科研工具本质上是一个开环系统：Data In, Paper Out。Agent 替你完成了所有隐性决策（如何界定核心贡献、结论下到什么分寸、消融实验如何归因），而人却被排除在思考回路之外。

Ducktor 旨在打破这种「执行加速、认知空心化」的困境，构建属于研究者的知识闭环：

1. 注入顶尖学术品味：输入不再只是实验数据，还将顶尖学者的方法论、审稿标准与你们课题组的经验共同作为上下文约束。
2. 过程拆解与实时对齐：在 Agent 推进研究的关键节点，Ducktor 主动暴露背后的学术取舍（Trade-offs），将隐性判断转化为可习得的显性原则。
3. 能力与成果双重沉淀：在打磨出高质量论文的同时，生成可溯源的决策日志与个人科研笔记，让研究者的学术直觉与 Agent 同步进化。

[!TIP] 用 DeepSeek Harness？ 请用 DeepSeek-Ducktor：命令和规则与 Ducktor 一致，更适配 DeepSeek Harness 的功能。

核心体验：之前 vs. 之后

当你把实验结果交给常规 AI 撰写论文时，AI 会一次性输出初稿。核心贡献如何提炼、结论措辞的强弱边界、对比基线的合理性，全部由模型在黑盒中自行决断。你可能拿到了一篇通顺的草稿，却错失了最重要的方法论训练，也为后续审稿埋下了隐患。

引入 Ducktor 后，同样的任务被重构为透明的教研闭环：

• 使用 /duck-outline 梳理主线逻辑，/duck-write 撰写正文，/duck-review 以审稿人视角严苛自查。
• 每完成一个关键阶段，Ducktor 都会讲清这一步最要紧的取舍（Why）：从常见的另一种做法、为什么这样选、什么条件下不成立里挑用得上的讲（这一步只是按部就班时，一句话带过）；有值得带走的**科研原则（Principle）和下次可以主动前置的做法（Next Time）**时，一并讲出，并记进笔记本。

核心机制与工作流

Ducktor 并不替换你现有的底层模型，而是作为一套轻量级规则、Hook 与技能层，引导你的 AI 扮演严谨的学术导师。

1. 双模式运行与「证据护栏」

安装后，Ducktor 默认处于按需模式，仅在你显式调用 /duck-* 命令时介入。在项目根目录下执行 /duck on 后，将开启当前项目的伴随指导模式（或使用 /duck quiet 开启静默模式：照样先问、照样记录，只是不在对话里讲解）：

• 即时方法论点拨：当 AI 完成具有实质意义的研究动作（如确定技术路线、调整实验设计、完成核心段落撰写），Ducktor 会在回复末尾用一到三行点出背后的科研考量。
• 关键决策前置征询：面对会改变研究走向的重大取舍，AI 在动手前会先向你确认（单次最多提出 3 个核心问题，避免过度打扰）。你说过「这类事我想自己定」或「下次让我先试」的，这一类先问你打算怎么做，听完再动手。
• 结果入文前的「证据护栏」：当你在伴随模式下要求 AI 将实验数据写入表格或推导结论时，Ducktor 会前置核查三项审稿级红线（发现隐患会先讲一次哪里不够、建议怎么补；你已经明说要写，它照你的写，并记为「你定」）：
  1. 统计显著性：实验是否仅运行了单次？性能差距是否大于结果本身的波动（随机种子、测试集抽样）？不是计算机方向的，换成你那一行的标准（如样本量与检验力、效应量与置信区间）。
  2. 归因解耦：当出现大幅性能提升时，收益来源（如参数量扩张、训练步数增加 vs. 方法本身改进）是否已拆解清楚？
  3. 主张与证据对齐：行文结论的措辞强度，是否超出了现有实验证据的支撑范围？

📌 注：显式执行 /duck-* 命令时，工作流将遵循对应命令的专属步骤，命令报告的「卡片提醒」一节列出和这次产物相关的几张共识卡；最要紧的那张讲的道理，可能化进命令结束时的讲解。关于开启 Ducktor 前后的真实对话对比，请参阅评测集 evals/before-after/。

2. 事后追问（/duck-why）与阶段复盘（/duck-learn）

• 即时追问 (/duck & /duck-why)：即使 AI 已经执行完毕，你也可以随时输入 /duck <你的问题>（例如 /duck 这一步有哪些值得注意的科研规范？），系统会自动路由至最匹配的命令进行解答。调用 /duck-why 时，Ducktor 会针对刚才的操作（或你指定的文件、Git Commit、段落），聚焦剖析最值得学习的一处判断：常见做法与有经验的人为什么这样选、什么条件下不成立、数据去哪核对。这一步是你拍板的、你又没说过理由时，它会先问一句你当时怎么想的，再接着你的话讲。名家和经验卡的观点化为经验融进讲解，出处写进报告；你问起出处，它直接给出作者、文章和链接。
• 阶段复盘 (/duck-learn)：在一个研究阶段告一段落时调用。它先读这一段的决策记录、报告、笔记、Git 提交和写出的稿子，先看稿子和方案本身站不站得住（比较是否只差一个因素、数字能否从数据算回来、写进去的事实有没有出处），再对比“初始预期”与“实际产出”，指出有经验的导师会重点审视的薄弱环节，梳理出交给 AI 的判断，给出一到两条下一步；记录里涉及上一次复盘的下一步时，照实说做了没有。最后请你回看一件具体的决定，说说当时怎么想、现在会怎么定（可以不答）。你说「这类事以后我想自己定」或「下次让我先试」，它先给你看要记进 .duck/config.md 的那一行，你同意再记，帮助你逐步收回学术主导权。

3. 个人知识沉淀与决策溯源（.duck/）

Ducktor 将过程中的认知资产以纯文本 Markdown 存储在项目本地的 .duck/ 目录下：

• 科研原则笔记本 (.duck/notebook.md)：按行记录提炼出的科研原则。开启后开始同类工作前、以及执行 /duck-* 命令时，Ducktor 会翻出相关的历史原则照着做。如果你表示“这类原则我已经掌握”，后续将转为只记录、不重复说教。
• 决策溯源日志 (.duck/decisions.md)：按行记录研究过程中的关键取舍，并明确标注决策者（「你定」或「AI 定」）。
• 复盘与精讲报告 (.duck/reports/)：存档每条命令的完整结果、讲解依据与卡片提醒，以及 /duck-learn、/duck-why 的深度分析。

所有记录均为标准 Markdown 文件，可直接随论文代码库提交至 Git（组会上面对导师追问“当时为什么这样设计实验”，可随时溯源）；若无需入库，将 .duck/ 加入 .git/info/exclude 即可。

4. 可溯源的导师知识库（拒绝凭空说教）

为避免大模型产生空洞的“正确的废话”，Ducktor 讲道理时的依据只取自以下四个来源。对话里化为经验来讲，出处写进报告或笔记本那一行，你问起时直接给出；找不到依据时，它会说明这是 AI 自己的判断：

• 经验卡 (Experience Cards)：内置 23 张高频科研经验卡，涵盖适用场景、操作准则与文献溯源（例如 W11：行文措辞强度必须与实验证据强度严格对齐）。
• 名家方法论索引 (Mentors)：结构化提炼 Richard Hamming、John Schulman、Andrej Karpathy、Jennifer Widom 等学者的经典科研方法论文章要点，并附原文链接。
• 科研手册 (Handbook)：源自 Supervisor-Skills 的系统化科研指南。
• 课题组自定义经验卡：支持通过 /duck-skill 注入你们实验室内部的审稿偏好与写作规范（发生冲突时，优先以课题组自定义规则为准）。

仓库架构

开启 Ducktor 的项目会在每次会话初始化时加载常驻规则 rules/core.md（针对仅支持规则文件的工具提供 AGENTS.md）。核心组件分布如下：

• skills/：14 条交互命令的定义与编排逻辑。
• library/：完整集成的 10 项 Supervisor-Skills 核心科研技能（涵盖文献综述、Idea 评估、投稿前审稿等）。
• cards/ & handbook/：内置经验卡、名家文章索引与科研手册。
• bin/、hooks/、scripts/：多平台插件适配脚本与生命周期 Hook。

安装与快速开始

让你的 agent 帮忙，把下面这段话发给它：

帮我安装 Ducktor 插件：https://github.com/yinwu01/Ducktor
照仓库里 INSTALL.md 的步骤装好，装完告诉我怎么开始用。

也可以照下面的步骤自己装。

环境要求：Node.js 18 及以上版本。 (注：若此前安装过旧版 Doctor Duck，请先参照 INSTALL.md 中的卸载指南清理旧版本。)

Claude Code

在终端中执行：

claude plugin marketplace add yinwu01/Ducktor
claude plugin install duck@ducktor

Codex

在终端中执行：

codex plugin marketplace add yinwu01/Ducktor
codex plugin add duck@ducktor

安装后，请在 Codex 中打开 /hooks，信任 Ducktor 注册的两条 Hook，随后开启新会话即可。

其他 AI 编程工具（Cursor / Gemini CLI / Qwen Code 等）

将本仓库克隆至本地，把 AGENTS.md 复制到你的目标项目根目录，并在对话中告知 AI 本仓库的本地路径。此模式下常驻规则自动生效；由于无原生斜杠命令支持，可通过自然语言触发（如*“请按照 Ducktor 的 /duck-review 流程审阅当前草稿”*）。各平台适配详情请参阅 docs/agent-portability.md。

启动验证

1. 在项目最外层根目录（新建空目录亦可）启动新的终端会话。
2. 在 Claude Code 中输入 /duck（Codex 中输入 $duck:duck），Ducktor 将展示极简上手指引与命令菜单。
3. 若希望在日常对话中开启伴随指导，执行一次 /duck on 即可。开关状态独立保存在当前项目的 .duck/config.md 中，不会污染其他项目（注意：请勿在 paper/ 等子目录下启动会话，否则无法读取根目录配置）。

更多关于版本更新、卸载流程与故障排查，请参阅 INSTALL.md。

命令参考

注：9 条核心科研工作流命令依赖 library/ 下的技能库，需完整安装插件方可使用。在 Codex 环境中，请将 /duck-review 替换为 $duck:duck-review（其余命令同理）。

常见问题 (FAQ)