服务发现 | LMSP 1.0 草案

3.1 发现方式

客户端按以下顺序尝试各种方式来发现服务：

手动配置。 用户直接输入服务地址。
探测本机约定地址。 客户端向候选地址请求 /.well-known/lmsp.json。约定的候选地址是 http://127.0.0.1:17832 和 http://[::1]:17832。
局域网发现。 客户端通过 mDNS 与 DNS-SD 浏览 _lmsp._tcp.local.。

某种方式只要得到一份有效的服务描述（第 3.3 节）即告成功。用户手动输入的地址始终优先于自动发现的地址。

3.2 局域网广播

DNS-SD 使用 PTR 记录查找服务实例，通过 SRV 记录获取主机与端口，通过 TXT 记录携带少量附加信息；与 mDNS 结合可实现零配置的局域网发现（RFC 6763、RFC 6762）。

示例广播：

Service type:   _lmsp._tcp.local.
Instance name:  Workstation LMSP._lmsp._tcp.local.

TXT record:
  v=1
  id=svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2
  path=/
  auth=pairing

TXT 键	含义
`v`	广播格式的版本。LMSP 1.0 为 `1`。
`id`	服务 id，与服务描述中的 `service.id` 相同。
`path`	服务根路径的 URL 路径。客户端请求 `{path}.well-known/lmsp.json`。
`auth`	认证提示。`pairing` 表示客户端必须先配对才能使用服务。

规则：

服务不得在 TXT 记录中放置访问令牌、模型清单、文件路径或其他敏感信息。该记录只负责找到服务，真实能力必须从服务描述中读取。
服务必须默认关闭 mDNS 广播，仅在用户明确开启“局域网发现”时才启用。仅在本机使用的服务无需广播。
在局域网中广播的服务需要监听回环地址之外的地址，而这只有在局域网模式下才被允许（第 10.5 节）。
客户端必须把 TXT 记录视为未经验证的提示，并通过读取服务描述来确认服务。

3.3 服务描述文档

GET /.well-known/lmsp.json

服务必须以 application/json 提供该文档，且不要求认证。

{
  "protocol": "lmsp",
  "versions": ["1.0"],
  "service": {
    "id": "svc_01J8M4Y8K6M5E6K6Z7Z0Y8W3M2",
    "name": "Workstation Local Models",
    "version": "1.0.0"
  },
  "interfaces": [
    {
      "kind": "lmsp",
      "version": "1.0",
      "url": "http://127.0.0.1:17832/lmsp/v1",
      "transport": "http+json"
    },
    {
      "kind": "openai",
      "version": "responses+chat",
      "url": "http://127.0.0.1:17832/v1",
      "transport": "http+json"
    }
  ],
  "capabilities": {
    "streaming": true,
    "tasks": true,
    "event_resume": true,
    "conversations": true,
    "model_management": true
  },
  "authentication": {
    "type": "bearer",
    "pairing_url": "http://127.0.0.1:17832/lmsp/v1/pair"
  },
  "openapi": "http://127.0.0.1:17832/lmsp/v1/openapi.json"
}

字段	含义
`protocol`	始终为 `"lmsp"`。
`versions`	服务支持的 LMSP 版本，格式为 `major.minor` 字符串。
`service`	`id` 是稳定的服务标识符，`name` 是显示名称，`version` 是服务软件的版本。
`interfaces`	所提供的接口。每项包含 `kind`（`lmsp`、`openai` 或 `ollama`）、`version`、基础 `url` 和 `transport`。对 `openai` 而言，`version` 表示所提供的 API 系列，例如 `responses+chat`。
`capabilities`	布尔型功能标志，见下表。
`authentication`	`type` 为 `bearer`。`pairing_url` 是客户端用配对码换取令牌的地址（第 10.2 节）。
`openapi`	描述 LMSP 接口的 OpenAPI 文档的 URL。

能力标志：

标志	含义
`streaming`	响应可以通过服务器发送事件流式返回。在 1.0 中必须为 `true`。
`tasks`	提供异步任务。在 1.0 中必须为 `true`。
`event_resume`	任务事件流可以订阅和恢复（`GET /lmsp/v1/tasks/{task_id}/events`）。
`conversations`	服务保存响应，因此 `store` 和 `previous_response_id` 可用，`GET /lmsp/v1/responses/{response_id}` 也可用。
`model_management`	可以显式加载和卸载模型。

3.4 客户端行为

客户端：

应从 versions 中选择自己也支持的最高版本。
应根据自己所能使用的协议，从 interfaces 中选择 LMSP 接口或 OpenAI 接口。
必须只使用服务描述中声明的能力，缺失的标志视为 false。
必须忽略不认识的扩展字段。
应定期或在请求失败时重新读取服务描述，而不是永久缓存。
应用 service.id 而不是地址来记住所选的服务，因为地址可能变化。