开发者文档
本文档面向想要了解 OpenWatcher 内部架构、进行二次开发或提交 PR 的开发者。
项目概览
OpenWatcher 是一个开源的 agent 状态监工工具，由三个核心模块组成：
- Go 后端 — 本地 HTTP 服务，负责会话扫描、配额管理、配对认证
- 桌面应用 — 基于 Wails v2 的跨平台客户端（macOS / Windows），提供安装向导和配置管理
- 手表应用 — Kotlin + Jetpack Compose 的 Wear OS 应用，实时展示 agent 状态
技术栈
| 模块 | 语言 | 框架 / 工具 |
|---|---|---|
| 后端 | Go 1.25 | net/http, modernc.org/sqlite |
| 桌面应用 | Go + JS | Wails v2, Vite 5 |
| 手表应用 | Kotlin 2.0 | Jetpack Compose, Wear Compose, OkHttp |
目录结构
| 路径 | 说明 |
|---|---|
cmd/openwatcher/ | 后端 CLI 入口 |
internal/ | 后端核心库（auth、config、pairing、quota、sessions 等） |
desktop-app/ | 桌面应用（Wails v2 项目） |
watch-app/ | 手表应用（Android / Wear OS） |
scripts/ | 构建、打包、发布脚本 |
site/ | 官网站点 |
环境搭建
本地开发
所需的开发工具：
- Go 1.25+ — 建议通过 mise 管理版本
- Node.js — 前端构建
- Wails v2 CLI —
go install github.com/wailsapp/wails/v2/cmd/wails@v2.12.0 - Android SDK — compileSdk 35，build-tools 35.0.0（手表端开发）
- Git
启动本地后端服务：
scripts/start-local.sh默认监听 127.0.0.1:18787，可通过环境变量自定义：
| 变量 | 说明 | 默认值 |
|---|---|---|
OPENWATCHER_LISTEN | 监听地址 | 127.0.0.1:18787 |
OPENWATCHER_CONFIG | 配置文件路径 | ~/.openwatcher/config.json |
OPENWATCHER_PAIRING_SLOT | 配对槽位 | beta |
OPENWATCHER_NO_AUTH | 禁用认证（仅调试） | 未设置 |
启动桌面应用开发模式：
cd desktop-app
wails dev构建手表端（调试）：
cd watch-app
./gradlew assembleDebug \
-PopenWatcherDebugBaseUrl=http://10.0.2.2:18787运行测试：
go test ./...
提示：后端健康检查可通过
curl http://127.0.0.1:18787/healthz 验证服务是否正常运行。
构建与打包
| 脚本 | 用途 |
|---|---|
package-desktop-release.sh | 打包桌面应用（macOS: dmg/zip, Windows: exe/zip） |
package-watch-release.sh | 构建手表 release APK，自动验签并生成元数据 |
package-backend-release.sh | 后端 sidecar 二进制打包 |
prepare-runtime-assets.sh | 准备运行时资源和 manifest |
check-release-artifacts.sh | 发布前产物检查（敏感文件、debug APK 等） |
桌面应用打包示例：
scripts/package-desktop-release.sh --platform darwin-arm64手表 release 构建：
RELEASE_SUMMARY="版本说明" scripts/package-watch-release.sh "beta-0.22.0"
注意：手表 release 构建要求工作区无未提交改动，否则脚本会拒绝执行。
参与贡献
欢迎通过 GitHub Issue 和 Pull Request 参与贡献。
- Fork 仓库并基于
main分支创建特性分支 - 确保
go test ./...全部通过 - 提交信息使用中文，遵循项目现有的 commit 风格
- PR 请描述改动内容和测试情况
开发流程
- 在 GitHub 上 Fork 仓库
- 克隆到本地：
git clone git@github.com:你的用户名/codex-watcher.git - 创建特性分支：
git checkout -b feature/你的特性名 - 本地开发并测试
- 提交并推送：
git push origin feature/你的特性名 - 在 GitHub 上创建 Pull Request
API 参考
后端默认监听 127.0.0.1:18787，提供以下主要接口：
| 接口 | 说明 |
|---|---|
GET /healthz | 健康检查 |
GET /api/sessions | 获取当前会话列表 |
GET /api/quota | 获取配额信息 |
POST /api/pair | 发起手表配对 |
GET /api/config | 获取运行时配置 |
更多 API 细节请参考
internal/server/ 源码中的路由定义。