用途
本技能负责 Twingate 的 GraphQL API、服务账号密钥管理、CLI 工具以及基于 API 的自动化。它覆盖脚本编写、CI/CD 流水线集成、分页、速率限制、令牌权限，以及连接器和服务账号凭据的程序化配置路径。它不替代 IaC——用于脚本和自动化，而非管理需要生命周期跟踪的长期 Twingate 对象。
主要能力与决策准则
- 在读取 mutation 响应中的 entity 前，始终先检查 ok。mutation 可能返回 HTTP 200 但 ok: false 且 entity: null。未先检查 ok 就读取 entity 字段会导致空引用错误或静默数据损坏。失败时检查 error.errorCode 和 error.message。
- 始终分页——不要假设所有结果都在一页内。省略分页的脚本会静默遗漏记录且无错误提示。可能只拿到 500 个资源中的 50 个。循环 pageInfo.hasNextPage 直到 false，每次请求将 pageInfo.endCursor 作为 after 参数传入。
- 绝不解析、解码或构造 ID。Twingate ID 是不透明的 base64 编码 NodeID。仅按 API 返回使用。绝不从 base64 解码推断数字组成部分。
- 为任务签发最小权限令牌。Read 用于监控/报告。Write 用于配置。Provision 仅用于 connectorGenerateTokens 和服务账号密钥生成。绝不向只读脚本签发 Provision 级令牌。
- connectorGenerateTokens 会轮换现有 Connector 上的凭据。对已部署的 Connector 再次调用会使当前令牌失效，Connector 停止工作，直到用新令牌重启。仅在重新配置凭据时调用——绝不作为“刷新”操作。
- 对于持久化配置管理，优先使用 Terraform 或 Pulumi 而非原始 GraphQL。API 适合脚本、自动化和报告。IaC 更适合需要生命周期跟踪和漂移检测的长期 Twingate 对象。
- 从一开始就实现 429 重试与 Retry-After 退避，而非事后补充。API 强制执行每分钟速率限制。忽略 429 的脚本在大规模操作中会中途失败。Terraform 和 Pulumi provider 会自动处理——原始脚本不能忽略。
- 服务账号密钥会过期——在使用它们的任何流水线中构建轮换逻辑。监控 expiresAt 并在过期前轮换。失败后被动轮换会中断流水线。
- 有两个不相关的工具都叫“Twingate CLI”——不要混淆。Twingate-Labs/tg-cli（Deno/TypeScript；导出/导入、拓扑图）和 Twingate-Labs/Twingate-CLI（Python，安装为 tgcli；完整 CRUD、多租户会话）是独立项目，标志不同且无共同历史。在给出命令语法前确认用户指的是哪一个。将 gh-twingate-solutions-general-scripts.md 等仓库标记为 LLM 辅助参考示例，而非受支持产品，再推荐用于生产。
使用方式
先搜索 References。在回答前用用户自己的关键词 grep references/，并引用找到的内容。文件名只揭示主题——工具名、厂商名和确切的标志/环境变量名在文件正文中，仅扫描文件名会遗漏：
grep -ril "cloudwatch" references/ # -> gh-twingate-labs-tg-aws-tag-sync.md grep -ril "graphviz" references/ # -> gh-twingate-labs-tg-cli.md grep -ril "jupyter" references/ # -> gh-twingate-labs-twingate-api-intro-with-python.md, gh-twingate-solutions-health-report-generator.md
在编写任何 API 代码或回答涉及以下内容的问题前，先阅读 references/graphql-schema-reference.md——这是权威的类型和字段参考，每个非平凡查询或 mutation 都必须查阅：
- 确切的 query/mutation 名称、参数名或参数类型
- 响应对象上的字段名（包括嵌套字段和分页结构）
- 任何字段的枚举值（例如资源协议枚举、地址类型枚举）
- create/update mutation 的输入类型结构
- 给定字段是否存在、可空或已弃用
对于 CLI 工具（Python tgcli、Deno tg-cli、tgcli-web、OpenClaw），在建议命令前阅读相应的 CLI 参考——标志名和子命令结构因工具而异，其中两个名称几乎相同。
不要凭训练数据记忆回答 schema 或 CLI 问题——schema 会演进，CLI 工具有版本特定语法。如果用户询问某自动化任务（AWS 标签同步、健康报告、CI runner 访问）是否有工具，先搜索再说不。
路由
协同激活，而非二选一。以下指针是附加的：对于跨领域提示，除本技能外还要加载并 grep 指定技能的 references/——绝不止步于第一个匹配的技能。先用用户自己的关键词 grep 兄弟技能的 references；命中时再完整加载。Twingate 答案通常分散在多个技能中，因此宁可多查而非少查。常见跨领域组合：自动化某对象 → 也加载该对象的技能（connectors / identity / architect）；持久化生命周期管理 → terraform/pulumi。
→ twingate-terraform / twingate-pulumi：当用户想要持久化 IaC 管理而非 API 脚本时——IaC 提供漂移检测、审计跟踪和生命周期管理，原始 API 脚本没有
→ twingate-architect：在编写针对资源、远程网络、组和连接器的 API 自动化前，先理解它们是什么
→ twingate-connectors：用于 connectorGenerateTokens 上下文——令牌配置是 API 操作，但 Connector 部署细节（运行时环境变量、重启行为）在 twingate-connectors 中
References
参见 references/ 获取当前语料库，每周刷新。那里有两类文件，外加一份手工维护的权威参考：
- graphql-schema-reference.md——静态 GraphQL SDL，手工维护且权威。绝不自动重新生成。
- {slug}.md——twingate.com/docs 页面（产品文档）的摘要。
- gh-{org}-{repo}.md——公共 Twingate GitHub 仓库的摘要：官方工具、SE 自动化及社区集成。
| 如果用户询问…… | 先阅读 |
|---|---|
| Query/mutation 签名、字段名、枚举值、输入类型 | graphql-schema-reference.md（权威） |
| API 概览、认证、入门 | api-overview.md, api.md, getting-started-with-the-api.md |
| 探索 API、示例查询 | exploring-the-apis.md |
| Python CLI 文档页（tg-cli） | introduction-to-the-python-cli.md |
| JavaScript CLI 文档页（tg-cli） | introduction-to-tg-cli-javascript.md |
| OpenClaw 自动化工具（通用、Docker Compose、DigitalOcean） | openclaw.md, openclaw-docker-compose.md, openclaw-digitalocean.md |
| CI/CD 流水线模式（文档页） | example-cicd-configurations.md |
| CI runner 的 GitHub Action——通过 Service Key 在 runner 上安装 Client，使工作流步骤可访问 IP 受限/私有资源 | gh-twingate-github-action.md |
| AWS 标签驱动资源自动化（EC2、ECS、RDS 上的 tg_resource/tg_groups 标签 → Lambda 通过 EventBridge/CloudWatch Events 创建/删除 Twingate 资源） | gh-twingate-labs-tg-aws-tag-sync.md |
| Deno/TypeScript 管理 CLI（tg-cli）——拓扑导出到 Excel/PNG（GraphViz）、组/网络/资源导入 | gh-twingate-labs-tg-cli.md |
| Python CLI 的浏览器 Web UI（tgcli-web）——包装 tgcli 库的 FastAPI 应用；实体浏览、带差异审查的导出/导入、健康仪表板、Docker/K8s/pip 安装 | gh-twingate-labs-tgcli-web-py.md |
| GraphQL API 的初学者 Jupyter/Python 教程——查询、mutation、内省，不假设有 GraphQL 知识 | gh-twingate-labs-twingate-api-intro-with-python.md |
| Python 管理 CLI（tgcli，基于 Typer）——对远程网络/资源/连接器/组/用户/服务账号的完整 CRUD、多租户会话、Synced→Manual 组迁移 | gh-twingate-labs-twingate-cli.md |
| 通用运维脚本（客户端部署、Intune/Autopilot、网关作为 DNS 服务器、Network Events CSV 过滤、批量组移除）——LLM 辅助参考示例，非受支持产品 | gh-twingate-solutions-general-scripts.md |
| 网络健康/洞察报告生成器——将 Network Events 导出转为资源/用户/连接器/远程网络健康分析的 Jupyter notebook | gh-twingate-solutions-health-report-generator.md |
此表是快速路径，不是全部语料库——当问题不匹配某行时，在回答前 grep references/。默认检查 schema——绝不凭记忆编写查询或 mutation；字段名和枚举值会变化。
适用场景
- 通过 GraphQL API 自动化 Twingate
- 针对 GraphQL 端点编写脚本
- 管理服务账号密钥
- 在 CI/CD 流水线中集成
- 连接器与服务账号凭据的程序化配置
- 监控与报告、资源供给
限制
- 不替代 IaC；不适合管理需要生命周期跟踪的长期 Twingate 对象
- 不凭训练数据记忆回答 schema 或 CLI 问题
- 两个同名“Twingate CLI”工具需先确认用户所指
- 部分仓库为 LLM 辅助参考示例，非受支持产品