@foxden-app/foxclaw 0.7.3 → 0.11.0

package/dist/telegram/api.js

@@ -4,7 +4,30 @@ import https from 'node:https';
 import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 const DEFAULT_API_BASE_URL = 'https://api.telegram.org';
-export async function callTelegramApi(botToken, method, body) {
+export function isTransientNetworkError(err) {
+    if (!err)
+        return false;
+    const msg = String(err.message || err).toLowerCase();
+    return (msg.includes('client network socket disconnected') ||
+        msg.includes('econnreset') ||
+        msg.includes('etimedout') ||
+        msg.includes('eai_again') ||
+        msg.includes('enotfound') ||
+        msg.includes('econnrefused') ||
+        msg.includes('socket hang up') ||
+        msg.includes('timed out') ||
+        msg.includes('timeout') ||
+        msg.includes('network socket disconnected') ||
+        msg.includes('network error') ||
+        msg.includes('fetch failed') ||
+        msg.includes('und_err_') ||
+        msg.includes('read tcp') ||
+        msg.includes('connection timed out') ||
+        msg.includes('broken pipe') ||
+        msg.includes('ehostunreach') ||
+        msg.includes('enetunreach'));
+}
+function callTelegramApiOnce(botToken, method, body) {
     const payload = JSON.stringify(body);
     const endpoint = telegramApiUrl(botToken, method);
     return new Promise((resolve, reject) => {
@@ -39,7 +62,25 @@ export async function callTelegramApi(botToken, method, body) {
         request.end();
     });
 }
-export async function callTelegramMultipartApi(botToken, method, fields, files) {
+export async function callTelegramApi(botToken, method, body) {
+    const maxAttempts = method === 'getUpdates' ? 1 : 4;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await callTelegramApiOnce(botToken, method, body);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < maxAttempts && isTransientNetworkError(err)) {
+                await new Promise((r) => setTimeout(r, Math.min(3000, 500 * Math.pow(2, attempt - 1))));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
+function callTelegramMultipartApiOnce(botToken, method, fields, files) {
     const boundary = `foxclaw-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
     const parts = [];
     for (const [name, value] of Object.entries(fields)) {
@@ -85,6 +126,24 @@ export async function callTelegramMultipartApi(botToken, method, fields, files)
         request.end();
     });
 }
+export async function callTelegramMultipartApi(botToken, method, fields, files) {
+    const maxAttempts = 3;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await callTelegramMultipartApiOnce(botToken, method, fields, files);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < maxAttempts && isTransientNetworkError(err)) {
+                await new Promise((r) => setTimeout(r, Math.min(3000, 500 * Math.pow(2, attempt - 1))));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
 export async function getTelegramFile(botToken, fileId) {
     const result = await callTelegramApi(botToken, 'getFile', { file_id: fileId });
     if (!result.ok || !result.result) {
@@ -92,7 +151,7 @@ export async function getTelegramFile(botToken, fileId) {
     }
     return result.result;
 }
-export async function downloadTelegramFile(botToken, remoteFilePath, destinationPath) {
+async function downloadTelegramFileOnce(botToken, remoteFilePath, destinationPath) {
     await fs.promises.mkdir(path.dirname(destinationPath), { recursive: true });
     const tempPath = `${destinationPath}.tmp-${process.pid}-${Date.now()}`;
     let response = null;
@@ -129,6 +188,24 @@ export async function downloadTelegramFile(botToken, remoteFilePath, destination
         response?.destroy();
     }
 }
+export async function downloadTelegramFile(botToken, remoteFilePath, destinationPath) {
+    const maxAttempts = 3;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await downloadTelegramFileOnce(botToken, remoteFilePath, destinationPath);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < maxAttempts && isTransientNetworkError(err)) {
+                await new Promise((r) => setTimeout(r, Math.min(3000, 500 * Math.pow(2, attempt - 1))));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}
 function escapeMultipartName(value) {
     return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\r', '').replaceAll('\n', '');
 }

package/dist/telegram/bot_home.js

@@ -5,16 +5,17 @@ const ID_FILE = '.foxclaw-bot.json';
 export function prepareTelegramBotHome(baseDir, botId, username, sharedHome = null) {
     if (!/^bot\d+$/.test(botId))
         throw new Error('Invalid Telegram bot identity');
-    if (username !== null && !/^[A-Za-z0-9_]{1,64}$/.test(username))
+    const normalizedUsername = username ? username.replace(/^@/, '') : null;
+    if (normalizedUsername !== null && !/^[A-Za-z0-9_]{1,64}$/.test(normalizedUsername))
         throw new Error('Invalid Telegram username for directory');
-    const base = path.resolve(baseDir);
-    fs.mkdirSync(base, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(baseDir, { recursive: true, mode: 0o700 });
+    const base = fs.realpathSync(path.resolve(baseDir));
     const legacy = path.join(base, botId);
     const legacyStat = lstat(legacy);
     const source = legacyStat?.isSymbolicLink() ? fs.realpathSync(legacy) : legacy;
     if (path.dirname(source) !== base)
         throw new Error(`Bot directory points outside its storage root: ${legacy}`);
-    const target = username ? path.join(base, `@${username}`) : source;
+    const target = normalizedUsername ? path.join(base, `@${normalizedUsername}`) : source;
     const sourceStat = lstat(source);
     const targetStat = lstat(target);
     if (sourceStat && !sourceStat.isDirectory())

package/dist/telegram/gateway.d.ts

@@ -100,6 +100,10 @@ export declare class TelegramGateway extends EventEmitter {
     downloadResolvedFile(remoteFilePath: string, destinationPath: string): Promise<number>;
     private resolveBotIdentity;
     private registerCommands;
+    setChatCommands(chatId: number | string, commands: Array<{
+        command: string;
+        description: string;
+    }>): Promise<void>;
     private pollLoop;
     private handleUpdate;
     private isAllowedChat;

package/dist/telegram/gateway.js

@@ -248,6 +248,17 @@ export class TelegramGateway extends EventEmitter {
             language_code: 'zh',
         });
     }
+    async setChatCommands(chatId, commands) {
+        try {
+            await callTelegramApi(this.botToken, 'setMyCommands', {
+                commands,
+                scope: { type: 'chat', chat_id: chatId },
+            });
+        }
+        catch (err) {
+            this.logger.warn('telegram.set_chat_commands_failed', { chatId, error: String(err) });
+        }
+    }
     async pollLoop() {
         let remoteInitialized = false;
         while (this.running) {

package/dist/types.d.ts

@@ -23,6 +23,7 @@ export interface ChatSessionSettings {
     collaborationMode: CollaborationModeValue | null;
     serviceTier: string | null;
     activeTurnMessageMode: ActiveTurnMessageMode | null;
+    activeBackendId?: string | null;
     updatedAt: number;
 }
 export type QueuedTurnInputStatus = 'queued' | 'processing' | 'completed' | 'cancelled' | 'failed';
@@ -402,7 +403,9 @@ export interface RuntimeStatus {
         activeTurns: number;
         runtimeKind?: 'default' | 'isolated';
         currentAuth?: string | null;
+        defaultBackend?: 'codex' | 'antigravity';
         codexHome?: string | null;
+        antigravityHome?: string | null;
         codexAppServer?: RuntimeStatus['codexAppServer'];
     }>;
     weixinRuntime?: {

package/dist/update.d.ts

@@ -12,6 +12,9 @@ export interface SelfUpdateStatus {
     codexUpdate?: string | null;
     codexFromVersion?: string | null;
     codexToVersion?: string | null;
+    agyUpdate?: string | null;
+    agyFromVersion?: string | null;
+    agyToVersion?: string | null;
     error: string | null;
     updatedAt: string;
 }
@@ -34,6 +37,7 @@ interface CreateSelfUpdateRuntimeOptions {
     statusPath: string;
     logPath: string;
     codexCliBin?: string;
+    agyCliBin?: string;
     pendingTimeoutMs?: number;
     now?: () => Date;
 }
@@ -44,6 +48,7 @@ interface PerformSelfUpdateOptions {
     notificationFile?: string;
     clusterBroadcastFile?: string;
     codexCliBin?: string;
+    agyCliBin?: string;
     env?: NodeJS.ProcessEnv;
 }
 export interface SelfUpdateLaunchCommand {
@@ -77,6 +82,7 @@ export declare function buildSelfUpdateLaunchCommand(options: {
     statusFile: string;
     logPath: string;
     codexCliBin?: string;
+    agyCliBin?: string;
     env?: NodeJS.ProcessEnv;
     platform?: NodeJS.Platform;
     systemdRunPath?: string | null;

package/dist/update.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import process from 'node:process';
 import { spawn, spawnSync } from 'node:child_process';
 const PACKAGE_SPEC = '@foxden-app/foxclaw@latest';
@@ -32,7 +33,23 @@ export function inferPnpmFallbackPackageFromEntryPoint(entryPoint) {
     return 'pnpm@latest';
 }
 export function resolveSelfUpdateInstaller(entryPoint, nodePath = process.execPath, exists = fs.existsSync, env = process.env) {
-    const pnpmHome = inferPnpmHomeFromEntryPoint(entryPoint);
+    let pnpmHome = inferPnpmHomeFromEntryPoint(entryPoint);
+    const normalizedEntryPoint = entryPoint.replace(/\\/g, '/');
+    const isExplicitNpm = normalizedEntryPoint.includes('/node_modules/@foxden-app/foxclaw/')
+        && !normalizedEntryPoint.includes('/.pnpm/')
+        && !normalizedEntryPoint.includes('/global/');
+    if (!pnpmHome && !isExplicitNpm) {
+        const candidatePnpmHome = env.PNPM_HOME?.trim() || (process.platform === 'win32'
+            ? (env.LOCALAPPDATA ? path.join(env.LOCALAPPDATA, 'pnpm') : null)
+            : path.join(os.homedir(), '.local', 'share', 'pnpm'));
+        if (candidatePnpmHome && exists(candidatePnpmHome)) {
+            const foxclawBin = path.join(candidatePnpmHome, process.platform === 'win32' ? 'foxclaw.cmd' : 'foxclaw');
+            const globalDir = path.join(candidatePnpmHome, 'global');
+            if (exists(foxclawBin) || exists(globalDir)) {
+                pnpmHome = candidatePnpmHome;
+            }
+        }
+    }
     if (pnpmHome) {
         const npmCommandName = process.platform === 'win32' ? 'npm.cmd' : 'npm';
         const npmCommand = executableCandidates(npmCommandName, nodePath, env)
@@ -203,6 +220,7 @@ export function createSelfUpdateRuntime(options) {
                     statusFile,
                     logPath: options.logPath,
                     ...(options.codexCliBin ? { codexCliBin: options.codexCliBin } : {}),
+                    ...(options.agyCliBin ? { agyCliBin: options.agyCliBin } : {}),
                 });
                 if (launch.viaSystemdRun) {
                     const result = spawnSync(launch.command, launch.args, {
@@ -237,6 +255,9 @@ export function createSelfUpdateRuntime(options) {
                     codexUpdate: null,
                     codexFromVersion: null,
                     codexToVersion: null,
+                    agyUpdate: null,
+                    agyFromVersion: null,
+                    agyToVersion: null,
                     error: formatError(error),
                     updatedAt: new Date().toISOString(),
                 });
@@ -255,9 +276,11 @@ export function createSelfUpdateRuntime(options) {
     };
 }
 export function buildSelfUpdateLaunchCommand(options) {
-    const env = options.codexCliBin
-        ? { ...(options.env ?? process.env), CODEX_CLI_BIN: options.codexCliBin }
-        : { ...(options.env ?? process.env) };
+    const env = { ...(options.env ?? process.env) };
+    if (options.codexCliBin)
+        env.CODEX_CLI_BIN = options.codexCliBin;
+    if (options.agyCliBin)
+        env.AGY_CLI_BIN = options.agyCliBin;
     const updateArgs = [options.entryPoint, 'update', '--notification-file', options.statusFile];
     const platform = options.platform ?? process.platform;
     const systemdRunPath = options.systemdRunPath === undefined
@@ -292,9 +315,12 @@ export function performSelfUpdate(options) {
     const env = options.env ?? process.env;
     let toVersion = null;
     let codexUpdate = null;
+    let agyUpdate = null;
     try {
         codexUpdate = updateManagedCodexCli(options.codexCliBin ?? env.CODEX_CLI_BIN ?? '', options.nodePath, env);
         console.log(`[UPDATE] ${codexUpdate.message}`);
+        agyUpdate = updateManagedAgyCli(options.agyCliBin ?? env.AGY_CLI_BIN ?? '', env);
+        console.log(`[UPDATE] ${agyUpdate.message}`);
         const installer = resolveSelfUpdateInstaller(options.entryPoint, options.nodePath, fs.existsSync, env);
         const installerEnv = buildInstallerEnv(options.entryPoint, installer, env);
         console.log(`[UPDATE] Installing ${PACKAGE_SPEC} with ${installer.manager}...`);
@@ -304,7 +330,7 @@ export function performSelfUpdate(options) {
         const releaseNotes = readInstalledReleaseNotes(updatedEntryPoint, toVersion, options.notificationFile);
         console.log('[UPDATE] Running checks and restarting the FoxClaw service...');
         runInherited(options.nodePath, [updatedEntryPoint, 'start'], installerEnv);
-        completeNotification(options.notificationFile, 'succeeded', toVersion, codexUpdate, null, releaseNotes);
+        completeNotification(options.notificationFile, 'succeeded', toVersion, codexUpdate, null, releaseNotes, agyUpdate);
         if (options.clusterBroadcastFile && env.FOXCLAW_SUPPRESS_UPDATE_BROADCAST !== '1') {
             writePendingClusterUpdateBroadcast(options.clusterBroadcastFile, {
                 targetVersion: toVersion,
@@ -322,7 +348,7 @@ export function performSelfUpdate(options) {
     }
     catch (error) {
         const message = formatError(error);
-        completeNotification(options.notificationFile, 'failed', toVersion, codexUpdate, message, null);
+        completeNotification(options.notificationFile, 'failed', toVersion, codexUpdate, message, null, agyUpdate);
         console.error(`[FAIL] FoxClaw update failed: ${message}`);
         return {
             ok: false,
@@ -407,6 +433,65 @@ function readCodexCliVersion(codexCliBin, env) {
 function parseCodexCliVersion(output) {
     return output.match(/\b\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?\b/)?.[0] ?? null;
 }
+function updateManagedAgyCli(agyCliBin, env) {
+    const candidateBins = [
+        agyCliBin,
+        resolveCommand('agy', env),
+        path.join(os.homedir(), '.local', 'bin', 'agy'),
+        '/usr/local/bin/agy',
+    ].filter(Boolean);
+    const resolved = candidateBins.find((c) => c && fs.existsSync(c));
+    if (!resolved) {
+        return {
+            message: 'Antigravity CLI (agy) update skipped: agy binary not found.',
+            fromVersion: null,
+            toVersion: null,
+        };
+    }
+    const fromVersion = readAgyCliVersion(resolved, env);
+    try {
+        const res = spawnSync(resolved, ['update'], { encoding: 'utf8', env });
+        const toVersion = readAgyCliVersion(resolved, env) ?? fromVersion;
+        const stdout = (res.stdout || '').trim();
+        if (stdout.includes('already on the latest')) {
+            return {
+                message: `Antigravity CLI (agy): already on latest version (${toVersion || fromVersion || 'latest'}).`,
+                fromVersion,
+                toVersion,
+            };
+        }
+        if (fromVersion && toVersion && fromVersion !== toVersion) {
+            return {
+                message: `Antigravity CLI (agy) updated: ${fromVersion} -> ${toVersion}.`,
+                fromVersion,
+                toVersion,
+            };
+        }
+        return {
+            message: stdout || `Antigravity CLI (agy) checked: ${toVersion || fromVersion || 'ok'}.`,
+            fromVersion,
+            toVersion,
+        };
+    }
+    catch (error) {
+        return {
+            message: `Antigravity CLI (agy) update failed without blocking FoxClaw update: ${formatError(error)}`,
+            fromVersion,
+            toVersion: readAgyCliVersion(resolved, env) ?? fromVersion,
+        };
+    }
+}
+function readAgyCliVersion(agyCliBin, env) {
+    try {
+        const result = spawnSync(agyCliBin, ['--version'], { encoding: 'utf8', env });
+        if (result.error || result.status !== 0)
+            return null;
+        return (result.stdout || '').trim().match(/\b\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?\b/)?.[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 function executableCandidates(commandName, nodePath, env, preferred = []) {
     return [
         ...preferred,
@@ -590,7 +675,7 @@ function extractLocalizedReleaseNoteSection(section, locale) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function completeNotification(notificationFile, state, toVersion, codexUpdate, error, releaseNotes) {
+function completeNotification(notificationFile, state, toVersion, codexUpdate, error, releaseNotes, agyUpdate) {
     if (!notificationFile) {
         return;
     }
@@ -607,6 +692,9 @@ function completeNotification(notificationFile, state, toVersion, codexUpdate, e
         codexUpdate: codexUpdate?.message ?? null,
         codexFromVersion: codexUpdate?.fromVersion ?? null,
         codexToVersion: codexUpdate?.toVersion ?? null,
+        agyUpdate: agyUpdate?.message ?? null,
+        agyFromVersion: agyUpdate?.fromVersion ?? null,
+        agyToVersion: agyUpdate?.toVersion ?? null,
         error,
         updatedAt: new Date().toISOString(),
     });

package/dist/voice/tts.js

@@ -96,6 +96,8 @@ async function convertToOggOpus(input, ffmpegBin) {
             '-y',
             '-i',
             inputPath,
+            '-filter:a',
+            'atempo=1.18',
             '-ac',
             '1',
             '-c:a',
@@ -166,7 +168,7 @@ sys.stdout.buffer.write(pathlib.Path(sys.argv[1]).read_bytes())
 PY
   exit 22
 fi
-ffmpeg -nostdin -hide_banner -loglevel error -y -i "$tmp/tts.wav" -ac 1 -c:a libopus -b:a 32k "$tmp/voice.ogg"
+ffmpeg -nostdin -hide_banner -loglevel error -y -i "$tmp/tts.wav" -filter:a "atempo=1.18" -ac 1 -c:a libopus -b:a 32k "$tmp/voice.ogg"
 python3 - "$tmp/voice.ogg" <<'PY'
 import pathlib
 import sys
@@ -225,7 +227,7 @@ sys.stdout.buffer.write(pathlib.Path(sys.argv[1]).read_bytes())
 PY
   exit 22
 fi
-ffmpeg -nostdin -hide_banner -loglevel error -y -i "$tmp/tts.wav" -ac 1 -c:a libopus -b:a 32k "$tmp/voice.ogg"
+ffmpeg -nostdin -hide_banner -loglevel error -y -i "$tmp/tts.wav" -filter:a "atempo=1.18" -ac 1 -c:a libopus -b:a 32k "$tmp/voice.ogg"
 python3 - "$tmp/voice.ogg" <<'PY'
 import pathlib
 import sys

package/docs/devlogs//346/212/200/346/234/257/351/200/232/350/256/257/02./347/273/237/344/270/200/351/200/232/351/201/223/350/260/203/345/272/246/345/231/250/344/270/216/345/217/257/346/217/222/346/213/224/345/274/225/346/223/216SPI/357/274/232FoxClaw/344/273/216/345/215/225/344/275/223/350/265/260/345/220/221/345/244/232Agent/345/272/225/345/272/247.md

@@ -0,0 +1,192 @@
+# 统一通道调度器与可插拔引擎 SPI：FoxClaw 从单体走向多 Agent 底座
+
+> 记录 FoxClaw 从单一 Codex 专属桥接器，演进为支持 Codex、OpenCode 与 Google Antigravity 多引擎并行的统一 Agent 调度底座的架构重构全过程。
+
+---
+
+## 1. 演进背景：为什么“给新 Agent 复制一套桥”走不通
+
+FoxClaw 最初的诞生，是为了解决自管本机 Codex 的最后一公里：在离开电脑时，通过受信任的 Telegram / 微信移动端入口完成审批接管、线程观察、多账号轮转与跨节点同步。
+
+在最初的单体架构下，整个系统以 Codex 的 `app-server` JSON-RPC 协议与状态机为绝对中心：
+- 会话轮次（Turn）的并发控制紧耦合在 Codex 的 RPC client 回调中；
+- Telegram 消息流式编辑、工具执行折叠、长文本分块等交互逻辑直接混杂在 `TelegramBotController` 内；
+- 崩溃恢复、异常捕获与队列状态紧密依赖单一 Codex thread 机制。
+
+当系统进一步引入支持多模型的 OpenCode，以及 Google 最新的 Antigravity (`agy`) 深度编程 Agent 时，一个严重的架构矛盾暴露在眼前：
+
+如果为每个新 Agent 各自编写一套 Telegram 桥接控制器，整个工程将迅速陷入“代码爆炸与维护灾难”：
+1. **交互逻辑严重冗余**：Markdown 富文本转义、700ms 节流流式编辑（Telegram 429 规避）、长消息（4000 字符）安全切分、工具调用块折叠（`<blockquote expandable>`）、活跃态 Typing 维持等通用交互在各个控制器中反复重抄（单是 Antigravity 控制器最初就复制了近 900 行交互代码）；
+2. **调度行为难以统一**：各个 Agent 面对瞬时并发请求时的行为不一致，有的在内存中丢弃，有的挂起阻塞，缺乏统一的抢占、队列与重启自愈保障；
+3. **运维与状态观测割裂**：指令体系如 `/setup`、`/status`、`/models`、`/effort`、`/steer`、`/interrupt` 在各个 Agent 之间表现各异，账号候选池与配额展示缺乏标准抽象。
+
+“重构吧，架构很重要。多花点精力没毛病。”
+
+这是一次必然的系统升级。FoxClaw 决定重塑内核，拆分核心责任：将**与渠道无关的会话调度、流式预览、消息切分、交互折叠与队列恢复**下沉为通用的 `UnifiedChannelOrchestrator`；将**与具体模型/引擎相关的执行交互、鉴权生命周期与参数控制**抽象为标准化的 `IEngineAdapter`（Engine Service Provider Interface）。
+
+---
+
+## 2. 架构设计：两层模型与分工契约
+
+重构后的 FoxClaw 采用分层解耦架构：
+
+```
+                ┌────────────────────────────────────────────────────────┐
+                │             Telegram / 微信 / 移动端渠道层              │
+                └───────────────────────────┬────────────────────────────┘
+                                            │
+                                            ▼
+               ┌─────────────────────────────────────────────────────────┐
+               │         UnifiedChannelOrchestrator (统一通道调度器)       │
+               │  - Turn 抢占与并发排队 (TurnQueue)                       │
+               │  - 700ms 智能节流流式预览 (StreamPreviewController)       │
+               │  - 消息分块 (chunkTelegramMessage) 与富文本安全转义      │
+               │  - 工具调用过程动态折叠 (<blockquote expandable>)        │
+               │  - 服务崩溃/重启后的队列中断与自愈恢复                      │
+               │  - 统一通用命令分发 (/setup, /status, /steer, /interrupt) │
+               └────────────────────────────┬────────────────────────────┘
+                                            │
+                           Engine SPI (IEngineAdapter)
+                                            │
+         ┌──────────────────────────────────┼──────────────────────────────────┐
+         ▼                                  ▼                                  ▼
+┌──────────────────┐               ┌──────────────────┐               ┌──────────────────┐
+│  Codex Adapter   │               │ Antigravity Adp  │               │ OpenCode Adapter │
+│ (App-Server RPC) │               │ (CLI ChildProc)  │               │ (HTTP Streaming) │
+└──────────────────┘               └──────────────────┘               └──────────────────┘
+         │                                  │                                  │
+         ▼                                  ▼                                  ▼
+   Codex Runtime                  Antigravity Engine                  OpenCode Engine
+```
+
+### 2.1 引擎服务提供者接口（Engine SPI）
+
+在 `src/core/engine_spi.ts` 中，我们提炼了面向 Agent 运行时的最小完备接口：
+
+```typescript
+export interface IEngineAdapter {
+  readonly id: string;
+  readonly displayName: string;
+
+  executeTurn(
+    request: EngineTurnRequest,
+    callbacks: EngineTurnCallbacks
+  ): Promise<EngineTurnExecution>;
+
+  cancelTurn(turnId: string, runId?: string): Promise<boolean>;
+
+  buildStatusSummary(): Promise<string>;
+  buildSetupKeyboard?(): Promise<{ text: string; reply_markup?: any }>;
+
+  handleCommand?(command: string, args: string[], ctx: EngineCommandContext): Promise<boolean>;
+  handleAction?(action: string, ctx: EngineActionContext): Promise<boolean>;
+
+  resolveCurrentModel?(): Promise<string | null>;
+  resolveCurrentEffort?(): Promise<string | null>;
+  switchModel?(modelId: string): Promise<void>;
+  setEffort?(effort: string): Promise<void>;
+
+  handleTurnError?(context: EngineTurnErrorContext): Promise<string | null>;
+  onTurnComplete?(turnId: string): Promise<void>;
+}
+```
+
+任何接入 FoxClaw 的后端 Agent，只要实现该接口，就能立刻获得：
+- 零代码成本获得防抖、防限流的流畅流式打字输出；
+- 完整的工具调用过程折叠；
+- 命令排队、插队、打断与重启自愈；
+- 标准的移动端交互键盘。
+
+---
+
+## 3. 统一通道调度器（UnifiedChannelOrchestrator）的核心实现
+
+### 3.1 700ms 节流预览与 Telegram 限流平衡
+
+在移动端即时通信网络中，Agent 的 token 增量生成速度（可达 50~150 tokens/s）远高于平台的 API 速率限制。Telegram 针对消息编辑（`editMessageText`）实施严格的单会话并发与频次限制，频繁编辑极易触发 HTTP 429 Retry-After。
+
+`StreamPreviewController` 采用基于时间窗口的双缓冲节流设计：
+1. **最小编辑间隔**：固定 700ms 节流窗口；
+2. **内容差异校验**：如果当前渲染的 Markdown 内容与上一次已发送成功的内容无实质变化，跳过该帧；
+3. **最终帧绝对交付**：流式结束后，无论节流计时器是否到期，强制刷新最终帧，确保输出不丢字、不截断；
+4. **Typing 心跳保活**：在长文本推理或工具执行期间，后台每 4 秒维持一次 `sendChatAction('typing')`，消除用户的“死机焦虑”。
+
+### 3.2 工具调用动态折叠与 4000 字符分块
+
+复杂任务中，Agent 会产生大量终端执行、文件查找、代码替换等中间工具调用。若平铺在 Telegram 会话中，会迅速淹没正文结论。
+
+调度器实现了工具调用的自适应折叠：
+- 当工具开始执行时，进入内部 buffer；
+- 转换为 HTML 规范的 `<blockquote expandable>...</blockquote>` 折叠块；
+- 最终正文超出 Telegram 单条消息 4096 字符上限时，通过 `chunkTelegramMessage` 按照段落、代码块、句末标点边界安全切分为连续消息序列，防止 Markdown 标签不配对导致的富文本渲染崩溃。
+
+### 3.3 崩溃自愈与跨重启状态机
+
+守护进程更新升级或异常重启时，处于运行中的任务不能处于不可知的悬空状态。
+`UnifiedChannelOrchestrator` 与 SQLite 存储层打通：
+- 在系统启动时扫描处于 `running` 或 `queued` 的历史 Turn；
+- 对未完成 Turn 标记为 `interrupted` 并向关联会话发送恢复通知；
+- 释放旧的并发互斥锁，确保用户在服务重启后无需手动清空队列即可继续提问。
+
+---
+
+## 4. 典型引擎适配实战：Antigravity 适配器
+
+Google Antigravity (`agy`) 是新一代面向复杂任务的深度智能体，其底层调用 CloudCode PA 接口与 Gemini 3.8/3.7/3.1 和 Claude 模型。将 Antigravity 接入 FoxClaw 涉及几个独特的挑战：
+
+### 4.1 Token 预检与全自动刷新（Token Preflight）
+
+Antigravity 的 OAuth Token 存储在 `~/.gemini/antigravity-cli/`。在真实环境中，Token 的有效寿命通常仅为 1 小时。若直接发起长任务 CLI 调用，过期的 Access Token 会导致数分钟后任务在模型层报错失败。
+
+`AntigravityEngineAdapter` 引入了**预检与静默刷新机制**：
+- 在每次执行 Turn 前，预先计算 access token 的剩余有效期；
+- 若剩余时间少于 5 分钟，自动调用 Google OAuth 凭据端点执行静默刷新；
+- 若刷新过程出现临时网络波动，执行回退并利用 `id_token` 中的账户哈希进行安全校验。
+
+### 4.2 应对 Google 503 容量饱和与配额冷却轮换
+
+在高峰期，大型推理模型可能频繁返回 `503 Service Unavailable` 或 `MODEL_CAPACITY_EXHAUSTED`。单次报错不应直接宣告任务失败。
+
+我们在适配器中实现了两层自愈：
+1. **指数退避重试**：针对瞬时容量饱和，适配器进行 1s、2s、4s 指数退避重试；
+2. **配额超限自动轮换（Quota Cooldown Rotation）**：当当前 Google 账号遭遇真正的用量限额（ResourceExhausted）时，适配器自动将该账号标记为冷却态，无缝切换至候选池中的下一个可用账号，并在新账号下自动恢复执行。
+
+### 4.3 彻底厘清配额展示：从时间误区到真实的 5h/7d 百分比
+
+在早期的候选账号切换面板中，按钮前缀曾显示类似 `100|80|...` 的字符。这引发了一个严重的认知混淆：
+“竖线前面的意义不是时间啊，为什么把百分比当时间展示？”
+
+我们彻底重构了配额可观测模块：
+- **真实指标定义**：Google PA API 返回的配额窗口为 `5 小时突发额度`（5h Window）与 `7 天长期额度`（7d Window），其返回值为 0~100 的**百分比数值（Remaining Percentage）**，而非倒计时或小时数；
+- **显式 Badge 格式化**：在 `formatCandidateButtonPrefix` 中全面规范化为明确带百分号的徽标：`100%|80%|account_name`；
+- **全链路感知**：在 `/auth` 列表、`/status` 面板与 `/setup` 概览中，统一以 `5h: 100% | 7d: 80%` 格式完整呈现，使开发者在手机上一眼看清各个候选账号的真实健康度。
+
+---
+
+## 5. 重构收益与系统验证
+
+### 5.1 代码精简与架构对称
+
+| 模块 | 重构前 | 重构后 | 变化收益 |
+| :--- | :--- | :--- | :--- |
+| **`AntigravityBridgeCore`** | ~1100 行（混杂所有 Telegram 交互） | 185 行（聚焦引擎交互与适配） | **减少 83% 样板代码** |
+| **流式交互与折叠** | 各 Agent 自行实现、版本不齐 | 集中在 `UnifiedChannelOrchestrator` | 一处改进，所有引擎同享 |
+| **新增 Agent 接入成本** | 需要复制完整 Telegram 控制器（~1000行） | 仅需实现 `IEngineAdapter`（~150行） | **降低 85% 扩展成本** |
+
+### 5.2 测试覆盖与生产验证
+
+本次重构涵盖全套自动化单元测试与端到端验证：
+- **测试套件覆盖**：全仓库 **449 个自动化测试 100% 通过**（覆盖 `orchestrator.test.ts`、`adapter.test.ts`、`turn_queue.test.ts`、`stream_preview.test.ts`、`attachments.test.ts` 等）；
+- **TypeScript 严格类型检查**：`npm run typecheck` 0 错误；
+- **全生产构建验证**：`npm run build` 干净生成生产级 `dist/`；
+- **线上 Daemon 热升级**：在生产环境无缝热重启 `foxclaw.service`，进程持续健康运行，实测双 Agent 并发、503 退避重试与多账号按额度轮换表现稳定。
+
+---
+
+## 6. 结语
+
+FoxClaw 从一个面向 Codex 的个人小工具，迈出了走向通用 Agent 基础设施的关键一步。
+
+统一通道调度器与可插拔引擎 SPI 的确立，不仅抹平了不同厂商 Agent 在命令行与网络协议上的差异，更让开发者无论面对哪一个大模型内核，都能在手机端拥有完全一致、稳定、丝滑的沉浸式控制体验。
+
+AI 工具在不断演进，而沉淀在工作流最后一公里的这套运行保障底座，才是让 Agent 真正能够全天候陪伴人类工程师前行的坚实桥梁。