fix(remotedevice): 设备通道名改用 - 分隔并派生合规名（v1.3.0 部署后 agent 完全不应答的根因）

## 事故

v1.3.0 部署到生产后，**整个 agent 不应答**：任何对话都返回
`all 3 providers failed, last error: api error 403: model "claude-opus-5" is not allowed for this key`。
回滚到 1.2.2 立即恢复（部署前 403=0/成功对话=10，部署后 403=5/成功对话=0）。

## 根因（网关日志给出的原文）

```
tier 3 gozen/deepseek-v4.1-flash: api error 400: [invalid_request_error]
  Invalid 'tools[299].function.name': string does not match pattern '^[a-zA...
```

设备的每设备输出通道名叫 `device/<id>`，内核按 `output_send__<通道名>` 生成工具 ⇒
`output_send__device/<id>` 里的 `/` 违反上游函数名规范 `^[a-zA-Z0-9_-]{1,64}$`。
上游不是"拒掉这一个工具"，而是**整条请求 400** ⇒ 网关 auto tier 全链条失败
（400/429/503 混在一起）⇒ 内核只能报"所有 provider 都失败"。
两台真实设备（waiter-fnnas / waiter-mainnas）一上线就登记了这种通道，于是必然触发。

## 修法（改插件，不改内核）

初版我在内核里加了"通道名净化 + 反向解析"层。用户否掉了这个方向，理由对：
**通道名是插件自己的声明，不合契约就该改插件**，不该让内核替插件擦屁股。
内核侧改动已全部回退（HEAD 干净）。

插件侧两处：
1. 分隔符 `device/<id>` → `device-<id>`（源码与来源标签统一，不留两套名字）。
2. 设备 id 是**外部输入**（设备自己声明），可能含空格/非 ASCII/超长 ⇒
   `deviceChannelName()` 把它派生为**合规且唯一**的通道名：
   保留 `[A-Za-z0-9_-]`、其它折成 `-`、主体截断到 32 字符（预算 64 = 13+7+32+7+…）、
   发生截断或撞名时追加 id 的 6 位短哈希。同一 id 恒定同名；真名仍用于路由与日志。

核心契约写进了插件注释与 SDK 文档（见 SDK 仓同批提交）：名字若来自外部输入，
**在插件侧派生合规名**，内核不会替你净化。

## 验证

- 新增 `TestDeviceChannelNameIsLLMFunctionNameSafe`：恶意 id（空格/符号/非 ASCII/超长/
  会折成同名的两个 id）都必须派生出**合法且互不重复**的通道名与工具名。
  反向验证：把分隔符改回 `/` 即 FAIL。
- 生产两台设备派生结果：`device-waiter-fnnas`、`device-waiter-mainnas`
  ⇒工具名 `output_send__device-waiter-fnnas`（37 字符，合规）。
- 全量 `go test ./...` = 37 包 ok / 0 FAIL；`-race`（remotedevice + core）无 DATA RACE。

internal/plugins/remotedevice/outputch.go

@@ -1,9 +1,9 @@
 package remotedevice
 
-// 设备输出通道：把"agent 主动发给设备"做成**每设备一个输出通道** `device/<id>`。
+// 设备输出通道：把"agent 主动发给设备"做成**每设备一个输出通道** `device-<id>`。
 //
 // 为什么是输出通道而不是再加一批工具：
-//   - **寻址**：`output_send__device/<id>` 直接指名道姓；模型看 `output_list_channels`
+//   - **寻址**：`output_send__device-<id>` 直接指名道姓；模型看 `output_list_channels`
 //     就知道当前有哪些设备在线，不必先 `devicedetect` 再往参数里塞 device_id。
 //   - **能力**：caps 由设备声明的 caps 映射，**内核**在发送前就按 caps 拦
 //     （把图片发给只支持文本的音箱会被拒，而不是等设备侧报错）。
