-
Notifications
You must be signed in to change notification settings - Fork 0
AI Weekly Optimization Plan v2
评估日期：2026-09-04 数据来源：SkillHub 官方评测报告（5 维度 4.52/5）+ 用户自述痛点 目标：把"能用"变"好用"，让下载转化、留存、口碑形成正循环
| 维度 | 均分 | 子项 |
|---|---|---|
| Adaptability（适配性） | 4.4 | boundary 4.5 / trigger 4.3 |
| Convention（规范性） | 4.7 | antiPatternFaq 4.5 / docQuality 4.8 / progressive 4.8 / structure 4.8 |
| Effectiveness（有效性） | 4.5 | accuracy 4.3 / completeness 4.8 / creativity 4.8 / usability 4.3 |
| Reliability（可靠性） | 4.5 | errorHandling 4.3 / func 4.8 / stability 4.5 |
| Trust（可信度） | 4.7 | domestic 4.3 / scan 5.0 |
| 综合 | 4.52/5 | 整体评价：架构精良，定位清晰，真正面向生产 |
用户原话：
"这个 Skill 质量很好，核心亮点是生成可搜索、可筛选、带图表的单文件新闻网站，新闻来源权威可靠，且完全免费无需注册账号。不足之处在于首次配置有一定技术门槛……适合有一定动手能力的用户使用。"
| # | 来源 | 问题 | 严重度 |
|---|---|---|---|
| P0-1 | 用户 | "让部署到飞书不用折腾 GitHub"——飞书卡片链接需要网页托管，目前只走 GitHub Pages，需要手动配 PAT、push gh-pages、切换 Pages 源 | 🔴 高 |
| P0-2 | 评测-accuracy |
model_profiles.json 含有 GPT-5.6 Sol、Claude Opus 5 等无真实来源锚点的未发布模型，违反"不要凭训练数据脑补数字"硬规则 |
🔴 高 |
| P0-3 | 用户 | "解决国内网抓取不了部分海外信息源问题"——LMArena / HuggingFace / Artificial Analysis 国内直连不稳定，排行榜实时数据经常回退到旧快照 | 🔴 高 |
| P1-1 | 评测-trigger | 触发词仅在 metadata 中列出，缺乏对话级使用示例——用户不知道该说什么话才能"一句话生成周报" | 🟡 中 |
| P1-2 | 评测-antiPatternFaq | FAQ 分散在多处（README / SKILL.md / changelog），缺少独立 FAQ 文档，用户遇到问题需跨文件搜索 | 🟡 中 |
| P1-3 | 评测-usability | 趋势线空白（需累积 2 周数据）、feishu_config.json 被 gitignore 需手动创建、GitHub Pages 部署三步（PAT / push / Pages 源切换） |
🟡 中 |
| P1-4 | 评测-errorHandling | 部分错误提示过于专业（如 ble001 noqa、GIT_CONFIG_*），普通用户难以理解如何解决 |
🟡 中 |
| P2-1 | 评测-boundary | 部分限制分散在各处，缺少集中声明（新闻条数上限、HTML 体积、排行榜模型数上限等） | 🟢 低 |
以下项目已在现有优化方案中记录并落地，本方案不再重复，但需关注其评测后暴露的遗留问题：
| 已落地项 | 关联问题 | 当前状态 |
|---|---|---|
飞书 Webhook 推送（delivery/feishu_bot.py） |
P0-1 | ✅ 已落地，网页托管支持多后端（github-pages/tencent-cos/vercel/netlify/cloudflare-pages/local），已去 GitHub 强依赖（commit c5d65d3） |
| 每周周一 09:00 automation | P0-1 | ✅ 已落地（automation-1786473641685） |
| 国内/国外双源 RSS 抓取 | P0-3 | ✅ 已落地，国外源失败时回退快照 |
| 单文件 HTML 交付 | — | ✅ 已落地 |
| 对抗式审查 C1/R1-R6/S1/S2/N2 | — | ✅ 已闭环，verify 31/31 / test 21 / validate 24/24 |
| 排行榜多源池 + 快照兜底 | P0-3 | ✅ 已落地，新增国内镜像 URL_REWRITES（hf-mirror 等）+ _http_get_fallback 自动回退（commit c5d65d3） |
| SKILL.md「快速开始」对话示例区（5 个真实示例） | P1-1 | ✅ 已落地（commit 94921b5） |
独立 references/FAQ.md（九节 + 排错速查表） |
P1-2 | ✅ 已落地（commit 94921b5） |
交互式 scripts/init_feishu_config.py（webhook/connector 双模式 + 校验） |
P1-3 | ✅ 已落地（commit 94921b5） |
ERR-* 错误码体系 + UserFacingError（含解决步骤） |
P1-4 | ✅ 已落地（commit 1c0cebc） |
scripts/aiweekly/const.py 硬约束常量集中声明 |
P2-1 | ✅ 已落地（commit 1c0cebc） |
scripts/validate_checks/constraints.py 事后审计 |
P2-1 | ✅ 已落地（commit 1c0cebc） |
| SKILL.md「硬约束」小节 + README「已知限制」补充 | P2-2 | ✅ 已落地（commit 1c0cebc） |
| manifest.json 版本 3.4.0 + features 字段 | P2-3 | ✅ 已落地（commit 1c0cebc） |
现状：飞书卡片里的「查看完整周报」链接指向 GitHub Pages URL，需要：① 创建 Classic PAT；② git push origin gh-pages；③ 在 GitHub 设置里切换 Pages 源。对非 GitHub 深度用户是一道坎。
方案：
-
新增
--deploy-to参数：支持github-pages/tencent-cos/vercel/netlify/cloudflare-pages等多种托管方式，每种方式对应一套部署脚本 - 默认提供 GitHub Pages 兜底：不传参时沿用现有行为，零破坏
- 腾讯云 COS 作为国内首选：一键部署到 COS 静态网站，国内直连速度远快于 GitHub Pages，且无需翻墙管理后台
-
Vercel / Netlify 作为中间选项：
vercel --prod一条命令即可部署，国内访问稳定 -
部署脚本收拢：
scripts/deploy.py统一入口，根据--deploy-to选对应实现
验证方式：
- 测试三种托管方式各部署一次，确认链接可达
-
validate_report.py加check_deploy_config：未配置部署方式时给出明确引导而非静默失败
状态：✅ 已落地（commit c5d65d3，2026-09-04） —— scripts/deploy.py 统一入口 +
publish.py --deploy-to + run_report.sh deploy 改调 deploy.py；非 github-pages 后端无需配置 GitHub，
飞书卡片 view_url 与部署后端解耦。附 delivery/deploy_config.example.json 配置示例。
现状：model_profiles.json 含 GPT-5.6 Sol、Claude Opus 5、Claude Fable 5 等条目，具有未来时间戳且无真实来源。评测明确指出这与 SKILL.md 中"不要凭训练数据脑补数字"的硬规则矛盾。
方案：
-
扫描 + 清理：用 Python 脚本扫描
model_profiles.json，找出published_date在未来或无来源字段（source_url为空）的条目，标记为"待验证" -
双轨制处理：
- 已验证模型：保留，补充真实来源链接
- 未验证/未来模型：移入
model_profiles_pending.json，并在报告中显示"🧪 实验模型（未经验证）"标识，不纳入排行榜排名计算
-
校验守护：
validate_report.py加check_model_profiles_accuracy——扫描model_profiles.json的source_url字段，对无来源的未来模型给出警告 - 维护机制：每次更新模型资料卡时，要求必须附带来源链接，否则不入库
验证方式：
- 清理后重跑周报，确认排行榜不含未验证模型
-
validate_report.py新增校验通过
状态：✅ 已落地（commit c5d65d3） —— scripts/validate_models.py（--fix/--check）将 15 条
无来源推测条目（source=榜单自动抓取·未联网核实）移入 model_profiles_unverified.json，主表 72→57 条全部
verified=true（Claude Opus 5 / GPT-5.6 Sol 等已联网核实为真实模型，保留）；model_meta._apply_profile_as_truth
加 P0-2 守护跳过 verified=false；validate_report.py 新增 check_model_profiles_accuracy（校验 24/24 → 25/25 全过）。
现状：LMArena、HuggingFace、Artificial Analysis 国内直连不稳定，排行榜实时数据经常回退到旧快照，用户看到的"实时榜"可能是几周前的数据。
方案：
-
国内镜像源：在
leaderboard_sources.py新增国内镜像列表：- LMArena →
lmarena.org.cn（如有）或mirror.lmarena.xyz - HuggingFace →
hf-mirror.com - Artificial Analysis →
aa-cn.mirror.xyz - OpenCompass 司南 → 主源（已在国内，无需镜像）
- LMArena →
-
自动探测 + 切换：
_detect_region()增强，不仅探测能否访问国外源，还预置镜像列表，国外源失败时自动尝试镜像，镜像也失败再回退快照 -
--proxy开关明确化：现有--proxy参数增加帮助信息，说明"国内用户访问国外排行榜时建议开启" -
排行榜快照周更机制：每周生成周报时，后台异步刷新排行榜快照（缓存到
leaderboard_cache.json），下次生成时无需等待抓取
验证方式：
- 在国内网络环境下测试各镜像可达性
- 排行榜部分实时 + 部分镜像 + 部分快照，验证降级逻辑正确
状态：✅ 已落地（commit c5d65d3） —— leaderboard_sources.py 新增 URL_REWRITES
（HF/LMArena/AA 主源 → hf-mirror.com 等国内镜像）+ _http_get_fallback 主源失败自动回退镜像，
全失败抛异常让 fetch_* 走快照兜底；HF_MIRROR/AA_MIRROR/LM_MIRROR 环境变量可覆盖。
新增 scripts/leaderboard_diagnose.py 诊断工具（逐源探测可达性 + 镜像回退命中统计）。
现状：SKILL.md 列了触发词（AI周报、weekly AI report 等），但缺少真实对话示例，新用户不知道该怎么说才能让 Skill 自动激活。
方案：
-
在 SKILL.md 最前面新增「快速开始」章节，放 3–5 个真实对话示例：
用户：帮我生成一份本周 AI 行业新闻周报 → Skill 自动激活，执行全链路（抓取→生成→可选推送） 用户：这周的 AI 新闻怎么样？我要看简报 → Skill 激活，生成轻量 Markdown 版 用户：帮我把上周的周报推送到飞书 → Skill 激活，读取 report.json，调飞书 Webhook - 在飞书卡片底部加「复用到下次」提示：卡片末尾加一行小字「下周想看同样的周报？直接说「AI周报」即可」
- FAQ 文档（见 P1-2）中第一个问题就是「怎么用这个 Skill？」，用对话形式回答
验证方式：
- 找 3 位不熟悉该 Skill 的同事，让他们只看示例就能说出怎么使用
- 统计 SkillHub 页面「如何使用」区打开率
现状：FAQ 分散在 README「排错」章节、SKILL.md 各节、CHANGELOG 中，用户遇到问题需跨文件搜索。
方案：
-
新建
references/FAQ.md，按使用流程分类：- 安装与配置：venv 怎么建、依赖怎么装、GitHub PAT 怎么生成
- 首次使用：第一次跑命令要做什么、飞书配置怎么写、WebSearch 数据在哪找
- 常见问题：排行榜是旧的怎么办、市场数据是估算的怎么回事、英文报道怎么看中文
- 飞书推送：Webhook 在哪获取、feishu_config.json 怎么写、bot 身份怎么选
- GitHub Pages：Pages 怎么开、PAT 权限怎么设、域名怎么绑
-
网络问题：国外源连不上怎么办、国内镜像怎么用、
--proxy怎么用 - 模型数据：某些模型是假的吗、排行榜怎么选的、snapshot 什么意思
- README 首页加 FAQ 入口：在快速开始下方加「遇到问题？看 FAQ →」链接
- SkillHub 页面同步：把 FAQ 精华部分同步到 SkillHub 页面的描述区
验证方式：
- 找 3 位新用户，让他们在不看主文档的情况下，仅通过 FAQ 解决 5 个预设问题
- FAQ 页面在 SkillHub 和 GitHub 两端的打开率统计
现状：feishu_config.json 被 gitignore，首次安装需手动创建，用户不知道要填什么。
方案：
-
新增
scripts/init_feishu_config.py：交互式创建feishu_config.json，根据用户选择的推送方式（Webhook / bot connector）自动生成对应模板 - Webhook 方式：提供飞书群设置→机器人→自定义机器人的完整路径指引 + 示例 JSON
- bot 方式：提供飞书开放平台→自建应用→机器人的完整路径指引 + 示例 JSON
-
验证配置：
init_feishu_config.py最后跑一次python -m aiweekly.feishu_connector --test验证连通性
验证方式：
- 找一位未配置过的用户，让他用新脚本完成飞书配置，记录耗时和卡点
现状：部分错误提示包含技术术语（ble001 noqa、GIT_CONFIG_*），普通用户难以理解。
方案：
-
错误码体系：每个可预见的错误定义一个简短代码（如
ERR-GH-PAT-001），对应一段用户友好的解释文字 -
三级错误输出：
- 用户可见：人话描述问题 + 解决步骤
-
开发者可见：错误码 + 原始异常（通过
--verbose开启） -
日志可见：完整堆栈（写入
.run.log）
-
示例：
❌ [ERR-GH-PAT-001] GitHub Pages 部署失败：PAT 缺少 pages:write 权限 解决方法： 1. 去 https://github.com/settings/tokens 重新生成 PAT 2. 勾选以下权限：repo + pages:write 3. 将新 PAT 填入 scripts/deploy_ghpages.py 第 12 行
验证方式：
- 找 3 位非开发背景用户，让他们阅读错误提示后知道怎么解决
现状：部分限制（新闻条数上限、HTML 体积、排行榜模型数上限）分散在各处。
方案：
-
在 SKILL.md 第二节「核心设计理念」末尾新增「硬约束」小节，集中列出所有限制：
- 新闻条数：单次抓取上限 100 条，超过截取前 100
- HTML 体积：建议 ≤5MB，超过会自动压缩 Chart.js 数据
- 排行榜模型数：每榜上限 50 条，超过截取 top 50
- 趋势线：需至少 2 周数据（快照）才能渲染，第 1 周趋势线为空
- README 快速开始页加「已知限制」提示：用浅灰色框展示，避免用户误判为 Bug
验证方式：
-
validate_report.py加check_constraints：检查 HTML 大小、新闻数量、排行榜行数是否符合约束
现状：SkillHub 页面只有功能描述，没有使用示例、FAQ、对比评测。
方案：
- 新增「使用示例」区块：放 3–5 个真实对话示例（同 P1-1）
- 新增「为什么选我」对比表：与其他 AI 周报工具对比（是否免费 / 是否需要 API Key / 是否支持飞书 / 是否含排行榜）
- 新增「最近更新」区块：自动从 CHANGELOG 同步最近 3 条更新
- 新增「反馈渠道」：链接到 issue tracker + 建议反馈问卷
验证方式：
- SkillHub 页面打开率、下载转化率、收藏率对比优化前后
| 阶段 | 周期 | 内容 | 北极星收益 |
|---|---|---|---|
| Sprint 1 | 1 周 | P0-1 飞书部署去 GitHub 化（新增腾讯云 COS / Vercel 部署方式） | 降低首次使用门槛，提升转化率 |
| Sprint 2 | 1 周 | P0-2 修复 model_profiles.json 准确性 + P0-3 国内镜像源 + 自动探测 | 提升准确性评分（4.3→4.5+），减少用户困惑 |
| Sprint 3 | 2 周 | P1-1 对话示例 + P1-2 独立 FAQ + P1-3 飞书配置简化 | 提升 trigger 评分（4.3→4.5+），降低新用户学习成本 |
| Sprint 4 | 持续 | P2-1 错误提示人性化 + P2-2 边界集中声明 + P2-3 SkillHub 页面优化 | 提升 errorHandling 评分（4.3→4.5+），口碑传播 |
| 指标 | 当前值 | 目标值 | 衡量方式 |
|---|---|---|---|
| SkillHub 下载转化率 | 84 下载 / 0 安装 | ≥ 10 安装 | SkillHub 后台统计 |
| 首次使用成功率 | 未知 | ≥ 80% | 用户反馈 + 错误日志分析 |
| FAQ 解决率 | 未知 | ≥ 70% | FAQ 页面停留时间 + 跳出率 |
| 飞书推送成功率 | 未知 | ≥ 95% | 推送日志 + 用户确认 |
| 排行榜实时率 | 低（频繁回退快照） | ≥ 60% |
leaderboard_health.jsonl 统计 |
| model_profiles 准确率 | 存疑（含未发布模型） | 100% 有来源 |
check_model_profiles_accuracy 守护 |
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| 腾讯云 COS 部署需要用户开通云资源 | P0-1 部分用户无法使用 | GitHub Pages 仍为默认，COS 作为可选增强 |
| 海外镜像源不稳定或失效 | P0-3 部分用户仍需用代理 | 自动探测 + 回退快照，镜像仅为加速手段 |
| model_profiles 修复可能影响现有排行榜 | P0-2 短期数据波动 | 双轨制（已验证 / 待验证），排行榜仅用已验证模型 |
| FAQ 文档维护成本高 | P1-2 文档过时 | 自动化同步：FAQ 从 CHANGELOG + README 自动提取，人工审核后入库 |
本次评测的核心结论：
"架构精良、定位清晰、真正面向生产。主要不足是部分模块文件体量较大、GitHub Pages 部署流程对新手仍有复杂度、排行榜数据存在准确性隐患。"
本次优化方案的优先级逻辑：
- P0 级（阻断性问题）：飞书部署去 GitHub 化、模型数据准确性、国内网络访问——这些问题直接影响核心体验，必须优先解决
- P1 级（体验级问题）：对话示例、独立 FAQ、配置简化——这些问题影响新用户转化和口碑传播
- P2 级（完善级问题）：错误提示、边界声明、页面优化——持续迭代，逐步提升
一句话：当前 Skill 已经"能用"，接下来要让它"好用"——让新手 5 分钟内跑通全流程，让老手随时能找到需要的信息。