H1b

@pipeworx/h1b

来自美国劳工部（DOL）劳工条件申请（LCA）披露数据的 H-1B 签证担保与工资信息——“公司 X 是否担保 H-1B”“公司 X 的 Y 岗位薪资是多少”“奥斯汀哪些公司担保的数据工程师最多”。

属于 Pipeworx——一个将 AI Agent 连接到 1881+ 个实时数据源的 MCP 网关。这是一个独立、非官方的集成，与上游提供方无关联、未获其背书，也非由其发布。

工具

• h1b_employer_sponsorship(employer, year?) — 雇主的申请数量、薪资范围、热门职位和地点。
• h1b_salary(job_title, employer?, city?, year?, limit?) — 岗位实际披露的基本工资统计数据，以及一组记录样本。
• h1b_top_sponsors(job_title, city?, year?, limit?) — 按岗位申请数量排名的雇主，并附中位数薪资。

参数名称和形状与 fleet #2514 之前保持不变——只有答案的提供来源发生了变化。

双层数据源（fleet #2514）

主数据源：DOL 自己的 LCA 披露文件，适用于近期联邦财政年度。较早年份的数据来自 h1bdata.info。每个来自 DOL 的响应都带有 data_as_of。

备用数据源：h1bdata.info，同一 DOL 数据的第三方聚合器。仅当请求年份不在本地镜像已加载的时间范围内，或数据库无法访问时才会使用——在镜像仅完成部分回填期间，此工具包不得比 #2514 之前的行为退步。每个响应都带有 source 字段，说明实际提供答案的数据源；工具包绝不会在不说明的情况下悄然切换数据源。

**绝不会把备用数据源返回的零条结果当作确定的“没有”（fleet #3198）。**如果本次调用读取数据库失败（没有凭据、超时或暂时性错误——source_status: "primary_unreachable"），而 h1bdata.info 返回零条结果，则会返回 sponsors_h1b: null，并说明实际上从未查询过主数据源，而不是把结果当作否定证据。只有在主数据源正常响应，但该年份确实不在其已加载时间范围内（source_status: "out_of_window"）时，备用数据源的零条结果才代表真实的“没有”（但仍有第三方数据可能延迟或名称变更的问题）。dbRpc 会在任何回退之前，对暂时性故障立即重试一次，因此单次网络波动本身不会让本应由镜像覆盖的查询降级到较弱的数据源。h1b_employer_sponsorship 的 matched_employers 现在也会优先排列完全匹配项（然后是名称包含匹配项），并为每项标注 name_match；这是因为雇主名称匹配使用简单的子字符串匹配，可能会合理地返回多个不同的法定名称。

为什么要使用镜像：实时抓取 h1bdata.info 时，每次查询最多只能获取 20,000 行原始 HTML 表格记录（fetchLcaLive 的安全上限）——对于申请数量超过此上限的雇主或职位，工资统计和 top_sponsors 排名会基于经过静默截断且不具代表性的子集计算。对于来自 DOL 的年份，top_sponsors 会汇总每一条匹配记录，不受此类上限约束（参见 222_h1b_lca_disclosures.sql 中的 h1b_top_sponsors RPC 的 total_all_filings，这是一个在行数限制之前计算的窗口函数求和结果）。

**本地镜像使用财政年度，而非日历年度。**DOL 的文件按联邦财政年度组织（10 月 1 日至 9 月 30 日）；通过本地镜像提供答案时，year 会直接作为该财政年度传入。h1bdata.info 自己的“year”筛选条件语义不同且未经验证（很可能是日历年）——同一个 year 值由两种路径分别回答时，不保证涵盖完全相同的 12 个月。响应的 note/source 字段会说明实际使用了哪种路径；这是一个真实且明确披露的差异，并未刻意掩盖。

个人数据规则（强制，遵循本地副本规则 — 任务 #2514）

DOL 自己的记录布局（LCA_Record_Layout_FY2024_Q4.pdf，于 2026-09-29 全文阅读）包含具名个人的联系方式字段，这些字段绝不会读入镜像——scripts/h1b-lca-transform.py 使用源列白名单（而非黑名单），因此 DOL 日后新增的列默认会被排除：

