PHP 对话收集数据!NeuronAI 引入 AIForm

为 NeuronAI 引入 AIForm

在构建开源框架的过程中，最有趣的事情之一就是：社区往往比你自己更早知道下一步应该做什么。当我开始开发 Neuron AI 时，我对核心基础组件已经有相当清晰的构想：Agent、Tool、工作流、结构化输出等。但我没有完全预料到的是，开发者们会如此迅速地将这些基础组件推向非常具体且实用的场景。通过 GitHub 和通讯订阅收到的功能请求和问题，往往是我了解真实世界中 PHP 开发者实际需求的最真实信号。

过去几个月里，有一个请求反复以不同形式出现：如何使用 Neuron AI 通过对话而不是传统表单来从用户那里收集信息？ 具体场景各不相同——有时是注册流程，有时是支持工单录入，有时是预约助手——但底层需求完全一致。人们尝试在 Agent 和工作流组件之上自己实现这个功能，虽然能跑通，但需要编写大量繁琐的胶水代码。

因此，今天正式发布 AIForm ，这是一个专门用于解决上述场景的 Neuron AI 组件。

AIForm 的功能

它的设计思路非常直接。你使用熟悉的 #[SchemaProperty] 属性定义想要收集的数据结构（就像 Neuron AI 的结构化输出系统一样），并在需要时附加验证规则。

然后继承 AIForm 类，配置好 Provider 即可。剩下的全部由组件自动处理：管理多轮对话、跟踪已收集的字段、在验证失败时重试，并在所有数据就绪后调用你的回调函数。

classRegistrationData{#[SchemaProperty(description: 'User full name', required: true)]#[NotBlank]public string $name;#[SchemaProperty(description: 'Email address', required: true)]#[Email]public string $email;#[SchemaProperty(description: 'Phone number')]public ?string $phone = null;}

classRegistrationFormextendsAIForm{protected string $formDataClass = RegistrationData::class;protectedfunctionprovider(): AIProviderInterface{returnnew Anthropic(            key: env('ANTHROPIC_API_KEY'),            model: env('ANTHROPIC_MODEL'),        );    }protectedfunctioncallback(): mixed{returnfunction(RegistrationData $data){$this->userService->register($data);        };    }}

在控制器中，你只需将每条用户消息传入表单实例处理，即可获得当前状态对象，其中包含状态、完成百分比、缺失字段等信息，用于驱动前端 UI。

$form = RegistrationForm::make()    ->setChatHistory(new FileChatHistory("/tmp/chats/{$sessionId}"));$handler = $form->process(new UserMessage($request->input('message')));$state = $handler->run();return response()->json(['status'          => $state->getStatus()->value,'message'         => $handler->getLastResponse(),'completion'      => $state->getCompletionPercentage(),'missing_fields'  => $state->getMissingFields(),'is_complete'     => $form->isComplete(),]);

确认步骤

在开发过程中，我们发现一个重要问题：当所有必填数据收集完毕，但在执行回调之前，应该如何处理？在注册、预约、结账等真实流程中，通常需要让用户再次查看已收集的信息并进行确认。

AIForm 通过 requireConfirmation() 方法优雅地解决了这个问题。它会让工作流抛出一个 FormInterruptRequest 中断，而不是立即提交。你可以将这个中断序列化保存到 Session 中，向用户展示 AI 生成的摘要，然后根据用户的回复恢复工作流。

如果用户确认，回调函数才会执行；如果用户想修改某项，表单会自动回到数据收集模式。

$form = RegistrationForm::make()->requireConfirmation();$handler = $form->process(new UserMessage($request->input('message')));$state = $handler->run();if ($handler->getInterrupt() instanceof FormInterruptRequest) {    $_SESSION['form_interrupt'] = serialize($handler->getInterrupt());// 将 AI 生成的摘要返回给用户}// 下一次请求时恢复流程：$interrupt = unserialize($_SESSION['form_interrupt']);$handler = $form->process(new UserMessage($request->input('message')), $interrupt);

这一机制基于 Neuron AI v2 工作流中引入的回路（human-in-the-loop）中断功能，如果你之前使用过，模式会非常熟悉。

为什么看起来更重要

初次看到 AIForm 时，人们很容易把它理解为“给表单套了一个聊天机器人外壳”。这种第一印象虽然合理，但并未完全抓住重点。更重要的是，它能自然地处理那些不按常规填写表单的用户：他们会跳过可选字段、输错邮箱、乱序回答问题，或者因为界面过于死板而中途放弃。对话式流程能自然地应对所有这些情况——AI 会提出跟进问题，用通俗语言说明验证错误，并在多轮对话中自动维护状态，而你无需自己编写任何相关逻辑。

另一个不太明显的优势体现在移动端和语音交互场景中，冗长的传统表单在这些环境下使用体验极差。如果你的 PHP 应用已经有 API 层和前端消费接口，那么将 AIForm 接入控制器后，你就获得了一个对话端点，可以对接任何界面，包括那些不以键盘输入为主的交互方式。

基于现有技术栈构建

AIForm 在底层是一个 Neuron AI 工作流，因此它继承了工作流系统提供的所有能力，包括原生的 Inspector 集成。只要你在环境中设置了 INSPECTOR_INGESTION_KEY，每一次表单对话都会完整出现在 Inspector 仪表盘中，包含完整的执行时间线。这在生产环境中非常重要——当对话卡住或验证循环出现异常时，你可以精确地看到发生了什么。

该组件已在 GitHub 上开源，仓库地址为 neuron-core/ai-form。安装命令：

composer require neuron-ai/ai-form

AIForm 所依赖的结构化输出系统和工作流组件文档，请访问 docs.neuron-ai.dev。