# 一源双生 白皮书 / One-Duality (Unity Duality) Whitepaper

> 一元双生：同一份知识只保存一份权威来源（一元），同时以两种形态存在（双生）——对人是 HTML 网页，对机器是 JSON / Markdown；两者通过统一接口（同一地址、稳定 id、同一版本号）打通，所有修改以 JSON Patch 提议、由人采纳、零 Token 编译发布。本文是 CaseForge「一源双生 + 增量补丁」背后的理论说明，并且本身就是一个 CaseForge 文档。
>
> One-Duality: one body of knowledge keeps a single authoritative source (the "one") and exists in two forms at once (the "duality") — HTML pages for people, JSON / Markdown for machines — bridged by a unified interface (one address, stable ids, one version number). Every change is proposed as a JSON Patch, adopted by a human and published by a zero-token compiler. This paper is the theory behind CaseForge's "one source, twin outputs + incremental patches", and is itself a CaseForge document.

版本 v6 · 编译 2026-11-11 23:34 UTC · 双语 zh-en · 状态 open · 标签 白皮书, SSOT, JSON 补丁, llms.txt, Markdown

方括号内为稳定 id，JSON Patch 路径形如 /entities/<id>/description、/timeline/<id>。

## 机器可读资源

- [case.json](https://ostoai.com/c/one-duality/case.json): 完整 SSOT（JSON，含 _meta 版本信息）
- [index.html](https://ostoai.com/c/one-duality/): 人类阅读版
- [index.md](https://ostoai.com/c/one-duality/index.md): Markdown 孪生版（完整正文，适合 LLM 直接阅读）
- [JSON Schema](https://ostoai.com/schema/case.json): 案件文档结构

## 时间线

- [m-20261111-md] 2026-11-11 编译器新增 Markdown 孪生 index.md 与 Accept 内容协商 / Compiler gains the Markdown twin index.md and Accept negotiation
- [m-20261111-wp] 2026-11-11 一元双生白皮书 v1 以 CaseForge 文档形式发布 / One-Duality whitepaper v1 published as a CaseForge document

## 实体

- [ssot] 单一事实源 SSOT / Single Source of Truth (SSOT)（document，唯一可编辑的权威文档 / The only editable authority）：受 JSON Schema 约束的 case.json，按版本保存。 / case.json constrained by a JSON Schema, stored by version.
- [html-twin] 人类孪生 index.html / Human twin: index.html（document，给人读 / For people）：排版、目录、关系图与双语对照。 / Typography, table of contents, concept map and bilingual layout.
- [md-twin] Markdown 孪生（正文版） / Markdown twin: index.md（document，给模型读完整正文 / Full prose for models）：低噪声的完整正文，适合 LLM 直接阅读与引用。 / Low-noise full text, ready for an LLM to read and cite.
- [json-twin] 机器孪生 case.json / Machine twin: case.json（document，给程序读完整结构 / Full structure for programs）：完整 SSOT 加 _meta（版本、哈希、其他孪生的地址）。 / The full SSOT plus _meta (version, hash, addresses of the other twins).
- [llms-twin] 给人工智能的索引文件 / AI index: llms.txt（document，给 AI 爬虫的目录 / A table of contents for AI crawlers）
- [patch-engine] 补丁引擎 / Patch engine（other，JSON Patch 提议、校验、分级 / Proposes, validates and grades JSON Patches）
- [gates] 闸门 / Gates（other，结构、风险、化名、币种 / Schema, risk, pseudonym, currency）
- [human] 人类审阅者 / Human reviewer（person，采纳或拒绝 / Adopts or rejects）
- [agents] AI 代理 / AI agents（other，会议室中的多个角色 / Multiple roles in the meeting room）
- [compiler] 零 Token 编译器 / Zero-token compiler（other，确定性渲染全部孪生 / Deterministically renders every twin）

## 关系

- [r-01] agents --提议补丁 / propose patches--> patch-engine
- [r-02] human --编辑 / edits--> patch-engine
- [r-03] patch-engine --送检 / checked by--> gates
- [r-04] gates --请求采纳 / asks to adopt--> human
- [r-05] human --采纳 → 新版本 / adopt → new version--> ssot
- [r-06] ssot --输入 / input--> compiler
- [r-07] compiler --生成 / renders--> html-twin
- [r-08] compiler --生成 / renders--> md-twin
- [r-09] compiler --生成 / renders--> json-twin
- [r-10] compiler --生成 / renders--> llms-twin
- [r-11] human --阅读 / reads--> html-twin
- [r-12] agents --读取 / reads--> md-twin

## 争点

- [q-negotiation] 内容协商与缓存 / Content negotiation and caching（open）：同一地址按 Accept 返回不同形态时，需要确保所有中间缓存都尊重 Vary: Accept；否则应优先使用显式后缀。 / When one address returns different forms by Accept, every intermediate cache must honour Vary: Accept; otherwise explicit suffixes should be preferred.
- [q-signing] 签名格式选择 / Choice of signature format（open）：签名溯源可采用多种现成方案，需要在可验证性、工具成熟度和运维成本之间权衡。 / Signed provenance can use several existing schemes; verifiability, tooling maturity and operational cost must be weighed.
- [q-granularity] 补丁粒度 / Patch granularity（open）：长篇章节以段落为单位还是以整节为单位打补丁，影响 diff 的可读性和翻译缓存的复用率。 / Whether long-form sections are patched per paragraph or per section affects diff readability and translation-cache reuse.

## 正文章节（完整正文见 index.md 或 case.json 的 sections）

- 一、背景 / 1. Background：[sec-01] 人读网页，机器读结构 / Humans read pages, machines read structure；[sec-02] 问题：两套副本，一种漂移 / The problem: two copies, one drift
- 二、概念定义 / 2. Definition：[sec-03] 一元双生：定义 / One-Duality: definition；[sec-04] 五条原则 / Five principles；[sec-05] 术语 / Glossary
- 三、架构 / 3. Architecture：[sec-06] 架构总览 / Architecture overview；[sec-07] 数据流 / Data flow；[sec-08] Mermaid 文字描述 / Mermaid text description
- 四、统一接口设计 / 4. Unified Interface Design：[sec-09] 单一事实源与结构约束 / A single SSOT and its schema；[sec-10] 内容协商与 URL 约定 / Content negotiation and URL conventions；[sec-11] 稳定 ID / Stable IDs；[sec-12] 增量补丁（JSON 补丁） / Incremental JSON Patch；[sec-13] 版本与回滚 / Versioning and rollback；[sec-14] 人类采纳闸门 / The human adoption gate；[sec-15] 零 Token 编译 / Zero-token compilation；[sec-16] 闸门示例：化名与币种 / Gate examples: pseudonyms and currency
- 五、与 os2ai.com 和 CaseForge 的关系 / 5. Relationship to os2ai.com and CaseForge：[sec-17] os2ai.com 多智能体编排 / os2ai.com multi-agent orchestration；[sec-18] CaseForge：一元双生的参考实现 / CaseForge: the reference implementation；[sec-19] 实例：抚养费执行案档案 LilyCase / Worked example: LilyCase；[sec-20] 本白皮书即自证 / This whitepaper eats its own cooking
- 六、未来方向 / 6. Future Directions：[sec-21] MCP 与代理端点 / MCP and agent endpoints；[sec-22] 向量索引 / Vector index；[sec-23] 签名溯源 / Signed provenance；[sec-24] 多用户与权限 / Multiple users and permissions；[sec-25] 联邦 / Federation；[sec-26] Mac 本地大模型 / Local LLMs on a Mac；[sec-27] 路线图（示意） / Roadmap (illustrative)
- 七、结语 / 7. Conclusion：[sec-28] 结语 / Closing

## Optional

- [RFC 6902 — JSON 补丁标准](https://www.rfc-editor.org/rfc/rfc6902): [rfc6902] 
- [llms.txt 规范提案说明](https://llmstxt.org/): [llmstxt] 
- [模型上下文协议 MCP](https://modelcontextprotocol.io/): [mcp] 
- [案件引擎文档结构定义](https://ostoai.com/schema/case.json): [caseforge-schema] 
- [实例：LilyCase（化名）](https://ostoai.com/c/lilycase/): [lilycase]