拓冰网站定制 
LiveKit Agents 开源贡献指南从编写 Provider 插件到通过 CI 代码质量门禁【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents本文以仓库内的 CONTRIBUTING.md 为主体完整梳理 LiveKit Agents 框架的开源贡献路径如何为一个 TTS/STT/LLM Provider 编写插件、如何修复缺陷与新增功能、如何在本地复现 CI 的代码质量检查ruff 格式化与 lint、mypy 严格类型检查、pdoc3 API 文档以及 Pull Request 的合入流程CLA 签署、CHANGELOG 自动化。读完后你可以独立完成一个符合该仓库工程规范的插件或缺陷修复并让改动顺利通过 CI 门禁。贡献总览与社区规范CONTRIBUTING.md 开宗明义LiveKit Agents 是开源项目欢迎所有本着诚意与社区协作的贡献者没有任何贡献太小。项目贡献遵循以下社区约定行为准则所有贡献者必须遵守项目的 行为准则。CLA 签署你的第一个 Pull Request 会触发 CLA Assistant 机器人提供本项目贡献者许可协议Contributor License Agreement的签署链接这是代码进入仓库的前提。社区互助即使不写代码也可以帮助社区成员解答框架使用问题——加入官方 Slack 的#agents频道即可参与。自动化维护不需要手工维护CHANGELOG.md或包清单文件这些由机器人和 Maintainer 在合并前处理贡献者只需关注代码本身。三种代码贡献路径文档明确给出三条贡献代码的途径各适合不同能力的贡献者编写插件Write a plugin如果你在用的 TTS/STT/LLM Provider 还不在插件列表中可以直接为其编写插件文档建议参考同类型插件的源码来理解构建方式。修复缺陷Fix bugs项目致力于保持框架尽可能可靠欢迎任何人帮助消除缺陷、提升稳定性具体流程遵循文档中的 Pull Request 指南。新增功能Add new features框架接受新功能但文档要求先开 Issue 讨论可行性与范围再动手实现避免无效工作。编写 Provider 插件从模板到注册文档建议参考相似插件的源码仓库里恰好内置了一个最小化模板livekit-plugins-minimal其 README 与 pyproject.toml 定义了完整的最小插件骨架。一个最小插件的结构如下# livekit-plugins/livekit-plugins-minimal/livekit/plugins/minimal/__init__.py from livekit.agents import Plugin from .log import logger from .version import __version__ class MinimalPlugin(Plugin): def __init__(self) - None: super().__init__(__name__, __version__, __package__, logger) Plugin.register_plugin(MinimalPlugin())从源码结构看这套注册机制的核心是框架的Plugin基类plugin.py构造函数要求传入title、version、package及一个 loggerregister_plugin()是一个类方法要求必须在主线程调用否则抛出RuntimeError并将实例追加到registered_plugins列表、发出plugin_registered事件供框架后续发现插件插件还可以可选地实现download_files()方法用于在启动时下载模型等文件。在 livekit-plugins-minimal/pyproject.toml 中可以看到一个插件包的完整工程约定requires-python 3.10.0、依赖livekit-agents1.8.0、版本从livekit/plugins/minimal/version.py动态读取当前为1.8.0、打包目标包含livekit目录。值得注意的是本仓库采用uv workspace组织所有插件根 pyproject.toml 的[tool.uv.workspace]成员列表与[tool.uv.sources]把livekit-plugins/*下 50 插件openai、anthropic、google、deepgram 等全部声明为工作区成员新插件放进livekit-plugins/后即可在本地工作区内被直接解析。开发环境准备仓库统一使用uv作为包管理器所有命令从仓库根目录执行。makefile 提供了完整的本地开发目标make install # 安装全部依赖等价于 uv sync --all-extras --dev如果还需要与本地 python-rtc 或本地 Rust SDK 联动SDK 开发者场景makefile 还提供了make link-rtc下载 FFI 产物并链接本地 python-rtc、make link-rtc-local从源码构建 Rust SDK需要 cargo、make unlink-rtc恢复 PyPI 版本、make status查看当前链接状态与make doctor诊断开发环境健康状况等目标详见 AGENTS.md 的 Linking Local python-rtc 一节。开发流以 examples/ 目录为开发循环CONTRIBUTING.md 的 Development flow 一节给出了一条非常实用的建议先浏览examples/目录了解框架的全部功能与用法然后把examples/dev/作为你自己专属的开发循环目录该目录用于存放贡献者自建的实验性示例当前仓库快照中未包含它可按需创建。examples/目录本身就是最好的功能目录按业务场景组织包括examples/avatar带推理 Agent 与人格系统的头像示例examples/drive_thru含数据库与订单模型的免下车点餐 Agent附 Dockerfile 与测试examples/frontdesk前台/日历 API 场景含 simulation.py 与场景定义 scenarios.yamlexamples/hotel_receptionist最复杂的酒店前台示例配有 18 份策略文档policies/*.md、多文件工具实现与 benchmark.pyexamples/voice_agents基础 Agent、MCP 集成、LlamaIndex RAG、OpenTelemetry 追踪等语音 Agent 变体examples/primitives 与 examples/otherecho agent、房间统计、转写/翻译等原始能力演示。每个示例都有独立的 README.md 说明总索引位于 examples/README.md并附带可复制的 Dockerfile-example。研究这些示例的代码组织方式是理解框架 API 最快的途径也是提交插件或功能前的事实参照。类型检查、Linting 与格式化make check / make fixCONTRIBUTING.md 指出CI 会验证代码质量本地可以用以下命令先自查——类型检查与 Lintingmake check从 makefile 看check目标实际串联了三项检查format-check、lint、type-check子目标实际命令作用format-checkuv run ruff format --check .只检查不修改发现格式问题即退出码 1lintuv run ruff check .运行 ruff linter失败时提示运行make fixtype-checkuv run python scripts/check_types.py运行 mypy 严格类型检查格式化与自动修复make fixfix目标等价于formatlint-fix即uv run ruff format .与uv run ruff check --fix .的组合对应 CONTRIBUTING.md 中要求的 Runruff check --fixandruff formatbefore committing。ruff 规则集具体校验什么根 pyproject.toml 中的[tool.ruff]配置定义了仓库的代码风格基线贡献者可以据此预判 CI 会拒绝什么line-length 100、target-version py310要求 Python 3.10 兼容lint 规则选择了E/Wpycodestyle、Fpyflakes、Iisort 导入排序、Bflake8-bugbear、C4flake8-comprehensions、UPpyupgrade以及RUF006asyncio 悬空任务警告并忽略E501isort 配置了combine-as-imports true与known-first-party [livekit]保证livekit相关导入被识别为第一方包pydocstyle 约定为google风格 docstring——这与 CONTRIBUTING.md 新方法/枚举/类必须写文档 的要求一脉相承。mypy 严格检查的实现细节type-check背后的 scripts/check_types.py 是一段值得细读的实现它自动发现livekit-plugins/下所有livekit-plugins-*包并逐一传给 mypy-p livekit.agents -p livekit.plugins.name ...仅排除browser、nvidia、rtzr三个插件EXCLUDED_PLUGINSmypy 以strict true模式运行配置见 根 pyproject.toml 的[tool.mypy]并启用pydantic.mypy插件类型桩stubs不用mypy --install-types动态安装而是声明并锁定在typing依赖组中如types-aiofiles、types-cffi等当 mypy 发现缺失的桩时会把完整清单写入.mypy_cache/missing_stubs脚本据此直接打印出应执行的uv add --group typing stubs命令保证每次运行都是确定性的单遍检查见 check_types.py 头部注释检查强制--platform linux无论宿主机是 macOS 还是 Windows都与 CI 门禁保持一致的分析平台避免 Windows 上解析termios等平台分支产生的差异错误。pdoc3 API 文档要求CONTRIBUTING.md 还要求新增方法/枚举/类必须写文档因为项目使用pdoc3自动生成 API 文档。从依赖声明看pdoc3、setuptools、beautifulsoup4、markdownify都在 根 pyproject.toml 的docs依赖组中文档构建工具链位于.github/下如 convert_html_docs.py并有专门的docs测试类别覆盖。因此新 API 不写 docstring不仅是风格问题更是会被 CI 拦截的合规问题。测试类别标记与 CI 单元门禁贡献修复或功能后需要跑测试验证。AGENTS.md 说明了本仓库的测试体系每个测试模块必须声明恰好一个类别标记module-levelpytestmark类别选择发生在导入之前因此按类别运行不会误导入其他模块标记选择标志含义pytest.mark.unit--unit快速、无外部依赖无需任何 Provider 凭据或网络pytest.mark.audio_eot--audio_eot无外部依赖的音频端点检测/轮次检测套件pytest.mark.plugin(name)--plugin [name]特定 Provider 集成测试需要该 Provider 的依赖/密钥pytest.mark.stt--stt跨 Provider 语音识别套件tests/test_stt.pypytest.mark.tts--tts跨 Provider 语音合成套件tests/test_tts.pypytest.mark.realtime(name)--realtime [name]实时模型测试pytest.mark.evals--evals针对 LiveKit 推理网关的行为评估pytest.mark.docs--docs.github/下文档构建工具测试常用命令uv run pytest --unit # 全部单元级测试 uv run pytest tests/test_tools.py # 单个测试文件 make unit-tests # CI 单元门禁unit audio_eot无需云账号 uv run pytest --list-categories # 按类别列出所有测试模块make unit-tests即uv run pytest --unit --audio_eot见 makefile与 CI 的无云账号门禁一致——贡献者应把这条作为本地必过线。若新测试模块缺少类别标记收集阶段会直接失败并给出提示可用--allow-uncategorized临时绕过CI 默认开启该规则。Pull Request 合入检查清单综合 CONTRIBUTING.md 与仓库配置一个可被批准的 PR 应满足提交前运行过ruff check --fix与ruff format本地等价于make fixCI 侧为make check所有新增方法/枚举/类带有 Google 风格 docstring能通过 pdoc3 文档生成与 mypy strict 检查相关测试通过且带有正确的类别标记无外部依赖的改动至少通过make unit-tests首次 PR 已完成 CLA Assistant 的协议签署不手工改动CHANGELOG.md与包清单——版本说明与清单由机器人与 Maintainer 处理版本号策略见 AGENTS.md默认 patch 级升级。常用命令速查命令作用依据make install安装全部开发依赖uv sync --all-extras --devmakefilemake check格式化检查 lint mypy 严格类型检查makefilemake fixruff 格式化 lint 自动修复makefilemake unit-tests运行无云账号依赖的 unit audio_eot 测试makefilemake doctor诊断 uv/python/cargo/git 与仓库结构健康状况makefilemake link-rtc/unlink-rtc/status本地 python-rtc 联动、还原 PyPI 版本、查看状态makefileuv run pytest --list-categories按类别列出全部测试模块AGENTS.md以上流程与命令均基于当前仓库快照CONTRIBUTING.md 定义贡献流程makefile、scripts/check_types.py 与 pyproject.toml 提供可本地复现的实现细节AGENTS.md 补充了测试类别与代码风格100 字符行宽、Python 3.10、Google 风格 docstring、mypy strict。按这套清单执行你的贡献就能与 CI 门禁对齐。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LiveKit Agents 开源贡献指南：从编写 Provider 插件到通过 CI 代码质量门禁
LiveKit Agents 开源贡献指南从编写 Provider 插件到通过 CI 代码质量门禁【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents本文以仓库内的 CONTRIBUTING.md 为主体完整梳理 LiveKit Agents 框架的开源贡献路径如何为一个 TTS/STT/LLM Provider 编写插件、如何修复缺陷与新增功能、如何在本地复现 CI 的代码质量检查ruff 格式化与 lint、mypy 严格类型检查、pdoc3 API 文档以及 Pull Request 的合入流程CLA 签署、CHANGELOG 自动化。读完后你可以独立完成一个符合该仓库工程规范的插件或缺陷修复并让改动顺利通过 CI 门禁。贡献总览与社区规范CONTRIBUTING.md 开宗明义LiveKit Agents 是开源项目欢迎所有本着诚意与社区协作的贡献者没有任何贡献太小。项目贡献遵循以下社区约定行为准则所有贡献者必须遵守项目的 行为准则。CLA 签署你的第一个 Pull Request 会触发 CLA Assistant 机器人提供本项目贡献者许可协议Contributor License Agreement的签署链接这是代码进入仓库的前提。社区互助即使不写代码也可以帮助社区成员解答框架使用问题——加入官方 Slack 的#agents频道即可参与。自动化维护不需要手工维护CHANGELOG.md或包清单文件这些由机器人和 Maintainer 在合并前处理贡献者只需关注代码本身。三种代码贡献路径文档明确给出三条贡献代码的途径各适合不同能力的贡献者编写插件Write a plugin如果你在用的 TTS/STT/LLM Provider 还不在插件列表中可以直接为其编写插件文档建议参考同类型插件的源码来理解构建方式。修复缺陷Fix bugs项目致力于保持框架尽可能可靠欢迎任何人帮助消除缺陷、提升稳定性具体流程遵循文档中的 Pull Request 指南。新增功能Add new features框架接受新功能但文档要求先开 Issue 讨论可行性与范围再动手实现避免无效工作。编写 Provider 插件从模板到注册文档建议参考相似插件的源码仓库里恰好内置了一个最小化模板livekit-plugins-minimal其 README 与 pyproject.toml 定义了完整的最小插件骨架。一个最小插件的结构如下# livekit-plugins/livekit-plugins-minimal/livekit/plugins/minimal/__init__.py from livekit.agents import Plugin from .log import logger from .version import __version__ class MinimalPlugin(Plugin): def __init__(self) - None: super().__init__(__name__, __version__, __package__, logger) Plugin.register_plugin(MinimalPlugin())从源码结构看这套注册机制的核心是框架的Plugin基类plugin.py构造函数要求传入title、version、package及一个 loggerregister_plugin()是一个类方法要求必须在主线程调用否则抛出RuntimeError并将实例追加到registered_plugins列表、发出plugin_registered事件供框架后续发现插件插件还可以可选地实现download_files()方法用于在启动时下载模型等文件。在 livekit-plugins-minimal/pyproject.toml 中可以看到一个插件包的完整工程约定requires-python 3.10.0、依赖livekit-agents1.8.0、版本从livekit/plugins/minimal/version.py动态读取当前为1.8.0、打包目标包含livekit目录。值得注意的是本仓库采用uv workspace组织所有插件根 pyproject.toml 的[tool.uv.workspace]成员列表与[tool.uv.sources]把livekit-plugins/*下 50 插件openai、anthropic、google、deepgram 等全部声明为工作区成员新插件放进livekit-plugins/后即可在本地工作区内被直接解析。开发环境准备仓库统一使用uv作为包管理器所有命令从仓库根目录执行。makefile 提供了完整的本地开发目标make install # 安装全部依赖等价于 uv sync --all-extras --dev如果还需要与本地 python-rtc 或本地 Rust SDK 联动SDK 开发者场景makefile 还提供了make link-rtc下载 FFI 产物并链接本地 python-rtc、make link-rtc-local从源码构建 Rust SDK需要 cargo、make unlink-rtc恢复 PyPI 版本、make status查看当前链接状态与make doctor诊断开发环境健康状况等目标详见 AGENTS.md 的 Linking Local python-rtc 一节。开发流以 examples/ 目录为开发循环CONTRIBUTING.md 的 Development flow 一节给出了一条非常实用的建议先浏览examples/目录了解框架的全部功能与用法然后把examples/dev/作为你自己专属的开发循环目录该目录用于存放贡献者自建的实验性示例当前仓库快照中未包含它可按需创建。examples/目录本身就是最好的功能目录按业务场景组织包括examples/avatar带推理 Agent 与人格系统的头像示例examples/drive_thru含数据库与订单模型的免下车点餐 Agent附 Dockerfile 与测试examples/frontdesk前台/日历 API 场景含 simulation.py 与场景定义 scenarios.yamlexamples/hotel_receptionist最复杂的酒店前台示例配有 18 份策略文档policies/*.md、多文件工具实现与 benchmark.pyexamples/voice_agents基础 Agent、MCP 集成、LlamaIndex RAG、OpenTelemetry 追踪等语音 Agent 变体examples/primitives 与 examples/otherecho agent、房间统计、转写/翻译等原始能力演示。每个示例都有独立的 README.md 说明总索引位于 examples/README.md并附带可复制的 Dockerfile-example。研究这些示例的代码组织方式是理解框架 API 最快的途径也是提交插件或功能前的事实参照。类型检查、Linting 与格式化make check / make fixCONTRIBUTING.md 指出CI 会验证代码质量本地可以用以下命令先自查——类型检查与 Lintingmake check从 makefile 看check目标实际串联了三项检查format-check、lint、type-check子目标实际命令作用format-checkuv run ruff format --check .只检查不修改发现格式问题即退出码 1lintuv run ruff check .运行 ruff linter失败时提示运行make fixtype-checkuv run python scripts/check_types.py运行 mypy 严格类型检查格式化与自动修复make fixfix目标等价于formatlint-fix即uv run ruff format .与uv run ruff check --fix .的组合对应 CONTRIBUTING.md 中要求的 Runruff check --fixandruff formatbefore committing。ruff 规则集具体校验什么根 pyproject.toml 中的[tool.ruff]配置定义了仓库的代码风格基线贡献者可以据此预判 CI 会拒绝什么line-length 100、target-version py310要求 Python 3.10 兼容lint 规则选择了E/Wpycodestyle、Fpyflakes、Iisort 导入排序、Bflake8-bugbear、C4flake8-comprehensions、UPpyupgrade以及RUF006asyncio 悬空任务警告并忽略E501isort 配置了combine-as-imports true与known-first-party [livekit]保证livekit相关导入被识别为第一方包pydocstyle 约定为google风格 docstring——这与 CONTRIBUTING.md 新方法/枚举/类必须写文档 的要求一脉相承。mypy 严格检查的实现细节type-check背后的 scripts/check_types.py 是一段值得细读的实现它自动发现livekit-plugins/下所有livekit-plugins-*包并逐一传给 mypy-p livekit.agents -p livekit.plugins.name ...仅排除browser、nvidia、rtzr三个插件EXCLUDED_PLUGINSmypy 以strict true模式运行配置见 根 pyproject.toml 的[tool.mypy]并启用pydantic.mypy插件类型桩stubs不用mypy --install-types动态安装而是声明并锁定在typing依赖组中如types-aiofiles、types-cffi等当 mypy 发现缺失的桩时会把完整清单写入.mypy_cache/missing_stubs脚本据此直接打印出应执行的uv add --group typing stubs命令保证每次运行都是确定性的单遍检查见 check_types.py 头部注释检查强制--platform linux无论宿主机是 macOS 还是 Windows都与 CI 门禁保持一致的分析平台避免 Windows 上解析termios等平台分支产生的差异错误。pdoc3 API 文档要求CONTRIBUTING.md 还要求新增方法/枚举/类必须写文档因为项目使用pdoc3自动生成 API 文档。从依赖声明看pdoc3、setuptools、beautifulsoup4、markdownify都在 根 pyproject.toml 的docs依赖组中文档构建工具链位于.github/下如 convert_html_docs.py并有专门的docs测试类别覆盖。因此新 API 不写 docstring不仅是风格问题更是会被 CI 拦截的合规问题。测试类别标记与 CI 单元门禁贡献修复或功能后需要跑测试验证。AGENTS.md 说明了本仓库的测试体系每个测试模块必须声明恰好一个类别标记module-levelpytestmark类别选择发生在导入之前因此按类别运行不会误导入其他模块标记选择标志含义pytest.mark.unit--unit快速、无外部依赖无需任何 Provider 凭据或网络pytest.mark.audio_eot--audio_eot无外部依赖的音频端点检测/轮次检测套件pytest.mark.plugin(name)--plugin [name]特定 Provider 集成测试需要该 Provider 的依赖/密钥pytest.mark.stt--stt跨 Provider 语音识别套件tests/test_stt.pypytest.mark.tts--tts跨 Provider 语音合成套件tests/test_tts.pypytest.mark.realtime(name)--realtime [name]实时模型测试pytest.mark.evals--evals针对 LiveKit 推理网关的行为评估pytest.mark.docs--docs.github/下文档构建工具测试常用命令uv run pytest --unit # 全部单元级测试 uv run pytest tests/test_tools.py # 单个测试文件 make unit-tests # CI 单元门禁unit audio_eot无需云账号 uv run pytest --list-categories # 按类别列出所有测试模块make unit-tests即uv run pytest --unit --audio_eot见 makefile与 CI 的无云账号门禁一致——贡献者应把这条作为本地必过线。若新测试模块缺少类别标记收集阶段会直接失败并给出提示可用--allow-uncategorized临时绕过CI 默认开启该规则。Pull Request 合入检查清单综合 CONTRIBUTING.md 与仓库配置一个可被批准的 PR 应满足提交前运行过ruff check --fix与ruff format本地等价于make fixCI 侧为make check所有新增方法/枚举/类带有 Google 风格 docstring能通过 pdoc3 文档生成与 mypy strict 检查相关测试通过且带有正确的类别标记无外部依赖的改动至少通过make unit-tests首次 PR 已完成 CLA Assistant 的协议签署不手工改动CHANGELOG.md与包清单——版本说明与清单由机器人与 Maintainer 处理版本号策略见 AGENTS.md默认 patch 级升级。常用命令速查命令作用依据make install安装全部开发依赖uv sync --all-extras --devmakefilemake check格式化检查 lint mypy 严格类型检查makefilemake fixruff 格式化 lint 自动修复makefilemake unit-tests运行无云账号依赖的 unit audio_eot 测试makefilemake doctor诊断 uv/python/cargo/git 与仓库结构健康状况makefilemake link-rtc/unlink-rtc/status本地 python-rtc 联动、还原 PyPI 版本、查看状态makefileuv run pytest --list-categories按类别列出全部测试模块AGENTS.md以上流程与命令均基于当前仓库快照CONTRIBUTING.md 定义贡献流程makefile、scripts/check_types.py 与 pyproject.toml 提供可本地复现的实现细节AGENTS.md 补充了测试类别与代码风格100 字符行宽、Python 3.10、Google 风格 docstring、mypy strict。按这套清单执行你的贡献就能与 CI 门禁对齐。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考