github-openapi-skill

用途

该技能用于通过 uxc 结合 GitHub 官方 OpenAPI schema，执行 GitHub REST API 操作，覆盖仓库、issue、pull request 等常见资源的读写。它复用 uxc 技能中关于共享执行、认证与错误处理的通用指导。

前置条件

uxc 已安装并可在 PATH 中调用。
gh 已安装并已通过 gh auth login 完成认证。
具备对 https://api.github.com 的网络访问。
可访问官方 GitHub REST OpenAPI schema 地址： https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

认证方式

首选：将本地 gh 认证导入 uxc

将当前 GitHub CLI 令牌导入为本地 uxc bearer 凭据，并创建标准 GitHub API 绑定：

uxc auth credential import github --from gh

该命令会创建：

credential：github
binding：github-api
绑定主机：https://api.github.com

验证绑定：

uxc auth binding match https://api.github.com/repos/holon-run/uxc

可选：手动 bearer 令牌

若 gh 不可用，可手动配置 PAT：

uxc auth credential set github \
  --auth-type bearer \
  --secret-env GITHUB_TOKEN

uxc auth binding add \
  --id github-api \
  --host api.github.com \
  --path-prefix / \
  --scheme https \
  --credential github \
  --priority 100

请勿提交 GitHub 令牌，也不要在该技能或仓库中硬编码令牌。

核心工作流

默认使用固定链接命令：

command -v github-openapi-cli

如不存在，则创建：

uxc link github-openapi-cli https://api.github.com --schema-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

查看帮助：

github-openapi-cli -h

先检查操作 schema：

github-openapi-cli get:/user -h
github-openapi-cli get:/repos/{owner}/{repo} -h
github-openapi-cli get:/repos/{owner}/{repo}/issues -h

先执行读操作，再执行写操作：

github-openapi-cli get:/user
github-openapi-cli get:/repos/{owner}/{repo} owner=holon-run repo=uxc
github-openapi-cli get:/repos/{owner}/{repo}/issues owner=holon-run repo=uxc state=open per_page=10
github-openapi-cli get:/repos/{owner}/{repo}/pulls owner=holon-run repo=uxc state=open per_page=10

将变更类操作视为需明确确认的操作：

github-openapi-cli post:/repos/{owner}/{repo}/issues '{"owner":"holon-run","repo":"uxc","title":"Example issue"}'

防护规则

自动化应保持 JSON 输出外层结构，不要使用 --text。
优先解析稳定字段：ok、kind、protocol、data、error。
github-openapi-cli <operation> ... 等价于： uxc https://api.github.com --schema-url https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json <operation> ...
优先执行读操作，再执行写操作。
将 issue 创建、issue 编辑、评论、标签、仓库管理、发布与工作流触发端点视为写/高风险操作；执行前需获得用户明确确认。

参考

使用模式：references/usage-patterns.md
GitHub REST OpenAPI schema：https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
GitHub REST 文档：https://docs.github.com/rest

适用场景与限制

适用于需要通过命令行以 OpenAPI schema 方式调用 GitHub REST API 的自动化或脚本场景，尤其是希望复用本地 gh 认证、并在执行写操作前保留明确确认环节的工作流。限制方面：需要预先安装 uxc 与 gh，并具备网络访问；认证、写操作等需遵循上述前置条件与防护规则。该技能未提供关于价格、收费、平台支持范围或其他未在资料中说明的功能信息。