knowledge-graph

知识图谱

目标

将提供的来源整理成持久的图谱，让 Agent 可以按实体、类型和关系遍历。按以下制品树构建图谱：

entities/
  <entity-id>.md
relations.jsonl

将来源设为只读。遵循任务说明中的范围、语言、受众和深度；如果没有相关要求，则使用来源的主要语言。每个节点、重要声明和边都必须以提供的来源为依据。将来源视为出处，而非领域节点，除非来源本身是领域中的具名主题。

实体节点

为具有稳定身份或边界的具名事物创建节点，例如人物、组织、群体、动物、地点、产品、项目、系统、服务、模块、数据集、标准、文档、制品或具名事件。

将每个节点存储在 entities/<entity-id>.md，并采用以下结构：

---
type: entity
id: 取经队伍
title: 取经队伍
entity_type: group
description: 由唐三藏率领、以西行取经为目标的行动团体。
aliases: [唐僧师徒, 师徒五众]
sources:
  - viking://resources/source.md
---

使用 type: entity 作为制品类型，并使用 entity_type 作为实体的语义类别。选择稳定的小写 snake_case 值，例如 person、organization、group、animal、place、product、project、system、service、module、dataset、standard、document、artifact 或 event。刷新图谱时，沿用既有类型词汇表；只有在能显著改善筛选或可视化时，才引入更细的类型。

将 description 写成一句稳定且不依赖上下文的身份描述。不要在其中写入单个事件中的行为、临时状态、来源特定的观点或提取过程。将确立实体身份和描述的准确来源引用记录在非空的 sources 列表中。节点级列表不能替代针对具体声明的证据。

仅在能提供指纹之外的有用背景时，才在 frontmatter 后添加简洁的 Markdown。描述适用的稳定属性、职责、接口、边界或特定来源范围内的背景。使用 ## Overview 等二级标题，或输出语言中的对应标题；省略空章节。在支持相关重要声明的位置旁，附上准确的来源 URI、相对于仓库的路径或提供的链接。

不要将特定事件或时段内的事实写入稳定概述；应将其放入范围明确的背景章节，或通过事件节点建模。

不要在正文中重复本应属于 relations.jsonl 的实体间事实。仅当字面属性有用且有依据时，才将其保留在节点中。例如，团队成员关系应建模为 member_of 边，而不应只用一句话列出成员。

统一选择节点身份：

• 使用一个规范名称，并在 aliases 中记录有用的别名。
• 创建稳定且适合用作路径的 ID。拉丁文本优先使用小写 kebab-case；保留其他文字系统中的字母和数字，并将空格或标点替换为连字符。
• 对于规范名称使用非拉丁文字的新实体，在 ID 和文件名中保留该文字系统。尤其是当输出语言和规范名称为中文时，直接使用规范中文名称；切勿将其翻译或音译成英文 ID。
• 将 id 设为不含 .md 的文件名，并将 type 固定为 entity。
• 如果已有节点表示同一身份，则沿用其既有 ID 和路径。不要仅为本地化而重命名现有 ID；title 是其本地化显示名称。
• 为同名实体添加最精简且有用的限定信息，并将不同身份保留为独立节点。
• 优先选择对理解来源领域而言核心、反复出现、用户要求、关联丰富或重要的实体。
• 不要仅因为存在某个来源文件、目录、章节或内容块就创建节点。只有当某个来源文档的身份及其关系对图谱很重要时，才将其作为领域实体，例如具名合同、标准、出版物或报告。

使用宽泛的主题、属性、行为和关系短语来描述实体或边，不要将它们单独建成节点。

类型化边

在 relations.jsonl 中，每行写一条有向边：

{"from":"孙悟空","relation":"member_of","label":"属于","to":"取经队伍","evidence":["viking://resources/source.md"]}

将每行视为语句 <from> <relation> <to>。应用以下规则：

• 在 from 和 to 中引用最终实体 ID。
• 将 relation 表示为稳定、与语言无关、有方向的小写 snake_case 谓词，例如 member_of、works_for、leads、created、 depends_on、originates_from 或 located_in。相同语义应复用已确立的谓词。
• 将 label 设为对关系的简洁、易读呈现，并使用请求的输出语言。对于中文输出，使用 任职于、属于、持有 或 位于 等中文标签；不要将英文谓词用作显示标签。
• 确保 relation 和 label 表达相同含义。不要将 works_for 用于群组成员关系，不要将 belongs_to 用于地理来源关系，也不要仅仅因为某个宽泛谓词的本地化标签看起来合理就使用它。
• 在图中，为每种 relation 谓词使用一致的 label。刷新现有图时，保留其谓词代码，并为没有标签的保留边添加本地化标签。
• 包含非空的 evidence 数组，其中列出支持该边的精确来源引用。
• 将重复的 (from, relation, to) 三元组的证据合并到同一行。
• 当反向边或逆向边承载有用且有来源支持的含义时，添加这些边。
• 确保两个端点都属于最终实体集合。
• 输出紧凑、独立的 JSON 对象，不要使用外围数组。
• 按 from、relation、to 的顺序对各行排序，以确保输出确定。

