Easy Stata Empirical

使用前置：需在 Agent 中配置 Stata MCP，可直接告诉 Agent“给我配置 Stata 的 MCP”。

中文

项目简介

把重复、批量的回归工作交给机器，把研究判断、执行许可和最终复现留给研究者。

这是一个面向会计、金融、管理和经济学研究者的 Agent 驱动 Stata 实证工作流 Skill。研究者提供一张已经整理好、可以直接进入回归的分析数据表，其中尽可能包含研究所需的候选解释变量 X、被解释变量 Y、控制变量和机制变量。研究者再确定允许使用的控制变量族、固定效应组合、模型、标准误和各阶段通过标准。

Skill 与 Agent 在这些边界内批量生成和执行回归、整理结果并按通过标准推进漏斗；研究者在每个阶段负责判断和批准，最后亲自完成保留规格的代码复现与数据复现。

人机协同

| 研究者负责 | Skill + Agent 负责 | | -------------------------------------------- | ---------------------------------------- | | 准备分析数据表，明确研究问题 | 读取数据结构并把研究边界转成可执行任务 | | 确定候选 X、Y、控制变量族和机制变量池 | 批量生成变量、模型、固定效应和标准误组合 | | 确定固定效应、模型、聚类方式和各阶段通过标准 | 编写并执行项目对应的 Stata 代码 | | 批准开始执行，并确认每一阶段保留哪些组合 | 保存完整 history，生成便于判断的 review | | 判断最终论文规格、经济含义和论证边界 | 按人工确认结果把组合送入下一阶段 | | 对最终组合进行代码复现和数据复现 | 记录日志、失败结果、配置和 provenance |

机器不替研究者提出结论，也不自动决定论文应该采用哪一个规格。它负责执行、筛选、回归和整理；研究者始终保留判断权和最终责任。

漏斗式回归工作流程

flowchart LR
    A[研究者提供分析数据表<br/>X / Y / 控制变量 / 机制变量] --> B[研究者确认边界<br/>控制变量族 / 固定效应 / 模型 / SE / 通过标准]
    B --> C[机器批量执行<br/>Baseline 基准回归]
    C --> D{研究者审阅并确认<br/>符合基准回归标准?}
    D -->|保留| E[机器批量执行<br/>Robustness 稳健性检验]
    D -->|不保留| X1[留在 history]
    E --> F{研究者审阅并确认<br/>符合稳健性标准?}
    F -->|保留| G[机器批量执行<br/>Mechanism 机制回归]
    F -->|不保留| X2[留在 history]
    G --> H[最终候选组合<br/>Baseline + Robustness + Mechanism]
    H --> I[研究者判断最终规格<br/>代码复现 + 数据复现]

具体流程是：

大批量基准回归：研究者先确定候选 X/Y、控制变量族、固定效应组合、模型和标准误，机器在批准范围内批量执行 baseline 组合。
进入稳健性检验：机器呈现全部结果；经研究者审阅确认、符合基准回归通过标准的组合进入 robustness。
进入机制回归：经研究者审阅确认、符合稳健性通过标准的组合进入 mechanism，并且只使用研究者批准的机制变量和机制路径。
形成最终候选集合：最终留下同时通过基准回归、稳健性检验和机制回归的组合，供研究者判断论文规格。
人工复现与最终判断：Skill 和 Agent 到此只完成执行、筛选、回归和整理；最终采用什么规格，以及代码和数据能否复现，由研究者亲自确认。

核心能力

一个公开 Skill 入口，不要求用户理解多个子 Skill；
对话式收集研究边界、阶段许可和人工选择，并沉淀为 Markdown 与 JSON；
在批准范围内批量执行 baseline、robustness 和 mechanism 回归；
生成稳定、跨机器可复现的 baseline combination_id；
标准化 baseline、robustness、mechanism 的 history/review 契约；
保留符号、显著性、星级和 pass 标记，帮助研究者直观审阅结果；
默认不覆盖文件、不修改输入数据、不删除工作流文件；
为配置、数据和运行产物生成 SHA-256 provenance manifest。

安装

根据需要，将英文版 easy-stata-empirical/ 或中文版 easy-stata-empirical-cn/ 复制到 Skills 目录，然后使用对应调用名：

使用 $easy-stata-empirical 启动我的 Stata 实证分析工作流。
使用 $easy-stata-empirical-cn 启动我的中文 Stata 实证分析工作流。

Skill 不捆绑 Stata。执行回归需要本机已有合法可用的 Stata 环境。

Python 辅助自动化

Python 只处理跨项目重复、规则明确的机械工作，减少 Agent 每次重新编写相同逻辑所消耗的 token；项目特定的 Stata 回归代码仍由 Agent 根据研究者批准的设计生成。

python3 scripts/workflow_cli.py init \
  --root /path/to/research-workflow \
  --template assets/templates/analysis_config.example.json

python3 scripts/workflow_cli.py validate \
  --config /path/to/research-workflow/analysis_config.json

python3 scripts/workflow_cli.py expand \
  --config /path/to/research-workflow/analysis_config.json \
  --output /path/to/research-workflow/02_AI输出/baseline/code/baseline_specifications.csv

Agent 随后读取配置和规格表，按研究者批准的模型编写 Stata .do 文件。Stata 导出的结果 CSV 可交给 review，阶段文件可交给 manifest。运行 python3 scripts/workflow_cli.py --help 查看完整参数。

Agent 与 Python 脚本的分工

Python 负责可确定、跨项目重复的机械工作：初始化、JSON 校验、网格展开、稳定 ID、review 派生和文件哈希。Agent 负责变量语义、数据变换、估计命令、固定效应实现、稳健性设计、机制路径、错误诊断和经济解释。

安全与复现

输入数据必须配置为只读；输出目录不能与数据文件相同；初始化只创建缺失文件；CLI 默认拒绝替换已有输出；Stata 仅在 execution.allow_stata_run 为 true 时由 Agent 执行。history 必须包含失败和不显著的尝试，review 只提供紧凑的人类视图。

当前边界

不负责原始数据的大规模清洗和合并；
不替研究者定义研究问题或最终论文规格；
不尝试用统一模板覆盖所有 Stata 计量实现；
mechanism review 当前验证并保留标准 evidence rows，复杂展示仍由 Agent 按项目生成；
自动化测试不需要 Stata，真实回归仍需人工验收。

扩展实证方法

本项目允许普通研究者增加新的估计方法、识别设计、诊断、稳健性检验和报告规范。扩展入口包括：

贡献指南：新增方法、质量要求和审阅责任；
方法目录：现有模块及其维护状态；
统一方法模板：适用边界、识别假设、Stata 实现、诊断、稳健性、报告和维护信息；
validate-method：在提交前检查文件名、元数据和必要章节。

新增方法默认标记为 draft。结构校验通过不代表方法在所有研究中正确；维护者和使用者仍需审阅最新文献、Stata 命令、识别假设和项目适用性。我们只提供可扩展框架和贡献建议，不预先加入维护者尚不能确认的方法模块。

python3 easy-stata-empirical/scripts/workflow_cli.py \
  validate-method \
  --file easy-stata-empirical/references/methods/<method-id>.md

许可

本项目采用 CC BY-NC-SA 4.0。使用者必须署名，不得用于商业目的，演绎作品必须使用相同许可。由于包含“非商业”限制，本项目属于源码公开、允许非商业复用，但不是 OSI 认可的开源软件许可证。

English

Prerequisite: Stata MCP must be configured in your Agent. You can simply tell the Agent: “Configure the Stata MCP for me.”

Overview

Give repetitive, high-volume regression work to the machine; keep research judgment, execution approval, and final replication with the researcher.

This is an Agent-driven Stata empirical workflow Skill for accounting, finance, management, and economics researchers. The researcher supplies one analysis-ready table containing, as far as the research design requires, candidate explanatory variables X, outcomes Y, controls, and mechanism variables. The researcher then defines the approved control families, fixed-effect combinations, models, standard errors, and pass rules.

Within those boundaries, the Skill and Agent generate and run regressions in batches, organize the results, and move approved combinations through a funnel. The researcher judges and authorizes every stage and personally completes final code and data replication.

Human-machine collaboration

| Researcher | Skill + Agent | | ------------------------------------------------------------ | ------------------------------------------------------------ | | Prepare the analysis-ready table and define the research question | Read the data structure and translate approved boundaries into executable tasks | | Define candidate X, Y, control families, and mechanism variables | Generate approved variable, model, fixed-effect, and standard-error combinations in batches | | Define fixed effects, models, clustering, and stage pass rules | Write and run project-specific Stata code | | Authorize execution and decide which combinations survive each stage | Preserve complete history and build compact review outputs | | Judge the final paper specification, economic meaning, and claim boundary | Send only human-approved combinations to the next stage | | Replicate the final code and data results | Record logs, failures, configuration, and provenance |

The machine does not make the paper's final specification decision or replace the researcher's conclusions. It executes, screens, estimates, and organizes; the researcher retains judgment and final responsibility.

Funnel regression workflow

flowchart LR
    A[Researcher supplies analysis table<br/>X / Y / controls / mechanisms] --> B[Researcher approves boundaries<br/>control families / FE / model / SE / pass rules]
    B --> C[Machine runs batch<br/>baseline regressions]
    C --> D{Researcher reviews and confirms<br/>passes baseline rule?}
    D -->|Keep| E[Machine runs batch<br/>robustness checks]
    D -->|Do not keep| X1[Retained in history]
    E --> F{Researcher reviews and confirms<br/>passes robustness rule?}
    F -->|Keep| G[Machine runs batch<br/>mechanism regressions]
    F -->|Do not keep| X2[Retained in history]
    G --> H[Final candidate combinations<br/>baseline + robustness + mechanism]
    H --> I[Researcher selects specification<br/>code replication + data replication]

The workflow is:

Large-scale baseline regressions: the researcher approves candidate X/Y, control families, fixed-effect combinations, models, and standard errors; the machine runs the admissible baseline grid.
Advance to robustness: the machine presents all results; combinations that the researcher confirms as meeting the baseline pass rule enter robustness checks.
Advance to mechanisms: combinations that the researcher confirms as meeting the robustness rule enter mechanism regressions, using only approved mechanism variables and paths.
Build the final candidate set: combinations that pass baseline, robustness, and mechanism stages become candidates for the paper specification.
Human replication and judgment: the Skill and Agent stop at execution, screening, estimation, and organization. The researcher personally confirms the final specification and reproduces both code and data results.

Core capabilities

One public Skill entry point; users do not need to understand separate child Skills.
Conversational research boundaries, execution approvals, and stage selections preserved as Markdown and JSON.
Batch baseline, robustness, and mechanism regressions within the approved boundary.
Stable, cross-machine baseline combination_id generation.
Standard history/review contracts for baseline, robustness, and mechanism stages.
Visible direction, significance, stars, and pass flags for researcher review.
No replacement by default, no input-data modification, and no workflow-file deletion.
SHA-256 provenance manifests for configuration, data, and run artifacts.

Installation

Copy either the English easy-stata-empirical/ package or the Chinese easy-stata-empirical-cn/ package into the Skills directory, then use its matching invocation name:

Use $easy-stata-empirical to start my Stata empirical workflow.
使用 $easy-stata-empirical-cn 启动我的中文 Stata 实证分析工作流。

The Skill does not bundle Stata. Regression execution requires a legally available local Stata installation.

Python-assisted automation

Python handles only repeated, rule-based mechanics shared across projects, reducing the tokens an Agent would otherwise spend rebuilding the same logic. The Agent still generates project-specific Stata code from the researcher-approved design.

python3 scripts/workflow_cli.py init \
  --root /path/to/research-workflow \
  --template assets/templates/analysis_config.example.json

python3 scripts/workflow_cli.py validate \
  --config /path/to/research-workflow/analysis_config.json

python3 scripts/workflow_cli.py expand \
  --config /path/to/research-workflow/analysis_config.json \
  --output /path/to/research-workflow/02_AI输出/baseline/code/baseline_specifications.csv

The Agent then reads the config and specification table and writes Stata .do files for the researcher-approved models. Stata result CSVs can be passed to review, and stage artifacts can be passed to manifest. Run python3 scripts/workflow_cli.py --help for all arguments.

Agent and Python script responsibilities

Python handles deterministic mechanics repeated across projects: initialization, JSON validation, grid expansion, stable IDs, review derivation, and file hashing. The Agent handles variable semantics, transformations, estimator commands, fixed-effect implementation, robustness design, mechanism paths, error diagnosis, and economic interpretation.

Safety and reproducibility

Input data must be configured read-only; the output root cannot equal the data file; initialization creates only missing files; the CLI refuses to replace existing outputs by default; and the Agent runs Stata only when execution.allow_stata_run is true. History includes failed and non-significant attempts, while review provides a compact human view.

Current boundaries

No large-scale raw-data cleaning or merging.
No automatic research-question or final-paper specification choice.
No attempt to force every Stata estimator into one universal template.
Mechanism review currently validates and preserves standard evidence rows; the Agent creates complex project-specific presentation.
Automated tests do not require Stata; real regressions still require human acceptance.

Extending empirical methods

Researchers may contribute estimators, identification designs, diagnostics, robustness checks, and reporting standards. The extension points are:

Contribution guide: method workflow, quality requirements, and review responsibilities.
Method catalog: current modules and maintenance status.
Method template: use boundaries, identification assumptions, Stata implementation, diagnostics, robustness, reporting, and maintenance.
validate-method: checks filenames, metadata, and required sections before submission.

New methods begin as draft. Passing structural validation does not prove that a method is correct for every study. Maintainers and users must still review current literature, Stata commands, identification assumptions, and project fit. The repository supplies an extensible framework and contribution guidance without pre-installing methods the maintainer cannot yet verify.

python3 easy-stata-empirical/scripts/workflow_cli.py \
  validate-method \
  --file easy-stata-empirical/references/methods/<method-id>.md

License

This project uses CC BY-NC-SA 4.0. Users must provide attribution, may not use the work commercially, and must license adaptations under the same terms. Because of the NonCommercial restriction, the source is publicly available for non-commercial reuse but is not OSI-approved open-source software.