dsh-hand-note · 随手笔记

给 DeepSeek Harness（dsh）用的本地随手笔记插件。 每篇笔记就是一个 Markdown 文件，数据完全在你本机，不依赖任何云服务——想到什么记什么，聊完什么存什么。

🌱 本项目由 fangqiing/dsh-knowledge-lite（v0.1.6，MIT）深度改造而来：全新卡片式界面、自定义标签管理、平铺速览列表，并保留其全部核心能力（全文搜索、Markdown 预览、自动保存、附件抽取、对话回写）。感谢原作者的开源工作。

✨ 它解决什么问题

聊天里的知识点留不住？ 每轮对话结束后一键「存入随手笔记」，AI 自动抽取可复用的命令、配置、结论与坑，勾选后写入
笔记散落各处找不回？ 全文搜索 + 标签筛选，毫秒级命中
不想把笔记交给第三方云？ 每篇一个 .md，放在你指定的本地文件夹，用 VS Code / Obsidian / 记事本都能直接改，插件自动识别
文档里的内容没法问 AI？ 拖入 Office 文件自动零依赖抽取正文，笔记立即可搜索、可被 AI 引用

🎨 界面一览

卡片式双栏布局：左侧速览列表 + 右侧编辑器，胶囊搜索框、标签 chip 条、分段式「编辑 / 预览」切换
平铺速览列表：无目录层级干扰，所有笔记按更新时间排列，相对时间（「3 小时前」）一目了然，悬停查看完整时间戳
舒适阅读排版：标题、列表符号、引用块色条、圆角代码块、斑马纹表格全部重新调校，明暗主题自适应；状态栏可调字号（小/中/大）与行宽（全宽/适中），长文阅读更舒服
沉浸编辑：无边框大标题、无干扰正文区、停笔约 1 秒自动落盘，Ctrl+S 随时手动保存
标签配色（0.3.1 新增）：同名标签固定同一颜色（色点 + 轻着色底），三处展示位置一致，扫一眼就能定位
紧凑模式（0.3.1 新增）：头部一键切换「紧凑/舒适」，紧凑下列表只显示标题+时间，一屏翻倍

📌 功能

笔记管理

本地纯文本存储：每篇一个 .md（YAML front matter 存元数据），外部编辑器改动即时可见
全文搜索 + 标签筛选：标题 / 正文 / 标签联合检索，标签 chip 单击筛选、再击取消
批量删除：点右上「批量删除」进入多选模式，卡片勾选、支持全选，一键移入回收站
回收站（0.2.2 新增）：删除不再直接销毁——笔记与附件原样移入库根目录 .trash/，保留 30 天；回收站视图内可单条恢复（回到删除前的目录）或彻底删除，也可一键清空，超期自动清理
自动保存：停止输入约 1 秒自动落盘；切换笔记、返回聊天、关闭窗口前自动冲刷；保存失败静默重试，Ctrl+S 保留为手动立即保存
Markdown 渲染预览：标题、粗体/斜体/删除线、行内代码、围栏代码块、链接与裸链、多级嵌套列表、任务列表 - [ ]、引用块、表格（含对齐）、分隔线；直接产出 React 元素、不解析 HTML，无注入风险

标签系统（0.2.0 新增）

提前自定义标签：标签条末尾「＋标签」输入即建，支持逗号批量（面试题, 算法, 待整理）；没人使用的标签也会常驻标签栏，方便先把体系搭好
一处删除、全局生效：悬停标签 chip 点 ×，确认后从标签栏与所有携带它的笔记中一并移除
持久化登记表：自定义标签存于库根目录 tags.json，与笔记数据同进退；迁移库位置时自动带走

附件与导入

拖入即导入：文本类（.txt .md .py .json .csv…）直接进正文；.docx .xlsx .pptx 原件存入 files/ 并零依赖抽取文本（自解 ZIP + XML，无第三方库）写进正文，可搜索、可被 AI 引用；其他（PDF / 图片 / 压缩包）原样保存，双击交系统程序打开
右键附件：用系统默认程序打开，或在资源管理器中定位
删除笔记连带清理附件，不留垃圾文件

与对话打通

对话回写（writeback）：带附件/文档的对话轮次末尾出现「存入随手笔记」按钮，AI 抽取候选知识点 → 勾选确认 → 写入；纯文字回答不触发，绝不打扰
侧栏入口：左侧栏「随手笔记」一键进入全屏笔记面板，「‹ 聊天」随时返回

📦 安装

方式一：dsh 插件市场（推荐）

收录后打开 dsh 的 设置 → 插件（插件市场），搜索 dsh-hand-note 或「随手笔记」一键安装。

方式二：dsh CLI

dsh plugin --profile <你的profile> add dsh-hand-note

方式三：从 GitHub 直接装

dsh plugin --profile <你的profile> add github:amd47802574/dsh-hand-note

方式四：手动 / 开发模式（Windows）