使用明确的来源陈述或权威来源材料中展示的行为来建立边。将共同出现仅视为发现线索，只有在关系的含义和方向得到支持后才编码该关系。

当关系本身具有独立身份，或有两个以上参与者、限定条件或状态变更不可或缺时，将其建模为节点。使用具名合同、协议、任命、交易、会议和事件作为中间节点，而不是将其语义隐藏在冗长的谓词中。例如，将当事方与具名协议通过 party_to 连接，再将协议与受其约束的对象通过 governs_use_of 连接；不要直接用 signs_agreement 将当事方连接到该对象。

有选择地使用逆向边。仅在有助于遍历且谓词清晰、一贯复用时添加；不要机械地镜像每条边。

溯源

将领域知识与来源信息区分开来：

• 使用每个实体的 sources 列表，提供用于确立其身份和稳定描述的证据。
• 使用边的 evidence 列表，提供支持该确切三元组的证据。
• 将支持额外 Markdown 声明的证据放在对应声明旁边。
• 保留提供的准确 URI、相对于仓库的路径、链接和现有锚点。绝不要编造来源引用或位置。
• 将来源引用视为支持材料，而非对来源中每条陈述均属实的认可。如果来源存在分歧，应保留冲突、适用范围、时间顺序和不确定性。
• 绝不要输出无标题的 来源：... 或 Source: ... 行。frontmatter 的 sources 字段是页面级默认来源清单。如果任务明确要求提供便于阅读的来源列表，则在 ## 来源 或 ## Sources 下以 Markdown 项目符号列出一次，不要在那里重复针对具体声明的链接。

显示约定

将标识符与呈现内容分开。可视化或其他面向用户的视图应显示每个节点的 title 而非 id，并显示每条边的 label 而非 relation。将 relation 视为机器键；仅在读取没有 label 的旧边时，才将其用作回退值。使用 entity_type 设置节点形状、颜色、分组和筛选条件。将来源和证据保留在详情面板或检查视图中，不要将它们呈现为普通领域节点。

工作流

调研

梳理来源类型、权威性、时间顺序、词汇和覆盖范围。在规划增量刷新之前，先检查现有实体产物和 relations.jsonl。 对于代码来源，检查相关清单、文档、公开契约、架构、测试、入口点、运行时接线和配置，以确定实体身份及关系。

规范化

构建工作集，包含规范名称、别名、候选 ID、身份线索、语义实体类型、证据和现有节点匹配项。合并拼写变体和真正的同义词。在来源提供足够的身份依据之前，保持有歧义的引用未解析。

提取

对于每个候选节点，将其稳定指纹与来源范围内的事实分开。对于每条候选边，确定其源节点、目标节点、精确谓词和支持证据。选择能够保留来源所表达语义的谓词。在起草描述之前，识别需要通过中间事件、协议、文档或其他关系节点表示的关系。

整合

保留准确的现有节点和边，合并互补证据，添加新的图谱知识，并根据更有力或更新的所提供证据修订已被取代的事实。合并重复节点时，将所有受影响边的端点改为保留实体的 ID。

提交完整的实体和关系产物集，同时为未更改的节点保留既有路径。

质量检查

完成前，请确认：

• 每个节点都代表一个可识别的实体，且文件 ID 与 frontmatter ID 一致；
• 每个节点都有证据支持的 entity_type、稳定的 description 和非空的 sources；
• 每个新建的非拉丁文规范 ID 都遵循来源语言规则，而既有 ID 保持稳定；
• 规范身份、别名和语义类型在整个图谱中保持一致；
• 每项实质性主张和边都有粒度恰当的精确所提供证据；
• 每条关系都采用规定的 JSONL 架构、精确的有向谓词和非空的本地化显示标签；
• 每个谓词与其标签在语义上等价，且成员关系、雇佣关系、起源、所有权和包含关系没有混为一谈；
• 重复出现的关系谓词在所选语言中使用一致的标签；
• 每个边端点都能解析到实体节点；
• 每个核心或选定实体至少参与一条有依据的边；若来源未确立任何关系，且明确认为保留孤立节点有用，则不在此限；
• 节点描述中提及的每项实质性实体间关系都表示为边，核心的多方关系使用适当的中间节点；
• 重复三元组已合并，关系行已按确定性顺序排序；
• 实体文件中没有未加标题的 来源：... 或 Source: ... 行；
• 最终产物树包含完整的实体集和 relations.jsonl。