Tencent Survey

SKILL.md

---
name: tencent-survey
description: "腾讯问卷（wj.qq.com）- 在线问卷调查平台。涉及「问卷」「调查」「表单」「投票」「考试」「测评」「wj.qq.com」等操作时优先使用。支持能力：(1) 获取问卷详情（标题、设置、页面、题目、选项完整结构 + 纯文本 DSL）(2) 使用纯文本创建问卷（text 必填，支持指定场景/指定项目）(3) 更新问卷中的单个题目（DSL 格式）(4) 获取问卷回答列表（支持游标分页）。支持场景：调查(1)、考试(3)、测评(6)、投票(8)。"
homepage: https://wj.qq.com
version: 1.0.2
metadata: {"openclaw":{"primaryEnv":"TENCENT_SURVEY_TOKEN","category":"tencent","tencentTokenMode":"custom","emoji":"📋"}}
---

# SKILL 更新

每天使用 SKILL 前进行一次更新检查，按照如下的步骤执行:

1. **查看当前版本version**：读取本文件顶部 frontmatter 中的 `version` 字段；格式为 MAJOR.MINOR.PATCH
2. **查看最新版本latest**：通过命令获取最新版本信息`latest`，输入参数 `current_version` 为上一步获取的当前版本
```bash
mcporter call tencent-survey "check_skill_update" --args '{"current_version": "当前版本"}'
```
JSON 格式数据返回，返回参数示例：
- `has_update`: 是否有更新（true/false）
- `latest`: 最新版本号，格式为 MAJOR.MINOR.PATCH
- `current_version`: 当前传入的版本号
- `release_note`: 最新版本发布说明
- `instruction`: 更新指令

3. **更新版本**：如果 `has_update` 为 true（即当前版本`current_version`低于最新版本`latest`），则遵循 `instruction` 指令进行更新，或提示用户更新

# 腾讯问卷 MCP 使用指南

腾讯问卷 MCP 提供问卷查询、创建、编辑与回答查看能力，让 AI 助手可以直接操作问卷系统。

## 触发场景

### 明确触发

以下情况应直接激活本 skill：
- 用户提到「问卷」「调查」「表单」「投票」「考试」「测评」等关键词
- 用户提供了 `wj.qq.com` 链接
- 用户说「帮我做个调查」「创建一个投票」等

### 模糊场景

| 用户表述 | 判断方式 |
|---------|---------|
| 「帮我做个投票」 | 直接使用本 skill，scene=8 |
| 「做个考试」 | 直接使用本 skill，scene=3 |
| 「做个测评」 | 直接使用本 skill，scene=6 |
| 「收集一下大家的意见」 | 直接使用本 skill，scene=1（调查） |
| 「我有个问卷链接…」 | 解析链接提取 survey_id，调用 get_survey |
| 「修改问卷的第X题」 | 先 get_survey 获取 question_id，再 update_question |
| 「看看问卷的回答」 | 调用 list_answers，注意翻页获取全部数据 |
| 「问卷收了多少份」 | 调用 list_answers 查看 total 字段 |

## 配置

**在本次会话首次调用工具前**，完成一次鉴权检查（完整流程见 `references/auth.md`）：

> `${SKILL_DIR}` 为本 skill 所在目录路径（即 `SKILL.md` 所在目录）。由 AI Agent 框架在加载 skill 时自动注入；如果框架未注入，请替换为 `SKILL.md` 所在目录的绝对路径。

### 方式一：环境变量传入 Token

如果已有 Token（环境变量 `TENCENT_SURVEY_TOKEN`），直接完成配置，无需 OAuth 授权：

```bash
TENCENT_SURVEY_TOKEN=xxx bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth
```

脚本检测到 `TENCENT_SURVEY_TOKEN` 后会自动写入 mcporter 配置，输出 `READY` 即表示就绪。

### 方式二：OAuth 设备授权

未设置 `TENCENT_SURVEY_TOKEN` 时，自动进入 OAuth 授权流程：

1. 执行 `bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth`
2. 输出 `READY` → 鉴权已就绪，直接继续
3. 输出 `AUTH_REQUIRED:<url>` → 向用户展示授权链接，然后执行 `bash "${SKILL_DIR}/setup.sh" wj_wait_auth` 等待授权完成
4. 输出 `ERROR:*` → 告知用户对应错误

> 鉴权通过后，**同一会话内后续调用无需重复检查**。仅当工具返回 `invalid_token`、`token expired`、`missing_token` 等鉴权错误时，才需要重新执行上述流程。

- Token 前缀固定为 `wjpt_`，长度 70 字符
- 每个 Token 绑定一个团队，只能操作该团队下的问卷

## 工具列表与调用方式

| 工具名称 | 功能说明 | 参考文档 |
|---------|---------|---------|
| get_survey | 获取指定问卷的详细信息（标题、设置、页面、题目、选项 + 纯文本 DSL） | `references/get_survey.md` |
| create_survey | 使用纯文本创建问卷（text 必填，支持指定场景/指定项目） | `references/create_survey.md` |
| update_question | 更新问卷中的某一道题目（需先获取 question_id） | `references/update_question.md` |
| list_answers | 获取问卷的回答列表（支持游标分页） | `references/list_answers.md` |
| check_skill_update | 检查 Skill 是否有新版本可更新 | 见上方「SKILL 更新」章节 |

调用优先级：

1. **MCP 原生调用**：如果当前 AI Agent 已通过 MCP 协议连接了 tencent-survey 服务（工具列表中可见 `get_survey`、`create_survey`、`update_question`、`list_answers`），直接调用工具即可
2. **mcporter CLI 调用**：如果 AI Agent 不支持 MCP 原生调用，或工具列表中未出现 tencent-survey 工具，通过终端执行 `mcporter call tencent-survey.<tool_name> --args '{...}'`
3. **确认工具可用**：使用 `mcporter list tencent-survey` 查看已注册的工具列表和参数 Schema

> 参考文档中的参数说明应与 MCP 工具 Schema 保持一致。如有冲突，以 `mcporter list tencent-survey` 返回的 Schema 为准。

## URL 解析规则

问卷投放链接格式为 `https://wj.qq.com/s2/{survey_id}/{hash}`

当用户提供链接时，取路径第二段为 `survey_id`：

| URL 格式 | 提取方式 | 示例 |
|----------|---------|------|
| `wj.qq.com/s2/{id}/{hash}` | 取路径第二段为 survey_id | `wj.qq.com/s2/292192/abc1` → `292192` |

> 提取到 `survey_id` 后，调用 `get_survey(survey_id=...)` 获取问卷详情。

## 数据模型

```
问卷（Survey）
├── 基本信息：id, hash, title, scene, state
├── 设置：prefix(欢迎语), suffix(结束语), started_at, end_at ...
├── 项目：project { id, name }
├── 纯文本内容：text（DSL 格式，包含标题和所有题目）
├── 页面列表（Pages[]）
│   └── 题目列表（Questions[]）
│       ├── 基本属性：id, type, sub_type, title, required
│       ├── 选项列表（Options[]）：id, text, exclusive
│       ├── 量表属性：starBeginNum, starNum
│       ├── 矩阵子问题：subTitles[]
│       └── 联动层级：levels[], groups[]
└── 回答列表（Answers[]）← 通过 list_answers 获取
    ├── 基本信息：answer_id, respondent_nickname, started_at, ended_at
    ├── 地理信息：country, province, city
    └── 回答内容（answer[]）
        └── 页面 → 题目回答 { id, type, text, options, blanks, groups }
```

> 核心嵌套关系：`Survey → Pages[] → Questions[] → Options[]`
> 回答嵌套关系：`Answer → answer[] (Pages) → questions[]`

## 常见工作流

### 查看问卷详情

参考文档：`references/get_survey.md`

1. 执行鉴权检查（见上方「配置」节）
2. 从用户提供的链接或 ID 获取 `survey_id`（链接解析见「URL 解析规则」）
3. 调用 `get_survey(survey_id=...)` 获取问卷详情
4. 递归解析 `pages → questions → options` 嵌套结构
5. 向用户展示问卷标题、题目列表等信息

### 创建问卷

参考文档：`references/create_survey.md`

1. 执行鉴权检查（见上方「配置」节）
2. 根据用户需求判断 `scene`：调查(1, 默认)、考试(3)、测评(6)、投票(8)
3. 按问卷文本语法组织 `text` 内容（语法详见参考文档）
4. 如果用户指定了项目，传入 `project_id`
5. 调用 `create_survey` 创建问卷
6. 从返回结果中取 `survey_id` 和 `hash`，拼接投放链接 `wj.qq.com/s2/{survey_id}/{hash}` 告知用户
7. 可选：调用 `get_survey` 确认问卷结构

### 更新问卷题目

参考文档：`references/update_question.md`

1. 执行鉴权检查（见上方「配置」节）
2. 调用 `get_survey(survey_id=...)` 获取问卷详情
3. 从返回的 `pages → questions` 中找到目标题目的 `id`（格式如 `q-1-xxxx`）
4. 参考返回的 `text` 字段了解当前问卷的 DSL 格式
5. 按 DSL 语法编写新的题目文本（只写这一道题，不需要问卷标题）
6. 调用 `update_question(survey_id=..., question_id=..., text=...)` 更新题目
7. 可选：再次调用 `get_survey` 确认更新结果

### 查看问卷回答

参考文档：`references/list_answers.md`

1. 执行鉴权检查（见上方「配置」节）
2. 调用 `list_answers(survey_id=...)` 获取首页回答
3. **⚠️ 注意翻页**：如果 `list.length == per_page`，说明可能还有下一页，需要循环翻页：
   - 将返回的 `last_answer_id` 作为下一次请求的参数
   - 继续调用 `list_answers(survey_id=..., last_answer_id=...)` 获取下一页
   - 直到 `list.length < per_page` 表示已到最后一页
4. 解析每条回答的 `answer` 字段（嵌套结构：`页面 → 题目回答`）
5. 向用户展示回答汇总或详情

## 注意事项

- **标题可能含 HTML 标签**：`get_survey` 返回的 `title` 字段可能包含 `<p>`、`<br>` 等标签，展示给用户前需清理
- **text 字段（DSL 格式）**：`get_survey` 返回的 `text` 字段是纯文本 DSL 格式的问卷内容，可作为 `update_question` 的参考
- **text 参数格式**：`create_survey` 和 `update_question` 的 `text` 为必填，JSON 中换行使用 `\n`，选项不需要字母前缀（写 `满意` 而非 `A. 满意`）
- **update_question 需先获取 question_id**：必须先调用 `get_survey` 获取题目列表，不能自行构造 question_id
- **list_answers 需要翻页**：回答列表使用游标分页，如果回答数量超过 `per_page`（默认 20），必须循环调用直到获取完所有数据
- **非幂等的写操作**：`create_survey` 每次调用都会创建新问卷，`update_question` 每次调用都会覆盖原题目

## 问题定位指南

### 常见错误码

| 错误码 | 错误类型 | 解决方案 |
|--------|---------|---------|
| `missing_token` | 请求未携带 Token | 检查 Authorization Header 或 access_token 参数 |
| `invalid_token_prefix` | Token 前缀错误 | 确认使用 `wjpt_` 开头的 Token |
| `invalid token` | Token 不存在或已撤销 | 重新创建 Token |
| `token expired` | Token 已过期 | 重新授权，详见 `references/auth.md` |
| `claim_error` | 问卷不属于当前团队 | 确认问卷 ID 正确且属于当前 Token 绑定的团队 |
| `invalid_text_format` | 文本格式错误（create_survey / update_question） | 检查 text DSL 语法 |
| `survey_not_editable` | 问卷不可编辑（update_question） | 问卷可能正在回收中，需先暂停 |

### 排查步骤

1. **检查错误信息**：查看返回的 error 字段，确定错误类型
2. **检查请求参数**：确认 `survey_id` 等参数值正确
3. **阅读参考文档**：`references/` 目录下包含所有工具的参数说明
4. **获取工具列表**：使用 `mcporter list tencent-survey` 确认工具是否可用