Context Surface Analyzer

一个本地、确定性的工具，用于度量一个明确的 Agent 工具目录快照并比较两个快照。

它报告规范化 UTF-8 字节与 SHA-256 摘要、工具/schema 数量、完全重复的 schema、硬性名称冲突、声明的预算检查以及差异。可选的 token 计数继续由外部测量并完整标注；本产品不会从字节推断 token，也不会判断某个工具是否有用。

运行

需要 Node.js 22 或更高版本，且无第三方运行时依赖。

npm run check
node src/cli.js analyze examples/baseline.json
node src/cli.js diff examples/baseline.json examples/updated.json
npm start

Web 界面在 http://127.0.0.1:4173 打开。使用 --port 0 可选择临时端口。快照可以粘贴，也可以从有界本地 JSON 文件加载；浏览器不会在页面关闭后将其保留。

Related MCP server: repo-health

快照权威来源

从当前提供方、平台或授权的导出器处获取每个快照。本产品刻意不发现主机、不启动任意的 MCP 服务器、不遍历文件，也不将仓库中的测试夹具视为当前已安装的目录。分析前，将导出的目录投影到 context-surface.snapshot.v0.1 封闭格式，并保留导出器、提供方和修订版本作为记录来源。

MCP

启动 newline-delimited JSON-RPC stdio 服务器：

npm run mcp

它提供两个只读工具：

• context.analyze：一个快照到一份分析；

• context.diff：较早和较晚的快照到一份比较。

两者都将快照 JSON 作为有界字符串接受，因此该路由没有环境性文件系统权限。快照约定与详细语义见 产品模型。

这一可移植运行时明确通过修订版 2025-11-25 服务 MCP 2025 遗留时代。支持双时代的客户端可通过 server/discover 的 method-not-found 响应识别该边界，并回退到 initialize。此无依赖插件未声明支持现代独有的 2026 传输。

本地 Codex 插件

构建并验证仓库本地插件，将该仓库添加为本地 marketplace，然后安装插件：

npm run check
codex plugin marketplace add <repository-root>
codex plugin add context-surface-analyzer@context-surface-analyzer

安装后启动一个新的 Codex 任务，使 Skill 与 MCP 工具从同一缓存的插件版本加载。

状态

这是一个本地 MVP。开发检查、直接运行时探测、已安装 Codex 路由、生产负载行为、公开发布就绪性以及所有者的视觉验收，均属各自独立的验收事项。见 审查契约 与 首个真实目录试用记录。

License

Apache License 2.0。请参见 LICENSE 和 NOTICE。