ghui 开发者指南:Bun + Effect 本地开发、测试与 Changesets 发布流程完全教程

原创2026-10-14 13:07:361,702 阅读

ghui 开发者指南:Bun + Effect 本地开发、测试与 Changesets 发布流程完全教程

ghui 是一款运行在终端里的 GitHub Pull Request TUI(Terminal UI),本文是面向新手的 ghui 开发者指南,带你快速跑通 Bun 本地开发环境、bun test 测试体系,以及基于 Changesets 的完整发布流程,从第一次 bun install 到参与一次真实发版。

1. 为什么值得上手 ghui:一套现代化的 TUI 技术栈

先看看 ghui 用了什么,心里有数后再动手会快很多:

  • Bun + TypeScript(strict):运行、构建、测试、打包全部由 Bun 一个工具链承担,无需 Node 构建配置
  • React 19 + @opentui/react:用 React 声明式地写终端界面
  • Effect:状态管理基于 Effect 的 Atom 响应式管线,SQLite 缓存由 @effect/sql-sqlite-bun 驱动
  • Monorepo 结构:根包 + packages/keymap/(实验性键位绑定库,bindings as data)

完整依赖声明见 package.json,领域术语(Item、Surface、App-shell 等)可以先读 CONTEXT.md 建立心智模型。

2. 环境准备:3 步完成 Bun 开发环境初始化

2.1 快速克隆并安装依赖

git clone https://gitcode.com/gh_mirrors/gh/ghui
cd ghui
bun install

bun install 会同时解析 workspaces("workspaces": [".", "packages/*"]),把子包 @ghui/keymap 以 workspace 依赖链接进来。

2.2 可选:用 Nix 一键统一工具链

如果你用 Nix,仓库自带 flake,flake.nix 的 devShell 内置了 bun、gh、git、nodejs_24 四个工具,保证 CI 与本地环境一致:

nix develop
bun install
bun run dev

2.3 本地配置:.env 与 Mock 模式

复制 .env.example 为 .env,可按需调整:

  • GHUI_PR_FETCH_LIMIT:拉取 PR 数量上限(默认 200)
  • GHUI_AUTHOR:作者身份标记
  • GHUI_MOTEL_PORT / GHUI_OTLP_ENDPOINT:本地可观测性(可选)

💡 没有 GitHub 登录态也能开发:bun run dev:mock 会生成 200 条 mock PR、4 个 mock 仓库,适合纯 UI 调试。

3. 本地开发日常:watch 模式与调试探针

3.1 用 bun run dev 获得秒级热更新

bun run dev

这个脚本(定义在 package.json 的 scripts.dev)做了三件事:--watch 监听源码、GHUI_DEBUG_LOG=/tmp/ghui-debug.log 落盘调试日志、GHUI_MOTEL_PORT(默认 27686)暴露本地观测端口。改一行代码,终端界面立即重绘。

3.2 无界面调试 Effect Atom 管线

ghui 的数据流是 activeViewAtom → pullRequestsAtom → ... → visiblePullRequestsAtom 的 Atom 链。遇到数据异常但不想盯着 TUI 复现时,可以用 dev/probe-atom-pipeline.ts 这类 headless 探针脚本:

bun dev/probe-atom-pipeline.ts <owner/repo>

它会逐步切换视图,打印每个 Atom 切换后的状态,配合 /tmp/ghui-debug.log 快速定位"坏数据从哪个 Atom 来的"。同目录下还有 dev/probe-filter.ts 用于过滤器排查。

3.3 代码风格:oxfmt + oxlint 双工具

bun run format        # 格式化 src/ test/ dev/
bun run format:check  # CI 同款检查
bun run lint          # oxlint 静态检查
bun run typecheck     # tsc --noEmit

风格规则集中在 .oxfmtrc.json:180 列宽、使用 Tab、不加分号——和主流 prettier 项目不太一样,提交前跑一次 format:check 能避免 CI 挂掉。TypeScript 侧开启 strict、verbatimModuleSyntax 等严格选项,并挂了 @effect/language-service 插件,Effect 用户在编辑器里能拿到专用补全,见 tsconfig.json。

4. 测试体系:bun test 一键跑通

4.1 运行主测试套件

bun run test        # 等价于 bun test test

test/ 下约有 40 个测试文件,覆盖缓存(cacheService.test.ts)、diff 渲染、主题存储、工作区布局等核心逻辑,秒级跑完。

4.2 别忘了子包测试

bun run test:keymap   # 进入 packages/keymap 单独跑 bun test

packages/keymap/ 是独立的实验性子包(含自己的 README.md 与迁移文档 MIGRATION.md),测试与主包分开执行,两个都要跑。

4.3 对照 CI 检查项自查

CI 工作流 ci.yml 在每次 PR 上执行 bun install --frozen-lockfile → format:check → typecheck → lint → test → test:keymap → package:smoke。本地提交前照这份清单过一遍,PR 就不会在 CI 上红。

5. Changesets 发布流程:从改动到 npm 上线

5.1 每个用户可见的改动都要留 changeset

ghui 采用 Changesets 管理版本。规则很简单(完整规范见 AGENTS.md):

bun run changeset         # 交互创建:选包、选 patch/minor/major、写说明
bun run changeset:status  # 查看待发布 changeset 列表
bun run changeset:version # 消费 changeset:bump 版本号 + 生成 CHANGELOG

changeset 通过 npm exec 调用固定版本(2.31.0)的 CLI,本地零安装;配置文件 .changeset/config.json 指定 baseBranch 为 main 且 commit: false(不自动产生 changeset commit)。最终产出的版本记录会写入 CHANGELOG.md。

5.2 发版前的完整检查清单

在提交 version bump 之前,按 AGENTS.md 的要求依次执行:

bun run format:check
bun run typecheck
bun run lint
bun run test
bun run package:smoke

其中 dev/package-smoke.ts 是发布前的"冒烟测试":打包 npm 主包 + 平台二进制包,分别在干净的 npm 和 bun 项目中安装,断言版本号一致、不含私有 workspace 依赖、ghui --version 可执行、SQLite 缓存服务能正常打开——等于在本地预演了用户 npm install -g 的全过程。

5.3 发版自动化:GitHub Actions 可信发布

把 version bump 推送到 main 并创建 v<version> Release 后,一切交给 publish.yml:

  1. verify:校验 Release tag 与 package.json 版本严格一致
  2. standalone:4 平台矩阵(darwin-arm64 / darwin-x64 / linux-arm64 / linux-x64,目标清单见 dev/release-targets.ts)用 bun build --compile 编译独立二进制(dev/build-standalone.ts)+ 平台二进制 npm 包(dev/build-npm-packages.ts),逐个 npm publish 并上传 release 资产
  3. publish:主包发布,全程使用 Trusted Publisher(OIDC id-token)+ provenance,不需要也不应配置 NPM_TOKEN
  4. 最后自动 dispatch Homebrew tap 更新,brew install kitlangton/tap/ghui 的用户即可升级

另外注意根 package.json 里的 prepublishOnly 是个"防呆开关":直接在源码目录 npm publish 会被主动拦下,确保只发布 dist/npm/main 构建产物。

6. 一分钟回顾:常用命令速查表

场景 命令
安装依赖 bun install
开发(watch + 调试日志) bun run dev
开发(mock 数据) bun run dev:mock
测试 / 子包测试 bun run test / bun run test:keymap
类型检查 bun run typecheck
格式 / Lint bun run format:check / bun run lint
发布冒烟 bun run package:smoke
创建 changeset bun run changeset
应用 changeset 升版 bun run changeset:version

掌握 "dev → test → changeset" 这条主线后,你可以从任意一个 plans/ 下规划中的功能入手提交 PR——祝开发顺利,欢迎在终端里把 GitHub 玩出花 🚀

登录后查看全文
ghui