Weavatrix Quality

io.github.Weavatrix由 GitHub 账号 Weavatrix 发布v0.1.0-alpha.5更新于 Nov 3, 2026

Revision-bound quality planning, execution, evidence, proof, and Playwright authoring.

已验证STDIO仅桌面浏览器自动化开发者工具

概览

AI 生成的概览

Weavatrix Quality 把 OpenSpec 变更与 Git 差异转化为绑定同一版本的测试证明，并向编码助手提供规划、执行、验证与证据工具。

可以做什么
  • 查看某个变更的义务清单以及与现有证明之间的缺口，不执行任何测试
  • 运行最小范围的影响测试集并产出覆盖率证据
  • 读取状态与综合验证结论，并按 id 深入查看某条证明或发现
  • 在可选的编写配置下编写 Playwright 测试程序：草拟、校验、预览、提升、录制与修复
适用场景
当你希望助手判断某次代码改动是否仍受测试保护，并生成同一版本的证明，而不仅仅是跑一遍测试套件时使用。适合已有 OpenSpec 变更、Git 历史和现成测试运行器的仓库。
运行要求
通过 npx 运行 npm 包，以 stdio 在本地启动，并在命令行传入仓库路径。需要 Node.js 和 Git 仓库，README 的 CI 示例使用 Node 24。浏览器预览需要在目标仓库中安装 Playwright。未声明任何 API 密钥或环境变量。
安装前请注意
项目处于 alpha 阶段，API 不稳定。init、run、spec seal 等命令会写入仓库，编写配置还能提升和修复测试程序。若配置中没有测试绑定，即使测试全绿也仍为未证明状态，因此结果取决于策略配置是否正确。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Weavatrix Quality，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

Weavatrix Quality (wvq)

[CI] [npm] [MCP] [MIT]

Know what your change can break — and whether it is still protected.

Weavatrix Quality (WVQ) turns OpenSpec intent + a Git change into revision-bound proof using your existing runners. The ordinary green path spends 0 runtime LLM tokens. Rust owns policy, selection, evidence, and proof; npm/JS is a typed boundary around the same binaries.

text
OpenSpec   → what must remain trueWeavatrix  → what changed and what it can affectRunners    → smallest safe protection setWVQ        → same-revision Proof + composite verdict
SurfacePackage
npm (primary)@weavatrix/wvq
MCP Registryio.github.Weavatrix/weavatrix-quality
crates.iowvq-cli · wvq-mcp · wvq-bench
Releasev0.1.0-alpha.5

Alpha 0.1.0-alpha.5. Useful first product loop (one plan → one execution → one report). Not the full v1 DoD — see CHANGELOG and ADR 0003.

Install

sh
# primary distribution (ships wvq + wvq-mcp + wvq-bench for 6 platforms)npm install --save-dev @weavatrix/[email protected]
# one-shot without adding a dependencynpx @weavatrix/[email protected] --help
# Rust binaries (alpha crates; API unstable)cargo install wvq-cli --version 0.1.0-alpha.5cargo install wvq-mcp --version 0.1.0-alpha.5cargo install wvq-bench --version 0.1.0-alpha.5

Unscoped wvq is blocked by npm name-similarity rules — always use @weavatrix/wvq.

5-minute quickstart

sh
cd your-repo
# 1) read-only discovery (never writes, never seals)npx @weavatrix/[email protected] doctor
# 2) write fail-closed policy (first time only)npx @weavatrix/[email protected] init
# 3) compile OpenSpec obligations for a change foldernpx @weavatrix/[email protected] spec validate --change current
# 4) run the smallest safe protection set (also builds measured coverage)npx @weavatrix/[email protected] run \  --change current \  --base origin/main \  --head HEAD \  --scope impacted \  --evidence-policy minimal# After a successful native coverage runner, Weavatrix `coverage_map` reads:#   .weavatrix/coverage/lcov.info# Quality does not invent a second stack. Playwright is last-resort JS only.
# 5) read-only composite verdict from stored evidencenpx @weavatrix/[email protected] verify --change current

Need bindings before proofs can seal? Start from .weavatrix-quality/config.yaml and the examples.

CLI cookbook

All commands take --repo <path> (default: .). Prefer absolute paths in CI.

Day-to-day cycle

sh
alias wvq='npx @weavatrix/[email protected]'
wvq doctorwvq plan --change checkout-fixwvq select --change checkout-fix --base origin/main --head WORKTREEwvq run --change checkout-fix --base origin/main --head WORKTREE --scope impactedwvq statuswvq verify --change checkout-fixwvq explain <proof-or-finding-id>

Spec / seal / debt

sh
wvq spec validate --change checkout-fixwvq spec seal --change checkout-fix          # fail-closed; needs valid obligationswvq debt --change checkout-fix --base origin/main --head HEADwvq baseline --change checkout-fix --decision observed_only   # CLI-only, not MCP

Observe-only CI (Stage A)

sh
# facts stay honest (UNPROVEN / NOT_ENOUGH_EVIDENCE), process exit stays 0wvq verify --change checkout-fix --observe-only true

Browser record → promote later via MCP/Studio

sh
wvq record --change checkout-fix --route /checkoutwvq ingest-journal --file .weavatrix-quality/journals/session.jsonwvq ingest-cassette --file captures/checkout.har --origin https://app.example.test

Shadow selected-vs-full (bench)

sh
wvq bench --repo . --change checkout-fix --base origin/main --head WORKTREE# or: npx @weavatrix/[email protected] bench --repo . ...

Exit codes

CodeMeaning
0success / observe-only (even when verdict is unresolved)
1unresolved evidence / ordinary failure
2blocking CONTRADICTED verify

Full CLI surface: wvq --help. Deep product rules live in docs/STATUS.md.

MCP cookbook

WVQ ships as an mcport MCP host. Default profile = 7 tools, no shell, large artifacts as handles only.

Cursor (mcp.json)

json
{  "mcpServers": {    "weavatrix-quality": {      "command": "npx",      "args": [        "-y",        "@weavatrix/[email protected]",        "mcp",        "--repo",        "C:/path/to/your-repo"      ]    }  }}

Claude Desktop

json
{  "mcpServers": {    "weavatrix-quality": {      "command": "npx",      "args": ["-y", "@weavatrix/[email protected]", "mcp", "--repo", "/Users/you/src/app"]    }  }}

Default tools (coding agents)

text
quality_context   quality_plan   quality_run   quality_statusquality_verify    quality_explain   quality_evidence

Example agent workflow:

  1. quality_context — what obligations exist for this change
  2. quality_plan — gaps vs existing proofs (no execution)
  3. quality_run — execute impacted protection and publish .weavatrix/coverage/lcov.info for Weavatrix coverage_map
  4. quality_verify — composite verdict
  5. quality_explain / quality_evidence — drill into a handle or id

Authoring profile (TestProgram draft → preview → promote)

sh
npx @weavatrix/[email protected] mcp --repo . \  --profile authoring \  --change checkout-fix \  --base origin/main \  --head WORKTREE
text
quality_test_draft    quality_test_validate   quality_test_previewquality_test_promote  quality_test_record     quality_test_heal

doctor / init / baseline stay CLI-only so agents cannot treat discovery or an observed baseline as authority.

More configs and JSON-RPC samples: examples/mcp/.

JavaScript library cookbook

sh
npm install --save-dev @weavatrix/[email protected]

Plan → run → verify

js
import { WvqClient } from '@weavatrix/wvq'
const wvq = new WvqClient({ repo: process.cwd() })
const plan = await wvq.plan({ change: 'checkout-fix' })console.log(plan.obligations, plan.gaps)
const run = await wvq.run({  change: 'checkout-fix',  base: 'origin/main',  head: 'WORKTREE',  scope: 'impacted',  evidencePolicy: 'minimal',})console.log(run.run_id, run.outcome, run.scope_reason)
const verify = await wvq.verify({ change: 'checkout-fix' })console.log(verify.state, verify.quality.proof, verify.base, verify.head)
if (verify.blocking) {  for (const reason of verify.quality.blocking_reasons) {    console.error(reason.code, reason.detail)  }  process.exit(2)}

Spec / select / debt / explain

js
await wvq.specValidate({ change: 'checkout-fix' })const selected = await wvq.select({  change: 'checkout-fix',  base: 'origin/main',  head: 'HEAD',})console.log(selected.selected, selected.uncovered_mandatory)
const debt = await wvq.debt({  change: 'checkout-fix',  base: 'origin/main',  head: 'HEAD',})console.log({ new: debt.new, fixed: debt.fixed, returned: debt.returned })
const detail = await wvq.explain(verify.proofs[0]?.id)console.log(detail.summary, detail.provenance)

MCP client from Node (default + authoring)

js
import { WvqMcpClient } from '@weavatrix/wvq/mcp'
const mcp = new WvqMcpClient({  repo: process.cwd(),  profile: 'default',  change: 'checkout-fix',})const status = await mcp.call('quality_status', { change: 'checkout-fix' })const verdict = await mcp.call('quality_verify', { change: 'checkout-fix' })
const authoring = new WvqMcpClient({  repo: process.cwd(),  profile: 'authoring',  change: 'checkout-fix',  base: 'origin/main',  head: 'WORKTREE',})const draft = await authoring.draft()const validated = await authoring.validate(candidateProgram)const preview = await authoring.preview(validated.program, {  screenshot: true,  trace: true,})if (preview.passed) {  await authoring.promote(preview.preview_id, validated.program)}

CI snippet (GitHub Actions)

yaml
- uses: actions/setup-node@v4  with:    node-version: 24- run: npx @weavatrix/[email protected] doctor- run: >    npx @weavatrix/[email protected] run    --change current --base origin/${{ github.base_ref }} --head HEAD    --scope impacted --evidence-policy minimal- run: npx @weavatrix/[email protected] verify --change current --observe-only true

Runnable copies: examples/js/ · examples/cli/.

Repository policy

.weavatrix-quality/config.yaml binds concrete tests to obligation IDs. A green suite without this mapping stays UNPROVEN.

yaml
quality_policy_v: 1
test_bindings:  - path: tests/permissions.spec.ts    runner: playwright    case: viewer cannot delete a widget    obligations: [permissions-delete]    cost: 10    flake_penalty: 0
browser:  base_url: http://127.0.0.1:3000  engine: chromium  headless: true  module_root: .

wvq init writes a fail-closed starter. This repo dogfoods change wvq-invariants — see examples/cli/dogfood.sh.

Browser preview needs Playwright in the target repo:

sh
npm install --save-dev playwrightnpx playwright install chromium

What WVQ is / is not

IsIs not
Spec-to-Proof over existing runnersA second test framework
Weavatrix-backed impact + selectionA browser engine (Playwright stays)
CLI + MCP + typed JS boundaryAn OpenSpec fork
0 LLM tokens on the green pathAutomatic silent oracle healing
Fail-closed on unknown schemasA single global “quality %”

Place in the ecosystem:

text
Weavatrix          UNDERSTAND   what exists in sourceWeavatrix Quality  PROVE        what must still be true after this changeWeavatrix Loom     COMPOSE      capabilities into ordinary Rust

Build from source

Requires Rust 1.89+.

sh
cargo test --workspace --lockedcargo clippy --workspace --all-targets --locked -- -D warnings

Docs map

DocUse when
examples/Copy-paste CLI / MCP / JS
CHANGELOGWhat alpha ships
docs/STATUS.mdMaturity matrix + next task
docs/adr/0003-…Alpha vs deferred v1
docs/CANONICAL-MASTER-SPEC.mdNormative product design

License

MIT. See LICENSE.

来源：README.md，提交 3e07414

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

3
  1. v0.1.0-alpha.5最新Sep 19, 2026
  2. v0.1.0-alpha.4Sep 19, 2026
  3. v0.1.0-alpha.3Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分