从 Charles 同步增量流量，并在时间线上创建一个新 checkpoint。

【fresh_start=False】（默认） 取上次 harvest 之后产生的新条目，写入 ARCHIVE，创建 checkpoint。 首次调用时加载 session 全部流量。

【fresh_start=True】 在时间线上插一个"重置点"，不加载任何条目。 之后的 harvest_data() 只返回此刻之后的新流量。 典型用法：切换分析目标前调用一次。

每次调用都会：

• 将新条目存入 ARCHIVE（可通过 load_checkpoint 随时回溯）

• 将 CACHE 切换到本次新增的条目

• 清空 Charles session 并重启录制（导出始终只含最新增量）

• 使所有关键词授权失效

列出所有 checkpoint，展示完整的收割时间线。

每条记录包含： id checkpoint 序号 read_at 收割时间（HH:MM:SS） count 本次新增条目数 start_time 本批流量的最早请求时间 end_time 本批流量的最晚请求时间 is_reset 是否为 fresh_start 重置点

当前正在查看的 checkpoint 由 current_checkpoint_id 标注。

将 CACHE 切换到指定 checkpoint 的数据，所有过滤工具随即在该时间窗口内工作。

这是只读回溯——ARCHIVE 和 CHECKPOINTS 不会被修改。 调用 harvest_data() 可随时切回最新增量。

checkpoint_id：来自 list_checkpoints 返回的 id 字段。

对当前 checkpoint 的流量做全局统计，帮助 agent 快速定向。

不拉取任何 body，只统计路由维度： top_hosts 流量最多的域名 top_paths 最活跃的路径前缀（取前两段） status_dist HTTP 状态码分布 method_dist HTTP 方法分布

【互锁-1】探测关键词在当前 checkpoint 的哪些条目中出现。

只返回 id + 命中位置的轻量索引，不返回 body 内容。 调用后 filter_by_keyword 对该关键词的批量限制解除（5 分钟内有效）。

【互锁-2】返回含关键词的条目精简视图（含 body 预览）。

匹配数 > 30 时须先调用 check_keyword_exists 解锁，防止上下文溢出。 limit 默认 10，上限 50，返回最近 N 条。

按 URL 路径关键词过滤，返回精简视图。

适合快速定位某个业务接口，例如 '/api/sign'、'/login'。 limit 默认 15，上限 50，返回最近 N 条。

按 host 字段过滤，返回精简视图。

只匹配 entry 顶层的 host 字段，不会误命中 body 或 headers 中出现的域名。 支持部分匹配，例如 'example.com' 可匹配所有子域名。 limit 默认 15，上限 50，返回最近 N 条。

按 HTTP 状态码过滤，返回精简视图。

适合排查异常请求，例如 403（鉴权失败）、500（服务错误）。 limit 默认 15，上限 50，返回最近 N 条。

按 HTTP 方法过滤（GET / POST / PUT / DELETE 等），返回精简视图。

大小写不敏感。limit 默认 15，上限 50，返回最近 N 条。

扫描当前 checkpoint 的所有条目，找出 body 疑似加密/压缩/编码的请求。

按 max(req_entropy, res_entropy) 降序排列。 threshold 默认 3.9：纯文本 JSON 通常 2.5~3.5，Base64 约 4.0~5.0，加密 > 5.0。 limit 默认 20，上限 100。

获取指定条目的完整原始数据（headers、body、timing 等全部字段）。

优先在当前 checkpoint 查找，找不到时从 ARCHIVE 全局搜索。 这样即使切换了 checkpoint，仍可用 entry_id 直接取历史数据。

切换网络带宽限制。

• preset 为预设名称 → 开启弱网；preset 为 null → 关闭弱网模拟。

• MCP 进程退出时自动关闭弱网，无需手动清理。

可用预设（直接填名称字符串）： 56 kbps Modem | 256 kbps ISDN/DSL | 512 kbps ISDN/DSL 2 Mbps ADSL | 8 Mbps ADSL2 | 16 Mbps ADSL2+ 32 Mbps VDSL | 32 Mbps Fibre | 100 Mbps Fibre 3G | 4G