ontorefactor-governance/docs/architecture.md

架构与扩展边界

模块职责

• db.py：唯一持久化边界，提供租户隔离的 SQLite 表与事务。
• service.py：本体、断言、证据、规则、问题、影响分析和导出领域逻辑。
• decision.py：项目上下文快照、目标证据隔离、三态字段退役门禁和决策审计。
• agents.py：只使用 lambdagent 公共 API 组合治理流水线。
• builds.py：多文件构建批次、四职责流水线、候选 Diff、审核发布与本体版本快照。
• llm.py：LongCat Provider、语义 Prompt、严格输出协议、安全转换和连接测试。
• paas.py：可选 AgentPaaS 运行摘要回写适配器；失败不会影响独立治理事务。
• api.py：FastAPI 输入校验、租户作用域、认证开关与静态页面托管。
• static/：无 Node.js 构建依赖的治理控制台。
• ontology/：版本化 M3–M0 Turtle 与 SHACL 语义合同。

依赖方向固定为 API → builds/service/agents → db，builds/agents → lambdagent。只有 paas.py 知道 AgentPaaS 的 HTTP 合同，领域模型不导入 PaaS，也不依赖 FastAPI。

数据和智能体的控制边界

治理部分	智能体表达	确定性控制
资产目录	从 DDL/OpenAPI/清单抽取表、列、API、Schema	唯一 URI、字段校验、租户作用域
业务术语	根据名称提出业务对象候选	人工接受后才成为正式断言
血缘与关系	从当前项目上下文生成 READS、USES、MIRRORS_TO 等候选	资产白名单、关系白名单、证据完整性
数据质量	识别可能需要质量规则的对象	阈值和门禁由规则引擎执行
安全与合规	标记疑似敏感字段	敏感生产字段必须关联策略和 Owner
责任体系	推荐责任域和待确认对象	正式 Owner 关系需要声明或审核
变更影响	沿已接受断言构建影响子图	最大深度、租户边界和状态过滤
审计	保留每一步轨迹和输入哈希	运行、证据、断言、审核状态持久化
退役决策	聚合 DDL、OpenAPI、扫描、APM、质量和审批上下文	五项确定性检查产生 ALLOW、BLOCKED 或 INSUFFICIENT_EVIDENCE

LongCat 分支的完整信任边界见 llm-integration.md。

原则是“智能体提出候选，确定性规则裁决，人工负责高风险确认”。

本体构建与运行时决策数据流

空白项目 + 用户上传文件
  ├─ DDL / OpenAPI
  ├─ 资产与关系清单
  └─ 代码扫描 / APM / 质量 / 审批证据与规则
                 ↓
          资产构建智能体
                 ↓
          语义融合智能体
                 ↓
      本体校验智能体 + 版本 Diff
                 ↓
    candidate / pending → 人工审核发布
                 ↓
     ontology_versions 不可变快照
                 ↓
  数据库当前本体、规则、证据和语义断言
                 ↓ 脱敏、目标匹配、长度预算
          项目上下文快照 + context_hash
                 ↓
        治理决策智能体的确定性门禁
                 ↓
 ALLOW / BLOCKED / INSUFFICIENT_EVIDENCE
                 ↓
   决策快照、证据 ID、断言 ID、动态治理问题

上下文默认最多包含 36 个相关资产、60 条关系和 16,000 字符证据；优先保留目标字段邻域，同时记录总数、纳入数和是否截断。证据若包含 metadata.target，只进入匹配目标的门禁；未声明目标的证据按项目级证据处理。

替换存储

SQLite 是独立版的默认实现。迁移到 PostgreSQL 或图数据库时，应保留 service.py 使用的数据合同：

• 所有实体都包含 tenant_id 与 project_id。
• 元素 URI 在项目内唯一。
• 关系以断言实体存在，不能压缩成无来源的裸边。
• accepted 的非声明断言必须包含 evidence 和 generatedBy。
• M0 已发布事实必须实例化一个 M1 类型。

可以新增 repository 接口并保留现有 SQLite 作为本地和测试实现，不需要改智能体的发现结果协议。

与 AgentPaaS 的可选集成

当前已提供可选、单向的外层适配器：

• 把 PaaS 身份映射为 tenant_id 和 reviewer。
• OntoRefactor 仍在本进程内执行 LambdAgent 工作流和治理事务。
• 每个职责完成后，只把 build_id、数量、状态和耗时等脱敏摘要写入 PaaS 的运行记录接口。
• PaaS 不可用时记录 unavailable，不回滚已完成的本体构建或发布。

配置项为 AGENTPAAS_BASE_URL、AGENTPAAS_API_KEY 以及四个 ONTOREFACTOR_PAAS_*_AGENT_ID。不要让独立项目导入 AgentPaaS 的 ORM、路由或配置；Web 控制台、命令行、容器和 PaaS 入口共享同一治理内核。