ontorefactor-governance

OntoRefactor Governance

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

它与 lambdagentpaas 已解耦：运行时只依赖可由 pip 从 Gogs 安装的 lambdagent Python 包，不导入 AgentPaaS 的 API、数据库、鉴权、前端或配置。AgentPaaS 可以作为以后可选的部署适配器，但不是本项目启动的前置条件。

这是什么系统

平台解决六件事：

1. 用 M3–M0 本体表达“元模型—领域类型—项目模型—运行事实”。
2. 管理业务、软件/数据、治理三个 Profile 及其跨域关系。
3. 把来源、置信度、生成者、有效期和人工复核绑定到每条语义断言。
4. 从 DDL、OpenAPI、JSON 资产清单发现模型，并把候选关系送入人工闭环。
5. 执行层级、来源、Owner、敏感字段策略、业务到软件映射等确定性门禁。
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，点击“创建演示项目”即可得到一个通过治理校验的租户隔离参考模型。交互式 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 大模型已配置”时，可以先点击“测试模型连接”，然后选择以下语义方式：

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

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

如何使用

挑战杯现场演示可直接打开 http://127.0.0.1:8010/?demo=1，点击“一键准备挑战杯 Demo”，按首页六步演示路径操作。完整讲稿、时间分配和断网兜底见 docs/demo-runbook.md。

• 治理总览：观察模型数量、开放问题、待审断言和 M3–M0 分布。
• 本体模型：检索业务、软件、数据和治理元素，点击对象执行关系影响分析。
• 语义断言：接受或驳回智能体推断出的候选关系。
• 证据中心：追溯断言对应的 DDL、OpenAPI、运行观测或人工声明。
• 治理问题：运行规则并把高风险问题推进到关闭状态。
• 智能体工作台：上传或粘贴 DDL、OpenAPI YAML/JSON、资产清单，先预检内容，再查看执行轨迹和落库结果。
• JSON-LD：在“本体模型”中导出当前项目，供图数据库、语义工具或其他平台使用。

文件上传支持 .sql、.json、.yaml 和 .yml，单文件最大 512KB。工作台提供三份可下载的演示输入；选择文件后，平台会自动识别类型，显示表、字段、API、Schema、敏感字段和文件哈希，预检不会写入数据库。点击“开始智能治理分析”后，原始文件会作为 SourceArtifact 保存到 SQLite 的 governance_evidence 表，运行记录和输入哈希保存到 governance_agent_runs 表。

上传接口：

POST /api/v1/governance/projects/{project_id}/sources/preview
POST /api/v1/governance/projects/{project_id}/agent-runs/upload

例如用 DDL 直接运行智能体：

curl.exe -X POST "http://127.0.0.1:8010/api/v1/governance/projects/<project_id>/agent-runs/upload" `
  -H "X-Tenant-ID: local" `
  -F "file=@src/ontorefactor_governance/static/samples/01-dcp-user.sql" `
  -F "source_type=auto" `
  -F "semantic_mode=llm" `
  -F "instruction=识别业务语义、敏感字段、Owner、质量规则和治理风险"

资产清单支持 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 流水线，其中业务语义分支可以调用一次 LongCat-2.0：

输入规范化
    ├── 确定性资产发现
    ├── LongCat 业务语义、Owner、分类与质量规则建议
    └── 确定性治理控制分析
            ↓
      结构校验、去重、证据化、候选落库

这些名称表达职责边界，便于单独测试和替换。资产发现与门禁是确定性代码；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。