今天，让我们深入 Dify 的开源贡献体系，看看这个项目是如何在短短时间内聚集起一个活跃的开发者社区的。作为想要参与 Dify 开发的你，这一章将是你的实战指南。

一、代码贡献流程：从想法到合并的完整路径

1.1 贡献前的准备工作

在开始编码之前，我们需要先在 GitHub 上找到一个现有的 issue，或者创建一个新的 issue。这不是官僚主义，而是基于实际经验的最佳实践。

为什么要先提 Issue？

我见过太多热心的开发者花了一周时间开发功能，结果发现项目组早就有了类似的实现，或者功能方向与项目规划不符。Dify 团队很聪明地通过 Issue 机制避免了这种浪费：

# Issue 类型分类
Feature Request（功能请求）：
- 需要详细说明功能目标和使用场景
- 等待团队成员确认可行性
- 获得 go-ahead 后才开始编码Bug Report（问题报告）：
- 可以直接开始修复
- 优先级按影响程度分类

实际操作技巧：

你可以使用社区开发的 Feature Request Copilot 来帮助你更好地描述需求。这是一个很聪明的做法，用 AI 来优化 AI 项目的贡献流程。

1.2 团队分工与对接人

了解团队分工能帮你更高效地找到对接人。基于我对 Dify 团队的观察，以下是当前的核心分工：

# 团队分工映射表
TEAM_FOCUS = {"Agent 架构": ["@yeuoly"],"RAG 管线设计": ["@jyong"], "工作流编排": ["@GarfieldDai"],"前端体验": ["@iamjoel", "@zxhlyh"],"开发者体验": ["@guchenhe", "@crazywoola"],"产品架构": ["@takatost"]
}

经验之谈：在 Issue 中 @mention 相关负责人，能显著提高响应速度。但注意不要滥用，保持专业和礼貌。

1.3 优先级判断机制

Dify 团队有一套清晰的优先级判断机制，理解这套机制能帮你选择合适的贡献方向：

# 功能优先级评估
High Priority:- 团队标记的高优先级功能- 社区反馈版中的热门需求Medium Priority:- 非核心功能增强- 次要功能改进Low Priority:- 有价值但非紧急的功能Future Feature:- 需要更长期规划的功能

Bug 修复优先级：

Critical: - 登录问题- 应用无法运行- 安全漏洞Medium:- 非关键 bug- 性能优化Low:- UI 小问题- 文档错误

二、环境搭建：开发者友好的设计哲学

2.1 Fork 和 Clone：标准但不简单

虽然流程看起来标准，但 Dify 在细节上做了很多优化：

# 1. Fork 仓库到个人账户
# 2. 克隆到本地
git clone git@github.com:<your-username>/dify.git
cd dify# 3. 添加上游仓库
git remote add upstream https://github.com/langgenius/dify.git# 4. 创建功能分支
git checkout -b feature/your-feature-name

避坑指南：

# 常见错误：直接在 main 分支开发
git checkout main  # ❌ 错误做法# 正确做法：总是创建新分支
git checkout -b fix/issue-123  # ✅ 正确做法

2.2 依赖环境：一个都不能少

Dify 的环境依赖看起来简单，但每一个都有深意：

必需依赖:Docker: "容器化开发环境"Docker Compose: "一键启动全栈服务"Node.js: "v18.x LTS 版本"Python: "3.11.x 版本"推荐工具:npm: "8.x.x 版本或以上"Yarn: "备用包管理器"

版本选择的考量：

• Python 3.11.x：新特性支持和性能优化的平衡点
• Node.js v18.x LTS：长期支持版本，稳定性优先
• Docker Compose：简化了复杂的服务依赖管理

2.3 分离式开发架构

Dify 采用前后端分离的开发模式，这要求开发者理解两套不同的启动流程：

# 后端启动流程
cd api/
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt# 数据库迁移
flask db upgrade# 启动开发服务器
flask run --host 0.0.0.0 --port 5001

# 前端启动流程  
cd web/
npm install
npm run dev

开发环境验证：

打开浏览器访问 http://localhost:3000，你应该能看到 Dify 正常运行。

2.4 常见环境问题解决

基于社区反馈，我总结了最常见的环境搭建问题：

# 问题1：端口冲突
# 解决方案：
def check_port_available(port):"""检查端口是否可用"""import socketsock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)result = sock.connect_ex(('localhost', port))sock.close()return result != 0# 问题2：依赖版本冲突
# 解决方案：使用虚拟环境隔离

三、专业化贡献指导

3.1 模型提供商接入开发

如果你想为 Dify 添加新的 LLM 提供商，这里有专门的指导文档。让我们看看核心的实现模式：

# 模型提供商抽象接口
class ModelProvider(ABC):"""模型提供商基类"""@abstractmethoddef get_provider_schema(self) -> ProviderSchema:"""获取提供商配置模式定义 API 密钥、端点等配置信息"""pass@abstractmethoddef validate_credentials(self, credentials: dict) -> None:"""验证提供商凭据在保存配置前验证 API 密钥是否有效"""pass@abstractmethoddef invoke_llm(self, model: str,credentials: dict,prompt_messages: list,model_parameters: dict) -> LLMResult:"""调用大语言模型统一的模型调用接口"""pass

实现新提供商的步骤：

# 1. 创建提供商目录
mkdir -p api/core/model_runtime/model_providers/your_provider# 2. 实现提供商类
class YourProvider(ModelProvider):def get_provider_schema(self) -> ProviderSchema:return ProviderConfig(provider='your_provider',label='Your Provider',supported_model_types=[ModelType.LLM],configurate_methods=[ConfigurateMethod.PREDEFINED_MODEL],provider_credential_schema=ProviderCredentialSchema(credential_form_schemas=[CredentialFormSchema(variable='api_key',label='API Key',type=FormType.SECRET_INPUT,required=True)]))

3.2 工具开发：扩展 Agent 能力

如果你想为 Agent 助手和工作流添加工具，这里有专门的指导。工具开发是 Dify 最活跃的贡献领域之一：

# 工具定义示例
class WeatherTool(BuiltinTool):"""天气查询工具"""def _invoke(self, user_id: str, tool_parameters: dict[str, Any]) -> ToolInvokeMessage:"""工具调用主逻辑Args:user_id: 用户IDtool_parameters: 工具参数Returns:ToolInvokeMessage: 工具执行结果"""location = tool_parameters.get('location')if not location:return self.create_text_message('请提供查询位置')# 实际的天气查询逻辑weather_data = self._fetch_weather(location)return self.create_text_message(f"{location}的天气：{weather_data['description']}，"f"温度：{weather_data['temperature']}°C")def _fetch_weather(self, location: str) -> dict:"""获取天气数据的具体实现"""# 这里实现实际的 API 调用pass

工具配置文件 (YAML)：

identity:name: weatherauthor: your_name@example.comlabel:en_US: Weather Queryzh_Hans: 天气查询
description:human:en_US: Query current weather informationzh_Hans: 查询当前天气信息llm: A tool for querying weather information by location
parameters:- name: locationtype: stringrequired: truelabel:en_US: Locationzh_Hans: 位置human_description:en_US: The location to query weather forzh_Hans: 需要查询天气的位置

3.3 前端组件开发

Dify 的前端基于现代化的 React 技术栈，采用了一些很棒的设计模式：

// 典型的 Dify 前端组件结构
import React, { useState, useCallback } from 'react'
import { useTranslation } from 'react-i18next'
import useSWR from 'swr'interface WeatherWidgetProps {className?: stringonLocationChange?: (location: string) => void
}const WeatherWidget: React.FC<WeatherWidgetProps> = ({className,onLocationChange
}) => {const { t } = useTranslation()const [location, setLocation] = useState('')// 使用 SWR 进行数据获取和缓存const { data: weatherData, error, mutate } = useSWR(location ? `/api/weather?location=${location}` : null,fetcher)const handleLocationSubmit = useCallback(async () => {if (!location.trim()) returntry {await mutate() // 触发数据重新获取onLocationChange?.(location)} catch (error) {console.error('Failed to fetch weather:', error)}}, [location, mutate, onLocationChange])return (<div className={`weather-widget ${className || ''}`}><inputtype="text"value={location}onChange={(e) => setLocation(e.target.value)}placeholder={t('weatherWidget.placeholder')}className="weather-input"/><button onClick={handleLocationSubmit}className="weather-submit-btn">{t('weatherWidget.query')}</button>{weatherData && (<div className="weather-result">{/* 天气信息展示 */}</div>)}</div>)
}export default WeatherWidget

四、Pull Request 规范：专业化的协作流程

4.1 PR 标题和描述规范

Dify 采用了约定式提交规范，这让项目历史更加清晰：

# PR 标题格式
feat: add weather query tool for agents
fix: resolve memory leak in workflow execution  
docs: update contribution guide with latest process
refactor: improve model provider abstraction
perf: optimize vector search performance

PR 描述模板：

## 变更概述
简要描述本次变更的内容和目的## 变更类型
- [ ] 新功能 (feat)
- [ ] 问题修复 (fix) 
- [ ] 文档更新 (docs)
- [ ] 代码重构 (refactor)
- [ ] 性能优化 (perf)
- [ ] 测试相关 (test)## 测试清单
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 手动测试验证
- [ ] 性能测试 (如适用)## 相关 Issue
Closes #123
Related to #456## 截图或演示
如果是 UI 相关变更，请提供截图或 GIF 演示## 特殊说明
如有破坏性变更或需要特别注意的地方，请在此说明

