// tier: helix-primary · order 10

HelixTranslate betalicense: TBD

GoGinQUIC / HTTP/3 (quic-go)gRPC + Protocol BuffersGorilla WebSocketPostgreSQLSQLiteRedisunidoc/unioffice + unipdfCobraLLMsVerifier bridgeDocker / Podman

Source

• HelixDevelopment/HelixTranslate
• HelixDevelopment/HelixConstitution

// architecture

经验证的模型书籍翻译——设计诚实，绝不静默回退

HelixTranslate 是一款高性能、基于 Go 的电子书翻译平台，可在 100 多种语言之间翻译书籍，使用经过验证的 LLM 服务商，配备实时 WebSocket 监控，并严格执行「禁止静默回退」的路由策略——宁可明确失败，绝不悄然降级。

基于 Go 的通用电子书翻译工具包。支持 FB2、EPUB、TXT、HTML、PDF 及 DOCX 等格式，跨越 100 多种语言，通过最强验证 LLM 模型（经由 LLMsVerifier 桥接）进行翻译，提供 REST/HTTP-3 及 gRPC API，支持分布式处理，并配备实时 WebSocket 监控仪表板。

HelixTranslate 是一套企业级、基于 Go 的系统，专为全书翻译而设计——不是段落或片段，而是完整的书籍作品，从头至尾。它能解析并重构多种电子书格式（FB2、EPUB、TXT、HTML、PDF、DOCX），支持 100 多种语言的自动检测，并提供 CLI 工具及 API 服务器（通过 HTTP/3 的 REST、gRPC 及 WebSocket 事件流），既可融入终端工作流，也能部署于服务网格。其核心特点在于*模型选择机制*：HelixTranslate 并非硬编码某一服务商并期望其保持稳定，而是将所有模型决策权交由 LLMsVerifier 桥接层（pkg/bridge），由其选择最强的*验证通过*的 API 模型，并返回一个确定性的、按评分排序的回退链。模型资格由响应速度、代码质量、功能丰富度及可靠性等加权评分决定——因此，为您翻译的模型是凭实力赢得位置，而非仅仅出现在配置文件中。

至关重要的是，系统在代码层面强制执行「禁止静默回退」原则：若无可用的服务商 API 密钥，或运营者明确请求不存在的服务商，流水线将直接返回明确的硬错误，而非悄然切换服务商或降级至本地运行时并假装一切正常——这一规则由专用的构建前检查点及配套的变异测试严格把关。本地运行时（Ollama、llama.cpp）被刻意排除在默认路径之外，确保弱引擎绝无机会悄然取代验证模型。在翻译核心之外，系统还配备实时 WebSocket 监控子系统：翻译 CLI 会向监控服务器发送结构化事件，驱动实时网页仪表板，而远程 SSH 工作节点则分布式承担翻译任务。此外，系统还集成多轮润色以确保一致性、预处理阶段的质量分析、翻译缓存以控制长文本成本，以及基于视觉的质量保证。整个平台遵循「反虚假工程」宪章：测试必须证明真实的用户可见结果，且必须通过强制性变异测试，而非仅靠「绿色勾选」这种毫无说服力的验证。

内容

为了可靠且*诚实*地翻译长篇书籍——绝不交付"虽有但质量下降"的译文。设计的核心理念是：缺失或无法验证的翻译必须被明确标记为严重错误，而模型选择必须始终指向经过真正验证的服务商，而非硬编码的猜测或静默的本地降级方案。

多数LLM翻译流程会悄然失效——它们默默切换至性能较弱的模型，降级至本地运行时，或输出不完整的结果，而测试套件依然显示"绿灯"，无人察觉质量的断崖式下跌。HelixTranslate从根本上杜绝了这种失效模式：模型选择受验证机制严格管控，降级链路确定且完全透明，"无密钥/无验证模型"直接触发明确的硬性错误，而非默默妥协。这一设计决策将"此翻译是否真正由可靠、经过验证的模型执行？"从一个无法验证的期望，转变为系统强制保障的承诺。

• 基于验证的模型路由：通过LLMsVerifier桥接器，自动选择最强的*已验证*模型，运营人员只需表达意图而非指定供应商，且无需手动选择可能宕机的服务商。
• 代码强制的"无静默降级"保障：四条明确的路由分支（模拟/显式验证器/显式供应商/桥接器默认），每条分支均触发硬性错误而非静默切换，同时刻意移除默认路径中的本地运行时，确保无更弱的降级选项可用。
• 机械化强制执行：CM-NO-LOCAL-RUNTIME预构建检查点，配合变异测试，在构建阶段即断言默认路径上绝不构造本地运行时客户端——若保障失效，构建直接失败，确保规则不被侵蚀。
• 确定性、按评分排序的降级链路：允许在*已验证*模型间进行供应商级别的故障转移，且过程完全透明，与被禁止的静默降级形成原则性区分——用户始终知晓是哪个可靠模型接管了任务。
• 实时WebSocket监控：结构化的翻译事件实时推送至仪表盘，通过分布式SSH工作节点，确保长篇书籍翻译任务可见且并行处理，而非黑盒操作。
• 反虚假测试机制：结合变异测试、否定断言、真实系统运行及视觉驱动的质量保证，确保"测试通过"绝不掩盖"功能实际失效"的问题。

• 确保翻译流程诚实可靠（杜绝静默降级）。通过将所有模型决策权集中于LLMsVerifier桥接器，形成单一管控点；设计四条明确的路由分支，每条分支均以硬性错误而非猜测应对；彻底移除默认路径中的本地运行时降级选项；并通过构建检查点及变异测试将规则固化——若保障被移除，构建直接失败。
• "测试绿灯，功能失效"。系统章程直指这一失效模式，并通过反虚假测试机制予以根除：采用面向用户的具体断言而非实现细节，引入真实系统（模拟仅限于单元测试），强制变异测试（刻意破坏功能后测试*必须*报错），以及通过视觉验证的质量保证，实际审视输出结果。
• 长篇多格式内容的质量保障。书籍级别的输入对一致性和成本均构成挑战；通过多轮润色、预分析阶段评估任务规模，以及翻译缓存（避免重复计算同一段落）予以解决。

内容

• Go —— 选用该技术是因其原生并发原语，能自然映射至并行解析、翻译及流式传输多个章节的需求；高并发后端模块位于 digital.vasic.translator。
• Gin —— 选用此轻量高速 HTTP 路由器，用于服务 REST API 接口层。
• QUIC / HTTP/3（quic-go） —— 选用该组合为 REST API 提供低延迟、现代化传输协议，确保在不稳定网络环境下依然稳定运行。
• gRPC + Protocol Buffers —— 选用此强类型、高性能服务接口，与 REST 并行运行，专为程序化调用方设计。
• Gorilla WebSocket —— 选用该技术承载实时、类型化的翻译事件流，为监控仪表板提供实时数据。
• PostgreSQL、SQLite、Redis —— 刻意采用三层架构：PostgreSQL 负责持久化关系型数据，SQLite 用于嵌入式/本地状态存储（同时支撑桥接器的已验证模型存储，位于 data/verified_models.db），Redis 则作为热缓存。
• unidoc/unioffice + unipdf —— 选用该组合处理复杂格式：DOCX 与 PDF 的解析与重构，确保多格式电子书往返转换的准确性。
• Cobra —— 选用该框架驱动 unified-translator 及其配套工具。
• golang-jwt（JWT HS256） —— 选用无状态 API 身份验证，结合基于 IP 的令牌桶限流及 TLS/QUIC 传输层安全机制，强化接口层防护。
• LLMsVerifier 桥接器（pkg/bridge） —— 核心组件：提供最优验证模型及其确定性降级链路，并作为唯一强制执行点，确保「无静默降级」承诺的落地。
• Testify —— 选用该测试套件，涵盖 Go 的测试集，包括专用的 provider_routing_test.go 及确保诚实规则不被篡改的变异测试门控。
• Docker / Podman（无根模式）+ Compose —— 选用容器化分布式部署方案（docker-compose.distributed.yml），采用无根 Podman 进一步提升安全性。

• 状态：测试版。 平台功能完备，但版本号在 VERSION、Makefile 及 AGENTS.md 中存在不一致，视为未最终确定。
• 许可证：待定。 README 声明为 MIT 许可，但未与 LICENSE 文件核实——使用前需确认。
• 仪表板/监控端点仅限本地访问，不对外公开。文档中提及的 WebSocket 性能指标为目标值，未经验证。ARCHITECTURE.md 仍列有已移除的 Ollama/本地引擎（信息过时）。

优先级：Helix 主要（LLM 基础设施集群）。在 Helix 平台家族中，优先级次于 HelixTrack。