# 设计取舍（为什么是这样，而不是那样） > English summary: the registry is an **append-only JSONL log** (not a database), deletions are **archived and > restorable** (never physical), rewrites are **atomic with a `.bak`**, concurrent writes are **detected and > refused** (no locks), the page is **rendered per request** (no build step), and the routes are **not > authenticated** (they are exactly as reachable as the DSH UI itself). Every section below states the > alternative that was rejected and the price actually paid. 这份文档集中回答"为什么这么写"。取舍散落在 CHANGELOG 的各轮里，这里按**决策**归拢，每条都写清 **选了什么 / 为什么 / 代价是什么** —— 代价那条最重要，没有代价的方案通常意味着还没想清楚。 ## 1. 存储：只追加的 JSONL，不是数据库 **选了什么**：一条登记 = 一行 JSON，追加到 `index.jsonl`。 **为什么**：这是给人看的文件。出问题时用记事本就能查、能改、能对比、能进版本库； 不需要为了"看一眼里面有什么"而装任何东西。它也天然抗"写一半崩了"——最坏情况是最后一行残缺， 而读的时候**坏行只跳过自己**（`readJsonl` 记进 `errors`），不会带走整份清单。 **代价**：没有索引、没有事务、没有并发控制（见 §4）。条目上万以后，筛选是线性扫描。 这个量级下（个人成果清单）不值得为此引入数据库依赖 —— 而且一旦引入，插件就再也不是"零依赖"。 ## 2. 删除：进留档，可放回 **选了什么**：`remove` 把条目**追加**到 `deleted.jsonl`（带 `removedAt` 与 `why`），从清单里移走； `restore` 把它放回来。**任何情况下都不动那个文件本身。** **为什么**：这个工具管的是"登记"，不是"数据"。用户说"这条不算成果了"和"把这个文件删掉"是两件事， 把它们混在一起会造成不可逆的误伤。留档让"手滑"变成可撤销的操作。 **代价**：清单与留档两个文件要一起维护；`restore` 是"两处改动"，因此有了 §4 里那个 "提交前复核"和那条 `entry-restored-deleted-log-unchanged` 的诚实报错。 ## 3. 重写：`.bak` → `.tmp` → `rename` **选了什么**：任何重写都先复制一份 `.bak`，把新内容写进 `.tmp`，最后 `rename` 覆盖。 **为什么**：`rename` 在同一文件系统内是原子替换 —— 要么旧内容、要么新内容，不会出现半份。 `.bak` 是"上一步"的快照，用于人肉回滚。 **代价**：每次重写多两次 I/O，还会常驻一个 `.bak`。对几千行的文件无所谓。 ## 4. 并发：复核 + 拒绝，而不是加锁 **选了什么**：`update` / `remove` / `restore` 都是「读—改—写」。读的时候连**内容哈希**一起记下 （`readJsonl()` 返回 `snapshot`），提交前复核哈希有没有变；变了就**不动文件**，返回 `{ ok: false, error: 'concurrent-modification' }`，并删掉 `.tmp`。 **为什么不是文件锁**：锁要处理持有时长、进程崩溃后残留、以及"等多久算超时"。**任何一处没处理对， 调用方就会挂住** —— 对一个跑在宿主进程里的插件来说，"卡住用户的会话"比"报一个错"严重得多。 复核 + 拒绝没有这些失效模式：它要么成功，要么立刻给出明确失败。 **代价**：冲突时用户要自己重试（错误里带着 id，能直接重跑那条命令）。 极小的窗口（复核之后、`rename` 之前）仍有理论上的竞态，`restore` 因此会在那种情况下返回 `note: 'entry-restored-deleted-log-unchanged'` —— **如实说清发生了什么，而不是假报成功**。 **为什么 `remove` 的顺序是先重写、再留档**：反过来的话，一旦复核失败，留档里已经多了一条**指向 "其实还在用"的条目**的记录，比原来的问题更难收拾。现在的顺序在冲突时"什么都不写"； 两次操作之间若崩溃，下一次重写的自愈会把它记成 `auto-archived`（有记录，不静默丢）。 ## 5. 自愈：重写时发现"消失且没留档"就补记 **选了什么**：重写前后对比，凡是**这次消失、删除留档里也没有**的 id，补一条 `why: 'auto-archived'` 的留档。 **为什么**：清单是人的资产。任何"条目不见了但没人知道为什么"的情况都应该留下痕迹 —— 哪怕是别的进程、别的工具、或用户手工编辑造成的。 **代价**：留档里会出现用户没主动删过的记录。这是**故意的**：宁可多一条能解释的记录， 也不要一条查不到去向的消失。 ## 6. 页面：请求期渲染，不做构建 **选了什么**：管理页由 `lib/page.js` 在**请求时**拼出完整 HTML（内联样式与脚本、中英双语文案一起打包）。 **为什么**：插件不该要求用户装构建工具链。没有 `dist/`、没有 watch、没有"忘了 build 所以改动没生效"。 改一行 `page.js`、刷新浏览器就能看到。也因此**包里没有生成物**，`npm pack` 出来的就是源码。 **代价**：页面代码写在一段模板字符串里 —— 这是个真实的坑：模板里再出现反引号会把脚本提前截断 （第 3 轮真犯过）。所以现在有 `test/page.test.mjs` 把渲染结果里的 `