名称： tally
版本： 1.0.0
描述： 通过 API 创建和编辑 Tally 表单。适用于以编程方式构建调查、反馈表或问卷。支持所有问题类型，包括文本输入、单选、多选、评分（通过变通方法）等。

Tally Forms API

通过 Tally.so 的 REST API 以编程方式创建和编辑表单。

身份验证

TALLY_KEY=$(cat ~/.config/tally/api_key)

接口端点

块结构

Tally 表单由块构成。每个问题需要多个共享相同 groupUuid 的块组合：

{
  "uuid": "q1-title",
  "type": "TITLE",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["问题文本", [["tag", "span"]]]]
  }
},
{
  "uuid": "q1-input",
  "type": "INPUT_TEXT",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {"isRequired": true}
}

关键点： TITLE 块和输入块必须共享相同的 groupUuid。

块类型

结构块

• FORM_TITLE - 表单标题和提交按钮
• TEXT - 段落文本
• HEADING_1, HEADING_2, HEADING_3 - 章节标题
• TITLE - 问题标签（位于 QUESTION 分组内）
• DIVIDER - 分隔线

输入块

• INPUT_TEXT - 短文本
• INPUT_NUMBER - 数字
• INPUT_EMAIL - 邮箱
• INPUT_DATE - 日期选择器
• INPUT_PHONE_NUMBER - 电话号码
• TEXTAREA - 长文本

选择块

• MULTIPLE_CHOICE_OPTION - 单选（groupType: MULTIPLE_CHOICE）
• CHECKBOX - 多选（groupType: CHECKBOXES）
• DROPDOWN_OPTION - 下拉选项

⚠️ 通过 API 渲染不佳的类型

• RATING - 星标评分无法显示
• LINEAR_SCALE - 线性量表无法显示

变通方案： 使用带星号表情符号的 MULTIPLE_CHOICE_OPTION。

示例

表单标题

{
  "uuid": "title-001",
  "type": "FORM_TITLE",
  "groupUuid": "group-title",
  "groupType": "FORM_TITLE",
  "payload": {
    "title": "我的调查",
    "button": {"label": "提交"}
  }
}

章节标题

{
  "uuid": "sec1-head",
  "type": "HEADING_2",
  "groupUuid": "group-sec1",
  "groupType": "TEXT",
  "payload": {
    "safeHTMLSchema": [["📊 章节标题", [["tag", "span"]]]]
  }
}

文本输入问题

{
  "uuid": "q1-title",
  "type": "TITLE",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["你的名字是？", [["tag", "span"]]]]
  }
},
{
  "uuid": "q1-input",
  "type": "INPUT_TEXT",
  "groupUuid": "group-q1",
  "groupType": "QUESTION",
  "payload": {"isRequired": true}
}

单选题

{
  "uuid": "q2-title",
  "type": "TITLE",
  "groupUuid": "group-q2",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["你从哪里听说我们？", [["tag", "span"]]]]
  }
},
{
  "uuid": "q2-opt1",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q2",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 0, "isFirst": true, "isLast": false, "text": "社交媒体"}
},
{
  "uuid": "q2-opt2",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q2",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 1, "isFirst": false, "isLast": true, "text": "朋友推荐"}
}

多选题

{
  "uuid": "q3-title",
  "type": "TITLE",
  "groupUuid": "group-q3",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["你对哪些功能感兴趣？", [["tag", "span"]]]]
  }
},
{
  "uuid": "q3-cb1",
  "type": "CHECKBOX",
  "groupUuid": "group-q3",
  "groupType": "CHECKBOXES",
  "payload": {"index": 0, "isFirst": true, "isLast": false, "text": "功能 A"}
},
{
  "uuid": "q3-cb2",
  "type": "CHECKBOX",
  "groupUuid": "group-q3",
  "groupType": "CHECKBOXES",
  "payload": {"index": 1, "isFirst": false, "isLast": true, "text": "功能 B"}
}

评分量表（使用星号的变通方案）

{
  "uuid": "q4-title",
  "type": "TITLE",
  "groupUuid": "group-q4",
  "groupType": "QUESTION",
  "payload": {
    "safeHTMLSchema": [["你如何评价我们的服务？", [["tag", "span"]]]]
  }
},
{
  "uuid": "q4-opt1",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 0, "isFirst": true, "isLast": false, "text": "⭐ 差"}
},
{
  "uuid": "q4-opt2",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 1, "isFirst": false, "isLast": false, "text": "⭐⭐ 一般"}
},
{
  "uuid": "q4-opt3",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 2, "isFirst": false, "isLast": false, "text": "⭐⭐⭐ 好"}
},
{
  "uuid": "q4-opt4",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 3, "isFirst": false, "isLast": false, "text": "⭐⭐⭐⭐ 很好"}
},
{
  "uuid": "q4-opt5",
  "type": "MULTIPLE_CHOICE_OPTION",
  "groupUuid": "group-q4",
  "groupType": "MULTIPLE_CHOICE",
  "payload": {"isRequired": true, "index": 4, "isFirst": false, "isLast": true, "text": "⭐⭐⭐⭐⭐ 极好"}
}

更新命令

TALLY_KEY=$(cat ~/.config/tally/api_key)

# 先备份
curl -s "https://api.tally.so/forms/{ID}" \
  -H "Authorization: Bearer $TALLY_KEY" > /tmp/backup.json

# 更新
curl -s "https://api.tally.so/forms/{ID}" \
  -X PATCH \
  -H "Authorization: Bearer $TALLY_KEY" \
  -H "Content-Type: application/json" \
  -d @/tmp/form.json

# 验证
curl -s "https://api.tally.so/forms/{ID}" \
  -H "Authorization: Bearer $TALLY_KEY" | jq '.blocks | length'

最佳实践

1. 修改前务必备份表单
2. 使用描述性 UUID（如 q1-title, q1-input, sec1-head）
3. 章节标题： 使用小写并添加表情符号前缀（例如：📊 通用反馈）
4. 对于评分： 使用带 ⭐ 表情符号的 MULTIPLE_CHOICE 类型，而非 RATING 类型
5. 更新后验证： 检查块数量是否符合预期