project-node-memory 1.1.2 → 1.1.4

package/README.md

@@ -104,7 +104,6 @@ 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 缺失时只说明，不报错）                                  |
 
 ## 库怎么定位
@@ -184,10 +183,27 @@ config:
 同一 `tscl` id 全库只能定义一次，且不能与节点 TID 同名。
 旧写法 `[[TID]]` 仍兼容（有定义时当宏、否则当链接），`kb_diag` 会 warning，2.0 移除。
 
+## 从 1.0 升到 1.1
+
+数据格式没变——md 还是 md，TID 还是那些 TID，插件卸了照样能读。变化只有两条：
+
+1. **`[[x]]` 现在只出链接**，不再把被引用节点的正文复制进来（要复制原文请显式写 `<tscl>`）。
+   好处是引用不再撑大渲染结果，位置型小节 `## 3.1` 也能点了。
+2. **`kb_init` 不再建 `facts/`**。已有的 `facts/` 不会被动，`kb_read`/`kb_search` 照常；只是新库默认只有
+   `doc/ lessons/ todo/ index/`，事实改写成 `<tscl>` 定义放进它所属的 `doc/` 里。
+
+老库要不要迁？**不迁也能用**，只是 `kb_diag` 会给每条裸引用一条 warning。要迁就让 Agent 按
+`kb_diag` 的清单逐条改成 `[[node="…"]]` / `[[tscl="…"]]`（只改写法，不动 TID 与文件）：
+
+```text
+kb_diag                                    # 列出每条 `旧语法引用`
+kb_write mode=node target=<TID> content=…  # 逐条改，或直接改 md 再 kb_diag 复验
+```
+
 ## 自检（不装 DSH 也能跑）
 
 ```bash
-node scripts/check.mjs      # 275 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / 提示词段落 / 随包技能
+node scripts/check.mjs      # 275 项：清单契约 / 工具 / 路由 / 客户端槽位 / 改名改写 / 建库写库 / tscl / 提示词段落 / 随包技能
 node test/parity.mjs        # 与 Python 原实现逐条对拍（需要 python 与 nodekb 源码）
 ```
 

package/README_EN.md

@@ -101,7 +101,6 @@ 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
@@ -163,10 +162,31 @@ as structure (a `##` there is not a heading); a `tscl` id may be defined exactly
 collide with a node TID. The old `[[TID]]` form still works (macro when a definition exists, link
 otherwise) with a `kb_diag` warning, and goes away in 2.0.
 
+## Upgrading from 1.0
+
+The data format is unchanged — Markdown stays Markdown, TIDs stay the same, and the library remains
+readable after the plugin is removed. Only two things changed:
+
+1. **`[[x]]` now renders a link only**; it no longer copies the referenced node's body into the
+   output (use an explicit `<tscl>` for that). References stop inflating rendered size, and
+   positional sections (`## 3.1`) become clickable.
+2. **`kb_init` no longer creates `facts/`.** Existing `facts/` folders are untouched and still
+   readable/searchable; new libraries get `doc/ lessons/ todo/ index/` only, and facts become
+   `<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, have the agent walk the `kb_diag` list and fix each one (syntax only, no
+TID or file changes):
+
+```text
+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
+```
+
 ## Self-check (no DSH required)
 
 ```bash
-node scripts/check.mjs      # 275 checks: manifest contract / tools / routes / client slots / rename rewriting / scaffold + write / prompt section / bundled skill
+node scripts/check.mjs      # 275 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/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'
@@ -310,33 +309,6 @@ 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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-node-memory",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "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 }