ontorefactor-governance/docs/architecture.md

架构与扩展边界

模块职责

• db.py：唯一持久化边界，提供租户隔离的 SQLite 表与事务。
• service.py：本体、断言、证据、规则、问题、影响分析和导出领域逻辑。
• agents.py：只使用 lambdagent 公共 API 组合治理流水线。
• llm.py：LongCat Provider、语义 Prompt、严格输出协议、安全转换和连接测试。
• api.py：FastAPI 输入校验、租户作用域、认证开关与静态页面托管。
• static/：无 Node.js 构建依赖的治理控制台。
• ontology/：版本化 M3–M0 Turtle 与 SHACL 语义合同。

依赖方向固定为 API → service/agents → db，agents → lambdagent。领域层不知道 AgentPaaS，也不依赖 FastAPI。

数据和智能体的控制边界

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

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

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

替换存储

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

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

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

与 AgentPaaS 的可选集成

如果将来要放回 AgentPaaS，只新增外层适配器：

• 把 PaaS 身份映射为 tenant_id 和 reviewer。
• 把平台任务请求转发到独立 API。
• 把 run_id、结果摘要和链接回写到 PaaS。

不要让独立项目导入 AgentPaaS 的 ORM、路由或配置。这样 Web 控制台、命令行、容器和 PaaS 四种入口可以共享同一治理内核。