# 管道运维参考

story-long-analyze 拆解管道的运维工具文档：`_progress.md` 模板、错误处理、恢复机制操作步骤。

> 质量阈值（置信度 / 覆盖率 / 重叠率）见 [material-decomposition.md 质量阈值体系](material-decomposition.md)。

---

## _progress.md 模板

```markdown
# 深度拆解进度：{书名}
- 小说：{标题} | 总章数：{N} | 输出目录：{路径} | 开始：{日期}
- 最终状态：{pending/paused_after_stage1/completed/completed_with_errors}
- schema_version: 2
## 管道进度
| 阶段 | 状态 | 进度 | 备注 |
|------|------|------|------|
## 章节边界（Stage 0.5 产物，唯一权威）
| 章号 | 标题 | 起始行 | 字数 |
|------|------|--------|------|
## 分块进度
| 块 | 章节 | 状态 |
## 失败记录
| 类型 | 章节/阶段 | 错误信息 | 重试状态 |
|------|----------|---------|---------|
## 质量检查
| 检查项 | 阶段 | 结果 | 修正 |
## 角色合并
| 合并前 | 合并后 | 依据 | 确认 |
## 断点
- 最后处理：第{N}章 | 当前阶段 | 下一操作
```

**schema_version 说明**：

| 版本 | 含义 |
|------|------|
| 缺 / 1 | 旧版 `_progress.md`，没有「章节边界」表。续跑时按下方「恢复机制操作步骤」步骤 0 触发 lazy migration |
| 2 | 含「章节边界」表（Stage 0.5 产物）。Stage 1/2/6 全部以该表为切片真值，不再各自跑 regex |

**最终状态值说明**：

| 状态值 | 含义 |
|--------|------|
| `pending` | 管道进行中，尚未跑完 |
| `paused_after_stage1` | Stage 1 停靠点暂停——Stage 0/1 已完成，已产出 `快速预览.md`，等待用户决定是否继续 Stage 2-6。续跑时跳过 Stage 0/1，从 Stage 2 开始 |
| `completed` | 全管道 Stage 0-6 完成 |
| `completed_with_errors` | 全管道完成，但有单章/单阶段失败（详见「失败记录」表，拆文报告中注明） |

---

## 错误处理

| 场景 | 处理 |
|------|------|
| 章节识别失败 | 提示确认格式；支持自定义正则 |
| 分块中断 | 读 _progress.md 断点恢复 |
| 聚合质量不达标 | 孤立情节二次分类；阈值放宽至 0.5 |
| 角色合并冲突 | 记录待确认列表 |
| 输出目录冲突 | 追加不覆盖；冲突标 `[重新分析]` |

---

## 恢复机制操作步骤

0. **schema_version 检测 + 章节边界 lazy migration**（在读取断点前）：
   - 若 `_progress.md` 缺 `schema_version` 字段或值 `< 2` → 视为 v1 旧文件
   - 若同时缺「章节边界」表 → 现场跑一次章节正则（见 `style-profile-generator.md` Step 4 模式）重建该表，按 `| 章号 | 标题 | 起始行 | 字数 |` 写回 `_progress.md`，并把 `schema_version` 升至 `2`
   - 这是 lazy migration——不阻断 resume，旧 `paused_after_stage1` 状态原样保留；用户感知是「续跑前多花 5-10 秒重建一次切片表」
   - 若 regex 也匹配不到任何章节（旧库章节前缀不标准）→ 不强行迁移，记录 `_progress.md` 失败行 `schema_migration: failed: 无法识别章节分隔符`，由用户人工处理
1. 管道启动时检查输出目录是否已有 `_progress.md`
2. 如有，读取断点信息（最后处理章节 + 当前阶段 + 最终状态）
3. **断点状态为 `paused_after_stage1`**（Stage 1 停靠点）→ 跳过 Stage 0/1，直接从 Stage 2 续跑逐章摘要，不重跑已完成的概要与黄金三章
4. 其他断点状态 → 从断点所在块的起始章节恢复，覆盖该块已有输出
