# spss-academic-workflow

Adopt this skill: https://proskills.md/skills/other/exist-d-spss-academic-workflow-skills-spss-academic-workflow

Page: https://proskills.md/skills/other/exist-d-spss-academic-workflow-skills-spss-academic-workflow
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/spss-academic-workflow/SKILL.md
size: 9720
sha: 619918454109aaa476e273a16272cd150d5a6854
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/SKILL.md

````text
---
name: spss-academic-workflow
description: "Use when the user wants a complete SPSS or SPSS-MCP empirical research workflow: organize source data, prepare datasets, design variables and models, run SPSS analyses, export Chinese result paragraphs and tables, write a Chinese LaTeX paper, and compile the final PDF."
metadata:
  short-description: "Run SPSS empirical analysis and draft a Chinese LaTeX paper"
---

# SPSS Academic Workflow

本 skill 用于把原始数据推进为完整的中文实证研究交付物：数据整理、研究设计、SPSS 统计分析、结果表格、中文论文正文、LaTeX 源码和 PDF。它的核心主题始终是“基于 SPSS 的实证分析”，写作与排版服务于分析结论，而不是反过来主导流程。

## 适用任务

当用户提出以下需求时使用本 skill：

- 使用 `SPSS`、`SPSS-MCP` 或 `SPSS syntax` 完成实证分析
- 从 Excel、CSV、SAV 等原始数据生成描述性统计、相关、回归、方差分析或其他统计结果
- 将统计结果整理成中文“结果”段落、表格和 LaTeX 论文
- 在指定项目目录内完成从原始数据到 `.tex`、PDF 的完整交付

## 执行模式

本 skill 按两种模式工作：

- 显式分析模式：用户明确说明分析类型，例如回归、t 检验、方差分析、相关、聚类、因子、信度、逻辑回归、生存分析等。此时优先执行用户指定分析，同时补齐必要的数据读取、描述统计、结果解释与成果整理。
- 自动路由模式：用户只说“使用 spss skills 分析这份数据”或“看看这份数据适合做什么分析”。此时先读取数据结构，再根据变量类型、研究问题和样本条件自动选择保守且合理的分析路径。

除非用户明确要求只做单一检验，否则不要只输出一张软件结果表；至少要补齐数据概览、变量说明和中文结果解释。

## 核心流程

1. 侦察项目：确认项目根目录、原始数据文件、已有产物和潜在旧分析。
2. 建立目录：创建标准目录树，必要时复制原始数据到 `01_source_data/raw/`。
3. 读取数据：检查变量名、样本量、缺失情况、变量类型和取值范围。
4. 研究设计：在 `03_research_design/` 中明确研究问题、假设、变量设计、模型设计和样本规则。
5. 数据准备：在 `02_data_prep/` 完成重命名、编码转换、缺失处理、异常值处理、变量标签和样本筛选。
6. 运行 SPSS：在 `04_spss_syntax/` 中用 SPSS-MCP 或 SPSS syntax 执行描述统计、相关、回归和补充检验。
7. 解析结果：把 SPSS 输出整理成 `05_analysis_output/` 下的表格、图形、说明笔记、日志和论文输入接口。
8. 完善设计：根据数据条件补充诊断检验、稳健性、异质性、机制或替代模型。
9. 写作论文：在 `06_paper_draft/` 中生成中文实证论文，包括摘要、引言、文献与假设、数据变量、模型、结果、讨论、结论和局限。
10. 排版与编译：按普通中文论文版式组织主稿，检查表格接口、引用流和编译链，输出 PDF。
11. 汇报交付：说明文件路径、调用工具、主要结论、研究限制和验证状态。

## 项目结构

用户给定项目根目录后，所有新产物默认写入该目录。标准结构如下：

```text
project-name/
├── 01_source_data/
│   ├── raw/
│   ├── external/
│   └── documentation/
├── 02_data_prep/
│   ├── mapping/
│   ├── interim/
│   ├── final/
│   └── audit/
├── 03_research_design/
│   ├── question.md
│   ├── hypotheses.md
│   ├── variable_design.md
│   ├── model_design.md
│   └── sample_rules.md
├── 04_spss_syntax/
│   ├── data_cleaning/
│   ├── variable_construction/
│   ├── descriptive/
│   ├── main_models/
│   ├── robustness/
│   └── appendix_models/
├── 05_analysis_output/
│   ├── tables/
│   ├── figures/
│   ├── notes/
│   ├── logs/
│   └── export_for_paper/
├── 06_paper_draft/
│   ├── sections/
│   ├── references/
│   ├── tables_inputs/
│   ├── figures_inputs/
│   └── paper.tex
├── 07_submission_package/
│   ├── draft/
│   ├── final/
│   └── archive/
└── 08_project_admin/
    ├── README.md
    ├── changelog.md
    └── reproducibility_checklist.md
```

如需快速建立目录，可运行：

```powershell
$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
$skillDir = Join-Path $codexHome "skills\spss-academic-workflow"
python (Join-Path $skillDir "scripts\scaffold_spss_academic.py") --project-root "<项目根目录>"
```

在 macOS、Linux 或服务器环境可使用：

```bash
SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/spss-academic-workflow"
python "$SKILL_DIR/scripts/scaffold_spss_academic.py" --project-root "<项目根目录>"
```

原始数据不得删除、覆盖或原地修改。清洗后的数据写入 `02_data_prep/interim/` 或 `02_data_prep/final/`。若中文路径会导致 SPSS 不稳定，可使用英文临时子目录或盘符映射，并优先使用英文变量名进入 SPSS。

## 分析标准

默认分析标准如下：

- 探索性任务：默认做到最低交付，重点是数据概览、描述统计、频数、相关和初步模型建议。
- 验证性任务：默认做到推荐交付，重点是主模型、递进模型、诊断和至少一种合理补充检验。
- 只有在研究问题、变量定义和样本条件充分时，才推进完整交付中的稳健性、异质性、机制或调节分析。

最低交付：

- 描述性统计
- 缺失值和样本筛选说明
- 主模型或核心统计检验
- 中文结果段落
- 一份结果表和复现日志

推荐交付：

- 描述统计表、相关系数表和主回归表
- 多模型递进设定
- 合理的变量转换与说明
- 至少一种稳健性或替代检验

完整交付：

- 数据质量审计、主模型、诊断、稳健性、异质性或机制分析
- 所有结果进入统一结果接口，供论文通过表格片段和结果摘要调用

## SPSS 调用原则

优先使用 SPSS-MCP。若当前 Codex 会话没有直接暴露 `mcp__spss__*` 工具，可在 Python 脚本中调用本机 `spss_mcp.server` 中的同名函数回退执行。

分析阶段至少沉淀以下成果物：

```text
02_data_prep/audit/codebook_<study_slug>.md
02_data_prep/audit/desc_<study_slug>.csv
05_analysis_output/notes/note_01_data_profile.md
05_analysis_output/notes/note_03_baseline_model.md
05_analysis_output/logs/run_03_baseline_model.md
05_analysis_output/tables/table_01_descriptive_statistics.md
05_analysis_output/tables/table_01_descriptive_statistics.tex
05_analysis_output/tables/table_02_correlation_matrix.md
05_analysis_output/tables/table_02_correlation_matrix.tex
05_analysis_output/tables/table_03_baseline_model.md
05_analysis_output/tables/table_03_baseline_model.tex
05_analysis_output/export_for_paper/paper_table_03_baseline_model.tex
06_paper_draft/paper.tex
06_paper_draft/output/paper.pdf
```

命名采用“阶段编号 + 内容说明”的小写 `snake_case` 规则，避免使用 `tab1<ScriptName>`、驼峰命名或依赖脚本名的结果文件名。表格编号应按论文展示顺序稳定排列，而不是按脚本运行顺序临时生成。

## 写作与排版原则

- 写作必须服务于论证，不得把论文写成软件输出说明书。
- 摘要、引言、结果、讨论和结论都必须与实际分析结果一致。
- 所有数字都以 `05_analysis_output/` 中的结果接口或结果表为准，不手工凭记忆改数。
- 普通中文论文默认使用 `ctexart`，除非已有项目另有 `class`。
- 结果表优先通过 `05_analysis_output/export_for_paper/` 接入主稿，不在主稿中手工重做表格。
- `06_paper_draft/tables_inputs/` 和 `06_paper_draft/figures_inputs/` 用于需要本地适配的稿件级输入，不是统计结果的唯一真源。

