dsh-web-notes

dsh-web-notes

DeepSeek Harness Web GUI（dsh web）的悬浮笔记插件。把命令、重要凭证、参数值以及任何你认为值得记录的内容随手记下来，并在需要时一键放回对话里。

English

功能

• 悬浮图标 — 聊天窗口右侧的动画笔记本图标，随时可点；可拖拽到任意位置（自动保存），遵循系统「减弱动态效果」设置。
• 入口与大小可配置 — 在 设置 → 插件 → 插件配置 中可选择悬浮（可拖动）或固定（钉在对话窗口右上角，不可拖动）两种快捷入口，按钮大小可选较小 / 常规 / 较大。改动即时生效，无需刷新。
• 笔记面板 — 滑出式面板：搜索、笔记列表（标题、预览、标签、相对时间）、每条笔记的操作按钮。
• 关闭面板 — X、ESC、dock 按钮、点击面板外部、以及触屏下的底部「关闭」按钮都能关闭面板；任何关闭方式都会先保存正在编辑的草稿而不是丢弃，编辑器里的「取消」是唯一的显式丢弃入口。
• 触屏/粗指针适配 — 触屏设备上所有控件放大到至少 44px 触控目标、每条笔记的操作按钮由「仅悬停显示」改为常驻可点行（触屏没有 hover，原本根本点不到）、拖拽调宽条加宽，并在拇指区提供底部「关闭」按钮；精确指针（鼠标）桌面端保持原有紧凑布局不变。
• 引入对话框 — 一键把笔记内容放入当前会话的输入框（标题保留为列表标签，不混入正文），检查后回车即可发送；没有打开会话时自动退化为复制到剪贴板。
• 选中即存 — 在页面上选中任意文本（比如 AI 回答中的一段），旁边会出现悬浮的「存为笔记」按钮，一键保存，首行自动作为标题。气泡会随滚动跟随选中内容，只有当选中取消、点击页面其他位置或切换窗口时才消失。
• Markdown 预览 — 笔记编辑器自动识别 Markdown（标题、列表、代码块、引用、表格、链接、加粗/斜体等）：普通笔记仍是纯文本框；一旦出现 MD 语法即显示「编辑 / 预览」切换按钮，预览按完整 GFM 渲染（DOMPurify 消毒，原始 HTML/脚本不会执行）。
• 会话级笔记 — 笔记可以绑定当前会话（仅在该会话打开时可见），也可以存为全局（所有会话及新对话页均可见）。面板提供「全部 / 当前会话 / 全局」作用域切换；新建笔记默认归入当前会话，编辑器中可勾选「保存到全局」；打开「默认保存全局」后，每次新建笔记都默认存为全局。
• 本地持久化 — 笔记存储在宿主机本地 $DSH_HOME/notes/notes.json（默认 ~/.dsh/notes/notes.json），原子写入、容错读取。
• 隐私优先 — 笔记 API 仅允许 loopback 访问，数据不出本机。
• 主题/皮肤自适应 — 所有颜色都使用官方 dsh 设计令牌（--dsw-alias-*）：默认完美匹配官方浅色/深色主题；安装皮肤插件（dsh-skins / skin-center）后自动跟随皮肤配色实时变化，无需刷新、无需皮肤专用代码。
• 中英文界面 — 跟随页面语言。

安装

从 npm 安装

插件已发布到 npm registry：

dsh plugin --profile web add dsh-web-notes

如果你的默认 npm 源是镜像且尚未同步到该包（例如 npmmirror——只读、同步有延迟），可直接指定官方源安装：

dsh plugin --profile web add dsh-web-notes --registry https://registry.npmjs.org/

本地开发安装

dsh plugin --profile web add link:/path/to/dsh-web-notes

然后把 bundle 加入 profile 清单，插件才会真正启动：

# 在 ~/.dsh/profiles/web/package.json 的 "dsh" > "profile" > "bundles" 列表末尾
# 追加 "dsh-web-notes"，然后重启 dsh web

官方 dsh plugin --profile web add <spec> 只是转发给 pnpm：它会安装包，但不会修改 dsh.profile.bundles 清单——由这个清单决定哪些已安装的包会被启动。需要手动把包名加进去（或通过聚合包携带 cordis.patch.yml insert），再重启。

验证安装

dsh plugin --profile web list          # 应能看到 dsh-web-notes
npm view dsh-web-notes version         # → 最新已发布版本

重启 dsh web 后，聊天窗口右侧会出现笔记本图标（见使用）。

更新

