zhangyy0423/veripipe

veripipe

执簿判官 · veripipe — 凭簿断案，无据不判 · evidence in, false positives out

一个面向测试 Web/HTTP 产品的 AI 智能体的反误报验证流水线。

中文名「执簿判官」——凭簿断案，无据不判。

AI 智能体擅长发现候选缺陷，却不擅长证明它们。
若不加约束，它们会为实际上正确的行为提交自信且格式规范的报告，
而对这些报告进行分诊的成本往往超过真实缺陷本身。
veripipe 只有在结构化、可复现的证据通过一条故障关闭式（fail-closed）判定链时，才会放行一个候选发现。

核心使用 Python 编写，仅有一个运行时依赖 —— PyYAML，用于加载语义/代码映射 —— 并附带一个清单驱动的安装器和一个零依赖的 MCP 服务器，因此任何 MCP 宿主都可以驱动它。

适用对象： 那些让 AI 智能体针对 Web/HTTP 产品运行，且厌倦了对自信但错误的缺陷报告进行分诊的团队。

一条命令即可试用（离线、无需安装、无需产品）：

python3 examples/demo.py

一份契约，三次智能体运行 —— 一次真实成功、一次虚假的“完成”，以及一次无依据的断言 —— 只有经过机器验证的失败才会被归档。

它解决的问题

原始智能体循环往往会以三种方式失败：

1. 文本匹配式判定器。 “页面显示错误”并不是缺陷。比较智能体的文字表述或渲染文本只会产生自信的胡言乱语。
2. 不可复现的一次性结果。 无法复现的发现不是发现。
3. LLM 自我确认。 问 LLM“这是缺陷吗？”，它会很乐意地赞同自己。

veripipe 针对上述每一点都有具体机制来应对，接下来将逐一描述。

核心概念

- L1–L4 判定器模型。 发现按其判定器的强度分级。只有 L1–L3（结构性 / 终态 / 复现证据）可以被归档。L4（建议 / 启发式）被隔离，且永远不能单独成为报告。
- 结构化终态判定器（L2）。 判定器比较来自语义映射的机器可比较终态，而绝不比较智能体输出文本。缺失 machine_check、未知断言类型、缺失观测字段或基于文本的检查都会返回 inconclusive —— 它们不是失败。
- 非对称 LLM 否决权。 当模型处于循环中时，它只能返回 allow、veto 或 request-more-evidence。它可以否决一个发现，但永远不能确认一个发现。 确认始终来自确定性证据。
- 处处故障关闭。 缺失遥测、契约漂移、未知判定、提供方错误以及预算耗尽，都会归结为“不归档”，而不是“无论如何都归档”。
- SQLite 账本。 案例、批次和命中都会被持久化，因此运行事后可审计、可查询。
- 受保护的两阶段发布。 离线试运行将发布意图写入 JSONL 队列。它本身绝不会推送到外部跟踪器或 wiki。
- 可插拔执行器。 内置 mock、playwright、http 和 l1-fuzz
执行器，外加一个通用的 external 执行器，让产品可以接入任意传输方式——它只需通过标准 CLI 返回结构化的 observed_state，而无需向中立核心添加产品代码。
- GitHub 发布技能。 publish-github 将机器验证的发现转化为 GitHub Discussion/Issue 草稿：默认 dry-run、仅限已验证内容、去重，每份草稿都带有自动披露页脚。参见
docs/publish-github.md。
- 契约上的产品中立性。 核心不导入任何产品驱动，也不包含任何产品名称或标识符；CI 门禁会 grep 检查泄漏，并针对中立的 sample fixture 运行引擎。

架构

product repo (private)                     veripipe (this repo, public)
┌────────────────────────────────┐        ┌────────────────────────────────────┐
│ adapter.config.json            │        │ pipeline_v2/      product-neutral   │
│ semantic-map.yaml              │  ───▶  │   orchestrator, oracles L1–L3,      │
│ Playwright specs / web app     │ signals│   ledger, funnel, publishing, …     │
│ runtime URLs, auth (never here)│        │ pipeline_v2_mcp/  MCP stdio server  │
└────────────────────────────────┘        │ scripts/installer manifest installer│
└────────────────────────────────────┘

产品仓库提供运行时信号、适配器配置和发布命令包装器。本仓库提供中立引擎、MCP 接口、安装器和测试。产品源代码、内部提示词、内网地址、项目标识符、运行日志、队列载荷、凭据以及未经审查的产品知识绝不存放在此处。

要求

- Python 3.9+。核心需要 PyYAML（其唯一的运行时依赖）；MCP 服务器仅使用标准库。
- 可选，仅用于真实浏览器运行：产品 仓库中的 Node.js + Playwright。veripipe 会调用产品的 Playwright 安装；它不捆绑浏览器。

安装

从源码安装（未发布时推荐）：

git clone  veripipe
cd veripipe
The core is importable directly from the scripts root:
export PYTHONPATH="$PWD/shared-skills/pipeline-v2/scripts:$PYTHONPATH"
python3 -m pipeline_v2.orchestrator --help

从 GitHub 安装（无需 PyPI 账号）：

pip install "git+https://github.com/zhangyy0423/veripipe"

或者，一旦发布到 PyPI：

pip install veripipe          # installs pipeline_v2 + pipeline_v2_mcp (pulls PyYAML)

快速开始

以下所有内容都是离线且无副作用的（--dry-run 会将意图写入队列文件，而不是推送到任何地方）。

在中立 fixture 上约 60 秒了解该方法（无产品、无网络）：

python3 examples/demo.py

它通过三次 agent 运行走完一个契约——一次真正的成功、一次虚假的“完成”，
以及一项无依据的声明——并表明只有经过机器验证的失败才会被归档。推理过程见 docs/methodology.md。

针对模拟执行器运行编排器：

python3 -m pipeline_v2.orchestrator \
--ledger /tmp/pipeline-v2.sqlite \
--queue /tmp/pipeline-v2-queue.jsonl \
--brief /tmp/pipeline-v2-brief.md

由适配器驱动的 Playwright 试运行（解析存储的 JSON 报告器夹具，无需产品服务）：

python3 -m pipeline_v2.orchestrator \
--ledger /tmp/pipeline-v2-adapter.sqlite \
--queue /tmp/pipeline-v2-adapter-queue.jsonl \
--brief /tmp/pipeline-v2-adapter-brief.md \
--executor playwright \
--adapter products//adapter.config.json \
--product-cwd /path/to/product \
--dry-run \
--report tests/fixtures/pipeline_v2/playwright/failure-report.json

在不写入任何账本/队列文件的情况下，对适配器的运行时先决条件进行预检：

python3 -m pipeline_v2.orchestrator \
--preflight \
--executor playwright \
--adapter products//adapter.config.json \
--product-cwd /path/to/product

除非同时传入 --enable-model-routing 和绝对路径的 --model-budget-overlay JSON 路径，否则模型路由保持禁用。该覆盖文件定义每批次的调用/令牌/成本限制，且不得包含提供商凭据。

MCP 服务器

任何 MCP 主机（Ducc、Claude Code、Codex 或你自己的客户端）都可以通过 stdio 驱动该流水线。该服务器是零依赖的——它直接实现 JSON-RPC 2.0 stdio 传输，因此凡是核心能运行的地方它都能运行。

python3 -m pipeline_v2_mcp

- 服务器名称：veripipe-pipeline-v2。
- 协议版本：2025-06-18（默认）、2025-03-26、2024-11-05。
- 传输方式：在 stdin/stdout 上使用换行分隔的 JSON-RPC；日志输出到 stderr。

工具

| 工具 | 用途 | 默认安全设置 |
| --- | --- | --- |
| preflight | 检查适配器的运行时先决条件 | 只读 |
| run_batch | 运行一个验证批次 | dry_run=true |
| run_loop | 运行多迭代循环运行器 | dry_run=true |
| knowledge_audit | 审计导出的知识以发现缺口/漂移 | 只读 |
| knowledge_export | 导出引擎知识（不含产品数据） | 只读 |
| code_map_validate | 验证代码映射，遇到漂移则故障关闭 | 只读 |
| change_impact | 根据代码映射计算变更影响 | 只读 |
| query_ledger | 从账本查询批次/用例/命中 | 只读 |

run_batch 和 run_loop 默认 dry_run=true；发布需要显式选择退出，并且仍然只写入本地队列。如果账本文件尚不存在，query_ledger 会拒绝运行——它绝不会作为副作用创建空数据库。

产品适配器与安装器

产品通过提供适配器（adapter.config.json、semantic-map.yaml、规范白名单）以及可选的代理薄壳来接入。由清单驱动的安装器会将产品的薄壳复制到产品
工作目录，并通过 SHA-256 跟踪每个受管文件，因此升级和
卸载是安全的：

python3 -m scripts.installer.installer --product  --product-cwd /path/to/product
python3 -m scripts.installer.installer doctor --product  --product-cwd /path/to/product

安装器是故障关闭的：它拒绝路径遍历和符号链接逃逸，
拒绝触碰它自己的同级检出，保护本地已修改的文件
（覆盖需要 --force），只删除它在清单中记录的文件，并且
绝不删除未受管的运行时证据。

如今的 Agent 薄壳面向 Claude Code（.claude/commands、
.claude/skills）和 Codex（.codex/skills）。一个 Ducc / dsh 薄壳
镜像了相同的对称设计（.dsh/skills）。有关适配器布局和宿主映射，
请参见 docs/adapters.md，
有关将技能和 MCP 服务器接入 dsh 宿主，请参见 docs/dsh-plugin.md。

引擎知识会传播；产品知识不会。 code_map、
knowledge_audit 和 knowledge_export 能力是中立
引擎的一部分，随框架一起移动。任何产品特定的图、映射或
知识内容都在产品仓库中生成，并保持私有。

文档

- docs/methodology.md — 整个项目所基于的
反误报方法（可独立阅读）。
- docs/adoption.md — 试用它，将其接入宿主，让它指向你的产品。
- docs/adapters.md — 适配器布局、宿主映射、
执行器矩阵，以及自带传输模式。
- docs/publish-github.md — 将机器验证的
发现提交到 GitHub Discussions/Issues（先试运行，仅限已验证项）。
- docs/github-action.md — 一个在 CI 中汇总一次运行的复合 Action。
- docs/testing.md — 门禁套件和产品绑定的
测试留出策略。
- docs/dsh-plugin.md — 将技能和 MCP
服务器接入 dsh 宿主。

测试与 CI

所有门禁均离线运行。PyYAML 是唯一的第三方依赖（它加载
语义/代码映射）；其余一切都来自标准库：

bash scripts/ci/run-gates.sh

门禁：bash-syntax、python-syntax、secret-scan、contract（Playwright
试运行 + MCP 服务器冒烟测试 + 产品中立性扫描），以及 unit
（安装器 + 引擎 + MCP 服务器套件）。少数产品绑定的套件
被有意排除在这个公共仓库之外；有关策略，请参见
docs/testing.md。

安全与保密

本仓库有意不包含产品源代码、内部提示词、
内网地址、项目标识符、运行日志、队列载荷和
凭据。secret-scan 门禁和产品中立性门禁在 CI 中强制执行
这一边界。内部知识应放在单独的私有知识
具有自身干净历史的仓库。

许可证

MIT © 2026 veripipe 贡献者。