ECC HUD 状态与会话控制契约面向多 Harness 的 ecc.hud-status.v1 便携状态协议解析【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC这篇技术指南围绕 ECCEverything Claude Code架构文档 hud-status-session-control.md 定义的「HUD 状态与会话控制契约」展开它是一套刻意与具体 Agent Harness 解耦的可移植状态载荷协议ecc.hud-status.v1供 Claude Code statusline、Codex 面板、dmux 会话、OpenCode 运行与纯终端工作流共用一个稳定字段命名空间。读完本文你将掌握协议顶层结构、会话控制词汇、同步契约的语义边界以及 ECC 仓库中ecc status、ecc loop-status、ecc session-inspect、ecc-statusline四条现状实现如何把各自信号「投影」进同一个外层契约为未来演进中的专属全屏 HUD 预留统一接口。为什么需要一份Harness 中立的状态契约在 ECC 的运行时环境中执行状态分散在多个互不相同的表面上Claude Code 的 statusline 通过 stdin 推送上下文与窗口压力Codex 依赖自身面板dmux 承载长时编排会话与 workerOpenCode 每次运行产生独立 transcript而纯终端工作流可能连图形界面都没有。若每个表面各自发明一套字段名状态数据将无法在表面之间搬运HUD 与交接handoff也无从谈起。该契约的核心立场是payload 以schema_version: ecc.hud-status.v1为版本标识顶层 section 集合保持稳定顶层字段名被当作稳定的公共 API任何 surface 都可以在不改字段名的情况下只发出部分数据partial data缺数据是合法的字段可以是null、空数组或unknown生产者不得臆造不兼容的新名字。由此契约的价值不在于全量强制而在于公共字段形状 宽容的缺失语义。文档给出的规范样例位于 examples/hud-status-contract.json它同时充当协议的手写示范与校验基准。顶层字段总览一个稳定的状态骨架每个ecc.hud-status.v1payload 都维持以下稳定的顶层分区任何实现都不得重命名或改变其语义字段用途主要数据源context模型、harness、仓库、分支、worktree、会话 id 与上下文窗口压力statusline stdin、git、会话适配器toolCalls近期工具调用计数、挂起调用、过期stale调用与最近一次工具事件loop-status、tool-usage.jsonl、hook bridgeactiveAgents当前 worker/子代理、运行时状态、分支、worktree、目标与交接路径dmux/编排快照activeAgents当前 worker/子代理运行时状态、分支、worktree、objective 与 handoff 路径dmux/orchestration 快照todos当前进行中任务与 todo 计数Claude todos、本地任务文件、计划元数据checks本地与远程校验状态能带命令或检查 URL 时附上CI、本地命令、发布门禁cost会话花费、token 数、预算与趋势成本追踪器、metrics bridgerisk注意力attention状态、冲突压力、stale 调用、脏 worktree 与人工复核标记readiness 门禁、git、队列状态queueStateGitHub PR/issue/discussion 计数、冲突队列、merge 队列与 stale-salvage 队列GitHub sync、work itemssessionControls当前目标支持的运营商动作operator actionsECC CLI、dmux、git/GitHubsyncLinear、GitHub 与 handoff 的发布状态状态更新、work items、handoff writer渲染铁律当某个 harness 无法提供某项信号时消费者应当把缺失的 section 渲染为不可用unavailable绝不能渲染成健康的绿色——这对正确判断运行体是否真正健康至关重要也是该契约与纯营销型状态页的本质区别。从规范样例理解各分区形态examples/hud-status-contract.json 展示了带具体值的完整 payload。例如context记录 harness、模型与仓库信息并给出contextWindow的remainingPct与pressurecontext: { harness: codex, model: gpt-5, repo: affaan-m/everything-claude-code, branch: main, worktree: /repo/everything-claude-code, sessionId: session-active, contextWindow: { remainingPct: 62, pressure: normal } }toolCalls区分三类计数器已发生的total、尚未返回的pending、以及超过时限的stalelastTool记录最近一次工具名、状态与完成时间——stale 计数正是 scripts/loop-status.js 中--bash-timeout-seconds默认 1800 秒判定挂起 Bash 调用是否过期的直接产物。activeAgents以数组描述每个 worker 的状态机todos用inProgress加counts结构呈现当前进行中任务与队列分布。risk是整个契约中最操作导向的分区它显式携带status、reasons、dirtyWorktree、conflicts与manualReviewRequiredrisk: { status: attention, reasons: [release tag not published], dirtyWorktree: false, conflicts: 0, manualReviewRequired: true }queueState则横向聚合了 GitHub 公网队列open PR/issue/discussion、mergeQueue、conflictQueue与staleSalvageQueue——其中 stale-salvage 队列直接呼应了 ECC 对陈旧工作回收stale PR salvage的长效追踪设计。会话控制词汇operator 的最小动作集契约规定了每个会话表面都应支持的最小会话控制词汇表动作名对消费者来说是可编程的稳定 API控制含义create启动一个新的隔离运行、worktree 或编排计划resume重新挂接到现有会话或历史目标status只输出当前 payload不修改任何状态stop请求优雅停止或将会话标记为已完成diff显示当前工作树或 worker 的 diffpr打开或检视关联的 pull requestmergeQueue展示可合并、被阻塞与等待检查项conflictQueue展示需要整合的脏/冲突 PR 或 worktree该词汇表通过sessionControls分区暴露能力边界sessionControls.supported列出当前 harness 实际可用的控制sessionControls.blocked解释哪些控制不可用及其原因例如缺少 GitHub token、不存在 tmux 会话、或底层适配器只读。在规范样例中supported恰好枚举了完整八项、blocked为空数组而在受限环境下某个控制不可用时不应静默消失而应出现在blocked并给出可诊断的理由字符串。status的语义被特别强调为无副作用——查询状态的动作绝不能反过来污染被观测的会话状态这是它能够被反复轮询的前提。同步契约把做过的事沉淀为可证证据sync分区刻意把三类持久化跟踪器分开避免所有运行都被迫写 Linear issue 或 GitHub 评论Linear记录项目状态更新 id、健康度如atRisk以及 issue 创建是否被工作区容量阻塞issueCapacityBlockedGitHub记录当前仓库、PR/issue/discussion 队列计数以及与会话绑定的最新合并/打开 PRhandoff记录持久化 Markdown 交接文件路径以及最近一批变更后是否已写入written。这一点与该仓库的另一份架构契约 progress-sync-contract.md 互为表里后者的「Real-time Boundary」明确规定本地实时路径默认以文件为后端node scripts/status.js --json与node scripts/work-items.js list --json负责向 HUD、handoff 或后续 Linear 同步暴露本地状态任何后来引入的托管遥测如 PostHog都必须消费同一事件模型不得变成第二套真相源。契约文档原文也强调当 Linear issue 容量被阻塞时payload 仍然可以通过 project update 与仓库内 handoff证明进度确实在发生——实时进度追踪因此不依赖任何单一外部系统。四条现状实现把分散信号投影进同一契约文档明确列出 ECC 仓库中当前的四条实现它们各自在不同粒度上产生或消费状态信号。结合源码我们可以看清每条命令真实做了什么。ecc status --json从 SQLite 状态存储做全量盘点scripts/status.js 的参数解析显示它支持--db path、--json|--markdown、--write path、--limit n与--exit-code。它查询 ECC SQLite 状态存储state store汇总活动会话、近期 skill 运行、安装健康度、待处理治理事件与关联 work item。命令行 help 明确写道Use --exit-code to return 2 when readiness needs attention即它能把就绪性需要关注翻译成进程退出码供脚本化门禁消费。输出的人类可读形态包含每个会话的id [harness/adapterId] state、仓库根、启动时间与 worker 数——这天然对应契约中的context与activeAgents分区而--write支持把同样的盘点落盘为可交接的持久产物。ecc loop-status --json --write-dir dir长时循环的注意力与实录快照scripts/loop-status.js 面向长时间运行的 agent 循环设计。其参数面非常细--json输出机器可读 JSON--transcript session.jsonl直接检视单个 transcript--bash-timeout-seconds默认 1800s决定挂起 Bash 调用何时被判为 stale--wake-grace-multiplier默认 2是 ScheduleWakeup 的宽限倍率--exit-code在检测到 attention 信号时退出码为 2--watch/--watch-interval-seconds支持周期性刷新。--write-dir dir会把index.json与每个会话的状态快照写入目标目录——这正是契约toolCalls工具计数与 stale 判定、riskattention 信号分区的现场数据来源。测试文件 tests/scripts/loop-status.test.js 覆盖了该扫描与快照逻辑印证了上述参数语义是可测试的稳定行为。ecc session-inspect target --write path从 dmux 与 Claude 历史产出规范快照scripts/session-inspect.js 提供的是会话体检式快照目标target可以是 dmux/编排 plan 文件、dmux 会话名、claude:latest、具体 Claude 会话 id、直接指向 session 文件甚至是skills:health、skills:amendify、skills:evaluate等技能改进体检目标。核心动作inspectSessionTarget来自scripts/lib/session-adapters/registry的适配器注册表--list-adapters可枚举--write output.json负责把结果原子落盘为规范会话快照——它的输出同样以ecc.hud-status.v1的外层形状为投影目标是dmux Claude-history 适配器这两类信号源进入统一契约的官方桥梁。scripts/hooks/ecc-statusline.jsClaude Code 内的紧凑单行渲染这是最贴近当下正在发生什么的表面。其注册方式不同于普通 hook它作为statusLine命令写入~/.claude/settings.json而非 hooks.json由 Claude Code 运行时每行状态推送 stdin 数据驱动。示例配置见 examples/statusline.json其中说明了安装方式、色彩阈值与依赖关系色彩阈值上下文用量 50% 绿、65% 黄、80% 橙、≥80% 红闪依赖读取由ecc-metrics-bridge.js的 PostToolUse hook 写入的桥接文件两方必须同时安装才能完整显示指标输出形态示例Opus 4.6 | Fixing auth bug | $1.23 47t 5f 15m | myproject ███████░░░ 68%。读 scripts/hooks/ecc-statusline.js 源码可看到它的完整逻辑链sanitizeSessionId先净化会话 id随后经readBridge读取指标桥文件、writeBridgeAtomic把剩余上下文百分比回写桥文件供 context-monitor 消费注意这里用到 scripts/lib/session-bridge.js 的原子写能力readCurrentTask在CLAUDE_CONFIG_DIR/todos下按{sessionId}-agent-*.json前缀匹配最新文件取in_progress状态 todo 的activeForm作为当前任务文本buildContextBar引入AUTO_COMPACT_BUFFER_PCT 16.5的自动压缩缓冲把 Claude Code 上报的剩余百分比折算为可用余量后再映射成十格彩色进度条避免窗口即将触发 auto-compact 时仍显示满格formatDuration把首个时间戳格式化为5s/12m/1h23m之类的紧凑时长单行输出最终由 model、当前任务、指标段、目录名与上下文条拼接而成通过\x1b[2m\u2502\x1b[0mdim 分隔符分隔。该脚本把契约中context模型、目录、窗口压力、todos当前任务、cost$1.23、toolCalls47t与文件变更数5f压缩进一行可扫读文本是先于全屏 HUD 存在的轻量可视化层。消费约定与未来方向契约文档在末尾给出了关键定位ecc.hud-status.v1是这些 surface在 ECC 演进出专属全屏 HUD 之前可以先投影进去的共同外层契约。换言之所有现状实现都有责任把各自的私有字段翻译成协议词汇HUD 消费者只需理解一张稳定的 schema而无需针对每种 harness 写分支判断。对开发者而言落地时可以遵循四条实用原则永远携带 schema_version让未来 v2 可以平滑演进而不破坏旧消费者只发你有的信号缺项用null/[]/unknown表达绝不发明同名异义的字段把不可用渲染成不可用宁可显式unknown也不向 operator 谎报健康动作语义保持一致status不产生副作用、stop优雅退出、create/resume只在支持的 harness 上暴露并通过sessionControls.blocked解释受限原因。这种一份 schema、多个 surface、宽容缺失、证据优先的设计使 ECC 的状态可观测性不必绑定任何单一 IDE、终端或托管面板——它既服务今天的 statusline 与 CLI 盘点也为明天真正属于自己的 HUD 预留了无需迁移的接口边界。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考