## Why archer 面向的是长时间运行的大表归档/导出,但当前唯一的进度输出(`--progress N`)只在 chunk 完整处理完后按行数阈值打印一行,既没有速率、百分比和 ETA,也不显示当前处于扫描、写文件、写库还是等待副本延迟。路径 B 的单日长查询、fsync 与 `lag.Wait` 期间完全没有输出,操作者无法区分"正在慢"和"已经卡死";续跑后进度与 `state.json` 的行数还会从零重新起算。 这次改动把进度从"稀疏日志"变成"给人看的实时显示",同时修正续跑计数语义。 ## What Changes - 新增默认 `--progress auto`:stderr 是终端时输出单行实时刷新(`\r` 覆盖、空格补齐、不使用 ANSI 清行与颜色,兼容 Windows conhost);非终端时保持静默。 - `--progress on|off|auto|N`:`on` 强制开启(非终端时按间隔输出稳定的 key=value 行,便于 `tail` 日志),`N>0` 保留现有行阈值语义,`off`/`0` 关闭。新增 `--progress-interval`(默认 1s)。 - 进度行统一写 stderr;`--dry-run` 与 `--statistics` 仍在 stdout。 - 显示内容包含 rows、窗口速率、分片序号、已写字节、当前阶段及各阶段耗时、elapsed;在能廉价估算总量时额外显示带 `~` 的百分比与 ETA,并标注估算口径(`day|key`)。 - 新增阶段模型:`probe → resume → estimate → scan → file → db → checkpoint → finalize`,`lag-wait` 作为 scan 前的独立阶段;长阻塞期间持续刷新。 - 进度开启时,结束打印一行 `done` 汇总;中断时停止刷新、清除 live 行并打印最终快照后再执行现有的封片与 checkpoint。 - **BREAKING(行为)**:`state.json` 的 `rows_done` 改为累计值(含续跑前已处理行数)。旧 checkpoint 继续可读;语义变化会影响依赖该字段的校验脚本(修正 `scripts/export-all.ps1 -Verify` 的误报)。 - `--statistics` 分开展示"本次运行"与"累计(含续跑)"。 - 应用内所有面向人的警告与 lag 提示收口到进度 reporter,避免与 live 行交错。 非目标:JSONL/机器可读进度、彩色输出、多行 TUI、精确 `COUNT(*)`、后台异步计数、`export-all` 脚本自身的多表进度条(脚本可通过 `--progress on` 获得日志行)。 ## Capabilities ### New Capabilities - `progress-reporting`: 进度输出的模式与降级、显示指标与格式、廉价总量估算与回退、阶段模型、中断与完成时的最终快照、续跑基线语义。 ### Modified Capabilities - `cli-contract`: `--progress` 的取值与默认值、新增 `--progress-interval`、进度输出通道(stderr)及 TTY/非 TTY 行为。 - `archive-core`: 运行循环的阶段标记、lag 等待期间的进度、中断时的最终快照,以及 `state.json` 中 `rows_done` 的累计语义与 `--statistics` 口径。 ## Impact - 代码:新增 `internal/progress`;修改 `internal/app/app.go`(阶段标记、消息收口、续跑基线、done/中断快照)、`internal/app/probe.go` 或扫描器(暴露日期/键边界供估算)、`internal/cli/{parse,config,validate}.go`、`internal/checkpoint` 使用方、`internal/lag` 的等待回调。 - 输出契约:进度从 stdout 移到 stderr;集成测试中按 stdout 抓 `progress:` 的用例需要更新。 - 脚本:`scripts/export-all.ps1` 的 `-Verify` 恢复正确;可选加 `--progress on` 让日志可 `tail -f`。 - 依赖:不新增第三方库(TTY 判定使用标准库;不使用 ANSI 清行)。