Dol Whd

@pipeworx/dol-whd — 美国劳工部工资与工时执法

自 2005 财年以来已结案的美国劳工部 工资与工时司 合规行动——工资盗窃、欠薪、最低工资和加班认定、童工、H-1B 和 H-2A 违规。osha 已涵盖劳工部执法中的 OSHA 部分；这个同类项目此前无人能够查询。

这是 Pipeworx 的一部分——一个将 AI Agent 接入 1878+ 个实时数据源的 MCP 网关。这是一项独立、非官方的集成，与上游提供方无关，未获其认可，也非由其发布。

Bruce 提供密钥后，该项目于 2026-09-01 从 _incubator 晋升（舰队 #1052）。最初是在舰队 #651 下，基于 10 行目录预览构建的，因为在获得密钥之前，每个行数据请求都会返回 401。

工具

工具	可回答的问题
whd_search	“雇主 是否因工资违规被开具处罚？”——按雇主、NAICS、州和日期筛选
whd_employer	某一雇主的完整案件记录和汇总数据
whd_top_backwages	“行业 中欠薪金额最高的是谁？”
whd_coverage	数据集涵盖的内容、发布日期和认定日期范围

身份验证

平台密钥（PLATFORM_DOL_KEY，在网关和 registry-api 上设置），支持通过 _apiKey 使用自带密钥。可从 https://dataportal.dol.gov 免费获取密钥，该密钥适用于所有劳工部数据集，提交后即可使用——无需审批。_apiKey 不在任何工具的 required 列表中，因为网关会注入平台密钥。

这不是 data.gov 通用密钥（不适用 [[reference-datagov-key-universal]]）；劳工部开放数据门户会自行签发密钥。

目录是开放的，但行数据不是，这是个陷阱。 GET /v4/datasets 和 GET /v4/datasets/10362 无需密钥都会返回 200，因此数据源看起来是开放的，直到你请求数据——此时不带密钥的行数据请求会返回 401，错误信息为 "The API key is either incorrect or missing from your query."。

更糟的是，不同端点的身份验证方式不一样。 /v4/datasets* 接受 X-API-KEY: 请求标头；/v4/get/... 则会以 401 拒绝该标头，要求将密钥作为查询参数传入。由于目录请求成功而所有数据请求都返回 401，人们容易误以为密钥错误，而不是放置位置错误，因此应统一使用标头。此数据包始终使用查询参数。

上游按来源 IP 限流，而非按密钥限流。 几分钟内大约调用 20 次后，会返回 HTTP 429，并带有 x-amzn-errortype: ForbiddenException，但不提供 Retry-After；限流会持续约十分钟。实测发现：来自受限 IP 的伪造密钥也会收到 429，而完全省略密钥仍会收到 401，这足以确认限流是基于 IP 的。因此，这对我们来说是共享出口的风险，而非单个密钥的配额限制。此数据包会退避两次，然后返回 { found: false, reason: "upstream_rate_limited" }，而不是抛出错误，因此可以区分触发限流和雇主没有案件记录这两种情况。

数据源

• https://apiprod.dol.gov/v4/get/whd/enforcement/json — 案件行数据（需要密钥）
• https://apiprod.dol.gov/v4/datasets/10362 — 数据集元数据 + 10 行预览（开放）
• https://dataportal.dol.gov — 密钥注册和 API 查询构建器

查询语法（有文档记录，并非猜测）

data.dol.gov 是一个 React SPA，其资源包 /static/js/main.1788ccf8.js 中包含劳工部自己的 API 文档。参数包括：limit、offset、sort（asc/desc）、sort_by（字段名）、fields、filter_object、X-API-KEY——全部作为查询参数传入。文档中列出的运算符为：eq、neq、gt、lt、in、not_in、like。不假定该列表之外的任何运算符可用。

filter_object 是一个 JSON 字符串，其中包含基于 {field, operator, value} 的嵌套 and / or 分组，具体见劳工部给出的示例：

filter_object={"and":[{"or":[{"field":"industry","operator":"eq","value":"A"},
                             {"field":"industry","operator":"eq","value":"C"}]},
                      {"field":"year","operator":"eq","value":"2021"}]}

此工具包已处理的陷阱

