Repository navigation
Commit ddb3360
docs(readme): say "ontology-driven" beside "the ontology is the software" (#24771)
Fixes #24754
Clause-②: no
The README now says "ontology-driven" beside "the ontology is the
software" — one file, two insertions, no structural change. Draft on
purpose: the wording is the maintainer's positioning and lands only on
his word on the text.
## The maintainer's words (verbatim — the ruling this PR executes)
> 「salesforce 之前叫元数据驱动,我们现在可以叫本体驱动吗」
> 「本体驱动 会不会和本体即软件更搭」
> 「立卡,更新 README」
## What changed — before / after of every changed line
`README.md`, 452 → 463 lines: one line changed, eleven added, nothing
removed.
**Thesis block** — line 12 changed, lines 13–16 new:
```diff
> **One executable business ontology.** AI writes it, the runtime runs it, agents
> operate it, you own it.
>
-> 本体即软件。
+> 本体即软件,本体驱动。
+>
+> Ontology-driven: database, API, UI and agent tools all derive from that one
+> definition of the business, so there is no second codebase to keep in step
+> with it.
>
> Apps small enough for AI to hold whole.
```
**〈What we mean by ontology〉** — a new paragraph at lines 97–102,
between the definition paragraph and the compare paragraph:
```diff
form is the [glossary entry](https://objectstack.ai/docs/getting-started/glossary#business-ontology).
+Metadata-driven, as the previous generation of platforms used the word, names
+the mechanism — behaviour derived from a declarative definition instead of
+written as code — and ObjectStack keeps it. Calling the stack ontology-driven
+names what that definition is and whose it is: a definition of the business
+rather than configuration of a platform, an open format in your repository
+rather than inside a vendor's system, and written for an agent to read.
+
[How it compares](https://objectstack.ai/docs/concepts/compare) sets ObjectStack
```
Untouched by design: the h2 and the bold four-promise sentence
(`compare.mdx` "In one sentence" and `ontology.mdx` line 7 repeat it
verbatim); the tag row (it mirrors the essay's four promises and the
demo gif's closing alt text); the section's two boundary sentences (not
a knowledge-representation ontology, not a semantic layer),
byte-identical; every link; every other section.
## Why these words — measured against the pages the README must agree
with
- `content/docs/concepts/compare.mdx` §Metadata-driven application
platforms: "the closest relatives … Salesforce's metadata is the
ancestor"; the difference is "where the definition lives, and who it is
written for" — typed TypeScript in your repository, shaped for an AI to
write. Its side-by-side row grants metadata-driven platforms
"Executable: Yes" and "Is the system itself: Yes". So the README does
NOT separate on "one source the runtime, API, UI and agents consume" or
on "the definition is the system" — both hold for the relatives too —
and it does not claim "no second application beside it" (README lines
92–93: code moves into the runtime as hooks, action bodies, CEL and
constrained JSX). The dispatch's suggested sentence carried both claims;
that is the recorded reason for departing from it.
- `content/blog/the-ontology-is-the-software.mdx` lines 230–236: "Not
Salesforce's metadata, either, though that is the closest ancestor …
What it was not: an open format, a thing you could take with you, or a
thing written for an agent to read." The new paragraph's three contrasts
are exactly those three.
- `content/docs/concepts/ontology.mdx` line 80 links "Metadata-Driven
Development" as what one definition derives, and
`content/docs/concepts/metadata-driven.mdx` defines that paradigm in
ObjectStack's own voice. So the README keeps metadata-driven as the
mechanism ("and ObjectStack keeps it") and lets ontology-driven name
what the definition is and whose it is — the card's two-level claim,
with no page contradicted.
- The essay's one prior use of the exact phrase is Guarino's 1998
"ontology-driven information systems" (line 215): a description to
design against, not a thing to run. The README's first use therefore
carries its executable definition in the same breath, and the section's
"validated rather than reasoned over" boundary stands untouched beside
it.
- Bilingual pairing: 「本体即软件,本体驱动。」 mirrors "the ontology is the
software, and the software is ontology-driven"; English
"ontology-driven" appears in the same block (line 14) and lowercase in
the section. Acceptance greps on the committed tree: `grep -c
"ontology-driven" README.md` = 1, `grep -c "本体驱动" README.md` = 1.
## 维护者速读(草稿)
**改了什么。** 只动 `README.md`,两处插入、零删除:①
论点块里「本体即软件。」变成「本体即软件,本体驱动。」,其下新增一行英文给 ontology-driven
下定义(数据库、API、UI、agent 工具全部从同一份业务定义派生,旁边不再有第二套代码库要跟着改);② 〈What we mean by
ontology〉新增一段两句话:metadata-driven
是上一代平台对机制的叫法(行为由声明式定义派生而非手写代码),ObjectStack 保留这套机制;叫它 ontology-driven
说的是这份定义是什么、归谁 —— 业务的定义而非平台的配置,放在你仓库里的开放格式而非锁在厂商系统里,并且写给 agent 读。
**为什么改。** 你的原话:「salesforce 之前叫元数据驱动,我们现在可以叫本体驱动吗」「本体驱动
会不会和本体即软件更搭」。两级主张分工:「本体即软件」答是什么,「本体驱动」答怎么跑。措辞按四轴自评 ——
实际需求:这是你点名的定位句,不是投机面;对外三页(compare、ontology、essay)已把 Salesforce
定为「最近的祖先」,README 只是把这层关系说出来。长远合理:新段的三个对比词逐字对应 essay 第 230–236 行对
Salesforce metadata 的三条「它不是」(开放格式、可带走、写给 agent 读),不另造口径。防 AI
误读:ontology-driven 在 essay 里唯一一次出现是 Guarino 1998 的非执行义,README
首次出现即带可执行定义,且紧邻「validated rather than reasoned over」的既有边界,不给 AI
读成知识本体的空间。不扩散:不改标签行(它镜像四个承诺与 gif 结尾文案)、不改加粗四承诺句(compare 与 ontology
页逐字复用)、不加节、不加链接。
**风险与代价(含回滚)。** 口径一致性:我们自己的文档在 41 个文件里(含 CHANGELOG、ADR 与 release notes)以
ObjectStack 的口吻说 metadata-driven —— docs 首页、getting-started 首页、concepts
索引的「Metadata-Driven Development」一节、design-principles、`packages/core` 与
`packages/cli` 的 README、create-objectstack 的 AGENTS.md 模板「a
metadata-driven low-code project」。本 PR 的措辞刻意不否定它:metadata-driven
仍是机制名,ontology-driven 是加在它之上的命名,所以不与任何一页矛盾;但若你要把 ontology-driven
立为统一用词,那些页面要另开 PR 跟进(见 Acceptance notes)。回滚代价为零:单文件、纯文本,`git revert`
一次即回到 452 行原样。
**席位意见。** (留空,席位定稿。)
**你要做的。** 对措辞拍板三件事:① 中文对句用「本体即软件,本体驱动。」(逗号成一句)还是「本体即软件。本体驱动。」(两句并列);②
英文定义行用现在的「Ontology-driven: …」标签式,还是改成完整对句「The ontology is the software,
and the software is ontology-driven: …」;③ 第二段的三个对比词(业务的定义、你仓库里的开放格式、写给
agent 读)是否就是你想对外说的三件事。点头后席位翻 ready 入队;要改字就在本 PR 上改,正文改动归席位。
## Verification
Gates — the nine families `node scripts/pm/dispatch-gates.mjs --commands
--repo objectstack-ai/objectstack` derives for this change at
`4cc84f1e54` (identical to the dispatch's harvest at `580fd4ed3c`), each
exit captured before any pipe, then reconciled:
| command | exit |
| :--- | :--- |
| `node scripts/check-closing-keyword-parity.mjs` | 0 |
| `node scripts/check-closing-keyword-parity.mjs --self-test` | 0 |
| `node scripts/check-comment-mask-corpus.mjs` | 0 |
| `pnpm check:doc-anchors` | 0 — "540 internal #fragment link(s) across
423 source file(s) all resolve to a real heading" |
| `pnpm check:driver-memory-census` | 0 |
| `pnpm check:gitlink-declared` | 0 |
| `pnpm check:nul-bytes` | 0 — "scanned 12505 text file(s) … no raw
ASCII control bytes" |
| `pnpm check:refd-timer-probe` | 0 |
| `pnpm check:watch-hint-literal` | 0 |
`dispatch-gates --ran`: "9 derived, 9 run, 0 NOT-MEASURED, 0 UNRUN",
exit 0. Control-byte scan of `README.md`: empty. No package is touched,
so there is no build closure, no package test and no typecheck to run (①
empty, ② empty); `pnpm lint` and the full farm are CI's. `README.md`
ships in no package's `files[]`, so no changeset; `skip-changeset` is
declared on this PR.
## Acceptance notes (observed, not filed)
- Our own docs use metadata-driven in ObjectStack's voice across 41
files (the load-bearing ones are named in the 速读). The README was
written to sit on top of that term, not against it; if ontology-driven
becomes the house term, those pages follow in their own PRs. carrier:
the `domain:skills` seat, to the maintainer · noted, not filed.
- `content/docs/concepts/compare.mdx` grants metadata-driven platforms
"Executable: Yes" and "Is the system itself: Yes", which is why the
README's differentiator is openness, ownership and agent-readability
rather than "one source the runtime consumes". No contradiction;
recorded so the next edit of either page keeps them aligned. carrier:
none · noted, not filed.
- Dispatch hypothesis 1 said "metadata" occurs on two README lines (28,
77); measured on `580fd4ed3c` it occurs on 22 lines. The load-bearing
half — "metadata-driven" zero occurrences — holds, and none of the 22
was touched.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01HEdP5tPhqQfzwRmKDxwn85)_
---------
Co-authored-by: objectstack-fleet[bot] <objectstack-fleet[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>1 parent 6387793 commit ddb3360
1 file changed
Lines changed: 11 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
11 | 11 | | |
12 | 12 | | |
13 | 13 | | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
14 | 18 | | |
15 | 19 | | |
16 | 20 | | |
| |||
90 | 94 | | |
91 | 95 | | |
92 | 96 | | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
93 | 104 | | |
94 | 105 | | |
95 | 106 | | |
| |||
0 commit comments