# 5 分钟上手

第一次装 dsh-global-todo 的完整路径：装上、打开面板、写第一条带步骤的待办、交给一个对话、弄清
「待确认」是什么，最后知道数据在哪、怎么备份。不解释设计，只说每一步点哪里。

先说清它最要紧的一条规则，后面每一步都绕着它：**Agent 说「做完了」不算完成**——它自己在工具里
报的、或者交给的会话干净收尾后宿主自动收尾的，都只进「待确认」，你点头才算（§5）。

## 0. 前提

| 需要 | 检查 |
|---|---|
| DSH `0.2.x`（`engines.dsh` 是 `>=0.2.0-rc.1 <0.3.0`；0.2.1-rc.2 上开发验证，0.2.1-rc.3 已核对） | `dsh --version` |
| Node.js `>= 22.19.0` | `node -v` |
| Web 客户端（面板由宿主 web server 提供） | 浏览器打开 `dsh web` 给出的地址 |

headless / ACP / SDK 组合里没有面板，只剩 Agent 工具。

## 1. 安装

先看你实际有哪些 profile（插件是装进某一个 profile，不是装进整台机器）：

```sh
ls ~/.dsh/profiles          # Windows: dir %USERPROFILE%\.dsh\profiles
```

把打印出来的名字填进去（大多数是 `web`）：

```sh
dsh plugin --profile <profile> add dsh-global-todo
```

装完**重启宿主**（`dsh web`，或你用的那个启动命令），再**刷新页面**。插件是 Loader 里的一行，
不是热加载脚本。

验证：侧栏出现「待办」入口。

侧栏还是空的？按顺序查三件事：① 你装的是不是正在跑的那个 profile；② 宿主有没有真的重启；
③ 页面有没有刷新。三件都对还是没有，跑 `npx dsh-global-todo-doctor <插件目录>` 自检。

## 2. 打开面板

点侧栏的「待办」。这是**全局面板**：不绑定某个会话，切到别的对话、关掉再开，清单还是同一份。
入口是插件注册到侧栏的固定项（`order: 86`），装好就在，不需要再单独「固定」；侧栏收起时，
用它的展开按钮打开即可。

第一眼应该看到：顶部计数胶囊（全部 / 未完成 / 逾期 / 待确认 / 收件箱…）、工具条、列表。

## 3. 加第一条（带步骤）

1. 点工具条的「添加」，出现输入框；写一句标题，回车（或点「添加」）保存。
2. 点输入框旁的「更多字段」，展开描述、附件、步骤、标签、优先级、截止时间。
3. 在「步骤」里一行写一步，最多 20 步、每步 200 字。这一步就是交出去时那份编号计划。
4. 有文档就贴**绝对路径**（一行一个），有网页就贴 URL；带用户名密码的 URL 会被拒绝。
5. 保存。

之后在详情里勾掉做完的步骤；行上显示「步骤 1/5」。

## 4. 交给一个对话

1. 先在工具条的 `交给：` 下拉里选目标：
   - 默认是**当前对话**（你最近在里面写过消息的那个）；
   - `自动`：先看这条待办已绑定的会话，其次当前对话，最后才新开；
   - `＋ 开一个新对话`：总是新开，工作区跟着写这条待办时的对话。
2. 鼠标移到那一行，点「交给 Agent」。
3. 面板会回执交给了哪个对话，并给一个「打开那个对话」的按钮；详情里的「最近派发」记着结果和原因。
4. 想知道那边进展：详情里的「会话回读」显示**会话在跑 / 已休眠**和它最后说的一句话，带一个打开按钮。

找不到可用对话时派发会**明确失败并说明原因**（比如没有工作目录），不会悄悄开一个。

## 5. 「待确认」是什么

Agent 说做完了，不等于你做完了：

- 那一行变成已完成，同时挂上「待确认」徽标；顶部出现带计数的「待确认」筛选。
- 点「确认完成」：保持已完成，标记消失。
- 点「退回清单」：回到未完成，完成记录清空，事情继续留在清单里。

自动收尾（派发出去的会话干净结束）也走同一条规则，所以「一份干砸的活显示成已完成」不会发生。

## 6. 数据在哪，怎么备份

| 东西 | 位置 |
|---|---|
| 清单 | `$DSH_HOME/global-todo/todos.json`（默认 `~/.dsh/global-todo/todos.json`） |
| 宿主侧设置 | 同目录的 `settings.json` |
| 面板错误日志 | 同目录的 `client-errors.log` |

写入是「临时文件 + rename」，所以**直接复制这个文件**拿到的一定是一份完整 JSON：要么旧版，
要么新版，不会是半截。

另一个宿主进程同时写同一份清单也可以：写入期间同目录会有一个 `todos.json.lock`，后来者排队，
等不到 5 秒就报 `store-busy`（503）。它**不是数据**——备份时不用管，确认没人在写时删掉也不丢东西。

| 方式 | 怎么做 | 适合 |
|---|---|---|
| 复制文件 | `cp "$DSH_HOME/global-todo/todos.json" ~/backup/todos.json` | 快照、放进同步盘或版本库 |
| 导出 JSON | 面板「更多操作 → 导出」 | 需要导回去：面板导入用 merge（按记录合并，删除随墓碑传播），API 传 `mode: 'replace'` 是精确还原 |
| 导出 Markdown | 面板「更多操作 → 导出 Markdown」 | 要读、要 diff、要贴进笔记（导入时只新增，不覆盖） |

换机器（一次性的搬运）：把上面那个文件复制过去，或临时把新环境的 `storePath` 指向它。

**两台机器长期共用一份清单**：不要共享同一个 `storePath`（每次读都走网络，断网就打不开）。在每台机器的
面板里打开 设置 → 多端同步，填同一个绝对路径，各自留一份本地文件、在那个目录里折成一份：

```
SER8:   /mnt/nas/agent-rw/global-todo
笔记本: Z:\Agent产出\global-todo      （或 UNC 路径）
```

按记录合并：同一条看 `updatedAt`；删除留墓碑，另一台的旧副本不会把它带回来；两台离线都新建时编号会重排。
「自动同步间隔」填 0 就只在手动同步。详见 [README](../README.md) 的「两台机器，一份清单」。

## 7. 接下来

- **让对话自己记**：点面板上的「从本对话抓取」，或直接对 Agent 说「抓一下待办」。
- **到点提醒**：设置里勾「开启到点提醒」，可设「提前（分钟）」并「开启系统通知」。
- **一周回顾**：「更多操作 → 本周报告」。
- **收件箱**：外部写入、置信度低于阈值的条目先进收件箱；确认后才进清单，超过 7 天没人确认会被归档
  （宿主每 6 小时扫一次）。

更多问题见 [FAQ](FAQ.md)；数据模型和被否掉的方案见 [DESIGN.md](DESIGN.md)。