Omarchy 崩溃上游报告规范：从判定归属、gh 检索到提交 Issue 的完整流程

Omarchy 是一套构建在 Arch Linux 之上的、高度配置化的现代 Linux 发行方案，它通过大量的 omarchy-* 命令、Quickshell 面板、Hyprland 与终端配置来组织整个桌面体验。当系统内某个进程崩溃并被诊断确认为 Omarchy 自身的问题后，如何规范地向上游报告，是这套体系中被专门文档化的环节。本文基于仓库中的 reporting.md 展开，完整覆盖“判定归属 — 三项前置条件 — 检索去重 — 追加评论或新建 Issue — 署名”的全流程，并结合 diagnose-crash 技能入口、贡献指南 以及 omarchy-crash-watch、omarchy-crash-mute、omarchy-debug 的源码实现，说明每个报告动作背后对应的系统机制。

一、前提：先完成崩溃诊断，再谈报告

reporting.md 开篇就给出了一条硬性前置条件：

Read this only after concluding that a crash is genuinely Omarchy's to fix. （只有在判定这个崩溃确实应由 Omarchy 修复之后，才阅读本文件。）

它与 SKILL.md 构成一对：SKILL.md 负责“从 systemd-coredump 的 core dump 出发还原事实”（coredumpctl info/list/dump、debuginfod 符号化、时间线关联、排除 OOM 等无聊原因），而 reporting.md 只处理诊断的最后一个分支——“如果这是 Omarchy 的 bug，该如何上报”。SKILL.md 的收尾章节明确写道：多数应用崩溃是上游应用自身的 bug，只有在少数确实落在 Omarchy 控制域内的情况下，才去读 reporting.md。

这种“诊断与报告分离”的切分是理解整个流程的钥匙：报告规范假设读者手里已经有了证据（信号、回溯、命令行、时间戳），而不是一个猜测。

二、先问自己：这是 Omarchy 的 bug 吗

文档要求在这一环“从严”（Be strict here）。原因在于 Omarchy 的定位——它是 Arch Linux 之上的一层配置，所以第三方应用内部（文件管理器、浏览器、GNOME 或 Qt 库）的崩溃，几乎总是那个项目自己的上游 bug，而不是 Omarchy 的。

文档给出了 Omarchy 控制域的近似边界清单：

• omarchy-* 系列命令；
• Quickshell shell 本体及其插件；
• 它随发行分发的 Hyprland 与终端配置；
• 它的主题（themes）；
• 它的安装与迁移脚本（对应仓库中的 install/ 与 migrations/ 目录）；
• 它对所安装内容的打包与配置方式。

核心结论是：一个程序仅仅被 Omarchy 安装，不代表它的崩溃是 Omarchy 的 bug——除非 Omarchy 自身的打包或配置牵涉其中。如果判定“不是 Omarchy 的问题”，文档的要求是：如实说明，然后停止；可以建议用户去找正确的上游项目，但代替用户去那个项目提单不在此流程的职责范围内。

这一判断与 contributing.md 中的渠道路由一致：已验证的 bug 走 GitHub issues，功能建议走 Discussions 的 Suggestions 分类，支持类与“这算不算 bug”的问题走 Discord 社区。

三、三项必要条件：缺一不可

在确认归属之后，reporting.md 列出了三条必须同时满足的条件：

1. 它是一个已被证据证实的、落在 Omarchy 控制域内的 bug。 Issue 只用于已验证的 bug。“这到底是不是 bug？”这类疑问属于 Discord 社区；功能点子属于 GitHub Discussions 的 Suggestions 分类。
2. 用户已明确同意。 必须把拟提交的确切标题和正文展示给用户看，并等待对方明确说“是”。绝不能在用户未表态的情况下擅自提单。
3. 这台机器有能力提单——gh auth status 必须成功。如果 gh 不存在或未认证，不要顺手去安装或认证它；应当说明情况，并把写好的完整文案交给用户自行提交。

这三条实际上定义了报告行为的三个维度：证据维度（1）、授权维度（2）、工具维度（3）。任何一条不满足，流程就应停在对应位置，而不是绕过。

四、提交前先检索：重复 Issue 比不报告更贵

文档用了一句很重的话定调：A duplicate issue costs a maintainer more time than no report at all.（一个重复的 issue 花费维护者的时间比不报告更多。）

给出的检索命令是：

