@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/lib/contract-envelope.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 结果信封：工具与 HTTP 返回的统一形状。
+ *
+ * 这一组的寿命最长、变更最慢——它是跨插件与跨工具的**约定**，改它等于改所有人的
+ * 返回形状。`Envelope<T,E>` 把载荷放在 `data` 下，`status` 由 `toolStatus()` 单点派生
+ * （有 warning 即 `partial`，无则 `success`；`failed` 没有 warning 形态）。
+ *
+ * `isRecord` 也在这里：它是构造与校验这些信封时用的通用对象守卫。
+ *
+ * 见 spec/contracts/envelope.json。
+ */
+export interface DataError {
+    code: string;
+    message: string;
+    /** A model/client-readable next action, not an opaque stack trace. */
+    nextAction?: string;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+}
+/** The statuses a call that returned usable data can carry. */
+export type SuccessStatus = 'success' | 'partial';
+/**
+ * Outcome of one tool call or HTTP response (spec/contracts/envelope.json).
+ *
+ * `partial` is not "many warnings": it means the call produced a usable result
+ * while something in it was skipped or downgraded, so a caller may proceed but
+ * must still read `warnings`. That is why the status is derived once
+ * ({@link toolStatus}) instead of being written by hand at every return site —
+ * three hand-written copies is how `error: null` went missing from the
+ * intent envelopes.
+ *
+ * `failed` is the only status a caller can trust without reading the payload:
+ * an envelope that carries it has `ok: false` and a non-null error.
+ */
+export type ToolStatus = SuccessStatus | 'failed';
+/**
+ * The unified response envelope: exactly the five keys the frozen contract
+ * names, and no others.
+ *
+ * It stays a discriminated union on `ok` for the same reason `DataResult` does:
+ * `if (!result.ok)` must hand the caller a non-null `error` without a second
+ * guard, which is how transport and tool code reads it. The union also pins the
+ * one status pairing that matters — `failed` only ever rides with `ok: false`.
+ *
+ * The error type is generic so a domain plugin can narrow it (for example
+ * `Envelope<T, KnowledgeError>` to keep `retryable` / `suggestion` visible)
+ * without forking the envelope itself.
+ */
+export type Envelope<T, E extends DataError = DataError> = {
+    ok: true;
+    status: SuccessStatus;
+    data: T;
+    warnings: string[];
+    error: null;
+} | {
+    ok: false;
+    status: 'failed';
+    data: T;
+    warnings: string[];
+    error: E;
+};
+/**
+ * The status rule, in one place: a call that produced warnings is `partial`,
+ * one that produced none is `success`. `failed` has no warning form — a failure
+ * carries an error, so it comes from {@link envelopeFailure}.
+ */
+export declare function toolStatus(warnings?: readonly string[]): SuccessStatus;
+/** A successful envelope; downgraded to `partial` when there are warnings. */
+export declare function envelopeSuccess<T, E extends DataError = DataError>(data: T, warnings?: string[]): Envelope<T, E>;
+/** A failed envelope. `data` still carries whatever partial payload exists. */
+export declare function envelopeFailure<T, E extends DataError = DataError>(data: T, error: E): Envelope<T, E>;
+/**
+ * 把一份载荷收成「JSON 装得下的样子」：丢掉值为 `undefined` 的键、数组空位补成
+ * `null`、非有限数（`NaN` / `±Infinity`）与 `-0` 归一，类实例（`Date`、自定义类）
+ * 变成它的可枚举自有属性。
+ *
+ * 为什么信封这一层要做：工具返回值会被原样写进会话日志，平台的
+ * `snapshotJsonValue` 只收 lossless JSON —— **对象里一个值为 `undefined` 的键就足以
+ * 让整次调用判为非法输出**（`INVALID_TOOL_OUTPUT`）。而 HTTP 那条路是
+ * `JSON.stringify`，本来就丢掉 `undefined`，所以这个错永远只在工具调用上现形，
+ * 而且现形成「明明成功却报错」。
+ *
+ * 实跑复现（0045）：`rebuild_knowledge` 只重建 wiki 时，报告里的
+ * `vectorQuantization` / `embeddingDimension` 是 `undefined` —— 卡片、`wiki_notes`、
+ * 图谱、FTS 全都已经落盘，调用方收到的是 `value is not lossless JSON`。
+ *
+ * 语义就是 `JSON.parse(JSON.stringify(v))`，只是不真的走一遍字符串。干净的值原样
+ * 返回（不复制），所以每次调用不会为一份没问题的载荷多付一次深拷贝。
+ */
+export declare function jsonSafe<T>(value: T): T;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/lib/contract-envelope.js

