OS2AI CaseForge · 白皮书 Whitepaper · v6 · 双语 中｜EN

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

进行中白皮书 / whitepaperSSOTJSON 补丁 / JSON Patchllms.txtMarkdown

摘要 / Summary

一元双生：同一份知识只保存一份权威来源（一元），同时以两种形态存在（双生）——对人是 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.
本白皮书为概念与设计文档。凡标注「示意」的图示、规则与路线图仅作说明，不代表实测数据或承诺；LilyCase 示例仅使用化名。
This whitepaper is a concept and design document. Anything marked "illustrative" (diagrams, rules, roadmap) is explanatory only and is neither measured data nor a commitment; the LilyCase example uses pseudonyms only.

正文 / Whitepaper

目录（7 个页面，28 个区块）
  1. 一、背景 / 1. Background
  2. 二、概念定义 / 2. Definition
  3. 三、架构 / 3. Architecture
  4. 四、统一接口设计 / 4. Unified Interface Design
  5. 五、与 os2ai.com 和 CaseForge 的关系 / 5. Relationship to os2ai.com and CaseForge
  6. 六、未来方向 / 6. Future Directions
  7. 七、结语 / 7. Conclusion

一、背景 / 1. Background

人读网页，机器读结构 / Humans read pages, machines read structure

人类喜欢阅读类似 HTML 的 Web 界面：有标题层级、排版、颜色、图表、可点击的链接和折叠目录。好的网页把注意力引导到重点上，让人在几分钟内建立对一件复杂事情的整体印象。
Humans like reading HTML-style web interfaces: heading hierarchy, typography, colour, diagrams, clickable links and collapsible tables of contents. A good page steers attention to what matters and lets a person build a mental model of a complex matter within minutes.
计算机则偏好结构化、低噪声的格式。存储和交换文档时，JSON 适合精确的字段、标识和可校验的结构；Markdown 适合长篇正文，几乎没有标记噪声。对大语言模型（LLM）来说，读一份干净的 Markdown 或 JSON，远比解析一整页带样式和脚本的 HTML 省事，也更不容易出错。
Computers prefer structured, low-noise formats. For storing and exchanging documents, JSON is good at precise fields, identifiers and validatable structure; Markdown is good at long-form prose with almost no markup noise. For a large language model (LLM), reading clean Markdown or JSON is far easier and less error-prone than parsing a full page of styled, scripted HTML.
还有第三个观察：计算机的「外脑」——硬盘、外存、知识库——今天实际上就住在网站上。人向 AI 提问，AI 就去网站上查找、引用、核对。网站因此不再只是给人看的橱窗，也是机器的长期记忆。
A third observation: a computer's "external brain" — its disks, external storage and knowledge bases — effectively lives on websites today. A human asks an AI a question; the AI goes to websites to look things up, cite and cross-check. A website is therefore no longer only a shop window for people; it is also long-term memory for machines.

问题：两套副本，一种漂移 / The problem: two copies, one drift

现实中，同一份知识常常被维护成两套：一套给人看的网页，一套给程序用的数据或文档。两套副本由不同的人、在不同时间修改，迟早会不一致。
In practice the same knowledge is often maintained twice: a web page for people and a data file or document for programs. The two copies are edited by different people at different times and sooner or later disagree.
• 漂移：网页改了，数据没改；或者反过来。
• Drift: the page changes but the data does not, or vice versa.
• 浪费：AI 每次都要抓取并清洗整页 HTML，耗费 Token，还可能误读导航、广告和脚本。
• Waste: an AI must fetch and clean full HTML every time, spending tokens and risking misreading navigation, ads and scripts.
• 无审计：谁在什么时候改了哪一句，往往无从追溯，也难以回滚。
• No audit trail: who changed which sentence and when is often untraceable and hard to roll back.
• AI 直接改写风险高：让模型整篇重写文档，容易悄悄丢失事实、引入幻觉或泄露隐私。
• Risky AI rewrites: letting a model rewrite a whole document can silently drop facts, introduce hallucinations or leak private data.

二、概念定义 / 2. Definition

一元双生：定义 / One-Duality: definition

「一元双生」（One-Duality，亦称 Unity Duality）指：同一份知识（一元）只保存一份权威来源，并以两种形态同时存在（双生）——对人是 HTML Web 界面，易读；对机器是 JSON、Markdown 结构化数据，易解析。两种形态通过统一接口打通：同一个地址、同一套标识、同一个版本号。
One-Duality (also called Unity Duality) means: one body of knowledge (the "one") keeps a single authoritative source and exists simultaneously in two forms (the "duality") — HTML web pages for humans, easy to read; JSON / Markdown structured data for machines, easy to parse. The two forms are bridged by a unified interface: the same address, the same identifiers, the same version number.
关键在于：两种形态都不是手写的，而是从同一个单一事实源（SSOT，Single Source of Truth）编译出来的。人看到的网页和机器读到的数据，在任何一个版本上都逐字对应，不可能各说各话。
The key point: neither form is hand-written. Both are compiled from the same Single Source of Truth (SSOT). For any given version, the page a person sees and the data a machine reads correspond word for word; they cannot tell different stories.
在 CaseForge 中，这一思想的工程表述是「一源双生 + 增量补丁」：一源 = SSOT（case.json），双生 = 人类版与机器版，增量补丁 = 所有修改都以 JSON Patch 的形式提出、由人采纳、形成新版本。
In CaseForge the engineering form of this idea is "one source, twin outputs + incremental patches": one source = the SSOT (case.json); twins = the human and machine outputs; incremental patches = every change is proposed as a JSON Patch, adopted by a human, and becomes a new version.

五条原则 / Five principles

• 唯一真源：只有 SSOT 可以被修改；HTML、Markdown、llms.txt、case.json 都是派生物。
• Single source: only the SSOT is ever edited; HTML, Markdown, llms.txt and case.json are derivatives.
• 形态派生：每一种呈现都由确定性的编译器生成，不调用模型、不消耗 Token，同样的输入永远得到同样的输出。
• Derived forms: every rendering is produced by a deterministic compiler that calls no model and spends no tokens; the same input always yields the same output.
• 稳定标识：每个实体、事件、章节都有不变的 id，人和机器可以用同一个 id 引用、链接、打补丁。
• Stable identifiers: every entity, event and section has a permanent id, so humans and machines can cite, link and patch it by the same id.
• 增量演化：修改以小而可审阅的补丁提交，而不是整篇重写；每次采纳产生新版本，可对比、可回滚。
• Incremental evolution: changes arrive as small, reviewable patches rather than whole rewrites; each adoption creates a new version that can be diffed and rolled back.
• 人类把关：AI 可以提议，人来决定。高风险修改必须显式确认，隐私和数据质量闸门在发布前自动检查。
• Human in charge: AI may propose, people decide. High-risk changes require explicit confirmation, and privacy and data-quality gates run automatically before publishing.

术语 / Glossary

• SSOT（单一事实源）：受 JSON Schema 约束的 case.json，是唯一可编辑的权威文档。
• SSOT (Single Source of Truth): the case.json constrained by a JSON Schema; the only editable, authoritative document.
• 人类孪生：index.html，面向阅读、导航和理解。
• Human twin: index.html, built for reading, navigation and understanding.
• 机器孪生：case.json（完整结构）、index.md（完整正文）、llms.txt（面向 AI 的索引）。
• Machine twins: case.json (full structure), index.md (full prose) and llms.txt (an index for AI).
• 补丁：RFC 6902 JSON Patch，一组 add、replace、remove 操作，带作者、理由和风险级别。
• Patch: an RFC 6902 JSON Patch — a list of add / replace / remove operations carrying an author, a rationale and a risk level.
• 闸门：在采纳或发布前运行的检查，例如结构校验、风险分级、化名隐私检查和币种标注检查。
• Gate: a check that runs before adoption or publishing, such as schema validation, risk levels, pseudonym privacy checks and currency-label checks.

三、架构 / 3. Architecture

架构总览 / Architecture overview

下图是一元双生的最小架构。写入只有一条路：补丁 → 闸门 → 人类采纳 → 新版本 SSOT。读取有多种形态，但都来自同一个版本的编译结果。
The diagram below shows the minimal One-Duality architecture. There is only one write path: patch → gates → human adoption → new SSOT version. There are several read forms, all compiled from the same version.
人 / AI 代理 Humans / Agents→JSON Patch 提议 Proposal→闸门 Gates→人类采纳 Human adopt→SSOT 新版本 New version
写入路径（示意）
SSOT case.json→零 Token 编译器 Zero-token compiler→index.html（人 Human）
SSOT case.json→零 Token 编译器 Zero-token compiler→index.md · llms.txt · case.json（机器 Machine）
读取路径（示意）
                    ┌──────────────────────────────────────────┐
  Humans ─────────▶ │  Cockpit · Meeting room · Editor (admin) │ ◀─── Agents
                    └──────────────┬───────────────────────────┘
                                   │  JSON Patch (RFC 6902) proposals
                                   ▼
                    ┌──────────────────────────────────────────┐
                    │  Gates: schema · L1/L2/L3 · pseudonym ·  │
                    │         currency · human adopt           │
                    └──────────────┬───────────────────────────┘
                                   │  adopt → new version (v+1), diff, rollback
                                   ▼
                    ┌──────────────────────────────────────────┐
                    │  SSOT (the One): case.json, versioned    │
                    └──────────────┬───────────────────────────┘
                                   │  zero-token compiler (Jinja2, pure Python)
             ┌─────────────────────┼─────────────────────┬──────────────────┐
             ▼                     ▼                     ▼                  ▼
        index.html             index.md              llms.txt           case.json
     (human twin)        (Markdown twin)        (AI index twin)     (machine twin)
             └──────────── one URL family: /c/<slug>/ + Accept negotiation ───┘

数据流 / Data flow

• 写入：人在指挥舱中编辑，或 AI 代理在会议室中讨论后提出 JSON Patch；补丁先经过结构校验和风险分级，再进入待审队列。
• Write: a person edits in the cockpit, or AI agents discuss in the meeting room and propose a JSON Patch; the patch is validated and risk-graded, then queued for review.
• 采纳：管理员查看 diff 后采纳；高风险补丁需要二次确认。采纳即产生新版本，旧版本完整保留。
• Adopt: an administrator reviews the diff and adopts; high-risk patches need a second confirmation. Adoption creates a new version; old versions are kept intact.
• 编译：新版本立即被零 Token 编译器渲染为全部孪生形态，并在写盘前再跑一次隐私与数据质量闸门。
• Compile: the new version is immediately rendered into all twin forms by the zero-token compiler, and privacy and data-quality gates run again before anything is written.
• 读取：人打开网页；AI 读取 Markdown、llms.txt 或 case.json；同一个地址可按 Accept 头返回不同形态。
• Read: people open the page; an AI reads Markdown, llms.txt or case.json; the same address can return different forms according to the Accept header.

Mermaid 文字描述 / Mermaid text description

下面是同一架构的 Mermaid 描述，可直接粘贴到支持 Mermaid 的编辑器中渲染。
Below is a Mermaid description of the same architecture; paste it into any Mermaid-capable editor to render it.
flowchart TD
  H[Human reader] -->|asks / reads| HTML[index.html]
  A[AI agent] -->|fetches| MD[index.md / llms.txt / case.json]
  H -->|edits / adopts| G{Gates + human adopt}
  A -->|proposes JSON Patch| G
  G -->|adopted| S[(SSOT case.json, versioned)]
  S -->|zero-token compile| HTML
  S -->|zero-token compile| MD
  S -->|rollback| S

四、统一接口设计 / 4. Unified Interface Design

单一事实源与结构约束 / A single SSOT and its schema

SSOT 是一个 JSON 文档，顶层由若干「以 id 为键的集合」组成：实体、关系、时间线、证据、争点、观点、决定、来源、长篇章节等。集合用对象而不是数组，是为了让每个元素都有可寻址、永不变化的路径，例如 /sections/sec-09/title。
The SSOT is a JSON document whose top level consists of collections keyed by id: entities, relations, timeline, evidence, issues, opinions, decisions, sources, long-form sections and so on. Collections are objects rather than arrays so that every element has an addressable, never-changing path, for example /sections/sec-09/title.
整个文档受公开的 JSON Schema 约束。任何补丁在采纳前都要对「打完补丁后的文档」重新校验，不合法的修改根本进不了版本历史。
The whole document is constrained by a public JSON Schema. Before adoption every patch is re-validated against the patched document, so invalid changes never enter the version history.

内容协商与 URL 约定 / Content negotiation and URL conventions

统一接口的核心是「一个地址家族」。人和机器访问同一个 /c/<slug>/ 前缀，既可以用后缀显式选择形态，也可以用 HTTP Accept 头协商。响应带有 Vary: Accept，缓存不会把两种形态混在一起。
The heart of the unified interface is one family of addresses. Humans and machines use the same /c/<slug>/ prefix; they can choose a form explicitly by suffix or negotiate it with the HTTP Accept header. Responses carry Vary: Accept so caches never mix the forms.
GET /c/<slug>/                      → index.html   (Accept: text/html, default)
GET /c/<slug>/  Accept: text/markdown → index.md
GET /c/<slug>/  Accept: application/json → case.json
GET /c/<slug>/index.md              → Markdown twin
GET /c/<slug>/llms.txt              → AI index (llmstxt.org style)
GET /c/<slug>/case.json             → full SSOT + _meta {version, sha256, html, markdown, llms_txt}
GET /schema/case.json               → JSON Schema of the SSOT
POST /api/cases/<slug>/patches      → propose JSON Patch (agents)
POST /api/patches/<id>/adopt        → human adopt (gate)
GET  /api/cases/<slug>/diff?a=&b=   → version diff;  POST …/rollback → new version
case.json 的 _meta 字段写明版本号、编译时间、内容哈希以及其他孪生形态的地址，机器可以据此判断自己读到的是不是最新版本。
The _meta field of case.json states the version, compile time, a content hash and the addresses of the other twins, so a machine can tell whether what it read is current.

稳定 ID / Stable IDs

id 由小写字母、数字和连字符组成，一经创建不再改名。网页中的锚点（例如 #s-sec-09）、llms.txt 中的方括号引用、补丁路径和会议室里 AI 的引用，用的都是同一个 id。这让「人指着网页说的那一段」和「机器要修改的那一段」天然是同一个东西。
An id consists of lowercase letters, digits and hyphens and is never renamed once created. Anchors in the page (for example #s-sec-09), bracketed references in llms.txt, patch paths and AI citations in the meeting room all use the same id. As a result, "the paragraph a person points at on the page" and "the paragraph a machine wants to change" are naturally the same thing.

增量补丁（JSON 补丁） / Incremental JSON Patch

所有修改都表达为 RFC 6902 JSON Patch。补丁很小、可读、可机器校验，并且天然记录了「改了哪里」。AI 代理只被允许提议补丁，不能直接写 SSOT。
Every change is expressed as an RFC 6902 JSON Patch. Patches are small, readable and machine-checkable, and they naturally record what changed. AI agents may only propose patches; they cannot write to the SSOT directly.
[
  {"op": "replace", "path": "/sections/sec-09/title", "value": "统一接口设计"},
  {"op": "add",     "path": "/timeline/m-20261111",
   "value": {"date": "2026-11-11", "title": "白皮书 v1 发布"}}
]
补丁按风险分级（示意规则）：L1 为小的文本修改；L2 为新增或结构性修改；L3 为大批量修改、删除、涉及决定的修改或整块替换，必须显式确认。AI 补丁的操作数也有上限，防止一次性大改。
Patches are graded by risk (illustrative rules): L1 for small text edits; L2 for additions or structural edits; L3 for mass edits, deletions, changes touching decisions or wholesale replacement, which require explicit confirmation. AI patches also have an operation cap to prevent sweeping one-shot rewrites.

版本与回滚 / Versioning and rollback

每次采纳都会把完整文档保存为一个新版本，并记录对应的补丁、作者和说明。任意两个版本可以对比 diff；回滚不是删除历史，而是把旧版本内容作为一个新版本重新发布，因此历史永远是只增不减的。
Each adoption stores the full document as a new version, together with its patch, author and message. Any two versions can be diffed. A rollback does not delete history; it republishes an older version's content as a new version, so history only ever grows.

人类采纳闸门 / The human adoption gate

一元双生不追求「全自动」。AI 擅长提出候选修改，人负责判断事实、语气和后果。系统把判断成本降到最低：清楚的 diff、风险等级、触发了哪些警告，一键采纳或拒绝。可以按需为低风险的 L1 补丁开启自动采纳，但默认关闭。
One-Duality does not aim for full automation. AI is good at proposing candidate changes; people judge facts, tone and consequences. The system minimises the cost of that judgement: a clear diff, a risk level and the warnings triggered, with one-click adopt or reject. Auto-adoption can be enabled for low-risk L1 patches if desired, but it is off by default.

零 Token 编译 / Zero-token compilation

从 SSOT 到全部孪生形态的编译是纯 Python + 模板，不调用任何模型，因此不消耗 Token、可重复、可测试。双语内容同样遵循这一原则：作者亲自写好的中英对照放在 translation_memory 中，编译时直接配对使用；只有缺失的部分才会调用机器翻译，并按内容哈希缓存，下次零成本复用。本白皮书的中英文均为原生撰写并放入 translation_memory。
Compilation from the SSOT to every twin is pure Python plus templates and calls no model, so it spends no tokens and is repeatable and testable. Bilingual content follows the same principle: authored zh/en pairs live in translation_memory and are paired directly at compile time; only missing parts go to machine translation, cached by content hash for free reuse next time. Both the Chinese and English of this whitepaper were written natively and placed in translation_memory.

闸门示例：化名与币种 / Gate examples: pseudonyms and currency

• 化名闸门：真实姓名与化名的映射保存在私有表中，从不公开。每次发布前，编译器扫描所有输出（包括译文），若仍出现映射中的真实姓名，可按设置警告或直接阻止发布，公开页面保持上一个安全版本。
• Pseudonym gate: the mapping between real names and pseudonyms is kept in a private table and never published. Before each publish the compiler scans every output, translations included; if a mapped real name still appears it either warns or blocks publishing, depending on settings, and the public page stays at the last safe version.
• 币种闸门：正文中的每一处金额都被登记为一条记录（金额、币种、确定性、依据、位置）。只有「已确认」的金额才在公开页面上显示 ISO 代码，例如 $78,151.25CAD；推测和待定的金额进入审核队列，不公开猜测。标注在编译时渲染，原文数字一字不改。
• Currency gate: every amount in the text is registered as a record (amount, currency, certainty, basis, location). Only confirmed amounts show an ISO code on public pages, for example $78,151.25CAD; inferred and pending amounts go to a review queue and no guess is published. Labels are rendered at compile time and the original digits are never altered.
这两个闸门说明了一元双生的一个普遍做法：把「规则」放进编译管线，而不是指望每个作者和每个 AI 都记得。
These two gates illustrate a general One-Duality practice: put the rules into the compile pipeline instead of hoping every author and every AI remembers them.

五、与 os2ai.com 和 CaseForge 的关系 / 5. Relationship to os2ai.com and CaseForge

os2ai.com 多智能体编排 / os2ai.com multi-agent orchestration

os2ai.com 是一个多智能体编排系统：多个 AI 角色在「会议室」中围绕同一个案件讨论，每个角色读取的是 SSOT 的压缩上下文，产出的是 JSON Patch 提议，而不是直接改写网页。人类在指挥舱里审阅、采纳或拒绝。
os2ai.com is a multi-agent orchestration system: several AI roles discuss the same case in a "meeting room". Each role reads a compressed context of the SSOT and produces JSON Patch proposals rather than rewriting pages directly. A person reviews, adopts or rejects them in the cockpit.
一元双生为这种协作提供了共同语言：代理之间、代理与人之间，都通过稳定 id 和补丁沟通；所有人看到的都是同一个版本。
One-Duality gives this collaboration a shared language: agents talk to each other and to people through stable ids and patches, and everyone sees the same version.

CaseForge：一元双生的参考实现 / CaseForge: the reference implementation

CaseForge 就是一元双生理论的工程实现，即「一源双生 + 增量补丁」。它由 FastAPI 服务、SQLite 版本库、补丁引擎、零 Token 编译器和指挥舱组成，部署在 os2ai.com 上，由 Caddy 提供 HTTPS。
CaseForge is the engineering implementation of the One-Duality theory, i.e. "one source, twin outputs + incremental patches". It consists of a FastAPI service, a SQLite version store, a patch engine, a zero-token compiler and a cockpit, deployed on os2ai.com with HTTPS provided by Caddy.
• 每个案件都自动拥有四个孪生形态：index.html、index.md、llms.txt、case.json。
• Every case automatically has four twins: index.html, index.md, llms.txt and case.json.
• 同一个案件可以通过主机路由出现在独立域名的根路径上，内容仍来自同一个 SSOT。
• The same case can appear at the root of its own domain through host routing, still served from the same SSOT.
• 指挥舱提供补丁队列、时光机（版本对比与回滚）、元数据编辑、化名映射、金额审核和双语切换。
• The cockpit provides the patch queue, a time machine (version diff and rollback), metadata editing, pseudonym mapping, currency review and a bilingual toggle.

实例：抚养费执行案档案 LilyCase / Worked example: LilyCase

LilyCase 是一宗跨国子女抚养费执行案的客观档案，当事人以化名 Terry 和 Lily 出现。它展示了一元双生在真实材料上的完整流程。以下描述均来自该案的版本历史，不是虚构指标。
LilyCase is an objective record of a cross-border child-support enforcement matter; the parties appear under the pseudonyms Terry and Lily. It shows the full One-Duality workflow on real material. The descriptions below come from the case's version history and are not invented metrics.
• 导入：原有网站被逆向整理为 SSOT，每一步导入都是一个版本，正文保存在长篇章节中，原站的中英对照进入 translation_memory。
• Import: the original website was reverse-engineered into an SSOT; each import step became a version, the prose went into long-form sections and the site's existing zh/en pairs went into translation_memory.
• 化名：在私有映射表中配置真实姓名与化名，一键生成替换补丁并采纳；此后每次发布都由隐私闸门检查，公开输出中的真实姓名为 0。
• Pseudonyms: real names and pseudonyms were configured in the private mapping table, a replacement patch was generated in one click and adopted; from then on every publish is checked by the privacy gate, and public outputs contain zero real names.
• 币种：自动扫描登记全部金额，用户确认的金额以 ISO 代码显示（如台账一行：应付 $78,151.25CAD，已付 $0.00，欠款 $56,280.63USD），整个标注作为一个可审阅、可回滚的补丁进入版本历史；推测和待定项留在「💱 金额审核」队列。
• Currency: all amounts were scanned and registered automatically; user-confirmed amounts show ISO codes (for example the ledger line: due $78,151.25CAD, paid $0.00, arrears $56,280.63USD). The labelling entered the version history as one reviewable, reversible patch, while inferred and pending items stay in the "💱 currency review" queue.
• 域名：同一个 SSOT 同时出现在 os2ai.com/c/lilycase/ 和独立域名 ai2case.com 的根路径上。
• Domains: the same SSOT appears both at os2ai.com/c/lilycase/ and at the root of the dedicated domain ai2case.com.

本白皮书即自证 / This whitepaper eats its own cooking

本白皮书本身就是一个 CaseForge 文档（slug：one-duality）。你正在阅读的页面、它的 Markdown 版、llms.txt 和 case.json，都由同一个 SSOT 编译而来；它的每一次修改都以补丁形式进入版本历史，可在指挥舱的时光机中查看。
This whitepaper is itself a CaseForge document (slug: one-duality). The page you are reading, its Markdown version, llms.txt and case.json are all compiled from the same SSOT; every change to it enters the version history as a patch and can be inspected in the cockpit's time machine.
/c/one-duality/→index.html · index.md · llms.txt · case.json
本文的孪生形态（示意）

六、未来方向 / 6. Future Directions

MCP 与代理端点 / MCP and agent endpoints

把 SSOT 的读取、检索和补丁提议封装为 MCP（Model Context Protocol）工具，让任何支持 MCP 的代理都能以统一方式查阅和提议修改，同时保留人类采纳闸门。
Wrap SSOT reading, search and patch proposals as MCP (Model Context Protocol) tools, so any MCP-capable agent can consult and propose changes in a uniform way while the human adoption gate stays in place.

向量索引 / Vector index

以稳定 id 为单位建立向量索引，检索结果直接返回 id 和版本号，回答可以精确引用到段落，引用在版本变化后仍然可追溯。
Build a vector index at the granularity of stable ids, so search results return an id and a version number; answers can cite down to the paragraph, and citations stay traceable after the version changes.

签名溯源 / Signed provenance

对每个版本的内容哈希进行数字签名，并在 _meta 中公开签名与公钥指纹，使任何读者都能验证「这份 JSON 和这张网页确实来自同一个、未被篡改的版本」。
Digitally sign each version's content hash and publish the signature and key fingerprint in _meta, so any reader can verify that a given JSON and a given page really come from the same, untampered version.

多用户与权限 / Multiple users and permissions

从单一管理员扩展到多角色：提议者、审阅者、发布者分离，按集合或字段授予权限，每一次采纳都有明确的责任人。
Grow from a single administrator to multiple roles: proposer, reviewer and publisher are separated, permissions are granted per collection or field, and every adoption has a clearly accountable person.

联邦 / Federation

不同站点的 SSOT 通过稳定 id 和公开的 case.json 互相引用，形成可验证的知识网络；一个站点可以订阅另一个站点的补丁流，而不必复制整份内容。
SSOTs on different sites reference each other through stable ids and public case.json files, forming a verifiable knowledge network; one site can subscribe to another's patch stream without copying the whole content.

Mac 本地大模型 / Local LLMs on a Mac

在本地设备（例如 Apple Silicon Mac）上运行的开源模型负责会议室讨论和补丁起草，敏感材料不必离开本机；因为编译是零 Token 的，本地模型只需处理真正需要智能的部分。
Open models running on a local device (for example an Apple Silicon Mac) handle meeting-room discussion and patch drafting, so sensitive material never has to leave the machine; because compilation is zero-token, the local model only handles the parts that genuinely need intelligence.

路线图（示意） / Roadmap (illustrative)

以下顺序仅为示意，不代表承诺的时间表：
The order below is illustrative only and is not a committed schedule:
Markdown 孪生 + 内容协商 Markdown twin + negotiation→MCP 端点 MCP endpoints→向量索引 Vector index→签名溯源 Signed provenance→多用户 Multi-user→联邦 Federation
路线图（示意）Roadmap (illustrative)

七、结语 / 7. Conclusion

结语 / Closing

一元双生不是新的文件格式，而是一种纪律：只维护一份真相，让网页和数据都从它生长出来；让 AI 提议、让人决定；让每一次改变都可见、可比、可回退。人和机器因此终于在读同一本书。
One-Duality is not a new file format but a discipline: maintain one truth and let both pages and data grow from it; let AI propose and people decide; make every change visible, comparable and reversible. Humans and machines are then, at last, reading the same book.

里程碑 / Milestones

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

核心概念 / Core Concepts

单一事实源 SSOT / Single Source of Truth (SSOT)

文书 · 唯一可编辑的权威文档 / The only editable authority #ssot
受 JSON Schema 约束的 case.json，按版本保存。
case.json constrained by a JSON Schema, stored by version.

人类孪生 index.html / Human twin: index.html

文书 · 给人读 / For people #html-twin
排版、目录、关系图与双语对照。
Typography, table of contents, concept map and bilingual layout.

Markdown 孪生（正文版） / Markdown twin: index.md

文书 · 给模型读完整正文 / Full prose for models #md-twin
低噪声的完整正文，适合 LLM 直接阅读与引用。
Low-noise full text, ready for an LLM to read and cite.

机器孪生 case.json / Machine twin: case.json

文书 · 给程序读完整结构 / Full structure for programs #json-twin
完整 SSOT 加 _meta（版本、哈希、其他孪生的地址）。
The full SSOT plus _meta (version, hash, addresses of the other twins).

给人工智能的索引文件 / AI index: llms.txt

文书 · 给 AI 爬虫的目录 / A table of contents for AI crawlers #llms-twin

补丁引擎 / Patch engine

其他 · JSON Patch 提议、校验、分级 / Proposes, validates and grades JSON Patches #patch-engine

闸门 / Gates

其他 · 结构、风险、化名、币种 / Schema, risk, pseudonym, currency #gates

人类审阅者 / Human reviewer

人物 · 采纳或拒绝 / Adopts or rejects #human

AI 代理 / AI agents

其他 · 会议室中的多个角色 / Multiple roles in the meeting room #agents

零 Token 编译器 / Zero-token compiler

其他 · 确定性渲染全部孪生 / Deterministically renders every twin #compiler

概念关系图 / Concept Map

从 From关系 Relation到 To说明 Note
AI 代理 / AI agents提议补丁 / propose patches补丁引擎 / Patch engine
人类审阅者 / Human reviewer编辑 / edits补丁引擎 / Patch engine
补丁引擎 / Patch engine送检 / checked by闸门 / Gates
闸门 / Gates请求采纳 / asks to adopt人类审阅者 / Human reviewer
人类审阅者 / Human reviewer采纳 → 新版本 / adopt → new version单一事实源 SSOT / Single Source of Truth (SSOT)
单一事实源 SSOT / Single Source of Truth (SSOT)输入 / input零 Token 编译器 / Zero-token compiler
零 Token 编译器 / Zero-token compiler生成 / renders人类孪生 index.html / Human twin: index.html
零 Token 编译器 / Zero-token compiler生成 / rendersMarkdown 孪生（正文版） / Markdown twin: index.md
零 Token 编译器 / Zero-token compiler生成 / renders机器孪生 case.json / Machine twin: case.json
零 Token 编译器 / Zero-token compiler生成 / renders给人工智能的索引文件 / AI index: llms.txt
人类审阅者 / Human reviewer阅读 / reads人类孪生 index.html / Human twin: index.html
AI 代理 / AI agents读取 / readsMarkdown 孪生（正文版） / Markdown twin: index.md

开放问题 / Open Questions

内容协商与缓存 / Content negotiation and caching 进行中

同一地址按 Accept 返回不同形态时，需要确保所有中间缓存都尊重 Vary: Accept；否则应优先使用显式后缀。
When one address returns different forms by Accept, every intermediate cache must honour Vary: Accept; otherwise explicit suffixes should be preferred.

签名格式选择 / Choice of signature format 进行中

签名溯源可采用多种现成方案，需要在可验证性、工具成熟度和运维成本之间权衡。
Signed provenance can use several existing schemes; verifiability, tooling maturity and operational cost must be weighed.

补丁粒度 / Patch granularity 进行中

长篇章节以段落为单位还是以整节为单位打补丁，影响 diff 的可读性和翻译缓存的复用率。
Whether long-form sections are patched per paragraph or per section affects diff readability and translation-cache reuse.

来源 / Sources