Smart Fill SDK

页面内智能录入 SDK，用于在业务页面嵌入「文本 / 图片识别 → 自动表单回填 → 结果反馈」能力。

快速开始

npm install
npm run dev

打开 Vite 示例页后，点击右上角「智能录入」悬浮按钮。

接入示例

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

const smartFill = SmartFill.create({
  formCode: 'apply-form',
  floatingContainer: '#smart-fill-host'
  // 或 routeContainerSelector: '.app-main > .page-container'
})

核心流程

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 网关调用 |

目录结构

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 组织，包名为 @kc-one/smart-fill-sdk。

npm login                    # 使用已加入 kc-one 组织且开启 2FA 的账号
npm run build
npm publish --access public  # publishConfig 已配置 public + registry.npmjs.org

安装：

npm install @kc-one/smart-fill-sdk

构建

npm run typecheck   # 类型检查
npm run build       # 构建 dist/（ESM + UMD + d.ts）
npm run preview     # 预览构建产物