---
name: 抽取作品知识
description: 将已完成拆解的作品正文按窗口抽取为 upgrade_book 实体、关系与演变草稿。作品完成拆书后需要建立本书知识面、续跑抽取窗口或查看抽取进度时使用；备份/恢复归 备份作品抽取结果，全量重置归 重置作品抽取结果，定向修复/迁移归 修复作品抽取结果，本 Skill 不负责这三类维护。
disable-model-invocation: true
---

# 按窗抽取作品知识

何时用：`拆解书稿` 已产出章节细纲与实体脚手架后，把本书正文按窗抽成 `upgrade_book` 来源的实体、关系和演变草稿。

## 输入与执行

- 输入是同一作品的 Canonical 章节正文、活动字段合同、已有 `upgrade_book` 草稿和窗口状态。
- `scripts/upgrade.py windows` 机械切窗，`run` 按窗顺序抽取，`status` 只读显示进度。
- 内容模型通过 `调用内容模型` 调用；嵌入通过 `生成知识向量` 写入。
- 同一租户、同一作品的 `windows/run` 通过 `upgrade_work_lock.py` 持有 PostgreSQL session advisory lock；取锁失败时不得执行任何业务 SQL、模型或嵌入调用。

## 抽取合同

正文按窗抽取 `upgrade_book` 实体卡。模型只返回新实体和已知实体的语义变化；名称、别名、出场章和窗口产物由确定性代码校验并落库。每窗采用短事务：模型和嵌入调用期间不持业务连接；实体与关系分别提交 `processing` marker，最终嵌入完整成功后才与 `done` 同事务提交。

新卡 `INSERT` 必须使用数据库实际返回的 revision；同窗后续更新绑定该 revision。关系首次同 pair 冲突只允许一次模型修复；未知额外键、字段异值、嵌入 owner 冲突或 payload 漂移均失败关闭。启动时只恢复可精确撤销的 `processing`；同一窗口本次第二次失败立即停止作品并留下 `retryable-clean` 断点。

名称只能取首次登场章正文中唯一命中的合法规范名或别名。多个合法名称同时命中、只命中通用称谓或无法唯一确定时，退化为中性类型描述，禁止借未来规范名补全早期台阶。

## 命令

```bash
# 幂等切窗
.venv/bin/python muse/content/entity/skills/ingest/抽取作品知识/scripts/upgrade.py windows --work-id 8

# 顺序抽取并断点续跑
.venv/bin/python muse/content/entity/skills/ingest/抽取作品知识/scripts/upgrade.py run --work-id 8 \
  [--max-windows K] [--max-calls M] [--semantic-dedup]

# 只读进度
.venv/bin/python muse/content/entity/skills/ingest/抽取作品知识/scripts/upgrade.py status --work-id 8
```

## 数据与失败边界

- 读取 Canonical 章节、活动 schema、已有升格草稿及窗口状态。
- 写入 `muse_knowledge_draft`、`example_upgrade_window`、`example_upgrade_alias`、`example_upgrade_presence`、`example_upgrade_card_state`、`example_upgrade_audit` 和 `example_knowledge_embedding`。
- `SOURCE_TYPE="upgrade_book"`、`upgrade-reset` 等是数据库历史兼容值，不随 Skill 改名。
- 不提供修复、重置、备份、恢复或存量迁移入口；备份与恢复由 `备份作品抽取结果`、全量重置由 `重置作品抽取结果`、定向修复与存量迁移由 `修复作品抽取结果` 承担。

## 输出

- 面向当前任务的可执行判断、检查清单或改写建议（Markdown 结构化段落）。
- 不直接落库、不代替 `写下一章` / `决定正文候选去留` 写 Canonical。

## 复利合同

- 本次至少完成一窗后经 `propose_lesson_dedup` 登记 `example_lesson`（绑 work_id / 完成窗数 / 调用数）。
- 升格仍走人工评审，不自动把升格卡升为公共范式。

## 输入