内容
# TENSA
**暂态，特征值和电网仿真应用** - 一个用于电力系统建模、仿真和分析的交互式、基于Web的工作台。你可以直观地构建系统，一键运行潮流和动态研究，实时查看结果，并通过可脚本化的API控制整个过程。它在你的浏览器中本地运行。TENSA基于[ANDES](https://github.com/CURENT/andes)电力系统仿真器构建。（该项目曾短暂地以“ANDES App”为名在测试阶段；相同的工具，新的名称。）
[](./LICENSE)
[](https://www.python.org/)
[](https://github.com/CURENT/andes)
[](./llms.txt)
## 查看实际操作
一个AI代理从头开始构建WSCC 9总线系统，通过实际的UI。它放置每个总线、线路、变压器、机器、励磁机和调速器，布局单线图，将案例保存到文件中并重新加载，然后运行潮流、三相故障和流媒体时域仿真、连续潮流和特征值分析。
[](https://github.com/Roger-GO/TENSA/raw/main/docs/demo/ieee9-agent-demo.mp4)
上面的剪辑是加速的。 [观看完整的2分钟演练（MP4）](https://github.com/Roger-GO/TENSA/raw/main/docs/demo/ieee9-agent-demo.mp4)。每一步都使用相同的HTTP API，任何脚本或代理都可以调用，并且您可以[自己记录](#run-the-demo-yourself)。
## 您能做什么
- **直观地构建系统。** 从UI添加总线、线路、变压器、发电机（静态和GENROU）、励磁机、调速器、负载和分流器。单线图自行布局，完全可拖动，因此您可以构建完整的动态案例，而无需触摸文件。
- **一键运行五项分析。** 潮流、时域仿真、特征值（小信号）、具有PV和QV曲线的连续潮流和状态估计。每个分析都作为非阻塞作业运行，带有实时进度和取消按钮。
- **在仿真运行时查看结果。** 时域结果通过WebSocket作为Apache Arrow帧流式传输，并在运行过程中填充图表，同时在图表上动画电压带叠加层。
- **一目了然地读取网络。** 传统的母线单线图，馈线、机器和负载整洁地围绕每个总线，潮流后显示电压和MW/MVAr流量标签，当总线超过其限制时显示颜色。
- **交互式添加干扰。** 总线故障、断路器切换和参数更改，在运行前设置并在重新加载案例时重放。
- **无忧编辑参数。** 更改是克隆后写入，带有完整的撤销/重做和差异视图。在提交之前，不会触及加载的案例。
- **查看结果。** 电压和角度图、可缩放和移动的特征值散点图、PV鼻曲线和残差直方图，全部在专用的全屏结果视图中。
- **保存、重新加载和复制。** 将系统写入xlsx、raw或json，稍后重新加载，并导出一个自包含的包，捕获案例、其布局和结果。
- **自动化。** 文档化的REST和WebSocket API，带有OpenAPI模式。 UI可以做的任何事情，脚本或AI代理也可以做。
- **保持本地。** 所有操作都在您的机器上运行。 服务器默认绑定到环回地址，没有帐户，也不会有任何信息发送到外部。
## 快速开始
最快的路径 - PyPI上的软件包已经内置了UI，因此您只需要这样做：
```bash
pip install tensa
tensa warm-cache # 一次，大约30秒
tensa serve --workspace ~/tensa-cases --port 8000 --open
```
### 从源代码
对于开发，或者您想自己构建UI，您需要Python 3.12或更高版本，以及带有[pnpm](https://pnpm.io/)的Node 22。 Node仅用于构建UI一次。
```bash
# 0. 克隆
git clone https://github.com/Roger-GO/TENSA.git
cd TENSA
# 1. 安装服务器（拉取ANDES、FastAPI、pyarrow）
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ./server
# 2. 构建Web UI（一次）
cd web && pnpm install && pnpm build && cd ..
# 3. 预热ANDES符号缓存（一次，大约30秒；升级ANDES后重新运行）
tensa warm-cache
# 4. 在一个端口上提供UI和API，然后打开浏览器
tensa serve --workspace ~/andes-cases --port 8000 --open
```
打开 `http://127.0.0.1:8000`。在第一次运行时，会为一个空的工作区提供三个示例案例（IEEE-14、Kundur和WSCC-9），因此可以立即打开一个案例。 加载案例或从头开始构建案例，运行潮流，添加干扰，并流式传输时域仿真。
要使用您自己的案例，请将任何`.xlsx`、`.raw`、`.dyr`或`.json`文件放入`--workspace`目录中，它就会出现在文件选择器中。
## 自己运行演示
[`web/scripts/agent-demo.mjs`](web/scripts/agent-demo.mjs) 记录了本README顶部的视频。 它使用Playwright驱动实际的UI：它从头开始构建WSCC 9总线，然后运行每个分析。
```bash
# 终端1：固定端口提供服务
tensa serve --workspace ~/andes-cases --port 18800
# 终端2：记录（写入demo-video/ieee9-agent-demo.webm）
cd web && pnpm exec playwright install chromium # 一次
node scripts/agent-demo.mjs http://127.0.0.1:18800
```
## 用于代理和脚本
整个应用程序由文档化的HTTP和WebSocket API驱动。 UI可以做的任何事情，脚本或LLM代理也可以做。
- OpenAPI模式位于 `GET /openapi.json`，交互式文档位于 `/docs`（Swagger）和 `/redoc`。
- [llms.txt](./llms.txt) 是为LLM消费编写的API映射：端点、工作流排序、枚举和值得注意的陷阱。
- [examples/](./examples/) 包含用于API的curl演练和自包含的Python客户端。
- MCP服务器通过[Model Context Protocol](https://modelcontextprotocol.io)工具公开会话、案例加载、潮流、TDS和干扰，因此像Claude这样的助手可以直接运行仿真：
```bash
pip install -e './server[mcp]'
tensa mcp --workspace ~/andes-cases
```
典型的程序流程：
```
POST /api/sessions -> session_id
POST /api/sessions/{id}/case -> 加载案例（xlsx/raw/dyr/json/m）
POST /api/sessions/{id}/disturbances -> 添加故障/切换/更改（预设置）
POST /api/sessions/{id}/pflow -> 解决潮流
POST /api/sessions/{id}/tds -> 批量TDS，或通过WS /api/ws/{id}流式传输
GET /api/sessions/{id}/operating-point -> 总线电压和角度
```
## 开发模式
```bash
# 终端1：后端
tensa serve --workspace ~/andes-cases --port 8000
# 终端2：前端热重载
cd web && VITE_ANDES_PORT=8000 pnpm dev # -> http://localhost:5173
```
## 网络访问和安全
要从网络上的另一台机器访问应用程序：
```bash
tensa serve --workspace ~/andes-cases --port 8000 \
--bind 0.0.0.0 --allow-origin http://<your-lan-ip>:8000
```
安全注意：TENSA没有身份验证。 它默认绑定到`127.0.0.1`（环回地址），并信任本地OS用户。 绑定到非环回地址会将API暴露给任何可以访问该接口的人，包括案例文件解析，这会评估表达式。 仅在您信任的网络上执行此操作，不要在该模式下加载不受信任的案例文件。 有关详细信息，请参见 [SECURITY.md](./SECURITY.md)。
## 架构
```
┌──────────────┐ REST + WebSocket ┌───────────────────┐ 多进程 ┌──────────────┐
│ React 19 SPA │ ◄────────────────► │ FastAPI 基质 │ ◄──────────────► │ ANDES 工作器 │
│ （或任何HTTP │ /api/* + /ws │ 会话、作业、 │ 数据 + 控制 │ 一个系统 │
│ 客户端） │ │ Arrow 流媒体 │ 管道 │ 每会话 │
└──────────────┘ └───────────────────┘ └──────────────┘
```
每个会话在单独的子进程中获得自己的`andes.System`。 API进程永远不会阻塞正在运行的仿真，并且一个运行中的崩溃不会导致服务器崩溃。
## 项目布局
| 路径 | 内容 |
|---|---|
| [`server/`](./server) | Python后端。 FastAPI路由器、每会话子进程工作器、Arrow流媒体、克隆后写入编辑和`tensa` CLI。 |
| [`web/`](./web) | React 19 和 TypeScript UI。 交互式SLD（React Flow），uPlot结果图，Radix UI，Tailwind v4，Zustand。 |
| [`examples/`](./examples) | 用于API的curl和Python客户端演练。 |
| [`llms.txt`](./llms.txt) | 为LLM编写的API映射。 |
| [`docs/`](./docs) | 图片和演示视频。 |
## 引用
如果您在工作中使用TENSA，请引用它。 GitHub的“引用此仓库”按钮从[CITATION.cff](./CITATION.cff)构建引用。 简短形式：
> Gracia Otalvaro, R. (2026). TENSA: 一个用于电力系统仿真的交互式Web工作台。 https://github.com/Roger-GO/TENSA
TENSA运行在ANDES上，后者执行底层电力系统计算。 如果您引用该项目，请同时感谢ANDES背后的作者，即[CURENT/ANDES](https://github.com/CURENT/andes)项目，由Cui等人开发。
## 贡献
欢迎PR。 有关设置、测试命令和约定的详细信息，请参见[CONTRIBUTING.md](./CONTRIBUTING.md)。 AI编码代理的说明位于[AGENTS.md](./AGENTS.md)，而值得注意的更改记录在[CHANGELOG.md](./CHANGELOG.md)中。
## 许可证
TENSA在[GNU General Public License v3.0](./LICENSE)下获得许可，与ANDES相同的许可证。
