Autonomous Novel Writing Cli AI Agent
_{自动化小说写作 Cli AI Agent}

English | 中文

Agent 写小说。写、审、改，全程接管。覆盖玄幻、仙侠、都市、科幻等多种风格，支持续写、番外、同人、仿写等创作形式。

Native English novel writing now supported！ Set --lang en to write in English. See English README for details.

npm i -g @actalk/inkos

InkOS 已发布为 OpenClaw Skill，可被任何兼容 Agent（Claude Code、OpenClaw 等）直接调用：

clawhub install inkos          # 从 ClawHub 安装 InkOS Skill

通过 npm 安装或克隆本项目时，skills/SKILL.md 已包含在内，🦞 可直接读取——无需额外从 ClawHub 安装。

安装后，Claw 可通过 exec 调用 InkOS 的原子命令和控制面操作（plan chapter/compose chapter/draft/audit/revise/write next），--json 输出结构化数据供 Claw 解析决策。推荐流程是先更新 author_intent.md 或 current_focus.md，再 plan / compose，最后决定是否 draft 或完整 write next。也可以在 ClawHub 搜索 inkos 在线查看。

方式一：全局配置（推荐，只需一次）

inkos config set-global \
  --provider <openai|anthropic|custom> \
  --base-url <API 地址> \
  --api-key <你的 API Key> \
  --model <模型名>

# provider: openai / anthropic / custom（兼容 OpenAI 格式的中转站选 custom）
# base-url: 你的 API 提供商地址
# api-key: 你的 API Key
# model: 你的模型名称

配置保存在 ~/.inkos/.env，所有项目共享。之后新建项目不用再配。

方式二：项目级 .env

inkos init my-novel     # 初始化项目
# 编辑 my-novel/.env

# 必填
INKOS_LLM_PROVIDER=                               # openai / anthropic / custom（兼容 OpenAI 接口的都选 custom）
INKOS_LLM_BASE_URL=                               # API 地址（支持中转站、智谱、Gemini 等）
INKOS_LLM_API_KEY=                                 # API Key
INKOS_LLM_MODEL=                                   # 模型名

# 可选
# INKOS_LLM_TEMPERATURE=0.7                       # 温度
# INKOS_LLM_MAX_TOKENS=8192                        # 最大输出 token
# INKOS_LLM_THINKING_BUDGET=0                      # Anthropic 扩展思考预算

项目 .env 会覆盖全局配置。不需要覆盖时可以不写。

方式三：多模型路由（可选）

给不同 Agent 分配不同模型，按需平衡质量与成本：

# 给不同 agent 配不同模型/提供商
inkos config set-model writer <model> --provider <provider> --base-url <url> --api-key-env <ENV_VAR>
inkos config set-model auditor <model> --provider <provider>
inkos config show-models        # 查看当前路由

未单独配置的 Agent 自动使用全局模型。

结构化状态 + 伏笔治理 + 字数治理

重点解决三个长篇写作的系统性问题：20+ 章后上下文膨胀导致写作变慢甚至 400 报错（Settler 全量注入 → JSON delta + 选择性检索）、伏笔只加不收、回收率接近 0%（Planner 排班 + Settler 盲区修补 + 审计追债）、字数偏差 50%+ 且 normalizer 可能毁章（LengthSpec + 安全网）。

