# ifppbot

**Repository Path**: ifpp-agent/ifppbot

## Basic Information

- **Project Name**: ifppbot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-08
- **Last Updated**: 2026-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ifppbot — 预测性维护助手

ifppbot 是一个基于 NASA ProgPy 的预测性维护（PHM）平台，由三个包组成：

| 包 | 技术栈 | 角色 |
|---|---|---|
| `packages/core` | Python 3.12+ | 内核：15 工具 MCP 面、数据体检、模型卡注册表、任务编排、报告渲染、黄金路径冒烟 |
| `packages/agent` | TypeScript/Node 20+ | 助手：pi-mono 薄适配层、领域 skills、对话状态机、P-a/P-b/P-c 反馈闭环、Agent-API、stdio MCP 子进程集成测试 |
| `packages/ui` | Vite + React + ECharts | 界面：五视图导航、WS 事件流、双通道（对话↔向导）、ECharts 图表渲染、i18n 双语 |

---

## 架构总览

```
┌─────────────────────────────────────────────────────┐
│                    ifppbot-ui                       │
│  (Vite+React: /home /chat /data /runs /settings)    │
│         ↕ Agent-API (HTTP+WS, 8 端点)               │
├─────────────────────────────────────────────────────┤
│                   ifppbot-agent                     │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐  │
│  │ session   │  │ orchestrator │  │ mcp-client       │  │
│  │ (状态机)  │  │ (5.1-5.5)   │  │ (15 工具白名单)   │  │
│  └──────────┘  └──────────┘  └────────┬──────────┘  │
│  ┌──────────┐  ┌──────────┐            ↕ MCP        │
│  │ wizard    │  │ pi-adapter │  ┌───────────────────┐ │
│  │ (精简模式) │  │ (LLM/Store │  │ ifppbot-core      │ │
│  └──────────┘  │  /Runner)  │  │ (Python 内核)     │ │
│                 └──────────┘  └───────────────────┘ │
└─────────────────────────────────────────────────────┘
```

**核心原则**：编排与规则确定性优先，LLM 只做理解与解释；LLM 缺席时精简模式完整兜底。

---

## 安装

### 前置条件

- Python ≥ 3.12（推荐 3.14）
- Node.js ≥ 20 LTS
- uv（Python 包管理器）

### 1. 安装 Python 内核

```bash
cd D:\codes\ifppbot

# 创建虚拟环境
uv venv .venv --python 3.14

# 安装 ifppbot-core（editable）
uv pip install --python .venv\Scripts\python.exe -e packages/core
```

### 2. 安装 Agent

```bash
cd packages/agent
npm install
npm run build
```

### 3. 安装 UI

```bash
cd packages/ui
npm install
npm run build
```

---

## 快速开始

### 1. 运行核心冒烟测试

```bash
# 确认内核 4 条黄金路径全绿
.venv\Scripts\python.exe -m ifppbot smoke
```

输出示例：
```
[OK] battery_rul: metrics={'rmse': 0.0, 'alpha_lambda': 0.0, ...} elapsed=2.2s
[OK] pump_rul: metrics={'rmse': 0.0, ...} elapsed=1.3s
[OK] battery_anomaly: metrics={'mean_score': 19.25, ...} elapsed=0.01s
[OK] synthetic: metrics={'quality_flags_count': 0.0, ...} elapsed=0.5s
[ALL GREEN] 4 条黄金路径全绿，基线已更新
```

### 2. 配置 Agent

复制模板并按需修改：

```bash
cd packages/agent
cp config.toml.ollama-example config.toml
# 或
cp config.toml.cloud-example config.toml
```

**Ollama 本地模型**（默认）：
```toml
[llm]
provider = "openai-compatible"
base_url = "http://localhost:11434/v1"
model = "qwen2.5:7b"
```

**云端模型**：
```toml
[llm]
provider = "openai-compatible"
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"
api_key_ref = "IFFPBOT_LLM_API_KEY"
```

### 3. 启动 Agent 服务

```bash
cd packages/agent
npm run build
node dist/index.js
```

输出：
```
[ifppbot-agent] listening on 127.0.0.1:8765 (mode: local)
```

### 4. 启动 UI

```bash
cd packages/ui
npm run dev
```

在浏览器打开 `http://localhost:5173`。

> 开发模式下，UI 通过 Vite 代理将 `/api` 请求转发到 Agent 服务（`http://127.0.0.1:8765`）。

---

## 使用流程

### 标准旅程（S1→S6）

```
S1 数据准备 → S2 数据体检 → S3 意图澄清 → S4 模型推荐 → S5 执行预测 → S6 结果解读
```

#### 方式一：对话模式（需 LLM）

1. 在 UI 的 **对话** 页面输入任务描述（如"帮我分析电池的 RUL"）
2. Agent 自动执行：体检 → 澄清 → 推荐 → 执行 → 解读
3. 结果在对话流中展示，含通俗层术语解释

#### 方式二：精简模式（无 LLM）

1. 在 **数据** 页面选择内置数据集或上传数据
2. 向导逐步引导：选任务 → 选目标 → 确认推荐 → 查看结果
3. 全部确定性，不依赖 LLM

#### 方式三：专家直跑

直接提交 TaskRecipe YAML：

```bash
curl -X POST http://127.0.0.1:8765/api/recipe/run \
  -H "Content-Type: application/json" \
  -d '{"session_id":"s1","recipe_yaml":"recipe: v1\nname: test\ntask: rul_prediction\n..."}'
```

### P-a/P-b/P-c 改进闭环

| 路径 | 含义 | 触发 |
|---|---|---|
| **P-a** | 换模型 | 推荐中有备选卡 → 用户选定 → 替换 model 段 → 重跑 → 对比 |
| **P-b** | 补样本 | 补充实测数据 → import_samples → 重训 → 阈值判定 |
| **P-c** | 混合策略 | 有物理卡 → build_hybrid_recipe（composite/ensemble_moe）→ 重跑 → 对比 |

---

## 核心能力（15 工具 MCP 面）

| # | 工具 | 用途 |
|---|---|---|
| 1 | `list_builtin_datasets` | 列出内置数据集 |
| 2 | `profile_dataset` | 数据体检（质量 flag、信号画像） |
| 3 | `list_model_cards` | 模型卡列表（可按 task/device 过滤） |
| 4 | `recommend_models` | 规则化推荐（top-1 + ≤2 备选 + 机器理由） |
| 5 | `assemble_recipe` | 从意图装配 TaskRecipe |
| 6 | `validate_recipe` | 配方校验（结构 + 语义双层） |
| 7 | `run_task` | 异步执行（支持 force_new 重试语义） |
| 8 | `get_run_status` | 运行状态查询 |
| 9 | `cancel_run` | 中断运行 |
| 10 | `get_report` | 获取报告（含 lay_terms 通俗层） |
| 11 | `compare_reports` | 新旧报告对比 |
| 12 | `import_samples` | 补样本导入（append 幂等） |
| 13 | `build_hybrid_recipe` | 混合策略配方构建 |
| 14 | `simulate_dataset` | 合成数据生成 |
| 15 | `list_runs` | 运行历史索引 |

---

## 内置数据集

| 数据集 | 行数 | 设备 | 通道 |
|---|---|---|---|
| `battery_run1` | 353 | 电池 | time, current, voltage, temperature, eod_state |
| `pump_run1` | 240 | 泵 | time + 8 输入 + 4 输出 + 4 状态 |

数据集由 progpy 物理模型合成固化（License 干净，无 NASA 数据分发）。

---

## 模型卡（18 卡注册表）

| 族 | 数量 | 典型卡 |
|---|---|---|
| physics | 6 | BatteryElectroChemEODEOL, CentrifugalPumpWithWear |
| datadriven | 3 | LSTM, DMD |
| anomaly | 4 | SigmaRule, PCADistance, Mahalanobis, RollingResidual |
| hybrid | 3 | composite, ensemble_moe, surrogate_from_physics |
| estimator | 2 | KF, UKF, ParticleFilter |
| predictor | 2 | MonteCarlo, UnscentedTransform |

**能力扩展**：第三方卡经 `ifppbot.cards` entry points 装载，extras 未装时可见但推荐降权。

---

## 配置

### Agent 配置（config.toml）

| 段 | 字段 | 说明 |
|---|---|---|
| `[server]` | host, port, mode, token | 服务监听与鉴权 |
| `[llm]` | provider, base_url, model, api_key_ref | LLM 端点（本地/云端统一入口） |
| `[core]` | mcp (stdio/http), pythonPath/httpUrl | core 连接方式 |
| `[feedback]` | quality_threshold | P-b 阈值判定 |
| `[polling]` | interval_ms, timeout_ms | 轮询间隔 |

### UI 开发代理

UI 的 `vite.config.ts` 已配置 `/api` 代理到 `http://127.0.0.1:8765`（含 WS）。

---

## 测试

### 核心测试
```bash
.venv\Scripts\python.exe -m pytest packages/core -q
# 178 tests, all green
```

### Agent 测试
```bash
cd packages/agent
npm test
# 113 tests, all green
```

### UI 构建
```bash
cd packages/ui
npm run build
# dist/ 产出可在任意静态目录使用
```

### 冒烟
```bash
.venv\Scripts\python.exe -m ifppbot smoke
# 4 条黄金路径 + 基线带宽断言
```

---

## 安全边界

- 工具面白名单硬编码 15 个，清单外一律拒绝并记审计
- 工件 URI 文法校验（kind 白名单、路径穿越拒绝、根目录锁死 workspace）
- 密钥 redact：日志/事件/错误信封三处擦除
- remote 模式 Bearer Token 鉴权（本机豁免）
- 拒答路径：修改系统/执行命令/编辑代码 → 固定拒答 + 公开渠道指引

---

## 技术约束

- Python ≥ 3.12，ProgPy 1.9.x（vendored，零修改）
- Node ≥ 20 LTS，TypeScript 5.x strict
- 缺省安装不含重型能力库（pyod/bibmon/ceruleo/basicts 为可选 extras）
- 无 ORM、无任务队列、无外部数据库服务
- 数据不出厂：core 无网络出站调用

---

## 项目结构

```
D:\codes\ifppbot\
├── .kiro\specs\           # Kiro spec（core/agent/ui 三份）
├── .github\workflows\     # CI 工作流
├── docs\new_design2\      # 设计文档
├── packages\
│   ├── core\              # Python 内核（178 测试）
│   │   ├── src\ifppbot\
│   │   │   ├── errors.py  workspace.py  ingest.py
│   │   │   ├── registry.py recipe.py  intent.py
│   │   │   ├── pipeline.py hybrid.py  simulate.py
│   │   │   ├── anomaly.py  report.py  mcp/
│   │   │   ├── smoke.py  __main__.py
│   │   │   ├── packs/     # 设备域示例
│   │   │   └── data/      # 内置数据集 + 基线
│   │   └── tests\          # pytest
│   ├── agent\             # TS 助手（113 测试）
│   │   ├── src\
│   │   │   ├── config.ts  schemas/  pi-adapter/
│   │   │   ├── mcp-client.ts  artifacts.ts
│   │   │   ├── session.ts  wizard.ts  orchestrator.ts
│   │   │   ├── security.ts  api/  index.ts
│   │   ├── skills/        # PHM 领域 skills ×5
│   │   ├── prompts-gen/   # LayTerms 构建脚本
│   │   └── test/
│   └── ui\                # Vite+React
│       ├── src\
│       │   ├── tokens/  common/  i18n/  client/
│       │   ├── views/  main.tsx
│       └── dist/          # 构建产物
├── progpy\                # vendored ProgPy 1.9.0
└── .venv\                 # Python 虚拟环境
```