Stata-MCP

# Stata Do 文件执行器

## 概述

StataDo 是 Stata-MCP 中负责执行 Stata do 文件的核心模块。它提供了一种安全可靠的方式来运行 Stata 脚本，具有自动结果日志记录功能，支持三大操作系统：macOS、Linux 和 Windows。

## 关键功能

### 跨平台支持

StataDo 自动适应不同的操作系统：

- **类 Unix 系统（macOS/Linux）**：通过标准输入流与 Stata 交互以实现高效命令执行
- **Windows 系统**：使用批处理文件方法执行 Stata 命令，确保兼容性

### 自动日志记录

每次执行 do 文件时，StataDo 自动：

1. 创建新的日志文件或在指定路径创建日志
2. 记录完整的 Stata 执行过程和输出结果
3. 将日志文件保存在 `stata-mcp-log` 目录中，便于审查和分析

### 安全保障

StataDo 包含内置的安全检查机制：

- **命令过滤**：阻止可能危及系统安全的 shell 转义命令（如 `!cmd` 或 `shell cmd`）
- **内容验证**：在执行前检查 do 文件内容，防止恶意命令执行

### 智能终端仿真

StataDo 模拟标准终端环境以确保 Stata 输出一致且可读：

- 设置固定的终端尺寸（120 列 × 40 行）
- 确保跨平台输出一致性

## 工作流程

1. **准备阶段**：接受 do 文件路径和日志文件路径参数
2. **安全检查**：验证 do 文件内容，确保没有危险命令
3. **环境适配**：根据操作系统类型选择适当的执行方法
4. **脚本执行**：调用 Stata CLI 执行 do 文件
5. **结果日志**：将执行过程和结果写入日志文件
6. **清理**：删除临时文件（Windows 平台）

## 使用场景

StataDo 主要用于以下场景：

- **批量数据处理**：执行包含数据清洗、转换等操作的 do 文件
- **统计分析**：运行回归分析、描述性统计等 Stata 命令
- **图表生成**：执行生成统计图表的 Stata 脚本
- **自动化研究工作流程**：在 AI Agent 或自动化脚本中调用 Stata 进行数据分析

## 与其他模块的集成

StataDo 是 Stata-MCP 工具链的重要组成部分：

- **StataFinder**：提供 Stata 可执行文件路径
- **StataController**：提供更高级别的 Stata 控制接口
- **日志系统**：自动在指定日志目录中记录执行结果

## 文件路径约定

StataDo 遵循 Stata-MCP 目录结构约定：

- **Do 文件目录**：`~/Documents/stata-mcp-folder/stata-mcp-dofile/`
- **日志文件目录**：`~/Documents/stata-mcp-folder/stata-mcp-log/`

## 注意事项

1. **文件编码**：StataDo 使用 UTF-8 编码读取 do 文件；请确保您的 do 文件使用 UTF-8 编码保存
2. **路径处理**：在 Windows 系统上，自动处理路径中的空格
3. **日志覆盖**：默认情况下，现有日志文件将被覆盖；此行为可通过参数控制
4. **错误处理**：执行失败时抛出异常；调用者应正确处理这些异常