OpenMath CLI

当前版本已实现：

• CLI 多会话
• 可配置 OpenAI 兼容 API
• Python + Markdown 工具
• Mathematica MCP 工具接入
• Tavily 实时互联网搜索工具

1. 环境准备

• Node.js 18+
• npm 9+
• Python 3.x（用于 run_python_script 工具）
• mma-mcp

2. .env 配置

2.1 快速创建

在项目根目录执行：

cp .env.example .env

Windows PowerShell 可用：

Copy-Item .env.example .env

然后编辑 .env，至少填好 OPENMATH_API_KEY 和 OPENMATH_MMA_MCP_PROJECT_DIR

2.2 推荐配置示例

OPENMATH_PROVIDER=openai-compatible
OPENMATH_BASE_URL=https://api.deepseek.com
OPENMATH_MODEL=deepseek-v4-flash
OPENMATH_API_KEY=your_api_key_here

OPENMATH_TIMEOUT_MS=60000
OPENMATH_MAX_CONTEXT_LENGTH=1048576
OPENMATH_MAX_RETRIES=2
OPENMATH_RETRY_BASE_DELAY_MS=800
OPENMATH_RPM_LIMIT=30

OPENMATH_PYTHON_BIN=python
OPENMATH_PYTHON_TIMEOUT_SEC=30
OPENMATH_PYTHON_MAX_OUTPUT_CHARS=12000

OPENMATH_MMA_MCP_ENABLED=enabled
OPENMATH_MMA_MCP_TRANSPORT=http
OPENMATH_MMA_MCP_COMMAND=uv
OPENMATH_MMA_MCP_PROJECT_DIR=/path/to/mma-mcp
OPENMATH_MMA_MCP_EXTRA_ARGS=
OPENMATH_MMA_MCP_HTTP_HOST=127.0.0.1
OPENMATH_MMA_MCP_HTTP_PORT=18080
OPENMATH_MMA_MCP_TIMEOUT_SEC=45
OPENMATH_MMA_MCP_TOOL_CACHE_TTL_SEC=30
OPENMATH_MMA_MCP_MAX_TEXT_CHARS=12000

OPENMATH_OPEN_URL=enabled
OPENMATH_OPEN_URL_TIMEOUT_SEC=10
OPENMATH_OPEN_URL_MAX_CHARS=12000

OPENMATH_TAVILY_SEARCH_ENABLED=disabled
OPENMATH_TAVILY_API_KEY=
OPENMATH_TAVILY_TIMEOUT_SEC=10
OPENMATH_TAVILY_MAX_RESULTS=5

OPENMATH_FILE_WHITELIST=answers

2.3 配置项说明

• OPENMATH_PROVIDER：模型提供方标识（openai-compatible/anthropic/google，当前 anthropic 会被映射到 openai-compatible）。
• OPENMATH_BASE_URL：兼容 OpenAI Chat Completions 的服务地址。
• OPENMATH_MODEL：默认模型名。
• OPENMATH_API_KEY：API 密钥（必填）。
• OPENMATH_TIMEOUT_MS：单次请求超时（毫秒）。
• OPENMATH_MAX_CONTEXT_LENGTH：最大上下文长度（token）。用于显示 context: <usage>/<max_length> 并在超过 75% 时触发压缩。
• OPENMATH_MAX_RETRIES：请求失败重试次数。
• OPENMATH_RETRY_BASE_DELAY_MS：重试基础退避时长（毫秒）。
• OPENMATH_RPM_LIMIT：每分钟请求数上限。
• OPENMATH_PYTHON_BIN：Python 可执行命令（如 python 或 py）。
• OPENMATH_PYTHON_TIMEOUT_SEC：Python 工具执行超时（秒）。
• OPENMATH_PYTHON_MAX_OUTPUT_CHARS：Python 输出最大字符数。
• OPENMATH_MMA_MCP_ENABLED：是否启用 Mathematica MCP 工具（enabled/disabled）。
• OPENMATH_MMA_MCP_TRANSPORT：MCP 传输模式（stdio/http，Windows 建议 http）。
• OPENMATH_MMA_MCP_COMMAND：启动 mma-mcp 的命令（默认 uv）。
• OPENMATH_MMA_MCP_PROJECT_DIR：mma-mcp 项目目录（用于 uv --directory）。
• OPENMATH_MMA_MCP_EXTRA_ARGS：附加启动参数（逗号分隔）。
• OPENMATH_MMA_MCP_HTTP_HOST：HTTP 传输模式的绑定地址。
• OPENMATH_MMA_MCP_HTTP_PORT：HTTP 传输模式的端口。
• OPENMATH_MMA_MCP_TIMEOUT_SEC：MCP 请求超时（秒）。
• OPENMATH_MMA_MCP_TOOL_CACHE_TTL_SEC：远端工具列表缓存时长（秒）。
• OPENMATH_MMA_MCP_MAX_TEXT_CHARS：Mathematica 文本结果截断上限。
• OPENMATH_OPEN_URL：是否启用打开 URL 工具（enabled/disabled）。
• OPENMATH_OPEN_URL_TIMEOUT_SEC： 打开 URL 请求超时（秒）。
• OPENMATH_OPEN_URL_MAX_CHARS：打开 URL 结果截断上限。
• OPENMATH_TAVILY_SEARCH_ENABLED：是否启用 Tavily 搜索工具（enabled/disabled）。
• OPENMATH_TAVILY_API_KEY：Tavily API 密钥。
• OPENMATH_TAVILY_TIMEOUT_SEC：Tavily 搜索请求超时（秒）。
• OPENMATH_TAVILY_MAX_RESULTS：Tavily 搜索默认返回结果条数。
• OPENMATH_FILE_WHITELIST：文件工具可写路径白名单（逗号分隔）。
• OPENMATH_THINKING_ENABLED：推理偏好开关（enabled/disabled，默认 enabled）。
  • DeepSeek 模式：映射为 thinking 的 enabled/disabled。
  • GPT 等模式：无 thinking 开关，disabled 时会自动把 reasoning_effort 降为 low。
• OPENMATH_REASONING_EFFORT：推理强度（minimal/low/medium/high/max/xhigh，默认 high）。模型可用的推理强度一般只有其中一部分，请查询 API 文档。

3. 安装与启动

npm install
npm run start

开发模式：

npm run dev

构建检查：

npm run build

如果你想要在仓库路径之外使用 openmath，可以作为系统命令安装：

npm link

4. CLI 使用方法

启动后输入自然语言可直接提问，用 Alt+Enter 换行，Enter 发送。输入斜杠命令可管理会话。

常用命令：

• /new [title]：新建并切换会话
• /list：查看会话列表
• /switch ：切换会话
• /history [limit]：查看最近消息
• /help：查看命令帮助
• /exit：退出

示例：

/new calculus-homework
解答 problems/1-1.md 中的问题
把答案放在 answers 下

5. 常见问题

5.1 启动时报 OPENMATH_API_KEY is required

说明 .env 未创建或未填写 OPENMATH_API_KEY。请先按第 2 节完成配置。

5.2 Python 工具执行失败

检查：

• OPENMATH_PYTHON_BIN 是否正确（可尝试 python 或 py）
• 本机是否能在终端直接运行对应 Python 命令

5.3 文件写入被拒绝

目标路径必须在 OPENMATH_FILE_WHITELIST 白名单中。

5.4 网络问题

如果你需要使用代理，请配置好环境变量 HTTP_PROXY=your_http_proxy, HTTPS_PROXY=your_https_proxy 以及 NODE_USE_ENV_PROXY=1。