Repo Identity ├─ project.json ├─ README.md ├─ catalog-info.yaml

Truth World ├─ sourceOfTruth ├─ STORAGE_TOPOLOGY.md ├─ docs/storage/* ├─ inventories/*

Contract World ├─ docs/contracts/* ├─ schemas/* ├─ gateway/openapi.yaml ├─ gateway/API.md

Runtime World ├─ gateway/ ├─ services/ ├─ scripts/ ├─ ops/

Evidence World ├─ gateway/scripts/smoke.mjs ├─ docs/operations/* ├─ .runtime/* ├─ inventories/*

Projection World ├─ generated/clients/* ├─ catalog/* ├─ docs exports / mirrors

你这套东西方向是对的，而且已经超过大部分“README 工程学”了。

但现在最大的问题不是内容少。

而是：

系统哲学过强
工程落点还不够收敛

说白了：

你已经开始在定义“工程文明”
但还没完全压缩成
“团队真正能执行的拓扑”

你现在最危险的问题其实是：

一、Ontology 爆炸

你这里已经出现：

truth
projection
runtime
ontology
contract
policy
evidence
graph
semantic
topology
intent
energy flow
meta-runtime

这些概念本身都对。

但：

一级概念太多

最后会导致：

谁都不知道：
一个新东西到底属于哪层

这是“高级系统”最容易死的地方。

二、你现在真正应该做的是

“强制收敛一级世界”

我建议你最终只保留：

1. Truth World
2. Contract World
3. Runtime World
4. Evidence World
5. Projection World

别再继续增加一级世界了。

这是最关键的。

三、为什么这样能防踩踏

因为所有系统腐化本质：

多个层开始争夺 owner

例如：

README 想拥有规则
Runtime 想拥有 schema
Projection 想拥有 truth
Prompt 想拥有 policy

于是：

踩踏

开始。

四、你真正该防的不是“代码冲突”

而是：

Truth Ownership Collision

这是大型 AI/runtime 项目真正的死亡原因。

五、你现在应该强制规定

1. Truth World

唯一允许：

canonical truth
semantic ontology
identity
relation
policy source

这里：

不能运行
不能渲染
不能调度

只能：

定义世界

例如：

schemas/
contracts/
ontology/

2. Contract World

这里只允许：

boundary crossing

例如：

OpenAPI
SDK
Event
Manifest
MCP schema

Contract World：

不能拥有业务真相

只能：

携带 truth

3. Runtime World

这里只允许：

execution
workflow
scheduler
queue
repair
retry
browser
agent

Runtime：

绝不能定义 truth

只能：

消费 contract

你现在文档里其实已经强调这个了。

这是对的。

4. Evidence World

这个是你文档里最牛逼的部分。

很多系统根本没有：

Failure leaves evidence
Smoke proves the loop

这是真正成熟工程思想。

Evidence World：

logs
audit
smoke
readback
trace
snapshot
failure report

注意：

Evidence 不是 Truth

只是：

Truth 的可验证痕迹

5. Projection World

这里只允许：

README
dashboard
markdown
HTML
reader UI
generated docs

并且必须：

可重建

这是你文档里最核心、最正确的思想之一。

六、你现在其实应该删掉很多“中间概念”

例如：

Energy Flow
Meta-runtime
Semantic Layer
Compression

这些：

不应该成为一级目录

它们应该：

成为评估维度

而不是：

成为拓扑节点

否则 ontology 会无限膨胀。

七、真正最小、抗踩踏的目录

你最终应该压缩成：

repo/
  truth/
  contracts/
  runtime/
  evidence/
  projections/

结束。

然后：

truth/

ontology/
schemas/
policy/
identity/
relations/

contracts/

openapi/
events/
sdk/
mcp/

runtime/

gateway/
workers/
scheduler/
browser/
workflow/

evidence/

smoke/
audit/
trace/
failures/
readback/

projections/

docs/
markdown/
dashboard/
generated/

八、为什么这套结构最不容易腐化

因为：

每层只有一个核心职责

这是：

高内聚

同时：

层之间只能通过 contract 连接

这是：

低耦合

九、真正防“踩踏”的核心

你文档里已经非常接近答案了：

Truth owns rules
Contract carries rules
Runtime executes rules
Projection renders facts

我给你再压缩一步：

最终版

Truth defines
Contract transports
Runtime executes
Evidence proves
Projection renders

这五句足够了。

十、你现在最大的风险

不是：

代码乱

而是：

哲学越来越强
拓扑越来越厚

最后：

新人无法落点

这是所有“文明级架构”最后的死亡方式。

十一、真正成熟的系统一定会做的事

折叠概念

例如：

你现在 25 问。

很好。

但真正进入工程时：

应该自动折叠成：

Truth
Contract
Runtime
Evidence
Projection

否则：

系统描述复杂度
会超过系统本身。

十二、最后一句（最重要）

真正高级的架构不是：

能表达更多概念

而是：

用更少世界
覆盖更多现实。

这才是真正的：

Compression

也是你文档最后真正接近的方向。你根据以下标准向用户汇报项目现状

怎么用这篇文章

这篇不是说明文，也不是纯理念文。它是工程项目资料整理的审计尺子。

当你把它交给我时，我会默认这样执行：

1. 先收集项目里的真实事实。
2. 再按 25 个根问题逐项对照。
3. 再清理重复、冲突、伪真源和混乱层。
4. 最后只留下可作为图纸使用的项目事实。

输入不是“这篇文章本身”，而是：

• 一个仓库
• 一组 README / docs / schemas / tests / smoke
• 真实 API、表、目录、运行证据

输出不是解释，而是：

• topology 图
• truth owner 表
• contract 清单
• runtime 清单
• boundary 清单
• conflict / duplicate / shadow truth 清单
• cleanup 建议
• 图纸索引

整理时的默认原则：

• 只认 canonical owner
• 只认可检查证据
• 只认项目事实，不认空泛抽象
• 发现重复就合并，发现冲突就标出，发现伪真源就剔除
• README、docs、dashboard、runtime、prompt、HTML 都要先判定角色，再决定能不能写进图纸

最短公式：

先问 topology，再写代码。
 
Truth owns rules
Contract carries rules
Runtime executes rules
Gateway enforces boundary
Storage persists facts
Projection renders facts
Smoke proves the loop
Failure leaves evidence

中文版本：

真源拥有规则
契约携带规则
运行时执行规则
网关守住边界
存储保存事实
投影呈现事实
smoke 证明闭环
失败留下证据

目录

1. 25 个根问题总表
2. 开工前最小证明模板
3. 四层分类
4. 25 个根问题详解
5. 横切原则：补强 25 问
6. 工程完成定义
7. 反模式清单
8. Graph-native / Obsidian 应用
9. 文件拓扑与六大图
10. 从 ContentBase / DataBase 抽出的通用经验
11. 附录：原始材料合并映射

一、25 个根问题总表

一句话版本：

1. Topology       → 结构
2. Truth          → 真相
3. Atom           → 原子
4. Relation       → 关系
5. Projection     → 投影
6. Runtime        → 运行
7. Boundary       → 边界
8. Contract       → 契约
9. Version        → 历史
10. Failure       → 失败
11. Ownership     → 权限
12. Lifecycle     → 生命周期
13. Storage       → 存储
14. Access        → 访问
15. Recovery      → 恢复
16. Identity      → 唯一标识
17. Observability → 可观测性
18. Capability    → 能力
19. Policy        → 规则
20. Evolution     → 演化
21. Entropy       → 防腐烂
22. Time          → 时间
23. Consistency   → 一致性
24. Economics     → 成本
25. Simplification→ 简化

使用步骤

以后拿这篇文章处理一个项目时，按这个顺序走：

1. 先找这个项目的真源在哪里。
2. 再找每个根问题在项目里对应的实际对象。
3. 再找哪些东西是 projection，哪些是 runtime，哪些是 boundary。
4. 再找重复、互相打架、说法不一致、没有 owner 的部分。
5. 最后把混乱部分清理成单一事实面。

判定混乱

下面这些情况都算混乱：

• 同一事实在多个地方被写成真源
• 文档、README、dashboard、生成物被当成 canonical source
• runtime 反向决定 schema
• projection 反向决定 truth
• 文件名、目录名、备注、口头说法互相打架
• 有解释，没有文件、表、API、测试、smoke 证据

输出格式

整理完一个项目后，结果应当收敛成：

• 项目事实总表
• 25 项对照表
• 事实冲突表
• 混乱清理表
• 图纸索引

输入规范

拿这篇文章处理项目时，优先收这些输入：

• README.md
• project.json
• docs/
• schemas/
• tests/
• smoke
• runtime evidence
• API / openapi
• 目录树
• 运行时日志 / audit / snapshot

如果一个项目没有这些输入，就先补事实，不要先补解释。

证据优先级

判断同一事实时，证据优先级按这个顺序：

1. 代码、schema、API、smoke
2. tests
3. runtime evidence
4. docs
5. README
6. 备注、口头描述、聊天记录

低优先级材料不能反向改写高优先级材料。

清理优先级

发现混乱时，按这个顺序清理：

1. 先去掉 shadow truth
2. 再合并重复定义
3. 再纠正 runtime 冒充 schema
4. 再纠正 projection 冒充 truth
5. 再修复没有 owner 的事实
6. 最后收敛 README / docs / 图纸索引

二、开工前最小证明模板

每次处理一个项目资料包，先回答四个问题。回答不了，不进入整理。

1. 这个项目的 canonical owner 在哪里？
2. 这组资料里哪些是 truth / projection / runtime / boundary？
3. 哪些文件、表、API、测试、smoke 在互相印证？
4. 哪些重复、冲突、伪真源需要清理？

最小证明必须落到可检查产物：项目事实总表、冲突表、清理表、图纸索引、证据锚点。

只给解释、不产生证据，视为未回答。

BLOCK 条件：四问任一无法回答，或只是在讲局部故事、没有项目证据，停止整理。

三、四层分类

这 25 个问题可以压缩成四层。

Ontology：系统里“什么存在”

• Truth
• Atom
• Relation
• Identity
• Capability

这一层回答：系统最终相信谁？最小对象是什么？对象之间怎么连接？对象如何被唯一识别？系统真正暴露什么能力？

Structure：系统如何组织

• Topology
• Projection
• Runtime
• Boundary
• Contract
• Storage
• Access

这一层回答：节点怎么连？谁只是展示？谁运行？谁不能越界？跨边界交换什么？数据存哪？通过什么路径访问？

Governance：系统如何被约束

• Ownership
• Policy
• Lifecycle
• Version
• Failure
• Recovery
• Observability

这一层回答：谁拥有？哪些规则绝不能违反？状态如何流转？变化如何记录？失败如何显式化？坏了如何恢复？如何诊断？

Dynamics：系统如何随时间演化

• Evolution
• Entropy
• Time
• Consistency
• Economics
• Simplification

这一层回答：系统如何扩展？如何防止腐烂？时间和因果如何进入系统？多个投影如何一致？成本如何受控？如何主动删减复杂度？

前 20 个问题覆盖结构、存在、治理。最后 5 个问题补上动力学，也就是系统如何随着时间腐化、漂移、演化、失控。

四、25 个根问题详解

1. Topology：节点和关系是什么？

核心问题：

系统由哪些节点组成？
节点之间谁依赖谁？
谁可以并行？
谁必须等待？
谁拥有真相？
谁只是投影？

相关知识：DAG、Graph System、Workflow Engine、Scheduler、Dependency Injection、Microservice Topology、Event Topology、Runtime Graph、Service Mesh。

典型对象：Node、Edge、dependsOn、parent-child、event-flow。

反腐化提醒：没有 topology，系统一定会退化成文件堆和调用堆。拓扑必须显式，而不是靠程序员脑补。

必须产物：topology graph / dependency list / workflow DAG。

BLOCK 条件：无法画出节点、边、依赖方向、并行/等待关系，或只能靠脑补调用顺序。

2. Truth：唯一真源是什么？

核心问题：

系统最终相信谁？
哪个对象才是真相？
数据库、AST、Git commit、schema、manifest、raw artifact，谁是 canonical？

相关知识：Canonical Model、Event Sourcing、Git Object Model、Database Authority、Immutable Artifact、Domain Authority、CRDT。

典型对象：Canonical AST、Database、Git Commit、Raw Artifact、Manifest。

反腐化提醒：真源不明确，系统一定会分裂。文档、prompt、UI、HTML、Markdown、snapshot、generated output 都不能替代 Truth。

必须产物：canonical owner path / truth object / write authority。

BLOCK 条件：找不到唯一真源，或出现多个可写 truth source。

3. Atom：最小业务原子是什么？

核心问题：

最小不可再拆的业务单元是什么？

内容系统里可能是 Document / Section / Block / Anchor / Asset。

生成系统里可能是 ContextResolver / PromptBuilder / QualityGate / RepairLoop。

相关知识：AST、Entity、Aggregate、ECS、Block Model、Domain Modeling。

典型对象：Paragraph、Asset、Annotation、PromptNode、Task。

反腐化提醒：没有 atom，所有逻辑都会长成 string heuristic；没有 domain atom，就没有稳定 relation。

必须产物：domain atom definition / typed entity or aggregate schema。

BLOCK 条件：只能用字符串、文件名、自然语言段落解释业务对象。

4. Relation：原子如何连接？

核心问题：

原子之间靠什么关系连接？
parent-child？
dependsOn？
references？
versionOf？
derivedFrom？
annotates？

相关知识：Graph Database、Foreign Key、Edge、Semantic Link、Reference System、Knowledge Graph。

典型关系：dependsOn、references、contains、annotates、derivedFrom、versionOf。

反腐化提醒：没有 relation，atom 只是碎片。外键错误很多时候不是数据库麻烦，而是拓扑结构在说话。

必须产物：relation schema / edge type list / FK or reference contract。

BLOCK 条件：关系只能靠约定、路径拼接、隐式字段或人工记忆维持。

5. Projection：哪些只是投影？

核心问题：

哪些东西只是展示结果，而不是真相？
HTML？
Markdown？
Search index？
Reader UI？
PDF？
EPUB？

相关知识：CQRS Projection、Materialized View、Static Site Generation、Read Model、Search Index、Render Pipeline。

典型对象：HTML、Markdown Export、Reader UI、Search Index、PDF、EPUB。

反腐化提醒：Projection 可以重建，不应该当本体。一旦 Projection 变 Truth，代码一套、文档一套、运行时一套、AI 理解一套，系统会分裂。

必须产物：projection list / rebuild path / source truth mapping。

BLOCK 条件：投影不可重建，或 Markdown / HTML / UI / snapshot 被当成 truth。

6. Runtime：谁执行、调度、保存状态？

核心问题：

系统运行时谁负责执行？
谁负责调度？
谁保存运行状态？
谁负责 retry / cache / resume？

相关知识：Runtime System、Scheduler、Temporal、Airflow、LangGraph、Kubernetes、Actor Model、State Machine。

典型对象：Worker、Executor、Queue、Retry State、Workflow State、Runtime Context。

反腐化提醒：没有 runtime，DAG 只是静态图。Runtime 只能消费 Contract，不能重写 Contract。

必须产物：runtime owner / scheduler path / state owner / retry-resume contract。

BLOCK 条件：没有明确执行者、调度者、状态 owner，或 runtime 重写 contract。

7. Boundary：谁不能越界？

核心问题：

哪些模块绝不能直接互相访问？
谁不能直接读谁？
谁只能通过 API / SDK / manifest / event 交互？

相关知识：Hexagonal Architecture、Clean Architecture、Layered Architecture、Bounded Context、Service Isolation、Sandboxing。

典型规则：

MyBlog 不能直接写 DataBase
ContentBase 不能复制 DataBase schema
AI 不能直接修改原件
Runtime 不能直接改 Canonical Truth

反腐化提醒：Boundary 不是建议，是系统法律。Gateway 不是转发器，而是边界法律。

必须产物：forbidden access list / allowed crossing contract / boundary owner。

BLOCK 条件：必须跨层直连、复制 schema、绕过 gateway，或靠临时字段越界。

8. Contract：跨边界交换什么？

核心问题：

系统之间交换什么格式？
OpenAPI？
JSON Schema？
Manifest？
SDK？
Event？
Projection Package？

相关知识：OpenAPI、gRPC、RPC、SDK、JSON Schema、Protobuf、MCP、Event Contract、Manifest、IDL。

典型对象：API、RPC、SDK、Event、Manifest、Projection Package。

反腐化提醒：Contract 是系统之间的法律。Prompt 只能消费规则，不能拥有规则；规则必须进入 canonical schema / executable contract。

必须产物：schema / API / event / SDK contract with owner。

BLOCK 条件：字段靠猜、调用方和被调用方各自定义格式，或 prompt 拥有规则。

9. Version：变化如何记录？

核心问题：

变化怎么记录？
覆盖？
生成新版本？
edit operation？
commit？
manifest revision？

相关知识：Git、Event Sourcing、Operational Transform、CRDT、Immutable History、Snapshot。

典型对象：Commit、GraphVersion、EditOperation、Revision、ManifestVersion。

反腐化提醒：成熟系统一般不直接覆盖，而是生成 version / operation。没有版本语义，就无法 replay、audit、rollback。

必须产物：version model / operation log / migration or revision policy。

BLOCK 条件：变化只能覆盖当前值，无法 audit、rollback、replay。

10. Failure：失败和损失如何显式化？

核心问题：

失败怎么记录？
损失怎么显式化？
降级、丢信息、解析不了，怎么表达？

相关知识：Observability、Retry System、Dead Letter Queue、Structured Error、Loss Report、Audit Trail。

典型对象：QualityReport、RepairTrace、ImportLossReport、RetryState、BlockedReason。

失败至少要有：

failure code
blocked reason
violation list
source anchor
target id
runtime trace
idempotency key
write status
readback evidence

反腐化提醒：失败不能只是抛错、console error、聊天里说没过。工程不是追求永远不失败，而是让失败也服从结构。

必须产物：failure code / loss report schema / blocked reason / trace evidence。

BLOCK 条件：失败只剩异常、console、聊天描述，无法持久化或追责。

11. Ownership：谁拥有、谁能写？

核心问题：

谁是 owner？
谁能修改？
谁只能读？
谁负责修？

相关知识：RBAC、ACL、Governance、Ownership Model、Write Authority。

典型对象：Author、Maintainer、Reviewer、Admin、Service Owner。

反腐化提醒：没有 ownership，模块会互相长器官。权限也是工程结构，不是部署杂项。

必须产物：owner map / write authority / reviewer or service account boundary。

BLOCK 条件：谁都能改、没人负责修，或权限靠人工记忆。

12. Lifecycle：状态流转是什么？

核心问题：

对象从创建到销毁经历什么状态？

典型状态：

draft
review
approved
published
archived
deleted

相关知识：Workflow、Finite State Machine、BPMN、Temporal Workflow、Approval Flow。

反腐化提醒：Lifecycle 对应 workflow，不只是数据结构。没有 lifecycle，系统会靠隐式状态和人工记忆运行。

必须产物：state machine / lifecycle table / allowed transition list。

BLOCK 条件：状态只能靠布尔字段、隐式时间顺序或人工流程解释。

13. Storage：分别存在哪里？

核心问题：

不同类型的数据分别存哪？
raw bytes 存哪？
metadata 存哪？
runtime state 存哪？
projection 存哪？

相关知识：Database、Object Storage、Blob Store、Vector DB、Filesystem、Cold Archive、Cache Layer。

典型对象：MySQL、Qdrant、COS、OpenList、Redis、S3。

反腐化提醒：存储位置不等于真相位置。Gateway route 必须写到 canonical storage，而不是让上游决定怎么落库。

必须产物：storage topology / table-bucket-cache mapping / canonical write path。

BLOCK 条件：存储位置和 truth owner 混淆，或上游自行决定落库结构。

14. Access：通过什么路径访问？

核心问题：

谁通过什么路径访问？
API？
SDK？
RPC？
file mount？
OpenList？
Gateway？

相关知识：API Gateway、Reverse Proxy、SDK、RPC、MCP、File Mount、Service Discovery。

典型对象：Gateway、REST API、gRPC、SDK、CLI、MCP Adapter。

反腐化提醒：访问路径不统一，边界会烂。不要因为某条路更快，就绕开 canonical access path。

必须产物：canonical access path / gateway route / SDK or CLI entrypoint。

BLOCK 条件：因为方便而绕过 canonical API、SDK、gateway 或 mount path。

15. Recovery：如何重建和恢复？

核心问题：

系统坏了如何恢复？
从哪个 truth 重建？
哪些能重建？
哪些是可丢弃缓存？
哪些必须备份？

相关知识：Disaster Recovery、Rebuild Pipeline、Snapshot、Backup、Event Replay、Projection Regeneration。

典型对象：Rebuild Projection、Replay Events、Restore Snapshot、Reindex Search、Rehydrate Runtime。

反腐化提醒：Recovery 是系统抗腐烂能力。不能重建的 projection 很可能已经偷偷变成 Truth。

必须产物：rebuild plan / backup policy / replay source / projection regeneration command。

BLOCK 条件：坏了只能手修，无法说明从哪个 truth 重建。

16. Identity：系统如何唯一标识对象？

核心问题：

对象如何唯一定位？
业务动作如何唯一定位？

相关知识：UUID、SHA256、Content Addressing、URI、Canonical ID。

典型对象：AssetID、DocumentID、AnchorID、GraphNodeID。

反腐化提醒：幂等键是业务身份，不是随机字符串。正式业务里的 idempotency key 应来自 workId / chapterId / chapterNumber / contractId / body hash / status / operation kind，不是 Date.now()。

必须产物：canonical ID scheme / idempotency key formula / address contract。

BLOCK 条件：身份来自 Date.now、随机值、标题、路径猜测，或同一对象多套 ID。

17. Observability：系统如何被观察？

核心问题：

系统运行时如何诊断？
谁失败？
为什么失败？
失败在哪一层？
损失是什么？
能否重试？
能否读回？
能否重建？
谁拥有修复权？

相关知识：OpenTelemetry、Structured Logging、Metrics、Distributed Tracing、Audit Log。

典型对象：traceId、runtime logs、quality metrics、workflow timeline。

反腐化提醒：不成熟系统失败时只留下“报错了、没生成、没保存、不知道为什么、再试一次”。成熟系统失败时仍然有秩序。

必须产物：trace id / structured logs / metrics / audit timeline。

BLOCK 条件：失败后无法回答谁失败、在哪层失败、损失是什么、能否重试。

18. Capability：系统真正提供什么能力？

核心问题：

系统对外真正暴露什么能力？
哪些 capability 是 runtime 能执行、可验证、可追责的？

相关知识：Capability-based Design、Service Registry、Plugin System、Runtime Capability Graph。

典型对象：runtime.generate.chapter、runtime.quality.check、runtime.repair.draft。

反腐化提醒：Capability 必须面向通用问题，而不是不断吸收具体案例。Runtime capability 不能演化成 case collection。

必须产物：capability manifest / input-output contract / runtime consumer。

BLOCK 条件：能力只是 handler、README、prompt 或 case collection，没有通用 contract。

19. Policy：系统有哪些不可违反规则？

核心问题：

什么规则绝不能违反？
哪些规则是 completion blocker？
哪些规则是 execution blocker？

相关知识：Governance、Validation Rules、Policy Engine、Constraint System。

典型规则：

Original artifact immutable
No direct SQL outside gateway
Projection cannot mutate truth
Prompt cannot own rules

反腐化提醒：如果一条规则会影响生成、校验、保存、发布、回滚、追责，它就不是提示词，而是 Executable Contract。

必须产物：executable policy / validation gate / completion blocker list。

BLOCK 条件：规则只在文档或口头约定里，不能自动拦截违规。

20. Evolution：系统未来如何演化？

核心问题：

未来怎么扩展而不崩？
新增能力是否需要新 owner？
旧结构怎么迁移？

相关知识：Plugin Architecture、Modular Design、Extensibility、Backward Compatibility、Migration Strategy。

典型对象：Plugin Node、Capability Extension、Schema Migration、Feature Gate。

反腐化提醒：扩展不是加旁路。扩展必须进入 topology、contract、runtime、storage、projection 的闭环。

必须产物：extension point / migration path / compatibility boundary / feature gate。

BLOCK 条件：扩展只能新增旁路、复制实现或破坏现有 topology。

21. Entropy：系统如何防止熵增？

核心问题：

规则是否越来越多？
是否开始 patch accumulation？
是否出现 shadow truth？
是否开始靠 blacklist、whitelist、regex、if-else 修系统？

相关知识：Anti-entropy、Complexity Control、Rule Accumulation、Drift Detection。

典型对象：rule budget、drift report、entropy delta、shadow truth detector。

反腐化提醒：系统抽象能力上升时，局部规则数量必须下降。否则再高级的 Runtime / DAG / Graph，最后都会退化成一大坨 if-else。

必须产物：entropy delta / rule budget / drift detector / shadow truth scan。

BLOCK 条件：新增规则、词表、if-else、patch，但没有抽象提升或删除折叠。

22. Time：时间如何进入系统？

核心问题：

事件顺序如何定义？
因果关系如何定义？
是否允许 replay？
runtime time、event time、logical time 如何区分？

相关知识：Event Time、Logical Clock、Timeline、Causality、Replay。

典型对象：eventTime、logicalClock、timeline event、causal edge、replay cursor。

反腐化提醒：没有时间模型，系统只能看当前状态，无法解释“为什么变成这样”。

必须产物：event-time model / logical clock / timeline schema / replay cursor。

BLOCK 条件：只能看当前状态，无法解释事件顺序和因果关系。

23. Consistency：系统一致性如何保证？

核心问题：

多个 projection 如何一致？
runtime 与 truth 如何同步？
storage 与 index 如何 reconcile？
什么时候需要强一致？
什么时候允许最终一致？

相关知识：Strong Consistency、Eventual Consistency、Reconciliation、CRDT。

典型对象：reconciliation job、consistency check、projection version、readback proof。

反腐化提醒：没有 readback 的 write，不算打通。HTTP 200 只能说明请求被处理，不能说明业务目标完成。

必须产物：consistency model / reconciliation job / readback proof / projection version。

BLOCK 条件：write 无 readback，多个 projection 不知道何时一致。

24. Economics：系统成本如何约束？

核心问题：

系统是否为了“完美”无限复杂化？
token、CPU、IO、延迟是否可控？
吞吐、延迟、存储、调用成本如何预算？

相关知识：Cost Model、Throughput、Latency、Resource Budget。

典型对象：cost budget、latency budget、token budget、IO budget、throughput target。

反腐化提醒：工程不是无限追求强，而是在预算内维持清晰结构。没有 economics，系统会越来越聪明，但越来越脏、越来越贵。

必须产物：cost budget / latency budget / token-CPU-IO budget / throughput target。

BLOCK 条件：为了完美无限加复杂度，成本、延迟、资源无上限。

25. Simplification：系统如何主动减少复杂度？

核心问题：

哪些 abstraction 已经过时？
哪些 capability 应该删除？
哪些规则可以合并？
哪些 projection 可以重建而不是保存？

相关知识：Refactoring、Deletion-first、Abstraction Compression、Complexity Pruning。

典型对象：deletion plan、collapse proof、obsolete capability list、complexity pruning report。

反腐化提醒：能删规则，比能加规则更重要。每个版本都应该让规则总量下降，抽象能力上升。

必须产物：deletion target / collapse proof / obsolete capability list / pruning report。

BLOCK 条件：只加不删，无法指出本次减少了哪个低阶规则或旧结构。

五、横切原则：补强 25 问

下面这些概念不是第 26、27、28 个并列根问题，而是嵌入 25 问的横切原则。

如果把它们单独扩成新清单，问题数量会增长，但系统抽象不一定上升。更好的做法是：保持 25 问作为主骨架，把这些原则压入现有问题的证明标准。

1. Compression：抽象如何压缩复杂度？

核心问题：

新增一个 case 时：
是新增规则？
还是提升抽象？

好的抽象不是“能处理更多特例”，而是：

用更少规则覆盖更多情况。

成熟系统：

case 数 ↑
规则数 ↓

不成熟系统：

case 数 ↑
if-else 数 ↑
prompt patch ↑

Compression 主要嵌入：

• Simplification
• Entropy
• Evolution
• Policy
• Capability

必须产物：规则减少证据 / 抽象替代关系 / 删除或折叠的低阶分支。

BLOCK 条件：新增 case 只能通过新增 blacklist、whitelist、regex、prompt patch、特殊分支或局部 helper 解决。

2. Semantic Layer：系统如何知道“它是什么”？

Atom、Relation、Projection 只能说明系统里有什么、如何连接、如何展示，但还需要回答：

这个对象的语义角色是什么？
它的不变量是什么？
系统为什么知道它是这个东西？

Schema 不等于 Meaning。

例如：

{
  "type": "chapter"
}

不等于系统真正理解“章节”。

语义层至少要表达：

semantic contract
semantic role
semantic invariant
semantic capability

Semantic Layer 主要嵌入：

• Atom
• Relation
• Contract
• Capability
• Policy

必须产物：semantic role / invariant / allowed relation / capability binding。

BLOCK 条件：系统只能靠字段名、文件名、prompt、自然语言描述或字符串启发式猜测语义。

3. Intent：为什么要执行？

Runtime 不能只是 task executor。它还必须知道：

目标是什么？
期望状态是什么？
完成标准是什么？
为什么这个 workflow 需要运行？

否则系统只能执行步骤，不能判断目标是否达成。

Intent 主要嵌入：

• Capability
• Runtime
• Lifecycle
• Contract
• Observability

必须产物：intent / goal / desired state / success criteria / verification path。

BLOCK 条件：只能说明“要运行哪个任务”，不能说明“为什么运行、运行后什么状态才算完成”。

4. Knowledge / Memory：经验如何进入未来运行？

Storage 保存数据，不等于 Memory 积累知识。

在 AI runtime 里：

memory != storage

Memory 是可被未来 runtime 消费的经验结构。失败不能只留下日志，还要进入学习闭环：

Failure
→ Learning
→ Policy / Contract / Capability Evolution
→ Future Runtime Behavior

Knowledge / Memory 主要嵌入：

• Failure
• Observability
• Policy
• Evolution
• Recovery

必须产物：learning owner / reusable rule update / policy evolution record / future runtime consumer。

BLOCK 条件：失败留下了，但系统不会因此改变未来行为，只能靠人类记住。

5. Energy Flow：什么驱动系统运转？

Topology 是静态结构，Energy Flow 是系统运行的驱动力。

必须明确系统是被什么驱动：

event-driven
pull-driven
schedule-driven
user-driven
policy-driven
feedback-driven

没有 Energy Flow，DAG 只是图，不是运行系统。

Energy Flow 主要嵌入：

• Topology
• Runtime
• Lifecycle
• Time
• Observability

必须产物：trigger source / event flow / schedule / feedback loop / causal chain。

BLOCK 条件：只能画出节点和边，但说不清什么事件、时间、策略或用户动作驱动它运行。

6. Anti-corruption Layer：系统如何抵御外部脏输入？

Boundary 和 Gateway 说明谁不能越界，Anti-corruption Layer 说明外部系统进入本系统时如何被翻译、隔离和验证。

典型外部输入包括：

Prompt
Markdown
HTML
Import JSON
Third-party API
Legacy DB
manual notes

它们都不能直接污染 canonical truth。

Anti-corruption Layer 主要嵌入：

• Boundary
• Contract
• Access
• Failure
• Gateway

必须产物：translation contract / validation rule / loss report / rejected state / canonical write boundary。

BLOCK 条件：外部输入可以直接写入 truth，或系统靠下游 normalize、sanitize、猜字段来修复污染。

7. Meta-runtime：Runtime 自己如何被治理？

Runtime 本身也会腐化。它不能成为最大 shadow system。

必须回答：

runtime capability registry 在哪？
runtime lifecycle 是什么？
runtime migration 如何记录？
runtime observability 如何实现？
runtime policy enforcement 谁负责？

Meta-runtime 主要嵌入：

• Runtime
• Capability
• Policy
• Observability
• Evolution

必须产物：runtime metadata owner / capability registry / runtime lifecycle / migration path / enforcement evidence。

BLOCK 条件：业务系统有 governance，但 runtime 自己靠隐式约定、脚本、prompt 或人工记忆运行。

8. Cohesion / Coupling / Self-contained Description

低耦合、高内聚、自包含和子描述不是装饰性原则，而是 25 问是否可执行的基本条件。

高内聚 = 一个 capability 内部规则围绕同一目的组织。
低耦合 = capability 之间只通过显式 relation / contract 连接。
自包含 = 理解和验证该节点不依赖外部口头约定。

每个 atom / capability / graph node 必须携带最小自描述：

• 它是什么
• 它负责什么
• 它不负责什么
• 它依赖谁
• 谁依赖它
• 输入是什么
• 输出是什么
• 不变量是什么
• 失败时留下什么证据

主要嵌入：

• Atom
• Relation
• Boundary
• Contract
• Capability
• Aggregate Graph Document

必须产物：purpose / boundary / inputs / outputs / invariants / failure modes / children。

BLOCK 条件：graph 只有节点和边，但节点自身不可解释，或理解节点必须依赖外部口头约定。

六、工程完成定义

不要把完成定义成：

代码写完
测试通过
接口返回 200

这太浅。

成熟的完成定义应该是：

canonical owner 已确认
schema 已落地
runtime 已消费
Gateway 已写入
storage 已保存
projection 可读回
failure 可解释
smoke 可复现
timeline 有记录
权限已验证
没有新增 shadow truth

一句话：

Done = truth、runtime、storage、projection、failure 全部闭环。

Write 的完成标准

真正的完成标准不是：

POST 返回 200

而是：

write succeeded
canonical object exists
projection can read it
payload preserves expected identity
runtime report matches contract
readback evidence exists

没有 readback 的 write，不算打通。

Smoke 的完成标准

Smoke 不是演示，是最低限度的系统契约。

单元测试证明函数逻辑可能对。集成测试证明模块之间可能对。Smoke 要证明：

真实 runtime
真实 env
真实权限
真实 storage
真实 write
真实 readback
真实 failure path

Smoke 不能只测 health、status、一个无害查询。它必须覆盖：

创建对象
写入对象
幂等
失败
读回
字段保持
权限边界

并且 smoke 应进入已有 canonical entrypoint，例如：

npm run smoke
pnpm run smoke:runtime-client

不要散落成一次性脚本。

七、反模式清单

1. 规则只写在 prompt 里

如果一条规则会影响生成、校验、保存、发布、回滚、追责，那它不是“提示词”，而是可执行契约。

例如：

当用词
禁用词
欧化结构
禁止符号
引用锚点
意象边界
作者画像
文章结构
上下篇衔接
失败报告

这些如果只写在 prompt、Markdown 文档、人工约定里，系统一定会遗忘。

正确路径：

规则进入 canonical schema
schema 暴露 runtime API
runtime 调用同一套规则
失败写入 durable report
report 可读回、可追责、可复盘

2. 文档变成 Truth

文档可以解释系统、记录理路、作为 projection。

文档不能拥有运行真相。

凡是会改变系统行为的东西，不能只落在：

README
设计文档
Obsidian 笔记
人工说明

它必须进入：

schema
contract
API
runtime capability
validator
state machine
gateway route
storage owner

3. 为一个失败造一个小系统

工程最常见的腐烂不是没人修，而是每次失败都有人顺手补一个小工具：

临时脚本
旁路 JSON
shadow registry
fallback route
local helper
手工修复层

短期看都能跑，长期看就是系统开始长出第二套神经。

判断标准：

有没有 canonical owner？
有没有 schema？
有没有唯一写入口？
有没有 runtime consumer？
有没有失败状态？
有没有读回验证？

如果没有，它不是工程进展，是结构性债务。

4. Gateway 只是转发器

真正的 Gateway 应该负责：

认证
幂等
schema validation
权限边界
事务边界
错误显式化
canonical storage write
readback contract

上游可以说：

我要记录一份验收报告。

但上游不能决定：

它应该落在哪张表
它应该是什么 kind
它应该怎么挂到 part
它应该怎么生成 blockId
它应该怎么保证幂等

这些属于 Gateway / DataBase 边界。

5. 失败不是一等对象

如果烂正文不能保存，这是对的。

但烂正文为什么烂，必须保存。

否则系统只知道：

没生成成功

却不知道：

哪个案例没覆盖
哪个引用没命中
哪个禁用词出现
哪个符号越界
哪个意象无来源
哪个结构泄漏

那就无法修复。

6. HTTP 200 被当成成功

HTTP 200 只能说明请求被处理了，不能说明业务目标完成了。

完成必须绑定 canonical object、projection readback、payload identity、runtime report contract。

7. 权限被当成部署杂项

权限文件也是 contract。它不是运维附录，它决定 runtime 能不能真的执行系统能力。

应该有：

canonical grant SQL
service account doc
runtime account mapping
smoke verification
SHOW GRANTS evidence

8. 关掉外键或绕过 parent owner

外键失败通常是在提醒你缺少 owner。

如果你想写一个 child，但 parent owner 不存在，正确修法不是关掉外键，也不是在 smoke 里手工补 parent，而是在 canonical write route 的同一事务里：

先 upsert parent
再 upsert child
再 upsert block / projection / report

外键不是阻碍，是拓扑结构在说话。

9. Runtime 重写 Contract

Runtime 层职责是：

执行
调度
生成
汇报
调用 Gateway

不是：

重新定义 DataBase 规则
重新定义存储结构
重新定义验收格式
重新定义内容真相

跨系统关系应该是：

DataBase owns contract
Gateway owns write boundary
ContentBase consumes contract
Runtime emits report
DataBase stores report
Projection reads report

10. 投影层不可重建

Markdown、OpenAPI client、生成文档、runtime capabilities docs 都可以存在。

但它们应该是：

projection
generated artifact
read model
human surface

而不是：

truth
manual source
parallel schema

八、Graph-native / Obsidian 应用

核心判断

Markdown 不应该是真源。Markdown 是 Projection Format。

如果要让 AI 真正理解文章结构，Markdown 绝不能是真源，因为 Markdown 本质是线性文本，不适合表达复杂 topology、relation、runtime metadata。

更合理的架构是：

Canonical Graph
↓
Projection Markdown
↓
Obsidian Surface

而不是：

Obsidian Markdown
↓
推导 Graph

后者会让 graph 永远是二等公民。

推荐分层

Layer 0 — Raw Artifact
Layer 1 — Canonical Graph
Layer 2 — Runtime Metadata
Layer 3 — Projection

也可以落成：

Canonical JSON / YAML Graph
↓
Projection Markdown
↓
Reader / AI / Search / Mindmap / Knowledge Graph

Markdown 负责人类阅读、写作、编辑。JSON / YAML Graph 负责系统真相。两者不互相污染。

Aggregate Graph Document

不要把所有 node 都拆成小文件，容易文件爆炸、关系漂移、人类认知破碎。

更适合当前方向的是：

Aggregate Graph Document

也就是：

一个文件 = 一个完整语义聚合体

例如：

engineering-root-questions.graph.json

文件本身是 graph aggregate，内部包含：

{
  "document": {},
  "nodes": [],
  "edges": [],
  "annotations": [],
  "versions": []
}

优点：

1. 不会文件爆炸
2. Obsidian 仍然能优雅编辑 projection
3. JSON / YAML 更适合 topology truth
4. Projection 会非常强
5. 非常适合 AST 思想

Vault 结构建议

vault/
├─ canonical/
│  └─ engineering-root.graph.json
├─ projections/
│  └─ engineering-root.md
├─ assets/
├─ annotations/
└─ runtime/

Obsidian 主要打开 projection。canonical/ 不给人随手编辑。

Projection generator 负责：

graph.json -> markdown

Obsidian 插件定位

• Dataview：query projection layer
• Canvas：topology visualization
• Excalidraw：relation sketch
• Metadata Menu：structured frontmatter editing
• Breadcrumbs：parent / child / dependsOn 关系

相关系统参照

• Obsidian 路线：Markdown 很强，但 Graph 通常不是一等真源
• Notion 路线：Block Graph Database
• Logseq 路线：block graph 组织方式
• ProseMirror / Tiptap / BlockNote 路线：接近 Notion-style block graph editor

目前没有一个完美成熟方案同时解决“人类编辑体验”和“Graph Canonical Truth”。比较现实的路线是：

Aggregate Graph Document + Projection Markdown

九、文件拓扑与六大图

25 个根问题本身隐含了一种文件拓扑。

它不适合普通的：

docs/
notes/
random md/

而更适合：

Ontology-driven topology

也就是让文件结构本身表达系统存在论。

推荐拓扑

System
├── ontology
├── contracts
├── runtimes
├── projections
├── governance
├── evidence
└── evolution

这不是文件夹分类，而是系统分层：

Ontology
→ Contract
→ Runtime
→ Evidence
→ Projection
→ Evolution

标准拓扑模板

这是更通用的落地模板，适合做仓库规范、项目规范和文件规范的底盘：

Enterprise / Organization
└── System Landscape
    ├── System Context
    │   ├── Users / External Systems
    │   └── This System
    ├── Containers
    │   ├── Web / API / Worker / DB / Gateway
    │   └── External Integrations
    ├── Components
    │   ├── Boundary
    │   ├── Runtime
    │   ├── Contract
    │   └── Storage
    └── Code
        └── Modules / Classes / Functions

落盘时，至少要能把每一层对应到一个文件或目录组：

• System Landscape -> README.md / docs/architecture/landscape.md
• System Context -> docs/architecture/system-context.md
• Containers -> docs/architecture/container.md
• Components -> docs/architecture/component.md
• Code -> apps/、packages/、services/、schemas/

推荐目录

system/
├── canonical/
│
│   ├── ontology/
│   │   ├── atoms/
│   │   ├── relations/
│   │   ├── capabilities/
│   │   ├── policies/
│   │   └── semantics/
│   │
│   ├── topology/
│   │   ├── runtime.graph.json
│   │   ├── storage.graph.json
│   │   ├── dependency.graph.json
│   │   └── ownership.graph.json
│   │
│   ├── contracts/
│   │   ├── schemas/
│   │   ├── events/
│   │   ├── APIs/
│   │   ├── manifests/
│   │   └── capabilities/
│   │
│   ├── governance/
│   │   ├── lifecycle/
│   │   ├── policy/
│   │   ├── ownership/
│   │   ├── consistency/
│   │   └── recovery/
│   │
│   ├── runtime/
│   │   ├── workflows/
│   │   ├── schedulers/
│   │   ├── executors/
│   │   ├── state-machines/
│   │   └── runtime-registry/
│   │
│   └── evolution/
│       ├── migrations/
│       ├── versions/
│       ├── entropy/
│       └── pruning/
│
├── projections/
│   ├── markdown/
│   ├── obsidian/
│   ├── docs/
│   ├── reader/
│   └── AI-context/
│
├── evidence/
│   ├── smoke/
│   ├── traces/
│   ├── failures/
│   ├── audits/
│   └── readbacks/
│
├── assets/
│
└── generated/

仓库文件树模板

repo/
├── README.md
├── project.json
├── catalog-info.yaml
├── docs/
│   ├── architecture/
│   │   ├── system-context.md
│   │   ├── container.md
│   │   ├── component.md
│   │   └── landscape.md
│   ├── contracts/
│   │   ├── openapi.yaml
│   │   ├── schema/
│   │   └── data-contract.md
│   ├── decisions/
│   │   └── ADR-xxxx-*.md
│   ├── operations/
│   ├── runtime/
│   └── evidence/
├── apps/
├── packages/
├── services/
├── schemas/
├── tests/
├── scripts/
├── inventories/
├── generated/
└── .runtime/

拓扑文件模板

{
  "name": "system-or-module-name",
  "owner": "team-or-person",
  "scope": "repo/system/container",
  "truth": ["canonical files or tables"],
  "dependencies": ["upstream nodes"],
  "relations": ["dependsOn", "readsFrom", "writesTo"],
  "contracts": ["openapi", "schema", "event"],
  "runtime": ["services", "jobs", "workers"],
  "storage": ["mysql", "s3", "cache"],
  "projections": ["README", "dashboard", "docs"],
  "evidence": ["tests", "smoke", "logs"],
  "docs": ["paths"]
}

文件规范原则

• 真源先于投影
• 合同先于实现
• runtime 不能反向定义 schema
• README 只能做索引和入口，不替代真源
• docs/ 负责解释，schemas/ 负责契约，tests/ 和 smoke 负责证据
• 目录树要能看出 owner、boundary、runtime、storage、projection 的分层
• 如果一棵树无法回答“谁拥有、谁调用、谁存储、谁投影、谁验证”，这棵树就不合格

大厂式标准件分工

成熟组织一般不会把所有架构事实塞进一个 README，而是拆成几类标准件：

职责边界：

• catalog-info.yaml 只登记 entity，不替代架构文档。
• README.md 只做入口和图纸索引，不承载所有真相。
• project.json 或 module.topology.json 负责机器可读项目图。
• docs/architecture/ 负责解释系统为什么这样分层。
• docs/contracts/ 和 schemas/ 承载可执行契约。
• docs/decisions/ 记录不能从当前代码直接看出的历史决策。
• tests/ 和 smoke 证明闭环，不写口号。

标准文件职责树

repo/
├── README.md                         # 人类入口；索引 truth / contract / runtime / evidence
├── project.json                      # 机器可读项目清单；project graph 节点
├── catalog-info.yaml                 # 软件目录实体；owner / lifecycle / system
├── docs/
│   ├── architecture/                 # C4 / 架构拓扑
│   │   ├── landscape.md              # 系统景观
│   │   ├── system-context.md         # 系统上下文
│   │   ├── container.md              # container / service 拓扑
│   │   └── component.md              # component 拓扑
│   ├── contracts/                    # 契约解释
│   │   ├── data-contract.md
│   │   └── api-contract.md
│   ├── decisions/                    # ADR
│   │   └── ADR-0001-record-architecture.md
│   ├── runtime/                      # runtime 面
│   │   ├── configuration.md
│   │   ├── service-addresses.md
│   │   └── observability.md
│   ├── operations/                   # 运维、恢复、迁移
│   └── evidence/                     # smoke、readback、audit 索引
├── schemas/                          # 可执行 schema
├── gateway/                          # gateway / API runtime
├── apps/                             # 应用入口
├── packages/                         # shared packages
├── services/                         # 服务或 worker
├── tests/                            # 自动化测试
├── scripts/                          # canonical entrypoints
├── generated/                        # 可重建产物
└── .runtime/                         # 本地运行证据；不是 truth

拓扑落地顺序

一个项目从混乱文件堆整理成标准结构时，按这个顺序：

1. 先补 README.md 的入口和图纸索引。
2. 再补 project.json 或 module.topology.json 的机器可读项目图。
3. 再补 catalog-info.yaml 的 owner / lifecycle / system 信息。
4. 再补 docs/architecture/ 的 C4 层级图。
5. 再补 docs/contracts/ 和 schemas/ 的契约。
6. 再补 docs/runtime/ 和 docs/operations/ 的运行与恢复。
7. 最后把 tests/、smoke、readback 作为 evidence 接上。

不能反过来。先写长文档、后找 truth，会把文档写成 shadow truth。

标准参考

• Backstage：软件目录、owner、lifecycle、system、component、API entity
• C4 Model：system context、container、component、code 四层图
• ADR / MADR：架构决策记录
• Nx / monorepo project graph：项目、包、依赖边界
• OpenAPI / JSON Schema：可执行 API 和数据契约

六大图

25 条根问题可以投影成六大图。

1. Ontology Graph

回答：

系统里有什么存在？

典型节点：

Atom
Capability
Policy
Identity
SemanticRole

2. Runtime Graph

回答：

谁执行谁？

典型节点：

Workflow
Executor
Scheduler
Queue
RepairLoop

3. Dependency Graph

回答：

谁依赖谁？

Dependency Graph 是 topology、boundary 和 anti-corruption 的共同证明。

4. Ownership Graph

回答：

谁拥有谁？
谁能写？
谁负责？

Ownership Graph 是 truth、policy、write authority 和 recovery 的共同证明。

5. Projection Graph

回答：

哪些东西是可重建 projection？

Projection Graph 必须能指回 truth，并给出 rebuild path。

6. Evolution Graph

回答：

系统如何演化？
哪些东西替代了哪些东西？

Evolution Graph 记录迁移、废弃、替换、折叠和删除，不让历史结构继续伪装成当前 truth。

十、从 ContentBase / DataBase 抽出的通用经验

这次真正暴露出来的不是某一个接口没写好，而是：

一个系统只要没有把 Truth、Runtime、Contract、Failure 四件事钉死，
就一定会滑向文件堆、提示词堆、脚本堆。

1. 规则不能只写在 prompt 里

Prompt 只能消费规则，不能拥有规则。

2. 文档不是 Truth

文档最好的位置是 executable truth 的投影，而不是 executable truth 的替身。

3. 不要为一个失败造一个小系统

临时脚本、旁路 JSON、shadow registry、fallback route、local helper、手工修复层，都会制造第二套神经。

4. Gateway 不是转发器，是边界法律

Gateway 应该负责认证、幂等、schema validation、权限边界、事务边界、错误显式化、canonical storage write、readback contract。

5. 失败必须成为一等对象

失败报告也必须能持久化。

6. 成功不能只看 HTTP 200

没有 readback 的 write，不算打通。

7. Smoke 不是演示，是最低限度的系统契约

Smoke 必须覆盖真实 runtime、真实 env、真实权限、真实 storage、真实 write、真实 readback。

8. 权限也是工程结构

权限文件也是 contract。

9. 外键错误通常是在提醒你缺少 owner

child 不能在没有 parent 的地方出生。

10. Runtime 只能消费 Contract，不能重写 Contract

DataBase owns contract，ContentBase consumes contract。

11. 幂等键是业务身份，不是随机字符串

幂等键表达的是“这次业务动作是谁”，不是“这次请求什么时候发生”。

12. 投影层必须能被重建

投影层如果不能重建，它已经变成了隐藏 Truth。

13. 工程完成的定义要升级

Done = truth、runtime、storage、projection、failure 全部闭环。

14. 通用工程公式

Truth owns rules
Contract carries rules
Runtime executes rules
Gateway enforces boundary
Storage persists facts
Projection renders facts
Smoke proves the loop
Failure leaves evidence

15. 最终判断标准

一个系统是否成熟，不是看它有多少功能，而是看它在失败时是否仍然有秩序。

成熟系统失败时会留下：

谁失败
为什么失败
失败在哪一层
损失是什么
能否重试
能否读回
能否重建
谁拥有修复权

不成熟系统失败时只留下：

报错了
没生成
没保存
不知道为什么
再试一次

十一、附录：原始材料合并映射

本文已将原始材料去重合并为一个 canonical 版本，信息归并关系如下。

1. 原 20 条清单

原始 1-20 条完整保留为本文 1-20：

Topology / Truth / Atom / Relation / Projection
Runtime / Boundary / Contract / Version / Failure
Ownership / Lifecycle / Storage / Access / Recovery
Identity / Observability / Capability / Policy / Evolution

2. 原 15 条旧版清单

原始“工程开工前的根问题清单”中的 15 条，已经折叠进本文 1-15，并保留了：

• 先问 topology，再写代码
• Truth 不明确会导致系统分裂
• Atom / Relation / Projection 的解释
• Runtime / Boundary / Contract 的边界
• Version / Failure / Ownership / Lifecycle / Storage / Access / Recovery 的工程意义

3. 原评价段落

原始“系统工程元问题”“系统存在论”“Graph-native Runtime Engineering Philosophy”“Runtime Civilization Thinking”等判断，已经合并进：

• 开头定位
• 四层分类
• Dynamics 说明
• 最终判断标准

4. 原跨领域适用性

原始列举的软件工程、分布式系统、数据系统、内容系统、AI Runtime、操作系统、编译器、Git、Kubernetes、LangGraph / Temporal / Airflow，以及 Web、游戏、组织架构等适用范围，已压缩进 25 条根问题的知识点和本附录。

这些根问题不依赖具体技术栈，可用于：

Web 系统：Next.js / Astro / React
AI Runtime：LangGraph / Temporal / Agent / Workflow
内容系统：CMS / Reader / EPUB / Knowledge Base
数据平台：Data Warehouse / Canonical Graph
游戏：Entity / Component / State / Runtime
OS / Infra：Process / Scheduler / Filesystem / Recovery
组织架构：Ownership / Boundary / Contract / Policy

5. 原 Graph / Obsidian 讨论

原始关于文章拓扑化、Markdown 不是 Truth、YAML + Markdown、Aggregate Graph Document、BlockNote、Tiptap、Logseq、Obsidian Graph、Dataview、Canvas、Excalidraw、Metadata Menu、Breadcrumbs 的讨论，已合并进“Graph-native / Obsidian 应用”。

保留的核心判断是：

Canonical Graph
↓
Projection Markdown
↓
Obsidian Surface

而不是：

Obsidian Markdown
↓
推导 Graph

6. 原 ContentBase / DataBase 经验

原始 15 条工程经验已完整压缩进“从 ContentBase / DataBase 抽出的通用经验”，并与“工程完成定义”和“反模式清单”交叉承载。

7. 原低耦合 / 高内聚 / 自包含 / 子描述讨论

原始关于低耦合、高内聚、自包含、description of subparts 的讨论，已合并进“横切原则：补强 25 问”的 Cohesion / Coupling / Self-contained Description。

保留的核心判断是：

高内聚 = capability 内部自洽。
低耦合 = capability 之间只经 contract 交互。
自包含 = 理解、执行、验证不依赖隐式外部记忆。

并保留了每个 atom / capability / graph node 必须携带：

purpose
boundary
inputs
outputs
invariants
failure modes
children

8. 原 7 个系统级缺口

原始提出的 7 个系统级缺口没有删除，而是作为横切原则嵌入 25 问：

9. 原文件拓扑与六大图讨论

原始关于“25 点的文件拓扑”“文明级文件拓扑”“推荐目录”“六大图”的讨论，已合并进“文件拓扑与六大图”。

保留的核心判断是：

没有 topology 的哲学，最终还是 Markdown 堆。

以及：

Ontology
→ Contract
→ Runtime
→ Evidence
→ Projection
→ Evolution

10. 最终保留的核心哲学

系统抽象能力上升时，局部规则数量必须下降。
 
否则，再高级的 Runtime / DAG / Graph，
最后都会重新退化成一大坨 if-else。