RimMind 的独立模型服务扩展模组,提供第三方模型协议适配、本地订阅代理服务(如 Codex / Sub2API)接入网关、多端点负载均衡与高可用自动故障转移。
Core 本身内置了标准 OpenAI 协议客户端。本扩展模组作为可插拔的扩展层,为 RimMind 运行体系扩展了:
- DeepSeek 官方原生协议与语音适配(
deepseek/deepseek_native):实现IContextualModelProtocol,支持退休模型自动归一化(deepseek-chat/deepseek-reasoner->deepseek-flash)、ReasoningEffort->thinking/reasoning_effort、safety_check.level=high与user_id隔离、冲突参数自动消解、多轮工具历史reasoning_content保留,并通过RimMindAPI.Ext注册ISpeechSynthesizer(/v1/tools/tts)与ISpeechRecognizer(/v1/tools/asr)。 - 原生 Anthropic Claude 协议适配:支持顶层
system隔离、tool_use/tool_result块互转、refusal内容拒绝分类与cache_read_input_tokens提取。 - 本地订阅安全网关(Codex / Sub2API / NewAPI):安全强制绑定本机回环地址(
127.0.0.1/localhost/::1),杜绝公网泄露本地订阅凭据风险。 - 多端点负载均衡与高可用容灾:支持按节点权重(
Math.Max(1, weight))分配的加权轮询(Weighted Round Robin)与主备故障转移(Priority Failover);支持单节点独立超时(node.timeoutSeconds)与基于失败发生时刻(failure-time clock)的 60 秒自动熔断隔离及半开恢复探测;通过HttpErrorClassifier精准区分ContentFiltered(不重试、不触发断路器)、ClientPermanentFailure(不重试)与ClientQuotaOrAuthFailure(IsolateImmediately立即熔断当前节点并故障转移至备用节点)。 - 实时网络延迟与健康探针:异步测量端点 RTT 延迟与连通状态,区分 HTTP 401/403 未授权响应(记录延迟但标记
isHealthy = false且不重置失败计数),并支持在游戏内设置界面与 DebugAction 一键 Ping 诊断。 - 非持久化环境变量凭据覆盖(
EnvironmentEndpointOverlay):将RIMMIND_TEST_*/RIMMIND_BACKUP_*自动化测试凭据以内存级 shadow 副本方式覆盖到无 Key 的OpenCodeGo节点,绝不污染或落盘修改玩家持久化设置。
依赖 Core,通过 Core 的 IAIClientFactory 扩展接口向 RimMindAPI.Request 注册 deepseek_native、opencode 与 extended_service 提供商,并通过 RimMindAPI.Ext 注册 ISpeechSynthesizer 与 ISpeechRecognizer。
| 项 | 值 |
|---|---|
| Target | net48 (源码), net10.0 (单元测试), C# 9.0, Nullable enable |
| Output | ../1.6/Assemblies/ |
| Assembly | RimMindModelService, RootNS: RimMind.ModelService |
| 依赖 | Krafs.Rimworld.Ref, Lib.Harmony.Ref, Newtonsoft.Json, RimMindCore (Domain/Application/Core) |
# 编译模组
dotnet build RimMind-Extension-ModelService/Source/RimMindModelService.csproj -c Release
# 运行单测
dotnet test RimMind-Extension-ModelService/Tests/RimMindModelService.Tests.csproj -c ReleaseSource/
├── RimMindModelServiceMod.cs Mod 入口,注册 deepseek_native / opencode / extended_service 工厂、TTS/ASR 扩展及设置页签
├── Audio/
│ ├── DeepSeekAudioEndpointResolver.cs 解析生效 DeepSeek 节点/环境变量基址与凭据
│ ├── DeepSeekSpeechRecognizer.cs ISpeechRecognizer 实现(POST /v1/tools/asr multipart/form-data + hotwords)
│ └── DeepSeekSpeechSynthesizer.cs ISpeechSynthesizer 实现(POST /v1/tools/tts 文本清洗与 2000 字符守卫)
├── Balancing/
│ └── LoadBalancer.cs 多端点调度(Priority Failover / 加权 Round Robin)与熔断隔离恢复
├── Client/
│ ├── DeepSeekClientFactory.cs deepseek_native 官方直连工厂(透传 ModelService DeepSeek 池或回落 Core 设置)
│ ├── EnvironmentEndpointOverlay.cs 自动化环境变量非持久化 shadow 凭据覆盖层(不污染 ModSettings)
│ ├── ModelServiceClient.cs IAIClient 多端点客户端(单节点超时、失败时刻熔断、风控/配额分流与密钥脱敏)
│ ├── ModelServiceClientFactory.cs extended_service 提供商工厂(受 enableService 门控 + EnvironmentEndpointOverlay)
│ └── OpenCodeGoClientFactory.cs opencode 订阅直连提供商工厂(自动注入 x-opencode-session)
├── Debug/
│ └── ModelServiceDebugActions.cs DebugAction 批量端点探活诊断(GetEndpointsSnapshot 快照 + MainThread.Post 回调)
├── Diagnostics/
│ └── EndpointHealthProbe.cs 异步 HTTP 连通与 RTT 延迟探针(区分 401/403 未授权与 5xx/网络异常)
├── Integration/
│ └── ModelServiceSettingsTab.cs ISettingsTab 扩展设置页签注册
├── Models/
│ ├── ModelEndpointConfig.cs 端点配置模型(含 thinkingPolicy / safetyLevel)、Scribe 持久化与 IsolateImmediately
│ ├── ModelEndpointPresets.cs Codex 本地网关、OpenCode Go 与 DeepSeek 官方预设工厂
│ └── ProviderType.cs 协议类型、负载均衡策略、思考模式与安全等级枚举
├── Protocol/
│ ├── AnthropicProtocolAdapter.cs Anthropic Claude 原生 messages 协议、refusal 识别与 ephemeral 缓存适配
│ ├── DeepSeekProtocolAdapter.cs DeepSeek V4 原生方言适配器(thinking/safety_check/冲突消解/工具历史推理链)
│ ├── HttpErrorClassifier.cs 统一 HTTP 错误分流(ContentFiltered / ClientQuotaOrAuth / Transient / Permanent)
│ ├── IModelProtocol.cs IModelProtocol、ProtocolCapabilities 与 IContextualModelProtocol 协议契约
│ ├── ModelProtocolRegistry.cs 协议注册表及 OpenAI / Anthropic / LocalGateway / OpenCodeGo / DeepSeek 协议实现
│ └── OpenAIProtocolAdapter.cs OpenAI 兼容报文与 ToolCall 互转适配器
├── Security/
│ └── LocalLoopbackValidator.cs 本机回环安全检查与公网泄露拦截
└── Settings/
├── ModelServiceSettings.cs Scribe 存档配置、EndpointSyncRoot 锁对象与 GetEndpointsSnapshot 快照
└── ModelServiceSettingsDrawer.cs Mod 设置界面(含 DeepSeek 预设、Thinking/Safety 选择器、Tooltip 与一键 Ping 诊断)
- 回环限制契约:类型为
LocalSubscriptionGateway的端点,其主机名必须被LocalLoopbackValidator.IsLoopbackAddress认定为回环地址(127.0.0.1/localhost/::1)。任何指向非回环公网地址的本地订阅请求将被强制记录失败并阻断(若有健康备用节点则故障转移,否则返回RimMindErrors.ClientPermanent),保护玩家的本地代理凭据。 - 环境变量非持久化覆盖契约(
EnvironmentEndpointOverlay):自动化测试环境变量(RIMMIND_TEST_*/RIMMIND_BACKUP_*)仅通过EnvironmentEndpointOverlay.Apply生成按节点 ID 缓存的内存 shadow 副本,严禁直接修改ModelServiceSettings.endpoints中的持久化实例,杜绝测试 API Key 明文写入设置 XML 或覆盖玩家 URL/模型。 - 并发、锁与列表实例契约:
ModelServiceClientFactory尊重ModelServiceSettings.enableService主开关;ModelServiceSettings.EndpointSyncRoot与endpoints指向同一列表实例,EnsureDefaultEndpoints()与ResetToDefault()必须在lock (EndpointSyncRoot)下原地修改集合(Clear()+AddRange(...)),保留endpoints列表引用不变。UI 渲染、批量探活与后台线程读取统一通过settings.GetEndpointsSnapshot()或lock (settings.EndpointSyncRoot)获取快照。 - 负载均衡、单节点超时与错误分流契约:
LoadBalancer支持主备优先(PriorityFailover)与按Math.Max(1, weight)比例分配的加权轮询(RoundRobin)。ModelServiceClient为每个候选节点应用独立的node.timeoutSeconds超时(最小 5 秒)并叠加总超时;瞬态失败(408/429/5xx/网络异常/insufficient_system_resource)按失败发生时刻累加RecordFailure并触发 60 秒熔断及备切;ClientQuotaOrAuthFailure(HTTP 401/402/403/余额不足/Key 失效)调用IsolateImmediately立即熔断当前节点并故障转移至备用节点;ContentFiltered(HTTP 400Content Exists Risk/content_filter或finish_reason=content_filter/refusal)与ClientPermanentFailure立即返回且不污染节点健康状态;错误消息中的 Bearer/API Key 经正则脱敏。 - 健康探针鉴权契约(
EndpointHealthProbe):探针收到 HTTP 401/403 时记录实测 RTT 延迟,但必须标记isHealthy = false(返回reachable but unauthorized)且不重置consecutiveFailures;仅 2xx 或 404 视为探活成功并调用RecordSuccess。 - 伪本地化防御契约:所有动态或外部翻译 Key 调用前必须经
Translator.CanTranslate守卫并提供英文退化文本。 - Core 边界契约:严禁侵入 Core 内部队列或私有单例,仅通过
IAIClient、IAIClientFactory、ISpeechSynthesizer、ISpeechRecognizer、ISettingsTab与RimMindAPI.MainThread.Post公共契约协作。