PRESTO-mcp-server

# presto-mcp 一款类型化的、沙盒化的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，允许 LLMs 在 Docker 中运行真正的 **PRESTO**（脉冲星/射电天文学）工具。每次运行都是隔离的（`--network none`，只读数据挂载，CPU/内存上限），记录到 `runs/<run_id>/`，并作为 MCP 资源暴露。 > **仅限 PRESTO** — 不适用于 PrestoDB、Apache Pulsar、PulsarX、TransientX、riptide、Heimdall 或 PULSAR_MINER。 --- ## 安装（规范） 一种一致的安装、配置和连接客户端的方式。设计用于上线和本地生产使用。 ### 决策（不可协商） | # | 决策 | 原因 | |---|----------|--------| | 1 | **所有配置存放在 `<repo>/.env`**（从 `.env.example` 复制） | 唯一的真实来源；不要在 Cursor/Claude JSON 中重复 `PRESTO_*` | | 2 | **单一启动命令** | `uv run --directory <REPO> python -m presto_mcp.server` | | 3 | **始终使用 `--directory <REPO>`** | MCP 客户端不依赖于 `cwd`；它从克隆中加载包和 `.env` | | 4 | **默认数据位置为 `./data`** | 如果数据在其他地方，只需在 `.env` 中更改 `PRESTO_DATA_DIR` | | 5 | **客户端 JSON = 仓库路径仅** | 替换 `REPLACE_WITH_REPO_ROOT`；无需 `"env"` 块 | | 6 | **客户端启动服务器** | 您无需在终端中保持 `uv run ...` 打开即可日常使用 | ### 1. 要求 - Python 3.11+，[uv](https://docs.astral.sh/uv/)，Docker 运行中 - 镜像： 在 `.env` 中设置 `PRESTO_IMAGE`（默认为 `alex88ridolfi/presto5:png`）。启动时，服务器可以自动拉取如果缺失（`PRESTO_PULL_IMAGE_ON_START=true`）。 ### 2. 克隆和安装 ```bash git clone <your-fork-or-repo-url> cd MCP-Server-Presto uv sync --extra dev # 可选，如果 PRESTO_PULL_IMAGE_ON_START=true（默认） docker pull alex88ridolfi/presto5:png ``` ### 3. 配置（仅 `.env`） ```bash cp .env.example .env # Windows: copy .env.example .env ``` 如有需要，编辑 `.env`： - **`PRESTO_DATA_DIR`** — 默认为 `./data`（仓库内的 `.fil` / `.fits` 文件）。 - 如果您的观测数据在仓库**外部**，请在此设置绝对路径（通常是您需要的唯一额外路径）。 所有其他内容（`runs/`、CPU、内存、Docker 镜像）都可以保持默认值。 将观测文件放在 `data/`（或您在 `PRESTO_DATA_DIR` 中设置的目录）中。 **Windows + OneDrive：** 右键单击数据文件夹 -> *始终在此设备上保持*（0 字节占位符会导致健康检查失败）。 #### 所有 `.env` 变量（包括高级） `.env.example` 故意保持最小，以满足日常使用。 如果您需要更深入的控制，可以将以下任何变量添加到 `.env` 中： | 变量 | 默认值 | 何时更改 | |---|---|---| | `PRESTO_IMAGE` | `alex88ridolfi/presto5:png` | 使用不同的 PRESTO 运行时镜像/标签。 | | `PRESTO_DATA_DIR` | `./data` | 您的观测文件存放在仓库外部。 | | `PRESTO_RUNS_DIR` | `./runs` | 将清单保存在数据附近或另一个磁盘上。 | | `PRESTO_OUTPUTS_DIR` | `./outputs` | 现代报告包（`outputs/<run_id>/`）。 | | `PRESTO_TOOL_PROFILE` | `all` | 仅公开工具的子集（`core`、`periodic`等）。 | | `PRESTO_AUTO_START_DOCKER` | Windows/macOS：`true`；Linux：`false` | 启用/禁用 Docker Desktop 自动启动行为。 | | `PRESTO_AUTO_START_DOCKER_TIMEOUT_SECONDS` | `120` | 给 Docker 更多时间以使其可用。 | | `PRESTO_AUTO_START_DOCKER_STARTUP_WAIT_SECONDS` | `45` | 标准客户端在重试连接之前等待启动的时间上限。 | | `PRESTO_PULL_IMAGE_ON_START` | `true` | 如果本地缺少 `PRESTO_IMAGE`，则在启动时运行 `docker pull`。 | | `PRESTO_PULL_IMAGE_TIMEOUT_SECONDS` | `900` | 启动期间等待 `docker pull` 的最大时间。 | | `PRESTO_DEFAULT_CPUS` | `4` | 增加/减少每个 PRESTO 调用 的 CPU。 | | `PRESTO_DEFAULT_MEMORY_MB` | `8192` | 为大作业增加内存或在小主机上减少内存。 | | `PRESTO_DEFAULT_TIMEOUT_SECONDS` | `1800` | 增加长时间运行的超时时间。 | | `PRESTO_MAX_CONCURRENT_RUNS` | `2` | 允许多个并发 Docker 运行（高级）。 | | `PRESTO_NETWORK` | `none` | 保持隔离；仅在调试时更改。 | | `PRESTO_SKIP_HEALTHCHECK` | `false` | 测试/调试仅；请勿在生产中使用。 | | `PRESTO_PYTHON_BIN` | *(自动)* | 镜像内的 `python3` 或 `python`；空 = 在启动时检测。 | | `PRESTO_MCP_LOG_LEVEL` | `INFO` | 结构化日志级别（`DEBUG`/`INFO`/`WARNING`/`ERROR`）。 | | `PRESTO_MCP_LOG_DIR` | `./logs` | 服务器会话 + 每个运行日志的基本目录。 | | `PRESTO_MCP_JSON_LOGS` | `true` | 与人类日志一起写入机器可读的 JSONL 日志。 | | `PRESTO_MCP_LIVE_STATUS` | `true` | 持续更新 `logs/runs/<run_id>/status.md`。 | | `PRESTO_MCP_CAPTURE_STDOUT_STDERR` | `true` | 将 PRESTO stdout/stderr 尾部捕获到运行日志中。 | ### 4. 验证启动 从仓库根目录： ```bash uv run --directory . python -m presto_mcp.server ``` 您应该在交互式终端中看到 **RUNNING** 横幅。按 Ctrl+C 停止。如果启动失败，请阅读 **stderr 上的横幅**（在 MCP Inspector 终端中也可见）：它列出了错误代码、简要摘要和编号的补救步骤。 **常见启动失败 — `DOCKER_DAEMON_DOWN`:** Docker 已安装但 Docker Desktop 未运行。在 Windows/macOS 上，服务器可以尝试自动启动它（默认 `PRESTO_AUTO_START_DOCKER=true`；等待最多 `PRESTO_AUTO_START_DOCKER_TIMEOUT_SECONDS`）。您也可以手动启动 Docker Desktop，确认 `docker info` 工作，然后重新启动 presto-mcp。 **Inspector “连接”但未列出工具：** 子进程在健康检查期间退出。在终端中运行相同的 `uv run ...` 命令 — 不要仅依赖 Inspector UI。 **`Invalid JSON: EOF` / `Received exception from stream` with `input_value='\n'`：** 您在服务器等待 stdio 的终端中按下了 Enter，或者 MCP 客户端发送了一个空行。不要在该窗口中输入 — 而是从您的 MCP 客户端连接。如果 Docker 仍在启动，请等待直到 `docker info` 工作，然后再次连接（不要在服务器终端中按 Enter）。 **注意：** PRESTO 已经在每个工具调用的短暂 `docker run --rm` 容器中运行。启动仅确保 Docker *引擎*可用；它不会启动一个长-lived PRESTO 容器。 ### 5. 测试工具（MCP Inspector） 无需先配置 Cursor 或 Claude： ```bash npx @modelcontextprotocol/inspector uv run --directory . python -m presto_mcp.server ``` 打开 Inspector 打印的 URL。尝试 `presto.validate_environment` 和 `presto.readfile`，文件名在 `data/` 下。 ### 6. 连接 Cursor 或 Claude Desktop 复制模板并仅替换 **only** `REPLACE_WITH_REPO_ROOT` 为绝对克隆路径（在 Windows JSON 中使用 `\\`）。 | 客户端 | 模板 | 目的地 | |--------|----------|-------------| | **Cursor** | [examples/mcp/cursor_mcp.example.json](examples/mcp/cursor_mcp.example.json) | `.cursor/mcp.json` 在仓库根目录 | | **Claude Desktop** | [examples/mcp/claude_desktop_config.example.json](examples/mcp/claude_desktop_config.example.json) | 合并到系统 `claude_desktop_config.json` 中 | 启用 **presto** 服务器（Cursor：设置 -> MCP）。完全重启 Claude Desktop。 额外详细信息（`uv.exe` 路径，venv 选项）：[examples/mcp/README.md](examples/mcp/README.md)。 ### 7. 与 LLM 一起使用 提示示例： - *“在 `57762_12049_J0532+3305_000022.fil` 上运行 `presto.readfile` 并总结元数据。”* - *“在该文件上使用 `presto.rfifind`，时间为 `2.0`，然后显示掩模统计信息。”* 文件名**相对于 `PRESTO_DATA_DIR`**（无绝对路径和 `..`）。输出进入 `runs/<run_id>/artifacts/`。 对于长时间作业：设置 `"background": true` 并使用 `presto.get_run_manifest` 轮询，直到 `SUCCESS` / `FAILED` / `TIMEOUT`。 ### 何时使用哪个命令 | 目标 | 命令 | |----------|---------| | 验证安装 | `uv run --directory . python -m presto_mcp.server` | | 在浏览器中测试工具 | `npx @modelcontextprotocol/inspector uv run --directory . python -m presto_mcp.server` | | 与 Cursor / Claude 一起使用 | 客户端运行相同的 `uv run --directory <REPO> ...`（JSON 模板）；**无需**额外的终端 | --- ## MCP 工具 服务器注册了 **45** 个 `presto.*` 工具。实用工具（无 Docker）首先列出；其余工具在配置的镜像中调用 PRESTO。 | 工具 | 目的 | | ---------------------------- | --------------------------------------------------- | | **分类和实用工具** | | | `presto.validate_environment` | Docker/镜像检查 + 可选的每个工具的准备情况 | | `presto.list_data_files` | 索引 `PRESTO_DATA_DIR` 下的文件 | | `presto.readfile` | 解析滤波器库/PSRFITS 头部元数据 | | `presto.list_runs` | 列出最近的运行（最新的优先） | | `presto.get_run_manifest` | 一个 `run_id` 的完整清单 | | `presto.summarize_run` | 结构化运行摘要 + `next_suggested_tools` | | `presto.inspect_artifacts` | 每个工件索引，带有资源 URI | | `presto.compare_periods` *(实用)* | 交叉检查周期与 `.par` 星历 | | `presto.binary_info` *(实用)* | 二进制 `.par` 的轨道摘要 | | `presto.compile_candidate_report_pdf` *(实用)* | 将运行图捆绑到一个 PDF 中 | | **RFI 和准备** | | | `presto.rfifind` | RFI 搜索 → `.mask`、`.rfi`、`.stats` 等 | | `presto.prepdata` | 扣除一个 DM → `.dat` + `.inf` | | `presto.ddplan` | DM 试验计划（无输入文件） | | `presto.prepsubband` | 扣除一个 DM 范围 → 许多 `.dat` 文件 | | **搜索和折叠** | | | `presto.realfft` | FFT 一个 `.dat` → `.fft` | | `presto.accelsearch` | 傅里叶/加速度搜索 `.fft` | | `presto.sifting` | 排名/消除重复的 ACCEL 候选者 | | `presto.prepfold` | 在已知周期 + DM 下折叠 → `.pfd` | | `presto.single_pulse_search` | `.dat` 文件的明亮单脉冲搜索 | | `presto.zapbirds` | 将 zaplist 应用于 `.fft` | | **时序和瞬变** | | | `presto.get_toas` | `.pfd` 和模板的时间到达 | | `presto.rrattrap` *(实验/依赖镜像)* | 分组单脉冲事件 | | `presto.make_spd` | 构建单脉冲诊断 `.spd` | | `presto.plot_spd` | 渲染 SPD 图（PNG/PS） | | `presto.waterfaller` | 动态谱（瀑布）PNG，围绕候选者 | | **数据准备** | | | `presto.psrfits2fil` | PSRFITS → SIGPROC `.fil` | | `presto.downsample_filterbank` | 降采样 `.fil`（调试/快速迭代） | | `presto.fb_truncate` | 从 `.fil` 中剪切样本窗口 | | **RFI** | | | `presto.rfifind_stats` | 结构化 `bad_channels` / `bad_intervals` 摘要 | | `presto.weights_to_ignorechan` *(实验)* | `.weights`/`.mask` → ignorechan 列表 | | `presto.makezaplist` *(实验)* | 从 `.birds` 构建 `.zaplist` | | **折叠质量控制** | | | `presto.pfd2png` *(实验)* | `.pfd` → PNG/PS（依赖镜像） | | `presto.pfdzap` *(实验)* | 严格区间/通道遮蔽 `.pfd` | | **高级** | | | `presto.sum_profiles` *(实验)* | 合并多个 `.bestprof` / `.prof` | | `presto.fourier_fold` *(实验)* | 在已知候选者上折叠 `.fft` | | `presto.search_bin` *(高级)* | 相位调制/边带搜索二进制 | | `presto.stacksearch` *(实验/依赖镜像)* | 搜索多个 `.fft` | | `presto.simple_zapbirds` *(实验/依赖镜像)* | 从 `.fft` 中消除鸟鸣（在暂存副本上） | | **现代报告** *(事后；读取工作目录)* | | | `presto.export_candidates_csv` | 归一化的 `candidates.csv` 用于一次运行 | | `presto.generate_summary_json` | 结构化 `summary.json` | | `presto.generate_visual_artifacts` | 发布 PNG 可视化 + 缩略图 | | `presto.generate_candidate_waterfalls` | 每个候选者的瀑布 PNG/PDF | | `presto.generate_report_html` | 离线 HTML 仪表板 | | `presto.generate_report_markdown` | 轻量级 Markdown 报告 | | `presto.generate_modern_report_bundle` | 完整报告包（意图路由） | **工具状态分类。** `stable` · `experimental`（等待镜像验证）· `image-dependent`（正确性取决于镜像内容，准备就绪门控）· `advanced`（参数空间广）· `utility`（无 Docker）。 ### 工具配置文件 `.env` 中的 `PRESTO_TOOL_PROFILE` 选择服务器公开哪些工具，以便 LLM 代理从较小的、任务聚焦的目录中选择，而不是一次选择所有 45 个工具。 | 配置文件 | 暴露的工具 | |---------|---------------| | `all`（默认） | 所有 45 个工具。 | | `core` | 仅核心工具（7 个工具）：`validate_environment`、`list_data_files`、`readfile`、`list_runs`、`get_run_manifest`、`summarize_run`、`inspect_artifacts`。 | | `rfi_prep` | 核心 + 数据准备 + RFI 工具。 | | `periodic` | 核心 + 周期/加速搜索管道。 | | `single_pulse` | 核心 + 单脉冲搜索管道。 | | `review_qc` | 核心 + 候选人审查/已知脉冲星 + 现代报告工具。 | | `advanced` | 核心 + 高级/实验性工具。 | 每个非 `all` 配置文件都包含上面的**核心**集，因此 `presto.get_run_manifest`（用于 `background` 轮询）始终可用。未知值会回退到 `all`。 ### 运行时兼容性 并非每个 PRESTO 镜像都包含每个例程，有些镜像会包含脚本但不包含它导入的内部 Python 模块。**任何会话中的推荐首选调用：** ```text presto.validate_environment(include_tool_readiness=true) presto.list_data_files(limit=20) presto.readfile(input_file="<your file>") ``` `presto.validate_environment` 通过轻量级 Docker 命令探测镜像，并报告每个工具的准备就绪情况（`runtime_compatibility.tool_readiness`）。依赖镜像的工具（`rrattrap`、`stacksearch`、`simple_zapbirds` 和 `accelsearch -wmax` 抖动标志）在检查就绪情况后会快速失败，并出现受控的、可操作的错误，而不是令人困惑的回溯。 已知案例：一些 PRESTO 镜像公开 `rrattrap.py` 但无法 `import presto.singlepulse`；然后 `presto.rrattrap` 拒绝运行并指向 `presto.validate_environment`。参见 [RUNTIME_COMPATIBILITY.md](./docs/RUNTIME_COMPATIBILITY.md) 获取完整内容。 **链接运行：** 消耗先前输出的工具采用类似 `<run_id>/artifacts/file.dat>` 的路径，相对于 `runs/`（参见每个工具的参数文档）。 ### MCP 资源 | URI | 内容 | | --- | --- | | `presto://data` | `PRESTO_DATA_DIR` 的 JSON 索引 | | `presto://runs` | 最近运行的 JSON 索引 | | `presto://runs/{run_id}/manifest` | `manifest.json` | | `presto://runs/{run_id}/stdout` | PRESTO stdout | | `presto://runs/{run_id}/stderr` | PRESTO stderr | | `presto://runs/{run_id}/summary` | `RunStructuredSummary` JSON | | `presto://runs/{run_id}/artifacts` | 工件索引（无文件内容） | | `presto://runs/{run_id}/artifacts/{filename}` | 一个工件（文本内联；大型/二进制 → JSON 描述符） | 完整参考： [RESOURCES.md](./docs/RESOURCES.md). **Docker 健康检查**（可选，在安装后）： ```bash docker run --rm alex88ridolfi/presto5:png which readfile rfifind prepfold ``` 启动健康检查调用 `docker info`，不仅是 `docker --version`；必须运行 Docker 守护进程。`presto.validate_environment` 分别报告 CLI、守护进程和镜像检查。 ### 现代报告层 (`outputs/`) `runs/` 保留原始 PRESTO 输出（内部工作目录）。**现代报告层** 在需求时将运行转换为干净、天文学家友好的工件，位于 `outputs/<run_id>/` 下，通过 7 个 `presto.*` 工具（它从不修改 PRESTO）。 ``` outputs/<run_id>/ manifest.json summary.json candidates.csv report.html report.md status.md / timeline.json visuals/*.png thumbnails/*.png waterfalls/*.png|*.pdf candidates/<id>/ (candidate.json, waterfall.png, ...) ``` 原始 PRESTO 中间件（`.dat`、`.fft`、`.pfd`、`.singlepulse`、`.ps` 等）**默认不**发布。允许的公共扩展名：`.json .csv .html .md .png .pdf`。用于完整报告的首选工具是 `presto.generate_modern_report_bundle`. 参见 [docs/modern_reporting_layer.md](./docs/modern_reporting_layer.md) 和 [docs/artifact_policy.md](./docs/artifact_policy.md). ### 可观测性（`logs/`） 每个服务器会话、MCP请求、工具调用、PRESTO命令、构件和错误都被记录为结构化事件： ``` logs/server/server-<session>.{log,jsonl} logs/server/latest.{log,jsonl} logs/runs/<run_id>/ run.jsonl timeline.json tool_calls.jsonl presto_commands.jsonl artifacts.jsonl errors.jsonl status.md commands/<id>.std{out,err}.txt ``` 人类可读和机器可读的JSONL日志文件并存，支持日志轮转、密钥隐藏和实时的`status.md`文件。可以通过传递可选的`workflow_run_id`参数，将管道的调用分组到一个`logs/runs/<id>/`目录下。可以通过上述的`PRESTO_MCP_LOG_*`变量进行配置。 --- ## 手动运行服务器 ```bash uv run --directory . python -m presto_mcp.server ``` 从`.env`文件中加载`PRESTO_*`环境变量，创建`runs/`、`outputs/`、`logs/`目录，运行健康检查，然后通过标准输入输出进行MCP通信。对于日常使用，建议让MCP客户端自动生成此命令，而不是手动运行。 --- ## 测试 ```bash uv run pytest -q # 单元测试和集成测试（不使用Docker） uv run ruff check . uv run pytest -q tests/e2e --run-e2e # 真实的Docker和数据测试 ``` --- ## 磁盘上的单个运行 ``` runs/20260517T145912Z-OE2YWN/ ├── manifest.json # Docker参数、状态、构件、时间信息 ├── stdout.log ├── stderr.log └── artifacts/ └── waterfall.png ``` `run_id`格式：`YYYYMMDDTHHMMSSZ-<6-char base32>`（UTC时间 + 随机熵）。 --- ## 实用工具和提示 工具参数和示例：[工具文档](./docs/TOOLS.md)。 快速检查： ```text presto.validate_environment(include_tool_readiness=true) presto.list_data_files(limit=20, extensions=[".fil",".fits"]) ``` **提示**（12种提示模板，无自动执行）：[提示文档](./docs/PROMPTS.md)。这些提示出现在MCP检查器和任何支持提示的客户端中。 **职责分离**。MCP层提供原子化、沙盒化的能力（工具）、可导航的状态（资源）和可重用的指导（提示）。有状态的自适应编排（循环遍历候选项、根据结果分支、带有参数调整的重试）属于未来版本的LangGraph（或等效层）的一部分，而不是在MCP内部实现。 --- ## 安全（摘要） - 输入通过`path_security`验证 - 不允许绝对路径、不允许`..`、仅限于`DATA_DIR`或暂存运行构件。 - 执行：仅使用`subprocess.run(argv, shell=False)`；不使用通用shell工具。 - Docker： `--network none`、`no-new-privileges`、`--pids-limit 256`、只读`data/`绑定、可选的只读`/runs`绑定用于先前的构件。 - 并发：`PRESTO_MAX_CONCURRENT_RUNS`控制Docker调用的进程范围（默认为`2`）。 - 类型化错误 - 不向客户端返回原始堆栈跟踪。 详细信息：[架构文档](./docs/ARCHITECTURE.md)。代理约定：[代理文档](./AGENTS.md)。 --- ## 限制和已知限制 - **仅支持标准输出解析器**，用于结构化字段；二进制产品（`.mask`、`.pfd`、PNG图像）作为构件/资源，不在服务器端解码。 - **`prepfold` 模式A** - 已知的周期 + 色散测量；加速候选折叠尚未实现。 - **仅支持标准输入输出** - 不支持HTTP传输。 - **`list_runs`** 通过遍历`runs/*/manifest.json`实现（适用于数千次运行）。 - 标准输出/标准错误仍在写入日志之前保存在内存中；返回给客户端的诊断信息是有限的，完整的日志保留在运行资源中。 - **依赖于镜像的工具**（`rrattrap`、`stacksearch`、`simple_zapbirds`、`accelsearch -wmax`）仅在配置的PRESTO镜像提供相应例程时才有效 - 请检查`presto.validate_environment(include_tool_readiness=true)`。参见 [运行时兼容性文档](./docs/RUNTIME_COMPATIBILITY.md)。 - `presto.binary_info` 的 `make_plot` 功能不受支持（它是一个无需Docker的实用工具）；轨道图来自 `presto.prepfold` / `presto.pfd2png`。 - 自适应编排（恢复/重启、自主搜索）**超出范围** - 它属于未来版本的LangGraph层。 贡献 - 请阅读 [贡献指南](./CONTRIBUTING.md)（尤其是反膨胀规则）。发布历史 - [变更日志](./CHANGELOG.md)。 --- ## 项目布局 | 路径 | 角色 | | --- | --- | | `pyproject.toml` / `uv.lock` | 依赖项和可复制的锁定文件（`uv sync`） | | `.env.example` | 所有 `PRESTO_*` 设置的模板 | | `AGENTS.md` | 代理编码的规范指南 | | `CONTRIBUTING.md` | 贡献规则和反膨胀政策 | | `docs/` | 架构、工具、提示、资源、运行时兼容性 | | `src/presto_mcp/server.py` | FastMCP入口点（标准输入输出） | | `src/presto_mcp/server_tools.py` | MCP工具注册（45种工具） | | `src/presto_mcp/reporting/` | 现代报告/构件层 | | `src/presto_mcp/observability/` | 结构化日志记录 + 运行跟踪 | | `src/presto_mcp/server_resources.py` | MCP资源注册 | | `src/presto_mcp/server_prompts.py` | MCP提示注册（12种提示） | | `src/presto_mcp/tool_metadata.py` | 工具配置文件（`PRESTO_TOOL_PROFILE`） | | `src/presto_mcp/docker_backend.py` | Docker参数 + 子进程 | | `src/presto_mcp/path_security.py` | 路径保护 | | `src/presto_mcp/executor.py` | 运行编排 | | `src/presto_mcp/tools/` | 每个工具一个模块 | | `tests/` | 单元测试、集成测试和端到端测试 | | `scripts/runtime_compat_report.py` | 手动镜像兼容性报告（CI工作流） | | `examples/mcp/` | 游标/Claude桌面JSON模板 | | `data/` | 观测输入（只读；通常不提交） | | `runs/` | 每次调用的清单、日志、构件（运行时） | --- ## 许可证 MIT - 请参见 `pyproject.toml`。