dashcheck

dashcheck

在发布仪表板前进行检查。dashcheck 是 dashboardbase 验证服务的小型客户端：传入一个配置文件，它会报告所有架构、布局、绑定或内容错误；传入微件端点实际返回的 JSON，它会根据该微件类型对应的契约检查响应正文；配置准备好分享时，它还可以生成一个 48 小时后过期的只读链接。

配置内容可以作为字符串直接传入，也可以通过本地文件路径指定——使用路径时，文件会在你的机器上读取，并将其文本发送出去。服务返回的内容会原样返回：中途不会截断、重命名或概括。这也包括拒绝响应：如果配置文件包含凭据，服务本身会拒绝创建链接并列出有问题的字段，而该拒绝响应正文会像其他响应一样原样传回。

配置

三个环境变量用于控制客户端：

• DASHBOARDBASE_API_URL（可选）——API 基础 URL。 默认为 https://api.dashboardbase.com。
• DASHBOARDBASE_API_KEY（可选）——设置后，会在每个请求中通过 x-api-key 标头发送。留空不算错误：验证端点无需密钥即可使用。
• DASHBOARDBASE_TIMEOUT_MS（可选）——以毫秒为单位的请求超时时间，通过中止控制器强制执行。 默认为 15000；超时会被视为获取失败。

工具

• validate_setup_file —— 验证 dashboardbase 配置文件 （JSON），并返回所有架构、布局、绑定或内容错误。接受 content（配置文件内容）或 path（配置文件的本地路径）；必须提供其中一个。
• validate_widget_response —— 根据 dashboardbase 中对应类型（kpi、timeseries、bar、table 或 text）的微件契约，验证微件端点的 JSON 响应。接受 response（端点返回的 JSON 正文）或 path（包含该响应的 JSON 文件的本地路径）；必须提供其中一个。widgetType 为可选项，可覆盖响应封套中的类型字段。若响应值可解析为 JSON，则会以解析后的值发送；否则会以原始字符串发送。
• create_setup_link —— 为配置文件创建可分享的只读链接；链接会在 48 小时后过期。 接受 content 或 path，与上文相同。

在发出任何请求前，本地会执行二选一规则： one of content or path is required（对于微件响应工具，要求 one of response or path is required）。无法读取的本地文件会报错：cannot read file: <path>。上游返回非 2xx 响应时会报错：dashboardbase error: HTTP <status>；API 无法访问（包括超时）时会报错：dashboardbase unreachable。

端点来源说明

原始记录明确了这三个工具、各自的参数表、三个环境变量、48 小时链接行为以及凭据拒绝行为，但未公开上游 HTTP 路径。以下三个路径是推测还原，并已注明：

• POST <base>/validate/setup-file，JSON 正文为 {"content": "..."} —— 推测还原（由 validate_setup_file 使用）。
• POST <base>/validate/widget-response，JSON 正文为 {"response": ..., "widgetType": "..."}（未提供 widgetType 时会省略该键）——推测还原（由 validate_widget_response 使用）。
• POST <base>/setup-links，JSON 正文为 {"content": "..."} —— 推测还原（由 create_setup_link 使用）。

命令行工具

每个工具都是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/dashcheck validate_setup_file '{"path":"./setup.json"}'
npx @reneturcios/dashcheck validate_widget_response '{"response":"{\"type\":\"kpi\",\"value\":42}","widgetType":"kpi"}'
npx @reneturcios/dashcheck create_setup_link '{"content":"{\"widgets\":[]}"}'
npx @reneturcios/dashcheck --version

输出为工具的结果文本（成功时为上游响应正文）。退出码：成功时为 0，运行时错误（包括验证、文件读取或上游失败）时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/dashcheck mcp

MCP 客户端配置（密钥为可选项；如果有密钥，请通过客户端的环境变量提供）：

{
  "mcpServers": {
    "dashcheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/dashcheck", "mcp"],
      "env": {
        "DASHBOARDBASE_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/dashcheck
docker run --rm ghcr.io/cloudcorprecords/dashcheck validate_setup_file '{"path":"./setup.json"}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch and injected file reader only, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios