# 视频缺失字段工作台 V1 说明 ## 目标 这套工作台用于把视频库里的空字段问题集中收口，给技术、运营、Codex 一个统一入口： 1. 看当前哪些字段缺失最严重 2. 看哪些视频优先处理 3. 复制一份可以直接派给 Codex 的提示词 ## 当前范围 V1 已上线的是“工作台产物 + 后台读取入口 + 手动触发生成 + 历史运行记录”。 当前不做： 1. 不会因为发现空字段，就自动调用 AI API 去猜演员、导演、年份、地区、语言 2. 不会在采集过程中，直接把不确定的结构化资料写回库 3. 不会自动加入计划任务周期跑 ## 命令行入口 ### 1. 只生成工作台 ```bash php SEONexus/code/think video:metadata:workbench --sample=20 --queue-limit=100 --prompt-limit=20 ``` 参数说明： 1. `--sample` 说明：缺失字段样本数，用于抽样展示典型问题视频 2. `--queue-limit` 说明：重采优先队列条数，用于给出优先处理的视频集合 3. `--prompt-limit` 说明：生成给 Codex 的派单样本数 ### 2. 一次性生成“工作台 + 缺字段任务池” ```bash php SEONexus/code/think video:metadata:task-pool --sample=20 --queue-limit=100 --prompt-limit=20 --batch-size=20 --batch-limit=10 ``` 参数说明： 1. `--sample` 说明：缺失字段样本数，用于抽样展示典型问题视频 2. `--queue-limit` 说明：重采优先队列条数，用于给出优先处理的视频集合 3. `--prompt-limit` 说明：生成给 Codex 的派单样本数 4. `--batch-size` 说明：每个待处理批次包含多少条视频 5. `--batch-limit` 说明：单次最多生成多少个批次 ## 后台接口 1. `GET /admin/video/metadata/missing/workbench` 作用：读取最新工作台摘要；如果没有现成产物，会现场生成一次 2. `GET /admin/video/metadata/missing/prompt` 作用：读取给 Codex 的最新提示词 3. `GET /admin/video/metadata/missing/workbench/runs` 作用：读取历史运行记录，方便做前后对比 4. `POST /admin/video/metadata/missing/workbench/run` 作用：强制刷新工作台产物 ## 产物目录 生成后会写到： ```text SEONexus/code/app/public/_admin_templates/video-metadata-missing-workbench/ ``` 主要文件： 1. `index.json` 作用：后台摘要数据源 2. `index.html` 作用：可直接打开看的工作台页面 3. `prompts/latest.md` 作用：可以复制给 Codex 的接手提示词 历史运行记录会写到： ```text SEONexus/code/app/public/_admin_templates/video-metadata-missing-workbench/runs/ ``` 每次生成都会保存一份： 1. `video-metadata-missing-workbench.summary.json` 2. `video-metadata-missing-workbench.summary.html` 3. `prompt.md` ## 适合怎么用 ### 场景一：技术自己接手 1. 后台刷新工作台 2. 打开 `prompt` 或 `latest.md` 3. 把提示词发给 Codex 4. Codex 分析优先级、批次、风险和后续执行建议 ### 场景二：运营先发现问题 1. 运营在后台看到字段缺失严重 2. 让技术刷新工作台 3. 技术把提示词发给 Codex 接手 ## 为什么暂时不自动调 AI 因为空字段里最重的是： 1. `v_director` 2. `v_actor` 这些都是结构化事实字段，不能靠 AI 猜。 现阶段更优策略是： 1. 先扫描并收集 2. 先重采、补源、人工确认 3. 只把文案型字段交给 AI ## 当前是否自动跑 当前不是自动计划任务触发，也不是采集时自动偷偷触发。 现在的触发方式只有两种： 1. 技术手动执行命令 2. 后台手动点击刷新接口 如果技术希望挂到服务器计划任务，建议先挂下面这条命令： ```bash php /www/wwwroot/diff-maccms/SEONexus/code/think video:metadata:task-pool --sample=8 --queue-limit=50 --prompt-limit=10 --batch-size=10 --batch-limit=10 ``` 推荐原因： 1. 一次执行同时刷新工作台和缺字段任务池 2. 不会自动补结构化事实字段 3. 只生成产物，不会偷偷调用 OpenAI API 4. 更适合作为跨项目、跨模板的安全计划任务入口 如果你是通过数据库里的计划任务表来挂，不走系统 cron，也已经留好了安全入口： 1. `pt_code` 使用：`REFRESH_VIDEO_METADATA_TASK_POOL` 2. 对应逻辑入口：`PlanTask::refreshVideoMetadataTaskPool()` 3. 默认行为： - 只刷新工作台和任务池产物 - 不自动补演员、导演、年份、地区、语言、发布日期 - 不自动调用 OpenAI API - 不自动写回视频库 建议口径： 1. 先在测试环境或低频环境启用 2. 先把 `pt_limit` 设成较大间隔，比如 `3600` 或 `21600` 3. 跑稳定后，再决定是否提升频率 也就是说，把代码同步到其它项目后，不会自己偷偷扫描全表，不会自己调用 AI。 如果别的项目想启用这条线，最小启动步骤是： 1. 同步最新代码 2. 执行一次 `video:metadata:task-pool` 3. 后台读取任务池接口或直接打开任务池产物页 这样就能先把“缺字段扫描、待处理批次、Codex 提示词”全跑起来。 ## 其它项目怎么启动 如果把这套代码同步到其它项目，要启动这个工作台，只需要： 1. 同步最新代码 2. 执行一次 ```bash php SEONexus/code/think video:metadata:workbench ``` 3. 后台读取对应接口或直接打开产物页 ## 下一阶段建议 V2 可以继续做： 1. 扫描全表空字段后，自动收集到“待处理池” 2. 后台展示“缺字段任务池” 3. 后台一键生成 Codex 派单提示词 4. 再决定是否接计划任务定时刷新 5. 给计划任务增加“只刷新工作台，不自动补事实字段”的安全模式 当前其中第 1 到 3 步已经具备基础能力，第 4 步现在可以通过挂 `video:metadata:task-pool` 命令实现。 ## 当前新增：缺字段待处理池 当前已经补出第二层： 1. `GET /admin/video/metadata/missing/task-pool` 作用：读取缺字段待处理池 2. `GET /admin/video/metadata/missing/task-pool/status` 作用：读取缺字段任务池总览状态，包含工作台规模、任务池批次状态、计划任务状态 3. `GET /admin/video/metadata/missing/task-pool/plan-task/status` 作用：读取缺字段计划任务的启用情况和间隔 4. `GET /admin/video/metadata/missing/task-pool/ops` 作用：读取缺字段任务池运维总览，包含推荐动作、常用命令和产物路径 5. `POST /admin/video/metadata/missing/task-pool/plan-task/status/save` 作用：保存缺字段计划任务的启用状态和执行间隔 6. `GET /admin/video/metadata/missing/task-pool/batch/detail` 作用：读取单个批次详情 7. `GET /admin/video/metadata/missing/task-pool/batch/prompt` 作用：读取单个批次的 Codex 提示词 8. `POST /admin/video/metadata/missing/task-pool/run` 作用：重新生成缺字段待处理池 9. `POST /admin/video/metadata/missing/task-pool/batch/state/save` 作用：保存批次状态 对应产物目录： ```text SEONexus/code/app/public/_admin_templates/video-metadata-missing-task-pool/ ``` 这套任务池现在已经包含： 1. 最新总览 `index.json` / `index.html` 2. 单批次稳定详情 `batches/*.json` 3. 单批次稳定提示词 `batches/*.md` 4. 单批次状态历史 `state/history/*.json` 5. 单批次复制提示词按钮和动作链接 6. 状态总览页 `status/index.json` / `status/index.html` 状态总览页的作用： 1. 直接展示当前缺字段视频规模 2. 展示当前任务池批次数和批次状态统计 3. 展示数据库计划任务状态 4. 适合不进后台接口时，直接打开 HTML 快速查看 ## 运维总览页 除了状态总览页，当前还补了一个更偏“后台操作指引”的运维总览页： ```text SEONexus/code/app/public/_admin_templates/video-metadata-missing-task-pool/ops/index.html SEONexus/code/app/public/_admin_templates/video-metadata-missing-task-pool/ops/index.json ``` 它的作用不是替代状态页，而是把“现在该做什么”讲得更直接： 1. 当前推荐动作 2. 当前可执行命令 3. 当前工作台和任务池产物路径 4. 当前计划任务是否启用 这个页面适合给： 1. 运营看，少看接口字段 2. 技术看，少翻文档 3. 接手的 Codex 看，直接按页面里的命令继续执行 当前这页默认会在刷新任务池时一起生成，后续如果计划任务接上，也会同步刷新。 ## 后台首页快捷入口 当前后台首页 `/admin` 已补成快捷入口页，直接提供下面这些跳转： 1. 工作台 2. 任务池 3. 状态总览 4. 运维总览 5. 计划任务状态 如果你是新接手的 Codex，先打开后台首页，再按页内链接进入对应模块，会比直接记接口路径更快。 ## Vue 后台迁移说明 这一轮已经把“视频缺字段工作台 / 任务池 / 状态总览 / 运维总览”的页面入口迁到 `SEONexusAdmin` 这个 Vue 后台。 现在要区分两类入口： 1. PHP `/admin/video/...` 作用：数据接口 2. Vue `#/video/...` 作用：后台实际页面入口 当前正确的后台页面路径是： 1. `#/video/metadata/missing/workbench` 2. `#/video/metadata/missing/task-pool` 3. `#/video/metadata/missing/task-pool/status` 4. `#/video/metadata/missing/task-pool/ops` 说明： 1. 不要再把 `/admin/video/metadata/missing/task-pool/ops` 当成最终后台页面 URL 2. 这个路径在当前体系里更适合作为 PHP 接口或旧产物路径，不适合作为 Vue 后台页面入口 3. 如果要同步到其它服务器，除了同步 `SEONexus/code` 里的 PHP 数据接口，还必须同步 `SEONexusAdmin` 的 Vue 页面和 `dist` ## 批次状态说明 当前批次状态先走“文件态”，不走数据库表。 状态文件位置： ```text SEONexus/code/app/public/_admin_templates/video-metadata-missing-task-pool/state/batch-status.json ``` 状态历史文件位置： ```text SEONexus/code/app/public/_admin_templates/video-metadata-missing-task-pool/state/history/ ``` 可用状态： 1. `pending` 含义：待处理 2. `dispatched` 含义：已派单，已经发给 Codex 或某位技术 3. `processing` 含义：处理中 4. `done` 含义：已完成 5. `skipped` 含义：已跳过 当前这样设计的原因： 1. 不需要改数据库 2. 可以马上同步到其它项目使用 3. 即使别的项目环境不一致，也能直接落地 4. 可以先把“当前状态”和“历史轨迹”都收进文件，再决定是否升级成数据库态 ## 批次历史接口 当前已经补出： 1. `GET /admin/video/metadata/missing/task-pool/batch/history` 作用：读取某个批次的状态变化历史 2. `POST /admin/video/metadata/missing/task-pool/batch/state/save` 作用：保存某个批次的状态变化，同时写入历史 3. `GET /admin/video/metadata/missing/task-pool/batch/detail` 作用：读取某个批次的完整内容、当前状态、历史 4. `GET /admin/video/metadata/missing/task-pool/batch/prompt` 作用：直接拿某个批次专属的 Codex 接手提示词 说明： 1. 每次状态变化都会追加写入历史 2. 历史时间戳已经提升到微秒级，避免同一秒连续操作时顺序混乱 后面如果这套机制稳定，再考虑升级成数据库态任务池。 ## 计划任务建议值 如果你准备把 `REFRESH_VIDEO_METADATA_TASK_POOL` 放进后台计划任务列表，建议先这样配： 1. `pt_enable = 0` 说明：默认先不启用，确认后台状态页和产物页正常后再打开 2. `pt_limit = 86400` 说明：先按 1 天跑一次，避免太频繁刷新 启用时可以先观察： 1. 工作台是否持续刷新 2. 任务池批次状态是否正常 3. 是否有其它项目需要同步相同计划任务 如果后台先想看“该不该启用、启用后跑什么”，优先打开运维总览页； 如果只是想看当前规模和状态，优先打开状态总览页。