read-code — 代码结构与逻辑梳理
读取项目（或指定目录/文件）的代码，输出自包含 HTML 代码地图，讲清「模块组成、协作方式、核心逻辑」。
产物面向人快速理解代码，不是 API 参考文档。
触发条件
用户意图匹配以下任一（同类表达皆可）即触发：
- 看项目 / 讲代码结构
- 梳理代码库、出一份文档
- 项目怎么跑起来 / 入口在哪
- 核心逻辑是什么 / 想改应该动哪里
- 生成代码地图 / 架构说明
工作流程
顺序：先全貌 → 后局部 → 再链路。
- 摸底：读 README / CLAUDE.md + 工程配置（
package.json/requirements.txt/pyproject.toml/go.mod），列目录树（排除node_modules/.git/__pycache__/ 构建产物），定技术栈、依赖、启动方式。 - 入口：定位
main/ 路由注册 / 启动脚本 / 构建入口；记录启动命令、端口、必需环境变量。 - 模块职责：逐个核心目录/文件标注「负责什么、不负责什么」；关键文件记路径 + 行号 + 核心函数 + 对外接口。
- 调用链路：从入口走一遍主流程，记录数据/控制流经过的模块顺序，识别分层、依赖方向、有无循环依赖。
- 关键逻辑：核心算法、易错点、边界/异常分支；能用 git log / 注释确认「为什么」就查，查不到不猜。
- 产出 HTML：按下述规范生成自包含 HTML 文件并保存，告知用户路径。
> 预算控制（省 token / 少调用，贯穿全程）：
> - 先定粒度：文件数 <30 逐文件；30~100 按模块讲；>100 只讲骨架 + 重点模块，避免平铺。
> - 优先读入口与大文件：用 wc -l / ls -S 定位最大文件；入口与高扇入文件精读，其余只扫关键段。
> - 片段读取而非整读：大文件用 grep / head -N / sed -n 只读关键段；生成/数据文件（lock、dist、min.js、长 SQL、测试夹具）跳过。
> - 并行读：相互独立的文件在一条消息内并发 Read，减少往返。
> - 链路通则停：主流程走通即收尾，不追求读完所有文件；确有疑点才追加查询。
HTML 输出规范
- 单文件自包含：CSS 内联，无外链 CDN / 字体 / 脚本，可离线打开；
<!DOCTYPE html>+<html lang="zh-CN">+ UTF-8。 - 命名：默认
{项目名}-code-map.html，存项目根目录或用户指定路径；写完后告知路径。 - 页面自上而下：
1. 页头：项目名、一句话简介、技术栈标签、运行方式（启动命令）
2. 目录结构：带职责注释的目录树（关键节点标文件/行号）
3. 模块清单：表格，文件/模块 → 职责 → 关键函数/入口 → 备注
4. 调用链路：编号步骤；复杂时配简单 SVG 流程图（入口到出口，标清数据流方向）
5. 关键逻辑：核心算法/易错点拆解 + 代码片段引用（标文件:行号）
6. 扩展指南：「想改什么 → 改哪里」对照表，每行对应真实文件行号 - 导航与样式：左侧固定 TOC 锚点跳转；长内容用
<details>折叠；简洁干净（系统字体栈、单一强调色、浅色背景）；支持浏览器 Ctrl+F；@media print隐藏侧边栏。 - 模板：结构参照
assets/code-map-template.html——仅在生成 HTML 时按需读取，不必每步加载。
质量要求
- 忠于代码：每个结论有代码依据；不确定标「待确认」，不臆测。
- 结构优先、可扫读：表格 / 列表 / 编号步骤优先，段落克制。
- 粒度得当：小项目逐文件讲，大项目按模块分层。
- 代码引用与真实代码一致，不编造文件 / 行号 / 逻辑。
边界与禁忌
- 不读
node_modules/.git/ 构建产物；超大文件只读关键片段。 - 不编造代码内容与调用关系；拿不准的链路标「待确认」。
- 不写成 API 参考文档——只回答「结构是什么、怎么协作、改哪里」。
<!-- v2: 文案压缩(token↓)、HTML 模板外置按需读取、新增预算控制(粒度分级/片段读取/并行读/链路通则停) -->
