RouterMonitor（P007）· 开发全过程纪要

一个「每几分钟看一眼路由器连接数、超阈值就抓现场并发邮件」的小工具，从 daemon 常驻进程改成 Windows 计划任务、从纯 CSV 演进到带 JSON 快照明细，并在一次真实的告警静默丢失事故里完成了稳定性改造。

本纪要全部内容基于 D:\LJH\项目\RouterMonitor 的 README、docs/2026-09-11-凌晨连接数尖峰分析.md、data/ 运行数据与 git 提交记录（6 个提交）整理。凡资料未记载处，均明确标注「资料未记录」。

关键信息速览

项	值
项目编号	P007
项目名称	RouterMonitor — 路由器监控
监控对象	爱快 iKuai IK-M360X（路由型号标注 Suyan K-M360X），`192.168.10.1`，管理接口 `http://192.168.10.1/Action/call`
云效仓库	`git@codeup.aliyun.com:62bc7cf811fc0f0c9e2aedb2/guxin-it/RouterMonitor.git`（私有，代码组 `guxin-it`）
本地目录	`D:\LJH\项目\RouterMonitor`（仓库即项目唯一工作区）
技术栈	Python（标准库 `urllib`/`csv`/`json`/`logging` 为主，无第三方依赖）；Windows 计划任务 `RouterMonitor_Collect` 调度（S4U，未登录也能运行）；CSV（UTF-8-SIG）+ JSON 快照；不使用数据库
开发周期	2026-09-01（首版 1.0 交付，1.1 补 .gitignore）→ 2026-09-11（v2.0 尖峰抓捕版 + 入库）→ 2026-10-12（稳定性改造）。git 内仅 6 个提交（自 2026-09-11 建仓）
当前版本	已发布：`main` = `5fc42ac`（tag `v2.0`）；待发布：`dev` 领先 3 个提交（`1285843` / `41f3550` / `9127312`）
采集节奏	现为 300 秒/轮（2026-10-12 由 120 秒改为 300 秒）；峰值检查 `check_interval_min=10`
运行数据	`data/router_2026-09-01.csv` 至 `router_2026-10-13.csv` 连续 43 天；抓捕快照 31 个（`data/capture/20260911_151244/` … ）
归档状态	仓库已建（2026-09-11）；tag `v2.0`；早期 1.0/1.1 快照存于本地冻结归档仓 `D:\LJH\产物归档\project-artifacts_del`（云端已于 2026-09-11 删除）
负责人	刘锦辉（liujinhui@agent.qq.com）— 顾信家居 IT

目录

一、项目缘起与初始规划
1.1 缘起：一次没人认领的夜间网络异常
1.2 痛点：缺的不是数据，是「出事时的现场」
1.3 需求边界与演进路线
1.4 如果现在重做，会怎么定
二、技术选型与架构设计
2.1 整体架构：一个跑完就退出的脚本
2.2 文件与模块划分
2.3 数据模型：CSV + JSON 快照 + state.json
2.4 触发判定设计
2.5 取数方式的关键取舍：JSON 主 + CSV 辅
2.6 邮件通道设计
2.7 调度方案：daemon 废弃改计划任务
三、迭代编年史
3.1 v1.0 首版交付（2026-09-01 17:59）
3.2 v1.1 补 .gitignore（2026-09-01 18:03）
3.3 v2.0 三项改造 + 尖峰分析（2026-09-11）
3.4 建仓整理：先归档再删除（2026-09-11 15:39）
3.5 归档反转：archive/ 全删（2026-09-11 15:40）
3.6 版本管理改用 git tag，归档仓冻结（2026-09-11 16:11）
3.7 2026-10-12：稳定性改造六项（dev，待发布）
3.8 分支模型与待发布记录落地（2026-10-12 14:41–14:45）
四、关键攻坚与踩坑复盘
4.1 凌晨 2:43 的 11,082 连接：一次真实的排障
4.2 告警静默丢失：邮件被挂在抓捕后面
4.3 脏数据伪装成峰值：7966 是怎么来的
4.4 峰值延迟确认：一个走不通的方案和它的替代品
4.5 最重的接口却必须保留：device_num 的节流熔断
4.6 会话失效与「向日葵效应」
五、质量保障与验证机制
六、构建、部署与归档
七、遗留问题与后续计划
八、协作方式复盘
附录 A：完整提交清单
附录 B：文件与模块说明

一、项目缘起与初始规划

1.1 缘起：一次没人认领的夜间网络异常

这个项目的起点不是「想做监控」，而是一次查不出原因的故障。

2026-09-11 凌晨，爱快后台显示当日凌晨 2:00 前后网络连接数峰值 45,349。初步怀疑是公司电脑夜间自动升级（Windows Update）。但排查下来不是——详见 docs/2026-09-11-凌晨连接数尖峰分析.md 与 §4.1。

结论是：排除了升级，但无法定位到具体是哪台内网设备发起的。原因很硬——「爱快默认不保存历史连接明细，且当时「行为审计」未开启，因此无法回溯该时刻是哪个内网 IP 发起」。

这次排障留下了两样东西，都成了 RouterMonitor 的直接需求来源：

一张图 + 一份结论文档（docs/spike_20260911_0243.png 与同名 md），证明「光有时间序列数据，只够排除、不足以定位」；
一个明确的能力缺口：要在异常发生的那一刻把连接明细抓下来，而不是事后回看聚合数字。

1.2 痛点：缺的不是数据，是「出事时的现场」

RouterMonitor 1.0 阶段已经在做每分钟采集 + 破纪录邮件（见 §3.1），但 1.0 的告警内容只有一个数字——「今天连接数创新高 XXXX」。当 2:43 的 11,082 被这样一条邮件概括时，它只能告诉你「有事发生」，不能告诉你「谁干的」。

所以 v2.0 的需求本质是一句话：告警邮件里必须直接带现场。

具体化为四个能力（README 变更记录 2026-09-11 三项改造）：

触发时抓全终端连接排行 + TOP N 台终端的逐条连接明细（协议 / 目标 IP / 端口 / 应用识别 / 走哪条 WAN）；
落盘成 data/capture/<时间戳>/，JSON 主 + CSV 辅，并维护 index.jsonl 历史索引；
邮件内容包含 TOP15 终端榜单 + TOP5 终端的应用聚合明细，不只给数字；
同时开启爱快「行为审计」，补上「哪台终端在何时连了什么」的历史留存能力。

1.3 需求边界与演进路线

README 的变更记录本身就是一条路线图，从 2026-09-01 到 2026-10-12 共 6 个可辨识的节点：

日期	节点
2026-09-01	首版交付 1.0（每分钟采集 + 破纪录邮件）；1.1 补 .gitignore
2026-09-01	改用纯 CSV 存储（弃用 DuckDB）
2026-09-04	改为破纪录后立即直发邮件（`send_mail_direct.py` 解密本地 OAuth 凭据直调 agent 邮箱）
2026-09-11	三项改造：JSON 主 + CSV 辅落盘；采集改 120 秒 + 新增 `device_num` + 改突破记录/绝对阈值才抓；调度迁移到 Windows 计划任务，弃用常驻进程与看门狗
2026-09-11	产物整理：目录归整、凭据隔离（`config.json` 不入库 + `config.example.json`）、删除弃用实现
2026-10-12	稳定性改造六项（峰值告警静默丢失、脏数据污染、重试、节流熔断、间隔调整、延迟测量工具）

值得单列的一条决策：2026-09-01 弃用 DuckDB 改纯 CSV。这是一个「往下降级」的选择——CSV 无 schema、无事务、无并发。从结果看这个选择是对的（见 §4.4 延迟确认机制正是靠「读当日 CSV 全文」才实现的），但当时并不知道这一点。

1.4 如果现在重做，会怎么定

以下是基于已发生事实的反向复盘，不是原始方案内容：

「设备身份」应该是一等公民。 现在报警只能给 IP + 主机名/备注（如 index.jsonl 里的 192.168.10.50 / LJH、192.168.10.147 / 陈耀辉），依赖爱快里的注释字段质量。想让邮件真正可执行，应该维护一张 IP ↔ 使用人 ↔ 部门 的本地映射表——爱快的「终端记录」（open_terminal_record）至今仍未开启（§7）。
采集器与判定的耦合应该更早拆开。 现在 collect.py 一个文件里既有采集、又有峰值判定、又有邮件构造、又有 CSV 读写。2026-10-12 那一笔要改 4 个不同层面的东西（判据、重试、节流、间隔），改动量 221 行却还要小心不破坏其他 3 个功能。判定逻辑本身是纯函数（decide_trigger），完全可以独立成模块 + 独立测试。
「配置即真相」这个原则应该更早贯彻。 2026-10-12 改采集间隔时发现 config.json 改了 300 秒，但 peak.check_interval_min 必须「≥ 采集间隔」，忘了改就会「比对比采集还频繁白跑」。凡是两个配置项之间有大小约束，就应该在加载时校验并拒绝启动，而不是靠人记住。
告警通道应该有第二条独立的路。 现在告警只有邮件一条路，send_mail_direct 挂了 → 直发失败 → 退回 pending_email.json 队列 → 靠外部每小时定时任务读取补发。告警系统自己依赖另一个调度器，本身就是个单点。
1.0 就不该用 daemon。 60 秒常驻 + 看门狗 + 开机自启三个组件，为的是一个「跑一次就退出」的逻辑。Windows 计划任务（S4U）在第 6 天（2026-09-11）就把它替掉了，早用早省 7 个文件。

二、技术选型与架构设计

2.1 整体架构：一个跑完就退出的脚本

Windows 计划任务 RouterMonitor_Collect（S4U，每 300 秒）
        │
        ▼
   collect.py --task                    ← 跑一轮即退出
        │
        ├─ router_stat.fetch_with_renew()          sysstat 接口（重试 2/4/8s）
        │      └─ _post() 指数退避，仅网络异常重试，认证异常立即上抛
        │
        ├─ spike_capture.fetch_device_count()     monitor_lanip limit=0,1（最重接口）
        │      └─ 经 _get_device_count_throttled() 节流 + 熔断
        │
        ├─ 追加写 data/router_YYYY-MM-DD.csv      11 列时序
        │
        ├─ spike_capture.check()                  触发判定
        │      ├─ 未触发 → return None
        │      ├─ 触发 → _login() → fetch_terminal_rank()
        │      │           → TOP5 × fetch_terminal_conns()（串行，间隔 0.4s）
        │      │           → save_capture() → data/capture/<时间戳>/
        │      │           → send_mail() → 直发，失败入 pending_email.json
        │      └─ 抓捕失败 → build_degraded_mail() → 发简报（2026-10-12 新增）
        │
        └─ check_peak()                           每 10 分钟，延迟确认峰值
               ├─ 处理上轮 pending_peak（10 分钟后回看持续率）
               └─ 产生新的 pending_peak 候选

state.json  ← 当日记录 / 触发基准 / 抓捕元数据 / pending_peak / rejected_peaks / device_count

设计上有一点值得强调：没有数据库。README 变更记录 2026-09-01 明确写了「改用纯 CSV 存储（弃用 DuckDB）」。所有状态（当日峰值、触发基准、冷却时间戳、熔断计数、待确认峰值）都在一个 state.json 里，按日期为顶层 key，跨天自动重置。

2.2 文件与模块划分

RouterMonitor/
├── collect.py                465+ 行  主入口：采集 → CSV → 触发判定 → 峰值检查
├── spike_capture.py          560+ 行  尖峰抓捕：判定 → 排行 + 明细 → 落盘 → 邮件
├── router_stat.py            280+ 行  爱快接口封装：登录 / 续期 / sysstat / 重试
├── send_mail_direct.py       380+ 行  agent 邮箱直发（OAuth 凭据解密 + token 续期 + 队列兜底）
├── smtp_sender.py             70 行   SMTP 备用通道
├── config.json               全部配置（不入库）
├── config.example.json       脱敏模板（入库）
├── state.json                状态（不入库）
├── agentmail_config.json     agent 邮箱 OAuth 配置（不入库）
│
├── tools/
│   ├── plot_spike.py         连接数曲线绘图
│   ├── renew_token.py        sess_key 续期工具
│   └── measure_router_latency.py   响应时间基线采集器（2026-10-12 新增）
│
├── docs/
│   ├── 2026-09-11-凌晨连接数尖峰分析.md
│   └── spike_20260911_0243.png
│
├── data/                     运行数据（不入库）
│   ├── router_YYYY-MM-DD.csv
│   ├── capture/<时间戳>/     31 个快照
│   │   ├── summary.json      触发原因 + TOP + 应用聚合 + 文件清单
│   │   ├── rank.json / rank.csv
│   │   └── conns/<ip>.json + all.csv
│   ├── capture/index.jsonl   抓捕历史索引
│   ├── pending_email.json    邮件兜底队列
│   └── .mail_tokens.json     access_token 缓存
│
└── logs/                     collect.log / error.log（不入库）

模块间依赖是单向的，这是这个项目结构上做得最好的地方：

collect.py ──import──> router_stat
      │                    ↑
      ├──import──> spike_capture ──import──> collect（仅 enqueue_mail 兜底时）
      └──import──> send_mail_direct

router_stat.py  ← 不 import 任何业务模块（独立可执行，有 main()）
spike_capture.py ← 不 import collect（仅在邮件失败兜底时延迟 import，避免循环）

router_stat.py 完全独立，有自己的 main()，可以 python router_stat.py 单跑看路由器状态。这个解耦在 2026-10-12 一次改 4 个模块时体现出了价值。

唯一的例外是 spike_capture.send_mail() 里的 import collect——在直发失败时延迟导入以调用 collect.enqueue_mail() 入队。这是刻意的延迟导入，用 try/except 包住避免循环依赖失败。属于可接受的妥协（代码注释也写了原因）。

2.3 数据模型：CSV + JSON 快照 + state.json

三层存储，各司其职：

第一层：CSV 时序（data/router_YYYY-MM-DD.csv，11 列，UTF-8-SIG 便于 Excel 直接打开）

列	含义	单位
`time`	采集时间	本地时间
`connect_num`	活跃连接数（NAT 会话数）	个
`up_bps` / `down_bps`	实时上行/下行速率	字节/秒
`total_up_bytes` / `total_down_bytes`	累计上行/下行流量	字节
`cpu_avg_pct`	CPU 平均负载	%
`mem_used_pct`	内存使用率	%
`mem_avail_mb`	可用内存	MB
`cpu_core_count`	CPU 核心数	个
`device_num`	在线终端数（物理设备数）	台

device_num 是 v2.0 新增的第 11 列。变更记录写明同时做了「历史行已迁移补齐」——1.0/1.1 的 CSV 只有 10 列。实测数据里能看到节流的效果（2026-10-13）：

2026-10-13 00:01:39,594,...,5,        ← device_num 为空（节流未到间隔）
2026-10-13 00:06:39,627,...,5,57
2026-10-13 00:11:39,495,...,5,58
2026-10-13 00:16:39,492,...,5,        ← 又一次节流跳过
2026-10-13 00:21:39,580,...,5,58

第二层：JSON 快照（data/capture/<时间戳>/）

20260911_151244/
├── summary.json       触发原因 + 榜单 TOP + 应用聚合 + 文件清单
├── rank.json          全终端排行（结构化）
├── rank.csv           全终端排行（Excel 友好）
└── conns/
    ├── 192.168.10.147.json    单终端明细（apps 聚合 + 原始 conns）
    ├── 192.168.10.145.json
    ├── ...（本次抓了 4 台）
    └── all.csv                全部明细汇总

summary.json 的实际结构（取自首个快照）：

{
  "time": "2026-09-11 15:12:44",
  "stamp": "20260911_151244",
  "trigger": {"text": "手动强制抓取", "total_connect": 99999,
              "day_record": 11082, "capture_base": 0},
  "total_connect": 99999,
  "device_num": 111,
  "terminal_count": 111,
  "top": [{"rank": 1, "connect_num": 77, "ip_addr": "192.168.10.147",
           "device": "陈耀辉", "client_model": "", "apname": ""}, ...]
}

index.jsonl 是抓捕历史索引，一行一次，data/capture/index.jsonl 现有 31 条。实际内容（已脱敏保留结构）：

{"time": "2026-09-17 14:25:42", "stamp": "20260917_142542", "total_connect": 6152,
 "device_num": 110, "day_record_before": 5252, "top1_ip": "192.168.10.113",
 "top1_device": "白龙腾", "dir": "20260917_142542/"}

31 次抓捕的 total_connect 区间大致在 3,000–6,200（首个 99999 是手动强制测试的假值）。这个分布本身就是触发参数（min_connect=3000）的标定依据——日常峰值就在 3000 附近，定低了会天天报警。

第三层：state.json（顶层按日期分组，跨天自动重置）

{
  "2026-10-12": {
    "max_connect": 4848,        // 已确认的真峰值
    "peak_row": {...},
    "last_peak_check_ts": "...",
    "pending_peak": {...},      // 待确认候选（2026-10-12 新增）
    "rejected_peaks": [...],    // 已否决的脏数据（最多留 20 条）
    "capture_base": ...,        // 上次触发时的连接数（grow_ratio 的基准）
    "last_device_num": ...
  },
  "spike_capture": {"last_ts": ..., "last_total": ..., "last_top1": "...",
                    "last_dir": ..., "last_degraded": false},
  "device_count": {"fail_streak": 0, "state": "ok",
                   "last_ok_ts": "...", "last_try_ts": "...", "last_value": 57}
}

注意 spike_capture 和 device_count 是跨日的全局键（不按日期分组），因为它们的语义（冷却时间、熔断状态）本身就是连续的。

2.4 触发判定设计

decide_trigger() 是整个项目的核心决策函数，返回 (是否触发, 原因文本, 详情dict)：

ratio, min_connect, abs_th = _trigger_params(cap)
rec  = int(day.get("max_connect") or 0)     # 当日记录
base = int(day.get("capture_base") or 0)    # 上次触发时的连接数
need = int(max(base * ratio, min_connect))

if total_connect >= abs_th:                                  # 规则一
    return True, f"连接数 {total_connect} ≥ 绝对阈值 {abs_th}", info
if (total_connect > rec and total_connect >= min_connect
        and total_connect >= need):                          # 规则二
    return True, f"连接数 {total_connect} 突破当日记录(前 {rec}), 且 ≥ 上次触发值 {base}×{ratio}", info
return False, "", info

当前参数（config.json → capture.trigger，实测值）：min_connect=3000、grow_ratio=1.5、abs_threshold=8000、cooldown_sec=180、detail_top=5、detail_min_conn=5。

README 把设计意图说得很清楚：

白天正常爬坡（~3,000-3,800）不会打扰；凌晨的量级级尖峰（≥8,000）必定触发。

三条规则的分工：

规则	作用	挡掉什么
`> 当日记录`	破纪录才抓	日常波动
`≥ min_connect=3000`	绝对下限	深夜低位的微小新高（3000 以下只是噪声）
`≥ base × grow_ratio`	相对增长	连续多次小幅爬坡导致的「假破纪录」
`≥ abs_threshold=8000`	无条件触发	兜底：不管什么状态，8000 必抓

grow_ratio 那一条是防「连抓」的：上一轮 3500 触发后，capture_base=3500，那么下一次要 3500×1.5=5250 才抓。配合 cooldown_sec=180（3 分钟冷却），风暴期不会重复抓、重复发信。

另有 detail_min_conn=5：连接数低于 5 台的终端不抓明细。这是对路由器负载的保护——fetch_terminal_conns() 每台终端 1 次请求，抓 TOP5 就是 5 次请求，每次间隔 time.sleep(0.4) 串行节流。

2.5 取数方式的关键取舍：JSON 主 + CSV 辅

README 里把这件事的推理写下来了，值得完整引用：

取数方式取舍：明细用 JSON —— 一次 json.dump 整体写（单次 I/O）、保留嵌套层级（协议/目标/应用/WAN），程序与 AI 读取最省事；CSV 仅作人工查阅（扁平表），但会被 Excel 独占锁定，不作为程序数据源。

三个理由，每个都是踩过坑的：

单次 I/O：json.dump 一次整体写完；CSV 逐行写，而且连接明细有多少条就写多少行。
保留嵌套层级：单条连接的「协议 / 目标 / 应用识别 / 走哪条 WAN」在 JSON 里是嵌套结构，在 CSV 里只能拍平成多列或拼接字符串。
Excel 独占锁：README 故障排查表第一条就是——

logs/error.log 报 Permission denied 写 CSV 失败 → 当日 CSV 被 Excel/WPS 手工打开，文件被独占锁定。关掉该文件即自动恢复；不需改代码

如果 CSV 是程序数据源，人看一眼就会打断程序。既然它是主要落盘格式，就必须让它不是程序依赖。collect.py 的模块文档字符串也把这条写成了约定：「当日 CSV 若被 Excel/WPS 手工打开会独占锁定导致写入失败(PermissionError)，属正常现象，关掉文件即恢复 —— 不做重试/转存等特殊处理」。

这条约定很有价值：明确接受一个已知限制，并写清楚为什么不修。加文件锁、加转存、加重试会让「人类日常会打开这个文件」这个必然事实变得不可控。

2.6 邮件通道设计

主通道：agent 邮箱直发（send_mail_direct.py）

README 描述：「agent 邮箱 liujinhui@agent.qq.com → 接收 117801633@qq.com」。代码里 SENDER = "liujinhui@agent.qq.com"，DEFAULT_TO = "117801633@qq.com"。

它的价值在于时机：README 强调「抓捕完成后立即直发（秒级），不依赖定时任务」。这直接对应 1.0 的一个老问题——等定时任务就失去了告警的意义。

凭据管理是一个三级获取链（1.0 的 README 描述）：「解密本地 WorkBuddy OAuth 凭据获取 token（缓存 → 凭据 → OAuth 刷新三级获取，自动续期）」。代码里能看到对应的函数：load_config() / extract_from_env() / mcp_post() / mcp_call() / get_me() / check_sender() / send_mail() / send_now() / flush_pending() / check_status() / get_quota()。

兜底通道：pending_email.json 队列。直发失败（send_mail() 捕获异常）时退回队列，README 记录是「WorkBuddy 每小时定时任务读取发送」。这里有一个架构上的隐忧，见 §7。

备用通道：SMTP（smtp_sender.py，70 行）。config.json 里 mail.channel 当前为 "smtp"，smtp_host=smtp.qq.com、smtp_port=465。实际发件人按 config.json 为 jinhuiliu@vip.qq.com。

告警去重：README 明确「破纪录告警与抓捕邮件已合并为同一封（peak.send_mail=false），不会重复打扰」。当前配置实测 peak.send_mail = False——峰值检查只维护 state.json 的 max_connect，不发邮件；邮件全部由 spike_capture.check() 发。这是一次明确的减法决策。

2.7 调度方案：daemon 废弃改计划任务

这是本项目最大的一次架构转向，也是最有价值的一次减法。

1.0 的方案（从冻结归档的 1.0 README 可完整还原）：

monitor_daemon.py（108 行）——「守护进程：每60秒调用采集逻辑（pythonw 无窗口运行，单实例保护）」
watchdog.py（72 行）+ install_watchdog_task.bat/.ps1 —— 看门狗，监控守护进程存活
install_daemon.bat（25 行）—— 「一键安装：立即启动 + 开机自启」
start_daemon.bat（4 行）—— 启动
cleanup_daemons.py（41 行）—— 清理所有守护进程

为了一个「跑一次就退出」的逻辑，付出了 7 个文件、约 290 行。而且这套东西要解决一连串问题：单实例保护、进程挂了要有人拉起来、开机要自启、无窗口运行、清理残留。

v2.0 的方案：一个 Windows 计划任务 RouterMonitor_Collect，S4U 权限（「未登录也能运行」），触发器周期化，每轮 python collect.py --task 跑完即退出。

collect.py 的模块文档字符串直接写明了转向：

运行方式 (2026-09-11 改版): 由 Windows 计划任务 RouterMonitor_Collect 每 120 秒调用一次, 单次执行即退出 (不再依赖常驻守护进程)。

--task 参数存在的唯一作用，是在日志里留痕触发来源：

if "--task" in sys.argv:
    logging.info("--- 由 Windows 计划任务 (RouterMonitor_Collect) 触发 ---")

代价：调度从 60 秒变成 120 秒（后改 300 秒），采样密度的损失换来了 7 个文件的消失、开机自启的原生支持、以及「进程死了不需要人管」。这笔交易在实操上非常划算。

三、迭代编年史

3.1 v1.0 首版交付（2026-09-01 17:59）

起点问题：需要持续知道内网路由器的连接数状态。

