企业官网建设流程全解析

老读者应该知道，我折腾前端组件化有些年头了。前阵子有个朋友找我，说他们的业务系统里有几十个表单，天天有客服在那手动复制粘贴用户信息，想接 AI 自动填充，又不想把现有页面推倒重来。这需求太典型了——传统表单接 AI，最怕三件事：侵入性太强、耦合太重、部署太麻烦。我第一反应就是 Web Component 那套原生方案：自定义一个标签，往里一嵌，完事。这篇就手把手拆一下，怎么用 Web Component 封装一个通用的 AI 表单填充 SDK，附上源码思路和踩坑记录。

这篇文章适合这几类人看：想把 AI 能力快速接到老表单上的前端工程师、想给团队沉淀通用能力的前端负责人、以及正在调研“能不能不改造现有页面上 AI”的架构师。不需要你精通 Web Component，但最好有点原生 JS 基础。我会从“为什么选这个方案”一路讲到“核心源码怎么拆”“实际效果怎么落地”，最后把常见坑一次性摊开。

1. 为什么偏要用 Web Component 来做这件事

先回答一个灵魂拷问：AI 表单填充又不是没人做过，后端接口返回数据、前端 JS 一把梭也能填充，为什么非要封装成 Web Component 形式的 SDK？

1.1 传统方案的三个硬伤

先说最常见的方案 A：直接写一段全局脚本，页面加载后遍历表单，调用 AI 接口，拿到结果往 input 里 set value。逻辑很简单，但它有三宗罪。第一，全局脚本不是模块化的，你在这个页面改了字段逻辑，那个页面不知道；第二，它和页面生命周期绑得太死，页面一改结构脚本就容易挂；第三，AI 接口的 prompt 构造、错误处理、重试逻辑全都混在一起，后期加需求就是改 bug 现场。

方案 B 是 iframe 嵌入。有些团队会做一个独立的 AI 填充工作台，用 iframe 嵌到表单旁边。好处是隔离得彻底，但坏处也很明显：iframe 加载成本高、通信靠 postMessage 容易漏消息、样式和布局很难自适应，而且很多企业系统有 CSP 限制，iframe 直接打不开。

方案 C 是框架组件，比如用 React/Vue 封装。这在新建项目里没问题，可一旦遇到老系统——jQuery 页面、后端直出的模板、甚至混合了多框架的应用——组件库根本塞不进去。你要在 React 项目里塞一个 Vue 组件，那是给自己找罪受。

1.2 Web Component 恰好补上了这些短板

Web Component 是浏览器原生标准，由三个技术拼成：Custom Elements 自定义标签、Shadow DOM 隔离样式、template 模板复用。它最大的特点是“技术栈无关”——你封装好的组件就是一个普通标签，任何页面里都能用，不管底下是 React、Vue、jQuery 还是原生 JS。

它本身就是 SDK 的理想形态：用<ai-form-fill>一个标签代表整个填充能力，开发者只需要在页面上写一句<ai-form-fill endpoint="xxx" api-key="xxx"></ai-form-fill>，再调一个 fill() 方法，就完成集成了。这种心智负担远小于读文档、写初始化代码、手动管理事件监听。

而且 AI 表单填充这个场景天然适合“局部增强”。它不是要重写整个表单，而是在现有表单上叠加一层智能能力。Web Component 的 Shadow DOM 能把自己内部的结构和样式隔离起来，不污染原表单；同时通过自定义事件对外通信，比全局事件总线清晰得多。下面这个表格可以更直观地看对比：

1.3 为什么 AI 填充特别适合“开口子”

再深入想一层：AI 填充不是简单地把接口数据铺到表单上，它需要“理解表单”。表单里哪个字段是姓名、哪个是地址、哪个是身份证号，这些肉眼能看出来的东西，程序却需要靠 name、label、placeholder 反推。这意味着填充逻辑本身就需要一套独立的上下文感知机制。

这段机制如果写在业务页面里，每个页面都要复制一遍；如果抽成独立 SDK，就能沉淀成一个“表单理解中间层”。SDK 同时暴露一个干净的接口给页面——传页面上的表单节点，它就负责找字段、构造上下文、请求 AI、回填结果。这就是服务化思想：把脏活累活收进内部，对外只给一个动作。

