什么是 上下文可视化 (context-viz)？

Context-Viz 是一款专门的技术工具，旨在提高 AI 代理如何利用其可用 Token 空间的透明度。通过分析当前的会话状态和工作区文件，它生成了系统提示、核心文件和消息历史记录中 Token 消耗的清晰格式化明细。这对于需要优化 Openclaw Skills 并防止意外上下文溢出或过度压缩的开发者来说尤其有价值。

除了主动上下文跟踪外，该技能还审计存储在磁盘上的代理长期内存。它对内存目录中当前未加载到上下文窗口的文件进行分类，允许用户在不影响当前模型会话的情况下查看代理知识库的完整范围。

下载入口:https://github.com/openclaw/skills/tree/main/skills/furukama/context-viz

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

上下文可视化 (context-viz) 应用场景

• 诊断代理在执行复杂任务时达到上下文限制的原因。
• 识别具体的核心文件（如 SOUL.md 或 AGENTS.md）占用的空间最多。
• 计算分配给消息历史记录与系统开销的上下文窗口确切百分比。
• 审计存储在磁盘上用于 Openclaw Skills 的存档内存的总大小和 Token 计数。

1. 该技能触发一个捆绑的 Python 脚本来扫描工作区，并使用标准的字符到 Token 比例估算文件的 Token 计数。
2. 它执行 session_status 命令以从核心环境获取实时元数据，包括模型限制和当前总使用量。
3. 该工具从总使用量中减去文件和系统开销，以隔离属于当前对话消息的 Token 计数。
4. 它计算每个组件的比例百分比，并生成等宽 ASCII 条形图以进行视觉反馈。
5. 最后，它扫描本地内存目录，以提供存在于磁盘上但当前不在活动上下文窗口中的文件的分类清单。

上下文可视化 (context-viz) 配置指南

要将此功能集成到您的 Openclaw Skills 工作流中，请确保工作区中包含估算脚本。您可以使用以下命令手动运行 Token 估算器：

python3 scripts/estimate_tokens.py /path/to/workspace

当代理被问及其实际上下文大小、使用明细或内存占用情况时，它将自动调用此逻辑。

上下文可视化 (context-viz) 数据架构与分类体系

该技能将其输出组织为两个主要部分：上下文使用情况和磁盘内存。数据结构如下：

name: context-viz
description: Visualize the current context window usage — token estimates per component (system prompt, tools, workspace files, messages, free space). Use when the user asks about context size, token usage, context breakdown, "how full is the context", or wants to see what's consuming their context window.

Context Visualization

Estimate and display a breakdown of the current context window usage.

How It Works

Run the bundled script to estimate token counts for workspace files:

python3 scripts/estimate_tokens.py /path/to/workspace

The script counts characters in known workspace files and estimates tokens (~4 chars/token).

Then call session_status to get the actual context usage from OpenClaw.

Generating the Visualization

1. Run session_status to get: model, context used/total, compactions
2. Run scripts/estimate_tokens.py to estimate file token sizes
3. Estimate message tokens: context_used - system_overhead - file_tokens
4. Present the breakdown using the format below

Output Format

Use a monospace block with bar chart. Adapt the bar lengths proportionally.

?? Context Usage
 ? k/k tokens (%)

Component                    Tokens    %     
─────────────────────────────────────────────
??  System prompt + tools    ~Xk      X%    ??
??  AGENTS.md                ~Xk      X%    ?
??  SOUL.md                  ~Xk      X%    
??  USER.md                  ~Xk      X%    
??  TOOLS.md                 ~Xk      X%    ?
??  HEARTBEAT.md             ~Xk      X%    
??  MEMORY.md                ~Xk      X%    ?
??  IDENTITY.md              ~Xk      X%    
??  Messages                 ~Xk      X%    ????????????
??  Free space               ~Xk      X%    ?????
─────────────────────────────────────────────

Use ? blocks: 1 block per ~2% of total context. Round to nearest block.

Memory Inventory (not in context)

Below the context chart, add a Memory on Disk section showing what's stored in memory/ — grouped by category. These files are NOT loaded into context but represent the agent's total knowledge base.

?? Memory on Disk (not in context)
Category                     Files  Tokens   Size
──────────────────────────────────────────────────
??  chinese-ai-digests        12    ~23k     92KB
??  other                     11    ~12k     46KB
??  daily-notes                9    ~5k      17KB
???  zettelkasten               8    ~4k      15KB
??  linkedin                   2    ~1k       5KB
──────────────────────────────────────────────────
     Total:                   42    ~44k    177KB

The script auto-categorizes files by directory or filename pattern.

Notes

• Token estimates use ~4 chars/token (rough average for English/mixed content)
• System prompt + tools overhead is estimated at ~8-10k tokens for a typical OpenClaw setup
• Message tokens are the remainder after subtracting files + system overhead
• Memory files are informational only — they show what the agent has accumulated
• For Discord/WhatsApp: skip markdown tables, use the block format above