@kc-one/smart-fill-sdk 0.0.12 → 0.0.13

package/README.md

@@ -1,223 +1,542 @@
-# Smart Fill SDK
-
-页面内智能录入 SDK，用于在业务页面嵌入「文本 / 图片识别 → 自动表单回填 → 结果反馈」能力。
-
-## 快速开始
-
-```bash
-npm install
-npm run dev
-```
-
-打开 Vite 示例页后，点击右上角「智能录入」悬浮按钮。
-
-## 接入示例
-
-```ts
-import { SmartFill } from '@kc-one/smart-fill-sdk'
-import '@kc-one/smart-fill-sdk/style.css'
-
-await SmartFill.setup({ apiKey: 'seKey_xxxxxxxxxxxxx' })
-// 网关地址在 src/config/defaults.ts 的 DEFAULT_BASE_URL 中配置
-
-const smartFill = SmartFill.create({
-  formCode: 'apply-form',
-  strictFormConfig: true,
-  routeContainerSelector: '.page-container',
-  // floatingContainer: '#smart-fill-host'
-})
-
-smartFill.registerFields([
-  {
-    fieldId: 'customerName',
-    label: '客户姓名',
-    type: 'text',
-    element: '[data-smart-fill-key="customerName"]'
-  },
-  {
-    fieldId: 'legalBankMobile',
-    label: '法人手机号',
-    type: 'text',
-    localRuleMode: 'off', // 该字段不走本地规则，仅走后端识别
-    element: '[data-smart-fill-key="legalBankMobile"]'
-  }
-])
-
-smartFill.mountFloatingButton()
-```
-
-### 悬浮挂载策略
-
-`mountFloatingButton()` 默认会自动识别当前 SPA 子路由页面容器；如果你的业务页面结构固定，推荐显式传入挂载策略，优先级如下：
-
-1. `floatingContainer`: 直接指定悬浮面板挂载容器，支持 `HTMLElement` 或 CSS 选择器
-2. `routeContainerSelector`: 指定当前子路由页面容器选择器
-3. SDK 自动识别当前页面容器
-4. 回退到 `document.body`
-
-```ts
-const smartFill = SmartFill.create({
-  formCode: 'apply-form',
-  floatingContainer: '#smart-fill-host'
-  // 或 routeContainerSelector: '.app-main > .page-container'
-})
-```
-
-## 核心流程
-
-```text
-SmartFill.setup({ apiKey })
-  → 校验 apiKey / 创建会话 / 获取 accessToken
-SmartFill.create({ formCode })
-  → 创建页面实例，绑定网关客户端
-smartFill.registerFields([...])   // 可选：L3 高精度字段注册
-smartFill.mountFloatingButton()   // 挂载悬浮入口 + 弹框 UI
-smartFill.open()
-  → rescan() 扫描字段，生成 scanToken
-用户输入文本 / 上传图片，点击「智能识别回填」
-  → 本地规则预识别（可开关）
-  → 后端识别网关补全
-  → 合并结果，自动回填高置信字段
-  → 返回 applied / skipped / warnings / traceId
-```
-
-## 当前实现范围
-
-| 模块 | 能力 |
-| --- | --- |
-| `SmartFill.setup` | apiKey 校验、会话初始化（网关地址见 `config/defaults.ts`） |
-| `SmartFill.create` | 实例生命周期、单活 UI 管理、SSR mock 实例 |
-| `registerFields / rescan` | 优先注册字段，兜底 DOM 扫描 |
-| `LocalRuleEngine` | 手机号、身份证、邮箱、银行卡、金额、日期、角色化键值对识别 |
-| `FieldSchema.localRuleMode` | 字段级本地规则策略：`inherit / off / only` |
-| `SmartFillPanel` | Shadow DOM 面板、本地优先识别总开关、自动回填进度和结果反馈 |
-| `DomFiller` | 原生控件回填、scanToken / fingerprint 校验、浅蓝高亮反馈 |
-| `GatewayClient` | `/sdk/session`、`/sdk/forms/:code`、`/sdk/recognize` 网关调用 |
-
-## 目录结构
-
-```text
-smart-fill-sdk/
-├─ package.json              # 包配置，exports 指向 dist/
-├─ vite.config.ts            # Vite 库模式构建 + d.ts 生成
-├─ tsconfig.json             # TypeScript 编译配置
-├─ README.md                 # 本文件
-│
-├─ examples/                 # 接入示例
-│  └─ vanilla/
-│     ├─ index.html          # 原生表单 demo 页面
-│     └─ main.ts             # setup → create → registerFields → mountFloatingButton
-│
-└─ src/                      # SDK 源码
-   ├─ index.ts                # 包入口，统一导出对外 API 与类型
-   ├─ style.css              # 回填成功高亮样式（浅蓝背景）
-   ├─ vite-env.d.ts          # CSS 模块类型声明
-   │
-   ├─ core/                  # 生命周期与实例编排
-   │  ├─ smart-fill.ts      # 全局 setup / create 入口，管理会话状态
-   │  ├─ smart-fill-instance.ts  # 页面实例：扫描、识别、自动回填、事件分发
-   │  ├─ instance-manager.ts  # 多实例 UI 互斥，同一时刻仅一个面板激活
-   │  └─ errors.ts           # 统一错误对象、traceId 生成
-   │
-   ├─ scanner/               # 字段扫描与稳定标识
-   │  ├─ dom-scanner.ts      # DOM 字段扫描、弹窗容器定位、scanToken 生成
-   │  └─ fingerprint.ts      # 字段 fingerprint 生成，过滤动态 ID
-   │
-   ├─ rules/                 # 浏览器端本地规则
-   │  └─ local-rules.ts      # 正则 + 键值对 + 角色语义识别引擎
-   │
-   ├─ config/                 # SDK 内置配置
-   │  └─ defaults.ts          # DEFAULT_BASE_URL 网关根地址（前期写死）
-   │
-   ├─ client/                 # 后端网关客户端
-   │  └─ gateway-client.ts   # session / formConfig / recognize 请求封装
-   │
-   ├─ filler/                 # 表单回填
-   │  └─ dom-filler.ts        # DOM 写入、适配器分发、scanToken 校验、高亮
-   │
-   ├─ ui/                     # 页面内 UI
-   │  └─ panel.ts             # Shadow DOM 弹框：输入、开关、识别、结果展示
-   │
-   ├─ events/                 # 事件系统
-   │  └─ event-bus.ts        # 轻量 pub/sub，驱动 ready / recognized / applied 等事件
-   │
-   ├─ adapters/               # 组件库回填适配器
-   │  └─ native.ts           # 原生 input / textarea / select 适配器
-   │
-   └─ types/                  # 对外 TypeScript 类型
-      └─ index.ts             # FieldSchema、RecognizeResult、SmartFillEventMap 等
-```
-
-### 模块职责说明
-
-#### `core/` — 生命周期
-
-- **`smart-fill.ts`**：SDK 全局单例入口。`setup()` 负责 apiKey 校验和会话初始化；`create()` 在 ready 后创建页面实例。
-- **`config/defaults.ts`**：前期写死的网关 `DEFAULT_BASE_URL`，切换环境时改此文件即可。
-- **`smart-fill-instance.ts`**：单页面实例的核心编排器。串联扫描 → 本地规则 → 网关识别 → 自动回填，并通过 EventBus 向外派发事件。
-- **`instance-manager.ts`**：保证同一时刻只有一个实例的 UI 面板处于打开状态，避免多实例互相遮挡。
-- **`errors.ts`**：统一错误码封装（`SmartFillException`）和 `traceId` 生成，供审计和排障使用。
-
-#### `scanner/` — 字段扫描
-
-- **`dom-scanner.ts`**：扫描页面可见输入控件，支持注册字段优先、平台容器、最上层弹窗/抽屉定位。每次扫描生成唯一 `scanToken`。
-- **`fingerprint.ts`**：为每个字段生成稳定指纹，过滤 React/AntD 等框架的动态 ID，用于回填前校验字段是否变化。
-
-#### `rules/` — 本地规则
-
-- **`local-rules.ts`**：浏览器端优先识别引擎。支持正则提取（手机号、身份证等）、键值对解析（`姓名：张三`）、角色语义（法人/紧急联系人/配偶）。匹配时优先角色字段，再退化到通用字段。
-
-#### `client/` — 网关
-
-- **`gateway-client.ts`**：封装后端 `/sdk/session`、`/sdk/forms/:code`、`/sdk/recognize` 三个接口，统一请求 `DEFAULT_BASE_URL`。
-
-#### `filler/` — 回填
-
-- **`dom-filler.ts`**：执行字段写入。校验 `scanToken` 和 `fingerprint` 防止误填；支持注册字段 `setValue`、适配器模式和原生 DOM 事件兜底；回填成功后添加浅蓝背景高亮，用户交互后自动消失。
-
-#### `ui/` — 界面
-
-- **`panel.ts`**：Shadow DOM 隔离的页面内弹框。包含文本输入、图片上传、本地优先识别开关、清空/识别按钮、识别结果列表和状态反馈。支持右上角悬浮 + 拖拽。
-
-#### `events/` — 事件
-
-- **`event-bus.ts`**：实例级和全局级事件总线，事件包括 `ready`、`scanCompleted`、`recognizing`、`recognized`、`applying`、`applied`、`error`。
-
-#### `adapters/` — 适配器
-
-- **`native.ts`**：原生 HTML 表单控件（input / textarea / select）的回填适配器，通过 dispatch `input/change` 事件触发框架响应。
-
-#### `types/` — 类型
-
-- **`index.ts`**：全部对外 TypeScript 类型定义，包括字段模型、识别结果、回填结果、事件映射、适配器接口等。
-
-## 本地规则开关
-
-| 层级 | 配置 | 说明 |
-| --- | --- | --- |
-| 弹框总开关 | UI「启用本地优先识别」 | 一键开启/关闭本地规则，默认开启 |
-| 字段级 | `FieldSchema.localRuleMode` | `inherit` 跟随总开关；`off` 跳过本地规则；`only` 仅本地规则、不走后端 |
-
-## 发布到 npm 公共仓库
-
-包归属 [@kc-one](https://www.npmjs.com/settings/kc-one/packages) 组织，包名为 `@kc-one/smart-fill-sdk`。
-
-```bash
-npm login                    # 使用已加入 kc-one 组织且开启 2FA 的账号
-npm run build
-npm publish --access public  # publishConfig 已配置 public + registry.npmjs.org
-```
-
-安装：
-
-```bash
-npm install @kc-one/smart-fill-sdk
-```
-
-## 构建
-
-```bash
-npm run typecheck   # 类型检查
-npm run build       # 构建 dist/（ESM + UMD + d.ts）
-npm run preview     # 预览构建产物
-```
+# Smart Fill SDK
+
+页面内智能录入 SDK，用于在业务页面嵌入「文本 / 图片识别 → 自动表单回填 → 结果反馈」能力。
+
+- **包名**：`@kc-one/smart-fill-sdk`
+- **当前版本**：`0.0.12`
+- **浏览器**：Chrome ≥ 90、Edge ≥ 90、Firefox ≥ 88、Safari ≥ 14
+
+## 安装
+
+```bash
+npm install @kc-one/smart-fill-sdk
+```
+
+## 快速开始
+
+### 本地开发
+
+```bash
+npm install
+npm run dev
+```
+
+打开 Vite 示例页（`examples/vanilla/index.html`），点击「智能录入」入口。
+
+### 业务接入
+
+```ts
+import { SmartFill } from '@kc-one/smart-fill-sdk'
+import '@kc-one/smart-fill-sdk/style.css'
+
+await SmartFill.setup({ apiKey: 'seKey-xxxxxxxxxxxxx' })
+// 网关根地址见 DEFAULT_BASE_URL（src/config/defaults.ts）
+
+const smartFill = SmartFill.create({
+  formCode: 'apply-form',
+  routeContainerSelector: '.page-container'
+})
+
+smartFill.registerFields([
+  {
+    fieldId: 'customerName',
+    label: '客户姓名',
+    type: 'text',
+    element: '[data-smart-fill-key="customerName"]'
+  },
+  {
+    fieldId: 'legalBankMobile',
+    label: '法人手机号',
+    type: 'text',
+    localRuleMode: 'off', // 该字段不走本地规则，仅走后端识别
+    element: '[data-smart-fill-key="legalBankMobile"]'
+  }
+])
+
+smartFill.mountFloatingButton()
+// 或嵌入指定容器：smartFill.mount('#smart-fill-entry')
+```
+
+## 核心流程
+
+```text
+SmartFill.setup({ apiKey })
+  → 校验 apiKey / 创建会话 / 获取 accessToken
+SmartFill.create({ formCode, ... })
+  → 创建页面实例，绑定网关客户端
+smartFill.registerFields([...])     // 可选：L3 高精度字段注册
+smartFill.mountFloatingButton()     // 或 mount() 嵌入容器
+smartFill.open()                      // 打开面板并 rescan
+用户输入文本 / 上传图片，点击「智能识别」
+  → rescan() 扫描字段，生成 scanToken
+  → 本地规则预识别（可开关）
+  → 后端识别网关补全
+  → 合并结果，自动回填高置信字段（或 apiCallback 回调）
+  → 返回 applied / skipped / warnings / traceId
+```
+
+---
+
+## 对外 API 总览
+
+### 类与常量
+
+| 导出 | 说明 |
+| --- | --- |
+| `SmartFill` | 全局入口：`setup` / `create` / `on` |
+| `SmartFillInstance` | 页面实例类（通常通过 `SmartFill.create()` 获取） |
+| `DomScanner` | DOM 字段扫描器 |
+| `DomFiller` | 表单回填执行器 |
+| `LocalRuleEngine` | 浏览器端本地规则识别引擎 |
+| `EventBus` | 轻量事件总线 |
+| `NativeAdapter` | 原生 input / textarea / select 适配器 |
+| `UiFrameworkAdapter` | Element / Ant Design Vue / Naive UI / Arco / Vant 等 UI 框架适配器 |
+| `ElementAdapter` | `UiFrameworkAdapter` 的兼容别名 |
+| `DEFAULT_BASE_URL` | 网关根地址常量 |
+| `SmartFillException` | 结构化异常类 |
+| `createError` | 创建标准 SDK 异常 |
+| `toSmartFillError` | 将未知 error 归一化为 `SmartFillError` |
+| `createTraceId` | 生成唯一追踪 ID |
+
+### 类型
+
+| 类型 | 说明 |
+| --- | --- |
+| `SmartFillSetupConfig` | `setup()` 配置 |
+| `SmartFillCreateConfig` | `create()` 配置 |
+| `FieldSchema` | 业务注册字段 Schema |
+| `FieldDescriptor` | 扫描后的运行时字段描述 |
+| `FieldType` / `FieldOption` | 字段类型与选项 |
+| `ScanResult` | 扫描结果（含 `scanToken` 与 `fields`） |
+| `RecognizePayload` / `RecognizeResult` | 识别入参与返回 |
+| `FieldSuggestion` | 单条识别建议 |
+| `ApplyInput` / `ApplyResult` | 回填入参与结果 |
+| `AutoApplyItem` / `AutoApplyState` | 自动回填候选状态 |
+| `ApiRecognizeCallbackResult` / `ApiRecognizeField` | API 回调模式返回结构 |
+| `SmartFillEventMap` / `SmartFillError` | 事件映射与错误结构 |
+| `SmartFillAdapter` | 自定义组件库适配器接口 |
+| `SessionResponse` | 会话初始化响应 |
+| `FormConfigResponse` | 已弃用的远端表单配置 |
+
+---
+
+## SmartFill（全局入口）
+
+### `SmartFill.setup(config): Promise<SessionResponse>`
+
+初始化 SDK，校验 apiKey 并创建网关会话。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | 是 | API 密钥，格式 `seKey-` 开头 |
+| `requestTimeoutMs` | `number` | 否 | HTTP 超时，默认 `30000` |
+
+行为说明：
+
+- 相同 `apiKey` 重复调用会复用已有 Promise
+- `apiKey` 变更时会销毁所有存活实例并清空扫描缓存
+- SSR 环境（无 `window`）返回 mock session，不发起网络请求
+
+### `SmartFill.create(config?): SmartFillInstance`
+
+创建页面实例。**必须在 `setup` 就绪后调用**，否则抛出 `SDK_NOT_READY`。
+
+SSR 环境返回 noop 实例，所有方法安全空操作。
+
+### `SmartFill.on(event, handler): () => void`
+
+订阅全局事件，目前仅 `ready`。返回取消订阅函数。
+
+---
+
+## SmartFillInstance（页面实例）
+
+通过 `SmartFill.create()` 获取，负责扫描、识别、回填与 UI 生命周期。
+
+### 事件
+
+#### `on(event, handler): () => void`
+
+订阅实例事件，返回取消订阅函数。
+
+| 事件 | 载荷 | 触发时机 |
+| --- | --- | --- |
+| `ready` | `{ apiKey }` | 实例就绪（全局 setup 完成时由全局总线触发） |
+| `scanCompleted` | `{ scanToken, fieldCount }` | `rescan()` 成功 |
+| `recognizing` | `{ scanToken, traceId }` | 识别开始 |
+| `recognized` | `RecognizeResult` | 识别完成 |
+| `applying` | `{ scanToken, count }` | 回填开始 |
+| `applied` | `ApplyResult` | 回填完成 |
+| `error` | `SmartFillError` | 任意阶段出错 |
+
+### 字段注册
+
+#### `registerFields(fields): this`
+
+显式注册字段映射（L3 模式）。注册后 `rescan` 仅解析这些字段，不再自动扫 DOM。
+
+- 支持链式调用
+- `rowKey` 用于明细行等同 `fieldId` 多行场景，组合键 `{fieldId}:{rowKey}` 不可重复
+
+#### `unregisterFields(fieldIds?): void`
+
+取消注册字段。不传 `fieldIds` 时清空全部注册。
+
+### UI 挂载
+
+#### `mount(target): this`
+
+将面板嵌入指定容器（inline 模式）。`target` 支持 CSS 选择器或 `HTMLElement`。
+
+#### `mountFloatingButton(): this`
+
+挂载右下角悬浮按钮 + 弹框（floating 模式）。挂载容器优先级见 [悬浮挂载策略](#悬浮挂载策略)。
+
+#### `open(targetPanel?): Promise<void>`
+
+打开面板并触发 `rescan`（若尚无扫描结果）。同时激活当前实例，关闭其他实例面板。
+
+#### `close(targetPanel?): void`
+
+关闭面板，不销毁实例。
+
+### 扫描 / 识别 / 回填
+
+#### `rescan(): Promise<ScanResult>`
+
+扫描页面可回填字段。优先级：`registerFields` > DOM 自动扫描。
+
+- 生成唯一 `scanToken`，贯穿识别与回填
+- 无字段时抛出 `NO_FIELDS_FOUND`
+- 成功时 emit `scanCompleted`
+
+#### `recognize(input): Promise<RecognizeResult>`
+
+识别入口：文本和/或图片 → 本地规则 + 后端网关 → 合并 → 自动回填或 API 回调。
+
+```ts
+await smartFill.recognize({
+  text: '姓名：张三 手机号：13800000000',
+  images: [file] // 可选，File[]
+})
+```
+
+识别策略：
+
+1. 识别前先 `rescan()`，下拉选项在用户主动识别时动态展开
+2. `localRuleMode === 'off'` 跳过本地规则；`'only'` 跳过后端；`'inherit'` 跟随本地优先开关
+3. 后端成功时优先采用后端字段，本地规则仅补充后端未返回的字段
+4. 后端失败且存在本地结果时降级为本地识别
+5. `apiEnable: true` 时跳过自动回填，改为触发 `apiCallback`
+6. 置信度 ≥ 0.75 且无 `warnings` 的字段自动回填
+
+#### `apply(input): Promise<ApplyResult>`
+
+手动回填指定字段，需传入与当前扫描一致的 `scanToken`。
+
+```ts
+await smartFill.apply({
+  scanToken: result.scanToken,
+  values: [
+    { fieldId: 'customerName', value: '张三', source: 'ai' }
+  ]
+})
+```
+
+#### `useAdapter(adapter): this`
+
+注册组件库回填适配器，支持链式调用。实例默认已内置 `UiFrameworkAdapter`。
+
+#### `destroy(): void`
+
+销毁实例：移除面板、清空事件、从实例管理器注销。销毁后调用其他方法抛出 `INSTANCE_DESTROYED`。
+
+---
+
+## SmartFill.create 配置项
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `formCode` | `string` | — | 表单编码，识别请求携带给后端 |
+| `strictFormConfig` | `boolean` | — | **已弃用**，不再拉取远端 formConfig |
+| `root` | `HTMLElement \| ShadowRoot` | `document` | 扫描根节点 |
+| `maxFields` | `number` | `200` | DOM 自动扫描最大字段数 |
+| `floatingContainer` | `HTMLElement \| string` | — | 悬浮面板挂载容器，优先级最高 |
+| `routeContainerSelector` | `string` | — | 子路由页面容器选择器 |
+| `locale` | `'zh-CN' \| 'en-US'` | — | 预留 |
+| `messages` | `Record<string, string>` | — | 面板文案覆盖，key 见下表 |
+| `apiEnable` | `boolean` | `false` | 为 `true` 时识别后不自动回填，改走 `apiCallback` |
+| `apiCallback` | `(result) => void \| Promise<void>` | — | API 回调，仅在 `apiEnable: true` 时触发 |
+
+### 面板文案 key（`messages`）
+
+| key | 默认文案 |
+| --- | --- |
+| `entry` | 智能录入 |
+| `title` | 智能录入 |
+| `expand` / `collapse` / `close` | 展开 / 收起 / 关闭 |
+| `placeholder` | 粘贴文本，如：姓名：张三 手机号：13800000000 |
+| `clear` | 清空 |
+| `recognize` | 智能识别 |
+| `uploadHint` | 点击、拖拽、Ctrl + V 粘贴图片至此 |
+| `empty` | 暂无识别结果 |
+| `emptyInput` | 请输入文本内容。 |
+| `recognized` | 识别完成，正在自动回填... |
+| `invalidImageError` | 请选择图片文件。 |
+| `maxFilesError` | 最多上传 N 张图片 |
+| `maxSingleFileSizeError` | 单张图片不能超过 10MB |
+| `maxTotalFileSizeError` | 上传图片总大小不能超过 50MB |
+| `imageReady` | 已选择 N 张图片，开始识别... |
+
+---
+
+## API 回调模式
+
+适用于业务方自行处理识别结果、不依赖 SDK 自动 DOM 回填的场景。
+
+```ts
+const smartFill = SmartFill.create({
+  formCode: 'apply-form',
+  apiEnable: true,
+  apiCallback: async (result) => {
+    console.log(result.fields) // ApiRecognizeField[]
+    // 可选：自行调用 apply 回填
+    await smartFill.apply({
+      scanToken: result.scanToken,
+      values: result.fields.map((f) => ({ fieldId: f.fieldId, value: f.value }))
+    })
+  }
+})
+```
+
+`ApiRecognizeCallbackResult` 结构：
+
+| 字段 | 说明 |
+| --- | --- |
+| `scanToken` | 当前扫描批次 token |
+| `trace` | 追踪信息（traceId、usedOcr、usedAi、durationMs） |
+| `fields` | 识别字段列表（含 value、confidence、currentValue 等） |
+| `warnings` | 可选警告 |
+
+---
+
+## 扩展模块 API
+
+### DomScanner
+
+```ts
+const scanner = new DomScanner(document)
+
+// 同步扫描
+const result = scanner.scan({
+  registered?: FieldSchema[],
+  scanContainer?: string,
+  maxFields?: number
+})
+
+// 异步扫描（展开下拉并补充动态选项）
+const resultWithOptions = await scanner.scanWithDynamicOptions({ maxFields: 200 })
+```
+
+返回 `ScanResult`：`{ scanToken, fields: FieldDescriptor[] }`。
+
+### DomFiller
+
+```ts
+const filler = new DomFiller(fields, schemas, adapters)
+const result = await filler.apply({
+  scanToken: 'scan_xxx',
+  values: [{ fieldId: 'mobile', value: '13800000000' }]
+})
+```
+
+回填前校验 `scanToken` 与 `fingerprint`，支持 `FieldSchema.setValue` / 适配器 / 原生 DOM 三种写入路径。
+
+跳过原因码：`FIELD_NOT_FOUND` | `SCAN_TOKEN_EXPIRED` | `VALIDATE_FAILED` | `SET_VALUE_FAILED`。
+
+### LocalRuleEngine
+
+```ts
+const engine = new LocalRuleEngine()
+const suggestions = engine.recognize(text, fields, scanToken)
+```
+
+当前支持的本地识别类型：手机号、身份证、邮箱、银行卡、金额、日期。
+
+### EventBus
+
+```ts
+const bus = new EventBus()
+const off = bus.on('recognized', (payload) => { ... })
+bus.off('recognized', handler)
+bus.emit('recognized', result)
+bus.clear()
+```
+
+### SmartFillAdapter（自定义适配器）
+
+```ts
+smartFill.useAdapter({
+  name: 'my-component',
+  match: (element, field) => element.classList.contains('my-input'),
+  getValue: (field) => { ... },
+  setValue: async (field, value) => { ... },
+  validateApplied: async (field, value) => true
+})
+```
+
+---
+
+## FieldSchema 字段注册
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `fieldId` | `string` | 字段唯一标识 |
+| `label` | `string` | 展示标签 |
+| `type` | `FieldType` | `text` / `textarea` / `select` / `radio` / `checkbox` / `date` / `number` / `amount` / `cascader` |
+| `element` | `HTMLElement \| string` | DOM 元素或 CSS 选择器 |
+| `localRuleMode` | `'inherit' \| 'off' \| 'only'` | 本地规则策略 |
+| `options` | `FieldOption[]` | 下拉/单选选项 |
+| `getValue` | `() => unknown` | 自定义读值 |
+| `setValue` | `(value) => void \| Promise<void>` | 自定义写值 |
+| `transform` | `(aiValue) => unknown` | AI 返回值转换 |
+| `validate` | `(value) => boolean \| string \| Promise<...>` | 写入前校验 |
+| `rowKey` | `string \| number` | 明细行 key |
+| `scope` | `'form' \| 'detail' \| 'dialog'` | 字段作用域 |
+| `required` / `section` / `demoValue` | — | 其他元数据 |
+
+---
+
+## 本地规则
+
+| 层级 | 配置 | 说明 |
+| --- | --- | --- |
+| 实例级 | `localPriorityEnabled`（localStorage 持久化） | 默认 **关闭**（优先后端识别）；开启后 `inherit` 字段走本地规则 |
+| 字段级 | `FieldSchema.localRuleMode` | `inherit` 跟随实例开关；`off` 跳过后端；`only` 仅本地、不走后端 |
+
+---
+
+## 悬浮挂载策略
+
+`mountFloatingButton()` 挂载容器优先级：
+
+1. `floatingContainer`：显式指定容器（`HTMLElement` 或 CSS 选择器）
+2. `routeContainerSelector`：子路由页面容器
+3. SDK 自动识别（`#app` / `#root` / `main` / `.page-container` 等）
+4. 回退到 `document.body`
+
+floating 模式下路由切换或挂载容器从 DOM 移除时，实例会自动 `destroy()`。
+
+---
+
+## 错误码
+
+| code | stage | 说明 |
+| --- | --- | --- |
+| `SDK_NOT_READY` | setup | 未调用 setup 或 setup 未完成 |
+| `API_KEY_INVALID` | setup | apiKey 格式不正确 |
+| `NO_FIELDS_FOUND` | scan | 当前页面未找到可回填字段 |
+| `UNSUPPORTED_PAGE` | scan / ui | 字段重复注册 / 挂载点未找到 |
+| `SCAN_TOKEN_EXPIRED` | apply | 扫描已过期，需重新 rescan |
+| `TOKEN_EXPIRED` | recognize | 会话过期，清空扫描缓存 |
+| `INSTANCE_DESTROYED` | ui | 实例已销毁 |
+| `RECOGNIZE_FAILED` | recognize | 识别失败 |
+| `RECOGNIZE_TIMEOUT` | recognize | 识别超时（可重试） |
+
+捕获示例：
+
+```ts
+import { SmartFillException } from '@kc-one/smart-fill-sdk'
+
+try {
+  await smartFill.recognize({ text: '...' })
+} catch (error) {
+  if (error instanceof SmartFillException) {
+    console.log(error.smartFillError.code, error.smartFillError.traceId)
+  }
+}
+```
+
+---
+
+## 目录结构
+
+```text
+smart-fill-sdk/
+├─ package.json
+├─ vite.config.ts
+├─ tsconfig.json
+├─ README.md
+│
+├─ examples/vanilla/          # 原生表单接入示例
+│  ├─ index.html
+│  └─ main.ts
+│
+└─ src/
+   ├─ index.ts                 # 包入口，统一导出 API 与类型
+   ├─ style.css                # 回填高亮样式
+   │
+   ├─ core/                    # 生命周期与实例编排
+   │  ├─ smart-fill.ts         # setup / create 全局入口
+   │  ├─ smart-fill-instance.ts
+   │  ├─ instance-manager.ts   # 多实例 UI 互斥
+   │  └─ errors.ts             # SmartFillException / createError
+   │
+   ├─ scanner/                 # 字段扫描
+   │  ├─ dom-scanner.ts
+   │  ├─ fingerprint.ts
+   │  └─ ui-frameworks.ts      # Element / AntD / Naive 等组件识别
+   │
+   ├─ select/                  # 下拉 / 级联 / 地址选择回填
+   │  ├─ custom-select.ts
+   │  ├─ select-fill.ts
+   │  ├─ option-match.ts
+   │  └─ address-cascader.ts
+   │
+   ├─ rules/local-rules.ts     # 本地规则引擎
+   ├─ config/defaults.ts       # DEFAULT_BASE_URL
+   ├─ client/gateway-client.ts # 网关 HTTP 客户端
+   ├─ filler/                  # DOM 回填与高亮
+   │  ├─ dom-filler.ts
+   │  └─ highlight-style.ts
+   ├─ ui/panel.ts              # Shadow DOM 面板
+   ├─ events/event-bus.ts
+   ├─ adapters/                # 原生 + UI 框架适配器
+   │  ├─ native.ts
+   │  └─ ui-framework.ts
+   └─ types/index.ts           # 全部对外 TypeScript 类型
+```
+
+---
+
+## 实现范围
+
+| 模块 | 能力 |
+| --- | --- |
+| `SmartFill.setup` | apiKey 校验、会话初始化 |
+| `SmartFill.create` | 实例生命周期、单活 UI 管理、SSR mock |
+| `registerFields / rescan` | 优先注册字段，兜底 DOM 扫描 + 页面/会话级扫描缓存 |
+| `LocalRuleEngine` | 手机号、身份证、邮箱、银行卡、金额、日期 |
+| `FieldSchema.localRuleMode` | 字段级本地规则策略 |
+| `SmartFillPanel` | Shadow DOM 面板、文本/图片输入、识别进度与结果反馈 |
+| `DomFiller` | 原生 + UI 框架回填、scanToken / fingerprint 校验、浅蓝高亮 |
+| `UiFrameworkAdapter` | Element / Ant Design Vue / Naive UI / Arco / Vant 等 |
+| `GatewayClient` | session / OCR / smartEntry 识别网关 |
+
+---
+
+## 构建与发布
+
+```bash
+npm run typecheck   # 类型检查
+npm run build       # 构建 dist/（ESM + UMD + d.ts）
+npm run preview     # 预览构建产物
+```
+
+发布到 [@kc-one](https://www.npmjs.com/settings/kc-one/packages)：
+
+```bash
+npm login
+npm run build
+npm publish --access public
+```