# Windows 监控管理系统接口说明

## 基础信息

- 后端默认地址：`http://127.0.0.1:8000`
- 返回格式：JSON
- 确认状态枚举：`PENDING`、`TRUSTED`、`SUSPICIOUS`、`IGNORED`、`NEED_MORE_INFO`
- AI 风险等级枚举：`LOW`、`MEDIUM`、`HIGH`

## 仪表盘

### 获取仪表盘概览

`GET /api/dashboard`

返回最近扫描记录、服务总数、进程总数、待确认数量、本次未出现数量。

## 标签

系统内置两个默认标签：

| 标签 | 默认是否可以被控制 | 说明 |
| --- | --- | --- |
| windows系统 | 否 | 用于标记 Windows 系统原生服务或进程 |
| 本系统相关 | 否 | 用于标记本项目自身相关服务或进程 |

如果服务或进程存在任一 `is_controllable = false` 的标签，前端不会显示启动、停止、重启等控制操作，后端控制接口也会拒绝执行。

### 查询标签

`GET /api/tags`

### 新增标签

`POST /api/tags`

```json
{
  "name": "业务软件",
  "description": "业务系统相关组件",
  "is_controllable": true
}
```

### 更新标签

`PATCH /api/tags/{tag_id}`

```json
{
  "name": "windows系统",
  "description": "Windows 系统原生服务或进程",
  "is_controllable": false
}
```

### 删除标签

`DELETE /api/tags/{tag_id}`

内置标签不可删除。

## AI 配置与调用

AI 模块分为项目内部统一 AI 服务层和具体供应商 API 对接层。当前支持：

| 类型 | 说明 |
| --- | --- |
| OPENAI | OpenAI Chat Completions API，默认 Base URL 为 `https://api.openai.com/v1` |
| OPENAI_COMPATIBLE | OpenAI 兼容格式 API，适用于 LM Studio、本地模型服务或其他兼容服务 |
| GOOGLE_GEMINI | Google Gemini Generate Content API，默认 Base URL 为 `https://generativelanguage.googleapis.com/v1beta` |

服务商 API Key 可为空，接口返回时只返回 `api_key_set`，不会返回明文 Key。

## 系统设置

### 查询系统设置

`GET /api/settings`

返回全局默认 AI 服务商、模型、温度，以及自动化文件保存相对路径。

### 更新系统设置

`PUT /api/settings`

```json
{
  "default_ai_provider_id": 1,
  "default_ai_model_id": 1,
  "default_ai_temperature": 0.1,
  "automation_file_root": "automation",
  "automation_screen_path": "automation/screens",
  "automation_error_path": "automation/errors",
  "automation_runtime_path": "automation/runtime",
  "automation_auto_screenshot_enabled": false,
  "automation_auto_screenshot_interval": 30,
  "automation_remote_token": "your-remote-token"
}
```

路径必须是相对路径，后端会解析到 `backend/data` 目录下。`automation_remote_token` 用于按 key 远程执行工作流，远程调用时通过 `X-Automation-Token` 请求头传入。

### 查询 AI 服务商

`GET /api/ai/providers`

### 新增 AI 服务商

`POST /api/ai/providers`

```json
{
  "name": "本地 LM Studio",
  "provider_type": "OPENAI_COMPATIBLE",
  "base_url": "http://127.0.0.1:1234/v1",
  "api_key": "",
  "enabled": true
}
```

### 更新 AI 服务商

`PATCH /api/ai/providers/{provider_id}`

```json
{
  "name": "OpenAI",
  "provider_type": "OPENAI",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-xxxx",
  "clear_api_key": false,
  "enabled": true
}
```

说明：编辑时 `api_key` 留空表示不修改原 Key；`clear_api_key = true` 表示清空原 Key。

### 删除 AI 服务商

`DELETE /api/ai/providers/{provider_id}`

会级联删除该服务商下的模型配置。

### 查询 AI 模型

`GET /api/ai/models?provider_id=1`

`provider_id` 可选；不传时返回全部模型。

