jsonloupe

jsonloupe 是一款基于浏览器的工作台，可用于检查、比较差异、编辑和查询普通查看器难以处理的超大或超高精度 JSON 文档；还可将其转换为电子表格：输入嵌套 JSON，输出相互关联的表格，可保存为一个 .xlsx 文件或一组 CSV 文件的 zip 包。你对每个文件提出的问题可以保存为 playbook 中的检查项：按一次按钮，就能对打开的文档逐一检查；同一个文件还可通过 jsonloupe check 为 CI 设置门禁。所有内容都留在你的机器上：在浏览器中，文档由 web worker 解析并存储在 IndexedDB 中，绝不会上传到任何地方。无后端、无需账户、无遥测。

运行

使用托管应用 jsonloupe.dev，每次合并后都会从 main 重新构建；或者在自己的机器上运行最新的 npm 发布版本，完全离线：

npx jsonloupe

这会启动一个仅监听环回地址的静态服务器（127.0.0.1:5199，或下一个可用端口），并从软件包中提供预构建的应用——没有运行时依赖，不发起网络请求，整个服务器只有一个约 200 行（含注释）的文件，便于审查：bin/jsonloupe.mjs。--port <n> 和 --no-open 的作用与名称一致；--key-file <path> 会从指定文件向页面提供模型密钥，且仅通过环回地址传输。同一命令还包含转换器的子命令（inspect、draft、convert，见下文），以及 CI 门禁（check，见下文）；运行 npx jsonloupe --help 可查看全部命令。

为什么还要另一个 JSON 查看器？

• 无损数字。 大于 2^53 的 Int64 ID（snowflake、订单或实体 ID）和高精度小数，在粘贴 → 查看 → 编辑 → 复制 → 下载的过程中都能保留精确数字。绝不会被强制转换为浮点数。
• 专为超大型文档打造。 树视图经过虚拟化处理，展开操作按块进行（[0 … 9999] 范围行），因此打开包含 500 万个元素的数组也能瞬间完成。解析、差异比较、搜索和压缩都在 UI 线程之外运行。
• 压缩负载是一等公民。 粘贴或拖入原始 .zst、Base64-Zstd（标准或 URL 安全格式），或 PostgreSQL \x… bytea——系统会自动检测，在工作线程中解码，并作为带有转换轨迹的文档打开。编码器和传输大小检查器（根据可编辑预算精确计算 UTF-8 / Zstd / Base64 / 封装字节数）也能反向完成转换。
• 在你的设备上，将嵌套 JSON 转换为电子表格。 重复数组和对象映射会成为相互关联的独立表——orders 和 order_items 通过 order_id 关联，而不是生成 items/0/sku 这样的列。写入任何内容之前，你都能先查看真实数据行；映射会保存为一个小文件，下个月的文件也能用它生成相同的列，无需模型参与。
• 语义差异比较。 并排比较时，根据身份对数组元素进行对齐（按 id、复合键或自动检测进行匹配），因此数组顺序变化不会造成大量误报。可按键或路径前缀忽略嘈杂字段。
• 真正的查询语言。 支持含谓词和聚合管道的 JSONPath 子集（$.tasks[?(@.status == 'FAILED')] | group(@.failureReason)），在本地执行，并在输入时实时预览。数值字面量、谓词、求和、平均值、最小值和最大值都能精确保留 int64 和高精度小数。
• 可用于门禁的检查。 将你对每个文件提出的问题保存为检查项——包括查询和预期计数——按一次按钮即可全部检查，并指出每个失败项对应的首批路径。无法完成的计数会标记为无法确定，绝不会冒充为通过。同一个检查方案文件可通过 jsonloupe check 为 CI 设置门禁，也可通过 MCP 的 run_checks 为 Agent 设置门禁。

快速开始

git clone https://github.com/priyanshuN/jsonloupe && cd jsonloupe
npm ci
npm run dev        # http://localhost:5199

在首页粘贴 JSON——系统会立即解析，并将其保存到本地存储（最近项目侧边栏：重新打开、固定、删除）。格式错误的输入（尾随逗号、单引号、Python 字面量、截断的日志片段）会自动修复并标记，同时保留原始字节。

功能导览

• 树形 / 代码 / 分栏视图 — 虚拟化树形视图、可编辑的 CodeMirror 代码 视图（折叠、搜索、使用 ⌘S 应用），或并排显示两者并支持点击行号 同步。在树形视图中内联编辑；所有编辑均支持完整撤销 / 重做。小型 文档会展开显示以填满屏幕；深入滚动时，当前所在位置的父级键会固定在 树形视图顶部。
• 命令面板 — 在任意位置按 ⌘K / Ctrl K：输入视图、操作、主题或 最近打开的文档名称中的几个字母，然后按 Enter。
• 配色方案 — 深色模式提供 Tokyo Night、Catppuccin Mocha、Dracula、Gruvbox 和 GitHub Dark；浅色模式提供 Solarized Light、Catppuccin Latte、Rosé Pine Dawn 和 GitHub Light；此外还有 jsonloupe 自带的一对配色方案。在侧边栏选择器中将 鼠标悬停在某个方案上（或在 ⌘K 中使用方向键浏览），即可在整个应用中 预览。每种模式都有自己的配色方案，因此“跟随系统”会在日落时切换 两种方案。所有方案均符合 WCAG AA 对比度标准，并已在 CI 中检查。
• 搜索与筛选 — 按 / 搜索（字面匹配或 /regex/i）；筛选模式会 仅保留匹配分支，并在完成后恢复展开状态。
• 路径与标识 — 面包屑导航支持一键复制为 JSONPath、JSON Pointer 或 JS 访问器；“相同值”可跳转至所有包含该值的节点 （无需 schema 的关联 ID 追踪）。
• 值透镜 — 将 epoch 转换为本地日期和“3 天前”；为 ISO 时间戳显示相同的 相对时间；为颜色字符串显示颜色块；识别纬度 / 经度、uuid / url / base64； 并显示已折叠容器的字节权重，方便一眼找到占用空间较大的节点。
• 表格与 CSV — 任意数组都可使用可排序表格视图；将表格或查询结果导出为 保留精确数字的 CSV（RFC 4180）。
• 操作手册 — 将检查项和函数汇集在一张工作表中 — 检查项由查询和 预期计数构成（无结果、至多 3 组、介于 1 和 10 之间）；run all 会检查 打开的文档中的所有检查项，并指出每项失败对应的首批节点。函数使用 JavaScript 编写，用于回答查询语言不应处理的问题；它会在移除了网络访问的 沙箱中运行。勾选多个函数后，按一次按钮即可将它们作为单份报告一并 执行。相同的检查项也可通过 jsonloupe check 在 CI 中进行验证。 （下文。）
• JSON → Excel / CSV 转换器 — 重命名和调整列顺序、选择源字段、添加 常量、设置日期和坐标处理方式、从目标 CSV 表头获取列名，并保存或分享映射， 以供下一个文件使用。 （下文。）
• 文件句柄 — 拖入 .json / .jsonl / .zst 文件；重新加载会从磁盘重新 读取文件，并显示与当前查看版本相比的变化。
• 查询 — 在本地运行 JSON 查询、保存实用查询，或将查询结果转换为 可复用的检查项。可选的 英文 → 查询 模式会仅根据文档的结构 （字段名称 / 类型，绝不包含值）将问题转换为查询，然后暂停，以便你在本地运行 前检查生成的查询。使用自己的连接：通过 OpenRouter 授权，无需粘贴密钥；也可使用 高级手动密钥选项——粘贴密钥，或从本地文件加载（原始密钥或 .env 行，在页面中 读取，绝不上传）。在你明确建立连接前，此功能不会启用。 披露面板会准确记录发送的内容。请参阅 SECURITY.md。

浏览器查询示例

打开文档，按 query，保持选中 JSON query，然后粘贴查询。 查询会直接在此标签页中运行：无需 API 密钥，也不会向模型发送任何内容。

给定以下小型文档：

{"tasks":[
  {"id":9007199254740992,"status":"FAILED"},
  {"id":9007199254740993,"status":"READY"}
]}

