Architecture Intelligence Platform

架构智能平台

Agent 应该推理架构，而不是重新构建架构。

AIP 为编码 Agent 提供有证据支撑的架构上下文。

它会协调声明的 API 契约与观测到的运行时行为，让 Agent 能够区分：

• 已声明且已观测到的依赖；
• 在生产环境中发现、但没有任何文档记录的依赖；
• 在所选运行时窗口内未观测到的已声明关系；
• AIP 无法安全确认的事实。

每个回答都绑定到快照，并可追溯到证据。面向 Agent 的工具均为只读。 四款真实的编码 Agent 客户端已针对 v0.4.2 完成端到端认证，详见 v0.4.2 兼容性矩阵。自那以后， 尚未再次进行认证。

5 分钟演示 · 真实场景演示：Quarkus Super Heroes · MCP 工具 · 工作原理

MCP Registry： io.github.michaelegner/architecture-intelligence-platform

LegacyPricingService 从未被声明。AIP 在运行时观测到了该依赖，将其标记为 OBSERVED_ONLY，并将这一判断追溯到对应的 OpenTelemetry 证据。

⭐ 如果你希望解决为编码 Agent 提供有证据支撑的架构上下文这一问题，请为 AIP 点星。

视频讲解 · 评估 · 边界 · 文档 · 研究领域概览

五分钟快速体验

需要 Docker（含 Compose）、curl 和 jq。无需 LLM API 密钥——此流程不会调用任何模型：

git clone https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
cp .env.example .env
examples/runtime-demo/mcp-demo.sh

脚本会启动 AIP、Neo4j 和一个 OTel Collector，导入捆绑的示例架构，为一批时间戳固定的运行时遥测数据填充种子，然后通过纯 HTTP/JSON-RPC 依次调用 tools/list → get_architecture_drift → get_evidence——兼容的 MCP 客户端也会采用相同的请求路径。

查询 order-service 的 get_architecture_drift 会返回两条发现：

ProductService 和 PaymentService（通过 payment-q）的状态为 CONFIRMED——既有声明又有观察记录——因此不会出现在结果中：漂移检查返回的是差异，而非匹配项。列出全部四项依赖的工具是 get_service_dependencies。除了两条声明外，答案还包含一个 limitations 条目：AIP 拒绝为无法举证的 unused-q 指定消费者。随后，每条声明的 evidence_refs 都可通过 get_evidence，在相同的 snapshot_id 下解析为相应证据：声明其中一项的 asyncapi.yaml，以及观察到另一项的 OpenTelemetry 时间窗口。

{
  "snapshot_id": "aip:snapshot:v1:685a34157b6842b00d7130b8490df63060c3d80871c2ed6f56cd9206e62342d8",
  "outcome": "PARTIAL",
  "limitations": [
    {
      "code": "UNRESOLVED_IDENTITY",
      "message": "queue:unused-q has no single evidenced consumer service; retained as the direct queue target rather than guessed.",
      "claim_ids": ["aip:claim:v1:ca0dd73ba391552edd6d2cc06cddd919a8af97f362cdb47392e78325219fd612"]
    }
  ],
  "claims": [
    {
      "dependency": "unused-q",
      "via": "unused-q",
      "qualification": "NOT_OBSERVED_IN_WINDOW",
      "evidence_refs": ["evidence:asyncapi:order-service"]
    },
    {
      "dependency": "LegacyPricingService",
      "via": "GET /pricing/{sku}",
      "qualification": "OBSERVED_ONLY",
      "evidence_refs": ["evidence:otel:demo:2026-08-26:bfae54276215"]
    }
  ]
}

[
  {
    "id": "evidence:asyncapi:order-service",
    "evidence_type": "DECLARED",
    "source_type": "ASYNCAPI",
    "source_locator": "examples/order-service/asyncapi.yaml"
  },
  {
    "id": "evidence:otel:demo:2026-08-26:bfae54276215",
    "evidence_type": "OBSERVED",
    "source_type": "OPENTELEMETRY",
    "source_locator": "opentelemetry"
  }
]

由于每个填充的 span 都是固定的，而非根据时钟生成，因此两次干净运行会产生相同的判定和 snapshot_id。运行 examples/runtime-demo/mcp-demo.sh --down 可拆除相关服务。分步骤版本——逐条列出每个 curl 命令，并解释每个答案的含义——请参阅 examples/runtime-demo/hero-demo.md。

Quarkus Super Heroes：修改 fight 服务前，先了解它

五分钟演示使用的是一个小型合成系统。此演示使用真实的多服务系统 Quarkus Super Heroes，该系统通过了 AIP v0.5.0 的真实系统资格验证。任务是：修改 rest-fights 中的图像叙述前，我需要了解什么？ 一条命令即可重放已通过资格验证的证据。需要 Docker 和 curl；无需构建 Quarkus、Kafka、集群或模型密钥：

examples/quarkus-super-heroes-demo/run.sh

关于 rest-fights 的答案显示了七项操作级 CALLS，其中三项在运行时为 CONFIRMED，四项为 NOT_OBSERVED_IN_WINDOW，并显示通过已配置映射解析出的 DEPLOYED_AS。答案还显示了一个 PUBLISHES_TO Topic fights，它由明确披露的、由操作人员编写的 AsyncAPI 覆盖文件声明。其消费者仍明确标记为 UNRESOLVED_IDENTITY，而不是猜测得出。AIP 暂时无法回答的 gRPC 调用会被标记为不在答案范围内，而不会隐藏起来。

演示 README · 逐个问题的演练指南 · 依赖项的确立方式 · 记录的 Claude Code 对话

Pitstop：你即将更改的事件会发送给哪些服务？

本地试用 → · 公共托管实例现提供 Sokol111 数据集：试用托管版 →

另一个真实系统是 Pitstop，这是一个基于 RabbitMQ 的 .NET 车库管理示例，使用不同的代理和技术栈。任务是：替换 MaintenanceJobFinished 中的 StartTime 和 EndTime 之前，哪些接收方会从它所发布到的交换机接收消息，我还必须检查什么？ 一条命令即可重放一段已编写并冻结的观测时间窗口。它需要 Docker 和 curl；无需 .NET、RabbitMQ 或模型密钥：

examples/pitstop-demo/run.sh

询问发布者：AIP 会通过具名队列解析出该扇出交换机的五个接收方，其中一个（ReportingService）没有出现在任何 Pitstop 文档中，并提供相关证据和发布者的限定说明。它明确说明自己不掌握负载或字段级知识，因此你仍须检查哪个接收方会读取 StartTime。本地重放是可复现的运行模式。直到 v0.7.2 I2 之前，持续运行且经过插桩的 Pitstop 也会向公共托管 AIP 实例提供数据；该实例现在提供冻结的 Sokol111 Kafka 数据集（本地 --live 模式需要私有的插桩分支）。演示 README 中介绍了可选的 Claude Code 插件（以及一个可选的模组，可在 Agent 的计划旁显示 AIP 的回答）；两者都通过此仓库的 Claude Code marketplace 安装（claude plugin marketplace add michaelegner/architecture-intelligence-platform）。

演示 README · 逐个问题的演练 · 输入来源

你可以用它做什么

发现无人记录的依赖关系。 真实流量会揭示规范、清单或图表中都不存在的调用。AIP 会将其标记为 OBSERVED_ONLY，并注明观察到该调用的时间窗口——例如上方演示中的 OrderService -> LegacyPricingService。

检查你声明的架构是否与实际运行的架构一致。 系统会逐项报告依赖关系的偏差，并同时检查两个方向——已声明但未观察到，以及观察到但从未声明——且每项都会注明依据，而非直接断言。

为编码 Agent 提供可引用的上下文。 六个只读 MCP 工具会向 Agent 提供直接依赖、偏差、来源信息、调用方位置、API 消费者用法和 Kafka Topic 消费者信息；每项都绑定到一个图快照，因此它能区分事实与猜测，也绝不会写入它正在读取的模型。

将 AIP 连接到你的编码 Agent

无需亲自运行脚本化的 MCP 调用，即可准备好确定性演示：

examples/runtime-demo/mcp-demo.sh --serve

现在，AIP 已可通过 http://localhost:8000/mcp 使用。使用以下示例配置编码 Agent 客户端——配置语法已根据各客户端当前的官方文档进行验证。

符合资格的客户端／平台组合列于 v0.4.2 兼容性矩阵中。它们已针对 v0.4.2 完成资格验证，此后未重新验证。除非另有列明，否则其他组合均未经验证。

Codex CLI

codex mcp add aip --url http://localhost:8000/mcp

Claude Code

claude mcp add --transport http --scope local aip http://localhost:8000/mcp

{ "mcpServers": { "aip": { "url": "http://localhost:8000/mcp" } } }

{ "servers": { "aip": { "type": "http", "url": "http://localhost:8000/mcp" } } }

然后提问：

使用 AIP 查找 demo 环境中服务 service:order-service 在 2026-08-26T00:00:00Z 至 2026-08-27T00:00:00Z 期间的架构偏差。对于每条发现，说明其判定依据， 并使用同一快照解析其证据。不要推断 AIP 无法确立的事实。

