PurRAssist

PurRAssist

为那些细节几乎正确的 AI 提供帮助。

PurRAssist 可从不完善的 JSON、名称、路径和文本中还原意图。为解码器提供一个 架构和一个努力程度：它会搜索组合式修正，验证完整结果，并返回变更证据。符合架构的猜测 仍然只是猜测。模棱两可的备选项会继续显示。可将其用作 Rust crate、MCP 服务或 CLI。

版本 0.1.0。 以 rust-v0.1.0 发布：六个 crate 均已发布到 crates.io，并提供 docs.rs 上的文档。请阅读 变更日志、说明可接受范围的实现契约， 以及提供可执行证据的资格记录。其中的 已知限制不会阻碍发布。发布流程 记录了软件包和注册表的门槛。

一个引擎，三种接口

一个恢复引擎，三种平等的使用方式：作为 Rust crate、MCP 服务和命令行工具。它们共用相同的引擎和证据回执。

Rust crate

cargo add purrassist

use purrassist::{Outcome, RecoveryRequest, Schema};

let schema = Schema::compile(r#"{
  "type": "object",
  "required": ["temperature"],
  "properties": {"temperature": {"type": "number"}},
  "additionalProperties": false
}"#)?;

let answer = schema.recover("[[{temperatur: '42',}]]", RecoveryRequest::default());
match answer.outcome {
    Outcome::Resolved(value) => assert_eq!(value.to_json(), r#"{"temperature":42}"#),
    Outcome::BestGuess(value) => println!("inferred: {}", value.to_json()),
    Outcome::Ambiguous(values) => println!("{} interpretations", values.len()),
    Outcome::Unresolved => println!("{}", answer.receipt.stopped),
}
# Ok::<(), purrassist::schema::SchemaError>(())

purrassist crate 是 Rust 接口： 它重新导出纯引擎、语法集成和派生宏。

MCP 服务

cargo install purrassist-cli
purrassist mcp --root /path/to/workspace

将服务添加到任何可启动 stdio 服务的 MCP 客户端：

{
  "mcpServers": {
    "purrassist": {
      "command": "purrassist",
      "args": ["mcp", "--root", "/path/to/workspace"]
    }
  }
}

该服务通过 stdio 使用以换行符分隔的 JSON-RPC。所有工具均列于 工具参考。启动服务会在根目录中创建 .purrassist/ 目录，文件工具会在其中保存事务日志；下方的 call 命令也会执行相同操作。

CLI

purrassist decode --schema schema.json --input response.txt
purrassist call match_strings --root DIR < args.json

purrassist call TOOL --root DIR 从 stdin 读取 JSON 参数对象，并 调用与 MCP 相同的操作：对于每个已注册工具，CLI 和 MCP 的结果都完全一致，这由测试 every_registry_entry_has_a_fixture_validated_through_cli_and_mcp 按工具逐一检查。 便捷命令 decode 和 match 是快捷方式，输出格式各自独立，并非工具的输出。 purrassist validate 会原样打印 validate_json 工具的输出。

Crate 概览

发布版本包含六个 crate，并按以下顺序发布：

Crate	职责
purrassist-core	共享引擎：纯恢复、匹配、架构、Markdown 和工具调用引擎，不依赖任何第三方运行时。
purrassist-derive	共享引擎：为类型化工具定义提供零依赖的 #[derive(ToolDefinition)] 和 #[derive(ToolEnum)]。
purrassist-syntax	共享引擎：隔离的 Tree-sitter 语法集成，用于源码检查和经验证的修复。
purrassist	Rust 接口：重新导出引擎和派生宏的门面。
purrassist-host	CLI 和 MCP 服务背后的文件系统及辅助功能集成：限定根目录的文件、带日志的替换、共享工具注册表。
purrassist-cli	CLI 和 stdio MCP 服务：purrassist 可执行程序。

工作区中还有两个内部 crate，不会发布：wasm-harness（原生、WASI 和浏览器 WASM 验收记录）以及 purrassist-helper-census （重复功能清点）。

功能

纯核心包含自己的 JSON 解析器、精确十进制算术、架构验证器、 Unicode 规范化、编辑距离、语音匹配、语义规则、恢复 搜索和回执。它不依赖任何第三方运行时。隔离的语法 crate 使用固定版本的 Tree-sitter 语法系列；请参阅 依赖项清单。每种工具均见 工具参考。

当前支持的功能包括：

• JSON 恢复功能包括嵌套解包、语法修复、近似键名/枚举值、字符串化值、完整架构验证，以及由项目自有的见证生成代数生成的虚构值（必需属性、patternProperties/additionalProperties/dependentSchemas 填充、符合 propertyNames 的键名修复），而非不考虑架构的启发式方法。
• 支持 Unicode、词法、Levenshtein、非受限 Damerau-Levenshtein、英语 Soundex、别名和上下文路径匹配。
• 支持显式语义域规则和调用方提供的嵌入相似度。
• 支持基于源文本的编辑、有界模糊替换、可重定位的统一差异、重叠检查、精确字节撤销，以及 Markdown 编辑索引和结构化的章节/列表/表格/引用操作。所有 1,324 个固定的 CommonMark/GFM 示例均经过精确渲染检查，并辅以生成式保留属性和独立差分测试。
• 支持 Python、Rust、JavaScript/JSX、TypeScript/TSX 语法检查和经过验证的标点修复。语法接受不代表程序正确。
• 支持面向协同写入方的单文件日志式替换和条件撤销。
• 从模型原始输出中恢复工具调用：支持加权、可逆的方言语法和优先级优先的标记修复；可根据带类型的工具或保留信息的 OpenAI/MCP/Anthropic 声明（Draft 2020-12 或 Draft-07 架构）解析；提供逐个调用的结果及分项修复；为会产生变更的工具提供保守保护；并可重新输出为任意方言或 OpenAI tool_calls 数组。对于尚未内置或不在请求允许列表中的方言调用标记，会报告为被拒绝的尝试（unsupported_dialect），绝不会将其静默视为内容。内置十二种方言：qwen3-coder-xml.v1、hermes.v1、openai-tool-calls.v1、llama3-json.v1、mistral-v3.v1、mistral-v11.v1、deepseek-v3.1.v1、deepseek-v3.v1、kimi-k2.v1、anthropic-tool-use.v1、harmony.v1 和 bare-json.v1；调用方可使用语法 DSL 添加自定义方言。带类型的工具定义可通过 #[derive(ToolDefinition)] 和 #[derive(ToolEnum)] 从 Rust 结构体和枚举生成（无依赖的 purrassist-derive crate，由门面重新导出；见下方示例）。仍在跟踪的项目包括：pythonic.v1（#12）、glm-4.5.v1（#13）和 gemma3-tool-code.v1（#14）方言、*-stripped 变体（#18）、流式识别（#16）和提供方流式事件（#17）。参见工具调用恢复。
• 提供 CLI、stdio MCP，以及可恢复的辅助请求/响应适配器（prepare_helper 和 complete_helper；参见辅助工具）。默认情况下无需模型，也不会加载或联系任何模型。

工具的架构和带类型的参数可以来自同一个 Rust 结构体：

use purrassist::json;
use purrassist::tool_call::{FromNode, ToolArguments};

#[derive(purrassist::ToolEnum, Debug, PartialEq)]
enum Order {
    Asc,
    Desc,
}

/// Search the index.
#[derive(purrassist::ToolDefinition, Debug, PartialEq)]
#[tool(effects = read_only)]
struct Search {
    /// What to look for.
    query: String,
    #[param(default = 10)]
    limit: u32,
    order: Option<Order>,
}

assert_eq!(Search::tool_definition().name(), "search");
let arguments = json::parse(r#"{"query": "cats", "order": "Desc"}"#)?;
assert_eq!(
    Search::from_node(&arguments),
    Ok(Search { query: "cats".into(), limit: 10, order: Some(Order::Desc) }),
);
# Ok::<(), Box<dyn std::error::Error>>(())

Schema::generate_witness/generate_witness_governed 会单独实现见证生成代数（规范化、通过德摩根对偶消除 not、合并 allOf 约束，并生成按类型定向的值，同时递归处理 $ref/$dynamicRef）：其结果为经过验证的 Witness、封闭形式的 Unsatisfiable 证明（绝不会根据搜索耗尽推断得出），或如实报告的 Exhausted；恢复过程也会通过同一代数生成所有猜测值。Schema::compile_governed 和 with_resources_governed 会返回带类型的 CompilationError 值，区分无效架构和资源故障。将同一个 governor 传入 recover_governed，即可共享总准备和恢复预算。decode_json 工具会自动完成此操作。便捷编译方法使用默认的有限预算。 purrassist_core::patch::Patch（一种有序、不重叠且绑定源摘要的字节范围替换集合）是此 crate 唯一的编辑表示；edits::EditPlan/TextEdit 是它的别名。除了 apply，它还提供受治理的 invert、compose、commute、rebase 和 diff 代数；apply_edit/apply_file 通过显式的 rebase_from 输入，使用 rebase/diff 将过时计划与期间发生的更改协调起来。请参阅计划应用。Rust markdown::Document API 的结构操作——insert_section、remove_section、move_section（可选地重新设置移动部分自身标题的级别）、rename_heading、ListItemEdit::Move、renumber_list、TableRowEdit::Move、TableColumnEdit::Move，以及 add_reference/relabel_reference/remove_reference/unlink_reference（这些操作会重写所有解析到受影响定义的快捷、折叠和完整引用用法）——通过宿主工具 plan_markdown_structure 提供，并由类型化的 op 选择（section_insert、section_remove、section_move、section_rename、list_move、list_renumber、table_row_move、table_column_move、reference_add、reference_relabel、reference_remove、reference_unlink）。每项操作都受治理、绑定摘要、经过重新解析检查，并提供精确的逆操作。

Rust markdown::InlineFragment 层保留精确的字节跨度，并渲染代码跨度、强调、加粗强调、行内链接/图片、转义、换行、自动链接和原始行内 HTML。显式选择方言可保留固定版本 CommonMark/GFM 的渲染差异。命名实体/数字实体会被解码。markdown::References 从提供的段落块中收集定义；InlineFragment::parse_with_references 会解析完整、折叠和快捷链接/图片，同时保留定义来源信息。Document::render_html 会收集各容器中的定义并渲染块。GFM 渲染会启用表格、任务列表、删除线、扩展自动链接和标签过滤；也可以使用显式扩展配置。全部 1,324 个固定版本的官方文档示例，均能在其上游配置下匹配精确 HTML。生成的对抗性保留检查和独立差分检查扩展了这个有限语料库；资格记录说明了它们的覆盖范围和局限性。

文件工具会拒绝过时版本，并记录事务标识以供撤销。可移植文件系统层会协调协作写入者；它并非用于防范恶意目录替换的沙箱，也不提供原子多文件事务。

受治理的引擎和宿主工具接受由调用方管理的取消，并具有明确的事务边界。stdio MCP 服务会在工具运行期间处理取消，并且最多允许四个活动工具调用。

使用检出代码

cargo run -p purrassist-cli -- --help
cargo run -p purrassist-cli -- match raeder reader writer
cargo run -p purrassist-cli -- call match_strings --root . < examples/match-strings.json
cargo run -p purrassist-cli -- call resolve_string --root . < examples/resolve-string.json
cargo run -p purrassist-cli -- decode --schema examples/temperature.schema.json \
  --input examples/temperature.input.txt
cargo run -p purrassist-cli -- recover-tool-calls --tools tools.json --emit openai turn.txt
cargo run -p purrassist-cli -- mcp --root /path/to/workspace

decode 会以 JSON 格式返回答案和收据。Exact 不执行任何恢复；Quick、Standard、Deep 和 Maximum 会逐步增加有限的搜索预算。耗尽会明确报告，且绝不证明某个架构不可满足。recover-tool-calls 会打印与 recover_tool_calls MCP 工具相同的结果，且绝不会执行调用。测试套件会通过 CLI 和 MCP 运行 examples/ 下的每个示例请求。工具参考介绍每个工具、其参数和示例；集成指南列出 recover-tool-calls 的所有选项。

开发与验证

Rust edition 2024，MSRV 1.98。开发使用 nightly Rust，以及 Clippy 和 rustfmt。禁止绕过提交验证。

make check       # formatting, attribution/dependencies, lint, optimized tests, docs
make wasm-test   # compare native/WASI recovery, matching, embeddings, Markdown, and grammars
make syntax-oracles  # compare fixed syntax probes to independent compilers
make benchmark  # recovery quality assertions and latency baseline
make fuzz       # ten coverage-guided targets and independent pattern/Markdown oracles
make fuzz-hosted  # the CI and pre-tag fuzz gate (known #6/#11 limitations handled)
make resources  # allocations, heap/RSS, latency, artifact size, and uncached build cost
make package    # Cargo verification and registered source/license archive audit
make release-gate  # the one release gate, run on the release toolchain by pull requests and release qualification

可使用 make resources 进行资源分析；请参阅测量范围和前置条件。该操作使用外部分析器，不会增加 crate 运行时依赖。

可对十个目标分别进行覆盖率引导的测试活动，使用 make fuzz TARGET=<target>（例如 TARGET=json）；请参阅属性、重放和资格认定限制。默认的 make fuzz 目前会因问题 #11 和 #6 的特征而停止，这些特征列于已知限制下；make fuzz-hosted 会在保留并注明这些限制的情况下完成所有目标。

一致性

JSON Schema 验证支持两种方言，由 $schema 选择：Draft 2020-12（默认）和 Draft-07（http://json-schema.org/draft-07/schema#，末尾可带 #，MCP 服务通常会这样声明）。Draft-07 支持元组形式的 items 与 additionalItems、definitions、两种形式的 dependencies、$ref 覆盖其同级关键字、$id 更改基 URI，以及纯名称 #anchor 标识符；Draft-07 验证会报告验证器 purrassist.schema.draft-07.v1。Draft 2019-09、draft-06 及更早的方言会在编译时被拒绝。见证生成、由 Schema 引导的恢复，以及工具声明适配器均遵循适用的这两种方言之一。

已纳入版本控制的主 Draft 2020-12 测试集包含 1,301 个测试，另有 121 个选定的可选测试也会运行；此外，还会运行完整的 vendored optional/format/ 测试集（878 个案例，涵盖所有 2020-12 格式，包括 RFC 5892/5893 IDNA2008 上下文规则和双向规则），运行时使用声明了格式断言词汇表的方言。所有 929 个必需的 Draft-07 案例均通过；911 个 Draft-07 optional/ 案例中（格式根据其注释结果判定），905 个通过，未通过的 6 个案例按组列出，并附有原因：内容断言（按设计仅作注释）以及跨 Draft 2019-09 草案的引用（未实现的方言）。Unicode 17 规范化测试包含 20,034 个案例。这些测试套件、回归测试、固定辅助程序记录，以及有界变异探测均可在本地运行。完整的发布资格认定要求通过资格认定记录中所述的精确提交门禁和注册表验收。

许可证与项目系列

第一方代码可按 MIT OR Apache-2.0 OR MulanPSL-2.0 任一许可证使用（MIT、Apache-2.0、MulanPSL-2.0）。 GitHub 侧边栏只显示三个许可证中的一个；Cargo.toml 中的 SPDX 表达式才是权威依据。第三方数据和语法依赖保留其各自的声明。 PurRAssist 与 PurRDF 共享 Blackcat Informatics 的猫剪影和配色；大括号和验证标记是此 crate 的服务徽标。