风险边界与引入方案

专题结论

Semantica 的主要风险不是“完全没有实现”，而是同一仓库内成熟度跨度很大：有些模型和算法值得验证，有些路径只完成接口或骨架，有些能力通过可选包装器接入且可绕过。整包采用会把这些差异一起带入生产。

建议：固定提交、建立隔离适配层、分三个 PoC 验证；通过语义正确性、审计完整性、性能和运维门槛后，只引入边界清晰的组件。

1. 风险总表

原始风险调用链与关键片段

ConflictDetector.resolve_conflicts()（接收冲突列表并返回统计结果的方法）遍历输入冲突，根据配置增加已解决或未解决计数，最后只返回统计字典；该方法范围内没有调用实体仓储、图写入或 ConflictResolver.resolve_conflict()（根据策略生成单个冲突裁决结果的方法）。因此其真实状态流是“冲突列表 → 计数判断 → 进度更新 → 统计返回”，不是“冲突列表 → 选择值 → 回写实体”。

原项目关键片段——ConflictDetector.resolve_conflicts()（只改变解决统计计数的占位处理方法片段）。

固定提交片段：冲突解决计数逻辑 原项目关键片段

for i, conflict in enumerate(conflicts):
    if self.auto_resolve:
        # Simple resolution logic: pick value with highest confidence
        # This is a placeholder for more complex logic
        if conflict.conflicting_values:
            # Mark as resolved (in a real system we would update the entity)
            resolved_count += 1
        else:
            unresolved_count += 1

这段实现直接证明“已解决”只是计数变化，源码注释也明确真实系统才会更新实体。可借鉴的是把自动处理、人工处理和进度反馈纳入同一工作流；不能照搬的是把统计结果当作数据已经完成裁决写回。

2. 核心依赖与部署边界

项目主体是 Python 库，没有统一核心 Web 框架。核心直接依赖已覆盖数值计算、NLP、Transformer、图计算、RDF、向量检索、可视化、文档、图像和音频处理。即使只使用来源或时态能力，未裁剪安装也会承担较大的包体、漏洞面和构建复杂度。

Explorer 是可选扩展，后端使用 FastAPI（Explorer HTTP 与 WebSocket 框架，约第 237 行），前端使用 React（工作台组件框架，锁定 19.2.5）与 Vite（前端构建工具，锁定 6.4.3）。前端 npm 依赖由 package-lock.json（固定前端直接与传递依赖的锁文件）锁定；Python 侧也有 requirements-ci.txt（为 Python 3.11 和 all 可选组生成的带哈希 CI 锁定清单，该可选组不含 GPU 依赖），但它不是针对生产最小能力、目标运行时和部署平台生成的专用锁定。

PoC 应把依赖分成：

• 直接依赖：PoC 代码实际 import 的最小集合；
• 可选依赖：仅相应后端、数据库、LLM 或 Explorer 功能启用时安装；
• 开发依赖：测试、格式化、类型检查和文档工具，不进入运行镜像；
• 传递依赖：由锁文件固定并由软件成分分析持续跟踪。

上游项目自身采用 MIT License（项目许可文本，约第 1—21 行），pyproject.toml（项目元数据清单，约第 10、22 行）也给出相同声明。该许可降低了项目代码的使用、修改和分发门槛，但不能覆盖第三方依赖、可选后端、模型与数据集的独立条款。生产前仍需基于实际启用的最小集合完成许可证核查、漏洞扫描、镜像体积评估、模型下载策略、CPU/GPU 兼容验证和离线构建验证。

3. 测试证据的解释边界

仓库包含双时态、来源、冲突和 Datalog 测试，例如双时态综合测试、来源边界测试和Datalog 测试。这些测试说明维护者覆盖了不少关键行为，但本次分析没有执行它们，不能据此宣称当前环境全部通过。

部分来源集成测试在模块不可用时直接跳过，见全模块来源测试和来源模块测试。因此测试数量不能等同于端到端链路已验证；PoC 必须把跳过项、可选依赖和底层导入纳入验收报告。

4. 建议的隔离边界

不要让业务代码直接依赖 Semantica 的大对象或跨模块 wrapper。建议建立自有适配层：

适配层只暴露稳定的自有契约，例如追加事实版本、按双轴读取快照、记录来源、作废实体、执行规则和返回完整证明。任何 Semantica 类型、异常或存储对象都不应越过该边界。

下面是抽象示例（不是项目原样配置），展示 PoC 必须锁定的运行信息：

component: semantica-adapter
source_commit: 5c6b40f36ceb8963ec76a9f0113363546b8675e8
package_version: 0.6.6
python_runtime: 3.12.x
dependency_lock_digest: sha256:generated-during-poc
enabled_capabilities:
  - provenance-sqlite
  - temporal-query
  - datalog
disabled_capabilities:
  - rete
  - automatic-conflict-writeback

5. 三个推荐 PoC

PoC A：来源、版本与作废

对象：ProvenanceManager（来源写入、血缘、版本、作废、审计和完整性入口，约第 64 行）与 SQLiteStorage（SQLite 持久化实现，约第 391 行）。

验收：

• 同一实体多版本可以稳定追溯；
• 版本演进与语义派生保持独立；
• 作废后下游影响范围完整；
• 业务写入与来源写入不存在静默缺口；
• 导出、摘要校验、备份恢复和并发写入符合目标规模；
• 证明本地哈希链之外的签名或外部锚定方案可行。

PoC B：双时态补录与历史回放

对象：TemporalGraphQuery（双轴点时和范围查询器，约第 41 行）、TemporalVersionManager（快照、修订、差异与校验管理器，约第 1149 行）及纯时态区间引擎。

验收：

• 有效时间和记录时间查询结果符合业务样例；
• 补录、更正、撤回和替代都保留旧认知；
• 边界、时区、开放区间和时间精度一致；
• 历史快照可复现当时决策所见信息；
• 目标数据规模下查询与快照性能达标。

PoC C：Datalog 可复算规则

对象：DatalogReasoner（事实、规则、递归和固定点推导引擎，约第 39 行）。

验收：

• 真实规则可表达，结论与基准实现一致；
• 递归和循环终止，资源上限可配置；
• 图到事实的映射保留类型、时间和来源；
• 结果携带规则版本、事实版本、变量绑定和完整证明；
• 规则升级能生成结论差异并支持回滚。

6. 生产门槛

以下条件未全部满足前，不建议进入生产关键路径：

1. 固定 Python 版本、直接/传递依赖和容器摘要，可离线复现构建。
2. 关键能力的单元、契约、属性、回放、故障注入和性能测试全部通过，跳过项为零或有书面豁免。
3. 上下文、时态、来源和决策写入具有统一事务或可靠事件语义。
4. API、CLI、MCP 和 Explorer 统一经过身份、授权、审计和限流层。
5. 证据可定位到原始片段，版本和作废可以向下游传播并触发重审。
6. Rete 与自动冲突写回保持关闭，除非实现完成并通过独立正确性验证。
7. 保留 MIT 许可证要求的版权与许可声明，并确保实际启用的第三方依赖、模型和数据集通过许可证、漏洞、数据驻留与隐私核查；备份恢复和灾难演练通过组织要求。
8. 组件可在不改业务领域接口的情况下替换或回退。

7. 可借鉴的交互设计

1. 风险控制台把“已验证、待验证、已知缺口、禁用”四种状态绑定到具体能力。
2. 升级页面展示 commit、依赖锁摘要、行为差异、测试结果和回滚点。
3. 审计缺口、来源断链、时态不一致和规则重放失败进入统一异常队列。
4. 冲突裁决展示候选值、来源、置信度、时间、建议与人工决定，并保留完整历史。
5. 任何高风险动作先显示影响范围，再要求理由、审批和二次确认。

8. 引入或参照结论

9. 源码依据

返回 Semantica 项目分析主报告