1. 项目概述一个基于Gemini CLI的多智能体分析框架最近在探索如何让大语言模型LLM更结构化、更可靠地处理复杂任务时我遇到了一个非常有意思的开源项目aliafshar/brain。这不仅仅是一个简单的脚本集合而是一个设计精巧的多智能体协作框架它完全运行在Gemini CLI环境中能够将一个模糊的“目标”Goal分解、分析并最终生成一份详尽的报告。最让我着迷的是它的“自编排”Self-Orchestration理念——整个多阶段的工作流包括不同角色的智能体Agent如何交接任务都是由Gemini模型自身通过对话来协调完成的。这就像是你给一个“大脑”下达了一个高级指令它自己就能组织起一个虚拟的“公司”让里面的“CEO”、“项目经理”、“研究员”各司其职协同工作最终给你一份董事会级别的分析报告。这个框架非常适合那些需要深度研究、信息整合和结构化输出的场景。比如你想分析“AI对某个特定行业的影响”、“评估一个新技术的市场前景”或者“梳理某个复杂事件的前因后果”。传统上这需要你手动拆解问题、分步搜索、整理信息、撰写报告过程繁琐且容易遗漏。而brain框架试图将这个过程自动化、流程化通过模拟一个组织的工作方式来提升最终产出的深度和可靠性。接下来我将结合自己的实践深入拆解这个框架的设计思路、实操要点以及我踩过的一些坑希望能帮你快速上手并理解其精妙之处。2. 核心设计理念与架构拆解在深入代码和操作之前理解brain框架背后的设计哲学至关重要。它没有采用传统的、硬编码的任务流水线而是构建了一个基于角色扮演和动态工作项管理的柔性系统。2.1 “自编排”工作流让模型管理模型项目的核心创新点在于“自编排”。通常多智能体系统需要一个外部的“调度器”或“协调器”来管理智能体之间的交互和任务流转这个调度器的逻辑需要开发者预先定义。而brain框架则将此重任交给了Gemini模型本身。它是如何工作的当你通过Gemini CLI输入一个以GOAL:开头的指令时框架并不会立即开始执行某个固定脚本。相反它会将整个框架的“说明书”——包括所有智能体的角色定义、预设的工作流程阶段描述——作为上下文提供给Gemini模型。然后模型会根据当前的目标和状态自主决定下一步该调用哪个智能体、执行哪个阶段。这个过程被完整记录在transcript.md中你可以看到模型“思考”“现在目标已明确我应该进入战略制定阶段请CEO和COO出场讨论。” 这种设计极大地增强了系统的灵活性和适应性工作流不再是静态的而是根据任务动态生成的。这样设计的好处是什么可进化性工作流逻辑存在于模型的“理解”中而非硬代码里。如果未来Gemini模型的能力迭代或者你通过提示词微调了智能体的行为整个系统的协作效率可能会自动提升。容错与调整在任务执行中如果某个环节产出不理想模型可以在后续的评审阶段如C-Suite Review发现问题并自主发起新一轮的分解与执行形成迭代循环。降低开发复杂度开发者无需精确预定义所有可能的任务路径只需定义好智能体角色和阶段目标剩下的“管理”工作交给大模型。2.2 智能体角色系统模拟真实组织架构框架的效力很大程度上来源于其精心设计的智能体角色。这些角色定义在agents.md文件中每个角色都有明确的职责、专业领域甚至“性格”。核心角色层级C-Suite战略层如ChiefExecutiveOfficerCEO、ChiefOperatingOfficerCOO。他们的职责是在第一阶段对初始目标进行高层级的战略分析界定范围定义成功标准。相当于项目的“决策委员会”。项目管理层战术层如SeniorProjectManager高级项目经理、JuniorProjectManager初级项目经理。他们负责将战略目标分解为具体的“史诗”Epic和“工作项”WorkItem。这是将模糊方向转化为可执行任务的关键环节。执行层工人层如Researcher研究员、Analyst分析师、Writer写手。他们是具体任务的执行者负责搜索信息、分析数据、编写内容等。框架允许你根据任务类型自定义更多的执行角色。合成层报告层如JuniorReportWriter初级报告撰写员、SeniorReportWriter高级报告撰写员。他们负责阅读整个工作过程的记录transcript.md整合所有发现撰写结构化的最终报告。角色定义的关键每个角色的描述Persona不仅仅是“它是一个研究员”而会包含更细致的指引例如“你是一个严谨、注重数据来源的研究员擅长从学术论文和行业报告中提取关键信息并对信息的时效性保持警惕。” 这样的描述能更好地引导模型扮演该角色产生更符合预期的行为。2.3 工作项WorkItem驱动模型整个框架的任务执行单元是WorkItem。你可以把它理解为一个标准的工单或任务卡包含两个核心字段description任务描述需要清晰、可操作。result任务执行的结果由负责的智能体填写。项目管理层智能体的核心产出就是将战略分解为一个WorkItem列表并为每个WorkItem指派最合适的执行层智能体。这个列表构成了第三阶段执行阶段的待办事项队列。所有WorkItem的执行过程、智能体的思考链Chain-of-Thought和结果都会被忠实记录形成了项目完整的“数字足迹”。3. 环境准备与初始配置详解要让brain框架跑起来你需要一个合适的运行环境。它完全基于Google的Gemini CLI构建因此所有准备工作都围绕此展开。3.1 基础环境搭建首先你需要确保拥有以下前提条件Python环境建议使用Python 3.9或更高版本。我习惯使用pyenv或conda来管理独立的Python环境避免包冲突。# 使用conda创建并激活环境示例 conda create -n brain-framework python3.9 conda activate brain-frameworkGemini API密钥你需要一个Google AI Studio的账户并生成一个API密钥。这个密钥是Gemini CLI与模型通信的凭证。安装Gemini CLI这是核心工具。通过pip安装官方命令行工具。pip install google-generativeai # 安装后通常可以通过 gemini --help 测试是否安装成功 # 注意有时命令行工具名可能是 google-generativeai 或 genai请以官方文档为准。注意Gemini CLI的安装方式和命令可能随官方更新而变化。如果上述gemini命令无效请务必查阅最新的 Google AI Python SDK文档 确认正确的安装包名和启动命令。我最初就在这里卡了一会儿发现安装的是库而非命令行工具需要额外安装一个CLI包装。3.2 获取与配置Brain框架克隆仓库git clone https://github.com/aliafshar/brain.git cd brain项目结构初窥进入目录后你会看到几个关键文件和文件夹agents.md智能体角色定义文件。这是你需要重点理解和可能自定义的文件。GEMINI.md核心提示词文件。它包含了引导Gemini进行自编排工作流的系统级指令。理解这个文件是理解项目灵魂的关键。info/目录用于存放预读材料。runs/目录所有任务运行的记录和产出物都会存储在这里。可能还有其他配置文件如config.json或requirements.txt配置API密钥你需要将获取的Gemini API密钥设置为环境变量。这是最常见的方式。# 在Linux/macOS的终端中 export GOOGLE_API_KEY你的_实际_API_密钥 # 在Windows的PowerShell中 $env:GOOGLE_API_KEY你的_实际_API_密钥实操心得为了避免每次打开终端都要重新设置我建议将这条导出命令添加到你的shell配置文件如~/.bashrc,~/.zshrc或Windows的环境变量设置中。但要注意不要在公开的代码或日志中泄露此密钥。3.3 预读材料Info目录的妙用info目录是一个非常有用的功能它允许你为智能体提供“背景资料”。在开始一个分析目标前你可以将相关的文档如市场报告、技术白皮书、新闻摘要的.txt或.md文件放入此目录。工作流程将文件支持.md,.txt,.pdf等格式放入./info。当你启动一个GOAL:时框架会自动扫描该目录列出所有文件让你选择。你选择的文件内容会被注入到本次任务运行的初始上下文中所有智能体都会知晓这些信息。这个功能的价值领域知识注入如果你要分析一个专业领域如量子计算可以放入基础术语解释文档让智能体从一开始就具备相关知识避免从零开始“胡诌”。公司内部资料分析可以放入内部财报、会议纪要让框架基于这些非公开信息进行分析。保证信息源质量通过提供精选的高质量材料你可以引导智能体在可靠的信息基础上进行分析减少其依赖可能过时或不准确的网络知识在当前框架的默认设置下执行层智能体可能会基于其内部知识生成内容而非实时搜索。注意事项PDF文件的解析质量取决于Gemini模型的多模态解析能力。对于复杂的图表或特殊排版信息提取可能会有损耗。对于关键材料我通常额外准备一个纯文本或Markdown的摘要版本放入info目录作为主要参考。4. 完整工作流程实操演练让我们用一个具体的例子贯穿brain框架的整个生命周期。假设我们的目标是“分析远程办公常态化对一线城市商业地产市场的潜在影响并预测未来三年的趋势”。4.1 第一阶段目标启动与战略制定启动CLI并输入目标# 在brain项目根目录下执行 gemini # 等待CLI交互界面启动后输入 GOAL: 分析远程办公常态化对一线城市商业地产市场的潜在影响并预测未来三年的趋势。选择预读材料如果你在info目录下放置了《2023年中国办公楼市场回顾》、《远程办公效率研究报告》等文件此时CLI会列出它们供你选择。你可以选择全部或部分。观察C-Suite讨论启动后框架会加载agents.md中的CEO、COO等角色。你会在transcript.md中看到一场虚拟的高层会议。CEO可能会说“我们的目标是分析远程办公对商业地产的影响。COO你认为我们应该从哪几个维度来界定这个问题的分析框架” COO可能会回应“我认为需要从需求侧企业租赁需求、供给侧写字楼供应、价格指标、以及不同细分业态甲级写字楼、联合办公等维度切入并设定以空置率、租金变化和资本价值作为核心评估指标。”这个阶段的输出是一个被重新厘清和细化的战略目标例如“本次分析将聚焦于北京、上海、深圳三个一线城市从企业租赁行为变化、写字楼市场供需数据、资产估值模型三个层面展开最终输出对2024-2026年市场趋势的定性判断与定量预测区间。”4.2 第二阶段战术分解与任务规划战略确定后SeniorProjectManagerSPM登场。它的任务是将“分析企业租赁行为变化”这样的战略目标分解成几个“史诗”Epic比如Epic 1 收集并分析近三年一线城市企业写字楼新增租赁与退租数据。Epic 2 调研主要科技公司与金融机构的远程办公政策及其对办公空间的实际调整案例。Epic 3 建立远程办公渗透率与写字楼需求之间的相关性分析模型。接着JuniorProjectManagerJPM会将每个史诗细化为具体的WorkItem并分配给执行层智能体。例如针对Epic 1可能产生以下WorkItemWorkItem 1分配给Researcher查找并总结仲量联行JLL、世邦魏理仕CBRE发布的2021-2023年北上深写字楼市场报告中的关键数据。WorkItem 2分配给Analyst对比疫情前后2019 vs 2022甲级写字楼净吸纳量的变化趋势并计算同比变化率。WorkItem 3分配给Researcher搜集关于“办公空间人均面积标准”在近年的调整趋势及相关政策动向。这个阶段的关键在于任务描述的清晰度。一个模糊的指令如“研究数据”会导致执行层智能体困惑。一个好的WorkItem描述应该是“从公开的行业报告中提取北京、上海、深圳三个城市在2021、2022、2023年的甲级写字楼空置率、平均租金数据并以表格形式呈现。”4.3 第三阶段任务执行与过程记录执行层智能体开始逐个处理WorkItem。框架会按照列表顺序将每个WorkItem的description和当前上下文包括之前的讨论和结果发送给指定的智能体。内部思考过程智能体不会直接输出答案。在transcript.md中你会先看到它的“内心独白”例如“我是Researcher我需要找到JLL和CBRE的报告。这些报告通常在其官网的‘研究’或‘洞察’板块。我需要提取的是具体数值而不是观点性描述。我回忆一下空置率通常以百分比表示租金以每平方米每月人民币元表示...”执行与产出思考完毕后智能体会执行“动作”在当前框架中可能表现为基于其知识生成内容或模拟调用搜索工具并将结果填入WorkItem的result字段。这个结果可能是生成的文本、模拟的数据表格或分析结论。全程记录所有这一切包括思考过程和最终结果都被追加到transcript.md中。这个文件因此变得非常庞大但也包含了完整的决策链条对于后续的复核和报告撰写至关重要。踩坑实录在这个阶段我最初发现智能体有时会“捏造”数据源。例如它可能说“根据CBRE 2023年Q4报告北京空置率为18.5%”但这个数字可能是它基于模式生成的并非真实数据。解决方案一是充分利用info目录提供真实数据源二是在agents.md中强化Researcher角色的提示词要求其必须注明数据来源如果无法找到确切来源应明确声明“基于模型知识进行的趋势性推断”。4.4 第四与第五阶段报告合成与高层评审当所有WorkItem执行完毕报告撰写智能体开始工作。初级报告撰写JuniorReportWriter会通读整个transcript.md这个文件可能已有数千行尝试提取关键信息组织成一个初步的报告草稿保存为report.md。这份草稿可能结构松散重点不突出。高级报告润色SeniorReportWriter会对草稿进行重构、润色和精炼确保其符合“董事会报告”的质量要求具备清晰的执行摘要、严谨的方法论说明、分章节的详细分析和明确的结论建议。C-Suite评审CEO和COO等高层角色再次出场审阅这份report.md。他们会对照第一阶段制定的战略目标来评估报告。如果通过运行结束report.md即为最终交付物。如果需要修改他们会提出具体反馈例如“报告对科技公司案例的分析深度不足需要补充至少三个具体公司的办公空间调整策略及其量化影响。” 或者“未来三年预测部分缺乏敏感性分析请补充在不同远程办公渗透率情景下的市场预测。”4.5 迭代循环让分析走向深入如果C-Suite提出了反馈框架的精妙之处就显现了。反馈会被视为新的“高层目标”流程将跳回第二阶段。SPM和JPM会根据反馈创建新的WorkItem例如“WorkItem N: 深入调研腾讯、阿里巴巴、字节跳动三家公司自2020年以来的远程办公政策演变及其对总部与分部办公面积的实际影响。”新的WorkItem进入执行队列由相应的Researcher或Analyst完成。完成后报告撰写员会再次整合新内容更新report.md。更新后的报告再次提交C-Suite评审。这个循环可以持续多次直到报告质量满足要求。这模拟了真实世界中一份高质量的分析报告需要多轮修改和深化的过程。5. 核心文件解析与自定义指南要真正驾驭brain框架甚至根据自己需求进行定制必须理解其核心配置文件。5.1agents.md定义你的智能体团队这个文件是框架的“角色剧本”。每个智能体用一个二级标题##定义标题名就是角色名如## ChiefExecutiveOfficer。标题下的内容就是该角色的“人设”提示词。自定义智能体示例 假设你需要一个专注于金融数据分析的智能体可以添加## QuantitativeAnalyst 你是一名顶级的量化分析师擅长处理金融市场数据精通统计学和计量经济学模型。你的风格极其严谨任何结论都必须有数据支撑。你擅长使用类比来解释复杂的金融概念例如将波动率比喻为“市场的情绪温度计”。在进行分析时你总是优先考虑数据的清洁度和来源可靠性并会明确指出分析中的局限性。自定义要点明确职责清晰定义他/她负责什么类型的WorkItem。塑造性格与专长细节描述能让模型扮演得更逼真。“严谨”、“注重数据源”、“擅长用比喻”这些都是有效的引导词。设定约束可以加入约束如“在无法获取真实数据时应构建合理的理论模型进行推演并明确说明此为模拟数据”。5.2GEMINI.md框架的“操作系统”这个文件是发送给Gemini模型的“系统指令”定义了整个多智能体工作流的规则。它通常包含框架介绍告诉模型这是一个多智能体系统。角色说明指示模型根据agents.md来扮演不同角色。工作流阶段描述大致说明Initiation, Strategy, Planning, Execution, Reporting, Review这几个阶段应该做什么。输出格式要求规定如何记录transcript如何更新WorkItem的状态和结果。自编排逻辑核心指令告诉模型在给定当前上下文目标、已完成的工作、现有报告时应如何决定下一步行动——是召集某个角色开会还是执行某个任务。修改风险提示GEMINI.md是框架最核心的“逻辑”修改它相当于给整个系统“重装操作系统”。除非你非常了解提示词工程和多智能体协调否则建议先深入理解原有内容再进行微调。一个常见的微调点是优化评审标准例如让C-Suite在评审时更关注“数据图表是否清晰”或“风险部分是否充分”。5.3transcript.md与report.md产出物分析transcript.md这是整个项目的“黑匣子”或“审计日志”。它对于调试和理解智能体行为不可或缺。当结果不如预期时查阅transcript中对应智能体的“思考过程”能帮你发现是角色定义不清、任务描述模糊还是模型本身的知识局限。report.md这是最终产品。框架的目标是生成结构清晰、论据充分、可直接使用的报告。你可以通过修改SeniorReportWriter的角色定义来改变报告的文风如更学术化或更商务化和固定结构如要求必须包含“方法论局限性”章节。6. 常见问题、局限性与优化策略在实际使用中你一定会遇到一些挑战。以下是我总结的常见问题及应对思路。6.1 问题一智能体“跑偏”或陷入循环现象智能体在某个问题上反复讨论无法达成共识或者执行的任务与核心目标渐行渐远。原因初始GOAL描述不够具体导致战略阶段无法形成清晰方向。智能体角色定义存在职责重叠或冲突。在迭代评审中C-Suite的反馈不够具体导致下一轮任务分解依然模糊。解决策略精炼目标使用SMART原则具体、可衡量、可达成、相关、有时限来构思你的GOAL。例如将“分析影响”改为“从供需、租金、空置率三个维度定量与定性结合分析2021-2023年远程办公对北京甲级写字楼市场的影响并给出2024年租金走势的预测区间”。明确角色边界在agents.md中为每个角色明确写上“不负责”什么。例如在Researcher中强调“你只负责信息搜集与整理不负责数据建模与深度分析”。提供具体反馈当报告需要修改时在评审环节或模拟评审时提供像“请在第三章补充一个对比表格列出五家代表性公司在2022与2023年的平均人均办公面积”这样具体的指令。6.2 问题二信息“幻觉”与事实准确性现象智能体生成的内容包含看似合理但实际不存在的数字、事件或引用。原因这是当前大语言模型的固有限制在缺乏足够准确上下文时会基于模式生成内容。缓解方案强化info目录使用这是对抗幻觉最有效的手段。提供高质量的、结构化的背景资料。定制Researcher角色在其描述中强烈要求“对于任何关键数据、引用、案例必须注明可公开访问的来源。如果无法确认应使用‘据行业一般认知’、‘模型推断’等措辞并说明此为估算或趋势判断”。后置人工审核将框架的产出视为“初稿”或“素材汇编”关键的数据和结论需要人工进行二次核实。框架的价值在于完成了信息搜集、初步整合和报告搭建的繁重工作。6.3 问题三运行速度慢与Token消耗大现象分析一个复杂目标可能需要很长时间并且由于transcript.md不断增长每次交互的上下文越来越长导致API调用缓慢且费用增加。原因自编排模式需要将整个工作历史作为上下文传递给模型以决定下一步行动。长上下文会导致延迟和成本上升。优化策略阶段性总结目前框架原生不支持但你可以通过修改提示词尝试让SeniorReportWriter或一个新增的Summarizer角色在每轮迭代后生成一个高度浓缩的“阶段摘要”用以替代部分冗长的历史transcript作为下一轮的上下文。设定迭代上限在GEMINI.md中为C-Suite评审阶段加入规则例如“最多进行三轮迭代修改第三轮后必须给出最终结论即使存在未完美解决的问题”。拆分大目标将一个庞大的目标手动拆分成几个逻辑上相对独立的子目标分别运行brain最后人工合成总报告。例如先分析“对需求端的影响”再分析“对供给端的影响”。6.4 问题四对复杂逻辑与深度推理的局限现象框架擅长信息搜集、整理和基于模板的报告生成但对于需要高度创造性、复杂逻辑链推理或解决全新未知问题如前沿科学研究的任务表现可能不尽如人意。认识局限brain框架本质上是一个流程自动化和信息处理的增强工具它放大了LLM在文本处理和组织方面的能力但并未突破其底层模型在深度推理上的天花板。它模拟的是“分析团队”的流程而非“天才科学家”的直觉。合理预期将其用于市场分析、竞品调研、文献综述、方案利弊罗列、标准报告撰写等场景效果最佳。对于开创性的理论构建或解决定义模糊的复杂问题仍需依赖人类的智慧。7. 高级技巧与扩展思路当你熟悉基础用法后可以尝试以下进阶玩法让这个框架更加强大。7.1 创建领域专属的智能体团队为特定领域定制一套智能体。例如做一个“网络安全事件分析”框架ThreatHunter负责模拟攻击链推测入侵路径。ForensicAnalyst负责分析模拟的日志数据寻找异常痕迹。ComplianceOfficer负责评估事件违反哪些安全条例或标准。IncidentResponseManager负责编写应急响应报告和后续整改建议。 然后提供一个如“分析某次数据泄露事件的根本原因与责任归属”的GOAL让这个专业团队协作。7.2 集成外部工具与实时数据当前框架的智能体主要依赖模型的内置知识。你可以通过改造框架让智能体具备“行动能力”。思路修改框架底层代码当Researcher智能体需要数据时不是让其生成而是让其“提出搜索查询”。然后你可以拦截这个查询通过代码调用搜索引擎API、金融数据API如Alpha Vantage、学术数据库API等获取真实、实时的数据再喂回给智能体进行分析。实现挑战这需要较强的编程能力涉及到对框架运行机制的深度理解和对Gemini API调用的封装改造。但这能将框架从一个“基于知识的模拟器”升级为“连接真实世界的自动分析引擎”。7.3 实现多轮对话与持续学习目前的brain框架是“单次任务”导向的。你可以设想一个扩展场景将其与一个长期运行的聊天机器人结合。用户首次提问brain启动一个完整的分析流程生成报告。报告被存储到知识库。当用户后续提出相关问题时聊天机器人可以先在知识库中检索已有报告如果已有相关分析则直接引用如果问题超出了已有报告范围则再次触发brain启动一个新的分析流程。这样系统就具备了“记忆”和“持续学习”的能力像一个真正的分析师团队在为你服务。aliafshar/brain项目为我们提供了一个极具启发性的范式展示了如何利用大语言模型的对话和角色扮演能力来构建一个能够自主管理复杂流程的智能系统。它的价值不在于解决某个具体问题而在于提供了一套可复用的“方法论”和“脚手架”。通过理解其自编排的核心思想、灵活的角色定义和基于工作项的任务管理机制我们可以将其适配到无数需要结构化分析、研究和报告生成的场景中。当然它目前仍是一个实验性项目对幻觉的控制、对复杂推理的处理以及运行成本都是实际应用中需要权衡的问题。但毫无疑问沿着这个方向探索我们正在一步步地将AI从“对话伙伴”转变为能够管理复杂项目的“智能协作者”。