Agent开发系列（九）-知识库建设（领域词典）

# 词条:GMV

基础信息:
  词条名: GMV                        # 必填,唯一
  分类: 业务指标                       # enum: 业务名词/技术名词/状态/角色/指标
  简短定义: "一段时间内所有订单的总成交金额"   # 必填,1 句话,30 字以内
  状态: active                       # enum: active / deprecated / draft

关联:
  涉及系统: [订单中心, 报表平台]           # 必填,多选
  关联代码: [order-service/calc.py:gmv()]  # 必填,可点击
  负责人: @data-team                   # 必填,团队/个人
  关联 ADR: [ADR-0015]                 # 可选

歧义(最关键):
  易混淆词:                           # 至少 1 个,否则认为定义不完整
    - 销售额: "财务口径,扣除退款"
    - 成交额: "技术口径,不含未支付订单"
  适用场景: [财务月报, 运营日报]         # 必填
  不适用场景: [实时推荐系统]            # 必填,至少 1 个
  反例: "GMV 不应该用于计算利润率"      # 必填,至少 1 条

元数据:
  创建人: @alice
  创建时间: 2026-06-01
  最后审阅: 2026-06-05
  审阅人: @bob
  来源: [PRD-2025Q3, 纪要-2026-05-12]  # 必填,溯源用
  LLM 标记: 🤖 auto-generated

2.1 关键设计点(为什么这些字段必填)

字段	必填原因
易混淆词	词典区别于 glossary 的核心,缺了就没价值
不适用场景	防止"过度使用",划清概念边界
反例	比定义本身更有价值的"边界判断"
关联代码(可点击)	不可点击 = 不可消费,Lint 拒绝
来源	词条可追溯到 Raw,这是 Raw ↔ Wiki 双向追溯的命门
状态(deprecated)	业务变化时标记，新人不会用过时词

2.2 反模式

反模式	后果
字段自由发挥(string,长篇)	不可机器解析,Agent 无法消费
缺歧义字段	退化成"一句话百度百科"
链接写"见订单中心"不点击	不可消费的链接,Lint 应告警
在词典里写"故事"	湿润化,LLM 越维护越离谱

三、领域词典的更新机制如何设计？

核心判断:更新机制 = 4 个触发器 + 1 个统一通道，没有触发器,词典会过期;没有统一通道,词典会乱。其中4个触发器是：

触发器	触发条件	动作
PR-ingest	PR 改动关联的代码路径	LLM 检查词条,提议 diff,走 PR
新词检测	新名词在代码/PR/会议出现 N≥3 次	LLM 提议新词条,owner 审
歧义事件	跨团队沟通出现"X 是什么"	立刻触发,补词条(最高优先级)
定期审阅	词条到审阅周期	owner 必须重审,否则标 stale

3.1 关键设计点

设计点	具体要求
写入通道	所有更新走 PR(包括 LLM 提议)
LLM 权限	无主分支写权限，只能开草稿 PR
PR 内容	必须显示 diff(原来这样 → 现在这样)
审阅周期	P0:季度;P1:半年;P2:年度;写进元数据
审阅提醒	Lint 到点自动告警,未审 = 默认标 stale
新词门槛	LLM 必须先评估"是否与现有词重叠"
新词证据	必须有上下文(出现在哪些 PR/会议/代码)
歧义事件	跨团队出现"X 是什么"立即触发,不等待审阅

3.2 反模式

反模式	后果
LLM 直接写主分支	失治理,2 周后词条不可信
owner 长期不审	词条过期,Lint 自动降权
词典和代码不同步	Lint 必须强制,改代码必查词条

四、领域词典的质量标准如何定义？

核心判断:质量 = 5 个可测指标,不是"看着齐不齐"，质量标准不能是"主观感觉",必须是可机器测的指标。否则没法持续改进。5 个核心指标是指：

指标	定义	健康值
覆盖率	P0 词条定义完成率 / 全部 P0 词条数	≥ 95%
新鲜度	词条最后审阅时间中位数	≤ 90 天
歧义避免率	跨团队沟通中"X 是什么"类问题的频率	月度环比下降
链接有效性	词条关联的代码/ADR 链接 100% 可解析	≥ 99%
LLM 提议采纳率	owner 接受 LLM 提议的比例	60-80%(太高说明 LLM 没贡献,太低说明 LLM 提议质量差)

4.1 P0词条三个门槛

门槛	必须满足	触发动作
准入门槛(发布前)	基础信息完整 / 关联字段全 / 歧义字段有内容 / 来源溯源 / owner 审过	缺一不准合并
持续门槛(运行中)	审阅周期内审过 / 关联链接有效 / 至少被 1 个 PR/ADR/文档引用	否则降级或归档
淘汰门槛(满足任一)	6 个月零引用 + 零审阅 + 关联代码都删了 / deprecated 超 90 天	自动归档

4.2 3个反向指标(出现就告警)

反向指标	告警触发	修复动作
Slack 出现"X 是什么"	自动检测	触发"歧义事件"更新
同一概念多处定义不一致	Lint 配对检查	触发 owner 审阅
新 PR 引入代码名词 6 个月未进词典	覆盖率下降	触发"新词检测"流水线

4.3 淘汰机制

类型	触发	动作	位置
自动归档	6 个月零引用的 P2 词条	移归档	`00-meta/glossary-archive.md`
手动归档	业务变化,owner 主动标	标 deprecated	原地标 + 90 天后归档
永不删除	任何归档	不删,只移	`90-archive/`

五、领域词典知识建设如何冷启动？

核心判断：从已有材料反向抽取,不要从零写。 团队的词已经存在,散落在代码、PRD、会议、Slack 里。真正的工作是"对齐",不是"创造"。

5.1 4步建设方法

步骤	动作	输出	责任方
Step 1:抽取	LLM 从代码/PRD/会议/Slack 抽候选词	候选词清单 + 上下文片段	LLM 自动
Step 2:筛选	模块 owner 标 P0/P1/P2/P3	优先级清单	人工
Step 3:定义	LLM 草拟定义 + 关联,owner 审改	词条草稿	LLM + 人工
Step 4:发布	走 PR,合并后更新 index.md	正式词条	人工 review

5.2 抽取源头(优先级)

源头	抽取方式	价值
代码 class/function/variable 名	静态分析	最高(代码 = 事实)
PRD / 设计文档	LLM 解析	高(业务侧)
会议纪要 / Slack 高频词	LLM 提取	中(噪声大)
客户反馈	人工标记	低(偶尔用)

5.3 优先级划分

级别	标准	处理方式
P0	跨团队使用 + 有歧义风险	必须建,先做 50-100 个
P1	跨团队使用 + 无歧义	应该建,第二批
P2	内部使用 + 无歧义	可建,有余力再做
P3	罕用 / 概念重叠 / 业务已废弃	不建,直接弃

5.4 反模式

反模式	为什么不行
从零写	90% 团队 3 个月后夭折
追求"全"	做不全,做了也维护不动
省略"易混淆词"	这是词典最值钱的部分,省了它就退化成 glossary