DeepChat 主内核边界基线Main Kernel Boundary Baseline解读P5 阶段架构迁移度量体系与落地实践【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat导读本文围绕 DeepChat 仓库中的架构治理文档 docs/architecture/baselines/main-kernel-boundary-baseline.md 展开系统讲解这套主内核边界基线Main Kernel Boundary Baseline的度量指标、分层口径、阶段门禁Phase Gates与配套生成脚本并揭示其背后的目标把渲染进程Renderer从对主进程旧式window.electron/window.api全局桥与 legacy presenter 的直接依赖中彻底剥离让 DeepChat 的主内核演进到 P5 阶段并保持可验证、可回归的干净边界。读完本文你将掌握这套基线里每个 Metric 的业务含义、六个阶段门禁P0–P5的判定信号、raw timer 与 hot path 直接依赖的审计方法以及如何用仓库内的生成脚本在任意时刻重新产出并比对这些基线报告。一、基线报告是什么主内核重构的体检报告DeepChat 在持续重构其 Electron 主进程main kernel与渲染进程renderer之间的边界。为了不让重构变成拆了东墙补西墙仓库用一套脚本化的基线体系来回答三个问题渲染进程还在偷偷触碰主进程的旧接口吗—— 通过usePresenter/window.electron/window.api等调用面计数。热路径依赖是否保持收敛—— 通过 hot path 文件的直接依赖边数。迁移是否按阶段推进且无回退—— 通过 P0–P5 六个阶段门禁的状态信号。这份基线文档正是这套治理体系的当前快照。它于 2026-09-06 生成当前处于P5 阶段与同目录下的 main-kernel-migration-scoreboard.md迁移计分板、main-kernel-migration-scoreboard.json机器可读版本、main-kernel-bridge-register.json桥接登记册以及 dependency-report.md依赖基线报告构成一个互相印证的报告族。从源码结构可以推断这些报告全部由 scripts/generate-architecture-baseline.mjs 一次性生成仓库在 package.json 中提供了对应 npm 脚本pnpm architecture:baseline # 等价于 node scripts/generate-architecture-baseline.mjs该脚本默认把报告写入docs/architecture/baselines/并内置了一道安全护栏assertBaselineOutputSafety会在相关目录存在未提交改动时拒绝覆盖正式基线避免用脏工作区污染权威快照。二、Metric Snapshot15 个度量指标的逐项拆解基线开篇的 Metric Snapshot 是整份报告的核心数据面完整继承如下MetricValuerenderer.usePresenter.count0renderer.business.usePresenter.count0renderer.quarantine.usePresenter.count0renderer.windowElectron.count0renderer.business.windowElectron.count0renderer.quarantine.windowElectron.count0renderer.windowApi.count0renderer.business.windowApi.count0renderer.quarantine.windowApi.count0renderer.quarantine.sourceFile.count0hotpath.directEdge.count2runtime.rawTimer.count246migrated.rawChannel.count0bridge.active.count0bridge.expired.count0这些指标不是手写的而是脚本逐一扫描源码得出的。对照 scripts/generate-architecture-baseline.mjs 中的模式定义可以精确还原每个指标的统计口径2.1 三类旧式访问面指标usePresenter系列统计渲染进程对 legacy presenter 辅助函数的调用。脚本使用正则(?!function\s)\b(?:usePresenter|useLegacyPresenter|useLegacy[A-Z][A-Za-z]*Presenter)\s*\(LEGACY_PRESENTER_HELPER_CALL_PATTERN排除掉函数声明本身只统计真实调用点另外用(?!function\s)\b(?:usePresenter|useLegacyPresenter)\s*\(GENERIC_LEGACY_PRESENTER_CALL_PATTERN作为通用口径。window.electron系列统计渲染进程代码中出现window.electron全局对象的次数WINDOW_ELECTRON_PATTERN。window.api系列统计window.api全局对象的出现次数WINDOW_API_PATTERN。每个系列又按business业务层与quarantine隔离层拆分为三个计数count为总和。2.2 收敛性与运行面指标renderer.quarantine.sourceFile.count隔离层quarantine残留的源文件数当前为 0。hotpath.directEdge.counthot path 文件之间的直接依赖边数当前为 2。runtime.rawTimer.count全量源码中裸setTimeout/setInterval调用总数当前为 246。这是计时器是否仍散落各处、是否应收敛到统一调度的审计信号。migrated.rawChannel.count已迁移路径上残留的裸 IPC / 事件总线通道字符串字面量数量当前为 0。脚本通过INLINE_IPC_CHANNEL_PATTERN匹配window.electron.ipcRenderer/ipcRenderer/ipcMain上的invoke/send/on/once/handle...直连调用与INLINE_EVENTBUS_CHANNEL_PATTERN匹配sendToRenderer/publish/...直连事件在MIGRATED_RAW_CHANNEL_GUARD_PATHS指定的关键路径如src/renderer/src/App.vue、src/preload/createBridge.ts、src/main/routes等上统计。bridge.active.count/bridge.expired.count桥接登记册bridge register中处于active与expired状态的桥接条目数。当前均为 0意味着不存在任何临时兼容桥——旧接口已经彻底移除无需桥接过渡。三、Renderer Single-Track Split业务层与隔离层的双轨划分基线明确给出了渲染进程的单轨single-track划分口径Business layer业务层src/renderer/src/**与src/renderer/settings/**Retired quarantine layer退役隔离层src/renderer/api/legacy/**且必须保持已删除状态脚本侧与之对应的是RENDERER_BUSINESS_ROOTSsrc/renderer/src、src/renderer/settings、src/renderer/services和RENDERER_QUARANTINE_ROOTsrc/renderer/api/legacy生成时会分别对两个层面统计三类 legacy surface得到下表Legacy surfaceBusiness layerQuarantine layerTotallegacy presenter helper000window.electron000window.api000Single-Track的含义是业务代码只允许走一条受控的新式通道preload 桥 类型化 API旧式全局桥一旦在业务层清零即从双轨业务 隔离收敛为单轨。当前快照下三层均为 0说明迁移已经彻底完成。四、Quarantine Exit Snapshot隔离层退出的验收快照隔离层退出quarantine exit快照记录了旧传输层的退休状态Retained capability familynone——renderer legacy transport已被整体退役没有任何能力家族被保留回迁。Source files0 / 0——隔离层现存源文件 0 个允许上限RENDERER_QUARANTINE_EXIT_MAX_FILES为 0 个。Delete conditionalready satisfied——删除条件已经满足重建隔离目录被视为回归regression。这份快照的防御性很强它不只要求现在没有遗留文件还通过 P0/P5 门禁持续监控src/renderer/api/legacy/**是否被重新创建防止历史代码复活。五、Phase GatesP0–P5 六个阶段门禁的判定逻辑阶段门禁表是本报告最具工程价值的表格它把一次大型架构迁移切分成六个可独立验收的阶段每个阶段都绑定明确的判定信号PhaseGate indicatorCurrent signalStatusP0Retired quarantine pathsrc/renderer/api/legacy/**must remain deleted and baseline emits business/retired split metricssrc/renderer/api/legacy/**deleted; split metrics emittedreadyP1Business layer direct legacy presenter helper /window.electron/window.apicounts must reach0legacyPresenter0, window.electron0, window.api0readyP2Business layerconfigPresenterandproviderRuntimehits must reach0configPresenter0, providerRuntime0readyP3Business layer window/device/workspace/project/file/browser/tab presenter hits must reach0window0, device0, workspace0, project0, file0, browser0, tab0readyP4Business layer session residual / skill / mcp / sync / upgrade / dialog / tool presenter hits must reach0agentSession0, skill0, mcp0, sync0, upgrade0, dialog0, tool0readyP5Business layer direct legacy access must be0, and retired quarantine source files must stay at0businessLegacy0/0/0, quarantineSourceFiles0/0ready对照脚本实现可以还原出严谨的判定算法P0由quarantineExists目录src/renderer/api/legacy是否存在决定存在则blocked否则ready。P1p1Ready business.usePresenter 0 business.windowElectron 0 business.windowApi 0。P2对configPresenter与providerRuntime两个 presenter 名逐一用createUsePresenterNamePattern匹配usePresenter(configPresenter)这类带引号参数的调用扫描业务层全部为 0 才算通过。对应PRESENTER_PHASE_GATES.P2。P3对windowPresenter、devicePresenter、workspacePresenter、projectPresenter、filePresenter、yoBrowserPresenter、tabPresenter七个 presenter 逐一清零对应PRESENTER_PHASE_GATES.P3。P4对agentSessionPresenter、skillPresenter、mcpPresenter、syncPresenter、upgradePresenter、dialogPresenter、toolPresenter七个 presenter 逐一清零对应PRESENTER_PHASE_GATES.P4。P5要求P1全部满足且隔离目录不存在、隔离层源文件数不超过 0。每个阶段都从遗留接入面的角度定义验收标准P1 清全局桥P2–P4 按业务域分批清除 presenter 调用P5 收口。当前六道门禁全部ready即迁移已达 P5 终态。六、Hot Path 直接依赖与 Raw Timers运行面审计6.1 Hot Path 直接依赖Hot path 是应用启动与路由分发的最关键链路。脚本定义HOT_PATH_FILES为四个文件src/main/app/composition.ts依赖组合根src/main/routes/index.ts路由出口src/main/agent/deepchat/harness/createDeepChatAgentHarness.tsAgent 运行时工厂src/main/provider/index.tsProvider 出口collectHotPathDirectEdges会解析这四个文件之间的直接 import 边。当前基线只发现 2 条直接边src/main/app/composition.ts - src/main/provider/index.tssrc/main/app/composition.ts - src/main/routes/index.ts也就是说组合根只直接连通 Provider 与 Routes 两大出口而未直接连通 Agent harness——依赖边界收敛得相当干净。从 src/main/app/composition.ts 的头部 import 可以看到组合根承担着WindowPresenter、ProviderRuntime、McpService、SyncService、UpgradeService等大量主进程服务的装配职责该文件共 3593 行是典型的组合根但热路径上它只与provider、routes两个出口有直接边其余依赖都经由中间模块间接传递。6.2 Raw Timers 分布runtime.rawTimer.count 246意味着主进程与渲染业务层仍有 246 处裸setTimeout/setInterval。基线给出了 Top 12 分布完整继承如下src/main/ocr/lightOcrProcessHost.ts: 10src/main/tool/codeMode/runCodeRuntimeManager.ts: 8src/main/provider/auth/githubCopilotDeviceFlow.ts: 6src/main/agent/shared/process/backgroundExecSessionManager.ts: 5src/main/desktop/browser/BrowserTab.ts: 5src/main/provider/aiSdk/runtime.ts: 5src/main/remote/index.ts: 5src/main/app/splashWindow.ts: 4src/main/cli/server.ts: 4src/main/memory/infra/vectorStoreManager.ts: 4src/main/memory/services/maintenanceService.ts: 4src/main/tape/application/traceInspectorHeadWatcher.ts: 4从分布可以推断裸计时器主要聚集在进程宿主OCR 子进程、代码模式运行时、后台执行会话管理、网络轮询GitHub Copilot 设备流、AI SDK 运行时、远程服务与窗口管理BrowserTab、splashWindow等天然需要轮询/心跳的模块中。与usePresenter、window.electron这类必须清零的指标不同raw timer 是治理指标而非淘汰指标——基线的目的是暴露分布为后续是否引入统一调度、是否使用unref或改用受控定时器提供决策依据。6.3 Migrated Path Raw Channel Literalsmigrated.rawChannel.count 0表示在MIGRATED_RAW_CHANNEL_GUARD_PATHS列出的已迁移关键路径渲染层 App.vue、各 ui store、chat-page、preload 桥、主进程 routes/ipc 等上已经不存在任何裸通道字符串字面量直连。这说明 IPC 通信已经完全收敛到类型化通道/契约层shared/contracts不再有散落的魔法字符串。七、从快照到机制这套基线如何落地为工程实践7.1 报告族联动单看一份基线价值有限DeepChat 把它做成了可对账的报告族main-kernel-boundary-baseline.md完整边界细节本文主体main-kernel-migration-scoreboard.md15 个指标 6 个阶段门禁的浓缩计分板用于快速对账main-kernel-migration-scoreboard.json机器可读的同一份数据含program: main-kernel-refactor与hotPathEdges数组可供 CI 断言main-kernel-bridge-register.json桥接登记册当前bridges: []即没有任何活跃或过期桥dependency-report.md四个作用域main / renderer-main / renderer-settings / renderer-shared的依赖边、出入度与环检测详情zero-inbound-candidates.md零入边候选文件清单供删除前人工分类。7.2 与迁移策略文档的配套关系仓库内 docs/architecture/baselines/main-kernel-migration-scoreboard.md 明确说明Phase 0 建立对比基线后续阶段应更新本报告并与该检查点对比。这揭示出该体系的工作循环在迁移起点P0生成权威基线快照每完成一批迁移重新运行node scripts/generate-architecture-baseline.mjs生成新快照对比新快照与 P0 基线确认指标单调收敛、门禁逐级点亮借助assertBaselineOutputSafety防止脏工作区污染权威快照。7.3 与渲染层架构治理的衔接仓库还维护了 renderer-application-boundaries-baseline.json 与对应的 docs/architecture/renderer-application-boundaries/plan.md由pnpm architecture:renderer-baselinepackage.json生成其中--check模式可用于 CI 门禁。主内核边界基线侧重渲染进程不再直连主进程旧接口而 renderer 边界基线侧重渲染进程内部模块的边界职责两者共同构成 DeepChat 进程内外的双层架构护栏。7.4 你可以如何复现与验证在仓库根目录执行pnpm architecture:baseline即可重新生成全部基线报告默认输出到docs/architecture/baselines/。如果只想在临时目录验证而不触碰权威报告可以显式指定输出目录node scripts/generate-architecture-baseline.mjs --output-dir /tmp/deepchat-baseline-check脚本支持的唯一 CLI 参数就是--output-dir见parseOutputDir其余行为全部内置。重新生成后把新快照与当前这份 P5 基线逐项对比即可判断是否发生回归。八、当前状态与后续动作建议从当前快照看DeepChat 主内核重构已经走到 P5 终态渲染层三类旧式访问面usePresenter/window.electron/window.api在业务层与隔离层均为 0隔离目录保持删除无任何回归迹象无活跃/过期桥接通道通信全部收敛到契约层热路径直接依赖仅剩组合根到 Provider 与 Routes 两条边。后续值得关注的治理动作结合源码结构推断非文档结论Raw Timer 收敛246 处裸计时器仍分布于 12 个以上模块可评估是否引入统一计时器抽象把setTimeout/setInterval收敛到单一受控入口并明确心跳类定时器的清理与unref策略。依赖环治理依赖报告显示 main 作用域仍有 14 个环如memory/types.ts - memory/injection.ts - ...、ACP 运行时相关环renderer-main 有 2 个环可作为下一轮解耦候选。CI 化将pnpm architecture:baseline与 scoreboard JSON 接入 CI对renderer.business.*系列指标与quarantine.sourceFile.count施加必须为 0的硬性断言防止旧式访问面以任何形式回潮。参考文件索引基线主文档docs/architecture/baselines/main-kernel-boundary-baseline.md迁移计分板docs/architecture/baselines/main-kernel-migration-scoreboard.md、main-kernel-migration-scoreboard.json桥接登记册docs/architecture/baselines/main-kernel-bridge-register.json依赖报告docs/architecture/baselines/dependency-report.md生成脚本scripts/generate-architecture-baseline.mjsnpm 入口package.json组合根示例src/main/app/composition.ts【免费下载链接】deepchatDeepChat - A smart assistant that connects powerful AI to your personal world项目地址: https://gitcode.com/GitHub_Trending/dee/deepchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考