📝 WriteHERE

基于异构递归规划的开源写作项目

WriteHERE 是一个开源框架，通过类人自适应规划彻底革新长篇写作。与遵循僵化工作流的传统 AI 写作工具不同，WriteHERE 能够动态分解写作任务，并整合三大核心能力：

1. 递归规划：将复杂写作任务拆解为可管理的子任务
2. 异构集成：无缝结合检索、推理和创作
3. 动态适应：根据上下文实时调整写作过程

我们的评估表明，该方法在小说写作和技术报告生成方面均持续优于当前最先进的方法。

🎉 最新消息

• [2025年9月] 我们的论文已被 EMNLP 2025 接受为口头报告。苏州见！🎊

🔍 概述

不同于依赖预设工作流程和僵化思维模式的传统方法，该框架：

1. 通过交织递归任务分解与执行的规划机制，消除了工作流限制
2. 通过整合不同类型的任务，促进异构任务分解
3. 在写作过程中动态适应，类似于人类的写作行为

我们在小说写作和技术报告生成上的评估表明，该方法在所有评估指标上均持续优于当前最先进的方法。

🌐 开源理念

WriteHERE 的开发秉持以下核心原则：

• 完全开源：所有代码均在 MIT 许可证下免费提供使用、修改和分发
• 非商业性：专为研究和教育目的开发，不涉及商业利益
• 完全透明：整个系统架构和决策过程对用户完全公开
• 社区驱动：我们欢迎来自社区的贡献、反馈和协作改进

🚀 快速入门

前置条件

• Python 3.6+
• Node.js 14+（用于前端）
• API 密钥，包括：
  • OpenAI（GPT 模型）
  • Anthropic（Claude 模型）
  • SerpAPI（用于报告生成中的搜索功能）

快速启动

您可以通过两种方式使用 WriteHERE：带可视化界面或不带可视化界面。

不带可视化界面运行

当您不需要实时可视化或希望将引擎用于批量处理时，这是更简单的方式。

1. 设置环境：

python -m venv venv
source venv/bin/activate
pip install -v -e .

# 根据示例创建 api_key.env 文件
cp recursive/api_key.env.example recursive/api_key.env
# 编辑文件以添加您的密钥
nano recursive/api_key.env

2. 直接运行引擎：

cd recursive
python engine.py --filename <input_file> --output-filename <output_file> --done-flag-file <done_file> --model <model_name> --mode <story|report>

生成故事的示例：

python engine.py --filename ../test_data/meta_fiction.jsonl --output-filename ./project/story/output.jsonl --done-flag-file ./project/story/done.txt --model gpt-4o --mode story

生成报告的示例：

python engine.py --filename ../test_data/qa_test.jsonl --output-filename ./project/qa/result.jsonl --done-flag-file ./project/qa/done.txt --model claude-3-sonnet --mode report

带可视化界面运行

此选项提供了一个 Web 界面，可实时可视化并监控写作过程。

1. 一步式设置与启动：

./setup_env.sh  # 一次性设置环境
./start.sh      # 启动应用

这将：

• 创建一个干净的 Python 虚拟环境
• 安装所有必需的依赖项
• 在端口 5001 上启动后端服务器
• 在端口 3000 上启动前端
• 自动打开浏览器访问 http://localhost:3000

您也可以使用命令行参数自定义端口：

./start.sh --backend-port 8080 --frontend-port 8000

对于 Anaconda/Miniconda 用户

如果您使用 Anaconda 并遇到依赖冲突，请使用：

./run_with_anaconda.sh

该脚本会创建一个名为 'writehere' 的专用 Anaconda 环境，安装正确的依赖项并同时启动两个服务器。

您还可以通过此脚本自定义端口：

./run_with_anaconda.sh --backend-port 8080 --frontend-port 8000

手动安装

如果您更倾向于手动设置各个组件：

后端设置

1. 创建 Python 虚拟环境：

python -m venv venv
source venv/bin/activate

2. 安装主要依赖项：

pip install -v -e .

3. 安装后端服务器依赖项：

pip install -r backend/requirements.txt

4. 启动后端服务器：

cd backend
python server.py

若需使用自定义端口：

python server.py --port 8080

首页设置

1. 安装前端依赖项：

cd frontend
npm install

2. 启动前端开发服务器：

npm start

若需使用自定义端口：

PORT=8000 npm start

故障排除

如遇任何问题，请查阅 故障排除指南，获取常见问题及解决方案。

✨ 特性

• 递归任务分解：将复杂写作任务拆解为可管理的子任务
• 动态集成：无缝结合检索、推理和创作任务
• 自适应工作流：根据上下文和需求灵活调整写作过程
• 多用途应用：支持创意小说和技术报告生成
• 用户友好界面：直观的 Web 界面，便于交互
• 实时可视化：可查看智能体的工作“思考过程”
• 透明运行：所有智能体的决策和过程对用户可见
• 完全可定制：可根据需求修改提示词、参数和工作流

📂 项目结构

.
├── backend/               # 后端 Flask 服务器
├── frontend/              # React 前端
├── recursive/             # 核心引擎实现
│   ├── agent/             # 智能体实现及提示词
│   ├── executor/          # 任务执行模块
│   ├── llm/               # 语言模型集成
│   ├── utils/             # 工具函数和辅助程序
│   ├── cache.py           # 缓存机制，提升效率
│   ├── engine.py          # 核心规划与执行引擎
│   ├── graph.py           # 任务图表示
│   ├── memory.py          # 内存管理
│   ├── test_run_report.sh # 生成报告的脚本
│   └── test_run_story.sh  # 生成故事的脚本
├── test_data/             # 测试用示例数据
└── start.sh               # 一体化启动脚本