gh search issues --repo basecamp/omarchy "<program> crash"
gh issue list --repo basecamp/omarchy --state all --search "<signal> <program>"

检索维度上有明确要求：按崩溃的程序名、信号名（signal）以及回溯中的特征符号来搜，而不是按你即将写下的那个标题措辞去搜。

关于 --state 有一个容易踩的坑被专门指出：gh search issues 的 --state 只接受 open 或 closed，传其他值会直接报错；而省略该参数时则同时搜索两种状态——这正是检索阶段想要的行为。因此要把 closed 的 issue 一并纳入：如果一个匹配的历史 issue 已被关闭并标记为修复，而在当前系统上崩溃仍可复现，那么这是一个 回归（regression）——报告回归的价值远高于再开一个重复单。

五、追加到已有报告：先读懂，再判断“是不是同一个 bug”

当检索命中一个疑似匹配的 issue 时，文档要求先完整阅读它：

gh issue view <number> --repo basecamp/omarchy --comments

随后做“同一故障”判定，这里有一条反直觉的准则：同一个程序崩溃，不等于同一个 bug——如果触发方式（trigger）或调用栈不同，就是不同的故障。

确认为同一故障后，优先在该 issue 上追加而不是新开——但前提是你手里有线程中尚不存在的新信息，例如：

• 一个不同的复现方式；
• 别人都没有、而你有符号化的调用栈；
• 更窄的触发条件；
• 能够定位到回归起始的版本。

如果“你只有『我也遇到了』”这一条，文档的态度非常干脆：那是噪声。此时应当如实告诉用户，并且什么都不提交。追加评论的命令是：

gh issue comment <number> --repo basecamp/omarchy --body "..."

六、新建 Issue：何时开、写什么、附什么

只有当检索完全没有命中匹配项时，才走新建流程：

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

Issue 正文要求包含以下几部分：

• 发生了什么、期望是什么、复现步骤；
• 系统信息：来自 omarchy version；
• 诊断输出：来自 omarchy debug --no-sudo --print。

最后一条在仓库里可以直接印证。bin/omarchy-debug 的源码显示：它接受 --no-sudo 与 --print 两个参数，诊断日志统一写入 /tmp/omarchy-debug.log，内容包括日期/主机名、Omarchy 包版本（通过 pacman -Q omarchy-dev 或 pacman -Q omarchy 获取）、inxi -Farz 系统信息、dmesg（--no-sudo 时跳过该节）、journalctl -b -p 4..1（当前启动以来的警告与错误）以及完整安装包列表（含 AUR 包识别）。不带 --print 运行交互式 omarchy debug 时，源码显示在检测到网络连通的情况下会提供“Upload log”选项，把日志上传到 logs.omarchy.org 并生成一个 24 小时后过期 的可分享 URL——这个 URL 正是 reporting.md 所说“值得写进 issue”的那段分享链接。

另有一个工具层面的限制需要注意：gh 无法附带媒体文件。如果截图有帮助，应当先保存截图，然后把文件路径交给用户，让用户把它拖进 Web 表单。这一点在 contributing.md 中同样被强调，并且给出了配套的截图/录屏命令（omarchy capture screenshot、omarchy screenrecord）；对于屏幕录制本身的失败，还建议用 OMARCHY_SCREENRECORD_DEBUG=true 重跑并附上 /tmp/omarchy-screenrecord.log。

七、源码级背景：报告对象是哪些崩溃，崩溃通知如何产生

理解报告流程的另一半，是理解 Omarchy 从哪里发现崩溃。omarchy-crash-watch 的源码展示了整个上游机制，它与报告规范形成呼应：

1. 数据源是 systemd-coredump 的 journal 条目。watcher 通过 journalctl -f -n 0 -o json "MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1" 实时追踪 coredump 日志（该 MESSAGE_ID 对应 systemd.journal-fields(7) 中的 coredump 记录），从结构化的 COREDUMP_* 字段中解析 uid、comm、pid、exe、signal——比 core 文件名携带的信息更多。

2. 通知携带诊断入口。每条崩溃 toast 通过 omarchy-notification-send 发出，并绑定 --exec omarchy-agent-crash "$pid" "$comm" "$exe" "$signal"——点击通知即触发 AI 诊断，这正是 SKILL.md 诊断流程的触发点之一。

3. 去重与过滤。watcher 对同一程序在默认 60 秒窗口内（可用 OMARCHY_CRASH_DEDUPE_SECONDS 调整）只通知一次，因为崩溃循环会反复 dump core；同时过滤非当前用户的崩溃（daemon 崩溃是系统管理员的问题）、匹配 OMARCHY_CRASH_IGNORE 正则的程序，以及自身的 omarchy-crash-* / omarchy-agent-* 机制进程。

4. 静音是按程序打标记的。watcher 在每条崩溃的最后一步检查 omarchy-toggle-enabled "crash-ignore/$name"——这与 omarchy-crash-mute 的实现完全对应：静音状态以 ~/.local/state/omarchy/toggles/crash-ignore/<program> 下的独立文件（flag）存在，按程序一个 flag 而非一份共享列表，这样解除某个程序的静音时不必读取、重写并重新解析其余部分。SKILL.md 建议诊断收尾时“提议为这一个程序静音通知”，并附上了用法：

   omarchy-crash-mute '<program>'        # 静音
   omarchy-crash-mute '<program>' off    # 恢复通知
   omarchy-crash-mute                    # 列出已静音项
   

   源码里还有几个值得注意的细节：mute 的 key 是可执行文件 basename，所以 omarchy-crash-mute 会把传入的路径用 ${program##*/} 归约成与 watcher 相同的键（见 bin/omarchy-crash-mute 第 48 行）；而 comm 字段被内核截断到 15 个字符，因此 SKILL.md 特别警告优先使用 binary: 路径而不是 process: 名——静音一个被截断的进程名会永远匹配不上，却看起来像生效了。此外程序名必须加引号，因为名字里可能含有单引号等 shell 元字符。全局开关则位于 Trigger > Toggle > Crash Capture（在 omarchy-menu.jsonc 中注册）。

这些机制说明了两点，恰好对应 reporting.md 的判断标准：其一，只有“shell 本体、插件、omarchy-* 命令、其配置与主题”这条链路上的崩溃才可能属于 Omarchy 控制域；其二，第三方程序即便出现在同一张崩溃通知里，也默认指向它们自己的上游。

八、署名：机器撰写的公开声明

流程的最后一步是署名。文档要求每条 issue 或评论以一行文字结尾，标明产出它的模型与 agent 运行框架（harness），让人类读者知道这是机器撰写的：

Filed by <model name> via <agent harness>.

并且要求使用真实的模型与 harness 名称；如果自己不确定，就直说，而不是编造一个版本号字符串。这条规则与诊断章节的总基调一致——“诚实的陈述，而非听起来可信的故事”。

九、流程速查

把 reporting.md 的完整决策路径压缩成一张速查表：

步骤	判定 / 命令	不满足时的行为
归属判定	崩溃是否落在 Omarchy 控制域（命令、shell/插件、Hyprland 与终端配置、主题、安装迁移脚本、打包配置）	如实说明，停止；可指向上游项目
条件 1	证据证实的 bug（非疑问、非建议）	疑问去 Discord，建议去 Discussions
条件 2	用户看过标题与正文并明确同意	等待，不擅自提单
条件 3	gh auth status 成功	不安装/不认证，把文案交给用户
检索	gh search issues / gh issue list --state all --search（含 closed）	命中已关闭且可复现 → 按回归处理
追加	gh issue view <n> --comments 确认同一故障且有增量信息	“我也遇到了” → 什么都不提交
新建	gh issue create --repo basecamp/omarchy，附 omarchy version 与 omarchy debug --no-sudo --print 输出（/tmp/omarchy-debug.log，交互版可生成 24 小时有效的分享 URL）	截图交给用户路径，手动拖入 Web 表单
署名	Filed by <model> via <harness>.	不确定型号就明说，不编造

十、小结

reporting.md 的篇幅不长，但把一条完整的开源协作纪律写得很实：归属判定从严、三项条件缺一不可、检索包含已关闭 issue 以识别回归、追加评论必须携带增量信息、机器输出必须署名。它与同目录的 SKILL.md 以及 contributing.md 一起，构成了 Omarchy 从“崩溃通知 → AI 诊断 → 归属判定 → 上游报告”的闭环；而 bin/omarchy-crash-watch 与 bin/omarchy-crash-mute 的源码则证明，这套流程的每一步都有对应的系统机制（journal 追踪、按程序的 flag 静音、15 字符进程名截断的规避）在支撑。对于维护者而言，这些规则的共同目标只有一个：让到达上游的每一条 issue 都值得维护者花时间读。