Dify 开源贡献实战从领 good first issue 到 PR 合并的完整指南【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify这是一份面向首次提交 PR 开发者的 Dify 开源贡献指南该往哪个仓库提改动、怎么提一个维护者能直接上手的 Issue、如何用 uv 和 pnpm 搭好本地开发环境、怎么跑通测试与代码质量工具链直到提交 PR 前的最后一步。走完这条路线你就有了一次完整合并的全部弹药。先认准目标仓库三类任务、三个入口Dify 的代码体系拆成主仓库加两个插件仓库提错地方是最常见的白干原因——比如把模型运行时改动提进主仓库会被直接打回。所以下手前先对号入座常规代码工作UI 缺陷、API 修复、文档在主仓库的 Issue 列表里筛选good first issue标签挑一个入门任务新增模型运行时或工具去独立的插件仓库dify-plugins开 PR更新现有模型/工具、修复插件 Bug去官方插件仓库dify-official-plugins。 无论走哪条路都有一条共同规则PR 描述里必须关联一个已存在的 Issue或者先建 Issue 讨论再开 PR。先讨论后动工等于先领工单再进场能避免你改完方向才发现维护者不打算那样做。提 Issue 的门道让维护者立刻能上手Issue 写得好不好直接决定它能否被打上优先级标签、你后续的 PR 能否顺利获批。Bug 报告和功能请求的要求不太一样分开看。Bug 报告官方要求包含的信息可以整理成一张清单清晰且具描述性的标题详细的问题描述附完整错误信息可复现的步骤steps to reproduce期望行为expected behavior后端日志——后端问题必附用docker-compose logs获取截图或视频如适用⚠️ 官方文档对其中一条单独加粗强调后端问题的日志不是可选的。优先级上官方把核心功能故障无法登录、应用不可用、安全漏洞定为 Critical非关键缺陷和性能优化是 Medium错别字这类小修是 Low。功能请求四要素描述性标题、功能详细描述、应用场景use case、其他上下文或截图。被团队成员标记的为高优先级社区反馈看板里受欢迎的请求是中优先级非核心小增强是低优先级有价值但不紧急的会归入 Future-Feature。一键搭好本地环境uv 后端与 pnpm 前端本地环境的质量决定迭代速度。好消息是dev/目录下的脚本都按相对自身位置解析路径编写你可以在任意目录执行它们。后端五步就位前提装好uv和pnpm。后端自 v1.3.0 起已从 poetry 切换到 uv 管理依赖按顺序执行./dev/setup # 拷贝 api/.env、web/.env.local、docker/middleware.env 并安装前后端依赖 ./dev/start-docker-compose # 启动 PostgreSQL / Redis / Weaviate 中间件 ./dev/start-api # 先跑数据库迁移再启动 API ./dev/start-web # 启动前端经根工作区安装 JS 依赖无需单独进 web 目录 ./dev/start-worker # 启动异步任务 worker可选 ./dev/start-beat 跑 Celery Beat启动后打开http://localhost:3000完成应用初始化。整套本地栈拉起后的服务拓扑大致如下两个要命的环境配置坑SECRET_KEY必须在api/.env里生成一个随机值Linux 下一条命令搞定sed -i /^SECRET_KEY/c\SECRET_KEY$(openssl rand -base64 42) .envCOOKIE_DOMAIN当前后端跑在不同子域时把它设为站点顶级域名如example.com。否则前后端无法共享认证 Cookie你会遇到刷新一次就掉登录这类怪问题。前端三步就位Node.js 与 pnpm 的版本由根目录package.json的devEngines.runtime和packageManager字段固定Node 24.20.0、pnpm 11.25.0照用即可。JavaScript 依赖由根工作区统一管理所以务必从仓库根目录操作pnpm install # 根工作区安装全部 JS 依赖 cp web/.env.example web/.env.local # 生成前端环境变量文件 pnpm dev # 启动默认开发栈vinext 本地 API 代理pnpm dev与pnpm -C web dev不是同一个东西前者带 vinext 和代理后者是裸 Next.js 开发服务器明确需要时再用。单独改 UI 组件时pnpm -C web storybook会另开一个 6006 端口的组件工作台改代码页面自动热更新。证明改动没破坏行为测试与代码质量工具链仓库的测试理念是测试保护可观测契约而不是每个文件都得有测试。理解这一点你才不会写出维护者不想要的测试。后端pytest reformatcd api uv sync --group dev # 安装测试环境依赖模拟环境变量在 pyproject.toml 的 tool.pytest_env 里 uv run pytest tests/unit_tests/ # 只跑单元测试集成测试用 tests/integration_tests/ ./dev/reformat # 跑齐全部格式化器与 linter代码质量记住它就够了./dev/reformat实际依次执行lint-imports架构分层检查、ruff check --fix、ruff format、dotenv-linter校验api/.env.example与web/.env.example注释一致性以及本地 pyrefly 类型检查。另外api/tests/下还有一层test_containers_integration_tests/Docker 容器化集成测试通常由 CI 执行本地不必强求。前端用 vp 跑别用 vitest前端基于 Vitest React Testing Library但项目采用 Vitevitest命令不可用必须通过vp执行cd web vp test run --project unit两个边界要守住标准单元测试跑在happy-dom环境browser项目只留给确实依赖真实浏览器行为的用例CSS 布局、原生焦点、真实指针输入等不要用裸vp test它会连 Browser Mode 在内跑掉所有已注册项目。至于什么时候该补测试web/docs/test.md 给得很明确改动影响用户交互与 UI 状态、导航与持久化、可到达的加载/成功/错误/空状态、可访问性语义或是可复现回归的 Bug 修复时才写仅因文件存在覆盖率缺口TypeScript 已保证类型而补的测试不被鼓励。提 PR 前自查清单官方 PR 流程是七步Fork 仓库 → 起草前先建 Issue 讨论 → 独立分支 → 可观测行为变更时补测试 → 既有测试全绿 → PR 描述关联 Issue → 等合并。开 PR 前把它过一遍描述里关联了 Issue修 Bug 的写fixes #issue number合并后 Issue 自动关闭改动在独立分支上且没有夹带无关提交测试补齐、既有测试通过前端vp test run --project unit后端./dev/reformat加 pytest 均绿后端改动对照 api/AGENTS.md 的分层约定如果你的改动落在后端最后这四项尤其值得核对传输解析与序列化留在 controllers编排逻辑放 services领域策略进core/配置统一经configs.dify_config读取出站 HTTP 走现有的 SSRF 安全出口core/helper/ssrf_proxy.py请求/响应模型用 Pydantic v2异步工作复用现有 Celery 任务归属者可重试任务必须保持副作用幂等。修改 controller schema 或SystemFeatureModel前先读 api/controllers/API_SCHEMA_GUIDE.md。卡住了去哪找人以及你的下一步环境起不来或测试跑不过先在对应 Issue 里留言——维护者通常都在看想要更快的响应去 Dify 官方 Discord 社区聊聊入口在根目录 README 的 Community 部分。所以现在就动手去主仓库 Issue 列表按good first issue筛出清单挑一个你最有把握的认领然后按本文的五步把本地环境拉起来。环境绿了你的第一次贡献就只隔着一份 PR 描述的距离了。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Dify 开源贡献实战：从领 good first issue 到 PR 合并的完整指南
Dify 开源贡献实战从领 good first issue 到 PR 合并的完整指南【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify这是一份面向首次提交 PR 开发者的 Dify 开源贡献指南该往哪个仓库提改动、怎么提一个维护者能直接上手的 Issue、如何用 uv 和 pnpm 搭好本地开发环境、怎么跑通测试与代码质量工具链直到提交 PR 前的最后一步。走完这条路线你就有了一次完整合并的全部弹药。先认准目标仓库三类任务、三个入口Dify 的代码体系拆成主仓库加两个插件仓库提错地方是最常见的白干原因——比如把模型运行时改动提进主仓库会被直接打回。所以下手前先对号入座常规代码工作UI 缺陷、API 修复、文档在主仓库的 Issue 列表里筛选good first issue标签挑一个入门任务新增模型运行时或工具去独立的插件仓库dify-plugins开 PR更新现有模型/工具、修复插件 Bug去官方插件仓库dify-official-plugins。 无论走哪条路都有一条共同规则PR 描述里必须关联一个已存在的 Issue或者先建 Issue 讨论再开 PR。先讨论后动工等于先领工单再进场能避免你改完方向才发现维护者不打算那样做。提 Issue 的门道让维护者立刻能上手Issue 写得好不好直接决定它能否被打上优先级标签、你后续的 PR 能否顺利获批。Bug 报告和功能请求的要求不太一样分开看。Bug 报告官方要求包含的信息可以整理成一张清单清晰且具描述性的标题详细的问题描述附完整错误信息可复现的步骤steps to reproduce期望行为expected behavior后端日志——后端问题必附用docker-compose logs获取截图或视频如适用⚠️ 官方文档对其中一条单独加粗强调后端问题的日志不是可选的。优先级上官方把核心功能故障无法登录、应用不可用、安全漏洞定为 Critical非关键缺陷和性能优化是 Medium错别字这类小修是 Low。功能请求四要素描述性标题、功能详细描述、应用场景use case、其他上下文或截图。被团队成员标记的为高优先级社区反馈看板里受欢迎的请求是中优先级非核心小增强是低优先级有价值但不紧急的会归入 Future-Feature。一键搭好本地环境uv 后端与 pnpm 前端本地环境的质量决定迭代速度。好消息是dev/目录下的脚本都按相对自身位置解析路径编写你可以在任意目录执行它们。后端五步就位前提装好uv和pnpm。后端自 v1.3.0 起已从 poetry 切换到 uv 管理依赖按顺序执行./dev/setup # 拷贝 api/.env、web/.env.local、docker/middleware.env 并安装前后端依赖 ./dev/start-docker-compose # 启动 PostgreSQL / Redis / Weaviate 中间件 ./dev/start-api # 先跑数据库迁移再启动 API ./dev/start-web # 启动前端经根工作区安装 JS 依赖无需单独进 web 目录 ./dev/start-worker # 启动异步任务 worker可选 ./dev/start-beat 跑 Celery Beat启动后打开http://localhost:3000完成应用初始化。整套本地栈拉起后的服务拓扑大致如下两个要命的环境配置坑SECRET_KEY必须在api/.env里生成一个随机值Linux 下一条命令搞定sed -i /^SECRET_KEY/c\SECRET_KEY$(openssl rand -base64 42) .envCOOKIE_DOMAIN当前后端跑在不同子域时把它设为站点顶级域名如example.com。否则前后端无法共享认证 Cookie你会遇到刷新一次就掉登录这类怪问题。前端三步就位Node.js 与 pnpm 的版本由根目录package.json的devEngines.runtime和packageManager字段固定Node 24.20.0、pnpm 11.25.0照用即可。JavaScript 依赖由根工作区统一管理所以务必从仓库根目录操作pnpm install # 根工作区安装全部 JS 依赖 cp web/.env.example web/.env.local # 生成前端环境变量文件 pnpm dev # 启动默认开发栈vinext 本地 API 代理pnpm dev与pnpm -C web dev不是同一个东西前者带 vinext 和代理后者是裸 Next.js 开发服务器明确需要时再用。单独改 UI 组件时pnpm -C web storybook会另开一个 6006 端口的组件工作台改代码页面自动热更新。证明改动没破坏行为测试与代码质量工具链仓库的测试理念是测试保护可观测契约而不是每个文件都得有测试。理解这一点你才不会写出维护者不想要的测试。后端pytest reformatcd api uv sync --group dev # 安装测试环境依赖模拟环境变量在 pyproject.toml 的 tool.pytest_env 里 uv run pytest tests/unit_tests/ # 只跑单元测试集成测试用 tests/integration_tests/ ./dev/reformat # 跑齐全部格式化器与 linter代码质量记住它就够了./dev/reformat实际依次执行lint-imports架构分层检查、ruff check --fix、ruff format、dotenv-linter校验api/.env.example与web/.env.example注释一致性以及本地 pyrefly 类型检查。另外api/tests/下还有一层test_containers_integration_tests/Docker 容器化集成测试通常由 CI 执行本地不必强求。前端用 vp 跑别用 vitest前端基于 Vitest React Testing Library但项目采用 Vitevitest命令不可用必须通过vp执行cd web vp test run --project unit两个边界要守住标准单元测试跑在happy-dom环境browser项目只留给确实依赖真实浏览器行为的用例CSS 布局、原生焦点、真实指针输入等不要用裸vp test它会连 Browser Mode 在内跑掉所有已注册项目。至于什么时候该补测试web/docs/test.md 给得很明确改动影响用户交互与 UI 状态、导航与持久化、可到达的加载/成功/错误/空状态、可访问性语义或是可复现回归的 Bug 修复时才写仅因文件存在覆盖率缺口TypeScript 已保证类型而补的测试不被鼓励。提 PR 前自查清单官方 PR 流程是七步Fork 仓库 → 起草前先建 Issue 讨论 → 独立分支 → 可观测行为变更时补测试 → 既有测试全绿 → PR 描述关联 Issue → 等合并。开 PR 前把它过一遍描述里关联了 Issue修 Bug 的写fixes #issue number合并后 Issue 自动关闭改动在独立分支上且没有夹带无关提交测试补齐、既有测试通过前端vp test run --project unit后端./dev/reformat加 pytest 均绿后端改动对照 api/AGENTS.md 的分层约定如果你的改动落在后端最后这四项尤其值得核对传输解析与序列化留在 controllers编排逻辑放 services领域策略进core/配置统一经configs.dify_config读取出站 HTTP 走现有的 SSRF 安全出口core/helper/ssrf_proxy.py请求/响应模型用 Pydantic v2异步工作复用现有 Celery 任务归属者可重试任务必须保持副作用幂等。修改 controller schema 或SystemFeatureModel前先读 api/controllers/API_SCHEMA_GUIDE.md。卡住了去哪找人以及你的下一步环境起不来或测试跑不过先在对应 Issue 里留言——维护者通常都在看想要更快的响应去 Dify 官方 Discord 社区聊聊入口在根目录 README 的 Community 部分。所以现在就动手去主仓库 Issue 列表按good first issue筛出清单挑一个你最有把握的认领然后按本文的五步把本地环境拉起来。环境绿了你的第一次贡献就只隔着一份 PR 描述的距离了。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
