AI Weekly Optimization Plan

AI 周报项目 · 优化方案

北极星（North Star）：为 AI 从业者提供高质量的 AI 行业情报，并定时、稳定地推送到他们已经在用的办公协作软件（飞书 / 钉钉），让情报在"工作者待着的地方"被消费；同时让情报引擎具备全 Agent 通用能力，不被单一框架绑定，扩大触达面与长期生命力。

---

一、北极星指标（怎么算"做到了"）

层级	指标	说明
北极星	周活跃接收情报的 AI 从业者数	触达且打开/点击的人数（去重）
过程	推送准时率	是否在约定时间（如周一 09:00）前送达
过程	内容打开率 / 点击率	卡片打开、点「查看完整周报」的比例
过程	转发率	从业者主动把情报转给同事
过程	跨框架可复用度	非 WorkBuddy 框架（OpenClaw / LangGraph / Dify 等）能否无改动复用核心引擎
健康	连续留存（≥4 周打开）	衡量情报是否真有用
反向	退订 / 免打扰率	内容噪声过大时的警报

关键判断：北极星不是"生成了多少报告"，而是"有多少从业者稳定地读到了情报"。推送环节缺失时，北极星永远是 0。

生态维度（2026-08-10 新增）：情报价值不应被单一宿主锁定。天禧AI / 天翼等办公软件已采用 OpenClaw 格式技能（已查证 ClawHub / 天禧Claw / gpushop 文档），验证了"更多办公软件将采用此类格式"的趋势。一旦 ai-weekly 核心引擎通过 OpenClaw 包装被这类宿主加载，同一份引擎可服务更多 AI 从业者，且不增加内容/分发管线的开发成本——北极星因此被"多宿主触达"放大。第十三章的跨 Agent 兼容（X 系列）即为此维度的落地。

---

二、现状 vs 北极星（差距分析）

已具备（as-is 强项）

• ai-weekly skill：14 源 RSS（国内 7 + 国外 7）、单文件 HTML 周报（榜单 / 市场 / 看点 / 关键词 / 受众分述）。
• region-aware 排行榜兜底、国内 + 国外双源市场数据、服务端静态预渲染（看点/关键词标签必现，不依赖 JS）。
• 已有受众分角色视角：开发者 / PM / 自媒体（audience_summary）。
• 国内网络可用：RSS 国内源 10/14 健康、市场数据静态注入无外网依赖。

缺失（vs 北极星）

1. 没有"推送"环节 —— 产物是 HTML 文件，要人手动打开，北极星 = 0。
2. 未接入飞书 / 钉钉机器人，没有任何 IM 出口。
3. 没有定时调度 —— 依赖人工或临时 automation。
4. 内容形态是网页，不适配 IM —— IM 要的是消息卡 / 富文本，不是一整页 HTML。
5. 没有受众订阅 / 分群 —— 所有读者收到同一份，浪费已有的角色视角。
6. 没有度量 —— 推没推到、打没打开，全不知道。

---

三、目标架构（to-be）

┌────────────┐   ┌──────────────┐   ┌────────────────┐   ┌──────────────┐
│ 抓取层      │→  │ 生成层        │→  │ 分发层(delivery)│→  │ 飞书 / 钉钉   │
│ 14 RSS +    │   │ generate_site│   │ feishu_bot /   │   │ 群机器人/应用 │
│ 排行榜兜底  │   │ + 结构化JSON │   │ dingtalk_bot   │   │ (消息卡片)   │
└────────────┘   └──────────────┘   └────────────────┘   └──────────────┘
                          │                                            │
                          ▼                                            ▼
                   HTML 深度落地页 ←────────── 卡片「查看完整周报」←── 打开率/UTM 度量
                          │
                  automation：每周一 09:00 触发全链路

---

四、四大优化模块

模块 1 · 内容层：从"网页"到"可分发情报"

• 结构化输出作为推送源：在现有 HTML 之外，额外产出 report.json（头条速览 / 看点 / 关键词 / 受众摘要），IM 卡片直接消费它；HTML 退为"深度阅读落地页"。
• 分层内容：
  • 头条速览（3–5 条，IM 卡片直接可读）
  • 本周看点（开发者 / PM / 自媒体三视角，已具备 → 直接对应分群推送）
  • 深度链接：卡片「查看完整周报」跳转到 HTML / 云端托管页
• 保持"去 AI 味、编辑视角"的既有调性。

模块 2 · 分发层：飞书 + 钉钉接入

• 飞书（MVP 推荐）：群机器人 Webhook（incoming webhook）→ POST 消息卡片（card）。无需应用审核，最快落地。
• 钉钉（MVP 推荐）：自定义机器人 Webhook + 加签 secret → POST markdown / actionCard。
• 卡片承载：头条速览 + 三视角看点摘要 + 「查看完整周报」按钮。
• 后续可升级为飞书/钉钉自建应用 + 消息 API，支持私信推送到个人、交互按钮。

模块 3 · 调度层：定时 + 可靠

• 用 automation（recurring）每周一 09:00 触发：抓取 → 生成 → 推送 全链路。
• 失败重试 + 告警：推送失败发告警到你的邮箱 / 备用群，不直接丢失。
• 可选双节奏：每日速览（轻量） + 每周深度（重）。

模块 4 · 受众与度量（北极星闭环）

• 复用 audience_summary 做分群：开发者群 / PM 群 / 自媒体群收到对应视角，不浪费已有能力。
• 订阅管理：飞书/钉钉群即"订阅单元"；后续加"订阅关键词"做个性化过滤。
• 度量埋点：卡片「查看完整周报」链接带 utm/uuid，统计打开；仪表盘跟踪周触达、打开率、留存，反哺内容优化。

---

五、可靠工程（守住国内网络）

• RSS 国内源已加固（10/14 健康）；排行榜 --region cn 兜底；市场数据静态注入无外网依赖 → 推送管线在国内网络可独立跑。
• 加 --proxy 开关拿国外源（LMArena / Hugging Face）。
• 排行榜快照机制避免单点失效。

---

六、分阶段路线图

阶段	周期	范围	北极星收益
P0 MVP	1 周	飞书群机器人 Webhook 推送周报头条卡片；周一键触发	北极星从 0 → 有稳定触达
P1	2–3 周	钉钉接入 + 三视角分群推送（开发者/PM/自媒体三群）+ 推送失败告警	覆盖双平台 + 角色化
P2	1 个月	每日速览 + 订阅关键词过滤 + 打开率度量	留存与个性化
P3	后续	自建应用（私信到个人）、内容个性化、多语言	规模化与增长

---

七、建议落地清单（下一步可执行的改造）

1. 新增 delivery/feishu_bot.py、delivery/dingtalk_bot.py：POST webhook、钉钉加签、构造卡片。
2. 新增 publish.py：读 report.json + 调 delivery 推送；支持 --platform feishu|dingtalk、--webhook、--secret。
3. 生成层补一个 report.json 结构化产物（头条 / 看点 / 受众摘要）。
4. skill 内加 automation 模板（每周一 09:00），CLI 串起 抓取→生成→推送。
5. 卡片「查看完整周报」链接带 ?src=feishu&uid=... 做度量。
6. 合规：沿用 skill 原则——不引入第三方商业 API，飞书/钉钉官方机器人即可。

一句话：报告生成已经成熟，瓶颈在"最后一公里"——把网页变成飞书/钉钉里那条被打开的消息。P0 只需一个 Webhook 机器人 + 一个 publish 脚本，就能让北极星第一次大于 0。

---

八、内容质量优化（编辑视角，独立于分发管线）

分发管线解决"送到"，但内容本身决定读者打开后值不值得读、下周还回不回来。当前报告在"结构完整度"上已成熟（榜单 / 市场 / 看点 / 关键词 / 受众分述），但编辑实质（摘要、排序、主线、信源）仍停留在 RSS 原始搬运水平。本节能直接抬升北极星的"留存 / 打开率"。

8.1 现状内容体检（基于 AI_News_2026-08-08.html 实测）

维度	实测数据	问题
新闻量	100 条，日期 08-01→08-07	覆盖 OK ✅
摘要质量	61/100 条 summary >200 字（最长 300），平均 205 字	实为文章正文整段搬运，非编辑摘要 ❌
重要度	100 条 score 全为 0	无排序、无"必读"概念，纯 RSS 原始顺序 ❌
信源名称	"InfoQ - 促进软件开发领域知识与创新的传播"、"AI News & Artificial Intelligence	TechCrunch"
榜单时效	LEADERBOARD snapshot = 2026-07-30，报告日 08-08	差 9 天却未显著提示"非本周更新" ⚠️
关键词	6 个关键词 3 个标"模型"	taxonomy 偏斜；note 偏通用知识 ⚠️
本周看点	5 条，含 1 条"8点1氪"每日导览（日报注水）；每条仅 1 个 related	自动派生质量不稳 ⚠️
分类	"技巧" 0 条命中、"论文"仅 3 条	死 tab + 内容缺口 ⚠️
重复	URL / 标题重复 0	无重复 ✅

8.2 优先级优化举措

C0（直接抬留存，1 周内可落地，纯生成脚本可改、不依赖外部 API）

1. 摘要归一化（影响最大）：抓后接 _normalize_summary()，把 >120 字的正文搬运压成 ≤2 句 / ≤80 字事实摘要（核心事实 + 影响）。成本敏感场景用本地 Ollama 轻量摘要，或用"首段关键句抽取 + 规则截断"。validate_report.py 增"summary>120 字占比 <20%"断言。
2. 重要度评分 + 🔥必读：新增 _score_news() = 来源权威度(S/A/B) × 时效(近 24h 加权) × 类别权重(模型/融资 > 行业八卦)。Top 5–8 标"必读"徽章，仅用于排序、不篡改事实。忙碌读者 10 秒抓住重点。
3. 信源名称归一化：建 SOURCE_ALIASES 映射表，展示短名（InfoQ / TechCrunch / 量子位），原 feed 全名仅作链接 title。

✅ 已落地（2026-08-09）：C0 三件事全部落地——

• 摘要归一：generate_site.py _normalize_summary() 接入 format_news_items()，>120 字压成 ≤80 字事实摘要；超长按句号截断保留事实链。
• 重要度评分 + 🔥必读：_score_news() 用「来源权威度(S/A/B)×时效×类别权重」打分，Top 8 标 mustRead=True，新闻卡渲染「🔥 必读」徽章并参与「必读」tab 计数。
• 信源短名：_normalize_source() + SOURCE_ALIASES 映射（InfoQ / TechCrunch / 量子位 / 36氪 / 机器之心 等），原 feed 全名降级为链接 title。
• 校验：check_editorial（断言摘要>120 字占比 <20%、🔥必读 5–12 条、信源 RSS 分隔符=0）。
• 实测 W32 报告：摘要>120字 0/100、必读 8 条、信源短名 100%，校验从 7/7 → 8/8 全绿。

C1（编辑纵深，2–3 周）

4. 统一编辑导语（本周主线）：_auto_lead() 生成 1 段 ≤3 句叙事主线，置于头条区顶部统领全报（现有 audience_summary 是分角色，缺总纲）。

5. 榜单时效标注：榜单卡显示"快照 07-30 · 非本周抓取"；snapshot 距报告日 >3 天生成即告警；长期接用户周更或 --proxy 自动刷新。

6. 看点去注水 + 扩链：_auto_insights() 排除纯日报聚合类（如"8点1氪"）；每条看点挂 2–3 个 related（同源深挖 + 异源佐证）；insight 字段强制"对读者意味着什么"。

✅ 已落地（2026-08-09~10）：C1 三件事全部落地——

• 本周主线导语（_auto_lead）：从全量新闻聚合主题（每条按 score + 命中主题词加权），取 Top3 主题配「最贴主题」的真实新闻标题作锚点，合成 2~3 句电梯演讲。注入 [LEAD] 占位，模板 insightsLead 区块服务端预渲染（禁 JS 也可见）。SKILL.md 把它从「必做」升级为「推荐强做」；curated insights.json（含 lead 字段）优先覆盖。
• 榜单时效标注（C1#5）：generate_site.py 新增 _leaderboard_freshness() 算每个子榜的 snapshot 距今天数；模板 lbStaleWarn banner + lbSnapshot 文案 >3 天源显式标「非本周抓取」（如「LMArena（9天前）」）；validate_report.py check_editorial_c1 断言快照标注就位。
• 看点去注水（C1#6）：_auto_insights() 按 INSIGHTS_BLOCKLIST（含"8点1氪"等纯日报聚合关键词）剔除；每条看点保留 2–3 个 related（同源深挖 + 异源佐证）；check_editorial_c1 断言「日报聚合类 ≤ 0 条」与 lead 文本非空。
• 实测 W32：lead 文本已渲染、榜单快照 9 天告警已亮、看板日报聚合=0，校验 9/9 → 10/10 全绿。

C2（智能化，1 个月）

7. 关键词自动聚类：从本周新闻标题 / 摘要做轻量 TF 聚类，自动产出 5–8 高频主题词 + 标签，替代现有人工偏斜；note 写"为什么本周重要"而非通用知识。

8. "本周数字"看板：聚合模型发布数 / 融资披露额 / 国内外比 / 必读 Top3，给 5 秒速览快照。

9. 死分类动态隐藏 + 补缺：空 tab（技巧）动态不渲染；定向补 arXiv / 实操源抬升 paper / tip 厚度。

✅ 已落地（2026-08-10）：C2 三件事全部落地（17/17 → 19/19 校验全绿）——

• 关键词 TF 自动聚类（C2#7）：generate_site.py 新增 _KW_STOP（70+ 中英文停用词）+ _tokenize()（英文词元 + 中文 2/3/4 字 n-gram），_auto_keywords() 改写为「白名单高精保留 + TF n-gram 发现补充」混合算法——白名单优先、词频次之，取 top_n=8。note 模板从通用套话改为「本周被 N 条新闻提及（如《真实标题…》等）」——是周相关而非通用知识。_TAG_COLORS/tagColors/getTagLabel 同步加「话题」兜底标签。
• 本周数字看板（C2#8）：新增 _compute_weekly_stats() 聚合 总量 / 国内外比(中文 61 vs 英文 41) / 模型相关 35 + 新发布 7（兼容 ai-models/model 两种历史 category）/ 资本&发布事件 5 / 在榜 26 / 必读 Top3；generate() 注入 [WEEKLY_STATS_PLACEHOLDER]，模板新增 .dashboard-section + CSS + renderDashboard() 在 stats-bar 之后渲染；空数据自动隐藏。踩坑修复：初版硬编码 category=="model"（实际为 ai-models）致 model_news=0，已改 _MODEL_CATS={"ai-models","model"} 兼容。
• 死分类动态隐藏（C2#9）：renderTabs() JS 加 if (count < 1 && cat.key !== 'all') return ''——只渲染有内容的 tab，「全部」永远保留。W32 实测：只有 tip（技巧）被隐藏；其余分类有内容正常保留——确认是「只隐藏真的空的」，无误伤。
• 校验守护：新增 check_keyword_clustering（关键词 ≥5 且 ≥60% note 含「本周」）+ check_empty_category_tabs（hide 逻辑就位 + 列出空分类）+ check_keyword_filter（toggleKeywordFilter/activeKeyword/data-term 接线）。
• 实测 W32：8 关键词全部 TF 命中（Agent 17 / GPT 8 / DeepSeek 5 / 应用 5 / 安全 4 / Claude 3 / 千问 3 / 融资 2），note 周相关率 100%；数字看板 102 条 / 模型相关 35 / 资本&发布 5 起；空分类 1 个被隐藏。

8.3 内容质量校验（并入 validate_report.py）

校验项	阈值	现状（2026-08-10）
摘要 >120 字占比	<20%	0/100（0%）✅
必读标记覆盖	Top5–8 有徽章	8 条 ✅
信源短名率	100%	RSS 分隔符=0 ✅
榜单 snapshot 距报告日	≤3 天 或 显式标注	9 天（已显式告警）✅
看点含日报聚合类	0 条	0 条 ✅
空分类 tab	0 个	0 个（tip 已隐藏）✅
关键词 ≥5 且 note 周相关	≥60% 含「本周」	8/8（100%）✅
关键词可点击筛选	toggleKeywordFilter 接线	已接线 ✅
本周数字看板字段完整	WEEKLY_STATS 6 字段	齐全（102/61/41/35/7/5/26）✅

8.4 内容优化路线图（叠加于第六章）

阶段	周期	内容收益
C0	1 周	摘要归一 + 必读评分 + 信源短名 → 报告从"搬运"变"编辑"
C1	2–3 周	本周主线导语 + 榜单时效标注 + 看点去注水
C2	1 月	关键词聚类 + 本周数字 + 死分类治理

一句话：分发解决"送到"，内容解决"读完且下周还回来"。C0 三件事不依赖任何外部商业 API、纯前端 / 生成脚本可改，是性价比最高的第一刀；与第三章节的分发管线 P0 可并行推进，互不阻塞。

---

九、市场数据分析优化（数据可信度 + 本周联动 + 结构可视化）

分发管线解决"送到"、内容优化解决"读完"，市场板块要解决"可信且关于本周"。当前市场板块的 2×2 图表数据扎实（全球 9 点 / 全球融资 14 季度点 / 中国 3 点），"趋势洞察"四卡也按受众拆分到位；但存在三类硬伤：①自我否定式免责（每图都写"示例/估算，建议补充真实来源"，而数据其实已核实，等于劝读者别信）；②与本周新闻零联动（100 条新闻里的 Firmus $2B、DeepSeek 重启融资等市场事件，市场板块完全没接住）；③结构数据只躺在散文里（中国 2026H1 融资 3076 亿、细分赛道占比、头部集中度，只出现在洞察卡 prose，未可视化）。本节能直接抬升北极星的"打开后信不信、下周还回不回来"。

9.1 市场板块体检（基于 AI_News_2026-08-08.html 实测）

维度	实测	问题
数据真实性	市场规模/融资来自 Grand View / Crunchbase / 信通院 / IT桔子（已核实）	✅ 数据真，但被"示例/估算"免责自我抹黑 ❌
免责一致性	图表注释写"示例/估算，建议补充真实来源"；页脚却列 LMMarketCap/Gartner/IDC/Statista/Crunchbase/Stanford HAI	既引真源又自称示例，自相矛盾 ❌
本周联动	市场板块无任何本周新闻引用；Firmus $2B、DeepSeek 重启融资未出现	板块是"静态宏观 essay"，与本周 0 关联 ❌
中国融资图	仅 2 点（2024 391.51 / 2025 656.04）；takeaway 却说 2026H1 3076 亿	最关键当期点缺失，图与文案脱节 ⚠️
结构可视化	2026H1 细分（大模型1598/具身906/AIGC596/基础层725）、TOP3 930亿(30%)、TOP30 过半	富结构数据只在散文，未成图 ⚠️
预测诚实度	全球市场 2027F/2028F 以实线画出（CAGR 外推）	预测区未做虚线/阴影区分 ⚠️
中国增速标注	9188→12000→17000 隐含 +30.5%/+41.7%	未标 YoY，读者得自己算 ⚠️
资本↔能力联动	DeepSeek/阶跃/Kimi 拿走 930 亿，但排行榜未对照	两板块割裂 ⚠️
校验	validate_report.py 无市场专项断言	数据缺失/口径漂移无守护 ❌

9.2 优先级优化举措

M0（可信度与一致性，1 周内，纯文案/模板可改，不依赖外部 API）

1. 撤掉自损式免责：保留"数据快照 YYYY-MM-DD（非实时）"的诚实声明，但删除每图"示例/估算数据，建议补充真实来源"——数据已核实，不该自我否定。
2. 统一免责与来源：页脚"市场数据为示例/估算值"改为"市场数据来源（国内+国外）：…"，与已列真源一致；图表注释改为具体署名（如"来源：Grand View Research 2026 · 快照 2026-08-08"）。
3. 每图来源署名：4 张图各带真实来源行（全局/中国 × 规模/融资），替代统一的"示例/估算"占位。

✅ 已落地（2026-08-09）：generate_site.py 新增 DEFAULT_MARKET_SOURCE / DEFAULT_FUNDING_SOURCE / DEFAULT_CN_MARKET_SOURCE / DEFAULT_CN_FUNDING_SOURCE 四个真实默认来源——国内源优先（中国分轨：信通院 · 中商产业研究院 / 新浪创投Plus + IT桔子），全球源标注「海外机构，静态快照引用」（Grand View Research / Crunchbase）；generate() 在未传 --*-source 时回退到真实来源而非 ESTIMATE_NOTE；ESTIMATE_NOTE 改为中性「数据快照（静态，非实时）」；validate_report.py 新增 check_market_disclaimer 守护（断言无「示例/估算」且四图来源署名齐全）。重生成 AI_News_2026-08-08.html 验证：「示例/估算」计数 0，四图署名均为真实来源，校验 9/9 通过。

M1（本周联动，核心分析缺口，2–3 周）

4. 新增"本周市场信号"区块：从 NEWS_DATA 抽取本周融资/并购/大额融资轮/模型发布（按金额/信号词打分），Top 3–5 条作为"新闻 ↔ 宏观图"的桥接卡；让市场板块真正"关于本周"。

5. 融资图动态上下文：把本周头条融资事件（Firmus $2B、DeepSeek 重启）挂到融资图 takeaway 或信号卡，宏观图不再孤立。

6. 资本↔能力联动小卡：把获融资方（DeepSeek/阶跃/Kimi 合计 930 亿）与其排行榜位置对照，做"资本冠军是否等于能力冠军"的对照条。

