admin/SEONexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add metadata workbench and shared seo rules

Browse Source
This commit is contained in:
root
2026-04-18 20:23:30 +08:00
parent 2ea87050a5
commit cec1fdbc69
44 changed files with 5488 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
docs/2026-04-18-视频缺失字段工作台V1说明.md Normal file
View File

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