# 桌面端运行与调试手册

## 文档目的

这份手册用于说明如何运行、测试、调试当前 `spool` 的桌面端 host。

当前覆盖范围：

- Rust 桌面后端 facade：`src/desktop.rs`
- Tauri 适配层：`src/desktop/tauri.rs`
- 可运行的 Tauri host：`src-tauri/`
- 最小静态前端工作台：`frontend/`
- 本机 Claude / Codex 会话浏览原型

## 关键目录

相关路径如下：

- 桌面后端 facade：[src/desktop.rs](/Users/long/Work/spool/src/desktop.rs)
- Tauri 命令适配层：[src/desktop/tauri.rs](/Users/long/Work/spool/src/desktop/tauri.rs)
- Host 启动入口：[src-tauri/src/main.rs](/Users/long/Work/spool/src-tauri/src/main.rs)
- Host 命令注册：[src-tauri/src/commands.rs](/Users/long/Work/spool/src-tauri/src/commands.rs)
- Tauri 配置：[src-tauri/tauri.conf.json](/Users/long/Work/spool/src-tauri/tauri.conf.json)
- Capability 配置：[src-tauri/capabilities/default.json](/Users/long/Work/spool/src-tauri/capabilities/default.json)
- 前端页面：[frontend/index.html](/Users/long/Work/spool/frontend/index.html)
- 前端逻辑：[frontend/desktop.js](/Users/long/Work/spool/frontend/desktop.js)
- 前端样式：[frontend/desktop.css](/Users/long/Work/spool/frontend/desktop.css)

## 运行前提

你需要具备：

- 可用的 Rust 工具链，能直接执行 `cargo`
- macOS 桌面会话，能够启动 Tauri 窗口
- 如果本机还没缓存过 Tauri 依赖，第一次编译需要联网下载 crates

可选但推荐准备：

- 一个真实可用的 `spool` 配置文件
- 一个真实 Obsidian vault，且仓库路径能命中 `project.repo_paths`
- 如果要验证 daemon 读路径，准备好 `spool-daemon` 二进制

## 一次性依赖检查

先做桌面 host 的编译检查：

```bash
cargo check --manifest-path src-tauri/Cargo.toml
```

如果这是本机第一次编译 Tauri，Cargo 可能会下载一批依赖。

## 快速验证命令

运行桌面端 smoke 测试：

```bash
cargo test --test tauri_smoke
```

检查前端脚本语法：

```bash
node --check frontend/desktop.js
```

如果想跑更完整的回归：

```bash
cargo test
```

## 启动桌面 Host

启动桌面应用：

```bash
cargo run --manifest-path src-tauri/Cargo.toml
```

预期结果：

- 打开一个标题为 `spool Desktop` 的 Tauri 窗口
- 顶部显示品牌区、语言切换、状态徽标
- 主界面按标签页拆分为：
  - `注入上下文`
  - `会话浏览`
  - `高级工作台`
  - `基础配置`
- 默认不再把所有信息堆在一屏里

## 最小手工测试流程

建议按下面顺序手工 smoke：

1. 先切到 `基础配置`
2. 在 `Config Path` 填入真实配置文件路径
3. 在 `Repo CWD` 填入能命中某个 `project.repo_paths` 的仓库目录
4. 回到 `注入上下文`
5. 填写任务描述与相关文件
6. 点击 `生成注入内容`
7. 确认同时生成：
   - 组合注入文本
   - Context 结果
   - Wakeup 结果
8. 点击 `复制注入内容`
9. 切到 `会话浏览`
10. 点击 `刷新会话`
11. 选择一个 session，确认右侧显示 session 摘要和关联记录
12. 切到 `高级工作台`
13. 点击 `载入工作台`
14. 如果队列里有数据，确认自动选中一条 record
15. 检查 `Selected Record`、`History`、事件列表与 action 按钮
16. 以 `Mode = propose` 创建一条测试 memory
17. 确认队列刷新，并自动选中新建 record
18. 点击 `Accept` 或 `Archive`
19. 确认队列刷新，history 事件数增加

额外观察点：

