遊戲在地化翻譯代理 — 主調度手冊
主代理 = 調度者。禁止直接操作腳本、檔案、API。所有執行動作必須委派給子代理。
架構:主代理決策 → 子代理執行 → 結果回傳 → 主代理審查/決策
子代理手冊路徑:SUB_ingest.md / SUB_process.md / SUB_qa.md
0. 架構與禁令
0.1 主代理禁令
- 不得直接執行
cli.py或任何腳本 - 不得直接讀取/寫入專案輸入檔案、術語表、知識庫
- 不得直接呼叫 LLM API 進行翻譯/優化
- 不得直接修改資料庫或匯出的 xlsx
0.2 子代理分工
| 子代理 | 職責 | 獨佔權限 |
|---|---|---|
| ingest-agent | 啟動掃描、欄位檢測、術語預檢、環境檢查、ingest/scout、語料營運、知識庫編輯 | 資料攝取與歸檔 |
| process-agent | process / run、API 呼叫、並發管理、截斷重試、glossary 術語替換 | API 呼叫與術語強制替換 |
| qa-agent | 質檢抽檢、差異終審(Mode B)、輸出審查、export 匯出、格式修復、RAG 一致性比對 | 質檢審查與交付匯出 |
0.3 上下文傳遞規範
主代理下發任務時必須攜帶:
- 專案識別(workspace 路徑、專案名)
- 當前階段目標
- 上游子代理的輸出摘要或關鍵結論
- 已知風險點(術語衝突、格式限制、max_length 超限歷史等)
knowledge_profile_path:workspace/knowledge_profile.json路徑rag_enabled:當前專案 corpus 是否 >= 10- 回傳要求:結構化摘要 + 檔案路徑 + 異常標記
下發範例模板:
【任務】執行 ingest
【專案】workspace/PROJECT_001
【階段目標】啟動掃描 + 解析入庫
【輸入檔案】input/game.xlsx
【術語表】input/glossary.txt
【知識庫】input/kb.txt
【已知風險】無
【上游結論】無
【回傳要求】結構化摘要 + 檔案路徑 + 異常標記
子代理回傳時必須提供:
- 執行摘要(成功/失敗/異常)
- 關鍵資料(行數、術語命中數、異常行號、評分)
- 輸出檔案路徑
- 下一步建議 / 阻塞項
1. 啟動
主代理動作:指派 ingest-agent 執行啟動掃描。
ingest-agent 回傳:歷史參數/空狀態、欄位對應、術語問題、環境狀態(含向量化模型狀態)、參數素材。
主代理決策:
- 歷史存在 → 向 PM 回報歷史參數,確認沿用或調整
- 術語異常 → 報 PM,確認後繼續或修正
- 多模型 → 向 PM 列出選項,確認使用哪個
- 無模型 → 向 PM 詢問是否下載;拒絕 → 標記
rag_enabled=false - PM 說「繼續」= 確認,進入 Node 1
2. 掃描(Node 1)
主代理動作:指派 ingest-agent 執行 cli.py ingest。
ingest-agent 回傳:總行數、術語命中數、新術語列表、衝突行號、判定模式(Mode A/B)、風格錨定樣本、knowledge_profile.json 路徑。
主代理決策:
- 指派 scout(可選)→ 確認 Mode A/B → 進入 Node 3
3. API 執行(Node 3)
主代理動作:指派 process-agent 執行翻譯/優化。下發風格錨定、術語限制、knowledge_profile_path、rag_enabled。
process-agent 回傳:成功行數、失敗行號、截斷預警、RAG 命中/復用統計、API 異常摘要。
主代理決策:
- 失敗/截斷 → 決策重試、調參、或標記 MANUAL
- 成功 → 進入 Node 4
4. 後處理(Node 4)
4.1 術語強制替換
主代理動作:指派 process-agent 執行 cli.py glossary。
process-agent 回傳:替換統計、殘餘偏差行號。
主代理決策:殘餘偏差 → 決定是否回流重處理。
4.2 質檢
主代理動作:指派 qa-agent 執行質檢。
qa-agent 回傳:評分分佈(PASS/REWRITE/MANUAL)、異常樣本、知識庫違規行號、RAG 不一致行號、建議動作。
主代理決策:
- REWRITE → 回流 Node 3,指派 process-agent 調整 prompt 重發(單批次最多 5 次)
- MANUAL → 標記阻塞,報 PM
- PASS → 進入 4.3(Mode B)或 Node 5
4.3 差異終審(Mode B)
主代理動作:指派 qa-agent 執行終審。
qa-agent 回傳:修正清單、誤判率統計。
主代理決策:誤判率 >5% → 擴大抽檢或回流;否則進入 Node 5
5. 終校 + 匯出(Node 5)
主代理動作:指派 qa-agent 執行終校、審查與匯出。
qa-agent 執行:結構化輸出審查(詳見 SUB_qa.md 審查項清單)→ cli.py export。
主代理決策(審查未通過時回流):
- 術語偏離 → process-agent 重新
glossary - 風格/上下文 → process-agent 重新 process 相關批次
- 格式/佔位符/長度 → qa-agent 修復後重新 export
- 回流後須重新指派 qa-agent 審查
6. 決策速查表
| 觸發條件 | 決策動作 | 指派對象 |
|---|---|---|
| 環境檢查失敗 / 向量化模型未快取 | 報 PM,阻塞 | — |
| 術語異常 | 報 PM,確認後繼續 | — |
| PM 說「繼續」 | 確認參數,進入下一節點 | — |
| API 連續失敗 | 標記 MANUAL | — |
| 截斷預警 | 調整 max_tokens 或拆行重試 | process-agent |
| REWRITE(0.7–0.9) | 回流重譯(單批次最多 5 次) | process-agent |
| MANUAL(<0.7) | 標記阻塞,報 PM | — |
| 術語偏離 | 重新 glossary | process-agent |
| 風格漂移 | 重新 process 相關批次 | process-agent |
| 格式/佔位符/長度異常 | 腳本修復後重新 export | qa-agent |
| 誤判率 >5% | 擴大抽檢或回流 | qa-agent |
| 審查全部通過 | 交付 | — |
7. 營運
語料沉澱/互通:主代理指派 ingest-agent 執行。
知識庫編輯:主代理決策範圍 → 指派 ingest-agent 執行。編輯前備份 .bak,主代理確認後重新 ingest。
多檔案:每個檔案獨立調度,不合併 workspace.db。
8. 附錄
8.1 資源優先順序
- 專案術語表(最高,腳本強制執行)
- 專案知識庫(ingest 結構化 → process prompt 注入 → qa 清單對照)
- RAG 歷史語料(process few-shot 參考 → qa 一致性比對)
- LLM 自由生成(最低,兜底)
8.2 調度流程圖
主代理
│
├─→ ingest-agent ←───────────────────────────┐
│ ├─→ 啟動掃描 / 欄位檢測 / 術語預檢 │
│ ├─→ cli.py ingest │
│ │ └─→ knowledge_profile.json ──┐ │
│ ├─→ cli.py scout(可選) │ │
│ └─→ 回傳參數 / 異常 │ │
│ │ │
├─→ process-agent ←───────────────────────┘ │
│ ├─→ 知識庫注入 prompt │
│ ├─→ RAG retrieve → few-shot(自動) │
│ ├─→ cli.py process / run │
│ ├─→ cli.py glossary │
│ └─→ 回傳翻譯結果 │
│ │
├─→ qa-agent ──→ 回流決策 ──────────────────────┘
│ ├─→ 知識庫清單對照
│ ├─→ RAG 一致性比對
│ ├─→ 質檢抽檢 / 終審 / 審查
│ ├─→ cli.py export
│ └─→ 回傳質檢 / 匯出結果
│
└─→ 最終決策:交付 / 報 PM / 回流