srdcheck

srdcheck

面向 Agent 的共享规则轨道：具名、有引用依据且边界明确的检查， 让每个调用方都能使用相同的确定性结果，而不会误将 局部检查当作全局合法性判定。

针对《系统参考文档》5.2.1 中特定规则给出机器判定： 应用规则时附上引用，可复现，可离线运行，并且足够坦诚，在问题超出 已发布范围时拒绝作答。面向 Agent 的规则律师——包括担任授权 DM 的 Agent。

Agent 从这里开始 → SKILL.md — 入门指南：何时调用、实例，以及 MUST/MUST NOT 要求。系列契约：FAMILY.md。

状态：v0.9.0 alpha — 项目尚新，但已可用，并在公开开发中。 塑造产品的破坏性测试——包括那个扼杀了我们一半初始构想的测试——见 eval/RESULTS-phase0.md；有无规则轨道的演示见 demo/mage-hand/；下方的真实性评分卡由 CI 生成。

运行时和操作系统保证见支持矩阵：Python 3.10–3.13、完整的 Ubuntu 测试套件，以及针对 Windows 和 macOS 上已安装构件的明确冒烟测试契约。

为什么要做这个项目

游戏越来越不再由一个模型运行，而是由多个 Agent 共享同一不断演变的状态——GM、玩家 Agent、规则裁判、工具调用方。只要有不止一个智能体参与裁定，核心问题就不再是单个 Agent 的知识或注意力预算，而是一致性：五个能力出众的模型各自阅读 SRD 并裁定擒抱、专注或死亡豁免时，都会略有不同，共享的游戏状态便会悄然失同步。再聪明的个体也无法保证它们彼此达成一致，而每次重新推导都多一次偏离的机会。解决办法是让它们都调用一条确定性轨道——相同的原子规则、相同的引用、每次都相同的判定——这样每个已应用规则的结果都带有统一的溯源信息，任何 Agent（或人类）都能审查。桌上裁定则保留独立的裁定沿袭。这正是 srdcheck 从便利工具变成关键基础设施的原因。

即使只有一名玩家，这条轨道也有价值。运行游戏的模型是出色的即兴创作者，但注意力预算有限：它在上下文中处理的每一项机制细节检查——这样是否合法、那个法术位是否已消耗、本轮反应是否恢复——都会耗费本应用于唯一需要智慧的工作的 token 和注意力：讲故事。而模型能够回答的检查，它无法证明，无法复现，并且——正如我们自己的基准测试所示——当问题超出规则的管辖范围时，它也不会拒绝作答。

我们在开发前测试过这一点。前沿模型几乎完美地回答了 SRD 规则问题——却也自信地裁定了自定规则、GM 自行决定的事项，以及 SRD 中不存在的内容，而这类问题唯一正确的答案是“这不归我裁定”。小型本地模型答错了 19–30%，且一次都没有拒绝作答。因此，srdcheck 并不与模型掌握的知识竞争。它是一条轨道：输入结构化事实，输出确定且有范围限制的结果；应用规则时附上引用——并为桌上的每个 Agent 提供同一条轨道。

它是什么

srdcheck 回答具名且边界明确的问题，例如：这项提议能通过 建模的动作经济检查吗？以及还剩下哪些建模预算选项类型？ 查看生成的能力与声明映射，了解每种工具 经过检查和未检查范围的权威说明。

• **给出判定，不凭感觉。**退出代码 0 = 通过已检查范围，1 = 与已检查范围冲突，2 = 无法裁定。每条已应用规则都附有 SRD 引文；对于边界拒绝，不会凭空编造引文。

• **范围和来源随判定一同提供。**判定架构 4.0 会在每个结果中保留 coverage_level、checked_scope、unchecked_scope 和 assumptions，并分别报告已断言／已使用／已推导／缺失的事实、咨询性 rule_result、带范围的 DM table_decision，以及明确的 state_mutation。每项规则说明都会指出：它仅在已检查范围内合法。

• **只做裁定，不做模拟。**不掷骰子、不叙述、不持有游戏状态。状态随查询传入；判定随结果返回。内核是无状态的纯函数，可嵌入任何 DM 产品、VTT 或 Agent。

• 状态提交默认拒绝。event.apply 会生成绑定到精确评估状态的幂等转换提案；transition.commit 会拒绝过时或顺序错误的提案，并在重试时返回相同语义的回执。Agent-DM 或宿主仍负责执行原子状态写入。请参阅 安全状态转换。

• **Agent-DM 裁定可持久化，无隐藏状态。**向现有查询工具提供可移植的桌面政策清单，以及请求／遭遇／会话／战役 ID。 匹配的裁定会自动生效，与 SRD 结果保持区分，并附带明确的桌面权限来源链。请参阅 桌面政策。

• **确定且快速。**判定流程中不调用大模型。在本地离线运行。

• **可观测，但不记录桌面内容。**选择启用的仅元数据生命周期事件会携带请求／判定 ID、版本、拒绝类别和耗时，并写入 stderr 或调用方接收器。根据约定，不包含原始提示词、状态、裁定、引文和错误消息；SRDCheck 不会持久化任何内容。

• **优先面向 Agent。**MCP + CLI、--pipe、--schema，以及仓库根目录下的 tool.json。人类可在同一负载中看到通俗易懂的原因；Agent 应将这些说明文字视为解释内容，而非约束条款。

• **规则集采用适配器。**内核不认识任何游戏；所有规则内容都从适配器包加载，每个适配器包都附带自己的来源清单——来源文档、哈希、许可证和署名——每项已应用规则的结果都会引用该清单。SRD 5.2.1 适配器作为参考实现随本仓库提供。任何人都可以为其他规则集构建适配器——社区、私人桌面，或为自己的 IP 发布第一方适配器的出版商——而他们的内容不会经过本项目。适配器目录只提供指引；绝不托管内容。

有关本项目遵循的不变量，请参阅 docs/product-truths.md；有关今日可执行示例与目标示例，请参阅 docs/anatomy-of-a-turn.md；有关 N/N-1 机器契约和更正政策，请参阅 docs/compatibility-policy.md。

维护者和收购尽职调查资料见 接管清单，其中链接了架构、发布、事件响应和支持运行手册。尚未核查的接管事项会明确列出为缺口，而不会暗示已做好准备。

**展示依据。**上下文窗口再大，也只能读懂 SRD；srdcheck 的价值在于其上层——一套一致且带引文的规则原子，以及一份共享架构，让多个 Agent 都能依赖它，无须各自将规则重新推导进上下文，导致结果渐行渐远。docs/atom-concordance.md 是该层的审计追踪：引擎应用的每条规则都映射到其依据的精确 SRD 文本（正向和反向），并自动生成、由 CI 检查是否为最新；逐字引文校验器则会证明每条引文确实出现在所引用的页面上。机器可读的 atom-concordance.json 是精简索引，Agent 可加载它来了解规则覆盖范围及其来源。

srdcheck 目前尚未检查的内容

诚实是产品的核心（真相 T8），因此这些边界会明确说明，而非含糊带过。当前 SRD 适配器覆盖了战斗回合的基础规则；它目前尚未检查：

• 特性前置条件。 turn.plan 判断回合的动作经济——你至多使用了一次动作、一次附赠动作、一次反应和一个法术位。它不会验证某项特性是否确实赋予了相应动作。仅使用一次双武器战斗的副手攻击，在“动作经济合法”这一点上没有问题，尽管 2024 年规则要求先执行攻击动作；该前置条件属于角色特性，而此版本尚未建模。成功消息会明确说明这一点。
• 各法术的效果。 伤害/生命值、死亡豁免和豁免检定现已建模（reducer 会处理 damage/heal/death-save；save.check 和 concentration.check 会解析调用方掷出的豁免），但特定法术的具体效果——例如 Fireball 的 8d6 伤害、Hold Person 在豁免失败时造成的麻痹——属于范围极广、难以穷尽的内容，仍明确不予处理。srdcheck 会计算豁免结果，但不会掷骰，也不会应用法术特有的效果。
• 状态效果覆盖范围因查询表面而异。 全部 15 种 SRD 状态效果均以注册表为依据逐条分类，而每项查询只声明其实际使用的效果：攻击修正、已建模的动作经济和速度、选定的豁免/属性检定效果、伤害类型、免疫，以及通过失能状态及其定义性嵌入条目处理的反应阻止。完整性预言机证明了其中列明的攻击/回合查询表面；这并不意味着每项工具都会检查每条状态效果条款。位置几何、先攻顺序以及隐匿/察觉对抗检定仍明确属于未覆盖范围。
• SRD 5.2.1 之外的内容——任何不在 SRD 中的内容，都会由 jurisdiction 返回退出码 2；在适配器 0.2.1 中，名称注册表涵盖法术、生物、状态效果、职业、子职业、种族、专长和背景（CI 会对照源文本进行普查校验）。背景覆盖仅限于管辖范围判断：它能识别 SRD 5.2.1 中实际列出的四种背景（侍祭、罪犯、贤者和士兵），但尚未将其规则机制作为结构化事实提供。
• 拼写错误或未知的查询字段会明确拒绝（适配器 0.2.1）：每项查询都会根据已声明的架构验证参数——遇到无法识别的字段时，会返回退出码 2 并指出该字段，绝不会悄悄使用默认值给出判定。CI 中的漂移预言机会确保处理程序与架构不再发生偏离。
• 仅当事实可能改变结果时才会请求。 若要使用已获得的 Mage Hand 能力，在提供相关距离之前会以 missing-fact 拒绝；若涉及搬运或操纵物体，还必须提供物体重量。若明确禁止某操作，或限制已超出，则结论已定，不会启动无关的补充信息循环。turn.plan 中的移动必须显式提供 feet；省略该字段绝不会被视为移动了 0 英尺。

无意义的输入（负数速度、99 环法术、超过 6 级的力竭）会返回退出码 2，而不会给出看似自信的答案。遇到疑问时，srdcheck 会拒绝判定——错误结论是唯一不可原谅的 bug。

立即试用

$ pip install git+https://github.com/chaoz23/srdcheck
$ python -m srdcheck jurisdiction "Fireball"          # exit 0 — known content
$ python -m srdcheck jurisdiction "Hexblade"          # exit 2 — not in the SRD, honestly refused
$ python -m srdcheck query mage-hand.use '{"kind": "attack"}'
{
  "verdict": "illegal",
  "exit_code": 1,
  "why": "The hand can't attack.",
  "citations": [{"section": "SRD 5.2.1 p.145 'Spells > Mage Hand'", "page": 145,
                 "quote": "The hand can't attack"}],
  "rule_ids": ["mage-hand.cant-attack"],
  "adapter": "[email protected]",
  "coverage_level": "rule-surface-complete",
  "checked_scope": ["listed uses and prohibitions", "10-pound limit", "30-foot range for the proposal"],
  "unchecked_scope": ["fine-manipulation ambiguity", "duration or range trigger tracking across events", "narrative consequences"],
  "assumptions": ["the supplied use kind describes the proposal", "supplied weight and distance facts are accurate when relevant to the result"]
}
$ python -m srdcheck query mage-hand.use '{"kind": "attack"}' --table-evaluation
# deterministic table.evaluation/1.0; status=findings, authority=self_attested
$ python -m srdcheck query save.check '{"modifier":2,"dc":10,"d20_result":12,"save_ability":"dex","saver_conditions":[]}' \
    --table-evaluation --table-context '{"session_id":"session-7","correlation_id":"discord-42"}'
$ python -m srdcheck cite "Command"                    # verbatim SRD text + page for any registered name
$ python -m srdcheck --schema                          # I/O contract for agents
$ python -m srdcheck capabilities                      # engine, protocol, adapters, digests, tools

确定性执行、离线运行，无需令牌。CI 门禁要求 100 次判定的 p95 延迟低于 100 ms；本地测得更低的延迟不构成兼容性承诺。查询接口刚刚起步，正逐步扩展——架构（内核 + 适配器，规范为 v0.9 RC）才是重点。

面向需要共享 table.evaluation/1.0 封装的桌面端宿主，query 和 --pipe 支持 --table-evaluation。 只有在指定的查询范围内，合法／非法判定才会成为完整的已检查无问题／发现结果； 缺失事实、不受支持的内容、歧义和 DM 自行裁量仍属于非无问题结果。主题包含机器可读的 srdcheck-query-scope:* 引用；可选的 --table-context JSON 可以添加调用方提供的 session_id、 entity_refs 和 correlation_id（输出为 correlation:*）。规则和引用证据完整自包含，并以每个发现的证据引用为键。 每个结果都是 self_attested，即使调用方是 DM 也不例外： 此适配器无法授予桌面、遭遇状态、动作或受保护宿主权限。

对于实时 Agent-DM 宿主，请使用 Discord 消息或已解析意图事件的 snowflake 作为保护隐私的请求关联键：

python -m srdcheck query mage-hand.use '{"kind":"attack"}' \
  --trace --request-id 123456789012345678

判定会输出到 stdout；仅含规范元数据的 NDJSON 会输出到 stderr。 有关事件架构、MCP 配置、保留边界和残余元数据风险，请参阅保护隐私的可观测性。

面向 Agent（MCP）

srdcheck 是零依赖 MCP 服务——仅使用标准库。pip install 后，命令为 srdcheck-mcp；从克隆的仓库运行则为：

{
  "mcpServers": {
    "srdcheck": {
      "command": "python3",
      "args": ["-m", "srdcheck.mcp"],
      "cwd": "/path/to/srdcheck"
    }
  }
}

完整工具清单及每个工具已检查／未检查的范围均根据运行时元数据生成，详见能力映射；CI 会拒绝过时或不完整的清单。每次调用都会以结构化内容返回与 CLI 相同的判定对象。已应用规则的结果会附带源引用；边界拒绝不会凭空捏造出处。illegal 判定是结果，而非错误；cannot-adjudicate 是坦诚的拒绝，而非失败。工具描述和架构来自已加载的适配器，因此新增适配器无需更改内核即可扩展工具列表。另请参阅 tool.json 中的 CLI 接口。选择启用的 table_evaluation MCP 工具接受 {query_type, params, context?}，并输出相同的共享封装，而不改变原生查询工具的响应。

所有一方提供的 cannot-adjudicate 结果都会在 data 下携带稳定的恢复元数据：原因代码、可恢复性、确切的缺失输入路径，以及建议的下一步操作。这些信息会告知 Agent 应修复请求、提供事实、选择适配器、使用其他能力、请求桌面裁定、协调过时状态，还是停止操作——无需解析 why。需要 DM 权限时，获授权的 Agent-DM 可以直接裁定；其他调用方则可以升级处理。详见机器可操作的拒绝契约。

作为 Python 库使用

通过稳定且有版本管理的接口使用规则集内容——无需耦合到内部文件路径：

from srdcheck import load_adapter, available_adapters

available_adapters()               # ['srd-5.1', 'srd-5.2.1', 'toy-tictactoe']
a = load_adapter("srd-5.2.1")      # a versioned identifier
a.categories()                     # the content categories this adapter carries
a.names("creature")                # every creature name (326, complete from the stat blocks)
a.record("creature", "Ghast")      # {"name": "Ghast", "cr": "2", "xp": 450, "citation": "SRD 5.2.1 p.287"}
a.query("encounter.xp-budget", {"level": 3, "difficulty": "moderate"})  # a verdict dict

跨版本版本陷阱检测——捕获在较早版本中有效、但在当前版本中已重命名／移除的名称（这是 LLM 常见的失误，例如 2014 年的“Goblin”在 2024 年变为“Goblin Warrior”）：

from srdcheck import edition_check
edition_check("Goblin", "creature")          # exit 1 — a srd-5.1 name, not in 5.2.1;
                                             #   data.candidates_in_current suggests Goblin Warrior/Minion
edition_check("Aboleth", "creature")         # exit 0 — valid in both
# or from the CLI: srdcheck edition-check "Goblin" --category creature

适配器标识符包含其版本，因此 load_adapter("srd-5.2.1") 和 load_adapter("srd-5.1") 可以共存，无需引入破坏性变更；edition_check 的参数由调用方提供（current / priors），因此可泛化到任意版本和任意类别。此句柄与内容无关：它了解类别和记录，但不了解任何特定规则集的术语。

基准测试

bench/ 是规则忠实度的裁判：包含带版本号的问题集及引用 SRD 的标准判定、可为任何模型或 Agent 评分的测试框架（通过 stdin/stdout 使用 gemini:、ollama: 或 cmd:your-agent），以及生成的评分卡，按类别分别报告错误率、拒答率和错误自信度，永远不提供汇总分数。生成的排行榜仅按错误数为参测对象排名（这是唯一不可饶恕的失败），任何第三方都可以提交经篡改检查的结果——你不能给自己的作业打分，因为标准答案属于问题集。已发布的发现：前沿模型能出色掌握成文规则，但恰恰会在规则止步之处表现出错误自信；而在按轮次跨度划分的漂移测试中（其标准判定由引擎自行推导），即使跨度达到 30 轮，它们也不会发生漂移；相比之下，本地 8B 模型的错误源于规则知识不足，而非记忆问题。只需运行一条命令，即可为你自己的 DM 产品进行基准测试。

真值记分卡

每个带标签的发布版本都会针对产品真值发布一份记分卡——由 CI 生成，从不手动编辑，也不计算总分。

由 scripts/truth_scorecard.py 生成——在 CI 中重新生成并检查差异，从不手动编辑。状态如实反映情况：结构性保障 和 审核中保留 的含义正是如此。

真值	主张	状态	证据
T1	错误判定	在 CI 中强制执行	共 749 项测试，包括从 Phase 0 评估移植的黄金测试套件；任何错误判定都会导致构建失败
T2	无引文，不立规则	在 CI 中强制执行	90/90 条规则原子都附有逐字引用的原文；适用规则的路径会引用来源，而边界拒绝不会捏造出处
T3	提供建议，绝不越权	结构性保障	API 没有可接入的阻止或否决接口；判定在设计上仅供参考
T4	一份载荷，面向两类受众	在 CI 中强制执行	每项判定都包含机器可读字段，以及模板化的通俗解释；已通过架构测试
T5	枚举才是方向	已在已发布的切片中验证	一致性扫描（50 种回合状态 + 玩具棋盘）会在每次推送时双向验证枚举与校验的一致性；覆盖所有生物的完整枚举仍是目标
T6	只做裁定，绝不模拟	在 CI 中强制执行	确定性测试加纯度 lint：内核中任何位置都不得使用随机性，判定路径中不得使用网络或子进程
T7	机制永远不应了解游戏	在 CI 中强制执行	内核 lint 会扫描每个内核模块中的游戏术语（开发期间曾据此发现一个真实违规）
T8	坦诚说明边界	在 CI 中强制执行	拒绝黄金测试：未知内容、未建模条件和确实含糊的规则文本都会返回退出码 2；含糊之处会引用来源，而注册表和输入边界可能没有引文
T9	绝不浓缩成单一数字	在 CI 中强制执行	基准测试记分卡新鲜度测试；按类别分别列出表格，整个仓库中不存在总分——即便排行榜也只按错误计数排名（T1），并分别展示其他失败模式，不将其混合
T10	陌生 Agent 启动流程	在 CI 中强制执行	冷启动一致性测试仅凭 tool.json/--schema/MCP 即可得到首次判定（24 个工具）；实测探测：仅向前沿模型提供 tool.json，它便在 1 次尝试、3.9 秒内给出了正确的首次判定（2026-07-16）
T11	桌上速度	在 CI 中强制执行	p95 延迟预算测试：100 次判定的 p95 延迟必须低于 100 毫秒；本地观测到更低延迟不构成兼容性承诺
T12	绝不兜售模型已有的能力	审核中保留	这是一项策略不变量：评审时会删去那些以知识对等为卖点的功能——由人来执行，并如实承认这一点
T13	基准测试就是产品	已发布	bench/ 发布了 5 个主题、共 5 套测试集，包含带引文的黄金判定；其中包括一个由引擎推导黄金结果、按时域划分的漂移测试通道；生成的 LEADERBOARD 可对任何主题排名；命令：driver + validate 命令可让第三方提交经过防篡改检查的结果
T14	每个派生状态都有溯源信息	在 CI 中强制执行	event.apply 会为每次成功的派生转换加盖标记（前序哈希、触发事件、规则 ID、规则与裁定的类型）；测试涵盖重放验证、篡改检测、架构最小化棘轮，以及 reducer 与 validator 的一致性；演示会逐哈希重放 15 轮

许可

• 代码：MIT。
• data/：包含根据 System Reference Document 5.2.1 派生、受 CC-BY-4.0 许可的材料——来源信息和所需署名请参阅 srdcheck/adapters/srd-5.2.1/sources/README.md。
• srdcheck 为非官方项目，与 Wizards of the Coast 无关联，也未获得其认可。

与替代方案的比较

• 只问大模型——前沿模型几乎能完美掌握这些规则（我们测量过，还因此砍掉了自己一半的想法）。但从设计上讲，它们无法做到：证明判定、复现判定，或在问题超出规则管辖范围时拒绝回答——在 6 次演示运行中的 5 次里，它们都在自由裁量区声称自己有权裁定规则。srdcheck 提供证明、拒绝、确定性和经济性——绝不提供知识。
• 查询 API 和参考 MCP 服务（Open5e、5e-srd-api 及其封装）——它们回答的是*“书上怎么说”，而不是“给定当前状态，这是否合法”*。二者互补，而非竞争；srdcheck 引用的正是它们提供的同一段文本。
• AI-DM 产品中的闭源引擎——这个垂直领域最强的产品都运行确定性规则层，各自私有重建、不附引用、未经基准测试，并且锁定在各自的平台上。srdcheck 将这一层开放、附上引用、进行基准测试，并支持嵌入——包括嵌入它们的产品。
• 模拟器库（战斗引擎、角色库）——它们运行游戏并持有状态。srdcheck 负责判定，但不持有任何状态（状态随查询传递，并带有来源链），这正是它能嵌入任何地方的原因。

先前工作

srdcheck 借鉴了 Temple of Elemental Evil / Temple+（分发器架构）、PCGen（前置条件谓词）、FoundryVTT PF2e system（将规则作为数据）、Datasworn（官方规则采用 JSON 的先例）和 FIREBALL（结构化游戏状态）的经验。我们研究了这些模式，但没有从中取用任何代码。

mcp-name: io.github.chaoz23/srdcheck

公式空缺（v0.3）

如果规则是一条公式，判定结果就是公式——只有调用方提供了所有空缺值时，才会给出数字。提供所需的体型／空手事实后，若调用 grapple.initiate 时未提供 str_modifier + proficiency_bonus，则返回 dc_formula 而不返回 dc； 若未提供 perception_modifier，则 passive.perception 返回 score_formula 而不返回 score。缘起：一次实战中，系统将基础值 8 显示为“DC 8”，而实际 DC 是 13。srdcheck 始终只负责查表：公式就是规则文本，填入调用方提供的空缺值属于算术——根据角色卡推导空缺值是 charactercheck 的职责，与本项目无关。

法术与特性事实（v0.4）

srdcheck query spell.facts '{"name": "Protection from Evil and Good", "cast_at": 1000}'
srdcheck query feature.uses '{"feature": "divine-sense", "charisma_modifier": 4}'

施法时间、距离、材料成分、持续时间、专注——这些都是 DM 凌晨 2 点容易记错的事实；srdcheck 会将其作为带引用的判定结果提供，且以全部 336 个 SRD 法术为基准进行普查（任何法术解析不完整都会导致构建失败）。cast_at 会根据调用方自己的时钟，通过纯算术计算出 expires_at：srdcheck 不持有状态，也不持有时钟。feature.uses 按照公式空缺规则处理 SRD 中基于次数公式的用法。缘起：玩家发现一个持续 10 分钟的结界被叙述为持续了 70 分钟。

编写自己的适配器（v0.5）

内核不懂任何游戏——现在，这套工具包也证明了这一点。随附的三个适配器覆盖了不同层级（仅注册表的 srd-5.1、完整的 srd-5.2.1、教程用的 toy-tictactoe）：

srdcheck new-adapter my-ruleset     # conformant skeleton
srdcheck conformance <adapter-id>   # the bar every adapter must clear

符合规范是准入门槛：来源固定为特定哈希的溯源清单、由架构声明且会拒绝未知键的输入、不会崩溃且诚实的拒绝行为，以及以普查为基准的注册表。固定黄金判定（在 CI 中运行 scripts/build_golden.py --check）可确保工具包重构对现有使用者逐字节不可见。指南：docs/ADAPTER-GUIDE.md。