Core App 启动链路与运行时变量参考
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）：已移除AppProviderfallback 读取，统一为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）。