Perm

@pipeworx/perm

来自 DOL PERM（Program Electronic Review Management，ETA-9089 表格）披露数据的美国绿卡劳工认证信息——“公司 X 是否为员工申请绿卡”“公司 X 在 PERM 下为职位 Y 提供的薪酬是多少”“哪些公司为最多的数据工程师申请绿卡”。这是 @pipeworx/h1b 的永久劳工认证姊妹项目（后者涵盖 LCA／临时签证方面）。

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

工具

• perm_employer_certifications(employer, year?) — 公司申请数量、薪酬范围、热门职位／地点。首先返回总数，每条响应都包含 data_as_of。
• perm_salary(job_title, employer?, city?, year?, limit?) — 某职位的实际披露薪酬统计数据和记录样本。
• perm_top_sponsors(job_title, city?, year?, limit?) — 按职位的申请数量对公司排名，并提供薪酬中位数。

身份验证

无需密钥。仅使用本地镜像——无需也不接受调用方凭据。

本地镜像，不回退到实时数据

为何使用镜像：与 LCA 一样，PERM 仅以季度／年度批量 .xlsx 文件的形式发布；它不在 dol-whd／osha／ebsa 已使用的 apiprod.dol.gov v4 网关中（于 2026-10-17 实时检查：不在该网关的 45 个数据集目录中）。本地 Supabase 镜像是此工具包的唯一数据源。

与 h1b 不同，这里没有实时回退。 LCA 有 h1bdata.info，这是一个长期运营的第三方聚合服务，提供相同的 DOL 数据；但没有找到类似的 PERM 披露数据第三方镜像。因此，如果查询超出镜像当前加载的财政年度范围，或者镜像完全无法读取，每个工具都会返回 coverage_status 字段，并将赞助／数量设为 null（而非 false）——绝不会只返回一个空结果，让人误以为“该公司不提供赞助”，而实际原因是镜像尚未加载该年度数据，或尚未完成首次加载。三种可区分的状态，遵循与 h1b 的 fleet #3198 修复相同的原则：

• not_loaded_yet — 镜像的摄取表确实为空（从未运行过首次刷新）。“此数据源尚未完成首次加载。”
• mirror_unreachable — 覆盖范围读取本身失败（无凭据、超时、暂时性数据库错误）。“这并不意味着申请数量为零——本次调用实际上从未查询该数据源。”
• out_of_window — 镜像正常响应，但请求的财政年度不在其已加载范围内。这是一个真实信号（但覆盖范围可能不完整）。

雇主名称匹配分级。 perm_search 的 SQL（employer_name ILIKE '%' || p_employer || '%'）和统计 RPC 的分组都使用简单的子串匹配，因此像“Amazon”这样的查询可能会合法地返回多个不同的法定名称（已对实际 FY2025 文件进行实时验证：AMAZON.COM SERVICES LLC／Amazon.com Services LLC／Amazon.Com Services Llc／Amazon Data Services, Inc. 均有出现）。matched_employers 会优先排列完全匹配项（先去除大小写和标点差异以及常见实体后缀），然后排列名称包含匹配项；每项都会标注 name_match——使用与 h1b 相同的 employerNameKey／gradeEmployerMatch／rankEmployerVariants 逻辑（fleet #3198）。

个人数据规则（强制，本地副本规则 — task #3263）

DOL 自己的记录布局（PERM_Record_Layout_FY2026_Q3.pdf，于 2026-10-17 完整阅读）包含具名个人的联系字段，这些字段绝不会读入镜像 — scripts/perm-transform.py 使用源列的 ALLOWLIST（而非 BLOCKLIST），因此 DOL 日后新增的列默认会被排除：

• EMP_POC_{LAST,FIRST,MIDDLE}_NAME、EMP_POC_EMAIL、EMP_POC_PHONE 以及 所有 EMP_POC_ADDR* 字段 — 雇主的具名联系人。
• ATTY_AG_{LAST,FIRST,MIDDLE}_NAME、ATTY_AG_EMAIL、ATTY_AG_PHONE、所有 ATTY_AG_ADDRESS*/STATE_BAR_NUMBER/GOOD_STANDING* 字段 — 代表雇主的 个人律师或代理人（ATTY_AG_LAW_FIRM_NAME 是企业名称，也会被丢弃：这里没有任何 工具会用到它）。
• DECL_PREP_{LAST,FIRST,MIDDLE}_NAME、DECL_PREP_EMAIL — 签署雇主声明的人。
• 所有 FOREIGN_WORKER_*/COUNTRY_OF_CITIZENSHIP/CLASS_OF_ADMISSION 字段 — PERM 的布局完全没有外国工人的姓名字段（已通过完整阅读布局确认）， 但这些字段仍描述受雇主担保工人本人的国籍/教育/经验，这里没有任何工具需要这些字段。

保留：EMP_BUSINESS_NAME/EMP_TRADE_NAME 以及雇主的城市/州/国家/ FEIN/NAICS（不含街道地址 — 与 h1b_lca_disclosures 采用相同的审慎原则）， 以及工作/工资/工作地点字段和案件状态/日期 — 这些信息识别的是进行强制公开披露的雇主，而非私人个人。

数据来源

