Fjc Case Outcomes

@pipeworx/fjc-case-outcomes

联邦法院案件量和案件结果统计——fleet #3271。作为 court-listener 工具包的补充：court-listener 用于查找和读取单个案卷与判决意见；本工具包则回答 court-listener 没有数据的汇总统计问题（“FY2023，纽约南区有多少起民权案件立案，又是如何结案的”），并提供直接按案卷号和地区法院查询案件结果的功能。

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

状态（2026-10-19）：已晋级，数据正在加载，工具示例待完成

迁移 264 已应用，fjc-idb-refresh.yml 也已实际运行（运行编号 39288114956）：FY2023-24 已加载——民事 690,312 行、刑事 435,234 行、上诉 80,722 行，另有各自的汇总表。FY2020-22 正在单独加载。本次会话已将此工具包从 _incubator 晋级，但 tool-examples.json、实时冒烟测试载荷和部署后的重新探测尚未完成—— 这些步骤需要通过此工具包对实时后端数据表发起真实调用，而这需要将 后端数据库的 URL 和服务角色凭据作为环境变量（确切变量名见 数据导入脚本自身的文件头）；本次会话两者都没有（已确认 .env、所有 .dev.vars 文件及进程环境中均不存在）。运行 node scripts/add-pack.mjs fjc-case-outcomes 后，流程在第 3/11 步（“未注入后端存储凭据”）正常停止。持有凭据的人可以运行： node scripts/add-pack.mjs fjc-case-outcomes --from 3，从该步骤准确续跑，并根据真实调用生成 tool-examples.json。

规模与 v1 范围（2026-10-19 PM 审查后修订）

FJC 每个财政年度、每种案件类型发布一个 SAS7BDAT 文件，没有 查询 API，也不支持多年批量导出。已在线确认 FY2021-FY2023 的年度文件命名 （cv23.sas7bdat、cr23_0.sas7bdat、 ap23.sas7bdat——文件名后缀不一致且没有文档说明，探测逻辑见 scripts/ingest-fjc-idb.mjs 的文件头）。

v1 范围：仅民事和刑事案件，FY2020-FY2024（5 个财政年度）。 上诉数据在成本较低时会尽可能纳入（见下方规模估算），但并非承诺范围； 破产数据则完全不在范围内（见下文）。

实际测量的规模，而非估算。 从实时 SAS7BDAT 文件解析 FY2023 民事 （293,677 行）和刑事（218,853 行）数据，并实际加载到本地 Postgres 17 中——包括原始表、汇总表、索引及 ANALYZE——随后通过 pg_total_relation_size 测量：

表	表大小	索引	总计
fjc_idb_civil	44 MB	21 MB	65 MB
fjc_idb_criminal	27 MB	14 MB	41 MB
fjc_idb_civil_summary	1.4 MB	1.6 MB	2.9 MB
fjc_idb_criminal_summary	0.7 MB	0.9 MB	1.6 MB
一个财政年度，总计			110 MB

线性外推到 v1（5 个财政年度，民事+刑事）：约 550 MB—— 远低于可能迫使我们重新考虑存储方案的约 1.5 GB 上限。需要注意的是： 该估算仅根据一年（FY2023）外推；案件量因年份而异，因此实际的 5 年规模 可能会有一定出入，但不会达到足以改变结论的倍数。对查询（按索引检索 district+docket）和经过筛选的汇总表读取分别运行 EXPLAIN ANALYZE，均确认只使用索引扫描、耗时低于毫秒，且零顺序扫描—— 确切执行计划见迁移文件的文件头。

本次构建不包含破产 IDB 数据。 FJC 自 2008 年起就发布破产案件数据， 但本次会话探测期间，bk##/bq##/bankr## 文件名（普通形式或带 _0 后缀）均未返回 HTTP 200——它可能使用不同的命名方案或完全不同的门户。 在评估规模之前需要单独研究；为确保本次构建的范围准确，而非猜测 URL， 此处不再继续尝试。

存储

Supabase（结构化关系数据、聚合查询较多），而非 R2/FTS5——这是按地区／年份／诉讼性质／处置结果分组计数的表格案件统计数据，而不是文本搜索。上文的真实负载容量评估已确认其可行性，并非凭空假设。

