OfficeDex 开发者上手指南:从源码运行到本地调试的完整教程
OfficeDex 开发者上手指南:从源码运行到本地调试的完整教程
OfficeDex 是首个 AI-Native VibeOfficing 平台:用一句自然语言,直接生成原生的 Word、PPT、Excel 文档。对于想参与贡献的开发者来说,它由 Wails v2(Go 桌面壳)+ React 19 + Vite 前端 + OfficeCLI 子进程 组成。本文带你完成从克隆仓库、安装依赖、一键启动桌面应用,到跑测试、做本地调试的完整流程,10 分钟即可跑起第一个开发环境。
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)
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 的解析顺序是:
- 环境变量
OFFICECLI_DESKTOP_BINARY(指向本地二进制的绝对路径,优先级最高) PATH中的officecli- 自动从 Release 下载(即
prefetch:officecli的行为)
export OFFICECLI_DESKTOP_BINARY=/absolute/path/to/officecli
除了命令行,也可以在 Settings → Runtime Environment 中切换 Hosted / External 模式、指定本地二进制并执行运行时检查。网络较慢时,先检查诊断面板与 bridge 日志中的实际 binary 路径,必要时配置代理后重试。
6. 读懂代码结构:三个入口文件
理解 OfficeDex 最快的方式,是先看清三层结构:
| 层 | 入口 | 职责 |
|---|---|---|
| 前端 | 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:
⚠️ 注意: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. 延伸阅读
- docs/DEVELOPER_ONBOARDING.md —— 架构、目录结构、数据流与常见陷阱的完整开发者文档
- docs/README.md —— docs 目录下各篇文档的索引
- AGENTS.md —— 本地网络代理、开发约定与验收规则
- docs/screenshots/ —— README 引用的全部功能截图
- playwright.config.ts —— E2E 浏览器测试配置
到这里,你已经具备了在 OfficeDex 上进行开发、调试与回归验证的全部基础。推荐流程:先跑通 npm run dev 完成一次真实生成,再按"UI → bridge.ts → app.go → internal/"的链路读一遍代码,最后用 npm run test:all 给第一次改动上保险。Happy hacking!




