01-yomiya-content-curator-design

Yomiya Content Curator Design

状态：设计沉淀。当前不改 iOS 或服务端业务代码。

目标：把「每日日语 / Yomiya」内容运营从人工凭经验管理，升级为 AI 辅助内容运营参谋流程。第一阶段默认只读，生成报告和后台手动操作清单；后续再逐步沉淀到 Admin 草案、半自动采纳和自动化闭环。

1. 背景

当前 iOS 首页不是单纯内容流，而是「栏目货架 + 内容列表 + 集合入口」。

已确认的用户侧展示形态包括：

顶部 tab：推荐 / 播客
底部 tab：推荐 / 导入 / 我的
首页栏目：日语初学入门、NHK 时事新闻、日语磨耳朵、日本民间故事、日语播客随身听、福娘经典童话、日语场景练习、最新内容、日本娱乐文化、深度阅读
展示对象：频道、playlist / collection、播客节目、具体文章 / 视频 / 音频内容

当前服务端已有较完整的内容采集和处理链路：

Web crawler：NHK、Hukumusume、YahooNewsEntertainment、Watanoc、Yomujp
YouTube channel crawler：internal/crawler/youtube_channel/youtube_channel_crawler.go
Podcast crawler：internal/crawler/podcast_show/podcast_show_crawler.go
内容处理链路：RawLifecycle -> ProfileResolver -> RuntimeResolver -> LanguageAnalysis -> DraftBuilder -> Classification -> AssetProcessing -> Persist -> AfterPersist
后台页面：内容管理、频道管理、YouTube 频道、Podcast show、过滤词、Prompt 管理
首页 API：/v1/featured

关键限制是：/v1/featured 当前主要基于配置里的 featured channels 拉取内容，还不是一个面向 App 完整生效的持久化首页编排系统。它返回的结构是 channels[]，每个 item 包含 channel 和 news。

同时，生产 Admin 已经出现新的 FeaturedHomeLayout 页面。该页面读写 /admin/v1/featured-home-layout，支持 collection_rail、vertical_content_list、channel、youtube_playlist、youtube_playlist_items、podcast_show 等布局/来源字段。但当前 iOS TestFlight 0.6.3 (97) 仍只读取 /v1/featured 的 channels[]，不消费 Admin 首页布局字段。具体排查见 03-featured-home-layout-diagnosis.md。

2. 已有能力

2.1 内容处理链路

服务端当前内容处理架构位于：

/Users/cc/Documents/yomiya-service/docs/architecture/content-processing-current.md

已支持：

collected + article
collected + video
collected + audio
user_imported + video
user_imported + audio

当前不支持：

user_imported + article

处理链路中，Classification 顺序是：

RiskReviewStep
DifficultyStep
AddSceneStep

AfterPersist 承担：

translation
translation-complete notification
audio / alignment follow-up
word-definition follow-up
processing-complete notification

这意味着运营参谋不应该重新发明风险、难度、场景、翻译判断，而应该读取和复用这些产物。

2.2 首页当前能力

internal/application/featured.go 当前逻辑：

读取配置中的 FeaturedChannelConfig
查询可见内容：
- VISIBLE
- MEMBERSHIP_VISIBLE
- TIME_LIMIT_VISIBLE
按频道返回 dto.FeaturedResponse
不持久化首页版本
不表达栏目内混排、专题版本、人工采纳记录或 A/B 编排

生产 Admin FeaturedHomeLayout 当前可表达的布局字段：

字段	已观察值	说明
`display_type`	`collection_rail`	集合横栏，适合展示 channel / YouTube playlist 卡片
`display_type`	`vertical_content_list`	内容竖栏，适合展示频道、播客节目、playlist 最新视频等内容列表
`source.type`	`channel`	频道来源
`source.type`	`youtube_playlist`	YouTube 播放列表，偏合集卡片
`source.type`	`youtube_playlist_items`	YouTube 播放列表最新视频，偏内容列表
`source.type`	`podcast_show`	播客节目
`source.limit`	正整数或 null	竖栏内容数量控制；`vertical_content_list` 下非 `youtube_playlist` 来源需要正整数