如需更稳定的主稿或段落骨架，优先复用 `assets/` 中的模板文件。

## 交付与验证

交付前至少检查：

- 清洗脚本可重复运行。
- 最终分析数据存在，样本量与 codebook、结果表一致。
- 主要结果表中的数字来自 SPSS 输出或解析结果。
- 主稿中的 `\input{}` 路径有效。
- PDF 编译成功，或已明确记录失败原因。
- 最终答复说明调用了哪些 SPSS-MCP 工具或回退函数。

## 参考地图

按任务需要读取，不要一次性加载所有内容：

- `references/workflow.md`：项目结构、阶段产物、清理规则和验证门禁
- `references/analysis-routing.md`：显式分析触发、自动分析路由、止损规则和汇报方式
- `references/empirical-design.md`：变量构造、模型选择、诊断、稳健性、异质性和机制分析
- `references/spss-mcp.md`：SPSS-MCP 环境发现、兼容处理、回退调用和结果记录
- `references/tool-matrix.md`：已注册工具、类别、用途和调用可见性
- `references/paper-writing.md`：中文实证论文结构、写作逻辑、结果叙述和修订检查
- `references/latex-layout.md`：普通中文论文的 LaTeX 版式规划、表格接口、编译链和排版 QA

## 最终答复格式

最终答复使用简体中文，简洁说明：

- 已完成哪些阶段
- 关键输出文件在哪里
- 调用了哪些 SPSS-MCP 工具或函数
- 主要实证结论是什么
- 是否成功生成 PDF；若失败，说明原因和可恢复路径
````

## File: skills/spss-academic-workflow/scripts/scaffold_spss_academic.py
size: 5835
sha: 926b9406aebd8dc85d64b5666554bf8ea91be6c1
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/scripts/scaffold_spss_academic.py

```text
"""Create a reproducible SPSS academic project scaffold.

This helper is intentionally conservative: it creates missing directories and
starter files, but never deletes or overwrites user data.
"""

from __future__ import annotations

import argparse
import shutil
from datetime import datetime
from pathlib import Path

DIRS = [
    "01_source_data/raw",
    "01_source_data/external",
    "01_source_data/documentation",
    "02_data_prep/mapping",
    "02_data_prep/interim",
    "02_data_prep/final",
    "02_data_prep/audit",
    "03_research_design",
    "04_spss_syntax/data_cleaning",
    "04_spss_syntax/variable_construction",
    "04_spss_syntax/descriptive",
    "04_spss_syntax/main_models",
    "04_spss_syntax/robustness",
    "04_spss_syntax/appendix_models",
    "05_analysis_output/tables",
    "05_analysis_output/figures",
    "05_analysis_output/notes",
    "05_analysis_output/logs",
    "05_analysis_output/export_for_paper",
    "06_paper_draft/sections",
    "06_paper_draft/references",
    "06_paper_draft/tables_inputs",
    "06_paper_draft/figures_inputs",
    "06_paper_draft/output",
    "07_submission_package/draft",
    "07_submission_package/final",
    "07_submission_package/archive",
    "08_project_admin",
]

RESEARCH_DESIGN_FILES = {
    "03_research_design/question.md": "# 研究问题\n\n- 主题：\n- 核心问题：\n- 识别目标：\n",
    "03_research_design/hypotheses.md": "# 研究假设\n\n- H1:\n- H2:\n- H3:\n",
    "03_research_design/variable_design.md": "# 变量设计\n\n## 因变量\n\n## 自变量\n\n## 控制变量\n\n## 变量构造规则\n",
    "03_research_design/model_design.md": "# 模型设计\n\n## 主模型\n\n## 稳健性方案\n\n## 异质性或机制方案\n",
    "03_research_design/sample_rules.md": "# 样本规则\n\n- 样本范围：\n- 删除规则：\n- 缺失处理：\n",
}

ADMIN_FILES = {
    "08_project_admin/README.md": None,
    "08_project_admin/changelog.md": "# Changelog\n\n",
    "08_project_admin/reproducibility_checklist.md": (
        "# Reproducibility Checklist\n\n"
        "- [ ] 原始数据已保存到 `01_source_data/raw/`\n"
        "- [ ] 变量映射和样本规则已写入设计文件\n"
        "- [ ] 最终分析数据已保存到 `02_data_prep/final/`\n"
        "- [ ] 结果表已按 `table_XX_<content>` 输出到 `05_analysis_output/tables/`\n"
        "- [ ] 论文接口文件已按 `paper_table_XX_<content>` 输出到 `05_analysis_output/export_for_paper/`\n"
        "- [ ] 结果说明已按 `note_XX_<content>` 输出到 `05_analysis_output/notes/`\n"
        "- [ ] 复现日志已按 `run_XX_<content>` 输出到 `05_analysis_output/logs/`\n"
        "- [ ] `06_paper_draft/paper.tex` 可编译\n"
    ),
}

def copy_raw_file(raw_file: Path, raw_dir: Path) -> Path:
    target = raw_dir / raw_file.name
    if target.exists():
        return target
    shutil.copy2(raw_file, target)
    return target

def write_text_if_missing(path: Path, content: str) -> None:
    if not path.exists():
        path.write_text(content, encoding="utf-8")

def render_readme(project_root: Path, copied_raw: Path | None) -> str:
    raw_line = f"`{copied_raw}`" if copied_raw else "未提供"
    created_at = datetime.now().isoformat(timespec="seconds")
    return (
        "# SPSS Academic Workflow Project\n\n"
        f"- Created at: `{created_at}`\n"
        f"- Project root: `{project_root}`\n"
        f"- Raw data copied to: {raw_line}\n\n"
        "## Structure\n\n"
        "- `01_source_data/`: 原始数据、外部数据与说明文档\n"
        "- `02_data_prep/`: 数据准备、中间数据、最终分析数据与审计文件\n"
        "- `03_research_design/`: 研究问题、假设、变量和模型设计\n"
        "- `04_spss_syntax/`: SPSS 清洗、描述统计、主模型与稳健性脚本\n"
        "- `05_analysis_output/`: 表格、图形、说明笔记、日志和论文接口\n"
        "- `06_paper_draft/`: 论文主稿、章节和编译输出\n"
        "- `07_submission_package/`: 对外提交包\n"
        "- `08_project_admin/`: 项目说明、变更记录和复现检查清单\n"
    )

def load_paper_template() -> str:
    assets_dir = Path(__file__).resolve().parents[1] / "assets"
    template = assets_dir / "paper_template.tex"
    return template.read_text(encoding="utf-8")

def main() -> None:
    parser = argparse.ArgumentParser(description="Create SPSS academic workflow directories.")
    parser.add_argument("--project-root", required=True, help="Project root directory.")
    parser.add_argument("--raw-file", help="Optional raw data file to copy into 01_source_data/raw.")
    args = parser.parse_args()

    project_root = Path(args.project_root).expanduser().resolve()
    project_root.mkdir(parents=True, exist_ok=True)

    for rel in DIRS:
        (project_root / rel).mkdir(parents=True, exist_ok=True)

    copied_raw = None
    if args.raw_file:
        raw_file = Path(args.raw_file).expanduser().resolve()
        if not raw_file.exists():
            raise FileNotFoundError(f"Raw file does not exist: {raw_file}")
        copied_raw = copy_raw_file(raw_file, project_root / "01_source_data" / "raw")

    for rel_path, content in RESEARCH_DESIGN_FILES.items():
        write_text_if_missing(project_root / rel_path, content)

    admin_readme = render_readme(project_root, copied_raw)
    write_text_if_missing(project_root / "08_project_admin" / "README.md", admin_readme)

    for rel_path, content in ADMIN_FILES.items():
        if content is not None:
            write_text_if_missing(project_root / rel_path, content)

    paper_path = project_root / "06_paper_draft" / "paper.tex"
    write_text_if_missing(paper_path, load_paper_template())

    print(f"Scaffold ready: {project_root}")

if __name__ == "__main__":
    main()
```

## File: skills/spss-academic-workflow/references/analysis-routing.md
size: 4331
sha: e90777543b2a9b7729b4bee361adb316ff370df7
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/references/analysis-routing.md

```text
# 分析触发与自动路由

## 一、显式分析触发

如果用户明确说出要做哪种分析，优先尊重用户指定路线，再自动补齐前置和收尾步骤。

### 1. 数据读取前置

无论用户点名哪种分析，默认先执行：

- `spss_check_status`
- `spss_list_files` 或定位目标文件
- `spss_list_variables`
- `spss_read_metadata`
- `spss_file_summary`
- `spss_read_data`

如输入为 CSV，先执行：

- `spss_import_csv`

### 2. 显式分析到工具的映射

| 用户表述 | 默认主工具 | 常规补充 |
|---|---|---|
| 描述性统计 | `spss_descriptives` / `spss_frequencies` | 缺失说明、变量标签整理 |
| 频数/列联表 | `spss_frequencies` / `spss_crosstabs` | 卡方解释、组别占比 |
| 相关分析 | `spss_correlations` | `spss_descriptives`、共线性说明 |
| t 检验 | `spss_t_test` | `spss_normality_outliers`、必要时 `spss_nonparametric_tests` |
| 方差分析 | `spss_anova` | 事后检验、必要时 `spss_glm_univariate` |
| 线性回归 | `spss_regression` | 描述统计、相关矩阵、稳健性检查 |
| 二元逻辑回归 | `spss_logistic_regression` | 描述统计、分类结果解释 |
| 序数回归 | `spss_ordinal_regression` | 平行线检验说明 |
| 多分类模型 | `spss_genlin` | 指定 `MULTINOMIAL` 分布 |
| 重复测量 | `spss_repeated_measures_anova` 或 `spss_mixed` | 数据结构检查 |
| 混合模型 | `spss_mixed` / `spss_genlinmixed` | subject/repeated 结构说明 |
| 生存分析 | `spss_kaplan_meier` / `spss_cox_regression` | 事件定义、删失说明 |
| 因子分析 | `spss_factor` | 信度、量表得分 |
| 信度分析 | `spss_reliability_alpha` | `spss_compute_scale_score` |
| 聚类分析 | `spss_cluster_hierarchical` / `spss_twostep_cluster` | 变量标准化说明 |
| 判别分析 | `spss_discriminant` | 分类准确率解释 |
| MANOVA/GLM | `spss_manova` / `spss_glm_univariate` | 组间效应解释 |

### 3. 显式分析模式下的默认补齐

除非用户明确说“只做这个检验”，否则默认补齐：

- 数据摘要。
- 核心变量说明。
- 至少一张主结果表。
- 中文结果段落。
- 适合时的诊断或替代检验。

## 二、自动分析路由

如果用户只说“用 spss skills 分析某数据”，而没有明确说检验类型，则按以下保守路线：

### 第一步：识别任务类型

- 如果用户给出明确因变量、自变量、控制变量，视为验证性分析。
- 如果用户只给数据文件，没有研究设定，视为探索性分析。
- 如果用户给出论文题目但变量不完整，先做变量识别与可行性判断，再进入验证性分析。

### 第二步：自动选择分析主线

#### 探索性分析

默认执行：

- 文件概览和变量识别。
- 描述性统计。
- 分类变量频数。
- 核心连续变量相关矩阵。
- 初步发现总结。
- 对可行的后续模型提出建议。

只有在数据结构和变量关系足够清楚时，才自动补回归或聚类等强假设分析。

#### 验证性分析

按因变量类型自动选模型：

- 连续：`spss_regression`
- 二分类：`spss_logistic_regression`
- 有序分类：`spss_ordinal_regression`
- 多分类：`spss_genlin` with `MULTINOMIAL`
- 多因变量：`spss_manova`
- 时间到事件：`spss_kaplan_meier` / `spss_cox_regression`
- 重复测量或层级结构：`spss_mixed` / `spss_genlinmixed`

### 第三步：自动补充

默认尝试以下补充模块中的至少一个：

- 诊断检验。
- 稳健性检验。
- 异质性分析。
- 机制或调节分析。

前提是：

- 样本量允许。
- 变量定义清楚。
- 不会明显超出数据的识别能力。

## 三、止损规则

以下情况不要强行自动做复杂模型：

- 因变量不明确。
- 变量编码不清晰。
- 样本量过小。
- 缺失过多。
- 用户问题本身只需要描述性结果。
- 当前数据不支持机制、异质性或因果解释。

遇到这些情况，应退回更保守的分析，并在日志中写明原因。

## 四、结果汇报规则

无论显式还是自动路由，最终都要说明：

- 实际调用了哪些工具或回退函数。
- 为什么选择当前分析路线。
- 哪些分析没做，以及为什么。
- 结果支持什么结论，不支持什么结论。
```

## File: skills/spss-academic-workflow/references/empirical-design.md
size: 4975
sha: 0aecf99c7f95f8583111f09a5792cd8392a3ed8b
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/references/empirical-design.md

```text
# 实证分析设计规范

## 研究设计起点

开始分析前先形成一页研究设计备忘：

- 研究问题：解释“谁影响谁”，以及为什么这个问题值得检验。
- 分析单位：个体、家庭、企业、地区、年份或观测记录。
- 样本范围：数据来源、年份、筛选规则和最终样本量。
- 因变量：变量含义、构造方式、取值范围和度量方向。
- 核心解释变量：理论含义、构造方式和预期方向。
- 控制变量：纳入理由、分类变量参照组和潜在遗漏变量。
- 识别限制：横截面数据通常只能谨慎表述相关关系，不能直接宣称因果。

## 数据质量审计

清洗阶段至少检查：

- 重复观测：按个体 ID、家庭 ID 或关键字段检查。
- 缺失值：报告核心变量缺失数量和缺失比例。
- 异常值：对金额、收入、年龄、比例、分数等变量检查极端值。
- 编码一致性：确认分类变量编码、反向题、缺失码和“不适用”码。
- 量表方向：确认数值越大是否代表概念更强。
- 样本筛选：任何筛选都要记录原始样本量、删除数量和理由。

## 变量构造

常见处理规则：

- 金额变量偏态明显时，优先构造 `ln(x + 1)`，并保留原变量用于描述。
- 多题项量表可以用均值或总分；如果题项方向不一致，先反向编码。
- 多个二分类投入项可以构造总和指标，也可分项进入模型。
- 分类变量进入回归前要构造虚拟变量并明确参照组。
- 如果变量取值为“优、良、中、差”等等级，可按研究设定转换为有序数值，并说明转换逻辑。
- 构造交互项前，连续变量可考虑中心化，便于解释主效应。

## 模型选择

根据因变量类型选择模型：

- 连续变量：OLS 回归。
- 二分类变量：binary logistic 回归。
- 多分类无序变量：multinomial logistic 回归。
- 有序分类变量：ordinal logistic 回归。
- 计数变量：Poisson 或负二项模型；若只用 OLS，要说明近似处理。
- 组间均值比较：t 检验、ANOVA 或带控制变量的回归。
- 相关关系探索：Pearson、Spearman 或偏相关。

SPSS 输出结果后，应把模型选择写成研究语言，而不是只写软件命令。

## 主模型结构

推荐递进模型：

- 模型 1：只加入控制变量。
- 模型 2：加入核心解释变量。
- 模型 3：加入其他维度解释变量或机制变量。
- 模型 4：完整模型。
- 模型 5：稳健性或替代设定。

每个模型应说明：

- 因变量和解释变量。
- 控制变量是否加入。
- 分类变量参照组。
- 样本量是否变化。
- 系数方向、显著性和效应大小。

## 诊断检验

根据模型和数据条件选择：

- 共线性：检查 VIF 或相关系数矩阵。
- 异方差：若 SPSS-MCP 能实现稳健标准误，优先报告；否则在局限中说明。
- 异常值：检查 Cook's distance、标准化残差或极端样本影响。
- 模型拟合：OLS 报告 `R^2` 和调整 `R^2`；logistic 报告伪 `R^2`、分类准确率或似然比检验。
- 样本选择：说明删除缺失后的样本是否可能带来选择偏差。

## 稳健性检验

至少选择一种与研究问题匹配的稳健性分析：

- 替换因变量度量方式。
- 替换核心解释变量度量方式。
- 使用分项变量替代综合指数，或用综合指数替代分项变量。
- 对金额变量使用原值、对数值或缩尾值进行比较。
- 改变样本范围，例如剔除极端值、保留特定年龄段或特定地区。
- 增加或减少控制变量。
- 更换模型形式，例如 OLS 与 ordered logistic 对照。

稳健性结果不必机械追求完全一致，但要解释是否支持主结论。

## 异质性、机制与调节

只有在理论和数据支持时才加入：

- 异质性：按性别、城乡、收入组、年龄段、地区、学校类型等分组。
- 机制分析：检验核心解释变量是否影响中介变量，以及加入机制变量后主效应如何变化。
- 调节分析：构造交互项，解释交互方向，并给出分组结果或边际解释。

注意：横截面数据中的机制和调节通常是“机制线索”或“异质性证据”，不宜写成严格因果链。

## 结果解释规范

中文解释遵循：

- 先说模型整体，再说核心变量。
- 同时报告方向、显著性和经济/现实含义。
- 不显著结果也要说明，不要悄悄省略。
- 对反直觉结果提出谨慎解释，例如选择效应、反向因果、测量误差或遗漏变量。
- 如果变量经过对数处理，解释为投入增加与因变量变化之间的关联，不要误读单位。

## 输出清单

推荐至少生成：

- 描述性统计表。
- 相关系数表。
- 主回归表。
- 稳健性检验表。
- 异质性、机制或调节分析表。
- 数据清洗 codebook。
- 复现日志。
```

