@timestatic/dsh-session-notebook

dsh plugin --profile web add @timestatic/dsh-session-notebook

<div align="center">

dsh-session-notebook

面向 DeepSeek Harness（DSH）会话的本地笔记插件：把对话里值得留下的内容划线、引用、整理成可搜索的笔记库。








</div>

dsh-session-notebook（界面名「AI 笔记」）是一个常驻 DSH 的 npm Bundle 插件。它把 AI 对话中的片段沉淀为持久、可检索、可导出的个人知识。

插件只在本机存储数据，不采集遥测、不自动把笔记送给模型。它复用宿主提供的 React、主题与连接通道，不接管页面、不捆绑第二份运行时、不注册共享 /api 拦截器，因此不会破坏 DSH 官方的启动、API Gateway、认证与连接生命周期。

为什么需要它

会话记录是一次性的流水，里面的结论、判断和踩过的坑却是长期资产。这个插件想让你像读电子书一样读 AI 会话：顺着正文往下读，遇到值得留下的句子就划下来，补一条自己的想法或标记「待验证」，高亮会持久重绘回原文位置；读完一轮，个人知识库里便多了几条可检索、可整理、可导出、能回链到来源会话的笔记。

• 长对话里翻找上一轮已经得出的结论，比重新问一遍还慢。
• AI 给的判断需要标注"待验证"，而不是和已确认的内容混在一起。
• 跨会话攒的 TODO、架构原则、踩坑记录，散在多个会话里就没有第二次生命。

目录

• [界面一览](#界面一览)
• [能做什么](#能做什么)
• [快速开始](#快速开始)
• [如何工作](#如何工作)
• [数据存储](#数据存储)
• [能力状态与已知边界](#能力状态与已知边界)
• [开发与检查](#开发与检查)
• [打包与安装](#打包与安装)
• [文档](#文档) · [许可](#许可) · [支持](#支持)

界面一览

上图即真实运行效果（DSH Web Host）：左侧会话正文里，黄色是插件重绘的已保存划线，点击一条会弹出「原文批注」详情（引用与批注正文，支持 × 或 Escape 关闭）；已完成回复的操作栏上有 ☆「收藏这条回复」按钮；右侧「AI 笔记」面板列出笔记卡片，标签、来源与时间直接显示在卡片上。

面板分四个 Tab：笔记库 / 回收站 / 标签 / 数据备份。顶栏显示工作区，面板底部显示插件版本与 Host 连接状态。

能做什么

• 划线与引用：选中会话正文即可保存为划线，附带准确原文、上下文与文本锚点；不伪造官方 messageId。
• 收藏整条回复：每条已完成、未中断的 Assistant 回复操作栏有 ☆ 按钮，弹出小窗可「收藏到笔记」一键保存（标题取回复开头，正文自动附来源 Session/Message 脚注），或「记笔记」把内容载入右侧面板草稿继续编辑；弹窗内可勾选标签（最多 10 个）。原文不抓页面 DOM——Host 经宿主公开的 sessionQuery 事件流精确读取该回复的最终文本（上限 99,000 字符）；保存结果不确定时可按同一请求重试，或放弃未确认的保存。
• 三种笔记类型：划线（只有引用）、笔记（引用 + 自己的正文）、手工笔记（自己写正文，可携带原文作为改写来源）。原始引用只读，正文独立编辑。
• 标签组织：创建、重命名、合并、删除标签；标签可选自动分配或六种预设颜色（亮粉、活力橙、明黄、薄荷绿、亮蓝、紫罗兰）。内置 TODO、重要、待验证快捷标签。
• 搜索与筛选：按正文、引用、标题、来源、标签检索；范围可选全部笔记 / 当前项目 / 当前会话，类型可筛，标签可多选（任一命中即匹配），也可只看「无标签」；另有时间字段、起止时间与排序等「更多筛选」；列表每页 50 条。标签 Tab 的筛选 chips 直接显示每个标签的笔记数。
• 持久高亮：在当前会话已挂载的消息上重绘高亮。点击命中一条划线直接打开详情；同一位置命中多条时先给出候选列表让你选。
• 回收站：普通删除先入回收站、可恢复；永久删除需要单独确认。删除标签只解除关联，不删笔记。
• 导出与备份：批量选择后导出为单个 UTF-8 Markdown 文件（可选包含标签与来源），确认后才下载；「数据备份」Tab 可下载含笔记、标签、来源锚点和回收站内容的完整 JSON。
• 回到对话：复制笔记的 Markdown、写入当前输入框或追加到最新草稿——都只在你确认后发生，绝不自动发送。

界面按明暗主题适配。打开笔记库的入口是会话头部工具区的「AI 笔记」图标按钮（悬停提示「打开 AI 笔记」）。

标签与检索

快速开始

环境要求

• Node.js >= 22（开发基线见仓库 .nvmrc；该文件不随 npm 包分发）。
• 已安装并登录的 DeepSeek Harness Desktop 或独立 Web Host。开发目标版本 0.2.0-rc.2；安装与启用需使用目标 Profile 对应的官方管理入口。

本地构建

npm ci                        # 安装工作区依赖
npm run build:client          # 由模板生成 src/client/index.js（首次或改模板后）
npm run check                 # 校验 Client 产物与模板一致 + 全部入口语法检查
npm test                      # 运行单元测试

安装到 Web

dsh plugin --profile web add @timestatic/dsh-session-notebook@0.2.0

Profile 名可用 ls ~/.dsh/profiles/ 查看（$DSH_HOME 未设置时为 ~/.dsh）。安装后启用插件，按需重启 Web Host。

安装到 Desktop

Desktop 从 Releases 下载对应版本的发布包（例如 v0.2.0 的 timestatic-dsh-session-notebook-0.2.0.tgz），再作为本地插件包安装进 Desktop：

1. 下载 .tgz，放到你有权访问的目录，不要解包，也不要放进 Profile 目录。

2. 在 Desktop 的插件管理页面选择“从本地包安装”，指向这个 .tgz；或在支持 plugin_manager 工具的 Desktop 会话中用 install_bundle 传入该文件的绝对路径（registry 为空字符串会安装失败）。

3. 读取返回的 application：restart-required 时须完整退出 Desktop 再重开，applied 才能继续验收。

4. 复查 list_bundles，确认目标 Profile 只有一个版本且 enabled 正确。

Desktop Profile 由 Electron 应用独占管理，普通终端的 dsh plugin --profile desktop ... 会直接报错，也不要用 npm install 装进 Profile。完整约束见[打包与安装](#打包与安装)与开发约束 §9；安装、启用、重启均需你单独授权。

开始使用

安装并启用、按需重启后：

1. 点击会话头部的「AI 笔记」图标，进入笔记库面板。

2. 在会话中选中一段文字，用浮层保存为划线，或补充正文 / 改写为笔记；也可点击已完成回复操作栏的 ☆，一键收藏整条回复或转为草稿笔记。

3. 用标签、搜索与范围筛选整理笔记；批量勾选后可导出 Markdown 或下载 JSON 备份。

如何工作

Client（会话标注 / 笔记库面板 / preview-api 传输适配）
  → connection.rpc.call('/api', 'dsh-session-notebook/<endpoint>', payload, signal)
  → 宿主 carrier + 精确 Notebook 路由（复用宿主 admission，校验 RPC 信封）
  → manual-runtime.js → preview-routes.js → manual-notebook-service.js
  → snapshot-coordinator.js → host/json-store.js → notes.json + data/<uuid>.json

关键点：本插件不注册共享 /api 拦截器，只注册自己命名空间下的精确路由；Client 走宿主提供的连接通道，不自行拼接认证请求、不读取页面 token。「收藏整条回复」由 Host 的 session/capture 精确路由承载，经宿主公开的 sessionQuery 服务只读该会话事件流、校验回复已完成且未中断后才返回原文，同样复用宿主 admission 与 RPC 信封校验。完整链路与安全边界见设计文档 §2。

数据存储

• 结构：notes.json 元数据 + 同目录 data/<uuid>.json 不可变笔记文件；元数据是唯一提交点。
• 默认位置：$DSH_HOME/storages/dsh-session-notebook/；未设置 DSH_HOME 时用 ~/.dsh/。插件配置 storageFile 可指定规范绝对路径；不读取其他插件数据。

$DSH_HOME/storages/dsh-session-notebook/
├── notes.json                     # 元数据：唯一提交点
├── .dsh-session-notebook.owner    # 目录归属哨兵，拒绝多个清单共用同一 data/
└── data/
    ├── <uuid>.json                # 每条笔记一个不可变文件
    └── .pending-<pid>-<uuid>/     # 提交前暂存，冲突时清理

• 多进程可打开同一库：Web 与桌面端可同时读写。进程只在加载快照、刷新、提交清单和回收文件期间短暂持有目录锁，冲突请求最多等待 5 秒。
• 变更先写入 data/.pending-<pid>-<uuid>/，锁内重读清单并校验 epoch / revision，通过后才把 UUID 文件提升到 data/ 并原子替换元数据；过期快照返回版本冲突，不覆盖其他进程的提交。损坏或缺失已引用 data 时停写，不把故障库当空库。
• 预算：有效元数据与引用 data 总计 50 MiB；收据最多 100000 条、最多 16 MiB，超限拒绝新修改。
• 非正常退出可能残留锁标记；插件不会自动删除无法确认所有者状态的标记，需先核实所有进程已停止，再按恢复流程处理。

实现细节见[设计文档 §5](https://github.com/timestatic/dsh

…(truncated)