ambleloft

用 Skill 在聊天中展示表单

把声明式表单随插件交付:本页说明清单登记和打包。若只需要独立 skill 的聊天表单,从声明式业务表单教程开始。

实践指南

完成后:在聊天中触发 Skill,看到声明的表单。

前置条件:按本页具体步骤准备所需文件与工具;学习路线中的上一页不自动构成依赖。

本页内容

01选择交付方式

插件是接入业务 Operation 的交付方式;独立 skill 可以直接导入并使用 chat 提交,不要求创建插件。

先创建独立业务表单

02前置条件与文件位置

先完成默认脚手架构建安装。在项目中新建 skills/intake/ 目录。这里使用单步 chat 提交,不调用业务写操作。若要直接运行现成版本,可用 declarative-intake 案例。

打开完整可运行案例

03声明 Skill 目录

在 extension.json 顶层合并 skills 数组。它列出包含 SKILL.md 的目录,不是 YAML 文件路径。保留已有 operations 和 contributes。

extension.json · merge fragment
"skills": ["skills/intake"]

04编写 Skill

description 说明什么时候使用;正文说明如何使用工具与等待用户。amble-form-ref 将 Skill 关联到包内模板,path 相对当前 SKILL.md 所在目录。它不是任意 Markdown 链接。

skills/intake/SKILL.md
---
name: team-intake
description: Collect a team plan with a form in chat.
---
When the user wants to submit a team plan, call forms_list.
Select team-intake from this extension, then call forms_present.
Wait for the user to fill and confirm the form.
Do not claim a business record has been created.

```amble-form-ref
path: intake.yaml
```

05定义表单

保存以下完整文件。字段 name 是模板内的稳定标识;required 要求输入;submit.kind: chat 将确认后的内容发送到当前聊天,不创建后端记录。

skills/intake/intake.yaml
version: 1
id: team-intake
title: Team plan
description: Review your information before sending.
fields:
  - name: title
    type: text
    label: Plan name
    required: true
    maxLength: 120
  - name: people
    type: number
    label: Participants
    integer: true
    minimum: 1
    maximum: 100
    required: true
  - name: confirmed
    type: checkbox
    label: I have checked this information
    required: true
submit:
  kind: chat
  label: Confirm and send

06把 Skill 与 YAML 一起打包

在 build.cjs 的异步函数中、output 创建之后加入下列复制语句。保持目录结构;只复制 SKILL.md 会造成模板不可发现。然后重新构建、校验、打包并安装。

build.cjs · insert inside async function
await fs.cp(path.join(root, 'skills'),
  path.join(output, 'skills'), { recursive: true });

07在聊天中验收

新建对话并请求「使用 team-intake 表单收集团队计划」。模型需支持工具调用。预期:Agent 发现模板 → 宿主展示表单 → 空必填项阻止提交 → 用户确认后内容进入聊天。若没出现,先查已安装包的 skills 路径和模板引用,再查扩展启用/信任与模型工具调用。

08下一步:连接业务操作

forms_list / forms_present 属于 Agent 工具,不能在后端 import 一个 forms API 来调用。需要持久化业务记录时,使用声明式 operation 提交并实现幂等与恢复。

实现多步业务表单

检查结果与排错

在聊天中触发 Skill,看到声明的表单。

按本页的验证步骤核对实际结果。涉及业务服务时,分别检查界面提交、工具回执与服务端记录。

打开错误代码与排错 →
SDK / CLI 0.1.0-alpha.9 · 接口基线 兼容性与预览说明 · 案例源码