gitea_admin/su-planning-office

Fork 0

Files

T

gitea_admin 2df696c390 发布：学生会策划部工作包（Skills + MCP）

2026-09-29 12:35:04 +08:00

8.4 KiB

Raw Permalink Blame History

list_answers 工具参考

概述

获取指定问卷的回答列表，支持游标分页。返回回答总数、回答详情列表和最后一条回答 ID（用于翻页）。

参数

参数	类型	必填	说明
`survey_id`	number	是	问卷 ID
`per_page`	number	否	每页返回条数，默认 20，最大 1000
`last_answer_id`	number	否	上一页最后一条回答的 ID，用于翻页。默认 0 表示从头开始

返回值

成功响应

{
  "total": 150,
  "list": [
    {
      "id": 1,
      "survey_id": 292192,
      "answer_id": 1,
      "respondent_nickname": "用户A",
      "started_at": "2026-01-15 10:30:00",
      "ended_at": "2026-01-15 10:35:22",
      "score": 0,
      "country": "中国",
      "province": "广东",
      "city": "深圳",
      "answer": [
        {
          "id": "p1",
          "questions": [
            {
              "id": "q-1-xxxx",
              "identity": "q-1-abcd1234",
              "title": "您对工作环境是否满意？",
              "type": "radio",
              "sub_type": 0,
              "text": "非常满意",
              "options": [
                {"id": "o1", "text": "非常满意", "selected": true},
                {"id": "o2", "text": "满意"},
                {"id": "o3", "text": "一般"},
                {"id": "o4", "text": "不满意"}
              ]
            },
            {
              "id": "q2",
              "identity": "q-1-efgh5678",
              "title": "请填写您的建议",
              "type": "textarea",
              "sub_type": 0,
              "text": "希望改善食堂伙食"
            }
          ]
        }
      ]
    }
  ],
  "last_answer_id": 20
}

顶层字段

字段	类型	说明
`total`	number	问卷回答总数（全量统计，非当前页条数）
`list`	array	当前页的回答列表（`AnswerPayload[]`）
`last_answer_id`	number	当前页最后一条回答的 ID，用于请求下一页

AnswerPayload 对象

字段	类型	说明
`id`	number	回答记录 ID
`survey_id`	number	问卷 ID
`answer_id`	number	回答序号
`respondent_id`	number	答题者 ID
`respondent_nickname`	string	答题者昵称
`respondent_avatar`	string	答题者头像
`respondent_type`	string	答题者类型
`openid`	string	答题者 OpenID
`started_at`	string	开始答题时间
`ended_at`	string	提交答题时间
`score`	number	考试/测评场景下的得分
`country`	string	答题者所在国家
`province`	string	答题者所在省份
`city`	string	答题者所在城市
`ua`	string	答题者 User-Agent
`ip`	string	答题者 IP 地址
`answer`	array	回答内容（按页面分组），见下方结构说明

answer 嵌套结构

回答内容按 页面 → 题目 的层级组织：

answer[]                         ← 页面列表
├── id: "p1"                     ← 页面 ID
└── questions[]                  ← 该页面下的题目回答
    ├── id: "q1"                 ← 题目 ID
    ├── identity: "q-1-xxxx"     ← 题目唯一标识
    ├── title: "题目标题"         ← 题目标题
    ├── type: "radio"            ← 题型
    ├── text: "用户填写的内容"     ← 文本类题目的回答文本
    ├── options[]                ← 选择题的选项（含选中状态）
    ├── groups[]                 ← 矩阵题的分组回答
    └── blanks[]                 ← 填空题的填空内容

Question（回答中的题目）字段说明

字段	类型	说明
`id`	string	题目 ID
`identity`	string	题目唯一标识（如 `q-1-xxxx`）
`title`	string	题目标题
`description`	string	题目描述
`type`	string	题型（`radio`/`checkbox`/`text`/`textarea`/`star` 等）
`sub_type`	number	题目子类型
`text`	any	回答内容（文本题为填写的文字，选择题为选中选项的文本）
`options`	array	选择题的选项列表（含选中状态）
`groups`	array	矩阵题的分组回答
`blanks`	array	填空题的各填空内容
`id_list`	array	选中选项的 ID 列表
`text_list`	array	选中选项的文本列表
`signature_id`	string	手写签名 ID
`files`	array	附件题的文件列表

分页机制（重要）

list_answers 使用游标分页（Cursor-based Pagination），不是传统的 offset 分页。

工作原理

每次请求返回一页数据和 last_answer_id
将上一次返回的 last_answer_id 作为下一次请求的参数，获取下一页
数据按 answer_id 升序排列

翻页流程

# 第一页：不传 last_answer_id（默认从头开始）
list_answers(survey_id=292192)
→ { total: 150, list: [...20条...], last_answer_id: 20 }

# 第二页：传入上一页返回的 last_answer_id
list_answers(survey_id=292192, last_answer_id=20)
→ { total: 150, list: [...20条...], last_answer_id: 45 }

# 第三页
list_answers(survey_id=292192, last_answer_id=45)
→ { total: 150, list: [...20条...], last_answer_id: 78 }

# ...继续翻页...

# 最后一页：返回不足 per_page 条，翻页结束
list_answers(survey_id=292192, last_answer_id=135)
→ { total: 150, list: [...10条...], last_answer_id: 150 }

判断是否还有下一页

条件	含义
`list.length == per_page`	可能还有下一页，继续用 `last_answer_id` 翻页
`list.length < per_page`	已到最后一页，无需继续翻页
`list` 为空数组	没有更多数据

⚠️ 注意：total 是问卷回答总数，不是当前页的条数。判断翻页是否结束，应该看 list.length 是否小于 per_page，而不是看 total。

获取全部回答的伪代码

all_answers = []
last_id = 0

while True:
    result = list_answers(survey_id=292192, per_page=100, last_answer_id=last_id)
    all_answers.extend(result.list)
    
    if len(result.list) < 100:  # 不足一页，已到末尾
        break
    
    last_id = result.last_answer_id

print(f"共 {result.total} 条回答，已全部获取 {len(all_answers)} 条")

调用示例

获取首页回答

list_answers(survey_id=292192)

指定每页条数

list_answers(survey_id=292192, per_page=50)

翻页获取下一页

list_answers(survey_id=292192, per_page=50, last_answer_id=45)

mcporter 调用

# 获取首页（默认 20 条）
mcporter call tencent-survey.list_answers --args '{"survey_id": 292192}'

# 每页 100 条
mcporter call tencent-survey.list_answers --args '{"survey_id": 292192, "per_page": 100}'

# 翻页
mcporter call tencent-survey.list_answers --args '{"survey_id": 292192, "per_page": 100, "last_answer_id": 45}'

错误码

error.type	错误描述	解决方案
`invalid_auth_status`	权限类型错误	检查 Token 权限
`claim_error`	权限校验错误	问卷不属于当前 Token 绑定的团队
`invalid_argument`	参数校验不通过	检查 survey_id 是否正确
`get_answers_error`	获取回答列表错误	确认 survey_id 正确且问卷存在

注意事项

游标分页：使用 last_answer_id 翻页，不支持跳页；必须按顺序逐页获取
需要循环翻页：如果回答数量多于 per_page，必须循环调用直到获取完所有数据
per_page 上限 1000：即使传入大于 1000 的值，也会被截断为 1000
total 是全量统计：total 字段表示问卷回收的总回答数，不随分页变化
answer 嵌套结构：每条回答的 answer 字段按 页面 → 题目 嵌套，需要递归解析
题目回答内容：不同题型的回答内容存储方式不同（text / options / blanks / groups），需根据 type 字段判断

Annotations（工具注解）

注解	值	说明
`readOnlyHint`	true	只读操作，不修改任何数据
`destructiveHint`	false	非破坏性操作
`idempotentHint`	true	幂等操作，多次调用结果一致
`openWorldHint`	false	内部调用

8.4 KiB Raw Permalink Blame History Unescape Escape

list_answers 工具参考

概述

参数

返回值

成功响应

顶层字段

AnswerPayload 对象

answer 嵌套结构

Question（回答中的题目）字段说明

分页机制（重要）

工作原理

翻页流程

判断是否还有下一页

获取全部回答的伪代码

调用示例

获取首页回答

指定每页条数

翻页获取下一页

mcporter 调用

错误码

注意事项

Annotations（工具注解）

8.4 KiB

Raw Permalink Blame History