<p align="center"> <img src="branding/logo/horizontal@1024.png" alt="stata-code logo" width="520" /> </p> <p align="center"> <a href="README.en.md">English</a> | <a href="README.md"><strong>中文</strong></a> </p>

stata-code

<div align="center"> <table> <tr> <td align="center"> <a href="https://copaper.ai"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/copaper-logo.png" alt="CoPaper.AI" width="200" /></a> </td> <td width="48"></td> <td align="center"> <a href="https://sccei.fsi.stanford.edu/reap"><img src="https://raw.githubusercontent.com/brycewang-stanford/stata-code/main/branding/partners/stanford-reap-logo.png" alt="Stanford REAP — 斯坦福中国经济与制度研究中心" width="280" /></a> </td> </tr> </table>

_{<strong>Stanford REAP × CoPaper.AI</strong> · 面向实证研究的产学研 AI 工具箱}

</div> <p align="center"> <img src="branding/github-instructions.png" alt="stata-code: agent-native Stata bridge — one Python core, multiple frontends (Jupyter kernel, MCP server, VS Code extension)" width="720" /> </p>

面向 LLM 智能体的 Stata 桥接工具 —— 一个 Python 核心，多种前端入口。

stata-code 让你可以从现代开发环境中驱动 Stata：LLM 智能体（Claude Code、Cursor、Claude Desktop）、Jupyter notebook，或 VS Code 编辑器。它们共享同一个 Python 核心，并返回稳定、结构化、适合智能体读取的结果格式。

面向实证经济学家。 用自然语言驱动 Stata：一次对话里跑完 DiD、IV、RDD 和出版级 esttab 表——再把每个估计在 Stata 与 Python 两套实现上交叉核对，只采信结果一致的那一个（Cunningham 跨包稳健性检验）。

60 秒上手（配合 Claude Code，无需全局安装）：

claude mcp add stata-code --scope user -- uvx --from "stata-code[mcp]" stata-code-mcp

然后直接问：

“用 data/cfps_panel.dta 跑一个工人月工资对处理变量的双向固定效应回归（控制变量 age age2 edu industry），再用 Callaway-Sant'Anna 检验异质处理效应，最后输出 esttab 表。”

stata-code 会自动写 do 文件、运行、把表格回传并解读结果——还能用 StatsPAI 把同一个 ATT 再估一遍，确认两套结果一致。这些工作流以一键 MCP prompts（did_event_study、iv_2sls、rdd、publication_table、cross_validate_did）的形式提供，背后是一个按需调用的 recipe 库。

为什么选 stata-code： MIT 许可证 · 同时提供 MCP server、内置 agent skill、Jupyter kernel、VS Code 扩展 和 终端命令行（stata-code run）· 统一的结构化、省 token 的结果格式（typed errors、原生 r() / e()）· 支持 Stata 17+（pystata）或 Stata 13+（无需 pystata 的 console 后端） · 零 Python 独立二进制 · 面向无人值守 agent 的默认命令安全护栏 · 配合 StatsPAI 做跨栈交叉验证（Cunningham 检验）。

                    ┌────────────────────────────────────────┐
                    │     stata-code core (Python)           │
                    │                                        │
                    │   • pystata 17+ / console 13+ backends │
                    │   • v1.0 统一结果 schema               │
                    │   • 默认节省 token                     │
                    │   • 通过 Stata frames 支持多 session   │
                    │   • 结构化 typed errors + 建议         │
                    └────────────────────────────────────────┘
                       ↑              ↑              ↑
              ┌────────┴────┐  ┌──────┴─────┐  ┌────┴────────────┐
              │  Jupyter    │  │  MCP       │  │  VS Code        │
              │  kernel     │  │  server    │  │  extension      │
              └─────────────┘  └────────────┘  └─────────────────┘

此外还有第四个前端——终端命令行（stata-code run / lint / setup），让任何能调用 shell 的 agent（或纯终端）拿到同一套带类型的 RunResult；core 支持两种后端：pystata（Stata 17+，内存会话）或 console 后端（Stata 13+ 批处理，无需 pystata），两者返回完全相同的 schema。

当前状态：v0.12（2026 年 7 月） —— core、MCP server、Jupyter kernel、VS Code 扩展和命令行都已经在 Stata 18 MP 上端到端跑通；console 后端把覆盖范围扩展到无需 pystata 的 Stata 13+。v0.12 新增常驻会话 daemon，让连续多次 CLI 调用共享内存中的数据；在此之前 v0.11 是一个「agent 使用体验」版本：返回体可裁剪、长任务可后台执行、do 文件内报错可定位、失败运行的 log 句柄自动关闭、生成文件自动上报 —— 详见 changelog。测试套件覆盖 schema、runner、console 解析器、MCP、kernel、notebook、run-index、subprocess pool、命令安全、linter 和 VS Code 等模块；CI 也检查 lint、类型、schema 生成、包元数据和 VSIX 打包。许可证：MIT。快速上手见 docs/quickstart.zh.md。

当前代码树明确支持的三类用户 / agent 工作流：

• 在 Jupyter notebook 里跑 Stata 代码。 pip install "stata-code[kernel]" + stata-code-kernel install --user 会注册一个名为 Stata 的 kernel，Jupyter Notebook、JupyterLab、以及 VS Code 的 Jupyter 扩展都能在 kernel 选择器里看到它。Cell 里直接写 Stata 命令，日志、图形和警告会内联渲染（自 v0.5 起 kernel logo 已一起打包进 PyPI wheel，VS Code 的 Jupyter kernel picker 也能正常显示）。详见下文 作为 Jupyter kernel。
• 可选的 agent「修复并重跑」循环。 stata_run 在每次失败时都会返回结构化的 error.kind/line/context 和 suggestions。默认情况下 Claude Code 只把它当作诊断信息上报；但如果你明确说「帮我修到跑通」「修复并反复运行直到成功」，agent 就会用同一组字段去改 .do 文件、再调 stata_run，直到代码通过。这个修复循环是 opt-in 的：默认失败 = 诊断，不是自动改写授权。详见下文 Agent 工作流里的报错恢复。
• 经济学实证工作流指南。 随包 skill 和 cookbook 覆盖现代 DiD、IV/弱工具变量、RDD、表格导出、data-MCP 到 Stata 的交接、以及跨包/跨栈 parity audit。stata-code 负责运行和审计 Stata 这一侧；R、Python、官方数据 MCP 仍是独立工具，通过显式 handoff 文件和 source metadata 衔接。详见 skills/stata-code/references/ 和 examples/。

---

为什么做这个项目

Stata 的 AI / agent 工具生态现在比较分散，详见 References-tools.md：

• 现有 MCP server（SepineTam/stata-mcp、tmonk/mcp-stata）使用 AGPL-3.0，不适合闭源或商业集成。
• 常用的 VS Code AI 插件（hanlulong/stata-mcp）是 MIT，但 MCP server 被打包在插件内部，不方便单独复用。
• 每个工具都用自己的方式封装 pystata，返回结构不统一，智能体需要为不同工具写特殊处理。
• 很多工具一开始是为人类交互设计的，再接到 MCP 上；它们经常把 200 行日志和 base64 图片直接塞进回复，默认就大量消耗 token。

stata-code 要填补的就是这个空位：

1. MIT 许可证，没有 copyleft 传染问题。
2. 所有前端共享同一个结果格式：SCHEMA.md。
3. 默认面向智能体：typed errors、结构化 r() / e()、log refs、graph refs、suggestion seeds。
4. 一个 core，多个入口：Jupyter kernel、MCP server、VS Code 扩展。

如果你关心 AGPL/GPL Stata 项目的 clean-room 边界，请看 LICENSE-POLICY.md。

---

安装

要求：Python 3.10+，外加以下任一种 Stata —— Stata 17+（用其自带的 pystata， 支持内存内会话），或 Stata 13+（走 console 后端，不需要 pystata，无状态）。

# 从 PyPI 安装
pip install stata-code

# 同时安装 MCP server 和 Jupyter kernel 的额外依赖
pip install "stata-code[mcp,kernel]"

# 或者从源码安装（开发用 editable install）
git clone https://github.com/brycewang-stanford/stata-code.git
cd stata-code
pip install -e ".[mcp,kernel]"

命名说明。 PyPI 上的发行包名是 stata-code（带连字符）， 但 Python 导入名是 stata_code（下划线 —— Python 标识符不能包含连字符）。 和 scikit-learn → import sklearn 是同样的约定。 所以：pip install stata-code，from stata_code import run。

注意：pystata 不在 PyPI 上，它随 Stata 一起安装。stata-code 会自动在 macOS 的 /Applications/Stata/utilities/pystata 以及 Linux / Windows 的对应位置寻找它。如果你的 Stata 安装在其他位置，请在导入前把 pystata 加到 PYTHONPATH。

安装后可以用只读 doctor 检查本机环境：

stata-code doctor
stata-code doctor --json          # 机器可读输出
stata-code doctor --no-stata-probe # 跳过实时 Stata 初始化
stata-code doctor --workspace /path/to/project --no-user-config-scan

doctor 会报告 package/Python 版本、MCP 和 Jupyter extras、pystata 发现结果、 PATH 上的 console scripts、常见项目级/用户级 MCP client 配置文件、 client/VS Code 配置提示，以及 best-effort 的 Stata 版本/edition 探测。它不会 改 shell、Stata、Claude、Cursor 或 VS Code 配置。

---

快速开始

完整 cookbook 在 examples/：基础回归、DiD、图形、多 session、大矩阵。

作为 Python library

包级 run() / execute() API 使用和 MCP server 相同的 subprocess-backed runner，因此长任务会遵守 timeout_ms，pystata 对 stdout 的重定向也会被隔离在 worker 进程中，不会污染调用方进程。

from stata_code import run

r = run("sysuse auto, clear")
r = run("regress mpg weight")

if r.ok:
    print(r.results.e.scalars["r2"])           # 0.6515 (native float)
    print(r.results.e.macros["cmd"])           # "regress"
    b = r.results.e.matrices["b"]
    print(dict(zip(b.cols, b.values[0])))      # {"weight": -0.006, "_cons": 39.44}
else:
    print(r.error.kind, r.error.message)       # ErrorKind.VARNAME_NOT_FOUND, "..."
    for s in r.error.suggestions:
        print("hint:", s.action)               # "Did you mean `mpg`?"

从命令行使用（Bash）

任何能 shell out 的 agent 或脚本都能用上同一套结构化引擎 —— 不需要 MCP。 stata-code run 可以执行 .do 文件、一个或多个 -e 片段，或从 stdin 读入的代码， 并打印 RunResult：

stata-code run analysis.do                  # 跑 do 文件，输出文本摘要
stata-code run -e "sysuse auto" -e "regress mpg weight"
stata-code run analysis.do --json           # 完整 RunResult JSON（给 agent 用）
echo "summarize price" | stata-code run -    # 从 stdin 读代码
stata-code run model.do --graphs out/        # 同时把图形导出到 out/
stata-code run job.do --session modelA --timeout-ms 120000

成功退出码是 0，Stata / adapter 出错时是 1，因此可以直接接进 CI 和"改了再跑"的 脚本循环。stata-code lint analysis.do 则在完全不启动 Stata 的前提下做静态检查 （大括号不配对、缺 end、悬空的 ///）。

后端 —— Stata 13+ 且没有 pystata。 --backend 决定代码怎么跑：pystata （Stata 17+，内存内会话）、console（Stata 13+ 批处理，不需要 pystata，无状态）， 或 auto（默认：有 pystata 就用，否则退到 console）。console 后端驱动 Stata 的命令行 可执行文件，并把日志解析成同样的带类型 RunResult —— 带类型的 r()/e()、估计表、 以及错误分类 —— 所以老版本 Stata 和无 pystata 的环境同样是一等公民：

stata-code run analysis.do --backend console
export STATA_CODE_STATA_CLI=/usr/local/stata18/stata-mp   # 自动找不到时手动指定

零 Python 二进制。 独立的 stata-code 可执行文件（由 scripts/build_standalone.py 构建，现成的 CI workflow 模板见 packaging/standalone.github-workflow.yml） 把运行时一起打包，不需要安装 Python。配合 --backend console，这就是一条完全不依赖 Python、又能拿到带类型 Stata 结果的路径。

会话 daemon（跨调用保持数据）

stata-code run 默认每次调用都起一个新进程，进程一退，内存里的数据就没了。 daemon 子命令把 subprocess pool 挪进一个常驻进程，通过 Unix socket 对外服务， 于是连续两次 run --daemon 会落在同一个 Stata 会话上：

stata-code run --daemon -e 'sysuse auto, clear' -e 'gen z = price/1000'
stata-code run --daemon -e 'summarize z'      # 新进程，但 z 还在
stata-code run --daemon -e 'regress price mpg'
stata-code run --daemon -e 'display e(r2)'    # 上一个进程留下的 e() 也还在

第一次 run --daemon 会自动把 daemon 拉起来，不需要手动 start。也可以显式管理：

stata-code daemon start                    # 后台启动（--foreground 留在当前终端）
stata-code daemon status                   # pid、uptime、活跃 session 列表
stata-code daemon status --json
stata-code daemon stop
stata-code daemon restart
stata-code daemon start --idle-timeout 0   # 0 = 永不因空闲退出

几个要点：

• 会话隔离照旧。 --session other 在 daemon 里仍然是独立的 Stata frame / worker， 彼此看不到对方的数据。
• 默认空闲 30 分钟自动退出，免得忘了关的 daemon 一直占着 Stata license。 用 --idle-timeout 调整，0 表示禁用。
• 只监听 Unix socket，不开 TCP。 daemon 会执行任意 Stata 代码，所以刻意只