用途
该技能用于在代码仓库中生成“AI 阅读代码后输出的代码导读文档”。适用场景包括:用户要求阅读某个目录或模块的主体代码并总结;用户要求把总结写入一个 Markdown 文档;用户希望文档突出“代码导读”“快速理解代码”“AI 生成”等属性;用户希望对多个模块分别生成导读文档,并统一命名风格。
输出目标是形成一份面向读者的代码导读文档,而不是零散笔记,突出模块职责、调用链路、目录分层、关键流程,并明确声明文档由 AI 阅读代码后生成,目标是帮助读者快速理解代码。
主要能力
- 界定边界:明确哪个目录是公共接口,哪个目录是内部实现;若用户强调“只有某个目录的头文件是对外 API”,会在文档中明确写出。
- 先读说明文档再读代码:优先阅读目标目录及其子目录中的 README.md、README_zh.md,先用说明文档建立模块职责认知,再用源码验证和补充细节。
- 聚焦主体代码:优先阅读入口文件、主流程文件、模块注册文件、构建脚本;对工具函数和第三方代码只做辅助理解。
- 从“读者快速理解”出发组织内容:按“这个模块是什么、怎么分层、怎么运行、关键点在哪”来写,而非按“读了哪些文件”来写。
- 明确是 AI 生成:文档开头加入统一说明,声明文档由 AI 阅读代码后生成,并写明目标是帮助读者快速理解代码结构、模块职责和主要流程。
使用方式
推荐工作流程如下:
- 确认目标和边界:确认目标目录、输出文件位置,以及是否有特别限制(如哪些头文件才算对外 API、是否要求参考 README_zh.md、是否要求中英文命名风格)。若用户已明确给出,则直接进入下一步。
- 建立目录级认知:优先阅读顶层 README.md、目标目录的 CMakeLists.txt、各子目录的 README_zh.md、关键公共头文件,建立初步认知(是库、组件、应用框架还是完整程序;主要分几层;每层职责;对外接口在哪里)。
- 梳理主体代码:重点阅读主入口文件、生命周期管理文件、模块管理器/注册器、关键 service/manager/controller、传输层或协议层核心实现、HAL/OSAL/Framework 核心实现、样例代码或示例主程序。梳理时重点回答:系统怎么初始化、核心对象是什么、模块之间如何协作、事件/回调/线程/状态机怎么串起来、输入输出数据怎么流动。
- 形成导读结构:建议采用“项目/目录定位、对外 API 边界、代码总体结构、核心数据模型、生命周期主流程、关键模块说明、调用链或运行链路、构建与平台适配、示例中的组装方式、一句话总结”等结构。若目录不是库而是应用组件,还应明确说明是否包含完整 main、与底层 SDK/上层示例的关系。
文档开头推荐说明:说明:本文档由 AI 在阅读当前目录代码后生成,目标是帮助读者快速理解代码结构、模块职责与主要运行流程,作为代码导读使用。
命名建议:若用户希望文档名更专业并突出导读和 AI 生成属性,推荐格式为 <module>_AI_Generated_Code_Reading_Guide.md,例如 volc_conv_ai_AI_Generated_Code_Reading_Guide.md、application_AI_Generated_Code_Reading_Guide.md。
写作要求:语言跟随用户(用户用中文就用中文写导读,用英文就用英文写);结构化表达,用清晰标题分段,从总体到细节组织内容,减少流水账式描述;强调“导读”,目标不是替代源码,而是让读者快速知道从哪里读、为什么这么分层、主线怎么走;尊重代码现状,以当前仓库中的代码为准,若示例中的初始化顺序比目录内更完整,可引用示例帮助解释但要说明其作用;不夸大,未实现的能力要明确写“当前未实现”或“当前代码中未看到完整闭环”,不要把设计意图误写成已实现能力。
推荐输出模板:
# `<模块名>` 代码梳理
> 说明:本文档由 AI 在阅读当前目录代码后生成,目标是帮助读者快速理解代码结构、模块职责与主要运行流程,作为代码导读使用。
## 1. 项目定位
## 2. 对外 API 边界
## 3. 代码总体结构
## 4. 核心流程
## 5. 关键模块说明
## 6. 构建与运行关系
## 7. 一句话总结
使用示例:
示例 1——用户请求:“阅读 /path/to/project/module 下的主体代码并总结,把总结写到 code_map.md 里。注意对外暴露的 API 只有 inc 目录中的。”处理要点:先读 inc/ 公共头文件,确定 API 边界;再读主入口和主要实现文件;在文档中明确写出“只有 inc 为对外 API”。
示例 2——用户请求:“阅读该目录下主体代码并总结,把总结写到 code_map.md 里。注意阅读各个子目录中的 README_zh.md 文件,帮助理解。”处理要点:优先读取各子目录 README_zh.md;用 README 建立模块认知后再补源码细节;在总结中体现 README 中的设计原则和代码中的实际落地。
完成后检查:文档是否写明“AI 生成”和“代码导读用途”;是否明确公共接口边界;是否覆盖主流程和关键模块;是否避免大量无关第三方细节;文件名是否符合用户要求;Markdown 是否无明显格式问题。
适用场景
适用于需要快速理解某个代码目录或模块的场景,尤其是希望获得结构化、面向读者的代码导读文档,而非零散笔记。可用于库、组件、应用框架或完整程序的代码梳理,也可对多个模块分别生成统一命名风格的导读文档。
限制
资料中未提供关于收费、价格、平台支持范围、具体效果指标等信息,暂未提供。该技能以当前仓库中的代码为准,未实现的能力会明确标注,不夸大设计意图。