做了什么（据冻结归档 2026-09-01-1.0/README.md 与归档仓 README 记录）：首版交付，包含 10 个文件。

功能形态（1.0 README 原文）：「每分钟采集路由器（Suyan K-M360X，192.168.10.1）系统状态，每 5 分钟对比当日活跃连接峰值，破纪录时自动发送邮件提醒。」

CSV 10 列（尚无 device_num）。调度是 monitor_daemon.py + 看门狗 + 开机自启。存储是纯 CSV（变更记录写明同日「改用纯 CSV 存储（弃用 DuckDB）」）。

验证方式：无自动化测试的痕迹（归档内容里只有 data/ 目录）。

影响：确立了项目的基本骨架——router_stat.py（接口层）/ collect.py（采集+判定）/ send_mail_direct.py（邮件）的三层结构。这个结构到 2.0、乃至 2026-10-12 都没有变过，只是被逐层加厚。归档仓 README 记录：「首版交付：路由器监控+峰值邮件告警」。

3.2 v1.1 补 .gitignore（2026-09-01 18:03）

归档仓 README 的记录极简：「补充 .gitignore 排除运行数据」。产物 10 个文件，与 1.0 相同。

影响：很轻，但方向是对的——第一天就把「运行数据不入库」这条规矩定下来，避免后面 data/ 下几十 MB 的 CSV 和含凭据的 config.json 被提交。2026-09-11 建仓时（a3bd48b）又做了一次更彻底的凭据隔离。

3.3 v2.0 三项改造 + 尖峰分析（2026-09-11）

这是项目最重要的一次迭代，也是唯一一次「先有事故、后有功能」的迭代。

起点问题：2026-09-11 凌晨连接数尖峰（45,349 UI 显示值，2:43 采样到 11,082）排不出原因。分析文档的第四章写得很清楚：

爱快默认不保存历史连接明细，且当时「行为审计」未开启，因此无法回溯该时刻是哪个内网 IP 发起。

做了什么（README 变更记录 2026-09-11 三项改造）：

改造	内容
1. 抓捕数据改为 JSON 主 + CSV 辅	`data/capture/<时间戳>/`，含 `index.jsonl` 历史索引
2. 采集改为 120 秒/轮，新增在线终端数	CSV 新增 `device_num` 列（历史行已迁移补齐）；判定改为突破当日记录/绝对阈值才抓取
3. 调度迁移到 Windows 计划任务	`RouterMonitor_Collect`（S4U，未登录也能运行），弃用常驻进程与看门狗

同时修复两处：CSV 表头新增 device_num（历史行已迁移补齐）；测试入口改用真实连接数（避免假数字误导邮件判读）。

配套产出两份文档：
- docs/2026-09-11-凌晨连接数尖峰分析.md（55 行）
- docs/spike_20260911_0243.png（67,735 字节，由 tools/plot_spike.py 生成）

验证方式：人工验证 + 首次抓捕快照留档。

影响：项目从「数值监控」变成「取证工具」。最有说服力的证据是首个抓捕快照（data/capture/20260911_151244/，15:12:44，即尖峰分析当天下午）：抓了 111 台终端的排行 + 4 台 TOP 终端的逐条明细。index.jsonl 里那天也留下了两条记录：

20260911_151244：total_connect=99999（手动强制测试的假值）、day_record_before=11082、TOP1 192.168.10.147（77 条连接）
20260912_092540：total_connect=3080、day_record_before=2916、TOP1 192.168.10.72

新布防手段也写进了分析文档：爱快「行为审计」已开启（URL / IM / 应用识别记录），并留下一个明确的遗留项——「终端记录」open_terminal_record 仍为 0，需在爱快 UI 中单独开启。

3.4 建仓整理：先归档再删除（2026-09-11 15:39）

起点问题：项目产物散乱——废弃的实现混在顶层目录，凭据明文躺在 config.json 里，没有分析文档。

做了什么：提交 a3bd48b，24 个文件、+2544 行（首次入库，几乎是全量导入）。提交正文列了 6 条：

- 目录归整：顶层仅保留 6 个在运行的脚本/配置；新增 tools/(辅助脚本)、docs/(分析报告)、archive/(已弃用内容留档)
- 归档弃用方案：daemon/watchdog 常驻进程相关 7 个文件 -> archive/daemon/（现已由 Windows 计划任务调度）
- 归档无用产物：路由器前端 JS 抓取产物 -> archive/router_js/；无关脚本 chrome_pwd_extract.py -> archive/unrelated/
- 删除零价值文件：空目录 chunks/、__pycache__/、路由器页面抓取残留 page.html / login.html / chunks_manifest.js、
  过期会话令牌 data/.capture_sess.txt、重复副本 router_2026-09-02 - 副本.csv、CSV 迁移备份 .bak10col
- 文档：重写 README.md（补触发规则/落盘结构/故障排查/变更记录）；新增 docs 尖峰分析报告、archive/README.md
- 安全：config.json 含真实凭据 -> 移入 .gitignore，新增脱敏模板 config.example.json；data/ logs/ state.json 整体不入库

关键实现细节：

archive/daemon/ 保留的 7 个文件：monitor_daemon.py(108) / watchdog.py(72) / cleanup_daemons.py(41) / install_watchdog_task.ps1(33) / install_daemon.bat(25) / install_watchdog_task.bat(6) / start_daemon.bat(4)，另有 archive/README.md(27 行) 说明归档原因。
config.example.json 的设计：每个敏感字段用 <占位符> 而不是留空——"password": "<路由器管理员密码>"、"username": "<爱快只读账号>"、"smtp_auth_code": "<SMTP 授权码>"。留空会让人以为是「不需要填」，<占位符> 明确表示「这里必须填」。每个配置块还带 _说明 / _cookie说明 字段解释用途。这是很成熟的模板设计。
.gitignore 23 行，分四段：密钥凭据、运行数据与日志、工具元数据（.workbuddy/）、Python / 系统文件。

当时的处置原则：先归档，不直接删。提交正文里 archive/ 三次出现都带「留档」「归档弃用」字样。

影响：项目第一次有了「可交接」的状态。但这个决定在 95 秒后被推翻（见 §3.5）。

3.5 归档反转：archive/ 全删（2026-09-11 15:40）

起点问题：a3bd48b 提交后 95 秒，推翻了自己的归档决定。

做了什么：提交 29d5a09，13 个文件、−442 行。提交正文第一行就是「按用户决定」：

按用户决定：弃用的常驻进程/看门狗实现、路由器前端 JS 抓取产物、无关脚本全部删除，不再保留

README：移除 archive/ 相关结构与文档链接，变更记录补充本次整理说明

删除清单（可从 diff 完整读出）：archive/README.md、archive/daemon/ 全部 7 个文件、archive/router_js/ 3 个、archive/unrelated/chrome_pwd_extract.py(111 行)。

这是一次值得记录的判断反转，而且反转得很快、对。理由可以从结果倒推：

归档没有产生任何价值。这些文件在 95 秒内没有被任何人查阅过一次——如果有人要查历史，应该用 git（git log -p 能看到任何文件的任何版本）。项目自己 README 在 §版本管理里也是这么写的：「取某版本代码：git checkout v2.0；看某文件历史：git log -p -- <文件>」。
归档进了仓库就成了长期负担。archive/ 在 git ls-files 里是正式跟踪文件，要维护、要解释（「这堆文件是什么」是每个新人都会问的问题）。
chrome_pwd_extract.py（Chrome 密码提取脚本）本来就不该留在任何地方，即使打上「无关脚本」的标签。

留下的教训：「先归档再删除」听起来稳妥，但在有 git 的前提下是多余的中间态。正确的顺序应该是：确认要删 → 提交历史会替你记住 → 直接删。这一次多花了 95 秒和 442 行代码来制造一个没人用的缓冲区。

3.6 版本管理改用 git tag，归档仓冻结（2026-09-11 16:11）

做了什么：提交 5fc42ac，只改 README（+15 行），加「版本管理」章节。README 原文：

本仓库即项目唯一工作区，版本用 git tag 标记，不再建立版本快照目录

配套的 tag 表格把三个版本与旧的归档快照对应起来：

Tag	对应归档快照	说明
`v2.0`	2026-09-11-2.0	尖峰抓捕版（当前）
—	2026-09-01-1.1	早期版本，快照保留在归档仓 `project-artifacts`（已冻结）
—	2026-09-01-1.0	首版交付，快照保留在归档仓（已冻结）

同章宣布：「归档仓 project-artifacts 自 2026-09-11 起冻结，仅作历史存档，不再新增版本目录。」

tag v2.0 的说明：「RouterMonitor v2.0 尖峰抓捕版（对应归档 2026-09-11-2.0）」。

影响：版本管理方式正式从「目录快照」切换到「git tag」。这也解释了为什么 git 里只有 6 个提交却对应 3 个产品版本——1.0 和 1.1 发生在建仓之前，它们的历史只存在于冻结归档仓里，不在本仓库的 git 历史中。

3.7 2026-10-12：稳定性改造六项（dev，待发布）

起点问题（提交正文原文）：

问题: 10-12 当天破纪录 connect=7966 却未收到任何告警邮件。排查出两个根因。

做了什么：提交 1285843（14:40:34），6 个文件、+581 / −47。这是全项目最大的一笔代码变更，也是唯一一次由「线上事故」驱动的变更。六项内容逐条拆解见 §4.2 至 §4.6。

#	内容	改动文件
1	邮件与抓捕解耦（新增 `build_degraded_mail()`）	`spike_capture.py`
2	峰值改为延迟确认（`pending_peak` + 持续率判据）	`collect.py`
3	指数退避重试（`RETRY_DELAYS=(2,4,8)`）	`router_stat.py`、`spike_capture.py`
4	在线终端数节流 + 熔断	`collect.py`
5	采集间隔 2 分钟 → 5 分钟；`peak.check_interval_min` 5→10；计划任务触发器 PT2M→PT5M	`config.json`（不入库）+ 代码注释
6	新增 `tools/measure_router_latency.py`	新文件（192 行）
—	`.gitignore` 补 `.bak_` / `.bak.`	`.gitignore`

验证方式（提交正文原文，这段是本项目质量意识的最好体现）：

验证: 隔离测试全覆盖(重试 4/4、延迟确认回放当日真实 CSV 确认 7966 被丢弃、节流熔断 5/5), 并实发 4 封真邮件验证端到端, 含伪装登录超时真实触发降级路径。state.json 当日 max_connect 已由 7966 回滚至 4848。

四项验证的含金量：

重试 4/4：指数退避的 4 种情形（成功/网络异常重试成功/三次全失败/认证异常不重试）逐个覆盖。
延迟确认回放当日真实 CSV：不是构造假数据，是拿 2026-10-12 当天真实的 CSV 跑一遍回放，确认 7966 会被判为脏数据丢弃。这是用真实事故数据验证修复本身。
节流熔断 5/5：节流跳过/正常成功/失败计数/进入熔断/恢复五种路径。
实发 4 封真邮件：含伪装登录超时的场景——即人为制造一次超时，验证降级邮件路径真的会被触发。这一条尤其难得，因为它验证的是失败路径，而失败路径恰恰是最不容易被测到的。

另外做了数据修正：state.json 当日 max_connect 由被污染的 7966 回滚至 4848。修代码的同时修数据，这一点很关键——否则代码改对了，历史记录仍然是错的。

影响：项目从「能跑」进入「可靠」。但这笔提交至今没有合并到 main（见 §6.4）。

3.8 分支模型与待发布记录落地（2026-10-12 14:41–14:45）

做了什么：两笔纯文档提交。

41f3550（14:41:42）README +20 行，新增「分支模型」与「待发布记录」两节：

每仓两条长期分支：dev（日常开发，随时可推）/ main（正式发布，等通知）+ git tag 记版本。发布流程 = dev 合并到 main → 补 tag → ls-remote 核验。

待发布表格如实记录：

dev 提交	内容	状态
`1285843`	2026-10-12 修复峰值告警静默丢失 + 脏数据污染 + 接口稳定性改造（六项）	⏳ 待合并到 main 并补 tag

并给出后续发布命令（git merge dev → git tag -a v2.1 → git push origin main --tags → git ls-remote 核验）。

9127312（14:45:40）.gitignore 补备份规则，+5 行。提交注释：

.gitignore 补 .bak_ 规则: 原 *.bak 只匹配以 .bak 结尾, 带时间戳的备份文件(如 collect.py.bak_20261012_1356) 会漏网入库。

