Right Reasons

Right Reasons

结构化业务本体，为 AI Agent 提供对机构推理的确定性访问。

使用 Markdown + RAG 的 AI Agent 在“为什么？”问题上的召回率为 0%。使用 Right Reasons 的同类 Agent 召回率为 100%。测试涵盖 48 个会话，并由 2 位独立评审员评估。完整实验结果 →

实验结果

在真实业务领域中进行测试（48 次运行、8 种任务类型、2 位独立的大模型评审员）：

指标	Markdown + RAG	Right Reasons	差异
实体召回率	0.514	0.976	+90%
“为什么？”问题召回率	0.000	1.000	0% → 100%
推理质量	1.96 / 5	4.33 / 5	+121%
稳定性（方差）	1.457	0.472	稳定性提升 3 倍
延迟	284.6s	183.8s	快 35%
两两对比胜场	0	20	（4 次平局）

完整方法和结果 →

功能介绍

Right Reasons 将你的业务知识映射到一个四层本体中：

LORE      (beliefs, worldview)
  ↓ interpreted_into
VISION    (goals, theses, priorities, boundaries)
  ↓ operationalized_into
RULES     (policies, decision rules, tactical concepts)
  ↓ applied_to
OPERATIONS (initiatives, decisions, tasks, events)

层与层之间的每个连接都带有一条断言——对这种关系存在原因的明确解释。这意味着 AI Agent 可以从任何运营决策追溯到为其提供依据的基础信念。

核心概念

• 确定性检索：使用 SQL 查询，而非向量搜索。不会产生概率性幻觉。
• 可实体化关系：每条边都可以附带一条经过版本管理的“为什么？”解释。
• 人工验证：每项 AI 提议的更改都须经过基于差异的审批（Dolt = 数据版 Git）。
• OPS Contracts：推理封装，将机构背景信息附加到外部系统中的工作。
• EPICAL pipeline：提取 → 思考 → 询问 → 校准 → 认证 → 加载。

快速开始

前提条件

• Docker 和 Docker Compose
• Python 3.11+

1. 启动数据库

docker compose up -d

这会使用架构和示例种子数据初始化 Dolt（涵盖全部 4 层的 11 个对象、8 个关系）。

2. 安装 MCP 服务

cd mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

3. 连接你的 AI Agent

将以下内容添加到你的 Claude Desktop / Claude Code MCP 配置中：

{
  "mcpServers": {
    "right-reasons": {
      "command": "/path/to/mcp-server/.venv/bin/right-reasons-mcp",
      "env": {
        "RR_DOLT_HOST": "127.0.0.1",
        "RR_DOLT_PORT": "3307",
        "RR_DOLT_DATABASE": "right_reasons"
      }
    }
  }
}

4. 试用

向你的 Agent 提问：

Why did we choose Provider A over Provider B for identity?
Use the get_explanation_packet tool with object ID "ex_ops_02".

Agent 将追溯推理链：

• OPERATIONS：选择 Provider A（价格实惠，兼容 OIDC）
• RULES：从价格实惠的身份提供商开始，之后再规划迁移
• VISION：为微型创业者打造自助服务工具
• LORE：小企业主希望自己处理会计事务

MCP 工具（18 个）

查询工具（9 个）

工具	描述
list_objects	按层、类型、搜索内容、验证状态筛选并列出对象
get_object	获取单个对象的完整详情
list_relations	列出关系及其断言解释
get_relation_assertion	获取某个关系的完整断言历史
traverse_graph	遍历本体图，追溯“为什么？”链条
get_schema_info	获取所有对象类型（14 种）和关系类型（20 种）
get_authentication_trail	审计轨迹：谁提出、确认、验证
get_explanation_packet	一次调用获取某个对象的完整背景信息
query_sql	用于高级查询的只读 SQL

变更工具（4 个）

工具	描述
create_session	启动 EPICAL 接收会话
propose_object	暂存候选对象（晋升前须先完成认证）
propose_relation	暂存候选关系
promote_candidate	将已认证的候选项晋升为规范项

OPS Contract 工具（3 个）

工具	描述
generate_ops_contract	根据本体自动生成用于外部工作的推理封装
get_ops_contract	获取解析了引用的合同
list_ops_contracts	按状态或类型列出合同

Dolt 工具（2）

工具	描述
dolt_status	工作集状态（类似于 git status）
dolt_diff	提交之间的行级差异（类似于 git diff）
dolt_commit	提交更改并附上说明

EPICAL：知识如何进入本体

Right Reasons 不允许 AI Agent 直接写入规范本体。所有知识都要经过 EPICAL 流程：

Source docs ──▶ EXTRACT ──▶ PONDER ──▶ INTERROGATE ──▶ CALIBRATE ──▶ AUTHENTICATE ──▶ LOAD
                  │           │            │               │              │              │
               raw text    identify     challenge       adjust        human           promote to
               intake      candidate    claims &        confidence    validates       canonical
                           objects &    assumptions     scores        via Dolt        ontology
                           relations                                 diff review

阶段	发生的事	参与者
提取	将源文档解析为片段	Agent
推敲	识别候选对象和关系	Agent
质询	质疑主张，揭示缺漏	Agent
校准	调整置信度和持久性评分	Agent
认证	人工审核 Dolt 差异，并批准或拒绝	人工
加载	将已认证的候选项提升为规范状态	Agent

认知边界严格明确：promote_candidate 要求状态为 authenticated 或 calibrated。Agent 不能绕过人工验证。

