@ptengine/inline-editor 0.0.0-stage → 0.1.1

package/dist/kernel/ai/aiInlineApply.d.ts

@@ -0,0 +1,330 @@
+/**
+ * AI 提出的 inline 改动 → 落到画布上。
+ *
+ * ## 这是三道闸的第三道
+ *
+ * | 闸 | 在哪 | 拦什么 |
+ * |---|---|---|
+ * | ① 生成端 | mastra `agents/experience-inline/schema.ts` 的 zod | 形状、`<`、`{}`/`javascript:`、CSS 属性名形状、条数 |
+ * | ② 装配端 | backend 的 inline 白名单（53/54/55/56） | 存库时的类型准入 |
+ * | ③ 编辑器 | **本文件** | 白名单、形状、作用域、selector 是否真的命中、内容安全 |
+ *
+ * 第三道不是多余的：前两道都在服务端，而**只有这里知道客户页此刻长什么样**
+ * （selector 命中几个元素要发 `resolveSelector` 才知道），也只有这里在真的往用户的
+ * 页面上写东西。
+ *
+ * ## 与现役 engage-editor 逐字对齐
+ *
+ * 映射语义抄自 `engage-editor/src/editor/services/aiInlineApply.service.js`：
+ *
+ *  - `EDIT_TEXT`     → 一条 `elementContent`，`mode: 'replace'` + **`isTextChange: true`**
+ *    （走「换 innerHTML、外壳保留」；漏掉这个字段会把元素本身换掉）
+ *  - `CHANGE_STYLE`  → **每个 CSS 属性一条** `elementStyle`
+ *
+ * 另外三个是本路径（编辑器里的对话）特有的，现役那份没有：
+ *
+ *  - `INSERT_ELEMENT` → `insertElement()`，即 `elementContent` + `mode: insert/append/before/after`。
+ *    content 是 **HTML** —— 全项目唯一一处真要审标记的地方，见 `insertHtmlGate.ts`
+ *  - `MOVE_ELEMENT`   → `elementMove`，target **只允许选中元素的祖先**（理由见 scope 注释）
+ *  - `DELETE_ELEMENT` → `deleteElement()`，即 `display: none`（**不是真删**，与工具条一致）
+ *  - `CHANGE_IMAGE`   → `replaceImage()` 的 img-src / background 两分支（**不走 insert**：
+ *    AI 只换图不插图），`alt` 有值时再追加一条 `setImageAlt()`
+ *  - `SET_LINK`       → `setClickAction()` + `buildActionObject({type:'link'})`，与「点击动作」
+ *    弹框里选 link 产出的对象逐字段同形
+ *
+ * ⚠️ 后五个**直接复用 `useChangeList` 里工具条那几个函数**（`insertElement` / `deleteElement` /
+ * `replaceImage` / `setImageAlt` / `setClickAction`），不自己拼 input：AI 与用户手工操作必须
+ * 产出同一种 change，否则同一个改动两条路存出来的数据不一样。
+ *
+ * ## 换图 / 改跳转多一道「来源闸」
+ *
+ * 前五个 op 的内容是模型自己写的文字与样式，落点全在客户页内部；这两个不一样 ——
+ * 一个 `src` / `url` 就是一条**对外请求面**，写进去等于让客户页去拉一个第三方地址
+ * （换图还会被真实用户加载，改跳转会把流量送走）。所以它们的地址必须**来源可指认**：
+ * 图片 origin 在宿主给的白名单里（上传域 / 页面自身），链接与页面同源或用户逐字给过。
+ * 模型凭记忆敲一个域名出来，这里必须拦下。
+ *
+ * ⚠️ 两个编辑器必须产出同样的 change，否则同一个 AI 建议在两边存出来的数据不一样，
+ * 而这种偏差要到发布后看线上效果才会发现。错误码也照抄（`INVALID_TEXT_CONTENT` 等），
+ * 好让两边的日志能对照着看。
+ *
+ * ## 刻意不做的事
+ *
+ * 不自己构造 `InlineChange`，而是产出 `*Input` 交给 `useChangeList` 的 `addStyle` /
+ * `addContent` —— 那条路径带着覆盖去重（DEC-21）、「先应用成功再入列」的顺序、以及
+ * 撤销闭包的记账。绕过它自己拼 change 等于把这些全丢掉。
+ */
+import type { ContentChangeInput, MoveChangeInput, StyleChangeInput } from '../changelist/builders.js';
+import type { AttributeChangeInput, ActionChangeInput } from '../changelist/builders.js';
+import type { ElementCapabilities, ViewportRect } from '@ptengine/inline-core/protocol';
+import { type ApplyCheck } from './postApplyCheck.js';
+/**
+ * 允许 AI 产出的操作。与 mastra `EDITOR_INLINE_OPS` 逐字一致。
+ *
+ * ⚠️ 比 Harness 那条批量流的 `INLINE_SAFE_OPS`（只有前两个）**宽**：那边是无人值守地
+ * 批量生成，这边是用户选中了一个元素、在编辑器里看着结果、每条都能单独撤销。
+ * 两个词表**刻意分开**，别为了「统一」把 Harness 那边一起放宽。
+ *
+ * ⚠️ **顺序与拼写都要与 mastra 那份对齐**（`tools/inline-edit/schema.ts`）：这边多一个，
+ * agent 给的那条会被 `NOT_IN_WHITELIST` 拒掉；那边多一个，agent 永远不会调它。
+ * 两边都不报错，只是改动永远不落地。
+ */
+export declare const AI_SAFE_OPS: readonly ["EDIT_TEXT", "CHANGE_STYLE", "INSERT_ELEMENT", "MOVE_ELEMENT", "DELETE_ELEMENT", "CHANGE_IMAGE", "SET_LINK", "EDIT_HTML"];
+/** `INSERT_ELEMENT` 的位置。**不含 `replace`** —— 那会把目标元素整个换掉，不是「插入」。 */
+export declare const AI_INSERT_MODES: readonly ["insert", "append", "before", "after"];
+/** `MOVE_ELEMENT` 的位置。与 content 那套词表不同（同名 before/after 映射到不同数值）。 */
+export declare const AI_MOVE_MODES: readonly ["top", "bottom", "before", "after"];
+export type AiSafeOp = (typeof AI_SAFE_OPS)[number];
+/** 线上形状 —— 与 mastra `inlineChangeSchema` 一致（`rationale` 只用于展示）。 */
+export interface AiWireChange {
+    abTestType: string;
+    selector: string;
+    /** EDIT_TEXT: 纯文本；CHANGE_STYLE: CSS 声明；INSERT_ELEMENT: HTML。MOVE/DELETE 不用。 */
+    content?: string;
+    /** INSERT_ELEMENT / MOVE_ELEMENT 的位置（两套词表不同，见上）。 */
+    mode?: string;
+    /** MOVE_ELEMENT 的目标 —— 只允许选中元素的祖先之一。 */
+    targetSelector?: string;
+    /** CHANGE_IMAGE 的新图地址。必须过 host 白名单闸（见 `allowedImageOrigins`）。 */
+    src?: string;
+    /** CHANGE_IMAGE 的新 alt。有值时**额外**落一条 `changeElementAttribute alt`。 */
+    alt?: string;
+    /** SET_LINK 的跳转地址。必须过来源闸（同源，或用户逐字给过）。 */
+    url?: string;
+    /** SET_LINK 是否新标签页打开。缺省 false。 */
+    newTab?: boolean;
+    rationale?: {
+        candidateSelector?: string;
+        briefPoint?: string;
+        summary?: string;
+    };
+}
+export type AiRejectReason = 'NOT_IN_WHITELIST' | 'INVALID_SHAPE' | 'OUT_OF_SCOPE' | 'ELEMENTS_NOT_FOUND'
+/** content / summary 里有替换字符 U+FFFD（模型吐坏的字）：这一条不落地，让它只重发这一条。 */
+ | 'GARBLED_TEXT'
+/** 探测 selector 时通道 / 会话出错（不是「找不到」）：该重试，`detail` 带原文。 */
+ | 'RESOLVE_FAILED' | 'AMBIGUOUS_SELECTOR' | 'INVALID_TEXT_CONTENT' | 'INVALID_STYLE_CONTENT'
+/** 新增元素那段 HTML 没过闸（标签/属性/取值/体量），detail 里是具体原因。 */
+ | 'INVALID_HTML_CONTENT'
+/** mode 不在该 op 的词表里（两套词表容易串）。 */
+ | 'INVALID_MODE'
+/** 移动的目标不是选中元素的祖先，或它在页面上不唯一。 */
+ | 'INVALID_MOVE_TARGET' | 'APPLY_FAILED'
+/** 换图的 `src` 不是 http(s)，或它的 origin 不在宿主给的白名单里（模型凭记忆编的域名）。 */
+ | 'UNSAFE_IMAGE_SRC'
+/**
+ * `EDIT_TEXT` 的目标是个容器（自己没有直接文本、却有子元素）：换 innerHTML 会把里面的图片、按钮
+ * 一起换成一个字符串。2026-09-30 方案卡对 `div.pf-31_>div` 写 EDIT_TEXT 就是这种 —— 正确的落点
+ * 是它里面那个文字叶子（货架里有）。能力位拿不到（老扩展）时不判。
+ */
+ | 'TEXT_TARGET_IS_CONTAINER'
+/** `insert` / `append` 进一个装不下孩子的元素（`<img>`、void 标签）：扩展会静默插进去、页面上什么都不出现。 */
+ | 'INSERT_TARGET_NO_CHILDREN'
+/** `before` / `after` 在一个不能有兄弟的元素旁（`<td>` 这类）：落点不成立。 */
+ | 'INSERT_NO_SIBLING'
+/** 目标既不是 `<img>` 也没有背景图 —— 换图无处可落（AI 不走「插入一张新图」那条分支）。 */
+ | 'IMAGE_TARGET_UNSUPPORTED'
+/** 跳转地址不是 http(s)，或既不同源也不是用户逐字给过的那个 URL。 */
+ | 'UNSAFE_LINK_URL'
+/** 目标不可点（`capabilities.canEditLink` 为假）：配上去 SDK 也不会执行。 */
+ | 'LINK_TARGET_UNSUPPORTED'
+/**
+ * agent 报的版本名在宿主那边**查无此版**（名字对不上、那一版已被删）。
+ *
+ * ⚠️ **本文件永远不会产出它** —— 包只认 versionId，名字到 id 的映射是宿主做的，
+ * 只有宿主知道有哪些版本。放进同一个词表是因为它回答的是同一个问题：
+ * 「这条为什么没落地」，卡片上要与其它原因并排展示。
+ */
+ | 'VERSION_NOT_FOUND'
+/**
+ * 这一批指名了另一个版本，但切过去失败了 —— **不是**这一层产出的，由 `InlineEditor`
+ * 在切换失败时整批填进来（停留在当前版本，一条都不应用：半批落在错误版本上比不落更糟）。
+ */
+ | 'VERSION_SWITCH_FAILED'
+/**
+ * 要撤销的那一批不属于当前版本（id 映射后不在当前清单里）—— 同样由 `InlineEditor`
+ * 产出，宿主据此把卡片上的「撤销这一批」禁掉，而不是让用户点了什么都没发生。
+ */
+ | 'VERSION_NOT_ACTIVE'
+/**
+ * 编辑器已关 / 画布会话失效 —— **不是**这一层产出的，由宿主在拿不到 apply 入口时
+ * 填进来。放进同一个词表是因为它回答的是同一个问题：「这条为什么没落地」。
+ */
+ | 'EDITOR_CLOSED';
+export interface AiApplyReject {
+    index: number;
+    selector: string;
+    reason: AiRejectReason;
+    /** `APPLY_FAILED` 时是画布命令的错误码/消息。 */
+    detail?: string;
+}
+export interface AiAppliedChange {
+    index: number;
+    selector: string;
+    op: AiSafeOp;
+    /** 一句人话（来自 `rationale.summary`），给卡片展示。 */
+    summary?: string;
+    /** 落进清单的 changeId —— 卡片靠它「撤销这一批」，不能用 revertAll（那会连用户手改的一起撤）。 */
+    changeIds: string[];
+    /** 这条改动插入的新元素 selector（INSERT 的根 / EDIT_HTML 的新根）。没有就没这个键。 */
+    insertedSelectors?: string[];
+    /** 几何自检结果（宿主能量几何时才有，见 `AiApplyDeps.resolve`）。 */
+    check?: ApplyCheck;
+}
+export interface AiApplyOutcome {
+    applied: AiAppliedChange[];
+    rejected: AiApplyReject[];
+}
+/** `'color: red; font-weight: 700'` → 逐条声明。非法声明直接丢掉（不是整条拒绝）。 */
+export declare function parseStyleDeclarations(content: string): Array<{
+    property: string;
+    value: string;
+}>;
+/**
+ * **授权票** —— 发消息那一刻交给 agent 的那份作用域（`<page-element>` 块里写着的
+ * 根 selector + 货架），由宿主随这一批改动一起交回来。
+ *
+ * ⚠️ 为什么需要它（真机 2026-09-22，vivaia 首屏换图）：`<page-element>` 是**发消息那一刻**
+ * 的快照，而 `scope` 是**落地那一刻**的实时选中。一轮 agent 要 60-120 秒（光生图就 25 秒），
+ * 这中间选中只要没了（画布里点一下、切一次设备都会重建会话），作用域就退成整页 ——
+ * 于是 agent 逐字抄我们给它的 selector 也会被判 `OUT_OF_SCOPE`，而两端都不报错，
+ * 回执读起来像「AI 改不了这个页面」。
+ *
+ * 判的口径没变，仍然是**「我们给过它什么」**：票里的 selector 全是我们自己采集、自己发出去的，
+ * 落地前该做的解析、唯一性校验一条没少。它只是让这份授权活到这一轮结束，而不是活到
+ * 用户下一次点击为止。
+ *
+ * 货架是**数组不是取值函数**（与 `scope.descendants` 刻意不同）：票就是一份快照，
+ * 它要的正是「当时那一份」，取值函数反而会取到现在这一份。
+ */
+export interface AiScopeGrant {
+    /** 票的根 —— `<page-element>` 里那行 `selector:`。 */
+    selector: string;
+    /** 票里的货架 —— 块里逐行列出、agent 唯一能逐字抄的那些。 */
+    descendants: string[];
+    /** 根的祖先链（不含根自己）。放行的改动按它算 `ancestors`，落盘收敛要用。 */
+    ancestors: string[];
+}
+export interface AiApplyDeps {
+    /**
+     * 允许被改的元素 —— 就是**用户提问时选中的那一个**。
+     *
+     * ⚠️ 这道闸不能省。agent 拿到的 selector 是我们给它的，但它完全可能自己编一个
+     * （`body > div:nth-of-type(3)`）。不校验的话，一句「把这个按钮改成绿色」可能改掉
+     * 整页所有按钮，**而且没有任何报错** —— 用户只会看到页面花了。
+     */
+    scope: {
+        selector: string;
+        /**
+         * 作用域根的 identifier。
+         *
+         * ⚠️ **不再进 change** —— 每条 change 的 `identifier` 一律用它自己的 selector
+         * （见 `base` 那段注释：与工具条产出同形）。保留这个字段是因为调用方仍用它自述
+         * 「这个作用域是谁」，而且它属于已发布的签名。
+         */
+        identifier: string;
+        /**
+         * 被授权的后代 selector（货架）—— **取值函数，不是数组**。
+         *
+         * 作用域 = 「选中元素本身」∪ 这一批。它是授权清单，不是参考资料：
+         * agent 只能逐字抄，不能自己拼；拼错的 selector 改错元素不报错。
+         *
+         * ⚠️ **为什么是函数**：货架是异步拉来的（`getDomTree`），而 apply 入口在选中变化
+         * 那一刻就注册好了。传数组的话闭包里存的是注册那一瞬间的快照 —— 那时货架还是空的，
+         * 于是 agent 明明按货架给了子元素 selector，却全被判 `OUT_OF_SCOPE`（真机踩过）。
+         * 改成函数让**调用时才取**，这类错就结构上不可能再犯。
+         *
+         * 省略 / 返回空 = 退回「只能改选中元素本身」。
+         */
+        descendants?: () => string[];
+        /**
+         * 选中元素的祖先 selector（由近及远或反序都行，只做集合判断）。
+         *
+         * `MOVE_ELEMENT` 的 target **只允许**取自这里。理由：agent 手上只有选中元素与它的
+         * 祖先链，兄弟元素的 selector 它没有 —— 让它自由填 target 就等于让它编一个，
+         * 而移动到一个编出来的位置**没有任何报错**，用户只会看到元素跑到了奇怪的地方。
+         *
+         * 「移到这个 section 的开头 / 移到这个 div 之前」用祖先 + mode 就能表达，够用。
+         */
+        ancestors: string[];
+        /**
+         * 货架里某一项的祖先链（由近及远，含作用域根自己）。**整页作用域专用**。
+         *
+         * 元素作用域不传：那时 `ancestors` 就是选中元素的祖先链，而作用域里的后代都在它
+         * 底下，同一条链够用。整页作用域不一样 —— 根是 `body`，它的 `ancestors` 是空数组，
+         * 拿它去判 `MOVE_ELEMENT` 的 target 会把**所有**移动判成非法（body 没有祖先）。
+         * 这个函数让那道闸改为对着「被移动的那个元素」的祖先链判，规则本身没变。
+         *
+         * 返回 `undefined`（不认识这个 selector）时退回 `ancestors` —— 与今天完全一致。
+         */
+        ancestorsOf?: (selector: string) => string[] | undefined;
+        /**
+         * 发消息那一刻交给 agent 的那份作用域（见 `AiScopeGrant`）。
+         *
+         * 与上面这份是**并集**，不是替代：实时选中还在时它一条都不多放；选中在这一轮里
+         * 丢了（或换了）时，它是唯一还记得「我们当时授权了什么」的东西。
+         */
+        grant?: AiScopeGrant;
+    };
+    /**
+     * 问 `selector` 在客户页上命中几个（跨域，必须走 agent 命令）。
+     *
+     * `viewportRect` 可选：给了矩形就表示宿主**能量几何**，落地后会跑一次几何自检
+     * （`postApplyCheck`）——改前的矩形就是这次探活顺带拿到的那份。不给 / null = 不检查。
+     */
+    resolve: (selector: string) => Promise<{
+        matched: boolean;
+        matchCount: number;
+        viewportRect?: ViewportRect | null;
+    }>;
+    /**
+     * 这条 changeId 插入了哪些新元素（扩展 `applyChange` 回报的 `insertedSelectors`，
+     * 改动清单记在内存里）。几何自检要量它们；宿主也要把它们并进授权范围，模型下一轮才改得动。
+     */
+    insertedSelectorsOf?: (changeId: string) => string[];
+    /** 落地后、量之前等一会（transition / 图片加载）。不给 = 不等。 */
+    settle?: () => Promise<void>;
+    /** 当前画布视口宽（判 OVERFLOW_X 用）。 */
+    viewportWidth?: () => number | undefined;
+    addStyle: (input: StyleChangeInput) => Promise<string>;
+    addContent: (input: ContentChangeInput) => Promise<string>;
+    addMove: (input: MoveChangeInput) => Promise<string>;
+    /** `CHANGE_IMAGE` 的 img-src 分支与 alt 用。 */
+    addAttribute: (input: AttributeChangeInput) => Promise<string>;
+    /** `SET_LINK` 用（`changeElementAction`）。 */
+    addAction: (input: ActionChangeInput) => Promise<string>;
+    /**
+     * 目标元素的能力位 —— `CHANGE_IMAGE` 要靠它分 img-src / background 两支，
+     * `SET_LINK` 要靠 `canEditLink` 判目标可不可点。
+     *
+     * ⚠️ **必须按 selector 现问**，不能复用选中态里那份：作用域允许改**货架里的后代**，
+     * 而后代的能力位与选中元素完全不同（选中的是 section，要换的图在里面的 `<img>` 上）。
+     * 拿选中元素的能力位去判分支，会对着一个 div 产出 `src` 属性 —— 属性确实设上了，
+     * div 不吃 src，表现是「AI 说换好了、图没变」。
+     *
+     * 省略 / 抛错 / 返回 null = 判不出目标类型，这两个 op 一律拒（不硬猜）。
+     */
+    getCapabilities?: (selector: string) => Promise<ElementCapabilities | null>;
+    /**
+     * 允许出现在 `src` 里的 origin 白名单（宿主注入：图片上传域 + 客户页自身的 origin）。
+     *
+     * 白名单而不是「只要是 http(s) 就行」：模型完全可能凭记忆敲一个域名出来，
+     * 而那个 `src` 会被**每一个真实访客**加载 —— 等于我们替客户往他的页面上挂了一个
+     * 第三方请求（可跟踪、可换内容、可失效）。空数组 = 全拒（fail closed）。
+     */
+    allowedImageOrigins: string[];
+    /**
+     * 本会话编辑器在这个页面上**读到过**的图片地址（完整 URL，整串相等才放行）。
+     * origin 白名单之外的第二条路：Shopify 这类站的图在 `cdn.shopify.com`，不在客户页 origin 下
+     * （见 `imageSource.ts`）。换图、整块重写、插入三处共用。缺省 = 这一路不放行。
+     */
+    allowedImageUrls?: string[];
+    /**
+     * 用户在对话里**逐字给过**的跳转地址。同源之外只认这一张表，且是**整串逐字相等**
+     * （不是 origin 相等）：外站地址是把客户的流量送走，得由用户自己说出来才算数。
+     */
+    allowedLinkUrls: string[];
+    /** 客户页自身的 origin —— 同源跳转直接放行（站内链接是最常见的正当用法）。 */
+    pageOrigin: string;
+}
+export declare function applyAiChanges(changes: AiWireChange[], deps: AiApplyDeps): Promise<AiApplyOutcome>;