架构文档最容易在代码变更之后失效。全球银行间经纪商面对的是规模较大的 .NET 代码库、多个团队和持续交付流程，手工维护系统上下文、组件关系和设计说明很快就会变成负担。
一种更可持续的做法，是把架构文档当成软件交付产物：从代码仓库读取事实，用 Amazon Bedrock AgentCore 承载分析代理，生成架构图和说明文档，再通过 Amazon Bedrock Knowledge Bases 建立可搜索入口，并由 AWS CodePipeline 触发更新。
把文档更新放进交付链路
这类方案的关键不只是让大模型“画一张图”，而是把代码、分析结果、文档和索引串成一个可重复执行的流程：
- 代码提交触发 AWS CodePipeline。
- 构建任务扫描 .NET 项目、配置文件和基础设施描述。
- AgentCore 中的代理根据扫描结果识别服务、依赖、入口、数据访问和外部集成。
- 代理输出结构化架构事实，以及 Mermaid 或其他格式的图表定义。
- 生成的 Markdown、JSON 和图表文件写入文档目录或对象存储。
- Knowledge Bases 对新的文档执行摄取，让工程师可以用自然语言检索架构信息。
这里有一个重要边界：模型应该负责归纳和解释，代码扫描器应该负责提供可验证的事实。不要把整个仓库直接丢给模型并期待它永远正确。项目文件、命名空间、依赖声明和调用关系应尽量先转换为结构化输入，再交给代理分析。
AgentCore 适合放在哪里
AgentCore 可以作为架构分析代理的运行环境。代理可以接收代码清单、依赖图、配置摘要和历史文档，然后执行几个相对清晰的任务：
- 识别应用边界，例如 Web API、后台任务、消息消费者和共享类库。
- 归纳组件之间的调用、发布订阅或数据访问关系。
- 标记外部系统，例如数据库、消息队列、身份服务和第三方 API。
- 生成架构决策记录、上下文说明和变更摘要。
- 输出适合渲染的 Mermaid 图表，而不是只返回一段难以验证的自然语言。
代理提示词可以要求输出固定 JSON 结构，例如 services、dependencies、external_systems 和 evidence。其中 evidence 用来记录结论来自哪个文件或项目，方便审查人员回到源代码核对。
一个可实践的提示词骨架如下：
你是架构分析代理。请根据输入的 .NET 项目清单和依赖事实生成架构文档。
约束：
1. 只能把输入中存在的类型、项目和依赖声明作为事实。
2. 不确定的关系放入 unknown_relations，不要猜测。
3. 每个服务和依赖都必须包含 evidence 文件路径。
4. 输出合法 JSON，不要输出 Markdown 围栏。
输出结构：
{
"services": [],
"dependencies": [],
"external_systems": [],
"unknown_relations": [],
"mermaid": "..."
}
先提取事实，再生成图表
下面的脚本是一个最小可运行示例。它扫描当前目录下的 .csproj 文件，提取项目名称、目标框架和项目引用，生成 architecture-inventory.json。这不是完整的 C# 语义分析器，但足以作为 CodeBuild 阶段的起点，也能作为 AgentCore 代理的结构化输入。
运行前请把脚本放在 .NET 仓库根目录下，并确认 Python 3.9 或更高版本可用：
#!/usr/bin/env python3
import json
import sys
from pathlib import Path
import xml.etree.ElementTree as ET
def text_without_namespace(element, tag):
for child in element.iter():
if child.tag.rsplit("}", 1)[-1] == tag:
return child.text or ""
return ""
def scan_project(path: Path):
root = ET.parse(path).getroot()
project_name = path.stem
target_frameworks = []
references = []
for child in root.iter():
tag = child.tag.rsplit("}", 1)[-1]
if tag in {"TargetFramework", "TargetFrameworks"} and child.text:
target_frameworks.extend(
value.strip() for value in child.text.split(";") if value.strip()
)
elif tag == "ProjectReference":
include = child.attrib.get("Include")
if include:
references.append(str((path.parent / include).resolve()))
return {
"name": project_name,
"path": str(path),
"target_frameworks": target_frameworks,
"project_references": sorted(references),
}
def main():
root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
projects = [scan_project(path) for path in sorted(root.rglob("*.csproj"))]
result = {"repository": root.name, "projects": projects}
output = root / "architecture-inventory.json"
output.write_text(json.dumps(result, indent=2), encoding="utf-8")
print(f"wrote {output} with {len(projects)} projects")
if __name__ == "__main__":
main()
生成的 JSON 可以继续交给 AgentCore 代理。代理输出的 Mermaid 内容则可以存成 docs/architecture.mmd，例如：
flowchart LR
Web[Trading Web API] --> Core[Brokerage Core]
Worker[Settlement Worker] --> Core
Core --> DB[(Relational Database)]
Core --> Bus[Message Broker]
Bus --> Worker
生产环境中还可以加入 Roslyn 分析、依赖包解析、ASP.NET 路由提取和数据库访问识别。不过每增加一种分析能力，都应该同时增加证据字段和测试样例，避免图表看起来完整却无法追溯。
用 CodePipeline 触发生成和索引
可以把构建任务拆成三个阶段：分析、文档生成、发布与索引。下面是一个可改造的 buildspec.yml 示例。AgentCore 调用方式和 Knowledge Bases 的资源标识取决于具体部署方式，因此示例通过环境变量保留这些配置，并明确标记了需要替换的命令。
version: 0.2
phases:
install:
runtime-versions:
python: 3.11
build:
commands:
- python scripts/scan_dotnet.py .
- mkdir -p generated-docs
- cp architecture-inventory.json generated-docs/
- python scripts/invoke_architecture_agent.py architecture-inventory.json generated-docs/architecture.md
- test -s generated-docs/architecture.md
post_build:
commands:
- aws s3 sync generated-docs/ "s3://${DOCS_BUCKET}/architecture/" --delete
- >-
aws bedrock-agent start-ingestion-job
--knowledge-base-id "${KNOWLEDGE_BASE_ID}"
--data-source-id "${DATA_SOURCE_ID}"
--region "${AWS_REGION}"
artifacts:
files:
- generated-docs/**/*
部署时需要重点处理以下配置：
DOCS_BUCKET指向文档源数据存储位置，并限制写入权限。KNOWLEDGE_BASE_ID和DATA_SOURCE_ID指向已经配置好的 Knowledge Bases 数据源。- CodeBuild 或 AgentCore 执行角色只授予读取代码、写入指定前缀和启动摄取任务所需的权限。
- 文档生成失败时让构建失败，避免把半成品索引成正式架构信息。
- 对生成结果进行格式校验，例如检查 JSON Schema、Mermaid 语法和必需的证据字段。
invoke_architecture_agent.py 可以实现为调用团队已经部署的 AgentCore 入口。调用协议取决于所使用的 AgentCore 运行方式，推荐让它接收一个小型 JSON 文档，并返回同样可校验的结构化结果，而不是直接处理整个 Git 工作区。
搜索体验取决于文档结构
把 Markdown 上传到 Knowledge Bases 并不等于自动得到好的架构搜索。文档需要具有稳定的标题、清晰的实体名称和足够的上下文。可以为每个服务生成一份独立文档，至少包含：
- 服务职责和不负责的范围。
- 入口，例如 HTTP 路由、消息主题或定时任务。
- 上游、下游和外部系统。
- 数据存储及访问方式。
- 最近一次生成时间和代码版本。
- 每个关键结论对应的文件路径和行号范围。
这样，工程师询问“结算任务由哪个服务消费消息”时，检索结果不只是返回一张图片，而是返回服务说明、消息关系和源代码证据。架构图适合快速建立全局视野，文本证据适合排查和审计，两者需要同时保留。
还要注意文档版本和权限问题。代码库可能包含内部系统名称、数据库表名或敏感配置线索。进入 Knowledge Bases 的内容应先经过密钥过滤、敏感信息检测和访问控制，不能因为文档生成自动化就跳过原有的数据治理流程。
落地时检查这几件事
这类自动化管道的价值在于持续更新，而不是一次性生成一套漂亮图片。落地前可以检查：
- 代码事实是否与模型推断分开保存？
- 每条架构结论是否能追溯到仓库文件？
- 生成失败是否会阻止错误文档发布？
- CodePipeline 是否覆盖主干和需要文档更新的分支策略？
- Knowledge Bases 是否有明确的数据源、权限和删除策略？
- 文档是否同时服务于架构师、开发者和运维人员？
- 是否为常见项目类型准备了回归样例，例如 API、Worker、类库和消息消费者？
采用 Amazon Bedrock AgentCore 的合理切入点，是先选择一个边界清楚的 .NET 系统，建立“扫描事实、生成文档、审查差异、更新索引”的闭环，再逐步扩大代码覆盖范围。模型可以显著减少整理和解释成本，但最终的架构可信度仍来自可验证的代码证据、稳定的流水线和明确的人工审查边界。