Azure Cosmos DB Python 服务构建助手
帮助 Python 团队构建安全、可测试且适用于 FastAPI 的 Cosmos DB NoSQL 服务。
证据显示优先使用 DefaultAzureCredential、生产环境避免密钥、模拟器密钥限定本地用途，并要求参数化查询；但删除操作没有用户确认、回滚或恢复方案，分区键授权仅作为原则提出而未实现，客户端生命周期示例存在未关闭问题，错误日志可能暴露端点和内部信息，因此扣分。
证据提供客户端、服务层、错误处理、重试和测试模板，主流程具有可理解性；但静态材料显示同步 Cosmos 客户端、线程池包装和异步上下文管理之间存在不一致，示例含多个 TODO、未固定依赖版本，失败状态有时以 None、空列表或 False 静默表示，且未提供可执行结果，因此受静态上限约束并扣分。
目标用户、Cosmos DB Python/FastAPI 场景和主要触发词较明确，覆盖认证、CRUD、分区键与测试；但触发词如 NoSQL database 和 add persistence 过宽，FastAPI 及特定项目模型假设明显，非适用边界、中文支持和中国大陆网络可达性未说明，因此扣分。
证据包含安装、环境变量、分层文档、参考文件、模板、MIT 许可证、作者和 1.0.0 版本元数据，信息架构较完整；但未提供兼容性矩阵、依赖锁定、变更日志、明确维护责任或更新路径，仓库 README 还声明整体处于持续开发阶段，因此扣分。
模板覆盖客户端初始化、CRUD、查询、分区策略、错误处理和测试，理论上能完成核心服务层搭建；但模板需要大量重命名、模型补充和项目配置，生产级质量及代表性输出未被静态证据验证，且部分示例需要人工修正，因此按静态上限给出中等分数并扣分。
证据是可审计的版本化源文件，包含测试模板、集成测试模式和仓库 CI 标识；但没有提供该技能关键路径的实际执行结果、完整测试套件或独立复核材料，README 徽章也不足以证明本技能已通过覆盖性测试，因此仅给有限分数。
- 不要直接将模板视为生产就绪代码；先统一同步/异步客户端策略，并补充客户端和凭据的关闭流程。
- 删除、跨分区移动和跨租户访问前应加入明确授权、用户确认、审计及失败恢复机制。
- 审查 extra_filter 的调用边界、异常日志和配置加载，避免查询片段注入及敏感信息泄露。
- 材料未说明 Azure 服务在中国大陆网络和区域环境中的可达性，部署前需单独验证。
它能做什么 & 适用场景
该技能面向使用 Python 和 FastAPI 构建 Azure Cosmos DB NoSQL 服务的开发者。它提供客户端配置、DefaultAzureCredential 与模拟器双重认证、服务层 CRUD、分区键、参数化查询和测试驱动开发模式。内容还涵盖 Pydantic 五层模型、优雅降级、单例容器以及同步或异步客户端生命周期管理。它适合需要生产级实现模式的 Azure 应用，但不负责部署 Cosmos DB 资源。
指导编码代理安装 azure-cosmos 和 azure-identity，读取环境变量配置 Cosmos 端点、数据库和容器，创建带 DefaultAzureCredential 或模拟器密钥的客户端，设计 FastAPI 路由与 Cosmos DB 服务层，生成 CRUD、文档与模型转换、分区键访问、参数化查询和 pytest 测试代码，并建议使用上下文管理器释放客户端和凭据资源。
- 正在开发 FastAPI 后端、需要为项目或工作区增加 Cosmos DB 持久化的 Python 开发者。
- 希望在本地使用 Cosmos DB 模拟器、在 Azure 生产环境使用托管身份或其他 Entra 凭据的团队。
- 需要按分区键隔离数据、避免跨分区扫描并验证用户授权范围的应用开发者。
- 希望先编写 pytest 测试，再实现可模拟 Cosmos 容器的服务层的团队。
- 需要将 Cosmos DB 文档、Pydantic API 模型和业务逻辑分离的后端项目。
优缺点一览
- 覆盖认证、客户端生命周期、服务层、模型、分区键、查询和测试等完整实现环节。
- 明确优先使用 DefaultAzureCredential，并将密钥限制在模拟器或本地开发场景。
- 提供 FastAPI、Pydantic 和 pytest 的具体代码模式。
- 强调参数化查询、授权相关分区键校验和优雅降级等生产实践。
- 仓库采用 MIT 许可证，并通过 npx skills add 提供集合安装方式。
- 只聚焦 Cosmos DB NoSQL 服务实现，不涵盖资源部署或完整基础设施配置。
- 技能依赖 Python、Azure SDK、FastAPI、Pydantic 和 pytest，源材料未说明版本兼容范围。
- 源材料没有提供该单项技能独立测试覆盖或运行结果。
- 异步实现、单例生命周期和上下文管理器之间需要开发者根据项目结构自行整合。
如何安装
在目标项目中运行 npx skills add microsoft/skills，在安装向导中选择 azure-cosmos-db-py。README 也说明可从仓库复制该技能到代理目录；技能源文件位于 .github/plugins/azure-sdk-python/skills/azure-cosmos-db-py/SKILL.md。具体代理目录由安装向导决定。
如何使用
在支持 Agent Skills 的编码代理中提出类似“为 FastAPI 添加 Azure Cosmos DB NoSQL 持久化，使用 DefaultAzureCredential、分区键、服务层 CRUD 和 pytest 测试”的请求，或使用“Cosmos DB”“Python Cosmos SDK”“database service layer”等触发短语。实现时按技能要求设置 COSMOS_ENDPOINT、COSMOS_DATABASE_NAME 和 COSMOS_CONTAINER_ID；模拟器场景还需 COSMOS_KEY。