04-content-monitoring-feishu-radar

Yomiya 内容监控：飞书只读雷达

状态：v1 落地方案与任务记录。 首次建立：2026-05-21，Asia/Shanghai。 默认模式：只读监控，不自动修改 Admin 状态，不自动发布，不自动重试转录。

1. 任务背景

Yomiya 的内容运营已经从单一文章列表，扩展到首页模块、YouTube playlist、playlist video、podcast episode、频道和 news detail 等多个对象。当前日常 IM 是飞书，实际运营讨论也发生在 JPListenning 群里；但后台操作分散在不同页面，导致几个问题反复出现：

• 运营不知道某个节目是否已经转录完成。
• 已转录节目可能已经入库，但用户侧因为 visibility 看不到。
• 首页栏目、playlist 详情页、Admin 详情页之间缺少一张统一对照表。
• 首页有些模块能填满，有些模块节目偏少，但人工排查成本高。
• 运营建议不能只看后台状态，还要围绕用户真正关心的学习任务来判断。

因此 v1 的目标不是继续堆一个后台表格，而是先建立一个可每天运行的“内容雷达”：它读取真实 API，生成本地报告和飞书群摘要，把问题稳定暴露出来。

2. v1 目标

v1 只解决一件事：让首页 YouTube playlist 的用户可见状态、Admin 准备状态和内容厚度每天可被检查。

必须回答：

• 当前首页有哪些 YouTube playlist？
• 用户实际能看到多少节目？
• Admin 中是否有 RECORDED + news_id 但用户不可见的节目？
• 是否有转录失败、排队或转录中积压？
• 哪些 playlist 的详情页内容太薄？
• 哪些内容应该先修可见性，哪些应该继续找候选视频扩容？

v1 不做：

• 不自动 publish-all。
• 不自动修改 news.visibility。
• 不自动重试转录任务。
• 不自动调整首页布局。
• 不把飞书 Base 当成主操作台。

3. 数据源

只读扫描脚本：/Users/cc/Documents/root-remote/scripts/yomiya_content_radar.py

默认 API：

• GET /v2/featured?language=zh-CN
  • 用于确认当前首页模块、section、item type 和 playlist id。
• GET /v1/youtube-playlists?page=1&page_size=100&language=zh-CN
  • 用于确认用户可见 playlist 与 video_count。
• GET /admin/v1/youtube-playlists/:id/videos?page=1&page_size=100&sort=added_desc
  • 用于确认 Admin 侧视频状态、news_id、visibility、转录失败信息。

Admin API 需要环境变量：

export YOMIYA_ADMIN_TOKEN='<admin bearer token without Bearer prefix>'

如果没有 YOMIYA_ADMIN_TOKEN，脚本会降级为 public-only 报告，只判断首页 playlist 数量和用户可见内容厚度，不声明已完成隐藏内容或转录失败校验。

4. 判定规则

红色异常

红色表示需要优先处理：

• 首页入口用户可见节目数为 0。
• status = RECORDED 且存在 news_id，但 visibility 不属于用户可见范围。
• 首页 playlist 存在 TRANSCRIPTION_FAILED。
• public 用户可见数量与 Admin 可见已入库数量不一致。

用户可见范围：

VISIBLE
MEMBERSHIP_VISIBLE
TIME_LIMIT_VISIBLE

黄色提醒

黄色表示运营需要判断或扩容：

• playlist 用户可见节目数少于 5。
• Admin 中存在 QUEUED 或 TRANSCRIBING 积压。
• 有 NEW_ON_YOUTUBE 但当前用户可见节目数仍偏少。
• 某个学习主题在首页出现，但详情页无法支撑连续消费。

绿色稳定

绿色表示当前可以作为稳定内容样板：

• 用户可见节目数大于等于 5。
• 没有隐藏已准备内容。
• 没有转录失败。
• Admin 与 public 结果一致。

5. 运行方式

仅生成本地报告：

python3 /Users/cc/Documents/root-remote/scripts/yomiya_content_radar.py

生成报告并打印飞书预览：

python3 /Users/cc/Documents/root-remote/scripts/yomiya_content_radar.py --print-feishu

预览飞书富文本请求，不发送：

python3 /Users/cc/Documents/root-remote/scripts/yomiya_content_radar.py --message-format markdown --feishu-dry-run

生成报告并发送到 JPListenning：