但第一阶段仍只能生成「首页栏目草案」和「后台操作清单」，不能假设 App 端已经能消费 Admin 的完整布局模型。每条首页建议都必须标注：

ideal_layout：运营理想布局。
current_app_effect：当前 iOS 0.6.3 (97) 是否能在 /v1/featured 生效。
blocked_by：如果不能生效，是 API 未返回、客户端不支持，还是内容未入库/不可见。

2.3 VIP 规则

VIP 规则已经沉淀在 news.visibility。

真实枚举：

INVISIBLE
VISIBLE
MEMBERSHIP_VISIBLE
TIME_LIMIT_VISIBLE
ARCHIVED

现有语义：

VISIBLE：普通可见
MEMBERSHIP_VISIBLE：会员可见，App 显示 VIP，并对非会员限制正文
TIME_LIMIT_VISIBLE：限时可见
INVISIBLE：不可见
ARCHIVED：归档

后端会把 MEMBERSHIP_VISIBLE 转成 premium tag。iOS 的 News.isMembershipRequired / NewsDetail.isMembershipRequired 基于 visibility == .membershipVisible 判断。

运营参谋的 VIP 建议必须输出为真实字段，例如：

建议字段：news.visibility = MEMBERSHIP_VISIBLE
理由：系列完整、时长适中、学习价值高，适合做会员内容
风险依据：raw_news.risk_check_status = LOW
后台动作：内容管理 -> 批量编辑 -> 状态改为会员可见

2.4 风险规则

现有风险链路：

先查 filter_words 中 status = ACTIVE 的过滤词。
命中过滤词时直接 blocked。
再调用 DeepSeek content_filter prompt。
DeepSeek 返回 High / Medium / Low。
High 和 Medium 会阻断。
风险检查失败时当前默认当作 Low 继续处理。

落库字段：

raw_news.status
- QUEUED
- PROCESSING
- DONE
- REJECTED
- FAILED
raw_news.risk_check_status
- HIGH
- MEDIUM
- LOW
- BLOCKED

注意：系统采集内容会做风险和难度检查；用户导入媒体目前跳过风险和难度。运营报告必须标出这个差异。

3. 核心缺口

当前已经有「采集、转写、处理、翻译、风险、难度、场景标签」，但缺少运营层能力：

资源级管理
- 缺少统一的 resource model，把 YouTube playlist / channel / podcast / web source 统一成可运营资产。
- 当前可用的近似表包括 channels、youtube_channels、podcast_shows、podcast_episodes、raw_news、news、transcription_tasks。
AI 编排层
- 缺少把大量内容转成首页栏目、列表页、专题页、翻译优先级、VIP 建议的运营决策层。
- 当前 /v1/featured 只按配置频道取内容，不保存 AI 草案或运营版本。
审核发布层
- 运营无法在 Admin 里看到 AI 草案、采纳原因、字段变化和复核状态。
- 第一阶段应保留人工审核和手动操作。
数据回流层
- 缺少曝光、点击、播放、完播、收藏、转化、翻译成本、转写成本对下一轮编排的反馈。
- 第一阶段可以先预留输入字段，不强行做自动优化。

4. 第一阶段方案：`yomiya-content-curator`

yomiya-content-curator 是一个本地/运营 AI Skill，默认只读。

它不是发布机器人，而是运营参谋：

读取真实后台数据。
读取已有规则基线。
给内容打运营分。
生成首页栏目草案。
输出后台操作清单。
操作后复核后台/API 状态。

4.1 能力边界

第一阶段允许：

读取数据库或只读 API。
汇总内容库存。
识别可上首页、可做会员、应归档、应补翻译、应补转写、应进入专题的内容。
生成 Markdown / CSV / JSON 报告。
给出后台手动操作步骤。
手动操作后重新读取 /v1/featured、内容详情 API 或 Admin 数据进行复核。

第一阶段禁止：

自动修改 news.visibility。
自动归档内容。
自动创建首页版本并发布。
自动改频道、playlist、pod客 show 配置。
自动绕过 filter_words、风险检查或人工审核。
把 risk_check_status = HIGH / MEDIUM / BLOCKED 内容推荐上首页。
对用户导入媒体做未声明的风险判断结论。

4.2 读取数据源

基础内容源：

数据源	关键字段	用途
`channels`	`id`, `name`, `display_name`, `description`, `img_url`, `is_visible`	栏目/频道货架基础
`youtube_channels`	`youtube_channel_id`, `name`, `auto_crawl_enabled`, `channel_id`	YouTube 来源资产
`podcast_shows`	`itunes_id`, `feed_url`, `name`, `artist_name`, `language`, `genre`, `auto_crawl_enabled`, `last_crawled_at`, `consecutive_crawl_failures`, `last_crawl_error`, `channel_id`	播客节目资产
`podcast_episodes`	`podcast_show_id`, `title`, `audio_url`, `duration_seconds`, `published_at`, `unique_id`, `transcription_task_id`	播客剧集候选
`raw_news`	`unique_id`, `status`, `risk_check_status`, `channel`, `data`	原始处理状态与风险状态
`news`	`id`, `news_id`, `title`, `date`, `level`, `channel_id`, `source`, `type`, `visibility`, `image_url`, `movie_url`, `is_resource_migrated`	已处理内容和可见性
`news_scenes`	`news_id`, `scene_id`, `scene_primary`	场景标签
`news_sentence_translations`	`sentence_id`, `language`, `text`	翻译完整度
`transcription_tasks`	`unique_id`, `url`, `channel_id`, `content_type`, `estimated_duration_seconds`, `status`, `news_id`, `transcript_type`, `error_code`, `error_message`	转写状态与成本
`filter_words`	`word`, `status`	风险规则基线

第一阶段不要求一次性读取用户行为数据，因为当前方案尚未确认行为埋点表。文档和报告中应把行为反馈标成「待补数据源」，而不是虚构已存在字段。

4.3 运营评分模型

运营分不是替代业务规则，而是把多个现有状态转换成排序建议。

建议输出 6 个分项：

分项	输入	说明
学习价值	`news.level`, `news_scenes`, 内容标题、频道	是否适合学习、是否有明确场景
质量	封面、标题、正文/音频/视频完整度、`is_resource_migrated`	是否适合展示
时效性	`news.date`, `published_at`, crawler 时间	新闻类内容权重更高，故事类内容可长期有效
完整度	翻译覆盖、转写完成、音频对齐、图片资源	是否可以无缺口地消费
风险	`raw_news.risk_check_status`, `raw_news.status`, `filter_words`	硬门槛，不能用高运营分覆盖
成本	`estimated_duration_seconds`, 缺翻译数量、缺转写状态	补齐成本和收益是否匹配

推荐计算方式：

operating_score = learning_value + quality + freshness + completeness - risk_penalty - cost_penalty

但第一阶段报告必须保留分项，不能只给一个总分。运营人员需要知道「为什么推荐」。

4.4 首页栏目草案

首页草案按用户实际看到的栏目输出，而不是按数据库表机械输出。

建议栏目策略：

首页栏目	主要候选	编排逻辑
日语初学入门	初学 collection / YouTube 入门系列 / N5-N4 内容	低难度、高完整度、封面清晰
NHK 时事新闻	NHK channel 下 `type=webpage/video` 内容	时效优先，风险必须 LOW，标题可读
日语磨耳朵	音频/视频、短时长、转写完成	听力消费优先，需 duration 和转写状态
日本民间故事	Hukumusume / 福娘 / 故事频道	系列连续、长期有效、适合 playlist
日语播客随身听	`podcast_shows` / `podcast_episodes`	show 维度货架 + episode 列表
福娘经典童话	福娘来源内容	系列稳定、适合专题
日语场景练习	`news_scenes` 主场景明确的内容	按场景聚合
最新内容	`news.date` / `published_at` 最近内容	内容状态健康时展示
日本娱乐文化	YahooNewsEntertainment 等来源	时效、风险、版权展示风险需严格
深度阅读	长文、N3+、翻译完整	适合进阶和会员转化

每个栏目报告必须包含：

