project-node-memory 0.0.0-stage → 1.0.1

package/lib/host/routes.js

@@ -0,0 +1,304 @@
+/**
+ * routes —— 给浏览器面板用的只读 HTTP API（前缀 /nodekb/api）。
+ *
+ * 宿主侧与客户端唯一允许的通信方式：插件自己注册的路由。
+ * 全部只读；写操作走 write/edit 工具改 md，不需要这里开写接口。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { render_node, render_subtree, toc_tree, node_info, resolve_path } from '../engine/render.js'
+import { search, formatSearch } from '../engine/search.js'
+import { diag } from '../engine/diag.js'
+import { extract_refs } from '../engine/parse.js'
+import { renameFileNode, formatRename } from '../engine/rename.js'
+import { openLibrary, knownLibraries } from './runtime.js'
+import { promptState } from './prompt.js'
+import { skillState } from './skill.js'
+import { toolState } from './tools.js'
+import { discoverLibraries } from '../engine/registry.js'
+
+const PREFIX = '/nodekb/api'
+
+function send(res, code, body, type = 'application/json; charset=utf-8') {
+  const payload = typeof body === 'string' ? body : JSON.stringify(body)
+  res.writeHead(code, {
+    'content-type': type,
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(payload),
+  })
+  res.end(payload)
+}
+
+/** 从 source（`path#L12` / `path#L1-L30`）里取出源文件与行范围 */
+export function parseSource(source) {
+  const s = String(source || '')
+  const hash = s.lastIndexOf('#')
+  if (hash < 0) return null
+  const file = s.slice(0, hash)
+  const m = /^L(\d+)(?:-L(\d+))?$/.exec(s.slice(hash + 1))
+  if (!file || !m) return null
+  const start = Number(m[1])
+  const end = m[2] ? Number(m[2]) : start
+  return { file, start, end }
+}
+
+// 路由只能注册一次（同类前缀重名会被 webServer 拒掉），但代码会被反复重载。
+// 中间这一跳让"第一个注册成功的路由"始终把请求转给"最新装载的处理器"，
+// 这样升级插件不需要重启 DSH 也能换上新逻辑。
+const LIVE_HANDLER = Symbol.for('project-node-memory.live-handler.v1')
+// 改名前装过旧版（行 id dsh-nodekb）时，旧 route 的闭包还在用的旧符号。
+// 两边同时写，旧 route 才能把请求转给新版处理器 —— 改名的升级不需要重启。
+const LIVE_HANDLER_OLD = Symbol.for('dsh-nodekb.live-handler.v1')
+
+// 最近一次浏览器半边的自证（GET /nodekb/api/client-report）
+let CLIENT_REPORT = null
+
+export function registerRoutes(ctx, config) {
+  const handler = async (req, res) => {
+    let url
+    try {
+      url = new URL(req.url || '/', 'http://127.0.0.1')
+    } catch {
+      send(res, 400, { error: 'bad url' })
+      return
+    }
+    const q = url.searchParams
+    const kb = q.get('kb') || undefined
+    const libPath = q.get('lib') || undefined
+    // 面板没有会话上下文：允许前端显式给一个工作区（人指定一次，存在 localStorage）
+    const wsParam = q.get('ws') || undefined
+    const exec = wsParam ? { cwd: wsParam } : null
+    // 面板给 ws 是显式选择，别拿它覆盖 Agent 侧记住的默认工作区
+    const open = () => openLibrary(config, exec, { kb, lib: libPath, remember: !wsParam })
+
+    try {
+      if (url.pathname === `${PREFIX}/version`) {
+        // 探针用：确认活着的处理器是哪一版（插件热载后老路由可能还在）
+        let pkg = {}
+        try {
+          pkg = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
+        } catch {
+          /* 读不到就只报进程信息 */
+        }
+        send(res, 200, { name: pkg.name, version: pkg.version, node: process.version, pid: process.pid })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/libs`) {
+        send(res, 200, { libs: knownLibraries(config, exec) })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/prompt`) {
+        // 自证：提示词段落到底有没有被宿主接上（不接上，Agent 就永远优先用 write）
+        send(res, 200, promptState())
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/skill`) {
+        // 自证：随包技能（写法规范）有没有进宿主 skill 注册表
+        send(res, 200, skillState())
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/tools`) {
+        // 自证：宿主收下了几个 kb_* 工具（被拒收的那条会出现在 failed 里）
+        send(res, 200, toolState())
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/workspaces`) {
+        // 面板没有会话上下文，但宿主有 DSH 自己的 workspace 注册表：
+        // 把「这个 DSH 用过哪些项目目录」直接给面板，省掉让人手打路径。
+        const out = []
+        try {
+          const reg = typeof ctx.get === 'function' ? ctx.get('workspaceRegistry') : ctx.workspaceRegistry
+          const list = reg && typeof reg.list === 'function' ? reg.list() : []
+          for (const w of list || []) {
+            const dir = String(w.path || '')
+            if (!dir) continue
+            let found = 0
+            try {
+              found = discoverLibraries(dir).length
+            } catch {
+              found = 0
+            }
+            out.push({
+              id: String(w.id || ''),
+              title: String(w.title || ''),
+              path: dir,
+              nodekb: found > 0,
+              libs: found,
+            })
+          }
+        } catch (e) {
+          send(res, 500, { error: String((e && e.message) || e), workspaces: [] })
+          return
+        }
+        send(res, 200, { workspaces: out })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/tree`) {
+        const lib = open()
+        send(res, 200, {
+          kb: lib.name,
+          base: lib.base,
+          nodekb: lib.nodekb,
+          problems: lib.problems,
+          nodeCount: lib.nodes.size,
+          tree: toc_tree(lib.nodes, 'root'),
+        })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/node`) {
+        const lib = open()
+        const target = q.get('tid') || 'root'
+        const mode = q.get('mode') || 'subtree'
+        const tid = resolve_path(lib.nodes, target)
+        if (tid === null) {
+          send(res, 404, { error: `未找到节点: ${target}`, kb: lib.name })
+          return
+        }
+        const node = lib.nodes.get(tid)
+        let text
+        if (mode === 'node') text = render_node(lib.nodes, tid)
+        else if (mode === 'raw') text = node.content
+        else text = render_subtree(lib.nodes, tid)
+        send(res, 200, {
+          kb: lib.name,
+          ...node_info(lib.nodes, tid),
+          kind: node.kind,
+          mode,
+          text,
+          children: [...lib.nodes.values()].filter((c) => c.parent_tid === tid).map((c) => c.tid),
+        })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/source`) {
+        const lib = open()
+        const target = q.get('tid') || 'root'
+        const tid = resolve_path(lib.nodes, target)
+        if (tid === null) {
+          send(res, 404, { error: `未找到节点: ${target}` })
+          return
+        }
+        const src = parseSource(lib.nodes.get(tid).source)
+        if (!src) {
+          send(res, 404, { error: '该节点没有源文件（文件夹节点）' })
+          return
+        }
+        const all = fs.readFileSync(src.file, 'utf8').replace(/^+/, '').split(/\r\n|\n|\r/)
+        // 文件节点给整篇（源里 L1-Ln），段落节点给该行起的一段窗口
+        const from = src.start - 1
+        const to = Math.min(all.length, src.end > src.start ? src.end : src.start + 60)
+        send(res, 200, {
+          kb: lib.name,
+          path: src.file,
+          offset: src.start,
+          totalLines: all.length,
+          lines: all.slice(from, to).map((textLine, i) => ({ number: from + i + 1, text: textLine })),
+        })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/search`) {
+        const lib = open()
+        const query = q.get('q') || ''
+        const res0 = search(lib.nodes, query, {
+          type: q.get('type') || undefined,
+          limit: Number(q.get('limit') || 20),
+          offset: Number(q.get('offset') || 0),
+        })
+        send(res, 200, { kb: lib.name, ...res0, text: formatSearch(query, res0) })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/diag`) {
+        const lib = open()
+        const { report } = diag(lib.nodes, { problems: lib.problems, libRoot: lib.nodekb })
+        send(res, 200, { kb: lib.name, ...report })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/backlinks`) {
+        const lib = open()
+        const target = q.get('tid') || ''
+        const tid = resolve_path(lib.nodes, target)
+        if (tid === null) {
+          send(res, 404, { error: `未找到节点: ${target}` })
+          return
+        }
+        const rows = []
+        for (const node of lib.nodes.values()) {
+          if (node.tid !== tid && extract_refs(node.content).includes(tid)) {
+            rows.push({ tid: node.tid, title: node.title, type: node.type, source: node.source })
+          }
+        }
+        send(res, 200, { kb: lib.name, target: tid, backlinks: rows })
+        return
+      }
+
+      // 客户端自证通道：浏览器半边 POST 自己的加载状态，人/Agent 用 GET 读。
+      if (url.pathname === `${PREFIX}/client-report`) {
+        if (req.method === 'POST') {
+          let body = ''
+          for await (const chunk of req) body += chunk
+          try {
+            CLIENT_REPORT = JSON.parse(body || '{}')
+          } catch {
+            CLIENT_REPORT = { unparsable: String(body).slice(0, 2000) }
+          }
+          CLIENT_REPORT = { ...CLIENT_REPORT, at: new Date().toISOString() }
+          send(res, 200, { ok: true })
+          return
+        }
+        send(res, 200, { report: CLIENT_REPORT })
+        return
+      }
+
+      if (url.pathname === `${PREFIX}/rename`) {
+        const lib = open()
+        const report = renameFileNode(lib, q.get('target') || '', q.get('new_name') || '', {
+          dryRun: q.get('dry_run') === '1' || q.get('dry_run') === 'true',
+        })
+        send(res, 200, { kb: lib.name, ...report, text: formatRename(report) })
+        return
+      }
+
+      send(res, 404, { error: `未知端点: ${url.pathname}` })
+    } catch (e) {
+      send(res, 400, { error: e && e.message ? e.message : String(e) })
+    }
+  }
+
+  // 让已注册的那条 route 转发到本次装载的处理器
+  globalThis[LIVE_HANDLER] = handler
+  globalThis[LIVE_HANDLER_OLD] = handler
+  const spec = {
+    kind: 'prefix',
+    path: PREFIX,
+    handler: (req, res) => {
+      const live = globalThis[LIVE_HANDLER] || globalThis[LIVE_HANDLER_OLD]
+      return live ? live(req, res) : send(res, 503, { error: 'project-node-memory 未就绪' })
+    },
+  }
+  try {
+    return ctx.webServer.register(spec)
+  } catch (e) {
+    // 升级插件时旧进程里的 route 还没释放，会撞 "duplicate prefix route"。
+    // 这不该让整行激活失败（工具仍然可用）；上面的 LIVE_HANDLER 已保证旧 route 也会走到新逻辑。
+    if (/duplicate|already registered|conflict/i.test(String((e && e.message) || e))) {
+      console.warn(`[project-node-memory] 路由 ${PREFIX} 已由更早的实例注册，本次沿用（请求已转发到最新处理器）。`)
+      return () => {
+        if (globalThis[LIVE_HANDLER] === handler) delete globalThis[LIVE_HANDLER]
+      }
+    }
+    throw e
+  }
+}
+
+export { PREFIX }

package/lib/host/runtime.js

@@ -0,0 +1,108 @@
+/**
+ * runtime —— 库的打开与缓存（工具的共用底层）。
+ *
+ * 缓存键是 .nodekb 的绝对路径，有效性靠「全库 md 的 mtime/size 签名」判断：
+ * 编辑任何一个 md 都会让签名变化，所以不需要 fs.watch（也就没有 watcher 丢事件的问题）。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { parse_library } from '../engine/mdlib.js'
+import { resolveLibrary, listLibraries } from '../engine/registry.js'
+
+const CACHE = new Map() // nodekb -> { sig, nodes, problems }
+const MAX_CACHE = 8
+
+// 面板没有会话上下文，只能靠人指定工作区（ws 参数）。
+// 但 Agent 调 kb_* 工具时是带着工作区的——把那一次记下来，
+// 面板就能「跟着 Agent 走」，不必每次手填目录。
+let LAST_WORKSPACE = ''
+
+export function rememberWorkspace(ws) {
+  if (typeof ws === 'string' && ws) LAST_WORKSPACE = path.resolve(ws)
+}
+
+export function lastWorkspace() {
+  return LAST_WORKSPACE
+}
+
+function signature(nodekb) {
+  let count = 0
+  let maxM = 0
+  let size = 0
+  const walk = (d) => {
+    let entries
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue // 与 parse_library 一致：跳过点目录/点文件
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) {
+        walk(p)
+      } else if (e.name.endsWith('.md')) {
+        try {
+          const st = fs.statSync(p)
+          count += 1
+          size += st.size
+          if (st.mtimeMs > maxM) maxM = st.mtimeMs
+        } catch {
+          /* 竞态删除：忽略 */
+        }
+      }
+    }
+  }
+  walk(nodekb)
+  return `${count}:${size}:${maxM}`
+}
+
+/** 取会话工作区：配置优先 → exec 上下文 → 进程 cwd */
+export function workspaceOf(config, exec) {
+  const configured = config && typeof config.workspace === 'string' ? config.workspace : ''
+  if (configured) return path.resolve(configured)
+  const env = process.env.DSH_NODEKB_WORKSPACE
+  if (env) return path.resolve(env)
+  const e = exec && typeof exec === 'object' ? exec : {}
+  const candidates = [e.workspace, e.cwd, e.session && e.session.workspace, e.session && e.session.cwd]
+  for (const c of candidates) if (typeof c === 'string' && c) return path.resolve(c)
+  if (LAST_WORKSPACE) return LAST_WORKSPACE
+  return process.cwd()
+}
+
+/**
+ * 打开一个库（带缓存）。
+ * @returns {{name:string, base:string, nodekb:string, nodes:Map, problems:string[], cached:boolean}}
+ */
+export function openLibrary(config, exec, { kb, lib, remember = true } = {}) {
+  const workspace = workspaceOf(config, exec)
+  // 只有「Agent 带着会话工作区」的调用才值得记下来；
+  // 面板用 ws 参数指定目录是显式选择，别拿它污染工具侧的默认工作区。
+  if (remember) rememberWorkspace(workspace)
+  const resolved = resolveLibrary({ kb, lib, workspace, config })
+  const sig = signature(resolved.nodekb)
+  const hit = CACHE.get(resolved.nodekb)
+  if (hit && hit.sig === sig) {
+    return { ...resolved, nodes: hit.nodes, problems: hit.problems, cached: true }
+  }
+  const problems = []
+  const nodes = parse_library(resolved.nodekb, problems)
+  CACHE.set(resolved.nodekb, { sig, nodes, problems })
+  if (CACHE.size > MAX_CACHE) CACHE.delete(CACHE.keys().next().value)
+  return { ...resolved, nodes, problems, cached: false }
+}
+
+export function knownLibraries(config, exec) {
+  return listLibraries({ workspace: workspaceOf(config, exec), config })
+}
+
+export function libraryHint(config, exec) {
+  try {
+    const rows = knownLibraries(config, exec)
+    if (!rows.length) return '当前没有可用库。在工作区（或已注册的技能目录）下建 .nodekb/ 并放入 md 文件即可。'
+    return `可用库: ${rows.map((r) => `${r.name}${r.exists ? '' : '(路径不存在)'}`).join('、')}`
+  } catch {
+    return ''
+  }
+}

package/lib/host/skill.js

@@ -0,0 +1,160 @@
+/**
+ * skill —— 随包分发一条「怎么写这个知识库」的技能。
+ *
+ * 为什么要做：系统提示词那段只能点到为止（常驻 token 有预算），而「文件怎么分、
+ * TID 怎么起、先读什么再写什么」这种规范篇幅不小、又不是每一轮都需要。skill 正好
+ * 是「按需加载、不用时不占提示词预算」的容器。
+ *
+ * 为什么不是把 SKILL.md 拷进用户的 $DSH_HOME/skills：那样能生效，但会在用户家目录
+ * 留下插件无权回收的文件（升级残留、卸载残留），而且需要该目录可写。宿主的 skills
+ * 服务提供 `register()`，把技能注册在内存里——随包版本走、禁用即撤回、零写入。
+ *
+ * 技能注册是**可选服务**，所以走动态注入：服务不在时插件照常起来（工具、面板、
+ * 提示词段落都不受影响）。
+ */
+
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+/** 必须是 kebab-case（宿主 skill 注册表按这个名字做唯一键） */
+export const SKILL_NAME = 'project-node-memory-guide'
+export const SKILL_SOURCE = 'project-node-memory'
+
+export const DEFAULT_SKILL_DESCRIPTION =
+  '用 .nodekb/ + kb_* 工具沉淀项目长期知识时的写法规范：什么时候该写、文件怎么分、TID 怎么起、先读什么再写什么。准备手写 docs/*.md 之前先读这一条。'
+
+/** 随包 SKILL.md 的位置：lib/host/ 上两级就是包根，skills/ 是它的兄弟目录。 */
+function skillFileCandidates() {
+  return [new URL('../../skills/project-node-memory-guide/SKILL.md', import.meta.url)]
+}
+
+/** 读随包 SKILL.md；读不到返回 undefined（不抛）。 */
+export function readBundledSkillText() {
+  for (const url of skillFileCandidates()) {
+    try {
+      return fs.readFileSync(fileURLToPath(url), 'utf8')
+    } catch {
+      /* 试下一个候选 */
+    }
+  }
+  return undefined
+}
+
+/**
+ * 拆出 YAML front matter。
+ * 只认简单 `key: value`（够用即可，不引依赖）；值两端的引号会剥掉。
+ */
+export function splitFrontMatter(text) {
+  const src = String(text ?? '').replace(/^\uFEFF/, '')
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(src)
+  if (!m) return { meta: {}, body: src }
+  const meta = {}
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line.trim())
+    if (!kv) continue
+    let v = kv[2].trim()
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1)
+    meta[kv[1]] = v
+  }
+  return { meta, body: src.slice(m[0].length) }
+}
+
+/** 最近一次注册结果（给 /nodekb/api/skill 自证用） */
+const STATE = { registered: false, reason: 'not-run', name: SKILL_NAME, chars: 0 }
+
+export function skillState() {
+  return { ...STATE }
+}
+
+/**
+ * 把随包 SKILL.md 注册成宿主内存里的 skill。
+ * @returns {() => void} disposer（未接上 skills 服务时是空函数）
+ */
+export function registerSkill(ctx, config) {
+  const c = (config && config.skill) || {}
+  if (c.enabled === false) {
+    Object.assign(STATE, { registered: false, reason: 'disabled-by-config', chars: 0 })
+    return () => {}
+  }
+
+  const raw = typeof c.text === 'string' && c.text.trim() ? c.text : readBundledSkillText()
+  if (typeof raw !== 'string' || !raw.trim()) {
+    Object.assign(STATE, { registered: false, reason: 'missing-skill-file', chars: 0 })
+    console.warn('[project-node-memory] 随包 SKILL.md 缺失，技能不注册（工具与面板不受影响）')
+    return () => {}
+  }
+
+  const { meta, body } = splitFrontMatter(raw)
+  const name = typeof meta.name === 'string' && meta.name ? meta.name : SKILL_NAME
+  const description =
+    (typeof c.description === 'string' && c.description.trim()) ||
+    (typeof meta.description === 'string' && meta.description.trim()) ||
+    DEFAULT_SKILL_DESCRIPTION
+  const content = body.trim()
+  const skill = {
+    name,
+    description,
+    content,
+    source: SKILL_SOURCE,
+    // 模型和用户都能调：/skill 命令与目录都要看到它
+    invocation: { modelInvocable: true, userInvocable: true },
+  }
+
+  const attach = (svc) => {
+    if (!svc || typeof svc.register !== 'function') {
+      Object.assign(STATE, { registered: false, reason: 'no-skills-service', chars: 0 })
+      return null
+    }
+    try {
+      const dispose = svc.register(skill)
+      Object.assign(STATE, { registered: true, reason: 'ok', name, chars: content.length })
+      return () => {
+        Object.assign(STATE, { registered: false, reason: 'disposed', chars: 0 })
+        if (typeof dispose === 'function') dispose()
+      }
+    } catch (e) {
+      Object.assign(STATE, { registered: false, reason: 'error: ' + (e && e.message), chars: 0 })
+      console.warn('[project-node-memory] 技能注册失败:', e && e.message)
+      return null
+    }
+  }
+
+  // 首选：动态注入（skills 服务可能晚于本插件就绪）
+  if (typeof ctx.inject === 'function') {
+    let off = null
+    try {
+      const effect = ctx.inject(['skills'], (child) => {
+        off = attach(child && child.skills)
+        return off || undefined
+      })
+      return () => {
+        try {
+          if (typeof effect === 'function') effect()
+          else if (effect && typeof effect.dispose === 'function') effect.dispose()
+        } catch {
+          /* 卸载期忽略 */
+        }
+        if (off) off()
+      }
+    } catch (e) {
+      Object.assign(STATE, { registered: false, reason: 'inject-error: ' + (e && e.message), chars: 0 })
+      return () => {}
+    }
+  }
+
+  // 退路：直接取
+  let svc = null
+  try {
+    svc = ctx.skills || (typeof ctx.get === 'function' ? ctx.get('skills') : null)
+  } catch {
+    svc = null
+  }
+  if (!svc) {
+    Object.assign(STATE, { registered: false, reason: 'no-skills-service', chars: 0 })
+    return () => {}
+  }
+  const off = attach(svc)
+  return () => {
+    if (off) off()
+  }
+}