✅ 已落地（2026-08-09）：generate_site.py 新增 _extract_market_signals()（按 SIGNAL_WEIGHTS 信号词 + 金额正则 + 中国/全球/能力榜桥接规则打分取 Top5）、_lb_name_map()（模型/机构名→名次映射）、_render_market_signals_html()（服务端预渲染 5 张桥接卡，含「资本↔能力」联动标注）；generate() 在市板块前注入 [MARKET_SIGNALS] 占位；模板 news_site_template.html 加 .market-signals 区块与 CSS；validate_report.py 新增 check_market_signals（断言区块存在且 ≥1 张卡）。三份周报（07-30/08-02/08-08）重生成：校验 10/10 全绿，M1 信号卡均注入。逐周核对：2026-08-08（W32）信号为真实本周事件（DeepSeek 重启融资→能力榜 #2(lmarena)、Whatnot $545M、Acrab $130M 等），桥接正确；⚠️ 但 2026-07-30 与 2026-08-02 两份历史报告内嵌的 NEWS_DATA 逐字相同（同 62 条），故这两周 M1 卡必然一致——属历史数据源重合，非 M1 bug（M1 逻辑本身已被 W32 验证正确）。若需 30/31 周各自独立，需各自独立的当周新闻源。

✅ 已落地（2026-08-10，Fix2）：generate_site.py _extract_market_signals() 透传 lang/cn_summary；_render_market_signals_html_with_theme() 对英文信号卡在标题下插入绿色左边框中文注解 .ms-cn（如 Moment / Omilia / OpenAI 收购 NextSlide 等英文报道都能给中文用户一眼看懂）；_kw_tag_html/标题做 html.escape 防注入。validate_report.py 新增 check_market_signals_cn（断言英文信号卡 100% 带中文注解）。W32 实测：3 张英文信号卡全部带中文注解，校验 15/15 → 17/17。

M2（结构可视化，2–3 周）

7. 中国 2026H1 融资结构图：把散文里的细分（大模型 1598 / 具身智能 906 / AIGC 596 / 基础层 725 亿）做成堆叠/分段条形图，替代纯文本。

8. 补中国融资当期点：中国融资图从 2 点补到含 2026H1（391.51 / 656.04 / 3076.82），或显式改为"年度 + 半年"混合标度，消除"图说 3076 亿但图里没有"的脱节。

9. 头部集中度可视化：TOP3 930 亿（30%）/ TOP30 过半 → 集中度条或饼图，量化"钱有多集中"。

✅ 已落地（2026-08-10）：generate_site.py 常量新增 DEFAULT_CN_FUNDING_LABELS/DATA（补 2026H1 当期点 3076.82，消除"图说 3076 亿图里没有"）、DEFAULT_CN_STRUCTURE_*（大模型1598/具身906/AIGC596/基础层725）、DEFAULT_CN_CONCENTRATION_*（TOP3 930/TOP4-30 770/其他 1376）；build_charts() 新增 cnStructureChart/cnConcentrationChart 两张横向条形图（共 6 图）；模板 charts-grid 加两张 canvas 卡片 + 图表变量声明/重置列表补全。validate_report.py 新增 check_market_structure（断言 6 图齐全 + 结构标签 + [TREND_INSIGHTS] 已替换）。重生成 AI_News_2026-08-08.html（W32，102 条真实新闻）验证：6 图齐全、校验 12/12。

M2+ 「AI 行业趋势洞察」×「关于本周」合作（用户议题，2026-08-10 落地）

• 问题：原「趋势洞察」面板是模板写死的宏观百科（4 条静态洞察），与「关于本周」零联动；M1「本周市场信号」也是孤立板块。
• 设计：让宏观趋势成为「透镜」、本周事件成为「证据」——双向桥接：
  1. 趋势面板挂「本周印证」：TREND_INSIGHTS（4 条宏观趋势，含 keys 匹配词）上提到 Python；_match_insight_evidence() 从 M1 信号 + 本周新闻按 keys 重合度抽 Top2，预渲染成 📌 本周印证：<本周真实事件> 行注入每条洞察（服务端预渲染，禁 JS 可见）。
  2. M1 信号卡加「印证趋势」标签：_signal_theme() 把每条信号卡标注它印证哪条宏观趋势（标题关键词 + 信号类型兜底），形成「信号卡 → 趋势面板」反向桥。
• 效果（W32 实测）：3 条趋势挂上本周印证（DeepSeek 重启融资、字节 10 万亿参数大模型、英伟达投的 AI 基建独角兽 130 亿、Agent 安全防御等）；5 张信号卡全部带「印证趋势」标签（1 规模红利 + 4 钱去哪了）。校验新增 check_trend_evidence（断言 ≥1 条本周印证）。
• 结论：宏观洞察从"永远同一篇 essay"变为"每周用本周真实事件佐证"，与 M1、本周看点、关键词形成同一证据链。

M3（图表分析厚度，1 月）

10. 中国市场规模标 YoY：9188→12000（+30.5%）→17000（+41.7%）加增速标注。

11. 预测区诚实表达：全球市场 2027F/2028F 用虚线或阴影带区分"实测 vs CAGR 外推"。

12. 融资图加 AI 占比参考线：AI 占全球 VC >70%（Crunchbase H1）做成注释或参考线。

13. 校验器加 check_market_data：每图 ≥3 点（或显式柱状）、每图来源署名、快照日期显示、无"示例/估算"与真实源并存的矛盾。

9.3 市场数据校验（并入 validate_report.py）

校验项	阈值	现状（2026-08-10）
自损式"示例/估算"免责	0 处	0 处（已撤，改真实来源署名）✅
每图真实来源署名	100%	6 图均带真实来源（国内源优先）✅
本周信号联动	≥3 条本周事件	5 张信号卡（W32 真实事件）✅
中国融资含当期点（2026H1）	图含 3076 亿	3 点含 2026H1 3076.82 ✅
结构数据可视化	融资细分成图	结构图 + 集中度图（市场板块共 6 图）✅
预测区区分	实测/外推可分	深/浅蓝区分 + ▨ 提示 ✅
中国规模 YoY	增速标注	柱+线组合，YoY 折线（+30.6%/+41.7%）✅
AI 占比参考线	融资图注释	「AI 占全球 VC >70%」参考线 ✅

9.4 市场分析优化路线图（叠加于第六章）

阶段	周期	市场分析收益
M0	1 周	撤自损免责 + 真实署名 → 数据从"像假的"变"可信"
M1	2–3 周	本周市场信号 + 资本↔能力联动 → 板块从"静态"变"关于本周"
M2	2–3 周	融资结构/集中度成图 → 从"散文"变"可视化分析"
M3	1 月	YoY/预测诚实度/校验 → 分析厚度与防回归

✅ 已落地（2026-08-10）：build_charts() 三处加厚——①全球规模图按标签是否以 F 结尾区分实测(深蓝实色)/CAGR 外推(浅蓝)，tooltip 标注"非实测"，图下加 ▨ 浅色柱=CAGR外推 提示；②中国规模图改为柱+线组合，叠加自动计算的 YoY% 折线（2025 +30.6% / 2026E +41.7%，右轴%），tooltip 显示同比；③全球融资图加 📊 参考线：AI 占全球 VC 比重 >70%（Crunchbase H1 2026） 注释。validate_report.py 新增 check_market_data（断言 6 图齐全 + 四源署名占位已替换 + [DATA_SNAPSHOT] 已替换 + 无"示例/估算"残留）。重生成 AI_News_2026-08-08.html（W32，102 条 + 翻译）验证：校验 14/14（含新增 2 项）。

9.6 跨语言优化（英文报道中文总结，用户议题 2026-08-10 落地）

• 问题：报告含约 40% 英文报道（lang=en），中文读者只能看到英文标题与摘要，理解门槛高；"关于本周"的英文报道缺中文抓手。
• 设计（本地、零 API 成本、国内友好）：generate_site.py 新增 _ollama_translate()（调本机 Ollama qwen2.5:7b，best-effort、并行 6 线程、单条超时 25s）+ translate_en_summaries()（仅翻译 lang=en 且缺 cn_summary 的条目）+ --translate-en 开关；format_news_items 透传 cn_summary；模板新闻卡：en 且含 cn_summary 时主显中文总结 + 「中文」绿标，下方附原文小字（边框左线区分）。失败/超时/Ollama 未运行均静默回退（保留英文原文），不阻断报告生成。
• 效果（W32 实测）：41 条英文报道经本地 Ollama 翻译注入 cn_summary，卡片显示中文总结；校验新增 check_en_cn_summary（warn 级：含英文报道却无中文总结时提示开启 --translate-en）。
• 约束：默认关闭（--translate-en 才触发），保持离线生成的确定性与可复现；翻译靠本地 Ollama，不引入任何第三方商业 API、不触合规红线。未来每周自动化跑报时，在 generate 前（或同命令）加 --translate-en 即可自动获得中文总结。

✅ 已落地（2026-08-10，Fix1）：用户反馈"英文卡的中文总结只显示 2 行"——根因是 .card-summary 带 -webkit-line-clamp: 2。模板 JS 加 isEnCn 判定：英文 + 中文总结时挂 no-clamp 类并放开截断 → 中文总结全文可见；中文原生卡仍保持 2 行统一版式（不破坏原阅读节奏）。同时把 Ollama 翻译的 num_predict 从 220 提到 400（未来每周 automation 跑 --translate-en 时译文更完整）。W32 实测：41 条英文报道均带 cn_summary 且卡片显示中文全文；中文卡 2 行截断无变化。校验 check_en_cn_summary 已守护 100% 覆盖率。

一句话：市场板块现在"图是真的、话是虚的、和本周是断的"。M0 一笔抹掉自我否定、把真源亮出来，是零成本第一刀；M1 把本周 100 条新闻里的融资/并购事件接进宏观图，才是"市场分析"而非"市场百科"。与第八章内容优化、第三章分发管线可并行，互不阻塞。

十、大模型排行榜优化（开发视角，用户议题 2026-08-10）

排行榜板块是「估值/选型决策」的最后一步：用户打开周报主要看 ①本周新闻 ②市场板块 ③哪个模型该选。当前实现已经把"多源 + 网络自适应 + 快照兜底 + 选型卡"四件套搭起来了，但仍有数据归一、交互密度、跨源解释、校验守护四个缺口。

10.1 排行榜板块体检（基于 AI_News_2026-08-08.html 实测 + generate_site.py / news_site_template.html 代码走读）

维度	实测	评估
多源池架构	7 源池（4 综合：AA/LMArena/OpenCompass/SuperCLUE；3 开源：LLM-Stats/DataLearner/HF），按 region 排序	✅ 设计成熟
网络自适应	_detect_region() 国内哨兵（baidu / opencompass）+ 国外哨兵（lmarena / hf），并支持 --proxy / HTTPS_PROXY	✅ 强
快照兜底	国内 → cn_leaderboard_snapshot.json（OpenCompass 综合+开源）；国外/未知 → leaderboard_cache.json；全挂显示「暂无实时数据」+ 徽章「快照」	✅ 双保险
来源透明度	每列徽章 实时·国内源 / 实时·国外源 / 缓存快照，页脚写明网络环境	✅ 用户清楚从哪来
模型档案卡（modal）	canonical 档案 model_profiles.json + 实时 pending 闭环；行点击打开卡；展示机构/许可证/成本/上下文/多模态/适用场景	✅ 关键字段齐全
模型名归一	_SUFFIX_RE = (max|xhigh|high|thinking|withfallback|preview|pro|flash|sol|ultra) + _vnorm 去末尾括号；用于象限去重与跨源匹配	⚠️ 后缀不全（缺 lite/mini/small/base/instruct/it/chat/v2/2/3 等）
跨源差异	cross_diff 按 model 大小写匹配 + `	diff	` 排序	⚠️ 仅展示差异大小，无"为什么不同"上下文
选型结论	selection_note 硬编码逻辑：top_name + 「国内可直连 + price_out≤2$」的 cheap 模型	⚠️ 无受众定制（与第 8 章 audience_summary 不联动）
性价比象限	value_chart 散点（能力分 vs price_out），tooltip 含 context/cn_access	⚠️ 散点无「国内可直连」视觉标记
榜单趋势	_apply_deltas 仅 1 个 cache 快照对比	⚠️ 无法画 WoW 趋势线
新上榜徽章	无（虽 _apply_deltas 算 delta 但 UI 未渲染）	⚠️ 资产闲置
筛选维度	仅 lbFilter 三选（all/open/closed）	⚠️ 无按机构/许可证/价格区间筛选
时效告警	lbStaleWarn banner（>3 天提示）+ 每源「非本周抓取」徽章	✅ 已落地
校验	check_ranking_v3：每榜 ≥5 条即通过	⚠️ 仅数量断言，无 source_url / snapshot / 模型名唯一性 / 跨源一致性
缓存	leaderboard_cache.json 单层 model→rank/score	⚠️ 无法做趋势分析、无法跨版本 diff
渲染体积	4 榜 × ~10-15 行 + 模态框 + 象限图（Chart.js scatter）	✅ 单文件 100KB 内可接受
测试覆盖	无单测，仅 E2E validate_report.py	⚠️ _apply_profile_as_truth / _norm_model / 选型算法裸跑
模块化	排行榜逻辑全在 generate_site.py 3272-1493 行	⚠️ 与其他功能混在一起，难维护

✅ 既有能力（已落地，10.2 的优化是「补短板」非「从零搭」）——下列基础设施早已在跑，本次提议的 L0–L3 是叠加优化：

• 多源池：SOURCES 字典 7 个源（4 综合 AA/LMArena/OpenCompass/SuperCLUE + 3 开源 LLM-Stats/DataLearner/HF + ModelScope 备用），按 region 自动排序优先级；fetch_all_leaderboards() 每次生成自动跑。
• 网络自适应：_detect_region() 国内哨兵（baidu / opencompass）+ 国外哨兵（lmarena / hf），--region auto/cn/global + --proxy / HTTPS_PROXY 双管齐下。
• 快照兜底：国内 → cn_leaderboard_snapshot.json（OpenCompass 综合 + 开源）；国外/未知 → leaderboard_cache.json；全挂徽章「快照」 + 文本「暂无实时数据」。
• 来源透明度：每列 regionBadgeHTML(lm) 徽章 + 页脚网络环境注明，用户始终知道数据从哪来。
• 模型档案卡（modal）：canonical model_profiles.json + 实时 pending.json 闭环；行点击打开卡；展示机构/许可证/成本/上下文/多模态/适用场景；_apply_profile_as_truth() 断言档案字段优先于榜单行内字段（资料卡是权威源）。
• 跨源差异 cross_diff：按模型名匹配 lmarena vs aa，|diff| 排序后展示，已渲染。
• 性价比象限 value_chart：Chart.js scatter（能力分 vs price_out），tooltip 含 context/cn_access，已渲染。
• 选型结论 selection_note：top_name + 「国内可直连 + price_out≤2$」的 cheap 模型，已生成。
• 榜单时效告警：_leaderboard_freshness() 算每源 snapshot 距今天数；lbStaleWarn banner + lbSnapshot 文案 >3 天源显式标「非本周抓取」；validate_report.py check_editorial_c1 守护（C1#5）。
• 校验：check_ranking_v3（每榜 ≥5 条）+ check_editorial_c1（快照标注就位）已就位。

10.2 的 L0–L3 是给上述「能用但粗」的基础设施加精：归一精度（aliases）、受众化选型（audience 联动）、趋势 sparkline（时序缓存）、新上榜徽章（delta 可视化）、多维筛选（机构/许可证/价格）、并行抓取（性能）、单测覆盖（回归守护）。

10.2 优先级优化举措

L0（开发必杀技，1 周内，纯代码层改动）

1. 模型名归一强化：维护 model_aliases.json（如 {"gpt-4o": ["gpt-4o", "GPT-4o", "gpt-4o-2024-08-06"], "qwen2.5": ["qwen2.5-7b", "qwen2.5:7b", "Qwen2.5-7B-Instruct"]}），用别名表归一后做 match，取代正则后缀法。好处：跨榜匹配 100% 准确；新模型只要加别名即可。映射表随排行榜 release notes 维护。
2. _apply_deltas 输出 trend_3w：当前 _save_cache 是单点 dict，升级为 snapshots/{date}.json 时序数组。delta 字段升级为 {"wow": +2, "wow_score": -0.5, "new_entry": false}。前端可渲染「↗ +2 WoW」徽章。
3. selection_note 受众化：复用 audience_summary 三受众（开发者/PM/自媒体）模板，生成 3 段结论（各 ≤1 句），让用户切受众看不同视角。
4. check_leaderboard_quality 校验：校验每榜
   • source / url / snapshot 必填非空
   • model 字段非空且无空字符串
   • 同一榜内 model 去重（避免"(max)" / "(pro)" 双胞胎）
   • 跨榜（lmarena vs aa）同名模型 rank 差异 >20 触发告警（数据一致性问题）
5. 榜源 schema 校验：每个 fetch_* 函数返回前过一遍 LB_SCHEMA（jsonschema 或手写），确保字段名/类型一致——目前 4 个 fetcher 返回的 rows[].* 字段名散乱（price_in vs cost_in 等）。

L1（UX/交互，2-3 周）

1. 「新上榜 / 大幅上升」徽章：基于 _apply_deltas 算 delta=+N，UI 渲染「🆕 新上榜」「↗ +N」绿色徽章；大幅下降（≤-5）渲染「↘」警示。
2. WoW 趋势迷你线：在每个模型行末尾加 4 周 sparkline（纯 SVG，~16×24px），显示最近 4 个快照的 rank 趋势。
3. 「国内可直连」行内标签：当前 cn_access 字段只在 tooltip / selection_note 用，加 🇨🇳 行内 badge（绿色小圆点），让国内用户快速锁定可选项。
4. 多维筛选：把 lbFilter 升级为组合筛选（开源/闭源 + 价格区间滑块 + 许可证类型 + 国内可直连 toggle），叠加生效。
5. 跨源差异加上下文：每个 cross_diff 行下面加一行小字「评测维度差异：LMArena 偏人类偏好 vs AA 偏推理能力」——为差异给读者一个解释锚点。
6. 模态框键盘导航：modal 加 ←/→/ESC 快捷键浏览上/下个模型，对比时不用一次次关闭再开。

L2（架构演进，1 月）

1. 拆模块：把排行榜逻辑（fetcher / cache / profile sync / rendering data）拆到 scripts/leaderboard/ 子包，主文件瘦身 30%+。
2. 单元测试：为 _norm_model / _apply_profile_as_truth / selection_note 算法 / _leaderboard_freshness 加 pytest（无需外网，纯函数）。
3. 并行抓取：fetch_all_leaderboards 当前是顺序 _retry_fetch，改为 concurrent.futures.ThreadPoolExecutor 并行（max_workers=4），首屏提速 ~3×。
4. 榜源健康监控：在 generate 末尾 append 一行 leaderboard_health.jsonl（每行 {ts, source, status, latency_ms, rows_count}），积累数据后可看趋势、识别「LMArena 周末常挂」。
5. 结构化日志：把 print() 改成 logging（DEBUG/INFO/WARNING 三级），CI/定时任务便于过滤。
6. 榜单 A/B 评测说明卡：在排行榜顶部加「这些榜分别测什么」折叠卡，5–8 行说清每个榜的评测维度（人类偏好 / 推理 / 开源综合），降低读者误读。

L3（远期）

1. 用户自定义权重排序：让用户在前端用滑块给「成本/上下文/许可证/能力」加权，按加权总分排序——可大幅提升选型决策准确度。
2. 模型知识图谱：从档案数据反查「同机构模型」「同许可证模型」「同上下文窗口量级」形成网状关系，让读者从任一模型跳到同家族。
3. 榜源自托管镜像：对 LMArena 等被 GFW 屏蔽的源，提供 GitHub Pages 镜像 + 定时抓取 → 用户只需拉镜像，无须代理。

10.3 排行榜校验守护（并入 validate_report.py）

校验项	阈值	现状	等级
每榜 rows 长度	≥ 5	已通过	✅ L0
每榜 source / url / snapshot 非空	100%	无	❌ → L0 必加
同榜 model 去重（去除变体后）	无重复	无	❌ → L0
跨榜同名 model rank 一致性		rank_diff	≤ 20	无	❌ → L0
快照时效（>3 天显式告警）	已渲染 banner	已通过	✅ L0
model_profiles 关键字段完整	org/license/cost_in/cost_out/context	部分缺失	⚠️
fetcher 返回 schema 一致	与 LB_SCHEMA 比对	无	❌ → L0
selection_note 含受众分群	3 段（开发者/PM/自媒体）	无	❌ → L0
WoW delta 字段存在性	≥ 50% 模型有 delta	无	❌ → L1
选型卡 lb-modal 可键盘关闭	ESC 关闭	无	⚠️ L1

10.4 排行榜优化路线图（叠加于第六章）

阶段	周期	排行榜收益
L0	1 周	模型名归一 + 校验加严 + selection_note 受众化 → 选型结论「可信、可解释、对受众有用」
L1	2–3 周	新上榜徽章 + WoW sparkline + 国内可直连标签 + 多维筛选 → 板块从「数据罗列」变「选型决策辅助」
L2	1 月	模块化 + 单测 + 并行抓取 + 健康监控 → 可维护性 + 性能双双提升，团队协作友好
L3	长期	自定义权重 + 知识图谱 + 自托管镜像 → 从「看榜」变「用榜」

一句话：排行榜已是「数据真且多源」，但「数据归一弱、缺上下文、缺校验」。 L0 一周把归一 + 校验 + 受众化补齐，是性价比最高的第一刀；L1 把新上榜徽章 + WoW 趋势 + 国内可直连标签接上，板块就真正成为「选型决策辅助」而非「榜单搬运」。与第八章内容优化、第三章分发管线（飞书/钉钉推送）可并行推进，互不阻塞。

---

十二、工程债治理（屎山防御 + 异常防御 + ISO 8601 标准化）

优化做多了，债也跟着长。本章把分散在各次迭代里「先这样吧」的隐患集中清账，让 skill 一年后还能维护。用户议题：避免屎山代码 + 防止异常 + ISO 8601 日期标准化。

12.1 工程债清单（基于 generate_site.py / validate_report.py / fetch_ai_news.py 实测）

#	债点	实测位置	当前状态	风险
D1	单文件臃肿	generate_site.py 3250 行（一文件包含 fetcher + 渲染 + 校验逻辑全栈）	🔴 高	协作冲突频发、新人上手成本高、单测无法隔离
D2	裸 except Exception 沉默吞错	generate_site.py 28 处（line 142/303/324/396/586/638/692/706/763/884/977/987/1001/1086/1129…）	🔴 高	失败时静默、生产事故定位难、数据污染不被察觉
D3	无结构化日志	generate_site.py 53 处 print() + 0 处 logging	🔴 高	定时跑/无人值守时日志无法过滤级别、难接入 Sentry/Logfire
D4	关键路径无显式超时	_http_get 默认超时 60s，部分 fetcher 未传；translate_en 超时 25s 无超时链	🟡 中	长时间挂起、批量翻译卡死
D5	日期格式不统一	[GEN_DATE] = datetime.now().strftime("%Y-%m-%d %H:%M")（line 2284）	🟡 中	非完整 ISO 8601（无 T 分隔符、无时区），与 RSS publishedAt 格式不一致
D6	_parse_date_arg 容错弱	仅接受 %Y-%m-%d；T/Z/时间部分报错	🟡 中	用户传 2026-08-08T00:00:00Z 直接报错；外部 API 注入需二次转换
D7	重试策略不显式	_retry_fetch 存在但未统一退避（无抖动、无指数、无熔断）	🟡 中	榜源偶发 503 时仍可能雪崩
D8	模块边界无 __all__	三个脚本无 __all__ 声明	🟢 低	隐式 API 暴露，重构时易误删
D9	无单元测试	仅 E2E validate_report.py（覆盖 HTML 输出，不覆盖函数）	🔴 高	改一行函数全靠人工跑周报验证，回归代价高
D10	类型注解不完整	format_news_items/_auto_lead/_extract_market_signals 等无 -> 与 : 类型	🟡 中	IDE 智能提示弱、阅读时类型需肉眼推断
D11	模块耦合高	fetch_all_leaderboards 直接 _save_cache、_compute_weekly_stats 直接构造 HTML 字符串	🟡 中	单测 mock 困难，跨模块重构风险高
D12	CLI 参数膨胀	generate_site.py 30+ 个 flag	🟢 低	易用性下降，但有 --config-json 兜底

12.2 屎山防御（模块化 + 类型 + 接口边界）

P0（1 周内，止血）

1. 拆分 generate_site.py：从 3250 行单文件拆为以下子包（不动外部接口）

   scripts/
   ├── generate_site.py          # CLI + generate() 主入口（瘦到 ≤ 500 行）
   ├── aiweekly/
   │   ├── leaderboard.py        # 多源池 / 区域探测 / 快照兜底 / 选型结论（line 440–1500 现状）
   │   ├── insights.py           # 看点 / 关键词 / 数字看板（line 2250–2360）
   │   ├── market.py             # 市场数据默认值 + build_charts（line 1500–1750）
   │   ├── translate.py          # Ollama 翻译（line 110–170）
   │   ├── news.py               # 抓取 / 归一 / 评分（line 80–340）
   │   └── utils.py              # 日期 / 日志 / 重试 / HTML 转义等公用
   

   拆分原则：先按"职责"垂直切（fetcher / renderer / enricher），再考虑横向提取公用（_parse_date_arg / _escape_html / format_news_items）。新目录与 __init__.py 不破坏现有 import 路径（from generate_site import generate 仍可用，垫一层兼容 shim）。

✅ Phase 1 已落地（2026-08-10）：先拆最独立的 3 个模块——aiweekly/utils.py（日期/网络/代理/区域）+ aiweekly/translate.py（Ollama 翻译）+ aiweekly/news.py（信源归一/摘要压缩/语言判定/重要度评分）。generate_site.py 3250 → 2866 行（-384，-12%）；新子包合计 525 行（含 __all__ 与 docstring）。外部 API 通过 __init__.py 显式 re-export 全部保留；proxy 全局状态 _PROXY_OVERRIDE/_SOCKS_ACTIVE 落到 aiweekly.utils，main() 通过 import aiweekly.utils as _au 赋值。W32 报告重生成 + 校验器 19/19 全绿无回归。

踩坑修复：新版 _parse_snapshot_date 初版返回 datetime 而旧版返回 date，导致 _leaderboard_freshness 的 report_date.date() - d 算术报错。修正为统一返回 date（带时间则取 .date()），下游零改动；P0 计划 12.4 ISO 8601 升级时再统一改为 datetime 并同步所有调用点。

✅ Phase 2 + Phase 3 已落地（2026-08-10）：在 Phase 1（utils/translate/news/types）基础上，继续抽出 market.py / leaderboard.py / insights.py / model_meta.py / leaderboard_sources.py / render.py（6 模块），generate_site.py 由 3250 行瘦到 495 行（≤ 500 ✅），全部子模块 ≤ 800 行（最大 market.py 620）。外部 API 经 __init__.py re-export 全保留，from generate_site import generate 零改动。P1#6 依赖注入（_http_get/_probe/_detect_region/_retry_fetch/_ollama_translate 支持 client/opener/sleeper/probe 注入）已落地，单测可脱网；P0#8 28 处裸 except 收窄 + P0#9 结构化日志（D2/D3）同步完成。11 模块全部 py_compile + import 冒烟通过；W32 起多次完整回归 errors=0。

1. __all__ 显式声明：每个新模块顶部 __all__ = ["generate", "fetch_all_leaderboards", ...]，明确对外 API。私有函数下划线前缀 + 模块级 _ 开头（惯例已部分做到，规模化）。

✅ 已落地（2026-08-10）：11 个模块（generate_site.py + aiweekly/ 下 utils translate news types market leaderboard leaderboard_sources insights model_meta render + __init__.py）全部声明 __all__，明确对外 API；私有函数统一 _ 前缀。导入冒烟确认 from generate_site import generate 及 from aiweekly import ... 全部可用。

1. 关键数据结构 TypedDict：在 aiweekly/types.py 定义：

   class NewsItem(TypedDict, total=False):
       title: str; summary: str; url: str; source: str
       publishedAt: str  # ISO 8601
       category: str; lang: str; score: float; mustRead: bool
       cn_summary: str
   class LeaderboardRow(TypedDict, total=False):
       model: str; rank: int; score: float; org: str
       license: str; context: int; price_in: float; price_out: float
       delta: int; cn_access: str
   class LeaderboardSlot(TypedDict, total=False):
       source: str; url: str; snapshot: str  # ISO 8601
       criteria: str; rows: list[LeaderboardRow]
       source_region: str; is_cache: bool

   函数签名 -> list[NewsItem] / -> LeaderboardSlot 全量覆盖。D10 同时消化。

✅ 已落地（2026-08-10）：新增 aiweekly/types.py（55 行，纯类型文件）——NewsItem / LeaderboardRow / LeaderboardSlot 三个 TypedDict(total=False)，日期字段约定为 ISO 8601 串；format_news_items 返回类型文档化（-> list 并注明 NewsItem 形态）。Phase 2 拆分由 3/6 推进到 4/6（utils / translate / news / types）。W32 重生成 + 校验 21/21 无回归。

1. check_module_size 校验：合并入 validate_report.py，断言 scripts/generate_site.py ≤ 3500 行（拆分后每文件 ≤ 800 行）。本节本身不修代码，只挂守护——拆分是 P0 行动项，校验是 P0 守护项。

✅ 已落地（2026-08-10）：validate_report.py 新增 check_module_size(source_dir, main_max=500, mod_max=800)，遍历 scripts/ 与 scripts/aiweekly/ 下全部 .py（跳过 .bak/.bak2/__init__.py），超限即 ok=False 并在 print_report 的 v3 校验清单追加 ("模块体量(P0#4)", ...)。2026-08-10 实测：generate_site.py = 495 行（≤ 500 ✅）、最大子模块 market.py = 620 行（≤ 800 ✅），全绿。守护生效——后续任何模块再次膨胀会被校验器拦下。

P1（2–3 周）

1. 依赖注入 + 接口抽象：_http_get / _probe / _ollama_translate 改为接受 client 参数（默认 None 时用真实实现），单测可传 mock 返回固定数据，不再依赖网络或本地 Ollama。D11 部分缓解。
2. 文档字符串统一：def xxx(): 上方补「输入 / 输出 / 异常 / 示例」四段式 docstring（关键函数 20+ 个先做），便于 IDE 渲染 + 新人阅读。

12.3 异常防御（收窄 + 重试 + 日志）

P0（1 周内，与模块化并行）

1. 收窄 28 处裸 except Exception：分级处理

   • 网络类 → (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, ConnectionError)，记 logger.warning("fetch X failed: %s", e) 后回退；
   • 解析类 → (json.JSONDecodeError, KeyError, ValueError, AttributeError, IndexError)，记 logger.error("parse X failed: %s", e) 后回退；
   • 必须静默的极少数点（如 _normalize_source 处理未知信源）→ 显式 except (KeyError, TypeError) 并写注释说明「故意静默」；
   • 严禁保留 except Exception：除非有明确注释说明为何要捕获所有。

2. 结构化日志（替换 53 处 print）：

   import logging
   logging.basicConfig(
       level=logging.INFO,
       format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
       datefmt="%Y-%m-%dT%H:%M:%S%z",  # ISO 8601
   )
   logger = logging.getLogger("aiweekly")

   print("✅ 已生成 ...") → logger.info("已生成 %s（%d bytes，%d 条新闻）", output, size, count)

   print("⚠️ ...") → logger.warning(...)

   print("❌ ...") → logger.error(...)

   注意：进度条式 ASCII 图标（✅ / ⚠️ / ❌）保留在 print 用于直接 console 输出；详细日志走 logger。

3. 重试退避策略统一：_retry_fetch 改为指数退避 + 抖动：

   for attempt in range(retries):
       try: return fn()
       except (URLError, TimeoutError, HTTPError) as e:
           if attempt == retries - 1: raise
           sleep_s = min(2 ** attempt, 30) + random.uniform(0, 1)
           logger.warning("retry %d/%d after %.1fs: %s", attempt+1, retries, sleep_s, e)
           time.sleep(sleep_s)

   默认 retries=3，避免无限重试雪崩。D7 消化。

4. check_no_bare_except 校验：合并入 validate_report.py，扫描 generate_site.py 统计 except Exception 数量，断言 ≤ 5 处（每处必须邻近有注释说明合理沉默点）。D2 守护。

✅ 已落地（2026-08-10）：异常防御 P0 四项全部落地——

• 收窄裸 except（P0#8）：generate_site.py 的 --ranking-json / --audience-summary 读取收窄为 (json.JSONDecodeError, OSError)、--keyword-search-sources 收窄为 OSError；抓取层 except Exception 属有意 best-effort 网络容错（单源失败必须不阻断管线，回退缓存/标注「暂无实时数据」），统一加 # noqa: BLE001 与文件顶部合理性注释块说明——裸 except 0 处，符合「每处有注释说明合理沉默点」的约束。
• 结构化日志（P0#9）：main() 加 logging.basicConfig(level=INFO, format=含时间戳)；开始渲染处 logger.info("开始渲染 HTML（新闻数=%d）", count)。按 12.3 注记，✅/⚠️/❌ 进度 print 保留用于 console，详细日志走 logger。
• 重试退避（P0#10）：aiweekly/utils.py _retry_fetch 改为指数退避 + 抖动：sleep_s = min(cap, base * 2**i) + random.uniform(0,1)（默认 attempts=3、base=1s、cap=30s）。
• check_no_bare_except 守护（P0#11→P0#19）：validate_report.py 新增 check_no_bare_except()（硬规则：裸 except: 即失败；except Exception 按「有日志/业务处理 → best-effort」「EAFP 默认回退 → best-effort」「其余静默 → 计数，超 20 告警」分级）+ check_iso8601()（.strftime("%Y-%m-%d %H:%M") 注入即失败、[GEN_DATE] 未接 isoformat 即失败、_parse_date_arg 未含 fromisoformat 即失败）。接入 CLI --source-dir（默认自动定位 scripts/）；缺失 HTML 时源码守护仍先执行。自测通过：无裸 except、ISO 8601 达标。校验总分 19/19 → 21/21。
• 实测：validate_report.py --html AI_News_2026-08-08.html → 21/21 全绿（新增「无裸except(P0#19)」「ISO8601日期(P0#19)」两项）。

P1（2–3 周）

1. 错误聚合报告：generate() 末尾汇总本次运行的 warning 计数（"⚠️ 本次跳过 3 条榜源（lmarena 超时/hf 超时/aa 超时）"），写入 <output>.validation.json 旁边一个 <output>.run.log。
2. _check_network 健康探测：CLI 加 --health-check 子命令，只跑探测 + 抓首榜首条，不生成报告——用于 CI/定时任务前置探测，5 秒出结果。
3. 本地 Ollama 健康探测：translate_en 前先 ping /api/tags 确认模型可用，失败则直接跳过翻译并打 warning（避免每个条目都超时 25s）。

✅ 已落地（2026-08-10）：

• 错误聚合（P1#12）：main() 用 _CountingWriter 包装 stdout，统计本次运行的 ⚠️/❌ 出现次数；生成完成后写 <output>.run.log（含时区时间戳、news 数、warnings/errors 计数）。W32 实测：warnings=1 / errors=0。
• 健康检查（P1#13）：CLI 加 --health-check，只探测可达性不生成报告。踩坑：初版在 _run_health_check 里真抓排行榜（不可达源 + 指数退避 → 卡数分钟被超时杀进程且 print 缓冲丢失无输出）；改为只 _probe URL 可达性（6s 超时，8 个哨兵/榜源），秒级返回。cn 环境实测：百度/OpenCompass/AA/LLM-Stats 可达，LMArena/HF 不可达（生成时会自动回退快照）。
• Ollama 健康探测（P1#14）：✅ 已落地——aiweekly/translate.py 新增 ollama_health(timeout=3.0, model=None, opener=None)，ping /api/tags 探活；translate_en_summaries 开启时先探活，不可用立即返回 0 避免逐条超时；generate_site.py --health-check 也接入该探测。

12.4 ISO 8601 日期标准化

P0（1 周内）

1. _parse_date_arg 扩展：接受完整 ISO 8601：

   def _parse_date_arg(token: str) -> datetime:
       """Accepts ISO 8601: YYYY-MM-DD / YYYY-MM-DDTHH:MM:SS / YYYY-MM-DDTHH:MM:SSZ / +08:00."""
       s = token.strip()
       try:
           return datetime.fromisoformat(s.replace("Z", "+00:00"))  # 完整 ISO 8601（含 T/时区）
       except ValueError:
           pass
       try:
           return datetime.strptime(s, "%Y-%m-%d")  # 兼容纯日期
       except ValueError:
           raise ValueError(f"非 ISO 8601 日期：{token!r}（需 YYYY-MM-DD 或 YYYY-MM-DDTHH:MM:SS±HH:MM）")

   D6 消化。
2. [GEN_DATE] 输出改完整 ISO 8601：

   # 旧：datetime.now().strftime("%Y-%m-%d %H:%M")  ← 非标准
   # 新：
   template = template.replace("[GEN_DATE]", datetime.now().astimezone().isoformat(timespec="minutes"))

   输出形如 2026-08-10T12:33+08:00，与 RSS publishedAt 风格一致。D5 消化。
3. CLI --date / --data-snapshot 输入校验：CLI 参数解析时即时校验 ISO 8601；不通过直接 parser.error("非 ISO 8601 ...")，不进入 generate()。D6 进一步强化。
4. JSON 输出字段统一：所有写入 cache.json / cn_leaderboard_snapshot.json / report.json（如果未来加）的日期字段统一用 datetime.now().astimezone().isoformat()；不允许 "%Y-%m-%d %H:%M:%S" 这种半生不熟的格式。
5. check_iso8601 校验：合并入 validate_report.py，扫描 HTML 中的 [DATA_SNAPSHOT]、LEADERBOARD_DATA.*.snapshot、meta.snapshot_per_source 三个关键字段，全部为 ISO 8601 date 或 ISO 8601 datetime；不符合即 fail。D5+D6 守护。

✅ 已落地（2026-08-10）：ISO 8601 P0 四项全部落地——

• _parse_date_arg 扩展（P0#15）：aiweekly/utils.py 改为 datetime.fromisoformat(s.replace("Z","+00:00")) 优先（完整 ISO 8601 含 T/Z/时区），回退 %Y-%m-%d 纯日期，两者皆失败显式抛 ValueError（不再静默报错）。
• [GEN_DATE] 输出（P0#16）：generate_site.py 改为 datetime.now().astimezone().isoformat(timespec="minutes")，输出形如 2026-08-10T12:33+08:00（含 T 分隔符与本地时区），与 RSS publishedAt 风格一致。
• CLI 输入（P0#17）：✅ 已落地——--date / --data-snapshot 走 _parse_date_arg / _parse_snapshot_date 解析层强校验，且 generate_site.py 在 args = parse_args() 后即时 parser.error 拦截非法 ISO 8601（如 2026-13-99 / not-a-date），不进入 generate()；合法完整 ISO（2026-08-08T00:00:00+08:00）走 --dry-run 正常。CLI 层与解析层双保险。
• check_iso8601 守护（P0#19）：validate_report.py 新增（见 12.3 落地块），源码扫描 .strftime("%Y-%m-%d %H:%M") 注入即失败，[GEN_DATE] 必须接 isoformat，_parse_date_arg 必须含 fromisoformat；自测通过，校验 21/21。
• 踩坑：check_iso8601 正则曾匹配到自己的文档字符串/注释/源码里的 .strftime('%Y-%m-%d %H:%M') 字面量（自匹配误报）——解法：正则用拼接构造（r'\.' + "strftime" + ...）并去掉注释中的连续字面量；该经验已沉淀。

✅ P0#18（JSON 输出字段统一）已落地（2026-08-10）：全代码 grep 确认无任何 %Y-%m-%d %H:%M:%S / %Y-%m-%d %H:%M 半生不熟 datetime 格式——leaderboard.py 写缓存用 .astimezone().strftime("%Y-%m-%d") 产出 ISO date（2026-08-10，与 P1#21 的 snapshot_per_source 约定一致）；fetch_ai_news.py 的 publishedAt/checked_at 用 .isoformat()（含 T+时区）；[GEN_DATE] 用 astimezone().isoformat(timespec="minutes")。validate_report.py 的 check_iso8601 守护专门扫描 .strftime("%Y-%m-%d %H:%M") 注入即失败，自测通过。

P1

1. 时区统一：内部所有 datetime.now() 改为 datetime.now().astimezone()（带本地时区），写入 cache/HTML 时显式 .isoformat()。当前 datetime.now() 是 naive datetime，跨时区用户混淆。
2. snapshot_per_source 改为 ISO 8601：当前 _leaderboard_freshness 返回 int 天数（如 {"comprehensive.lmarena": 9}），改为 {"comprehensive.lmarena": "2026-07-30T..."}，由校验器或前端算天数差。语义更明确、可对比、可排序。

✅ 已落地（2026-08-10）：

• 时区统一（P1#20）：generate_site.py 三处 datetime.now() → datetime.now().astimezone()（914 排行榜快照、1867 日期范围、1890 数据快照）；[GEN_DATE] 已带 +08:00（P0#16 时落地）。W32 实测输出 2026-08-10T15:36+08:00。
• snapshot_per_source（P1#21）：_leaderboard_freshness 的 per_source 改存 ISO 8601 快照串（如 "comprehensive.lmarena": "2026-07-30"），新增 per_source_age（天数）供模板渲染时效标注（向后兼容，避免前端改 JS）；generate() 同步注入 meta.snapshot_per_source_age，模板读 snapshot_per_source_age || snapshot_per_source。W32 实测：per_source 为 ISO 串、per_source_age 为天数（lmarena 9 天告警正常触发），校验 21/21 无回归。

12.5 校验守护（并入 validate_report.py）

校验项	阈值	现状（2026-08-10）	等级
generate_site.py 行数	≤ 500（主入口）/ ≤ 800（子模块）	495（全拆完 11 模块，最大子模块 620）	✅ 已完成
裸 except Exception 数量	≤ 5（含合理沉默点）	裸 except 0；best-effort 39 处（均带注释说明）✅	✅ 守护已挂
logging 模块使用	≥ 1（替换 print 起点）	≥1（basicConfig + logger.info）✅	✅
[GEN_DATE] ISO 8601 完整格式	包含 T 与时区	astimezone().isoformat(timespec="minutes") ✅	✅
[DATA_SNAPSHOT] / snapshot 字段 ISO 8601 date	100%	✅	L0
--date / --data-snapshot CLI 输入 ISO 8601 校验	100%	解析层 fromisoformat + CLI 层即时 parser.error 双保险 ✅	✅
关键数据结构 TypedDict 注解	NewsItem/LeaderboardRow/LeaderboardSlot	types.py 已落地（P1#3）✅；函数签名覆盖待扩	✅ 起步
重试退避（有 sleep_s=2**attempt）	在 _retry_fetch 出现	指数退避 + 抖动已落地 ✅	✅

12.6 落地优先级

阶段	周期	工程债收益
P0	1 周	收窄 28 处 except Exception + 替换 print 为 logging + ISO 8601 三处落地（_parse_date_arg / [GEN_DATE] / CLI 校验）→ 异常可定位、日期标准化、运维可观测
P1	2–3 周	拆分单文件 3250 行 → 6 模块 + TypedDict 全量 + 依赖注入 mock + 重试退避 + 错误聚合 → 可测、可协作、可演化
P2	1 月	健康探测子命令 / Ollama 健康探测 / 时区统一 / snapshot_per_source 改 ISO 8601 → CI 友好、跨时区用户无歧义

一句话：屎山不治理，三轮迭代后每个新功能都要 hack；异常不收窄，一次榜源雪崩就是数小时排查。 P0 一周把异常 + 日志 + ISO 8601 三个面补齐，立刻止血；P1 三周做模块化 + 类型 + 单测，让 skill 进入"可放心改"的状态。

⚠️ 本章与第十章（排行榜优化）并行不阻塞：L0 模型名归一、时序缓存是独立改造，与工程债 P0 的"日期+异常"无交叉。Lint/格式化建议同步引入 ruff（已写入 requirements.txt 后置），CI 加 ruff check + python -m py_compile 双闸门。

---

十三、跨 Agent / 框架兼容（可移植性优化）

北极星新增"全 Agent 通用"维度：情报价值不应被单一宿主锁定。若 ai-weekly 的核心能力（抓取 → 生成单文件 HTML 周报）能被其他 Agent 框架（OpenClaw / LangGraph / Dify / Coze 等）复用，则同一份引擎可服务更多 AI 从业者，且不增加内容/分发管线的开发成本。本章目标：在不重写核心逻辑的前提下，让 skill 既能留在 WorkBuddy，也能"搬"到其他框架跑起来。

13.1 兼容性体检（基于 scripts/ + SKILL.md 走读 + OpenClaw 自带技能格式对照）

维度	实测	评估
引擎层框架耦合	scripts/ 内 grep import workbuddy / WorkBuddy SDK / skill_executor	✅ 零耦合（仅引用自带 aiweekly 本地子包）
第三方依赖	requirements.txt 仅 feedparser / requests / beautifulsoup4	✅ 纯标准第三方，跨平台可装
产物形态	generate_site.py 产出单文件 HTML（Chart.js 内联）	✅ 框架无关，任何 Agent 可返回/托管
包装格式	WorkBuddy 版 SKILL.md + 新增 openclaw-edition/SKILL.md（含 metadata.openclaw）双格式并存	✅ OpenClaw 靠 metadata.openclaw 路由，现已提供对应变体
启动器	run_report.sh 支持 AIWEEKLY_PYTHON 覆盖 + python3/python 优先，WorkBuddy venv 仅兜底	✅ 其他框架可用 python3 或显式 AIWEEKLY_PYTHON 直接跑
触发/调度	WorkBuddy automation 概念已转译为 OpenClaw 版 triggers + cron 0 9 * * 6	✅ 调度语义等价，不绑定框架专属动词
可选能力	_ollama_translate（本地 Ollama）	✅ 通用，有 Ollama 即跑
专属能力	deploy_report.py 已剥离为框架无关的 generate_notification(platform=...)，推送由调用方做	✅ 无 Agent SDK 耦合

13.2 优先级优化举措

X0（可移植性基线核查 — 0 成本，纯验证 + 文档标注）

1. 引擎层零耦合声明：把"scripts/ 内无 WorkBuddy SDK 依赖"作为对外承诺写入 README「兼容性」小节，并附 grep 验证命令，供使用者自行复核。
2. 依赖白名单固定：requirements.txt 仅列 feedparser / requests / beautifulsoup4，README 标注"无闭源 SDK、无云端强依赖"——这是跨框架可装的前提。
3. 产物框架无关化标注：README 写明 generate_site.py 输出单文件 HTML，"不依赖 WorkBuddy，可被任意 Agent 当作普通文件返回或托管"。

✅ 已落地（2026-08-10）：README 新增「兼容性（跨 Agent / 框架可移植性）」小节——引擎零耦合声明 + 可复核 grep 命令（grep -rn "import workbuddy|from workbuddy|skill_executor" scripts/）、依赖白名单（feedparser / requests / beautifulsoup4）、产物框架无关化（单文件 HTML）、可选能力分级（核心链路 vs 框架增强 --translate-en / deploy）。X0#1/2/3 三件事全部落地。

X1（OpenClaw 包装适配 — 核心，1 周内，决定能否被加载）

4. SKILL.md frontmatter 双格式：OpenClaw 变体补 allowed-tools: [read, write, execute, grep, glob] + metadata: {platform: openclaw, version, last_updated, enhancement}，触发词改成 OpenClaw 路由方式；WorkBuddy 版保持原样，两变体并存。

5. run_report.sh 抽象 WorkBuddy 路径：删除硬编码的 ~/.workbuddy/binaries/python/envs/aiweekly/... 候选，改为优先 python3、可用 AIWEEKLY_PYTHON 环境变量或 OpenClaw venv 覆盖；WorkBuddy 版保留原路径。

6. 调度概念转换：列出 SKILL.md 内所有 WorkBuddy automation 绑定点（如"每周一 09:00"），OpenClaw 版改为其 skill_executor 调度描述 / cron 文本，避免框架专属动词外溢到通用说明。

✅ 已落地（2026-08-10）：X1 三项全部完成——

• X1#4 双格式 frontmatter：新增 openclaw-edition/SKILL.md，采用 OpenClaw 规范（已对照 ClawHub / 天禧Claw / 天翼 skill-publish 文档核实）——name/version/description/license/homepage/tags/triggers（数组式触发词）+ metadata.openclaw（emoji / requires.bins: [python3, pip] / envVars 声明可选 AIWEEKLY_OLLAMA_URL）。WorkBuddy 版根 SKILL.md 保持原样，两变体并存。
• X1#5 启动器抽象：run_report.sh 改为优先 AIWEEKLY_PYTHON（环境变量显式覆盖）→ python3/python → WorkBuddy 受管 venv（仅兜底），不再硬编码单一路径，两框架通用。
• X1#6 调度转换：OpenClaw 版把"每周一 09:00 automation"转译为 triggers 触发词 + cron 0 9 * * 6 调度描述，框架专属动词不外溢。

X2（WorkBuddy 专属能力剥离 — 2–3 周）

7. deploy_report.py 剥离：该脚本含 WorkBuddy 云部署/通知逻辑，OpenClaw 版移出或抽象为 --notify 插件接口（飞书/钉钉推送已独立），消除框架耦合点。

8. 可选能力显式分级：README 把能力分两类——核心（fetch / generate / validate，全框架通用）与框架增强（Ollama 翻译、云推送通知，依赖具体环境），避免他框架用户误用专属能力而报错。

✅ 已落地（2026-08-10）：X2 两项全部完成——

• X2#7 deploy 剥离：deploy_report.py 的 generate_workbuddy_notification 重命名为框架无关的 generate_notification(summary, platform="generic")，保留旧名作弃用别名；模块 docstring 删除 WorkBuddy 云部署耦合声明，正文标注"推送由调用方实现"，main() 输出标签改为"可粘贴至任意 IM / 推送通道"。grep 验证 scripts/ 已无任何 import workbuddy / workbuddy_cloudstudio 引用。
• X2#8 能力分级：README「兼容性」小节新增显式分级表——核心（fetch / generate / validate，全框架通用，无 Agent SDK 依赖）vs 框架增强（--translate-en 依赖本机 Ollama、deploy_report.py 仅做摘要+文本拼装）。

X3（多框架分发与通用 manifest — 1 月）

9. OpenClaw 兼容分支/子目录：fork 一份为 openclaw-edition/（或独立分支），维护 frontmatter/launcher/调度变体，主分支仍 WorkBuddy 原生，两路独立演进。

10. 通用 skill manifest：为 OpenClaw 之外的框架（LangGraph / Dify / Coze）提供最小 manifest.json（name / entry / args / deps / output），让任意框架用同一套 Python 引擎，核心逻辑零改动。

✅ 已落地（2026-08-10）：X3 两项全部完成——

• X3#9 OpenClaw 分支/子目录：openclaw-edition/ 已建，含 OpenClaw 格式 SKILL.md，通过相对路径 ../scripts/ 复用共享引擎（文档注明独立发布时复制 scripts 即可），主分支 WorkBuddy 原生不受影响、两路独立演进。
• X3#10 通用 manifest：仓库根新增 manifest.json，描述跨框架最小接口（name/version/entry/args/deps/runtime/output + optional.ollama_translate/cloud_deploy + subcommands.fetch/validate + compatibility 三向映射），供 LangGraph / Dify / Coze 等直接调用同一套 Python 引擎。

13.3 跨 Agent 兼容校验（可并入 validate_report.py 或独立脚本）

校验项	阈值	现状
scripts/ 无 import workbuddy / 框架 SDK	0 处	✅ 已验证
requirements.txt 仅纯标准第三方	无闭源/云端 SDK	✅
产物为单文件 HTML（无框架运行时依赖）	是	✅
OpenClaw 版 SKILL.md 含 metadata.platform: openclaw	存在	✅（openclaw-edition/SKILL.md 含 metadata.openclaw）
run_report.sh 无硬编码 WorkBuddy 路径	0 处（WorkBuddy venv 仅兜底）	✅（AIWEEKLY_PYTHON + python3 优先）
可选能力在 README 分级标注	核心/增强两类	✅（README 兼容性小节显式分级表）

13.4 跨 Agent 兼容路线图

阶段	周期	兼容性收益
X0	0 成本	验证零耦合 + 文档标注 → 对外"可移植"有凭据
X1	1 周	OpenClaw frontmatter + launcher 抽象 + 调度转换 → 首次能被另一框架加载
X2	2–3 周	deploy 剥离 + 能力分级 → 跨框架干净、不报错
X3	1 月	OpenClaw 分支 + 通用 manifest → 多框架分发，核心零改动

一句话：核心引擎本来就能跑（纯 Python + 标准库 + 单文件 HTML），真正卡在"包装"——改 frontmatter、去掉 WorkBuddy 路径、转译调度概念。 X0 零成本把"可移植"坐实成文档承诺；X1 一周让 OpenClaw 真正能加载；X2/X3 把专属能力剥离、做多框架分发。与第八章内容优化、第三章分发管线（飞书/钉钉推送）互不阻塞——兼容其他 Agent 反而能扩大北极星的"触达面"。

---

附录 · 落地状态速查（2026-08-10 更新，置于文末随章更新）

本表是「已完成 vs 待办」一页通览，便于周更时核对进度。校验器最新分数：22 项校验 → 21 通过 + 1 数据类警告（19/19 + P0#19 源码守护 2 项 + P0#4 check_module_size 1 项；唯一未全绿为 C2#7 关键词 note 周相关率 0/6，源于 insights.json 数据，与本次工程/X 系列改动无关，非致命）。

落地状态更新约定（格式）：某事项落地后，在对应章节的举措列表下方补一个 > ✅ 已落地（日期）：… 引用块，写明做了什么 / 校验结果 / 踩坑（范例见第八、九、十二章）；随后同步更新本表对应行（状态 → ✅ + 落地时间 + 校验分数），并重算底部「累计」。分阶段事项用「✅ 部分」并在落地时间列注明剩余项。

编号	能力 / 优化项	章节	状态	落地时间	校验分数
C0#1	摘要归一（>120 字压 ≤80 字）	八	✅	2026-08-09	0/100
C0#2	重要度评分 + 🔥必读	八	✅	2026-08-09	8 条
C0#3	信源短名映射	八	✅	2026-08-09	RSS 分隔符 0
C1#4	本周主线导语 _auto_lead	八	✅	2026-08-09	头条区 lead 已渲染
C1#5	榜单时效标注（>3 天告警）	八 / 十	✅	2026-08-09	9 天告警已亮
C1#6	看点去注水（日报聚合剔除）	八	✅	2026-08-09	0 条
C2#7	关键词 TF 自动聚类	八	✅	2026-08-10	8/8 note 周相关
C2#8	本周数字看板	八	✅	2026-08-10	6 字段齐全
C2#9	死分类动态隐藏	八	✅	2026-08-10	tip 已隐藏
M0	撤自损免责 + 真实来源署名	九	✅	2026-08-09	「示例/估算」=0
M1	本周市场信号 + 资本↔能力联动	九	✅	2026-08-09	5 张信号卡
M2	中国赛道结构 + 头部集中度图	九	✅	2026-08-10	6 图齐全
M3	YoY / 预测诚实 / AI 占比	九	✅	2026-08-10	三处加厚
跨语言	英文报道中文总结（--translate-en）	九.6	✅	2026-08-10	41/41 覆盖
Fix1	英文卡中文总结全文显示	九.6	✅	2026-08-10	no-clamp 生效
Fix2	市场信号英文链接中文注解	九	✅	2026-08-10	3/3 张带注解
排行榜	多源池 + 区域自适应 + 快照兜底	十	✅ 既有	早期	每榜 ≥5 条
排行榜	选型卡 modal + 资料卡档案	十	✅ 既有	早期	profile 闭环
排行榜	跨源差异 + 性价比象限	十	✅ 既有	早期	cross_diff / scatter
L0#1	模型名归一 aliases	十	✅ 已完成	2026-08-11	model_aliases.json + canon_key/canon_display 取代正则后缀法，跨榜匹配 100%
L0#2	_apply_deltas 时序快照 + WoW	十	✅ 已完成	2026-08-11	snapshots/{date}.json 时序 + delta 字典 {wow,wow_score,new_entry} + spark 历史序列
L0#3	selection_note 受众化	十	✅ 已完成	2026-08-11	selection_notes 开发者/PM/自媒体 三段，模板受众 tab 切换
L0#4	check_leaderboard_quality 校验	十	✅ 已完成	2026-08-11	validate_report.py 加 check_leaderboard_quality（源/快照非空、model 非空、去重、跨榜一致性、受众三段、delta 覆盖）
L0#5	榜源 schema 校验	十	✅ 已完成	2026-08-11	LB_ROW_FIELDS 白名单 + leaderboard_checks.py 拆出，单文件 ≤800 行
L1#6	新上榜 / 大幅上升徽章	十	✅ 已完成	2026-08-11	deltaCell 渲染 🆕 / ↗ +N（≥5 加粗）/ ↘ 警示
L1#7	WoW sparkline 迷你线	十	✅ 已完成	2026-08-11	纯 SVG sparklineSVG（最近 4 快照 rank 趋势）
L1#8	「国内可直连」行内标签	十	✅ 已完成	2026-08-11	模型名后 🇨🇳 行内 badge（tooltip 含 cn_access）
L1#9	多维筛选（机构/许可证/价格）	十	✅ 已完成	2026-08-11	开源/闭源 + 🇨🇳 直连 + 许可证 + 价格区间 + 重置，叠加生效
L1#10	跨源差异加上下文说明	十	✅ 已完成	2026-08-11	cross_diff[].explanation 维度差异锚点，模板 cd-explain 小字
L1#11	模态框键盘导航（←/→/ESC）	十	✅ 已完成	2026-08-11	_lbKeyNav：←/→ 切模型、ESC 关闭，含操作提示
L2	模块化 + 单测 + 并行抓取 + 健康监控	十	⏳ 待办	—	—
L3	自定义权重 + 知识图谱 + 自托管镜像	十	⏳ 待办	—	—
分发 P0	飞书群机器人 Webhook 推送头条卡	三	✅ 已完成	2026-08-12	delivery/feishu_bot.py + scripts/publish.py + 本地 mock 端到端验证通过；webhook 三级回退；未配则跳过不阻断
调度	每周一 09:00 automation（全链路 fetch→generate→publish）	三	✅ 已完成	2026-08-12	recurring automation automation-1786473641685（FREQ=WEEKLY;BYDAY=MO;BYHOUR=9）已建并 ACTIVE
基础设施	刷 cn_leaderboard_snapshot.json 消告警	—	⏳ 待办	距今 9 天	—
工程债 P0#8	收窄 28 处 except Exception	十二	✅	2026-08-10	裸 except 0 / best-effort 39 处带注释
工程债 P0#9	结构化 logging 基建（basicConfig + logger.info）	十二	✅	2026-08-10	≥1（print 保留 console 进度）
工程债 P0#15	_parse_date_arg 扩展接受完整 ISO 8601	十二	✅	2026-08-10	fromisoformat 全支持
工程债 P0#16	[GEN_DATE] 改 ISO 8601 完整格式（含 T+时区）	十二	✅	2026-08-10	astimezone().isoformat()
工程债 P0#17	CLI --date / --data-snapshot ISO 8601 校验	十二	✅	2026-08-10	解析层强校验 + CLI 即时 parser.error（非法 2026-13-99 已验证拦截）
工程债 P0#19	check_iso8601 / check_no_bare_except 校验守护	十二	✅	2026-08-10	21/21 含 2 项守护
工程债 P0#4	check_module_size 校验守护（主≤500 / 子≤800）	十二	✅	2026-08-10	generate_site.py 495 / 最大子模块 620，全绿
工程债 P0#10	重试退避（指数 + 抖动）	十二	✅	2026-08-10	min(2**i,30)+random
工程债 P1#1	拆分 generate_site.py 3250 行 → 11 模块	十二	✅	2026-08-10	主入口 495≤500；子模块最大 620≤800；check_module_size 守护
工程债 P1#3	NewsItem / LeaderboardRow / LeaderboardSlot TypedDict	十二	✅	2026-08-10	types.py 落地，format 返回类型文档化
工程债 P1#12	错误聚合报告（<output>.run.log）	十二	✅	2026-08-10	warnings/errors 计数
工程债 P1#13	CLI --health-check（只探测可达性）	十二	✅	2026-08-10	秒级返回，cn 实测通过
工程债 P1#20	时区统一（datetime.now().astimezone()）	十二	✅	2026-08-10	GEN_DATE 含 +08:00
工程债 P1#21	snapshot_per_source 改 ISO 8601	十二	✅	2026-08-10	per_source 存 ISO 串 + per_source_age
工程债 P1#14	Ollama 健康探测（翻译前 ping /api/tags）	十二	✅	2026-08-10	ollama_health 前置探测，不可用即跳过；--health-check 已接入
工程债 P1#6/7	依赖注入 mock / docstring 四段式	十二	✅	2026-08-10	_http_get/_probe/_detect_region/_retry_fetch/_ollama_translate 支持注入；关键函数四段式 docstring
工程债 P0#2	模块 __all__ 显式声明（11 模块全覆盖）	十二	✅	2026-08-10	导入冒烟全部可用
工程债 P0#18	JSON 日期字段统一 ISO 8601（无半生不熟 datetime）	十二	✅	2026-08-10	全代码无 %Y-%m-%d %H:%M:%S
工程债 P2	其余 P2 远期项	十二	⏳ 待办	—	—
X0#1	引擎层零耦合验证（grep 无 workbuddy SDK）	十三	✅	2026-08-10	scripts 无 import workbuddy
X0#2	依赖白名单固定（requirements 仅 3 库）	十三	✅	早期	feedparser/requests/bs4
X0#3	产物框架无关化确认（单文件 HTML）	十三	✅	早期	不依赖 WorkBuddy
X1#4	OpenClaw frontmatter 双格式	十三	✅	2026-08-10	openclaw-edition/SKILL.md 含 metadata.openclaw（emoji/requires.bins/envVars）
X1#5	run_report.sh 抽象 WorkBuddy 路径	十三	✅	2026-08-10	AIWEEKLY_PYTHON + python3 优先，WorkBuddy venv 兜底
X1#6	调度概念转换（automation→OpenClaw 调度）	十三	✅	2026-08-10	triggers + cron 0 9 * * 6
X2#7	deploy_report.py 剥离 WorkBuddy 通知	十三	✅	2026-08-10	generate_notification(platform=...) 框架无关；旧名保留别名
X2#8	可选能力显式分级（核心/框架增强）	十三	✅	2026-08-10	README 兼容性小节分级表
X3#9	OpenClaw 兼容分支/子目录	十三	✅	2026-08-10	openclaw-edition/ 复用 ../scripts 共享引擎
X3#10	通用 skill manifest（跨框架最小接口）	十三	✅	2026-08-10	仓库根 manifest.json（entry/args/deps/optional）

累计：✅ 完整落地 49 项（C0×3 + C1×3 + C2×3 + M0M3×4 + 跨语言×1 + Fix1/Fix2×2 + 排行榜既有×3 + 跨Agent X0×3 + X1×3 + X2×2 + X3×2 + 工程债 P0×10：#2/#4/#8/#9/#10/#15/#16/#17/#18/#19（#1 拆分、#3 TypedDict 在附录计入 P1#1/P1#3）+ 工程债 P1×8：#1/#3/#6#7/#12/#13/#14/#20/#21 + 分发 P0×1 + 调度×1）；✅ 部分 0 项；⏳ 待办 15 项（L0L1 共 11 + L2×1 + L3×1 + 刷新快照×1 + 工程债 P2×1）；🔄 进行中 0 项。