# 桌面端运行与调试手册
## 文档目的
这份手册用于说明如何运行、测试、调试当前 `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. 如果前端继续变复杂，再决定是否引入更正式的前端构建与开发流程