@dsh-workbench/shared 0.3.6 → 0.3.8

package/dist/host/__tests__/fakes.js

@@ -0,0 +1,76 @@
+import { setTimeout as delay } from 'node:timers/promises';
+const tick = () => delay(0);
+export function createFakeShell(replies = []) {
+    const calls = [];
+    let running = 0;
+    let peak = 0;
+    const replyAt = (index) => typeof replies === 'function' ? replies(calls[index], index) : (replies[index] ?? {});
+    const shell = {
+        resolve(request) {
+            calls.push(request);
+            return request;
+        },
+        async execute() {
+            const index = calls.length - 1;
+            const reply = replyAt(index);
+            if (reply.failWith !== undefined)
+                throw reply.failWith;
+            running += 1;
+            peak = Math.max(peak, running);
+            return {
+                async result() {
+                    await tick();
+                    running -= 1;
+                    return {
+                        exitCode: reply.exitCode ?? 0,
+                        timedOut: reply.timedOut ?? false,
+                        aborted: reply.aborted ?? false,
+                        stdout: { text: reply.stdout ?? '', truncated: false },
+                        stderr: { text: reply.stderr ?? '', truncated: false },
+                    };
+                },
+            };
+        },
+    };
+    return {
+        shell,
+        calls,
+        peak: () => peak,
+        commands: () => calls.map((call) => call.command),
+    };
+}
+export function createFakeOpencli(replies = []) {
+    const calls = [];
+    const opencli = {
+        async json(args, options = {}) {
+            const call = {
+                args,
+                ...(options.key === undefined ? {} : { key: options.key }),
+                ...(options.workdir === undefined ? {} : { workdir: options.workdir }),
+            };
+            calls.push(call);
+            const index = calls.length - 1;
+            const reply = typeof replies === 'function' ? replies(call, index) : (replies[index] ?? []);
+            if (reply instanceof Error)
+                throw reply;
+            return { value: reply, at: Date.now() };
+        },
+    };
+    return {
+        opencli,
+        calls,
+        keys: () => calls.map((call) => call.key),
+    };
+}
+export function createFakeLogger() {
+    const warnings = [];
+    return {
+        logger: {
+            info: () => { },
+            warn: (message) => {
+                warnings.push(message);
+            },
+        },
+        warnings,
+    };
+}

package/dist/host/__tests__/preflight-fixtures.d.ts

@@ -0,0 +1,19 @@
+import { createFakeShell } from './fakes';
+export declare const GOOD_BRIDGE_REPORT: string;
+export declare const ALL_OK: {
+    stdout: string;
+}[];
+export declare const STALE_DAEMON_BRIDGE: string;
+export declare const BROKEN_BRIDGE: string;
+export declare function build(replies: Parameters<typeof createFakeShell>[0], install?: () => Promise<{
+    ok: boolean;
+    detail: string;
+}>, warmReads?: () => readonly (readonly string[])[]): {
+    fake: {
+        shell: import("../..").DshShell;
+        calls: import("./fakes").ShellCall[];
+        peak: () => number;
+        commands: () => string[];
+    };
+    preflight: import("../preflight").Preflight;
+};

package/dist/host/__tests__/preflight-fixtures.js

@@ -0,0 +1,47 @@
+import { createPreflight } from '../preflight';
+import { createFakeShell } from './fakes';
+export const GOOD_BRIDGE_REPORT = [
+    'opencli v1.8.7 doctor (node v24.15.0)',
+    '',
+    '[OK] Daemon: running on port 19825 (v1.8.7)',
+    '[OK] Extension: connected (v1.0.24)',
+    '[OK] Connectivity: connected in 0.0s',
+    '',
+    'Everything looks good!',
+].join('\n');
+export const ALL_OK = [{ stdout: '1.8.8\n' }, { stdout: GOOD_BRIDGE_REPORT }];
+export const STALE_DAEMON_BRIDGE = [
+    'opencli v1.8.7 doctor (node v24.15.0)',
+    '',
+    '[STALE] Daemon: running on port 19825 (v1.8.8 != CLI v1.8.7)',
+    '[OK] Extension: connected (v1.0.24)',
+    '[OK] Connectivity: connected in 0.0s',
+    '',
+    'Issues:',
+    '  • Stale daemon detected: daemon v1.8.8 != CLI v1.8.7.',
+    '  Run: opencli daemon restart',
+].join('\n');
+export const BROKEN_BRIDGE = [
+    'opencli v1.8.7 doctor (node v24.15.0)',
+    '',
+    '[MISSING] Daemon: not running',
+    '[MISSING] Extension: not connected',
+    '[FAIL] Connectivity: failed (daemon not reachable)',
+    '',
+    'Issues:',
+    "  • Daemon is not running. It should start automatically when you run an opencli browser command.",
+    '  • Daemon is running but the Chrome/Chromium extension is not connected.',
+    'If the extension is not installed:',
+    '  1. Download from https://github.com/jackwener/opencli/releases',
+    '  2. Open chrome://extensions/ → Enable Developer Mode',
+    '  3. Click "Load unpacked" → select the extension folder',
+].join('\n');
+export function build(replies, install, warmReads) {
+    const fake = createFakeShell(replies);
+    const preflight = createPreflight({
+        shell: fake.shell,
+        ...(install === undefined ? {} : { install }),
+        ...(warmReads === undefined ? {} : { warmReads }),
+    });
+    return { fake, preflight };
+}

package/dist/host/board-fact.d.ts

@@ -0,0 +1,8 @@
+import { type BoardFactState, type BoardProbe } from '../lib/board-fact.js';
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
+export declare function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFactState;

package/dist/host/board-fact.js

@@ -0,0 +1,16 @@
+import { insideWorkshop } from '../lib/board-fact.js';
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
+export function boardFactOf(probe, workshop) {
+    if (!probe.workbench)
+        return 'unknown';
+    if (!probe.bar || !probe.open || !probe.drawn)
+        return 'hidden';
+    if (probe.board === '' || workshop === null)
+        return 'unknown';
+    return insideWorkshop(workshop, probe.board) ? 'workshop' : 'other';
+}

package/dist/host/browser-read.js

@@ -1,4 +1,5 @@
-import { parseJsonLoose, tailLines } from '../lib/text.js';
+import { parseJsonLoose } from '../lib/text.js';
+import { tailLines } from './shell-text.js';
 import { backgroundLine } from './opencli-window.js';
 import { runShell } from './shell.js';
 export const BROWSER_SCREEN_SESSION = 'workbench';

package/dist/host/context-inject.d.ts

@@ -0,0 +1,24 @@
+import { type ContextRef } from '@dsh-workbench/shared';
+import type { ContextRenderer } from './unit-face';
+export declare const CONTEXT_SOURCE_KIND = "workbench";
+export interface ScannableMessage {
+    readonly source?: {
+        readonly kind?: string;
+    };
+    readonly content?: readonly {
+        readonly type?: string;
+        readonly text?: string;
+    }[];
+}
+export type { ContextRenderer };
+export declare function collectContextRefs(messages: readonly ScannableMessage[]): ContextRef[];
+export declare function buildContextMessage(text: string, summary: string): unknown;
+export interface ContextInjector {
+    inject(messages: readonly ScannableMessage[], agent: unknown): Promise<unknown | undefined>;
+}
+export declare function createContextInjector(options: {
+    renderers: ReadonlyMap<string, ContextRenderer>;
+    logger?: {
+        warn?(message: string): void;
+    } | undefined;
+}): ContextInjector;

