企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• 代码智能体
• MCP Clients
• Agent 沙箱

本指南面向所有想为 🤗 smolagents（一个让 Agent"用代码思考"的精简库）贡献代码、文档或社区力量的开发者，系统讲解仓库约定俗成的贡献流程：从"先开 Issue 等待status:accepted标签"到"PR 合入前必须通过make quality与 `make test" 的全过程。读完本文，你将掌握如何正确提交 Bug 报告与功能需求、如何认领并修复既有 Issue、如何搭建开发环境并通过仓库内置的 ruff 质量检查与 pytest 测试流水线，最终让你的贡献以最顺畅的方式被维护者审查并合入。

贡献方式总览：不止写代码

smolagents 欢迎所有人的贡献，并珍视每一条贡献。代码提交并不是帮助社区的唯一方式：回答问题、帮助他人、改进文档同样极具价值。除此之外，在博客中介绍 smolagents 支持的精彩项目、在社交平台上分享使用体验，或是给仓库点一个 Star 表示认可，也都是一种支持。

仓库的 CONTRIBUTING.md 将贡献方式归纳为四类：

• 提交 Issue：报告你遇到的 Bug，或描述你希望看到的新功能；
• 贡献示例或文档：完善 examples 目录下的示例代码，或改进 docs 下的多语言文档；
• 修复既有 Issue：从被标注为good first issue或help wanted的问题入手，提交代码修复；
• 参与 Triage：复现他人报告的 Bug、回答社区问题、审查开放的 Pull Request。

所有形式的贡献对社区同等重要。

无论选择哪种方式，请务必遵守仓库的 CODE_OF_CONDUCT.md。

提交 PR 前的硬性规则

smolagents 收到的 Pull Request 远多于维护者能够逐一审查的数量。以下规则是为了让真正收到的贡献获得认真、及时的审查——它们的目的是帮你避免浪费精力，而不是把你拒之门外。

先开 Issue，等待status:accepted标签

对于任何大于"改错别字、修失效链接"的改动，请先打开 Issue，并等待维护者为其打上status:accepted标签后再开始写补丁。被接受的 Issue 是维护者对后续 PR 进行审查的承诺：

• 没有关联已接受 Issue 的 PR 会被标记为needs-issue；
• 该 PR 将在14 天后被关闭。

这一约定保证维护者有限的审查精力集中在有明确需求的改动上。

首个 PR 落地前，一次只开一个

在你第一个贡献被合入之前，请同时只保持一个开放的 Pull Request。一旦有你的贡献被合并，之后你想开多少都可以。这避免了多路并行导致维护者无法集中跟踪你的改动。

使用 AI 助手：声明它，并对 diff 负责

smolagents 本身就是构建 Agent 的库，因此用 Agent 来为它做贡献是完全合理且受欢迎的。但维护者需要有一个人对结果负责：你读过这次改动、你跑过测试、你能解释它为什么正确、你会回应审查意见。批量提交、无人负责的自动生成补丁将被直接关闭。

第一个"可审查"的 PR 优先，而非第一个提交的

当多个 PR 解决同一个 Issue 时，仓库合入的是完整、经过测试、范围正确的那一个，而不是时间戳最早的那一个。抢先提交并不会加分。

核心库只做原语（primitives），不做集成（integrations）

smolagents 刻意保持小巧。以下类型的内容通常不会被接受进入核心库：

• 新的内置工具（built-in tools）；
• 特定供应商（provider-specific）的模型封装；
• 针对单个站点的抓取器（per-site scrapers）。

这类内容更合适的去处是发布到 Hugging Face Hub，让它们按照你自己的节奏演进。如果不确定某个改动是否在核心范围内，在动手开发之前先在 Issue 里问一句，可以避免大量返工。

如何提交高质量的 Bug Issue

库的健壮与可靠，离不开用户报告他们遇到的问题。提交 Bug 报告前，请先做好两件事：