### 新增 AI 模型

`POST /api/ai/models`

```json
{
  "provider_id": 1,
  "name": "gpt-4o-mini",
  "display_name": "GPT-4o mini",
  "is_default": true
}
```

### 更新 AI 模型

`PATCH /api/ai/models/{model_id}`

```json
{
  "provider_id": 1,
  "name": "gemini-1.5-flash",
  "display_name": "Gemini Flash",
  "is_default": true
}
```

同一服务商只能有一个默认模型。设置新的默认模型后，同服务商其他模型会自动取消默认。

### 删除 AI 模型

`DELETE /api/ai/models/{model_id}`

### 测试 AI 服务

`POST /api/ai/test`

```json
{
  "provider_id": 1,
  "model_id": 1,
  "prompt": "请用一句话回答：你已经可以连接了吗？",
  "temperature": 0.2
}
```

返回：

```json
{
  "provider": {},
  "model": {},
  "content": "AI 输出文本",
  "raw_response": {}
}
```

## 扫描

### 执行完整扫描

`POST /api/scans/run`

执行 Windows 服务和进程采集，写入扫描记录，并按业务规则更新 `is_present_now`、`last_seen_at`、运行状态等字段。

### 查询扫描历史

`GET /api/scans?page=1&page_size=20`

### 查询扫描详情

`GET /api/scans/{scan_id}`

## 传感器

### 获取实时传感器信息

`GET /api/sensors`

说明：

- 数据不写入数据库。
- CPU、内存负载来自 `psutil`。
- 显卡优先使用 `nvidia-smi`；如果不可用，尝试 Windows GPU 性能计数器。
- 温度优先读取 LibreHardwareMonitor/OpenHardwareMonitor WMI，其次尝试 `psutil` 和 ACPI 热区。
- Windows 原生接口不一定能提供 CPU/GPU 真实温度，实际可见字段取决于硬件、驱动和监控组件。

返回主要字段：

| 字段 | 说明 |
| --- | --- |
| collected_at | 采集时间 |
| cpu | CPU 总负载、每核心负载、核心数、频率 |
| memory | 物理内存和交换区使用情况 |
| gpu | 显卡负载、温度、显存、功耗等 |
| temperatures | psutil/ACPI 温度 |
| hardware_sensors | LibreHardwareMonitor/OpenHardwareMonitor 传感器 |

## 硬盘 SMART

### 扫描 smartctl 设备列表

`GET /api/smart/scan`

等价于执行：

```powershell
smartctl --scan
```

### 获取全部硬盘 SMART 信息

`GET /api/smart/devices?include_jmb39x=true&jmb39x_slots=8`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| include_jmb39x | boolean | 是否对 SAT/ATA 类设备额外探测 JMB39x 阵列槽位 |
| jmb39x_slots | integer | 探测槽位数量，范围 0-16，默认 8 |

普通设备会按 `smartctl --scan` 返回的设备和类型执行：

```powershell
smartctl -a -d sat /dev/sdb
```

JMB39x 阵列会按槽位执行：

```powershell
smartctl -a -d jmb39x,0 /dev/sdb
smartctl -a -d jmb39x,1 /dev/sdb
```

返回每块盘的解析摘要、ATA SMART 属性表、警告信息和原始 `smartctl` 输出。

### 获取单个设备 SMART 信息

`GET /api/smart/device?device=/dev/sda&device_type=nvme`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| device | string | 设备路径，例如 `/dev/sda` |
| device_type | string | 可选，smartctl 的 `-d` 类型，例如 `nvme`、`sat`、`jmb39x,0` |

## Windows 服务

### 查询服务列表

`GET /api/services`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| keyword | string | 按名称、显示名称、路径、描述搜索 |
| confirm_status | string | 确认状态 |
| present | boolean | `true` 本次出现，`false` 本次未出现 |
| page | integer | 页码，默认 1 |
| page_size | integer | 每页数量，默认 20，最大 200 |

### 获取服务详情

`GET /api/services/{service_id}`

### 更新服务说明和状态

`PATCH /api/services/{service_id}`

请求体：

```json
{
  "confirm_status": "TRUSTED",
  "user_note": "人工确认说明"
}
```

### 批量更新服务状态

`PATCH /api/services/batch`

请求体：

```json
{
  "ids": [1, 2, 3],
  "confirm_status": "SUSPICIOUS",
  "user_note": "批量标记说明，可为空"
}
```

### 根据 AI JSON 批量更新服务

`POST /api/services/import-ai`

请求体：

```json
{
  "items": [
    {
      "type": "service",
      "name": "WinDefend",
      "description": "Microsoft Defender 防病毒核心服务。",
      "judgement": "TRUSTED",
      "risk_level": "LOW",
      "reason": "Microsoft 官方安全组件。",
      "suggestion": "保持运行。",
      "tags": ["windows系统"]
    }
  ]
}
```

说明：

- `tags` 为可选字段，格式为标签名称数组；老格式不传 `tags` 仍可导入。
- 如果传入 `tags`，后端会将对应服务的标签替换为该数组。
- 数据库中不存在的标签会自动创建，默认 `is_controllable = true`、`is_builtin = false`。

### 调用 AI 分析服务并返回待确认结果

`POST /api/services/analyze-ai`

```json
{
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.2,
  "scope": "selected",
  "ids": [1, 2]
}
```

说明：

- 后端会复用服务 AI 提示词模板，调用配置的 AI 服务商和模型。
- 接口只返回 AI 输出解析结果和更新预览，不直接写入数据库。
- 前端确认后继续调用 `/api/services/import-ai` 入库。

返回主要字段：

| 字段 | 说明 |
| --- | --- |
| items | 解析后的 AI JSON 数组 |
| preview | 当前数据库值与 AI 建议值的对比 |
| raw_output | AI 原始输出文本 |
| provider | 本次使用的服务商信息 |
| model | 本次使用的模型信息 |
| prompt_text | 本次发送给 AI 的提示词 |
| markdown_table | 人工核对表 |

### 生成服务 AI 分析提示词

`POST /api/services/ai-prompt`

请求体：

```json
{
  "scope": "selected",
  "ids": [1, 2]
}
```

说明：

- `scope = selected` 时使用 `ids` 指定的服务。
- `scope = pending` 时忽略 `ids`，生成全部待确认服务的提示词。
- 返回 `prompt_text`、`markdown_table` 和 `items`。

### 更新服务标签

`PUT /api/services/{service_id}/tags`

```json
{
  "tag_ids": [1, 2]
}
```

### 启动服务

`POST /api/services/{service_id}/start`

### 停止服务

`POST /api/services/{service_id}/stop`

### 重新启动服务

`POST /api/services/{service_id}/restart`

控制规则：

- `confirm_status` 必须是 `TRUSTED`、`SUSPICIOUS` 或 `IGNORED`。
- `PENDING` 和 `NEED_MORE_INFO` 不允许控制。
- 任一关联标签 `is_controllable = false` 时不允许控制。
- 服务必须在最近一次扫描中仍然存在。

## Windows 进程

### 查询进程列表

`GET /api/processes`

查询参数：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| keyword | string | 按名称、路径、命令行、用户搜索 |
| confirm_status | string | 确认状态 |
| present | boolean | `true` 本次出现，`false` 本次未出现 |
| page | integer | 页码，默认 1 |
| page_size | integer | 每页数量，默认 20，最大 200 |

### 获取进程详情

`GET /api/processes/{process_id}`

### 更新进程说明和状态

`PATCH /api/processes/{process_id}`

请求体：

```json
{
  "confirm_status": "SUSPICIOUS",
  "user_note": "人工确认说明"
}
```

### 批量更新进程状态

`PATCH /api/processes/batch`

请求体：

```json
{
  "ids": [10, 11],
  "confirm_status": "IGNORED",
  "user_note": "批量忽略说明，可为空"
}
```

### 根据 AI JSON 批量更新进程

`POST /api/processes/import-ai`

