内容
<div align="center">
# SimTrace
**一个可追踪的、用于构建工具的离散事件仿真工具包，适用于 SimPy 模型，通过 MCP 暴露。**
[](LICENSE)
</div>
---
SimTrace 将 [FactorySimPy](https://github.com/FactorySimPy/FactorySimPy) 的离散事件仿真基元作为 **MCP 工具**公开，以便 LLM 代理可以逐步构建工厂模型（创建节点，创建边，连接它们并运行仿真），并通过 OpenTelemetry **跟踪每个工具调用**。
服务器通过 stdio 使用开放的 [MCP](https://modelcontextprotocol.io) 协议，并且是**客户端无关的**：任何 MCP 客户端（桌面助手、代理框架或自定义客户端）都可以驱动它。
## 功能
- 🧱 **可组合的基元：** 源、机器、分割器、组合器、缓冲区、输送带和车队，每个都是一个单独的、类型良好的工具调用。
- 🤖 **代理原生：** LLM 一次构建一个工具调用，运行并调整模型，而不是发出固定的脚本。
- 🔍 **默认可追踪：** 每个工具调用都成为一个 OpenTelemetry 跨度，您可以在 Jaeger 中检查它，以便查看模型的构建和运行方式。
- ✅ **运行后验证：** 保守和逐项流程检查捕获了静默丢失或错误路由物品的模型。
## 工具
| 分组 | 工具 | 模块 |
|---|---|---|
| 节点（主动） | `create_source`、`create_sink`、`create_machine`、`create_splitter`、`create_combiner` | `simtrace.tools.builders.nodes` |
| 边（被动） | `create_buffer`、`create_conveyor`、`create_fleet` | `simtrace.tools.builders.edges` |
| 生命周期 | `connect`、`get_model`、`reset_model`、`run_simulation` | `simtrace.tools.simulation` |
| 验证 | `verify_conservation`、`verify_item_flow` | `simtrace.tools.validation` |
设计说明位于 [`architecture/`](architecture/) (`node_tools.md`、`edge_tools.md`、`simulation_tools.md`、`observability.md`)。工作模型位于 [`examples/`](examples/)。
## 快速开始
需要 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。
```bash
git clone https://github.com/s0582346/SimTrace.git
cd SimTrace
uv sync
```
这安装了所有依赖项，包括在 `vendor/FactorySimPy` 下的 FactorySimPy 供应商checkout。
然后启动 MCP 服务器：
```bash
uv run python -m simtrace.server
```
服务器通过 stdio 使用 MCP，因此通常由 MCP 客户端启动（参见下文），而不是手动运行。
> **注意：** `pyproject.toml` 中的 `simtrace` 控制台脚本当前未连接；请使用 `python -m simtrace.server`。
## 连接 MCP 客户端
服务器是一个标准的stdio MCP服务器。配置您的MCP客户端使用项目的venv Python启动它：
/path/to/simtrace/.venv/bin/python -m simtrace.server
将 `/path/to/simtrace` 替换为克隆的绝对路径（在 Windows 上，例如 `C:\\Users\\you\\simtrace` 和 `\\.venv\\Scripts\\python.exe`）。
许多客户端共享相同的 JSON 配置格式，在 `mcpServers` 键下添加服务器：
```json
{
"mcpServers": {
"simtrace": {
"command": "/path/to/simtrace/.venv/bin/python",
"args": ["-m", "simtrace.server"]
}
}
}
```
配置完成后，SimTrace 工具将出现在客户端中。有关配置的位置和如何重新加载它，请参阅客户端文档。
## 可观察性（OpenTelemetry + Jaeger）
每个工具调用都成为一个 OpenTelemetry 跨度，通过 OTLP/HTTP 导出到本地 Jaeger 实例。
1. 启动 Jaeger：
```bash
docker compose up -d
```
2. 在不需要 MCP 客户端的情况下生成一些跨度。烟雾脚本调用真正的工具端到端（构建一个 `source -> buffer -> sink` 线路，运行它，并触发一个错误跨度）：
```bash
uv run python scripts/trace_smoke.py
```
即使 Jaeger 关闭，它也可以正常运行（跨度只是被丢弃），因此它也可以快速检查工具路径是否正常。
3. 在 <http://localhost:16686> → 服务 **simtrace** → *查找跟踪* 中查看跟踪。
当服务器由 MCP 客户端驱动时，跨度会以相同的方式导出；只需保持 Jaeger 运行。有关设计和配置详细信息（例如 `OTEL_EXPORTER_OTLP_ENDPOINT`），请参见 [`architecture/observability.md`](architecture/observability.md)。
## 许可证
SimTrace 在 [MIT 许可证](LICENSE) 下发布。
## 致谢
- [FactorySimPy](https://github.com/FactorySimPy/FactorySimPy)，SimTrace 建立在其上的离散事件仿真基元。
- [Fraunhofer IPK](https://www.ipk.fraunhofer.de/)，为支持这项工作。
