Upsonicgpt-computer-assistant贡献指南从本地开发环境搭建到扩展 VectorDB、模型、存储与工具 Provider【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant本文基于仓库根目录的 CONTRIBUTING.md 整理并深化面向希望参与 Upsonic 开发的贡献者你将学会如何用uv搭建可编辑开发环境、按规范运行单元测试与依赖 Docker 的冒烟测试并掌握四条官方扩展路径——新增 VectorDB Provider、模型 Provider、存储 Provider 与工具——每一步都给出了源码级参考实现位置帮助你写出符合项目标准的可合并代码。开发环境搭建Development SetupCONTRIBUTING.md 给出的官方环境搭建流程如下共四步克隆仓库如尚未安装uv先安装pip install uv创建并激活虚拟环境uv venv source .venv/bin/activate # Unix # 或 .venv\Scripts\activate # Windows以可编辑模式安装开发依赖uv pip install -e .[dev]如果针对某个具体功能做开发可按需安装对应的可选依赖组uv pip install -e .[vectordb,storage,models,embeddings,tools]结合 pyproject.toml 可以进一步理解这套流程背后的设计项目要求 Python3.10requires-python 3.10当前声明版本为0.77.3dev依赖组[dependency-groups]包含mypy、pre-commit、pytest、pytest-asyncio、pytest-timeout、tomlkit与uv等工具链这正是第 4 步.[dev]安装的实质内容可选依赖组粒度很细除文档中提到的vectordb、storage、models、embeddings、tools聚合组外还有sqlite-storage、redis-storage、postgres-storage、mongo-storage、mem0-storage等单存储组以及chroma、qdrant、milvus、weaviate、pinecone、faiss、pgvector、supermemory等单向量库组。storage与vectordb这样的聚合组实际上是对单库组的再引用例如storage [upsonic[sqlite-storage], upsonic[redis-storage], ...]。因此贡献者可以只安装自己正在开发的那一个后端的最小依赖集合而不必拉下全部重型依赖如torch、transformers构建系统为hatchling包路径为src/upsonic[tool.hatch.build.targets.wheel]因此所有扩展代码都应放在src/upsonic/之下项目还声明了[tool.uv]配置default-groups [dev]且要求uv 0.10.0uv sync会默认带上 dev 组。运行测试单元测试uv run --all-extras pytest tests/unit_tests -v--all-extras会一次性安装所有可选依赖组保证tests/unit_tests下涉及多后端的测试都能导入。pytest.ini 配置了asyncio_mode strict需要显式标记的异步测试、testpaths tests与test_*.py的收集规则并注册了integration标记可用-m not integration排除。冒烟测试需要 Dockermake smoke_tests查看 Makefile 可以看到该目标的完整依赖链smoke_tests: deps_smoke docker_up。deps_smoke执行uv sync --extra storage --extra faiss为存储与向量库测试同步可选依赖docker_up先cd tests/smoke_tests后启动docker-compose up -d再轮询最多约 60 秒等待服务变为Up状态随后运行uv run pytest tests/smoke_tests -v并显式忽略两个 HITL 长流程用例test_comprehensive_hitl.py与usage_durable_execution.py。CONTRIBUTING.md 说明该流程会自动拉起所需的 Redis、PostgreSQL、MongoDB 等服务对应 tests/smoke_tests/docker-compose.yml。Makefile 还提供了配套目标make docker_up仅启动服务、make docker_down停止服务、make docker_restart重启、make test_storage_only只跑tests/smoke_tests/memory的存储测试。运行指定测试uv run --all-extras pytest tests/unit_tests/tools/test_common_tools_duckduckgo.py -v uv run --all-extras pytest tests/smoke_tests/memory -v仓库中确有对应文件tests/unit_tests/tools/test_common_tools_duckduckgo.py 与tests/smoke_tests/memory/目录包含test_sqlite_storage_comprehensive.py、test_redis_storage_comprehensive.py等按后端命名的综合测试。代码标准Code StandardsCONTRIBUTING.md 列出了三条强制性的代码规范它们都直接映射到仓库中可见的既有实现。Sync/Async 双版本模式每个函数/方法必须同时提供同步与异步版本异步版本以a前缀命名def process(data: str) - Result: Synchronous version. ... async def aprocess(data: str) - Result: Asynchronous version - prefix with a. ...这一规范在核心基类中有典型落地。以 src/upsonic/vectordb/base.py 中的BaseVectorDBProvider为例从源码结构看它采用“async-first 同步包装”的设计抽象方法全部为异步aconnect、adisconnect、ais_ready等均以a前缀命名而同步版本connect、disconnect、is_ready在基类中统一通过_run_async_from_sync实现——该方法在已有事件循环运行时改用ThreadPoolExecutor在新线程中运行独立的持久事件循环否则直接run_until_complete。也就是说Provider 作者只需实现a前缀的异步方法同步入口由基类自动补齐这正是“每个函数都有 sync/async 两版”规范在框架层的实现方式。类型注解所有代码必须带完整的类型注解除非绝对必要否则不允许使用Anydef calculate_score( items: list[dict[str, float]], threshold: float 0.5 ) - tuple[float, list[str]]: ...pyproject.toml 的dev组包含mypy1.14.1从依赖配置可以推断 CI 或本地检查会将 mypy 作为类型正确性的强制工具。独立函数依赖显式注入函数必须自包含所有依赖通过参数传入不得依赖全局状态# ✅ 正确 def process_data(client: HttpClient, config: Config, data: str) - Result: ... # ❌ 错误 - 依赖外部状态 def process_data(data: str) - Result: client get_global_client() # 不要这样做 ...对照BaseVectorDBProvider.__init__的实现可以看到同样的风格构造函数显式接收configBaseVectorDBConfig或 dict在实例内部完成配置归一化与id/name派生而不是在模块级读取任何全局配置。扩展点Extension PointsCONTRIBUTING.md 定义了四类标准扩展点。以下逐条继承其步骤并补充仓库内可参照的具体文件。新增 VectorDB Provider在src/upsonic/vectordb/providers/下新建your_provider.py实现 src/upsonic/vectordb/base.py 中的VectorDBProvider接口基类为BaseVectorDBProvider在 pyproject.toml 中为客户端库新增一个可选依赖组[project.optional-dependencies] your-provider [ your-client-libx.x.x, ]更新vectordb聚合组将其纳入在tests/smoke_tests/vectordb/添加测试。参考实现src/upsonic/vectordb/providers/chroma.py。结合 src/upsonic/vectordb/init.py 可以确认现有 Provider 全集ChromaProvider、FaissProvider、PineconeProvider、QdrantProvider、MilvusProvider、WeaviateProvider、PgVectorProvider、SuperMemoryProvider。该文件还维护了一个惰性导入映射ChromaProvider: .providers.chroma等与_provider_cache——从源码结构看新增 Provider 后若要进入惰性加载路径通常也需要同步在此注册使对应客户端依赖未安装时不会触发 ImportError。tests/smoke_tests/vectordb/下每个后端都有一份test_*_provider.py如test_qdrant_provider.py、test_pgvector_provider.py且该目录含独立的 tests/smoke_tests/vectordb/docker-compose-pgvector.yml说明向量库冒烟测试可能还需要专属 compose 文件。新增模型 Provider在src/upsonic/models/下新建your_provider.py按既有 Provider 的模式实现所需接口在 src/upsonic/models/model_registry.py 中注册在 pyproject.toml 新增可选依赖组[project.optional-dependencies] your-provider [ your-client-libx.x.x, ]更新models聚合组在tests/unit_tests/或tests/smoke_tests/添加测试。参考实现src/upsonic/models/openai.py、src/upsonic/models/anthropic.py。从源码结构看model_registry.py并不只是简单的名字表它定义了ModelCapabilityreasoning、function_calling、structured_output 等能力枚举、ModelTierflagship/advanced/standard/fast/specialized与带基准分数字段的ModelMetadata并提供get_model_metadata、get_models_by_capability、get_top_models等查询函数smoke_tests中的 tests/smoke_tests/test_model_selection.py 则验证了基于该元数据的模型选择链路。因此新 Provider 注册后其模型的能力标签会直接参与框架的模型推荐逻辑。同时src/upsonic/models 目录下还配套有profiles/各厂商模型画像与providers/传输层 Provider模块贡献时应保持这三层结构的既有分工。新增存储 Provider在src/upsonic/storage/下新建目录目录结构约定为src/upsonic/storage/your_storage/ ├── __init__.py ├── your_storage.py # Sync 实现 ├── async_your_storage.py # Async 实现 ├── schemas.py └── utils.py实现 src/upsonic/storage/base.py 中的BaseStorage接口必须同时提供同步与异步两套实现在 pyproject.toml 新增可选依赖组[project.optional-dependencies] your-storage [ your-clientx.x.x, ]更新storage聚合组在tests/smoke_tests/memory/添加测试。参考实现src/upsonic/storage/postgres/、src/upsonic/storage/redis/均为已存在的完整目录。阅读 src/upsonic/storage/base.py 中的Storage抽象基类可以明确接口面构造函数接收五类表名session_table、user_memory_table、cultural_knowledge_table、knowledge_table、usage_entry_table默认值分别为upsonic_sessions、upsonic_user_memories、upsonic_cultural_knowledge、upsonic_knowledge、upsonic_usage_entries抽象方法覆盖table_exists、upsert_session(s)、get_session(s)等会话与记忆的读写操作并预留了close()钩子供子类释放连接池。tests/smoke_tests/memory/下的测试按后端一一对应test_sqlite_storage_comprehensive.py、test_mongo_storage_comprehensive.py等新增后端时按同一命名模式补齐测试即可与 Makefile 的test_storage_only目标无缝衔接。新增工具Tool通用工具放入src/upsonic/tools/common_tools/your_tool.py自定义/集成类工具放入src/upsonic/tools/custom_tools/your_tool.py遵循 src/upsonic/tools/base.py 的基础工具模式在对应的__init__.py中导出在tests/unit_tests/tools/添加测试更新tools依赖组。参考实现src/upsonic/tools/common_tools/duckduckgo.py。仓库现状与文档完全一致common_tools/下现有bochasearch.py、duckduckgo.py、financial_tools.py、tavily.pycustom_tools/下现有apify.py、daytona.py、e2b.py、firecrawl.py、exa.py、gmail.py、mail.py、slack.py、telegram.py、discord.py、whatsapp.py等集成工具。测试侧同样对齐tests/unit_tests/tools/提供test_common_tools_duckduckgo.py、test_common_tools_financial.py等工具单测tests/smoke_tests/tools/则有test_apify_tool.py、test_e2b_tool.py等外部集成冒烟测试通常需要对应 API 密钥。Pull Request 提交准则CONTRIBUTING.md 要求每条 PR 满足五点保持聚焦一个 PR 只包含一个功能或一个修复包含测试所有新代码必须有测试覆盖遵循类型规范提供正确的类型注解同步/异步成对任何新函数都要实现两个版本本地先跑通提交前确保本地测试全部通过。结合前文的 Makefile 与 pytest 配置提交前的最低验证组合通常是uv run --all-extras pytest tests/unit_tests -v跑单测涉及存储/向量库后端时再执行make smoke_tests完成带 Docker 的冒烟验证。License项目采用 MIT 许可证见 LICENCE。小结CONTRIBUTING.md 把贡献路径收敛为四条主线uv.[dev]的可编辑环境、--all-extras单测与make smoke_tests冒烟测试的测试双轨制、sync/async 成对与全类型注解的代码规范以及 VectorDB、模型、存储、工具四类 Provider 扩展点。每条扩展点都指定了基类位置src/upsonic/vectordb/base.py、src/upsonic/storage/base.py、src/upsonic/models/model_registry.py、src/upsonic/tools/base.py、pyproject.toml依赖组约定与参考实现文件贡献者只需沿既有模式复制结构、补齐测试即可产出与项目风格一致的扩展。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Upsonic（gpt-computer-assistant）贡献指南：从本地开发环境搭建到扩展 VectorDB、模型、存储与工具 Provider
Upsonicgpt-computer-assistant贡献指南从本地开发环境搭建到扩展 VectorDB、模型、存储与工具 Provider【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant本文基于仓库根目录的 CONTRIBUTING.md 整理并深化面向希望参与 Upsonic 开发的贡献者你将学会如何用uv搭建可编辑开发环境、按规范运行单元测试与依赖 Docker 的冒烟测试并掌握四条官方扩展路径——新增 VectorDB Provider、模型 Provider、存储 Provider 与工具——每一步都给出了源码级参考实现位置帮助你写出符合项目标准的可合并代码。开发环境搭建Development SetupCONTRIBUTING.md 给出的官方环境搭建流程如下共四步克隆仓库如尚未安装uv先安装pip install uv创建并激活虚拟环境uv venv source .venv/bin/activate # Unix # 或 .venv\Scripts\activate # Windows以可编辑模式安装开发依赖uv pip install -e .[dev]如果针对某个具体功能做开发可按需安装对应的可选依赖组uv pip install -e .[vectordb,storage,models,embeddings,tools]结合 pyproject.toml 可以进一步理解这套流程背后的设计项目要求 Python3.10requires-python 3.10当前声明版本为0.77.3dev依赖组[dependency-groups]包含mypy、pre-commit、pytest、pytest-asyncio、pytest-timeout、tomlkit与uv等工具链这正是第 4 步.[dev]安装的实质内容可选依赖组粒度很细除文档中提到的vectordb、storage、models、embeddings、tools聚合组外还有sqlite-storage、redis-storage、postgres-storage、mongo-storage、mem0-storage等单存储组以及chroma、qdrant、milvus、weaviate、pinecone、faiss、pgvector、supermemory等单向量库组。storage与vectordb这样的聚合组实际上是对单库组的再引用例如storage [upsonic[sqlite-storage], upsonic[redis-storage], ...]。因此贡献者可以只安装自己正在开发的那一个后端的最小依赖集合而不必拉下全部重型依赖如torch、transformers构建系统为hatchling包路径为src/upsonic[tool.hatch.build.targets.wheel]因此所有扩展代码都应放在src/upsonic/之下项目还声明了[tool.uv]配置default-groups [dev]且要求uv 0.10.0uv sync会默认带上 dev 组。运行测试单元测试uv run --all-extras pytest tests/unit_tests -v--all-extras会一次性安装所有可选依赖组保证tests/unit_tests下涉及多后端的测试都能导入。pytest.ini 配置了asyncio_mode strict需要显式标记的异步测试、testpaths tests与test_*.py的收集规则并注册了integration标记可用-m not integration排除。冒烟测试需要 Dockermake smoke_tests查看 Makefile 可以看到该目标的完整依赖链smoke_tests: deps_smoke docker_up。deps_smoke执行uv sync --extra storage --extra faiss为存储与向量库测试同步可选依赖docker_up先cd tests/smoke_tests后启动docker-compose up -d再轮询最多约 60 秒等待服务变为Up状态随后运行uv run pytest tests/smoke_tests -v并显式忽略两个 HITL 长流程用例test_comprehensive_hitl.py与usage_durable_execution.py。CONTRIBUTING.md 说明该流程会自动拉起所需的 Redis、PostgreSQL、MongoDB 等服务对应 tests/smoke_tests/docker-compose.yml。Makefile 还提供了配套目标make docker_up仅启动服务、make docker_down停止服务、make docker_restart重启、make test_storage_only只跑tests/smoke_tests/memory的存储测试。运行指定测试uv run --all-extras pytest tests/unit_tests/tools/test_common_tools_duckduckgo.py -v uv run --all-extras pytest tests/smoke_tests/memory -v仓库中确有对应文件tests/unit_tests/tools/test_common_tools_duckduckgo.py 与tests/smoke_tests/memory/目录包含test_sqlite_storage_comprehensive.py、test_redis_storage_comprehensive.py等按后端命名的综合测试。代码标准Code StandardsCONTRIBUTING.md 列出了三条强制性的代码规范它们都直接映射到仓库中可见的既有实现。Sync/Async 双版本模式每个函数/方法必须同时提供同步与异步版本异步版本以a前缀命名def process(data: str) - Result: Synchronous version. ... async def aprocess(data: str) - Result: Asynchronous version - prefix with a. ...这一规范在核心基类中有典型落地。以 src/upsonic/vectordb/base.py 中的BaseVectorDBProvider为例从源码结构看它采用“async-first 同步包装”的设计抽象方法全部为异步aconnect、adisconnect、ais_ready等均以a前缀命名而同步版本connect、disconnect、is_ready在基类中统一通过_run_async_from_sync实现——该方法在已有事件循环运行时改用ThreadPoolExecutor在新线程中运行独立的持久事件循环否则直接run_until_complete。也就是说Provider 作者只需实现a前缀的异步方法同步入口由基类自动补齐这正是“每个函数都有 sync/async 两版”规范在框架层的实现方式。类型注解所有代码必须带完整的类型注解除非绝对必要否则不允许使用Anydef calculate_score( items: list[dict[str, float]], threshold: float 0.5 ) - tuple[float, list[str]]: ...pyproject.toml 的dev组包含mypy1.14.1从依赖配置可以推断 CI 或本地检查会将 mypy 作为类型正确性的强制工具。独立函数依赖显式注入函数必须自包含所有依赖通过参数传入不得依赖全局状态# ✅ 正确 def process_data(client: HttpClient, config: Config, data: str) - Result: ... # ❌ 错误 - 依赖外部状态 def process_data(data: str) - Result: client get_global_client() # 不要这样做 ...对照BaseVectorDBProvider.__init__的实现可以看到同样的风格构造函数显式接收configBaseVectorDBConfig或 dict在实例内部完成配置归一化与id/name派生而不是在模块级读取任何全局配置。扩展点Extension PointsCONTRIBUTING.md 定义了四类标准扩展点。以下逐条继承其步骤并补充仓库内可参照的具体文件。新增 VectorDB Provider在src/upsonic/vectordb/providers/下新建your_provider.py实现 src/upsonic/vectordb/base.py 中的VectorDBProvider接口基类为BaseVectorDBProvider在 pyproject.toml 中为客户端库新增一个可选依赖组[project.optional-dependencies] your-provider [ your-client-libx.x.x, ]更新vectordb聚合组将其纳入在tests/smoke_tests/vectordb/添加测试。参考实现src/upsonic/vectordb/providers/chroma.py。结合 src/upsonic/vectordb/init.py 可以确认现有 Provider 全集ChromaProvider、FaissProvider、PineconeProvider、QdrantProvider、MilvusProvider、WeaviateProvider、PgVectorProvider、SuperMemoryProvider。该文件还维护了一个惰性导入映射ChromaProvider: .providers.chroma等与_provider_cache——从源码结构看新增 Provider 后若要进入惰性加载路径通常也需要同步在此注册使对应客户端依赖未安装时不会触发 ImportError。tests/smoke_tests/vectordb/下每个后端都有一份test_*_provider.py如test_qdrant_provider.py、test_pgvector_provider.py且该目录含独立的 tests/smoke_tests/vectordb/docker-compose-pgvector.yml说明向量库冒烟测试可能还需要专属 compose 文件。新增模型 Provider在src/upsonic/models/下新建your_provider.py按既有 Provider 的模式实现所需接口在 src/upsonic/models/model_registry.py 中注册在 pyproject.toml 新增可选依赖组[project.optional-dependencies] your-provider [ your-client-libx.x.x, ]更新models聚合组在tests/unit_tests/或tests/smoke_tests/添加测试。参考实现src/upsonic/models/openai.py、src/upsonic/models/anthropic.py。从源码结构看model_registry.py并不只是简单的名字表它定义了ModelCapabilityreasoning、function_calling、structured_output 等能力枚举、ModelTierflagship/advanced/standard/fast/specialized与带基准分数字段的ModelMetadata并提供get_model_metadata、get_models_by_capability、get_top_models等查询函数smoke_tests中的 tests/smoke_tests/test_model_selection.py 则验证了基于该元数据的模型选择链路。因此新 Provider 注册后其模型的能力标签会直接参与框架的模型推荐逻辑。同时src/upsonic/models 目录下还配套有profiles/各厂商模型画像与providers/传输层 Provider模块贡献时应保持这三层结构的既有分工。新增存储 Provider在src/upsonic/storage/下新建目录目录结构约定为src/upsonic/storage/your_storage/ ├── __init__.py ├── your_storage.py # Sync 实现 ├── async_your_storage.py # Async 实现 ├── schemas.py └── utils.py实现 src/upsonic/storage/base.py 中的BaseStorage接口必须同时提供同步与异步两套实现在 pyproject.toml 新增可选依赖组[project.optional-dependencies] your-storage [ your-clientx.x.x, ]更新storage聚合组在tests/smoke_tests/memory/添加测试。参考实现src/upsonic/storage/postgres/、src/upsonic/storage/redis/均为已存在的完整目录。阅读 src/upsonic/storage/base.py 中的Storage抽象基类可以明确接口面构造函数接收五类表名session_table、user_memory_table、cultural_knowledge_table、knowledge_table、usage_entry_table默认值分别为upsonic_sessions、upsonic_user_memories、upsonic_cultural_knowledge、upsonic_knowledge、upsonic_usage_entries抽象方法覆盖table_exists、upsert_session(s)、get_session(s)等会话与记忆的读写操作并预留了close()钩子供子类释放连接池。tests/smoke_tests/memory/下的测试按后端一一对应test_sqlite_storage_comprehensive.py、test_mongo_storage_comprehensive.py等新增后端时按同一命名模式补齐测试即可与 Makefile 的test_storage_only目标无缝衔接。新增工具Tool通用工具放入src/upsonic/tools/common_tools/your_tool.py自定义/集成类工具放入src/upsonic/tools/custom_tools/your_tool.py遵循 src/upsonic/tools/base.py 的基础工具模式在对应的__init__.py中导出在tests/unit_tests/tools/添加测试更新tools依赖组。参考实现src/upsonic/tools/common_tools/duckduckgo.py。仓库现状与文档完全一致common_tools/下现有bochasearch.py、duckduckgo.py、financial_tools.py、tavily.pycustom_tools/下现有apify.py、daytona.py、e2b.py、firecrawl.py、exa.py、gmail.py、mail.py、slack.py、telegram.py、discord.py、whatsapp.py等集成工具。测试侧同样对齐tests/unit_tests/tools/提供test_common_tools_duckduckgo.py、test_common_tools_financial.py等工具单测tests/smoke_tests/tools/则有test_apify_tool.py、test_e2b_tool.py等外部集成冒烟测试通常需要对应 API 密钥。Pull Request 提交准则CONTRIBUTING.md 要求每条 PR 满足五点保持聚焦一个 PR 只包含一个功能或一个修复包含测试所有新代码必须有测试覆盖遵循类型规范提供正确的类型注解同步/异步成对任何新函数都要实现两个版本本地先跑通提交前确保本地测试全部通过。结合前文的 Makefile 与 pytest 配置提交前的最低验证组合通常是uv run --all-extras pytest tests/unit_tests -v跑单测涉及存储/向量库后端时再执行make smoke_tests完成带 Docker 的冒烟验证。License项目采用 MIT 许可证见 LICENCE。小结CONTRIBUTING.md 把贡献路径收敛为四条主线uv.[dev]的可编辑环境、--all-extras单测与make smoke_tests冒烟测试的测试双轨制、sync/async 成对与全类型注解的代码规范以及 VectorDB、模型、存储、工具四类 Provider 扩展点。每条扩展点都指定了基类位置src/upsonic/vectordb/base.py、src/upsonic/storage/base.py、src/upsonic/models/model_registry.py、src/upsonic/tools/base.py、pyproject.toml依赖组约定与参考实现文件贡献者只需沿既有模式复制结构、补齐测试即可产出与项目风格一致的扩展。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考