栏目名
建议 display_type
候选内容列表
推荐排序
建议展示数量
每条内容的真实 ID
字段依据
用户价值
后台动作
风险和待补项
当前 App 生效状态

4.5 横竖交叉编排

首页编排不应只堆竖向列表，也不应只堆横向合集。yomiya-content-curator 需要生成横竖交叉的首页草案，让用户在感官上看到更丰富的内容结构。

建议基础节奏：

顶部频道入口
第 1 段：collection_rail
第 2 段：vertical_content_list
第 3 段：collection_rail
第 4 段：vertical_content_list
第 5 段：vertical_content_list 或 collection_rail，视库存质量决定

编排规则：

collection_rail 用于专题感、系列感、入口感，例如播客节目、YouTube playlist、民间故事合集、学唱日语歌。
vertical_content_list 用于连续消费，例如 NHK 新闻、最新内容、日语磨耳朵、场景练习。
相邻两个 section 尽量不要使用同一种 display_type，除非库存不足。
相邻两个 section 尽量不要使用同一内容来源或同一学习目标，避免首页视觉和内容都重复。
首页前 3 个 section 需要覆盖不同动机：轻松开始、时事/新鲜、系列/专题。
高风险、翻译缺失严重、转写未完成的内容不能因为视觉节奏需要而被强行放入。

4.6 竖型栏目数量控制

竖型栏目必须可以控制展示数量。目的不是把所有内容都塞进首页，而是控制首页密度和节奏。

建议字段：

section.display_type = vertical_content_list
section.visible_item_count = 3
section.source.limit = 3
section.max_item_count = 5

第一阶段报告中统一输出：

字段	含义
`display_type`	`vertical_content_list`
`visible_item_count`	建议首屏/当前首页直接展示几条
`source.limit`	建议后台来源拉取数量
`item_limit_reason`	为什么是 2/3/5 条

建议默认：

新闻/最新内容：visible_item_count = 3，避免时效内容压住首页。
故事/童话/深度阅读：visible_item_count = 2-3，降低长内容压迫感。
磨耳朵/短音频：visible_item_count = 4-5，因为单条消费成本低。
播客 episode：visible_item_count = 2-3，避免长音频显得过重。
歌曲/流行文化实验栏目：第一版 visible_item_count = 2，先观察点击和完播。

示例输出：

栏目：学唱日语歌
建议 display_type：collection_rail
下一段承接：vertical_content_list
竖栏 visible_item_count：2
source.type：youtube_playlist_items
source.limit：2
理由：歌曲栏目适合先以横向 playlist 建立专题感，再用 2 条竖向内容测试点击；不宜一次展示过多，避免首页显得娱乐化过重。
当前 App 生效状态：SKIP，iOS 0.6.3 (97) 不支持 youtube_playlist section。

4.7 输出报告

第一阶段输出 5 类报告。

A. 内容库存报告

回答：

当前各频道有多少可见内容。
有多少内容卡在 INVISIBLE。
有多少内容风险不通过。
有多少内容缺翻译、缺转写、缺封面。
哪些资源最近抓取失败。

B. 首页编排草案

回答：

每个首页栏目建议放什么。
每个栏目是 collection_rail 还是 vertical_content_list。
横竖交叉顺序是什么。
竖型栏目展示几条内容，后台来源 limit 建议是多少。
排序理由是什么。
哪些内容现在已经可见。
哪些内容要先改 visibility、补翻译或补转写。
哪些栏目当前能在 iOS 0.6.3 (97) 生效，哪些需要新的 App 首页布局协议。

C. VIP 建议报告

回答：

哪些内容适合 MEMBERSHIP_VISIBLE。
哪些内容应保持 VISIBLE 用于拉新。
哪些内容应限时可见。
哪些内容不应设 VIP，因为内容不完整、风险不稳或价值不足。

D. 后台操作清单

必须映射到真实后台动作，例如：

内容：news.id = 9f1...
建议字段：news.visibility = MEMBERSHIP_VISIBLE
理由：日本民间故事系列连续，视频时长 6:05，适合会员深度内容
风险：raw_news.risk_check_status = LOW
待补：无
后台动作：内容管理 -> 搜索标题 -> 批量编辑 -> 状态改为会员可见
复核：调用 /v1/featured，确认该内容带 premium tag 且非会员显示 VIP

