oh-my-openagent（OmO）统一 Agent 状态目录：`~/.omo/agent` 的解析规则、legacy 迁移与 QA 验证

oh-my-openagentOmO统一 Agent 状态目录~/.omo/agent的解析规则、legacy 迁移与 QA 验证【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent导读本文基于 .omo/evidence/20260814-omo-agent-dir-unification/README.md 这一 QA 证据记录系统讲解 oh-my-openagentOmO命令名omo如何将引擎状态目录收敛为唯一的规范位置HOME/.omo/agent包括环境变量解析优先级、launcher 向引擎注入目录的完整链路、从旧扁平布局HOME/.omo的一次性安全迁移carry-forward以及该特性在真实引擎与捕获桩capture stub两种表面上的验证方法与结论。读完本文你将掌握 OmO 状态目录的解析与覆盖规则、迁移的幂等与不覆写保证以及如何用隔离 HOME 的沙箱脚本验证这类启动期行为。为什么需要唯一目录三个入口、三个默认值的历史问题在统一之前OmO 的每个入口各自携带一份默认目录解析逻辑——发布版 launcher、omo doctor、omo setup以及本地安装的 launcher 各自决定引擎状态放哪里。结果就是同一个产品会因启动方式不同而读取三个不同的目录当某一次更新只改了其中一个默认值时用户看到的现象就是设置被清空了尽管数据其实原封未动地躺在另一个目录里。这段动机直接写在该特性的唯一实现文件中packages/omo-native/bin/lib/agent-dir.js 的模块注释明确声明The one place that answers where does omo keep engine state——每一个 OmO 入口都必须通过该模块解析目录。统一目录的核心目标就是无论从哪个入口启动、无论是否设置了环境变量最终解析出的引擎状态目录始终是同一个。核心机制一规范目录解析canonicalAgentDir解析顺序三个环境变量 一个默认值目录解析的唯一实现是canonicalAgentDir()agent-dir.js它按固定优先级处理三个环境变量优先级环境变量说明1最高OMO_CODING_AGENT_DIR当前品牌OmO的显式目录2SENPI_CODING_AGENT_DIR引擎 senpi 的 legacy 名称向后兼容3PI_CODING_AGENT_DIR更早期的名称继续保留以兼容旧脚本4兜底—默认规范位置HOME/.omo/agent其行为细节显式覆盖优先只要某个变量有非空值就使用resolve(configured)解析后的绝对路径不再看后面任何变量空白值视为未设置env[name]?.trim()之后为空则跳过回落到下一个变量乃至默认值默认目录固定defaultAgentDir(home)返回join(home, .omo, agent)agent-dir.js运行时 HOME 优先于系统 homedirruntimeHome()依次取env.HOME || env.USERPROFILE || homedir()agent-dir.js保证 Windows 下通过环境变量携带的运行时 home 优先于os.homedir()。上述优先级、空白值回落、品牌名优先于 legacy 名的行为全部有单元测试逐一锁定见 packages/omo-native/test/agent-dir.test.ts。全入口统一谁在用 canonicalAgentDir通过代码搜索可以确认以下所有入口与工具模块都已改为经由agent-dir.js解析不再各自维护默认值launcherpackages/omo-native/bin/lib/launcher.js启动引擎前调用canonicalAgentDir(env)doctorpackages/omo-native/bin/lib/doctor.jssetup 检测链路setup-detect.js、setup-detect-cache.js、setup-detect-refresh.js、setup-import.js均导入canonicalAgentDir编译入口packages/omo-native/compile-entry.ts。这意味着统一目录不是 launcher 单点的行为而是整个产品的全局约束。核心机制二launcher 如何把目录交给引擎在 launcher.js 的senpiEnvironment()中解析结果被同时注入两个环境变量交给引擎进程const agentDir canonicalAgentDir(env) env.OMO_CODING_AGENT_DIR agentDir env.SENPI_CODING_AGENT_DIR agentDir这段代码注释解释了同时设置两个名字的原因legacy 名称也一并传递这样由工具直接 spawn 出来的裸 senpi 进程会继承同一份状态目录而不是回落到它自己的默认位置——这正是一致性的关键。除此之外senpiEnvironment()还注入了OMO_NATIVE1用于 OmO Native 品牌标识、SENPI_RUNTIMEbun 或 node避免引擎二次决策运行时、SENPI_BRANDJSON 品牌画像含configDir: .omo与flatLayout: false见 launcher.js、OMO_BIN保证按名解析产品时重新进入 launcher等。品牌画像中configDir: .omo与flatLayout: false正是 QA 记录中 capture stub 捕获到的两个字段。核心机制三legacy 扁平布局的一次性迁移adoptLegacyFlatState统一目录最大的风险是看起来像一次重置老用户的引擎状态此前直接散落在HOME/.omo/settings.json扁平布局即引擎状态直接写在配置目录下legacyFlatAgentDir()返回join(home, .omo)。因此agent-dir.js提供了adoptLegacyFlatState()在首次启动时把旧状态搬运进规范目录。迁移的六个规则从 adoptLegacyFlatState 的实现可以归纳出严格的行为契约只在默认目录生效如果canonicalAgentDir()因为用户设置了环境变量而指向别处迁移直接跳过——用户亲手 pin 的目录绝不被触碰第 98-99 行允许列表搬运只迁移settings.json、auth.json、models.json、models-store.json、mcp.json、trust.json六个小型配置文件ADOPTED_STATE_FILESagent-dir.jssessions、caches、logs 留在原地避免启动变成无界拷贝已存在文件不覆盖目标文件已存在时除settings.json走 backfill 外其余一律不动settings 只做缺口回填backfillbackfillSettings()计算 legacy 文件有、canonical 文件没有的顶层 key只合并这些缺失键agent-dir.js。canonical 永远是更新的真相flat 只负责补洞回填前先把 canonical 备份为settings.json.bak-ISO 时间戳幂等 标记迁移完成后写入标记文件.adopted-from-omo-flatADOPTION_MARKERagent-dir.js后续启动见到标记即跳过绝不重复迁移坏 JSON 不阻塞启动legacysettings.json无法解析时readJsonFile()返回undefined本次跳过迁移且不写标记——用户修复文件后下次启动仍会补迁移任何情况下启动都不会被一份手改坏的配置文件卡死agent-dir.js。launcher 在启动路径上调用它并输出提示reportLegacyFlatAdoption() 会在result.adopted为真时打印omo: carried forward settings from the legacy ~/.omo layout (...)。QA 验证方案隔离 HOME 真实引擎 捕获桩QA 记录本身run.sh设计了两层验证分别针对产品能启动与launcher 究竟给引擎钉了什么两个问题真实引擎表面把开发者全局 omo-ai 安装中的code-yeongyu/senpi符号链接进沙箱包验证产品能真实启动并解析状态捕获桩表面用一个写入CAPTURE_FILE的桩引擎dist/cli.js记录它收到的完整环境验证 launcher 对引擎注入的目录值。沙箱HOME只预置统一前的扁平布局一个HOME/.omo/settings.json含favoriteModels与retry.fallbackChains随后依次执行omo --version、omo doctor两次、omo setup --dry-run、一次无覆盖的桩运行、一次设置OMO_CODING_AGENT_DIR的桩运行。完整输出见 transcript.txt。QA 观察结果四条核心结论1. 规范目录解析成立捕获桩收到的子进程环境为transcript.txt{ OMO_CODING_AGENT_DIR: HOME/.omo/agent, SENPI_CODING_AGENT_DIR: HOME/.omo/agent, brandConfigDir: .omo, brandFlatLayout: false }同时omo setup --dry-run报告 senpi harness 就来自该目录并输出PASS: no ~/.senpi anywhere in the sandbox——旧默认值曾使用的目录从未被创建。2. 显式覆盖仍然生效设置OMO_CODING_AGENT_DIRSANDBOX/pinned后两个变量名到达引擎时均为SANDBOX/pinned覆盖优先级得到验证transcript.txt。3. 不重置迁移保留全部滞留值首次 launcher 调用打印omo: carried forward settings from the legacy ~/.omo layout (settings.json)随后HOME/.omo/agent/settings.json完整持有原值favoriteModels为[anthropic/claude-fable-5,apitopia/kimi-k3-unlocked]fallbackChains为{claude-fable-5:[],openmodel/claude-fable-5:[anthropic-api/claude-fable-5:xhigh]}而扁平原文件的哈希保持字节一致0ba283a2...UNCHANGED——迁移只读不写旧文件。4. 幂等第二次启动没有任何 adoption 提示canonical 文件哈希不变PASS: canonical file unchanged。启动本身也正常omo --version输出omo 5.0.0-0.beta.7 (engine: senpi 2026.8.12-4)transcript.txt。隔离性与残余风险QA 自身的可信度边界该 QA 的另一半价值在于证明测的是沙箱没碰开发者真实状态运行前后开发者real HOME/.omo/settings.json哈希不变a1ab2671...real HOME/.omo/agent/.adopted-from-omo-flat不存在证明 carry-forward 从未在沙箱外运行沙箱运行窗口内开发者real HOME/.omo/agent/settings.json确有变化14bbcdea...到d5521fca...但这是开发者自己正在运行的 omo 会话所致新值是一条五段的claude-fable-5回退链、以apitopia/glm-5.2:max结尾既不出现在沙箱夹具claude-fable-5: []也不在扁平文件中且上述两个标记证明 QA 没有任何写路径触及它。残余风险文档自述carry-forward 会读取一个可能被用户并发编辑的目录。缓解设计是它只添加 canonical 文件缺失的键且先备份再写因此并发编辑不会丢失任何内容。已声明的省略项omo setup --dry-run需要凭据来源沙箱 opencodeauth.json存放的是字面量占位符SANDBOX-ONLY-NOT-A-REAL-KEY未使用任何真实密钥transcript 中FAIL senpi version: expected 2026.8.13, found 2026.8.12-4是沙箱产物分支钉住2026.8.13而沙箱符号链接的是全局安装的2026.8.12-4不是产品缺陷。单元测试补齐的分支沙箱跑不动的角落单次沙箱无法廉价覆盖所有分支因此文档明确指出由单元测试补齐packages/omo-native/test/agent-dir.test.tslegacy 环境变量SENPI_CODING_AGENT_DIR、PI_CODING_AGENT_DIR各自被按序采纳OMO_CODING_AGENT_DIR优先第 48-64 行空白覆盖值为 时回落到默认规范位置第 66-69 行malformed legacy JSON{ not json不会破坏启动canonical 文件保持原样且不写标记第 147-157 行永不覆写规则canonical 已存在favoriteModels时只回填缺失的retry键且生成settings.json.bak-*备份第 108-123 行跳过场景设置了OMO_CODING_AGENT_DIR覆盖时adopted为 false且覆盖目录不会被创建第 127-138 行无 legacy 状态的空 HOME 保持为空第 140-145 行不复活已删状态二次迁移是 no-op不会把 canonical 中已删除的键从 flat 复活第 93-104 行。实操要点小结想给 OmO 指定引擎状态目录设置OMO_CODING_AGENT_DIR最优先旧脚本可继续用SENPI_CODING_AGENT_DIR或PI_CODING_AGENT_DIR默认状态目录恒为HOME/.omo/agent品牌配置目录为.omobrandConfigDirflatLayout: false表示引擎状态不再直接写入配置目录首次从旧版本升级启动时launcher 会一次性把扁平布局中的六个状态文件搬入规范目录看到carried forward settings from the legacy ~/.omo layout属正常行为原文件不会被改动第二次启动不再提示若用户已显式设置目录迁移逻辑完全跳过绝不触碰用户指定的目录。延伸阅读特性 QA 记录.omo/evidence/20260814-omo-agent-dir-unification/README.md、run.sh、transcript.txt唯一实现packages/omo-native/bin/lib/agent-dir.jslauncher 注入链路packages/omo-native/bin/lib/launcher.js单元测试packages/omo-native/test/agent-dir.test.ts统一入口佐证doctor.js、setup-detect.js、compile-entry.ts【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考