感谢你对 Universal-Code 的关注与支持!我们欢迎社区提交 Bug 修复、功能增强、文档优化以及用户体验改进。
为了让开发与审查流程更顺畅高效,请在提交代码前阅读本指南。
在本地搭建开发环境前,请确保已安装以下基础工具:
| 工具 | 推荐版本 | 来源与用途 |
|---|---|---|
| Go | 遵循 go.mod,当前 1.26.11 | 核心控制平面、CLI、TUI、HTTP API 与 SQLite 状态机 |
| Node.js | 24+ | 前端管理界面(web/ 目录下的 React 19 + Vite) |
| Git | 2.41+ | 源码版本管理 |
| Rust (可选) | 1.97.1+ | 仅在修改或验证 analyzers/ 目录下的 WASI 代码分析器时需要 |
提示:启动 API、连接界面和运行离线测试不需要云端模型凭据。真实模型对话需要另行配置模型;测试中的 Mock Provider 不代表已验证真实模型调用。
# 克隆代码库
git clone https://github.com/CWNU-Open-Source-Community/Universal-Code.git
cd Universal-Code
# 安装前端依赖
cd web
npm ci
cd ..
# 下载并校验锁定的 Go 模块依赖(verify 本身不会下载缺失模块)
go mod download
go mod verify以下命令均从仓库根目录执行。两个 Token 必须不同,且各为 32–512 字节、不含空白。使用已安装的 Node.js 分别生成 32 个随机字节,编码后各为 64 字节的十六进制文本。每次执行都会生成新值。
Linux / macOS(Bash):
export CYBERAGENT_API_TOKEN="$(node -p "require('node:crypto').randomBytes(32).toString('hex')")"
export CYBERAGENT_API_CONTROL_TOKEN="$(node -p "require('node:crypto').randomBytes(32).toString('hex')")"
export CYBERAGENT_HOME="${CYBERAGENT_HOME:-$PWD/.cyberagent-workbench/dev}"
node -e "console.log('Read token: ' + process.env.CYBERAGENT_API_TOKEN); console.log('Control token: ' + process.env.CYBERAGENT_API_CONTROL_TOKEN)"
go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765Windows(PowerShell):
$env:CYBERAGENT_API_TOKEN = node -p "require('node:crypto').randomBytes(32).toString('hex')"
$env:CYBERAGENT_API_CONTROL_TOKEN = node -p "require('node:crypto').randomBytes(32).toString('hex')"
if (-not $env:CYBERAGENT_HOME) { $env:CYBERAGENT_HOME = Join-Path (Get-Location).Path '.cyberagent-workbench/dev' }
node -e "console.log('Read token: ' + process.env.CYBERAGENT_API_TOKEN); console.log('Control token: ' + process.env.CYBERAGENT_API_CONTROL_TOKEN)"
go run ./cmd/cyberagent api serve --listen 127.0.0.1:8765首次编译可能需要数分钟。看到 api_url: http://127.0.0.1:8765/api/v1 后保持终端运行。未另设 CYBERAGENT_HOME 时,开发数据保存在已被 Git 忽略的 .cyberagent-workbench/dev,不使用桌面应用的数据目录。上面打印的令牌仅用于下一步本机连接,请勿提交或粘贴到 Issue、截图、日志附件中。
新开终端,从同一仓库根目录执行(Bash / PowerShell 均可):
cd web
npm run dev -- --host 127.0.0.1 --port 5173 --strictPort- 打开 **http://127.0.0.1:5173**,在“查看令牌 / Read access token”中填入终端 A 打印的
Read token。 - 如需创建任务或操作,再在“操作令牌 / Control access token”中填入
Control token,点击“连接 / Connect”。不要将 Token 写入 URL、前端.env或源码。 - 成功后进入工作台;浏览器网络面板中的
/api/v1/health和/api/v1/capabilities应返回 200。前端通过同源/api代理到http://127.0.0.1:8765,浏览器无需直接访问后端端口。 - 在两个终端分别按
Ctrl+C停止服务。重新生成 Token 后需要重新连接;开发数据会保留。
端口占用时先停止旧的开发进程。--strictPort 可防止前端悄悄改用其他端口。若自行更改后端端口,须在启动 Vite 的终端设置 CYBERAGENT_API_TARGET 为对应的 loopback URL。
该命令用于基本界面/API 联调。工作区导入、模型凭据写入、后台执行等功能还需要对应的显式启动开关;控制 Token 本身不会开启全部能力。按需查阅 go run ./cmd/cyberagent api serve --help 和使用指南。
CI 会直接提取上述代码块,在 Linux/Bash 与 Windows/PowerShell 上启动真实 Go API、Vite 和 Chromium,验证令牌、代理与连接页。依赖准备完成后,本地可运行 cd web、npx playwright install chromium,回到根目录运行 node scripts/check-contributor-startup.mjs。
这是独立的开发入口,使用内嵌前后端;完成上面的浏览器联调不需要构建桌面应用。
- Windows 桌面端 (需要 Edge WebView2 Runtime):
# 本地构建未签名测试包 ./scripts/build-desktop.ps1 # 运行可复现验证构建 ./scripts/build-desktop.ps1 -VerifyReproducible
- macOS 桌面端:
# 本地构建测试包 ./scripts/build-desktop-darwin.sh
准备发布时,同步 README.md、README.en.md、docs/windows-release.md、docs/macos-release.md 中 public-downloads 标记内的版本、日期、下载与启动说明,再运行:
python -B scripts/check-download-docs.py
python -B -m unittest discover -s scripts -p test_download_docs.py -v每个入口必须使用同一个明确的 Release tag;/releases/latest 不包含预发布,不能作为预览版入口。Windows 链接指向 TraverseBoard.exe,Mac 按 macos-arm64 / macos-amd64 选择 DMG。Release 页负责展示包含源码 revision 的完整文件名,避免在源码文档中预先引用该提交自身的 hash。
发布 tag 时,Desktop release 工作流会要求四份文档的版本等于待发布版本;上传 Draft 资产后,还会确认 EXE、校验和及两个架构的 DMG 均已上传、非空,且 DMG 文件名绑定本次版本与源码 revision。任何入口或资产不一致都会阻止公开发布。Actions 测试候选另列,保留其登录与过期说明。
Universal-Code 以 Go 结构体与路由定义作为 API 的唯一真相来源 (Single Source of Truth)。
当你修改了 Go HTTP 控制器、路由或对外 DTO 时,必须从仓库根目录重新生成接口定义并提交受测快照:
# 1. 由 Go 导出最新的 OpenAPI 3.1 规范文档
go run ./cmd/cyberagent api openapi --output docs/openapi.json
# 2. 重新生成前端 TypeScript 类型定义
cd web
npm run generate:api
cd ..
# 3. 检查是否存在类型或接口漂移
cd web
npm run check:api
cd ..注意:请勿手动编辑
docs/openapi.json或web/src/api/schema.d.ts。所有 DTO 生成物在 CI 中均会通过npm run check:api严格校验一致性。
在提交 Pull Request 前,请确保相关测试均能本地通过:
cd web
# 运行 TypeScript 静态类型检查
npm run typecheck
# 运行 Vitest 单元与集成测试套件
npm test
# 验证生产打包构建
npm run build# Go 静态分析
go vet ./...
# 运行全量单元测试
go test -count=1 ./...
# 运行桌面端专属集成测试 (Windows / macOS)
go test -tags "desktop" -count=1 ./cmd/cyberagent-desktop ./internal/desktop ./internal/webuicd analyzers
cargo fmt --all -- --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
cd ..- 严禁提交机密凭据:绝不要将真实 API Key、Bearer/Control Token、Cookie、
.env文件、真实的供应商请求日志或敏感数据提交到 Git 仓库。 - 本地临时数据隔离:请勿将本地生成的
.cyberagent-workbench/、cyberagent.db、SQLite WAL 文件或build/、dist/产物提交到版本库中。 - 测试环境纯净:单元测试与 CI 流程默认使用 Mock Provider,切勿在自动化测试中对公网产生真实计费或未授权的网络流量。
- 安全第一与最小特权原则:
- 所有的代码读写、终端命令执行和网络访问都具备明确的审计边界。
- 文件删除、覆盖式重命名或危险命令必须经过人工弹窗确认,绝不允许静默越权。
- 前后端职责分明:
- Go 控制面 拥有完整的数据持久化、状态转换、权限门禁和执行调度能力。
- React 前端 负责用户交互呈现与视觉效果,不私自推导或伪造未经后端确认的状态。
- 纯 CSS 现代性能标准:
- 界面视觉效果优先使用现代纯 CSS 属性(如
backdrop-filter、多层box-shadow内阴影、linear-gradient)。 - 涉及滚动和视觉效果的改动应在实际页面验证;性能结论应记录测量环境与结果。
- 界面视觉效果优先使用现代纯 CSS 属性(如
- 统一规范的产品命名:
- 所有面向用户的标题、文案、关于页面与文档中,产品官方名称一律统一为
Universal-Code。
- 所有面向用户的标题、文案、关于页面与文档中,产品官方名称一律统一为
- 从
main分支切出具名分支,例如:git checkout -b fix/sidebar-docking # 或 git checkout -b feat/support-deepseek-r1 - 保持 Commit 粒度清晰,提交信息简明扼要。
- 运行覆盖本次改动的相关测试和必需检查,在 PR 中记录验证范围与结果。
- 在 GitHub 上发起 Pull Request,简要说明:
- 改动背景:解决了什么问题或增加了什么特性。
- 关键设计:采用了什么样的架构思路。
- 验证方式:在本地如何复现并验证了修复效果。
感谢你为 Universal-Code 做出的贡献。