WhyJ-Quant 的架构演进给 Agent 做桌面,先想清楚关窗之后

从 WhyJ-Quant 的现有代码出发,记录借鉴 DSH 与 ZCode 时改变的判断、保留的约束和待验证的风险。

源码审阅与架构取舍 · 2026-10-22

预计阅读 9 分钟

文章目录

给已有 Agent 加桌面界面,最先要拆的是任务与窗口的生命周期。复用 TS 核心、保留三个入口,需要补齐执行归属与恢复。本文来自讨论和源码审阅,重构与长期验证尚未完成。

一句关窗继续,改变了问题

最初,我们希望把已有 Ink 界面做成 exe,保留分析、行情和输入功能。讨论自然落在桌面框架与 TS 复用上。

当前 WhyJ Quant CLI 终端界面:左侧分析与工具执行记录,右侧 Overview 行情与数据源,底部 Composer 输入框和状态栏。 放大查看
图 1 · 当前 CLI 终端界面(用户提供):分析区、Overview、Composer 与状态栏,是桌面图形界面的功能与布局起点。

直到需求补上了一句:关闭窗口后,还要继续工作。任务的寿命必须长于界面连接,成果还要支持回看与追问。

我们查看现有 Electron 入口,发现它通过 PTY 和 xterm 展示终端;关窗处理先隐藏窗口,再发送 Ctrl+D,随后用定时器结束进程树,渲染进程异常也会触发清理。这套行为适合“窗口承载一次终端会话”,却与新的持续工作要求冲突。尚未做故障复现。

我们选定 Electron+React+TypeScript+Vite。Ink 的布局思路可以延续,图形组件仍需重写;同用 TS,无法省掉生命周期的拆分。

参考项目,先看它划开的边界

DSH 与 ZCode 提供了两个值得借鉴的拆分边界。

DSH共享启动
Electron Host CLI runProfile
ZCode共享界面
桌面入口MessagePort Web 入口WebSocket 共享 React Root
图 2 · 源码关系简图:DSH Host;ZCode 的桌面与Web入口。只展示本轮借鉴的边界。

DSH 的桌面 Host调用共享 runProfile,CLI 与桌面沿用启动能力,窗口由 Electron 管理。这让我们看到:可以保留多个入口,而不让每个入口重新组装模型、工具和配置。但 Host 独立成子进程并不意味着它永远存活;该实现收到父进程断连后仍会停止。

ZCode 的桌面和网页加载同一个 React Root,连接分别适配 MessagePort 与 WebSocket。我们借鉴它的界面共享方式,并以其工作台交互为布局参考:量化场景拟安排左侧工作空间与任务、中间对话与输入、右侧行情、证据和成果。这是我们的映射方案。

先借边界,暂不搬完整插件体系和多包结构:额外的构建与版本协调,需要真实需求支撑。

先让推荐接受现有系统的约束,再用最小的实际改动减少关键未知。

共享代码,还要明确谁在执行

现有 agent、runtime、quant、source、storage 已有职责划分,保留这些资产比重排目录更重要。需要先处理的是 AppRuntime:它已有提交、取消和状态能力,同时也带着打开配置、恢复面板等界面回调,还引用了 TUI 的类型。若直接给网页调用,界面耦合也会一起带过去。

先提取应用服务,面板、焦点和快捷键留给界面。三个入口共享契约,浏览器与桌面共享 React UI,CLI 保留 Ink TUI;逐条迁移调用链。

CLI / TUIapps/cli 启动
apps/tui 渲染
Electron 桌面apps/web · React UI
浏览器apps/web · React UI
Host · 共享应用服务提交、取消、会话、状态同步
Agent / Runtime研究、行情、计算
Storage进度与成果
图 3 · 拟议结构:三个入口,共享能力。CLI 可独立调用服务;访问同一任务时,各入口连接同一 Host。

共享代码,不等于共享正在执行的任务。各自创建 Agent 会产生两份状态。跨入口接续任务,必须连接同一 Host,并对齐工作空间、会话和运行标识;独立单次 CLI 可直调服务。

因此,目录先收敛为下面的目标结构,尚未实施迁移:

apps/
  cli/          启动参数、终端/单次命令/网页模式
  tui/          Ink 布局、输入与终端刷新
  desktop/      Electron、preload、窗口与安装
  web/          桌面与浏览器共用的 React UI
src/
  app/          bootstrap、Host、应用服务
  commands/     命令解析与分发(逐步由 src/cli 收敛)
  agent/ runtime/ quant/ source/ storage/ types/
site/           公开网站

apps/cli 决定怎么启动,commands 解释命令,apps/tui 和 apps/web 分别渲染两种界面。两套渲染器分别处理终端按键和网页焦点。

网页是正式入口,也是调试入口

保留 whyj CLI 与 Ink TUI,一个命令名承接不同入口。沿用现有默认行为和专业子命令,只新增网页模式:

表 1 · 启动方式与状态

启动方式用途与状态
whyj保留交互式 TUI、终端布局与按键。
whyj -c "/help"保留单次命令;脚本可加 --json。
whyj web拟新增:连接或启动 Host,自动打开网页。
双击桌面图标拟改为加载共享 React UI,补充托盘与原生能力。
whyj doctor保留环境诊断。

交互入口共用 bootstrap:定位工作空间 → 查找兼容 Host → 连接或启动 → 打开界面。用启动锁与就绪检查避免并发创建两套后台;单次命令按需加载,帮助和版本查询不启动 Host。

网页正式使用加载构建产物,无需 Vite;开发时再接热更新。默认绑定本机回环地址,保留来源与令牌检查。开发脚本拟统一如下,后两项尚待新增:

bun run dev           # 保留 CLI/TUI 开发
bun run dev:web       # Host + Vite
bun run dev:desktop   # Host + Vite + Electron

开发编排负责就绪等待、日志与进程清理。关闭网页只断开连接,桌面关窗进入托盘;TUI 退出不误停共享 Host。明确停止后台时提示未完成任务,并按归属清理资源。

保存过成果,不代表任务能恢复

追问和保存已有实现,长期运行却仍有缺口。

研究 manager在本次服务达到 50 次研究后要求保存并重启,追问历史也有上限;它还承担单股研究规则。对一个范围明确的实验,这些限制是合理护栏。要变成长期工作台,需要补上已完成 Agent、订阅和临时状态的回收,以及历史按需加载。直接去掉次数限制,只是把资源问题推迟暴露。

研究成果存储只接受完成状态,保存的版本不可变。它保护引用依据,却无法单独说明中断时的工作现场。成果是可引用的版本,进度是可继续的工作现场。两者需要不同的保存语义。

保留不可变成果,消息、运行状态与关键事件自动落盘,优先复用 session journal。若工具已写文件但结果未记录,恢复时必须核对副作用;无法判断就标为待确认,不能直接重跑。

现有 HTTP+SSE 推送会复制完整运行对象,长对话成本尚未测量。首版沿用 Bun 与 HTTP+SSE,再决定是否采用快照加带序号的增量;节省流量的代价是缺口检测与重新同步。

断开订阅只结束观察,取消必须是明确命令,避免刷新界面误停研究。

测试跟着职责迁移,验收跨越入口

现有 测试入口区分模块与集成测试:多数模块用例在 src/*/test,应用集成在 tests/app,架构约束在 tests/architecture;桌面另有 smoke 和安装检查。研究工作区已有取消、追问、保存重载和断流不取消等用例。重构应继承这些行为资产。

建议保留模块就近测试,将共享行为集中验证,各入口只补适配与少量端到端用例。以下是目标组织,尚未迁移:

表 2 · 测试职责与位置

测试位置应该守住的行为
src/*/test保留计算、取数与存储的测试。服务提取后,用例随职责进入 src/app/services/test,复用固定数据与可控假 Agent。
tests/app
tests/contracts
保留应用组装测试,新增直连服务与 Host API 的共用契约用例:提交、取消、追问、保存,对齐状态和成果;不比较模型回复原文。
apps/*/testCLI 检查参数、输出与退出码;Web 检查输入、焦点和订阅;Electron 检查窗口、托盘与连接。TUI 专属用例迁入 apps/tui/test,检查按键、粘贴、滚动和窄终端。
tests/e2e少量跨入口场景使用真实 Host、临时工作空间与假模型;网页和桌面走真实界面,CLI/TUI 走进程或伪终端。

旧入口先锁定行为,新服务接过同组断言,旧入口保留接线测试。假 Agent 控制延迟、失败和迟到事件,各测试隔离目录、端口与时钟。

启动回归还要检查:默认 whyj 与旧参数兼容,重复启动只创建一个 Host,退出单个界面不误停共享任务。

验收链:网页提交 → 桌面接回同一运行 → 关窗仍执行 → CLI 取消 → 迟到事件不能覆盖取消状态 → 显式继续并保存、追问。另测运行中终止 Host 后能定位中断。检查运行标识、终态与成果版本,并验证重试不重复执行、副作用不明时不自动重跑。

还有一个真实的迁移陷阱:当前桌面 smoke期待关窗后进程退出。新需求落地时,应拆成“关窗保活”和“明确退出后清理”两组断言,不能为了旧测试通过而保留旧行为。

CI 也要分层。每个 PR 跑类型、架构、模块与契约测试;改动入口再跑对应适配及端到端检查。定时任务跑长时间运行和真实 provider 冒烟;发布前在干净 Windows 环境验证安装、启动、升级及数据保留。真实模型的质量评估单列,记录模型、样本与预算。

迁入 apps/ 时同步更新测试发现规则、test:fence 和 CI;显式排除需独立运行的桌面与端到端套件,继续隔离手工产物生成器。现有 npm test 不包含桌面套件,全绿不等于三个入口都通过。

再测输入、滚动、重连延迟与跨日资源增长。完全退出后继续运行另做守护设计,休眠不在持续执行承诺内。顺序仍是本地工作台、桌面产品化、手机端。

本文依据固定版本;测试组织另补查 WhyJ-Quant 0548a92,链接随文给出。图 1 是现有 CLI 截图;图 2 是源码关系简图;图 3 是演进建议。文中的风险来自代码审阅与设计推演,尚无性能测量或长期运行验收结果。

WhyJ 2026返回顶部

插图