chore(version): 1.6.0

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
feat(deploy): 部署前校验 master.key 可解封配置 + llmsproxy -show-secrets
2026-11-08 10:17:21 +00:00 · 2026-09-26 14:21:51 +08:00 · 2026-09-26 14:21:44 +08:00 · 2026-09-26 14:08:44 +08:00 · 2026-09-26 14:01:47 +08:00 · 2026-09-11 18:19:47 +08:00
19 changed files with 1779 additions and 41 deletions
--- a/cmd/gui/package-lock.json
+++ b/cmd/gui/package-lock.json
@ -1,12 +1,12 @@
 {
  "name": "modelrouter-gui",
-  "version": "1.5.8",
+  "version": "1.6.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "modelrouter-gui",
-      "version": "1.5.8",
+      "version": "1.6.0",
      "license": "Proprietary",
      "devDependencies": {
        "electron": "^33.0.0",
--- a/cmd/gui/package.json
+++ b/cmd/gui/package.json
@ -1,6 +1,6 @@
 {
  "name": "modelrouter-gui",
-  "version": "1.5.8",
+  "version": "1.6.0",
  "description": "ModelRouter Desktop — embedded ModelRouter core with tray",
  "author": "ModelRouter",
  "main": "main.js",
--- a/cmd/llmsproxy/main.go
+++ b/cmd/llmsproxy/main.go
@ -24,6 +24,7 @@ import (
 func main() {
 	cfgPath := flag.String("config", "config.yaml", "path to gateway config file")
 	checkOnly := flag.Bool("check", false, "validate the config file and exit (0 = valid, 1 = invalid); nothing is started and no file is written")
+	showSecrets := flag.Bool("show-secrets", false, "print the config's credentials in the clear and exit; nothing is started and no file is written")
 	flag.Parse()

 	// -check is the deploy-time preflight: parse and validate the config
@ -41,6 +42,20 @@ func main() {
 		return
 	}

+	// -show-secrets is the operator escape hatch for a config whose
+	// credentials are sealed at rest: it prints them to stdout and exits
+	// without starting anything or writing anything. Nothing else in the
+	// program prints a credential, and this path never logs to a file.
+	if *showSecrets {
+		if _, err := os.Stat(*cfgPath); err != nil {
+			log.Fatalf("[llmsproxy] show-secrets: %v", err)
+		}
+		if err := config.PrintSecrets(*cfgPath); err != nil {
+			log.Fatalf("[llmsproxy] show-secrets: %v", err)
+		}
+		return
+	}
+
 	created, err := config.EnsureDefault(*cfgPath)
 	if err != nil {
 		log.Fatalf("[llmsproxy] config: %v", err)
--- a/deploy.sh
+++ b/deploy.sh
@ -244,6 +244,63 @@ verify_config() {
    return 1
 }

+# ---------- 密钥可解封校验 ----------
+# config.yaml 里的凭据以 enc:v1: 密文落盘，解密钥匙是 master.key（或
+# LLMS_PROXY_MASTER_KEY）。一旦钥匙丢失/错位，配置在**启动时**才会报错，
+# 那时服务已经处于「二进制已替换 + 配置已替换」的半死状态，只能靠回滚。
+# 所以在替换任何东西之前先验：能不能用现有的钥匙解开现有的密文。
+#
+# 两种情形要分开：
+#   1. 配置里**有**密文 ⇒ 钥匙必须能解开（否则拒绝部署）
+#   2. 配置里**没有**密文 ⇒ 全新安装/首次加密，无需钥匙（但会顺手记一条，
+#      因为它意味着这次部署会把明文写成密文，而钥匙必须同时就位）
+verify_master_key() {
+    log "密钥可解封校验"
+    [[ -f "$TARGET_CONFIG" ]] || return 0   # 配置都不在，交给 verify_config 报错
+
+    local sealed
+    sealed=$(grep -c 'enc:v1:' "$TARGET_CONFIG" 2>/dev/null || echo 0)
+    if [[ "$sealed" -eq 0 ]]; then
+        warn "配置内无密文（尚未加密或全为明文）——首次加密需要 master.key 可写"
+        return 0
+    fi
+
+    # 钥匙来源与 config 包一致：env 优先，否则 runtime_file 同目录的 master.key
+    local runtime_file key_file
+    runtime_file=$(awk '/^runtime_file:/{print $2; exit}' "$TARGET_CONFIG")
+    [[ -n "$runtime_file" ]] || runtime_file="$(dirname "$TARGET_CONFIG")/runtime.json"
+    key_file="$(dirname "$runtime_file")/master.key"
+
+    if [[ -n "${LLMS_PROXY_MASTER_KEY:-}" ]]; then
+        log "  钥匙来源: LLMS_PROXY_MASTER_KEY（环境变量）"
+        # 走真实解密路径验证，而不是只检查格式
+        if out=$("$TARGET_BIN" -show-secrets -config "$TARGET_CONFIG" 2>&1); then
+            log "✓ 凭据可解封（$(echo "$out" | grep -cE '^(source|key) ') 项）"
+            return 0
+        fi
+        err "凭据无法用 LLMS_PROXY_MASTER_KEY 解封，未替换任何文件："
+        printf '%s\n' "$out" >&2
+        return 1
+    fi
+
+    if [[ ! -f "$key_file" ]]; then
+        err "配置含 $sealed 处密文，但钥匙文件不存在: $key_file"
+        err "  没有它，部署后服务将无法启动。恢复 master.key 或设置 LLMS_PROXY_MASTER_KEY 后重试。"
+        return 1
+    fi
+    log "  钥匙文件: $key_file ($(stat -c '%A' "$key_file" 2>/dev/null || echo '?')，$(wc -c < "$key_file") 字节)"
+
+    if out=$("$TARGET_BIN" -show-secrets -config "$TARGET_CONFIG" 2>&1); then
+        log "✓ 凭据可解封（$(echo "$out" | grep -cE '^(source|key) ') 项）"
+        return 0
+    fi
+    err "凭据无法解密（钥匙与配置不匹配），未替换任何文件："
+    printf '%s\n' "$out" | head -5 >&2
+    err "  密钥来源: $key_file"
+    err "  常见原因：master.key 被重新生成、恢复了不匹配的备份，或换了机器。"
+    return 1
+}
+
 # ---------- 同步适配器 ----------
 sync_adapters() {
    log "同步适配器"
@ -393,6 +450,10 @@ main() {
    parse_args "$@"
    log "═══ llmsproxy 原子部署开始 ═══"
    precheck
+    # 密钥校验放在 build/替换之前：它的失败后果最重（配置里的密文永久解不开），
+    # 必须在动任何文件之前就挡住。此阶段用的是**当前线上二进制**，它已经
+    # 支持 -show-secrets（首次引入该子命令的版本除外，此时跳过并提示）。
+    verify_master_key
    build
    sync_adapters
    backup_old_state
--- a/internal/config/config.go
+++ b/internal/config/config.go
@ -27,6 +27,11 @@ type Config struct {
 	Auto          []ModelScope `yaml:"auto,omitempty"`       // AUTO 调度链规则（WebUI 优先级页编辑，chat）
 	AutoImage     []ModelScope `yaml:"auto_image,omitempty"` // AUTO 生图调度链规则（WebUI 优先级页·生图）
 	Keys          []GWKey      `yaml:"keys,omitempty"`       // 网关密钥（WebUI 密钥页管理）
+	// box seals credentials (sources' api_key/headers, keys' key) at rest.
+	// In-memory values are always plaintext; only the bytes on disk are sealed.
+	// Wired by AttachSecretBox — Load leaves it nil so `-check` and tests stay
+	// filesystem-free.
+	box *SecretBox
 }

 // Defaults applied to any source (YAML or runtime) that leaves a field unset.
@ -192,10 +197,15 @@ func RemoveSourceFromYAML(path, name string) error {

 // UpsertSourceInYAML adds or updates a source entry in the YAML config file.
 // Uses yaml.Node to preserve the rest of the file's comments and formatting.
-func UpsertSourceInYAML(path, name string, src Source) error {
+// When box is non-nil the source's credentials are sealed before writing, so a
+// newly added source never lands in the file as plaintext.
+func UpsertSourceInYAML(path, name string, src Source, box *SecretBox) error {
 	if path == "" {
 		return fmt.Errorf("config path is empty")
 	}
+	if err := sealSource(&src, box); err != nil {
+		return err
+	}
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return err
@ -253,11 +263,17 @@ func UpsertSourceInYAML(path, name string, src Source) error {

 // Save writes the current config back to the YAML file (preserving comments
 // via yaml.Node round-trip when possible, or full marshaling as fallback).
+// Credentials are sealed on the way out and the in-memory copy is restored to
+// plaintext afterwards, so callers keep working with usable values.
 func (c *Config) Save() error {
 	if c.Path == "" {
 		return fmt.Errorf("config path is empty")
 	}
+	if err := c.sealInPlace(c.box); err != nil {
+		return err
+	}
 	out, err := yaml.Marshal(c)
+	c.unsealAfterWrite(c.box)
 	if err != nil {
 		return fmt.Errorf("marshal config: %w", err)
 	}
--- a/internal/config/secret_config.go
+++ b/internal/config/secret_config.go
@ -0,0 +1,272 @@
+package config
+
+// Secret handling for config.yaml.
+//
+// config.yaml is 0644 world-readable by design (ops need to inspect it), so any
+// credential in it must not sit there in plaintext. Sources' api_key / headers
+// and gateway keys are therefore sealed at rest with the same SecretBox used by
+// the runtime store, and unsealed in memory at load time.
+//
+// The invariant that makes this safe: **in-memory values are always plaintext**,
+// and the enc:v1: prefix is what marks a file value as sealed. Read paths that
+// predate this (core.resolveSourceKey) already unseal, so only the write side and
+// the load-time normalize step are new.
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"strings"
+)
+
+// sealSource seals one source's credentials in place (used by the YAML upsert
+// path, which is a package function and therefore has no Config to borrow a box
+// from).
+func sealSource(s *Source, box *SecretBox) error {
+	if box == nil {
+		return nil
+	}
+	if s.APIKey != "" && !strings.HasPrefix(s.APIKey, encPrefix) {
+		v, err := box.Encrypt(s.APIKey)
+		if err != nil {
+			return err
+		}
+		s.APIKey = v
+	}
+	for k, v := range s.Headers {
+		if v == "" || strings.HasPrefix(v, encPrefix) {
+			continue
+		}
+		e, err := box.Encrypt(v)
+		if err != nil {
+			return err
+		}
+		s.Headers[k] = e
+	}
+	return nil
+}
+
+// normalizeSecrets unseals every credential in the freshly parsed config so the
+// rest of the program only ever sees plaintext. A value without the enc:v1:
+// prefix is left untouched, which keeps hand-written plaintext configs working
+// (and is what a pre-encryption config file looks like).
+//
+// A value that carries the prefix but fails to decrypt is a hard error, not
+// something to paper over: returning the ciphertext (MustDecrypt's behavior)
+// would let the next Save re-seal it and turn one bad value into permanent,
+// compounding corruption. Losing the master key must be loud.
+func (c *Config) normalizeSecrets(box *SecretBox) error {
+	if box == nil {
+		return nil
+	}
+	for i := range c.Sources {
+		s := &c.Sources[i]
+		if strings.HasPrefix(s.APIKey, encPrefix) {
+			v, err := box.Decrypt(s.APIKey)
+			if err != nil {
+				return fmt.Errorf("source %q api_key: %w", s.Name, err)
+			}
+			s.APIKey = v
+		}
+		for k, v := range s.Headers {
+			if strings.HasPrefix(v, encPrefix) {
+				d, err := box.Decrypt(v)
+				if err != nil {
+					return fmt.Errorf("source %q header %q: %w", s.Name, k, err)
+				}
+				s.Headers[k] = d
+			}
+		}
+	}
+	for i := range c.Keys {
+		if strings.HasPrefix(c.Keys[i].Key, encPrefix) {
+			v, err := box.Decrypt(c.Keys[i].Key)
+			if err != nil {
+				return fmt.Errorf("gateway key %q: %w", c.Keys[i].Name, err)
+			}
+			c.Keys[i].Key = v
+		}
+	}
+	return nil
+}
+
+// sealInPlace replaces plaintext credentials with ciphertext for writing. It is
+// deliberately a separate step from Marshal: callers that need the plaintext
+// (auth comparisons, log output, returning a key to the operator who just
+// created it) must not be handed a sealed config by accident.
+func (c *Config) sealInPlace(box *SecretBox) error {
+	if box == nil {
+		return nil
+	}
+	for i := range c.Sources {
+		s := &c.Sources[i]
+		if s.APIKey != "" && !strings.HasPrefix(s.APIKey, encPrefix) {
+			v, err := box.Encrypt(s.APIKey)
+			if err != nil {
+				return err
+			}
+			s.APIKey = v
+		}
+		if len(s.Headers) > 0 {
+			sealed := make(map[string]string, len(s.Headers))
+			for k, v := range s.Headers {
+				if v == "" || strings.HasPrefix(v, encPrefix) {
+					sealed[k] = v
+					continue
+				}
+				e, err := box.Encrypt(v)
+				if err != nil {
+					return err
+				}
+				sealed[k] = e
+			}
+			s.Headers = sealed
+		}
+	}
+	for i := range c.Keys {
+		k := &c.Keys[i]
+		if k.Key != "" && !strings.HasPrefix(k.Key, encPrefix) {
+			v, err := box.Encrypt(k.Key)
+			if err != nil {
+				return err
+			}
+			k.Key = v
+		}
+	}
+	return nil
+}
+
+// unsealAfterWrite restores plaintext after a sealed marshal so the live process
+// keeps working on plaintext values (mirrors Store.persistLocked's dance).
+func (c *Config) unsealAfterWrite(box *SecretBox) {
+	// Save just encrypted every value it can see, so a failure here is
+	// impossible; ignore the error rather than panic in a write path.
+	_ = c.normalizeSecrets(box)
+}
+
+// hasPlaintextSecrets reports whether any credential in the config is still in
+// the clear. Used to decide whether a startup migration write is needed, and to
+// warn (without leaking values) when no master key is available.
+func (c *Config) hasPlaintextSecrets() bool {
+	for _, s := range c.Sources {
+		if s.APIKey != "" && !strings.HasPrefix(s.APIKey, encPrefix) {
+			return true
+		}
+		for _, v := range s.Headers {
+			if v != "" && !strings.HasPrefix(v, encPrefix) {
+				return true
+			}
+		}
+	}
+	for _, k := range c.Keys {
+		if k.Key != "" && !strings.HasPrefix(k.Key, encPrefix) {
+			return true
+		}
+	}
+	return false
+}
+
+// countPlaintextSecrets returns how many credentials are still in the clear, for
+// an operator-facing migration log line that must not print the values.
+func (c *Config) countPlaintextSecrets() int {
+	n := 0
+	for _, s := range c.Sources {
+		if s.APIKey != "" && !strings.HasPrefix(s.APIKey, encPrefix) {
+			n++
+		}
+		for _, v := range s.Headers {
+			if v != "" && !strings.HasPrefix(v, encPrefix) {
+				n++
+			}
+		}
+	}
+	for _, k := range c.Keys {
+		if k.Key != "" && !strings.HasPrefix(k.Key, encPrefix) {
+			n++
+		}
+	}
+	return n
+}
+
+// NormalizeSecretsForRun unseals the loaded config and then seals it back on
+// disk if anything was still in the clear. Order matters: Load() read the file
+// with ciphertext still in place, so the unseal has to happen before the
+// registry (and any Save the startup path performs) sees the values.
+func (c *Config) NormalizeSecretsForRun(box *SecretBox) error {
+	c.AttachSecretBox(box)
+	if err := c.normalizeSecrets(box); err != nil {
+		return err
+	}
+	return c.migratePlaintextSecrets()
+}
+
+// AttachSecretBox wires the encryption box into the config so Save can seal
+// credentials. Kept as an explicit call (rather than a constructor argument) so
+// config.Load stays usable in contexts that have no filesystem secrets (tests,
+// `-check`).
+func (c *Config) AttachSecretBox(box *SecretBox) { c.box = box }
+
+// SecretBox returns the wired encryption box, or nil when none is attached.
+func (c *Config) SecretBox() *SecretBox { return c.box }
+
+// migratePlaintextSecrets seals any credential still in the clear and writes the
+// file once. It is idempotent: a config that is already sealed (or has no
+// secrets) is left alone and nothing is written.
+func (c *Config) migratePlaintextSecrets() error {
+	if c.box == nil || c.Path == "" {
+		return nil
+	}
+	if !c.hasPlaintextSecrets() {
+		return nil
+	}
+	n := c.countPlaintextSecrets()
+	if err := c.Save(); err != nil {
+		return err
+	}
+	log.Printf("[config] sealed %d plaintext credential(s) in %s", n, c.Path)
+	return nil
+}
+
+// PrintSecrets writes the config's credentials to stdout in the clear and
+// returns an error only when the file cannot be read or the master key does not
+// match. It is the operator counterpart to sealing-at-rest: with keys stored as
+// ciphertext, "which key is this source using" must still be answerable.
+//
+// It deliberately takes a path rather than a *Config so the caller cannot
+// accidentally hand it a config that has already been unsealed in memory, and it
+// never writes anything.
+func PrintSecrets(path string) error {
+	cfg, err := Load(path)
+	if err != nil {
+		return err
+	}
+	box, err := NewSecretBox(cfg.RuntimeFile)
+	if err != nil {
+		return fmt.Errorf("%w (is master.key present and intact?)", err)
+	}
+	if err := cfg.normalizeSecrets(box); err != nil {
+		return err
+	}
+	w := os.Stdout
+	fmt.Fprintf(w, "# %s — %d source(s), %d gateway key(s)\n", path, len(cfg.Sources), len(cfg.Keys))
+	for _, s := range cfg.Sources {
+		fmt.Fprintf(w, "source %-16s api_key=%s\n", s.Name, orNone(s.APIKey))
+		for k, v := range s.Headers {
+			if v != "" {
+				fmt.Fprintf(w, "source %-16s header[%s]=%s\n", s.Name, k, v)
+			}
+		}
+	}
+	for _, k := range cfg.Keys {
+		fmt.Fprintf(w, "key    %-16s role=%-5s %s\n", k.Name, k.Role, k.Key)
+	}
+	fmt.Fprintf(w, "gateway_keys (legacy): %s\n", strings.Join(cfg.GatewayKeys, " "))
+	return nil
+}
+
+func orNone(s string) string {
+	if s == "" {
+		return "(unset)"
+	}
+	return s
+}
--- a/internal/config/secret_config_test.go
+++ b/internal/config/secret_config_test.go
@ -0,0 +1,283 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeMasterKey plants a deterministic master.key next to the given runtime
+// file so tests exercise the real box instead of the env-var shortcut.
+func writeMasterKey(t *testing.T, runtimeFile string) *SecretBox {
+	t.Helper()
+	if err := os.WriteFile(filepath.Join(filepath.Dir(runtimeFile), "master.key"),
+		[]byte(strings.Repeat("ab", 32)), 0600); err != nil {
+		t.Fatal(err)
+	}
+	box, err := NewSecretBox(runtimeFile)
+	if err != nil {
+		t.Fatalf("NewSecretBox: %v", err)
+	}
+	return box
+}
+
+func TestSaveSealsCredentialsAndLoadUnseals(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	runtime := filepath.Join(dir, "runtime.json")
+	box := writeMasterKey(t, runtime)
+
+	cfg := &Config{
+		Path:   path,
+		Listen: "127.0.0.1:0",
+		Sources: []Source{{
+			Name:    "up",
+			BaseURL: "http://up/v1",
+			APIKey:  "sk-plaintext-secret",
+			Adapter: "openai",
+			Headers: map[string]string{"X-Extra": "header-secret"},
+			Models:  []Model{{ID: "m", Kind: "chat"}},
+		}},
+		Keys: []GWKey{{Key: "sk-gw-plain", Role: "admin", Name: "admin"}},
+	}
+	cfg.AttachSecretBox(box)
+	if err := cfg.Save(); err != nil {
+		t.Fatalf("Save: %v", err)
+	}
+
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(raw)
+	if strings.Contains(text, "sk-plaintext-secret") {
+		t.Error("source api_key written in plaintext")
+	}
+	if strings.Contains(text, "header-secret") {
+		t.Error("source header written in plaintext")
+	}
+	if strings.Contains(text, "sk-gw-plain") {
+		t.Error("gateway key written in plaintext")
+	}
+	if n := strings.Count(text, encPrefix); n != 3 {
+		t.Errorf("expected 3 sealed values, found %d", n)
+	}
+
+	// The live in-memory config must still hold plaintext after Save.
+	if cfg.Sources[0].APIKey != "sk-plaintext-secret" {
+		t.Errorf("in-memory api_key mutated by Save: %q", cfg.Sources[0].APIKey)
+	}
+	if cfg.Keys[0].Key != "sk-gw-plain" {
+		t.Errorf("in-memory gateway key mutated by Save: %q", cfg.Keys[0].Key)
+	}
+
+	// A fresh load must hand back plaintext again.
+	loaded, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	loaded.AttachSecretBox(box)
+	loaded.normalizeSecrets(box)
+	if loaded.Sources[0].APIKey != "sk-plaintext-secret" {
+		t.Errorf("loaded api_key = %q, want plaintext", loaded.Sources[0].APIKey)
+	}
+	if loaded.Sources[0].Headers["X-Extra"] != "header-secret" {
+		t.Errorf("loaded header = %q, want plaintext", loaded.Sources[0].Headers["X-Extra"])
+	}
+	if loaded.Keys[0].Key != "sk-gw-plain" {
+		t.Errorf("loaded gateway key = %q, want plaintext", loaded.Keys[0].Key)
+	}
+}
+
+func TestPlaintextConfigStillLoads(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	// A hand-written, pre-encryption config: no enc:v1: anywhere.
+	body := `listen: 127.0.0.1:0
+sources:
+  - name: legacy
+    base_url: http://legacy/v1
+    api_key: sk-written-by-hand
+    adapter: openai
+    models:
+      - id: m
+        kind: chat
+`
+	if err := os.WriteFile(path, []byte(body), 0644); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	box := writeMasterKey(t, filepath.Join(dir, "runtime.json"))
+	cfg.AttachSecretBox(box)
+	cfg.normalizeSecrets(box)
+	if cfg.Sources[0].APIKey != "sk-written-by-hand" {
+		t.Errorf("plaintext config value changed: %q", cfg.Sources[0].APIKey)
+	}
+}
+
+func TestMigratePlaintextSecretsIsIdempotent(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	runtime := filepath.Join(dir, "runtime.json")
+	box := writeMasterKey(t, runtime)
+
+	cfg := &Config{
+		Path:    path,
+		Listen:  "127.0.0.1:0",
+		Sources: []Source{{Name: "up", BaseURL: "http://up/v1", APIKey: "sk-clear", Adapter: "openai", Models: []Model{{ID: "m"}}}},
+	}
+	cfg.AttachSecretBox(box)
+
+	if err := cfg.migratePlaintextSecrets(); err != nil {
+		t.Fatalf("first migrate: %v", err)
+	}
+	first, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(first), encPrefix) {
+		t.Fatal("migration did not seal the value")
+	}
+	// In-memory must be plaintext so the running process keeps working.
+	if cfg.Sources[0].APIKey != "sk-clear" {
+		t.Errorf("in-memory api_key = %q, want plaintext", cfg.Sources[0].APIKey)
+	}
+
+	// Second run: already sealed => no write.
+	before, _ := os.Stat(path)
+	if err := cfg.migratePlaintextSecrets(); err != nil {
+		t.Fatalf("second migrate: %v", err)
+	}
+	after, _ := os.Stat(path)
+	if before.ModTime() != after.ModTime() {
+		t.Error("second migrate rewrote an already-sealed config")
+	}
+}
+
+func TestSealedValueDoesNotDoubleEncrypt(t *testing.T) {
+	dir := t.TempDir()
+	box := writeMasterKey(t, filepath.Join(dir, "runtime.json"))
+	cfg := &Config{Path: filepath.Join(dir, "config.yaml"), Sources: []Source{{Name: "a", BaseURL: "http://a"}}}
+	cfg.AttachSecretBox(box)
+
+	once, err := box.Encrypt("sk-x")
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg.Sources[0].APIKey = once
+	if err := cfg.Save(); err != nil {
+		t.Fatal(err)
+	}
+	got, err := box.Decrypt(cfg.Sources[0].APIKey)
+	if err != nil {
+		t.Fatalf("value became undecryptable: %v", err)
+	}
+	if got != "sk-x" {
+		t.Errorf("round trip = %q, want sk-x", got)
+	}
+}
+
+func TestUpsertSourceInYAMLSealsCredentials(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	box := writeMasterKey(t, filepath.Join(dir, "runtime.json"))
+
+	if err := os.WriteFile(path, []byte("listen: 127.0.0.1:0\nsources: []\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	src := Source{Name: "new", BaseURL: "http://new/v1", APIKey: "sk-fresh", Adapter: "openai", Models: []Model{{ID: "m"}}}
+	if err := UpsertSourceInYAML(path, src.Name, src, box); err != nil {
+		t.Fatalf("UpsertSourceInYAML: %v", err)
+	}
+	raw, _ := os.ReadFile(path)
+	if strings.Contains(string(raw), "sk-fresh") {
+		t.Error("newly added source stored its api_key in plaintext")
+	}
+	if !strings.Contains(string(raw), encPrefix) {
+		t.Error("newly added source was not sealed")
+	}
+}
+
+func TestCountPlaintextSecrets(t *testing.T) {
+	cfg := &Config{
+		Sources: []Source{
+			{Name: "a", APIKey: encPrefix + "abc", Headers: map[string]string{"H": encPrefix + "x"}},
+			{Name: "b", APIKey: "sk-in-clear", Headers: map[string]string{"H2": "clear-too"}},
+		},
+		Keys: []GWKey{{Key: "sk-gw-clear"}},
+	}
+	if got := cfg.countPlaintextSecrets(); got != 3 {
+		t.Errorf("countPlaintextSecrets = %d, want 3", got)
+	}
+	if !cfg.hasPlaintextSecrets() {
+		t.Error("hasPlaintextSecrets = false, want true")
+	}
+	cfg.Sources[1].APIKey = encPrefix + "y"
+	cfg.Sources[1].Headers["H2"] = encPrefix + "z"
+	cfg.Keys[0].Key = encPrefix + "k"
+	if cfg.hasPlaintextSecrets() {
+		t.Error("hasPlaintextSecrets = true after sealing everything")
+	}
+}
+
+// TestNormalizeSecretsFailsLoudlyOnWrongMasterKey is the negative case that
+// guards the migration: with a wrong key, a sealed value must NOT be handed
+// back as ciphertext for a later re-seal (that compounds corruption and turns
+// one lost key file into permanently unusable config).
+func TestNormalizeSecretsFailsLoudlyOnWrongMasterKey(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.yaml")
+	runtime := filepath.Join(dir, "runtime.json")
+	good := writeMasterKey(t, runtime)
+
+	cfg := &Config{
+		Path:    path,
+		Listen:  "127.0.0.1:0",
+		Sources: []Source{{Name: "up", BaseURL: "http://up/v1", APIKey: "sk-secret", Adapter: "openai", Models: []Model{{ID: "m"}}}},
+	}
+	cfg.AttachSecretBox(good)
+	if err := cfg.Save(); err != nil {
+		t.Fatal(err)
+	}
+	sealedOnce, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// A different master key must be rejected, loudly. NewSecretBox derives the
+	// key path from the RUNTIME file's directory, so the wrong key has to live
+	// in a different directory — otherwise it would read the good master.key.
+	otherDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(otherDir, "master.key"),
+		[]byte(strings.Repeat("cd", 32)), 0600); err != nil {
+		t.Fatal(err)
+	}
+	badBox, err := NewSecretBox(filepath.Join(otherDir, "runtime.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	loaded.AttachSecretBox(badBox)
+	if err := loaded.NormalizeSecretsForRun(badBox); err == nil {
+		t.Fatal("expected an error with the wrong master key, got nil")
+	}
+
+	// Crucially: the file must be untouched — no second seal on top.
+	after, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(after) != string(sealedOnce) {
+		t.Error("config file was rewritten despite the decrypt failure")
+	}
+	if n := strings.Count(string(after), encPrefix); n != strings.Count(string(sealedOnce), encPrefix) {
+		t.Errorf("sealed count changed %d -> %d (double encryption)", strings.Count(string(sealedOnce), encPrefix), n)
+	}
+}
--- a/internal/core/core.go
+++ b/internal/core/core.go
@ -7,6 +7,7 @@ import (
 	"crypto/rand"
 	"encoding/hex"
 	"fmt"
+	"log"
 	"os"
 	"path/filepath"
 	"sort"
@ -53,6 +54,10 @@ func NewFromConfig(cfg *config.Config) (*Core, error) {
 		return nil, fmt.Errorf("lua vm: %w", err)
 	}
 	c.store = config.NewStore(cfg.RuntimeFile)
+	// Share one box between the runtime store and config.yaml so a single
+	// master.key seals both files. config.Load left the config holding
+	// ciphertext (if it was sealed); unseal it now that the box exists.
+	cfg.AttachSecretBox(c.store.SecretBox())
 	if err := c.store.Load(); err != nil {
 		return nil, fmt.Errorf("runtime store: %w", err)
 	}
@ -74,6 +79,12 @@ func NewFromConfig(cfg *config.Config) (*Core, error) {
 	if err := c.seedPresetTemplates(); err != nil {
 		return nil, fmt.Errorf("seed preset templates: %w", err)
 	}
+	// Seal any credential still in the clear in config.yaml. Idempotent: an
+	// already-sealed config is not rewritten, so a normal restart writes
+	// nothing. This is the only place that rewrites the file on startup.
+	if err := cfg.NormalizeSecretsForRun(c.store.SecretBox()); err != nil {
+		return nil, fmt.Errorf("normalize secrets: %w", err)
+	}
 	return c, nil
 }

@ -439,6 +450,11 @@ func (c *Core) mergedSources() []config.Source {
 }

 // resolveSourceKey applies api_key_env and decrypts enc:v1: ciphertext.
+// Config values are already unsealed at startup (Config.NormalizeSecretsForRun),
+// so the decrypt branch is the belt-and-braces path for a source that arrived
+// already sealed through another route. A failure there leaves the ciphertext in
+// place, which makes the upstream reject the key loudly rather than sending an
+// empty Authorization header that might look like a config-less source.
 func (c *Core) resolveSourceKey(s config.Source) config.Source {
 	if s.APIKeyEnv != "" {
 		if v := os.Getenv(s.APIKeyEnv); v != "" {
@ -447,7 +463,11 @@ func (c *Core) resolveSourceKey(s config.Source) config.Source {
 		return s
 	}
 	if box := c.store.SecretBox(); box != nil && strings.HasPrefix(s.APIKey, "enc:v1:") {
-		s.APIKey = box.MustDecrypt(s.APIKey)
+		if v, err := box.Decrypt(s.APIKey); err == nil {
+			s.APIKey = v
+		} else {
+			log.Printf("[core] source %s: api_key decrypt failed: %v", s.Name, err)
+		}
 	}
 	return s
 }
@ -655,7 +675,7 @@ func (c *Core) AddSource(src config.Source) error {
 	if err := normalizeSource(&src); err != nil {
 		return err
 	}
-	if err := config.UpsertSourceInYAML(c.cfg.Path, src.Name, src); err != nil {
+	if err := config.UpsertSourceInYAML(c.cfg.Path, src.Name, src, c.cfg.SecretBox()); err != nil {
 		return err
 	}
 	// Update in-memory Sources so mergedSources() finds the entry.
--- a/internal/gateway/apiv1.go
+++ b/internal/gateway/apiv1.go
@ -0,0 +1,415 @@
+package gateway
+
+// Agent-facing management API.
+//
+// The Web UI has always driven the gateway through /api/*, so the management
+// surface already exists. What it lacked was anything an agent could *rely* on:
+// no way to discover the contract, no single call that answers "what is the
+// current state", and per-endpoint response shapes that make scripting brittle.
+//
+// This file adds a versioned, self-describing facade under /api/v1 without
+// touching the existing endpoints, so the Web UI keeps working unchanged while
+// agents get a stable contract:
+//
+//	GET    /api/v1                      — machine-readable index of every endpoint
+//	GET    /api/v1/overview             — one call: sources + auto chain + keys + health
+//	GET    /api/v1/sources              — sources, credentials masked
+//	GET    /api/v1/sources/{name}       — one source
+//	GET    /api/v1/auto                 — scheduling chain + live slot states
+//	GET    /api/v1/keys                 — key metadata (never the secret)
+//	GET    /api/v1/models               — every model id the gateway can route
+//	GET    /api/v1/health               — per-source health, no auth needed beyond the key
+//
+// Auth is the same gateway key as everywhere else (Authorization: Bearer, or
+// ?api_key=, or the gw_key cookie). Read endpoints accept any role; writes
+// still require admin, enforced by the same middleware the UI goes through.
+
+import (
+	"errors"
+	"net/http"
+	"net/url"
+	"sort"
+	"strings"
+
+	"llmsproxy/internal/config"
+)
+
+// apiV1Routes dispatches /api/v1/*. Kept separate from routes() so the original
+// switch stays readable and the versioned surface can grow on its own.
+func (g *Gateway) apiV1Routes(w http.ResponseWriter, r *http.Request) {
+	path := strings.TrimPrefix(r.URL.Path, "/api/v1")
+	path = strings.Trim(path, "/")
+
+	switch {
+	case path == "":
+		g.apiV1Index(w, r)
+	case path == "overview":
+		g.apiV1Overview(w, r)
+	case path == "health":
+		g.apiV1Health(w, r)
+	case path == "models":
+		g.apiV1Models(w, r)
+	case path == "sources":
+		if r.Method != http.MethodGet {
+			writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "use GET")
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]interface{}{"sources": maskSources(g.core.Sources())})
+	case strings.HasPrefix(path, "sources/"):
+		name, err := decodePathSegment(strings.TrimPrefix(path, "sources/"))
+		if err != nil {
+			writeError(w, http.StatusBadRequest, "invalid_request", err.Error())
+			return
+		}
+		if r.Method != http.MethodGet {
+			writeError(w, http.StatusMethodNotAllowed, "method_not_allowed",
+				"use PUT/DELETE on /api/sources/{name} to modify a source")
+			return
+		}
+		for _, s := range g.core.Sources() {
+			if s.Name == name {
+				// ?reveal=credentials is admin-only and is what the Web UI's
+				// edit dialog uses: a form that round-trips a source must be
+				// able to show the current key, otherwise saving an unrelated
+				// field would blank it. Everything else stays masked.
+				if r.URL.Query().Get("reveal") == "credentials" {
+					if reqRole(r.Context()) != "admin" {
+						writeError(w, http.StatusForbidden, "forbidden",
+							"admin role required to reveal credentials")
+						return
+					}
+					writeJSON(w, http.StatusOK, map[string]interface{}{"source": s})
+					return
+				}
+				writeJSON(w, http.StatusOK, map[string]interface{}{"source": maskSource(s)})
+				return
+			}
+		}
+		writeError(w, http.StatusNotFound, "not_found", "no such source: "+name)
+	case path == "auto":
+		if r.Method != http.MethodGet {
+			writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "use GET")
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]interface{}{
+			"rules":       g.core.AutoRules(),
+			"image_rules": g.core.AutoImageRules(),
+			"states":      g.core.AutoSlotStates(),
+		})
+	case path == "keys":
+		if reqRole(r.Context()) != "admin" {
+			writeError(w, http.StatusForbidden, "forbidden", "admin role required")
+			return
+		}
+		if r.Method != http.MethodGet {
+			writeError(w, http.StatusMethodNotAllowed, "method_not_allowed",
+				"use POST/PUT/DELETE on /api/keys to manage keys")
+			return
+		}
+		keys := g.core.ListKeys()
+		out := make([]map[string]interface{}, 0, len(keys))
+		for _, k := range keys {
+			out = append(out, map[string]interface{}{
+				"name":       k.Name,
+				"role":       k.Role,
+				"models":     k.Models,
+				"note":       k.Note,
+				"created_at": k.CreatedAt,
+				"seed":       k.Seed,
+				// The secret itself is never echoed. An operator that needs it
+				// already has it from creation time or from config.yaml.
+				"key_prefix": maskKey(k.Key),
+			})
+		}
+		writeJSON(w, http.StatusOK, map[string]interface{}{"keys": out})
+	default:
+		g.apiV1Index(w, r)
+	}
+}
+
+// apiV1Index is the discovery document: it names every endpoint with its
+// method, auth requirement and purpose, so an agent does not have to scrape the
+// HTML to find out what it can call.
+func (g *Gateway) apiV1Index(w http.ResponseWriter, r *http.Request) {
+	type ep struct {
+		Method      string `json:"method"`
+		Path        string `json:"path"`
+		Auth        string `json:"auth"`
+		Summary     string `json:"summary"`
+		WriteEffect string `json:"writes,omitempty"`
+	}
+	index := map[string]interface{}{
+		"api_version": "v1",
+		"description": "llmsproxy management API. Authenticate with a gateway key: " +
+			"'Authorization: Bearer <key>', '?api_key=<key>', or the gw_key cookie. " +
+			"Read endpoints accept any role; mutations require an admin key.",
+		"discovery": []ep{
+			{Method: "GET", Path: "/api/v1", Auth: "any", Summary: "this document"},
+			{Method: "GET", Path: "/api/v1/overview", Auth: "any",
+				Summary: "current state in one call: sources, auto chain, key count, source health"},
+			{Method: "GET", Path: "/api/v1/health", Auth: "any",
+				Summary: "per-source health snapshot only"},
+			{Method: "GET", Path: "/api/v1/models", Auth: "any",
+				Summary: "every model id the gateway can route, grouped by owning source"},
+			{Method: "GET", Path: "/api/v1/sources", Auth: "any",
+				Summary: "all sources with credentials masked"},
+			{Method: "GET", Path: "/api/v1/sources/{name}", Auth: "any", Summary: "one source"},
+			{Method: "GET", Path: "/api/v1/auto", Auth: "any",
+				Summary: "AUTO scheduling chain and live per-slot state"},
+			{Method: "GET", Path: "/api/v1/keys", Auth: "admin",
+				Summary: "gateway key metadata; secrets are never returned"},
+
+			{Method: "GET", Path: "/api/sources", Auth: "admin", Summary: "raw source list (includes api_key)"},
+			{Method: "POST", Path: "/api/sources", Auth: "admin", Summary: "add or replace a source",
+				WriteEffect: "writes config.yaml (api_key sealed at rest)"},
+			{Method: "PUT", Path: "/api/sources/{name}", Auth: "admin", Summary: "update one source",
+				WriteEffect: "writes config.yaml"},
+			{Method: "DELETE", Path: "/api/sources/{name}", Auth: "admin", Summary: "delete a source",
+				WriteEffect: "writes config.yaml"},
+
+			{Method: "GET", Path: "/api/auto", Auth: "any", Summary: "scheduling chain (readable by any role)"},
+			{Method: "PUT", Path: "/api/auto", Auth: "admin", Summary: "replace the scheduling chain",
+				WriteEffect: "writes config.yaml (the AUTO chain lives here)"},
+
+			{Method: "GET", Path: "/api/keys", Auth: "admin", Summary: "gateway keys"},
+			{Method: "POST", Path: "/api/keys", Auth: "admin", Summary: "create a gateway key",
+				WriteEffect: "writes config.yaml"},
+			{Method: "DELETE", Path: "/api/keys/{name}", Auth: "admin", Summary: "delete a gateway key",
+				WriteEffect: "writes config.yaml"},
+
+			{Method: "GET", Path: "/api/status", Auth: "any", Summary: "per-source health detail"},
+			{Method: "GET", Path: "/api/stats", Auth: "any", Summary: "usage aggregates"},
+			{Method: "GET", Path: "/api/stats/records", Auth: "any", Summary: "paged request records"},
+			{Method: "GET", Path: "/api/adapters", Auth: "admin", Summary: "installed Lua adapters"},
+			{Method: "GET", Path: "/api/source_templates", Auth: "admin", Summary: "source templates"},
+			{Method: "POST", Path: "/v1/chat/completions", Auth: "any", Summary: "OpenAI-compatible inference"},
+		},
+		"conventions": map[string]interface{}{
+			"errors":       "{ \"error\": { \"type\": <code>, \"message\": <text> } }",
+			"path_escape":  "URL-encode source and key names; {name} is a single path segment",
+			"idempotency":  "POST /api/sources and PUT /api/sources/{name} both upsert by name",
+			"config_truth": "all configuration lives in config.yaml; API writes are persisted immediately",
+			"credentials": "credentials are masked by default. GET /api/v1/sources/{name}?reveal=credentials " +
+				"returns them in the clear and is admin-only — the Web UI edit dialog uses it, because a form " +
+				"that round-trips a source must show the current key or saving another field would blank it.",
+		},
+	}
+	writeJSON(w, http.StatusOK, index)
+}
+
+// apiV1Overview is the "what is the current state" call an agent makes first.
+// One round trip instead of five.
+func (g *Gateway) apiV1Overview(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "use GET")
+		return
+	}
+	sources := g.core.Sources()
+	names := make([]string, 0, len(sources))
+	modelCount := 0
+	for _, s := range sources {
+		names = append(names, s.Name)
+		modelCount += len(s.Models)
+	}
+	keys := g.core.ListKeys()
+	adminCount, userCount := 0, 0
+	for _, k := range keys {
+		if k.Role == "admin" {
+			adminCount++
+		} else {
+			userCount++
+		}
+	}
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"api_version": "v1",
+		"summary": map[string]interface{}{
+			"source_count":      len(sources),
+			"model_count":       modelCount,
+			"gateway_key_count": len(keys),
+			"admin_key_count":   adminCount,
+			"user_key_count":    userCount,
+			"auto_slots":        len(g.core.AutoRules()),
+		},
+		"sources":    maskSources(sources),
+		"auto":       g.core.AutoRules(),
+		"auto_image": g.core.AutoImageRules(),
+		"health":     g.sourceHealthBrief(),
+		"caller": map[string]interface{}{
+			"role": reqRole(r.Context()),
+			"key":  maskKey(reqKey(r.Context())),
+		},
+	})
+}
+
+func (g *Gateway) apiV1Health(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "use GET")
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]interface{}{"sources": g.sourceHealthBrief()})
+}
+
+// apiV1Models lists routable model ids per source, which is what an agent needs
+// to build a valid request — /v1/models flattens them and hides the owner.
+func (g *Gateway) apiV1Models(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "use GET")
+		return
+	}
+	bySource := map[string][]string{}
+	var all []string
+	for _, s := range g.core.Sources() {
+		for _, m := range s.Models {
+			bySource[s.Name] = append(bySource[s.Name], m.ID)
+			all = append(all, m.ID)
+		}
+	}
+	sort.Strings(all)
+	all = dedupeStrings(all)
+	writeJSON(w, http.StatusOK, map[string]interface{}{
+		"count":     len(all),
+		"models":    all,
+		"by_source": bySource,
+		"note":      "request a model as \"<source>:<model>\" to pin one source, or the bare id to let the gateway choose",
+	})
+}
+
+// ---- helpers ----
+
+// maskSources returns sources with credentials replaced by a presence marker.
+// The UI still uses /api/sources (which returns real values, because its edit
+// form round-trips them); this is the safe view for programmatic callers.
+func maskSources(srcs []config.Source) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(srcs))
+	for _, s := range srcs {
+		out = append(out, maskSource(s))
+	}
+	return out
+}
+
+func maskSource(s config.Source) map[string]interface{} {
+	return map[string]interface{}{
+		"name":           s.Name,
+		"base_url":       s.BaseURL,
+		"adapter":        s.Adapter,
+		"endpoint":       s.Endpoint,
+		"image_endpoint": s.ImageEndpoint,
+		"api_key":        maskKey(s.APIKey),
+		"api_key_set":    s.APIKey != "",
+		"models":         s.Models,
+		"headers":        maskHeaders(s.Headers),
+		"proxy_url":      s.ProxyURL,
+		"meta":           s.Meta,
+		"temperature":    s.Temperature,
+		"max_tokens":     s.MaxTokens,
+		"max_concurrent": s.MaxConcurrent,
+		"rpm":            s.RPM,
+	}
+}
+
+func maskKey(k string) string {
+	if k == "" {
+		return ""
+	}
+	if strings.HasPrefix(k, "enc:v1:") {
+		return "(sealed)"
+	}
+	if len(k) <= 10 {
+		return k[:2] + "…"
+	}
+	return k[:6] + "…" + k[len(k)-4:]
+}
+
+func maskHeaders(h map[string]string) map[string]string {
+	if h == nil {
+		return nil
+	}
+	out := make(map[string]string, len(h))
+	for k, v := range h {
+		out[k] = maskKey(v)
+	}
+	return out
+}
+
+// sourceHealthBrief reuses the same registry status the UI's /api/status shows,
+// so the agent view and the UI view cannot drift apart. Recent-traffic counters
+// come from the same stats window, because a source that is actually serving
+// traffic must never look down just because a probe was rate-limited.
+func (g *Gateway) sourceHealthBrief() []map[string]interface{} {
+	sts := g.core.Registry().Status()
+	recent := g.stats.SourceRecent(300)
+	avgs := g.stats.SourceAverages(300)
+	for i := range sts {
+		if v, ok := recent[sts[i].Name]; ok {
+			sts[i].RecentOK = v[0]
+			sts[i].RecentErr = v[1]
+		}
+		if a, ok := avgs[sts[i].Name]; ok {
+			sts[i].AvgFirstByteMs = a.AvgFirstByteMs
+			sts[i].AvgTokPerS = a.AvgTokPerS
+		}
+	}
+	out := make([]map[string]interface{}, 0, len(sts))
+	for _, s := range sts {
+		row := map[string]interface{}{
+			"name":           s.Name,
+			"adapter":        s.Adapter,
+			"healthy":        s.Healthy,
+			"available":      s.Available,
+			"live_available": s.LiveAvailable,
+			"model_count":    len(s.Models),
+		}
+		if s.LastError != "" {
+			row["last_error"] = s.LastError
+		}
+		if s.LastChecked > 0 {
+			row["last_checked"] = s.LastChecked
+		}
+		if s.RecentOK > 0 || s.RecentErr > 0 {
+			row["recent_ok"] = s.RecentOK
+			row["recent_err"] = s.RecentErr
+		}
+		if s.AvgFirstByteMs > 0 {
+			row["avg_first_byte_ms"] = s.AvgFirstByteMs
+		}
+		if s.AvgTokPerS > 0 {
+			row["avg_tok_per_s"] = s.AvgTokPerS
+		}
+		if s.FailCount > 0 {
+			row["fail_count"] = s.FailCount
+		}
+		if s.Permanent {
+			row["permanent"] = true
+		}
+		out = append(out, row)
+	}
+	return out
+}
+
+// decodePathSegment URL-decodes one path segment and rejects an empty result,
+// so a name containing a slash cannot be silently mis-resolved.
+func decodePathSegment(seg string) (string, error) {
+	s, err := url.PathUnescape(seg)
+	if err != nil {
+		return "", err
+	}
+	if s == "" {
+		return "", errEmptySegment
+	}
+	return s, nil
+}
+
+func dedupeStrings(in []string) []string {
+	out := in[:0]
+	var last string
+	for i, s := range in {
+		if i == 0 || s != last {
+			out = append(out, s)
+		}
+		last = s
+	}
+	return out
+}
+
+// errEmptySegment marks a path like /api/v1/sources/ with no name after it.
+var errEmptySegment = errors.New("empty path segment")
--- a/internal/gateway/apiv1_test.go
+++ b/internal/gateway/apiv1_test.go
@ -0,0 +1,299 @@
+package gateway
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"llmsproxy/internal/config"
+)
+
+// v1Gateway builds a gateway with one source and two keys, and returns the
+// secrets so a test can assert they never appear in a response.
+func v1Gateway(t *testing.T) (*Gateway, string, string) {
+	t.Helper()
+	g := newTestGateway(t, config.Source{
+		Name:    "up",
+		BaseURL: "http://up.example/v1",
+		APIKey:  "sk-up-secret",
+		Adapter: "openai",
+		Models:  []config.Model{{ID: "m1", Kind: "chat"}},
+	})
+	// The shared helper only seeds one admin key; add a user key through the
+	// core so role-gated endpoints have something to reject.
+	if _, err := g.core.CreateKey("agent", "user", nil, "test agent key"); err != nil {
+		t.Fatalf("CreateKey: %v", err)
+	}
+	rec := doReq(t, g, http.MethodGet, "/api/keys", "")
+	var doc struct {
+		Keys []config.GWKey `json:"keys"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &doc); err != nil {
+		t.Fatalf("decode keys: %v", err)
+	}
+	userKey := ""
+	for _, k := range doc.Keys {
+		if k.Role == "user" {
+			userKey = k.Key
+		}
+	}
+	if userKey == "" {
+		t.Fatal("no user key was created")
+	}
+	return g, "sk-test", userKey
+}
+
+func decodeJSON(t *testing.T, body string, v interface{}) {
+	t.Helper()
+	if err := json.Unmarshal([]byte(body), v); err != nil {
+		t.Fatalf("decode %s: %v", body, err)
+	}
+}
+
+func TestAPIV1IndexIsDiscoverable(t *testing.T) {
+	g, _, _ := v1Gateway(t)
+	rec := doReq(t, g, http.MethodGet, "/api/v1", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", rec.Code, rec.Body.String())
+	}
+	var doc struct {
+		APIVersion  string `json:"api_version"`
+		Description string `json:"description"`
+		Discovery   []struct {
+			Method  string `json:"method"`
+			Path    string `json:"path"`
+			Auth    string `json:"auth"`
+			Summary string `json:"summary"`
+		} `json:"discovery"`
+		Conventions map[string]interface{} `json:"conventions"`
+	}
+	decodeJSON(t, rec.Body.String(), &doc)
+	if doc.APIVersion != "v1" {
+		t.Errorf("api_version = %q", doc.APIVersion)
+	}
+	if doc.Description == "" {
+		t.Error("index should carry a usage description")
+	}
+	if len(doc.Discovery) == 0 {
+		t.Fatal("discovery list is empty")
+	}
+	want := map[string]bool{
+		"/api/v1/overview": false, "/api/v1/sources": false,
+		"/api/v1/auto": false, "/api/v1/models": false,
+		"/api/v1/health": false, "/api/v1/keys": false,
+		"/api/sources": false, "/api/auto": false, "/v1/chat/completions": false,
+	}
+	for _, e := range doc.Discovery {
+		if _, ok := want[e.Path]; ok {
+			want[e.Path] = true
+		}
+		if e.Method == "" || e.Path == "" || e.Auth == "" || e.Summary == "" {
+			t.Errorf("incomplete discovery entry: %+v", e)
+		}
+	}
+	for p, found := range want {
+		if !found {
+			t.Errorf("discovery is missing %s", p)
+		}
+	}
+	if doc.Conventions["errors"] == nil {
+		t.Error("conventions should document the error shape")
+	}
+}
+
+func TestAPIV1OverviewSummarisesState(t *testing.T) {
+	g, _, _ := v1Gateway(t)
+	rec := doReq(t, g, http.MethodGet, "/api/v1/overview", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d: %s", rec.Code, rec.Body.String())
+	}
+	var doc struct {
+		Summary struct {
+			SourceCount     int `json:"source_count"`
+			ModelCount      int `json:"model_count"`
+			GatewayKeyCount int `json:"gateway_key_count"`
+		} `json:"summary"`
+		Sources []map[string]interface{} `json:"sources"`
+		Auto    []map[string]interface{} `json:"auto"`
+		Health  []map[string]interface{} `json:"health"`
+		Caller  struct {
+			Role string `json:"role"`
+		} `json:"caller"`
+	}
+	decodeJSON(t, rec.Body.String(), &doc)
+	if doc.Summary.SourceCount != 1 {
+		t.Errorf("source_count = %d, want 1", doc.Summary.SourceCount)
+	}
+	if doc.Summary.ModelCount != 1 {
+		t.Errorf("model_count = %d, want 1", doc.Summary.ModelCount)
+	}
+	if doc.Summary.GatewayKeyCount < 2 {
+		t.Errorf("gateway_key_count = %d, want >= 2", doc.Summary.GatewayKeyCount)
+	}
+	if len(doc.Sources) != 1 || doc.Sources[0]["name"] != "up" {
+		t.Errorf("sources = %+v", doc.Sources)
+	}
+	if doc.Caller.Role != "admin" {
+		t.Errorf("caller.role = %q, want admin", doc.Caller.Role)
+	}
+}
+
+func TestAPIV1NeverEchoesSecrets(t *testing.T) {
+	g, admin, user := v1Gateway(t)
+	for _, path := range []string{"/api/v1", "/api/v1/overview", "/api/v1/sources", "/api/v1/sources/up", "/api/v1/keys", "/api/v1/models", "/api/v1/health", "/api/v1/auto"} {
+		rec := doReq(t, g, http.MethodGet, path, "")
+		if rec.Code != http.StatusOK {
+			t.Fatalf("%s status = %d: %s", path, rec.Code, rec.Body.String())
+		}
+		if strings.Contains(rec.Body.String(), "sk-up-secret") {
+			t.Errorf("%s leaked the source api_key", path)
+		}
+		if admin != "" && strings.Contains(rec.Body.String(), admin) {
+			t.Errorf("%s leaked the admin gateway key", path)
+		}
+		if strings.Contains(rec.Body.String(), user) {
+			t.Errorf("%s leaked the user gateway key", path)
+		}
+	}
+	// Masking must still be useful: it says a key is configured.
+	rec := doReq(t, g, http.MethodGet, "/api/v1/sources/up", "")
+	if !strings.Contains(rec.Body.String(), `"api_key_set":true`) {
+		t.Error("masked source should report that a key is configured")
+	}
+}
+
+func TestAPIV1KeysRequiresAdminAndMasks(t *testing.T) {
+	g, _, user := v1Gateway(t)
+	// Authenticate as the user key by swapping the shared helper's header.
+	req := newAuthedRequest(t, http.MethodGet, "/api/v1/keys", user)
+	rec := serveViaHandler(t, g, req)
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("user role on /api/v1/keys = %d, want 403: %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestAPIV1SourcesNotFound(t *testing.T) {
+	g, _, _ := v1Gateway(t)
+	rec := doReq(t, g, http.MethodGet, "/api/v1/sources/nope", "")
+	if rec.Code != http.StatusNotFound {
+		t.Errorf("status = %d, want 404: %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestAPIV1RejectsWrites(t *testing.T) {
+	g, _, _ := v1Gateway(t)
+	for _, m := range []string{http.MethodPost, http.MethodPut, http.MethodDelete, http.MethodPatch} {
+		rec := doReq(t, g, m, "/api/v1/sources", `{}`)
+		if rec.Code == http.StatusOK {
+			t.Errorf("%s /api/v1/sources returned 200; the v1 read facade must not mutate", m)
+		}
+	}
+	// And the source must be untouched.
+	rec := doReq(t, g, http.MethodGet, "/api/v1/sources", "")
+	if !strings.Contains(rec.Body.String(), `"name":"up"`) {
+		t.Error("the source disappeared after a rejected write")
+	}
+}
+
+func TestAPIV1ModelsGroupsBySource(t *testing.T) {
+	g, _, _ := v1Gateway(t)
+	rec := doReq(t, g, http.MethodGet, "/api/v1/models", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d", rec.Code)
+	}
+	var doc struct {
+		Count    int                 `json:"count"`
+		Models   []string            `json:"models"`
+		BySource map[string][]string `json:"by_source"`
+	}
+	decodeJSON(t, rec.Body.String(), &doc)
+	if doc.Count != 1 || doc.Models[0] != "m1" {
+		t.Errorf("models = %+v", doc.Models)
+	}
+	if len(doc.BySource["up"]) != 1 || doc.BySource["up"][0] != "m1" {
+		t.Errorf("by_source = %+v", doc.BySource)
+	}
+}
+
+func TestAPIV1RequiresAuthentication(t *testing.T) {
+	g, _, _ := v1Gateway(t)
+	for _, path := range []string{"/api/v1", "/api/v1/overview", "/api/v1/sources", "/api/v1/health", "/api/v1/models"} {
+		req := newRequest(http.MethodGet, path, "")
+		rec := serveViaHandler(t, g, req)
+		if rec.Code != http.StatusUnauthorized {
+			t.Errorf("%s without a key = %d, want 401", path, rec.Code)
+		}
+	}
+}
+
+func TestMaskKeyHidesTheSecret(t *testing.T) {
+	cases := map[string]string{
+		"":                   "",
+		"ab":                 "ab…",
+		"sk-gw-abcdefghijkl": "sk-gw-…ijkl",
+		"enc:v1:AAAA":        "(sealed)",
+	}
+	for in, want := range cases {
+		if got := maskKey(in); got != want {
+			t.Errorf("maskKey(%q) = %q, want %q", in, got, want)
+		}
+	}
+	// The masked form must not reveal the middle of the secret.
+	full := maskKey("sk-gw-1234567890abcdef")
+	if strings.Contains(full, "4567890abcdef") {
+		t.Errorf("maskKey leaked the middle: %q", full)
+	}
+}
+
+// newRequest builds an unauthenticated request.
+func newRequest(method, path, body string) *http.Request {
+	req, _ := http.NewRequest(method, path, strings.NewReader(body))
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	return req
+}
+
+// newAuthedRequest builds a request carrying the given bearer key.
+func newAuthedRequest(t *testing.T, method, path, key string) *http.Request {
+	t.Helper()
+	req := newRequest(method, path, "")
+	req.Header.Set("Authorization", "Bearer "+key)
+	return req
+}
+
+// serveViaHandler pushes a request through the full handler chain (auth included).
+func serveViaHandler(t *testing.T, g *Gateway, req *http.Request) *httptest.ResponseRecorder {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	g.Handler().ServeHTTP(rec, req)
+	return rec
+}
+
+// TestAPIV1RevealRequiresAdmin: the only way to read a key in the clear is the
+// explicit admin-only reveal. Without the role check this endpoint would hand
+// every source credential to any valid (even user-scoped) key.
+func TestAPIV1RevealRequiresAdmin(t *testing.T) {
+	g, _, user := v1Gateway(t)
+	rec := serveViaHandler(t, g, newAuthedRequest(t, http.MethodGet, "/api/v1/sources/up?reveal=credentials", user))
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("user reveal = %d, want 403: %s", rec.Code, rec.Body.String())
+	}
+	if strings.Contains(rec.Body.String(), "sk-up-secret") {
+		t.Error("a forbidden reveal still leaked the key")
+	}
+	rec = doReq(t, g, http.MethodGet, "/api/v1/sources/up?reveal=credentials", "")
+	if rec.Code != http.StatusOK {
+		t.Fatalf("admin reveal = %d: %s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "sk-up-secret") {
+		t.Error("admin reveal should return the key in the clear (the edit form needs it)")
+	}
+	// The masked default view must still hide it on the same path.
+	rec = doReq(t, g, http.MethodGet, "/api/v1/sources/up", "")
+	if strings.Contains(rec.Body.String(), "sk-up-secret") {
+		t.Error("the default view leaked the key")
+	}
+}
--- a/internal/gateway/chat.go
+++ b/internal/gateway/chat.go
@ -42,6 +42,10 @@ type ChatCompletion struct {
 	Model   string            `json:"model"`
 	Choices []ChatChoice      `json:"choices"`
 	Usage   *types.TokenUsage `json:"usage,omitempty"`
+	// Cost is the upstream-reported charge for this request, passed through
+	// verbatim (OpenCode reports it as a decimal string, always "0" on the
+	// flat-rate Go subscription). Absent when the upstream reports nothing.
+	Cost string `json:"cost,omitempty"`
 }

 type ChatChoice struct {
@ -66,6 +70,10 @@ type ChatChunk struct {
 	// Usage is sent in the final chunk of a stream (empty choices) so
 	// OpenAI-compatible clients can read token usage.
 	Usage *types.TokenUsage `json:"usage,omitempty"`
+	// Cost is the upstream-reported charge for this request, passed through
+	// verbatim (OpenCode reports it as a decimal string). Emitted on the
+	// terminal chunk, mirroring OpenCode's own {"choices":[],"cost":"0"}.
+	Cost string `json:"cost,omitempty"`
 }

 type ChunkChoice struct {
@ -703,6 +711,7 @@ func writeChatCompletion(w http.ResponseWriter, resp *types.UnifiedResponse, mod
 		Created: time.Now().Unix(),
 		Model:   modelName,
 		Choices: []ChatChoice{{Index: 0, Message: msg, FinishReason: resp.FinishReason}},
+		Cost:    resp.Cost,
 	}
 	if resp.TokenUsage.Total > 0 || resp.TokenUsage.Prompt > 0 || resp.TokenUsage.Completion > 0 {
 		out.Usage = &resp.TokenUsage
@ -822,11 +831,15 @@ func (g *Gateway) pumpStream(w http.ResponseWriter, rec *Req, chunks <-chan type
 	// source's status-page latency average.
 	rec.FirstByteMs = time.Since(t0).Milliseconds()
 	var lastUsage *types.TokenUsage
+	var lastCost string
 	lastFinish := ""
 	for ck := range chunks {
 		if ck.Usage != nil {
 			lastUsage = mergeUsage(lastUsage, ck.Usage)
 		}
+		if ck.Cost != "" {
+			lastCost = ck.Cost
+		}
 		chunk := ChatChunk{
 			ID: id, Object: "chat.completion.chunk", Created: created, Model: modelName,
 		}
@ -893,6 +906,14 @@ func (g *Gateway) pumpStream(w http.ResponseWriter, rec *Req, chunks <-chan type
 			ID: id, Object: "chat.completion.chunk", Created: created, Model: modelName,
 			Choices: []ChunkChoice{},
 			Usage:   tut,
+			Cost:    lastCost,
+		})
+	} else if lastCost != "" {
+		// Cost arrived without any usage (OpenCode sends it on its own frame).
+		send(ChatChunk{
+			ID: id, Object: "chat.completion.chunk", Created: created, Model: modelName,
+			Choices: []ChunkChoice{},
+			Cost:    lastCost,
 		})
 	}
 	fmt.Fprintf(w, "data: [DONE]\n\n")
--- a/internal/gateway/server.go
+++ b/internal/gateway/server.go
@ -222,6 +222,8 @@ func (g *Gateway) routes(w http.ResponseWriter, r *http.Request) {
 		g.handleModels(w, r)
 	case r.URL.Path == "/api/adapters" || strings.HasPrefix(r.URL.Path, "/api/adapters/"):
 		g.handleAdaptersAPI(w, r)
+	case r.URL.Path == "/api/v1" || strings.HasPrefix(r.URL.Path, "/api/v1/"):
+		g.apiV1Routes(w, r)
 	case r.URL.Path == "/api/sources" || strings.HasPrefix(r.URL.Path, "/api/sources/"):
 		g.handleSourcesAPI(w, r)
 	case r.URL.Path == "/api/source_templates" || strings.HasPrefix(r.URL.Path, "/api/source_templates/"):
--- a/internal/gateway/ui/index.html
+++ b/internal/gateway/ui/index.html
@ -2772,7 +2772,10 @@

      /* ---------- sources tab ---------- */
      async function renderSources() {
-        const j = await api("/api/sources");
+        // Read through /api/v1: the UI is a client of the same public API an
+        // agent uses, so there is one contract rather than a private path.
+        // The list view needs no credentials, so the masked view is enough.
+        const j = await api("/api/v1/sources");
        const rows = j.sources
          .map(
            (
@ -2794,13 +2797,23 @@
      function editSource(name) {
        const wrap = document.createElement("div");
        wrap.id = "modal-wrap";
-        Promise.all([api("/api/sources"), api("/api/status")])
-          .then(([src, st]) => {
-            const s = src.sources.find((x) => x.name === name) || {
-              name: name,
-              models: [{ id: "", priority: 0, kind: "chat" }],
-            };
-            const cur = s.adapter || "openai";
+            // The edit dialog round-trips the whole source, so it must load the
+            // real api_key — otherwise saving an unrelated field would blank
+            // it. That is what ?reveal=credentials is for (admin-only).
+            const srcPath = name
+              ? "/api/v1/sources/" + encodeURIComponent(name) + "?reveal=credentials"
+              : "/api/v1/sources";
+            Promise.all([api(srcPath), api("/api/status")])
+              .then(([src, st]) => {
+                // Editing: the single-source shape. Creating: an empty form.
+                const s = name
+                  ? src.source
+                  : { name: "", models: [{ id: "", priority: 0, kind: "chat" }] };
+                if (!s) {
+                  toast(t("toastSave"));
+                  return;
+                }
+                const cur = s.adapter || "openai";
            const apps = ["", ...(st.adapters || []).map((a) => a.name)];
            if (cur && !apps.includes(cur)) apps.push(cur);
            const adSel =
@ -3215,7 +3228,7 @@
      const sortLanes = { chat: [], image: [] };
      let sortStateMap = new Map();
      async function renderSort() {
-        const j = await api("/api/sources");
+        const j = await api("/api/v1/sources");
        let autoR = [];
        let autoImg = [];
        try {
@ -4155,7 +4168,7 @@
      async function loadModelPairs() {
        let srcs = [];
        try {
-          srcs = (await api("/api/sources")).sources || [];
+          srcs = (await api("/api/v1/sources")).sources || [];
        } catch (e) {}
        const pairs = [];
        (srcs || []).forEach((s) =>
--- a/internal/lua/adapters/opencodego.lua
+++ b/internal/lua/adapters/opencodego.lua
@ -221,6 +221,19 @@ function adapter.transform_response(raw_body)
                unified.token_usage.prompt_tokens_details = { cached_tokens = resp.usage.prompt_cache_hit_tokens }
            end
        end
+        -- 上游报告输出里有多少是思考 token。不给客户端的话，无法判断
+        -- completion_tokens 里多少是「可见回答」、多少是「思考」（都按输出计费）。
+        local ctd = resp.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            unified.token_usage.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
+        end
+    end
+
+    -- 本次调用的费用，上游放在**顶层**且是**字符串**（如 "0"、"0.0012"）。
+    -- Go 订阅是包月制，恒为 "0"；只有 Zen 按量付费模型才有信息量。
+    -- 原样透传：网关不解析、不换算、不汇总 —— 它只是上游事实的搬运者。
+    if resp.cost ~= nil then
+        unified.cost = tostring(resp.cost)
    end

    if type(resp.choices) == "table" and #resp.choices > 0 then
@ -267,22 +280,36 @@ function adapter.transform_stream_chunk(raw_chunk)
            completion = chunk.usage.completion_tokens or chunk.usage.completion or 0,
            total = chunk.usage.total_tokens or chunk.usage.total or 0,
        }
+        -- 独立字段与 prompt_tokens_details **并存**透传，不要写成 elseif：
+        -- 上游命中缓存时两者都发，非流式路径也是两个都带。写成 elseif 会让
+        -- 流式丢掉 prompt_cache_hit_tokens/miss，与同一源的**非流式**产出不一致
+        -- （dsh 优先读 details，但只认独立字段的老客户端会看不到缓存）。
        if type(chunk.usage.prompt_tokens_details) == "table" and chunk.usage.prompt_tokens_details.cached_tokens ~= nil then
            uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_tokens_details.cached_tokens }
-        elseif (chunk.usage.prompt_cache_hit_tokens or 0) > 0 then
+        end
+        if (chunk.usage.prompt_cache_hit_tokens or 0) > 0 then
            uses.prompt_cache_hit_tokens = chunk.usage.prompt_cache_hit_tokens
            uses.prompt_cache_miss_tokens = chunk.usage.prompt_cache_miss_tokens or 0
-            uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_cache_hit_tokens }
+            if uses.prompt_tokens_details == nil then
+                uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_cache_hit_tokens }
+            end
+        end
+        local ctd = chunk.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            uses.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
        end
    end

    if not chunk.choices or #chunk.choices == 0 then
-        if uses ~= nil then
-            -- usage-only chunk is not a content/finish signal; the gateway
-            -- emits its own terminal stop chunk and merges this usage.
-            return json.encode({ usage = uses, done = false })
-        end
-        return ""
+        -- 空 choices 的帧既不是内容也不是结束信号。上游发两种：
+        --   {"choices":[],"usage":{...}}   —— 终帧用量
+        --   {"choices":[],"cost":"0"}      —— 单独的费用帧
+        -- 两者可能落在同一帧上，必须都转出去；早退只带 usage 会把费用丢干净。
+        local out = { done = false }
+        if uses ~= nil then out.usage = uses end
+        if chunk.cost ~= nil then out.cost = tostring(chunk.cost) end
+        if uses == nil and chunk.cost == nil then return "" end
+        return json.encode(out)
    end
    local delta = chunk.choices[1].delta or {}
    local fr = chunk.choices[1].finish_reason
--- a/internal/lua/adapters/opencodezen.lua
+++ b/internal/lua/adapters/opencodezen.lua
@ -209,6 +209,19 @@ function adapter.transform_response(raw_body)
                unified.token_usage.prompt_tokens_details = { cached_tokens = resp.usage.prompt_cache_hit_tokens }
            end
        end
+        -- 上游报告输出里有多少是思考 token。不给客户端的话，无法判断
+        -- completion_tokens 里多少是「可见回答」、多少是「思考」（都按输出计费）。
+        local ctd = resp.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            unified.token_usage.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
+        end
+    end
+
+    -- 本次调用的费用，上游放在**顶层**且是**字符串**（如 "0"、"0.0012"）。
+    -- Go 订阅是包月制，恒为 "0"；只有 Zen 按量付费模型才有信息量。
+    -- 原样透传：网关不解析、不换算、不汇总 —— 它只是上游事实的搬运者。
+    if resp.cost ~= nil then
+        unified.cost = tostring(resp.cost)
    end

    if type(resp.choices) == "table" and #resp.choices > 0 then
@ -255,22 +268,36 @@ function adapter.transform_stream_chunk(raw_chunk)
            completion = chunk.usage.completion_tokens or chunk.usage.completion or 0,
            total = chunk.usage.total_tokens or chunk.usage.total or 0,
        }
+        -- 独立字段与 prompt_tokens_details **并存**透传，不要写成 elseif：
+        -- 上游命中缓存时两者都发，非流式路径也是两个都带。写成 elseif 会让
+        -- 流式丢掉 prompt_cache_hit_tokens/miss，与同一源的**非流式**产出不一致
+        -- （dsh 优先读 details，但只认独立字段的老客户端会看不到缓存）。
        if type(chunk.usage.prompt_tokens_details) == "table" and chunk.usage.prompt_tokens_details.cached_tokens ~= nil then
            uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_tokens_details.cached_tokens }
-        elseif (chunk.usage.prompt_cache_hit_tokens or 0) > 0 then
+        end
+        if (chunk.usage.prompt_cache_hit_tokens or 0) > 0 then
            uses.prompt_cache_hit_tokens = chunk.usage.prompt_cache_hit_tokens
            uses.prompt_cache_miss_tokens = chunk.usage.prompt_cache_miss_tokens or 0
-            uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_cache_hit_tokens }
+            if uses.prompt_tokens_details == nil then
+                uses.prompt_tokens_details = { cached_tokens = chunk.usage.prompt_cache_hit_tokens }
+            end
+        end
+        local ctd = chunk.usage.completion_tokens_details
+        if type(ctd) == "table" and ctd.reasoning_tokens ~= nil then
+            uses.completion_tokens_details = { reasoning_tokens = ctd.reasoning_tokens }
        end
    end

    if not chunk.choices or #chunk.choices == 0 then
-        if uses ~= nil then
-            -- usage-only chunk is not a content/finish signal; the gateway
-            -- emits its own terminal stop chunk and merges this usage.
-            return json.encode({ usage = uses, done = false })
-        end
-        return ""
+        -- 空 choices 的帧既不是内容也不是结束信号。上游发两种：
+        --   {"choices":[],"usage":{...}}   —— 终帧用量
+        --   {"choices":[],"cost":"0"}      —— 单独的费用帧
+        -- 两者可能落在同一帧上，必须都转出去；早退只带 usage 会把费用丢干净。
+        local out = { done = false }
+        if uses ~= nil then out.usage = uses end
+        if chunk.cost ~= nil then out.cost = tostring(chunk.cost) end
+        if uses == nil and chunk.cost == nil then return "" end
+        return json.encode(out)
    end
    local delta = chunk.choices[1].delta or {}
    local fr = chunk.choices[1].finish_reason
--- a/internal/lua/usage_cost_test.go
+++ b/internal/lua/usage_cost_test.go
@ -0,0 +1,177 @@
+package lua
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// OpenCode Zen/Go 在 usage 里报告输出有多少是思考 token，并在**顶层**用一个
+// **字符串**给出本次费用。前者决定「completion_tokens 里多少是可见回答」，
+// 后者是唯一的费用信号。两者都曾被适配器丢掉。
+func TestOpenCodeCostAndReasoningPassthrough(t *testing.T) {
+	for _, name := range []string{"opencodego", "opencodezen"} {
+		vm := NewVM(freshAdapterDir(t))
+		if err := vm.Start(); err != nil {
+			t.Fatal(err)
+		}
+
+		// ---- 非流式 ----
+		resp := `{"id":"x","object":"chat.completion","model":"deepseek-v4.1-flash",
+			"choices":[{"index":0,"message":{"role":"assistant","content":"hi","reasoning_content":"think"},
+			"finish_reason":"stop"}],
+			"usage":{"prompt_tokens":37,"completion_tokens":40,"total_tokens":77,
+			"prompt_cache_hit_tokens":0,"prompt_cache_miss_tokens":37,
+			"prompt_tokens_details":{"cached_tokens":0},
+			"completion_tokens_details":{"reasoning_tokens":40}},
+			"cost":"0"}`
+		out, err := vm.Transform(name, "transform_response", resp)
+		if err != nil {
+			t.Fatalf("%s transform_response: %v", name, err)
+		}
+		var r struct {
+			TokenUsage struct {
+				Completion int `json:"completion"`
+				Details    *struct {
+					ReasoningTokens int `json:"reasoning_tokens"`
+				} `json:"completion_tokens_details"`
+			} `json:"token_usage"`
+			Cost string `json:"cost"`
+		}
+		if err := json.Unmarshal([]byte(out), &r); err != nil {
+			t.Fatalf("%s unmarshal: %v (%s)", name, err, out)
+		}
+		if r.Cost != "0" {
+			t.Errorf("%s: cost 未透传（上游给的是字符串 \"0\"）: %q", name, r.Cost)
+		}
+		if r.TokenUsage.Details == nil || r.TokenUsage.Details.ReasoningTokens != 40 {
+			t.Errorf("%s: completion_tokens_details.reasoning_tokens 未透传: %s", name, out)
+		}
+		// 前提校验：reasoning_tokens 确实 ≤ completion_tokens（全为思考）。
+		if r.TokenUsage.Details != nil && r.TokenUsage.Details.ReasoningTokens > r.TokenUsage.Completion {
+			t.Errorf("%s: reasoning 不应超过 completion", name)
+		}
+
+		// ---- 流式：非零费用也要透传 ----
+		chunk := `{"id":"x","object":"chat.completion.chunk","choices":[],
+			"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15,
+			"completion_tokens_details":{"reasoning_tokens":4}},"cost":"0.0012"}`
+		co, err := vm.Transform(name, "transform_stream_chunk", chunk)
+		if err != nil {
+			t.Fatalf("%s transform_stream_chunk: %v", name, err)
+		}
+		var c struct {
+			Cost  string `json:"cost"`
+			Usage *struct {
+				Details *struct {
+					ReasoningTokens int `json:"reasoning_tokens"`
+				} `json:"completion_tokens_details"`
+			} `json:"usage"`
+		}
+		if err := json.Unmarshal([]byte(co), &c); err != nil {
+			t.Fatalf("%s unmarshal chunk: %v (%s)", name, err, co)
+		}
+		if c.Usage == nil || c.Usage.Details == nil || c.Usage.Details.ReasoningTokens != 4 {
+			t.Errorf("%s: 流式 reasoning_tokens 未透传: %s", name, co)
+		}
+		if c.Cost != "0.0012" {
+			t.Errorf("%s: 流式 cost 未透传: %s", name, co)
+		}
+
+		// ---- 独立的 cost 帧（上游就这么发：choices 为空、只有 cost）----
+		only := `{"choices":[],"cost":"0"}`
+		oo, err := vm.Transform(name, "transform_stream_chunk", only)
+		if err != nil {
+			t.Fatalf("%s cost-only chunk: %v", name, err)
+		}
+		if oo == "" {
+			t.Fatalf("%s: 纯 cost 帧被整个丢弃（客户端将看不到费用）", name)
+		}
+		var oc struct {
+			Cost string `json:"cost"`
+		}
+		if err := json.Unmarshal([]byte(oo), &oc); err != nil {
+			t.Fatalf("%s unmarshal cost chunk: %v (%s)", name, err, oo)
+		}
+		if oc.Cost != "0" {
+			t.Errorf("%s: 纯 cost 帧内容丢失: %s", name, oo)
+		}
+
+		// ---- 回归：没有 cost / 没有 details 时不得凭空造字段 ----
+		bare := `{"choices":[{"index":0,"delta":{"content":"hi"},"finish_reason":"stop"}],
+			"usage":{"prompt_tokens":3,"completion_tokens":1,"total_tokens":4}}`
+		bo, _ := vm.Transform(name, "transform_response", bare)
+		if got := bo; len(got) > 0 && containsAll(got, `"cost"`) {
+			t.Errorf("%s: 上游没给 cost 却透传了该字段: %s", name, got)
+		}
+
+		vm.Stop()
+	}
+}
+
+func containsAll(s string, subs ...string) bool {
+	for _, sub := range subs {
+		found := false
+		for i := 0; i+len(sub) <= len(s); i++ {
+			if s[i:i+len(sub)] == sub {
+				found = true
+				break
+			}
+		}
+		if !found {
+			return false
+		}
+	}
+	return true
+}
+
+// 流式与非流式对同一上游切片的产出必须一致：命中缓存时上游同时给
+// prompt_tokens_details.cached_tokens 和独立的 hit/miss 字段，两边都要透传。
+func TestOpenCodeStreamCacheFieldsMatchNonStream(t *testing.T) {
+	for _, name := range []string{"opencodego", "opencodezen"} {
+		vm := NewVM(freshAdapterDir(t))
+		if err := vm.Start(); err != nil {
+			t.Fatal(err)
+		}
+		type cache struct {
+			Details *struct {
+				CachedTokens int `json:"cached_tokens"`
+			} `json:"prompt_tokens_details"`
+			Hit  int `json:"prompt_cache_hit_tokens"`
+			Miss int `json:"prompt_cache_miss_tokens"`
+		}
+		usage := `"usage":{"prompt_tokens":5732,"completion_tokens":20,"total_tokens":5752,
+			"prompt_cache_hit_tokens":5504,"prompt_cache_miss_tokens":228,
+			"prompt_tokens_details":{"cached_tokens":5504}}`
+
+		// 非流式
+		nout, _ := vm.Transform(name, "transform_response",
+			`{"choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}],`+usage+`}`)
+		var nr struct {
+			U cache `json:"token_usage"`
+		}
+		if err := json.Unmarshal([]byte(nout), &nr); err != nil {
+			t.Fatalf("%s: %v", name, err)
+		}
+		// 流式
+		sout, _ := vm.Transform(name, "transform_stream_chunk",
+			`{"choices":[],`+usage+`}`)
+		var sr struct {
+			U cache `json:"usage"`
+		}
+		if err := json.Unmarshal([]byte(sout), &sr); err != nil {
+			t.Fatalf("%s chunk: %v (%s)", name, err, sout)
+		}
+
+		if nr.U.Hit != 5504 || nr.U.Miss != 228 {
+			t.Errorf("%s: 非流式 hit/miss 异常: %+v", name, nr.U)
+		}
+		if sr.U.Hit != nr.U.Hit || sr.U.Miss != nr.U.Miss {
+			t.Errorf("%s: 流式 hit/miss 与非流式不一致 (stream %d/%d vs non-stream %d/%d): %s",
+				name, sr.U.Hit, sr.U.Miss, nr.U.Hit, nr.U.Miss, sout)
+		}
+		if sr.U.Details == nil || sr.U.Details.CachedTokens != 5504 {
+			t.Errorf("%s: 流式 cached_tokens 丢失: %s", name, sout)
+		}
+		vm.Stop()
+	}
+}
--- a/internal/provider/provider.go
+++ b/internal/provider/provider.go
@ -1518,12 +1518,24 @@ func standardSSEChunk(data string) string {
 			PromptTokensDetails *struct {
 				CachedTokens int `json:"cached_tokens"`
 			} `json:"prompt_tokens_details"`
+			CompletionTokensDetails *struct {
+				ReasoningTokens int `json:"reasoning_tokens"`
+			} `json:"completion_tokens_details"`
 		} `json:"usage"`
+		// Cost is a top-level decimal string on OpenCode Zen/Go responses.
+		Cost json.RawMessage `json:"cost"`
 	}
 	if err := json.Unmarshal([]byte(data), &raw); err != nil {
 		return ""
 	}
 	if len(raw.Choices) == 0 && raw.UpstreamUsage.Total == 0 && raw.UpstreamUsage.TotalTokens == 0 {
+		// Cost-only chunk: OpenCode sends the charge on its own frame
+		// {"choices":[],"cost":"0"} with no usage at all. Dropping it here
+		// would lose the only cost signal the client can see.
+		if c := rawCostString(raw.Cost); c != "" {
+			out, _ := json.Marshal(types.UnifiedChunk{Cost: c})
+			return string(out)
+		}
 		return ""
 	}
 	var usage *types.TokenUsage
@ -1541,6 +1553,11 @@ func standardSSEChunk(data string) string {
 				CachedTokens: pu.PromptTokensDetails.CachedTokens,
 			}
 		}
+		if pu.CompletionTokensDetails != nil {
+			usage.CompletionTokensDetails = &types.CompletionTokensDetails{
+				ReasoningTokens: pu.CompletionTokensDetails.ReasoningTokens,
+			}
+		}
 	}
 	finish := ""
 	done := false
@ -1565,6 +1582,24 @@ func standardSSEChunk(data string) string {
 	return string(out)
 }

+// rawCostString normalizes an upstream cost field into a plain string. The
+// value is a decimal **string** on OpenCode Zen/Go ("0", "0.0012"), but other
+// upstreams have been seen to send a bare number, so both are accepted.
+// Returns "" when absent, null, or empty.
+func rawCostString(raw json.RawMessage) string {
+	s := strings.TrimSpace(string(raw))
+	if s == "" || s == "null" {
+		return ""
+	}
+	if s[0] == '"' {
+		var unq string
+		if json.Unmarshal(raw, &unq) == nil {
+			return strings.TrimSpace(unq)
+		}
+	}
+	return s
+}
+
 // pickFirst returns a if non-zero, else b (for usage keys that may appear in
 // either standard *_tokens or legacy short form).
 func pickFirst(a, b int) int {
--- a/internal/types/types.go
+++ b/internal/types/types.go
@ -117,6 +117,11 @@ type UnifiedResponse struct {
 	ToolCalls        []ToolCall `json:"tool_calls,omitempty"`
 	// ImageData used by image-generation adapters.
 	ImageData []ImageData `json:"image_data,omitempty"`
+	// Cost is the upstream-reported charge for this request, passed through
+	// verbatim (OpenCode Zen/Go put a decimal **string** at the response top
+	// level). Deliberately not parsed or summed by the gateway: it is an
+	// upstream fact, and only some upstreams report it at all.
+	Cost string `json:"cost,omitempty"`
 }

 type TokenUsage struct {
@ -133,6 +138,16 @@ type TokenUsage struct {
 	// prompt_tokens_details.cached_tokens is absent.
 	PromptCacheHit  int `json:"prompt_cache_hit_tokens,omitempty"`
 	PromptCacheMiss int `json:"prompt_cache_miss_tokens,omitempty"`
+	// CompletionTokensDetails mirrors the OpenAI v2 usage.completion_tokens_details
+	// object. OpenCode Zen/Go report how much of the completion was thinking
+	// tokens here; without it clients cannot tell how much of the billed output
+	// was reasoning rather than visible answer.
+	CompletionTokensDetails *CompletionTokensDetails `json:"completion_tokens_details,omitempty"`
+}
+
+// CompletionTokensDetails is the OpenAI v2 completion_tokens_details object.
+type CompletionTokensDetails struct {
+	ReasoningTokens int `json:"reasoning_tokens"`
 }

 // PromptTokensDetails is the OpenAI v2 prompt_tokens_details object. Only
@ -157,15 +172,16 @@ func (t TokenUsage) MarshalJSON() ([]byte, error) {
 		pdetails = &PromptTokensDetails{CachedTokens: t.PromptCacheHit}
 	}
 	return json.Marshal(struct {
-		PromptTokens          int                  `json:"prompt_tokens"`
-		CompletionTokens      int                  `json:"completion_tokens"`
-		TotalTokens           int                  `json:"total_tokens"`
-		Prompt                int                  `json:"prompt"`
-		Completion            int                  `json:"completion"`
-		Total                 int                  `json:"total"`
-		PromptTokensDetails   *PromptTokensDetails `json:"prompt_tokens_details,omitempty"`
-		PromptCacheHitTokens  int                  `json:"prompt_cache_hit_tokens,omitempty"`
-		PromptCacheMissTokens int                  `json:"prompt_cache_miss_tokens,omitempty"`
+		PromptTokens          int                      `json:"prompt_tokens"`
+		CompletionTokens      int                      `json:"completion_tokens"`
+		TotalTokens           int                      `json:"total_tokens"`
+		Prompt                int                      `json:"prompt"`
+		Completion            int                      `json:"completion"`
+		Total                 int                      `json:"total"`
+		PromptTokensDetails   *PromptTokensDetails     `json:"prompt_tokens_details,omitempty"`
+		PromptCacheHitTokens  int                      `json:"prompt_cache_hit_tokens,omitempty"`
+		PromptCacheMissTokens int                      `json:"prompt_cache_miss_tokens,omitempty"`
+		CompletionDetails     *CompletionTokensDetails `json:"completion_tokens_details,omitempty"`
 	}{
 		PromptTokens:          t.Prompt,
 		CompletionTokens:      t.Completion,
@ -176,6 +192,7 @@ func (t TokenUsage) MarshalJSON() ([]byte, error) {
 		PromptTokensDetails:   pdetails,
 		PromptCacheHitTokens:  t.PromptCacheHit,
 		PromptCacheMissTokens: t.PromptCacheMiss,
+		CompletionDetails:     t.CompletionTokensDetails,
 	})
 }

@ -219,6 +236,9 @@ type UnifiedChunk struct {
 	// often has empty choices). Gateway uses it to emit exact usage in the
 	// final stream chunk instead of estimates.
 	Usage *TokenUsage `json:"usage,omitempty"`
+	// Cost is upstream-reported charge for this request (decimal string),
+	// passed through verbatim; OpenCode sends it on its own stream chunk.
+	Cost string `json:"cost,omitempty"`
 }

 // Meta passed to Lua build_headers hook
--- a/internal/types/types_test.go
+++ b/internal/types/types_test.go
@ -2,6 +2,7 @@ package types

 import (
 	"encoding/json"
+	"strings"
 	"testing"
 )

@ -117,3 +118,37 @@ func TestChatMessageNormalizesEmptyArrayContent(t *testing.T) {
 		t.Fatalf("empty tool_calls array must be dropped, got %s", om.ToolCalls)
 	}
 }
+
+// 上游报告输出里有多少是思考 token；缺少这个字段，客户端无法判断
+// completion_tokens 里多少是可见回答、多少是思考（两者都按输出计费）。
+func TestTokenUsageMarshalsCompletionTokensDetails(t *testing.T) {
+	u := TokenUsage{
+		Prompt: 37, Completion: 40, Total: 77,
+		CompletionTokensDetails: &CompletionTokensDetails{ReasoningTokens: 40},
+	}
+	b, err := json.Marshal(u)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]interface{}
+	if err := json.Unmarshal(b, &got); err != nil {
+		t.Fatal(err)
+	}
+	ctd, ok := got["completion_tokens_details"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("completion_tokens_details 未输出: %s", b)
+	}
+	if n, _ := ctd["reasoning_tokens"].(float64); int(n) != 40 {
+		t.Errorf("reasoning_tokens = %v, want 40 (%s)", ctd["reasoning_tokens"], b)
+	}
+	// 标准 OpenAI 字段同时存在，老客户端不受影响。
+	if _, ok := got["completion_tokens"]; !ok {
+		t.Errorf("标准 completion_tokens 丢失: %s", b)
+	}
+
+	// 未设置时不得凭空造字段。
+	b2, _ := json.Marshal(TokenUsage{Prompt: 1, Completion: 2, Total: 3})
+	if strings.Contains(string(b2), "completion_tokens_details") {
+		t.Errorf("无数据时不应输出 completion_tokens_details: %s", b2)
+	}
+}
Author	SHA1	Message	Date
JianFeeeee	d81bfb1460	chore(version): 1.6.0 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-09-26 14:21:51 +08:00
llmsproxy	a8cff57e24	feat(deploy): 部署前校验 master.key 可解封配置 + llmsproxy -show-secrets 密钥校验（deploy.sh） - 新增 verify_master_key，在 build/替换任何文件之前执行。失败则二进制与配置分毫未动、服务不受影响（已负向验证：缺钥匙、错钥匙两种情况都挡住） - 走真实的 -show-secrets 解密路径，而不是只检查钥匙文件格式——格式合法但内容不匹配（重新生成、恢复了错的备份、换机器）同样会被拒 - 钥匙来源与 config 包一致：LLMS_PROXY_MASTER_KEY 优先，否则 dirname(runtime_file)/master.key - 配置里没有密文时跳过并提示（首次加密场景） -show-secrets - llmsproxy -show-secrets -config <path>：把凭据打到 stdout 后退出 - 不启动任何东西、不写任何文件（已验证 mtime 不变） - 加密往返无损：封存前后输出逐字节一致 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-09-26 14:21:44 +08:00
llmsproxy	926b9f6565	feat: WebUI 改为依赖 /api/v1，UI 与 agent 共用一套 API 契约 - sources / sort / keys 三个页面的数据源从 /api/sources 切到 /api/v1/sources （写操作仍走 /api/sources：v1 是只读门面，不做变更） - 编辑弹窗改用 /api/v1/sources/{name}?reveal=credentials（admin-only）取明文 key。这是必须的：表单要整体回传源，若不回填 key，改个端口就会把 key 清空。 - 遮蔽视图仍是默认，只有显式 reveal 才返回明文端到端验证（真浏览器 + 临时实例，非仅 API 测试）： - sources/sort/keys 三页实际发出 GET /api/v1/sources，0 console error - editSource('demo') → reveal=credentials，#s-key 与 #s-url 正确回填 - 写入往返：改 base_url /v1→/v2 后重开，key 仍在（未被清空） - 落盘 api_key 明文残留 0、密文 1 测试：+1（reveal 必须 admin，否则任意 user key 可读全部凭据）变异验证：reveal 去掉 admin 校验 → 403 断言变红 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-09-26 14:08:44 +08:00
llmsproxy	ad28a924a5	feat: 密钥静态加密 + /api/v1 agent 管理 API 密钥加密（写侧封存 / 读侧解封） - config.yaml 的 sources[].api_key、sources[].headers、keys[].key 落盘即 AES-256-GCM 密文（enc:v1: 前缀），master.key 复用 runtime store 那把 - 内存里永远是明文：鉴权比对、API 返回新建 key、WebUI 编辑回填都不受影响 - 启动时一次性封存现存明文（幂等，已封存则不写盘）；-check 不写文件 - UpsertSourceInYAML 增加 box 参数，新加的源不再以明文落盘 - 解密失败改为硬错误：原先 MustDecrypt 返回密文会被下次 Save 二次封存（实测：源 key 18→20、静默损坏），现在启动即失败且配置分毫不动 /api/v1：面向 agent 的管理 API（WebUI 零影响） - GET /api/v1 机器可读索引，列出每个端点的方法/权限/用途 - GET /api/v1/overview 一次调用看全貌：源 + AUTO 链 + 密钥数 + 健康度 - GET /api/v1/health 仅健康快照 - GET /api/v1/models 按源分组的可路由模型清单 - GET /api/v1/sources[/{name}] 凭据遮蔽后的源 - GET /api/v1/auto 调度链与实时槽位状态 - GET /api/v1/keys admin only，密钥元数据，绝不回显密钥本身 - 沿用同一套网关 key 鉴权；读端点任意角色，写仍需 admin 测试：15 个新用例（含负向：泄密、越权、写操作必须被拒）变异验证：maskKey 不遮蔽→红、去掉 admin 校验→红 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-09-26 14:01:47 +08:00
JianFeeeee	432129243e	chore(version): 1.5.9	2026-09-11 18:19:47 +08:00
JianFeeeee	c744ee151e	feat(opencode): 透传 completion_tokens_details.reasoning_tokens 与上游 cost 回答「opencodego 的用量与费用透传呢」时逐字段核对上游产出，发现 usage 漏了一项、费用整项丢失。 ## 上游实际发什么（实测 opencode.ai/zen/go/v1） { "choices": [...], "usage": { "prompt_tokens": 37, "completion_tokens": 40, "total_tokens": 77, "prompt_cache_hit_tokens": 0, "prompt_cache_miss_tokens": 37, "prompt_tokens_details": {"cached_tokens": 0}, "completion_tokens_details": {"reasoning_tokens": 40} }, "cost": "0" } cost 在顶层且是字符串。流式时还会单独发一帧： {"choices":[],"cost":"0"} ## 此前丢了两样 1. completion_tokens_details.reasoning_tokens —— 输出里有多少是思考 token。没有它，客户端无法判断 completion_tokens 里多少是可见回答、多少是思考，而两者都按输出计费。 2. cost —— 唯一的费用信号，网关整个丢弃。Go 订阅是包月制恒为 "0"，但 Zen 按量付费模型（以及未来的其它源）有信息量。顺带修掉一处流式/非流式不一致：命中缓存时上游同时给 prompt_tokens_details.cached_tokens 和独立的 hit/miss，流式路径写成了 elseif，只留 details，与非流式产出不同（只认独立字段的老客户端会看不到缓存）。 ## 实现 - types.TokenUsage += CompletionTokensDetails；UnifiedResponse / UnifiedChunk += Cost - opencodego/opencodezen 适配器映射两个字段；空 choices 帧改成 usage 与 cost 都可带（早退只带 usage 会把同帧的 cost 丢干净 —— 新测试先抓到的就是这个） - Gateway ChatCompletion / ChatChunk += cost，随终帧发（对齐上游的 {"choices":[],"cost":"0"} 形态） - Go 兜底 standardSSEChunk 同步支持（openai 系适配器不再漏 reasoning_tokens；纯 cost 帧不再被整体丢弃），新增 rawCostString 兼容字符串/数字两种形态费用只做搬运：不解析、不换算、不汇总 —— 它是上游事实，且只有部分上游提供。 ## 验证经网关实测 gozen:deepseek-v4.1-flash，流式与非流式产出逐字段一致： prompt_tokens_details.cached_tokens=6784 prompt_cache_hit_tokens=6784 / miss=148 completion_tokens_details.reasoning_tokens=16 cost="0" 测试：TestOpenCodeCostAndReasoningPassthrough（含「无数据不得凭空造字段」反例）、 TestOpenCodeStreamCacheFieldsMatchNonStream、TestTokenUsageMarshalsCompletionTokensDetails。	2026-09-11 18:19:40 +08:00