# StarWork 桌面端技术架构 > star-work 仓库全景解读：AI 原生 Office 套件的三层拼装（统一外壳 + Agent 引擎 + 编辑器层）、进程与运行时模型、五编辑器能力矩阵、AI 改文档的三条硬约束、工作区围栏与云控通道，附四张交互式图表。 --- LLMS 索引： [llms.txt](/llms.txt) --- 依据 `star-work` 仓库源码与 `README.md` 编制，与[云控服务端架构](../star-work-cloud-architecture/)互为表里：本文讲桌面端（终端），彼文讲服务端（治理）。文中四张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。 ## 一、项目概览 {#overview} **StarWork** 是 **AI 原生的企业级 Office 套件**：一个桌面应用里装下文档、表格、演示、PDF、Markdown 五个编辑器，AI 与人工操作共用同一套文档模型——AI 能直接读写文档结构（改段落、改单元格、生成整套演示），而不是只在对话框里隔空聊天。打开和保存都是**标准 Office 格式**，不引入私有格式；本地功能不联网；AI 改动受代码级门禁约束。 | 项 | 值 | |---|---| | 编辑器应用 | **5**（docs / sheets / slides / pdf / markdown） | | 共享能力包 | **14**（`packages/`） | | 可打开或编辑的扩展名 | **8**（`.docx` `.xlsx` `.xlsm` `.xls` `.csv` `.pptx` `.pdf` `.md`） | | 可接入模型服务 | **13**（OpenAI / Claude / Gemini / DeepSeek / Kimi / GLM / Qwen / Doubao / MiniMax / Grok / Mistral / OpenRouter / 自定义端点） | | 五端 AI 领域工具 | 约 **105**（slides 37 最厚，markdown 11 最薄） | | 演示模板回归用例 | **127**（decks 2 + layouts 86 + charts 33 + tables 6） | | 对外语言 | 中文、英文（i18n 框架按 19 种语言搭建，其余译文未验收） | | 层 | 选型 | |---|---| | 桌面框架 | Electron（electron-vite 构建，electron-builder 打包） | | Agent 引擎 | `@earendil-works/pi-coding-agent`（会话、工具调用、技能、模型接入） | | 界面层 | React + TypeScript（各编辑器界面独立构建） | | 原生引擎 | Rust（`xlsx-sidecar` 表格引擎，cargo 构建） | | 包管理 | pnpm workspace（根 + 5 应用 + 14 能力包） | ## 二、总体技术架构 {#architecture} 三层拼装：**通用的 Agent 引擎负责「想」，成熟的编辑器负责「编辑」，自研的是把两者接起来并管得住的那一层。** 全屏打开 ↗ - **统一外壳（自研 `src/`）**：一个窗口 + 顶部标签页；首页工作台（会话、项目管理、记忆、设置）；Agent↔编辑器桥与工作区围栏；云控客户端；国际化与主题。 - **Agent 层**：第三方 `pi-coding-agent` SDK 承担推理与调度；自研的 `workspace-jail` 给全部会话套上文件/命令围栏，`editor-bridge` 为每个编辑器标签页注册领域工具。 - **编辑器层（自研应用层 + 文档引擎）**：五个编辑器应用 + 14 个共享能力包；模型请求经模型网关（one-api 类）以 OpenAI 兼容协议转发，云控下发的网关根地址在客户端做 `/v1` 版本段幂等补全（`model-url.ts`），根治多实例网关偶发 404。 > [!NOTE] > 五个编辑器的底层内核使用成熟第三方组件（表格、文档与 Markdown、演示渲染、PDF 各有其内核，PDF 侧基于 PDF.js 与 PDFium）。「AI 原生」指的是**应用层与自研文档引擎**：约 105 个领域工具、导出质量门禁、预览-确认-事务提交、引用溯源三套约束机制。人工编辑路径完整且独立，不用 AI 也能正常办公。 ## 三、进程与运行时模型 {#process} 全屏打开 ↗ - **一个主进程**承载全部业务逻辑：五个编辑器的主模块都打包进同一个进程，窗口只有一个，靠标签页切换（`tab-manager.ts`）； - **每个打开的文件新增一个界面视图**（`WebContentsView`），首页不占独立视图——界面层进程数 = 1 + 打开的文件数，与应用个数无关； - **真正的操作系统子进程只有一个**：表格的 Rust 原生引擎 `xlsx-sidecar`，第一个表格打开时启动一次（带预热），之后所有表格共用，靠会话标识区分文件； - 界面层拿不到文件系统与系统命令，所有文件读写与外部调用都经主进程受控执行，前后端走**本机 IPC**，不经网络。 ## 四、编辑器与能力包 {#editors} | 应用 | 处理格式 | 能力要点 | 主要引擎包 | |---|---|---|---| | **Docs** 文档 | `.docx` | 流式写作；保存时**按段落打补丁**，AI 只改它实际动过的段落 | `docx-engine` | | **Sheets** 表格 | `.xlsx` `.xlsm` `.xls` `.csv` | Rust 引擎加速；AI 产出走**提议 → 预览 → 事务提交**；公式引用链审计 | `xlsx-sidecar` + 领域层 | | **Slides** 演示 | `.pptx` | 一句话生成整套演示：语义 SVG → 质量门禁 → 原生可编辑 PPTX | `pptx-engine` / `pptx-render` / `svg2pptx` | | **PDF** | `.pdf` | 改文字/内容块/表单域；本地转 Word/PPT/Excel；扫描件 OCR（平台有差异） | `pdf2docx`（PDFium 字级抽取） | | **Markdown** | `.md` | 所见即所得；公式与流程图块（画布/源码双视图） | 内置 | 14 个共享能力包（`packages/`）按职责分四类： | 类别 | 包 | 职责 | |---|---|---| | 文档引擎 | `docx-engine` / `pptx-engine` / `pptx-render` / `svg2pptx` / `pdf2docx` | OOXML 读写与字节级保真、语义 SVG → 原生 PPTX 导出（含质量门禁）、PDF 转换管线 + OCR 辅助 | | AI 能力 | `agent-core` / `ai-provider` / `ai-search` | ReAct 循环、多模型流式接入、联网检索 | | 输入解析 | `file-parse` / `font-metrics` | 附件按类型分流提取（二进制文档→文本，图片→多模态输入）、系统字体度量 | | 应用基础 | `project-store` / `i18n` / `ui` / `electron-utils` | 项目与工作区存储、多语言字典（key 不一致编译期报错）、共用界面组件、桌面公共能力 | ## 五、AI 改文档的三条硬约束 {#constraints} 这些约束不是提示词，是代码里的门禁。 ### 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 实际动过的段落——样式、批注、页码等其余内容原样保留。 ## 六、安全模型 {#security} - **工作区围栏**（`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 去办——模型只决定「目标应用 + 任务内容 + 源文件」，账号/会话/标签页寻址由主进程处理，领域工具与围栏在目标标签页那边。 ## 七、云控通道 {#cloud} 企业侧由云控承担：模型、配置、技能、版本、日志由服务端统一下发与回收，终端使用者不需要配置任何密钥。 全屏打开 ↗ 客户端连接策略三阶段（`src/main/cloud/client.ts`）：启动期按内置清单轮询生产→准生产→测试入口（地址清单编译进 App，云控删不掉）→ 连上后按本地策略重连（间隔封顶 10s + 随机抖动）→ 连续失败够多次自动轮换候选入口。掉线判定由 socket error/close 驱动，睡眠唤醒后心跳失败主动 `revalidate()` 兜底 TCP 僵死的「假连接」。服务端侧协议与部署详见[云控服务端技术架构](../star-work-cloud-architecture/)。 ## 八、工程与质量 {#engineering} - **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/`（完整对话与工具调用流水，排查问题先看这里）。 ## 九、已知限制 {#limits} | # | 限制 | 说明 | |---|---|---| | 1 | Windows / Linux **无系统级沙箱** | 只有工作区围栏 + 命令级拦截，强度低于 macOS | | 2 | **Linux 无 OCR** | 扫描件 PDF 降级为整页位图，降级是显式的 | | 3 | 打包后 OCR 是否随包分发**待实测** | 装包后需用扫描件实测一次 | | 4 | 大工作簿性能**无基准数据** | 架构上与视口相关，但没有实测数字 | | 5 | 其余 17 种语言译文未验收 | 对外只讲中英文 | | 6 | 五端 AI 能力深度不均 | 演示端 37 个工具最厚，Markdown 端 11 个最薄 | | 7 | 首页 Agent **无法生成 Office 文件** | 首页只有 7 个文件工具，没有转交编辑器的通道（编辑器内委派除外） | | 8 | 演示生成为**一次性提交** | 整套页面一次门禁、一次导出落地，没有二次修正机会 | > [!NOTE] > 本文中数字均为仓库实测值，计数方式可复现：模板数来自 `packages/svg2pptx/tests/templates.test.ts` 用例集合，模型服务商数来自 `packages/ai-provider/src/providers.ts`，AI 工具数来自各 `apps/*/src/renderer/ai/*.ts` 的工具定义。没有实测的指标不给数量级结论。 --- 反链： - [星辰智能](/docs/ai/xingchen-intelligence/)