# Stata Help

> **仅限 macOS 和 Linux！**

此模块目前仅支持 macOS 和 Linux 系统。暂不支持 Windows。

## 概述

StataHelp 是一个实用模块，直接从您本地 Stata 安装中检索 Stata 命令的帮助文档。它提供对 Stata 内置帮助系统的快速访问，并具有智能缓存以提高性能。

## 关键功能

### 本地帮助访问

StataHelp 查询您机器上安装的 Stata 帮助系统：

- **无需互联网**：所有帮助文档来自您本地的 Stata 安装
- **快速访问**：通过 Stata CLI 即时检索帮助信息
- **完整文档**：访问 Stata 中可用的全面帮助内容

### 智能缓存系统

StataHelp 包含多级缓存机制以提高性能：

- **项目级缓存**：将帮助结果保存到项目的临时目录以便快速访问
- **全局缓存**：将帮助文件存储在 `~/.stata_mcp/help/` 中以便跨项目重用
- **环境控制**：使用 `STATA_MCP__CACHE_HELP` 和 `STATA_MCP__SAVE_HELP` 控制缓存行为

### 命令验证

在执行 Stata 命令之前，您可以使用 StataHelp 验证命令是否存在：

- 检查给定命令的帮助文档是否可用
- 帮助防止因拼写错误或缺失包导致的错误
- 对在自动化工作流程中验证用户输入很有用

## 使用场景

- **命令验证**：在执行前检查 Stata 命令是否存在
- **文档查询**：以编程方式检索 Stata 命令的帮助文本
- **交互式辅助**：在 AI 驱动的 Stata 工作流程中提供上下文帮助
- **错误预防**：在脚本中运行命令之前验证命令

## 工作原理

1. **缓存检查**：首先检查项目级缓存，然后检查全局缓存（如果启用）
2. **Stata 查询**：如果未缓存，向 Stata CLI 发送 `help {command}` 请求
3. **文档检索**：Stata 在其本地文档中搜索指定命令
4. **缓存存储**：将结果保存到缓存（如果启用）
5. **结果返回**：返回帮助文本以供显示或处理

## 配置

使用环境变量控制缓存行为：

```bash
# 启用全局缓存（默认：true）
export STATA_MCP__CACHE_HELP=true

# 启用项目级保存（默认：true）
export STATA_MCP__SAVE_HELP=true
```

## 限制

- **平台支持**：目前仅在 macOS 和 Linux 上工作
- **仅本地文档**：无法访问本地未安装的包的帮助
- **无互联网搜索**：不执行缺失命令的在线搜索

## 文件位置

- **全局缓存目录**：`~/.stata_mcp/help/`
- **项目缓存目录**：`{project_tmp_dir}/`（通常在 `stata-mcp-tmp/` 中）
