Skip to content

dsy122/BookForge

BranchesTags

Repository files navigation

BookForge

AI 写作的 Agent 编排框架

BookForge 不写文章。它编排一群专业写作 agent——有人负责研究资料，有人负责草稿撰写，有人负责润色，有人负责审校——协作完成从构思到成稿的整个写作流程。

目录

什么是 Agent Harness

LLM 提供了智能，但它不会管理上下文、不会调用工具、不会自己判断什么时候该查资料、什么时候该写、什么时候该回头修改。

Harness（编排框架）就是解决这些问题的——它包裹在 LLM 外面，提供：

能力 说明
Agent 调度 管理多个专业 agent，分配任务、收集结果、决策下一步
工具层 提供风格检查、知识库检索、字数统计等专用工具
知识管理 世界观、角色设定、时间线的持久化和检索
质量控制 多级审校制度，每章完成必须通过检查
并行执行 多个独立任务同时进行，最大化写作效率

BookForge = 写作 Agent 编排框架。模型负责「写什么」，框架负责「怎么写、谁来写、写完怎么检查」。

三层架构

┌──────────────────────────────────────────┐
│           Scribe（主编排 Agent）           │
│   意图识别 · 任务分解 · Agent 调度 · 审校   │
├──────────────────────────────────────────┤
│              写作 Agent 层                │
│                                          │
│  Draftsman  │ Reviewer  │  Polisher      │
│  (草稿撰写)  │ (综合审查) │ (文体润色)      │
│                                          │
│  Archivist  │ Researcher│                │
│  (内部检索)  │ (外部研究) │                 │
├──────────────────────────────────────────┤
│               工具层                      │
│                                          │
│  风格检查 · 文法检查 · 知识库查询          │
│  字数统计 · 文本对比 · 引用管理            │
├──────────────────────────────────────────┤
│               知识层                      │
│                                          │
│  世界观设定 · 角色库 · 时间线 · 风格指南    │
├──────────────────────────────────────────┤
│         BookForge 引擎层（自研）           │
│                                          │
│  ScribeEngine · GateEvaluator · 6 组件    │
│  Think→Act→Observe · TODO 驱动审查循环    │
└──────────────────────────────────────────┘

Scribe（主编排） 是唯一的指挥者。它理解你的写作意图，把任务拆解为原子操作，分派给下层的专业 agent，收集结果并决定是否通过。Scribe 自己不写一个字。

Agent 体系

Scribe — 主编排者

Scribe 是整个写作流程的大脑。它的工作是理解意图、分解任务、调度 agent、审查结果。

职责：

  • 解析用户的写作需求（类型、风格、篇幅、受众）
  • 将写作任务分解为可并行或串行的子任务
  • 根据任务类型委派给对应的写作 agent
  • 收集结果，走审校流程，决定通过或驳回
  • 管理知识上下文——加载相关世界观设定和角色信息

行为准则：

  • 永远不亲自写正文，只做编排
  • 默认并行执行，能同时跑的任务不排队
  • 不确定时先问，不猜
  • 每章完成前必须通过审校

研究 Agent

Agent 职责
Archivist 搜索内部知识库：已写章节、角色设定、世界观文档、大纲
Researcher 搜索外部资料：网络资料、学术文献、事实数据、引用来源

写作 Agent

Agent 职责
Draftsman 核心写作：根据 brief 和设定，生成章节正文、场景描写、对话
Polisher 文体优化：调整节奏、润色词藻、统一语气、消除冗余

审校 Agent

Agent 职责
Reviewer 综合审查：情节弧线、角色发展、节奏、连贯性、风格、文法。只读不写，输出审查报告及 APPROVED 判定。

Phase 5 架构变更：原 Editor（结构审查）和 Continuity（连贯检查）已合并为 Reviewer。Reviewer 内部通过加载不同 Skill（structure / continuity-check / style-check / grammar-check）覆盖全部审查维度。

写作工作流

每个写作任务经过三个阶段：

第一阶段：意图识别

Scribe 收到你的消息后，首先判断意图：

你说了什么 Scribe 怎么理解 Scribe 做什么
"查一下明朝的科举制度" 资料研究 派 Researcher + Archivist → 返回综合结果
"写第三章" 执行写作 加载设定 → 派 Draftsman → 审校
"这段对话不太自然" 修改润色 派 Polisher → 对比新旧版本 → 确认
"你觉得这个结局怎么样" 结构审查 派 Reviewer → 分析报告 → 等你决定
"重新设计世界观" 开放式设计 评估已有设定 → 提方案 → 等你确认

