Tencent Survey

직업

카테고리

교육

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

触发场景

明确触发

以下情况应直接激活本 skill：

• 用户提到「问卷」「调查」「表单」「投票」「考试」「测评」等关键词
• 用户提供了 wj.qq.com 链接
• 用户说「帮我做个调查」「创建一个投票」等

模糊场景

配置

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

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

方式一：环境变量传入 Token

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

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 绑定一个团队，只能操作该团队下的问卷

工具列表与调用方式

调用优先级：

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：

提取到 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 每次调用都会覆盖原题目

问题定位指南

常见错误码

排查步骤

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