OfficeDex 开发者上手指南:从源码运行到本地调试的完整教程

原创2026-10-15 21:14:591,718 阅读

OfficeDex 开发者上手指南:从源码运行到本地调试的完整教程

OfficeDex 是首个 AI-Native VibeOfficing 平台:用一句自然语言,直接生成原生的 Word、PPT、Excel 文档。对于想参与贡献的开发者来说,它由 Wails v2(Go 桌面壳)+ React 19 + Vite 前端 + OfficeCLI 子进程 组成。本文带你完成从克隆仓库、安装依赖、一键启动桌面应用,到跑测试、做本地调试的完整流程,10 分钟即可跑起第一个开发环境。

OfficeDex 演示:从一句提示词到生成完整 Word 文档的 30 秒演示

1. 开发前准备:环境与依赖清单

在动手之前,先确认本机工具链。OfficeDex 同时涉及前端(Node/TypeScript)与桌面运行时(Go/Wails),缺一不可:

工具 版本要求 用途
Node.js + npm 20 LTS+ 前端渲染、构建脚本、测试
Go 1.25.0(以 go.mod 为准) Wails 桌面端后端、IPC、持久化
Wails CLI v2 wails dev 开发循环、热重载
平台 WebView 依赖 macOS:Xcode CLT;Windows:WebView2 前端页面的原生容器
officecli 二进制 版本由 package.json 中 officecliVersion 锁定 文档生成引擎,首次运行会自动下载

💡 完整的前置条件说明见 docs/DEVELOPER_ONBOARDING.md,贡献规范见 CONTRIBUTING.md。

2. 克隆仓库与安装依赖

git clone https://gitcode.com/gh_mirrors/of/officedex
cd officedex
npm install

npm install 完成后,注意两点:

  • package.json 中定义了 predev 钩子:每次执行 npm run dev 前会自动运行 scripts/fetch-officecli.mjs,把锁定版本的 officecli 二进制下载到 build/officecli/,无需手动处理。
  • 首次启动前建议先跑一遍类型检查,确认依赖安装完整:
npm run lint   # 即 tsc --noEmit,严格模式类型检查

3. 一键启动桌面应用:npm run dev

开发脚本都集中在 package.json:

npm run dev          # wails dev:完整桌面应用 + 热重载
npm run dev:browser # 仅 Vite 渲染器:浏览器中查看 UI(端口 3100)

OfficeDex 桌面应用首页:选择场景模板或输入自然语言开始生成文档

npm run dev 启动后,你会看到一个原生窗口(而非浏览器标签页),左侧是 New Generation / Dialogue / Tasks 导航,中间是生成入口——这就是 main.go 拉起 Wails 窗口、嵌入 dist/ 前端资源并注入 Go bindings 后的完整运行时。

macOS 专属调试技巧:项目自带 scripts/start-desktop.sh,它会用一个隔离的测试用户数据目录(OfficeDex-Test)启动桌面开发模式,避免污染真实配置:

npm run start:desktop

支持 --dry-run 预览实际命令,也支持 OFFICECLI_SOURCE_DIR、PRESENTATION_SOURCE_DIR 等环境变量指向本地关联仓库。

4. 两种开发模式怎么选?

模式 命令 适用场景
桌面端开发 npm run dev 验证完整的 JS ↔ Go 绑定、文件对话框、真实 WebView 行为
浏览器开发 npm run dev:browser 只改 UI/样式,快速迭代,不需要 Go 编译
模板实验室 npm run demo:pptx-lab 在浏览器里分步查看 PPT「导入模板 → 蒸馏规则 → 槽位填充」管线,见 demo/pptx-template-lab/

浏览器模式访问 Vite 输出的 http://localhost:3100 即可;模板实验室则监听 http://127.0.0.1:4177。

5. OfficeCLI 运行时:本地调试的关键一环

OfficeDex 的文档生成并不在应用进程内完成,而是由独立的 officecli agent-bridge 子进程 负责,前端与 Go 侧通过 JSON-RPC 2.0(stdio 传输)与之通信。开发模式下,CLI 的解析顺序是:

  1. 环境变量 OFFICECLI_DESKTOP_BINARY(指向本地二进制的绝对路径,优先级最高)
  2. PATH 中的 officecli
  3. 自动从 Release 下载(即 prefetch:officecli 的行为)
export OFFICECLI_DESKTOP_BINARY=/absolute/path/to/officecli

OfficeDex 设置页:运行时环境、生成模式与 LLM 配置均可在 GUI 中调整

除了命令行,也可以在 Settings → Runtime Environment 中切换 Hosted / External 模式、指定本地二进制并执行运行时检查。网络较慢时,先检查诊断面板与 bridge 日志中的实际 binary 路径,必要时配置代理后重试。

6. 读懂代码结构:三个入口文件

理解 OfficeDex 最快的方式,是先看清三层结构:

OfficeDex Engine 架构:Memory、Format、Agent 三大核心能力协作生成 Office 文档

层 入口 职责
前端 src/renderer/bridge.ts 所有 Wails 调用的集中层,不要在组件里直接拼 window.go
桌面壳 app.go、main.go App 主对象与 Wails 方法暴露;窗口、资源服务器、bindings 装配
本地运行时 internal/ bridge(子进程池/JSON-RPC)、localstore(SQLite)、preview、settings 等按包拆分

几条高价值的阅读路径:

  • 改 UI:从 src/renderer/ 找页面,先看 src/shell/tokens.css 的设计令牌;
  • 改生成链路:bridge.ts → app.go 的 Wails 方法 → internal/bridge → internal/localstore;
  • 改配置:前端 useSettings.ts ↔ Go 侧 internal/settings/;
  • 看协议定义:src/shared/ 中的前后端共享类型。

各功能入口的对照表见 docs/DEVELOPER_ONBOARDING.md 第 8 节。

7. 本地调试:测试与快速反馈循环

OfficeDex 的测试按变更范围逐级执行(完整命令见 CONTRIBUTING.md):

npm run lint        # 类型检查
npx vitest run      # 渲染器单元测试
npm run test:go     # Go 侧全部单测(含 demo build tag)
npm run test:e2e    # Playwright 真实浏览器 E2E(先执行 test:e2e:install)
npm run test:all    # 一条命令跑完上面所有

针对特定模块的更快反馈:

# bridge / 协议相关
npx vitest run src/renderer/bridge.test.ts

# Go 侧 bridge 包
env -u GOROOT go test ./internal/bridge -count=1

# PPT 编辑器链路
npx vitest run src/renderer/presentation src/shared/presentation*

冒烟验证建议:启动应用后输入一条简单需求(如"生成一份 Q3 销售分析报告"),观察左侧事件流逐步推进,右侧即可内联预览生成的 DOCX / XLSX,无需打开 Office:

OfficeDex 生成 DOCX 后的内联预览:左侧任务事件流,右侧直接渲染 Word 文档内容

⚠️ 注意:bridge 子进程承载任务生命周期,调试时不要随意杀掉正在忙碌的 bridge 进程,否则会产生悬空任务(stranded task)。真实生成 E2E 会消耗模型资源,相关测试有环境变量门控,启用前请确认账号与预算。

8. 常见问题速查(FAQ)

Q1:npm install 卡在 @shimo/* 包上? @shimo/sdk-sheet 等三个包目前只发布在内部 npm registry,外部开发者完整安装前端依赖可能受限。可以先走 .npmrc 配置内部源;若无法访问,Go 侧(internal/、根目录 app_*.go)依然可以完整阅读、构建和测试。详见 CONTRIBUTING.md。

Q2:改了前端代码没生效? npm run dev 依赖热重载,若长时间无响应可检查 Wails 进程是否还活着;只改 UI 时优先用 npm run dev:browser,反馈速度更快。

Q3:本地没有 officecli,启动后生成失败? 确认 prefetch:officecli 是否成功下载(产物在 build/officecli/);或用 OFFICECLI_DESKTOP_BINARY 显式指向本地二进制。解析优先级见上文第 5 节。

Q4:public/presentation、dist/、build/ 里的内容能直接改吗? 不能。这些目录由脚本生成或同步(来源是同级 presentation 仓库),手工修改会在下次构建时被覆盖。请修改源仓库或 staging 脚本。

Q5:提交前还要做什么? 执行 git status --short --branch、git diff --check 核对改动面;UI 改动需与 tokens.css 保持一致;若涉及 i18n,zh.ts 与 en.ts 的键必须成对新增。PR 检查清单见 CONTRIBUTING.md。

9. 延伸阅读

到这里,你已经具备了在 OfficeDex 上进行开发、调试与回归验证的全部基础。推荐流程:先跑通 npm run dev 完成一次真实生成,再按"UI → bridge.ts → app.go → internal/"的链路读一遍代码,最后用 npm run test:all 给第一次改动上保险。Happy hacking!

登录后查看全文
officedex