# Ontology 工作宪法

> 本体论实验的七条不可违反原则。每次修改 ontology 相关代码前必须对照检查。

## 宪法七条

### 最高条：项目隔离（优先级最高，不可覆盖）

> **Ontology 是 openclaw-model-bridge 的独立子项目。Ontology 的任何操作都不得对原项目产生任何影响。**

这是所有其他条款的前提。违反此条 = 违反全部宪法。

**具体要求**：

1. **目录隔离**：所有 ontology 文件集中在 `ontology/` 目录下（代码、测试、数据、文档），不在项目根目录散落任何文件。后续成熟后可直接 `git subtree split` 拆为独立仓库
2. **代码隔离**：`ontology/engine.py`、`ontology/diff.py`、`ontology/tests/test_engine.py`、`ontology/tool_ontology.yaml` 是**只读观察者**，不得修改原项目的运行时行为
3. **导入方向单向**：ontology 代码可以 `import proxy_filters`（读取硬编码数据做对比），但 proxy_filters / tool_proxy / adapter **永远不得 import ontology 模块**（当前 proxy_filters.py 启动时的一致性检查是唯一例外，使用 `importlib.util` 动态加载且 try/except 包裹，`ontology/` 不存在时静默跳过）
4. **删除安全**：`rm -rf ontology/` 后原项目必须正常运行，所有原有测试必须通过
5. **文档隔离**：ontology 文档全部在 `ontology/docs/` 下，不修改 `docs/config.md`、`README.md` 等原项目文档
6. **测试隔离**：ontology 测试在 `ontology/tests/` 下，不修改 `test_tool_proxy.py` 等原有测试；`full_regression.sh` 可选择性包含 ontology 测试，但 ontology 测试失败**不得阻断**原项目的回归

**检查方法**：
```bash
# 模拟删除 ontology 后原项目是否正常
python3 -c "
import proxy_filters
print('ALLOWED_TOOLS:', len(proxy_filters.ALLOWED_TOOLS))
print('CLEAN_SCHEMAS:', len(proxy_filters.CLEAN_SCHEMAS))
print('proxy_filters OK: independent of ontology')
"
python3 -m unittest test_tool_proxy  # 必须不依赖 ontology 就能通过
```

### 第零条：术语纪律（2026-04-06 新增，来自外部专家评审）

> **"Ontology"在本项目中不是一个词，而是四个层次。混用即失控。**

- Layer 1: Concept Ontology（概念本体）— 实体-关系-属性的形式定义
- Layer 2: Constraint & Policy（约束与策略）— 部分可用 OWL，部分需要规则引擎
- Layer 3: Execution Semantics（执行语义）— ontology-aware runtime，不是 ontology 本身
- Layer 4: Evidence & Audit（证据与审计）— 决策追溯，独立支柱

任何文档、代码注释、PR 描述中出现"ontology"时，必须明确指的是哪一层。

**核心命题**：Ontology is not the whole solution; it is the semantic control plane of enterprise AI.

**检查方法**：review 时搜索"ontology"/"本体"，确认每处使用都能对应到 L1-L4 之一。详见 `ontology_scope.md`。

### 第一条：非破坏性引入

> **现有系统必须继续用原有方式运行，本体层并行存在。**

- 新增本体文件（YAML/引擎/测试）不修改现有运行逻辑
- proxy_filters.py 保留全部硬编码规则，ontology_engine 不替代、只验证
- 切换到本体驱动需要经过：并行运行 → 差异对比 → 逐项替换 → 全量回归
- **禁止**：一次性将硬编码规则删除换成本体加载

**检查方法**：`python3 -m unittest test_tool_proxy` 必须不依赖 ontology_engine 就能通过。

### 第二条：一致性安全网

> **本体声明必须与硬编码规则 100% 一致，任何偏差立即可见。**

- `python3 ontology/engine.py --check` 必须返回 `✅ consistent`
- 每次修改 proxy_filters.py 或 ontology/tool_ontology.yaml，必须同步修改对方
- CI/preflight 包含一致性检查，不一致则阻断
- 修改任一侧后立即运行 `python3 ontology/engine.py --check`

**检查方法**：`python3 ontology/engine.py --check` 退出码为 0。

### 第三条：每条规则有 rationale

> **不只记录"是什么"，还必须记录"为什么"。这是本体论与配置文件的核心区别。**

- tool_ontology.yaml 中每条 policy rule 必须有 `rationale` 字段
- rationale 说明：为什么需要这条规则 + 什么证据/教训驱动了它
- 空 rationale 或 "TODO" 不允许合入
- 测试强制：`test_policy_has_rationale` 扫描全部规则

**检查方法**：`python3 -m unittest ontology.tests.test_engine.TestPolicies.test_policy_has_rationale`

### 第四条：强制差异对比表格

> **每次变更必须生成两种范式（硬编码 vs 本体）的全量差异对比表格。**

- `python3 ontology/diff.py` 生成 Markdown 表格，逐项对比
- 对比维度：工具白名单、Schema、参数集、别名、策略规则、浏览器约束
- 每个维度标注状态：✅ 一致 / ⚠️ 偏差 / ❌ 缺失
- 表格输出到终端 + 可选保存到 `ontology/docs/ontology_diff_report.md`
- **变更 PR 描述中必须附带 diff 表格截图或内容**

**检查方法**：`python3 ontology/diff.py` 输出全绿。

### 第五条：每次变更必须输出优势分析表格（无例外）

> **当前处于项目开发前期。每一次变更都必须输出表格，详细列举并分析本体论 vs 硬编码/配置文件的差异及优势。没有例外。项目可以慢一点，但不能跳跃任何模糊的难点。**

这条宪法的存在理由：本体论的价值不是"我们说它好"，而是**每一步都能用对比证据说明好在哪里**。如果某次变更无法清晰说明比硬编码优在何处，说明这次变更要么不该做，要么还没想清楚。

**具体要求**：

1. **每次 commit 前**必须输出一张对比表格（在对话中展示给用户），至少包含：

   | 维度 | 硬编码/配置文件方式 | 本体论方式 | 优势分析 |
   |------|-------------------|-----------|---------|
   | （变更涉及的每个具体点） | （现有方式怎么做） | （本体方式怎么做） | （好在哪里，量化证据） |

2. **表格必须具体**，禁止出现以下模糊表述：
   - ❌ "更灵活" → 必须说明哪种场景下灵活在哪里
   - ❌ "更好维护" → 必须量化：改 N 处 vs 改 1 处
   - ❌ "更可扩展" → 必须给出新增工具/规则时的具体操作步骤对比

3. **如果某个变更点无法说清优势**，必须在表格中标注 `⚠️ 待验证` 并暂不实现，而不是模糊跳过

4. **模糊难点必须显式记录**：如果在实现中遇到"硬编码其实也能做"或"本体方式反而更复杂"的情况，必须诚实记录在表格中，标注为 `⚠️ 本体无明显优势` 或 `❌ 本体更复杂`。这不是失败，而是精确划定本体的价值边界

**检查方法**：每次 PR / commit message 中必须包含对比分析表格的引用或摘要。reviewer（用户）确认表格覆盖了所有变更点。

**为什么这条宪法重要**：

```
没有这条宪法：
  → 开发者凭直觉推进 → 某些功能做完才发现"其实配置文件也行"
  → 优势模糊 → 无法对外解释 → 项目失去说服力

有这条宪法：
  → 每一步都有对比证据 → 优势清晰可量化 → 劣势也被诚实标记
  → 积累 20 次变更后 → 自动形成一份"本体论价值白皮书"
  → 这份白皮书就是项目对外的核心说服力
```

### 第六条：双范式互验证（2026-04-07 新增，来自治理本体实践）

> **硬编码和本体论是两个独立的系统范式。两者必须互相验证，任何分歧即为告警。硬编码是老师，本体是学生——学生通过从老师那里学习"什么该检查"，逐渐成长为能独立发现问题的治理体系。**

这条宪法的存在理由：2026-04-07 对抗审计发现 22 个声明-实际断裂，全部是"硬编码说的"和"本体声明的"对不上。两个范式的分歧不是问题，**没有人比对分歧才是问题**。

**架构原则**：

```
硬编码系统（成熟、久经生产验证）
  ├── proxy_filters.py    → 工具过滤、参数修复、请求截断
  ├── kb_status_refresh.sh → 健康状态刷新
  ├── auto_deploy.sh      → 文件同步、漂移检测
  └── 610 个测试          → 组件行为验证

本体系统（新兴、声明式、可推理）
  ├── tool_ontology.yaml       → 81 条工具规则声明
  ├── governance_ontology.yaml → 12 不变式 + 5 元规则
  ├── governance_checker.py    → 可执行验证引擎
  └── Phase 0 元规则发现        → 自主发现未覆盖的声明

双向验证：
  本体 → 验证硬编码：governance_checker 执行不变式检查代码行为
  硬编码 → 验证本体：diff.py 比对硬编码实际值与本体声明值
  任何分歧 → 告警，不是沉默
```

**演进路径**：

```
阶段 1（当前）：硬编码是老师
  本体从硬编码中学习"什么是正确的"
  每次发现 bug → 新增一个不变式 → 本体覆盖度 +1

阶段 2（未来）：双方平等
  本体积累足够不变式 → 能独立发现硬编码中的新问题
  Phase 0 元规则已证明这一点（自主发现 23 个未覆盖 job）

阶段 3（远期）：本体成为安全网
  硬编码变更时，本体自动验证是否违反已知不变式
  新增声明时，元规则自动要求补全执行和验证
  本体不替代硬编码，而是驱动硬编码的演进方向
```

**禁止事项**：
- ❌ 不得因为"本体已声明"就删除硬编码实现（宪法第一条仍然优先）
- ❌ 不得因为"硬编码已验证"就跳过本体声明（双通道必须同时存在）
- ❌ 不得让两个范式在没有 diff 比对的情况下独立演进

**核心命题**：

> **Ontology 不是告诉你哪里坏了，而是告诉你哪里坏了你会发现不了。**
> 硬编码告诉你"系统现在怎么运行"，本体告诉你"系统应该怎么运行"。
> 两者的差距就是风险。

**检查方法**：
```bash
# 工具规则双范式比对
python3 ontology/diff.py

# 治理不变式验证
python3 ontology/governance_checker.py

# 两个都必须全绿，才允许提交
```

**实证**（2026-04-07）：
- 双范式比对发现 MAX_TOOLS 定义但未 import → 修复后工具数从 18 降到 12
- 双范式比对发现 ArXiv interval 声明 vs crontab 不一致 → 修复后凌晨零推送
- 双范式比对发现 5 个 governance gap → 全部修复后 12/12 不变式通过
- Phase 0 元规则自主发现 23 个未覆盖 job → 本体从"被动记录"升级为"主动发现"

## 执行流程

```
修改 proxy_filters.py 或 ontology/*.yaml
    │
    ├── 1. 输出"本体 vs 硬编码"对比分析表格          ← 宪法第五条（最先做）
    ├── 2. python3 ontology/engine.py --check            ← 宪法第二条（工具一致性）
    ├── 3. python3 ontology/diff.py                      ← 宪法第四条（全量差异）
    ├── 4. python3 ontology/governance_checker.py         ← 宪法第六条（治理不变式）
    ├── 5. python3 -m unittest test_tool_proxy            ← 宪法第一条（不依赖本体）
    ├── 6. python3 -m unittest ontology.tests.test_engine ← 宪法第三条（rationale 检查）
    │
    └── 全部通过 + 表格已展示 → 允许提交
```

## 宪法的意义

这七条不是流程开销，而是**实验安全网**：

0. **项目隔离**保证 ontology 是独立子项目，随时可拆走、删除不影响原系统
1. **术语纪律**保证"ontology"四层不混用
2. **非破坏性**保证实验失败不影响生产
3. **一致性安全网**保证两套系统不会悄悄漂移
4. **rationale**让每条规则有生命——可以被质疑、被修改、被追溯
5. **差异对比**让"本体化进度"可视化——哪些规则已迁移、哪些还在硬编码
6. **优势分析表格**让每一步的价值可量化、可追溯、可累积——20 次变更后自动形成价值白皮书
7. **双范式互验证**让硬编码和本体互为安全网——用成熟的传统方式完善并催熟新兴的本体论

当差异对比表格显示 100% 一致、且本体的元规则能自主发现新增声明的覆盖缺口时，就是本体从学生毕业为老师的时刻。
当 `ontology/` 目录足够成熟时，`git subtree split` 即可拆为独立仓库。

## 附录：本体论价值判别矩阵

> 以下条件用于综合判断"当前场景下本体方案应该用到什么程度"。
> 每次做功能决策前，对照此矩阵打分，决定是用本体还是配置文件就够了。

### 五个判别因子

| # | 因子 | 低值（配置文件够用） | 高值（本体价值显现） | 当前状态 |
|---|------|-------------------|-------------------|---------|
| F1 | **工具数量** | ≤20：手动列举可控 | >30：人工 review 遗漏率上升；>50：手动维护不可行 | 18 个（低） |
| F2 | **策略数量** | ≤5：交叉少，人工可检查 | >10：策略交叉频繁；>20：冲突检测必须自动化 | ~5 个（低） |
| F3 | **变更频率** | 每月 ≤2 次工具/策略变更 | 每周 >3 次变更：手动同步 4 处的出错率不可接受 | 低频（低） |
| F4 | **多方协作** | 单人维护 | 2+ 团队/Agent 共享工具和策略：术语漂移+权限冲突 | 单人（低） |
| F5 | **合规要求** | 内部项目，无外部审计 | 受监管行业：每条规则需要依据、变更历史、审批记录 | 无（低） |

### 判别规则

```
得分 = 高值因子的数量（0-5）

0-1 个高值: 配置文件/硬编码足够。本体是过度设计。
            → 仅保留 Phase 0（声明式 YAML + 一致性检查），不继续推进
            
2-3 个高值: 本体开始有实际价值。语义查询和自动推导可以减少维护成本。
            → 推进到 Phase 2（语义查询接入业务逻辑）

4-5 个高值: 本体是必需品。没有本体的系统在这个规模下不可治理。
            → 全面推进到 Phase 3（独立模块 + 企业级参考实现）
```

### 当前评估（2026-04-06）

| 因子 | 当前值 | 判定 | 预测（6个月后） |
|------|--------|------|---------------|
| F1 工具数量 | 18 | 低 | 中-高（OpenClaw plugin 生态增长，预计 30-40） |
| F2 策略数量 | ~5 | 低 | 中（随合规和多 Agent 需求增长，预计 10-15） |
| F3 变更频率 | 低频 | 低 | 中（工具数量增长带动策略变更） |
| F4 多方协作 | 单人 | 低 | 中（如果开源被其他团队使用） |
| F5 合规要求 | 无 | 低 | 待定（取决于目标行业） |

**当前得分：0 个高值 → 诚实结论：配置文件目前够用。**
**预测得分：2-3 个高值 → 6 个月后本体开始有实际价值。**

**这就是为什么我们现在做的是"验证方法论"而不是"替换生产系统"。** 提前在小规模验证，等条件成熟时方法论已经过验证，可以直接推广。

### 何时重新评估

以下任一事件发生时，必须重新对照矩阵打分：

- [ ] OpenClaw 工具数量超过 30
- [ ] 策略规则超过 10 条
- [ ] 第二个团队/开发者开始使用本项目的工具体系
- [ ] 有外部用户/企业表达采用意向
- [ ] 目标行业确定（金融/供应链/医疗等受监管行业）
- [ ] 多 Agent 协作上线（2+ Agent 共享工具策略）

---
*创建: 2026-04-06 | 修订: 2026-04-07（新增第六条：双范式互验证）| 这是不可修改的宪法，除非原则本身需要演化*
