ArchGraph

一个由你定义本体的知识图谱框架 —— 通过一个统一的 MCP 接口接入你的编码 Agent。

English · 简体中文

面向在真实代码库上运行编码 Agent 的团队，ArchGraph 让 Agent 在一张**意图图谱（intent graph）上拥有持久、分层的长期记忆 —— 这是一张带版本的架构图，记录系统为什么长成这样，而不只是长什么样。你和 Agent 通过一个 MCP 服务端（MCP = Model Context Protocol，让 AI 工具把外部服务当作工具调用的开放标准）来读写它。图谱的形态由本体（ontology）**决定 —— 也就是元素与关系类型的词汇表 —— 而这套本体由你定义。内置默认是 ArchiMate 3.2 + ARGO 扩展，其中 ArchiMate 是一套标准的企业架构建模语言，ARGO 是 argo-deploy 与 argo-init 命令背后的工具链与 Agent 工作流层。一个仓库可以接入自己的本体 —— 本仓库就是这么做的。一次安装，一个接口，学一次。

准备好试一试了吗？直接跳到 构建你自己的图谱。

安装 · 构建你自己的图谱 · 为什么选择 ArchGraph · 能力总览 · 文档 · 社区

这是什么？

如果你在真实代码库上运行编码 Agent，那么每个会话都是「冷启动」，而系统背后的「为什么」无处安放。ArchGraph 让一张架构图成为唯一的事实来源 —— Agent 的记忆与产品的设计合于同一个模型。你只需安装并学习一个 MCP 接口：Agent 在会话开始时恢复上下文，在需要时召回细节，并复用已知内容而不是重复创建（若确实要建重复项，必须显式确认）。

• 架构师 / 技术负责人 —— 用一张模型同时描述产品、工具链与 Agent。
• Agent 使用者 —— 会话开始时记忆已恢复，需要时按需召回，复用而非重复。
• 平台团队 —— 一个接口，部署进你已在使用的编辑器。

→ 完整上手：docs/getting-started.html

为什么选择 ArchGraph

每个运行编码 Agent 的团队都会撞上同一堵墙：代码在仓库里，但代码背后的推理无处安放。常见的四种做法各有用武之地，但都撑不了多久。

真正的差异不在于「自定义 vs. 锁定」。Protégé/OWL、Neo4j、TerminusDB、Archi/EA 都允许你扩展模型或自带词汇。而在于 ArchGraph 把本体做成一个一等公民、受校验、运行时解析的 schema bundle，并把它放在一个 Agent 既能读又能写的 MCP 接口之后，且内建类型化去重与提交可追溯。

包含成本的诚实对比只放在一个权威位置 —— docs/capabilities.html#compare。

自带本体

只会说一种语言的知识图谱框架，称不上框架。ArchGraph 把内核与本体分离：仓库在 .argo/schema/ 下放一份 schema bundle（元素/关系类型、端点规则、actor 契约、可选 guide），校验、MCP 指引与 .qea 投影都会随之改变。一份 bundle 可以 extends: "default" —— 继承内置的 ArchiMate 3.2 + ARGO 扩展 —— 再追加自己的类型；无需改动框架。

本仓库就是证明：它自己的 bundle 用 extends: "default" 并叠加了一份 UML 2 状态机 profile，在运行时从 .argo/schema/ 解析，而不是硬编码在框架里。

→ 一个完整示例 —— 定义本体后一步步建图：docs/case-team-graph.html · 预置本体目录：custom-schema/（Team Graph · Finance CDM · Industry 4.0 AAS · STIX Threat Intelligence · UML 2 · SysML · IPD · Mathematics）· 完整编写参考（类型、关系结构、公理/约束）：docs/ontology-authoring.md

本体校验（可选）

你的 schema bundle 已经能约束端点规则。ArchGraph 还能更进一步，在框架既有的校验时机上运行一个真正的本体 / 推理引擎 —— 写入时（本次变更的增量子图）与初始化时（整张图）—— 以捕捉仅靠 schema 无法发现的问题：

• 逻辑矛盾（OWL 不一致 —— 例如一个元素同时属于两个互斥类型，或单值槽位被赋了两个值），以及
• 约束违规（SHACL，由你的端点矩阵编译而来）。

它是可选的、默认关闭；一旦启用则是失败即阻断（fail-close） —— 已配置但不可用的引擎会被视为阻断性错误，而不是默默通过（咨询类校验器可以按条目用 onError: "warn" 选择退出）。

启用它。

argo-deploy -EnableOntologyValidation

这会把两个键写进 ~/.argo/.env（也就是部署器配置的同一个文件）—— 你不用手动编辑：

ARGO_ONTOLOGY_PYTHON=python
ARGO_VALIDATION_EXTENSIONS=[{"name":"ontology","timings":["write","init"],"command":["node","<argo>/scripts/ontology-projection/cli.js","--workspace","{workspaceRoot}","--graph","{graphPath}","--mode","{mode}"]}]

