380 lines
12 KiB
Markdown
380 lines
12 KiB
Markdown
# 视频缺失字段工作台 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. 是否有其它项目需要同步相同计划任务
|
||
|
||
如果后台先想看“该不该启用、启用后跑什么”，优先打开运维总览页；
|
||
如果只是想看当前规模和状态，优先打开状态总览页。
|