project-node-memory 1.3.3 → 1.4.0

package/README.md

@@ -67,7 +67,7 @@ dsh plugin add ./project-node-memory-<版本>.tgz
 
 | 键               | 默认                                            | 作用                                                          |
 | ---------------- | ----------------------------------------------- | ------------------------------------------------------------- |
-| `workspace`      | 会话工作区 → 进程 cwd                           | 覆盖「工作区」，库发现与路径白名单都以它为界                  |
+| `workspace`      | 无（自动判定）                                  | 覆盖「工作区」。判定顺序见下；工具侧优先取会话头里的 cwd |
 | `libraries`      | 无                                              | `名字: 目录`，显式登记工作区之外的库（目录下需有 `.nodekb/`） |
 | `registries`     | 工作区 `.nodekb/registry.json` + 用户全局注册表 | 额外的 `kb_registry.json`（与 Python 版同格式）               |
 | `exclude`        | 见下                                            | 库发现时忽略的目录名，支持 `*` 通配；`!pattern` 强制放行     |
@@ -94,16 +94,17 @@ config:
 面板只读，数据走宿主侧注册的 `/nodekb/api/*`。写库就是写 md——用 `write` / `edit` 工具，或者 `kb_write`。
 右栏正文单次最多渲染 10000 字符（超出显示截断提示）；宽表格横向滚动，长文本纵向滚动。
 
-## 9 个工具
+## 10 个工具
 
 | 工具            | 干什么                                                                                         |
 | --------------- | ---------------------------------------------------------------------------------------------- |
-| `kb_list`       | 有哪些库、哪个是默认。不确定传什么 `kb` 时先调它                                               |
+| `kb_list`       | 有哪些库（含绝对路径与来源）、本会话判定的工作区。不确定传什么 `kb` 时先调它                   |
 | `kb_read`       | `target` + `mode`（`subtree` 默认 / `node` / `toc` / `raw`）+ `maxlen`                         |
 | `kb_search`     | 中文友好检索（2-gram + 多词加权 + 少见时退化子串），返回稳定 TID、类型、源行、片段             |
 | `kb_diag`       | 结构自检；有 error 时直接失败，别读完才发现引用断了                                            |
 | `kb_backlinks`  | 谁引用了它。改 TID / 删节点前先跑                                                              |
 | `kb_init`       | 建 `.nodekb` 骨架（幂等），铺出 `doc/ lessons/ todo/ index/` 与落位约定                 |
+| `kb_register`   | 把已有的库登记进**项目自己**的 `kb_registry.json`（不写全局表、不改配置）                      |
 | `kb_write`      | 写库：`append` / `replace` / `create` / `node`（就地改写一个 `<node>` 块）；写前校验、写后自检 |
 | `kb_rename`     | 文件改名 + 全库引用一起改写；写前重读，别人刚改的不覆盖                                        |
 | `kb_vcs_status` | 库内嵌 git 的快照历史与未提交改动（git 缺失时只说明，不报错）                                  |
@@ -112,7 +113,7 @@ config:
 
 所有 `kb_*` 工具只有一个定位参数 `kb`，它同时接受**名字**与**路径**：
 
-1. `kb` 给路径（技能目录，或其下的 `.nodekb`，绝对或相对工作区）——必须落在工作区或已注册库内
+1. `kb` 给路径（技能目录，或其下的 `.nodekb`，绝对或相对工作区）——必须落在**本会话工作区、任一已登记工作区或已注册库**内
 2. `kb` 给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）
 3. 都不给：工作区自带的 `.nodekb/` → 工作区里发现且唯一的库 → 注册表里唯一的库
 
@@ -140,7 +141,19 @@ config:
           - D:\shared\kb_registry.json
 ```
 
-`config.workspace` 可覆盖「工作区」；优先级是 **exec 上下文（面板点的目录 / 会话工作区）→ config.workspace → 环境变量 `DSH_NODEKB_WORKSPACE` → 最近一次工具用过的目录 → 进程 cwd**。所以在面板里换目录总能生效，配置只当默认值。
+「工作区」是解析库与判断可写范围的基准，判定顺序是：
+
+1. **会话头里的 `cwd`**（工具调用时）——`exec.agent.id` → `ctx.get('sessions').get(id).header.cwd`。这是唯一可靠来源：DSH 交给工具的 `exec` 里没有 `cwd`/`workspace` 字段。
+2. `exec` 里显式的目录（面板请求带的 `ws`）。
+3. `config.workspace`。
+4. 环境变量 `DSH_NODEKB_WORKSPACE`。
+5. 面板没有会话，才退到「最近一次工具用过的工作区」；最后是进程 cwd。
+
+每次 `kb_list` / `kb_init` 的回执都会写明**这次用的是哪个工作区、来源是哪一层**；`GET /nodekb/api/where` 给同样的信息。
+
+写库或建库时，若目标落在**另一个**已登记工作区里，`kb_init` 会直接拒绝并打印双方路径——这是为了防止相对路径被解析到别的项目里。真要在那边建，去那个项目开会话；或者先用 `kb_register` 把已有的库登记进当前项目。
+
+`kb_register` 只写 `<项目>/kb_registry.json`（建议随仓库提交），不碰全局注册表、不碰插件配置——所以权限问题可以在工具集内部自己解决，不用去改一个模型看不见的文件。
 
 面板拿不到会话上下文，所以它默认跟随**最近一次 `kb_*` 工具调用所在的工作区**（Agent 读过哪个项目，面板就显示哪个项目）；顶栏的目录下拉只列出 DSH 用过的、且**真的有 `.nodekb`** 的项目目录（标了各自发现几个库），点右上「目录」也可以手填路径。选择存在浏览器 localStorage，只影响面板，不影响工具。
 

package/README_EN.md

@@ -93,12 +93,13 @@ The right column renders at most 10,000 characters per view (with a truncation n
 
 | Tool | What it does |
 |---|---|
-| `kb_list` | Which libraries exist and which is default. Call this first when unsure what `kb` to pass |
+| `kb_list` | Which libraries exist (absolute paths and origins) plus the workspace this call resolved to. Call this first when unsure what `kb` to pass |
 | `kb_read` | `target` + `mode` (`subtree` default / `node` / `toc` / `raw`) + `maxlen` |
 | `kb_search` | CJK-friendly retrieval (2-gram index + multi-term weighting + substring fallback), returns stable TID, type, source line, snippet |
 | `kb_diag` | Structure self-check; fails outright on errors so you don't finish a read before noticing a broken ref |
 | `kb_backlinks` | Who references this node. Run before renaming a TID or deleting a node |
 | `kb_init` | Scaffold `.nodekb` (idempotent): `doc/ lessons/ todo/ index/` plus placement conventions |
+| `kb_register` | Register an existing library in the **project's own** `kb_registry.json` (never the global registry or the plugin config) |
 | `kb_write` | Write into the library: `append` / `replace` / `create` / `node` (rewrite one `<node>` block in place); validates before writing, self-checks after |
 | `kb_rename` | Rename a file and rewrite every reference pointing at it; re-reads before writing, so concurrent edits are never clobbered |
 | `kb_vcs_status` | Snapshot history and uncommitted changes of the library's embedded git repo (explains itself when git is missing) |
@@ -135,7 +136,17 @@ Registries use the same format as the Python build's `kb_registry.json`; by defa
           - D:\shared\kb_registry.json
 ```
 