第二阶段：写作执行

  1. 知识加载 — Archivist 检索 lorebook、角色设定、前文章节
  2. 外部研究 — Researcher 搜集参考资料（如需要）
  3. 任务分解 — 章节/场景拆解为原子写作单元
  4. 并行委派 — 多个独立场景或视角同时撰写
  5. 风格统一 — Polisher 润色初稿

第三阶段：TODO 驱动审查循环

  1. Scribe 维护 TODO 列表，追踪写作和审查进度
  2. 写作 TODO 完成后，委派 Reviewer 做综合审查（结构 + 连贯性 + 风格 + 文法）
  3. Reviewer 返回 APPROVED: true/false 判定及具体问题
  4. 审查通过 → Gate 放行 → 标记章节完成
  5. 审查未通过 → 根据报告追加修改 TODO → 循环继续

全部 TODO 完成 + Reviewer 批准 → Gate 放行，标记章节完成。

一个完整的例子

你："写《明朝那些事儿》风格的万历十五年，2000字"

Scribe：
├── 意图：历史叙事写作
├── 风格：轻松口语化
├── 篇幅：2000字
│
├── [并行] Archivist：检索前文章节和设定
├── [并行] Researcher：搜索万历十五年关键事件
│
├── Draftsman：按设定 + 资料撰写草稿
├── Polisher：调校风格匹配《明朝那些事儿》
├── Reviewer：综合审查（结构 + 连贯性 + 风格）
│
└── ✓ Gate 放行，输出完成章节

技能系统

Skill 是可插拔的写作专业知识。每个 skill 是一份指南文件，告诉 agent 在特定场景下该怎么做。只有当 agent 需要时才加载，不占用上下文。

写作技法

Skill 用途
dialogue 对话撰写：角色语癖、潜台词、节奏控制
description 场景描写：五感运用、画面感、详略控制
pacing 节奏控制：张弛有度、高潮铺垫、过渡处理
exposition 背景交代：信息传递效率，避免倾泻
character-voice 角色声音：每个角色的独特语言风格
point-of-view 视角管理：第一/第三人称规则、视角切换
structure 结构设计：三幕式、章节弧线、钩子设置
subtext 潜台词：冰山理论、未言之物、读者参与感

质量控制

Skill 用途
style-check 风格一致性：语气、时态、人称统一
continuity-check 连贯性：时间线、角色行为、道具追踪
fact-check 事实核查：引用来源、数据准确性、交叉验证
sensitivity-read 敏感度审查：刻板印象检查、文化准确性、包容性

Skill 示例

---
name: dialogue
description: 对话撰写技法。触发词：对话、对白、台词
---

# 对话撰写

## 核心原则

1. 每个角色有独特的声音——词汇量、句式、口头禅各不相同
2. 对话即行动——每句话要么推动情节，要么揭示角色
3. 留潜台词——角色说的和想的往往不同

## 检查清单

- [ ] 去掉对话标签后，能否分辨谁在说话？
- [ ] 对话是否推动了情节或揭示了角色？
- [ ] 有没有至少一层潜台词？

质量控制

每章完成必须通过 TODO 驱动的审查循环 + Gate 判定：

Scribe TODO 列表:
  [x] 写第三章草稿（委派 Draftsman）
  [x] 风格润色（委派 Polisher）
  [ ] 综合审查（委派 Reviewer）
  [ ] 输出最终章节

循环:
  Draftsman 完成 → 标记 TODO
  Polisher 完成 → 标记 TODO
  Reviewer 审查 → 通过标记，未通过则新增修改 TODO
  Gate Evaluator.should_stop() → 所有 TODO [x] 且 Reviewer approved → STOP

Gate 拒绝？ → 引擎重新拉起 Scribe，告知拒绝原因 → 继续循环

双向门禁：Agent 端 prompt 约束（必须在所有 TODO 完成且 Reviewer 批准后才能声明完成）+ 引擎端 GateEvaluator 拦截（不满足条件则注入拒绝原因继续循环）。最大编排轮数 100，超限后强制 Reviewer 出最终总结。

每步都有证据记录——检查结果、修改 diff、审校批注，全程可追溯。

技术栈

BookForge 拥有自研核心引擎（bookforge/core/engine.py），提供 Think→Act→Observe 循环和 6 个可插拔组件。

层级 技术
核心引擎 ScribeEngine（自研）— Think→Act→Observe 循环、LLM、Context、Tool Registry、Hook、State、Evaluator
语言 Python 3.12+
数据模型 Pydantic v2
LLM 适配 LiteLLM（支持 Claude / OpenAI / 兼容 API）
配置 YAML + 环境变量回退
知识库 Markdown 文件系统（lorebook、character sheets）
版本管理 Git（章节版本管理、diff 对比）

项目结构

BookForge/
├── README.md                         # 项目概述
├── pyproject.toml                    # 项目配置与依赖
├── docs/
│   └── ROADMAP.md                    # 技术路线图
│
├── bookforge/                        # 引擎源码
│   ├── core/                         # 核心引擎
│   │   ├── engine.py                 #   ScribeEngine（Think→Act→Observe）
│   │   ├── base.py                   #   6 个 ABC + 2 个 Protocol
│   │   └── schema.py                 #   7 个 Pydantic 数据模型
│   ├── components/                   # 可插拔组件
│   │   ├── llm/lite_llm.py           #   LLM 适配器（LiteLLM）
│   │   ├── context/simple.py         #   上下文管理器
│   │   ├── tools/dict_registry.py    #   工具注册表（@registry.tool）
│   │   ├── hooks/simple.py           #   生命周期 Hook
│   │   ├── evaluator/trace.py        #   轨迹评估器
│   │   └── state/json_store.py       #   状态持久化
│   ├── config/loader.py              # YAML 配置加载
│   └── logging.py                    # 日志模块
│
├── tests/                            # 测试（268 项）
│   ├── core/                         #   引擎单元测试
│   ├── components/                   #   组件单元测试
│   ├── config/                       #   配置测试
│   └── integration/                  #   端到端集成测试
│
├── agents/                           # Agent 定义（.md 文件）
│   ├── scribe.md                     # 主编排者
│   ├── draftsman.md                  # 草稿撰写
│   ├── reviewer.md                    # 综合审查（结构+连贯性+风格+文法）
│   ├── archivist.md                  # 内部知识检索
│   ├── researcher.md                 # 外部资料研究
│   └── polisher.md                   # 文体润色
│
├── tools/                            # 写作专用 Tool（Python）
│   ├── style_check.py                # 风格一致性检查
│   ├── grammar_check.py              # 文法检查
│   ├── word_count.py                 # 字数统计
│   ├── lorebook_query.py             # 世界观知识库查询
│   ├── character_lookup.py           # 角色设定查询
│   ├── timeline_check.py             # 时间线验证
│   ├── diff.py                       # 文本差异对比
│   └── citation_format.py            # 引用格式化
│
├── skills/                           # 写作 Skill（SKILL.md）
│   ├── dialogue/SKILL.md             # 对话技法
│   ├── description/SKILL.md          # 描写技法
│   ├── pacing/SKILL.md               # 节奏控制
│   ├── exposition/SKILL.md           # 背景交代
│   ├── character-voice/SKILL.md      # 角色声音
│   ├── point-of-view/SKILL.md        # 视角管理
│   ├── structure/SKILL.md            # 结构设计
│   ├── subtext/SKILL.md              # 潜台词技法
│   ├── style-check/SKILL.md          # 风格检查指南
│   ├── continuity-check/SKILL.md     # 连贯性检查指南
│   ├── fact-check/SKILL.md           # 事实核查指南
│   └── sensitivity-read/SKILL.md     # 敏感度审查指南
│
├── hooks/                            # 生命周期 Hook
│   └── review_pipeline.py            # 三级审校 Pipeline
│
└── workspace/                        # 写作工作区（示例）
    ├── manuscript/                   # 手稿章节
    ├── lorebook/                     # 世界观设定
    ├── characters/                   # 角色档案
    ├── outline/                      # 大纲
    └── references/                   # 参考资料

快速开始

# 1. 克隆 BookForge
git clone https://github.com/your-org/BookForge.git
cd BookForge

# 2. 创建虚拟环境并安装
python -m venv .venv
.venv\Scripts\activate      # Windows
source .venv/bin/activate   # macOS/Linux
pip install -e ".[dev]"

# 3. 配置 API Key
# 方式一：在 bookforge.yaml 中配置
cp bookforge.yaml.example bookforge.yaml
# 编辑 bookforge.yaml，填入 provider、model、api_key

# 方式二：设置环境变量
# export OPENAI_API_KEY=sk-...    # 或 ANTHROPIC_API_KEY

# 4. 运行测试确认引擎正常
pytest tests/ -v

# 5. 开始写作（后续版本）
# python -m bookforge --agent scribe

"The model writes. The engine orchestrates."

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages