# dsh-md-notes 使用文档

> 中文 · [English](usage.md)

一个面向 DeepSeek Harness（DSH）的笔记插件。本文档**从零开始**讲清楚插件的
所有功能与用法——从写第一篇笔记，到用 Git 同步笔记。假定插件已安装
（安装见 [README](../README.zh.md)）。

**一句话概括**：笔记是各工作区 `.dsh-notes/` 目录下的普通 `.md` 文件。你可以在
这里编辑它们、把对话一键记入笔记，还可以（可选地）用 Git 仓库备份 / 多端同步。

---

## 1. 笔记存在哪里

- 每个 dsh **工作区**都有自己的笔记目录：`<工作区>/.dsh-notes/`。
- 每篇笔记就是一个普通的 `.md` 文件。用任意编辑器打开改都行——插件下次读取
  时自然能看到你的修改。
- 目录里的 `meta.json` 只是标题/更新时间的缓存，不用管它（也**不会**被提交到 Git）。

> 笔记**深度绑定工作区**：没有工作区就没有存放位置——请先在 dsh 侧边栏新建工作区。

## 2. 打开笔记管理器

点击侧边栏底部的**笔记入口**，打开全屏管理器，分左右两栏：

- **左栏 — 笔记列表**，按工作区分组。每个工作区一行：文件夹图标、折叠箭头、
  一个「+」新建按钮（在该工作区新建；启用 Git 后还有更新/推送图标按钮，见 [§5](#5-git-同步可选)）。
- **右栏 — 笔记内容**，有「预览 / 编辑」两个 Tab 和「保存」按钮。**点击已有笔记默认打开预览**；
  新建笔记则直接进入编辑模式。

### 新建笔记

点工作区行的「+」。笔记会自动生成标题（「未命名笔记 <日期>」）并**直接进入编辑模式**。

### 编辑与预览

- **预览**：看渲染效果（GFM 表格 / 任务列表 / 公式 / 代码高亮）——点击已有笔记时默认显示。
- **编辑**：直接写 markdown 源码。
- **保存**：写入本地 `.md` 文件并刷新列表。

### 删除笔记

鼠标悬停列表项，点 🗑 图标。会弹确认框（删除不可撤销，请确认）。

### 笔记正在写入时

写入笔记期间，正在写入的笔记**无法编辑**（跨会话锁定），写入完成自动解除。

## 3. 把对话记入笔记

在任意回答下方，点**笔记图标**（复制按钮旁）。弹出选择面板：

1. 选一篇已有笔记——列表按工作区分组展示**所有工作区**的笔记（可折叠/展开
   浏览，当前工作区也在其中），或用任意工作区行上的「+」现场新建一篇。
   **正在写入的笔记不可选中**（行尾有 loading）——同一笔记的写入跨会话互斥。
2. 点「写入笔记」。提问 + 回答文本直接从对话本身提取（**即时、无等待**），作为一段带
   时间戳的内容**追加**到笔记末尾；写入期间按钮显示「写入中…」，成功后按钮**左侧出现
   绿色「已写入 ✓」**再自动关闭弹窗：

   ```markdown
   ---

   ## <会话标题> -- <时间戳>

   ### 👤 <用户标签>
   <提问内容>

   ### 🤖 <助手标签>
   <回答内容>
   ```

## 4. 引用笔记进对话（@ 引用）

在对话输入框里输入 **`@`** 选择笔记：选中后输入框出现一个**笔记 chip**，发送时**笔记内容会自动进入模型上下文**——模型直接就能看到笔记内容并回答，你**不需要**另外说「请读取笔记」。

### 4.1 选择笔记

1. 输入 `@` → 候选菜单列出**当前工作区**的笔记（📝 前缀；行首为标题，副行为文件名）。
2. 上下键 / 点击选中 → 出现笔记 chip；可以继续输入 `@` 多选几篇。
3. 继续输入文字会**过滤**候选（按标题或文件名匹配）。

### 4.2 引用其他工作区的笔记

- 输入部分工作区名（如 `@dsh-pl`）→ 候选出现**工作区行**（`dsh-plugin/`，带 🗂️ 图标）；
- **点击工作区行** → 自动补全为 `@dsh-plugin/` 并**立即列出该工作区的笔记**，继续输入即在该工作区内过滤；
- 精确输入工作区名（如 `@dsh-plugin`）也会直接切换；
- **中文（无空格）工作区名已支持**；只有**带空格**的工作区名无法用文本触发（dsh 输入框
   的触发词遇到空格会截断，这是 dsh 的限制，后续计划提供菜单内全工作区列选）。

### 4.3 发送后会发生什么

发送后发生两件事：

1. **你的消息里保留一行可读引用**（标准 markdown 链接语法），例如
   `引用笔记 [标题](.dsh-notes/xxx.md)`（同工作区）或
   `引用笔记 [标题](../dsh-work/.dsh-notes/xxx.md)`（跨工作区）——告诉模型（和你）引用的是哪篇笔记；
2. **host 端把笔记内容注入模型上下文**——对话里会出现一条可折叠的「上下文注入」行
   （来源标 `md-notes`），展开可以看到注入的笔记内容。模型**直接拿到内容**，不依赖它自己调用
   `read` 工具去读文件。

### 4.4 常见问题

- **追问不用重新引用**：注入的笔记内容会一直留在本次会话的上下文里（直到 dsh 自动压缩旧内容），
  后续追问（如「里面提到的 X 是什么」）模型依然记得。如果担心笔记太长占用上下文，可以开新会话，
  或只引用需要的笔记。
- **笔记被删除 / 移动**：发送时若笔记已不存在，发送会被阻止并提示「<笔记名> 无法找到，
  请删除引用」——删掉失效的 chip 重新发送即可。
- **手打的 `@笔记名` 不会生效**：纯文本的 `@笔记名` 只是输入框里的高亮装饰，**不会**进入
  模型上下文——要引用必须通过菜单选中（chip）。
- **没有工作区**：会话没有工作区时，输入 `@` 不会弹出候选（静默）。

## 5. Git 同步（可选）

Git 同步能把你的笔记备份并跨机器同步。插件会自动管理仓库的**本地 clone**——
你只需要给它一个仓库 **URL**。

> **笔记本地永远存在 `<工作区>/.dsh-notes`**。Git 同步只是把笔记推送到仓库 /
> 从仓库拉取，**不会改变笔记的本地保存位置**。

### 5.1 两种模式（二选一）

在设置面板（见 [§6](#6-设置面板)）里选择模式：

| 模式 | 作用 | 需要配置 |
|---|---|---|
| **关闭** | 不做 Git 同步，笔记就是本地文件 | — |
| **共享仓库** | 一个仓库管所有工作区。每个工作区的笔记同步到该仓库的分支下、以工作区名命名的子目录里 | 仓库 URL + 可选分支（默认 main） |
| **独立仓库** | 每个工作区各自一个仓库 | 每个工作区：仓库 URL + 分支（默认 main）+ 仓库内子路径（默认仓库根） |

> 想要一个仓库管所有东西？用**共享仓库**——每个工作区自动占一个子目录。
> 想按项目分开？用**独立仓库**。

### 5.2 推送笔记

1. 打开任意笔记，点「推送」（在保存按钮旁边）；或直接点笔记列表**工作区行上的推送图标**。
2. 弹出小面板，填提交信息（默认「笔记更新 <时间>」）。确认后提交并推送。
3. 首次推送会自动 clone 仓库（凭据交给 git 自己处理——HTTPS 凭据助手或你的 SSH key）。

**推送前**，插件会检查远端：有没有与你不同的笔记、或只存在于远端的笔记
（比如你在本地删掉的）。有差异时会弹确认：

> 「远端有以下笔记与本地不同或本地已删除：`<名单>`，是否用本地版本覆盖/删除远端？」

- **用本地覆盖远端** → 继续推送，包括把删除同步上去。
- **取消** → 不推送。

### 5.3 更新笔记（拉取）

点「更新」（编辑器上方，或笔记列表**工作区行上的更新图标**）把远端版本拉下来：

- 远端有**你本地没有的新笔记** → 拉下来，左侧列表自动刷新。
- 某篇笔记**两边都改了**（你本地也编辑过）→ 插件保留你的本地版本，并弹窗询问：

  > 「远端有 N 个笔记与本地不同，是否用远端版本覆盖本地？」

  - **用远端覆盖本地** → 远端版本覆盖你的本地文件。
  - **取消** → 本地保持不变。

### 5.4 打开笔记时的自动拉取

打开笔记时（若开启了「自动拉取」），插件会先**静默**拉取远端——**绝不覆盖**
你本地改过的内容。若远端有与本地冲突的笔记，会在「更新」按钮左侧显示提示
「远端有更新，需手动更新」。点「更新」即可处理。

### 5.5 推送被拒绝时

如果远端领先或历史不相关，推送会被拒绝，界面出现「**合并远端并重试**」按钮。
点击它把远端合并进本地 clone，再重新推送。

## 6. 设置面板

打开笔记管理器，点标题旁的 **⚙ 设置图标**（或打开 dsh 的设置 → **MD 笔记**分区）。
所有 Git 相关配置都在这里：

- **模式**：关闭 / 共享仓库 / 独立仓库。
- **共享仓库**：仓库 URL + 分支（可选，默认 main）。
- **独立仓库**（每个工作区）：URL + 分支 + 仓库内子路径。
- **打开笔记时自动拉取**（勾选框，默认开启）。
- **提交作者名 / 邮箱**（当仓库本身没配置 git 身份时使用；否则以仓库自身的配置为准）。

## 7. 版本更新提示

插件加载时会检查 npm 上 `dsh-md-notes` 是否有新版本（检查结果缓存 10 分钟，失败静默跳过）。
有新版时会出现黄色「有新版本需要更新」tag：

- **侧边栏笔记入口**按钮尾部（hover 显示最新版本号）；
- **笔记管理器标题栏**设置按钮旁。

升级方式：`dsh plugin --profile web update dsh-md-notes`，然后重启 dsh web。

## 8. 小贴士

- **文件是你的**：笔记就是普通 `.md` 文件，随处可编辑；卸载插件也不会丢。
- **meta.json** 只是本地缓存：不入库，clone 后会重建。
- **本地删掉笔记后推送**，远端也会同步删除（镜像同步，需确认）。
- **只有 `.md` 文件参与同步**。你在远端仓库放的其它文件不会被拉进笔记目录。
- **语言**：所有界面文案跟随 dsh 的语言设置（中 / 英）。