@4399ywkf/editor 0.1.2 → 0.2.0

package/dist/doc-runtime.d.ts

@@ -0,0 +1,325 @@
+import { JSONContent, Editor } from '@tiptap/core';
+import { Node } from '@tiptap/pm/model';
+
+/**
+ * LiteXML —— 给 AI 看的文档表示。
+ *
+ * 设计原则（来自实测与业界先例）：
+ *  1. 比 ProseMirror JSON 省 token（Notion 换成 markdown、Tiptap 做 Shorthand，
+ *     理由都是这个）。实测 7 块中文文档：LiteXML 322 token / PM JSON minified 499
+ *     （1.55x）/ pretty 898（2.79x）。1.55x 是下限 —— 中文正文占比高时对 JSON 最有利，
+ *     嵌套列表和表格会把差距成倍拉大；
+ *  2. 每个可寻址块带稳定 id，AI 只用 id 定位，绝不用 position；
+ *  3. **有损但不丢失**：表达不了的节点降级成不透明占位符 `<node type="..."/>`，
+ *     而不是抛错；表达不了的属性靠写入侧 attrs 合并保住（见 mergeParsedNode）。
+ *
+ * 本模块是**纯数据变换**：进 ProseMirror JSON 出字符串，或者反过来。
+ * 不碰 Editor 实例、不碰 DOM（XML 解析器由调用方注入，同 docx/parse.ts 的做法），
+ * 所以可以在 Node 里直接跑往返测试。
+ */
+
+/**
+ * 节点类型 → 标签。不在表里的走 `<node type="..."/>` 兜底。
+ *
+ * 这张表镜像的是**本编辑器自己的 schema**（30 个节点类型）。它必须和
+ * components/tiptap-node/ 下的节点定义住在同一个包里 —— 跨仓之后每加一个节点
+ * 类型，序列化就静默降级成占位符，不报错、不丢数据、也不告诉你。
+ */
+declare const NODE_TAG: Record<string, string>;
+/** 叶子节点：自闭合，没有子内容。AI 不应往里写内容。 */
+declare const VOID_TAGS: ReadonlySet<string>;
+/** 只读节点：由扩展自动维护，AI 不许直接写。 */
+declare const READONLY_TAGS: ReadonlySet<string>;
+declare const MARK_TAG: Record<string, string>;
+/** 可被 formatText 施加/移除的标记。 */
+declare const FORMATTABLE: string[];
+type FormattableMark = "bold" | "italic" | "underline" | "strike" | "code" | "superscript" | "subscript";
+declare function nodeToXml(node: JSONContent, depth?: number): string;
+/** 把一整份 ProseMirror doc JSON 序列化成 LiteXML。 */
+declare function docToXml(doc: JSONContent): string;
+/**
+ * XML 解析器由调用方注入 —— 浏览器传原生 `DOMParser`，Node 传 `@xmldom/xmldom` 的。
+ * 同 `docx/parse.ts` 的做法，目的一样：让这层能在 Node 里跑测试。
+ * 省略时自动取 `globalThis.DOMParser`，所以浏览器侧零配置。
+ */
+interface LiteXmlParseOptions {
+    DOMParser?: {
+        new (): {
+            parseFromString(source: string, mimeType: string): Document;
+        };
+    };
+}
+declare function xmlElToPm(el: Element): JSONContent;
+/** 把一段 LiteXML 片段（可以是多个平级块）解析成 ProseMirror JSON 数组。 */
+declare function parseXmlFragment(xml: string, opts?: LiteXmlParseOptions): JSONContent[];
+/**
+ * LiteXML 是**有损投影**。直接用解析结果整块替换会把它表达不了的属性静默抹掉
+ * （= 「AI 改一个词顺手毁排版」）。所以 modify 一律以原节点 attrs 为底做合并，
+ * 只让 XML 里真的出现过的键覆盖。
+ *
+ * 已验证的用例：对带 `lang="typescript"` 的代码块用不带 lang 的 XML 做 modify，
+ * 内容改了、lang 保住。
+ */
+declare function mergeParsedNode(originalAttrs: Record<string, unknown>, parsed: JSONContent): JSONContent;
+
+/**
+ * doc-runtime 的操作层：一组 `(editor, args) => result` 的函数。
+ *
+ * 纪律：
+ *  - **寻址在执行的那一瞬间才解析**（每个函数自己现查 id → pos），所以没有
+ *    「写后索引失效」—— 调用方不需要倒序处理，也不需要每改一处就重读一遍。
+ *    这条同时写进了工具 description，因为模型带着 Google Docs / 腾讯文档那套
+ *    条件反射，不明说它会自作聪明。
+ *  - 这层**不碰 DOM、不做高亮**。要闪烁提示的话，看返回值里的 id 自己去做
+ *    （DocRuntime 就是这么干的）—— 操作层保持可测。
+ */
+
+interface NodeHit {
+    node: Node;
+    pos: number;
+}
+declare function findById(editor: Editor, id: string): NodeHit | null;
+type ModifyOperation = {
+    action: "insert";
+    afterId: string;
+    litexml: string;
+    beforeId?: never;
+    id?: never;
+} | {
+    action: "insert";
+    beforeId: string;
+    litexml: string;
+    afterId?: never;
+    id?: never;
+} | {
+    action: "remove";
+    id: string;
+    litexml?: never;
+    afterId?: never;
+    beforeId?: never;
+} | {
+    action: "modify";
+    litexml: string | string[];
+    id?: never;
+    afterId?: never;
+    beforeId?: never;
+};
+interface ModifyResultItem {
+    action: string;
+    success: boolean;
+    error?: string;
+    id?: string;
+    anchor?: string;
+    count?: number;
+    modifiedIds?: string[];
+}
+interface ModifyNodesResult {
+    results: ModifyResultItem[];
+    successCount: number;
+    totalCount: number;
+    /** 本批实际改动到的块 id，调用方可拿去做高亮。 */
+    touchedIds: string[];
+}
+declare function applyOperations(editor: Editor, operations: ModifyOperation[], parseOpts?: LiteXmlParseOptions): ModifyNodesResult;
+interface ReplaceTextArgs {
+    searchText: string;
+    newText: string;
+    /** 限定生效范围；省略则全文 */
+    nodeIds?: string[];
+    /** 默认 false，只替换第一处 */
+    replaceAll?: boolean;
+}
+interface ReplaceTextResult {
+    replacementCount: number;
+    modifiedNodeIds: string[];
+}
+declare function replaceText(editor: Editor, { searchText, newText, nodeIds, replaceAll }: ReplaceTextArgs): ReplaceTextResult;
+interface FormatTextArgs {
+    nodeId: string;
+    searchText: string;
+    marks: FormattableMark[];
+    /** true 则移除这些标记而不是施加，默认 false */
+    remove?: boolean;
+    /** 块内第几处匹配，从 1 开始，默认 1 */
+    occurrence?: number;
+}
+declare function formatText(editor: Editor, { nodeId, searchText, marks, remove, occurrence }: FormatTextArgs): {
+    nodeId: string;
+    marks: FormattableMark[];
+    removed: boolean;
+    matched: string;
+};
+type TableAction = "set_cells" | "insert_row_after" | "insert_row_before" | "insert_col_after" | "insert_col_before" | "delete_row" | "delete_col" | "toggle_header_row" | "merge_cells" | "split_cell";
+interface TableEditArgs {
+    tableId: string;
+    action: TableAction;
+    row?: number;
+    col?: number;
+    values?: {
+        row: number;
+        col: number;
+        text: string;
+    }[];
+}
+declare function tableEdit(editor: Editor, { tableId, action, row, col, values }: TableEditArgs): {
+    tableId: string;
+    updated: number;
+    action?: undefined;
+    ok?: undefined;
+} | {
+    tableId: string;
+    action: "insert_row_after" | "insert_row_before" | "insert_col_after" | "insert_col_before" | "delete_row" | "delete_col" | "toggle_header_row" | "merge_cells" | "split_cell";
+    ok: boolean;
+    updated?: undefined;
+};
+interface FindHit {
+    nodeId: string | null;
+    nodeType: string;
+    contextBefore: string;
+    match: string;
+    contextAfter: string;
+}
+declare function findTextInDoc(editor: Editor, query: string, limit?: number): {
+    hits: FindHit[];
+    total: number;
+};
+declare function getSelection(editor: Editor): {
+    selection: null;
+    note: string;
+} | {
+    selection: {
+        text: string;
+        blocks: {
+            id: string;
+            type: string;
+        }[];
+    };
+    note?: undefined;
+};
+/**
+ * 从**运行时 schema** 反射出来的能力清单，所以永远不会和实现漂移。
+ * 模型不确定某个结构能不能写、该用什么标签时先查它。
+ */
+declare function docSchema(editor: Editor): {
+    nodeTypes: string[];
+    markTypes: string[];
+    litexmlTags: Record<string, string>;
+    readonlyTags: string[];
+    idBearingTypes: string[];
+    note: string;
+};
+/** 按节点类型点数，用来和导入源做对账。 */
+declare function docStats(editor: Editor): {
+    nodes: Record<string, number>;
+    marks: Record<string, number>;
+    headings: Record<string, number>;
+    textLength: number;
+    topLevelBlocks: number;
+};
+
+type DocReadFormat = "xml" | "json" | "both";
+interface GetPageContentArgs {
+    /**
+     * 默认 xml。json 是 ProseMirror 原生结构（无损但费 token，约 1.5-2.8 倍），
+     * 只在怀疑 LiteXML 丢了信息时才用。
+     */
+    format?: DocReadFormat;
+}
+interface DocRuntimeOptions {
+    editor?: Editor | null;
+    /**
+     * 写操作后对改动到的块做视觉提示。浏览器里默认闪一下（`.ai-flash`），
+     * 传 `false` 关掉。Node / 测试环境里自动 no-op。
+     */
+    highlight?: ((id: string) => void) | false;
+    /** XML 解析器注入。浏览器里省略即可，会走全局 `DOMParser`。 */
+    DOMParser?: LiteXmlParseOptions["DOMParser"];
+}
+declare class DocRuntime {
+    private editor;
+    private readonly highlight;
+    private readonly parseOpts;
+    constructor(options?: DocRuntimeOptions);
+    /** 编辑器实例就绪 / 卸载时调用。配合 `<NotionEditor onEditorReady>` 用。 */
+    setEditor(editor: Editor | null): void;
+    isReady(): boolean;
+    private use;
+    private flash;
+    /** 读全文。要编辑之前必须先调它拿 id。 */
+    getPageContent({ format }?: GetPageContentArgs): {
+        blockCount: number;
+        xml?: string;
+        json?: unknown;
+    };
+    /** 运行时反射出的节点·标记·标签映射·哪些类型带 id。永不与实现漂移。 */
+    getSchema(): {
+        nodeTypes: string[];
+        markTypes: string[];
+        litexmlTags: Record<string, string>;
+        readonlyTags: string[];
+        idBearingTypes: string[];
+        note: string;
+    };
+    /** 按节点类型点数，用来和导入源做对账。 */
+    getStats(): {
+        nodes: Record<string, number>;
+        marks: Record<string, number>;
+        headings: Record<string, number>;
+        textLength: number;
+        topLevelBlocks: number;
+    };
+    /** 检索，返回可直接回填给写工具的 nodeId。 */
+    find(args: {
+        query: string;
+        limit?: number;
+    }): {
+        hits: FindHit[];
+        total: number;
+    };
+    /** 用户此刻的选区；无选区时显式声明「不要沿用历史」。 */
+    getSelection(): {
+        selection: null;
+        note: string;
+    } | {
+        selection: {
+            text: string;
+            blocks: {
+                id: string;
+                type: string;
+            }[];
+        };
+        note?: undefined;
+    };
+    /** 块内文本替换（细粒度改动首选）。 */
+    replaceText(args: ReplaceTextArgs): ReplaceTextResult;
+    /** 对某段文字加/去 bold·italic·underline·strike·code·sup·sub（改格式首选）。 */
+    formatText(args: FormatTextArgs): {
+        nodeId: string;
+        marks: FormattableMark[];
+        removed: boolean;
+        matched: string;
+    };
+    /** 结构化 insert / remove / modify，一次提交多个操作。 */
+    modifyNodes(args: {
+        operations: ModifyOperation[];
+    }): ModifyNodesResult;
+    /** 表格：增删行列、合并拆分、批量写值。 */
+    tableEdit(args: TableEditArgs): {
+        tableId: string;
+        updated: number;
+        action?: undefined;
+        ok?: undefined;
+    } | {
+        tableId: string;
+        action: "insert_row_after" | "insert_row_before" | "insert_col_after" | "insert_col_before" | "delete_row" | "delete_col" | "toggle_header_row" | "merge_cells" | "split_cell";
+        ok: boolean;
+        updated?: undefined;
+    };
+    /**
+     * 工具名 → 方法。给传输层（MCP 桥、agent executor）用的单一分发口，
+     * 这样加一个工具只需要改这里，不需要每个传输各写一遍 switch。
+     */
+    call(tool: string, args?: Record<string, unknown>): Promise<unknown>;
+}
+
+export { type DocReadFormat, DocRuntime, type DocRuntimeOptions, FORMATTABLE, type FindHit, type FormatTextArgs, type FormattableMark, type GetPageContentArgs, type LiteXmlParseOptions, MARK_TAG, type ModifyNodesResult, type ModifyOperation, type ModifyResultItem, NODE_TAG, type NodeHit, READONLY_TAGS, type ReplaceTextArgs, type ReplaceTextResult, type TableAction, type TableEditArgs, VOID_TAGS, applyOperations, docSchema, docStats, docToXml, findById, findTextInDoc, formatText, getSelection, mergeParsedNode, nodeToXml, parseXmlFragment, replaceText, tableEdit, xmlElToPm };