43 lines
3.3 KiB
Markdown
43 lines
3.3 KiB
Markdown
# @deepseek-ai/dsh-session-registry-file
|
||
|
||
[English](README.md) | 中文
|
||
|
||
[存活会话注册表 seam](../session-registry/README.md) 的文件后端实现：整套介质就是 Harness home 下的一个加锁保护的 JSON 文件。挂载它即发布 `ctx.sessionRegistry`；`file` 暴露注册表文件的绝对路径（`<root>/sessions.json`）。
|
||
|
||
## 存活状态与崩溃安全
|
||
|
||
存活状态在读取时由记录的 pid 经 `kill(pid, 0)` 推导：`ESRCH` 表示已消亡，`EPERM` 表示存活于另一个用户之下，其他任何 errno 都向外抛出，而不会被当成一个答案来解读。因此，未运行 disposer 就被杀掉的进程留下的记录，会被下一次 `list()` 剪除并重写——不需要 daemon，不需要心跳，也不会有永久残留的幽灵记录。`bootId` 用于区分被复用的 pid，因此注销不会删除属于另一个 incarnation 的同名记录。
|
||
|
||
## 并发
|
||
|
||
两层机制都是必需的，任何一层都无法替代另一层。
|
||
|
||
- **跨进程**：每个读改写周期都持有 [`proper-lockfile`](https://github.com/moxystudio/node-proper-lockfile) 咨询锁。无锁的全文件重发布会在并发启动器下丢失记录，这正是 storage-hub JSON 后端（文档声明 last-write-wins、单宿主进程）无法承担该介质的原因。
|
||
- **进程内**：调用在内部链上排队。咨询锁按进程跟踪，因此同进程的重叠调用者会争用其有限的重试预算而非排队；并发调用超过十来个时预算耗尽，注册会被拒绝。调用方以 fire-and-forget 方式发布，这样的拒绝会静默地把一个存活会话从列表中丢掉。
|
||
|
||
写入采用临时文件加原子 `rename`（不做 fsync：崩溃丢失的列表会被下一个进程的读取重建，崩溃持久性在这里没有收益），根目录 `0o700`，文件 `0o600`。
|
||
|
||
## 持久化格式
|
||
|
||
`sessions.json` 携带一个 `version` 戳，在预发布立场下固定为 `0`：版本不同将被拒绝而非迁移。由于介质是共享且用户可见的，读取会校验每个字段。单条不可用的行会被丢弃而其同伴保留；无法解析的文本或异版本文件读作空——另一个 harness 版本写入的一条损坏记录，不得隐藏所有其他存活会话。上述任一情况都会把介质标记为受损，下一次写入将重新发布并修复它。
|
||
|
||
## 配置
|
||
|
||
| 键 | 类型 | 默认值 | 含义 |
|
||
| --- | --- | --- | --- |
|
||
| `root` | string | 必填——无默认值（回退到 cwd 会使注册表散落各处） | 存放 `sessions.json` 的目录；按需以 `0o700` 创建 |
|
||
| `lockStaleMs` | natural | `10000` | 持有的锁超过该毫秒数即视为被遗弃并被回收 |
|
||
| `lockRetries` | natural | `10` | 锁争用时在明确失败前的重试次数 |
|
||
|
||
## 模型体验
|
||
|
||
无。本包不注册工具、不注入提示词、不追加会话事件；它只为 CLI 列表界面存储宿主侧进程记录。
|
||
|
||
#### KV 缓存影响
|
||
|
||
与在途请求无关：注册表从不触碰请求前缀，因此这里不会使提供方缓存复用失效。
|
||
|
||
## 已知限制与后续工作
|
||
|
||
- **陈旧窗口内被复用的 pid 会被信任**——`bootId` 能区分本进程所写记录的 incarnation，但外来记录的 pid 若已被操作系统重新分配给无关的存活进程，在其属主移除之前会一直被报告为存活。
|