📊 实时任务可视化

使用可视化界面时，您可以实时查看任务执行过程。当智能体在生成内容时，您可以看到：

1. 任务的层次化分解
2. 当前正在处理的任务
3. 每个任务的状态（待处理、进行中、已完成）
4. 每个任务的类型（检索、推理、组合）

这种可视化能够让您深入了解智能体的“思考过程”，帮助您理解复杂的写作任务是如何被逐步拆解并解决的。

👥 贡献说明

我们欢迎社区成员为 WriteHERE 的改进贡献力量！以下是几种参与方式：

代码贡献

1. fork 仓库，并在 main 分支上创建您的功能分支
2. 按照安装说明搭建开发环境
3. 进行代码修改，确保遵循项目的编码风格和规范
4. 为新增功能添加测试
5. 运行测试套件，确保所有测试通过
6. 提交 pull request，并清晰描述您的改动及其优势

Bug 报告与功能请求

• 使用 Issues 标签页报告 bug 或提出新功能建议
• 对于 bug，请提供详细的复现步骤、预期行为和实际行为
• 对于功能请求，请描述您希望实现的功能以及它将如何使项目受益

文档改进

• 通过修复错误、添加示例或澄清说明来完善文档
• 文档更改可以像代码更改一样通过 pull request 提交

社区支持

• 在 Issues 区域回答其他用户的问题
• 与社区分享您的使用经验和案例

开发指南

• 遵循现有代码风格和架构
• 为新函数、类和模块编写文档
• 编写清晰的提交信息，解释更改的目的
• 保持 pull request 的单一性，每次只针对一个功能或 bug 修复

通过为 WriteHERE 做出贡献，您同意您的贡献将采用项目的 MIT 许可证进行授权。

📚 引用

如果您在研究中使用了本代码，请引用我们的论文：

@misc{xiong2025heterogeneousrecursiveplanning,
      title={超越提纲：基于语言模型的自适应长文写作中的异构递归规划}, 
      author={Ruibin Xiong 和 Yimeng Chen 和 Dmitrii Khizbullin 和 Mingchen Zhuge 和 Jürgen Schmidhuber},
      year={2025},
      eprint={2503.08275},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2503.08275}
}

⚖️ 许可证

MIT 许可证

本项目为开源项目。您可以自由地将代码用于研究、教育和个人目的，并对其进行修改和分发。

WriteHERE 快速上手指南

WriteHERE 是一个基于异构递归规划（Heterogeneous Recursive Planning）的开源写作框架。它模拟人类的自适应规划能力，动态分解写作任务，无缝整合检索、推理和创作，适用于小说创作和技术报告生成。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux / macOS / Windows (WSL 推荐)
• Python: 3.6 或更高版本
• Node.js: 14 或更高版本（如需使用可视化界面）
• API Keys: 您需要准备以下服务的密钥：
  • OpenAI (用于 GPT 模型)
  • Anthropic (用于 Claude 模型)
  • SerpAPI (用于报告生成中的搜索功能)

安装步骤

1. 克隆项目与配置环境变量

首先克隆仓库并设置 API 密钥配置文件：

git clone <repository_url>
cd WriteHERE

# 创建 Python 虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 用户请使用: venv\Scripts\activate

# 安装核心依赖
pip install -v -e .

# 配置 API 密钥
cp recursive/api_key.env.example recursive/api_key.env
# 使用编辑器打开文件并填入您的 API Keys
nano recursive/api_key.env

2. 选择运行模式

您可以根据需求选择无界面模式（适合批量处理/命令行）或可视化界面模式（适合实时监控写作过程）。

选项 A：运行可视化界面（推荐新手）

此模式提供 Web 界面，可实时观察任务的层级分解和执行状态。

一键启动（标准环境）：

./setup_env.sh  # 一次性设置环境
./start.sh      # 启动应用

启动后，浏览器将自动打开 http://localhost:3000。后端运行在 5001 端口，前端运行在 3000 端口。

自定义端口：

./start.sh --backend-port 8080 --frontend-port 8000

Anaconda/Miniconda 用户： 如果遇到依赖冲突，请使用专用脚本：

./run_with_anaconda.sh
# 自定义端口
./run_with_anaconda.sh --backend-port 8080 --frontend-port 8000

选项 B：无界面模式（命令行引擎）

适合不需要实时可视化或进行批量处理的场景。

直接在 recursive 目录下运行引擎：

cd recursive
python engine.py --filename <input_file> --output-filename <output_file> --done-flag-file <done_file> --model <model_name> --mode <story|report>

基本使用示例

以下是两个典型的使用场景命令：

场景 1：生成小说故事 (Story Mode)

使用 GPT-4o 模型处理虚构类写作任务：

python engine.py --filename ../test_data/meta_fiction.jsonl --output-filename ./project/story/output.jsonl --done-flag-file ./project/story/done.txt --model gpt-4o --mode story

场景 2：生成技术报告 (Report Mode)

使用 Claude 3 Sonnet 模型处理需要检索和推理的报告任务：

python engine.py --filename ../test_data/qa_test.jsonl --output-filename ./project/qa/result.jsonl --done-flag-file ./project/qa/done.txt --model claude-3-sonnet --mode report

运行完成后，结果将保存至指定的 output-filename 文件中。