Happier开源贡献指南:如何参与这个多设备AI Agent编排项目
Happier开源贡献指南:如何参与这个多设备AI Agent编排项目
Happier 是一个面向 Web、桌面与移动端的开源 AI Agent 编排客户端与编排器(orchestrator),能将 Claude Code、Codex、OpenCode、Pi、Cursor、Grok 等编码智能体统一调度到上百个并行会话中。本文是一份完整的 Happier 开源贡献指南:无论你是想修一个文档错字,还是想为多设备 AI Agent 编排功能添砖加瓦,都能在 20 分钟内找到合适的切入点和标准流程。
⚠️ 项目现状提示:Happier 目前处于 pre-release 快速迭代期,API、流程与代码结构都可能发生变化。先对齐方向再动手,是避免白做功的关键。
🎯 先认清方向:什么贡献可以直接提,什么要先讨论
Happier 维护者的核心原则:小修随时欢迎,大改先讨论。这样既能避免你花几个小时写一个方向不符的 PR,也能让审查更快通过。
| ✅ 可直接提交 PR | ⚠️ 请先在项目讨论区沟通 |
|---|---|
| 文档修正、错别字、表述澄清 | 新功能 |
| 带清晰复现步骤的小 Bug 修复 | 行为 / 默认值 / 设置流程变更 |
| 单元测试、集成测试与 CI 改进 | UI/UX 改动 |
| 更友好的错误信息与日志 | 大型重构或依赖变更 |
| 不改变行为的纯机械性重构 | 跨 Server + CLI + UI 的多组件改动 |
| 涉及认证、加密、同步协议等安全敏感区域 | |
| 预计耗时超过 1–2 小时的工作 |
完整规则见仓库根目录的 CONTRIBUTING.md,各应用子目录(如 apps/ui/AGENTS.md、apps/cli/AGENTS.md)还附有针对该模块的专项开发约定。
🐞 最被低估的贡献方式:写一个高质量 Issue
Happier 官方明确指出:一条写得好的 Issue,往往比一个 PR 更有价值——项目正处在快速迭代期,清晰的描述能直接帮助维护者按当前架构解决问题。
一个好 Issue 的 5 个要素:
- 具体、可检索的标题——"Android:并行 Agent 运行时返回键无响应" 优于 "返回键坏了"
- 平台与版本上下文——iOS/Android、系统版本、CLI 运行方式
- 做了什么 → 期望什么 → 实际发生什么
- 稳定复现步骤(如果能可靠复现)
- 你的初步猜测——哪怕只是一个模糊的方向
不确定原因完全没关系,官方原话:"清晰描述问题本身就是贡献。" 如果你纠结于花 1 小时写 PR,不如先用 15 分钟写一条详尽的 Issue——这对双方都是更好的时间投资。
🛠️ 如何快速搭建 Happier 本地开发环境
贡献代码前,你需要能从源码跑起一整套 Happier。项目采用 repo-local 模式:所有 yarn 脚本在独立隔离的本地栈中运行,互不干扰。
npm i -g yarn
git clone https://gitcode.com/gh_mirrors/hap/happier
cd happier
yarn
yarn build
yarn cli:activate
yarn tui
跑起来之后,最常用的几条命令(都在仓库根目录执行):
| 命令 | 作用 |
|---|---|
yarn dev |
启动本地开发栈(Server + UI + Daemon) |
yarn tui |
在集成 TUI 中查看日志与控制台 |
yarn build / yarn start / yarn stop |
类生产构建、启动、停止 |
yarn logs |
流式查看日志(可加 --component=daemon 过滤) |
yarn mobile |
移动端开发工作流 |
详细的环境说明见 apps/docs/content/docs/development/index.mdx,其中还涵盖 Dev Container、桌面端 QA 等进阶场景。
🗂️ 熟悉仓库结构:Monorepo 里的模块地图
Happier 是一个 Yarn Workspaces 单体仓库,多数改动会横跨多个工作区。下表是最核心的模块:
| 目录 | 职责 |
|---|---|
apps/ui/ |
移动端与桌面端 UI(React Native + Tauri 壳) |
apps/cli/ |
命令行工具与本机 Daemon |
apps/server/ |
服务端 API、实时事件与存储 |
apps/docs/ |
官方文档站 |
apps/stack/ |
本地栈编排(hstack 工具集) |
packages/protocol/ |
各端之间的共享协议与契约 |
packages/tests/ |
端到端测试套件与测试基础设施 |
改 UI 前先看 apps/ui/AGENTS.md,改服务端先看 apps/server/AGENTS.md;跨端改动则建议通读根目录的 AGENTS.md——这是项目的"Agent 宪法",写清了架构红线与核心不变量。
🌿 分支模型与 PR 流程:三步走就能做对
Happier 采用三分支模型(详见 docs/release-process.md):
dev:集成分支,所有 PR 的目标preview:预览 / 候选发布分支main:稳定发布分支(不要 向它提 PR)
标准流程:
- 从
dev拉出功能分支 - 小步提交,向
dev发起 PR - PR 中说明 为什么改(问题 + 背景)、改了什么、如何测试;行为变更尽量附测试
- 想提前对齐思路?直接开一个 Draft PR
小技巧:PR 里关联对应的 Issue / 讨论帖,能显著加快合并速度。
🧪 测试与 CI:提交前该跑哪些检查
Happier 的测试"车道"按重量分级,详见 docs/testing.md:
yarn test—— 快速单元测试(跨所有应用)yarn test:integration—— 编排较重的应用集成测试yarn test:e2e:core:fast—— 默认本地核心 E2E 循环yarn test:e2e:ui—— Playwright 驱动的 UI 浏览器 E2E
官方建议:修改代码时用最小相关子集快速迭代;交付前至少跑一遍你改动包的类型检查,并在共享契约被触碰时补跑一条更宽的集成车道。
🤖 使用 AI 辅助贡献?这样写更容易被接受
Happier 本身就是用 AI Agent 构建的,对 AI 辅助贡献持开放态度——维护者看重的是背后的人类推理。如果你用了 AI 写代码、调试或塑造方案,请在 PR 中:
- 说明用了哪个工具
- 解释你要解决什么、为什么选这种思路
- 给出你给 AI 的指令和你的推理过程
- 确认哪些部分是你亲自测试验证过的
📚 贡献者文档清单
| 文档 | 内容 |
|---|---|
| CONTRIBUTING.md | 贡献总则(必读) |
| README.md | 项目总览与安装方式 |
| docs/testing.md | 测试车道与放置规范 |
| docs/release-process.md | 分支模型与发布流程 |
| docs/backend-architecture.md | 服务端架构速览 |
| AGENTS.md | 仓库级开发宪法 |
| apps/docs/content/docs/development/index.mdx | 本地栈、测试、DevBox 等开发文档入口 |
一句话总结:小修直接 PR 到 dev,大改先讨论,AI 辅助要写清思路——带上清晰上下文,开始你的第一个 Happier 贡献吧 🚀