• EMPLOYER_POC_{LAST,FIRST,MIDDLE}_NAME、EMPLOYER_POC_EMAIL、 EMPLOYER_POC_PHONE — 雇主的具名联系人。
• AGENT_ATTORNEY_{LAST,FIRST,MIDDLE}_NAME、 AGENT_ATTORNEY_EMAIL_ADDRESS、AGENT_ATTORNEY_PHONE — 代表雇主的律师／代理人。
• PREPARER_{LAST,FIRST,MIDDLE}_NAME、PREPARER_EMAIL — 填写表格的人员。

DOL 的文件本身已排除外籍员工本人的姓名／地址（DOL 自己的说明仅列出“Attorney's FEIN and Attorney's State Bar Number”为保留信息——此数据集从未包含员工个人身份信息）。保留的字段包括：EMPLOYER_NAME／TRADE_NAME_DBA 和雇主地址，精确到城市／州／国家（不含街道），以及职位／工资／工作地点字段——这些信息标识的是依法必须公开披露信息的雇主，而非私人个人。

数据源

• https://www.dol.gov/agencies/eta/foreign-labor/performance — DOL OFLC 绩效数据页面，提供各财年的披露文件链接。
• 已于 2026-09-29 在线核实（DOL 未作说明，根据 decision_date 分布逆向推断——记录布局 PDF 对已结束财年的描述有误）：
  • 当前尚未结束财年的最新季度文件是从该财年 10 月 1 日累计至所标注季度末的累计文件（FY2026_Q3.xlsx 覆盖 2025 年 10 月至 2026 年 6 月）。文件位于 https://www.dol.gov/media/LCA_Disclosure_Data_<label>.xlsx。开放财年只加载最新的单个文件。
  • 财年结束后，DOL 归档的该财年季度文件各自为独立文件——decision_date 仅落在对应季度内（已核实：FY2025_Q3.xlsx 仅含 2025 年 4 月至 6 月的数据，FY2025_Q4.xlsx 仅含 2025 年 7 月至 9 月的数据——并非全年数据，尽管记录布局 PDF 封面上明确写着“Reporting Period: October 1 ... through September 30”）。文件位于 https://www.dol.gov/sites/dolgov/files/ETA/oflc/pdfs/LCA_Disclosure_Data_<label>.xlsx。 已结束的财年需要全部四个季度文件才能覆盖全年数据；这些文件之间没有重叠。
• 无需认证，未观察到速率限制。美国联邦行政数据——属于公有领域。

导入流程

• supabase/migrations/222_h1b_lca_disclosures.sql — h1b_lca_disclosures 表 + h1b_lca_ingest_runs 记录表 + 三个 RPC（h1b_lca_search、 h1b_top_sponsors、h1b_lca_coverage）。已启用 RLS；anon/authenticated 无授权；仅限 service_role。
• scripts/h1b-lca-transform.py — 使用 openpyxl(read_only=True) 逐行流式读取一个 .xlsx 文件（绝不将整个工作簿缓存在内存中——一个完整财年的未压缩数据为 80-250MB），通过允许列表选择非个人信息列，并根据 WAGE_RATE_OF_PAY_FROM/WAGE_UNIT_OF_PAY 计算 base_salary_annual（Hour×2080、Week×52、 Bi-Weekly×26、Month×12、Year×1）。
• scripts/h1b-lca-upsert.sh — 每个文件依次执行：下载（先尝试当年 URL，失败时回退到已结束年度的存档 URL）、转换、使用 \copy 导入暂存表，然后执行 INSERT ... ON CONFLICT (case_number) DO UPDATE （CASE_NUMBER 是 DOL 为每个申请分配的稳定 ID——无需合成键）。
• .github/workflows/h1b-lca-refresh.yml — 仅支持 workflow_dispatch（有意不设置 schedule:——按照 Bruce 的“supa stagger”规则，大型 Supabase 数据加载会在夜间排队，每次只运行一个；此外，自 ~2026-09-09 起，GitHub 的 schedule: 触发器在整个集群范围内也一直不可靠）。默认 files 输入为任务要求的“最近 8 个季度”，已验证无重叠、无缺漏： 2026:FY2026_Q3（累计数据，= FY2026 Q1+Q2+Q3）+ 2025:FY2025_Q1,2025:FY2025_Q2,2025:FY2025_Q3,2025:FY2025_Q4（四个 独立季度）+ 2024:FY2024_Q4（一个独立季度）——共 6 个文件， 覆盖 2024 年 7 月至 2026 年 6 月。

