Formbridge

FormBridge

混合模式的 Agent-人工表单提交基础设施。AI Agent 填写已知信息，由人工补全其余内容，并提供完整的字段级归属记录、审批工作流和 Webhook 投递。

问题所在

AI Agent 可以收集表单所需的_大部分_数据，但有些字段需要人工填写：签名、文件上传、身份验证、主观偏好。现有的表单工具迫使你二选一：完全自动化_或_完全手动操作。没有任何工具能处理两者之间的交接。

FormBridge 的工作方式

Agent                          FormBridge                        Human
  │                               │                                │
  ├─ POST /submissions ──────────►│  Creates draft, returns         │
  │  (fills known fields)         │  resumeToken + handoff URL      │
  │                               │                                │
  │                               │◄──── Opens link ────────────────┤
  │                               │  Pre-filled form with           │
  │                               │  attribution badges             │
  │                               │                                │
  │                               │◄──── Fills remaining fields ────┤
  │                               │◄──── Submits ──────────────────┤
  │                               │                                │
  │  ◄── Webhook delivery ───────┤  Validated, approved,           │
  │      (HMAC-signed)            │  delivered to destination       │

1. Agent 创建一份提交并填写已知字段
2. FormBridge 生成一个带轮换令牌的安全恢复 URL
3. 人工打开链接，查看预填字段及“由 Agent 填写”标记
4. 人工补全剩余字段、上传文件并提交
5. 提交内容流转至验证 → 可选审批关卡 → Webhook 投递
6. 每个字段都会记录填写者（Agent、人工或系统）及填写时间

软件包

软件包	npm	描述
@agentkitai/formbridge-mcp-server	—	核心服务 — HTTP API、MCP 工具、提交生命周期、存储后端（主软件包）
@agentkitai/formbridge-create		CLI 脚手架工具（npx @agentkitai/formbridge-create）
@agentkitai/formbridge-form-renderer		用于渲染表单和恢复由 Agent 发起的提交的 React 组件与钩子
@agentkitai/formbridge-schema-normalizer		将 Zod、JSON Schema 和 OpenAPI 规范转换为统一的 IntakeSchema IR
@agentkitai/formbridge-shared		各软件包共用的实用工具
@agentkitai/formbridge-templates		现成的收集模板（供应商入驻、IT 访问权限、客户信息收集、费用报销、错误报告）
@agentkitai/formbridge-admin-dashboard	—	用于管理信息收集、审核提交内容和配置审批的 React SPA

快速开始

安装

核心服务软件包（@agentkitai/formbridge-mcp-server）尚未发布到 npm。请从源代码安装：

git clone https://github.com/agentkitai/formbridge.git
cd formbridge
npm install
npm run build

配套软件包（@agentkitai/formbridge-create、@agentkitai/formbridge-form-renderer、@agentkitai/formbridge-schema-normalizer、@agentkitai/formbridge-shared、@agentkitai/formbridge-templates）已发布，可直接从 npm 安装。

选项 1：HTTP API 服务

import { createFormBridgeApp } from '@agentkitai/formbridge-mcp-server';
import { serve } from '@hono/node-server';

const app = createFormBridgeApp({
  intakes: [{
    id: 'contact-form',
    version: '1.0.0',
    name: 'Contact Form',
    schema: {
      type: 'object',
      properties: {
        name:    { type: 'string', title: 'Full Name' },
        email:   { type: 'string', format: 'email', title: 'Email' },
        message: { type: 'string', title: 'Message' },
      },
      required: ['name', 'email', 'message'],
    },
    destination: {
      type: 'webhook',
      name: 'Contact API',
      config: { url: 'https://api.example.com/contacts', method: 'POST' },
    },
  }],
});

serve({ fetch: app.fetch, port: 3000 });
console.log('FormBridge running on http://localhost:3000');

完整的提交生命周期：

# 1. Agent creates a submission with known fields
curl -X POST http://localhost:3000/intake/contact-form/submissions \
  -H 'Content-Type: application/json' \
  -d '{
    "actor": { "kind": "agent", "id": "gpt-4" },
    "idempotencyKey": "req_abc123",
    "initialFields": { "name": "John Doe", "email": "[email protected]" }
  }'
# → { ok: true, submissionId: "sub_...", resumeToken: "rtok_...", state: "draft" }

