# 使用指南

YOLO 会把对话中需要继续跟进的事项整理成计划，并在到期时提醒你。它负责记录、整理和提醒，
不会在未经授权的情况下替你执行任务。

## 一、安装与启动

安装 [Node.js](https://nodejs.org/) 22 LTS（至少 22.19）或 Node.js 24，并确保 `pnpm` 命令可用。
如果尚未启用 pnpm，先运行 `corepack enable`。然后执行：

```bash
npx @deepseek-ai/dsh plugin --profile web add dsh-plugin-yolo@0.4.0-rc1
npx @deepseek-ai/dsh web
```

页面默认在 [http://127.0.0.1:3080](http://127.0.0.1:3080) 打开。若不希望自动打开浏览器，
在第二条命令后添加 `--no-open`；若 3080 端口已被占用，可添加 `--port 4080`。

也可以从固定的 GitHub 标签安装：

```bash
npx @deepseek-ai/dsh plugin --profile web add github:hanshanyike/dsh-yolo#v0.4.0-rc1
npx @deepseek-ai/dsh web
```

GitHub 安装会在本机完成构建。如果安装过程要求批准构建脚本，请运行
`npx @deepseek-ai/dsh plugin --profile web approve-builds` 命令，选择 `dsh-plugin-yolo` 后重试。
日常使用推荐 npm 安装，步骤更少。

也可以克隆仓库并从源码构建安装：

```bash
git clone https://github.com/hanshanyike/dsh-yolo.git
cd dsh-yolo
git checkout v0.4.0-rc1
corepack enable
pnpm install --frozen-lockfile
pnpm build
npx @deepseek-ai/dsh plugin --profile web add .
npx @deepseek-ai/dsh web
```

源码安装会把当前目录链接到 `web` profile，适合调试或验证尚未发布到 npm 的提交。切换标签或拉取更新后，
需要重新执行 `pnpm install --frozen-lockfile` 和 `pnpm build`。

## 二、第一次使用

1. 在 dsh 中选择一个工作区并开始对话。
2. 自然地说明要跟进的事情和时间，例如「周五前把演示稿发给研发」。
3. 对话结束后，YOLO 会整理明确的待办、目标、里程碑和提醒时间。
4. 点击左侧边栏底部的 **YOLO**，在助手看板中查看和处理这些事项。

后续不必使用固定格式。当所指事项足够明确时，你可以说「做完了」「推迟到下周一」或「目标
完成了一半」，YOLO 会更新对应事项，并保留变化记录。

## 三、YOLO 会记录什么

YOLO 只保留与持续跟进有关的信息：

- 有明确结果的待办和日程安排；
- 跨天或跨周的目标；
- 有目标日期的里程碑；
- 影响跟进方式的规则，例如提前多久提醒、什么时间不要打扰；
- 与计划变化有关的决定和进展。

寒暄、通用知识、人物画像，以及与计划管理无关的偏好不会进入长期记录。YOLO 使用语义理解
识别事项，不要求你记住关键词或命令。

## 四、侧边栏看板与提醒

助手看板按以下页面组织事项：

- **首页**：当前需要回应的助手判断、提醒和今天事项；普通无日期积压不会为了填满页面而出现；
- **计划**：按“今天 / 接下来 / 目标 / 全部”组织开放事项，高级筛选只影响计划；
- **历史**：严格分开已完成、已取消和最近变化；提醒扫描、简报生成、已读等内部审计不会伪装成用户进展。

点击事项可完成、推迟、编辑或与助手讨论。完成后会短暂提供撤销入口。看板会聚合所有已知
工作区的事项，每一行仍保留所属工作区，操作会更新正确的数据。
首页按“工作区 + 事项”去重，同一事项有多条未处理提醒时只展示一个事项，但侧栏角标仍精确表示
未处理通知条数。部分工作区加载失败时，页面只统计已加载内容并明确提示。

提醒到期时，侧边栏会显示未处理数量，页面右下角也会出现约 10 秒的提示；鼠标停留、键盘
焦点进入提示或页面暂时隐藏时，倒计时会暂停。提示不会主动抢走键盘焦点，点击后可直接打开
助手看板；忽略提示不会丢失提醒，它仍会留在看板和 YOLO 专属对话中。提醒不会插入正在进行的
工作会话。

顶部的「和助手聊聊」用于询问整体安排。从某个事项选择「讨论这项安排」则开启只围绕该事项的
独立讨论，两类对话不会混用历史。事项详情、事项讨论、助手对话和来源预览共享同一个上下文位置：
标准宽度下替换主面，空间足够时才在主面右侧显示一个 340px 上下文区，不会形成三栏。
改变宿主侧栏或窗口宽度只改变呈现，不会更换页面、线程、等待中的请求、草稿或滚动位置。

点击来源先打开预览。新提取事项可显示有界的用户原话摘录、工作区、会话和记录时间；手动、工具、
早期记录或缺少摘录的数据会明确降级，不伪造跳转。只有成功打开原会话后 YOLO 才会收起；再次
打开 YOLO 会恢复原页面、事项和来源预览。宿主导航失败时预览保持可见，可直接重试。

发送后会先显示“已提交，等待助手回复”；等待较久时只提示回复可能仍在处理中，不会自动重发。
在同一次 dsh 宿主运行期间，收起、展开或重新打开面板都会继续显示这条等待状态。请求状态目前
只保存在宿主进程：重启 dsh 后，已经进入会话记录的消息仍会显示，但尚未写入会话记录的等待项
可能无法恢复；临时事项对话在整页刷新后也不会恢复为同一临时线程。

## 五、设置

在 dsh 的 **设置 → 插件 → YOLO** 中可以调整：

| 设置 | 作用 |
|---|---|
| 启用 LLM 提取 | 是否在对话结束后整理计划 |
| 提取模型 | 用于理解对话并整理事项的模型 |
| 启用到期提醒 | 是否扫描并生成到期提醒 |
| 扫描间隔 | 检查到期事项的频率 |
| 提前量 | 在截止时间前多久提醒；`0` 表示到点提醒 |
| 安静时段 | 在指定时间内暂缓提醒，结束后补发 |
| 早晚报 | 是否生成每日早报、晚报，以及时间与润色模型 |
| 快照节奏 | 每天或每 10 轮对话生成一次 Markdown 快照 |

卡片同时显示当前值与宿主提供的默认值；修改后需要点击「保存设置」，刷新页面可回读已保存值。
修改提醒扫描间隔后，需要重新启动 dsh；其他设置会在下一次提取或调度检查时生效。关闭到期提醒
只停止到期待办扫描，不会关闭已启用的早晚报或快照。

## 六、数据与隐私

YOLO 的数据保存在各工作区的 `.dsh/yolo/` 目录：

```text
<工作区>/.dsh/yolo/
├── yolo-*.db
└── snapshots/
```

数据库是当前计划的主要存储，`snapshots/` 中的 Markdown 文件便于人工查看。数据按工作区
隔离，同一工作区的 Git 分支共享计划；助手看板集中展示多个工作区，但不同工作区仍使用各自的库。
从早期候选版升级时，YOLO 会把同一工作区遗留的分支库幂等合入 cwd 主库并保留源库文件；若某个
遗留库损坏或被锁定，加载错误会明确指出对应文件，不会把它当作空数据跳过。

备份时请复制整个 `.dsh/yolo/` 目录。当前不支持只用 Markdown 快照重建数据库。理解对话时会
调用你在 dsh 中配置的模型，数据处理方式取决于所使用的模型服务。

## 七、常见问题

### 看板显示「加载失败」

确认 dsh 仍在运行，并且已经完成插件安装。必要时重新执行安装命令后再启动 dsh。

### 看板一直为空

YOLO 会在一轮对话结束后整理事项。确认设置中的「启用 LLM 提取」已经打开，并在对话中给出
明确的事项或时间。

### 没有收到提醒

检查「启用提醒」、截止时间、提前量和安静时段。dsh 未运行期间到期的提醒会在下次启动后补发。

### 数据出现在了意外的项目中

数据按工作区保存。请确认当前选择的工作区是否正确；同一工作区切换 Git 分支不会改变计划，
聚合看板会同时显示其他已知工作区的事项，并在每一行标明来源。

### 想清空某个工作区的数据

先退出 dsh 并备份数据，再删除该工作区的 `.dsh/yolo/` 目录。这个操作会同时删除数据库和快照，
且不能在 YOLO 中撤销。

### Windows 启动时报 `SetNamedSecurityInfoW failed (Win32 5)`

这通常是工作区目录权限导致的。可以用管理员身份运行一次 dsh，或把工作区移动到当前用户拥有的
目录下。