seli-api 是一个面向 Seli 平台的 CLI 操作技能,目标是在智能体代表某个租户执行 Seli 工作时,通过已安装的 seli CLI 作为默认接口完成操作。由于该二进制文件自带文档,且公共 API 会持续扩展,这个技能并不复制命令树或 API 参考,而是提供一套发现式的工作流程。
用途与定位:将用户请求转化为单一、机械的 Seli 意图,再通过帮助系统发现对应的命令组和具体命令,最后执行并核验结果。它适用于任何需要以租户身份通过 Seli CLI 查看或变更数据的场景。
主要能力与工作流:
-
环境与认证预检。开始新环境或新会话时,先用 shell 原生查找解析可执行文件(POSIX shell 用
command -v seli,PowerShell 用Get-Command seli),然后运行seli version。之后保持使用同一解析结果执行版本、帮助、预检和操作,避免混用不同构建导致错误的参数与能力判断。若找不到 seli,应先只读检查操作系统、架构、shell 和可用包管理器,告知用户 Seli CLI 尚未安装并推荐官方安装指南 https://github.com/vtech-com/seli-api-sdk#installation,由用户授权后再安装,并用seli version验证。版本检查成功后,运行只读的认证与连通性探测seli health --tenant <code>;该探测需要 API 主机、API 密钥和租户三项,租户可通过--tenant、SELI_TENANT或已存储的 default_tenant 解析,主机来自构建内置的 default_api_url、SELI_API_URL或存储的 api_url。 -
按退出码解释结果。退出码 0 表示 API 可达且密钥对该租户有效;退出码 2 中 AUTH_MISSING_HEADER 表示未配置密钥、请求未发出,其他 error.code 表示服务器拒绝密钥,应让用户自行在 Seli Web 应用创建或获取密钥,并在自己的终端用
seli auth login --key <key>存储,或在 CI 与共享机器上优先导出SELI_API_KEY;退出码 3 表示密钥有效但无法为该租户操作;退出码 5 为本地或校验错误,如 TENANT_REQUIRED(未解析到租户)、API_URL_MISSING(构建无默认主机)、INSECURE_BASE_URL(URL 非 https);退出码 6 表示连通性失败,包括 30 秒超时,应排查 DNS、网络或 API URL,而非误判为认证问题;退出码 7 表示被限流,需退避后重试;其他非零退出码(包括退出码 1,也涵盖服务器 HTTP 5xx)应阅读 error 对象中的 request_id 和 raw 后再建议恢复步骤。 -
逐步发现命令面。用
seli --help、seli <group> --help、seli <group> <command> --help按用户意图只读取相关的组与命令。可运行的命令页包含用途、用法、参数、约束、示例和输出。不得凭记忆重建命令、猜测参数,也不得把该技能当作命令清单;已安装版本的帮助优先于技能描述,二者不一致时应遵循帮助并反馈差异。 -
计划、执行与核验。调用前,将请求转化为单一 Seli 意图,从帮助中发现组与命令,构造参数或 JSON 前阅读叶子命令帮助,并解析租户;若写入操作的目标租户不明确,应先询问。用户可同时属于多个租户,不存在可假定的唯一“当前”租户;解析出的租户只是决定查看哪个租户数据的路由选择。若租户来自存储的默认值(meta.tenant_source 为 config)而非用户请求,应说明实际使用的租户。不应仅凭成员级别推断权限,而应让 API 的 403 响应来说明。调用后解析 stdout 上的单个 JSON 文档,先检查 error 键再信任数据;部分结果(如
members list --all在第一页后失败)会同时携带数据与错误且退出码非零,此时错误键旁的行只是答案的前缀。还应核对 meta.tenant 与 meta.tenant_source(flag、env 或 config),写入操作还要核验返回对象,并在汇报结果时避免暴露凭据、原始认证头或无关租户数据。 -
处理缺失命令与失败。若预期命令不存在,应复查根帮助和相关组帮助,猜测的名称不能证明能力不可用;操作可能位于相邻组,或已安装 CLI 旧于当前 API。命令失败时,阅读 stdout 错误对象的 code、message、http_status,raw 是服务器响应体,request_id 是升级问题时引用的句柄;阅读叶子命令帮助,仅在确实需要脱敏 HTTP 追踪时使用
--verbose;仅对瞬时网络或限流等可重试错误重试,不盲目重试校验、认证、权限、冲突或结果不明确的写入。写入失败并不证明 API 缺少该能力,不得编造重建资源、更改标识符或绕过租户处理等破坏性恢复步骤。 -
谨慎使用公共 API 规范。公共规范位于
<host>/api/openapi(公开、无需密钥),主机来自seli version的 default_api_url、SELI_API_URL 或存储的 api_url,路径均以 /api/ 开头而非 /api/v1/。对于普通用户操作,应止步于 CLI 帮助并通过 seli 执行;仅在用户明确询问公共 API 契约或正在构建集成、正在开发或审查该 SDK、实际帮助确认存在 CLI 缺口且需区分“CLI 未暴露”与“公共 API 不存在”、或需诊断版本不匹配与帮助/规范不准确时,才打开规范。在 SDK 仓库内应优先使用对应版本的 api/openapi.json,公共 URL 用于查看当前已发布契约。规范只定义 API 路径与模式,不定义已安装 CLI 的参数拼写;在规范中找到端点并不授权绕过 CLI 进行常规租户操作,应报告缺口或建议升级。只有在用户任务明确是构建或测试公共 API 集成且另行授权时,才可调用原始 HTTP。 -
按需加载特殊场景指引。大多数操作只需叶子帮助;成员查找或为其他写入解析特定人员身份时,在阅读叶子帮助后加载 references/domains/members.md,无关的列表或搜索工作不应加载领域参考。
范围边界:该技能覆盖 Seli CLI 操作与公共 API 发现,不定义组织的产品编码、条码、命名、审批或数据治理策略,这些应来自用户自身政策或独立的组织专用技能。
凭据安全:认证密钥属于用户。不得要求用户将 API 密钥粘贴到对话中,不得检查凭据文件或环境变量以恢复密钥,不得打印密钥、将其放入示例或通过 shell 追踪暴露。