企业官网建设流程全解析

专栏作家智能体（ColumnWriter）实战解析：基于 HelloAgents 的多智能体专栏创作流水线

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents

本文基于仓库Co-creation-projects/melxy1997-ColumnWriter项目，深入剖析一个由 Plan-and-Solve、ReAct、Reflection 三种经典 Agent 范式协同驱动的智能专栏写作系统：从主题输入到专栏大纲规划、递归内容树生成、联网搜索增强、独立评审与自动修改，再到 Markdown 文章与统计报告导出。读完本文，你将掌握该项目的完整模块架构、多 Agent 工作流与配置参数语义，并能够直接复现运行，将其作为构建"规划—写作—评审—优化"闭环型内容生产系统的参考实现。

项目定位：模拟一个专业创作者团队

专栏作家智能体（Column Writer Agent）是基于 HelloAgents 框架构建的智能专栏写作系统。它没有把"写文章"交给单个大模型一次性完成，而是模拟了一个专业的创作者团队，让不同类型的 Agent 分工协作：

• 策划专家：负责顶层设计和内容规划，把宽泛主题拆解为结构化的专栏大纲；
• 写作专家：负责具体内容的撰写，并在写作过程中主动调用搜索工具获取最新资料；
• 评审专家：负责内容质量把控，给出多维度的评分与可操作的修改建议。

系统支持树形递归生成专栏目录，可以创作出结构严谨、内容详实的长篇技术专栏。项目源码位于 Co-creation-projects/melxy1997-ColumnWriter，运行环境要求 Python 3.10+。

图：专栏作家智能体的实际执行画面，展示了规划、写作、评审等阶段的命令行输出

核心功能一览

1. 智能规划与分解：利用 Plan-and-Solve 模式，自动将宽泛主题（如"Python 异步编程"）拆解为包含多个子话题和章节的完整大纲，支持多层级递归展开，生成深度内容。
2. 多模式智能写作：ReAct 模式在写作过程中主动调用搜索工具获取最新信息；Reflection 模式通过自我反思机制，生成初稿后自动评审并优化。
3. 联网搜索增强：集成 Tavily/SerpApi 保证内容时效性与准确性，集成 GitHub MCP 可直接读取开源项目代码作为案例。
4. 质量闭环控制：内置评分系统，对生成内容进行多维度评审（准确性、逻辑性、易读性等），分数不足自动触发修改流程，直至达到质量标准。
5. 智能缓存与容错：支持规划结果缓存避免重复生成，具备错误恢复机制，在 Agent 调用失败时自动降级处理，确保任务完成。

模块架构：七个核心模块各司其职

系统由以下核心模块组成（引用自 README.md）：

其中，数据模型层（models.py）是整个系统流转的基石：

• ContentLevel枚举定义了三级内容层次：TOPIC（子话题）、SECTION（小节）、DETAIL（细节）；
• ContentNode是内容树的节点，除标题、描述、内容外，还通过children列表支持任意深度的递归嵌套，并提供get_all_nodes()（深度优先遍历）与count_words()（递归统计字数）两个实用方法；
• ColumnPlan封装专栏规划结果（标题、简介、目标读者、子话题列表），并提供from_dict/to_dict用于与 LLM 输出的 JSON 及本地缓存互转；
• ReviewResult封装评审结果（总分、评级、各维度得分、详细反馈、修改计划等），是"评审—修改"闭环的数据载体。

工作流：多阶段递归的创作流水线

系统工作流由 orchestrator.py 中的ColumnWriterOrchestrator.create_column()驱动，是一个多阶段、递归的过程：

阶段 1：规划（Planning）

用户输入专栏主题后，PlannerAgent（基于PlanAndSolveAgent）分析主题、分解任务，生成结构化的ColumnPlan（包含标题、简介、目标读者、子话题列表）。在源码中，规划通过"任务分解 → 逐步执行"的方式完成：先输出不超过 10 步的规划步骤，再逐条执行，最后一步强制输出完整 JSON 格式的专栏大纲。

阶段 2：递归写作（Writing - Recursive）

Orchestrator 遍历规划中的每个子话题，逐个启动写作任务：

• Level 1 (Topic)：生成子话题引言和概述；
• Level 2 (Section)：细化为小节，进行深入阐述；
• Level 3 (Detail)：补充具体案例、代码或详细说明。

_recursive_write()是递归写作的核心逻辑：当level > settings.max_depth时停止展开；否则根据use_reflection_mode分流到两种实现——_write_with_reflection()（ReflectionAgent 一步完成"生成+优化"）或_write_with_react()（ReActAgent 生成后走独立评审）。子节点的展开由内容数据中的needs_expansion与subsections字段驱动（见_process_children()），从而形成一棵真正的递归内容树。

