Wenyi架构全景：CLI、Web与Worker如何共享同一个翻译内核

【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyi

Wenyi 是一款面向长文本的开源翻译工具，用全书理解、实时术语库与证据驱动审校，把被语言阻隔的作品带到读者的语言中。它最有意思的一点是：CLI 命令行、Web 界面、后台 Worker 三条使用路径，跑的是同一个翻译内核。无论你是终端极客还是浏览器用户，得到的翻译流程、状态模型和质量控制完全一致。这篇文章用一次架构图解，讲清 Wenyi 架构中 CLI、Web 与 Worker 如何分工协作。

三种入口，一个内核：Wenyi 的整体分层

理解 Wenyi 架构，先记住一条依赖方向：所有入口最终都汇聚到同一个核心包wenyi-core。

关键约束写在仓库架构文档里（英文版 docs/architecture.md，中文版 docs/zh/architecture.md）：Core 不依赖 CLI 或 Web 框架。内核不知道自己是跑在终端里还是容器里，这是"共享内核"能成立的前提。

状态存储是唯一"可替换零件"

内核读写状态一律通过存储接口 packages/core/wenyi_core/storage/protocol.py，两条路径各注入一个适配器：

• CLI 路径：本地适配器组合文件 + SQLite，状态落在state/<书>/targets/<语言>/目录；
• Web 路径：apps/api/wenyi_api/storage_pg.py 注入PostgresStorage，项目、章节、段落、术语、审校记录全部进 PostgreSQL。

对新手来说这意味着什么？换入口不需要换"大脑"——术语一致性、批次检查点、断点续跑这些能力在两个入口下是同一份代码提供的。

CLI 入口：一条命令翻译整本书

CLI 由 packages/cli/wenyi_cli/cli.py 装配，wenyi_cli/commands/ 目录下按职责注册了工作流、检查、术语等命令组。典型用法：

uv run wenyi prepare book.epub # 解析、分析、预扫 uv run wenyi translate book.epub # 翻译，可中断后原命令续跑 uv run wenyi review book.epub # 独立全书审校

翻译主流程由 packages/core/wenyi_core/pipeline/orchestrator.py 的Orchestrator统一路由：它是个"薄门面"，只负责装配服务和步骤顺序，具体解析、模型调用、状态读写都下沉到领域服务。每个翻译批次完成即落盘，中断后重跑同一命令自动跳过已完成批次——这就是续跑能力在 CLI 侧的体现。

Web 与 Worker：浏览器只是遥控器

Web 端（React + Vite 前端在 apps/web/）本身不做翻译，它做的事只有两件事：调用 API、通过 WebSocket 看进度。真正干活的是两个独立的后台 Worker（Arq + Redis 队列）：

• worker监听wenyi:workflows队列：解析、准备、翻译、审校、SRT 字幕；
• export-worker监听wenyi:exports队列：从一致性快照做导出，可与翻译并行。

两个队列的定义见 apps/api/wenyi_api/workers/init.py，任务实现集中在 apps/api/wenyi_api/workers/tasks.py。注意max_jobs = 1：翻译这类长任务同一项目串行执行，避免并发写状态。

Worker 还内置了一个恢复循环：每 30 秒检查排队/运行中超过 2 分钟无更新的任务，确认孤儿后把项目标记为paused，浏览器点"继续"即可从原任务类型和已存进度接着跑。翻译过程在页面里是实时可见的——

快速上手：按这份地图读源码

想动手改代码？按任务查对应入口，比通读仓库高效得多（完整约束见 AGENTS.md）：

小结

Wenyi 架构的核心思路可以压缩成一句话：把翻译内核做成一个"不知道自己在哪运行"的纯领域库，CLI 用文件状态、Web 用数据库、Worker 用队列调度，三者只是给同一台发动机换了不同的传动轴。这种设计让命令行用户、浏览器用户和自托管部署者共享同一套翻译质量能力，也是长文本翻译项目里非常值得借鉴的分层方式。

【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyi