SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场capigo-api

capigo-api

智能体与模型

查看项目

更新于 10-21 16:23

技能介绍

用途

本技能用于通过已安装的 capigo CLI 驱动 Capigo 平台，是智能体为租户执行任何 Capigo 工作的入口。它不复制命令树或 API 参考，而是教授一套发现式工作流，因为已安装的二进制文件自带文档，且 Public API 会持续增长。

主要能力

  • 环境与认证预检：解析可执行文件（POSIX 下 command -v capigo，PowerShell 下 Get-Command capigo），运行 capigo version，再运行只读的 capigo health 探测认证与连通性。
  • 按退出码解读结果：退出 0 表示 API 可达且密钥被接受；退出 2 表示密钥缺失、格式错误或被拒绝（AUTH_MISSING_HEADER 为首次运行、未配置密钥的情况，不可重试直到用户登录）；退出 6 表示连通失败，应排查 DNS、网络或 API URL，而非误判为认证问题；其他非零退出需阅读错误对象与 capigo help exit-codes。
  • 渐进式发现命令面：capigo --help、capigo <group> --help、capigo <group> <command> --help，只阅读与用户意图相关的分组和命令。
  • 获取横切契约：capigo help tenancy、capigo help output、capigo help exit-codes、capigo help soft-delete、capigo help versioning。
  • 计划、执行与验证：调用前把请求翻译为单一机械 Capigo 意图、从帮助中发现分组与命令、阅读叶子命令帮助、解析租户；调用后解析 stdout 上的单个 JSON 文档，先检查 error 键，写入操作核对 meta.tenant 与返回对象。
  • 处理缺失命令与失败：重新检查根帮助与相关分组帮助，阅读 stdout 错误对象（message、next、request_id、capability_note），仅在错误类别支持时重试（如瞬时网络或限流），不盲目重试验证、认证、权限、冲突或结果不明的写入。
  • 按需加载领域参考：涉及关系创建、遍历或变更时，在阅读叶子帮助后加载相关领域参考，如 references/domains/products.md（产品、变体、产品引用、产品属性）、references/domains/tasks.md（任务、负责人、子任务、评论与提及、标签）、references/domains/boards.md（看板与列表放置、按代码读取看板）、references/domains/wms.md（仓库、库位、可用性及四种库存单据）。

使用方式

  1. 预检环境与认证：解析可执行文件，运行 capigo version；若 shell 找不到 capigo，用只读检查了解操作系统、架构、shell 与可用包管理器，告知用户未安装并推荐官方安装指南 https://github.com/vtech-com/capigo-api-sdk#installation；例如存在 Homebrew 时可建议 brew install --cask vtech-com/tap/capigo。不要因二进制缺失就擅自安装或更改机器，需等待用户授权，再用 capigo version 验证。版本检查成功后运行 capigo health。
  2. 发现实时命令面：使用内置帮助逐级查看，不要凭记忆重建命令、猜测标志或把本技能当作命令清单。已安装的帮助在 CLI 拼写与行为上优先；若帮助与本技能冲突，遵循帮助并报告不一致。
  3. 计划、执行与验证：调用前解析租户，写入租户不明确时先询问；用户已授权确切资源、变更与租户时不要添加多余确认；任务创建仍遵循单独的负责人选择门。写入时显式命名该工作区，以便事后通过 stdout 的 meta.tenant 验证。调用后解析单个 JSON 文档，先检查 error 键，写入操作核对 meta.tenant 与返回对象，报告结果时不暴露凭据、原始认证头或无关租户数据。
  4. 处理缺失命令与失败：若预期命令缺失，重新检查根帮助与相关分组帮助；命令失败时阅读 stdout 错误对象、叶子命令帮助与 capigo help exit-codes，仅在需要时使用 --verbose 查看脱敏 HTTP 跟踪。
  5. 谨慎使用 Public API 规范：规范地址为 https://platform.capigo.app/api/openapi。仅在用户明确询问 Public API 契约或正在构建集成、正在开发或审查本 SDK、实时帮助确认 CLI 缺口需区分“CLI 未暴露”与“Public API 不存在”、或需诊断版本不匹配或帮助/规范声明不准确时才打开规范。在 SDK 仓库内优先使用其版本化的 api/openapi.json。规范定义 API 路径与模式，不定义已安装 CLI 的标志拼写；在规范中找到端点并不授权绕过 CLI 执行常规租户操作。

适用场景

  • 智能体为租户执行 Capigo 平台操作。
  • 需要发现并调用 Capigo CLI 命令、验证认证与连通性、处理退出码与错误。
  • 涉及产品、任务、看板、WMS 等关系型操作时按需加载领域参考。
  • 用户明确询问 Public API 契约或构建集成时查阅规范。

限制

  • 密钥绑定创建它的单一工作区，服务端对每个请求强制执行：命名其他工作区（--tenant、CAPIGO_TENANT 或属于其他密钥的 default_tenant）会以退出 3 失败；不命名也不会扩大调用范围。capigo tenants list 列出账户所属工作区，并非当前密钥可达范围，应视为账户目录。旧密钥可能不带工作区并可到达账户的每个工作区，不要从前缀或年龄推断密钥范围。跨工作区工作需各自密钥，每个密钥一个配置文件，或每次调用设置 CAPIGO_API_KEY 与 CAPIGO_TENANT；没有 --profile 标志，也没有命令创建配置文件，第二个配置文件需手动编辑 ~/.capigo/config.json。
  • 不要用 capigo auth whoami 作为预检，其 /me 路由未实现，404 不能说明密钥是否有效。
  • 认证密钥属于用户：绝不要要求用户把 API 密钥粘贴到聊天中，不要检查凭据文件或环境变量以恢复密钥、打印它、放入示例或通过 shell 跟踪暴露它；应引导用户使用 capigo auth login --help 并在本地通过受支持流程输入密钥。
  • 本技能覆盖 Capigo CLI 操作与 Public API 发现，不定义组织的产品代码、条码、命名、审批或数据治理策略，这些应来自用户自身策略或单独的组织专用技能。
  • 资料未提供具体收费、价格、平台支持范围或效果数据。