会话划线便签 iptton-ai/dsh-plugin-session-notes

会话便签 — DSH 会话划线便签插件

非官方项目，由社区成员独立开发和维护。
非官方项目,由社区成员独立开发和维护。

English · 中文说明

在 DeepSeek Harness (DSH) 的会话消息中选中任意句子划线并记一张小便签；右侧面板聚合展示全部便签，支持按当前目录 / 本会话过滤；便签跨重启持久化，还可一键发送到对话框继续追问。

screenshot: highlight + notes panel

功能

- ✍️ 划线并批注 — 在消息里选中任意文本（可跨加粗 / 代码 / 段落边界），点击浮动的 📝 记便签 按钮，写下你的便签。选中的内容会获得持久黄色划线（CSS Custom Highlight API —— 不改动 DOM，对 React 安全）。
- 🗂 三种作用域 — 每条便签都属于本会话、当前工作区（目录）或全局（整个 DSH）。在面板里创建、编辑、删除；同一作用域的便签在该作用域的任何会话中都可见。
- 🔍 可过滤面板 — 在全部 / 当前目录 / 本会话之间切换，计数实时更新。
- 📤 发送到对话框 — 把便签（内容 + 引用来源）追加到当前输入草稿，随时可发。
- 👀 先看后改弹窗 — 点击划线打开便签，只读展示；编辑是明确的动作。
- 🔄 划线自愈 — MutationObserver + 每 5 秒对账，在重渲染、虚拟化或分页之后重新应用划线。
- 💾 持久存储 — 纯 JSON，位于 ~/.dsh/storages/session-notes/notes.json；优先走 fs-service 写入，失败回退 shell，写入队列串行化。
- 📌 状态便签 （常驻形态） — 每个工作区只有一条生效，更新 = 替换（不是追加）；渲染为面板顶部的 Current 行。见设计文档（灵感来自 project-working-loop）。
- ☑ 任务便签 → 新会话 （常驻形态） — 任务便签带有 next（下一步动作）、doneWhen（验收条件）和完成勾选框。▶ 新会话 会开出一个新会话，开场消息就是该任务的全部世界观：任务 + 创建时的三层快照（引用 / 所在消息 / 触发它的问题）+ 派生时对来源会话最近 30 分钟的尾部摘要 + 工作区状态快照 + 一段「先复述再行动；背景不足就停下」的前言。硬上限 8000 字符，配一套固定的裁剪阶梯。
- ⏰ 定时派生 （常驻形态） — 设置 dueAt（快捷选项：明天 9 点 / 5 小时后）；默认到点自动派生新会话，也可只通知。一次性闩锁，三阶段持久化（跨重启绝不重复派生）；已完成的任务永不触发；错过的自动任务在下次启动时触发。
- 🛡 来源丢失防御（常驻形态）——宿主每 3 分钟轮询一次 session/list：当某个任务的来源会话被删除时，待执行自动派生会降级为通知，并弹出面板决策卡（照常自动跑 / 取消定时 / 编辑）；已归档的来源只加一个软标记。开场消息本身带有「停下并询问」的守卫，用来兜住轮询漏掉的竞态。任务永远不会被悄悄删除——创建时抓取的快照能在会话消亡后存活。

安装

支持两种形态：A. 常驻配置档插件（常驻，重启后仍在，推荐）和 B. 动态 cordis 包（动态，免装即用，重启即失）。

A. 常驻 —— 配置档 bundle（推荐）

本包在 package.json 里声明了 dsh.bundle.patch（→ cordis.patch.yml）。正是这条声明让 DSH 把它当作可管理的 配置档 bundle，而不是普通依赖——没有它，安装会以 "this package declares no bundle, so it cannot be managed as a plugin" 结束。

命令行：

straight from GitHub
dsh plugin --profile web add github:iptton-ai/dsh-plugin-session-notes

or from a local clone
git clone https://github.com/iptton-ai/dsh-plugin-session-notes
dsh plugin --profile web add /abs/path/to/dsh-plugin-session-notes

GUI： 侧边栏 → Plugins → Add plugin，然后粘贴 github:iptton-ai/dsh-plugin-session-notes。

两种方式下，DSH 都会安装依赖、把 dsh-session-notes 追加到配置档的 dsh.profile.bundles，并把包里的 cordis.patch.yml 作为 bundle 层应用——这一层会插入 session-notes 行。重启 dsh web。宿主侧提供 /session-notes/api/；客户端侧通过包里的 dsh.client 声明被拾取，并在每次页面加载时打包（刷新后 UI 仍在）。

手动等效做法（自己编辑配置档）

1. 把本仓库克隆到磁盘任意位置。
2. 把它加为配置档的依赖并安装：

cd ~/.dsh/profiles/web
pnpm add link:/abs/path/to/dsh-plugin-session-notes

3. 把 "dsh-session-notes" 加到该配置档 package.json 里的 dsh.profile.bundles 数组。
4. 重启 dsh web。

不要手动把 session-notes 行插进配置档的 cordis.patch.yml：bundle 自带的 cordis.patch.yml 已经插过了，重复插入会让这一行注册两次。

B. 动态 —— cordis_define

在当前 dsh web 进程里运行——不用构建，不用 npm。

1. 克隆或下载本仓库。
2. 打开一个 DSH 会话（创造模式 / cordis preset——带 cordis_define / cordis_run 工具的那个），对智能体说：

帮我安装这个插件:仓库 https://github.com/iptton-ai/dsh-plugin-session-notes。
用 cordis_define 定义(读取 src/host.js 作为 code.host、src/client.js 作为 code.client,plugin id 前缀 snote), 然后 cordis_run 激活并批准。
或者，如果你更想手动操作：把 src/host.js 和 src/client.js 里的两个函数体粘贴到 cordis_define 的 code.host / code.client，然后对返回的包执行 cordis_run，在 UI 里批准即可。

3. 刷新页面，打开一个会话，选中一些消息文本。

动态插件的生命周期与 dsh web 进程一致。DSH 重启后，重新执行第 2 步（磁盘上的笔记会保留）。

工作原理

| 组件 | 位置 | 作用 |
| 零 DOM 高亮引擎 | src/client.js | 把每条笔记的引文与消息流做匹配，采用空白折叠 + 感知间隙的文本拼接（块级/ 边界插入 \n，行内相邻节点无缝拼接 —— 与 Selection.toString() 一致），然后把 Range 注册进 CSS.highlights（::highlight(snote-hl)）。在不支持 Highlight API 的引擎上回退为 包裹。 |
| 消息流锚点 | src/client.js | 在 conversation.composer.dock 插槽里放一个隐藏条目，向上走到滚动容器 —— 不依赖产品类名，也不替换 DOM。 |
| 侧边面板 / 弹窗 / 选区按钮 | src/client.js | 只做增量插槽条目：shell.overlay、conversation.session.header.utilities。 |
| 持久化 | src/host.js | 通过 harness.handle 提供包内私有 RPC（notes/list|add|update|delete|diag）；JSON 存到 ~/.dsh/storages/session-notes/；针对自己的存储文件按调用使用 danger-full-access 沙箱策略（默认的 workspace-write 围栏不包含 ~/.dsh）。 |

沙箱说明

宿主侧只针对自己的存储文件（~/.dsh/storages/session-notes/notes.json）显式传入 sandboxPolicy: { mode: 'danger-full-access' }，因为部署默认的 workspace-write 围栏不包含 DSH 主目录。插件不会碰其他路径。

中文说明

Session Notes(会话划线便签) 是一个 DeepSeek Harness (DSH) 的动态 Cordis 插件:像在书上做批注一样,在 AI 会话里边聊边划线、记便签。

功能特性

- ✍️ 划线记便签 —— 在任意消息中选中一段文字(跨加粗/行内代码/段落边界的选区都支持),点选区上方的「📝 记便签」按钮写下想法,选中文本即获得持久的黄色划线。基于 CSS Custom Highlight API,零 DOM 修改,React 重渲染不会破坏高亮。
- 🗂 三种归属 —— 每条便签可归属本会话、当前目录(workspace)或全局(整个 DSH);在面板里可新建/编辑/删除,目录级与全局便签在该范围内所有会话可见。
- 🔍 可过滤面板 —— 右侧面板支持 全部 / 当前目录 / 本会话 三档过滤,实时计数;点击划线默认打开只读查看弹窗,点「编辑」才进入编辑态。
- 📤 发送到对话框 —— 把便签(内容 + 引用原文)一键追加到当前输入框草稿,直接继续追问。
- 🔄 高亮自愈 —— MutationObserver + 5 秒对账,消息重渲染、翻页加载、虚拟化后划线自动恢复。
- 💾 持久存储 —— 纯 JSON 落盘于 ~/.dsh/storages/session-notes/notes.json,跨重启保留;fs 服务写入失败时自动降级 shell 通道,写队列失败隔离。
- 📌 状态便签(常驻形态)—— 每个目录一条活跃,更新=替换而非追加;渲染在面板顶部的「当前」状态行,一眼看清做到哪了。设计文档 docs/design-working-loop.md(灵感来自 project-working-loop)。
- ☑ 任务便签 → 新会话(常驻形态)—— 任务便签携带 next(下一步)、doneWhen(验收条件)与完成勾选框。▶ 新会话以任务为世界观开一个全新会话:开场消息 = 任务 + 创建时三层捕获(高亮原文/所在消息/当时的提问)+ spawn 时来源会话 30 分钟尾声摘要 + 工作台状态快照 + 「先复述再执行;背景不足就停下来问」的起手指示;总量 8K 硬顶、固定裁剪阶梯。
- ⏰ 定时启动（常驻形态）—— 设 dueAt（快捷：明早 9 点 / 5 小时后），到点默认自动开新会话，可选仅提醒；一次性闩锁 + 三段落盘，重启绝不双开；已勾完成的任务永不触发；错过的 auto 任务下次启动照常补射。
- 🛡 来源会话失守防线（常驻形态）—— host 每 3 分钟轮询 session/list：来源会话被删时，未触发的 auto 任务自动降级为提醒并浮出决策卡（照常自动跑/取消定时/编辑）；归档仅软提示。开场消息自带停止条款兜住轮询缝隙；任务永远不会被静默删除——创建时捕获不随会话消亡。

