平台与兼容性支持矩阵
生产支持代表经过验证的安全边界,不代表“二进制能够启动”就自动获得支持。
本页是 Herdr-MCP 1.0 的公开兼容性约定。只有下表明确标为生产支持的平台才属于正式 workstation 支持范围。候选或不支持的平台不得被描述为与生产平台等价。
协议与运行时兼容性#
Herdr-MCP 有多层彼此独立的协议,它们不会共用一个版本号。
| 层 | 当前生产身份 | 有界兼容范围 | 失败关闭规则 |
|---|---|---|---|
| 公共 MCP 客户端协议 | initialize 协商接受 2025-11-25、2025-06-18、2025-03-26、2024-11-05、2024-10-07 |
ChatGPT/OpenAI discovery 可公布探测版本 2026-07-28;该值不是额外的 initialize 协议版本 |
缺失或无法识别的 initialize 协议值会明确降到 legacy baseline 2025-11-25,不会把未列出的协议对外声明为支持 |
| 公共 Edge 工具契约 | epoch 7,19 个 action | 旧对话可能保留历史工具快照,但 Edge 只发布当前 DEV/PROD 公共 catalog;epoch 3 身份仅作为非 DEV/PROD 的保守回退与 rollback 基线 | 不在当前公共契约内的工具会被拒绝 |
| Workstation Runtime Execution Contract | epoch 4,18 个工具 | 紧邻上一代冻结的 epoch 3、18 个工具作为有界 rollback 基线,同时保留仍在现场的冻结 epoch 2、18 个工具 catalog | 其他 epoch/hash 组合在 workstation 执行前直接拒绝 |
| Relay wire protocol | 数字 protocol_version = 1 |
无 | 缺失、字符串形式或未知版本会在写入 Relay 状态前被拒绝 |
| 持久运行时状态 | 当前二进制 schema;只有一个已声明且不可逆的前向步骤(N→N+1)可通过显式 herdr-mcp update 并在备份状态后接纳 |
旧 store 通过追加式迁移事务性升级 | 降级、多步或未声明的 schema 变更都会拒绝;定时更新拒绝迁移,更新后的 store 对旧二进制失败关闭 |
当前 ChatGPT 路径按无状态 Streamable HTTP 客户端验证:openai-mcp 的 initialize 与 tools/list 使用所需 SSE framing,notifications/initialized 可正常处理,Connector 重连不依赖保留过期的 Mcp-Session-Id。Workstation reconnect、Durable Object rehydration、heartbeat hibernation 与 reconnect grace 分别有回归测试,因此浏览器重新连上并不等于 workstation mutation 可以安全重放。
Herdr 运行时支持#
herdr-mcp 只驱动一种 Herdr 运行时:Herdr TUI。下表版本核对于 2026-10-30。
| Herdr 运行时 | herdr-mcp v1.1 状态 | 说明 |
|---|---|---|
Herdr TUI(herdr CLI + herdr server) |
支持 | herdr-mcp 唯一驱动的运行时:通过 Herdr TUI socket API 操作 workspace、tab、pane 和 agent。CI 与 release gate 固定使用 Herdr TUI 0.9.5。文档:Herdr TUI 文档。 |
Herdr app(0.1.9)及 herdr-core(hc 0.1.14) |
不支持 | 独立的运行时,使用自己的 JSON-RPC/OpenRPC socket;以 terminal 而非 workspace/tab 为模型,Agent 状态只通过 OSC 7501 上报,且与 Herdr TUI 不共享 Agent。在其中启动的 Agent 对 herdr-mcp 不可见。 |
N、N-1 与 N+1 规则#
N 表示当前部署的 Edge 契约和当前已验证的 runtime generation。
- N → N 是常规生产路径。候选 runtime 只有在健康检查和精确 runtime execution contract 验证通过后才能切换流量;Release 更新还要求 manifest 与本地 durable-state schema 匹配。
- N-1 runtime execution 只是有界 rollback,不是任意历史版本兼容承诺。当前同时接受紧邻上一代冻结的 epoch-4 runtime contract、仍在现场的冻结 epoch-2 catalog 与当前 epoch 5,并且按 epoch + hash 校验;更老的任意 catalog 不会被接收。
- N+1 runtime 或 control plane 不做猜测兼容。未来 epoch、Relay protocol 或 durable-state schema 必须经过显式迁移和验证后才能使用;当前实现会拒绝未知 contract pair 和未来 schema,而不是尝试“尽量降级运行”。
- durable state 升级是单向迁移。 只有一个已声明且不可逆的前向 state-schema 步骤(N→N+1)可通过显式
herdr-mcp update,并先创建状态备份。降级、多步和未声明变更都会拒绝;定时更新拒绝迁移。回滚必须先恢复备份,之后才能启动旧 binary。Runtime rollback 只切回执行所有权,不会撤销已经发生的 Git、文件、远程服务或 Agent 副作用。
实现升级与 contract migration 是两种不同操作。普通修复可以在不改变 tools/list 的情况下升级 runtime;增加或移除模型可见工具必须显式升级 contract epoch,并重新验证客户端工具快照。
平台支持#
| 平台 | 状态 | 文件系统边界 | 进程 / 凭据边界 | 网络边界 | 验证说明 |
|---|---|---|---|---|---|
| macOS(Apple Silicon) | 生产支持 | 远程文件/Git mutation 仅允许作用于实时 managed Git root,并叠加 read-only/write-root、dirty/busy、secret-path 等 gate。Shell 仍以登录用户身份执行,不是 sandbox。涉及 TCC 的原生访问使用长期稳定的 Herdr-MCP broker responsibility boundary。 | 用户级 launchd 管理 runtime 与 production Link;immutable generation 通过 runtime/current 切换。本地浏览器 IPC 使用 Herdr-MCP 所有、mode-0600 的 Unix socket;device/runtime credential 使用 macOS 凭据边界。 |
Runtime MCP 仅绑定 loopback 并要求本地 bearer;workstation 主动建立经过认证的 outbound Link,不公开 workstation 入站端口。 | 已做实体机验证。 Apple Silicon macOS 是当前主要生产路径;TCC broker/process、generation rollback、OAuth/Connector、真实 ChatGPT 与浏览器插件链路均有专项回归/UAT。 |
| Linux x86_64(原生 Debian 类主机) | 生产支持 | 与 macOS 相同的 managed-Git-root 和 mutation gate,通过 Unix 文件所有权/权限执行。Linux 没有 macOS TCC;shell 同样是 workstation 用户的非 sandbox shell。 | 优先 systemd --user;没有 user systemd manager 时使用已验证的 current-user process backend。Device credential 与 Herdr-MCP 所有的 service/control 文件使用私有用户级存储与权限。受管 runtime 绑定浏览器扩展的 mode-0600 extension.sock,native-host install 为 Google Chrome 登记 Chromium host(Chromium 与 Chrome for Testing 在其配置目录已存在时登记)。 |
同样使用 loopback runtime + authenticated outbound Link。扩展不使用 loopback bearer。 | 已做实体机验证。 原生 Debian existing-fleet 安装、Link/service lifecycle、updater apply 已验证;发布静态 x86_64-unknown-linux-musl 资产。 |
| Linux ARM64 / aarch64(原生 Debian 类主机) | 生产支持 | 与 Linux x86_64 相同的 managed-root 与 Unix ownership 边界。 | 同样使用 systemd --user / managed-process service model、私有 credential store,以及与 Linux x86_64 相同的 Chromium Native Messaging host。 |
同样使用 loopback runtime + authenticated outbound Link。扩展不使用 loopback bearer。 | 已在 NanoPi R5C / Debian 11 ARM64 做实体机验证。 exact-source release build、immutable-generation install、原 enrolled device identity 保留、systemd-user service/Link reconcile 与 Edge herdr_inspect 均通过;Release qualification 还在 GitHub 原生 ARM64 runner 构建并 smoke 静态 aarch64-unknown-linux-musl。 |
| Windows x86_64 | 候选——非生产支持 | 实体机 UAT 已实际覆盖原生 managed-root/path 边界,但 1.0 Production 声明仍需在最新 main 的精确 candidate 上完成 #394 的完整晋级记录。 | #364 的原生实现已进入 main,使用 current-user process、Windows Credential Manager、Startup-folder 登录启动项,并做 process ownership fencing。1.0 runtime 也已经在 Windows 上启用首台设备 worker bootstrap,包含 canonical enrollment 和受管 Link 激活。源码合并和 hosted CI 只是候选验证证据,不构成正式支持保证。实体机 UAT 已实际跑过安装、service/Link 恢复、模拟登录恢复、device/Connector 保持以及真实 Connector 对话;#514 修复了验收过程中暴露的 Windows HOME/PATH 问题。 |
候选实现沿用 loopback + authenticated outbound Link。 | Windows x86_64 已实际进行实体机 UAT,但 #394 的 Production 晋级仍保持打开。 在冻结最终 1.0 支持声明前,需要在精确 candidate 上记录一次全新 Windows 首台设备 worker bootstrap,覆盖 Worker 创建、canonical enrollment、Link ready 和一次真实 MCP 调用;其余晋级记录还需包含 device/Connector 身份保持、模拟登录恢复、最终只读 inspect/workspace/pane 访问和 managed-root 路径证据。没有显式 fixture 前,UNC/网络路径仍不属于支持声明;若要声明 UNC/网络路径能力,必须先补对应 fixture。 |
| Windows ARM64 / aarch64 | 候选——非生产支持 | 与 Windows x86_64 相同的候选 filesystem/path contract;尚不声明实体机文件系统能力。 | 同样使用原生 Windows current-user process、Credential Manager 与 Startup-folder ownership model。 | 同样使用候选 loopback + authenticated outbound Link。 | 已在 GitHub 原生 windows-11-arm runner 做 release build/qualification,尚无 Windows ARM64 实体机 UAT。 发布 target 为 aarch64-pc-windows-msvc;晋级 Production 仍需实体机 lifecycle、credential、path 与端到端 Link UAT。 |
| WSL | 不支持 | 尚未验证 WSL host/guest 文件系统、Windows drive mount、symlink 与权限模型可等价于原生 Linux。 | 不声明 WSL 专用 service manager、credential、browser IPC 或 host/guest process ownership 边界。 | WSL/NAT/Windows-host 网络关系不属于已验证的 production Link 边界。 | Linux binary 即使能在 WSL 启动,也不能作为支持证据。在单独的 qualification 明确这些边界前,不应把 WSL 用作安全敏感的 Herdr-MCP workstation 目标。 |
“生产支持”不等于本地 sandbox#
生产支持表示 Herdr-MCP 自己负责的边界明确并经过验证,并不把开发电脑变成容器沙箱:
herdr_fs_*和 managed Git 操作受项目 root gate 约束;herdr_exec*有意以 workstation 用户身份执行,可以访问该用户本身可访问的资源;- Herdr pane/agent 是同一 workstation 安全模型下的持久本地进程;
- Edge OAuth、device authorization、outbound Link authentication 保护远程入口,不会降低本地用户权限。
如果某个平台无法提供等价且经过验证的边界,正确做法是标记为候选或不支持,而不是静默降低要求。
候选平台晋级条件#
候选平台只有在待合并的精确实现同时满足以下条件后,才能改为生产支持:
- service/process lifecycle 能通过安装、restart/login recovery、失败激活,并且不会误接管无关进程;
- credential 在重装/恢复过程中保持私密且继续绑定到同一 device;
- managed-root 文件操作覆盖该平台原生路径语义,包括所声明的 absolute/relative path,以及任何声称支持的 UNC/网络文件系统行为;
- runtime/Link 在 workstation 边界保持 loopback/outbound-only;
initialize、tools/list、reconnect,以及一次真实 Web-AI → Edge → Link → workstation 只读请求通过;- 该 OS 的 required clean-machine CI 通过,hosted CI 无法证明的边界由实体机 UAT 覆盖;
- 未验证的子环境继续明确标记为 unsupported,不能自动继承更宽泛的平台支持标签。
相关文档:架构、Runtime 升级、故障排查和维护者 Release model。