VMware Debug

VMware Debug

免责声明：由社区维护的开源项目，与 VMware, Inc. 或 Broadcom Inc. 无关联，也未获其认可或赞助。“VMware”和 “vSphere”是 Broadcom 的商标。源代码依据 MIT 许可证公开，供审查。

VMware 技能系列的诊断核心。你提供症状（错误、日志转储、虚拟机运行缓慢）；此技能会开展系统化调查，将其他技能中的事件关联到同一时间线，按可能性排列根因假设，并告知你接下来要检查什么。它绝不会接触 vSphere——不连接任何内容，也不会执行修复；它唯一的写入操作是将信息记录到 $OPS_HOME 下的本地案例台账中。修复工作会交由 vmware-aiops（单步操作）或 vmware-pilot（多步、设有门控）处理，与 vmware-harden → vmware-pilot 的顾问／执行者分工方式一致。

完整方法、事件封装契约和症状路由，请参阅 skills/vmware-debug/SKILL.md。

升级到 2.0

2.0 将 14 个 MCP 工具中的 13 个重命名，使每个名称都以动词开头（例如，case_close → close_case、case_get → get_case、case_grade → grade_case）。完整的旧名称 → 新名称对照表见 RELEASE_NOTES.md。其他内容均未改变：工具、参数、安全门控和 CLI 命令保持不变。如果 Agent 提示词、脚本或 ~/.vmware/rules.yaml 中引用了工具名称，请更新；不过，使用旧名称编写的拒绝规则仍可与 vmware-policy ≥ 1.18.1 配合使用（vmware-audit policy 会列出重命名后适用范围扩大的规则），而 vmware-pilot ≥ 1.13 会转换已保存工作流中的旧名称。 如果早于 2.0 的安装共用该 rules.yaml，也请将其升级到 vmware-policy ≥ 1.18.2：它会同时使用新旧名称匹配每条规则，因此一个文件即可同时适用于两者。

配套技能

需求	技能
事件关联／根因分析	vmware-debug（本项目）
集中式日志搜索	vmware-log-insight（将其 search_logs 结果提供给此技能）
vCenter 事件和警报	vmware-monitor
指标／异常	vmware-aria
执行修复	vmware-aiops（单步操作）／vmware-pilot（多步、设有门控）

安装

uv tool install vmware-debug
vmware-debug categories          # see which symptom categories it can diagnose

MCP 工具（14 个 — 7 个读取，7 个写入）

7 个写入操作仅写入本地案例台账，不会触及任何 VMware 系统。

关联分析 — 无状态，用于单次查看：

工具	用途
build_incident_timeline	[READ] 关联预先获取的事件 → 时间线 + 峰值 + 排序后的假设 + 下一步检查建议
list_symptom_categories	[READ] 列出已识别的症状类别，以及每类需要检查的内容

调查台账 — 用于需要长期推理的事件：

工具	用途
open_case	[WRITE] 定义事件；返回案例 ID 和此环境可达到的等级
get_case_readiness	[READ] 在开始前，查看此环境按症状类别可达到的等级
get_case_knowledge	[READ] 查看接受哪些知识格式、已挂载哪些内容，以及哪些条目适用于某个案例
plan_case	[READ] 查看接下来要获取的内容 — 每个步骤对应的技能、工具和用途；根据案例当前状态重新计算
list_cases	[READ] 按时间从新到旧列出案例
get_case	[READ] 查看单个案例：范围、台账条目数量、等级历史
record_case_hypothesis	[WRITE] 登记一个候选解释，或读取支持和反驳各个解释的台账
submit_case_evidence	[WRITE] 记录一条检索到的事实，并附上其来源、查询和时间依据
record_case_gap	[WRITE] 记录无法检索的内容，以及如何补齐
record_case_timeline	[WRITE] 将案例收集到的所有内容关联为一条时间线
grade_case	[WRITE] 根据台账重新计算结论等级并记录
close_case	[WRITE] 记录最终等级、归档，并列出尚未解决的问题

事件封装：{ts, source, severity, entity, text, fields}。Agent 会先将每个来源的事件规范化为此格式，再交给 debug，因此 debug 在运行时完全不依赖其他包。 在 fields 中保留每个事件的 event_type — 分类器会同时匹配该字段和文本；大多数现代 vSphere 事件都是 EventEx：文本是通用的样板句，只有 eventTypeId 才能说明事件的实际类型。

安全性

从设计上即为离线且无需凭据：它不会连接到任何 vCenter/NSX/Aria，在 VMware 上没有破坏性操作面，也没有可泄漏的机密。唯一的写入是本地案例台账：证据、缺口、假设和等级历史均为只追加；timeline.md 会根据证据重新生成，case.json 保存当前等级和状态。多个写入进程时也是如此：每次写入案例前，都会先获取该案例的锁文件（.ledger.lock，以独占方式创建），因此在共享 $OPS_HOME 的情况下，两个进程写入同一案例时会串行执行，而不会丢失彼此的条目；每个文件都会先写入临时名称，再移动到目标位置，因此读取者不会看到写入到一半的文件（在不支持硬链接的文件系统上，新证据文件会直接创建在目标位置：仍不会被覆盖，但读取时可能尚未写完）。进程崩溃后遗留的锁会连同持有者信息一起报告，且绝不会自动删除；确认没有进程正在写入该案例后，再手动删除。已发布的 1.11.3 及更早版本不会获取此锁，因此所有共享案例目录的计算机都必须升级。请参阅 SECURITY.md。

离线／隔离网络安装（从源代码安装）

本项目使用现代 PEP 517 构建系统（hatchling），因此按设计不提供 setup.py——这是预期行为，并非文件缺失。如果你克隆了源代码，并遇到 ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build，说明你的 pip 版本低于 21.3， 无法使用非 setuptools 后端进行可编辑（-e）安装。可编辑模式只是开发者的便利功能，并非运行工具所必需——请任选以下一种方式：

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

对于真正与网络隔离的主机，请在联网机器上构建 wheel 包并复制到目标主机——目标主机随后无需联网：

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-debug

远程访问（HTTPS）和限制工具

默认情况下，vmware-debug mcp 通过 stdio 与一个本地客户端通信，并提供所有工具。以下两个选项可以更改此行为 （vmware-policy ≥ 1.21.0）。

通过 HTTPS 提供服务，以便其他机器上的客户端连接。每个调用方都需要一个 bearer token：

vmware-audit token create alice          # prints the token once; give it to alice
vmware-audit token list                  # names only
vmware-audit token revoke alice          # refused from its next request, no restart
vmware-debug mcp --transport https --host 0.0.0.0 --port 8443 \
    --cert /etc/vmware-mcp/server.pem --key /etc/vmware-mcp/server-key.pem \
    --public-name mcp.example.com

连接客户端（此处以 Claude Code 为例；任何支持可流式传输 HTTP 和自定义请求头的 MCP 客户端均可）：

claude mcp add --transport http vmware-debug https://mcp.example.com:8443/mcp \
    --header "Authorization: Bearer $VMWARE_MCP_TOKEN"

{
  "mcpServers": {
    "vmware-debug": {
      "type": "http",
      "url": "https://mcp.example.com:8443/mcp",
      "headers": { "Authorization": "Bearer ${VMWARE_MCP_TOKEN}" }
    }
  }
}

• 没有 token 时，服务不会启动；它会拒绝 --public-name 以外的 Host／Origin 值，并会在绑定端口前检查未经身份验证的请求是否返回 401。请为这些名称使用客户端信任的证书。
• 如果在同一台机器上使用 TLS 终止反向代理，请使用 --transport http --host 127.0.0.1 --public-name mcp.example.com，并透传 Authorization 请求头。
• 如果负载均衡器或网关位于另一台机器上，请保留 --transport https（自签名证书也可以），在 --public-name 中列出负载均衡器发送的 Host 主机名，并让它转发 Authorization。它的健康探测可以使用 GET /healthz，无需 token，并且只返回 {"status": "ok"} （vmware-policy ≥ 1.23.0）。
• 每个请求都附带 traceparent 或 X-Request-ID，即可将其记录在审计行中；随后使用 vmware-audit log --correlation-id ID 查找同一平台请求关联的调用。
• 审计日志将每个调用方记录为 token:<name>。指定不同目标的调用会并行运行；未指定目标的调用则依次运行，因此多人共用一个服务时，请指定目标。
• 所有能够访问此端点的人都将使用该服务的账户进行操作。 Token 用于识别调用方；它们不会授予任何平台权限。请为每个权限级别运行一个端点。
• **一个端点供多人或多个角色使用：**运行一次 vmware-audit roles enable，然后为每个 token 指定角色（使用 vmware-audit token create NAME --role reader，或在 roles.yaml 中指定包含工具和目标的角色；vmware-policy ≥ 1.24.0）。角色会限制 token 可在此端点上调用的内容；它不能授予超出账户权限的权限。请参阅 vmware-policy 的 README 中的 “Roles for network callers”。

仅提供只读工具，以及你选择开放的写入工具：

vmware-debug mcp --expose read --allow-write close_case
# or: VMWARE_DEBUG_MCP_EXPOSE=read VMWARE_DEBUG_MCP_ALLOW_WRITE=close_case vmware-debug mcp

未提供的工具不会显示在客户端的工具列表中。错误值或未知的写入工具会导致服务停止运行 （退出码 2）。这只会限制向客户端提供的工具，并非授权机制，因此账户本身应遵循最小权限原则。

详细信息：skills/vmware-debug/references/setup-guide.md（“Serving MCP over HTTPS”、“Limiting which tools are offered”）。

许可证

MIT。