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:
@@ -115,12 +115,10 @@ def _parse_progress_line(line: str) -> int | None:
|
||||
def _sorted_frame_files(frames_dir: Path) -> list[Path]:
|
||||
"""按文件名中的帧号数值排序返回帧文件列表(自然排序,非字典序)。
|
||||
|
||||
关键点:ffmpeg 的 %04d 编号在超过 9999 帧后会自动扩为 5 位
|
||||
(frame_10000.png 等),此时 sorted() 默认的字典序会把 5 位编号排在
|
||||
4 位编号之前(如 "frame_10009" < "frame_1009"),导致帧号回退、
|
||||
manifest 时间与图像错位(曾真实发生于 run_339ec7ee437f 的 14236 帧
|
||||
任务,全片后半段时间轴全部错乱)。必须解析出帧号按数值排序,
|
||||
才能保证"第 k 个文件 = 第 k 个选中帧 = 时间 index*step/fps"成立。
|
||||
ffmpeg 的 %04d 编号超过 9999 帧后会扩为 5 位,字典序会把 5 位编号排在
|
||||
4 位之前("frame_10009" < "frame_1009"),导致帧号回退、帧时间与图像
|
||||
错位。必须解析帧号按数值排序,才能保证“第 k 个文件 = 第 k 个选中帧 =
|
||||
时间 index*step/fps”成立。
|
||||
"""
|
||||
def frame_number(path: Path) -> int:
|
||||
# 文件名形如 frame_0001.png,取下划线后的数字部分。
|
||||
|
||||
Reference in New Issue
Block a user