omx-setup

OMX 安装

使用此任务卡为当前项目和/或用户范围安装或刷新 OMX。共享的安全、生命周期、钩子、团队、自主性和取消规则位于 templates/AGENTS.md。不要从本卡推断新的命令行行为；实现才是权威依据。

命令与替代方案

omx setup [--force] [--merge-agents|--no-merge-agents|--clear-merge-agents-policy] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>] [--mcp <none|compat>] [--no-mcp|--with-mcp] [--disable-team|--enable-team|--team-mode <enabled|disabled>]
omx agents-init [path] [--dry-run] [--force] [--verbose]

仅将 agents-init 用于轻量的 AGENTS.md 脚手架，而不是完整安装。

支持的安装选项：

• --force：覆盖/重新安装受管产物；瞬态，不会持久化或被重放。
• --merge-agents、--no-merge-agents、--clear-merge-agents-policy：精确的裸选择器（无值/等号）。重复的相同选择器是幂等的；冲突的选择器会在变更前失败。set 会为每个调用项目根持久化显式策略；clear 会移除它，且不能与 set 组合。merge 会刷新受管区段；no-merge 只会抑制该分支，并不是保留模式。
• --dry-run、--verbose：预览操作或显示每个文件/每个步骤的详细信息。
• --scope user|project：选择用户（~/.codex、~/.omx/agents）或项目（./.codex、./.omx/agents）目标。
• --plugin / --legacy：选择交付模式；--install-mode legacy|plugin 是规范的脚本拼写。冲突的模式标志会失败。
• --mcp none|compat（加上 --no-mcp / --with-mcp）：省略或启用第一方 MCP 兼容性和共享注册表同步。
• --disable-team、--enable-team、--team-mode enabled|disabled：选择 Team 技能/上下文生成；冲突的选择器会失败。

解析安装

1. 范围：显式标志、有效的持久化 ./.omx/setup-scope.json、TTY 选择（默认 user），或非交互式 user。旧式 project-local 会迁移为 project。
2. 模式：显式标志、在保留时持久化的模式、发现的 ${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.json 且包含 name: oh-my-codex（plugin 默认值），否则为 legacy。TTY 重新运行会汇总已保存的选择，并提供保留/查看/重置；非交互式运行不会阻塞。
3. 仅在安装成功后创建所需目录并原子化持久化偏好设置。

安装会更改的内容

• Legacy 模式安装提示词/原生 Agent/技能，并合并完整的 config.toml。
• Plugin 模式归档/移除旧式 OMX 受管的提示词/技能，刷新可安装的原生 Agent TOML 和陈旧的生成式不可安装 Agent，并保留安装方拥有的运行时钩子。
• 两种模式都会验证构建出的 dist/cli/team.js 中的 Team CLI 互操作标记，仅在选中/允许时生成 AGENTS 默认值，并写入 ./.omx/hud-config.json；通知钩子引用在插件技能交付之外由安装方拥有。
• AGENTS.md 为 ./AGENTS.md。在没有 --force 或 --merge-agents 的情况下，交互式运行会在覆盖前询问，非交互式运行会保留它。活动会话保护措施可能会跳过写入。Plugin 模式可能会单独提示 AGENTS 和 developer_instructions 默认值；非交互式运行会保留现有文件。
• Plugin 模式启用安装方拥有的运行时标志（plugin_hooks、goals，或旧式 hooks/codex_hooks 回退）。项目范围使用 CODEX_HOME=./.codex，除非显式覆盖。

验证

omx setup --force --verbose
omx doctor

预期 doctor 会为所选范围内的提示词和技能、项目根 AGENTS.md、.omx/state 以及范围目标 config.toml 中的命令行优先配置提供证据。除非安装使用了 --mcp compat（如果已安装的 CLI 支持），否则会省略第一方 MCP 和共享注册表同步。

如果使用本地源码，请在运行 node dist/cli/omx.js setup --force --verbose 和 node dist/cli/omx.js doctor 之前先运行 npm run build。如果 AGENTS 未被覆盖或合并，请停止活动的 OMX 会话，并使用 --force 或 --merge-agents 重新运行；不要手动编辑生命周期状态。

发现故障排查

如果 $omx-setup 缺失或已过期：运行 omx setup --verbose，然后运行 omx doctor；对于项目范围，检查 ./.codex/skills/omx-setup/SKILL.md，对于旧版用户范围，检查 ${CODEX_HOME:-~/.codex}/skills/omx-setup/SKILL.md。在插件模式下，验证 oh-my-codex 插件是否已安装或被发现。对于重复项，检查历史 ~/.agents/skills 重叠情况，并遵循 doctor/setup 的清理指引。

退出约定

报告所选范围/模式、dry-run 与变更、AGENTS 策略、受影响的根目录以及 doctor 指标。仅在 setup 成功完成且验证确认存在预期文件/配置后才停止；失败时保留确切的命令输出，并重新运行最小的纠正命令。不要仅凭 dry-run 就声称已完成安装。