4.2 KiB
GoodBuddy 开发与构建
环境要求
- Node.js 24，或当前锁定依赖明确支持的 Node.js 版本
- npm
- Windows、Linux 或 macOS
安装锁定依赖：
npm ci
不要将 API Key、访问令牌、私有模型地址或本地数据库提交到仓库。
本地开发
启动开发环境：
npm run dev
预览已经生成的生产构建：
npm run build
npm start
质量验证
提交或打包前运行：
npm test
npm run typecheck
npm run lint
监听模式：
npm run test:watch
真实 Runtime 端到端测试默认关闭。配置兼容模型凭据后，显式启用：
GOODBUDDY_RUN_RUNTIME_E2E=1 npm test -- src/main/agent/runtime-e2e.manual.test.ts
该测试可能发起真实外部模型调用。测试不会输出 API Key，文件操作在临时工作区中执行。
生产构建
生成 Electron Main、Preload 和 Renderer 生产文件：
npm run build
中间构建输出位于 out。该目录为生成内容，应修改源文件后重新构建，不要直接编辑。
平台打包
当前平台默认包
npm run dist
Windows
生成 Windows NSIS 安装包：
npm run dist:win
生成 Windows 便携目录：
npm run portable
macOS
生成 x64 和 arm64 DMG：
npm run dist:mac
Linux
同时生成 Linux x64 和 arm64 包：
npm run dist:linux
只生成指定架构：
npm run dist:linux:x64
npm run dist:linux:arm64
每个 Linux 架构生成：
deb：适用于麒麟、统信 UOS 等 Debian 系桌面。- AppImage：适用于免安装验证和便携运行。
打包产物位于 dist。
Runtime 资源
发布包会携带经过版本与完整性校验的 OpenCode 和 Continue Runtime：
- OpenCode 平台二进制来自
.runtime-resources/<arch>。 - Continue Runtime 来自锁定版本的
@continuedev/cli。 - 打包钩子位于
build/runtime-hooks.cjs。
跨架构打包前，确认目标架构的 OpenCode 资源已经准备完成。不要用其他架构的二进制替代目标资源。
跨平台 CI 与 GitHub Release
.github/workflows/packages.yml 是统一发布工作流。它先验证并生成一次
out 生产 bundle，再在六个原生 Runner 上分别打包 Windows、macOS 和
Linux 的 x64、arm64 版本。生产 bundle 仅作为短期 Actions artifact
供打包任务复用，不会上传到 GitHub Release。
本地构建单个平台目标：
npm run release:package -- --platform <windows|macos|linux> --arch <x64|arm64>
默认产物为 Windows 的 NSIS 与 portable EXE、macOS 的 DMG 与 ZIP，以及
Linux 的 AppImage 与 DEB。每个目标目录都包含带文件大小和 SHA-256 的
release-manifest.json。
推送 v${package.version} 标签时，只有在六个打包目标全部成功后，工作流
才会严格校验并聚合所有平台产物，生成按平台重命名的 manifests、总
release-manifest.json 和 SHA256SUMS。随后工作流创建或更新 draft
GitHub Release，上传全部资产成功后才发布。重跑会保留人工编辑的 Release
notes 和未知附件。推送 main 或普通手动触发只构建 Actions artifacts，
不会创建或更新 Release。
发布标签必须与 package.json 版本完全一致。实际推送标签和触发发布前仍
需人工确认，例如当前版本应使用：
git tag v$(node -p "require('./package.json').version")
git push origin v$(node -p "require('./package.json').version")
当前未配置 Windows/macOS 代码签名或 macOS notarization。对外分发前应按 目标平台配置签名凭据并重新验证安装、升级和系统安全提示。
发布前冒烟测试
建议在每个目标系统上至少验证：
- 安装、启动、升级和卸载。
- 中文输入法、窗口缩放和高分屏显示。
- 系统密钥环和模型连接。
- 本地知识库导入、检索和知识图谱。
- Ask、Execute 的权限边界与旧版 Plan 数据兼容。
- OpenCode 与 Continue 的权限边界、取消和超时。
- 智能心跳的创建、暂停、恢复和历史记录。
- 应用退出后无残留 Runtime 子进程。