请求体：

```json
{
  "items": [
    {
      "type": "process",
      "name": "unknown.exe",
      "description": "未知用途执行文件。",
      "judgement": "SUSPICIOUS",
      "risk_level": "HIGH",
      "reason": "路径和命令行异常。",
      "suggestion": "建议隔离并检查哈希和网络连接。",
      "tags": ["可疑程序"]
    }
  ]
}
```

说明：

- `tags` 为可选字段，格式为标签名称数组；老格式不传 `tags` 仍可导入。
- 如果传入 `tags`，后端会将对应进程的标签替换为该数组。
- 数据库中不存在的标签会自动创建，默认 `is_controllable = true`、`is_builtin = false`。

### 调用 AI 分析进程并返回待确认结果

`POST /api/processes/analyze-ai`

```json
{
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.2,
  "scope": "pending"
}
```

说明：

- 后端会复用进程 AI 提示词模板，调用配置的 AI 服务商和模型。
- 接口只返回 AI 输出解析结果和更新预览，不直接写入数据库。
- 前端确认后继续调用 `/api/processes/import-ai` 入库。

### 生成进程 AI 分析提示词

`POST /api/processes/ai-prompt`

请求体：

```json
{
  "scope": "pending"
}
```

返回 `prompt_text`、`markdown_table` 和 `items`。

### 更新进程标签

`PUT /api/processes/{process_id}/tags`

```json
{
  "tag_ids": [2]
}
```

### 启动进程

`POST /api/processes/{process_id}/start`

使用数据库中记录的 `cmdline` 或 `exe_path` 重新启动进程。

### 停止进程

`POST /api/processes/{process_id}/stop`

使用数据库中记录的 `last_pid` 停止进程，并校验当前 PID 的进程名与记录一致，避免误杀 PID 复用后的其他进程。

控制规则：

- `confirm_status` 必须是 `TRUSTED`、`SUSPICIOUS` 或 `IGNORED`。
- `PENDING` 和 `NEED_MORE_INFO` 不允许控制。
- 任一关联标签 `is_controllable = false` 时不允许控制。
- 停止进程要求该进程在最近一次扫描中仍然存在。

## Windows 自动化

自动化接口用于后续复杂本机操作编排。关机、重启、鼠标和键盘操作会直接影响当前 Windows 桌面环境，调用前应由上层业务明确确认。

### 关机

`POST /api/automation/power/shutdown`

```json
{
  "delay_seconds": 60,
  "force": false,
  "reason": "计划关机"
}
```

### 重启

`POST /api/automation/power/restart`

请求体同关机接口。

### 取消已排程关机或重启

`POST /api/automation/power/cancel`

### 启动程序

`POST /api/automation/programs/start`

```json
{
  "command": "notepad.exe",
  "cwd": null,
  "shell": true
}
```

### 关闭程序

`POST /api/automation/programs/stop`

```json
{
  "pid": 1234,
  "name": null,
  "timeout_seconds": 8,
  "kill_after_timeout": true
}
```

说明：`pid` 和 `name` 至少传一个；按名称关闭时会匹配同名进程。

### 屏幕截图

`POST /api/automation/screenshot`

```json
{
  "save_path": "C:/Temp/screen.png",
  "include_base64": true
}
```

### 鼠标操作

`POST /api/automation/mouse`

```json
{
  "action": "click",
  "x": 100,
  "y": 200,
  "button": "left",
  "clicks": 1,
  "duration": 0,
  "amount": 0
}
```

`action` 支持：`move_to`、`move_rel`、`click`、`double_click`、`right_click`、`drag_to`、`scroll`。

### 键盘操作

`POST /api/automation/keyboard`

```json
{
  "action": "hotkey",
  "keys": ["ctrl", "s"],
  "interval": 0
}
```

`action` 支持：`press`、`hotkey`、`write`、`key_down`、`key_up`。

### AI 视觉分析当前界面

`POST /api/automation/vision/analyze`

```json
{
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.1
}
```

