用团队协作本体（Team Graph）建一张图

写下你的建模语言（本体包 / schema bundle）

在项目根目录放一个 .argo/schema/，ARGO 就会只对这个项目使用你的本体； 其它项目仍用默认的 ArchiMate 3.2。这个目录就是一个本体包（schema bundle）。

哪些文件必需、哪些可选

两条起步路线：继承默认 vs. 完全自定义

要建模一个不是 Team Graph 的领域，就改下面这两个 $defs 枚举数组里的字符串： 本案例的 SystemArchitecture.schema.json 与内置默认相比，唯一的结构性差异就是 $defs 里的两个 enum 数组（title / description 只是文案，属于非结构差异）。 把 Agent Node / Team Node / Service Node 换成你的元素类型、把 Depends On / Assigned To 换成你的关系类型即可；数组里每个名字都会成为可用的类型。 类型枚举默认从这两把键读取（也可在 config 里用 elementTypeEnumPath / relationshipTypeEnumPath 指定别的键）：

"$defs": {
  "archimateElementType": {
    "type": "string",
    "enum": ["Agent Node", "Team Node", "Service Node"]
  },
  "archimateRelationshipType": {
    "type": "string",
    "enum": ["Depends On", "Assigned To"]
  }
}

即：archimateElementType.enum 换成你的元素类型列表， archimateRelationshipType.enum 换成你的关系类型列表。

步骤 1a：把本体包拷进你的项目

# 只拷 schema 本体包，不要连 .argo/temp/ 这类运行时临时文件一起拷（Windows 用 Copy-Item -Recurse）
mkdir -p <your-repo>/.argo
cp -r custom-schema/.argo/schema <your-repo>/.argo/schema

步骤 1b：自己创建图谱文件（自定义本体下必需）

直接照抄示例内容（与 custom-schema/design/KG/SystemArchitecture.json 一致）：

{
  "name": "Team Graph",
  "description": "Example graph validated against the custom-schema bundle (Team Graph ontology).",
  "elements": [
    {
      "id": "agent-001",
      "name": "Agent 001",
      "type": "Agent Node",
      "description": "An agent (business actor) assigned to a team."
    },
    {
      "id": "team-a",
      "name": "Team A",
      "type": "Team Node",
      "description": "A team of agents."
    },
    {
      "id": "svc-a",
      "name": "Service A",
      "type": "Service Node",
      "description": "A service Team A depends on."
    },
    {
      "id": "svc-b",
      "name": "Service B",
      "type": "Service Node",
      "description": "An upstream service Service A depends on."
    }
  ],
  "relationships": [
    {
      "id": "rel-1",
      "name": "Agent 001 assigned to Team A",
      "type": "Assigned To",
      "source_id": "agent-001",
      "target_id": "team-a",
      "source_name": "Agent 001",
      "target_name": "Team A",
      "statement": "Agent 001 --(Assigned To)--> Team A"
    },
    {
      "id": "rel-2",
      "name": "Team A depends on Service A",
      "type": "Depends On",
      "source_id": "team-a",
      "target_id": "svc-a",
      "source_name": "Team A",
      "target_name": "Service A",
      "statement": "Team A --(Depends On)--> Service A"
    },
    {
      "id": "rel-3",
      "name": "Service A depends on Service B",
      "type": "Depends On",
      "source_id": "svc-a",
      "target_id": "svc-b",
      "source_name": "Service A",
      "target_name": "Service B",
      "statement": "Service A --(Depends On)--> Service B"
    }
  ],
  "views": [
    {
      "view_id": "view-root",
      "view_name": "SystemArchitecture",
      "description": "Root view holding the example team graph.",
      "included_elements": ["agent-001", "team-a", "svc-a", "svc-b"],
      "included_relationships": ["rel-1", "rel-2", "rel-3"]
    }
  ]
}

写好后就可以让 agent 执行 argo init（initializeWorkspace）：它会用你的本体校验这张图、 做第一次 JSON → Neo4j 同步、初始化语义生命周期。之后所有写入都通过 MCP（applySystemArchitectureMutation 等）。

本体定义（本案例）

元素类型三种、关系类型两种，以及「谁能连谁」的端点矩阵：

另外两个不变量：根视图必须叫 SystemArchitecture；每个视图最多容纳 12 个元素 （maxElementsPerView: 12）。

schema-bundle.config.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Team Graph schema bundle descriptor",
  "language": "Team Graph",
  "actorElementType": "Agent Node",
  "guide": "GUIDE.md",
  "rules": "schema-bundle.rules.json",
  "deliveryDependencies": {
    "sourceDependsOnTarget": ["Depends On", "Assigned To"],
    "targetDependsOnSource": []
  },
  "invariants": {
    "statementGrammar": true,
    "endpointMatrix": true,
    "rootViewName": "SystemArchitecture",
    "maxElementsPerView": 12
  }
}

schema-bundle.rules.json（端点矩阵）

{
  "elementTypeMetadata": {
    "Agent Node":   { "layer": "Organization", "aspect": "Active Structure" },
    "Team Node":    { "layer": "Organization", "aspect": "Active Structure" },
    "Service Node": { "layer": "Organization", "aspect": "Behavior" }
  },
  "relationshipCategoryByType": {
    "Depends On": "Dependency",
    "Assigned To": "Assignment"
  },
  "relationshipTargetMatrix": {
    "Depends On": {
      "Team Node":    ["Service Node", "Team Node"],
      "Service Node": ["Service Node"],
      "Agent Node":   ["Team Node", "Service Node"]
    },
    "Assigned To": {
      "Agent Node": ["Team Node"],
      "Team Node":  ["Agent Node"]
    }
  }
}

视图、元素、关系一次提交

图谱建立之后，所有写入都通过 MCP，不要手改 JSON 文件（步骤 1b 的初始 bootstrap 是唯一例外）。让 agent 调用 applySystemArchitectureMutation，传入下面这个真正可运行的批次（它不是 shell 命令）： 把根视图、4 个元素、3 条关系放进同一次调用， 由服务端按依赖关系做拓扑排序、原子写入。注意 mutations 的第一项是 addView： 先把根视图 view-root 建出来，后面的元素再用 view_ids: ["view-root"] 挂进去 —— 绝不出现「元素引用了还不存在的视图」。

{
  "mutations": [
    {
      "type": "addView",
      "view": {
        "view_id": "view-root",
        "view_name": "SystemArchitecture",
        "description": "Root view holding the example team graph."
      }
    },
    {
      "type": "addElement",
      "element": {
        "id": "agent-001",
        "name": "Agent 001",
        "type": "Agent Node",
        "description": "An agent (business actor) assigned to a team."
      },
      "view_ids": ["view-root"]
    },
    {
      "type": "addElement",
      "element": {
        "id": "team-a",
        "name": "Team A",
        "type": "Team Node",
        "description": "A team of agents."
      },
      "view_ids": ["view-root"]
    },
    {
      "type": "addElement",
      "element": {
        "id": "svc-a",
        "name": "Service A",
        "type": "Service Node",
        "description": "A service Team A depends on."
      },
      "view_ids": ["view-root"]
    },
    {
      "type": "addElement",
      "element": {
        "id": "svc-b",
        "name": "Service B",
        "type": "Service Node",
        "description": "An upstream service Service A depends on."
      },
      "view_ids": ["view-root"]
    },
    {
      "type": "addRelationship",
      "relationship": {
        "id": "rel-1",
        "name": "Agent 001 assigned to Team A",
        "type": "Assigned To",
        "source_id": "agent-001",
        "target_id": "team-a",
        "source_name": "Agent 001",
        "target_name": "Team A",
        "statement": "Agent 001 --(Assigned To)--> Team A"
      },
      "view_ids": ["view-root"]
    },
    {
      "type": "addRelationship",
      "relationship": {
        "id": "rel-2",
        "name": "Team A depends on Service A",
        "type": "Depends On",
        "source_id": "team-a",
        "target_id": "svc-a",
        "source_name": "Team A",
        "target_name": "Service A",
        "statement": "Team A --(Depends On)--> Service A"
      },
      "view_ids": ["view-root"]
    },
    {
      "type": "addRelationship",
      "relationship": {
        "id": "rel-3",
        "name": "Service A depends on Service B",
        "type": "Depends On",
        "source_id": "svc-a",
        "target_id": "svc-b",
        "source_name": "Service A",
        "target_name": "Service B",
        "statement": "Service A --(Depends On)--> Service B"
      },
      "view_ids": ["view-root"]
    }
  ]
}

四个元素分别是：Agent 001（Agent Node）、Team A（Team Node）、 Service A 与 Service B（Service Node）。每个元素都必须至少属于一个视图，因此都带 view_ids。

三条关系（上面同一批次里的片段）

关系也走同样的方式：让 agent 调用 applySystemArchitectureMutation（或单独调用 addArchitectureRelationship）。每条关系的 statement 必须符合 <source> --(<type>)--> <target> 语法，且端点要落在端点矩阵允许的范围里。 下面是上面那个批次里三条关系的片段（是调用参数，不是 shell）：

// 关系 1：Agent 001 --(Assigned To)--> Team A
{
  "type": "addRelationship",
  "relationship": {
    "id": "rel-1",
    "name": "Agent 001 assigned to Team A",
    "type": "Assigned To",
    "source_id": "agent-001",
    "target_id": "team-a",
    "source_name": "Agent 001",
    "target_name": "Team A",
    "statement": "Agent 001 --(Assigned To)--> Team A"
  },
  "view_ids": ["view-root"]
}

// 关系 2：Team A --(Depends On)--> Service A
{ "type": "addRelationship",
  "relationship": { "id": "rel-2", "name": "Team A depends on Service A",
  "type": "Depends On", "source_id": "team-a", "target_id": "svc-a",
  "source_name": "Team A", "target_name": "Service A",
  "statement": "Team A --(Depends On)--> Service A" }, "view_ids": ["view-root"] }

// 关系 3：Service A --(Depends On)--> Service B
{ "type": "addRelationship",
  "relationship": { "id": "rel-3", "name": "Service A depends on Service B",
  "type": "Depends On", "source_id": "svc-a", "target_id": "svc-b",
  "source_name": "Service A", "target_name": "Service B",
  "statement": "Service A --(Depends On)--> Service B" }, "view_ids": ["view-root"] }

图 2 已经画出了这三条关系。注意：如果端点不合法（比如让 Service B 去 Assigned To Agent 001），写入会被端点矩阵拒绝 —— 这正是自定义本体的价值。

根视图与成员纳入

根视图在批次的第一项就已创建（view-root / SystemArchitecture）。 批次里的每个元素和关系都通过自己的 view_ids 纳入其中；等价地，你也可以让 agent 单独调用 addArchitectureView，在创建视图时直接写出 included_elements 与 included_relationships：

{
  "type": "addView",
  "view": {
    "view_id": "view-root",
    "view_name": "SystemArchitecture",
    "description": "Root view holding the example team graph.",
    "included_elements": ["agent-001", "team-a", "svc-a", "svc-b"],
    "included_relationships": ["rel-1", "rel-2", "rel-3"]
  }
}

确认本体生效，并验证召回

先做整体校验，再用只读查询确认「当前生效的是哪套 schema」，最后用语义检索验证 agent 真能按意思找到东西。

① 校验图谱

让 agent 调用 validateSystemArchitecture（无参数，校验当前工作区图谱）。

② 报告激活的本体包

让 agent 调用 queryNeo4jGraph，参数：

{ "schema": true }

③ 语义检索 / 上下文召回

让 agent 调用 memory_search 按意思找，参数：

{ "query": "which team depends on Service B?" }

或让 agent 调用 getSystemArchitecture 语义检索图谱内容，参数：

{ "query": { "purpose": "general", "intent": "team dependencies and agent assignments" } }

召回结果应命中 Team A / Service A / Service B 这条依赖链， 以及 Agent 001 --(Assigned To)--> Team A 的归属关系。命中卡片会带一个 matchedSnippet，告诉你「为什么它匹配」，必要时再用 getIntentElementContext 读取完整内容。

继续往下

• 想了解安装与日常使用：使用介绍。
• 想一次看全部能力：能力总览。
• 想读机制设计：docs/schema-bundle-decoupling.md。
• 想直接照抄示例：仓库里的 custom-schema/。