# stability-criteria

**Repository Path**: openminds/stability-criteria

## Basic Information

- **Project Name**: stability-criteria
- **Description**: 飞行器气动稳定性耦合判据。判据可作为初步选形的快速有效工具，但在未经完整仿真与试验验证前，不宜直接称为充要条件。实际设计中应结合数值仿真、地面试验和飞行试验综合验证。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: stability, MCP

## README

# stability-axes

飞行器气动稳定性耦合判据 MCP 服务器（FastMCP 4）。判据可作为初步选形的快速有效工具，但在未经完整仿真与试验验证前，不宜直接称为充要条件。实际设计中应结合数值仿真、地面试验和飞行试验综合验证。

仓库地址：[https://gitee.com/openminds/stability-criteria](https://gitee.com/openminds/stability-criteria)

理论依据见 [thoery.md](thoery.md)（文件名沿用历史拼写），涵盖式 (9)–(62)。

## 功能特性

基于 [Model Context Protocol](https://modelcontextprotocol.io/) 暴露 8 个工具，供支持 MCP 的 AI 客户端（Claude Code、Trae、Cursor 等）调用：

| 工具 | 说明 | 理论公式 |
|---|---|---|
| `compute_primed_derivatives` | 体轴原始导数 → 含 Ixz 交叉耦合修正的 primed 导数 | 式 (9) |
| `evaluate_pitch_open` | 开环俯仰通道稳定性判据 | 式 (11a)/(12)/(15)/(17a) |
| `evaluate_yaw_open` | 开环偏航通道稳定性判据 | 式 (20a)/(21)/(24)/(26a) |
| `evaluate_roll_open` | 开环滚转通道稳定性判据 | 式 (38a)/(33)/(36)/(38b) |
| `evaluate_pitch_closed` | 闭环俯仰通道稳定性判据 | 式 (41)/(42)/(43)/(43a)/(43b) |
| `evaluate_yaw_closed_tailless` | 无尾飞行器闭环偏航判据（保留 `Y_da_p`） | 式 (46)/(47)/(48)/(49) |
| `evaluate_roll_closed` | 闭环滚转通道稳定性判据 | 式 (52)/(54)/(55)/(55a)/(55b) |
| `evaluate_nonlinear` | 大迎角/侧滑非线性判据（输入为力矩，非导数） | 式 (56)–(62) |

线性判据对三次特征多项式 `λ³ + A2λ² + A1λ + A0` 采用严格 Routh–Hurwitz 条件：`A2>0`、`A0>0`、`A2·A1−A0>0`。

## 环境要求

- Python ≥ 3.12
- [uv](https://docs.astral.sh/uv/)（本仓库包管理器）
- 支持 MCP 的 AI 客户端（Claude Code、Trae、Cursor 等）

## 安装

在项目根目录 `E:\myWorkspace\stability-criteria` 下执行：

```powershell
uv sync --extra dev
```

安装完成后将生成：

- 虚拟环境：`E:\myWorkspace\stability-criteria\.venv`
- stdio 启动入口：`E:\myWorkspace\stability-criteria\.venv\Scripts\stability-criteria.exe`

## AI 客户端 MCP 配置

项目绝对路径：`E:\myWorkspace\stability-criteria`

在 AI 客户端的 MCP 服务器配置中添加以下内容（通过 uv 启动，不依赖虚拟环境的具体路径）：

```json
{
  "mcpServers": {
    "stability-axes": {
      "command": "uv",
      "args": ["run", "--directory", "E:\\myWorkspace\\stability-criteria", "stability-criteria", "--transport", "stdio"]
    }
  }
}
```

各客户端读取该文件的方式：

- **Claude Code**：自动识别项目根目录的 `.mcp.json`，首次使用时提示是否信任该服务器；
- **Trae**：在设置 → MCP 中添加服务器，或放置 `.mcp.json` 于项目根目录；
- **Cursor**：在 Settings → MCP 中添加，或放置 `.mcp.json` 于项目根目录；
- **其他客户端**：参考各客户端文档配置 stdio 类型的 MCP 服务器，`command` 与 `args` 同上。

### 验证连接

```powershell
claude mcp list
```

看到 `stability-axes` 状态为 `✔ Connected` 即配置成功（其他客户端请参考各自文档查看连接状态）。进入 AI 客户端会话后可直接提问，例如：

> 用开环俯仰通道判据评估这组 primed 导数是否稳定

## 使用说明

### 典型调用流程

1. 调用 `compute_primed_derivatives`，将体轴原始导数按式 (9) 转换为 primed 导数，可用 `channel` 参数（`pitch`/`yaw`/`roll`/`all`）过滤输出；
2. 将 primed 导数与飞行姿态角（弧度）传给对应的开环评估工具；
3. 闭环工具需额外提供控制面 primed 导数与反馈增益（`ControlGains`）；
4. 返回的 `StabilityResult` 包含 `A2/A1/A0`、风轴导数、逐项判据布尔值、`overall_stable` 与可读 `message`。

注意：输入模型均设置 `extra="forbid"`，多余字段会被拒绝；`Ix/Iy/Iz ≤ 0` 等校验错误以工具错误（ToolError）返回，不会产生服务端 500。

### CHINA 坐标约定

`coordinate_system` 参数支持 `"default"`（默认）与 `"CHINA"`（中国国标符号体系）：

- **输入始终按 thoery.md 默认约定提供**，该参数不改变输入解释；
- `CHINA` 仅作用于输出显示层：风轴导数值取反、不等号方向对调（lt ↔ gt）；
- 因此 `A2/A1/A0`、Routh–Hurwitz 各项与 `overall_stable` 在两种模式下**严格不变**。

## 测试

```powershell
uv run pytest
```

## 直接运行

```powershell
# stdio（等价于 MCP 客户端启动方式）
uv run stability-criteria

# HTTP
uv run uvicorn stability_axes.mcp_server:app --port 8000
```

## 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request