DSH-game-translate

中文 | English

DSH-game-translate 是基于 DeepSeek Harness (dsh) 构建的可视化本地游戏汉化插件。全部插件代码与资源均独立维护于本目录，无需修改上游 game-translation 核心或宿主 Harness 源码。

在工作目录的根对话中输入 /翻译 即可唤出独立的原生翻译窗口：窗口专注于目录选择、章节分组阅读、双栏对照与单句手改微调；底层的资产解包、翻译任务派发、质量审校及独立副本写回则由主对话 Agent 协同内置的 game-translation Skill 与 Core 自动完成。

本插件充分利用了 DeepSeek Harness（基于 Cordis）的插件化运行时能力，将游戏汉化拆解为职责清晰的三层协同机制：

• 原生可视化窗口（浏览、点选与微调）：提供游戏目录选择、智能阅读分组切换、原文/译文双栏等高对照与悬停手改功能，以独立非置顶窗口运行，不阻塞主聊天窗口的正常交互。
• DSH 主/子 Agent 调度（翻译编排与多模型并发）：主对话 Agent 负责工程初始化、上下文审校与最终封装指令；批量翻译既可由主 Agent 直接完成，也可通过 DSH 原生子 Agent（内置等待机制与防重复派发保护）委托给其他外部模型并发处理，无需在 Skill 内重复造轮子。
• 确定性汉化核心（Python Core & Skill）：底层无缝驱动 game-translation Core，完整保留真实的 Entry / Task / Scene 状态机、占位符与术语校验、译文草稿修订版本，并在原游戏保持只读的流程下生成独立汉化副本、执行逐字段读回核验。

核心功能与交互

1. 智能阅读分组与脚本片段定位

• 自适应章节聚合：告别零碎的原始 Scene 列表，插件会按文件来源、事件及显式章节/路线边界自动组织相邻 Scene。在完整保留原 Scene 的前提下，默认以约 140 段 / 6000 原文字符为软容量，并根据游戏规模尝试收敛至 60 组以内；保留来源与分支边界优先，不保证所有游戏都能压到这一数量。
• 展开定位与无损映射：组内清晰标出原始脚本标签与分支片段（如 80:*number_of_days、标签片段 · 10 段），支持一键展开定位，不强行推断线性剧情；底层的原 Scene / Task ID、译文修订号与写回索引完全不变。勾选阅读组发起翻译后，Host 会自动解析真实成员并分批交给 Agent 处理。

2. 双栏等高对照与零 Token 即时手改

• 沉浸式剧本排版：说话人自然内联至台词前方，旁白独立成段；原文（只读）与译文双栏严格按同一 Task 等高对齐、共用滚动区，未译侧自动留白对齐。
• 丝滑悬停手改体验：译文正文、右侧空隙与铅笔按钮纳入同一悬停热区，鼠标移入时平滑淡入并轻微上浮，移出后等待 160ms 再淡出（支持中途移回反向续接，并遵循系统“减少动态效果”设置）；同时完整保留双击选择与复制文字功能。
• 直连 Core 即时校验保存：点击铅笔进入编辑态后，可直接修改译文或切换修改说话人译名（存在未保存输入时会自动拦截切换并提示先保存或取消）。按 Ctrl+Enter 保存、Esc 取消；保存操作通过宿主通信通道调用底层 Core 进行占位符与规则校验，不调用大模型、零 Token 消耗。若检测到不兼容的旧版窗口，会自动保留编辑内容并提示更新。

3. DSH 原生子 Agent 与多协议模型接入

• 四大主流接口协议：支持在设置面板中新增或编辑专用翻译模型，原生兼容 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 与 Gemini generateContent（API 输入框使用中性焦点边框并自动清理首尾空格）。
• 凭据安全托管：API Key 交由 DSH credentials 服务保存，不存入浏览器 localStorage、模型配置 JSON 或插件的命令参数日志；是否加密落盘取决于所用 DSH 凭据后端。
• 诊断降噪与分页报告：状态与目录查询默认返回精简摘要（支持按需查看完整诊断），构建与核验报告支持单独分页读取，保持主对话上下文干净高效。

