| # 横切关注点 — 错误处理、日志、遥测与性能 |
|
|
| ## 1. 错误处理架构 |
|
|
| ### 1.1 错误类型层次 |
|
|
| 代码库定义了一个多层级的错误类体系，所有自定义错误最终继承自 `Error`： |
|
|
| - **基类 `ClaudeError`** (`src/utils/errors.ts`) — 设置 `this.name = this.constructor.name`，是所有内部错误的根类。 |
| - **中止错误** — `AbortError` 和 SDK 的 `APIUserAbortError` 通过 `isAbortError()` 统一检测；该函数也兼容 DOMException 的 `name === 'AbortError'` 模式。 |
| - **Shell 错误** — `ShellError` 携带 `stdout`、`stderr`、`code`、`interrupted` 四个字段，用于统一处理子进程失败。 |
| - **配置解析错误** — `ConfigParseError` 携带 `filePath` 和后备的 `defaultConfig`。 |
| - **Axios 错误分类** — `classifyAxiosError()` 将 HTTP 客户端错误归类为 `auth`、`timeout`、`network`、`http`、`other` 五种类型。 |
| - **遥测安全错误** — `TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS` 在构造时分离用户可见消息和遥测安全消息。 |
|
|
| 领域特定错误分布在各个模块中： |
|
|
| - `StopTaskError` (`src/tasks/stopTask.ts`) — 带有 `code` 字段区分 `not_found`、`not_running`、`unsupported_type`。 |
| - `ToolExecutionError` — 工具执行过程中的运行时错误。 |
| - `BridgeFatalError` / `BridgeHeadlessPermanentError` (`src/bridge/`) — Bridge 模式下的致命/永久错误。 |
| - `CannotRetryError` / `FallbackTriggeredError` (`src/services/api/withRetry.ts`) — API 重试耗尽或模型降级时的错误。 |
| - `McpAuthError` / `XaaTokenExchangeError` (`src/services/mcp/`) — MCP 协议认证相关错误。 |
| - 辅助函数 `toError()`、`errorMessage()`、`shortErrorStack()`、`isFsInaccessible()` 提供了通用的错误处理基础设施。 |
|
|
| ### 1.2 工具执行错误 |
|
|
| 工具调用执行时产生的错误通过 Task 系统的 catch 边界捕获。每个 Task 类型（`LocalShellTask`、`LocalAgentTask`、`InProcessTeammateTask`）实现自己的错误处理逻辑： |
|
|
| - **`AbortError`** 在 agent 任务中被特殊处理 — 提取部分结果 (`extractPartialResult`) 后生成通知而非静默丢弃。Bash 任务中则静默抑制 "exit code 137" 通知以减少噪音。 |
| - **`StopTaskError`** 区分任务不存在、未在运行和不支持的类型，让调用方可以根据 `error.code` 决定处理策略。 |
| - **`MaxFileReadTokenExceededError`** (`src/tools/FileReadTool/`) — 文件读取超过 token 上限时抛出，触发调用方改用分块读取。 |
| - **`SessionBranchingError`** (`src/utils/sessionBranching.ts`) — 会话分支操作失败时的特定错误。 |
| - **`ConversationStartupError`** (`src/server/services/conversationService.ts`) — 服务器端会话恢复失败时的错误。 |
| - 工具执行器在上层 catch 边界中将错误序列化为 `tool_result` 内容，确保 LLM 可以感知错误并调整行为。 |
|
|
| ### 1.3 模型调用错误与恢复策略 |
|
|
| `withRetry()` (`src/services/api/withRetry.ts`) 实现了完整的 API 调用重试引擎： |
|
|
| - **默认最大重试次数** 为 10（可通过 `CLAUDE_CODE_MAX_RETRIES` 环境变量覆盖）。 |
| - **错误分类**: 529 过载、429 速率限制（含 fast-mode overage）、401 认证过期、403 token 吊销、ECONNRESET/EPIPE 连接中断、400 max_tokens context overflow。 |
| - **退避策略**: 指数退避 + 随机 jitter（`BASE_DELAY_MS * 2^(attempt-1) + jitter`），优先使用 `Retry-After` 响应头。 |
| - **Fast Mode 降级**: 短延迟直接重试（保留 prompt cache），长延迟触发 cooldown 切换为标准速度。 |
| - **模型降级**: 连续 3 次 529 错误后触发 `FallbackTriggeredError`，切换到 fallback 模型。 |
| - **持久模式** (`CLAUDE_CODE_UNATTENDED_RETRY`): 无限重试 429/529，最大退避 5 分钟，6 小时上限，每 30 秒输出心跳防止会话超时。 |
| - **背景请求不重试**: 非前台 `QuerySource`（如摘要、标题、建议）在 529 时直接放弃，避免容量级联放大。`FOREGROUND_529_RETRY_SOURCES` 集合中仅包含用户等待结果的查询源。 |
| - **认证错误处理链**: 401/403 错误触发 OAuth token 刷新 (`handleOAuth401Error`)、AWS credential cache 清理 (`clearAwsCredentialsCache`)、GCP credential cache 清理 (`clearGcpCredentialsCache`)。CCR 模式下 401/403 被视为瞬态错误（网络抖动）而非坏凭证。 |
| - **Context Overflow 恢复**: `parseMaxTokensContextOverflowError()` 解析 "input length and `max_tokens` exceed context limit" 错误消息，提取 `inputTokens`、`contextLimit`，自动计算调整后的 `max_tokens` 并重试。至少保留 1000 token 安全缓冲区和 3000 输出 token 下限。 |
| - **连接池管理**: ECONNRESET/EPIPE 错误触发 `disableKeepAlive()`，在重试时创建新连接而非复用可能损坏的 keep-alive socket。 |
| - **Mock 错误集成**: Ant 员工通过 `/mock-limits` 命令触发的模拟速率限制错误 (`checkMockRateLimitError`) 在重试引擎中受到特殊处理 — 不被视为可重试错误，确保测试场景不会进入无限重试循环。 |
|
|
| ### 1.4 致命错误 vs 可恢复错误 |
|
|
| - **可恢复错误**: 网络抖动、速率限制、认证过期、token 吊销 — 通过重试、token 刷新、连接池禁用等机制自动恢复。 |
| - **致命错误**: `BridgeFatalError`、`CannotRetryError`（重试耗尽后）、配置解析失败 — 需要用户干预或进程重启。 |
|
|
| --- |
|
|
| ## 2. 日志系统 |
|
|
| ### 2.1 控制台日志与文件日志 |
|
|
| - **`logForDebugging()`** (`src/utils/debug.ts`) — 双重输出到 stderr 和文件。支持日志级别过滤（`CLAUDE_CODE_DEBUG_LOG_LEVEL` 从 verbose 到 error），`CLAUDE_CODE_DEBUG` 环境变量启用输出。`CLAUDE_CODE_DEBUG_FILTER` 按模块名称过滤减少噪音。 |
| - **缓冲写入**: `BufferedWriter` 模式将高频日志积累到内存缓冲区后批量写入磁盘，减少细粒度 I/O 的系统调用开销。日志文件位于 `{CLAUDE_CONFIG_HOME}/debug.log`，使用符号链接跟踪最新会话，便于快速定位当前 session 的日志。 |
| - **`logError()`** (`src/utils/log.ts`) — 专用错误日志函数，捕获完整错误栈和结构化元数据，输出到标准错误流。 |
| - **日志文件轮转**: 通过 `getClaudeConfigHomeDir()` 确定日志目录路径，`registerCleanup` 在进程退出时确保缓冲区排空。CLAUDE_CODE_FORCE_FULL_LOGO 等构建时常量控制日志展示格式。 |
| - **调试过滤器**: `parseDebugFilter()` 和 `shouldShowDebugMessage()` 允许按来源模块名称精确控制哪些调试消息可见，在开发高噪音模块时可以只关注特定子系统的输出。 |
|
|
| ### 2.2 LogSelector UI 组件 (`src/components/LogSelector.tsx`) |
|
|
| 一个功能完整的日志浏览器，提供： |
|
|
| - **模糊搜索** (Fuse.js) — 按会话标题、摘要、内容搜索。 |
| - **标签分类** — 按 agent 名称、自定义标签、项目过滤。 |
| - **树形浏览** — 按日期层级组织日志。 |
| - **对话预览** — 在侧面板显示选中会话的摘要消息。 |
| - **智能搜索** — 可以通过 AI 驱动的语义搜索查找相关日志。 |
| - **分页加载** (`onLoadMore`) — 支持无限滚动。 |
|
|
| ### 2.3 诊断工具 (`/doctor` 命令 & DiagnosticsService) |
|
|
| - **`DiagnosticsService`** (`src/server/services/diagnosticsService.ts`) — 捕获 `console.error`、`console.warn`、`process.on('uncaughtException')`、`process.on('unhandledRejection')`，将诊断事件写入文件系统。7 天保留期，50MB 上限。 |
| - **REST API** (`src/server/api/diagnostics.ts`) — 提供 `GET /api/diagnostics/status`、`GET /api/diagnostics/events`、`POST /api/diagnostics/export` 等端点。导出为压缩的 tar.gz，自动脱敏 API key、token 等敏感信息。 |
| - **`DiagnosticsTrackingError`** (`src/services/diagnosticTracking.ts`) — 内部跟踪诊断事件类型的错误。 |
|
|
| --- |
|
|
| ## 3. 遥测与分析 |
|
|
| ### 3.1 GrowthBook 集成 (`src/services/analytics/growthbook.ts`) |
|
|
| GrowthBook 提供 feature flags 和 A/B 测试能力： |
|
|
| - **远程评估**: `remoteEval: true` 模式下，服务器端评估 feature flag 值，客户端缓存到内存 (`remoteEvalFeatureValues`) 和磁盘 (`cachedGrowthBookFeatures` 在 `~/.claude.json`)。 |
| - **用户属性**: 发送 `deviceID`、`platform`、`organizationUUID`、`accountUUID`、`subscriptionType`、`rateLimitTier` 等用于定向。 |
| - **缓存策略**: |
| - `getFeatureValue_CACHED_MAY_BE_STALE()` — 非阻塞，优先内存缓存，后备磁盘缓存，适用于启动关键路径。 |
| - `getDynamicConfig_BLOCKS_ON_INIT()` — 阻塞直到初始化完成（最多 5 秒超时）。 |
| - `checkSecurityRestrictionGate()` — 安全检查相关 gate，等待 re-init 完成以确保值新鲜。 |
| - `checkGate_CACHED_OR_BLOCKING()` — 磁盘缓存为 true 时快速返回，false 时等待服务器确认（避免 false 误阻止用户功能）。 |
| - **实验曝光**: 每个 feature 在一个 session 内只记录一次曝光事件 (`loggedExposures` 去重)，通过 `logGrowthBookExperimentTo1P` 发送到第一方遥测。 |
| - **周期刷新**: 非 Ant 构建每 6 小时刷新，Ant 构建每 20 分钟刷新。刷新时重建 `remoteEvalFeatureValues` 并同步到磁盘。 |
| - **认证变更**: `refreshGrowthBookAfterAuthChange()` 销毁旧客户端并使用新认证头重建，防止 API key 变更后返回过期值。 |
| - **环境变量覆盖**: Ant 员工可通过 `CLAUDE_INTERNAL_FC_OVERRIDES` 全局覆盖 feature flag（用于评估工具）。 |
|
|
| ### 3.2 遥测 Sink 架构 (`src/services/analytics/sink.ts`) |
|
|
| 分析系统采用 sink 模式，支持热插拔遥测后端： |
|
|
| - **`AnalyticsSink` 接口** (`src/services/analytics/index.ts`) — 定义 `logEvent()` 同步和 `logEventAsync()` 异步方法，以及 `attachAnalyticsSink()` 注册函数。OSS 构建中所有实现体为空（no-op），降低二进制体积。 |
| - **`initializeAnalyticsGates()` / `initializeAnalyticsSink()`** (`src/services/analytics/sink.ts`) — OSS 构建中为空函数。在完整构建中会初始化 GrowthBook 和 Datadog 后端。 |
| - **`sinkKillswitch.ts`** — 通过 GrowthBook feature flag 在运行时动态禁用遥测发送，用于紧急情况下的数据收集开关。 |
| - **元数据标记** — `AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS` 类型确保只有在调用方显式声明"此元数据不包含敏感信息"时才能传递，编译期防止数据泄露。 |
|
|
| ### 3.3 第一方事件日志 (`src/services/analytics/firstPartyEventLogger.ts`) |
|
|
| Ant 内部构建使用第一方事件日志系统： |
|
|
| - **实验曝光日志**: `logGrowthBookExperimentTo1P()` 记录 A/B 实验的分组信息和用户属性。 |
| - **批处理配置**: 通过 `tengu_1p_event_batch_config` 动态配置批量发送策略。使用 `onGrowthBookRefresh` 订阅配置变更，在运行时重建 LoggerProvider。 |
| - **条件启用**: `is1PEventLoggingEnabled()` 检查隐私级别、用户认证状态等前置条件，只有满足所有条件时才启用。 |
|
|
| ### 3.4 Datadog (`src/services/analytics/datadog.ts`) |
|
|
| OSS 构建中 Datadog 遥测被禁用（`initializeDatadog` 返回 `false`，`trackDatadogEvent` 函数体为空）。接口保留以便启动代码不需要对 OSS 变体特殊处理。Datadog 用于生产环境的性能监控、错误追踪和自定义指标仪表板。 |
|
|
| ### 3.5 分析配置 (`src/services/analytics/config.ts`) |
|
|
| `isAnalyticsDisabled()` 在以下情况下禁用分析：NODE_ENV=test、Bedrock/Vertex/Foundry 第三方提供商、隐私级别为 no-telemetry 或 essential-traffic 模式。 |
| |
| ### 3.6 成本与令牌用量追踪 (`src/cost-tracker.ts`) |
| |
| - **全局状态**: `getTotalCostUSD()`、`getTotalInputTokens()`、`getTotalOutputTokens()`、`getTotalAPIDuration()` 等函数从 bootstrap state 读取聚合数据。 |
| - **按模型统计**: `getUsageForModel()` 按模型名跟踪 `inputTokens`、`outputTokens`、`cacheReadInputTokens`、`cacheCreationInputTokens`、`costUSD`。 |
| - **会话持久化**: `saveCurrentSessionCosts()` 将当前 session 的成本写入 project config；`restoreCostStateForSession()` 在恢复 session 时重建成本状态。 |
| - **成本展示**: `formatTotalCost()` 输出格式化成本摘要（总成本、API 时长、代码变更行数、按模型的令牌使用量）。 |
| - **exit 回调**: `useCostSummary()` (`src/costHook.ts`) 在 `process.on('exit')` 时自动输出成本摘要并保存 session 数据。 |
| |
| --- |
| |
| ## 4. 性能工程 |
| |
| ### 4.1 流式工具执行 |
| |
| 工具执行采用流式架构（`QueryEngine` 中的 `AsyncGenerator`），LLM 输出 token 流式到达的同时，工具结果可以并行返回： |
| |
| - **`QueryEngine`** 将 LLM 的流式响应解析为 `TextBlock`、`ToolUseBlock`、`ContentBlockStop` 等事件，边解析边交付给 UI 渲染。 |
| - **工具并行**: 当 LLM 发起多个工具调用时，`tools.ts` 中的调度器可以并行执行无依赖的工具（如同时读取多个文件），减少总等待时间。流式响应持续接收新的工具调用请求。 |
| - **前台 vs 背景**: 前台 `QuerySource`（如 `repl_main_thread`）使用完整的重试、提示缓存和速率限制逻辑；背景任务（摘要、标题生成）使用轻量级路径以减少延迟。 |
| - **`QuerySource` 分类**: 定义在 `src/constants/querySource.ts`，包括 `repl_main_thread`、`repl_main_thread:outputStyle:custom`、`sdk`、`agent:custom`、`compact`、`hook_agent`、`auto_mode` 等 20+ 种类型，影响重试策略和日志记录。 |
| |
| ### 4.2 提示缓存 (Prompt Caching) |
| |
| - **缓存写入控制** (`skipCacheWrite`) — 某些场景（如快速诊断查询）跳过缓存写入以节省 cache creation token 成本。适用于可丢弃的中间查询，如标题生成、会话摘要等。 |
| - **缓存读取追踪** — `cache_read_input_tokens` 和 `cache_creation_input_tokens` 通过 `cost-tracker.ts` 分模型追踪。API 响应中的 `usage.cache_read_input_tokens` 和 `usage.cache_creation_input_tokens` 字段在 `addToTotalSessionCost()` 中累加。 |
| - **Fast Mode 缓存保留** — 在 fast mode 中，短延迟重试使用相同的模型名以保留 prompt cache（减少 cache creation 消耗）；长延迟触发 cooldown 切换到标准模型时，失去缓存被视为可接受成本。 |
| - **Cache Break Detection** (`PROMPT_CACHE_BREAK_DETECTION` feature flag) — 监控和检测 prompt cache 命中率异常下降的场景，帮助诊断缓存失效原因。 |
| - **成本核算**: `calculateUSDCost()` 函数根据模型单价、输入/输出/cache read/cache creation token 用量计算精确成本。未知模型通过 `hasUnknownModelCost()` 标记。 |
|
|
| ### 4.3 上下文预取 |
|
|
| - **内存预取**: `memory` 系统在 agent 启动时主动从磁盘加载相关记忆片段。 |
| - **技能预取**: `skills` 系统预加载已启用的技能描述和工具定义。 |
| - **推测执行** (`SpeculationState`): 在用户输入到达之前，系统可以推测性地启动任务执行。 |
|
|
| ### 4.4 令牌估算 |
|
|
| `getContextWindowForModel()` 和 `getModelMaxOutputTokens()` 提供按模型的上下文窗口和输出上限。`parseMaxTokensContextOverflowError()` 解析 API 返回的 context overflow 错误并自动调整 `max_tokens` 参数。 |
|
|
| ### 4.5 速率限制模拟 (`src/services/rateLimitMocking.ts`) |
|
|
| Ant 员工可以通过 `/mock-limits` 命令模拟各种速率限制场景（429、529、fast-mode cooldown），用于测试 UI 行为和恢复逻辑。与 `withRetry()` 集成，确保模拟错误不触发真实重试。 |
|
|
| ### 4.6 背景任务卸载 |
|
|
| 在 stop hooks 中使用 fire-and-forget 模式（`void` 前缀 + `.catch()`），确保关键路径不被背景任务阻塞。例如：`LogSelector.tsx` 中的日志写入、`onChangeAppState` 中的 side-effect 通知。 |
|
|
| --- |
|
|
| ## 5. 跨组件通信模式 |
|
|
| ### 5.0 Signal 模式 (`src/utils/signal.ts`) |
|
|
| `createSignal<T>()` 提供轻量级的事件信号原语，与 Store 不同，Signal 不持有状态快照，仅用于通知"某事发生了"： |
|
|
| - **订阅/取消**: `subscribe(listener)` 返回取消函数，与 React useEffect 的 cleanup 模式天然兼容。 |
| - **类型安全**: 通过泛型 `Args` 指定事件参数类型。 |
| - **去重**: `clear()` 移除所有监听器，用于 dispose 和 reset 路径。 |
| - **使用场景**: GrowthBook 刷新通知 (`refreshed` signal)、设置变更通知、`onChangeAppState` 中的事件广播。 |
| - **与 Store 的区别**: Signal 无 `getState()`，不存储值，仅做事件通知。在代码库中替换了 ~15 处重复的 `new Set<Listener>()` + `subscribe/notify` 模式。 |
|
|
| ## 6. 状态管理性能 |
|
|
| ### 6.1 AppState 可观察存储 (`createStore` 模式) |
|
|
| `createStore<T>()` (`src/state/store.ts`) 是一个轻量级不可变状态存储，模式灵感来源于 Redux 但更简洁： |
|
|
| - `getState()` — O(1) 引用读取，无任何开销。 |
| - `setState(updater)` — 接收 `(prev: T) => T` 更新函数。通过 `Object.is` 做引用相等性检查，避免无变更时通知监听器。`onChange` 回调在每次有效状态变更时同步触发，接收 `{ newState, oldState }` 上下文。 |
| - `subscribe(listener)` — 基于 `Set<Listener>` 的发布-订阅，返回取消订阅函数。无额外分配。 |
| - `AppStateStore` 类型 (`src/state/AppStateStore.ts`) 继承自 `Store<AppState>`，添加了 `AppState` 的默认值工厂函数 `getDefaultAppState()`。完整的 AppState 包含 `tasks`、`toolPermissionContext`、`settings`、`isUltraplanMode`、`viewingAgentTaskId` 等顶级字段。 |
| - **不可变性保证**: `setState` 使用 updater 函数模式，每次变更产生新的状态对象。React 渲染层依赖引用相等性进行短路优化。 |
|
|
| ### 6.2 onChangeAppState 副作用处理器 (`src/state/onChangeAppState.ts`) |
|
|
| 一个集中式 `onChange` 处理器，在 AppState 变更时协调跨系统的副作用： |
|
|
| - 权限模式同步（CCR/SDK） |
| - 会话元数据变更通知 |
| - 设置变更应用 (`applySettingsChange`) |
| - API key 缓存清理 |
|
|
| 这种模式避免了 React 组件中散落的 `useEffect` 链，让状态变更的副作用可预测且可测试。 |
|
|
| ### 6.3 Selector 模式 (`src/state/selectors.ts`) |
|
|
| 纯函数选择器从 AppState 派生计算状态： |
|
|
| - `getViewedTeammateTask()` — 提取当前查看的 teammate 任务 |
| - `getActiveAgentForInput()` — 确定用户输入路由目标（leader / viewed / named_agent） |
| |
| 选择器保持轻量、无副作用，便于组合和测试。 |
| |
| ### 6.4 React Context 订阅 |
| |
| `AppStateProvider` (`src/state/AppState.tsx`) 使用 React Context + `useSyncExternalStore` 将存储桥接到 React 渲染周期。`VoiceProvider` 通过 `feature('VOICE_MODE')` 进行死代码消除 — 外部构建中它是一个无操作的包裹器。`useSettingsChange` hook 监听设置文件变更并增量更新状态。 |
|
|
| --- |
|
|
| ## 7. 构建优化 |
|
|
| ### 7.1 Feature Flag 死代码消除 (`bun:bundle feature()`) |
|
|
| Bun 的编译时 `feature()` 函数允许在构建阶段消除未使用的代码分支： |
|
|
| - `scripts/build.ts` 定义了完整的实验特性列表（如 `VOICE_MODE`、`AGENT_MEMORY_SNAPSHOT`、`BASH_CLASSIFIER` 等 50+ 个 flag）。 |
| - 外部构建默认只启用 `VOICE_MODE`。 |
| - 构建命令 `bun build --feature=<flag>` 将 feature flag 注入编译步骤，未启用的分支在 tree-shaking 中被完全移除。 |
| - 这使得 ant-internal 代码可以直接嵌入仓库，而外部构建不携带任何内部逻辑。 |
|
|
| ### 7.2 React Compiler 输出 (`src/components/LogoV2/`) |
|
|
| `LogoV2/` 目录中的组件（`LogoV2.tsx`、`AnimatedClawd.tsx`、`Feed.tsx`、`WelcomeV2.tsx` 等）使用了 React Compiler (`react/compiler-runtime`) 自动记忆化输出。编译器将 `useMemo`/`useCallback` 模式自动化，减少手动优化的工作量。 |
|
|
| ### 7.3 WASM 二进制文件 |
|
|
| VAD（Voice Activity Detection）服务 (`src/friend/voice/vad-service.ts`) 使用 `onnxruntime-web` 的 WASM 后端（而非 `onnxruntime-node` 原生插件），因为 Bun 不支持 Node-API 原生插件。WASM 二进制文件 (`onnxruntime-web`) 随 dist 打包。 |
|
|
| ### 7.4 Build 脚本 (`scripts/build.ts`) |
|
|
| 构建管道使用 Bun 原生打包器，生成单一可执行文件： |
|
|
| 1. **预构建 Friend VRM 前端**: 检查 `src/components/friend/frontend/dist/index.html` 是否存在，不存在时执行 `npm run build`。 |
| 2. **主构建**: 使用 `bun build --compile --target bun --minify --bytecode` 生成单个可执行文件。`--minify` 减小二进制体积，`--bytecode` 编译为 Bun 字节码提升启动速度。 |
| 3. **编译时常量注入**: |
| - `MACRO.VERSION` — 语义版本号（开发版附加 git SHA 和时间戳）。 |
| - `MACRO.BUILD_TIME` — ISO 8601 构建时间戳。 |
| - `MACRO.FEEDBACK_CHANNEL` — 反馈渠道（OSS 构建为 `github`）。 |
| - `MACRO.VERSION_CHANGELOG` — 最近的 git commit 日志或指向 GitHub 的 URL。 |
| 4. **外部模块排除**: `@ant/*`、`audio-capture-napi`、`image-processor-napi`、`modifiers-napi`、`url-handler-napi` 通过 `--external` 排除捆绑，减小二进制体积并允许运行时加载原生模块。 |
| 5. **环境变量定义**: `process.env.USER_TYPE='external'`、`process.env.CLAUDE_CODE_FORCE_FULL_LOGO='true'`、`process.env.CCR_FORCE_BUNDLE='true'` 等定义确保构建产物运行于正确模式。 |
| 6. **完整特性集**: 使用 `--feature-set=dev-full` 启用全部实验特性（50+ feature flags），默认仅启用 `VOICE_MODE`。 |
| 7. **输出产物**: 开发版本输出到 `./Codev`，发布版本输出到 `./dist/cli`。 |
|
|
| --- |
|
|
| ## 8. 资源管理 |
|
|
| ### 8.1 子进程管理 |
|
|
| - **音频采集** (`arecord` / `sox`) — 通过 `child_process.spawn` 管理，采样率 16kHz，16-bit PCM。 |
| - **Whisper STT** (`src/services/voice/whisperSTT.ts`) — 本地语音识别子进程，管理其生命周期并处理输出解析。 |
| - **Tauri 子进程** — 在 Friend 桌面模式下启动和管理 Tauri shell 进程。 |
| - **子进程超时** — `RipgrepTimeoutError`、`StallTimeoutError` 确保子进程不会无限期挂起。`cleanupRegistry.ts` 注册进程清理回调，在优雅关闭时统一终止。 |
|
|
| ### 8.2 定时器和超时 |
|
|
| - **GrowthBook 周期刷新** — `setupPeriodicGrowthBookRefresh()` 使用 `setInterval`（非 Ant: 6h，Ant: 20min），`unref()` 保证不阻止进程退出。 |
| - **API 重试退避** — `sleep()` + `AbortSignal` 组合，支持中途取消。 |
| - **持久重试心跳** — 每 30 秒输出系统消息防止空闲超时。 |
| - **优雅关闭** — `gracefulShutdown.ts` 中的 `CleanupTimeoutError` 确保关闭过程不会无限阻塞。 |
|
|
| ### 8.3 优雅关闭与清理注册表 |
|
|
| `cleanupRegistry.ts` 和 `gracefulShutdown.ts` 实现了进程级资源清理系统： |
|
|
| - **`registerCleanup()`** (`src/utils/cleanupRegistry.ts`) — 全局 `Set<() => Promise<void>>` 注册表。任何模块可以注册异步清理函数，返回取消注册函数。`runCleanupFunctions()` 使用 `Promise.all` 并行执行所有清理任务。 |
| - **`gracefulShutdown()`** (`src/utils/gracefulShutdown.ts`) — 主关闭流程，按顺序执行： |
| 1. `onExit('signal-exit')` 捕获 SIGTERM/SIGINT，设置 `isShuttingDown` 标志。 |
| 2. 同步恢复终端模式（退出 alt screen、恢复光标、禁用 mouse tracking、恢复 Kitty 键盘模式）。 |
| 3. `runCleanupFunctions()` 并行运行所有注册的异步清理。 |
| 4. 关闭 Datadog（`shutdownDatadog()`）和第一方事件日志。 |
| 5. 最终日志发送（会话成本、诊断事件）。`CleanupTimeoutError` 防止清理阶段无限阻塞。 |
|
|
| ### 8.4 文件句柄管理 |
|
|
| - **SSE 客户端** — EventSource 连接在设置/清理生命周期中管理，使用 `AbortController` 确保断开。 |
| - **音频文件** — 语音录制生成临时 WAV 文件，`FriendService` 负责生命周期管理。 |
| - **调试日志** — `BufferedWriter` 管理文件写入，`registerCleanup` 注册关闭回调。 |
| - **诊断事件** — `DiagnosticsService` 使用文件系统存储诊断事件，7 天保留期和 50MB 上限防止磁盘膨胀。 |
|
|
| ### 8.5 VAD 内存状态管理 |
|
|
| `SileroVad` (`src/friend/voice/vad-service.ts`) 在 ONNX 推理会话中维护 LSTM 状态张量 (`stateH`、`stateC`)。每个音频帧（512 采样 / 32ms）处理后更新状态。关键优化： |
|
|
| - **RMS 能量过滤**: 低于 `rmsThreshold`（默认 ~-48dBFS）的帧跳过 ONNX 推理，直接视为静音。在高噪声环境中可以减少约 60% 的推理次数。 |
| - **状态重置**: `reset()` 方法清空 LSTM 状态和累积缓冲区，用于会话间清理。 |
| - **预处理触发**: `preSpeechTriggerFrames`（默认 10 帧 / 320ms）过滤短时噪音爆发，避免误触发。 |
|
|
| --- |
|
|
| ## 架构决策记录 |
|
|
| | 决策 | 理由 | |
| |------|------| |
| | 错误使用 `class extends Error` 并显式设置 `this.name` | 确保压缩构建中 `instanceof` 失效时仍可通过 `name` 属性识别错误类型 | |
| | 重试引擎使用 generator (`yield`) | 允许在重试间隔中间向调用方输出系统消息（心跳、进度） | |
| | GrowthBook 使用 `remoteEval: true` | 服务器端评估避免客户端下载完整规则集，减少网络负载和延迟 | |
| | VAD 使用 WASM 而非原生插件 | 兼容 Bun 运行时（Node-API 原生插件在 Bun 中导致 segfault） | |
| | 选择器使用纯函数而非 memoized selector | AppState 不可变性保证引用相等性检查足够高效，不需要额外记忆化开销 | |
| | Feature flag 死代码消除在构建时而非运行时完成 | 显著减小外部构建的二进制体积，消除内部代码泄漏风险 | |
| | Datadog / 遥测在 OSS 构建中默认禁用 | 保持开放源代码版本的隐私友好特性，同时保持接口兼容性 | |
|
|
