Habblaud 开发者指南：从本地测试到发布 Release 的完整工作流

Habblaud 是一个像素风虚拟办公室，把 Claude Code 与 Codex 代理的实时工作状态可视化：每个项目是一间办公室，每个代理是一个像素小人，谁在敲代码、谁在等你审批、谁已经交付，一眼就能看到。本文为贡献者整理了一套从本地开发、测试验证到发布 Release 的完整工作流，全部命令可直接照抄执行。

快速总览：Habblaud 开发工作流一图看懂

📌 在动手之前，先了解整体流程（共 5 步）：

1. 准备环境：npm install+npm run dev本地跑起来
2. 本地验证：npm run typecheck→npm test→npm run build三连
3. 演示模式：用 Demo 模式和调试工具做可视化验证
4. 理解结构：知道代码在shared/、server/、client/里各管什么
5. 发布 Release：改版本号 → 写 CHANGELOG →npm run release一键发布

第一步：准备开发环境并本地运行 Habblaud

环境要求

• Node.js 22.12+与npm（项目用 Node 24 开发）
• macOS 或 Linux（Docker 可选，用于容器化验证）

克隆并启动

git clone https://gitcode.com/gh_mirrors/ha/habblaud cd habblaud npm install npm run dev

npm run dev会同时启动 Node 服务器和带热重载的 Vite 客户端，打开http://localhost:4747即可看到办公室。常用开发命令汇总如下（均定义在 package.json 中）：

💡npm install只下载构建工具（Vite、TypeScript、tsx 等）。Habblaud 服务器本身零运行时依赖，只用 Node 内置模块——这也是 Dockerfile 里运行阶段只需拷贝dist/的原因。

第二步：本地验证三连——typecheck、npm test 与 build

在提交 Pull Request 之前，CONTRIBUTING.md 要求跑完这三步：

npm run typecheck # ① 类型检查：覆盖 client 与 server 两套 tsconfig npm test # ② 单元测试：Vitest 全量运行 npm run build # ③ 生产构建：验证打包无误

几个值得了解的设计细节：

• 测试分布：测试文件与源码同目录（*.test.ts），vitest.config.ts 扫描server/、shared/、client/src/三处，环境为 node。
• CHANGELOG 守护测试：server/test/release.test.ts 中有一条特殊测试——如果package.json的版本号在 CHANGELOG.md 里没有对应章节，npm test会直接失败。这意味着"每次发版必须写 changelog"是由测试强制的，而不是口头约定。
• 改了文案？界面支持葡萄牙语、英语、西班牙语、法语（原文为葡萄牙语），翻译统一走tr()函数（见 shared/i18n.ts），跑npm run i18n:check可列出缺失和冗余的翻译。
• 改了 Claude Code 插件（mod）？额外验证：

claude plugin validate mod/habblaud # 校验插件，列出事件与调用 claude plugin test mod/habblaud # 跑插件测试（无需会话、账号和网络）

✅ 三步全绿，才建议发起 Pull Request。

第三步：用演示模式与调试工具做可视化验证

改了渲染、动画或世界逻辑，光看测试不够。Habblaud 提供了完整的"假数据"体系，不需要真的开着 Claude Code 会话：

• 浏览器模拟：URL 加?mock=1（如http://localhost:4747/?mock=1），纯前端模拟所有代理；&speed=3加速时间，&sessions=6调整模拟会话数。
• 服务端演示：npm run demo（等价于HABBLAUD_DEMO=1）启动时即带假代理。
• 时间旅行：URL 加?hora=21:30直接设定打开时的时刻；浏览器控制台还有habblaud.world.debug工具，例如habblaud.world.debug.setHour(21)立刻切到夜晚场景：

• 无头截图：不想开浏览器也能截图，scripts/shot.mjs 用 Playwright 驱动隔离的无头 Chromium：

npx playwright-core install chromium-headless-shell # 首次只需一次 node scripts/shot.mjs 'http://localhost:4747/?mock=1&speed=3' /tmp/habblaud.png --size 1400x900 --wait 4000

• 假时间线：npm run demo:timeline离线生成一整天的模拟时间线数据，供"时光回放"功能使用（可配--date、--seed等参数，见 scripts/demo-timeline.ts）。

第四步：项目结构与关键文件速览

Habblaud 是"纯 Node 后端 + Vite 前端"的三层结构，改代码前花一分钟定位归属：

• 服务器细节（数据源、API 路由表、安全边界）都在 server/README.md，是排查"为什么页面没数据"的第一站。
• 前端构建行为（产物进dist/client、带 hash 的资源进/bundle/）由 vite.config.ts 决定。
• 构建流程：npm run build先用 Vite 打客户端，再打服务端产物到dist/；npm start即node dist/server/index.js。

第五步：发布 Release——从 CHANGELOG 到 npm run release

Habblaud 的发布流程被 scripts/release.ts 严格化：版本号、changelog 章节、tag 三者的对应关系由脚本自动校验，任何一步不齐都发不出去。

1. 提升版本号（遵循语义化版本）

npm version minor --no-git-tag-version # 有新功能：0.11.0 → 0.12.0 npm version patch --no-git-tag-version # 纯修 bug：0.11.0 → 0.11.1

只改package.json里的数字，不自动打 tag（tag 留给发布脚本）。

2. 写 CHANGELOG 章节

CHANGELOG.md 采用 Keep a Changelog 格式。操作要点：

1. 开发期间，改动先记在顶部的## [Não lançado]（未发布）章节里；
2. 发版时，把该章节标题替换为## [0.12.0] - 2026-XX-XX（版本号 + 日期），并在其上方留一个空的## [Não lançado]；
3. 同步更新文件末尾的版本对比链接。

⚠️ 这一步漏掉的话，npm test会失败（前文提到的守护测试）；即使侥幸绕过，npm run release也会报错：CHANGELOG.md 没有该版本章节。

3. 合并到 main 并一键发布

git checkout main && git pull && git merge <你的分支> npm test # 合并后再确认全绿 npm run release -- --dry-run # 先干跑：只展示将发布的 release notes npm run release # 正式发布（需要已登录的 gh CLI）

npm run release的完整校验链（源码见 scripts/release.ts）：

• ✅package.json版本必须有对应 CHANGELOG 章节，且内容非空；
• ✅ 必须处于main分支、工作区干净、本地与远端完全同步；
• ✅ tagvX.Y.Z不得已存在；
• 通过后：创建附注 tag → 推送 → 用 CHANGELOG 章节文本作为 notes 创建 Release（脚本还会把换行折在 120 列内的长句自动合并，保证 release notes 排版完整）。

发布之后：用户如何感知新版

• 服务器内的更新检查器（server/updates/checker.ts）每 6 小时匿名查询一次 Releases API（带 ETag，不消耗额度），结果缓存在updates.json；
• 发现新版本后，顶栏版本号位置会变成绿色的New version徽章，配合通知提醒用户git pull更新；
• 用户跳过检查可设HABBLAUD_UPDATE_CHECK=0。

发布前检查清单与常见问题

🚀 最后过一遍清单，避免白忙：

• npm run typecheck、npm test、npm run build全绿
• 改动package.json版本后，CHANGELOG 有对应章节（且npm test通过）
• 视觉类改动附了截图/GIF（建议用?mock=1演示模式截取，不含真实数据）
• 当前在main、工作区干净、gh已登录
• 先用--dry-run预览过 release notes

常见问题：

总结：把每次发版变成肌肉记忆

Habblaud 的贡献闭环可以浓缩成一条命令链：

npm run dev # 跑起来 npm run typecheck && npm test && npm run build # 验证 # …写 changelog、提 PR、合并… npm version minor --no-git-tag-version && npm run release # 发布

工作流细节参考 CONTRIBUTING.md 与 server/README.md。祝你在像素办公室里开发愉快 🎉