阶段 3：工具调用（Tool Use）

写作过程中，Writer Agent 可以主动调用工具：

• web_search：搜索最新技术动态、统计数据；
• search_recent_info：搜索某主题的最新信息；
• search_code_examples：查找代码示例和教程；
• verify_facts：验证事实准确性；
• github（可选）：搜索 GitHub 仓库，读取真实项目代码。

阶段 4：评审与优化（Review & Refine）

• ReAct 模式 + 独立评审：内容生成后，ReviewerAgent进行多维度评分（内容质量 40 分、结构逻辑 30 分、语言表达 20 分、格式规范 10 分）。若分数低于通过阈值（默认 75 分），RevisionAgent根据评审意见修改；若分数过低（低于revision_threshold，默认 60 分）则直接触发重写。循环直到通过或达到最大修改次数（默认 2 次）。
• Reflection 模式：使用ReflectionWriterAgent，Agent 生成初稿后立即自我反思（Self-Reflection）并自动优化，一步到位。

_review_and_revise()是闭环控制的具体实现：每一轮评审结果都会记入review_history，同时更新系统统计信息（total_reviews、total_revisions、total_rewrites、approved_first_try），最终把评审轮次、得分、评级写入内容元数据，供导出与复盘使用。

阶段 5：组装与导出（Assembly & Export）

将生成的递归内容树展平：_tree_to_markdown()按节点深度生成#/##/###标题层级；_calculate_statistics()汇总文章数、总节点数、总字数与平均字数；最终由 exporter.py 的ColumnExporter.export_to_files()输出三部分内容——完整 JSON 数据（column_data.json）、每篇文章的 Markdown 文件（含元数据：文章 ID、字数、评审分数、评审等级、修改记录），以及统计报告（REPORT.md，包含字数、耗时、质量评分、Agent 模式等数据）。

智能体模式：四种设计范式组合

本项目同时应用了多种 Agent 设计模式，是理解多范式编排的绝佳样本：

1. Plan-and-Solve（规划与求解）——PlannerAgent

• 原理：将复杂任务分解为步骤列表（Plan），然后逐个执行（Solve）。
• 应用：PlannerAgent在 agents.py 中通过自定义 planner/executor 两段提示词驱动PlanAndSolveAgent：planner 提示词要求输出"分析核心概念→确定整体框架→规划 2-4 个子话题→设定学习目标和要点→组装完整专栏大纲"等不超过 10 步的规划步骤；executor 提示词要求最后一步输出含column_title、column_description、target_audience、topics字段的完整 JSON。
• 优势：适合处理宏观的、需要长链条推理的规划任务，避免一步生成导致的逻辑混乱。

2. ReAct（推理 + 行动）——WriterAgent

• 原理：循环执行Reasoning（思考）→ Acting（行动/工具调用）→ Observation（观察结果），最终以Finish[JSON内容]结束。
• 应用：WriterAgent基于ReActAgent构建，max_steps=10（给 Agent 更多机会完成任务），通过ToolRegistry注册搜索函数包装器。其自定义提示词（WRITER_PROMPT，见 prompts.py）严格规定：完成写作后必须使用\n\nFinish[JSON内容]格式输出，Finish中必须是包含title、level、content、word_count、needs_expansion、subsections、metadata的完整 JSON。
• 优势：使 Agent 能够与外部世界交互（搜索、查库），不仅仅依靠训练数据写作，确保内容的实效性和准确性。

3. Reflection（反思）——ReflectionWriterAgent

• 原理：生成内容 → 自我评估（Critic）→ 优化内容（Refine）。
• 应用：ReflectionWriterAgent基于ReflectionAgent构建，max_iterations=2，自定义三阶段提示词（initial/reflect/refine）：先写初稿，再以评审专家视角从"内容质量 40 分、结构逻辑 30 分、语言表达 20 分、格式规范 10 分"四个维度反思（85 分以上则回答"无需改进"），最后按Next Steps行动点优化。
• 优势：显著提升内容质量，模拟人类"写完读一遍再改"的创作习惯。

4. Independent Review（独立评审）——ReviewerAgent+RevisionAgent

• 原理：
  • ReviewerAgent（基于SimpleAgent）：按 REVIEWER_PROMPT 对内容进行多维度评审，输出详细评分（内容质量 40 分、结构逻辑 30 分、语言表达 20 分、格式规范 10 分）、优点清单、问题清单（含类别、严重程度、位置、问题描述、修改建议、影响）以及优先级修改计划，评级分为优秀（85-100）/良好（75-84）/需改进（60-74）/不合格（<60）；
  • RevisionAgent（基于SimpleAgent）：按REVISION_PROMPT根据评审意见进行针对性修改，要求保留优点、严格按照"优先修改项"改写、控制字数在目标 ±10% 范围内，并输出revised_content、revision_summary（主要修改/次要修改/保留优点）与字数变化。
