# Core App 启动链路与运行时变量参考

> 更新时间：2026-10-07
> 范围：`apps/core-app/src` 中 `process.env` / `import.meta.env` 的实际引用

## 启动与回退现状

### 1) Assistant 模块启动现状

- `assistantModule` 始终进入 Core App 启动模块列表，不再存在环境变量 gate 或 Assistant 专用 `shouldSkip` 分支。
- 产品可用性由持久化 App Settings 控制；宿主会把缺失的 `assistant.enabled` 修复为 `false`，因此 Assistant 仍默认关闭，但不再改变模块启动语义。
- 运维和用户应通过设置页启用 Assistant；已移除的 `TUFF_ENABLE_ASSISTANT_EXPERIMENT` 不再是受支持的运行时变量，也不会再出现旧 optional-module / env-gate 日志。

### 2) dev.source 探活 + 本地降级（已改）

- 现状：`DevPluginLoader` 先请求远端 `manifest.json` 作为探活。
- 远端失败时：
  - 自动回退到本地 `manifest.json` + 本地 README/资产；
  - 运行时强制 `dev.source=false`（仅当前进程，不落盘）；
  - 记录 `DEV_SOURCE_FALLBACK_LOCAL`（warning）。
- 仅当“远端失败 + 本地也不可用”时，才记录 `REMOTE_MANIFEST_FAILED`（error）。

## 插件 Issue Code 速查（含 `DEV_SOURCE_FALLBACK_LOCAL`）

| Code                              | 默认级别 | 作用                                                          |
| --------------------------------- | -------- | ------------------------------------------------------------- |
| `MISSING_MANIFEST`                | error    | 插件目录缺少 `manifest.json`                                  |
| `INVALID_MANIFEST_JSON`           | error    | 本地或远端 manifest 无法解析                                  |
| `NAME_MISMATCH`                   | error    | `manifest.name` 与目录名不一致                                |
| `MANIFEST_MISSING_NAME`           | error    | 缺少 `name`                                                   |
| `MANIFEST_MISSING_VERSION`        | warning  | 缺少 `version`（默认 `0.0.0`）                                |
| `CATEGORY_MISSING`                | error    | `sdkapi` 达门槛但未声明 `category`                            |
| `SDKAPI_BLOCKED`                  | error    | `sdkapi` 缺失、非法、未受支持或低于最低门槛，插件会被直接阻断 |
| `PERMISSION_MISSING`              | warning  | 缺少必需权限授权                                              |
| `UNKNOWN_PERMISSION_IDS`          | warning  | 声明了未知权限 ID                                             |
| `INVALID_FEATURE_COMMANDS`        | warning  | feature.commands 结构不合法                                   |
| `OMNI_TRANSFER_SDK_TOO_LOW`       | warning  | 声明 omniTransfer 但 sdkapi 不满足                            |
| `DUPLICATE_PLUGIN_NAME`           | error    | 插件名冲突                                                    |
| `LOADER_FATAL`                    | error    | 加载器阶段致命异常                                            |
| `DEV_MODE_ACTIVE`                 | warning  | 插件当前运行在 dev 模式                                       |
| `DEV_ADDRESS_INVALID`             | error    | `dev.address` 非法                                            |
| `DEV_SOURCE_DISABLED_IN_PACKAGED` | warning  | 打包环境自动禁用 `dev.source`                                 |
| `DEV_SOURCE_FALLBACK_LOCAL`       | warning  | 远端探活失败后回退本地资产                                    |
| `REMOTE_MANIFEST_FAILED`          | error    | 远端 manifest 失败且本地回退也失败                            |
| `DEV_SERVER_DISCONNECTED`         | warning  | dev server 健康检查断连                                       |
| `LIFECYCLE_SCRIPT_FAILED`         | error    | `index.js` 生命周期脚本执行失败                               |
| `RUNTIME_ERROR`                   | error    | 运行期生命周期/调用异常                                       |
| `AUTO_DISABLED_EXCESSIVE_ERRORS`  | error    | 短时错误过多触发自动停用                                      |
| `INVALID_VIEW_PATH`               | error    | interaction path 非法                                         |
| `PROTOCOL_NOT_ALLOWED`            | error    | 生产环境禁止远端 `http/https` view                            |
| `WIDGET_UNSUPPORTED_TYPE`         | error    | widget 类型不支持                                             |
| `WIDGET_INVALID_DEPENDENCY`       | error    | widget 依赖不允许                                             |
| `WIDGET_COMPILE_FAILED`           | error    | widget 编译失败                                               |

## 环境变量全量说明（逐项）

### A. 业务开关 / 可配置项

布尔开关统一走 `@talex-touch/utils/env` 的 `parseBooleanFlag` / `getBooleanEnv`：`1` / `true` / `yes` / `on` 为开，`0` / `false` / `no` / `off` 为关，其余取各项注明的默认值。

| 变量                                                                                      | 作用                                                                                   | 主要读取位置                                                                    |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `ELECTRON_RENDERER_URL`                                                                   | dev 模式渲染入口 URL（主窗口/CoreBox/OmniPanel/MetaOverlay 等）                        | `src/main/core/touch-app.ts`、`src/main/utils/renderer-url.ts`                  |
| `NODE_ENV`                                                                                | dev/test/prod 行为判断（日志、分析、store API）                                        | 多处（analytics/logger/sentry/store）                                           |
| `BUILD_TYPE`                                                                              | 构建类型（Sentry environment/release 等）                                              | `src/main/modules/sentry/*`、`app-provider.ts`                                  |
| `TUFF_ENABLE_RENDERER_OVERRIDE`                                                           | 是否允许 renderer override 包生效                                                      | `src/main/core/touch-app.ts`、`src/main/modules/update/update-system.ts`        |
| `TUFF_NEXUS_BASE_URL`                                                                     | Core App 运行时 Nexus API 基地址显式覆盖；优先级高于设置页 server mode                 | `packages/utils/env`、Core App Nexus runtime resolver                           |
| `TUFF_DISABLE_NATIVE_OCR`                                                                 | 关闭本地 OCR provider                                                                  | `src/main/modules/ai/intelligence-config.ts`、`packages/tuff-native/index.js`   |
| `TUFF_DISABLE_NATIVE_AUDIO`                                                               | 关闭原生录音 addon（听写界面会提示被环境变量关闭）                                     | `packages/tuff-native/audio.js`                                                 |
| `TUFF_DISABLE_NATIVE_SCREENSHOT`                                                          | 关闭原生截图后端                                                                       | `packages/tuff-native/screenshot-protocol.js`                                   |
| `TUFF_DISABLE_GLOBAL_SHORTCUTS`                                                           | `1` 时跳过全局快捷键注册                                                               | `src/main/modules/global-shortcon.ts`                                           |
| `TUFF_OPAQUE_WINDOWS`                                                                     | 强制不透明窗口（关掉 vibrancy / Mica），特效把启动器弄坏时的恢复开关                   | `src/main/core/window-effects.ts`                                               |
| `TUFF_CLIPBOARD_NATIVE_WATCH`                                                             | 用原生剪贴板变更监听代替轮询                                                           | `src/main/modules/clipboard/clipboard-service.ts`                               |
| `TUFF_FILE_PROVIDER_BASE_WATCH_PATHS`                                                     | 覆盖文件 provider 的基础监听根目录                                                     | `src/main/modules/box-tool/addon/files/file-provider.ts`                        |
| `TUFF_DB_AUX_ENABLED`                                                                     | 辅助库（推荐 / 遥测）开关，默认开                                                      | `src/main/db/runtime-flags.ts`                                                  |
| `TUFF_DB_SEARCH_SPLIT_ENABLED`                                                            | 搜索索引独立为 `search-index.db`，默认开；`0` 是回退到共享文件的急停开关               | `src/main/db/runtime-flags.ts`                                                  |
| `TUFF_DB_QOS_ENABLED`                                                                     | 数据库写入 QoS 调度，默认开                                                            | `src/main/db/runtime-flags.ts`                                                  |
| `TUFF_STARTUP_DEGRADE_ENABLED`                                                            | 启动后 120 s 写入降级窗口，默认开                                                      | `src/main/db/runtime-flags.ts`                                                  |
| `TUFF_STARTUP_ANALYTICS_ENABLED`                                                          | 启动分析采集，默认开                                                                   | `src/main/modules/analytics/startup-analytics.ts`                               |
| `TUFF_RECO_TIME_STATS_REBUILD`                                                            | `1` 时从 usage logs 重建推荐时间统计                                                   | `src/main/modules/box-tool/search-engine/time-stats-aggregator.ts`              |
| `TUFF_INTELLIGENCE_CONTEXT_COREBOX_ONLY`                                                  | `1` 时拒绝非 CoreBox 持有的智能上下文会话                                              | `src/main/modules/ai/intelligence-context-hygiene.ts`                           |
| `TUFF_AGENT_TOOL_CONFIRM_TIMEOUT_MS`                                                      | agent 工具确认超时（最小 250）                                                         | `src/main/modules/tool-gateway/index.ts`                                        |
| `TUFF_SENTRY_TRACES_SAMPLE_RATE`                                                          | 覆盖 Sentry traces 采样率                                                              | `src/main/modules/sentry/sentry-service.ts`                                     |
| `TUFF_PERF_STARTUP_LAG_GRACE_MS`                                                          | 启动后事件循环卡顿的宽限期（默认 2500）                                                | `src/main/utils/perf-monitor.ts`                                                |
| `TUFF_V8_JITLESS`                                                                         | `1` 时以 `--jitless` 启动 V8（macOS Tahoe 崩溃规避，JS 变慢）                          | `src/main/core/precore.ts`                                                      |
| `TUFF_TRACE_DEPRECATION`                                                                  | `1` 时打开 Node 弃用告警堆栈                                                           | `src/main/core/precore.ts`                                                      |
| `TUFF_PLUGIN_TRUST_ROOTS_JSON`                                                            | 替换内置插件签名信任根                                                                 | `src/main/modules/plugin/signature-verifier.ts`                                 |
| `TUFF_PLUGIN_REVOKED_PUBLISHER_KEYS_JSON`                                                 | 已吊销的插件发布者 key id                                                              | `src/main/modules/plugin/signature-verifier.ts`                                 |
| `TUFF_PI_CLI_PATH` / `TUFF_OMP_CLI_PATH` / `TUFF_CODEX_CLI_PATH` / `TUFF_CLAUDE_CLI_PATH` | 钉死对应本地 AI CLI 的可执行文件路径                                                   | `src/main/modules/ai/providers/pi-cli-runtime.ts`                               |
| `TUFF_OMP_AGENT_DIR`                                                                      | omp agent 目录（默认 `~/.omp/agent`）                                                  | `src/main/modules/ai/providers/pi-model-catalog.ts`                             |
| `TUFF_DEV_SERVER_HOST` / `TUFF_DEV_SERVER_PORT`                                           | dev 渲染服务器绑定地址                                                                 | `electron.vite.config.ts`                                                       |
| `TUFF_DEV_PARENT_PID`                                                                     | dev wrapper 写入；该进程消失时应用自行退出                                             | `src/main/utils/dev-process-manager.ts`                                         |
| `TALEX_CONFIG_STORAGE_BACKEND`                                                            | 应用配置后端：`sqlite`（默认）或 `legacy`                                              | `src/main/modules/storage/app-config-repository.ts`                             |
| `TALEX_EVERYTHING_SDK_PATH`                                                               | Windows Everything SDK addon 自定义路径                                                | `src/main/modules/box-tool/addon/files/everything-backend-service.ts`           |
| `TALEX_EVERYTHING_DLL_PATH`                                                               | Windows `Everything64.dll` 路径，供原生 addon 读取（CI 设置；provider 运行时也会写入） | `packages/tuff-native/native/src/everything/addon.cc`、`everything-provider.ts` |
| `TALEX_FILE_PROVIDER_EXTRACT_ICONS`                                                       | FileProvider 图标提取开关（默认开）                                                    | `src/main/modules/box-tool/addon/files/file-provider.ts`                        |
| `TALEX_PLUGIN_LOG_STDOUT`                                                                 | 插件日志同时输出到 stdout                                                              | `packages/utils/plugin/node/logger.ts`                                          |

