报告、差异与投递

引擎有两个读取面。stats 是按提供商汇总的仪表盘快照；report weekly 组合摘要、保存快照并可投递。两者使用相同的时区窗口和相同的诚实性字段。

相关页面：数据源与配额、抓取与审计、自动化与投递、MCP 与智能体技能。

stats 与 report weekly

	stats	report weekly
用途	按提供商提供仪表盘指标	组合周度摘要
提供商	GSC、Yandex Webmaster、Metrika、Bing、CrUX、PSI，始终按此顺序	相同提供商，加上已保存的抓取问题
写入	不写入；不需要 SQLite	有存储时保存周度快照
投递	从不	仅在使用 --send 时
对比	每个提供商的当前与上一窗口	GSC 标题指标差值、分引擎流量、机会
输出	JSON 信封或简短文本表	JSON、HTML、email 或 Telegram 文本

lv24-seo stats --days 7 --lag-days 2 --json
lv24-seo report weekly --days 7 --lag-days 2 --out reports/
lv24-seo report weekly --days 7 --lag-days 2 --send --json

stats 的 status 为 ok、no_data、missing_token、not_configured 或 error，并隔离单个提供商故障：信封仍为 ok: true，同时 coverage.failed 增加。metrics 只包含实际报告的值，不用零填充，也不做跨引擎合计。previous 仅对可比较的 GSC、Yandex Webmaster 和 Metrika 窗口存在；Bing、CrUX 和 PSI 返回 null。

只有当每个已配置服务都是 ok、有行、未被截断，且没有缺失或失败时，coverage.complete 才为 true。未配置任何提供商时为 false。

窗口与限制

• --days 是当前窗口长度，范围为 1 到 3660。更大的值会以 INVALID_INPUT 和退出码 2 失败，而不是构建无界窗口。
• --lag-days 将两个窗口一起向后移动，接受 0 或更大值。上一窗口是紧邻当前窗口之前、长度相同的窗口。
• GSC 数据有 2–3 天延迟，因此周一早上的报告更稳定。默认是 7 天窗口和 2 天延迟。
• 窗口使用 report.timezone。提供商日期不做转换。
• MCP seo_weekly_report 会把 days 上限设为 90、lag_days 上限设为 14，并给出警告；低于最小值的值会被拒绝。CLI 接受完整的 1–3660 范围。需要更长回看时请使用 CLI。

周报包含什么

标题指标比较两个相同窗口内的 GSC 点击、展示、CTR 和平均排名。CTR 变化以百分点（pp）表示。没有可比较的 GSC 窗口时，报告保留真实的当前值并令 previous: null，同时说明差值不可用；它不会编造基线，也不会把多个引擎合并成跨引擎总计。

分引擎数字保持独立：

• Yandex Webmaster：当前热门查询窗口，在周报中最多 500 行。
• Yandex Metrika：会话，不是点击。
• Bing、CrUX 和 PSI：配置后作为额外引擎行。CrUX 是字段数据，PSI 是实验室数据，两者从不合并。

报告还包含排序后的机会（接近排名区间、CTR 差距、衰退页面）、按严重程度分组的最近抓取问题、来源部分、数据说明和限制。每个机会都带有真实证据和预期点击；预期点击是优先级估计，不是流量承诺。

JSON 信封还包含 meta.complete、meta.sources、meta.sources_failed、meta.sources_missing、meta.sources_incomplete、meta.data_age_days、meta.truncated、meta.limitations、meta.locale 和 meta.snapshot_hash。

输出与已保存快照

lv24-seo report weekly --out reports/

--out DIR 写入两个文件：

• report.json — 规范英语，足够稳定，可在多次运行之间做差异比较。
• report.html — 按 report.locale 渲染。

数据目录存在时，周度运行还会把快照保存到 data/seo.sqlite3。lv24-seo init 创建 <config dir>/data；相对 [storage] data_dir 锚定到配置文件，而 LV24_SEO_DATA_DIR 仍是进程作用域覆盖。没有存储时命令会警告快照未保存。

快照按类型、属性和周期作为键。它们供 report diff 使用；发送账本位于同一个 SQLite 文件中。MCP 在内存中保留最新报告供 seo://report/latest 使用。即使显示语言是俄语或中文，report.json、--json 信封和 report diff --markdown 仍保持规范英语；机器码从不翻译。

读取 truncated 与 limitations

