什么是 NarraFork

NarraFork 是一个以「叙事分叉」为核心隐喻的 Web AI 协作编程平台。它将软件开发过程建模为一个不断分叉和汇聚的叙事流 —— 每个工作分支是一个「章节」，每个 AI 助手是一个「叙述者」，而整个项目的演进则构成一张可视化的「叙述线」。

当前状态

NarraFork 目前处于 Alpha 内测阶段，功能和 API 可能随时变动。

为什么做 NarraFork

在使用 AI 辅助编程时，我们经常遇到这些问题：

• 多个方案想并行尝试，但 AI 的上下文在分支切换时丢失了
• 团队协作时，不同成员的 AI 会话各自为战，缺乏关联
• 技术方案的探索过程和决策历史难以追溯
• 想对比两种实现方案的优劣，却没有原生的支持

NarraFork 试图解决这些问题。它把 AI 会话和 git 工作流深度绑定，让每个分支都有自己的 AI 叙述者，保持上下文连贯，同时通过 叙述线 把所有分支的关系串联起来。

核心概念

NarraFork 用叙事隐喻来映射开发中的实体，以下是核心术语与技术实体的对应关系：

NarraFork 术语	对应的技术实体	说明
项目（Project）	Git 仓库	一个项目绑定一个 git 仓库，是所有章节和叙述者的容器
章节（Chapter）	Git 分支 + Worktree	每个章节对应一个独立的 git branch 和 worktree，拥有隔离的文件空间
叙述者（Narrator）	AI 会话	绑定到章节的 AI 对话，维护独立的上下文和消息历史
叙述线	分支关系图	以有向图形式可视化所有章节之间的 fork / merge 关系

一个项目下可以有多个章节，每个章节拥有自己的叙述者。章节 fork 时，叙述者的上下文也可以一并继承，这是 NarraFork 区别于普通 git 工作流的关键。

章节（Chapter）

章节是 NarraFork 的基本工作单元。每个章节对应一个独立的 git worktree，拥有自己的文件系统和 AI 会话。章节有三种角色：

• 主线（trunk） —— 项目的主干，接收其他章节的合并
• 分支（branch） —— 常规工作分支，完成后合并回主线
• 探索（exploration） —— 用于技术方案探索和对比，不一定会合并

章节之间可以进行 fork、merge、cherry-pick 等操作，和 git 的工作方式一脉相承，但多了 AI 上下文的继承。

叙述者（Narrator）

叙述者是绑定到章节的 AI 会话。你可以自行选择和配置 AI 来源。叙述者的特点：

• 拥有章节的完整上下文，理解当前代码状态
• 支持会话分叉 —— 从某个对话节点分出新的对话线
• 支持上下文继承 —— fork 章节时可以选择继承方式（完整 / 压缩 / 全新）
• 流式输出，工具调用需要权限审批

叙述线

叙述线 是项目的全局视图，以交互式有向图的形式展示所有章节及其关系。你可以在这里看到：

• 哪些章节从哪里分叉出来
• 哪些章节已经合并、哪些还在进行中
• 章节之间的依赖和 cherry-pick 关系

这让项目的演进历史一目了然，也方便团队成员快速了解全局。

探索组（Exploration Group）

当你想对比多种技术方案时，可以创建一个探索组。把几个探索章节归到同一组里，方便横向对比不同实现的优劣，最终选定一个方案合并回主线。

架构概览

NarraFork 采用前后端分离架构，支持小团队私有化部署：

┌─────────────────────────────────┐
│           浏览器前端              │
│   React 19 · Mantine · xterm.js │
│   React Flow · TanStack Router  │
└──────────────┬──────────────────┘
               │ HTTP / WebSocket
┌──────────────┴──────────────────┐
│           后端服务               │
│     Bun · Hono · SQLite         │
│   Git Worktree · AI SDK         │
│      Podman（可选）              │
└─────────────────────────────────┘

• 前端：基于 React 19 和 Mantine 组件库，使用 React Flow 渲染 叙述线 图，xterm.js 提供终端模拟
• 后端：运行在 Bun 上，使用 Hono 框架提供 API，SQLite 存储数据，通过 git worktree 管理章节的文件隔离
• AI 集成：通过 SDK 对接 AI 服务，支持 MCP 工具协议
• 部署方式：安装后本地运行，通过浏览器访问，适合小团队私有部署

主要功能

功能	说明
项目管理	创建、配置、归档项目
章节管理	创建、fork、merge、休眠 / 唤醒章节
AI 对话	流式对话、权限审批、消息分支
叙述线	交互式可视化章节关系图
终端集成	在章节中直接运行命令
套路系统	Skills & Routines，复用技能和命令
探索组	技术方案对比和决策
国际化	支持英文和简体中文

适合谁

NarraFork 目前面向小团队私有部署场景。如果你的团队：

• 在日常开发中使用 AI 辅助编程
• 需要并行探索多种技术方案
• 重视决策过程的可追溯性
• 希望 AI 上下文能跟着分支走

那 NarraFork 可能适合你。不过请注意，项目仍在 Alpha 阶段，还有不少粗糙的地方。