【免费下载链接】ghui
A GitHub TUI
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 installbun 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 dev2.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 testtest/ 下约有 40 个测试文件，覆盖缓存（cacheService.test.ts）、diff 渲染、主题存储、工作区布局等核心逻辑，秒级跑完。
4.2 别忘了子包测试
bun run test:keymap # 进入 packages/keymap 单独跑 bun testpackages/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 版本号 + 生成 CHANGELOGchangeset 通过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：
- verify：校验 Release tag 与
package.json版本严格一致 - 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 资产 - publish：主包发布，全程使用 Trusted Publisher（OIDC
id-token）+ provenance，不需要也不应配置 NPM_TOKEN - 最后自动 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
A GitHub TUI
相关推荐
VoltAgent 贡献者开发指南：pnpm + Lerna 单仓环境搭建、测试与 Changesets 版本发布全流程
VoltAgent 贡献者开发指南：pnpm + Lerna 单仓环境搭建、测试与 Changesets 版本发布全流程 本文基于 VoltAgent 官方贡献
人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Webamp NPM 包开发指南：本地开发、构建产物、测试与版本发布全流程
Webamp NPM 包开发指南：本地开发、构建产物、测试与版本发布全流程 Webamp 是一个用 HTML5、TypeScript 与 React 重新实现
前端音视频Cline 开源贡献开发指南：Bun 单体仓库中的本地开发、测试与 PR 提交全流程
Cline 开源贡献开发指南：Bun 单体仓库中的本地开发、测试与 PR 提交全流程 本文基于 Cline 仓库根目录的 CONTRIBUTING.md htt
人工智能AI Agent代码智能体AI 应用开发工具MCP Clients
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
、oklch 与 @property 彩虹动画实战)