预期的 AIP 发现：

• LegacyPricingService — OBSERVED_ONLY（运行时观察到，但从未声明）
• unused-q — NOT_OBSERVED_IN_WINDOW（已声明，在此时间窗口内未观察到——绝不能称为“未使用”或“已失效”）

以下是 Codex CLI 实时完成这一操作的演示：

这些说明适用于本地运行的客户端——托管／云端 Agent 通常无法访问你的 localhost。/mcp 不支持通过公共互联网进行身份验证；请在本地或可信网络中使用。此路径下，AIP 本身无需 LLM API 密钥；但你的客户端可能仍需要自己的密钥。

查看各客户端的详细设置、验证来源和清理说明 →

为什么？

更改服务的 Agent 需要了解该服务实际与哪些对象通信。目前，它通常从两个有问题的来源获取这些信息：可能已经与实际情况脱节的架构文档，以及根据上下文窗口中恰好出现的代码做出的貌似合理的推断。这两者听起来同样可信，却都无法让 Agent 区分事实与猜测。

AIP 根据已存在且作为日常开发一部分持续维护的证据来回答这个问题——OpenAPI／AsyncAPI 规范、用于描述规范无法表达的唯一信息（谁调用谁）的最小清单，以及可选的真实 OpenTelemetry 流量。依赖关系和偏差的回答会说明每项声明由哪些证据支持、运行时观察结果是否与声明一致，以及 AIP 无法确立什么：从未观察到的依赖会报告为未观察到，而绝不会报告为不存在；无法解析的身份也绝不会靠猜测。证据深入查看功能会在同一快照中解析这些证据引用，不会创建新的架构声明。

AIP 可以帮助 Agent 推理架构，但 Agent 绝不能成为架构事实的来源。——ROADMAP.md 中 v0.4 的原则

MCP 工具

AIP 通过标准的协商式 MCP 客户端初始化（参见边界），在 /mcp 暴露经过验证的架构模型，提供恰好六个只读工具：

这六个工具均不会写入图数据，也不需要 LLM API 密钥——整个工具集都是确定性的—— 而且它们都不会编造、猜测或擅自提升尚未解决的事实：证据不足时，会在 limitations 条目中明确说明，绝不会默不作声。

每个答案包含什么、答案依据什么，以及此工具集刻意不做什么： 见下文边界。完整参考文档（包括精确的 JSON-RPC 调用格式）： docs/mcp.md。

快速开始

如需运行整个平台（REST API、Service Explorer、MCP 端点），而不仅仅是演示：

cp .env.example .env
docker compose up

.env.example 中的 NEO4J_PASSWORD 是仅供本地使用的固定默认值（change-me-local）——用于试用没有问题，但绝不可用于可从本机外部访问的环境。

然后打开 http://localhost:8000。config.yaml 已指向此仓库 examples/ 中的示例服务，因此可以立即对它们调用 POST /api/import。关于如何在不使用 Docker 的情况下本地运行、运行测试套件和执行 lint，请参见 docs/development.md。

AIP 的工作原理

输入证据，输出经过限定的架构事实：

OpenAPI · AsyncAPI · architecture.yaml   (declared)
OpenTelemetry traces                     (observed)
        -> canonical model -> evidence-backed graph -> qualified claims -> MCP tools / REST / UI

手工维护的架构文档会逐渐过时，因为没有任何机制强制其与系统保持一致。AIP 从不存储缺少其生成证据的架构事实，因此声明和观察到的信号始终可区分，不会混为一谈，变成一种含糊不清的“真相”。

已声明与已观察

图中的每种关系都带有证据，其证据可以是 DECLARED（来自规范/清单）、OBSERVED（来自真实遥测），也可以两者兼有。这些证据会转化为相应状态：

移除过时的声明不会删除仍有观察证据的关系——而是会将其状态从 CONFIRMED 降级为 OBSERVED_ONLY。关于这一保证的精确不变量及其重要性，请参见 docs/graph-model.md。上文的依赖和漂移 MCP 工具会原样返回这些限定信息；输出过程中不会提升或淡化任何内容。

摄取

采用模块化 Python 单体架构（单个 FastAPI 进程）；Neo4j 是唯一的外部持久化依赖。摄取采用严格分阶段的管线——scan -> parse -> source-validate -> map to canonical model -> canonical-validate -> reconcile/diff -> transactional graph write——服务的导入要么完全成功，要么全部丢弃，不会留下部分结果。源适配器绝不会直接写入 Neo4j；它们都会先映射到同一个共享的 Canonical Model。完整详情，包括图谱／证据模型和所有 API 路由，请参阅：docs/architecture.md。

确定性分析

五项针对声明式架构的固定参数化 Cypher 分析（队列发送方／接收方、孤立队列、混合架构影响范围），以及五项针对声明数据与观测运行时数据的分析（实际观测到的内容、已确认的内容、仅观测到的内容、仅声明的内容，以及各服务的遥测覆盖情况）。这些分析都不涉及 LLM——完整列表及每项分析所回答的问题，请参阅 docs/analyses.md。

核心功能

• 通过六个只读 MCP 工具提供有证据支撑的服务依赖关系和架构偏差
• 将 OpenAPI、AsyncAPI 和 OpenTelemetry 证据协调到一个图谱中
• 队列和独立于来源的 Pub/Sub 语义。Topic 扇出仅通过显式声明的 Subscription 表示，Kafka 消费者组绝不会被视为 Subscription。
• 与快照绑定的来源追踪——每项声明都可追溯到生成它的规范文件、清单或观测时间窗口
• 确定性的声明数据与观测数据协调，支持跨批次 OTel 关联
• 谨慎处理缺失证据和未解析的身份——绝不猜测，也绝不静默丢弃
• 由 Neo4j 支持的架构模型，可选配 Service Explorer UI

查看架构和功能文档 → · 关联模式 →

示例

随附的 examples/ fixture 是一个小型的、完全合成的四服务场景：

其中包含 unused-q（没有接收方的发送方）和 unknown-producer-q（没有已知发送方的接收方），专门用于测试孤立队列分析。一次调用 POST /api/import 即可加载全部内容。

评估

AIP 使用独立编写的真实情况进行评估，而非根据 AIP 自身的输出生成预期结果，并以确定性的 PASS/FAIL 判定：

• 针对声明／观测关系事实的 10 个确定性场景
• 覆盖全部三个 MCP 工具的 23 个 ArchitectureAnswer 场景
• 两次干净的 ArchitectureAnswer 运行在语义上完全相同；hero 演示的 structuredContent 在重复干净运行中逐字节一致
• 基于 Quarkus Super Heroes 和 Apache Airflow 的真实系统验证

uv run python -m evaluation run       # ten relation-fact scenarios
uv run python -m evaluation answers   # 23 ArchitectureAnswer scenarios

无需 LLM 提供商密钥——这两套测试都不会触及自然语言查询层。完整场景列表、真实情况格式和失败报告示例，请参阅 evaluation/README.md。

在真实系统中进行测试

AIP 的模型还在两个并非为其设计的系统上接受了验证：Quarkus Super Heroes 和 Apache Airflow。重要的结果并非 AIP “发现了一切”，而是未支持和未解决的情况都明确保留， 而没有被转化为看似合理的架构事实。请参阅 docs/real-world-validation/README.md，了解 真实依据独立性规则、档案结构和各系统的发现。若要亲自探索 Quarkus 系统，请运行 Quarkus Super Heroes 演示。

使用 OpenTelemetry 获取运行时证据

AIP 将 OTLP 跟踪数据用作额外的遥测使用方，而不是替代你的可观测性后端。 它绝不能成为 OTel Collector 转发数据的唯一目标，而且 AIP 自身的可用性绝不能影响应用程序的正常可观测性：

捆绑的运行时演示会持续生成合成流量，并展示 CONFIRMED、 OBSERVED_ONLY 和 NOT_OBSERVED_IN_WINDOW 关系如何实时填充到 API 和 Service Explorer 中：

OpenTelemetry 集成 → · 运行时演示指南 →

可选的人类语言查询界面

POST /api/query 也能回答自然语言问题，供交互式探索使用——如果可能，会将问题路由到现有的确定性分析； 否则会使用 LLM 生成 Cypher，并且在查询 Neo4j 之前，必须通过严格的只读允许列表验证器。LLM 永远 不会持有写入凭据，生成的 Cypher 也始终会展示出来以便追溯。此功能完全可选——即使未配置 LLM 提供商， 平台也能正常工作，且没有任何 MCP 工具依赖此功能。请参阅 docs/semantic-validation.md。

边界

MCP 工具会返回什么，以及它们有意不返回什么。原有的三个工具共用下面的 ArchitectureAnswer 信封；第四个工具增加了单独版本化的 本地性契约，第五个工具增加了单独版本化的 API 消费者使用情况契约，第六个工具增加了目标消费者契约。

一个信封。 原有的三个工具返回相同的 ArchitectureAnswer（schema_version、producer、 tool、outcome、snapshot、observation_context、data、claims、evidence_refs、 limitations），并根据已发布的封闭 JSON Schema 进行验证。依赖和漂移答案会填充 claims/evidence_refs，而 get_evidence 会将证据记录解析到 data 中，并有意将顶层数组留空。

当前状态，而非历史记录。 每个答案都绑定到一个稳定的图快照标识——当前图状态的指纹，因此可以证明两个相关答案指向同一个已标识的图状态。没有历史或特定时间点查询接口；如果某个 snapshot_id 已不再是当前快照，则会返回 SNAPSHOT_NOT_AVAILABLE 限制，而不会基于过时数据作答。

明确的观测上下文。 对运行时敏感的依赖和漂移工具会在每个答案中携带环境和时间窗口；而 get_evidence 则有意不包含观测上下文，并要求提供明确的 snapshot_id。

仅限直接依赖。 仅限一跳——不进行传递式遍历，工具背后也没有通用的 Cypher 或图查询接口。

仅限已声明的 Pub/Sub。 Topic 和 Subscription 仅来自已声明的 AsyncAPI（或已配置的映射）。运行时遥测可以确认它们，但绝不会凭空生成；AIP 不支持对 Kafka、Azure Service Bus、Google Pub/Sub 或 RabbitMQ 进行实时 Broker 发现（参见 docs/ingestion.md）。

一种路径，一种连接模式。 /mcp 仅提供标准的协商式 MCP（参见 docs/mcp.md）；v0.4.x 直接信封已弃用，不符合有效协商式 MCP 流量要求的请求都会被拒绝。

本地或可信网络。 与 AIP 的其他部分一样，/mcp 面向本地或可信网络环境构建；它并未针对直接暴露于公共互联网而强化安全性——参见 docs/security-model.md。

文档

• docs/mcp.md — 面向 AI Agent 的六个只读 MCP 工具，以及可运行的 主打演示教程
• docs/architecture.md — 流水线、API 接口
• docs/canonical-model.md — 实体和确定性 ID
• docs/graph-model.md — 关系、事实/证据不变量、观测到的 PROVIDES
• docs/evidence.md — 来源、Evidence 节点、关联模式
• docs/ingestion.md — 声明的三个源适配器
• docs/analyses.md — A1-A5 和 O1-O5
• docs/semantic-validation.md — 自然语言查询流水线
• docs/opentelemetry.md — 运行时观测、属性允许列表、覆盖范围
• evaluation/README.md — 确定性评估套件：场景、真实情况格式、运行方法和失败报告解读
• real_world_validation/README.md 和 docs/real-world-validation/README.md — v0.3 真实场景验证规范：问题词汇表、expected.yaml 结构、档案结构
• docs/configuration.md — 所有设置及其默认值
• docs/security-model.md — 信任边界
• docs/development.md — 本地开发、测试、代码检查
• docs/adapter-development.md — 如何为 AIP 扩展新的数据源
• docs/reviews/architecture-review-0.4.0.md — v0.4.0 发布后的 架构评审：经受住考验的部分、四项结构性发现、实测读取成本
• docs/reviews/code-health-review-2026-10-08.md — v0.6.2 的代码健康度 和设计评审：五项按优先级排序的发现
• docs/product-doctrine-and-strategic-direction.md — 产品理念、语义边界、战略方向和路线图依据
• docs/adr/ — 架构决策记录：为何选择 Neo4j、为何采用规范模型、为何大模型只读且绝不作为事实来源等
• docs/specifications/ — 原始设计规范，记录平台发展至今的可追溯历史
• docs/landscape.md — 研究概况：形式化基础、相关平台、Agent 上下文、架构意图、治理和验证
• ROADMAP.md / CHANGELOG.md — 项目发展方向及已发布内容

参与贡献

开发环境设置、测试/代码检查/格式化命令以及适配器贡献指南，请参阅 CONTRIBUTING.md。问题和想法请发布到 讨论区；Bug 和功能请求请使用议题模板。请勿通过公开议题报告安全漏洞——请参阅 SECURITY.md。本项目遵循 贡献者公约。

项目状态

最新版本： v0.7.2 — 上下文引擎互操作性 + 产品边界限定。

尚未达到 1.0：REST/MCP 接口、图架构、规范模型、适配器 SPI 和配置格式仍可能在次要版本更新时发生变化。每次发布都会提供已发布制品验证记录—— docs/release-validation/v0.7.2-release-record.md 是最新记录。请参阅 CHANGELOG.md 了解每次发布的内容，并参阅 ROADMAP.md 了解后续计划。

许可证

根据 Apache License 2.0 版授权。 请参阅 LICENSE。第三方依赖项许可证：THIRD_PARTY_LICENSES.md。