内容
# Form.io 智能编码工具集 <!-- omit from toc -->
[](https://github.com/formio/ai/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@formio/ai)
[](https://www.npmjs.com/package/@formio/mcp)
[](./LICENSE)
`@formio/ai` 是 Form.io 进入智能编码环境的桥梁。它提供了一系列工具，使任何开发者都能够使用他们最喜欢的智能编码工具集（从 Claude Code 开始）对 Form.io 企业服务器执行复杂的动作。这将 Form.io 企业服务器转变为**智能应用的可组合后端**。
- [快速入门](#快速入门)
- [您将获得什么](#您将获得什么)
- [为什么存在](#为什么存在)
- [智能技能库](#智能技能库)
- [编排技能](#编排技能)
- [所有技能](#所有技能)
- [示例和用例](#示例和用例)
- [构建完整应用](#构建完整应用)
- [构建表单和向导](#构建表单和向导)
- [在现有应用中嵌入表单](#在现有应用中嵌入表单)
- [通过提示操作 REST API](#通过提示操作-rest-api)
- [在没有技能的情况下使用 MCP 服务器](#在没有技能的情况下使用-mcp-服务器)
- [MCP 服务器工具](#mcp-服务器工具)
- [表单](#表单)
- [角色](#角色)
- [操作](#操作)
- [项目](#项目)
- [诊断](#诊断)
- [身份验证](#身份验证)
- [登录表单自动解析](#登录表单自动解析)
- [环境变量](#环境变量)
- [贡献](#贡献)
- [许可证](#许可证)
## 快速入门
快速入门很简单。首先按照以下步骤安装 Claude Code：
1. [安装 Claude Code](https://github.com/anthropics/claude-code#get-started)
2. 在终端中运行 `claude`。
3. 在 **Claude Code** 中运行以下命令。
```bash
/plugin marketplace add https://github.com/formio/ai.git
/plugin install formio-ai@formio
```
Claude Code 在安装时提示输入 `项目网址` 和 `基准网址`。这些参数的描述如下：
- **项目网址**：这是您的“项目”的端点。如果您正在使用我们的 SaaS 环境（https://portal.form.io），则您的项目网址将是一个子域，例如 https://myproject.form.io。但是，对于大多数用例，当 Form.io 在您自己的环境中部署时，项目网址通常是一个“子目录”结构，如 https://forms.mysite.com/myproject。
- **基准网址**：这是部署的端点。如果您正在使用 SaaS 环境（https://portal.form.io），则这始终是 https://api.form.io。但是，对于大多数用例，当 Form.io 在您自己的环境中部署时，这就是部署的网址，如 https://forms.mysite.com。
## 您将获得什么
- **Claude Code 插件：`@formio/ai`。** 一键安装。包含 MCP 服务器和技能库，并与 Claude Code 注册。
- **MCP 服务器：`@formio/mcp`。** Form.io 操作（`form_*`、`role_*`、`action_*`、`project_*`）作为 MCP 工具。与任何支持 MCP 的客户端配合使用：Claude Code、Claude Desktop、VS Copilot 等。
- **技能库：** 十个可激活的技能，涵盖应用编排、表单构建（网页表单和向导）、表单嵌入、资源规划、JSON 模式编写、操作配置、身份验证和授权、`@formio/js` SDK 接口以及完整的 Form.io REST 接口。
## 为什么存在
Form.io 过去十年一直是企业数据的标准化层。随着 AI 编码代理的普及，这一标准化变得更加重要，而不是不那么重要。
**在此基础上构建，而不是从头开始。** 代理构建完整的应用程序，包括数据模型、表单、工作流和业务逻辑。Form.io 是它构建的基础平台。API、数据模式、RBAC、审计基础设施和表单管理功能都是生产级别的，并且已经存在。代理将它们用作工具来构建更好的应用程序。
**跨所有 AI 构建的应用实现标准化。** 一个模型、一套规则、一份审计跟踪，无论哪个团队或哪个代理构建它。借助标准化层，多个团队交付多个应用程序，所有这些应用程序都具有可防御的、可协调的数据层。
**内置治理。** RBAC、组权限、更改历史、审计跟踪——所有这些都在第一次传递时发出。每个应用程序都落在同一个合规范围内，企业已经在运行该范围。
## 智能技能库
该插件提供了一个可激活的技能库。Claude 根据您的请求按需加载相关技能——您很少需要显式命名一个技能。
### 编排技能
编排技能是一种特殊的技能，作为大多数提示的**入口点**。它们不涵盖单个功能，而是协调其他技能（规划、模式编写、操作、部署、框架搭建）以完成一个广泛的、自然语言的请求。 当您描述*您想要什么*而不是*使用哪个工具*时，编排技能会接管并驱动整个流程。
| 技能 | 功能 |
| --- | --- |
| `formio-application` | 框架无关的“构建我一个应用”编排器。将自然语言意图转换为由 Form.io 项目支持的运行应用程序——规划资源、导入模板并移交给框架实现者。也处理在现有应用中添加新功能。 |
| `formio-form-builder` | “构建我一个表单”编排器。从意图到模式编写再到部署中的保存表单，构建一个完整的表单——网页表单或多页向导，并具有可选的嵌入交接。也处理现有表单的字段编辑。 |
### 所有技能
| 技能 | 功能 |
| --- | --- |
| `formio-application` | 用于在 Form.io 平台上构建或扩展应用程序的编排入口点（参见上文）。 |
| `formio-form-builder` | 用于构建单个表单——网页表单或向导——的编排入口点，端到端（参见上文）。 |
| `formio-form` | 在任何 Web 应用程序中使用 `@formio/js` 渲染器嵌入和渲染 Form.io 表单——预填充、条件字段、计算值、自定义验证和条件向导页面。 |
| `formio-resource-planner` | 根据高级需求规划资源结构、字段配置和访问/权限模型，然后发出一个准备导入的 `template.json`。 |
| `formio-schema` | Form.io JSON 模式的参考——项目、表单/资源和提交的文档形状。在构造、编辑或解释任何 Form.io JSON 时使用。 |
| `formio-actions` | Form.io 操作的配置参考——电子邮件通知、身份验证、Webhook、角色分配和表单到表单保存的服务器端行为层。 |
| `formio-auth` | 身份验证和授权专家——登录/注册、RBAC、SSO（OIDC/SAML/LDAP）、Token 交换、自定义 JWT、无密码电子邮件令牌和 JWT/会话机制。 |
| `formio-api` | 全面的 Form.io REST API 参考——平台管理、项目管理、运行时和 PDF 范围内的每个端点。 |
| `formio-sdk` | `@formio/js` JavaScript SDK 和 `@formio/js/utils` 实用程序的参考——静态和实例方法、VanillaJS 渲染、插件和帮助程序。 |
| `formio-angular` | Angular 框架实现者。使用 `@formio/angular` 将批准的 `template.json` 和目标项目转换为一个可工作的 Angular 应用。由 `formio-application` 委托。 |
## 示例和用例
可在 [`examples/`](./examples/) 目录中找到可直接粘贴的示例提示——每个文件都是一个自包含的提示，附有关于它应该执行的说明。要尝试一个，请创建一个新文件夹，在其中启动 Claude Code，然后粘贴提示：
```bash
mkdir form-app
cd form-app
claude
```
### 构建完整应用
使用 `formio-application` 编排技能创建全新的“绿地”表单应用——或在现有应用中引入新的表单功能。代理规划数据模型，将其导入 Form.io 项目，并搭建前端，使用 Form.io 平台作为完整应用逻辑的可组合后端。
- [CRM 应用](./examples/apps/crm.md) — 具有所有者范围访问的客户端、交易和活动日志。
- [帮助台](./examples/apps/help-desk.md) — 客户工单、代理工作流、内部笔记和电子邮件通知。
- [故事板](./examples/apps/storyboard.md) — 具有协作人员访问的生产 → 场景 → 镜头层次结构。
***当前库仅支持为新“绿地”应用的 Angular 应用程序框架。它通常支持其他框架，使用 Vanilla JS `@formio/js` JavaScript 渲染器。其他框架的完全支持即将到来。***
### 构建表单和向导
使用 `formio-form-builder` 技能创建复杂表单和多页条件向导。代理编写表单 JSON 并自动在部署的任何阶段创建表单——包括必须遵守定义明确的外部模式的表单，例如 [FHIR](https://hl7.org/fhir)。
- [大学申请向导](./examples/forms/college-application.md) — 具有程序驱动的条件页面的多页向导。
- [符合 FHIR 的患者表单](./examples/forms/fhir-patient.md) — 符合 FHIR 患者资源的提交数据。
- [客户反馈表单](./examples/forms/customer-feedback.md) — 条件后续字段和条件电子邮件通知。
- [学生入职向导](./examples/forms/student-onboarding-embed.md) — 创建向导并在您的应用中嵌入它。
### 在现有应用中嵌入表单
使用 `formio-form` 技能在任何基于 HTML 的应用中嵌入现有表单或向导。
- [嵌入现有表单](./examples/embed/render-existing-form.md) — 使用 `@formio/js` 渲染保存的表单，预填充它并处理提交事件。
### 通过提示操作 REST API
`formio-api` 技能了解您的 Form.io 部署的完整 REST 接口——通过提示创建任何资源、表单、提交或其他实体。
- [创建患者资源](./examples/api/patient-resource.md) — 通过 MCP 服务器的一方工具创建新资源。
## 在没有技能的情况下使用 MCP 服务器
捆绑的 MCP 服务器也作为独立的 [`@formio/mcp`](https://www.npmjs.com/package/@formio/mcp) 发布——您不需要 Claude Code 插件或技能库即可使用它。任何支持 MCP 的客户端（Claude Code、Claude Desktop、Cursor、VS Code Copilot）可以直接启动服务器并调用[以下工具](#mcp-服务器工具)。
要从 Claude Code 连接而无需插件，请在项目根目录中添加一个 `.mcp.json`：
```json
{
"mcpServers": {
"formio-mcp": {
"command": "npx",
"args": ["-y", "@formio/mcp"],
"env": {
"FORMIO_BASE_URL": "https://api.form.io",
"FORMIO_PROJECT_URL": "https://your-project.form.io"
}
}
}
}
```
在独立模式下，`FORMIO_BASE_URL` 和 `FORMIO_PROJECT_URL` 是必需的环境变量（[完整列表](#环境变量)）。身份验证方式与插件模式相同：第一个身份验证的工具调用会打开浏览器门户登录流程，或者设置 `FORMIO_API_KEY` 以完全跳过浏览器。
连接后，直接提示工具——无需激活技能：
```
使用 formio-mcp 工具，显示我 Form.io 项目中的所有表单和角色，然后导出完整的项目模板并保存到 ./backup/template.json。
```
```
使用 formio-mcp form_create 工具，创建一个名为“联系我们”的新表单，包含姓名（必填）、电子邮件（必填）、主题和消息字段，以及一个提交按钮。
```
这些可以直接粘贴的版本位于 [`examples/mcp/`](./examples/mcp/) 目录中：[检查和导出项目](./examples/mcp/inspect-and-export.md) 和 [直接创建表单](./examples/mcp/create-form-direct.md)。
一个注意事项：没有技能，代理会根据自己的一般知识编写 Form.io JSON（表单模式、操作设置、访问数组），而不是技能库编码的约定——每个操作工具涵盖的仍然有效，但您会放弃防护措施。对于其他传输（用于远程客户端的 Streamable HTTP，用于 Claude Desktop 的 SSE）以及从此存储库的克隆中运行服务器，请参阅 [MCP 服务器 README](./packages/mcp-server/README.md)。
## MCP 服务器工具
捆绑的 `@formio/mcp` 服务器公开这些工具。技能优先于原始 HTTP 使用这些工具，只要操作被覆盖。
### 表单
| 工具 | 目的 |
| --- | --- |
| `form_create` | 创建新表单。使用 `formio-schema` 技能首先构建 JSON 定义。 |
| `form_get` | 按 ID 或路径获取单个表单定义。 |
| `form_list` | 列出表单，可选过滤和分页。 |
| `form_update` | 更新现有表单。先调用 `form_get`，然后使用 `formio-schema` 编辑，最后更新。 |
| `form_revisions_list` | 列出表单的不可变已发布修订摘要（_vid、_id、modified、user、_vnote）。需要启用表单修订。 |
| `form_revision_get` | 按 _vid 或修订文档 _id 获取单个不可变表单修订。 |
### 角色
| 工具 | 目的 |
| --- | --- |
| `role_create` | 创建新项目角色。 |
| `role_list` | 列出所有项目角色。 |
| `role_update` | 完全替换更新角色。包括您要保留的所有字段。 |
### 操作
| 工具 | 目的 |
| --- | --- |
| `action_types_list` | 列出服务器上可用的所有操作类型。 |
| `action_type_get` | 获取操作类型的设置模式。 |
| `action_create` | 将新操作附加到表单。 |
| `action_list` | 列出表单上的操作。 |
| `action_get` | 获取按 ID 的单个操作。 |
| `action_update` | 更新操作。 |
| `action_delete` | 从表单中分离操作。 |
### 项目
| 工具 | 目的 |
| --- | --- |
| `project_export` | 导出项目的完整模板（角色、资源、表单、操作）为可移植的 JSON 文档。在 `project_import` 之前使用以快照。 |
| `project_import` | 导入模板 JSON — 累加合并角色、资源、表单和操作。**同机器名称的项目在原地覆盖；其他项目保留。** |
| `project_set` | 仅插件模式 — 在 `~/.formio/projects.json` 中持久化每个工作目录的项目 URL 映射。独立模式下从未公开（独立服务器通过 env 绑定到 `FORMIO_PROJECT_URL`）。 |
### 诊断
| 工具 | 目的 |
| --- | --- |
| `hello` | 烟雾测试工具。返回静态问候语；用于在任何身份验证调用之前验证 MCP 连线。 |
---
## 身份验证
MCP 服务器支持两种身份验证模式：
- **JWT 模式（默认）。** 短寿命本地 Express 服务器渲染 Form.io 门户登录表单；用户一次性登录，JWT 通过 `/callback` 端点返回，`formioFetch` 在后续每个请求上附加 `x-jwt-token`。流程是隐式的——**第一个身份验证工具调用**在缓存未命中时触发它。没有显式的 `authenticate` 工具。
- **API 密钥模式。** 设置 `FORMIO_API_KEY`。所有请求都附加 `x-token`；浏览器流程完全跳过。
### 登录表单自动解析
当 `FORMIO_LOGIN_FORM` 未设置时，服务器会在第一次登录尝试时探测这些候选并缓存第一个响应的候选（每个候选 1.5 秒超时）：
1. `${FORMIO_BASE_URL}/formio/user/login`（portal-base）
2. `${FORMIO_PROJECT_URL}/admin/login`（项目管理）
3. `${FORMIO_PROJECT_URL}/user/login`（项目用户）
探测懒惰地运行——只有当实际提供本地身份验证页面时。
---
## 环境变量
| 名称 | 必需 | 默认值 | 目的 | 主机 SaaS 示例 | 自托管示例 |
| --- | :-: | --- | --- | --- | --- |
| `FORMIO_BASE_URL` | 是 | — | Form.io 部署的完整基准 URL。 | `https://api.form.io` | `https://forms.example.com` |
| `FORMIO_PROJECT_URL` | 是\* | — | Form.io 项目的完整 URL。在插件模式下，仅用于提供未映射的工作目录的预填充默认值。 | `https://myproject.form.io` | `https://forms.example.com/myproject` |
| `FORMIO_API_KEY` | 否 | `undefined` | 长期项目 API 密钥。设置后，服务器跳过浏览器登录流程。 | `CHANGEME` | `CHANGEME` |
| `FORMIO_LOGIN_FORM` | 否 | 自动解析 | 重写 JWT 登录流程使用的门户登录表单 URL。 | `https://formio.form.io/user/login` | `https://forms.example.com/formio/user/login` |
| `FORMIO_PLUGIN_CONTEXT` | 否 | `0` | 由插件清单设置。当 `1` 时，服务器启用 `project_set` 并从 `~/.formio/projects.json` 读取 `FORMIO_PROJECT_URL` 而不是环境变量。 | | |
| `FORMIO_INSECURE_TLS` | 否 | `false` | 当为 `true` 时，跳过 TLS 证书验证（设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`）——用于自托管部署，证书未经自签名验证。不要在生产环境中使用。 | — | `true` |
\* 在插件上下文中，`FORMIO_PROJECT_URL` 由 `project_set` 工具按工作目录捕获并持久化到 `~/.formio/projects.json`。`verify-project-url` `SessionStart`/`PreToolUse` 钩子提供 `formio_default_project_url`（来自插件用户配置）作为第一次进入工作区的默认值。
---
## 贡献
这是一个 pnpm + Turborepo 多模块仓库：MCP 服务器（`packages/mcp-server/`）、Claude Code 插件（`plugin/`，捆绑服务器 + 技能库）和技能测试套件（`packages/skill-tests/`）。设置、约定、作者指南和发布流程在 [CONTRIBUTING.md](./CONTRIBUTING.md) 中。安全报告： [SECURITY.md](./SECURITY.md)。
## 许可证
[MIT](./LICENSE)