4.2 代码审查要点

基于我参与 Dify 代码审查的经验，以下是审查者最关注的几个方面：

# 1. 代码质量检查清单
CODE_REVIEW_CHECKLIST = {"功能性": ["是否解决了指定的问题","是否引入了新的 bug","边界条件是否处理正确"],"可读性": ["命名是否清晰表达意图","代码逻辑是否容易理解", "注释是否必要且准确"],"性能": ["是否存在性能瓶颈","数据库查询是否优化","内存使用是否合理"],"安全性": ["用户输入是否验证","权限检查是否到位","敏感信息是否保护"]
}

常见的审查反馈类型：

# 示例：性能优化建议
# 审查意见：❌ 不推荐
def get_all_apps(user_id: str):apps = db.session.query(App).all()user_apps = [app for app in apps if app.user_id == user_id]return user_apps# 建议改进：✅ 推荐
def get_all_apps(user_id: str):return db.session.query(App).filter(App.user_id == user_id).all()

4.3 CI/CD 集成与自动化检查

Dify 有完善的自动化检查流程，理解这些检查能帮你避免常见问题：

# .github/workflows/ci.yml 核心流程
name: CI Pipeline
on:pull_request:branches: [main, deploy/dev]jobs:backend-tests:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Set up Pythonuses: actions/setup-python@v3with:python-version: '3.11'- name: Install dependenciesrun: |cd apipip install -r requirements.txt- name: Run testsrun: |cd api  python -m pytest tests/- name: Run lintingrun: |cd apiflake8 .frontend-tests:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Set up Node.jsuses: actions/setup-node@v3with:node-version: '18'- name: Install dependenciesrun: |cd webnpm ci- name: Run testsrun: |cd webnpm run test- name: Run lintingrun: |cd webnpm run lint

预提交检查清单：

# 本地预检查命令
# 后端检查
cd api/
python -m pytest tests/           # 运行测试
flake8 .                         # 代码风格检查
mypy .                           # 类型检查# 前端检查  
cd web/
npm run test                     # 运行测试
npm run lint                     # ESLint 检查
npm run type-check              # TypeScript 类型检查

五、社区参与方式：从代码到文化

5.1 文档贡献：知识的传承

文档贡献有着清晰的流程和格式要求。在我看来，好的文档往往比代码更难写，因为它需要站在新手的角度思考问题。

文档贡献格式规范：

# 推荐的文档结构
## 引言
- 应用场景和解决的问题
- 核心特性和亮点  
- 最终效果和演示## 项目原理/流程概述## 前置条件 (如适用)
- 所需资源清单
- 工具和依赖要求## 在 Dify 平台中的实现 (建议步骤)
- 应用创建和基础配置
- 流程构建指南
- 关键节点配置详情## 常见问题

文档 PR 规范：

提交文档 PR 时，请使用格式 “Docs: Add xxx” 作为标题，并在评论字段提供简要描述。

5.2 社区讨论：思想的碰撞

Dify 社区有多个交流渠道，每个渠道都有其特定的用途：

交流渠道指南:
- GitHub Issues: 功能建议和 Bug 报告
- GitHub Discussions: 设计讨论和想法交流
- Discord: 实时聊天和快速问答
- 微信群: 中文用户交流 (非官方)

社区参与建议：

# 社区参与层次
COMMUNITY_INVOLVEMENT_LEVELS = {"初学者": ["提问和回答问题","报告使用中遇到的问题","分享使用心得和案例"],"贡献者": ["提交代码和文档","参与 Issue 讨论","审查其他人的 PR"],"核心贡献者": ["参与架构设计讨论","指导新贡献者","维护项目质量标准"]
}

5.3 插件生态：扩展的艺术

Dify 的插件系统为社区贡献提供了新的可能性。你可以将插件发布到个人 GitHub 仓库进行管理：

# 插件发布流程
# 1. 开发完成插件
# 2. 创建 GitHub 仓库
git init
git add .
git commit -m "Initial plugin commit"
git remote add origin https://github.com/your-username/your-plugin.git
git push -u origin main# 3. 创建 Release
git tag v1.0.0
git push origin v1.0.0# 4. 在 Dify 中通过 GitHub 链接安装
# 插件安装 URL: https://github.com/your-username/your-plugin.git

插件开发最佳实践：

# plugin.yaml 配置示例
identity:name: awesome_pluginauthor: your_name@example.comlabel:en_US: Awesome Pluginzh_Hans: 超赞插件description:en_US: An awesome plugin for Difyzh_Hans: 一个超赞的 Dify 插件icon: plugin_icon.svgmeta:version: "1.0.0"api_version: "1.0.0"supported_dify_versions: [">=0.6.0"]endpoints:- path: "/api/plugin/awesome"method: "POST"handler: "handlers.awesome_handler"

六、代码审查要点：质量把控的艺术

6.1 审查者的视角

作为一名经常参与 Dify 代码审查的开发者，我发现最有效的审查往往关注这几个方面：

# 代码审查金字塔模型
class CodeReviewPyramid:"""代码审查优先级金字塔"""def __init__(self):self.levels = {"致命问题": ["安全漏洞","数据泄露风险", "系统崩溃可能"],"严重问题": ["逻辑错误","性能问题","内存泄露"],"一般问题": ["代码重复","命名不规范","缺少注释"],"建议优化": ["代码风格","更好的实现方式","可读性改进"]}

实际审查示例：

# 原始代码 (需要改进)
def process_user_input(input_data):if input_data:if len(input_data) > 0:if input_data.strip():result = input_data.strip().lower()if result == "yes" or result == "y":return Trueelif result == "no" or result == "n":return Falseelse:return Nonereturn None# 审查建议后的改进版本
def process_user_input(input_data: str) -> Optional[bool]:"""处理用户输入，转换为布尔值Args:input_data: 用户输入字符串Returns:True: 用户确认 (yes/y)False: 用户拒绝 (no/n)  None: 无效输入"""if not input_data or not input_data.strip():return Nonenormalized_input = input_data.strip().lower()positive_responses = {'yes', 'y'}negative_responses = {'no', 'n'}if normalized_input in positive_responses:return Trueelif normalized_input in negative_responses:return Falseelse:return None

6.2 常见审查反馈模式

基于 Dify 项目的实际情况，我总结了一些常见的审查反馈模式：

# 常见反馈类型和标准回复
REVIEW_FEEDBACK_TEMPLATES = {"性能优化": {"问题": "这个查询可能会有性能问题","建议": "考虑添加数据库索引或使用更高效的查询方式","示例": "使用 filter() 而不是 Python 列表推导式过滤数据库结果"},"安全问题": {"问题": "用户输入没有进行验证","建议": "添加输入验证和参数化查询","示例": "使用 SQLAlchemy 的参数化查询防止 SQL 注入"},"代码风格": {"问题": "变量命名不符合 Python 规范","建议": "使用 snake_case 命名法","示例": "将 userID 改为 user_id"}
}

6.3 高质量审查的技巧

经过多年的代码审查实践，我发现以下技巧特别有效：

def effective_code_review():"""高效代码审查的实践指南"""# 1. 审查前的准备preparation_checklist = ["理解 PR 的目标和背景","检查相关 Issue 和讨论","了解修改的业务逻辑"]# 2. 审查过程中的关注点review_focus = ["先看整体架构，再看具体实现","关注业务逻辑是否正确","检查错误处理是否完善","确认测试覆盖是否充分"]# 3. 反馈的艺术feedback_principles = ["具体指出问题所在","提供改进建议而非仅指出问题", "区分必须修改和建议优化","保持建设性和友善的语调"]return {"preparation": preparation_checklist,"focus": review_focus,"feedback": feedback_principles}

七、最佳实践与避坑指南

7.1 新手常见错误

基于我观察到的情况，新贡献者经常在这些地方犯错：

# 常见错误清单
COMMON_MISTAKES = {"环境配置": ["Python 版本不匹配导致依赖安装失败","Node.js 版本过旧导致前端构建错误","Docker 配置不当导致服务启动失败"],"代码风格": ["不遵循项目的命名约定","缺少必要的类型标注","导入语句组织混乱"],"PR 提交": ["一个 PR 包含多个不相关的变更","提交信息不清晰或格式不正确","缺少必要的测试代码"],"沟通协作": ["没有在 Issue 中充分讨论就开始编码","PR 描述过于简单，缺少必要信息","对审查反馈回应不及时"]
}

实用的避坑技巧：

# 提交前的自检清单
echo "🔍 Pre-commit Checklist"
echo "========================"# 1. 代码质量检查
echo "✅ Running tests..."
cd api && python -m pytest tests/ && cd ../web && npm test# 2. 代码风格检查  
echo "✅ Checking code style..."
cd api && flake8 . && cd ../web && npm run lint# 3. 类型检查
echo "✅ Type checking..."
cd api && mypy . && cd ../web && npm run type-check# 4. 提交信息检查
echo "✅ Commit message format check..."
git log --oneline -1 | grep -E '^(feat|fix|docs|style|refactor|test|chore):'echo "🎉 All checks passed! Ready to push."

7.2 高效贡献的策略

经过多年的开源贡献经验，我总结出一套高效的贡献策略：

