COS API AI 生态

面向外部开发者的 COS / 数据万象(CI) API AI 接入辅助包：规则、Skills、结构化知识、CLI 安装器和只读 MCP。目标是让 AI 编程助手在接入腾讯云对象存储 COS 与数据万象 CI 时，稳定生成安全、可运行、可追溯到官方资料的代码。

它不是 SDK，不调用真实 COS/CI API，不接收密钥。核心价值：让 AI 少幻觉、少泄密、多可追溯。

一期覆盖：

• 服务端用永久密钥签发 STS 临时密钥（最小权限 policy，限定 action/resource/bucket/prefix/时长）。
• 浏览器 / 移动端只用临时密钥：Web 直传/列表/下载、CORS、预签名 URL、分块上传、移动端上传。
• 服务端 Node SDK（cos-nodejs-sdk-v5）与 Web SDK（cos-js-sdk-v5）用法。
• CI 最小闭环：数据万象图片处理（下载时处理）走通「授权 → 调用 → 错误处理」。
• 静态审查永久 SecretId/SecretKey 泄露、STS/CI policy 过宽（resource:*/action:*）。

安全底线：永久 SecretId/SecretKey 只在服务端；前端/移动端只用 STS 临时密钥；不混淆 COS XML API / COS SDK / CI 处理 API / STS 云 API。CI 的 ci:* action 命名、CI 开通方式、CI 请求签名是否与 COS 一致等，凡官方文档未明示的一律标注**「待核验」**，不编造。

给开发者使用

正式发布到 npm 后，安装到项目：

npx cos-api-ai@latest init --ide all

常用命令：

npx cos-api-ai@latest init --ide cursor --rules --skills
npx cos-api-ai@latest init --ide codebuddy --mcp
npx cos-api-ai@latest update
npx cos-api-ai@latest doctor
npx cos-api-ai@latest uninstall --ide all

默认安装 rules、skills 和本地知识库。只有显式传入 --mcp 时才写入只读 MCP 配置。

当前 npm 包尚未正式发布，本地自测请直接从仓库运行：

node bin/cos-api-ai.js init --cwd /path/to/test-project --ide all --mcp --mcp-local
node bin/cos-api-ai.js doctor --cwd /path/to/test-project
node bin/cos-api-ai.js uninstall --cwd /path/to/test-project --ide all

四 IDE 安装方式

一条命令装全部（推荐）：

npx cos-api-ai@latest init --ide all --mcp

按 IDE 分别安装：

CodeBuddy

npx cos-api-ai@latest init --ide codebuddy --mcp

产物：.codebuddy/rules/cos.mdc（always-on 规则）、.codebuddy/skills/cos-*（场景 skills）、.codebuddy/mcp.json（只读 MCP）。CodeBuddy 自动加载这些目录。

Cursor

npx cos-api-ai@latest init --ide cursor --mcp

产物：.cursor/rules/cos.mdc、.cursor/skills/cos-*、.cursor/mcp.json。可在 Cursor 的 Settings → Rules / MCP 中看到。

Claude Code

npx cos-api-ai@latest init --ide claude --mcp

产物：.claude/rules/cos.md（Claude Code 会话启动自动加载，无 paths 即常驻）、.claude/skills/cos-*/SKILL.md（Agent Skills）、项目根 .mcp.json（project scope，首次使用需在 Claude Code 里批准）。

Codex（OpenAI Codex CLI）

npx cos-api-ai@latest init --ide codex
# 可选：接入只读 MCP（init 会打印同样的命令）
codex mcp add cos-api-ai -- npx -y cos-api-ai@latest mcp

产物：项目根 AGENTS.md 注入托管区块（Codex 常驻加载，含规则 + 场景路由 + 知识指针）、.cos-api-ai/knowledge/（区块指引 AI 读取）。Codex 无原生 skills 概念——场景路由写进 AGENTS.md 块、指向知识库，不建 skills 目录。Codex 的 MCP 是全局 ~/.codex/config.toml，用官方 codex mcp add 命令接入，本工具不写/不改该文件；卸载后如加过 MCP，请手动 codex mcp remove cos-api-ai。 已有 AGENTS.md 时只增删本包托管区块，不动你的原有内容。

卸载：npx cos-api-ai@latest uninstall --ide all（会移除各 IDE 产物、AGENTS.md 托管区块，并保留 .mcp.json 中其它 server）。

如何真实验证（下载 IDE 实测）

先做本地基础校验，再到各 IDE 里验证「是否真的被加载并生效」。

0）通用（不依赖 IDE）

npx cos-api-ai@latest init --cwd /path/to/demo --ide all --mcp
npx cos-api-ai@latest doctor --cwd /path/to/demo   # 期望全 OK、exit 0

doctor 全 OK 只说明「产物落到了各 IDE 约定位置」，下面才是「IDE 真的用起来了」。

1）下载/安装各 IDE

• Claude Code：npm install -g @anthropic-ai/claude-code（或见官方文档）。
• Codex：npm install -g @openai/codex（或 brew install codex；以官方为准）。
• Cursor：从 cursor.com 下载客户端。
• CodeBuddy：从腾讯云 CodeBuddy 官网下载客户端。

2）在项目里 init，然后用下面三类「行为验证」确认真的生效（比看文件更可信）：

• 规则生效（反密钥泄露）：新开会话问「帮我在 React 前端直接用 COS SDK 上传文件」。生效标志：AI 拒绝把永久 SecretId/SecretKey 放前端，改用后端 STS 临时密钥。
• skills + 知识生效（可追溯/不编造）：问「用 Node 后端签发 COS STS 临时密钥」。生效标志：用正确包名 qcloud-cos-sts、qcs::cos: 形式的最小权限 policy ARN、并引用官方来源链接。
• 反幻觉（CI）：问「对 COS 图片做内容审核」。生效标志：用真实 action ci:CreateAuditingPictureJob（而不是编造的 ci:CreateAuditingImageJob）。

3）MCP 是否接上

• Cursor / CodeBuddy：在 IDE 的 MCP 设置面板看到 cos-api-ai server（已连接/绿点）；或让 AI 调用 cos_search_api、cos_recommend_policy 等工具。
• Claude Code：运行 claude mcp list，应出现 cos-api-ai（project scope，首次需批准）。
• Codex：codex mcp add ... 后运行 codex mcp list，应出现 cos-api-ai。

提示：评测已证明「rules+skills+MCP」组对来源可追溯率、反幻觉的提升（见 评测方案）；上面的行为验证就是在你自己的 IDE 里复现这一效果。

安装产物

• .cos-api-ai/knowledge/：endpoint 索引、错误码、action/policy 配方、集成清单/模式、SDK 示例。
• .cos-api-ai/install.json：安装元数据。
• .cursor/rules/cos.mdc、.codebuddy/rules/cos.mdc、.claude/rules/cos.md：always-on 规则。
• AGENTS.md（Codex）：注入 cos-api-ai 托管区块（规则 + 场景路由 + 知识指针）；卸载只删该区块，保留用户原有内容。
• .codebuddy/skills/cos-*、.claude/skills/cos-*、.cursor/skills/cos-*：场景 Skills（含 ci-image-processing）。
• .mcp.json、.cursor/mcp.json、.codebuddy/mcp.json：可选只读 MCP 配置（Claude Code 读根目录 .mcp.json；Codex 用官方命令 codex mcp add cos-api-ai -- npx -y cos-api-ai@latest mcp 接入）。

只读 MCP

MCP 不调用真实 COS/CI API，不接收密钥，只查询本地知识：

• cos_list_api_groups
• cos_search_api
• cos_get_endpoint
• cos_sdk_example
• cos_recommend_policy（只返回 policy 模板，不签发真实临时密钥）
• cos_explain_error
• cos_check_project（只静态扫描永久密钥泄露与 policy 过宽）

手动 smoke：node bin/cos-api-ai-mcp.js

维护者常用命令

npm run ci                 # 本地全量：test + eval:fixtures + validate + npm pack --dry-run
npm test
npm run validate           # 公开产物校验
npm run eval:fixtures      # 静态门禁 fixture pass/fail 全覆盖
npm run sdk:check          # SDK 公开渠道可用性
npm run sources:check      # 资料源更新检查
npm run release:preflight  # 发布前预检

文档

• 产品无关方法论 Playbook
• COS API AI 实施蓝图
• 项目状态
• 评测方案与结果
• 官网开发者文档（栏目源文件，3 篇）
• 项目汇报（发布 brief）
• 发布前人工审核清单 / 交接说明

License

MIT