---
name: 修复作品抽取结果
description: 对已有 upgrade_book 抽取结果做定向修复与存量迁移，包括 legacy failed 窗口恢复、单卡质量修复、presence 重复清理、存量窗口章号定位和存量回洗。需要修补个别窗口或行而不是重跑全书时使用；正常按窗抽取归 抽取作品知识，全量重置归 重置作品抽取结果，备份恢复归 备份作品抽取结果。
disable-model-invocation: true
---

# 定向修复作品抽取结果

何时用：抽取结果**局部**出问题——某个窗口停在 legacy failed、某张卡字段质量不合格、presence 出现重复行、存量 `[窗N]` 演变条目没有真实章号。全量重抽用 `重置作品抽取结果`，备份恢复用 `备份作品抽取结果`，正常 `windows/run/status` 用 `抽取作品知识`。

## 依赖边界

修复算法的唯一实现在 `抽取作品知识/scripts/upgrade.py`；`maintenance.py` 只是维护命令的入口，不把正常抽取命令混进来。同书互斥同样复用 `upgrade_work_lock.py`。

## 输入

| 入口 | 用途 |
|---|---|
| `scripts/maintenance.py` | 暴露 `recover-legacy-failed`、`repair-card-quality`、`repair-presence-duplicates`。 |
| `scripts/migrate_upgrade_windows.py` | 将存量 `[窗N]` 演变条目定位到真实章号，仅 dry-run。 |
| `scripts/parse_rewash.py` | 存量回洗工具；是否退役由现有数据状态决定。 |

```bash
.venv/bin/python muse/content/entity/skills/ingest/修复作品抽取结果/scripts/maintenance.py \
  recover-legacy-failed --work-id 8 --window-no 7 --preview
```

## 输出

`--preview` 输出待修复范围、行集合与一个确认 SHA；`--execute` 输出实际修改行数与回执。`migrate_upgrade_windows.py` 只输出迁移计划。

## 数据边界

- preview 默认只读；execute 只修改目标租户、目标作品、`upgrade_book` 边界内的派生状态。
- 不生成新抽取内容，不提供正常 `run/windows/status`。
- `migrate_upgrade_windows.py` 当前只输出迁移计划，不落库；真实写入仍需另行 gate 与授权。

## 红线

- 定向修复必须先 `preview`，`execute` 精确匹配 preview 的确认 SHA，并显式确认没有同书活进程。
- 修复范围、行集合、revision、payload、owner 或关联状态任一漂移都失败关闭。
- 取锁失败必须在业务 SQL、文件验证、嵌入或模型调用之前非零退出。
- 不得用定向修复代替全量重抽去掩盖成批的抽取缺陷。

## 复利合同

- 存量重洗提交后经 `propose_lesson_dedup` 登记 `example_lesson`（绑清洗统计）。
- 升格仍走人工评审；定向修复不得掩盖成批抽取缺陷。