目录 展开 收起
ChatCrystal 的“关系图”由两类数据组成：笔记之间的有向关系，以及当前界面默认展示的标签共现图。不要把图上的一条边直接当成事实或证明；它只是从候选、模型输出或标签共现规则得到的可检查线索。
本文依据固定提交 7642768 的 关系服务 与 关系路由。
两种图不要混为一谈
笔记关系表记录 source、target、类型、confidence、description 和 created_by。自动发现允许 CAUSED_BY、LEADS_TO、RESOLVED_BY、SIMILAR_TO、CONTRADICTS、DEPENDS_ON、EXTENDS、REFERENCES 八种枚举；同一方向、同一类型只能保留一条。手动关系的 confidence 固定设为 1，来源由 created_by 记录；这个数值不是经过测量的概率。
当前 Web 图页面调用 GET /api/graph/projection?level=tag，默认展示标签节点和共现边，最多 120 个节点；强度筛选对应 minScore。点击标签后，页面再按该标签加载最多 20 条笔记。GET /api/relations/graph 仍可返回笔记节点和关系边，但它是另一个接口，不代表首页当前一定使用它。
自动发现如何挑选候选
POST /api/notes/<note-id>/discover-relations 先用源笔记标题做语义搜索，最多取 20 个候选并排除自己；搜索失败或没有候选时，退回按创建时间取最近 20 条。候选的摘要最多截取 200 个字符，源笔记摘要最多放入 500 个字符的提示。候选集合有限，发现结果不代表扫描了整个库。
模型输出使用结构化数组和上述关系枚举。应用随后只保留候选 ID、confidence 至少 0.5 的项，并截取最多 5 条；描述字段有“简短说明”的提示，但 schema 没有把 20 字做成硬性长度校验。写入使用 INSERT OR IGNORE，重复关系不会产生第二条。
执行前将 <note-id> 和 <relation-id> 替换为实际 ID；手动示例中的 42、58 也须替换为库中存在的笔记。
curl --request POST \
'http://localhost:3721/api/notes/<note-id>/discover-relations'
curl 'http://localhost:3721/api/notes/<note-id>/relations'接口是同步发现流程，模型不可用时会返回错误；它不是后台保证完成的任务。手动创建关系则显式指定目标 ID、类型和说明：
curl --request POST http://localhost:3721/api/notes/42/relations \
--header 'Content-Type: application/json' \
--data '{"target_note_id":58,"relation_type":"RESOLVED_BY","description":"按测试结果复核"}'
curl --request DELETE 'http://localhost:3721/api/relations/<relation-id>'服务会校验两条笔记存在、禁止自引用和未知类型；手动重复插入会返回 HTTP 400 错误。
用关系扩展搜索，但保留来源
语义搜索可以用 expand=true 加一跳关系：只扩展 confidence 至少 0.5 的边，关联分数按“直接分数 × 0.7 × confidence”折扣。已在结果中的笔记会跳过，扩展不是多跳路径搜索，也不能保证每个关联结果都来自最强路径。阅读结果时回到笔记正文和原始会话，不把 via_relation 当成事实验证。
批量发现接口会为没有出边的笔记入队；队列按应用的任务机制执行，响应里的 queued 只是提交数量。它不承诺每条关系生成成功，也不应替代逐条结果核验。
让图成为可复查的线索
先记录关系的 source、target、类型、confidence 和创建来源，再用一个具体问题验证：这条关系是否能在两条笔记的摘要或原文中找到依据？若结论冲突，保留反例并检查当前项目条件。标签共现图只能说明标签出现在相同笔记中，不能自动升级为因果关系。
关系接口、语义检索和图投影的边界见 语义搜索流程；数据写回的质量约束见 Agent 知识记忆闭环。