ontorefactor-governance/docs/llm-integration.md

LongCat-2.0 接入与安全边界

调用协议

• Provider：LongCat
• Model：LongCat-2.0
• OpenAI 兼容入口：https://api.longcat.chat/openai/v1/chat/completions
• 认证：Authorization: Bearer <LONGCAT_API_KEY>
• 默认温度：0.1
• 默认关闭思考模式：LONGCAT_THINKING=disabled。治理语义抽取使用严格结构化协议，关闭思考可降低延迟和超时风险；需要复杂推理时可显式设为 enabled
• 默认最大输出：4096 tokens
• 请求使用 response_format=json_object；若仍出现语法或字段协议错误，智能体会进行一次受控格式修复
• 超时：120 秒
• 对 HTTP 429、5xx 和临时网络错误执行指数退避重试

LONGCAT_API_KEY 只从服务端环境读取。状态 API 只返回 configured: true/false，不返回密钥内容、长度、前缀或哈希。

智能体边界

LongCat 分支接收确定性解析后的 M1 资产目录，以及从当前项目数据库查询、脱敏并按预算截断的本体关系、证据摘要和启用规则。它不接收数据库口令、请求头或未处理的密钥。允许模型建议：

• 数据表/API/Schema 对应的业务对象；
• Owner 角色；
• public、internal、confidential、restricted 分类；
• 完整性、唯一性、有效性、一致性、及时性质量规则；
• 不涉及自动执行的治理问题。
• 项目资产之间的 READS、USES、EXPOSES、BELONGS_TO、MIRRORS_TO 候选关系。

模型不得：

• 引用资产白名单之外的对象；
• 创建 M0 运行事实；
• 返回白名单之外的关系；
• 把置信度提高到 0.85 以上；
• 直接接受断言、关闭问题、执行 SQL 或修改生产系统。

输出闭环

模型输出经过以下步骤：

1. 提取 JSON，拒绝自然语言或不可解析结果；
2. 使用 Pydantic 严格校验字段和数量；
3. 验证所有资产引用；
4. 将关系限制为 REPRESENTS、OWNED_BY、CLASSIFIED_AS、VALIDATES、READS、USES、EXPOSES、BELONGS_TO、MIRRORS_TO；
5. 强制所有断言为 inferred + pending；
6. 建立 ModelInference 证据；
7. 保存模型、Prompt 版本、Token、耗时和请求/响应哈希；
8. 候选本体先等待人工发布；结构事实发布后才运行治理决策智能体。模型断言默认继续保持 pending，用户可在“语义断言”页面接受或驳回；门禁可把 pending 断言作为明确标注来源的风险线索，但不会把它伪装成已审核事实。

每个构建批次保存源文件清单、SHA-256、版本 Diff、执行轨迹和模型指标。每次 Agent Run 还保存项目上下文的 context_hash 和 context_scope。模型不负责输出 ALLOW 或 BLOCKED；最终三态结论始终由已发布本体、当前数据库事实和启用规则计算。

如果模型输出在长度上限处被截断，平台只恢复已经完整闭合且仍能通过严格协议校验的数组，并在模型指标中标记 partial_output_recovered=true；不完整数组会被丢弃，未知资产和越权关系仍会让本次运行失败。

运行模式

请求模式	行为
auto	有密钥使用 LongCat，无密钥使用规则语义
llm	必须使用 LongCat；缺少密钥或调用失败时返回错误
deterministic	永远不调用模型

部署变量 ONTOREFACTOR_LLM_MODE 可以设置为 auto、required 或 disabled，从服务端统一约束所有请求。