class EfficientContributionStrategy:"""高效贡献策略"""def __init__(self):self.phases = {"学习阶段": self._learning_phase(),"初级贡献": self._beginner_contribution(),"高级贡献": self._advanced_contribution(),"核心贡献": self._core_contribution()}def _learning_phase(self):"""学习阶段：熟悉项目"""return ["仔细阅读 README 和文档","搭建本地开发环境","运行现有测试，理解项目结构","浏览最近的 PR 和 Issue，了解项目动态"]def _beginner_contribution(self):"""初级贡献：从小处着手"""return ["修复文档中的错别字","添加缺失的类型标注","改进错误信息的表达","优化现有测试的可读性"]def _advanced_contribution(self):"""高级贡献：解决实际问题"""return ["修复 Good First Issue 标签的问题","实现社区需要的小功能","优化现有功能的性能","补充缺失的单元测试"]def _core_contribution(self):"""核心贡献：参与架构设计"""return ["参与架构讨论和设计决策","实现复杂的新功能","优化核心模块的设计","指导新贡献者参与项目"]

7.3 持续改进的心得

开源贡献不是一蹴而就的过程，需要持续的学习和改进。以下是我的一些心得：

## 技术成长路径### 第一个月：熟悉期
- 目标：能够成功运行项目，理解基本架构
- 行动：修复 1-2 个小 bug，提交 2-3 个 PR
- 学习重点：项目结构、编码规范、提交流程### 第二至三个月：贡献期  
- 目标：能够独立实现小功能，参与代码审查
- 行动：实现 1-2 个新功能，审查他人的 PR
- 学习重点：业务逻辑、设计模式、测试方法### 第四至六个月：深入期
- 目标：理解核心模块，能够设计技术方案
- 行动：参与架构讨论，指导新贡献者
- 学习重点：系统设计、性能优化、团队协作### 六个月后：专家期
- 目标：成为某个领域的专家，影响项目方向
- 行动：主导重要功能开发，参与产品规划
- 学习重点：技术前沿、项目管理、社区建设

八、未来发展方向：社区的演进

8.1 社区治理模式的思考

Dify 作为一个快速发展的开源项目，其社区治理模式也在不断演进。基于我对多个开源项目的观察，我认为 Dify 可能会朝着以下方向发展：

# 社区治理演进模型
class CommunityGovernanceEvolution:"""社区治理演进模型"""def __init__(self):self.current_stage = "创始人主导期"self.evolution_path = {"创始人主导期": {"特征": "核心团队决策，社区反馈","优势": "决策快速，方向明确","挑战": "扩展性有限，依赖核心团队"},"核心贡献者委员会": {"特征": "多人决策，专业分工","优势": "决策质量提升，责任分散","挑战": "协调成本增加，可能出现分歧"},"开放式治理": {"特征": "社区投票，透明决策","优势": "民主化程度高，社区参与度强","挑战": "决策效率可能降低"}}

8.2 技术栈演进趋势

随着 AI 技术的快速发展，Dify 的技术栈也在不断演进：

# 技术栈演进预测
TECH_STACK_EVOLUTION = {"近期 (6个月内)": {"后端": ["更多 LLM 提供商支持","工作流引擎性能优化","插件系统标准化"],"前端": ["组件库完善","用户体验优化","国际化支持增强"]},"中期 (1年内)": {"架构": ["微服务化改造","云原生部署优化","边缘计算支持"],"功能": ["多模态 AI 集成","实时协作功能","企业级权限控制"]},"长期 (2年内)": {"生态": ["完整的插件市场","第三方集成平台","行业解决方案模板"],"技术": ["边缘 AI 推理","联邦学习支持","自动化运维平台"]}
}

8.3 贡献者发展路径

对于想要在 Dify 社区长期发展的贡献者，我建议制定清晰的发展路径：

class ContributorCareerPath:"""贡献者职业发展路径"""def __init__(self):self.roles = {"代码贡献者": {"技能要求": ["Python/TypeScript", "AI/ML 基础", "系统设计"],"发展方向": ["架构师", "技术专家", "团队负责人"],"成长建议": "深入理解系统架构，积极参与核心功能开发"},"文档维护者": {"技能要求": ["技术写作", "用户体验", "多语言能力"],"发展方向": ["产品经理", "开发者关系", "社区经理"],"成长建议": "关注用户需求，提升内容质量和用户体验"},"社区建设者": {"技能要求": ["沟通协调", "项目管理", "社区运营"],"发展方向": ["社区经理", "项目经理", "开源推广者"],"成长建议": "积极参与社区活动，建立良好的人际关系网络"},"生态开发者": {"技能要求": ["插件开发", "API 集成", "业务理解"],"发展方向": ["解决方案架构师", "技术顾问", "创业者"],"成长建议": "深入理解业务场景，开发有价值的插件和工具"}}

九、实战案例：从提交到合并的完整流程

让我通过一个具体的案例来展示完整的贡献流程。假设我们要为 Dify 添加一个新的天气查询工具：

9.1 需求分析和 Issue 创建