• 美国劳工部外国劳工认证办公室 — PERM 披露数据。按季度发布，按联邦财政年度划分（10 月 1 日 — 9 月 30 日）。无需认证，未观察到速率限制。美国联邦行政数据 — 属于公有领域。
• 已于 2026-10-17 在线验证：已结束的财政年度中，标注为 Q4 的文件本身就是完整财政年度数据 — 这与 h1b 的 LCA 镜像不同，后者每个已结束年份的季度文件都是独立数据，需要四个季度文件。 PERM_Record_Layout_FY2025_Q4.pdf 的封面明确写着“报告期：2024 年 10 月 1 日至 2025 年 9 月 30 日”。 因此，每个财政年度只需一个文件即可覆盖全年。当前尚未结束的财政年度中，最新季度文件同样是从 10 月 1 日开始累计的 （FY2026_Q3.pdf：“2025 年 10 月 1 日至 2026 年 6 月 30 日”）。

仅支持新版表格

DOL 的 PERM 表格（ETA-9089）于 2023-06-01 更改。已于 2026-10-17 通过两次实际下载在线验证：FY2024 文件采用旧版 155 列结构（例如只有一个 EMP_CONTACT_NAME 字段，没有 JOB_OPP_WAGE_FROM），而 FY2025 及之后的文件采用此数据包转换脚本所预期的新版 137 列结构。 scripts/perm-transform.py 的 REQUIRED_SOURCE 检查会直接拒绝旧版表格文件，而不是默默地错误映射 — 旧版表格的历史数据回填（FY2025 之前）属于未来工作，目前尚未尝试。镜像目前加载 FY2025 起的数据。

数据导入工具链

• supabase/migrations/259_perm_disclosures.sql — perm_disclosures 表 + perm_ingest_runs 记录表 + 四个 RPC（perm_search、perm_stats、 perm_top_sponsors、perm_coverage）。已启用 RLS；anon/authenticated 无授权；仅限 service_role。
• scripts/perm-transform.py — 通过 openpyxl(read_only=True) 逐行读取单个 .xlsx 文件（绝不缓冲整个工作簿），通过允许列表选择非个人信息列，并根据 JOB_OPP_WAGE_FROM/JOB_OPP_WAGE_PER 计算 base_salary_annual（小时×2080、周×52、双周×26、 月×12、年×1），并采用与 h1b 转换逻辑相同的申报方笔误防护规则（标注为“Hour”的四位或五位数金额视为已按年计算；年化结果超过 $5,000,000 时置空，不作为数据提供）。
• scripts/perm-upsert.sh — 每个文件依次执行：下载（先尝试当前年份 URL，失败则回退到已结束年份的存档 URL）、转换、通过 \copy 导入暂存表，然后执行 INSERT ... ON CONFLICT (case_number) DO UPDATE （CASE_NUMBER 是 DOL 为每份申请分配的稳定 ID — 无需合成键）。
• .github/workflows/perm-refresh.yml — 仅支持 workflow_dispatch（刻意不设置 schedule: — 按照 Bruce 的“Supa stagger”规则，大型 Supabase 数据加载会在夜间排队逐个执行；此外，自约 2026-09-09 起，GitHub 的 schedule: 触发器在整个集群中也一直不可靠）。默认 files 输入：2026:FY2026_Q3（当前开放年份）+ 2025:FY2025_Q4 （完整 FY2025）。

已观察到的大小/行数（实时数据，2026-10-17 — 转换验证试运行，尚未载入存储）

文件	字节数	实际数据行（仅转换，未写入数据库）
FY2025_Q4（完整 FY2025，2024 年 10 月至 2025 年 9 月）	87,007,731	保留 147,056 行，丢弃 1,603 行（缺少 CASE_NUMBER）
FY2024_Q4（旧格式，未载入）	76,167,854	转换程序拒绝处理 — 旧格式结构
FY2026_Q3（当前，累计数据）	156,267,808	验证试运行期间未下载 — 按 FY2025 全年数量折算 9/12 个月，估计约 110k-130k 行

注意事项

• 在实际 FY2025 文件中观察到的 case_status 值：Certified、 Certified - Expired（破折号两侧有空格 — 并非记录布局说明中可能提到的 Certified-Expired）、Denied、Withdrawn。“Certified”筛选条件匹配前两项。
• 未先构建旧格式转换路径前，不要将 FY2024 或更早年份的文件加入刷新流程 — 参见上文“仅支持新格式”。
• 如果镜像无法返回赞助或计数信息，perm_employer_certifications/perm_salary/perm_top_sponsors 都会返回 null（不会返回 false/0）— 在将空结果视为确实不存在之前，请先检查 coverage_status。

快速开始

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

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

此端点实际提供的内容

https://gateway.pipeworx.io/perm/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 都连接到同一个网关和相同的 1831+ 个数据源。唯一的区别在于直接列出的是哪个工具包的工具；从任一端点都可以通过 ask_pipeworx 访问所有工具。

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

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

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

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

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

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

或者直接运行，确认它能正常启动：

npx -y @pipeworx/mcp-perm

它通过 stdin/stdout 使用 MCP 通信，并为仅此工具包的工具响应 initialize/tools/list/tools/call——不包含上文网关连接额外提供的共享元工具。数据源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

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

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

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

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT