上下文契约

契约应回答什么

每个 Agent 任务只需要相关子图，但下面的字段应稳定：

contract_version: 2026-08-02.1
database: commerce
schema: app
role: analytics_readonly
dialect: postgresql-18
timezone: UTC
currency_unit: cents
tables:
  orders:
    purpose: one row per checkout
    primary_key: [id]
    columns:
      customer_id: { type: bigint, nullable: false, ref: customers.id }
      status: { type: text, allowed: [pending, paid, shipped, cancelled] }
      total_cents: { type: bigint, min: 0 }
      placed_at: { type: timestamptz, meaning: checkout completion instant }
    invariants:
      - paid orders have an immutable total
    sensitive: []
limits:
  statement_timeout_ms: 5000
  max_rows: 200
  writes: forbidden

契约版本应与迁移版本或 schema hash 关联。工具返回契约版本，便于定位“模型基于旧 schema 生成 SQL”的问题。

三层上下文

全局规则：方言、时区、金额单位、默认 schema、权限与限制。
任务子图：相关表、键、列、注释、枚举和关键索引。
动态证据：只读样例、统计摘要、最近错误；必须标注采样时间与是否截断。

不要发送全库每个索引的完整 DDL。先按表名、列名、注释和外键关系检索出任务子图，再按需展开索引或函数定义。

必须从上下文移除

密码、连接 URI、API key 和 pg_authid 数据。
不属于当前租户或权限域的样例值。
完整生产行样本，尤其是个人信息与密钥材料。
无法说明来源和时效性的业务规则。
把估算统计误写成精确事实的数字。

输出契约

要求模型返回结构化对象，而不是可直接执行的任意文本：

{
  "intent": "read",
  "sql": "SELECT id, total_cents FROM app.orders WHERE customer_id = $1 LIMIT $2",
  "params": [42, 50],
  "assumptions": ["customer_id is the authenticated customer's internal id"],
  "expected_columns": ["id", "total_cents"],
  "risk": "R0"
}

策略层再次验证 SQL；不要因为 JSON 格式正确就信任其语义。

缺失信息的行为

契约必须允许模型回答 insufficient_context，列出所需的表、列或业务定义。相比猜一个看似合理的列名，这是成功行为，不是失败。

把动态 Linux 事实交给只读工具

安装、升级和排错问题还需要发行版动态事实。可以把 PkgSeek 只读 MCP 配置为 Linux 软件包证据层，让 Agent 查询准确包名、文件 provider、仓库、release、版本历史和厂商安全状态；本站文档继续提供 PostgreSQL 的选择、升级和验证规则。

linux_evidence:
  provider: pkgseek
  distro: ubuntu
  release: noble
  architecture: amd64
  package_source: pgdg
  observed_at: required
  missing_coordinate: insufficient_context
  state_changes: require_confirmation

工具没有返回准确坐标时，模型必须报告“当前索引未收录”，不能改写成“软件包不存在”。查询是只读的；sudo apt install、仓库修改、服务重启和大版本升级仍要单独确认并在执行后验证。