@vitronai/alethia

Agent 原生的端到端测试，具备可验证的安全性。 你的 agent 用自然语言驱动真实浏览器，破坏性操作会被一道你能证明其有效的安全门拦截——附带签名审计轨迹，且无需云端。

Install

Claude Code —— 最快路径（插件）：

/plugin marketplace add vitron-ai/alethia-mcp
/plugin install alethia@vitronai

这会一步完成 MCP 服务器和技能的配置——无需手动执行 npm install 或编辑 MCP 配置。重启或运行 /reload-plugins 即可激活。

Claude Code —— 仅安装技能（无插件管理器）：

mkdir -p ~/.claude/skills/alethia && \
  curl -fsSL https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/skills/alethia/SKILL.md \
    -o ~/.claude/skills/alethia/SKILL.md

重启 Claude Code。下次你让它测试某个页面时，它会发现 Alethia 尚未配置，并引导你自行安装 bridge。

其他用户（Claude Desktop、Cursor、Cline、Continue）：

npm install -g @vitronai/alethia

然后将其添加到你的客户端的 MCP 配置中：

{
  "mcpServers": {
    "alethia": {
      "command": "alethia-mcp"
    }
  }
}

保存后重启你的客户端。当你的 agent 首次调用 Alethia 工具时，runtime 会自动下载（已签名，约 100 MB）。默认会打开一个 cockpit 窗口供你观察——设置 ALETHIA_HEADLESS=1 可隐藏它；CI 环境会自动隐藏。

升级 bridge： npm install -g @vitronai/alethia@latest。自 0.6.0 起，新 runtime 版本不再需要新的 bridge——它会在每次启动时查询 GitHub Releases。

始终运行最新版本而无需手动升级：

{
  "mcpServers": {
    "alethia": {
      "command": "npx",
      "args": ["-y", "@vitronai/alethia@latest"]
    }
  }
}

@latest 后缀很重要——没有它，npx -y 可能会提供过期的缓存版本。权衡：冷缓存时增加 10–30 秒，而且每次启动都会拉取 npm 当前提供的任何版本（对于合规敏感的工作，全局安装是更安全的默认选择，因为它只会在你明确升级时发生变化）。

固定特定 runtime 版本（可复现的 CI、二分定位）：

"env": { "ALETHIA_RUNTIME_VERSION": "0.4.0" }

安装 Claude Code 技能（可选，教会 Claude 何时使用每个工具）：

alethia-mcp --install-skill

Related MCP server: titmas-agent-action-gate

你可以要求什么

你不需要直接调用这些工具——只需用自然语言告诉你的 agent，它就会选择合适的工具。

在密码、令牌或信用卡字段中输入内容会被拦截，除非你将请求描述为真实的登录或支付测试——agent 会为你启用该操作，你无需指定任何标志。

更多可直接粘贴的示例： agent cookbook 包含完整的演练——在未知页面上引导测试、完整的合规检查、并行的多页面检查、实时合作伙伴演示。每一个都是你可以直接粘贴的提示词。

将 Alethia 添加到你的项目

无需按项目安装——一旦配置好 MCP 服务器，任何项目中的任何 agent 都可以使用它。

1. 将 .alethia 文件放在仓库视为测试代码的任何位置——例如 tests/e2e/，或任何合适的地方。

   # tests/e2e/login.alethia
   name login flow
   navigate to http://127.0.0.1:5173
   assert "Sign in" is visible
   click Sign in
   type dev@company.com into the email field
   assert dashboard is visible

2. 让 agent 运行它： “针对 http://127.0.0.1:5173 运行 tests/e2e/login.alethia。”

3. 在 CI 中，完全无需 agent 或 MCP 主机即可运行：

   alethia run tests/e2e/login.alethia

   通过时退出码为 0，失败时为 1。可直接使用的工作流：examples/github-actions.yml。

一个可运行的参考项目（演示应用 + 规范 + CI + 基准测试）位于 vitron-ai/alethia-anvil。

为什么不用 Cypress 或 Playwright？

它也不仅仅是一个测试工具——让 agent 检查它正在构建的页面上的 getComputedStyle() 或 offsetWidth，你会直接从 DOM 获得实时、未缓存的答案，而不是经历重新加载和检查的循环。

深入了解： 架构 · 安全门 · 常见问题 · 面向 agent 驱动测试的 UI 模式

CLI 标志

alethia-mcp                  Run as a stdio MCP server (default)
alethia-mcp run <path>       Run an NLP test file from the shell (CI mode)
alethia-mcp run --nlp "..."  Run inline NLP from the shell
alethia-mcp run -            Read NLP from stdin
alethia-mcp --version        Print the version and exit
alethia-mcp --health-check   Probe the Alethia runtime and exit 0/1
alethia-mcp --debug          Run with debug logging on stderr

同时还会安装一个更短的 alethia 别名（同一个二进制文件），因此 run 子命令可以以 alethia run <path> 的形式调用。

环境变量

bridge 如何保持自身更新

• runtime 在首次使用时从已签名的 GitHub releases 自动安装（Ed25519 验证）。bridge 在首次启动时向 GitHub 查询当前版本（缓存 1 小时）——bridge 源码中没有版本固定，因此全局安装的 bridge 会持续拉取随发布推出的最新 runtime。

• bridge 也会自动更新自身（自 0.8.0 起）：启动时检查 npm，验证 tarball 的 SHA-512，安装到 ~/.alethia/bridge/<version>/。未经明确操作不会跨越主版本；新版本只有在完成真实的 MCP 握手后才会被信任，在此之前崩溃的版本会在 3 次尝试后被隔离。

• 随附的 Claude Code 技能以相同方式自动刷新——每次启动时将其与 ~/.claude/skills/alethia/SKILL.md 进行比较，如果过期则覆盖。

故障排查

“Alethia desktop runtime is not running” ——运行 alethia-mcp --health-check（如果缺失会触发自动安装）。如果仍然失败，请检查到 GitHub 的网络连通性。

"WRITE_HIGH" / "EA1 POLICY BLOCK"（审计日志中） — 一个破坏性操作被阻止了。这是正确的、故障时关闭（fail-closed）的行为——不是需要修复的错误。放宽该策略需要人工配置；代理无法在调用内部自行完成。

"SENSITIVE_INPUT_DENIED" — 检测到密码/令牌/信用卡字段。仅在合法的认证/支付测试中，使用 allowSensitiveInput: true 来覆盖此限制。

MCP 客户端看不到工具 — 运行 alethia-mcp --health-check，检查你的配置格式，重启客户端，并设置 ALETHIA_DEBUG=1 以记录桥接流量日志。

"Server transport closed unexpectedly" / 桥接进程静默退出 — 通常是过期的缓存桥接。如果使用 npx -y @vitronai/alethia 且未加 @latest，请加上它，或运行 rm -rf ~/.npm/_npx。如果使用全局安装，请运行 npm install -g @vitronai/alethia@latest。然后完全退出并重启你的客户端（macOS 上按 Cmd-Q，而不仅仅是关闭窗口）。

"我在 GitHub 上看到了新版本，但我的运行时没有升级" — "当前版本"检查会缓存 1 小时。通过 rm ~/.alethia/.latest-release ~/.alethia/.bridge-registry-cache 清除缓存，然后重启客户端。

安全态势

该运行时在架构上仅限本地：其签名二进制文件拒绝导航到 file://、localhost、127.0.0.1、.local 以及 RFC1918 私有地址范围之外的任何位置。这是一个编译期常量——没有任何标志、环境变量或 UI 开关可以改变它。完整的威胁模型和披露流程：SECURITY.md。滥用举报：team@vitron.ai。

隐私

在架构上仅限本地——不会在您的机器之外收集、传输或存储任何内容。页面内容、截图和测试指令均在本地处理，绝不会发送到任何地方。证据包仅在明确请求时写入您的文件系统。零遥测、零分析、零崩溃报告。如有疑问：team@vitron.ai。

许可证与专利声明

此桥接组件采用 MIT 许可证——参见 LICENSE。Alethia 运行时本身正在申请专利（美国申请号 19/571,437）；此桥接组件的 MIT 许可证不授予对运行时的专利许可。商业使用运行时可能需要单独的许可证。许可咨询：team@vitron.ai。