Metadata-Version: 2.4
Name: my-novel-agent
Version: 0.1.1
Summary: A sophisticated novel generation and processing agent.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: anthropic
Requires-Dist: beautifulsoup4
Requires-Dist: mcp
Requires-Dist: neo4j
Requires-Dist: prompt_toolkit
Requires-Dist: python-dotenv
Requires-Dist: PyYAML
Requires-Dist: requests

# 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 安装

```bash
pip install my-novel-agent
```

创建项目目录并配置：

```bash
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：

```bash
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 我的小说  # 初始化小说工作区
```

### 方式二：克隆源码运行

```bash
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`：

```bash
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
```

启动：

```bash
novel-agent
```

首次使用：

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

## 环境变量

| 变量 | 必需 | 说明 |
|------|------|------|
| `ANTHROPIC_API_KEY` | 是 | Anthropic API 密钥 |
| `ANTHROPIC_BASE_URL` | 是 | API 端点（如 `https://api.anthropic.com`） |
| `NEO4J_URI` | 否 | Neo4j 连接地址（图谱功能需要） |
| `NEO4J_USERNAME` | 否 | Neo4j 用户名 |
| `NEO4J_PASSWORD` | 否 | Neo4j 密码 |
| `NOVEL_AGENT_LOG` | 否 | 运行日志目录（默认 `.logs/`） |
| `NOVEL_AGENT_LOG_MAX_CHARS` | 否 | 单条日志最大字符数 |
| `NOVEL_AGENT_TRACE` | 否 | 请求级 Trace 开关（设 `1` 启用） |

## REPL 命令

| 命令 | 说明 |
|------|------|
| `/` | 显示所有可用命令 |
| `/setup` | 从 API 获取可用模型列表并选择 |
| `/model` | 查看当前模型和可用模型 |
| `/model use <id>` | 切换到指定模型 |
| `/novel new [name] [--pid id]` | 创建新小说（可指定 project_id） |
| `/novel status` | 查看当前小说状态 |
| `/novel list` | 列出已归档的小说 |
| `/novel restore <id>` | 恢复已归档的小说 |
| `/session current` | 当前会话信息 |
| `/session list` | 列出所有会话 |
| `/session show <id>` | 查看会话详情 |
| `/session new` | 创建新会话 |
| `/session switch <id>` | 切换会话 |
| `/memory status` | 记忆功能状态 |
| `/memory commit` | 手动触发记忆提取 |
| `/memory on` / `/memory off` | 开关记忆 |
| `/compact` | 手动压缩上下文 |
| `/tasks` | 查看任务板 |
| `/team` | 查看队友状态 |
| `/inbox` | 查看收件箱 |
| `/questions` | 查看待回答问题 |
| `/answer <text>` | 回答待处理问题 |
| `/msg <text>` | Agent 执行期间发送消息 |
| `/checkpoint create [name]` | 创建检查点 |
| `/checkpoint list` | 列出检查点 |
| `/checkpoint restore <id>` | 恢复检查点 |
| `/finalize_apply` | 应用已审阅的章节终稿 |
| `/focus <agent>` | 切换 REPL 视角到指定 agent |
| `/mcp status` | MCP 服务器和工具加载状态 |

## 代码结构

```
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）：

| 目录 | 用途 |
|------|------|
| `.novels/` | 小说状态（current.json + 归档） |
| `.sessions/` | 会话持久化（对话历史 + 元数据） |
| `.checkpoints/` | 检查点快照（状态回滚） |
| `.tasks/` | 任务板（Agent 协作的任务状态） |
| `.team/` | 固定队友状态 + 收件箱 |
| `.logs/` | JSONL 结构化日志 |
| `.traces/` | 请求级 Trace 数据 |
| `chapters/` | 章节正文 |
| `ledgers/` | 三账本文件 |
| `characters/` | 角色卡 |
| `planning/` | 大纲 + 章纲 + 终稿 action files |

## 开发

```bash
# 克隆项目
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]"
```

### 测试

按模块运行测试：

```bash
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
```

或全量运行：

```bash
python -m unittest discover tests -v
```

## 许可证

MIT License
