# 随记使用指南

[返回首页](../README.md) · [English guide](GUIDE.en.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)

随记是 DSH 中由人管理的笔记与轻文档工作台：直接写段落、列表和待办，按需要允许 agent 一起维护。当前版本兼容 **DeepSeek Harness 0.2.0-rc.2 与 0.2.1-alpha.1**，采用 macOS、Windows 和 Linux 各自的按键习惯；Web 与原生 Desktop、各系统的实际验收范围见[验证记录](VALIDATION.md)。

## 界面与操作

### 入口

- 左侧导航「随记」打开完整工作台，无需先选会话。工作台会重新打开你上次看的笔记。
- 对话时，在官方右侧栏的新标签页里选择「随记」，在笔记列表与正文之间切换；不占用聊天输入框的按钮区。
- 在聊天输入框输入 `/jot` 按 Enter，或在斜杠菜单选择「打开随记」，会弹出一个列表。第一项「打开随记」已选中，再按一次 Enter 就在右侧栏打开；也可以选「新建笔记」，或输入关键词找到置顶和最近的笔记直接打开。选中后消费 `/jot` 指令片段，保留其他草稿内容和附件；按 Escape 关闭列表，`/jot` 留在输入框里。
- 窄栏右上角的「打开完整笔记页」会带着当前笔记和未保存的草稿一起切到工作台。

### 笔记列表

- 「最近」显示全部置顶笔记和最近修改的 5 条；「全部」按日期分组并连续滚动；「回收站」保存已删除的笔记。视图右侧显示当前列表的条数，如「6 条」。
- 搜索框匹配标题和正文，标题命中排在前面，结果里显示命中附近的正文。「最近」视图里搜索的也是全部笔记。焦点在随记里、不在输入框时，按 `/` 直接搜索。
- 没有结果时，如果其他文件夹或回收站里有匹配，会提示条数，并提供「在全部文件夹中搜索」或「在回收站中查看」，一键切换且保留搜索词。
- 「排序与选项」里可按修改时间、创建时间或标题排序（「最近」固定按修改时间），也可进入多选，批量移动或移到回收站；这里还有「导出全部笔记…」和「键盘快捷键」。
- 焦点在一条笔记上时，Shift+F10 或键盘上的菜单键打开与右键相同的菜单（置顶、移动、复制、导出、删除）。单独的 F10 留给浏览器。多选模式下没有这个菜单。
- 每条笔记显示时间、清单进度（如 `2/5`）、所在文件夹，以及最近一次由 AI 保存时的「AI 修改」标记。没有标题的笔记用正文第一行作为显示标题。
- 文件夹可选，由你自行创建和命名；还没有文件夹时，从「排序与选项」里新建。有文件夹后，列表顶部出现文件夹筛选和「文件夹操作」（新建、重命名、删除；删除文件夹会保留其中的笔记）。
- 工作台里可以拖动列表右侧边界调整宽度（双击恢复默认），或用右上角按钮隐藏列表、专注写作。标题、格式工具栏和正文靠左对齐，正文保留阅读限宽，空白留在右侧。

### 编辑

- 点「新建」后光标直接在标题里，按 Enter 进入正文。未经任何编辑的新建空笔记，离开时会自动删除；写过内容、置顶或改过文件夹后会保留，即使后来清空正文。
- 工具栏常驻粗体、斜体、下划线、链接和待办清单；「样式」里有正文、标题 1–3、无序／有序列表、引用、代码块、删除线、行内代码、分割线、清除格式、七种文字颜色和六种高亮，每一项右侧标着快捷键（窄栏里隐藏，悬停按钮仍可看到）。颜色在深色主题下会自动换成易读的色调，保存与导出仍是原色。标题和正文获得键盘焦点时显示强调色轮廓。
- 选中文字后点工具栏的链接，或按 Mod+K，填写文字和地址。已有链接时，光标放在链接里即可改地址、改文字、打开或去掉。浮层打开后可以直接输入，Escape 关闭。接受 http、https、mailto、tel，以及以 `#` 开头的地址（保留但不打开）；没写协议的主机名会补上 https。粘贴进正文的网址仍会自动变成链接。编辑时单击链接只移动光标；中键、按住 Command（macOS）或 Ctrl（其他系统）再单击，或在只读笔记里单击，才会打开，而且只打开一次；双击的第二下不会再打开。只读笔记里用 Tab 移到链接后按 Enter 同样打开一次。右键和 macOS 上的 Ctrl+单击弹出浏览器菜单，不会打开链接。已经保存在笔记里、又带有账号或口令的地址不会带上可点击的 href，单击和中键都不会打开。
- 在空行输入 `/` 打开插入菜单：正文、标题 1–3、待办清单、无序／有序列表、引用、代码块、表格、分割线和「图片或附件」。中文输入法下 `/` 键打出的 `、` 同样可以；继续输入可以筛选，支持中文、英文和拼音首字母（如 `/bt` 找到标题、`/db` 找到待办）。↑／↓ 选择，Enter 或 Tab 插入，Escape 关闭并保留已输入的字符。只有整行只有这个符号和筛选词、且光标在行尾时才会打开，句子里的 `/` 和 `、` 不受影响；表格里不打开。
- 也可以直接输入 `# `、`- `、`1. `、`[ ] `、`> `、`---`、`**粗体**` 等写法，自动转换为对应格式。
- 待办里按 Mod+Enter 勾选或取消当前项；在列表或待办里按 Alt+Shift+↑／↓ 把当前项上移或下移，嵌套项只在自己那一层移动。光标在核对清单里时，工具栏的「整理」把已勾选项移到这张清单底部，未完成和已完成各自保持原来的先后，可以撤销。已经排好、或没有已完成项时，按钮不可用。
- 「查找」在当前笔记里查找、跳转和替换；全部替换可一次撤销，回收站里的笔记只能查找。
- 右上角显示保存状态：自动保存，也可以点「未保存」立即保存或按 Mod+S；保存失败时显示「保存失败 · 重试」。

### 删除与回收站

- 「移到回收站」不再二次确认，底部提示里可以直接「撤销」；多选后批量移到回收站也一样，撤销会把这一批一起恢复。
- 回收站里的笔记可以恢复、复制为新笔记或导出；「永久删除」和「清空回收站」需要确认，且无法撤销。永久删除时，只被这些笔记使用的图片和附件也一并删除；其他笔记仍在引用的附件会保留。

### 摘录

窗口或右侧栏顶部的摘录按钮会带上当前选中的文字。可以新建笔记，也可以追加到某条笔记；当前打开的笔记排在最前并默认选中。右侧栏里会预填当前页面地址作为来源，工作台里不预填。

## 安装、升级与卸载

```sh
# 桌面客户端
dsh plugin --profile desktop add dsh-jot
# Web UI
dsh plugin --profile web add dsh-jot
```

安装或升级后重启对应 Host。官方 Desktop 可通过应用菜单「管理 dsh 命令…」启用其内置 CLI。Desktop 与 Web 使用独立 Profile；给 Web 安装不会自动给 Desktop 安装，配置为同一个数据目录时两者共用笔记。

DSH 0.2.1-alpha.3 Web 升级：先保存笔记。在运行中的插件管理器里，先移除随记，再安装 `dsh-jot@latest`；启用热重载时，对已安装的包再次安装会返回 `already-installed`，不会更新正在运行的代码。可替换的插件会直接生效；宿主提示重启时再重启。参见[官方升级说明](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-alpha.3/docs/upgrade-guide/v0.2.1-alpha.2/plugin-install-over-installed/guide.zh.md)。

使用 CLI 升级时，先停止对应的 Web Host，再移除并重新安装，完成后启动原来的 Web Profile：

```sh
dsh plugin --profile web remove dsh-jot
dsh plugin --profile web add dsh-jot@latest
```

已验收的官方 macOS Desktop 宿主为 DSH 0.2.0-rc.2，与 alpha.3 Web 分开。使用 Desktop 自带的 CLI 前先完全退出桌面应用，升级后重新打开：

```sh
dsh plugin --profile desktop add dsh-jot@latest
```

仅卸载时，选对应的 Profile：

```sh
dsh plugin --profile desktop remove dsh-jot
dsh plugin --profile web remove dsh-jot
```

卸载和重装保留独立存储的笔记及附件。若改过插件的 `directory` 设置，先记下该目录，重装后恢复该设置；不要删除笔记目录。

## 构建和本地开发

Node.js `^22.19.0 || >=24`，pnpm 11。

```sh
git clone https://github.com/Totoro-qaq/dsh-jot.git
cd dsh-jot
pnpm install --frozen-lockfile
pnpm check
pnpm pack:check
pnpm pack --pack-destination artifacts
dsh plugin --profile desktop add /absolute/path/to/dsh-jot/artifacts/dsh-jot-<版本>.tgz
```

`pnpm dev` 打开 `http://127.0.0.1:4178` 的本地预览，使用相同的数据层、HTTP 适配器和编辑组件；顶部可以切换工作台／侧栏、深色主题和英文界面。预览数据放在仓库 `.jot-dev/`，与真实 DSH 笔记分开。预览只用于界面调试，真实插件使用 DSH 的认证机制。

修改 `src/client/icons.tsx` 后运行 `pnpm icons`，同步随包发布的 `assets/icons/*.svg`；测试会检查两者一致。

## 快捷键

正文编辑以 macOS 的 Command、Windows／Linux 的 Ctrl 为主修饰键：

| 操作 | macOS | Windows／Linux |
| --- | --- | --- |
| 复制／剪切／粘贴／全选 | Command + C／X／V／A | Ctrl + C／X／V／A |
| 撤销／重做 | Command + Z／Shift + Command + Z | Ctrl + Z／Ctrl + Shift + Z；另支持 Ctrl + Y |
| 粗体／斜体／下划线 | Command + B／I／U | Ctrl + B／I／U |
| 添加或编辑链接 | Command + K | Ctrl + K |
| 当前笔记查找／保存 | Command + F／S | Ctrl + F／S |
| 正文／标题 1–3 | Option + Command + 0／1–3 | Ctrl + Alt + 0／1–3 |
| 无序列表／有序列表／待办清单 | Shift + Command + 8／7／9 | Ctrl + Shift + 8／7／9 |
| 引用／代码块 | Shift + Command + B／Option + Command + C | Ctrl + Shift + B／Ctrl + Alt + C |
| 删除线／行内代码／高亮 | Shift + Command + S／Command + E／Shift + Command + H | Ctrl + Shift + S／Ctrl + E／Ctrl + Shift + H |
| 勾选或取消当前待办 | Command + Return | Ctrl + Enter |
| 上移／下移当前列表项 | Option + Shift + ↑／↓ | Alt + Shift + ↑／↓ |
| 已完成项移到底部 | 工具栏「整理」 | 同左 |
| 打开当前笔记菜单 | Shift + F10／菜单键 | 同左 |
| 调整当前列宽 | 在表格中 Option + Shift + Command + ←／→ | 在表格中 Ctrl + Alt + Shift + ←／→ |
| 搜索笔记库 | `/` | `/` |
| 显示全部快捷键 | `?` | `?` |

在随记里、焦点不在输入框时按 `?`，或在「排序与选项」里选「键盘快捷键」，可以随时查看这张表。段落和文字格式的快捷键是编辑器（Tiptap）的默认按键，H4–H6 不再响应快捷键，旧笔记和 AI 写入的四到六级标题仍正常显示。Mod+Enter 只在待办里勾选；在其他段落中保留原来的换行行为。这些按键在真实 Desktop 中可能先被宿主或系统处理，实际结果以[验证记录](VALIDATION.md)为准。

剪贴板操作保留系统与编辑器的原生处理，格式和撤销／重做由编辑器按焦点处理。工作台选中笔记时，Mod+F／S 查找或保存当前笔记；菜单和对话框保留自己的按键处理。列表使用方向键、Home、End 和 Enter／Space；选择模式下 Enter／Space 切换勾选。菜单和对话框支持 Escape 与键盘焦点管理；搜索框里按 Escape 清空搜索。

随记在 DSH 的键盘快捷键设置中注册了三条命令：「随记：打开随记」「随记：新建笔记」「随记：摘录选中的文字」。在设置中搜索「随记」或 `jot` 即可找到。它们**默认不绑定任何按键**，可以按自己的习惯设置；测试中使用的组合键不是产品默认值。对话可见时命令在右侧栏执行，否则打开完整工作台。摘录会先保留选中的文字；对话框打开时，命令不会在背景新建笔记。

macOS／Windows Desktop 会先处理宿主绑定。正文聚焦时，随记使用 DSH 公开的 `shortcuts.registerFixed` 临时保留 Mod+B；macOS 的撤销／重做另通过公开 `shortcuts.register` 路由到正文历史，避开 Electron Edit 菜单的键盘拦截。失焦或卸载清理这些绑定，不修改用户设置。Web／Linux 保留本地编辑器优先处理。新建笔记没有占用 DSH 新会话的 Mod+N。

## 表格操作

点击单元格后，表格上方的「⋯」管理当前列，左侧的「⋮」管理当前行；可以在前后插入，也可以删除所选行列。右侧和底部的「＋」分别追加最后一列和最后一行，位置不跟随文字光标。右上角的表格图标打开「表格选项」。

拖动列与列之间的边界调整宽度，保存后再次打开会保留；拖动尚未结束时按 Escape，取消这次调整并恢复原宽度。光标在单元格里时，Ctrl+Alt+Shift+←／→（macOS 上是 Option+Shift+Command+←／→）每次把当前列加减 16 像素。Alt+←／→ 仍留给按词移动和浏览器后退，Option+Shift+←／→ 仍留给按词选择。已经到最小或最大宽度时，这个组合键仍由表格处理，不会漏给浏览器。表格里的 Tab 仍用来切换单元格，所以列宽不靠 Tab 过去再按方向键。列宽控制本身获得焦点时，←／→ 同样有效。每一次按键单独撤销，新的宽度会读给屏幕阅读器。行列操作和已完成的列宽调整可以连续撤销／重做，自动保存不会清空这段历史。「表格选项 → 自动适应宽度」清除整张表的手动列宽。行高随内容自动撑开；多列表格在自己的区域内横向滚动，不撑宽整个侧栏。当前不提供整体缩放或行高拖动。

表格最多 200 行、50 列，还受到笔记总节点数与 1 MiB 容量限制。新增操作在超过容量前拒绝；拖动列宽若因新增元数据超限，会还原原列宽并保留正文输入。回收站中的笔记不能调整表格。持久化兼容合并单元格，但当前没有合并／拆分按钮。

## 附件与导出

### 官方预览与应用打开

点击附件优先交给 DSH 官方文件预览，使用已选中的会话。在完整随记工作台点击会切回该会话并打开预览侧栏；正文草稿继续保留。Word／PPT 由官方主机服务转换为 PDF；Excel、文本、图片和 PDF 使用对应的官方查看器，可用格式和大小限制以主机配置为准。此操作不创建新会话，也不把附件复制进工作项目。

没有选中的会话或官方查看器不可用时，继续使用附件弹窗和下载功能。主机具备桌面打开能力时，弹窗另提供「用默认应用打开」；macOS、Windows 和带桌面环境的 Linux 使用各自的文件关联。Web 远程访问时打开的是运行 DSH 的主机，不是浏览器所在电脑；无桌面环境的服务器保留下载入口。外部应用打开的是经校验的附件副本，修改不会自动同步到笔记。

### 附件限制与清理

附件默认单文件最多 **20 MiB**，同一数据目录累计 **500 MiB／1,000 个附件**；界面每次最多添加 20 个文件。配置 `attachmentMaxBytes`、`attachmentMaxTotalBytes` 可调整字节额度。附件存入受管理的本地文件，正文只保存附件 ID，不保存任意文件路径。

| 类型 | 未使用官方查看器时如何查看 |
| --- | --- |
| PNG、JPEG、GIF、WebP | 正文图片及预览弹窗 |
| PDF | 预览弹窗，依赖 DSH／浏览器的 PDF 查看器 |
| Word、Excel、PPT、Markdown、TXT、SVG、音视频等 | 文件卡片、下载，以及主机支持时的默认应用打开 |

上传没有扩展名白名单；能保存不代表能解析或预览。图片按实际字节识别，边长最多 10,000 像素、总像素最多 4,000 万。搜索索引标题和正文中的文件名／说明，不解析 PDF 正文或做 OCR。

