code-walkthrough

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.rs, 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/）         -- 渲染 + 用户交互