project-node-memory 1.1.3 → 1.2.1

package/README.md

@@ -104,13 +104,14 @@ config:
 | `kb_init`       | 建 `.nodekb` 骨架（幂等），铺出 `doc/ lessons/ todo/ index/` 与落位约定                 |
 | `kb_write`      | 写库：`append` / `replace` / `create` / `node`（就地改写一个 `<node>` 块）；写前校验、写后自检 |
 | `kb_rename`     | 文件改名 + 全库引用一起改写；写前重读，别人刚改的不覆盖                                        |
-| `kb_migrate`    | 旧语法裸引用 `[[x]]` → `[[node="x"]]` / `[[tscl="x"]]`；**默认只演练**，`dry_run=false` 才落盘    |
 | `kb_vcs_status` | 库内嵌 git 的快照历史与未提交改动（git 缺失时只说明，不报错）                                  |
 
 ## 库怎么定位
 
-1. `lib` 参数给路径（技能目录，或其下的 `.nodekb`）——必须落在工作区或已注册库内
-2. `kb` 参数给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）
+所有 `kb_*` 工具只有一个定位参数 `kb`，它同时接受**名字**与**路径**：
+
+1. `kb` 给路径（技能目录，或其下的 `.nodekb`，绝对或相对工作区）——必须落在工作区或已注册库内
+2. `kb` 给名字（注册表里的名字，或工作区里发现的名字，如某个技能名）
 3. 都不给：工作区自带的 `.nodekb/` → 工作区里发现且唯一的库 → 注册表里唯一的库
 
 **自动发现**：给了工作区之后，库里不只在工作区根找，还会按约定位置下钻（有界 BFS，默认 2 层）：
@@ -193,20 +194,18 @@ config:
 2. **`kb_init` 不再建 `facts/`**。已有的 `facts/` 不会被动，`kb_read`/`kb_search` 照常；只是新库默认只有
    `doc/ lessons/ todo/ index/`，事实改写成 `<tscl>` 定义放进它所属的 `doc/` 里。
 
-老库要不要迁？**不迁也能用**，只是 `kb_diag` 会给每条裸引用一条 warning。要迁就跑：
+老库要不要迁？**不迁也能用**，只是 `kb_diag` 会给每条裸引用一条 warning。要迁就让 Agent 按
+`kb_diag` 的清单逐条改成 `[[node="…"]]` / `[[tscl="…"]]`（只改写法，不动 TID 与文件）：
 
 ```text
-kb_migrate                        # 演练：报每个文件会改几处、哪些引用本来就悬空
-kb_migrate dry_run=false          # 确认后落盘
+kb_diag                                    # 列出每条 `旧语法引用`
+kb_write mode=node target=<TID> content=…  # 逐条改，或直接改 md 再 kb_diag 复验
 ```
 
-迁移只改写法（`[[doc:x]]` → `[[node="doc:x"]]`，命中定义则 `[[tscl="…"]]`），不动任何 TID、不搬文件，
-所以引用关系与渲染结果都不变；围栏代码块内一律跳过。
-
 ## 自检（不装 DSH 也能跑）
 
 ```bash
-node scripts/check.mjs      # 290 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 迁移 / 提示词段落 / 随包技能
+node scripts/check.mjs      # 280 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
 node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
 ```
 

package/README_EN.md