-`config.workspace` overrides "the workspace", which otherwise comes from the session and falls back to the process cwd.
+"The workspace" is the basis for both library resolution and the writable allowlist:
+
+1. **the session header's `cwd`** (for tool calls) — `exec.agent.id` → `ctx.get('sessions').get(id).header.cwd`. This is the only reliable source: the `exec` DSH hands a tool has no `cwd`/`workspace` field at all.
+2. an explicit directory in `exec` (the `ws` a panel request carries).
+3. `config.workspace`.
+4. the `DSH_NODEKB_WORKSPACE` environment variable.
+5. only for the panel (which has no session): the workspace of the most recent tool call; last resort, the process cwd.
+
+Every `kb_list` / `kb_init` receipt states which workspace was used and which layer it came from; `GET /nodekb/api/where` reports the same.
+
+`kb_init` refuses to write into a **different** registered workspace and prints both paths — so a relative path can never silently land in another project. To work there, open a session in that project; or use `kb_register` to register an existing library with the current project. `kb_register` writes only `<project>/kb_registry.json` (commit it), never the global registry or the plugin config — permissions become solvable from inside the tool set.
 
 The panel has no session context, so it follows **the workspace of the most recent `kb_*` tool call** (whichever project the agent read, the panel shows). The directory dropdown in the header lists projects DSH has used, annotated with how many libraries each contains; the 「目录」 button lets you type a path. The choice is stored in browser localStorage and affects the panel only, never the tools.
 

package/lib/engine/registry.js

