stata-ai-skill

Stata AI Skill

需要 Apple Silicon macOS 或 Windows、原生 stata-ai-skill 可执行文件，以及本地安装并获得许可的 Stata。不支持 Intel Mac。如果自动发现 Stata 失败，请使用 Agent 引导的两阶段 aiskill setup 回退流程，并使用相同的 localhost 服务端口。

此原生服务提取自 ZihaoVistonWang/stata-all-in-one， 保留了 AI Skill HTTP 工作流，运行时无需 VS Code。

使用原生 localhost 服务 http://127.0.0.1:19522 运行 Stata。 不要导入内部模块。稳定接口为 HTTP。

定位可执行文件

使用 PATH 或构建输出之前，Agent 必须先从此 Skill 目录解析可执行文件。 不要要求用户知道 Cargo 的 target/release 目录。

预期的打包布局：

stata-ai-skill/
  SKILL.md
  bin/
    macos/
      stata-ai-skill            (legacy fallback)
    macos-arm64/
      stata-ai-skill            (Apple Silicon)
    windows/
      stata-ai-skill.exe          (x64)
    windows-arm64/
      stata-ai-skill.exe          (ARM64)
  scripts/
    discover_stata_windows.bat
  stata/
    aiskill/
      aiskill.ado
      aiskill.sthlp
      aiskill.pkg
      stata.toc

解析顺序：

1. 如果设置了 STATA_AI_SKILL_BIN，则使用该确切可执行文件路径。
2. macOS Apple Silicon：使用 <this-skill-directory>/bin/macos-arm64/stata-ai-skill。
3. macOS Intel（x86_64）：停止并告知用户此 Skill 不支持 Intel Mac。
4. macOS Apple Silicon 回退路径：使用 <this-skill-directory>/bin/macos/stata-ai-skill。
5. Windows x64：使用 <this-skill-directory>\bin\windows\stata-ai-skill.exe。
6. Windows ARM64：使用 <this-skill-directory>\bin\windows-arm64\stata-ai-skill.exe。
7. 仅当受支持平台上的打包二进制文件缺失时，才回退使用 PATH 中的 stata-ai-skill。

检测 macOS 架构：

case "$(uname -m)" in
  arm64) exe="./bin/macos-arm64/stata-ai-skill" ;;
  x86_64)
    echo "Stata AI Skill does not support Intel Mac."
    exit 1
    ;;
  *) exe="./bin/macos/stata-ai-skill" ;;
esac

通过 PowerShell 检测 Windows 架构：

if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
    $exe = ".\bin\windows-arm64\stata-ai-skill.exe"
} else {
    $exe = ".\bin\windows\stata-ai-skill.exe"
}

对于开发构建，使用以下命令刷新打包的可执行文件：

cargo run -p xtask -- dist

执行下方命令时，将 stata-ai-skill 替换为解析出的 可执行文件路径。示例：

# macOS, from the skill directory
./bin/macos-arm64/stata-ai-skill serve

# Windows, from the skill directory
.\bin\windows\stata-ai-skill.exe serve

Agent 工作流

重置并重新配置

将“重新配置此 Skill”“重置 Stata Skill”“重新配置该技能”“重置 Stata 配置”“换一个 Stata”或“重新开始设置”等请求视为明确要求删除已持久化的 Stata AI Skill 配置并重新运行设置。该请求本身即授权执行重置；无需再次确认。

如果服务在线，请原地重置：

curl -s -X POST http://127.0.0.1:19522/configure/reset

此操作会移除已持久化的配置文件，并返回 restartRequired: true。 等待服务停止，然后使用解析后的可执行文件重启，且不要带上 --stata-path 参数。安全地停止进程会关闭嵌入式 Stata 会话，并清除安装/设置令牌和阶段状态。此操作不会卸载 Stata、删除 ado 包或更改 Stata 许可证。

如果服务离线，请使用解析后的可执行文件，然后启动服务：

stata-ai-skill config reset
stata-ai-skill serve

重启后，读取 /status 并按照下方的常规设置流程操作。即使只有一个检测到的候选项，也必须向用户展示并要求明确选择；如果没有候选项，则进入手动两阶段流程。如果 Stata 正忙导致重置返回 HTTP 409，请等待当前执行完成后重试一次。不要用 aiskill setup, force 代替，因为它会保留旧的已持久化选择。

1. 检查服务是否正在运行：

curl -s --connect-timeout 2 http://127.0.0.1:19522/status 2>/dev/null || echo "OFFLINE"

2. 如果服务离线，启动原生可执行文件：

stata-ai-skill serve

使用“定位可执行文件”中解析出的可执行文件路径；上方的裸命令仅为简写。将服务作为长期运行的后台进程启动，以便 Agent 继续发送 HTTP 请求。在 macOS/zsh 上：

nohup ./bin/macos-arm64/stata-ai-skill serve > /tmp/stata-ai-skill.log 2>&1 &

如果启动失败且端口已被占用，请先重新检查 /status。 如果已有另一个 Stata AI Skill 服务正在响应，请复用该服务。否则选择另一个端口并持久化：

./bin/macos-arm64/stata-ai-skill config set --port 19523
nohup ./bin/macos-arm64/stata-ai-skill serve > /tmp/stata-ai-skill.log 2>&1 &
curl -s http://127.0.0.1:19523/status

3. 尝试执行前，先读取 setup.phase。设置状态及 Agent 必须执行的操作如下：

setup.phase	Agent 操作
selection_required	请用户选择一个检测到的 Stata 安装，然后调用 /configure
manual_setup_required	立即创建安装会话，并向用户提供生成的 installation.do 命令
awaiting_install_result	等待用户运行复制的第一条命令；每两秒轮询一次 /status，每次轮询时段不超过一分钟
awaiting_aiskill_setup	向用户提供第二条命令 aiskill setup
configuring	继续轮询，直到状态变为 ready 或 configuration_failed
install_failed	提供重试或跳过选项；不要显示 aiskill setup
configuration_failed	报告 setup.lastResult、许可证诊断信息，并提供重试选项
ready	调用 /execute

确认自动检测到的安装

detectedCandidates 按 Stata 版本从新到旧排序，其次依次为 MP、SE、BE 和 IC。即使只有一个候选项，也不要默默选择。使用宿主 Agent 最合适的结构化提问工具，向用户展示推荐候选项、其他候选项以及手动设置选项。如果没有可用的结构化提问工具，请在聊天中提问并等待用户明确回复。

如果用户选择手动设置，请将该选择视为完整决定：立即调用 POST /setup/install-session，并展示其返回的命令。不要再询问是否安装 aiskill。

用户确认后，通过已经运行的服务进行配置和初始化；无需重启：

curl -s -X POST http://127.0.0.1:19522/configure \
  -H "Content-Type: application/json" \
  -d '{"stataPath":"/Applications/StataNow/StataMP.app"}'

请原样使用所选候选项的 path。成功响应会返回更新后的状态，其中 sessionActive: true，且 setup.phase: "ready"。

手动分两阶段执行 aiskill setup

当自动发现未找到候选项，或用户明确选择手动设置时，请使用此流程。该选择已启动手动工作流；无需再次请求安装确认。立即创建安装会话：

curl -s -X POST http://127.0.0.1:19522/setup/install-session

原样复制或显示返回的 command。其中包含生成脚本的绝对路径，例如：

do "D:/path/to/the/system/temp/directory/installation.do"

告诉用户在他们希望 Skill 使用的特定 GUI Stata 安装中运行此命令。该命令会在此 Stata 进程内运行 net install，因此由 Stata 自行为该用户选择正确的 PERSONAL/PLUS ado 目录；Agent 和后台服务不得猜测或直接写入 ado 路径。

19522 服务会在 awaiting_install_result 状态下保持运行，并通过 GET /installed 接收脚本的成功或失败回调。在后台轮询 JSON /status；只有当阶段变为 awaiting_aiskill_setup 后，才发送第二条命令。然后请用户在同一个单独打开的 GUI Stata 中运行以下命令：

aiskill setup

切勿通过 /execute 运行 aiskill setup。它会从 GET /status?format=stata 获取一次性令牌，将 GUI Stata 的平台、版本、版本类型、机器类型和 c(sysdir_stata) 报告给 GET /setup，然后立即返回。继续轮询 JSON /status，直到状态变为 ready 或 configuration_failed。

设置／安装令牌只能使用一次，并会在十分钟后过期。普通的 JSON /status 轮询不会轮换或使 Stata 设置令牌失效。

4. 如果 /status 返回 sessionActive: true 和 setup.phase: "ready"，请调用 /execute。

/status 包含 Agent 应用于故障排查的诊断字段：

• config.port
• config.stataPath
• config.configFile
• config.logDir
• config.tempDir
• config.graphDir
• capabilities.cwd
• capabilities.timeoutMaxSeconds

如果 /status 返回 needsLicense: true 或 missing: "stata_license"，说明已找到 Stata，但未找到许可证文件。请告知用户：

“Stata 已安装，但服务无法找到 Stata 许可证文件 stata.lic / STATA.lic。请打开 Stata 一次以确认其已获得许可，或检查 Stata 安装文件夹中是否存在许可证文件。”

常见的许可证文件位置：

• macOS：/Applications/StataNow/stata.lic
• Windows：C:\Program Files\Stata18\STATA.lic

执行

先阅读命令帮助

使用特定 Stata 命令前，先通过 /execute 运行 help <command> 并阅读其文档。在编写最终分析命令前，确认命令语法、选项和特定版本的行为。例如，使用 regress 前先运行 help regress。

如果 Stata 报告帮助文件或命令不可用，请勿猜测其语法。报告缺少的命令，并在安装任何社区贡献的程序包前请求批准。

直接运行现有 Do 文件

用户提供现有 .do 文件时，请在 file 字段中传入其路径。优先采用此方式，而不是复制文件、使用 Python 或 shell 命令读取文件，或通过 code 发送文件内容。

• 现有 .do 文件使用 file，内联 Stata 命令使用 code。
• 尽可能使用绝对 file 路径。支持包含空格的路径；按常规对路径进行 JSON 编码，不要将其复制到 /tmp。
• 如果 do 文件使用相对路径引用数据集、包含的 do 文件、日志或生成的输出，请将 cwd 设为 do 文件所在的项目目录。
• 本地 Stata AI Skill 服务进程必须能够访问该文件。
• 不要同时传入 file 和 code；如果两者都存在，则以 file 为准。

macOS 和 Linux

在 bash 或 zsh 中使用 curl：

curl -s -X POST http://127.0.0.1:19522/execute \
  -H "Content-Type: application/json" \
  -d '{"file":"/Users/me/project/analysis.do","cwd":"/Users/me/project","timeout":120}'

Windows 命令提示符

Windows 同时支持命令提示符（cmd.exe）和 PowerShell；不要求使用 PowerShell。在命令提示符中，对 JSON 双引号进行转义：

curl.exe -s -X POST http://127.0.0.1:19522/execute -H "Content-Type: application/json" -d "{\"file\":\"C:\\Users\\me\\project\\analysis.do\",\"cwd\":\"C:\\Users\\me\\project\",\"timeout\":120}"

Windows PowerShell

将请求 JSON（而不是 do 文件）写入不带 BOM 的临时 UTF-8 文件，然后使用 curl.exe 发送：

$body = '{"file":"C:\\Users\\me\\project\\analysis.do","cwd":"C:\\Users\\me\\project","timeout":120}'
[System.IO.File]::WriteAllText("$env:TEMP\stata_body.json", $body, [System.Text.UTF8Encoding]::new($false))
curl.exe -s -X POST http://127.0.0.1:19522/execute `
  -H "Content-Type: application/json" `
  --data-binary "@$env:TEMP\stata_body.json"

在这三种情况下，服务都会直接执行 do 文件，并在 do 命令之前应用 cwd。

有关 PowerShell 引号、UTF-8 BOM 和多行 JSON 的更多说明，请在当前 shell 为 Windows PowerShell 时阅读 references/windows-powershell-http.md。

响应：

{
  "success": true,
  "returnCode": 0,
  "output": "4",
  "error": "",
  "graphs": []
}

对于较长的命令，请以秒为单位设置 timeout：

curl -s -X POST http://127.0.0.1:19522/execute \
  -H "Content-Type: application/json" \
  -d '{"code":"bootstrap r(mean), reps(1000): summarize price", "timeout": 300}'

对于使用相对路径的工作流，请设置 cwd。服务会在运行内联代码或 do 文件之前添加 Stata cd 命令：

curl -s -X POST http://127.0.0.1:19522/execute \
  -H "Content-Type: application/json" \
  -d '{"cwd":"/Users/me/project","code":"use data/auto.dta, clear\nsummarize"}'

超时恢复

超时会返回 HTTP 408 并发送 Stata 中断信号。如果响应显示 Stata is still stopping，则 /status.busy 会有意保持为 true；在其变为 false 之前，请勿 再次发送执行请求。如有需要，可再次发送 /break；如果 Stata 始终无法停止，则调用 /shutdown 并重启服务。

图形导出

独立服务会在会话初始化后启用 Stata 图形捕获，执行 quietly _gr_list on。它会在原始位置识别 graph export，包括前导的 . 以及 quietly/qui、capture/cap 和 noisily/noi 前缀。它会保留 replace 和 name(...)；位图的 width(...) 和 height(...) 用于控制 Rust 渲染的输出尺寸。

显式 SVG 导出会安全执行，并在响应的 graphs 数组中返回：

[{ "name": "Graph", "svg": "/absolute/path/to/foo.svg", "png": null }]

支持 PNG/JPG/JPEG 导出，无需让 Stata 直接写入这些格式。在用户代码的同一位置，服务会先导出 SVG， 再使用捆绑的 Rust 库进行转换，保留 SVG 路径，并写入请求的位图路径。对于 PNG 请求，png 字段包含 生成的 PNG 路径。对于 JPG/JPEG 请求，png 保持为 null，图形对象则包含生成位图的 file 和 format 字段。TIF 和 TIFF 等其他不安全的位图格式仍会被改写为 SVG，并在 output 中报告。

如果用户代码中没有显式的 graph export，执行成功后仍会采用自动的 _gr_list SVG 导出行为，并在 graphs 下返回生成的 SVG 路径。

Lianxh 搜索

当用户询问 Stata 示例、命令教程或 Lianxh 文章时，请阅读并遵循 references/lianxh-search.md。其中包含安装许可边界、三次查询限制、搜索语法和超时恢复工作流。

中断与关闭

中断当前 Stata 执行：

curl -s -X POST http://127.0.0.1:19522/break

关闭后台服务：

curl -s -X POST http://127.0.0.1:19522/shutdown

文件

服务仅使用系统目录。它不会在当前仓库或工作目录中创建 .stata-all-in-one/。临时 .do 文件均为唯一文件， 并会在执行后删除。图形会先导出为 SVG，并以绝对路径的形式在 graphs 中返回；显式请求 PNG/JPG/JPEG 时， 会从该 SVG 转换，无需系统图像转换器。