1. 确认 Bug 尚未被报告过（使用 Issues 页面的搜索栏）；
2. 确认问题属于库本身的 Bug，而不是你业务代码的问题。

确认无误后，在 Issue 中尽量包含以下信息，以便维护者快速定位：

• 你的OS 类型与版本，以及环境版本（Rust、Python 及相关依赖的版本）；
• 一段简短、自包含、可复现的代码片段；
• 若抛出了异常，附上完整的 traceback；
• 其他可能有帮助的补充信息，例如截图。

如果你已经想好了修复方案，也请在 Issue 中说明——一旦它被打上status:accepted标签，这个问题就归你来做了。

如何提交 Feature Request

如果你想为 smolagents 增加新功能，请打开 Issue 并描述清楚以下四点：

1. 动机（motivation）：这个功能背后的动机是什么？是源于使用库时遇到的问题或挫败感？是你项目需要的能力？还是你开发过、认为能让社区受益的东西？
2. 尽可能详细的描述：关于功能本身你提供的信息越多，维护者就越能帮到你。
3. 演示用法的代码片段：一个能展示该功能如何使用的代码示例。
4. 论文出处：如果该功能源自某篇论文，请附上论文链接。

正如文档所言："如果你的 Issue 写得很好，创建它的时候就已经完成了 80%"。

文档贡献与写作规范

仓库始终在寻找让文档更清晰、更准确的改进，包括错别字、缺失内容、含糊不清或不准确之处。除了直接告诉维护者，你也可以亲自提交文档修改。

文档源文件位于 docs/source/en/，并提供了 zh、es、hi、ko 等多语言目录。具体的构建与写作规范记录在 docs/README.md，要点包括：

• 构建文档：安装doc-builder后，用doc-builder build smolagents docs/source/en/ --build_dir ~/tmp/test-build生成本地文档（构建产物不需要提交）；用doc-builder preview smolagents docs/source/en/在http://localhost:5173本地预览；
• 新增页面：新建 Markdown 文件放入docs/source/en/对应子目录，然后在 docs/source/en/_toctree.yml 中把文件名（不含扩展名）登记到正确的 toc-tree 下；preview命令只对已有文件生效，新增文件后需更新_toctree.yml并重启 preview；
• docstring 风格：遵循 Google 文档风格，参数以Args:前缀 + 缩进定义，返回值以Returns:前缀引入；可选参数标注*optional*与默认值；
• 内部链接语法：提及类、函数或方法时，使用[`XXXClass`]或[`~utils.ModelOutput`]形式的内部链接语法，工具会自动生成指向其文档的链接（带~前缀可只显示类名）；
• 重命名/移动章节：在旧位置保留"章节已移动"的锚点映射（<a href="#section-b">Section A</a><a id="section-a"></a>），保证历史链接不失效；
• 图片约定：为控制仓库体积，不直接提交图片等非文本文件，推荐放入hf-internal-testing或huggingface/documentation-images等数据集中再按 URL 引用。

认领并修复既有 Issue

如果你发现现有代码存在问题且已有修复思路，在 Issue 下留言认领。一旦维护者打上status:accepted标签并将它分配给你，就可以着手创建 Pull Request 了。

对于新手，good first issue与help wanted标签是绝佳的切入点——它们通常经过维护者筛选，难度适中且需求明确。

开发环境的搭建

对仓库代码做任何改动前，先安装开发依赖。文档提供了两种方式：

使用 pip：

pip install -e ".[dev]"

使用 uv：

uv pip install -e "smolagents[dev] @ ."

两种方式等价，都会从源码以可编辑模式（editable）安装 smolagents 并附带全部开发依赖。查看 pyproject.toml 可知，dev依赖组实际上聚合了两部分：

• smolagents[quality,test]：质量检查与测试工具链；
• sqlalchemy：供 examples 下的示例使用。

其中quality组只包含ruff>=0.9.0，而test组则较为丰富：pytest>=8.1.0、pytest-datadir、pytest-timeout（用于文档测试的超时标记）、ipython（交互环境测试）、pandas、rank-bm25、Wikipedia-API、mlx[cpu]以及smolagents[all]全家桶等。

质量检查：make quality

修改代码后，请确认改动符合仓库的代码质量要求：

make quality

从 Makefile 可以看出，这条命令作用于examples src tests三个目录，实际执行两步：

quality: ruff check $(check_dirs) ruff format --check $(check_dirs)

即先用 ruff 做静态检查（lint），再检查格式是否符合规范。ruff 的规则在 pyproject.toml 中配置：line-length = 119，选择E、F、I、W四类规则（忽略F403、E501），并针对 examples 目录放宽E402（模块导入位置）。同样的检查也在 CI 中执行——见 .github/workflows/quality.yml，它逐条运行ruff check examples src tests与ruff format --check examples src tests，也就是说本地make quality通过基本等于 CI 质量门禁通过。

自动格式化：make style

如果质量检查失败，可以运行格式化器自动修复并提交改动：

make style

对应 Makefile 中的实现：

style: ruff check $(check_dirs) --fix ruff format $(check_dirs)

ruff check --fix会尽量自动修复 lint 问题，ruff format则按仓库规范统一代码格式。此外，仓库还提供了 .pre-commit-config.yaml 预提交钩子，包含 ruff 修复、ruff-format 格式化、check-merge-conflict（检查未解决的合并冲突）与check-yaml（校验 YAML）四类钩子，建议本地启用以便在提交前自动拦截问题。

运行测试：make test

本地运行测试套件的命令是：

make test

对应 Makefile 中的pytest ./tests/。pytest 的默认参数在 pyproject.toml 中配置为-sv --durations=0（显示详细输出并统计每个用例耗时）。

测试目录 tests 按模块组织，覆盖了库的各个核心组件，例如：

• test_agents.py：Agent 生命周期与行为；
• test_models.py：各类模型封装与推理后端；
• test_tools.py：工具定义、校验与调用（1068 行，是规模最大的测试文件之一）；
• test_local_python_executor.py：本地 Python 代码执行器；
• test_default_tools.py、test_mcp_client.py、test_memory.py、test_monitoring.py、test_remote_executors.py、test_serialization.py等。

测试基础设施也值得了解：tests/fixtures/下提供了agents.py与tools.py两套 fixture，并通过 tests/conftest.py 中的pytest_plugins注册为插件自动生效；conftest.py还自动为每个MultiStepAgent的实例化注入verbosity_level=LogLevel.OFF，抑制测试日志输出。CI 中的 tests.yml 使用 uv 安装smolagents[test]后在 Python 3.10 与 3.12 两个版本上分别运行pytest ./tests/——因此本地make test通过同样是合入门禁的一部分。

代码风格守则

仓库根目录的 AGENTS.md 对贡献者提出了三条简明守则：

• 遵循面向对象原则（OOP principles）；
• 写得 Pythonic：遵循 Python 最佳实践与惯用模式；
• 为新功能编写单元测试：任何新行为都应伴随对应测试。

想成为维护者？如何进阶

smolagents 是一个由 Hugging Face 主导和维护的项目，同时非常欢迎来自其他组织的、有热情的个人加入维护者行列，一起推动 Agent 生态的发展。如果你是这样的人（或组织），请直接联系项目团队沟通合作意向。

延伸阅读

• CONTRIBUTING.md：本指南对应的仓库原文；
• CODE_OF_CONDUCT.md：贡献者行为准则；
• Makefile：quality/style/test三个命令的精确定义；
• pyproject.toml：开发依赖组、ruff 规则与 pytest 配置；
• .github/workflows/quality.yml 与 .github/workflows/tests.yml：与本地命令等价的 CI 流水线；
• docs/README.md：文档构建与写作规范。

• 人工智能
• AI Agent
• Agent 框架
• 工具调用
• 代码智能体
• MCP Clients
• Agent 沙箱