# 2. Human completes remaining fields via resume token
curl -X PATCH http://localhost:3000/intake/contact-form/submissions/sub_.../fields \
  -H 'Content-Type: application/json' \
  -d '{
    "resumeToken": "rtok_...",
    "actor": { "kind": "human", "id": "user-1" },
    "fields": { "message": "I'd like to learn more about your product." }
  }'

# 3. Submit the completed form
curl -X POST http://localhost:3000/intake/contact-form/submissions/sub_.../submit \
  -H 'Content-Type: application/json' \
  -d '{
    "resumeToken": "rtok_...",
    "actor": { "kind": "human", "id": "user-1" }
  }'
# → Triggers validation, approval (if configured), and webhook delivery

选项 2：MCP 服务（适用于 AI Agent）

import { FormBridgeMCPServer } from '@agentkitai/formbridge-mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new FormBridgeMCPServer({
  name: 'my-formbridge',
  version: '1.0.0',
});

server.registerIntake({
  id: 'vendor_onboarding',
  version: '1.0.0',
  name: 'Vendor Onboarding',
  description: 'Register new vendors',
  schema: z.object({
    companyName: z.string().describe('Legal company name'),
    taxId:       z.string().describe('Tax identification number'),
    contact:     z.string().email().describe('Primary contact email'),
    w9Upload:    z.string().optional().describe('W-9 form upload (human-only)'),
  }),
  destination: {
    type: 'webhook',
    name: 'Vendor System',
    config: { url: 'https://api.example.com/vendors', method: 'POST' },
  },
});

// Each intake auto-generates 4 MCP tools:
//   vendor_onboarding__create   — Start a new submission
//   vendor_onboarding__set      — Update fields
//   vendor_onboarding__validate — Check completeness
//   vendor_onboarding__submit   — Submit for processing

const transport = new StdioServerTransport();
await server.getServer().connect(transport);

选项 3：React 表单渲染器

import { FormBridgeForm, ResumeFormPage } from '@agentkitai/formbridge-form-renderer';

// Standalone form
function ContactPage() {
  return (
    <FormBridgeForm
      schema={contactSchema}
      endpoint="http://localhost:3000"
      actor={{ kind: 'human', id: 'user-1' }}
      onSuccess={(data, submissionId) => {
        console.log('Submitted:', submissionId);
      }}
    />
  );
}

// Resume an agent-started form (pre-filled fields + attribution badges)
function ResumePage() {
  const token = new URLSearchParams(location.search).get('token');
  return (
    <ResumeFormPage
      resumeToken={token}
      endpoint="http://localhost:3000"
    />
  );
}

选项 4：CLI 脚手架

# Interactive — walks you through setup
npx @agentkitai/formbridge-create

# Non-interactive
npx @agentkitai/formbridge-create --name my-intake --schema zod --interface http,mcp

功能

核心功能

• 提交状态机 — draft → in_progress → submitted → finalized，支持配置状态转换
• 字段归属追踪 — 每个字段都会记录设置该字段的参与者（Agent、人类、系统）及时间
• 恢复令牌 — 用于交接 URL 的安全轮换令牌（每次状态变更时轮换）
• 幂等提交 — 使用相同键的重复请求会返回现有提交
• 架构规范标准化 — 接受 Zod 架构、JSON Schema 或 OpenAPI 规范作为输入

协作

• 混合模式表单 — Agent 填写能够填写的内容，人类完成其余部分
• 条件字段 — 根据其他字段的值显示或隐藏字段（动态架构）
• 多步向导 — 通过步骤指示器和导航逐步展示内容
• 文件上传协议 — 通过签名 URL 协商安全处理文件（兼容 S3）

生产环境

• 审批关卡 — 可配置的审核工作流；提交内容会暂停，直到获批或被拒绝
• Webhook 投递 — 采用 HMAC 签名的负载，支持指数退避和投递追踪
• 事件流 — 以仅追加方式记录每次状态变更、字段更新和操作的审计轨迹
• 身份验证与 RBAC — API 密钥身份验证、OAuth 提供商、基于角色的访问控制、速率限制
• 多租户 — 通过可配置的存储和访问边界实现租户隔离
• 可插拔存储 — 内存（开发环境）、SQLite（单服务）、PostgreSQL（多副本高可用）、S3（文件上传）

开发者体验

• MCP Server — 根据收集定义自动生成 MCP 工具，以便与 AI Agent 集成
• 管理仪表板 — 用于管理收集表单、审核提交内容和查看分析数据的 React SPA
• CLI 脚手架 — npx @agentkitai/formbridge-create 可生成开箱即用的项目
• 5 个入门模板 — 供应商入驻、IT 访问申请、客户信息收集、费用报告、错误报告
• VitePress 文档 — API 参考、指南、演练教程和概念文档
• CI/CD — 使用 GitHub Actions 在 Node 18/20/22 上运行 lint、类型检查和测试

API 参考

端点

方法	路径	描述
GET	/health	健康检查
GET	/intake/:id/schema	获取收集表单架构
POST	/intake/:id/submissions	创建提交
GET	/intake/:id/submissions/:subId	获取提交
PATCH	/intake/:id/submissions/:subId	更新字段
POST	/intake/:id/submissions/:subId/submit	提交
GET	/submissions/:subId/events	获取事件流
POST	/submissions/:subId/approve	批准提交
POST	/submissions/:subId/reject	拒绝提交
POST	/intake/:id/submissions/:subId/uploads	请求文件上传 URL
POST	/intake/:id/submissions/:subId/uploads/:uploadId/confirm	确认文件上传
GET	/submissions/:subId/deliveries	列出某个提交的 webhook 投递记录
GET	/webhooks/deliveries/:deliveryId	获取单条 webhook 投递记录
GET	/analytics/summary	提交分析摘要
GET	/analytics/volume	随时间变化的提交量
GET	/analytics/funnel	按状态划分的提交漏斗
GET	/analytics/intakes	各收集表单的指标

提交状态

draft → in_progress → submitted → finalized
          │  ↘ awaiting_upload
          ↘ needs_review → approved → submitted/finalized
                        ↘ rejected

• draft — 刚创建，正在由 Agent 和/或人工填写
• in_progress — 正在设置字段
• awaiting_upload — 等待文件上传完成
• submitted — 所有必填字段均已填写，等待审核（或自动批准）
• needs_review — 暂停在审批节点，等待审核者决定
• approved — 已通过审批节点
• rejected — 被审核者拒绝（终态）
• finalized — 已完成并交付至目标位置（终态）
• cancelled / expired — 已取消或因 TTL 过期而终止的状态

存储后端

FormBridge 支持多种存储后端，通过 FORMBRIDGE_STORAGE 环境变量进行选择。

后端	值	用途	依赖项
内存	memory（默认）	开发、测试	无
SQLite	sqlite	单服务器生产环境	better-sqlite3
PostgreSQL	postgres	多副本高可用部署	pg

PostgreSQL 配置

# Required
export FORMBRIDGE_STORAGE=postgres
export DATABASE_URL=postgresql://user:password@host:5432/formbridge

# Optional: install pg driver
npm install pg

import { PostgresStorage } from '@agentkitai/formbridge-mcp-server';

const storage = new PostgresStorage({
  connectionString: process.env.DATABASE_URL!,
  maxConnections: 20,        // default: 10
  idleTimeoutMillis: 30000,  // default: 30000
});
await storage.initialize(); // runs migrations automatically

// Or use the factory:
import { createStorageFromEnv } from '@agentkitai/formbridge-mcp-server';
const storage = await createStorageFromEnv(); // reads FORMBRIDGE_STORAGE + DATABASE_URL

PostgreSQL 架构使用适当的 Postgres 类型：ID 使用 UUID，结构化数据使用 JSONB，时间戳使用 TIMESTAMPTZ。迁移文件位于 migrations/001_init.sql。

架构

┌──────────────────────────────────────────────────────────┐
│                     FormBridge Core                       │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │   Intake     │  │  Submission  │  │   Approval     │  │
│  │  Registry    │  │   Manager    │  │   Manager      │  │
│  └─────────────┘  └──────────────┘  └────────────────┘  │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │   Event      │  │   Webhook    │  │   Condition    │  │
│  │   Store      │  │   Manager    │  │   Evaluator    │  │
│  └─────────────┘  └──────────────┘  └────────────────┘  │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │              Storage Layer                           │ │
│  │  Memory (dev) │ SQLite (prod) │ S3 (file uploads)   │ │
│  └─────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌──────────────────┐  ┌──────────────────────────────┐  │
│  │   HTTP API        │  │   MCP Server                 │  │
│  │   (Hono)          │  │   (Stdio + SSE transports)   │  │
│  └──────────────────┘  └──────────────────────────────┘  │
│                                                          │
│  ┌──────────────────┐  ┌──────────────────────────────┐  │
│  │   Auth / RBAC     │  │   Rate Limiting              │  │
│  │   Multi-tenancy   │  │   CORS                       │  │
│  └──────────────────┘  └──────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

