兼容与公共接口

Komari Lite 的内部数据库会继续演进，主题和外部集成应使用公共 API 或 RPC，不应读取数据库表。

兼容原则

• 旧字段能明确映射时保留字段名，返回新版统一口径。
• 新字段不会改变原有字段的类型。
• 公共接口缺失或权限不足时，主题应显示可理解的空状态。
• 管理接口必须保持登录与权限校验，不能为了主题兼容开放内部数据。

实时状态

公共 WebSocket 和 common:getNodesLatestStatus 返回服务器最新状态。当前周期校准后的上传与下载、国家/地区和本周期有效额度会在服务端统一映射，主题不需要了解内部迁移表。

流量口径

第三方主题应区分：

• 当前周期校准后的生效上传与下载。
• 当前统计方式计算出的用量。
• 本周期有效额度。
• 计费节点筛选结果。

公共接口中的现有上传、下载字段已经包含当前周期生效的校准结果。主题不应读取内部校准记录后再次叠加，也不应把“额度追加”当作实际用量。未设置价格的节点不要擅自纳入计费汇总。

流量校准只修正当前计费周期的有效用量，不会改写 Agent 原始累计计数。需要展示服务商计费进度、当前用量或告警状态时，应直接使用公共接口返回值，确保与仪表盘和报告一致。

历史接口

历史指标经过分层存储后，接口仍按请求时间范围返回可用精度。主题不应假设所有时间范围都存在原始秒级点，也不应依赖每个指标拥有完全相同的采样间隔。

2.2.1 会在服务端把可共享条件的多指标、多节点查询合并为批量扫描。这项优化不改变公共接口的 JSON 字段、层级、数据类型、点顺序、标签、点数限制、空数据填充和可见节点过滤，现有主题不需要为批量引擎单独适配。

仪表盘跳转属于另一项显式能力。主题可以在 komari-theme.json 中声明服务器详情、网络总览和 Ping 任务参数；未声明时使用兼容回退。具体格式见 主题开发指南。

版本探测

遇到不同版本接口差异时，可以按能力判断接口是否存在，但应集中在单一适配层中，避免每个组件各自维护 try/catch 和回退分支。

安全边界

Agent Token、管理员会话、2FA 验证结果、备份和私钥路径都不是主题公共数据。任何需要管理员权限的功能都必须走受保护的管理接口。