---
name: 重置作品抽取结果
description: 全量重抽前预览或清空单本作品的 upgrade_book 派生状态，把窗口退回 pending。需要对一本书重新跑一遍作品面抽取时使用；正常按窗抽取归 抽取作品知识，定向修复归 修复作品抽取结果，备份恢复归 备份作品抽取结果。
disable-model-invocation: true
---

# 重置作品抽取状态

何时用：某本书要**全量重抽**。升格是串行有状态管线，直接重跑会被旧状态卡死——窗全是 done 不再处理、判重底册装着旧代卡、旧审计行会把新软删卡错还原、别名全行唯一索引让新别名被静默吞掉。

备份与恢复归 `备份作品抽取结果`，定向修复与存量迁移归 `修复作品抽取结果`，正常 `windows/run/status` 归 `抽取作品知识`。

## 依赖边界

同书互斥复用 `抽取作品知识/scripts/upgrade_work_lock.py` 的 advisory lock；备份复验单向调用 `备份作品抽取结果/scripts/backup_upgrade_work.py`，本 Skill 不复制第二份备份验证逻辑。

## 输入

```bash
# 只读预览
.venv/bin/python muse/content/entity/skills/ingest/重置作品抽取结果/scripts/reset_upgrade_work.py --work-id 8

# 真重置
.venv/bin/python muse/content/entity/skills/ingest/重置作品抽取结果/scripts/reset_upgrade_work.py \
  --work-id 8 --execute --backup-dir /private/tmp/muse-upgrade-work8-before-reset \
  --backup-id <manifest-backup_id> --confirmation-sha <manifest-confirmationSha>
```

`--execute` 必须同时给出 `--backup-dir`、`--backup-id`、`--confirmation-sha`；三者由 `备份作品抽取结果` 的清单产出。

## 输出

预览输出按表列出将被软删、硬删和重置的行数统计，不写库。`--execute` 输出实际清理行数、窗口回退数量与单事务提交回执；任一断言失败输出失败原因并整体回滚。

## 数据边界

清理边界逐表核实过约束：

- `muse_knowledge_draft` 升格卡 → **软删**（知识数据绝不物删，可回滚）。
- `example_upgrade_window` → 保留窗行，仅重置 `status=pending`。
- `example_upgrade_alias` → 硬删本书行（全行唯一索引会让软删旧行挡住重抽 INSERT）。
- `example_upgrade_presence`、`example_upgrade_card_state`、`example_upgrade_audit` → 硬删本书行。
- `example_knowledge_embedding` → 软删本书升格卡的全部活向量，并覆盖旧版 reset 遗留在已软删卡上的活向量。

写入范围限于目标租户、目标作品、`upgrade_book` 边界；不生成新抽取内容，不提供 `run/windows/status`。

## 红线

- `--execute` 前必须持同书锁、复验备份并核对代码身份；取锁失败在任何业务 SQL 之前非零退出。
- 全部清理在固定表锁顺序（输入源→派生域，派生域内保持 draft→embedding）的单事务内完成，全清或全不清。
- 知识数据只软删，不物删。
- 不得跳过 `备份作品抽取结果` 的备份直接重置。

## 复利合同

- `--execute` 七域清理断言通过后经 `propose_lesson_dedup` 登记 `example_lesson`（绑 work_id / backup_id）。
- 预览路径不写库、不登记 lesson。