Skill: sky-lv/tencent-survey (version 1.0.0)

--- 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` 确认工具是否可用


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)