407 lines
13 KiB
Markdown
407 lines
13 KiB
Markdown
# 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)` | 插入超链接 |
|
||
| 图片 | `{宽度, 高度}` | 插入图片，`{宽度, 高度}` 必填，值为数字或 `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 | 内部调用 |
|