SuperAPI AI 工具集

code-tour

通用与其它

查看项目

更新于 10-15 17:28

技能介绍

用途:为不熟悉的代码库生成一条有顺序的导览路径,让每一站都为下一站做铺垫,并注释设计原因而非功能描述。适用于工程师入职、系统交接、设计评审前共享上下文、记录仅存于已关闭 PR 中的设计理由、审计已腐化的旧导览,以及时隔半年重新阅读自己的代码。

主要能力:提供三个脚本。tour_propose.py 按入口点、扇入和边界信号对候选站点排序,Python 用 AST 导入图,其他语言为文件名启发式,分数仅作候选参考。tour_render.py 将导览渲染为入职文档,并审计注释是否只复述行为、少于 20 词或缺少因果语言,why-ratio 达 0.8 才渲染。tour_validate.py 对照当前代码树解析每个锚点,报告 deleted、moved、drifted、shifted 状态,任一站点损坏时退出码为 1,可接入 CI。

使用方式:先确认导览要回答的一个问题、受众及其已有知识、时间预算、值得解释的设计决策。用符号名而非行号锚定站点,行号仅作便利记录。示例命令:python3 engineering/code-tour/scripts/tour_propose.py --repo . --max-stops 7 --exclude vendor --exclude generated --format text;python3 engineering/code-tour/scripts/tour_render.py --input engineering/code-tour/assets/sample_tour.json --audit-only --min-why-ratio 0.8 --format text;python3 engineering/code-tour/scripts/tour_validate.py --tour engineering/code-tour/assets/sample_tour.json --repo engineering/code-tour --format text。

限制:时间预算决定站点数,30 分钟约 5-7 站,超过 10 站读者会略读,超过 60 分钟应拆成两个导览。不要以数据模型开头,不要按作者思维排序,不要追求覆盖所有模块。导览定义应放在所描述的仓库内并在 CI 中校验。非 Python 语言的扇入为启发式,可能高估常见名称。具体收费、平台支持等信息暂未提供。