weavatrix-online

Weavatrix Online

在网络中传递仓库智能，同时不将你的仓库交给网络。

Weavatrix 生态中明确划定网络边界的产品。Core 和 Refactor 仍需分别安装。

Weavatrix Online 是一款采用 MIT 许可证的 MCP 连接器，可连接 Weavatrix Cloud 和兼容的客户自主管控端点。它在本地进行分析，生成可检查且不含源代码的负载，并要求精确的短时确认，才能将该负载发送到本机之外。

公开的 Online 配置提供 7 个 MCP 工具，用于端点发现、公告、恶意软件审查、架构合约和受控同步。本地 weavatrix-js 图引擎属于实现细节：它的工具不会重新导出，因此即使同时安装 Core、Refactor 和 Online，也不会在 Agent 的上下文中重复出现它们的工具目录。

安装或启动 Online 都不会触发同步。preview_sync 不会发出网络请求；sync_graph 只接受仍然有效且与同一仓库、目标位置、负载和图匹配的预览。

选择合适的 Weavatrix 软件包

产品	安装方式	边界
weavatrix	npm 或 Cargo	原生的本地优先 MCP 产品。两个软件包管理器分发的是同一个本地 Weavatrix 服务和引擎。
weavatrix-rust	Cargo	与协议无关的 Rust 仓库智能引擎，可用于库和命令行；不负责 MCP 传输。
weavatrix-refactor	npm 或 Cargo	仅提供原生扩展的事务式重构；内部使用 Rust 图引擎。
weavatrix-online	npm	可选网络扩展：通过内部本地图运行时提供不含源代码的 Cloud／可自托管工作流。

Online 目前在内部使用 JavaScript 图／运行时软件包：

weavatrix-online 0.3.4
  └─ weavatrix-js 0.3.x (internal; no Core tools re-exported)

它不会代理原生 weavatrix 可执行文件，不会导入 weavatrix-refactor，也不会复制任一引擎。如果图必须完全保留在本地，请使用 weavatrix。如果工作流涉及端点状态、远程管理的架构合约、公告刷新或明确的不含源代码同步，请使用 weavatrix-online。

安装和运行

Cursor、Codex、Claude 和 Grok 插件

此仓库现在包含一个可移植插件包 plugins/weavatrix-online，以及面向全部四个客户端的原生市场清单。该插件会启动固定版本的 npm 发布包，并附带一个可选的精简技能，其中每种 Online 方法都有一张按需加载的卡片。

codex plugin marketplace add Weavatrix/weavatrix-online --sparse .agents/plugins plugins/weavatrix-online
codex plugin add weavatrix-online@weavatrix-online

claude plugin marketplace add Weavatrix/weavatrix-online --sparse .claude-plugin plugins
claude plugin install weavatrix-online@weavatrix-online

grok plugin marketplace add Weavatrix/weavatrix-online

Cursor 可以从 ~/.cursor/plugins/local/weavatrix-online 在本地加载该插件包；公开市场发现功能需等到列表经过审核并获批后才会启用。

直接启动 MCP

无需全局安装，直接运行固定版本的发布包：

npx -y [email protected] C:\path\to\repository

此命令会启动一个 stdio MCP 服务。第一个位置参数是要分析的仓库。也可以显式指定已有的图：

npx -y [email protected] C:\graphs\repository\graph.json C:\path\to\repository

npm 软件包有意设计为可执行 MCP 产品；它不会宣称提供并不存在的 JavaScript 库入口点。

Codex

[mcp_servers.weavatrix_online]
command = "npx"
args = ["-y", "[email protected]", "C:\\path\\to\\repository"]

[mcp_servers.weavatrix_online.env]
WEAVATRIX_SYNC_URL = "https://app.weavatrix.com/api/v1/graphs/sync"
WEAVATRIX_SYNC_TOKEN = "load-from-runtime-secret-storage"

Claude Desktop

{
  "mcpServers": {
    "weavatrix-online": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "C:\\path\\to\\repository"
      ],
      "env": {
        "WEAVATRIX_SYNC_URL": "https://app.weavatrix.com/api/v1/graphs/sync",
        "WEAVATRIX_SYNC_TOKEN": "load-from-runtime-secret-storage"
      }
    }
  }
}

请将 Bearer 令牌保存在 MCP 客户端的运行时密钥存储中。不要将其放入 Git、已提交的 .env 文件、发布日志或纳入版本控制的 MCP 配置中。

七个 Online 工具

工具	网络	证据与效果
online_status	是	在不提供仓库证据的情况下，发现端点功能、负载版本、限制和身份验证模式。
refresh_advisories	是	清点精确的依赖坐标，查询 OSV，验证返回的记录，并以原子方式刷新本地缓存。
scan_dependency_vulnerabilities	否	将当前清单与该缓存进行匹配。覆盖缺失、过期、不完整或不匹配时，状态仍为 NOT_CHECKED 或 PARTIAL。
scan_dependency_malware	否	对已安装的依赖文件进行有界静态审查。发现项需要人工审查，绝不代表已遭入侵。
pull_architecture_contract	是	获取当前不透明仓库 ID 对应的所有者批准目标，验证该目标并更新本地图缓存。
preview_sync	否	序列化精确的允许列表负载，对其进行哈希处理，并签发一个有效期为五分钟的确认令牌。
sync_graph	是	仅发送经 preview_sync 批准的负载；必须设置 dry_run:false 并提供匹配的令牌。

安装 Weavatrix Core， 以获取只读仓库情报；安装 Weavatrix Refactor， 以进行受保护的源代码更改。它们的方法仍属于各自的产品。

典型工作流

在进行任何仓库操作前，检查端点兼容性：

{"name":"online_status","arguments":{"timeout_ms":10000}}

刷新公告证据，然后在本地进行评估：

{"name":"refresh_advisories","arguments":{"timeout_ms":20000}}
{"name":"scan_dependency_vulnerabilities","arguments":{"max_age_days":30}}

查看确切的上传内容，但不发送：

{"name":"preview_sync","arguments":{"payload_version":3}}

在人工或受信任的控制器批准所显示的目标、分区摘要、 计数、大小和正文哈希后，使用返回的令牌：

{
  "name": "sync_graph",
  "arguments": {
    "payload_version": 3,
    "dry_run": false,
    "confirm_token": "token-returned-by-preview_sync",
    "timeout_ms": 30000
  }
}

更改图、仓库、目标、负载或有效期状态都会使该批准失效。端点拒绝请求或不可用时，图仍保留在本地。

网络与许可边界

local repository
      │
      ▼
local graph + derived evidence
      │
      ▼
preview_sync ── inspect destination, sections, counts, size, and SHA-256
      │
      ▼
explicit approval
      │
      ▼
sync_graph ── capability negotiation ── approved endpoint

连接器会强制执行以下规则：

• 所有非环回目标均使用 HTTPS；
• 本地开发仅允许使用环回 HTTP；
• URL 中不得嵌入凭据；
• 上传前进行端点功能协商；
• 使用有界的版本化负载允许列表；
• 使用精确的预览哈希和短时有效的确认令牌；
• 证据不完整时，如实标记为 NOT_CHECKED 和 PARTIAL。

同步负载包含有界的图拓扑和选定的派生证据。 它不包含源代码正文、代码片段、绝对主机路径、环境值、 凭据、Git 远程地址以及线缆允许列表之外的字段。“不含源代码” 不代表匿名：批准前请检查所显示的仓库身份、目标、 计数、分区和哈希。

配置

变量	必需	含义
WEAVATRIX_SYNC_URL	用于 Online 网络工作流	云端或兼容的可自托管同步端点。
WEAVATRIX_SYNC_TOKEN	用于 Cloud/经过身份验证的端点	作用域受限的 bearer 令牌，仅发送到已批准的端点。
WEAVATRIX_CAPABILITIES_URL	否	显式指定的功能文档；否则使用 /api/v1/capabilities，并在需要时回退到旧版 /api/health。
WEAVATRIX_ARCHITECTURE_URL	否	显式指定的、经所有者批准的架构契约端点。
WEAVATRIX_PRECISION	否	本地语义精度：lsp（默认值）或 off。
WEAVATRIX_GRAPH_HOME	否	覆盖本地图/缓存存储位置。
WEAVATRIX_ADVISORY_STORE	否	覆盖本地公告缓存文件。

兼容端点必须实现版本化的功能和同步契约。 功能发现本身不会发送任何仓库证据。

安全证据，不妄下定论

安全公告刷新会检查有界仓库清单中发现的固定版本 npm、PyPI、Go、Maven/Gradle 和 crates.io 坐标。只有当当前清单与完整且最新的 Online 缓存相符时，才允许报告干净的零结果。

恶意软件审查采用静态且有界的方式。它可以识别下载并执行的生命周期脚本、反向 Shell 模式、解码后执行、挖矿程序迹象、读取凭据文件或可疑的数据外传端点等证据。但它无法证明执行情况、来源、凭据泄露、安全性或系统已遭入侵。

架构契约会在本地验证通过后才会生效。

请通过 GitHub Security Advisories 私下报告漏洞。

架构

该连接器采用严格的模块化端口与适配器系统：

policy
  └─ discovery adapters
       └─ security cache and evidence services
            └─ Online actions
                 └─ MCP composition and executable

• policy：目标验证、版本匹配、清单标识和恶意软件证据规则；
• discovery：有界清单和已安装软件包适配器；
• security：原子化安全公告状态、缓存匹配、扫描和报告；
• online-actions：能力、契约、安全公告、预览和同步用例；
• composition：扩展注册、启动器和 stdio 可执行文件。

已检入的 架构契约 强制要求运行时循环依赖为零、生产文件不超过 300 行、函数不超过 100 行，且不设例外，也不设违规基线。

开发与发布验证

npm ci --ignore-scripts
npm test
npm run verify:release
npm audit
npm pack --dry-run --json

发布门禁会验证软件包标识、依赖版本范围、已安装版本的精确性、MCP Registry 元数据、已检入的发行说明、MIT 许可、发布文件允许列表，以及标签与版本的一致性。CI 会在 Node.js 24 上重复运行测试、安全审计和软件包试运行。

许可证

MIT。Weavatrix Online 和其内部的 weavatrix-js 运行时是独立版本化并采用 MIT 许可的软件包。