English | 中文

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

面向 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.10（2026 年 7 月） —— core、MCP server、Jupyter kernel、VS Code 扩展和命令行都已经在 Stata 18 MP 上端到端跑通；console 后端把覆盖范围扩展到无需 pystata 的 Stata 13+。测试套件覆盖 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。

要求：Stata 17+（自带 pystata）和 Python 3.10+。

# 从 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、大矩阵。

包级 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`?"

pip install "stata-code[mcp]" 之后，stata-code-mcp 会出现在你的 PATH 中。可以接到 Claude Code、Cursor、Claude Desktop 等任何兼容 MCP 的客户端里。

如果你还没有安装 Claude Code，请先看 anthropics/claude-code。

最快的方式是 claude mcp add 命令。根据想要的可见范围选 scope：

# user scope —— 一次安装，本机所有 Claude Code workspace 全局可用
claude mcp add stata-code --scope user -- stata-code-mcp

# local scope —— 仅当前 workspace（本地 Claude 配置，不会提交到仓库）
claude mcp add stata-code --scope local -- stata-code-mcp

# project scope —— 写入仓库内的 ./.mcp.json，和协作者共享
claude mcp add stata-code --scope project -- stata-code-mcp

接着运行 claude，输入 /mcp 确认 stata-code 出现并带有 19 个工具（stata_run, stata_info, get_log, search_log, get_graph, get_matrix, inspect_data, lint_do, install_package, list_sessions, cancel_session, reset_session, notebook_outline, notebook_get_cell, notebook_locate, notebook_edit_cell, notebook_insert_cell, notebook_delete_cell, list_runs）。

stata_run 不会自行改写源 .do 文件或替你改代码。它执行提交的 Stata 代码，所以代码本身仍可能照常生成日志、图形、表格或其他输出。Stata 报错时，stata_run 返回结构化诊断（error.kind, error.message, error.line, error.context）和尽力生成的 suggestions。这支持两种不同的 Claude Code 工作流：

• 如果你说的是「运行这个 do-file」或「验证这段代码」，Claude 可以只报告失败原因和建议的下一步，不修改源文件。
• 如果你明确说「帮我修到跑通」或「修复并反复运行直到成功」，Claude 可以基于同一组结构化错误字段修改 .do 文件，再调用 stata_run 继续迭代。

如果需要自动修复循环，请明确说出来。否则，失败的运行应先被视为诊断结果，而不是自动改写代码的授权。

如果不想全局 pip install stata-code，可以用 uv 临时运行：

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

uvx 会在首次启动时下载并缓存 stata-code。注意：pystata 不在 PyPI 上，仍需要在宿主机上能找到。runner 会自动把标准 Stata 安装路径（macOS 上的 /Applications/Stata/utilities/pystata 等）加到 sys.path；如果你的 Stata 在别处，请用 env 设置 PYTHONPATH。

本仓库还带有 Claude Code 插件清单（.claude-plugin/）。把 marketplace 加入你的 Claude Code 配置后，两条命令即可同时接好 MCP server 和教会 Claude v1.0 结果 schema 的 agent skill：

claude plugin marketplace add brycewang-stanford/stata-code
claude plugin install stata-code

插件会注册 stata-code MCP server，并安装 stata-code skill，让 Claude 学会按 error.kind 分支、惰性调用 get_log(ref)、并直接使用 notebook 编辑工具，无需每个会话重新解释。

大多数非 Claude Code 的 MCP client 都接受同一段 JSON 配置。把它放进对应 client 的 MCP 配置文件即可：

对于没有 mcp add CLI 的客户端，直接编辑配置文件即可（~/.claude/mcp.json、Cursor settings、Claude Desktop 的 claude_desktop_config.json 等）：

{
  "mcpServers": {
    "stata-code": {
      "command": "stata-code-mcp"
    }
  }
}

如果 stata-code-mcp 不在 PATH 上，也可以以 module 方式运行：

python -m stata_code.mcp

如果 stata-code-mcp 安装在项目内 virtualenv（推荐用于可复现环境），建议在 client 配置里写绝对路径，例如 /abs/path/to/.venv/bin/stata-code-mcp。

如果 stata_run 返回 adapter_crash，并出现 worker emitted non-JSON: '\n'， 请升级到 stata-code>=0.6.4，然后重启 MCP client，让它启动新的 server 进程。 同时确认 client 解析到的是预期的 stata-code-mcp；项目内 virtualenv 安装 应使用 .venv/bin/stata-code-mcp 的绝对路径，不要依赖全局 PATH。

如果 OpenAI 系客户端返回 API Error: 400 Invalid schema for function 'mcp__stata-code__notebook_insert_cell'，并提到顶层 oneOf，请升级到 stata-code>=0.6.5，然后重启 MCP client。旧 server 进程在重启前仍会继续 暴露旧 schema。

MCP server 注册了 19 个工具：

对于新版 MCP 客户端，这些工具会返回 structuredContent，并在 tool metadata 里声明 outputSchema；同时仍保留序列化 JSON text block，兼容旧客户端。 server 还暴露 MCP resources：

同时提供 MCP prompts：run_do_file_and_report、debug_stata_error、 fix_and_rerun_until_passes、replication_audit、 plan_cross_stack_parity_audit、data_mcp_to_stata_handoff、 summarize_estimation_results、run_notebook_cell_and_report、 fix_and_rerun_notebook_cell、did_event_study、iv_2sls、rdd、 publication_table 和 cross_validate_did，用于常见 agent 工作流。

stata-code 的 Jupyter 支持是以 kernel 形式打包在 Python 包里的 —— JupyterLab 插件市场里没有独立的 "stata-code 插件"。安装分两步：先 pip install 安装带 kernel extra 的包，再把 kernelspec 注册到 Jupyter。

前置条件：本机已经安装 Stata 17+ 且持有合法许可证（kernel 通过 pystata 调用本地 Stata），同一个 Python 环境里已经装好 jupyter/jupyterlab，Python 版本 ≥ 3.10。

# 1. 安装带 kernel extra 的 stata-code（会同时装上 ipykernel）
pip install "stata-code[kernel]"

# 2. 把 kernelspec 注册到当前用户的 Jupyter data dir
stata-code-kernel install --user
# 等价命令：
# python -m stata_code.kernel install --user

检查 kernel 是否注册成功：

jupyter kernelspec list
# 输出里应该能看到名为 `stata` 的条目

然后打开 Jupyter Notebook / JupyterLab（或 VS Code 中的 .ipynb），在 kernel 选择器里挑 Stata，cell 里直接写 Stata 命令即可，日志、graphs 和 warnings 会以内联方式显示。

JupyterLab 的 Extension Manager 只能安装前端 JS 扩展，装不了 kernel。所以上面的 pip install + install --user 是唯一支持的安装路径。

配套扩展已发布到 Marketplace：brycewang-stanford.stata-code-vscode。它会以子进程方式启动 stata-code-mcp，并提供语法高亮、**# section 和 program define 的 Outline、.do 文件的 code-lens "Run cell" / "Run section"、七视图侧边栏（sessions / last result / data 变量浏览器 / run history / logs / graphs / outputs）——其中包含一个 agent-native 版的 Stata 变量窗口，以及一个把每次运行写到磁盘的 esttab 表格和 export 文件呈现出来的 Outputs 面板——状态栏指示器、补全、帮助跳转、保守变量重命名，以及来自 v1.0 typed errors 的内联诊断。

# 从 VS Code 命令行
code --install-extension brycewang-stanford.stata-code-vscode

或者打开 VS Code 的 Extensions 侧栏，搜索 stata-code。扩展同时发布在 Open VSX，因此 Cursor、Windsurf 等 VS Code 兼容编辑器不必经过微软 Marketplace 也能安装。

首次激活时，扩展会在 PATH（以及 workspace 下的 .venv / venv）里探测 stata-code-mcp。如果找不到，会弹出一次性的安装提示，附上准确的 pip install "stata-code[mcp]" 命令——选择 Don't show again 可对当前扩展版本永久静默。

扩展仍然依赖系统 Python 上安装了 MCP extra（pip install "stata-code[mcp]"），从而保证 stata-code-mcp 在 PATH 上可用，并且能导入 MCP SDK。和其它前端一样，需要 Stata 17+ 和有效的 Stata 许可证。

扩展识别 .do 文件里两类互补的结构标记。二者可以混用在同一个文件里，互不冲突：

program define … end 代码块也会出现在 Outline 里，嵌套在所属 section 之下。

如果扩展或 MCP client 找不到 server，请在同一个 Python 环境里运行 stata-code doctor --no-stata-probe。它会报告 stata-code-mcp 是否在 PATH 上，并提示 GUI client 常见的绝对路径或 python -m stata_code.mcp 兜底配置。它也会读取当前 workspace 和用户目录里常见的 MCP 配置文件，告诉你 client 是否已经指向 stata-code。

典型的 stata_run 响应比现有 MCP server 直接返回日志和图片的方式小约 10 倍。核心设计有三点：

1. 日志默认只返回 head + tail + ref。完整日志可以按需用 get_log(ref) 获取。Stata 回归日志可能有约 6,000 tokens，stata-code 默认约 600 tokens。
2. 图形默认返回 refs，不内联 base64。一个 30 KB PNG 转成 base64 约 50,000 tokens；返回 ref 可以让智能体只在真正需要渲染时再取 bytes。
3. 错误是结构化 typed errors。智能体可以判断 err.kind == "varname_not_found"，而不是正则解析英文日志。

例如，变量名写错时返回的是结构化错误：

{
  "ok": false,
  "rc": 111,
  "error": {
    "kind": "varname_not_found",
    "varname": "mpgg",
    "line": 3,
    "context": {
      "before": ["use auto"],
      "failing": "summarize mpgg",
      "after": []
    },
    "suggestions": [
      {"action": "Did you mean `mpg`?", "command": "describe"}
    ]
  }
}

完整 schema 见 SCHEMA.md。

stata_code/
├── core/
│   ├── _runtime.py    # process-singleton pystata wrapper
│   ├── _refs.py       # LRU ref store for log/graph/matrix payloads
│   ├── schema.py      # Pydantic v2 models for the v1.0 result schema
│   ├── errors.py      # rc → ErrorKind mapping + suggestion seeds
│   ├── runner.py      # in-process execute(); collects everything via sfi
│   └── _pool.py       # subprocess workers for public API / MCP hard timeouts
├── mcp/
│   └── server.py      # MCP server (19 tools)
└── kernel/
    └── kernel.py      # Jupyter kernel

runner.py 是唯一直接接触 pystata 的地方。包级 Python API 和 MCP server 会先走 _pool.py，由隔离的 worker subprocess 调用 runner.execute()；Jupyter kernel 为了 notebook 交互性仍使用 in-process runner。

stata-code 是这个问题空间里更年轻的、MIT 许可证的、agent-native 的替代方案。AGPL 方案里，SepineTam 的 stata-mcp 目前更成熟；stata-code 的目标是服务那些不能接受 copyleft 传染、又需要结构化智能体接口的场景。

• v1.0 result schema (SCHEMA.md)
• 基于 pystata 的 runner，原生类型化的 r()、e() 和矩阵
• 通过 Stata frames 支持多 session（session_id 接受 [A-Za-z0-9_-]+；例如 model-a 这类 id 会在内部映射到合法的私有 frame 名，但返回结果仍回显公开 id）
• 行级错误归属：line number、context、commands_executed
• 图形捕获：png / svg / pdf + ref store，并记录来源命令归属
• 日志截断 + ref store
• 警告抽取：5 类 + 通用 notes
• 31 类错误分类法 + 标准化建议
• MCP server：19 个工具，覆盖执行、notebook 导航 / 检索 / 原子化编辑、运行索引（list_runs）、日志检索（search_log）、数据集检查（inspect_data）、静态检查（lint_do）和包安装（install_package）
• 命令安全护栏：shell、winexec、erase、rm、rmdir、! 等 OS 逃逸 / 删除文件命令在执行前被拦截；可通过 STATA_CODE_COMMAND_POLICY / STATA_CODE_POLICY_ALLOW / STATA_CODE_POLICY_BLOCK 配置
• Bash / 终端入口：stata-code run（.do 文件、-e 片段或 stdin）打印同一套结构化 RunResult，任何能调用 shell 的 agent 都可消费；stata-code lint 运行静态检查；stata-code setup 写入 MCP 客户端配置
• Console（批处理）后端（core/console.py、--backend console、run_console()）：驱动 Stata 命令行、把日志解析成同一套带类型的 RunResult，支持 Stata 13+ 且无需 pystata
• 零 Python 独立二进制（scripts/build_standalone.py + CI 工作流模板 packaging/standalone.github-workflow.yml）；配合 --backend console 是完全不依赖 Python 的一条龙
• VS Code 一键上手：扩展可自动在工作区创建 .venv 并安装 server（命令面板：“Stata: Set Up MCP Server”）
• 中文快速上手指南：docs/quickstart.zh.md
• Jupyter kernel：接入 v1.0 pipeline，kernel logo 已随 wheel 一起打包
• 矩阵大小上限 + 大矩阵的 get_matrix(ref)（>10k cells）
• 公共 Python API 和 MCP server 的 subprocess-backed 硬超时与取消：timeout_ms、cancel(session_id)、MCP cancel_session
• .ipynb 单 cell 修复闭环：notebook_outline / notebook_get_cell / notebook_edit_cell，并通过 expected_source 做乐观并发控制；stata_run 回显 origin_cell_id
• 持久化 run bundle + list_runs：按 cell / origin / session / since / ok 查询 manifest.json，并用 limit / offset 翻页
• 只读 stata-code doctor / verify 诊断：检查 package 版本、extras、 pystata 发现、console scripts、client 配置提示，以及可选的实时 Stata 版本探测
• 经济学实证工作流层：现代 DiD、IV/弱工具变量、RDD、表格导出、data-MCP handoff、跨包/跨栈 parity audit 的 skill references 和 cookbook examples
• 从 schema.py 自动生成 JSON Schema 工件：schema/run_result.schema.json
• VS Code 扩展已发布到 Marketplace brycewang-stanford.stata-code-vscode：语法高亮、section outline/navigation、code-lens cell/section runner、七视图侧边栏（sessions / last result / data 变量浏览器 / run history / logs / graphs / outputs）、状态栏、补全、保守变量重命名、诊断、MCP 子进程
• Clean-room 许可证策略 (LICENSE-POLICY.md)

• Stata 11–16 的 console fallback，按 v1.0 schema 重新实现
• 决定 Jupyter kernel 是否也迁到 subprocess pool，或者继续清楚记录当前为了交互性保留 in-process runner 的取舍
• VS Code 体验打磨：Extension Host 端到端测试、首次启动诊断、命令面板 UX
• v1.0 —— 稳定 schema，覆盖更广的 Stata edition

明确不做的范围见 SCHEMA.md §7。

pip install -e ".[dev,mcp,kernel]"
pytest                              # 完整测试集；本机有 Stata 时包含真实 Stata 集成测试
pytest -m "not stata_required"      # CI 子集，不需要 Stata
pytest -m "stata_required" -v       # 仅 Stata 集成测试

stata_required marker 标记真实 Stata 集成测试。CI 使用 pytest -m "not stata_required"，因此不会收集这些测试。本地没有 Stata 时，这些测试也会用 "pystata / Stata 17+ not available" 信息 cleanly skip。

• 提 PR 前请先读 LICENSE-POLICY.md。
• 第一个 PR description 里请加一行 acknowledgement，模板在 policy 文件里。
• 新增 schema field 或 runner 行为时必须补测试。

代码使用 MIT。LICENSE-POLICY.md 说明本项目如何处理和其他 Stata 项目的关系。

Stata 是 StataCorp LLC 的注册商标。本项目是独立项目，不隶属于 StataCorp，也未获得 StataCorp 背书。

本项目参考和学习的 Stata 工具生态整理在 References-tools.md。其中列出的项目保留各自的许可证和作者归属；复用前请查看对应仓库。

访问 copaper.ai

微信公众号：CoPaper.AI

_{由 CoPaper.AI 维护，孵化于 Stanford REAP / SCCEI · 实证研究 AI 助手}