# 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 功能入口、
  新建按钮；启用 Git 后，工作区组内还有一张 **Git 同步卡片**（状态「已同步」/
  「未推送 N 处」+ 更新/推送按钮，见 [§5](#5-git-同步可选)）。
- **右栏 — 笔记内容**，有「预览 / 编辑」两个 Tab 和「保存」按钮。**点击已有笔记默认打开预览**；
  新建笔记则直接进入编辑模式。
- **底部 — 全局 Git 状态行**：跨工作区汇总「未推送 N 处 · X 个工作区 · Y 个待同步」。

### 新建笔记

点工作区行的「+」，弹出「新建笔记」弹窗：

- **标题**：默认「未命名笔记 <日期>」，可改——它是笔记的显示标题（正文首个 `# 标题`），之后随时可改。
- **文件名**（可选）：留空则按标题自动生成；填写则按你写的文件名创建（非法字符转 `-`、强制 `.md` 后缀）。**创建后文件名固定**，不再随标题变化。

> ⚠️ **文件名不要重名**：文件名是笔记的**唯一标识**（互链、`@` 引用、Git 同步都按文件名定位）。
> 同一工作区内重名会导致互链/引用跳错、Git 同步互相覆盖等异常——**强烈不建议重名**。
> 弹窗会实时显示「将创建：<文件名>」；若与已有笔记重名，会红字提示并**禁用创建**，请更换标题或文件名。

创建成功后**直接进入编辑模式**。

### 编辑与预览

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

### 搜索笔记

管理器顶部栏的搜索框可**跨全部工作区**搜索——标题与正文、大小写不敏感；多个关键词用
空格分隔（全部命中才算匹配）。

- 输入时左栏切换为分组结果（工作区 → 笔记 → 命中行，关键词高亮显示）；编辑器与
  Git 区不受影响。清空（或按 `Esc`）即恢复原列表。
- 笔记行显示总命中数；「标题命中」徽标表示关键词命中了标题。
- 点**命中行**：笔记以编辑态打开并定位到该行——命中行滚到视口中部、关键词处于
  选中态；点笔记行则跳到它的第一个命中。正在写入的笔记退回预览打开。

### 笔记互链

在笔记正文里写 `[[笔记名]]`（或反引号 `` `笔记名` ``）引用另一篇笔记，预览时它会变成可点链接，
点击即跳转到目标笔记（支持跨工作区）。按标题或文件名匹配（大小写不敏感）：

- 只写笔记名时，同名跨工作区**优先当前工作区**；无重名仍可跨区。
- 要链接**另一个工作区**的重名笔记，写 `[[工作区名/笔记名]]`（工作区名或 id 均可）。
- 同一工作区内**标题**重名时，hover 会提示「N 篇同名标题，建议用文件名区分」——此时用
  `[[文件名]]` 精确链接（文件名在工作区内唯一）。
- 引用的笔记不存在时保持普通文本。

### 删除笔记

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

### 笔记正在写入时

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

## 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. **插件后端（运行 dsh 的本地进程）把笔记内容注入模型上下文**——对话里会出现一条可折叠的「上下文注入」行
   （来源标 `md-notes`），展开可以看到注入的笔记内容。模型**直接拿到内容**，不依赖它自己调用
   `read` 工具去读文件。

### 4.4 常见问题

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

## 5. Git 同步（可选）

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

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

**工作区行的 git 图标**：

- **只有配置了 git 仓库的工作区才显示**；没配仓库的工作区不显示。
- 点 git 图标展开 / 收起该工作区的 **Git 同步卡片**。
- 图标下方有两个小圆点，**只在有需要处理的事情时才出现**：
  - **左下黄点** = 远端有更新（点「更新」拉取）；
  - **右下红点** = 本地有未推送的改动（点「推送」）。
- 鼠标悬停在 git 图标上会显示两行提示：远端更新个数、本地未推送个数。

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

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

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

> **推荐用共享仓库**：一个 URL 管所有工作区，每个工作区自动占一个子目录，配置最省心。
> 想按项目分开、或用不同仓库分别授权时，再用**独立仓库**。

### 5.2 推送笔记

1. 打开笔记管理器，在工作区 **Git 同步卡片**上点「推送」——按钮行切换成提交信息行
   （输入框 + 确认 / 取消）。
2. 填提交信息（默认「笔记更新 <时间>」），点确认提交并推送；点取消则退回按钮行。
3. 首次推送会自动 clone 仓库（凭据交给 git 自己处理——HTTPS 凭据助手或你的 SSH key）。

**推送前**，插件会把远端与**上次同步的状态**做三向比较（base / local / remote）。只有
**远端自上次同步后变了**、且你的本地又与它不同（或本地已删、远端还在）时才弹确认：

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

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

你本地单方面改过、远端没动的笔记**不算冲突**，会直接正常推送。

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

点工作区 **Git 同步卡片**上的「更新」把远端版本拉下来：

- 远端有**你本地没有的新笔记** → 拉下来，左侧列表自动刷新。
- 某篇笔记**远端自上次同步后变了**、且与你本地编辑**不一致** → 插件保留你的本地版本，并弹窗询问：

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

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

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

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

### 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` 文件，随处可编辑；卸载插件也不会丢。
- **文件名在同工作区内唯一**：文件名是笔记身份，重名会导致互链/引用/Git 同步异常，不建议重名。
- **meta.json** 只是本地缓存：不入库，clone 后会重建。
- **本地删掉笔记后推送**，远端也会同步删除（镜像同步，需确认）。
- **只有 `.md` 文件参与同步**。你在远端仓库放的其它文件不会被拉进笔记目录。
- **语言**：所有界面文案跟随 dsh 的语言设置（中 / 英）。