安装方法

支持两种形态：A. 常驻 profile 组合包（重启后仍在，推荐）与 B. 动态 Cordis 插件（免安装、重启即失）。

A. 常驻 —— 作为 profile 组合包安装（推荐）

本包的 package.json 声明了 dsh.bundle.patch（→ cordis.patch.yml）。DSH 正是凭这一声明把它当作可管理的组合包；缺了它，安装会以「这个包没有声明组合包，不能作为插件管理」结束。

直接从 GitHub 装
dsh plugin --profile web add github:iptton-ai/dsh-plugin-session-notes

或从本地克隆装
git clone https://github.com/iptton-ai/dsh-plugin-session-notes
dsh plugin --profile web add /abs/path/to/dsh-plugin-session-notes

界面上等价操作：左侧 插件 → 添加插件，粘贴 github:iptton-ai/dsh-plugin-session-notes。

DSH 会把依赖装好、把 dsh-session-notes 追加进 profile 的 dsh.profile.bundles，并把本包自带的 cordis.patch.yml 作为组合包层应用（其中插入 session-notes 那一行）。重启 dsh web 即可。宿主半区提供 /session-notes/api/，浏览器半区经包的 dsh.client 声明被打进每次页面加载的 bundle（刷新不丢 UI）。

手动改 profile 也可以：把本仓库 pnpm add link:<路径> 进 profile，再把 "dsh-session-notes" 加进 dsh.profile.bundles。不要再手动往 profile 的 cordis.patch.yml 里插 session-notes 行 —— 组合包自带的 patch 已经插过一次，重复插入会注册两遍。

B. 动态 —— cordis_define

这是一个 DSH 动态 Cordis 插件，直接运行在当前 dsh web 进程里 —— 无需构建、无需 npm。

1. 克隆或下载本仓库。
2. 打开一个带 cordis_define / cordis_run 工具的 DSH 会话（创造模式 / cordis 预设），对 agent 说：

帮我安装这个插件：仓库 https://github.com/iptton-ai/dsh-plugin-session-notes。
用 cordis_define 定义（读取 src/host.js 作为 code.host、src/client.js 作为 code.client，plugin id 前缀 snote），然后 cordis_run 激活并批准。

也可以手动：把 src/host.js、src/client.js 两个函数体分别粘贴进 cordis_define 的 code.host / code.client，再 cordis_run 激活返回的 package 并在界面上批准。
3. 刷新页面，打开会话，选中一段消息文字即可开始。

动态插件的生命周期与 dsh web 进程一致。DSH 重启后重新执行第 2 步即可（磁盘上的便签数据不会丢）。

工作原理

| 模块 | 位置 | 说明 |
| 零 DOM 高亮引擎 | src/client.js | 用空白折叠 + 间隙感知拼接（块级/ 边界补 \n、inline 紧邻节点无缝相连，与 Selection.toString() 语义一致）把每条便签的引用文本匹配回消息流，然后构造 Range 注册进 CSS.highlights（::highlight(snote-hl) 伪元素绘制）。不支持该 API 的浏览器自动回退 包裹方案。 |
| 消息流锚点 | src/client.js | 在 conversation.composer.dock 插槽注册一个隐藏锚点组件，向上定位消息滚动容器 —— 不依赖产品 class 名，不替换任何产品 UI。 |
| 面板 / 弹窗 / 选区按钮 | src/client.js | 全部为增量插槽项：shell.overlay、conversation.session.header.utilities。 |
| 持久化 | src/host.js | 通过 harness.handle 提供包私有 RPC（notes/list|add|update|delete|diag）；JSON 存储于 ~/.dsh/storages/session-notes/；对自己的存储文件按调用声明 danger-full-access 沙箱策略（部署默认的 workspace-write 围栏不覆盖 ~/.dsh）。 |

沙箱说明

Host 半仅对自己的存储文件（~/.dsh/storages/session-notes/notes.json）显式传 sandboxPolicy: { mode: 'danger-full-access' }，原因是部署默认的 workspace-write 文件围栏不包含 DSH 主目录。插件不触碰其他任何路径。

License

MIT