给已有 Agent 加桌面界面,最先要拆的是任务与窗口的生命周期。复用 TS 核心、保留三个入口,需要补齐执行归属与恢复。本文来自讨论和源码审阅,重构与长期验证尚未完成。
一句关窗继续,改变了问题
最初,我们希望把已有 Ink 界面做成 exe,保留分析、行情和输入功能。讨论自然落在桌面框架与 TS 复用上。
放大查看
直到需求补上了一句:关闭窗口后,还要继续工作。任务的寿命必须长于界面连接,成果还要支持回看与追问。
我们查看现有 Electron 入口,发现它通过 PTY 和 xterm 展示终端;关窗处理先隐藏窗口,再发送 Ctrl+D,随后用定时器结束进程树,渲染进程异常也会触发清理。这套行为适合“窗口承载一次终端会话”,却与新的持续工作要求冲突。尚未做故障复现。
我们选定 Electron+React+TypeScript+Vite。Ink 的布局思路可以延续,图形组件仍需重写;同用 TS,无法省掉生命周期的拆分。
参考项目,先看它划开的边界
DSH 与 ZCode 提供了两个值得借鉴的拆分边界。
DSH 的桌面 Host调用共享 runProfile,CLI 与桌面沿用启动能力,窗口由 Electron 管理。这让我们看到:可以保留多个入口,而不让每个入口重新组装模型、工具和配置。但 Host 独立成子进程并不意味着它永远存活;该实现收到父进程断连后仍会停止。
ZCode 的桌面和网页加载同一个 React Root,连接分别适配 MessagePort 与 WebSocket。我们借鉴它的界面共享方式,并以其工作台交互为布局参考:量化场景拟安排左侧工作空间与任务、中间对话与输入、右侧行情、证据和成果。这是我们的映射方案。
先借边界,暂不搬完整插件体系和多包结构:额外的构建与版本协调,需要真实需求支撑。
先让推荐接受现有系统的约束,再用最小的实际改动减少关键未知。
共享代码,还要明确谁在执行
现有 agent、runtime、quant、source、storage 已有职责划分,保留这些资产比重排目录更重要。需要先处理的是 AppRuntime:它已有提交、取消和状态能力,同时也带着打开配置、恢复面板等界面回调,还引用了 TUI 的类型。若直接给网页调用,界面耦合也会一起带过去。
先提取应用服务,面板、焦点和快捷键留给界面。三个入口共享契约,浏览器与桌面共享 React UI,CLI 保留 Ink TUI;逐条迁移调用链。
apps/tui 渲染
共享代码,不等于共享正在执行的任务。各自创建 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/apptests/ | 保留应用组装测试,新增直连服务与 Host API 的共用契约用例:提交、取消、追问、保存,对齐状态和成果;不比较模型回复原文。 |
apps/*/test | CLI 检查参数、输出与退出码;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 是演进建议。文中的风险来自代码审阅与设计推演,尚无性能测量或长期运行验收结果。