@@ -0,0 +1,106 @@
+/**
+ * 结果信封：工具与 HTTP 返回的统一形状。
+ *
+ * 这一组的寿命最长、变更最慢——它是跨插件与跨工具的**约定**，改它等于改所有人的
+ * 返回形状。`Envelope<T,E>` 把载荷放在 `data` 下，`status` 由 `toolStatus()` 单点派生
+ * （有 warning 即 `partial`，无则 `success`；`failed` 没有 warning 形态）。
+ *
+ * `isRecord` 也在这里：它是构造与校验这些信封时用的通用对象守卫。
+ *
+ * 见 spec/contracts/envelope.json。
+ */
+/* -------------------------------------------------------- result envelope */
+/**
+ * The status rule, in one place: a call that produced warnings is `partial`,
+ * one that produced none is `success`. `failed` has no warning form — a failure
+ * carries an error, so it comes from {@link envelopeFailure}.
+ */
+export function toolStatus(warnings = []) {
+    return warnings.length === 0 ? 'success' : 'partial';
+}
+/** A successful envelope; downgraded to `partial` when there are warnings. */
+export function envelopeSuccess(data, warnings = []) {
+    return { ok: true, status: toolStatus(warnings), data: jsonSafe(data), warnings, error: null };
+}
+/** A failed envelope. `data` still carries whatever partial payload exists. */
+export function envelopeFailure(data, error) {
+    return { ok: false, status: 'failed', data: jsonSafe(data), warnings: [], error: jsonSafe(error) };
+}
+/**
+ * 把一份载荷收成「JSON 装得下的样子」：丢掉值为 `undefined` 的键、数组空位补成
+ * `null`、非有限数（`NaN` / `±Infinity`）与 `-0` 归一，类实例（`Date`、自定义类）
+ * 变成它的可枚举自有属性。
+ *
+ * 为什么信封这一层要做：工具返回值会被原样写进会话日志，平台的
+ * `snapshotJsonValue` 只收 lossless JSON —— **对象里一个值为 `undefined` 的键就足以
+ * 让整次调用判为非法输出**（`INVALID_TOOL_OUTPUT`）。而 HTTP 那条路是
+ * `JSON.stringify`，本来就丢掉 `undefined`，所以这个错永远只在工具调用上现形，
+ * 而且现形成「明明成功却报错」。
+ *
+ * 实跑复现（0045）：`rebuild_knowledge` 只重建 wiki 时，报告里的
+ * `vectorQuantization` / `embeddingDimension` 是 `undefined` —— 卡片、`wiki_notes`、
+ * 图谱、FTS 全都已经落盘，调用方收到的是 `value is not lossless JSON`。
+ *
+ * 语义就是 `JSON.parse(JSON.stringify(v))`，只是不真的走一遍字符串。干净的值原样
+ * 返回（不复制），所以每次调用不会为一份没问题的载荷多付一次深拷贝。
+ */
+export function jsonSafe(value) {
+    return collapse(value);
+}
+function collapse(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    const kind = typeof value;
+    if (kind === 'number') {
+        const num = value;
+        if (!Number.isFinite(num))
+            return null;
+        return Object.is(num, -0) ? 0 : num;
+    }
+    // JSON 没有 BigInt 这个类型，`JSON.stringify` 遇到它会直接抛。这里取它的十进制写法：
+    // 一个能存下来的近似值，好过让整次调用失败。
+    if (kind === 'bigint')
+        return String(value);
+    // `undefined` / 函数 / symbol：在 JSON 里表示「这个键不存在」。
+    if (kind !== 'object')
+        return undefined;
+    const record = value;
+    const toJSON = record.toJSON;
+    if (typeof toJSON === 'function')
+        return collapse(toJSON.call(value));
+    if (Array.isArray(value)) {
+        // 逐下标而不是 `map`：`map` 会跳过空位，留下的空位仍是非法 JSON
+        // （`[1, , 3]` 序列化出来是 `[1,null,3]`，而 `snapshotJsonValue` 直接拒）。
+        let changed = Object.keys(value).length !== value.length;
+        const out = [];
+        for (let index = 0; index < value.length; index += 1) {
+            const item = value[index];
+            const next = collapse(item) ?? null;
+            if (next !== item)
+                changed = true;
+            out.push(next);
+        }
+        return changed ? out : value;
+    }
+    const proto = Object.getPrototypeOf(value);
+    // 类实例、带符号键或不可枚举自有属性的对象：`snapshotJsonValue` 都会拒。
+    // 判据用「自有属性名」而不是「可枚举键」就是为了看见后两者。
+    let changed = (proto !== Object.prototype && proto !== null)
+        || Object.getOwnPropertySymbols(value).length > 0
+        || Object.getOwnPropertyNames(value).length !== Object.keys(record).length;
+    const out = {};
+    for (const key of Object.keys(record)) {
+        const next = collapse(record[key]);
+        if (next === undefined) {
+            changed = true;
+            continue;
+        }
+        out[key] = next;
+        if (next !== record[key])
+            changed = true;
+    }
+    return changed ? out : value;
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/lib/contract-layout.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 磁盘布局：项目根在哪、工作簿与画布存哪、新建的文件叫什么名字。
+ *
+ * table 与 excalidraw 插件必须对同一个问题给出同一个答案。两边对「项目根」的算法不一致就会找不到文件。
+ *
+ * 文件名同理：「叫什么」是持久化契约的一部分 —— 落盘名就是 id，改一次规则等于把
+ * 已有文件变成孤儿；所以规则与目录名放在同一个子路径里，一起冻结。
+ *
+ * 见 spec/VERSION-MATRIX.md 的冻结契约表（`storages/` 是持久化路径）。
+ */
+/**
+ * The one directory name a plugin's project-local files live under.
+ *
+ * `data-table` and `data-excalidraw` keep their state beside
+ * the project it belongs to — `<project>/storages/<plugin>/…` — instead of in a
+ * single per-user store. That makes a project directory self-contained: copy it
+ * and the workbooks and drawings travel with it; delete it and
+ * nothing is left behind in the user's home. Each plugin supplies its own leaf
+ * name; this constant fixes only the segment they share, so the plugins cannot
+ * drift into separate layouts.
+ */
+export declare const STORAGES_DIRECTORY = "storages";
+/**
+ * What a caller knows about the project directory of one Session.
+ *
+ * All three fields are read structurally: the Session registry's header and the
+ * sandbox policy belong to the Host, and a plugin sees them as plain objects.
+ */
+export interface ProjectLocation {
+    /** `Session.header.cwd` — the Session's working directory. */
+    cwd?: unknown;
+    /** The sandbox policy's workspace root; DSH's own fallback. */
+    workspaceRoot?: unknown;
+    /**
+     * The caller's last resort, passed explicitly because there is no correct
+     * default here: a run with neither a Session nor a policy is a run whose
+     * process directory is the only honest answer, and only the caller has it.
+     */
+    fallback: string;
+}
+/**
+ * The project directory one Session's files belong to.
+ *
+ * The derivation is the Host's, not this package's: the Session header's `cwd`
+ * first, then the sandbox policy's workspace root (what DSH's own workspace-file
+ * service falls back to), then the caller's own directory. It lives here because
+ * three plugins now need the same answer, and "the project" quietly becoming
+ * three slightly different directories is exactly the failure this prevents —
+ * each caller supplies the two facts only it has.
+ *
+ * @param location - Session cwd, policy root, and the last-resort fallback.
+ * @returns an absolute directory that may not exist yet.
+ */
+export declare function projectRootOf(location: ProjectLocation): string;
+/**
+ * Whether a path could be a project directory.
+ *
+ * A filesystem root is not a project. DSH's local sandbox policy reports
+ * `workspaceRoot: "/"` whenever it has no better answer, and taking that literally puts
+ * `<root>/storages/...` at `/storages/...` — which fails with EACCES on macOS, and would be
+ * wrong even where it succeeded. Skipping it lets the caller's real fallback apply.
+ *
+ * @param value - Candidate path.
+ * @returns true when it is a non-empty path that is not a filesystem root.
+ */
+export declare function isProjectDirectory(value: unknown): value is string;
+/**
+ * How many characters of the meaning a new storage file name carries.
+ *
+ * 25 是**人读的长度**，不是文件系统的限制：名字出现在侧栏、文件树和工具回执里，
+ * 超过一屏半行的名字等于没有名字。上限以内按整字截断（不是按字节、也不是按 UTF-16
+ * 码元 —— 后者会把一个汉字或一个 emoji 劈成两半）。
+ */
+export declare const STORAGE_NAME_MAX_CHARS = 25;
+/** 名字里一个可用字符都没有时用的占位，例如 name 只给了 `！！！`。 */
+export declare const STORAGE_NAME_FALLBACK = "\u672A\u547D\u540D";
+/**
+ * `yyyymmdd`：某一刻的**本地**日期，用作新建存储文件名的前缀。
+ *
+ * 本地而不是 UTC：文件是给人看的，用户说「今天建的」就是他自己日历上的今天。
+ * 与知识插件的 `output/<YYYY-MM-DD>/` 按本地日分桶是同一条理由。
+ *
+ * @param at - 时刻，默认现在。
+ * @returns 8 位数字，例如 `20261002`。
+ */
+export declare function compactDate(at?: Date): string;
+/**
+ * 把一段任意文本压成安全的文件名片段：保留汉字、字母、数字、`_`、`-`、`.`，
+ * 其余（空格、标点、路径分隔符、表情）一律并成 `-`，并去掉首尾的 `-`。
+ *
+ * 这是**字符集**规则，不含日期和长度 —— 已存在的 id 也要经过它，而给老文件补日期或
+ * 截短名字会让它再也找不到；所有调用方必须接受同一批字符，否则同一个名字会无法读取。
+ *
+ * 路径分隔符在这里被消掉，所以片段接到目录后面不会跑出目录；`..` 只会变成一个普通
+ * 文件名的一部分。
+ *
+ * @param value - 任意文本，通常是显示名或调用方给的 id。
+ * @returns 安全片段，可能为空串（当输入没有任何可用字符时）。
+ */
+export declare function storageSegment(value: string): string;
+/**
+ * 新建存储文件叫什么名字：`yyyymmdd-中文名`，中文名（即日期前缀之后的整段）不超过
+ * {@link STORAGE_NAME_MAX_CHARS} 个字。
+ *
+ * 为什么要有统一的一个函数：table 的工作簿和画布文件都放在
+ * `<project>/storages/<plugin>/<名字>.<扩展名>`（工作簿 `.json`，画布 `.excalidraw`），落盘名
+ * 就是 id。过去它们各自生成 `_<ascii slug>`、`session-<uuid>`、`main` —— 打开 storages 目录
+ * 看不出哪个文件是什么，而中文显示名会被字符集规则整段换成 `-`（`销售汇总` 变成 `_wb`）。
+ * 所以**含义进名字**：用户看见的 `销售汇总` 就是文件名里的 `销售汇总`。
+ *
+ * 画布接入晚于这个函数：画布长期用固定的 `main.excalidraw` 和 `画布 N` 当新文件名，
+ * 所以这条规则对画布**没有生效**过。现在画布的新建路径（Agent 的 `excalidraw_create`、面板的
+ * 「新建画布」）也走它；`main.excalidraw` 保留为「省略名字时的默认地址」——地址不是新名字，
+ * 给它补日期等于让老文件找不到。
+ *
+ * 已经带 `yyyymmdd-` 前缀的输入保留自己的日期，不叠加第二个前缀（调用方按规则起好名
+ * 时不该被改写成「今天」）；其余输入补当天日期。
+ *
+ * 碰撞后缀（`-2`、`-3`）由调用方在同一目录里自己让路，它们不计入 25 字上限 —— 上限管
+ * 的是「含义有多长」，不是「目录里有几个重名」。
+ *
+ * @param meaning - 名字的含义，通常是显示名；也可以已经是 `yyyymmdd-名字`。
+ * @param options.at - 日期前缀用的时刻，默认现在。
+ * @param options.fallback - 含义为空时的替代名，默认 {@link STORAGE_NAME_FALLBACK}。
+ * @returns 形如 `20261002-销售汇总` 的文件名片段。
+ */
+export declare function storageNameOf(meaning: string, options?: {
+    readonly at?: Date;
+    readonly fallback?: string;
+}): string;

package/lib/contract-layout.js

@@ -0,0 +1,138 @@
+/**
+ * 磁盘布局：项目根在哪、工作簿与画布存哪、新建的文件叫什么名字。
+ *
+ * table 与 excalidraw 插件必须对同一个问题给出同一个答案。两边对「项目根」的算法不一致就会找不到文件。
+ *
+ * 文件名同理：「叫什么」是持久化契约的一部分 —— 落盘名就是 id，改一次规则等于把
+ * 已有文件变成孤儿；所以规则与目录名放在同一个子路径里，一起冻结。
+ *
+ * 见 spec/VERSION-MATRIX.md 的冻结契约表（`storages/` 是持久化路径）。
+ */
+/* ------------------------------------------------------ project storage */
+/**
+ * The one directory name a plugin's project-local files live under.
+ *
+ * `data-table` and `data-excalidraw` keep their state beside
+ * the project it belongs to — `<project>/storages/<plugin>/…` — instead of in a
+ * single per-user store. That makes a project directory self-contained: copy it
+ * and the workbooks and drawings travel with it; delete it and
+ * nothing is left behind in the user's home. Each plugin supplies its own leaf
+ * name; this constant fixes only the segment they share, so the plugins cannot
+ * drift into separate layouts.
+ */
+export const STORAGES_DIRECTORY = 'storages';
+/**
+ * The project directory one Session's files belong to.
+ *
+ * The derivation is the Host's, not this package's: the Session header's `cwd`
+ * first, then the sandbox policy's workspace root (what DSH's own workspace-file
+ * service falls back to), then the caller's own directory. It lives here because
+ * three plugins now need the same answer, and "the project" quietly becoming
+ * three slightly different directories is exactly the failure this prevents —
+ * each caller supplies the two facts only it has.
+ *
+ * @param location - Session cwd, policy root, and the last-resort fallback.
+ * @returns an absolute directory that may not exist yet.
+ */
+export function projectRootOf(location) {
+    if (isProjectDirectory(location.cwd))
+        return location.cwd;
+    if (isProjectDirectory(location.workspaceRoot))
+        return location.workspaceRoot;
+    return location.fallback;
+}
+/**
+ * Whether a path could be a project directory.
+ *
+ * A filesystem root is not a project. DSH's local sandbox policy reports
+ * `workspaceRoot: "/"` whenever it has no better answer, and taking that literally puts
+ * `<root>/storages/...` at `/storages/...` — which fails with EACCES on macOS, and would be
+ * wrong even where it succeeded. Skipping it lets the caller's real fallback apply.
+ *
+ * @param value - Candidate path.
+ * @returns true when it is a non-empty path that is not a filesystem root.
+ */
+export function isProjectDirectory(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    return value.replace(/[/\\]+$/, '').length > 0;
+}
+/* ------------------------------------------------ storage file names */
+/**
+ * How many characters of the meaning a new storage file name carries.
+ *
+ * 25 是**人读的长度**，不是文件系统的限制：名字出现在侧栏、文件树和工具回执里，
+ * 超过一屏半行的名字等于没有名字。上限以内按整字截断（不是按字节、也不是按 UTF-16
+ * 码元 —— 后者会把一个汉字或一个 emoji 劈成两半）。
+ */
+export const STORAGE_NAME_MAX_CHARS = 25;
+/** 名字里一个可用字符都没有时用的占位，例如 name 只给了 `！！！`。 */
+export const STORAGE_NAME_FALLBACK = '未命名';
+/**
+ * `yyyymmdd`：某一刻的**本地**日期，用作新建存储文件名的前缀。
+ *
+ * 本地而不是 UTC：文件是给人看的，用户说「今天建的」就是他自己日历上的今天。
+ * 与知识插件的 `output/<YYYY-MM-DD>/` 按本地日分桶是同一条理由。
+ *
+ * @param at - 时刻，默认现在。
+ * @returns 8 位数字，例如 `20261002`。
+ */
+export function compactDate(at = new Date()) {
+    const pad = (value) => `${value}`.padStart(2, '0');
+    return `${at.getFullYear()}${pad(at.getMonth() + 1)}${pad(at.getDate())}`;
+}
+/**
+ * 把一段任意文本压成安全的文件名片段：保留汉字、字母、数字、`_`、`-`、`.`，
+ * 其余（空格、标点、路径分隔符、表情）一律并成 `-`，并去掉首尾的 `-`。
+ *
+ * 这是**字符集**规则，不含日期和长度 —— 已存在的 id 也要经过它，而给老文件补日期或
+ * 截短名字会让它再也找不到；所有调用方必须接受同一批字符，否则同一个名字会无法读取。
+ *
+ * 路径分隔符在这里被消掉，所以片段接到目录后面不会跑出目录；`..` 只会变成一个普通
+ * 文件名的一部分。
+ *
+ * @param value - 任意文本，通常是显示名或调用方给的 id。
+ * @returns 安全片段，可能为空串（当输入没有任何可用字符时）。
+ */
+export function storageSegment(value) {
+    return value
+        .trim()
+        .replace(/[^\p{L}\p{N}_.-]+/gu, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * 新建存储文件叫什么名字：`yyyymmdd-中文名`，中文名（即日期前缀之后的整段）不超过
+ * {@link STORAGE_NAME_MAX_CHARS} 个字。
+ *
+ * 为什么要有统一的一个函数：table 的工作簿和画布文件都放在
+ * `<project>/storages/<plugin>/<名字>.<扩展名>`（工作簿 `.json`，画布 `.excalidraw`），落盘名
+ * 就是 id。过去它们各自生成 `_<ascii slug>`、`session-<uuid>`、`main` —— 打开 storages 目录
+ * 看不出哪个文件是什么，而中文显示名会被字符集规则整段换成 `-`（`销售汇总` 变成 `_wb`）。
+ * 所以**含义进名字**：用户看见的 `销售汇总` 就是文件名里的 `销售汇总`。
+ *
+ * 画布接入晚于这个函数：画布长期用固定的 `main.excalidraw` 和 `画布 N` 当新文件名，
+ * 所以这条规则对画布**没有生效**过。现在画布的新建路径（Agent 的 `excalidraw_create`、面板的
+ * 「新建画布」）也走它；`main.excalidraw` 保留为「省略名字时的默认地址」——地址不是新名字，
+ * 给它补日期等于让老文件找不到。
+ *
+ * 已经带 `yyyymmdd-` 前缀的输入保留自己的日期，不叠加第二个前缀（调用方按规则起好名
+ * 时不该被改写成「今天」）；其余输入补当天日期。
+ *
+ * 碰撞后缀（`-2`、`-3`）由调用方在同一目录里自己让路，它们不计入 25 字上限 —— 上限管
+ * 的是「含义有多长」，不是「目录里有几个重名」。
+ *
+ * @param meaning - 名字的含义，通常是显示名；也可以已经是 `yyyymmdd-名字`。
+ * @param options.at - 日期前缀用的时刻，默认现在。
+ * @param options.fallback - 含义为空时的替代名，默认 {@link STORAGE_NAME_FALLBACK}。
+ * @returns 形如 `20261002-销售汇总` 的文件名片段。
+ */
+export function storageNameOf(meaning, options = {}) {
+    const raw = meaning.trim();
+    const dated = /^(\d{8})-(.*)$/su.exec(raw);
+    const prefix = dated === null ? compactDate(options.at) : dated[1];
+    const segment = storageSegment(dated === null ? raw : dated[2]);
+    const fallback = options.fallback ?? STORAGE_NAME_FALLBACK;
+    // 截断之后再收一次尾：断在第 25 个字是 `-` 时别留一个 `20261002-销售汇总-`。
+    const cut = [...(segment.length === 0 ? fallback : segment)].slice(0, STORAGE_NAME_MAX_CHARS).join('').replace(/-+$/g, '');
+    return `${prefix}-${cut.length === 0 ? fallback : cut}`;
+}

package/lib/contract-refs.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 跨插件引用与血缘：一个插件指向另一个插件产出的东西时，用的就是这些形状。
+ *
+ * `SheetRef` 是 Sheet 单元格指向 table 的工作簿，`LineageContext` / `LineageRef` 是
+ *「这次写入源自哪次会话的哪个动作」。
+ *
+ * 它们必须共享：跨插件生成的引用要保持同一形状。
+ */
+export interface SheetRef {
+    workbookId: string;
+    sheetId: string;
+    sheetName: string;
+    range?: string;
+}
+/**
+ * Cross-plugin business lineage. These ids are deliberately opaque and do
+ * not encode user input. A task is the user's business objective, a subtask
+ * is one plan/workflow node, and a run is one execution attempt.
+ *
+ * All properties are optional so existing persisted records and user-originated
+ * browser mutations remain readable without a migration.
+ */
+export interface LineageContext {
+    sessionId?: string;
+    turnId?: string;
+    intentId?: string;
+    taskId?: string;
+    subtaskId?: string;
+    parentSubtaskId?: string;
+    runId?: string;
+    traceId?: string;
+    domain?: string;
+}
+/** A provenance edge from a durable artifact or knowledge record to a task. */
+export interface LineageRef extends LineageContext {
+    role?: 'created' | 'derived' | 'retrieved' | 'executed' | 'feedback' | 'triggered';
+    refType?: string;
+    refId?: string;
+}

package/lib/contract-refs.js

@@ -0,0 +1,9 @@
+/**
+ * 跨插件引用与血缘：一个插件指向另一个插件产出的东西时，用的就是这些形状。
+ *
+ * `SheetRef` 是 Sheet 单元格指向 table 的工作簿，`LineageContext` / `LineageRef` 是
+ *「这次写入源自哪次会话的哪个动作」。
+ *
+ * 它们必须共享：跨插件生成的引用要保持同一形状。
+ */
+export {};