project-node-memory 1.1.4 → 1.2.1

package/README.md

@@ -108,8 +108,10 @@ config:
 
 ## 库怎么定位
 
-1. `lib` 参数给路径（技能目录，或其下的 `.nodekb`）——必须落在工作区或已注册库内
-2. `kb` 参数给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）
+所有 `kb_*` 工具只有一个定位参数 `kb`，它同时接受**名字**与**路径**：
+
+1. `kb` 给路径（技能目录，或其下的 `.nodekb`，绝对或相对工作区）——必须落在工作区或已注册库内
+2. `kb` 给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）
 3. 都不给：工作区自带的 `.nodekb/` → 工作区里发现且唯一的库 → 注册表里唯一的库
 
 **自动发现**：给了工作区之后，库里不只在工作区根找，还会按约定位置下钻（有界 BFS，默认 2 层）：
@@ -203,7 +205,7 @@ kb_write mode=node target=<TID> content=…  # 逐条改，或直接改 md 再 k
 ## 自检（不装 DSH 也能跑）
 
 ```bash
-node scripts/check.mjs      # 275 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
+node scripts/check.mjs      # 280 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
 node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
 ```
 

package/README_EN.md

@@ -105,8 +105,10 @@ The right column renders at most 10,000 characters per view (with a truncation n
 
 ## How a library is located
 
-1. `lib` — a path (a skill directory or its `.nodekb`), which must fall inside the workspace or a registered library.
-2. `kb` — a name (from a registry, or discovered in the workspace, e.g. a skill name).
+Every `kb_*` tool takes exactly one location parameter, `kb`, which accepts **either a name or a path**:
+
+1. `kb` = a path (a skill directory or its `.nodekb`, absolute or workspace-relative) — must fall inside the workspace or a registered library.
+2. `kb` = a name (from a registry, or discovered in the workspace, e.g. a skill name).
 3. Neither — the workspace's own `.nodekb/` → the single library discovered in the workspace → the single registered library.
 
 **Discovery**: given a workspace, it looks beyond the root at conventional locations (bounded BFS, depth 2 by default):
@@ -186,7 +188,7 @@ kb_write mode=node target=<TID> content=…  # fix one at a time, or edit the md
 ## Self-check (no DSH required)
 
 ```bash
-node scripts/check.mjs      # 275 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / tscl / prompt section / bundled skill
+node scripts/check.mjs      # 280 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / tscl / prompt section / bundled skill
 node test/parity.mjs        # case-by-case parity against the Python implementation (needs python and nodekb sources)
 ```
 

package/lib/engine/registry.js

@@ -194,6 +194,11 @@ export function discoverLibraries(root, { depth = 2, budget = 300, limit = 60, e
  */
 export function resolveLibrary({ kb, lib, workspace, config } = {}) {
   const ws = path.resolve(workspace || process.cwd())
+  // kb 同时接受「库名」与「路径」：带分隔符 / 绝对路径 / 指向 .nodekb 的一律当路径。
+  const raw = kb === undefined || kb === null ? '' : String(kb).trim()
+  const looksLikePath = !!raw && (path.isAbsolute(raw) || /[\\/]/.test(raw) || /\.nodekb$/i.test(raw))
+  const explicit = lib || (looksLikePath ? raw : undefined)
+  const kbName = looksLikePath ? undefined : raw
   const exclude = config && config.exclude
   const discover = () => discoverLibraries(ws, { exclude })
   const registries = loadRegistries(
@@ -202,10 +207,10 @@ export function resolveLibrary({ kb, lib, workspace, config } = {}) {
   )
 
   // 1) 显式路径
-  if (lib) {
-    const p = path.resolve(ws, lib)
+  if (explicit) {
+    const p = path.resolve(ws, explicit)
     const nodekb = path.basename(p) === '.nodekb' ? p : path.join(p, '.nodekb')
-    if (!isDir(nodekb)) throw new Error(`库目录不存在: ${nodekb}（你传入: ${lib}）`)
+    if (!isDir(nodekb)) throw new Error(`库目录不存在: ${nodekb}（你传入: ${explicit}）`)
     const allowed = [ws, ...[...registries.values()].map((e) => e.path)]
     if (!allowed.some((root) => isInside(nodekb, root))) {
       throw new Error(
@@ -217,7 +222,7 @@ export function resolveLibrary({ kb, lib, workspace, config } = {}) {
   }
 
   // 2) 名字
-  const name = kb && String(kb).trim()
+  const name = kbName
   if (name) {
     const entry = registries.get(name)
     if (entry) {
@@ -234,7 +239,7 @@ export function resolveLibrary({ kb, lib, workspace, config } = {}) {
       if (wsLib) return wsLib
     }
     const names = [...registries.keys(), ...discover().map((r) => r.name)]
-    throw new Error(`未注册的库: ${name}（可用: ${names.join(', ') || '无'}；或用 lib 参数给绝对路径）`)
+    throw new Error(`未注册的库: ${name}（可用: ${names.join(', ') || '无'}；kb 也可以直接传库目录路径）`)
   }
 
   // 3) 无参：工作区自带 → 工作区里唯一发现 → 唯一的注册表库

package/lib/host/tools.js

@@ -30,11 +30,7 @@ export function toolState() {
 
 const KB_PARAM = {
   type: 'string',
-  description: '库名（注册表里的名字，或工作区自带的 workspace）。省略则用工作区 .nodekb；都不存在时用唯一已注册的库。',
-}
-const LIB_PARAM = {
-  type: 'string',
-  description: '库根路径的备用写法：技能目录或其下的 .nodekb 绝对路径（也可相对工作区）。仅当库没有注册名时使用。',
+  description: '库：名字（注册表/工作区里的名字）或目录路径（技能目录或其 .nodekb）。省略则用工作区默认库。',
 }
 
 function text(t) {
@@ -60,7 +56,7 @@ function allowedRoots(config, exec) {
 /** 库定位失败时补一句「有哪些库可用」，别让模型瞎猜 */
 function locate(config, exec, args) {
   try {
-    return openLibrary(config, exec, { kb: args.kb, lib: args.lib })
+    return openLibrary(config, exec, { kb: args.kb })
   } catch (e) {
     const hint = libraryHint(config, exec)
     const err = new Error(`${e.message}${hint ? `\n${hint}` : ''}`)
@@ -100,17 +96,13 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_read',
     description:
-      '读取 nodekb 知识库的一个节点。target 是 TID（如 doc:03-工程经验与坑:3.1）或唯一前缀（如 3.1 不行、doc:03 可以）。' +
-      'mode 默认 subtree = 整支渲染（本节点的 [[TID]] 引用就地展开成内容，再递归子节点）；' +
-      'toc = 只看结构不看正文（每个节点一行：tid · 标题 · 字符数，适合先定位再读）；' +
-      'node = 只读本节点自身（不含子节点，也不展开子节）；raw = 元信息 + 原始内容（含未展开的 [[TID]]）。' +
-      '比 read 工具好在：一次拿到装配好的上下文，且 TID 不受文件行号漂移影响。超过 maxlen 会报错并提示改用 toc/node。',
+      '读知识库的一个节点。target = TID 或其唯一前缀（空/"." = 库根）。mode: subtree（默认，整支投影）| toc（只看结构，' +
+      '先定位再读）| node（只本节点）| raw（元信息+原文）。比 read 好在 TID 不随行号漂移；超 maxlen 会报错并提示换 toc/node。',
     parameters: {
       type: 'object',
       properties: {
         target: { type: 'string', description: '节点 TID 或其唯一前缀。空字符串或 "." 表示库根。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
         mode: {
           type: 'string',
           enum: ['subtree', 'node', 'toc', 'raw'],
@@ -173,15 +165,13 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_search',
     description:
-      '在 nodekb 知识库里检索（中文自然语言可用：连续中文按 2-gram 拆分并过滤虚词，多词命中加权，无命中时退化为整句子串匹配）。' +
-      '返回每条命中的稳定 TID（positional=true 表示命中的是位置型段落，tid 已上溯到文件/显式节点，ref 是实际命中点）、类型、标题、源文件行号与命中片段。' +
-      '用 kb_search 找到 tid，再用 kb_read 读，比 grep 后逐个 read 省往返。',
+      '检索知识库（中文 2-gram + 多词加权 + 子串兜底）。返回稳定 TID、类型、标题、源行、片段。' +
+      '先 kb_search 拿 tid 再 kb_read，比 grep 后逐个 read 省往返。',
     parameters: {
       type: 'object',
       properties: {
         query: { type: 'string', description: '检索词或自然语言问句。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
         type: { type: 'string', description: '只保留该类型的节点（如 doc / todo / handover）。' },
         limit: { type: 'integer', description: '返回条数上限，默认 10。' },
         offset: { type: 'integer', description: '跳过前 N 条，用于翻页。' },
@@ -214,14 +204,12 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_diag',
     description:
-      '知识库结构自检。errors = 真损坏（悬空引用 [[TID]]、引用位置型段落 TID、循环引用、孤儿节点、树环、重复 TID）；' +
-      'warnings = 疑似内容漂移（同一段文字出现在多个节点 / 节点内重复行），默认不影响结论。' +
-      '改完 md 之后跑一次，比人工核对可靠。库根可放 diag_ignore.json 豁免样板块。',
+      '结构自检。errors = 真损坏（悬空/位置型引用、循环、孤儿、树环、重复 TID、tscl 定义问题）；' +
+      'warnings = 疑似漂移（同一段文字出现在多处），默认不算失败。写完 md 就跑一次。',
     parameters: {
       type: 'object',
       properties: {
         kb: KB_PARAM,
-        lib: LIB_PARAM,
         strict: { type: 'boolean', description: '严格模式：把 warnings 也算失败。' },
       },
     },
@@ -246,14 +234,13 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_backlinks',
     description:
-      '反查：谁引用了这个节点（[[TID]] 指向它）。改 TID / 删节点之前先跑，能一次列出所有会断的地方——' +
-      '比全库 grep 更准（只认真实引用语法，不受正文里偶然出现的同名文字干扰）。',
+      '反查：谁引用了这个 id（`[[node=…]]`/`[[tscl=…]]`/旧式 `[[TID]]` 都算）。改 TID 或删节点前先跑，' +
+      '比全库 grep 准——只认真实引用语法。',
     parameters: {
       type: 'object',
       properties: {
         target: { type: 'string', description: '节点 TID 或其唯一前缀。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
       required: ['target'],
     },
@@ -282,9 +269,8 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_rename',
     description:
-      '重命名库里的一个 md 文件，并把全库指向它的 [[TID]] 引用一起改写（含 [[tid:1.2]] 这种子节点引用）。' +
-      'nodekb 的 TID 由文件名派生，所以「用 mv / 编辑器改名」必然留下一堆悬空引用；要么用这个工具，' +
-      '要么改名后自己跑 kb_diag 逐个修。写前会重读校验，别人刚改过的文件不覆盖、只报出来。',
+      '重命名 md 文件并改写全库指向它的引用（含子节点）。TID 由文件名派生，所以用 mv 改名必然留悬空引用；' +
+      '写前重读校验，别人刚改过的文件跳过不覆盖。',
     parameters: {
       type: 'object',
       properties: {
@@ -292,7 +278,6 @@ export function buildTools(ctx, config) {
         new_name: { type: 'string', description: '新文件名（.md 可省略，不能带目录）。' },
         dry_run: { type: 'boolean', description: 'true = 只报「会改哪些引用」，不动文件。' },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
       required: ['target', 'new_name'],
     },
@@ -313,13 +298,11 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_vcs_status',
     description:
-      '查看知识库内嵌 git 仓库的状态（最近提交 + 未提交改动）。nodekb 每次解析后会自动快照，' +
-      '所以这里能看到「库的改动历史」；文件系统上有改动但没进快照时也会列出来。git 不可用时返回说明而不报错。',
+      '库内嵌 git 的快照历史与未提交改动（每次解析后自动快照）；git 不可用时只说明不报错。',
     parameters: {
       type: 'object',
       properties: {
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
     },
     output: {
@@ -365,11 +348,8 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_init',
     description:
-      '为一个项目建 .nodekb 知识库骨架（幂等：已存在的文件不覆盖）。' +
-      '当用户要在项目里沉淀长期知识、而你准备开始写第一份文档之前，先调这个——' +
-      '它一次铺出 doc/ facts/ lessons/ todo/ index/entry.md 与 .nodekb/README.md 里的落位约定，' +
-      '比你自己拿 write 从零设计目录结构更省事，也让后续 Agent 知道该往哪写。' +
-      '已经有 .nodekb/ 就不要调（先用 kb_list 看）。',
+      '建 .nodekb 骨架（幂等，已有的不覆盖）：doc/ lessons/ todo/ index/entry.md + 落位约定。' +
+      '准备手写 docs/*.md 之前先调这个；已经有 .nodekb/ 就别调（先 kb_list 看）。',
     parameters: {
       type: 'object',
       properties: {
@@ -403,10 +383,8 @@ export function buildTools(ctx, config) {
   tools.push({
     name: 'kb_write',
     description:
-      '往 nodekb 库里写内容，并在写后立刻自检（悬空引用/位置型引用/重复块）。' +
-      '这是「用知识库管知识」的正路：同样写 md，但写前校验 TID 与 <node> 独占一行，写后把结构错误当场报回来；' +
-      '直接用 write/edit 没有这一层。' +
-      'mode=append 追加到文件（不存在则创建）、replace 整篇覆盖、create 只新建、node 就地改写一个 <node> 块。',
+      '写库并立刻自检（悬空引用/重复定义/结构错误当场报回来）。写前校验 TID 与 <node> 独占一行；' +
+      '用 write/edit 直接改没有这层。mode=append（追加，不存在则建）| replace（整篇）| create（只新建）| node（就地改一个 <node> 块）。',
     parameters: {
       type: 'object',
       properties: {
@@ -421,7 +399,6 @@ export function buildTools(ctx, config) {
           description: '默认：路径→append，TID→node。create 遇到已存在会报错，避免覆盖。',
         },
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
       required: ['target', 'content'],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-node-memory",
-  "version": "1.1.4",
+  "version": "1.2.1",
   "description": "Project node knowledge base for DSH agents: markdown-as-database, stable TIDs, transclusion projection, structure self-check.",
   "type": "module",
   "license": "MIT",