- 界面右上角语言切换应能在 `中文 / EN` 间切换主要 UI 文案
- `基础配置` 完成后，顶部 `Setup` 徽标应从未完成变为已完成
- `Context Result` 上方应显示一排摘要卡片
- `Wakeup Result` 上方也应显示一排摘要卡片
- `会话浏览` 中应优先出现本机 Claude / Codex 会话列表
- 如果某些会话没有完整 transcript 解析，仍应至少能看到 provider、标题、更新时间等摘要
- `Selected Record` 上方应显示结构化 metadata 摘要卡片
- `History` 面板应显示事件摘要卡片和倒序事件列表
- action 按钮应只在当前 record 允许该状态迁移时可点击
- `Last Error` 面板应在失败时显示结构化错误

## 如何使用 Daemon 读路径

桌面工作台支持可选的 daemon-backed lifecycle reads。

使用方式：

1. 切到 `基础配置`
2. 勾选 `启用 daemon-backed lifecycle reads`
3. 如果需要，填写 `Daemon Bin`

本仓库内的 daemon 二进制默认路径示例：

```bash
target/debug/spool-daemon
```

如果不勾选 daemon 模式，桌面端会走 direct read 路径。

## 构建 Daemon 二进制

如果要先准备本地 daemon：

```bash
cargo build --bin spool-daemon
```

## 调试排查清单

### 应用能启动，但命令执行失败

优先检查：

- `Config Path` 是否真实存在，且指向合法 TOML
- `Repo CWD` 是否命中某个 `project.repo_paths`
- 配置中的 vault 路径是否真实存在
- 桌面端 `Last Error` 面板里是否返回结构化 `DesktopErrorEnvelope`

### 应用能编译，但看不到窗口

优先检查：

- 是否在真实 macOS 桌面会话中运行
- 是否被系统窗口权限、沙箱或会话环境拦住
- `cargo run --manifest-path src-tauri/Cargo.toml` 是否真的进入了运行态

### 直接用浏览器打开页面后，命令全部失败

如果你直接打开 `frontend/index.html`，那么 `window.__TAURI__` 不存在。

此时预期表现是：

- `Bridge` 状态显示为 `browser`
- 所有命令调用都会失败，因为没有 Tauri invoke bridge

这是正常现象。该页面必须由 Tauri host 托管运行。

### Tauri host 编译时报 icon/config 问题

检查：

- [src-tauri/icons/icon.png](/Users/long/Work/spool/src-tauri/icons/icon.png) 是否存在
- [src-tauri/tauri.conf.json](/Users/long/Work/spool/src-tauri/tauri.conf.json) 是否是合法 JSON
- [src-tauri/capabilities/default.json](/Users/long/Work/spool/src-tauri/capabilities/default.json) 是否存在

### Tauri IPC 权限问题

重点检查 capability 文件：

- [src-tauri/capabilities/default.json](/Users/long/Work/spool/src-tauri/capabilities/default.json)

当前 host 使用的是一个较窄的默认 capability，仅给 `main` 窗口开放 core app/window/webview/event 权限。

## 关于会话浏览的当前语义

当前的 `会话浏览` 已经开始读取本机会话源：

- `~/.claude/projects/**/sessions-index.json`
- `~/.claude/projects/**/*.jsonl`
- `~/.codex/session_index.jsonl`
- `~/.codex/sessions/**/*.jsonl`

但目前仍然是原型阶段：

- Claude 会话详情优先来自本地 `.jsonl`
- Codex 会话列表与基础详情已接入
- 仍然没有覆盖所有 AI 工具，也还不是完整统一的 transcript 平台
- `spool memory` 中的 `session:*` 引用仍会作为补充来源保留

## 常用开发命令

桌面 host 编译检查：

```bash
cargo check --manifest-path src-tauri/Cargo.toml
```

桌面 host 启动：

```bash
cargo run --manifest-path src-tauri/Cargo.toml
```

桌面 smoke 测试：

```bash
cargo test --test tauri_smoke
```

全量测试：

```bash
cargo test
```

构建 daemon：

```bash
cargo build --bin spool-daemon
```

检查前端脚本语法：

```bash
node --check frontend/desktop.js
```

## 当前限制

- 前端工作台还比较早期，主要偏开发/调试用途
- 还没有 batch lifecycle actions
- 还没有 edit-in-place memory 编辑
- 还没有完整的桌面打包流程
- 还没有更成熟的前端状态管理层

## 下一步建议重点

如果继续扩展桌面工作台，优先看这些点：

1. 继续把 detail/history 从文本块推进到更强的结构化视图
2. 增加更明确的 lifecycle queue 过滤与排序能力
3. 在界面上展示更明确的 daemon 诊断状态
4. 如果前端继续变复杂，再决定是否引入更正式的前端构建与开发流程
