# l1-admin —— L1 原子记忆管理工具集 L1 原子记忆（`{profile}/memoryDB/l1/records/*.jsonl`）的日常管理工具，沉淀自 2026-09-11「L1 全量审计 + 清理」实战（233 条逐条处置、两次踩坑后定版）。 ## 工具一览 | 工具 | 作用 | 安全默认 | |---|---|---| | `tombstone.mjs` | 按 id 作废记录（就地标记 `deleted:true`） | `--dry-run` 默认；`--apply` 实写前自动备份 | | `rewrite.mjs` | 改写记录（新 id 追加 + 旧行就地标记） | 同上 | | `verify.mjs` | 库体检：行数/存活/坏行/同 id/畸形/错误串白名单 | 只读 | | `health.mjs` | 健康指标：超长/test 残留/孤儿 stats/自造 id/畸形/错误串 | 只读 | | `rollback.mjs` | 从备份目录恢复 L1 records | `--dry-run` 默认；实恢复前自动备份当前库 | | `scene-pool.mjs` | **工作场景池**运维：`report`（池状态 + 批级指标）/ `cluster`（历史场景名聚类）/ `seed`（按映射提案播种）/ `merge-report`（合并候选） | 除 `seed --apply` 外全部只读；`seed` 默认 dry-run，实写前自动备份 `scenes.json` | | `task-state.mts` | 标记任务生命周期（就地改顶层 `taskState`，与 `l1_task_state` 工具同一实现） | 默认 dry-run；`--apply` 写盘；`--backup` 可选（**默认不备份**，理由见下） | | `l1-fix.mts` | L1 纠错（改写正文 / 作废），转发 `fix-tool.ts` 的 `runFix` | 默认 dry-run（走抽出来的 `checkFixGates`，**不含 IO 级校验**）；`--force` 只解高价值那道闸 | | `embedding.mts` | 向量库 `status` / `backfill` / `rebuild` | `status` 只读且便宜；另两个要 `--apply`，`rebuild` 还要 `--confirm REBUILD`（会先清空向量库） | | `trigger.mts` | **请求某层入队**（`--layer l1\|l2\|l3`）或 `--status` 探查三层信号 | 只落一份待消费信号，**不是立即执行**；落完回读确认 | | `l1-mode.mts` | L1 提取模式读写（`--set code\|chat`） | 唯一不要求 `--apply` 的写操作（可逆、幂等）；写完回读确认 | | `subagent-stop.mts` | 停掉某层子代理（`--layer`，`--list` 看在跑哪些） | 与 `/my-memory:subagent-kill` 同序列；不可逆，故**无 dry-run** | | `l2-archive.mts` | L2 块 `list` / `archive --file --reason` / `restore --file` | 持 **L2 run-lock**；归档必须有 reason；默认 dry-run（预演不跑自愈） | | `l3-edit.mts` | L3 提议稿条目 `add` / `update` / `delete`，转发 `applyL3Edit` | 默认 dry-run；写 `USER-temp.md`（提议稿），不碰 live | | `l3-restore.mts` | 列出 / 还原画像备份到提议稿（`--list` / `--file --confirm`） | 写前先另存当前提议稿；空备份默认拒（`--allow-empty` 才放行） | | `l3-merge.mts` | **把提议稿并入 live `USER.md`**（全仓库唯一写 live 画像的路径） | 默认只追加新条目并保留旧条目；`--replace` 才完整替换，替换模式的三道闸默认拒绝；实写分别确认 `MERGE` / `REPLACE` | | `viewer-cli.mts` | 上面那批包装的**共用骨架**（参数解析 / JSON 出口 / 哨兵收尾 / `run()`）；不是可执行入口 | — | | `viewer.mts` | **一键启动查看器**：同步最新页面 → 起桥 → 开浏览器（自动避让占用端口） | 只绑 `127.0.0.1`；`--no-open` / `--no-sync` 可关掉两件事 | | `viewers/启动查看器.cmd` | 上面的 Windows 双击入口（内容纯 ASCII，中文由 node 打印） | 同上 | | `viewer-bridge.mjs` | **查看器写盘桥**：静态托管 `memoryDB` + 写盘端点 + 目录列举 + 诊断 | 只绑 `127.0.0.1`；写端点默认 dry-run，破坏性动作另有 `confirm` 副验 | | `pipeline-jobs.mts` | **只读转储 `pipeline/jobs.sqlite`**（排队 / 在跑 / 最近结束；「流水线」页的取数口） | 只读（`node:sqlite` 的 `readOnly` 打开）；库不存在时报 `exists:false`，**不顺手建库** | | `viewer-status.mts` | 查看器版本与漂移诊断（源码内容版本 vs 已部署版本） | 只读 | | `viewer-limits.mts` | 查看器要展示的阈值（`l1.mode` / `l2.maxScenes` / L3 各限额），从源码常量透出 | 只读；**不暴露含密钥的 `config/` 整份文件** | | `active-days.mts` | 活跃会话日清单（权威源 `l0/conversations`） | 只读 | 公共参数：`--profile `（默认 `C:/Users/leaf/.pi/agent/profiles/default`）、`--dry-run` / `--apply`。 > `.mts` 需 `node --experimental-strip-types` 执行（Node ≥22.13）。之所以有这几个 `.mts`：它们是 > 「网页 ↔ 扩展 `.ts` 实现」的桥 —— `.mjs` 不能 import `.ts`，而查看器用到的阈值、版本哈希、 > 活跃日口径必须与源码**同一份实现**，所以由 `.mts` 转发，绝不在 `.mjs` 里重写一遍。 ### `task-state.mts` 为什么默认不备份 本目录其它写者（`tombstone` / `rewrite` / `migrate-task-state`）都是"实写前自动备份"，那是它们的安全默认。 `task-state` 刻意不同，因为这个动作的风险档次不一样： - `tombstone` 让记录**死掉**（退出召回与向量）、`rewrite` 换掉正文 —— 从结果看不出原来的样子，必须能回滚； - `taskState` 只是就地改一个状态字段：**可逆**（改回去即可）、幂等、留审计、不动正文/编号/向量。 而且**查看器界面上的切换按钮**会随时调用它 —— 每次点击都把整个 `l1/records` 备份一遍， 既拖慢交互又把 `backups/` 淹没。 所以备份改为显式 `--backup`（人工批量操作时加）。批量迁移另有 `scripts/migrate-task-state.mts`，自带 `--apply` 前备份。 ## 查看器写盘桥（viewer-bridge.mjs） ```bash # 一键（推荐）：同步页面 + 起桥 + 开浏览器 npm run viewer # 或 node --experimental-strip-types scripts/l1-admin/viewer.mts # Windows 双击：viewers\启动查看器.cmd # 只起桥（自己控制端口、不自动开浏览器） node scripts/l1-admin/viewer-bridge.mjs [--port 5174] [--profile ] [--lan] [--host ] # 局域网调试：别的设备也能打开（环回保留，额外听本机那张局域网网卡） npm run viewer -- --lan # 或 启动查看器.cmd --lan ``` `viewer.mts` 除了启动时部署、选端口、打开页面，还会在运行期间监听仓库 `viewers/` 源码： 保存源码后自动增量部署，已打开页面每 2 秒检查版本并自动重载。**重载可能丢失尚未提交的表单输入**。 `--no-sync` 会跳过启动部署和热更新监听。直接运行 `viewer-bridge.mjs` 不会启动源码监听。 启动时的三件事，都是"每次都要做、忘了就出问题"的机械步骤： ① 调 `deployViewers` 同步最新页面（幂等，内容没变零写入）；② 从 5174 起探测空闲端口（**5174 被占时 不再直接退出**——实测被占过一次，之后每次都要手动 `taskkill`）；③ 打开浏览器到 `viewers/index.html`。 profile 用扩展的 `ProfileManager` 解析（读宿主 `settings.json` 的 `memorySystem.activeProfile`）， 避免"查看器看 A profile、扩展写 B profile"这种无声错配。停止：关掉控制台窗口，或 Ctrl+C。 **`--lan` / `--host `（局域网调试，2026-10-09 按用户要求加）**：在环回之外**额外**监听本机那张 局域网网卡（`--host 0.0.0.0` = 所有网卡，那时它本就覆盖环回、不再重复听），并把给别的设备用的地址打印出来。 "哪块网卡算局域网"的规则只在 `lan-addresses.mjs` 一份（优先 `172.16.10.0/24`，其次其它私有段）， 启动器与桥共用 —— 各写一份迟早出现"启动器打印 A 地址、桥实际听 B 地址"这类最难查的错配。 **它是显式开关而不是默认行为**：那个地址上**没有鉴权**、CORS 全开，写端点（改任务状态 / 删除 / 并入 live 画像 / 整库还原）同网段任何设备都能调 —— 启动时会把这段代价原样打印，⑰ 节也钉住 "默认只有环回"。`config/`（含 embedding API key）在静态托管之外，局域网也取不到。 | 端点 | 作用 | |---|---| | `POST /api/tombstone` | `{ids}` → `tombstone.mjs --apply`（备份 + 就地标记） | | `POST /api/task-state` | `{ids, state, reason?}` → `task-state.mts --apply`（**取跨进程写锁**，拿不到锁一条都不写） | | `POST /api/l1/fix` | 纠错（`l1-fix.mts` → `runFix`：证据门槛 / 24h 防抖 / 高价值保护） | | `POST /api/l1/rollback` | 整库还原（`rollback.mjs`；`confirm` 必须等于备份目录名） | | `POST /api/l1/embedding` | 向量回填 / 重建（`embedding.mts`；重建要 `confirm:"REBUILD"`；**长任务，期间整座桥不响应**） | | `POST /api/l1/mode` | L1 提取模式 `code`/`chat`（唯一无 `apply` 的配置写入，可逆幂等） | | `POST /api/trigger` · `POST /api/subagent/stop` | 请求某层入队（**只落信号**）/ 停掉某层子代理（不可逆） | | `POST /api/l2/archive` · `/api/l2/restore` · `/api/l2/scene-pool/seed` | 块归档 / 恢复（L2 run-lock）/ 场景池播种 | | `POST /api/l3/edit` · `/api/l3/restore` · `/api/l3/merge` | 提议稿条目增删改 / 还原到提议稿 / **并入 live 画像**（三道闸 + `confirm`） | | `GET /api/l1/shards` · `/api/l1/backups` | `l1/records/*.jsonl` 清单 + 行数；`backups/l1-admin/*` 备份目录（浏览器列不了目录） | | `GET /api/l1/embeddings` · `/api/l1/active-days` | 向量库状态（便宜）/ 活跃会话日（权威源；`hit-stats.json` 侧车会滞后，实测差过 1 天） | | `GET /api/l2/blocks` · `/api/l2/scene-pool/report` · `/merge-report` | L2 块目录列举；场景池只读报告（**输出是文本不是 JSON**，且可能较慢 ⇒ 页面按需拉取） | | `GET /api/l3/backups` · `/api/profile-files` | 画像备份清单 / profile 根的 `MEMORY.md`+`USER.md`+`USER-temp.md` | | `GET /api/limits` | 阈值与配置节（含 `l1.mode`） | | `GET /api/pending-triggers` · `/api/subagent-runs` | 三层待消费信号（**只读探查，不消费**）/ 在跑的子代理 | | `GET /api/pipeline/jobs` | 作业队列只读转储（`pipeline-jobs.mts`；「流水线」页用） | | `GET /api/health` · `/api/viewer-status` | 存活 / 版本与漂移 | **写端点一律默认 dry-run**（必须显式 `apply:true`），破坏性动作另有 `confirm` 副验（还原要备份名、 重建要 `REBUILD`、追加并入要 `MERGE`、完整替换要 `REPLACE`）—— 桥里那道是**副验**，CLI 自己也会验一次，两道都在。 这条安全默认由 `verify-viewer-deploy.ts` 的 ⑱ 节逐端点断言。 二十个**实测踩过**的点，改动时别踩回去： 1. **`req.url` 必须 `decodeURIComponent`**。浏览器的 fetch 会把非 ASCII 文件名百分号编码， 不解码就会去找字面名为 `%E4%B8%AA…` 的文件 → **L2 的块（全是中文名）整批 404**，而页面不报错、 只是默默显示索引兜底值。 2. **`/api/profile-files` 是必需的**，不能靠相对路径。桥只挂载 `memoryDB`，而画像文件在 profile **根** （上一级）；页面里写 `../../USER.md` 只会解析回 `/USER.md` = `{memoryDB}/USER.md` → 404。 3. **CLI 的 stdout 要先跳过前置日志再解析 JSON**。`autoBackup` 会 `console.log` 一行 「已自动备份：…」，整段 `JSON.parse` 会把一次**成功**的写盘报成 500。桥里用 `parseCliJson` 从第一个 `{` 起解析。 4. **别用 `node --check ` 做语法门禁 —— 它会对含 `import` 的 `.mts` 假绿**。 Node 24 实测：`.mts` 带 import 时 `--check` 走 `cjs/loader.wrapSafe` 那条路径后**静默返回 0**， 而同样内容写成 `.mjs` 才会真的报错。也就是说这个组合恰好对**本目录所有真实 CLI**（都以 import 开头） 失效 —— 一条从不报警的门禁比没有门禁更糟。可行做法见 `verify-viewer-deploy.ts` 的检查 ⑮： 先用 `module.stripTypeScriptTypes` 去类型，再把源码从 stdin 交给 `node --input-type=module --check -`。 5. **改查看器样式时别写 `scrollbar-color` —— 它会让滚动条变宽**。实测（Chrome 146 / Electron 41）： 侧栏滚动条不指定 = 11px，一指定 `scrollbar-color` 就退回 16px 的经典滚动条（带箭头）， 比完全不指定更糟；让原生控件（滚动条 / select 弹层 / 复选框 / search 清除按钮）变暗的是 `:root { color-scheme: dark }`，滚动条外形交给 `::-webkit-scrollbar`。 同一类"静默失真"的坑还有：别在 JS 里内联十六进制色值（色值只留 `viewer.css` 的 `:root` 一份）、 别用 `.bar-track > i` 这种 (0,1,1) 选择器给 `.c-*` 工具类兜底（会压过 (0,1,0)，把条形图变成兜底灰）。 完整界面契约在 `viewers/assets/viewer.css` 文件头；以上三条由 `verify-viewer-deploy.ts` 的 ⑯ 节断言。 6. **别在 `aside` / `.wrap-scroll` 上写 `overscroll-behavior: contain`**（用户报过"L2 页鼠标滚动失效"）。 实测只要容器带 `contain`，滚轮就被它吞掉，**哪怕它根本没有可滚内容** —— L2 的块表格是 `overflow:auto` 但内容不溢出、又占了内容列大半，于是滚轮在那一大片区域完全没反应； 把 `overscroll-behavior` 改回 `auto`，同一个手势立刻能把页面滚下去（同坐标对照实验）。 `contain` 只保留在弹层上（打开弹层时拦住滚轮、别滚动背景）。这条同样由 ⑯ 节断言。 7. **`?port=` 丢了不会报错，只会静默变只读**（用户就是拿"无写盘桥"来问的）。页面靠 query 里的 `?port=` 才知道桥在哪，所以：① 页内跳转必须带 `location.search`（顶部导航曾漏掉，在总览页点一下导航就中招， L2 会冒出 3 处"无写盘桥"）；② 桥的根路径 `/` 必须 **302 到带 `?port=` 的总览页** —— 就地返回 `index.html` 会让相对引用的 `assets/*` 解析成 `/assets/*` 全 404、连 `window.V` 都没有， 而桥启动打印的第一行正好是这个根路径（终端里可点）；③ 真丢了 query 时页面顶部要给出可操作提示， 与 `file://` 的提示分开写（两种降级原因不同）。三条由 ⑰ 节断言。 8. **桥的 URL 是 `req.url.split("?")[0]` —— GET 端点接不了查询串**（2026-10-08 补齐管理操作时定的约定）。 加 `?cmd=report` 这种参数不会报错，只会静默走到 404 分支。需要参数的**读**操作一律用**路径段** （`/api/l2/scene-pool/report`），**写**操作一律 POST + JSON body。⑱ 节断言这条约定还在， 并且页面里不许出现给 `/api/*` 挂查询串的写法。 9. **收尾函数只写 JSON 不中止执行 ⇒ 脚本会输出第二个 JSON ⇒ 桥解析失败**（实测踩到）。 `viewer-cli.mts` 的 `finish/fail/usageError` 现在是**抛哨兵异常**（`ExitSignal`），脚本主体必须包在 `run(async () => …)` 里；否则守卫写完错误后代码会继续往下跑（`trigger.mts --layer l9` 甚至还会去写一个 `pending-trigger-l9.json`），两个 JSON 首尾相连，`JSON.parse` 整段失败 —— 一次说得清清楚楚的拒绝 被报成"CLI 未返回可解析的 JSON"。约定写在 `viewer-cli.mts` 头部。 10. **"说人话"的 CLI 不能走 JSON 解析**。`rollback.mjs` / `scene-pool.mjs` 输出的是文本报告（分隔线 + 表格）， 拿 `parseCliJson` 去啃要么得 null（把成功报成失败）、要么啃出半截对象。桥里为此单列了 `passthroughText`，与 `passthrough` 分开。 11. **桥是单线程 + `execFileSync`：一次 CLI 调用期间整座桥不响应任何请求**（向量回填/重建、场景池报告）。 这不是能靠并发解决的问题，所以页面必须显示"运行中、勿重复点"，长任务用长超时 （回填/重建 30 分钟）。要真并发得把执行改成"子进程 + 轮询状态"，本轮没做。 12. **`.ops-note { grid-column: 2 }` 不能当全局规则写**（2026-10-09 视觉巡检）。`.ops` 是**单列**网格， 只要它有一个**直接子级**被 `grid-column: 2` 推到第 2 列，隐式网格就会多出一列，之后所有自动放置的 子级开始两列交替 —— 实测 L2 侧栏整块右移 106px，被 `aside`（`overflow: auto`）裁掉， 而且按钮中心点正好落进主区表格的 `td` 上，**看得见一条白边、点不到**。 结论：`grid-column` 只写 `.ops-row > .ops-note`，`.ops` 的直接子级保持 auto。 13. **`th { white-space: nowrap }` 只能点名给需要的那张表**。全局开会让播种表（`table-layout: fixed` + 三等分列，列宽 80px）的「别名（逗号分隔）」直接**溢出 18px 压到隔壁列** —— fixed 布局不会为了 内容加宽列。场景块表的「成员」「updated」换行是另一个问题，用 `#blockTable th` 点名即可。 配套：`td.day` 让「2026-09-12」不被拆成两行。 14. **`.full-content` 的 `max-height` 必须与 `-webkit-line-clamp` 对齐**。clamp 要 6 行、行高 1.55， 6 × 1.55 = **9.3em**，原来写的 `8.8em` 比 6 行矮 —— 每张卡片第 6 行都被切掉下半截（连省略号一起）。 另外 clamp 生效时 `scrollHeight` 报的是**截断前整篇**，别拿它判"有没有被裁"，要拿它和 `行数 × 行高` 比。 15. **`.ops-ctl` 里的控件不许带固有宽度**。`select` 的固有宽度取**最长选项**、`input.confirm-input` 写死 `min-width: 220px`，而 336px 侧栏的控件列只有 ~153px（危险区被 `.danger-zone` 的内边距再吃一圈， 只剩 141px）—— 实测分别溢出 **441px / 79px**，`aside` 是 `overflow: auto`，表现为侧栏横向滚动条 + 控件被裁。统一 `min-width: 0; max-width: 100%`，危险区的 `.ops-row` 改单列让控件拿满宽度。 同理，备份下拉的选项文案要把**能区分彼此的部分放最前**：5 个 `backfill-*` 目录只有末尾时间戳不同， 目录名打头的话它们在框里显示成一模一样的 `backfill-project-`。 16. **写死的 `max-width` 要对着真实容器量**。`.chip.scene` 原来写死 340px，实测 253 个未归类 chip 里 **213 个被截**，而卡片头其实还有 ~130px 空位没用。改成 `max-width: 100%` 后只剩 12 个真放不下的 （省略号 + `title` 悬停看全名是既有设计，保留）。同一类问题：`input[type=search]` 只有 `min-width` 没有 `flex-grow`，占位符写的是可搜字段全清单，结果被裁成「搜索 content / 场景 / 项目 / id / ƒ」。 17. **断不开的长 token 会顶大表格列的 min-content，逼出整张表的横向滚动**。丢弃留痕表的正文列是 `white-space: pre-wrap`，一个 `/my-memory:l2-trigger` 这种断不开的 token 把整表撑到 **1195px > 容器 1014px** —— 于是右边被切，而滚动条远在 118 行之下的 `.wrap-scroll` 底部，等于"看不见能滚"。 给正文列补 `overflow-wrap: anywhere` 后 min-content 回落，整表正好 1014px 放下， 顺带那 8 处"文字比格子宽"也一起消失。判"有没有压到隔壁列"要用**边框盒**比，不是内容盒 （内容盒到边框盒之间还有 9px padding，差几像素只是行尾空格的舍入）。 18. **"只读打开"一个 WAL 库也会留下痕迹，而"看一眼队列"不该顺手建库**（2026-10-09，`pipeline-jobs.mts`）。 实测（Node 24.17）：`new DatabaseSync(p, { readOnly: true })` 打开一个 WAL 模式的 sqlite 后， 目录里会多出 **0 字节的 `-wal` 与 `-shm`** —— 那是 WAL 机制的正常产物，不是写数据， 所以门禁**不要**断言"调用后没有这两个文件"（会假红）；该断言的是库内容不变（字节数 + 行数）。 真正要守的是另一件：**库不存在时不能建**。用 `PipelineJobsDB`（扩展里那个类）就会踩这一条 —— 它的构造函数 `mkdir` + `PRAGMA journal_mode=WAL` + 建表，于是"从未跑过流水线"会被工具洗成 "有一个空队列"，两种事实混成一种。`pipeline-jobs.mts` 因此先 `existsSync` 再以 `readOnly` 打开， 不存在就回 `exists:false`（实测主进程持写锁时只读依然能读，WAL 下读者不阻塞写者）。 同一条上还有两个小口径：`queued` 的排序是**认领顺序**（复刻 `jobs-db.ts:listQueued`：L3 永远最后）， 它决定页面上"下一个跑谁"，改了那边要同步改这边；`recent` 按 **id 倒序**而不是时间字符串排序 （id 自增，等于"最近的在前"，不依赖 time 文本可比）。 19. **Blink 里 `