git clone https://github.com/amd47802574/dsh-hand-note.git
cd dsh-hand-note
# 把本目录链接（或复制）进 dsh profile 的 node_modules，并在 profile
# package.json 的 dependencies 与 dsh.profile.bundles 中登记 dsh-hand-note
# 安装/卸载前需彻底退出 dsh，否则文件被占用（EPERM）

从旧版 dsh-knowledge-lite 迁移：默认库已改为 ~/dsh随手笔记；首次启动后在底部状态栏「库位置」选回 E:/dsh-kb（或任意位置），笔记、附件与标签会自动迁移过去。

🚀 快速上手

打开左侧栏「随手笔记」，点右上 ＋新建笔记
填标题、写正文（Markdown），停笔即自动保存
想分类？在标签栏点 ＋标签 先建体系；编辑器里点 ＋标签 按钮从列表点选，或输入新名字回车直接创建并挂上
带文档聊完后，点对话轮次末尾的 存入随手笔记 沉淀知识点
想换库位置？点底部状态栏右侧的「库位置」文件夹胶囊，弹出系统文件夹选择窗口，选完自动迁移

⌨️ 快捷键

快捷键	作用
`Ctrl+S`	手动立即保存
`Esc`	关闭右键菜单 / 退出回收站视图
右键笔记	打开 / 复制 / 剪切 / 重命名 / 删除（移入回收站）
右键标签 chip 的 ×	删除该标签（全局）

⚙️ 配置

项	默认值	说明
笔记根目录	`~/dsh随手笔记`	所有笔记与附件的存储位置，可在底部状态栏随时更改（自动迁移）。设了 `DSH_HOME` 环境变量时为 `$DSH_HOME/dsh随手笔记`
配置文件	`~/dsh-hand-note.json`	记住根目录设置，独立于插件目录与笔记库，profile 重置不丢失
自定义标签	`<根目录>/tags.json`	提前注册的标签登记表，可手工编辑

目录结构：

~/dsh随手笔记/
├── notes/          # 每篇笔记一个 .md（文件名即笔记 id）
│   └── 子目录/     # 磁盘文件夹即分类（可选）
├── files/          # 附件原文件（<id>--<原名>）
├── .trash/         # 回收站：删除的笔记保留 30 天（0.2.2 新增）
└── tags.json       # 自定义标签登记表

🏗️ 架构

文件	职责
`lib/store.js`	笔记存储：扫描（mtime 缓存）、增删改查、标签登记表、批量删标签、回收站（移入/恢复/彻底删除/30 天清理）
`lib/index.js`	宿主（Node）侧入口：webServer 路由 + 令牌鉴权 + RPC 分发表
`lib/client.js`	浏览器半侧 UI：面板、列表、编辑器、Markdown 渲染、自动保存
`lib/attachments.js`	Office 文档零依赖文本抽取（ZIP + XML 手解，无第三方库）
`lib/writeback.js`	对话回写：定位会话轮次、调用 LLM 抽取候选
`lib/writeback-prompts.js`	抽取提示词
`lib/config.js`	根目录配置读写与库迁移

安全设计：浏览器→宿主的 RPC 走 per-start 随机令牌（注入鉴权页）+ 同源/环回回退校验，常量时间比较；Markdown 渲染零 innerHTML，笔记内容无法向 shell 注入标记。

❓ FAQ

Q：和原版 dsh-knowledge-lite 什么关系？ A：由它 fork 并深度改造：界面全部重做、新增自定义标签管理（提前建标签 / 全局删标签）、列表改平铺速览；数据格式与默认库位置完全兼容。

Q：同时装两个插件会冲突吗？ A：会看到两个入口、两份相同的库（默认同根目录）。建议二选一。

Q：默认库在哪里？ A：用户主目录下的 ~/dsh随手笔记（Windows 即 C:\Users\<用户名>\dsh随手笔记；设了 DSH_HOME 则在其下），任何机器开箱即用、不依赖某个盘符。想换位置点底部状态栏的「库位置」即可；改 lib/config.js 的 DEFAULT_ROOT 可换默认值。

Q：外部编辑器改了 .md 会丢吗？ A：存储层按 mtime 缓存，外部改动会被识别并展示；插件写入采用临时文件 + 原子重命名，不会写出半截文件。

Q：删除笔记会丢吗？ A：不会立即丢。删除会把 .md 移到库根目录的 .trash/ 里，附件原样保留，30 天内在「回收站」视图里随时恢复（回到删除前的目录）；彻底删除或超期才真正清掉文件与附件。

Q：删除标签会动我的笔记吗？ A：只从笔记的 front matter 里移除该标签字段，正文与其他标签原样保留；删除即时生效并在状态栏显示影响篇数，删错了重新挂上即可。

🧭 兼容性

宿主：DeepSeek Harness 0.2.0-rc.2（peerDependencies 声明）
平台：Windows / macOS / Linux 均可用（默认库在用户主目录，无盘符依赖）
Node：^22.19.0 || >=24.0.0

📝 更新日志

