SuperAPI AI 工具集

explain-architecture

通用与其它

查看项目

更新于 10-16 01:26

技能介绍

用途:为代码库或其中某一部分建立准确的心智模型,并交付为一个自包含的 HTML 导读页。目标是“指路”而非评审,读者读完后应知道各部分是什么、如何拼接、数据流向何处、下一步该看哪里。

主要能力:按结构(有哪些部件、如何连接)与行为(发生什么、按什么顺序)组织内容;包含一张按业务/应用/技术分层的 SVG 全局地图(可点击跳转到对应章节)、技术栈概览、部件清单、层间衔接说明、一条真实请求或事件的端到端流程追踪(每步附 path:line 与简短原样代码片段)、横切关注点、以及“下一步看哪里”。

使用方式:先确定范围(整个仓库、单个服务、单个功能流程或单个模块)与读者视角(新人、实现者、审阅者);默认新人+整仓概览。探索时从入口与清单、顶层结构、接缝(HTTP 路由、事件总线、共享数据层、定时任务/worker)、一条真实端到端流程、横切关注点依次进行,所有论断须以实际读过的文件为依据并引用 path:line。随后复制技能目录中的 assets/template.html 到输出路径(默认 docs/<scope>-architecture.html)并替换槽位。验证命令:SKILL_DIR="<absolute path of the directory containing this SKILL.md>"; python3 "$SKILL_DIR/scripts/validate_explain_architecture.py" <output-file.html>,需退出码为 0,并按共享约定渲染验证。

适用场景:新人上手、架构概览、向他人说明某功能或模块的组织方式。

限制:页面应自包含(内联 CSS、JavaScript、SVG),可直接从磁盘打开,无需服务器;4–6 个章节,仅一条追踪流程,只呈现服务该视角的必要细节;不得编造,代码片段须原样或省略;不做质量评判(那属于 architecture-lens);更深入的单子系统讲解应转向 html-explainer。输出路径若已有产物且未被指定替换,应使用新路径或询问更新哪一个,并保留无关内容。