Pixelle-Video 贡献指南从 Fork 到 Pull Request 的完整开发协作流程【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video本篇技术指南面向希望参与 Pixelle-Video 开源项目开发的开发者系统讲解从 Fork 仓库、搭建本地开发环境、遵守代码规范到提交 Pull Request 与提交 Issue 的完整协作流程。读完本文你将掌握基于uv的依赖管理与测试运行方式、项目强制执行的 PEP 8 与测试标准以及让 PR 快速被维护者合入的实践要点。文中所有命令与配置均以当前仓库实际内容为准可直接复制运行。一、先了解你要贡献的项目在动手提交代码之前建议先浏览仓库的顶层结构明确各目录职责pixelle_video/核心业务逻辑包含服务层llm_service.py、tts_service.py、media.py 等、流水线pipelines、配置管理config与提示词模板promptsweb/基于 Streamlit 的 Web 界面层入口为 web/app.py各功能页位于 web/pagesapi/FastAPI 实现的 REST 接口层路由定义在 api/routerstemplates/按画幅1080x1080、1080x1920、1920x1080组织的 HTML 视频模板workflows/ComfyUI / RunningHub 工作流 JSON 定义分为runninghub/与selfhost/两套来源docs/多语言en/zh技术文档即本指南所在位置config.example.yaml默认配置模板配置文件详解 对此有完整说明。从架构文档architecture.md可以看到项目采用分层设计Web 层Streamlit→ 服务层核心业务逻辑→ ComfyUI 层图像与 TTS 生成核心协调类为PixelleVideoCore见 service.py它统一管理 LLM 文案生成、图像服务、TTS 语音与最终视频合成。理解了这条调用链你就能快速定位某个功能改动应落在哪个目录。二、贡献工作流从 Fork 到 Pull Request官方贡献流程见 contributing.md共五步下面逐一步说明并补充实战细节。1. Fork 仓库点击项目仓库页面右上角的Fork按钮将仓库复制到你的账号下。Fork 之后你就拥有了一个独立的远程副本可以自由修改而不影响上游。2. 创建特性分支永远不要在main或master分支上直接开发。每次改动都应从最新的主干切出独立分支命名建议与功能强相关例如git checkout -b feature/AmazingFeature分支命名习惯上使用feature/、fix/、docs/等前缀让维护者一眼看出改动类型。3. 提交更改保持提交粒度清晰、语义明确一条提交只做一件事git commit -m Add some AmazingFeature提交信息建议使用祈使句说明“做了什么、为什么这么做”。对于涉及多个模块的改动拆分成多个逻辑提交比一个巨型提交更容易被 review。4. 推送分支git push origin feature/AmazingFeature将本地分支推送到你 Fork 出的远程仓库。5. 打开 Pull Request在 Fork 仓库页面点击New Pull Request选择你的特性分支与上游目标分支填写 PR 标题与描述。一份好的 PR 描述通常包含本次改动解决了什么问题可关联对应 Issue 编号改动的核心实现思路自测结果本地测试是否通过、是否手动跑过 Web 界面验证新增或修改了哪些测试用例。三、搭建本地开发环境原文档的 Development Setup 部分是整个指南的实操核心下面结合仓库的 pyproject.toml 逐条展开。1. 克隆仓库git clone https://github.com/your-username/Pixelle-Video.git cd Pixelle-Video若只想查看或运行项目本体直接克隆上游仓库即可需要提交 PR 时再使用你 Fork 后的地址替换your-username。2. 使用 uv 安装依赖官方推荐项目以uv作为包管理器pyproject.toml 声明了requires-python 3.11与完整运行时依赖uv.lock锁定了精确版本。执行uv syncuv会依据pyproject.toml与uv.lock自动创建虚拟环境并安装全部依赖无需手动venv。对于开发场景还需安装可选开发依赖组uv sync --extra devpyproject.toml 中[project.optional-dependencies].dev定义如下dev [ pytest8.0.0, pytest-asyncio0.23.0, ruff0.6.0, ]其中pytest-asyncio用于测试异步代码项目大量使用 AsyncIOruff是代码静态检查工具。开发依赖与运行时依赖分离避免污染生产环境。不使用uv时也可pip install -e .安装完整步骤见安装指南。3. 验证安装启动 Web 界面依赖安装完成后可先启动 Streamlit Web 界面确认环境可用。仓库自带的启动脚本 start_web.sh 内容即#!/bin/bash # Start Pixelle-Video Web UI echo Starting Pixelle-Video Web UI... uv run streamlit run web/app.py因此只需执行bash start_web.sh或直接运行uv run streamlit run web/app.py浏览器访问http://localhost:8501看到 Web 界面即说明环境搭建成功。Windows 用户可参考同目录的 start_web.bat 或直接使用官方 Windows 整合包详见安装指南。4. 运行测试uv run pytestpyproject.toml 中预置了 pytest 配置[tool.pytest.ini_options] asyncio_mode auto testpaths [tests]asyncio_mode auto测试函数无需手动标记pytest.mark.asyncio异步用例会被自动识别执行testpaths [tests]pytest 默认只在tests/目录下发现测试文件。因此新增单元测试时请统一放入仓库根目录的tests/目录下并按test_*.py规则命名确保能被 pytest 自动收集。提交 PR 前务必保证全量测试通过。四、代码规范与质量工具原文档明确了三条硬性标准以下逐条展开为可操作的检查项。1. 所有代码与注释使用英文项目面向全球贡献者与维护者代码、注释、文档字符串docstring、PR 与 Issue 一律使用英文保持协作语言统一。2. 遵循 PEP 8 标准PEP 8 是 Python 官方编码风格指南核心要点包括4 空格缩进、行宽限制、命名规范类名PascalCase、函数与变量snake_case、常量UPPER_CASE等。项目已通过ruff将大部分规范固化为自动检查pyproject.toml 中的配置如下[tool.ruff] line-length 100 target-version py311 [tool.ruff.lint] select [E, F, I] ignore [E501]解读line-length 100行宽上限 100 字符较 PEP 8 默认的 79 更宽松target-version py311按 Python 3.11 语法特性解析代码select [E, F, I]启用错误类E含缩进、行尾空白等、Pyflakes 类F未使用导入、未定义名称等、导入排序类Iimport 顺序规范ignore [E501]行过长检查被显式忽略因为已单独配置line-length 100。提交前请运行 lint 检查uv run ruff check .若存在导入排序问题可自动修复uv run ruff check . --fix保持零 lint 告警是合入 PR 的基本门槛。3. 添加适当的测试“Add appropriate tests”意味着任何行为变更都应配套测试新功能为新增函数/类编写覆盖正常路径的单元测试缺陷修复先写一个能复现该 bug 的失败测试再修复代码使其通过回归测试涉及异步逻辑利用asyncio_mode auto直接编写async def test_...用例例如验证 LLMService 的调用与结构化输出解析response_type参数。用 pixelle_video/services/llm_service.py 举例该服务基于 OpenAI SDK 实现支持任意 OpenAI 兼容供应商OpenAI、通义千问、DeepSeek、Ollama 等并通过response_typePydantic 模型返回结构化结果。若你修改了其 prompt 解析逻辑就应在tests/下补充相应的解析用例。五、提交 Issue报告问题与功能建议贡献不限于写代码。遇到使用问题、发现 bug 或想提出功能建议时请通过仓库的Issues页面提交入口可从仓库首页顶部导航进入原文档指向的 GitHub Issues 页面即此功能。高质量 Issue 的要素Bug 报告描述期望行为与实际行为、复现步骤、运行环境操作系统、Python 版本、依赖版本、相关日志或截图若涉及 Web 界面操作注明页面与配置项功能建议说明使用场景、期望能力与可选实现思路便于维护者评估使用问题先查阅 FAQ 与故障排查避免重复提问。提交前建议先搜索是否已有相同或相近的 Issue减少重复。六、社区行为准则项目致力于营造开放包容的社区环境原文档 Code of Conduct 部分。参与讨论、Issue 与 PR review 时请保持友善与尊重对不同经验水平、不同背景的贡献者一视同仁。具体而言用建设性语气提出意见避免人身攻击或武断否定对新手保持耐心review 时给出“为什么这样改更好”的解释而非只贴结论尊重维护者的决策与项目既定方向重大改动先通过 Issue 沟通再动工。七、给贡献者的切入建议如果你初到仓库不知从何入手以下路径可帮助你快速进入状态从文档与配置入手阅读 architecture.md 理解分层对照 config.example.yaml 与配置文档 弄清每个配置项的用途从 Issue 起步挑选标有good first issue或help wanted标签的条目这类任务通常范围明确、上手成本低先小后大优先提交文档修正、错误提示优化、测试补充等低风险改动建立对 CI/lint/测试流程的熟悉度后再触碰核心流水线如 pipelines/standard.py本地验证闭环任何改动都要经历uv run ruff check .零告警→uv run pytest全绿→ 启动 Web 界面人工验证 三步确认无误后再推送并开启 PR。遵循上述流程与规范你的贡献将更容易被审查与合入。期待你的第一个 Pull Request。【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pixelle-Video 贡献指南：从 Fork 到 Pull Request 的完整开发协作流程
Pixelle-Video 贡献指南从 Fork 到 Pull Request 的完整开发协作流程【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video本篇技术指南面向希望参与 Pixelle-Video 开源项目开发的开发者系统讲解从 Fork 仓库、搭建本地开发环境、遵守代码规范到提交 Pull Request 与提交 Issue 的完整协作流程。读完本文你将掌握基于uv的依赖管理与测试运行方式、项目强制执行的 PEP 8 与测试标准以及让 PR 快速被维护者合入的实践要点。文中所有命令与配置均以当前仓库实际内容为准可直接复制运行。一、先了解你要贡献的项目在动手提交代码之前建议先浏览仓库的顶层结构明确各目录职责pixelle_video/核心业务逻辑包含服务层llm_service.py、tts_service.py、media.py 等、流水线pipelines、配置管理config与提示词模板promptsweb/基于 Streamlit 的 Web 界面层入口为 web/app.py各功能页位于 web/pagesapi/FastAPI 实现的 REST 接口层路由定义在 api/routerstemplates/按画幅1080x1080、1080x1920、1920x1080组织的 HTML 视频模板workflows/ComfyUI / RunningHub 工作流 JSON 定义分为runninghub/与selfhost/两套来源docs/多语言en/zh技术文档即本指南所在位置config.example.yaml默认配置模板配置文件详解 对此有完整说明。从架构文档architecture.md可以看到项目采用分层设计Web 层Streamlit→ 服务层核心业务逻辑→ ComfyUI 层图像与 TTS 生成核心协调类为PixelleVideoCore见 service.py它统一管理 LLM 文案生成、图像服务、TTS 语音与最终视频合成。理解了这条调用链你就能快速定位某个功能改动应落在哪个目录。二、贡献工作流从 Fork 到 Pull Request官方贡献流程见 contributing.md共五步下面逐一步说明并补充实战细节。1. Fork 仓库点击项目仓库页面右上角的Fork按钮将仓库复制到你的账号下。Fork 之后你就拥有了一个独立的远程副本可以自由修改而不影响上游。2. 创建特性分支永远不要在main或master分支上直接开发。每次改动都应从最新的主干切出独立分支命名建议与功能强相关例如git checkout -b feature/AmazingFeature分支命名习惯上使用feature/、fix/、docs/等前缀让维护者一眼看出改动类型。3. 提交更改保持提交粒度清晰、语义明确一条提交只做一件事git commit -m Add some AmazingFeature提交信息建议使用祈使句说明“做了什么、为什么这么做”。对于涉及多个模块的改动拆分成多个逻辑提交比一个巨型提交更容易被 review。4. 推送分支git push origin feature/AmazingFeature将本地分支推送到你 Fork 出的远程仓库。5. 打开 Pull Request在 Fork 仓库页面点击New Pull Request选择你的特性分支与上游目标分支填写 PR 标题与描述。一份好的 PR 描述通常包含本次改动解决了什么问题可关联对应 Issue 编号改动的核心实现思路自测结果本地测试是否通过、是否手动跑过 Web 界面验证新增或修改了哪些测试用例。三、搭建本地开发环境原文档的 Development Setup 部分是整个指南的实操核心下面结合仓库的 pyproject.toml 逐条展开。1. 克隆仓库git clone https://github.com/your-username/Pixelle-Video.git cd Pixelle-Video若只想查看或运行项目本体直接克隆上游仓库即可需要提交 PR 时再使用你 Fork 后的地址替换your-username。2. 使用 uv 安装依赖官方推荐项目以uv作为包管理器pyproject.toml 声明了requires-python 3.11与完整运行时依赖uv.lock锁定了精确版本。执行uv syncuv会依据pyproject.toml与uv.lock自动创建虚拟环境并安装全部依赖无需手动venv。对于开发场景还需安装可选开发依赖组uv sync --extra devpyproject.toml 中[project.optional-dependencies].dev定义如下dev [ pytest8.0.0, pytest-asyncio0.23.0, ruff0.6.0, ]其中pytest-asyncio用于测试异步代码项目大量使用 AsyncIOruff是代码静态检查工具。开发依赖与运行时依赖分离避免污染生产环境。不使用uv时也可pip install -e .安装完整步骤见安装指南。3. 验证安装启动 Web 界面依赖安装完成后可先启动 Streamlit Web 界面确认环境可用。仓库自带的启动脚本 start_web.sh 内容即#!/bin/bash # Start Pixelle-Video Web UI echo Starting Pixelle-Video Web UI... uv run streamlit run web/app.py因此只需执行bash start_web.sh或直接运行uv run streamlit run web/app.py浏览器访问http://localhost:8501看到 Web 界面即说明环境搭建成功。Windows 用户可参考同目录的 start_web.bat 或直接使用官方 Windows 整合包详见安装指南。4. 运行测试uv run pytestpyproject.toml 中预置了 pytest 配置[tool.pytest.ini_options] asyncio_mode auto testpaths [tests]asyncio_mode auto测试函数无需手动标记pytest.mark.asyncio异步用例会被自动识别执行testpaths [tests]pytest 默认只在tests/目录下发现测试文件。因此新增单元测试时请统一放入仓库根目录的tests/目录下并按test_*.py规则命名确保能被 pytest 自动收集。提交 PR 前务必保证全量测试通过。四、代码规范与质量工具原文档明确了三条硬性标准以下逐条展开为可操作的检查项。1. 所有代码与注释使用英文项目面向全球贡献者与维护者代码、注释、文档字符串docstring、PR 与 Issue 一律使用英文保持协作语言统一。2. 遵循 PEP 8 标准PEP 8 是 Python 官方编码风格指南核心要点包括4 空格缩进、行宽限制、命名规范类名PascalCase、函数与变量snake_case、常量UPPER_CASE等。项目已通过ruff将大部分规范固化为自动检查pyproject.toml 中的配置如下[tool.ruff] line-length 100 target-version py311 [tool.ruff.lint] select [E, F, I] ignore [E501]解读line-length 100行宽上限 100 字符较 PEP 8 默认的 79 更宽松target-version py311按 Python 3.11 语法特性解析代码select [E, F, I]启用错误类E含缩进、行尾空白等、Pyflakes 类F未使用导入、未定义名称等、导入排序类Iimport 顺序规范ignore [E501]行过长检查被显式忽略因为已单独配置line-length 100。提交前请运行 lint 检查uv run ruff check .若存在导入排序问题可自动修复uv run ruff check . --fix保持零 lint 告警是合入 PR 的基本门槛。3. 添加适当的测试“Add appropriate tests”意味着任何行为变更都应配套测试新功能为新增函数/类编写覆盖正常路径的单元测试缺陷修复先写一个能复现该 bug 的失败测试再修复代码使其通过回归测试涉及异步逻辑利用asyncio_mode auto直接编写async def test_...用例例如验证 LLMService 的调用与结构化输出解析response_type参数。用 pixelle_video/services/llm_service.py 举例该服务基于 OpenAI SDK 实现支持任意 OpenAI 兼容供应商OpenAI、通义千问、DeepSeek、Ollama 等并通过response_typePydantic 模型返回结构化结果。若你修改了其 prompt 解析逻辑就应在tests/下补充相应的解析用例。五、提交 Issue报告问题与功能建议贡献不限于写代码。遇到使用问题、发现 bug 或想提出功能建议时请通过仓库的Issues页面提交入口可从仓库首页顶部导航进入原文档指向的 GitHub Issues 页面即此功能。高质量 Issue 的要素Bug 报告描述期望行为与实际行为、复现步骤、运行环境操作系统、Python 版本、依赖版本、相关日志或截图若涉及 Web 界面操作注明页面与配置项功能建议说明使用场景、期望能力与可选实现思路便于维护者评估使用问题先查阅 FAQ 与故障排查避免重复提问。提交前建议先搜索是否已有相同或相近的 Issue减少重复。六、社区行为准则项目致力于营造开放包容的社区环境原文档 Code of Conduct 部分。参与讨论、Issue 与 PR review 时请保持友善与尊重对不同经验水平、不同背景的贡献者一视同仁。具体而言用建设性语气提出意见避免人身攻击或武断否定对新手保持耐心review 时给出“为什么这样改更好”的解释而非只贴结论尊重维护者的决策与项目既定方向重大改动先通过 Issue 沟通再动工。七、给贡献者的切入建议如果你初到仓库不知从何入手以下路径可帮助你快速进入状态从文档与配置入手阅读 architecture.md 理解分层对照 config.example.yaml 与配置文档 弄清每个配置项的用途从 Issue 起步挑选标有good first issue或help wanted标签的条目这类任务通常范围明确、上手成本低先小后大优先提交文档修正、错误提示优化、测试补充等低风险改动建立对 CI/lint/测试流程的熟悉度后再触碰核心流水线如 pipelines/standard.py本地验证闭环任何改动都要经历uv run ruff check .零告警→uv run pytest全绿→ 启动 Web 界面人工验证 三步确认无误后再推送并开启 PR。遵循上述流程与规范你的贡献将更容易被审查与合入。期待你的第一个 Pull Request。【免费下载链接】Pixelle-Video AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考