跳转至

HUD 状态与会话控制契约

本契约定义了 ECC 用于本地操作员界面、交接和未来 HUD 的可移植状态负载。它有意保持与 harness 无关：Claude Code statusline、Codex 窗格、dmux 会话、OpenCode 运行或仅终端工作流都可以发出部分数据，而无需更改字段名称。

规范示例位于 examples/hud-status-contract.json。

负载结构

每个状态负载都使用 schema_version: "ecc.hud-status.v1"，并保持以下顶层部分稳定：

字段 用途 主要来源
context 模型、harness、仓库、分支、worktree、会话 ID 以及上下文窗口压力 statusline stdin、git、会话适配器
toolCalls 近期工具计数、待处理调用、过期调用和最后一次工具事件 loop-status、tool-usage.jsonl、hook 桥接
activeAgents 当前 worker/subagent、运行时状态、分支、worktree、目标和交接路径 dmux/编排快照
todos 当前进行中的任务和待办计数 Claude todos、本地任务文件、计划元数据
checks 本地和远程验证状态，在可用时包含命令/检查 URL CI、本地命令、发布门禁
cost 会话支出、token 计数、预算和趋势 成本跟踪器、metrics 桥接
risk 关注状态、冲突压力、过期调用、脏 worktree 和人工审查标志 就绪门禁、git、队列状态
queueState GitHub PR/issue/discussion 计数、冲突队列、合并队列和过期回收队列 GitHub 同步、工作项
sessionControls 当前目标支持的操作员动作 ECC CLI、dmux、git/GitHub
sync Linear、GitHub 和交接发布状态 状态更新、工作项、交接写入器

当 harness 无法暴露信号时，字段可以为 null、空数组或 "unknown"。生产者不应发明不兼容的名称。消费者应将缺失部分渲染为不可用，而不是绿色。

会话控制

最小的会话控制词汇是：

控制 含义
create 启动新的隔离运行、worktree 或编排计划
resume 重新连接到现有会话或历史目标
status 发出当前负载而不改变状态
stop 请求优雅停止或将会话标记为已完成
diff 显示当前工作树或 worker 差异
pr 打开或检查关联的 pull request
mergeQueue 显示可合并、被阻塞和等待检查的项
conflictQueue 显示需要集成的脏/冲突 PR 或 worktree

sessionControls.supported 列出当前 harness 可用的控制。sessionControls.blocked 解释不可用的控制，例如缺少 GitHub token、没有 tmux 会话或只读适配器。

同步契约

同步部分区分持久化跟踪器：

  • Linear 记录项目状态更新 ID、健康状态，以及 issue 创建是否被工作区容量阻塞。
  • GitHub 记录当前仓库、PR/issue/discussion 队列计数，以及与会话关联的最新已合并或开放 PR。
  • handoff 记录持久化 Markdown 交接路径，以及它是否已在最新批次后写入。

这使实时进度跟踪变得明确，而不要求每次运行都创建 Linear issue 或 GitHub 评论。当 Linear issue 容量被阻塞时，状态负载仍可通过项目更新和仓库交接证明进度。

当前实现

  • ecc status --json 从 SQLite 状态存储中暴露就绪状态、活动会话、skill 运行、安装健康状态、治理和关联工作项。
  • ecc loop-status --json --write-dir <dir> 为长时间运行的循环写入实时转录快照和关注信号。
  • ecc session-inspect <target> --write <path> 从 dmux 和 Claude-history 适配器发出规范会话快照。
  • scripts/hooks/ecc-statusline.js 在 Claude Code 内渲染紧凑的模型、任务、成本、工具、文件、持续时间、目录和上下文压力信号。

ecc.hud-status.v1 负载是这些界面在 ECC 拥有专用全屏 HUD 之前可以投影到的公共外部契约。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC