# 使用指南

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

## 一、安装与启动

YOLO 需要运行在 **dsh 0.1.5-rc.1 或更新版本**的宿主上；更旧的宿主无法加载本版的浏览器面板，
插件设置页也不会出现这一版的配置卡。可以先运行 `npx @deepseek-ai/dsh --version` 确认版本，必要时用
`npm install -g @deepseek-ai/dsh@latest` 升级 dsh。

安装 [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.5.0
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.5.0
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.5.0
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 使用语义理解
识别事项，不要求你记住关键词或命令。

### 目标、事项和里程碑

- **事项**是一次具体行动或安排，例如「周五前把演示稿发给研发」；它可以独立提醒、完成、推迟或取消。
- **里程碑**是用户标记的阶段结果或检查点，例如「灰度验证通过」；它不是事项的父容器，也不要求一定有支持事项。
- **目标**是需要一段时间持续跟进的最终结果，例如「9 月完成产品发布」；它可以关联多个支持事项和里程碑，但事项完成数量不会自动宣布目标达成。

明确说「帮我持续跟进」且结果足够清楚时，目标可以直接进入进行中；只有长期愿望或意图不明确时，会先作为待确认目标。进入 **计划 → 目标** 后，可以看到完成标准、当前下一步、目标日期、最近进展和阶段标记，并通过「推进目标」进入目标专属讨论。完成标准满足后仍需用户明确选择「达成」；「放弃」只停止继续跟进，不会删除关联事项或历史。

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

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

- **首页**：先明确今天需要处理的事项数量，再展示当前需要回应的助手判断、提醒和今天事项；次级安排按分组卡片收束，普通无日期积压不会为了填满页面而出现；
- **计划**：按“今天 / 接下来 / 目标 / 全部”组织开放事项，高级筛选只影响计划；未从对话中提取到明确日期的事项，行内截止日期按“今天”显示；
- **历史**：可在“按时间 / 按事项”之间切换，默认只看今天的变化，也可选择其他日期或切换到全部时间。按时间以日期组织完整变化，按事项把同一事项的新增、改期、编辑、完成、取消和重新打开串成一条记录，并可按进行中、已结束、已完成或已取消筛选；提醒扫描、简报生成、已读等系统操作不会混入用户变化。早期无法确认属于哪件事项的记录只留在时间线，不会按标题猜测归组。

点击事项可完成、推迟、编辑或与助手讨论。完成后会短暂提供撤销入口。看板会聚合所有已知
工作区的事项，每一行仍保留所属工作区，操作会更新正确的数据。
首页按“工作区 + 事项”去重，同一事项有多条未处理提醒时只展示一个事项。顶部「通知」数字表示
自上次查看以来的新通知，不代表未完成事项；打开通知记录后数字归零，仍未处理的事项继续留在首页。
部分工作区加载失败时，页面只统计已加载内容并明确提示。

### 取消与永久删除

事项详情中的两种操作含义不同：

- **取消事项**：事项移到历史的“已取消”，保留来源与变化记录，之后可以重新打开；
- **永久删除事项**：输入“永久删除”确认后，移除事项及相关的合并记录、来源信息、提醒、推荐反馈、待发送提醒和搜索记录，不能撤销。原始宿主会话与既有时间线不在本次删除范围内。

顶部「更多 → 按日期删除事项」支持按**截止日期**或**创建日期**选择某一天或包含首尾两天的日期区间，
执行前会展示事项数量和标题。批量取消只处理待处理和进行中的事项；永久删除会处理范围内所有
状态的事项。默认只作用当前工作区，选择“全部已知工作区”后才会跨工作区处理；部分工作区不可用时，
系统会禁止全局批量操作，避免静默漏处理。按截止日期处理时，没有截止日期的事项不在范围内。

提醒或简报到达时，侧边栏会显示新通知信号，页面右下角也会出现约 10 秒的提示；鼠标停留、键盘
焦点进入提示或页面暂时隐藏时，倒计时会暂停。提示不会主动抢走键盘焦点，点击后可直接打开
关联事项或通知记录；忽略提示不会丢失内容，完整投递历史可从顶部「通知」分页查看。通知记录只负责
阅读、追溯和打开事项，完成、推迟或“知道了”仍在首页与事项详情中处理。提醒不会插入正在进行的
工作会话。

已经看过的通知不会自动消失，长期使用会一直堆积，所以通知记录可以随时清理：卡片元信息行右端的
`×` 删除这一条投递；面板头部的「一键清除」在二次确认后清空整个记录（跨所有已知工作区）。删除
只作用于投递记录本身，刷新或换一个浏览器看到的都是同一份剩余记录，任何事项状态都不会因此改变；
首页仍未处理的提醒需要在那里正常回应。

顶部的「和助手聊聊」每次打开都会开启一个新的独立会话，不会带入上一次助手对话的历史；输入框支持多行内容，Enter 仍可直接发送。从某个事项选择
「讨论这项安排」则开启只围绕该事项的独立讨论，两类对话不会混用历史。事项详情、事项讨论、助手对话和来源预览共享同一个上下文位置：
标准宽度下替换主面，空间足够时才在主面右侧显示一个 340px 上下文区，不会形成三栏。
改变宿主侧栏或窗口宽度只改变呈现，不会更换页面、线程、等待中的请求、草稿或滚动位置。

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

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

## 五、设置

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

| 设置 | 作用 |
|---|---|
| 启用 LLM 提取 | 是否在对话结束后整理计划 |
| 提取模型 | 用于理解对话并整理事项的模型 |
| 高置信事项自动关联（实验性） | 默认关闭；仅把置信度达到阈值、唯一开放候选的后续提及关联到原事项，或修改明确截止时间 |
| 关联置信度阈值 | 0 到 1 之间的数字，默认 0.85；越低越容易自动关联，也越需要留意误关联 |
| 重复事项合并建议（实验性） | 默认关闭；结合对话含义和标题中的核心动作、对象显示同工作区候选、理由与置信度，始终要求人工确认 |
| 启用到期提醒 | 是否扫描并生成到期提醒 |
| 扫描间隔 | 检查到期事项的频率 |
| 提前量 | 在截止时间前多久提醒；`0` 表示到点提醒。只写日期、不写钟点的事项，从当天 `00:00` 起进入提醒窗口（逾期从次日才计起），设置提前量可让它提前到前一晚触发 |
| 安静时段 | 在指定时间内暂缓提醒，结束后补发 |
| 早晚报 | 是否生成每日早报、晚报，以及时间与润色模型 |
| 快照节奏 | 每天或每 10 轮对话生成一次 Markdown 快照 |

有新版本时，YOLO 这张卡片的标题行会出现「有新版本」标记（不必展开就能看到），展开后给出新版本号
和一条可直接执行的更新命令：

```bash
npx @deepseek-ai/dsh plugin --profile web add dsh-plugin-yolo@<新版本>
```

比较的是 npm 上 `latest` 指向的版本。

早报会先突出当前最该处理的一项，并列出今日到期、逾期和近期变化；晚报会总结完成、新增、未完成及明日优先事项。早晚报与提醒一起进入顶部通知记录，可展开阅读完整正文。
修改提醒扫描间隔后，需要重新启动 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，或把工作区移动到当前用户拥有的
目录下。