SuperAPI AI 工具集

AI_Generated_Code_Reading_Guide_Skill

编程与开发

查看项目

更新于 10-16 09:15

技能介绍

用途

该技能用于在代码仓库中生成“AI 阅读代码后输出的代码导读文档”。适用场景包括:用户要求阅读某个目录或模块的主体代码并总结;用户要求把总结写入一个 Markdown 文档;用户希望文档突出“代码导读”“快速理解代码”“AI 生成”等属性;用户希望对多个模块分别生成导读文档,并统一命名风格。

输出目标是形成一份面向读者的代码导读文档,而不是零散笔记,突出模块职责、调用链路、目录分层、关键流程,并明确声明文档由 AI 阅读代码后生成,目标是帮助读者快速理解代码。

主要能力

  • 界定边界:明确哪个目录是公共接口,哪个目录是内部实现;若用户强调“只有某个目录的头文件是对外 API”,会在文档中明确写出。
  • 先读说明文档再读代码:优先阅读目标目录及其子目录中的 README.md、README_zh.md,先用说明文档建立模块职责认知,再用源码验证和补充细节。
  • 聚焦主体代码:优先阅读入口文件、主流程文件、模块注册文件、构建脚本;对工具函数和第三方代码只做辅助理解。
  • 从“读者快速理解”出发组织内容:按“这个模块是什么、怎么分层、怎么运行、关键点在哪”来写,而非按“读了哪些文件”来写。
  • 明确是 AI 生成:文档开头加入统一说明,声明文档由 AI 阅读代码后生成,并写明目标是帮助读者快速理解代码结构、模块职责和主要流程。

使用方式

推荐工作流程如下:

  1. 确认目标和边界:确认目标目录、输出文件位置,以及是否有特别限制(如哪些头文件才算对外 API、是否要求参考 README_zh.md、是否要求中英文命名风格)。若用户已明确给出,则直接进入下一步。
  2. 建立目录级认知:优先阅读顶层 README.md、目标目录的 CMakeLists.txt、各子目录的 README_zh.md、关键公共头文件,建立初步认知(是库、组件、应用框架还是完整程序;主要分几层;每层职责;对外接口在哪里)。
  3. 梳理主体代码:重点阅读主入口文件、生命周期管理文件、模块管理器/注册器、关键 service/manager/controller、传输层或协议层核心实现、HAL/OSAL/Framework 核心实现、样例代码或示例主程序。梳理时重点回答:系统怎么初始化、核心对象是什么、模块之间如何协作、事件/回调/线程/状态机怎么串起来、输入输出数据怎么流动。
  4. 形成导读结构:建议采用“项目/目录定位、对外 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 是否无明显格式问题。

适用场景

适用于需要快速理解某个代码目录或模块的场景,尤其是希望获得结构化、面向读者的代码导读文档,而非零散笔记。可用于库、组件、应用框架或完整程序的代码梳理,也可对多个模块分别生成统一命名风格的导读文档。

限制

资料中未提供关于收费、价格、平台支持范围、具体效果指标等信息,暂未提供。该技能以当前仓库中的代码为准,未实现的能力会明确标注,不夸大设计意图。