操作系统开发工具AI 应用CLI【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址https://gitcode.com/GitHub_Trending/om/omarchy点击查看免费下载本指南围绕 Omarchy一个基于 Arch Linux 与 Hyprland 的现代化 Linux 发行版仓库根目录的CLAUDE.md及其引用的 AGENTS.md 展开系统梳理贡献者在修改命令、安装脚本、Quickshell 桌面、主题、测试与迁移时必须遵循的工程规范。阅读本文后你将掌握该仓库的文档分层、omarchy-*命令命名与元数据声明机制、$OMARCHY_PATH运行时约定、权限提升边界、辅助命令清单、配置目录结构以及三层测试入口能够直接依据规范在该仓库中定位文件、编写命令与测试。入口CLAUDE.md 与 AGENTS.md 的引用关系仓库根目录的CLAUDE.md全文只有一行AGENTS.md这是 Claude 系工具对指令文件的引用语法意味着所有面向 AI 编码代理的开发约束统一收敛在 AGENTS.md 中。因此AGENTS.md 才是仓库真正的开发宪法它覆盖任务指南、文档布局、编码风格、命令命名、运行时环境、权限提升、Git 提交、辅助命令、菜单、配置结构、测试与刷新模式十二个方面。后文所有小节均以 AGENTS.md 的章节为骨架展开并结合仓库源码给出实现级佐证。任务指南体系agents/skills/ 下的七个技能文档AGENTS.md 规定特定类型的工作必须先阅读agents/skills/下对应的指南再动手。该目录目前包含七个技能文档技能文档适用场景command-metadata.md新增或修改bin/下的命令install-scripts.md在install/下工作或处理系统/用户级安装命令shell-dev.md编辑shell/下的 Quickshell 桌面icon-font.md向default/fonts/omarchy/omarchy.ttf添加品牌字形acceptance-tests.md编写或运行test/acceptance.d/下的图形验收测试visual-verification.md验证任何影响运行中 UI 的视觉变更migrations.md创建或修改migrations/下的迁移脚本以命令元数据为例command-metadata.md 说明bin/下的命令可在文件顶部注释中声明 CLI 元数据bin/omarchy只扫描前 80 行测试会持续校验元数据合法性。支持的关键字包括# omarchy:group、# omarchy:name、# omarchy:summary、# omarchy:args、# omarchy:examples、# omarchy:alias/aliases、# omarchy:hiddentrue、# omarchy:requires-sudotrue。例如截图命令的元数据声明形式为# omarchy:summaryTake a screenshot # omarchy:args[smart|region|windows|fullscreen] [slurp|copy] # omarchy:examplesomarchy screenshot | omarchy capture screenshot region元数据解析在路由器 bin/omarchy 的register_command()中实现它逐行读取文件头部跳过 shebang 与空行遇非注释行即停止requires-sudo与hidden两个字段的值若不为true会直接记为元数据错误。文件名是路由的兜底来源omarchy-group-verb形式会拆出组与子命令名未显式声明summary时则回退到首个注释行。文档布局三层文档树各司其职AGENTS.md 明确仓库内存在按体裁与受众拆分的三棵文档树agents/skills/——任务操作规程做 X 时执行此流程面向所有在代码库上工作的人docs/——系统形态参考文件布局、更新管线、主题、shell 架构面向代码库工作者技能文档为求深度会链接到这里manual/——面向最终用户的 Omarchy 使用手册已发布绝不涉及代码库内部实现。这一分层与 docs/file-layout.md 中的构建映射一致manual/用户手册章节、agents/skills/贡献者任务指南、docs/、test/与plans/均不进入两个 Arch 包omarchy与omarchy-settings只存在于仓库中而bin/、install/、migrations/、themes/、shell/则会被打包为运行时内容。手册章节编号从 01 到 51覆盖欢迎、导航、主题、热键、终端、AI、游戏、双系统安装等最终用户话题例如 14-omarchy-cli.md 与 31-dotfiles.md。编码风格bash 5 条件与文件约定AGENTS.md 对仓库内 bash 代码主要在bin/、install/、migrations/、default/中给出明确风格约束Markdown 文档plans/、docs/、manual/写满整行不在 80 列处硬换行只在标题、列表项等结构边界断行缩进用两个空格禁用 Tab使用 bash 5 条件字符串/文件测试用[[ ]]数值测试用(( ))[[ ]]内变量不加引号但比较字符串字面量时要加引号如[[ $branch dev ]]数值比较优先用(( ))如(( count 50 ))而不是[[ $count -lt 50 ]]简单双分支控制流用完整的if/else不要依赖单分支中的exec或exit让后续语句不可达含空格的字符串/路径用引号包裹而不是用\转义空格shebang 必须统一为#!/bin/bash绝不用#!/usr/bin/env bash仅安全敏感入口可用精确的#!/bin/bash -p形式以抑制BASH_ENV与导出函数启动注入且必须在边界处说明理由并由回归测试覆盖install/与migrations/下的脚本可能被 source允许省略 shebang。上述约定在测试中也有体现迁移测试以bash -euo pipefail执行迁移文件而非依赖可执行位。命令命名omarchy- 前缀与 GROUP_DESCRIPTIONSAGENTS.md 的核心规定是所有命令以omarchy-开头前缀指示用途。仓库bin/目录现存 400 余个omarchy-*可执行文件均遵循该命名。常见前缀组及其用途如下前缀用途cmd-检查命令是否存在、杂项工具capture-截图、录屏与其他捕获工具pkg-包管理辅助hw-硬件检测返回退出码供条件判断refresh-把默认配置复制到用户~/.config/restart-重启某个组件launch-打开应用程序install-安装可选软件setup-交互式设置向导toggle-开关功能theme-主题管理update-更新组件面向用户浏览的命令组权威清单位于 bin/omarchy 的GROUP_DESCRIPTIONS关联数组新增可浏览命令组时必须同步维护它。AGENTS.md 特别说明某个组若其命令全部标记# omarchy:hiddentrue则不会在顶层组列表出现apply-与provision-正是因此有意缺席——它们仍然可以路由omarchy group也仍会打印组头。从源码结构看路由表完全由bin/omarchy在启动时扫描bin/omarchy-*文件构建load_commands()遍历目录register_command()解析元数据并注册路由GROUP_DESCRIPTIONS只负责顶层组的描述文案二者分离保证了命名指南不会与路由器漂移。仓库还提供omarchy-dev-benchmark-cli与omarchy commands --json等命令用于检查路由与元数据。运行时环境$OMARCHY_PATH 单一事实源AGENTS.md 规定$OMARCHY_PATH由 uwsm 会话环境在顶层设置Omarchy 运行时代码始终可用。bin/下的命令与 Quickshell QML 应依赖$OMARCHY_PATHQML 侧为Quickshell.env(OMARCHY_PATH)不要从HOME、Quickshell.shellDir推导回退路径也不要手动重新导出或提供默认值。其底层机制在 docs/file-layout.md 的Env bootstrap一节default/bash/env-bootstrap是OMARCHY_PATH与 dev-link 感知PATH的单一事实源。它优先 source/etc/omarchy.conf由omarchy-dev-link写入、omarchy-dev-unlink重置回包路径否则强制OMARCHY_PATH/usr/share/omarchy以防陈旧继承值在 unlink 后残留仅当OMARCHY_PATH不是/usr/share/omarchy时才把$OMARCHY_PATH/bin前置到PATH——生产安装下二进制已通过omarchy包以/usr/bin/omarchy-*形式在PATH上。该引导脚本被/etc/profile.d/omarchy.sh、/etc/skel/.bashrc、/usr/share/uwsm/env.d/10-omarchy与default/bash/envs四处 source且幂等。值得注意的是sudo不继承该PATH解析走/etc/sudoers的secure_path因此omarchy-dev-link还会写/etc/sudoers.d/omarchy-dev-path并在安装前用visudo -c校验。权限提升sudo 与 pkexec 的边界AGENTS.md 将权限提升规则委托给 default/agents/skills/omarchy/SKILL.md 的 Privilege Escalation 一节仓库自己的脚本遵循同一标准。规则核心是按调用方是否有终端可输入密码来划线。在可见终端中运行的交互式脚本或命令特权工作用sudoOmarchy 可能对特定命令授予免密sudo需要密码时终端正是索要密码的合适场所仅当调用方无法与终端交互或无法在那里输入密码时如由 Agent 启动的命令、图形后台进程才使用pkexec不要因为命令改变系统状态就简单地把sudo换成pkexec。该技能文件同时强调端用户定制任务中/usr/share/omarchy/是只读的读取安全且鼓励本地修改会在下次omarchy update时被覆盖安全的自定义位置是~/.config/、~/.config/omarchy/themes/name/与~/.config/omarchy/hooks/。Git 提交规范AGENTS.md 对提交提出两条简洁要求提交应原子化只包含一个连贯的变更或修复不混入无关工作提交信息应简洁并描述所做变更。这与仓库的迁移模型相呼应——每个迁移是一个独立的时间戳脚本migrations/unix timestamp.sh一次迁移只修复一个既定问题如 migrations.md 所述。辅助命令用封装代替裸命令AGENTS.md 列出应优先使用的辅助命令避免贡献者直接调用原始 shell 工具辅助命令用途omarchy-cmd-missing/omarchy-cmd-present检查命令是否存在omarchy-pkg-missing/omarchy-pkg-present检查包是否存在omarchy-pkg-add安装包同时处理 pacman 与 AURomarchy-pkg-drop移除包替代裸pacman -R*omarchy-notification-send发送桌面通知不直接调notify-sendomarchy-hw-asus-rog及同类hw-*检测特定硬件关键约束是Omarchy 默认包集安装的命令是运行时不变量直接调用即可不要为它们添加防御性的omarchy-cmd-present/omarchy-cmd-missing检查命令存在性辅助仅用于真正可选的依赖或默认包集安装前就能运行的代码。迁移脚本与包辅助脚本是例外——此时辅助命令本身可能尚未可用。菜单规范default/omarchy/omarchy-menu.jsonc菜单定义位于 default/omarchy/omarchy-menu.jsoncschema、guards 与 providers 详见 docs/menu.md。AGENTS.md 对菜单条目有一条明确禁令不要给新菜单条目添加aliases。别名仅保留给用户已经习惯输入的既有替代名如power-menu、settings用于兼容搜索并不需要它们——标签、id 末段与描述都可搜索。从 docs/menu.md 可知菜单是 Quickshell 桌面的omarchy.menu插件内容由default/omarchy/omarchy-menu.jsonc运行时从$OMARCHY_PATH读取与用户覆盖文件~/.config/omarchy/extensions/omarchy-menu.jsonc合并而成两个文件在启动时解析并受 watch编辑无需重启 shell 即生效。条目 schema 中when/checked/disabled是 bash 条件守卫全部守卫会被批量送入单个 bash 进程求值包/命令存在性通过一次pacman -Q快照在进程内回答$(omarchy-...)读值型命令只跑一次并替换进各表达式provider则让子菜单行在运行时由 shell 生成而非来自 JSONC。配置结构config/、default/themed/ 与 themes/AGENTS.md 给出三类配置文件的定位config/——复制到~/.config/的默认配置default/themed/*.tpl——含{{ variable }}占位符的主题模板占位符填入主题色themes/*/colors.toml——主题颜色定义accent、background、foreground、red/green/yellow/blue/magenta/cyan 及bright_*变体。以 themes/catppuccin/colors.toml 为实例颜色文件包含mode dark、accent、selection、多层background/foreground、八色及bright_*变体。default/themed/下现存约 20 个模板覆盖 alacritty、btop、chromium、claude、foot、ghostty、helix、kitty、neovim、obsidian、shell、vscode 等应用主题切换时由omarchy-theme-set-templates等命令以{{ variable }}替换渲染。用户侧运行时状态存于~/.local/state/omarchy/current/而~/.config/omarchy/保留用户可能用 dotfile 管理器版本化的内容用户主题、hooks、shell 布局、插件、模板覆盖。测试体系test/all、test/cli 与 test/shellAGENTS.md 要求修改后运行聚焦的自动化测试当前测试入口有三个./test/all——CLI 与 shell 测试的聚合运行器有意不运行图形验收测试./test/cli——CLI 路由、命令元数据、主题辅助与安全分发覆盖./test/shell——test/shell.d/下全部 Omarchy shell 测试。新 shell 测试应放在test/shell.d/area-test.sh以便./test/shell自动拾取并 source base-test.sh 获取共享的根路径发现、断言与 Node 测试辅助。图形验收套件在一次性 VM 中运行而非开发会话内见 acceptance-tests.md视觉变更除自动化测试外还必须在运行中的 UI 里验证见 visual-verification.md。从实现看test/all 会依次运行test/cli与test/shell两个套件即使前一个失败也继续最后汇总失败套件并以非零码退出——单点失败不会遮蔽另一套件。docs/testing.md 进一步说明./test/cli对bin/下每个omarchy-*可执行文件做元数据 lint必须有# omarchy:summary且无已移除或冗余字段./test/shell每个文件是独立套件失败粒度是运行内按文件、文件内按断言。base-test.sh 契约与无 compositor 环境每个 shell 测试以固定头开始set -euo pipefail后 sourcebase-test.sh。base-test.sh拒绝被直接执行是库而非脚本从自身位置发现仓库根并导出为ROOT测试以$ROOT/bin/...引用文件不依赖调用者工作目录或已安装的 Omarchy。断言为 TAP 风格pass description输出ok - descriptionskip description输出ok - description # SKIP需说明无法运行的原因fail description [detail]打印细节与not ok - description后退出该文件——文件内首个失败即结束避免后续断言基于已失效状态继续报告require_command cmd在缺少工具时失败该文件。require_compositor description负责 compositor 依赖测试在无头机器上的保绿无 compositor 应答时以skip并 exit 0。其探针比环境变量检查更严格——WAYLAND_DISPLAY只能证明变量被继承沙箱可能透传环境但封锁$XDG_RUNTIME_DIRQuickshell 会通过变量检查后在QGuiApplication内崩溃每次启动一个 core dump。因此compositor_reachable先检查 socket 真实存在再向 Hyprland 本体查询hyprctl -j monitors重试三次且仅当HYPRLAND_INSTANCE_SIGNATURE可问时因为中途死掉的 compositor 会遗留 socket。compositor 可达时还设置ulimit -c 0防止连接中断经qFatal()退出时留下 core dump 碎片。从 bash 单测 shell JavaScriptQuickshell 插件把逻辑放在普通.js模块如shell/plugins/menu/MenuModel.js结尾有受保护的if (typeof module ! undefined) module.exports {...}块QML 直接导入并忽略该守卫Node 则按 CommonJS 加载。这种双重身份让模型逻辑无需 compositor 即可单测。run_node_test是桥梁为 heredoc 前置 JS 预lude后管道进node预lude 镜像 bash 断言协议pass/fail/assert/assertEqual/assertDeepEqual同为ok/not ok行、同为失败即退出并提供root、path与requireFromRoot(relativePath)run_node_test JS const menu requireFromRoot(shell/plugins/menu/MenuModel.js) const parsed menu.parseMenuJsonc({ items: { root: { label: Go }, }, }) assertEqual(parsed.length, 1, menu parses JSONC with trailing commas) JS约四分之一的 shell 测试文件以此方式把解析、合并与布局逻辑当作纯函数测试compositor 门控测试只留给只有在线会话才能证明的行为。刷新模式omarchy-refresh-config 的备份语义AGENTS.md 演示了将默认配置复制到用户配置并自动备份的标准用法omarchy-refresh-config hypr/hyprland.lua这会把$OMARCHY_PATH/config/hypr/hyprland.lua复制到~/.config/hypr/hyprland.lua。参数被同时插入两个路径且只用[[ -e ]]检查——所以要传普通相对路径含..的名称会解析并复制到~/.config之外而不是被拒绝。实现位于 bin/omarchy-refresh-config先校验$OMARCHY_PATH/config/$config_file存在建立目标目录若目标已存在则备份为~/.config/file.bak.$(date %s)再覆盖并用cmp -s判断内容是否真的变化——若相同则删除备份若不同则打印带颜色的差异 diff目标不存在时直接复制。外层还有omarchy refresh config config-file路由参数相对~/.config/以及omarchy-refresh-hyprland、omarchy-refresh-shell等按组件的刷新命令。与之相对的是显式重同步命令omarchy-reinstall-configs它把/etc/skel以cp -af回放覆盖$HOME并刷新 limine/plymouth/nvim——这是破坏性操作会无备份地覆盖从/etc/skel复制来的用户文件。总结AGENTS.md 作为CLAUDE.md引用的唯一规范把 Omarchy 仓库的开发纪律收敛为可执行、可验证的规则任务指南按工种分册、文档按受众分三树、命令以omarchy-前缀统一并由bin/omarchy路由器从元数据动态建表、$OMARCHY_PATH由 uwsm 会话注入且禁止自行推导、特权操作按终端可用性在sudo/pkexec间划线、辅助命令封装裸工具、测试按 CLI/shell/图形验收三层组织且全部聚焦文件级可发现。贡献者只需遵循本指南定位到的规范与源码路径即可在改动命令、配置、主题或迁移时保持与仓库既有约定一致并被自动化测试持续守护。赞分享操作系统开发工具AI 应用CLI【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址https://gitcode.com/GitHub_Trending/om/omarchy点击查看免费下载相关推荐Omarchy 代码库开发规范指南命令路由、文档布局、配置与测试体系解析Omarchy 代码库开发规范指南命令路由、文档布局、配置与测试体系解析 Omarchy 是一款以 Arch Linux、Hyprland 与 Quicksh操作系统开发工具AI 应用CLIBlockly 仓库开发指南AGENTS.md 中的工程规范、命令体系与代码约定全解析Blockly 仓库开发指南AGENTS.md 中的工程规范、命令体系与代码约定全解析 本篇技术指南以 Blockly 仓库根目录的 AGENTS.md ht前端低代码UI组件Page Agent 仓库编码助手指南AGENTS.md 架构、开发命令与测试规范全解析Page Agent 仓库编码助手指南AGENTS.md 架构、开发命令与测试规范全解析 导读 本文基于仓库根目录 AGENTS.md https://li人工智能AI Agent浏览器控制GUI 自动化前端MCP 服务上一篇Next.js 实战在服务端渲染的 React 组件中集成 WebAssemblyRust 编译示例下一篇react-day-picker 的 Chevron 图标组件从函数签名到源码实现与自定义替换创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考