context-budget

用途

Context Budget 用于回答“当前上下文用了多少、还剩多少”这类问题，并可选地对已安装组件做静态开销审计。它的设计原则是：实时上下文用量必须来自提供方的原生计量器，而不是通过扫描文件来推测。

主要能力

默认路径：实时上下文

当调用没有附带审计请求时，一律视为实时上下文请求，包括询问当前窗口、剩余容量、headroom、token 用量或上下文明细。此路径下：

不调用或使用任何工具；
不扫描或读取文件；
不运行 shell 命令、提供方 CLI、调试日志或 MCP 发现；
只回复原生命令和一句简短说明。

按当前 harness 路由：

Harness	原生命令	说明
Codex CLI	/status	显示当前 token 用量与剩余上下文容量。可使用 /statusline 并启用 Context stats 与 Token counters 获得常驻页脚计量器。
Codex app	/status	显示当前线程上下文用量与速率限制。
Claude Code	/context	显示实时上下文明细。使用 /context all 展开条目。
其他或未知	无已验证命令	说明 ECC 无法读取实时提供方状态，并询问当前使用哪个 harness。

技能无法代替用户调用 TUI 斜杠命令。不得用估算扫描替代原生命令，也不得从“上下文很重”“还剩多少”等措辞推断出审计请求。

显式静态审计

仅当用户明确说出 --audit、“audit installed components”或同等明确措辞时，才运行安装/配置审计。--verbose 只改变报告详细程度，本身不构成审计请求。

若审计范围不明确，先询问 harness 和安装根目录，再读取任何内容。审计保持有界且只读：

只检查指定的插件/安装根目录和指定 harness 的已知配置文件；
不递归枚举工作区根目录、主目录、提供方缓存、transcript、调试日志或无关 worktree；
不启动提供方 CLI、MCP 服务器或调试会话去统计工具数量；
每类组件清单输出上限 50 条，其余汇总；
不写临时日志，也不把配置内容复制进报告。

只审计与 eager discovery 相关的组件元数据：

agent 与 skill 描述；
harness 会 eager 发现的命令描述；
明确命名范围内始终加载的指令文件；
已有有界 manifest 暴露的已配置 MCP 工具 schema。

完整的 skill、agent、命令和规则正文通常属于按需内容。应将其磁盘大小与预估 eager 开销分开报告，而不是把每个正文都计入会话基线。

审计输出

返回紧凑报告，包含：

harness 与检查的确切路径；
按组件类别估算的 eager/discovery 开销；
已安装数量与最重的元数据条目；
假设、不可用测量值，以及最多三条优化建议。

每个计算出的 token 数字都是静态配置开销的估计，不是实时会话上下文。不得声称估算值来自提供方、是当前值、精确值或已实现节省的证据。应引导用户回到原生实时上下文命令查看当前用量。

可选：选定记录诊断

仅当用户明确为该诊断选定某个文件时，才检查持久化记录。这与默认实时上下文请求和安装审计相互独立。

对本地文件诊断，需明确选择一个稳定的常规 JSONL 文件或打算检查的快照。替换下方示例路径；这不会查找或重连会话。该片段只打印聚合字节数，逐行读取，内存占用取决于最大记录，应避免超大记录和正在增长的文件。

python3 - "/path/to/selected-session.jsonl" <<'EOF'
import json
import sys

total = attachment = other = unclassified = 0
try:
    with open(sys.argv[1], "rb") as source:
        for raw in source:
            size = len(raw)
            total += size
            try:
                record = json.loads(raw.decode("utf-8"))
            except (UnicodeDecodeError, json.JSONDecodeError):
                unclassified += size
                continue
            record_type = record.get("type") if isinstance(record, dict) else None
            if not isinstance(record_type, str):
                unclassified += size
            elif record_type == "attachment":
                attachment += size
            else:
                other += size
except OSError:
    print("Cannot read selected JSONL file.", file=sys.stderr)
    raise SystemExit(1)

pct = attachment * 100.0 / total if total else 0.0
print(f"persisted {total}B | attachment records {attachment}B ({pct:.1f}%) | "
      f"other records {other}B | unclassified {unclassified}B")
EOF

三类之和等于原文件字节数，包含行尾和空行。attachment 是精确的记录类型过滤，不保证对应 harness 当前内部 schema。其他记录具有不同的字符串类型；格式错误的 JSON、无效 UTF-8、非对象值、缺失或非字符串类型以及空行都归为 unclassified。两类都不代表“对话”，百分比只是持久化字节的占比。

这些计数不能确定活动上下文、剩余空间、token 用量、计费或重连会加载什么。要查看当前 harness 报告的上下文与用量，请使用与版本匹配的 /context 和 /usage 命令（/cost 是别名）。

使用方式

询问实时上下文时，直接提问即可，技能会返回对应 harness 的原生命令。
需要静态审计时，明确使用 --audit 或“audit installed components”等措辞，并说明 harness 与安装根目录。
需要记录诊断时，明确选定一个 JSONL 文件并运行上述片段。

适用场景

在 Codex 或 Claude Code 中快速查看当前上下文用量与剩余容量；
在明确要求下，评估已安装 agent、skill、命令、指令文件与 MCP schema 的静态发现开销；
在明确选定文件的前提下，统计持久化记录中附件与其他记录的字节占比。

限制

技能无法代替用户执行 TUI 斜杠命令；
无法读取未知 harness 的实时提供方状态；
所有 token 数字均为静态配置开销估计，不代表实时会话上下文、计费或已实现节省；
记录诊断的计数不能确定活动上下文、剩余空间或重连加载内容；
审计范围必须明确，否则需先询问 harness 与安装根目录。