
Srdcheck
io.github.chaoz23由 GitHub 账号 chaoz23 发布v0.8.0更新于 Oct 24, 2026
Scoped deterministic SRD 5.2.1 rules checks for agents — applied rules cited, boundaries explicit.
概览
让助手针对《龙与地下城》SRD 5.2.1 的具体规则问题获得确定性、带引用的裁定,并对超出范围的问题明确拒绝。
- 可以做什么
- 对 System Reference Document 5.2.1 执行具名、有边界的规则检查,返回结构化裁定与退出码:0 表示通过所检查范围,1 表示与之冲突,2 表示无法裁定。被应用的规则附带 SRD 引用,每条结果都说明已检查范围、未检查范围、假设与来源。它只做裁定而不模拟:不掷骰、不叙述、不持有游戏状态,裁定路径中不调用大模型。工具覆盖回合行动经济、豁免、专注、状态、法术与特性事实、管辖权检查以及状态转换提案。
- 适用场景
- 适合多个智能体或人类 DM 需要对成文 SRD 规则获得一致且可复现裁定的场景,避免每个模型各自重新推导。也适合需要可证明、带引用的裁定,或正确答案是诚实拒绝(问题超出 SRD 范围)的场合。
- 运行要求
- 在用户机器上本地运行的进程,仅限桌面端。可通过 uvx 运行 PyPI 包 srdcheck,或在 pip install 后使用 srdcheck-mcp 命令;需要 Python 3.10–3.13。未声明认证、环境变量、请求头或网络访问;可离线运行。
安装
在 SourceWeft 中
- 打开 控制台中的 Srdcheck,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
srdcheck
A shared rules rail for agents: named, cited checks with explicit boundaries, so every caller can use the same deterministic result without mistaking a partial check for global legality.
Machine verdicts over specific rules of the System Reference Document 5.2.1: cited when a rule is applied, reproducible, offline, and honest enough to refuse questions outside the shipped scope. The rules lawyer for agents — including an agent acting as the authorized DM.
Agents start here → SKILL.md — the front door: when to call this, worked examples, MUST/MUST NOTs. Family contract: FAMILY.md.
Status: v0.9.0 alpha — young but real, building in the open. The kill tests that shaped the product — including the one that killed half our original idea — are in eval/RESULTS-phase0.md; the with/without-rails demo is in demo/mage-hand/; the truth scorecard below is generated by CI.
Runtime and operating-system guarantees are defined in the support matrix: Python 3.10–3.13, a full Ubuntu suite, and explicit installed-artifact smoke contracts on Windows and macOS.
Why this exists
A game increasingly runs not as one model but as several agents sharing one evolving state — a GM, player agents, a rules referee, tool-callers. The moment more than one mind adjudicates, the binding problem stops being any single agent's knowledge or attention budget and becomes consistency: five capable models will each read the SRD and rule on grapple, concentration, or a death save a little differently, and the shared game state quietly desyncs. No amount of individual intelligence guarantees they agree with each other, and every re-derivation is another chance to drift. The fix is a deterministic rail they all call — the same atoms, the same citations, the same verdict every time — so every applied-rule result carries one provenance any agent (or a human) can audit. Table rulings retain separate ruling lineage. That is where srdcheck stops being a convenience and becomes load-bearing.
Even at a table of one, the rail earns its place. A model running a game is a brilliant improviser with a finite attention budget: every mechanical micro-check it handles in-context — is this legal, is that slot spent, does the reaction refresh this round — spends tokens and attention that belong to the only work that needs a mind, the story. And the checks a model can answer, it cannot prove, cannot reproduce, and — as our own benchmark showed — will not refuse when the question is outside the rules' jurisdiction.
We tested this before building. Frontier models answered our SRD rules questions nearly perfectly — and confidently ruled on house rules, GM discretion, and content that doesn't exist in the SRD, where the only correct answer is "not my call." Small local models got 19–30% wrong with zero refusals. So srdcheck does not compete with what models know. It is a rail: structured facts in, a deterministic scoped result out, with citations whenever it applies a rule — and the same rail for every agent at the table.
What it is
srdcheck answers named, bounded questions such as: does this proposal pass the modeled action-economy check? and which modeled budget option kinds remain? See the generated capability and claim map for the canonical checked and unchecked scope of every tool.
-
Verdicts, not vibes. Exit code
0= passes the checked scope,1= conflicts with the checked scope,2= cannot adjudicate. Every applied rule carries its SRD citation; boundary refusals do not invent citations. -
Scope and provenance travel with the verdict. Verdict schema 4.0 keeps
coverage_level,checked_scope,unchecked_scope, andassumptionson every result and separately reports asserted/consumed/derived/missing facts, the advisoryrule_result, any scoped DMtable_decision, and explicitstate_mutation. Every legal explanation says it is legal only within that checked scope. -
Judge, never simulate. No dice, no narration, no owned game state. State comes in with the query; a verdict goes out. The kernel is a stateless pure function — embeddable in anyone's DM product, VTT, or agent.
-
State commits fail closed.
event.applyemits an idempotent transition proposal bound to the exact evaluated state;transition.commitrejects a stale/out-of-order proposal and returns the same semantic receipt on retry. The agent-DM or host still performs the atomic state write. See safe state transitions. -
Agent-DM rulings persist without hidden state. Supply a portable table-policy manifest and request/encounter/session/campaign IDs to existing query tools. Matching rulings apply automatically, remain distinct from the SRD result, and carry explicit table-authority lineage. See table policies.
-
Deterministic and fast. No LLM call anywhere in the verdict path. Runs local and offline.
-
Observable without recording the table. Opt-in metadata-only lifecycle events carry request/verdict IDs, versions, refusal class, and timing on stderr or a caller sink. Raw prompts, state, rulings, citations, and error messages are excluded by contract; SRDCheck persists nothing.
-
For agents first. MCP + CLI,
--pipe,--schema,tool.jsonat the repo root. Humans get plain-English why in the same payload; agents treat that prose as explanatory, not contractual. -
Rulesets are adapters. The kernel knows no game; all rule content loads from adapter packages, each carrying its own provenance manifest — source document, hash, license, attribution — that every applied-rule result cites through. The SRD 5.2.1 adapter ships in this repo as the reference implementation. Anyone can build an adapter for another ruleset — a community, a private table, or a publisher shipping a first-party adapter for their own IP — and their content never passes through this project. The adapter catalog points; it never hosts.
See docs/product-truths.md for the invariants this project holds itself to, docs/anatomy-of-a-turn.md for executable-today versus target examples, and docs/compatibility-policy.md for the N/N-1 machine contract and correction policy.
Maintainer and acquisition diligence lives in the takeover inventory, with linked architecture, release, incident-response, and support runbooks. Unchecked takeover items are explicit gaps, not implied readiness.
Show your work. A big context window can read the SRD; srdcheck's value is the layer above — a consistent, cited set of rule atoms and a shared schema that several agents can rely on without each re-deriving the rules into context and drifting apart. docs/atom-concordance.md is the audit trail for that layer: every rule the engine applies, mapped to the exact SRD text it's grounded in (forward and inverse), generated and CI-checked-fresh, with a verbatim-citation oracle proving each quote really is on its cited page. A machine-readable atom-concordance.json is the slim index an agent can load to know what the rail covers and where it came from.
What srdcheck does not check yet
Honesty is the product (truth T8), so the boundaries are stated, not implied. The current SRD adapter covers combat-turn fundamentals; it does not yet check:
- Feature prerequisites.
turn.planjudges the turn's action economy — that you spent at most one action, one bonus action, one reaction, one spell slot. It does not verify that a feature actually grants a given action. A lone two-weapon-fighting offhand attack is "action-economy legal" even though the 2024 rules require the Attack action first; that prerequisite lives in the character's features, which this version doesn't model. The success message says so explicitly. - Per-spell effects. Damage/HP, death saves, and saving throws are now modeled (the reducer folds
damage/heal/death-save;save.checkandconcentration.checkresolve caller-rolled saves), but what a given spell does — Fireball's 8d6, Hold Person's paralysis on a failed save — is the long-tail swamp and stays refused. srdcheck computes the save; it does not roll the dice or apply the spell's bespoke effect. - Condition coverage is surface-specific. All 15 SRD conditions are registry-anchored and classified clause by clause, while each query claims only the effects it actually consumes: attack modifiers, modeled action economy and Speed, selected save/check effects, damage typing, immunity, and Reaction blocking through Incapacitated and its definitional embeds. The completeness oracle proves its named attack/turn surfaces; it does not imply that every condition clause is checked by every tool. Positional geometry, initiative order, and stealth/perception contests remain explicit boundaries.
- Content outside the SRD 5.2.1 — anything not in the SRD returns exit 2 from
jurisdiction; in adapter 0.2.1 the name registries cover spells, creatures, conditions, classes, subclasses, species, feats, and backgrounds (census-anchored against the source text in CI). Background coverage is jurisdiction-only: it recognizes the four backgrounds actually present in SRD 5.2.1 (Acolyte, Criminal, Sage, and Soldier) but does not yet expose their mechanics as structured facts. - Misspelled or unknown query fields refuse loudly (adapter 0.2.1): every query validates its params against the declared schema — an unrecognized field returns exit 2 naming the offender, never a silently-defaulted verdict. A drift oracle in CI keeps handlers and schemas from ever diverging again.
- Facts are requested only while they can change the result. A granted Mage
Hand use refuses with
missing-factuntil its relevant distance and, when it carries or manipulates an object, weight are supplied. A prohibition or an already-exceeded limit is decisive and does not trigger an irrelevant repair loop. Aturn.planmove requires explicitfeet; omission is never treated as a zero-foot move.
Nonsensical inputs (negative Speed, a 99th-level spell, exhaustion past 6) return exit 2 rather than a confident-looking answer. When in doubt, srdcheck refuses — a wrong verdict is the only unforgivable bug.
Try it now
Deterministic, offline, and no tokens. CI gates 100-verdict p95 latency below 100 ms; lower local observations are not a compatibility promise. The query surface is young and growing slice by slice — the architecture (kernel + adapters, spec at v0.9 RC) is the point.
query and --pipe accept --table-evaluation for portfolio hosts that need
the shared table.evaluation/1.0 envelope. Legal/illegal verdicts become
complete checked-clean/finding results only within the named query scope;
missing facts, unsupported content, ambiguity, and DM discretion remain
non-clean. The subject carries a machine-readable srdcheck-query-scope:*
reference; optional --table-context JSON can add caller-owned session_id,
entity_refs, and a correlation_id (emitted as correlation:*). Rule and
citation evidence is self-contained and keyed by every finding evidence ref.
Every result is self_attested, including when the calling agent is the DM:
this adapter cannot grant table, encounter-state, action, or protected-host
authority.
For a live agent-DM host, use the Discord message or resolved-intent event snowflake as the privacy-safe request join key:
The verdict stays on stdout; canonical metadata-only NDJSON goes to stderr. See privacy-safe observability for the event schema, MCP configuration, retention boundary, and residual metadata risk.
For agents (MCP)
srdcheck is an MCP server with zero dependencies — stdlib only. After pip install, the command is srdcheck-mcp; from a clone it's:
The complete tool inventory and each tool's checked/unchecked scope are generated
from runtime metadata in the capability map; CI rejects
stale or incomplete inventory. Every call returns the same verdict object as the
CLI as structured content. Applied-rule results carry their source citations;
boundary refusals do not invent provenance. An illegal verdict is a result,
not an error; cannot-adjudicate is an honest refusal, not a failure. Tool
descriptions and schemas come from loaded adapters, so new adapters extend the
tool list without kernel changes. See also tool.json for the CLI
surface. The opt-in table_evaluation MCP tool accepts {query_type, params, context?} and emits the same shared envelope without changing native query-tool
responses.
Every first-party cannot-adjudicate result carries stable recovery metadata
under data: a reason code, recoverability, exact missing-input paths, and a
suggested next action. That tells an agent whether to repair the request,
provide facts, select an adapter, use another capability, resolve a table
ruling, reconcile stale state, or stop—without parsing why. When DM authority is required, an
authorized agent-DM can rule directly; another caller can escalate. See the
machine-actionable refusal contract.
As a Python library
Consume a ruleset's content through a stable, versioned interface — no coupling to internal file paths:
Cross-version edition-trap detection — catch a name that was valid in an older edition but renamed/removed in the current one (the classic LLM failure, e.g. "Goblin" in 2014 → "Goblin Warrior" in 2024):
Adapter identifiers carry their version, so load_adapter("srd-5.2.1") and load_adapter("srd-5.1") coexist without a breaking change; edition_check is caller-parameterized (current / priors), so it generalizes to any versions and any category. The handle is content-neutral: it knows about categories and records, never about a specific ruleset's vocabulary.
The benchmark
bench/ is the rules-fidelity referee: versioned question sets with SRD-cited gold verdicts, a harness that scores any model or agent (gemini:, ollama:, or cmd:your-agent on stdin/stdout), and a generated scorecard that reports wrong-rate, refusal-rate, and false-confidence separately, per category, with no aggregate number — ever. A generated leaderboard ranks subjects by wrong-count alone (the one unforgivable failure), and any third party can submit a tamper-checked result — you can't grade your own homework, because the golds are the set's. Published findings: frontier models ace codified rules and fail by false confidence exactly where the rules end — and, on a per-horizon drift lane whose gold verdicts are derived by the engine itself, they don't drift even at 30-round horizons, while a local 8B model's errors are mistakes of rule-knowledge, not memory. Benchmark your own DM product with one command.
Truth scorecard
Every tagged release publishes a scorecard against the product truths — generated by CI, never hand-edited, no aggregate score.
Generated by scripts/truth_scorecard.py — regenerated and diff-checked in CI, never hand-edited. Statuses are honest: structural and held in review mean exactly that.
Licensing
- Code: MIT.
data/: includes material derived from the System Reference Document 5.2.1 under CC-BY-4.0 — seesrdcheck/adapters/srd-5.2.1/sources/README.mdfor provenance and the required attribution.- srdcheck is unofficial and is not affiliated with or endorsed by Wizards of the Coast.
vs alternatives
- Just asking the LLM — frontier models know these rules nearly perfectly (we measured it and killed half our own idea). What they can't do by construction: prove a verdict, reproduce it, or refuse when the question is outside the rules' jurisdiction — they claimed rules authority in the discretion zone in 5 of 6 demo runs. srdcheck sells proof, refusal, determinism, and economy — never knowledge.
- Lookup APIs and reference MCP servers (Open5e, 5e-srd-api and their wrappers) — they answer "what does the book say," not "is this legal given this state." Complementary, not competing; srdcheck cites the same text they serve.
- Closed engines inside AI-DM products — the strongest products in this vertical run deterministic rules layers, each rebuilt privately, uncited, unbenchmarked, and locked to their platform. srdcheck is that layer open, cited, benchmarked, and embeddable — including in theirs.
- Simulator libraries (combat engines, character libraries) — they run games and own state. srdcheck judges and owns nothing (state travels with the query, stamped with lineage), which is exactly what makes it embeddable anywhere.
Prior art
srdcheck stands on lessons from Temple of Elemental Evil / Temple+ (dispatcher architecture), PCGen (prerequisite predicates), the FoundryVTT PF2e system (rules as data), Datasworn (official rules-as-JSON precedent), and FIREBALL (structured play state). Patterns were studied; no code was taken from any of them.
mcp-name: io.github.chaoz23/srdcheck
Formula blanks (v0.3)
If a rule is a formula, the verdict is the formula — a number appears
only when the caller supplied every blank. Once the required size/free-hand
prerequisite facts are supplied, grapple.initiate without str_modifier +
proficiency_bonus returns dc_formula and no dc;
passive.perception without perception_modifier returns score_formula
and no score. Origin: a live table where the base-8 rendered as "DC 8"
when the true DC was 13. srdcheck stays lookup-pure: the formula is the rule
text, filling caller-supplied blanks is arithmetic — deriving the blanks
from a sheet is charactercheck's lane, never this one.
Spell & feature facts (v0.4)
Casting time, range, components, duration, concentration — the facts a DM
misremembers at 2am — as cited verdicts, census-anchored over all 336 SRD
spells (the build fails if any spell parses incompletely). cast_at adds
expires_at as pure arithmetic on the caller's own clock: srdcheck holds no
state and no clock. feature.uses covers the SRD's use-count formulas
under the formula-blanks discipline. Origin: a 10-minute ward narrated as
active for seventy minutes, caught by the human player.
Writing your own adapter (v0.5)
The kernel knows no game — and now the kit proves it. Three bundled adapters
span the tiers (registry-only srd-5.1, full srd-5.2.1, tutorial
toy-tictactoe):
Conformance is the entry ticket: provenance manifest with a hash-pinned
source, schema-declared inputs that refuse unknown keys, crash-free honest
refusal, census-anchored registries. Golden-verdict pinning
(scripts/build_golden.py --check, in CI) guarantees kit refactors are
byte-invisible to existing consumers. Guide: docs/ADAPTER-GUIDE.md.
来源:README.md,提交 fd8bd14
工具
0版本历史
1- v0.8.0最新Sep 16, 2026
评分
已满足适用检查项的 40%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
请在仓库或注册中心条目中声明许可证。