InkOS Local Usage

这份 README 面向当前仓库源码的本地使用方式：

• 直接运行仓库里的本地 CLI，而不是 npm 发布版
• 使用新增的 Codex OAuth bridge
• 在本地通过 Studio 调试写作、审校和建书流程

如果你想看项目原本的官方介绍、功能总览和发布版使用说明，请看 README_legacy.md。

这个 fork 做了什么

相对上游 InkOS，这个版本额外做了这些增强：

• 新增本地 Codex OAuth bridge，可复用 codex login 的 ChatGPT OAuth 登录态
• 支持把 InkOS 配到本地 bridge 上，直接调用 gpt-5.4
• 补了 Studio 建书阶段的进度条、阶段状态、当前创建任务日志过滤、侧边栏任务卡片
• 增强了 bridge 日志、超时处理和建书流程可观测性

环境要求

• Node.js >= 20
• pnpm >= 9
• 已安装 Codex CLI
• 已完成 Codex 登录

codex login
codex login status

一次性准备

在仓库根目录执行：

pnpm install
pnpm build

如果你只想编译关键包，也可以用：

pnpm --filter @actalk/inkos-core build
pnpm --filter @actalk/inkos-codex-bridge build
pnpm --filter @actalk/inkos-studio build
pnpm --filter @actalk/inkos build

不要优先使用全局 inkos

这个 fork 的功能很多还没有发布到 npm，所以不要默认跑全局安装的 inkos。

优先使用仓库里的本地 CLI：

node packages/cli/dist/index.js --help

常用命令：

node packages/cli/dist/index.js status
node packages/cli/dist/index.js doctor
node packages/cli/dist/index.js studio
node packages/cli/dist/index.js codex status
node packages/cli/dist/index.js codex bridge doctor

本地项目使用流程

1. 初始化一个项目

mkdir -p /path/to/my-novel
cd /path/to/my-novel
node /path/to/inkos/packages/cli/dist/index.js init .

2. 切到 Codex bridge 配置

node /path/to/inkos/packages/cli/dist/index.js config use-codex --model gpt-5.4 --port 8787

这会把当前项目的 inkos.json 指向本地 bridge：

• provider = custom
• baseUrl = http://127.0.0.1:8787/v1
• apiFormat = responses
• model = gpt-5.4

3. 启动 bridge

node /path/to/inkos/packages/cli/dist/index.js codex bridge start

4. 检查状态

node /path/to/inkos/packages/cli/dist/index.js codex status
node /path/to/inkos/packages/cli/dist/index.js codex bridge doctor
node /path/to/inkos/packages/cli/dist/index.js doctor

5. 启动 Studio

进入你的项目目录后：

node /path/to/inkos/packages/cli/dist/index.js studio

推荐工作流

cd /path/to/my-novel
node /path/to/inkos/packages/cli/dist/index.js book create --title "测试书" --genre xuanhuan
node /path/to/inkos/packages/cli/dist/index.js write next 测试书
node /path/to/inkos/packages/cli/dist/index.js review list 测试书
node /path/to/inkos/packages/cli/dist/index.js studio

一键启动

仓库根目录提供了 dev-start.sh，会自动：

1. 构建工作区
2. 初始化一个本地测试项目
3. 配置当前项目走 Codex bridge
4. 启动 bridge
5. 跑一次 doctor
6. 启动 Studio

示例：

./dev-start.sh
./dev-start.sh /path/to/my-novel
INKOS_DEV_SKIP_BUILD=1 ./dev-start.sh /path/to/my-novel

日常排查

bridge 日志

tail -n 120 ~/.inkos/inkos-codex-bridge.log

项目日志

tail -n 120 /path/to/my-novel/inkos.log

常见问题

• 如果 codex bridge start 报认证问题，先执行 codex login status
• 如果 Studio 建书卡住，先看“当前创建任务日志”和 inkos.log
• 如果出现超时，优先看 bridge 日志里是 architect 超时还是 reviewer 超时
• 如果误用了全局 inkos，很可能会跑到 npm 发布版，看不到本地改动

旧版说明

项目原本的 README 已保留为：

• README_legacy.md

那一版更适合了解上游 InkOS 的原始定位、功能总览和发布版使用方式。