Warmplane

Warmplane

安全控制：

本地控制平面，让 Model Context Protocol（MCP）会话通过紧凑的能力门面、策略治理和确定性执行保持热连接。

v0.32.0 — 更新日志 · 用户指南 · Agent 技能 · 性能 · 白皮书 · OpenAPI

---

⚡ 什么是 Warmplane？

Warmplane 是用于 AI 工具调用的本地控制平面和反向代理。它与多个上游 MCP 服务保持持久的热连接，并将它们多路复用到一个统一的受治理接口后面。

Warmplane 解决的问题

1. 上下文窗口中的 Token 膨胀：每轮都发送数十种工具的大型 JSON 模式，会浪费数万个提示词 Token。Warmplane 提供紧凑的目录索引（将载荷大小减少 58–96%）、按需发现模式，以及 SHA-256 ETag 缓存。
2. 工具描述欠佳且含糊不清：许多上游工具的文档字符串内容稀少、容易误导或措辞不佳，导致大模型困惑。Warmplane 支持通过多态别名（AliasTarget）覆盖工具摘要和描述，并生成紧凑的参数签名（tool(req, [opt])），无需修改上游代码即可优化 Agent 的零样本准确率。
3. 重复调用与重试：网络出现短暂故障时，朴素的 Agent 会盲目重试具有副作用的操作。Warmplane 提供抗崩溃的恰好一次幂等去重（idk_<sha256>）和明确的重试分类（safe、idempotent、unsafe）。
4. 无治理的执行与安全风险：让 Agent 直接连接实时基础设施，可能导致未授权操作。Warmplane 强制实施多租户 RBAC、按配置文件划分的服务集群、秘密信息编辑，以及人在回路（HITL）审批关卡。
5. 级联挂起与不稳定：上游进程缓慢或崩溃会冻结 Agent 循环。Warmplane 通过亚微秒级熔断器和自愈式进程监管来监控运行状况。

---

🚀 快速开始

1. 安装

Homebrew（macOS 和 Linux）：

brew tap warmplane/tap
brew install warmplane

Cargo（crates.io）：

cargo install warmplane

# Optional: with local ONNX vector search (FastEmbed)
cargo install warmplane --features semantic-search

从源代码构建：

git clone https://github.com/Warmplane/warmplane.git
cd warmplane
cargo install --path . --features semantic-search

2. 配置上游服务

以交互方式添加服务，或从现有 AI 工具导入：

# Interactive setup wizard
warmplane server add

# Or non-interactively
warmplane server add filesystem --command npx --arg "-y" --arg "@modelcontextprotocol/server-filesystem" --arg "/tmp"
warmplane server add context7 --url "https://mcp.context7.ai/sse" --bearer-env "CONTEXT7_API_KEY"

# Or 1-click import from Claude Desktop, Cursor, OpenCode, Zed
warmplane config import

或者配置 mcp_servers.json：

{
  "port": 9090,
  "toolTimeoutMs": 15000,
  "capabilityAliases": {
    "db.query": "sqlite.read_query",
    "search": {
      "target": "semble-rs.search",
      "summary": "Search codebase using semantic or BM25 ranking. Pass absolute repo path."
    }
  },
  "policy": {
    "allow": ["db.*", "fs.*", "search"],
    "deny": ["fs.delete*"],
    "requireApproval": ["db.mutation*"],
    "redactKeys": ["token", "password", "api_key"]
  },
  "profiles": {
    "coding": {
      "servers": ["filesystem", "sqlite"],
      "description": "Local engineering and exploration tools"
    }
  },
  "mcpServers": {
    "sqlite": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sqlite", "./test.db"] },
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
  }
}

3. 连接或启动 Warmplane

选择符合你工作流的运行模式：

• 模式 1：直接集成 MCP Stdio（无需后台守护进程）： 将 AI 客户端（Cursor、Claude Desktop、Antigravity）指向 warmplane mcp-server。AI 客户端会直接将 Warmplane 作为子进程启动：

  {
    "mcpServers": {
      "warmplane": {
        "command": "warmplane",
        "args": ["mcp-server", "--config", "mcp_servers.json", "--profile", "coding"]
      }
    }
  }
  

• 模式 2：后台守护进程与 Web 控制台： 运行一个中央常驻守护进程，提供 REST API、交互式 Web UI 和审计日志：

  warmplane daemon --port 9090
  

• 模式 3：通过 Streamable HTTP/SSE MCP 连接常驻守护进程： 如果已配置 mcpHttpServer，AI 客户端便可通过 HTTP/SSE（http://127.0.0.1:9191/sse）连接到同一个共享守护进程实例。

---

🔌 客户端接口

Warmplane 提供三种主要访问模式，它们共享统一的核心状态、策略门控和遥测数据：

1. 原生 MCP Stdio 代理（warmplane mcp-server）

将任何原生支持 MCP 的桌面客户端（Claude Desktop、Cursor、Zed、Windsurf）直接指向 Warmplane：

{
  "mcpServers": {
    "warmplane": {
      "command": "warmplane",
      "args": ["mcp-server", "--config", "mcp_servers.json", "--profile", "coding"]
    }
  }
}

2. HTTP REST 控制平面（warmplane daemon）

为网关、Web 应用和后端服务提供功能完整的 HTTP JSON API：

• GET /v1/capabilities：精简的能力目录索引
• POST /v1/capabilities/search：混合词法与语义能力搜索
• POST /v1/tools/call：规范化执行封装，支持上下文提炼（_jsonpath、_limit_lines）和幂等键
• POST /v1/tools/batch_call：支持通过 $step.field 插值参数的链式多步执行
• GET /v1/tasks & POST /v1/tasks/:id/update：SEP-2663 异步任务生命周期与 HITL 审核
• GET /ui：内嵌的独立 Web 控制台

3. 进程内嵌入式引擎（EmbeddedWarmplane）

直接使用进程内 Rust 库，实现零开销 Agent 执行，无需 HTTP 子进程或网络跳转：

use warmplane::{EmbeddedWarmplane, engine::ExecutionOptions};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (cp, _token) = EmbeddedWarmplane::start_from_path("mcp_servers.json").await?;
    let res = cp.call_capability(
        "filesystem.read_file",
        json!({ "path": "/tmp/test.txt" }),
        ExecutionOptions::default().with_request_id("req-1"),
    ).await;
    println!("Output: {:?}", res.data);
    Ok(())
}

