TiDB Agent 文档体系全解析：docs/agents/ 目录结构、测试执行手册与子系统导航索引

• 数据库
• 分布式数据库
• 后端
• OLAP

【免费下载链接】tidb

TiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.

项目地址：https://gitcode.com/GitHub_Trending/ti/tidb

点击查看免费下载

本文以docs/agents/目录的官方入口 docs/agents/README.md 为核心骨架，完整展开 TiDB 仓库中面向 AI Agent 的文档体系：目录分层规则、策略与操作文档的职责边界、可复制执行的测试命令手册（单元测试、failpoint、集成测试、RealTiKV）、子系统架构索引与组件级深度笔记的组织方式。读完后，你可以直接按文档中的命令模板在本地运行 TiDB 的各类测试，并理解仓库如何为 Agent 协作设计"策略在根、操作在docs/agents/、组件笔记按模块分目录"的三层结构。

一、Agent 文档体系的定位与目录布局

docs/agents/README.md 明确了该目录的唯一职责：它是 Agent 面向文档（agent-facing documentation）的单一顶层入口（"the single top-level home for agent-facing documentation"）。README 给出的布局（Layout）规则分为两层：

1. 跨领域（Cross-cutting）的运行手册和检查清单统一放在docs/agents/*.md顶层。当前包含：
   • docs/agents/testing-flow.md —— 测试执行命令手册（Unit/Integration/RealTiKV）；
   • docs/agents/architecture-index.md —— 子系统路径导航索引；
   • docs/agents/agents-review-guide.md —— 对 Agent 文档本身变更的评审指南；
   • docs/agents/notes-guide.md —— 组件笔记的放置与更新规则。
2. 组件专属（Component-specific）笔记放在docs/agents/<component>/子目录。当前仓库中已有四个组件目录：
   • docs/agents/ddl/：DDL 执行框架的深度笔记（9 个文件，从执行流、作业生命周期到 add-index、modify-column、分区 DDL 的逐篇深潜）；
   • docs/agents/dxf/：DXF（Distributed eXecution Framework，分布式执行框架）导航笔记；
   • docs/agents/executor/：执行器相关开发笔记（如 FULL OUTER JOIN 的分阶段实现记录）；
   • docs/agents/import-into/：IMPORT INTO 的冲突解决与清理排障笔记。

这种"顶层放横切 runbook、子目录放组件笔记"的分层方式，使得新增组件时只需在docs/agents/下开新文件夹，而不必改动任何横切文档。

二、职责边界：策略归 AGENTS.md，操作归 docs/agents/

README 的 Maintenance 一节给出了两条维护规则，这是理解整个体系的钥匙：

• 策略级（policy-level）要求保留在仓库根部的 AGENTS.md；
• 操作性（operational）细节保留在docs/agents/下的文档中。

AGENTS.md 本身定义了仓库级默认约束：

• 术语优先级：MUST 为必需、SHOULD 为推荐、MAY 为可选；根部AGENTS.md是仓库全局默认，更深层路径新增的AGENTS.md对其子树 SHOULD 具有更高优先级。
• 五条不可妥协项（Non-negotiables）：正确性优先（TiDB 是分布式 SQL 数据库，小改动可能改变 SQL 语义、一致性或集群行为）、不做臆测性实现（不发明不存在的 API/默认值/协议行为）、diff 保持最小、留下可验证证据（跑定向检查并报告精确命令）、尊重生成代码（不手改生成产物，须从源输入重新生成）。
• 快速决策矩阵（Quick Decision Matrix）：将"任务类型 → 必须执行的动作"列表化，例如——使用 failpoint 的包跑单元测试 MUST 先启用后禁用 failpoint；录制集成测试 MUST 使用 recording 命令而不是-record；RealTiKV 测试 MUST 后台启动 playground、跑完清理 playground 数据；bug 修复 MUST 补回归测试并验证"修复前失败、修复后通过"；纯格式 PR MUST NOT 跑昂贵的realtikvtest。
• 构建流（Build Flow）：明确列出必须运行make bazel_prepare的触发条件清单（新克隆工作区、WORKSPACE/DEPS.bzl/BUILD.bazel/MODULE.bazel等 Bazel 文件变更、Go 源文件增删改名、已有 Go 文件的 import 段变更、新增顶层func TestXxx(t *testing.T)、go.mod/go.sum依赖变更、Bazel 测试目标更新、本地 Bazel 依赖/工具链报错）。推荐本地构建顺序为：

# 仅在满足触发条件时执行 make bazel_prepare # 然后继续常规本地构建步骤 make bazel_bin make gogenerate # 可选：重新生成生成代码 go mod tidy # 可选：go.mod/go.sum 有变更时

这些目标在当前仓库 Makefile 中均可确认存在：bazel_prepare（注释为 "Update and generate BUILD.bazel files. Please run this before commit."）、bazel_bin、gogenerate，以及bazel_test（其依赖链为bazel-failpoint-enable bazel_prepare，印证了文档中"make bazel_test已内置 failpoint 启用"的说法）。同时AGENTS.md特别强调：make bazel_lint_changed在本地 macOS 环境可能缓慢且耗资源，Agent MUST NOT 在用户未显式要求时运行它。

• 任务 → 验证矩阵（Task -> Validation Matrix）：按改动范围给出最小验证集，例如改pkg/planner/**规则需定向 planner 单测并视需要更新 testdata；改tests/integrationtest/t/**需录制并核对了r目录中再生成结果的正确性；改pkg/ddl/**需 DDL 专项测试与兼容性影响检查。
• Agent 输出契约（Agent Output Contract）：交付变更时必须报告改动的文件、所用验证档位（WIP/Ready/Heavy）及原因、风险（正确性/兼容性/性能）、实际执行的精确命令、以及本地未验证的内容。

docs/agents/agents-review-guide.md 则进一步固化了这条边界：任何新的 MUST/SHOULD/MAY/MUST NOT 策略必须先落在AGENTS.md，docs/agents/下的文档只能解释或举例策略，不得引入新的策略范围；评审时还要重点检查高风险策略门（Bazel 元数据规则的无歧义性、PR 要求的Issue Number:行、测试策略与 runbook 无矛盾等），并提供了可复制的快速验证命令，例如：

# 检查策略锚点 grep -n "Task -> Validation Matrix\|Testing Policy\|make bazel_prepare" AGENTS.md # 确保规范性关键词未被反引号包裹 rg -n -P '`(MUST(?: NOT)?|SHOULD|MAY)`' AGENTS.md docs/agents/agents-review-guide.md # 确保本次变更删除/重命名的路径不再被 Markdown 文档引用 git diff --name-status <base_ref>...HEAD | \ awk '$1=="D"{print $2} $1 ~ /^R[0-9]*/{print $2}' | \ while read -r old_path; do [ -n "${old_path}" ] && rg -n --fixed-strings "${old_path}" --glob '*.md' . || true done

评审完成的验收标准包括：AGENTS.md与变更后的docs/agents/文档之间无策略矛盾、关键规则无歧义措辞、无失效路径引用、且最终评审意见附带具体证据（路径 + 执行过的精确命令）。

三、测试执行手册：testing-flow.md 的完整命令面

docs/agents/testing-flow.md 是整个docs/agents/体系中实操密度最高的文档，声明自己是"命令 playbook 的规范操作参考"（canonical operational reference），并规定.agents/skills/下的技能应当指向这里而不是复制长命令块。其内容按测试面分为四段。

3.1 单元测试（/pkg/...）

pushd pkg/<package_name> go test -run <TestName> -tags=intest,deadlock popd

要点：优先定向运行（-run <TestName>），仅在确有需要时才跑整包；-record只用于明确支持录制的测试套件；运行成功后要复查改动的 result/testdata 文件。

3.2 failpoint 判定与启用

对于使用 failpoint 的包，手册给出了判定命令（决定是否需要启用 failpoint）：

rg -n --fixed-strings -- "failpoint." pkg/<package_name> rg -n --fixed-strings -- "testfailpoint." pkg/<package_name> # 若存在 BUILD.bazel，还需检查 failpoint 依赖 test -f pkg/<package_name>/BUILD.bazel && rg -n --fixed-strings -- "@com_github_pingcap_failpoint//:failpoint" pkg/<package_name>/BUILD.bazel