# GitHub Issue 示例
**标题**: feat: Add weather query tool for agents**问题描述**:
当前 Dify 的 Agent 缺少天气查询功能，用户无法让 AI 助手查询实时天气信息。**解决方案**:
添加一个天气查询工具，集成主流天气 API（如 OpenWeatherMap），支持：
- 根据城市名查询当前天气
- 支持多语言城市名识别
- 返回温度、湿度、天气描述等信息**验收标准**:
- [ ] 实现天气查询工具类
- [ ] 添加工具配置文件
- [ ] 编写单元测试
- [ ] 更新相关文档**API 选择**: OpenWeatherMap API (免费额度足够)

9.2 技术方案设计

在获得团队确认后，我们开始设计技术方案：

# 技术方案文档
"""
天气查询工具技术方案1. 工具结构- 工具类：WeatherTool (继承自 BuiltinTool)- 配置文件：weather.yaml- 测试文件：test_weather_tool.py2. API 集成- 使用 OpenWeatherMap API- 支持城市名和经纬度查询- 错误处理和重试机制3. 多语言支持- 支持中英文城市名- 返回结果本地化4. 配置参数- api_key: OpenWeatherMap API 密钥- units: 温度单位 (metric/imperial)- lang: 返回语言
"""

9.3 代码实现

# api/core/tools/builtins/weather/weather.py
import requests
from typing import Any, Dict
from core.tools.entities.tool_entities import ToolInvokeMessage
from core.tools.tool.builtin_tool import BuiltinToolclass WeatherTool(BuiltinTool):"""天气查询工具"""def _invoke(self, user_id: str, tool_parameters: Dict[str, Any]) -> ToolInvokeMessage:"""调用天气查询工具Args:user_id: 用户IDtool_parameters: 工具参数- location: 查询位置- units: 温度单位 (可选)- lang: 语言 (可选)Returns:ToolInvokeMessage: 包含天气信息的消息"""try:# 参数验证location = tool_parameters.get('location', '').strip()if not location:return self.create_text_message('请提供查询位置')# 获取配置api_key = self.runtime.credentials.get('openweather_api_key')if not api_key:return self.create_text_message('未配置天气 API 密钥')units = tool_parameters.get('units', 'metric')lang = tool_parameters.get('lang', 'zh_cn')# 调用天气 APIweather_data = self._fetch_weather(location, api_key, units, lang)if not weather_data:return self.create_text_message(f'无法获取 {location} 的天气信息')# 格式化返回结果message = self._format_weather_message(weather_data, location)return self.create_text_message(message)except Exception as e:return self.create_text_message(f'查询天气时发生错误: {str(e)}')def _fetch_weather(self, location: str, api_key: str, units: str, lang: str) -> Dict[str, Any]:"""获取天气数据"""url = "http://api.openweathermap.org/data/2.5/weather"params = {'q': location,'appid': api_key,'units': units,'lang': lang}try:response = requests.get(url, params=params, timeout=10)response.raise_for_status()return response.json()except requests.RequestException:return {}def _format_weather_message(self, data: Dict[str, Any], location: str) -> str:"""格式化天气信息"""try:temp = data['main']['temp']feels_like = data['main']['feels_like']humidity = data['main']['humidity']description = data['weather'][0]['description']message = f"""📍 {location} 当前天气：
🌡️ 温度：{temp}°C（体感 {feels_like}°C）
💧 湿度：{humidity}%
☁️ 天气：{description}"""return messageexcept KeyError:return f"{location} 的天气数据格式异常"

9.4 配置文件

# api/core/tools/builtins/weather/weather.yaml
identity:name: weatherauthor: contributor@example.comlabel:en_US: Weather Queryzh_Hans: 天气查询
description:human:en_US: Query current weather information for any locationzh_Hans: 查询任意位置的当前天气信息llm: A tool for querying real-time weather information including temperature, humidity, and weather conditions for specified locations.parameters:- name: locationtype: stringrequired: truelabel:en_US: Locationzh_Hans: 位置human_description:en_US: The city or location to query weather for (e.g., "Beijing", "New York")zh_Hans: 需要查询天气的城市或位置（如："北京"、"纽约"）llm_description: The location name for weather query, can be city name or "city, country" formatform: llm- name: unitstype: selectrequired: falsedefault: metriclabel:en_US: Temperature Unitzh_Hans: 温度单位human_description:en_US: Temperature unit for the weather reportzh_Hans: 天气报告中的温度单位llm_description: Temperature unit (metric for Celsius, imperial for Fahrenheit)options:- value: metriclabel:en_US: Celsius (°C)zh_Hans: 摄氏度 (°C)- value: imperiallabel:en_US: Fahrenheit (°F)zh_Hans: 华氏度 (°F)form: form- name: langtype: selectrequired: falsedefault: zh_cnlabel:en_US: Languagezh_Hans: 语言human_description:en_US: Language for weather descriptionzh_Hans: 天气描述的语言llm_description: Language code for weather description localizationoptions:- value: zh_cnlabel:en_US: Chinesezh_Hans: 中文- value: enlabel:en_US: Englishzh_Hans: 英文form: formcredentials_for_provider:openweather_api_key:label:en_US: OpenWeatherMap API Keyzh_Hans: OpenWeatherMap API 密钥help:en_US: Get your API key from https://openweathermap.org/apizh_Hans: 从 https://openweathermap.org/api 获取您的 API 密钥url: https://openweathermap.org/api

9.5 单元测试

# api/tests/core/tools/builtins/test_weather.py
import pytest
from unittest.mock import Mock, patch
from core.tools.builtins.weather.weather import WeatherToolclass TestWeatherTool:"""天气工具测试类"""def setup_method(self):"""测试前置设置"""self.tool = WeatherTool()self.tool.runtime = Mock()self.tool.runtime.credentials = {'openweather_api_key': 'test_api_key'}@patch('core.tools.builtins.weather.weather.requests.get')def test_successful_weather_query(self, mock_get):"""测试成功的天气查询"""# 模拟 API 响应mock_response = Mock()mock_response.json.return_value = {'main': {'temp': 25.0,'feels_like': 27.0,'humidity': 60},'weather': [{'description': '晴天'}]}mock_response.raise_for_status.return_value = Nonemock_get.return_value = mock_response# 执行测试result = self.tool._invoke('test_user', {'location': '北京'})# 断言结果assert result.type == 'text'assert '北京' in result.messageassert '25.0°C' in result.messageassert '晴天' in result.messagedef test_missing_location(self):"""测试缺少位置参数"""result = self.tool._invoke('test_user', {})assert result.type == 'text'assert '请提供查询位置' in result.messagedef test_missing_api_key(self):"""测试缺少 API 密钥"""self.tool.runtime.credentials = {}result = self.tool._invoke('test_user', {'location': '北京'})assert result.type == 'text'assert '未配置天气 API 密钥' in result.message@patch('core.tools.builtins.weather.weather.requests.get')def test_api_error(self, mock_get):"""测试 API 错误"""mock_get.side_effect = Exception('API Error')result = self.tool._invoke('test_user', {'location': '北京'})assert result.type == 'text'assert '查询天气时发生错误' in result.message

9.6 文档更新

# docs/zh_hans/guides/tools/builtins/weather.md
# 天气查询工具天气查询工具允许 AI 助手查询任意位置的实时天气信息，包括温度、湿度、天气状况等详细信息。## 功能特性- 🌍 支持全球任意城市天气查询
- 🌡️ 提供温度、体感温度、湿度等详细信息
- 🗣️ 支持中英文天气描述
- ⚙️ 灵活的温度单位配置## 配置步骤### 1. 获取 API 密钥1. 访问 [OpenWeatherMap](https://openweathermap.org/api)
2. 注册账户并获取免费 API 密钥
3. 记录您的 API 密钥### 2. 配置工具1. 在 Dify 工作台中创建或编辑应用
2. 进入工具配置页面
3. 找到"天气查询"工具并启用
4. 输入您的 OpenWeatherMap API 密钥
5. 保存配置## 使用示例### 基本查询**用户输入**：北京的天气怎么样？**AI 回复**：

📍 北京 当前天气：
🌡️ 温度：25°C（体感 27°C）
💧 湿度：60%
☁️ 天气：晴天

### 多城市查询**用户输入**：帮我查一下纽约和伦敦的天气**AI 回复**：

📍 纽约 当前天气：
🌡️ 温度：22°C（体感 24°C）
💧 湿度：55%
☁️ 天气：多云

📍 伦敦 当前天气：
🌡️ 温度：18°C（体感 16°C）
💧 湿度：75%
☁️ 天气：小雨

## 注意事项- API 密钥每月有免费调用次数限制，请合理使用
- 支持中英文城市名，建议使用准确的城市名称
- 工具会自动处理网络错误和无效位置## 故障排除### 常见问题**Q: 提示"未配置天气 API 密钥"**
A: 请检查是否正确配置了 OpenWeatherMap API 密钥**Q: 查询结果显示"无法获取天气信息"**
A: 请检查城市名称是否正确，或尝试使用英文城市名**Q: API 调用频率限制**
A: 免费版本有调用次数限制，请考虑升级到付费版本或优化使用频率

9.7 PR 提交

# Pull Request 标题
feat: add weather query tool for agents# Pull Request 描述
## 变更概述
添加天气查询工具，允许 AI 助手查询实时天气信息。集成 OpenWeatherMap API，支持全球城市天气查询。## 变更类型
- [x] 新功能 (feat)
- [ ] 问题修复 (fix)
- [ ] 文档更新 (docs)
- [ ] 代码重构 (refactor)
- [ ] 性能优化 (perf)
- [ ] 测试相关 (test)## 功能特性
- ✅ 支持全球城市天气查询
- ✅ 中英文天气描述支持
- ✅ 温度单位可配置 (摄氏度/华氏度)
- ✅ 详细的错误处理和用户反馈
- ✅ 完整的单元测试覆盖## 测试清单
- [x] 单元测试通过 (coverage: 95%)
- [x] 集成测试通过
- [x] 手动功能测试验证
- [x] 错误场景测试## 文件变更

api/core/tools/builtins/weather/
├── init.py
├── weather.py # 工具实现
└── weather.yaml # 工具配置

api/tests/core/tools/builtins/
└── test_weather.py # 单元测试

docs/zh_hans/guides/tools/builtins/
└── weather.md # 用户文档

## 相关 Issue
Closes #1234## 演示截图
[包含工具配置和使用效果的截图]## 特殊说明
需要用户自行申请 OpenWeatherMap API 密钥，免费版本每月有 1000 次调用限制。

十、结语：开源精神的传承

回到这一章的开头，我提到开源项目的成功往往不在于技术本身，而在于社区。通过深入了解 Dify 的贡献体系，我们可以看到这个项目在社区建设上的用心：

10.1 Dify 社区的亮点

# Dify 社区成功要素分析
COMMUNITY_SUCCESS_FACTORS = {"技术门槛": {"lowered_barriers": ["详细的环境搭建指南","清晰的代码结构和注释","完善的 CI/CD 自动化检查"],"learning_resources": ["丰富的文档和示例","活跃的社区讨论","及时的问题响应"]},"贡献体验": {"smooth_process": ["标准化的 PR 流程","友好的代码审查文化","快速的反馈循环"],"recognition": ["贡献者在 README 中的展示","社区活动中的认可","职业发展机会的提供"]},"项目治理": {"transparent_decision": ["公开的功能规划讨论","清晰的优先级评估机制","包容性的社区文化"],"sustainable_development": ["核心团队的持续投入","商业模式的良性循环","长远发展规划的制定"]}
}

10.2 给未来贡献者的建议

作为一个在开源世界打拼多年的老兵，我想对准备加入 Dify 社区的朋友们说几句话：

保持好奇心和学习态度：开源项目是最好的学习平台，你将接触到世界级的代码和设计思想。

从小处开始，持续积累：不要一开始就想做大功能，从修复文档错误、添加注释开始，逐步建立影响力。

注重沟通和协作：技术能力重要，但沟通协作能力同样重要。学会清晰地表达想法，友好地处理分歧。

享受贡献的过程：开源贡献不仅仅是为了项目，更是为了自己的成长。享受学习新技术、解决问题、帮助他人的过程。

10.3 展望未来

随着 AI 技术的快速发展，像 Dify 这样的平台将变得越来越重要。作为开发者，我们不仅是技术的使用者，更应该成为技术的推动者。

def future_vision():"""对 Dify 社区未来的展望"""return {"技术愿景": ["更智能的 AI 应用开发体验","更完善的插件生态系统","更强大的企业级功能支持"],"社区愿景": ["更多样化的贡献者群体","更国际化的协作模式","更可持续的发展机制"],"个人成长": ["在实践中提升技术能力","在协作中培养领导力","在贡献中实现个人价值"]}

最后的话

这一章我们深入探讨了 Dify 的开源贡献体系，从流程规范到实战案例，从技术细节到社区文化。好的开源项目就像一个活跃的生态系统，每个贡献者都是其中不可或缺的一部分。

下一章，我们将探讨《未来架构演进展望》，看看 Dify 在技术和生态方面的发展规划，以及我们作为开发者如何在这个演进过程中找到自己的位置。

如果你在阅读这一章后有任何问题或想法，欢迎在社区中与我们交流。记住，最好的学习方式就是实践，最好的贡献方式就是开始行动。

让我们一起在开源的海洋中乘风破浪，用代码改变世界！

---

本章要点回顾：

✅ 贡献流程：从 Issue 讨论到 PR 合并的完整路径
✅ 环境搭建：开发者友好的配置指南和避坑技巧
✅ 专业贡献：模型提供商、工具开发、前端组件的实战指导
✅ 代码审查：高质量协作的艺术和最佳实践
✅ 社区参与：从技术贡献到社区建设的多元化路径
✅ 实战案例：天气查询工具的完整开发流程

下章预告：第20章《未来架构演进展望》将带你了解 Dify 的技术发展路线图，探讨 AI 应用开发平台的未来趋势，以及我们如何在技术演进中把握机遇。

---

“开源不仅仅是代码的共享，更是智慧的传承和创新的催化剂。”