project-node-memory 0.0.0-stage → 1.0.1

package/lib/engine/scaffold.js

@@ -0,0 +1,123 @@
+/**
+ * scaffold —— 给一个目录铺出 .nodekb 骨架。
+ *
+ * 目的不是「生成一堆空文件」，而是把**约定**写进库里：后来的人（或 Agent）
+ * 打开 .nodekb/README.md 就知道该放哪、该多大、什么时候引用而不是复述。
+ * 幂等：已存在的文件一律跳过，绝不动用户已写的内容。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+const README = `# 本库约定（.nodekb）
+
+这是 **node project memory** 库：md 文件即数据库，没有索引库、没有向量、没有后台进程。
+删掉插件之后它仍然是普通 md。
+
+## 落位
+
+| 目录 | 放什么 | 判据 |
+|---|---|---|
+| \`doc/\` | 主题文档（一块一块的正文） | 会随版本演进、需要通读的解释性内容 |
+| \`facts/\` | 事实常量（一个节点一条） | 值本身即答案：版本号、公差、系数、路径、阈值 |
+| \`lessons/\` | 踩过的坑 | 换个人还会再踩，且「怎么发现的」比结论更值钱 |
+| \`todo/\` | 待办与计划 | 有明确完成条件 |
+| \`index/entry.md\` | 入口索引 | 只放指针（\`[[TID]]\`），不要复述正文 |
+
+## 三条硬规则
+
+1. **一个主题一个文件，取 < 4KB**。超过就拆成 \`doc/03-xxx.md\` 的多节，入口表加一行指针。
+2. **不要复述**。同一段数字/结论只写一次，其它地方用 \`[[TID]]\` 引用；改名时 \`kb_rename\` 会一起改写。
+3. **写之前先 \`kb_read mode=toc\` 看结构**，写完跑 \`kb_diag\`：悬空引用、引用位置型段落、循环、重复 TID 都会当场报出来。
+
+## 语法（就两条）
+
+- 文件即节点：\`doc/03-build.md\` → TID \`doc:03-build\`；\`## 3.1 标题\` → 子节点 \`doc:03-build:3.1\`
+- 显式节点：\`<node name="fact:abi" type="fact">\` … \`</node>\`，标签必须**独占一行**
+- 引用：\`[[doc:03-build:3.1]]\`（引用文件夹/文件展开整支，引用显式节点只展开它自己）
+`
+
+const ENTRY = `# 入口索引
+
+只放指针，不复述正文。每条一行：\`- [[TID]] 一句话说明\`。
+
+## 主题
+
+- [[doc:00-overview]] 项目概览与结构
+
+## 事实
+
+（\`facts/\` 下的节点）
+
+## 待办
+
+（\`todo/\` 下的条目）
+`
+
+const OVERVIEW = `# 项目概览
+
+## 这个项目是什么
+
+（一段话说清楚）
+
+## 目录与关键文件
+
+（只列「改动会牵连很多地方」的那几个）
+
+## 运行时与依赖
+
+（版本、入口、构建方式）
+`
+
+const LESSONS = `# 教训
+
+一条一个 \`<node name="lesson:xxx" type="lesson">\`，写「现象 → 为什么 → 怎么发现的」。
+比结论更值钱的是发现它的过程。
+`
+
+const TODO = `# 待办
+
+一条一个 \`<node name="todo:xxx" type="todo">\`，每条要有**明确的完成条件**。
+`
+
+const FACTS = `# 事实
+
+一个常量一条 \`<node name="fact:xxx" type="fact">\`：值 + 单位 + 出处 + 什么时候会变。
+值本身即答案的东西才放这里，解释性内容放 doc/。
+`
+
+const IGNORE = `{
+  "blocks": [],
+  "lines": []
+}
+`
+
+const SEEDS = [
+  ['README.md', README],
+  ['index/entry.md', ENTRY],
+  ['doc/00-overview.md', OVERVIEW],
+  ['facts/README.md', FACTS],
+  ['lessons/README.md', LESSONS],
+  ['todo/README.md', TODO],
+  ['diag_ignore.json', IGNORE],
+]
+
+/**
+ * @param {string} nodekbDir 目标 .nodekb 目录（不存在则创建）
+ * @returns {{nodekb:string, created:string[], skipped:string[]}}
+ */
+export function scaffold(nodekbDir) {
+  const created = []
+  const skipped = []
+  for (const [rel, content] of SEEDS) {
+    const abs = path.join(nodekbDir, rel)
+    if (fs.existsSync(abs)) {
+      skipped.push(rel)
+      continue
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true })
+    fs.writeFileSync(abs, content, 'utf8')
+    created.push(rel)
+  }
+  return { nodekb: nodekbDir, created, skipped }
+}

