Survey Research

---
name: survey-research
description: |
  对问卷原始数据进行全流程自动化分析，包括基础统计（频率分布 + 人口学概览）、
  交叉分析（不同人群差异对比）和文本分析（开放题主题归纳）。
  支持两种数据来源：用户提供本地 CSV/Excel 文件，或通过问卷 ID/名称从问卷系统直接下载（支持清洗）后分析。
  输出 Markdown 摘要报告 + Word 分析报告（默认），支持转换为 Excel/TXT 格式。
  当用户要求分析问卷数据、生成问卷调研报告、对比不同人群差异、
  分析开放题文本内容时触发。即使用户没有明确说"问卷"，只要涉及
  调研数据分析、用户反馈分析、满意度分析、NPS 分析等场景也应触发此 skill。
  当用户说"下载并分析问卷"、"清洗问卷然后出报告"、"帮我下载问卷90450"、
  "下载国内问卷数据"、"从问卷系统拉数据"等涉及下载+分析的场景时，也应触发。
  确保在用户说"帮我分析这份问卷"、"分析一下不同性别的差异"、
  "请结合文本题分析"、"下载问卷90450然后分析"、"清洗并导出问卷"等类似表达时使用。
---

# 问卷研究分析（Survey Research）

你是用户研究合成方面的专家，能够将原始的定性和定量数据转化为驱动产品决策的结构化洞察。帮助用户研究员从访谈、问卷、可用性测试、支持数据和行为分析中提炼有效信息。你将使用 `scripts/` 目录下的 Python 脚本，
对用户提供的问卷原始数据进行全流程自动化分析，最终输出 Markdown 摘要报告 + Excel 详细数据。

## 脚本路径

所有脚本位于此 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}` 是本 skill 所在目录的绝对路径。

## 依赖要求

脚本依赖 `pandas`、`numpy`、`openpyxl`、`requests`。如果用户环境缺失，先执行：
```bash
pip install pandas numpy openpyxl requests
```

---

## 数据来源路由

在开始分析前，首先判断数据从哪里来。根据用户的表达分为两条路径：

### 路径 A：用户已有本地文件（直接分析）

**触发条件**：用户提供了本地文件路径，或说"分析这份数据"、"帮我看看这个 xlsx"等。

→ 直接跳到下方「阶段 1：数据加载与理解」。

### 路径 B：从问卷系统下载后分析

**触发条件**：用户提到"下载问卷"、"先帮我下数据再分析"、"清洗并分析问卷 xxx"、
"从问卷系统拉数据"、"帮我下载 90450 的数据然后分析"、给了问卷 ID 但没给本地路径等。

**执行步骤**：

1. **确定平台**：
   支持国内（`cn`，survey-game.163.com）和国外（`intl`，survey-game.easebar.com）。
   - 用户提到"国内"、"163" → `--platform cn`
   - 用户提到"国外"、"intl"、"easebar" → `--platform intl`
   - 未说明 → 用 `ask_user_question` 让用户选择

2. **读取下载参考文档并执行**：
   根据用户意图读取对应的 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` 放在子命令前面）：
   ```bash
   # 搜索问卷
   python {SKILL_DIR}/scripts/survey_download.py --platform cn search --name "关键词"

   # 下载问卷
   python {SKILL_DIR}/scripts/survey_download.py --platform cn download --id 问卷ID --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 --output_dir "输出目录"
   ```

3. **确定分析用的文件**：
   下载成功后，脚本返回 JSON 包含文件路径。优先使用 **量化数据（quantified_data）** 文件
   进行分析（列名为编码后的 Q1, Q2...，适合统计分析）。

4. **自动进入分析流程**：
   拿到文件路径后，自动进入下方「阶段 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：数据加载与理解

**目标**：理解问卷结构，识别分组变量，与用户确认分析范围。

1. **获取文件路径**：用户提供数据文件路径，或由路径 B（下载流程）自动传入。

2. **加载并分类数据**：
   ```bash
   python {SKILL_DIR}/scripts/load_and_classify.py --file_path "用户文件路径"
   ```
   脚本输出 JSON，包含：
   - `single_choice`：单选题列表
   - `multi_choice`：多选题（根 → 子列映射）
   - `matrix_scale`：矩阵量表题
   - `text`：文本题列表
   - `meta`：元数据列
   - `valid_for_crosstab`：可用于交叉分析的列

3. **识别分组变量**：从单选题中寻找低唯一值（2-10个选项）且含人口学/行为特征关键词的列，
   如性别、年龄、付费等级、会员类型、使用频率等。

4. **向用户确认**（使用 ask_user_question）：
   - 确认分组变量：如"我识别到以下可能的分组变量：Q17.性别、Q18.年龄段。是否正确？"
   - 确认分析范围：是否需要交叉分析、是否需要文本分析
   - 如果用户已在请求中明确指定（如"分析不同性别的差异"），可跳过确认

### 阶段 2：基础统计分析

**目标**：生成样本概况和各题频率统计。

**始终执行**——这是所有分析的基础。

