gh-dash 贡献指南：从 Issue 到 PR 的完整协作工作流与本地开发环境搭建

• 开发工具
• CLI
• 研发协作

本篇技术指南面向希望为 gh-dash（一款"不打断你工作流"的 GitHub 终端 UI）贡献代码的开发者，系统讲解项目的贡献规则、基于 Devbox 的本地开发环境搭建、代码库结构与导航方法，以及调试、Linting、本地文档站点运行等开发环节的实操步骤。读完本文，你将掌握从提出功能想法、提交 PR、参与评审到最终合并的完整协作流程，并能快速在本机搭建与官方一致的开发环境。

贡献前必须理解的两条铁律

gh-dash 的贡献指南在开头就立下了两条核心规则，这决定了整个项目的协作基调：

1. 你必须真正理解自己写的代码。如果你无法解释你的改动做了什么、以及它们如何与更大的系统交互，就不要向该项目提交贡献。这条规则的深层含义是：gh-dash 的架构由 TUI 渲染层、GitHub GraphQL 数据层、配置解析层等多个子系统组成，一个 PR 的改动往往横跨多层，只有理解调用链的贡献者才能保证改动不会破坏既有行为。
2. 提交 PR 后必须愿意回应评论并长期维护这段代码。项目明确拒绝"路过式 PR"（drive-by PR）——即只解决自己遇到的问题、却不愿意迭代修改的提交。如果只是解决自己的痛点而不打算跟进维护，请把改动留在自己的 fork 里。

这两条规则与项目的"维护者是人"的定位一脉相承，也直接引出了下一条更严格的政策。

严格的 No-AI 政策

项目有一条严格的禁止 AI 政策，详细条款见仓库根目录的 AI_POLICY.md，主要包括：

• 禁止任何 LLM 生成的内容，无论是代码还是文字；
• 禁止改写/转述 LLM 生成的内容；
• 禁止使用 LLM 进行编辑，包括修正拼写或语法错误；
• 禁止使用 LLM 进行翻译；
• 禁止使用 LLM 头脑风暴后分享其结果；
• 禁止使用 LLM 查找 bug；
• 禁止在评论中谈论使用聊天机器人/LLM 服务。

需要注意适用范围：这些规则只约束外部贡献者。维护者一般不受此限制，因为他们已被证明能合理使用判断力；一旦维护者出现不当的 AI 使用，该豁免会被重新审视。

政策的出发点很朴素：这个项目由人类维护，每一则讨论、issue 和 PR 都会被人类阅读和评审。用低质量、未经合格验证的产出去接近这个协作边界，等于把验证负担转嫁给维护者，是不尊重他人时间的表现。同时，项目追求的是积极、用心、长期的贡献者——理想状态是：先开 discussion 讨论、大型改动拆分为小 PR、PR 描述是真诚的人类文字、愿意迭代打磨而非"一次性交付"、并愿意在未来持续维护这段代码。

贡献工作流速查（Quick Guide）

官方文档按三种场景给出了清晰的行动路径：

我有一个功能想法（I Have an Idea for a Feature）

和 bug 报告一样，先在 issues 和 discussions 中搜索，确认该功能是否已被请求。如果没有，则在"Feature Requests, Ideas"分类下打开一个 discussion。

我已经实现了一个功能（I've Implemented a Feature）

按优先级依次选择：

• 如果已有对应的 issue，直接打开 pull request；
• 如果没有 issue，打开一个 discussion 并链接到你的分支；
• 如果你想"冒险"一下，也可以直接开 PR 并期待好运。

我有一个既非 bug 也非功能请求的问题

在 Q&A 分类下打开 discussion，或加入项目的 Discord 服务器，在 #help 论坛频道提问。

本地开发环境：基于 Devbox 的标准化工具链

gh-dash 使用 Devbox 定义了完整的环境：

