155 lines
5.8 KiB
Markdown
155 lines
5.8 KiB
Markdown
# 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 | 内部调用 |
|