rhinelab-ui/docs/LOCAL-ARCHIVE.md

本地归档接入（LOCAL ARCHIVE）

把 E:\归档 接进本界面：主阵列展示从归档中精选的四十条档案，LOCAL ARCHIVE 面板负责检索归档的全部条目并直接执行归档写操作。

两块数据的关系

	三维阵列	主检索的本地归档栏 + LOCAL ARCHIVE 面板
数据	public/archive-index.json（全量，运行时载入）	同一份索引
内容	列 = 归档顶层内容分类，列内 = 该分类的全部真实归档条目	全量条目（约 5 万条路径）
用途	三维阵列、详情、解密动效、抽盘与拖拽	列表检索、打开、定位、归档操作
条数约束	无（随归档变化）	无
降级	索引不可用时退回 content/archives.json 的四十条精选档案	退回静态快照，只读

2026-09-12 起阵列已改为全量归档驱动，因此归档里新增的文件会直接出现在阵列中（换到它所在的列即可）。三维阵列与检索列表共用同一份内存索引（loadArchiveIndex），不会重复下载。

四十条精选档案现在只作为降级数据集与 TXT 摘要来源，见 ../content/README.md。全量阵列的设计、性能与证据见 ../verification/ARCHIVE-ARRAY.md。

启动

推荐一条命令同时拉起归档服务与开发服务器：

npm run dev:archive

也可以分开启动（两个终端）：

npm run archive:serve   # 归档服务，默认 127.0.0.1:43117
npm run dev             # Vite 开发服务器

只跑 npm run dev 也能用：面板会退回只读检索模式，此时打开文件、定位与归档操作会被禁用并给出提示。

启动后点击顶部导航的 LOCAL ARCHIVE。

数据更新

服务启动时会扫描一次归档并在 E:\归档 上挂一个递归监视器。归档里新增或改动文件后，约 2.5 秒防抖，服务自动重新生成快照，并通过事件流通知已打开的页面重新载入索引——不需要手动刷新。

也可以点面板状态栏的重新扫描 ↻，或调用 POST /archive-api/refresh。

npm run dev / npm run build 的钩子也会各生成一次快照。

详情页的「文件位置」按钮

详情页右下角的 SHOW IN FOLDER / 文件位置 按钮（原先是 EXPORT 下载 TXT）会直接在资源管理器中定位当前档案在 E:\归档 中的位置，用的是该条精选档案在 content/archives.json 里的真实 path，通过本地归档服务的 POST /reveal 完成。

• 服务未运行时按钮会提示"需要本地归档服务：请运行 npm run dev:archive"，不会静默失败。
• 详情页脚注显示的是归档内的相对路径文本。浏览器不允许网页跳转 file: 链接，所以它不再是可点击链接。
• public/archives/*.txt 仍会为每条档案生成，但详情页不再提供下载入口。

面板能做什么

检索：输入任意片段，匹配相对路径（含文件名与扩展名）。命中数实时显示，单次最多渲染 200 行，匹配片段高亮。索引在第一次打开面板时载入一次，之后在内存中过滤，不再走网络。

每行的三个动作：

按钮	行为	是否需要服务
打开	用系统默认程序打开文件；目录则用资源管理器打开	是
定位	在资源管理器中选中该条目	是
归档…	选中该条目作为源，在右侧进入归档操作	是

归档操作（四种，均为安全写）：

操作	说明
移动到	归档内移动，同盘重命名。跨盘拒绝，请改用复制
复制到	递归复制
解压到	调用 C:\Program Files\7-Zip\7z.exe 解压到目标目录
新建分类目录	在归档内新建目录

一律先点「预览影响」：显示源、目标、体积、文件数、是否跨盘，并给出能不能执行的结论。预览不通过时执行按钮保持禁用。执行结果用界面右下角的提示条反馈，并追加到操作日志。

不提供删除与重命名：这两项不可逆，需要时请在资源管理器中手动完成。

安全设计

• 只监听回环：服务绑定 127.0.0.1，不对外网开放。
• 每次启动的访问令牌：服务启动时生成随机令牌写入项目根目录的 .archive-token（已加入 .gitignore）。浏览器不持有令牌——Vite 在 /archive-api 代理层注入它。因此即使别的网页知道端口号，也无法调用本服务。
• 路径围栏：客户端只传相对路径，服务解析为绝对路径后必须仍落在归档根目录内；越界、绝对路径与 .. 一律 403。符号链接不算越界，但不会被跟随。
• 操作日志：每次写操作追加一行 JSON 到 E:\归档\00_索引\操作日志.jsonl，含时间、操作、源、目标。
• 写操作需要显式确认：/apply 必须带 confirm: true，否则 400。服务端会重新计算一次影响预览，不信任客户端传来的结论。

配置

archive.config.json：

{
  "root": "E:\\归档",
  "port": 43117,
  "exclude": [],
  "indexFile": "public/archive-index.json",
  "logFile": "00_索引\\操作日志.jsonl"
}

exclude 里的目录会被索引跳过（其本身仍作为目录条目保留）。改 port 时不需要同步改前端：Vite 代理会在配置加载时读取同一个文件。

接口

所有接口都需要 x-archive-token 头，经 Vite 代理访问时自动注入。在浏览器或 curl 里直接调用时前缀为 /archive-api，直连服务时无前缀。

方法与路径	用途
GET /status	根目录、端口、监视状态、最近一次快照时间、总量
GET /index	全量索引（支持 gzip，约 0.7 MB）
GET /search?q=&limit=	服务端检索
POST /plan	影响预览，不修改任何文件
POST /apply	执行写操作，需要 confirm: true
POST /open / POST /reveal	打开文件 / 在资源管理器中定位
POST /refresh	立即重新扫描归档
GET /events	快照更新事件流（SSE）

快照文件

文件	体积	说明
content/archives.json	约 45 KB	四十条精选档案，页面与 TXT 下载共用
public/archive-index.json	约 7.4 MB	全量索引，紧凑数组 [路径, 类型, 字节, mtime]
public/archives/*.txt	40 个	每条档案的可下载摘要

archive-index.json 不进入 PWA 离线预缓存（scripts/build-pwa.mjs 的白名单不含根目录文件），因此离线包体积不受影响；代价是离线状态下打开检索面板只有空态。服务在线时索引走 gzip（约 0.7 MB），比静态快照快得多。

构建与部署

生产构建不包含归档服务，也不带 /archive-api 代理，线上站点打开面板会显示"只读检索模式"，检索走静态 archive-index.json，写操作不可用——这是刻意的：本地归档服务不应暴露在公网。

npm run preview 同样配置了代理，因此本地预览可以完整体验。

故障排查

现象	处理
面板显示"服务未运行"	先 npm run archive:serve；确认端口 43117 未被占用
打开/定位提示需要服务	同上；这是刻意的降级，检索仍可用
令牌无效（401）	服务重启会换新令牌；重启 Vite 让代理读到新值，或直接用 npm run dev:archive
「7-Zip 解压失败」	确认 C:\Program Files\7-Zip\7z.exe 存在；面板 /status 的 sevenZip 字段会说明
新增文件没有出现在检索里	① 等约 3 秒（防抖），或点「重新扫描 ↻」② 查 /status 的 lastError 与 lastScan ③ 手动 npm run archive:snapshot。索引与检索本身极少出错，先查服务和快照时间，再怀疑代码。
面板开了很久、刚加的文件搜不到	面板每次打开都会重新取索引（服务在线时），关闭面板不再退掉事件订阅；若仍不对，Ctrl+F5 整页刷新一次。
摘要里的数字和归档对不上	重新生成快照；{size}/{files}/{date} 只在生成时采样