# Docent

> 仅当用户显式选择 docent 时使用；由单个专职子代理通读现有代码，生成可离线交互的代码讲解报告。

- Skill: `ben2pc/docent` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add ben2pc/docent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ben2pc/docent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ben2pc (https://skillmd.com/u/ben2pc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ben2pc/docent

---


# Docent：代码讲解员

Agent 写代码的速度远超人类阅读代码的速度，人类对代码库的心智模型持续落后。Docent 把线性的代码问答升级为一份可以从系统总览逐层下钻到代码证据的理解报告。

**核心目的**：让一个没跟上进度的人类，在约 10 分钟内建立对目标代码逻辑的**正确**心智模型。报告的一切形式选择都服务于这个目的。

Docent 解释现有系统“现在是什么、为什么这样咬合”，不是代码审查或架构评审，也不默认提出目标设计。用户进一步要求优化时，先完成现状解释，再把当前架构与代码证据交给 `arch-design` 澄清未来方案。

## 何时使用

- 仅当用户显式选择 `docent` 时使用。Claude Code 的插件命令是 `/auriga-workflow:docent <参数>`；Codex 中显式选择 `auriga-workflow:docent` 并提供参数。**不要**在普通问答（"这个函数返回什么"）中自动触发本 skill——那种问题直接回答即可。

## 入口

Claude Code：`/auriga-workflow:docent <自然语言问题 | 路径>`

Codex：显式选择 `auriga-workflow:docent`，并输入自然语言问题或路径。

| 参数形态 | 处理方式 |
|---|---|
| 仓库内存在的文件或目录路径 | 理解范围即该路径，跳过定位阶段 |
| 其他文本 | 当作主题（例："用户登录后 token 是怎么刷新的"），由子代理先定位相关代码 |
| 无参数 | 沿用当前对话中唯一明确的问题或路径；确实无法确定范围时再询问 |

## 执行模型：单个专职子代理

主 agent 只做三件事：解析参数、派遣**一个**专职子代理、交付结果。定位→通读→合成→生成的全过程都发生在子代理内部。

为什么是一个而不是多个：理解是不可分割的认知过程——"A 文件里这个判断为什么存在"的答案往往在 B 文件里。并行碎片化阅读会切断跨文件因果链，拼装出"每个文件是什么"，拼不出"它们为什么这样咬合"。子代理的价值不在并行，而在**隔离**：把批量代码阅读的上下文消耗挡在主对话之外。

派遣包必须完整包含：用户的原始问题或路径、当前工作目录、本 skill 所在目录的绝对路径（下称 `<skill-dir>`）、当次对话语言、用户指定的输出位置，以及下面这条明确指令：先读取 `<skill-dir>/references/report-workflow.md`，执行其中的报告生成流程；你就是唯一的报告生成子代理，不得再次派遣子代理。不要只给目录后期待隔离上下文自行获得本技能内容。

若当前运行时不支持派遣子代理，停止并说明 Docent 依赖单个隔离子代理，当前环境无法执行；不要把批量代码阅读降级到主对话。

## 交付

子代理返回后，主 agent：

1. 核对报告存在且拼装验证成功。交互式桌面环境存在可用浏览器命令时打开报告；无图形界面或无法确认时只返回路径
2. 在主对话给出：报告文件路径 + 一段文字摘要（讲了什么逻辑、读了哪些核心文件、有什么值得注意的发现）

## 纠偏循环

"阅读足迹"一节的存在意义是让用户能发现定位偏差。用户指出"漏看了 X"或"方向不对"后：在同一会话内重新派遣子代理修订（把用户反馈和上一份报告路径一并交给它），产出更新的报告。不引入任何跨会话持久化状态。