### B. 启动期内部注入变量（非外部配置）

| 变量                                 | 作用                                       | 写入位置                |
| ------------------------------------ | ------------------------------------------ | ----------------------- |
| `APP_VERSION`                        | 运行时版本号（缺省时从 package.json 注入） | `src/main/polyfills.ts` |
| `DEBUG`                              | debug.talex 文件触发的日志调试开关         | `src/main/polyfills.ts` |
| `ELECTRON_DISABLE_SECURITY_WARNINGS` | 关闭 Electron 安全警告输出                 | `src/main/polyfills.ts` |
| `WS_NO_UTF_8_VALIDATE`               | 禁用 `ws` 可选 `utf-8-validate` addon      | `src/main/index.ts`     |
| `WS_NO_BUFFER_UTIL`                  | 禁用 `ws` 可选 `bufferutil` addon          | `src/main/index.ts`     |

### C. 系统环境变量（只读依赖）

| 变量                | 作用                            | 主要读取位置                                                             |
| ------------------- | ------------------------------- | ------------------------------------------------------------------------ |
| `HOME`              | macOS/Linux 扫描用户应用目录    | `src/main/modules/box-tool/addon/apps/app-scanner.ts`                    |
| `LANG`              | Linux 应用名称本地化解析        | `src/main/modules/box-tool/addon/apps/linux.ts`                          |
| `LOCALAPPDATA`      | Windows Everything/App 扫描路径 | `everything-provider.ts`、`app-scanner.ts`                               |
| `PROGRAMFILES`      | Windows 安装路径扫描            | `everything-provider.ts`、`network-service.ts`、`file-protocol/index.ts` |
| `PROGRAMFILES(X86)` | Windows x86 安装路径扫描        | 同上                                                                     |
| `SystemRoot`        | Windows 系统目录探测            | `network-service.ts`、`file-protocol/index.ts`                           |
| `USERPROFILE`       | Windows 管理员路径特征判断      | `system/permission-checker.ts`                                           |
| `WINDIR`            | Windows 临时写权限检测路径      | `system/permission-checker.ts`                                           |
| `TERM`              | 托盘“在终端中打开”候选命令      | `modules/tray/tray-menu-builder.ts`                                      |
| `TERMINAL`          | 同上（备用）                    | `modules/tray/tray-menu-builder.ts`                                      |

### D. 渲染层构建变量（Vite）

| 变量                   | 作用                            | 主要读取位置                                        |
| ---------------------- | ------------------------------- | --------------------------------------------------- |
| `import.meta.env.DEV`  | 前端 dev 分支（日志/调试 UI）   | `renderer/src/utils/dev-log.ts` 等                  |
| `import.meta.env.MODE` | 前端模式判断（如 about 页显示） | `renderer/src/views/base/settings/SettingAbout.vue` |

### E. 验收 / 基准测试钩子（仅 harness 使用）

由 `scripts/coreapp-packaged-*.ts` 为单次启动设置，正常启动一个都没有。生产代码通过 `src/main/core/acceptance-mode.ts`（`isStartupBenchmarkMode`、`resolveStartupBenchmarkUserDataDir`、`isIsolatedAcceptanceMode`、`isVisibleEvidenceHookEnabled`）读取这些门槛，不再各自直读 `process.env`。

| 变量                                                                                       | 作用                                             |
| ------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| `TUFF_STARTUP_BENCHMARK_ONCE`                                                              | 计时基准启动，跑完自行退出；同时解锁可见证据钩子 |
| `TUFF_STARTUP_BENCHMARK_USER_DATA_DIR`                                                     | 该次启动的隔离 userData / sessionData 根目录     |
| `TUFF_STARTUP_BENCHMARK_DIAG_PATH`                                                         | precore 写 userData 诊断 JSON 的位置             |
| `TUFF_STARTUP_BENCHMARK_EXIT_DELAY_MS`                                                     | 基准启动退出前的延迟（默认 1200）                |
| `TUFF_PACKAGED_ACCEPTANCE_ISOLATED`                                                        | 隔离验收 profile 下跳过单实例锁                  |
| `TUFF_VISIBLE_EVIDENCE_AUTH*` / `TUFF_VISIBLE_EVIDENCE_ASSISTANT_IMAGE_TRANSLATE*`         | 可见证据截图用的脚本化登录与图片翻译结果         |
| `TUFF_MCP_SMOKE*`、`TUFF_PRIVACY_SMOKE_EXPECTED_ENTRYPOINT`、`TUFF_STUB_*`、`TUFF_PROBE_*` | 冒烟测试入口与 CLI 桩                            |

## 可清理变量候选（先列出，不直接删除）

当前暂无待清理候选（前述高/中/低优先项已全部完成收敛）。

## Nexus Runtime API 服务器解析

- Core App 运行时 API 统一由 `packages/utils/env.resolveTuffNexusBaseUrl()` 解析，唯一外部覆盖变量是 `TUFF_NEXUS_BASE_URL`。
- 解析优先级固定为：`TUFF_NEXUS_BASE_URL` 显式覆盖 > 设置页“运行时 API 服务器”为 local > 官方地址 `https://tuff.tagzxia.com`。
- local 模式默认地址为 `http://localhost:3200`，但不会再因为 dev/unpackaged 自动启用；必须由设置页 local 或 `TUFF_NEXUS_BASE_URL` 显式指定。
- 官网、文档、Dashboard、更新源等外链默认值继续使用官方线上地址，不跟随运行时 API server mode。

## 已完成清理项

- `trace-warnings`：已从 `src/main/polyfills.ts` 移除运行时 `process.env` 写入（2026-03-23）。
- `unhandledrejections`：已从 `src/main/polyfills.ts` 移除运行时 `process.env` 写入（2026-03-23）。
- `VITE_DEV_SERVER_URL`（main 侧 fallback）：已移除 `AppProvider` fallback 读取，统一为 `ELECTRON_RENDERER_URL`（2026-03-23）。
- `TALEX_WORKFLOW_DEBUG`：已移除 TPEX Provider 固定 SID 调试开关与对应写盘逻辑（2026-03-23）。
- `TUFF_RELEASE_SIGNATURE_KEY_URL` / `TUFF_RELEASE_SIGNATURE_PUBLIC_KEY_URL`：已从签名公钥 URL 解析中移除兼容别名，统一 `TUFF_UPDATE_*`（2026-03-23）。
- `TUFF_OMNIPANEL_SMOKE`：已移除启动期 OmniPanel 冒烟探针 env gate 与对应逻辑（2026-03-23）。
- `USE_LOCAL_NEXUS`：已移除 PluginStoreService 的本地 Nexus env 特判，统一走 `getTpexApiBase()`（2026-03-23）。
- `VITE_NEXUS_URL` / `NEXUS_API_BASE` / `NEXUS_API_BASE_LOCAL` / `TPEX_API_BASE` / `AUTH_ORIGIN` / `TUFF_LOCAL_BASE_URL`：已停止作为 Core App runtime API 地址解析输入，统一迁移到 `TUFF_NEXUS_BASE_URL`（2026-05-12）。
- `DIST` / `PUBLIC`：已从 `src/main/polyfills.ts` 移除运行时写入，全仓没有读者（2026-10-07）。
- `TUFF_ENCRYPTION_KEY`：已从发布 workflow 移除 secret 注入与「official build」提示，代码里没有读者（2026-10-07）。
- `ELECTRON_PLATFORM` / `ELECTRON_ARCH`：已从 `scripts/build-target.js` 移除，仓库与 electron-builder 都不读（2026-10-07）。
- `BUILD_MAC_LSUIELEMENT`：别名已删，只认 `TUFF_MAC_LSUIELEMENT`（2026-10-07）。
- `TUFF_RELEASE_API_URL` / `TUFF_BUILD_SIGNATURE_URL` / `TUFF_BUILD_SIGNATURE_KEY_URL` / `TUFF_UPDATE_SIGNATURE_KEY_URL` / `TUFF_UPDATE_SIGNATURE_PUBLIC_KEY_URL`：已从上表移除，`apps/core-app/src` 中已无读者（2026-10-07）。
- `smoke:omnipanel` 脚本：已删除，它只设置早已移除的 `TUFF_OMNIPANEL_SMOKE`（2026-10-07）。
- `apps/core-app/.env`（`VITE_CLERK_PUBLISHABLE_KEY`、`VITE_NEXUS_URL`）：已删除，两个键都没有读者（2026-10-07）。
- 布尔开关解析：十份本地拷贝已收敛到 `@talex-touch/utils/env`（2026-10-07）。