Novel Agent

Python 3.9+ · Anthropic Claude · Neo4j · 多 Agent 协作 · 上下文压缩 · 端到端评测

从 0 设计并实现面向长篇小说创作的多 Agent 系统，支持从故事规划、章节生成、角色与剧情记忆管理到终稿校验的全流程智能创作。

核心能力

多 Agent 协作框架 — Lead Agent 调度 plan_agent / writer_agent / graph_agent 三个固定队友，通过消息总线、任务板、权限模型实现职责解耦与状态一致性，可稳定协作完成 100min+ 长链路任务，全程无人工介入。

分级上下文压缩 — 根据信息价值与恢复成本差异化压缩上下文，在保证关键记忆完整性的同时显著降低 Token 消耗。实测 15 章连续创作，Token 消耗从 1.25 亿降至 8100 万（↓35.2%），Prompt Cache 命中率仅从 99% 降至 97%。

工具系统作为模型容错层 — 自动参数修正、编辑模糊匹配、统一错误反馈和运行时护栏，将模型的不确定性消化在工具层，显著提升长链路 Agent 的工具调用可靠性。

图谱 + 账本双轨记忆 — Neo4j 存储角色、事件、时间线等结构化知识；三账本（desire / cost / info_gap）追踪叙事要素。章节终稿闸门确保引用校验 → 分域草案 → 逐条审阅 → 按序落盘的数据一致性。

可恢复的长任务运行时 — 会话增量持久化 + 项目状态快照（检查点），支持崩溃恢复、状态回放和可控回滚。

可观测 + 评测 — 双层观测体系（结构化日志 + 请求级 Trace），结合 Trace 驱动的自动化评测框架，从产物正确性、运行指标和 LLM Judge 多维度评估 Agent 能力。

文件记忆系统 — 零依赖的内置记忆系统，每条记忆独立 Markdown 文件，模型驱动的自动提取与召回，支持跨会话的长期记忆持久化。

快速开始

方式一：pip 安装

pip install my-novel-agent

创建项目目录并配置：

mkdir my-novel && cd my-novel

# 创建 .env 文件
cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-xxx
ANTHROPIC_BASE_URL=https://api.anthropic.com

# Neo4j（可选，图谱功能需要）
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
EOF

# 启动
novel-agent

记忆功能开箱即用（基于文件系统，零额外依赖）。

如果需要图谱功能，先启动 Neo4j：

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your_password \
  neo4j:5.26.26-community

启动后在 REPL 中：

/setup              # 从 API 获取模型列表并选择
/novel new 我的小说  # 初始化小说工作区

方式二：克隆源码运行

git clone https://github.com/lazyayuan/my-novel-agent.git
cd my-novel-agent
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

配置 .env：

cat > .env << 'EOF'
ANTHROPIC_API_KEY=sk-xxx
ANTHROPIC_BASE_URL=https://api.anthropic.com

# Neo4j（可选，图谱功能需要）
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
EOF

启动：

novel-agent

首次使用：

/setup              # 选择模型
/novel new 我的小说  # 初始化小说

环境变量

REPL 命令

代码结构