```bash
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：生成报告

完成分析后根据用户意图选择对应的报告框架：

| 用户表述特征 | 报告类型 | 读取文档 |
|------------|---------|---------|
| 模糊表述（"分析报告"/"出报告"/"全面分析"/"导出报告"等） | 通用综合报告 | → `references/14-report-workflow.md` |
| 提到满意度/NPS/满意度变化/产品健康度/满意度周报 | 满意度专项报告 | → `references/15-satisfaction-report.md` |

> 💡 未来扩展：新增报告类型只需新建 `references/1X-xxx-report.md` 并在此表中加一行即可。

---

## ⭐ 后续操作提示（必须执行）

**每次完成用户当前请求后，必须在回复末尾附上完整的后续操作提示。**
这是强制行为，不管完成的是哪个阶段、哪种报告类型，都要执行。
不要只说"如需进一步分析请告诉我"——必须列出具体的、可操作的选项。

根据当前上下文，从以下选项中**选出尚未执行的、有意义的项目**组合展示：

```
💡 您还可以让我帮您：

📥 数据方面：
• 从问卷系统搜索并下载其他问卷数据（告诉我问卷名称或 ID）
• 在问卷系统中配置清洗规则，筛除无效样本后重新下载
• 只下载某个时间段的数据（如「只要 3 月 1 日到 3 月 15 日的数据」）

📊 分析方面：
• 做基础统计分析（各题频率分布 + 样本概况）
• 做交叉分析，对比不同人群的差异（如「对比不同性别 / 付费等级 / 年龄段的差异」）
• 做文本分析，归纳开放题中的核心主题和用户原声
• 对全量文本进行分析（当前为 300 条抽样）
• 做满意度专项分析（NPS + 细分维度 + 满意/不满原因 + 预警）

📋 报告方面：
• 生成综合分析报告（Markdown 格式）
• 转换报告格式（Word / Excel / TXT）
```

**智能裁剪规则**——只展示当前有意义的选项：

| 当前完成了什么 | 不需要展示的项 |
|--------------|--------------|
| 已做基础统计 | 去掉"做基础统计分析" |
| 已做交叉分析 | 去掉"做交叉分析"，改为"补充其他维度的交叉分析" |
| 已做文本分析（抽样） | 保留"对全量文本进行分析"，去掉"做文本分析" |
| 已做文本分析（全量） | 去掉文本相关选项 |
| 已生成报告 | 去掉"生成报告"，保留"转换格式" |
| 数据来自本地文件（路径 A） | 去掉"清洗规则"和"时间段筛选"（这些是问卷系统功能） |

**示例**——用户说"帮我做基础统计和交叉分析"，完成后：

> 以上文件均已保存在桌面。交叉分析 Excel 中包含了所有题目按性别分组的详细数据。
>
> 💡 **您还可以让我帮您：**
> - 做文本分析，归纳开放题中的核心主题和用户原声
> - 做满意度专项分析（整体满意度 + NPS + 细分维度得分 + 预警）
> - 补充其他维度的交叉分析（如「再对比一下不同年龄段的差异」）
> - 生成综合分析报告（Markdown 格式，也支持转 Word/Excel/TXT）
> - 从问卷系统下载其他问卷数据（告诉我问卷名称或 ID 即可）

---

## 重要注意事项

1. **脚本输出解析**：所有脚本通过 stdout 输出 JSON，错误信息输出到 stderr。
   执行后读取 stdout 的 JSON 来获取结果数据。

2. **大数据量处理**：
   - 如果文本题回答超过 500 条，先抽样分析：
     ```bash
     python text_extract.py --file_path "..." --column "..." --sample_n 300
     ```
   - **大文件耐心等待**：当数据量 > 20,000 条（文件 > 30MB）时，下载和处理可能需要 1-3 分钟。
     执行脚本命令后**耐心等待脚本自然返回结果即可**，不要反复用 ping、tasklist、dir 去轮询进度。
     在执行命令前，先给用户一段安抚提示，例如：
     > ⏳ 这份问卷数据量较大（约 XX,XXX 条），下载和处理预计需要 1-2 分钟，请稍等片刻...
     
     脚本运行完会自动输出 JSON 结果，不需要你做任何额外的等待操作。

3. **Windows 路径**：在 Windows 上执行脚本时，文件路径使用正斜杠或双反斜杠。

4. **错误处理**：如果脚本报错，检查：
   - 文件路径是否正确
   - 依赖是否已安装
   - Excel 文件是否被其他程序占用

5. **交叉分析列名**：`--col_questions` 中的列名必须与数据中完全匹配。
   从 `load_and_classify.py` 的输出中获取准确的列名。

6. **中文编码**：所有脚本使用 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 处理与自动刷新（下载遇到认证问题时） |

### 核心调用时机

- **阶段 4 文本分析**：参考 `01`、`02` 进行维度归纳
- **阶段 5 报告撰写**：参考 `03`、`06` 进行多数据源融合表达；参考 `08` 对建议进行量化支撑
- **解读定量数据时**：参考 `05` 规避常见统计错误
- **发现明显用户分群时**：参考 `07` 描述用户群体特征

---

## 预留模块（后续扩展）

以下模块当前未实现，后续版本补充：

- **舆情分析**：结合外部舆情数据进行综合分析
- **竞品参考**：对比竞品的调研数据或公开报告