• 筛选失败的行：

  $.tasks[?(@.status == 'FAILED')]
  

  结果：匹配 1 项，$.tasks[0]。

• 按状态统计行数：

  $.tasks[*] | group(@.status)
  

  结果：FAILED 1、READY 1。

• 比较超出 JavaScript 安全范围的整数，且不进行舍入：

  $.tasks[?(@.id > 9007199254740992)] | count
  

  结果：1 — 只有精确值为 9007199254740993 的 id 更大。

将嵌套 JSON 转换为关联表格

如果你只需要一个电子表格， jsonloupe.dev/json-to-excel.html 就是 专门完成这项工作的独立页面：粘贴、转换，搞定。

打开文档，按工具栏工具组中的表格图标 （convert；将鼠标悬停在每个图标上，就会显示其名称）。每个重复出现的数组都会成为自己的表格，并通过数据中已有的 id 关联回父表——例如：

{ "orders": [
    { "id": 7, "cust": "ACME",
      "items": [ { "sku": "A", "qty": 2 }, { "sku": "B", "qty": 1 } ] } ] }

最终会生成两个工作表，而不是一个满是 items/0/sku 列的行：

orders                    order_items
id  cust                  order_id  sku  qty
 7  ACME                         7  A      2
                                 7  B      1

jsonloupe 会帮你找到这些表格，但不会盲目猜测：映射和真实行的预览会一直显示在屏幕上，你可以在其中重命名列、选择要保留的字段，并指定日期和坐标的读取方式。你确认的内容会保存为一个小型映射文件——可以保存在此浏览器中、导出，或通过命令行使用：

jsonloupe inspect payload.json          # what tables are in here?
jsonloupe draft   payload.json -o payload.spec.json   # a first mapping, to read
jsonloupe convert payload.json --spec payload.spec.json -o payload.xlsx

同一映射通过浏览器、CLI 和 MCP 服务生成相同的列，全程不涉及模型——冻结映射的意义就在于此。写入单元格的内容与文档中的内容一致：日期会作为真正的日期写入，可用于排序和相减；数字和坐标会作为数字写入；看起来像数字的文本仍会保留为文本，因此 "1.10" 会保留末尾的零，int64 id 的每一位数字也会完整保留，不会被舍入。超出 Excel 限制的内容以及列无法读取的值都会被报告或拒绝，绝不会悄悄写错。

操作手册：将函数和检查项保存为文件

文档每天都在变化；你要问的那几个问题却不会。因此，工具栏中的 playbook（1.8 之前名为 functions 视图；按 ⌘K 仍可通过该名称找到）会在文档旁打开操作手册，以单个工作表的形式显示你的检查项——查询及其预期结果数量——以及你的函数，每种列表都按名称排序。run all（操作手册打开时按 ⌘⇧↵ / Ctrl ⇧↵；再按一次即可停止）会针对当前打开的内容执行所有检查项，并在原处为每一行标出判定结果，然后运行已勾选的函数。 第一个未通过的行会自动打开，显示它匹配到的首批节点；点击路径，旁边树形视图中的对应节点就会被选中，而工作表仍停留在原处。

检查项

在工作表中按 + check，或使用 save as check 将查询结果转换为检查项。检查项会统计匹配项数量：| group 统计分组数，| distinct 统计不同值的数量；当数量符合预期时即通过：

通过条件	expectation	Playbook 版本
未找到匹配项	{"type": "no-matches"}	3
找到至少一项匹配	{"type": "at-least-one"}	3
找到恰好 N 项	{"type": "exact-count", "count": N}	3
找到至多 N 项	{"type": "at-most", "count": N}	4
找到至少 N 项（N ≥ 1）	{"type": "at-least", "count": N}	4
找到 M 到 N 项（含两端）	{"type": "between", "min": M, "max": N}	4

计数必须是 JavaScript 安全范围内的整数；超出上限的一个数会被拒绝，不会进行四舍五入。以 | sum、| avg、| min 或 | max 结尾的查询返回的是一个值，而非计数，因此对此类查询执行检查时会显示无法运行，而不会判断一个本来就不该计数的数值。

每项检查的结果为 ✓ pass、✕ fail、? inconclusive 或 ✗ could not run。不确定是诚实的第三种判定：| group 和 | distinct 最多保留 100,000 个分组或值（基数上限）。超过上限后，计数只有下限：至少为 100,001。只有当下限本身足以证明符合预期时（至少一项，或已达到 至少 N 项），下限判定才会通过；当计数已超过上限时（无匹配项，或 至多 100,000 项），则判定失败；其他情况均为不确定——绝不会将尚未达标的结果报告为通过。缩小查询范围即可确定结果。

如果检查项的查询引用了当前打开文档中不存在的字段，该检查项所在行会显示这一情况，面板还会添加提示：“this reads status — this document has none of that, so a pass here may prove nothing”。如果字段已被重命名，无匹配项检查仍会在该文件上照常通过。

已保存的检查项会保留最近一次判定，以及最多五条匹配路径和每条路径的简短预览。检查项归属于它最近一次运行时所针对的文档：在其他文档上运行后，原有记录会被替换。重新打开它运行过的文档时，判定结果仍会保留；编辑文档后，结果会逐渐淡出，并标记为“document edited”，直到再次运行。此记录保存在此浏览器中：它不会写入导出的 playbook，移除文档时也会一并删除。

函数

函数会学习它读取的内容。首次运行时，它会通过录制代理读取文档，并记录实际访问过的路径。因此，在你点击运行之前，面板就能显示：

此函数读取 orders、orders[].deliveredInHours——此文档中没有这些内容

而不是让你看到空结果后以为“今天没有”。这始终只是提示，不会阻止运行：读取记录只知道本次运行走过的分支，因此运行按钮仍然可用。勾选多个函数后，run all 会一次性运行所有函数，并以函数名为键返回一个对象。函数区标题中的打开报告会显示今天的报告；报告可下载，也可像其他文档一样重新打开。只要文档保持打开，函数的结果就会保留。打开另一份文档或重新加载后，该行会显示尚未运行。此浏览器会记住勾选了哪些函数。

脚本在临时工作线程中运行。任何用户代码运行前，都会移除 fetch、XMLHttpRequest、WebSockets、IndexedDB、importScripts 和嵌套工作线程；脚本会在返回结果时终止，或在十秒后终止（勾选运行的批次共用这十秒，超时后会整体停止）——粘贴的脚本无法访问网络或你已打开的文档。JavaScript 数字模式会保留现有函数的行为，并在文档包含会被舍入的值时给出提示。exact text 模式则会将这些不安全的字面值作为原始数字字符串（"9007199254740993"）传给函数；3 和 1.5 等普通值仍然是数字，因此常规计数和算术运算仍可正常进行。此模式会与函数一起保存和导出，而不是作为浏览器偏好设置保留。

文件

操作手册将这些可复用的工作保存为文件——其中只有问题和预期结果，不包含数据：

{
  "playbookVersion": 4,
  "name": "carrier dumps",
  "functions": [
    {
      "name": "slow orders",
      "script": "data.orders.filter(o => o.deliveredInHours > 48)",
      "reads": ["orders", "orders[].deliveredInHours"],
      "numberMode": "exact-text"
    }
  ],
  "checks": [
    {
      "name": "no failed orders",
      "query": "$.orders[?(@.status == 'FAILED')]",
      "expectation": { "type": "no-matches" }
    },
    {
      "name": "a full day of orders",
      "query": "$.orders[*]",
      "expectation": { "type": "at-least", "count": 1000 }
    },
    {
      "name": "a handful of carriers",
      "query": "$.orders[*] | group(@.carrier)",
      "expectation": { "type": "between", "min": 1, "max": 5 }
    }
  ]
}

操作手册栏中的导出会生成文件，除非某项检查需要版本 4，否则会导出为版本 3：不含 at-most、at-least 或 between 检查的库会导出为版本 3，可由 jsonloupe 1.4 到 1.7 读取。导入或将文件拖到窗口中，会添加文件中的内容。导入会合并，绝不替换——如果已有同名内容，会保留你的版本，并将导入内容命名为 slow orders 2；因为重复项只需删除一次就能处理，而覆盖不可逆。未知字段会按名称拒绝，而非直接丢弃，因此来自较新版本 jsonloupe 的文件不会以子集形式导入，并让你误以为导入成功。库最多保存 100 个函数和 100 项检查：保存第 101 个时会拒绝并提示原因；超出容量的操作手册也会整体拒绝，而不是挤掉最旧的内容。版本 1、2 和 3 的操作手册仍可导入；版本 1 的函数会保留其原始的 JavaScript 数字模式。

在 CI 中：jsonloupe check

同样的检查也可用于控制流水线。jsonloupe check 使用浏览器自己的引擎，对一个或多个文件运行检查方案中的检查；任何检查失败时都会以非零状态退出：

npx -y jsonloupe@^1.8.0 check carrier-dumps.playbook.json out/orders.json

out/orders.json · 3 checks · 4 ms
  ✕ no failed orders — Fail — 2 matches; expected no matches
      first: $.orders[312]
             $.orders[877]
  ✓ a full day of orders — Pass — 1,204 matches; expected at least 1,000 matches
  ✓ a handful of carriers — Pass — 3 groups; expected between 1 and 5 groups
1 function not run — functions run only in the browser
✕ 1 failed · ✓ 2 passed

请保留 @^1.8.0。1.8 之前的 jsonloupe 没有 check 子命令：它会改为启动查看器的本地服务，而该服务不会退出，因此作业会一直挂起，直到运行器超时。从 1.8 开始，jsonloupe 遇到不认识的词时会以状态码 1 退出，而不是启动任何服务。

检查方案必须放在最前面，后面可以跟任意数量的文件：.json、.jsonl/.ndjson、原始 Zstd，或 Base64-Zstd / bytea 负载，检测方式与浏览器中的相同。无效 JSON 文件会导致检查失败，不会在你不知情的情况下被修复；--allow-repair 则会检查修复后的文档。读取任何文件前都会先检查所有查询，因此最后一项检查中的拼写错误不会造成解析开销。函数使用 JavaScript 编写，绝不会在浏览器沙箱之外运行，因此 check 会统计函数数量，并说明未运行这些函数。文本报告会输出匹配的路径，而不会输出值，因为 CI 日志通常是公开的。路径仍会显示所经过的键，因此，如果文档使用电子邮件地址或账号 ID 作为键，请传入 --no-evidence。--format json 会写出一个对象，其中包含每个匹配节点的简短预览，供程序读取；--max-evidence N（0–100，默认值为 3）或 --no-evidence 用于设置检查未通过时列出的路径数量。

退出状态	含义
0	所有文件上的所有检查均已通过
1	用法错误、无法读取文件或检查方案，或文件不是有效 JSON——包括需要修复的文件
2	检查方案不是有效 JSON 或不是检查方案、没有检查项或超过 100 项（这是库的上限），或者某项查询无法被任何检查统计；未执行任何检查
3	至少有一项检查失败
4	没有检查失败，但有检查结果不确定或无法运行

有多个文件时，会优先返回最便于采取行动的状态：3，然后是 1，最后是 4。不确定结果有单独的状态码，因此流水线可以有意选择容忍它（… || test $? -eq 4）。

在 GitHub Actions 中，--format github 会在文本报告后添加注释：检查未通过时，会在检查方案上添加注释——结果不确定时为警告，否则为错误；对于无法检查的每个文件，或无效的检查方案，也会添加错误注释：

jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      # … the steps that write out/orders.json
      - run: npx -y jsonloupe@^1.8.0 check carrier-dumps.playbook.json out/orders.json --format github

Agent 可通过 MCP 服务的 run_checks（下文）获得相同的门禁检查，并传入检查方案路径或内联检查项。对于无效 JSON 文档，它会以相同方式拒绝处理；allowRepair: true 会检查修复后的文档，并说明已进行修复。

与 AI Agent 搭配使用

同一引擎也以 MCP 服务的形式运行，因此 Agent 可以处理超出其上下文容量的文档：

claude mcp add jsonloupe -- npx -y -p jsonloupe jsonloupe-mcp

如果你有 jq 和纯 JSON，请使用 jq。 本工具适用于 jq 难以处理的情况： 必须先解码的压缩载荷（.zst、Base64-Zstd、PostgreSQL \x… bytea）、 必须在整个流水线中精确保留的 int64 和十进制数字、两个文档之间基于标识键的语义差异，以及没有 shell 可运行 jq 的 MCP 宿主。

共 12 个工具（自 1.8 起包含 run_checks）：load_doc、get_schema、run_query、 profile、sample、diff_docs、export_csv、export_result，以及用于上述 电子表格流程的 inspect、draft_spec 和 convert，还有 run_checks，它会根据 playbook 的检查项对文档进行 门控，但不会运行其中的函数。对于单个问题，直接将 filePath 传给 get_schema、run_query、profile、sample、export_csv、export_result 或 run_checks；它会打开文档，并在同一次调用中返回可复用的 docId。如果要连续 提出多个问题，或使用需要 docId 的 diff_docs 和转换器工具，请先调用一次 load_doc，然后复用该 docId。最多可同时打开 8 个文档；超过后会关闭最近 最少使用的文档，并在下一条响应中说明。查询详情默认返回 10 行（仅需摘要时使用 limit=0，或通过 offset + limit 分页），文本和结构化 MCP 结果都有大小限制。 以下是处理一个 37 MB 路由载荷的典型运行示例：

run_query filePath=payload.json "$.tasks[?(@.status == 'FAILED')] | count"
                                  → docId: d1 · count: 17500
profile d1 "$.tasks[*]"          → auto-discovered field coverage, null/missing/types,
                                    exact sums/stats, lengths, distincts and top values
run_query d1 "$.tasks[?(@.status == 'FAILED')] | group(@.region, @.failureReason)"
                                  → composite breakdown, exact complete counts
run_query d1 "$.tasks[*] | top(@.delayMinutes, @.id, @.status)" limit=5
                                  → only the five highest rows; the full array never enters context
sample d1 "$.tasks[0]"           → the whole element, id 9007199254740993 intact
export_result d1 "…| pluck(@.id, @.failureReason)" format=csv outPath=failed.csv
                                  → complete, atomic, rows + UTF-8 bytes only
inspect d1                       → candidate tables, fields, types, deterministic suggestions
draft_spec d1 outPath=tasks.spec.json
                                  → reviewable mapping on disk
convert d1 specPath=tasks.spec.json outPath=tasks.xlsx
                                  → workbook path + row/skipped/warning counts, never its rows
run_checks d1 playbookPath=tasks.playbook.json
                                  → pass, fail or inconclusive per check (or could not run);
                                    a failed or inconclusive check names its first paths
                                    ($.tasks[3]); functions counted, never run

常用的 schema → profile → query 循环刻意设计得比加载 JSON 或编写一次性 Python 脚本成本更低：计数和聚合会对每个匹配项进行流式处理，而不将结果列表 载入内存；present、missing 和 isNull 能区分 false、null 和缺失；复合分组 以及有界的 top/bottom 可替代本地排序脚本；配置文件可在一次扫描中检查多个 字段或自动发现的字段。完整的 CSV/JSONL 导出会流式写入临时文件并以原子方式 发布。除非 Agent 明确传入 overwrite=true，否则不会覆盖现有路径。

该服务不会进行网络调用，只会访问明确提供的输入/输出路径。查询错误时会返回 语法说明和建议，而不是空结果。可复现的 Agent 选择评测会衡量：当 Python 也可用时，Agent 是否 会选择这些操作。

如果 Agent 知道已安装 MCP，却仍然编写一次性脚本，请将此路由规则写入其项目 说明（例如 AGENTS.md 或 CLAUDE.md）：

对于小型纯 JSON，如果 jq 已经是最简便且安全的选项，请使用 jq。 否则，只要 JsonLoupe MCP 支持相应操作，就优先使用它，而不是临时编写 Python；只有 JsonLoupe 无法满足需求时，才使用自定义 shell 代码。

在浏览器中：WebMCP

在浏览器支持 WebMCP 的环境中 （document.modelContext——Chrome 149 的 Chrome 源试用功能，以及 ChatGPT 桌面应用内置的浏览器），jsonloupe.dev 会注册同一组有界 操作，指向屏幕上当前显示的文档，因此浏览器 Agent 和旁观者共用一份文档，无需 来回发送副本。共 8 个工具：run_query、get_schema、profile 和 sample 的 工作方式与通过 stdio 使用时相同；另有 4 个工具作用于查看器本身，这是任何无头 服务都无法做到的：load_doc 会在查看器中打开文档，reveal_path 会滚动树形视图 到某一行并将其闪烁高亮，highlight_matches/clear_highlights 会控制工具栏自身 的筛选状态——筛选结果可见、可计数，且可由用户点击自己的按钮撤销。所有返回文档 内容的工具都标注了 untrustedContentHint：值是数据，绝不是指令。没有此 API 的 浏览器不会获取任何内容，运行的仍是原有应用。详情、测试说明和来源信息见 WEBMCP.md。

隐私与安全

文档不会离开你的设备。完整的网络调用清单（4 次 fetch 调用，全部用于可选的模型连接或英文查询翻译）、仅包含结构信息的 LLM 契约以及 XSS 防护策略均记录在 SECURITY.md 中。相应的 威胁模型、信任边界和保障论证见 SECURITY-ASSURANCE.md。

部署

jsonloupe 可构建为完全静态的网站：

npm run build      # dist/

从任意静态托管服务（GitHub Pages、Cloudflare Pages、Netlify……）提供 dist/。 应用运行不需要任何服务端支持。若要匹配 jsonloupe.dev 的 防护，请在托管服务上设置 SECURITY-HEADERS.md 中的响应标头——尤其是 /assets/run-sandbox-*.js 上运行沙箱自身的 CSP，否则粘贴的脚本中的 import() 可能访问任意主机。本地的 /__api-key 便捷端点（开发模式下，或通过 npx jsonloupe --key-file）在静态部署中 并不存在；只有访客连接自己的模型账户或密钥后，才会启用英文翻译。

开发

npm run dev        # Vite on :5199, with the loopback-only /__api-key endpoint
npm test           # vitest — engine, worker, converter, playbook, CLI, MCP, WebMCP, NL and DOM suites
npm run lint:security  # FLOSS security analysis + checked TypeScript style
npm run lint:contract  # the UI contract in src/style.css: tokens, contrast, motion, type ramp
npm run lint:headers   # every source file carries the MIT SPDX and copyright notice
npm run coverage   # same suite with enforced 90% statement / 80% branch floors
npm run build      # type checks + vite build + the MCP and CLI bundles
npm run build:mcp  # or build:cli — one target's type check and bundle only
npm run test:a11y  # real Chromium: axe, keyboard/focus, playbook and WebMCP journeys (run after build)
npm run check:site-headers # verify the live OpenSSF hardening headers
npm run check:reproducible-build  # clean locked installs must produce identical bytes
npm run smoke:mcp  # drives the built MCP server over real stdio against a 37 MB fixture (run after build)
npm run eval:agent -- --help  # black-box MCP-vs-Python agent-choice benchmark
npm run eval:ask -- --dry-run  # Ask correctness/injection suite; --dry-run costs nothing

请从 CONTRIBUTING.md 开始。架构和内部机制记录在 ARCHITECTURE.md 和 SPEC.md 中；转换器另有自己的 SPEC-converter.md，其中也说明了它会明确拒绝执行的操作。项目决策和未来 12 个月的规划见 GOVERNANCE.md 和 ROADMAP.md。官方发布流程 和使用方验证记录在 RELEASING.md 中。每个版本的 变更内容见 CHANGELOG.md。

许可证

MIT。捆绑的第三方软件包列在 THIRD_PARTY_LICENSES.md 中。

软件按“原样”提供，不附带任何形式的保证——详见许可证 文本。如果你连接模型以进行英文查询，则你对所配置 LLM 提供方的使用受该提供方条款约束。