Context Budget Lab

Context Budget Lab is a small JavaScript tool for reviewing what an LLM agent should keep in its live context window. It scores context items by task relevance, priority, source trust, recency, and redundancy, then produces a keep/drop report under a token budget.

中文说明：这个项目用于检查智能体上下文包中哪些内容值得放进当前提示词窗口。它会根据任务相关性、优先级、来源可信度、时间新鲜度和重复程度打分，并在给定 token 预算下输出保留和丢弃建议。

What is implemented

• A shared scoring engine in src/contextBudget.js.
• A CLI that reads a JSON context pack and writes Markdown, JSON, or HTML reports.
• A browser demo served from index.html that uses the same scoring engine.
• A sample agent context pack in samples/agent-context-pack.json.
• Node tests covering token estimates, normalization, redundancy detection, budget packing, and ranking.

中文说明：当前实现包括一个可复用的评分模块、命令行报告工具、静态网页演示、示例上下文数据，以及覆盖核心行为的 Node 测试。

Architecture

The project keeps the core logic dependency-free so it can run in Node and in the browser:

• src/contextBudget.js normalizes input, estimates token cost, scores context items, detects redundant content, and selects items that fit the budget.
• src/renderers.js turns analysis results into Markdown or HTML for CLI output.
• src/cli.js handles file input, command-line flags, and report writing.
• app.js, index.html, and styles.css provide the static demo for GitHub Pages.

中文说明：核心逻辑不依赖第三方库，因此 Node 命令行和浏览器页面可以复用同一套算法。CLI 只负责读写文件和渲染报告，网页只负责展示和交互。

How to run

npm install
npm test
node src/cli.js samples/agent-context-pack.json --budget 620 --format markdown
node src/cli.js samples/agent-context-pack.json --budget 620 --format html --output output/report.html

For the browser demo:

npx serve . -l 4173

Then open http://localhost:4173/.

中文说明：先安装依赖并运行测试。命令行工具可以输出 Markdown、JSON 或 HTML。网页演示可以用任意静态服务器打开，例如 npx serve . -l 4173。

Verification / tests

npm test
npm run check

npm run check runs the test suite and writes a sample Markdown report to output/sample-report.md.

中文说明：npm test 验证核心算法行为，npm run check 会额外生成一份示例 Markdown 报告，方便检查 CLI 输出是否可用。

Known limitations

• Token estimation is approximate and does not use a model-specific tokenizer.
• The redundancy check uses term overlap, not embeddings.
• The scorer is deterministic and does not call an LLM judge.
• The browser demo uses a single editable JSON document instead of a full dataset manager.

中文说明：当前 token 估算不是模型专用 tokenizer；重复检测也不是向量相似度；评分过程不调用大模型；网页演示只处理一个 JSON 文档。

Roadmap

• Add optional model-specific tokenizer adapters.
• Export a compact context pack that can be pasted into agent prompts.
• Add a trace comparison mode for before/after context changes.
• Support embedding-based redundancy scoring when a user supplies vectors.

中文说明：后续可以增加模型专用 tokenizer、导出压缩后的上下文包、比较上下文调整前后的 trace，以及在用户提供向量时支持 embedding 重复检测。