vynazevedo/ARKHE

# ARKHE **架构即可执行模型——而非仅仅是图纸。**

你通过文本描述系统。ARKHE 将该文本编译为一个经过验证的模型：当架构违反规则时，它会在 CI 中使构建失败；直接从源码计算关键路径的 SLO；将模型与决策（ADR）关联；并检测模型与实际代码之间的漂移。图表、Mermaid 和交互式探索器仅仅是基于同一模型衍生出的视图。

_{同一个编译器运行在 CI、编辑器（LSP）和浏览器（WebAssembly）中——预览永远不会与 arkhe check 产生分歧。}

## 查看运行效果 一个模型，多种视图：从上下文到组件，支持缩放、正交布线，以及根据预算衡量的流程关键路径。

## 诞生背景 对市场工具（Structurizr, LikeC4, D2, Ilograph, Backstage, C4-PlantUML）的一项调研表明，目前没有任何工具能在单一的文本工件中实现以下功能： - **适应度函数（Fitness functions）是语言本身的构造**，而不是其他工具中的测试。`arkhe check` 会在失败时像类型检查（type-check）那样导致构建失败。 - **带契约的类型化关系**：协议、同步/异步/流式传输、数据类别、SLO。 - **从源码计算的静态 SLO**：基于关键路径的延迟和串联组合的可用性，无需 runtime。 - **模型与代码漂移检测**（`arkhe sync`）：提供收敛/发散/缺失的判定结论及基线锁定（ratchet），防止模型腐化。 - **带有截止日期的 ADR 和弃用机制**：到期后会自动转化为错误。 ## 安装 ``` go build -o arkhe ./cmd/arkhe go build -o arkhe-lsp ./cmd/arkhe-lsp ``` 需要 Go 1.26 或更高版本。无外部依赖。 ## 用法 ``` arkhe check examples/ecommerce.arkhe # valida; sai com 1 se houver erro (CI) arkhe fmt examples/ecommerce.arkhe -w # formata no estilo canônico (preserva comentários) arkhe json examples/ecommerce.arkhe # modelo semântico resolvido arkhe mermaid examples/netflix.arkhe play # diagrama Mermaid de uma visão arkhe html examples/ecommerce.arkhe -o out.html # explorador interativo, arquivo único arkhe sync examples/westack.arkhe --go examples/godemo # deriva modelo-vs-código arkhe playground # editor ao vivo no browser (WASM) ``` 路径可以是一个 `.arkhe` 文件或一个目录（加载所有文件并遵循 `import` 指令）。在 CI 中，架构即是测试： ``` - run: ./arkhe check arquitetura/ ``` ## 从源码计算的 SLO `arkhe html` 会生成一个单文件（约 50 KB，无 CDN）的浏览器视图，具备层级自动布局、正交布线、支持逐层下钻的缩放、按颜色区分类型的连线，以及一个源码面板。流程回放展示了每个步骤的延迟瀑布图与预算的对比——在这里 checkout 故意超过了 900 ms，因此 `check` 会导致构建失败。

## 实时 Playground ``` arkhe playground # código à esquerda, diagrama à direita ``` 类似于 Mermaid Live Editor 风格，但通过 WebAssembly **在浏览器中运行与 CI 相同的编译器**：预览永远不会与 `arkhe check` 产生分歧。诊断信息和 SLO 会随着每一次按键实时更新。

## 联合机制：组织级全景图 每个仓库对应一个 `.arkhe` 文件。每个项目对其自身的 C4 进行建模，并声明它暴露的内容（`expose`）、依赖的对象（`depends`）以及所属的 workspace（`workspace`）。ARKHE 将所有内容聚合到一个经过验证的图中——即组织全景图——其中项目被归组到各个 workspace（团队/领域）中，每个项目都是一个可导航的区块，而连线则连接了 workspace 内部及跨 workspace 之间的真实依赖。这就像 Backstage 风格的目录，但是经过验证的：组织级别的策略可以捕获并否决跨越仓库的违规行为。 ``` arkhe scan ./repos # agrega os .arkhe de vários projetos (landscape federado) arkhe server --root ./repos # serve o landscape ao vivo (Structurizr-in-Docker) arkhe server --github minha-org --token $GH_TOKEN # varre todos os repos de uma org ```

每个项目都会声明其 workspace、接口暴露面及其依赖关系： ``` meta { id "orders" } depends checkout system orders "Pedidos" { workspace "comercio" # agrupa o projeto no landscape expose service api "Orders API" # público: outros projetos podem referenciar service worker "Worker" # interno: encapsulado } orders.api -> checkout.api "inicia checkout" # aresta cross-projeto ``` 验证过程会跨仓库执行：`LNK001`（依赖了不存在的项目）、`LNK002`（引用了其他项目中未暴露的节点）、`LNK003`（无法解析的跨项目依赖）。你可以通过 Docker 运行：`docker run -v ./repos:/data -p 8080:8080 arkhe`；或者将其安装为 GitHub App（通过 `--app-id`/`--key`/`--installation` 进行身份验证），并在 `/webhook` 设置 webhook 以便在代码 push 时进行更新。 ## 目录：每个节点即一个实体 节点承载了平台团队所强制的目录元数据——负责人、关键程度、成本中心、类型和生命周期——并且验证机制会强制执行规范化卫生检查：一个没有负责人的关键系统会导致构建失败（`CAT001`），无效的值会产生警告（`CAT002`/`CAT003`）。该目录是从经过验证的 `.arkhe` 文件中衍生出来的，而不是从一个会逐渐腐化的平行 YAML 文件中获取的。 ``` system pagamentos "Pagamentos" { owner "@acme/plataforma" criticality critical # critical | high | medium | low costcenter "CC-1001" type service lifecycle production # production | experimental | deprecated } ``` 为了避免从零开始编写，`arkhe init` 可以根据 GitHub 仓库中的真实特征（描述、编程语言、topics、CODEOWNERS、OpenAPI）生成一份草案——团队成员只需审查并提交： ``` arkhe init acme/service-pagamentos -o service-pagamentos.arkhe arkhe check service-pagamentos.arkhe # o rascunho já passa na verificação ``` ## 自托管 Portal Portal 模式是一个具备独立前端的多组织架构目录：将其安装在一台机器上，通过 GitHub App 连接你的 GitHub 组织，然后即可浏览该目录（可按负责人、关键程度、成本中心、workspace 进行筛选），查看每个实体的页面（包括跨项目在内的传入与传出依赖关系、数据库 schema、诊断信息）以及经过验证的全景图。所有内容都直接读取仓库中的 `.arkhe` 文件：代码依然是唯一的真相来源。 ``` docker compose up -d # sobe portal + Caddy (TLS); persistência em SQLite por padrão ``` 首次访问时，Portal 会提示你创建管理员账号；随后只需连接一个组织（GitHub App 或 token），它就会扫描所有仓库中的 `.arkhe` 文件。数据持久化使用 SQLite（零配置，存储在一个 volume 中）；如需使用 Postgres，请通过 `--profile postgres` 启动并指定 `DATABASE_URL`。如果不使用 Docker，独立的二进制文件同样可以提供 Portal 服务： ``` arkhe server --db ./arkhe.db --port 8080 ``` 将 `.env.example` 复制为 `.env` 以配置域名（通过 Caddy 实现 TLS 自动化）、GitHub App 和 webhook 密钥。 ## 30 秒了解该语言 ``` kind agent { shape hex } contract AgentTask { taskId string channel string payload json } person cliente "Cliente" system westack "Escritório Virtual" { scope internal gateway edge "Edge / BFF" { tech "Next.js" source "westack/svc/edge" } service orquestrador "Orquestrador" { source "westack/svc/orquestrador" } broker barramento "Barramento" { tech "NATS" } agent sac "Agente SAC" { status experimental source "westack/svc/sac" } store memoria "Memory Layer" { tech "Redis" tag pii } } cliente -> westack.edge "abre" { p50 40ms p99 90ms availability 99.9 } westack.edge -> westack.orquestrador "cria" { proto gRPC p99 60ms availability 99.95 } westack.orquestrador ~> westack.barramento "evt" { contract AgentTask delivery at-least-once p99 15ms } flow "atendimento" { budget 600ms availability 99.5 cliente -> westack.edge "clica" westack.edge -> westack.orquestrador "CreateTask" westack.orquestrador ~> westack.barramento "publica" } policy "a borda não toca dados sensíveis" { forbid westack.edge -> tag:pii } policy "agente sempre por evento" { require * -> kind:agent as async } decision "adr-002" { status accepted affects westack.barramento } deployment prod "Produção GCP" { node gke "GKE Autopilot" place westack.edge on gke { replicas 3 } } view interno { title "Dentro do WeStack" of westack depth 2 } ``` 概念视图详见 [docs/LINGUAGEM.md](docs/LINGUAGEM.md)；EBNF 形式的正式语法详见 [docs/GRAMATICA.md](docs/GRAMATICA.md)。 ## 生态系统 | 工具 | 功能 | 详情 | |---|---|---| | `arkhe fmt` | 标准格式化工具，保留注释，幂等 | [LINGUAGEM.md](docs/LINGUAGEM.md) | | `cmd/arkhe-lsp` | 基于 stdio 的 Language Server：提供实时诊断、悬停提示、定义、引用、重命名、semantic tokens | [EDITOR.md](docs/EDITOR.md) | | `cmd/arkhe-mcp` | Model Context Protocol 服务器：允许 agent 查询架构（“哪个服务涉及 PII？”、“checkout 的关键路径是什么？”） | [MCP.md](docs/MCP.md) | | `arkhe playground` | 通过 WebAssembly 在浏览器中运行的实时编辑器 | [PLAYGROUND.md](docs/PLAYGROUND.md) | | `arkhe sync` | 基于 Go imports、AsyncAPI 和 OpenAPI 检测模型与代码的漂移，并带有基线锁定（ratchet） | 见下文 | ### 模型与代码漂移检测（`arkhe sync`） ``` arkhe sync modelo.arkhe --go ./src --asyncapi ./specs --openapi ./specs --baseline drift.json ``` - `--go`：Go imports 图（同步连线）。 - `--asyncapi`：publish/subscribe 频道（imports 无法察觉的事件连线）。 - `--openapi`：检查声明的 endpoint 与实际暴露的路由是否一致。 每一条连线都会收到一个判定结论：收敛/发散/缺失。`--baseline` 会应用基线锁定（ratchet）机制：只有新增的漂移才会导致构建失败。 ### 真实规模的示例 - `examples/ecommerce.arkhe`：Amazon 风格的在线交易平台（37 个节点，DDD bounded contexts，契约，多区域部署）。故意未通过 SLO001（预算）和 AVL001/AVL004（可用性和 us-east-1 的共享故障域）检查。 - `examples/netflix.arkhe`：Netflix 风格的流媒体平台（Open Connect, Zuul, playback, DRM, Kafka pipeline）。在预算范围内通过检查，但带有弃用（Hystrix）和故障域警告。 - `examples/c4-banking.arkhe`：经典的 C4 示例（网上银行），支持在上下文/容器/组件层级间导航浏览。 ## 解释器架构 采用符合 Go 惯例的布局，遵循标准库的约定（go/token, go/scanner, go/ast, go/parser, go/types）： ``` cmd/arkhe/ binário CLI (check, fmt, json, mermaid, html, sync, playground) cmd/arkhe-lsp/ servidor Language Server (stdio) cmd/arkhe-mcp/ servidor MCP para agentes (stdio) cmd/arkhe-wasm/ mesmo compilador em WebAssembly (playground no browser) internal/ token/ tipos de token e posições lexer/ scanner ast/ árvore sintática parser/ parser recursivo-descendente format/ formatter canônico (arkhe fmt) diag/ diagnósticos model/ modelo semântico e resolvedor de nomes qualificados check/ fitness functions (validação) slo/ confiabilidade (caminho crítico, disponibilidade, domínio de falha) drift/ deriva modelo-vs-código (Go, AsyncAPI, OpenAPI) render/ json, mermaid, html, engine.js (diagrama) e playground (WASM) loader/ carga multiarquivo com import lsp/ lógica do Language Server mcp/ lógica do servidor MCP (consulta da arquitetura) ``` Playground 内嵌了 `internal/render/arkhe.wasm`。每当解释器发生更改时，请使用 `make wasm` 重新生成它。 ## 测试 ``` go test ./... ``` 涵盖了限定名称解析、多文件合并、每一个诊断代码、SLO 引擎（关键路径、可用性、故障域）、三种来源的漂移判定结论、格式化工具以及 Language Server。 ## 许可证 [MIT](LICENSE) © Vinicius Azevedo。

标签：AI工具, DevOps工具, EVTX分析, Go语言, SOC Prime, WebAssembly, 云安全监控, 开发工具, 日志审计, 架构即代码, 程序破解, 请求拦截, 静态分析