English | 中文
版本适配（dsh-notes ↔ DSH）
DSH 更新频繁，插件各版本能力与适配范围不同，升级插件前请对照下表。声明范围来自 peerDependencies（npm 安装时强制校验），「实测基线」是该版本开发与回归所用的 DSH 版本：
| 插件版本 | 发布 | 声明适配 DSH | 实测基线 | 要点 |
|---|
| 0.6.1 | 2026-10-14 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 维护补丁（健壮性 / 安全闸 / 文档，零新语法零新形态）：文档安全写侧闭环（掩码回写守卫——note_get 掩码态正文回写=整体拒绝不落盘 + 自救指引，机密区整块占位与行级敏感占位双形态判定；巡检自伤事故实证驱动）+ 机密读取记录查看入口（设置「数据与存储」组，reveal 审计环形缓冲最近 100 条，双端）+ 向量层卫生（启动对账——重启漏索引自愈 +「上次构建」重启不丢 + pendingErr 分键 + indexable N≡M 口径）+ 检索精修（İ/ß/fi Unicode 摘要偏移修复 + 短查询压制阈值真模型实证保持 + 存量键清理）+ README 双语「宿主能力依赖」表（功能 × 宿主版本 × 缺席行为，版本号实证钉验）；check 1269→1295 · e2e 624→641（67→69 用例） |
| 0.6.0 | 2026-10-12 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 大版本·机密区间（文档安全批次 S2-S6 六卡）：```secret 围栏机密标记（选区一键包 fence，工具栏 / 右键 / Ctrl+Shift+S 三入口，面板三件套同构）+ 编辑器双模遮蔽（富文本模糊岛 + 源码模式不透明遮蔽块，点击揭示约 10 秒自动回蔽、揭示态可编辑——遮蔽纯渲染层红线：textarea.value 永存真原文，保存往返逐字节断言锁定）+ 十面消费管线避让（注入 / note_get（缺省打码 + spanCount）/ 检索 / 摘要 / 向量索引 / AI 整理 / 导出（含单导出 + includeSecret 开关）/ 派发载荷 / 体检 / 选区——机密永不裸奔）+ reveal 门禁（agent 读机密须先 ask_user_question 征得用户同意，每次 reveal 记进程审计日志——纪律门禁非密码学边界，诚实标注）+ 保存时自动检测疑似凭据建议（一键标记 / 忽略，绝不自动改写正文；设置卡「数据与存储」组全局开关缺省开，仅管建议不管保护）；check 1223→1269 · e2e 581→624（61→67 用例） |
| 0.5.0 | 2026-10-10 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 大版本·语义检索（主批次四卡 + 真机冒烟驱动的 P0-P2 修复与 R1-R3 架构修订）：本地语义检索（bge-small-zh 向量嵌入与文本通道 RRF(k=60) 融合排序——词面零重叠的概念查询也能召回；嵌入/索引/查询全在 host 进程闭环：onnxruntime-web 纯 wasm 零原生依赖，浏览器纯消费端，正文不出机器）+ 保存即嵌入（2s 防抖微批，保存→可搜 <5s）+ 「构建索引」后台异步全库重建（立即返回 + 状态行轮询进度 + 真失败 sticky 报错）+ 搜索摘要行 + 命中高亮 + 「语义」徽标（note_search 同步带摘要）+ 语义设置区（总开关缺省关闭零成本；模型 23MB host 侧按需下载，镜像链 hf-mirror→HF；敏感与 sys 机器笔记永不入索引）+ 定时调度唤醒休眠目标（agents.resume）+ 挂载行随目标笔记 injectTo 过滤；check 1111→1223 · e2e 529→581（61 用例） |
| 0.4.8 | 2026-10-08 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 七卡（UX 重构专批 + 测试网信任章，UX 巡检 R1/R2 候选清账）：双链 [[ 输入补全（源码模式光标处候选下拉，内存搜索零 RPC，键盘边界锁）+ 三重分类收敛（主题并入标签——读侧 effTags 虚拟合并零迁移风险、写侧惰性落盘、侧栏「主题」树改「标签」树多值分组、编辑器标签增删控件）+ 笔记行右键菜单（移动到…树形子层/置顶/派发/删除）+ 设置弹窗分组导航（七组 rail + 窄宽 chips + scroll-spy）+ 语言切换上顶栏（🌐 中文/English 两态直切，设置项下线）+ mock/宿主契约对齐审计（17 处漂移修复 + 常驻闸：注册对等/键集活体 36 探针/过滤矩阵 12 组/豁免清单——host 加 RPC 忘同步 mock 即红）+ 注入管理窄宽溢出双修复；check 1050→1111 · e2e 359→529（51 用例，含面板真机通道） |
| 0.4.7 | 2026-10-08 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 七卡（用户实测驱动，6 个真 bug 活机钓出）：调度稳定性（锚定任务首触永不触发 P0 热修 + 同名任务专属会话按笔记 id 尾缀判别不再冒领）+ 专属会话权限预设（schedule 第 10 键 preset 完全/受限两档显式声明 + 创建透传宿主 permissionPresets + 派发弹窗权限下拉与「无界面会话」提示行）+ AI 整理专题（整理中遮罩/失败驻留条/超限前置校验 + 长度上限按模型自适应且可配 organizeMaxChars）+ 约定体检超时 8s→120s + 编辑器数据安全（关闭瞬间在途编辑 flush + 失败态双端统一红点「加载失败」+ 源码模式在途窗补锁）+ 面板 e2e 通道通车（mock 挂载 harness + React vendor，面板真机用例入网，kind 滞后/组分页等带病发版路径入锁）+ UX 打磨（设置粘性保存条/长说明收折/顶栏封板溢出菜单/组尾加载行键盘可达/三态 ⓘ）+ 遥测上报退避与 /dsh-notes 慢请求诊断钩；check 1007→1050 · e2e 231→359（39 用例） |
| 0.4.6 | 2026-10-07 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 合版（含未发版的 0.4.5，21 卡 + 1 热修，UX 巡检 R2 + 用户实测驱动）：稳定性加固（RPC 韧性层——20s 超时/挂起「连接慢」提示条/落地页空态 + 富文本在途窗「假同步绿点」根修为锁编辑+「正文加载中」）+ 治理入口上顶栏（「建议」按钮带实时计数徽标 + 约定体检直达 + 使用说明首屏「核心概念 30 秒」）+ @ 引用笔记直达输入框（候选「笔记」分组，标题搜索正文内联注入）+ 约定体检（LLM 两两检测注入中约定的冲突/被取代对，敏感打码，只提名不执行）+ 详情页一键导出 MD + 会话头部 📎 注入清单徽标（点开明细浮层）+ 调度专题（周期任务编辑误触发根修 declaredAt 重锚 + 专属会话支持选模型）+ 分组分页（置顶/文件夹/未入夹/主题四组各自「加载更多（还有 N 条）」，全局窗口切片与滚动加载死锁退役）+ kind 过滤滞后一拍根修（filtersRef 序位缺陷，显式传参）+ 派发完成不再自动标 resolved（回执经空闲转换闭环，resolved 纯人工兜底）+ 文案通俗化与一致性 19 项 + 建议器断点 6 项 + check 节注册自动发现（消批次共享锁）；check 882→1007 · e2e 231（31 用例） |
| 0.4.4 | 2026-10-06 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 八卡（用户活机提案驱动）：派发体系重构（派发回执笔记化——「执行记录 · 标题」kind=log 伴生笔记归专用夹、📤/📥/✅ 三表归一、双端可点跳转 + 休眠会话「下次活动送达」零唤醒 + 周期定时专属会话首轮创建复用）+ 目录段补充行整体移除（挂载行=目录段唯一内容源）+ 文件夹治理（文件夹展开=sys 显式入口直翻记忆档案 + hidden 隐藏属性纯 UI 遮罩（显隐开关/右键隐藏/跳转常显）+ 自动沉淀夹 sys 默认隐身（工作日志/记忆档案/执行记录，机器档与显示隐藏双通道放行））+ AI 整理可选追加指令弹卡（无指令路径 prompt 逐字节等价）+ 重开面板正文空白修复（富文本非受控 DOM 重建洞，双闸）；check 824→882 · e2e 141（22 用例） |
| 0.4.3 | 2026-10-05 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 合版（含未发版的 0.4.1/0.4.2 及主批次 14 卡 + 验收修复 12 卡）：笔记网络内核（图内核/RootNote 托管节/onNoteChanged 事件总线/per-note 串行链/kind=sys）+ 注入管线三层架构（载荷=注入索引 §1 挂载行「何时查我」人可编辑 / 机器存储=telemetry.json 四纪律 / 呈现=目录段价值信号行）+ 目录与资料桶合并单一目录段（挂载行=增强态，缺省关）+ whenToUse LLM 预填挂载弹框（三入口 modal-first，8s 回退标题）+ 日志与普通笔记同权（可见/可搜/可编辑/显式可目录，唯注入硬关；「文件视图」与 overlay 特化拆除，展开卡顿 64×→1×）+ sys 机器笔记缺省降噪（面板「机器」档翻记忆档案，档案归位真实文件夹）+ useCount 收编 note-stats facet 单一事实源（note_get 热路径零 .md 重写）+ 效用账本三层（遥测/信号行/记忆档案明细）+ 浏览器 e2e 套件（17 用例 90 断言）；check 736→824 |
| 0.3.3 | 2026-10-04 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 工作记忆 r3 车道模型（约定/记忆并行通道，启用不再做重叠冲突确认）+ 注入管理面板（全库注入三态总览 + 单行直改 + 多选批量）+ 设置卡交互反馈（✕ 常驻关闭 + dirty 保存/还原 + 关闭兜底 flush）+ 内部模块化重构（client 46 片 / app 40 片 / host 双清单 45 片次，双包同源组装器逐字节等价 + 发布面零 BOM 断言）+ check --only 分节回归；peer 声明不变 |
| 0.3.2 | 2026-10-03 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 纯 README 补发（0.3.1 发版 README 未同步事故补救：补齐版本历史/Token 统计/嵌套文件夹等特性描述），零代码变更 |
| 0.3.1 | 2026-10-03 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 工作记忆 v0（kind=log 工作日志沉淀 + memory-guide 引导 + 日志卫生）+ 快照版本历史 + Token 消耗统计 + 虚拟文件夹嵌套（maxFolderDepth/递归子树/级联删除）+ 回收站批量与多选删除 + 列表韧性；npm 页 README 停留 0.3.0 清单（0.3.2 已补救） |
| 0.3.0 | 2026-10-02 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 大版本：编辑器双模式（源码⇄富文本）+ 图片支持 + ✨AI 整理 + 显式归档（预览/撤销）+ 敏感脱敏 + 注入增强（时效/预算/预览器）+ 回收站 + 使用遥测 + 双链/反向链接 + 单文件导出 + 整理建议器 + 筛选中心（约 20 项，详见功能清单）；peer 声明维持不变（上界 ^0.2.0 保守不放开 0.3.x——未验证） |
| 0.2.4 | 2026-09-30 | ^0.1.7 | 0.2.0-rc.2 | ^0.2.0 | 0.2.0-rc.2 | 兼容 DSH 0.2.0：声明显式覆盖 0.2.0-rc.2 预发布（semver 预发布不命中宽区间，须枚举）；改名竞态防正文丢失；已在本机 0.2.0-rc.2 实测加载 |
| 0.2.3 | 2026-09-30 | >=0.1.7 <0.2.0-0 | 0.1.7 | npm 页面 README 与仓库根同步（sync-pkg-readme + docs 入白名单） |
| 0.2.2 | 2026-09-30 | >=0.1.7 <0.2.0-0 | 0.1.7 | 声明范围校正：下限收紧到实测基线 0.1.7（0.1.5~0.1.6 派发列表超时实测不可用，0.2.1 仍误声明旧范围） |
| 0.2.1 | 2026-09-30 | >=0.1.5-rc.1 <0.2.0-0 | 0.1.7 | 上下文注入双角色（约定/资料）/ 注入范围移除工作区维度（默认所有会话）/ 入口按钮与配色 v2 打磨 |
| 0.2.0 | 2026-09-29 | >=0.1.5-rc.1 <0.2.0-0 | 0.1.7 | 虚拟文件夹 / UI v2 / 目录索引注入 / 导入导出 / /dsh-notes-app / 0.1.7 派发性能修复 |
| 0.1.2 | 2026-09-25 | >=0.1.5-rc.1 <0.2.0-0 | 0.1.5~0.1.6 | 基础面板：CRUD / 快速记录 / 派发 / 约定注入 / 搜索 |
| 0.1.0 | 2026-09-23 | >=0.1.5-rc.1 <0.2.0-0 | 0.1.5-rc | 首个 npm 发布 |
- 建议：始终使用最新插件版 + 表中「实测基线」及以上的 DSH；低于实测基线时不保证 RPC 面完整（如 <0.1.7 有派发列表超时问题，0.2.0 已带缓解但行为以 0.1.7 为准）。
- semver 预发布提示：
0.2.0-rc.2 这类预发布版本不命中 >=0.1.7 <0.3.0-0 这类宽区间（semver 规则），声明里须显式枚举预发布分支——0.2.4 起已按此声明。
- DSH 发生大版本变更（
0.x 次版本跃迁）时，本表会在插件对应适配版发布后更新；peerDependencies 上限（当前 <0.3.0-0/^0.2.0）即"未在更新后的 DSH 上验证"的保守声明，解除以新插件版本发布为准。
宿主能力依赖（功能 × 宿主版本 × 缺席行为）
上面是版本级发版史；本表换一个维度——按功能列出对宿主能力的依赖，以及能力缺席时的实际行为。版本号均经宿主 npm 发布包代码实证钉验，非凭印象：
| 功能 | 需要宿主版本 / 能力 | 缺席时行为 |
|---|
派发会话列表（会话元数据缓存 + titlesPending 轮询） | DSH ≥ 0.1.7 | 列表慢/超时（0.1.5~0.1.6 实测不可用）；插件 0.2.0 起自带缓存+轮询缓解，行为仍以 0.1.7 为准 |
| 定时调度唤醒休眠目标 | 宿主提供 agents.resume（实证 dsh-agent 包 0.1.5-rc.1 起存在，声明区间全覆盖） | 运行时逐点探测：缺席时调度链记 lastError（「宿主不支持 agents.resume」），不静默排队、不崩页面；手动派发不受影响 |
| 笔记面板与会话头部入口 | 宿主 slots 服务 + 内建槽位 shell.overlay / conversation.session.header.actions（实证 0.1.5-rc.1 起存在） | slots 服务缺席时 client 记 console.error 并整体跳过挂载——入口按钮与面板不出现，宿主页面其余部分不受影响 |
| 工作记忆 / 注入 / 检索 / 语义检索 / 机密区间 | 无额外宿主依赖（插件侧闭环；语义嵌入在插件自己的 host 进程代码内完成，正文不出机器） | —（不依赖声明区间之外的宿主能力，无缺席情形） |
总原则：宿主能力缺席时按能力降级、不崩页面——能运行时探测的逐点探测降级（如上两行的能力探测与守卫），不能探测的交给 peerDependencies 在 npm 安装期拦截。
解决什么问题
Agent 会话里的结论是「一次性」的：一个方案为什么这么选、项目有哪些硬约定、下午冒出来的待办，全都散落在对话流里；上下文一压缩、会话一关，这些知识就没了。下一个会话的 agent 不知道上周定过什么，用户也得反复复述约定。
dsh-notes 把这件事变成可积累的本地资产：
| 问题 | 解法 |
|---|
| 结论聊完就丢 | 面板内 Enter 即存为本地 Markdown（~/.dsh/notes），选区文字一键摘录，永不出本机 |
| 笔记越记越乱 | LLM 异步识别主题并回填标题/分类，kind（笔记/决策/待办/链接/引用）与 status（进行中/置顶/已解决/已取代）两个正交维度 + 虚拟文件夹归档 |
| agent 不知道约定与资料 | 详情区「⚡ 关闭 / 约定 / 资料」三态分段控件：约定=须遵守的行为规则、资料=事实性补充信息（agent 按需取用），笔记内容按角色分桶注入 Agent 系统提示（order 130），范围默认注入所有会话，可限定指定会话 |
| agent 不知道库里有什么 | 目录段（并入 order 130 单一注入段）：挂载行（- [[id]] 何时查我：…）是唯一内容源——显式挂载才进段，附规划轻推自动进系统提示；相关条目 note_get 拉全文、note_search 检索更多（0.4.4-E 起不再平铺全库清单） |
| 待办没人执行 | 一键把待办派发给任意活跃会话（Agent.send 注入「召回上下文 + 具体要求」并唤醒对方开始工作），派发历史可标记完成 |
| 事后找不到 | 面板即时搜索 + 全文兜底并集检索、note_search 工具按 tag/topic/kind 过滤、归档按会话或标签合并、软删除可恢复 |
设计哲学：笔记网络
dsh-notes 不只是「一个带面板的笔记插件」——整个产品是一张不断生长的笔记引用网络：节点 = 笔记（记忆 / 资料 / 日志 / 档案 / 索引 / 待办…），边 = 引用。功能千变万化，载体永远是网络上的一个节点；治理界面皆节点，高频写皆根文件。每加一个新特性，先用裁决问句过一遍：它的节点是什么？它的边是什么？（先有节点，再有边）
网络里的四类边：
| 边 | 形态 | 语义 |
|---|
| 双链 | 正文 [[id]] | 证据（日志 → 记忆）/ 关联 |
| 软链 | front-matter 字段（schedule.runLog、refNote） | 关联（伴生笔记指向宿主） |
| 索引挂载 | 注入索引 §1 行 - [[id]] 何时查我：… | 挂载（索引 → 资料，召回主通道） |
| 派发挂载 | dispatches[].sessionId | 召回（任务 → 资料 = 确定性分发） |
根索引模式：机器产物不建新面板——数据集中在链接的伴生笔记（RootNote 托管节框架：锚点节 / 行格式 / 幂等 / 裁尾；机器只做节内行级操作，节外零触碰）。实例：定时派发执行记录、记忆档案、注入索引。召回指标是用户裁决的例外通道（0.4.3 验收修复⑤）：遥测属高频机器计数，迁出笔记正文到 notes/telemetry.json 机器存储层（内存增量 + 2s 防抖原子落盘 + 容量三闸，单写者 = host 进程），存量「召回遥测（自动）」笔记降级为日评估顺带刷新的人读镜像（热路径零笔记写入），指标汇总经 notes-recall-stats RPC 输出到面板。呈现层（0.4.3 验收修复⑥）：注入装配在目录段尾部追加价值信号行（（本周引用：id×次数｜零引用候选：id｜截至 HH:MM）——账本快照内存现算、与目录行同版本原子快照、只提存活目录行 id、无快照静默省略、≤200 字符），注入管理面板挂载区出紧凑统计行（挂载 N｜本周引用 Top｜零引用 M，点开见全量分通道统计）——信号行只服务注入呈现，正确性/清理裁决必须走 notes-recall-stats 全量或人工（用途分级红线）。原正文零触碰——约定正文是派发载荷，历史一律写进伴生笔记。
记忆治理两层（召回保证性分级）：inject 全文注入 = 强保证；任务挂载（索引 §1 一行 whenToUse）= 中保证 · 主力通道。资料默认不注入——挂载是显式动作。（原弱保证层「索引目录全库平铺」已于 0.4.4-E 整体移除——全库平铺与「资料=显式挂载」模型冲突。）
红线：约定桶全文注入不动；资料默认不注入（任务挂载显式开通）；档案/指标类根笔记永不注入（防套娃）；工作日志与普通笔记同权（可见/可搜索/可编辑），唯注入硬关——inject 永不可开启（UI 不提供开关 + host 强制纠正双保险）。
安装
宿主要求：Node ≥ 22；DSH ≥ 0.1.5-rc.1（已通过 peerDependencies 声明，含预发布分支的版本范围见 package.json）
dsh plugin --profile web add dsh-notes-plugin
重启 DSH 后生效：会话头部出现「智能笔记」按钮（✎，带计数徽标），点击打开/关闭面板；桌面角落另有可拖拽的悬浮气泡入口。
体积说明：0.5.0 起语义检索的嵌入运行时随包分发（onnxruntime-web 纯 wasm + transformers.js，约 +25MB）。零原生保证是构造性的：host 侧恒导入 transformers 的 web 构建（其中 sharp/onnxruntime-node 为 webpack ignored 空壳、从不被引用），与安装布局无关；npm overrides 整包桩化保留为纵深防御——本仓库安装树零 .node/零 @img/* 二进制。向量模型本体（bge-small-zh-v1.5，约 23MB）不进 npm 包：首次启用语义检索时经镜像链（hf-mirror → huggingface.co）下载到 ~/.dsh/notes/models/，全程本地推理、正文不出机器。
升级 / 卸载
dsh plugin --profile web add dsh-notes-plugin@latest # 升级（重启 DSH）
dsh plugin --profile web remove dsh-notes-plugin # 卸载（不删数据）
功能清单
- 快速记录：顶栏
＋ 图标（或 Alt+N）展开输入框，Enter 即存、Shift+Enter 换行；LLM 异步识别主题并回填标题，不阻塞交互
- 选区记录：选中页面任意文字浮出「快速记录」按钮，一键存为
quote 类型笔记（也可在同一浮层写「备注」，由 LLM 提取标签/类型/注入意图）
- 同会话合并：10 分钟窗口内的连续速记按时间戳自动合并成一条，避免碎片化
- 类型与状态：
kind = 笔记 / 决策 / 待办 / 链接 / 引用；status = 进行中 / 置顶 / 已解决 / 已取代（置顶单独分组，已解决降透明度）
- 虚拟文件夹（支持嵌套）：侧栏笔记树按「📌 置顶 / 📁 文件夹树 / 未分类笔记」组织；文件夹可嵌套（右键「新建子文件夹」或拖拽换父，深度上限
maxFolderDepth 默认 3 层、可调/0 不限，cycle 自动拒绝）；文件夹视图与计数按递归子树口径（点父文件夹可见全部子孙内容）；删除文件夹=连子删除（confirm 明示「N 个子文件夹 + M 条笔记移入回收站（可恢复）；文件夹结构不可恢复」，恢复的笔记原文件夹已不存在时自动落未分类）；右键可重命名 / 上移下移（同级内换位）/ 移回根级；清单持久化在 folders.json（parent 字段，存量零迁移），选中态存 localStorage
- 快照版本历史：每次保存前自动快照到
.history/<id>/（分层保留：1 小时内每版 / 当天每小时 / 7 天内每天，单笔记 20 版上限 + 全局 50MB LRU）；详情区「历史」面板列出版本（时间/字节数）、点开只读预览、一键恢复——恢复前自动为当前版本落快照，恢复本身可撤销（再退回去即可）
- 面板 UI v2：两栏布局——左侧笔记树（置顶 / 文件夹 / 未分类主题分组，「主题过滤」跨文件夹全局生效），右侧通栏编辑器（标题 + 主题/标签/类型/状态 meta chips 直改）；SVG 图标库 + DSH 设计 token 配色，明暗主题自适应；快速记录卡片 v2（选区预览 + 复制/记录/取消，复制成功即关卡片）
- 中英文双语界面：设置卡「语言」项切换 中文 / English（localStorage 持久化，默认中文，切换即全量重渲染）；运行时扁平字典
src/i18n/zh.js + en.js（双端共源）+ t(key, {name}) 插值，缺 key 回退中文原文、永不裸 key；check 常驻 i18n 守卫（zh/en key 集一致 + 重复 key 防线 + 字典↔代码引用双向覆盖 + 产物字典抽查），报告尾部输出「未覆盖清单」提示内联中文残留（只提示不阻塞）；host 端 RPC 报错文案本期保持中文
- 上下文注入（双角色）：详情区「⚡ 关闭 / 约定 / 资料」三态分段控件（独立字段
inject + injectRole，不依赖标签）——约定=须遵守的行为规则（每回合注入「用户约定」桶），资料=事实性补充信息（「参考资料」桶，与当前任务相关时按需取用）；范围浮层多选——默认注入所有会话，勾选具体会话则仅限这些会话（会话按工作区分组、显示会话名，自动排除子 agent 与已归档会话）
- 目录段（0.4.3 起与资料桶合并为单一目录段；0.4.4-E 起唯挂载行源）：整篇注入之外的轻量清单 = 挂载行（注入索引 §1 的
- [[id]] 何时查我：…）——资料 = 显式挂载，未挂载笔记不再平铺进段（0.4.4-E 移除「目录段补充未挂载条目」：全库平铺与显式挂载模型冲突，catalogEnabled 总开关/预览徽标/catalog 遥测埋点一并退役，存量 settings.json 残留键为惰性死键不迁移；recall 字段随之失去消费方，保留 dormant 读写兼容）；挂载行随约定注入同段进系统提示（order 130，原 order 131 独立块已撤销）并附规划轻推 + 挂载 note_get 引导；注入预算压缩时挂载行内部从最旧整条省略；尾部附日志计数提示行与价值信号行（0.4.3 验收修复⑥：（本周引用：id×次数｜零引用候选：id｜截至 HH:MM），账本快照内存现算、与目录行同版本原子快照，无快照静默省略）
- 注入管理面板：设置卡片「注入管理 → 管理…」——全库注入三态总览（约定 N / 资料 M / 未注入 K 统计 chips 点击即过滤 + 250ms 防抖搜索）；行内三态 segmented 直改（语义与详情区三态分段控件完全一致；0.4.3 验收修复⑪起单行切「资料」档先弹 whenToUse 编辑框——LLM 草稿预填、确认才落索引行并把笔记翻为资料档、取消零副作用，详情页三态同此链路）；多选批量「设为约定 / 设为资料 / 关闭注入」（confirm 确认，单条失败计数不中断；批量「设为资料」维持静默落缺省挂载行 whenToUse=标题）；注入中在前（约定 > 资料），组内按更新时间降序；日志注入硬关（行内不渲染注入开关、静态标注「日志不参与注入」，批量不可选；host injectForcedOff 强制纠正双保险），敏感笔记行内提示注入自动脱敏，曾注入徽章展示粘性标记；挂载区统计行（0.4.3 验收修复⑥：挂载 N｜本周引用 Top｜零引用 M，复用 账本快照，点开见全量分通道召回率，无快照静默省略）
Agent 工具（3 个）
| 工具 | 作用 |
|---|
note_search | 自由文本 + tag / topic / kind / folder 过滤检索（folder 兼容文件夹 id 或精确名称，"" = 未分类；返回瘦身列表，正文用 note_get 取） |
note_get | 按 id 读完整正文 + 全部元数据（含派发历史） |
note_manage | 单一入口 CRUD + 整理 + 派发 + 移动：create / list / update / move / delete / restore / archive / dispatch |
note_manage { action: 'move', id, folder }：把笔记移入虚拟文件夹（folder 兼容文件夹 id 或精确名称，"" = 移出到未分类；找不到文件夹直接报错，不写悬空引用）。文件夹本身的新建/重命名/删除/排序由面板的 notes-folders RPC 管理。
note_manage 的 create / update 另支持 injectRole（'convention' / 'reference'，仅 inject: true 时有意义，缺省 convention）：convention = 须遵守的行为规则（「用户约定」桶），reference = 事实性补充信息（「参考资料」桶，agent 按需取用）；按 kind 推断的建议——decision/todo → convention，note/link/quote → reference。
note_manage 的 create / update 另支持 recall（布尔，默认 true）：已退役兼容字段（deprecated，0.4.5-A 写侧退役）——原控制目录索引注入，该功能已于 0.4.4-E 整体移除（目录段唯挂载行源）；入参仍接受、存量 front-matter 行照常解析（读写兼容，存量零迁移零删除），但新写不再落盘，对注入无任何效果（笔记永远可被 note_search 检索）。
note_manage { action: 'dispatch', id, targetSessionId? }：不传 targetSessionId 时返回当前活跃会话列表供选择，传了则把该待办注入目标会话并唤醒它开始工作。
数据位置
笔记是 ~/.dsh/notes/ 下的独立 Markdown 文件（YAML front-matter + 正文），纯本地、不上传；卸载插件不删数据。
~/.dsh/notes/
n-xxxxxxxx.md # 一条笔记 = 一个文件
n-xxxxxxxx.md.bak # 归档/覆盖时的备份
.history/ # 快照式版本历史（每次保存前自动快照上一版；详见「版本历史」）
n-xxxxxxxx/ # 按笔记分目录
2026-09-17T06-02-34.123Z.ab1.cd2.md # <UTC 时间戳>.<内容 hash>.md（纯文本，不压缩不加密）
assets/ # 图片资产（base64 文本落盘；正文以  相对路径引用；孤儿资产可用「设置 → 资产清理」清理）
folders.json # 虚拟文件夹清单 [{id, name, order}]（缺失/损坏自动兜底为空清单，不影响笔记主流程）
settings.json # 面板设置（LLM 模型选配、staleDays 时效阈值、injectBudgetChars 注入预算等；0.4.4-E 起 catalogEnabled 为惰性死键——功能已拆，存量不迁移）
perf-report.json # 面板性能遥测（可随时删除）
models/ # 语义检索向量模型 host 缓存（bge-small-zh-v1.5，约 23MB；首次启用时下载，可删——下次启用重新下载）
版本历史（快照式）：每次保存落盘前，host 自动把被替换的上一版快照进 .history/<笔记 id>/（与编辑器防抖对齐，一次真实保存 = 一份快照；无变化的重复保存按内容 hash 去重跳过）。保留策略：1 小时内每版全留 → 当天每小时 1 版 → 7 天内每天 1 版 → 超 7 天淘汰；单笔记最多 20 版；全库 .history 总预算 50MB（超限时跨笔记淘汰最旧快照）。回收站「彻底删除」会连带清空该笔记的整棵历史。历史是本地安全网：导出默认不含 .history（RPC notes-export 加 includeHistory: true 才连带），导入前自动备份恒含历史，导入合并仅对库内不存在的新笔记连带其历史（同 id 冲突跳过，两库历史不混杂）。
首次启动若检测到旧的开发版笔记目录（<repo>/notes/），会一次性复制缺失的文件到 ~/.dsh/notes（只复制、不删除，同名跳过）。
---
id: n-xxxxxxxx
title: 标题
topic: 主题 # LLM 自动识别
workspace: 工作区名 # 取会话 cwd 目录名
folder: "" # 虚拟文件夹 id（folders.json 清单内）；"" = 未分类
tags: tag1, tag2
kind: note # note/decision/todo/link/quote
status: active # active/pinned/resolved/superseded
inject: false # 是否注入系统提示（注入为上下文总开关）
injectRole: convention # 注入角色（仅 inject=true 时落盘/生效）：convention=约定·须遵守的行为规则 / reference=资料·事实性补充信息（agent 按需取用）；缺省 convention
injectTo: [] # 注入范围多选：[] = 所有会话（默认）/ [会话短id,...] = 仅限这些会话（存量 global/workspace 值按所有会话容错）
# （recall 行已退役：0.4.5-A 起不再写入；存量文件的 recall 行保留并照常解析，对注入无效果）
injectEver: false # 曾注入粘性标记（inject 曾置 true 即永久 true，只读）
sensitive: false # 敏感笔记（注入时正文按行打码脱敏）
useCount: 0 # 使用遥测（note_get 命中计数，60s 防抖落盘）
createdAt: ISO-8601
updatedAt: ISO-8601
sessionId: 来源会话
cwd: 来源工作目录
contractType: "" # 契约分型（"" = 普通笔记；dispatch-schedule = 定时派发约定；其余值系统内部流程管理）
schedule: {...} # 定时派发声明 + 机器状态（仅 contractType=dispatch-schedule 落盘，JSON 单行：{at|every, target, action, enabled, anchor?, dow?, lastFiredAt?, lastRun?, lastError?, runLog?}；anchor='HH:MM' 锚定本地时刻，dow=0-6 每周星期几；runLog=执行记录伴生笔记 id 软链（「执行记录 · @标题」，kind=log + 执行记录夹），派发成功即懒创建回写）
dispatches: [] # 派发历史（会话/要求/时间/done）
mergedFrom: [] # 归档合并来源 id
archivedAt: ""
deleted: "false" # 软删除标记
---
正文 Markdown
向后兼容：旧文件缺 inject/kind/status/injectRole/injectTo/folder/recall/sensitive/injectEver/useCount 字段时自动兜底（folder 缺省为未分类；recall 缺省为 true；injectRole 缺省为 convention；sensitive/injectEver 缺省 false；useCount 缺省 0，存量笔记零迁移；无 inject 时回退按 tags 含 convention 判定）。folder 指向清单外 id（如 folders.json 损坏或被外部改乱）时按未分类对待，删除文件夹会主动把其下笔记的 folder 清空回退未分类。
权限与实现
- Host 端：
inject: ['fs', 'sandboxPolicy']，只需笔记读写与写策略；llm / agents / systemPrompt / sessionPersistence / workspaceRegistry 均按需 ctx.get + 存在性守卫，缺失时对应功能降级（如无 LLM 时不自动分类）
- Client 端：
inject: ['slots']，注册 4 个 Slot 注入点——会话头部按钮（conversation.session.header.actions，order 40）、悬浮气泡（shell.overlay 199）、浮窗面板（200）、选区捕获（201）
- 通信：client 经
fetch('/dsh-notes') POST {method, args} 调用 host 的 RPC（笔记 CRUD / 搜索 / 归档 / 派发 / 导入导出 / 设置 / notes-folders 文件夹管理等方法 + 1 个存活探测 notes-ping）；样式经 notes-css 下发并注入 <style>，零外部运行时依赖；宿主另注册 GET /dsh-notes-app 页面路由，直接返回包内 app.html（text/html，非 GET/HEAD 405）
源码与开发
- 仓库：https://github.com/PPawnsir/dsh-notes-plugin
- 本包（
packages/dsh-notes-plugin/）由开发版模块化源码生成：index.mjs 为 host 端 ESM 静态包（src/host/** 按 manifest.dist.js 拼接写盘），lib/client.js 由 scripts/build-dist.cjs 从 src/client/** 拼接产物机械转换（带转换计数断言，漏改即中止），app.html 为 /dsh-notes-app 全窗口笔记页（src/app/** 拼接产物；与 design/notes-ui-v2.html 原型共享同一套 UI/交互，仅数据层不同）
- 回归测试（内存 mock，不触碰真实笔记）：
node scripts/build-dist.cjs # 改完 src/**（client/host/app/shared/styles）后一次性刷新四产物：lib/client.js + lib/styles.css + app.html + index.mjs
node --check packages/dsh-notes-plugin/index.mjs
node --check packages/dsh-notes-plugin/lib/client.js
node check.js # 1295 例回归（host 全链路 + 静态包 + client UI 面 + 虚拟文件夹 + 目录段挂载行 + 导入导出 + 半独立页 + 双模式编辑器 + 敏感脱敏 + 注入增强 + 遥测/双链 + 快照式历史引擎 + 模块化结构契约 + README.en 双语 + i18n 守卫 + 笔记网络守卫/README 哲学节）
npm run e2e # 浏览器 e2e（Playwright + 内置 mock host，69 用例 641 断言：加载/CRUD/搜索/注入管理与挂载弹框/日志同权/拖拽/回收站/导出/机器档翻档案/文件夹sys/hidden显隐/休眠派发/执行记录跳转/整理弹卡/机密横幅与读取记录等；需 chromium 或系统 Chrome）
详见 DEVELOPMENT.md。
发版
发布走 npm Trusted Publishing（OIDC）：不需要 npm token，不需要 OTP，本地不需要登录 npm。.github/workflows/release.yml 拿 GitHub Actions 的 OIDC 身份直接换发布权限，并附 SLSA provenance。
触发条件是「发布一个 GitHub Release」，不是推 tag。
只 git push --tags 不会发布任何东西——tag 会静静躺在那里。
# 1. 改 packages/dsh-notes-plugin/package.json 的 version，提交
git commit -am "release: vX.Y.Z——<摘要>"
# 2. 打 tag 并推送（这一步还没有发布）
git tag vX.Y.Z && git push origin main --tags
# 3. 创建 GitHub Release —— 这一步才真正触发发布
gh release create vX.Y.Z --title "vX.Y.Z — <标题>" --notes-file <notes.md>
workflow 随后自动跑 build → check → npm publish --provenance，并校验 tag 与 packages/dsh-notes-plugin/package.json 版本一致（不一致直接失败）。
几个已知的坑：
- registry 有复制延迟：workflow 显示
✅ Published 后，npm view 仍可能有 1–5 分钟看到旧版本（Fastly max-age=300）。以 workflow 日志为准，不要据此判断失败而重试——重试只会撞上 E409「版本已存在」。
- 别去折腾 npm token：npm 正在系统性废止 bypass-2FA 的 granular token。
release.yml 不依赖任何 token，发布失败请先看 workflow 日志，而不是 token 配置。
- 一次性前置配置：首次使用前在 npmjs.com 上把包
dsh-notes-plugin 的 Settings → Publishing access → Trusted Publishers 里 Add Trusted Publisher（Provider: GitHub Actions · Owner: PPawnsir · Repository: dsh-notes-plugin · Workflow: release.yml）。未配置前 workflow 会在 publish 步失败，属预期。
- 兜底路径：
.github/workflows/publish.yml（NPM_TOKEN）保留为手动兜底（Run workflow 触发），仅在 OIDC 不可用时使用。
License
MIT
