StarWork 桌面端技术架构

依据 star-work 仓库源码与 README.md 编制，与云控服务端架构互为表里：本文讲桌面端（终端），彼文讲服务端（治理）。文中四张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。

一、项目概览

StarWork 是 AI 原生的企业级 Office 套件：一个桌面应用里装下文档、表格、演示、PDF、Markdown 五个编辑器，AI 与人工操作共用同一套文档模型——AI 能直接读写文档结构（改段落、改单元格、生成整套演示），而不是只在对话框里隔空聊天。打开和保存都是标准 Office 格式，不引入私有格式；本地功能不联网；AI 改动受代码级门禁约束。

二、总体技术架构

三层拼装：通用的 Agent 引擎负责「想」，成熟的编辑器负责「编辑」，自研的是把两者接起来并管得住的那一层。

全屏打开 ↗

• 统一外壳（自研 src/）：一个窗口 + 顶部标签页；首页工作台（会话、项目管理、记忆、设置）；Agent↔编辑器桥与工作区围栏；云控客户端；国际化与主题。
• Agent 层：第三方 pi-coding-agent SDK 承担推理与调度；自研的 workspace-jail 给全部会话套上文件/命令围栏，editor-bridge 为每个编辑器标签页注册领域工具。
• 编辑器层（自研应用层 + 文档引擎）：五个编辑器应用 + 14 个共享能力包；模型请求经模型网关（one-api 类）以 OpenAI 兼容协议转发，云控下发的网关根地址在客户端做 /v1 版本段幂等补全（model-url.ts），根治多实例网关偶发 404。

三、进程与运行时模型

全屏打开 ↗

• 一个主进程承载全部业务逻辑：五个编辑器的主模块都打包进同一个进程，窗口只有一个，靠标签页切换（tab-manager.ts）；
• 每个打开的文件新增一个界面视图（WebContentsView），首页不占独立视图——界面层进程数 = 1 + 打开的文件数，与应用个数无关；
• 真正的操作系统子进程只有一个：表格的 Rust 原生引擎 xlsx-sidecar，第一个表格打开时启动一次（带预热），之后所有表格共用，靠会话标识区分文件；
• 界面层拿不到文件系统与系统命令，所有文件读写与外部调用都经主进程受控执行，前后端走本机 IPC，不经网络。

四、编辑器与能力包

14 个共享能力包（packages/）按职责分四类：

五、AI 改文档的三条硬约束

这些约束不是提示词，是代码里的门禁。

5.1 演示：逐页生成与导出门禁

全屏打开 ↗

一句话任务进入后：附件与联网检索结果分配 [S#] 来源编号 → 大纲按页面角色逐页规划 → 模型流式生成语义 SVG（deck-stream）→ 每页过质量门禁（svg2pptx/quality.ts，与导出器共用同一渲染前端——凡是门禁放过的，导出器必然能渲染）→ 全套就绪后导出原生可编辑 PPTX，引用编号写入演讲者备注。

• 阻断项：页面角色缺失、元素越界、引用编号悬空 → 阻断导出；附件未读完 → 拒绝生成整套演示；
• 告警项：精确数字无来源 → 告警不阻断；
• 回归保障：127 份真实模板（decks/layouts/charts/tables）在 templates.test.ts 中持续验证产物一致性，改动导出器必跑。

5.2 表格：提议 → 预览 → 事务提交

AI 产出不直接改文件：先过 schema 校验 → 修订冲突检测 → 生成预览 → 使用者确认后才作为事务提交（apps/sheets/src/renderer/ai/ 的 response-verify / retry-prune / 编辑队列）。公式引用链可追踪审计（formula-audit）。大工作簿的内存占用与整表规模解耦、只与视口相关（架构如此，暂无实测基准）。

5.3 文档：按段落打补丁

docx-engine 以带 docxIndex 锚点的 Block 树解析 docx，保存时只重写 AI 实际动过的段落——样式、批注、页码等其余内容原样保留。

六、安全模型

• 工作区围栏（src/main/pi/workspace-jail.ts，1629 行）：全部 pi 会话共用；read/ls/grep/find/write/edit 路径越出工作区直接抛错，read 按扩展名分流——二进制文档经 file-parse 提取文本，图片保持裸字节交给多模态模型；
• 命令沙箱：macOS 用 sandbox-exec 硬沙箱（读写只放行工作区/临时目录/工具链缓存，$HOME 凭证目录不可读写）；Windows 无等价沙箱，用 spawnHook 命令级拦截（拦得住字面量，拦不住变量拼接）——如实说：强度低于 macOS；
• 网络：sandbox-net 沙箱代理受控放行；云控通道 TLS + 设备令牌；
• 委派（pi/delegate.ts）：把一整件事交给某个编辑器标签页的 agent 去办——模型只决定「目标应用 + 任务内容 + 源文件」，账号/会话/标签页寻址由主进程处理，领域工具与围栏在目标标签页那边。

七、云控通道

企业侧由云控承担：模型、配置、技能、版本、日志由服务端统一下发与回收，终端使用者不需要配置任何密钥。

全屏打开 ↗

客户端连接策略三阶段（src/main/cloud/client.ts）：启动期按内置清单轮询生产→准生产→测试入口（地址清单编译进 App，云控删不掉）→ 连上后按本地策略重连（间隔封顶 10s + 随机抖动）→ 连续失败够多次自动轮换候选入口。掉线判定由 socket error/close 驱动，睡眠唤醒后心跳失败主动 revalidate() 兜底 TCP 僵死的「假连接」。服务端侧协议与部署详见云控服务端技术架构。

八、工程与质量

• monorepo：根（外壳）+ apps/（5 编辑器，每个 = 主模块 + 界面层 + preload + shared）+ packages/（14 能力包），pnpm workspace；
• 开发形态：pnpm dev 并行起五个编辑器渲染服务（5173–5177，HMR）+ 外壳（首页 5199）；云控固定连本机 ws://127.0.0.1:8090；改主进程代码需重启 dev；
• 质量门禁：pnpm typecheck（主进程 + 首页 + 五编辑器）、ESLint + Prettier、vitest 单测分布在 apps/*/tests 与 packages/*/tests（实测合计 672 个 *.test.ts）；表格端另有 gate 全量门禁（typecheck + 夹具 + cargo test + 兼容性校验）；
• 运行期数据（开发形态）：~/Library/Application Support/StarWork Dev/（Windows %APPDATA%/StarWork Dev/）——home/projects.json（工作区）、app-settings.json、cloud-config.json、pi-sdk/models.json（云控下发的模型目录）、pi-sdk/sessions/ 与 home/pi-sessions/（完整对话与工具调用流水，排查问题先看这里）。

九、已知限制