4. Windows 原生独立窗口与定制玻璃材质

• 自然窗口层级与复用：在 Windows 下采用普通非置顶、无 DSH 主窗口强绑定的原生独立窗口，保留 DSH 图标与视觉材质，点击其他窗口时按正常 Windows 窗口顺序切换；原生文件夹选择器则以翻译窗口作为模态 owner。同一对话限时复用窗口，关闭窗口不会取消后台已派发的 Agent 任务（非 Windows 网页入口自动沿用浏览器弹窗 / 浮窗）。
• WPF / DWM 玻璃与纯白双材质：底层材质交由独立的 WPF / DWM 路径渲染（默认参数：乳白 5%、柔光 15%、边缘反光 100%、高光范围 100%、阅读区白度 20%），设置中开放乳白与柔光无级调节。支持纯白 / 玻璃两种风格无缝切换，统一了阅读区留白、边框与滚动条占位，切换材质时保持相同的正文布局与换行规则。
• 排版持久化与细节打磨：字体、字号、行距、栏宽比例及材质设置自动持久化；设置下拉菜单支持再次点击收起、外部点击与 Esc 关闭、方向键选择及连续进退场过渡；内置正文缓存与合并刷新机制。

五步快速上手

1. 安装插件：安装发布包 dsh-game-translate-<version>.tgz。若当前有未保存输入请先复制备份，随后完全退出并重启目标 DSH profile（付费账户与主模型直接沿用你自己的 DSH 设置）。
2. 打开窗口与选择游戏：在工作目录根对话输入 /翻译 唤出翻译窗口，点击右上角 ••• → 选择游戏目录…，由原生翻译窗口直接打开 Windows 文件夹对话框。
3. 初始化解包：点击「初始化」并确认额度提醒，处理进度与报错信息可在原聊天窗口查看。成功绑定根会话后初始化按钮自动禁用防重；若中途失败会保留现场产物，修复后可直接重试。
4. 勾选翻译与审校微调：点击「翻译…」勾选待处理的阅读组，选择由主 Agent 翻译，或调度 DSH 原生子 Agent 使用其他模型翻译。完成后窗口自动更新已保存译文，可随时双栏审阅或点击铅笔手改。
5. 封装写回独立副本：核对完成后点击「封装写回…」选择输出路径并确认，主 Agent 将调用 Skill / Core 创建全新独立游戏副本，并自动完成读回核验。

完整安装步骤、模型配置与问题排查方法详见 使用说明。

支持的游戏引擎速览

本插件内置 game-translation Core，包含以下 6 大游戏引擎家族的提取、审查、翻译与写回适配路线。可选工具和依赖需按游戏另行配置；这里列的是实现范围，不表示所有版本、格式或实际游戏均已验收。

引擎家族	已实现的提取与写回能力	边界情况与 Agent 辅助项
RPG Maker (XP / VX / VX Ace / MV / MZ)	• MV / MZ：读写数据库 JSON、系统文本与事件脚本，完整保留控制码。 • XP / VX / VX Ace：读写 Ruby Marshal 数据；支持 Game.rgssad / Game.rgss2a / Game.rgss3a 加密归档自动解密脱壳并重构为免加密独立副本。	插件私有硬编码文本、动态拼接对白及图片文字需个案适配；输出副本直接使用解包资源运行。
WOLF RPG Editor (绿狼引擎)	• 集成 UberWolfCli 与 WolfTL 可选后端，自动解包 .wolf 密态归档。 • 基于 WolfTL 的结构化导出提取剧情对白、说话人与分支选项，在编码可写时写回输出副本。	魔改加密变体、图片文字与未知编码需个案处理；中文显示需在游戏内配置中文字体，实际加载与显示需验证。
Unity (表格 / 序列化资产 / 代码字符串)	• 明文与内嵌表格：识别 StreamingAssets 与无扩展名 TextAsset 中的 JSON、CSV、TSV、TXT、XML，保持原编码与 BOM。 • 序列化资产：按需通过 UnityPy 读写 TextAsset、StringTable、TMP 文本、Fungus 及 Utage 剧情书。 • 代码字符串：支持 IL2CPP global-metadata.dat（v29）与 Mono Assembly-CSharp.dll（ldstr）改写，支持 Addressables 本地 Bundle 同步与字体替换。	剥离类型树（Stripped TypeTree）的商业游戏需配合 TypeTreeGeneratorAPI；Addressables 远程包与多处共享的代码字面量索引需人工确认。
Ren'Py (视觉小说引擎)	• 读取松散 .rpy 脚本、.rpa 归档与 .rpyc 编译脚本（集成 unrpa / unrpyc）。 • 按官方翻译 ID 提取，在输出副本中生成标准 game/tl/<language>/ 原生多语言覆写脚本。	混淆脚本与动态拼接文本需 Agent 辅助分析；默认不改动原剧本，通过原生多语言层加载；显式使用 SDK 备用路线时会执行工作副本的项目初始化。
TyranoScript (Web / Electron 视觉小说)	• 提取松散工程或标准 Electron app.asar 容器中的 .ks 剧本。 • 按脚本标签分组提取对白、说话人及 text 参数，写回原有形式的输出资源，ASAR 工程重构 ASAR，并从输出归档读回。	复杂 JS 动态逻辑与自定义宏需单独适配；若 EXE 对 ASAR 带有完整性哈希校验，当前构建会停止，由 Agent 调查实际加载关系；插件不会自动关闭校验或改为松散加载。
Godot Engine (3.x / 4.x 封包与场景)	• 集成 GDRETools 读写 .pck 容器与 EXE 内嵌 GDPC 包，支持明确选择关联启动入口。 • 支持场景节点属性、PO 文件，以及 OptimizedTranslation 编译型二进制多语言表的哈希桶定位与 UTF-8 缓冲区无损写回。	脚本内动态构造的未注册字符串需先经候选审查；多包加载优先级或特殊外壳需 Agent 辅助研判。

工程结构与运行环境

环境与构建要求

• 运行环境：Windows 原生窗口面向 x64，需要 .NET Framework 4.8 与 WebView2 Runtime；目标适配 DSH 0.2.1-rc.3 / Cordis ~4.0.5 / Node.js 24.9+ / Python 3.10+（其他版本尚未验收）。
• 开箱即用：发行包 dsh-game-translate-<version>.tgz 已预编译包含前端 UI，安装后无需再次编译。本地开发调试可执行 npm ci 与 npm run build。

目录与模块划分

src/
  index.js                插件 Host 入口（会话绑定、命令注册、阅读组映射与通信）
  models.js               外部翻译模型适配层（OpenAI / Anthropic / Gemini 四协议）
  delegation.js           DSH 原生子 Agent 任务派发、等待与防重控制
  client/                 翻译窗口前端 UI 源码（发行入口为 dist/client.js）
python/
  bridge.py               Python Worker 通信入口
  operations.py           插件操作、会话范围与 Core 调用
  vendor/                 固定版本的 game-translation Core 及引擎参考文档
skills/
  game-translation/       配套 Agent 技能规范与各引擎/宿主参考文档
native/wpf/               Windows 窗口、材质和本地通信宿主
docs/                     安装使用说明

验证边界与发行说明

• 验证边界：四大模型协议采用本地模拟响应测试，子任务委托采用模拟 DSH 子任务验证；底层 Core 使用独立样例游戏完成真实解包、提交、写回与读回核验；前端 UI 通过离屏浏览器检查，Windows 原生宿主通过无窗口自检通道验证。上述自动检查未使用真实 API Key、未调用付费模型或自动启动游戏。实际 DSH 环境下的视觉表现、窗口切换、真实模型服务商连通性及游戏实机运行效果由用户实测确认。
• 安装与打包范围：升级前请保存未提交输入并备份重要配置；保持原有 dataDirectory，以继续使用已有绑定和译文。发行包包含预编译 UI 与 Windows 宿主，不包含可选引擎工具、Python 解释器或 WebView2 Runtime。公开文件排除 node_modules、research、测试产物、模型设置、API 凭据以及个人游戏与聊天记录。
• 第三方开源声明：本项目涉及的第三方组件与许可证信息详见 THIRD_PARTY_NOTICES.md。