docs: add Chinese TiDB Cloud CLI (tdc) Preview documentation

TOC-ai.md

@@ -7,10 +7,15 @@
 
 - [使用 Python 快速上手](/ai/quickstart-via-python.md)
 - [使用 SQL 快速上手](/ai/quickstart-via-sql.md)
+- TiDB Cloud CLI (tdc) (Preview)
+  - [概览](/ai/tdc/tdc-overview.md)
+  - [快速开始](/ai/tdc/tdc-quick-start.md)
 
 ## 基础概念
 
 - [向量搜索](/ai/concepts/vector-search-overview.md)
+- TiDB Cloud CLI (tdc) (Preview)
+  - [概念与架构](/ai/tdc/concepts/tdc-concepts-and-architecture.md)
 
 ## 使用指南
 
@@ -30,6 +35,14 @@
   - [Join 查询](/ai/guides/join-queries.md)
   - [Raw SQL 查询](/ai/guides/raw-queries.md)
   - [事务](/ai/guides/transactions.md)
+- TiDB Cloud CLI (tdc) (Preview)
+  - [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md)
+  - [组织](/ai/tdc/guides/tdc-organization.md)
+  - [Starter 数据库](/ai/tdc/guides/tdc-starter-database.md)
+  - [文件系统](/ai/tdc/guides/tdc-filesystem.md)
+  - [文件系统 Git](/ai/tdc/guides/tdc-filesystem-git.md)
+  - [文件系统 Journal](/ai/tdc/guides/tdc-filesystem-journal.md)
+  - [文件系统 Vault](/ai/tdc/guides/tdc-filesystem-vault.md)
 
 ## 代码示例
 
@@ -44,6 +57,14 @@
   - [RAG 应用](/ai/examples/rag-with-pytidb.md)
   - [对话记忆](/ai/examples/memory-with-pytidb.md)
   - [文本转 SQL](/ai/examples/text2sql-with-pytidb.md)
+- TiDB Cloud CLI (tdc) (Preview)
+  - [Agent 沙箱](/ai/tdc/examples/tdc-agent-sandbox-example.md)
+  - [日常工作流](/ai/tdc/examples/tdc-daily-workflow-example.md)
+  - [使用不同角色查询 SQL](/ai/tdc/examples/tdc-query-sql-with-roles-example.md)
+  - [在多台机器间共享文件系统](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md)
+  - [为 Agent 准备 Git 工作区](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md)
+  - [记录 Agent 工作流](/ai/tdc/examples/tdc-journal-agent-workflow-example.md)
+  - [向 Agent 委派 Vault 密钥](/ai/tdc/examples/tdc-vault-agent-secrets-example.md)
 
 ## 集成指南
 
@@ -84,3 +105,8 @@
 - [性能调优](/ai/reference/vector-search-improve-performance.md)
 - [限制](/ai/reference/vector-search-limitations.md)
 - [更新记录](/ai/reference/vector-search-changelogs.md)
+- TiDB Cloud CLI (tdc) (Preview)
+  - [CLI 参考](/ai/tdc/reference/tdc-cli-reference.md)
+  - [配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md)
+  - [区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md)
+  - [故障排查](/ai/tdc/reference/tdc-troubleshooting.md)

ai/_index.md

@@ -16,13 +16,21 @@ TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文
 | [使用 Python 快速上手](/ai/quickstart-via-python.md) | 使用 Python 在几分钟内构建你的第一个基于 TiDB 的 AI 应用。 |
 | [使用 SQL 快速上手](/ai/quickstart-via-sql.md) | 使用 SQL 快速开始向量搜索。 |
 
