dsh-session-ops 0.0.0-stage → 0.2.0

package/lib/sessionlog.js

@@ -0,0 +1,14 @@
+/**
+ * 会话日志的帧级读写原语 —— **实现在本包的 `lib/store/` 里**（`dsh-session-ops`）。
+ *
+ * 这个文件现在只是一层**历史路径的门面**：`./sessionlog.js` 曾经是本插件私有的
+ * 实现（从 dsh-sync 移植），而删除半边那边重复着同一套知识的另一半
+ * （`decodeProjectKey`）。两个插件合并成 `dsh-session-ops` 之后：
+ *   - 实现只有一份，规则与边界都写在 `lib/store/paths.js` / `lib/store/frames.js`
+ *     的模块注释里；
+ *   - 这里的模块路径保留下来，是为了让本包原有的 `test/*.mjs` 不必改 import 就继续可用。
+ *
+ * @module dsh-session-ops/sessionlog
+ */
+export { CHECKSUM_OPTIONS, ZSTD_MAGIC, hasZstd, readHeaderFromBuffer, rewriteHeaderCwd, scanZstdFrames, } from './store/frames.js';
+export { compressionSuffix, encodeSegment, generationLogFilename, logPath, projectKey, sessionDir, } from './store/paths.js';

package/lib/store/frames.js

@@ -0,0 +1,274 @@
+/**
+ * 会话日志（`session[.vN].jsonl[.zstd]`）的**帧级读写原语**。
+ *
+ * ## 帧格式
+ *
+ * 日志是**独立 Zstandard 帧的标准拼接**：帧 0 只含 header 行（DSH 的
+ * `assertIndependentHeaderFrame` 强制），之后每帧是一个事件批次。于是改写只需重压
+ * 帧 0、再把剩余字节原样接上——后续帧一个字节都不动。
+ *
+ * 两个必须对齐的细节：
+ *   - DSH 压缩时带内容校验和（`params: {[ZSTD_c_checksumFlag]: 1}`），重压帧 0
+ *     也必须带（见 {@link CHECKSUM_OPTIONS}）；
+ *   - 帧边界要自己走一遍（Node 不暴露「已消费输入字节数」），就是下面的
+ *     {@link scanZstdFrames}。
+ *
+ * ## 为什么头部这么要紧
+ *
+ * header 承载 `cwd` / `origin` / `parentSession` / `isSeeded`：
+ *   - 「会话属于哪个工作区」在 DSH 里**只**由 `header.cwd` 决定
+ *     （`WorkspaceEntity.sessionIds` 每次读取都用 `realpath(header.cwd) === workspace.path`
+ *     过滤），加上 `assertStoredIdentity` 要求物理路径等于
+ *     `logPath(root, header.cwd, id)`，所以搬迁 == 改 cwd + 挪目录；
+ *   - 「是不是子代理会话」只能从 `origin` 拿，projcache 里没有。
+ *
+ * 于是本模块同时提供两种读法，**语义不同、不要互相替换**：
+ *   - {@link readHeaderFromBuffer}：只解**帧 0**（帧结构严格，给搬迁用）；
+ *   - {@link readSessionHeader}：按目录找日志文件、整段解压取第一行（宽松，给扫描/删除用）。
+ *
+ * @module dsh-session-ops/store/frames
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import zlib from 'node:zlib';
+import { isSessionLogFile } from './paths.js';
+import { messageOf } from './util.js';
+/** zstd 帧魔数（小端）。 */
+export const ZSTD_MAGIC = 0xfd2fb528;
+/** 与 DSH 一致的压缩选项：带内容校验和。 */
+export const CHECKSUM_OPTIONS = zlib.constants?.ZSTD_c_checksumFlag === undefined
+    ? {}
+    : { params: { [zlib.constants.ZSTD_c_checksumFlag]: 1 } };
+/** `zstdCompressSync` 需要 Node ≥22.15 / ≥23.8；缺失时插件拒绝搬迁而不是写坏日志。 */
+export const hasZstd = typeof zlib.zstdCompressSync === 'function' && typeof zlib.zstdDecompressSync === 'function';
+/** `zstdDecompressSync` 同样需要 Node ≥22.15；缺失时降级为「读不到会话头」。 */
+const zstdDecompress = typeof zlib.zstdDecompressSync === 'function' ? zlib.zstdDecompressSync : undefined;
+/**
+ * 走一遍拼接帧，给出每帧的字节范围。
+ *
+ * 按 zstd 规范解析帧头（魔数 → Frame_Header_Descriptor → 可选窗口描述符 /
+ * 字典 id / 内容长度）与块序列（3 字节块头 → 块体），直到 Last_Block，
+ * 再按标志位跳过 4 字节内容校验和。
+ *
+ * @param buffer - 整个日志文件的内容。
+ * @returns `{frames, incomplete, reason}`；`frames` 每项含 `{start, end}`。
+ */
+export function scanZstdFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const start = offset;
+        if (buffer.length - offset < 4)
+            return { frames, incomplete: true, reason: `尾部剩 ${buffer.length - offset} 字节，不足以构成帧魔数` };
+        if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) {
+            return { frames, incomplete: true, reason: `偏移 ${offset} 处不是 zstd 魔数` };
+        }
+        offset += 4;
+        if (offset >= buffer.length)
+            return { frames, incomplete: true, reason: '帧头被截断（缺少描述符）' };
+        const descriptor = buffer.readUInt8(offset);
+        offset += 1;
+        const fcsFlag = descriptor >> 6;
+        const singleSegment = (descriptor >> 5) & 1;
+        const checksum = (descriptor >> 2) & 1;
+        const dictionaryFlag = descriptor & 3;
+        if (singleSegment === 0)
+            offset += 1; // Window_Descriptor
+        offset += dictionaryFlag === 0 ? 0 : dictionaryFlag === 1 ? 1 : dictionaryFlag === 2 ? 2 : 4;
+        const fcsSize = fcsFlag === 0 ? (singleSegment === 1 ? 1 : 0) : fcsFlag === 1 ? 2 : fcsFlag === 2 ? 4 : 8;
+        offset += fcsSize;
+        if (offset > buffer.length)
+            return { frames, incomplete: true, reason: '帧头字段越过文件尾' };
+        for (;;) {
+            if (offset + 3 > buffer.length)
+                return { frames, incomplete: true, reason: '块头被截断' };
+            const header = buffer.readUInt8(offset) | (buffer.readUInt8(offset + 1) << 8) | (buffer.readUInt8(offset + 2) << 16);
+            offset += 3;
+            const lastBlock = header & 1;
+            const blockType = (header >> 1) & 3;
+            const blockSize = header >> 3;
+            if (blockType === 0)
+                offset += blockSize;
+            else if (blockType === 1)
+                offset += 1;
+            else if (blockType === 2)
+                offset += blockSize;
+            else
+                return { frames, incomplete: true, reason: `偏移 ${offset - 3} 处出现保留块类型` };
+            if (lastBlock === 1)
+                break;
+        }
+        if (checksum === 1)
+            offset += 4;
+        if (offset > buffer.length)
+            return { frames, incomplete: true, reason: '帧体越过文件尾' };
+        frames.push({ start, end: offset });
+    }
+    return { frames, incomplete: false };
+}
+/**
+ * 读出日志第一帧里的 header 对象（只解析，不改写）。
+ * @param buffer - 日志内容。
+ * @param compressed - `true`（默认）表示 zstd 帧日志，`false` 表示未压缩的行式日志。
+ * @returns header 对象；不是合法会话日志时 `undefined`。
+ */
+export function readHeaderFromBuffer(buffer, compressed = true) {
+    if (!compressed) {
+        try {
+            const text = buffer.toString('utf8');
+            const newlineIndex = text.indexOf('\n');
+            const parsed = JSON.parse(newlineIndex === -1 ? text : text.slice(0, newlineIndex));
+            return parsed !== null && typeof parsed === 'object' && parsed.type === 'session' ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const scan = scanZstdFrames(buffer);
+    if (scan.frames.length === 0)
+        return undefined;
+    try {
+        const first = scan.frames[0];
+        const inflated = zlib.zstdDecompressSync(buffer.subarray(first.start, first.end));
+        const text = Buffer.from(inflated).toString('utf8');
+        const newlineIndex = text.indexOf('\n');
+        const parsed = JSON.parse(newlineIndex === -1 ? text : text.slice(0, newlineIndex));
+        return parsed !== null && typeof parsed === 'object' && parsed.type === 'session' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 把一个会话目录里的会话头读出来（**宽松**读法：扫目录找日志文件，取解压后的第一行）。
+ *
+ * 与 {@link readHeaderFromBuffer} 的区别是它不校验帧结构、也不要求 `type === 'session'`：
+ * 目录里可能有半截写入或手工改名的日志，扫描/删除路径宁可拿到一个「像头部」的对象，
+ * 也不要因为格式不严格就把整条会话当成不可读。
+ *
+ * 解压失败（截断、缺 zstd 支持）返回 `undefined`，调用方按「未知」处理。
+ * @param dir - 会话目录。
+ * @param cache - 以 `路径:mtime:size` 为键的头部缓存（可选；不传就现建一个）。
+ * @returns 头部对象，或 undefined。
+ */
+export function readSessionHeader(dir, cache = new Map()) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return undefined;
+    }
+    const log = entries.find((e) => e.isFile() && isSessionLogFile(e.name));
+    if (log === undefined)
+        return undefined;
+    const path = join(dir, log.name);
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch {
+        return undefined;
+    }
+    const key = `${path}:${stat.mtimeMs}:${stat.size}`;
+    if (cache.has(key))
+        return cache.get(key);
+    let header;
+    try {
+        const raw = readFileSync(path);
+        const text = log.name.endsWith('.zstd')
+            ? zstdDecompress === undefined
+                ? undefined
+                : zstdDecompress(raw).toString('utf8')
+            : raw.toString('utf8');
+        if (text !== undefined) {
+            const end = text.indexOf('\n');
+            header = JSON.parse(end === -1 ? text : text.slice(0, end));
+        }
+    }
+    catch {
+        header = undefined;
+    }
+    cache.set(key, header);
+    return header;
+}
+/**
+ * 把会话头的 `cwd` 改写成另一条绝对路径。
+ *
+ * 只动 `cwd` 一个键，其余键（含该 generation 自己的字段）按原顺序逐字保留；
+ * 帧 0 之后的字节**原样接上**，所以事件批次一个字节都没变。
+ *
+ * @param buffer - 日志内容。
+ * @param newCwd - 改写后的绝对路径。
+ * @param options - `{compressed}`：帧日志（默认 `true`）或未压缩行式日志。
+ * @returns `{buffer, rewritten, header, frames?, reason?}`；无需改写或无法改写时
+ *   `rewritten: false` 并原样返回。
+ */
+export function rewriteHeaderCwd(buffer, newCwd, options = {}) {
+    const compressed = options.compressed !== false;
+    if (typeof newCwd !== 'string' || newCwd.length === 0) {
+        return { buffer, rewritten: false, reason: 'empty target cwd' };
+    }
+    if (!compressed) {
+        const text = buffer.toString('utf8');
+        const newlineIndex = text.indexOf('\n');
+        const firstLine = newlineIndex === -1 ? text : text.slice(0, newlineIndex);
+        const rest = newlineIndex === -1 ? '' : text.slice(newlineIndex);
+        let header;
+        try {
+            header = JSON.parse(firstLine);
+        }
+        catch {
+            return { buffer, rewritten: false, reason: 'header line is not JSON' };
+        }
+        if (header?.type !== 'session' || typeof header.cwd !== 'string') {
+            return { buffer, rewritten: false, reason: 'header has no cwd' };
+        }
+        if (header.cwd === newCwd)
+            return { buffer, rewritten: false, header };
+        const rebuilt = {};
+        for (const [key, value] of Object.entries(header))
+            rebuilt[key] = key === 'cwd' ? newCwd : value;
+        return { buffer: Buffer.from(JSON.stringify(rebuilt) + rest, 'utf8'), rewritten: true, header: rebuilt };
+    }
+    if (!hasZstd)
+        return { buffer, rewritten: false, reason: 'this node build lacks zlib zstd support' };
+    const scan = scanZstdFrames(buffer);
+    if (scan.incomplete || scan.frames.length === 0) {
+        return { buffer, rewritten: false, reason: scan.reason ?? 'no complete frame' };
+    }
+    const firstFrame = scan.frames[0];
+    let header;
+    let rest;
+    try {
+        const inflated = zlib.zstdDecompressSync(buffer.subarray(firstFrame.start, firstFrame.end));
+        const text = Buffer.from(inflated).toString('utf8');
+        const newlineIndex = text.indexOf('\n');
+        header = JSON.parse(newlineIndex === -1 ? text : text.slice(0, newlineIndex));
+        rest = newlineIndex === -1 ? '' : text.slice(newlineIndex);
+    }
+    catch (error) {
+        return { buffer, rewritten: false, reason: `cannot decode header frame: ${messageOf(error)}` };
+    }
+    if (header?.type !== 'session' || typeof header.cwd !== 'string') {
+        return { buffer, rewritten: false, reason: 'header has no cwd' };
+    }
+    if (header.cwd === newCwd)
+        return { buffer, rewritten: false, header, frames: scan.frames.length };
+    const rebuilt = {};
+    for (const [key, value] of Object.entries(header))
+        rebuilt[key] = key === 'cwd' ? newCwd : value;
+    let newFrame;
+    try {
+        newFrame = zlib.zstdCompressSync(Buffer.from(JSON.stringify(rebuilt) + rest, 'utf8'), CHECKSUM_OPTIONS);
+    }
+    catch (error) {
+        return { buffer, rewritten: false, reason: `cannot recompress header frame: ${messageOf(error)}` };
+    }
+    return {
+        buffer: Buffer.concat([newFrame, buffer.subarray(firstFrame.end)]),
+        rewritten: true,
+        header: rebuilt,
+        frames: scan.frames.length,
+    };
+}

package/lib/store/host.js

@@ -0,0 +1,104 @@
+/**
+ * 宿主侧的公共底座：`$DSH_HOME`、尽力而为的文件日志、以及 volatile 配置的解包。
+ *
+ * 这几段代码在两个插件里逐字重复——它们都是「DSH 宿主约定」而不是插件策略：
+ *   - `dshHome()` 认 `DSH_HOME` 环境变量（测试靠它把整个沙箱指到临时目录）；
+ *   - 宿主 stdout 不落盘，排障只能靠 `$DSH_HOME/logs/<name>.log`；
+ *   - 标了 `.volatile()` 的配置字段，Loader 交给 `apply` 的是活引用（`{get()}`）
+ *     而不是值，值在写盘后原地更新，所以**解包必须做两次**（进 schema 之前一次、
+ *     schema 出来之后再一次，后者是因为 schemastery 对 volatile 字段输出的也是活引用）。
+ *
+ * 文件日志的**行格式两边不同**（admin 是 `[时间] 级别 正文`，move 是 `时间 [级别] 正文`），
+ * 这是对外可见的排障产物，所以这里不做统一，而是把两种格式都作为预设导出，
+ * 由调用方显式选择（见 {@link LOG_LINE_LEVEL_FIRST} / {@link LOG_LINE_TIME_FIRST}）。
+ *
+ * @module dsh-session-ops/store/host
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** `$DSH_HOME`：环境变量优先，默认 `~/.dsh`。 */
+export function dshHome() {
+    const fromEnv = process.env.DSH_HOME;
+    return fromEnv !== undefined && fromEnv !== '' ? fromEnv : join(homedir(), '.dsh');
+}
+/**
+ * 文件日志行格式之一：`[ISO 时间] 级别 正文`（`dsh-session-admin` 在用）。
+ * @param entry - `{iso, level, message}`。
+ * @returns 一整行（含结尾换行）。
+ */
+export const LOG_LINE_LEVEL_FIRST = ({ iso, level, message }) => `[${iso}] ${level} ${message}\n`;
+/**
+ * 文件日志行格式之一：`ISO 时间 [级别] 正文`（`dsh-session-move` 在用）。
+ * @param entry - `{iso, level, message}`。
+ * @returns 一整行（含结尾换行）。
+ */
+export const LOG_LINE_TIME_FIRST = ({ iso, level, message }) => `${iso} [${level}] ${message}\n`;
+/**
+ * 尽力而为的文件日志：写 `$DSH_HOME/logs/<name>.log`，并顺带喂宿主 logger。
+ *
+ * 任何一步失败都静默吞掉——日志本身永远不该成为故障源（建目录失败、磁盘满了、
+ * 宿主 logger 不可用，都不影响插件机制）。
+ * @param ctx - Host cordis 上下文（只用 `ctx?.logger`，可为 undefined）。
+ * @param options - `{name, formatLine}`：日志文件名（不含 `.log`；默认
+ *   `dsh-session-ops`）与行格式（默认 {@link LOG_LINE_LEVEL_FIRST}）。
+ * @returns `(level, message) => void`，即插件里的 `log`。
+ */
+export function createFileLogger(ctx, options = {}) {
+    const name = typeof options.name === 'string' && options.name.length > 0 ? options.name : 'dsh-session-ops';
+    const formatLine = typeof options.formatLine === 'function' ? options.formatLine : LOG_LINE_LEVEL_FIRST;
+    let path;
+    try {
+        const dir = join(dshHome(), 'logs');
+        mkdirSync(dir, { recursive: true });
+        path = join(dir, `${name}.log`);
+    }
+    catch {
+        path = undefined;
+    }
+    return (level, message) => {
+        try {
+            ctx?.logger?.[level]?.(message);
+        }
+        catch {
+            /* 宿主 logger 不可用不影响文件日志 */
+        }
+        if (path === undefined)
+            return;
+        try {
+            appendFileSync(path, formatLine({ iso: new Date().toISOString(), level, message }), 'utf8');
+        }
+        catch {
+            /* 日志写不进去就算了 */
+        }
+    };
+}
+/**
+ * 解包 entry 配置里的 `.volatile()` 活引用。
+ * @param raw - entry 配置或普通配置对象。
+ * @returns 值已解包的浅拷贝。
+ */
+export function plainConfig(raw = {}) {
+    const source = raw !== null && typeof raw === 'object' ? raw : {};
+    const plain = {};
+    for (const [key, value] of Object.entries(source)) {
+        plain[key] = value !== null && typeof value === 'object' && typeof value.get === 'function'
+            ? value.get()
+            : value;
+    }
+    return plain;
+}
+/**
+ * 解析一份 entry 配置：先解包输入的活引用，再交给 schema 校验并补默认值，最后**再解包
+ * 一次**——schemastery 对 `.volatile()` 字段输出的也是活引用，不收敛的话读到的就是
+ * `{ get() }` 对象（HTTP 面上会变成一个空对象）。
+ *
+ * schema 由调用方传入（本包只把 `@deepseek-ai/schemastery` 当类型来源），传进来的只要是
+ * 「可调用、收普通对象、返回带默认值的普通对象」即可。
+ * @param schema - 插件自己的 `Config`（schemastery 对象，可调用）。
+ * @param raw - entry 配置或普通配置对象。
+ * @returns 普通值配置。
+ */
+export function resolveVolatileConfig(schema, raw = {}) {
+    return plainConfig(schema(plainConfig(raw)));
+}

package/lib/store/http.js

@@ -0,0 +1,133 @@
+/**
+ * 两个会话插件共用的 **HTTP 面**：JSON 响应封装、请求体读取、以及前缀路由的骨架。
+ *
+ * 路由协议（响应码与响应体）是两个插件对浏览器半边的**公开契约**，必须逐字一致，
+ * 所以它只在写一份：
+ *   - 403 `{ok:false,error:{code:'forbidden',message:'forbidden'}}` —— 信任栅栏拒绝；
+ *   - 404 `{ok:false,error:{code:'not-found',message:'unknown method'}}` —— 路径没落在
+ *     前缀下，或方法名里还有 `/`；
+ *   - 404 `{ok:false,error:{code:'not-found',message:'unknown method <m>'}}` —— 方法不在表里；
+ *   - 200 `{ok:true,value}`；
+ *   - 400 `{ok:false,error:{code:'bad-request',message:<err.message>}}` —— 处理器抛错。
+ *   `GET` 的载荷是 query string，其余方法读 `JSON` 请求体（1 MiB 上限）。
+ *
+ * **信任栅栏本身刻意不在这里**：两个插件的判定依据不同（`dsh-session-admin` 看
+ * `Host` 头 + `sec-fetch-site`/`Origin` + `allowHosts` 的 host/hostname 匹配；
+ * `dsh-session-move` 看 socket 的 `remoteAddress` + `allowHosts` 精确字符串匹配），
+ * 语义不同就不能合并——合并必然改动其中一边的对外行为。这里只收一个
+ * `trustRequest(req) => boolean` 回调。
+ *
+ * 同理，`writeJson` 的 `content-length` 与 `readJsonBody` 的严格程度两边也不同，
+ * 都用显式开关保留原状（见各参数）。
+ *
+ * @module dsh-session-ops/store/http
+ */
+import { messageOf } from './util.js';
+/** 请求体上限：1 MiB。 */
+const MAX_BODY_BYTES = 1024 * 1024;
+/**
+ * 写一个 JSON 响应。
+ * @param res - Node HTTP 响应。
+ * @param status - 状态码。
+ * @param body - 任意可 JSON 序列化的值。
+ * @param options - `{contentLength}`：是否带上 `content-length` 头。默认 `false`
+ *   （`dsh-session-move` 的原样行为，响应走 chunked）；`dsh-session-admin` 传 `true`
+ *   以保留它原有的 `content-length`。
+ * @returns 无。
+ */
+export function writeJson(res, status, body, options = {}) {
+    const text = JSON.stringify(body);
+    if (options.contentLength === true) {
+        res.writeHead(status, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+            'content-length': Buffer.byteLength(text),
+        });
+    }
+    else {
+        res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    }
+    res.end(text);
+}
+/**
+ * 读一个 JSON 请求体（上限 1 MiB）。
+ *
+ * 严格程度由调用方选，因为两个插件原本就不一样：
+ *   - `requireObject: false`（默认，`dsh-session-admin` 的行为）：不 trim、不校验类型，
+ *     空 body 返回 `{}`，其余原样交给 `JSON.parse`（一个空白 body 会抛出
+ *     `Unexpected end of JSON input`，进而变成 400）；
+ *   - `requireObject: true`（`dsh-session-move` 的行为）：trim 后空串返回 `{}`，
+ *     解析结果必须是**普通对象**，否则抛 `request body must be a JSON object`。
+ * @param req - Node HTTP 请求。
+ * @param options - `{requireObject}`。
+ * @returns 解析出来的载荷对象。
+ */
+export async function readJsonBody(req, options = {}) {
+    const requireObject = options.requireObject === true;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error('request body too large');
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return {};
+    const buffer = Buffer.concat(chunks).toString('utf8');
+    if (!requireObject)
+        return JSON.parse(buffer);
+    const text = buffer.trim();
+    if (text === '')
+        return {};
+    const parsed = JSON.parse(text);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('request body must be a JSON object');
+    return parsed;
+}
+/**
+ * 造一个 `kind: 'prefix'` 路由处理器（`ctx.webServer.register({kind:'prefix', path, handler})` 的 `handler`）。
+ *
+ * 方法表里的每个处理器收到 `payload`，返回值包成 `{ok:true,value}`；抛错变成 400 并写一行
+ * `<method> failed: <message>` 日志。`GET` 的载荷是 query string（全部是字符串）。
+ * @param options - 见下。
+ * @param options.prefix - 路由前缀，如 `/session-admin/api`。
+ * @param options.methods - 方法名 → `async (payload) => value`。
+ * @param options.trustRequest - `(req) => boolean`：请求是否来自受信的浏览器（各插件自己的栅栏）。
+ * @param options.log - `(level, message) => void`（可为 undefined）。
+ * @param options.readBody - 读请求体，默认 {@link readJsonBody}（宽松）；`dsh-session-move`
+ *   传 `(req) => readJsonBody(req, {requireObject: true})`。
+ * @param options.contentLength - 透传给 {@link writeJson}。
+ * @returns `async (req, res) => void`。
+ */
+export function createApiHandler(options) {
+    const { prefix, methods, trustRequest, log, readBody = readJsonBody, contentLength = false } = options;
+    const reply = (res, status, body) => writeJson(res, status, body, { contentLength });
+    return async (req, res) => {
+        if (typeof trustRequest !== 'function' || !trustRequest(req)) {
+            reply(res, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } });
+            return;
+        }
+        const url = new URL(req.url ?? '/', 'http://dsh.internal');
+        const method = url.pathname.startsWith(`${prefix}/`) ? url.pathname.slice(prefix.length + 1) : undefined;
+        if (method === undefined || method.includes('/')) {
+            reply(res, 404, { ok: false, error: { code: 'not-found', message: 'unknown method' } });
+            return;
+        }
+        const handler = methods[method];
+        if (typeof handler !== 'function') {
+            reply(res, 404, { ok: false, error: { code: 'not-found', message: `unknown method ${method}` } });
+            return;
+        }
+        try {
+            const payload = req.method === 'GET' ? Object.fromEntries(url.searchParams) : await readBody(req);
+            const value = await handler(payload);
+            reply(res, 200, { ok: true, value });
+        }
+        catch (error) {
+            if (typeof log === 'function')
+                log('warn', `${method} failed: ${messageOf(error)}`);
+            reply(res, 400, { ok: false, error: { code: 'bad-request', message: messageOf(error) } });
+        }
+    };
+}