@@ -101,13 +101,14 @@ The right column renders at most 10,000 characters per view (with a truncation n
 | `kb_init` | Scaffold `.nodekb` (idempotent): `doc/ lessons/ todo/ index/` plus placement conventions |
 | `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_migrate` | Rewrites legacy bare refs `[[x]]` into `[[node="x"]]` / `[[tscl="x"]]`; **dry-run by default**, pass `dry_run=false` to write |
 | `kb_vcs_status` | Snapshot history and uncommitted changes of the library's embedded git repo (explains itself when git is missing) |
 
 ## 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):
@@ -176,21 +177,18 @@ readable after the plugin is removed. Only two things changed:
    `<tscl>` definitions inside the `doc/` file they belong to.
 
 Do old libraries need migrating? **No** — they keep working, `kb_diag` just emits one warning per
-bare reference. To migrate:
+bare reference. To migrate, have the agent walk the `kb_diag` list and fix each one (syntax only, no
+TID or file changes):
 
 ```text
-kb_migrate                        # dry run: how many refs per file, which ones are already dangling
-kb_migrate dry_run=false          # write
+kb_diag                                    # lists every `旧语法引用` (legacy bare ref)
+kb_write mode=node target=<TID> content=…  # fix one at a time, or edit the md and re-run kb_diag
 ```
 
-Migration only changes syntax (`[[doc:x]]` → `[[node="doc:x"]]`, or `[[tscl="…"]]` when the id is a
-definition). No TID changes, no file moves, so references and rendered output stay identical; fenced
-code blocks are skipped.
-
 ## Self-check (no DSH required)
 
 ```bash
-node scripts/check.mjs      # 290 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / tscl / migration / 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/prompt.js

@@ -21,7 +21,7 @@ export const DEFAULT_PROMPT = [
   '- 读库：先 `kb_read mode=toc` 看结构（几百 token），再按 TID 读一支；找不到就 `kb_search`。别一次性把整库读进上下文。',
   '- 改名前先 `kb_backlinks`，改名用 `kb_rename`（会重写全库引用并跳过被并发改过的文件）。',
   '- 引用分两种，别混：**结构**用 `[[node="doc:03-build:3.1"]]`（只出一个链接，不复制正文）；**值只写一处**——定义 `<tscl id="fact:abi">…</tscl>`，各处写 `[[tscl="fact:abi"]]`，同一 id 全库只能定义一次。',
-  '- 旧写法 `[[TID]]` 仍能用但 `kb_diag` 会 warning，2.0 移除（老库可先跑 `kb_migrate` 演练，确认后 `dry_run=false` 批量迁）。',
+  '- 旧写法 `[[TID]]` 仍能用但 `kb_diag` 会 warning，2.0 移除（老库按 diag 清单逐处改成 `[[node=…]]` / `[[tscl=…]]`）。',
 ].join('\n')
 
 function textOf(config) {

package/lib/host/routes.js

@@ -12,7 +12,6 @@ import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
 import { extractRefs } from '../engine/parse.js'
 import { renameFileNode, formatRename } from '../engine/rename.js'
-import { migrateLibrary, formatMigrate } from '../engine/migrate.js'
 import { openLibrary, knownLibraries, whereInfo, workspaceOf } from './runtime.js'
 import { promptState } from './prompt.js'
 import { skillState } from './skill.js'
@@ -280,14 +279,6 @@ export function registerRoutes(ctx, config) {
         return
       }
 
-      if (url.pathname === `${PREFIX}/migrate`) {
-        const lib = open()
-        const dryRun = !(q.get('dry_run') === '0' || q.get('dry_run') === 'false')
-        const report = migrateLibrary(lib, { dryRun })
-        send(res, 200, { kb: lib.name, ...report, text: formatMigrate(report) })
-        return
-      }
-
       send(res, 404, { error: `未知端点: ${url.pathname}` })
     } catch (e) {
       send(res, 400, { error: e && e.message ? e.message : String(e) })

package/lib/host/tools.js

@@ -14,7 +14,6 @@ import { search, formatSearch } from '../engine/search.js'
 import { diag } from '../engine/diag.js'
 import { extractRefs } from '../engine/parse.js'
 import { renameFileNode, formatRename } from '../engine/rename.js'
-import { migrateLibrary, formatMigrate } from '../engine/migrate.js'
 import { scaffold } from '../engine/scaffold.js'
 import { writeInto } from '../engine/write.js'
 import { isInside } from '../engine/registry.js'
@@ -31,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) {
@@ -61,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}` : ''}`)
@@ -101,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'],
@@ -174,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 条，用于翻页。' },
@@ -215,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 也算失败。' },
       },
     },
@@ -247,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'],
     },
@@ -283,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: {
@@ -293,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'],
     },
@@ -310,44 +294,15 @@ export function buildTools(ctx, config) {
     },
   })
 
-  // ── kb_migrate ───────────────────────────────────────────────────────────
-  tools.push({
-    name: 'kb_migrate',
-    description:
-      '把库里的旧写法裸引用 [[x]] 迁成 1.1 的双语法：[[tscl="x"]]（x 是定义）或 [[node="x"]]（x 是节点 TID）。' +
-      '默认只演练（dry_run 缺省为 true），返回每个文件会改几处、哪些引用指向不存在的 id 会原样保留。' +
-      '围栏代码块内不动；写前重读校验，别人刚改过的文件不覆盖。',
-    parameters: {
-      type: 'object',
-      properties: {
-        dry_run: { type: 'boolean', description: '默认 true（只报告）。确认无误后传 false 才真正写盘。' },
-        kb: KB_PARAM,
-        lib: LIB_PARAM,
-      },
-    },
-    output: {
-      schema: {},
-      render: (_args, value) => text(value.text),
-    },
-    async execute(args, exec) {
-      const lib = locate(config, exec, args)
-      const dryRun = args.dry_run === undefined ? true : Boolean(args.dry_run)
-      const report = migrateLibrary(lib, { dryRun })
-      return { ...report, kb: lib.name, text: warnPrefix(lib) + formatMigrate(report) }
-    },
-  })
-
   // ── kb_vcs_status ────────────────────────────────────────────────────────
   tools.push({
     name: 'kb_vcs_status',
     description:
-      '查看知识库内嵌 git 仓库的状态（最近提交 + 未提交改动）。nodekb 每次解析后会自动快照，' +
-      '所以这里能看到「库的改动历史」；文件系统上有改动但没进快照时也会列出来。git 不可用时返回说明而不报错。',
+      '库内嵌 git 的快照历史与未提交改动（每次解析后自动快照）；git 不可用时只说明不报错。',
     parameters: {
       type: 'object',
       properties: {
         kb: KB_PARAM,
-        lib: LIB_PARAM,
       },
     },
     output: {
@@ -393,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: {
@@ -431,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: {
@@ -449,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.3",
+  "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",

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

@@ -55,7 +55,7 @@ kb_search query=...         # toc 里找不到再搜
 - 定义块内部的 `##` **不会**变成节点——它只是文本。
 
 旧写法 `[[TID]]` 仍能解析（有定义时当宏、否则当链接），但 `kb_diag` 会 warning，2.0 移除。
