gitea_admin/su-planning-office
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
gitea_admin
2026-09-29 12:35:04 +08:00
commit 2df696c390
147 changed files with 50777 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/tencent-survey/references/auth.md
+103
View File
@@ -0,0 +1,103 @@
# 腾讯问卷鉴权检查
## 何时需要鉴权
- **会话首次调用工具前**：执行一次鉴权检查
- **鉴权通过后**：同一会话内后续调用**无需重复检查**，直接调用工具即可
- **按需重试**：仅当工具调用返回以下鉴权错误时，才需重新执行鉴权流程：
- `invalid_token` / `invalid token`
- `token expired`
- `missing_token`
- `invalid_token_prefix`
腾讯问卷授权流程，**必须按以下步骤执行**：
## 快速配置：通过环境变量传入 Token
如果已有 Token，可通过 `TENCENT_SURVEY_TOKEN` 环境变量直接完成配置，跳过 OAuth 授权：
```bash
TENCENT_SURVEY_TOKEN=xxx bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth
```
| 输出 | 处理方式 |
|------|---------|
| `READY` | ✅ Token 已写入配置，直接执行用户任务 |
| `ERROR:invalid_token_prefix` | Token 格式错误，必须以 `wjpt_` 开头 |
| `ERROR:save_token_failed` | Token 写入配置失败 |
> 设置了 `TENCENT_SURVEY_TOKEN` 时，脚本会优先使用该 Token，不再发起 OAuth 流程。
## 第一步：检查状态（立即返回）
未设置 `TENCENT_SURVEY_TOKEN` 时，进入标准 OAuth 设备授权流程：
```bash
bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth
```
> `${SKILL_DIR}` 为当前 skill 所在目录路径（即 `setup.sh` 所在目录）。
| 输出 | 处理方式 |
|------|---------|
| `READY` | ✅ 直接执行用户任务，**无需第二步** |
| `NONCE:<nonce>` | 记录 nonce 值，用于展示给用户（在 `AUTH_REQUIRED` 之前输出） |
| `AUTH_REQUIRED:<url>` | **立即**向用户展示授权链接（见下方模板），**然后执行第二步** |
| `ERROR:*` | 告知用户对应错误 |
## 第二步：等待授权完成（仅 AUTH_REQUIRED 时执行）
**展示授权链接后**，立即执行：
```bash
bash "${SKILL_DIR}/setup.sh" wj_wait_auth
```
| 输出 | 处理方式 |
|------|---------|
| `TOKEN_READY:ok` | ✅ 授权成功，Token 已写入配置，继续执行用户任务 |
| `AUTH_TIMEOUT` | 告知用户：「授权超时，请重新发起请求。」 |
| `ERROR:*` | 告知用户对应错误，请重新发起请求 |
## 第三步：人工兜底（前两步都失败的情况）
🔑 **手动获取 Token**：访问 [https://wj.qq.com/claw](https://wj.qq.com/claw) 登录后创建 Token，再通过环境变量配置：
```bash
TENCENT_SURVEY_TOKEN=<your_token> bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth
```
或手动执行 mcporter 命令：
```bash
mcporter config add tencent-survey "https://wj.qq.com/api/v2/mcp" \
--header "Authorization=Bearer <your_token>" \
--transport http \
--scope home
```
> Token 以 `wjpt_` 开头，可在 [https://wj.qq.com/oauth/authorize](https://wj.qq.com/oauth/authorize) 登录后创建。
## 授权链接展示模板
当第一步输出 `AUTH_REQUIRED:<url>` 时，**立即**向用户展示：
> 🔑 **需要先完成腾讯问卷授权**
>
> 请确保在**浏览器**中打开以下链接完成授权：**[点击授权腾讯问卷]({url})**
>
> 🔑 授权码（nonce）：`{nonce}`
>
> ⚠️ 请使用 **QQ 或微信** 扫码 / 登录授权
>
> _(授权后将自动继续，无需回复)_
## 错误说明
| 错误 | 含义 |
|------|------|
| `ERROR:mcporter_not_found` | 缺少依赖，请先安装 Node.js |
| `ERROR:invalid_token_prefix` | `TENCENT_SURVEY_TOKEN` 格式错误，必须以 `wjpt_` 开头 |
| `ERROR:empty_token` | 授权异常，Token 为空 |
| `ERROR:save_token_failed` | Token 写入配置失败 |
| `AUTH_TIMEOUT` | 用户未在时限内完成授权 |
skills/tencent-survey/references/create_survey.md
+406
View File
@@ -0,0 +1,406 @@
# create_survey 工具参考
## 概述
使用纯文本创建问卷。系统会自动将文本解析为问卷结构。
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `text` | string | **是** | 问卷内容文本，换行使用 `\n` 代替（具体语法见下文） |
| `scene` | number | 否 | 问卷场景，默认为 1（调查），见下方场景枚举 |
| `project_id` | number | 否 | 项目 ID，将问卷创建到指定项目下 |
> **注意**：`text` 为必填参数。创建空白问卷时至少需要传入问卷标题，如 `text="新建问卷"`。
## 返回值
### 成功响应
```json
{
"survey_id": 716128,
"hash": "859f"
}
```
### 字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `survey_id` | number | 新创建的问卷 ID |
| `hash` | string | 问卷 hash，用于拼接投放链接 |
> **投放链接拼接**：`https://wj.qq.com/s2/{survey_id}/{hash}`
### 失败响应
```json
{
"code": "InvalidArgument",
"error": {
"type": "invalid_text_format"
}
}
```
## 场景枚举
| scene | 场景 | 说明 |
|-------|------|------|
| **1** | **调查** | **默认值**，通用问卷调查 |
| 3 | 考试 | 带评分的考试问卷 |
| 6 | 测评 | 测评类问卷 |
| 8 | 投票 | 投票类问卷 |
## text 文本语法详解
`text` 参数使用纯文本描述问卷结构，系统会自动解析为对应的问卷题型。
> **重要**：在 JSON 参数中，所有换行必须使用 `\n` 代替。
>
> 📖 语法详细参考：
> - [内容编辑概述](https://wj.qq.com/docs/survey-dsl/content/)
> - [语法说明](https://wj.qq.com/docs/survey-dsl/content/grammar)
> - [普通场景语法](https://wj.qq.com/docs/survey-dsl/content/scene-default)
> - [考试场景语法](https://wj.qq.com/docs/survey-dsl/content/scene-exam)
> - [测评场景语法](https://wj.qq.com/docs/survey-dsl/content/scene-assessment)
### 基础结构
```
问卷标题
问卷引导语（可选）
题目标题[题型](描述)
选项/内容
```
- 第一行为**问卷标题**
- 标题后可跟**引导语**（可选）
- 使用 `=== 分页 ===` 插入分页符
- 题目之间用空行分隔
### 题型语法列表
| 题型 | 语法 | 说明 |
|------|------|------|
| 单选题 | `标题[单选题](描述)\n选项A\n选项B` | 选项另起一行，每行一个 |
| 多选题 | `标题[多选题](描述)\n选项A\n选项B` | 选项另起一行 |
| 下拉题 | `标题[下拉题](描述)\n选项A\n选项B` | 选项另起一行 |
| 排序题 | `标题[排序题](描述)\n选项A\n选项B` | 选项另起一行 |
| 单行文本题 | `标题[单行文本题](描述)` | 无需选项 |
| 多行文本题 | `标题[多行文本题](描述)` | 无需选项 |
| 多项填空题 | `标题[多项填空题](描述)\n填空1：____` | 使用 `____` 指定填空位置 |
| 量表题 | `标题[量表题](描述)\n1~5` | 使用数字范围指定量表 |
| 日期时间题 | `标题[日期时间题](描述)` | 无需选项 |
| 地理位置题 | `标题[地理位置题](描述)` | 无需选项 |
| 附件题 | `标题[附件题](描述)` | 无需选项 |
| 手写签名题 | `标题[手写签名题](描述)` | 无需选项 |
| 段落说明 | `描述内容[段落说明]` | 用于纯文本段落说明（也称 `[文本描述题]`） |
| 矩阵单选题 | `标题[矩阵单选题](描述)\n选项A 选项B\n子问题1\n子问题2` | 选项空格分隔，子问题另起一行 |
| 矩阵多选题 | `标题[矩阵多选题](描述)\n选项A 选项B\n子问题1\n子问题2` | 同上 |
| 矩阵量表题 | `标题[矩阵量表题](描述)\n1~5\n子问题1\n子问题2` | 量表范围在前，子问题在后 |
| 联动题 | `标题[联动题](描述)\n第一层 第二层\n答案A+子答案A1+子答案A2\n答案B+子答案B1` | 层级名空格分隔，答案用 `+` 连接 |
> **提示**：`(描述)` 部分为可选的题目描述/说明文字。`[单选题]` 为默认题型，可以省略。
### 题目结构
每道题目的完整结构为：
```
标题[题型][设置](描述)
```
各部分顺序固定，不可调换。其中 `[设置]` 和 `(描述)` 都是可选的。
### 题目设置
支持在题型后追加设置标记：
| 设置 | 语法 | 说明 |
|------|------|------|
| 必答 | `[必答]` | 该题必须作答 |
| 选答 | `[选答]` | 该题可以跳过 |
示例：`您的姓名[单行文本题][必答](请填写真实姓名)`
### 考试场景专用设置
在考试场景（`scene=3`）中，题目可追加答案、分值和评分机制设置：
| 设置 | 语法 | 说明 |
|------|------|------|
| 答案 | `[答案：A、B]` | 正确答案，选项索引从 A 开始 |
| 填空答案 | `[答案：1.答案1、2.答案2]` | 各填空的正确答案 |
| 分值 | `[分数：5]` | 该题总分值 |
| 多空分值 | `[分数：2、3]` | 各空/各选项的分值 |
| 全部正确得分 | `[全部]` | 完全匹配答案才得分 |
| 部分正确得分 | `[部分]` | 部分匹配也可得分（多选题、不定项选择题） |
| 按空得分 | `[按空]` | 按填空分别计分（多项填空题） |
| 人工评分 | `[人工]` | 需人工阅卷评分（所有题型均可） |
> **考试题型**：考试场景额外支持 `[判断题]`、`[不定项选择题]`、`[问答题]` 三种题型。
### 测评场景专用题型
在测评场景（`scene=6`）中，选择题使用专用题型标记：
| 题型 | 语法 | 说明 |
|------|------|------|
| 测评单选题 | `[测评单选题]` | 替代普通场景的 `[单选题]` |
| 测评多选题 | `[测评多选题]` | 替代普通场景的 `[多选题]` |
> 测评场景也支持 `[量表题]`、`[矩阵单选题]`、`[矩阵量表题]`、`[单行文本题]`、`[多行文本题]`、`[多项填空题]`、`[文本描述题]`。
### 富文本语法
在题目标题、描述和选项中支持使用以下富文本语法：
| 类型 | 语法 | 说明 |
|------|------|------|
| 高亮 | `**高亮文本**` | 文本加粗/高亮显示 |
| 链接 | `[链接文本](https://example.com)` | 插入超链接 |
| 图片 | `![alt](https://example.com/img.png){宽度, 高度}` | 插入图片，`{宽度, 高度}` 必填，值为数字或 `auto` |
| 视频 | `!video(视频地址)` | 插入视频，仅支持腾讯视频、哔哩哔哩、优酷 |
### 完整示例（普通调查场景）
以下示例覆盖了普通调查场景（`scene=1`，默认）中的所有题型：
```
员工满意度调查
为了给您提供更好的服务，希望您能抽出几分钟时间，将您的感受和建议告诉我们。
1. 您在公司工作了多久？[单选题]
1年以下
1-3年
3-5年
5年以上
2. 您对以下哪些方面比较满意？[多选题]
工作环境
薪资福利
团队氛围
职业发展
3. 请选择您的部门[下拉题]
技术部
产品部
市场部
人力资源部
4. 请对以下福利按重要程度排序[排序题]
薪资待遇
年假天数
培训机会
弹性工作
5. 请对整体工作满意度打分[量表题](5分表示非常满意，1分表示非常不满意)
1~5
6. 您的姓名[单行文本题]
7. 您有什么建议或意见？[多行文本题]
8. 请填写以下信息[多项填空题]
姓名：____ 工号：____
9. 请选择您的入职日期[日期时间题]
10. 请选择您的办公地点[地理位置题]
11. 请上传相关材料[附件题]
12. 请签名确认[手写签名题]
本问卷到此结束，感谢您的参与！[段落说明]
=== 分页 ===
13. 请对各部门的协作效率打分[矩阵单选题]
非常好 较好 一般 较差
技术部
产品部
市场部
14. 以下哪些部门您有过合作经历？[矩阵多选题]
有合作 有交流 无接触
技术部
产品部
市场部
15. 请为各方面打分[矩阵量表题](1分最低，5分最高)
1~5
工作环境
薪资福利
团队氛围
16. 请选择您的所在区域[联动题]
省份 城市
广东省+广州市+深圳市+东莞市
北京市+朝阳区+海淀区
上海市+浦东新区+徐汇区
```
### 考试场景示例
考试场景（`scene=3`）支持设置答案、分值和评分机制。语法在题型后追加 `[答案：...]`、`[分数：...]`、`[全部]`/`[部分]`/`[按空]`/`[人工]`。
```
期中考试
考生姓名：____ 班级：____ 考号：____
1. 在下列物体中，难溶于水的物体是？[单选题][答案：D][分数：5][全部]
味精
酱油
酒精
食用油
2. 地球是太阳系中最大的行星[判断题][答案：A][分数：3][全部]
错误
正确
3. 哪些颜色属于奥运五环的颜色？[多选题][答案：A、B、D][分数：5][部分]
蓝色
黑色
紫色
红色
棕色
4. 哪些是哺乳动物？[不定项选择题][答案：B、C][分数：4][部分]
鳄鱼
鲸鱼
海豚
蜥蜴
5. 古诗文默写[多项填空题][答案：1.秋风萧瑟、2.洪波涌起][分数：2、3][按空]
树木丛生，百草丰茂。____，____。（曹操《观沧海》）
6. 以"一件令人感动的事"为题写一篇小作文[问答题][分数：20][人工]
```
### 测评场景示例
测评场景（`scene=6`）使用 `[测评单选题]`、`[测评多选题]` 等专用题型：
```
职业性格测评
本测评将帮助您了解自己的职业性格类型，请根据真实感受作答。
1. 在团队合作中，您通常扮演什么角色？[测评单选题]
领导者
协调者
执行者
创意提供者
2. 以下哪些描述符合您的工作风格？[测评多选题]
注重细节
喜欢创新
善于沟通
偏好独立工作
3. 请评价您对当前工作的满意程度[量表题](1分非常不满意，5分非常满意)
1~5
4. 请对以下陈述表示您的同意程度[矩阵单选题]
非常同意 同意 中立 不同意 非常不同意
我善于处理压力
我喜欢接受新挑战
我注重工作与生活的平衡
5. 请为以下能力自评打分[矩阵量表题](1分最低，5分最高)
1~5
沟通能力
领导能力
学习能力
团队协作
6. 请简要描述您的职业目标[多行文本题]
```
### 请求体示例
```json
{
"text": "员工满意度调查\n\n为了给您提供更好的服务，希望您能抽出几分钟时间。\n\n1. 您在公司工作了多久？[单选题]\n1年以下\n1-3年\n3-5年\n5年以上\n\n2. 您对以下哪些方面比较满意？[多选题]\n工作环境\n薪资福利\n团队氛围\n职业发展\n\n3. 请对整体工作满意度打分[量表题](5分表示非常满意，1分表示非常不满意)\n1~5\n\n4. 您有什么建议或意见？[多行文本题]"
}
```
## 调用示例
### 创建带内容的问卷
```
create_survey(text="满意度调查\n\n1. 您对工作环境是否满意？[单选题]\n非常满意\n满意\n一般\n不满意\n\n2. 您有什么建议？[多行文本题]")
```
### 创建在线考试
```
create_survey(scene=3, text="期中考试\n\n1. 1+1=?[单选题][答案：B][分数：5][全部]\n1\n2\n3\n4\n\n2. 以下哪些是偶数？[多选题][答案：A、C][分数：4][部分]\n2\n3\n4\n5\n\n3. 请默写古诗[问答题][分数：10][人工]")
```
### 创建投票
```
create_survey(scene=8, text="年度最佳员工投票\n\n1. 请选择您心目中的最佳员工[单选题]\n张三\n李四\n王五")
```
### 创建测评
```
create_survey(scene=6, text="性格测评\n\n1. 遇到困难时，您通常会？[测评单选题]\n独立解决\n寻求帮助\n暂时搁置\n\n2. 请为自信程度打分[量表题]\n1~5")
```
### 指定项目下创建
```
create_survey(project_id=100, text="项目反馈问卷\n\n1. 项目进展如何？[单选题]\n按计划进行\n有延迟\n已完成")
```
### mcporter 调用
```bash
# 创建调查
mcporter call tencent-survey.create_survey --args '{"text": "满意度调查\n\n1. 满意吗？[单选题]\n满意\n不满意"}'
# 指定场景（投票）
mcporter call tencent-survey.create_survey --args '{"scene": 8, "text": "投票\n\n1. 选谁？[单选题]\n甲\n乙"}'
```
## 错误码
| error.type | 错误描述 | 解决方案 |
|------------|---------|---------|
| `permission_denied` | 无创建权限 | 确认 Token 有创建问卷的权限 |
| `invalid_text_format` | 文本内容格式错误 | 检查 text 语法是否正确，参考上方语法说明 |
| `invalid_argument` | 参数校验不通过 | 检查参数类型和值是否正确 |
| `resource_exhausted` | 创建数量超过限制 | 当前团队问卷数量已达上限 |
## 注意事项
1. **text 为必填参数**：必须提供 text 内容
2. **project_id 需要有效**：传入无效的 project_id 会导致创建失败
3. **非幂等操作**：每次调用都会创建一份新问卷，请勿重复调用
4. **换行必须用 `\n`**：JSON 中不能直接换行，必须用 `\n` 替代
5. **选项不需要字母前缀**：选项直接写内容即可（如 `满意`），不需要写 `A. 满意`
6. **题目内不允许空行**：一道题目的标题和选项之间不能有空行，否则会被识别为两道题
7. **量表范围用 `~`**：量表题使用 `1~5` 格式（全角 `～` 和半角 `~` 均支持）
8. **考试场景题型差异**：考试场景额外支持 `[判断题]`、`[不定项选择题]`、`[问答题]`，答案索引从 A 开始
9. **测评场景题型差异**：测评场景的选择题需使用 `[测评单选题]`、`[测评多选题]`
## Annotations（工具注解）
| 注解 | 值 | 说明 |
|------|---|------|
| `readOnlyHint` | false | 非只读操作 |
| `destructiveHint` | false | 非破坏性操作 |
| `idempotentHint` | false | **非幂等**，每次调用都创建新问卷 |
| `openWorldHint` | false | 内部调用 |
skills/tencent-survey/references/get_survey.md
+231
View File
@@ -0,0 +1,231 @@
# get_survey 工具参考
## 概述
获取指定问卷的详细信息，包括标题、设置、页面、题目和选项。同时返回纯文本格式的问卷内容（`text` 字段，DSL 格式）。
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `survey_id` | number | **是** | 问卷 ID |
## 返回值
```json
{
"id": 292192,
"hash": "abc123def",
"scene": "1",
"title": "员工满意度调查",
"prefix": "欢迎参与本次调查",
"suffix": "感谢您的参与",
"state": 2,
"page_count": 1,
"topic_count": 3,
"started_at": "2026-01-15 00:00:00",
"end_at": "2026-07-01 00:00:00",
"createTime": 1736899800,
"updateTime": 1736899900,
"creator_user_id": 60000000001,
"project": {
"id": 1234,
"name": "2026年度调查"
},
"text": "员工满意度调查\n\n欢迎参与本次调查\n\n1. 您对工作环境是否满意？[单选题]\n非常满意\n满意\n一般\n不满意\n\n2. 请对整体满意度打分[量表题]\n1~5\n\n3. 请填写您的建议[多行文本题]",
"survey_dsl": {
"code": "if `q-1-xxxx::o1` then show `q2`",
"errors": []
},
"pages": [
{
"id": "p1",
"index": "0",
"questions": [
{
"id": "q-1-xxxx",
"index": 1,
"type": "radio",
"sub_type": 0,
"title": "您对工作环境是否满意？",
"description": "",
"required": true,
"options": [
{"id": "o1", "text": "非常满意"},
{"id": "o2", "text": "满意"},
{"id": "o3", "text": "一般"},
{"id": "o4", "text": "不满意"}
]
},
{
"id": "q2",
"index": 2,
"type": "star",
"title": "请对整体满意度打分",
"required": true,
"starBeginNum": 1,
"starNum": 5
},
{
"id": "q3",
"index": 3,
"type": "textarea",
"title": "请填写您的建议",
"required": false
}
]
}
]
}
```
### Survey 对象
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | number | 问卷 ID |
| `hash` | string | 问卷 hash，用于拼接投放链接 `https://wj.qq.com/s2/{id}/{hash}` |
| `scene` | string | 问卷场景：`"1"`=调查, `"3"`=考试, `"6"`=测评, `"8"`=投票 |
| `title` | string | 问卷标题（**可能包含 HTML 标签**） |
| `prefix` | string | 欢迎语 |
| `suffix` | string | 结束语 |
| `state` | number | 状态：0=草稿, 2=回收中, 3=暂停回收 |
| `page_count` | number | 页数 |
| `topic_count` | number | 问题数 |
| `started_at` | string | 回收开始时间 |
| `end_at` | string | 回收结束时间 |
| `createTime` | number | 创建时间（时间戳） |
| `updateTime` | number | 更新时间（时间戳） |
| `creator_user_id` | number | 问卷创建者的用户 ID |
| `project` | object | 问卷所属项目 |
| `project.id` | number | 项目 ID |
| `project.name` | string | 项目名称 |
| `text` | string | 纯文本格式的问卷内容（DSL 格式），包含标题、引导语和所有题目。可直接用于 `update_question` 等工具的参考 |
| `survey_dsl` | object | 问卷自定义逻辑信息 |
| `survey_dsl.code` | string | 当前自定义逻辑代码（DSL 脚本），可作为 `update_logic` 的参考。为空字符串时表示未设置逻辑 |
| `survey_dsl.errors` | array | 逻辑代码中的语法错误列表，为空数组时表示无错误 |
| `pages` | array | 页面列表 |
### Page 对象
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 单页标识 |
| `index` | string | 序号 |
| `questions` | array | 该页面下的题目列表 |
### Question 对象
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 题目 ID |
| `index` | number | 题目编号 |
| `type` | string | 题目类型（见下方 type 枚举） |
| `sub_type` | number | 题目子类型（有 sub_type 时优先根据 sub_type 判断） |
| `title` | string | 题目标题 |
| `description` | string | 题目备注 |
| `required` | boolean | 是否必答 |
| `options` | array | 选项列表（仅选择题有） |
| `hidden` | boolean | 是否隐藏 |
| `random` | boolean | 选项是否随机 |
| `goto` | object | 答题后跳转题目 |
| `maxlength` | object | 多选题最多可选 / 文本题最大字数 |
| `starBeginNum` | number | 量表题起始值 |
| `starNum` | number | 量表范围（2~10） |
| `starShowCustomStart` | string | 量表题起始文案 |
| `starShowCustomEnd` | string | 量表题末尾文案 |
| `subTitles` | array | 矩阵题子问题列表 |
| `subTitles[].id` | string | 矩阵题子问题 ID |
| `subTitles[].text` | string | 矩阵题子问题文本 |
| `levels` | array | 联动题各级标题 |
| `groups` | array | 联动题选项列表（嵌套） |
### Option 对象
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 选项 ID |
| `text` | string | 选项文案 |
| `exclusive` | boolean | 多选题中是否为互斥选项 |
| `noRandom` | boolean | 选项随机时是否固定当前选项位置 |
| `goto` | object | 选择后跳转题目 |
| `display` | object | 选择后显示题目 |
### type 枚举
| type | 说明 |
|------|------|
| `radio` | 单选 |
| `checkbox` | 多选 |
| `select` | 下拉 |
| `text` | 单行文本 |
| `textarea` | 多行文本 |
| `blanks` | 填空 |
| `star` | 量表/NPS |
| `sort` | 排序 |
| `matrix_radio` | 矩阵单选 |
| `matrix_checkbox` | 矩阵多选 |
| `matrix_star` | 矩阵量表 |
| `matrix_blank` | 矩阵填空 |
| `chained_selects` | 联动 |
| `upload` | 图片/文件 |
| `description` | 文本描述 |
| `datetime` | 日期/时间 |
| `signature` | 手写签名 |
| `address` | 地理位置 |
| `phone` | 手机号 |
| `sheet` | 自增表格 |
### 基本设置字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `prev` | boolean | 是否允许回到上一页 |
| `titleIndex` | boolean | 是否显示题目序号 |
| `login_check` | boolean | 是否开启登录验证 |
| `answer_count` | number | 允许回答次数 |
| `whitelist_enable` | boolean | 是否开启白名单 |
| `redirect_url` | string | 答题后跳转链接 |
| `webhook_url` | string | 答题后推送数据的地址 |
| `is_allow_update_answer` | boolean | 是否允许修改答案 |
| `is_enabled_location` | boolean | 是否获取用户位置信息 |
## 调用示例
### 直接调用
```
get_survey(survey_id=292192)
```
### mcporter 调用
```bash
mcporter call tencent-survey.get_survey --args '{"survey_id": 292192}'
```
## 错误码
| error.type | 错误描述 | 解决方案 |
|------------|---------|---------|
| `invalid_auth_status` | 权限类型错误 | 检查 Token 权限 |
| `claim_error` | 权限校验错误 | 问卷不属于当前 Token 绑定的团队 |
| `get_survey_error` | 获取数据错误 | 确认 survey_id 正确且问卷存在 |
## 注意事项
1. **title 可能包含 HTML 标签**：如 `<p>标题</p>`、`<br>` 等，展示给用户前建议清理
2. **嵌套结构**：数据为 `pages[] → questions[] → options[]`，需要递归解析
3. **type 与 sub_type**：有 `sub_type` 时优先根据 `sub_type` 判断题目类型
4. **投放链接拼接**：`https://wj.qq.com/s2/{id}/{hash}`
5. **text 字段**：返回纯文本 DSL 格式的问卷内容，包含标题和所有题目。该字段可作为 `update_question` 工具的参考，了解当前问卷的文本结构
6. **survey_dsl 字段**：返回当前问卷的自定义逻辑代码（`code`）和错误信息（`errors`）。`code` 可作为 `update_logic` 工具的参考，了解当前已设置的逻辑规则。追加逻辑时需在原有 `code` 基础上修改
## Annotations（工具注解）
| 注解 | 值 | 说明 |
|------|---|------|
| `readOnlyHint` | true | 只读操作，不修改任何数据 |
| `destructiveHint` | false | 非破坏性操作 |
| `idempotentHint` | true | 幂等操作，多次调用结果一致 |
| `openWorldHint` | false | 内部调用 |
skills/tencent-survey/references/list_answers.md
+254
View File
@@ -0,0 +1,254 @@
# list_answers 工具参考
## 概述
获取指定问卷的回答列表，支持游标分页。返回回答总数、回答详情列表和最后一条回答 ID（用于翻页）。
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `survey_id` | number | **是** | 问卷 ID |
| `per_page` | number | 否 | 每页返回条数，默认 20，最大 1000 |
| `last_answer_id` | number | 否 | 上一页最后一条回答的 ID，用于翻页。默认 0 表示从头开始 |
## 返回值
### 成功响应
```json
{
"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`。
### 获取全部回答的伪代码
```python
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 调用
```bash
# 获取首页（默认 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 正确且问卷存在 |
## 注意事项
1. **游标分页**：使用 `last_answer_id` 翻页，不支持跳页；必须按顺序逐页获取
2. **需要循环翻页**：如果回答数量多于 `per_page`，必须循环调用直到获取完所有数据
3. **per_page 上限 1000**：即使传入大于 1000 的值，也会被截断为 1000
4. **total 是全量统计**：`total` 字段表示问卷回收的总回答数，不随分页变化
5. **answer 嵌套结构**：每条回答的 `answer` 字段按 `页面 → 题目` 嵌套，需要递归解析
6. **题目回答内容**：不同题型的回答内容存储方式不同（`text` / `options` / `blanks` / `groups`），需根据 `type` 字段判断
## Annotations（工具注解）
| 注解 | 值 | 说明 |
|------|---|------|
| `readOnlyHint` | true | 只读操作，不修改任何数据 |
| `destructiveHint` | false | 非破坏性操作 |
| `idempotentHint` | true | 幂等操作，多次调用结果一致 |
| `openWorldHint` | false | 内部调用 |
skills/tencent-survey/references/update_logic.md
+235
View File
@@ -0,0 +1,235 @@
# update_logic 工具参考
## 概述
更新问卷的自定义逻辑设置（DSL 代码）。可通过 `get_survey` 返回的 `survey_dsl` 字段获取当前逻辑代码，修改后整体传入。传入空字符串可清空所有逻辑。
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `survey_id` | number | **是** | 问卷 ID |
| `dsl` | string | **是** | 问卷自定义逻辑代码（DSL 脚本语法） |
> **重要**：`dsl` 中引用题目和选项时需使用反引号包裹的 ID 格式（如 `` `q-1-abcd::o-100-ABCD` ``），ID 可从 `get_survey` 返回的题目和选项信息中获取。
## 返回值
### 成功响应
```json
{
"survey_id": 716128,
"result": "success"
}
```
### 失败响应
```json
{
"survey_id": 716128,
"result": "failed",
"error": "invalid_dsl_syntax: ..."
}
```
### 字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `survey_id` | number | 问卷 ID |
| `result` | string | `"success"` 表示成功，`"failed"` 表示失败 |
| `error` | string | 仅失败时返回，错误描述信息 |
## DSL 语法说明
自定义逻辑使用 DSL（Domain-Specific Language）脚本语法。多条规则用换行分隔。
> 📖 完整语法文档：https://wj.qq.com/docs/dsl/grammar
### 引用格式
在通过 MCP 工具编写 DSL 时，题目和选项 ID 需要使用**反引号包裹**：
| 元素 | 格式 | 示例 |
|------|------|------|
| 题目 | `` `q-1-xxxx` `` | `` `q-1-abcd` `` |
| 选项 | `` `q-1-xxxx::o-100-ABCD` `` | `` `q-1-abcd::o-100-EFGH` `` |
| 矩阵子问题 | `` `q-1-xxxx::s-200-IJKL` `` | `` `q-1-abcd::s-200-IJKL` `` |
| 填空项 | `` `q-1-xxxx::b-300-MNOP` `` | `` `q-1-abcd::b-300-MNOP` `` |
> **注意**：ID 值必须从 `get_survey` 返回的数据中获取，不能自行构造。
### 条件操作符
| 操作符 | 说明 | 示例 |
|--------|------|------|
| `and` | 逻辑与 | `if Q1A1 and Q2A2 then show Q3` |
| `or` | 逻辑或 | `if Q1A1 or Q1A2 then show Q2` |
| `not` | 逻辑非 | `if Q1 and not Q1A3 then show Q2` |
| `()` | 分组 | `if (Q1A1 or Q1A2) and Q2A1 then show Q3` |
| `>` `>=` `==` `<` `<=` | 比较 | `if Q1 > 5 then show Q2` |
| `+` `-` `*` `/` | 算数运算 | `if Q1 + Q2 > 10 then show Q3` |
### 行为控制语句
| 语句类型 | 语法格式 | 说明 |
|---------|---------|------|
| **条件显示** | `if <条件> then show <目标>` | 满足条件时显示题目或选项 |
| **条件隐藏** | `if <条件> then hide <目标>` | 满足条件时隐藏题目或选项 |
| **直接隐藏** | `hide <目标>` | 直接隐藏题目或选项（无条件） |
| **连线跳转** | `if <条件> then branch from <题目> to <目标>` | 满足条件时从某题跳转到指定题目或 `END` |
| **内容替换** | `replace "<文本>" in <题目> title with <来源>` | 将题目标题中的指定文本替换为另一题的回答 |
| **随机排序** | `shuffle <范围>` | 对题目或选项进行随机排序 |
| **随机抽取** | `random show <数量> from <范围>` | 从题目或选项中随机抽取指定数量显示 |
| **自动圈选** | `set <选项>` | 自动选中指定选项 |
| **自动填充** | `set <题目> = <来源>` | 自动填充文本题内容 |
### 特殊关键字
| 关键字 | 说明 | 示例 |
|--------|------|------|
| `END` | 结束页，用于跳转到问卷结尾 | `branch from Q1 to END` |
| `len` | 答案个数 | `if len Q1 > 2 then show Q3` |
| `index` | 答案排在第几位 | `if index Q1A1 == 1 then show Q2` |
| `RANDBETWEEN(min, max)` | 随机生成整数 | `if RANDBETWEEN(1, 10) > 5 then show Q2` |
| `LANG()` | 获取答题者语言 | `if LANG() == "zhs" then show Q1` |
| `PARAMS("key")` | 获取自定义参数 | `if PARAMS("source") == "wechat" then show Q2` |
| `#` | 注释 | `# 这是注释，不会被执行` |
### 范围表示
| 格式 | 说明 | 示例 |
|------|------|------|
| `Q1~3` | 题目 Q1 到 Q3 | `shuffle Q1~3` |
| `Q1A1~4` | 题目 Q1 的选项 A1 到 A4 | `shuffle Q1A1~4` |
| `Q1,Q3,Q5` | 不连续的题目 | `random show 1 from Q1,Q3,Q5` |
> 当连续 3 个以上序号时，系统会自动合并为 `~` 格式。
### weight 权重
`random show` 支持设置权重：
```
random show 1 from Q1~3 weight by 1:1:2
```
表示 Q3 被抽取的概率是 Q1、Q2 的两倍。
## 调用示例
### 典型工作流
```
# 1. 先获取问卷详情，确认题目和选项 ID
get_survey(survey_id=716128)
# 返回中查看 survey_dsl.code 获取当前逻辑代码
# 从 pages → questions → options 中获取题目和选项的 ID
# 2. 编写并更新逻辑
update_logic(survey_id=716128, dsl="if `q-1-abcd::o-100-EFGH` then show `q-1-ijkl`")
```
### 条件显示逻辑
```
# 选择了第1题的第1个选项时，显示第2题
update_logic(survey_id=716128, dsl="if `q-1-abcd::o-100-EFGH` then show `q-1-ijkl`")
```
### 多条件组合
```
# 第1题选了A 且 第2题选了B 时，显示第3题
update_logic(survey_id=716128, dsl="if `q-1-abcd::o-100-EFGH` and `q-1-ijkl::o-200-MNOP` then show `q-1-qrst`")
```
### 连线跳转（甄别题）
```
# 选择了第1题某选项时，跳转到问卷结束
update_logic(survey_id=716128, dsl="if `q-1-abcd::o-100-EFGH` then branch from `q-1-abcd` to END")
```
### 内容替换
```
# 将第3题标题中的"XXX"替换为第1题的回答
update_logic(survey_id=716128, dsl="replace \"XXX\" in `q-1-qrst` title with `q-1-abcd`")
```
### 随机排序与随机抽取
```
# 随机排序第1题的选项1~4
update_logic(survey_id=716128, dsl="shuffle `q-1-abcd::o-100-A`~`q-1-abcd::o-100-D`")
# 从题目1~3中随机抽取1道显示
update_logic(survey_id=716128, dsl="random show 1 from `q-1-abcd`~`q-1-qrst`")
```
### 多条规则组合
```
# 多条规则用换行分隔
update_logic(survey_id=716128, dsl="if `q-1-abcd::o-100-EFGH` then show `q-1-ijkl`\nif `q-1-abcd::o-100-MNOP` then show `q-1-qrst`\nreplace \"XXX\" in `q-1-uvwx` title with `q-1-abcd`")
```
### 清空所有逻辑
```
update_logic(survey_id=716128, dsl="")
```
### mcporter 调用
```bash
# 设置条件显示逻辑
mcporter call tencent-survey.update_logic --args '{"survey_id": 716128, "dsl": "if `q-1-abcd::o-100-EFGH` then show `q-1-ijkl`"}'
# 清空所有逻辑
mcporter call tencent-survey.update_logic --args '{"survey_id": 716128, "dsl": ""}'
```
## 权限要求
调用此接口需要满足以下权限条件（逐级校验）：
| 校验层 | 说明 |
|--------|------|
| `WithSurveyClaims` | 问卷归属校验：问卷必须属于当前 Token 绑定的团队 |
| `WithSurveyEditorClaims` | 编辑权限校验：当前用户需具有该问卷的编辑权限 |
| `WithSurveyEditableClaims` | 可编辑状态校验：问卷必须处于可编辑状态（如草稿状态） |
## 错误码
| error.type | 错误描述 | 解决方案 |
|------------|---------|---------|
| `invalid_dsl_syntax` | DSL 语法错误 | 检查 DSL 代码语法是否正确，参考语法文档 |
| `invalid_reference` | 引用的题目/选项 ID 不存在 | 确认 ID 从 get_survey 返回数据中获取 |
| `claim_error` | 权限校验错误 | 问卷不属于当前 Token 绑定的团队，或无编辑权限 |
| `survey_not_editable` | 问卷不可编辑 | 问卷可能正在回收中，需先暂停回收 |
| `invalid_argument` | 参数校验不通过 | 检查 survey_id、dsl 是否正确 |
## 注意事项
1. **先获取再更新**：必须先调用 `get_survey` 获取问卷详情，从返回数据中获取正确的题目 ID 和选项 ID
2. **整体覆盖**：`dsl` 参数为问卷的完整逻辑代码，每次调用会覆盖所有已有逻辑。如需追加规则，需先获取当前 `survey_dsl.code`，在其基础上修改后整体传入
3. **非幂等操作**：每次调用都会覆盖原有逻辑配置
4. **ID 使用反引号**：通过 MCP 工具编写 DSL 时，题目和选项 ID 需使用反引号包裹（如 `` `q-1-abcd::o-100-EFGH` ``）
5. **多条规则换行分隔**：在 JSON 参数中，多条规则之间使用 `\n` 分隔
6. **清空逻辑**：传入空字符串（`""`）可清空所有自定义逻辑
7. **问卷状态要求**：问卷必须处于可编辑状态，正在回收中的问卷需先暂停才能编辑
8. **与基础逻辑共存**：自定义逻辑与基础逻辑可同时设置，执行顺序为先执行基础逻辑、再执行自定义逻辑
9. **付费功能**：自定义逻辑为付费高级功能。如调用时返回 `paid_function_trial_no_permission` 错误，说明当前团队未购买该功能权限，需引导用户前往[腾讯问卷购买页](https://wj.qq.com/pricing)进行付费升级（升级为付费版本）后再使用
## Annotations（工具注解）
| 注解 | 值 | 说明 |
|------|---|------|
| `readOnlyHint` | false | 非只读操作，会修改问卷逻辑配置 |
| `destructiveHint` | false | 非破坏性操作（更新而非删除） |
| `idempotentHint` | false | **非幂等**，每次调用都覆盖逻辑配置 |
| `openWorldHint` | false | 内部调用 |
skills/tencent-survey/references/update_question.md
+154
View File
@@ -0,0 +1,154 @@
# update_question 工具参考
## 概述
更新问卷中的某一道题目。需要先用 `get_survey` 获取问卷详情以确认 `question_id`，再调用此接口更新指定题目的内容。只传入目标题目的纯文本（DSL 格式），系统会自动解析并覆盖该题。
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `survey_id` | number | **是** | 问卷 ID |
| `question_id` | string | **是** | 要更新的题目 ID，格式形如 `q-1-xxxx`（从 `get_survey` 返回的题目列表中获取） |
| `text` | string | **是** | 该题目的新文本内容（DSL 格式），只需包含这一道题 |
> **重要**：`question_id` 必须从 `get_survey` 返回的题目列表中获取，不能自行构造。
## 返回值
### 成功响应
```json
{
"survey_id": 716128,
"question_id": "q-1-abcd1234",
"result": "success"
}
```
### 失败响应
```json
{
"survey_id": 716128,
"question_id": "q-1-abcd1234",
"result": "failed",
"error": "invalid_text_format: ..."
}
```
### 字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `survey_id` | number | 问卷 ID |
| `question_id` | string | 更新的题目 ID |
| `result` | string | `"success"` 表示成功，`"failed"` 表示失败 |
| `error` | string | 仅失败时返回，错误描述信息 |
## text 语法说明
`text` 参数使用与 `create_survey` 相同的 DSL 语法，但**只需写一道题**（不需要写问卷标题）。
### 语法格式
```
题目标题[题型](描述)
选项A
选项B
```
> **关键规则**：`[题型]` 标签**必须紧跟在标题末尾**，后面不能再有文字。`(描述)` 部分为可选。
### 各题型示例
| 题型 | text 示例 |
|------|----------|
| 单选题 | `"您的性别[单选题]\n男\n女"` |
| 多选题 | `"您感兴趣的领域[多选题]\n技术\n设计\n产品\n运营"` |
| 下拉题 | `"请选择部门[下拉题]\n研发部\n市场部\n财务部"` |
| 排序题 | `"请排列优先级[排序题]\n功能\n性能\n安全\n体验"` |
| 单行文本题 | `"您的姓名[单行文本题]"` |
| 多行文本题 | `"您的建议[多行文本题]"` |
| 量表题 | `"请打分[量表题](5分非常满意)\n1~5"` |
| 多项填空题 | `"联系方式[多项填空题]\n手机号：____\n邮箱：____"` |
| 矩阵单选题 | `"满意度评价[矩阵单选题]\n非常满意 满意 一般 不满意\n服务态度\n响应速度"` |
| 段落说明 | `"以下为附加问题[段落说明]"` |
> 完整语法参考：`references/create_survey.md` 中的「text 文本语法详解」章节。
## 调用示例
### 典型工作流
```
# 1. 先获取问卷详情，确认题目 ID
get_survey(survey_id=716128)
# 返回中找到目标题目，例如 id="q-1-abcd1234"，类型为单选题
# 2. 更新该题目
update_question(survey_id=716128, question_id="q-1-abcd1234", text="您的性别[单选题]\n男\n女\n其他")
```
### 更新量表题
```
update_question(survey_id=716128, question_id="q-1-efgh5678", text="请对服务打分[量表题](1分最低，10分最高)\n1~10")
```
### 更新多选题
```
update_question(survey_id=716128, question_id="q-1-ijkl9012", text="您常用的编程语言[多选题]\nGo\nPython\nJava\nTypeScript\nRust")
```
### mcporter 调用
```bash
# 更新单选题
mcporter call tencent-survey.update_question --args '{"survey_id": 716128, "question_id": "q-1-abcd1234", "text": "您的性别[单选题]\n男\n女\n其他"}'
# 更新多行文本题
mcporter call tencent-survey.update_question --args '{"survey_id": 716128, "question_id": "q-1-efgh5678", "text": "请填写您的建议[多行文本题]"}'
```
## 权限要求
调用此接口需要满足以下权限条件（逐级校验）：
| 校验层 | 说明 |
|--------|------|
| `WithSurveyClaims` | 问卷归属校验：问卷必须属于当前 Token 绑定的团队 |
| `WithSurveyEditorClaims` | 编辑权限校验：当前用户需具有该问卷的编辑权限 |
| `WithSurveyEditableClaims` | 可编辑状态校验：问卷必须处于可编辑状态（如草稿状态） |
## 错误码
| error.type | 错误描述 | 解决方案 |
|------------|---------|---------|
| `invalid_text_format` | 文本内容格式错误 | 检查 text 语法是否正确，`[题型]` 需紧跟标题末尾 |
| `no_question_parsed` | 未能解析出任何题目 | 确认 text 包含了完整的题目内容 |
| `unknown_question_type` | 无法识别的题型 | 检查 `[题型]` 标签是否使用了支持的题型名称 |
| `save_question_failed` | 保存题目失败 | 服务端异常，请稍后重试 |
| `claim_error` | 权限校验错误 | 问卷不属于当前 Token 绑定的团队，或无编辑权限 |
| `survey_not_editable` | 问卷不可编辑 | 问卷可能正在回收中，需先暂停回收 |
| `invalid_argument` | 参数校验不通过 | 检查 survey_id、question_id、text 是否正确 |
## 注意事项
1. **先获取再更新**：必须先调用 `get_survey` 获取问卷详情，从返回的题目列表中获取正确的 `question_id`
2. **单题更新**：`text` 只需包含一道题目的内容，不要写问卷标题或多道题
3. **非幂等操作**：每次调用都会覆盖原题目内容
4. **题型标签位置**：`[题型]` 必须紧跟标题末尾，不能放在其他位置
5. **问卷状态要求**：问卷必须处于可编辑状态，正在回收中的问卷需先暂停才能编辑
6. **换行用 `\n`**：在 JSON 参数中，所有换行必须使用 `\n` 代替
7. **选项无需字母前缀**：选项直接写内容即可（如 `满意`），不需要写 `A. 满意`
## Annotations（工具注解）
| 注解 | 值 | 说明 |
|------|---|------|
| `readOnlyHint` | false | 非只读操作，会修改问卷内容 |
| `destructiveHint` | false | 非破坏性操作（更新而非删除） |
| `idempotentHint` | false | **非幂等**，每次调用都覆盖题目内容 |
| `openWorldHint` | false | 内部调用 |