• 零匹配查询会以 HTTP 204 和空响应体作答，而不是以 200 和 {"data":[]} 作答。204 的 res.ok 为 true，因此，如果不检查状态就进行解析，会因输入为空而抛出异常——把“这家雇主没有案件”这一最常见的否定结果变成看似是我们解析出错。
• filter_object 的关键字必须小写——field、operator、value、and、or。其他任何写法都会返回 500，并附带一条笼统的“检查是否有拼写错误”消息，但不会指出哪个字段有误。错误的数据集名称也会返回同样的 500，这就是为什么 whd/whisard（原始需求中的名称）看起来像是 DOL 服务中断，而不是拼写错误。正确的数据集是 whd/enforcement。
• 要让 like 执行子串匹配，必须使用 %。 DOL 将 like 记录为子串运算符，但未说明语法。2026-09-01 实测：%Walmart% 和裸写 Walmart 都会返回行，但通配符写法匹配范围更广——它还会匹配 "Subway Georgetown Walmart"，而裸写不会。裸写的 like 是锚定匹配。此处所有雇主搜索都使用 %term%。
• 商号 ≠ 法定名称。 “Reliant Energy”和“Reliant Energy Retail Services, LLC”是同一家雇主。两者都用 like 匹配，每条命中结果都会通过 matched_field 指明匹配到的是哪个名称。
• bw_atp_amt 是总额，FLSA 列是个陷阱。 法规层级的列（flsa_bw_atp_amt、sca_bw_atp_amt、cwhssa_bw_amt、dbra_…、mspa_…、h1b_…、fmla_… 等）互斥，且合计为 bw_atp_amt——已通过涉及两项法规的案件验证（Corrections Corp of America：7,118,609 SCA + 953,252 CWHSSA = 8,071,861；Hewlett-Packard：4,831,719 SCA + 401,211 FLSA = 5,232,930，两者均完全相符）。但 flsa_ot_…、flsa_mw_…、flsa_15a3_… 和 flsa_smw* 这一组是 flsa_bw_atp_amt 的明细，并非与其并列的列，因此把所有 *_bw_*_amt 列相加会造成重复计数。此工具包会分别返回 back_wages_agreed_usd（总额）、back_wages_by_statute 和 flsa_breakdown，并提供 back_wages_reconciles 标志，以便结构变更能在响应中显现，而不是悄悄抬高数字。
• 调查结果日期不是案件的立案或结案日期。 数据集明确说明了这一点，而且不包含后两者。应依据调查结果日期登记数据新鲜度。
• 但不要直接取最新的调查结果日期。 findings_end_date 为 NULL 的行会排在 sort=desc 的最前面，因此显而易见的查询会返回 null；而 DOL 自己的数据中也有输错的未来日期——最新的非空行标注为 3021-05-01。whd_coverage 会在窗口两端设置边界，并在 window_note 中说明这一点。
• www.dol.gov 的 HTML 页面会对通过 Akamai 访问的普通 UA 返回 403，需要完整的浏览器标头集（workers/data-pipeline/src/datasets/dod-contracts.ts 中的 BROWSER_HEADERS）。这是标头指纹拦截，不是 CF 出口拦截——不要为此构建代理。apiprod.dol.gov 是单独的主机，不存在此类限制。

推广时已解决的问题

• bw_atp_amt 是各法案列的总和，还是单独的类别？ 它是法规层级列的总额——已通过真实数据行确认，见上文的陷阱。这是此工具包在没有密钥时唯一尚未解决的问题。
• 能否从已部署的 Cloudflare Worker 访问？ 可以——2026-09-01 已通过网关进行实时验证。apiprod.dol.gov 不限制 CF 出口。（上文提到的 www.dol.gov Akamai 拦截针对的是另一台主机，仍会影响 HTML 抓取。）
• PLATFORM_DOL_KEY 已在 pipeworx-gateway 和 pipeworx-registry-api 上设为 wrangler 密钥。

其他 41 个 DOL 数据集

同一 v4 API 为九个机构的 42 个数据集提供服务（MSHA 15 个、OSHA 11 个、 ILAB 7 个、ETA 4 个，以及 EBSA、TRNG、VETS、WB 和 WHD 各 1 个）。完整列表、 调用形式以及上述所有陷阱均记录在 docs/dol-open-data-catalog.md 中。 仅供调查——其中没有任何内容已经构建完成，饱和后也不应基于这些内容进行推测性构建；保留它只是为了让需求信号有处可落。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "dol-whd": {
      "url": "https://gateway.pipeworx.io/dol-whd/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/dol-whd/mcp 上的 tools/list 会返回上表中的工具， 以及共享的 Pipeworx 元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 以及 网关范围内的其他工具。因此，你看到的工具数量会比表中的更多：单个工具包端点目前会在自身工具之外列出约 30 个共享工具。连接的 initialize 响应会说明其准确范围，并且是当天情况的权威依据。

这是有意为之，并非意外的多路复用。元工具可以让限定范围的连接通过 ask_pipeworx 跨整个目录路由，从而回答此工具包未涵盖的问题，而无需添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的架构信息占用的上下文超过了路由功能带来的价值，请连接一次完整网关，而不是连接多个工具包端点。

也可以连接完整的 Pipeworx 网关，直接列出每个工具包的工具， 而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1878+ 个数据源。唯一的区别是哪些工具包的工具会被直接列出；从任一端点都可以通过 ask_pipeworx 访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/whd_search \
  -H 'Content-Type: application/json' \
  -d '{"employer":"Walmart"}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/whd_search。查找工具：使用 {"query":"..."} 向 POST https://gateway.pipeworx.io/v1/tools/search_packs 发送请求。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关往返：

{
  "mcpServers": {
    "dol-whd": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-dol-whd"]
    }
  }
}

或者直接运行它，确认服务可以启动：

npx -y @pipeworx/mcp-dol-whd

它通过 stdin/stdout 使用 MCP 通信，并仅针对此工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接提供的任何共享元工具。相同的源代码、相同的工具，但没有 ask_pipeworx 路由功能。

使用 ask_pipeworx

你也可以用通俗英语提问，而不必直接调用工具——此功能既适用于上面的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Dol Whd data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT