Omarchy 上游贡献工作流：从 Bug 报告、诊断日志收集到 PR 提交的完整实践

本篇基于 Omarchy 仓库中面向 AI Agent 的贡献技能文档 contributing.md 展开，讲解 Omarchy 上游（basecamp/omarchy 仓库）的官方问题反馈与代码贡献流程：如何正确路由 Bug 报告、功能建议与支持请求，如何用 omarchy debug 采集可上传的诊断日志并附上屏幕录像，以及如何 fork 工作副本、遵循仓库自身规范完成 PR。读完本文，你既能替用户高质量地上报一个带完整诊断信息的 issue，也能独立完成一次符合仓库风格与测试要求的代码修复。

三类请求的渠道路由

Omarchy 对反馈渠道有明确的分工，报告前必须先判断请求类型，把它放到正确的地方（依据 contributing.md 的路由规则）：

• 已确认的 Bug → 上游仓库的 GitHub Issues。Issue 只接受经过验证的 bug，不接受支持类请求；
• 功能想法与建议 → 上游仓库 Discussions 的 Suggestions 分类；
• 支持与"这到底算不算 bug"类问题 → 官方 Discord 社区（入口在 Omarchy 官网 omarchy.org）。当问题还不能明确认定是 Omarchy 本身的缺陷时，应该从这里开始排查，而不是直接开 issue。

这个分工的意义在于：把"疑似 bug"直接提交到 issue 区会污染已验证 bug 队列；而支持类问题在 Discord 里通常能更快得到解答，也能帮你判断后续是否真的需要走 issue 流程。

填写一份合格的 Bug 报告

上游的 bug 模板要求提供三类信息：系统细节（CPU、GPU、Omarchy 版本）、带复现步骤的问题描述、诊断信息。omarchy CLI 把采集这些信息的过程压缩成了两条命令：

omarchy version

# 生成诊断日志（同时写入 /tmp/omarchy-debug.log）
omarchy debug --no-sudo --print

omarchy debug 到底采集了什么

omarchy debug 由 bin/omarchy-debug 实现，其命令元数据标注了 requires-sudo=true（第 6 行），说明默认路径是需要 root 权限的完整采集模式；--no-sudo 与 --print 是两个可选开关，行为在源码中一一对应：

• --no-sudo：跳过 sudo dmesg 环节，内核环日志部分替换为 (skipped - --no-sudo flag used) 占位文本（见 bin/omarchy-debug）。官方技能文档 SKILL.md 特别强调：交互式/无终端环境下应始终加 --no-sudo --print，避免交互式 sudo 密码提示挂死终端；
• --print：将日志直接打印到 stdout 后退出（bin/omarchy-debug），适合非交互场景把日志交给用户或写进 issue 正文。

无论是否加 --print，日志都会先落盘到 /tmp/omarchy-debug.log（bin/omarchy-debug）。日志内容分四个板块（bin/omarchy-debug）：

1. SYSTEM INFORMATION：inxi -Farz 输出，覆盖 CPU、GPU、内存与系统架构，正好对应 bug 模板要求的系统细节；
2. DMESG：完整内核环日志（--no-sudo 时跳过）；
3. JOURNALCTL：当前启动周期内的 warning 与 error 级日志（journalctl -b -p 4..1，bin/omarchy-debug）；
4. INSTALLED PACKAGES：全部 pacman 已装包及其版本，并用 comm 对比 pacman -Sql 数据库额外标出 AUR 来源的包，方便上游判断是否与第三方包冲突。

头部还记录了日期、主机名以及 omarchy 包名与版本（优先匹配 omarchy-dev，回退 omarchy，见 bin/omarchy-debug）。

交互式模式与日志上传

不带 --print 时，omarchy debug 生成日志后会用 gum choose 弹出菜单，提供"查看日志 / 保存到当前目录"，并且只有在 ping -c 1 8.8.8.8 探测到网络可用时才追加"上传日志"选项（bin/omarchy-debug）。选择上传后，日志通过 curl 以 multipart 表单发送到 logs.omarchy.org，表单带 expires=24 字段，即生成的分享链接 24 小时后过期（bin/omarchy-debug）——所以这个 URL 适合直接粘贴进 issue 正文，而不适合长期留存。

此外还有一个隐藏命令 bin/omarchy-upload-log，用于上传特定场景的日志包，支持 install（默认，含 archinstall 与 omarchy 安装日志）、this-boot（本次启动 journalctl）、last-boot（上次启动）、installed（系统信息 + 全部已装包）四种类型，同样走 24 小时过期的日志服务器。排障安装失败或启动问题时可以直接复用这条通道。

用屏幕截图/录像固化问题现场

文档特别指出：一段能复现问题的截图或短录像，往往比文字描述更有价值。Omarchy 自带的采集命令（完整说明见同目录的 capture.md，路由前缀 capture- 在上游 bin/omarchy 的 GROUP_DESCRIPTIONS 中登记为"Screenshots and screen recording"）：

omarchy screenshot                            # 交互式智能区域流程
omarchy capture screenshot region             # 框选区域
omarchy capture screenshot windows            # 按窗口截取
omarchy capture screenshot fullscreen save    # 全屏直存磁盘（跳过标注编辑器）

omarchy screenrecord --fullscreen             # 开始录制全屏
# ...在镜头前复现问题...
omarchy screenrecord --stop-recording          # 停止并打印保存路径

要点：screenrecord 不加 --fullscreen 时会先弹出区域选择器；录像默认存到 Videos 目录，可用 OMARCHY_SCREENRECORD_DIR 覆盖；截图默认存到 Pictures 目录，可用 OMARCHY_SCREENSHOT_DIR 覆盖。录像务必短小、聚焦在异常行为本身。

录像失败时额外采集 screenrecord 日志

如果 bug 本身就是"屏幕录像失败"，重新执行时加环境变量 OMARCHY_SCREENRECORD_DEBUG=true，底层实现会把 gpu-screen-recorder 的 stderr 追加到 /tmp/omarchy-screenrecord.log（见 bin/omarchy-capture-screenrecording：LOG_FILE 在该变量为 true 时指向此日志文件，否则指向 /dev/null）。把这个文件一并附到报告里即可。

提交 Issue

gh issue create --repo basecamp/omarchy --title "..." --body "..."

Issue 正文应包含六要素：实际发生了什么、期望行为、复现步骤、系统细节、debug 日志 URL（或附件日志）、屏幕截图/录像。一个容易踩的细节：GitHub issue 的附件要通过网页表单拖拽添加，gh 命令行本身无法上传媒体文件——所以保存好截图/录像后，把文件路径交给用户手动拖入表单。

提交 PR：fork 工作副本与仓库规范

绝不直接改 /usr/share/omarchy

修复上游 bug 时的第一原则：不要对已安装的 /usr/share/omarchy 目录做开发。该目录由 omarchy 包所有，SKILL.md 明确指出其中任何本地改动都会在下次 omarchy update 时被覆盖。正确做法是 fork 一份独立工作副本：

gh repo fork basecamp/omarchy --clone
cd omarchy

仓库自带 AGENTS.md 是贡献权威

contributing.md 要求 PR 作者遵循仓库根目录的 AGENTS.md，其中与贡献质量直接相关的约定包括：

• 代码风格（AGENTS.md）：bash 5 条件语法（[[ ]] / (( ))）、脚本 shebang 统一 #!/bin/bash、路径含空格用引号而非反斜杠转义等；
• Git 提交（AGENTS.md）：提交必须原子化——一个提交只包含一个内聚的变更，不混入无关改动；提交信息简短且准确描述改动内容；
• 测试入口（AGENTS.md）：推送前运行聚合测试入口 test/all，它覆盖 CLI 与 shell 测试但有意不运行图形验收测试（后者在一次性 VM 中执行，见 agents/skills/acceptance-tests.md）。测试套件的具体构成可参考 docs/testing.md。

视觉类修复必须附前后对比

如果一个 PR 修复的是视觉问题，PR 中应包含修复前后的对比截图——同样用 omarchy capture 系列命令采集。这条要求与 agents/skills/visual-verification.md 的"视觉变更必须在运行中的 UI 里验证"原则一脉相承。

贡献前自检清单

把 contributing.md 的要求浓缩成一张可执行的清单：

环节	检查项	依据
路由	是已验证 bug、功能建议还是支持问题？放对渠道了吗	contributing.md 路由表
诊断	是否运行了 omarchy version 与 omarchy debug --no-sudo --print	bin/omarchy-debug
日志	日志 URL 是否已写入 issue（注意 24 小时过期）	bin/omarchy-debug
现场	是否保存了聚焦问题行为的截图/短录像，并把文件路径交给用户拖入表单	capture.md
录像故障	是否用 OMARCHY_SCREENRECORD_DEBUG=true 补采了 /tmp/omarchy-screenrecord.log	bin/omarchy-capture-screenrecording
工作副本	是否 fork 了独立副本而非改 /usr/share/omarchy	contributing.md、SKILL.md
提交质量	提交是否原子、推送前是否跑过 ./test/all、视觉修复是否附前后对比	AGENTS.md

这套流程体现了 Omarchy 社区的一个特点：诊断采集、日志托管、截图录像全部内建在发行版自带的 omarchy CLI 中，贡献者（包括自动化 Agent）不需要额外安装任何工具，就能产出上游可直接采信的报告与 PR。