┌────────────────────┐  ┌────────────────────────────────┐
│  React Form        │  │  Admin Dashboard               │
│  Renderer          │  │  (React SPA)                   │
└────────────────────┘  └────────────────────────────────┘

┌────────────────────┐  ┌────────────────────────────────┐
│  CLI Scaffolding   │  │  Schema Normalizer             │
│  (create-formbridge)│  │  (Zod/JSONSchema/OpenAPI → IR) │
└────────────────────┘  └────────────────────────────────┘

项目结构

src/
  auth/           # API key auth, OAuth, RBAC, rate limiting, tenant isolation
  core/           # Business logic — submission manager, approval gates, events,
                  #   state machine, condition evaluator, webhook delivery
  mcp/            # MCP server, tool generator, stdio + SSE transports
  middleware/     # Hono middleware (CORS, error handling)
  routes/         # HTTP route handlers (submissions, approvals, uploads, events,
                  #   webhooks, analytics, health)
  storage/        # Storage backends (memory, SQLite, S3) + migration utility
  types/          # TypeScript types and intake contract spec

packages/
  admin-dashboard/    # React SPA — intake management, submission review, analytics
  create-formbridge/  # CLI tool — interactive + non-interactive project scaffolding
  form-renderer/      # React components — FormBridgeForm, ResumeFormPage, WizardForm
  schema-normalizer/  # Converts Zod, JSON Schema, OpenAPI → unified IntakeSchema IR
  shared/             # Shared utilities across packages
  templates/          # 5 starter templates with full schema definitions
  demo/               # Demo app with sample intakes and pre-configured workflows

docs/               # VitePress documentation site
tests/              # 1,427 tests across 59 files
.github/workflows/  # CI (lint + typecheck + tests on Node 18/20/22) + release

开发

# Install dependencies
npm install

# Run all 1,427 tests
npm run test:run

# Watch mode
npm test

# Type checking (zero errors)
npm run typecheck

# Lint (ESLint flat config v9)
npm run lint

# Build
npm run build

# Run the demo app
cd packages/demo && npm run dev

测试

测试套件涵盖：

• 核心逻辑 — 提交生命周期、状态机转换、审批工作流、字段归属
• API 端点 — 对所有路由进行完整的 HTTP 请求/响应测试
• MCP server — 工具生成、服务初始化、传输处理
• 存储后端 — 内存、SQLite 和 S3 存储及边界情况
• CLI 脚手架 — CLI 端到端测试（交互式和非交互式）
• 架构规范化 — Zod、JSON Schema 和 OpenAPI 转换
• 条件评估 — 动态字段可见性规则
• Webhook 投递 — HMAC 签名、重试逻辑、投递跟踪

1,427 tests passing across 59 test files

（两个上传路径测试会断言使用 POSIX / 分隔符，因此在 Windows 上会失败；它们在 Linux/macOS 上通过，CI 也在这些系统上运行。）

路线图

• 发布 npm 软件包（5 个软件包已上线 npm）
• PostgreSQL 存储后端
• 实时协作（WebSocket 字段锁定）
• 为待处理的审批发送邮件通知
• 带图表的表单分析仪表板
• 托管云版本

贡献

欢迎贡献！请先提交 issue，讨论您想要进行的更改。

git clone https://github.com/agentkitai/formbridge.git
cd formbridge
npm install
npm run test:run   # All tests pass
npm run typecheck  # Zero errors
npm run lint       # Clean

🧰 AgentKit 生态系统

项目	描述
AgentLens	AI Agent 的可观测性与审计跟踪
Lore	跨 Agent 记忆与经验分享
AgentGate	人机协同审批网关
FormBridge	Agent 与人类混合模式表单	⬅️ 您正在这里
AgentEval	测试与评估框架
agentkit-cli	统一的 CLI 编排工具

许可证

MIT © 2026 Amit Paz