{ "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.16.0/.schema/devbox.schema.json", "env": { "GOPATH": "$PWD/.devbox/go", "GOBIN": "$PWD/.devbox/go/bin", "PATH": "$PATH:$PWD/.devbox/go/bin" }, "packages": { "git": "latest", "gh": "latest", "go": "1.27.0", "golangci-lint": "2.13.1", "gofumpt": "0.8.0", "go-task": "3.44.1", "nerdfix": "0.4.2", "fd": "10.2.0" }, "shell": { "init_hook": [ "echo \"Creating devbox shell...\"", "[[ $(command -v prism) != \"$GOBIN/prism\" ]] && go install go.dalton.dog/prism@latest", "[[ $(command -v gotip) != \"$GOBIN/gotip\" ]] && go install github.com/lusingander/gotip/cmd/gotip@latest" ] } }

可以看到环境固定了 Go 1.27.0、golangci-lint 2.13.1、gofumpt 0.8.0、go-task 3.44.1 等关键工具版本，并在进入 shell 时自动安装prism（测试运行器）与gotip（测试重跑工具）。首次进入 shell 时这些工具会一并就位，因此耗时较长属正常现象。

搭建步骤

1. 克隆仓库：

git clone https://gitcode.com/gh_mirrors/gh/gh-dash.git && cd gh-dash

2. 安装 devbox（需要 bash）：

curl -fsSL https://get.jetpack.io/devbox | bash

3. 启动 devbox shell 并完成环境初始化（首次会耗时较长）：

devbox shell

这会在一个安装了全部所需工具的 shell 中运行，之后的task、go、golangci-lint等命令都来自该环境。

可选优化：direnv 与 VSCode 集成

• direnv：允许按目录设置独立的环境变量，让devbox shell自动生效。安装后用brew install direnv，在~/.bashrc末尾追加eval "$(direnv hook bash)"（其他 shell 参见 direnv 官方安装说明），然后运行direnv allow启用。
• VSCode 扩展：按官方指南配置 VSCode 自动运行devbox shell，让编辑器内打开的终端直接复用同一套工具环境。

故障排查

如果 devbox 环境异常，最简单的处理是删除项目根目录下的.devbox目录后重新进入devbox shell，让其重新生成完整环境。

导航代码库：架构分层与目录结构

文档建议先熟悉三个前置知识，再深入代码：

• Bubbletea：项目使用的 TUI 框架，负责消息驱动的界面更新；
• Elm 架构：Bubbletea 背后的思想——Model / Update / View 的纯函数式循环；
• glow：用于解析与呈现 Markdown（从 go.mod 看，实际渲染由charm.land/glamour/v2完成）。

官方文档列出的代码结构如下（注意：文档撰写时目录名不带internal/前缀）：

• ui/—— 负责渲染 TUI 各部分的代码；
• data/—— 从 GitHub GraphQL API 获取数据的代码；
• config/—— 解析用户config.yml的代码；
• utils/—— 各类工具函数。

对照当前仓库的实际结构，这四个模块已经迁移到internal/目录下，且职责划分更细：

此外，CLI 入口位于 cmd/root.go（基于 cobra，定义了--config、--debug、--cpuprofile等标志），程序主入口在 gh-dash.go。数据层与 TUI 层之间的连接在 internal/tui/ui.go 的Model结构中体现——它聚合了 sidebar、各 section、tabs、footer 以及ProgramContext。

提示：在阅读代码前先浏览 internal/tui/ui_test.go 与各组件的_test.go文件，它们用黄金文件（golden files）验证渲染输出，是理解每个组件行为的捷径。

调试：写日志、跟日志、跑 debug 模式

gh-dash 的调试链路非常清晰，官方文档给出了三个配套步骤：

1. 用 Charm 的log包写入日志：

import "charm.land/log/v2" // more code... log.Debug("some message", "someVariable", someVariable)

2. 用task logs实时跟踪日志文件。
3. 在另一个终端窗口运行task debug以 debug 模式启动程序。

这三个环节对应 Taskfile.yaml 中的任务定义。task debug实际执行的是：

debug: desc: Run in debug mode. Run `task logs` to watch the logs. env: LOG_LEVEL: debug DEBUG: true cmds: - printf "...\n―――――――――――――――――――――――――――――――――――――――――――――――\n" > ./debug.log - go run . --debug {{.CLI_ARGS}}

