Omarchy 崩溃上游报告规范从判定归属、gh 检索到提交 Issue 的完整流程【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchyOmarchy 是一套构建在 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 Omarchys 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列出了三条必须同时满足的条件它是一个已被证据证实的、落在 Omarchy 控制域内的 bug。Issue 只用于已验证的 bug。“这到底是不是 bug”这类疑问属于 Discord 社区功能点子属于 GitHub Discussions 的 Suggestions 分类。用户已明确同意。必须把拟提交的确切标题和正文展示给用户看并等待对方明确说“是”。绝不能在用户未表态的情况下擅自提单。这台机器有能力提单——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_DEBUGtrue重跑并附上/tmp/omarchy-screenrecord.log。七、源码级背景报告对象是哪些崩溃崩溃通知如何产生理解报告流程的另一半是理解 Omarchy 从哪里发现崩溃。omarchy-crash-watch 的源码展示了整个上游机制它与报告规范形成呼应数据源是 systemd-coredump 的 journal 条目。watcher 通过journalctl -f -n 0 -o json MESSAGE_IDfc2e22bc6ee647b6b90729ab34a250b1实时追踪 coredump 日志该 MESSAGE_ID 对应systemd.journal-fields(7)中的 coredump 记录从结构化的COREDUMP_*字段中解析 uid、comm、pid、exe、signal——比 core 文件名携带的信息更多。通知携带诊断入口。每条崩溃 toast 通过omarchy-notification-send发出并绑定--exec omarchy-agent-crash $pid $comm $exe $signal——点击通知即触发 AI 诊断这正是 SKILL.md 诊断流程的触发点之一。去重与过滤。watcher 对同一程序在默认 60 秒窗口内可用OMARCHY_CRASH_DEDUPE_SECONDS调整只通知一次因为崩溃循环会反复 dump core同时过滤非当前用户的崩溃daemon 崩溃是系统管理员的问题、匹配OMARCHY_CRASH_IGNORE正则的程序以及自身的omarchy-crash-*/omarchy-agent-*机制进程。静音是按程序打标记的。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用户看过标题与正文并明确同意等待不擅自提单条件 3gh 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 都值得维护者花时间读。【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考