使用介绍 · Getting Started

给新用户的入门指南

这份文档面向第一次接触 ArchGraph 的人：先讲清它是什么、能为你做什么，再一步一步带你安装、配置、初始化，最后说明日常使用时你的 coding agent 会自动替你做什么。跟着读一遍，你就能把第一个项目跑起来。

这是什么 / 能为你做什么

ArchGraph 是给 AI coding agent 用的「长期记忆」。它把你的项目架构建模成一张 意图图谱（intent graph），并通过一个统一的 MCP 接口让 agent 读写： agent 不用每次把整个项目重新读一遍，就能恢复上下文、找到「这个任务对应架构里的哪个元素」，然后在改动前先定位、改动后把 commit 登记回图谱。默认用 ArchiMate 3.2 + ARGO 扩展 建模，但它也支持换成你自己的业务本体（见建模自己的东西）。

一句话：它让 agent 的记忆变成一张干净、可查、可追溯的架构图，而不是一堆散落的文件。 写入会自动去重，所以图谱不会越用越乱，语义检索也能一直保持准确。

它既不是「把上下文散在文件里」，也不是「只做语义召回的向量库」，也不是「把模型与 agent 读写路径分开」的通用图/本体工具 —— 关键差别在于：本体是一个一等公民、受校验、运行时解析的 schema bundle，而读和写都走同一个 MCP 接口。看与其他做法的对比（含 ArchGraph 自身成本）→

适合谁

希望让 coding agent 更「懂项目」、少走弯路的开发者。
需要把架构决策、验收测试、提交记录沉淀成可追溯资产的项目负责人。
想用自己业务领域的本体来建模（而不是通用 ArchiMate）的团队。
愿意在 GitHub Copilot / Cursor / OpenCode / DeepSeek Harness / OpenClaw / Codex 里工作的用户 —— 我们一次部署覆盖全部宿主。

前置条件

用大白话说：大部分功能开箱即用，只有「结构化查询」和「语义检索」需要额外配置。 下面三样东西里，Node.js 一定要装；Neo4j 和 embedding 端点只有在你需要这些能力时才需要。

组件	是否必需	作用（大白话）
Node.js（≥ 18）	必需	ArchGraph 本身和 MCP 服务端跑在 Node 上，安装它才能用。
Neo4j 图数据库	结构化查询 / 语义检索必需	把图谱的「结构投影」存进去，让 agent 能用只读 Cypher 做结构化查询；语义召回也依赖它存向量。可以是本地、Docker 或托管的实例。
Embedding / 向量端点	语义检索必需	给「语义召回」（Graph RAG）提供向量能力。任何 OpenAI 兼容的 embedding 端点都行 —— 云服务，或自建服务（离线 / 内网 / 私有部署）。

不配 Neo4j / embedding 会怎样？ 意图图谱本身的上下文读取 （如 getIntentElementContext、getArchitectureViewContext）、写入（建元素、建关系、建视图、校验、去重、验收登记）以及 EA 互操作 依然可用；失效的是 Neo4j 结构投影 / Cypher 结构查询 和 全部语义检索（Graph RAG）。所以你可以先不配，等需要时再补。

安装与部署

两条命令，把工具链、Skills、Rules 和 MCP 服务端一次装好，并注册进你的宿主。

npm install -g archgraph-argo
argo-deploy

argo-deploy 会自动把 argo MCP 服务端注册到 GitHub Copilot、Cursor、OpenCode、DeepSeek Harness、OpenClaw、Codex，并安装对应的 skills / rules / agents。注意各宿主能力不同： skills 和 rules 会装到每个宿主，而 agents（子代理定义）只装到支持它的宿主 —— OpenClaw 和 Codex 没有 agents（它们只接收 rules + skills + MCP 注册）。对 Codex，rules 会写到 ~/.codex/AGENTS.md（每个会话都会注入，所以唤醒门禁始终生效）， skills 写到 ~/.codex/skills/。

交互式填写 ~/.argo/.env

argo-deploy 运行时会一步步问你 Neo4j 和 embedding 的连接信息，写进 ~/.argo/.env。已有的、非空的值会被保留，所以你随时可以事后直接编辑该文件再重跑。下表是常用的 .env 键（另有若干可选的语义检索调优键；完整清单见 argo/.env.example，未知键会被 secret 预检拒绝）：

配置项	填什么
`ARGO_EMBEDDING_PROFILE`	embedding 提供方 profile：`approved`（默认，用下面的人工批准云端 profile）或 `openai-compatible`（自建兼容端点）。
`ARGO_EMBEDDING_BASE_URL`	embedding 端点地址（OpenAI 兼容，结尾不要带斜杠）。
`ARGO_EMBEDDING_MODEL`	embedding 模型名。
`ARGO_EMBEDDING_PROVIDER`	提供方标签（记录在证据里，也是 rerank 的回退提供方）。
`ARGO_EMBEDDING_MODEL_VERSION`	模型版本 / 资质标签（仅记录证据）。
`ARGO_EMBEDDING_DIMENSIONS`	向量维度，必须与模型一致（当前 profile 为 1536）。
`ARGO_EMBEDDING_QUERY_INSTRUCTION`	可选的查询侧指令前缀（面向 instruction-tuned 模型；文档侧不加）。
`ARGO_EMBEDDING_API_KEY`	可选的 embedding API Key（留空则用 `QWEN_KEY`）。
`ARGO_NEO4J_DATABASE_URL`	你的 Neo4j 实例地址（URI，例如 `neo4j://127.0.0.1:7687`）。
`ARGO_NEO4J_DATABASE_USERNAME`	Neo4j 用户名。
`ARGO_NEO4J_DATABASE_PASSWORD`	Neo4j 密码。
`ARGO_NEO4J_DATABASE`	可选，覆盖 Neo4j 数据库名（默认取仓库文件夹名）。
`QWEN_KEY`	embedding 端点的 API Key（例如阿里云 DashScope）。

自建 / 内网 / 离线怎么办？ 设 ARGO_EMBEDDING_PROFILE=openai-compatible，指向任意 OpenAI 兼容的 embedding 服务即可。详见 docs/self-hosted-embedding-deployment.md。

部署后记得重启你的宿主。 正在运行的 MCP 客户端在启动时加载代码，重启 opencode / VS Code / Cursor / OpenClaw / Codex 等，才会用到新部署。

初始化工作区：argo init

进入你的项目后，让 coding agent 执行一次 argo init（它对应 MCP 调用 initializeWorkspace）。这一步会做四件事：

当项目里没有 design/KG/SystemArchitecture.json 时，创建一个初始图谱（注意：仅内置默认 ArchiMate 3.2 schema 会自动创建；用自定义本体时图谱写你自己提供，否则初始化会 fail-closed）。
执行第一次「JSON → Neo4j」同步，把结构投影写进图数据库。
初始化语义检索（Graph RAG）生命周期，让向量召回可用。
校验整张架构图是否合法、一致。

从这一刻起，这张意图图谱就是你项目的单一事实来源（source of truth）。

没配 Neo4j / embedding 会怎样？ 图谱创建与校验照常完成，但上面第 2、3 步（JSON → Neo4j 结构同步、语义生命周期）会报告 failed。补齐前置条件后重跑 argo init 即可。

默认 vs. 工作区。 全新安装默认内置 ArchiMate 3.2 + ARGO 扩展；而某个工作区可能解析到它自己的本体包（schema bundle），用 extends: "default" 继承默认再追加类型。用 queryNeo4jGraph { "schema": true } 就能看到当前生效的是哪一套。

日常怎么用

安装和初始化只需要做一次。之后你只要打开项目、让 coding agent 干活，剩下的事情它会在 ARGO 工作流里自动完成：

STEP 1

先定位架构元素

接到任务后，agent 先在意图图谱里找到「这个任务对应哪个架构元素」，而不是盲目翻文件或直接改代码。

STEP 2

武装 Skills / Rules

它把该元素相关的 Skills 和 Rules 装进本次会话记忆，知道这个领域该怎么做、有什么约束。

STEP 3

测试先行

先识别（必要时补上）可执行的 GIVEN-WHEN-THEN 验收测试，再动手实现，保证改动有外部视角的验证。

STEP 4

复用去重

要建的元素、关系或视图如果已经存在，就复用而不是复制；语义上非常接近的同类元素会被拦下并作为候选返回，避免同一概念分裂成两份。

STEP 5

提交回登记

改动提交后，agent 会把 commit id 和涉及的文件路径登记回对应的架构元素上。图谱因此自带审计轨迹。

也就是说，你不用记这些步骤 —— 它们是框架的内建行为。你只管提出需求，agent 会按上述闭环执行。

怎么建模自己的东西

默认情况下，ArchGraph 用 ArchiMate 3.2 这套通用企业架构建模语言。但如果你有自己的业务领域，可以在项目里放一份本体包（schema bundle），ARGO 就会只用你的本体来校验和检索这个项目 —— 而且只影响这一个项目，不会动到全局默认。本体包可以 extends: "default" 继承内置默认（ArchiMate 3.2 + ARGO 扩展）再追加自己的类型。

→ 看使用案例：自定义业务域本体并一步步建图（Team Graph）

常见问题 / 排错

语义检索没有结果 / 报错？

先确认 ~/.argo/.env 里 Neo4j 和 embedding 都填对，并执行过一次 argo init（它才会同步投影、初始化向量）。改完 .env 后重跑 argo-deploy 并重启宿主。

连不上 Neo4j？

检查 ARGO_NEO4J_DATABASE_URL 能否从你机器访问、用户名密码是否正确。本地 / Docker 实例要确认端口已放行。

想换 embedding 提供方 / 自建？

改 .env 的 ARGO_EMBEDDING_*：自建时把 ARGO_EMBEDDING_PROFILE 设为 openai-compatible，并填好 base URL、模型名、维度与 API Key。

图谱被写乱了 / 出现重复元素？

正常路径下写入会去重、不会产生重复。若确实需要新建一个「近似重复」的对象，写入时会要求显式确认和理由 —— 这是刻意设计的保护。

agent 一开始就报「图谱不可用」？

先用只读的 queryNeo4jGraph { "schema": true } 看激活的是哪套 schema、bundleValidation.status 是否 passed。failed 说明本体包配置有问题，需要先修好再写。

自定义本体下 `argo init` 报 `NO_DEFAULT_GRAPH`？

这是预期行为：自定义本体不会自动复制内置默认图。请自己创建 design/KG/SystemArchitecture.json —— 见使用案例的第一步。