Windows 监控管理系统接口说明

基础信息

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

仪表盘

获取仪表盘概览

GET /api/dashboard

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

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

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

{
  "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

{
  "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}

{
  "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

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

更新 AI 模型

PATCH /api/ai/models/{model_id}

{
  "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

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

{
  "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

等价于执行：

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 返回的设备和类型执行：

smartctl -a -d sat /dev/sdb

JMB39x 阵列会按槽位执行：

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}

请求体：

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

批量更新服务状态

PATCH /api/services/batch

请求体：

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

根据 AI JSON 批量更新服务

POST /api/services/import-ai

请求体：

{
  "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

{
  "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

请求体：

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

说明：

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

更新服务标签

PUT /api/services/{service_id}/tags

{
  "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}

请求体：

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

批量更新进程状态

PATCH /api/processes/batch

请求体：

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

根据 AI JSON 批量更新进程

POST /api/processes/import-ai

请求体：

{
  "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

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

说明：

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

生成进程 AI 分析提示词

POST /api/processes/ai-prompt

请求体：

{
  "scope": "pending"
}

返回 prompt_text、markdown_table 和 items。

更新进程标签

PUT /api/processes/{process_id}/tags

{
  "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

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

重启

POST /api/automation/power/restart

请求体同关机接口。

取消已排程关机或重启

POST /api/automation/power/cancel

启动程序

POST /api/automation/programs/start

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

关闭程序

POST /api/automation/programs/stop

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

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

屏幕截图

POST /api/automation/screenshot

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

鼠标操作

POST /api/automation/mouse

{
  "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

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

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

AI 视觉分析当前界面

POST /api/automation/vision/analyze

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

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

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

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

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

定位单个可操作元素

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

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

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

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

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

截取当前屏幕

POST /api/automation/vision/screenshot

{
  "save": true
}

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

高层自动化动作接口

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

POST /api/automation/actions/mouse

{
  "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

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

POST /api/automation/actions/text-input

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

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

POST /api/automation/actions/start-program

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

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

{
  "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 草稿。

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

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

POST /api/automation/workflows/plan/continue

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

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

POST /api/automation/workflows

{
  "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"
    }
  ]
}

输入值支持四种来源：

{ "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

{
  "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，并在请求头携带：

X-Automation-Token: your-remote-token

请求体与按 ID 执行一致：

{
  "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 可以使用已有标签，也可以在确有必要时返回新的短标签名称；导入时不存在的标签会自动新增。

api-docs.md 22 KB Verlauf Originalformat

Windows 监控管理系统接口说明

基础信息

仪表盘

获取仪表盘概览

标签

查询标签

新增标签

更新标签

删除标签

AI 配置与调用

系统设置

查询系统设置

更新系统设置

查询 AI 服务商

新增 AI 服务商

更新 AI 服务商

删除 AI 服务商

查询 AI 模型

新增 AI 模型

更新 AI 模型

删除 AI 模型

测试 AI 服务

扫描

执行完整扫描

查询扫描历史

查询扫描详情

传感器

获取实时传感器信息

硬盘 SMART

扫描 smartctl 设备列表

获取全部硬盘 SMART 信息

获取单个设备 SMART 信息

Windows 服务

查询服务列表

获取服务详情

更新服务说明和状态

批量更新服务状态

根据 AI JSON 批量更新服务

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

生成服务 AI 分析提示词

更新服务标签

启动服务

停止服务

重新启动服务

Windows 进程

查询进程列表

获取进程详情

更新进程说明和状态

批量更新进程状态

根据 AI JSON 批量更新进程

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

生成进程 AI 分析提示词

更新进程标签

启动进程

停止进程

Windows 自动化

关机

重启

取消已排程关机或重启

启动程序

关闭程序

屏幕截图

鼠标操作

键盘操作

AI 视觉分析当前界面

定位单个可操作元素

截取当前屏幕

高层自动化动作接口

自动化工作流

已识别界面

自动化错误记录

AI 提示词中的标签信息

api-docs.md 22 KB

Verlauf Originalformat