所以从架构角度，Web Component 是这类“局部智能增强型 SDK”的最优解之一：既是稳定的容器，又保持页面的绝对主导权。

2. 动手前先理清：Web Component 的四个关键点

你如果没系统用过 Web Component，我建议直接看这一节。这四件事 90% 的源码思路都建立在这上面。

2.1 Custom Elements：你怎么定义一个新标签

Custom Elements 的核心是customElements.define()。你用class extends HTMLElement定义一个类，里面实现生命周期回调，然后注册到浏览器里，就能在任何 HTML 里使用这个标签。

生命周期里有几个关键函数：

• connectedCallback：组件被插入文档时触发，适合做初始化、解析属性、绑定事件。
• disconnectedCallback：组件被移除时触发，适合清理解绑定时器、取消请求。
• attributeChangedCallback：observedAttributes里列出的属性发生变化时触发，适合响应式更新。
• adoptedCallback：组件被移动到新文档时触发，实际中较少用到。

对 AI 填充 SDK 来说，connectedCallback是核心——这里要把表单上下文扫描一遍，方便后续 fill() 调用时快速匹配合适的字段。disconnectedCallback里要 AbortController 掉进行中的 AI 请求，防止页面都关闭了请求还在跑。

外部不需要知道你的类名，只需要知道标签名。这就像你在 HTML 里新发明了一个元素，但它在所有现代浏览器里都合法。

2.2 Shadow DOM：样式隔离与事件穿透的秘密

Shadow DOM 给组件提供了一片“封闭的 DOM 树开关”。这棵树里的样式外面看不到，外面的样式也钻不进来。因此你做填充反馈动画、状态提示条时，怎么改样式都不用害怕和外层页面冲突。

“事件穿透”是你最容易踩的坑之一。Shadow DOM 里触发的自定义事件，默认是出得去的，因为事件的 composed 属性默认为 true 时能跨过 Shadow DOM 边界，但前提是你要给事件设置composed: true。如果忘了这个，外层页面监听这个事件就永远收不到。我第一次写的时候就被坑过，事件明明触发了，外部页面怎么都监听不到，查了半天才发现是composed的问题。

此外，Shadow DOM 里的 input、button 等控件参与外层表单提交的方式也有讲究。注意：Shadow DOM 内的表单控件默认不属于外层的<form>，你如果只是填充而不走原生表单提交，问题不大；但如果你希望填充后表单校验自动触发，就得往原页面字段上派发input和change事件，想办法让原表单感知到变化。

2.3 template 和 slot：内部的模板骨架

<template>标签存放组件的内部骨架，浏览器不会渲染它，只有在被 clone 到 Shadow DOM 里时才生效。<slot>则是插槽，允许外部往里塞内容——比如自定义一个“AI 填充中”的动画效果，或者放一个手动触发按钮。

实际封装里，模板一般包含三块：状态提示条（请求中、成功、失败）、填充进度指示器、以及一个可选的触发按钮。如果你把触发按钮也做成插槽，页面甚至能把 SDK 的启动按钮放在任意位置，通过事件方式触发填充。

2.4 属性、方法、事件三角色

组件和外界的互动靠“属性 + 方法 + 事件”三个角色。

• 属性定义配置：endpoint、model、api-key、selector等，通过attributeChangedCallback响应变化。
• 方法定义行为：fill()启动填充、fillFrom(data)从一个已有的 JSON 数据源直接填充、reset()清空填充痕迹。
• 事件定义通知：fill-start、fill-progress、fill-success、fill-error、fill-ready，都是 CustomEvent。

这种“三角色”模型应该被严格遵循：外部不要直接访问组件内部树，组件不依赖外部任何全局变量。边界越清楚，维护越省心。

3. SDK 整体架构设计：它到底该管什么，不该管什么

我见过很多失败的封装，根本原因都是“管太宽”。一个 AI 表单填充 SDK，如果连弹窗、按钮颜色、水印、UI 文案都管了，那它很快就变成一套笨重的 UI 框架，跟老系统打架。

3.1 功能边界：只做增强，不重新造表单

这个 SDK 的边界应该定义为：它不渲染业务表单，只在现有表单上做“感知 + 决策 + 填充 + 反馈”。具体来说：

• 感知：自动扫描表单上下文，找出候选字段及标签、placeholder、name、id。
• 决策：把字段上下文、用户输入的部分数据、必要的业务提示拼成 AI 请求，交给服务端。
• 填充：把 AI 返回的结果，按字段映射规则填回控件。
• 反馈：把填充状态用事件和状态条通知给页面和用户。

它不该管的是：用户权限认证、表单校验策略、业务数据存储。这些留在你的业务系统里，SDK 只通过endpoint和api-key这种配置拿调用权限即可。

这个边界看起来是取舍，实际上是安全和可维护性的关键。把权限留在外部，意味着即使 SDK 开源泄漏，也不会直接暴露核心业务数据。

3.2 配置与数据流：静态配置、动态调用、实时事件

一份配置文件会包含以下关键模板：

{ "endpoint": "https://api.example.com/ai/form-fill", "model": "form-fill-v2", "apiKey": "sk-xxx", "selector": "#billing-form", "mapping": { "customer-name": "name.legal_name", "customer-phone": "contact.mobile", "customer-address": "address.full" }, "exclude": ["csrf-token", "captcha"] }

• endpoint：AI 服务接口地址，SDK 不做任何转发。
• model：按需选择模型或服务版本。
• selector：指定要填充的表单范围，默认取组件所在文档的第一个 form。
• mapping：把表单字段名映射到 AI 返回的 JSON 结构路径上，这个字段是真正的“字段理解层”。
• exclude：排除不需要填充的隐藏字段、令牌字段、验证码字段。

数据流大概是：用户触发 fill()→ SDK 读配置 → 采集表单上下文 → 组装请求 → 调用 AI 服务 → 解析返回 → 按 mapping 一一回填 → 触发事件。

3.3 状态机设计：别让组件在混乱的状态里翻车

AI 请求有不确定性，所以 SDK 内部要有清晰状态机。我用的状态是：

idle（就绪） →preparing（扫描表单） →fetching（请求 AI） →filling（回填中） →done或error

拿状态机管理，能防住一个经典 bug：用户连续点击多次 fill() 导致重复请求。SDK 内部只要state === 'fetching'时忽略新请求即可。另一个作用是，状态条 UI 可以根据状态自动切换，外部也能通过getState()方法查询。

状态机的实现不复杂，核心是一个setState(state)方法，每次切换时更新内部状态、渲染 UI、广播事件。

3.4 事件协议：对外唯一可信的通知通道

建议把事件协议设计成以下样子：

事件命名用“动作+结果”，语义清晰。外部接的时候，只用监听这几个事件就行，不用管内部是怎么实现的。

4. 核心源码思路拆解：从类骨架到字段理解与智能填充

前面是设计，这里是真正的“源码思路”。我习惯用 TypeScript 编写，最后打包成 ES Module 和 IIFE 两种格式。代码思路比最终代码更重要，所以我会把关键逻辑切片讲清楚。

4.1 类结构与生命周期模板

先看整体骨架：