三个原始表（fjc_idb_civil、fjc_idb_criminal、fjc_idb_appellate）只包含此处工具实际使用的字段——没有兜底用的 raw jsonb 列（早期草案中曾有这一列；审查时将其删除，因为在真实 Postgres 表中，即使未使用，每个字节也要付出成本，而本次修订正是要如实呈现这一点）。

聚合数据是预计算的汇总表，而不是视图。 在本次迁移的早期草案中，直接对原始表执行 GROUP BY 的视图看起来成本很低，但 PostgREST 的 statement_timeout 约为 8 秒，而 uspto-maintenance-fees 套件（2750 万行）采用这种结构时，每次调用都会超时，直到移除 count=exact 和全表扫描才解决。fjc_idb_*_summary 由 scripts/ingest-fjc-idb.mjs 按每个财年加载一次来构建（它没有直接 SQL 连接——只使用其他套件的导入流程也会用到的同一 PostgREST 凭据——因此 GROUP BY 在 Node 中对已解析的行执行，而非在 SQL 中执行），并在每次完整财年刷新时重新插入。聚合工具只读取这些汇总表，绝不读取按案件存储的原始表。完整设计理由请参阅迁移文件顶部的注释。

刷新

完整替换财年数据，而非逐行 upsert——原始表和汇总表均如此。 IDB 自身的季度更新模式只会修订仍处于报告期内的财年记录（参见 FJC Research Guide）；财年结束后，其文件便不再变化。因此，定期刷新只需重新拉取当前财年（并出于稳妥考虑，拉取上一财年）的文件，删除 (table, fiscal_year) 对应的所有已加载行——原始表和汇总表都要删除——然后重新插入：scripts/ingest-fjc-idb.mjs --case-type all --years <current>,<current-1>。FY2020-FY2024 的 v1 全量回填是单独的一次性运行，使用同一脚本并传入更宽的 --years 列表。脚本不会运行 ANALYZE（没有直接 SQL 访问权限）；完整替换某个财年的所有行后，Postgres autovacuum 会处理分析。首次一次性回填时，应由人工通过 psql 手动运行 ANALYZE 作为最后一步，而不是等待 autovacuum。

fjc-idb-refresh.yml 已在 .github/workflows/fjc-idb-refresh.yml 启用（由 config-applier 应用，因为 .github/workflows/** 禁止推送），并已成功运行过一次数据加载（运行编号 39288114956）；等 tool-examples.json 存在后，其冒烟测试步骤就会通过（参见上文“状态”）。

完整发布前剩余事项

1. 需要有人使用后端数据库的 URL 和 service-role 凭据运行 node scripts/add-pack.mjs fjc-case-outcomes --from 3——这会使用已加载的数据对两个工具进行真实冒烟测试，根据这些调用生成 tool-examples.json，并完成其余的 add-pack 检查清单（确认 npm-release-status、添加交付项）。
2. 下一次部署后，通过在线网关重新探测两个工具。
3. 在 #3271 上执行 fleet_close，并附上任务验收清单要求的 smoke_payloads、live_probes 等产物。

工具

• fjc_case_outcome_lookup(case_type, district_or_circuit, docket, fiscal_year?, defendant_number?) — 根据案卷编号和地区（上诉案件则为巡回区），查询单个案件／被告的处置结果。
• fjc_case_outcomes_summary(case_type, fiscal_year?, district_or_circuit?, nature_of_suit_code?, offense_code?, disposition_code?, group_by?, limit?) — 汇总计数，先显示总数，再按所请求的维度拆分（诉讼性质／犯罪代码／处置结果／年份／地区或巡回区）。

数据源

• 联邦司法中心（Federal Judicial Center），综合数据库（Integrated Database）——联邦法院的民事案件、刑事被告、破产案件和上诉案件的立案与终结数据，由美国法院行政办公室按季度报告。美国联邦政府数据，属于公共领域。数据持续覆盖至 1970 年（民事／刑事）和 1971 年（上诉）。没有查询 API——仅提供批量文件；此数据包将指定年份范围的数据镜像到 Supabase。

注意事项

各年份的文件名后缀不一致，且未作说明。 cv23.sas7bdat（民事）不需要后缀；cr23_0.sas7bdat（刑事）需要后缀；ap23.sas7bdat（上诉）不需要后缀。导入脚本会针对每个年份／案件类型探测两种形式，而不是硬编码某一种模式。

对于缺失日期，pandas.read_sas 会返回 NaT，而普通的 isinstance(v, float) and math.isnan(v) 检查无法捕获它，并会导致 json.dumps 报错：TypeError: Object of type NaTType is not JSON serializable——此问题在民事文件的 TRANSDAT 列中实际发生过（绝大多数案件的值都是 NaT，因为这些案件从未移交到其他地区）。现已改为先检查 pd.isna(v)，一次调用即可覆盖 None、浮点 NaN 和 NaT。

刑事被告姓名已由 FJC 自行去标识化 （经实证核实：2023 财年全部 218,853 条刑事记录中的 NAME 列均为 null），依据的是 1995／2003 年司法会议政策——没有可保留的姓名，因此刑事表完全不设姓名字段。民事当事人姓名（PLT／DEF）已填充并公开；数据按原样存储。

**1992 年财政年度边界发生了变化。**统计年度 SY70-SY91 按 7 月至次年 6 月计算；从 1993 财年起，改为联邦政府的 10 月至次年 9 月财政年度；1992 年的文件则涵盖 15 个月的过渡期。若调用方查询“1991 年”和“1993 年”，那么除非考虑到这一点，否则查询的是不可比较的 12 个月时间段——工具响应中尚未体现这一点；这是后续推广步骤需要处理的已记录问题。

**代码是原始 FJC 代码（诉讼性质、处理结果、罪名、地区、巡回区），尚未标注为易读名称。**有关为何未臆测对照表，以及计划中的后续工作（从 FJC 自行发布的代码手册中整理一张小型参考表，例如 https://www.fjc.gov/sites/default/files/idb/codebooks/），请参见迁移文件头部。

**(fiscal_year, district, office, docket) 并不唯一——这是加载真实的 2023 财年民事文件后发现的，并非预先假定。**293,677 条记录仅对应 290,139 个不同组合（约 1.2% 冲突）。检查过的一组记录中，两条记录的处理结果和诉讼性质相同，但 filedate 不同（2017 年与 2023 年）——这很可能是重启或重新编号的诉讼程序；IDB 没有案件级版本列可用于区分。刑事案件也出现了同样的情况（即使包含 defendant_number 仍有冲突）。因此，原始表在此组合上使用普通索引，而非唯一约束——导入脚本会加载 FJC 发布的所有记录，而不进行去重；fjc_case_outcome_lookup 会返回某个案号的所有匹配记录。

**fjc_case_outcomes_summary 需要提供 fiscal_year 和／或 district_or_circuit。**汇总表已预先聚合，但未筛选的多年查询仍可能产生超过 PostgREST 行数上限的不同分组；实际测量发现，仅 2023 财年就有 26,067 个不同的民事分组。工具会获取汇总表中粒度最细的所有匹配数据，并在客户端重新聚合为调用方要求的任意较粗 group_by（PostgREST 无法通过普通 select= 对表重新执行 GROUP BY）；如果获取结果触及安全上限，响应会附带 total_may_be_incomplete: true，而不是悄悄返回错误的总数。

快速开始

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

{
  "mcpServers": {
    "fjc-case-outcomes": {
      "url": "https://gateway.pipeworx.io/fjc-case-outcomes/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/fjc-case-outcomes/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 都连接到同一个网关和相同的 1879+ 个数据源。唯一的区别在于直接列出的是哪个工具包的工具；无论连接哪个，ask_pipeworx 都能访问所有工具包的工具。

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

curl -X POST https://gateway.pipeworx.io/v1/tools/fjc_case_outcome_lookup \
  -H 'Content-Type: application/json' \
  -d '{"case_type":"civil","district_or_circuit":"90","docket":"1701877","fiscal_year":2023}'

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

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

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

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

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

npx -y @pipeworx/mcp-fjc-case-outcomes

它通过 stdin/stdout 使用 MCP 协议，仅对本工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接所添加的共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

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

ask_pipeworx({ question: "your question about Fjc Case Outcomes data" })

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

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT