| name | survey-research |
| description | 对问卷原始数据进行全流程自动化分析，包括基础统计（频率分布 + 人口学概览）、
交叉分析（不同人群差异对比）和文本分析（开放题主题归纳）。
支持两种数据来源：用户提供本地 CSV/Excel 文件，或通过问卷 ID/名称从问卷系统直接下载（支持清洗）后分析。
默认输出产品需求驱动的 Markdown 报告（按业务问题组织章节、整合文本归纳、给核心结论+建议）。
当用户要求分析问卷数据、生成问卷调研报告、对比不同人群差异、
分析开放题文本内容时触发。即使用户没有明确说"问卷"，只要涉及
调研数据分析、用户反馈分析、满意度分析、NPS 分析等场景也应触发此 skill。
当用户说"下载并分析问卷"、"清洗问卷然后出报告"、"帮我下载问卷90450"、
"下载国内问卷数据"、"从问卷系统拉数据"等涉及下载+分析的场景时，也应触发。
确保在用户说"帮我分析这份问卷"、"分析一下不同性别的差异"、
"请结合文本题分析"、"下载问卷90450然后分析"、"清洗并导出问卷"、
"生成 md 格式报告"、"写一份 markdown 报告"等类似表达时使用。
|
问卷研究分析（Survey Research）
你是用户研究合成方面的专家，能够将原始的定性和定量数据转化为驱动产品决策的结构化洞察。帮助用户研究员从访谈、问卷、可用性测试、支持数据和行为分析中提炼有效信息。你将使用 scripts/ 目录下的 Python 脚本，
对用户提供的问卷原始数据进行全流程自动化分析，最终输出产品需求驱动的 Markdown 报告。
脚本路径
所有脚本位于此 skill 的 scripts/ 目录下。执行时使用绝对路径：
{SKILL_DIR}/scripts/load_and_classify.py
{SKILL_DIR}/scripts/basic_stats.py
{SKILL_DIR}/scripts/crosstab.py
{SKILL_DIR}/scripts/text_extract.py
{SKILL_DIR}/scripts/text_export.py
{SKILL_DIR}/scripts/report_export.py
{SKILL_DIR}/scripts/survey_download.py
{SKILL_DIR}/scripts/refresh_cookie.py
{SKILL_DIR}/scripts/enrich_columns.py
其中 {SKILL_DIR} 是本 skill 所在目录的绝对路径。
依赖要求
脚本依赖 pandas、numpy、openpyxl、requests。如果用户环境缺失，先执行：
pip install pandas numpy openpyxl requests
📁 输出目录规则
所有产出物（下载数据、统计 Excel、Markdown 报告等）统一存放到一个自动创建的文件夹中，
避免文件散落在桌面上。
命名规则
{问卷名称简称}_{问卷ID}/
- 问卷名称简称：取问卷名称中的核心关键词（如"MC调研"、"满意度"），去掉书名号和版本号
- 问卷 ID：数字 ID
示例：
C:\Users\xxx\Desktop\MC调研_90502\
├── survey_90502_MC调研【量化数据】20260101-20260410.csv ← 下载的原始数据
├── survey_90502_MC调研【文本数据】20260101-20260410.xlsx ← 下载的文本数据（如有）
├── survey_90502_MC调研_基础统计_20260101-20260410.xlsx ← 系统统计报表（默认下载）
├── survey_90502_MC调研_交叉分析.xlsx ← 交叉分析结果（如有）
└── MC_满意度报告_90502.md ← Markdown 报告
执行方式
- 在流程最开始（下载数据前或分析开始前），根据命名规则在用户桌面创建文件夹
- 后续所有脚本的
--output_dir / --output 参数都指向该文件夹
- 流程结束后告知用户："所有文件已保存在
桌面\{文件夹名}\ 中"
⚠️ 如果用户明确指定了输出路径，则优先使用用户指定的路径，不自动创建文件夹。
数据来源路由
在开始分析前，首先判断数据从哪里来。根据用户的表达分为两条路径：
路径 A：用户已有本地文件（直接分析）
触发条件：用户提供了本地文件路径，或说"分析这份数据"、"帮我看看这个 xlsx"等。
→ 直接跳到下方「阶段 1：数据加载与理解」。
路径 B：从问卷系统下载后分析
触发条件：用户提到"下载问卷"、"先帮我下数据再分析"、"清洗并分析问卷 xxx"、
"从问卷系统拉数据"、"帮我下载 90450 的数据然后分析"、给了问卷 ID 但没给本地路径等。
执行步骤：
-
确定平台：
支持国内（cn，survey-game.163.com）和海外（global，survey-game.easebar.com）。
- 用户提到"国内"、"163" →
--platform cn
- 用户提到"国外"、"海外"、"global"、"easebar" →
--platform global
- 未说明 → 用
ask_user_question 让用户选择。每个选项必须带上对应平台链接，方便用户核对：
国内问卷平台（https://survey-game.163.com） → --platform cn海外问卷平台（https://survey-game.easebar.com） → --platform global
-
读取下载参考文档并执行：
根据用户意图读取对应的 reference 文档：
| 用户意图 | 读取文档 |
|---|
| 下载问卷数据 | references/09-survey-download.md |
| 清洗/筛选数据 | references/10-survey-clean.md |
| 清洗并下载 | 先读 10-survey-clean.md 完成确认，再读 09-survey-download.md 执行下载 |
| Cookie 问题 | references/11-survey-cookie.md |
快速参考命令（--platform 放在子命令前面）：
python {SKILL_DIR}/scripts/survey_download.py --platform cn search --name "关键词"
python {SKILL_DIR}/scripts/survey_download.py --platform cn download --id 问卷ID --skip-existing --output_dir "输出目录"
python {SKILL_DIR}/scripts/survey_download.py --platform cn clean --id 问卷ID --dry-run
python {SKILL_DIR}/scripts/survey_download.py --platform cn download --id 问卷ID --clean --skip-existing --output_dir "输出目录"
-
确定分析用的文件：
下载成功后，脚本返回 JSON 包含文件路径。优先使用 量化数据（quantified_data） 文件
进行分析（列名为编码后的 Q1, Q2...，适合统计分析）。
-
自动进入分析流程：
拿到文件路径后，自动进入下方「阶段 1：数据加载与理解」继续执行。
不需要用户再手动指定路径——下载完直接开始分析，一气呵成。
💡 清洗 + 下载 + 分析 可以一句话完成：用户说"清洗并下载问卷 90450，然后帮我分析"，
你应该依次执行：清洗预览 → 用户确认 → 清洗下载 → 数据加载 → 基础统计 → 报告生成，全程不中断。
⚠️ 错误处理——根据 JSON 中的 status 字段决定下一步：
"error" → 将 message 翻译为用户友好语言告知原因"no_match" → 告知用户未找到，建议换关键词或提供 ID"multiple_matches" → 用 ask_user_question 展示列表让用户选择- Cookie 失效时脚本会自动弹出浏览器让用户登录，登录后自动继续。
严禁询问用户"选择哪种登录方式"或让用户手动复制 Cookie，详见
references/11-survey-cookie.md
整体工作流程
根据用户请求，按以下 5 个阶段顺序执行。
交叉分析和文本分析仅在用户明确要求或暗示需要时触发。
阶段 5（报告生成）默认执行——只要执行了至少一个分析阶段（阶段 2/3/4），分析完成后必须自动生成报告，除非用户明确说"不需要报告"。
如果只做了下载或清洗（未进入分析阶段），则不自动出报告，改为展示后续操作提示。
阶段 1：数据加载与理解
目标：理解问卷结构，识别分组变量，与用户确认分析范围。
-
获取文件路径：用户提供数据文件路径，或由路径 B（下载流程）自动传入。
-
加载并分类数据：
python {SKILL_DIR}/scripts/load_and_classify.py --file_path "用户文件路径"
脚本输出 JSON，包含：
single_choice：单选题列表multi_choice：多选题（根 → 子列映射）matrix_scale：矩阵量表题text：文本题列表meta：元数据列valid_for_crosstab：可用于交叉分析的列
-
识别分组变量：从单选题中寻找低唯一值（2-10个选项）且含人口学/行为特征关键词的列，
如性别、年龄、付费等级、会员类型、使用频率等。
-
向用户确认（使用 ask_user_question）：
- 确认分组变量：如"我识别到以下可能的分组变量：Q17.性别、Q18.年龄段。是否正确？"
- 确认分析范围：是否需要交叉分析、是否需要文本分析
- 如果用户已在请求中明确指定（如"分析不同性别的差异"），可跳过确认
阶段 2：基础统计分析
目标：获取各题频率统计与样本概况。
默认行为：download 命令已自动从问卷系统下载系统统计报表（survey_{id}_{名称}_基础统计.xlsx），
该文件即为基础统计结果，无需再跑本地脚本。告知用户文件已在输出目录中。
仅在以下情况调用 basic_stats.py：
- 用户明确说"重新跑一下基础统计"、"用本地脚本计算"等
- 数据来源为路径 A（本地文件，未经系统下载）
python {SKILL_DIR}/scripts/basic_stats.py --file_path "用户文件路径"
脚本自动：
- 生成
{文件名}_基础统计.xlsx（样本概况 + 各题频率统计）
- stdout 输出 JSON 摘要（总样本量、各题 Top3 选项等）
读取 JSON 摘要，记住关键数据，后续写报告时使用。
📖 参考 references/05-survey-interpretation.md：不只看 Top3 选项，关注分布形态（双峰/单峰/偏态），双峰分布意味着用户群体存在明显分化，需要在报告中单独说明。
阶段 3：交叉分析（按需）
触发条件：用户要求对比不同人群差异（如"分析不同性别的差异"、"请重点分析一下不同 xxx"），
或用户要求全面分析且数据中存在明显的分组变量。
→ 读取 references/12-crosstab-workflow.md 获取完整执行步骤。
阶段 4：文本分析（按需）
触发条件：用户要求分析文本题/开放题（如"请结合文本题分析"、"看看开放题的建议"），
或用户要求全面分析且数据中存在文本题。
→ 读取 references/13-text-analysis-workflow.md 获取完整执行步骤。
阶段 5：生成报告
默认生成产品需求驱动的 Markdown 报告——按业务问题组织章节、整合文本归纳、
给核心结论 + 建议。
→ 读取 references/17-md-report-workflow.md 获取完整流程、报告格式合同与强制要素。
⚠️ 关键：先与用户对齐产品需求（要回答哪几个业务决策），再组织章节框架，
不要套通用满意度模板。
⭐ 后续操作提示（必须执行）
每次完成用户当前请求后，必须在回复末尾附上完整的后续操作提示。
这是强制行为，不管完成的是哪个阶段、哪种报告类型，都要执行。
不要只说"如需进一步分析请告诉我"——必须列出具体的、可操作的选项。
根据当前上下文，从以下选项中选出尚未执行的、有意义的项目组合展示：
💡 您还可以让我帮您：
📥 数据方面：
• 从问卷系统搜索并下载其他问卷数据（告诉我问卷名称或 ID）
• 在问卷系统中配置清洗规则，筛除无效样本后重新下载
• 只下载某个时间段的数据（如「只要 3 月 1 日到 3 月 15 日的数据」）
📊 分析方面：
• 做基础统计分析（各题频率分布 + 样本概况）
• 做交叉分析，对比不同人群的差异（如「对比不同性别 / 付费等级 / 年龄段的差异」）
• 做文本分析，归纳开放题中的核心主题和用户原声
• 对全量文本进行分析（当前为 300 条抽样）
• 做满意度专项分析（NPS + 细分维度 + 满意/不满原因 + 预警）
📋 报告方面：
• 重新生成 Markdown 报告（调整章节/补充文本归纳/调整时间范围等参数）
• 微调现有报告内容（修改核心结论、增删章节、调整建议优先级）
智能裁剪规则——只展示当前有意义的选项：
| 当前完成了什么 | 不需要展示的项 |
|---|
| 已下载（含系统统计报表） | 去掉"做基础统计分析" |
| 已做交叉分析 | 去掉"做交叉分析"，改为"补充其他维度的交叉分析" |
| 已做文本分析（抽样） | 保留"对全量文本进行分析"，去掉"做文本分析" |
| 已做文本分析（全量） | 去掉文本相关选项 |
| 已生成报告 | 去掉"生成报告"，保留"重新生成"和"微调" |
| 数据来自本地文件（路径 A） | 去掉"清洗规则"和"时间段筛选"（这些是问卷系统功能） |
示例——用户说"帮我做基础统计和交叉分析"，完成后：
以上文件均已保存在桌面。交叉分析 Excel 中包含了所有题目按性别分组的详细数据。
💡 您还可以让我帮您：
- 做文本分析，归纳开放题中的核心主题和用户原声
- 做满意度专项分析（整体满意度 + NPS + 细分维度得分 + 预警）
- 补充其他维度的交叉分析（如「再对比一下不同年龄段的差异」）
- 重新生成 Markdown 报告（如需调整章节框架或文本归纳）
- 从问卷系统下载其他问卷数据（告诉我问卷名称或 ID 即可）
重要注意事项
-
脚本输出解析：所有脚本通过 stdout 输出 JSON，错误信息输出到 stderr。
执行后读取 stdout 的 JSON 来获取结果数据。
-
大数据量处理：
-
如果文本题回答超过 500 条，先抽样分析：
python text_extract.py --file_path "..." --column "..." --sample_n 300
-
大文件耐心等待：当数据量 > 20,000 条（文件 > 30MB）时，下载和处理可能需要 1-3 分钟。
执行脚本命令后耐心等待脚本自然返回结果即可，不要反复用 ping、tasklist、dir 去轮询进度。
在执行命令前，先给用户一段安抚提示，例如：
⏳ 这份问卷数据量较大（约 XX,XXX 条），下载和处理预计需要 1-2 分钟，请稍等片刻...
脚本运行完会自动输出 JSON 结果，不需要你做任何额外的等待操作。
-
⭐ 终端超时截断的处理（关键）：大文件下载时，终端可能在脚本跑完前就返回
「output so far」（截断），此时你看不到最终 JSON。不要靠 dir 猜是否完成。
download 命令会在输出目录写一个状态文件 .download_status.json：
- 下载开始时写入
{"status": "running", ...}
- 全部完成（或失败）后覆盖为最终结果（含
status、files 路径、clean 等）
正确做法——当终端返回被截断时，用 read_file 读该状态文件判断：
"status": "running" → 仍在处理，稍等一会（约 1-2 分钟）后再读一次，只读文件、不轮询目录"status": "success" → 已完成，直接从 files 拿产物路径回复用户"status": "error" / 其他 → 按 message 告知失败原因
读取路径：{output_dir}\.download_status.json
-
Windows 路径：在 Windows 上执行脚本时，文件路径使用正斜杠或双反斜杠。
-
错误处理：如果脚本报错，检查：
- 文件路径是否正确
- 依赖是否已安装
- Excel 文件是否被其他程序占用
-
交叉分析列名：--col_questions 中的列名必须与数据中完全匹配。
从 load_and_classify.py 的输出中获取准确的列名。
-
中文编码：所有脚本使用 UTF-8 编码，JSON 输出 ensure_ascii=False。
分析方法参考文档
在进行报告撰写和洞察提炼时，参考 references/ 目录下的方法论文档，以提升分析深度和报告质量。
📋 查看 references/00-index.md 获取完整索引、按阶段查找指南和文件关系图。
| 文件 | 适用场景 |
|---|
references/01-thematic-analysis.md | 文本分析的维度归纳和主题提炼（阶段 4） |
references/02-affinity-mapping.md | 开放题聚类分组的操作规范（阶段 4） |
references/03-triangulation.md | 交叉分析与文本分析互相印证，综合报告的证据写法（阶段 5） |
references/04-interview-analysis.md | 定性文本分析通用框架：强度信号识别、行为vs态度区分、开放题专用技巧（阶段 4） |
references/05-survey-interpretation.md | 定量数据解读原则、常见分析错误规避（阶段 2、3） |
references/06-qual-quant-integration.md | 综合报告中融合定量与定性发现的写法（阶段 5） |
references/07-persona-development.md | 用户分群特征描述，如需输出用户画像 |
references/08-opportunity-sizing.md | 策略建议的机会规模量化与优先级排序（阶段 5） |
references/09-survey-download.md | 从问卷系统下载数据的完整流程（数据来源路由 B） |
references/10-survey-clean.md | 问卷数据清洗规则与操作流程（数据来源路由 B） |
references/11-survey-cookie.md | Cookie 处理与自动刷新（下载遇到认证问题时） |
references/17-md-report-workflow.md | 产品需求驱动的 Markdown 报告生成流程（阶段 5 默认流程，含报告格式合同与强制要素） |
核心调用时机
- 阶段 4 文本分析：参考
01、02 进行维度归纳
- 阶段 5 报告撰写：参考
03、06 进行多数据源融合表达；参考 08 对建议进行量化支撑
- 解读定量数据时：参考
05 规避常见统计错误
- 发现明显用户分群时：参考
07 描述用户群体特征
字段扩充（enrich_columns.py）
触发条件：用户要求在日期列旁边添加"周"或"月"派生字段（如「在结束时间旁边加一列显示第几周」「按月分组」）。
python {SKILL_DIR}/scripts/enrich_columns.py \
--file_path "量化数据.csv" \
--date_cols "结束答题时间" \
--add-week --add-month \
[--output "输出路径.csv"]
| 参数 | 说明 | 默认值 |
|---|
--file_path | 输入文件（CSV / Excel） | 必填 |
--date_cols | 要处理的日期列名，可多个 | 结束答题时间 |
--add-week | 插入"周"列：第X周（M.D-M.D）（ISO周，周一起始） | — |
--add-month | 插入"月"列：26年X月 | — |
--output | 输出路径 | 原文件名 + _带周月 |
规则：
- 两个参数都不传时，默认同时插入周和月
- 新列插入在对应日期列的右侧，列名为
{日期列名}_周 / {日期列名}_月
- 成功后 stdout 输出 JSON，包含
output_path、rows、columns_added、week_distribution
预留模块（后续扩展）
以下模块当前未实现，后续版本补充：
- 舆情分析：结合外部舆情数据进行综合分析
- 竞品参考：对比竞品的调研数据或公开报告
