【背景与目标】Unity 工程的语言表此前靠人工翻译再逐格粘贴:5 张表、7600 余个 key、15 种目标语言,约 11.4 万个格子。改一处中文要人工回忆哪些语言已过期,漏翻、错翻、术语不统一反复出现,一轮全量核对要 1~2 天。目标是把语言表维护变成「机器人扫描、人只确认」:只处理新增或中文改动的格子,由大模型按术语表和语言风格翻译,写回 Excel 并提交 Git,策划在飞书群里点一次确认即可。
【核心功能模块】①配置层 profiles:每工程一份,声明表路径、sheet、key/源语言/目标语言列、术语表与风格文件,接新项目只加一份配置;②增量引擎 langtool.py:用 state 基线对比出待译格子,生成计划、批量调用翻译后端,写回前做表结构校验与已译合规体检;③飞书卡片 Agent:长连接收事件,按「项目+群」排队,发项目菜单卡、计划卡、明细卡、状态卡,支持定时扫描(默认 23:00)和群内 @机器人 手动触发,48 小时未确认自动作废刷灰;④写回与安全层:Excel COM 写入 + 整表备份 + 跨进程写锁互斥 + Git 只提交目标表;⑤运维层 ops:控制面一键启动、状态、看门狗计划任务与两套自测。
【业务流程与功能路径】群里 @机器人 或到点自动扫描 → 选项目 → 出计划卡(勾选目标语言、切换 Codex/DeepSeek 引擎、看待译样例与条数)→ 点确认 → 自动备份、翻译、写表、Git 提交与推送 → 状态卡回填结果,可翻页看明细、失败一键重试。策划和测试只需在群里操作,值班排障走命令行与排障树;多群按项目隔离权限,写表类按钮限发起人。
【整体架构】单机常驻 Python 进程,不开入站端口,飞书走长连接事件回调。Agent 只做交互与编排,翻译和写表下沉到 langtool.py 子进程,两者通过任务队列、结果 JSON 与 state 基线交接,进程间用文件写锁互斥。分层:飞书协议适配(feishu_ws.py)→ 卡片构建(超体积时按 variants 逐级降级)→ 任务队列与状态机(排队/执行中/成功/部分成功/需人工/已作废)→ 翻译与写表内核 → Git 与备份 → 审计日志。技术栈:Python 3.13 + openpyxl + Excel COM(win32com)+ Codex CLI 与 DeepSeek 内网中转双后端 + 飞书开放平台卡片 2.0 + PowerShell 计划任务。
【我负责的模块与结果】独立完成全部模块与文档:Agent 7018 行、翻译与写表内核 2754 行、写锁与长连接适配 394 行;两套自测脚本 1.3 万行、约 1800 个断言调用点,配 31 项验收场景和 13 节值班排障树。已接入 3 个工程、5 张表、7600 余个 key × 15 种语言(约 11.4 万格),只翻新增/中文改动格,一轮例行核对从人工 1~2 天降到分钟级;每次写表前生成整表备份并按表保留最新 10 份,可回滚。
【难点与解决方案】①上游网关关闭 chat/completions(一律 403):改为本地 codex exec 子进程调用并加 --ignore-user-config 隔离个人配置,实测单发 30~80 秒、并发 2 稳定,另建 DeepSeek 通道按卡切换、参数建卡时冻结;②Excel COM 只能在已登录的交互式桌面会话运行,无法注册成 Windows 服务:改用计划任务 + VBS 隐藏窗口拉起,停止时忙则拒绝、强制需确认;③飞书卡片 2.0 多选组件字段写成 selected 报 200621,必须用 selected_values,且 form 必须带 submit 按钮;④增量正确性依赖基线,state 必须随机器迁移,否则会退化成全表重翻;⑤权限:来源群、卡片消息、参数哈希、群成员四道校验,再加「写表/改任务/推送按钮只有发起人能点」,多群按项目隔离,同一项目出现在两个群时启动直接拦截;⑥Git 安全:只提交目标 Excel,不 amend、不 force push、只用 --ff-only 快进,回滚只复制备份,禁用 checkout/reset/stash。