AOCI-CODE Database Cognition 完全指南:把 PostgreSQL、MySQL、openGauss 表结构纳入同一索引

原创2026-10-12 18:47:511,695 阅读
文章标签:开发工具MCP 服务CLI代码智能体人工智能Agent 记忆

AOCI-CODE Database Cognition 完全指南:把 PostgreSQL、MySQL、openGauss 表结构纳入同一索引

AOCI-CODE 是一个本地优先的 Go 语言 MCP 服务器 + CLI 工具,它的 Database Cognition(数据库认知索引)功能能把 PostgreSQL、MySQL、openGauss 的表结构以"只读证据"方式采集下来,与代码索引一起纳入同一份 Git 版本化的 aoci.database.txt,让 Claude Code、Codex、Cursor、opencode 等编程 Agent 在动手改代码之前,先"读懂"数据库的表、约束和关键规则。

AOCI-CODE 数据库认知索引:项目级全量认知,代码与数据库统一理解

什么是 Database Cognition?为什么需要它 🧭

写代码的 AI Agent 最大的短板之一是:对数据库一无所知。表名叫什么、哪张表是权威数据源、外键关系如何、哪些字段绝不能删——这些信息 Agent 只能靠反复翻迁移脚本和 SQL 文件去猜。

Database Cognition 的做法是给每张表写一行"认知条目"(FRAS 格式),和代码索引共用同一套治理流程:

字段 回答的问题 示例内容
F — Function 这张表的核心职责? 存储权威的商业订单聚合
R — Relations 修改时必须一起考虑的表? customers、payments、audit_events
A — API 外部可依赖的接口/契约? order_number、OrderRepository、POST_/orders
S — 约束 代码里推断不出、但改错会出事的规则? 订单状态流转与台账必须同一事务提交

项目自带的真实样例可以直接看到效果:

orders[DB9L]: F:store the authoritative commercial order aggregate | R:customers,payments,order_dependencies,audit_events | A:order_number,OrderRepository,OrderService,POST_/orders | S:Order state transitions and their ledger effects must commit in one transaction; completed orders are retained rather than deleted

(样例来自 testdata/volumes/database-quality/aoci.database.txt)

五步打通:从声明数据源到表级认知 ✅

整个流程命令都很直白,网络访问只发生在显式数据库命令中,其余步骤全部离线:

1. 声明一个数据库源(不存任何密码)

aoci --repo . database source add \
  --source-id primary \
  --engine postgresql \
  --database-name app \
  --namespace public

省略 --credential-env 时,AOCI 会从 source-id 派生环境变量名(primary → AOCI_DB_PRIMARY_DSN)。配置里只保存这个引用名,连接串由 DBA 在 AOCI 进程之外通过环境变量提供。用只读预检确认凭据是否就绪:

aoci --repo . database source access --source primary --json

2. 采集只读结构证据(Snapshot)

aoci --repo . database snapshot --source primary --json

这一步读取的只是系统目录(information_schema / pg_catalog 等),记录基表、列、主键/外键、索引、分区等结构事实,并生成内容寻址的 table_evidence_sha256 指纹。

3. 显式接受证据基线

aoci --repo . database baseline accept --source primary \
  --snapshot-sha <source_snapshot_sha256> --json

4. 开启 Database Cognition Volume

对已对齐的 Code-only Volumes 项目执行窄范围 Bootstrap,只添加 Database 描述符、标记型 aoci.database.txt 和基线绑定,不触碰任何代码内容:

aoci --repo . database cognition bootstrap
aoci --repo . database cognition status --json

5. 让 Agent 写表级 FRAS

之后走标准的 MCP 维护循环:Agent 调用 aoci_maintain 获取确定性的候选页面(含完整 Table Evidence、字典规则和合法示例),阅读证据后为每张表写出完整条目,再用 aoci_update_entry 提交整批候选。每页候选都绑定 Volume 预镜像与表证据 SHA,写入走既有的 CAS/原子写/基线/恢复管线。

三大引擎支持情况一览 🗄️

引擎 驱动 v1 覆盖范围与限制
PostgreSQL jackc/pgx/v5 基表 + 分区表;JSONB、serial、identity、生成列、表达式/部分/包含索引、分区方法/边界
MySQL go-sql-driver/mysql MySQL 8.0+;--namespace 必须等于 --database-name;覆盖 auto_increment、前缀/降序/不可见索引、分区定义
openGauss 打过评审补丁的 openGauss-connector-go-pq v1.0.8(见 third_party/openGauss-connector-go-pq) 仅限 6.0.5 LTS + A/PG 兼容模式的普通非分区基表;遇到分区、列存、MOT、视图等不支持特性会 fail-closed(报 unsupported_catalog_feature),绝不静默降级成 PostgreSQL 事实

三个驱动均为纯 Go 实现,支持 CGO_ENABLED=0。详细契约见 docs/database-evidence.md 与 docs/database-cognition-authoring.md。

安全边界:读什么、不读什么 🔒

AOCI-CODE 的数据边界非常克制,值得新手放心使用:

  • 只读、单连接、可重复读事务;永不查询业务行,不 SELECT/COUNT 数据,不采样值,不读统计信息
  • 零 DDL/DML:不执行 INSERT、UPDATE、DELETE、ALTER、CREATE、DROP、迁移
  • 凭据不落盘:DSN、密码、主机、用户名永远不写入索引、证据、基线或日志;错误信息只暴露稳定错误码
  • 离线治理:Maintain、status、候选校验与 Apply 全程不重连数据库
  • 改名不猜测:表重命名报告为 removed + new,由人和模型决定认知工作,绝不自动"对齐"
  • openGauss 的 TCP 非回环连接强制 sslmode=verify-full + TLS 1.2+,拒绝降级模式

采集器源码集中在 internal/dbevidence/,认知评估逻辑在 internal/dbcognition/。

认知状态体检:一眼看懂索引健康度 🩺

aoci database cognition status 会对每张表给出离线状态:

状态 含义
cognition_current 条目、条目 SHA 与当前证据 SHA 一致,一切就绪
cognition_missing 证据里有这张表,但 Volume 里还没有条目
cognition_stale 绑定的证据身份与当前证据不一致(结构变了)
cognition_unbaselined 条目存在但缺少对应绑定
cognition_orphan 当前证据里已没有这张表(停下待人工裁决,不会自动删除)

结构漂移只会让受影响的表变 stale,其他表的指纹保持稳定——这让增量维护的成本非常低。

延伸阅读:官方文档与关键源码

💡 一句话总结:先建好代码索引,再声明数据库源、采集证据、接受基线、Bootstrap 开启 Database Volume,Agent 就会把表结构和代码放进同一张"系统地图"——从此改表之前,Agent 已经知道哪张表是权威、哪条约束碰不得。

登录后查看全文
aoci-code