实际规则块与 netServer 项目完全相同（*.bak / *.bak_* / *.bak.* / *~ / *.old / *.orig）——两个项目在同一天各自踩了同一个坑并各自修了（netServer 的 29a6a35 在 14:46:34，相隔 71 秒）。

为什么两笔提交不合并成一笔：文档先行（14:41）→ 再补 gitignore（14:45），间隔 4 分钟。看起来是分两次操作完成的，没有为合并成一个提交做整理。这与 netServer 项目的做法不同——那边同样是文档与代码分开提交，但提交顺序是「先代码后文档」。这个差异是随手的，不影响正确性。

四、关键攻坚与踩坑复盘

4.1 凌晨 2:43 的 11,082 连接：一次真实的排障

这是本项目所有后续工作的起点，必须完整记录。

现象：爱快（iKuai IK-M360X，192.168.10.1）后台显示当日凌晨 2:00 前后网络连接数峰值 45,349。初步怀疑：公司电脑夜间自动升级（Windows Update）。

排查过程：靠 RouterMonitor 每 60 秒采样的 CSV 时间序列定位。分析文档记录的关键三行：

时间	连接数	上行	下行	CPU
02:42	326	18 KB/s	50 KB/s	0.9%
02:43	11,082	9 KB/s	7 KB/s	0.5%
02:44	343	13 KB/s	11 KB/s	1.0%

（本纪要撰写时直接核对了 data/router_2026-09-11.csv 的原始数据，与文档完全一致，上表可信。）

补充的三个事实：

当日基线稳定在 300–400；当日 700 个采样点中仅 02:43 一个点爆表，事件持续不足 2 分钟；
白天上班时段正常峰值为 2,000–3,800；
内存占用 26% → 30% 小幅跳变，说明爱快为突发事件分配了连接跟踪表，事件结束即回落。

根因判定（排除 Windows Update，四条理由）：

本机凌晨 0–4 点无任何 Windows Update 事件（最近一次为前一日 19:35）；
WU 默认触发在 3:00 左右，与 02:43 不符；
升级/下载行为必然伴随带宽显著上涨并持续数分钟以上——本次带宽几乎为零（9 KB/s 上行、7 KB/s 下行，比基线还低）；
单机 WU 的 NAT 连接数量级（数百）远达不到 11,082，更不足以撑起 UI 显示的 45,349。

结论（特征判定）：

2 分钟内打出上万条「短命、近乎零流量」的连接，是以下两类行为的典型指纹：
- 端口扫描 / 主机探测（内网某设备被扫描或某设备在扫描外网）
- P2P tracker announce 风暴（迅雷/BT 客户端启动瞬间向数百 tracker 发起请求）

即：某台内网设备在 02:43 短暂异常外联，而非全网段批量行为。

这次排障留下的硬伤：

爱快默认不保存历史连接明细，且当时「行为审计」未开启，因此无法回溯该时刻是哪个内网 IP 发起。

排障后的布防（2026-09-11 完成）：

RouterMonitor 增加触发式抓捕（连接数突破当日记录或 ≥8,000 绝对阈值时，自动抓全终端排行 + 明细，含协议/目标 IP/端口/应用识别/走哪条 WAN，落盘并立即邮件告警）；
爱快行为审计已开启（URL / IM / 应用识别记录均为开）；
- 遗留项：「终端记录」open_terminal_record 仍为 0，需在爱快 UI 中单独开启；只有它开启才会留存「哪台终端在何时连了什么」的历史；
采集频率调整为 120 秒/轮（计划任务调度），数据以 CSV（时间序列）+ JSON（快照明细）双格式落盘。

复现时的处理建议（分析文档第五章）：

查看邮件中的 TOP1 终端，即为元凶 IP（捕获数据同时存档在 data/capture/<时间戳>/）；
看该终端连接的应用识别名与目标 IP：出现「未知P2P」或大量境外 IP、随机高位端口 → P2P/异常外联；
去该终端上确认是否有下载类软件在后台运行，或杀毒扫描。

沉淀的经验：

「只有聚合数字」在排障上是死的。「连接数 11,082」这个数字能让 IT 排除掉三种假设，但无法指向任何一个 IP。只有「那一刻的逐条连接明细」能指向一个具体设备。 这是 v2.0 全部设计的出发点。
带宽是区分「流量型行为」和「连接数型行为」的最好指标。判断第 3 条理由（升级必然伴随带宽上涨）本质上是一个交叉验证：如果 X 行为成立，B 指标应该同步变化；实测 B 没变，所以 X 不成立。 这个推理模式比事后看日志更快。
采集频率决定了排障能力的上限。1.0 的 60 秒采样抓住了 2 分钟的尖峰（虽然只抓到 1 个点），这已经是运气好；如果事件只持续 40 秒，60 秒采样会直接漏掉。监控系统的价值在事故当天就已经兑现了——这不是事后补的文档。
一个诚实的分析文档比一个漂亮的结论更有价值。这份文档没有假装定位到了元凶，而是明确写「无法回溯」，并把它转化成两个可执行的动作（触发式抓捕 + 开启行为审计）加一条遗留项。

4.2 告警静默丢失：邮件被挂在抓捕后面

现象：2026-10-12 当天破纪录 connect=7966，一封告警邮件都没收到。

排查过程：从「系统看起来正常」入手——峰值记录照常更新了。提交正文的诊断很准：

spike_capture.check() 原把发信放在"抓终端排行成功之后", fetch_terminal_rank 超时即 return None, 发信代码根本没机会执行。峰值记录却照常更新, 表面看系统正常实则静默失败。

根因：这是一次典型的静默失败设计。原代码结构（现已重构）：

try:
    cookie = _login(url, ...)
    rows = fetch_terminal_rank(url, cookie)     # ← 这里超时
except Exception as e:
    logging.error(msg)                          # 只记日志
    rows = None                                 # ← rows 变 None

if rows is None:
    ...                                        # ← 直接结束，什么都不发
# ... 只有 rows 不为 None 才会走到 send_mail()

三个问题叠加成一个致命缺陷：

发信被耦合在抓捕成功之后——详情抓取失败，等于告警失败；
失败被 logging.error() 记录到 logs/error.log，但没人看日志；
最致命的一点：峰值记录照常更新。也就是说所有「看起来正常」的指标都是正常的——state.json 里 max_connect 是对的、CSV 有数据、下次运行也正常。没有任何一个表层信号能暴露这个失败。

修法：新增 build_degraded_mail()，邮件与抓捕解耦。

现在的代码（spike_capture.check() 内）：

except Exception as e:
    # ★ 降级: 抓捕失败不再静默退出, 改为发简报邮件 (2026-10-12 方案A)
    capture_err = str(e)
    logging.error(msg)
    with open(... / "error.log", "a", encoding="utf-8") as f:
        f.write(f"{when} {msg}\n")
    rows = None

if rows is None:
    # ---- 降级路径: 发简报邮件 + 更新基准, 保证告警不丢 ----
    subject = f"... 连接数 {total_connect} 创当日新高（详情抓取失败）"
    body = build_degraded_mail(total_connect, device_count, when, info,
                               trigger_text, capture_err)
    send_mail(cfg, subject, body)
    logging.info(f"已发送降级简报邮件 (抓捕失败, connect={total_connect})")

    if not force:
        day["capture_base"] = total_connect        # 基准照常更新
    state["spike_capture"] = {..., "last_degraded": True, "last_error": capture_err[:200]}
    ...
    return {"time": when, "total": total_connect, "rows": None, "detail": [],
            "degraded": True, "error": capture_err}

降级邮件的内容（build_degraded_mail() 生成的正文结构）刻意做成「坏消息要能独立说清楚」：

路由器连接数监控 - 峰值告警（简报，详情抓取失败）
==============================================
告警时间 : 2026-10-12 13:1x:xx
触发原因 : 连接数 7966 突破当日记录(前 ...), 且 ≥ 上次触发值 ...×1.5
总连接数 : 7966   (触发前当日记录 2916)
在线终端 : 101 台

── 详情抓取失败 ──
原因 : <具体异常>
说明 : 路由器管理接口在抓取终端排行时无响应（多为接口超时），
        本封仅携带核心告警信息，终端榜单与连接明细缺失。
        监控采集本身仍在继续，数据未中断。

如需排查可查看 RouterMonitor/logs/error.log。
本邮件由 RouterMonitor 自动发送。

三个设计细节值得学：

收件人不需要做任何额外动作就能判断发生了什么——标题里就带「（详情抓取失败）」，正文有明确分隔线。
明确告知「数据未中断」——避免收件人误以为整个监控挂了而做过度反应。
降级时基准照常更新（day["capture_base"] = total_connect），并记 last_degraded: True + last_error 到 state.json。基准更新是对的（那次连接数确实达到了），同时留了降级痕迹可查。

验证方式：「实发 4 封真邮件验证端到端，含伪装登录超时真实触发降级路径」——即人为把登录搞超时，验证降级邮件真的会发出来。

沉淀的经验：

「告警」和「告警的详情」必须解耦。告警的职责是「通知有事发生」，把「查明是什么事」的责任绑在告警链路上，等于让辅助功能（详情抓取）的失败吞掉主要功能（通知）。这是典型的关键路径依赖非关键路径的设计错误。
静默失败最危险的地方是「其他指标都正常」。这里 max_connect 正确更新、CSV 正常写入、下次运行正常——如果只做表面检查，100% 发现不了。判据应该是「该发生的事有没有发生」，而不是「已有的状态对不对」。
降级比失败好，但降级路径必须被测试。写 build_degraded_mail() 不难，难的是意识到降级路径需要单独测试——它平时不执行，恰恰最容易坏。这次的做法（伪装登录超时实发真邮件）是这个项目里最扎实的一次验证。

4.3 脏数据伪装成峰值：7966 是怎么来的

这是同一起事故的第二个根因，也是更隐蔽的一个。

现象：state.json 里当天 max_connect 被记成 7966，但 2026-10-12 13:11 前后实际连接数在 2,800–3,700 之间。

排查过程：本纪要撰写时直接核对了 data/router_2026-10-12.csv 的原始数据，与提交正文描述完全一致：

2026-10-12 13:11:39,7966,99467,160996,943264261567,4620467574871,7.87,28%,699.9,5,
2026-10-12 13:13:39,2927,112526,5532055,943283002393,4620744367189,9.07,29%,695.7,5,101
2026-10-12 13:15:39,2997,79133,978894,943294063676,4620847697761,3.78,28%,700.8,5,99

7966 前后两行分别是 2927 和 2997。提交正文的诊断：

7966 实为 API 超时重试返回的半截响应（下一轮直接掉到 2927, 前后均 2800~3700, 带宽与累计流量无对应变化）。

「带宽与累计流量无对应变化」这一条是关键的交叉验证——如果真有 7,966 条连接，累计流量 total_up_bytes/total_down_bytes 必然有对应增量。实测该行累计流量与前后行连续，说明网络侧根本什么都没发生。

（对照 2026-09-11 的真尖峰：509772531039 → 509773376745，累计上行 2 分钟涨了 845,706 字节——这才是真连接数。同一个 CSV 字段，在两个事件里给出了相反的答案，这就是最好的交叉验证工具。）

根因：路由器 API 在超时重试时返回了半截/错位响应，Python 把它当成合法整数解析了。接口层没有做数值合理性校验，脏数据一路畅通无阻地：

路由器半截响应 → sysstat 解析（无校验）→ 写入 CSV（无校验）→ check_peak 读 CSV 求 MAX（无校验）→ 入账 max_connect → 发邮件

修法：峰值入账前做持续性判定，且用延迟确认机制（详见 §4.4）。

数据修正：state.json 当日 max_connect 已由 7966 回滚至 4848。

沉淀的经验：

外部系统的返回值永远是不可信输入。半截响应不是 HTTP 异常，是「一个看起来合法的错误数字」。凡是跨系统取数的地方都要有 sanity check（数量级、与相邻样本的关系、与累计量的一致性）。
「派生指标之间应当一致」是最好的脏数据检测器。这里用的是：连接数 ↔ 累计流量 ↔ 带宽，三者物理上必须联动。这比任何单字段的合法性校验都强。
监控系统的数据要能被人复查。这次能发现脏数据，正是因为有 43 天连续的 CSV。如果只有 state.json 里的一个 max_connect，7966 就是「一个事实」，永远查不出问题。
修代码的同时要修数据。这次把 max_connect 回滚到 4848 是必要动作——否则新代码上线后，历史记录仍然是错的，而错误的历史记录会误导下一次阈值标定。

