\r \r

SKILL 更新\r

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

1. 查看当前版本version：读取本文件顶部 frontmatter 中的 version 字段；格式为 MAJOR.MINOR.PATCH\r
2. 查看最新版本latest：通过命令获取最新版本信息latest，输入参数 current_version 为上一步获取的当前版本\r

mcporter call tencent-survey "check_skill_update" --args '{"current_version": "当前版本"}'\r
```\r
JSON 格式数据返回，返回参数示例：\r
- `has_update`: 是否有更新（true/false）\r
- `latest`: 最新版本号，格式为 MAJOR.MINOR.PATCH\r
- `current_version`: 当前传入的版本号\r
- `release_note`: 最新版本发布说明\r
- `instruction`: 更新指令\r
\r
3. **更新版本**：如果 `has_update` 为 true（即当前版本`current_version`低于最新版本`latest`），则遵循 `instruction` 指令进行更新，或提示用户更新\r
\r
# 腾讯问卷 MCP 使用指南\r
\r
腾讯问卷 MCP 提供问卷查询、创建、编辑与回答查看能力，让 AI 助手可以直接操作问卷系统。\r
\r
## 触发场景\r
\r
### 明确触发\r
\r
以下情况应直接激活本 skill：\r
- 用户提到「问卷」「调查」「表单」「投票」「考试」「测评」等关键词\r
- 用户提供了 `wj.qq.com` 链接\r
- 用户说「帮我做个调查」「创建一个投票」等\r
\r
### 模糊场景\r
\r
| 用户表述 | 判断方式 |\r
|---------|---------|\r
| 「帮我做个投票」 | 直接使用本 skill，scene=8 |\r
| 「做个考试」 | 直接使用本 skill，scene=3 |\r
| 「做个测评」 | 直接使用本 skill，scene=6 |\r
| 「收集一下大家的意见」 | 直接使用本 skill，scene=1（调查） |\r
| 「我有个问卷链接…」 | 解析链接提取 survey_id，调用 get_survey |\r
| 「修改问卷的第X题」 | 先 get_survey 获取 question_id，再 update_question |\r
| 「看看问卷的回答」 | 调用 list_answers，注意翻页获取全部数据 |\r
| 「问卷收了多少份」 | 调用 list_answers 查看 total 字段 |\r
\r
## 配置\r
\r
**在本次会话首次调用工具前**，完成一次鉴权检查（完整流程见 `references/auth.md`）：\r
\r
> `${SKILL_DIR}` 为本 skill 所在目录路径（即 `SKILL.md` 所在目录）。由 AI Agent 框架在加载 skill 时自动注入；如果框架未注入，请替换为 `SKILL.md` 所在目录的绝对路径。\r
\r
### 方式一：环境变量传入 Token\r
\r
如果已有 Token（环境变量 `TENCENT_SURVEY_TOKEN`），直接完成配置，无需 OAuth 授权：\r
\r
```bash\r
TENCENT_SURVEY_TOKEN=xxx bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth\r
```\r
\r
脚本检测到 `TENCENT_SURVEY_TOKEN` 后会自动写入 mcporter 配置，输出 `READY` 即表示就绪。\r
\r
### 方式二：OAuth 设备授权\r
\r
未设置 `TENCENT_SURVEY_TOKEN` 时，自动进入 OAuth 授权流程：\r
\r
1. 执行 `bash "${SKILL_DIR}/setup.sh" wj_check_and_start_auth`\r
2. 输出 `READY` → 鉴权已就绪，直接继续\r
3. 输出 `AUTH_REQUIRED:\x3Curl>` → 向用户展示授权链接，然后执行 `bash "${SKILL_DIR}/setup.sh" wj_wait_auth` 等待授权完成\r
4. 输出 `ERROR:*` → 告知用户对应错误\r
\r
> 鉴权通过后，**同一会话内后续调用无需重复检查**。仅当工具返回 `invalid_token`、`token expired`、`missing_token` 等鉴权错误时，才需要重新执行上述流程。\r
\r
- Token 前缀固定为 `wjpt_`，长度 70 字符\r
- 每个 Token 绑定一个团队，只能操作该团队下的问卷\r
\r
## 工具列表与调用方式\r
\r
| 工具名称 | 功能说明 | 参考文档 |\r
|---------|---------|---------|\r
| get_survey | 获取指定问卷的详细信息（标题、设置、页面、题目、选项 + 纯文本 DSL） | `references/get_survey.md` |\r
| create_survey | 使用纯文本创建问卷（text 必填，支持指定场景/指定项目） | `references/create_survey.md` |\r
| update_question | 更新问卷中的某一道题目（需先获取 question_id） | `references/update_question.md` |\r
| list_answers | 获取问卷的回答列表（支持游标分页） | `references/list_answers.md` |\r
| check_skill_update | 检查 Skill 是否有新版本可更新 | 见上方「SKILL 更新」章节 |\r
\r
调用优先级：\r
\r
1. **MCP 原生调用**：如果当前 AI Agent 已通过 MCP 协议连接了 tencent-survey 服务（工具列表中可见 `get_survey`、`create_survey`、`update_question`、`list_answers`），直接调用工具即可\r
2. **mcporter CLI 调用**：如果 AI Agent 不支持 MCP 原生调用，或工具列表中未出现 tencent-survey 工具，通过终端执行 `mcporter call tencent-survey.\x3Ctool_name> --args '{...}'`\r
3. **确认工具可用**：使用 `mcporter list tencent-survey` 查看已注册的工具列表和参数 Schema\r
\r
> 参考文档中的参数说明应与 MCP 工具 Schema 保持一致。如有冲突，以 `mcporter list tencent-survey` 返回的 Schema 为准。\r
\r
## URL 解析规则\r
\r
问卷投放链接格式为 `https://wj.qq.com/s2/{survey_id}/{hash}`\r
\r
当用户提供链接时，取路径第二段为 `survey_id`：\r
\r
| URL 格式 | 提取方式 | 示例 |\r
|----------|---------|------|\r
| `wj.qq.com/s2/{id}/{hash}` | 取路径第二段为 survey_id | `wj.qq.com/s2/292192/abc1` → `292192` |\r
\r
> 提取到 `survey_id` 后，调用 `get_survey(survey_id=...)` 获取问卷详情。\r
\r
## 数据模型\r
\r
```\r
问卷（Survey）\r
├── 基本信息：id, hash, title, scene, state\r
├── 设置：prefix(欢迎语), suffix(结束语), started_at, end_at ...\r
├── 项目：project { id, name }\r
├── 纯文本内容：text（DSL 格式，包含标题和所有题目）\r
├── 页面列表（Pages[]）\r
│   └── 题目列表（Questions[]）\r
│       ├── 基本属性：id, type, sub_type, title, required\r
│       ├── 选项列表（Options[]）：id, text, exclusive\r
│       ├── 量表属性：starBeginNum, starNum\r
│       ├── 矩阵子问题：subTitles[]\r
│       └── 联动层级：levels[], groups[]\r
└── 回答列表（Answers[]）← 通过 list_answers 获取\r
    ├── 基本信息：answer_id, respondent_nickname, started_at, ended_at\r
    ├── 地理信息：country, province, city\r
    └── 回答内容（answer[]）\r
        └── 页面 → 题目回答 { id, type, text, options, blanks, groups }\r
```\r
\r
> 核心嵌套关系：`Survey → Pages[] → Questions[] → Options[]`\r
> 回答嵌套关系：`Answer → answer[] (Pages) → questions[]`\r
\r
## 常见工作流\r
\r
### 查看问卷详情\r
\r
参考文档：`references/get_survey.md`\r
\r
1. 执行鉴权检查（见上方「配置」节）\r
2. 从用户提供的链接或 ID 获取 `survey_id`（链接解析见「URL 解析规则」）\r
3. 调用 `get_survey(survey_id=...)` 获取问卷详情\r
4. 递归解析 `pages → questions → options` 嵌套结构\r
5. 向用户展示问卷标题、题目列表等信息\r
\r
### 创建问卷\r
\r
参考文档：`references/create_survey.md`\r
\r
1. 执行鉴权检查（见上方「配置」节）\r
2. 根据用户需求判断 `scene`：调查(1, 默认)、考试(3)、测评(6)、投票(8)\r
3. 按问卷文本语法组织 `text` 内容（语法详见参考文档）\r
4. 如果用户指定了项目，传入 `project_id`\r
5. 调用 `create_survey` 创建问卷\r
6. 从返回结果中取 `survey_id` 和 `hash`，拼接投放链接 `wj.qq.com/s2/{survey_id}/{hash}` 告知用户\r
7. 可选：调用 `get_survey` 确认问卷结构\r
\r
### 更新问卷题目\r
\r
参考文档：`references/update_question.md`\r
\r
1. 执行鉴权检查（见上方「配置」节）\r
2. 调用 `get_survey(survey_id=...)` 获取问卷详情\r
3. 从返回的 `pages → questions` 中找到目标题目的 `id`（格式如 `q-1-xxxx`）\r
4. 参考返回的 `text` 字段了解当前问卷的 DSL 格式\r
5. 按 DSL 语法编写新的题目文本（只写这一道题，不需要问卷标题）\r
6. 调用 `update_question(survey_id=..., question_id=..., text=...)` 更新题目\r
7. 可选：再次调用 `get_survey` 确认更新结果\r
\r
### 查看问卷回答\r
\r
参考文档：`references/list_answers.md`\r
\r
1. 执行鉴权检查（见上方「配置」节）\r
2. 调用 `list_answers(survey_id=...)` 获取首页回答\r
3. **⚠️ 注意翻页**：如果 `list.length == per_page`，说明可能还有下一页，需要循环翻页：\r
   - 将返回的 `last_answer_id` 作为下一次请求的参数\r
   - 继续调用 `list_answers(survey_id=..., last_answer_id=...)` 获取下一页\r
   - 直到 `list.length \x3C per_page` 表示已到最后一页\r
4. 解析每条回答的 `answer` 字段（嵌套结构：`页面 → 题目回答`）\r
5. 向用户展示回答汇总或详情\r
\r
## 注意事项\r
\r
- **标题可能含 HTML 标签**：`get_survey` 返回的 `title` 字段可能包含 `\x3Cp>`、`\x3Cbr>` 等标签，展示给用户前需清理\r
- **text 字段（DSL 格式）**：`get_survey` 返回的 `text` 字段是纯文本 DSL 格式的问卷内容，可作为 `update_question` 的参考\r
- **text 参数格式**：`create_survey` 和 `update_question` 的 `text` 为必填，JSON 中换行使用 `\
`，选项不需要字母前缀（写 `满意` 而非 `A. 满意`）\r
- **update_question 需先获取 question_id**：必须先调用 `get_survey` 获取题目列表，不能自行构造 question_id\r
- **list_answers 需要翻页**：回答列表使用游标分页，如果回答数量超过 `per_page`（默认 20），必须循环调用直到获取完所有数据\r
- **非幂等的写操作**：`create_survey` 每次调用都会创建新问卷，`update_question` 每次调用都会覆盖原题目\r
\r
## 问题定位指南\r
\r
### 常见错误码\r
\r
| 错误码 | 错误类型 | 解决方案 |\r
|--------|---------|---------|\r
| `missing_token` | 请求未携带 Token | 检查 Authorization Header 或 access_token 参数 |\r
| `invalid_token_prefix` | Token 前缀错误 | 确认使用 `wjpt_` 开头的 Token |\r
| `invalid token` | Token 不存在或已撤销 | 重新创建 Token |\r
| `token expired` | Token 已过期 | 重新授权，详见 `references/auth.md` |\r
| `claim_error` | 问卷不属于当前团队 | 确认问卷 ID 正确且属于当前 Token 绑定的团队 |\r
| `invalid_text_format` | 文本格式错误（create_survey / update_question） | 检查 text DSL 语法 |\r
| `survey_not_editable` | 问卷不可编辑（update_question） | 问卷可能正在回收中，需先暂停 |\r
\r
### 排查步骤\r
\r
1. **检查错误信息**：查看返回的 error 字段，确定错误类型\r
2. **检查请求参数**：确认 `survey_id` 等参数值正确\r
3. **阅读参考文档**：`references/` 目录下包含所有工具的参数说明\r
4. **获取工具列表**：使用 `mcporter list tencent-survey` 确认工具是否可用\r