capigo-api

Capigo CLI 操作指南

使用 capigo 作为与 Capigo 交互的常用接口。已安装的二进制文件提供自我说明，而 Public API 还会不断扩展，因此本技能介绍的是一套探索工作流，而不是重复列出命令树或 API 参考。

1. 检查环境和身份验证

每次进入新环境或会话时，先使用 Shell 原生查找方式解析可执行文件（在 POSIX Shell 中运行 command -v capigo，或在 PowerShell 中运行 Get-Command capigo），然后运行：

capigo version

在版本、帮助、预检和执行过程中，始终使用解析出的可执行文件；混用一个构建版本的帮助信息和另一个版本执行命令，会导致错误的标志和功能错误。

如果 Shell 找不到 capigo：

1. 使用只读检查，查看操作系统、架构、Shell 和可用的包管理器。
2. 告知用户尚未安装 Capigo CLI，并推荐官方安装指南：https://github.com/vtech-com/capigo-api-sdk#installation。
3. 优先推荐适合检测到的机器的安装方式。例如，如果存在 Homebrew，建议运行 brew install --cask vtech-com/tap/capigo；该指南也介绍了 GitHub Releases 和基于 Go 的安装方式及其平台特定注意事项。
4. 不要仅仅因为缺少二进制文件就安装软件或更改机器。等待用户授权后，再通过 capigo version 验证安装结果。

版本检查成功后，运行只读的身份验证和连通性探测：

capigo health

根据退出代码和标准输出中的 error 对象进行判断：

• 退出代码为 0：API 可访问，且配置的密钥已通过验证。继续操作。
• 退出代码为 2，且错误对象中包含 key_source：运行 CLI 的环境提供了密钥，因此以下登录步骤不适用。不要建议运行 capigo auth login，也不要向用户索要密钥；按照错误中的 next 操作。AUTH_EMPTY_ENV_KEY 表示该环境为此用户提供了空密钥。
• 退出代码为 2：密钥缺失、格式错误或未通过验证。运行 capigo auth login --help，告知用户在登录 https://platform.capigo.app 后创建或获取密钥，并请他们在本地运行受支持的登录命令。然后重试 capigo health。代码 AUTH_MISSING_HEADER 表示首次运行的情况——完全没有配置密钥，因此 CLI 从未访问 API。这不是暂时性问题：用户登录前不要重试。
• 退出代码为 6：连接失败。排查 DNS、网络访问或配置的 API URL；不要将其误判为身份验证问题，也不要要求用户重新登录。
• 其他任何非零退出代码：查看错误对象和 capigo help exit-codes，再建议恢复步骤。

不要使用 capigo auth whoami 进行预检。其 /me 路由尚未实现，因此 404 无法说明配置的密钥是否有效。

身份验证机密属于用户。绝不要要求用户将 API 密钥粘贴到聊天中，不要检查凭据文件或环境变量来找回密钥，不要打印密钥、将其放入示例或通过 Shell 跟踪暴露密钥。引导用户运行 capigo auth login --help，并让他们通过受支持的流程在本地输入密钥——但如果错误中包含 key_source，则密钥由环境管理，auth login 会以 KEY_MANAGED_BY_ENV 拒绝执行，应按照其自身的 next 操作。在 CAPIGO_NO_CONFIG=1 模式下，配置文件会被禁用，config 命令会以 CONFIG_DISABLED 退出代码 1；请在每条命令中传入 --tenant，而不要存储默认值。 当环境提供密钥时，也会决定密钥的去向：基础 URL 依次取自 --api-url、CAPIGO_API_URL，然后是默认主机；租户依次取自 --tenant，然后是 CAPIGO_TENANT。已存储的 api_url 或 default_tenant，以及未加前缀的 API_URL 或 TENANT 变量都会被忽略，而且 meta.tenant_source 永远不会是 config。切勿自行传入 --api-url，也不要尝试将 CLI 指向其他服务。使用此类密钥时，config get api_url 和 config get default_tenant 会打印已存储的值，但 API 命令不会采用这些值。 EMPTY_ENV_API_URL（退出码为 1）表示环境设置了空 URL：没有发送任何内容，重试也无济于事——请告知人工人员。

一个密钥对应一个工作区

密钥绑定到创建它时所在的单个工作区；平台的 API keys 页面会显示该工作区。每个请求都会在服务端强制执行此绑定，因此无论 CLI 发送什么都不例外：

• 指定另一个工作区——使用 --tenant、CAPIGO_TENANT，或属于不同密钥的 default_tenant——都会以退出码 3 失败。密钥有效；指定的工作区不属于该密钥。
• 不指定工作区不会扩大调用范围。请求仍然只读取该密钥对应的工作区；由于 CLI 报告的是它解析出的租户，而它没有解析出租户，因此 meta 不会标明租户。如果用户需要知道答案属于哪个工作区，请将该密钥对应的工作区作为 --tenant 传入：返回相同的行，并显示 meta.tenant。
• capigo tenants list 不代表此密钥的可访问范围。它会列出该账户所属的工作区，且不会按密钥缩小范围，因此应将其视为账户目录，而绝不能视为当前密钥可以指定的工作区集合。
• 较旧的密钥可能没有绑定工作区，并能访问账户所属的所有工作区。不要根据密钥前缀或创建时间推断其访问范围；请从 API keys 页面确认，或依据即将执行的调用的退出码判断。

因此，要在多个工作区中操作，每个工作区都需要一个密钥——每个密钥使用一个配置文件，或在每次调用时设置 CAPIGO_API_KEY 和 CAPIGO_TENANT。没有 --profile 标志，也没有任何命令可以创建配置文件：第二个配置文件需要手动编辑 ~/.capigo/config.json。如果错误信息包含 key_source，则唯一的密钥由环境提供：不要设置 CAPIGO_API_KEY、编辑配置或索要另一个密钥——请遵循错误中的 next（包括退出码 3）。

2. 探索当前可用的命令

capigo version 成功后，逐步使用内置帮助：

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

已安装的帮助信息优先于 CLI 的拼写和行为说明，因为它随当前精确版本的构建一起发布。如果帮助信息与此技能不一致，请遵循帮助信息，并向技能维护者报告差异。

3. 规划、执行和验证

调用前：

1. 将请求转换为一个机械式 Capigo 意图。
2. 通过帮助信息查找分组和命令。
3. 构造标志或 JSON 之前，先阅读叶子命令的帮助信息。
4. 确定租户。如果写入操作的租户不明确，请先询问，再执行写入。如果用户已明确授权具体资源、变更和租户，则不要额外要求确认。创建任务仍须遵循下方单独的受派人选择门槛。请记住，密钥绑定到单个工作区：执行写入时，应明确指定该工作区，而不要依赖默认值，以便在标准输出中通过 meta.tenant 验证。
5. 遵循 references/cli-conventions.md 中的约定。

调用后：

1. 解析标准输出中的单个 JSON 文档。
2. 在信任 data 前检查是否存在 error 键；部分结果可能同时包含两者。
3. 对于写入操作，应验证 meta.tenant 和返回的对象，而不要假定使用了预期的租户或执行了预期的变更。
4. 报告结果时，不要泄露凭据、原始身份验证标头或无关的租户数据。

4. 处理缺少的命令和失败情况

如果预期命令不存在，请重新检查根帮助信息和相关分组的帮助信息。你猜测的名称并不能证明该功能不可用。该操作可能位于相邻分组下，或者已安装的 CLI 可能比当前 API 旧。

如果命令失败：

1. 阅读标准输出中的 error 对象，尤其是 message、next、request_id 以及任何 capability_note。
2. 阅读叶子命令的帮助信息和 capigo help exit-codes。
3. 仅在确实需要查看已脱敏的 HTTP 跟踪信息时使用 --verbose。
4. 仅当错误类别允许时才重试，例如临时网络错误或速率限制响应。对于验证、身份验证、权限、冲突或结果不明确的写入操作，不要盲目重试。

写入失败并不能证明 API 不具备该功能。不要编造破坏性的恢复步骤，例如重新创建资源、更改标识符或绕过租户处理。

5. 谨慎使用 Public API 规范

Public 规范：https://platform.capigo.app/api/openapi

对于常规用户操作，请止步于 CLI 帮助信息，并通过 capigo 执行。仅在满足以下至少一项时打开规范：

• 用户明确询问 Public API 契约，或正在构建集成；
• 你正在开发或审查此 SDK；
• 实时帮助信息确认 CLI 存在缺口，且你需要区分“此 CLI 未公开”与“Public API 中不存在”；
• 必须诊断版本不匹配或不准确的帮助信息／规范声明。

在 SDK 仓库中时，优先使用所处理版本对应的 api/openapi.json；使用公共 URL 检查当前发布的契约。规范定义 API 路径和架构，而不是已安装 CLI 的标志写法。在规范中找到某个端点，并不意味着可以绕过 CLI 执行常规租户操作。应报告该缺口或建议升级。仅当用户的任务明确要求构建或测试 Public API 集成，且该工作已单独获授权时，才调用原始 HTTP。

6. 仅在需要时加载特殊情况指南

大多数操作无需加载随附的领域指南：查看叶节点帮助即可。

对于会创建、遍历或更改关系的操作，请先阅读叶节点帮助，再仅加载相关领域参考文档：

• references/domains/products.md 适用于产品、变体、产品引用、产品属性（capigo property-definitions）和目录标签（products tags、variants tags、capigo tags list）；
• references/domains/tasks.md 适用于任务、负责人、子任务、评论和提及，以及标签（--label、capigo labels list）；
• references/domains/boards.md 适用于将任务放到看板或列表上，或按代码读取看板；
• references/domains/wms.md 适用于 capigo wms 下的所有内容：仓库、库位、可用量和四种库存单据。

创建产品、写入 properties 或属性定义，以及添加或移除目录标签时，请在查看叶节点帮助后阅读 products.md。创建任务或子任务，或发布评论时，请在查看相关叶节点帮助后阅读 tasks.md；仅在将任务放到看板上时，才需要一并阅读 boards.md。对于任何 capigo wms 写入操作，以及向用户报告 WMS 读取结果时，都请阅读 wms.md：其中的判定结果、空值成本和状态很容易报告错误。无关的列表或搜索操作无需加载领域参考文档。

范围边界

此技能涵盖 Capigo CLI 操作和 Public API 发现。它不规定组织的产品代码、条形码、命名、审批或数据治理政策。请遵循用户自己的政策或单独的组织专用技能。