问卷网

问卷网 Skill 使用指南

本 Skill 提供问卷网问卷的创建、查询、编辑、查看报表（/report/topic/{project_id}，由 open_report.js 实现，默认自动用浏览器打开；--no-open 仅输出链接）、数据概况（overview_stats.js，即时统计答卷/浏览/完成率；请求 URL 与 generate_sign.js（ai_skills）同源签名）与数据导出能力。

触发场景

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

• 用户提到「问卷」「调查」「收集」「表单」「投票」「评选」「报名」「登记」「考试」「测评」「趣味测试」「心理测试」「打分测试」「满意度」「在线收款」「360评估」「问卷网」「wenjuan.com」等关键词

• 用户说「帮我做个调查」「创建一个投票」「做个表单/报名表」「新建问卷」「新建测评问卷」「做个趣味测试」等

• 新建问卷统一流程：凡「新建/创建」类需求，在完成 references/create_survey.md 所述的发布前用户确认（展示标题、类型、题目概要并取得明确同意）后，再执行 workflow_create_and_publish.js（登录 → 创建并导入 → 发布 → 轮询审核）。注意：把题目写成 examples/*.json 只是本地稿；仅在用户确认上线后再运行该脚本（或 import_project.js 及后续发布）才会在问卷网导入并对外开收；趣味测试/活动推广类 勿在「写完 JSON」处停止，也勿在用户未确认时擅自跑发布命令。Agent：用户确认后，若适用已登记活动题库，应在同一会话内执行 npm run publish:valentines / publish:labor / publish:april-fools / publish:april-fools-fun / publish:singles-day（Skill 根目录，见 package.json）或等价 node scripts/publish_preset.js …，并汇报终端结果；未确认前可提供命令行供用户自行执行。题目来源四选一：(A) 主题/场景默认模板（--title + --type，可选 --scene）(B) 本地题目 JSON（-f / --text-file，.json 或内容为 JSON 的 .txt）(C) 链接（-u / --url，http(s) 可访问的题目 JSON）(D) 标准输入（--stdin，管道/重定向 JSON）。设计稿可为 txt / docx / xlsx / pdf：除「已是 JSON 的 txt」外，均须先转为题目 JSON 再 --file（见 references/create_survey.md「稿件支持的文档格式」）。并按类型传参：

  • 调研：--type survey（可省略，默认多为 survey）
  • 测评/打分/趣味测试结果：--type assess
  • 投票/评选：--type vote
  • 表单/报名/信息登记：--type form 不要把投票、表单、测评误作成 survey，否则题型与后台能力不匹配。

模糊场景

功能列表与参考文档

核心工作流

工作流 1：新建问卷

使用 workflow_create_and_publish.js（或等价步骤）时：

1. 检查/获取登录凭证
2. 创建项目并导入题目（textproject / 默认模板，或 `--file` / `--text-file` / `--url` / `--stdin` 的题目 JSON；**稿为 txt/docx/xlsx/pdf 时**先转为 JSON，见 `references/create_survey.md`「稿件支持的文档格式」）
   • 调研：--type survey（常见默认）
   • 测评/打分测验：--type assess（题目须含 score 等测评结构）
   • 投票/评选：--type vote
   • 表单/报名登记：--type form
3. 发布项目（update_project_status）
4. 如遇 NOT_BIND_MOBILE，先 bind_mobile 再重试发布
5. 发布成功后自动轮询审核与项目状态，直至稳定或超时（不可关闭）

一键命令示例见 references/create_survey.md。调研 / 测评 / 投票 / 表单共用本脚本，仅 --type（及题目 JSON）不同。

工作流 2：编辑问卷

1. 执行鉴权检查
2. 调用 list_projects 展示列表，用户选择项目
3. 调用 fetch_project 获取问卷完整结构
4. 如需修改项目信息（标题/欢迎语/结束语）→ 调用 update_project
5. 如需编辑题目 → 调用 **edit_question.js**（文档见 update_question）
6. 如需新增题目 → 调用 create_question.js
7. 如需删除题目 → 调用 delete_question.js

⚠️ 重要：编辑问卷结构或项目信息前，工作流会先 停止收集（若当前为收集中），再调用 项目归档（POST /report/ajax/project_archive/：Query 含 pid 与 ai_skills 签名，见 references/project_archive.md），归档成功后才执行改题/改项。也可手动先 publish_survey(action=stop)；编辑完成后不会自动重新发布，如需恢复收集请手动 publish_survey(action=publish)。

工作流 3：查看数据（数据概况 / 报表页 / 原始导出）

1. 执行鉴权检查
2. 调用 list_projects 选择项目（或已知 project_id）
3. 若只需即时数字概况（答卷数、今日答卷、浏览量、完成率等）→ 调用 overview_stats（`overview_stats.js`；接口 URL 已带与 **generate_sign（ai_skills）** 一致的 `appkey`/`web_site`/签名）
4. 若需报表可视化页面 → 调用 get_report（`open_report.js`）打开 `/report/topic/{project_id}`（`--no-open` 仅打印链接）
5. 如需原始数据 → 调用 export_data

环境准备

本 Skill 需要 Node.js 18+ 环境。

快速安装（推荐）

./setup.sh -y    # 自动安装 Node.js 和依赖

一键完成：检测 Node.js → 自动安装（如需要）→ 打印当前 npm registry（不修改源）→ 安装依赖 → 验证环境。setup.sh 成功结束时的输出只说明 Node/依赖已就绪，不会引导「接下来去登录」；需要调用问卷网接口时再按 references/auth.md 完成登录。

支持系统： macOS, Ubuntu/Debian, CentOS/RHEL/Fedora, Arch Linux, openSUSE, Alpine, Windows

Workerbuddy / 无图形界面登录问卷网： 执行 node scripts/login_auto.js，脚本会始终尝试自动打开浏览器；若在 Agent 环境无可见窗口，请使用获取二维码后已写入的 last_wenjuan_login_url.txt 内整行链接，在本机浏览器扫码。扫码后不要关运行脚本的终端，直至出现登录成功。详见 references/auth.md。

减少重复扫码： 若本地已有未过期凭证（token_store 约定的 ~/.wenjuan/、项目内 .wenjuan/auth.json 等），login_auto.js 与 workflow_create_and_publish.js 内嵌登录会跳过再次拉二维码；仅在服务端判定需重新登录（如 NEED_LOGIN）或你使用 node scripts/login_auto.js --force-login 时才会重新扫码。Workerbuddy 若每次任务沙箱清空主目录，请把凭证目录指到持久卷：设置环境变量 WENJUAN_TOKEN_DIR 指向固定路径，避免每轮任务都误判「未登录」而反复扫码。

其他选项

./setup.sh       # 交互式安装
./setup.sh -c    # 仅检查环境
./setup.sh -v    # 验证安装
./setup.sh -h    # 显示帮助

详细说明

• 环境要求、手动安装步骤、常见问题 → 详见 references/check_env.md
• 二次验证环境 → 使用 check_env 工具

版本更新检查

建议触发时机：每天第一次打开时自动检查

强制触发规则（WorkerBuddy）：

• 当用户输入「升级版本 / 更新版本 / 升级到最新 / 更新到最新」等同义表达时，必须立即执行版本检查，不等待“每日首次”时机。
• 版本检查后若 has_update=true（或 latest > current_version），必须立刻进入更新流程，不能只提示不执行。
• 更新完成后，必须再次读取本地 package.json 的 version 进行核验，并向用户输出“更新前版本 → 更新后版本”。
• 若检查、下载或安装失败，必须返回明确失败原因，并给出可执行的下一步（优先引用接口 instruction）。

检查当前 Skill 版本是否需要更新：

node scripts/check_version.js

快速使用

发现新版本处理

当检测到新版本时，提示用户安装最新版本：

const { checkVersion, shouldUpdate } = require('./scripts/check_version');

const result = await checkVersion();

if (shouldUpdate(result)) {
    const data = result.data;
    console.log(`📦 发现新版本: ${data.latest}`);
    console.log(`当前版本: ${data.current_version}`);
    console.log(`\n更新内容:\n${data.release_note}`);
    // 服务端下发的更新说明（优先遵循）
    if (data.instruction) {
        console.log(`\n更新指引:\n${data.instruction}`);
    }
}

升级指令标准流程（必须执行）

当用户明确要求“升级到最新版本”时，按以下顺序执行且不可省略：

1. 运行 node scripts/check_version.js --json 获取版本信息。
2. 判断是否需要更新（has_update=true 或 latest > current_version）。
3. 若需更新：优先按接口返回的 instruction 执行下载与安装。
4. 安装后读取本地 package.json 的 version 做二次确认。
5. 向用户返回：当前版本、最新版本、升级结果、失败原因（如有）。

提示方式：

• 在对话开始时显示更新提示
• 告知用户当前版本和最新版本号
• 优先展示接口返回的 instruction；不要默认用户已安装 Git 或目录名为某一固定文件夹

更新途径（按实际分发方式选一种，互不假设）：

• Cursor / 技能市场 / 插件：在对应入口重新安装或拉取新版 Skill，通常不需要也不能保证本机有 git。
• ZIP 包（如 pack_skill.sh 生成的 wenjuan-survey-skill-*.zip）：下载新版压缩包并解压覆盖或替换原目录。
• Git 克隆：仅在用户确认本机有 Git 且当前目录是克隆下来的仓库时，才建议在 Skill 根目录（例如本仓库名为 wenjuan-survey，以你本机路径为准）执行 git pull。

详细说明 → 详见 references/version_check.md

数据模型

问卷（Project）
├── 基本信息：project_id, title, ptype_enname, scene_type, status
├── 设置：begin_desc(欢迎语), end_desc(结束语), appearance_themenum
├── 页面列表（Pages[]）
│   └── 题目列表（Questions[]）
│       ├── 基本属性：question_id, question_type, title, is_required
│       ├── 选项列表（Options[]）：option_id, title, is_open
│       └── 矩阵行（MatrixRows[]）：title
└── 查看报表 ← `https://www.wenjuan.com/report/topic/{project_id}`（`get_report` / `open_report.js`）；**数据概况** ← `overview_stats.js`（`/report/api/v2/overview/stats/{pid}/`，**签名同** `generate_sign.js`）；原始答卷 ← `export_data`

签名认证说明

编辑类（app_api/edit/...）、报表下载（/report/api/download*）与 数据概况（/report/api/v2/overview/stats/...）的 URL 查询签名，均使用 scripts/generate_sign.js 中的同一 CONFIG（web_site=ai_skills、appkey、secret，MD5 signature）。

用法示例（buildSignedUrl）

const { buildSignedUrl } = require('./scripts/generate_sign');

const baseUrl = "https://www.wenjuan.com/app_api/edit/xxx/";
const params = { project_id: "xxx" };
const fullUrl = buildSignedUrl(baseUrl, params);
// 自动添加：appkey, web_site, timestamp, signature

查询参数名：

• appkey：应用标识（与旧版报表 app_key 已统一为 ai_skills 的 appkey）
• web_site：固定为 ai_skills
• timestamp：秒级时间戳
• signature：参与签名的参数按名字母序拼接各参数值后加 secret 再 MD5（小写 hex），逻辑见 generate_sign.js

报表脚本：export_data.js 的 buildUrlWithAuth 内部调用 buildSignedUrl；overview_stats.js 复用 buildUrlWithAuth。详见 references/overview_stats.md。

常见错误码

认证相关

⚠️ 遇到以下错误码时，需要重新执行扫码登录：

项目相关

题目相关

其他

注意事项

1. 编辑前停止收集 + 项目归档：脚本通过 ensureReadyForEdit 自动处理——收集中则先 stop，再调归档接口直至成功；归档未完成则不会继续编辑（详见 references/project_archive.md）。禁止绕过：修改项目信息、题目或选项时，不得通过覆盖 QuestionEditor 方法、直接 require 后只调 updateProject/updateQuestion/createQuestionApi 的旧路径、或手写 edit_project/edit_question 请求等方式跳过上述步骤；须使用 update_project.js、edit_question.js、create_question.js、delete_question.js 的官方 CLI 或模块导出函数（其内部已统一停收 + 归档）。若归档报权限错误，应在问卷网侧解决权限，而不是在会话内跳过守卫。
2. Token 有效期：access_token 有过期时间，失效后需重新登录
3. 发布需绑定手机号：首次发布项目时可能需要先绑定手机号
4. 签名时效：签名使用当前时间戳，有效期较短，每次请求需重新生成
5. 运行环境：功能脚本均为 Node.js（.js）；JWT 的目录与读取顺序由 scripts/token_store.js 统一实现（工程内 .wenjuan/auth.json 优先，其次用户级目录下的 token.json / access_token；用户级目录默认为 ~/.wenjuan，可用环境变量 WENJUAN_TOKEN_DIR 或各脚本 --token-dir 覆盖）。详见 references/auth.md。
6. 默认路径（约定）：扫码登录后主凭证 ~/.wenjuan/token.json；原始数据导出默认目录 ~/.wenjuan/download/（均可被 WENJUAN_TOKEN_DIR / --token-dir、-o 覆盖，见 references/auth.md）。

目录结构

wenjuan-survey/
├── SKILL.md                    # 本文档
├── setup.sh                    # 环境检测与安装脚本
├── package.json                # Node.js 依赖包列表
├── package-lock.json           # npm 锁定文件
├── node_modules/               # 依赖包目录
├── scripts/                    # 所有功能脚本
│   ├── workflow_create_and_publish.js
│   ├── publish_preset.js       # 节日测评一键发布（npm run publish:*）
│   ├── list_projects.js
│   ├── fetch_project.js        # 获取项目详细结构
│   ├── update_project.js       # 更新项目信息
│   ├── publish.js
│   ├── project_edit_guard.js   # 编辑前：stop（若收集中）+ 项目归档成功
│   ├── project_archive.js      # 项目归档 API 封装（可被 guard / CLI 调用）
│   ├── bind_mobile.js          # 绑定手机号
│   ├── create_question.js
│   ├── edit_question.js
│   ├── delete_question.js
│   ├── export_data.js
│   ├── overview_stats.js       # 数据概况（Stats v2）
│   ├── open_report.js          # get_report：查看报表，默认打开浏览器
│   ├── generate_sign.js
│   ├── token_store.js          # JWT 路径与读取顺序（单一来源）
│   ├── login_auto.js
│   ├── check_version.js        # 版本检查
│   ├── pack_skill.sh           # 打分发包（zip，排除 node_modules / examples / downloads / .wenjuan）
│   └── check_env.js            # 环境验证（需先装Node.js）
├── references/                 # 各功能详细文档
│   ├── auth.md
│   ├── create_survey.md
│   ├── list_projects.md
│   ├── fetch_project.md        # 获取项目结构文档
│   ├── update_project.md       # 更新项目信息文档
│   ├── bind_mobile.md          # 绑定手机号文档
│   ├── create_question.md
│   ├── update_question.md
│   ├── delete_question.md
│   ├── project_archive.md      # 项目归档接口与编辑工作流
│   ├── publish_survey.md
│   ├── get_report.md           # 查看报表定义与用法
│   ├── export_data.md
│   ├── overview_stats.md       # 数据概况 API 与用法
│   ├── version_check.md
│   ├── check_env.md
│   ├── skill_overview.md       # 触发/工作流/错误码等总览（与本文档互补）
│   └── url_signing.md          # URL 查询签名说明
└── examples/                   # 示例文件
    ├── sample_questions.json   # 题目列表示例
    ├── sample_project.json     # 完整项目数据示例
    ├── university_student_survey.json
    └── i_love_shanghai_survey.json