0.3.3

修复：重启 dsh 后首次打开随手笔记，顶部标签栏一直不渲染——reloadTags 拿到数据后从未 emit，界面不知道要重绘，直到下一次任意交互才「突然出现」。现在标签/目录加载完成即刷新界面，首屏三路并行加载（不再串行等列表），并在启动竞态失败时自动重试一次

0.3.2

修复：插件更新/重载后库目录被重置——桌面壳在正常启动与更新后重载两个场景下对 DSH_HOME 的解析不一致，配置文件被读去不同位置。现在配置读取走多路径回退链（DSH_HOME 下 → 用户主目录 → 旧版 E:\dsh-tools 位置），写入时镜像到全部已知位置，任何环境下启动都能找回你设置的库位置
修复：右键菜单输入框（新建标签/重命名/目录改名）超出白色底板边界——改用 flex stretch 布局，聚焦光圈不再溢出；新建标签占位文案精简为「逗号可批量添加」

0.3.1

标签配色：同名标签永远同一色相（按标签名哈希到 11 个预设色），标签栏、卡片、编辑器三处统一带色点，视觉锚点一眼可辨；选中筛选时回退主题色
列表密度切换：头部「紧凑/舒适」按钮，紧凑模式只显示标题+时间，一屏容量翻倍，偏好本机记忆
空状态引导：库为空时不再是一屏空白，改为三张可点击引导卡——新建笔记 / 拖入文件（附格式说明）/ 回聊天存对话知识点
正文排版设置：状态栏新增「字号小/中/大」与「行宽全宽/适中」两个胶囊，行宽适中时限约 45 字/行居中排版，长文更易读；偏好本机记忆
主题融合：accent 色改为 --accent → --primary → 紫色兜底 的回退链，并清理掉 5 处写死的 rgba(109,94,242,…) 阴影/边框，换 dsh 主题后插件界面自动跟随

0.3.0

默认根目录可移植：统一改为用户主目录下的 ~/dsh随手笔记（设了 DSH_HOME 则在 $DSH_HOME 下），不再依赖 E 盘，任何平台开箱即用；老用户在底部状态栏「库位置」选回旧库即可自动迁移
配置文件移至 ~/dsh-hand-note.json（DSH_HOME 下，独立于笔记库）
修复：无 E 盘的机器上「更改库位置」必然失败——旧逻辑先创建 E:/dsh-tools 再写配置，创建抛错导致改根目录永远走不到；macOS/Linux 上也不再误建名为 E: 的文件夹
诊断日志改写到用户主目录 dsh-hand-note.log，不再固定写 E 盘、不再随笔记库位置漂移，且不再把完整 config 写进日志

0.2.2

新增回收站：单篇删除与批量删除一律先移入库根目录 .trash/（front matter 记录原目录），保留 30 天
回收站视图：右上「回收站」按钮进入，可单条恢复（回到删除前的目录，原 id 被占用时自动换新 id）、单条彻底删除、一键清空；Esc 退出
附件随恢复一起回来：移入回收站不再删除 files/ 里的附件，彻底删除/清空/超期清理时才一并删除
修复：库迁移此前只复制 notes/ 顶层且不带走附件与回收站，现在递归复制 notes/ 子目录，并迁移 files/ 与 .trash/
修复：配置文件读取因缺少 readFileSync 导入而始终回退默认路径，E:/dsh-tools/dsh-hand-note.json 现在真正生效

0.2.1

新增批量删除笔记：多选勾选、全选、二次确认
保存按钮移至编辑器右上角（与「编辑 / 预览」同行），取消底部操作栏，编辑区更高；自动保存状态同步显示在顶部
编辑器标签输入框改为「＋标签」按钮：从标签列表点选添加、输入即建，chip 悬停 × 从本篇移除
删除操作去掉二次确认：笔记、目录、标签与批量删除即点即删，结果在状态栏提示
库位置改为状态栏右侧的文件夹胶囊：点击弹宿主原生文件夹选择窗口直接选目录，不支持对话框的环境回退手动输入
移除「引用到对话」功能（按钮、Ctrl+Alt+K 快搜面板与输入框入口），更专注记录

0.2.0

全新卡片式界面：双栏布局、胶囊搜索、标签 chip 条、分段式编辑/预览切换、底部状态栏
自定义标签管理：提前建标签（支持批量）、一处删除全局生效、tags.json 持久化
列表改平铺速览，新增相对时间显示
Markdown 预览排版全面翻新；引用快搜面板增加快捷键提示条
继承 0.1.x：全文搜索、自动保存、附件导入与 Office 抽取、对话回写、库迁移

0.1.6（上游）

见 fangqiing/dsh-knowledge-lite

🙏 致谢

fangqiing/dsh-knowledge-lite —— 本项目的前身
@lemoncat7/dsh-knowledge —— 回写实现的参考
dsh-market / awesome-dsh-plugin —— 插件生态

License

MIT

dsh-hand-note

Установка

README