pigway-console-adapter-frame-flow/README.zh-CN.md

<p><img src="docs/brand/pigway-logo.png" alt="PIGWay" width="96" height="96"></p>

# PIGWay Console Adapter — Frame Flow

简体中文 | [English](README.md)

独立 ZIP 插件 `pigway-frame-flow` v1.0.5，采用现有 Console adapter protocol v1，仅依赖 Python 标准库。源码在独立仓库 `pigway-console-adapter-frame-flow` 维护，无需修改 Console 核心或部署额外服务。

## 安装

1. 在 Console「机器管理」上传 `dist/pigway-frame-flow-1.0.5.zip`，启用插件。
2. 添加设备，选择 PIGWay Frame Flow，填写 Console 能访问的 Frame Flow HTTP(S) 根地址（不含 `/api/v1`）和 **Frame Flow API 令牌**，不是 KoKonna Key 或网页登录密码。
3. 若使用受限 API 客户端，授予 `devices:read`、`jobs:read`；默认 `FRAME_FLOW_TOKEN` 也可使用。令牌保存于 Console 敏感字段。跨不可信网络使用 HTTPS。
4. 查看通用资源看板、告警与历史；默认每 60 秒采集一次。卡片和告警随 Console 中英文切换，资源显示 API 上报名称或 Console 中设置的显示名称。

采集 `/health`、`/ready`、`/api/v1/devices`、`/api/v1/jobs`，不发送写请求、不刷新画框、不执行任务。设备接口可能按 Frame Flow 现有缓存规则查询厂商只读状态。

服务：就绪状态、设备数、任务数。画框：在线状态、可用时的电量。任务：启用状态和最近终态结果。`FAILED` 与 `UNKNOWN` 分别告警；未运行或执行中不当作成功。停用任务仍显示其最近失败，成功后恢复。设备离线、服务未就绪分别告警。

`/ready` 的 HTTP 503 作为未就绪状态采集；认证、超时、格式错误或其他采集失败交给 Console 保留旧快照并标记未更新，不伪造离线和零值。完整成功快照才确认告警恢复。历史从安装后的采样开始；设备指标是读取时观察到的 API 状态，不证明物理屏幕已刷新。Mock 服务返回的也是 Mock 设备状态。

## 本地验证与打包

在本仓库根目录执行（运行插件无需安装第三方依赖）：

```sh
python3 -m venv .venv
.venv/bin/python -m pip install pytest ruff
.venv/bin/python -m pytest -q
mkdir -p dist
.venv/bin/python package.py plugin dist/pigway-frame-flow-1.0.5.zip
```

开发时可将 `PIGWAY_ADAPTER_PATH` 指向本目录 `plugin` 的绝对路径。ZIP 安装默认停用；生产安装与设备登记需在 Console 中执行。本地验证覆盖模拟接口、RPC 和隔离安装。

Frame Flow API 契约测试为可选集成验证，需要另行安装 Frame Flow 及其依赖。例如相邻项目保留现有虚拟环境时，执行 `PYTHONPATH=../pigway-frame-flow ../pigway-frame-flow/.venv/bin/python -m pytest -q`。独立环境未安装 Frame Flow 时跳过该项，其余测试正常运行。

历史页的新增指标译名需 Console 配套支持（生产已安装）。仅安装插件也可正常采集并显示双语概览卡片。浏览器测试：安装 Playwright 后执行 `node tests/ui.cjs`。

[文档目录](docs/README.md)

系统配置 → 选择 Frame Flow → Frame Flow 接入，可修改服务地址、API 令牌和管理入口。首页标题旁的链接默认打开服务地址；管理入口可单独设置，令牌留空保留现有值。