dsh plugin 只是转发给 pnpm，所以更新就是 pnpm 的 update——无需手动改 manifest（profile 会在下一次 dsh plugin 运行时按已安装状态自动对账 bundle 清单），然后重启 dsh web：

dsh plugin --profile web update dsh-web-notes
# 或指定精确版本：
dsh plugin --profile web add dsh-web-notes@latest --registry https://registry.npmjs.org/

镜像同步延迟：发布是发到官方源的，而 npmmirror 等镜像同步有延迟——刚发布后你的默认源可能还是旧版本（甚至短暂 404）。如果新版本发布后 update「没反应」，加上 --registry https://registry.npmjs.org/ 直连官方源即可。

更新不会动你的笔记：数据存在宿主机 $DSH_HOME/notes/notes.json，设置也会保留。

使用

1. 点击聊天窗口右侧的笔记本图标。
2. 点击「新建」记录内容（标题可选，默认取内容首行）；或在页面上选中任意文本，点击悬浮的「存为笔记」。
3. 笔记列表中：
   • 引入 — 把笔记放进当前会话的输入框（若已有内容则追加在后面），回车即可发送。
   • 复制 — 把标题 + 内容复制到剪贴板。
   • 编辑 / 删除 — 管理笔记。

笔记支持按标题、内容、标签搜索（编辑时用逗号分隔标签）。

配置

插件注册了 notes 设置命名空间，并在 设置 → 插件 → 插件配置 中提供设置卡片（命名空间也可通过 ~/.dsh/settings.yaml 修改）：

notes:
  enabled: true            # 总开关：false 时完全隐藏悬浮图标
  selectionCapture: true   # false 时关闭「选中即存」悬浮按钮
  dockMode: floating       # floating（悬浮可拖动）| fixed（对话窗口右上角固定）
  buttonSize: large        # small（较小）| regular（常规）| large（较大）
  defaultGlobal: false     # 新建笔记默认存为全局（所有会话可见）

五项均可直接在设置卡片中实时修改，悬浮图标与面板立即响应。

安全说明

笔记里可能包含凭证、Token 等敏感信息。它们以明文存储在本地 JSON 文件（~/.dsh/notes/notes.json，与 ~/.dsh/credentials.yaml 同一信任模型），且仅向本机浏览器提供服务。请勿存放你无法承受在本机泄露的密钥，并依靠操作系统的用户权限保护该文件。备份/导出该文件即等于导出全部笔记。

开发

pnpm install
pnpm run build        # tsc -b（类型）+ tsdown（lib/index.js + lib/client.js）
node scripts/smoke-host.mjs   # 宿主逻辑独立冒烟测试（无需 dsh 应用）

# 客户端 UI 验证，无需 dsh 应用（见下）
pnpm exec tsdown --config tsdown.harness.config.ts
node scripts/verify-touch.mjs

scripts/verify-touch.mjs 驱动 scripts/harness/entry.tsx：一个独立 harness，用真实的 NotesDock 组件树 + 真实的 NOTES_CSS 配上 mock 的宿主契约（笔记 API、会话 store、settings scope），在无头 Chrome 中经 CDP 断言粗指针适配与各条关闭路径，并输出 .logs/touch-desktop.png / .logs/touch-coarse.png 供肉眼检查。

scripts/cdp-*.mjs 与 screenshot.mjs 这些探针驱动的是正在运行的 GUI，因此需要该实例的浏览器认证：dsh ≥ 0.1.5 把 / 放在进程级 launch token（换取签名 cookie）之后，全新的无头浏览器会拿到 401 dsh web authentication required，应用根本不会启动。请在同一个浏览器 profile 中打开 dsh web 启动时打印的带 token URL，或改用上面的 harness 做纯客户端检查。

架构：

• 宿主侧（src/index.ts、src/service.ts、src/routes.ts、src/persist.ts）— cordis 插件行 notes：CRUD 服务、原子 JSON 持久化、loopback 保护的 /api/notes/* 路由、settings 命名空间。
• 浏览器侧（src/client/）— 直接挂在 document.body 上的全局悬浮界面（笔记没有会话维度）；通过同源 JSON 与宿主通信；通过官方对话输入门面 ctx.conversation.input.for(actx).setDraft(...) 写入输入框。

客户端 bundle 以闭包工厂产物（window.__ModuleLoader__.load({ id: 'dsh-web-notes', factory })）构建，由 web 插件表在 /plugins/dsh-web-notes/client.js 提供。

Roadmap

• 笔记分类 / 置顶。
• 引入时可选「直接发送」。

License

Apache-2.0。© 2026 Shrbuz — 署名信息见 NOTICE。