Human-in-the-Loop

一个请求，完成一次 人工确认

通过 API 发起请求，Ask4Me 把交互链接推送到通知渠道。你在手机或浏览器里点按钮、输入文字或提交表单，原始 HTTP 长连接拿到最终结果。

Terminal - 一个请求示例 
curl -sS --max-time 120 \
  -X POST '' \
  -H 'Authorization: Bearer change-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Ask4Me Demo",
    "body": "请点一个按钮回复。",
    "mcd": ":::buttons\n- [OK](ok)\n- [Later](later)\n:::"
  }'
{
  "request_id": "req_xxx",
  "last_event_type": "user.submitted",
  "data": { "action": "ok", "text": "" },
  "last_event_id": "evt_xxx"
}

快速使用

nonStream 是默认模式：不带 stream=true 时，/v1/ask 会一直等待用户提交或请求过期，然后一次性返回 JSON。

建议：请提供 mcd 或 jsonforms.schema，这样交互页才有按钮、输入框或表单可提交。

POST 裸请求

POST with MCD buttons 
curl -sS --max-time 120 \
  -X POST '' \
  -H 'Authorization: Bearer change-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Ask4Me Demo",
    "body": "请选择一个动作。",
    "mcd": ":::buttons\n- [OK](ok)\n- [Later](later)\n:::",
    "expires_in_seconds": 600
  }'

GET 裸请求

如果环境不方便设置 Authorization header，可以用 GET 并在 URL 上带 key。

GET with query params 
curl -sS --max-time 120 -G '' \
  --data-urlencode 'key=change-me' \
  --data-urlencode 'title=Ask4Me Demo' \
  --data-urlencode 'body=请点一个按钮回复。' \
  --data-urlencode $'mcd=:::buttons\n- [OK](ok)\n- [Later](later)\n:::'
安全提示：URL 参数可能被代理或日志记录；能用 POST + Authorization 时优先用 POST。

API 用法

续接等待

当客户端超时后，可以用同一个 request_id 再请求一次，继续等待或取回终态结果。

Resume after timeout 
curl -sS --max-time 40 -G '' \
  --data-urlencode 'key=change-me' \
  --data-urlencode 'request_id=req_xxx'

SSE 备用模式

需要实时拿到 request.created 和后续事件流时，使用 stream=true。

SSE stream 
curl -N -sS \
  -X POST '' \
  -H 'Authorization: Bearer change-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Ask4Me",
    "body": "Please respond.",
    "mcd": ":::buttons\n- [OK](ok)\n:::"
  }'

SSE 输出格式为 data: <Event JSON>\n\n，结束标记为 data: [DONE]\n\n。响应头会带 X-Ask4Me-Request-Id。

终态事件

事件含义
user.submitted用户点击按钮、提交输入或提交表单
request.expired请求到期仍未提交
notify.failed通知发送失败，通常是通知渠道不可用或返回错误

MCD 语法

MCD 是交互控件描述。它会在交互页里渲染按钮和输入框。

Buttons 块

MCD Buttons 
:::buttons
- [OK](ok)
- [Later](later)
:::

Input 行

MCD Input 
:::input name="note" label="补充说明" submit="提交"
:::

按钮结果

用户点击按钮后，提交值会出现在终态结果的 data.action。

输入结果

用户提交输入后，文本会出现在终态结果的 data.text。

混合使用

按钮和输入框可以同时出现；任一提交都会完成这次交互。

JSON Forms

需要更复杂的表单时，POST JSON 里提供 jsonforms.schema。当提供 jsonforms.schema 时，交互页会渲染表单并忽略 mcd。

JSON Forms POST 
curl -sS --max-time 120 \
  -X POST '' \
  -H 'Authorization: Bearer change-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "JSON Forms Demo",
    "body": "请填写表单。",
    "jsonforms": {
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "minLength": 1 },
          "age": { "type": "integer", "minimum": 0 }
        },
        "required": ["name"]
      },
      "uischema": {
        "type": "VerticalLayout",
        "elements": [
          { "type": "Control", "scope": "#/properties/name" },
          { "type": "Control", "scope": "#/properties/age" }
        ]
      },
      "data": { "age": 18 },
      "submit_label": "提交"
    },
    "expires_in_seconds": 600
  }'

表单提交后，终态事件 user.submitted 的 data 会包含 payload。

{
  "action": "",
  "text": "",
  "payload": { "name": "Alice", "age": 18 }
}

扩展用法

可折叠分组

在 Group 的 options 中设置 collapsible: true，可把一组字段放进折叠区。

长文本说明

Label 支持 maxHeight、collapsible 和 markdown: true，适合展示长说明。

只读长文本

Control 设置 readonlyBlock: true 后，可把字符串字段显示为不可编辑的滚动块。

JavaScript SDK 与 CLI

JavaScript SDK

SDK 默认使用 SSE 模式，适合在程序里实时消费事件。

SDK Example 
npm i ask4me-sdk

import { ask } from "ask4me-sdk";

const endpoint = "";
const apiKey = "change-me";

const { requestId, result } = await ask({
  endpoint,
  apiKey,
  payload: {
    title: "Ask4Me Demo",
    body: "请随便点一个按钮或回一段话。",
    mcd: ":::buttons\n- [OK](ok)\n- [Later](later)\n:::"
  },
  onEvent: (ev) => process.stdout.write(`${JSON.stringify(ev)}\n`)
});

console.log("request_id:", requestId);
console.log("final:", result);

CLI

CLI Usage 
npm i -g ask4me-cli

ask4me-cli -h  -k change-me \
  --title 'Ask4Me' --body '请回复确认。'