package/lib/engine/search.js

@@ -0,0 +1,138 @@
+/**
+ * search —— 实时检索（零持久化索引）：2-gram 词面倒排 + 多词加权 + LIKE 兜底。
+ *
+ * 与 Python 版 commands.cmd_search 逐行对齐（同一算法、同一排序、同一片段窗口），
+ * 差异只有一个：这里返回结构体，格式化由调用方（工具层/路由层）决定。
+ */
+
+import { render_node, TransclusionError } from './render.js'
+
+// 中文虚词 2-gram（检索分词时过滤）
+const STOP_GRAMS = new Set([
+  '怎么', '如何', '是否', '什么', '为什么', '一个', '这种', '那个', '这个',
+  '他们', '我们', '你们', '进行', '以及', '还是', '就是', '不是', '没有',
+  '可以', '需要', '问题', '情况', '时候', '地方', '东西', '因为', '所以',
+  '但是', '然后', '接着', '开始', '最后', '主要', '目前', '已经', '现在',
+  '等等', '如果', '那么', '不能', '不会', '应该', '可能',
+])
+
+const CJK_RUN = /[\u4e00-\u9fff]+/g
+const QUERY_TOKEN = /[\u4e00-\u9fff]+|[a-zA-Z0-9_.-]+/g
+const INDEX_TOKEN = /[\u4e00-\u9fff]+|[a-z0-9_]+/g
+
+/** query → 检索 term：非中文 token 原样；连续中文按 2-gram 拆分并过滤虚词 */
+export function searchTerms(query) {
+  const terms = []
+  for (const tok of String(query).match(QUERY_TOKEN) || []) {
+    if (/^[\u4e00-\u9fff]+$/.test(tok)) {
+      if (tok.length <= 2) {
+        if (!STOP_GRAMS.has(tok)) terms.push(tok)
+        continue
+      }
+      const seen = new Set()
+      for (let i = 0; i < tok.length - 1; i++) {
+        const g = tok.slice(i, i + 2)
+        if (!seen.has(g) && !STOP_GRAMS.has(g)) {
+          seen.add(g)
+          terms.push(g)
+        }
+        if (terms.length >= 10) break
+      }
+    } else {
+      terms.push(tok)
+    }
+  }
+  return [...new Set(terms)]
+}
+
+/** 位置型段落 TID 提升为稳定句柄：沿 parent 上溯到文件/显式节点/文件夹 */
+export function stableTid(nodes, tid) {
+  let cur = nodes.get(tid)
+  while (cur && cur.positional && cur.parent_tid != null && nodes.has(cur.parent_tid)) {
+    cur = nodes.get(cur.parent_tid)
+  }
+  return cur ? cur.tid : tid
+}
+
+/**
+ * 检索。
+ * @returns {{total:number,count:number,offset:number,hits:Array}}
+ */
+export function search(nodes, query, { type, limit = 10, offset = 0, snippet = 240 } = {}) {
+  const terms = searchTerms(query)
+  const index = new Map() // gram -> Set(tid)
+  for (const node of nodes.values()) {
+    const text = `${node.title}\n${node.content}\n${node.tid}`.toLowerCase()
+    const grams = new Set()
+    for (const tok of text.match(INDEX_TOKEN) || []) {
+      if (/^[\x00-\x7f]+$/.test(tok)) {
+        grams.add(tok)
+      } else {
+        for (let i = 0; i < tok.length - 1; i++) grams.add(tok.slice(i, i + 2))
+      }
+    }
+    for (const g of grams) {
+      let set = index.get(g)
+      if (!set) index.set(g, (set = new Set()))
+      set.add(node.tid)
+    }
+  }
+
+  const scores = new Map()
+  for (const g of terms) {
+    for (const tid of index.get(g) || []) scores.set(tid, (scores.get(tid) || 0) + 1)
+  }
+
+  let rows = []
+  if (scores.size) {
+    const ranked = [...scores.entries()].sort(
+      (a, b) => b[1] - a[1] || nodes.get(a[0]).content.length - nodes.get(b[0]).content.length,
+    )
+    for (const [tid] of ranked) {
+      const node = nodes.get(tid)
+      if (type && node.type !== type) continue
+      rows.push(node)
+    }
+  }
+  if (!rows.length) {
+    // LIKE 兜底：2-gram 未命中（生僻词/整句）时退回子串匹配
+    for (const node of nodes.values()) {
+      if (type && node.type !== type) continue
+      if (!node.title.includes(query) && !node.content.includes(query) && !node.tid.includes(query)) continue
+      rows.push(node)
+    }
+  }
+
+  const total = rows.length
+  const hits = []
+  for (const node of rows.slice(offset, offset + limit)) {
+    let text
+    try {
+      text = render_node(nodes, node.tid)
+    } catch (e) {
+      if (!(e instanceof TransclusionError)) throw e
+      text = node.content
+    }
+    let idx0 = terms.length ? text.indexOf(terms[0]) : -1
+    if (idx0 < 0) idx0 = 0
+    const stable = stableTid(nodes, node.tid)
+    const half = Math.max(40, Math.floor(snippet / 2))
+    hits.push({
+      // tid = 稳定句柄（位置型段落上溯到文件/显式节点），ref = 实际命中节点，positional 标记
+      tid: stable,
+      ref: node.tid,
+      positional: !!node.positional,
+      type: node.type,
+      title: node.title,
+      source: node.source,
+      snippet: text.slice(Math.max(0, idx0 - half), idx0 + half + 1), // 保留换行/缩进，不再压平
+    })
+  }
+  return { total, count: hits.length, offset, hits }
+}
+
+/** 命中列表 → 紧凑文本（模型侧默认读这个） */
+export function formatSearch(query, result) {
+  if (!result.hits.length) return `无匹配: ${query}`
+  return result.hits.map((h) => `${h.tid}  [${h.type}] ${h.title}\n    …${h.snippet}…`).join('\n')
+}

package/lib/engine/write.js

@@ -0,0 +1,140 @@
+/**
+ * write —— 往库里写内容（**带校验**）。
+ *
+ * 这是本项目对「Agent 直接用 write/edit 手搭知识库」的回答：
+ * 同样是写 md，但写之前校验 TID / 标签独占一行 / 路径在库内，写之后由调用方跑 diag。
+ * 手写没有任何一层会拦你，所以规则靠人记；这里的规则是代码。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { is_valid_tid } from './parse.js'
+
+const NODE_OPEN = /^<node\b[^>]*>$/m
+const NODE_TAG_LINE = /^\s*<\/?node\b[^>]*>\s*$/m
+
+function fail(msg) {
+  throw new Error(msg)
+}
+
+/** 库内相对路径 → 绝对路径；越界直接拒绝 */
+function absIn(nodekb, rel) {
+  const abs = path.resolve(nodekb, rel)
+  const root = path.resolve(nodekb)
+  const a = process.platform === 'win32' ? abs.toLowerCase() : abs
+  const r = process.platform === 'win32' ? root.toLowerCase() : root
+  if (a !== r && !a.startsWith(r + path.sep)) fail(`拒绝写库外路径: ${rel}`)
+  return abs
+}
+
+function readText(abs) {
+  try {
+    return fs.readFileSync(abs, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/** 校验一段将要落盘的内容：node 标签必须独占一行、名字必须是合法 TID */
+export function validateContent(text, where) {
+  const lines = text.split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    // 反引号/围栏里的示例不算真标签
+    if (/^\s*(```|~~~)/.test(line)) {
+      // 跳过围栏块
+      const fence = line.trim().slice(0, 3)
+      i++
+      while (i < lines.length && !lines[i].trim().startsWith(fence)) i++
+      continue
+    }
+    const m = /^\s*<node\b([^>]*)>\s*$/.exec(line)
+    if (m) {
+      const nameM = /\bname\s*=\s*"([^"]*)"/.exec(m[1]) || /\bname\s*=\s*'([^']*)'/.exec(m[1])
+      if (!nameM) fail(`${where}:${i + 1} <node> 缺少 name=`)
+      const tid = nameM[1]
+      if (!is_valid_tid(tid)) fail(`${where}:${i + 1} 非法 TID「${tid}」：只能用字母/数字/汉字与 : . _ -`)
+      continue
+    }
+    const inline = /<node\b|<\/node>/.test(line)
+    if (inline && !NODE_TAG_LINE.test(line)) {
+      fail(`${where}:${i + 1} <node> / </node> 必须独占一行（现在是「${line.trim().slice(0, 60)}」）`)
+    }
+  }
+  return true
+}
+
+/**
+ * @param {{nodekb:string, nodes:Map}} lib 已打开的库
+ * @param {{target:string, content:string, mode?:'append'|'replace'|'create'|'node'}} input
+ * @returns {{rel:string, abs:string, bytes:number, mode:string, created:boolean, tid?:string}}
+ */
+export function writeInto(lib, input) {
+  const target = String(input.target || '').trim()
+  const content = String(input.content ?? '')
+  let mode = String(input.mode || '').trim()
+  if (!target) fail('target 必填：库内相对路径（如 doc/03-build.md）或显式节点 TID（如 fact:abi）')
+  if (!content) fail('content 必填：本次要写入的内容')
+
+  const looksPath = /\.md$/i.test(target) || target.includes('/') || target.includes('\\')
+  const looksTid = !looksPath && target.includes(':')
+
+  if (looksTid) {
+    mode = mode || 'node'
+    if (mode !== 'node') fail(`target「${target}」是 TID，只能配 mode=node（或改用相对路径 + append/replace/create）`)
+    const node = lib.nodes.get(target)
+    if (!node) fail(`库里没有显式节点「${target}」。要新建文件请用相对路径（如 lessons/003.md）`)
+    if (node.kind !== 'node') {
+      fail(`「${target}」是 ${node.kind === 'section' ? '位置型段落（## 标题）' : node.kind} 节点，不是 <node> 块；改写 ## 段落请用相对路径 + mode=replace`)
+    }
+    const rel = node.source.split('#')[0]
+    const abs = path.isAbsolute(rel) ? path.normalize(rel) : absIn(lib.nodekb, rel)
+    if (!fs.existsSync(abs)) fail(`源文件不存在: ${abs}`)
+    const raw = fs.readFileSync(abs, 'utf8')
+    // 用 source 里的行号定位（`path#L12-L30`），在行上找 <node …> 与 </node>，替换两者之间
+    const hm = /#L(\d+)(?:-L(\d+))?/.exec(node.source || '')
+    if (!hm) fail('这个节点没有行号信息，无法就地改写；请用相对路径 + mode=replace 整篇重写')
+    const from = Number(hm[1]) - 1
+    const to = hm[2] ? Number(hm[2]) : from + 1
+    const lines = raw.split('\n')
+    let openAt = -1
+    let closeAt = -1
+    for (let i = from; i < Math.min(to + 1, lines.length); i++) {
+      if (openAt < 0 && /^\s*<node\b/.test(lines[i])) {
+        openAt = i
+        continue
+      }
+      if (openAt >= 0 && /^\s*<\/node>\s*$/.test(lines[i])) {
+        closeAt = i
+        break
+      }
+    }
+    if (openAt < 0 || closeAt < 0) fail(`无法在 ${rel} 的第 ${hm[1]}–${to} 行定位 <node> 块`)
+    validateContent(content, path.basename(abs))
+    const bodyLines = content.replace(/^\n+|\n+$/g, '').split('\n')
+    lines.splice(openAt + 1, closeAt - openAt - 1, ...bodyLines)
+    fs.writeFileSync(abs, lines.join('\n'), 'utf8')
+    return { rel, abs, bytes: Buffer.byteLength(content, 'utf8'), mode, created: false, tid: target }
+  }
+
+  mode = mode || 'append'
+  if (!['append', 'replace', 'create'].includes(mode)) fail(`未知 mode: ${mode}（可用 append / replace / create / node）`)
+  const rel = path.relative(lib.nodekb, absIn(lib.nodekb, target)) || target
+  const abs = absIn(lib.nodekb, target)
+  const existing = readText(abs)
+  if (mode === 'create' && existing !== null) fail(`${rel} 已存在。要追加用 mode=append，要整篇覆盖用 mode=replace`)
+  validateContent(content, rel)
+
+  let next
+  if (mode === 'replace' || existing === null) {
+    next = content.endsWith('\n') ? content : content + '\n'
+  } else {
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n'
+    next = existing + sep + content.replace(/^\n+/, '') + (content.endsWith('\n') ? '' : '\n')
+  }
+  fs.mkdirSync(path.dirname(abs), { recursive: true })
+  fs.writeFileSync(abs, next, 'utf8')
+  return { rel, abs, bytes: Buffer.byteLength(content, 'utf8'), mode, created: existing === null }
+}
+
+export { NODE_OPEN }

package/lib/host/prompt.js

@@ -0,0 +1,111 @@
+/**
+ * prompt —— 往系统提示词里加一段「本项目的知识库怎么用」。
+ *
+ * 这是让 Agent **优先**用 kb_* 而不是自己拿 write 搭 docs/ 的唯一常驻手段：
+ * 工具描述只有在模型已经决定「我要写知识」时才会被读到，而提示词每一轮都在。
+ * 代价是常驻 token，所以整段压到 ~450 字，只留 schema 表达不了的约定。
+ *
+ * 插件配置 prompt.enabled=false 可以关掉；prompt.text 可以整段替换。
+ */
+
+export const PROMPT_SECTION_NAME = 'project-node-memory'
+export const PROMPT_SECTION_ORDER = 100
+
+export const DEFAULT_PROMPT = [
+  '## 项目知识库（project-node-memory）',
+  '',
+  '本项目需要沉淀长期知识（设计决策、踩坑、事实常量、待办、交接）时，**用 `.nodekb/` + `kb_*` 工具**，不要用 write/edit 手搭 `docs/*.md` 式的渐进式文档——手写没有校验、没有稳定 TID、没有引用展开。',
+  '',
+  '- 建库：`kb_init` 一次铺出骨架（`doc/ facts/ lessons/ todo/ index/entry.md` + 约定说明）。已有 `.nodekb/` 就别重建。',
+  '- 写库：`kb_write`（append/replace/create，或对显式节点用 mode=node）。它写前校验 TID 与 `<node>` 独占一行，写后立刻跑 diag 把悬空引用/重复块报回来；同样的事用 write 做没有任何一层会拦。',
+  '- 读库：先 `kb_read mode=toc` 看结构（几百 token），再按 TID 读一支；找不到就 `kb_search`。别一次性把整库读进上下文。',
+  '- 改名前先 `kb_backlinks`，改名用 `kb_rename`（会重写全库引用并跳过被并发改过的文件）。',
+  '- 一个主题一个文件、取 < 4KB；结论只写一次，别处用 `[[TID]]` 引用。',
+].join('\n')
+
+function textOf(config) {
+  const p = (config && config.prompt) || {}
+  if (typeof p.text === 'string' && p.text.trim()) return p.text
+  return DEFAULT_PROMPT
+}
+
+/** 最近一次注册的结果（给 /nodekb/api/prompt 自证用） */
+const STATE = { registered: false, reason: 'not-run', chars: 0, name: PROMPT_SECTION_NAME, order: PROMPT_SECTION_ORDER }
+
+export function promptState() {
+  return { ...STATE }
+}
+
+/**
+ * @returns {() => void} disposer（未接上 systemPrompt 服务时是空函数）
+ *
+ * 注意：`systemPrompt` 是**可选服务**，不能写进静态 `inject`（拿不到就整个插件不激活，
+ * 连工具一起没了）。宿主给的是动态注入 `ctx.inject(['systemPrompt'], (child) => …)`：
+ * 服务就绪时回调，插件先照常起来。
+ */
+export function registerPrompt(ctx, config) {
+  const p = (config && config.prompt) || {}
+  if (p.enabled === false) {
+    Object.assign(STATE, { registered: false, reason: 'disabled-by-config', chars: 0 })
+    return () => {}
+  }
+
+  const attach = (sp) => {
+    if (!sp || typeof sp.section !== 'function') {
+      Object.assign(STATE, { registered: false, reason: 'no-systemPrompt-service', chars: 0 })
+      return null
+    }
+    const text = textOf(config)
+    try {
+      const dispose = sp.section({ name: PROMPT_SECTION_NAME, order: PROMPT_SECTION_ORDER, text })
+      Object.assign(STATE, { registered: true, reason: 'ok', chars: text.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
+    }
+  }
+
+  // 首选：动态注入，服务晚于插件就绪也能接上
+  if (typeof ctx.inject === 'function') {
+    let off = null
+    try {
+      const effect = ctx.inject(['systemPrompt'], (child) => {
+        off = attach(child && child.systemPrompt)
+        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 sp = null
+  try {
+    sp = ctx.systemPrompt || (typeof ctx.get === 'function' ? ctx.get('systemPrompt') : null)
+  } catch {
+    sp = null
+  }
+  if (!sp) {
+    Object.assign(STATE, { registered: false, reason: 'no-systemPrompt-service', chars: 0 })
+    return () => {}
+  }
+  const off = attach(sp)
+  return () => {
+    if (off) off()
+  }
+}