ontorefactor-governance

OntoRefactor Governance

OntoRefactor Governance 是一个可独立部署的、由本体驱动的数据治理平台。它把业务概念、软件资产、数据对象、治理规则、证据与运行事实统一到 M3–M0 四层模型中，并通过 LambdAgent 与 LongCat-2.0 从 DDL、OpenAPI 或资产清单自动发现和理解治理对象。

它与 lambdagentpaas 保持解耦：核心运行时只依赖可由 pip 安装的 lambdagent Python 包，不导入 AgentPaaS 的 ORM、数据库、鉴权或前端。配置 AgentPaaS 后，平台可以把四个职责步骤的脱敏运行摘要回写到 PaaS；不配置时全部功能仍可独立运行。

这是什么系统

平台解决六件事：

1. 用 M3–M0 本体表达“元模型—领域类型—项目模型—运行事实”。
2. 管理业务、软件/数据、治理三个 Profile 及其跨域关系。
3. 把来源、置信度、生成者、有效期和人工复核绑定到每条语义断言。
4. 从 DDL、OpenAPI、资产清单和证据包构建候选本体，并展示与当前版本的 Diff。
5. 人工发布不可变本体版本后，从数据库读取当前证据并执行三态确定性门禁。
6. 提供语义断言复核、影响分析、治理问题、智能体轨迹和 JSON-LD 导出。

快速开始

需要 Python 3.10 或更高版本以及 Git。pip install 会从你指定的 Gogs 仓库安装其中的 lambdagent 子项目。

cd ontorefactor-governance
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -e ".[dev]"
ontorefactor-governance

打开 http://127.0.0.1:8010。点击“创建空白挑战杯 Demo”只会创建空项目，不会写入项目本体、关系、证据、规则或结论；随后到“本体构建”上传演示文件。交互式 API 文档位于 http://127.0.0.1:8010/docs。

默认数据文件是当前目录下的 ontorefactor.db。可通过环境变量修改：

$env:ONTOREFACTOR_DATABASE_URL = "sqlite:///./data/governance.db"
$env:ONTOREFACTOR_DEFAULT_TENANT = "my-team"
$env:ONTOREFACTOR_API_KEY = "replace-with-a-secret"
ontorefactor-governance --host 0.0.0.0 --port 8010

启用 ONTOREFACTOR_API_KEY 后，客户端需要发送 Authorization: Bearer <key>。生产环境还应由网关验证用户身份并生成可信的 X-Tenant-ID；不要把未经验证的租户请求头直接暴露到公网。

配置 LongCat-2.0

项目使用 LongCat 官方 OpenAI 兼容端点 https://api.longcat.chat/openai/v1/chat/completions，模型名为 LongCat-2.0。不要把密钥提交到 Git，也不要放进浏览器设置。

复制配置模板并填写一个新生成的密钥：

Copy-Item .env.example .env
notepad .env

在 .env 中设置：

ONTOREFACTOR_LLM_MODE=auto
LONGCAT_API_KEY=替换为新生成的密钥
LONGCAT_BASE_URL=https://api.longcat.chat/openai
LONGCAT_MODEL=LongCat-2.0
LONGCAT_THINKING=disabled

重新启动平台后，进入“本体构建”。页面显示 LongCat-2.0 已配置时，可以先点击“测试模型连接”，然后选择以下语义方式：

• 自动选择：有密钥时使用 LongCat，没有密钥时使用确定性语义规则。
• 强制 LongCat-2.0：模型不可用时本次运行失败，不会伪装成 AI 结果。
• 仅确定性规则：不产生模型费用，适合离线运行和回归测试。

LongCat 官方文档：LongCat API 开放平台。

如何使用

挑战杯现场演示可直接打开 http://127.0.0.1:8010/?demo=1&tab=agent。下载并一次选择页面中的四份输入，运行三个构建智能体，检查 Diff 后发布本体；然后切换到“治理问答”，用自然语言单独调用第四个治理决策智能体。完整讲稿见 docs/demo-runbook.md。

• 治理总览：观察模型数量、开放问题、待审断言和 M3–M0 分布。
• 本体模型：检索业务、软件、数据和治理元素，点击对象执行关系影响分析。
• 语义断言：接受或驳回智能体推断出的候选关系。
• 证据中心：追溯断言对应的 DDL、OpenAPI、运行观测或人工声明。
• 治理问题：运行规则并把高风险问题推进到关闭状态。
• 本体构建：前三个智能体协作完成多文件解析、候选本体构建、Diff 审核和版本发布。
• 治理问答：第四个智能体独立接收自然语言问题，只读已发布本体和证据并执行确定性门禁。
• JSON-LD：在“本体模型”中导出当前项目，供图数据库、语义工具或其他平台使用。

文件上传支持 .sql、.json、.yaml 和 .yml，每批 1–12 份、单文件最大 512KB、总量最大 3MB。工作台提供四份演示输入：DDL、OpenAPI、资产清单、治理证据包。构建成功后，原文件作为 SourceArtifact 保存，候选元素与待审断言分别落库，并在 ontology_builds 中记录输入哈希、Diff、校验、模型指标和执行轨迹。治理规则只在发布时启用。

上传接口：

POST /api/v1/governance/projects/{project_id}/sources/preview
POST /api/v1/governance/projects/{project_id}/agent-runs/upload
POST /api/v1/governance/projects/{project_id}/ontology-builds/upload
GET  /api/v1/governance/projects/{project_id}/ontology-builds
POST /api/v1/governance/projects/{project_id}/ontology-builds/{build_id}/publish
POST /api/v1/governance/projects/{project_id}/governance-agent/ask
GET  /api/v1/governance/projects/{project_id}/ontology-versions

例如一次提交四份文件构建候选本体：

curl.exe -X POST "http://127.0.0.1:8010/api/v1/governance/projects/<project_id>/ontology-builds/upload" `
  -H "X-Tenant-ID: local" `
  -F "files=@src/ontorefactor_governance/static/samples/01-dcp-user.sql" `
  -F "files=@src/ontorefactor_governance/static/samples/02-user-profile-openapi.yaml" `
  -F "files=@src/ontorefactor_governance/static/samples/03-dcp-asset-inventory.json" `
  -F "files=@src/ontorefactor_governance/static/samples/04-governance-evidence.json" `
  -F "semantic_mode=llm" `
  -F "environment=production" `
  -F "decision_target=dcp_user.mobile" `
  -F "instruction=从全部输入构建项目本体并识别治理风险"

动态决策闭环

项目不预置项目本体、关系、治理证据、规则或结论。前三个智能体从用户文件构建候选本体，人工确认后发布为不可变版本；该流程不会自动执行治理决策。用户随后在“治理问答”中提问，第四个智能体才从数据库加载已发布本体、启用规则、全部当前证据和语义断言，形成脱敏、长度受控的上下文并执行门禁；每次问答保存问题、上下文哈希、证据 ID、断言 ID 和结果快照。

字段退役门禁检查五项事实：代码/APM 消费者是否归零、迁移质量是否达标、Owner 与安全审批是否完成、旧契约兼容周期是否完成、加密替代字段是否就绪。结果只有三种：

• ALLOW：全部检查通过。
• BLOCKED：至少一项已有证据明确不通过。
• INSUFFICIENT_EVIDENCE：没有失败项，但至少一项缺少规则或当前证据。

演示项目本身为空。消费者为 3、迁移完整率为 99.87% 等事实来自用户上传的 04-governance-evidence.json；BLOCKED、五项检查和治理问题由发布后的当前数据库动态计算。使用相同 uri 再次调用证据接口即可更新事实，下一次门禁会得到新结果：

POST /api/v1/governance/projects/{project_id}/evidence
POST /api/v1/governance/projects/{project_id}/decisions/retirement
GET  /api/v1/governance/projects/{project_id}/decisions

治理证据在 metadata.target 中绑定字段（如 dcp_user.mobile），避免同项目其他字段的报告干扰。代码扫描/APM 使用 consumer_count，质量报告使用 completeness 与 unmatched_rows，审批使用 approved、pending、rejected，契约或发布记录使用 completed_release_cycles。生产连接器只需把这些事实持续写入 governance_evidence，无需修改决策代码。门禁还会把上传发现的同名 M1 字段解析为同一决策身份，使刚生成在导入资产上的候选断言可以直接参与当前计算。为控制模型上下文，默认只选取目标附近最多 36 个资产、60 条关系和 16,000 字符证据正文；总量、纳入量和截断状态都会进入审计。

资产清单支持 JSON 或 YAML，JSON 格式如下：

{
  "tables": [
    {
      "schema": "public",
      "name": "customer",
      "columns": [
        {"name": "id", "data_type": "INTEGER", "primary_key": true},
        {"name": "mobile", "data_type": "VARCHAR", "sensitive": true}
      ]
    }
  ],
  "apis": [],
  "schemas": []
}

为什么仍然有多个“智能体”

这里没有启动许多微服务，也没有让多个大模型自由协商。四个名称是同一条 LambdAgent 工作流中的职责边界，前三个负责构建，第四个只在本体发布后决策：

用户上传 1–12 份文件
    ↓ 资产构建智能体（确定性解析与跨文件归并）
候选结构资产
    ↓ 语义融合智能体（LongCat 或确定性语义）
候选对象、关系、Owner、分类和质量建议
    ↓ 本体校验智能体（白名单、端点、URI、Diff）
候选本体 → 人工审核 → 发布 vNext
    ↓ 治理决策智能体（数据库当前证据 + 确定性门禁）
ALLOW / BLOCKED / INSUFFICIENT_EVIDENCE

资产解析、候选校验与门禁是确定性代码；LongCat 输出必须通过 Pydantic 协议、资产白名单、关系白名单和置信度上限检查。模型断言强制为 pending，默认不会随结构事实一起接受。每个构建批次记录一个 run_id、模型、Prompt 版本、Token、耗时、输入清单和请求/响应哈希。

本体分层

层级	表达内容	平台中的例子
M3	如何定义类型、关系、属性、约束、断言	MetaEntityType、MetaAssertionType
M2	跨项目复用的领域类型	BusinessCapability、Table、QualityRule
M1	某项目的逻辑模型	Tenant、DcpTenantTable、TenantIsolationPolicy
M0	真实运行实例与观测	生产列、代码提交、质量测量

版本化 Turtle 和 SHACL 文件位于 ontology。数据库关系被重新实体化为断言，因此每条关系都能携带证据、置信度、生成者、复核状态与有效期。

容器运行

docker compose up --build

控制台仍位于 http://127.0.0.1:8010，SQLite 数据持久化在 Docker 命名卷 governance-data 中。

开发与验证

pip install -e ".[dev]"
pytest -q

测试覆盖租户隔离、参考模型幂等性、治理校验、影响分析、JSON-LD、LambdAgent 执行与审计、LongCat 协议、模型输出安全边界、HTTP API，以及全部 Turtle 资源解析。测试使用模拟响应，不消耗真实模型额度。

独立边界

ontorefactor-governance
├── FastAPI + 静态 Web 控制台
├── SQLite 治理存储
├── M3–M0 本体与 SHACL
└── lambdagent（pip 依赖）

lambdagentpaas（可选外部运行记录，核心无运行时依赖）

更细的决策与扩展点见 docs/architecture.md。