stata-ai-skill

Stata AI Skill

Apple Silicon 搭載の macOS または Windows、ネイティブの stata-ai-skill 実行ファイル、およびローカルにインストールされ、ライセンスが有効な Stata が必要です。Intel Mac は サポートされていません。Stata の自動検出に失敗した場合は、同じ localhost サービスポートで エージェントのガイドに従い、2 段階の aiskill setup フォールバックを使用してください。

このネイティブサービスは ZihaoVistonWang/stata-all-in-one から抽出されたもので、実行時に VS Code を必要とせず、AI Skill の HTTP ワークフローを維持します。

Stata の実行には、ネイティブの localhost サービス http://127.0.0.1:19522 を使用してください。 内部モジュールはインポートしないでください。安定したインターフェースは HTTP です。

実行ファイルの場所

エージェントは PATH やビルド出力を参照する前に、このスキルディレクトリから実行ファイルを解決する 必要があります。ユーザーに 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. Apple Silicon 搭載の macOS：<this-skill-directory>/bin/macos-arm64/stata-ai-skill を使用します。
3. Intel 搭載の macOS（x86_64）：処理を中止し、このスキルは Intel Mac をサポートしていないことをユーザーに伝えます。
4. Apple Silicon 搭載の macOS のフォールバック：<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

エージェントのワークフロー

リセットと再設定

「このスキルを再設定して」「Stata スキルをリセットして」「重新配置该技能」「重置 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 を読み取り、以下の通常のセットアップ手順に従ってください。検出された候補がある場合、候補が1つだけでも、明示的に選択してもらうためにユーザーに提示する必要があります。候補がない場合は、手動の2段階フローに進みます。Stata が使用中のためリセットが HTTP 409 を返した場合は、現在の実行が完了するまで待ってから、1回だけ再試行してください。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

「実行ファイルの場所を特定する」で解決した実行ファイルのパスを使用してください。上記の単独のコマンドは簡略表記にすぎません。エージェントが引き続き 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 を読み取ってください。セットアップの状態と、エージェントに必要な操作は次のとおりです。

setup.phase	エージェントの操作
selection_required	検出された Stata インストールの中から選ぶようユーザーに尋ねてから、/configure を呼び出します
manual_setup_required	直ちにインストールセッションを作成し、生成された installation.do コマンドをユーザーに提示します
awaiting_install_result	ユーザーが最初のコピー済みコマンドを実行するまで待ちます。1分以内の間隔で、2秒ごとに /status をポーリングします
awaiting_aiskill_setup	2つ目のコマンド aiskill setup をユーザーに提示します
configuring	ready または configuration_failed になるまでポーリングを続けます
install_failed	再試行またはスキップを提案します。aiskill setup は提示しないでください
configuration_failed	setup.lastResult とライセンス診断を報告し、再試行を提案します
ready	/execute を呼び出します

自動検出されたインストールを確認する

detectedCandidates は、Stata のバージョンが新しい順、次に MP、SE、BE、IC の順で並んでいます。候補が1つだけでも、黙って選択しないでください。ホストエージェントで利用できる最適な構造化質問ツールを使って、推奨候補、他の候補、手動セットアップの選択肢を提示してください。構造化質問ツールが利用できない場合は、チャットで尋ね、明示的な返答を待ってください。

ユーザーが手動セットアップを選択した場合、その選択を確定したものとして扱ってください。直ちに 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" を含む更新後のステータスが返されます。

手動による 2 段階の 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 ディレクトリを選択します。エージェントとバックグラウンドサービスが ado パスを推測したり、直接書き込んだりしてはいけません。

19522 サービスは awaiting_install_result の状態で稼働を続け、スクリプトの成功または失敗のコールバックを GET /installed で受け取ります。バックグラウンドで JSON /status をポーリングしてください。フェーズが awaiting_aiskill_setup になるまでは、2 つ目のコマンドを送信しないでください。その後、同じく別途開いた GUI Stata で次を実行するようユーザーに依頼します。

aiskill setup

/execute 経由で aiskill setup を実行してはいけません。このコマンドは GET /status?format=stata から一度だけ使用できるトークンを取得し、GUI Stata のプラットフォーム、バージョン、エディション、マシンタイプ、および c(sysdir_stata) を GET /setup に報告して、すぐに戻ります。ready または configuration_failed になるまで、JSON /status のポーリングを続けてください。

セットアップ／インストールのトークンは一度だけ使用でき、有効期限は 10 分です。通常の JSON /status のポーリングによって、Stata セットアップトークンが更新または無効化されることはありません。

4. /status が sessionActive: true および setup.phase: "ready" を返した場合は、/execute を呼び出してください。

/status には、エージェントがトラブルシューティングに使用すべき診断フィールドが含まれます。

• 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 やシェルコマンドで読み取ったり、内容を 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 について詳しくは、アクティブなシェルが 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 を呼び出してサービスを再起動してください。

グラフのエクスポート

スタンドアロンサービスでは、セッション初期化後に quietly _gr_list on を実行して、Stata のグラフキャプチャを有効にします。元の位置にある 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 エクスポート動作が維持され、生成された SVG のパスが graphs に返されます。

Lianxh の検索

ユーザーが Stata の料理本の例、コマンドのチュートリアル、または Lianxh の記事を求めた場合は、 references/lianxh-search.md を読み、その指示に従ってください。ここには、インストールへの同意の境界、3 件のクエリ上限、検索構文、タイムアウトからの復旧ワークフローが記載されています。

中断とシャットダウン

現在の 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 から変換されます。