内容
# cosmosdb-agent-kit
[](https://opensource.org/licenses/MIT)
[](CONTRIBUTING.md)
[](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
[](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/discussions)
Azure Cosmos DB 智能代理技能集合，适用于 AI 编程代理。技能是封装的指令和脚本，扩展了代理的能力。
技能遵循 [Agent Skills](https://agentskills.io/) 格式，该工具包适用于 **Claude Code**、**Codex**、**Cursor**、**Gemini CLI**、**Kimi Code** 和 **GitHub Copilot**。
## 最佳使用场景
该代理工具包设计用于**渐进式（按需）技能交付**：仅在需要时加载相关技能，而不是将整个技能集注入每个提示中。为了获得最佳结果：
- **推荐：** 支持渐进式或按需技能加载的代理主机（例如，VS Code 中的 GitHub Copilot），**或** 具有大上下文窗口的模型（大约 **200K+ tokens**）。
- **谨慎使用：** 将**整个**技能集作为始终在线的上下文注入的主机（某些 IDE 代理和 CLI 工具）**与** 具有较小可用提示预算的模型（大约 **128K tokens 或更少**）。在此配置中，完整的技能 payload 可能消耗或溢出上下文窗口，从而降低输出质量或导致代理停止进展。
**如果您处于受限设置**（始终注入并使用较小上下文模型），请优先选择以下选项之一：
- 加载**单个、专注的技能**以完成当前任务，而不是完整的技能集；
- 切换到**更大上下文模型**；
- 使用支持**按需技能发现**的主机。
> 这些建议基于跨多个模型和交付机制的内部技能效果测试。确切的上下文限制因模型和主机而异。
## 可用技能
| 技能 | 描述 | 状态 |
|-------|-------------|--------|
| [cosmosdb-best-practices](skills/cosmosdb-best-practices/) | 性能优化（111 条规则，12 类别） | ✅ 稳定 |
| migration-capacity-planning | RU 计算、数据大小估算、分区预拆分 | 🚧 计划中 |
### cosmosdb-best-practices
Azure Cosmos DB 性能优化指南，包含 12 类别的 111 条规则，按影响优先级排序。
**使用场景：**
- 编写与 Cosmos DB 交互的新代码；
- 设计数据模型或选择分区键；
- 检查代码中的性能问题；
- 优化查询或吞吐量配置。
**涵盖类别：**
- 数据建模（关键）
- 分区键设计（关键）
- 查询优化（高）
- SDK 最佳实践（高）
- 设计模式（高）
- 向量搜索（高）
- 全文搜索（高）
- 安全（高）
- 索引策略（中高）
- 吞吐量和扩展（中）
- 全球分布（中）
- 开发工具（中）
- 监控和诊断（低中）
## 安装
### APM（推荐 — 所有托管端）
```bash
apm install AzureCosmosDB/cosmosdb-agent-kit
```
一键安装适用于 GitHub Copilot、Claude Code、Cursor、Codex、Gemini 和 Kimi Code 的技能。
### 通用一键安装（所有代理）
```bash
npx skills add AzureCosmosDB/cosmosdb-agent-kit
```
将技能目录放入您正在使用的代理中。
### GitHub Copilot CLI
```bash
/plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
/plugin install cosmosdb@cosmosdb-agent-kit
```
### Claude Code
```bash
/plugin install cosmosdb@claude-plugins-official
```
### Gemini CLI
```bash
gemini extensions install https://github.com/AzureCosmosDB/cosmosdb-agent-kit
```
### Kimi Code CLI
直接从 GitHub 安装（推荐）：
```bash
/plugins install https://github.com/AzureCosmosDB/cosmosdb-agent-kit
/reload
```
或添加自定义市场目录，然后从插件管理器（/plugins）安装：
```bash
/plugins marketplace https://raw.githubusercontent.com/AzureCosmosDB/cosmosdb-agent-kit/main/kimi-marketplace.json
```
插件清单位于 `.kimi-plugin/plugin.json`，目录位于 `kimi-marketplace.json`。
### OpenAI Codex CLI
添加存储库市场，然后从 ChatGPT 桌面应用程序的插件目录安装：
```bash
codex plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
```
插件清单位于 `.codex-plugin/plugin.json`，市场目录位于 `.agents/plugins/marketplace.json`（Codex 还读取旧的 `.claude-plugin/marketplace.json`）。
### 每个代理的插件目录
存储库中包含预制的插件清单：
| 代理 | 清单 |
|-------|----------|
| Claude Code | `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` |
| OpenAI Codex | `.codex-plugin/plugin.json` + `.agents/plugins/marketplace.json` |
| Cursor | `.cursor-plugin/plugin.json` |
| Gemini CLI | `gemini-extension.json` + `GEMINI.md` |
| Kimi Code | `.kimi-plugin/plugin.json` |
| GitHub Copilot | `skills/cosmosdb-best-practices/SKILL.md`（自动检测） |
## 网站
项目网站位于 `docs/`，设计用于 GitHub Pages 发布。
- 主页：`docs/index.html`
- 样式：`docs/styles.css`
- 交互 + 调查流程：`docs/app.js`
网站包含一个反馈调查，打开一个预填充的 GitHub 问题，允许用户分享对 Agent Kit 的改进，而无需后端服务。
### 本地预览
```bash
# 选项 1：VS Code Live Server
# 使用 Live Server 打开 docs/index.html
# 选项 2：Python 静态服务器
python -m http.server 8080 --directory docs
```
然后打开 `http://localhost:8080`。
### 使用 GitHub Pages 发布
在存储库设置中，将 Pages 源设置为 `Deploy from a branch`，分支 `main`，文件夹 `/docs`。
## 使用
安装后，技能会自动可用。代理将在检测到相关任务时使用它们。
**示例：**
```
检查我的 Cosmos DB 数据模型
```
```
帮助我为订单集合选择分区键
```
```
优化此 Cosmos DB 查询
```
## 技能结构
每个技能包含：
- `SKILL.md` - 代理的说明和索引（代理读取；链接到规则）
- `rules/` - 单个规则文件
- `metadata.json` - 版本和元数据
## 兼容性
与 Claude Code、Codex、Cursor、Gemini CLI、Kimi Code、GitHub Copilot 和其他 Agent Skills 兼容的工具一起工作。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取贡献指南。
## 评估（仅限本地）
该项目包含一个用于本地技能测试的 [Vally](https://github.com/microsoft/vally) 评估框架。目前，评估在 CI 中不强制执行（模拟执行器无法验证响应内容），但您可以本地运行它们以检查更改：
```bash
# 按照 https://github.com/microsoft/vally 中的说明安装 Vally
# 运行评估
vally run evals/cosmosdb-best-practices/eval.yaml -v
# 检查技能准备情况
vally check skills/cosmosdb-best-practices
```
**正在寻找帮助？** 查看我们的 [good first issues](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 或浏览 [Discussions](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/discussions) 板块以分享想法。
## 贡献者
感谢所有贡献规则、修复和想法的人员！
<!-- ALL-CONTRIBUTORS-LIST:START -->
<!-- prettier-ignore-start -->
<!-- markdownlint-disable -->
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
欢迎任何形式的贡献！参见 [贡献指南](CONTRIBUTING.md) 以开始。
## 使用 Vally 进行评估
该项目使用 [Vally](https://github.com/microsoft/vally) 来评估技能质量，测试代理在数据建模、分区、查询、SDK 使用和吞吐量场景等方面是否提供正确的 Cosmos DB 指导。
```bash
# 按照 https://github.com/microsoft/vally 中的说明安装 Vally
# 运行评估（模拟执行器，无需 API 密钥）
vally run evals/cosmosdb-best-practices/eval.yaml -v
# 检查技能准备情况
vally check skills/cosmosdb-best-practices
# 使用真实模型运行（需要 Copilot 身份验证）
vally run evals/cosmosdb-best-practices/eval.yaml --executor copilot-sdk --model claude-sonnet-4.6
```
## 更新日志
参见 [CHANGELOG.md](CHANGELOG.md) 获取 agent kit 的更新历史，包括 `cosmosdb-best-practices` 技能和测试框架。每个条目都链接到引入更改的 PR。
当您合并 PR 时，请在 `CHANGELOG.md` 顶部添加新的带日期的条目。
## License
MIT
MCP 市场