From 51e51efd2a0f50ac18663bdf38340aa4d1988bbf Mon Sep 17 00:00:00 2001 From: Leon Date: Thu, 25 Jun 2026 19:24:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9ECLAUDE.md=E8=BF=90?= =?UTF-8?q?=E7=BB=B4=E6=8C=87=E5=8D=97=EF=BC=8C=E5=90=AB=E5=AE=A2=E6=88=B7?= =?UTF-8?q?=E6=9C=8D=E5=8A=A1=E5=99=A8=E6=9B=B4=E6=96=B0=E6=AD=A5=E9=AA=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 客户服务器git pull+重启标准流程 - DashScope API Key IP绑定说明 - MT vs 通用模型选型建议 - 共享术语表/数据目录说明 - 本分支相对原项目的关键改动 Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c736f3b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,85 @@ +# DocuTranslate（华宝/langcore 分支）运维指南 + +本仓库 fork 自 [xunbu/docutranslate](https://github.com/xunbu/docutranslate)，已针对华宝（印尼烟厂）的中文/英文/印尼语三语文档翻译场景定制。 + +## Git 仓库 + +- **远程地址**：`https://git.langcore.net/Leon/docutranslate` +- **账号**：leon@langcore.cn +- **默认分支**：`main`（所有修改提交到 main 并推送） + +## 客户服务器更新步骤 + +客户服务器运行在 Windows 上，部署路径 `C:\Users\langcore3\Desktop\doctranslate\docutranslate`，对外地址 `http://172.16.100.246:8010/`。 + +```powershell +# 1. 进入项目目录 +cd C:\Users\langcore3\Desktop\doctranslate\docutranslate + +# 2. 拉取最新代码 +git pull + +# 3. 确认已拉到目标提交 +git log --oneline -1 + +# 4. 重启服务（先 Ctrl+C 停掉当前运行的 uv run docutranslate，再启动） +uv run docutranslate -i --host 0.0.0.0 +``` + +> `--host 0.0.0.0` 是必须的，否则服务只监听 127.0.0.1，局域网其他设备无法访问（这是常见的"外部访问不到"原因）。 + +### 启动后验证 + +```powershell +# 健康检查（应返回版本号） +python -c "import urllib.request,json; print(urllib.request.urlopen('http://127.0.0.1:8010/service/meta').read().decode())" + +# 共享术语表（应返回 {"rows":[...]}） +python -c "import urllib.request,json; print(urllib.request.urlopen('http://127.0.0.1:8010/service/glossary').read().decode())" +``` + +浏览器侧：访问 `http://172.16.100.246:8010/` 后 **Ctrl+Shift+R 硬刷新**，清除旧的 JS/CSS/JSON 缓存。 + +## 翻译 API 配置 + +`.env` 文件（项目根目录，**不入 git**）配置 LLM 凭证： + +```env +DOCUTRANSLATE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1 +DOCUTRANSLATE_API_KEY=<阿里云 DashScope Key> +DOCUTRANSLATE_MODEL_ID=qwen3.6-plus # 或 qwen-mt-plus +DOCUTRANSLATE_RPM= +DOCUTRANSLATE_TPM= +``` + +- **DashScope API Key 受 IP/账号绑定**：在客户服务器上可用的 Key，从开发机或命令行测试可能返回 401（这是正常的，不是 Key 失效）。只在客户服务器上验证 Key。 +- **qwen-mt-plus（MT 模型）**：会破坏所有文本分隔符/JSON 结构，只能逐条翻译，速度慢（616 段 ~14 分钟）。推荐用 **qwen3.6-plus**（通用大模型，JSON 批处理，~1 分钟）。 +- **RPM/TPM 留空**：非 MT 模型不需要限流。 + +## 关键数据目录 + +- `data/glossary.json` — 全公司共享三语术语表（运行时生成，已 gitignore，各服务器独立存储） +- `docutranslate/output/` — 翻译输出临时目录（已 gitignore） +- `.env` — API 凭证（已 gitignore） + +## 本地开发 + +```bash +# 开发模式启动（仅本机访问，默认端口 8010） +uv sync +uv run docutranslate -i +``` + +本地可用的测试 LLM（智谱 GLM，与 DevScope 项目共用 Key）： +```env +DOCUTRANSLATE_BASE_URL=https://open.bigmodel.cn/api/paas/v4 +DOCUTRANSLATE_API_KEY=9a0a338f1ef346f293733201b96335cd.Guv1hBOyqopJHOjh +DOCUTRANSLATE_MODEL_ID=glm-4-flash +``` + +## 本分支相对原项目的关键改动 + +- **共享三语术语表**（中/英/印尼）：`glossary/glossary_store.py` + `glossary/lang_mapping.py` + `GET/POST /service/glossary`，全公司共享、保存即生效、默认引用。 +- **MT 模型逐条翻译**：`segments_agent.py` 对 qwen-mt-* 模型改用纯文本逐条发送（MT 模型会破坏批处理分隔符）。 +- **docx 格式保留**：`docx_translator.py` 段落级翻译 + 合并同格式 Run，Run 保留率从 3.8% 提升到 ~100%。 +- **多语言 UI**：中文/English/Bahasa Indonesia（替换原越南语），浏览器语言自动检测。