• 优势：专业分工，评审标准统一，可追溯评审历史，支持多轮修改直到达标。

模型与工具配置

模型支持

通过config.py配置，支持多种 LLM 后端，包括任何兼容 OpenAI 接口格式的模型。源码中Settings同时兼容新旧两套字段名（llm_api_key/openai_api_key、llm_base_url/openai_base_url、llm_model_id/openai_model），get_settings()会做自动映射，避免历史配置失效。默认llm_model_id为gpt-4，默认llm_base_url为https://api.openai.com/v1，请求超时llm_timeout=180秒。

工具集成

1. SearchTool（联网搜索）：支持后端 Tavily（推荐）、SerpApi 等。_setup_search_tool()在检测到TAVILY_API_KEY或SERPAPI_API_KEY时初始化SearchTool，并注册 4 个适配写作提示词的包装函数：web_search、search_recent_info、search_code_examples、verify_facts。若未配置 Key，会跳过初始化并打印提示，不影响系统其余流程。
2. MCPTool（Model Context Protocol）：当环境变量GITHUB_PERSONAL_ACCESS_TOKEN存在时，注册名为github的 MCP 工具，server_command为["npx", "-y", "@modelcontextprotocol/server-github"]，支持搜索 GitHub 仓库、查看文件内容、分析代码结构，非常适合编写技术类专栏。注意这要求本机已安装 Node.js/npx。

配置参数详解：一个.env掌控全流程

config.py 使用pydantic-settings加载.env，核心配置项如下：

其中get_word_count(level)按层级返回目标字数（未匹配层级默认 400），字数要求会同时写入写作任务和评审/修改任务，作为质量约束的一部分。

优化特性：让系统"稳得住、跑得久"

1. 智能缓存机制（Smart Caching）

• Planner 缓存：PlannerAgent内部定义了CachedExecutor类（继承PlanAndSolveAgent的Executor），会缓存规划阶段的每个步骤结果——缓存文件以"主题 + 步骤索引 + 步骤内容"的 MD5 哈希命名，保存到.cache/steps_cache/目录，并校验主题与步骤是否匹配，避免脏缓存命中。如果主题相同，再次运行时会直接加载缓存，节省 Token 和时间。
• 文件缓存：完整规划结果（ColumnPlan）以主题哈希命名持久化到本地.cache/plan_<hash>.json，plan_column(main_topic, use_cache=True)时优先加载。

图：规划结果缓存机制，相同主题二次运行可直接复用，避免重复生成

2. 模型输出解析（Robust Parser）

utils.py 中的JSONExtractor实现了增强版 JSON 解析器，按顺序依次尝试 5 种提取策略：

1. _extract_from_finish：从Finish[...]标准格式提取；
2. _extract_direct_json：直接解析以{开头的纯 JSON；
3. _extract_from_markdown_json：提取```json代码块中的 JSON；
4. _extract_from_markdown：从 Markdown 代码块提取；
5. _extract_from_braces：从混杂文本中截取花括号片段。

同时支持required_fields（必需字段校验，优先选择包含必需字段的候选）与fallback_fields（缺失字段默认值），并可"从历史对话（history）中回溯提取有效信息"（_extract_from_history），防止因某次输出格式错误导致整个任务失败。ReviewerAgent在解析失败时还会返回一个默认评审结果（60 分、需改进），保证流程不中断。

3. 错误恢复（Error Recovery）

ReActAgentWrapper通过包装ReActAgent实现三层容错：

• 拦截_parse_output，统一使用parse_react_output解析，兼容格式漂移；
• 拦截llm.invoke捕获所有原始 LLM 响应（last_raw_responses），当run()返回空响应、占位符（如"JSON内容"）或"无法在限定步数内完成"等错误消息时，直接从最后一次原始响应中提取 JSON，最大化挽救已有工作成果；
• 当ReActAgent达到最大步数或执行失败时，_generate_content_with_history()自动回退到SimpleAgent，利用最后 10 条历史信息（Thought/Action/Observation）基于history_summary直接生成结果，确保流程不直接终止。

图：ReAct 输出解析失败时的自动恢复与降级处理逻辑

快速开始

1. 安装依赖

pip install -r requirements.txt

依赖清单（requirements.txt）核心为：hello-agents>=0.1.0（框架）、python-dotenv、pydantic>=2.0.0、pydantic-settings>=2.0.0，可选依赖包括fastmcp>=2.0.0（MCP 支持）、tavily-python>=0.3.0与google-search-results>=2.4.2（搜索，至少安装一个）。项目还提供了pyproject.toml与uv.lock，熟悉 uv 的开发者可直接用uv sync管理环境。

2. 配置环境变量

复制env.example到.env并填写配置（.env由config.py通过load_dotenv()自动加载）：

# LLM 配置 OPENAI_API_KEY=your_key OPENAI_BASE_URL=... # 搜索配置 (可选，但推荐) TAVILY_API_KEY=tvly-... # 或 SERPAPI_API_KEY=... # GitHub MCP (可选) GITHUB_PERSONAL_ACCESS_TOKEN=...

3. 运行

# 交互式模式 python main.py # 命令行模式 python main.py "Python 异步编程"

main.py 的交互逻辑是：未传参数时提示输入主题（直接回车使用默认主题"Python异步编程完全指南"），随后询问写作模式——输入1使用 ReActAgent 模式（默认），输入2使用 ReflectionAgent 模式；若选择 ReAct 模式还会再询问是否启用独立评审流程（默认启用，通过阈值取自settings.approval_threshold）。运行结束会打印文章总数、总字数、平均字数以及生成/评审/修改/重写次数与各 Agent 模式明细。

4. 查看结果

运行完成后，结果保存在output_YYYYMMDD_HHMMSS目录下，包含：

• column_data.json：完整结构化数据；
• topic_xxx_<标题>.md：每篇文章的 Markdown 文件（正文 + 元数据，含评审分数、等级、修改记录）；
• REPORT.md：统计报告，含专栏信息、内容统计、Agent 模式、创作统计（开始/结束时间、总耗时、生成调用、评审/修改次数）与文章列表（每篇字数、模式、评分）。

图：输出目录中的文章文件与统计报告结构

真实产出示例：从主题到三篇文章只需一分钟

仓库自带了两个真实运行结果，可直观验证系统效果：

以 output_20251121_190555/REPORT.md 为例，输入主题为"JavaScript 异步编程"，系统在约69.2 秒内完成规划与写作（3 次生成调用），产出 3 篇文章、共3191 字，平均每篇 1063 字：

1. 揭秘JavaScript异步编程的本质与Event Loop机制（1264 字）
2. 从回调地狱到优雅的Promise与async/await（1049 字）
3. 精通JavaScript异步：高级模式、并发控制与性能优化（878 字）

三篇文章的 Agent 模式均为ReActAgent，Planner 为PlanAndSolveAgent，主题从"Event Loop 原理"到"Promise/async-await 演进"再到"并发控制与性能优化"，呈现清晰的递进式知识链，正是 PLANNER_PROMPT 中"从基础到高级、从理论到实践"规划原则的直接体现。另一个输出目录output_20251125_201358/则展示了"前端工程化"主题下 4 篇文章的规划结果（导论与基础构建 → 自动化构建 → 质量保障与持续交付 → 高级优化架构与未来趋势）。

适用场景与使用建议

• 技术专栏批量生产：给定主题即可自动生成结构完整、内容详实、带质量评分的多篇技术文章，适合作为内容团队的辅助工具。
• 多 Agent 范式教学样本：同一系统内串联 Plan-and-Solve（规划）、ReAct（写作+工具调用）、Reflection（自我反思）与独立评审/修改四种范式，且每类 Agent 均可在源码中对照其提示词与调用链，是学习多智能体编排的优秀参考。相关范式原理可对照仓库 docs/chapter4/Chapter4-Building-Classic-Agent-Paradigms.md 与 code/chapter4 中的示例代码。
• 关键调优点：内容深度由max_depth与各级word_count_level_x控制；质量与成本平衡由approval_threshold、revision_threshold、max_revisions调节；enable_review=False可跳过评审仅快速生成；enable_search=False可离线运行（内容时效性会下降）。

需要注意的适用前提：系统依赖外部 LLM API（默认 OpenAI 兼容接口）与可选搜索/GitHub 服务，未配置对应 Key 时相应功能会自动降级；当前版本enable_parallel默认为False，多话题按顺序逐个写作；输出为中文场景下可直接使用，其他语言需在提示词中补充语言约束。

总结

ColumnWriter 项目的价值在于：它不是一个"一键生成文章"的黑盒脚本，而是一条可观测、可配置、可容错的多智能体创作流水线——用 Plan-and-Solve 保证内容结构的全局合理性，用 ReAct 让写作过程与实时信息联动，用独立评审/反思机制形成质量闭环，再用缓存与降级策略提升鲁棒性与经济性。如果你正在设计类似的 Agent 内容生产系统，这个仓库的模块划分、JSONExtractor解析策略、评审循环与错误恢复设计，都是值得直接借鉴的实现细节。

相关源码入口：orchestrator.py、agents.py、models.py、prompts.py、config.py、exporter.py、utils.py。

【免费下载链接】hello-agents📚 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents