问卷网 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，否则题型与后台能力不匹配。

• 确认交互（操作按钮）：展示标题、类型、题目概要后，必须明确说明选择“直接创建”会在问卷网账号中创建项目、发布并开始收集；随后在回复末尾提供两个可点击的操作按钮，按钮文案必须分别为：

  • 返回修改
  • 直接创建

  原生交互优先：先检查当前会话实际提供的工具；若存在交互选择、提问、建议回复或按钮工具，必须调用该工具创建原生按钮，不要仅在正文中罗列选项。Skill 文本本身不能制造客户端按钮，因此不得在未调用交互工具时声称已经提供按钮。仅在当前工具列表没有任何原生交互能力时，才回退为回复末尾两行纯文本，顺序固定为“返回修改”“直接创建”。禁止只写“请回复‘直接创建’”而遗漏“返回修改”，也不得用 Markdown 链接或 HTML 模拟按钮。

  用户点击“直接创建”按钮即完成确认，必须立即执行创建发布工作流；不得再要求用户输入“直接创建”，也不得进行第二次确认。点击“返回修改”时只继续修改题目，不得创建、导入或发布。仅在客户端没有原生交互工具、已回退为纯文本选项时，用户才需要输入对应文字。

• 发布成功结果必须对用户可见（硬性）：工作流结束后，上述「项目标题 / 项目 ID / 题目数量 / 当前状态 / 答题链接 / 二维码海报」信息块 + 海报文件附件，必须写进面向用户的最终回复正文，让用户在聊天主界面直接看到。禁止只出现在工具输出、终端日志、折叠的过程/思考消息、侧栏产物列表而不在最终回复里复述；禁止用“已完成，详见过程消息/产物”一类话术代替。否则用户拿不到链接与海报，无法继续使用。

• 复用已有同主题项目时同样必须带海报（硬性）：若因「同一主题不得刷测试项目」检测到账号侧已有同主题问卷、本次未新建，最终回复仍须给出完整可用信息（含答题链接与二维码海报）。须先用已有 survey_link（或 short_id）调用 node scripts/generate_share_poster.js --title "..." --url "..." --project-id "..." 生成海报，再按下方格式展示；禁止只列标题/ID/链接而无海报附件。可先用一两句说明“检测到同主题已存在、未新建”，随后仍输出同一套字段块 + 海报文件附件。

• 最终回复格式（固定，新建成功与复用已有均适用）：最终回复必须按以下顺序与字段展示（字段名加粗，取值跟在冒号后；勿增删字段、勿改顺序）。海报不要用 Markdown/HTML 内联渲染成大图；应在信息块下方以文件附件/产物卡片附上 poster_path（效果：文件名 + 大小，可下载打开）：

  **项目标题：** <title>
  **项目 ID：** <project_id>
  **题目数量：** <question_count> 道
  **当前状态：** 收集中
  **答题链接：** <survey_link>
  **二维码海报：** 已生成并展示，可直接扫码填写。
  
  <以文件附件附上 poster_path，例如：大学生恋爱观与恋爱现状调查-<project_id>.png>
  

  示例（新建成功）：

  **项目标题：** 大学生恋爱观与恋爱现状调查
  **项目 ID：** 6a8fa7a1e9cf9ea0b999b8ee
  **题目数量：** 23 道
  **当前状态：** 收集中
  **答题链接：** https://www.wenjuan.com/s/UZBZJvUStK6
  **二维码海报：** 已生成并展示，可直接扫码填写。
  

  示例（复用已有，可加简短说明后接同一字段块）：

  检测到同主题问卷已存在，为避免重复创建，本次未新建项目。
  
  **项目标题：** 大学生恋爱观与恋爱现状调查
  **项目 ID：** 6a8fa7a1e9cf9ea0b999b8ee
  **题目数量：** 23 道
  **当前状态：** 收集中
  **答题链接：** https://www.wenjuan.com/s/UZBZJvUStK6
  **二维码海报：** 已生成并展示，可直接扫码填写。
  

  随后附上海报文件产物（聊天中显示为附件卡片，而非内联预览图）。禁止输出 ![问卷二维码海报](...) 或 <img ...>。若海报生成失败：将「二维码海报」一行改为失败原因，不附文件，并保留答题链接。若仍在审核中，将「当前状态」写为「审核中」。复用已有时可在字段块后补充一句「如需修改题目或标题，可直接编辑该项目」。

模糊场景

用户表述	处理方式
「帮我做个投票」/「评选」/「票选」	workflow_create_and_publish.js + --type vote + --title（或 --file / --url / --stdin 等 JSON）；见 references/create_survey.md
「做个表单」/「报名表」/「信息登记」/「收集联系人」	workflow_create_and_publish.js + --type form + --title（或 JSON 导入）；见 references/create_survey.md
「做个考试」/「做个调研」	workflow_create_and_publish.js + --type survey（或默认 survey）+ --title / JSON 导入
「做个测评」/「新建测评问卷」/「趣味测试带结果」	workflow_create_and_publish.js + --type assess + 题目 JSON（选项含 score）或默认测评模板；见 references/create_survey.md
「按这个链接里的题目建问卷」/「从 URL 导入」	workflow_create_and_publish.js + --url + 按需 --type / --title（链接体为题目 JSON）
「把下面文本/JSON 建成问卷」	将提纲整理为题目 JSON 后 --file / --text-file / --stdin + 正确 --type
「按 Word / Excel / PDF / 文档里的题目建问卷」	txt：提纲或 JSON → 整理为题目 JSON；docx / xlsx / pdf：按 references/create_survey.md「稿件支持的文档格式」抽取或读表 → 题目 JSON → workflow_create_and_publish.js + --file + 正确 --type；docx 示例见 examples/college_pocket_money_from_docx.json
「收集一下大家的意见」	直接使用本 skill
「查看我的问卷」	调用 list_projects 获取列表
「编辑问卷的第X题」	先 list_projects 选择，再 fetch_project 获取结构，再用 edit_question.js（references/update_question.md）编辑题目
「修改问卷标题」	使用 update_project 修改标题
「查看问卷结构」	使用 fetch_project 获取详细结构
「需要绑定手机号」	使用 bind_mobile 完成手机号绑定
「看看问卷的回答」	查看报表＝打开 https://www.wenjuan.com/report/topic/{project_id}，使用 get_report（open_report.js，默认自动用浏览器打开；不要弹窗时加 --no-open）
「下载问卷数据」	调用 export_data 导出数据
「回收多少份」「数据概况」「完成率多少」	调用 overview_stats（overview_stats.js），或再看报表页 open_report.js
「退出登录」「清空授权」「删掉 token」	手动删除本机凭证文件（见 references/auth.md「清除本机登录态（手动）」）

功能列表与参考文档

功能名称	功能说明	参考文档
create_survey	创建并发布：一律 workflow_create_and_publish.js；题目来源：默认模板 / --file / --text-file / --url / --stdin（题目 JSON）；稿：txt / docx / xlsx / pdf 先转 JSON；调研 --type survey、测评 --type assess、投票 --type vote、表单 --type form（投票/表单/测评均勿默认成 survey）	references/create_survey.md
list_projects	获取我的问卷列表	references/list_projects.md
fetch_project	获取项目详细结构（题目、页面等）	references/fetch_project.md
update_project	更新项目信息（标题、欢迎语、结束语）	references/update_project.md
create_question	在问卷中新增题目	references/create_question.md
update_question	更新问卷中的某道题目（edit_question.js）	references/update_question.md
delete_question	删除问卷中的题目	references/delete_question.md
publish_survey	发布/停止问卷收集	references/publish_survey.md
get_report	查看报表：默认浏览器打开 /report/topic/{project_id}（open_report.js；列表多条时须交互选；--no-open 仅打印）	references/get_report.md
export_data	下载原始答题数据	references/export_data.md
overview_stats	数据概况：答卷数、今日答卷、浏览量、完成率等（Stats v2 GET；查询签名与 generate_sign.js / export_data 一致）	references/overview_stats.md
bind_mobile	绑定手机号（发布前需要）	references/bind_mobile.md
check_version	检查 Skill 版本更新	references/version_check.md
check_env	仅检查 Node.js 与 npm 依赖（不检查登录/授权）	references/check_env.md

硬性约束：不支持矩阵题型

本 Skill 不支持创建、导入或批量生成矩阵类题型（矩阵单选/多选/打分/填空等）。question_list 中不得出现 QUESTION_TYPE_MATRIX_* 或带 matrixrow_list 的题目；导入时脚本会报错拒绝。

用户需要多维度评价时，请改为 多道量表题、评价题、打分题或单选题；若必须用矩阵，告知用户在问卷网编辑器中手动添加。

硬性约束：同一主题不得刷测试项目

调试题型、改 JSON、试 survey/assess 只允许在本地文件迭代。禁止为同一次需求在用户账号里连续创建 expA/expB、t1、基线、验证、草稿等多份项目。

允许	禁止
本地改 examples/*.json 或题目 JSON，对照 project_json_structure_guide.md	每改一版就跑一次 workflow_create_and_publish.js / import_project.js（含 --no-publish）
用户明确同意后，账号侧只创建 1 个项目	用「实验 / 调试 / 验证 / 基线」标题再开新项目
结构不对：在已有那一个项目上改题（edit_question / create_question），或用户明确说「删掉重来」后再建第 2 个	类型判错就再发一份、旧的留着（如误判 assess 后又发 survey）

计数上限：同一用户主题，未获「再建一个」的明确指令前，账号侧创建次数为 0 或 1。已经有正式项目时，后续只编辑该 project_id。复用已有项目回复用户时，仍须生成并附上二维码海报（generate_share_poster.js），字段块与新建成功相同，不得省略海报。

请求来源参数（Agent 调用时显式传入）

本 Skill 的 Markdown 指引值为：

• 创建项目：--ai-source 12
• 获取扫码二维码/注册来源：--reg-source ai_skills

Agent 调用 workflow_create_and_publish.js 时应显式带上这两个参数，例如：

node scripts/workflow_create_and_publish.js \
  --ai-source 12 \
  --reg-source ai_skills \
  --title "问卷标题" \
  --type survey

若外层 Markdown 指引未加载、旧调用方未传参数，JS 才使用兼容默认值 12 和 ai_skills。接入方需要其他来源值时可通过同名参数覆盖，禁止直接修改请求脚本。

硬性约束：测评必须给出正确答案

创建 assess 测评时必须按题型提供正确答案：单选/多选/判断题在正确选项上设置 custom_attr.is_correct: "1"；填空题在填空项上设置 custom_attr.correct_answer，不使用 is_correct。同时设置对应分值。custom_attr.answer_analysis 只是答案解析，不能替代正确答案；导入脚本会在创建项目之前报错拦截缺少正确答案的题目，不得猜测答案。

核心工作流

工作流 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. 发布成功后自动轮询审核与项目状态，直至稳定或超时（不可关闭）
6. 获取最终答题链接后自动生成二维码海报，输出到 `~/.wenjuan/posters/`
7. 发布成功或复用已有同主题项目时：必须把「最终回复格式」整段写进**面向用户的最终回复**（信息块 + 海报文件附件）；复用场景须先用已有答题链接生成海报；禁止只留在过程/工具输出里、禁止折叠隐藏

一键命令示例见 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

WorkBuddy / 无图形界面登录问卷网： 执行 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 时才会重新扫码。WorkBuddy 若每次任务沙箱清空主目录，请把凭证目录指到持久卷：设置环境变量 WENJUAN_TOKEN_DIR 指向固定路径，避免每轮任务都误判「未登录」而反复扫码。

其他选项

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

详细说明

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

版本更新检查

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

强制触发规则（WorkBuddy）：

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

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

node scripts/check_version.js

快速使用

命令	说明
node scripts/check_version.js	检查版本，显示完整信息；默认退出码 0（含「有新版本」提示），WorkBuddy 不应判为失败
node scripts/check_version.js --auto	自动模式，有更新时才输出
node scripts/check_version.js --json	输出原始 JSON 格式
node scripts/check_version.js --fail-on-update	有新版本时退出码 1（仅 CI 需要严格失败时使用）

发现新版本处理

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

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
└── 查看报表 ← `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。

常见错误码

认证相关

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

错误码	错误信息	说明	解决方案
20004	USER_NOT_EXIST	用户不存在	重新扫码登录
20055	JWT_EXPIRED	jwt_token 过期	重新扫码登录
20056	CAN_NOT_GET_MID_FROM_JWT	jwt 获取不到 mid	重新扫码登录
20057	JWT_DECODE_ERROR	jwt 解析失败	重新扫码登录
20058	GET_JWT_ERROR	获取JWT错误	重新扫码登录或稍后重试
401 / Unauthorized	-	Token 失效或过期	重新扫码登录

项目相关

错误码/错误信息	说明	解决方案
NOT_BIND_MOBILE	未绑定手机号	运行 bind_mobile.js 完成绑定后再发布
PROJECT_PUBLISHED / PROJECT_EDIT_DISABLED	项目收集中无法编辑	先调用 publish_survey(action=stop) 停止收集
PROJECT_NOT_FOUND	项目不存在	检查 project_id 是否正确

题目相关

错误码/错误信息	说明	解决方案
QUESTION_NOT_FOUND	题目不存在	检查 question_id 是否正确
INVALID_PARAM	参数错误	检查请求参数格式和内容

其他

错误码/错误信息	说明	解决方案
SIGNATURE_ERROR	签名错误	检查签名计算逻辑或密钥配置
RATE_LIMIT	请求过于频繁	稍后重试

注意事项

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_share_poster.js # 根据答题链接生成带标题和二维码的分享海报
│   ├── 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 查询签名说明
├── assets/
│   ├── share_poster_template.png   # 分享海报模板 1（设计稿 1080×1920，输出 900×1350）
│   ├── share_poster_template_2.png # 分享海报模板 2（同上）
│   ├── share_poster_template_3.png # 分享海报模板 3（同上）
│   └── share_poster_template_4.png # 分享海报模板 4（生成时四选一随机；输出统一 900×1350）
└── examples/                   # 示例文件
    ├── sample_questions.json   # 题目列表示例
    ├── sample_project.json     # 完整项目数据示例
    ├── university_student_survey.json
    └── i_love_shanghai_survey.json