Ver Fonte

docs: 同步 CLAUDE.md(github-trending 与定时生成)

修正封面承接语、coverTags 停用、todayStars/top6、max_tokens 16384+截断重试、封面与章节目录渲染等过时描述;新增「定时生成」段与 SCHEDULES/SCHEDULER_ENABLED。

Co-Authored-By: Claude <noreply@anthropic.com>
lkatzey há 5 dias atrás
pai
commit
fb0be6add8
1 ficheiros alterados com 12 adições e 6 exclusões
  1. 12 6
      CLAUDE.md

+ 12 - 6
CLAUDE.md

@@ -39,7 +39,7 @@ packages/templates/ 5 个模板的 Remotion React 组件
 
 输入始终是**结构化 JSON** (`VideoInputSchema`)。流水线在 `packages/core/src/stages/` 中依次执行 6 个阶段:
 
-1. **parse** — 通过 `VideoInputSchema` 验证 JSON,转换为内部 `ParsedContent`(cover → scene-0,outro → 最后一个 scene)。`github-trending` 模板的 cover 场景在这里确定性写入开场口播(masthead + "今日精选 N 个项目"),并承载 LLM 产出的 `coverTags`(≤5 个主题标签)与 `trendSummary`(一句话趋势总结),由模板在首屏渲染;不再注入单独的 summary 场景
+1. **parse** — 通过 `VideoInputSchema` 验证 JSON,转换为内部 `ParsedContent`(cover → scene-0,outro → 最后一个 scene)。`github-trending` 在这里:①内容场景按 `github.repo.todayStars` 降序取 **top 6**(视频只介绍今日涨星最多的 6 个,顺序与首屏一致);②确定性写入 cover 开场口播(一句承接语 `下面进入项目详解。`,**不含日期/数量**——日期与卡片由首屏视觉呈现);③承载 LLM 产出的 `trendSummary`(一句话趋势)透传到首屏渲染。不再注入 summary 场景,也已停用 `coverTags`
 2. **tts** — 按场景调用 TTS provider,生成逐场景音频文件 + word timestamps
 3. **assets** — 解析图片资源(本地 `path` > 远程 `url` > 关键词 `query`),复制背景图/字体
 4. **compose** — 转换为带帧时间轴的 `ComposedProject`,word timestamps 转为场景内相对时间。逐字段拷贝场景数据——新增场景字段时**必须在此阶段显式透传**(`buildInputProps` 用 `...scene` 自动透传,但 compose 是手写字段映射)
@@ -62,7 +62,7 @@ Provider 通过 `registerProvider()` 在 `packages/tts/src/providers/` 中注册
 ### 模板系统
 
 5 个模板(news、knowledge、opinion、marketing、github-trending),每个在 `packages/templates/src/<name>/index.tsx` 中有对应的场景组件。共享基础组件位于 `packages/templates/src/base/`。`Root.tsx` 按以下规则路由:
-- `sceneType === "cover"` → 内置 `CoverScene`(`github-trending` 的 cover 接收 `coverTags`/`trendSummary`,在首屏渲染主题标签行 + 一句话趋势句
+- `sceneType === "cover"` → 内置 `CoverScene`(`github-trending` cover 渲染:深色标题卡居中靠上 + top6 仓库卡片网格[横屏 3×2 / 竖屏 2×3,每卡:名称/语言/今日 +N 涨星/highlights 一句话] + trendSummary 副标题;另在进度条上方渲染 `ChapterToc` 章节目录,当前章节高亮
 - `sceneType === "outro"` → 内置 `OutroScene`
 - 其他 content 类型 → `SCENE_MAP[template]` 对应模板组件
 
@@ -100,13 +100,19 @@ publish 阶段位于 `packages/core/src/publish/`(`oss.ts` 用 `ali-oss` 分
 - `TIMEZONE` — github-trending 首屏日期与输出日期子目录所用时区,默认 `Asia/Shanghai`(Docker 同时据此设 `TZ`)
 - `OSS_REGION` `OSS_BUCKET` `OSS_ACCESS_KEY_ID` `OSS_ACCESS_KEY_SECRET` `OSS_ENDPOINT` `OSS_PATH` `OSS_PUBLIC_DOMAIN` `OSS_SECURE` — 阿里云 OSS(密钥走 .env)
 - `FEISHU_WEBHOOK_URL` `FEISHU_WEBHOOK_SECRET` — 飞书自定义机器人 webhook
+- `SCHEDULES` — JSON 数组,整体覆盖 `config/default.yaml` 的 `schedules`(部署期改定时任务无需重建镜像)
+- `SCHEDULER_ENABLED` — `false` 关闭容器内进程内调度器(默认开启)
+
+## 定时生成(容器内调度)
+
+容器内置**进程内调度器**:Next.js 服务启动时经 `apps/web/src/instrumentation.ts`(`register()` 钩子)启动 `apps/web/src/lib/scheduler.ts`,用 `node-cron` 按 `config/default.yaml` 的 `schedules` 段(cron + TZ,默认 Asia/Shanghai)到点 spawn CLI 渲染——复用 `/api/render` 同一链路(`apps/web/src/lib/run-render.ts` 的 `startRenderJob`),任务进 jobs 列表、走 OSS/飞书发布。单副本下进程内调度不重复执行;内置单飞(上一次未结束则跳过)。改配置后重启容器生效;`SCHEDULES` 环境变量可整体覆盖,`SCHEDULER_ENABLED=false` 关闭。详见 `docs/DEPLOYMENT.md` §4.3。
 
 ## 核心 Schema
 
 全部在 `packages/shared/src/types/` 中用 Zod 定义:
 
-- `VideoInputSchema` — 用户输入格式(title、subtitle、cover、scenes[]、outro、globalStyle;github-trending 另有可选 `coverTags`/`trendSummary`,由 LLM 产出)
-- `SceneSchema` — 内部场景,含 `sceneType: "cover" | "content" | "summary" | "outro"`、可选 `github`(GithubSceneData)、可选 `coverTags`(string[])/`trendSummary`(string,仅 github-trending 的 cover 场景使用)
+- `VideoInputSchema` — 用户输入格式(title、subtitle、cover、scenes[]、outro、globalStyle;github-trending 另有可选 `trendSummary`,由 LLM 产出。`coverTags` 字段保留但已停用
+- `SceneSchema` — 内部场景,含 `sceneType: "cover" | "content" | "summary" | "outro"`、可选 `github`(GithubSceneData,`repo` 含 `todayStars` 今日涨星)、可选 `trendSummary`(string,仅 github-trending 的 cover 场景用。`coverTags` 保留但停用)
 - `ComposedSceneSchema` — compose 后的场景,含帧时间轴、`audioPath`、已解析的图片。字段与 `SceneSchema` 一一对应
 - `PipelineInputSchema` — 顶层流水线输入(text、template、platform、ttsProvider)
 
@@ -114,6 +120,6 @@ publish 阶段位于 `packages/core/src/publish/`(`oss.ts` 用 `ali-oss` 分
 
 ## LLM 与 TTS 提示
 
-- `LLMClient`(`packages/shared/src/llm/client.ts`)显式设置 `max_tokens: 8192`——`github-trending` 多仓库结构化 JSON 输出约 6000 tokens,provider 默认值(1024-4096)会截断响应导致 JSON 解析失败
-- `github-trending` 的 cover narration 是 `parse.ts` 硬编码模板字符串(含日期和仓库计数),**不交给 LLM**;但首屏的 `coverTags`(≤5 个主题标签)与 `trendSummary`(一句话趋势)由 LLM 产出并透传到 cover 场景渲染。LLM 仍只产出 per-repo `scenes[]`,不生成 overview/summary 场景
+- `LLMClient`(`packages/shared/src/llm/client.ts`)设置 `max_tokens: 16384`,`chat()` 返回 `{ content, finishReason }`。github-trending 大 trending 列表可能撑爆 token 上限被截断 → JSON 不完整;parse 阶段对解析失败会**重试一次**(追加精简指令让响应在限额内闭合),错误信息带 `finish_reason` 便于诊断
+- `github-trending` 的 cover narration 是 `parse.ts` 硬编码的一句承接语(`下面进入项目详解。`),**不交给 LLM**,也不含日期/仓库数量。`trendSummary`(一句话趋势)由 LLM 产出并透传到首屏渲染。LLM 只产出 per-repo `scenes[]`(数据源规则要求按今日涨星降序选 6 个),不生成 overview/summary 场景;parse 端会再次按 todayStars 排序取 top6 作兜底。`coverTags` 已停用
 - TTS 按场景独立合成,受 provider 配额限制;调试布局可用 `--no-tts` 跳过(生成静音视频)