E. 操作后复核报告

回答：

后台字段是否真的变了。
/v1/featured 是否出现预期内容。
iOS 对应位置是否会显示 VIP / 栏目 / 列表入口。
仍未生效的原因：配置未覆盖、频道不可见、内容不可见、缓存、接口未返回、客户端未支持布局类型。

5. 规则复用

5.1 VIP

只使用 news.visibility 作为建议目标，不创建新 VIP 规则。

允许建议：

news.visibility = VISIBLE
news.visibility = MEMBERSHIP_VISIBLE
news.visibility = TIME_LIMIT_VISIBLE
news.visibility = INVISIBLE
news.visibility = ARCHIVED

不允许建议：

直接改 iOS 本地 VIP 标记。
绕过服务端可见性判断。
对风险未通过内容建议会员可见。

5.2 风险

风险是硬门槛。

建议规则：

raw_news.risk_check_status = LOW：可以进入普通运营候选。
raw_news.risk_check_status = HIGH / MEDIUM / BLOCKED：不得推荐上首页；只能进入风险复核/归档建议。
raw_news.risk_check_status IS NULL：标为「风险状态未知」，不能进入自动推荐，只能建议补跑或人工复核。
raw_news.status = REJECTED：不得推荐。
用户导入媒体：标注「当前处理链路跳过风险/难度」，不能把它描述成已通过系统风险检查。

5.3 翻译

翻译完整度读取 news_sentence_translations 与句子数对比。

建议：

缺目标语言翻译的内容，不进入多语言重点推荐。
日语学习核心内容可优先补中文翻译。
新闻时效类内容若过期，不一定值得补齐所有语言。

5.4 难度

难度读取 news.level。

建议：

初学栏目优先 N5 / N4。
深度阅读可接受 N3+。
难度未知时标为「待补难度」，不能混入精确难度栏目。

5.5 场景

场景读取 news_scenes。

建议：

有 primary scene 的内容优先进入「日语场景练习」。
没有场景但标题/频道可推断的内容，只能输出「建议补场景」，不能当作已标注。

6. 手动保留动作

第一阶段必须保持人工手动：

修改 news.visibility
归档内容
调整频道是否可见
调整 YouTube channel / podcast show 自动抓取开关
触发补翻译、补转写、重处理
首页配置或专题配置上线
对风险未知、风险失败、版权疑虑内容做最终判断
对 VIP 策略做商业判断

原因：这些动作会改变用户可见内容或成本结构，需要运营审核。

7. 未来半自动动作

第二阶段以后可以考虑：

Admin 保存 AI 建议草案。
运营点击「采纳建议」，批量生成待执行变更。
首页编排版本化，支持预览、发布、回滚。
自动把稳定栏目草案转换成 featured_sections / featured_items。
对补翻译、补转写生成任务草案。
操作后自动复核 API 返回。
结合行为数据自动调整权重。

但半自动动作必须满足：

有版本记录。
有 diff。
有操作者。
有复核状态。
有回滚路径。
有风险硬门槛。

8. 后台需要补的数据模型

8.1 统一资源模型

建议未来新增 content_sources 或等价模型，统一管理：

web source
YouTube channel
YouTube playlist
podcast show
manual collection

建议字段：

id
source_type
external_id
name
description
cover_url
channel_id
auto_crawl_enabled
last_crawled_at
last_error
operator_note
created_at
updated_at

8.2 首页编排模型

建议未来新增：

featured_versions
featured_sections
featured_items

featured_versions：

id
status：DRAFT / ACTIVE / ARCHIVED
title
created_by
published_at
ai_run_id

featured_sections：

id
version_id
section_key
display_name
layout_type
sort_order
visible_item_count
source_limit
presentation_reason

featured_items：

id
section_id
item_type：news / channel / playlist / podcast_show / podcast_episode / collection
item_id
sort_order
reason
risk_snapshot
visibility_snapshot

8.3 AI 建议模型