c9f69d9d6d
范围（不含 design-story-foundation、docs/、humanization/README.md 等进行中改动）:
1. 新增 harness/ 控制平面
- skill_harness.py 静态审计：32 个运行时 Skill 的 frontmatter/manifest/文档污染，当前 0 问题
- run_selected.py 选择性执行器：manifest 与磁盘一一对账、依赖阻断、
空跑与 skip-only 失败关闭、AST 测试形状门
- manifests/skills.json：32 个 Skill 的合同责任方与协作领域登记
- manifests/test-inventory.json：81 个测试资产登记
- specs/skill-testing.md 与 README.md：测试分层、证据边界与 harness 职责
2. 实现测试从 .claude/skills/*/scripts/ 迁至 tests/skills/<skill>/
- 71 个测试文件迁移并修复项目根与临时目录运行导入
- 数据库触发器测试宽泛异常收窄为 psycopg.errors.RaiseException
- 抽取离线大测试拆出真实 PG smoke（默认阻断，不计入离线通过）
- 抽取 presence 去重边界拆出独立测试：493 + 78 = 571 项检查不变
3. 运行时文档清理
- 13 个 SKILL.md 移除自测/离线验证段落、测试命令与测试文件事实源表述，
只保留运行时合同；业务运行合同、额度、授权与离线模式均保留
4. SoT 同步
- AGENTS.md：新增 Skill 领域索引（7 个合同责任方分组，覆盖 32 个运行时 Skill）
- 领域 07：测试入口改由 harness/manifests/ 登记，SKILL.md 不承载测试命令
- humanization 覆盖矩阵：活动测试路径同步迁移
验证证据: harness 自测 15 项 + runner 自测 13 项通过；静态审计 32 Skill / 0 问题；
73 个非数据库测试通过；8 个集成条目中 6 个 PostgreSQL 项被依赖门明确阻断；
py_compile 与 git diff --check 通过。未连接 PostgreSQL、网络、真实模型或额度。
已知边界: 真正 skill_behavior_eval 仍为 0，尚未验证任何 Skill 自然语言行为；
evaluate-frozen-replay 的 raw 存储边界冲突留待单独治理。
72 lines
4.4 KiB
Markdown
72 lines
4.4 KiB
Markdown
---
|
||
name: maintain-work-extraction
|
||
description: 维护既有 upgrade_book 抽取状态，包括七域备份验证与恢复、全量重抽前重置、失败窗口恢复、定向数据修复和存量迁移。需要修复或重建作品抽取结果时使用；不负责正常按窗抽取。
|
||
disable-model-invocation: true
|
||
---
|
||
|
||
# 维护作品知识抽取
|
||
|
||
何时用：作品的 `upgrade_book` 派生状态需要备份、恢复、重置、定向修复或存量迁移。正常 `windows/run/status` 属于 `extract-work-knowledge`。
|
||
|
||
## 依赖边界
|
||
|
||
维护命令复用 `extract-work-knowledge/scripts/upgrade.py` 的修复算法和 `upgrade_work_lock.py` 的同书锁，不复制第二套数据库补偿逻辑。`upgrade_book`、`upgrade-reset`、`parse_upgrade.py` 等字符串是存量数据库或备份清单的兼容键，不随 Skill 改名。
|
||
|
||
## 维护入口
|
||
|
||
| 入口 | 用途 |
|
||
|---|---|
|
||
| `scripts/backup_upgrade_work.py` | 七域一致性 `backup/verify/rehearse/restore`。 |
|
||
| `scripts/reset_upgrade_work.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` | 存量回洗工具；是否退役由现有数据状态决定。 |
|
||
|
||
## 同书互斥
|
||
|
||
重置预览/执行、备份、演练、恢复和所有写修复均使用 `extract-work-knowledge` 的 PostgreSQL session advisory lock。取锁失败时必须在业务 SQL、文件验证、嵌入或模型调用前非零退出；`status` 不属于本 Skill。
|
||
|
||
## 备份与恢复合同
|
||
|
||
`reset --execute` 前必须用一个 `REPEATABLE READ READ ONLY` 事务导出本书七域状态，并从磁盘独立复验。备份目录必须是 `/private/tmp` 下尚不存在的新目录。清单绑定数据库 identity、Canonical 章节与 block、窗口边界、活动字段合同、计划参数和实际代码 fileSha。
|
||
|
||
备份清单中的 `parse_upgrade.py`、`parse-book/SKILL.md` 等逻辑键保持不变，以便存量备份继续离线验证；真实路径分别指向当前 `extract-work-knowledge` 与 `deconstruct-book` 文件。
|
||
|
||
恢复前固定执行离线 `verify`。`rehearse` 在真实表的单事务中应用并强制回滚；`restore --execute` 必须精确匹配 `backup_id + confirmationSha`，逐域读回后才提交。任何 work、tenant、数据库 identity、Canonical、窗口、合同或代码漂移均拒绝。
|
||
|
||
```bash
|
||
.venv/bin/python .claude/skills/maintain-work-extraction/scripts/backup_upgrade_work.py backup \
|
||
--work-id 8 --expected-chapters 594 --expected-windows 116
|
||
.venv/bin/python .claude/skills/maintain-work-extraction/scripts/backup_upgrade_work.py verify \
|
||
--backup-dir /private/tmp/muse-upgrade-work8-before-reset
|
||
.venv/bin/python .claude/skills/maintain-work-extraction/scripts/backup_upgrade_work.py rehearse \
|
||
--work-id 8 --backup-dir /private/tmp/muse-upgrade-work8-before-reset \
|
||
--confirmation-sha <manifest-confirmationSha>
|
||
```
|
||
|
||
## 重置与定向修复
|
||
|
||
reset 软删目标 `upgrade_book` 草稿和无 Canonical owner 的活向量，窗口保留并回到 `pending`；别名、presence、card state 和 audit 按既有约束清理。执行时须持同书锁、复验备份和代码身份，并在固定表锁顺序内完成单事务重置；任一断言失败整体回滚。
|
||
|
||
```bash
|
||
# 只读预览
|
||
.venv/bin/python .claude/skills/maintain-work-extraction/scripts/reset_upgrade_work.py --work-id 8
|
||
|
||
# 真重置
|
||
.venv/bin/python .claude/skills/maintain-work-extraction/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>
|
||
|
||
# 定向维护命令
|
||
.venv/bin/python .claude/skills/maintain-work-extraction/scripts/maintenance.py \
|
||
recover-legacy-failed --work-id 8 --window-no 7 --preview
|
||
```
|
||
|
||
定向修复必须先 preview，execute 精确匹配 preview 的确认 SHA，并显式确认没有同书活进程。修复范围、行集合、revision、payload、owner 或关联状态任一漂移都失败关闭。
|
||
|
||
## 数据边界
|
||
|
||
- 备份与 preview 默认只读；execute 只修改目标租户、目标作品、`upgrade_book` 边界内的派生状态。
|
||
- 不生成新抽取内容，不提供正常 `run/windows/status`。
|
||
- `migrate_upgrade_windows.py` 当前只输出迁移计划，不落库；真实写入仍需另行 gate 与授权。
|