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
+6 -12
View File
@@ -104,9 +104,8 @@ class WorkflowScheduler:
else:
time.sleep(self.interval_seconds)
except Exception: # noqa: BLE001
# 单次轮询异常不杀死调度线程:曾因 next_queued_run/execute_run
# 的未捕获异常导致线程退出,任务永远停留在 QUEUED 不被拾起
# run_011d01f19999 实际发生)。记录后跳过本轮,下一轮继续。
# 单次轮询异常不杀死调度线程:否则任务会永远停在 QUEUED
# 无人拾起。记录后跳过本轮,下一轮继续。
logger.exception("调度器轮询异常,跳过本轮")
time.sleep(self.interval_seconds)
def _resolve_ref(
@@ -131,10 +130,8 @@ class WorkflowScheduler:
# 任务不存在或不在可执行状态(排队/暂停)时直接返回,避免重复执行。
if run is None or run["status"] not in ("QUEUED", "PAUSED"):
return
# 已暂停的任务不自动续跑:直接返回保持 PAUSED,等用户显式 resume
# resume 把状态转回 QUEUED 后才会真正执行)。修复回归——此前以
# PAUSED 进入后立即置 RUNNING,节点循环的暂停检查永远不成立,
# 任务被复活继续执行("点击暂停反而开始任务")。
# 已暂停的任务不自动续跑:直接返回保持 PAUSED,等用户显式 resume
# resume 转回 QUEUED 后才执行);否则暂停会被立刻覆盖成 RUNNING。
if run["status"] == "PAUSED":
return
@@ -150,11 +147,8 @@ class WorkflowScheduler:
return
# 解析并校验 DAG,随后计算拓扑执行顺序。
#
# 任何预检异常(缺字段/边引用不存在/环形依赖)都必须在这里把任务标
# FAILED修复前这段在 try 之外,异常直接冒到 _loop 被吞掉,任务停在
# QUEUEDnext_queued_run 每轮拾起同一条队首记录,后续任务全部堵塞
# (R04:环形 DAG 卡死队列)。历史无效版本无法删除,只能就地判失败。
# FAILED否则队首记录会一直停在 QUEUED 堵塞后续任务。
try:
definition = WorkflowDefinition.from_dict(version["definition"])
definition.validate()
@@ -311,7 +305,7 @@ class WorkflowScheduler:
"""
source = Path(resolved)
if not source.is_file():
# 兼容旧版本:原文件已改名,但最终别名仍记录有效路径时直接复用。
# 兼容历史记录:原文件已改名,但最终别名仍指向有效路径时复用。
existing = self.db.get_artifact(run["id"], alias)
if existing is not None and Path(existing["uri"]).is_file():
return existing["uri"]