package/lib/store/index.js

@@ -0,0 +1,30 @@
+/**
+ * `dsh-session-ops/lib/store` —— 本包内部的**会话存储原语**。
+ *
+ * 这一层只做库：没有模型工具、没有槽位注册、没有 DSH 插件生命周期代码，
+ * 也**零 `@deepseek-ai/*` 运行时依赖**（只用 node 内置模块）。删除半边与搬迁半边
+ * 共用它，避免两边逐字重复同一套会话存储知识。
+ *
+ * 五个子模块：
+ *   - {@link module:dsh-session-ops/store/paths}：项目目录键 `--C-proj--` 的编解码、
+ *     会话目录与 generation 文件名的命名规则；
+ *   - {@link module:dsh-session-ops/store/frames}：`session[.vN].jsonl[.zstd]` 的帧扫描、
+ *     头部读取（两种严格度）与 cwd 改写；
+ *   - {@link module:dsh-session-ops/store/registry}：工作区注册表成员表 / 归档集合、
+ *     驻留会话、「正在跑一轮」判定、内存里三处 cwd 的重定向；
+ *   - {@link module:dsh-session-ops/store/host}：`$DSH_HOME`、尽力而为的文件日志、
+ *     volatile 配置解包；
+ *   - {@link module:dsh-session-ops/store/http}：两个半边共用的 HTTP 面（JSON 响应封装、
+ *     请求体读取、前缀路由骨架；**信任栅栏按插件语义不同，不在这里**）。
+ *
+ * 有意**没有**放进来的东西（语义不同或只有一边有）：两套信任栅栏、迁移的三步改名策略
+ * （`planMove`/`applyPlan`）、磁盘扫描与范围筛选（删除半边专有）、项目记忆跟随
+ * （搬迁半边专有）、模型工具与槽位定义。
+ *
+ * @module dsh-session-ops/store
+ */
+export * from './paths.js';
+export * from './frames.js';
+export * from './registry.js';
+export * from './host.js';
+export * from './http.js';