@@ -15,7 +15,9 @@ package remotedevice
 // 它们的返回值（图像/命令输出/状态）必须进模型上下文，做成通道会丢掉这个语义。
 
 import (
+	"crypto/sha1"
 	"encoding/base64"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"log"
@@ -76,14 +78,75 @@ func deviceOutputCaps(caps []string, kind string) agentIO.OutputCapability {
 	return out
 }
 
-// deviceChannelName 是设备输出（也是输入）通道名：`device/<id>`。
+// deviceChannelName 由**设备自报的 id** 派生一个合规且唯一的通道名：`device-<派生值>`。
 //
 // 入站与出站**同名**：两者指的是同一台设备，分成两个名字只会让模型与授权表更难对。
-func deviceChannelName(id string) string { return "device/" + id }
+//
+// 为什么不能直接用 id：通道名会被内核拼进 LLM 的**函数名**（`output_send__<通道名>`），
+// 上游规范是 `^[a-zA-Z0-9_-]{1,64}$`；而设备 id 是**外部输入**（设备自己声明），
+// 可能含空格/非 ASCII/超长。违规的后果不是"这个工具不能用"，而是**整条请求被 400 拒绝** ——
+// 实测把生产打挂：`Invalid 'tools[299].function.name'`，网关 auto tier 全链条失败，
+// 内核只能报"所有 provider 都失败"，表现成"整个 agent 不说话了"。
+//
+// 派生规则（确定性，同一 id 永远同名）：
+//  1. 保留 [A-Za-z0-9_-]，其它字符折成 '-'；折叠后为空则用 "dev"
+//  2. 截断到 maxDeviceChannelSuffix 字符（给 "device-" 与短哈希留余量）
+//  3. 若发生截断，或该名字已被**另一个** id 占用，则追加 id 的 6 位短哈希
+//
+// 设备 id 本身仍用于路由与日志（真名不丢），通道名只是它派生的标识符。
+func (p *Plugin) deviceChannelName(id string) string {
+	p.devChansMu.Lock()
+	defer p.devChansMu.Unlock()
+	if p.devChans == nil {
+		p.devChans = make(map[string]string)
+	}
+	if name, ok := p.devChans[id]; ok {
+		return name
+	}
+	var b strings.Builder
+	for _, r := range id {
+		switch {
+		case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r >= '0' && r <= '9', r == '_', r == '-':
+			b.WriteRune(r)
+		default:
+			b.WriteByte('-')
+		}
+	}
+	base := b.String()
+	if base == "" {
+		base = "dev"
+	}
+	truncated := false
+	if len(base) > maxDeviceChannelSuffix {
+		base = base[:maxDeviceChannelSuffix]
+		truncated = true
+	}
+	name := "device-" + base
+	// 撞名检查：不同 id 折出同一个名字时必须可区分
+	for otherID, otherName := range p.devChans {
+		if otherName == name && otherID != id {
+			truncated = true
+			break
+		}
+	}
+	if truncated {
+		sum := sha1.Sum([]byte(id))
+		name += "-" + hex.EncodeToString(sum[:3])
+	}
+	p.devChans[id] = name
+	return name
+}
+
+const (
+	// maxDeviceChannelSuffix 是通道名主体的长度上限。
+	// 预算：上游函数名上限 64 = "output_send__"(13) + "device-"(7) + 主体 + "-"+短哈希(7)
+	// ⇒ 主体最多 37；取 32 留余量（改名/前缀变动不会立刻越界）。
+	maxDeviceChannelSuffix = 32
+)
 
 // wireDeviceChannels 把"设备上下线"接到通道的登记/注销上。
 //
-// 一台设备 = 一对**同名**通道 `device/<id>`：入站（设备上报 → agent）与出站
+// 一台设备 = 一对**同名**通道 `device-<id>`：入站（设备上报 → agent）与出站
 // （agent → 设备）。用**同步回调**而不是 ChangeChan（后者是 select+default，
 // 缓冲满会丢事件；丢一次就留下死通道或漏注册）。
 //
@@ -92,14 +155,14 @@ func deviceChannelName(id string) string { return "device/" + id }
 func (p *Plugin) wireDeviceChannels() {
 	p.registry.SetPresenceHandler(
 		func(meta DeviceMeta) {
-			_ = p.sdk.RegisterInputChannel(deviceChannelName(meta.DeviceID), sdk.ChannelDef{})
+			_ = p.sdk.RegisterInputChannel(p.deviceChannelName(meta.DeviceID), sdk.ChannelDef{})
 			p.ensureDeviceOutputChannel(meta.DeviceID)
 		},
 		func(id string) { p.dropDeviceOutputChannel(id) },
 	)
 }
 
-// ensureDeviceOutputChannel 给在线设备注册输出通道 device/<id>（幂等）。
+// ensureDeviceOutputChannel 给在线设备注册输出通道 device-<id>（幂等）。
 func (p *Plugin) ensureDeviceOutputChannel(id string) {
 	if p.sdk == nil || id == "" {
 		return
@@ -108,7 +171,7 @@ func (p *Plugin) ensureDeviceOutputChannel(id string) {
 	if !ok || !meta.Online {
 		return
 	}
-	ch := deviceChannelName(id)
+	ch := p.deviceChannelName(id)
 	caps := deviceOutputCaps(meta.Caps, meta.Kind)
 	desc := fmt.Sprintf("远程设备 %s（%s）：agent 主动向该设备发送内容；能力位 %s",
 		id, fallback(meta.Name, meta.Kind), agentIO.OutputCapability(caps).String())
@@ -130,7 +193,7 @@ func (p *Plugin) dropDeviceOutputChannel(id string) {
 	if p.sdk == nil || id == "" {
 		return
 	}
-	ch := deviceChannelName(id)
+	ch := p.deviceChannelName(id)
 	if err := p.sdk.UnregisterOutputChannel(ch); err != nil {
 		p.logf("unregister output channel %s: %v", ch, err)
 		return
@@ -247,9 +310,9 @@ func (d *devicectlDevice) output(args map[string]interface{}) (interface{}, erro
 			ids = append(ids, m.DeviceID)
 		}
 		if len(ids) == 0 {
-			return nil, fmt.Errorf("devicectl 需要 meta.device_id 才能投递；当前没有在线设备（device_list_channels 可看每台设备的 device/<id> 通道）")
+			return nil, fmt.Errorf("devicectl 需要 meta.device_id 才能投递；当前没有在线设备（device_list_channels 可看每台设备的 device-<id> 通道）")
 		}
-		return nil, fmt.Errorf("devicectl 需要 meta.device_id（或直接用通道 device/<id>）；当前在线设备: %s", strings.Join(ids, ", "))
+		return nil, fmt.Errorf("devicectl 需要 meta.device_id（或直接用通道 device-<id>）；当前在线设备: %s", strings.Join(ids, ", "))
 	}
 	return pushToDevice(d.reg, deviceID, args)
 }

internal/plugins/remotedevice/outputch_test.go

@@ -9,6 +9,8 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"regexp"
+	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -130,7 +132,7 @@ func TestDeviceChannelLifecycleAndPush(t *testing.T) {
 	cli.sendText([]byte(`{"op":"hello","device":{"device_id":"spk-1","name":"音箱","kind":"speaker","caps":["speaker"]}}`))
 	cli.readHelloAckAndBind(t, token)
 
-	ch := deviceChannelName("spk-1")
+	ch := p.deviceChannelName("spk-1")
 	deadline := time.Now().Add(3 * time.Second)
 	caps, ok := rec.caps(ch)
 	for !ok && time.Now().Before(deadline) {
@@ -255,3 +257,31 @@ func TestDevicectlAggregateOutputAddressing(t *testing.T) {
 		t.Fatal("不存在的设备应报错")
 	}
 }
+
+// 通道名合规性：设备通道名会被内核拼进 LLM **函数名**（output_send__<通道名>），
+// 而上游函数名规范是 ^[a-zA-Z0-9_-]{1,64}$ —— 违规会让**整条请求**被 400 拒绝
+// （实测把生产打挂：device/<id> 里的 `/` 触发 Invalid 'tools[299].function.name'，
+// 网关 auto tier 全链条失败，整个 agent 不说话了）。
+//
+// 通道名是**插件自己的声明**，所以这条判据钉在插件侧。
+func TestDeviceChannelNameIsLLMFunctionNameSafe(t *testing.T) {
+	re := regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)
+	// 含**恶意/异常** id：空格、符号、非 ASCII、超长、以及会折成同一个名字的两个 id
+	ids := []string{"waiter-fnnas", "1", "a b!c", "中文设备", strings.Repeat("x", 120), "a b", "a-b"}
+	p := &Plugin{}
+	seen := map[string]string{}
+	for _, id := range ids {
+		ch := p.deviceChannelName(id)
+		if prev, dup := seen[ch]; dup {
+			t.Errorf("不同设备 id（%q 与 %q）派生出同一个通道名 %q", prev, id, ch)
+		}
+		seen[ch] = id
+		if !re.MatchString(ch) {
+			t.Errorf("设备通道名 %q 违反上游函数名规范 %s", ch, re)
+		}
+		toolName := "output_send__" + ch
+		if !re.MatchString(toolName) {
+			t.Errorf("派生出的工具名 %q 违反上游函数名规范 %s", toolName, re)
+		}
+	}
+}

internal/plugins/remotedevice/plugin.go

@@ -37,6 +37,11 @@ type Plugin struct {
 	token    string
 	sdk      *sdk.PluginSDK
 	dev      *devicectlDevice
+
+	// devChansMu/devChans 维护"设备自报 id → 派生的通道名"。
+	// 设备 id 是外部输入，不能直接进通道名（见 outputch.go 的 deviceChannelName）。
+	devChansMu sync.Mutex
+	devChans   map[string]string
 }
 
 func New(name string) *Plugin {
@@ -124,7 +129,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 	//
 	// **注意**：agent 的输出**不会**被自动转回设备 —— 主动转发只有 webui 与 cli 两个
 	// 交互界面（它们把最终回复渲染成对话气泡是本职）。设备要走
-	// `output_send__device/<id>`（agent 主动调用），这才与"输出是 agent 的主动调用"一致。
+	// `output_send__device-<id>`（agent 主动调用），这才与"输出是 agent 的主动调用"一致。
 	// 节流：同设备同类型事件 10s 内去重，防传感器风暴。
 	lastEventAt := map[string]time.Time{}
 	var eventMu sync.Mutex
@@ -159,9 +164,10 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
 
 		log.Printf("[remotedevice] event from %s: %s", deviceID, evtType)
 		if p.sdk != nil {
-			// 设备通道 device/<id> 是动态的：设备首次上报时**懒登记** inputch
+			// 设备通道 device-<id> 是动态的（分隔符用 - 而非 /，见 deviceChannelName 的说明：
-			// （Register 幂等），父 agent 才能把它划给驻留子。
+			// 通道名会进 LLM 函数名，必须满足 ^[a-zA-Z0-9_-]{1,64}$）。
-			devCh := "device/" + deviceID
+			// 首次上报时**懒登记** inputch（Register 幂等），父 agent 才能把它划给驻留子。
+			devCh := p.deviceChannelName(deviceID)
 			_ = p.sdk.RegisterInputChannel(devCh, sdk.ChannelDef{})
 			// 异步注入：不阻塞 WS 读循环；回复路由回 device/{id} 输出通道
 			p.sdk.InjectInput(devCh, devCh, "text", map[string]interface{}{"content": text})

internal/plugins/remotedevice/registry.go

@@ -287,7 +287,7 @@ func (r *Registry) register(meta DeviceMeta) {
 	r.devices[meta.DeviceID] = &meta
 	onOnline := r.onOnline
 	r.mu.Unlock()
-	// 先回调（可能注册 device/<id> 输出通道），再发变更通知。
+	// 先回调（可能注册 device-<id> 输出通道），再发变更通知。
 	if onOnline != nil {
 		onOnline(meta)
 	}