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 是怎么刷新的"），由子代理先定位相关代码
无参数	先问用户想理解什么（AskUserQuestion / request_user_input），不要凭空猜测范围

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

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

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

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

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

子代理工作流

1. 定位（路径入口跳过本阶段）

按问题从定位工具箱中选择必要手段，不机械地全部执行：

• 主题与仓库命名关系明确时，先按文件名、目录名或符号名搜索。
• 用户带来报错、日志或界面文案时，搜索对应字符串字面量。
• 入口不明确或调用关系复杂时，沿引用、调用链和数据流扩展范围。
• 当前代码无法解释结构原因，或用户关心演化时，再查 git log -S、--grep 等版本历史。

汇合成两份清单：核心文件（将通读）与外围文件（仅记录关联，不深入）。范围过大装不下时，宁可缩小核心清单也不要降低阅读质量——裁剪必须在报告"阅读足迹"一节可见。

2. 建立当前状态模型

按逻辑关系而不是文件顺序通读核心文件，形成三层相互对应的模型：

1. 系统位置：目标逻辑位于哪些模块、组件和外部边界之间。
2. 关键关系：调用、分支、状态、依赖、领域对象或数据关系如何连接。
3. 代码证据：每个重要结论由哪些具体文件和行号支撑。

从入口沿调用链、数据流和状态变化阅读，持续回答“为什么这样咬合”。只有版本历史能解释当前结构时才读取关键演化节点。

3. 合成报告

核心内容

按下面的认知顺序组织报告。窄范围可以合并相邻章节，但不能漏掉信息：

1. 阅读目标与一句话答案：直接回答用户的问题，说明范围、为什么存在和未覆盖内容。
2. 当前架构总览：先展示模块、组件、外部依赖和目标逻辑所在位置。
3. 文件级代码地图：展开到文件粒度，标明核心文件和外围文件的职责。
4. 核心概念与职责：解释读懂代码所需的少数概念、状态、角色和不变量。
5. 关键路径或关键关系：按问题选择调用、流程、状态、依赖、类型或数据关系，不强行把所有问题画成流程。
6. 从图到代码证据：沿关键关系讲解实现，每项代码结论附 文件:行号；只摘录不看原文就无法理解的判断或转换。
7. 数据或状态与副作用：说明关键数据如何进入、转换、持久化或触发外部调用。
8. 相邻契约与容易误改之处：说明依赖谁、谁依赖它、对外承诺、错误语义、顺序要求和不明显约束。
9. 如何验证理解：目标可运行或可操作时说明端到端体验和预期现象；否则给出适合该代码形态的自动化测试、静态检查或人工核对证据。
10. 阅读足迹与未知区域：列出通读、仅定位和未深入的文件；范围裁剪与无法确认的事实必须可见。

条件内容

• 历史演化（按需）——仅当版本历史能解释当前结构，或用户明确关心演化时展开关键提交及其动机。
• 人工端到端体验（按需）——它是“如何验证理解”的一种方式，只在目标存在真实可运行或可操作入口时展开步骤和预期现象；其他目标不要虚构体验路径，改用核心内容中要求的替代证据。
• 部署与运行（按需）——仅当进程边界、运行环境、配置、监控或恢复机制影响当前代码形态时说明。

条件内容不适用时可以省略，不必用空章节或“不适用”占位。核心内容及其验证路径不能静默缺失；窄范围下可以合并章节，但必须保留对应信息。

4. 生成 HTML 报告

先读两份参考：<skill-dir>/references/design-guidelines.md（信息与视觉设计）和 <skill-dir>/references/components.md（安全拼装与组件契约）。默认复用稳定视觉基线，正文按当前问题组织；只有定制版式能明显改善理解时才调整。

拼装纪律：最终 HTML 由 <skill-dir>/scripts/assemble.sh 拼装。生成彼此独立的正文片段、纯文本标题、图形 JSON，以及按需定制的 CSS；全部放进当次报告独享的临时目录。仓库派生的文本、代码和文件名进入正文前必须做 HTML 转义；拼装脚本会拒绝活动脚本、事件处理器、外部资源、错误图形结构和不存在的图形目标。不要逐字重打固定资产，具体命令和数据契约见 components.md。

可视化手段调色板（按问题自选，不要全用）：

• 时序图——讲一次请求 / 调用链路
• 流程图——讲分支决策逻辑
• 状态图——讲状态机
• 依赖图或组件图——讲模块边界、所有权和依赖方向
• 类图或数据模型图——讲领域类型与持久化关系
• 对照表——讲配置优先级、多实现差异
• 可折叠的多层级下钻——概览到细节的渐进披露
• 带锚点的代码片段——关键代码原文 + 讲解

硬性质量约束（违反任何一条即不合格）：

• 第一屏架构总览：在一句话答案之后先给当前架构图，展示模块、组件、外部边界和目标逻辑的位置，让读者先建立空间感
• 主要关系图：至少用一张与问题匹配的标准软件工程图承载关键关系，可选时序图、流程图、状态图、依赖图、组件图、类图或数据模型图。范围极窄时可以与架构总览合并
• 锚点与下钻：所有代码结论附 文件:行号，图中核心节点显示代码位置并链接到报告内对应讲解
• 自包含离线：单文件 HTML，打开时零网络请求。图表用内联 SVG 或纯 HTML/CSS 绘制，不引入需要从网络加载的脚本库；字体用系统字体栈或内联资源
• 安全：正文不含脚本和事件处理器，仓库派生内容经过转义，图形数据通过独立 JSON 交给固定渲染器
• 阅读足迹：核心内容中的阅读足迹不可省略，这是用户纠偏的依据
• 语言：报告正文跟随当次对话语言（代码标识符与锚点除外）
• 落点：写入 /tmp（如 /tmp/docent-<主题slug>.html），不落进项目仓库

交付

子代理返回后，主 agent：

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

纠偏循环

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

Must Not

• Must not 并行派遣多个子代理分头阅读——碎片化阅读切断因果链
• Must not 把报告或中间产物写进项目仓库
• Must not 为制造视觉差异而无条件重做版式或定制 CSS
• Must not 在报告里写没有锚点支撑的代码结论
• Must not 把报告变成代码质量审查、改造建议或未经用户确认的目标架构
• Must not 把仓库文本直接拼成活动 HTML，或在正文片段中加入脚本
• Must not 静默裁剪范围——所有"没读 / 没深入"都要在阅读足迹一节可见