export class AIFormFill extends HTMLElement { static get observedAttributes() { return ['endpoint', 'model', 'api-key', 'selector', 'mapping']; } private state: SDKState = 'idle'; private controller: AbortController | null = null; private root: ShadowRoot; private fieldRegistry: FieldContext[] = []; constructor() { super(); this.root = this.attachShadow({ mode: 'open' }); } connectedCallback(): void { this.render(); this.scanForm(); this.dispatch('fill-ready', { state: this.state }); } disconnectedCallback(): void { this.controller?.abort(); } attributeChangedCallback(name: string, oldVal: string, newVal: string): void { if (oldVal === newVal) return; // 配置变化时，重新扫描表单 if (name === 'selector' || name === 'mapping') { this.scanForm(); } if (name === 'endpoint' || name === 'api-key') { this.controller?.abort(); this.setState('idle'); } } }

几个关键设计：

• shadowRoot用open模式，方便调试工具检查内部状态。
• attributeChangedCallback监听配置变化，selector 变了就重新扫描表单字段。
• disconnectedCallback里要abort()，这是防止请求泄漏的兜底。

不要依赖构造函数做初始化，组件插入文档前属性可能还没就绪，connectedCallback才是安全时机。

4.2 表单字段采集：它怎么“理解”一个表单

AI 填充的前提是理解表单语义。SDK 需要扫描目标表单，把它变成结构化上下文。每一步都得考虑：哪些字段是必要的、哪些要排除、怎么把 label 和 placeholder 转化成 AI 能读懂的提示。

interface FieldContext { name: string; type: string; // text / select / checkbox / radio / date ... label?: string; placeholder?: string; value: string; required?: boolean; options?: string[]; // 对 select、radio 而言 } function scanForm(form: HTMLFormElement | HTMLElement): FieldContext[] { const fields: FieldContext[] = []; const nodes = form.querySelectorAll<HTMLElement>( 'input, select, textarea' ); nodes.forEach((node) => { const input = node as HTMLInputElement; if (input.disabled || input.readOnly) return; if (excludeSet.has(input.name || input.id)) return; fields.push({ name: input.name || input.id || extractInputName(node), type: getControlType(input), label: findLabel(input), placeholder: input.getAttribute('placeholder') || '', value: input.value || '', required: input.hasAttribute('required'), options: extractOptions(input) }); }); return dedupe(fields); }

字段采集有几个容易漏的细节：

• 排除 tokens:所有type=hidden且 name 里含token、csrf、captcha的字段，默认排除，因为这种字段填充了反而坏事。
• label 识别:优先用<label for="...">，次选aria-label，再不行就用包裹它的 label 文本。老系统里 label 经常和 input 不在同一个容器里，得向上找两层。
• select 选项:采集 select 的 option 文本，因为 AI 要判断返回的值合不合法，避免填出不存在选项。

采集成功后，这些上下文会存储到fieldRegistry里，供 fill() 调用。

4.3 组装请求与调用 AI 服务的完整链路

填充时，SDK 要把上下文、用户预设信息、以及一条业务提示语拼成一个请求体。

async fill(preset?: Record<string, unknown>): Promise<void> { if (this.state === 'fetching') return; this.setState('preparing'); const snapshot = this.fieldRegistry.map((f) => ({ name: f.name, label: f.label, type: f.type, placeholder: f.placeholder, value: f.value, required: f.required, options: f.options || [] })); const payload = { model: this.model, prompt: '请根据以下表单上下文和用户信息，用JSON返回需要填充的值。', formContext: snapshot, presetData: preset || {}, mappingRule: this.mappingRule }; this.setState('fetching'); const result = await this.requestAI(payload); this.performFill(result); }

requestAI里用 fetch 加 AbortController：

private async requestAI(payload: unknown): Promise<FillResult> { const controller = new AbortController(); this.controller = controller; const timeout = setTimeout(() => controller.abort(), 15000); try { const res = await fetch(this.endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.apiKey}` }, body: JSON.stringify(payload), signal: controller.signal }); if (!res.ok) { throw new Error(`AI request failed: ${res.status}`); } const data = await res.json(); return normalizeFillResult(data); } finally { clearTimeout(timeout); this.controller = null; } }

这里有几个判断值得展开：

• 超时机制：15 秒是一个合理默认值，因为常规表单填充不是复杂对话，15 秒足够；如果超时，主动 abort，避免连接挂到天荒地老。
• Authorization 头：这是最常见的转发方式。但注意，如果 key 在前端暴露有安全顾虑，建议让后端网关把请求转发给 AI 服务，SDK 只调自家后端接口，后端再调 AI。
• 返回结构约定：AI 返回的 JSON 必须是一个{ result: { fieldName: value } }结构，这个约定要在 prompt 里跟 AI 讲清楚，并在 SDK 里做一个校验函数，字段名不在 mapping 规则里就丢弃。

4.4 回填策略：不是所有控件都 set value 那么简单

拿到 AI 返回结果后，真正的“手工活”才刚开始——要把数据填回不同控件。不同控件的填充方式完全不同，必须分类型处理。

function performFill(result: FillResult): void { const fields = result.values || {}; const filled: string[] = []; Object.entries(fields).forEach(([fieldName, value]) => { const ctrl = this.fieldRegistry.find( (f) => f.name === fieldName || this.mappingRule[fieldName] === f.name ); if (!ctrl) return; const element = document.querySelector(`[name="${ctrl.name}"]`); if (!element) return; switch (ctrl.type) { case 'text': case 'email': case 'tel': case 'date': case 'textarea': setNativeValue(element, value as string); break; case 'select': fillSelect(element, value as string); break; case 'radio': setRadioByLabel(element, value as string); break; case 'checkbox': setCheckboxByValue(element, value as string); break; default: setNativeValue(element, value as string); } filled.push(fieldName); }); this.dispatch('fill-success', { filledFields: filled, result }); }

setNativeValue的实现很关键，因为直接el.value = v不会触发 React/Vue 的受控组件更新。必须用原生 value setter 绕过框架拦截：

function setNativeValue(element: Element, value: string) { const proto = Object.getPrototypeOf(element) as HTMLInputElement; const desc = Object.getOwnPropertyDescriptor(proto, 'value'); desc?.set?.call(element, value); element.dispatchEvent(new Event('input', { bubbles: true })); element.dispatchEvent(new Event('change', { bubbles: true })); }

这是专门给受控组件用的招。直接赋值在现代前端框架里十有八九无效，事件派发也不够，必须把 setter 找出来调用。我在多个框架项目里验证过，这个技巧有效。

select 的填充还要考虑 option 匹配：如果返回的中文文本和 option label 一致，直接选中；不一致，建议用模糊匹配（比如包含关系）作为兜底。radio 同理。

4.5 错误处理与降级策略

AI 不稳定是常态，错误处理必须分级。我的分层是：

降级策略也很重要：如果 AI 服务临时不可用，保留用户手动填写的入口，绝对不能让填充组件“卡死”用户操作。

4.6 安全与隐私：这个东西不能不提

AI 表单填充一定会把字段上下文发给服务端，隐私红线在于：

• 默认不采集密码、验证码、信用卡号：如果你的表单里有这些字段，宁可只发 name 和 label，也绝不发 value。
• 脱敏策略：常见的有身份证、手机号、邮箱，这类字段只给 AI 发标签、不发当前值，或者只发打码后的值。
• 数据保留期限：建议在服务端做日志策略时明确，客户端不落库。
• export 到日志：SDK 可以提供一个logMasked()方法，给外部自己决定怎么记录日志。

这节是给团队做安全评审用的。安全能力不是上线后补丁，而是 SDK 架构的一部分。

5. 实操落地：从零到一构建一个可复现的演示 SDK

这里开始进入“附源码思路”的正题。我给出一个最小可复现工程，你可以直接抄作业。

5.1 项目结构与依赖

项目用 Vite 做开发服务器和打包，用 TypeScript 编写逻辑。目录结构：

ai-form-fill/ ├── index.html # 演示页面 ├── package.json ├── tsconfig.json └── src/ ├── ai-form-fill.ts # 核心组件 ├── field-scanner.ts # 字段扫描 ├── ai-client.ts # AI 请求客户端 ├── filler.ts # 回填逻辑 └── index.ts # 注册出口

依赖项尽量少。不需要任何框架库，Web Component 本身就是原生协议，runtime 零依赖这个亮点一定要保持住。

5.2 核心注册与打包出口

src/index.ts的定义与注册：

import { AIFormFill } from './ai-form-fill'; if (!customElements.get('ai-form-fill')) { customElements.define('ai-form-fill', AIFormFill); } export default AIFormFill;

判断customElements.get是个好习惯，防止重复注册引发NotSupportedError。

打包配置上，Vite 的lib模式可以同时输出：

• ES 模块格式：dist/ai-form-fill.es.js
• IIFE 格式：dist/ai-form-fill.global.js，方便老系统直接<script>引入

文件名用ai-form-fill.global.js比较好，语义清楚。

5.3 演示页面：一个带受控表单的 HTML

做一个经典的演示页，里面是一个老系统常见的纯 HTML 表单，甚至是一个模拟 React 受控输入的场景：

<!DOCTYPE html> <html> <head> <meta charset="UTF-8" /> <title>Web Component AI 表单填充 Demo</title> <style> .form-item { margin-bottom: 16px; } label { display: block; margin-bottom: 4px; font-weight: 600; } input, select { width: 320px; padding: 8px; } </style> </head> <body> <form id="order-form"> <div class="form-item"> <label for="customer-name" class="field-label">客户姓名</label> <input id="customer-name" name="customer-name" placeholder="例如：张三" /> </div> <div class="form-item"> <label for="customer-mobile" class="field-label">手机号</label> <input id="customer-mobile" name="customer-mobile" placeholder="例如：13800138000" /> </div> <div class="form-item"> <label for="customer-address" class="field-label">收货地址</label> <input id="customer-address" name="customer-address" placeholder="省市区+街道" /> </div> <div class="form-item"> <label for="delivery-time">期望送达时间</label> <select id="delivery-time" name="delivery-time"> <option value="">请选择</option> <option value="morning">上午 9:00-12:00</option> <option value="afternoon">下午 14:00-18:00</option> <option value="evening">晚上 18:00-21:00</option> </select> </div> </form> <ai-form-fill endpoint="https://api.example.com/ai/fill" model="form-fill-v2" api-key="YOUR_KEY" selector="#order-form" ></ai-form-fill> <button id="fill-btn">AI 一键填充</button> <script type="module"> import './src/index.ts'; const fillEl = document.querySelector('ai-form-fill'); document.getElementById('fill-btn').addEventListener('click', () => { fillEl.fill({ /* 预设上下文 */ }); }); fillEl.addEventListener('fill-success', (e) => { console.log('填充成功字段：', e.detail.filledFields); }); fillEl.addEventListener('fill-error', (e) => { console.error('填充失败：', e.detail); }); </script> </body> </html>

这个演示的核心就是：页面完全不知道 AI 是怎么调用的，它只知道点按钮 → 调用 fill() → 得到 fill-success/fill-error 事件。

5.4 接入老系统的三种姿势

发布后，不同系统有不同的接入姿势：

• 现代工程：npm install，在入口文件import 'ai-form-fill/dist/ai-form-fill.es.js'，然后页面直接写标签。
• 老模板系统：直接<script src="/path/ai-form-fill.global.js"></script>，然后写标签。
• 低代码平台：有些平台支持自定义控件，把这个标签注册进去，配置 endpoint 和 mapping 即可。

这三种姿势，本质都是把 SDK 当作“黑盒增强器”。你不需要理解 AI 服务端怎么写的，只需要理解“填了配置、看事件”这个模型。

6. 常见问题与排查技巧实录

这里记录几个真实项目中我和朋友遇到的问题，都是文档里不会写的血泪坑。

6.1 Shadow DOM 事件为什么监听不到

症状：外部页面addEventListener('fill-success')没有触发。

排查思路：检查自定义事件的bubbles和composed属性。很多新手构造 CustomEvent 时忘记写：

this.dispatchEvent(new CustomEvent('fill-success', { detail: payload, bubbles: true, composed: true }));

composed: true是关键——它让事件能够穿越 Shadow DOM 边界进入外层 DOM。这一点我在前面已经强调，但值得再次标注：所有从 Shadow DOM 内部发出的 CustomEvent，都建议显式设置composed: true。

6.2 受控表单填充后刷新值但 UI 没更新

症状：明明 element.value 变了，但页面的 React/Vue 数据模型还是旧值，提交时是空。

这个 90% 是框架拦截了 value setter。解决方案就是我在 4.4 节写的setNativeValue：绕过框架，直接调用原生 setter，再派发 input 和 change 事件。这是整个 SDK 里最核心的一段兼容代码，建议升级为独立工具函数并加注释。

6.3 页面有 CSP 限制，外部脚本加载不了

这种问题多见于银行、政务类系统。CSP 通常会限制script-src，你必须把 SDK 的脚本域名加入白名单。此外，如果 CSP 里限制了connect-src，SDK 请求 AI 接口也会被拦。解决方案是：请求域名加入白名单，或者让后端网关转发同源请求。推荐后者，因为网关转发还能隐藏企业内部的 AI 服务结构。

6.4 AI 返回值和表单选项对不上

比如 AI 返回“上午”，但 select 的 value 是morning。我的建议是这样的三级匹配：

1. 精确匹配 value 值。
2. option 的 text 文本包含或等于返回文本。
3. 使用自定义映射字典，例如{ '上午': 'morning' }。

不建议用模型去猜 value，容易出现幻觉。在 mappingRule 里直接配好这种字典，比让 AI 硬猜稳得多。

6.5 选择器定位不准

有的老系统一个页面有多个表单，selector 不写导致 SDK 挂到了第一个 form 上。

解决：selector 支持三种形态：CSS 选择器、HTMLFormElement 实例、以及auto（默认找组件最近的祖先 form）。监听方式我用的是document.querySelector加document.getElementById兜底，适配老系统里五花八门的 ID。

6.6 多实例冲突

两个页面分别用两个不同配置的<ai-form-fill>，会不会串？不会，每个实例的 state 和 controller 都是实例字段，互不干扰。唯一要留心的是scanForm里如果用document.querySelector扫全局，可能把别的表单也扫进来。所以scanForm必须严格限制在selector指定的表单范围。

7. 从能用到好用：扩展方向与我的个人体会

核心 SDK 跑通以后，有几个很值得扩展的方向，也是我在真实项目里验证过的价值增量。

7.1 流式填充与多模态支持

如果 AI 服务支持 SSE（Server-Sent Events），SDK 可以在fetching阶段监听流式输出，实现“一边生成一边填”的体验。这在长表单上观感提升非常明显，用户能看到姓名先填上，地址一步一步出来。实现核心是改造requestAI，用fetch读ReadableStream，逐段解析 JSON，再调用performFill处理部分结果。注意流式情况下，字段间有依赖关系时（比如先填城市，再根据城市填区县），需要声明依赖顺序，不然会填得很乱。

多模态支持则是指如果 AI 能直接接收截图，SDK 可以允许用户拍一张手写表格照片，AI 识别后填充。但这种模式对端侧算力要求高，更合理的是只做“图片上传 → 服务端 OCR+LLM → 返回填充结果”链路。

7.2 云端配置中心

一旦 SDK 接入多个系统，字段映射、prompt 模板、版本选择如果都写在前端属性里，改动会很痛苦。可以做一个云端配置中心，SDK 只配置一个config-id，启动时拉取并缓存配置。这样全公司几十个系统，统一改一处配置就能全部生效。这个思路非常适合团队沉淀“智能表单能力中台”。

7.3 表单校验联动

填充完不等于填对了。SDK 可以暴露一个validateMappedFields()方法，对 AI 返回的每个值做基础校验：邮箱格式、手机号位数、必填字段是否为空。一旦发现问题，可以在状态条里回显“手机号格式看起来不对，请确认”。这能在体验上堵住 AI 幻觉的最后一道闸。

7.4 我的个人体会

最后分享一点真实感受。封装这类 SDK，最难的不是 Web Component 的 API 用法，而是“克制”。我刚开始写的时候，总想把 loading 动画、成功弹窗、AI 推荐理由展示全塞进去，结果项目越写越重，接入方怨声载道。后来我把 UI 部分几乎砍光，只保留一条 2 像素高的状态条和事件协议，反而接入量翻了三倍——因为老系统的团队终于觉得“这玩意不会摔碎我的布局”。

另外就是“AI 当服务”的思路：SDK 里不要写任何具体业务 prompt，只把表单上下文结构化交给服务端，让服务端去拼 prompt。这样可以随时换模型、调策略，SDK 几乎不用发版。我自己见过太多团队把 prompt 写死在前端，最后模型一升级，全乱套。

还有一个经验：这类 SDK 一定要有一个“演示盒子”，最好是一个 800 行的 HTML 单文件，包含常见字段类型和模拟接口。因为团队评审和试用时，花三分钟看一个能跑的 demo，比看一小时文档都管用。我每次交付这类项目都会把这个最小 demo 带在包里，谁问就直接发过去。

如果你也想在团队里推这件事，我的建议是从一个非核心但痛点明显的表单开始，比如订单备注补充、客户信息完善、地址标准化这种低频但价值高的场景。验证跑通之后，再往更多系统铺开。技术选型不是越大越复杂越好，能让一个老系统三天内接入 AI 能力，本身就是这个方案最大的价值。