为实体添加语义描述

语义描述（Description）是帮助 AI 代理理解数据含义的关键元数据。当你在实体、字段和参数上添加描述后，代理调用 describe_entities 工具时就能获得业务语境，从而做出更准确的查询决策。

为什么需要描述

没有描述时，代理看到的是技术名称如 ProductID、dbo.Orders。有了描述后，代理理解 ProductID 是"产品目录中每个产品的唯一标识符"，dbo.Orders 存放的是"包含行项目和物流信息的客户采购订单"。这直接影响代理选择实体、字段和参数的准确性。

描述通过 describe_entities MCP 工具暴露给代理，包含实体描述、字段描述（含类型和是否主键）以及可执行的操作列表。

实体描述

CLI 添加

# 新建实体时添加
dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --description "产品目录，包含价格、库存和供应商信息"

# 已有实体更新
dab update Orders \
  --description "客户订单，包含行项目、配送详情和支付状态"

配置示例

{
  "Products": {
    "description": "产品目录，包含价格、库存和供应商信息",
    "source": { "object": "dbo.Products", "type": "table" }
  }
}

实体描述应解释这个表/视图/存储过程代表什么业务概念。一到两句话，包含核心业务含义即可。

字段描述

每个字段逐条添加描述，帮助代理理解每列的业务含义：

dab update Products \
  --fields.name ProductID \
  --fields.description "产品唯一标识符（自增主键）" \
  --fields.primary-key true

dab update Products \
  --fields.name UnitPrice \
  --fields.description "零售单价，单位为人民币元"

dab update Products \
  --fields.name UnitsInStock \
  --fields.description "当前可用库存数量"

dab update Products \
  --fields.name ReorderLevel \
  --fields.description "触发自动补货的最低库存量（正整数）"

dab update Products \
  --fields.name Discontinued \
  --fields.description "是否已停产（true 表示不再销售）"

字段描述最佳实践

应该写的	示例
业务含义	"客户配送地址" 而非 "地址"
单位	"重量，单位为千克"、"价格，单位为人民币元"
格式	"ISO 8601 日期格式"、"E.164 电话格式"
业务规则	"负数表示信用余额"、"null 表示未设置"
约束	"必须为正整数"

不应该写的	说明
重复字段名	"ProductID 是产品 ID"——没有增加任何信息
纯技术术语	需要加上业务语境
长篇大论	一到两句话
忽略 null 含义	说明 null 值是否有特殊含义

参数描述

存储过程的参数描述帮助代理正确传参。参数元数据使用逗号分隔列表，按参数顺序一一对应：

dab add SearchProducts \
  --source dbo.usp_SearchProducts \
  --source.type "stored-procedure" \
  --permissions "anonymous:execute" \
  --description "按关键词、分类和价格区间搜索产品" \
  --parameters.name "SearchTerm,CategoryID,MinPrice,MaxPrice,PageSize" \
  --parameters.description "产品名称和描述中的搜索关键词,产品分类ID（null 搜索全部分类）,最低价格（人民币元，null 不设下限）,最高价格（人民币元，null 不设上限）,每页结果数（默认 20，最大 100）" \
  --parameters.required "true,false,false,false,false" \
  --parameters.default ",null,null,null,20"

参数列表格式规则

• --parameters.name：参数名按顺序列出，逗号分隔。
• --parameters.description：对应描述列表，顺序、数量必须与 name 完全一致。
• --parameters.required：true 或 false，按顺序列出。
• --parameters.default：默认值列表，必填参数写空字符串占位。

逗号分隔的列表对齐至关重要。如果数量或顺序不匹配，配置会出错。

已有存储过程更新参数描述

dab update GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.description "起始日期（包含）,结束日期（包含）" \
  --parameters.required "true,true"

描述在 MCP 中的表现

当 AI 代理调用 describe_entities 时，描述和 schema 信息一起返回：

{
  "entities": [
    {
      "name": "Products",
      "description": "产品目录，包含价格、库存和供应商信息",
      "fields": [
        {
          "name": "ProductID",
          "description": "产品唯一标识符（自增主键）"
        },
        {
          "name": "UnitPrice",
          "description": "零售单价，单位为人民币元"
        }
      ],
      "operations": ["read_records", "create_record", "update_record"]
    }
  ]
}

NOTE

当前响应中只包含字段的 name 和 description。数据类型和主键标志暂不会出现在响应中。代理需要依靠实体与字段说明，以及错误反馈，来推断正确用法。

代理利用这些信息选择正确实体、挑选相关字段、构造准确查询，以及为存储过程提供正确的参数值。

批量维护

对于大 schema，建议将字段描述维护在脚本中，批量执行：

#!/bin/bash
# 批量更新 Products 表字段描述
declare -A fields
fields=(
  ["ProductID"]="产品唯一标识符（自增主键）:true"
  ["ProductName"]="产品显示名称:false"
  ["UnitPrice"]="零售单价，单位为人民币元:false"
  ["UnitsInStock"]="当前可用库存数量:false"
)

for name in "${!fields[@]}"; do
  IFS=':' read -r desc is_pk <<< "${fields[$name]}"
  dab update Products --fields.name "$name" --fields.description "$desc" --fields.primary-key "$is_pk"
done

下一步

• 数据操作工具 — 代理如何通过 DML 工具操作数据。
• 自定义工具 — 将存储过程注册为命名 MCP 工具。