后端会截取当前 Windows 屏幕，调用支持视觉输入的 AI 模型识别界面名称、描述、是否为 Windows 桌面、是否为浏览器网页，以及可操作元素列表。

可操作元素在该步骤只要求返回：

```json
{
  "name": "保存按钮",
  "approximate_location": "窗口右下角"
}
```

该步骤不要求 AI 返回元素坐标。坐标需要通过单个元素定位接口按需获取。

### 定位单个可操作元素

`POST /api/automation/screens/{screen_id}/elements/{element_id}/locate`

```json
{
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.1
}
```

后端会把保存的界面截图和该元素的名称、大致位置描述发送给 AI，只定位这一个元素。AI 应返回：

```json
{
  "has_element": true,
  "x_percent": 42.5,
  "y_percent": 68.2,
  "reason": "目标按钮位于窗口右下区域"
}
```

当 `has_element = true` 时，后端会按原始截图分辨率换算像素坐标并更新该元素记录；前端随后才会在截图上绘制坐标点。

### 截取当前屏幕

`POST /api/automation/vision/screenshot`

```json
{
  "save": true
}
```

只截屏并返回图片，不进行 AI 分析。自动化操作页面的手动截屏和自动截屏使用该接口。

### 高层自动化动作接口

以下接口会在动作执行前获取一次当前进程列表，执行后再次获取并对比新增进程。若请求携带 `screen_id`，后端会先截图当前屏幕，并把当前截图和数据库中保存的目标界面截图发送给 AI 做界面对比；不匹配时会写入自动化错误记录并终止动作。

`POST /api/automation/actions/mouse`

```json
{
  "screen_id": 1,
  "provider_id": 1,
  "model_id": 1,
  "temperature": 0.1,
  "x": 420,
  "y": 260,
  "mouse_action": "click"
}
```

`mouse_action` 支持：`click`、`right_click`、`double_click`。

`POST /api/automation/actions/keyboard`

```json
{
  "screen_id": 1,
  "provider_id": 1,
  "model_id": 1,
  "keys": ["ctrl", "s"]
}
```

`POST /api/automation/actions/text-input`

```json
{
  "screen_id": 1,
  "provider_id": 1,
  "model_id": 1,
  "text": "要输入的中文文本"
}
```

文本输入使用剪贴板粘贴，避免中文直接按键模拟不稳定。

`POST /api/automation/actions/start-program`

```json
{
  "command": "msedge",
  "cwd": null,
  "shell": true
}
```

`POST /api/automation/actions/close-opened-programs`

```json
{
  "pids": [1234, 5678]
}
```

如果不传 `pids`，后端会尝试关闭当前后端进程内记录的自动化新增进程。

### 自动化工作流

`GET /api/automation/workflows`

返回工作流列表，包含 `schema_version`、`node_count`、`edge_count`。

`GET /api/automation/workflow-nodes`

返回后端注册的节点定义，前端可据此生成节点库和参数表单。每个节点包含 `type`、`category`、`label`、`params`、`inputs`、`outputs`、`control_ports`。

常用节点示例：`browser.open_url` 打开网页，`wait.seconds` 等待，`mouse.double_click` 双击坐标，`text.input` 输入文本。

`POST /api/automation/workflows/plan`

根据用户需求调用 AI 生成 `workflow/v1` 草稿。

```json
{
  "requirement": "打开记事本并输入 hello",
  "provider_id": null,
  "model_id": null,
  "temperature": null
}
```

返回：

```json
{
  "session_id": "uuid",
  "plan": {
    "summary": "计划摘要",
    "questions": [],
    "workflow": {
      "schema_version": "workflow/v1",
      "name": "示例",
      "nodes": [],
      "edges": []
    }
  },
  "ai_raw_content": "..."
}
```

`POST /api/automation/workflows/plan/continue`

继续一次 AI 工作流规划对话。

```json
{
  "session_id": "uuid",
  "user_message": "补充说明",
  "provider_id": null,
  "model_id": null,
  "temperature": null
}
```

`POST /api/automation/workflows`

```json
{
  "schema_version": "workflow/v1",
  "workflow_key": "browser-click-demo",
  "name": "打开浏览器并点击",
  "description": "示例工作流",
  "variables": {
    "target_text": {
      "type": "string",
      "default": "hello"
    }
  },
  "settings": {
    "max_steps": 100,
    "default_timeout_ms": 30000,
    "on_unhandled_error": "pause_for_user"
  },
  "nodes": [
    {
      "id": "start_1",
      "type": "flow.start",
      "title": "开始",
      "position": { "x": 80, "y": 120 },
      "params": {},
      "inputs": {}
    },
    {
      "id": "program_1",
      "type": "program.start",
      "title": "启动 Edge",
      "position": { "x": 320, "y": 120 },
      "params": { "command": "msedge", "shell": true },
      "inputs": {}
    },
    {
      "id": "mouse_1",
      "type": "mouse.click",
      "title": "点击按钮",
      "position": { "x": 560, "y": 120 },
      "params": { "button": "left", "clicks": 1 },
      "inputs": {
        "x": { "source": "literal", "value": 420 },
        "y": { "source": "literal", "value": 260 }
      }
    }
  ],
  "edges": [
    {
      "id": "edge_1",
      "kind": "control",
      "source": "start_1",
      "source_port": "next",
      "target": "program_1",
      "target_port": "run"
    },
    {
      "id": "edge_2",
      "kind": "control",
      "source": "program_1",
      "source_port": "success",
      "target": "mouse_1",
      "target_port": "run"
    }
  ]
}
```

输入值支持四种来源：

```json
{ "source": "literal", "value": 100 }
{ "source": "variable", "name": "target_text" }
{ "source": "node_output", "node_id": "locate_1", "output": "x" }
{ "source": "runtime", "name": "current_screenshot_path" }
```

连线 `kind` 分为 `control` 和 `data`。`control` 决定执行顺序，`data` 把源节点输出写入目标节点输入。完整格式见 `workflow-format.md`。

`GET /api/automation/workflows/{workflow_id}`

`GET /api/automation/workflows/by-key/{workflow_key}`

`POST /api/automation/workflows/{workflow_id}/run`

```json
{
  "provider_id": null,
  "model_id": null,
  "temperature": null,
  "variables": {
    "target_text": "本次运行覆盖值"
  }
}
```

如果不传 AI 参数，后端会使用系统设置中的默认 AI 服务商、模型和温度。后端会从 `flow.start` 或没有入边的节点开始，沿 `control` 连线执行。节点输出会写入运行上下文，供后续节点通过 `node_output` 或 `data` 连线读取。节点失败时，返回项会尽量包含 `artifacts.screenshot_path`，用于前端展示失败截图并继续询问用户。

`POST /api/automation/workflows/by-key/{workflow_key}/run`

按稳定 key 远程执行工作流。该接口必须先在系统设置中配置 `automation_remote_token`，并在请求头携带：

```text
X-Automation-Token: your-remote-token
```

请求体与按 ID 执行一致：

```json
{
  "variables": {
    "channel_url": "https://tv.cctv.com/live/cctv5"
  }
}
```

`PUT /api/automation/workflows/{workflow_id}`

`DELETE /api/automation/workflows/{workflow_id}`

### 已识别界面

`GET /api/automation/screens`

`GET /api/automation/screens/{screen_id}?include_image=true`

`DELETE /api/automation/screens/{screen_id}`

### 自动化错误记录

`GET /api/automation/errors`

`GET /api/automation/errors/{error_id}?include_images=true`

## AI 提示词中的标签信息

服务和进程的 AI 提示词会包含：

- 每个待分析对象的 `tags` 字段。
- 系统中已有标签列表，包括 `name`、`description`、`is_controllable`。
- 标签判断要求：AI 需要结合已有标签进行分析，并在输出对象的 `tags` 字段中返回建议绑定的标签名称数组。
- AI 可以使用已有标签，也可以在确有必要时返回新的短标签名称；导入时不存在的标签会自动新增。