docs: 注释规范要求精简可读,并清理生产代码中的历史叙事

AGENTS.md 的注释规范新增三节可执行约束:

- 只写代码真实逻辑:注释只回答"做什么"与"为什么必须这么做",禁止写决策/
  修改时间、历史版本对比、实测数据与实验结论、事故与缺陷编号(run_xxxx /
  batch_xxxx / R01 等)——这些属 docs/decisions.md 与审查跟踪文件;当前生效
  的约束可以写,但不附带它何时因何变成这样。
- 精简可读:单段连续注释不超过 3 行;docstring 一句话概括职责,不重复函数名
  已表达的信息;不写逐行翻译代码的废话注释,只在非显然处(业务规则、边界、
  易错点、外部约束)加注。
- 覆盖范围:测试注释只说明验证什么行为,回归用例可保留一句溯源;并明确
  参数说明应写在**参数读取处**附近,而不是把多个参数的解释堆在离使用位置
  很远的注释块里。

按此清理生产代码(注释净减 70 行,18 个文件),典型处理:

- nodes/whisper.py:删掉堆在一起、含"用户 2026-08 决定 / 实测 savr-1054"
  等叙事的参数块,把各参数说明移到各自的读取处与 model.transcribe 调用处;
- nodes/llm_filter.py、nodes/subtitle_cleanup.py:模块 docstring 去掉英文
  背景叙事与条数统计,保留"默认只跑规则层""整条删除而非 '-' 占位"等当前
  行为;
- src/wov_app/{batch,db,scheduler}.py 与 routers:去掉 batch_xxx/run_xxx 事故
  编号与"修复前……"对比,改为一句"否则会出现什么问题";
- nodes/ass.py、frame_extract.py:去掉废弃值对比与日期,保留判据本身。

安全验证:用 AST 对比(剥离 docstring 后比较语法树)确认 18 个文件**零逻辑
变更**;`nodes/proper_nouns.py` 的规则表 reason 字段会注入 LLM 提示词,属于
数据而非注释,已恢复原值。全量测试 476 passed。
This commit is contained in:
2026-09-13 16:37:49 +08:00
parent 8f6083f8cf
commit 7a7212f70c
18 changed files with 192 additions and 262 deletions
+12 -21
View File
@@ -353,11 +353,10 @@ class Database:
def next_queued_run(self) -> dict[str, Any] | None:
"""按创建时间返回最早一条排队(QUEUED)任务。
只取 QUEUEDPAUSED 任务必须由用户显式 resume(转回 QUEUED)后调度器
才重新执行。修复回归——此前把 PAUSED 也当可执行任务拾起,execute_run
会先置 RUNNING 再检查暂停,导致"点击暂停反而开始任务"
同时排除 source=batch 的批量运行:批量任务由批量引擎使用视频旁的
同名文件夹作为 storage 执行,主调度器拾起会用错存储目录。
只取 QUEUEDPAUSED 必须由用户显式 resume 后才执行,否则暂停会被
execute_run 立刻覆盖成 RUNNING。
排除 source=batch:批量运行由批量引擎在私有工作空间执行,主调度器
拾起会用错存储目录。
"""
with self._connect() as conn:
row = conn.execute(
@@ -388,13 +387,10 @@ class Database:
def recover_interrupted_batch_jobs(self, updated_at: str) -> int:
"""重启恢复:把遗留 RUNNING 的批量任务恢复为 QUEUED,返回恢复数量。
批量引擎处理视频(尤其大文件)时进程被杀/重启,批量任务停在
RUNNING:其关联 run 由 recover_interrupted_runs 恢复为 QUEUED,但
批量任务本身若保持 RUNNINGnext_queued_batch_job 只拾取 QUEUED
永远不会重新驱动它 → 未处理完的 PENDING 视频永久残留
batch_969fabe74b83 事故链路之一)。恢复为 QUEUED 后引擎重新拾起,
从断点(剩余 PENDING 视频 + 已恢复的 run)继续处理。用户主动暂停的
PAUSED 批量任务保持不变,等待显式 resume。
批量任务停在 RUNNINGnext_queued_batch_job 只拾取 QUEUED
永远不会重新驱动它,未处理完的 PENDING 视频会永久残留;恢复为
QUEUED 后引擎从断点(剩余视频 + 已恢复的 run)继续。用户主动暂停的
PAUSED 保持不变。
"""
with self._connect() as conn:
cur = conn.execute(
@@ -579,15 +575,10 @@ class Database:
def sync_batch_job_progress(self, job_id: str) -> None:
"""按视频明细实时对齐任务的 total/done/failed 汇总并落库。
统计口径(2026-09 用户确认):total = 本批**无字幕、需要处理**的视频数
(= 明细里非 SKIPPED 的数量,创建时已固定,运行中 SKIPPED 不会变化);
done = 实际**处理完成**的视频数(仅 COMPLETEDSKIPPED 不计);
failed = 处理失败的视频数。已有字幕直接跳过的视频不参与 total/done
引擎在暂停、视频间检查、收尾等边界调用,router 在读取前也调用,保证
前端看到的进度始终与明细一致——即使任务被暂停或进程被终止(回归
batch_fee668175444:整批 431 个含 383 个已有字幕,应显示 15/48 而非
0/431)。任务不存在时静默返回。
口径:total = 需处理的视频数(非 SKIPPED,创建时固定);done 只计
COMPLETEDSKIPPED 不计);failed 为失败数。引擎在暂停、视频间与
收尾边界调用,router 读取前也调用,保证前端进度与明细一致(即使任务
被暂停或进程被终止)。任务不存在时静默返回
"""
with self._connect() as conn:
counts = conn.execute(