尧图网站建设 
OmX sparkshell 实战指南用 Rust 原生侧车驯服命令输出噪音与 tmux 面板检查【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codexomx sparkshell是 OmXOh My codeX提供的一个原生 Rust 命令执行与智能总结侧车它以独立二进制的方式执行任意命令、显式 shell 脚本或 tmux 面板内容在输出超过阈值时调用本地模型 API 生成摘要并内置密钥脱敏、结果缓存与 JSON 报告能力。本文将以 experimental-dev-omx-sparkshell.md 的 PR 变基记录为骨架结合 src/cli/sparkshell.ts 与 crates/omx-sparkshell 的源码实现完整讲解它的三种执行模式、原始输出与摘要的切换逻辑、环境变量配置、团队检查集成以及降级容错机制。读完本文你将能够独立构建、调用并扩展omx sparkshell并在omx team status的检查元数据中直接使用它完成 leader 排查。一、为什么需要 sparkshell从海量输出到可执行结论在团队模式team mode与 tmux 多面板工作流中leader 与 HUD 面板会持续产生大量命令输出构建日志、测试失败堆栈、git 历史、心跳文件……这些输出往往动辄数百上千行其中真正决定下一步动作的信息失败命令名、非零退出码、可执行的恢复提示、关键文件路径却被噪音淹没。omx sparkshell的设计目标正是解决这个问题命令执行本身交给原生 Rust 侧车完成超长输出交给本地模型 API 总结总结与原始行为之间以明确的阈值自动切换从而让看一眼输出就能决定下一步成为可能。该特性以 PR 形式合并到experimental/dev分支其变基记录即本文所依托的 experimental-dev-omx-sparkshell.md。从当前仓库结构看经过后续调整Rust crate 位于crates/omx-sparkshell而非 PR 记录中的native/omx-sparkshell且已被排除出根 Cargo workspace以保证仓库根目录的 manifest-path cargo 命令正常工作。二、总体架构CLI 调度、原生二进制发现与执行2.1 调用链omx sparkshell的完整调用链分两层TypeScript 调度层src/cli/sparkshell.ts 中的sparkshellCommand(args)负责解析--help、定位原生二进制、处理降级路径最终通过runSparkShellBinary同步派生子进程执行。Rust 执行层crates/omx-sparkshell/src/main.rs 中的run(args)负责解析参数、执行命令、脱敏、缓存与总结最后以命令的退出码退出。2.2 二进制发现顺序源码级resolveSparkShellBinaryPathWithHydrationsrc/cli/sparkshell.ts按如下优先级定位原生二进制环境变量OMX_SPARKSHELL_BIN显式指定的绝对/相对路径包内缓存目录中状态为verified的托管原生二进制resolveCachedNativeBinaryCandidatePaths打包路径bin/native/platform-arch[/libc]/omx-sparkshellLinux 上按musl优先、glibc次之的顺序探测见packagedSparkShellBinaryCandidatePaths仓库本地构建产物target/release/omx-sparkshell与嵌套的crates/omx-sparkshell/target/release/omx-sparkshell以上均失败时尝试从 release 资产水化hydrate下载仍未找到时抛出错误提示设置OMX_SPARKSHELL_BIN或联网获取 release 资产。Windows 上的二进制名为omx-sparkshell.exe其余平台为omx-sparkshellsparkshellBinaryName。三、三种执行模式与核心参数omx sparkshell支持三种互斥的执行目标均需显式 opt-in模式语法说明直接命令Direct argvomx sparkshell command [args...]直接以 argv 执行不经过 shell不做元字符解析显式 Shellomx sparkshell --shell shell command通过 shell 执行脚本元字符仅在显式 opt-in 时生效tmux 面板omx sparkshell --tmux-pane pane-id [--tail-lines 100-1000]捕获更大范围的面板尾部并应用相同的 raw-vs-summary 逻辑直接命令模式在 POSIX 上以bash -lc展开见 exec.rs 的resolve_shell_argv_for_platformWindows 上则按pwsh→powershell.exe→cmd.exe /d /s /c的优先级选择。--tail-lines默认 200 行取值范围 100~1000越界、非数字或未与--tmux-pane搭配使用时均会报错parse_tail_lines与parse_input中的校验均有对应测试覆盖见 main.rs 的tests模块。其余全局参数Rust 侧parse_input解析--json输出结构化 JSON 报告详见第七节--budget chars/--budgetchars摘要字符预算默认 1000超长文本在安全字符边界截断并标注[truncated: N chars omitted]--since-last与缓存配合仅报告自上次观察以来的新增行见第六节--cacheon|off、--cache-ttl-ms ms控制结果缓存默认开启、TTL 为 10 分钟--team name、--worker name结合OMX_TEAM_STATE_ROOT下的团队状态做诊断分类详见第八节。四、构建与打包从源码到可执行二进制omx-sparkshell是一个独立的 Rust 二进制 crateCargo.toml依赖同仓库的omx-muxcrate用于复用build_capture_pane_args生成 tmux 捕获参数。构建与验证入口位于 src/scripts/build-sparkshell.ts 与 src/scripts/test-sparkshell.ts对应 PR 记录中的scripts/build-sparkshell.mjs/scripts/test-sparkshell.mjs仓库内为 TypeScript 源文件。PR 记录的本地验证命令链experimental-dev-omx-sparkshell.md完整复现如下npm run lint npm run check:no-unused npm run build:full cargo test --manifest-path crates/omx-sparkshell/Cargo.toml node scripts/build-sparkshell.mjs node scripts/test-sparkshell.mjs node bin/omx.js sparkshell cargo --version node bin/omx.js sparkshell npm --version node bin/omx.js sparkshell git log --oneline -3 npm test注意两点操作细节均为 PR 记录中的实际约束npm test会在打包清理时移除暂存的打包二进制需在验证后重新恢复被跟踪的二进制Rust 构建产物crates/omx-sparkshell/target/应在验证后清理不进入版本库。omx sparkshell --helpTypeScript 层会输出 SPARKSHELL_USAGE 中的完整用法与环境变量说明Rust 二进制的--help则由 usage_text() 输出两者互为印证。五、raw-vs-summary输出阈值与总结切换逻辑这是 sparkshell 的核心行为。执行命令获得原始输出后main.rs 的run流程如下脱敏先对 stdout/stderr 做密钥脱敏见第八节摘要路径使用脱敏后的输出阈值判断用combined_visible_lines统计 stdout 与 stderr 的总行数与阈值比较。阈值默认 12 行可由环境变量OMX_SPARKSHELL_LINES覆盖仅接受正整数非法值回退默认见 threshold.rs分支处理行数 ≤ 阈值直接原样输出write_raw_output不做总结以原始退出码退出行数 阈值非 JSON 模式调用summarize_output生成摘要并以--budget截断输出若总结失败如本地 API 不可用回退为原始输出并打印summary unavailable ...; showing raw output instead。非 JSON 模式下无论是否总结进程最终都以被执命令的退出码退出process::exit(output.exit_code())保证脚本化的退出码语义不被破坏。六、本地模型 API 桥接与结果缓存6.1 总结请求codex_bridgecodex_bridge.rs 实现了对本地 API 的 HTTP 调用POST base/v1/responses请求体含model、input、reasoning: {effort: low}、stream: false。其模型与端点解析顺序如下API 地址OMX_API_BASE_URL→OMX_API_PORT拼成http://127.0.0.1:port→ 默认http://127.0.0.1:14510摘要模型OMX_SPARKSHELL_MODEL→OMX_DEFAULT_SPARK_MODEL→OMX_SPARK_MODEL→ 默认gpt-5.6-luna回退模型OMX_SPARKSHELL_FALLBACK_MODEL→OMX_DEFAULT_STANDARD_MODEL→ 默认gpt-5.6-terra超时OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS默认 60 秒。当主模型请求失败且错误信息命中quota、rate limit、429、unavailable、model not found、capacity等关键词时自动用回退模型重试should_retry_with_fallback。响应解析支持output_text顶层字段与responses风格的嵌套output结构extract_output_text/extract_response_output_text并兼容多种 JSON 字符串形态。安全方面API 地址默认仅允许 loopback 主机localhost或127.0.0.0/8回环地址非回环主机需显式设置OMX_API_ALLOW_UNSAFE_BASE_URL1才放行parse_http_url及其测试认证 token 通过OMX_API_LOCAL_BEARER或OMX_API_STATE_FILE指向的 daemon 状态文件解析。6.2 摘要规范化与指令约束模型输出经由normalize_summary白名单化仅保留summary:、failures:、warnings:三个顶级节其余节如next steps:会被丢弃并以固定格式渲染为 markdown 列表。构造 prompt 时prompt.rs 的build_summary_prompt会先识别命令族git、node-js、python、rust、go、ruby、java-kotlin、c-cpp、csharp、swift、generic-shell 共 11 类再把脱敏后的 stdout/stderr 嵌入STDOUT ... STDOUT标记并用OMX_SPARKSHELL_SUMMARY_MAX_LINES默认 400 行与OMX_SPARKSHELL_SUMMARY_MAX_BYTES默认 24000 字节对嵌入内容做头部尾部截断。若设置了OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE其内容会作为instructions字段随请求发送仓库默认指令见 templates/model-instructions/sparkshell-lightweight-AGENTS.md核心约束是廉价简洁地总结、不扩散成规划/编排行为、保留关键失败与警告、不主动给出修改建议。6.3 结果缓存与 --since-last仅 tmux 面板模式启用缓存直接命令/Shell 模式不做缓存。缓存目录按OMX_SPARKSHELL_CACHE_DIR→OMX_TEAM_STATE_ROOT/../cache/sparkshell→.omx/cache/sparkshell的顺序解析键为pane-pane-id非法字符用 FNV-1a 哈希为pane-hhex。缓存文件记录时间戳、内容哈希与行数统计CACHE_BODY_VERSIONomx-sparkshell-cache-v2相同哈希且未过期 →cache_hit摘要直接输出unchanged since previous observation行数增长 → 计算变化行区间changed_ranges新增行追加到末尾--since-last模式在 JSON 报告中仅输出new findings since last observation:之后的新增行供轮询式监控场景使用。七、--json 结构化报告evidence、诊断与 redaction 计数--json模式绕过 raw 输出直接生成一份单对象 JSON 报告write_json_report包含ok/modecommand|shell|tmux-pane/statusok|failed/exit_codesummary按 budget 截断的摘要含unchanged since previous observation或summary unavailable ...兜底文案errors/warnings来自诊断分类见下evidencestdout_lines、stderr_lines、raw_hashstdoutstderr 拼接文本的 64 位默认哈希、pane_id、tail_lines、line_rangenext_action/confidence/classification诊断分类结果cachecache_hit、previous_hash、current_hash、changed_line_rangesredactions.count脱敏替换发生次数。诊断分类classify基于输出文本关键词auth_errorauthorization/authentication/401、type_errorTypeError、test_failuretest failed/failures/failed、waiting_for_inputpress enter/waiting for input/continue?、busy_processingthinking/running/building。若同时指定--team与--worker还会读取OMX_TEAM_STATE_ROOT/team/team/workers/worker/下的heartbeat.json超过 120 秒未更新判为stale_heartbeat与status.jsonstate 值映射与 src/team/state.ts 的WorkerStatus.stateunion 对齐给出busy_processing/waiting_for_input/test_failure等团队级诊断与建议动作wait / inspect raw pane / run omx team status。八、安全设计输出脱敏与降级容错8.1 密钥脱敏redaction.rs无论 raw 还是 summary 路径输出在被展示或送入 prompt 之前都会经过 redaction.rs 的redact_output按三类规则逐行替换Authorization: Bearer value头大小写不敏感键值对秘密access_token、api_key、apikey、auth_token、password、secret、token后跟或:的值支持引号包裹、JSON 逗号/花括号边界截断已知秘密前缀标记sk-、ghp_、xoxb-。所有命中统一替换为[REDACTED]并计数计数会写入 JSON 报告的redactions.count。测试覆盖了 stdout/stderr 双流、JSON 冒号形态与重复秘密形态见 redaction.rs 的tests模块。8.2 三层降级TypeScript 调度层当原生二进制不可用时sparkshellCommand依据是否显式设置OMX_SPARKSHELL_BIN决定行为未显式覆盖时进入runSparkShellFallback降级——打印诊断cause/path/state/remediation后用解析出的 fallback argvPOSIX 为sh -lcWindows 按 pwsh → powershell → cmd 顺序以原始命令模式直接执行不提供摘要显式覆盖但启动失败missing/blocked由classifySpawnError判定直接抛出错误不静默降级GLIBC 不兼容若 stderr 命中GLIBC... not found类模式isSparkShellNativeCompatibilityFailure同样走降级路径并在诊断中标注glibc-incompatible。降级诊断信息会做单行化、ASCII 过滤与 500 字符截断sanitizeFallbackDiagnostic避免污染终端。九、团队检查集成omx team status的 pane 元数据与可直接执行的 sparkshell 命令PR 的另一半内容是omx team status的检查能力增强使其输出可直接对接 sparkshell。src/team/pane-status.ts 中为文本与 JSON 输出新增leader_pane_id/hud_pane_id/worker_panes各角色的 pane idsparkshell_hint与sparkshell_commands为 leader/HUD/每个 worker pane 预生成的omx sparkshell --tmux-pane pane-id --tail-lines N命令如omx sparkshell --tmux-pane %11 --tail-lines 200可直接复制执行recommended_inspect_targets/recommended_inspect_reasons/recommended_inspect_clis推荐检查目标、理由与 worker CLIrecommended_inspect_items结构化 JSON 载荷逐项给出target、pane_id、worker_cli以及 worker 的 CLI、角色、liveness、索引、turn/activity 上下文、task id/subject/description/status/lifecycle、approvals/claims/dependencies、worktree/runtime 路径与团队/worker 状态产物路径。配合 sparkshell 的--team/--worker分类与--tmux-pane面板捕获dead/non-reporting worker 定位闭环变为omx team status输出推荐检查项 → 复制其中的 sparkshell 命令 → 拿到面板摘要与诊断分类 → 决定 wait / inspect / shutdown。PR 记录中特别指出rebase 后 MCP 团队任务清理被加固为从当前 home 目录动态解析 jobs 目录且测试已针对新暴露的 claim-lock 检查元数据做了更新。十、验证与质量保障确定性测试CLI 层覆盖二进制解析优先级、musl/glibc 候选顺序、fallback 与打包行为见 src/cli/tests/sparkshell-cli.test.ts 与 src/cli/tests/sparkshell-packaging.test.tsRust 层覆盖参数解析边界tail-lines 100/1000、缺值、前缀值、模式互斥、shell argv 平台选择、模型/超时环境变量解析、摘要白名单规范化、脱敏与 loopback 校验见 crates/omx-sparkshell 各模块的tests模块。重负载/手动场景docs/qa/explore-sparkshell-heavy-manual-stress.md 记录了四个被排除在默认 CI 之外的手动场景——大型噪音 tmux-pane 捕获、重复/并发调用压力、伪随机摘要语料、操作者逐步走查并为每个场景定义了 must-preserve facts、证据采集模板与失败信号例如摘要保留措辞但丢失决定性事实即判失败。基线命令node bin/omx.js sparkshell git --version、omx sparkshell --help、omx sparkshell --tmux-pane pane-id --tail-lines 400等均为该文档中已验证或建议的命令形态。十一、环境变量速查表变量作用默认值OMX_SPARKSHELL_BIN覆盖原生二进制路径绝对或相对 cwd自动发现OMX_SPARKSHELL_MODEL摘要模型gpt-5.6-lunaOMX_SPARKSHELL_FALLBACK_MODEL重试模型gpt-5.6-terraOMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE覆盖打包的总结指令文件内置 lightweight AGENTSOMX_SPARKSHELL_SUMMARY_TIMEOUT_MS本地 API 总结超时60000OMX_SPARKSHELL_LINESraw-vs-summary 行数阈值12OMX_SPARKSHELL_SUMMARY_MAX_LINES/_MAX_BYTESprompt 嵌入截断400/24000OMX_SPARKSHELL_CACHE_DIR面板缓存目录.omx/cache/sparkshellOMX_API_BASE_URL/OMX_API_PORT本地 API 端点http://127.0.0.1:14510OMX_API_LOCAL_BEARER/OMX_API_STATE_FILEAPI 认证daemon 状态文件OMX_API_ALLOW_UNSAFE_BASE_URL允许非 loopback API 地址仅开发用未设置OMX_TEAM_STATE_ROOT团队/worker 状态与缓存根.omx/state十二、小结omx sparkshell用最小的架构复杂度一个 Rust 二进制 一层 TS 调度解决了 OmX 团队工作流中最实际的痛点超长命令输出的低成本总结、tmux 面板的可编程检查、以及团队状态检查结果到下一步动作的无缝衔接。其 raw-vs-summary 阈值切换、--json结构化报告、缓存去重与多层降级设计使它既适合交互式排查也适合被脚本和omx team status等上游命令自动驱动。若要在真实环境中启用它请从npm run build:full构建开始用node bin/omx.js sparkshell git --version验证基线再逐步尝试--json、--since-last与--tmux-pane模式并参考 experimental-dev-omx-sparkshell.md 中的验证清单完成回归。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OmX sparkshell 实战指南：用 Rust 原生侧车驯服命令输出噪音与 tmux 面板检查
OmX sparkshell 实战指南用 Rust 原生侧车驯服命令输出噪音与 tmux 面板检查【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codexomx sparkshell是 OmXOh My codeX提供的一个原生 Rust 命令执行与智能总结侧车它以独立二进制的方式执行任意命令、显式 shell 脚本或 tmux 面板内容在输出超过阈值时调用本地模型 API 生成摘要并内置密钥脱敏、结果缓存与 JSON 报告能力。本文将以 experimental-dev-omx-sparkshell.md 的 PR 变基记录为骨架结合 src/cli/sparkshell.ts 与 crates/omx-sparkshell 的源码实现完整讲解它的三种执行模式、原始输出与摘要的切换逻辑、环境变量配置、团队检查集成以及降级容错机制。读完本文你将能够独立构建、调用并扩展omx sparkshell并在omx team status的检查元数据中直接使用它完成 leader 排查。一、为什么需要 sparkshell从海量输出到可执行结论在团队模式team mode与 tmux 多面板工作流中leader 与 HUD 面板会持续产生大量命令输出构建日志、测试失败堆栈、git 历史、心跳文件……这些输出往往动辄数百上千行其中真正决定下一步动作的信息失败命令名、非零退出码、可执行的恢复提示、关键文件路径却被噪音淹没。omx sparkshell的设计目标正是解决这个问题命令执行本身交给原生 Rust 侧车完成超长输出交给本地模型 API 总结总结与原始行为之间以明确的阈值自动切换从而让看一眼输出就能决定下一步成为可能。该特性以 PR 形式合并到experimental/dev分支其变基记录即本文所依托的 experimental-dev-omx-sparkshell.md。从当前仓库结构看经过后续调整Rust crate 位于crates/omx-sparkshell而非 PR 记录中的native/omx-sparkshell且已被排除出根 Cargo workspace以保证仓库根目录的 manifest-path cargo 命令正常工作。二、总体架构CLI 调度、原生二进制发现与执行2.1 调用链omx sparkshell的完整调用链分两层TypeScript 调度层src/cli/sparkshell.ts 中的sparkshellCommand(args)负责解析--help、定位原生二进制、处理降级路径最终通过runSparkShellBinary同步派生子进程执行。Rust 执行层crates/omx-sparkshell/src/main.rs 中的run(args)负责解析参数、执行命令、脱敏、缓存与总结最后以命令的退出码退出。2.2 二进制发现顺序源码级resolveSparkShellBinaryPathWithHydrationsrc/cli/sparkshell.ts按如下优先级定位原生二进制环境变量OMX_SPARKSHELL_BIN显式指定的绝对/相对路径包内缓存目录中状态为verified的托管原生二进制resolveCachedNativeBinaryCandidatePaths打包路径bin/native/platform-arch[/libc]/omx-sparkshellLinux 上按musl优先、glibc次之的顺序探测见packagedSparkShellBinaryCandidatePaths仓库本地构建产物target/release/omx-sparkshell与嵌套的crates/omx-sparkshell/target/release/omx-sparkshell以上均失败时尝试从 release 资产水化hydrate下载仍未找到时抛出错误提示设置OMX_SPARKSHELL_BIN或联网获取 release 资产。Windows 上的二进制名为omx-sparkshell.exe其余平台为omx-sparkshellsparkshellBinaryName。三、三种执行模式与核心参数omx sparkshell支持三种互斥的执行目标均需显式 opt-in模式语法说明直接命令Direct argvomx sparkshell command [args...]直接以 argv 执行不经过 shell不做元字符解析显式 Shellomx sparkshell --shell shell command通过 shell 执行脚本元字符仅在显式 opt-in 时生效tmux 面板omx sparkshell --tmux-pane pane-id [--tail-lines 100-1000]捕获更大范围的面板尾部并应用相同的 raw-vs-summary 逻辑直接命令模式在 POSIX 上以bash -lc展开见 exec.rs 的resolve_shell_argv_for_platformWindows 上则按pwsh→powershell.exe→cmd.exe /d /s /c的优先级选择。--tail-lines默认 200 行取值范围 100~1000越界、非数字或未与--tmux-pane搭配使用时均会报错parse_tail_lines与parse_input中的校验均有对应测试覆盖见 main.rs 的tests模块。其余全局参数Rust 侧parse_input解析--json输出结构化 JSON 报告详见第七节--budget chars/--budgetchars摘要字符预算默认 1000超长文本在安全字符边界截断并标注[truncated: N chars omitted]--since-last与缓存配合仅报告自上次观察以来的新增行见第六节--cacheon|off、--cache-ttl-ms ms控制结果缓存默认开启、TTL 为 10 分钟--team name、--worker name结合OMX_TEAM_STATE_ROOT下的团队状态做诊断分类详见第八节。四、构建与打包从源码到可执行二进制omx-sparkshell是一个独立的 Rust 二进制 crateCargo.toml依赖同仓库的omx-muxcrate用于复用build_capture_pane_args生成 tmux 捕获参数。构建与验证入口位于 src/scripts/build-sparkshell.ts 与 src/scripts/test-sparkshell.ts对应 PR 记录中的scripts/build-sparkshell.mjs/scripts/test-sparkshell.mjs仓库内为 TypeScript 源文件。PR 记录的本地验证命令链experimental-dev-omx-sparkshell.md完整复现如下npm run lint npm run check:no-unused npm run build:full cargo test --manifest-path crates/omx-sparkshell/Cargo.toml node scripts/build-sparkshell.mjs node scripts/test-sparkshell.mjs node bin/omx.js sparkshell cargo --version node bin/omx.js sparkshell npm --version node bin/omx.js sparkshell git log --oneline -3 npm test注意两点操作细节均为 PR 记录中的实际约束npm test会在打包清理时移除暂存的打包二进制需在验证后重新恢复被跟踪的二进制Rust 构建产物crates/omx-sparkshell/target/应在验证后清理不进入版本库。omx sparkshell --helpTypeScript 层会输出 SPARKSHELL_USAGE 中的完整用法与环境变量说明Rust 二进制的--help则由 usage_text() 输出两者互为印证。五、raw-vs-summary输出阈值与总结切换逻辑这是 sparkshell 的核心行为。执行命令获得原始输出后main.rs 的run流程如下脱敏先对 stdout/stderr 做密钥脱敏见第八节摘要路径使用脱敏后的输出阈值判断用combined_visible_lines统计 stdout 与 stderr 的总行数与阈值比较。阈值默认 12 行可由环境变量OMX_SPARKSHELL_LINES覆盖仅接受正整数非法值回退默认见 threshold.rs分支处理行数 ≤ 阈值直接原样输出write_raw_output不做总结以原始退出码退出行数 阈值非 JSON 模式调用summarize_output生成摘要并以--budget截断输出若总结失败如本地 API 不可用回退为原始输出并打印summary unavailable ...; showing raw output instead。非 JSON 模式下无论是否总结进程最终都以被执命令的退出码退出process::exit(output.exit_code())保证脚本化的退出码语义不被破坏。六、本地模型 API 桥接与结果缓存6.1 总结请求codex_bridgecodex_bridge.rs 实现了对本地 API 的 HTTP 调用POST base/v1/responses请求体含model、input、reasoning: {effort: low}、stream: false。其模型与端点解析顺序如下API 地址OMX_API_BASE_URL→OMX_API_PORT拼成http://127.0.0.1:port→ 默认http://127.0.0.1:14510摘要模型OMX_SPARKSHELL_MODEL→OMX_DEFAULT_SPARK_MODEL→OMX_SPARK_MODEL→ 默认gpt-5.6-luna回退模型OMX_SPARKSHELL_FALLBACK_MODEL→OMX_DEFAULT_STANDARD_MODEL→ 默认gpt-5.6-terra超时OMX_SPARKSHELL_SUMMARY_TIMEOUT_MS默认 60 秒。当主模型请求失败且错误信息命中quota、rate limit、429、unavailable、model not found、capacity等关键词时自动用回退模型重试should_retry_with_fallback。响应解析支持output_text顶层字段与responses风格的嵌套output结构extract_output_text/extract_response_output_text并兼容多种 JSON 字符串形态。安全方面API 地址默认仅允许 loopback 主机localhost或127.0.0.0/8回环地址非回环主机需显式设置OMX_API_ALLOW_UNSAFE_BASE_URL1才放行parse_http_url及其测试认证 token 通过OMX_API_LOCAL_BEARER或OMX_API_STATE_FILE指向的 daemon 状态文件解析。6.2 摘要规范化与指令约束模型输出经由normalize_summary白名单化仅保留summary:、failures:、warnings:三个顶级节其余节如next steps:会被丢弃并以固定格式渲染为 markdown 列表。构造 prompt 时prompt.rs 的build_summary_prompt会先识别命令族git、node-js、python、rust、go、ruby、java-kotlin、c-cpp、csharp、swift、generic-shell 共 11 类再把脱敏后的 stdout/stderr 嵌入STDOUT ... STDOUT标记并用OMX_SPARKSHELL_SUMMARY_MAX_LINES默认 400 行与OMX_SPARKSHELL_SUMMARY_MAX_BYTES默认 24000 字节对嵌入内容做头部尾部截断。若设置了OMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE其内容会作为instructions字段随请求发送仓库默认指令见 templates/model-instructions/sparkshell-lightweight-AGENTS.md核心约束是廉价简洁地总结、不扩散成规划/编排行为、保留关键失败与警告、不主动给出修改建议。6.3 结果缓存与 --since-last仅 tmux 面板模式启用缓存直接命令/Shell 模式不做缓存。缓存目录按OMX_SPARKSHELL_CACHE_DIR→OMX_TEAM_STATE_ROOT/../cache/sparkshell→.omx/cache/sparkshell的顺序解析键为pane-pane-id非法字符用 FNV-1a 哈希为pane-hhex。缓存文件记录时间戳、内容哈希与行数统计CACHE_BODY_VERSIONomx-sparkshell-cache-v2相同哈希且未过期 →cache_hit摘要直接输出unchanged since previous observation行数增长 → 计算变化行区间changed_ranges新增行追加到末尾--since-last模式在 JSON 报告中仅输出new findings since last observation:之后的新增行供轮询式监控场景使用。七、--json 结构化报告evidence、诊断与 redaction 计数--json模式绕过 raw 输出直接生成一份单对象 JSON 报告write_json_report包含ok/modecommand|shell|tmux-pane/statusok|failed/exit_codesummary按 budget 截断的摘要含unchanged since previous observation或summary unavailable ...兜底文案errors/warnings来自诊断分类见下evidencestdout_lines、stderr_lines、raw_hashstdoutstderr 拼接文本的 64 位默认哈希、pane_id、tail_lines、line_rangenext_action/confidence/classification诊断分类结果cachecache_hit、previous_hash、current_hash、changed_line_rangesredactions.count脱敏替换发生次数。诊断分类classify基于输出文本关键词auth_errorauthorization/authentication/401、type_errorTypeError、test_failuretest failed/failures/failed、waiting_for_inputpress enter/waiting for input/continue?、busy_processingthinking/running/building。若同时指定--team与--worker还会读取OMX_TEAM_STATE_ROOT/team/team/workers/worker/下的heartbeat.json超过 120 秒未更新判为stale_heartbeat与status.jsonstate 值映射与 src/team/state.ts 的WorkerStatus.stateunion 对齐给出busy_processing/waiting_for_input/test_failure等团队级诊断与建议动作wait / inspect raw pane / run omx team status。八、安全设计输出脱敏与降级容错8.1 密钥脱敏redaction.rs无论 raw 还是 summary 路径输出在被展示或送入 prompt 之前都会经过 redaction.rs 的redact_output按三类规则逐行替换Authorization: Bearer value头大小写不敏感键值对秘密access_token、api_key、apikey、auth_token、password、secret、token后跟或:的值支持引号包裹、JSON 逗号/花括号边界截断已知秘密前缀标记sk-、ghp_、xoxb-。所有命中统一替换为[REDACTED]并计数计数会写入 JSON 报告的redactions.count。测试覆盖了 stdout/stderr 双流、JSON 冒号形态与重复秘密形态见 redaction.rs 的tests模块。8.2 三层降级TypeScript 调度层当原生二进制不可用时sparkshellCommand依据是否显式设置OMX_SPARKSHELL_BIN决定行为未显式覆盖时进入runSparkShellFallback降级——打印诊断cause/path/state/remediation后用解析出的 fallback argvPOSIX 为sh -lcWindows 按 pwsh → powershell → cmd 顺序以原始命令模式直接执行不提供摘要显式覆盖但启动失败missing/blocked由classifySpawnError判定直接抛出错误不静默降级GLIBC 不兼容若 stderr 命中GLIBC... not found类模式isSparkShellNativeCompatibilityFailure同样走降级路径并在诊断中标注glibc-incompatible。降级诊断信息会做单行化、ASCII 过滤与 500 字符截断sanitizeFallbackDiagnostic避免污染终端。九、团队检查集成omx team status的 pane 元数据与可直接执行的 sparkshell 命令PR 的另一半内容是omx team status的检查能力增强使其输出可直接对接 sparkshell。src/team/pane-status.ts 中为文本与 JSON 输出新增leader_pane_id/hud_pane_id/worker_panes各角色的 pane idsparkshell_hint与sparkshell_commands为 leader/HUD/每个 worker pane 预生成的omx sparkshell --tmux-pane pane-id --tail-lines N命令如omx sparkshell --tmux-pane %11 --tail-lines 200可直接复制执行recommended_inspect_targets/recommended_inspect_reasons/recommended_inspect_clis推荐检查目标、理由与 worker CLIrecommended_inspect_items结构化 JSON 载荷逐项给出target、pane_id、worker_cli以及 worker 的 CLI、角色、liveness、索引、turn/activity 上下文、task id/subject/description/status/lifecycle、approvals/claims/dependencies、worktree/runtime 路径与团队/worker 状态产物路径。配合 sparkshell 的--team/--worker分类与--tmux-pane面板捕获dead/non-reporting worker 定位闭环变为omx team status输出推荐检查项 → 复制其中的 sparkshell 命令 → 拿到面板摘要与诊断分类 → 决定 wait / inspect / shutdown。PR 记录中特别指出rebase 后 MCP 团队任务清理被加固为从当前 home 目录动态解析 jobs 目录且测试已针对新暴露的 claim-lock 检查元数据做了更新。十、验证与质量保障确定性测试CLI 层覆盖二进制解析优先级、musl/glibc 候选顺序、fallback 与打包行为见 src/cli/tests/sparkshell-cli.test.ts 与 src/cli/tests/sparkshell-packaging.test.tsRust 层覆盖参数解析边界tail-lines 100/1000、缺值、前缀值、模式互斥、shell argv 平台选择、模型/超时环境变量解析、摘要白名单规范化、脱敏与 loopback 校验见 crates/omx-sparkshell 各模块的tests模块。重负载/手动场景docs/qa/explore-sparkshell-heavy-manual-stress.md 记录了四个被排除在默认 CI 之外的手动场景——大型噪音 tmux-pane 捕获、重复/并发调用压力、伪随机摘要语料、操作者逐步走查并为每个场景定义了 must-preserve facts、证据采集模板与失败信号例如摘要保留措辞但丢失决定性事实即判失败。基线命令node bin/omx.js sparkshell git --version、omx sparkshell --help、omx sparkshell --tmux-pane pane-id --tail-lines 400等均为该文档中已验证或建议的命令形态。十一、环境变量速查表变量作用默认值OMX_SPARKSHELL_BIN覆盖原生二进制路径绝对或相对 cwd自动发现OMX_SPARKSHELL_MODEL摘要模型gpt-5.6-lunaOMX_SPARKSHELL_FALLBACK_MODEL重试模型gpt-5.6-terraOMX_SPARKSHELL_MODEL_INSTRUCTIONS_FILE覆盖打包的总结指令文件内置 lightweight AGENTSOMX_SPARKSHELL_SUMMARY_TIMEOUT_MS本地 API 总结超时60000OMX_SPARKSHELL_LINESraw-vs-summary 行数阈值12OMX_SPARKSHELL_SUMMARY_MAX_LINES/_MAX_BYTESprompt 嵌入截断400/24000OMX_SPARKSHELL_CACHE_DIR面板缓存目录.omx/cache/sparkshellOMX_API_BASE_URL/OMX_API_PORT本地 API 端点http://127.0.0.1:14510OMX_API_LOCAL_BEARER/OMX_API_STATE_FILEAPI 认证daemon 状态文件OMX_API_ALLOW_UNSAFE_BASE_URL允许非 loopback API 地址仅开发用未设置OMX_TEAM_STATE_ROOT团队/worker 状态与缓存根.omx/state十二、小结omx sparkshell用最小的架构复杂度一个 Rust 二进制 一层 TS 调度解决了 OmX 团队工作流中最实际的痛点超长命令输出的低成本总结、tmux 面板的可编程检查、以及团队状态检查结果到下一步动作的无缝衔接。其 raw-vs-summary 阈值切换、--json结构化报告、缓存去重与多层降级设计使它既适合交互式排查也适合被脚本和omx team status等上游命令自动驱动。若要在真实环境中启用它请从npm run build:full构建开始用node bin/omx.js sparkshell git --version验证基线再逐步尝试--json、--since-last与--tmux-pane模式并参考 experimental-dev-omx-sparkshell.md 中的验证清单完成回归。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考