章节系统
章节（Chapter）是 NarraFork 的基本工作单元。每个章节对应一个独立的 git worktree，拥有自己的文件空间和 AI 叙述者会话。你可以把它理解为一个「带 AI 上下文的增强版 git 分支」。
章节的生命周期
一个章节从创建到结束，会经历以下状态：
创建 → 活跃（active）
├→ 休眠（dormant）── 唤醒 → 活跃
├→ 已合并（merged）── 唤醒 → 活跃
├→ 已废弃（abandoned）
└→ 已冻结（frozen）- 活跃：正常工作状态，拥有 worktree，可以编辑代码、与 AI 对话
- 休眠：暂时不用的章节。worktree 被删除以节省磁盘空间，但 git 分支和对话历史完整保留，随时可以唤醒
- 已合并：代码已合并到目标章节。如果需要，也可以唤醒继续工作
- 已冻结：拆分操作产生的前序章节，只读状态
- 已废弃：彻底清理，worktree、分支、容器全部删除
NarraFork 还支持自动休眠 —— 当活跃的 worktree 数量超过配置上限时，会按最后访问时间自动休眠最久未使用的章节。
三种角色
每个章节有一个角色标签，用于表达它在项目中的语义定位：
| 角色 | 说明 |
|---|---|
| 主线（trunk） | 项目的主干线，持续演进，接收其他章节的合并。不会被自动休眠 |
| 分支（branch） | 默认角色。从某个章节 fork 出来，完成后合并回去 |
| 探索（exploration） | 用于技术方案探索，可归入探索组进行横向对比 |
角色是语义标签，不限制操作能力 —— 任何角色都可以 fork、merge、cherry-pick。
Fork：分叉一个新章节
Fork 是创建新章节的主要方式。当你从一个章节 fork 时，会发生两件事：
Git 层面：
- 从指定的 commit 点创建新的 git 分支
- 为新分支创建独立的 worktree（位于
<项目>/.worktrees/<章节名>/） - 复制项目配置文件（如
.env等）
AI 上下文层面： fork 时可以选择三种上下文继承模式：
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 完整继承（full） | 新叙述者继承 fork 点之前的完整对话历史 | 需要延续之前的讨论 |
| 压缩继承（compressed） | 自动生成上下文摘要注入新叙述者 | 保留关键信息，节省 token |
| 全新开始（fresh） | 新叙述者从零开始，无历史上下文 | 想换个思路重新来 |
这意味着 fork 不只是代码层面的分支，AI 的记忆也跟着走。
Merge：合并章节
当一个章节的工作完成后，可以合并回目标章节。NarraFork 支持三种合并策略：
- merge：标准三路合并，保留完整的分支历史
- squash：将源分支的所有 commit 压缩为一个
- cherry-pick：逐个挑选 commit 合并
合并前会自动进行冲突检测。如果存在冲突，你可以选择手动解决，也可以让 AI 叙述者辅助分析冲突并给出建议。
NarraFork 还支持批量合并 —— 将多个章节依次合并到同一个目标，遇到冲突时会暂停等待你的决策。
休眠与唤醒
休眠是 NarraFork 的资源管理机制。
休眠时：
- 清理终端会话和文件监视
- 自动提交未保存的更改
- 删除 worktree 目录，释放磁盘空间
- git 分支和所有对话历史完整保留
唤醒时：
- 从 git 分支重建 worktree
- 恢复到休眠前的代码状态
- 对话历史完好无损，可以继续和 AI 叙述者交流
这让你可以同时维护大量章节而不用担心磁盘占用，需要时随时唤醒继续工作。