dsh-notes-plugin 0.1.0

package/index.mjs

@@ -0,0 +1,1149 @@
+/* global harness */
+// dsh-notes — host 端（ESM 静态包，发布版）
+//
+// 本文件是 bootstrap 开发版 host-impl.js 的**迁移**（不是重写）：apply 体内的功能逻辑逐段保留
+// （19 个 RPC + 3 个工具 + 约定注入 + 派发 + LLM 分类 + 缓存/归档/软删除 + 性能遥测）。
+// 与开发版的三点结构性差异：
+//   1. 形式：`return { inject, apply }`（被 new Function 执行）→ ESM `export name/inject/apply`
+//      （package.json 已声明 "type": "module"、"main": "./index.mjs"）
+//   2. 路径：PLUGIN_DIR/notes → ~/.dsh/notes（os.homedir()/.dsh/notes）。开发版目录仅保留两处用途：
+//      (a) 一次性数据迁移源；(b) styles.css / client-impl.js 等开发资产的回退读取路径。
+//   3. RPC/工具注册：主通道仍是全局 Builtin `harness`（`harness.handle` / `harness.defineTool` /
+//      `harness.registerTool`，与 host-impl.js 的 `function handle(name,fn){ return harness.handle(...) }`
+//      和 `harness.defineTool(def)` + `harness.registerTool(ctx, tool)` 姿势一致，原样保留）。
+//      额外的兜底：若某部署没有 harness（例如真实 Cordis row 里没有沙箱注入的 Builtin），则同一批
+//      handler 退到 `ctx.webServer.register({kind:'exact', path:'/dsh-notes'})`、工具退到 `ctx.tools.register`
+//      （已发布范例 task-board-plugin/packages/dsh-agent-board/index.mjs 用的就是这条服务路径）。
+//      两条通道互斥（工具不会重复注册）；RPC 表始终维护，供 webServer 路由消费。
+import os from 'node:os'
+import path from 'node:path'
+import fsNode from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-notes-plugin'
+// 硬依赖：fs（笔记读写）+ sandboxPolicy（写策略）+ webServer（静态包 RPC 路由）+ tools（静态包工具注册）。
+// 注意：harness 是动态插件的全局 Builtin，静态包里不存在（PACKAGING.md）——静态包必须 inject webServer/tools 走 ctx 服务通道。
+export const inject = ['fs', 'sandboxPolicy', 'webServer', 'tools']
+
+// ---- 路径锚点（模块级常量，import 时求值，无副作用）----
+const PKG_DIR = path.dirname(fileURLToPath(import.meta.url))     // packages/dsh-notes
+const NOTES_ROOT = path.join(os.homedir(), '.dsh', 'notes')      // 发布版存储根
+// 开发版目录：只用于 (a) 首次启动的一次性数据迁移 (b) 开发资产回退读取。发布环境不存在这些文件时静默跳过。
+const LEGACY_PLUGIN_DIR = 'D:\\deepseek-work\\dsh-notes-plugin'
+const LEGACY_NOTES_DIR = path.join(LEGACY_PLUGIN_DIR, 'notes')
+// 样式/源码候选路径：包内 lib/styles.css 优先（P3 会把 styles.css 放那里），再包根，最后开发版回退
+const CSS_CANDIDATES = [
+  path.join(PKG_DIR, 'lib', 'styles.css'),
+  path.join(PKG_DIR, 'styles.css'),
+  path.join(LEGACY_PLUGIN_DIR, 'styles.css'),
+]
+const RPC_PATH = '/dsh-notes'
+
+// 零外部依赖：link: 安装的包从真实路径解析，裸 import '@deepseek-ai/dsh-tools' 会 ERR_MODULE_NOT_FOUND。
+// defineTool 本体只是 校验+包装 出 {name, description, parameters, output, execute} 普通对象，
+// 这里内联等价实现（与 task-board index.mjs 相同）；parameters 已是完整 JSON Schema，原样透传。
+function defineTool(options) {
+  var userExecute = options.execute
+  var userRender = options.output && options.output.render
+  return {
+    name: options.name,
+    description: options.description,
+    parameters: options.parameters,
+    output: {
+      schema: options.output.schema,
+      render: userRender ? function (args, value) { return userRender(args, value) } : undefined,
+    },
+    execute: function (args, exec) { return userExecute(args, exec) },
+  }
+}
+
+export function apply(ctx) {
+    const fs = ctx.fs
+    const sp = ctx.sandboxPolicy
+    const tools = ctx.tools
+    const webServer = ctx.webServer
+    const agents = ctx.get('agents')
+    const llm = ctx.get('llm')
+    const adm = ctx.get('agentDefaultModel')
+    const systemPrompt = ctx.get('systemPrompt')
+    const sessionPersistence = ctx.get('sessionPersistence')
+    const workspaceRegistry = ctx.get('workspaceRegistry')
+    const sessionTitle = ctx.get('sessionTitle')
+    const sessionQuery = ctx.get('sessionQuery')
+    const NOTES_DIR = NOTES_ROOT
+    const disposers = []
+    // 动态沙箱 Builtin：harness 是「dynamic Host half」的符号（cordis-host-runner 用 node:vm 注入），
+    // 静态包（真实 Cordis row）里通常不存在；存在时作为兼容通道使用（见 RPC 桥 / regTool 回退）。
+    const harnessRef = typeof harness !== 'undefined' ? harness : undefined
+
+    function genId() {
+      return 'n-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6)
+    }
+
+    function basename(p) {
+      if (!p) return ''
+      const s = String(p).replace(/[\\/]+$/, '')
+      const parts = s.split(/[\\/]/)
+      return parts[parts.length - 1] || s
+    }
+
+    function shortSid(sid) { return sid ? String(sid).replace(/^session-/, '').slice(0, 8) : '' }
+
+    // dispatches 派发历史：对象数组，front-matter 里以 JSON 字符串存储
+    function parseDispatches(s) {
+      if (!s) return []
+      try { const d = JSON.parse(s); return Array.isArray(d) ? d : [] } catch (e) { return [] }
+    }
+
+    function escYaml(s) {
+      s = String(s == null ? '' : s)
+      if (/[":#\[\]{}&,*?|<>=!%@\n]/.test(s)) {
+        return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n') + '"'
+      }
+      return s
+    }
+
+    function buildFM(m) {
+      return '---\n' +
+        'id: ' + escYaml(m.id) + '\n' +
+        'title: ' + escYaml(m.title) + '\n' +
+        'topic: ' + escYaml(m.topic || '') + '\n' +
+        'workspace: ' + escYaml(m.workspace || '') + '\n' +
+        'tags: ' + (m.tags || []).map(escYaml).join(', ') + '\n' +
+        'kind: ' + escYaml(m.kind || 'note') + '\n' +
+        'status: ' + escYaml(m.status || 'active') + '\n' +
+        'inject: ' + escYaml(m.inject ? 'true' : 'false') + '\n' +
+        'injectTo: ' + (m.injectTo || []).map(escYaml).join(', ') + '\n' +
+        'createdAt: ' + escYaml(m.createdAt) + '\n' +
+        'updatedAt: ' + escYaml(m.updatedAt) + '\n' +
+        'sessionId: ' + escYaml(m.sessionId) + '\n' +
+        'cwd: ' + escYaml(m.cwd) + '\n' +
+        'mergedFrom: ' + (m.mergedFrom || []).map(escYaml).join(', ') + '\n' +
+        'dispatches: ' + escYaml(JSON.stringify(m.dispatches || [])) + '\n' +
+        'archivedAt: ' + escYaml(m.archivedAt || '') + '\n' +
+        'deleted: ' + escYaml(m.deleted || 'false') + '\n' +
+        '---\n\n'
+    }
+
+    function parseFM(content) {
+      const meta = {}
+      let body = content
+      const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/)
+      if (m) {
+        body = m[2] || ''
+        for (const line of m[1].split(/\r?\n/)) {
+          const idx = line.indexOf(':')
+          if (idx < 0) continue
+          const key = line.slice(0, idx).trim()
+          let val = line.slice(idx + 1).trim()
+          if (val.charAt(0) === '"' && val.charAt(val.length - 1) === '"') {
+            val = val.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\').replace(/\\n/g, '\n')
+          }
+          meta[key] = (key === 'tags' || key === 'mergedFrom' || key === 'injectTo')
+            ? (val ? val.split(',').map(s => s.trim()).filter(Boolean) : [])
+            : val
+        }
+      }
+      return { meta, body }
+    }
+
+    function sessCtx() {
+      const sc = { sessionId: '', cwd: '' }
+      try {
+        if (agents) {
+          const a = agents.currentInitiator()
+          if (a) {
+            sc.sessionId = a.sessionId || (a.session && a.session.id) || ''
+            sc.cwd = (a.session && a.session.header && a.session.header.cwd) || ''
+          }
+        }
+      } catch (e) {}
+      return sc
+    }
+
+    function getPolicy() {
+      try {
+        if (sp && sp.resolve) {
+          return sp.resolve({ mode: 'danger-full-access' })
+        }
+      } catch (e) {}
+      return undefined
+    }
+
+    // 三段式标题：工作区 · 会话 · 主题
+    function buildQuickTitle(sc, topic) {
+      const ws = basename(sc.cwd)
+      const sess = sc.sessionId ? sc.sessionId.replace(/^session-/, '').slice(0, 8) : ''
+      return [ws, sess, topic].filter(Boolean).join(' · ') || topic || '未分类'
+    }
+
+    async function classifyTopic(text) {
+      if (!llm || !adm) return '未分类'
+      try {
+        const sel = adm.currentSelection()
+        if (!sel || !sel.provider || !sel.model) return '未分类'
+        const preset = ['需求', '设计', '开发', '调试', '运维', '调研', '其他']
+        const prompt = '你是一个笔记主题分类器。预设主题：' + preset.join('、') + '。请优先从预设主题中选择最匹配的一个；如果内容明显不属于任何预设主题，可输出一个新的简短主题（2-6个汉字）。只输出主题名本身，不要解释、标点或换行：\n\n' + text
+        let out = ''
+        for await (const chunk of llm.stream({
+          provider: sel.provider,
+          model: sel.model,
+          messages: [{
+            id: 'topic-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
+            role: 'user',
+            content: [{ type: 'text', text: prompt }],
+            source: { kind: 'user' }
+          }],
+          system: '你是一个笔记主题分类器，把用户内容归纳成极简主题。',
+          temperature: 0
+        })) {
+          if (chunk && chunk.type === 'text-delta') out += chunk.text
+          if (chunk && chunk.type === 'finish') break
+        }
+        const topic = out.trim().replace(/^["'「」『』]+|["'「」『』]+$/g, '')
+        return topic || '未分类'
+      } catch (e) {
+        console.error('notes: classifyTopic failed', e)
+        return '未分类'
+      }
+    }
+
+    // ---- 缓存层：解析结果按 id 常驻内存；本插件所有写入同步缓存，外部新增文件在 list 时懒加载 ----
+    const KINDS = ['note', 'decision', 'todo', 'link', 'quote']
+    const STATUSES = ['active', 'pinned', 'resolved', 'superseded']
+    const cache = new Map()
+
+    function noteFromParsed(id, p) {
+      const tags = p.meta.tags || []
+      // inject：显式 true/false 优先；旧数据（无 inject 字段）回退到 tags 含 convention（向后兼容）
+      const inject = p.meta.inject === 'true' ? true : (p.meta.inject === 'false' ? false : tags.indexOf('convention') >= 0)
+      // injectTo：数组（parseFM 已按 , 拆分）；旧数据若是字符串也兜底成数组
+      let injectTo = []
+      if (Array.isArray(p.meta.injectTo)) injectTo = p.meta.injectTo
+      else if (p.meta.injectTo) injectTo = String(p.meta.injectTo).split(',').map(s => s.trim()).filter(Boolean)
+      return {
+        id: p.meta.id || id,
+        title: p.meta.title || 'Untitled',
+        topic: p.meta.topic || '未分类',
+        workspace: p.meta.workspace || '',
+        tags: tags,
+        kind: p.meta.kind || 'note',
+        status: p.meta.status || 'active',
+        inject: inject,
+        injectTo: injectTo,
+        createdAt: p.meta.createdAt || '',
+        updatedAt: p.meta.updatedAt || '',
+        sessionId: p.meta.sessionId || '',
+        cwd: p.meta.cwd || '',
+        mergedFrom: p.meta.mergedFrom || [],
+        dispatches: parseDispatches(p.meta.dispatches),
+        archivedAt: p.meta.archivedAt || '',
+        deleted: p.meta.deleted === 'true',
+        body: p.body || ''
+      }
+    }
+
+    function noteFile(id) { return path.join(NOTES_ROOT, id + '.md') }
+
+    async function readNoteFile(id) {
+      perfStats.diskReads++
+      const ft = await fs.resolve(noteFile(id))
+      const c = await fs.readText(ft)
+      const note = noteFromParsed(id, parseFM(c))
+      cache.set(note.id, note)
+      return note
+    }
+
+    async function loadNote(id) {
+      const hit = cache.get(id)
+      if (hit) { perfStats.cacheReads++; return hit }
+      return readNoteFile(id)
+    }
+
+    async function persistNote(n) {
+      perfStats.diskWrites++
+      const meta = {
+        id: n.id, title: n.title, topic: n.topic, workspace: n.workspace,
+        tags: n.tags || [], kind: n.kind || 'note', status: n.status || 'active',
+        inject: n.inject === true, injectTo: n.injectTo || [],
+        createdAt: n.createdAt, updatedAt: n.updatedAt,
+        sessionId: n.sessionId, cwd: n.cwd, mergedFrom: n.mergedFrom || [],
+        dispatches: n.dispatches || [],
+        archivedAt: n.archivedAt || '', deleted: n.deleted ? 'true' : 'false'
+      }
+      const content = buildFM(meta) + (n.body || '')
+      const ft = await fs.resolve(noteFile(n.id))
+      await fs.writeText(ft, content, undefined, undefined, getPolicy())
+      cache.set(n.id, Object.assign({}, n))
+    }
+
+    // 列表/RPC 瘦身：不带 body，正文编辑走 notes-get 按需加载
+    function slim(n) {
+      return {
+        id: n.id, title: n.title, topic: n.topic, workspace: n.workspace,
+        tags: n.tags, kind: n.kind || 'note', status: n.status || 'active',
+        inject: n.inject === true, injectTo: n.injectTo || [],
+        createdAt: n.createdAt, updatedAt: n.updatedAt,
+        sessionId: n.sessionId, cwd: n.cwd, mergedFrom: n.mergedFrom,
+        dispatches: n.dispatches || [],
+        archivedAt: n.archivedAt, preview: String(n.body || '').slice(0, 200)
+      }
+    }
+
+    async function _create(title, body, tags, topic, extra) {
+      const id = genId()
+      const now = new Date().toISOString()
+      const sc = sessCtx()
+      const ex = extra || {}
+      const note = {
+        id, title: title || 'Untitled', topic: topic || '未分类',
+        workspace: ex.workspace || basename(sc.cwd),
+        tags: tags || [],
+        kind: ex.kind || 'note',
+        status: ex.status || 'active',
+        inject: ex.inject === true,
+        injectTo: ex.injectTo || [],
+        createdAt: ex.createdAt || now, updatedAt: ex.updatedAt || now,
+        sessionId: ex.sessionId !== undefined ? ex.sessionId : sc.sessionId,
+        cwd: ex.cwd || sc.cwd,
+        mergedFrom: ex.mergedFrom || [],
+        dispatches: ex.dispatches || [],
+        archivedAt: ex.archivedAt || '',
+        deleted: false,
+        body: body || ''
+      }
+      await persistNote(note)
+      return { id, topic: note.topic, title: note.title, kind: note.kind, status: note.status }
+    }
+
+    async function _list(tag, kind) {
+      try {
+        // 首次启动的一次性迁移（开发版 notes → ~/.dsh/notes）可能与首个 RPC 竞态，这里等一下
+        try { await migrationDone } catch (e) {}
+        const dirTarget = await fs.resolve(NOTES_DIR)
+        const info = await fs.stat(dirTarget)
+        if (!info) return []
+        const entries = await fs.listDir(dirTarget)
+        const notes = []
+        for (const entry of entries) {
+          if (!entry.name || !entry.name.endsWith('.md')) continue
+          const id = entry.name.replace(/\.md$/, '')
+          try {
+            const note = await loadNote(id)
+            if (note.deleted) continue
+            if (tag && (note.tags || []).indexOf(tag) < 0) continue
+            if (kind && note.kind !== kind) continue
+            notes.push(note)
+          } catch (e) { console.error('notes: read failed', entry.name, e) }
+        }
+        // 置顶（pinned）优先，其次按更新时间降序
+        notes.sort((a, b) => {
+          const pa = a.status === 'pinned' ? 1 : 0
+          const pb = b.status === 'pinned' ? 1 : 0
+          if (pa !== pb) return pb - pa
+          return (b.updatedAt || '').localeCompare(a.updatedAt || '')
+        })
+        return notes
+      } catch (e) {
+        console.error('notes: list error', e)
+        return []
+      }
+    }
+
+    async function _get(id) {
+      const note = await loadNote(id)
+      if (note.deleted) throw new Error('Note has been deleted')
+      return Object.assign({}, note)
+    }
+
+    async function _update(id, title, body, tags, topic, kind, status, inject, injectTo) {
+      const note = Object.assign({}, await loadNote(id))
+      if (note.deleted) throw new Error('Note has been deleted')
+      if (title !== undefined) note.title = title
+      if (topic !== undefined) note.topic = topic
+      if (tags !== undefined) note.tags = tags
+      if (kind !== undefined) note.kind = kind
+      if (status !== undefined) note.status = status
+      if (inject !== undefined) note.inject = inject === true
+      if (injectTo !== undefined) note.injectTo = injectTo
+      if (body !== undefined) note.body = body
+      note.updatedAt = new Date().toISOString()
+      await persistNote(note)
+      return { id, kind: note.kind, status: note.status }
+    }
+
+    // 快速记录队列：串行化避免读-改-写竞态导致内容丢失
+    // 合并策略：同 session 且上一条速记在 10 分钟内更新过才合并，否则新建（避免过度合并）
+    // 主题分类异步执行：先落盘返回，分类完成后回填主题与标题，不阻塞交互
+    const MERGE_WINDOW_MS = 10 * 60 * 1000
+    let quickChain = Promise.resolve()
+    function _quickCapture(text, sessionId, cwd, kind) {
+      const run = quickChain.then(() => _quickCaptureInner(text, sessionId, cwd, kind))
+      quickChain = run.then((r) => {
+        if (!r || !r.id) return
+        perfStats.classify++
+        const ct0 = Date.now()
+        return classifyTopic(text).then(async (topic) => {
+          perfStats.classifyMs += Date.now() - ct0
+          try {
+            const newTitle = r.merged ? undefined : buildQuickTitle({ sessionId: r.sid, cwd: r.cwd }, topic)
+            await _update(r.id, newTitle, undefined, undefined, topic)
+          } catch (e) {}
+        }).catch(() => {})
+      }, () => {})
+      return run
+    }
+    async function _quickCaptureInner(text, sessionId, cwd, kind) {
+      const now = new Date().toISOString()
+      const sc = sessCtx()
+      const sid = sessionId || sc.sessionId
+      const cw = cwd || sc.cwd
+      if (sid) {
+        const all = await _list()
+        const existing = all.find(n => (n.tags || []).indexOf('quick') >= 0 && n.sessionId === sid)
+        const fresh = existing && existing.updatedAt && (Date.now() - new Date(existing.updatedAt).getTime()) < MERGE_WINDOW_MS
+        if (existing && fresh) {
+          const stamp = '## ' + now.slice(0, 10) + ' ' + now.slice(11, 16) + '\n\n'
+          const newBody = String(existing.body || '').trim() + '\n\n' + stamp + text + '\n'
+          await _update(existing.id, undefined, newBody, undefined, undefined)
+          return { id: existing.id, topic: existing.topic, title: existing.title, kind: existing.kind, merged: true, sid: sid, cwd: cw }
+        }
+      }
+      const id = genId()
+      const title = buildQuickTitle({ sessionId: sid, cwd: cw }, '速记')
+      const note = {
+        id, title: title, topic: '分类中',
+        workspace: basename(cw),
+        tags: ['quick'],
+        kind: kind || 'note',
+        status: 'active',
+        createdAt: now, updatedAt: now,
+        sessionId: sid, cwd: cw,
+        mergedFrom: [], archivedAt: '',
+        deleted: false,
+        body: text + '\n'
+      }
+      await persistNote(note)
+      return { id, topic: '分类中', title: title, kind: note.kind, merged: false, sid: sid, cwd: cw }
+    }
+
+    // T3 指令式快速记录：从用户备注提取元数据（tags/titleHint/kind/inject）
+    // 复用 classifyTopic 的 llm.stream + adm.currentSelection 模式，temperature 0
+    // 解析容错：失败/不规范 → 返回 null（调用方按无备注处理，等价 notes-quick）
+    // 关键约束：绝不改写原文——LLM 只输出结构化 JSON，原文由调用方落盘
+    async function extractInstruction(text, note) {
+      if (!llm || !adm) return null
+      try {
+        const sel = adm.currentSelection()
+        if (!sel || !sel.provider || !sel.model) return null
+        const prompt = '给定选区原文和用户备注，从备注中提取笔记元数据。只输出严格 JSON，没提到的字段留空/默认，绝不改写原文。\n' +
+          '字段说明：\n' +
+          '- tags: 字符串数组，打标签（如备注"标记为重要 bug" → ["重要","bug"]）\n' +
+          '- titleHint: 字符串，标题/主题引导（如"这是关于登录的" → "登录"）\n' +
+          '- kind: 字符串，类型枚举 note/decision/todo/link/quote（如"这是待办" → todo）\n' +
+          '- inject: 布尔，是否设为约定（如"记住这个" → true）\n\n' +
+          '选区原文：\n' + text + '\n\n用户备注：\n' + note + '\n\n只输出 JSON：{"tags":[],"titleHint":"","kind":"note","inject":false}'
+        let out = ''
+        for await (const chunk of llm.stream({
+          provider: sel.provider,
+          model: sel.model,
+          messages: [{
+            id: 'instruct-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
+            role: 'user',
+            content: [{ type: 'text', text: prompt }],
+            source: { kind: 'user' }
+          }],
+          system: '你是一个笔记元数据提取器。从用户备注中提取结构化字段，输出严格 JSON，绝不改写原文。',
+          temperature: 0
+        })) {
+          if (chunk && chunk.type === 'text-delta') out += chunk.text
+          if (chunk && chunk.type === 'finish') break
+        }
+        // 容错解析：提取第一个 {...} 块；失败返回 null
+        const m = out.match(/\{[\s\S]*\}/)
+        if (!m) return null
+        const obj = JSON.parse(m[0])
+        const tags = Array.isArray(obj.tags) ? obj.tags.map(function (s) { return String(s).trim() }).filter(Boolean) : []
+        const titleHint = obj.titleHint ? String(obj.titleHint).trim() : ''
+        const kindRaw = String(obj.kind || '').trim().toLowerCase()
+        const kind = KINDS.indexOf(kindRaw) >= 0 ? kindRaw : 'note'
+        const inject = obj.inject === true
+        return { tags: tags, titleHint: titleHint, kind: kind, inject: inject }
+      } catch (e) {
+        console.error('notes: extractInstruction failed', e)
+        return null
+      }
+    }
+
+    // T3 指令式快速记录：选区原文 + LLM 提取元数据 → 新建独立笔记
+    // 备注为空 / LLM 不可用 / 解析失败 → 等价 notes-quick（走合并逻辑，原文不变）
+    // 备注非空且 LLM 成功 → 新建独立笔记（不走合并窗口），body=选区原文（不变），应用提取的元数据
+    async function _quickInstruct(text, note, sessionId, cwd) {
+      const noteTrim = String(note || '').trim()
+      // 备注为空 → 走现有逻辑（合并窗口，行为不变）
+      if (!noteTrim) {
+        const r = await _quickCapture(text, sessionId, cwd, 'quote')
+        return { ok: true, id: r.id, applied: { tags: [], kind: r.kind || 'note', inject: false }, merged: r.merged }
+      }
+      // 备注非空 → LLM 提取元数据
+      const meta = await extractInstruction(text, noteTrim)
+      if (!meta) {
+        // LLM 不可用 / 解析失败 → 等价 notes-quick（合并逻辑，原文不变）
+        const r = await _quickCapture(text, sessionId, cwd, 'quote')
+        return { ok: true, id: r.id, applied: { tags: [], kind: r.kind || 'note', inject: false }, merged: r.merged, fallback: true }
+      }
+      // 新建独立笔记（不走合并窗口），body=选区原文（不变）
+      const now = new Date().toISOString()
+      const sc = sessCtx()
+      const sid = sessionId || sc.sessionId
+      const cw = cwd || sc.cwd
+      const extraTags = meta.tags.filter(function (t) { return t !== 'quick' })
+      const tags = ['quick'].concat(extraTags)
+      const topic = meta.titleHint || '速记'
+      const title = buildQuickTitle({ sessionId: sid, cwd: cw }, topic)
+      const id = genId()
+      const noteObj = {
+        id: id, title: title, topic: topic, workspace: basename(cw),
+        tags: tags, kind: meta.kind, status: 'active', inject: meta.inject, injectTo: [],
+        createdAt: now, updatedAt: now, sessionId: sid, cwd: cw,
+        mergedFrom: [], archivedAt: '', deleted: false,
+        body: text + '\n'
+      }
+      await persistNote(noteObj)
+      // 无 titleHint 时异步分类回填主题/标题（不阻塞交互，复用 classifyTopic 模式）
+      if (!meta.titleHint) {
+        classifyTopic(text).then(async function (topic2) {
+          try {
+            const newTitle = buildQuickTitle({ sessionId: sid, cwd: cw }, topic2)
+            await _update(id, newTitle, undefined, undefined, topic2)
+          } catch (e) {}
+        }).catch(function () {})
+      }
+      return { ok: true, id: id, applied: { tags: meta.tags, kind: meta.kind, inject: meta.inject, titleHint: meta.titleHint } }
+    }
+
+    async function _delete(id) {
+      const note = Object.assign({}, await loadNote(id))
+      note.deleted = true
+      note.updatedAt = new Date().toISOString()
+      await persistNote(note)
+      return { id }
+    }
+
+    // 恢复软删除的笔记（撤销删除/撤销归档）
+    async function _restore(id) {
+      const note = Object.assign({}, await loadNote(id))
+      note.deleted = false
+      note.updatedAt = new Date().toISOString()
+      await persistNote(note)
+      return { id }
+    }
+
+    // 归档：快速记录按 session 合并；手动笔记按标签合并
+    async function _archive() {
+      const all = await _list()
+      const groups = new Map()
+      for (const n of all) {
+        const isQuick = (n.tags || []).indexOf('quick') >= 0
+        const key = isQuick
+          ? 'quick:' + (n.sessionId || 'none')
+          : 'manual:' + (n.tags || []).slice().sort().join(',')
+        if (!groups.has(key)) groups.set(key, [])
+        groups.get(key).push(n)
+      }
+      let merged = 0
+      const mergedIds = []
+      for (const members of groups.values()) {
+        if (members.length < 2) continue
+        members.sort((a, b) => (a.updatedAt || '').localeCompare(b.updatedAt || ''))
+        const now = new Date().toISOString()
+        const bodyParts = members.map(n => {
+          const d = (n.updatedAt || n.createdAt || '').slice(0, 10)
+          return '## ' + d + '\n\n' + String(n.body || '').trim() + '\n'
+        })
+        const body = bodyParts.join('\n')
+        const topic = members[members.length - 1].topic || members[0].topic || '未分类'
+        const last = members[members.length - 1]
+        const title = last.topic || members[0].title || '归档'
+        const r = await _create(title, body, members[0].tags || [], topic, {
+          workspace: last.workspace || '',
+          createdAt: members[0].createdAt || now,
+          updatedAt: now,
+          sessionId: last.sessionId || '',
+          cwd: last.cwd || '',
+          mergedFrom: members.map(n => n.id),
+          archivedAt: now
+        })
+        // 归档前先备份原笔记（.bak 后缀，_list 不会读到）
+        for (const n of members) {
+          try {
+            const src = await fs.resolve(noteFile(n.id))
+            const dst = await fs.resolve(noteFile(n.id) + '.bak')
+            const c = await fs.readText(src)
+            await fs.writeText(dst, c, undefined, undefined, getPolicy())
+          } catch (e) {}
+        }
+        for (const n of members) { await _delete(n.id) }
+        merged++
+        mergedIds.push(r.id)
+      }
+      return { merged, mergedIds }
+    }
+
+    // 派发目标会话列表（共享）：**未归档的主会话**（可继续对话，符合 DSH 交互逻辑），不只是当前 live。
+    // sessionPersistence.list() 返回 SessionPersistenceSnapshot[]（{header, revision, ...}），id/origin/cwd/createdAt 都在 header 里；兼容旧版直接返回 SessionHeader
+    function snapHeader(h) { return (h && h.header) ? h.header : h }
+    // 与左侧会话列表一致：sessionPersistence.list() 过滤子 agent + 已归档；名字 live 用 sessionTitle.get（最新 fold），非 live 用 persistence 最后 title。
+    async function _activeSessions() {
+      if (!workspaceRegistry || !workspaceRegistry.list) return []
+      // 已归档集合（workspaceRegistry.archivedSessionIds 是 registry 级归档集合）
+      const archivedSet = {}
+      try { const arch = workspaceRegistry.archivedSessionIds; if (Array.isArray(arch)) { for (const id of arch) archivedSet[id] = true } } catch (e) {}
+      // 数据源：各工作区的 sessionIds（= 左侧会话列表显示的有效会话；已关闭/废弃的不在任何工作区里，自然排除）
+      const entries = []
+      const seen = {}
+      const wl = workspaceRegistry.list() || []
+      for (const w of wl) {
+        const wsTitle = (w && w.title) || basename((w && w.path) || '')
+        let sids = []
+        try { sids = w.sessionIds || [] } catch (e) {}
+        for (const sid of (sids || [])) {
+          if (!sid || seen[sid]) continue
+          seen[sid] = true
+          if (archivedSet[sid]) continue  // 已归档跳过
+          entries.push({ sid, wsTitle })
+        }
+      }
+      if (entries.length === 0) return []
+      // 批量读 title + header（origin/cwd/createdAt）：sessionQuery.readTitleSnapshots（live/persisted 都行，取代已删除的 inspect）
+      const metaMap = {}
+      if (sessionQuery && sessionQuery.readTitleSnapshots) {
+        try {
+          const results = await sessionQuery.readTitleSnapshots(entries.map(e => e.sid))
+          for (const r of (results || [])) {
+            if (r && r.status === 'fulfilled' && r.value) {
+              const hd = r.value.session || {}
+              metaMap[r.sessionId] = { title: (r.value.title && r.value.title.title) || '', cwd: hd.cwd || '', origin: hd.origin || '', createdAt: hd.createdAt }
+            }
+          }
+        } catch (e) {}
+      }
+      const out = []
+      for (const e of entries) {
+        const meta = metaMap[e.sid] || {}
+        if (meta.origin === 'subagent') continue  // 排除一次性子 agent
+        const liveAgent = agents && agents.get ? agents.get(e.sid) : undefined
+        const live = !!liveAgent
+        let title = meta.title || ''
+        // live 优先用 sessionTitle.get（最新 fold，含 fork 改名后的新名）
+        if (live && sessionTitle && sessionTitle.get && liveAgent.session) {
+          try { const snap = sessionTitle.get(liveAgent.session); if (snap && snap.title) title = snap.title } catch (e2) {}
+        }
+        // 无标题且非 live 的会话视为已关闭/废弃（从没生成标题，也不在运行），不在派发/注入列表显示
+        if (!title && !live) continue
+        out.push({ id: e.sid, short: shortSid(e.sid), name: title || (e.wsTitle + ' · ' + shortSid(e.sid)), cwd: meta.cwd || '', workspace: e.wsTitle, live: live, createdAt: meta.createdAt })
+      }
+      // 排序：live 在前，再按创建时间倒序
+      out.sort((a, b) => { if (a.live !== b.live) return a.live ? -1 : 1; return String(b.createdAt || '').localeCompare(String(a.createdAt || '')) })
+      return out
+    }
+
+    // 任务派发（共享）：主动注入上下文 + 触发对话——agent.send 一条消息到目标会话，
+    // source 标记为 { kind:'plugin', form:'recall' }（todo 作为"召回的上下文"，区别于用户指令/系统提示拼接），
+    // wakeup=true 保证触发该会话 agent 去获取并处理这条上下文（可见反应，不污染系统提示）。
+    // opts: { sessionId, sessionName, workspace, mode('existing'|'new'), instruction }
+    async function _dispatch(id, opts) {
+      const o = opts || {}
+      const note = await _get(id)
+      if (note.deleted) return { error: '笔记已删除' }
+      if (!o.sessionId) return { error: '缺少目标会话' }
+      const target = agents && agents.get ? agents.get(o.sessionId) : undefined
+      if (!target || typeof target.send !== 'function') return { error: '目标会话当前未打开，无法触发工作。请先打开它，或改用「新建会话」。', needOpen: true }
+      const instruction = String(o.instruction || '').trim()
+      const text = '【笔记插件 · 派发的待办上下文】\n\n【待办】' + (note.title || 'Untitled') + '\n' + String(note.body || note.title || '').trim() + (instruction ? '\n\n【派发方补充的要求】\n' + instruction : '') + '\n\n—— 以上是笔记插件派发给你的待办上下文（recall）。请获取此上下文并开始处理。'
+      const msg = {
+        id: 'note-dispatch-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
+        role: 'user',
+        content: [{ type: 'text', text: text }],
+        // form:'recall'：标记为"召回的上下文"而非用户指令；agent loop 照常处理（wakeup 触发），模型据 form 理解为参考资料
+        source: { kind: 'plugin', plugin: 'dsh-notes', form: 'recall' }
+      }
+      target.send(msg, 'next-turn', true)
+      // 派发历史：作为笔记属性记录（不改正文）
+      const rec = {
+        sessionId: o.sessionId,
+        sessionName: o.sessionName || shortSid(o.sessionId),
+        workspace: o.workspace || '',
+        mode: o.mode || 'existing',
+        instruction: instruction,
+        at: new Date().toISOString(),
+        done: false
+      }
+      note.dispatches = (note.dispatches || []).concat([rec])
+      note.updatedAt = new Date().toISOString()
+      await persistNote(note)
+      return { ok: true, id: note.id, sessionId: o.sessionId, sessionName: rec.sessionName, dispatch: rec }
+    }
+
+    // 标记一条派发待办为完成（停止注入目标会话的系统提示）
+    async function _dispatchDone(id, dispatchIndex) {
+      const note = await _get(id)
+      if (note.deleted) return { error: '笔记已删除' }
+      const ds = note.dispatches || []
+      const i = typeof dispatchIndex === 'number' ? dispatchIndex : -1
+      if (i < 0 || i >= ds.length) return { error: '无效的派发记录索引' }
+      ds[i] = Object.assign({}, ds[i], { done: true, doneAt: new Date().toISOString() })
+      note.dispatches = ds
+      note.updatedAt = new Date().toISOString()
+      await persistNote(note)
+      return { ok: true, id: note.id }
+    }
+
+    async function _search(query, tag, topic, kind) {
+      const all = await _list()
+      const q = query ? String(query).toLowerCase() : ''
+      return all.filter(n => {
+        if (tag && (n.tags || []).indexOf(tag) < 0) return false
+        if (topic && n.topic !== topic) return false
+        if (kind && n.kind !== kind) return false
+        if (q) {
+          const hay = ((n.title || '') + ' ' + (n.body || '') + ' ' + (n.topic || '') + ' ' + (n.tags || []).join(' ')).toLowerCase()
+          if (hay.indexOf(q) < 0) return false
+        }
+        return true
+      })
+    }
+
+    // T2.3 工作区约定：从常驻内存 cache 同步读取 convention 笔记，注入 agent 系统提示。
+    // text 是同步函数（systemPrompt 契约），故不能 await _list()，必须读 cache。
+    // 注入范围由约定笔记的 injectTo 字段决定（可选）：
+    // 是否注入：inject 布尔字段（noteFromParsed 已对旧数据回退到 convention 标签）。
+    // 注入范围 injectTo 是多选数组：
+    //   []（空）        → 默认当前工作区（向后兼容旧数据 injectTo=''）
+    //   含 'global'     → 全局注入（不限工作区）
+    //   含 'workspace'  → 当前工作区
+    //   含会话短 id     → 注入该会话（可多选多个会话）
+    function conventionText() {
+      const shortSid = (x) => x ? String(x).replace(/^session-/, '').slice(0, 8) : ''
+      try {
+        let cwd = ''
+        let sid = ''
+        const a = agents && agents.currentInitiator ? agents.currentInitiator() : undefined
+        if (a) {
+          cwd = (a.session && a.session.header && a.session.header.cwd) || ''
+          sid = a.sessionId || (a.session && a.session.id) || ''
+        }
+        const ws = basename(cwd)
+        const curSid = shortSid(sid)
+        const matches = []
+        for (const n of cache.values()) {
+          if (n.deleted) continue
+          if (n.inject !== true) continue
+          const targets = n.injectTo || []
+          let hit = false
+          if (targets.length === 0) {
+            // 默认：当前工作区（workspace 为空视为全局约定）
+            hit = !n.workspace || !ws || n.workspace === ws
+          } else {
+            for (const t of targets) {
+              if (t === 'global') { hit = true; break }
+              if (t === 'workspace') { if (!n.workspace || !ws || n.workspace === ws) { hit = true; break } }
+              else if (t === curSid) { hit = true; break }
+            }
+          }
+          if (hit) matches.push(n)
+        }
+        if (matches.length === 0) return ''
+        matches.sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''))
+        const blocks = matches.map(n => {
+          const src = shortSid(n.sessionId)
+          const srcLabel = src ? '（记录于会话 ' + src + '）' : '（来源会话未知）'
+          return '【' + (n.title || 'Untitled') + '】' + srcLabel + '\n' + String(n.body || '').trim()
+        }).join('\n\n')
+        const label = ws ? '工作区「' + ws + '」' : '全局'
+        const full = '以下是' + label + '已记录的约定（本地笔记，每条标注其记录会话；与当前任务无关时忽略）：\n\n' + blocks
+        return full.length > 4000 ? full.slice(0, 4000) + '\n\n（内容过长已截断）' : full
+      } catch (e) { return '' }
+    }
+
+    // ---- 性能遥测：RPC 计数/耗时 + 缓存命中 + client 推送快照，节流写盘供诊断 ----
+    const perfStats = { started: new Date().toISOString(), rpc: {}, rpcMs: {}, classify: 0, classifyMs: 0, cacheReads: 0, diskReads: 0, diskWrites: 0, client: null }
+    const PERF_PATH = path.join(NOTES_ROOT, 'perf-report.json')
+    let lastPerfWrite = 0
+    function writePerfReport() {
+      const t = Date.now()
+      if (t - lastPerfWrite < 10000) return
+      lastPerfWrite = t
+      ;(async () => {
+        try {
+          const ft = await fs.resolve(PERF_PATH)
+          await fs.writeText(ft, JSON.stringify({ writtenAt: new Date().toISOString(), host: perfStats }, null, 2), undefined, undefined, getPolicy())
+        } catch (e) {}
+      })()
+    }
+
+    // ---- client ↔ host RPC ----
+    // 主通道：全局 Builtin `harness.handle`（原 host-impl.js 的 helper 姿势原样保留，只是补了 handler 表）。
+    // 兜底通道：harness 缺失时同一批 handler 由 ctx.webServer.register 的 exact 路由承载。
+    const handlers = {}
+    function handle(name, fn) {
+      const wrapped = async (args) => {
+        const t0 = Date.now()
+        try { return await fn(args) }
+        finally { perfStats.rpc[name] = (perfStats.rpc[name] || 0) + 1; perfStats.rpcMs[name] = (perfStats.rpcMs[name] || 0) + (Date.now() - t0); writePerfReport() }
+      }
+      handlers[name] = wrapped   // handler 表始终维护：webServer 兜底路由据此分发
+      if (harnessRef && typeof harnessRef.handle === 'function') return harnessRef.handle(name, wrapped)
+      return () => { delete handlers[name] }
+    }
+    disposers.push(handle('notes-perf', async (args) => { if (args && args.perf) perfStats.client = args.perf; return { ok: true } }))
+    disposers.push(handle('notes-list', async (args) => ({ notes: (await _list(args && args.tag, args && args.kind)).map(slim) })))
+    // 样式文件按需下发：避免 client 内嵌超长 CSS 字符串（包内 styles.css 优先，开发版目录回退）
+    disposers.push(handle('notes-css', async () => {
+      try {
+        for (const p of CSS_CANDIDATES) {
+          try { if (fsNode.existsSync(p)) return { css: fsNode.readFileSync(p, 'utf8') } } catch (e) {}
+        }
+        throw new Error('styles.css not found in: ' + CSS_CANDIDATES.join(' | '))
+      } catch (e) { return { error: String(e.message || e) } }
+    }))
+    // client 实现源码下发：开发版 bootstrap 壳通过它加载 client-impl.js（同理避免 define 传大字符串）。
+    // 发布版候选：开发版目录的 client-impl.js / host-impl.js，包内的 lib/client.js / index.mjs。
+    disposers.push(handle('notes-src', async (args) => {
+      try {
+        const which = args && args.which === 'client' ? 'client' : 'host'
+        const candidates = which === 'client'
+          ? [path.join(LEGACY_PLUGIN_DIR, 'client-impl.js'), path.join(PKG_DIR, 'lib', 'client.js')]
+          : [path.join(LEGACY_PLUGIN_DIR, 'host-impl.js'), path.join(PKG_DIR, 'index.mjs')]
+        for (const p of candidates) {
+          try { if (fsNode.existsSync(p)) return { src: fsNode.readFileSync(p, 'utf8') } } catch (e) {}
+        }
+        throw new Error(which + ' source not found in: ' + candidates.join(' | '))
+      } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-get', async (args) => {
+      try { const n = await _get(args.id); const s = slim(n); s.body = n.body; return { note: s } } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-create', async (args) => {
+      try { return await _create(args.title, args.body, args.tags, args.topic, { kind: args.kind, status: args.status, inject: args.inject, injectTo: args.injectTo }) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-update', async (args) => {
+      try { return await _update(args.id, args.title, args.body, args.tags, args.topic, args.kind, args.status, args.inject, args.injectTo) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-quick', async (args) => {
+      try { return await _quickCapture(args.text, args.sessionId, args.cwd, args.kind) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    // T3 指令式快速记录：备注非空时 LLM 提取 tags/titleHint/kind/inject，选区原文原样为 body，备注不进笔记
+    disposers.push(handle('notes-quick-instruct', async (args) => {
+      try { return await _quickInstruct(args.text, args.note, args.sessionId, args.cwd) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-delete', async (args) => {
+      try { return await _delete(args.id) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-restore', async (args) => {
+      try { return await _restore(args.id) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-archive', async () => {
+      try { return await _archive() } catch (e) { return { error: String(e.message || e) } }
+    }))
+    disposers.push(handle('notes-search', async (args) => {
+      try { return { notes: (await _search(args && args.query, args && args.tag, args && args.topic, args && args.kind)).map(slim) } } catch (e) { return { error: String(e.message || e) } }
+    }))
+    // T2.3 工作区约定自动注入：注册动态 prompt context（order 130，位于 policy/delegation 之后）
+    if (systemPrompt && typeof systemPrompt.context === 'function') {
+      disposers.push(systemPrompt.context({ name: 'notes:workspace-conventions', order: 130, text: () => conventionText() }))
+    }
+    // 调试 RPC：预览当前会话将注入的约定文本（E2E 验证用）
+    disposers.push(handle('notes-conventions', async () => ({ text: conventionText() || '' })))
+    // 会话列表（注入范围多选用）：与派发同源——工作区有效会话（排除已归档 + 子 agent），复用 _activeSessions
+    disposers.push(handle('notes-sessions', async () => {
+      try { return { sessions: await _activeSessions() } } catch (e) { return { sessions: [] } }
+    }))
+    // 活跃主会话列表（任务派发目标用）：agents.roots() 返回顶层 live agents（天然排除子 agent）
+    disposers.push(handle('notes-active-sessions', async () => {
+      try { return { sessions: await _activeSessions() } } catch (e) { return { sessions: [] } }
+    }))
+    // 工作区列表（派发对话框的"新建会话"下拉用）
+    disposers.push(handle('notes-workspaces', async () => {
+      try {
+        if (!workspaceRegistry || !workspaceRegistry.list) return { workspaces: [] }
+        const list = workspaceRegistry.list() || []
+        return { workspaces: list.map(w => ({ id: w.id, title: w.title || basename(w.path || ''), cwd: w.path || '' })) }
+      } catch (e) { return { workspaces: [] } }
+    }))
+    // 任务派发（client 面板用）：复用共享 _dispatch（系统提示注入形式，登记到 dispatches）
+    disposers.push(handle('notes-dispatch', async (args) => {
+      try { return await _dispatch(args.id, { sessionId: args.sessionId, sessionName: args.sessionName, workspace: args.workspace, mode: args.mode, instruction: args.instruction }) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    // 标记派发待办完成（停止注入目标会话系统提示）
+    disposers.push(handle('notes-dispatch-done', async (args) => {
+      try { return await _dispatchDone(args.id, args.dispatchIndex) } catch (e) { return { error: String(e.message || e) } }
+    }))
+    // POC 存活探测（P1 骨架遗留，包内 lib/client.js 的「笔记POC」按钮消费；非 host-impl 的 19 个 RPC 之一）
+    disposers.push(handle('notes-ping', async (args) => ({ ok: true, pong: Date.now(), echo: (args && typeof args === 'object') ? args : null })))
+
+    // ---- RPC 兜底路由（harness 缺失时生效；harness 存在时它是无副作用的第二传送门）----
+    function readBody(req, limit) {
+      return new Promise(function (resolve, reject) {
+        var chunks = [], size = 0
+        req.on('data', function (c) { size += c.length; if (size > limit) { reject(new Error('payload too large')); try { req.destroy() } catch (_) {} return }; chunks.push(c) })
+        req.on('end', function () { resolve(Buffer.concat(chunks).toString('utf8')) })
+        req.on('error', reject)
+      })
+    }
+    if (webServer && typeof webServer.register === 'function') {
+      disposers.push(webServer.register({
+        kind: 'exact',
+        path: RPC_PATH,
+        handler: async function (req, res) {
+          res.setHeader('Content-Type', 'application/json')
+          res.setHeader('Cache-Control', 'no-store')
+          if (req.method !== 'POST') { res.writeHead(405); res.end(JSON.stringify({ ok: false, message: 'method not allowed' })); return }
+          var payload = null
+          try { payload = JSON.parse(await readBody(req, 4 * 1024 * 1024)) } catch (e) { res.writeHead(400); res.end(JSON.stringify({ ok: false, message: 'bad request' })); return }
+          var fn = payload && handlers[payload.method]
+          if (!fn) { res.writeHead(404); res.end(JSON.stringify({ ok: false, message: 'unknown method: ' + payload.method })); return }
+          try { var out = await fn(payload.args); res.writeHead(200); res.end(JSON.stringify(out === undefined ? null : out)) } catch (e) { res.writeHead(500); res.end(JSON.stringify({ ok: false, message: String(e) })) }
+        },
+      }))
+    } else if (!(harnessRef && typeof harnessRef.handle === 'function')) {
+      console.error('notes: harness 与 ctx.webServer 均不可用，RPC 未注册')
+    }
+
+    // 工具注册：主通道 = 全局 Builtin harness.defineTool + harness.registerTool（原 host-impl.js 姿势原样保留）；
+    // 仅在 harness 缺失时回退到 ctx.tools.register（task-board 的服务路径）。两通道互斥，不会重复注册。
+    function regTool(def) {
+      if (harnessRef && typeof harnessRef.defineTool === 'function' && typeof harnessRef.registerTool === 'function') {
+        const tool = harnessRef.defineTool(def)
+        if (tool) { const d = harnessRef.registerTool(ctx, tool); if (typeof d === 'function') disposers.push(d) }
+        return
+      }
+      if (tools && typeof tools.register === 'function') {
+        const d = tools.register(defineTool(def))
+        if (typeof d === 'function') disposers.push(d)
+        return
+      }
+      console.error('notes: 无可用工具注册通道（harness / ctx.tools），工具未注册：' + (def && def.name))
+    }
+
+    const outSchema = { type: 'object', additionalProperties: true }
+    function mkRender() {
+      return (args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+    }
+
+    // ---- 工具层：合并 9 个细粒度工具为 3 个（note_search / note_get / note_manage）
+    // RPC 层保持 handler 不变（client panel 仍在用）；工具只面向 Agent，瘦身 schema。
+    regTool({
+      name: 'note_search',
+      description: 'Search local notes by free-text query (matches title/body/topic/tags), with optional tag, topic, and kind filters. Returns slim notes (no body) for fast triage — call note_get for the full body of a specific id.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Free-text query against title, body, topic, and tags. Omit to list all (optionally filtered by tag/topic/kind).' },
+          tag: { type: 'string', description: 'Optional tag filter (exact match)' },
+          topic: { type: 'string', description: 'Optional topic filter (exact match)' },
+          kind: { type: 'string', enum: KINDS, description: 'Optional kind filter: note/decision/todo/link/quote' },
+          limit: { type: 'number', description: 'Optional max results (default 50)' }
+        }
+      },
+      output: { schema: outSchema, render: mkRender() },
+      async execute(args) {
+        const all = await _search(args && args.query, args && args.tag, args && args.topic, args && args.kind)
+        const limit = (args && args.limit) || 50
+        return { count: all.length, notes: all.slice(0, limit).map(slim) }
+      }
+    })
+
+    regTool({
+      name: 'note_get',
+      description: 'Read the full body and metadata of a local note by id. Use after note_search to retrieve the body of an interesting result.',
+      parameters: {
+        type: 'object',
+        properties: { id: { type: 'string', description: 'Note id' } },
+        required: ['id']
+      },
+      output: { schema: outSchema, render: mkRender() },
+      async execute(args) {
+        try { const n = await _get(args.id); return { note: n } }
+        catch (e) { return { error: String(e.message || e) } }
+      }
+    })
+
+    regTool({
+      name: 'note_manage',
+      description: 'Single tool for create/list/update/delete/restore/archive. Pick an action and supply its required fields. The Agent should prefer this for any non-search CRUD: one tool means one decision point and one schema to learn.\n\n' +
+        'Fields kind (what it is) and status (its lifecycle) are orthogonal: kind ∈ note/decision/todo/link/quote (default note); status ∈ active/pinned/resolved/superseded (default active).\n' +
+        'inject (boolean) controls whether the note is injected into the system prompt as a workspace convention — an explicit field, NOT a tag. injectTo (string[]) is the injection scope, a multi-select list: [] or ["workspace"]=current workspace (default), ["global"]=all sessions, or session short-ids like ["99f2b674","7f8b49e6"]=those sessions.\n\n' +
+        'Actions:\n' +
+        '- create: { title, body, topic?, tags?, kind?, status?, inject?, injectTo?, sessionId?, cwd?, workspace? }\n' +
+        '- list: { tag?, topic?, kind? } (no id/title/body needed)\n' +
+        '- update: { id, title?, body?, topic?, tags?, kind?, status?, inject?, injectTo? }\n' +
+        '- delete: { id } (soft delete; restorable via restore)\n' +
+        '- restore: { id } (undo delete/archive)\n' +
+        '- archive: {} (no fields; merges quick-captures by session and manual notes by tag)\n' +
+        '- dispatch: { id, targetSessionId?, targetSessionName?, instruction? } (assemble the todo context plus your instruction into one user message and send it to a live session as a real task; the handoff is recorded in the note\'s dispatches property. Omit targetSessionId to list live sessions.)',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['create', 'list', 'update', 'delete', 'restore', 'archive', 'dispatch', 'debugws'], description: 'Action to perform' },
+          // create / update 字段
+          id: { type: 'string', description: 'Note id (required for update/delete/restore/dispatch)' },
+          title: { type: 'string', description: 'Title (create/update)' },
+          body: { type: 'string', description: 'Markdown body (create/update)' },
+          topic: { type: 'string', description: 'Topic (create/update; defaults to 未分类)' },
+          tags: { type: 'array', items: { type: 'string' }, description: 'Tags (create/update)' },
+          kind: { type: 'string', enum: KINDS, description: 'Kind (create/update): note/decision/todo/link/quote; default note' },
+          status: { type: 'string', enum: STATUSES, description: 'Status (create/update): active/pinned/resolved/superseded; default active' },
+          inject: { type: 'boolean', description: 'Inject as convention into system prompt (create/update); default false' },
+          injectTo: { type: 'array', items: { type: 'string' }, description: 'Injection scope multi-select (create/update): []/["workspace"]=current workspace (default), ["global"]=all, or session short-ids' },
+          // dispatch 字段
+          targetSessionId: { type: 'string', description: 'Dispatch target: a live session id (dispatch). Omit to list live sessions.' },
+          targetSessionName: { type: 'string', description: 'Dispatch target display name (dispatch, optional)' },
+          instruction: { type: 'string', description: 'Dispatch: your concrete instruction appended to the todo context (dispatch, optional)' },
+          // list 字段
+          tag: { type: 'string', description: 'Tag filter (list only)' },
+          // 高级（通常自动填充）
+          sessionId: { type: 'string', description: 'Session id (advanced; usually auto-filled)' },
+          cwd: { type: 'string', description: 'Working dir (advanced; usually auto-filled)' },
+          workspace: { type: 'string', description: 'Workspace name (advanced; usually auto-filled)' }
+        },
+        required: ['action']
+      },
+      output: { schema: outSchema, render: mkRender() },
+      async execute(args) {
+        const action = args && args.action
+        try {
+          if (action === 'create') {
+            if (!args.title || !args.body) return { error: 'note_manage.create 需要 title 和 body' }
+            const r = await _create(args.title, args.body, args.tags, args.topic, {
+              sessionId: args.sessionId, cwd: args.cwd, workspace: args.workspace,
+              kind: args.kind, status: args.status, inject: args.inject, injectTo: args.injectTo
+            })
+            return { action: 'create', id: r.id, topic: r.topic, kind: r.kind, status: r.status, message: 'Note created' }
+          }
+          if (action === 'list') {
+            const notes = await _list(args.tag, args.kind)
+            return { action: 'list', count: notes.length, notes: notes.map(slim) }
+          }
+          if (action === 'update') {
+            if (!args.id) return { error: 'note_manage.update 需要 id' }
+            const r = await _update(args.id, args.title, args.body, args.tags, args.topic, args.kind, args.status, args.inject, args.injectTo)
+            return { action: 'update', id: args.id, kind: r.kind, status: r.status, message: 'Note updated' }
+          }
+          if (action === 'delete') {
+            if (!args.id) return { error: 'note_manage.delete 需要 id' }
+            await _delete(args.id)
+            return { action: 'delete', id: args.id, message: 'Note deleted (soft)' }
+          }
+          if (action === 'restore') {
+            if (!args.id) return { error: 'note_manage.restore 需要 id' }
+            await _restore(args.id)
+            return { action: 'restore', id: args.id, message: 'Note restored' }
+          }
+          if (action === 'archive') {
+            const r = await _archive()
+            return { action: 'archive', merged: r.merged, mergedIds: r.mergedIds, message: 'Archived ' + r.merged + ' groups' }
+          }
+          if (action === 'debugws') {
+            // dump 指定会话（args.sessionId=short id）的 title 事件历史 + fold 结果
+            if (args.sessionId) {
+              const hs = await sessionPersistence.list()
+              const h = hs.map(snapHeader).find(x => x && shortSid(x.id) === args.sessionId)
+              if (!h) return { error: '会话不存在: ' + args.sessionId }
+              const insp = await sessionPersistence.inspect(h.id)
+              const evs = (insp && insp.events) || []
+              const titleEvs = []
+              for (const ev of evs) { if (ev && ev.type === 'session/title') titleEvs.push({ seq: ev.seq, title: ev.data && ev.data.title, source: ev.data && ev.data.source && ev.data.source.kind }) }
+              const live = agents && agents.get ? agents.get(h.id) : undefined
+              let stTitle = '(not live)'
+              if (live) { try { const s = sessionTitle.get(live.session); stTitle = s && s.title } catch (e) { stTitle = 'ERR' } }
+              return { action: 'debugws', sessionShort: args.sessionId, live: !!live, parent: h.parentSession ? shortSid(h.parentSession) : '', sessionTitleGet: stTitle, titleEvents: titleEvs }
+            }
+            // 默认：对比 工作区 sessionIds（左侧列表数据源）vs sessionPersistence.list()（所有持久化），确认"已关闭"会话的差异
+            const wl = (workspaceRegistry && workspaceRegistry.list) ? workspaceRegistry.list() : []
+            const archivedSet = {}
+            try { const arch = workspaceRegistry && workspaceRegistry.archivedSessionIds; if (Array.isArray(arch)) { for (const id of arch) archivedSet[id] = true } } catch (e) {}
+            const wsInfo = []
+            let totalInWs = 0, archivedInWs = 0
+            for (const w of wl) {
+              let sids = []
+              try { sids = w.sessionIds || [] } catch (e) {}
+              const cnt = Array.isArray(sids) ? sids.length : 0
+              totalInWs += cnt
+              const archCnt = Array.isArray(sids) ? sids.filter(s => archivedSet[s]).length : 0
+              archivedInWs += archCnt
+              wsInfo.push({ title: w.title, sessionCount: cnt, archivedInIt: archCnt })
+            }
+            let totalPersist = 0
+            try { const hs = await sessionPersistence.list(); totalPersist = hs.length } catch (e) {}
+            return {
+              action: 'debugws',
+              hasInspect: typeof sessionPersistence.inspect,
+              hasStat: typeof sessionPersistence.stat,
+              totalPersist: totalPersist,
+              totalInWorkspaces: totalInWs,
+              archivedInWorkspaces: archivedInWs,
+              archivedSetSize: Object.keys(archivedSet).length,
+              workspaces: wsInfo
+            }
+          }
+          if (action === 'dispatch') {
+            if (!args.id) return { error: 'note_manage.dispatch 需要 id' }
+            if (!args.targetSessionId) {
+              // 未指定目标：返回当前活跃主会话列表（含名字）供 agent 选择
+              const list = (await _activeSessions()).map(s => ({ sessionId: s.id, short: s.short, name: s.name, workspace: s.workspace }))
+              return { action: 'dispatch', needTarget: true, activeSessions: list, message: '请用 targetSessionId 指定目标活跃会话' }
+            }
+            const r = await _dispatch(args.id, { sessionId: args.targetSessionId, sessionName: args.targetSessionName, instruction: args.instruction, mode: 'existing' })
+            if (r.error) return { error: r.error }
+            return { action: 'dispatch', id: args.id, sessionId: r.sessionId, message: '已派发到「' + r.sessionName + '」' + (args.instruction ? '（含具体要求）' : '') }
+          }
+          return { error: 'note_manage: 未知 action：' + String(action) + '（期望 create/list/update/delete/restore/archive/dispatch）' }
+        } catch (e) { return { error: String(e.message || e) } }
+      }
+    })
+
+    // ---- 一次性数据迁移：开发版 D:\...\dsh-notes-plugin\notes → ~/.dsh/notes ----
+    // 触发：目标目录缺失该 .md 时逐文件复制（幂等、不覆盖已存在的目标文件、不删除源目录）。
+    // 走 ctx.fs 服务（而非 node:fs），保证写盘受 sandboxPolicy 管束，单测里也只落在内存 mock。
+    async function listMd(dir) {
+      try {
+        const target = await fs.resolve(dir)
+        const info = await fs.stat(target)
+        if (!info) return []
+        const entries = await fs.listDir(target)
+        return (entries || []).map(e => e && e.name).filter(n => n && /\.md$/i.test(n))
+      } catch (e) { return [] }
+    }
+    async function migrateLegacyNotes() {
+      try {
+        const legacyNames = await listMd(LEGACY_NOTES_DIR)
+        if (legacyNames.length === 0) return { migrated: 0, skipped: 'no-legacy-notes' }
+        const existing = {}
+        for (const n of await listMd(NOTES_ROOT)) existing[n] = true
+        let migrated = 0
+        for (const name of legacyNames) {
+          if (existing[name]) continue
+          try {
+            const src = await fs.resolve(path.join(LEGACY_NOTES_DIR, name))
+            const dst = await fs.resolve(path.join(NOTES_ROOT, name))
+            const content = await fs.readText(src)
+            await fs.writeText(dst, content, undefined, undefined, getPolicy())
+            migrated++
+          } catch (e) { console.error('notes: migrate failed', name, e) }
+        }
+        if (migrated > 0) console.log('notes: migrated ' + migrated + ' legacy note(s) → ' + NOTES_ROOT)
+        return { migrated: migrated, total: legacyNames.length }
+      } catch (e) {
+        console.error('notes: legacy migration error', e)
+        return { migrated: 0, error: String(e && e.message || e) }
+      }
+    }
+    let migrationDone = migrateLegacyNotes()
+
+    ctx.effect(() => () => {
+      for (const d of disposers) { try { d() } catch (e) {} }
+    })
+    // 发布版不再写 .last-host-load 开发心跳（静态包 import 即就绪，无需引导壳自检）
+    console.log('notes plugin: host ready (static pkg), notes dir =', NOTES_ROOT, ', llm =', !!llm, ', adm =', !!adm, ', rpc =', RPC_PATH)
+}