• 管线升级为 10-agent：新增 Planner、Composer、Observer、Reflector、Normalizer
• 真相文件迁移到 story/state/*.json（Zod 校验），Settler 输出 JSON delta 而非全量 markdown，旧书自动迁移
• Node 22+ 启用 SQLite 时序记忆数据库，按相关性检索历史事实
• Planner 生成 hookAgenda 排班伏笔推进与回收，Settler working set 扩展覆盖 dormant debt
• hookOps 新增 mention 语义防止假推进，analyzeHookHealth 审计伏笔债务，evaluateHookAdmission 拦截重复伏笔
• 字数治理：LengthSpec + Normalizer 单 pass 修正，安全网防止归一化毁章
• 用户 INKOS_LLM_MAX_TOKENS 作为全局上限生效，llm.extra 保留键自动过滤
• 跨章重复检测、对话驱动引导、English variance brief、多角色场景阻力要求
• 章节摘要去重、ESM node:sqlite 修复、consolidate 全角括号兼容
• 双语 CLI 输出和日志

inkos book create --title "吞天魔帝" --genre xuanhuan  # 创建新书
inkos write next 吞天魔帝      # 写下一章（完整管线：草稿 → 审计 → 修订）
inkos status                   # 查看状态
inkos review list 吞天魔帝     # 审阅草稿
inkos review approve-all 吞天魔帝  # 批量通过
inkos export 吞天魔帝          # 导出全书
inkos export 吞天魔帝 --format epub  # 导出 EPUB（手机/Kindle 阅读）

连续性审计员从 33 个维度检查每一章草稿：角色记忆、物资连续性、伏笔回收、大纲偏离、叙事节奏、情感弧线等。内置 AI 痕迹检测维度，自动识别"LLM 味"表达（高频词、句式单调、过度总结），审计不通过自动进入修订循环。

去 AI 味规则内置于写手 agent 的 prompt 层——词汇疲劳词表、禁用句式、文风指纹注入，从源头减少 AI 生成痕迹。revise --mode anti-detect 可对已有章节做专门的反检测改写。

inkos style analyze 分析参考文本，提取统计指纹（句长分布、词频特征、节奏模式）和 LLM 风格指南。inkos style import 将指纹注入指定书籍，后续所有章节自动采用该风格，修订者也会用风格标准做审计。

inkos book create --brief my-ideas.md 传入你的脑洞、世界观设定、人设文档。建筑师 agent 会基于简报生成故事设定（story_bible.md）和创作规则（book_rules.md），而非凭空创作；同时把简报落盘到 story/author_intent.md，让这本书的长期创作意图不会只在建书时生效一次。

每本书现在都有两份长期可编辑的 Markdown 控制文档：

• story/author_intent.md：这本书长期想成为什么
• story/current_focus.md：最近 1-3 章要把注意力拉回哪里

写作前可以先跑：

inkos plan chapter 吞天魔帝 --context "本章先把注意力拉回师徒矛盾"
inkos compose chapter 吞天魔帝

这会生成 story/runtime/chapter-XXXX.intent.md、context.json、rule-stack.yaml、trace.json。其中 intent.md 给人看，其他文件给系统执行和调试。plan / compose 只编译本地文档和状态，不依赖在线 LLM，可在没配好 API Key 前先验证控制输入。

draft、write next、revise 现在共享同一套保守型字数治理：

• --words 指定的是目标字数，系统会自动推导一个允许区间，不承诺逐字精确命中
• 中文默认按 zh_chars 计数，英文默认按 en_words 计数
• 如果正文超出允许区间，InkOS 最多只会追加 1 次纠偏归一化（压缩或补足），不会直接硬截断正文
• 如果 1 次纠偏后仍然超出 hard range，章节照常保存，但会在结果和 chapter index 里留下长度 warning / telemetry

inkos import chapters 从已有小说文本导入章节，自动逆向工程 7 个真相文件（世界状态、角色矩阵、资源账本、伏笔钩子等），支持 第X章 和自定义分割模式、断点续导。导入后 inkos write next 无缝接续创作。

inkos fanfic init --from source.txt --mode canon 从原作素材创建同人书。支持四种模式：canon（正典延续）、au（架空世界）、ooc（性格重塑）、cp（CP 向）。内置正典导入器、同人专属审计维度和信息边界管控——确保设定不矛盾。

不同 Agent 可以走不同模型和 Provider。写手用 Claude（创意强），审计用 GPT-4o（便宜快速），雷达用本地模型（零成本）。inkos config set-model 按 agent 粒度配置，未配置的自动回退全局模型。

inkos up 启动后台循环自动写章。管线对非关键问题全自动运行，关键问题暂停等人工审核。通知推送支持 Telegram、飞书、企业微信、Webhook（HMAC-SHA256 签名 + 事件过滤）。日志写入 inkos.log（JSON Lines），-q 静默模式。

支持任何 OpenAI 兼容接口（--provider custom）。Stream 自动降级——中转站不支持 SSE 时自动回退 sync。Fallback 解析器处理小模型不规范输出，流中断时自动恢复部分内容。

每章自动创建状态快照，inkos write rewrite 可回滚任意章节。写手动笔前输出自检表（上下文、资源、伏笔、风险），写完输出结算表，审计员交叉验证。文件锁防止并发写入。写后验证器含跨章重复检测和 11 条硬规则自动 spot-fix。

伏笔系统使用 Zod schema 校验——lastAdvancedChapter 必须是整数，status 只能是 open/progressing/deferred/resolved。LLM 输出的 JSON delta 在写入前经过 applyRuntimeStateDelta 做 immutable 更新 + validateRuntimeState 结构校验。坏数据直接拒绝，不会滚雪球。

用户设置的 INKOS_LLM_MAX_TOKENS 作为全局上限生效，llm.extra 中的保留键（max_tokens、temperature 等）被自动过滤，防止意外覆盖。

每一章由多个 Agent 接力完成，全程零人工干预：

如果审计不通过，管线自动进入"修订 → 再审计"循环，直到所有关键问题清零。

每本书维护 7 个真相文件作为唯一事实来源：

连续性审计员对照这些文件检查每一章草稿。如果角色"记起"了从未亲眼见过的事，或者拿出了两章前已经丢失的武器，审计员会捕捉到。

从 0.6.0 起，真相文件的权威来源从 markdown 迁移到 story/state/*.json（Zod schema 校验）。Settler 不再输出完整 markdown 文件，而是输出 JSON delta，由代码层做 immutable apply + 结构校验后写入。markdown 文件仍然保留作为人类可读的投影。旧书首次运行时自动从 markdown 迁移到结构化 JSON，零人工操作。

Node 22+ 环境下自动启用 SQLite 时序记忆数据库（story/memory.db），支持按相关性检索历史事实、伏笔和章节摘要，避免全量注入导致的上下文膨胀。

除了 7 个真相文件，InkOS 还把“护栏”和“自定义”拆成可审阅的控制层：

• story/author_intent.md：长期作者意图
• story/current_focus.md：当前阶段的关注点
• story/runtime/chapter-XXXX.intent.md：本章目标、保留项、避免项、冲突处理
• story/runtime/chapter-XXXX.context.json：本章实际选入的上下文
• story/runtime/chapter-XXXX.rule-stack.yaml：本章的优先级层和覆盖关系
• story/runtime/chapter-XXXX.trace.json：本章输入编译轨迹

这样 brief、卷纲、书级规则、当前任务不再混成一坨 prompt，而是先编译，再写作。

写手 agent 内置 ~25 条通用创作规则（人物塑造、叙事技法、逻辑自洽、语言约束、去 AI 味），适用于所有题材。

在此基础上，每个题材有专属规则（禁忌、语言约束、节奏、审计维度），每本书有独立的 book_rules.md（主角人设、数值上限、自定义禁令）、story_bible.md（世界观设定）、author_intent.md（长期方向）和 current_focus.md（近期关注点）。volume_outline.md 仍然是默认规划，但在 v2 输入治理模式下不再天然压过当前任务意图。

inkOS 是 pnpm workspace monorepo，由三个包组成；每本书的数据统一存在 ~/.inkos/data/books/<bookId>/ 下。架构比较大，拆成 6 张小图逐层展开。

flowchart TB
    subgraph monorepo["inkOS monorepo (pnpm workspace)"]
        CLI["packages/cli<br/>命令入口 inkos"]
        CORE["packages/core<br/>agents / pipeline / state / llm"]
        STUDIO["packages/studio<br/>本地 GUI<br/>server.cjs + 静态 Web UI"]
    end

    CLI --> CORE
    STUDIO --> CORE

    USER[("~/.inkos/data/books/&lt;bookId&gt;/<br/>每本书一个数据目录")]
    ENV[("~/.inkos/.env<br/>全局 LLM 配置")]

    CORE --> USER
    CLI -.读.-> ENV
    STUDIO -.读.-> ENV

• packages/core 是所有业务逻辑的发源地——agents、pipeline、真相文件读写、LLM provider、状态机。
• packages/cli 是 inkos 命令本身，基本只是命令行解析 + 调 core 的 API。
• packages/studio 是 Electron/浏览器壳的本地 GUI，通过 server.cjs 在本地起 HTTP，内部一样是调 core。
• 用户数据全部在 ~/.inkos/ 之下，和代码完全隔离，升级/卸载不会动用户数据。

flowchart TD
    Start([inkos write next]) --> Lock[StateManager 获取书锁]
    Lock --> Prep[PREP<br/>ensureControlDocuments<br/>loadBookConfig<br/>getNextChapterNumber]
    Prep --> Plan[Planner<br/>生成 chapter intent]
    Plan --> Compose[Composer<br/>生成 context.json + rule-stack]
    Compose --> Write[Writer Phase 1<br/>生成创意正文]
    Write --> Settle["Settler Phase 2<br/>Observer 提取事实<br/>Reflector 产出 delta<br/>第一次 merge 5 个真相文件"]
    Settle --> PostFix{postWriteErrors?}
    PostFix -->|yes| Revise[Reviser<br/>修复禁止句式等]
    PostFix -->|no| LenCheck
    Revise --> LenCheck{字数越界?}
    LenCheck -->|yes| Normalize[Normalizer<br/>单 pass 压缩或补足]
    LenCheck -->|no| Audit
    Normalize --> Audit[Continuity Auditor<br/>33 维度交叉验证]
    Audit --> AuditPass{审计通过?}
    AuditPass -->|no| Revise2[Reviser<br/>修复审计问题]
    Revise2 --> Audit
    AuditPass -->|yes| BP["buildPersistenceOutput<br/>finalContent 被改动过?<br/>→ ChapterAnalyzer 重算<br/>→ 第二次 merge 5 真相文件<br/>v0.2.2.6 Bug E 修复点"]
    BP --> Save[saveChapter +<br/>saveNewTruthFiles]
    Save --> SaveJson[saveRuntimeStateSnapshot<br/>state/ JSON 权威源]
    SaveJson --> Idx[更新 chapters/index.json]
    Idx --> Snap[snapshotState<br/>story/snapshots/N/]
    Snap --> Release[释放书锁]
    Release --> End([完成])

两次 merge 的由来：Settler 阶段已经 merge 过一次真相文件。但如果 Reviser 或 Normalizer 后来又改动了正文，原先基于旧正文提取的事实就对不上新正文了，于是 buildPersistenceOutput 会用修订后的正文重跑一次 ChapterAnalyzer，并再次 merge 到磁盘上的现有文件。Bug E 就发生在"再次 merge"这一步——修复前只 merge 了账本，另外 4 个文件被 analyzer 的"only current chapter"输出直接覆盖。

flowchart LR
    subgraph INPUT["输入治理层"]
        Radar[雷达 Radar<br/>平台趋势<br/>可跳过]
        Planner[规划师 Planner<br/>章节意图]
        Composer[编排师 Composer<br/>精选上下文]
    end

    subgraph WRITE_LAYER["写作层"]
        Architect[建筑师 Architect<br/>章节结构]
        Writer[写手 Writer<br/>创意正文]
    end

    subgraph SETTLE_LAYER["结算层"]
        Observer[观察者 Observer<br/>提取 9 类事实]
        Reflector[反射器 Reflector<br/>JSON delta]
    end

    subgraph QA_LAYER["质量层"]
        Normalizer[归一化器 Normalizer<br/>字数治理]
        Auditor[审计员 Auditor<br/>33 维度审计]
        Reviser[修订者 Reviser<br/>修复问题]
    end

    Radar --> Planner
    Planner --> Composer
    Composer --> Architect
    Architect --> Writer
    Writer --> Observer
    Observer --> Reflector
    Reflector --> Normalizer
    Normalizer --> Auditor
    Auditor --> Reviser
    Reviser -.审计循环.-> Auditor

每个 agent 由 packages/core/src/agents/ 下对应的类实现（BaseAgent 抽象 LLM 调用），pipeline runner（packages/core/src/pipeline/runner.ts）负责接力编排。

flowchart TB
    Book[("~/.inkos/data/books/<bookId>/")]
    Book --> Cfg[book.json]
    Book --> Ch[chapters/]
    Book --> St[story/]

    Ch --> ChIdx[index.json]
    Ch --> ChMd[NNNN_Title.md]

    St --> Foundation[基石文件<br/>WRITE-ONCE]
    St --> TruthMd[真相 Markdown<br/>每章演进]
    St --> StateJson[state/ JSON 权威源<br/>每章全量覆盖]
    St --> Snapshots[snapshots/N/<br/>每章只写不改]
    St --> Runtime[runtime/chapter-XXXX.*<br/>每章新建]
    St --> Memory[memory.db<br/>Node 22+ SQLite]

    Foundation --> F1[story_bible.md]
    Foundation --> F2[volume_outline.md]
    Foundation --> F3[book_rules.md]
    Foundation --> F4[author_intent.md]
    Foundation --> F5[current_focus.md]

    TruthMd --> T1[current_state.md]
    TruthMd --> T2[particle_ledger.md]
    TruthMd --> T3[pending_hooks.md]
    TruthMd --> T4[chapter_summaries.md]
    TruthMd --> T5[subplot_board.md]
    TruthMd --> T6[emotional_arcs.md]
    TruthMd --> T7[character_matrix.md]

每个文件有不同的写入行为，这张表是 debug 数据累积/丢失类问题的关键索引：

读表要点：

• 🔀 MERGE = 读现有文件 + 按 key 合并新增/更新行 + 写回。这是长篇写作能稳定累积数据的关键。
• ➕ APPEND+DEDUPE = 新行追加到末尾，但会按 chapter_number 去重已有行。
• ♻️ OVERWRITE = 每章全量替换。注意：state/*.json 虽然是 OVERWRITE，但它的内容本身是 reducer 基于上一版 + delta 算出来的，所以等价于"逻辑上 merge，物理上全写"。
• 📸 WRITE-ONCE-AT-N = 每个 N 只写一次，之后永远不改；是章节级的不可变快照。
• 🔒 WRITE-ONCE = 整本书的生命周期里只写一次（或由用户手工编辑）。

sequenceDiagram
    autonumber
    participant P as Pipeline
    participant BP as buildPersistenceOutput
    participant CA as ChapterAnalyzer
    participant Disk as story/
    participant SC as saveChapter

    P->>BP: finalContent (经过 revise/normalize)
    alt finalContent == output.content
        BP-->>P: 快路径直接返回<br/>（正文未改动，Settler 的结果有效）
    else 正文被改动过
        BP->>CA: analyzeChapter(finalContent)
        CA-->>BP: analyzed<br/>(LLM 可能只含当前章增量)
        par 并行读 5 个真相文件
            BP->>Disk: read particle_ledger.md
            BP->>Disk: read pending_hooks.md
            BP->>Disk: read subplot_board.md
            BP->>Disk: read emotional_arcs.md
            BP->>Disk: read character_matrix.md
        end
        Disk-->>BP: 当前磁盘内容
        BP->>BP: mergeLedgerForPersistence
        BP->>BP: mergeTableMarkdownByKey (hooks / subplots / emoArcs)
        BP->>BP: mergeCharacterMatrixMarkdown
        BP-->>P: 合并后的 output<br/>历史条目全部保留
    end
    P->>SC: saveChapter(merged)
    SC->>Disk: 写回 5 个真相文件 + snapshots/N/

修复前这一步只做 ledger 的 merge，另外 4 个真相文件直接用 analyzer 的原始输出（通常只含当前章的条目）覆盖磁盘，导致远期伏笔、历史情感弧、角色矩阵等累积数据被擦除。Bug E 修复 = 把所有 5 个文件的 merge 都补齐。

InkOS 提供三种交互方式，底层共享同一组原子操作：

inkos write next 吞天魔帝          # 写草稿 → 审计 → 自动修订，一步到位
inkos write next 吞天魔帝 --count 5 # 连续写 5 章

write next 现在默认走 plan -> compose -> write 的输入治理链路。若你需要回退到旧的 prompt 拼装路径，可在 inkos.json 中显式设置：

{
  "inputGovernanceMode": "legacy"
}

默认值为 v2。legacy 仅作为显式 fallback 保留。

inkos plan chapter 吞天魔帝 --context "本章重点写师徒矛盾" --json
inkos compose chapter 吞天魔帝 --json
inkos draft 吞天魔帝 --context "本章重点写师徒矛盾" --json
inkos audit 吞天魔帝 31 --json
inkos revise 吞天魔帝 31 --json

每个命令独立执行单一操作，--json 输出结构化数据。plan / compose 负责控制输入，draft / audit / revise 负责正文与质量链路。可被外部 AI Agent 通过 exec 调用，也可用于脚本编排。

inkos agent "帮我写一本都市修仙，主角是个程序员"
inkos agent "写下一章，重点写师徒矛盾"
inkos agent "先扫描市场趋势，然后根据结果创建一本新书"

内置 18 个工具（write_draft、plan_chapter、compose_chapter、audit_chapter、revise_chapter、scan_market、create_book、update_author_intent、update_current_focus、get_book_status、read_truth_files、list_books、write_full_pipeline、web_fetch、import_style、import_canon、import_chapters、write_truth_file），LLM 通过 tool-use 决定调用顺序。推荐的 Agent 工作流是：先调整控制面，再 plan / compose，最后决定写草稿还是跑完整管线。

用 InkOS 全自动跑了一本玄幻题材的《吞天魔帝》：

[id] 参数在项目只有一本书时可省略，自动检测。所有命令支持 --json 输出结构化数据。draft / write next / plan chapter / compose chapter 支持 --context 传入创作指导，--words 覆盖每章目标字数。book create 支持 --brief <file> 传入创作简报（你的脑洞/设定文档），Architect 会基于此生成设定而非凭空创作。plan chapter / compose chapter 不要求在线 LLM，可在配置 API Key 之前先检查输入治理结果。

• packages/studio Web UI 审阅编辑界面（Vite + React + Hono）
• 局部干预（重写半章 + 级联更新后续 truth 文件）
• 自定义 agent 插件系统
• 平台格式导出（起点、番茄等）

欢迎贡献代码。提 issue 或 PR。

pnpm install
pnpm dev          # 监听模式
pnpm test         # 运行测试
pnpm typecheck    # 类型检查

MIT