作者:charles he
AI 辅助说明:本文使用 AI 辅助阅读源码、组织结构和起草文字。代码事实以文末列出的源码为依据;文中的工程建议不等于已经实现的功能。
把 Web 业务和桌面助手放进同一个仓库,最容易先解决的是目录问题,最容易留下的是权限问题:React 页面能否直接发业务命令?打开业务窗口是否就算接通了助手?侧栏切页会不会中断对话?
CDF(Composable Delivery Foundation)本次整理为 monorepo,把 Frappe 业务模块与 React/Electron 桌面代码放在一起维护。这里的“多端”指 Web 业务空间与桌面工作台,不包含一个凭空补出的移动客户端。下面不展开产品功能清单,而是沿着一次点击的路径读源码:组件内切页 → 主进程打开业务窗口 → 跨边界能力注入。
一、同叫“导航”,其实有三种不同操作
桌面壳的 src/App.tsx 使用 page 状态切换工作台、助手、连接设置和应用状态。这是本地 React UI 的导航,不是浏览器跳转,也不是业务权限切换。
业务空间则由 electron/main/index.ts 中的 openWorkspace() 打开独立 BrowserWindow,加载配置站点的 /workspace。两者需要分开理解:
| 操作 | 状态归谁管理 | 不应该顺带发生什么 |
|---|---|---|
| 点击桌面侧栏 | React 页面状态 | 不应把切页等同于取消任务 |
| 打开业务空间 | Electron 主进程和业务站点 | 不应把桌面 preload 自动交给远程页面 |
| 保存业务地址 | 主进程连接配置 | 不应把“地址保存成功”写成“业务已登录” |
App.tsx 的业务状态文案也保留了这个区别:地址存在时显示“待连接验证”。主进程快照中的业务状态是 configured 或 not-configured,而不是根据 URL 是否存在就推断登录成功。
这个细节比一个漂亮的绿色圆点更重要。桌面服务、执行内核、业务站点属于不同故障域:本机服务起来了,远程站点可能不可达;业务页面能登录,模型也可能没有通过连接测试。把这些情况合成一个 ready,界面会替后端做出没有依据的承诺。
二、保留组件实例,和保留任务执行,不是一回事
助手没有随着侧栏切页直接卸载。src/App.tsx 的实际 JSX 是:
{data&&<div hidden={page!=='assistant'} className={page!=='assistant'?'assistant-hidden':undefined}><Assistant hostState={data.kernel} businessHost={businessHost}/></div>}
这里先等待桌面快照,再挂载助手;之后通过 hidden 控制可见性。对 React 来说,切到设置页时助手仍在树中,组件局部状态不会仅因这次切页而销毁。
但不要把这解释成“任务一定能跨重启恢复”。隐藏组件、关闭窗口、重建窗口、退出应用是四件事。当前主进程还维护了进度事件的 frame、runId 和 epoch:发送进度前检查事件是否属于当前主窗口、当前执行、当前窗口代次。窗口被替换后,旧执行的输出不会自动转交给新窗口。
这是一个值得复用的思路:UI 身份也有生命周期。 仅比较任务 ID 不足以证明新页面应该接收旧页面的异步结果。组件级状态保留解决切页体验,主进程的身份检查解决事件投递边界,两者不能互相代替。
三、preload 暴露动词,不暴露任意 IPC
electron/preload/index.ts 通过 contextBridge 暴露 window.cdf。截取其中几项:
snapshot: () => ipcRenderer.invoke('cdf:snapshot'),
saveEndpoint: (endpoint: string) => ipcRenderer.invoke('cdf:save-endpoint', endpoint),
openWorkspace: () => ipcRenderer.invoke('cdf:open-workspace'),
quit: () => ipcRenderer.invoke('cdf:quit'),
这里没有把 ipcRenderer.invoke(channel, payload) 原样塞给 React。页面拿到的是有限的业务动词,而不是自行选择 IPC 通道的能力。
不过,有限接口只是第一道边界。TypeScript 类型会在运行时消失,所以主进程仍要验证来源与参数。electron/main/index.ts 的 trusted() 同时检查:
- sender 是否为桌面主窗口的
webContents; - senderFrame 是否为该窗口的 mainFrame;
- frame URL 是否精确等于预期开发地址或本地页面地址。
注册处理器的 handle() 在执行实际 action 之前调用这个检查。部分模型接口还用 fields() 检查参数对象的键集合,拒绝额外字段或缺失字段。
因此,“有类型”与“被授权调用”是两层不同问题。前者帮助开发者,后者必须在真正拥有能力的进程里执行。
四、远程业务页面不是桌面壳的另一个组件
业务窗口的创建参数没有配置桌面 preload,同时明确使用 nodeIntegration:false、contextIsolation:true、sandbox:true,并采用独立的持久化会话分区 persist:cdf-business。
这不等于“无痕浏览器”:persist: 恰恰意味着会话可以持久化。它的意义在于把业务站点会话与桌面壳默认会话分开,而不是声称登录信息不会在本机留下任何状态。
连接地址和后续导航也有两套约束。在 electron/policies.ts 中,连接地址只接受 HTTPS,或明确列出的本机 HTTP 地址;拒绝用户名、密码、非根路径、查询串和片段。后续导航则检查同源:
export function allowNavigation(origin: string, target: string): boolean {
try { const url = new URL(target); return !url.username && !url.password && url.origin === origin && ['https:', 'http:'].includes(url.protocol) } catch { return false }
}
业务窗口把这一判断用于导航、重定向和新窗口请求。新窗口请求被拒绝;同源目标可以改为在当前业务窗口加载。
代价也很明确:跨域 SSO 跳转可能被这套规则挡住。如果以后要支持它,应设计特定认证流程和回跳校验,而不是为了让登录“先跑通”就取消导航约束。同源限制不是完整的站点信任证明,但它让当前允许的导航范围可以被读懂、被测试。
五、最值得保留的一行:businessHost = null
打开 Frappe 页面,不意味着桌面助手已拥有修改 Frappe 数据的能力。当前 src/main.tsx 渲染的是 <App />,没有注入业务 host;App 的入口签名明确为:
export default function App({businessHost = null}:{businessHost?:BusinessHost|null} = {}){
src/business/BusinessHost.ts 定义了一个很窄的接口:
export interface BusinessHost {
readonly scope: Binding
readonly preview: Readonly<ReadbackExpectation>
readonly canConfirm: boolean
confirm(): Promise<void>
readback(): Promise<BusinessReadback>
}
注意,这只是端口,不是已经接好的运行时。该文件的 hostFromAdapter() 是供未来 host 与离线注入测试使用的同进程组合 helper;它不创建 transport,也不创建 journal。adapter.ts 同样要求外部注入传输和写入意图记录能力。
因此不能把这组文件介绍成“已实现可信宿主,React 可以安全执行真实业务”。准确说法是:源码已经表达了能力接口及校验逻辑,但默认桌面入口没有接入业务 host。生产连接还需要把认证、会话、凭据和持久化意图放在可信边界内,只向 renderer 传递受限 DTO。
这个空值不是为了凑一个待办项。它让“设计上预留的能力”与“用户现在实际拥有的能力”在代码里有可见区别。
六、monorepo 应该统一变更,不应该统一权限
将两端放在一个仓库的收益,是一项协议变更能一起检查:Python 端增加字段、TypeScript 解码器接受字段、React 展示对应状态,可以放在同一次变更里评审。它不要求 Python 和 Electron 共享包管理器,更不要求两端共享运行时身份。
对这类仓库,我建议按边界组织验证,而不只按文件扩展名组织:
- 导航策略:远程 HTTP、携带凭据的 URL、跨源 redirect 应被拒绝;明确的本机 HTTP 例外应单独覆盖。
- IPC 来源:正确 channel 但错误 frame 也应被拒绝,不能只测试参数 happy path。
- React 生命周期:切页保留组件;替换窗口后旧进度不能污染新页面。
- 业务端口:未注入 host 时保持不可用;注入测试替身时验证交互,但不能据此宣称真实业务闭环完成。
- 仓库交付:两端分别说明构建依赖、入口和许可证来源,避免一个根目录脚本暗中启动全部服务。
以上是验证建议,不是本文执行过的测试报告。当前模型调用、真实 native 环境与业务端到端闭环仍未验收;这里讨论的是源码能够支撑的边界设计,而不是安装包发布或产品可用性结论。
收尾:比“多端复用”更重要的是少复用什么
这次读代码最有价值的地方,不是 React 能否装进 Electron,而是哪些东西没有被顺手共享:业务页没有拿到桌面 preload;地址配置没有冒充登录状态;组件可见性没有冒充进程生命周期;业务端口也没有因为接口存在就默认启用。
monorepo 让这些约束可以在同一处检查。真正应当统一的是协议和变更证据,而不是把不同端的权限揉成一个全能对象。
源码阅读入口
本文对应已公开提交 ef2f472。业务源码位于根目录 apps/,桌面源码位于 desktop/;下列链接固定到该版本。
许可说明:代码许可沿各来源文件、组件 LICENSE 和第三方 NOTICE,不因合入 monorepo 或本文引用而重新统一授权。文章作者为 charles he。