dsh-memory-nebula 0.0.0-stage → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,533 @@
+# 更新记录
+
+本文件记录「记忆星图」每个版本改了什么。日期为落盘日期。
+
+## 1.1.1 — 2026-11-10
+
+主题「上架」：从 npm 包直接托管 DSH 插件市场索引，不依赖第二个站点。
+
+### 插件市场条目
+
+```text
+https://cdn.jsdelivr.net/npm/dsh-memory-nebula@1.1.1/market/index.json
+```
+
+- `market/index.json`：format 1 索引，分类「记忆与检索」，标签「本地优先 / 可视化 / 中英双语」；
+  当前版本指向 npm 源 `dsh-memory-nebula@1.1.1`，`engines.dsh >= 0.2.2-rc.1`。
+- `market/assets/icon.svg`：256×256 的星图图标，随包发布。
+- `locale/zh.json` / `locale/en.json`：市场卡片标题、描述与详情文档入口。
+- `docs/market.zh.md` / `docs/market.en.md`：双语的详细介绍，含空态、示例、证据链、
+  范围快照、10k 基准与安装命令；图片走 `docs/assets/`。
+- 索引通过 `@deepseek-ai/dsh-plugin-market-index` 的 `parseMarketIndex` 校验；
+  图标相对索引解析为 jsDelivr 上的绝对 URL。
+- 单测 84 → **87**（市场索引/双语详情/图片路径 3 项），release-check 增加上架构件检查。
+
+## 1.1.0 — 2026-11-10
+
+主题「装得上」：插件跑不起来时，先别猜，跑一遍只读体检。
+
+### `memory-nebula-doctor`
+
+```bash
+node node_modules/dsh-memory-nebula/scripts/doctor.mjs --profile <profile目录>
+```
+
+- 检查 Node 下界、包内关键文件、profile 的 `dependencies` 与 `dsh.profile.bundles`、
+  `node_modules` 里的实际版本与 `cordis.patch.yml`。
+- 可选 `--root` 额外记忆库根、`--base` ping 正在跑的实例；`--json` 给自动化。
+- 只读：不安装、不改 profile、不写记忆库；warn 不阻断，fail 才退出 1。
+- 已在本机 desktop profile 实测：8 项全过（runtime / package / files / profile /
+  dependency / bundle / installed / sources）。
+- 单测 76 → **84**（doctor 8 项），新增 `npm run doctor` 与 bin `memory-nebula-doctor`。
+
+## 1.0.1 — 2026-11-10
+
+主题「下界」：把 `engines.node >= 22.13.0` 从承诺变成实测。
+
+- Node **v22.13.0**（LTS 下界）跑通 76/76 单测、release-check、63/63 冒烟；
+  `--diagnose` 在 1,945 记忆 / 9,229 连接上建图 547ms、RSS 147MB、退出 0。
+- `docs/compatibility.md` 把 Node 22 从「预期可用」移到「已验证」；
+  `docs/verified.md` 增加 1.0.1 证据段。
+- 不改运行时代码；版本号只用于区分这次验证过的文档与包。
+
+## 1.0.0 — 2026-11-10
+
+主题「敢卖」：把「出问题时怎么支持」和「换台机器怎么装」写成可执行的东西。
+功能不扩张，先把可交付性补齐。
+
+### 一键诊断
+
+- **`GET /diagnostics`**：纯文本报告版本、构建、启动时间、宿主/独立引擎模式、Node/系统/架构、
+  PID/运行时长/RSS、图规模（节点/边/工作区/会话）、建图耗时、来源身份（key/title/adapter/size）、
+  能力清单与最近错误；**不读正文、不带本机路径**。
+- **`node lib/standalone.mjs --diagnose`**：只建一次图、打印同一份报告然后退出；适合客户机器上
+  远程指导，不需要先起端口。
+- **页面 `?` →「复制诊断」**：在报告上补充浏览器 UA、语言、屏幕/DPR、WebGL renderer、
+  当前视图与最近一次页面错误；不含记忆正文，可直接贴给支持。
+- 新增 `diagnostics` 能力标记；旧宿主没有该路由时页面不依赖它，按钮仍可用本地信息生成报告。
+
+### 兼容与分发
+
+- **`docs/compatibility.md`**：分开写「已验证 / 预期可用但未实测 / 明确不支持」；
+  只把真跑过的组合写成支持，未测平台不承诺「全平台」。
+- **`docs/distribution.md`**：tgz 校验与安装、升级、回滚、卸载、支持流程、市场文案、
+  发布检查清单；明确 npm publish 需维护者执行。
+- README / README.en 的安装名、版本、文档表同步到 1.0.0。
+
+### 测试与包
+
+- 单测 73 → **76**：诊断报告结构、路径/正文不泄漏、空图格式化；
+  HTTP `/diagnostics` 的 content-type、no-store、无路径断言。
+- 冒烟 56 → **63**：新增 `/diagnostics` 契约检查。
+- 发布包 61 → **64 文件**（新增 diagnostics.js 与两份文档），版本 `1.0.0`。
+
+## 0.9.0 — 2026-11-10
+
+主题「说英文」：界面中英双语，中文仍是源语言，英文查表替换，查不到就回退中文。
+
+### 国际化
+
+- **`lib/web/i18n.js`**：以中文原文为 key 的 `EN` 字典（400+ 条），提供 `t()` 插值、
+  `applyDom()` 处理静态 `data-zh*`、`setLang()` / `toggle()`；语言优先级
+  `?lang=` → localStorage `nebula.lang` → `navigator.language`。
+- **动态文案**：`app.js` 399 处、`api.js` 13 处、`render.js` 2 处、`space3d.js` 5 处
+  中文串包成 `T('…')`；HTML 片段与 `ws:日记` 等逻辑字符串跳过，避免把标签当 key。
+- **静态文案**：顶栏、搜索框、面板标题、导出菜单、看板 tab、快捷键浮层、时间条、
+  错误页全部 `data-zh`；顶栏新增语言按钮（中文显示 `EN`，英文显示 `中`）。
+- **快照**：`share.js` 内联 `i18n.js`，离线快照同样可切英文；`/share?lang=en` 生效。
+- **服务端解释句**：`localizeWhy()` 翻译「直接命中查询词」「被读过 N 次」
+  「经由「X」的 Y 关联扩散而来」，并给数组加类型守卫。
+- **英文排版**：`html.lang-en` 专用间距/字号；来源计数、快捷键面板、统计条不再挤压；
+  英文截图 `dev/shot/i18n-en.png`、空态 `empty-en.png`、示例 `demo-en.png`、
+  快照 `i18n-snapshot.png`。
+
+### 验证
+
+- 单测 65 → 73：新增 `test/i18n.test.mjs` 7 项（字典非空、回退、语言来源、applyDom、
+  T/静态 key 全覆盖）与快照内联 i18n 1 项。
+- 英文实机：顶栏/搜索/左栏/看板/详情/快捷键盘/新手三步/离线快照全部英文；
+  `window.__nebulaErrors` 为空；820 宽无横向溢出；快照 0 外部请求。
+- 中文侧回归：`?lang=zh` 下空态、示例、详情、看板正常；默认随系统语言。
+
+## 0.8.0 — 2026-11-10
+
+主题「一万条也敢开」：先有可复现的 10k 基准，再把首屏从 17 秒压到一秒以内。
+
+### 性能
+
+- **随包基准** `scripts/bench.mjs`：确定性合成 10,000 节点 / 78,593 边、20 工作区、
+  900 会话；测建图、检索、体检、证据链、单文件快照与内存。`npm run bench` 可直接复跑。
+- **首屏 16.96s → 0.67s**：超过 3,000 节点时不再播生长动画、不再跑 420 轮力导向，
+  按工作区初始布局直接出图；1,000–3,000 节点把轮次降到 180。
+- **建图 4.9s → 1.3s**：大图关键词候选只取 `node.sig` 的稀有词，实体配对跳过超大共享组；
+  分词器从三条正则改为单次字符扫描。
+- **检索 188ms → 4.4ms**：按图缓存 token 表与邻接表，节点已有 tokens 时不再重复分词。
+- **体检 5.3s → 0.73s**：`auditHygiene` 只分词一次，dup 用提前退出的 Jaccard，
+  stale 用关键词倒排按 updatedAt 找最近邻。
+- **快照 75ms / 11.6MB**（10,000 节点，含全部正文）。
+
+### 验证
+
+- 目标与实测写进 `docs/benchmarks.md`：建图 1.3s（<3s）、首屏 0.67s（<1.5s）、
+  检索 4.4ms（<80ms）、体检 0.73s（<1.5s）、快照 75ms（<2s）、JS 堆 131MB（<300MB）。
+- headless Edge（软件渲染 1680×874）打开 10k 快照：`elapsed 652–692ms`、`loadMs 63–151ms`、
+  首次 `draw` 13–18ms、`resources 0`、无 JS 异常；截图 `dev/shot/bench-10k.png`。
+- 单测 65/65、冒烟 56/56、安全探针 21/21；release-check 全绿。
+
+### 说明
+
+- 3D 视图不在 10k 基准内；超过 3,000 条默认停在 2D，手动切 3D 会提示先筛选，
+  避免在软件 GL 下等太久。
+- 5 万条以上仍需分页/裁剪，当前只对一万条给出预算与实测。
+
+## 0.7.1 — 2026-11-10
+
+主题「把出口补上」：0.7.0 留下的两个小口子，加上实测中发现的一处状态残留。
+
+### 修复
+
+- **搜索空结果有出口了**：空态卡片新增「清空搜索」「只看一个工作区」「看看示例」三个按钮，
+  不再只有一句「换更短的词试试」；`Esc` 与「清空搜索」共用同一段收尾（清输入、清高亮、还焦点）。
+- **「种子扩散」说人话**：详情里按钮加 `title`，下面补一句「扩散不是搜索：从这条出发，
+  沿已有连接看 2 跳内的邻居」，不用术语解释术语。
+- **从真实库进示例时，新手卡片不再留在画面上**：`showOnboard` 先收旧卡片再判断模式，
+  `enterDemo` 拉完图后也调用一次；示例/快照中依旧不显示引导。
+
+### 验证
+
+- 单测 65/65、冒烟 56/56、安全探针 21/21；release-check 全绿。
+- headless Edge 实测：搜索 `zzzz-not-a-word` 出现三个按钮；点「看看示例」进 64 条示例星系，
+  `#onboard` 不存在；示例里搜「索引」打开详情，`.seed-note` 文案正确；`window.__nebulaErrors` 为空。
+
+## 0.7.0 — 2026-11-10
+
+主题「关灯与带路」：分享前能先关掉不该出门的部分，第一次进来有人领着走三步。
+
+### 新功能
+
+- **导出隐藏规则**：`GET /share?hide=level:<层级>&hide=ws:<工作区>&hide=project:<项目>&hide=status:<状态>`，
+  可重复传，也可逗号分隔。白名单之外直接 400，不静默忽略——隐私规则「以为藏了」比报错危险。
+  隐藏发生在范围切片之后：先选分享哪一片，再从中剔掉不该出门的记忆。
+- **隐藏后的自洽**：节点、边、正文、`stats`、`byWorkspace`、`byLevel`、`clusters`、体检全部按剩余节点重算；
+  范围被清空返回 404，焦点起点被隐藏返回 400，错误信息说清是哪条规则。
+- **快照脱敏**：`graph.sources` 与 `overview.sources` 只留名字与规模，去掉本机 `path` / `dbPath`；
+  概览顶层的 `dbPath`、`lastError` 不再进入快照。分享文件里没有本机路径。
+- **导出菜单开关**：「隐去「日记」工作区」勾选后作用于整图 / 当前工作区 / 选中节点三档导出；
+  只影响导出的快照，不改记忆库。导出该工作区本身时给提示，不生成空文件。
+- **新手三步**：有数据的库首次打开出现一张可跳过的卡片——搜一个词、点开一条看证据、
+  看一条真实证据链（不是示意图）。每步都能直接点；三步走完自动收起。
+  跳过只写 `localStorage`（`nebula.onboarded.v1`），不碰记忆库；按 `?` 打开快捷键一览可「重看新手三步」。
+
+### 修复
+
+- 快照的来源与概览不再携带本机路径、数据库位置和上次错误文本。
+
+### 接口与测试
+
+- `/share` 新增 `hide` 参数；响应 payload 的 `scope` 增加 `hidden` 与 `hide`。
+- 单元测试 59 → 65（share +4、http +2），冒烟 53 → 56；覆盖 hide 解析、整区剔除、起点被隐藏、
+  空范围、脱敏与非法规则。全量 65/65 通过。
+- 实机：示例 `hide=ws:日记` → 57 节点 / 66 边 / 已隐去 7 条；`scope=ws:日记&hide=ws:日记` → 404；
+  真实库首次打开三步卡片可点、跳过写入标记、刷新不再出现、按 `?` 可重看，无 JS 异常。
+
+## 0.6.0 — 2026-11-10
+
+主题「切片」：分享一个项目，而不是整座库。
+
+`/share` 原本只能导出整张图。真实用户的图里混着日记、私事和别的项目，要发给同事或客户
+就只能整份发——这一版把「范围」变成一等公民：范围外的节点、边、正文、体检结论都不会
+进入快照，收件人看到的数字也只属于这一片。
+
+### 新功能
+
+- **范围快照**：`GET /share?scope=ws:<工作区>`、`?scope=project:<项目>`、
+  `?scope=focus:<节点 id>&hops=<1-5>`。焦点模式按无向边做 N 跳扩散（默认 2 跳）；
+  范围为空返回 404，格式错误返回 400。
+- **切片自洽**：节点重新编号、边重映射，`degree` / `stats` / `clusters` / 体检全部按切片重算；
+  `cards`、`truth`、`externals` 这些「整库视角」的摘要留空，避免把全库结论带进局部快照。
+- **快照范围标签**：顶部从「离线快照」变成「离线快照 · 工作区 · 星港产品」/
+  「项目 · …」/「以「…」为中心 · 2 跳」，下载文件名带 `-ws-` / `-project-` / `-focus-` 后缀。
+- **导出菜单三档**：新增「当前工作区 · 单文件 HTML」与「选中节点 2 跳 · 单文件 HTML」；
+  没有选中节点、或工作区筛选不是恰好一个时，给一句人话提示而不是导出错误的范围。
+
+### 修复
+
+- 快照体检、统计、簇不再复用整库结果；切片里的「孤立 / 弱关系 / 重复」只描述这一片。
+
+### 接口与测试
+
+- `/share` 新增 `scope`、`hops` 参数；响应 payload 增加 `scope:{kind,value,label,hops,nodes,edges}`。
+- 单元测试 53 → 59（share +4、http +2），冒烟 51 → 53；覆盖 ws/project/focus 切片、非法范围、未知节点、
+  文件名后缀、范围外正文不泄漏。全量 59/59 通过。
+- 实机：示例库 `ws:xingang` → 32 节点 / 31 边 / 330KB；`focus:xg-weekly&hops=1` → 12/12；
+  真实库选中节点导出 2 跳 → 73 节点 / 193 边 / 462KB，`dy-locker` 不在文件里。
+
+## 0.5.0 — 2026-11-10
+
+主题「第一束光」：第一次打开就能看见东西，也能把整张星图带走。
+这一版补的是「从没数据到看懂」和「从看懂到分享」之间的那段路。
+
+### 新功能
+
+- **示例星系**：内置 61 条虚构记忆、3 个来源节点、6 个工作区与 43 条会话脉络，
+  用和真实库完全相同的 `buildGraph()` 建图（64 节点 / 78 连接），也会出现重复、过长、未读、
+  弱关系这些体检样本。所有接口都接受 `?demo=1`，示例实例惰性创建、整进程共用，
+  非 GET 请求一律 403，`cacheSet` / 事件账本 / 文件监听在示例模式下全部关闭——
+  逛完退出，真实库一个字节都不会变。
+- **首启空态**：空库不再只留一句「还没有星星」，而是给三条路：先写记忆再重建、
+  进示例星系逛一圈、或按 `docs/adapters.md` 接自己的库。顶部有常驻胶囊显示当前处于
+  示例/快照模式，并提供「退出示例」。
+- **单文件快照**：`GET /share` 把当前星图打包成一个自包含 HTML（内联样式、渲染脚本、
+  三维引擎与全部正文），双击即可离线打开；顶部标「离线快照 · 只读 · 生成于 …」，
+  搜索、节点详情、证据链全部在本地计算，轮询/重建/写入按钮自动隐藏或拒绝。
+  导出菜单新增「整张星图 · 单文件 HTML」。
+- **`?demo=1` 直达链接**：`…/memory-nebula/?demo=1` 直接进入示例星系，方便给别人看效果。
+
+### 修复
+
+- **体检的「孤立」与「弱关系」一直是假的**：`auditHygiene()` 按 `e.a/e.b` 统计度数，
+  而生产边是 `{s,t}` / 公开图 `{s,d}`，导致所有节点都被算成孤立、弱关系永远为 0。
+  现在统一经 `edgeEnds()` 解析，并把「弱关系」口径收紧为「度数 ≥10 且没有一条 w≥0.45 的强边」，
+  不再把只是关键词撞得多、但其实有实体关系的节点报出来。
+- **共激活只在文本候选里找**：同一批会话里反复一起出现的两条记忆，如果正文互不相似，
+  永远进不了候选，注释里说的「两次以上共激活也算数」并不成立。现在共激活自身也会补进候选
+  （阈值 1.6），真实库的共激活边从 41 条增加到 171 条。
+- **快照顶部缺生成时间**：快照模式下 `pullGraph()` 跳过了 `resolveBase()`，元信息为空；
+  现在无论在线离线都会先取元信息。
+- **快照正文为空**：`buildGraph()` 的输出只带 `preview`，快照却从图节点取 `content`；
+  改为从原始节点补齐正文（1842 条里 1805 条有正文，其余是来源节点）。
+- **导出 HTML 被 `$&` 咬掉脚本**：字符串式 `replace()` 把 app.js 源码里的 `'\\$&'`
+  当成替换模式，生成物里残留一个外链 `<script src="app.js">`；改为函数式替换。
+- **示例退出 / 空态按钮的作用域错误**：两个处理器分别引用了 `boot()` 内的局部函数和
+  块级 `const`，实机点击抛 `ReferenceError`；已把处理器收回 `boot()`、把变量提到块外。
+- **快照里还摆着「屏蔽」按钮**：点了必然失败；快照与示例模式下不再渲染这个按钮（两者都只读）。
+- **快照下载文件名用 UTC**：页面写「生成于 23:44」，文件名却是 15:44；改为本地时间。
+- **820–1180px 宽度下模式条压住搜索框**：示例/快照条固定在 62px，和顶部搜索重叠；
+  现在 1180px 以下让到搜索框下方（760px 以下再下移），实测 820×900 与 700×900 都不再重叠。
+
+### 接口
+
+- `/ping` 与 `/graph` 增加 `demo` 字段；能力清单新增 `demo`、`share`。
+- 新增 `GET /share`：`text/html; charset=utf-8`，`content-disposition: attachment`，
+  文件名 `memory-nebula-snapshot-YYYY-MM-DD-HH-mm.html`，同样带 `no-store` / `nosniff`。
+- 示例模式复用既有全部只读接口，不新增写路径。
+
+### 测试
+
+- 单测 53 项：原有 37 项 + 示例图结构与体检样本 5 项 + `/share` 自包含与转义 5 项 +
+  HTTP 的 demo 只读 / ETag 304 / CSRF / 未知接口 6 项。
+- 冒烟新增 13 项（示例图、示例检索与证据链、写保护、`/share` 头与自包含），共 51 项。
+
+## 0.4.0 — 2026-11-08
+
+这一版不改功能，改的是「敢不敢交给别人用」：把本机服务的边界收窄、把版本漂移摆到明面上、
+把重复实现与死文件删掉，并补上可重复执行的单测、冒烟、安全探针与发布检查。
+
+### 安全
+
+- **跨站读写**：独立引擎原来对所有来源发 `Access-Control-Allow-Origin: *`，任意网页都能读走本机记忆；
+  所有 POST 也不校验来源，一个 `<form>` 就能触发重建或屏蔽。现在只回显 loopback Origin（127.0.0.1 / localhost / ::1），
+  并带 `Vary: Origin`；非 GET/HEAD 请求同时校验 `Origin` 与 `Sec-Fetch-Site`，跨站一律 403；
+  非本机 `OPTIONS` 也回 403。
+- **请求体**：`readBody` 区分 `too_large`（413）与 `bad_json`（400），不再把坏 JSON 当空对象继续跑；
+  `/ingest` 单次上限 5000 条。
+- **路径穿越**：静态资源只认 6 个白名单文件名，`/../package.json` 返回 404。
+- **响应头**：JSON 与静态文件统一 `nosniff`、`no-store`、`referrer-policy: no-referrer`；页面额外发 CSP
+  （`default-src 'self'`、`frame-ancestors 'self'`、禁止表单提交）与 `x-frame-options: SAMEORIGIN`。
+- **高亮转义**：搜索高亮先转义再一次性插入 `<mark>`，并把 `amp/lt/gt/quot` 这类实体会被二次解析的词排除，
+  记忆正文里的 `<img onerror=…>` 不会被当 HTML 执行。
+
+### 兼容与诊断
+
+- **版本漂移可见**：`/ping` 新增 `ok / version / build / startedAt / mode / capabilities`。
+  页面拿到旧宿主（缺 `sources/bridge/ledger/ingest`）时在顶部显示琥珀色横幅，给出两条可操作路径：
+  重启 DSH，或在插件目录跑 `powershell -ExecutionPolicy Bypass -File sidecar.ps1 start` 后刷新。
+  独立引擎接管时提示一次「已切到独立引擎」；同一构建不再重复打扰。
+- **`/graph` 支持 ETag 与 `If-None-Match`**：12 秒轮询在没变化时拿 304，不再每次重传整张图。
+- **冷启动并发**：多个调用同时 `refresh()` 时，后到的等第一轮建完再返回，不再拿到空图。
+- **`--root` 生效**：`Nebula` 构造器同时接受 `roots` 与 `log`（原来只认 `extraRoots`/`logger`，独立引擎的参数被静默忽略）；
+  端口越界、`--root` 缺值都会明确报错并非零退出。
+- **独立引擎 CLI**：`memory-nebula --port/--root/--help/--version`，带 shebang，可作为 `bin` 使用。
+- **探测降噪**：独立引擎自己的页面（同源且 `mode: standalone`）不再去探宿主 7890，
+  浏览器控制台没有多余的 `ERR_CONNECTION_REFUSED`。
+- **可移植的默认根**：不再写死 `D:\document` / `C:\Users\<名字>\Documents`，改为「我的文档 + 当前目录」；
+  `--root` 仍可追加任意目录。
+- **sidecar 可靠性**：`sidecar.ps1` 自动找 node（PATH → 常见安装位置 → `$DSH_HOME/dsh-runtimes`），
+  `-Root` 默认当前目录，`status` / `stop` 只作用于同一个 `--port`；`start` 不再用
+  `Start-Process -RedirectStandardOutput`（Windows PowerShell 5.1 会挂住调用方 70 秒以上），
+  改由引擎 `--log` 自己写日志。启动前先探端口，被占用时 300ms 内退出。
+
+### 页面
+
+- 无障碍：画布标记为装饰、看板/项目卡片/命令面板补 `role="dialog"` 与名称、关闭按钮与搜索框/时间滑杆补 `aria-label`、
+  连接状态与提示条 `aria-live`；页脚版本取自 `/ping`，与包版本一致。
+
+### 清理
+
+- 删除 `lib/host/graph.debug.js`（graph.js 的调试副本，无任何 import）与 `lib/host/hygiene.js`
+  （与 `graph.js` 的 `auditHygiene` 重复，`nebula.js` 里的懒加载分支从未被调用）。
+- 删除 `lib/index.js` 末尾未使用的 `samePath` / `listDir` 与重复的 `readdirSync` import。
+- 前端不再用 `document.write` 拼时间戳加载脚本；静态文件本身 `no-store`，刷新即最新。
+- `BUILD` 改为递归扫描 `lib` 下全部 `.m?js`，改任何模块都会推进构建号（原来只盯 8 个文件）。
+
+### 测试与发布
+
+- 新增 `test/`：`text / graph / path / http / package` 五组共 **34 项** `node:test` 断言，`npm test` 一条命令跑完。
+- 新增 `scripts/release-check.mjs`：版本一致、UTF-8 无替换符、`node --check`、相对 import 可解析、
+  Markdown 相对链接存在、`lib` 无 TODO/`console.log`、死文件与必需文件齐全。
+- `scripts/smoke.mjs` 保持 38 项端到端断言；另有 14 项安全探针（CORS / 写保护 / 穿越 / 响应头）。
+- `package.json` 补 `scripts`（test/smoke/check/standalone）、`bin`、`sidecar.ps1` 进包，版本升到 0.4.0。
+
+### 文档
+
+- 新增 `docs/security.md`（本机服务边界、威胁模型、验证方法）与 `docs/release.md`（发布前检查清单）。
+- 更新 `docs/testing.md`（三层测试与命令）、`docs/operations.md`（独立引擎、端口、CORS、版本漂移）、
+  新增 `docs/http-api.md`（路由、`/ping` 字段、ETag、错误码与请求体限制）。
+
+## 0.3.0 — 2026-11-08
+
+这一版把「只认 meow-memory」改成「谁都能接」，并且第一次让星图**参与别的插件正在做的注入**：
+别的插件喂了什么，星图补它没喂的那一半。结构上是新增一层适配器与一个补充包，原有七条不变量全部保留。
+
+### 结构
+
+- **来源适配器层** `lib/host/adapters/`：`util.js`（安全读盘、frontmatter、遍历、哈希）、`meow.js`（原 sources.js 的抽取逻辑）、`notes.js`（任意 `.md/.jsonl/.json/.txt` 目录）、`sqlite.js`（任意 SQLite，列名自动猜）、`ingest.js`（远端推送落成 JSONL）、`index.js`（注册表 + 发现 + 配置 + 扫描）。
+  契约只有三个动作：`detect(config) → store[]`、`scan(store) → {nodes, ledgers}`、`probe(config)`。新增一种来源 = 新增一个文件，不用碰建图与前端。
+- **`sources.json` 成为唯一配置入口**（`$DSH_HOME/memory-nebula/sources.json`）：`autoDetect`、`sources[]`（含 `adapter`/`path`/`dbPath`/`tables`/`levelField`/`where`）、`extraRoots`、`disabled`。文件不存在就用自动探测，读坏也退回自动探测，不会让插件起不来。
+- **`bridge.js` 补充包**：把「已读记忆」当种子做 1~2 跳扩散，按权重/重要度/热度/状态/超连接惩罚打分，跳过已注入与冷却中的条目，再按「每工作区/每层级」配额与字符预算裁剪。这就是「有选择性的一同注入」的执行体。
+- **`ledger.js` 注入账本**：`$DSH_HOME/memory-nebula/injected/<session>.json` 记 `seen/injected/external`，另有 `_global.json` 存 7 天冷却表。任何插件都能读写同一份账本，因此「谁注入过什么」第一次有了跨插件的公共事实。
+- **热载改造**：`live.js` 从硬编码 9 个文件改成递归枚举 `lib/host/`（跳过 `node_modules`、`.` 开头目录、`live.js` 自身与 `graph.debug.js`），按相对路径建子目录再 import。新增模块不再需要改清单；`engineStamp()` 加 1.5 秒缓存，轮询不再每次 stat 全目录。
+- 节点第一次带 `provider` / `adapter` 字段（图、`/graph`、前端都在用），「这条记忆谁给的」不再是猜的。
+
+### 新增
+
+- 工具：`nebula_bridge`（补充包，参数 `memory_ids[] / query / limit / chars / min_weight / hops`）、`nebula_sources`（适配器清单 + 已接来源 + 读取统计 + 接入指引）、`nebula_ingest`（远端推送 `provider + items[]`，写盘后立即重建）。
+- 路由：`GET /bridge`、`GET /sources`、`POST /ingest`、`GET /ledger`、`GET /export?format=md|json`。
+- `Nebula` 门面方法：`bridge()`、`sourcesReport()`、`ingest()`、`ledger()`、`exportReport()`、`#buildIndex()`。
+- 每轮注入重写：读 meow 账本 + 星图账本合成 `seen` → 取最近 40 条当种子 → 按 `inject.json` 的预算出条 → 节流（每会话最多 `maxRounds` 轮、每轮新增已读不足 3 条就不打扰）。
+- 前端：左栏「记忆来源」筛选（只接一个来源时不显示，避免一颗 chip 的噪音）、详情面板来源徽章、来源配色（未知来源按名字哈希出颜色）。
+- 界面：3D 光点改用普通混合（原来加色叠加，密集区全糊成一片白，层级色白给）；连线透明度由 `0.11+0.44w` 降到 `0.06+0.30w`，中心不再是一张白网；矮屏（≤920px 高）把「记忆概览」排成两列并收紧间距，1600×900 下四组筛选与两根滑杆全部露出来。
+- 导出：`/export?format=md` 给人看（规模、工作区表、层级表、枢纽、最强关联、孤岛），`format=json` 给 AI 看（节点按 degree 截断、边带 `[idA,idB,w,type]`）。
+- 文档：`docs/adapters.md`（适配器契约与全部字段）、`docs/integration-guide.md`（给「别人的 AI」的接入手册：三条路径 + 判断树 + 验证步骤）。
+
+### 修复
+
+- **接了第二个来源之后 `stats.sessions` 从 62 掉到 1**：`scanAll()` 把各来源返回的账本数组当 map 用 `Object.entries` 拍平，数组被展开成 `{"0":…,"1":…}`，会话数按 key 数算。现在数组直接拼接，对象形式才按 key 归组。
+- **`GET /bridge` 返回 500**：路由里 `const res = nebula.bridge(...)` 遮蔽了 HTTP 响应的 `res`，`sendJson` 拿到的是一份查询结果。改名 `out` 后正常。
+- **推送进来的记忆在图里查不到来源**：`buildGraph` 的 `outNodes` 没透出 `provider`/`adapter`，节点都退化成默认值。补上后 `/sources` 的 `byProvider` 与节点字段一致。
+- **详情面板 O(deg·n)**：`detail()` 每次 `nodes.find()` 找邻居，1300+ 节点时点一下要几秒。现在统一走 `#buildIndex()` 的 `byId/byI/byUid/adj`，并给「出处」「证据」加缓存——同一会话第二次详情 5ms（20 次合计）。
+- **重建时 O(n²)**：`refresh()` 里 `new Map(graph.nodes.map(...))` 原本写在 `for` 循环内部，每个节点都重建整张表。提到循环外。
+- **新接进来的来源全是孤岛**：建边要求两节点共享 ≥4 个「稀有词」，而一条两三百字的笔记，稀有词签名与老记忆的交集往往只有 1–2 个，永远够不到门槛 —— 结果记忆读进来了、`/sources` 数得出来，图上却一个连线都没有，`bridge` 从它扩散出 0 条。修法不是把门槛一路调低（那会把整张图糊掉），而是在剪枝之后加一段**孤立自举**：只对「度 0 且非内置来源」的节点，按共享稀有词数取前两名候选，连 `semantic / w=0.32` 的弱边（每个孤岛最多 2 条，全局上限 80 条）。留在剪枝之后是因为 0.32 的边会被已满的老节点挤掉。留两条是因为唯一的邻居若是 stale，`bridge` 的 `statusFactor` 会把它滤掉，等于白连。
+
+### 性能
+
+- **热载失败会 45ms 重试一次**：`sync()` 只要 import 失败，下一次轮询立刻再试，实测一分钟能刷上千条同样的栈（本机日志一度涨到几百兆）。现在按 2 的幂退避，上限 60 秒，成功即清零。
+- **每次改文件都会攒一个热载目录**：`$DSH_HOME/memory-nebula/engine/<stamp>/` 只增不减，本机攒到 110 个 / 10MB。现在每次热载后只留最近 3 个 + 当前，回收即刻发生。
+- 建图 1730 节点 / 7727 边约 1.3s（本机，冷启动含 9 个记忆库只读打开）。
+- 详情：冷 8ms/次、热 0.25ms/次。
+- `engineStamp()` 1.5 秒缓存后，页面 12 秒轮询不再引发全目录 stat。
+
+## 0.2.0 — 2026-11-07 / 2026-11-08
+
+这一版是「能发布」的一版：修掉一个会让整张图看起来坏掉的 bug，把图数据的形状收成一个入口，
+补上导出能力，并把界面从「能用」推到「经得起每天打开」。
+
+### 修复
+
+- **点「重建」后连线全部消失**（最严重）：`/refresh` 返回的图没有经过 `expandGraph`，
+  `state.edges` 里的边还是 `{s,d}` 下标形状，渲染层按 `{a,b}` 取端点，结果一条都挂不上。
+  现在 `graph` 与 `refresh` 共用同一个 `normalizeGraph()`，形状只在一个地方还原。
+- **重建后筛选面板与实际画面不一致**：面板重建时 chip 全部显示为「亮」，
+  而画布仍按旧的 `state.filter` 隐藏节点。现在面板按 `state.filter` 初始化，
+  并把已不存在的筛选键收敛掉（工作区改名后不会「一条都看不见」）。
+- 关掉「记忆来源」面板时，折叠按钮被旧样式漏掉、显示成白方块。
+- **时间回放里点「重建」后，时间轴不跟着新图走**：换了图但滑杆还是上一版的 `timeCut`，
+  新写的记忆会被旧闸门挡在外面，看着像「重建丢记忆」。现在 `applyGraph()` 会重算时间轴。
+- 重建提示里的耗时显示成 `undefinedms`：读的是 `graph.stats.buildMs`，实际字段在图对象顶层。
+- **「导出可见子图」不认时间闸门**：拖到某一天后导出的 JSON 仍含更晚的记忆。
+  现在导出与画面共用同一个「可见」定义，并在 `filter.until` 里写明截止时刻。
+- **「屏蔽关联 / 断开连边」点了没法回头**：这两个动作即时生效、原本没有确认框，误点只能去
+  看板里翻。现在提示条上直接挂「撤销」（8 秒），且带动作的提示条不会被轮询的「星云已更新」顶掉。
+- **筛选把整张图藏光时只剩一片空屏**：现在中间给一句「这一屏没有记忆」+ 出口（Shift+F /
+  左栏重置），并且 LOD 光斑与「孤儿细线」（端点已被筛掉却还在画的边）一起收干净——
+  否则画面说没有记忆、旁边还挂着 131 个光斑，谁都会以为界面在骗人。
+- **主线（`L`）看不到「我现在在哪」**：原来的列表只列同一会话的**其他**记忆，当前这条
+  不在里面；也没有日期分隔，跨天后只靠时间分不清是哪天。现在把当前这条一起排进去并高亮
+  （右下写「当前」），按天加日期小标题，标题与页脚都带真实条数。
+- **窄屏（≤900px）没有筛选入口**：左列被 CSS 整个收起，等于「手机上只能看不能筛」。
+  现在顶栏多一个「筛选」按钮，把左列当抽屉拉出来（点别处 / Esc 收回，每次从顶上开始看）。
+- **ghost 按钮点亮后文字看不见**：`.btn.on` 给的是深色字（配亮青底），套在玻璃底上就变成
+  深字压深底。补 `.btn.ghost.on` 自己的配色。
+- **从 3D 切回 2D，筛选全丢**：两个渲染器各存一份筛选，2D 分支没重放 `state.filter`，
+  于是「3D 里筛到 1144 条、切回来 1659 条」。现在切回时重新交一次。
+- **在星系 / 时间视图里导出的 PNG 是一张空图**（只有标题栏和工作区名字）：WebGL 的绘制缓冲默认
+  不保留，等一帧过去再 `drawImage` 只能拿到被清掉的画布。现在导出前先 `paintNow()` 同步补画一帧，
+  在同一个任务里取像素。
+- **3D（星系 / 时间）里按工作区筛选会把整张图筛空**：chip 的键是 `ws` 名（`Liberty Of Code`），
+  3D 只拿 `n.cluster`（`LibertyOfCode`）去比，含空格的名字永远不相等。现在两个都认。
+  同一处还修了 3D 的「筛完还剩几条」：补上 `visibleNodes()/visibleEdges()`，
+  左栏「隐藏 N 条」在 3D 里也说真话；全筛掉时不再只剩一圈簇名。
+- **换一组同样数量的工作区筛选后，边还画着上一组的路径**：边路径缓存的键里只有筛选集合的
+  `size`，没有「谁被藏起来」的版本；现在缓存键带上 `hiddenVersion`，筛选一变立刻重算。
+- **点完搜索结果后键盘「失灵」**：焦点还留在搜索框里，Esc / e / f / r 全被输入框吞掉。
+  现在选中命中就把焦点还回画布，Esc 能正常关详情。
+- 窄屏下筛选面板要滚动时，「重置筛选 · 回全视图」会被滚出视野：改为吸顶，滚动条拇指也提亮一档。
+- **首屏失败态原来是一句 `Failed to fetch` 加一坨调试 JSON，没有可点的东西**：现在说人话（连不上记忆库 / 需要从 DSH 打开 / 取图失败三种），给「重试」与「复制诊断」，技术细节折进 `details`。重试走的是正常取图那条路径，原地恢复、不用刷新页面。
+
+### 新增
+
+- **导出（顶栏「导出」菜单）**
+  - `当前视图 · PNG`：把现在看到的画面拼一张带标题栏的图（节点数 / 连接数 / 工作区数 / 时间戳），
+    界面元素不进图；2D 出图时会临时收掉给侧栏留的空白并重新居中，所以图不会一半是空的。
+  - `可见子图 · JSON`：把当前筛选下看得见的节点与边导出成 `memory-nebula/subgraph@1`，
+    含筛选条件与统计，便于外部再分析。
+- **左栏分组可折叠**：工作区 / 记忆层级 / 连接类型 / 两根滑杆 / 记忆来源都能收起，
+  状态记在 `localStorage`，下次打开还是你收起来的样子。
+- **点任何地方都能定位**：从搜索、看板、详情里的邻居点开一条记忆时，
+  如果它不在视口里，镜头会（缓动）把它带到「可用区域」正中；
+  本来就在视口里就不动镜头，避免点一下画面就跳。
+- 详情面板的镜头定位会避开左右面板——节点不会藏在侧栏底下。
+- **时间回放（螺旋视图）**：底部出现一条时间轴，往左拖只留下「那一天之前的记忆」，
+  连线跟着同一时刻一起收；标签实时显示「≤ 10-31 · 635 条」，双击时间轴回到全部。
+  闸门加在 `space3d.visible()` 里，所以聚类视图/筛选/证据链都遵循同一套可见性。
+- 降级失败不再完全静默：`overview / recall / path / align` 第一次出问题会留一条
+  `console.debug`，来源面板读不到时直接显示「来源读不到：…」而不是空着。
+- **空结果只有一句「没有找到相关记忆」**：抬头照样写清查了什么、扫过多少、没认出的词，
+  正文补一句可执行的下一步（换更短的词 / 先按工作区筛再顺着连线找）。
+- **拉远后点「光斑」没反应，反而选中了光斑底下压着的某个点**：这一档根本分不清单点，
+  点光斑的本意就是「进去看看」。现在先判 LOD 再判单点，点完镜头飞进那个项目并提示
+  「已放大「XXX」 · 双击空白回到全图」（实测 k 0.18 → 0.526）。
+- **按下 Esc 以后键盘还是不听使唤**：搜索框里的 Esc 只清空输入、不还焦点，后面的 `1/2/3`、`f`、`r`
+  全被输入框吞掉；现在清空的同时把焦点交回画布（实测 Esc 后 `activeElement` 是 body，按 `2` 能切视图）。
+- **手快时旧搜索结果盖掉新结果**：检索加了序号，只认最后一次；失败提示也只报最后一次。
+- **看板屏蔽页两处**：行里显示的是记忆标题而不是一串 id 尾号；点「恢复」后不用再等 overview
+  那一趟（屏蔽页只读自己的列表）。
+- **浏览器页签**：补了主题色、描述和一个内联 SVG 图标（不再是空白文档图标 + 404）。
+- **看板里点「恢复」后要干等三秒**：按钮当场变成「恢复中…」并锁住，恢复完列表自动刷新。
+- **接口半死时一直转圈**：请求加了 12 秒上限（探活 3 秒），超时会说「等了 12 秒还没有回包」，
+  而不是无限等；首屏失败态、轮询断线提示都能接住。
+- **小字太灰**：`--text-faint` 从 #526278 提到 #6b7f96，对面板底对比度 3.06 → 4.63
+  （10px 的标签也过了 WCAG AA）；层级只靠字号与字距区分，不靠「灰到看不清」。
+- **搜索结果里 ↑ 从第一条往上按会卡住**：现在绕到最后一条；↓ 仍然从高亮处往下走。
+- **减少动态效果 / 读屏**：系统开了 `prefers-reduced-motion` 时不再播生长动画、3D 也不再自动旋转，直接全亮；
+  两块画布补 `role="img"` 与一句话摘要（如「记忆星图：1684 条记忆，6773 条连接」）。
+- **搜索结果只说「找到几条」，不说为什么**：抬头补上查询词、扫描条数、最相关条数，命中标题里
+  与查询重合的词标亮；认不出的词单独列出来（以实测 `星图 记忆 zzzz` 为例：12 条最相关 · 扫过 90 条 · 没认出的词：zzzz）。
+- **刚重建完就导出，会得到一张只长了一半的图**：导出前先把还没点亮的节点一次点亮（`finishReveal`），
+  再收边距取像素；实测动画中导出（revealed 0 / pump 运行）得到完整 1.13MB 图，导出后画面直接是全亮的。
+- **英文入口**：加 `README.en.md`（功能表、快速开始、设计约束），README 顶部一行 `English` 互链，随包发布。
+- **空库时那句「记忆库是空的」会一直挂着**：后来有数据了也没人收。现在新图里只要有节点就自己消失。
+- **星云自己更新了，左栏的计数还是旧的**：轮询/换腿拿到新图时只换了画布，没重建筛选面板——
+  新工作区不会出现，旧计数也不动。现在两条路径都带上 filters，筛选条件本身照旧保留。
+- **只能用键盘的人看不见焦点在哪**：给按钮 / chip / 菜单项 / 卡片加 `:focus-visible` 细光环（只在键盘走位时出现，鼠标点不打扰）。
+- **建议条自己把「已撤销」关掉**：动作里的提示会被 finally 清掉，而且清错了新提示的定时器。
+  现在用序号区分「这条还是不是当前那条」，并先把文案改成「正在处理…」。
+- **顶栏加了一个「?」**：快捷键一览不用先知道 `?` 才能看到；Esc 现在也能关掉它（并先于其他面板）。
+- **点开一条刚被重建掉的记忆，右侧还挂着旧详情**：404 时收起面板并说「这条记忆已经不在了」。
+- **屏蔽列表读不到时显示「没有屏蔽任何关联」**：读失败与列表为空分开说，别让人以为数据丢了。
+- **顶栏五个数字没有解释**：悬停给一句人话（平均连接 = 平均每条记忆连了几条边）。
+- **在星系视图里改过窗口大小，切回星云是一张空画布**：隐藏的 canvas 被 `resize()` 量成 0，
+  后备缓冲写成 1×1 之后再没人补。现在隐藏时不动尺寸，切回 2D 时补量一次。
+- **接口断了会说话**：页面每 12 秒探一次，两条腿都不通时顶部出现一条细提示「接口断开了 · 正在重试…」，
+  恢复后自己消失并提示「连接已恢复」。以前只会对着不动的图猜是卡了还是坏了。
+- **命令面板补三条**：`重置筛选 · 回全视图`、`主线：当前记忆的时间线`、`快捷键一览`——
+  以前这几件事只能靠记住 Shift+F / L / ?，现在也能打名字找。
+- **详情头部「复制 id / 复制会话」**：把一条记忆带到 issue、聊天、笔记里时不用再手抄；
+  会话 id 也可直接复制（深链要等宿主给路由，先保证拿得到 id）。
+
+### 性能
+
+- 2D 星云：连线的 `Path2D` 按「颜色 + 透明度档」归并后**缓存**，
+  只有坐标版本（布局动了）、镜头、聚类包围盒、筛选、高亮变化时才重建。
+  静止时每帧从「重建几千条曲线」降到「复用几批路径 + 一次 stroke」。
+- 3D 星系/螺旋：确认已有脏标记（`moving || cacheDirty || needDraw`）才重画，静止时不空转。
+
+### 视觉
+
+- 时间螺旋模式的连线由 0.42 提到 0.58：能看清「谁连着谁」，又不把盘心糊成一片。
+- 顶栏按钮底色压实（0.70 → 0.88 + backdrop blur）：节点标签不再透过按钮显形。
+
+### 工程
+
+- 图数据形状只有一个入口（`normalizeGraph`）；应用侧只有一个 `applyGraph()`，
+  首屏、重建、轮询、失败对齐都走它。
+- `package.json`：版本 0.2.0，去掉 `private`，补 `license: MIT`、`CHANGELOG.md` / `LICENSE` 进 `files`。
+- 新增 `LICENSE`（MIT）与本文件。
+- **README 拆成五册（配 `docs/assets/preview.png` 预览图）**（`docs/data-and-edges` / `recall-and-tools` / `interface` / `operations` / `verified`），
+  README 只留简介、能力表、快速开始、文档索引与目录结构——原来 278 行一屏读不完。
+  顺带纠正两处过时口径：热载只覆盖 9 个引擎文件（`http.js` / `index.js` / `live.js` 仍需重启），
+  `tool/call` 维度早已接进「会话里实际调用过 N 次」。
+- 新增 `scripts/smoke.mjs`（随包发布）：只读接口契约自查——`v=2` 形状、边端点/权重合法、
+  id 唯一、`stats` 与数组一致、`refresh` 与 `graph` 同构（历史上丢线就出在这里）、
+  `node / recall / path / overview` 可用。`node scripts/smoke.mjs` 全绿才算能发。
+
+### 文档
+
+- **补两册工程文档**：`docs/architecture.md`（模块分工 / 请求路径 / 七条不变量，含「隐藏的 canvas 不要量尺寸」）、
+  `docs/testing.md`（23 项契约自查 + 26 个浏览器探针清单 + 手工验收七步）；README 索引同步。
+
+## 0.1.0 — 2026-11-01
+
+- 第一版：只读抽取各记忆插件（meow-memory / hindsight / openviking 等）的记忆，
+  按同一实体、同关键词、同项目、共激活、语义相似五类关系连边；
+  2D 星云 / 3D 星系 / 时间螺旋三档视图，区块加载，记忆体检，证据链，扩散检索。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 主人 & 小代码酱
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.