附件在永久删除笔记或清空回收站时清理：只被被删笔记引用的附件随之删除，回收站或其他笔记仍在引用的附件保留。仅从正文里删掉附件卡片、或只把笔记移到回收站，不会立即删除附件文件。

### 导出

| 格式 | 导出内容 |
| --- | --- |
| TXT | 标题、正文、列表／待办状态、表格文字和附件名称说明 |
| Markdown | 格式、列表／待办及表格；有附件时返回 ZIP，包含 `note.md` 与 `assets/`，链接不依赖 DSH 登录 |
| PDF | 中文字体嵌入、常用样式、矢量待办框、分页表格、页码和 PNG／JPEG 图片 |
| Word（DOCX） | 文字格式、编号列表、待办状态、表格及 PNG／JPEG 图片 |

单篇导出使用当前草稿，不要求先保存。每次最多引用 100 个不同附件，附件原始字节总量和最终导出文件均不得超过 50 MiB。PDF 超过 8 列的表格改为带行／列标识的文字；合并单元格内容保留，但合并边框不完全还原。PDF／DOCX 对 GIF、WebP 和普通文件保留名称说明。PDF 内嵌 `assets/fonts/NotoSansSC-*.otf`，按 [SIL Open Font License 1.1](../assets/fonts/OFL.txt) 分发；DOCX 字体显示由阅读器决定。导出不声明与编辑器逐像素相同。

### 导出多篇笔记

「排序与选项 → 导出全部笔记…」把笔记打包成一个 ZIP；选了某个文件夹或「未分类」时，菜单变为「导出这些笔记…」，只导出该文件夹范围内的笔记。搜索词不限制导出范围，回收站里的笔记不会导出。对话框里可选：

| 格式 | 适合 |
| --- | --- |
| Word（.docx，默认） | Word、WPS 和 Pages 都能打开，PNG／JPEG 图片直接嵌在文档里 |
| PDF | 排版固定，适合阅读、打印和分享 |
| Markdown | 纯文本，方便导入 Obsidian 等笔记软件，图片以相对链接指向附件文件夹 |

ZIP 里每篇笔记一个文件，按文件夹分目录，未分类的笔记放在根目录；同名笔记自动加上「(2)」这样的序号，没有标题的笔记用正文第一行命名。笔记用到的附件按原文件放在 `附件/`（英文界面为 `attachments/`）里，同一个附件只放一份，所以 Word／PDF 无法嵌入的 GIF、WebP 和普通文件也不会丢。导出前会先保存正在编辑的笔记。ZIP 根目录还有一份 `jot-library.json`，记录每篇笔记的完整内容（包括颜色和表格列宽）、文件夹、置顶和时间，用「导入笔记」可以原样恢复；Word 和 PDF 格式的导出也一样。

一次最多导出 2,000 篇笔记；PDF 每篇都要嵌入中文字体，一次最多 500 篇。附件总量、生成条目的累计字节预算（含 ZIP 开销）与最终文件各限制 200 MiB。超过时请按文件夹分批导出，或改用 Word。

### 导入笔记

「排序与选项 → 导入笔记…」可以选择文件，也可以选择整个文件夹；笔记库还是空的时，列表里也有「导入已有的笔记…」。

- **随记导出的 ZIP**：按其中的 `jot-library.json` 原样恢复，内容、文件夹、置顶、时间和附件都不变，Word、PDF、Markdown 三种格式的导出都可以。
- **Markdown（.md、.markdown）和纯文本（.txt）**：每个文件一篇笔记。Markdown 按[和 agent 相同的写法](#agent-协作)转换，还认得 Obsidian 的 `[[链接]]`、`![[嵌入]]` 和 `==高亮==`。文件开头的 YAML 属性会去掉；开头的一级标题（或属性里的 `title`）作为笔记标题，否则用文件名。纯文本每行一段，不做转换。
- 选择文件夹时，所选文件夹本身不会成为随记文件夹，它下面的子文件夹会；多层子文件夹合成一个名称，如「工作 / 周会」。和已有文件夹同名时放进那个文件夹。
- 笔记用到的图片和附件按笔记所在位置的相对路径、所选文件夹的根目录或文件名查找，一起存入；选中了但没有被笔记用到的文件不会上传。找不到的图片保留原来的写法，导入后的提示会说明数量。
- 和已有笔记标题、内容完全相同的笔记会跳过，同样的附件也不会存第二份，所以同一个备份导入两次不会多出笔记。
- 隐藏文件和文件夹（如 `.obsidian`、`.git`）会被忽略。文件夹内的 ZIP 按普通附件处理，仅携带笔记引用的 ZIP，不展开其中内容；单独选择一个 ZIP 时才按导入压缩包处理。

一次最多导入 2,000 篇笔记，上传内容最多 200 MiB；单个 Markdown 文件最多 4 MiB，单个附件仍受 20 MiB 上限。能读取的笔记在一次保存里写入；写入失败时一篇都不会留下，已经上传的附件也会删除。过大或无法转换的文件会跳过，并在提示里说明数量。第三方工具打包的 ZIP 如果文件名不是 UTF-8 编码（例如中文 Windows 自带的压缩），文件名可能乱码，这时请直接选择文件夹导入。

## Agent 协作

「允许 AI 协作」默认关闭，由你在列表底部打开或关闭。开启后 agent 可使用：

| 工具 | 用途 |
| --- | --- |
| `jot_list` | 搜索笔记，返回有界的摘要列表和文件夹名称 |
| `jot_read` | 以 Markdown 读取一篇笔记，返回编号的待办项、当前版本，以及 Markdown 表达不了的格式（`notInMarkdown`） |
| `jot_create` | 新建笔记；正文支持 Markdown |
| `jot_update` | 基于当前版本查找替换文字（改字时推荐）、追加内容、改标题、移动文件夹或整篇替换 |
| `jot_set_task` | 按编号勾选或取消一个待办项 |
| `jot_delete` | 将笔记移到回收站 |

- 文字默认按 Markdown 转换：`#` 标题、`-`／`1.` 列表（缩进两个空格表示嵌套）、`- [ ]`／`[x]` 待办、`>` 引用、```` ``` ```` 代码、`---` 分割线、`| 表格 |`，以及 `**粗体**`、`*斜体*`、`~~删除线~~`、`==高亮==`、`` `代码` `` 和 `[链接](https://…)`。HTML 只认 `<u>`、`<mark>`、带颜色的 `<span>`、`<strong>`、`<em>`、`<s>`、`<code>`、`<a href>` 和 `<br>`，用来表示下划线、颜色和换行，其他标签一律作为普通文字。图片和附件写成单独一行的 `![说明](attachment:编号)` 或 `[说明](attachment:编号)`，编号必须是已存在的附件。传 `format: "plain"` 时每行都是普通段落。
- `jot_read` 给 agent 的就是这种 Markdown，agent 能看到并保留标题、列表、粗体、链接、颜色和附件。改几个字时用 `edits`：每一项 `{ find, replace }` 在一个段落内精确匹配可见文字（不含 `**`、`#` 这类标记），替换后的文字沿用原来的格式；同一段文字出现多次时要多带几个字，或设 `all: true` 全部替换。任何一项匹配不到，整次修改都不生效。
- 追加的列表或待办紧接在笔记末尾的同类列表后面时会合并进去，「加一条待办」不会另起一张清单。
- 整篇替换（`text`）只在笔记转成 Markdown 再转回来不丢东西时才执行。表格列宽、合并单元格这类 Markdown 写不出来的格式会列在 `jot_read` 的 `notInMarkdown` 里，这时整篇替换会被拒绝；只有在你同意后，agent 才能用 `allowFormattingLoss: true` 重试。用 `format: "plain"` 整篇替换有格式的笔记同样需要你同意。
- 修改、勾选和删除都要求精确的 `revision`，避免覆盖其他编辑；每次调用都检查最新开关状态，agent 无法通过工具开启自己的权限。
- AI 保存的版本会在列表和正文工具栏标出「AI 修改」，你再次编辑后标记消失。这一归属记录存放在单独的 `jot.activity.json` 中，旧版本插件读取笔记不受影响。
- 对保留了修改前版本的已有笔记，点正文工具栏的「AI 修改」，或在「更多笔记操作」里选「撤销 AI 的修改…」，确认后笔记回到 AI 修改之前的样子，成为一个新的由你保存的版本。AI 连续做的几次修改算一轮，会一起撤销；中间只要你编辑过，就只撤销最近这一轮。撤销只能由你操作，关闭 AI 协作后也可以撤销。没有修改前版本时（例如 AI 新建笔记）只显示标记；目前不提供独立的 AI 修改历史或重做 AI 修改，常规备份仍可能保留上一次状态。
- AI 修改前的版本单独存放在 `jot.agent-undo/`，每篇笔记最多一份；你编辑、撤销或永久删除笔记后清理。
- 开启 AI 协作后，没有「AI 修改」标记的笔记会在正文工具栏显示一个小图标，提醒 AI 在你要求时可以读写笔记。

开关控制的是随记提供的工具，不是系统级文件访问权限。关闭时随记的工具不会注册到 DSH，也就不会随模型请求发送；打开后立即可用。Desktop 和 Web 共用数据目录时，在一边切换开关，另一边最多约 10 秒后跟上。笔记不会自动注入每轮模型请求；模型通过明确的读取或搜索获取内容。

## 数据与冲突

默认数据目录为 `$DSH_HOME/jot`，未设置 `DSH_HOME` 时为 `~/.dsh/jot`。可以在插件配置中设置 `directory`。同一数据目录由人和 agent 共用，文件锁保护跨进程修改。

- `jot.json`：笔记、文件夹和开关状态。
- `jot.json.bak`：上一次保存前的有效状态。
- `jot.activity.json`：AI 修改标记，可选；损坏或缺失时只会不显示标记。
- `jot.agent-undo/`：AI 修改前的版本，用于撤销 AI 的修改，可选；损坏或缺失时只是无法撤销。
- `.jot.lock`：写入／读取协调锁，记录 owner PID。
- `attachments/`：受管理的附件二进制、`manifest.json` 和附件协调锁。

单篇笔记最多 1 MiB、正文最多 200,000 个字符长度单位；整库最多 32 MiB。界面每 3 秒检查一次更新：没有变化时服务端只核对文件，不读取笔记内容，回复「未修改」；有变化时只返回改动过的笔记。窗口在后台时暂停检查。

损坏或未知版本的数据会明确拒绝读写，保留原文件，不静默覆盖为空库。异常退出若留下锁，应先确认锁中的进程已经结束，再移走该锁；不要以清空笔记文件解决锁冲突。文件替换是原子的；本版本不声明断电时最近一次提交必然保留。

另一个面板或 agent 改过正在编辑的笔记时：如果你在编辑已有段落，而别处只是在末尾追加内容，或者只改了你没动的标题、文件夹或置顶，可安全合并的改动会并进草稿，光标不动，撤销也不会撤掉别处的内容。另一面板已保存的同一份追加只保留一次；在它后面继续新增段落也不会重复拼接。两边追加有分歧或无法确定是否重叠时，会保留冲突。其他情况下界面提示「这条笔记有新版本，你的草稿已保留」，可以载入最新版本或把草稿另存为新笔记。

## 验证与边界

`pnpm check` 覆盖类型检查、持久化／跨进程并发／版本冲突／agent 门控／HTTP 认证边界、Markdown 转换、永久删除与附件清理、客户端草稿保护和图标资源一致性，并生成 Host 与 Client。`pnpm pack:check` 检查模块工厂、包身份和共享 React 导入。真实宿主、界面及打包验证见[验证记录](VALIDATION.md)；共享 Web 插件接口不能替代 Desktop 原生壳的独立实测。

本版不包含云同步、实时多人编辑、修改历史、自由绘图／批注或自动总结后台任务。批量管理逐条检查版本并执行；失败前已完成的操作会保留，不是整批事务。

## License

插件：MIT。客户端打包的第三方代码：[THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md)。随包字体：[SIL Open Font License 1.1](../assets/fonts/OFL.txt)。

## 社区收录材料

OMDSH 投稿信息与权限说明见[作者投稿声明](community/omdsh-intake.zh-CN.md)。材料是否已提交、平台是否完成审核，应以目录的实际状态为准；这份声明不代表收录通过。