OPS 合约：外部工作的推理封套

OPS 合约解决了“最后一公里”问题：如何将组织推理传递到实际开展工作的系统（Jira、CI/CD、规划工具）？

OPS 合约不是任务管理器，而是一种推理封套——一个回形针，将限定范围的组织上下文附加到外部系统中的工作项上。

External work item          OPS Contract                    Ontology
(Jira, GitHub, etc.)        (reasoning envelope)            (4 layers)
┌──────────────┐     ┌─────────────────────┐     ┌──────────────────┐
│ TASK-123:    │────▶│ Clauses (from RULES)│◀────│ RULES: policies, │
│ Prepare      │     │ Constraints         │     │ decision rules   │
│ annual       │     │ Success criteria    │     ├──────────────────┤
│ report       │     │ References (31)     │     │ VISION: goals,   │
│              │     │ Reasoning chain (13)│     │ boundaries       │
└──────────────┘     └─────────────────────┘     ├──────────────────┤
                                                  │ LORE: beliefs,   │
                                                  │ worldview        │
                                                  └──────────────────┘

Agent 通过一次调用生成它：

generate_ops_contract(
    external_work_ref="jira://TASK-123",
    description="Prepare annual report for submission",
    contract_kind="annual_reporting"
)

合约会告诉执行任务的 Agent 这项任务为何重要、适用哪些规则，以及绝不能越过哪些边界，而无需 Agent 自行查询整个本体。

架构

完整架构见 schema/LOAD1st_bootstrap.sql。

核心表：

• rr_object — 规范业务对象，包含层级、置信度和验证状态
• rr_relation — 对象之间的类型化边
• rr_relation_assertion — 版本化的“为什么？”说明（可再化关系）
• rr_object_type — 4 个层级中的 14 种类型
• rr_relation_type — 5 个类别中的 20 种关系类型
• ops_contract — 外部工作项的推理封套
• src_session、src_candidate_object、src_candidate_relation — EPICAL 接入流程
• src_authentication_event、rr_validation_record — 审计跟踪

对象类型（14）

层级	类型	描述
LORE	lore_item	基础信念或世界观要素
VISION	strategic_goal	期望在较长时间范围内达成的结果
VISION	strategic_thesis	关于如何创造成功的方向性信念
VISION	strategic_priority	对不同战略方向的相对权重
VISION	strategic_boundary	战略禁区或明确限制
RULES	policy	从较高层级战略推导出的运营政策
RULES	decision_rule	影响行动的离散逻辑
RULES	escalation_rule	向上追溯或进行人工审核的触发条件
RULES	tactical_concept	可复用的应用型运营模式
OPERATIONS	initiative	范围明确的工作或计划
OPERATIONS	situation	需要解读的实时情境
OPERATIONS	decision	已选择或建议采取的行动方案
OPERATIONS	task	具体行动单元
OPERATIONS	event	观察到的结果或信号

关系类型（20）

分为 5 个系列。可具体化的关系（✓）可以附带带版本的断言说明。

过渡 — 构成推理主线的跨层链接：

代码	描述	可具体化
interpreted_into	LORE → VISION 的解释性过渡	✓
operationalized_into	VISION → RULES 的操作化	✓
applied_to	RULES → OPERATIONS 的应用	✓

结构 — 层内关系：

代码	描述	可具体化
supports	正向贡献
constrains	限制关系
conflicts_with	张力或冲突
depends_on	依赖关系
affects	实质性影响
relevant_to	情境相关性

推理 — 论证与优先级排序：

代码	描述	可具体化
justified_by	明确的推理支持	✓
validated_against	与另一对象进行验证	✓
prioritized_over	相对排序	✓
escalates_to	升级目标	✓

治理 — 所有权与权威：

代码	描述	可具体化
owned_by	所有权
reviewed_by	审查关系
authorized_by	授权
overridden_by	覆盖（附带说明）	✓

反馈 — 观察与结果：

代码	描述	可具体化
observed_in	在情境中的观察
resulted_in	因果结果	✓
evaluated_by	评估	✓

架构

┌─────────────┐     ┌──────────────┐     ┌──────────┐
│  AI Agent   │────▶│  MCP Server  │────▶│   Dolt   │
│ (Claude,    │     │  (Python /   │     │  (Git    │
│  GPT, etc.) │◀────│   FastMCP)   │◀────│  for     │
│             │     │  18 tools    │     │  data)   │
└─────────────┘     └──────────────┘     └──────────┘
                           │
                    stdio / SSE / HTTP

• Dolt 为数据提供 Git 语义：分支、提交、差异、合并、PR 风格的验证
• MCP 是 Agent 与工具通信的事实标准（SDK 下载量超过 9,700 万）
• Python / FastMCP 让服务保持简单（7 个文件共约 700 行）

示例：生成 OPS Contract

generate_ops_contract(
    external_work_ref="jira://TASK-123",
    description="Prepare annual report for submission",
    contract_kind="annual_reporting"
)

返回一个推理封装，其中包含：

• 根据 RULES 层对象推导出的条款
• 来自策略的约束
• 来自决策规则和战术概念的成功标准
• 对全部 4 个层中所有相关对象的引用
• 展示完整 LORE → VISION → RULES → OPS 路径的推理链

许可证

Business Source License 1.1 — 请参阅 LICENSE。

贡献

Right Reasons 仍处于早期开发阶段。如果您有兴趣参与贡献，或将其用于您的业务，请提交 issue 或联系我们。