World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
Decisions get a home in the repo, and revisions stay visible (#38)
WaylandYangf3e74f2bba64
diff --git a/.gitignore b/.gitignoreindex dd8d52c1..e0efb2b7 100644--- a/.gitignore+++ b/.gitignore@@ -6,5 +6,8 @@ web/dist/*.log.DS_Store/data-/docs+# docs/ 是本地草稿区;只有决策记录入库。+# 必须写成 /docs/* 而非 /docs——父目录被忽略时,子路径无法用 ! 重新纳入。+/docs/*+!/docs/decisions/.claude/diff --git a/docs/decisions/0001-ontology-import-and-governance.md b/docs/decisions/0001-ontology-import-and-governance.mdnew file mode 100644index 00000000..ad945a24--- /dev/null+++ b/docs/decisions/0001-ontology-import-and-governance.md@@ -0,0 +1,263 @@+# 0001 · 本体导入与治理路线++- **状态**:进行中 · P0–P5 均未开工+- **成文**:2026-08-27 / 28,随调研持续修订(约定见 [README](README.md))++> 理由比清单重要——清单会过期,理由决定以后遇到新情况怎么判。所以本文把「贯穿性判据」放在分阶段之前,且推翻过的判断就地留痕(见 P1、P3 的修订记录)。++## 为什么是这条线++产品的差异化是"时间"与"可信",而这两样的上游都是**本体**:抽取器按本体决定抽什么、归成什么类;时态引擎按本体的 `functional` 决定什么算矛盾;消解按类型决定谁能和谁是同一个。本体不对,下游全歪,而且歪得沉默。++企业已经有自己的本体(FIBO、行业标准、Protégé 自建),让他们在界面上一条条重建不现实。所以这条线的终点是:**把企业本体导进来,让抽取按他们的词汇工作,并且治理过程本身能沉淀。**++---++## 已验证的事实(2026-08-28,真实语料测得)++用公开企业新闻稿建了 `Industry Corpus` 库(NVIDIA 博客 18 篇 + 微软新闻室 10 篇,RSS 摄入):++| 指标 | 数值 |+|---|---|+| 文档 / 分块 | 28 / 181 |+| 实体 / 事实 | 917 / 922 |+| **实体密度** | **5.07 个 / 分块** |+| 消解:自动合并 / 待人工 | 10 对 / 5 对 |+| 攒批裁决任务数 | 22(处理 917 实体的消解对) |+| 图谱总览查询 | 103 ms |+| as-of 查询 | 107 ms |+| 实体变更历史(NVIDIA 122 事件) | 16 ms |+| 当前 9 类本体在提示词中的体积 | 466 字符 |++**跨文档消解成立**:NVIDIA 聚合了 16 篇文档的 118 条事实,没有裂成同名副本。++**已修的三个缺陷**(分支见文末):++1. HTTP 客户端不发 User-Agent → 维基百科等站点 403,URL/RSS 对一大片真实网站直接失效+2. HTML 提取全文档遍历 → 一篇维基条目 60 个分块,首块整块是侧栏菜单、末块是版权声明+3. `part_of` 被标成 `functional` → 28 篇新闻稿积压 59 条假冲突("属于 Microsoft Learn"与"属于 Microsoft"并存不是矛盾)++**未解决的质量问题**:Product 类占 40%(368 个),抽样约四分之一是泛化短语("row power center"、"financial databases")。补救手段是给类写描述(description 进抽取提示词),但**目前只能整库重抽**,因为实体不可单独编辑——见 P0。++---++## 贯穿性判据++以后遇到新构造、新特性,用这几条判,不要重新辩论:++1. **不是"OWL 有没有",是"我们有没有机器消费它"**——但要加时间维度:**丢弃不可逆,保存近乎免费**。所以原文一律保真,投影只覆盖当下用得上的。推论:**保留了原文,投影就不必语义完整**——简化是 UI/提示词层的取舍,不是数据损失。+2. **本体是引导,不是执法**。声明可能是错的(`part_of` 就是),所以本体应当影响提示词与候选排序,而不是驱动丢弃、覆盖、自动改写。错误的引导模型能靠原文覆盖;错误的执法会系统性地毁数据。+3. **提示词大小必须与本体规模脱钩**。把 N 个类塞进每个分块的提示词,成本是 O(分块 × 本体),而且模型从 800 个选项里挑反而更差。规模问题用检索解,不用"少列几个"解。+4. **同名不能传递任何结论**。判定为同一实体 → 本来就一个类型,无所谓传递;判定为不同 → 名字正是我们刻意不信任的信号(两个张伟)。能携带信息的是上下文。+5. **不确定性浮到人面前**,不要悄悄猜。分层阈值 + 灰区进 Review,与消解的"宁分勿合"同源。+6. **治理经验固化进 schema,不要固化成隐形规则**。改一次类描述是可见、可评审、进审计台账的;从点击里长出来的自动规则半年后没人知道为什么。+7. **唯一 ≠ 身份**。`key` 有 `UNIQUE (kb_id, key)`,但它派生自会变的东西(label / 局部名),而身份要求跨时间稳定。只要两个不同的全局事物可能想要同一个 key,key 就必须附带"来自何处"才能当标识符——那就是 IRI。另:**IRI 是名字不是地址**,绝大多数不可访问,不要去抓取,也不要把 http/https、末尾斜杠"规范化"成同一个。++---++## 分阶段++### P0 · 实体可编辑 —— 地基,且现在就在流血++**问题**:实体是只读的。`/kbs/{id}/entities/{entity_id}` 只有 GET,store 层唯一的 `UPDATE entities SET type_id` 在 `resolution.rs:388`(合并时自动升格),前端面板没有任何编辑入口。类型判错、名字抽歪,只能整库重抽这把大锤。++**做**+- `PATCH /kbs/{id}/entities/{entity_id}`,Editor 权限,可改 `type_id` / `canonical_name`+- 落审计台账:`entity.retyped` / `entity.renamed`,detail 带前后值快照(沿用决策台账的自包含快照约定)+- 前端:实体面板头部加编辑入口++> **修订记录**:初稿写「`entities` 上有唯一索引,改名会撞 409」。**两处都错**——`entities_kb_type_name_idx` 是**普通索引不是唯一索引**,而且同类同名的重复**现在就存在**(`General` 库「张伟」×2、「rust compiler」×2)。更要紧的是:不该加那个约束。++**碰撞是提示,不是拒绝**:「张伟」×2 正是"宁分勿合"的设计产物——两个不同的人可以同名同类,消解的整个灰区逻辑依赖于能把他们分开存放。所以改名/改类型撞上同名时:**查出来、提示"已有同名实体,是否合并?"、但允许继续**。加唯一约束会砸掉消解的地基,报 409 会让用户无法录入第二个张伟。++**动机数据**:`General` 库里跨类型同名的——"rust" **5 个**、"java" 3 个、"c++" 3 个。同一个东西被分进五个类,今天无法收拾。++**验收**:能把 "row power center" 从 Product 改成 Concept,改动出现在审计台账,图谱与本体页的计数同步。++---++### P1 · 停止静默丢弃 —— 小,但现在就在流血++> **修订记录**:这一格原本是"关系的 range 校验",理由是"对现有语料立刻生效"。**那句是错的**——查证后:23 个关系里只有 2 个有 domain(就是那两个属性),**range 一条都没有**,因为 UI 里没有这一项、没有任何东西会写它。range 数据只可能来自 OWL 导入,所以它不可能独立于 P2 生效。range 的正确位置见 P2(导入并保存)与 P3(作为信号之一消费)。++**真正现在就在流血的**:抽取器把事实**静默丢弃**——抽出来了、被挡掉、不留任何痕迹,用户看不见,只是图里少了东西。与"账本 append-only、每条事实都有证据、不确定性浮到人面前"三条原则直接冲突。++**范围比最初判断的大**(2026-08-28 逐行核过 `extraction.rs`)。属性路径不是一个 `continue`,是四个真丢弃:++| 行 | 条件 | 性质 |+|---|---|---|+| 255 | 主语未在 `entities` 中声明 | 真丢弃 |+| 257 | `domain_type_id` 为 NULL | **不可达**——`ontology.rs:197` 强制 attribute 必有 domain,`update_relation_type` 又不许改 kind/domain(`ontology.rs:290`)。且无 domain 的属性连提示词都进不去(`extraction.rs:122` 的 `r.domain_type_id?`)。防御性代码,不需要信号 |+| 261 | domain 不匹配 | 真丢弃(最初只点了这一条) |+| 269 | 既无 `value` 也无 `object` | 真丢弃 |+| 274 | datatype 归一化失败 | 有 `debug!` 日志,但用户不可见 |++关系路径另有两条值得记:`confidence < 0.6`(第 234 行,设计阈值,但同样不可见——用户无从知道"抽到了但不够自信")与 `related_to` 不在本体时**整条事实消失**(第 380 行,删掉默认关系就会踩到)。++**顺带发现一个不一致**:关系路径上主宾未声明时会**兜底按 `concept` 消解**(332-362 行),属性路径上同样的缺失却直接丢(255 行)。同一个原因,一边宽容一边静默丢弃。要么两边都兜底,要么两边都记信号——不能一边一个样。++**做**+- 新表 `extraction_drops (kb_id, document_id, reason, detail, count, example, updated_at)`,PK `(kb_id, document_id, reason, detail)`,抽取开始时按 document 清空+- 不复用 `ontology_misses`:那张表语义是"你的本体缺这些"(面向本体演进),丢弃是"这些事实没落地"(面向数据完整性),两者的读者和动作都不同+- 按 document 归集顺带修好生命周期:`ontology_misses` 只在整库 rebuild 时清(`graph.rs:689`),来源级重抽不清,会攒陈旧条目。新表按 document 清则天然正确++**验收**:故意给 Person 专属属性喂一个 Organization 主语,Library 的文档行能看到"3 条事实未落地",点开有原因与样例,事实不再无声消失。++---++### P2 · OWL 导入++**架构分三层,关键在第一层**++1. **原文保真**:导入的本体文件原样进 blob store(内容寻址那套摄入管道在用),`ontology_imports` 记录 (kb_id, blob sha, 文件名, 时间, 投影版本)。这一步不理解语义,只负责不丢。+2. **投影**:把今天能消费的子集映射进 `entity_types` / `relation_types`。**是可重跑的推导,不是一次性转换。**+3. **重投影**:推理机上线或我们补上新校验时重跑,用户什么都不用做。++这样"我们表达不了"从**能力缺口**降级成**投影暂未覆盖**。++**映射表**++| OWL / RDFS | Utopia | 备注 |+|---|---|---|+| `owl:Class` | entity_type | |+| `rdfs:subClassOf` | **多父**(见下) | |+| `rdfs:label` | `label` | 优先 `@en`/`@zh` |+| **`rdfs:comment`** | **`description`** | 承重:进抽取提示词,也是 P3 检索的匹配依据 |+| `owl:ObjectProperty` | relation_type (`kind=relation`) | |+| `owl:DatatypeProperty` | relation_type (`kind=attribute`) | |+| `rdfs:domain` | `relation_type_domains`(多值关联表) | 见下"多值域" |+| `rdfs:range` | `relation_type_ranges`(多值关联表)/ `datatype` | 同上;**只存不强制**,消费者是 P3/P5 |+| `owl:FunctionalProperty` | `functional` | max-cardinality-1,时态引擎的命根子 |+| `owl:InverseFunctionalProperty` | `inverse_functional` | |+| IRI | 新增 `iri` 列 | 见下"IRI 与 key 的分工" |+| 其余公理 | **保留在原文,报告为"暂未投影"** | 不是"已跳过" |++**IRI 与 key 的分工**:`key` 有硬约束——只允许 `[a-z0-9_]`、最长 40 字符(`ontology.rs:77`),而且它是**给模型读写的令牌**:提示词列的是 key,模型返回的 `type` 是 key,`type_ids` 按 key 查。IRI 塞不进去(冒号斜杠井号全非法),放宽约束的话提示词变成 800 行 URL,还要模型逐字复现——截断或幻觉一个字符就匹配失败。++所以:**IRI 是全局身份(权威),key 是模型标签**。key 从 IRI 派生(命名空间前缀 + 局部名,snake_case,冲突加后缀),短而稳定。存储:一个可空 TEXT 列 + `UNIQUE (kb_id, iri) WHERE iri IS NOT NULL`;手工建的类为 NULL,无负担。++**为什么 key 唯一了还要它**——重导入是本体功能上线就会撞到的第一件事:++```+v1: http://acme.com/hr#Employee rdfs:label "Employee" → key = employee+v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_member ← 同一个类+```++没有 IRI 只能二选一,都错:建新类 `staff_member` 把 `employee` 变孤儿(实体全挂在上面),或按 label 匹配(label 正是刚变的那个)。有 IRI 就是一次 `WHERE iri = $1`,改名字,实体不动。++想「那 key 就从局部名派生」也撑不住:`foaf:Person` 与 `acme:Person` 都要 `person`,谁拿 `_2` 后缀取决于导入顺序,下次重导入分不出 `person_2` 是谁的——除非记下它来自哪个 IRI,那就是 IRI 列绕一圈重新发明。另两个用途:**溯源**(上游类被手改后重导入要调和,得先知道它是上游的)与 **P5 导出**(key 反推不出命名空间,有损)。++**多值域(domain / range)**:OWL 里并集是常态(`works_at` 的值域可能是 `Organization ∪ Project`),单列表达不了,用关联表存,判定走子类 DAG。++导入的语义陷阱:RDFS 中同一属性的**多条 `rdfs:range` 是交集**("必须同时是两者"),不是并集——极常见的建模错误,但规范如此。`owl:unionOf` → 直接进表;多条独立 `rdfs:range` → 一者是另一者的子类则取更具体的,互不包含则**报告"暂未投影",不猜**。++**domain/range 的正确用法是提示词里的类型签名,不是闸门**++关系在提示词里从 `- works_at (works at): 描述` 变成 `- works_at (works at): Person → Organization。描述`。这是**给模型的类型签名**,在源头减少 "Alice works_at 西雅图" 这类三元组,而不是等错了再修——事后校验面对的是既成事实(丢掉可惜、留着是脏数据),签名是在生成那一刻掰正。++**是引导不是强制**:本体写错时模型看到原文说了别的仍可覆盖;强制闸门则会系统性丢数据(`part_of` 烧我们的正是这种方式)。++大本体下(P3 规模)它换位置继续有用:预测谓词时,**domain/range 与实际主宾类型匹配的候选关系排名更高**,作为检索排序信号。++三件事的必要性不同:**存**(是,P5 的正经输入,成本在解析器里本来就要写)、**进提示词当签名**(是,最高性价比,约十行)、**校验/自动升格/违规队列**(否,P3 用更丰富的证据做同一件事,且用可能错的声明驱动自动动作风险高)。++**交集不实现,理由是架构性的**:**因为保留了原文,投影就不必语义完整**。投影只服务提示词与界面展示,两者都接受简化;需要完整语义的是推理机,而它读的是 blob 里的原文。实现交集意味着要表达"既是 A 又是 B"的匿名类——往描述逻辑走的第一步,会把 schema 拖进类表达式的泥潭,而收益只是提示词多一行字。++**多继承要真支持**:`type_matches_domain`(`extraction.rs:137`)沿单父链上溯。丢掉一个父分支,那分支上的属性会**静默失配**——抽出来了、写入时被挡、不报错。补法:`entity_type_parents` 关联表存全部父类,domain/range 判定走 DAG(访问集防环),左栏仍按主父展示成树,避免同一个类出现多次。++**两个必须在预览里说清的**+- **哪些关系会因 `functional` 而开启冲突检测**——这正是 `part_of` 那个坑,企业本体声明为函数性但数据不遵守,导完就是一队假冲突+- **有多少类没有 `rdfs:comment`**——它们在 P3 的自动分类里质量会明显偏低++**流程**:上传 → **dry-run 预览**(新建/更新/暂未投影各多少、上述两项警告)→ 确认才落库。绝不让上传一个文件就不可逆地改掉本体。++**v1 砍掉**:OWL/XML 与 Manchester 语法(Turtle + RDF/XML 覆盖 Protégé 导出的绝大多数)、任何推理、个体导入、反向导出。++**个体(ABox)永不作为事实导入**——不是能力问题,是原则:每条事实必须有证据链和出处,凭空塞进来的实例破坏的正是这个地基。它们随原文件保存,将来推理机可当背景知识读。++**依赖**:`oxttl` + `oxrdfxml`(Oxigraph 那套小而专的 crate)。不引 `horned-owl`,我们不需要推理。工作区目前无任何 RDF 依赖。++---++### P3 · 类型消解 —— 让大本体可用++**问题**:今天类型由 LLM 在抽取时从**内联清单**里挑。9 个类很好;800 个类时提示词爆炸且准确率下降。++**分三层,第一层最要紧**++1. **抽取只给粗类型**——提示词永远只列基础类(person/organization/product/place/event/concept)。**提示词大小从此与本体规模无关。**+2. **类型消解(新后台任务)**——类的 `label + description` 嵌入成向量(一次性);实体积累名字和事实后,用**合成文本**(名字 + 参与的谓词 + 粗类)嵌入检索 top-k 候选类,只把这 k 个交给 LLM 裁决。高置信自动升格,灰区进 Review,结果缓存。+3. **推理推出的类型**——有 `equivalentClass` 定义的类无需模型判断(等 P5)。++#### P3b · 关系清单同样会膨胀(原先漏掉的)++上面只解决了实体类型。但提示词里紧挨着类清单的是**关系清单**,同样由本体全量展开、同样每个分块重发。实测(Industry Corpus):9 个类 197 字符,10 个关系 **250 字符**——关系已经是更大的那一半。且**代码库无任何 prompt caching**(`cache_control` 零命中),O(分块 × 本体) 没有缓存兜底。部门级本体(300 类 / 400 属性)约每分块 4200 token,181 分块 76 万输入 token——而这才 28 篇文档。++**当初漏掉的原因是一个不对称**:`(NVIDIA, acquired, Mellanox)` 不知道 NVIDIA 是 Organization 也是完整事实——**类型是挂在节点上的注解,可延后**;而 `(NVIDIA, ?, Mellanox)` 不是事实,**谓词就是事实本身**,"先空着后补"不通。++**出路是换中间态**:延后到**表层谓词**而非延后到空——`(NVIDIA, "acquired", Mellanox)`,自由文本,可存,模型无需词表即可产出。第二遍带着完整句子和检索候选映射到本体关系,与类型消解同一套机器。domain/range 在这里作排序信号(主宾类型匹配的候选排名更高)。++**流水线已跑了三分之二**:`ontology_misses` 有活数据(`available_from ×9`、`scales_to ×5`、`runs_on ×4`、`collaborated_with ×4`),`extraction.rs:366-383` 已在接受词表外谓词并记录表层形式,缺的只有映射那一步。今天它只是给人看的报表,不是消解器的输入。++**前置缺陷(需先修)**:降级有损——`f.predicate` 只进了 `record_miss` 的聚合,**事实上一字未留**,今天无法回答"哪些事实从 `available_from` 降级而来"。同"原文保真"原则:**先别扔,扔了不可逆**。++> **修订记录**:初判是加 `facts.surface_predicate`。**错了**——查 `graph.rs:164-175` 后发现事实是去重的,该列会先写者胜。正确位置是 `fact_evidence`。++**放在 `fact_evidence` 上,不是 `facts` 上**:`insert_fact_inner`(`graph.rs:164-175`)按 `(kb_id, subject_id, predicate_id, object_id)` 对存活事实去重,所以一条 `(A, related_to, B)` 会吸收多个分块——甲块说 "runs on"、乙块说 "optimized for",合并成同一行。放 `facts` 上就是**先写者胜、其余静默丢弃**,正是本条要修的毛病。`fact_evidence` 每分块一行、已带 `quote`(该块的原文佐证),表层谓词是同一种东西:每次观察的原始形态。粒度对,且无需新增语义。++加 `fact_evidence.surface_predicate TEXT`,两条路径都写(关系路径写降级前的 `f.predicate`;正常命中时写模型实际给的那个词,因为它可能是别名)。不等映射落地就有独立价值——Review 与实体面板可直接展示"原文说的是 available from,被降级成 related to",而今天前端对 `related_to` 无任何特殊处理(`web/src/` 里零命中),降级对用户完全不可见。++**映射不取代 miss 报表**:反复出现又映射不上的(`available_from ×9`)正是"本体该加这个关系"的治理信号(P4 燃料)。映射只吃高置信的那部分,其余留在 miss 里变建议。++**不要用 `profile_embedding` 做检索**:它是实体所在分块的质心,代表"出现在什么样的文档里"而非"是什么"。人物出现在 GPU 发布稿里,质心也是 GPU 味的。必须用合成文本重新嵌入。++**成本(按实测数据推算)**+- 对现有小本体部署:**0**——类数低于阈值(约 30)时不启用,粗类即细类+- 对比"天真导入 500 类":**大幅省**。500 类塞进提示词约 8,000 tokens × 181 分块 = 140 万额外输入 tokens;检索方案把提示词按回 466 字符+- 净增:**调用次数 +15~20%,tokens 约 +5%**——类型消解调用不含分块正文,比抽取调用小一个数量级;攒批(现有裁决任务已做到约 40:1)+ 分层阈值让多数实体不进 LLM+- 新增:917 个短文本嵌入,量级相当于再嵌一百来个分块++**真正的风险不是成本是质量**:大本体下错判会把噪声规模化。缓解仍是判据 4——只有相似度高且与次优拉开差距的才自动升格,灰区进 Review。++**第一次抽取一定有类型**:`entities.type_id NOT NULL`,没有"未分类"状态。粗类是真类型不是占位符,小本体下它就是最终类型。升格挂在文档抽取完成的同一条任务链上(与攒批裁决并列),窗口是秒级。++---++### P4 · 治理即经验++**顺序不能反**:先有 P0 的编辑能力,才有"人工决策"可保护、可学习。++1. **决策不可被遗忘(正确性,不是功能)**——`entities` 加 `type_source`(extracted / human / inferred)。抽取不覆盖 `human`;推理机也不覆盖。没有这一层,重抽会静默吃掉全部治理成果。+2. **决策记忆做检索**——`resolution_verdicts` 已经是这个模式的一半,但按 `pair_key` 精确匹配、不泛化。类型决策要走一步:存下人工改类时的检索向量与结果,下次分类时**检索最相近的历史决策当证据**交给裁决器。按语境相似度泛化,不按名字相等(判据 3)。+3. **纠正聚合成本体信号(收益最高)**——一个月里 37 个实体从 Product 挪到 Concept,该修的不是那 37 条,是 Product 的描述太松。Ontology 页加信号面板:"Product → Concept 迁移 37 次(近 30 天)",点开看样例,旁边"用 AI 起草更严格的描述"——与现有 misses 面板的 Suggest with AI 完全同构。++---++### P5 · 推理机(远期)++`utopia-reason` 目前是 3 行空壳。它上线后能消费的,正是 P2 保留而未投影的那些公理:++- `TransitiveProperty` → "NVIDIA 名下所有东西"(现在只能靠 hops 逐跳猜)+- 非 1 的基数被违反 → **一致性告警进 Review 队列**,本体成为数据质量规则+- `someValuesFrom` / 类表达式 → 自动归类,实体无需显式标注类型+- `equivalentClass` / `inverseOf` / 属性链 → 常规推理输入+- `disjointWith` → 剪掉可证伪的跨类型合并候选(`resolution.rs:103` 的"类型漂移"逻辑会跨类型召回,这里能拦下不可能的组合)++**这些今天全部读不了,但 P2 的原文保真保证了届时无需用户重新上传。**++---++## 开放问题++- **升格准确率给不出数**——需要真实企业本体做小样本评测,现在只有推演+- **`active` 标记的定位**:原本当规模解药(错,规模应由 P3 的检索解),现在只剩治理用途(弃用的旧类不参与分配)。是否值得单独做,等有真实大本体再定+- **阈值 30 是拍的**——类数超过多少才启用类型消解,需要实测校准+- **`disjointWith` 与 `SymmetricProperty` 收益中等**:前者剪枝防错误合并;后者去重(新语料里测得 8 对互为反向的重复事实,占 910 条的 1%)。排在 P2 之后按需++---++## 基准语料++`Industry Corpus` 库保留着(NVIDIA 博客 18 篇 + 微软新闻室 10 篇,RSS 摄入),是上面所有数字的来源,也是后续所有评测的基线——改动前后跑同一个库,数字才可比。别在它上面做破坏性实验。++分支状态不记在这里:git 自己知道,写进文档只会过期。diff --git a/docs/decisions/README.md b/docs/decisions/README.mdnew file mode 100644index 00000000..eece36ad--- /dev/null+++ b/docs/decisions/README.md@@ -0,0 +1,29 @@+# 决策记录++代码记录了**做成什么样**,git 记录了**什么时候改的**。两者都不记录**为什么这样而不是那样**,以及**哪些路走过发现是死路**。这个目录记那个。++判断标准:如果半年后有人(包括我们自己)看着某段代码问"当初为什么不直接……",而答案不在代码里,那就该有一篇。++## 约定++**文件名** `NNNN-短横线英文标题.md`,四位序号,按创建顺序递增,不留空号。序号只是稳定的引用锚点,不表示优先级。++**目录扁平**。在出现第二种性质不同的文档之前,不建子目录。++**修订就地留痕,不静默改写**。结论变了——尤其是因为查证推翻了原判断——**在原处保留「修订记录」块**写清:原本是什么、为什么错、依据什么改的。不要把错误的那版删干净。++> 这条不是文档洁癖,是同一条产品原则。我们的账本从不原地 UPDATE 事实,纠正是插入新行 + `supersedes` 旧行,因为**认知变更本身是信息**。决策记录同理:知道"我们曾经以为 range 能立刻生效,查完发现一条都没有",比只看到最终结论有用得多——它告诉你下次该先查什么。++**结论变得太多时**,另起一篇并在旧篇顶部标 `已被 NNNN 取代`,而不是把旧篇改成新的。++**语言**:中文,与代码注释一致(UI 与 README 保持英文)。目前的读者是维护者,不是外部贡献者;将来需要时再译。++## 索引++| | 文档 | 状态 |+|---|---|---|+| 0001 | [本体导入与治理路线](0001-ontology-import-and-governance.md) | 进行中 · P0–P5 未开工 |++## 不放这里的东西++`docs/` 根目录是**本地草稿区**(`.gitignore` 里 `/docs/*` 忽略,只对 `/docs/decisions/` 开口)。随手的调研笔记、临时清单、跑测试的中间产物放那儿,不入库。等某份草稿沉淀出了值得留的判断,再作为一篇决策记录搬进来。