4.4 峰值延迟确认：一个走不通的方案和它的替代品

起点问题：如何在入账前判断一个新峰值是真的？

走不通的第一个方案（提交正文明确记录了否决过程，这是本次改造最有价值的部分）：

注: 最初想用「与邻域最大值比率」, 但实时运行时后续数据尚未产生无法判断, 该方案不可行, 故改为延迟确认机制。

这个死结值得说清楚：check_peak() 是实时运行的。它读到 CSV 里最新的最大值时，后面 10 分钟的数据还不存在。任何「看后续数据」的判据都无法实时执行。这是一个看起来很自然、实则根本无法实现的思路。

替代方案：延迟确认（方案A, 修订版，代码注释里标了版本演进）

核心常量：

CONFIRM_DELAY_MIN = 10       # 延迟确认窗口：10 分钟
SUSTAIN_THRESHOLD = 0.5      # 持续率阈值

判据定义：持续率 = 峰值发生后 10 分钟内的最大连接数 ÷ 峰值

阈值标定（提交正文）：

全历史 3.3 万样本统计, 真峰值持续率 0.55~0.76, 脏数据 0.04~0.42, 阈值取 0.5。

这是一个中间有明确间隔带的分布——真峰值最低 0.55，脏数据最高 0.42，阈值 0.5 落在正中间，两侧都有 0.05+ 的余量。如果两个区间重叠，阈值就不可靠；这里不重叠，说明判据是有区分力的。

机制流程（check_peak()）：

每 10 分钟执行 check_peak():
  ├─ [1] 先处理上一轮挂起的 pending_peak
  │     ├─ 还没到 10 分钟确认点，且发现更大的候选 → 直接替换候选
  │     └─ 到确认点：
  │           after = [峰值后 0~600 秒内的所有有效样本]
  │           sustain = max(after) / pending["connect_num"]
  │           ├─ sustain ≥ 0.5 → 确认为真峰值
  │           │     ├─ max_connect = pending
  │           │     ├─ 记录 peak_row
  │           │     ├─ pop pending_peak
  │           │     └─ 满足条件则发信（当前 peak.send_mail=false，故不发）
  │           └─ sustain < 0.5 → 判为脏数据
  │                 ├─ pop pending_peak
  │                 └─ 记入 rejected_peaks（只留最近 20 条，防反复入队）
  │
  └─ [2] 求当前最大候选 → 写入 pending_peak（不立即入账）

三个细节做得很到位：

候选替换：确认窗口内若出现更大的峰值，直接替换候选。这样一个「10 分钟内的持续爬坡」不会被拆成多个假峰值——候选永远是窗口内最大的那个。
rejected_peaks 防反复入队：脏数据被丢弃后记进 rejected_peaks（保留最近 20 条），防止同一个 7966 在下一轮又被选为候选、再判一次、再丢弃。这是必需的——否则每次检查都会重复处理同一条脏数据，浪费且污染日志。
非法值单独剔除：connect_num <= 0 的行被显式剔并 logging.warning 记录，不参与判定。这是另一层基础的合法性检查。

代价（必须如实记录）：

真峰值的告警延迟 10 分钟。这是设计内的代价，提交正文说得很直接：「既不漏真峰值(延迟发信)，也不让脏数据污染峰值记录/发假警」。
但注意：spike_capture.check() 的抓捕告警不受影响，它是立即的。只有 peak 那条路径延迟。而 peak.send_mail 当前是 false，所以实际上没有任何用户可见的延迟——延迟的只是 state.json 里 max_connect 的更新时刻。这是一个纯内部的状态机制。
如果将来把 peak.send_mail 打开，这个 10 分钟延迟就会变成用户可见的。届时需要重新权衡。

沉淀的经验：

遇到「实时判断需要未来数据」的死结时，要敢于改架构而不是改指标。第一个方案（邻域比率）的思路不算错，错在它隐含了「能立刻拿到后续数据」这个不可能的前提。延迟确认本质上是把「判断时点」从「事件发生时」推迟到「证据充分时」——这是在实时系统里引入确认延迟的经典手法。
阈值要靠历史数据标定，不能拍脑袋。3.3 万样本、真峰值 0.55~0.76 vs 脏数据 0.04~0.42——这个分布本身就是判据有效性的证据。更重要的是它暴露了不重叠，这是敢用 0.5 的前提。
纯 CSV 存储在这个场景下成了优势。延迟确认需要「回看这个峰值之后 10 分钟的数据」，也就是必须能随机访问全天的历史样本。如果数据在时序数据库里按窗口存储，这个功能要另外设计；现在读一下当日 CSV 就行。弃用 DuckDB 的决定在这里兑现了。
丢弃的东西也要记录。rejected_peaks 存了时间、值、持续率（保留 20 条）。这不只是防重复入队，更是给人看的——如果某天持续率都在 0.4 附近，说明阈值需要重新标定。没有这份记录，阈值的漂移是看不见的。

4.5 最重的接口却必须保留：device_num 的节流熔断

现象：在线终端数接口慢到离谱，而且大量失败。

实测数据（README 专设一节记录，2026-10-12 网络空闲时测得）：

接口	耗时
API 主统计（verinfo/stream）	12 ms
API 在线终端数（monitor_lanip）	136 ms（慢 11.7 倍）

但这个字段不能丢。README 给出的理由斩钉截铁：

该字段必须保留——没有终端数作分母，连接数没有参考意义。

也就是说，「3,000 条连接」单独看没有意义，「3,000 条连接 / 114 台终端 = 每台 26 条」才是有意义的指标。这是 v2.0 特意新增的字段，也是这个项目区别于「单纯看连接数」的关键。

裸调用的两个代价（README 原文）：

失败即占满 timeout（原 8s），整轮采集被拖住；
远控时段极易超时 —— 2026-10-12 当天失败 353 次，且仍在每轮傻试。

353 次失败这个数字很有说服力：不是偶发故障，是常态化的失败，而代码里没有任何反馈机制，所以「353 次」这件事本身也是事后统计才发现的。

修法：collect.py::_get_device_count_throttled()，四个参数三层机制：

参数	值	作用
`DEVICE_COUNT_INTERVAL_SEC`	300	正常 5 分钟查一次（该值变化很慢，不必每轮）
`DEVICE_COUNT_TIMEOUT`	5	超时收紧到 5s，快速失败留给退避重试
`DEVICE_COUNT_FAIL_THRESHOLD`	3	连续失败 3 次进入熔断
`DEVICE_COUNT_COOLDOWN_SEC`	1800	熔断冷却 30 分钟，期间完全不再请求

代码实现（摘录关键分支）：

# ---- 熔断判定: 冷却未到则直接跳过 ----
if last_try and fail_streak >= DEVICE_COUNT_FAIL_THRESHOLD:
    since = (now - fromisoformat(last_try)).total_seconds()
    if since < DEVICE_COUNT_COOLDOWN_SEC:
        dc_state["state"] = "cooldown"
        save_state(cfg, st)
        return None                    # 完全不请求

# ---- 节流: 正常间隔未到则跳过 ----
if last_try and fail_streak == 0:
    if since < DEVICE_COUNT_INTERVAL_SEC:
        return None                    # 不请求

try:
    dc = spike_capture.fetch_device_count(cfg, timeout=DEVICE_COUNT_TIMEOUT)
except Exception:
    dc = None

if dc is not None:
    dc_state["fail_streak"] = 0
    dc_state["state"] = "ok"
    if fail_streak:
        logging.info(f"在线终端数已从熔断恢复: {dc} (连续失败 {fail_streak} 次后成功)")
    return dc

fail_streak += 1
dc_state["state"] = ("cooldown" if fail_streak >= DEVICE_COUNT_FAIL_THRESHOLD
                     else "degraded")

五个设计要点：

三档状态区分：ok / degraded（失败但未到熔断）/ cooldown（熔断中）。不是简单的布尔。这样能区分「偶发失败」和「已经放弃」。
取不到时返回 None 而不是写 0。main() 里 device_num = ""，CSV 该列为空。不写脏数据——这与 §4.3 修复的脏数据问题是同一个原则。实测 CSV 里能看到大量空值，正是节流在起作用。
恢复时打日志：在线终端数已从熔断恢复: 57 (连续失败 353 次后成功) 这类日志让人能确认熔断确实在生效也确实在恢复。
状态持久化在 state.json.device_count：fail_streak / state / last_try_ts / last_ok_ts / last_value。跨进程存活——因为每次执行都是新进程，状态必须在文件里。
错峰：代码注释说明策略之一是「①错峰, 不与主采集同秒, 改到本轮末尾」——主统计先采，设备数最后采。两个请求不并发。

顺带调整的两处关联配置：

采集间隔 2 分钟 → 5 分钟。既然最重的接口要节流到 5 分钟，把整个采集周期压到 2 分钟就没意义了。
peak.check_interval_min 同步 5 → 10。提交正文特别说明了原因：「须 >= 采集间隔, 否则比对比采集还频繁白跑」。这是一个配置项间的隐含约束。

沉淀的经验：

「必须保留但代价很高」的字段，正确做法是节流 + 熔断，而不是删掉或裸调用。删掉会丢失「分母」这个关键上下文；裸调用会拖垮整条链路。这两条都不对。
超时收紧（8s → 5s）+ 快速失败 + 退避重试，是一整套配合。单独收紧超时只会让失败来得更快；单独加重试会在慢接口上放大请求量。
熔断状态必须持久化，且要有恢复路径。熔断最常见的失败形态是「熔断了但永远不恢复」。这里的设计是「冷却结束或任意一次成功即自动恢复正常间隔并重置计数」——两条恢复路径都有。
返回值要能表达「取不到」。返回 None 而不是 0，让上层能区分「0 台设备」（不可能且可疑）和「没查到」。这个区分直接避免了 §4.3 那类脏数据。
节流效果可以在 CSV 里直接看到（§2.3 的实测片段）。可观测性做在数据里，比做在日志里更难被忽略。

4.6 会话失效与「向日葵效应」

两个相关但独立的机制，都记在这里。

机制一：会话失效自愈

爱快接口认证失效时返回的错误码特征（router_stat.py）：

AUTH_ERROR_HINTS = ("no login", "10014", "not login", "unauthorized", "401")

处理流程：

_post() 捕获异常 → is_auth_error(exc) 判定 → 认证类错误立即上抛，不重试；
上层用 config.json → capture.auth 里的只读账号（不是 admin）自动重新登录拿新 sess_key；
重试一次；
仍失败则记 logs/error.log。

关键决策：区分「网络类异常」和「认证类异常」。这正是指数退避重试（RETRY_DELAYS=(2,4,8)）的前提：

仅网络类异常重试，认证类错误（is_auth_error）立即上抛不重试

重试的异常白名单也很明确：

RETRY_DELAYS = (2, 4, 8)   # 指数退避秒数
RETRY_EXCEPTIONS = (urllib.error.URLError, TimeoutError, socket.timeout, OSError)

为什么必须区分：会话失效时，重试 3 次全是必然失败（每次都是同一个 10014），只是白等 2+4+8=14 秒。正确做法是立刻重新登录。

机制二：向日葵效应（已知外部干扰源）

README 把这个单独记为「已知外部干扰源」：

向日葵远程会话期间路由器管理接口显著变慢（刘实测确认）。规避方式：不用远程时主动断开向日葵连接。tools/measure_router_latency.py 可在任意时刻采集 ping / HTTP / 各接口耗时基线用于排查。

为了验证这个假设，专门写了 tools/measure_router_latency.py（192 行）。工具的文档字符串把用途说得很清楚：「用途: 验证『向日葵远程会话期间路由器管理接口变慢』这一现象，并为后续优化提供量化基线」。

这个工具还有一个细节值得记（属于工具安全守则）：

★ 使用注意 (2026-10-12 刘提醒):
本脚本会访问内网路由器。在 WorkBuddy 会话里调用时, 命令行只写脚本路径, 不要在命令行或临时脚本里直接写内网 IP / URL —— 那会触发 WorkBuddy 的「等待人工点击确认」安全弹窗, 用户不点任务就会卡死。
正确用法: python tools/measure_router_latency.py -n 5

为什么这个细节重要：如果把 http://192.168.10.1/... 写在命令行里，AI 工具环境的安全策略会弹确认框，用户不点，任务就卡死。解决办法是让 IP 从 config.json 读取（代码注释：「路由器地址与凭据一律从上级 config.json 读取, 不在此硬编码」），命令行只有脚本路径 + 参数。

这是一个人机协作层面的工程细节：AI 工具的安全弹窗机制和自动化脚本的无人值守需求天然冲突，解法是把敏感参数移进配置文件，让命令行变得「无害」。

工具还声明了只读性：「只读操作: 仅发 ping 与只读 API 请求, 不改任何配置、不写业务数据」。

沉淀的经验：

重试策略必须区分错误类型。「网络抖动重试、认证失败上抛」是所有接口调用的基本功。不区分的后果是：认证失效时白等 14 秒，而且日志里全是无意义的重试记录。
指数退避的三个值（2/4/8）是权衡出来的。对一个每 5 分钟跑一次的任务，退到 8 秒上限已经足够（总代价 14 秒 vs 5 分钟的周期，容忍度很高）。退避上限应该和调用周期挂钩，不是越大越好。
「某个外部软件会拖慢我们」这类经验，必须能被验证。写一个专门的测量工具，把「主观感觉变慢」变成「可复现的延迟基线」，这条经验才能被后来者信任和使用。这比在文档里写一句「向日葵会拖慢」有价值得多。
只读账号的权限最小化：capture.auth 用的是只读账号而非 admin。这意味着即使这个凭据泄露，攻击者也只能读。这个细节做得很对。

五、质量保障与验证机制

这个项目没有测试文件（git ls-files 确认：11 个文件，0 个测试）。质量手段是「实发验证 + 数据回放 + 文档化约定」三条腿。

5.1 验证手段一：实发真邮件（端到端）

这是本项目最有特色的验证方式——验证告警系统必须真的发信，用假邮件验证等于没验证。

1285843 提交的验证记录：

并实发 4 封真邮件验证端到端, 含伪装登录超时真实触发降级路径。

四封邮件覆盖：正常路径、降级路径（伪装超时）、重试路径等。收件人是真实的人（117801633@qq.com），所以「收到」本身就是验证结论。

「伪装登录超时」这个手法尤其值得记：它验证的是失败路径，而失败路径恰恰最容易坏、也最不容易被测到。主动制造一次真实故障来验证降级逻辑，比写单元测试更贴近真实。

5.2 验证手段二：真实数据回放

延迟确认机制（§4.4）的验证方式是：拿事故当天的真实 CSV 回放一遍，确认 7966 会被判为脏数据丢弃。

这条验证的价值在于：输入是真实脏数据，输出是可验证的确定结论。构造假数据的话，判据可能只是碰巧对；用真数据回放，能确认修复真的解决了那次事故。

5.3 验证手段三：隔离测试（分项计数）

提交正文用计数的方式记录分项覆盖：

测试项	覆盖
重试	4/4（成功 / 网络异常重试成功 / 三次全失败 / 认证异常不重试）
节流熔断	5/5（节流跳过 / 正常成功 / 失败计数 / 进入熔断 / 恢复）
延迟确认	回放真实 CSV
端到端	实发 4 封真邮件

用「N/N」而不是「已测试」来记录覆盖率，这是个值得学的小习惯——它可核对，也让人一眼看出漏了什么。

5.4 数据交叉验证（无意识的验证手段）

这个项目没有刻意的数据校验，但实际形成了交叉验证：

校验点	方法
连接数 vs 累计流量	11,082 真尖峰时 `total_up_bytes` 2 分钟涨 845,706 字节；7966 脏数据时累计流量无变化
连接数 vs 相邻样本	11,082 前后是 326/343；7966 前后是 2927/2997
连接数 vs 带宽	真尖峰带宽无异常（说明是「连接数型」而非「流量型」行为）
`device_num` 的空值分布	节流生效的直接证据

§4.1 的排障和 §4.3 的脏数据识别，用的是同一套字段的不同组合——这说明这套数据模型本身就具备了可诊断性，是个好设计的副产品。

5.5 凭据与数据隔离

措施	实现	生效提交
真实配置不入库	`.gitignore` 含 `config.json`	`a3bd48b`
agent 邮箱配置不入库	`.gitignore` 含 `agentmail_config.json`	`a3bd48b`
token 缓存不入库	`.gitignore` 含 `data/.mail_tokens.json`	`a3bd48b`
运行数据不入库	`.gitignore` 含 `data/`、`logs/`、`state.json`	`a3bd48b`
工具元数据不入库	`.gitignore` 含 `.workbuddy/`	`a3bd48b`
脱敏模板入库	`config.example.json`，敏感字段用 `<占位符>` 而非留空	`a3bd48b`
采集账号权限最小化	`capture.auth` 用只读账号而非 admin	v2.0
备份文件不入库	`.bak`、`~`、`.old`、`*.orig`	`9127312`
测量脚本不硬编码凭据	从 `config.json` 读取，命令行只写脚本路径	`1285843`

config.example.json 的模板质量值得单独说一句：敏感字段用 <路由器管理员密码>、<爱快只读账号>、<该账号密码>、<SMTP 授权码>、<发件邮箱>、<收件邮箱> 这种尖括号占位符，而不是留空。留空会让人以为「不需要填」；尖括号明确表示「这里必须填，而且我知道该填什么类型」。

5.6 文档化约定（代替代码防护）

有几个已知问题，选择了写进文档而不修：

问题	约定	为什么这么定
CSV 被 Excel 独占锁 → `Permission denied`	「关掉文件即自动恢复；不需改代码」「不做重试/转存等特殊处理」	人类日常会打开这个文件，是必然事实；加特殊处理会让这个事实更不可控
PowerShell 传中文路径失败	「工具环境下会失败，改用 bash 或 `[char]` 拼码点」	环境限制，改代码无用
向日葵远程拖慢接口	「不用远程时主动断开向日葵连接」	外部软件行为，无法从代码侧解决
邮件兜底队列依赖外部定时任务	`pending_email.json` + WorkBuddy 每小时任务	（见 §7，这是个真隐患而非合理约定）

前三条是合理的工程约定（承认限制、说明为什么不修）；第四条是待改进项。区分这两类是写文档时的必要判断。

六、构建、部署与归档

6.1 构建与运行方式

无构建步骤。纯 Python 脚本 + 标准库，无第三方依赖，无打包。

运行入口：

python collect.py --task        # 计划任务入口（跑一轮即退出）
python collect.py --verbose     # 单次采集调试（会写入 CSV）
python spike_capture.py --force # 手动强制抓取（会发邮件）
python router_stat.py           # 查看路由器状态
python tools/renew_token.py --status   # 检查会话有效性
python tools/measure_router_latency.py -n 5   # 延迟基线采集

依赖：只 import 标准库（urllib / csv / json / logging / datetime / argparse / statistics / subprocess / uuid / socket / random / time / os / sys）。没有 requirements.txt——这是「无依赖」带来的最大好处：换机器不需要装任何东西。

6.2 部署路径与调度配置

本地工作区   D:\LJH\项目\RouterMonitor      （仓库即唯一工作区，直接在开发机上跑）
                ↓ push
云效 Codeup  git@codeup.aliyun.com:62bc7cf811fc0f0c9e2aedb2/guxin-it/RouterMonitor.git
                ↓ git clone
Windows 计划任务  RouterMonitor_Collect
                  ├─ 触发器：PT5M（2026-10-12 由 PT2M 改为 PT5M）
                  ├─ 权限：S4U（未登录也能运行）
                  └─ 动作：python collect.py --task
                        ↓
                  data/ + logs/ + state.json（本地，不入库）

调度配置在两处，2026-10-12 改动时两处都改了：

位置	配置项	当前值
`config.json`（代码侧，不入库）	`collect.interval_sec`	300
Windows 计划任务触发器（系统侧）	重复间隔	PT5M

这两处必须手动保持一致，代码无法校验。（peak.check_interval_min 的上下界关系同样无自动校验。）

当前实测配置（从 config.json 读出，已脱敏）：

"collect": {"interval_sec": 300, "scheduler": "windows_task",
            "task_name": "RouterMonitor_Collect"},
"peak":    {"check_interval_min": 10, "send_first_baseline": false,
            "send_mail": false},
"capture": {"trigger": {"grow_ratio": 1.5, "min_connect": 3000,
                        "abs_threshold": 8000},
            "cooldown_sec": 180, "detail_top": 5, "detail_min_conn": 5}

注意 config.example.json 里的 interval_sec 仍是 120、check_interval_min 仍是 5，而实际 config.json 是 300 / 10。模板没有跟上 2026-10-12 的改动（见 §7.2）。

6.3 Codeup 归档过程

仓库建立：2026-09-11 15:39，提交 a3bd48b（24 文件 / +2544）——一次全量导入。仓库位于云效代码组 guxin-it（组 ID 62bc7cf811fc0f0c9e2aedb2），私有。group_remotes.json 记录了同组 7 个仓库，这是其中之一。

旧归档仓的处理（这一步的背景必须记清楚）：

早期版本（1.0 / 1.1）以目录快照形式存在于归档仓 project-artifacts；
2026-09-11 该仓从云端删除，快照转为本地冻结存档：D:\LJH\产物归档\project-artifacts_del\RouterMonitor\（含 2026-09-01-1.0 / 2026-09-01-1.1 / 2026-09-11-2.0 三个目录）；
同日（5fc42ac）README 宣布：「归档仓 project-artifacts 自 2026-09-11 起冻结，仅作历史存档，不再新增版本目录」。

版本管理方式的切换：

旧：目录快照（产物归档/project-artifacts/2026-09-11-2.0/…）—— 手工、重复、易漏
新：git tag（v2.0）—— 自动、可 checkout、可追溯

README 明确写：「本仓库即项目唯一工作区，版本用 git tag 标记，不再建立版本快照目录」。

注意一个后果：1.0 和 1.1 的历史不在本仓库的 git 里。git log 只有 6 个提交（最早 2026-09-11），而产品版本有三个。想看 1.0 的代码只能去冻结归档仓。README 的 tag 表格用「—」标出这两个版本并指向归档仓，做了说明。

tag 清单（git ls-remote 核验）：

Tag	指向 commit	说明
`v2.0`	`5fc42ac`	RouterMonitor v2.0 尖峰抓捕版（对应归档 2026-09-11-2.0）

分支模型（41f3550 确立，写进 README）：

每仓两条长期分支：dev（日常开发，随时可推）/ main（正式发布，等通知）+ git tag 记版本。
发布流程 = dev 合并到 main → 补 tag → ls-remote 核验。

README 同步：这个项目的 README 维护得相当好。变更记录逐条记录了从 2026-09-01 到 2026-10-12 的 6 个节点，每个节点都写清了「改了什么」和「为什么」。1285843 那次甚至在 README 里展开了六项改造的完整说明（含触发判据的量化数据）。

远端核验结果（本纪要撰写时用 git ls-remote origin 实测）：

5fc42acd598dbeccc4f3f5f009e192fdbe8e6150    HEAD
912731281b465c0210b4031b73d76785c80be444    refs/heads/dev
5fc42acd598dbeccc4f3f5f009e192fdbe8e6150    refs/heads/main
d12ee8bd6714629e368e19b9c0cc714b35913e85    refs/tags/v2.0
5fc42acd598dbeccc4f3f5f009e192fdbe8e6150    refs/tags/v2.0^{}

本地与远端完全一致，无未提交变更。

6.4 如实说明：哪些已发布、哪些仍在 dev

内容	提交	所在分支	状态
v2.0 完整功能（尖峰抓捕、JSON 落盘、计划任务调度、凭据隔离）	`a3bd48b`	main ✅	已发布
删除 archive/	`29d5a09`	main ✅	已发布
版本管理改 git tag，归档仓冻结	`5fc42ac`	main ✅	已发布（tag `v2.0`）
稳定性改造六项（告警解耦、延迟确认、重试、节流熔断、间隔调整、测量工具）	`1285843`	dev	⏳ 待合并到 main 并补 tag（v2.1）
README 分支模型与待发布记录	`41f3550`	dev	⏳ 随 v2.1 一起发布
.gitignore 补备份规则	`9127312`	dev	⏳ 随 v2.1 一起发布

⚠️ 这是一个需要明确提醒的状态：

2026-10-12 的稳定性改造至今没有合并到 main、没有打 tag，但修复已经在生产运行。这意味着：

线上跑的代码不在 main 上。任何按「checkout main 就能拿到最新生产代码」操作的人，拿到的是 2026-09-11 的版本——没有告警解耦、没有延迟确认、没有节流熔断。如果有人在服务器上重新 clone 并重启，会把已修复的 bug 恢复回去。
README 里的「待发布记录」表格如实记录了这个状态（1285843 ⏳），这是好的——状态是明确的、可查的。
风险窗口 = 自 2026-10-12 至今（今天 2026-10-13，约 1 天）。dev 与 main 的差距是 3 个提交。

README 已给出发布命令：

git checkout main && git merge dev        # 合并
git tag -a v2.1 -m "..."                  # 补 tag
git push origin main --tags               # 推 main 与 tag
git ls-remote origin refs/heads/main refs/tags/v2.1   # 核验

这是本次纪要最需要向负责人提醒的一条（详见文末异常提示）。

七、遗留问题与后续计划

以下全部基于 git 记录、README 与运行数据中可佐证的事实，未记录的项不做推测。

7.1 已明确记录但未完成的布防项

项	出处	状态
爱快「终端记录」`open_terminal_record` 仍为 0	`docs/2026-09-11-凌晨连接数尖峰分析.md` 第四章	❌ 未开启。分析文档写明「需在爱快 UI 中单独开启；只有它开启才会留存『哪台终端在何时连了什么』的历史」
早期包体的追踪（1.0/1.1）超出本仓库	git 历史从 2026-09-11 起	⚠️ 代码只存在于本地冻结归档仓 `D:\LJH\产物归档\project-artifacts_del`，该仓云端已删除

第一项是能力上的实质缺口。尖峰分析文档里 v2.0 的抓捕机制只能覆盖「RouterMonitor 抓到的那一刻」；如果某次异常发生在非采集时刻，或者 RouterMonitor 停了，抓捕就不会发生。行为审计里的「终端记录」才是全时段覆盖，这两者互补。当前只做了一半。

7.2 文档与代码不一致（需修正）

config.example.json 与 config.json 不同步。模板里 collect.interval_sec = 120、peak.check_interval_min = 5；实际运行值是 300 / 10。2026-10-12 改了 config.json（不入库）但没同步模板（入库）。按模板重建配置的用户会拿到 2 分钟采集 + 5 分钟峰值检查，而且这个组合恰恰是提交正文指出的「比对比采集还频繁白跑」的错误配置。
collect.py 模块文档字符串仍写 120 秒 / 5 分钟。开头写「由 Windows 计划任务 RouterMonitor_Collect 每 120 秒调用一次」，功能 5 写「每 5 分钟执行一次『当日连接数峰值』检查」——实际已是 300 秒 / 10 分钟。
README 目录结构一节未列出 tools/measure_router_latency.py。该文件在 2026-10-12 已新增（192 行），README 的目录树里 tools/ 下只有 plot_spike.py 和 renew_token.py。不过 README 正文在「在线终端数节流熔断」一节提到了这个工具——正文更新了，目录树漏了。
config.example.json 的 mail.sender 是占位符，但代码里有硬编码默认值。send_mail_direct.py 里 SENDER = "liujinhui@agent.qq.com"、DEFAULT_TO = "117801633@qq.com"，而实际 config.json 的 mail.sender 是 jinhuiliu@vip.qq.com、receiver 是 117801633@qq.com。README 写「发送：agent 邮箱 liujinhui@agent.qq.com → 接收 117801633@qq.com」。发件地址在代码与配置之间存在两处，行为取决于走哪条通道（agent 邮箱直发 vs SMTP），容易混淆。
.gitignore 有重复规则块。文件里 *.bak / *.bak_* / *.bak.* 出现了两次（一次在「系统」段 9127312 加的，一次在「备份文件」段 29a6a35 风格的块里）。功能上无害（重复规则不生效两次），但说明两笔改动是分别加的、没有合并整理——同一个坑在同一个仓库里修了两次。

7.3 架构与技术债（自查得出）

