# 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 | 内部调用 |