src/my_novel_agent/
├── s_full.py                  # REPL 主循环 + 编排引擎（工具注册、模型调用、团队协作）
├── cli.py                     # CLI 入口点（novel-agent 命令）
│
├── 领域层
│   ├── novel_graph.py         # Neo4j 图谱 schema、受控 upsert、Cypher 查询
│   ├── novel_ledgers.py       # 三账本系统（desire/cost/info_gap），Markdown + YAML
│   ├── novel_outlines.py      # 大纲路径规范化、ID 校验（CH-###/VOL-###）
│   ├── character_cards.py     # 角色卡 CRUD，审阅式更新（old/new 局部替换）
│   ├── story_time.py          # 小说内时间运算（日期偏移/比较/算术）
│   ├── chapter_finalization.py # 章节终稿闸门（引用校验 → 分域草案 → 按序落盘）
│   └── file_memory.py         # 文件记忆系统（提取/召回/删除，每条记忆一个 .md 文件）
│
├── 运行时
│   ├── model_runtime.py       # 模型注册表、context window 追踪、API 模型发现
│   ├── prompt_runtime.py      # Markdown prompt 装配（agents/ + sections/ 模板拼装）
│   ├── context_compaction.py  # 分级上下文压缩（按信息价值差异化压缩）
│   ├── session_store.py       # 会话增量持久化（.sessions/ 目录）
│   ├── teammate_policy.py     # lead/队友工具边界与写路径限制
│   ├── permissions.py         # 统一权限模型（读/写 allow/deny，global + 角色级）
│   ├── novel_workspace.py     # 小说工作区管理（创建、归档、恢复）
│   ├── checkpoint_manager.py  # 检查点管理（状态快照与回滚）
│   ├── memory_runtime.py      # 记忆运行时（Protocol + 工厂，自动选择文件/向量实现）
│   ├── agent_loop.py          # Agent 循环抽象（单 agent 的 run/idle/work 状态机）
│   ├── loop_runtime.py        # 循环运行时解析
│   ├── task_messaging.py      # 任务板 + 消息总线（Agent 间通信）
│   └── tool_runners.py        # 工具执行器
│
├── 工具层
│   ├── edit_tool.py           # 模型容错的文件编辑（模糊匹配、自动修正）
│   ├── file_lock.py           # 文件级并发锁
│   └── graph_dryrun.py        # 图谱操作试执行（显式事务回滚）
│
├── 插件化扩展
│   ├── mcp_runtime.py         # MCP Server 子进程管理
│   └── hook_runtime.py        # Shell Hook（PreToolUse/PostToolUse/SessionStart）
│
├── 可观测性
│   ├── runtime_logging.py     # JSONL 结构化日志（.logs/）
│   ├── trace_logging.py       # 请求级 Trace（.traces/，含完整 payload）
│   ├── finalization_http_proxy.py  # 终稿审阅 HTTP 代理（localhost:18765）
│   ├── finalization_trial.py  # 试落盘（隔离临时区 + file_diff 报告）
│   ├── finalization_viewer.html    # 浏览器审阅 UI（逐条 apply/skip）
│   ├── trace_viewer.html      # Trace 可视化（缓存命中率分析）
│   ├── log_viewer.html        # 日志可视化
│   └── compact_test_viewer.html    # 压缩测试查看器
│
├── REPL
│   ├── repl_commands.py       # 斜杠命令定义
│   └── repl_input.py          # prompt_toolkit 输入（自动补全）
│
├── config/                    # 配置文件
│   └── permissions.json       # 角色权限配置
│
├── prompts/                   # Markdown prompt 模板
│   ├── agents/                # 各 Agent 系统提示词（lead/plan/writer/graph/subagent）
│   ├── sections/              # 可复用提示词片段（职责、工具规则、协作边界）
│   └── novel/                 # 小说专用 prompt（角色卡模板等）
│
├── mcp_server/                # MCP 服务器
│   └── novel_hotspots_server.py  # 热点数据抓取（起点/番茄新书榜）
│
└── eval/                      # 评测框架
    ├── run.py                 # 评测编排（隔离 → 跑 s_full → 收 trace → 评分 → Judge）
    ├── judge.py               # LLM Judge 评分（rubric + transcript 打分）
    ├── scorers.py             # 确定性评分（ArtifactScorer / MetricDeltaScorer）
    ├── trace.py               # Trace 解析与指标聚合
    ├── isolation.py           # worktree + Neo4j 隔离（确保每次评测独立）
    └── baseline_capture.py    # 基线捕获与对比

运行时产物目录（小说工作区下，不提交 git）：

开发

# 克隆项目
git clone https://github.com/lazyayuan/my-novel-agent.git
cd my-novel-agent

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装开发依赖
pip install -e ".[memory]"

测试

按模块运行测试：

python -m unittest tests.test_novel_ledgers -v
python -m unittest tests.test_novel_outlines -v
python -m unittest tests.test_novel_graph -v
python -m unittest tests.test_story_time -v
python -m unittest tests.test_character_cards -v
python -m unittest tests.test_chapter_finalization -v
python -m unittest tests.test_file_memory -v
python -m unittest tests.test_memory_runtime -v
python -m unittest tests.test_context_compaction -v
python -m unittest tests.test_prompt_runtime -v
python -m unittest tests.test_hook_runtime -v
python -m unittest tests.test_runtime_logging -v
python -m unittest tests.test_trace_logging -v
python -m unittest tests.test_teammate_policy -v
python -m unittest tests.test_lead_tool_wiring -v
python -m unittest tests.test_permissions -v
python -m unittest tests.test_graph_dryrun -v
python -m unittest tests.test_message_bus -v
python -m unittest tests.test_loop_runtime -v
python -m unittest tests.test_checkpoint_manager -v
python -m unittest tests.test_finalization_http_proxy -v
python -m unittest tests.test_finalization_trial -v

或全量运行：

python -m unittest discover tests -v

许可证

MIT License