toolwright/toolwright

# Toolwright **AI 工具的免疫系统。** 捕获任何 API —— 或封装现有的 MCP server —— 获得一个受治理的工具供应链：凭证与模型上下文隔离、签名审批、默认失败关闭的运行时、漂移检测以及有界的自我修复。 [](https://pypi.org/project/toolwright/) [](LICENSE) [](https://www.python.org/downloads/)

**无治理** ``` # Token 硬编码在 tool 配置中 {"auth": "Bearer ghp_s3cr3t..."} # Model 在上下文中看到 token # tool 运行前无批准 # API 变更 → 静默 agent 故障 # 无审计追踪 ```

**使用 Toolwright** ``` toolwright create github export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ..." toolwright serve # Token 在运行时注入，从不进入上下文 # 签名 lockfile 把关每一次变更 # 在 agents 崩溃前检测到漂移 # 每个决策均经审计 ```

## 为什么这很重要 每个 AI agent 都需要工具。但目前工具连接 API 的方式存在缺陷： - **凭证泄露到模型上下文中** —— API key 落入工具定义、日志和提示词中，模型可以看到并滥用它们 - **工具变更悄无声息** —— 新功能和变更的 schema 未经人工审查即上线 - **API 漂移导致 agent 崩溃** —— 上游变更导致静默故障，没有警报或恢复机制 生成是入口。**治理是护城河。** | 关注点 | 典型 MCP server | Toolwright | |---|---|---| | Credentials (凭证) | 在配置中，对模型可见 | 运行时注入，从不出现在上下文中 | | 新工具 | 立即可用 | 经过签名的 lockfile 把关 | | API 变更 | 静默崩溃 | 检测到漂移，提议修复 | | 故障 | 重试或崩溃 | 熔断器、隔离、回滚 | | 审计追踪 | 无 | 每个决策都记录原因代码 | | 恢复 | 手动重建 | 带快照的有界自我修复 | ## 安装 ``` pip install "toolwright[all]" ``` `tw` 可作为简写形式使用。有关[选择性安装](#install-options)见下文。 ## 60 秒快速上手 ``` # 从 GitHub API 创建受监管的 tools toolwright create github # 设置 token（绝不进入 model 上下文） export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ghp_yourToken" # 获取 Claude Desktop 的配置片段 toolwright config # 粘贴到 Claude Desktop 配置中 → 重启 → 完成。 ``` 就是这样。GitHub 工具 —— 已进行风险分类，并应用了行为规则。你的 agent 现在可以在治理下列出仓库、创建 issue 和管理 pull request。 ## 适用于你拥有的任何资源 | 起点 | 命令 | |---|---| | 已知 API | `toolwright create github` | | Web 应用 | `toolwright mint https://app.example.com -a api.example.com` | | OpenAPI 规范 | `toolwright capture import openapi.yaml -a api.example.com` | | HAR 文件 | `toolwright capture import traffic.har -a api.example.com` | | OTEL traces | `toolwright capture import traces.json --input-format otel -a api.example.com` | | MCP server | `toolwright wrap npx -y @modelcontextprotocol/server-github` | 所有路径都会生成相同的受治理产出物：工具、策略、lockfile、基线和验证契约。 ## 供应链如何运作 ``` ┌──────────────────────────────────────────────┐ Browser traffic │ │ OpenAPI spec ──> │ capture / mint ──> compile ──> │ HAR / OTEL │ │ │ toolpack (tools + policy + lockfile) │ │ │ │ serve ──> governed MCP server │ │ ├── credential injection (proxy layer) │ │ ├── signed approval gates │ │ ├── circuit breakers │ │ └── drift / verify / repair │ └──────────────────────────────────────────────┘ ``` 1. **Capture (捕获)** —— 记录来自任何来源的真实 API 行为 2. **Compile (编译)** —— 生成具有 schema、风险层级和策略的确定性工具定义 3. **Approve (审批)** —— 使用 Ed25519 密钥签署变更。审查前不运行任何内容。 4. **Serve (服务)** —— 通过 MCP 暴露工具，具备身份注入、策略执行和熔断器功能 5. **Heal (修复)** —— 检测漂移、验证行为并在安全范围内自动修复 ## 核心能力 ### 凭证从不接触模型上下文 身份验证在运行时通过环境变量解析 —— 按主机、隔离。工具定义、日志、证据包和 agent 提示词均不含凭证。 ``` export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ghp_..." export TOOLWRIGHT_AUTH_API_STRIPE_COM="Bearer sk_..." # Toolwright 为每次上游调用注入正确的 token ``` ### 每次变更在运行前都经过签名 lockfile 上的 Ed25519 签名。新工具、变更的 schema、扩展的功能 —— 全部由显式审批把关。杜绝静默权限提升。 ``` toolwright gate allow --all # interactive review toolwright gate check # verify lockfile integrity toolwright gate block delete_user # block a specific tool ``` ### 默认失败关闭 (Fail-closed) 默认拒绝。仅允许显式白名单。网络安全被硬编码：SSRF 防护、私有 CIDR 过滤、重定向验证和响应大小限制。 ### 漂移检测和有界自我修复 持续健康探测在上游变更导致 agent 崩溃前捕获它们。安全的补丁自动应用。有风险的补丁升级待审批。快照支持即时回滚。 ``` toolwright drift # one-shot check toolwright serve --watch --auto-heal safe # continuous monitoring ``` ### 行为规则和熔断器 调用时的可组合约束。即时终止行为异常的工具。 ``` toolwright rules template apply crud-safety # require read before delete toolwright kill search_api --reason "500s" # circuit breaker kill switch toolwright enable search_api # bring it back ``` ## 已有 MCP server？封装它。 ``` toolwright wrap npx -y @modelcontextprotocol/server-github toolwright wrap --url https://mcp.sentry.dev/mcp --header "Authorization: Bearer $TOKEN" ``` `wrap` 发现上游服务器的工具，并应用相同的审批、规则、熔断器和失败关闭执行策略。无需重新创建工具 —— 只需治理。 ## 服务选项 ``` toolwright serve # stdio (Claude Desktop) toolwright serve --http # HTTP + web dashboard toolwright serve --scope repos,issues # serve specific groups toolwright serve --max-risk low # cap risk tier exposure toolwright serve --watch --auto-heal safe # continuous healing ``` ## 文档 - **[60 秒上手 GitHub API](docs/quickstarts/github.md)** —— 使用 `toolwright create github` 快速开始 - **[任何 REST API](docs/quickstarts/any-rest-api.md)** —— 针对自定义 API 的浏览器捕获 - [用户指南](docs/user-guide.md) —— 完整生命周期参考 - [架构](docs/architecture.md) —— 内部原理 - [已知限制](docs/known-limitations.md) | [故障排除](docs/troubleshooting.md) | [术语表](docs/glossary.md) 运行 `toolwright --help` 获取快速参考。运行 `toolwright --help-all` 获取所有命令。 ## 安装选项 ``` pip install "toolwright[all]" # MCP server + browser capture + TUI python -m playwright install chromium # for browser capture (use same interpreter) ``` 或者只安装你需要的： ``` pip install toolwright # core pip install "toolwright[mcp]" # + MCP server pip install "toolwright[playwright]" # + browser capture pip install "toolwright[tui]" # + dashboard TUI ``` ## 许可证 MIT

标签：AI 安全, API 网关, DevSecOps, JSONLines, LLM 工具, MCP 服务器, Python, StruQ, 上游代理, 代码签名, 凭证隔离, 审计日志, 故障自愈, 文档安全, 无后门, 智能体安全, 模型上下文协议, 沙箱, 漂移检测, 熔断器, 特征检测, 自我修复, 逆向工具, 零信任