CrewAI 自定义 Tool 项目模板：从脚手架创建到发布安装的完整工作流

CrewAI 的 crewai create tool 命令会基于仓库中的 Tool 模板（templates/tool）生成一个可直接发布、可被他人安装的自定义工具项目。本文以该模板自带的 README.md 为主体，结合模板内的 pyproject.toml、工具代码骨架以及 CLI 侧 ToolCommand 的实现，讲清楚一个 CrewAI Tool 项目从创建、安装依赖、开发、发布到被他人安装的完整链路，以及每一步背后的源码机制。

模板定位：Tool 项目的标准骨架

当你在一个空目录下执行 crewai create tool <handle> 后，CLI 会把 templates/tool 目录整体复制为项目根目录，并替换其中的占位符。最终生成的项目结构如下（对应 templates/tool 目录）：

<folder_name>/
├── README.md
├── pyproject.toml
├── AGENTS.md
└── src/
    └── <folder_name>/
        ├── __init__.py
        └── tool.py

其中 pyproject.toml 模板（pyproject.toml）定义了项目的关键元信息：

[project]
name = "{{folder_name}}"
version = "0.1.0"
description = "Power up your crews with {{folder_name}}"
readme = "README.md"
requires-python = ">=3.10,<3.14"
dependencies = [
    "{{crewai_tools_dependency}}"
]

[tool.crewai]
type = "tool"

各字段的作用：

• name / description：包名与描述，来自脚手架时替换的 {{folder_name}} 占位符；
• requires-python：锁定 Python >=3.10,<3.14，与模板 README 中「Ensure you have Python >=3.10 <3.14 installed」的要求一致；
• {{crewai_tools_dependency}}：脚手架时由 CLI 动态计算并填入，见下文「依赖版本范围」；
• [tool.crewai] type = "tool"：向 CrewAI 生态声明这是一个 Tool 类型项目。从 cli.py 中多处「Backfills a project_id for projects that have [tool.crewai]」的注释可以推断，后续命令（如 install/run 相关入口）会以该表作为项目类型识别与 project_id 回填的依据。

工具代码骨架在 src/{{folder_name}}/tool.py，是一个最小可运行的 BaseTool 子类：

from crewai.tools import BaseTool


class {{class_name}}(BaseTool):
    name: str = "Name of my tool"
    description: str = "What this tool does. It's vital for effective utilization."

    def _run(self, argument: str) -> str:
        return "Tool's result"

开发自定义工具时，核心就是修改 name、description 与 _run 的实现；__init__.py 则负责把 {{class_name}} 导出为包级 API（__all__ = ["{{class_name}}"]），供 crew 侧直接 import 使用。

脚手架创建流程（源码视角）

创建逻辑位于 tools/main.py 的 ToolCommand.create，要点如下：

1. handle 归一化：folder_name 将 handle 中的空格、连字符替换为下划线并转小写；class_name 则转成 TitleCase 并去掉空格，用作类名。因此 crewai create tool my-tool 会生成 my_tool/ 目录与 MyTool 类。
2. 防重入保护：_ensure_not_in_project 会检查当前目录是否存在 pyproject.toml，若已在一个项目内则拒绝创建，避免嵌套生成。
3. 模板复制与占位符替换：通过 tree_copy 复制 templates/tool，再用 tree_find_and_replace 依次替换 {{folder_name}}、{{class_name}} 和 {{crewai_tools_dependency}}，并把仓库级 AGENTS.md 复制到新项目。
4. 初始化仓库并登录：创建完成后 CLI 会执行 git init 并调用 login() 获取工具仓库凭证。也就是说，模板 README 中描述的发布/安装能力，前提是这个目录本身是一个 git 仓库且已认证。

关于依赖版本范围：{{crewai_tools_dependency}} 由 version.py 的 get_crewai_tools_dependency 生成，形如 crewai[tools]>=<当前CLI版本>,<major+1>.0.0，即锁定与当前 CLI 同一大版本区间，保证生成的 tool 项目与 CLI 兼容。

安装依赖与初始化项目

继承自模板 README.md 的官方操作步骤：

1. 确认系统已安装 Python >=3.10 <3.14；
2. 安装 uv（模板项目用 UV 做依赖管理与包处理）：

pip install uv

3. 进入生成的工具项目目录，安装依赖：

crewai install

这里的 crewai install 是 CLI 封装的 uv 包装命令：从 cli.py 中可以看到，相关命令会「adds custom tool authentication through env vars」，即通过 build_env_with_all_tool_credentials 注入工具仓库凭证后再透传给底层 uv，从而支持从 CrewAI 私有工具仓库拉取依赖。

发布 Tool：crewai tool publish

模板 README 给出的发布命令是：

crewai tool publish {{tool_name}}

（{{tool_name}} 即项目 handle/包名。）在 cli.py 中，crewai tool publish 还支持以下选项：

选项	说明
--public	公开发布到社区可见的 Tool 仓库
--private	私有发布（默认，仅在组织内共享）
--force	跳过 Git 远端同步校验（本地未 commit/push/pull 时会直接报错退出）

注意 CLI 已提示 crewai tool create 属于被弃用命令（建议改用 crewai create tool），但 tool install / tool publish 仍是现行入口。

ToolCommand.publish 的完整流程（tools/main.py）：

1. Git 同步检查：git.Repository().is_synced() 不通过且未加 --force 时，提示先 commit、push、pull 再重试；
2. 提取元数据：调用 crewai.utilities.project_utils.extract_available_exports 发现项目导出的工具，extract_tools_metadata 提取每个工具的模块、描述、init 参数 schema 与环境变量需求，并在终端打印预览（参数名、类型、默认值、是否必填）；
3. 构建 sdist：执行 uv build --sdist --out-dir <临时目录> 生成 .tar.gz，并将 tarball base64 编码；
4. 上传：通过 Plus API publish_tool 上传 handle、版本、描述、tarball、可用导出与工具元数据；
5. 安全扫描：发布成功后会提示「Security checks are running in the background」，工具需通过后台安全检查后才可被安装。

安装他人发布的 Tool：crewai tool install

模板 README 中，其他人可以在自己的 crew 项目里运行：

crewai tool install {{tool_name}}

对应实现 ToolCommand.install / _add_package 的行为：

1. 先调用 get_tool(handle) 查询工具详情，404 时提示「No tool found with this name」并退出；
2. 根据工具的 source 字段选择安装路径：
   • source == "pypi"：直接 uv add <handle>；
   • 否则（来自 CrewAI 工具仓库）：uv add --index "<repo_handle>=<repo_url>" <handle>，并通过 build_env_with_tool_repository_credentials 注入仓库凭证完成私有索引认证。

因此「publish → install」本质上是把工具以 Python 包（sdist）形式托管在 CrewAI Tool Repository（或 PyPI），消费方只需一条 crewai tool install 即可把工具装进 crew 的依赖环境。

命令速查

命令	作用	备注
crewai create tool <handle>	基于 templates/tool 生成 Tool 项目	crewai tool create 已弃用，仅打印弃用提示后转发
pip install uv	安装 UV 包管理器	模板 README 要求的前置步骤
crewai install	在工具项目内安装依赖	自动注入工具仓库认证环境变量
crewai tool publish [--public/--private] [--force]	构建 sdist 并发布到 Tool 仓库	默认私有；发布前要求 git 已同步
crewai tool install <handle>	安装已发布的工具包	支持 PyPI 来源与 CrewAI 私有索引两种来源

适用前提与限制

• Python 版本必须在 >=3.10,<3.14 区间内（模板 pyproject.toml 的 requires-python 硬性约束）；
• 创建/发布/安装 Tool 都依赖 git 仓库状态与 CrewAI 账号登录（login 失败会要求重新 crewai login 并确认当前组织对 Tool 仓库有访问权限）；
• ToolCommand 的部分能力（如元数据提取）依赖完整 crewai 包，缺少时会提示 pip install crewai；
• 发布后工具处于后台安全扫描期间暂时不可用，需扫描完成后才能被 crewai tool install 拉取。

综上，templates/tool 模板不仅是生成项目的静态骨架，还与 tools/main.py 中的 ToolCommand 紧密配套：模板负责「长什么样」，ToolCommand 负责「怎么建、怎么发、怎么装」。理解了这一对关系，就能完整掌握 CrewAI 自定义 Tool 的开发生命周期。