PubLedge

PubLedge

用于记录双方针对特定事实作出的书面解释的开放记录协议，涵盖联合解释协议（JIA）、监管缓解协议（RMA）、不采取行动函、私人裁定函、咨询意见以及类似的公民事务文书（HOA 决策日志、合作社治理记录、飞行俱乐部资产协议等）。

采用带有结构化 frontmatter 的纯 Markdown。SHA-256 清单校验可确保源文件与清单一致。该协议与 Semantic Arts gist 上层本体绑定，使来自不同主管机构的记录可以一并查询。

公开维护。软件包 v0.2.5；协议规范 v0.2.0。MCP 服务支持 MCP 2026-07-28 无状态核心，也支持旧版 2024-11-05 握手。当前 npm、MCP Registry、GitHub 标签和 GitHub Release 的状态观察记录在发布状态中。独立产品的扩展计划暂缓，等待明确的法律图谱或采用方需求信号。

适用对象

发布或依赖针对特定事实作出的书面解释，并需要以可移植、可查询的形式记录这些解释的监管机构、受监管方和公民团体。

解决的问题

针对特定事实作出的解释（不采取行动函、私人裁定、JIA、HOA 决议）散落在不同的非结构化记录中，无法跨主管机构进行比较。PubLedge 是一项开放协议，可将这些记录保存为经过清单校验并与共享本体绑定的 Markdown 文档。

规范 URL

https://publedge.org/

PAICE 法律图谱的一部分

PubLedge 是 PAICE 法律图谱的一个组件（与 EveryAILaw、AI Incident Law 和 Obligation First 并列）。它有意保持开放：代码采用 Apache 2.0 许可，协议和内容采用 CC BY 4.0 许可，注明出处即可用于商业用途。开放的姊妹项目由 EveryAILaw Pro 资助，它是图谱中唯一受限的层；这里的开放性是有意为之，也是 PBC 章程的选择。规范模型见 PAICE Foundation INTENT。

此仓库包含什么

三项内容集中于一处：

1. 协议 — PROTOCOL.md 规范和阐述其制定依据的 PRIOR-ART.md 调研。
2. 以犹他州为基础的参考内容 — 5 个 JIA/RMA 模板，以犹他州《AI 政策法案》（《犹他州法典》第 13-72a 条）和生成式 AI 安全港（第 13-75-104 条）为依据；另有 18 份示范文书，位于 data/examples/instruments/，涵盖 8 个主管机构（Utah OAIP、犹他州议会、科罗拉多州议会、SEC、CFPB、IRS Chief Counsel、IRS TEGE、CFTC）和 7 种文书类型（JIA、RMA、不采取行动函、咨询意见、私人裁定函、解释函、法规）。data/examples/obligations/ 中有 35 条一等义务记录，通过 data/examples/mapping/index.yml 与文书关联；法律生命周期与编辑成熟度分别跟踪。
3. 已发布的网站 — 渲染后的 HTML 位于 docs/，由 GitHub Pages 从 main /docs 提供服务。提交前运行 node scripts/build.js && node scripts/build-extras.js 重新生成；如果 docs/ 与源文件不一致，CI 将失败。

维护范围

每周检查会标记逾期记录和时间不一致之处，供人工审核。另有一项独立的手动试点，观察三个选定的官方来源，并保留无法访问的来源和未解决的发现。该试点不会更新验证日期、法律状态或更广泛的语料库。独立的缺失运行监控和恢复邮件验收仍未完成。有关带日期的证据和审核边界，请参阅维护试点。

机器可读端点

每条记录和索引都会同时以 HTML 和结构化形式发布，以便 Agent 无需抓取即可浏览登记库：

界面	格式
/	WebSite + Organization + DataCatalog JSON-LD（@graph）；链接到每个数据集分发项
/us/{jurisdiction}/{authority}/{type}/{instance}/	每条记录对应的规范分层 URL；内嵌 Schema.org LegalDocument JSON-LD；PDF + OCR 文本位于同一目录
/us/{jurisdiction}/{authority}/{type}/{instance}/record.json	同一记录的 JSON 版本；格式由 /schema/json/record.schema.json 验证；存在时包含 authority_response 注释
/instruments.html、/obligations.html、/authorities.html	ItemList JSON-LD；支持筛选和排序，便于人类阅读
/matrix.html	Dataset JSON-LD + 覆盖矩阵；DataDownload 分发项位于 /api/v1/matrix.json
/definitions/	DefinedTermSet，包含作为 DefinedTerm 的文书类型 + 状态
/api/v1/*.json	机器清单：容器、主要文书、主管机构、映射、矩阵、即将到期、最近变更
/api/v1/of/*.json	义务优先绑定记录，涵盖主管机构、文书、术语、义务和行政签发认定
/calendar.ics	执行日历（iCal）
/feed.xml、/atom.xml、/feed.json	RSS 2.0、Atom 1.0、JSON Feed 1.1
/sitemap.xml	站点地图索引 → 各分区站点地图（records、authorities、statutes、reference、templates、bridges、meta）
/llms.txt、/agents.json	Agent 发现简介 + 功能
/.well-known/mcp.json	可安装的 MCP 服务发现信息；其确切软件包身份和提供方观察记录于发布状态
/robots.txt	明确允许 17 种 AI 爬虫访问（GPTBot、ClaudeBot、PerplexityBot、Google-Extended、Applebot-Extended 等）
mcp-server.js	MCP 服务，提供 13 个只读工具：list_<legal-instruments>（支持按司法辖区/主管机构/类型/状态筛选）、get_<legal-instrument>、list_obligations、get_obligation、list_authorities、get_authority、search、search_obligations、get_matrix、get_mappings、fetch_by_url、get_upcoming、get_recently_changed

本仓库不是什么

• 不是监管机构。PubLedge 不会发布裁决。
• 不是律所。此处的模板是既有范例，并非法律建议。
• 不是 CMS。编辑者在 git 中编辑 markdown。
• 不是区块链。完整性层使用普通文件上的纯 SHA-256。

快速开始

git clone https://github.com/snapsynapse/publedge.git
cd publedge
./scripts/validate-hashes.sh           # verify integrity
node scripts/validate.js               # cross-reference checks
node scripts/build.js                  # regenerate docs/ entity pages + API
node scripts/build-extras.js           # copy reference HTML, feeds, discovery files

要验证义务优先绑定，请将 snapsynapse/obligation-first 检出到本仓库旁边，或设置 OBLIGATION_FIRST_DIR，然后运行 npm run validate:of。

有意编辑内容后，请刷新哈希：

./scripts/validate-hashes.sh --update

CI 会在每次推送和拉取请求时运行上述所有检查，并使用 pa11y-ci 对站点地图中的每个 URL 执行 WCAG 2.1 AA 检查。

五分钟内开始使用 PubLedge

选择适合当前任务的使用方式：

1. 浏览文书注册表，或打开规范记录，例如 SEC CorpFin 无行动函。
2. 查询索引，无需抓取 HTML：

curl -sS https://publedge.org/api/v1/containers.json | jq '.[0]'

3. 在规范记录 URL 后附加 record.json，获取记录格式的 JSON 表示：

curl -sS https://publedge.org/us/federal/sec-corpfin/nal/2025-001/record.json | jq '.id, .status'

4. 查看发布状态，确认由提供方验证的 npm 版本，然后将该软件包版本添加到任何支持 stdio 的客户端。以下示例适用于此软件包版本：

{
  "mcpServers": {
    "publedge": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

5. 使用 search 发现记录；如果已有规范的 PubLedge URL，则使用 fetch_by_url。该软件包提供上文列出的 13 个工具。完整的端点和功能清单见 api/v1/index.json、agents.json 和受源代码控制的发布状态。

data/examples/ 下的规范 Markdown 文件是持续维护的源文件。已发布的 HTML、API 索引以及每个 record.json 都是生成的表示形式，不应直接编辑。检出仓库的说明针对源代码操作；这并不代表软件包可安装。请使用规范发布状态选择经提供方验证的软件包。

仓库布局

路径	用途
PROTOCOL.md	PubLedge 规范
INTENT.md	仓库处置、当前工作和重新审议触发条件的权威说明
PRIOR-ART.md	类似文书项目的调查
DEFINITIONS.md	规范词汇（状态值、文书类型、义务种类）
MANIFEST.yaml	每个规范文件的 SHA-256 哈希值
_templates/jia/、_templates/rma/	含有 {{variable}} 占位符的填写模板
data/examples/instruments/	18 份示例文书；文件名 = 稳定 ID（例如 us-ut-oaip-rma-2025-001.md）
data/examples/authorities/	各签发机构的权威记录
data/examples/obligations/	文书引用的义务定义
data/examples/mapping/	义务到法规的映射索引
about/	手工编写的 /about/ 源页面（原样复制到 docs/）
reference/	手工编写的参考 HTML（先例、免责声明、词汇表）
schema/json/	JSON Schema 和 JSON-LD 上下文
vendor/gist/	Semantic Arts gist 核心本体的固定快照
scripts/	验证器（validate.js、verify.js）、构建脚本（build.js、build-extras.js）、哈希检查
_workshop/	网站本体研讨会的产出（分类体系、站点地图、内容指南、路线图）

_workshop/ 目录记录了上述布局背后的设计决策。在提出结构性更改前，请阅读 _workshop/TAXONOMY.md、_workshop/SITEMAP.md 和 _workshop/CONTENT-GUIDE.md。

贡献文书

1. 从 _templates/jia/ 或 _templates/rma/ 中选择模板。
2. 将每个 {{variable_name}} 替换为适用的值。
3. 将 id 设置为 {jurisdiction}-{authority}-{type}-{YYYY-NNN}（例如 us-ut-oaip-rma-2025-003）。文件名必须匹配：us-ut-oaip-rma-2025-003.md。
4. 将法律 status: proposed 和 editorial_status: draft 设为相应值。在 parties: 下添加各方。
5. 将文件放在 data/examples/instruments/ 下。
6. 运行 ./scripts/validate-hashes.sh --update，更新 MANIFEST.yaml。
7. 运行 node scripts/build.js && node scripts/build-extras.js，验证网站能否顺利重新生成。
8. 提交拉取请求。

完整规范（包括义务条目、源 PDF 和 OCR 工作流）请参阅 CONTRIBUTING.md。

许可证

PubLedge 采用双重许可：

• 内容（markdown、YAML、HTML）— CC-BY 4.0
• 代码（脚本、架构、构建工具）— Apache 2.0

许可划分详见 LICENSE。随附的快照保留其上游许可证；固定版本的 gist 核心本体采用 CC-BY 4.0（Semantic Arts）。完整致谢见 ATTRIBUTION.md。

构建基础

• Knowledge as Code — PubLedge 继承的四角色实体模式（Authority / Container / Secondary / Primary）。
• gist (Semantic Arts) — 与 PubLedge 实体绑定的开源顶层本体。
• Every AI Law — statute_anchors[] 中法规锚点 URL 的首选来源。
• skill-provenance — 为 validate-hashes.sh 改编的哈希机制模式。PubLedge 不采用完整的 skill-provenance 协议。

状态与路线图

里程碑	状态
工作坊、分类体系、站点地图、内容指南	已完成
协议规范（PROTOCOL.md）	已完成
既有方案调查（PRIOR-ART.md）	已完成
犹他州初始模板（3 个 JIA、2 个 RMA）	已完成
首个注册表实例（us-ut-oaip-jia-2026-001）	已完成
哈希固定完整性校验 + CI 验证	已完成
发现文件（llms.txt、agents.json、feed.xml）	已完成
MCP 服务（mcp-server.js）	已完成
CLI 验证器（scripts/validate.js、scripts/verify.js）	已完成
JSON Schemas + JSON-LD 上下文（schema/json/）	已完成
统一站点生成器（build.js + build-extras.js）	已完成
Frontmatter 规范 v0.2	已完成
9 项联邦 + 犹他州演示重映射	已完成
4 项犹他州法规作为一级文书记录	已完成
规范 URL 架构（/{country}/{jurisdiction}/{authority}/{type}/{YYYY-NNN}/）	已完成
每份文书的 record.json（Schema.org LegalDocument JSON-LD）	已完成
calendar.ics、api/v1/upcoming.json、api/v1/recently_changed.json	已完成
状态词汇表（9 个值）+ DEFINITIONS.md + /definitions/ 页面	已完成
用于撰写式摄取的 publedge-source-ingest skill	已完成
/reference/disclaimer/ 上的免责声明与来源政策	已完成
义务 + 映射整理阶段（35 项义务、16 项映射）	已完成
顶层页面上的 JSON-LD（首页 @graph、ItemList 索引、DefinedTermSet、Dataset）	已完成
拆分站点地图索引 + 7 个分区站点地图	已完成
与 RSS 并列的 JSON Feed 1.1 + Atom 1.0 订阅源	已完成
/schema/json/record.schema.json（JSON Schema draft 2020-12）	已完成
扩展的 MCP 工具集（13 个工具；筛选器、基于 URL 的获取、即将发生、最近变更）	已完成
robots.txt 中的显式 AI 爬虫允许列表	已完成
Authority 响应协议字段、渲染、架构与验证	已完成
audits/ + .a11y-audit/ 中的 Agent 就绪度 + a11y 审计产物	已完成
Axe-core WCAG 2.1 AA 修复（4 条规则，70 个实例 → 0）	已完成
发布前审查用的私有快照	已发送
律师审查（SLC 律师）	待处理；由需求触发
repo-polish	已完成
仓库公开	已完成
Obligation-First v0.4.x 命名配置	已完成
promo-orchestrator + 公开公告	暂缓
浏览器端注册表浏览器 + 比较工具	暂缓
拆分并剥离为可复用协议模板	暂缓

有关分阶段计划，请参阅 ROADMAP.md；原始工作坊计划请参阅 _workshop/ROADMAP.md。