从源码看，cmd/root.go 的Run函数在收到--debug标志后会打开debug.log文件，将日志输出切换到文件并设置时间格式与调用者信息，同时根据LOG_LEVEL环境变量（debug/info/warn/error）决定日志级别（见setDebugLogLevel()）。因此，task debug与task logs的搭配本质上是：一个进程向debug.log写日志，另一个进程tail -f实时查看。

如果你只想看更高级别的日志，Taskfile 还提供了变体：

• task debug:warn—— 只记录 warn 及以上级别（LOG_LEVEL: warn）；
• task debug:info—— 只记录 info 及以上级别（LOG_LEVEL: info）。

进阶：性能剖析与断点调试

除了日志，Taskfile.yaml 还提供了完整的剖析与调试支持：

• task profile：以DASH_PROFILE=true启动。主程序 gh-dash.go 检测到该环境变量后，会在localhost:6060启动 pprof HTTP 服务；
• task profile:cpu：抓取 10 秒 CPU profile 并在:6061可视化；
• task profile:heap/task profile:allocs：分别查看堆与分配概况；
• task dlv：以 headless 模式启动 Delve 调试器（--listen=127.0.0.1:43000），可与 IDE 远程调试对接。

另外，internal/data/logger.go 中的HTTPLogger会在 debug 模式下记录每次 GraphQL 请求的原始报文（默认 100000 字节上限，超出会标记TRIMMED并在结尾输出实际长度），是排查数据层问题的重要抓手。

Linting：本地先过一遍，省去 CI 往返

CI 会运行 lint 检查，但对 fork 来的 PR，CI 可能需要维护者批准才会启动。因此在本地先跑一遍能省去一个来回：

task lint

对应 Taskfile.yaml 中的定义：golangci-lint run --path-mode=abs --config=".golangci.yml" --timeout=5m（并显式清空GOEXPERIMENT避免干扰）。

若需要自动修复格式问题（行宽、import 排序等）：

task lint:fix

它会在上述命令后追加--fix。此外，项目还提供了针对 Nerd Font 图标的检查任务：

• task check-nerd-font—— 通过nerdfix check扫描所有 Go 文件中的异常图标字符；
• task fix-nerd-font—— 以 JSON 格式自动修复。

由于 TUI 界面大量使用 Nerd Font 图标（见 internal/tui/theme 与各组件中的图标常量），这条检查对保证界面渲染正确很有价值。

本地运行文档站点

gh-dash 的文档站点位于docs/目录（基于 Astro，入口配置见 astro.config.mjs）。本地启动只需：

task docs

然后浏览器访问localhost:4321即可预览。相关的完整流程还包括：

• task docs-build—— 先pnpm i安装依赖再执行生产构建；
• task docs-preview—— 构建后本地预览生产产物。

从 Issue 到 Merge：完整协作闭环回顾

总结 gh-dash 的贡献工作流，一条典型路径是：

1. 先在 issues/discussions 中搜索，确认问题或功能是否已存在；
2. 功能想法先在 discussions 中提出并讨论，获得反馈后再动手；
3. 实现后按"有 issue 直接开 PR / 无 issue 先开 discussion 链接分支"的原则提交；
4. 本地依次完成task lint（或task lint:fix）、task test等自检，减少 CI 往返；
5. 提交 PR 后保持参与，愿意回应评审意见并迭代修改；
6. 评审通过后由维护者合并。

整个过程始终以两条铁律为底线：理解你的代码、愿意长期维护它，并且严格遵循项目的 No-AI 政策。遵循这套流程，你不仅能顺利把改动合入 gh-dash，也会更深入地理解这个由 Bubbletea 驱动的终端 UI 项目——从 internal/tui/ui.go 的 Model 聚合，到 internal/data 的 GraphQL 数据层，再到 internal/config/parser.go 的 YAML 配置解析，整个代码库都对贡献者保持着高度可读性。

• 开发工具
• CLI
• 研发协作