NarraFork

Appearance

立刻体验 ​

前置要求

NarraFork 依赖以下工具，请确保已安装，否则部分功能将无法正常运行。

Git（必须）

bash
# 检查 Git 是否已安装
git --version

如果未安装，请前往 Git 官网 下载安装。

ripgrep（必须）

NarraFork 使用 rg（ripgrep）进行代码搜索。

bash
# 检查 rg 是否已安装
rg --version

如果未安装：

  • macOS：brew install ripgrep
  • Debian/Ubuntu：apt install ripgrep
  • Windows：winget install BurntSushi.ripgrep.MSVC，或前往 ripgrep GitHub 下载安装包

下载 ​

NarraFork 提供以下平台的预编译二进制文件：

平台架构文件名
macOSARM64（M1/M2/M3/M4）narrafork-macos-arm64
macOSx64（Intel）narrafork-macos-x64
Linuxx86_64narrafork-linux-x64
LinuxARM64narrafork-linux-arm64
Windowsx64narrafork-windows-x64.exe

下载后给文件添加执行权限（macOS / Linux）：

bash
chmod +x narrafork-macos-arm64

启动 ​

直接运行二进制文件即可：

bash
./narrafork-macos-arm64

首次启动会自动在 ~/.narrafork/ 下创建数据库和配置文件。启动完成后，在浏览器中访问 http://localhost:7788 即可使用。

macOS 用户

由于 macOS 的权限管控，localhost 可能无法正常访问。请改用局域网 IP 地址访问，例如 http://192.168.x.x:7788。可以通过以下命令查看本机 IP：

bash
#允许局域网访问
./narrafork-macos-arm64 --host=0.0.0.0
#获取本机 IP
ipconfig getifaddr en0

然后就可以前往局域网进行使用。

启动参数 ​

参数说明默认值
--port指定服务端口7778
--host指定监听地址localhost

示例：

bash
# 修改端口
./narrafork-macos-arm64 --port=8080

# 允许局域网访问
./narrafork-macos-arm64 --host=0.0.0.0

也可以通过环境变量设置：

bash
PORT=8080 HOST=0.0.0.0 ./narrafork-macos-arm64

配置 AI 供应商 ​

启动并登录后，你需要配置 AI 供应商和模型才能开始使用。详细步骤请参考 配置供应商与模型。

配置完成后就可以创建项目、开启章节，开始使用 AI 叙述者进行协作编程了。

平台说明 ​

macOS ​

macOS 用户注意

由于二进制文件为交叉编译产物，macOS 的 Gatekeeper 会阻止直接运行。首次使用前需要手动签名或移除隔离属性：

bash
# 方式一：本地签名
codesign --force --sign - narrafork-macos-arm64

# 方式二：移除隔离属性
xattr -cr narrafork-macos-arm64

二选一即可。

macOS / Linux ​

  • 需要安装 dtach 用于终端会话持久化
    • macOS：brew install dtach
    • Debian/Ubuntu：apt install dtach
  • Podman 容器环境为可选功能，仅 Linux 支持（rootless 模式）

Windows ​

  • 终端持久化功能（dtach）暂不支持 Windows
  • Podman 容器功能暂不支持 Windows

反馈与问题 ​

遇到问题或有建议，欢迎到 GitHub 提 Issue：

👉 https://github.com/Narrafork/narrafork-issue/issues