# 架构与扩展边界

## 模块职责

- `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`](llm-integration.md)。

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

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

```text
空白项目 + 用户上传文件
  ├─ 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 入口共享同一治理内核。