wq-migrate

> 依赖 wq-rules，默认quiet 模式。

旧项目迁移与规整

触发关键词规整项目、迁移旧项目、补齐缺失文件、检查项目完整性、修复项目结构、升级项目格式、旧项目升级、项目检查、查缺补漏、项目规范化

核心功能

1. 项目扫描：全面扫描现有项目结构，识别文件缺失和字段问题2. 路径迁移：旧路径自动迁移到新 canonical 路径
2. 配置补齐：生成缺失的 .sumeru/project.json、status.json 等配置文件4. 目录补齐：创建缺失的目录结构
3. 字段补全：补齐章节任务卡缺失的必填字段6. *人物卡生成：从大纲中提取人物信息生成人物卡
4. 迁移报告：生成详细的迁移报告

使用方式

/wq-migrate                    # 完整迁移检查与修复
/wq-migrate 仅检查            # 只检查不修复
/wq-migrate 仅迁移路径        # 只迁移旧路径
/wq-migrate 补齐配置           # 只补齐配置文件/wq-migrate 补齐人物卡        # 只生成缺失的人物卡```

---

## 一、迁移检查清单
### 1.1 项目配置检查
| 检查项 | 修复方式 |
|--------|----------|
| `.sumeru/project.json` 不存在| 根据已有文件推断配置，生成project.json |
| `.sumeru/status.json` 不存在| 扫描 chapters/ 和outlines/ 推断状态|
| `.sumeru/changelog.md` 不存在| 创建空文件|
| `.sumeru/decisions.md` 不存在| 创建空文件|
| `.sumeru/backlog.md` 不存在| 创建空文件|
| `.sumeru/issues.md` 不存在| 创建空文件|

### 1.2 目录结构检查
| 检查项 | 修复方式 |
|--------|----------|
| `chapters/` 不存在| 创建空目录|
| `characters/` 不存在| 创建空目录|
| `outlines/` 不存在| 创建空目录|
| `publish/` 不存在| 创建空目录|
| `.sumeru/cache/` 不存在| 创建空目录|
| `.sumeru/context-packs/` 不存在| 创建空目录|
| `.sumeru/continuity/` 不存在| 创建空目录|
| `.sumeru/volumes/` 不存在且 chapters ≥ 150 | 提示用户进入「分卷迁移」模式（见第十部分）；非分卷模式可忽略 |
| `.sumeru/cross-volume/` 不存在且启用分卷模式 | 按 outline.md 推断并初始化（见第十部分·c） |

### 1.3 旧路径迁移检查
| 旧路径| 新路径| 迁移方式 |
|--------|--------|----------|
| `.sumeru/outline/chapter-outlines.json` | `outlines/chapters.json` | 读取旧文件，合并到新文件 |
| `.sumeru/issues/index.json` | `.sumeru/issues.md` | 读取旧JSON，转换为 Markdown |
| `docs/requirements.md` | `plan.md` | 读取旧文件，合并到plan.md |
| `docs/glossary.md` | `plan.md` 术语补| 合并到plan.md 术语部分 |
| `docs/style-guide.md` | `.sumeru/cache/style-brief.md` | 转换为缓存格式|
| `ideas/*` | `plan.md` | 合并创意到plan.md |

### 1.4 章节任务卡字段检查
`outlines/chapters.json` 每章必须包含以下 15 个必填字段：

| 字段 | 说明 |
|------|------|
| `chapter` | 章节及|
| `title` | 章节标题 |
| `purpose` | 本章核心作用 |
| `events` | 核心事件列表（≥3项） |
| `openingHook` | 具体开场方式|
| `outputs` | 必须产出内容 |
| `acceptanceCriteria` | 验收条件 |
| `creativeGoal` | 创意目标 |
| `freshnessHook` | 新鲜感来源|
| `emotionalBeat` | 情绪走向 |
| `emotionalBeatTemplate` | 情绪模板ID |
| `readerMemoryPoint` | 读者记忆点 |
| `tropeToAvoid` | 要避开的套路|
| `protectedElements` | 底线元素 |
| `rhythm` | 节奏（fast/medium/slow：|

**修复方式**：- 缺字段→件`.sumeru/outline/chapter-XXX-YYY.md` 回退补充
- 无回退源→从大纲和已有章节推断，标记为 `auto-generated`

### 1.5 人物卡检查
| 检查项 | 修复方式 |
|--------|----------|
| `characters/` 目录为空 | 件`plan.md` 和`outline.md` 提取人物信息生成 |
| 人物卡缺少必要字段| 补齐：姓名、年龄、身份、核心性格、人物弧关|
| 人物卡与大纲不一致 | 以大纲为准，更新人物卡 |

### 1.6 伏笔管理检查
| 检查项 | 修复方式 |
|--------|----------|
| `outline.md` 缺少伏笔管理补| 从已有章节提取伏笔，生成管理补|
| 伏笔缺少 ID | 自动分配 ID（F1、F2...：|
| 伏笔缺少预期回收位置 | 根据剧情推断，标记为 `待规划` |

### 1.7 章节状态检查
| 检查项 | 修复方式 |
|--------|----------|
| 章节文件缺少 SUMERU_STATUS 标记 | 扫描章节内容推断状态，添加标记 |
| status.json 与实际章节不一致 | 以实际章节为准，更新 status.json |
| 章节命名不规范| 提示用户手动重命启|

### 1.8 接续文件检查（v1.3.0 新增）
> **目的**：检查 `wq-worldbuilder` 恢复所需的前置文件是否齐全。
> **范围**：仅完整迁移模式执行；`仅检查` 模式也执行此段以输出诊断报告。
> **详细处理规则**：见「第十二、接续协议」。

| 检查项 | 模式 | 缺失时 |
|--------|------|--------|
| `.sumeru/creative-anchors.md` | 全部 | 进入 H1：从 plan.md + outline.md 推断 5-7 个锚点，标记 `pending` |
| `.sumeru/intro.md` | 全部 | 进入 H2：推断生成 300-500 字简介，标记 `pending` |
| `.sumeru/status.json.migrationHandoff` | 全部 | 进入 H3：写入 handoff 字段 |
| `.sumeru/context-packs/` | long/full | 进入 H4：初始化空目录 |
| `.sumeru/continuity/consistency-rules.json` | long/full | 进入 H5：从章节 `SUMERU_STATUS.state_diff` 合并重建 |
| `chapters/*.md` 中 `SUMERU_STATUS` 标记 | 全部 | 进入 H6：按内容/mtime 推断状态后补写 |
| `outlines/chapters.json` 字段完整性 | 全部 | 已在 1.4 处理；接续阶段不再重复 |
| `characters/*.md` 字段完整性 | 全部 | 已在 1.5 处理；接续阶段不再重复 |

**与 1.1-1.7 的区别**：
- 1.1-1.7 解决"文件是否齐全 / 字段是否完整"——属于**文件层**整顿
- 1.8 解决"恢复所需文件是否就绪"——属于**流程层**接续
- 1.8 的处理全部进入第五阶段「接续准备」执行，不阻塞第三阶段「执行迁移」

### 1.9 分卷结构检查（v1.3+ 新增）
> **目的**：检测项目是否需要/已启用分卷模式，并执行对应的目录初始化。
> **触发条件**：`chapters/` 文件数 ≥ 150，或 `outline.md` 显式声明分卷数 ≥ 2。
> **详细处理规则**：见「第十部分·分卷迁移」与 `wq-rules/SKILL.md` 第十五部分·分卷隔离与卷切换协议。

| 检查项 | 修复方式 |
|--------|----------|
| 扁平项目但 chapters ≥ 150 | 仅提示用户「建议升级为分卷模式」，不强制执行；用户需主动调用 `/wq-migrate 分卷迁移` 才会进入第十部分 |
| 分卷模式但缺少 `volumes/` 目录 | 按 chapters 数量和卷大小（150-250 章/卷）计算分卷方案，创建 `.sumeru/volumes/` 并初始化 `vol-001/` 子目录 |
| 分卷模式但缺少 `cross-volume/` | 从已有数据（`characters/`、`outline.md` 跨卷依赖表、`continuity/`）推断并初始化（见第十部分·c） |
| 扁平 `outlines/chapters.json` 含 150+ 章 | 提供可选子模式：将全局 chapters.json 按卷拆分到 `vol-N/outlines/chapters.json`（per-volume 优先级 > 全局）；如用户拒绝则保留单一来源 |

**与 1.8 的区别**：
- 1.8 是"接续协议"，保证 `worldbuilder` 能恢复上次创作
- 1.9 是"分卷结构协议"，保证分卷模式下数据按卷隔离且跨卷依赖可查
- 1.9 仅在用户调用 `分卷迁移` 或主动启用分卷模式时执行；完整迁移流程中默认跳过

---

## 二、迁移流程

用户调用 /wq-migrate
│
├─[第一阶段：项目扫描]
│ ├─ 扫描目录结构
│ ├─ 识别旧路径
│ ├─ 检查配置文件
│ └─ 检查章节任务卡字段
│
├─[第二阶段：生成迁移计划]
│ ├─ 列出需要修复的项目
│ ├─ 按优先级排序
│ └─ 询问用户确认
│
├─[第三阶段：执行迁移]
│ ├─ 迁移旧路径
│ ├─ 补齐配置文件
│ ├─ 补齐目录结构
│ ├─ 补齐章节任务卡字段
│ └─ 生成人物卡
│
├─[第四阶段：生成报告]
│ ├─ 迁移报告
│ ├─ 更新 status.json
│ └─ 记录 changelog
│
└─[第五阶段：接续准备] ⭐ v1.3.0 新增
├─ 补做 creative-anchors.md（H1）
├─ 补做 intro.md（H2）
├─ 写入 migrationHandoff 字段（H3）
├─ 初始化 context-packs/（H4，仅 long/full）
├─ 重建 consistency-rules.json（H5，仅 long/full）
└─ 补全章节 SUMERU_STATUS 标记（H6）
→ 详见「第十二、接续协议」

└─[第六阶段：分卷迁移] ⭐ v1.3+ 新增（可选，仅在分卷模式时执行）
    ├─ 计算卷大小与分卷方案
    ├─ 创建 .sumeru/volumes/vol-N/ 子目录
    ├─ 初始化 vol-N/continuity/ 与 vol-N/cache/batch-summaries/
    ├─ 初始化 .sumeru/cross-volume/ 三份文档
    ├─ 可选：拆分 outlines/chapters.json 到 per-volume
    └─ 更新 project.json（volumeCount / currentVolume / volumes[]）
    → 详见「第十部分·分卷迁移」

**模式区别：**
- **仅检查 / 仅迁移路径 / 补齐配置 / 补齐人物卡**：执行到第三阶段相应子任务即结束，**不进入第五阶段**
- **完整迁移**（无子参数）：必须执行全五阶段；第五阶段任意子步骤失败时，整体标记为 `partial`，详见 12.7
- **分卷迁移**（`分卷迁移` 子参数或 chapters ≥ 150 且用户确认）：在前述模式完成后额外执行第六阶段；详见「第十部分·分卷迁移」

---

## 三、project.json 推断规则

当`.sumeru/project.json` 不存在时，根据已有文件推断：

| 推断来源 | 推断字段 |
|----------|----------|
| `plan.md` 标题 | `title` |
| `plan.md` 类型标签 | `genre` |
| `plan.md` 受众定位 | `audience` |
| `plan.md` 目标平台 | `targetPlatform` |
| `outline.md` 分卷数| `plannedChapters` |
| `chapters/` 已有文件 | `currentStage` |
| 章节平均字数 | `chapterWordRange` |

**推断不出的字段*：使用默认值，标记不`pending`。
---

## 四、status.json 推断规则

当`.sumeru/status.json` 不存在时，根据已有文件推断：

| 推断来源 | 推断逻辑 |
|----------|----------|
| `chapters/` 文件数量 | 已完成章节数 |
| 章节首行 SUMERU_STATUS | 章节状态（drafted/polished/finalized：|
| `.sumeru/reviews/` 是否存在 | 是否经过审查 |
| `publish/` 是否存在 | 是否已导准|

---

## 五、旧路径迁移详细规则

### 5.1 chapter-outlines.json →chapters.json

```javascript
// 迁移逻辑
1. 读取 .sumeru/outline/chapter-outlines.json
2. 解析每个章节的基本信息（chapter, title, purpose, events：3. 缺少的必填字段标记为 "待补关
4. 写入 outlines/chapters.json
5. 备份旧文件到 .sumeru/backup/

5.2 issues/index.json →issues.md

# 迁移逻辑
1. 读取 .sumeru/issues/index.json
2. 按严重程度分类3. 转换不Markdown 格式
4. 写入 .sumeru/issues.md
5. 备份旧文件到 .sumeru/backup/

5.3 docs/ →plan.md

# 迁移逻辑
1. 读取 docs/requirements.md（需求）
2. 读取 docs/glossary.md（术语）
3. 读取 docs/style-guide.md（风格）
4. 合并到plan.md 对应章节
5. 备份旧文件到 .sumeru/backup/

六、人物卡生成规则

件plan.md 和outline.md 提取人物信息：

提取来源

1. plan.md 人物设定部分
2. outline.md 主要人物列表
3. outline.md 人物关系描述
4. 已有章节中的人物描写

生成格式

# {人物名}

## 基础信息
- **姓名**：{从大纲提取}
- **年龄**：{从大纲提取或推断}
- **身份**：{从大纲提取}
- **外貌特征**：{从章节描写提取，或标认待补关}

## 性格画像
- **核心性格**：{从大纲提取}
- **说话风格**：{从章节对话提取，或标认待补关}
- **行为习惯**：{从章节描写提取，或标认待补关}
- **内在矛盾**：{从大纲推断，或标认待补关}

## 人物弧光
- **起点状态*：{从大纲提取}
- **关键转折**：{从大纲提取}
- **终点状态*：{从大纲提取}

## 核心驱动功- **核心欲望**：{从大纲提取}
- **核心恐惧**：{从大纲推断}

## 人物关系
| 对象 | 关系 | 当前状态|
|------|------|----------|
| {从大纲提取} | {从大纲提取} | {从大纲提取} |

## 战力/能力
- **能力等级**：{从大纲提取或推断}
- **特殊技能*：{从大纲提取}

## 人物标签
`#{类型}` `#{单阶段}`

七、迁移报告格式

# 项目迁移报告

## 迁移概要
- **迁移时间**：{timestamp}
- **项目名称**：{title}
- **迁移模式**：{完整迁移/仅检查仅迁移路径}

## 检查结果
### 项目配置
| 项目 | 状态| 说明 |
|------|------|------|
| project.json | ✅已存在/ 🔧 已生成/ ✗生成失败 | {说明} |
| status.json | ✅已存在/ 🔧 已生成| {说明} |

### 目录结构
| 目录 | 状态|
|------|------|
| chapters/ | ✅已存在/ 🔧 已创建|
| characters/ | ✅已存在/ 🔧 已创建|
| outlines/ | ✅已存在/ 🔧 已创建|

### 旧路径迁移| 旧路径| 新路径| 状态|
|--------|--------|------|
| .sumeru/outline/chapter-outlines.json | outlines/chapters.json | ✅已迁移/ ⚠️ 需手动处理 |

### 章节任务单| 章节 | 缺失字段 | 状态|
|------|----------|------|
| 001 | 旧| ✅完整 |
| 002 | openingHook, freshnessHook | 🔧 已补关/ ⚠️ 待补关|

### 人物卡| 人物 | 状态|
|------|------|
| 主角 | ✅已生成|
| 反派 | ⚠️ 待补充详情|

### 接续准备（v1.3.0 新增）
| 步骤 | 文件 | 状态 | 备注 |
|------|------|------|------|
| H1 anchor | `.sumeru/creative-anchors.md` | ✅已推断 / ⏭️skipped / ❌失败 | {n} 个锚点,全部 `pending` |
| H2 intro | `.sumeru/intro.md` | ✅已推断 / ⏭️skipped / ❌失败 | 字数 {n} |
| H3 handoff | `status.json.migrationHandoff` | ✅已写入 / ❌失败 | 写入 `recommendedNext` |
| H4 context-packs | `.sumeru/context-packs/` | ✅已初始化 / ⏭️非 long/full / ❌失败 | — |
| H5 continuity | `.sumeru/continuity/consistency-rules.json` | ✅已重建 / ⏭️非 long/full / ❌失败 | 合并 {n} 章 state_diff |
| H6 chapter status | `chapters/*.md` 标记补全 | ✅全部已补 / ⚠️部分已补 / ❌失败 | 补 {a} / 共 {b} |

**整体接续状态**：`ready`（可恢复） / `partial`（部分完成，需用户介入） / `failed`（未完成接续）

## 待办事项
- [ ] {需要用户手动处理的事项}

## 续作建议（v1.3.0 新增）⭐

> **完整迁移模式必出本段**；`仅检查` / `仅迁移路径` / `补齐配置` / `补齐人物卡` 模式可省略。

### ✅ 项目已就绪（ready 状态时）

你的项目已完成迁移，可使用新技能继续创作。

**第一步（推荐）**：校对推断的简介
```bash
cat .sumeru/intro.md      # 校对
# 不满意直接编辑，下次 finalize 会使用新版本

第二步（推荐）：确认创意锚点

/wq-worldbuilder 恢复上次创作
# 系统会按 migrationHandoff 字段：
#   - 跳过 topic / outline 阶段
#   - 进入"锚点确认"流程（pending 锚点逐条确认）
#   - 确认后自动进入 write 续作

第三步：续作
- 续写："续写第N章"
- 重写："重写第N章"
- 全审："审查全部"
- 润色："润色第X-Y章"

⚠️ 项目部分就绪（partial 状态时）

迁移过程中部分接续步骤失败，需用户介入：

最小恢复命令：

/wq-worldbuilder 恢复上次创作
# 恢复时会检测到 partial 状态，逐项提示用户补做

❌ 项目未就绪（failed 状态时）

接续协议关键步骤失败，项目不可直接恢复。建议：
1. 检查 .sumeru/migration.json 中 errors 字段
2. 手动补做失败步骤
3. 重新运行 /wq-migrate 单独补做

当前项目快照

---

## 八、数据持久化

**用户可见输出**：- `migration-report.md`：迁移报命
**中间数据**：- `.sumeru/backup/`：旧文件备份
- `.sumeru/migration.json`：迁移记当

**分卷迁移中间数据**（仅在第六阶段执行时生成）：
- `.sumeru/volumes/vol-N/continuity/consistency-rules.json`：每卷独立一致性规则（空 schema）
- `.sumeru/volumes/vol-N/continuity/batch-summaries/`：每卷批次摘要目录（空）
- `.sumeru/volumes/vol-N/cache/batch-summaries/`：每卷缓存批次摘要（空）
- `.sumeru/volumes/vol-N/outlines/chapters.json`：每卷章节任务卡（可选拆分，按用户确认）
- `.sumeru/cross-volume/master-characters.md`：全局人物索引
- `.sumeru/cross-volume/master-timeline.md`：全局时间线主干
- `.sumeru/cross-volume/dependency-table.md`：跨卷依赖表

**`project.json` 增量字段**（分卷迁移后追加，**不修改**既有字段）：
- `volumeCount`：分卷数（≥ 2 时启用分卷隔离）
- `currentVolume`：当前活跃卷 ID（默认 `"vol-001"`）
- `volumes[vol-N]`：卷详情映射（`title` / `chapterRange` / `status`）
---

## 九、与其他 Skill 配合

- **前置**：无（可直接调用：- **后续**：迁移完成后可继续使生`wq-worldbuilder` 恢复创作，或使用其他 Skill 继续

---

## 十、分卷迁移（Volume Migration，v1.3+ 新增）

> **目标**：将扁平项目升级为分卷模式，或为已分卷项目补齐分卷基础设施。
> **具体规范**：分卷数据模型、目录结构、激活/降级规则详见 `wq-rules/SKILL.md` 第十五部分·分卷隔离与卷切换协议；本节仅描述迁移阶段的执行流程。

### 10.1 触发条件

分卷迁移作为**子模式**触发，不会自动执行：

| 触发方式 | 说明 |
|----------|------|
| 显式调用 `/wq-migrate 分卷迁移` | 用户主动请求升级为分卷模式 |
| 显式调用 `/wq-migrate 启用分卷` | 同上，语义别名 |
| 1.9 检查项触发 | 完整迁移过程中检测到 `chapters/` ≥ 150 且 `volumes/` 缺失，**仅提示**，不自动执行；需用户回复确认才会进入本节 |
| `outline.md` 显式声明分卷数 ≥ 2 | 同上，仅提示 |

**与第五阶段接续协议的关系**：分卷迁移是**独立的可选阶段**（第六阶段），不强制与接续协议联动。但完整迁移流程推荐顺序为：先执行第五阶段补做 anchor/intro，再执行第六阶段分卷初始化。

### 10.2 迁移流程

进入分卷迁移模式
│
├─[A. 扫描与方案计算]
│ ├─ 统计 chapters/ 文件数（总章节数 N）
│ ├─ 读取 outline.md 分卷规划（如有）
│ ├─ 计算卷数：volumeCount = ceil(N / 200)（按目标 200 章/卷，区间 150-250）
│ ├─ 计算每卷章节区间（连续分配）：
│ │ vol-001: 1 ~ ceil(N/volumeCount)
│ │ vol-002: ... ~ ...
│ │ vol-K: ... ~ N
│ ├─ 读取 outline.md 跨卷依赖表（如有）
│ └─ 生成迁移方案 → 询问用户确认
│
├─[B. 卷目录创建]
│ ├─ 创建 .sumeru/volumes/
│ ├─ 对每个 vol-N 创建：
│ │ .sumeru/volumes/vol-N/continuity/
│ │ .sumeru/volumes/vol-N/continuity/batch-summaries/
│ │ .sumeru/volumes/vol-N/cache/
│ │ .sumeru/volumes/vol-N/cache/batch-summaries/
│ │ .sumeru/volumes/vol-N/outlines/ （可选，按 D 执行）
│ ├─ 初始化 vol-N/continuity/consistency-rules.json：
│ │ {"schemaVersion": "1.3", "volumeId": "vol-N",
│ │ "chapterRange": [<start>, <end>], "rules": [], "stateDiff": []}
│ └─ vol-N/cache/batch-summaries/ 保持空（待后续批次写入）
│
├─[C. 跨卷基础设施创建]
│ ├─ 创建 .sumeru/cross-volume/
│ ├─ 创建 master-characters.md（见 10.4.a）
│ ├─ 创建 master-timeline.md（见 10.4.b）
│ └─ 创建 dependency-table.md（见 10.4.c）
│
├─[D. chapters.json 拆分（可选）]
│ ├─ 询问用户：是否将 outlines/chapters.json 按卷拆分到 per-volume 副本？
│ ├─ 用户同意：
│ │ ├─ 按 chapterRange 切片
│ │ ├─ 写入 vol-N/outlines/chapters.json
│ │ └─ 保留根级 outlines/chapters.json 作为单一来源（per-volume 是缓存镜像）
│ └─ 用户拒绝：保持单一全局文件不变
│
├─[E. project.json 更新]
│ ├─ 写入 volumeCount = K
│ ├─ 写入 currentVolume = "vol-001"（首个活跃卷）
│ ├─ 写入 volumes 映射：
│ │ "volumes": {
│ │ "vol-001": {"title": "<从 outline.md 提取或占位>",
│ │ "chapterRange": [<start>, <end>],
│ │ "status": "planned"},
│ │ ...
│ │ }
│ └─ 不修改 existing fields（保留 title/genre/audience 等）
│
└─[F. 报告与变更记录]
├─ 迁移报告追加「分卷迁移结果」段
├─ 写入 changelog.md
└─ 更新 status.json（currentVolume 字段保持兼容；不修改 chapterStatus 字段）

### 10.3 卷大小与分配规则

| 参数 | 取值 | 说明 |
|------|------|------|
| 目标卷大小 | 200 章/卷 | 推荐值 |
| 最小卷大小 | 150 章/卷 | 低于此值不切分 |
| 最大卷大小 | 250 章/卷 | 超出此值强制切分 |
| 分配方式 | 连续区间 | `vol-001: [1, a]`, `vol-002: [a+1, b]`, ... 末卷补齐余数 |
| 边界对齐 | 优先 outline.md | 若 outline.md 已声明分卷章节段，**优先采用用户声明**，跳过自动计算 |

### 10.4 跨卷数据生成规则

#### a. `master-characters.md`

从以下来源汇总人物状态：

| 来源 | 提取内容 |
|------|----------|
| `characters/*.md` | 全局人物基础信息（姓名、身份、当前状态） |
| `outline.md` 人物表 | 人物在各卷的出场规划 |
| `.sumeru/continuity/` | 人物状态快照（如有） |

格式：

```markdown
# 全局人物索引（Master Characters）

> 生成时间：{timestamp}
> 来源：characters/, outline.md, .sumeru/continuity/
> 状态：⚠️ pending（迁移自动生成，待用户校对）

| # | 人物 | 当前卷 | 状态 | 关键转折 | 出场章节 |
|---|------|--------|------|----------|----------|
| 1 | {name} | vol-001 | active | {arc point} | {range} |
| ... |

b. master-timeline.md

从 outline.md 的章节规划生成卷级时间线骨架：

# 全局时间线主干（Master Timeline）

> 生成时间：{timestamp}
> 来源：outline.md 分卷规划

| 卷 | 章节范围 | 时间锚点 | 关键事件 | 跨卷承诺 |
|----|----------|----------|----------|----------|
| vol-001 | 1-200 | {从大纲提取} | {从大纲提取} | — |
| vol-002 | 201-400 | {从大纲提取} | {从大纲提取} | {来自 vol-001 的承诺} |
| ... |

回退：若 outline.md 无时间线信息，骨架仅含章节范围与卷标题，时间锚点列填 待规划。

c. dependency-table.md

仅当 outline.md 显式包含「跨卷依赖表」段时提取；否则创建空模板：

# 跨卷依赖表（Dependency Table）

> 生成时间：{timestamp}
> 来源：outline.md 跨卷依赖表 / [empty]

| ID | 源卷 | 目标卷 | 类型 | 描述 | 状态 |
|----|------|--------|------|------|------|
| D001 | vol-001 | vol-002 | 伏笔 | {从大纲提取} | pending |
| ... |

10.5 chapters.json 拆分策略

核心原则：outlines/chapters.json（全局）始终是单一真相源（single source of truth）；vol-N/outlines/chapters.json 是按卷镜像缓存。

优先级规则（在 wq-write / wq-review 读取时）：
1. 如 vol-N/outlines/chapters.json 存在 → 优先使用（per-volume）
2. 否则回退到全局 outlines/chapters.json 并按 chapter 字段过滤

拆分方式：

// 伪代码
const globalChapters = readJSON('outlines/chapters.json');
for each vol-N in volumePlan:
  const range = volumes[vol-N].chapterRange;
  const slice = globalChapters.filter(c => c.chapter >= range[0] && c.chapter <= range[1]);
  writeJSON(`vol-N/outlines/chapters.json`, slice);

不拆分场景：用户拒绝、章节数 < 200、或 outlines/chapters.json 字段不完整（先执行 1.4 字段补全）。

10.6 迁移报告「分卷迁移结果」段

分卷迁移完成后，在 migration-report.md 追加：

## 分卷迁移结果

| 卷 | 章节范围 | 状态 | continuity | cache | chapters.json |
|----|----------|------|------------|-------|----------------|
| vol-001 | 1-200 | planned | ✅已初始化 | ✅已初始化 | ✅已拆分 / ⏭️保持全局 |
| vol-002 | 201-400 | planned | ✅已初始化 | ✅已初始化 | ✅已拆分 / ⏭️保持全局 |
| ... |

### 跨卷基础设施
- `.sumeru/cross-volume/master-characters.md`：{n} 个人物
- `.sumeru/cross-volume/master-timeline.md`：{k} 个时间锚点
- `.sumeru/cross-volume/dependency-table.md`：{m} 条依赖 / [empty]

### project.json 更新
- `volumeCount`: 0 → {K}
- `currentVolume`: "" → "vol-001"
- `volumes`: 新增 {K} 条记录

10.7 失败处理

10.8 与其他阶段的关系

重要约束：
- 不移动 chapters/*.md 文件到卷目录（卷目录仅放 continuity/cache/outlines）
- 不修改 status.json 的 chapterStatus 字段（分卷后由 wq-worldbuilder 在卷切换时自动管理 vol-N/status.json）
- 不修改 H1-H6 接续协议字段（migrationHandoff 不含分卷信息）

十一、独立调用说明

1. 定位项目根目录2. 执行项目扫描
2. 生成迁移计划
3. 询问用户确认
4. 执行迁移
5. 生成报告
6. 更新 status.json 和changelog

十二、接续协议（Handoff Protocol）

> 目标：确保 wq-migrate 完成后，项目处于"可被 wq-worldbuilder 恢复"的就绪状态。
> 适用版本：v1.3.0 起。
>
> 与 v1.2 的区别：v1.2 仅完成"文件规整"即结束；v1.3 必须额外完成"接续准备"（补做 anchor / intro / handoff 标记）才算完成迁移。

12.1 为什么需要接续协议

老/不完整项目迁移后存在三个隐藏缺口，必须在迁移阶段补齐，否则 worldbuilder 恢复上次创作 会失准：

1. 缺失 creative-anchors.md（1.2.0 新增阶段）：写作子 Agent 拿不到锚点，章节一致性退化。
2. 缺失 intro.md（1.2.0 升级为必填）：finalize / publish 阶段可能跳过简介注入。
3. 缺失 migrationHandoff 标记：worldbuilder 无法判断"项目是否经过 migrate"，会按全新项目初始化导致覆盖风险。

12.2 接续检查清单（强制执行）

完整迁移（/wq-migrate 不带子参数）必须在「生成报告」之后依次执行以下步骤，缺一不可：

12.3 anchor 补做规则（H1 详细）

creative-anchors.md 是 1.2.0 新增的不可违背创意基准。老项目没有这个文件时，不能跳过、不能直接进入 write，必须按以下规则推断：

推断来源：
- plan.md 的"核心设定"、"金手指"、"核心冲突"段
- outline.md 的"分卷大纲"、"主线"、"人物设定"段
- 已有章节（chapters/*.md）的标题、首段、对话片段

锚点类型（与世界 builder 第 158-188 行锚点定义保持一致）：

输出格式（与 wq-worldbuilder 一致）：

# 创意锚点（Creative Anchors）

> 状态：⚠️ **pending**（迁移推断，待用户确认）
> 生成时间：{timestamp}
> 推断来源：plan.md, outline.md, chapters/*.md

| # | 类型 | 锚点 | 来源 | 状态 |
|---|------|------|------|------|
| 1 | 核心反差 | {推断的锚点} | plan.md §核心设定 | pending |
| 2 | 情感锚 | {推断的锚点} | outline.md §主线 | pending |
| 3 | 设定钩子 | {推断的锚点} | plan.md §世界观 | pending |
| ... | | | | |

## 确认提示
请用 `/wq-worldbuilder {原题材} 锚点确认` 逐条确认、修改或新增，确认后状态从 `pending` 改为 `confirmed` / `user_modified` / `user_added`。

12.4 intro.md 补做规则（H2 详细）

生成模板：

# {作品名}

> 状态：⚠️ pending（迁移推断，待用户校对）
> 字数：{实际字数}（建议 300-500 字）

## 基本信息
- **类型**：{从 plan.md genre 字段}
- **受众**：{从 plan.md audience 字段}
- **目标平台**：{从 plan.md targetPlatform 字段}

## 简介正文
{从 outline.md 主线冲突 + plan.md 困境/转折/冲突/悬念 四要素生成，300-500 字}

## 平台标签
{按 plan.md 关键词映射到 4+ 平台标签}

质量门禁：
- 字数 300-500（短篇可放宽至 200-300）
- 必含四要素：困境 → 转折 → 冲突 → 悬念
- 至少 4 个平台标签

12.5 migrationHandoff 字段格式（H3 详细）

.sumeru/status.json 顶层追加：

{
  "migrationHandoff": {
    "version": "1.3.0",
    "migratedAt": "2026-06-05T12:00:00Z",
    "fromVersion": "1.0.0",
    "migratedBy": "wq-migrate",
    "anchorStatus": "pending",
    "introStatus": "pending",
    "continuityRebuilt": true,
    "recommendedNext": "/wq-worldbuilder 恢复上次创作"
  }
}

worldbuilder 恢复 检测到 migrationHandoff 字段时：
- 跳过 topic / outline 阶段（已完成）
- 跳到 intro 校对（如果 anchorStatus / introStatus 为 pending）
- 然后到 anchor 确认（pending 锚点逐条确认）
- 最后到当前实际章节续作

12.6 续作建议输出格式

迁移报告末尾追加"续作建议"段（完整迁移必出，仅检查/仅迁移路径模式可省）：

## 续作建议（Next Steps）

### ✅ 项目已就绪

你的项目已完成迁移，可使用新技能继续创作。

### 第一步：校对简介（可选）
```bash
# 校对推断生成的简介
cat .sumeru/intro.md
# 满意 → 无需操作
# 需修改 → 直接编辑文件，下次 finalize 会使用新版本

第二步：确认创意锚点（推荐）

/wq-worldbuilder 恢复上次创作
# → 系统会自动进入"锚点确认"流程
# → 逐条确认 pending 锚点
# → 确认后进入续作阶段

第三步：继续创作

锚点确认后系统自动进入 write 阶段。续作规则：
- 续写：直接说"续写第N章"
- 重写某章："重写第N章"
- 全书审查："审查全部"
- 润色："润色第X-Y章"

当前项目快照

### 12.7 失败处理

接续协议任意一步失败的处理：

| 失败步骤 | 处理 |
|----------|------|
| H1 anchor 推断失败（无 plan.md / outline.md） | 跳过 anchor 写入，但 `anchorStatus` 标记为 `skipped`；worldbuilder 恢复时提示用户"需手动建立锚点" |
| H2 intro 推断失败 | 跳过 intro 写入，标记 `skipped`；finalize 阶段检测到无 intro 时给出警告 |
| H3 handoff 字段写入失败 | 整个迁移标记 `partial`；worldbuilder 不会自动接管，需用户手动确认状态 |
| H5 continuity 重建失败（如章节无 SUMERU_STATUS） | 跳过，标记 `skipped`；review 阶段重建 |
| H6 旧章节无状态标记 | 按 H6 规则推断；推断失败 → 标记 `unknown`，worldbuilder 恢复时暂停询问用户 |

### 12.8 与 worldbuilder 的接力协议

`/wq-worldbuilder 恢复上次创作` 检测迁移 handoff 的逻辑：

1. 读取 .sumeru/status.json
2. 检查 migrationHandoff 字段
3. 如果存在：
   a. if anchorStatus == "pending" → 跳到 anchor 确认
   b. elif introStatus == "pending" → 跳到 intro 校对
   c. else → 跳到当前 actualStage
4. 如果不存在：
   a. 检查 .sumeru/migration.json（migrate 旧版产物）
   b. 如果存在 → 提示用户"建议先运行 /wq-migrate 完成接续协议"
   c. 如果不存在 → 按全新项目处理（topic → outline → ...）
   ```

12.9 状态字段语义对照

为避免 migrationHandoff 与 status.json 现有字段冲突，新增字段只增不改：

worldbuilder 读 currentStage 决定主流程，读 migrationHandoff.anchorStatus 决定是否在 anchor 阶段暂停等待确认。两者正交。