-接手老库时先跑 `kb_migrate`（默认只演练），看清每处会改成 `[[node=…]]` 还是 `[[tscl=…]]` 再 `dry_run=false`。
+接手老库时按 `kb_diag` 的「旧语法引用」清单逐处改成 `[[node=…]]` 或 `[[tscl=…]]`，改完再跑一次 `kb_diag`。
 
 ## TID 规则
 

package/lib/engine/migrate.js

@@ -1,171 +0,0 @@
-/**
- * migrate —— 把旧写法裸引用 `[[x]]` 迁成 1.1 的双语法。
- *
- * 规则：
- *   - x 是 tscl 定义 id  → `[[tscl="x"]]`（值嵌入）
- *   - x 是节点 TID        → `[[node="x"]]`（链接）
- *   - 两者都不是          → 原样保留，记进 unresolved（本来就悬空，迁移不该猜）
- *
- * 三条纪律与 rename 一致：围栏内不动、写前重读复核 mtime/size、默认只演练（dry_run）。
- */
-
-import fs from 'node:fs'
-import path from 'node:path'
-import { ROOT_TID } from './mdlib.js'
-
-const FENCE = '```'
-const BARE_REF = /\[\[([^[\]"=\s][^[\]]*)\]\]/g
-
-function absOf(lib, node) {
-  const raw = String(node.source || '').split('#')[0]
-  if (!raw) return ''
-  return path.isAbsolute(raw) ? path.normalize(raw) : path.join(lib.nodekb, raw)
-}
-
-function relOf(lib, abs) {
-  return path.relative(lib.nodekb, abs).split(path.sep).join('/')
-}
-
-function allMarkdown(nodekb) {
-  const out = []
-  const walk = (d) => {
-    let entries
-    try {
-      entries = fs.readdirSync(d, { withFileTypes: true })
-    } catch {
-      return
-    }
-    for (const e of entries) {
-      if (e.name.startsWith('.')) continue
-      const p = path.join(d, e.name)
-      if (e.isDirectory()) walk(p)
-      else if (e.name.endsWith('.md')) out.push(p)
-    }
-  }
-  walk(nodekb)
-  return out
-}
-
-/** 纯函数：把一段 md 文本里的裸引用改写（可单测） */
-export function migrateText(text, { isTid, isDef }) {
-  const out = []
-  const hits = { node: 0, tscl: 0, unresolved: [] }
-  let fenced = false
-  for (const line of String(text).split('\n')) {
-    if (line.trim().startsWith(FENCE)) {
-      fenced = !fenced
-      out.push(line)
-      continue
-    }
-    if (fenced) {
-      out.push(line)
-      continue
-    }
-    out.push(
-      line.replace(BARE_REF, (whole, inner) => {
-        const id = inner.trim()
-        if (isDef(id)) {
-          hits.tscl += 1
-          return `[[tscl="${id}"]]`
-        }
-        if (isTid(id)) {
-          hits.node += 1
-          return `[[node="${id}"]]`
-        }
-        hits.unresolved.push(id)
-        return whole
-      }),
-    )
-  }
-  return { text: out.join('\n'), hits }
-}
-
-/**
- * 迁移整个库。
- * @param {{nodekb:string, nodes:Map, defs?:Map}} lib openLibrary 的结果
- * @param {{dryRun?:boolean}} [opts] 默认演练
- */
-export function migrateLibrary(lib, opts = {}) {
-  const dryRun = opts.dryRun !== false
-  const defs = lib.defs || new Map()
-  const nodes = lib.nodes
-  const isTid = (id) => nodes.has(id)
-  const isDef = (id) => defs.has(id)
-
-  const report = { dry_run: dryRun, files: [], node: 0, tscl: 0, unresolved: [], skipped: [] }
-  const edits = []
-  const visited = new Set()
-
-  for (const node of nodes.values()) {
-    if (node.kind !== 'file') continue
-    const abs = absOf(lib, node)
-    if (!abs) continue
-    visited.add(path.resolve(abs))
-    let text
-    let st1
-    try {
-      st1 = fs.statSync(abs)
-      text = fs.readFileSync(abs, 'utf8')
-    } catch (e) {
-      report.skipped.push({ path: relOf(lib, abs), why: `读失败: ${e.message}` })
-      continue
-    }
-    if (!text.includes('[[')) continue
-    const { text: next, hits } = migrateText(text, { isTid, isDef })
-    const changed = hits.node + hits.tscl
-    for (const u of hits.unresolved) report.unresolved.push({ path: relOf(lib, abs), ref: u })
-    if (!changed) continue
-    report.node += hits.node
-    report.tscl += hits.tscl
-    report.files.push({ path: relOf(lib, abs), count: changed, node: hits.node, tscl: hits.tscl })
-    edits.push({ abs, st1, next, path: relOf(lib, abs) })
-  }
-
-  if (!dryRun) {
-    for (const e of edits) {
-      try {
-        const st2 = fs.statSync(e.abs)
-        if (st2.mtimeMs !== e.st1.mtimeMs || st2.size !== e.st1.size) {
-          report.skipped.push({ path: e.path, why: '读后被改动，未覆盖' })
-          continue
-        }
-        fs.writeFileSync(e.abs, e.next, 'utf8')
-      } catch (err) {
-        report.skipped.push({ path: e.path, why: err.message })
-      }
-    }
-  }
-
-  // 兜底：只报「存在但没进索引」的 md（解析失败的孤儿文件），不重复报已处理的
-  for (const abs of allMarkdown(lib.nodekb)) {
-    if (visited.has(path.resolve(abs))) continue
-    report.skipped.push({ path: relOf(lib, abs), why: '未被解析为目标节点，未处理' })
-  }
-
-  return report
-}
-
-export function formatMigrate(report) {
-  const lines = []
-  lines.push(report.dry_run ? '（演练，未落盘；确认后传 dry_run=false 才写）' : '已写入')
-  const total = report.files.reduce((s, f) => s + f.count, 0)
-  if (!total) {
-    lines.push('没有需要迁移的裸引用')
-  } else {
-    lines.push(`共 ${total} 处裸引用 → ${report.tscl} 处 [[tscl="…"]]、${report.node} 处 [[node="…"]]`)
-    for (const f of report.files.slice(0, 20)) lines.push(`  - ${f.path}: ${f.count}（tscl ${f.tscl} / node ${f.node}）`)
-    if (report.files.length > 20) lines.push(`  …另有 ${report.files.length - 20} 个文件`)
-  }
-  if (report.unresolved.length) {
-    lines.push(`保留未改 ${report.unresolved.length} 处（指向的 id 既不是节点也不是定义，本来悬空）：`)
-    for (const u of report.unresolved.slice(0, 10)) lines.push(`  - ${u.path}: [[${u.ref}]]`)
-    if (report.unresolved.length > 10) lines.push(`  …另有 ${report.unresolved.length - 10} 处`)
-  }
-  if (report.skipped.length) {
-    lines.push(`跳过 ${report.skipped.length} 个文件：`)
-    for (const s of report.skipped.slice(0, 10)) lines.push(`  - ${s.path}: ${s.why}`)
-  }
-  return lines.join('\n')
-}
-
-export { ROOT_TID }