尧图网站建设 
Hello-Agents 共创项目实战指南从智能体应用开发到开源贡献的完整流程【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents《从零开始构建智能体》Hello-Agents教程的Co-creation-projects共创项目区是学习者将前十六章所学智能体范式、工具系统、记忆机制、通信协议等转化为真实作品的展示与协作空间。本文以该共创项目区规范为骨架完整讲解从项目选题、命名、目录结构搭建、Notebook 开发、README 撰写到 Fork 仓库并提交 Pull Request 的全流程并结合仓库内的项目模板、框架源码与社区真实作品给出可复制、可运行的实战方案。读完本文你将掌握一套标准的智能体应用开源交付流程能够独立完成一个符合规范的共创项目。一、共创项目区是什么学习者作品的展示与协作空间Co-creation-projects目录是 Hello-Agents 仓库中专为学习者开辟的作品集区域定位非常明确这里是学习者展示自己多智能体应用的地方。与教程正文的code/各章随堂代码和docs/章节文档不同这里的每个子目录都是一位社区成员从零开发、独立维护的完整项目。从仓库目录结构可以看到该区域已经沉淀了大量形态各异的作品覆盖从单文件脚本到前后端分离的全栈应用基于 Notebook 的轻量项目如 1zrj-DataAnalysisAgent数据分析、Henry2513-MeetingActionAgent会议行动项提取、jjyaoao-CodeReviewAgent代码审查含完整后端与前端的项目如 aatanxiao12-beep-YingQianFastAPI 后端 React/TypeScript 前端、afei-GuessWhoAmI猜人物游戏前后端分离甚至自研框架级项目如 YYHDBL-HelloCodeAgentCli基于 HelloAgents 二次开发的 CLI 智能体框架。这些作品的共同点是以 HelloAgents 框架或其范式思想为底座解决一个具体问题并且全部遵循统一的项目组织规范这也是本文要展开的核心内容。二、动手前的规划选题与命名规范2.1 项目命名规范共创项目区对项目文件夹命名有硬性约束格式固定为{GitHub用户名}-{项目名称}例如jjyaoao-CodeReviewAgentzhangsan-StudyBuddylisi-DataAnalyst命名即身份前缀绑定 GitHub 账号保证项目归属清晰、便于溯源后缀描述项目功能让读者仅凭目录名即可判断项目主题。这一点与 docs/chapter16/第十六章 毕业设计.md 中毕业设计项目的命名要求完全一致第 16.1.2 节共创项目本质上就是毕业设计作品的承载形态。2.2 选题原则与推荐方向毕业设计章节16.2 节给出了明确的选题原则项目应具有实用性解决真实问题而不是为了技术而技术同时要在有限的时间和资源内可以完成并能清晰展示技术能力。共创项目区官方将作品划分为五大类每一类都有对应的真实作品作为参考分类方向举例仓库中的代表项目生产力工具代码审查、文档生成、会议纪要、邮件助手jjyaoao-CodeReviewAgent学习辅助学习伙伴、论文助手、编程导师、语言学习chengH425-PaperAssistant、chen070808-ProgrammingTutor创意娱乐故事生成、游戏 NPC、音乐推荐、菜谱lgs-only-NovelGenerator数据分析数据分析、股票分析、舆情监控、竞品分析1zrj-DataAnalysisAgent、CC1227871-StockInsightAgent生活服务健康助手、理财助手、购物助手、家居控制Shawnxyxy-HealthRecordAgent以毕业设计章节中的智能代码审查助手CodeReviewAgent选题示例来看一个合格的选题需要同时想清楚三件事问题分析代码审查是软件开发的重要环节但人工审查耗时且易遗漏静态分析工具只能发现语法错误、无法理解语义因此需要一个能理解代码逻辑的 LLM 智能助手核心功能代码质量分析风格、命名、注释、潜在 bug 检测、性能优化建议、最佳实践推荐预期成果可运行的 Notebook 展示完整审查流程输出结构化的 Markdown 审查报告。社区真实项目 jjyaoao-CodeReviewAgent 正是该选题的落地通过CodeAnalysisToolPython AST 解析结构与StyleCheckToolPEP 8 风格检查两个工具配合SimpleAgent实现了代码结构分析、风格检查、LLM 深度建议与报告生成四合一的能力。三、项目结构标准最小必备三件套共创项目区对每个项目的最基本要求是包含三个必备文件你的用户名-项目名称/ ├── README.md # 项目说明文档必需 ├── requirements.txt # Python依赖列表必需 ├── main.ipynb # 主要的Jupyter Notebook必需 └── ... # 其他文件可选README.md项目的门面承担让读者三分钟看懂项目的职责requirements.txt完整声明 Python 依赖保证pip install -r requirements.txt即可复现运行环境main.ipynb可运行的 Jupyter Notebook是项目功能的主载体要求打开即可运行、按序执行即可复现结果。除此之外社区项目普遍还会补充以下可选目录参见 jjyaoao-CodeReviewAgent 与毕业设计章节 16.3.3 节的推荐结构你的用户名-项目名称/ ├── .env.example # 环境变量示例API 密钥占位 ├── .gitignore # Git 忽略规则忽略 .env、大文件、输出 ├── data/ # 示例数据只放小规模样例 ├── outputs/ # 输出结果报告、截图、图表 └── src/ # 代码较多时拆分的源码包agents/tools/utils其中.env.example与.gitignore虽然不在三件套硬性要求中但几乎所有高质量项目都会包含前者让使用者知道需要配置哪些环境变量后者防止 API 密钥与输出文件被误提交到仓库。四、用官方模板快速起步共创项目区提供了官方起点 EXAMPLE-ProjectTemplate包含一份标准的 README 模板 与一份可直接套用的 main.ipynb。4.1 README 模板的结构拆解模板要求 README 至少覆盖以下板块每个板块都有明确目的板块目的项目名称 一句话简介让读者 3 秒内判断项目是否相关项目简介说明解决什么问题、特色功能、适用场景核心功能以勾选清单列出功能点技术栈声明使用的框架、范式ReAct、Plan-and-Solve 等、工具与 API快速开始环境要求 → 安装依赖 → 配置 API 密钥 → 运行项目使用示例代码示例与运行结果项目亮点 / 性能评估突出技术特色有评测数据则如实展示未来计划 / 贡献指南 / 许可证 / 作者 / 致谢项目的社区化收尾其中快速开始是模板着墨最多的部分标准流程为# 1. 安装依赖 pip install -r requirements.txt # 2. 创建 .env 文件并填入 API 密钥 cp .env.example .env # 编辑 .env 文件 # OPENAI_API_KEYyour_key_here # 3. 启动 Jupyter 并运行 main.ipynb jupyter lab环境要求模板中明确写有Python 3.10这也是 Hello-Agents 教程全书的运行基准版本。4.2 Notebook 模板的六段式结构模板 main.ipynb 将项目 Notebook 划分为六个逻辑段落这套结构被社区大量作品沿用项目介绍Markdown项目名称、简介、作者信息姓名、GitHub、日期环境配置安装依赖、导入hello_agents库、load_dotenv()加载环境变量工具定义继承BaseTool编写自定义工具类智能体构建创建HelloAgentsLLM、定义系统提示词、实例化SimpleAgent并注册工具功能演示多个示例输入验证基础功能与复杂场景性能评估可选 总结与展望评测指标以及实现的功能、遇到的挑战、未来改进方向。模板中的核心代码骨架如下from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import BaseTool import os from dotenv import load_dotenv load_dotenv() class CustomTool(BaseTool): 自定义工具类 name tool_name description 工具描述 def run(self, query: str) - str: 工具执行逻辑 return f处理结果{query} llm HelloAgentsLLM() system_prompt 你是一个智能助手。 你的任务是 1. 理解用户的需求 2. 使用合适的工具 3. 提供有帮助的回答 agent SimpleAgent( name示例智能体, llmllm, system_promptsystem_prompt ) agent.add_tool(CustomTool()) result agent.run(你的测试输入) print(result)五、框架源码层面的纵深理解你正在使用的 API共创项目的开发质量取决于对 HelloAgents 框架核心 API 的理解程度。main.ipynb模板中的几行导入语句背后是框架最核心的组件from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry from hello_agents.tools import Tool, ToolParameter5.1 SimpleAgent范式封装与可扩展基类SimpleAgent是教程第七章构建的框架核心类封装了接收输入 → 组装消息 → 调用 LLM → 返回响应的基础对话链路并支持工具注册与调用。框架同时开放了继承扩展的能力——code/chapter7/my_simple_agent.py 演示了如何基于SimpleAgent基类重写run()方法实现带多轮工具调用max_tool_iterations循环与流式输出stream_run的自定义智能体。共创项目中凡是需要非标准交互逻辑的场景都可以参考这种继承基类 重写运行方法的模式。5.2 Tool / BaseTool / ToolParameter工具系统的三个层次框架的工具体系存在两套 API 形态共创项目中均有使用声明式继承BaseTool模板所用声明name、description类属性并实现run(query)方法适合快速原型参数化继承Tool并实现run(parameters: Dict)与get_parameters() - List[ToolParameter]毕业设计章节示例所用通过ToolParameter(name, type, description, required)显式声明参数 Schema更适合工具需要结构化参数、可被 LLM 可靠调用的场景。以 jjyaoao-CodeReviewAgent 的CodeAnalysisTool为例工具在run()内部使用 Python 标准库ast解析代码统计函数数、类数、代码行数并捕获SyntaxErrorStyleCheckTool则逐行检查 79 字符上限与缩进规范。这两个工具没有调用任何 LLM是纯确定性逻辑恰好演示了共创项目中确定性工具负责硬规则LLM 负责语义理解的分工原则——工具把客观事实结构统计、风格问题交给模型模型基于这些事实生成深度审查意见避免模型凭空编造代码指标。5.3 ToolRegistry工具注册与编排tool_registry ToolRegistry() tool_registry.register_tool(CodeAnalysisTool()) tool_registry.register_tool(StyleCheckTool()) agent SimpleAgent( name代码审查助手, llmllm, system_promptsystem_prompt, tool_registrytool_registry )ToolRegistry负责工具的注册、描述汇总get_tools_description用于注入系统提示词与按名执行execute_tool。当智能体配置了tool_registry后LLM 才能在对话中按需调用工具形成感知 → 决策 → 行动 → 观察的闭环。5.4 LLM 接入配置以环境变量解耦框架通过环境变量统一管理 LLM 接入社区项目普遍遵循 ModelScope 兼容的配置范式LLM_MODEL_IDQwen/Qwen2.5-72B-Instruct LLM_API_KEYyour_api_key_here LLM_BASE_URLhttps://api-inference.modelscope.cn/v1/ LLM_TIMEOUT60推荐两种配置方式.env文件推荐cp .env.example .env后编辑配合python-dotenv的load_dotenv()在 Notebook 首格加载Notebook 内直接设置os.environ[LLM_MODEL_ID] ...等方式写入环境变量适合快速演示。.env文件必须加入.gitignore仅提交.env.example占位模板避免密钥泄露。六、开发规范与质量门槛6.1 提交前的自检清单毕业设计章节16.4.4 节提供了一份提交前自检清单可直接作为共创项目的验收标准代码能够正常运行没有报错README 文档完整说明清晰requirements.txt 包含所有依赖有清晰的使用示例代码有适当的注释输出结果符合预期处理了常见的异常情况项目结构清晰文件命名规范大文件已妥善处理6.2 大文件处理规范为保持主仓库轻量化共创项目对大文件有明确限制项目总大小不超过 5MB禁止直接提交视频文件、大型数据集、模型文件。若项目确实包含大资源官方提供三种处理方案外部链接推荐将数据集上传百度网盘、Google Drive、Kaggle、HuggingFace Datasets视频上传 B 站、YouTube模型上传 HuggingFace Models、ModelScope在 README 中给出下载说明独立资源仓库为资源较多的项目单独创建项目名称-resources仓库README 中给出git clone与数据摆放说明仅提交示例数据主仓库只放小规模样例如 100 条记录的sample.csvREADME 中注明完整数据集的获取方式。最佳实践形态是data/下仅保留 1MB 示例数据outputs/下仅保留演示结果图片。6.3 requirements.txt 编写要点# 核心依赖 hello-agents[all]0.2.7 # 可视化如果需要 matplotlib3.7.0 plotly5.14.0 # Web框架如果需要 fastapi0.109.0 uvicorn0.27.0建议标注主版本下限按核心依赖 → 可视化 → Web 框架分组并加注释便于维护者理解每个依赖的用途。可参考社区作品各自的 requirements.txt 实际写法。七、从 Fork 到 Pull Request完整的开源贡献流程共创项目的提交完全走开源协作标准流程以下按顺序展开对应毕业设计章节 16.316.5 节。7.1 环境准备# 安装 HelloAgents 框架含全部可选依赖 pip install hello-agents[all] # 检查并配置 Git 用户信息 git config --global user.name 你的名字 git config --global user.email 你的邮箱 # 安装 JupyterLab推荐 pip install jupyterlab jupyter lab7.2 Fork 与克隆访问 Hello-Agents 仓库点击右上角Fork将副本创建到自己的账号下克隆自己 Fork 的仓库到本地并添加上游仓库以便同步更新git clone gitgithub.com:你的用户名/hello-agents.git cd hello-agents git remote add upstream Hello-Agents上游仓库地址 git remote -v创建独立开发分支避免污染主分支git checkout -b feature/你的项目名称 # 例如 git checkout -b feature/code-review-agent7.3 在共创目录中开发cd Co-creation-projects mkdir 你的用户名-项目名称 cd 你的用户名-项目名称在此目录内完成三件套开发、README 编写、自检与本地测试jupyter lab运行main.ipynb逐格验证。7.4 提交与推送# 查看改动 git status # 添加文件推荐只添加项目目录 git add Co-creation-projects/你的用户名-项目名称/ # 提交信息遵循 Conventional Commits 风格 git commit -m feat: 添加XXX毕业设计项目 # 推送到自己的 Fork git push origin feature/你的项目名称提交信息类型规范feat新增功能或项目毕业设计项目使用此类型、fix修复 bug、docs文档更新、style格式调整、refactor重构、test测试、chore其他修改。7.5 创建 Pull RequestPR 的关键约定有两点务必遵守① PR 标题统一格式[毕业设计] 项目名称 - 简短描述例如[毕业设计] CodeReviewAgent - 智能代码审查助手[毕业设计] StudyBuddy - AI学习伙伴[毕业设计] DataAnalyst - 智能数据分析师统一标题格式是为了让所有毕业设计/共创项目在 PR 列表中可检索、可管理。② PR 分支选择Base repositoryhello-agents主仓库Base branchmainHead repository你自己的 ForkCompare branchfeature/你的项目名称③ PR 描述建议包含项目名称与作者、项目类型生产力工具/学习辅助/创意娱乐/数据分析/生活服务、项目简介、核心功能、技术亮点、演示效果截图、自检清单代码可运行、README 完整、requirements.txt 完整、有使用示例、有注释。7.6 响应 Review 与合并提交 PR 后社区成员会进行代码 Review 并提出改进建议。正确应对方式是查看评论 → 修改代码 → 以fix: 根据review意见修改XXX之类的提交信息推送更新 → 在 PR 中回复说明修改内容。通过评审后项目会被合并进主仓库的Co-creation-projects目录成为共创项目区的一员。八、从模板到真实作品社区项目赏析模板是骨架真实作品才是血肉。以下三个项目分别代表不同复杂度层级可作为你创作时的对标参照。8.1 标准形态CodeReviewAgent生产力工具jjyaoao-CodeReviewAgent 是毕业设计章节官方引用的完整示例Notebook 内分 07 部分组织快速演示、LLM 配置、工具定义、注册表构建、智能体创建、示例运行、报告落盘将待审代码放入data/sample_code.py后运行即可在outputs/review_report.md得到结构化审查报告。它的 README 严格遵循模板章节顺序简介 → 功能 → 技术栈 → 快速开始 → 使用示例 → 亮点 → 结构 → 技术实现 → 示例输出 → 未来改进是README 规范的范本。8.2 数据驱动形态DataAnalysisAgent数据分析1zrj-DataAnalysisAgent 展示了另一类典型数据清洗工具DataCleaningTool按用户指定规则清洗表格与数据统计工具DataStatisticsTool提供描述性统计分析配合SimpleAgent将 Excel 数据转化为 ECharts 图表outputs/echarts.html与 Markdown 分析报告outputs/report.md。这类项目的价值在于演示了LLM 决策 确定性工具执行如何端到端打通数据流水线。8.3 全栈形态YingQian后端 前端aatanxiao12-beep-YingQian 将共创项目的边界推到了工程化全栈后端基于 FastAPIbackend/pyproject.toml、backend/run.py前端基于 React TypeScript Vitefrontend/并配有main.ipynb承载核心演示。它说明共创项目并不局限于 Notebook——只要三件套齐备、结构清晰、可复现运行任何复杂度形态的作品都欢迎。九、交流与许可证9.1 交流与反馈渠道共创项目区官方提供的交流方式包括在 Issue 中提问、加入 Datawhale 社区讨论、参与社区项目的 Review。Review 既是他人帮你把关质量也是你观摩学习其他作品实现思路的机会。9.2 许可证共创项目区所有作品统一遵循CC BY-NC-SA 4.0 License知识共享-署名-非商业性使用-相同方式共享欢迎学习与再创作但需注明出处、不得用于商业用途、衍生作品需以相同许可协议发布。注意这与示例项目模板 README 中写的MIT License存在差异——提交共创项目时请以项目区统一的 CC BY-NC-SA 4.0 为准。十、总结从选题命名到三件套搭建从模板套用到框架 API 的深度理解从本地自检到 Fork-PR 开源协作共创项目的完整链路并不复杂但每一步都有明确的规范可循。核心要点可以浓缩为四句话命名即规范{GitHub用户名}-{项目名称}一眼可读三件套兜底README requirements.txt main.ipynb缺一不可工具与 LLM 分工确定性逻辑交给工具语义理解交给 LLM用Tool/ToolParameter声明结构化接口流程守约定PR 标题[毕业设计] 项目名称 - 简短描述项目 ≤5MB、大文件走外部方案。无论你的作品是几十行的原型还是前后端齐全的全栈应用只要亲自实现、结构合规、文档清晰都值得被收录。正如毕业设计章节所言小的创意同样可以被收录只要是自己动手的作品都是值得珍惜的。现在去Co-creation-projects目录下创建属于你的第一个共创项目吧。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hello-Agents 共创项目实战指南：从智能体应用开发到开源贡献的完整流程
Hello-Agents 共创项目实战指南从智能体应用开发到开源贡献的完整流程【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents《从零开始构建智能体》Hello-Agents教程的Co-creation-projects共创项目区是学习者将前十六章所学智能体范式、工具系统、记忆机制、通信协议等转化为真实作品的展示与协作空间。本文以该共创项目区规范为骨架完整讲解从项目选题、命名、目录结构搭建、Notebook 开发、README 撰写到 Fork 仓库并提交 Pull Request 的全流程并结合仓库内的项目模板、框架源码与社区真实作品给出可复制、可运行的实战方案。读完本文你将掌握一套标准的智能体应用开源交付流程能够独立完成一个符合规范的共创项目。一、共创项目区是什么学习者作品的展示与协作空间Co-creation-projects目录是 Hello-Agents 仓库中专为学习者开辟的作品集区域定位非常明确这里是学习者展示自己多智能体应用的地方。与教程正文的code/各章随堂代码和docs/章节文档不同这里的每个子目录都是一位社区成员从零开发、独立维护的完整项目。从仓库目录结构可以看到该区域已经沉淀了大量形态各异的作品覆盖从单文件脚本到前后端分离的全栈应用基于 Notebook 的轻量项目如 1zrj-DataAnalysisAgent数据分析、Henry2513-MeetingActionAgent会议行动项提取、jjyaoao-CodeReviewAgent代码审查含完整后端与前端的项目如 aatanxiao12-beep-YingQianFastAPI 后端 React/TypeScript 前端、afei-GuessWhoAmI猜人物游戏前后端分离甚至自研框架级项目如 YYHDBL-HelloCodeAgentCli基于 HelloAgents 二次开发的 CLI 智能体框架。这些作品的共同点是以 HelloAgents 框架或其范式思想为底座解决一个具体问题并且全部遵循统一的项目组织规范这也是本文要展开的核心内容。二、动手前的规划选题与命名规范2.1 项目命名规范共创项目区对项目文件夹命名有硬性约束格式固定为{GitHub用户名}-{项目名称}例如jjyaoao-CodeReviewAgentzhangsan-StudyBuddylisi-DataAnalyst命名即身份前缀绑定 GitHub 账号保证项目归属清晰、便于溯源后缀描述项目功能让读者仅凭目录名即可判断项目主题。这一点与 docs/chapter16/第十六章 毕业设计.md 中毕业设计项目的命名要求完全一致第 16.1.2 节共创项目本质上就是毕业设计作品的承载形态。2.2 选题原则与推荐方向毕业设计章节16.2 节给出了明确的选题原则项目应具有实用性解决真实问题而不是为了技术而技术同时要在有限的时间和资源内可以完成并能清晰展示技术能力。共创项目区官方将作品划分为五大类每一类都有对应的真实作品作为参考分类方向举例仓库中的代表项目生产力工具代码审查、文档生成、会议纪要、邮件助手jjyaoao-CodeReviewAgent学习辅助学习伙伴、论文助手、编程导师、语言学习chengH425-PaperAssistant、chen070808-ProgrammingTutor创意娱乐故事生成、游戏 NPC、音乐推荐、菜谱lgs-only-NovelGenerator数据分析数据分析、股票分析、舆情监控、竞品分析1zrj-DataAnalysisAgent、CC1227871-StockInsightAgent生活服务健康助手、理财助手、购物助手、家居控制Shawnxyxy-HealthRecordAgent以毕业设计章节中的智能代码审查助手CodeReviewAgent选题示例来看一个合格的选题需要同时想清楚三件事问题分析代码审查是软件开发的重要环节但人工审查耗时且易遗漏静态分析工具只能发现语法错误、无法理解语义因此需要一个能理解代码逻辑的 LLM 智能助手核心功能代码质量分析风格、命名、注释、潜在 bug 检测、性能优化建议、最佳实践推荐预期成果可运行的 Notebook 展示完整审查流程输出结构化的 Markdown 审查报告。社区真实项目 jjyaoao-CodeReviewAgent 正是该选题的落地通过CodeAnalysisToolPython AST 解析结构与StyleCheckToolPEP 8 风格检查两个工具配合SimpleAgent实现了代码结构分析、风格检查、LLM 深度建议与报告生成四合一的能力。三、项目结构标准最小必备三件套共创项目区对每个项目的最基本要求是包含三个必备文件你的用户名-项目名称/ ├── README.md # 项目说明文档必需 ├── requirements.txt # Python依赖列表必需 ├── main.ipynb # 主要的Jupyter Notebook必需 └── ... # 其他文件可选README.md项目的门面承担让读者三分钟看懂项目的职责requirements.txt完整声明 Python 依赖保证pip install -r requirements.txt即可复现运行环境main.ipynb可运行的 Jupyter Notebook是项目功能的主载体要求打开即可运行、按序执行即可复现结果。除此之外社区项目普遍还会补充以下可选目录参见 jjyaoao-CodeReviewAgent 与毕业设计章节 16.3.3 节的推荐结构你的用户名-项目名称/ ├── .env.example # 环境变量示例API 密钥占位 ├── .gitignore # Git 忽略规则忽略 .env、大文件、输出 ├── data/ # 示例数据只放小规模样例 ├── outputs/ # 输出结果报告、截图、图表 └── src/ # 代码较多时拆分的源码包agents/tools/utils其中.env.example与.gitignore虽然不在三件套硬性要求中但几乎所有高质量项目都会包含前者让使用者知道需要配置哪些环境变量后者防止 API 密钥与输出文件被误提交到仓库。四、用官方模板快速起步共创项目区提供了官方起点 EXAMPLE-ProjectTemplate包含一份标准的 README 模板 与一份可直接套用的 main.ipynb。4.1 README 模板的结构拆解模板要求 README 至少覆盖以下板块每个板块都有明确目的板块目的项目名称 一句话简介让读者 3 秒内判断项目是否相关项目简介说明解决什么问题、特色功能、适用场景核心功能以勾选清单列出功能点技术栈声明使用的框架、范式ReAct、Plan-and-Solve 等、工具与 API快速开始环境要求 → 安装依赖 → 配置 API 密钥 → 运行项目使用示例代码示例与运行结果项目亮点 / 性能评估突出技术特色有评测数据则如实展示未来计划 / 贡献指南 / 许可证 / 作者 / 致谢项目的社区化收尾其中快速开始是模板着墨最多的部分标准流程为# 1. 安装依赖 pip install -r requirements.txt # 2. 创建 .env 文件并填入 API 密钥 cp .env.example .env # 编辑 .env 文件 # OPENAI_API_KEYyour_key_here # 3. 启动 Jupyter 并运行 main.ipynb jupyter lab环境要求模板中明确写有Python 3.10这也是 Hello-Agents 教程全书的运行基准版本。4.2 Notebook 模板的六段式结构模板 main.ipynb 将项目 Notebook 划分为六个逻辑段落这套结构被社区大量作品沿用项目介绍Markdown项目名称、简介、作者信息姓名、GitHub、日期环境配置安装依赖、导入hello_agents库、load_dotenv()加载环境变量工具定义继承BaseTool编写自定义工具类智能体构建创建HelloAgentsLLM、定义系统提示词、实例化SimpleAgent并注册工具功能演示多个示例输入验证基础功能与复杂场景性能评估可选 总结与展望评测指标以及实现的功能、遇到的挑战、未来改进方向。模板中的核心代码骨架如下from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import BaseTool import os from dotenv import load_dotenv load_dotenv() class CustomTool(BaseTool): 自定义工具类 name tool_name description 工具描述 def run(self, query: str) - str: 工具执行逻辑 return f处理结果{query} llm HelloAgentsLLM() system_prompt 你是一个智能助手。 你的任务是 1. 理解用户的需求 2. 使用合适的工具 3. 提供有帮助的回答 agent SimpleAgent( name示例智能体, llmllm, system_promptsystem_prompt ) agent.add_tool(CustomTool()) result agent.run(你的测试输入) print(result)五、框架源码层面的纵深理解你正在使用的 API共创项目的开发质量取决于对 HelloAgents 框架核心 API 的理解程度。main.ipynb模板中的几行导入语句背后是框架最核心的组件from hello_agents import SimpleAgent, HelloAgentsLLM, ToolRegistry from hello_agents.tools import Tool, ToolParameter5.1 SimpleAgent范式封装与可扩展基类SimpleAgent是教程第七章构建的框架核心类封装了接收输入 → 组装消息 → 调用 LLM → 返回响应的基础对话链路并支持工具注册与调用。框架同时开放了继承扩展的能力——code/chapter7/my_simple_agent.py 演示了如何基于SimpleAgent基类重写run()方法实现带多轮工具调用max_tool_iterations循环与流式输出stream_run的自定义智能体。共创项目中凡是需要非标准交互逻辑的场景都可以参考这种继承基类 重写运行方法的模式。5.2 Tool / BaseTool / ToolParameter工具系统的三个层次框架的工具体系存在两套 API 形态共创项目中均有使用声明式继承BaseTool模板所用声明name、description类属性并实现run(query)方法适合快速原型参数化继承Tool并实现run(parameters: Dict)与get_parameters() - List[ToolParameter]毕业设计章节示例所用通过ToolParameter(name, type, description, required)显式声明参数 Schema更适合工具需要结构化参数、可被 LLM 可靠调用的场景。以 jjyaoao-CodeReviewAgent 的CodeAnalysisTool为例工具在run()内部使用 Python 标准库ast解析代码统计函数数、类数、代码行数并捕获SyntaxErrorStyleCheckTool则逐行检查 79 字符上限与缩进规范。这两个工具没有调用任何 LLM是纯确定性逻辑恰好演示了共创项目中确定性工具负责硬规则LLM 负责语义理解的分工原则——工具把客观事实结构统计、风格问题交给模型模型基于这些事实生成深度审查意见避免模型凭空编造代码指标。5.3 ToolRegistry工具注册与编排tool_registry ToolRegistry() tool_registry.register_tool(CodeAnalysisTool()) tool_registry.register_tool(StyleCheckTool()) agent SimpleAgent( name代码审查助手, llmllm, system_promptsystem_prompt, tool_registrytool_registry )ToolRegistry负责工具的注册、描述汇总get_tools_description用于注入系统提示词与按名执行execute_tool。当智能体配置了tool_registry后LLM 才能在对话中按需调用工具形成感知 → 决策 → 行动 → 观察的闭环。5.4 LLM 接入配置以环境变量解耦框架通过环境变量统一管理 LLM 接入社区项目普遍遵循 ModelScope 兼容的配置范式LLM_MODEL_IDQwen/Qwen2.5-72B-Instruct LLM_API_KEYyour_api_key_here LLM_BASE_URLhttps://api-inference.modelscope.cn/v1/ LLM_TIMEOUT60推荐两种配置方式.env文件推荐cp .env.example .env后编辑配合python-dotenv的load_dotenv()在 Notebook 首格加载Notebook 内直接设置os.environ[LLM_MODEL_ID] ...等方式写入环境变量适合快速演示。.env文件必须加入.gitignore仅提交.env.example占位模板避免密钥泄露。六、开发规范与质量门槛6.1 提交前的自检清单毕业设计章节16.4.4 节提供了一份提交前自检清单可直接作为共创项目的验收标准代码能够正常运行没有报错README 文档完整说明清晰requirements.txt 包含所有依赖有清晰的使用示例代码有适当的注释输出结果符合预期处理了常见的异常情况项目结构清晰文件命名规范大文件已妥善处理6.2 大文件处理规范为保持主仓库轻量化共创项目对大文件有明确限制项目总大小不超过 5MB禁止直接提交视频文件、大型数据集、模型文件。若项目确实包含大资源官方提供三种处理方案外部链接推荐将数据集上传百度网盘、Google Drive、Kaggle、HuggingFace Datasets视频上传 B 站、YouTube模型上传 HuggingFace Models、ModelScope在 README 中给出下载说明独立资源仓库为资源较多的项目单独创建项目名称-resources仓库README 中给出git clone与数据摆放说明仅提交示例数据主仓库只放小规模样例如 100 条记录的sample.csvREADME 中注明完整数据集的获取方式。最佳实践形态是data/下仅保留 1MB 示例数据outputs/下仅保留演示结果图片。6.3 requirements.txt 编写要点# 核心依赖 hello-agents[all]0.2.7 # 可视化如果需要 matplotlib3.7.0 plotly5.14.0 # Web框架如果需要 fastapi0.109.0 uvicorn0.27.0建议标注主版本下限按核心依赖 → 可视化 → Web 框架分组并加注释便于维护者理解每个依赖的用途。可参考社区作品各自的 requirements.txt 实际写法。七、从 Fork 到 Pull Request完整的开源贡献流程共创项目的提交完全走开源协作标准流程以下按顺序展开对应毕业设计章节 16.316.5 节。7.1 环境准备# 安装 HelloAgents 框架含全部可选依赖 pip install hello-agents[all] # 检查并配置 Git 用户信息 git config --global user.name 你的名字 git config --global user.email 你的邮箱 # 安装 JupyterLab推荐 pip install jupyterlab jupyter lab7.2 Fork 与克隆访问 Hello-Agents 仓库点击右上角Fork将副本创建到自己的账号下克隆自己 Fork 的仓库到本地并添加上游仓库以便同步更新git clone gitgithub.com:你的用户名/hello-agents.git cd hello-agents git remote add upstream Hello-Agents上游仓库地址 git remote -v创建独立开发分支避免污染主分支git checkout -b feature/你的项目名称 # 例如 git checkout -b feature/code-review-agent7.3 在共创目录中开发cd Co-creation-projects mkdir 你的用户名-项目名称 cd 你的用户名-项目名称在此目录内完成三件套开发、README 编写、自检与本地测试jupyter lab运行main.ipynb逐格验证。7.4 提交与推送# 查看改动 git status # 添加文件推荐只添加项目目录 git add Co-creation-projects/你的用户名-项目名称/ # 提交信息遵循 Conventional Commits 风格 git commit -m feat: 添加XXX毕业设计项目 # 推送到自己的 Fork git push origin feature/你的项目名称提交信息类型规范feat新增功能或项目毕业设计项目使用此类型、fix修复 bug、docs文档更新、style格式调整、refactor重构、test测试、chore其他修改。7.5 创建 Pull RequestPR 的关键约定有两点务必遵守① PR 标题统一格式[毕业设计] 项目名称 - 简短描述例如[毕业设计] CodeReviewAgent - 智能代码审查助手[毕业设计] StudyBuddy - AI学习伙伴[毕业设计] DataAnalyst - 智能数据分析师统一标题格式是为了让所有毕业设计/共创项目在 PR 列表中可检索、可管理。② PR 分支选择Base repositoryhello-agents主仓库Base branchmainHead repository你自己的 ForkCompare branchfeature/你的项目名称③ PR 描述建议包含项目名称与作者、项目类型生产力工具/学习辅助/创意娱乐/数据分析/生活服务、项目简介、核心功能、技术亮点、演示效果截图、自检清单代码可运行、README 完整、requirements.txt 完整、有使用示例、有注释。7.6 响应 Review 与合并提交 PR 后社区成员会进行代码 Review 并提出改进建议。正确应对方式是查看评论 → 修改代码 → 以fix: 根据review意见修改XXX之类的提交信息推送更新 → 在 PR 中回复说明修改内容。通过评审后项目会被合并进主仓库的Co-creation-projects目录成为共创项目区的一员。八、从模板到真实作品社区项目赏析模板是骨架真实作品才是血肉。以下三个项目分别代表不同复杂度层级可作为你创作时的对标参照。8.1 标准形态CodeReviewAgent生产力工具jjyaoao-CodeReviewAgent 是毕业设计章节官方引用的完整示例Notebook 内分 07 部分组织快速演示、LLM 配置、工具定义、注册表构建、智能体创建、示例运行、报告落盘将待审代码放入data/sample_code.py后运行即可在outputs/review_report.md得到结构化审查报告。它的 README 严格遵循模板章节顺序简介 → 功能 → 技术栈 → 快速开始 → 使用示例 → 亮点 → 结构 → 技术实现 → 示例输出 → 未来改进是README 规范的范本。8.2 数据驱动形态DataAnalysisAgent数据分析1zrj-DataAnalysisAgent 展示了另一类典型数据清洗工具DataCleaningTool按用户指定规则清洗表格与数据统计工具DataStatisticsTool提供描述性统计分析配合SimpleAgent将 Excel 数据转化为 ECharts 图表outputs/echarts.html与 Markdown 分析报告outputs/report.md。这类项目的价值在于演示了LLM 决策 确定性工具执行如何端到端打通数据流水线。8.3 全栈形态YingQian后端 前端aatanxiao12-beep-YingQian 将共创项目的边界推到了工程化全栈后端基于 FastAPIbackend/pyproject.toml、backend/run.py前端基于 React TypeScript Vitefrontend/并配有main.ipynb承载核心演示。它说明共创项目并不局限于 Notebook——只要三件套齐备、结构清晰、可复现运行任何复杂度形态的作品都欢迎。九、交流与许可证9.1 交流与反馈渠道共创项目区官方提供的交流方式包括在 Issue 中提问、加入 Datawhale 社区讨论、参与社区项目的 Review。Review 既是他人帮你把关质量也是你观摩学习其他作品实现思路的机会。9.2 许可证共创项目区所有作品统一遵循CC BY-NC-SA 4.0 License知识共享-署名-非商业性使用-相同方式共享欢迎学习与再创作但需注明出处、不得用于商业用途、衍生作品需以相同许可协议发布。注意这与示例项目模板 README 中写的MIT License存在差异——提交共创项目时请以项目区统一的 CC BY-NC-SA 4.0 为准。十、总结从选题命名到三件套搭建从模板套用到框架 API 的深度理解从本地自检到 Fork-PR 开源协作共创项目的完整链路并不复杂但每一步都有明确的规范可循。核心要点可以浓缩为四句话命名即规范{GitHub用户名}-{项目名称}一眼可读三件套兜底README requirements.txt main.ipynb缺一不可工具与 LLM 分工确定性逻辑交给工具语义理解交给 LLM用Tool/ToolParameter声明结构化接口流程守约定PR 标题[毕业设计] 项目名称 - 简短描述项目 ≤5MB、大文件走外部方案。无论你的作品是几十行的原型还是前后端齐全的全栈应用只要亲自实现、结构合规、文档清晰都值得被收录。正如毕业设计章节所言小的创意同样可以被收录只要是自己动手的作品都是值得珍惜的。现在去Co-creation-projects目录下创建属于你的第一个共创项目吧。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考