观察到的大小/行数（线上数据，2026-09-29——转换验证运行，并非完整加载）

文件	字节数	实际数据行数
FY2026_Q3（累计数据，2025 年 10 月至 2026 年 6 月）	251,850,891	437,496
FY2025_Q4（仅 2025 年 7 月至 9 月）	79,134,156	118,580
FY2025_Q3（仅 2025 年 4 月至 6 月）	143,867,250	238,425
FY2025_Q2（仅 2025 年 1 月至 3 月）	106,951,050	未下载——按文件大小比例估算约 175k
FY2025_Q1（仅 2024 年 10 月至 12 月）	87,690,398	未下载——按文件大小比例估算约 145k
FY2024_Q4（仅 2024 年 7 月至 9 月）	83,056,843	未下载——按文件大小比例估算约 120k

默认 6 个文件的总量估计为：约 120-130 万行，xlsx 下载量约 650MB。每个 .xlsx 工作表的实际数据后面都有大量真正为空的虚假行 （例如，FY2026_Q3 声明的工作表维度为 1,032,736 行，其中实际数据行有 437,496 行）——这是 DOL 导出造成的结果，并非转换脚本的错误；这些行会被丢弃，并计入“没有 CASE_NUMBER”。

已知的源数据质量陷阱

DOL 原始数据中的 WAGE_RATE_OF_PAY_FROM/WAGE_UNIT_OF_PAY 偶尔会出现不一致，导致 base_salary_annual 数值荒谬（观察到 FY2026_Q3 中有一行年化后约为 4.53 亿美元——几乎可以肯定是提交者填写单位时出错；系统会原样保留，而不进行“修正”，这与 sba_loans 保留源数据中重复或冲突的原始行做法一致）。基于 median 的统计不易受此影响；响应中的 max 偶尔可能显示这类异常值——这是源数据的问题，并非镜像缺陷。

注意事项

• DOL 线上 .xlsx 文件中的 H-1B 依赖型雇主列标题为 H_1B_DEPENDENT（下划线），而记录布局 PDF 中写作 H-1B_DEPENDENT（连字符）。应以线上文件为准；已于 2026-09-29 对照 FY2026_Q3.xlsx 验证。
• 对于尚未结束的财年，不要加载多个文件；对于已结束的财年，除非该年度的四个季度文件齐全，否则不要加载其中任何文件——参见上文“数据源”。操作有误会导致行重复（重叠的累计文件和独立季度文件重复计数），或出现未被察觉的数据缺口。

快速开始

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

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

此端点实际提供的内容

tools/list 在 https://gateway.pipeworx.io/h1b/mcp 返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和其余网关级工具。因此，你看到的工具数量会多于表格中的数量：目前，单个工具包端点除了列出该工具包自己的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，并且是当天范围的权威信息。

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

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

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

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

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

curl -X POST https://gateway.pipeworx.io/v1/tools/h1b_employer_sponsorship \
  -H 'Content-Type: application/json' \
  -d '{"employer":"Google","year":2024}'

首次调用无需账户。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/h1b_employer_sponsorship。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

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

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

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

也可以直接运行，以确认服务能够启动：

npx -y @pipeworx/mcp-h1b

它通过 stdin/stdout 使用 MCP 协议，并针对仅此工具包的工具响应 initialize/tools/list/tools/call——不包含上方网关连接提供的任何共享元工具。数据源相同，工具相同，但不支持 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用自然语言提问，而不是直接调用工具——这既适用于上方的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about H1b data" })

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

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT