| name | code-walkthrough |
| description | 与用户共同阅读代码，逐层讲解架构与数据流。支持自底向上分层模式和调用链追踪模式。主动发现 dead code、设计偏差、迁移遗漏，但不修改代码。先建立全局视角再逐文件深入，阅读过程中可随时 zoom out 回到全景。Use when user wants to walkthrough code, understand architecture, trace call chains, review a module's structure, or says "过代码" / "walkthrough" / "walk me through" / "zoom out". |
Code Walkthrough
与用户共同阅读代码，逐文件讲解架构、数据流与设计决策。纯讲解 + 审查，不修改代码。
核心原则
- 先全景再深入 -- 先建立模块全局地图，再逐文件探索；不知道全貌就不知道该看什么
- 逐文件推进 -- 每次只读一个文件，讲完要点、确认用户无问题后再继续，不批量扫
- 证据驱动 -- 所有讲解必须引用具体文件路径和行号，不凭印象说话
- 主动审查 -- 阅读过程中主动标注 dead code、设计偏差、迁移遗漏、边界缺失，但不修改代码
- 交互确认 -- 每个文件讲完后等用户确认，用户有疑问优先解答再继续
- 用户主导节奏 -- 用户说"继续"才到下一个文件，用户说"看看这个"就切换焦点
两种模式
模式 A：自底向上分层（默认）
从数据实体开始，逐层向上经过 Repository → Service → Handler → Domain → Engine → Task。
适用场景：新接手模块、架构改造后全貌理解、PRD 实现 review。
层级顺序（按 DDD 四层架构）：
Layer 1: 数据实体 / 值对象（domain/entity/, domain/value_object/）
Layer 2: 仓储接口（domain/repository/）
Layer 3: 仓储实现（infrastructure/db/）
Layer 4: Application Service（application/service/）
Layer 5: Handler / API 层（handler/ 或 app/）
Layer 6: Domain 核心接口与模型（domain/ 核心类型）
Layer 7: Engine / 编排层（domain/engine/ 或 application/service/ 编排逻辑）
Layer 8: App 层适配器 / Helper（app/ 下的 adapter、helper）
Layer 9: 生产装配（bootstrap/）
Layer 10: 具体业务实现（task/、handler/ 具体实现）
每层只选 1-2 个代表性文件深入，不求全覆盖。用户可以随时跳过某层或深入某层。
模式 B：调用链追踪
从一个入口点出发，沿调用链逐函数深入。
适用场景：排查问题、理解某个具体流程、验证数据流正确性。
流程：
- 用户指定入口（如 "从 Engine.Execute 开始" 或 "从 POST /api/v1/xxx 开始"）
- 读取入口函数，讲解输入/输出/关键分支
- 沿主路径追踪下一个被调用的函数
- 每个函数讲完后确认，用户可以要求深入某个分支或跳过
工作流
Phase 1: 确定阅读范围
根据用户输入判断模式和范围：
| 用户输入 | 处理方式 |
|---|
| 指定目录/模块名（如 "workflow 资源审计"） | 模式 A，扫描目录结构确定层级 |
| 指定文件/类型名（如 "SaveALBTask"） | 先用 grep/find 推导上下游，用户选择模式 |
| 指定入口函数（如 "从 Engine.Execute 开始"） | 模式 B，沿调用链追踪 |
| 模糊描述（如 "过一下这块代码"） | 用 ask_user_question 确认范围和模式 |
范围推导：当用户只给了起点时：
- 用
fffind / grep 找到相关文件
- 识别文件的 DDD 层级（entity / repository / service / handler / task）
- 按层级排序，构建阅读清单
- 展示清单给用户确认后开始
Phase 2: 全局视角（Zoom Out）
在逐文件阅读之前，先建立模块全景认知。 不知道全貌就不知道该看什么、以什么顺序看。
2.1 扫描模块结构
用 fffind / grep / ls 扫描目标模块的所有相关文件，识别：
- 涉及哪些子目录 / 包
- 每个文件属于哪个 DDD 层
- 文件间的依赖关系（通过 import 和调用关系推导）
2.2 绘制模块地图
用项目的领域词汇（而非泛化的技术词汇）绘制全景地图：
呈现格式：
workflow 资源审计模块全景（15 个文件）
├── domain/flow/ ← 审计声明模型（flow 包，不依赖 mife_cluster）
│ ├── resource_audit.go ResourceChange / Declaration / Writer 接口
│ ├── resource_audit_collector.go Collector（有变更 task 嵌入用）
│ ├── no_resource_change_audit.go NoResourceChangeAudit（无变更 task 嵌入用）
│ └── flow_task.go FlowTask 接口 + DeclareResourceAudit
│
├── domain/engine/ ← Engine 审计处理
│ ├── engine.go Engine 结构体 + writer 注入
│ └── task_executor.go processResourceAudit 核心逻辑
│
├── app/workflow/audit/ ← App 层适配器
│ ├── writer.go ResourceAuditWriter（flow → entity 转换）
│ └── resource_change.go AlbCreated / NodeCreated 等 helper
│
├── domain/resource_audit/ ← 持久化层
│ ├── entity/change_record.go ResourceChangeRecord 实体
│ ├── repository/audit_repository.go AuditRepository 接口
│ └── infrastructure/db/ GORM 实现
│
└── bootstrap/ ← 生产装配
└── register_admin_workflows.go deps 注册 + writer 注入
数据流方向：task → collector → Engine → writer → service → repository → DB
关键要求：
- 使用领域术语（如"资源审计声明"而非"audit struct"、"Collector"而非"helper class"）
- 标注每个子模块的职责，让未读代码的人也能理解模块边界
- 标注模块间的调用关系和数据流方向
- 如果涉及改造，标注哪些是新增、哪些是待删除
2.3 确认阅读计划
展示全景地图后，向用户确认：
- 推荐的阅读顺序（如 "建议从底层数据模型开始，逐层向上"）
- 用户是否想调整顺序（如 "先看 Engine 还是先看 entity"）
- 是否有特定文件想跳过或重点深入
用户确认后进入 Phase 3。
Phase 3: 逐文件阅读
对阅读清单中的每个文件，执行以下步骤：
3.1 读取文件
用 read 工具完整读取目标文件。如果文件超过 200 行，分段读取但保持讲解连贯。
3.2 讲解要点
每个文件讲解以下内容（按需，不求全覆盖）：
结构梳理：
- 文件属于哪个 DDD 层、什么职责
- 核心类型/接口/函数及其作用
- 与上下游的关系（被谁调用、调用谁）
关键设计：
- 重要的设计决策和权衡
- 接口契约和约束
- 错误处理策略
具体引用：
- 始终使用
文件路径:行号 格式引用
- 关键代码片段直接贴出（不超过 10 行）
3.3 主动审查
阅读过程中主动检查以下问题：
| 检查项 | 说明 |
|---|
| Dead code | 没有调用方的函数/方法/类型 |
| 设计偏差 | 实现与文档/PRD 描述不一致 |
| 迁移遗漏 | 接口变更后未同步更新的实现 |
| 边界缺失 | 缺少 nil 检查、空值处理、错误传播 |
| 层级违规 | 上层依赖下层的反向依赖、跨层直接访问 |
| 重复逻辑 | 多处存在相似代码应提取为共享函数 |
发现问题时：
- 在讲解中自然地标注出来
- 说明问题是什么、为什么是问题
- 不修改代码，除非用户明确要求
- 如果用户要求修复，标记为待办，继续阅读流程
3.4 确认与互动
每个文件讲完后：
- 问"有什么想讨论的，还是继续看下一个？"
- 用户有疑问时优先解答
- 用户可以说"继续"、"跳过"、"深入看某个部分"
- 用户可以随时改变阅读顺序
3.5 按需 Zoom Out
在逐文件阅读过程中，用户可以随时要求回到全局视角（如说 "zoom out"、"往上拉一层"、"给我个全景"），或者在以下时机自动触发：
- 过完一个 DDD 层级后，进入下一层之前
- 连续读了 3-4 个同层文件后，帮助用户重新建立整体认知
- 用户表示"有点迷失"或"这跟前面什么关系"时
执行方式：用最新的已读状态重新绘制 Phase 2 的模块地图（✅ 标记已读文件），问用户："要继续逐文件深入，还是先看看其他层？"
Phase 4: 层级总结
每过完一个 DDD 层级后，做一个简要总结：
- 该层有哪些文件、各自职责
- 该层与上下游的接口契约
- 发现的问题汇总
Phase 5: 全貌总结
所有文件过完后，输出完整总结：
## 代码地图
### 分层结构
[按层级列出所有文件及其职责]
### 数据流
[从入口到出口的完整调用链，标注文件:行号]
### 设计决策
[关键决策及其权衡]
### 发现的问题
[按严重程度排列的问题列表]
- Dead code: [文件:行号]
- 设计偏差: [描述]
- 迁移遗漏: [描述]
### 待确认项
[阅读过程中未解决的开放问题]
讲解风格
- 先说结论再展开：先用一句话概括文件作用，再展开细节
- 用表格梳理复杂关系：多个类型/方法的对比用表格，不用长段文字
- 用流程图梳理执行顺序：多步骤流程用缩进文本树，不用纯文字描述
- 对比新旧：如果涉及改造，同时展示旧方案和新方案的差异
- 标注置信度：对把握不足的部分说"这里我不确定，建议验证"
- 用领域词汇：描述模块和调用关系时，使用项目的领域术语（如"资源审计声明"而非"audit object"），帮助用户建立领域心智模型
关键规则
- 先全景再深入 -- 必须先建立模块地图，再逐文件探索
- 不改代码 -- 纯讲解 + 审查，除非用户明确说"帮我修一下"
- 逐文件推进 -- 不批量读取，每读一个文件讲完确认后再继续
- 有证据 -- 所有讲解引用具体
文件路径:行号
- 主动审查 -- 阅读时标注 dead code、设计偏差、迁移遗漏
- 用户主导 -- 用户控制节奏，可以说"继续"、"跳过"、"深入"、"换个方向"、"zoom out"
- 不猜测 -- 代码意图不明确时说"这里我不确定"，不自行推测
- 语言一致 -- 使用用户的语言（中文/英文）
