OntoSoma

你系统的活体本体,永远等于代码。 The living body of your system — always equal to the code.

OntoSoma 是一个面向 AI 开发/运维/迭代全生命周期的本体(ontology)工具。它把一套软件系统的「设计意图 / 源代码 / 运行时」三样东西,从"三份会互相漂移的副本",收敛成同一个本体的三个投影,并用规则闸保证它们之间零漂移。

它的目标是控制 AI 开发的随机性、固化系统的结构与边界、让人和 AI 在同一个"活的、且永远为真的"模型上做需求分析、设计、构建与运维。

30 秒理解

当前 AI 开发的痛点:写跑偏(随机性)、写完跟设计对不上(漂移)、文档很快过期、每个会话都要从零重新"理解"代码库且每次理解都偏一点。

OntoSoma 的解法是一句话:

只管理"投影之间的差"。 设计、代码、运行时本就是一个本体的不同看法,漂移不是靠纪律去防,而是结构上不可能。

• 三位一体,零漂移 —— 代码是唯一真源,本体从代码派生,设计态与实际态可 diff;偏离必然显形。
• 本体即文档 —— 没有独立的、会过期的文档。一切记录(为什么这么设计、何时变的)钉在本体对象上,随时间轴回放。
• 低心智负担 —— 一个本体,N 个镜头(高度 × 关注面 × 时间 × 焦点),只回答你此刻问的那一个问题,而不是甩你一张全景图。
• 运行态实时体现 —— 不止静态代码,还含运行时:哪些 MCP/skill/tool 注册在哪、怎么跑、跟谁交互。spec 工具是标本,OntoSoma 是活体。

「合格的本体天然含零漂移和真源,否则它只是个会过期的文档,不配叫本体。」

它跟 openspec / superpowers 是什么关系

• superpowers = 怎么做(思维/流程,Markdown skills)。
• openspec = 做之前说清楚(spec,但 spec 与代码分离、会漂移)。
• OntoSoma = 把"说清楚 → 做 → 验证一致 → 可追溯演化 → 运行时仍为真"焊成一个不漏气的闭环,且本体是活的(含运行态)。

OntoSoma 在分发与跨工具适配上借鉴 superpowers/openspec 的成熟做法(Markdown + AGENTS.md + 各 harness 薄清单 + 零依赖),但多出两件它们没有的东西:闭环对账 与 三态(设计/代码/运行)统一。

仓库形态(规划)

独立 monorepo。OntoSoma 是工具本体,不寄生在任何使用它的项目里;它把别的代码库当作分析目标(第一个狗粮目标是隔壁的 A-CDM)。

ontosoma/
├─ AGENTS.md            # 方法论注入入口(跨工具标准),搞清楚后接入
├─ skills/              # 方法论内容层(Markdown,描述动作不点名工具)
├─ packages/
│  ├─ engine/           # 派生器 + 闸 + 本体存储(TypeScript)
│  ├─ web/              # 可观测 web(读同一份本体产物)
│  └─ reporters/        # 运行态薄 SDK(按目标 app 语言,只发事件)
├─ docs/                # 见下方文档索引
└─ .ontosoma/           # 派生出的本体产物(当 lockfile 提交)

当前处于初始化阶段(pre-alpha):仅落库设计文档,代码尚未开工。

文档索引

| 文档 | 内容 | |---|---| | docs/vision.md | 愿景与哲学:为什么、是什么、四根支柱、闭环、对比 | | docs/architecture.md | 架构与技术:三态、两条数据腿、本体即 lockfile、镜头、技术栈 | | docs/decisions.md | 已锁定的关键决策 + 为什么(名字/栈/存储/独立仓/分发/构建路线) | | docs/brand.md | 命名/拼写/定位约定:官方写法、canonical 锚点、防同形术语稀释 |

路线(分阶段:先传统,后狗粮)

1. 阶段 0 — 初始化(本次):落库设计文档,锁定名字与技术栈。
2. 阶段 1 — 传统构建:用最常规的方式把骨架搭起来——派生器(tree-sitter)+ 本体产物(lockfile)+ 规则闸跑通。先把概念跑顺,不急着炫。
3. 阶段 2 — 立即吃狗粮:概念一清,马上让 OntoSoma 描述 OntoSoma 自己,并对准 A-CDM 验证「本体即文档 + 三态对账」。
4. 阶段 3 — 通用分发:补 web 观测 + session 注入 + 各 harness 薄清单,做成可插入任意 AI 工具的插件。

名字:OntoSoma = Onto(本体/存在)+ Soma(身体/活体),两个希腊词根,意为"系统的活体本体"。中文统称「本体」。官方拼写 OntoSoma(包名 ontosoma),约定见 docs/brand.md。

定位澄清:OntoSoma 是代码/系统本体工具(给 AI 开发/运维/迭代用),不是语义网 / OWL / RDF 工具。