TiDB Cloud Auth · Agent Skill User Guide / 用户指南

iWhat this skill does这个技能能做什么

This is an agent skill: you talk to the agent in plain language, and it runs a bundled, safety-checked CLI to configure TiDB Cloud Auth for you — no need to memorize any commands.

这是一个智能体技能（agent skill）：你用自然语言与智能体对话，它会调用内置且带安全校验的命令行工具，替你完成 TiDB Cloud Auth 的配置——你无需记忆任何命令。

It covers the full lifecycle of building an authenticated, database-backed app on TiDB Cloud: creating a project, binding your own TiDB database, issuing keys, creating and publishing tables, writing access policies, wiring up Google / GitHub / OIDC sign-in and email, managing users, generating TypeScript types, and scaffolding a ready-to-run frontend.

它覆盖了在 TiDB Cloud 上构建「带鉴权 + 数据库」应用的完整流程：创建项目、绑定你自己的 TiDB 数据库、签发密钥、创建并发布数据表、编写访问策略、接入 Google / GitHub / OIDC 登录与邮件、管理用户、生成 TypeScript 类型，以及脚手架生成一个可直接运行的前端应用。

🩺

Diagnose & Docs

诊断与文档

Check credentials, refresh API references from the live contract.

检查凭据、从实时契约刷新 API 参考文档。

📦

Project & Database

项目与数据库

Create a project and bind your own TiDB database.

创建项目并绑定你自己的 TiDB 数据库。

🔑

Keys

密钥

Browser client keys and private machine service keys.

浏览器客户端密钥与私有机器服务密钥。

🗄️

Tables

数据表

Create tables via migrations and publish them for the Data API.

通过迁移创建表，并发布给 Data API 使用。

🛡️

Policies

访问策略

Write and simulate row/table access rules.

编写并模拟行级 / 表级访问规则。

🔐

Auth providers

登录方式

Google, GitHub, OIDC and SMTP email flows.

Google、GitHub、OIDC 及 SMTP 邮件流程。

👤

User management

用户管理

List, create, ban, reset passwords, revoke sessions.

列出、创建、封禁、重置密码、吊销会话。

⚛️

Types & Frontend

类型与前端

Generate DB types and a Vite + auth-js starter app.

生成数据库类型与 Vite + auth-js 起步应用。

≡Contents目录

1Before you start开始之前 2How to talk to the agent如何与智能体对话 3The golden path标准配置流程 4Diagnose & docs诊断与文档 5Project & database项目与数据库 6Keys密钥 7Tables数据表 8Policies访问策略 9Auth providers & email登录方式与邮件 10User management用户管理 11Types & frontend类型与前端 12Other AI agents其他 AI 智能体 13Safety & secrets安全与密钥 14Troubleshooting故障排查 15Production-style testing生产式验收测试

1Before you start开始之前

Put all TiDB Cloud Auth configuration in exactly one owner-only .tidbcloud-auth/<app>.env file in your project. The filename is your choice. The agent's CLI discovers and parses it automatically; do not source it or paste secrets into chat.

把全部 TiDB Cloud Auth 配置写入项目内唯一一个、仅属主可读写的 .tidbcloud-auth/<app>.env 文件；文件名由你决定。智能体 CLI 会自动发现并解析它；不要执行 source，也不要把密钥粘贴到对话里。

Existing project (normal configuration)

已有项目（日常配置）

TIDBCLOUD_AUTH_ADMIN_URL=...
TIDBCLOUD_AUTH_DATA_URL=...
TIDBCLOUD_AUTH_ORG_ID=...
TIDBCLOUD_AUTH_PROJECT_ID=...
TIDBCLOUD_AUTH_PROJECT_ADMIN_PUBLIC_KEY=...
TIDBCLOUD_AUTH_PROJECT_ADMIN_PRIVATE_KEY=...
TIDBCLOUD_AUTH_APP_ORIGIN=...

Creating a new project (additional credentials)

创建新项目（额外凭据）

TIDBCLOUD_AUTH_OWNER_USER_ID=...
TIDBCLOUD_AUTH_ORG_ADMIN_PUBLIC_KEY=...
TIDBCLOUD_AUTH_ORG_ADMIN_PRIVATE_KEY=...

Org Admin credentials are needed only for project setup. After setup, use the newly issued project-scoped Admin key for work inside that project.

Org Admin 凭据只在执行 project setup 时需要。项目创建完成后，项目内的操作应使用新签发的项目级 Admin 密钥。

Public application key

公开应用密钥

TIDBCLOUD_AUTH_CLIENT_KEY=...

The client key is a publishable browser/Data API key, not an Admin credential. It can be supplied here, or saved automatically into setup state by key client create or project bootstrap.

客户端密钥是可公开的浏览器 / Data API 密钥，不是 Admin 凭据。你可以在这里提供，也可以由 key client create 或 project bootstrap 自动保存到配置状态。

Secrets supplied only at execute time (never printed)

仅在执行时读取的密钥（绝不打印）

TIDBCLOUD_AUTH_DB_DSN=...          # your TiDB DSN for binding create绑定数据库时使用的 TiDB DSN
GOOGLE_OAUTH_CLIENT_SECRET=...     # or GITHUB_/<PROVIDER>_OAUTH_CLIENT_SECRET或 GITHUB_/<提供方>_OAUTH_CLIENT_SECRET
TIDBCLOUD_AUTH_SMTP_PASSWORD=...   # or _SMTP_API_TOKEN for email或用于邮件的 _SMTP_API_TOKEN

TIDBCLOUD_AUTH_DB_DSN accepts either the TiDB Cloud console URL form (mysql://user:password@host:4000/db) or the Go MySQL driver form (user:password@tcp(host:4000)/db). Keep the full value in the environment—never paste it into chat.

TIDBCLOUD_AUTH_DB_DSN 支持 TiDB Cloud 控制台给出的 URL 格式（mysql://user:password@host:4000/db），也支持 Go MySQL 驱动格式（user:password@tcp(host:4000)/db）。完整值只放在环境变量中，切勿粘贴到对话里。

The agent confirms four inputs before provisioning: task/project, whether a BYO TiDB DSN is available, required auth providers, and browser origins/redirect URIs. It never asks you to paste the DSN or another secret. 开始开通前，智能体会一次确认四类信息：任务/项目、是否已有 BYO TiDB DSN、需要的登录方式，以及浏览器来源/回调地址。它不会要求你粘贴 DSN 或其他密钥。

Node.js required. The skill runs on Node (built-ins only). Check with node --version. You do not run these commands yourself — the agent does — but Node must be installed. 需要 Node.js。 该技能基于 Node 运行（仅使用内置模块）。用 node --version 检查。你不必亲自敲这些命令——由智能体执行——但机器上必须安装 Node。

2How to talk to the agent如何与智能体对话

Just describe your goal in everyday language. The agent picks the right command, shows you the exact Admin API request it plans to send, and waits for your confirmation before touching anything real.

用日常语言描述你的目标即可。智能体会选择正确的命令，先展示它准备发送的 Admin API 请求内容，并在真正执行任何变更前等待你确认。

Dry-run by default. Every mutating command is a preview until you approve it. The agent only adds --yes (to execute) after you review the generated request body. That's why many examples below mention a "preview first, then confirm" flow. 默认只预演（dry-run）。 每一个会产生变更的命令，在你批准前都只是预览。智能体只有在你审阅了生成的请求内容后，才会加上 --yes 去真正执行。因此下文很多示例都是「先预览、再确认」的流程。

In the examples below, the blue quoted lines are things you say to the agent. The grey node … lines show what the agent runs under the hood — you never have to type them.

在下文示例中，蓝色引号内的句子是你对智能体说的话。灰色的 node … 行展示智能体在底层实际执行的命令——你永远无需亲自输入。

3The golden path: from zero to a running app标准流程：从零到可运行的应用

For a brand-new app, this is the recommended order. You can say all of it at once, or go step by step. Results from earlier steps (URLs, binding ID, client key) are saved and automatically threaded into later steps.

对于一个全新的应用，推荐按以下顺序进行。你可以一次性说出全部需求，也可以逐步进行。前面步骤的结果（地址、binding ID、客户端密钥）会被保存，并自动传递到后续步骤中。

🗣 One-shot prompt一句话完成

Set up a new TiDB Cloud Auth project called "todo-app", bind my TiDB database, create a browser client key, add Google login, create a todos table with id and title, publish it, add a read policy, then scaffold a frontend.

帮我新建一个叫 “todo-app” 的 TiDB Cloud Auth 项目，绑定我的 TiDB 数据库，创建一个浏览器客户端密钥，加上 Google 登录，创建一张包含 id 和 title 的 todos 表并发布，添加一个读取策略，最后生成一个前端应用。

Check project Admin key scopes检查项目 Admin 密钥权限scopes preflight
Project setup创建项目project setup --name todo-app
Bootstrap an existing project when readiness requests it当就绪检查要求时引导已有项目project bootstrap --profile auth_ready
Bind your TiDB database (BYO)绑定你自己的 TiDB 数据库binding create --name main --bootstrap-profile auth_ready
Create a publishable browser client key创建可公开的浏览器客户端密钥key client create --name web --allowed-origins https://app.example
Configure auth providers & email配置登录方式与邮件auth provider / oauth google / auth mail-provider
Create the table创建数据表table create --name todos --columns id:bigint,owner_id:varchar(128),title:varchar(255) --apply
Activate and refresh the schema激活并刷新结构schema version create → schema refresh → schema source
Publish with explicit row isolation以明确的行隔离模式发布table publish --spec publish.json
Add access policies添加访问策略policy upsert --resource todos --action table.read
Scaffold the frontend app生成前端应用frontend scaffold --output ./app --name todo-app
Generate TypeScript types and verify readiness生成 TypeScript 类型并验证就绪状态typegen → project readiness → SDK smoke test

4Diagnose & docs诊断与文档

Start here if anything feels off. doctor validates the single project env file, discovers the Admin contract, checks scopes and project readiness, then reports a machine-readable phase, blockers, safe missing items, and next command. docs regenerates the endpoint references.

如果感觉哪里不对，先从这里开始。doctor 会校验唯一的项目 env 文件、发现 Admin 契约、检查权限与项目就绪状态，并返回机器可读的阶段、阻塞项、安全的缺失项和下一条命令。docs 用于重新生成接口参考文档。

🗣 Check my setup检查我的环境

Check whether my TiDB Cloud Auth credentials are configured correctly.

检查一下我的 TiDB Cloud Auth 凭据是否配置正确。

→ agent runs智能体执行

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" doctor

🗣 Check Admin key scopes检查 Admin 密钥权限

Before provisioning, check whether my project Admin key has every required scope.

开始开通前，检查我的项目 Admin 密钥是否具备全部所需权限。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" scopes preflight

The command reads the key's granted scopes from the live project and lists the exact missing scopes. A key cannot grant scopes to itself; add them in the TiDB Cloud Auth console, keep role = owner, then run the check again.

该命令会从实时项目读取密钥已有的权限，并准确列出缺少项。密钥不能给自己增加权限；请在 TiDB Cloud Auth 控制台中补齐，保持 role = owner，然后重新检查。

🗣 Refresh the API docs刷新 API 文档

Regenerate the endpoint reference docs and tell me if coverage is complete.

重新生成接口参考文档，并告诉我覆盖是否完整。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" docs generate
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" docs check

5Project & database项目与数据库

Create a project, or formally bootstrap an existing project when readiness reports missing Auth/JWT configuration, then bind your own ("BYO") TiDB database. You can validate, list, or recover a binding at any time.

创建项目；如果已有项目的就绪检查报告缺少 Auth/JWT 配置，则先通过正式接口完成 bootstrap；然后绑定你自己的（BYO）TiDB 数据库。你可以随时校验、列出或恢复某个绑定。

🗣 Create a project创建项目 dry-run

Create a new project named "todo-app". Show me the request first.

创建一个名为 “todo-app” 的新项目，先把请求内容给我看。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" project setup --name todo-app --owner-user-id USER_ID          # preview预览
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" project setup --name todo-app --owner-user-id USER_ID --reveal-to .tidbcloud-auth/project-admin.json --yes    # after you confirm你确认后

Execution creates a project-scoped Admin key and writes its one-time private key only to the pre-reserved owner-only reveal file. The workflow then authenticates with that key and reads back the project and key metadata.

执行时会创建项目级 Admin 密钥，其一次性私钥只写入预先独占、仅属主可读写的 reveal 文件；随后工作流会使用新密钥回读项目和密钥元数据。

🗣 Bootstrap an existing project引导已有项目 dry-run

My project already exists. Complete the formal Auth-ready bootstrap and safely save any first-return keys.

我的项目已经存在。通过正式接口完成 Auth-ready bootstrap，并安全保存首次返回的密钥。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" project bootstrap --profile auth_ready --reason "prepare application" --reveal-to .tidbcloud-auth/bootstrap-secrets.json          # preview预览
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" project bootstrap --profile auth_ready --reason "prepare application" --reveal-to .tidbcloud-auth/bootstrap-secrets.json --yes    # after review检查后执行

The reveal file is reserved with owner-only permissions before mutation. Only the publishable client key is copied to setup state; the service key never appears in state or stdout. A lost response fails closed after readiness readback.

执行变更前会先独占创建仅属主可访问的 reveal 文件。只有可公开的 client key 会写入 setup state；service key 绝不会进入 state 或终端输出。响应丢失时会在回读 readiness 后安全停止。

🗣 Bind my database绑定我的数据库

Preview my DSN target, then bind my TiDB database as "main" and make it Data-API ready. My DSN is in the environment.

先预览 DSN 的目标，再把我的 TiDB 数据库绑定为 “main” 并让它可供 Data API 使用。我的 DSN 已放在环境变量里。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding normalize-dsn
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding create --name main --bootstrap-profile auth_ready          # preview预览
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding create --name main --bootstrap-profile auth_ready --yes    # after you confirm你确认后
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding get
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding validate --yes

--name main is a logical name; the CLI derives a stable physical ID containing the project identity, so another tenant may also use “main.” normalize-dsn shows only the redacted target. Use auth_ready for Auth + Data apps and data_api_ready only for Data-only apps.

--name main 是逻辑名称；CLI 会派生包含项目身份的稳定物理 ID，因此另一个租户也能使用“main”。normalize-dsn 只显示脱敏目标。Auth + Data 应用使用 auth_ready，仅 Data 应用才使用 data_api_ready。

🗣 Verify a binding校验绑定

Validate the "main" binding and list all my bindings.

校验 “main” 绑定，并列出我所有的绑定。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding get
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding validate --yes
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" binding list

6Keys密钥

Key type	Where it's used	Safe in browser?
Client key	Frontend / browser apps	✔ Yes — scoped & publishable
Service key	Server / backend runtime	✘ No — secret, server-only
密钥类型	用途	可用于浏览器？
客户端密钥	前端 / 浏览器应用	✔ 可以——作用域受限且可公开
服务密钥	服务端 / 后端运行时	✘ 不可——机密，仅限服务端

🗣 Browser client key浏览器客户端密钥

Create a publishable client key named "web" allowed from https://app.example.

创建一个名为 “web”、允许来源为 https://app.example 的可公开客户端密钥。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" key client create --name web --allowed-origins https://app.example --yes

The created key is saved into setup state, so a later frontend scaffold wires it in automatically.

生成的密钥会被保存到配置状态中，随后 frontend scaffold 会自动接入它。

🗣 Private machine service key私有机器服务密钥

Create a private machine service key named "private-ops" and save its secret to service-key.json. Do not use it with the public Data API.

创建一个名为 “private-ops” 的私有机器服务密钥，把密钥保存到 service-key.json。不要把它用于公开 Data API。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" key service create --name private-ops --reveal-to service-key.json --yes

The secret is shown only once via --reveal-to FILE (written with restricted permissions) and is redacted from normal output. Keep that file out of git and the browser. 该密钥仅通过 --reveal-to FILE 显示一次（以受限权限写入文件），在普通输出中会被脱敏。请务必让该文件远离 git 与浏览器。

🗣 Rotate a key轮换密钥

Rotate client key KEY123 but keep the old one valid for an hour.

轮换客户端密钥 KEY123，但让旧密钥再保留一小时有效。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" key client rotate --key-id KEY123 --retire-after-seconds 3600 --yes

7Tables数据表

Tables always go through Admin workflows. The public Data API is for CRUD only — never for DDL, raw SQL, or schema changes. Creating and publishing tables must use the commands below. 数据表的变更必须走 Admin 工作流。 公开的 Data API 只用于增删改查（CRUD），绝不用于 DDL、原始 SQL 或结构变更。创建与发布表必须使用下面的命令。

🗣 Create a table创建数据表

Create a todos table with a bigint id and a varchar(255) title, and apply the migration.

创建一张 todos 表，包含 bigint 类型的 id 和 varchar(255) 类型的 title，并执行该迁移。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" table create --name todos \
  --columns id:bigint,owner_id:varchar(128),title:varchar(255) --apply --yes

--yes submits the request — without it you get a dry-run preview. With --yes alone the migration job is created but stops at review-only; add --apply to also review and apply it.

--yes 才会真正提交请求——不加它只得到预览。仅加 --yes 时，迁移任务会被创建但停在「仅审阅」阶段；再加 --apply 才会审阅并实际应用该迁移。

Target order: explicit --binding-id, then the spec's binding_id, then the value saved by binding create. --database is optional and only checks that the selected binding points to the expected database; it never selects the migration target.

目标选择顺序是：显式 --binding-id、规格文件中的 binding_id、最后是 binding create 保存的值。--database 只是可选的一致性检查，用来确认所选 binding 指向预期数据库；它绝不会选择迁移目标。

🗣 Publish a table发布数据表

Publish the todos table so the Data API can serve it, using publish.json.

用 publish.json 把 todos 表发布出去，让 Data API 能够访问它。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" schema version create --state active --yes
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" schema refresh --yes
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" schema source
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" table publish --spec publish.json --yes

The spec must explicitly choose exactly one isolation mode: row_security for user-owned rows or disable_row_security: true for deliberately shared data. A policy does not replace this choice.

规格必须明确选择且只选择一种隔离模式：用户私有行使用 row_security，有意共享的数据使用 disable_row_security: true。访问策略不能替代这一选择。

8Policies访问策略

Policies decide who can read or write which resource. Always simulate before you commit — it's non-mutating and shows you the effect.

策略决定谁可以读写哪些资源。提交前请务必先模拟（simulate）——它不会产生变更，并会展示实际效果。

🗣 Simulate, then apply先模拟，再应用

Simulate a read policy on todos, and if it looks right, add it.

在 todos 上模拟一个读取策略，如果没问题就添加它。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" policy simulate --resource todos --action table.read
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" policy upsert   --resource todos --action table.read --owner-column owner_id --yes

9Auth providers & email登录方式与邮件

Configure Google, GitHub, or generic OIDC sign-in, plus an SMTP mail provider for verification, recovery, and email-change flows. Client secrets are read from the environment at execute time — never typed into chat.

配置 Google、GitHub 或通用 OIDC 登录，以及用于邮箱验证、找回密码、变更邮箱等流程的 SMTP 邮件服务。客户端密钥在执行时从环境变量读取——绝不输入到对话中。

🗣 Google loginGoogle 登录

Add Google sign-in with client id GOOGLE_ID and callback https://app.example/callback.

添加 Google 登录，客户端 ID 为 GOOGLE_ID，回调地址为 https://app.example/callback。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" oauth google --client-id GOOGLE_ID \
  --redirect-uris https://app.example/callback --yes

🗣 GitHub loginGitHub 登录

Set up GitHub login with client id GH_ID and the same callback.

用客户端 ID GH_ID 和相同的回调地址配置 GitHub 登录。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" auth provider --provider github --client-id GH_ID \
  --redirect-uris https://app.example/callback --yes

🗣 Email (SMTP)邮件（SMTP）

Configure email sending from no-reply@app.example via smtp.example on port 587.

配置从 no-reply@app.example 发送邮件，使用 smtp.example 的 587 端口。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" auth mail-provider --from-email no-reply@app.example \
  --smtp-host smtp.example --smtp-port 587 --yes

🗣 Auth settings鉴权设置

Require email confirmation on signup, and show me the current auth settings.

要求注册时进行邮箱确认，并把当前的鉴权设置给我看。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" auth settings get
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" auth settings update --email-confirm-required true --yes

10User management用户管理

Full admin control over end users: list, inspect, create, ban/unban, enable/disable, reset passwords, and revoke sessions.

对终端用户的完整管理权限：列出、查看、创建、封禁 / 解封、启用 / 停用、重置密码，以及吊销会话。

🗣 Everyday user ops常见用户操作

List all users. Then ban user U42 until next Monday and revoke all their sessions.

列出所有用户。然后封禁用户 U42 直到下周一，并吊销他的所有会话。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" user list
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" user ban --user-id U42 --banned-until 2026-07-13T00:00:00Z --yes
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" user revoke-sessions --user-id U42 --yes

🗣 Password reset重置密码

Send a password reset for user U42 back to https://app.example/reset.

为用户 U42 发起密码重置，回调到 https://app.example/reset。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" user password-reset --user-id U42 \
  --redirect-uri https://app.example/reset --yes

A new user's password is read from TIDBCLOUD_AUTH_USER_PASSWORD at execute time.

新建用户的密码在执行时从 TIDBCLOUD_AUTH_USER_PASSWORD 读取。

11Types & frontend类型与前端

Scaffold the Vite + TypeScript starter first, then generate SDK-compatible Database types from the published schema. This fixed order prevents a template placeholder from replacing generated types. The starter supports password auth, one-time Google/GitHub OAuth callback handling, password recovery, email verification, and filtered CRUD against published tables.

先脚手架生成 Vite + TypeScript 起步应用，再从已发布 schema 生成与 SDK 兼容的 Database 类型。这个固定顺序可防止模板占位文件覆盖已生成类型。起步应用支持密码登录、Google/GitHub OAuth 单次回调处理、找回密码、邮箱验证，以及针对已发布表的带过滤 CRUD。

🗣 Scaffold the app生成应用

Scaffold a frontend app named todo-app into ./app using my schema.

用我的 schema，把一个名为 todo-app 的前端应用脚手架生成到 ./app。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" frontend scaffold --output ./app --name todo-app

🗣 Generate types after scaffold脚手架后生成类型

Generate TypeScript database types from schema.json into app/src/database.types.ts.

从 schema.json 生成 TypeScript 数据库类型，输出到 app/src/database.types.ts。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" typegen --schema-file schema.json --output app/src/database.types.ts

Omit --schema-file to pull the schema live from the Data API /schema endpoint instead — that path uses TIDBCLOUD_AUTH_DATA_URL and the project client key.

省略 --schema-file 时，会改为从 Data API 的 /schema 接口实时拉取 schema——该方式使用 TIDBCLOUD_AUTH_DATA_URL 和项目客户端密钥。

SDK is bundled, no npm needed. Because @tidbcloud/auth-js isn't published to npm, the skill vendors a packed build into the app's vendor/ folder and pins a file: dependency — it installs offline. .env.example contains public placeholders only; actual public app settings go to an ignored owner-only .env.local. SDK 已内置，无需 npm。 由于 @tidbcloud/auth-js 尚未发布到 npm，技能会把打包好的构建物放入应用的 vendor/ 目录，并以 file: 形式固定依赖——可离线安装。.env.example 只含公开占位符；实际公开应用配置写入被 git 忽略、仅属主可读写的 .env.local。

12Using other AI agents配合其他 AI 智能体

This skill is agent-agnostic — everything runs through the Node CLI and plain-markdown references. Claude loads it natively. For other tools (OpenAI Codex, GitHub Copilot, Gemini CLI, Cursor), the agent can generate discovery adapters so they route to the same skill.

该技能与具体智能体无关——所有操作都通过 Node CLI 和纯 Markdown 参考文档完成。Claude 可原生加载它。对于其他工具（OpenAI Codex、GitHub Copilot、Gemini CLI、Cursor），智能体可以生成发现适配器，让它们都指向同一个技能。

🗣 Sync adapters同步适配器

Generate the agent adapter files so Codex, Copilot, Gemini and Cursor can find this skill.

生成智能体适配器文件，让 Codex、Copilot、Gemini 和 Cursor 都能找到这个技能。

→

node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" agents sync
node "<SKILL_DIR>/scripts/tidbcloud-auth.mjs" agents check   # verify they're up to date校验是否为最新

Generates AGENTS.md, .github/copilot-instructions.md, GEMINI.md, and .cursor/rules/…. These are generated — never edit them by hand.

会生成 AGENTS.md、.github/copilot-instructions.md、GEMINI.md 和 .cursor/rules/…。它们是自动生成的——请勿手动编辑。

13Safety & secrets安全与密钥

The skill is built to keep you safe by default. Keep these rules in mind:

该技能在设计上默认保护你的安全。请牢记以下几条规则：

Never paste secrets into chat. Admin private keys, service key secrets, OAuth client secrets, DSNs, bearer/refresh tokens, and user JWTs all come from environment variables — not prompts, frontend files, logs, or generated docs.
切勿把密钥粘贴到对话里。 Admin 私钥、服务密钥、OAuth 客户端密钥、DSN、bearer/refresh 令牌、用户 JWT 都从环境变量读取——不应出现在提示词、前端文件、日志或生成的文档中。
Mutations are dry-run first. Review the generated Admin API request body before you approve --yes.
变更操作默认先预演。 在你批准 --yes 前，先审阅生成的 Admin API 请求内容。
Client key vs. service key. Only client keys belong in the browser. Service keys are private machine credentials for supported internal/Ops workflows; the public Data API rejects them.
区分客户端密钥与服务密钥。 只有客户端密钥可放入浏览器；服务密钥仅用于受支持的内部/Ops 私有机器流程，公开 Data API 会拒绝它。
Data API is CRUD-only. No DDL, raw SQL, RPC, stored procedures, or schema changes through the public Data API — those go through Admin workflows.
Data API 只做增删改查。 公开 Data API 不允许 DDL、原始 SQL、RPC、存储过程或结构变更——这些都走 Admin 工作流。
Secrets are redacted. Even error output and logs are run through a redactor, and created service keys are shown only once via --reveal-to.
密钥会被脱敏。 即使是错误输出和日志也会经过脱敏处理，新建的服务密钥仅通过 --reveal-to 显示一次。

14Troubleshooting故障排查

Symptom	Try saying to the agent
Credentials seem missing or wrong	“Run doctor and tell me which env vars are missing.”
Admin request returns `admin_forbidden`	“Run scopes preflight and list the exact scopes I need to add in the console.”
Unsure which database a DSN targets	“Run binding normalize-dsn and show me the redacted host, database, and TLS state.”
An endpoint behaves unexpectedly	“Regenerate the docs and check the contract for this route.”
A published table isn't readable	“Simulate the read policy on this table and check the binding is valid.”
OAuth callback fails	“Re-check my GitHub provider config and redirect URIs.”
Frontend can't reach the API	“Verify the client key and Data URL in my .env against setup state.”
现象	可以这样对智能体说
凭据似乎缺失或不正确	「运行 doctor，告诉我缺少哪些环境变量。」
Admin 请求返回 `admin_forbidden`	「运行 scopes preflight，准确列出我需要在控制台补充的权限。」
不确定 DSN 指向哪个数据库	「运行 binding normalize-dsn，显示脱敏后的主机、数据库和 TLS 状态。」
某个接口行为异常	「重新生成文档，并检查这个路由的契约。」
已发布的表读取不到	「模拟这张表的读取策略，并检查绑定是否有效。」
OAuth 回调失败	「重新检查我的 GitHub 提供方配置和回调地址。」
前端连不上 API	「对照配置状态，校验我 .env 里的客户端密钥和 Data 地址。」

Deeper guidance lives in the skill's reference files: references/01-endpoint-index.md through 11-skill-feedback.md. Ask the agent to open the relevant one when you want the exact contract for an endpoint.

更深入的说明位于技能的参考文件中：references/01-endpoint-index.md 到 11-skill-feedback.md。当你需要某个接口的精确契约时，可以让智能体打开对应文件。

15Production-style application testing生产式应用验收测试

You can test the skill against a real deployed TiDB Cloud Auth service by asking the agent to build an isolated application, such as an e-commerce MVP. This exercises the real Admin, Auth, and Data API paths; it must not use mocks, raw SQL, manual database edits, or service keys on the public Data API.

你可以让智能体创建一个隔离应用（例如电商 MVP），对真实部署的 TiDB Cloud Auth 服务进行技能验收。该测试会走真实的 Admin、Auth 和 Data API 路径；不得使用 mock、原始 SQL、手工修改数据库，也不得用 service key 调用公开 Data API。

🗣 E-commerce acceptance test电商验收测试

Use the installed tidbcloud-auth skill to build a production-style e-commerce test app in ./ecom-app. Use an isolated project, create and publish products, orders, and order_items, configure password auth, generate SDK types, and verify two-user row isolation against the real AWS backend. Save redacted evidence.

使用已安装的 tidbcloud-auth 技能，在 ./ecom-app 创建生产式电商测试应用。使用隔离项目，创建并发布 products、orders 和 order_items，配置密码登录，生成 SDK 类型，并在真实 AWS 后端验证两个用户之间的行隔离。保存脱敏证据。

Required order

固定执行顺序

docs check → agents check → doctor → scopes preflight
Read back the project, binding, keys, providers, migrations, publications, and policies before mutation.变更前读取并核对项目、binding、密钥、provider、migration、publication 和 policy。
Create tables through reviewed migration jobs, activate the schema version, publish tables, then create and simulate least-privilege policies.通过已审核的 migration job 创建表，激活 schema version，发布表，再创建并模拟最小权限 policy。
Scaffold first, then generate types from the live published schema.先生成脚手架，再从真实已发布 schema 生成类型。
Run typecheck, production build, real Auth flows, Data API CRUD, cross-user isolation, negative key tests, and an idempotent readback rerun.运行类型检查、生产构建、真实 Auth 流程、Data API CRUD、跨用户隔离、非法密钥测试，以及幂等 readback 重跑。

Production-style is not the same as public production. Use an isolated project and disposable test users. Trusted production TLS is required before a public launch; if the AWS deployment uses staging certificates, record that limitation and test only in a controlled environment. Never paste the DSN or credentials into the prompt. 生产式测试不等于公网生产发布。请使用隔离项目和可删除的测试用户。公网发布前必须使用受信任的生产 TLS；如果 AWS 部署仍使用 staging 证书，应记录该限制，并只在受控环境测试。绝不要把 DSN 或凭据粘贴到 Prompt。

Success means evidence, not just a running page: two users can sign in, shared products are readable, each user can create and read only their own orders, forged owner IDs are denied, unpublished tables stay hidden, invalid client/service-key boundaries fail closed, secrets are absent from output, and a second dry run reuses the same project-scoped resources without duplicates.

成功必须有证据，不能只看页面能打开：两个用户可以登录；共享商品可读；每个用户只能创建和读取自己的订单；伪造 owner ID 被拒绝；未发布表不可见；非法 client key 与 service key 边界会安全失败；输出中没有秘密；第二次 dry-run 会复用同一组项目级资源且不产生重复项。