Duck + Doctor · 小黄鸭博士

少一点猜测。
多一点理解。

让 AI 解释代码,让 Ducktor 把解释放在你需要的地方——VS Code 中,源码的旁边。

VS Code 1.85+ · 中英双语 · 插件无需配置 API Key

src/share/aggregate/group_concat.h
24template <VecValueTypeClass in_tc> 25class GroupConcatAggregate final ← Ducktor 30 using BaseClass = BatchAggregateWrapper<…>;
从类概览,走进真实实现。

同一分组的字符串如何拼接?ORDER BY 和 DISTINCT 如何包装?超长结果如何处理?

打开下方交互案例 → · 完整源码、术语、逐行解释与可定位流程图。

01 独立解释文件02 分层理解代码03 引用直达源码04 中英双语界面
沿用你熟悉的工具

一种解释格式,多种阅读环境。

插件 · IDE

VSVS CodeQQoderCCursorTTrae IDECBCodeBuddy…其他 IDE

面向 VS Code 及兼容其插件 API 的 IDE,包括 Qoder、Cursor、Trae IDE、CodeBuddy。通过 Releases 下载 VSIX 安装;IDE 需要支持 VSIX 安装及所需 VS Code API(1.85+),具体能力可能随 IDE 版本变化。

生成 skill · AI Agent

CCursorCXCodexCCClaude Code…其他 Agent

同一套生成 skill 可用于 Cursor、Codex、Claude Code,以及能读取 skill 指令和工作区文件的其他 Agent。不同 Agent 的自动发现路径不同,具体安装方法见下方。

以上仅列出部分 IDE 和 Agent,其他支持相应插件 API 或 skill 指令的工具也可使用。兼容性取决于具体工具及版本,不代表官方背书。

在浏览器里体验 Ducktor

真实代码,真实上下文。

以 OceanBase 开源代码的 GROUP_CONCAT 实现为例,直接读取完整 C++ 源码和配套 .ducktor 解释。试试术语点状下划线、行末 Ducktor 提示、悬浮窗口操作和右侧面板;点击流程图定位真实源码,再通过「逐行解释」对照阅读细节。

.ducktor 解释由 openai/gpt-6.1-sol 生成,通过 skill 生成了比较初级的解释,仅供参考。

此外,网页为模拟效果,真实效果参考插件实际表现。

为真实的代码阅读而设计

增加上下文,不增加干扰。

无论是熟悉陌生项目、追踪具体实现,还是审阅改动,解释都保存在镜像的 .ducktor 文件中,不必修改源码。

01 / 整体理解

代码块解释

通过代码块首行的行末提示,在悬停窗口或专用右侧面板中阅读整体说明。

02 / 术语释义

让概念回到上下文

悬停带点状下划线的关键词查看释义,支持别名,以及局部、模块和全局作用域。

03 / 逐行细节

源码与解释对照阅读

独立预览将只读完整源码与 Markdown 逐行解释对齐展示,也可以随时切换到整体说明。

04 / 引用串联

顺着解释追踪实现

从解释直接跳转到源码文件、行范围、工作区符号或外部文档,串起相关实现。

05 / 流程关系

用图表读懂协作

在解释面板中阅读 Mermaid 流程与关系图,点击已绑定的节点可跳转到对应源码范围。

06 / 文件目录

找到下一个阅读入口

通过 Ducktor 文件目录浏览带解释的文件,按文件名搜索,并筛选逐行解释和图表。

两种工具,一条阅读路径

生成解释,贴着源码阅读。

生成 skill 指导你的 AI Agent,插件负责展示结果。两者可以配合使用,也可以独立使用。

01 / 源码

选择解释范围

一个函数、一个文件,或本次改动涉及的代码。范围与解释深度是独立选择。

02 / AI + SKILL

生成代码解释

AI Agent 按 skill 读取当前源码,核对位置和引用,生成符合规范的解释。

03 / .DUCKTOR

保持源码不变

UTF-8 YAML 解释文件保存在工作区根目录的 .ducktor/ 下,与源码路径镜像对应。

04 / IDE

阅读与跳转

在编辑器中探索整体说明、术语、逐行解释和关联代码,不必离开阅读上下文。

按需要选择深度

从快速概览,到逐步导学。

L1–L5 是生成预设,不是文件格式字段。能力可以独立组合,也可以加上 G 补充审阅关注点。

等级侧重点逐层增加的内容
L1概览职责与结果
L2使用重要输入输出、前提、副作用与失败行为
L3理解执行阶段、分支与数据流
L4逐行所有有意义源码行的解释
L5导学必要符号、当前涉及的类型成员与协作关系

L5 默认只解释当前函数涉及的成员,不展开整个类或依赖树。查看完整能力约定 ↗

快速开始

让下一个代码库,更容易读懂。

让 Agent 帮你安装

复制以下提示词到 Agent,让它先确认安装目标,再执行全局安装:

请帮我安装 Ducktor skill 和 VSIX 插件,仓库:https://github.com/ZoruaSama/Ducktor。
1. 先检测操作系统及本机已安装的 VS Code 类 IDE(如 VS Code、Cursor、Qoder、Trae、CodeBuddy 等),列出名称、版本及可用的 CLI 或安装路径。不要假定只安装了 VS Code。
2. 询问我想给哪个或哪些 IDE 安装插件,以及使用哪个或哪些 Agent;等我确认后再安装。
3. skill 必须安装到用户主目录下的全局路径,不要安装到项目目录。手动安装时完整复制 skills/ducktor-generator/(含 SKILL.md 和 references/)到所选 Agent 的全局目录:Codex 用 ~/.codex/skills/ducktor-generator/,Claude Code 用 ~/.claude/skills/ducktor-generator/,Cursor 用 ~/.cursor/skills/ducktor-generator/。
4. 若使用 OpenSkills,先检查 Node.js/npm,按需安装 npm install -g openskills,再运行 openskills install ZoruaSama/Ducktor --global --universal,选择 ducktor-generator。确认所选 Agent 能加载 ~/.agent/skills/;不能自动加载时,使用其原生全局 skill 目录。后续更新用 openskills update ducktor-generator。
5. 从 GitHub Releases 下载最新发布的 VSIX,使用所选 IDE 实际支持的安装方式安装到当前用户的全局扩展目录,不要装到项目或其他 IDE。不要覆盖已有设置;需要新增依赖、提权或覆盖文件时先征求我确认。
6. 验证插件已安装、skill 的 SKILL.md 和 references/ 完整可读,报告实际安装路径及需要重启或重新加载的 IDE/Agent。不要声称尚未执行的步骤已成功。
7. 最后向用户输出以下使用提示:
按 Ctrl + Shift + P(macOS:⌘ + Shift + P)打开命令面板,直接搜索以下关键词,选择对应的切换命令并确保功能已开启:
hover:开启 Hover 悬浮提示。
codelens:开启 CodeLens。
inlay hints(或 inline hints):开启 Inlay Hints 行内提示。

自己手动安装

1. 安装 VS Code 插件

Ducktor 暂未发布到 VS Code 插件商店。请从 GitHub Releases 下载最新的 .vsix 文件,在 IDE 命令面板运行 Extensions: Install from VSIX...,选择下载的文件完成安装。

在 VS Code 中打开项目文件夹,按 Ctrl + Shift + P(macOS:⌘ + Shift + P)打开命令面板,直接搜索以下关键词,选择对应的切换命令并确保功能已开启:

  • hover:开启 Hover 悬浮提示。
  • codelens:开启 CodeLens。
  • inlay hints(或 inline hints):开启 Inlay Hints 行内提示。

也可以打开命令面板,搜索 Preferences: Open User Settings (JSON),将以下配置合并到现有设置(不要覆盖其他配置):

{
  "editor.inlayHints.enabled": "on",
  "editor.hover.enabled": true,
  "editor.codeLens": true
}

2. 安装生成 skill

使用 OpenSkills:用 OpenSkills 安装完整 skill。先安装 Node.js LTS(包含 npm),在终端安装 OpenSkills:

npm install -g openskills

全局安装到用户主目录的通用 Agent skill 路径(~/.agent/skills/):--global 表示全局安装,--universal 表示使用通用目录;仅加 --universal 不会变成全局安装。

openskills install ZoruaSama/Ducktor --global --universal

后续更新此 skill:

openskills update ducktor-generator

如 Agent 通过 AGENTS.md 加载 skill,可在对应项目运行以下注册命令(不会将 skill 重新安装到项目):

openskills sync

出现提示时选择 ducktor-generator。sync 为读取 AGENTS.md 的 Agent 注册 skill;其他Agent遵循各自的加载约定。

手动安装:下载或克隆本仓库,将 skills/ducktor-generator/ 整个目录复制到Agent 的 skill 路径,包含 SKILL.md 和 references/。

  • Codex:~/.codex/skills/ducktor-generator/
  • Claude Code:~/.claude/skills/ducktor-generator/
  • Cursor:~/.cursor/skills/ducktor-generator/

以上为用户主目录(~)下的全局 skill 路径,不是项目目录。按Agent要求重启或重新加载 Agent;若未自动发现 skill,可让 Agent 读取克隆仓库中的 skills/ducktor-generator/SKILL.md 并遵循其流程。

安装完成后,可向 AI Agent 发出生成请求:

为 src/main.js 生成 L3 Ducktor 解释,
使用中文,并为相关符号补充
可核实的引用。
浏览整个项目

File Explorer 汇总页。

想一眼看到项目里所有带解释的文件?在命令面板打开 Ducktor File Explorer,不用离开 VS Code 就能获得完整的项目解释视图。

怎么打开

按 Ctrl + Shift + P(macOS:⌘ + Shift + P),输入 Ducktor,运行 Ducktor: Open File Explorer / 打开文件目录。命令 ID 为 ducktor.showIndex。

之后想再打开?搜索 Ducktor 即可,它就在所有 Ducktor 命令旁边。

能做什么

  • 按原始目录结构浏览所有带 Ducktor 解释的源文件
  • 展开任意文件,查看逐行解释、代码块概览和术语释义
  • 点击任一入口直接跳转到对应的源码行
  • 按"有逐行解释"、"有图表"等条件筛选
  • 按文件名搜索,快速定位
使用前的小提示

几个实用问题。

插件会自动生成解释吗?

不会。生成由使用 Ducktor generator skill 的 AI Agent完成。插件只读取和展示已有解释,无需配置模型或 API Key。你也可以手写解释文件。

解释文件应该放在哪里?

在工作区根 .ducktor/ 目录下镜像源码路径,再追加 .ducktor 扩展名。例如 src/main.js 对应 .ducktor/src/main.js.ducktor。插件不读取源码旁的解释文件;多根工作区中的每个文件夹分别维护解释目录。

怎样打开不同的阅读视图?

悬停 Ducktor 行末提示或带下划线的术语;存在有效逐行解释时,使用文件顶部的 CodeLens。浏览项目可在命令面板运行 Ducktor: Open File Explorer / 打开文件目录。将 ducktor.displayMode 设为 panel 可使用右侧面板。

可以生成中文解释吗?

可以。在生成请求中明确正文语言。将 ducktor.language 设为 zh-CN 可使用插件的中文界面;该设置不会翻译已有解释正文。

阅读代码,也建立理解

认识你的代码阅读伙伴。