然后重启你的编辑器 / 宿主，让 MCP 服务端重新加载 ~/.argo/.env。要关闭它，清空 ARGO_VALIDATION_EXTENSIONS 这一行（或部署时不带该标志）并重启即可。

依赖。 引擎是 pySHACL + owlready2/HermiT。部署器会替你安装这些 Python 包（pyshacl、owlready2）；Python 3 与一个 JRE 是前置条件 —— 若缺任一，部署会带告警停止（它绝不会擅自安装系统运行时），请先装上再重跑 argo-deploy。传 -SkipOntologyEngine 可完全跳过引擎步骤。

验证。

Get-Content "$env:USERPROFILE\.argo\.env" | Select-String ARGO_VALIDATION_EXTENSIONS   # macOS/Linux 上是 ~/.argo/.env
python -c "import pyshacl, owlready2; print('ok')"

这个扩展点是开闭的：任何遵守这份小契约的外部校验器（argv 令牌 {workspaceRoot} / {graphPath} / {mode}；从环境读取变更后的文档与被触碰的 id；打印 {errors, warnings}）都可以作为一条条目加入 ARGO_VALIDATION_EXTENSIONS —— 无需改动框架。规范：argo/scripts/ontology-projection/EXTENSION_PROTOCOL.md。

安装

前置条件：Node.js ≥ 18（ARGO 工具链与 MCP 服务端都跑在 Node 上）。

npm install -g archgraph-argo
argo-deploy

argo-deploy 会注册 argo MCP 服务端，并把 skills 与 rules 安装进 GitHub Copilot、Cursor、OpenCode、DeepSeek Harness、OpenClaw 和 Codex（agents 只在支持它的宿主上安装）。随后它会提示你填写 ~/.argo/.env 里的少量设置。部署完成后，重启你的编辑器 / 宿主，让它重新加载 MCP 服务端。语义查询还需要 Neo4j 与一个 embedding 端点 —— 见 构建你自己的图谱。

快速开始

只有一条权威起点：构建你自己的图谱 —— 装一次，然后选路线 A（默认本体）或路线 B（你自己的本体）。那一节包含每一步与每个 MCP 调用；这里刻意不再放第二份副本，所以只有一条路可走。

**唯一开箱即用之外的前置条件：**语义（Graph RAG）检索需要一台 Neo4j 实例与一个 OpenAI 兼容的 embedding 端点。上下文读取、写入与 Enterprise Architect 互操作无需它们；Cypher（Neo4j 的图查询语言）结构投影与全部语义检索则需要 Neo4j。

构建你自己的图谱

二选一。一切都在你的编码 Agent 与 ARGO MCP 服务端之间完成；你唯一需要亲自运行的命令就是安装。初始化之后，意图图谱就是唯一的事实来源。

路线 A —— 默认本体（最快）

无需本体工作：使用内置的 ArchiMate 3.2 + ARGO 扩展。

1. 安装（一次）。 需要 Node.js ≥ 18。

   npm install -g archgraph-argo
   argo-deploy

   然后重启你的编辑器 / 宿主，让它重新加载 MCP 服务端。

2. 初始化。 让你的编码 Agent 运行 argo-init（工作区初始化 CLI）。它会创建并校验起始的 design/KG/SystemArchitecture.json，其中已经包含名为 SystemArchitecture 的项目根视图。

3. 添加元素与关系。 让你的编码 Agent 调用 applySystemArchitectureMutation，把每个新元素与关系挂到项目的既有根视图上 —— 先让它解析该视图真实的 view_id（queryNeo4jGraph / getArchitectureViewContext）。不要预建视图：一个名为 SystemArchitecture 的新视图会与 argo-init 创建的那个冲突，此后任何指向别的 id 的 view_ids 都会失败。

4. 验证。 让你的编码 Agent 调用 validateSystemArchitecture，再用 {"schema": true} 调用 queryNeo4jGraph 确认生效的元素与关系类型。

路线 B —— 你自己的本体

1. 安装（一次）。 同路线 A。

2. 编写你的 schema。 把你的建模语言放到 .argo/schema/ 下。一份独立 bundle —— 一个完整的 SystemArchitecture.schema.json，编辑其两个 $defs 枚举数组 archimateElementType 与 archimateRelationshipType —— 还必须在 schema-bundle.config.json 中声明 actorElementType，设为你某个元素类型（若你的 schema 确实没有 actor 概念则设为 null），否则会加载失败即阻断（bundleValidation.status: "failed"），校验/写入都会被阻塞。仅 extends: "default" 的 bundle 只需那份 config。schema-bundle.rules.json 保持可选（没有它时端点检查较为宽松）。

3. 自己编写图谱。 使用自定义 schema 时，argo-init 不会创建图谱 —— 打包的默认图与你的词汇不匹配 —— 它会失败即阻断并报 NO_DEFAULT_GRAPH。在任何 MCP 写入之前，手工创建 design/KG/SystemArchitecture.json，使用你自己的元素与关系类型以及你自己的根视图。然后让你的编码 Agent 运行 argo-init 来校验它。

4. 加入你自己的根视图。 让你的编码 Agent 调用 applySystemArchitectureMutation，把每个元素与关系挂到你编写的根视图上（而不是默认那个）。

5. 验证。 让你的编码 Agent 调用 validateSystemArchitecture，再用 {"schema": true} 调用 queryNeo4jGraph。

完整图文、分步的走查见 docs/case-team-graph.html（中文），预置示例 bundle 收录于 custom-schema/。结果看起来是这样：

能力总览

每一行都链接到一个简短的页面 —— 这是地图，不是手册。

• 分层长期记忆 —— 会话开始时一份紧凑的工作记忆，按需召回一份长期记忆，以及一个归档。
• 可插拔本体 —— 交付你自己的 schema bundle；默认（ArchiMate 3.2 + ARGO 扩展）是数据，不是代码。
• 语义 + 结构检索 —— Graph RAG 召回，加上只读 Cypher 精确查询结构。
• 去重写入 —— 复用既有的元素、关系或视图，而不是复制它；近似重复会作为候选被拦下。
• 验收测试先行 + 可追溯 —— 每次改动都可测试，且 commit id 会登记回元素。
• Enterprise Architect 互操作 —— 图谱投影为 .qea；人类在 EA 里的编辑以语义 diff 返回。
• 联邦图谱共享 —— 主权图谱通过注册中心–代理（registry–broker）互联；读取经授权并按引用返回。
• 一个 MCP 接口，六个宿主 —— 装一次，在 Copilot、Cursor、OpenCode、DeepSeek Harness、OpenClaw 与 Codex 中运行。

如何使用

初始化一次（argo-init），然后打开你的项目，让你的编码 Agent 干活。它会：

1. 在改动任何东西之前，先定位任务背后的架构元素，
2. 用该元素的 Skills 与 Rules 武装自己，
3. 测试先行（GIVEN-WHEN-THEN），并把每个 commit 追溯到图谱，
4. 默认复用既有元素 —— 近似重复需要显式确认。

意图架构图就是唯一的事实来源。

支持的宿主

| 宿主 | MCP | Skills | Rules | Agents | |---------|:---:|:------:|:-----:|:------:| | GitHub Copilot | ✓ | ✓ | ✓ | ✓ | | Cursor | ✓ | ✓ | ✓ | ✓ | | OpenCode | ✓ | ✓ | ✓ | ✓ | | DeepSeek Harness | ✓ | ✓ | ✓ | ✓ | | OpenClaw | ✓ | ✓ | ✓ | — | | Codex | ✓ | ✓ | ✓ | — |

一次 argo-deploy 即可注册 argo MCP 服务端，并把全部产物自动安装进每个宿主。

跨项目读写

跨项目访问走两条独立通道 —— 不能混为一谈：

1. 本地路径 —— 每次调用传 workspaceRoot，读取同机上一个对等项目的图谱。写入按设计只读：外部写入会被拒绝并返回 WORKSPACE_WRITE_DENIED。
2. 联邦 —— 每次调用传 projectId，经联邦中心路由，在其处授权（默认拒绝），并按引用返回。

本地通道是否可用取决于宿主，因为宿主可能桥接 MCP 服务端并按调用固定工作区：

| 宿主 | 本地读（workspaceRoot） | 本地写 | 联邦读（projectId） | |---------|:----------------------------:|:-----------:|:----------------------------:| | OpenCode | ✓ | blocked（WORKSPACE_WRITE_DENIED） | ✓ | | Codex | ✓ | blocked（WORKSPACE_WRITE_DENIED） | ✓ | | DeepSeek Harness | ✗ | ✗ | ✓ | | GitHub Copilot | ✓ | blocked（WORKSPACE_WRITE_DENIED） | ✓ | | Cursor | 待测 | 待测 | ✓ | | OpenClaw | 不涉及 | 不涉及 | ✓ |

DeepSeek Harness 无法做本地跨项目访问：它的桥接固定了会话工作区，请求不会按原样到达服务端，只有联邦通道可用。

社区

ArchGraph 建立在开放共建之上：在项目间分享与复用架构子图。分享是联邦式的 —— 每个项目保持图谱主权，成员通过引用进行注册、发现、授权与读取已开放内容（默认拒绝；不复制、不合并）。中心是一个注册中心–代理，只保存联邦元数据，从不保存内容。

• 社区站点 —— https://argo.derekworkspacev5.com/archgraph/
• graph-wiki（图谱资产之家）—— https://github.com/derekhu0002/graph-wiki
• GitHub —— https://github.com/derekhu0002/archgraph

文档

• 使用介绍 · 能力总览 · 完整案例：Team Graph
• Schema bundles / 本体解耦 · 自建 embedding 部署 · MCP 验收
• 洞察 —— GraphRAG、Agent 记忆与可移植技能。

许可证

Apache License 2.0