SPARDA

SPARDA

🇫🇷 法语 — AI 写作。SPARDA 证明。 一个确定性的离线门禁，可检测 AI 修改何时移除了防护、暴露了路由或破坏了不变量——无需 API 密钥，直接集成到 Agent 的编辑循环中。10 分钟全面了解（痛点、架构、愿景）：SPARDA-EXPLIQUE.md。

---

AI 写作。SPARDA 证明。

AI 写作。SPARDA 证明。

AI 编写后端的信任层。 SPARDA 会将你的后端——路由、数据库查询、状态变更、防护机制、副作用——编译成一个确定性的行为图，然后在发布前静态证明哪些问题会发生、哪些不会：没有未受保护的状态变更，没有被破坏的不变量，没有非原子性的聚合写入。

100% 本地运行 · 确定性 · 无需 API 密钥 · 无需云账户。遇到真实风险时，它会明确报错；如果只能看到应用的一部分，则会标记为 PROVEN (PARTIAL)——绝不会错误地显示绿色。而当它能证明自己甚至没有检查整个应用时，就会标记为 PREMISE NOT VERIFIED，不做任何断言。

60 秒验证

适用于你的 Express、FastAPI、Flask、Next.js、NestJS 或 Medusa 应用——无需任何配置：

npx sparda-mcp apocalypse   # prove the tree is safe to deploy — exit 1 on any real risk, or on an unverified premise
npx sparda-mcp prove        # the whole verdict: proof + coverage + shareable seal
npx sparda-mcp badge        # a README badge: proven · coverage% · routes

在底层，它会将后端编译成一个与语言无关的图——统一行为图（UBG），根据 SBIR 规范序列化为 .sparda/ubg.json（SPARDA 行为 IR）——每条命令都是对该图的一次遍历。

核心优势——在编辑循环中捕获移除防护的 AI 修改

文本差异审查和模式扫描器从根本上做不到的一件事：证明这次特定修改移除了上一版本中已有的保护。sparda gate 会对比修改前后的行为图，并拦截回归问题——确定性、离线、亚秒级运行，退出码为 2（Claude Code 的 PostToolUse 契约会据此停止 Agent 的编辑循环）。只需一条命令，无需设置，即可端到端查看：

npm run wedge     # (from a clone)  — or drive it on your own app with `sparda gate --arm` then `sparda gate --hook`

  1. baseline armed on the guarded code   (POST /admin/delete-user · requireAdmin)
  2. an AI edit "simplifies" requireAdmin → a pass-through (still compiles, still 200s)
  3. sparda gate on the edit:
       ✗ [critical] GUARD_REMOVED — POST /admin/delete-user was guarded in the baseline
                    and is now reachable without any guard (src/app.js:11)
     ⏱  ~40 ms · deterministic · offline · no API key
     ⛔ exit 2 on --hook — Claude Code PostToolUse blocks the edit

一行命令接入 Claude Code——插件会注册一个 PostToolUse 钩子，在每次 Edit/Write 后运行 npx -y sparda-mcp gate --hook，因此移除防护的修改会在生效前被捕获。

重要

路由编译验证——亲自复现。 SPARDA 可将真正庞大的开源项目编译为行为图，不会发生崩溃，每个项目只需约 1–2 秒：Next.js Dub（579 条路由）、NestJS Immich（281 条）、MedusaJS（477 条）。它原生解析深层依赖注入、外部控制器和 Next.js 处理器。运行一条命令即可克隆这些项目，并在你的机器上重新测量：

node bench/repro.mjs        # → bench/route-proof.json

先说明实情：_编译_路由是解析器的结果（上面的数字）；_证明_它安全则是针对每个仓库的独立判定——而大多数真实应用的结果都是 NOT_PROVEN，这才是实际情况，并不代表失败。（我们的完整 25 个仓库压力测试语料库编译了 3,565 条路由，速度约为每秒 150 条路由；这项测试需要先检出该语料库。）

