Stata-sep（基于 Stata-MCP）

核心思路

• 目标：在 Claude Code 等 MCP 客户端中，把 Stata-MCP 的全部工具（工具列表见下文）和 agent/评估用法包装成可复用流程，减少提示词负担。
• 输出优先级：先给高层决策与最小可运行路径，再按需展开到具体工具调用/样例（渐进披露）。
• 安全默认：仅使用绝对路径；写/改文件或运行 do 前明确路径；安装 ado 包需用户确认。

快速起步（最小可用链路）

1. 环境探测：uvx stata-mcp --usable；若 stata_cli 失败，设置环境变量 stata_cli 为 Stata 可执行绝对路径（macOS 如 /Applications/Stata/StataMP.app/Contents/MacOS/stata-mp，Windows 如 C:\\Program Files\\Stata18\\StataSE.exe）。可选 documents_path。
2. 将 MCP server 加入客户端（示例 config JSON 已放 references/usage.md）。默认工作根：~/Documents/stata-mcp-folder/，自动包含 stata-mcp-log/、stata-mcp-dofile/、stata-mcp-result/、stata-mcp-tmp/。
3. 最小流水线：
   • write_dofile 写入完整 do，必要时先调用 results_doc_path 生成输出目录。
   • stata_do 运行 do，返回日志路径与内容。
   • read_file 查看日志或结果。
   • 若需数据概览，先用 get_data_info（支持 .dta/.csv）。

工具地图（全量覆盖）

• help(cmd)（Unix only）：返回 Stata help。用于快速查语法。
• write_dofile(content, encoding?, strict_mode?)：把 Stata 代码写入新 do，返回绝对路径。建议在顶部 use 数据并设置 local output_path（来自 results_doc_path）。
• append_dofile(original_dofile_path, content, encoding?)：在现有 do 基础上追加，或新建副本；返回新 do 路径。
• stata_do(dofile_path, log_file_name?, is_read_log=True)：执行 do，返回 log_file_path 和可选 log_content。
• read_file(file_path, encoding="utf-8")：读取任意文本文件内容。
• get_data_info(data_path, vars_list?, encoding="utf-8")：对 .dta/.csv 生成描述性统计，结果写入 tmp 目录并返回概要。
• ado_package_install(package, source="ssc"|"github"|"net", is_replace=True, package_source_from=None)（Unix only）：安装 ado；首次使用需确认。
• load_figure(figure_path)：载入 png/jpg，便于回显图形。
• mk_dir(path)：安全创建目录。
• Prompts：stata_assistant_role(lang?)、stata_analysis_strategy(lang?)、results_doc_path() 生成输出目录。

推荐工作流（逐层展开）

1. 数据理解：get_data_info → 选择变量/样本 → 形成 do 草稿。
2. do 生成：
   • 快速试验用 write_dofile；增量修改用 append_dofile。
   • 需要表格输出时先 results_doc_path，在 do 里 local output_path "<返回路径>"，配合 outreg2/esttab。
3. 执行与回溯：stata_do → 如失败查看 log_content 或用 read_file 重读；必要时追加 do 并重跑。
4. 包依赖：缺少命令时，用 ado_package_install(" ,") 安装；完成后复跑。
5. 产出：用 load_figure 回显图形，用 read_file 回显表格/日志。

Agent 模式与评估

• Agent：uvx stata-mcp --agent 或直接 stata-mcp --agent，修改示例任务位于 stata-mcp/source/agent_examples/openai/main.py（model_instructions 与 task_message）。
• 作为工具：StataAgent.as_tool() 示例见 source/docs/Usages/agent_as/agent_as_tool.md。
• 评估：流程与样例问答在 source/docs/Usages/Evaluation.md；可据此自定义评测集合。

参考资料（按需加载）

• references/usage.md：客户端配置、环境变量、最小命令速查。绝对路径：/Users/lingguiwang/Skill-Seekers/Github/stata-sep/references/usage.md。
• references/tools.md：各工具参数与返回字段、常见坑。绝对路径：/Users/lingguiwang/Skill-Seekers/Github/stata-sep/references/tools.md。
• references/usage_full.md：官方 Usage 详版（中英混排）。
• references/advanced.md：高级用法（传输方式、定制路径等）。
• references/questions.md：常见问题汇总。
• references/evaluation.md：评估流程与示例问答生成方法。
• references/agent_as_tool.md：将 Stata-Agent 作为工具嵌入其他 agent 的示例。
• assets/config.json：最小配置模板，可直接拷贝调整绝对路径与环境变量。
• assets/agent_examples/：可直接复制的 agent 示例代码（OpenAI/prompt 生成）。

注意事项

• 所有路径使用绝对路径；Windows 需转义反斜杠。
• 运行/写入前确认目标目录，避免覆盖用户文件。
• 安装 ado、创建目录等潜在改动操作需先向用户确认。