快速开始

本指南帮助你在本地完成 Automa Agent 的开发环境搭建与首次运行。

环境要求

项目	版本
Node.js	>= 18.x
pnpm	>= 8.x
操作系统	Windows 10+、macOS 10.15+、Linux

Windows 原生能力

屏幕识别、虚拟显示器等功能依赖 Rust 原生模块，请参阅 desktop_selection 构建说明。

安装

git clone git@codeup.aliyun.com:6627798cd833774c93cc0790/erp_automa.git
cd erp_automa
pnpm install

# 重建 Electron 原生依赖（版本需与 package.json 中 electron 一致）
npm rebuild better-sqlite3 --runtime=electron --target=30.5.1

开发

pnpm dev

首次启动将初始化 SQLite 数据库与默认配置。工作流设计器、AI 工作台等功能均在桌面应用内使用。

构建发布

pnpm build:win    # Windows
pnpm build:mac    # macOS
pnpm build:linux  # Linux

构建前会自动执行文档与类型生成（gen:executor-docs、gen:handler-typings、gen:bizapi-docs）。

文档站点

项目内置 VitePress 官网，支持全文搜索与静态部署：

pnpm docs:dev      # 本地预览 http://localhost:5173
pnpm docs:build    # 构建 → docs/.vitepress/dist
pnpm docs:preview  # 预览构建结果

部署官网

平台	说明
Nginx / OSS	上传 dist 目录，配置 SPA fallback 至 index.html
Vercel / Netlify	构建命令 pnpm docs:build，输出目录 docs/.vitepress/dist
内网服务器	rsync -av docs/.vitepress/dist/ user@host:/var/www/automa-agent/

自动生成参考

docs:build 会先执行 gen:executor-docs 与 gen:bizapi-docs，再同步至 docs/reference/。

常见问题

Q：better-sqlite3 加载失败？

执行上方 npm rebuild 命令，确保 --target 与 Electron 版本一致。

Q：原生模块编译失败？

进入 native/desktop_selection 执行 npm run build，详见 BUILD 文档。

Q：更多问题？

参见 完整项目指南 — 常见问题。