Agent开发系列（十）-知识库建设（架构总览）
目录
一、什么是架构总览
二、架构总览的知识模板如何定义？
2.1 总览页设计
2.2 服务清单字段(最重要的模板)
2.3 依赖图(dependency-graph.md)结构
2.4 技术栈矩阵(tech-stack.md)结构
2.5 部署拓扑(deployment.md)结构
三、架构总览的更新机制应该如何落地？
3.1 关键设计点
3.2 反模式
四、架构总览的质量标准应该如何定义？
4.1 3 个反向指标(出现就告警)
4.2 准入与淘汰门槛
一、什么是架构总览
| 它是什么 | 它不是什么 |
|---|---|
| 系统当前的"地图" | 系统的"历史"(那是 ADR) |
| LLM 自动生成的影子 | 人手画的"愿景图" |
| 给人和 Agent 共同消费的查询表 | 给人"读"的散文式设计文档 |
| 强结构化(图、表、清单) | 湿润化(大量解释文字) |
核心判断:架构总览 = 代码的影子,不是人写的文档。人手画的架构图 100% 跟代码脱节。LLM 从代码/配置/部署文件抽取,人 review,这是它和知识词典的本质区别——词典是"对齐",架构总览是"反射"。
二、架构总览的知识模板如何定义？
核心判断：强结构化,几乎全用表格/列表。 架构总览不是"读"的,是"查"的。核心包含5类模板：
| 模板 | 文件位置 | 内容 |
|---|---|---|
| 总览页 | 20-architecture/overview.md | 系统一句话、规模、技术栈、部署环境、更新时间 |
| 服务清单 | 20-architecture/services/[name].md | 每个服务一个文件 |
| 依赖图 | 20-architecture/dependency-graph.md | 服务间调用关系 |
| 技术栈矩阵 | 20-architecture/tech-stack.md | 服务 × 技术栈二维表 |
| 部署拓扑 | 20-architecture/deployment.md | 环境 × 部署方式 |
2.1 总览页设计
| 字段 | 类型 | 来源 | 必填 |
|---|---|---|---|
| 系统名称 | string | 配置 | ✓ |
| 业务域划分 | list | 代码 | ✓ |
| 服务数量 | number | LLM 自动 | ✓ |
| 主要技术栈 | list | LLM 自动 | ✓ |
| 部署环境列表 | list | K8s | ✓ |
| 上次自动生成时间 | datetime | 工具 | ✓ |
| 上次架构师 review 时间 | date | 人工 | ✓ |
2.2 服务清单字段(最重要的模板)
| 字段 | 类型 | 来源 | 必填 | 备注 |
|---|---|---|---|---|
| 服务名 | string | 服务注册 | ✓ | 唯一 |
| 业务域 | enum | 配置 | ✓ | 业务域分类 |
| 负责人 | @user/team | CODEOWNERS | ✓ | |
| 技术栈 | list | 代码 | ✓ | 语言/框架/DB |
| 主要职责 | string(≤30字) | LLM 草拟 + 人工审 | ✓ | 一句话 |
| 上游依赖 | list[link] | LLM 自动 | ✓ | 调用谁 |
| 下游被调用 | list[link] | LLM 自动 | ✓ | 谁调用我 |
| 关键 API | list[link] | 链接到 30-api/ | ✓ | |
| 部署位置 | list | K8s | ✓ | 哪些环境 |
| SLO | object | 监控 | × | 可用性/延迟 |
| 监控链接 | link | Datadog/Prometheus | ✓ | |
| 关联 ADR | list[link] | 人工补 | × | 关键决策 |
| 关联 Runbook | list[link] | 链接到 40-runbooks/ | × | 告警处理 |
| 关键路径标记 | enum | 人工标 | × | P0/P1/P2 |
| 最后更新 | datetime | 工具 | ✓ |
2.3 依赖图(dependency-graph.md)结构
| 元素 | 表示 | 数据来源 |
|---|---|---|
| 节点 | 服务 / 数据库 / 外部依赖 | 服务注册 + schema |
| 边 | 调用方向、协议、流量量级 | LLM 从 trace 抽 |
| 节点颜色 | 内部服务 / 外部 / 存储 | 规则化 |
| 边颜色 | 同步 / 异步 / 批处理 | 协议推断 |
| 关键路径高亮 | P0 服务和它们的链路 | 人工标 |
| 数据来源 | 自动生成 | 工具 |
| 上次生成时间 | datetime | 工具 |
2.4 技术栈矩阵(tech-stack.md)结构
| 务/组件 | 语言 | 框架 | 数据库 | 消息队列 | 缓存 | 部署方式 | 镜像 |
|---|---|---|---|---|---|---|---|
| api-gateway | Go | Kong + 自研插件 | — | — | Redis 7 | K8s | registry.example.com/gateway:v3.2.1 |
| user-service | Java 17 | Spring Boot 3.2 | MySQL 8.0(主从) | Kafka 3.6 | Redis 7 | K8s | registry.example.com/user:v2.8.0 |
2.5 部署拓扑(deployment.md)结构
| 环境 | 部署方式 | 入口域名/网关 | 数据隔离 | 监控告警通道 |
|---|---|---|---|---|
| local-dev(本地开发) | Docker Compose + Tilt | *.localhost:3000 | 每人独立 MySQL/Redis 实例,本地 mock 第三方 | 无(只本地 stdout 日志) |
| integration(集成测试) | K8s namespace(PR merge 自动部署) | integration.internal.example.com | 完全独立 cluster,合成数据,无生产数据 | Slack#alerts-integration(只 P0) |
| staging(预发) | K8s 独立 cluster(蓝绿) | staging.example.com | 与生产物理隔离,每日 02:00 从生产脱敏同步 | Slack#alerts-staging+ 值班人飞书(仅 P0/P1) |
三、架构总览的更新机制应该如何落地？
核心判断：架构总览 = 代码的影子。代码动,它动。没有自动化的影子,影子就是假的。包含4 个触发器：
| 触发器 | 触发条件 | 动作 | 责任方 |
|---|---|---|---|
| PR-ingest | PR 改动服务结构/依赖/部署配置 | LLM 重生成对应章节,diff 化,走 PR | 自动 |
| 每日重建 | 每日定时 | 全文重建,做 diff 检视 | 自动 |
| 重大变更触发 | 新服务/下线服务/关键依赖变化/改 SLO | 必须人工 review,可能触发 ADR | 人工 + LLM |
| 手动触发 | 架构师发现需要更新 | 立即触发重建 | 人工 |
3.1 关键设计点
| 设计点 | 具体要求 |
|---|---|
| 写入通道 | 所有生成走 PR(包括 LLM 自动) |
| 变更可见性 | PR 必须显示diff(哪变了),人 review 时只看 diff |
| 稳定时 auto-merge | 如果重建后无 diff,自动跳过 |
| 重大变更必人审 | 新服务/下线/关键依赖变化,SLA 24h 内 review |
| 日常变更抽样审 | LLM 自动审 10%,架构师扫一遍 |
| 每周全量 review | 架构师每周一次全量扫架构总览,10-30 分钟 |
| ADR 联动 | 重大变更 PR 自动建议"是否需要写 ADR" |
| 影子回写 Raw | 架构总览有"孤儿服务"时告警(代码里没有但总览里有) |
3.2 反模式
| 反模式 | 后果 |
|---|---|
| 让人手改架构总览 | 改完就脱节 |
| LLM 直接写主分支 | 失治理,2 周后没人信 |
| 不做 diff,全文覆盖 | 看不见"哪变了",review 不可能 |
| 重建频率太低(月级) | 期间变更会大量丢失 |
| 重建频率太高(分钟级) | 噪声淹没信号,review 疲劳 |
| 关键路径长期不标 | 值班时不知道 P0 路径,救火慢 |
四、架构总览的质量标准应该如何定义？
核心判断：架构总览的"质量" = 跟代码的同步度 + 关键信息完整度。不是"图漂不漂亮"。5 个核心指标：
| 指标 | 定义 | 健康值 | 测量方式 |
|---|---|---|---|
| 同步延迟 | 代码变更到架构总览更新的时间 | ≤ 24h | PR 时间戳 vs 重建时间戳 |
| 链接有效性 | 架构总览中所有链接 100% 解析 | ≥ 99% | 自动化 |
| 服务覆盖率 | 已部署服务在总览中出现的比例 | 100% | 对照服务注册 |
| ADR 关联率 | 关键决策(选型/架构)有 ADR 链接的比例 | ≥ 90% | 抽样审 |
| 关键路径标注完整度 | P0 服务都被标注关键路径 | 100% | 人工核查 |
4.1 3 个反向指标(出现就告警)
| 反向指标 | 告警触发 | 修复动作 |
|---|---|---|
| 漏抽 | 代码里有新服务但总览没有 | 触发"新服务检测"流水线,补源数据 |
| 幽灵服务 | 总览里有但服务注册里没有 | 触发"服务下线"检测,确认是否真下线 |
| 决策脱节 | 关键选型(语言/中间件)没 ADR 链接 | 提示架构师补 ADR |
4.2 准入与淘汰门槛
| 门槛 | 触发 | 动作 |
|---|---|---|
| 新服务准入 | 服务注册新增服务,但总览缺 | 自动告警,要求 owner 补全服务清单 |
| 服务下线淘汰 | 服务注册移除服务,但总览还在 | 30 天未处理,自动标 deprecated |
| ADR 缺失 | 关键决策无 ADR 链接 | 季度审查时列出,要求补 |
| 幽灵服务 | 总览有但运行时没有 | 立即告警,要么补回,要么归档 |