有命中则用 failpoint 启用方式运行，无命中则普通运行并在报告中说明判定证据；特别提醒-tags=intest,deadlock并不会启用 failpoint。启用运行使用封装脚本 tools/check/failpoint-go-test.sh：

./tools/check/failpoint-go-test.sh pkg/<package_name> -run <TestName>

从脚本头部的 usage 说明可以确认其行为：启用 failpoint → 运行go test→ 清理阶段始终禁用 failpoint；未传-tags时默认-tags=intest,deadlock，需要nextgen时显式传-tags=intest,deadlock,nextgen。底层启用/禁用路径由tools/check/failpoint-state.sh串行化，文档因此警告不要在同一 worktree 的并行 Agent 任务中直接调用tools/bin/failpoint-ctl。走 Bazel 的路径则对应make bazel-failpoint-enable/make bazel-failpoint-disable；使用make bazel_test时无需单独执行 enable（该目标已依赖bazel-failpoint-enable），但结束后仍要执行 disable。

3.3 集成测试（/tests/integrationtest）

测试输入在tests/integrationtest/t，期望结果在tests/integrationtest/r（两者均为仓库顶层 tests/integrationtest/ 下的真实目录）：

pushd tests/integrationtest ./run-tests.sh -r <TestName> popd

文档给出的映射示例：若改的是t/planner/core/binary_plan.test，则TestName就是planner/core/binary_plan。结果文件通常不需手工编辑；确需编辑时保持最小改动并在报告前核实正确性。

3.4 RealTiKV 测试（/tests/realtikvtest）

用于依赖真实 TiKV/TiUP Playground 行为的用例。完整生命周期为"后台启动 playground → 等待 PD 就绪 → 跑测试 → 强制清理 → 验证清理"：

tiup playground --mode tikv-slim --tag realtikvtest & PLAYGROUND_PID=$! # 默认 PD 为 127.0.0.1:2379；端口被占时使用非默认端口或端口偏移 tiup playground --mode tikv-slim --tag realtikvtest --pd.port 12379 & # 或 tiup playground --mode tikv-slim --tag realtikvtest --port-offset 10000 &

PD_ADDR=127.0.0.1:2379 # 若以 --pd.port 12379 或 --port-offset 10000 启动，则 PD_ADDR=127.0.0.1:12379 until curl -sf "http://${PD_ADDR}/pd/api/v1/version" >/dev/null; do sleep 1; done

go test -run <TestName> -tags=intest,deadlock ./tests/realtikvtest/<dir>/... # 非默认 PD 示例 go test -run <TestName> -tags=intest,deadlock ./tests/realtikvtest/<dir>/... -args \ -tikv-path "tikv://127.0.0.1:12379?disableGC=true"

[ -n "${PLAYGROUND_PID:-}" ] && kill "${PLAYGROUND_PID}" 2>/dev/null || true [ -n "${PLAYGROUND_PID:-}" ] && wait "${PLAYGROUND_PID}" 2>/dev/null || true rm -rf "${HOME}/.tiup/data/realtikvtest" # 清理校验：PD 端点应不可达 ! curl -sf "http://${PD_ADDR}/pd/api/v1/version"

文档还推荐了一个带trap cleanup EXIT INT TERM的 cleanup-safe 模板，保证长时本地调试时即使中断也能自动回收 playground 进程和${HOME}/.tiup/data/realtikvtest数据目录。--tag realtikvtest的作用正是让数据退出后仍保留在该目录、从而可以在清理阶段删除。默认不加-v，仅调试时添加。替代工作流位于 tests/realtikvtest/scripts/classic/ 与 tests/realtikvtest/scripts/next-gen/（两者均含bootstrap-test-with-cluster.sh、run-tests.sh、run-tests-with-gotest.sh等脚本），分别对应经典模式与 next-gen 模式。

四、架构索引：architecture-index.md 的子系统导航

docs/agents/architecture-index.md 自称是"快速子系统发现的导航索引"（navigation index for quick subsystem discovery），硬性要求仍留在根部AGENTS.md。它规定四步使用法：把任务映射到一个主属子系统 → 找覆盖相同行为的既有测试 → 复用既有 fixture/testdata 再考虑新形状 → 仅在跨模块影响明确时才扩展到相邻子系统。

索引覆盖的核心子系统与路径（均与仓库当前目录结构一致）：

子系统	关键路径	典型改动
Planner 与优化	pkg/planner/、pkg/planner/core/base/、pkg/planner/core/operator/logicalop/、pkg/planner/core/operator/physicalop/	规则匹配、计划形状、基于代价的选择；首查测试为pkg/planner/core/casetest/与pkg/planner/core/casetest/rule/testdata/
执行与表达式	pkg/executor/、pkg/expression/	运行时算子语义、内建函数行为、求值边界
Session/变量/协议	pkg/session/、pkg/sessionctx/、pkg/sessionctx/variable/、pkg/server/	会话生命周期、语句上下文、协议层行为
DDL 与元数据	pkg/ddl/、pkg/infoschema/、pkg/meta/、pkg/meta/autoid/	schema 演化、元数据持久化、ID 生成
存储与分布式执行	pkg/kv/、pkg/store/、pkg/distsql/、pkg/tablecodec/	KV 语义、存储集成、分布式查询路径
Domain 与统计	pkg/domain/、pkg/statistics/	schema/统计生命周期、基数/估算行为
Parser 与 AST	pkg/parser/	SQL 语法、AST 节点、解析行为

测试面（Test Surfaces）划分为三类：包内单测（pkg/**本地）、集成测试（输入tests/integrationtest/t/、期望输出tests/integrationtest/r/）、RealTiKV 测试（tests/realtikvtest/，当行为依赖真实 TiKV/PD 交互时使用）。文档还给出"常见跨模块路径"作为调用链心智模型：Planner → Executor → Expression（查询语义）、Session/Variables → Executor（用户可见运行时行为）、DDL → Infoschema/Meta → Domain（schema 生命周期）、Store/KV/DistSQL → Executor（分布式执行行为）。

从源码结构看，这份索引与仓库顶层目录逐一对应：pkg/planner/下确实存在core/、casetest/等目录，tests/integrationtest/顶层同时存在t/与r/两个子目录，印证了索引的"输入/期望输出"划分。

五、组件级笔记：ddl、dxf、import-into、executor 四个子目录

README 声明的四个组件目录，各自遵循"导航优先、指向源码"的写法，以下逐一说明其骨架。

5.1docs/agents/ddl/：DDL 执行框架的 Read-First 索引

docs/agents/ddl/README.md 开头即给出 DDL 的心智模型：TiDB DDL 是基于作业（job-based）且由 owner 驱动的——SQL DDL 语句被转换为持久化的 DDL 作业，由DDL owner调度 worker 逐步推进 schema 状态并等待全集群 schema 版本同步。文档点名的"最常见错误"是在pkg/executor/（SQL 执行层）直接实现 DDL 行为，那会绕过作业持久化/owner 故障切换（可恢复性）、schema 状态机（delete only→write only→reorg→public）、schema 版本 + diff 更新与集群同步、以及 MDL/lease 安全机制。

该 README 还要求 Agent 在动pkg/ddl/之前书面回答 8 个前置问题（是否 job-based 或元数据快速路径、需要哪些 schema 状态迁移、是否需要 reorg/backfill 扫描及其 checkpoint、取消/回滚语义、对 schema 版本与 follower 同步的影响、涉及哪些系统表如mysql.tidb_ddl_job与mysql.tidb_ddl_reorg及字段向后兼容性、MDL 阻塞与写冲突的在线行为、最小回归测试与可确定性化的 failpoint）。文档提供了按任务分篇的索引（01 执行流、02 作业生命周期、03 reorg/backfill、04 开发检查清单、05 文件地图、06 add-index 深潜、07 modify-column 深潜、08 分区 DDL 深潜，均为docs/agents/ddl/下的真实文件）、一个 mermaid 时序图（Session →pkg/executor/ddl.go的DDLExec→pkg/ddl/executor.go→JobSubmitter→mysql.tidb_ddl_job→ owner 的jobScheduler→ worker →pkg/ddl/schemaver/syncer.go的Syncer），以及一张"先看哪里"的代码地图（pkg/executor/ddl.go、pkg/ddl/ddl.go、pkg/ddl/executor.go、pkg/ddl/job_submitter.go、pkg/ddl/job_scheduler.go、pkg/ddl/job_worker.go、pkg/ddl/systable/manager.go、pkg/domain/domain.go）。根部 AGENTS.md 对此有对应硬约束：改 DDL 行为前 MUST 先读docs/agents/ddl/README.md；调试时这些文档只能当假设（MUST 用代码/测试验证）；若实现与文档行为不一致，MUST 随代码一起更新文档并在 PR/issue 中说明。

5.2docs/agents/dxf/：DXF 框架导航

docs/agents/dxf/README.md 是 DXF（Distributed eXecution Framework）的导航地图，范围涵盖核心框架pkg/dxf/framework/、IMPORT INTO 应用pkg/dxf/importinto/、DDL 分布式 backfill 应用pkg/ddl/、SQL 入口pkg/executor/与pkg/executor/importer/、以及运行时 bootstrap 与 ownership 循环所在的pkg/session/与pkg/domain/。其"阅读规则"与全仓库一致：包有doc.go时先读（DXF 从pkg/dxf/framework/doc.go开始）。框架地图按职责切分：framework/proto/（任务类型/步骤常量、task-subtask 模型、状态机枚举）、framework/handle/（提交/等待/暂停恢复/取消/修改 API）、framework/storage/（任务管理器与 dist-task 表持久化）、framework/scheduler/（owner 侧调度）、framework/taskexecutor/（节点侧执行）、framework/planner/（逻辑计划到物理计划/任务创建）、operator/（算子流水线工具）。

文档进一步给出运行时流程速览（业务逻辑构建任务元数据并提交 → storage 持久化 task/subtask 状态 →Domain在每个节点启动 executor-manager 循环 → scheduler-manager 循环仅在本节点为 DDL owner 时运行 → scheduler 扩展推进步骤并派发子任务 → executor 扩展执行子任务并汇报状态/摘要），以及新增任务类型的检查清单：先在pkg/dxf/framework/proto/定义任务类型与步骤枚举（step.go明确禁止修改既有常量值以保向后兼容）、实现scheduler.Extension与taskexecutor.Extension、注册scheduler.RegisterSchedulerFactory/taskexecutor.RegisterTaskType/ 可选scheduler.RegisterCleanerFactory，并要求GetNextStep从任务基础状态出发保持确定性。两条关键不变量值得注意：任务 rank 同时驱动调度与抢占（rank 高 =(priority, create_time, id)元组小）；RequiredSlots是预留基线，实际运行可通过ExtraParams.MaxRuntimeSlots+TargetSteps使用更少的 slot。

5.3docs/agents/import-into/：冲突解决排障地图

docs/agents/import-into/README.md 聚焦"只读单个包时容易漏掉"的冲突解决与清理行为，范围为 IMPORT INTO 作业/任务生命周期（mysql.tidb_import_jobs+ DXF 任务）、全局排序冲突检测/收集/解决、后处理校验与清理。它给出两条步骤流：本地排序路径StepInit -> ImportStepImport -> ImportStepPostProcess -> StepDone；全局排序路径StepInit -> ImportStepEncodeAndSort -> ImportStepMergeSort -> ImportStepWriteAndIngest -> ImportStepCollectConflicts -> ImportStepConflictResolution -> ImportStepPostProcess -> StepDone（后三个为可选子任务阶段）。排障示例包括："collect-conflicts / conflict-resolution 步骤为何被跳过？"（当collectConflictInfos未发现已记录冲突时不生成 spec，可检查各阶段 meta 的RecordedConflictKVCount > 0）与"后处理为何跳过 checksum？"（TooManyConflictsFromIndex在有限内存 row-key 集合超限——约 step 内存的一半——时被置位，后处理据此跳过最终 checksum）。

5.4docs/agents/executor/：特性开发笔记

docs/agents/executor/fullouter_join_dev_note.md 展示了另一种笔记形态：特性开发的过程追踪。它记录了 TiDB 添加 SQL 标准FULL OUTER JOIN的四步计划（语法/AST 恢复/特性门 → root planner → root HashJoin v1 执行 → TiFlash MPP shuffle join）、初始目标范围（FULL OUTER JOIN ... ON ...、Volcano planner、root HashJoin v1、由tidb_enable_full_outer_join门控且默认OFF）、初始非目标（USING/NATURAL FULL OUTER JOIN、Cascades planner、IndexJoin/MergeJoin/HashJoin v2 等），以及按主题的 Decision Log（决策日志）。这是 notes-guide 中"决策与实现计划留痕"规范的实例。

六、notes-guide：组件笔记的放置、更新与拆分规则

docs/agents/notes-guide.md 规定了组件笔记的三条操作规则，是维护docs/agents/<component>/子目录的规范：

1. 位置与布局：笔记放在docs/agents/<component>/，靠近所属组件；优先复用既有文件夹；新增文件夹时应在本指南中加一条简短说明使其可被发现；本指南不维护组件文件夹的完整内联列表——以docs/agents/目录本身为当前文件夹名的唯一事实来源（与docs/agents/README.md的 Layout 一节互为呼应）。
2. 更新规则：主题/根因重叠时更新既有小节；只有真正全新的主题才追加带日期的新小节。
3. 大笔记拆分：单文件超过 2000 行时按功能拆分，并更新所有指向旧路径的引用。

指南末尾还固定了一条索引：IMPORT INTO 笔记位于docs/agents/import-into/README.md。

七、配套生态：.agents/skills 技能与 PLANS.md ExecPlan

README 声明的策略/操作二分法之上，仓库还有一套被两份顶层文件支撑的配套机制：

• 技能库 .agents/skills/README.md：仓库级技能存放于.agents/skills，每个技能的内容与引用集中在各自的技能文件夹内（如.agents/skills/<skill>/SKILL.md及references/）。当前仓库中存在九个操作工作流技能：tidb-verify-profile（选择 WIP/Ready/Heavy 验证档位）、tidb-bazel-prepare-gate（判定是否需要make bazel_prepare）、tidb-failpoint-test-runner（failpoint 启用/禁用判定与安全跑单测）、tidb-integrationtest-recorder（集成测试录制流）、tidb-realtikv-runner（RealTiKV 启停清理纪律）、tidb-test-diff-triage（测试 diff 归因：failpoint vs 上游 vs 本地回归）、tidb-issue-metadata-guard与tidb-pr-metadata-guard（issue/PR 模板与元数据守护）、tidb-change-instruction-critic（实现前评估修复方案）。该 README 明确了三层分工：策略与验证/报告要求用AGENTS.md，构建/测试命令 playbook 用docs/agents/testing-flow.md，技能提供指向这些 playbook 的入口工作流——这正对应 AGENTS.md 中"政策归AGENTS.md、详细命令 playbook 归docs/agents/*、技能提供入口工作流"的表述。
• ExecPlan 规范 PLANS.md：定义"执行计划"（ExecPlan）——一份自包含的、可供无仓库背景的执行者（人或无状态 Agent）从头到尾完成特性交付的活文档。其不可协商要求包括：完全自包含、随进展持续更新、让新手也能端到端实现、产出可演示的行为（而不只是源码编辑）、用白话定义非显见术语；并强制每个计划维护Progress、Surprises & Discoveries、Decision Log、Outcomes & Retrospective四个活章节。AGENTS.md 的 ExecPlans 一节将其挂入流程：编写复杂特性或重大重构时，从设计到实现都应使用符合PLANS.md格式的 ExecPlan，并在实现推进期间保持其为活文档。

八、从文档到行动：一份可直接使用的操作速查

把上述文档串起来，Agent（或人类）在 TiDB 仓库中完成一次改动验证的最小闭环是：

1. 定位：按 docs/agents/architecture-index.md 把任务映射到主属子系统，找到同行为的既有测试与 testdata；改动前阅读目标包的doc.go（若存在）——这是 AGENTS.md Pre-flight Checklist 的第 2 条。
2. 判定构建前置：对照Build Flow的触发清单（或.agents/skills/tidb-bazel-prepare-gate）决定是否需要make bazel_prepare，需要则把生成的BUILD.bazel/*.bazel/*.bzl变更纳入 diff。
3. 选择最小验证集：按Task -> Validation Matrix定测试面，命令一律取自 docs/agents/testing-flow.md：单测用go test -run <TestName> -tags=intest,deadlock（failpoint 包改用./tools/check/failpoint-go-test.sh）；集成测试用tests/integrationtest/run-tests.sh -r <TestName>后核对r/下 diff；RealTiKV 用例按"后台 playground → 轮询 PD 就绪 → 测试 → kill +rm -rf ${HOME}/.tiup/data/realtikvtest→ curl 校验端点不可达"的完整生命周期执行。
4. 按档位交付：迭代中用WIP验证档位，交付前用Ready档位（代码改动要求make lint），并按 Agent Output Contract 报告文件、档位、风险、精确命令与未验证项。
5. 文档自洽：若改动本身涉及AGENTS.md、.agents/skills/或docs/agents/下任何文件，先按 docs/agents/agents-review-guide.md 的六组检查清单（优先级与范围、结构与去重、高风险策略门、测试/验证一致性、PR/Issue 策略一致性、引用与路径卫生）自查，并用其中的快速验证命令留证。

九、小结

docs/agents/目录体系的设计可以用 docs/agents/README.md 的两段话概括：布局上，横切 runbook 居顶层、组件笔记按子目录归位；维护上，策略进根部AGENTS.md、操作留在docs/agents/。围绕这一中心，testing-flow.md 提供可复制粘贴的四类测试命令面（含 failpoint 判定与 RealTiKV 清理纪律），architecture-index.md 提供子系统到路径与测试面的映射，agents-review-guide.md 与 notes-guide.md 分别约束文档自身的变更评审与笔记生长方式；ddl/、dxf/、import-into/、executor/四个组件目录则以"Read-First 索引 + 代码地图 + 决策留痕"的形态承载各模块的深度知识。技能库.agents/skills/与PLANS.md的 ExecPlan 规范则分别负责"工作流入口"与"长任务交付"，共同构成一套策略、操作、组件知识三层分离且互相不重复的 Agent 文档体系。

赞分享

• 数据库
• 分布式数据库
• 后端
• OLAP

【免费下载链接】tidb

TiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.

项目地址：https://gitcode.com/GitHub_Trending/ti/tidb

点击查看免费下载

相关推荐

• Data-Juicer 官方文档导航解析：Sphinx 文档站点的索引架构与目录体系

  Data Juicer 官方文档导航解析：Sphinx 文档站点的索引架构与目录体系 Data Juicer 项目通过 Sphinx 构建的在线文档站点，其入口

  人工智能大模型数据工程数据清洗数据增强数据质检

• Wand-Enhancer 使用教程：本地补丁免费解除 Wand 2 小时限制，附手机远程面板完整指南

  Wand Enhancer 使用教程：本地补丁免费解除 Wand 2 小时限制，附手机远程面板完整指南 Wand Enhancer 是一款针对 Wand（原 W

  桌面应用前端

• Just the Docs 导航系统完全指南：主导航、面包屑、子页目录与页内导航的配置与源码解析

  Just the Docs 导航系统完全指南：主导航、面包屑、子页目录与页内导航的配置与源码解析 Just the Docs 的默认页面布局内置了一套完整的文档

  文档静态站点UI组件