行为图带来的能力——100% 本地运行、确定性、4 个精确锁定的依赖、无需 API 密钥：

Command	What it does
prove	一次操作即可获得完整的信任判定 — 证明 + 覆盖率 + 前提检查 + 可分享的印章（--json / --markdown）
apocalypse	证明部署安全 — 任何防护、 invariant、事务或聚合边界都无法被破坏（SARIF + CI 门禁）
heal	自我修复，且有证明 — Copilot Autofix 缺少的门禁：只有当重放结果匹配、verify 仍然通过，且 apocalypse 未发现新风险或防护缺失时，修复才会交付。无论是谁编写修复，都由机器来判定。
badge	可分享的产物 — 独立完整的 SVG 徽章 + README 代码片段（判定 · 覆盖率 · 路由）
dossier	公开报告 — 一个独立完整的 HTML 页面：判定、风险，以及 SPARDA 自身的盲点
ubg	将代码库编译为行为图（原生支持 Express · FastAPI · Flask · Next.js · NestJS · Medusa；通过 OpenAPI 支持任何技术栈）
timeless	时间旅行 — 记录生产请求，逐字节重放，并将 bug 导出为测试
mirror	执行图 — 无需框架和源代码，通过 HTTP 提供编译后的行为
init / dev	运行时，可选 — 将行为图作为实时 MCP 服务提供给 AI 客户端（+ Twin、Immune、Evolution）

证明器才是产品。MCP 服务只是行为图的一种_输出_，并非重点 — SPARDA 会编译整个系统的行为，然后进行证明、重放、修复，并（可选地）提供服务。

术语说明： SBIR 是规范（格式，类似“JSON”）；UBG 是编译后的图本身（产物，ubg.json）。MCP 服务只是行为图的一种_输出_，并非产品。

可选：向 AI 客户端公开图（MCP 运行时）

除了证明，SPARDA 还能将正在运行的应用变成一个实时 MCP 服务——让图可执行，并具备写入安全机制和免疫层。此功能为可选项，与上文的证明器相互独立。

1. 扫描并注入——在应用目录中运行一次：

   npx sparda-mcp init
   

   SPARDA 会解析你的路由（AST），生成带标记的 /mcp 路由器，将其注入 应用（并创建备份），然后写入 sparda.json。每个步骤都可撤销。

2. 启动应用，然后启动桥接程序：

   npx sparda-mcp dev
   

3. 连接客户端。 init 会打印一段可直接粘贴到 claude_desktop_config.json 的配置，其中已填入应用名称和路径：

   {
     "mcpServers": {
       "your-app": {
         "command": "npx",
         "args": ["sparda-mcp", "dev"],
         "cwd": "/absolute/path/to/your-app"
       }
     }
   }
   

   Claude Code 会连接到同一个桥接程序。就这样——你的运行中应用现在已成为一组 MCP 工具，可供 AI 调用。

试用独立演示

无需修改代码库，即可立即查看 SPARDA 的运行效果：

npx sparda-mcp demo

这会在临时文件夹中的内置演示应用上运行完整的 MCP 生命周期（检测 → 解析 → 生成 → 注入 → 移除），耗时约 10 秒。要运行编译器本身，可在任意 Express/FastAPI 应用上先运行 npx sparda-mcp ubg，然后运行 apocalypse。

黑匣子报告

SPARDA 被设计为本地有机体。要查看它记住了什么，以及回收了多少计算资源：

npx sparda-mcp report

这会打印一个终端仪表板，汇总你公开的工具、写入授权、证明日志中的决策，以及已结晶的复合工具。

要在 .sparda/report.html 写入一份独立、可离线使用的 HTML 仪表板，请追加 --html 标志：

npx sparda-mcp report --html

要输出原始 JSON 以供集成：

npx sparda-mcp report --json

部署证明：Apocalypse

SPARDA 的行为图是对系统的形式化模型。你无需等待运行时故障，也不必依赖静态分析的主观判断，即可在部署前静态证明后端的安全性：

npx sparda-mcp apocalypse

此命令会读取编译后的 .sparda/ubg.json（运行时完全不解析源代码），并验证五项静态正确性义务：

• 无防护的变更（严重）：标记任何未经过安全 guard 的变更路径。
• 非原子聚合写入（高）：当 API 在单个事务范围之外写入同一一致性域（聚合）中的多个表时发出标记。
• 未验证的受约束写入（中）：标记写入带有已声明不变量（CHECK、NOT NULL、UNIQUE）的列，却未事先进行验证（Zod/Pydantic）。这些不变量从你的 .sql DDL 或 schema.prisma 中解析，也包括 Prisma 枚举。
• 不可逆的可观察副作用（高）：标记与状态写入同时发生的进程外操作（如 Stripe 扣款），但不存在结构化补偿路径（如 catch-refund）的情况。
• 绕过聚合成员（信息）：标记直接变更成员表、而未通过聚合根进行的情况。

要将当前图保存为安全基线：

npx sparda-mcp apocalypse --save-baseline

后续运行会将候选图与此基线进行差异比较，以检测回归风险：

• 删除任何安全 guard（严重）。
• 删除数据库 SQL 不变量（高）。
• API 影响范围扩大（中）。

如果发现任何严重或高风险问题，apocalypse 会以非零代码退出，以阻止 CI 流水线继续运行。

只需在工作流中添加一步——问题结果会显示在 GitHub Security 选项卡中（SARIF）：

- uses: zakariagharzouli/sparda@main
  with:
    sarif: 'true'

时间旅行：Timeless

每个生产请求在其副作用之间都是确定性的——编译器确切知道非确定性所在的位置（db、http、clock、random、uuid：图中的副作用节点）。Timeless 只记录这些位置（每个请求几 KB），并使用来自录制内容的虚拟化数据库、webhook 和时钟，针对当前代码以逐字节完全相同的方式重放请求：

npx sparda-mcp timeless                # list recorded flights
npx sparda-mcp timeless replay <id>    # re-fly it — byte-identical or loud divergence
npx sparda-mcp timeless export <id>    # the production bug is now a vitest test

在应用中只需两行代码（ESM）即可进行录制，并内置确定性采样和 GDPR 脱敏：

import { getFlightBox } from 'sparda-mcp/src/flight/box.js';
const box = getFlightBox(); box.arm();
app.use(box.middleware({ sample: 100 }));   // 1 request in 100; passwords/tokens redacted by default
const db = box.wrapClient(pgPool);           // your query client, tapped

这是别人都没有的闭环：生产环境 Bug → 录制的飞行记录 → 失败测试 → AI 编写修复 → apocalypse 证明修复不会破坏任何保护条件、不变量或事务 → 部署。 重放以请求为单位（捕获并发竞态不在 v1 范围内——这一点明确说明，不会隐瞒）。

自愈，且有证明：sparda heal

将上述闭环化为一个操作——由机器判断修复是否合格，无论修复由谁编写：

npx sparda-mcp heal <flightId>                       # diagnose + write the fix brief
# ...apply the fix (a human, or --agent "your-ai-cli")...
npx sparda-mcp heal <flightId> --check --expect '{"status":404}'

任务说明直接从图中生成——它会提供处理程序的 file:line、修复不得扩展的能力，以及不得移除的保护条件。然后，门禁——也就是实际产品——会同时从三个维度验证修复：

1. 行为——对录制飞行记录进行宽松重放（使用相同的确定性输入），现在会产生预期响应，而不是录制下来的 Bug。修复可以重新表述查询（采集点会重新标记，允许这样做）；但不得更改副作用的顺序或类型。
2. 编译器定律——verify 仍然通过：图依然健全且具有确定性。
3. 无回归——apocalypse 将修复前冻结的图与修复后的图进行差异比较：没有新增严重/高危问题，没有移除保护条件，也没有扩大影响范围。

✓ HEALED & PROVEN — same recorded inputs, correct output, zero law broken, zero protection lost. Ship it.

门禁在正反两方面都诚实：未修复的 Bug，或暗中丢弃保护条件的“修复”，都会让门禁保持关闭（退出码为 1）。这就是能够编写看似合理代码的 AI 与能够证明代码正确的系统之间的区别——这是 Agent 时代缺失的信任层。

地球上的任何后端：OpenAPI 降级

SPARDA 原生解析 Express、FastAPI 和 Next.js——而其他所有技术栈都可以通过业界已有共识的格式接入。Go、Java、Rails、Laravel、.NET：只要有 OpenAPI 规范，就能编译。

npx sparda-mcp ubg --openapi openapi.json

安全方案会变成用于门控的 guard 节点，响应模式会变成带类型的返回值，声明的请求体会计为已验证输入。将规范与 .sql 或 schema.prisma 文件配合使用，完整的状态层——不变量、聚合、状态机——就能根据声明的事实补全。（v1 支持 JSON 规范；我们拒绝在零依赖的情况下半吊子地解析 YAML。）

Mirror VM：删除框架，应用仍能响应

图不只是示意图——它可以执行：

npx sparda-mcp mirror

MIRROR — the graph is serving. 3 entrypoint(s) on http://127.0.0.1:4477
  GET    /orders/{orderId}  → {amount, id, status}
  POST   /orders  🔒 bearerAuth  → {amount, id, status}

没有 Express。没有 FastAPI。没有源代码——只有 ubg.json 响应 HTTP：保护条件会真正拒绝请求（401），响应会按编译后的返回模式呈现，未知路径会返回 404 并附带完整路由表。前端团队可以针对尚未部署——甚至尚未编写——的后端进行开发（将 mirror 指向 OpenAPI 规范即可）。每个响应都会携带 x-sparda-mirror: true；mirror 只提供已声明的行为，绝不会编造业务值。

要撤销所有更改：npx sparda-mcp remove 会逐字节恢复你的代码。

愿景——每句话都有 CI 中的测试作为依据

1. 三分钟，一条命令。 AST 扫描、路由器生成、可逆注入——无需配置。
2. 免费试用，免费离开。 npx sparda-mcp remove 会逐字节还原你的代码（已在 JS、TS、Python，甚至 Windows CRLF 文件上测试）。不留痕迹，不会被锁定。
3. 未经你同意，AI 无法写入。 所有 POST/PUT/DELETE 默认禁用；你可以逐个工具启用，且每次重新运行后都会保留你的选择。
4. 你的应用会保护自己。 某个路由连续失败 3 次后就会被隔离——AI 无法反复请求已损坏的生产环境。延迟异常也会被标记。无需 LLM。
5. 任何数据都不会离开你的设备。 不向我们发送遥测数据，无云服务，本地密钥认证，仅有 4 个精确锁定版本的依赖项。
6. 学到的内容永不丢失。 诊断信息、描述、设置——与 git 一同进行版本管理，每次重新初始化后都会保留。

我们不承诺的内容：docs/SECURITY.md 中如实说明了限制。

工作原理

1. npx sparda-mcp init 会解析你的代码库（AST）、提取每个路由，并在应用中注入一个带有标记的小型路由器（/mcp）——可通过 npx sparda-mcp remove 完全撤销。
2. 工具调用在你的应用实时进程中运行——使用已预热的数据库连接池、真实的认证链和真实数据。SPARDA 不会增加任何基础设施：计算由你的主机进程提供，智能由 AI 客户端自己的模型（MCP 采样）提供，存储则来自 sparda.json 和 git。
3. 写入工具（POST/PUT/DELETE）默认禁用。你可以在 sparda.json 中逐个工具选择启用——每次重新运行后都会保留你的选择。
4. 可疑的文档字符串会先经过清理，再传给 AI（防范提示词注入）。
5. npx sparda-mcp doctor --app 会审计你的代码库是否存在偏差：检测过时的工具（AI 看到幽灵工具）、未同步的路由、通过指纹检测的架构漂移，以及僵尸配置。高严重性问题会触发非零退出代码，供 CI 流水线使用。
6. npx sparda-mcp seed export/import 可以安全地打包并分享应用的“基因组”（语义记忆、工作流、抗体），在不同环境或相似技术栈之间传递免疫记忆，且不会泄露数据。
7. npx sparda-mcp twin 会在原端口启动一个安全的后端模拟服务器。它根据已学习的示例（观察到的响应结构和模拟数据）处理 GET 调用，并返回模拟的 202 写入响应，全程不会触及真实数据库或生产 API。运行 npx sparda-mcp twin --learn 可学习示例。
8. npx sparda-mcp grammar 会映射有效工具调用序列的图（观察到的调用链和候选假设），以防止 LLM 臆造路由。
9. npx sparda-mcp evolve 会变异候选调用链，并在内存中通过模拟服务器对其进行测试，将成功的调用链提升为进化后的工作流建议。

SPARDA 能为你的 AI 提供什么

操作，而不只是读取

每个路由都会变成一个针对实时进程运行的工具——使用真实的认证、真实的数据和已预热的连接。只需调用一次 sparda_get_context，AI 就能获取完整的实时状态：已启用的工具、建议的工作流、运行时遥测数据、隔离状态和免疫记忆——让每次会话都能从上次停止的地方继续。

写入安全：未经你同意，AI 无法写入

• 写入操作（POST/PUT/DELETE）默认禁用。在 sparda.json 中逐个工具启用；每次重新初始化后都会保留你的选择。
• 启用的写入操作不会在首次调用时执行。SPARDA 会返回一个 awaiting_confirmation 信封，其中包含一次性令牌和操作预览——只有明确确认后才会提交。
• 如果你的客户端支持 MCP elicitation，确认提示会直接出现在AI 自己的界面中。
• 写入后验证：每次成功写入后，都会重新读取同一资源，因此 AI 和你都能看到实际效果，而不是乐观的猜测。

你的应用会自我防护——热路径上零大模型调用

• 隔离。 某个工具连续 3 次返回 5xx 后，就会被隔离：后续调用会收到带有原因和重试延迟的 503，而不是继续冲击故障路由。冷却一段时间后，它会半开放，允许进行一次探测。
• 延迟和异常标记。 路由器会学习每条路由的基线，并通过几行数学计算在本地标记偏差。
• 自适应诊断，仅在意外情况发生时触发。 出现真正的新故障时，系统会唤醒 AI 客户端自己的模型进行一次诊断；诊断结果会作为“抗体”缓存到 sparda.json 中，因此之后遇到同样的故障不会消耗任何 token。克隆你的代码不会克隆它的免疫记忆。

免费智能层，无需 API 密钥

首次连接时，AI 客户端自己的模型（通过 MCP 采样）会将原始路由改写为业务语言的工具描述，并提出多步骤工作流——这些内容会缓存到 sparda.json 中，并作为 MCP 提示词公开。无需配置，也无需付费。

用得越多，成本越低

• 响应复用。 当读取操作持续返回相同答案时，SPARDA 会直接从内存中提供下一次相同调用的结果，无需触及你的宿主应用。仅适用于读取操作；写入操作始终会访问宿主应用。
• 复用率仪表盘。 GET /mcp/stats 会统计有多少调用由 SPARDA 自身的知识作答，以及有多少调用访问了宿主路由。第一天读数为 0%，并会随着使用逐渐升高——它只是一个衡量指标，而非承诺。

无人编写的工具——Labs，选择启用，默认关闭

在 sparda.json 中设置 "labs": { "recordSequences": true } 即可启用。随后，SPARDA 会注意到一个工具的输出何时作为下一个工具的输入，并记录该电路——仅记录结构（工具名称、参数名称、次数），绝不记录你的数据。只读 电路在出现足够多次后会结晶为组合工具，并在会话期间公布：一次调用即可运行整条链，自动将每一步的真实响应作为下一步的输入。写入路由绝不会被吸收——每次调用都必须经过确认。

动态上下文和遥测

GET /mcp/stats（每个工具的调用次数／错误数、工具“纯度”、隔离状态）和 GET /mcp/events（错误、延迟异常、缓存的诊断结果）会准确展示你的应用正在执行的操作，并以实时通知的形式呈现给 AI。

专为 AI 客户端打造：内置 Skill

SPARDA 附带一项 Agent Skill（SKILL.md），可教会任何兼容的 AI 客户端如何充分发挥 SPARDA 服务的全部潜力——先调用 sparda_get_context，利用响应复用，遵守隔离状态，优先使用已结晶的电路而非重新遍历整条链，并遵循两阶段写入确认协议。每个项目的实时工具列表始终会在运行时从 sparda_get_context 获取，因此这些指导永不过时。

支持的框架

• Next.js App Router（13/14/15）——基于文件的注入。SPARDA 会创建一个兜底路由处理程序。它可以原生解析包装过的处理程序（export const POST = withAuth(h)）和深层 effect 链。
• NestJS——基于 AST 的路由注入。可深度解析多跳依赖注入（Controller → Service → Repository）、继承的 DI，以及 baseUrl／paths 导入。支持 Prisma、TypeORM 和 Kysely。
• Express 4/5（JS/TS，ESM/CJS）——基于 AST 的路由注入。可深度解析外部控制器、Mongoose 模式和 barrel 再导出。使用动态树扫描查找非标准入口点（bootstrap.ts 等）。
• MedusaJS——原生通过 AST 解析复杂的电商路由。
• 地球上的任何后端（Go、Java、Rails、Laravel）——可根据 OpenAPI 3.x 规范轻松编译。
• FastAPI（Python >= 3.9）——基于 AST 的路由注入。

安全态势（如实说明）

• 4 个运行时依赖，均固定到精确版本。
• 动态本地密钥解析。 生成的路由器不包含任何硬编码密钥。它会在运行时从环境变量 SPARDA_LOCAL_KEY 或本地的 git 忽略文件 .sparda/key 中解析授权密钥；如果两者都不存在，则会采取失败关闭策略（503）。对于自定义生产或暂存环境，你可以通过在环境中公开 SPARDA_LOCAL_KEY 来覆盖此行为。
• 每次调用路由器时都使用本地密钥；防止自引用循环；超时时间为 30s；输出截断至 8 KB。
• 基于 AST 位置注入，带有备份并在注入后重新解析；npx sparda-mcp remove 会留下干净的 git diff。
• 持久化不包含任何值：SPARDA 只记录结构（工具名称、字段名称、指纹），绝不记录你的负载。

完整威胁模型和已知不足：docs/SECURITY.md。

文档

• docs/ARCHITECTURE.md — 介绍 init、注入的路由器和桥接器如何协同工作，以及 sparda.json 架构。
• docs/SECURITY.md — 威胁模型、防御措施和如实说明的已知不足。
• docs/TESTING.md — 说明如何在 CI 中确保上述承诺切实兑现。
• docs/ERRORS.md — 错误知识库。

开源核心之外

SPARDA 免费使用，包括用于生产环境（参见许可证）。团队规模的功能—— 精细到个人的访问策略以及经过签名、防篡改的审计日志——计划在未来的付费层级中推出。开源核心本身已完整可用；这里没有任何功能被限制来诱导你升级付费。

许可证

Business Source License 1.1 — 可免费使用，包括用于生产环境。 你不得转售 SPARDA，也不得将其作为竞争性的商业服务提供。 每个版本都会在发布四年后转换为 Apache 2.0。

作者：Residual Labs