Code Walkthrough

---
name: code-walkthrough
description: 与用户共同阅读 Neeko 代码，逐层讲解 Tauri 应用架构与跨端数据流。支持三域分层模式（Rust 后端 / React 前端 / 跨端桥接）和调用链追踪模式（含跨端追踪）。主动发现 dead code、设计偏差、类型不一致、迁移遗漏，但不修改代码。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

与用户共同阅读 Neeko 代码，逐文件讲解 Tauri 应用架构、跨端数据流与设计决策。纯讲解 + 审查，不修改代码。

---

## 核心原则

1. **先全景再深入** -- 先建立模块全局地图，再逐文件探索；不知道全貌就不知道该看什么
2. **逐文件推进** -- 每次只读一个文件，讲完要点、确认用户无问题后再继续，不批量扫
3. **证据驱动** -- 所有讲解必须引用具体文件路径和行号，不凭印象说话
4. **主动审查** -- 阅读过程中主动标注 dead code、设计偏差、类型不一致、迁移遗漏，但不修改代码
5. **交互确认** -- 每个文件讲完后等用户确认，用户有疑问优先解答再继续
6. **用户主导节奏** -- 用户说"继续"才到下一个文件，用户说"看看这个"就切换焦点
7. **双端意识** -- 始终关注 Rust 后端与 React 前端的契约关系，标注跨端依赖

---

## Neeko 架构概览

Neeko 是基于 **Tauri 2 + React 18** 的桌面应用。代码分为三个域：

```
┌─────────────────────────────────────────────────────────────────┐
│                         React 前端 (src/)                        │
│  components/ → hooks/ → store/ ← contexts/ ← types.ts          │
└───────────────────────────┬─────────────────────────────────────┘
                            │ @tauri-apps/api/core.invoke()
                            │ Tauri Events (listen/emit)
┌───────────────────────────┴─────────────────────────────────────┐
│                    Rust 后端 (src-tauri/src/)                     │
│  commands/ → managers → models/ + storage.rs + git/ + skill/    │
└─────────────────────────────────────────────────────────────────┘
```

**核心数据流**：
- 前端 → 后端：`hooks` 调用 `invoke("command_name", args)` → Tauri IPC → `commands/<domain>.rs` → `managers`
- 后端 → 前端：`app.emit("event-name", payload)` → 前端 `listen()` → hooks/store 更新
- 类型契约：`src-tauri/src/models/` ↔ `src/types.ts`（serde 序列化）

---

## 两种模式

### 模式 A：三域分层（默认）

从数据模型开始，按三个域逐层向上阅读。

**适用场景**：新接手模块、架构改造后全貌理解、PRD 实现 review。

**域与层级**：

```
域 1: Rust 后端（src-tauri/src/）
├── Layer 1: 数据模型（models/）             -- 共享契约层，Rust ↔ TS 类型同步
├── Layer 2: 存储层（storage.rs）            -- JSON 持久化
├── Layer 3: Manager（terminal.rs, project.rs, agent.rs 等） -- 业务逻辑核心
├── Layer 4: 命令层（commands/）             -- Tauri IPC 入口，参数校验 + 错误转换
└── Layer 5: 应用组装（app/, app_state.rs）  -- 依赖注入 + 命令注册

域 2: 跨端桥接
├── Layer 6: 类型契约（models/ ↔ types.ts）  -- 结构体/接口对齐
└── Layer 7: IPC 通道（invoke/events）       -- 命令名 + 事件名映射

域 3: React 前端（src/）
├── Layer 8: 类型定义（types.ts）            -- TypeScript 接口
├── Layer 9: 状态管理（store/, contexts/）    -- 全局状态 + 领域动作
├── Layer 10: 自定义 Hooks（hooks/）         -- 业务逻辑封装 + invoke 调用
└── Layer 11: UI 组件（components/）         -- 渲染 + 用户交互
```

每层只选 1-2 个代表性文件深入，不求全覆盖。用户可以随时跳过某层或深入某层。

### 模式 B：调用链追踪

从一个入口点出发，沿调用链逐函数深入。**支持跨端追踪**。

**适用场景**：排查问题、理解某个具体流程、验证数据流正确性。

**流程**：
1. 用户指定入口（如 "从 create_terminal_session 开始" 或 "从 useLocalProjects 开始"）
2. 读取入口函数，讲解输入/输出/关键分支
3. 沿主路径追踪下一个被调用的函数
4. **跨端追踪**：遇到 `invoke()` 调用时，自动跳转到对应的 Rust 命令；遇到 `listen()` 时，标注事件来源
5. 每个函数讲完后确认，用户可以要求深入某个分支或跳过

---

## 工作流

### Phase 1: 确定阅读范围

根据用户输入判断模式和范围：

| 用户输入 | 处理方式 |
|----------|----------|
| 指定目录/模块名（如 "终端管理"、"git 模块"） | 模式 A，扫描目录结构确定层级 |
| 指定文件/类型名（如 "TerminalManager"） | 先用 grep/find 推导上下游，用户选择模式 |
| 指定入口函数（如 "从 create_terminal_session 开始"） | 模式 B，沿调用链追踪 |
| 指定端（如 "看看后端"、"前端怎么实现的"） | 模式 A，聚焦单域 |
| 模糊描述（如 "过一下这块代码"） | 用 `ask_user_question` 确认范围和模式 |

**范围推导**：当用户只给了起点时：
1. 用 `find` / `grep` 找到相关文件
2. 识别文件所属的域和层级（Rust 后端 / 跨端桥接 / React 前端）
3. 按层级排序，构建阅读清单
4. 展示清单给用户确认后开始

### Phase 2: 全局视角（Zoom Out）

**在逐文件阅读之前，先建立模块全景认知。** 不知道全貌就不知道该看什么、以什么顺序看。

#### 2.1 扫描模块结构

用 `find` / `grep` / `ls` 扫描目标模块的所有相关文件，识别：
- 涉及哪些子目录 / 包
- 每个文件属于哪个域和层级
- 文件间的依赖关系（通过 import、use、mod 推导）

#### 2.2 绘制模块地图

用项目的领域词汇绘制全景地图：

**呈现格式**（以终端管理模块为例）：

```
终端管理模块全景（12 个文件）

├── src-tauri/src/models/terminal.rs          ← 数据模型层
│   └── TerminalSession, TerminalStatus       定义终端会话结构
│
├── src-tauri/src/terminal.rs                 ← Manager 层
│   └── TerminalManager                       本地 PTY 生命周期管理
│       ├── create_session()                  创建 PTY 进程
│       ├── write_to_terminal()               写入输入
│       └── close_session()                   关闭并清理
│
├── src-tauri/src/commands/terminal.rs        ← 命令层
│   └── create_terminal_session               Tauri IPC 入口
│       └── 调用 TerminalManager.create_session()
│
├── src-tauri/src/app_state.rs:25             ← 状态组装
│   └── terminal_manager: TerminalManager     注入到 AppStateWrapper
│
│   ─── 跨端桥接 ───
│
├── src/types.ts:42                           ← TypeScript 类型
│   └── TerminalSession                       与 Rust 模型对齐
│
├── src/components/terminal/TerminalView.tsx  ← UI 组件
│   └── xterm.js 渲染 + listen("terminal-output-{id}")
│
├── src/components/terminal/terminalCache.ts  ← 终端实例缓存
│   └── Map<string, Terminal>                 避免重复创建
│
└── src/hooks/useAppContainer.ts:120          ← 容器 Hook
    └── createTerminal() → invoke("create_terminal_session")

数据流：TerminalView → useAppContainer → invoke → commands/terminal → TerminalManager → PTY
事件流：PTY → TerminalManager → emit("terminal-output-{id}") → listen → TerminalView
```

**关键要求**：
- 使用领域术语（如"PTY 会话"而非"process object"、"TerminalManager"而非"service class"）
- 标注每个子模块的职责，让未读代码的人也能理解模块边界
- 标注跨端调用关系（invoke 命令名、事件名）
- 标注数据流向（哪个端发起、哪个端接收）
- 如果涉及改造，标注哪些是新增、哪些是待删除

#### 2.3 确认阅读计划

展示全景地图后，向用户确认：
- 推荐的阅读顺序（如 "建议从 models/ 开始，再看 Manager，最后看前端"）
- 用户是否想调整顺序（如 "先看前端怎么调用的"）
- 是否有特定文件想跳过或重点深入

用户确认后进入 Phase 3。

### Phase 3: 逐文件阅读

对阅读清单中的每个文件，执行以下步骤：

#### 3.1 读取文件

用 `read` 工具完整读取目标文件。如果文件超过 200 行，分段读取但保持讲解连贯。

#### 3.2 讲解要点

每个文件讲解以下内容（按需，不求全覆盖）：

**结构梳理**：
- 文件属于哪个域、什么层级、什么职责
- 核心类型/接口/函数及其作用
- 与上下游的关系（被谁调用、调用谁）

**跨端关注点**（Rust 后端文件）：
- 对应的前端调用方在哪里
- 返回类型是否与 TypeScript 类型一致
- 命令是否已在 `commands/mod.rs` 中注册
- 错误类型是否可序列化（`AppError`）

**跨端关注点**（React 前端文件）：
- 调用了哪些 Rust 命令（`invoke` 调用）
- 监听了哪些事件（`listen` 调用）
- 状态来源是 store 还是 context

**关键设计**：
- 重要的设计决策和权衡
- 接口契约和约束
- 错误处理策略

**具体引用**：
- 始终使用 `文件路径:行号` 格式引用
- 关键代码片段直接贴出（不超过 10 行）

#### 3.3 主动审查

阅读过程中主动检查以下问题：

| 检查项 | 说明 | 适用端 |
|--------|------|--------|
| Dead code | 没有调用方的函数/方法/类型 | 双端 |
| 设计偏差 | 实现与文档/PRD 描述不一致 | 双端 |
| 类型不一致 | Rust 结构体与 TypeScript 接口字段不匹配 | 跨端 |
| 命令注册遗漏 | 命令函数存在但未加入注册宏 | Rust |
| 事件名不匹配 | emit 的事件名与 listen 的事件名不一致 | 跨端 |
| 错误序列化 | AppError 变体缺少 Serialize derive 或消息丢失 | Rust |
| 边界缺失 | 缺少 nil 检查、空值处理、错误传播 | 双端 |
| 锁死锁风险 | 跨 await 持有 Mutex、嵌套锁 | Rust |
| 层级违规 | 上层依赖下层的反向依赖、跨层直接访问 | 双端 |
| 重复逻辑 | 多处存在相似代码应提取为共享函数 | 双端 |

发现问题时：
- 在讲解中自然地标注出来
- 说明问题是什么、为什么是问题
- **不修改代码**，除非用户明确要求
- 如果用户要求修复，标记为待办，继续阅读流程

#### 3.4 确认与互动

每个文件讲完后：
- 问"有什么想讨论的，还是继续看下一个？"
- 用户有疑问时优先解答
- 用户可以说"继续"、"跳过"、"深入看某个部分"
- 用户可以随时改变阅读顺序

#### 3.5 按需 Zoom Out

在逐文件阅读过程中，用户可以随时要求回到全局视角（如说 "zoom out"、"往上拉一层"、"给我个全景"），或者在以下时机自动触发：

- 过完一个域层级后，进入下一层之前
- 连续读了 3-4 个同层文件后，帮助用户重新建立整体认知
- 用户表示"有点迷失"或"这跟前面什么关系"时

**执行方式**：用最新的已读状态重新绘制 Phase 2 的模块地图（✅ 标记已读文件），问用户："要继续逐文件深入，还是先看看其他层？"

### Phase 4: 层级总结

每过完一个域层级后，做一个简要总结：
- 该层有哪些文件、各自职责
- 该层与上下游的接口契约
- 发现的问题汇总

### Phase 5: 全貌总结

所有文件过完后，输出完整总结：

```
## 代码地图

### 分层结构
[按域和层级列出所有文件及其职责]

### 数据流
[从入口到出口的完整调用链，标注文件:行号]
- 前端 → 后端：invoke("command") 链路
- 后端 → 前端：emit("event") 链路

### 类型契约
[Rust 模型与 TypeScript 接口的对应关系]

### 设计决策
[key 设计决策及其权衡]

### 发现的问题
[按严重程度排列的问题列表]
- 类型不一致: [Rust 类型:行号 ↔ TS 接口:行号]
- Dead code: [文件:行号]
- 设计偏差: [描述]
- 迁移遗漏: [描述]

### 待确认项
[阅读过程中未解决的开放问题]
```

---

## 讲解风格

- **先说结论再展开**：先用一句话概括文件作用，再展开细节
- **用表格梳理复杂关系**：多个类型/方法的对比用表格，不用长段文字
- **用流程图梳理执行顺序**：多步骤流程用缩进文本树，不用纯文字描述
- **跨端标注**：涉及跨端调用时，明确标注"前端调用方在 xxx"或"后端实现在 xxx"
- **对比新旧**：如果涉及改造，同时展示旧方案和新方案的差异
- **标注置信度**：对把握不足的部分说"这里我不确定，建议验证"
- **用领域词汇**：描述模块和调用关系时，使用项目的领域术语（如"PTY 会话"、"Skill Store"），帮助用户建立领域心智模型

---

## 关键规则

1. **先全景再深入** -- 必须先建立模块地图，再逐文件探索
2. **不改代码** -- 纯讲解 + 审查，除非用户明确说"帮我修一下"
3. **逐文件推进** -- 不批量读取，每读一个文件讲完确认后再继续
4. **有证据** -- 所有讲解引用具体 `文件路径:行号`
5. **主动审查** -- 阅读时标注 dead code、设计偏差、类型不一致、迁移遗漏
6. **用户主导** -- 用户控制节奏，可以说"继续"、"跳过"、"深入"、"换个方向"、"zoom out"
7. **不猜测** -- 代码意图不明确时说"这里我不确定"，不自行推测
8. **语言一致** -- 使用用户的语言（中文/英文）
9. **双端追踪** -- 涉及跨端调用时，主动标注另一端的位置和实现