债	位置	影响
告警单点	邮件 → 直发失败 → `pending_email.json` 队列 → 靠 WorkBuddy 每小时定时任务补发	🔴 高。告警系统自己依赖另一个调度器；那个调度器挂了，兜底队列就永远堆积
配置两处手动同步	`config.json` 的 `interval_sec` vs Windows 计划任务触发器	中。改了代码侧忘了改系统侧，采集频率静默不一致
配置项间约束无校验	`peak.check_interval_min` 必须 ≥ `collect.interval_sec`	中。加载时不校验，忘了改就「比对比采集还频繁白跑」
**`collect.py` 职责过载`	一个文件含采集 + 峰值判定 + 邮件构造 + CSV 读写 + 状态管理	中。2026-10-12 改 4 个层面的东西要动 221 行
无自动化测试	0 个测试文件	中。验证靠实发邮件和数据回放，无法重复执行
接口返回值无 sanity check	`sysstat` 解析后直接用	中。半截响应能一路通到 `max_connect`（已靠延迟确认补救，但根因未在解析层拦截）
鉴权用 admin 会话登录	`_login()` 用 `capture.auth`（只读账号）✅，但 `router_stat.DEFAULT_URL` 硬编码	低
`data/` 无清理策略	43 天 CSV 累计约 3 MB + 31 个快照	低。`capture/` 增长更快
备份文件散落	目录里 5 个 `.bak_20261012_*`	低。已 gitignore 挡住入库

7.4 已出现但未见处理的运行时信号

现象	证据	说明
2026-10-12 在线终端数失败 353 次	提交正文记录	改造后应有改善（熔断冷却 30 分钟），但改造后的失败次数无记录，无法确认改善幅度
首个快照 `total_connect = 99999`	`data/capture/20260911_151244/summary.json`	`--force` 手动测试用的假值。因为 `force` 模式不污染 `capture_base`，对判定无影响；但这个值落进了永久存档
`spike_20260911_0243.png` 用的是 60 秒采样数据	分析文档 + CSV	v2.0 已改 120 秒、2026-10-12 改 300 秒。这张图已不能代表当前采样密度，未来复现同类事件时曲线会更稀疏

7.5 建议的后续顺序

立即：合并 1285843 到 main 并补 tag v2.1（消除 §6.4 的风险窗口）；
同步 config.example.json 与 collect.py 文档字符串的采集间隔；
清理 .gitignore 重复块；README 目录树补 measure_router_latency.py；
补发件地址的配置/代码一致性说明；
在爱快 UI 开启「终端记录」open_terminal_record（补上全时段覆盖）；
给 send_mail_direct 增加第二条独立告警通道，或让兜底队列由 RouterMonitor 自己的计划任务消费（解除对 WorkBuddy 定时任务的依赖）；
考虑把 check_peak 抽成独立模块 + 用历史 CSV 做可重复的判据回归测试。

八、协作方式复盘

本章只写能从提交记录、文档与运行数据中佐证的事实，不虚构对话内容。

8.1 哪些判断是人做的

判断	出处	性质
启动尖峰排障并追问「到底是谁」	`docs/2026-09-11-凌晨连接数尖峰分析.md` 全文	人的追问。工具只能给数字，「这不对劲，必须查清楚」是人的判断
判定排除 Windows Update（四条理由）	分析文档第三章	人的推理。结合了「本机无 WU 事件」「WU 默认 3 点」「升级必带带宽」「单机量级不够」四条领域知识
判定特征指纹（短命 + 零流量 = 端口扫描 / P2P tracker 风暴）	分析文档第三章	人的领域判断。这一步 AI 给不出「这是 P2P 典型指纹」这种经验性结论
决定新增触发式抓捕功能（而不是只加日志）	README 变更记录 + 分析文档第四章	人的产品判断。从「无法回溯」的遗憾直接推出「要在事发那一刻抓」
决定 `archive/` 从「归档」改为「全删」	`29d5a09` 提交正文「按用户决定」	明确的人工裁决。AI 在「先归档更稳妥」的惯性上停住了，人判断出归档无价值（git 历史已覆盖）
决定版本管理从目录快照改 git tag，归档仓冻结	`5fc42ac` + README 版本管理章节	人的流程决策
决定明文密码「接受历史残留」类问题不在本项目发生——`config.json` 从建仓起就 gitignore	`a3bd48b` 提交正文「安全：config.json 含真实凭据 → 移入 .gitignore」	人工的安全要求。对比 netServer 项目明文密码入库 9 天，这个项目在第一天就做了隔离
决定 `capture.auth` 用只读账号而非 admin	`config.example.json` + `spike_capture.py`	人的权限最小化意识
决定「不用远程时主动断开向日葵」作为运维约定	README「已知外部干扰源」	人的环境知识。工具只能测出「变慢了」，「怎么办」要人来定
提醒「命令行不要写内网 IP，会触发安全弹窗」	`tools/measure_router_latency.py` 文档字符串「★ 使用注意 (2026-10-12 刘提醒)」	人机协作层面的经验，已写入工具文档
决定把 10-12 的修复留在 dev 等通知	`1285843` 提交正文末「注: main 分支与 tag 未改动, 等通知后再发布」	人的发布节奏控制
决定接受 CSV 被 Excel 锁定的限制、不做特殊处理	`collect.py` 文档字符串 + README 故障排查表	人的工程取舍（承认限制并写清为什么不修）

8.2 哪些由 AI 推进

从改动规模与形态能明显看出 AI 深度参与的部分：

稳定性改造主体（1285843，6 文件 / +581 行）。六项改造一次性完成，含熔断状态机（ok/degraded/cooldown 三档）、延迟确认的候选替换与 rejected_peaks 防重复、双层 _post() 重试、测量工具（192 行）。每项都带完整的代码注释说明「为什么」（如「★ 关键约束: check_peak 实时运行时『后续数据尚未产生』」），且注释里保留了方案演进痕迹（「方案A, 修订版」）。
否决第一个方案的推理。提交正文写：「最初想用『与邻域最大值比率』，但实时运行时后续数据尚未产生无法判断，该方案不可行，故改为延迟确认机制」。这是典型的「先尝试 → 发现矛盾 → 换思路」过程被完整记录下来——AI 没有把走不通的路悄悄绕过去，而是把它写进了提交说明。
阈值标定的量化表达。「全历史 3.3 万样本统计, 真峰值 0.55~0.76, 脏数据 0.04~0.42, 阈值取 0.5」——把判据的可靠性建立在数据分布上，并明确指出两侧都有余量。
尖峰曲线图（docs/spike_20260911_0243.png）。由 tools/plot_spike.py（46 行）从 CSV 生成，图入 git（67,735 字节）。数据 + 图 + 结论三者作为一个完整证据包入库，这个组合本身就提升了文档的说服力。
整理与文档（a3bd48b 的 README 重写 +166 行、9a3c485 式的规范补全模式、41f3550 的分支模型章节）。结构化补全类工作。

8.3 哪种协作模式最有效

从 6 个提交的分布能看出一个很清晰的规律：

人提供「现场」和「判断」，AI 提供「取证」和「实现」。这个项目里最关键的一步——2:43 那 11,082 到底意味着什么——完全由人给出；但把这次判断转化成可执行的监测能力，是 AI 完成的。

三个证据支持的判断：

最有价值的一次协作是「事故 → 需求」的转化。人排查出「短命 + 零流量 = 端口扫描/P2P」，人意识到「无法回溯」很糟糕，于是决定「要在那一刻抓现场」。这个转化链条里，「现场」来自人的排查，「无法回溯」的痛点来自人的认知，「抓取 + 落盘 + 报警 + 邮件」的工程实现是 AI 做的。分工非常自然。
「承认解决不了」比「硬给答案」更有价值。分析文档第四章明确写「无法回溯」，没有编造一个可疑 IP。而同一份文档的第四章后半段立刻给出三个可执行的布防动作。AI 在这里的作用是「把你知道的东西变成能用的东西」，而不是「替你猜答案」。
人做决策的速度和 AI 做实现的深度形成了良好配合。§3.5 那个 archive/ 的例子特别典型：AI 的第一反应是「先归档更稳妥」（这也确实是常规最佳实践），人看了一眼说「不用留，git 历史里有」，95 秒后执行删除。这个场景里 AI 需要被人的常识纠正——而这恰好说明分工是成立的：AI 负责覆盖更多可能性，人负责判断哪些可能性值得保留。

一次值得记的协作失误：文档与代码的脱节。2026-10-12 改了 config.json 的采集间隔（300 秒）和代码里的常量，但 config.example.json（入库模板）、collect.py 模块文档字符串、README 目录树三处都没同步。AI 倾向于按任务范围更新「被要求更新的地方」，不会自发回头做全局一致性校对。这类问题需要人来指定检查范围。

另一个可观察的规律：.gitignore 在同一个项目里修了两次。1285843 修了 *.bak_*，9127312 又加了一个「备份文件」块（含 *.bak / *.bak_* / *.bak.* / *~ / *.old / *.orig）——说明同一笔改动被拆成了两次提交。加上 netServer 项目在同一天（相隔 71 秒）也踩了同样的坑，可以得出一个跨项目的判断：通用规则应该抽到全局 gitignore 或团队规范里，每个仓库各修一次既重复又容易重复添加。

一个正面的协作细节：tools/measure_router_latency.py 文档字符串里那段「★ 使用注意 (2026-10-12 刘提醒)」——人踩过的工具坑被写进了工具文档，供后来者（含 AI）阅读。这是很健康的知识沉淀方式，和 RouterMonitor 早期版本写在 README 里的故障排查表是同一个思路。

附录 A：完整提交清单

全部 6 个提交（git log --all），按时间正序：

日期	提交哈希	说明	变更量	分支/tag
2026-09-11 15:39:01	`a3bd48b`	`整理项目产物：目录归整 + 文档补齐 + 凭据隔离` — 目录归整（新增 `tools/`、`docs/`、`archive/`）；归档 daemon/watchdog 7 文件到 `archive/daemon/`；归档路由器前端 JS 与无关脚本；删除零价值文件；重写 README（+166）；新增尖峰分析报告与配图；`config.json` 移入 .gitignore + 新增 `config.example.json`	24 文件 / +2544	main
2026-09-11 15:40:50	`29d5a09`	`删除 archive/ 归档内容，同步更新 README` — 按用户决定：弃用的常驻进程/看门狗实现、路由器前端 JS 抓取产物、无关脚本全部删除，不再保留；README 移除 archive/ 相关结构与链接	13 文件 / −442	main
2026-09-11 16:11:34	`5fc42ac`	`README 补充版本管理章节：版本改用 git tag 标记，归档仓冻结`	1 文件 / +15	main，tag `v2.0`
2026-10-12 14:40:34	`1285843`	`2026-10-12 修复峰值告警静默丢失 + 脏数据污染 + 接口稳定性改造` — 六项：①邮件与抓捕解耦（`build_degraded_mail()`）②峰值延迟确认（`pending_peak` + 持续率 ≥ 0.5）③指数退避重试（`RETRY_DELAYS=(2,4,8)`，仅网络异常重试）④在线终端数节流熔断（300/5s/3 次/1800s）⑤采集间隔 2→5 分钟，`check_interval_min` 5→10，计划任务 PT2M→PT5M ⑥新增 `tools/measure_router_latency.py`；另 `.gitignore` 补 `.bak_`	6 文件 / +581 −47	dev ⏳
2026-10-12 14:41:42	`41f3550`	`README 补充分支模型与待发布记录(dev 已推 1285843, main/tag 待通知)` — 新增「分支模型」（dev/main + tag）与「待发布记录」两节，附发布命令	1 文件 / +20	dev ⏳
2026-10-12 14:45:40	`9127312`	`gitignore: 补齐备份文件忽略规则` — 追加 `.bak` / `.bak_` / `.bak.` / `~` / `.old` / `.orig`（注：与 `1285843` 中的规则部分重复）	1 文件 / +5	dev ⏳

建仓前的版本（仅存于本地冻结归档仓 D:\LJH\产物归档\project-artifacts_del\RouterMonitor\）：

归档目录	时间	内容
`2026-09-01-1.0`	2026-09-01 17:59	首版交付：路由器监控 + 峰值邮件告警。每分钟采集、每 5 分钟峰值检查、破纪录立即直发邮件。10 个文件（daemon 方案）
`2026-09-01-1.1`	2026-09-01 18:03	补充 .gitignore 排除运行数据。10 个文件
`2026-09-11-2.0`	2026-09-11 15:48	尖峰抓捕版（对应 tag `v2.0`）：120 秒采集 + 超阈值自动抓 TOP5 终端连接明细（JSON 落盘）+ 邮件告警，Windows 计划任务调度，凭据隔离

tag 清单（git ls-remote 核验）：

Tag	指向 commit	说明
`v2.0`	`5fc42ac`	RouterMonitor v2.0 尖峰抓捕版（对应归档 2026-09-11-2.0）

附录 B：文件与模块说明

git ls-files 共 11 个跟踪文件（本地工作目录另有约 10 个不入库的文件：config.json、agentmail_config.json、state.json、data/、logs/、5 个 .bak_2026* 备份、__pycache__/）。

B.1 核心脚本（入库）

路径	作用
`collect.py`	主入口。`--task` 计划任务模式 / `--verbose` 调试模式。流程：读配置 → 建日志 → `fetch_with_renew()` 取 sysstat → `_get_device_count_throttled()` 取在线终端数（节流熔断）→ 追加写当日 CSV（11 列）→ `spike_capture.check()` 触发判定 → `check_peak()` 峰值延迟确认。关键常量：`CONFIRM_DELAY_MIN=10`、`SUSTAIN_THRESHOLD=0.5`、`DEVICE_COUNT_INTERVAL_SEC=300`、`DEVICE_COUNT_TIMEOUT=5`、`DEVICE_COUNT_FAIL_THRESHOLD=3`、`DEVICE_COUNT_COOLDOWN_SEC=1800`
`spike_capture.py`	尖峰抓捕。`decide_trigger()` 触发判定（`min_connect`/`grow_ratio`/`abs_threshold` 三重条件 + 冷却）→ `_login()` + `fetch_terminal_rank()` 全终端排行 → TOP N 台 `fetch_terminal_conns()` 逐条明细（串行，间隔 0.4s）→ `save_capture()` 落盘 → `send_mail()` 直发（失败入队）。2026-10-12 新增 `build_degraded_mail()` 降级路径。关键常量：`DEFAULT_GROW_RATIO=1.5`、`DEFAULT_MIN_CONNECT=3000`、`DEFAULT_ABS_THRESHOLD=8000`、`DEFAULT_COOLDOWN=180`、`KEEP_TOP=15`、`DEFAULT_DETAIL_TOP=5`、`DEFAULT_DETAIL_MIN_CONN=5`、`RETRY_DELAYS=(2,4,8)`
`router_stat.py`	爱快接口封装（独立可执行）。`load_config` / `_post`（指数退避） / `is_auth_error`（`AUTH_ERROR_HINTS = no login/10014/not login/unauthorized/401`） / `login` / `renew_cookie` / `check_login` / `get_stat`（verinfo,cpu,memory,stream,cputemp） / `fmt_bytes` / `fmt_rate` / `print_stat` / `main`。不 import 任何业务模块
`send_mail_direct.py`	agent 邮箱直发。三级取 token（缓存 → 凭据 → OAuth 刷新）+ 自动续期 + `mcp_post`/`mcp_call` 调 `api.mail.qq.com` + `flush_pending()` 队列兜底 + `check_status()`/`get_quota()` 自查。硬编码 `SENDER="liujinhui@agent.qq.com"`、`DEFAULT_TO="117801633@qq.com"`
`smtp_sender.py`	SMTP 备用通道。`send_mail(mail_cfg, to, subject, body)`，70 行

B.2 工具脚本（入库，不参与自动运行）

路径	作用
`tools/plot_spike.py`	连接数曲线绘图（生成 `docs/spike_20260911_0243.png`），46 行
`tools/renew_token.py`	`sess_key` 续期工具。`--status` 检查有效性 / `--info` 查看当前 Cookie / 无参数按 config 凭据自动登录刷新
`tools/measure_router_latency.py`	响应时间基线采集器（2026-10-12 新增，192 行）。采集 ping / HTTP / 各接口耗时，用于验证「向日葵远程期间接口变慢」。`-n N` 控制轮数、`--json` 导出结果。只读；路由器地址与凭据从 `config.json` 读取不硬编码；文档字符串含「命令行不要写内网 IP」的使用注意

B.3 配置与状态（不入库）

路径	作用
`config.json`	全部配置（不入库）：`router`（url/cookie/timeout）、`auth`（登录凭据 + auto_renew）、`collect`（interval_sec=300 / scheduler=windows_task / task_name）、`capture`（enabled / trigger 三参数 / cooldown_sec=180 / detail_top=5 / detail_min_conn=5 / auth 只读账号）、`storage`（data_dir / state_file / log_dir / save_csv）、`peak`（check_interval_min=10 / send_first_baseline=false / send_mail=false）、`mail`（enabled / channel=smtp / sender / receiver / subject_prefix / pending_file / smtp_*）
`config.example.json`	脱敏模板（入库）。敏感字段用 `<尖括号占位符>`；`_说明` 字段解释各配置块。⚠️ `interval_sec` 仍为 120、`check_interval_min` 仍为 5，与实际配置不同步
`state.json`	运行状态（不入库）。顶层按日期分组（当日 `max_connect`/`peak_row`/`pending_peak`/`rejected_peaks`/`capture_base`/`last_peak_check_ts`/`last_device_num`）+ 跨日全局键（`spike_capture` 冷却与降级标记、`device_count` 熔断状态）
`agentmail_config.json`	agent 邮箱 OAuth 凭据（不入库），961 字节

B.4 文档（入库）

路径	作用
`README.md`	项目说明：目录结构、工作原理（5 节）、CSV 字段、常用命令、故障排查表、相关文档、版本管理（tag 对应表 + 分支模型 + 待发布记录）、变更记录（6 个节点）、在线终端数节流熔断专章（实测延迟表 + 参数表 + 已知干扰源）
`docs/2026-09-11-凌晨连接数尖峰分析.md`	真实排障记录。现象 / 数据定位（三行对比表）/ 结论（排除 WU 的四条理由 + 特征指纹判定）/ 局限与后续布防（含遗留项）/ 复现时的处理建议。55 行
`docs/spike_20260911_0243.png`	尖峰曲线图，由 `tools/plot_spike.py` 从 60 秒采样的 CSV 生成，67,735 字节

B.5 运行数据（不入库）

路径	作用
`data/router_YYYY-MM-DD.csv`	每日时序，11 列 UTF-8-SIG。现存 2026-09-01 至 2026-10-13 共 43 个文件（9-01 至 9-11 为 60 秒采样，约 1440 行/天；9-11 后改为 120 秒；10-12 后为 300 秒，当日 143 行）
`data/capture/<时间戳>/summary.json`	抓捕摘要：触发原因 + TOP 榜单 + 应用聚合 + 文件清单
`data/capture/<时间戳>/rank.json` / `rank.csv`	全终端连接排行（结构化 / Excel 友好）
`data/capture/<时间戳>/conns/<ip>.json`	单终端连接明细（apps 聚合 + 原始 conns），仅连接数 ≥ `detail_min_conn` 的终端
`data/capture/<时间戳>/conns/all.csv`	全部明细汇总
`data/capture/index.jsonl`	抓捕历史索引，一行一次，含时间/stamp/总连接数/在线终端数/触发前当日记录/TOP1 IP 与设备名/目录名。现存 31 条（20260911_151244 至 10 月）
`data/pending_email.json`	邮件兜底队列，直发失败时入队（当前内容为空数组）
`data/.mail_tokens.json`	agent 邮箱 access_token 本地缓存，自动刷新
`logs/collect.log`	运行日志
`logs/error.log`	错误日志（如「在线终端数探测失败」「待确认峰值判为脏数据并丢弃」「待确认峰值通过」「已发送降级简报邮件」「在线终端数已从熔断恢复」）

B.6 其他不入库文件

路径	说明
`__pycache__/`	Python 字节码缓存（已 gitignore）
`.workbuddy/memory/`	工具元数据目录（已 gitignore），2026-09-01 创建
`collect.py.bak_20261012_1335` / `.bak_20261012_1356` 等 5 个	手工备份文件，已由 `9127312` 补规则挡在 git 之外

本纪要基于 D:\LJH\项目\RouterMonitor 仓库（6 个提交，main=5fc42ac/tag v2.0，dev=9127312）的 README、docs/ 文档、data/ 运行数据（CSV 与抓捕快照）与 git 历史整理，未作推测性补充。涉及 2026-09-11 凌晨尖峰的数据已与 data/router_2026-09-11.csv、7966 脏数据已与 data/router_2026-10-12.csv 原始记录逐条核对。远端状态于撰写时经 git ls-remote 实测核验。