python3 /Users/cc/Documents/root-remote/scripts/yomiya_content_radar.py --send-feishu

默认会用 --message-format markdown 发送飞书富文本 post。需要回退纯文本时使用：

python3 /Users/cc/Documents/root-remote/scripts/yomiya_content_radar.py --message-format text --send-feishu

--message-format card 只作为后续 interactive card 预留，v1 不发送卡片。

脚本默认输出：

/Users/cc/Documents/root-remote/product/YomiyaContentOperator/reports/YYYY-MM-DD-content-radar.md
/Users/cc/Documents/root-remote/product/YomiyaContentOperator/reports/YYYY-MM-DD-content-radar.json

Markdown 给人看，JSON 给后续自动化、趋势统计或飞书 Base 回填复用。

6. 飞书群报告口径

飞书群优先发 Markdown 富文本，不刷完整长明细。

固定内容：

• 首页 playlist 数量。
• 用户可见节目总数。
• Admin 已入库、已入库未外露、转录失败数量。
• 红色异常数量、黄色提醒数量、绿色稳定数量。
• 今日结论指标表。
• 用户首页栏目总览表：栏目 / 首页卡片 / 代表内容 / playlist 可见节目 / 状态。
• 红色需处理列表与黄色提醒列表。
• 本地 Markdown 和 JSON 报告路径。

飞书报告不是最终操作指令。任何可见性修改、发布、重试转录，都必须由人确认后在 Admin 或对应后台流程中执行。

7. 人工处理流程

已入库但未外露

1. 打开报告中的 Admin playlist URL。
2. 找到 RECORDED + news_id 但不可见的节目。
3. 判断是否适合对用户开放。
4. 人工调整 news.visibility。
5. 重新运行内容雷达，确认 public video_count 已变化。

转录失败

1. 查看失败视频标题、task_id 和错误信息。
2. 判断是源视频问题、字幕问题、provider 问题，还是服务端队列问题。
3. 需要工程处理时，进入 yomiya-service issue，而不是在飞书里散落讨论。
4. 修复或重试后重新运行内容雷达。

内容偏薄

1. 先看 playlist 是否已经有 NEW_ON_YOUTUBE 候选。
2. 如果没有候选，再去找同主题 YouTube playlist 或 channel。
3. 强学习任务优先扩容：
   • 入门基础
   • JLPT 考前
   • 场景会话
   • 跟读和磨耳朵
4. 目标是先补到 5 条以上，再考虑更高的内容密度。

8. 用户需求视角

运营建议不能只围绕“后台有没有内容”，而应该对应用户进入首页时的学习任务。

当前首页可以按这些用户任务观察：

• 入门基础：假名、N5/N4、基础口语。
• JLPT 考前：按等级和考点组织的临考内容。
• 跟读/磨耳朵：低速、重复、适合连续听。
• 场景会话：真实对话、旅行、生活、校园、职场。
• 听歌学日语：歌曲、歌词、发音和文化记忆点。
• 高阶原生：演讲、访谈、真实语速。
• 新闻/童话：一个负责新鲜感，一个负责常青内容。
• podcast 随身听：陪伴型、通勤型、长期留存内容。

如果某个模块在首页占位，但无法支撑用户继续点进去消费，就应该被标为内容偏薄，而不是只看它有没有 1 条内容。

9. 后续扩展

v1.1 可以扩展：

• podcast episode 转录和 news_visibility 监控。
• news/channel 首页模块新鲜度和风险状态监控。
• 飞书 Base 历史归档，用于看趋势而不是替代群报告。
• NEW_ON_YOUTUBE 候选自动聚类，辅助找扩容素材。
• 一周一次的内容结构报告：哪些学习任务内容过剩，哪些内容短缺。

v2 才考虑：

• Admin 中集成内容雷达面板。
• 对可见性修复生成待确认操作单。
• 对转录失败生成重试建议。
• 对首页模块生成候选编排草案。

10. 首次验收口径

首次 dry-run 需要复现当前基线：

• 首页 YouTube playlist 约 15 个。
• 用户可见节目约 94 条。
• 有 Admin token 时，Admin 已入库节目约 94 条。
• 有 Admin token 时，已入库但未外露节目为 0。
• #10、#17、#27 等节目偏少的 playlist 应被标为黄色提醒。

如果没有 Admin token，报告必须明确写出 Admin 校验未执行，不能假装完成 94/94/0 的完整校验。