Agent开发系列（十）-知识库建设（架构总览）

[2.1 总览页设计](#2.1 总览页设计)

[2.2 服务清单字段(最重要的模板)](#2.2 服务清单字段(最重要的模板))

[2.3 依赖图(dependency-graph.md)结构](#2.3 依赖图(dependency-graph.md)结构)

[2.4 技术栈矩阵(tech-stack.md)结构](#2.4 技术栈矩阵(tech-stack.md)结构)

[2.5 部署拓扑(deployment.md)结构](#2.5 部署拓扑(deployment.md)结构)

[3.1 关键设计点](#3.1 关键设计点)

[3.2 反模式](#3.2 反模式)

[4.1 3 个反向指标(出现就告警)](#4.1 3 个反向指标(出现就告警))

[4.2 准入与淘汰门槛](#4.2 准入与淘汰门槛)

一、什么是架构总览

核心判断 :架构总览 = 代码的影子,不是人写的文档。 人手画的架构图 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`	环境 × 部署方式

务/组件	语言	框架	数据库	消息队列	缓存	部署方式	镜像
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

环境	部署方式	入口域名/网关	数据隔离	监控告警通道
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(包括 LLM 自动)
变更可见性	PR 必须显示 diff(哪变了),人 review 时只看 diff
稳定时 auto-merge	如果重建后无 diff,自动跳过
重大变更必人审	新服务/下线/关键依赖变化,SLA 24h 内 review
日常变更抽样审	LLM 自动审 10%,架构师扫一遍
每周全量 review	架构师每周一次全量扫架构总览,10-30 分钟
ADR 联动	重大变更 PR 自动建议"是否需要写 ADR"
影子回写 Raw	架构总览有"孤儿服务"时告警(代码里没有但总览里有)

核心判断：架构总览的"质量" = 跟代码的同步度 + 关键信息完整度。不是"图漂不漂亮"。5 个核心指标：