---

🤖 教会你的 AI Agent 使用 Warmplane（Agent 技能）

Warmplane 内置了官方 Agent 技能（.skills/warmplane/），遵循 agentskills.io 开放标准。将你的编码 Agent（Claude Code、Google Antigravity、Cursor、OpenCode、Codex）直接指向此代码库：

# Install Warmplane Skill into Claude Code
claude skill install Warmplane/warmplane

# Or copy into your agent workspace
mkdir -p .agents/skills/warmplane && cp -r .skills/warmplane/* .agents/skills/warmplane/

• 📖 .skills/warmplane/SKILL.md — 核心提示词触发条件和标准 Agent 工作流
• 🔌 references/mcp_stdio_usage.md — 一键客户端配置（17 种 IDE）和 MCP 门面工具
• ⚙️ references/configuration_schema.md — mcp_servers.json 架构与动态密钥
• 🛠️ references/cli_cheatsheet.md — 守护进程、同步和保险库的终端命令
• 🚑 references/error_resolution.md — 熔断器、策略拒绝和恢复

---

📊 性能亮点

Warmplane 使用纯 Rust 构建，并采用零成本抽象：

• 50.4 ns：ETag 缓存验证（If-None-Match $\rightarrow$ 304 Not Modified）
• 159.8 ns：幂等缓存命中去重
• 1.58 µs：SHA-256 增量目录版本哈希（$N=10$）
• 15.9 µs：过滤后的混合能力搜索（$N=50$）
• 372.1 µs：在 1,000 个工具中进行零分配词法标签搜索

👉 在 docs/PERFORMANCE.md 中查看完整基准测试和方法说明。

---

🛡️ 核心能力矩阵

| 能力 | 起始版本 | 描述 | | 凭据生命周期限制与任务超时正确性 | v0.31.0 | 强制执行 JWT exp 验证、安全处理 UTF-8 凭据、修复亚秒级任务 TTL，以及 rustls 0.23.45 安全升级 |

凭据、审批与策略边界强制执行	v0.32.0	对 RBAC 令牌和服务端环境变量中的机密信息进行脱敏、故障关闭式 HITL 审批、要求 Webhook 签名，以及在资源和提示词路由上执行租户策略
尽职调查安全强化与韧性	v0.30.0	以恒定时间比较 Bearer 令牌、验证 JWT iss/aud/nbf、安全提取客户端 IP、确保 fsync 审计持久性，以及无竞态的状态存储
可配置的 MCP 协议版本与 HTTP 客户端接入	v0.29.0	可配置的 supportedProtocolVersions、一键客户端安装的 HTTP 传输选择、SSRF Webhook 允许列表，以及路径遍历防护
实时 MCP list_changed 与透传工具	v0.28.0	实时工具/资源/提示词列表变更通知、SEP-1319 _meta 发现提示、顶层原生工具透传，以及 WORM 变更审计日志记录
自定义别名描述与签名	v0.27.0	多态文档字符串覆盖（AliasTarget）、精简的大模型签名（tool(req, [opt])）、双向别名解析
一键式 AI 客户端注入与同步	v0.26.0	面向 Claude Desktop、OpenCode、Claude Code、Cursor、Zed、Windsurf、Cline 的双向 MCP 适配器引擎
原生 OS 密钥链保险库	v0.26.0	安全的 OS 密钥链存储和动态机密 URI 解析（keychain://、op://、env://）
可执行操作的 ChatOps Webhook	v0.26.0	带 HMAC-SHA256 签名的 Slack、Discord 和 Microsoft Teams 双向审批卡片
按配置文件划分的治理与星座	v0.26.0	细粒度的按配置文件策略规则、星座边界徽标和实时筛选指标
控制台任务与 HITL 界面	v0.25.0	实时任务与审批中心、MRTR 输入解析表单、Playground 异步切换开关，以及内嵌任务 API
SEP-2663 任务扩展	v0.24.0	非阻塞的 io.modelcontextprotocol/tasks 能力、统一 HITL 状态机、REST 与 CLI 命令
进程内嵌入式 Rust 引擎	v0.23.0	用于零开销库集成的 EmbeddedWarmplane 和 ControlPlaneHandle
流式 HTTP/SSE MCP 传输	v0.22.0	共托管的 /mcp/sse MCP 传输，支持远程 Agent 连接
命名服务器星座	v0.21.0	通过作用域 ETag 分区和 stdio 筛选进行配置文件分组（profiles）
多租户 RBAC	v0.20.0	基于角色的令牌访问、确定性目录分区、租户上下文传播
客户端委托的 MCP 采样	v0.19.0	带票据跟踪和长轮询的反向 RPC 采样（sampling/createMessage）
持久化状态子系统	v0.18.0	用于审批、幂等性和 OAuth2 令牌的原子化、可抵御重启的磁盘存储（AtomicFile<T>）
信号处理与优雅拆卸	v0.18.0	稳健处理 SIGINT/SIGTERM、刷新异步工作线程、防止子进程孤儿化
MCP 资源与提示词工作室	v0.17.0	全方位资源浏览器、带动态表单的提示词模板渲染器，以及 SSE 同步
多步批处理流水线	v0.17.0	带引用参数插值的可视化流水线编辑器（POST /v1/tools/batch_call）
企业级安全与身份验证	v0.16.0	基于令牌的中间件保护、WORM 审计 HMAC 验证和机密信息屏蔽
容错与监督	v0.15.0	降级启动、按服务划分的断路器、指数退避重启监督
Agent 增强套件	v0.14.0	门面搜索、上下文提炼（_jsonpath/_limit_lines）和多步批处理执行
HITL 审批引擎	v0.13.0	操作员关卡审批引擎、挂起、参数编辑和 HMAC Webhook 分发
WORM 审计与 SIEM	v0.12.0	仅追加的 SHA-256 哈希链审计日志、验证 API，以及 Splunk/Webhook SIEM 导出
控制台 Web UI	v0.11.0	独立的内嵌式 Web 仪表板，用于管理服务、测试 Playground、策略和遥测
动态热重载	v0.11.0	上游服务的零停机挂载/卸载、显式执行 warmplane reload 和 /v1/config/reload

---

更新日志

v0.32.0 — 凭据、审批与策略边界强制执行

• 静态 RBAC 令牌、配置文件密钥和服务端环境变量已脱敏（src/config.rs）：McpConfig::sanitize_secrets 是由 GET /v1/config 和 warmplane config show 应用的脱敏过程。它遗漏了三个承载实时凭据的字段。静态 RBAC 令牌造成的泄漏最严重，因为该映射以密钥本身为键，因此读取配置会返回部署中的所有 Bearer 令牌，包括权限更高的令牌。每个配置文件中的 policy.webhook 密钥和身份验证标头也同样被遗漏；现在，服务端的 env 块已整体脱敏，因为环境变量块没有可用于筛选的命名约定。
• HITL 审批不再能自行授予（src/http_v1/tasks_api.rs）：handle_update_task 在交叉解析审批注册表时，两次采用了默认放行策略。任务更新中没有 hitl_approval 键时，会使用伪造的 "security-operator" 身份自动批准工单，因此调用工具的 Agent 可以批准自己的受控执行；该路径也不会生成审计事件。非布尔值的 approved 会通过 unwrap_or(true)，因此作为字符串的 {"approved":"false"} 会被视为授权。现在，审批决定只能根据显式布尔值解析，格式错误的值会被拒绝，并返回 400 INVALID_APPROVAL_DECISION。
• **配置密钥时必须提供 Webhook 签名（src/http_v1/webhooks_api.rs）：**HMAC 检查原先采用“提供签名时才验证”的逻辑，因此不带签名标头的回调会完全跳过验证，并继续执行 approve 或 reject。ChatOps 集成按设计不持有 Bearer 令牌，因此签名是该路由唯一的凭据；省略签名后，无需任何凭据即可处理任意待审批工单。
• **租户策略现在也适用于 resources/read 和 prompts/get（src/http_v1/catalog.rs）：**这两个处理程序针对基础策略进行授权，且未获取租户上下文，与所有同类处理程序不同。由于 compute_effective_policy 会完全替换角色的允许列表，基础策略是可用范围最广的策略，因此检查基础策略会授予角色原本未获准的权限。handle_get_prompt 还从基础策略读取 redact_keys，忽略了配置文件的脱敏键。

v0.31.0 — 有界凭据生命周期、UTF-8 安全的凭据处理与正确的任务超时

• **强制执行 JWT 到期时间（src/rbac/engine.rs）：**对称 JWT 验证器仅在 exp 声明能解析为数字时才进行检查，因此缺少 exp、其值为 null 或非数字的令牌会完全跳过到期验证，并永久通过身份验证。现在必须提供 exp；存在但不可用的声明会被视为已过期；到期时刻则按照 RFC 7519 采用排他性判断。nbf 仍为可选，但存在且格式错误时会被拒绝。
• UTF-8 安全的凭据前缀（src/rbac/engine.rs）：authenticate 会在固定字节偏移处截取所提供的令牌，以生成授权 ID 并记录被拒绝的凭据。若令牌的第八个字节位于多字节字符中，就会触发崩溃，而不是返回 INVALID_CREDENTIALS；这使未经身份验证的调用者能够将错误的密钥转化为拒绝服务，也导致无法使用非 ASCII 静态密钥。现在截断操作会回退到最近的字符边界。
• **亚秒级任务 TTL 不再归零（src/tasks.rs）：**到期检查会将毫秒 TTL 除以 1000，再与以整秒记录的创建时间进行比较。整数除法会将任何不足一秒的生命周期向下取整为 0，因此请求 ttlMs: 500 的任务会在返回时就被标记为 Failed。现在转换会向上取整，且 expires_at_epoch_secs 不再等于创建时间。
• **rustls 0.23.45 安全更新（Cargo.lock）：**更新锁定的 rustls 版本，以修复 RUSTSEC-2026-0285 问题；该问题可能导致 TLS 1.3 握手消息在不同加密级别边界之间被错误接受。该依赖由 reqwest 间接引入。

v0.30.0 — 安全加固、恒定时间加密、JWT 强制校验与生产环境尽职审查

• 恒定时间校验与时序攻击加固（src/daemon/auth.rs、src/chatops/、src/vault.rs）： 集成 subtle crate，通过 ConstantTimeEq 对 HTTP bearer 身份验证令牌、Webhook HMAC 签名和 Keychain 密钥进行恒定时间切片比较，消除侧信道时序攻击风险。
• 严格校验 JWT RBAC 声明（src/rbac/jwt.rs）： 强制要求 JWT 包含必需的加密声明（exp、iat、sub/actor_id 和 role），并进行宽限时间校验，防止接受未签名、已过期或格式错误的 bearer 声明。
• 安全解析客户端 IP（src/http_v1/helpers.rs、src/daemon/server.rs）： 校验转发标头（X-Forwarded-For、X-Real-IP）中的 IPv4/IPv6 语法，并通过 Axum ConnectInfo<SocketAddr> 直接提取远程套接字对端地址，防止 WORM 审计记录和速率限制受到 IP 欺骗攻击。
• 原子化锁定状态文件权限（src/storage.rs）： 强制将临时和持久化敏感状态文件（oauth_tokens.json、secrets）的 POSIX 权限设为 0o600，并将状态目录权限设为 0o700。
• 线程安全的审计哈希链（src/audit/store.rs）： 加固内存中的 WORM 审计序列计数器，确保原子递增排序，消除高并发情况下的序列缺口和竞态条件。
• 生产环境尽职审查整改： 针对输入边界、内存分配、安全关闭信号和 API 错误封装等方面，解决了全部 14 项全面审查发现的问题（H1–H3、M1–M6、L1–L5）。

v0.29.0 — 可配置的 MCP 协议版本、HTTP 客户端接入与安全加固

• 一键客户端安装中的 HTTP 传输选项（src/cli.rs、src/client_adapter.rs）： 为客户端接入新增 --transport http 标志和交互式传输方式选择（warmplane client install <target> --transport http），将客户端直接配置为连接守护进程的流式 HTTP 端点。
• 可配置的 MCP 协议版本（src/config.rs、src/http_v1/mcp_transport.rs）： 新增 supportedProtocolVersions 配置选项，允许运营人员自定义 MCP 流式 HTTP 初始化期间公布的协议版本数组。
• Webhook SSRF 允许列表保护（src/config.rs、src/http_v1/webhooks_api.rs）： 新增 policy.webhook.allowed_urls 校验，对发出的 Webhook 测试请求实施显式 URL 允许列表。
• 配置导入的路径遍历防护（src/config_import.rs）： 在配置导入操作中新增严格的路径包含性校验（validate_safe_import_path），阻止相对路径越界（../）。
• 限制搜索分配与执行（src/search/hybrid.rs）： 限制搜索请求上限和向量分配，防止不可信输入导致内存耗尽。

v0.28.0 — 实时 MCP list_changed 通知、SEP-1319 发现提示与直通工具

• 实时 MCP list_changed 通知（src/mcp_server.rs、src/daemon/state.rs）： 在 tools、resources 和 prompts 能力中声明 listChanged: true（enable_tool_list_changed、enable_resources_list_changed、enable_resources_subscribe、enable_prompts_list_changed）。当上游服务挂载/卸载，或配置/别名发生变更时，活跃的 MCP stdio 会话会收到实时 JSON-RPC 通知。
• SEP-1319 元数据发现提示（src/mcp_server.rs）： 向 notifications/tools/list_changed 注入 io.warmplane/discovery_hint 元数据载荷，建议 Agent 运行 capabilities_list 以发现后端能力，避免工具架构产生持续的 token 开销。
• 顶层原生工具直通（src/config.rs、src/mcp_server.rs、src/cli_config.rs）： 将能力别名（passthrough: true）提升为原生顶层工具，直接通过 tools/list 导出，并采用严格的 MCP 名称清理规则（^[a-zA-Z0-9_-]{1,64}$）和直接调度解析。
• 动态变更的 WORM 审计轨迹（src/daemon/lifecycle.rs、src/http_v1/config_api.rs）： 针对服务挂载/卸载、别名变更、安全策略更新和配置文件变更，新增防篡改的 SHA-256 哈希链式 AuditEventType::ConfigMutation 审计记录。
• 交互式别名管理 UI（ui/src/components/aliases.ts、ui/src/main.ts）： 在 Control Deck Web UI 中新增点击编辑别名行、直通切换胶囊徽标和输入清理功能。

v0.27.0 — 自定义别名描述、精简的大模型工具签名与任务检查器

• 自定义别名描述与文档字符串覆盖（src/config.rs、src/supervisor.rs）： 升级别名配置模型以支持多态定义（AliasTarget）。别名可以是简单的目标字符串（"alias": "server.tool"），也可以是详细对象（"alias": { "target": "server.tool", "summary": "...", "description": "..." }），使平台工程师和开发者无需修改上游源代码，即可修复或改进描述不佳的上游工具，提升大模型的零样本易用性。
• 精简的大模型工具签名（src/supervisor.rs、src/daemon/types.rs、src/engine/types.rs）： 从 JSON Schemas 派生确定性的精简参数签名（tool_name(req1, [opt1], [opt2])），并区分必填字段与可空/可选属性。该签名显示在 MCP capabilities_list、目录搜索和 Web UI 索引摘要中。
• 双向别名解析（src/supervisor.rs）： 修复监督式发现将目标相等性与已配置别名键进行比对时出现的映射不匹配问题，确保规范目标能够无缝呈现给客户端界面。
• 丰富的任务检查器模态框与双重控制（ui/src/components/tasks.ts）： 增强 Tasks & Approvals UI，新增专用检查器模态框、实时状态查看器、格式化的 JSON 载荷检查，以及检查/取消双重操作控件。
• 服务模板缺少密钥警告（ui/src/components/servers.ts、src/vault/）： 当必需的模板环境变量或 Keychain 密钥尚未配置时，在服务卡片和诊断信息中新增实时 (Missing Keys) 警告徽标和状态指示器。
• 实时别名配置 API 与 UI： 在 Control Deck 的 Aliases 选项卡（ui/src/components/aliases.ts）和 CLI（warmplane config alias set --summary ...）中新增自定义摘要输入，并在磁盘变更时自动实时热重载并协调配置。

v0.26.1 — MCP Stdio 流隔离与日志修复

• MCP Stdio 流隔离（src/telemetry.rs）： 配置 tracing_subscriber::fmt::layer() 将内容写入 stderr（.with_writer(std::io::stderr)）。防止运行时结构化 JSON 日志和 span 诊断信息污染 stdout。
• 继承上游进程的 Stderr（src/supervisor.rs）： 上游 stdio 子进程现在会显式继承 Warmplane 的标准错误流（cmd.stderr(std::process::Stdio::inherit())）。防止上游启动横幅（例如 Memory 和 Filesystem 服务横幅）泄漏到 stdio JSON-RPC 会话中。
• 客户端协议可靠性： 修复了使用 AI Agent 和 IDE 以 stdio 服务模式运行 Warmplane（warmplane mcp-server）时的 JSON-RPC 初始化失败问题（invalid message version tag ""; expected "2.0"）。

v0.26.0 — 一键同步 AI 客户端、原生密钥库、ChatOps 与配置文件治理

• 一键 AI 客户端注入与生态同步（src/client_sync.rs）： 零配置的双向 MCP 适配器引擎。可检测、注入和分离 Warmplane 代理配置，并绑定配置文件，支持 Claude Desktop（macOS、Linux、Windows）、OpenCode、Claude Code CLI（CLAUDE_CONFIG_DIR）、Cursor（全局和工作区）、Zed Editor（context_servers）、Windsurf，以及 Roo Code / Cline。
• 100% Agent 配置导入兼容性（src/config_import.rs）： 统一发现外部配置，并使用可识别方言的解析器（StandardMcpServers、OpenCode mcp、Zed context_servers），同时防止自身代理。
• 原生 OS 密钥链库与动态密钥（src/vault/）： 新增安全的 OS 级凭据管理（warmplane secret set/get/delete）和环境变量中的动态运行时密钥展开（keychain://、op://、env://），并对日志中的密钥进行掩码处理。
• 可执行操作的 ChatOps 与双向 Webhook（src/chatops/）： 为 Slack（Block Kit）、Discord（Embeds）和 Microsoft Teams（Adaptive Cards）提供丰富的交互式审批卡片，并支持 HMAC-SHA256 签名验证。
• 按配置文件治理策略（src/policy.rs、ui/src/components/policy.ts）： 提供精细的配置文件级 allow、deny 和 requireApproval 规则，可覆盖全局策略或限定其适用范围。
• Constellation 边界与动态可见性（ui/src/components/servers.ts）： 提供可视化的 constellation 徽章（✔ IN CONSTELLATION、🚫 EXCLUDED FROM PROFILE）、自动派生的 <server>.* 隐式策略拒绝规则，以及一键成员资格切换。
• 服务诊断与一键重启： 新增实时错误诊断模态框、服务重启端点（POST /v1/config/servers/:id/restart），以及针对全部 25 个 MCP 服务模板的自动化冒烟测试套件（scripts/test-templates.ts）。
• 动态目录 ETag 指纹与布局稳定： 采用配置文件感知的指纹哈希（sha256:...-p:<profile_id>:<hash>），确保 ETag 立即失效并重新填充 Playground 目录。通过持续预留滚动条间隙，稳定视口布局。

v0.25.2 — 官方 MCP 注册表元数据与 MCPB 打包格式

• MCPB 分发格式（packaging/mcpb/、.github/workflows/release-artifacts.yml）： 新增自动化构建和打包流程，用于生成特定平台的 Model Context Protocol Bundle（.mcpb），其中包含独立二进制文件、引导配置和标准化清单（manifest_version: "0.3"）。
• 官方 MCP 注册表元数据（server.json）： 发布工作流现在会自动生成符合官方 server.schema.json 规范（io.github.warmplane/warmplane）的规范注册表元数据，并附带多架构 SHA-256 软件包摘要。
• Homebrew Tap（Warmplane/homebrew-tap）： 配置官方 Tap 分发，提供预构建的 macOS 和 Linux formula（brew tap warmplane/tap && brew install warmplane）。

v0.25.1 — 异步任务完成状态机修复

• 异步任务终结（src/engine/mod.rs、src/http_v1/execute.rs）： 修复了一项回归问题：异步能力执行（async_task: true 或 Prefer: respond-async）以及在 Human-in-the-Loop（HITL）输入响应后恢复的任务，会一直停留在 TaskStatus::Working。后台工作器现在会可靠地将终止状态（带有 result 的 TaskStatus::Completed，或带有结构化错误的 TaskStatus::Failed）直接写入 TaskRegistry。
• 嵌入式任务生命周期测试（tests/embedded_tests.rs、tests/tasks_tests.rs）： 新增全面的自动化集成测试，验证在提交审批和直接调用异步任务后，get_task 和 list_tasks 能观察到终止的 completed 状态及上游负载。

v0.25.0 — Control Deck 任务与 HITL UI、进程内嵌入式任务 API

• Control Deck 任务与审批中心（ui/src/components/tasks.ts）： 将审核队列升级为统一的任务与审批仪表板（data-tab="tasks"），提供实时状态 KPI（input_required、working、completed、cancelled/failed）、交互式操作卡片（内嵌 MRTR 输入解析表单，支持布尔值、JSON 编辑器和文本字段）、TTL 倒计时器以及协作式取消控件。
• MCP Playground 异步执行模式： 在工具测试 Playground 中新增 “⚡ Async Task Mode” 切换开关，并提供交互式 202 Accepted 任务卡片预览，可一键跳转至任务与审批审核面板。
• 嵌入式 Rust 任务管理 API（ControlPlaneHandle）： 在进程内的 ControlPlaneHandle 上开放直接任务管理方法（list_tasks、get_task、update_task、cancel_task），让嵌入式应用无需 HTTP 或 JSON-RPC 序列化开销即可管理异步 SEP-2663 任务。
• 总览驾驶舱与徽章集成： 在总览驾驶舱中新增 “Tasks & HITL State” 遥测卡片，并将侧边栏实时徽章关联到尚待处理的 input_required 任务。

v0.24.0 — SEP-2663 任务扩展、统一 HITL 执行与 MCP 路线图对齐

• SEP-2663 任务扩展实现（src/tasks.rs）： 实现官方 io.modelcontextprotocol/tasks 能力，支持原子持久化存储（tasks.json）、安全的 TTL 到期检测，以及 oneshot 输入响应通道（TaskWaitSender / TaskWaitReceiver）。
• 统一的 HITL 审批与异步任务状态机： 将 Human-in-the-Loop 审批工作流和异步工具执行统一接入 SEP-2663 生命周期。需要操作员门控审批或使用 async_task: true / Prefer: respond-async 请求的工具执行，会返回 202 Accepted，并附带 resultType: "task" 和 status: "input_required"，同时内嵌 MRTR inputRequests。
• HTTP REST 任务 API（/v1/tasks/*）： 新增全面的任务检查与控制 REST 端点：GET /v1/tasks（列表）、GET /v1/tasks/:id（轮询状态/结果）、POST /v1/tasks/:id/update（提交 inputResponses 以唤醒工作器）和 POST /v1/tasks/:id/cancel（协作式取消）。
• MCP 门面服务集成： 在 MCP 门面服务上开放 task_get、task_update 和 task_cancel 工具，供 Agent 直接编排。
• CLI 任务子命令与异步执行标志： 新增 warmplane tasks list、warmplane tasks get <id>、warmplane tasks update <id> -r '<json>'、warmplane tasks cancel <id>，以及 warmplane call-capability 的 --async-task 标志。
• MCP 协议路线图战略分析： 发布 docs/MCP_ROADMAP_REPORT.md，分析官方 MCP 路线图，以及 Warmplane 在无状态传输、无会话路由和渐进式能力发现方面的架构对齐情况。

v0.23.0 — 嵌入式 Rust 引擎、进程内控制平面与 Facade 适配器重构

• 进程内嵌入式 Rust 库引擎（EmbeddedWarmplane、ControlPlaneHandle）： 将 Warmplane 暴露为纯进程内库，无需 HTTP、守护进程子进程或 JSON-RPC 序列化开销。调用方可通过 EmbeddedWarmplane::start(config) 或 EmbeddedWarmplane::start_from_path(path) 在自己的 Tokio 运行时中直接启动引擎，并通过类型化的 ControlPlaneHandle 方法（list_capabilities、describe_capability、search_capabilities、call_capability、batch_call、read_resource、get_prompt、health_status）进行交互。
• 强类型泛型信封与错误模型： 在 warmplane::engine::types 中新增 Envelope<T>、WarmplaneError、CapabilitySummary、CapabilityDetail、ExecutionOptions、ReadResourceOptions、GetPromptOptions 和 EngineHealthStatus，保留结构化诊断信息（request_id、trace_id、retry、operator），用于程序化编排。
• MCP 标准输入输出服务 Facade 适配器重构： 重构 mcp_server.rs，将所有工具调用执行、搜索、描述、批量执行以及资源／提示词分发直接委托给 ControlPlaneHandle，消除重复逻辑并统一执行管线。
• 嵌入式引擎集成测试套件： 在 tests/embedded_tests.rs 中新增专用集成测试，涵盖嵌入式引擎生命周期启动、降级服务处理、健康状态检查和优雅取消。

v0.22.0 — 可流式 HTTP/SSE MCP 传输、交互式 Playground 与 UI 润色

• 可流式 HTTP/SSE MCP 服务传输（mcp-http-server）： 构建独立及与守护进程共置的 HTTP/SSE MCP 服务端点（/mcp/sse、/mcp/messages），让远程 AI Agent 和 IDE（Cursor、Windsurf、Claude Desktop）能够通过标准 HTTP/SSE 网络连接，并自动保持连接，无需客户端漂移。
• 与守护进程共置及配置（mcpHttpServer）： 新增一流配置支持（mcpHttpServer），可在核心 /v1 HTTP 守护进程旁自动初始化 HTTP/SSE MCP 服务实例。
• 配置档案限制与绑定认证门控： 在 MCP 服务传输中集成配置档案限制（profile），严格隔离向远程客户端公开的工具和资源。绑定到公共非环回网络接口（0.0.0.0／外部 IP）时，自动强制执行 Bearer 令牌认证。
• 交互式 MCP Playground 易用性： 在 Web Control Deck MCP Playground 中新增示例模板注入、动态格式切换、基于架构生成参数，以及实时参数验证。
• UI 过渡效果、冲突检查与润色： 去除仪表板各标签页重复的页面标题，引入流畅的 CSS cubic-bezier 过渡效果，为模态框背景添加动画并支持 prefers-reduced-motion 无障碍设置，同时新增冲突防护和自动生成唯一服务 ID 的功能。

v0.21.0 — 命名服务器星座（配置档案）、信号生命周期与集成方生态

• 命名服务器星座（配置档案）： 添加了一流的配置档案支持（ProfileConfig），可将与任务相关的上游 MCP 服务子集分组为命名星座（例如 coding、research、data_science）。
• 动态配置档案选择与作用域 ETag 分区： 支持通过 X-Warmplane-Profile 标头和 ?profile= 查询参数按请求指定配置档案作用域。目录端点（/v1/capabilities、/v1/resources、/v1/prompts）和搜索（/v1/capabilities/search）会动态筛除当前配置档案之外的条目，并维护确定性的、按配置档案分区的 ETag（sha256:...-p:<profile_id>）。
• MCP Facade Stdio 配置档案筛选： 为 warmplane mcp-server 和 warmplane list-capabilities 添加了 --profile <name> CLI 选项，为 Agent 宿主提供严格限定作用域的 MCP 工具和资源界面。
• Web Control Deck 配置档案中心： 在 Web UI 控制面板中添加了交互式可视化配置档案管理器，支持一键切换当前星座、切换服务器以及实时筛选目录。
• 信号处理与进程销毁加固： 集成了在收到 SIGINT（Ctrl-C）/ SIGTERM 时立即分发 tokio_util::sync::CancellationToken、解除 SSE 流排空阻塞、通过 kill_on_drop(true) 防止子进程孤立，并强制执行 3 秒的有界安全关闭超时。
• 开发者与集成方生态指南： 发布了官方 Rust 集成方指南、TypeScript 集成方指南 和 幂等性架构专题文章。

v0.20.0 — 多租户 RBAC 与确定性目录分区

• 多租户 RBAC 引擎（src/rbac）： 构建了基于角色的访问控制引擎，支持静态 API 令牌、配置中的令牌到角色映射（rbac.tokens），以及使用可配置密钥（rbac.jwt_secret）进行的加密 HMAC-SHA256 对称 JWT 签名验证。
• 确定性目录分区与作用域筛除： 重构了 /v1/capabilities、/v1/resources、/v1/prompts 和 /v1/capabilities/search，使其根据调用方角色和生效策略动态筛选条目。未授权条目在目录列表和搜索查询中完全不可见。
• 租户上下文注入与不可抵赖审计： 通过 RBAC 守卫中间件（src/rbac/middleware.rs）将解析后的 TenantContext（tenant_id、role、actor_id、grant_id、effective_policy）注入请求扩展。将经过验证的租户/主体元数据自动绑定到 WORM 审计事件中。
• 角色策略覆盖与 HITL 委派： 支持细粒度角色定义（RolePolicyConfig），可配置自定义 allow、deny、require_approval 和 redact_keys 规则，以覆盖或合并基础系统策略。
• 集成测试套件： 添加了专用 RBAC 集成测试（tests/rbac_integration.rs），涵盖令牌身份验证、搜索筛选、目录隔离、策略边界执行和多租户审计验证。

v0.19.0 — 客户端委托的 MCP 采样、HTTP/SSE 监督循环与加固

• 客户端委托的 MCP 采样（sampling/createMessage）： 实现了客户端委托的大模型补全反向 RPC 处理（src/sampling.rs）。上游服务或 Agent 提交采样请求，并生成受跟踪的工单（samp_<timestamp>_<seq>），支持同步长轮询或异步生命周期端点（POST /v1/sampling/create_message、GET /v1/sampling/requests、GET /v1/sampling/requests/:id、POST /v1/sampling/requests/:id/respond）。
• 持久化采样状态： 通过 AtomicFile<HashMap<String, PendingSamplingRequest>> 添加了原子化、重启后可恢复的磁盘存储（sampling.json），并加入自动过期清理任务。
• 自愈式 Streamable HTTP/SSE 监督器： 将远程 HTTP/SSE MCP 服务集成到监督循环中，支持自动重连退避、目录协调和降级启动状态报告。
• 安全与 DoS 加固： 将语义向量搜索的候选能力嵌入数量上限设为 MAX_VECTOR_SEARCH_CANDIDATES = 250；将审计导出查询限制为 MAX_IN_MEMORY_AUDIT_EVENTS（20,000）；对 OAuth 代理请求强制执行 Host 标头和环回 Origin 检查。
• CI 门禁与 TypeScript 类型检查： 在 Web UI CI 流水线中添加自动 TypeScript 类型检查（tsc --noEmit），并将推送触发范围限制为 main，以消除重复运行。
• 务实的 Rust 合规性： 全部 51 个源文件均达到 100% 合规，且包含标准合规标头（// Rust guideline compliant YYYY-MM-DD）。

v0.18.0 — 持久化状态子系统、优雅关闭、CI UI 自动化与端到端测试套件

• 持久化状态子系统： 为 Human-in-the-Loop 待处理审批（approvals.json）、幂等执行记录（idempotency.json）、OAuth2 令牌（oauth_tokens.json）和目录变更事件（catalog_events.json）添加了原子化、重启后可恢复的磁盘存储（AtomicFile<T> 和 StateDirectory）。在 McpConfig 中添加了 state 配置块，并新增 warmplane config state show/set CLI 命令。
• 优雅的信号处理与子系统关闭： 在 Unix 和 Windows 上添加了稳健的 SIGINT（Ctrl+C）和 SIGTERM 信号捕获，集成了优雅的 HTTP 服务排空、异步审计工作线程刷新（AuditWorkerMsg::FlushAndShutdown），并确保关机时干净终止 stdio 子进程。
• 务实的 Rust 合规性： 全部 51 个源文件均达到 100% 合规，且包含标准合规标头（// Rust guideline compliant YYYY-MM-DD）。
• CI 自动化 Web UI 构建与偏差门禁： 将 Bun 集成到 GitHub Actions CI（ci.yml）和发布流水线（release-artifacts.yml），加入自动构建步骤，并严格检测 git diff --exit-code ui/dist/index.html 的偏差。
• 全面的端到端集成测试套件： 实现了专用 E2E 测试框架（tests/e2e_tests.rs），用于测试 stdio MCP 协议握手、实时 TCP SSE 流式传输、配置热重载、模拟 OAuth2 RFC 8414 提供方往返交互（包括无提示的 401 令牌刷新）以及监督器恢复。

v0.17.0 — 360° MCP 探索器、可视化批处理流水线构建器与 WORM 审计分页

• WORM 审计多字段搜索与分页： 新增对 11 个元数据字段进行不区分大小写的子串搜索，以及按结果状态和服务筛选、偏移量／限制分页（/v1/audit/events），并支持上下文感知的 CSV 和 JSONL 导出下载（/v1/audit/export）。
• MCP 资源探索器与实时内容读取器： 新增 360° 资源发现浏览器，包含协议方案徽标（file://、postgres://、github://、memory://、sqlite:// 等）、元数据／MIME 查看器，以及支持上下文提炼（_jsonpath、_limit_lines、_truncate_bytes）的实时内容读取器。
• MCP 提示词模板工作室： 新增动态提示词模板浏览和参数表单生成，并提供 REQUIRED 验证徽标、渲染解析后的系统／用户提示词封装（/v1/prompts/get）。
• 在途操作取消： 新增交互式 UI 执行取消控件，支持实时执行计时器和即时协作式中止（POST /v1/operations/:id/cancel）。
• 可视化多步批处理流水线构建器： 新增交互式模态流水线编辑器，可串联工具、插入参数变量（${steps[0].result.id}），并为每个节点提供容错能力（POST /v1/tools/batch_call）。
• 实时 SSE 状态同步： 将 /v1/resources/updates SSE 流接入控制台，自动刷新资源、提示词和目录数据流。

v0.16.0 — 企业级安全加固、审计加密完整性与生命周期韧性

• API 令牌身份验证与中间件防护： 新增 --auth-token CLI 参数、McpConfig.auth_token 配置字段，以及对 WARMPLANE_AUTH_TOKEN 环境变量的支持，通过 Bearer/X-Warmplane-Key 身份验证安全保护守护进程端点。
• OAuth 代理安全与密钥屏蔽： 通过 Host 验证和跨源浏览器拦截加固 OAuth 代理监听器；在日志输出中屏蔽 state 和 PKCE code_challenge 密钥。
• 加密 WORM 审计完整性与 HMAC 签名： 将全部 20 个持久化元数据字段纳入哈希链摘要（work_item_id、client_ip、resource_uri、execution_latency_us、error_message）；新增 HMAC-SHA256 密钥摘要计算和检查点生成，以便进行外部加密锚定。
• 密钥净化与脱敏： 增强不区分大小写的脱敏匹配，并内置默认敏感密钥列表（token、secret、password、key、authorization 等）；限制外部 HITL webhook 事件仅传输 sanitized_args；在 CLI 命令打印内容前净化密钥。
• 监督器与断路器协调： 监督器重新连接成功后自动重置断路器；在 HalfOpen 断路器状态下新增单航探测限制；实现 60 秒滑动窗口重启退避；在目录协调期间清理已移除的项目；卸载服务时清理断路器。
• 资源上限与安全控制： 强制执行 MAX_BATCH_STEPS = 50 和 DEFAULT_BATCH_TIMEOUT_MS = 60_000 执行预算；将通配符 JSONPath 输出扩展限制为 10,000 项，将搜索结果限制为 100 项；对未知操作取消请求返回 POLICY_DENIED（HTTP 403）和 404；净化 CSV 审计导出内容以防公式注入。
• CI 质量门禁与依赖审计： 在 GitHub Actions CI 中集成原生 cargo-audit 扫描；更新依赖以解决所有已报告的安全公告问题。
• CLI 版本标志： 在 warmplane 二进制解析器中启用标准 --version 和 -V 标志。

v0.15.0 — 容错、启动韧性与 Control Deck 功能对齐

• 启动韧性与降级启动： 当上游服务（例如 Docker、远程 SSE 端点或未配置的工具）故障或超时时，守护进程仍可正常启动。故障服务会标记为 degraded，不会导致守护进程崩溃，也不会阻塞其他正常的上游服务。
• 进程监管器与熔断器： 支持按服务和全局配置熔断器（failureThreshold、cooldownMs、autoRestart、maxRestarts），跟踪状态（CLOSED、OPEN、HALF-OPEN），并通过指数退避重启监管机制恢复服务。
• Web UI 功能全面对齐：
  • 服务中心：服务器卡片编辑工作流（✏️ Edit）、实时熔断器遥测徽标和服务韧性指示器。
  • 模板向导：在一键精选服务配置中直接提供容错与监管器配置折叠面板。
  • 交互式试用场：上下文提炼控件（_jsonpath、_limit_lines、_truncate_bytes）和执行延迟测量。
  • 响应式 Bento-Grid 概览卡片，带实时健康状态指示点（connected 🟢、degraded 🟡、error 🔴）。
• CLI 韧性配置： 提供 warmplane config resilience set 和 warmplane config resilience show，用于无头熔断器管理。

v0.14.0 — Agent 增强套件：门面搜索、上下文提炼与多步骤批处理

• MCP 门面混合搜索： 通过 MCP stdio 门面开放 capability_search 工具，支持按关键词、标签、服务器 ID 和执行模式筛选。
• 上下文提炼与截断： 为 /v1/tools/call 和 capability_call 添加 _jsonpath、_limit_lines 和 _truncate_bytes 修饰符，防止过大的输出耗尽大模型上下文窗口。
• 多步骤链式批量调用： 新增 POST /v1/tools/batch_call 和 capabilities_batch_call，支持通过 $step.field 引用插值，在单次往返中执行存在依赖关系的工具调用。

v0.13.0 — 人机协同（HITL）审批引擎与签名 Webhook

• 审批拦截器： 对敏感能力调用实施策略驱动的暂停（requireApproval）。
• 运维人员 REST API： 提供端点以列出（/v1/approvals）、检查、批准并修改参数（/v1/approvals/:id/approve），或拒绝（/v1/approvals/:id/reject）。
• 签名 HMAC Webhook： 在审批生命周期事件发生时实时分发 Webhook，并在标头中附带 SHA-256 HMAC 签名。
• 可配置 TTL 过期： 自动超时过期（approvalTimeoutSecs），并返回结构化取消封装。

v0.12.0 — 加密 WORM 审计日志与 SIEM 流式传输

• 对工具执行和 HITL 决策事件采用只追加的线性 SHA-256 哈希链。
• 提供审计验证和导出端点（/v1/audit/...），并支持 Splunk HEC 和通用 Webhook 摄取。

v0.11.0 — Control Deck Web UI 与动态上游热重载

• Control Deck Web UI： 在 /ui 和 / 提供内嵌的零依赖 Web 仪表板，包含实时遥测、服务器管理器、交互式工具试用场、策略/脱敏管理器和别名注册表。
• 动态上游挂载，零停机： 无需重启守护进程，即可通过 REST/UI/CLI 动态挂载和卸载 stdio、HTTP 和 OAuth2 上游工作进程。
• 动态目录与 ETag： 采用并发安全的状态管理，在服务器变更时自动重新计算 SHA256 ETag 并发送 SSE 资源通知。
• 显式配置热重载： 新增 warmplane reload CLI 命令和 POST /v1/config/reload 端点，可根据对 mcp_servers.json 的手动修改，妥善协调内存中的工作进程。

v0.10.0 — CLI 配置管理与生态导入器

• 新增 warmplane server（add、remove、list、get、test）命令，提供交互式 inquire 向导和基于标志的无头自动化。
• 新增 warmplane config（init、show、import、alias、policy），用于安全、事务性的配置变更。
• 新增从 Claude Desktop、Cursor 和 Zed 设置中自动发现并导入配置的功能。
• 新增原子配置文件写入（fs::rename），防止 JSON 损坏。

v0.9.0 — 符合 MCP 2026-07-28 规范、MRTR 与订阅

• 升级至官方 MCP Rust SDK rmcp 3.1.2 和 reqwest 0.13。
• 将默认协议版本设为 "2026-07-28"，并向后兼容 "2025-11-25"。
• 在 HTTP REST、stdio 门面和上游工作进程中新增多轮往返请求（MRTR）支持（input_responses 和 request_state）。
• 新增缓存提示（ttl_ms: 300000、cache_scope: "public"），并在目录列表中按字母顺序进行确定性排序。
• 在 stdio 门面中新增 subscriptions_listen 工具，并新增用于实时通知的 /v1/resources/updates SSE 流。
• 验证了 OAuth 2.0 流程的 RFC 9207 / SEP-2468 iss 回调验证。

v0.8.0 — 语义向量嵌入与 FastEmbed ONNX 流水线

• 集成 FastEmbed ONNX 嵌入流水线，在可选的 --features semantic-search 功能下提供稠密余弦向量相似度搜索。
• 结合 BM25 关键词匹配与稠密向量搜索的混合倒数排名融合。

v0.7.0 — 务实的 Rust 现代化与构建器模式

全面采用 Microsoft 的《Pragmatic Rust Guidelines》（AGENTS.md）。为核心状态（AppStateBuilder）、搜索筛选器（SearchFilterBuilder）和请求上下文（RequestContextBuilder）实现了 Builder Pattern（M-INIT-BUILDER）。改进了错误安全性（M-PANIC-IS-STOP）、结构化日志记录（M-LOG-STRUCTURED）、规范文档（M-CANONICAL-DOCS）和灵活的 trait 互操作（M-IMPL-ASREF）。

v0.6.0 — 幂等性、取消与重试元数据

传递 Idempotency-Key / X-Idempotency-Key，以对并发工具调用去重。通过取消端点或 CLI 中止任何正在进行的请求。现在，每个响应信封都包含结构化的 "retry" 元数据（classification + state），供编排器感知的重试逻辑使用。

v0.5.0 — 请求上下文与关联

结构化的 RequestContext（operation_id、work_item_id、actor_id、grant_id）贯穿所有执行信封和跟踪 span。提供 HTTP 请求头回退机制（X-Request-ID、X-Operation-ID、X-Actor-ID、X-Grant-ID）。

v0.4.0 — 目录版本控制与缓存验证

SHA-256 目录版本。所有目录读取均包含 ETag 请求头；If-None-Match 条件请求会返回 304 Not Modified。GET /v1/catalog/events 变更源支持基于游标的分页。

v0.3.0 — 混合搜索

POST /v1/capabilities/search 支持 BM25 评分、可选的 FastEmbed 向量嵌入、标签 / 服务 ID 筛选和排序结果。 POST /v1/capabilities/search 支持 BM25 评分、可选的 FastEmbed 向量嵌入、标签 / 服务 ID 筛选和排序结果。

---

文档

文档	说明
docs/USER-GUIDE.md	完整使用指南：配置、模式、所有 CLI 命令、身份验证、策略
docs/PERFORMANCE.md	基准测试方法、延迟百分位数和性能分析结果
docs/openapi.yaml	OpenAPI 3.1 规范
docs/config.schema.json	mcp_servers.json 的 JSON Schema
docs/OBSERVABILITY.md	结构化日志、OTLP 配置、跟踪关联
docs/INSTALL.md	构建变体、分发说明
docs/DEPLOYMENT.md	生产环境部署运行手册