下结论前按以下顺序检查信封：

1. ok 和 meta.complete — 每个已配置来源是否返回了可用行？
2. meta.truncated — 提供商是否截断了数据？
3. meta.data_age_days — 窗口相对抓取时间有多旧？
4. meta.limitations[] 和 warnings[] — 哪些是未知或近似的？

只出现在一个窗口中的指标是未知，不是零。被截断的响应不完整。恰好填满 50,000 行上限的 GSC 最后一页会报告为截断，而不是完整：完整一页不能证明不存在下一行。单个提供商失败不会让报告失败：email 会指出缺失来源，信封设置 complete: false，其余引擎仍返回数据。

本地化

report.locale 接受 ru、en 和 zh，默认 ru。它控制周报邮件主题、HTML 和纯文本、CLI 人类可读摘要、--out 写出的 HTML，以及 Telegram 消息，包括数字、百分比、排名、日期和复数格式。

本地化只影响呈现。JSON 信封、MCP payload、已保存快照和 report diff 保持规范英语。不支持的语言会在配置校验时以 CONFIG_INVALID 失败，而不是静默回退。

Email 与 Telegram

Email 使用 587 端口的 SMTP、STARTTLS 和会验证证书的 TLS 上下文。只有 TLS 成功后才登录。消息为 multipart/alternative：产品 HTML 模板加上相同内容的 78 列纯文本，主题为单行本地化文本，最多 78 个字符。

模板是 600px 卡片，仅使用内联 CSS，带深色页眉和文字标识。没有外部图片、样式表、脚本、跟踪像素或远程字体。未知 KPI 显示为本地化的“无数据”，而不是 0 或长破折号。Metrika 显示为会话，不是点击。问题部分为空时会说明未提供问题数据，而不是声称站点干净。限制和警告会保留并去重；提供商原文保持原语言，并在报告本地化时标注为原文。页脚包含准确的属性 id、UTC 生成时间和“generated by lv24-seo”。

Telegram 通过 Bot API sendMessage 发送相同的 78 列本地化文本。HTTP 4xx/5xx、传输超时和格式错误的 Bot API 响应都会标记为 failed，绝不记录为已发送。

只有 email 和 Telegram 两个渠道。没有 Resend 或 Brevo 适配器，也没有 --channel github；提供商侧 GitHub issue 投递未实现。

幂等性与投递保证

sends 账本在 (kind, property, period, channel, content_hash) 上唯一。哈希覆盖标题和各个部分，以及规范化后的渲染语言；generated_at 和诊断信息不参与。英语不在哈希中包含语言，因此升级不会重发已经投递的英语周期。

only_on_change 在内容哈希已投递时跳过发送（already_sent）。当没有任何变化达到 report.thresholds 时，实质性门槛会跳过发送（no_material_change）。门槛先于语言哈希运行，因此当周期没有实质性变化时，单纯切换语言仍可能被抑制；一旦门槛通过或被禁用，就会投递。

投递是每渠道 at-least-once。传输结果不明确时会标记 failed 且不记录，因此下一次运行可能重复投递。并发运行通过 SQLite 在检查、发送和记账周围的事务去重；进程崩溃后 SMTP 和 Bot API 都不提供 exactly-once。每个周期只保留一个计划任务。

比较已保存快照

lv24-seo report diff --json
lv24-seo report diff --base 2026-11-02..2026-11-08 --head 2026-11-09..2026-11-15 --markdown

report diff 比较两个已保存的周度快照，不调用任何提供商。默认使用两个最新周期。它报告标题指标变化、按严重程度的问题数量、新增、已解决和未变的机会，以及新增和解除的限制。

只出现在一个快照中的指标会列入 unknown_metrics，绝不当成零。任一快照没有标题对比或周期长度不同时，comparable 和 meta.complete 为 false。--markdown 只输出 GitHub-flavoured Markdown，警告写入 stderr，因此 stdout 仍是可用于 PR 评论或 CI 摘要的合法 Markdown。Markdown 差异每组最多列出 20 个机会，并说明还有多少。

该命令需要 lv24-seo init 和两次针对不同周期的 report weekly 运行。没有存储时以 CONFIG_INVALID 失败；少于两个快照时以 INVALID_INPUT 失败。两者都带有 next_action。

Source: _source/engine-cli.md, _source/engine-scheduling.md, _source/engine-releases-0.5.2.md.