dowafu 0.1.0 → 0.3.0

package/dist/cli-args.js

@@ -7,27 +7,7 @@
 // 完整用法（原僅一行）。
 import { DispatchError } from "./types.js";
 import { getCommandName } from "./pkg-info.js";
-export const HELP_TEXT = `用法：${getCommandName()} <ticket-dir> [options]
-
-  --repo-root <dir>        白名單邊界與 .claude/agents 的根，預設 cwd
-  --providers <path>       整檔取代出貨的 providers.json
-  --json                   stdout 只印結果 JSON，其餘輸出改走 stderr
-  --out <dir>              落檔目錄，預設 tmp/spoke/
-  --concurrency <n>        同時執行的 spoke 數，預設 2
-  --max-tokens <n>         呼叫前估算閘門（各 spoke 初始 prompt 總和），預設 200000
-  --max-spoke-tokens <n>   單一 spoke 執行期累積上限（實際 usage），預設 400000
-  --timeout <sec>          單次 API 呼叫逾時（不是整支 spoke），預設 600
-  --retries <n>            單輪呼叫的重試次數（僅暫時性錯誤），預設 2
-  --chars-per-token <n>    閘門一估算係數，預設 1.0（可由 providers.json 逐家覆寫）
-  --max-spoke-reasoning-tokens <n>  單一 spoke 的推理 token 累積上限，預設 50000
-  --max-round-reasoning-tokens <n>  單輪推理 token 上限，預設 null（不檢查）
-  --rate-limit-retries <n> 429 專用重試次數，預設 5（不計入 --retries）
-  --max-rate-wait <sec>    單次 429 等待上限，預設 30
-  --max-tool-calls <n>     單一 spoke 的 read_file 呼叫上限，預設 30
-  --dry-run                解析、驗證、估算、印報表，不呼叫 API
-  --yes                    略過派工確認。非互動環境（stdin 不是 TTY）沒帶就中止
-  --help, -h               印本說明後結束（exit 0）
-  --version, -V            印版本號後結束（exit 0）`;
+import { m } from "./messages.js";
 const DEFAULTS = {
     out: "tmp/spoke",
     concurrency: 2,
@@ -50,7 +30,58 @@ const DEFAULTS = {
     dryRun: false,
     yes: false,
 };
-export function parseArgs(argv) {
+// plan_i18n_v1.3.md §二之1：--lang 與 DISPATCH_LANG 走同一個判定函式，接受 en／zh-tw／zh，
+// 大小寫不敏感、trim。不共用的話會出現「同一個值放旗標有效、放環境變數無效」這種依媒介
+// 分裂的邊界，是最難查的那種不一致。
+export function parseLang(value) {
+    const v = value.trim().toLowerCase();
+    if (v === "en")
+        return "en";
+    if (v === "zh-tw" || v === "zh")
+        return "zh";
+    return null;
+}
+// plan_i18n_impl_tickets T3：resolveLang 之前，還有一段訊息需要語言——parseArgs 自己的
+// 解析期錯誤、以及 resolveLang 判定失敗時它自己要拋的那兩則訊息。這段時序裡還沒有
+// 「權威語言」可用（--lang 可能就是壞的那個值，資格未定；resolveLang 本身還沒跑完，
+// 不能拿它自己會拋例外的回傳值來決定拋例外訊息用什麼語言）。
+//
+// v1.2 §1.3／§3.2：這類訊息一律走「DISPATCH_LANG 有效就用它，否則用內建預設 en」——
+// 不查 --lang（它在這個時間點的有效性正是問題本身），也不會拋例外。cli.ts 在
+// registerSecrets／loadDispatchEnv 之後、parseArgs 之前算好這個值，一併傳給 parseArgs
+// 與用於 --help 本身的輸出；resolveLang 內部對它自己的兩則錯誤訊息也重用同一函式。
+export function resolveFallbackLang(envLangRaw) {
+    const trimmed = (envLangRaw ?? "").trim();
+    if (!trimmed)
+        return "en";
+    return parseLang(trimmed) ?? "en";
+}
+// plan_i18n_v1.3.md §二之2：--lang 與 DISPATCH_LANG 的完整組合表（九項）。
+// 呼叫時機：parseArgs 之後、help／version 短路之後——在此之前不得驗證語言。
+export function resolveLang(cliLangRaw, envLangRaw) {
+    const envTrimmed = (envLangRaw ?? "").trim();
+    const envIsSet = envTrimmed.length > 0; // #7：空字串／全空白視為「未設定」，不是無效
+    const envParsed = envIsSet ? parseLang(envTrimmed) : null;
+    const msgLang = resolveFallbackLang(envLangRaw);
+    if (cliLangRaw !== undefined) {
+        const cliParsed = parseLang(cliLangRaw);
+        if (cliParsed !== null)
+            return cliParsed; // #1：旗標有效，不驗 DISPATCH_LANG
+        // #4：旗標無效——一併指出 env 是否也無效，避免使用者修好旗標後才撞到 env 又是壞的。
+        const envNote = envIsSet && envParsed === null ? m(msgLang, "invalidEnvAlsoNote", envLangRaw) : "";
+        throw new DispatchError(m(msgLang, "invalidLangFlag", cliLangRaw, m(msgLang, "availableValuesSuffix", m(msgLang, "availableLangValues")), envNote), 2);
+    }
+    if (!envIsSet)
+        return "en"; // #7：未設定 → 內建預設
+    if (envParsed !== null)
+        return envParsed; // #2
+    // #3：DISPATCH_LANG 無效且沒有有效 --lang——訊息須指名是環境變數，不是旗標。
+    throw new DispatchError(m(msgLang, "invalidEnvLang", envLangRaw, m(msgLang, "availableValuesSuffix", m(msgLang, "availableLangValues"))), 2);
+}
+// plan_i18n_impl_tickets T3：lang 是「訊息語言」，即 resolveFallbackLang 算出的那個值
+// （見上方說明）——parseArgs 這個階段權威語言尚未確定，不是 run-level lang。
+export function parseArgs(argv, lang) {
+    const helpText = m(lang, "helpText", getCommandName());
     // --help／--version 可出現在任何位置，且優先於其他一切解析——不要求先有 ticketDir。
     if (argv.includes("--help") || argv.includes("-h"))
         return { mode: "help" };
@@ -62,7 +93,7 @@ export function parseArgs(argv) {
         flagHandlers[name] = (v) => {
             const n = Number(v);
             if (!Number.isFinite(n))
-                throw new DispatchError(`--${name} 需要數字，收到：${v}`, 2);
+                throw new DispatchError(m(lang, "numberFlagInvalid", name, v), 2);
             apply(n);
         };
     };
@@ -70,6 +101,10 @@ export function parseArgs(argv) {
     flagHandlers["out"] = (v) => (options.out = v);
     flagHandlers["repo-root"] = (v) => (options.repoRoot = v);
     flagHandlers["providers"] = (v) => (options.providersPath = v);
+    // 這裡只存原始字串，不驗證格式——格式與 DISPATCH_LANG 的組合判定需要 process.env，
+    // parseArgs 是純函式不碰它，交給 cli.ts 呼叫 resolveLang（見下）。重複帶 --lang 時
+    // 最後一次覆蓋前一次，與其他旗標一致（v1.3 §二之2 #8）。
+    flagHandlers["lang"] = (v) => (options.langRaw = v);
     numFlag("concurrency", (n) => (options.concurrency = n));
     numFlag("max-tokens", (n) => (options.maxTokens = n));
     numFlag("max-spoke-tokens", (n) => (options.maxSpokeTokens = n));
@@ -96,10 +131,13 @@ export function parseArgs(argv) {
             const name = arg.slice(2);
             const handler = flagHandlers[name];
             if (!handler)
-                throw new DispatchError(`未知選項：${arg}\n\n${HELP_TEXT}`, 2);
+                throw new DispatchError(m(lang, "unknownOption", arg, helpText), 2);
             const value = argv[++i];
-            if (value === undefined)
-                throw new DispatchError(`--${name} 缺少值`, 2);
+            if (value === undefined) {
+                // v1.3 §二之2 #9：--lang 缺值時沿用既有的「缺少值」措辭，額外列出可用值。
+                const suffix = name === "lang" ? m(lang, "availableValuesSuffix", m(lang, "availableLangValues")) : "";
+                throw new DispatchError(m(lang, "missingFlagValue", name, suffix), 2);
+            }
             handler(value);
         }
         else if (ticketDir === undefined) {
@@ -108,31 +146,43 @@ export function parseArgs(argv) {
         else {
             // v1.10 §9：多餘的 positional 原本被靜默忽略（`hub-dispatch a b` 只跑 a），
             // 與設計原則 2（fail closed）不一致，改為中止。
-            throw new DispatchError(`多餘的引數：${arg}（工單目錄已是 "${ticketDir}"）\n\n${HELP_TEXT}`, 2);
+            throw new DispatchError(m(lang, "tooManyArgs", arg, ticketDir, helpText), 2);
         }
     }
     if (!ticketDir) {
-        throw new DispatchError(HELP_TEXT, 2);
+        throw new DispatchError(helpText, 2);
     }
     return { mode: "run", ticketDir, options };
 }
-export function formatEvent(event) {
+// plan_i18n_impl_tickets T3：跟 run-level lang，不是 env lang——這是執行中的即時輸出，
+// 此時 resolveLang 早已成功、cli.ts 手上有權威值，直接傳進來即可，不必再猜語言。
+export function formatEvent(event, lang) {
     switch (event.type) {
         case "spoke_start":
-            return `[${event.agent}] 開始 → ${event.provider}/${event.model}`;
+            return m(lang, "eventSpokeStart", event.agent, event.provider, event.model);
         case "round":
+            // 此則純 ASCII（round／usage／toolCalls 皆非中文），兩語言逐字相同，不必經 messages.ts。
             return `[${event.agent}] round ${event.round} usage=${JSON.stringify(event.usage)} toolCalls=${event.hasToolCalls}`;
         case "unknown_usage_keys":
-            return `[${event.agent}] ⚠ round ${event.round} 出現未知 usage 欄位：${event.keys.join(", ")}`;
+            return m(lang, "eventUnknownUsageKeys", event.agent, event.round, event.keys.join(", "));
         case "tool_call":
-            return `[${event.agent}] read_file(${event.path}) ${event.allowed ? "允許" : `拒絕(${event.reason})`}`;
+            return m(lang, "eventToolCall", event.agent, event.path, event.allowed, event.reason);
         case "rate_limit_wait":
-            return `[${event.agent}] 429，等待 ${event.seconds}s（來源：${event.source}）`;
+            return m(lang, "eventRateLimitWait", event.agent, event.seconds, event.source);
         case "round_error":
-            return `[${event.agent}] ⚠ round ${event.round} 錯誤 status=${event.status ?? "—"}：${event.message}`;
-        case "spoke_end":
-            return (`[${event.agent}] 結束 status=${event.status} latency=${event.latencyMs}ms totalTokens=${event.totalTokens}` +
-                ` cost=${event.costUsd === null ? "無價目資料" : `$${event.costUsd.toFixed(4)}`}` +
-                (event.budgetTrigger ? ` budgetTrigger=${event.budgetTrigger}` : ""));
+            return m(lang, "eventRoundError", event.agent, event.round, String(event.status ?? "—"), event.message);
+        case "spoke_end": {
+            const costLabel = event.costUsd === null ? m(lang, "noPricingData") : `$${event.costUsd.toFixed(4)}`;
+            const budgetSuffix = event.budgetTrigger ? ` budgetTrigger=${event.budgetTrigger}` : "";
+            return m(lang, "eventSpokeEnd", event.agent, event.status, event.latencyMs, event.totalTokens, costLabel, budgetSuffix);
+        }
     }
 }
+// plan_i18n_impl_tickets T3b：moved out of cli.ts（原本是該檔的私有函式）。cli.ts 底部有
+// `main().catch()` 的無條件呼叫，import 它會直接跑掉整支程式（見檔頭說明）——這支函式本身
+// 純函式、不含 I/O，搬來這裡才有安全的方式可以單元測試，不必 spawn 子行程。
+export function buildStdoutSummary(results, lang) {
+    return results
+        .map((r) => m(lang, "stdoutSummaryLine", r.agent, r.status, r.modelReturned ?? "—", r.usage.totalTokens, r.costUsd === null ? m(lang, "noPricingData") : `$${r.costUsd.toFixed(4)}`, r.latencyMs))
+        .join("\n");
+}

package/dist/cli.js

@@ -19,19 +19,21 @@ import { createGeminiAdapter } from "./adapters/gemini-native.js";
 import { createAnthropicAdapter } from "./adapters/anthropic-messages.js";
 import { auditSpoke } from "./audit.js";
 import { auditToolCalls } from "./tool-call-audit.js";
-import { ensureOutDir, persistSpokeResult, RunLogWriter, writeSummary } from "./output.js";
+import { ensureOutDir, outDirHasArtifacts, persistSpokeResult, RunLogWriter, writeSummary } from "./output.js";
 import { registerSecrets, maskString, maskDeep } from "./mask.js";
 import { SECRET_ENV_VARS } from "./secret-env.js";
 import { resolveDispatchHome, loadDispatchEnv } from "./dispatch-home.js";
-import { bundledProvidersPath, getPackageVersion } from "./pkg-info.js";
+import { bundledProvidersPath, getPackageVersion, getCommandName } from "./pkg-info.js";
 import { checkGitignore } from "./gitignore-check.js";
 import { buildJsonPayload, buildJsonPlan } from "./json-output.js";
-import { parseArgs, formatEvent, HELP_TEXT } from "./cli-args.js";
+import { parseArgs, formatEvent, resolveLang, resolveFallbackLang, buildStdoutSummary } from "./cli-args.js";
+import { m } from "./messages.js";
 function createAdapterFor(spoke) {
     const apiKey = process.env[`${spoke.provider.toUpperCase()}_API_KEY`];
     if (!apiKey) {
-        // resolveSpokes 已檢查過，此處為型別窄化防禦
-        throw new DispatchError(`內部錯誤：${spoke.provider} 的 API key 遺失`, 2);
+        // resolveSpokes 已檢查過，此處為型別窄化防禦。用 spoke.lang 而非 langRaw／options.lang——
+        // 它是 ResolvedSpoke 上已經過 resolveLang 判定的權威值，與 run-level lang 同一個來源。
+        throw new DispatchError(m(spoke.lang, "apiKeyMissing", spoke.provider), 2);
     }
     // §29 規格十：窮盡式分派，不留「其餘落到 gemini」的 fallback——那會讓未來第四家 provider
     // 靜默走錯 adapter。switch 缺 case 時 TypeScript 因「不是每條路徑都回傳值」編譯失敗。
@@ -42,14 +44,16 @@ function createAdapterFor(spoke) {
                 apiKey,
                 store: spoke.providerConfig.store,
                 reasoning: spoke.providerConfig.reasoning,
+                lang: spoke.lang,
             });
         case "gemini-native":
-            return createGeminiAdapter({ apiKey, baseURL: spoke.providerConfig.baseURL });
+            return createGeminiAdapter({ apiKey, baseURL: spoke.providerConfig.baseURL, lang: spoke.lang });
         case "anthropic-messages":
             return createAnthropicAdapter({
                 baseURL: spoke.providerConfig.baseURL,
                 apiKey,
                 reasoning: spoke.providerConfig.reasoning,
+                lang: spoke.lang,
             });
     }
 }
@@ -68,9 +72,22 @@ async function confirm(message, output) {
     return answer.trim().toLowerCase() === "y";
 }
 async function main() {
-    const parsed = parseArgs(process.argv.slice(2));
+    // plan_i18n_v1.3.md §三：DISPATCH_HOME → .env → secrets 全部搬到 parseArgs 之前，
+    // 因為這段現在跑在 --help 之前，任何會拋的東西都會擋住求助路徑——resolveDispatchHome／
+    // loadDispatchEnv 內部已各自降級失敗為「沒有設定檔」。§24.4：明文禁止讀 cwd 的 .env，
+    // 故不用 `import "dotenv/config"`（那會讀 cwd），改為明確指定 dispatchHome 下的路徑。
+    const dispatchHome = resolveDispatchHome();
+    if (dispatchHome !== null)
+        loadDispatchEnv(dispatchHome);
+    registerSecrets(SECRET_ENV_VARS.map((k) => process.env[k]));
+    // plan_i18n_impl_tickets T3：parseArgs 自己的解析期錯誤、以及 --help 本身的輸出，都發生在
+    // resolveLang 判定出權威語言之前——這裡只能用「DISPATCH_LANG 有效就用它，否則內建預設 en」
+    // 這個不會拋例外的簡化判定（resolveFallbackLang，見 cli-args.ts）。--lang 旗標的值在這個
+    // 時間點還沒被驗證，不查它（v1.3 §二之2 #5／#6：help／version 的語言不受 --lang 影響）。
+    const messageLang = resolveFallbackLang(process.env.DISPATCH_LANG);
+    const parsed = parseArgs(process.argv.slice(2), messageLang);
     if (parsed.mode === "help") {
-        console.log(HELP_TEXT);
+        console.log(m(messageLang, "helpText", getCommandName()));
         return;
     }
     if (parsed.mode === "version") {
@@ -79,27 +96,28 @@ async function main() {
     }
     const { ticketDir, options } = parsed;
     const log = makeLogger(options.json);
-    // §10 步驟 0：設定解析——DISPATCH_HOME → .env → providers 來源 → formatVersion。
-    // 全部在任何 API 呼叫之前，成本為零。§24.4：明文禁止讀 cwd 的 .env，故不用
-    // `import "dotenv/config"`（那會讀 cwd），改為明確指定 dispatchHome 下的路徑。
-    const dispatchHome = resolveDispatchHome();
-    loadDispatchEnv(dispatchHome);
-    registerSecrets(SECRET_ENV_VARS.map((k) => process.env[k]));
+    // plan_i18n_v1.3.md §二：--lang > DISPATCH_LANG > 內建預設，含九項組合判定
+    // （fail closed，無效值 exit 2）。help／version 已在上面短路，不會走到這裡。
+    //
+    // T1 驗收帶出的第一條（T3 執行）：語言的權威來源只有這行的回傳值。CLI 層訊息一律用
+    // 這個 lang，不得讀 options.langRaw——後者是未經 parseLang 驗證的原始字串，可能是
+    // undefined 或未正規化的 "ZH-TW"，誤用會靜默走中文分支且 typecheck 不會紅。
+    const lang = resolveLang(options.langRaw, process.env.DISPATCH_LANG);
     // v1.10 §9：--repo-root 只影響白名單邊界、.claude/agents 位置、_docs/ 拒絕判定；
     // 工單目錄仍相對 cwd 解析，不要求位於 repoRoot 內（見 resolveSpokes 呼叫處）。
     const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
     const ticketId = path.basename(path.resolve(ticketDir));
     // §10 步驟 1–2：工單解析＋允許清單存在性（loadTicket／resolveSpokes 內部 fail closed）
-    const ticket = await loadTicket(ticketDir);
+    const ticket = await loadTicket(ticketDir, lang);
     // §10 步驟 3／v1.10 §24.3：providers.json 隨工具出貨、不可覆寫（方案 D）；
     // --providers 是唯一逃生口，整檔取代，一樣過 formatVersion 檢查。
     const providersPath = options.providersPath ? path.resolve(options.providersPath) : bundledProvidersPath();
     const providersSource = options.providersPath
         ? { kind: "explicit", path: providersPath, formatVersion: PROVIDERS_FORMAT_VERSION }
         : { kind: "bundled", formatVersion: PROVIDERS_FORMAT_VERSION };
-    const providers = await loadProviders(providersPath);
+    const providers = await loadProviders(providersPath, lang);
     // §10 步驟 4–5：effort 值域、API key 齊備、models 白名單（resolveSpokes 內部）
-    const spokes = await resolveSpokes(ticket, providers, repoRoot);
+    const spokes = await resolveSpokes(ticket, providers, repoRoot, lang);
     // §10 步驟 6／§14 閘門一：呼叫前估算
     const estimates = spokes.map((spoke) => {
         const systemPrompt = buildSystemPrompt(spoke.agentBody, spoke.lang);
@@ -110,7 +128,7 @@ async function main() {
             estimatedTokens: estimateTokens(systemPrompt, charsPerToken) + estimateTokens(firstUserText, charsPerToken),
         };
     });
-    checkGateOne(estimates, options.maxTokens);
+    checkGateOne(estimates, options.maxTokens, lang);
     // plan_dispatch_v2.0.md §14：允許清單總量估算，獨立於閘門一之外，只呈現不設閘門
     // （閘門一不含允許清單內容，見 gate.ts 的說明）。與 estimates 同一模式：算一次，
     // 報表與 --json plan 共用，不重複讀檔。
@@ -142,25 +160,30 @@ async function main() {
         exitCode,
     });
     // §10 步驟 7／§11：派工報表
-    const report = buildReport(ticketId, spokes, estimates, allowlistEstimates, options, outDir, {
-        repoRoot,
-        providersSource,
-        gitignoreStatus,
-    });
+    const report = buildReport(ticketId, spokes, estimates, allowlistEstimates, options, outDir, { repoRoot, providersSource, gitignoreStatus }, lang);
     log.info(report);
+    // 護欄的預告：乾跑不受影響（它不寫任何東西），但先講，免得實跑才發現被擋。
+    const outDirDirty = await outDirHasArtifacts(outDir);
     if (options.dryRun) {
-        log.info("\n--dry-run：僅解析／驗證／估算／印報表，未呼叫任何 API。");
+        if (outDirDirty)
+            log.info("\n" + m(lang, "outDirNotEmptyDryRunWarning", outDir));
+        log.info("\n" + m(lang, "dryRunNotice"));
         if (options.json) {
             console.log(JSON.stringify(maskDeep(buildPayload("dry-run", [], new Map(), new Map(), 0))));
         }
         return;
     }
+    // 擋在 confirm 之前：不要先問「要不要花錢」再中止。exitCode 5 是「派工前被守則擋下、
+    // 未花任何錢」，與 3（成本閘門超限）分開，才分得出是哪一種擋。
+    // **刻意不提供 --overwrite 之類的旗標**：有旗標，「加上去」就會變成最便宜的滿足方式，
+    // 那正是 --yes 已經示範過的路。要覆蓋，由使用者自己清掉目錄。
+    if (outDirDirty) {
+        throw new DispatchError(m(lang, "outDirNotEmptyAbort", outDir), 5);
+    }
     if (!options.yes) {
-        const ok = await confirm("繼續？[y/N] ", options.json ? process.stderr : process.stdout);
+        const ok = await confirm(m(lang, "confirmPrompt"), options.json ? process.stderr : process.stdout);
         if (!ok) {
-            log.info(process.stdin.isTTY
-                ? "已取消，未呼叫任何 API。"
-                : "非互動環境（stdin 不是 TTY）無人可確認，已取消，未呼叫任何 API。要在此環境派工請明確加上 --yes。");
+            log.info(process.stdin.isTTY ? m(lang, "cancelledInteractive") : m(lang, "cancelledNonInteractive"));
             if (options.json) {
                 console.log(JSON.stringify(maskDeep(buildPayload("cancelled", [], new Map(), new Map(), 0))));
             }
@@ -173,13 +196,13 @@ async function main() {
     }
     catch (err) {
         outDirReady = false;
-        console.error(`落檔目錄不可寫：${outDir}`);
+        console.error(m(lang, "outDirNotWritable", outDir));
         console.error(maskString(String(err)));
     }
-    const runLog = outDirReady ? new RunLogWriter(path.join(outDir, "run.jsonl")) : null;
+    const runLog = outDirReady ? new RunLogWriter(path.join(outDir, "run.jsonl"), lang) : null;
     const semaphore = new Semaphore(options.concurrency);
     const onEvent = (event) => {
-        log.info(formatEvent(event));
+        log.info(formatEvent(event, lang));
         runLog?.append(event);
     };
     // §10 步驟 8：信號量控制發起，Promise.allSettled 只負責收尾
@@ -204,7 +227,7 @@ async function main() {
             // §13（一）：每支 spoke 完成即落檔，不等 Promise.allSettled——多 spoke 並行、
             // 其中一支慢很多時，快的那支已付費的產出不因慢的還在跑而暴露在中斷風險下。
             if (outDirReady) {
-                await persistSpokeResult(outDir, result, (msg) => console.error(msg));
+                await persistSpokeResult(outDir, result, (msg) => console.error(msg), lang);
             }
             return result;
         }
@@ -263,16 +286,16 @@ async function main() {
     // rejected 分支的兜底——真實 result 重寫一次是冪等的（writeFile 覆蓋）。
     if (outDirReady) {
         for (const r of results) {
-            await persistSpokeResult(outDir, r, (msg) => console.error(msg));
+            await persistSpokeResult(outDir, r, (msg) => console.error(msg), lang);
         }
-        await writeSummary(outDir, ticketId, results, audits, toolCallAudits);
+        await writeSummary(outDir, ticketId, results, audits, toolCallAudits, lang);
         await runLog?.flush();
-        log.info(`\n落檔完成：${outDir}/`);
+        log.info("\n" + m(lang, "outDirWritten", outDir));
     }
     else {
         // 落檔目錄不可寫時，不讓已付費的結果消失——完整結果改印到 stderr（json 模式下
         // stdout 仍須維持只有最後那個單一 JSON 物件的契約，不能把這份診斷用資料混進去）。
-        log.info("\n落檔目錄不可寫，完整報告已改印於 stderr：");
+        log.info("\n" + m(lang, "outDirFallbackStderr"));
         console.error(JSON.stringify(maskDeep(results), null, 2));
     }
     const allFailed = results.every((r) => r.status === "failed");
@@ -284,15 +307,9 @@ async function main() {
         console.log(JSON.stringify(maskDeep(buildPayload("executed", results, audits, toolCallAudits, exitCode))));
     }
     else {
-        log.info("\n" + buildStdoutSummary(results));
+        log.info("\n" + buildStdoutSummary(results, lang));
     }
 }
-function buildStdoutSummary(results) {
-    return results
-        .map((r) => `${r.agent}: ${r.status}  model=${r.modelReturned ?? "—"}  token=${r.usage.totalTokens}  ` +
-        `cost=${r.costUsd === null ? "無價目資料" : `$${r.costUsd.toFixed(4)}`}  耗時=${r.latencyMs}ms`)
-        .join("\n");
-}
 main().catch((err) => {
     if (err instanceof DispatchError) {
         console.error(maskString(err.message));

package/dist/dispatch-home.js

@@ -9,15 +9,33 @@
 import dotenv from "dotenv";
 import os from "node:os";
 import path from "node:path";
+// plan_i18n_v1.3.md §三：這兩個函式現在跑在 parseArgs／--help 之前（見 cli.ts），任何
+// 會拋的東西都會擋住求助路徑。因此各自包 try/catch，任何例外都降級為「沒有設定檔」，
+// 不中止、不拋——包括 os.homedir() 在無 HOME／無 passwd 對應時拋錯。
 export function resolveDispatchHome(env = process.env, homedir = os.homedir) {
-    if (env.DISPATCH_HOME)
-        return env.DISPATCH_HOME;
-    if (env.XDG_CONFIG_HOME)
-        return path.join(env.XDG_CONFIG_HOME, "dispatch");
-    return path.join(homedir(), ".config", "dispatch");
+    try {
+        if (env.DISPATCH_HOME)
+            return env.DISPATCH_HOME;
+        // v0.2.0：目錄名與 CLI 同名（`dowafu`），原本叫 `dispatch`。**不做舊路徑回退**
+        // （乙案已否決）——回退那段程式碼一旦寫下就永遠刪不掉，而它要處理的是一次性的搬家。
+        // 代價是搬家沒做完時 loadDispatchEnv 靜默降級（見下方註解），症狀要到派工當下才出現，
+        // 所以 impl_tickets 的順序是「先複製目錄、再改這兩行」。
+        if (env.XDG_CONFIG_HOME)
+            return path.join(env.XDG_CONFIG_HOME, "dowafu");
+        return path.join(homedir(), ".config", "dowafu");
+    }
+    catch {
+        return null;
+    }
 }
 // 唯一允許呼叫 dotenv 的地方——`path` 一律明確指定為 dispatchHome 下的 `.env`，
 // 絕不留白（留白即回退成 dotenv 預設讀 cwd 的 `.env`，正是本函式存在的目的所要杜絕的）。
+// 維持 `void` 簽名：讀取失敗一律降級為「沒有設定檔」（見上方註解），呼叫端不需要狀態。
 export function loadDispatchEnv(dispatchHome) {
-    dotenv.config({ path: path.join(dispatchHome, ".env") });
+    try {
+        dotenv.config({ path: path.join(dispatchHome, ".env") });
+    }
+    catch {
+        // .env 是目錄／無讀取權限／內容畸形等，全部降級，不中止、不拋。
+    }
 }

package/dist/gate.js

@@ -3,6 +3,7 @@
 // 此檢查在任何 API 呼叫之前，成本為零。
 import fs from "node:fs";
 import { DispatchError } from "./types.js";
+import { m } from "./messages.js";
 // §14：charsPerToken 預設 1.0（不是 chars/4）——實測 chars/4 對中文系統性低估 2.7–4 倍，
 // 低估比高估危險，此閘門寧可誤報。providers.json 可逐家覆寫（見 cli.ts 呼叫端）。
 function estimateTokensFromChars(chars, charsPerToken) {
@@ -27,11 +28,11 @@ export function estimateSequentialRead(filePaths, charsPerToken) {
         sorted: amplify([...sizes].sort((a, b) => a - b)),
     };
 }
-export function checkGateOne(estimates, maxTokens) {
+export function checkGateOne(estimates, maxTokens, lang) {
     const total = estimates.reduce((sum, e) => sum + e.estimatedTokens, 0);
     if (total > maxTokens) {
         const detail = estimates.map((e) => `  ${e.agent}: ${e.estimatedTokens}`).join("\n");
-        throw new DispatchError(`閘門一超限：合計初始估算 ${total} tokens 超過 --max-tokens ${maxTokens}\n${detail}`, 3);
+        throw new DispatchError(m(lang, "gateOneExceeded", total, maxTokens, detail), 3);
     }
     return total;
 }

package/dist/mask.js

@@ -44,15 +44,28 @@ export function maskDeep(value) {
     }
     return value;
 }
+// 序列化失敗一律降級為固定字串，不再往上拋——呼叫端（describeError）的職責是「把錯誤描述
+// 出來」，它自己不能因為描述不出來而變成第二個錯誤。回傳值仍經 maskString，因為
+// 不可序列化的物件其 toString 也可能帶出秘密。
+function safeStringify(value) {
+    try {
+        return maskString(JSON.stringify(value));
+    }
+    catch {
+        return "[unserializable error body]";
+    }
+}
 export function describeError(err) {
     if (err && typeof err === "object") {
         const anyErr = err;
         const status = typeof anyErr.status === "number" ? anyErr.status : undefined;
         const headers = maskHeaders(anyErr.headers);
         const message = typeof anyErr.message === "string" ? maskString(anyErr.message) : undefined;
-        const errorBody = anyErr.error && typeof anyErr.error === "object"
-            ? { message: maskString(JSON.stringify(anyErr.error)) }
-            : undefined;
+        // issue_log_v2.5.md 待修 #10：JSON.stringify 遇 BigInt 會拋 TypeError、遇循環引用同樣拋，
+        // 而 runSpoke 沒有包住這條路徑——遮蔽層自己拋錯的下場是整支 spoke 落到 allSettled 的防禦
+        // 分支：status failed，而且**那次錯誤本身不會被記錄**，因為記錄它正是這個函式的工作。
+        // 序列化不了就退回型別描述，不得讓遮蔽層成為新的失敗來源。
+        const errorBody = anyErr.error && typeof anyErr.error === "object" ? { message: safeStringify(anyErr.error) } : undefined;
         return {
             status,
             is429: status === 429,