@@ -192,7 +192,7 @@ export function discoverLibraries(root, { depth = 2, budget = 300, limit = 60, e
  * 定位库根（返回 .nodekb 目录）。
  * @throws 带可行动提示的错误
  */
-export function resolveLibrary({ kb, lib, workspace, config } = {}) {
+export function resolveLibrary({ kb, lib, workspace, config, extraRoots = [] } = {}) {
   const ws = path.resolve(workspace || process.cwd())
   // kb 同时接受「库名」与「路径」：带分隔符 / 绝对路径 / 指向 .nodekb 的一律当路径。
   const raw = kb === undefined || kb === null ? '' : String(kb).trim()
@@ -211,11 +211,15 @@ export function resolveLibrary({ kb, lib, workspace, config } = {}) {
     const p = path.resolve(ws, explicit)
     const nodekb = path.basename(p) === '.nodekb' ? p : path.join(p, '.nodekb')
     if (!isDir(nodekb)) throw new Error(`库目录不存在: ${nodekb}（你传入: ${explicit}）`)
-    const allowed = [ws, ...[...registries.values()].map((e) => e.path)]
+    // 允许范围 = 本会话工作区 + 全部已登记工作区 + 注册表里的库。
+    // 「已登记工作区」是关键：多项目并行时，工具能读到的库不该只有一个根决定的那个。
+    const allowed = [ws, ...extraRoots, ...[...registries.values()].map((e) => e.path)]
     if (!allowed.some((root) => isInside(nodekb, root))) {
       throw new Error(
-        `拒绝访问工作区外的库: ${nodekb}\n` +
-          `允许范围 = 工作区 ${ws} + 已注册库。需要长期使用请在插件配置 config.libraries 里登记。`,
+        `拒绝访问未登记位置的库: ${nodekb}\n` +
+          `已判定的工作区 = ${ws}\n` +
+          `允许范围 = 该工作区 + 已登记工作区${extraRoots.length ? `（${extraRoots.length} 个）` : ''} + 已注册库。\n` +
+          `要长期使用这个库，把它登记进项目：kb_register(kb="<该库所在目录>")，会在 <项目>/kb_registry.json 里记一行。`,
       )
     }
     return { name: path.basename(nodekb), base: path.dirname(nodekb), nodekb, origin: 'lib' }
@@ -300,3 +304,27 @@ export function listLibraries({ workspace, config, scope, includeHidden = false
   }
   return rows
 }
+
+/**
+ * 把一个库登记进**项目自己**的 kb_registry.json（`<workspace>/kb_registry.json`）。
+ * 不写全局注册表、不改 profile 配置：登记随项目走，换人 clone 下来就在，
+ * 也不会像全局注册表那样把 A 项目的库漏进 B 项目的选择器。
+ */
+export function writeProjectRegistry({ workspace, name, dir, hidden = false }) {
+  const ws = path.resolve(workspace)
+  const file = path.join(ws, 'kb_registry.json')
+  let data = {}
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) data = parsed
+  } catch {
+    data = {}
+  }
+  if (!data.libraries || typeof data.libraries !== 'object' || Array.isArray(data.libraries)) data.libraries = {}
+  const entry = { path: path.resolve(dir) }
+  if (hidden) entry.hidden = true
+  const replaced = !!data.libraries[name]
+  data.libraries[name] = entry
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n', 'utf8')
+  return { file, name, path: entry.path, replaced }
+}

package/lib/host/prompt.js

@@ -21,6 +21,7 @@ export const DEFAULT_PROMPT = [
   '- 读库：先 `kb_read mode=toc` 看结构，再按 TID 读一支；找不到就 `kb_search`。别一次性把整库读进上下文。',
   '- 改名前先 `kb_backlinks`，改名用 `kb_rename`（会重写全库引用并跳过被并发改过的文件）。',
   '- 引用分两种：结构用 `[[node="xxx"]]`（只出一个链接，不复制正文）；值只写一处——定义 `<tscl id="xxx:xxx">…</tscl>`，嵌入处写 `[[tscl="xxx:xxx"]]`，同一 id 全库只能定义一次。定义可就近写在正文句子里（单行、别写进表格）。读一个值用 `kb_read target=<定义 id>`。',
+  '- 库找不到时先 `kb_list`（它会写明本会话判定的工作区与来源）；已有的库可用 `kb_register` 登记进项目，不必改配置。',
 ].join('\n')
 
 function textOf(config) {

package/lib/host/runtime.js

@@ -3,6 +3,11 @@
  *
  * 缓存键是 .nodekb 的绝对路径，有效性靠「全库 md 的 mtime/size 签名」判断：
  * 编辑任何一个 md 都会让签名变化，所以不需要 fs.watch（也就没有 watcher 丢事件的问题）。
+ *
+ * 会话工作区从哪来（1.4.0 起）：DSH 交给工具的 `exec` 里**没有** workspace/cwd，
+ * 只有 `exec.agent.id`（= 会话 id）。会话头里才有真话：
+ *   ctx.get('sessions').get(sessionId).header.cwd
+ * 所以这里先问会话头，再退显式参数与配置；进程 cwd 只作最后兜底。
  */
 
 import fs from 'node:fs'
@@ -14,9 +19,63 @@ import { resolveLibrary, listLibraries } from '../engine/registry.js'
 const CACHE = new Map() // nodekb -> { sig, nodes, problems, defs }
 const MAX_CACHE = 8
 
+// 宿主服务句柄（apply 时注入）：sessions / workspaceRegistry 都是可选服务。
+let SERVICES = null
+
+export function bindServices(ctx) {
+  SERVICES = ctx || null
+}
+
+function service(name) {
+  if (!SERVICES) return null
+  try {
+    if (typeof SERVICES.get === 'function') return SERVICES.get(name) || null
+    return SERVICES[name] || null
+  } catch {
+    return null
+  }
+}
+
+/** 调用方会话 id：DSH 把它放在 exec.agent.id 上（ToolExecutionInput.agent）。 */
+export function sessionIdOf(exec) {
+  const agent = exec && typeof exec === 'object' ? exec.agent : null
+  const id = agent && typeof agent === 'object' ? agent.id : null
+  return typeof id === 'string' && id ? id : ''
+}
+
+/** 会话头里记录的工作目录（会话真正的项目根）。 */
+export function sessionCwd(exec) {
+  const sid = sessionIdOf(exec)
+  if (!sid) return ''
+  const sessions = service('sessions')
+  if (!sessions || typeof sessions.get !== 'function') return ''
+  try {
+    const session = sessions.get(sid)
+    const header = session && session.header
+    const cwd = header && header.cwd
+    return typeof cwd === 'string' && cwd ? path.resolve(cwd) : ''
+  } catch {
+    return ''
+  }
+}
+
+/** 已登记工作区的全部路径（允许范围用，不再只认「解析出来的那一个」）。 */
+export function workspaceRoots() {
+  const reg = service('workspaceRegistry')
+  if (!reg || typeof reg.list !== 'function') return []
+  try {
+    return reg
+      .list()
+      .map((w) => (w && typeof w.path === 'string' ? path.resolve(w.path) : ''))
+      .filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
 // 面板没有会话上下文，只能靠人指定工作区（ws 参数）。
-// 但 Agent 调 kb_* 工具时是带着工作区的——把那一次记下来，
-// 面板就能「跟着 Agent 走」，不必每次手填目录。
+// 但 Agent 调 kb_* 工具时是带着会话的——把那次的工作区记下来，面板就能「跟着 Agent 走」。
+// 这条兜底**只服务面板**：带 exec 的工具调用永远不吃它（否则会把上一个项目的路径带进来）。
 let LAST_WORKSPACE = ''
 
 export function rememberWorkspace(ws) {
@@ -59,31 +118,44 @@ function signature(nodekb) {
   return `${count}:${size}:${maxM}`
 }
 
-/** 取会话工作区：exec 上下文（面板显式 ws / 会话工作区） → 配置 → 环境变量 → 上次记住的 → 进程 cwd
- *  exec 放最前面：面板点了哪个工作区、Agent 在哪个会话里，都必须压过配置里的默认值。 */
-export function workspaceOf(config, exec) {
-  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)
+/** 判定工作区，并说明它是怎么定下来的。
+ *  顺序：显式 exec.workspace → exec.cwd → 会话头 cwd → 配置 → 环境变量 →（仅面板）上次记住的 → 进程 cwd */
+export function workspaceSource(config, exec) {
+  const e = exec && typeof exec === 'object' ? exec : null
+  const explicit = e && typeof e.workspace === 'string' && e.workspace ? path.resolve(e.workspace) : ''
+  if (explicit) return { path: explicit, from: 'exec.workspace' }
+  const cwd = e && typeof e.cwd === 'string' && e.cwd ? path.resolve(e.cwd) : ''
+  if (cwd) return { path: cwd, from: 'exec.cwd' }
+  const scwd = sessionCwd(e)
+  if (scwd) return { path: scwd, from: 'session.header.cwd' }
   const configured = config && typeof config.workspace === 'string' ? config.workspace : ''
-  if (configured) return path.resolve(configured)
+  if (configured) return { path: path.resolve(configured), from: 'config.workspace' }
   const env = process.env.DSH_NODEKB_WORKSPACE
-  if (env) return path.resolve(env)
-  if (LAST_WORKSPACE) return LAST_WORKSPACE
-  return process.cwd()
+  if (env) return { path: path.resolve(env), from: 'env.DSH_NODEKB_WORKSPACE' }
+  if (!e && LAST_WORKSPACE) return { path: LAST_WORKSPACE, from: 'last-workspace（面板）' }
+  return { path: process.cwd(), from: 'process.cwd' }
+}
+
+export function workspaceOf(config, exec) {
+  return workspaceSource(config, exec).path
 }
 
 /** 诊断用：把「工作区是怎么定下来的」原样吐出来（面板/工具都对不上时靠它） */
 export function whereInfo(config, exec) {
-  const e = exec && typeof exec === 'object' ? exec : {}
+  const e = exec && typeof exec === 'object' ? exec : null
+  const src = workspaceSource(config, e)
   return {
+    sessionId: sessionIdOf(e),
+    sessionCwd: sessionCwd(e),
+    execWorkspace: (e && e.workspace && String(e.workspace)) || '',
+    execCwd: (e && e.cwd && String(e.cwd)) || '',
     configured: (config && config.workspace) || '',
     env: process.env.DSH_NODEKB_WORKSPACE || '',
-    execWorkspace: (e.workspace && String(e.workspace)) || '',
-    execCwd: (e.cwd && String(e.cwd)) || '',
     lastWorkspace: LAST_WORKSPACE || '',
     processCwd: process.cwd(),
-    resolved: workspaceOf(config, exec),
+    workspaceRoots: workspaceRoots(),
+    resolved: src.path,
+    from: src.from,
   }
 }
 
@@ -92,15 +164,15 @@ export function whereInfo(config, exec) {
  * @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 { path: workspace, from } = workspaceSource(config, exec)
+  // 只有「带着会话的调用」才值得记下来；面板用 ws 参数指定目录是显式选择，别污染工具侧默认工作区。
+  if (remember && exec && typeof exec === 'object' && !exec.wsParam) rememberWorkspace(workspace)
+  const resolved = resolveLibrary({ kb, lib, workspace, config, extraRoots: workspaceRoots() })
   const sig = signature(resolved.nodekb)
   const hit = CACHE.get(resolved.nodekb)
+  const base = { ...resolved, workspace, workspaceFrom: from }
   if (hit && hit.sig === sig) {
-    return { ...resolved, nodes: hit.nodes, defs: hit.defs, problems: hit.problems, cached: true }
+    return { ...base, nodes: hit.nodes, defs: hit.defs, problems: hit.problems, cached: true }
   }
   const problems = []
   const nodes = parse_library(resolved.nodekb, problems)
@@ -111,7 +183,7 @@ export function openLibrary(config, exec, { kb, lib, remember = true } = {}) {
   }
   CACHE.set(resolved.nodekb, { sig, nodes, defs: found.defs, problems })
   if (CACHE.size > MAX_CACHE) CACHE.delete(CACHE.keys().next().value)
-  return { ...resolved, nodes, defs: found.defs, problems, cached: false }
+  return { ...base, nodes, defs: found.defs, problems, cached: false }
 }
 
 export function knownLibraries(config, exec, opts = {}) {

package/lib/host/tools.js

@@ -7,6 +7,7 @@
  * 设计取向：description 本身就是 prompt，所以它要写清楚「什么时候用我、什么时候别用我」。
  */
 
+import fs from 'node:fs'
 import path from 'node:path'
 import { execFileSync } from 'node:child_process'
 import { render_node, render_subtree, toc_lines, node_info, resolve_path } from '../engine/render.js'
@@ -17,8 +18,17 @@ import { refsToDef, formatDefRead } from '../engine/defs.js'
 import { renameFileNode, formatRename } from '../engine/rename.js'
 import { scaffold } from '../engine/scaffold.js'
 import { writeInto } from '../engine/write.js'
-import { isInside } from '../engine/registry.js'
-import { openLibrary, workspaceOf, libraryHint, knownLibraries } from './runtime.js'
+import { isInside, writeProjectRegistry } from '../engine/registry.js'
+import {
+  openLibrary,
+  workspaceOf,
+  workspaceSource,
+  libraryHint,
+  knownLibraries,
+  workspaceRoots,
+  sessionIdOf,
+  bindServices,
+} from './runtime.js'
 
 const DEFAULT_MAXLEN = 50000
 
@@ -43,15 +53,24 @@ function warnPrefix(lib) {
   return `⚠ 库有 ${lib.problems.length} 处 TID 冲突，已跳过冲突项：\n  - ${lib.problems.slice(0, 5).join('\n  - ')}\n\n`
 }
 
-/** 允许建库/写库的根：工作区 + 所有已注册库（技能目录也在其中） */
+/** 允许建库/写库的根：本会话工作区 + 全部已登记工作区 + 所有已注册库（技能目录也在其中） */
 function allowedRoots(config, exec) {
+  const out = []
   try {
-    return knownLibraries(config, exec)
-      .map((r) => r.path || r.nodekb)
-      .filter((p) => typeof p === 'string' && p)
+    for (const r of knownLibraries(config, exec)) {
+      const p = r.path || r.nodekb
+      if (typeof p === 'string' && p) out.push(p)
+    }
+  } catch {
+    /* 库列表拿不到就只靠 workspaceRoots */
+  }
+  for (const r of workspaceRoots()) out.push(r)
+  try {
+    out.push(workspaceOf(config, exec))
   } catch {
-    return []
+    /* ignore */
   }
+  return [...new Set(out.filter(Boolean))]
 }
 
 /** 库定位失败时补一句「有哪些库可用」，别让模型瞎猜 */
@@ -67,28 +86,37 @@ function locate(config, exec, args) {
 }
 
 export function buildTools(ctx, config) {
+  bindServices(ctx)
   const tools = []
 
   // ── kb_list ──────────────────────────────────────────────────────────────
   tools.push({
     name: 'kb_list',
     description:
-      '列出当前可用的 nodekb 知识库以及本次调用实际会命中的默认库。不确定该传什么 kb 参数时先用它。',
+      '列出当前可用的 nodekb 知识库，以及本次调用实际会命中的工作区与默认库。建库前/不确定该传什么 kb 时先用它。',
     parameters: { type: 'object', properties: {} },
     output: {
       schema: {},
       render: (_args, value) => text(value.text),
     },
-    async execute() {
-      const rows = knownLibraries(config, null)
-      const lines = ['可用于 kb_* 工具的 nodekb 库：']
+    async execute(_args, exec) {
+      const src = workspaceSource(config, exec)
+      const rows = knownLibraries(config, exec)
+      const byName = new Map()
+      for (const r of rows) byName.set(r.name, (byName.get(r.name) || 0) + 1)
+      const lines = [`工作区: ${src.path}（来源: ${src.from}）`]
+      if (sessionIdOf(exec)) lines.push(`会话: ${sessionIdOf(exec)}`)
+      lines.push('', '可用于 kb_* 工具的 nodekb 库：')
       if (!rows.length) {
-        lines.push('  （无）在工作区建 .nodekb/ 并放入 md 文件，或在插件配置 config.libraries / config.registries 里登记。')
+        lines.push('  （无）在工作区建 .nodekb/ 并放 md 文件，或先调 kb_init。')
       }
       for (const r of rows) {
-        lines.push(`- ${r.name}  ${r.path}${r.exists ? '' : '  [路径不存在]'}${r.origin === 'workspace' ? '  （工作区默认）' : ''}`)
+        const mark = r.exists ? '' : '  [路径不存在]'
+        const origin = r.origin === 'workspace' ? '  （工作区默认）' : `  （${r.origin}）`
+        const dup = byName.get(r.name) > 1 ? '  ⚠ 同名库，按名字调用有歧义，请用路径' : ''
+        lines.push(`- ${r.name}  ${r.path}${mark}${origin}${dup}`)
       }
-      return { text: lines.join('\n'), libs: rows }
+      return { text: lines.join('\n'), workspace: src.path, workspaceFrom: src.from, libs: rows }
     },
   })
 
@@ -381,18 +409,84 @@ export function buildTools(ctx, config) {
       render: (_args, value) => text(value.text),
     },
     async execute(args, exec) {
-      const ws = workspaceOf(config, exec)
+      const src = workspaceSource(config, exec)
+      const ws = src.path
       const rel = typeof args.dir === 'string' && args.dir.trim() ? args.dir.trim() : '.nodekb'
       const target = path.resolve(ws, rel)
-      const okRoot = isInside(target, ws) || allowedRoots(config, exec).some((r) => isInside(target, r))
-      if (!okRoot) throw new Error(`拒绝在工作区外建库: ${target}`)
+      const otherWorkspace = workspaceRoots().find((r) => r !== ws && isInside(target, r))
+      if (otherWorkspace) {
+        throw new Error(
+          `拒绝把库建在另一个已登记的工作区里: ${target}\n` +
+            `本会话判定的工作区 = ${ws}（来源: ${src.from}）\n` +
+            `目标却落在 = ${otherWorkspace}\n` +
+            `如果确实要建在那个项目里，请在那个项目下开会话再执行；如果只是想在本会话工作区里建，传相对路径（如 .nodekb 或 .dsh/skills/<技能>/.nodekb）。`,
+        )
+      }
+      const okRoot = allowedRoots(config, exec).some((r) => isInside(target, r))
+      if (!okRoot) {
+        throw new Error(
+          `拒绝在工作区外建库: ${target}\n` +
+            `本会话工作区 = ${ws}（来源: ${src.from}）\n` +
+            `允许范围 = 该工作区 + 已登记工作区 + 已注册库：\n  - ` +
+            allowedRoots(config, exec).join('\n  - '),
+        )
+      }
       const res = scaffold(target)
-      const lines = [`库目录: ${res.nodekb}`]
+      const lines = [`库目录: ${res.nodekb}`, `工作区: ${ws}（来源: ${src.from}）`]
       lines.push(res.created.length ? `新建 ${res.created.length} 个文件:\n` + res.created.map((f) => '  + ' + f).join('\n') : '没有新建文件（骨架已存在）')
       if (res.skipped.length) lines.push(`跳过 ${res.skipped.length} 个已存在文件: ${res.skipped.join('、')}`)
       lines.push('')
       lines.push('下一步：把这次要记的东西用 kb_write 写进对应目录（先读 .nodekb/README.md 的落位表），写完 kb_diag 一遍。')
-      return { text: lines.join('\n'), nodekb: res.nodekb, created: res.created, skipped: res.skipped }
+      lines.push('提示：文件名建议用 ASCII（中文标题写进 # 一级标题里），Windows 控制台显示中文路径会乱码。')
+      return { text: lines.join('\n'), nodekb: res.nodekb, workspace: ws, workspaceFrom: src.from, created: res.created, skipped: res.skipped }
+    },
+  })
+
+  // ── kb_register ──────────────────────────────────────────────────────────
+  tools.push({
+    name: 'kb_register',
+    description:
+      '把一个已存在的 .nodekb 库登记进当前项目的 kb_registry.json，之后就能用库名访问它。' +
+      '只写项目内文件，不改全局注册表、不改插件配置。',
+    parameters: {
+      type: 'object',
+      properties: {
+        dir: {
+          type: 'string',
+          description: '库所在目录（含 .nodekb 的那一层）；绝对路径或相对本会话工作区。也可以直接传 .nodekb 目录。',
+        },
+        name: { type: 'string', description: '库名，缺省取目录名。' },
+        hidden: { type: 'boolean', description: '登记但不出现在库列表里（给老文档里的别名用）。' },
+      },
+      required: ['dir'],
+    },
+    output: {
+      schema: {},
+      render: (_args, value) => text(value.text),
+    },
+    async execute(args, exec) {
+      const src = workspaceSource(config, exec)
+      const ws = src.path
+      const raw = typeof args.dir === 'string' ? args.dir.trim() : ''
+      if (!raw) throw new Error('dir 不能为空：传库所在目录（含 .nodekb 的那一层）')
+      const p = path.resolve(ws, raw)
+      const dir = path.basename(p) === '.nodekb' ? path.dirname(p) : p
+      const nodekb = path.join(dir, '.nodekb')
+      let isDirNow = false
+      try {
+        isDirNow = fs.statSync(nodekb).isDirectory()
+      } catch {
+        isDirNow = false
+      }
+      if (!isDirNow) throw new Error(`这里没有 .nodekb: ${nodekb}（先 kb_init 建库，或确认目录）`)
+      const name = (typeof args.name === 'string' && args.name.trim()) || path.basename(dir)
+      const res = writeProjectRegistry({ workspace: ws, name, dir, hidden: args.hidden === true })
+      const lines = [
+        `已登记: ${res.name} → ${res.path}${res.replaced ? '（覆盖了同名登记）' : ''}`,
+        `写入: ${res.file}`,
+        `之后可直接用 kb="${res.name}"；这个文件建议随仓库一起提交，换台机器就能用。`,
+      ]
+      return { text: lines.join('\n'), name: res.name, dir: res.path, file: res.file }
     },
   })
 

package/package.json

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

package/skills/project-node-memory-guide/SKILL.md

@@ -79,5 +79,6 @@ kb_write target=doc/03-...md          mode=append  content=...
 
 ## 注意事项
 
+0. 库定位找不到时先 `kb_list`：它会写明本会话判定的工作区、来源（会话头 / 配置 / 面板）与每个库的绝对路径。已有的库用 `kb_register dir=<库目录> name=<名字>` 登记进项目的 `kb_registry.json`，不要让人去改插件配置。
 1. 不要把整段对话贴进 `doc/` —— 记的是过程，不是结论。
 2. 不要把同一件事在 `doc/` 和 `lessons/` 各写一份 —— 抽成 `<tscl>` 定义，两处都引用它。