+### TiDB Cloud CLI (tdc) (Preview)
+
+| 文档 | 描述 |
+| --- | --- |
+| [tdc 概览](/ai/tdc/tdc-overview.md) | 了解 tdc 管理的资源，以及它如何使用随附的文件系统 companion。 |
+| [快速开始使用 tdc](/ai/tdc/tdc-quick-start.md) | 安装并配置 tdc，然后完成第一次数据库或文件系统操作。 |
+
 ## 基础概念
 
 了解 TiDB AI 搜索的基础概念。
 
 | 文档 | 描述 |
 | --- | --- |
 | [向量搜索](/ai/concepts/vector-search-overview.md) | 向量搜索的全面概述，包括概念、工作原理和应用场景。 |
+| [tdc 概念与架构 (Preview)](/ai/tdc/concepts/tdc-concepts-and-architecture.md) | 了解 profile、地域、凭证、SQL 角色、文件系统以及 Drive9 companion 边界。 |
 
 ## 使用指南
 
@@ -39,6 +47,18 @@ TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文
 | [Auto Embedding（自动生成向量）](/ai/guides/auto-embedding.md) | 数据插入时自动生成嵌入向量。 |
 | [过滤](/ai/guides/filtering.md) | 通过元信息条件过滤搜索结果。 |
 
+### TiDB Cloud CLI (tdc) (Preview)
+
+| 文档 | 描述 |
+| --- | --- |
+| [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md) | 安装发布版二进制文件、配置 profile、更新和卸载 tdc。 |
+| [组织](/ai/tdc/guides/tdc-organization.md) | 列出项目并了解虚拟项目的选择方式。 |
+| [Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) | 管理集群、分支、SQL 用户、连接字符串以及 SQL 执行。 |
+| [文件系统](/ai/tdc/guides/tdc-filesystem.md) | 管理文件系统资源、数据、layer、打包以及 FUSE 或 WebDAV 挂载。 |
+| [文件系统 Git](/ai/tdc/guides/tdc-filesystem-git.md) | 克隆、hydrate 并管理关联的 Git worktree。 |
+| [文件系统 Journal](/ai/tdc/guides/tdc-filesystem-journal.md) | 记录、搜索并验证仅追加的工作流事件。 |
+| [文件系统 Vault](/ai/tdc/guides/tdc-filesystem-vault.md) | 存储密钥、委派访问、审计、注入并挂载只读 Vault。 |
+
 ## 代码示例
 
 完整代码示例和演示，展示 TiDB 的 AI 能力。
@@ -52,6 +72,18 @@ TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文
 | [对话记忆](/ai/examples/memory-with-pytidb.md) | 为 AI agent 和聊天机器人提供持久 memory。 |
 | [文本转 SQL](/ai/examples/text2sql-with-pytidb.md) | 将自然语言转换为 SQL 查询。 |
 
+### TiDB Cloud CLI (tdc) (Preview)
+
+| 文档 | 描述 |
+| --- | --- |
+| [Agent 沙箱](/ai/tdc/examples/tdc-agent-sandbox-example.md) | 在不提供 TiDB Cloud API 密钥的情况下，让干净的沙箱访问文件系统。 |
+| [日常工作流](/ai/tdc/examples/tdc-daily-workflow-example.md) | 按常规运维流程管理一个 Starter 集群和文件系统。 |
+| [使用不同角色查询 SQL](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) | 显式使用只读、读写和管理员 SQL 角色。 |
+| [在多台机器间共享文件系统](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) | 安全传递 owner token，并验证多台机器间的数据可见性。 |
+| [为 Agent 准备 Git 工作区](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) | 准备已挂载的 Git 工作区和隔离的关联 worktree。 |
+| [记录 Agent 工作流](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) | 记录结构化事件并验证其哈希链。 |
+| [向 Agent 委派 Vault 密钥](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) | 向 Agent 临时授予一个密钥字段的访问权限。 |
+
 ## 集成指南
 
 将 TiDB 集成到主流 AI framework、嵌入提供商和开发工具中。
@@ -75,3 +107,12 @@ TiDB AI 与向量搜索特性的技术参考文档。
 | [向量搜索索引](/ai/reference/vector-search-index.md) | 创建和管理向量索引以提升性能。 |
 | [性能调优](/ai/reference/vector-search-improve-performance.md) | 优化向量搜索性能。 |
 | [限制](/ai/reference/vector-search-limitations.md) | 当前的限制与约束。 |
+
+### TiDB Cloud CLI (tdc) (Preview)
+
+| 文档 | 描述 |
+| --- | --- |
+| [CLI 参考](/ai/tdc/reference/tdc-cli-reference.md) | 全局参数、输出、查询、dry run、帮助、错误和别名。 |
+| [配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profile、优先级、本地状态、凭证、挂载定位文件和日志。 |
+| [区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | 部署区域、认证边界、平台、持久性和预览阶段限制。 |
+| [故障排查](/ai/tdc/reference/tdc-troubleshooting.md) | 排查认证、配额、SQL、companion、文件系统选择和挂载故障。 |

ai/tdc/concepts/tdc-concepts-and-architecture.md

@@ -0,0 +1,129 @@
+---
+title: tdc 概念与架构
+summary: 了解 tdc profile、region、凭证、SQL 角色、文件系统资源、本地状态和内置的 Drive9 companion。
+---
+
+# tdc 概念与架构
+
+本文介绍使用 tdc 管理 TiDB Cloud Starter 和 TiDB Cloud 文件系统所需的核心概念。
+
+> **注意：**
+>
+> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。
+
+## 命令模型
+
+tdc 使用 service 名词和显式 operation 名称：
+
+```text
+tdc db create-db-cluster
+tdc fs copy-file
+tdc fs-git clone-git-workspace
+```
+
+命令树最多两级。完整且清晰的命令与参数名称，让日志和 Agent 生成的命令更容易理解。除 `tdc configure` 外，其他命令均不交互。
+
+结构化命令默认返回 JSON。使用 `--output text` 获得面向终端的输出，使用 `--query` 进行 JMESPath 投影。
+
+## Profile 与 region
+
+Profile 是包含 TiDB Cloud 部署区域、默认 virtual project 和凭证的本地命名空间。默认 profile 名为 `default`，使用 `--profile` 选择其他 profile。
+
+tdc 使用一个 canonical region code 表示 placement：
+
+```text
+aws-us-east-1
+aws-ap-southeast-1
+ali-ap-southeast-1
+```
+
+前缀表示云服务提供商。全局 `--region` 可为单次命令覆盖 `TDC_REGION_CODE` 和 profile 中的 region，但不会修改已保存的配置。
+
+执行 `tdc configure` 时，tdc 会调用 organization API，并要求 API key 恰好能访问一个 `type = "tidbx_virtual"` 的 project。该 project ID 会成为创建 Starter 集群时的默认值。
+
+## 凭证边界
+
+tdc 为不同安全边界使用不同凭证：
+
+| 凭证 | 用途 | 存储位置 |
+| --- | --- | --- |
+| TiDB Cloud API public/private key | Organization、Starter control plane、文件系统创建与删除 | `~/.tdc/credentials` |
+| DB SQL 用户名/密码 | 访问一个 Starter 集群的 SQL | `~/.tdc/db_users/<cluster-id>/credentials` |
+| 文件系统 owner token | 文件系统数据面、挂载、Git、Journal 和 owner Vault 操作 | `~/.tdc/fs_resources/` 下的每资源凭证或 `TDC_FS_TOKEN` |
+| 委派 Vault token | 对指定 secret 字段的有限访问 | `TDC_VAULT_TOKEN` 或显式命令输入 |
+
+TiDB Cloud API key 不会被复用为 SQL 密码或文件系统 token。
+
+## SQL 角色
+
+`tdc db create-db-sql-users` 为集群创建或修复三个稳定用户：
+
+- `read_only`：不能修改数据的查询；
+- `read_write`：常规应用与 Agent 工作；
+- `admin`：DDL 和权限管理。
+
+使用 `--read-only`、`--read-write` 或 `--admin` 显式选择角色。不提供角色 flag 时，默认使用 read-write。
+
+## 一个 profile 管理多个文件系统
+
+一个 profile 可以注册多个文件系统资源。每个资源拥有独立的配置和凭证文件。选择顺序如下：
+
+1. `--file-system-name`；
+2. `TDC_FS_FILE_SYSTEM_NAME`；
+3. profile 的默认文件系统；
+4. 只有一个已注册文件系统时，选择该资源。
+
+如果存在多个资源但没有选择，tdc 会报错而不是猜测。使用 `tdc fs set-default-file-system` 设置默认资源。
+
+## 无配置 sandbox 访问
+
+全新的 Agent 沙箱不需要运行 `tdc configure`，也不需要 TiDB Cloud API key。只需提供：
+
+```bash
+export TDC_FS_TOKEN="<owner-token>"
+export TDC_REGION_CODE="aws-us-east-1"
+export TDC_FS_FILE_SYSTEM_NAME="workspace"
+```
+
+tdc 会在内存中将这些值解析为 profile 命名空间，不会写入 `[env]` profile，也不会持久化 token。
+
+## 本地状态
+
+tdc 管理的所有状态都位于 `~/.tdc/`：
+
+| 路径 | 内容 |
+| --- | --- |
+| `config` | 非敏感 profile、默认 project 和日志设置 |
+| `credentials` | TiDB Cloud API key |
+| `fs_resources/` | 按 profile 和文件系统隔离的元数据与 owner 凭证 |
+| `db_users/` | 集群级 SQL 凭证 |
+| `mounts/` | 后台挂载的非敏感定位信息 |
+| `logs/tdc.jsonl` | 已脱敏的本地 operation log |
+| `bin/` | 已安装的 `tdc` 和 `tdc-drive9` |
+
+Operation logging 是本地日志，不是 telemetry。设置 `TDC_LOGGING=off` 可为单个进程关闭。
+
+## tdc 与 Drive9 companion
+
+tdc 将 [Drive9](https://github.com/mem9-ai/drive9) 安装为内部名称 `tdc-drive9`。
+
+tdc 负责：
+
+- profile、凭证、region 和文件系统选择；
+- TiDB Cloud control-plane 调用；
+- JSON/text 输出、查询、错误和本地日志；
+- 将 tdc 命令转换为 companion 调用。
+
+Companion 负责：
+
+- 文件系统读写、元数据、链接、搜索和 layer；
+- FUSE/WebDAV 挂载进程、缓存、drain 和 unmount；
+- pack/unpack、Git workspace、Journal 和 Vault 语义。
+
+后台挂载会留下长期运行的 `tdc-drive9 mount --foreground` 进程。`tdc fs drain-file-system` 要求该进程刷出待处理的 FUSE 工作，`tdc fs unmount-file-system` 停止挂载。不要在仍有未刷出的写入或需要保留的本地 overlay 数据时终止机器。
+
+## 后续步骤
+
+- [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md)
+- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md)
+- [tdc 区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md)

ai/tdc/examples/tdc-agent-sandbox-example.md

@@ -0,0 +1,119 @@
+---
+title: 在 Agent Sandbox 中使用 TiDB Cloud 文件系统
+summary: 在可信机器上创建文件系统，并让全新的 Agent 沙箱在没有 TiDB Cloud API key 的情况下访问。
+---
+
+# 在 Agent Sandbox 中使用 TiDB Cloud 文件系统
+
+本示例让临时 Coding Agent 获得持久工作区，而不需要将用户完整的 tdc 配置复制到沙箱中。
+
+> **注意：**
+>
+> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。
+
+## Agent 面临的问题
+
+Coding Agent 通常运行在全新、短生命周期的沙箱中。沙箱被替换后，本地磁盘随之消失，但 Agent 仍然需要之前生成的产物、仓库状态以及其他 worker 写入的文件。重复构建这些状态会浪费任务时间，而复制 `~/.tdc/` 或注入 TiDB Cloud API key，又会让沙箱获得并不需要的控制面权限。
+
+## 本地存储和完整云凭证为什么不够
+
+沙箱本地目录速度快，但既不持久也不能共享。通用对象存储 API 需要应用自行实现上传和下载逻辑，无法直接支持普通文件操作。给每个沙箱提供用户的完整云凭证虽然能够访问资源，却扩大了安全边界。
+
+## tdc 如何改变工作流
+
+可信机器只需创建一次文件系统。沙箱仅接收文件系统 owner token、region code 和文件系统名称，无需运行 `tdc configure`，即可使用 data plane、挂载、Git、Journal 和 Vault。Agent 只需要访问特定 secret 时，应使用委派的 Vault token，而不是 owner token。
+
+## 前置条件
+
+- 在可信机器上安装并配置 tdc。
+- 在 sandbox 中安装 tdc。Release installer 包含 `tdc-drive9`。
+- 使用 secret manager 或加密的 sandbox input 传递 token。
+
+## 第 1 步：在可信机器上创建文件系统
+
+```bash
+export TDC_FS_TOKEN="$(tdc fs create-file-system \
+  --file-system-name agent-sandbox \
+  --wait \
+  --query fs_token \
+  --output text)"
+```
+
+记录该 profile 使用的 canonical region code，例如 `aws-us-east-1`。不要输出 token。
+
+## 第 2 步：注入最小 sandbox 环境
+
+通过 sandbox secret/environment 机制配置：
+
+```bash
+TDC_FS_TOKEN=<owner-token>
+TDC_REGION_CODE=aws-us-east-1
+TDC_FS_FILE_SYSTEM_NAME=agent-sandbox
+```
+
+Sandbox 不需要 `TDC_PUBLIC_KEY`、`TDC_PRIVATE_KEY`、`tdc configure`，也不需要从 `~/.tdc/` 复制文件。
+
+## 第 3 步：验证直接访问
+
+在 sandbox 中：
+
+```bash
+printf 'sandbox ready\n' | tdc fs copy-file \
+  --from-stdin \
+  --to-remote /sandbox/status.txt
+
+tdc fs read-file --path /sandbox/status.txt
+```
+
+预期输出：
+
+```text
+sandbox ready
+```
+
+## 第 4 步：可选挂载文件系统
+
+在 Linux FUSE 环境中：
+
+```bash
+mkdir -p /workspace
+tdc fs mount-file-system \
+  --file-system-name agent-sandbox \
+  --mount-path /workspace \
+  --driver fuse
+
+cat /workspace/sandbox/status.txt
+```
+
+在 macOS 上省略 `--driver fuse`，使用默认 WebDAV。只有安装 macFUSE 后才使用 FUSE。
+
+挂载后，可以使用同一 FS 环境运行 `tdc fs-git`、`tdc fs-journal` 和 owner 授权的 `tdc fs-vault`。Agent 只需要指定 secret field 时，应提供 delegated `TDC_VAULT_TOKEN`，而不是 owner token。
+
+## 清理
+
+停止 writer。对于 FUSE：
+
+```bash
+tdc fs drain-file-system --mount-path /workspace
+tdc fs unmount-file-system --mount-path /workspace
+```
+
+对于 WebDAV，关闭文件并只运行 unmount。回到可信机器：
+
+```bash
+tdc fs delete-file-system \
+  --file-system-name agent-sandbox \
+  --confirm-file-system-name agent-sandbox
+```
+
+## 安全说明
+
+- 将 `TDC_FS_TOKEN` 视为 owner credential。
+- 不要将其写入镜像、代码仓库、命令行参数或操作日志。
+- 删除 sandbox 不会删除远端文件系统。
+- 如果 pending write 必须持久化，请在删除 FUSE sandbox 前执行 drain。
+
+## 后续步骤
+
+- [使用 tdc 管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md)
+- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md)