Skip to main content

wist_api/status/
v1.rs

1//! `agent/status` seam —— **v1** 基线。
2//!
3//! agentd 周期性上报自身状态(CPU/内存/工作状态/发现策略版本/证书状态/机器画像…),网关收下并落库。
4//! 冻结基线:只做**加性**兼容不动它;需要非加性变更就新开 `v2`。
5//! 约定见 `wist-design/doc/design/foundation/api-seam-inventory.md` §7。
6
7use serde::{Deserialize, Serialize};
8
9use wist_contracts::capability_report::{InvestigationCapabilities, LogsCapabilities};
10
11use super::{AgentLocalWork, AgentUplinkState, HostProfile};
12
13/// 本版本的线上版本号(与路由 `/api/v1/…` 一致)。
14pub const API_VERSION: &str = wist_contracts::API_VERSION_V1;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "snake_case")]
18pub enum AgentWorkState {
19    Paused,
20    Resumed,
21}
22
23/// 工作状态变化(非告警、非失败):暂停/恢复各上报一次。
24#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
25#[serde(deny_unknown_fields)]
26pub struct AgentWorkStateChange {
27    pub input_id: String,
28    pub state: AgentWorkState,
29    pub reason: String,
30    pub at: String,
31}
32
33#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
34#[serde(deny_unknown_fields)]
35pub struct AgentStatusReport {
36    pub agent_id: String,
37    pub instance_id: String,
38    pub version: String,
39    /// Own resident-set size in bytes reported by the agent.
40    #[serde(default)]
41    pub memory_bytes: Option<u64>,
42    /// Agent 进程自身 CPU 占用,**单核口径**(100% = 占满一个核;多线程进程可 >100)。
43    ///
44    /// 它只统计 agent 进程**自己**的 CPU 时间(`getrusage(RUSAGE_SELF)`),不含它拉起的子进程。
45    #[serde(default)]
46    pub cpu_percent: Option<f64>,
47    /// Agent 所在机器的**逻辑核数**(`available_parallelism`)。
48    ///
49    /// 为什么必须和 `cpu_percent` 同一份上报带上来:`cpu_percent` 是单核口径,
50    /// 而运维看图时真正常问的是「这台机器被它占了百分之几」——那是 `cpu_percent / 核数`。
51    /// 少了核数,右侧那个数既算不出来、也无法复核(4 核上的 13% 和 64 核上的 13% 完全不是一回事)。
52    ///
53    /// 为什么让 agent 报原始值、而不是它自己算好整机占比:沿用本仓已有的取舍
54    /// (与 `discovery_policy_version`、事实摘要 digest 同理)——agent 只交**原始事实**
55    /// (自己的 CPU 时间、自己的核数),换算只留一处,在网关。agent 自算的派生值
56    /// 一旦算法退化,下游没有任何一层能发现。
57    #[serde(default)]
58    pub cpu_cores: Option<u32>,
59    /// Measured round-trip latency to the admin control plane in milliseconds.
60    #[serde(default)]
61    pub admin_latency_ms: Option<u64>,
62    /// 自上次上报以来的工作状态变化(paused/resumed),非告警、非失败。
63    #[serde(default)]
64    pub work_state_changes: Option<Vec<AgentWorkStateChange>>,
65    /// 本机**实际生效**的发现方向策略版本;`None` = 还没拿到策略表(在用内建默认周期)。
66    ///
67    /// 为什么必须由 agent 上报、而不是网关自己记账:网关知道自己**发布**了哪一版,
68    /// 但不知道某台机器**拉到并应用**了哪一版 —— 拉取可能失败、可能还没到轮询节拍、
69    /// 也可能拿到后被夹取。而运维要回答的正是那句「我改了策略,哪些机器还没生效」。
70    #[serde(default)]
71    pub discovery_policy_version: Option<i64>,
72    /// 本机**工作内容视图**(`state/work.json` 的子集):我手里有哪些工作、各自在采哪些文件、
73    /// 一次性工作做到哪一步。
74    ///
75    /// 为什么必须由 agent 上报:网关知道自己**授权**了什么,但「真的在采哪些文件」只有 agent
76    /// 知道(本机手工加的输入、暂停、某条来源今天接不接得了)。网关侧只存最近一份。
77    /// `None` = 这台 agent 还没报过(旧版本 agent 不发这个字段)。
78    #[serde(default)]
79    pub local_work: Option<AgentLocalWork>,
80    /// 本机**实际生效**的采集输出状态(见 [`AgentUplinkState`])。
81    ///
82    /// 为什么必须由 agent 上报:网关知道自己**下发**了「启用 + 目标」,但不知道 agent
83    /// **生效**成了什么 —— grant 可能还没拉到、可能被本机总闸拦住、可能目标连不上。
84    /// 运维要回答的正是那句「这台为什么不上送」。
85    ///
86    /// `None` = 这台 agent 还没报过(旧版本 agent 不发这个字段)—— 落库后保持上一次的值
87    /// (与 `local_work` 同口径)。
88    #[serde(default)]
89    pub uplink_state: Option<AgentUplinkState>,
90    /// 本机**客户端证书**状态(mTLS);还没有证书时 `None`。
91    ///
92    /// 为什么要 agent 上报:证书与到期时间只有本机知道(服务端在握手期就验完了,
93    /// 而**过期证书根本进不来**);而「哪些机器快到期 / 已过期需重装」正是运维要提前看到的
94    /// (见 `docs/design/agent-identity-mtls.md` §5.5)。
95    ///
96    /// `None` = 这台 agent 还没报过 / 没证书 —— 落库后保持上一次的值(与其他可选字段同口径)。
97    #[serde(default)]
98    pub certificate_status: Option<AgentCertificateStatus>,
99    /// 机器画像(机器名 / `node_id` / `machine_id` / 网卡地址)—— 注册表里「这是哪台机器」的展示来源。
100    ///
101    /// 为什么由状态上报带(而不是只靠注册):**凭证书首触重建**登记时,机器画像全是空的
102    /// (证书只承载稳定身份),原设计指望「后续状态上报补齐」,但那条通道以前没有这些字段 ——
103    /// 于是经证书注册的机器在管理面永远只剩一个 ID。这里把注册时的 `HostProfile` 原样带上。
104    ///
105    /// `None` = 老版本 agentd 没带 —— 落库后保持上一次的值(与 `local_work` / `uplink_state` 同口径)。
106    #[serde(default)]
107    pub machine_profile: Option<HostProfile>,
108    /// 本机**能承接的日志形态 / 导出器**(D7 能力协商)。
109    ///
110    /// 为什么要 agent 报、而不是网关按 `version` 推:版本号只能回答“新旧”,回答不了
111    /// “这一版在**这个环境**里真能不能采”(导出器依赖的二进制可能没装、单层 glob 支持是
112    /// 一个具体能力而不是一个版本)。而回滚场景里最容易出错的就是“新目录 + 回滚后的 agent” ——
113    /// 网关必须看**它自己说了什么**。
114    ///
115    /// `None` = 旧版本 agentd 没报:网关按“未知”处理 —— 依赖新能力(glob / 新导出器)的单元
116    /// **不算可采**,宁可少派也不派下去报 unsupported。
117    #[serde(default)]
118    pub logs_capabilities: Option<LogsCapabilities>,
119    /// 本机**调查能力**(见 [`InvestigationCapabilities`]):能跑哪些调查面、是不是 root。
120    ///
121    /// 为什么要 agent 报、而不是网关按版本推:调查是**一次性只读操作**,网关必须在
122    /// **入队前**就知道这台机器认不认识这个面 —— 否则会把命令发下去换一个 `unsupported`,
123    /// 管理面上只会显示成「命令失败」,而真正原因是「这台机器不会 / 没权限」。
124    ///
125    /// `None` = 旧版本 agentd 没报:网关按「未知」处理 —— **只允许**它自己确认支持的面
126    /// (目前没有),宁可让菜单置灰,也不发一条注定失败的调查。
127    #[serde(default)]
128    pub investigation_capabilities: Option<InvestigationCapabilities>,
129    /// 本机对网关下发的**一次性命令**的处理结果(见 [`AgentCommandAck`])。
130    ///
131    /// 空 = 本次没有要确认的命令,字段不出现。**加性字段**:本结构是
132    /// `deny_unknown_fields`,所以部署顺序必须 **gateway 先于 agentd**(与本文件其它
133    /// 新增字段同一条规则,见 `CHANGELOG` 的升级提示)。
134    #[serde(default, skip_serializing_if = "Vec::is_empty")]
135    pub command_acks: Vec<AgentCommandAck>,
136}
137
138/// agent 本地客户端证书状态(上报给网关,供页面/告警展示)。
139#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
140#[serde(deny_unknown_fields)]
141pub struct AgentCertificateStatus {
142    /// 证书到期时刻(RFC3339)。
143    pub not_after: String,
144    /// 距到期的剩余秒数(已过期为负)。
145    pub remaining_seconds: i64,
146    /// `valid` / `renew_due` / `expired`。
147    pub state: String,
148    /// agent 本机**最近一次续签判定**的结果(§5.5)。
149    ///
150    /// `None` = 老版本 agentd 不发(或本机台账一时读不到)—— 网关落库时**保留上一次的值**
151    /// (与本报告里 `local_work` / `uplink_state` 同一口径)。
152    #[serde(default)]
153    pub last_renewal: Option<AgentCredentialRenewal>,
154}
155
156/// agent 本机**最近一次续签判定**的结果(§5.5)。
157///
158/// 续签是后台动作,**不记录就等于静默**:agentd 把本地台账(`identity/renewal.json`)原样带上来,
159/// 网关只存 / 展示,不重算。与 [`AgentCertificateStatus`] 同口径:`None` = 还没报过。
160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161#[serde(deny_unknown_fields)]
162pub struct AgentCredentialRenewal {
163    /// `not_due` / `renewed` / `failed` / `needs_reinstall` / `revoked`(与 agentd 本地台账同口径)。
164    pub outcome: String,
165    /// 本次判定时刻(RFC3339)。
166    pub checked_at: String,
167    /// 人读细节(失败原因 / 续到了什么时候…);无内容时为空串。
168    pub detail: String,
169    /// 续签后证书的到期时刻(RFC3339);无证书时为空串。
170    pub not_after: String,
171}
172
173/// 状态上报的**回执**。
174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
175#[serde(deny_unknown_fields)]
176pub struct AgentStatusAck {
177    pub agent_id: String,
178    pub instance_id: String,
179    pub acknowledged_at: String,
180    /// 网关下发的待执行命令;没有命令时字段不出现。
181    ///
182    /// 为什么放在回执里:agent 没有入站监听面,状态上报(3s)是唯一由网关**回话**的通道。
183    /// 这里放的是**通用命令信封**(`kind` + 可选参数),而不是每条命令一个字段 ——
184    /// 新增一种命令只加一个 kind 词表值,不再改报文形状。
185    #[serde(default, skip_serializing_if = "Vec::is_empty")]
186    pub commands: Vec<AgentCommand>,
187}
188
189/// 网关下发给 agent 的一次性命令。
190///
191/// 与「期望状态」(工作 / 上送 / 策略)刻意分开:那些是可重拉的幂等快照,
192/// 这里是**一次执行**的动作,有明确的 `command_id`、结果与去重语义。
193///
194/// `command_id` 是去重键:agent 把处理过的命令写进本地台账,网关在没有收到
195/// `command_acks` 时会重发同一条;agent 见到同一个 id 不重复跑,只补结果。
196#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
197#[serde(deny_unknown_fields)]
198pub struct AgentCommand {
199    pub command_id: String,
200    /// 网关受理时刻(墙钟毫秒):agent 用它判过期。
201    pub requested_at_ms: i64,
202    /// 命令词表(见 [`command_kind`])。**开放字符串**:未知值由 agent 回
203    /// `unsupported`,而不是让整份回执解析失败。
204    pub kind: String,
205    /// 命令参数(JSON 文本;空 = 无参数)。不同 `kind` 自己解析,未知字段不进入本层。
206    #[serde(default, skip_serializing_if = "String::is_empty")]
207    pub params: String,
208}
209
210/// agent 对一条命令的处理结果(随下一次状态上报回传)。
211#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
212#[serde(deny_unknown_fields)]
213pub struct AgentCommandAck {
214    pub command_id: String,
215    /// 见 [`command_outcome`]。
216    pub outcome: String,
217    /// 人读细节(失败原因 / 探针统计…);无内容时省略。
218    #[serde(default, skip_serializing_if = "String::is_empty")]
219    pub detail: String,
220}
221
222/// 命令词表(`AgentCommand.kind`)。新增命令只在这里加一个值 + 一个执行分支。
223pub mod command_kind {
224    /// 立刻重采一次并上报事实(见 agentd `refresh-facts`)。
225    pub const REFRESH_FACTS: &str = "refresh_facts";
226    /// 一次性只读调查(见 agentd `investigate`):当场查一个问题并给证据表。
227    ///
228    /// `params` 是题目自己的 JSON(`topic` + 题目选项);不认识的值由 agent 回 `unsupported`。
229    /// 完整报告**不走这里**:ack 只回结论摘要,报告本体走数据面 ` IVSREP: ` 帧。
230    pub const INVESTIGATE: &str = "investigate";
231    /// 手工刷新一组“知识/期望状态”。`params` 是 [`crate::status::RefreshParams`] 的 JSON。
232    ///
233    /// 只覆盖可重复拉取的控制面数据;`uplink` 只能显式请求(直接决定“发不发、发到哪”)。
234    pub const REFRESH: &str = "refresh";
235}
236
237/// `refresh` 命令的可刷新来源词表([`RefreshParams::what`] 的取值)。
238pub mod refresh_what {
239    /// 重采并重报事实(等价于已有的 `refresh_facts`)。
240    pub const FACTS: &str = "facts";
241    /// 发现策略(`discovery-policies:poll`)。
242    pub const POLICIES: &str = "policies";
243    /// 工作授权(`work:poll`)。
244    pub const WORK: &str = "work";
245    /// 选择类 label(`metrics-labels`)。**与 CLI 子命令同名**:运维在命令台账里读到的
246    /// 值必须能直接抄回 `--only`。
247    pub const METRICS_LABELS: &str = "metrics-labels";
248    /// 凭据续期(排障用,不进 `--all`)。
249    pub const CREDENTIALS: &str = "credentials";
250    /// 上送开关与目标。**不进 `--all`**,只能显式请求。
251    pub const UPLINK: &str = "uplink";
252
253    /// 全部已知来源(校验 `RefreshParams` 用;顺序 = 文档里的表格顺序)。
254    ///
255    /// 注意:这份表**不等于** `--all` 的范围 —— `uplink` / `credentials` 只能显式点名。
256    pub const ALL: &[&str] = &[FACTS, POLICIES, WORK, METRICS_LABELS, CREDENTIALS, UPLINK];
257}
258
259/// `refresh` 命令的参数。
260#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
261#[serde(deny_unknown_fields)]
262pub struct RefreshParams {
263    /// 要刷新的来源(见 [`refresh_what`])。空表由 agent 按“无效参数”处理。
264    pub what: Vec<String>,
265}
266
267/// 命令结果词表(`AgentCommandAck.outcome`)。
268pub mod command_outcome {
269    /// 执行完成,效果已生效(重采:事实已上报)。
270    pub const SUCCEEDED: &str = "succeeded";
271    /// 执行了,但没达到目标(重采:事实上报失败)。
272    pub const FAILED: &str = "failed";
273    /// 执行了,但本机没有可用的上送通道(重采:输出是 `file`)。
274    pub const NO_UPLINK: &str = "no_uplink";
275    /// 没执行:本地最小间隔未到。
276    pub const THROTTLED: &str = "throttled";
277    /// 没执行:命令过期(网关下发后很久才被拿到)。
278    pub const STALE: &str = "stale";
279    /// 不认识这种 `kind`(旧 agent 收到新命令)。
280    pub const UNSUPPORTED: &str = "unsupported";
281    /// **agent 侧阶段回报**:命令已被取走、正在执行,终态还会再来一条。
282    ///
283    /// 网关收到它只记「已认领」(`claimed_at`),**不能**当终态 —— 一条 `disk` 调查
284    /// 默认要扫 120s,没有这个阶段的话,页面上「等待认领」会持续整个扫描时长,
285    /// 看起来像命令丢了。终态到达时再写 `acked_at` / `outcome` / `detail`。
286    pub const ACCEPTED: &str = "accepted";
287    /// **仅网关侧**:未执行的旧命令被同 kind 的新命令覆盖。agent 不会回这个值。
288    pub const SUPERSEDED: &str = "superseded";
289    /// **仅网关侧**:命令超过待执行窗口(旧 agent 不认、或长期离线),网关不再下发。
290    pub const EXPIRED: &str = "expired";
291}
292
293#[cfg(test)]
294mod tests {
295    use super::{
296        AgentCertificateStatus, AgentCommandAck, AgentStatusAck, AgentStatusReport, AgentWorkState,
297        AgentWorkStateChange, command_outcome,
298    };
299
300    #[test]
301    fn agent_work_state_uses_snake_case_on_the_wire() {
302        assert_eq!(
303            serde_json::to_string(&AgentWorkState::Paused).unwrap(),
304            "\"paused\""
305        );
306        assert_eq!(
307            serde_json::to_string(&AgentWorkState::Resumed).unwrap(),
308            "\"resumed\""
309        );
310        let change = AgentWorkStateChange {
311            input_id: "app".to_string(),
312            state: AgentWorkState::Paused,
313            reason: "spool_over_limit".to_string(),
314            at: "2026-09-27T00:00:00Z".to_string(),
315        };
316        let json = serde_json::to_string(&change).expect("encode");
317        let back: AgentWorkStateChange = serde_json::from_str(&json).expect("decode");
318        assert_eq!(back, change);
319
320        // 与同族的 AgentStatusReport 一致:拒绝未知字段,避免字段漂移静默通过。
321        let mutated = json.replacen('{', "{\"extra\":1,", 1);
322        assert!(serde_json::from_str::<AgentWorkStateChange>(&mutated).is_err());
323    }
324
325    #[test]
326    fn a_minimal_agent_status_report_decodes_and_extra_keys_fail() {
327        // 旧版 agent 只发三个必填字段;其余全是 #[serde(default)]。
328        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.1.5"}"#;
329        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
330        assert_eq!(report.memory_bytes, None);
331        assert_eq!(report.cpu_percent, None);
332        assert_eq!(report.work_state_changes, None);
333        assert_eq!(report.discovery_policy_version, None);
334        assert!(report.local_work.is_none());
335        assert!(report.uplink_state.is_none());
336        assert!(report.certificate_status.is_none());
337        // 机器画像同样是可选的:旧版 agent 不带 -> None(网关落库时保持上一次的值)。
338        assert!(report.machine_profile.is_none());
339        // 命令结果同样可选(旧 agent 不带 = 没有要确认的命令)。
340        assert!(report.command_acks.is_empty());
341
342        assert!(
343            serde_json::from_str::<AgentStatusReport>(
344                r#"{"agent_id":"a","instance_id":"i","version":"v","nope":1}"#
345            )
346            .is_err()
347        );
348    }
349
350    /// 机器画像随状态上报带上时能如实解码(机器名 / node_id / 网卡地址)。
351    #[test]
352    fn an_agent_status_report_carries_the_machine_profile() {
353        let json = r#"{
354            "agent_id":"a","instance_id":"i","version":"0.1.24",
355            "machine_profile":{
356                "node_id":"node-1","hostname":"host-1","os":"linux","arch":"x86_64",
357                "machine_id":"mid-1","cloud_instance_id":null,"k8s_node_uid":null,
358                "ip_addresses":["en0 192.168.1.5/24","10.8.0.2"]
359            }
360        }"#;
361        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
362        let profile = report.machine_profile.expect("machine_profile present");
363        assert_eq!(profile.hostname, "host-1");
364        assert_eq!(profile.node_id, "node-1");
365        assert_eq!(profile.machine_id, "mid-1");
366        assert_eq!(
367            profile.ip_addresses,
368            vec!["en0 192.168.1.5/24".to_string(), "10.8.0.2".to_string()]
369        );
370    }
371
372    /// 证书状态里的「最近一次续签」是可选的,且拒绝未知字段:
373    /// 旧 agentd 少发它必须仍能解码(上线顺序不一,网关不能因此 400)。
374    #[test]
375    fn certificate_status_last_renewal_is_optional_and_round_trips() {
376        let legacy =
377            r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid"}"#;
378        let status: AgentCertificateStatus = serde_json::from_str(legacy).expect("decode");
379        assert!(status.last_renewal.is_none());
380
381        let json = r#"{"not_after":"2026-11-04T00:00:00Z","remaining_seconds":100,"state":"valid",
382            "last_renewal":{"outcome":"renewed","checked_at":"2026-10-08T00:00:00Z",
383            "detail":"credential renewed","not_after":"2026-11-04T00:00:00Z"}}"#;
384        let status: AgentCertificateStatus = serde_json::from_str(json).expect("decode");
385        assert_eq!(
386            status.last_renewal.as_ref().expect("renewal").outcome,
387            "renewed"
388        );
389
390        let encoded = serde_json::to_string(&status).expect("encode");
391        let back: AgentCertificateStatus = serde_json::from_str(&encoded).expect("decode");
392        assert_eq!(back, status);
393
394        // 字段漂移(`last_renewal` 里多出未知键)必须显形。
395        let drifted = r#"{"not_after":"x","remaining_seconds":0,"state":"valid",
396            "last_renewal":{"outcome":"renewed","checked_at":"t","detail":"","not_after":"",
397            "extra":1}}"#;
398        assert!(serde_json::from_str::<AgentCertificateStatus>(drifted).is_err());
399    }
400
401    /// D7:能力清单可选;旧 agentd 不带时必须是 `None`(网关据此按“未知”处理)。
402    #[test]
403    fn logs_capabilities_are_optional_and_round_trip() {
404        let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.8.0"}"#;
405        let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
406        assert!(report.logs_capabilities.is_none());
407
408        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0",
409            "logs_capabilities":{
410                "file_inputs":["absolute-path","glob"],
411                "multiline_modes":["none","indented"],
412                "exporters":["journalctl-kernel"]
413            }}"#;
414        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
415        let logs = report.logs_capabilities.expect("logs_capabilities");
416        assert_eq!(logs.exporters, vec!["journalctl-kernel".to_string()]);
417        assert!(logs.file_inputs.contains(&"glob".to_string()));
418
419        // 字段漂移仍要显形(与同族结构一致)。
420        let drifted = r#"{"agent_id":"a","instance_id":"i","version":"v",
421            "logs_capabilities":{"file_inputs":[],"nope":1}}"#;
422        assert!(serde_json::from_str::<AgentStatusReport>(drifted).is_err());
423    }
424
425    /// 回执里可以带一批通用命令;旧网关不带这个字段时仍然是合法回执。
426    #[test]
427    fn a_status_ack_carries_optional_commands() {
428        let legacy = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t"}"#;
429        let ack: AgentStatusAck = serde_json::from_str(legacy).expect("decode");
430        assert!(ack.commands.is_empty());
431
432        let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
433            "commands":[{"command_id":"c-1","requested_at_ms":1700000000000,
434            "kind":"refresh_facts"}]}"#;
435        let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
436        assert_eq!(ack.commands.len(), 1);
437        let command = &ack.commands[0];
438        assert_eq!(command.command_id, "c-1");
439        assert_eq!(command.requested_at_ms, 1_700_000_000_000);
440        assert_eq!(command.kind, "refresh_facts");
441        assert!(command.params.is_empty());
442
443        // 没有命令时字段不出现:旧 agent(若未来开始解析回执)不会被空数组干扰。
444        let encoded = serde_json::to_string(&AgentStatusAck {
445            agent_id: "a".to_string(),
446            instance_id: "i".to_string(),
447            acknowledged_at: "t".to_string(),
448            commands: Vec::new(),
449        })
450        .expect("encode");
451        assert!(!encoded.contains("commands"));
452
453        // 命令里的字段漂移要显形。
454        let drifted = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
455            "commands":[{"command_id":"c-1","requested_at_ms":1,
456            "kind":"refresh_facts","nope":1}]}"#;
457        assert!(serde_json::from_str::<AgentStatusAck>(drifted).is_err());
458    }
459
460    /// 未知 kind 是**合法字符串**(旧 agent 要靠它回 `unsupported`),不是解析错误。
461    #[test]
462    fn an_unknown_command_kind_still_decodes() {
463        let json = r#"{"agent_id":"a","instance_id":"i","acknowledged_at":"t",
464            "commands":[{"command_id":"c-9","requested_at_ms":1,"kind":"future_command"}]}"#;
465        let ack: AgentStatusAck = serde_json::from_str(json).expect("decode");
466        assert_eq!(ack.commands[0].kind, "future_command");
467    }
468
469    #[test]
470    fn refresh_params_round_trip() {
471        let params = super::RefreshParams {
472            what: vec![
473                super::refresh_what::WORK.to_string(),
474                super::refresh_what::METRICS_LABELS.to_string(),
475            ],
476        };
477        let text = serde_json::to_string(&params).expect("serialize");
478        assert_eq!(text, r#"{"what":["work","metrics-labels"]}"#);
479        let parsed: super::RefreshParams = serde_json::from_str(&text).expect("deserialize");
480        assert_eq!(parsed, params);
481    }
482
483    /// 新 agent 报告里的命令结果可选;旧 agent 不带时字段不出现。
484    #[test]
485    fn an_agent_status_report_can_carry_command_results() {
486        let legacy = r#"{"agent_id":"a","instance_id":"i","version":"0.9.0"}"#;
487        let report: AgentStatusReport = serde_json::from_str(legacy).expect("decode");
488        assert!(report.command_acks.is_empty());
489
490        let json = r#"{"agent_id":"a","instance_id":"i","version":"0.9.11",
491            "command_acks":[{"command_id":"c-1","outcome":"succeeded",
492            "detail":"probes=6 failed=0"}]}"#;
493        let report: AgentStatusReport = serde_json::from_str(json).expect("decode");
494        assert_eq!(
495            report.command_acks,
496            vec![AgentCommandAck {
497                command_id: "c-1".to_string(),
498                outcome: command_outcome::SUCCEEDED.to_string(),
499                detail: "probes=6 failed=0".to_string(),
500            }]
501        );
502    }
503
504    /// `accepted` 是 **跨版本协议词**:字面量一旦变,先发的那一侧就听不懂后发的一侧。
505    ///
506    /// 具体后果:agent 说新词、网关认旧词 → 网关当成终态落库,命令被提前收口、
507    /// 页面永远拿不到结果。所以这里把 wire 值钉死,而不是只靠常量名。
508    #[test]
509    fn an_accepted_command_ack_keeps_its_wire_name() {
510        assert_eq!(command_outcome::ACCEPTED, "accepted");
511
512        let ack = AgentCommandAck {
513            command_id: "c-1".to_string(),
514            outcome: command_outcome::ACCEPTED.to_string(),
515            detail: "已取走,扫描中(最长 120s)".to_string(),
516        };
517        let json = serde_json::to_string(&ack).expect("encode");
518        assert!(
519            json.contains(r#""outcome":"accepted""#),
520            "阶段回报的 wire 值变了:{json}"
521        );
522        assert_eq!(
523            serde_json::from_str::<AgentCommandAck>(&json).expect("decode"),
524            ack
525        );
526
527        // 旧 agent 只发终态词:`accepted` 不能与其中任何一个撞名。
528        for terminal in [
529            command_outcome::SUCCEEDED,
530            command_outcome::FAILED,
531            command_outcome::NO_UPLINK,
532            command_outcome::THROTTLED,
533            command_outcome::STALE,
534            command_outcome::UNSUPPORTED,
535        ] {
536            assert_ne!(command_outcome::ACCEPTED, terminal);
537        }
538    }
539}