AGENTS.md@apps/desktop/src/main/app-monitor git:20260818.4f19511A

Immutable. This exact content never changes and is served at /api/v1/blob/422c03a229e234b8.

# App Monitor Rules

> 本目录规则适用于应用监控实现。监控不是日志记录，也不是业务流程的一部分。

## Core Principle

应用监控必须是旁路能力：可失败、可延迟、可丢失，不能影响、阻塞或改变原有业务流程。

## Implementation Rules

- 监控记录不得成为业务成功条件。业务操作成功与否只能由原业务逻辑决定。
- 监控失败必须被吞掉或降级为 warn，不得向调用方抛出并中断业务流程。
- 不要在 IPC handler、加工轮、会话执行、文件维护等关键路径里 `await` 纯监控 IO。
- 需要扫描磁盘、读取大文件、统计快照、写持久化文件时，应使用后台调度、合并去重或周期 flush。
- 高频事件只能做轻量内存计数；持久化走既有周期落盘机制。
- 监控数据只能保存聚合指标和当前快照，不保存事件流水、用户内容、文件内容或可还原隐私的数据。
- 修改 `AppMonitorData` 的持久化结构时，必须先评估兼容方式：纯新增聚合字段且可由 normalize 补默认值时，不必提高 `APP_MONITOR_SCHEMA_VERSION`；需要显式转换旧数据语义时，才提高版本并补齐连续 migration。
- 监控逻辑不得引入业务锁、扩大现有锁范围，或改变原有互斥/并发语义。
- 监控订阅必须可释放，不能因为监控导致 session、timer、listener 泄漏。

## Acceptable Patterns

- 业务完成后同步增加内存计数。
- 业务完成后触发 `void` 后台任务记录快照。
- 多次快照请求合并为一轮后台扫描，扫描期间只记录 pending 标记。
- 后台监控任务内部 catch 错误并记录 warn。

## Forbidden Patterns

- 为了监控在业务路径中新增必经 IO。
- 因监控写入失败让 IPC 请求失败。
- 因监控扫描耗时延迟用户操作返回。
- 为了监控重新读取或重算已经不需要的业务数据，并在主流程中等待结果。
- 把监控实现成详细日志、审计流水或事件明细存储。