AOCI-CODE System Cognition 投影指南:Lineage、Relations、Impact 如何做到不造假知识图谱
AOCI-CODE System Cognition 投影指南:Lineage、Relations、Impact 如何做到不造假知识图谱
AOCI-CODE 是一个本地优先、用 Git 版本化的代码库与数据库结构认知地图,让 Claude Code、Codex、Cursor、opencode 等 AI Agent 在改动代码前先读懂整个系统。它内置的 System Cognition 能力——Lineage、Relations、Impact——把已治理的正式认知派生成可查询的关系视图,却始终不落地第二套状态,这正是它敢称"不造假知识图谱"的底气。
核心概念:投影,而不是新的事实源
传统知识图谱往往自带图数据库、独立写入路径和一套新的事实存储,图一旦与源码漂移,就会"以讹传讹"。AOCI-CODE 走了相反的路:从权威资产即时派生、不持久化、可随时重算。
源码里这句注释把边界写得极直白(BuildSystemProjection):
derives a narrow relation and lineage view ... It has no persistence or Apply behavior and therefore cannot become a second fact source.
投影结构体一出生就带着两个标记(system_projection.go):
| 字段 | 取值 | 含义 |
|---|---|---|
derived |
true |
结果是从权威资产派生的,非原生事实 |
authoritative |
false |
关系投影不是权威来源,冲突时以权威资产为准 |
一句话:投影只是权威资产的一个"切片",删掉它随时能从 Cognition Volumes 重新算出来。
三条投影命令各回答什么问题
| 命令 | 版本标识 | 回答的问题 |
|---|---|---|
cognition system relations |
system-relation-projection/v1 |
对象之间的结构与语义关系长什么样 |
cognition system lineage |
cognition-lineage/v1 |
某条认知的来源、Evidence 与 Receipt 绑定链 |
cognition system impact |
database-to-code-impact/v1 |
某张表变化可能影响哪些代码认知对象 |
cognition system snapshot |
cognition-evolution-snapshot/v1 |
当前认知集合的只读快照 |
cognition system evolution |
cognition-evolution/v1 |
从历史快照演进到当前发生了什么 |
完整合同见 aoci-system-cognition-runtime-v1.txt,其中 "Boundary" 一节明确:这些命令只暴露只读派生视图,不创建 Apply、CAS、Recovery、Baseline 或 Ledger 生命周期。
Lineage:给每条认知挂上"来源链"
Lineage 为每个受管对象输出一条 LineageRecord,把"这条认知是怎么来的"讲清楚:
- 对象指纹:
object_sha256、volume_sha256,绑定到具体字节; - 绑定关系(bindings):代码对象 →
code_source,指向 Baseline 里的源码 SHA-256;数据库对象 →schema_evidence,指向已接受的 Table Evidence SHA; - 新鲜度状态:
current/stale/unbaselined,由"当前源码哈希是否等于基线指纹"判定。
关键在于 Lineage 只读取现有 Baseline 与 Evidence 绑定来解释来源链(buildLineageRecord),它自己不成为独立的 Provenance 数据库——来源的权威仍在 Cognition Volume、Evidence 绑定与 Receipt 身份上。
Relations:窄关系投影,只读文本里的 R 标注
这是"不造假"最典型的一处。AOCI-CODE 每条 Entry 都有 R(Relations) 字段,是模型写给模型看的语义线索。投影时,程序只把"对得上"的受管对象连成边(appendExplicitRelations):
这是投影而不是校验:对不上的标注既不是缺陷也不产生 Finding,因为 R 是模型写给模型的语义线索,允许指向尚未创作、已经移除或不受管的东西。
buildImpactGraph 的注释进一步点明分工:机器只管单条形式与预算,跨条目的语义一律交给模型。 于是:
- R 指向的对象不存在?→ 不产生边,也不报诊断;
- 同名多义?→ 不猜,不产生边(resolveImpactRelation)。
换句话说,程序绝不靠 SQL、import、路径或名称相似度去"猜"关系——它只搬运模型已明确创作、并经治理接受的那部分强关系。
Impact:沿显式关系查数据库影响面
cognition system impact --object <database_ref> 从一个规范数据库对象出发,只沿显式的正式 R 关系做双向遍历,找出可能受影响的代码对象(ResolveDatabaseImpact):
It never infers dependencies from paths, SQL, imports, or names.
每个命中的对象都会标注 reason:explicit_relation(一跳直达)或 transitive_explicit_relation(多跳传递),并给出完整 path 与 distance。若投影本身不完整,结果会带 complete=false 并附 Findings,而不会静默补全。
权威边界:投影与事实源如何分工
一句话总结 AOCI-CODE 与知识图谱系统的区别:它不是一个知识图谱系统。 Narrow System Relation Projection 可以看作便于查询的关系视图,但它没有第二套状态管理、独立写入路径或新的事实存储。
| 维度 | 事实源(权威) | 派生投影(视图) |
|---|---|---|
| Lineage | Cognition Volumes + Evidence 绑定 + Receipt 身份 | cognition-lineage/v1 记录 |
| Relations | Root Manifest + 正式 Entry 中模型创作的 R | system-relation-projection/v1 |
| Impact | 当前正式 R 关系及其可解析身份 | database-to-code-impact/v1 |
| Snapshot / Evolution | 当前权威资产的确定性观察 | 调用方保存/比较的投影 |
Finding 类型本身就声明 "never contains generated cognition semantics"(types.go),从类型层面杜绝"诊断里混入语义判断"。更多权威划分见 contract-authority.md。
快速上手:五条命令跑一遍投影
在已建立 Whole-Index 的仓库根目录执行(--json 输出机器可读结果):
# 1. 结构关系 + 正式 R 关系投影
aoci --repo . cognition system relations
# 2. 认知对象的来源与绑定链
aoci --repo . cognition system lineage
# 3. 从一张表出发查数据库 → 代码影响面
aoci --repo . cognition system impact --object database://primary/public/orders
# 4. 存一份当前认知快照,供日后比较
aoci --repo . cognition system snapshot --json > previous.json
# 5. 比较历史快照与当前投影的演进
aoci --repo . cognition system evolution --snapshot-file previous.json
五条命令全程不联网、不读业务行、不依赖图数据库,对相同输入确定性排序后再计算投影身份,可在 CI 中安全复用。
延伸阅读
- System Cognition 运行时合同
- 权威边界说明
- Cognition Volumes 文档
- Database Cognition Authoring
- 派生投影源码:internal/cognition/
AOCI-CODE 的 System Cognition 不追求"图越大越全",而追求每一条边都能追溯到模型明确创作的 R 和已接受的 Evidence。投影可以删、可以重算,而事实源始终只有一个——这正是它不造假知识图谱的全部秘密。