## File: skills/spss-academic-workflow/references/latex-layout.md
size: 3589
sha: e212bcc78ccdbc7bed3012fe40470e3f290cab1f
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/references/latex-layout.md

````text
# 中文论文 LaTeX 排版规划

## 适用时机

当用户已经完成或接近完成实证分析，希望把结果整理为一篇规范、清晰、可编译的中文 LaTeX 论文时，读取本文件。

## 总体目标

中文论文排版的目标不是“花哨”，而是：

- 结构清晰
- 结果表接口稳定
- 图表和正文风格统一
- 编译链简单可靠
- 后续扩写、换模板或改投时成本较低

## 主稿规则

默认主稿：

```text
06_paper_draft/paper.tex
```

默认版式选择：

- 首选 `ctexart`
- 只有在篇幅很长且天然需要 chapter 级结构时，才考虑 `ctexrep`
- 若用户已有既定模板，优先沿用

## 与分析输出的衔接

分析结果的真源在 `05_analysis_output/`：

- `tables/`：机器生成的原始表格
- `figures/`：机器生成的图形
- `notes/`：中文结果说明
- `export_for_paper/`：供主稿消费的稳定接口

默认策略：

- 分析脚本生成 `05_analysis_output/export_for_paper/*.tex`
- 主稿通过 `\input{}` 直接消费这些接口
- 不在主稿中手工重做表格

推荐写法：

```latex
\input{../05_analysis_output/export_for_paper/paper_table_03_baseline_model.tex}
```

`06_paper_draft/tables_inputs/` 和 `06_paper_draft/figures_inputs/` 仅在期刊模板、学校模板或编译方式要求本地复制时使用；默认不是统计结果的唯一真源。

论文侧接口命名统一使用 `paper_table_XX_<content>.tex` 或 `paper_figure_XX_<content>.tex`。其中 `XX` 对应正文展示顺序，`<content>` 使用小写 `snake_case`，例如 `paper_table_01_descriptive_statistics.tex`。

## 图表规范

### 表格

- 优先使用三线表风格
- 每张表有标题、编号、主体和表注
- 表注说明显著性符号、标准误形式、参考组或变量定义
- 表格过宽时，优先简化列名、拆表或调整列宽，必要时再用 `resizebox`

### 图形

- 图形文件放在 `05_analysis_output/figures/`
- 图题、编号和表格风格统一
- 图注只写必要说明，不重复正文
- 纯探索性图形可放附录

## 参考文献与引用流

优先保证引用流顺畅：

- 明确 `.bib` 是否存在
- 明确使用 `bibtex` 还是 `biber`
- 确认引用命令风格统一
- 文献样式和当前 class 不冲突

如用户未提供正式文献库：

- 不编造文献条目
- 可以保留引用占位或待补文献说明

## 编译链

普通中文论文默认优先：

```powershell
xelatex -interaction=nonstopmode -halt-on-error paper.tex
```

如项目更适合 `latexmk`：

```powershell
latexmk -xelatex -interaction=nonstopmode paper.tex
```

建议把 PDF 输出到：

```text
06_paper_draft/output/paper.pdf
```

## 排版 QA

### 编译前检查

- 主稿路径是否明确
- `\input{}` 的表格路径是否存在
- class 和核心宏包是否冲突
- 图表文件是否存在
- 参考文献文件是否存在

### 编译后检查

- PDF 是否成功生成
- 目录、页码、交叉引用是否正常
- 表格是否溢出页面
- 中文是否正常显示
- 变量名中的下划线、百分号是否正确转义

### 交付前检查

- 标题、摘要、关键词是否齐全
- 主回归表和正文是否对应
- 图表编号是否连续
- 表注和显著性说明是否统一
- 文献是否挂接成功

## 与 SPSS 工作流的边界

LaTeX 排版必须服从 SPSS 实证分析主线：

- 结果数字以 `05_analysis_output/` 为准
- 结果解释以 `05_analysis_output/notes/` 为准
- 主稿负责组织，不负责重新计算结果
- PDF 编译只是交付阶段，不改变统计结论
````

## File: skills/spss-academic-workflow/references/paper-writing.md
size: 4229
sha: 6692a3e499fcf3979bd502869f175e67d50e87a3
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/references/paper-writing.md

```text
# 中文实证论文写作

## 适用时机

当分析已经完成或接近完成，需要把研究问题、变量、模型、结果和解释组织成一篇中文实证论文时，读取本文件。

## 核心原则

论文写作应服务于研究论证，而不是复述软件输出。每一部分都应回答一个明确问题：

- 研究什么
- 为什么值得研究
- 如何用当前数据检验
- 结果说明了什么
- 这些结论的边界在哪里

写作必须和分析同步，不得在没有结果支撑时预写结论，也不得把表格数字直接堆成正文。

## 研究问题的收缩

在正式写作前，把问题从宽泛主题收缩成可检验表达：

- 宽泛主题：研究的是哪个大问题
- 具体问题：在该主题下关心的核心关系是什么
- 可检验问题：用现有数据、现有变量和现有模型能检验什么
- 边界说明：当前数据支持相关、比较、探索，还是较强的因果识别

这些内容优先写入 `03_research_design/question.md`、`hypotheses.md` 和 `model_design.md`。

## 论文结构

普通中文实证论文建议包含：

1. 标题
2. 摘要
3. 关键词
4. 引言
5. 文献综述与研究假设
6. 数据来源、变量说明与模型设定
7. 实证结果
8. 稳健性、异质性或机制分析
9. 讨论
10. 结论与启示
11. 参考文献
12. 附录

## 各部分写法

### 标题

标题应包含研究对象、核心关系和数据来源。若数据不支持强因果识别，优先使用“影响研究”“关联研究”“实证分析”等表述。

### 摘要

摘要建议 200-400 字，至少包括：

- 研究问题
- 数据与方法
- 主要发现
- 贡献或启示

### 引言

引言建议使用漏斗结构：

1. 现实背景
2. 具体问题
3. 研究缺口
4. 研究问题
5. 研究设计
6. 研究贡献
7. 文章结构

### 文献综述与研究假设

文献综述应按主题、机制或争议组织，而不是按作者逐篇罗列。每段最好完成三件事：

- 归纳已有结论
- 指出差异和不足
- 引出本文假设或研究问题

### 数据、变量与方法

方法部分应满足复现要求：

- 数据来源说清楚
- 样本筛选和缺失处理说清楚
- 因变量、自变量、控制变量构造说清楚
- 模型设定和参考组说清楚
- 分析工具和统计方法说清楚

变量构造依据优先写入 `03_research_design/variable_design.md`，清洗和映射依据优先写入 `02_data_prep/mapping/` 与 `02_data_prep/audit/`。

### 结果部分

结果部分应先报告，再解释。每段至少包含：

- 表格编号
- 模型设定
- 核心系数方向
- 显著性水平
- 效应大小或现实含义
- 对研究预期的支持情况

正文数字以 `05_analysis_output/tables/` 和 `05_analysis_output/notes/` 为准，不手工凭记忆改数。

### 讨论部分

讨论部分的任务不是重复结果，而是解释结果：

- 为什么会出现这种结果
- 结果与理论预期是否一致
- 与已有研究是支持、补充还是冲突
- 数据、测量和识别限制如何影响解释

### 结论部分

结论建议按四步收束：

1. 回到研究问题
2. 总结核心发现
3. 给出政策或实践启示
4. 说明局限与未来研究

## 写作语气

默认采用学术克制表达：

- 用“结果表明”“结果提示”“可能与……有关”“在控制其他因素后”
- 少用“证明”“必然导致”“完全说明”
- 事实、方法和结果尽量简洁直接，减少空话和套话

## 结果与写作同步产物

分析阶段建议同步沉淀：

- 一句话研究问题
- 一句话核心发现
- 一句话研究贡献
- 每张主表对应的中文结果段落
- 稳健性、异质性或机制分析的解释草稿
- 研究局限清单

这些材料优先写入：

- `05_analysis_output/notes/`
- `06_paper_draft/sections/`

## 修订检查

提交前至少检查：

- 摘要、引言、结果、结论中的核心发现是否一致
- 研究问题与实际模型是否一致
- 假设表述是否超出数据支持范围
- 结果段落是否逐表对应
- 不显著结果是否被诚实呈现
- 讨论是否把解释和事实混在一起
- 结论是否超出了方法和数据的能力边界
```

## File: skills/spss-academic-workflow/references/spss-mcp.md
size: 2079
sha: e7ae2b619fb4c083b7845e8dac4b5161de987914
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/references/spss-mcp.md

````text
# SPSS-MCP 使用说明

## 环境发现与配置

不要假设某台机器的固定盘符、用户目录、conda 环境名或 SPSS 安装路径。执行时按以下优先级发现环境：

1. 优先读取用户显式提供的 `SPSS_INSTALL_PATH`、Python 可执行文件、conda/venv 名称和项目根目录。
2. 如用户未提供，检查当前 Codex 进程可用的 Python：`python`、`python3`、`py -3` 或当前虚拟环境解释器。
3. 检查 `spss-mcp`、`pandas`、`pyreadstat` 是否已安装；缺失时在当前环境或用户指定环境中安装。
4. 检查 SPSS batch 程序是否可用。Windows 常见程序名为 `stats.exe`。
5. 将实际发现的 Python、SPSS、SPSS-MCP 路径写入 `05_analysis_output/logs/run_XX_<content>.md`。

常用诊断命令：

```powershell
python -m pip show spss-mcp
python -m spss_mcp.cli status
```

## 推荐调用方式

如当前 Codex 会话直接暴露 SPSS MCP 工具，优先调用这些工具。若工具未直接暴露，可在 Python 中调用已安装的 `spss_mcp.server` 函数，沿用同一套 server 逻辑。

分析阶段应记录：

- 使用了哪些 MCP 工具或回退函数
- 输入数据路径
- 输出表格路径
- SPSS syntax 类型
- 环境信息与任何重要 warning

这些内容统一写入：

```text
05_analysis_output/logs/run_XX_<content>.md
```

## Windows 与旧版 SPSS 兼容策略

SPSS 24 对新 Python 语法、中文路径和中文变量名可能不稳定。遇到问题时按以下顺序处理：

1. 将分析变量转换为英文变量名。
2. 尽量把 SPSS 输入输出放在 ASCII 子路径下。
3. 优先让 SPSS 读取 `.sav`，而不是直接读取中文路径下的 Excel。
4. 必要时为 SPSS 单独设置临时目录。

## SPSS syntax 规范

- 路径使用正斜杠或转义反斜杠。
- 回归建议使用明确的模型块，例如控制变量模型、核心变量模型、完整模型。
- 分类变量要说明虚拟变量构造和参考组。
- 对 SPSS 输出进行结构化解析后再生成论文表格，不从截图或终端直接抄数。
````

## File: skills/spss-academic-workflow/references/tool-matrix.md
size: 5423
sha: 57e156a6e11df73c2b407a1f6361804a3d285e81
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/references/tool-matrix.md

```text
# SPSS-MCP 工具矩阵

以下名称基于当前已安装 `spss_mcp` 包中注册的工具名。不同 Codex 会话中，这些工具不一定都以原生 `mcp__spss__*` 形式直接显示；如果未直接显示，可用 Python 调用 `spss_mcp.server` 中的同名函数回退执行。

## 1. 状态、发现与数据文件

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_check_status` | 状态诊断 | 检查 SPSS、pyreadstat、pandas、路径、超时配置 | 是 | 推荐最先调用 |
| `spss_list_files` | 文件发现 | 列出目录中的 `.sav` 文件 | 是 | 文件级 |
| `spss_list_variables` | 元数据 | 读取变量列表和标签 | 是 | 常作分析前置 |
| `spss_read_metadata` | 元数据 | 读取变量类型、标签、取值信息 | 是 | 常作分析前置 |
| `spss_read_data` | 数据预览 | 读取前若干行观察值 | 是 | 常作分析前置 |
| `spss_file_summary` | 数据概览 | 获取样本量、变量数等摘要 | 是 | 常作分析前置 |
| `spss_import_csv` | 导入转换 | 将 CSV 导入为 `.sav` | 是 | 适合工作流起点 |

## 2. 结构化方法发现与底层 syntax

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_list_supported_methods` | 方法发现 | 查看 registry-backed 的高级结构化方法 | 是 | 高级分析前可先查 |
| `spss_get_method_schema` | 方法 schema | 获取高级方法参数 schema | 是 | 适合自动编排 |
| `spss_get_method_support` | 方法支持信息 | 查看支持级别、命令家族、断言 | 是 | 适合自动编排 |
| `spss_run_syntax` | 底层执行 | 直接运行自定义 SPSS syntax | 是 | 最灵活 |
| `spss_validate_syntax` | syntax 校验 | 执行前检查 syntax | 是 | 与 `spss_run_syntax` 配套 |

## 3. 基础统计与探索性分析

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_frequencies` | 频数 | 分类变量频数和比例 | 是 | EDA 起点 |
| `spss_descriptives` | 描述统计 | 均值、标准差、极值 | 是 | EDA 起点 |
| `spss_crosstabs` | 列联表 | 分类变量交叉表和卡方 | 是 | 分组差异 |
| `spss_t_test` | 均值比较 | 单样本、独立样本、配对 t 检验 | 是 | 分组或前后测 |
| `spss_anova` | 方差分析 | 单因素 ANOVA 与事后检验 | 是 | 组间差异 |
| `spss_correlations` | 相关分析 | Pearson 或 Spearman | 是 | 回归前常用 |
| `spss_nonparametric_tests` | 非参数检验 | Mann-Whitney、Wilcoxon、Kruskal-Wallis | 是 | 分布不满足假设时 |
| `spss_normality_outliers` | 正态性/异常值 | 分布、异常值检查 | 是 | 假设检验辅助 |

## 4. 回归、量表和一般学术分析

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_regression` | 线性回归 | OLS、多模型回归 | 是 | 实证分析高频 |
| `spss_factor` | 因子分析 | 探索性因子提取 | 是 | 量表构建 |
| `spss_reliability_alpha` | 信度分析 | Cronbach's alpha | 是 | 量表检验 |
| `spss_compute_scale_score` | 量表得分 | 计算题项均值、总分等 | 是 | 常与信度配合 |
| `spss_repeated_measures_anova` | 重复测量方差分析 | 同一对象多时点或多条件比较 | 是 | 前后测 |

## 5. 广义与高级回归

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_logistic_regression` | 二元逻辑回归 | 因变量为二分类 | 是 | registry-backed |
| `spss_ordinal_regression` | 序数回归 | 因变量为有序分类 | 是 | registry-backed |
| `spss_genlin` | 广义线性模型 | 正态、二项、泊松、Gamma、负二项、多项分布 | 是 | 可覆盖多项模型 |
| `spss_mixed` | 混合模型 | 线性混合模型 | 是 | registry-backed |
| `spss_genlinmixed` | 广义线性混合模型 | 混合广义模型 | 是 | registry-backed |
| `spss_glm_univariate` | 单变量 GLM | 因变量一个、因素与协变量组合 | 是 | registry-backed |

## 6. 生存分析

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_cox_regression` | Cox 回归 | 生存时间与风险因素分析 | 是 | registry-backed |
| `spss_kaplan_meier` | Kaplan-Meier | 生存曲线和组间比较 | 是 | registry-backed |

## 7. 多元统计与分类

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_discriminant` | 判别分析 | 基于多个变量进行分组判别 | 是 | registry-backed |
| `spss_manova` | MANOVA | 多个因变量的方差分析 | 是 | registry-backed |

## 8. 聚类

| 工具名 | 类别 | 典型用途 | 当前包内已注册 | 备注 |
|---|---|---|---|---|
| `spss_cluster_hierarchical` | 层次聚类 | 样本分群 | 是 | registry-backed |
| `spss_twostep_cluster` | 两步聚类 | 连续与分类变量混合聚类 | 是 | registry-backed |

## 使用说明

- “当前包内已注册 = 是”表示该名称已经真实存在于本机安装的 `spss_mcp.server` 中。
- 这不等于“当前对话一定显示为原生 MCP 工具”。若当前会话没有 `mcp__spss__*` 命名空间，可用 Python 回退调用。
- 对需要高可靠参数校验的高级方法，优先用 `spss_list_supported_methods`、`spss_get_method_schema`、`spss_get_method_support` 先检查。
```

## File: skills/spss-academic-workflow/references/workflow.md
size: 8514
sha: 1ff0f7f008b3aa752e46807b2c26a2af126fbde3
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/references/workflow.md

````text
# SPSS Academic Workflow：项目流程

## 目录结构

在用户指定的项目根目录下创建并维护以下结构：

```text
project-name/
├── 01_source_data/
│   ├── raw/
│   ├── external/
│   └── documentation/
├── 02_data_prep/
│   ├── mapping/
│   ├── interim/
│   ├── final/
│   └── audit/
├── 03_research_design/
│   ├── question.md
│   ├── hypotheses.md
│   ├── variable_design.md
│   ├── model_design.md
│   └── sample_rules.md
├── 04_spss_syntax/
│   ├── data_cleaning/
│   ├── variable_construction/
│   ├── descriptive/
│   ├── main_models/
│   ├── robustness/
│   └── appendix_models/
├── 05_analysis_output/
│   ├── tables/
│   ├── figures/
│   ├── notes/
│   ├── logs/
│   └── export_for_paper/
├── 06_paper_draft/
│   ├── sections/
│   ├── references/
│   ├── tables_inputs/
│   ├── figures_inputs/
│   └── paper.tex
├── 07_submission_package/
│   ├── draft/
│   ├── final/
│   └── archive/
└── 08_project_admin/
    ├── README.md
    ├── changelog.md
    └── reproducibility_checklist.md
```

## 各层分工

- `01_source_data/raw`：原始数据副本，只读，不覆盖。
- `01_source_data/external`：外部补充数据，如地区宏观数据、学校层面数据、政策表。
- `01_source_data/documentation`：问卷说明、变量字典、来源记录、数据许可说明。
- `02_data_prep/mapping`：变量映射、编码转换、中文题项到英文变量名的对应表。
- `02_data_prep/interim`：清洗中的中间数据。
- `02_data_prep/final`：正式进入 SPSS 分析的最终数据，优先使用英文变量名的 `.sav`。
- `02_data_prep/audit`：codebook、描述统计、缺失处理说明、样本筛选说明。
- `03_research_design`：研究问题、假设、变量设计、模型设计、样本口径。
- `04_spss_syntax`：SPSS 语法或与 SPSS-MCP 配套的执行脚本，按用途分层保存。
- `05_analysis_output/tables`：原始分析表格输出，包含 `.md`、`.tex` 等。
- `05_analysis_output/figures`：图形与可视化输出。
- `05_analysis_output/notes`：结果摘要、中文解释、模型说明。
- `05_analysis_output/logs`：复现日志、环境记录、调用工具记录。
- `05_analysis_output/export_for_paper`：专门供论文主稿消费的 `.tex` 片段、图注包装文件或摘要接口。
- `06_paper_draft/sections`：论文分章节草稿。
- `06_paper_draft/references`：`.bib` 或稿件内参考文献资源。
- `06_paper_draft/tables_inputs`：仅在稿件需要本地适配时放置稿件侧表格输入。
- `06_paper_draft/figures_inputs`：仅在稿件需要本地适配时放置稿件侧图形输入。
- `06_paper_draft/paper.tex`：主稿入口。
- `07_submission_package`：对外投递包。
- `08_project_admin`：项目说明、变更记录、复现检查清单。

## 数据阶段

- 所有“用户要求全部在项目目录内完成”的任务，都应先把外部原始数据复制到 `01_source_data/raw/` 再处理。
- 原始数据一律不原地改写。
- `02_data_prep/final/` 中的最终分析数据是进入 SPSS 的真源。
- 如有多个版本，命名上体现日期、样本口径或变量口径差异。

推荐命名：

```text
02_data_prep/final/cfps2020_children_analysis_final.sav
02_data_prep/mapping/variable_map_cfps2020_children.csv
02_data_prep/audit/codebook_cfps2020_children.md
02_data_prep/audit/desc_cfps2020_children.csv
02_data_prep/audit/sample_flow_cfps2020_children.md
```

## 研究设计阶段

`03_research_design/` 不是摆设，而是实证分析的前置约束层：

- `question.md`：研究主题和研究问题
- `hypotheses.md`：研究假设或经验预期
- `variable_design.md`：因变量、自变量、控制变量、构造方式
- `model_design.md`：主模型、扩展模型、稳健性方案
- `sample_rules.md`：样本筛选和删失规则

如果用户已经直接给出这些信息，仍建议在此目录落一份简短说明，避免后续写作和分析脱节。

## SPSS 执行阶段

清洗和分析逻辑统一放入 `04_spss_syntax/`：

```text
04_spss_syntax/data_cleaning/
04_spss_syntax/variable_construction/
04_spss_syntax/descriptive/
04_spss_syntax/main_models/
04_spss_syntax/robustness/
04_spss_syntax/appendix_models/
```

命名建议：

```text
04_spss_syntax/data_cleaning/clean_01_import_raw.py
04_spss_syntax/variable_construction/clean_02_construct_variables.py
04_spss_syntax/descriptive/desc_01_sample_profile.py
04_spss_syntax/main_models/model_01_baseline_ols.py
04_spss_syntax/main_models/model_02_controls_extended.py
04_spss_syntax/robustness/robust_01_alt_depvar.py
04_spss_syntax/appendix_models/appendix_01_full_controls.py
```

## 命名规范

全流程默认使用小写 `snake_case`，优先 ASCII 文件名，避免中文文件名、空格、驼峰命名和含义不清的临时编号。文件名应体现“阶段、顺序、内容”，而不是单纯复用脚本名。

统一规则：

- 数据文件：`<source>_<population>_<purpose>_<stage>.<ext>`
- 映射文件：`variable_map_<study_slug>.csv`
- 审计文件：`codebook_<study_slug>.md`、`desc_<study_slug>.csv`、`sample_flow_<study_slug>.md`
- 清洗脚本：`clean_01_import_raw.py`、`clean_02_construct_variables.py`
- 描述脚本：`desc_01_sample_profile.py`
- 主模型脚本：`model_01_baseline_ols.py`
- 稳健性脚本：`robust_01_alt_depvar.py`
- 附录脚本：`appendix_01_full_controls.py`
- 结果表：`table_01_descriptive_statistics.tex`
- 论文表接口：`paper_table_01_descriptive_statistics.tex`
- 结果说明：`note_01_data_profile.md`
- 复现日志：`run_01_data_profile.md`

编号规则：

- `01`、`02`、`03` 表示论文展示顺序或分析流程顺序。
- 同一类结果编号一旦进入论文主线，不因重新运行脚本而改变。
- 新增补充结果时追加编号，不重排已有正式结果，除非用户明确要求整体重排。
- 探索性临时文件如必须保留，应放入对应阶段目录并使用 `explore_` 前缀。

## 结果阶段

分析输出统一进入 `05_analysis_output/`：

```text
05_analysis_output/tables/table_01_descriptive_statistics.md
05_analysis_output/tables/table_01_descriptive_statistics.tex
05_analysis_output/tables/table_02_correlation_matrix.md
05_analysis_output/tables/table_02_correlation_matrix.tex
05_analysis_output/tables/table_03_baseline_model.md
05_analysis_output/tables/table_03_baseline_model.tex
05_analysis_output/notes/note_03_baseline_model.md
05_analysis_output/logs/run_03_baseline_model.md
05_analysis_output/export_for_paper/paper_table_03_baseline_model.tex
```

分工原则：

- `tables/`：分析程序直接导出的原始表
- `notes/`：为论文服务的结果解释与摘要
- `logs/`：为复现服务的环境和运行记录
- `export_for_paper/`：为 LaTeX 主稿服务的稳定接口

## 论文阶段

论文主稿统一进入 `06_paper_draft/`：

- `paper.tex`：稿件主入口
- `sections/`：分章节内容
- `references/`：文献资源
- `tables_inputs/` 和 `figures_inputs/`：仅当模板、期刊或编译策略需要本地复制时使用

默认主稿应优先直接消费 `../05_analysis_output/export_for_paper/` 中的接口，而不是重新做表。

## 清理规则

只有在用户明确要求删除旧分析时，才删除生成产物。安全删除范围通常包括：

- `02_data_prep/interim`
- `02_data_prep/final`
- `02_data_prep/audit`
- `03_research_design`
- `04_spss_syntax`
- `05_analysis_output`
- `06_paper_draft`
- `07_submission_package`
- `08_project_admin` 中由本流程自动生成的文件

不要删除：

- `01_source_data/raw` 中的原始数据副本
- `01_source_data/external` 中用户手动放入的外部数据
- 用户未确认属于本流程生成的其他文件

## 验证门禁

完成前至少检查：

- 清洗脚本可重复运行
- 最终分析数据存在且样本量与日志一致
- 研究设计、变量设计和模型设定与实际分析一致
- 结果表中的数字来自 SPSS 输出或结构化解析结果
- `05_analysis_output/export_for_paper/` 中的接口文件存在
- `06_paper_draft/paper.tex` 中的 `\input{}` 或图形引用有效
- PDF 编译成功，或已记录明确失败原因
````

## File: skills/spss-academic-workflow/assets/paper_template.tex
size: 1515
sha: 94b771b7d6a22cebfaf0022291b1dd63b38c77da
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/assets/paper_template.tex

```text
\documentclass[12pt]{ctexart}

�sepackage[a4paper,margin=2.54cm]{geometry}
�sepackage{amsmath,amssymb}
�sepackage{booktabs}
�sepackage{threeparttable}
�sepackage{array}
�sepackage{graphicx}
�sepackage{hyperref}

\title{题目待定}
\author{作者待填}
\date{\today}

\begin{document}

\maketitle

\begin{abstract}
摘要待补。建议按“研究问题、数据与方法、主要发现、贡献与启示”的顺序填写。
\end{abstract}

\noindent\textbf{关键词：} 关键词1；关键词2；关键词3

\section{引言}
引言待补。建议按“现实背景、研究缺口、研究问题、研究设计、研究贡献、文章结构”的顺序展开。

\section{文献综述与研究假设}
文献综述待补。建议按主题或机制组织，而不是按作者逐篇罗列。

\section{数据来源、变量说明与模型设定}
数据来源、样本处理、变量构造和模型设定待补。

\section{实证结果}
结果概述待补。
% 主结果表接口示例
% \input{../05_analysis_output/export_for_paper/paper_table_01_descriptive_statistics.tex}
% \input{../05_analysis_output/export_for_paper/paper_table_03_baseline_model.tex}

\section{稳健性、异质性或机制分析}
补充分析待补。

\section{讨论}
讨论待补。重点解释主要结果、反直觉结果和研究边界。

\section{结论与启示}
结论待补。重点回到研究问题，总结发现，说明启示与局限。

% \bibliographystyle{plain}
% \bibliography{references}

\end{document}
```

## File: skills/spss-academic-workflow/assets/results_section_template.md
size: 2192
sha: e97dda9630453e3a3b475323a9890c8069f3ef5b
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/assets/results_section_template.md

```text
# 结果段落模板

本模板用于把 `05_analysis_output/tables/` 中的统计表和 `05_analysis_output/notes/` 中的结果摘要，整理成可直接写入 `06_paper_draft/sections/` 的中文“结果”段落。

## 结果接口定位

- 表格文件：`05_analysis_output/tables/table_XX_<content>.md` 或 `.tex`
- 论文接口：`05_analysis_output/export_for_paper/paper_table_XX_<content>.tex`
- 结果摘要：`05_analysis_output/notes/note_XX_<content>.md`
- 复现日志：`05_analysis_output/logs/run_XX_<content>.md`

## 写作前提

先明确以下信息：

- 对应表格名称：
- 对应分析名称：
- 推荐文件基名：`table_XX_<content>`
- 回答的研究问题：
- 样本量：
- 因变量：
- 核心自变量：
- 模型列设置：

## 中文结果段落

表 X 报告了[分析主题]的主结果。列（1）展示了[基准设定]，列（2）在此基础上加入了[补充设定]，列（3）为[完整模型或替代模型]。结果显示，核心解释变量 `X` 的系数为[数值]，并在[显著性水平]上显著，说明在控制[控制变量或固定效应]后，`X` 与 `Y` 之间存在[正向/负向/不显著]关系。就经济意义或实际意义而言，[简述效应大小、方向和现实含义]。因此，该结果[支持/不支持/部分支持]研究预期。

如需补充，可继续写：

- 从统计意义看：
- 从现实意义看：
- 与描述统计或相关分析是否一致：
- 与理论预期或既有研究是否一致：

## 扩展段落接口

如果该表不是主结果表，而是补充结果表，可改写为：

- 稳健性结果：强调估计方向、显著性和结论稳定性
- 异质性结果：强调不同组之间的差异
- 机制结果：强调中介、渠道或调节方向
- 替代设定结果：强调结论是否依赖特定变量定义或样本口径

## 自检清单

- 数字是否来自 `05_analysis_output/tables/` 或 `05_analysis_output/notes/`
- 表格编号、表名和段落引用是否一致
- 是否清楚区分“证据”“解释”“结论”
- 是否避免把整张表逐列机械复述
- 是否能直接移动到 `06_paper_draft/sections/04_results.tex` 或相应章节
```

## File: skills/spss-academic-workflow/assets/table_note_template.tex
size: 466
sha: 77de1975298d28b68e021e419dce3856db949195
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/assets/table_note_template.tex

```text
\begin{tablenotes}[flushleft]
\footnotesize
\item 注：括号内为标准误。$^{*} p<0.10$，$^{**} p<0.05$，$^{***} p<0.01$。
\item 如涉及参考组、变量缩放、对数处理、聚类标准误、固定效应或样本筛选，请在此补充说明。
\item 本表的正文数据应来自 `05_analysis_output/tables/table_XX_<content>.tex` 或 `05_analysis_output/export_for_paper/paper_table_XX_<content>.tex` 中的对应接口文件。
\end{tablenotes}
```

## File: skills/spss-academic-workflow/agents/openai.yaml
size: 362
sha: c89327a805862ea7567c694c5c2043986e2cfd7a
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/agents/openai.yaml

```text
interface:
  display_name: "SPSS Academic Workflow"
  short_description: "Run SPSS empirical analysis, write Chinese results, and produce a LaTeX paper"
  default_prompt: "Use $spss-academic-workflow to run an SPSS empirical analysis, generate Chinese result sections and tables, and produce a compilable LaTeX paper."

policy:
  allow_implicit_invocation: true
```

## File: skills/spss-academic-workflow/LICENSE.txt
size: 1104
sha: 946ebfb3c3dba43b80c79ed364e1636f3bc5b998
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/skills/spss-academic-workflow/LICENSE.txt

```text
MIT License

Copyright (c) 2026 EXIST-D and SPSS Academic Workflow contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## File: README.md
upstream: https://github.com/exist-d/spss-academic-workflow/blob/main/README.md

````text
# SPSS Academic Workflow Skill

[English](README.en.md) | 简体中文

本仓库打包了 `spss-academic-workflow`，这是一个面向 Codex 的 Agent Skill，用于基于 SPSS 的中文实证学术研究流程。它可以帮助 agent 组织研究项目、准备数据集、设计变量和模型、运行或指导 SPSS/SPSS-MCP 分析、导出表格和中文结果段落、撰写中文 LaTeX 论文，并编译最终 PDF。

## 仓库结构

```text
spss-academic-workflow/
├── README.md
├── README.en.md
├── LICENSE
└── skills/
    └── spss-academic-workflow/
        ├── SKILL.md
        ├── LICENSE.txt
        ├── agents/
        │   └── openai.yaml
        ├── assets/
        ├── references/
        └── scripts/
```

## 功能范围

- 创建可复现的实证研究项目目录结构。
- 指导数据准备、变量设计、样本规则和模型设计。
- 运行或记录 SPSS/SPSS-MCP 分析，覆盖描述性统计、频数与交叉表、相关分析、均值比较、t 检验、方差分析、卡方检验、信度分析、因子分析、主成分分析、聚类分析、线性回归、分层/逐步回归、Logistic 回归、非参数检验以及常见诊断检验。
- 支持围绕实证论文展开的模型扩展，例如主效应模型、控制变量模型、稳健性检验、替代变量/替代样本检验、异质性分析、机制分析、调节效应和中介效应。
- 根据变量类型、研究问题和样本条件，为探索性任务推荐合适的 SPSS 分析路径，并记录分析选择、样本处理和结果解释依据。
- 将统计输出整理成论文可用的表格、结果说明和中文学术写作内容。
- 生成 LaTeX 源文件，并支持中文实证论文的 PDF 编译。

## SPSS-MCP 依赖

本 skill 的 SPSS-MCP 工作流使用 [Exekiel179/SPSS-MCP](https://github.com/Exekiel179/SPSS-MCP) 提供的 MCP server，将自然语言分析需求转换为 SPSS syntax，并通过本机 IBM SPSS Statistics 引擎执行分析。

本仓库不会打包 SPSS-MCP 源码，也不会替代它的安装流程。使用时请先按照 SPSS-MCP 仓库说明在本机安装并配置好 MCP server。本 skill 只是把它作为外部分析接口接入 Codex 工作流，用来完成 SPSS 数据分析、结果整理和论文写作。

### 环境要求

- Windows 10/11。
- Python 3.10 或更高版本。
- 本机已安装 IBM SPSS Statistics，SPSS-MCP 当前说明支持 version 20-31。
- 已安装并可在终端运行 `spss-mcp`。
- 当前 agent 客户端需要支持 MCP。SPSS-MCP 的自动配置命令面向 Claude Code；在 Codex 中使用时，请将等价 MCP server 配置接入 Codex，使其能够通过 `spss-mcp serve --transport stdio` 调用该服务。
- 如果 SPSS 不能被自动检测，请按 SPSS-MCP 文档设置 `SPSS_INSTALL_PATH`；如启动或分析较慢，可设置 `SPSS_STARTUP_TIMEOUT` 或 `SPSS_TIMEOUT`。

### Codex 兼容配置示例

SPSS-MCP 上游文档主要面向 Claude Code；本仓库面向 Codex 使用场景。Codex 支持本地 STDIO MCP server，可在 `~/.codex/config.toml` 或受信任项目的 `.codex/config.toml` 中加入类似配置：

```toml
[mcp_servers.spss]
command = "spss-mcp"
args = ["serve", "--transport", "stdio"]
startup_timeout_sec = 300
tool_timeout_sec = 300
```

如果需要手动指定 SPSS 路径或超时时间，可加入：

```toml
[mcp_servers.spss.env]
SPSS_INSTALL_PATH = "C:\\Program Files\\IBM\\SPSS Statistics\\31"
SPSS_STARTUP_TIMEOUT = "300"
SPSS_TIMEOUT = "300"
```

配置后重启 Codex，并在 Codex 的 MCP 状态界面确认 `spss` server 已启动。本项目作者已在 Codex + Windows + 本机 SPSS 环境下测试该工作流；其他环境请以 SPSS-MCP 上游支持范围和本机 SPSS 安装情况为准。

## 安装方式

推荐使用 [skills.sh](https://skills.sh/) 的 `skills` CLI 安装到 Codex：

```powershell
npx skills add EXIST-D/spss-academic-workflow --skill spss-academic-workflow --agent codex --yes --copy
```

该命令已在 Windows 环境下验证，可识别本仓库中的 `spss-academic-workflow`，并安装到当前项目的 `.agents/skills/spss-academic-workflow`。

也可以在 Codex 中使用 skill installer，并指向 GitHub 目录 URL：

```text
$skill-installer install https://github.com/EXIST-D/spss-academic-workflow/tree/main/skills/spss-academic-workflow
```

如果安装后没有立即出现该 skill，请重启 Codex。

## 使用示例

可以显式调用：

```text
Use $spss-academic-workflow to analyze this dataset with SPSS and produce Chinese result sections, tables, LaTeX source, and a PDF.
```

也可以用自然语言描述任务。下面是一些简单模板：

```text
请使用 SPSS 分析这份实证数据，并写出中文论文结果部分。

请帮我查看这个数据集适合做哪些 SPSS 分析，并生成项目目录和初步分析方案。

请基于这份问卷数据做描述性统计、信度分析和回归分析，并整理成论文表格。

请用 SPSS-MCP 运行主模型和稳健性检验，然后输出中文结果解释和 LaTeX 表格。

请把当前项目整理为完整的中文实证论文草稿，包括数据、模型、结果和结论部分。
```

如果希望一次性说明项目路径、数据文件、分析目标和本机环境，可以使用下面的完整模板：

```text
使用 $spss-academic-workflow，对路径“<项目根目录>”下的数据文件“<数据文件名>”进行详细的 <分析主题或模型类型> 分析。

所有工作都在“<项目根目录>”内完成。

请自行选择最完整且合理的分析流程进行全面分析，包括但不限于数据读取、变量识别、缺失值检查、描述性统计、相关分析、主模型估计、诊断检验、稳健性或补充分析，以及论文写作所需的结果整理。

请自动选择合适的 SPSS 分析流程，输出中文结果解释、结果表格、paper.tex 和可编译 PDF，并在最终回复中说明调用了哪些工具、生成了哪些关键文件，以及 PDF 是否编译成功。

请使用 conda 的“<conda 环境名>”虚拟环境。

本机 SPSS 安装目录为：“<SPSS 安装目录>”。
```

## 包含内容

- `SKILL.md`：主要 workflow 和触发说明。
- `references/`：工作流路由、实证设计、SPSS-MCP 使用、工具选择、论文写作和 LaTeX 排版的详细参考。
- `scripts/`：辅助脚本，包括保守的项目脚手架脚本。
- `assets/`：LaTeX 论文、表格注释和结果段落模板。
- `agents/openai.yaml`：可选的 Codex UI 元数据和调用策略。

## 生成项目目录

使用本 skill 处理具体实证项目时，默认会在用户指定的项目根目录下组织以下 `01` 到 `08` 目录：

```text
project-name/
├── 01_source_data/
├── 02_data_prep/
├── 03_research_design/
├── 04_spss_syntax/
├── 05_analysis_output/
├── 06_paper_draft/
├── 07_submission_package/
└── 08_project_admin/
```

- `01_source_data/`：保存原始数据、外部数据和数据来源说明；原始数据应保留在 `raw/`，不覆盖、不原地修改。
- `02_data_prep/`：保存变量映射、清洗中间数据、最终分析数据和数据审计文件，例如 codebook、缺失值检查和描述统计摘要。
- `03_research_design/`：保存研究问题、研究假设、变量设计、模型设计和样本规则。
- `04_spss_syntax/`：保存 SPSS syntax，按数据清洗、变量构造、描述统计、主模型、稳健性和附录模型分组。
- `05_analysis_output/`：保存分析输出，包括表格、图形、结果说明、运行日志和论文可直接引用的表格接口。
- `06_paper_draft/`：保存中文论文草稿、章节文件、参考文献、表格/图形输入文件、LaTeX 主稿和编译输出 PDF。
- `07_submission_package/`：保存投稿、答辩或交付所需的草稿、最终版和归档文件。
- `08_project_admin/`：保存项目管理和复现说明，例如项目 README、changelog 和 reproducibility checklist。

## 作者与维护

本项目由 [EXIST-D](https://github.com/EXIST-D) 创建并维护。

欢迎通过 GitHub Issues 提交问题、使用反馈或改进建议。如果你基于本 skill 做了扩展，也欢迎提交 Pull Request。

## 许可证

本仓库使用 MIT License。详见 [LICENSE](LICENSE)。打包后的 skill 内部也包含一份许可证副本：`skills/spss-academic-workflow/LICENSE.txt`。
````