package/dist/host/context-inject.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { encodeRef, parseMarkers } from '@dsh-workbench/shared';
+export const CONTEXT_SOURCE_KIND = 'workbench';
+export function collectContextRefs(messages) {
+    const seen = new Set();
+    const refs = [];
+    for (const message of messages) {
+        if (message.source?.kind !== 'user')
+            continue;
+        for (const block of message.content ?? []) {
+            if (block.type !== 'text' || typeof block.text !== 'string')
+                continue;
+            for (const ref of parseMarkers(block.text)) {
+                const key = encodeRef(ref);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                refs.push(ref);
+            }
+        }
+    }
+    return refs;
+}
+export function buildContextMessage(text, summary) {
+    return {
+        role: 'user',
+        id: randomUUID(),
+        content: [{ type: 'text', text }],
+        source: { kind: CONTEXT_SOURCE_KIND, form: 'notice', summary },
+    };
+}
+export function createContextInjector(options) {
+    const done = new WeakMap();
+    return {
+        async inject(messages, agent) {
+            const refs = collectContextRefs(messages);
+            if (refs.length === 0)
+                return undefined;
+            const key = typeof agent === 'object' && agent !== null ? agent : undefined;
+            const seen = key === undefined ? undefined : (done.get(key) ?? new Set());
+            if (key !== undefined && seen !== undefined)
+                done.set(key, seen);
+            const fresh = [];
+            for (const ref of refs) {
+                const encoded = encodeRef(ref);
+                if (seen?.has(encoded) === true)
+                    continue;
+                seen?.add(encoded);
+                fresh.push(ref);
+            }
+            if (fresh.length === 0)
+                return undefined;
+            const texts = [];
+            for (const ref of fresh) {
+                const render = options.renderers.get(ref.kind);
+                if (render === undefined)
+                    continue;
+                let text;
+                try {
+                    text = await render(ref);
+                }
+                catch (error) {
+                    options.logger?.warn?.(`[dsh-workbench] 渲染对话引用失败：${String(error)}`);
+                    text = `工作台面板引用了一条内容（${encodeRef(ref)}），但当前渲染不出来（项目未选中或数据源不可用）。`;
+                }
+                if (text !== '')
+                    texts.push(text);
+            }
+            if (texts.length === 0)
+                return undefined;
+            return buildContextMessage(texts.join('\n\n'), `工作台引用：${fresh.length} 条`);
+        },
+    };
+}

package/dist/host/context-ref.d.ts

@@ -0,0 +1,13 @@
+import { type ContextRef } from '../api/context-ref.js';
+/**
+ * 把 kind:part/part 文本读回引用。
+ * @param text 待解析文本。
+ * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
+ */
+export declare function decodeRef(text: string): ContextRef | undefined;
+/**
+ * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
+ * @param text 任意文本；null / undefined 当空串。
+ * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
+ */
+export declare function parseMarkers(text: string): ContextRef[];

package/dist/host/context-ref.js

@@ -0,0 +1,41 @@
+import { CONTEXT_MARKER_NAME, encodeRef } from '../api/context-ref.js';
+const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._~%#/-]+)`, 'g');
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+/**
+ * 把 kind:part/part 文本读回引用。
+ * @param text 待解析文本。
+ * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
+ */
+export function decodeRef(text) {
+    const at = text.indexOf(':');
+    if (at <= 0 || at === text.length - 1)
+        return undefined;
+    const kind = text.slice(0, at);
+    if (!/^[a-z][a-z0-9-]*$/.test(kind))
+        return undefined;
+    const parts = text.slice(at + 1).split('/').filter((part) => part !== '');
+    if (parts.length === 0)
+        return undefined;
+    return { kind, parts };
+}
+/**
+ * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
+ * @param text 任意文本；null / undefined 当空串。
+ * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
+ */
+export function parseMarkers(text) {
+    const seen = new Set();
+    const refs = [];
+    for (const match of String(text ?? '').matchAll(MARKER)) {
+        const raw = match[1].replace(TRAILING_PUNCTUATION, '');
+        const ref = decodeRef(raw);
+        if (ref === undefined)
+            continue;
+        const key = encodeRef(ref);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push(ref);
+    }
+    return refs;
+}

package/dist/host/diy-debug.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 调试约定的两个相位：`debugging` 正占着用户的屏，`paused` 已暂停但仍持着约定。
+ */
+export type DebugPhase = 'debugging' | 'paused';
+/**
+ * 调试约定收得下的三个人话动作：暂停 / 继续 / 结束。
+ */
+export type DebugIntent = 'pause' | 'resume' | 'stop';
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
+export declare function parseDebugIntent(value: unknown): DebugIntent | null;
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export declare const DEBUG_STALE_MS: number;
+/**
+ * 一份活着的调试约定：相位 + 谁的会话 + 哪个工作区 / 板 / 单元 + 起于何时（`at` 是最后一次动作）。
+ */
+export interface DebugState {
+    readonly phase: DebugPhase;
+    readonly sessionId: string;
+    readonly workspacePath: string;
+    readonly title: string;
+    readonly board: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly startedAt: number;
+    readonly at: number;
+}
+/**
+ * 建立约定要交的那几件：会话、工作区、板、单元、名字，以及此刻的时间戳。
+ */
+export interface DebugPact {
+    readonly sessionId: string;
+    readonly workspacePath: string;
+    readonly title: string;
+    readonly board: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly now: number;
+}
+/**
+ * 约定被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已暂停 / 已在调试。
+ */
+export type DebugRefusal = 'already-held' | 'held-by-other' | 'not-owner' | 'none' | 'already-paused' | 'already-debugging';
+/**
+ * 一次约定动作的结果：成功带新状态，失败带拒绝码。
+ */
+export type DebugMove = {
+    readonly ok: true;
+    readonly state: DebugState;
+} | {
+    readonly ok: false;
+    readonly code: DebugRefusal;
+};
+/**
+ * 调试约定的存取口（外壳持有一份）：`live` 取当前有效的约定，`begin` / `pause` / `resume` / `stop` 推相位。
+ */
+export interface DebugStore {
+    live(now: number): DebugState | null;
+    begin(pact: DebugPact): DebugMove;
+    pause(sessionId: string, now: number): DebugMove;
+    resume(sessionId: string, now: number): DebugMove;
+    stop(sessionId: string, now: number): DebugMove;
+    settle?(): Promise<void>;
+}
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
+export declare function createDebugStore(): DebugStore;
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
+export declare function debugOwnerText(state: DebugState): string;

package/dist/host/diy-debug.js

@@ -0,0 +1,88 @@
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
+export function parseDebugIntent(value) {
+    return value === 'pause' || value === 'resume' || value === 'stop' ? value : null;
+}
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export const DEBUG_STALE_MS = 4 * 60 * 60 * 1000;
+function alive(state, now) {
+    if (state === null)
+        return null;
+    return now - state.at <= DEBUG_STALE_MS ? state : null;
+}
+function ownerOf(state, sessionId, now) {
+    const held = alive(state, now);
+    if (held === null)
+        return 'none';
+    return held.sessionId === sessionId ? held : 'not-owner';
+}
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
+export function createDebugStore() {
+    let held = null;
+    const live = (now) => alive(held, now);
+    return {
+        live,
+        begin(pact) {
+            const current = alive(held, pact.now);
+            if (current !== null) {
+                return { ok: false, code: current.sessionId === pact.sessionId ? 'already-held' : 'held-by-other' };
+            }
+            const state = {
+                phase: 'debugging',
+                sessionId: pact.sessionId,
+                workspacePath: pact.workspacePath,
+                title: pact.title,
+                board: pact.board,
+                unit: pact.unit,
+                name: pact.name,
+                startedAt: pact.now,
+                at: pact.now,
+            };
+            held = state;
+            return { ok: true, state };
+        },
+        pause(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'paused')
+                return { ok: false, code: 'already-paused' };
+            const state = { ...found, phase: 'paused', at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        resume(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            if (found.phase === 'debugging')
+                return { ok: false, code: 'already-debugging' };
+            const state = { ...found, phase: 'debugging', at: now };
+            held = state;
+            return { ok: true, state };
+        },
+        stop(sessionId, now) {
+            const found = ownerOf(held, sessionId, now);
+            if (typeof found === 'string')
+                return { ok: false, code: found };
+            held = null;
+            return { ok: true, state: found };
+        },
+    };
+}
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
+export function debugOwnerText(state) {
+    return `会话 ${state.sessionId}（自 ${new Date(state.startedAt).toISOString().slice(11, 19)}Z 起在调试 ${state.unit}）`;
+}

package/dist/host/diy-record.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 录制交接的三个相位：`armed` 等用户在外站页面上动手，`recording` 正在录，`finished` 录完待取。
+ */
+export type RecordPhase = 'armed' | 'recording' | 'finished';
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
+export declare const RECORD_STALE_MS: number;
+/**
+ * 这次录制要找的那一次写：HTTP 方法 + URL 里必须含的一段（不填就是只认方法）。
+ */
+export interface RecordExpect {
+    readonly method: string;
+    readonly urlContains: string;
+}
+/**
+ * 一次「截图」在宿主台账里的那一行：页面上的计数、落图那一刻、落盘路径；没落下来时带 `error` 原文（落成的那条没有它）。
+ */
+export interface RecordShot {
+    readonly n: number;
+    readonly at: number;
+    readonly path: string;
+    readonly error?: string;
+}
+/**
+ * 某个页面计数已经试过几次：初拍算一次，失败再试一次；计数一换就从头数。
+ */
+export interface RecordShotTries {
+    readonly n: number;
+    readonly tries: number;
+}
+/**
+ * 一张图最多试几次（初拍 + 一次重试）：失败如实报过就停，不每拍重试到底。
+ */
+export declare const RECORD_SHOT_TRIES = 2;
+/**
+ * 一份活着的录制约定：相位 + 谁的会话 + 哪个工作区 / 单元 + 页面 URL 与标题 + 要找的那一次写 +
+ * 落盘文件 + 三个时间戳，以及两份台账：按计数落图的 `shots`（`shotsSeen` 只记落成的那个计数）
+ * 与门铃的 `beats` / `beatMs`（命中几次、最近一次等了多久）。
+ */
+export interface RecordState {
+    readonly phase: RecordPhase;
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly url: string;
+    readonly title: string;
+    readonly action: string;
+    readonly expect: RecordExpect | null;
+    readonly captureFile: string;
+    readonly startedAt: number;
+    readonly t0: number | null;
+    readonly t1: number | null;
+    readonly shots: readonly RecordShot[];
+    readonly shotsSeen: number;
+    readonly shotTries: RecordShotTries | null;
+    readonly beats: number;
+    readonly beatMs: number;
+    readonly at: number;
+}
+/**
+ * 开一次录制要交的那几件：会话、工作区、单元、名字、页面 URL 与标题、动作名、期望、落盘文件，以及此刻时间。
+ */
+export interface RecordPact {
+    readonly sessionId: string;
+    readonly workspace: string;
+    readonly unit: string;
+    readonly name: string;
+    readonly url: string;
+    readonly title: string;
+    readonly action: string;
+    readonly expect: RecordExpect | null;
+    readonly captureFile: string;
+    readonly now: number;
+}
+/**
+ * 录制被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已在录 / 还没 arm / 不在录 / 还没录完。
+ */
+export type RecordRefusal = 'already-held' | 'held-by-other' | 'not-owner' | 'none' | 'already-recording' | 'not-armed' | 'not-recording' | 'not-finished';
+/**
+ * 一次录制动作的结果：成功带新状态，失败带拒绝码。
+ */
+export type RecordMove = {
+    readonly ok: true;
+    readonly state: RecordState;
+} | {
+    readonly ok: false;
+    readonly code: RecordRefusal;
+};
+/**
+ * 录制约定收得下的三个人话动作：看看进度 / 停手 / 结束并取回。
+ */
+export type RecordIntent = 'peek' | 'halt' | 'stop';
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
+export declare function parseRecordIntent(raw: unknown): RecordIntent | null;
+/**
+ * 录制约定的存取口（外壳持有一份）：相位随 `begin → started → finished` 推进，`release` 是收尾时放掉浏览器那一跳。
+ */
+export interface RecordStore {
+    readonly release?: ((state: RecordState) => Promise<{
+        readonly tab: boolean;
+        readonly capture: boolean;
+    }>) | undefined;
+    live(now: number): RecordState | null;
+    begin(pact: RecordPact): RecordMove;
+    started(sessionId: string, at: number, now: number): RecordMove;
+    finished(sessionId: string, at: number, now: number): RecordMove;
+    shotTaken(sessionId: string, shot: RecordShot, now: number): RecordMove;
+    shotFailed(sessionId: string, shot: RecordShot, now: number): RecordMove;
+    beat(sessionId: string, ms: number, now: number): RecordMove;
+    stop(sessionId: string, now: number): RecordMove;
+}
+/**
+ * 这一拍该不该落图：页面计数涨过 `shotsSeen` 才算；同一个计数已经试满就先放下，等他自己再按。
+ * @param state - 当前有效的那份约定。
+ * @param pageShots - 页面浮条上那个「已拍」计数。
+ * @returns 该落的那个计数；不该落给 `null`（没涨 / 试满了 / 不是个正经数）。
+ */
+export declare function shotDueOf(state: RecordState, pageShots: number): number | null;
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
+export declare function createRecordStore(): RecordStore;
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
+export declare function recordOwnerText(state: RecordState): string;