feat: 将插件 stdin 协议定为 v1，并按声明注入凭据

进程外插件改为只读环境变量和自身配置，避免读宿主 appsettings；宿主按 plugin.json 声明注入 LLM / OpenWeather 等凭据。
2026-09-11 10:46:52 +08:00
parent d1b979f2db
commit b631acd42e
22 changed files with 377 additions and 95 deletions
@@ -32,18 +32,16 @@ public sealed class CredentialPublicView
 /// </summary>
 public sealed class CredentialStore
 {
-    private readonly IConfiguration _config;
    private readonly Dictionary<string, CredentialRecord> _named = new(StringComparer.OrdinalIgnoreCase);

    public CredentialStore(IConfiguration config)
    {
-        _config = config;
        LlmOptions llm = AgentFactory.Load(config);
        _named["llm-default"] = new CredentialRecord
        {
            Id = "llm-default",
            Name = "系统默认模型",
-            Type = "openai-compatible",
+            Type = PluginCredentialTypes.OpenAiCompatible,
            Endpoint = llm.Endpoint,
            ApiKey = llm.ApiKey,
            Model = llm.Model,
@@ -53,23 +51,38 @@ public sealed class CredentialStore
        foreach (IConfigurationSection child in section.GetChildren())
        {
            string id = child.Key;
-            string type = child["type"] ?? "openai-compatible";
+            string type = child["type"] ?? PluginCredentialTypes.OpenAiCompatible;
            bool useLlm = string.Equals(child["source"], "llm-section", StringComparison.OrdinalIgnoreCase)
                || child.GetValue("useLlmSection", false);
-            CredentialRecord fallback = _named.GetValueOrDefault("llm-default")!;
+            CredentialRecord fallback = _named["llm-default"];
+            Dictionary<string, string> extra = new(StringComparer.OrdinalIgnoreCase);
+            foreach (IConfigurationSection extraChild in child.GetSection("extra").GetChildren())
+            {
+                if (!string.IsNullOrWhiteSpace(extraChild.Value))
+                {
+                    extra[extraChild.Key] = extraChild.Value;
+                }
+            }
+
+            string apiKey = First(
+                child["apiKey"],
+                useLlm ? fallback.ApiKey : null,
+                PluginCredentialTypes.IsOpenWeather(type) ? Environment.GetEnvironmentVariable("OPENWEATHER_API_KEY") : null);
+
            _named[id] = new CredentialRecord
            {
                Id = id,
                Name = child["name"] ?? id,
                Type = type,
                Endpoint = First(child["endpoint"], useLlm ? fallback.Endpoint : null),
-                ApiKey = First(child["apiKey"], useLlm ? fallback.ApiKey : null),
+                ApiKey = apiKey,
                Model = First(child["model"], useLlm ? fallback.Model : null),
+                Extra = extra,
            };
        }
    }

-    /// <summary>给前端的列表。Endpoint 目前未打码（学习项目）；ApiKey 绝不会出现在这里。</summary>
+    /// <summary>给前端的列表。ApiKey 绝不会出现在这里。</summary>
    public IReadOnlyList<CredentialPublicView> ListPublic()
        => _named.Values
            .OrderBy(item => item.Id, StringComparer.OrdinalIgnoreCase)
@@ -91,6 +104,23 @@ public sealed class CredentialStore
        throw new InvalidOperationException($"找不到凭据 `{id}`。请在 appsettings.json 的 Credentials 中配置，或改用 llm-default。");
    }

+    /// <summary>按插件声明的 type 取凭据。preferredId 类型不匹配时不会凑合用。</summary>
+    public CredentialRecord? TryResolveForType(string declaredType, string? preferredId)
+    {
+        if (!string.IsNullOrWhiteSpace(preferredId) && _named.TryGetValue(preferredId, out CredentialRecord? named))
+        {
+            if (!PluginCredentialTypes.Matches(declaredType, named.Type))
+            {
+                throw new InvalidOperationException(
+                    $"凭据 `{preferredId}` 的类型是 `{named.Type}`，插件声明需要 `{declaredType}`。");
+            }
+
+            return named;
+        }
+
+        return _named.Values.FirstOrDefault(item => PluginCredentialTypes.Matches(declaredType, item.Type));
+    }
+
    public PluginCredentialPayload ToPayload(CredentialRecord record)
        => new()
        {
@@ -16,14 +16,16 @@ public sealed class PluginProcessRunner(PluginOptions options, CredentialStore c
        LoadedPlugin plugin,
        Dictionary<string, object?> inputs,
        string? credentialId,
+        IReadOnlyDictionary<string, string>? credentialBindings,
        CancellationToken cancellationToken)
    {
        PluginManifest manifest = plugin.Manifest;
        ValidateDeclaredInputs(manifest, inputs);

-        Dictionary<string, PluginCredentialPayload> payload = ResolveCredentials(manifest, credentialId);
+        Dictionary<string, PluginCredentialPayload> payload = ResolveCredentials(manifest, credentialId, credentialBindings);
        PluginRequest request = new()
        {
+            ProtocolVersion = PluginProtocol.Normalize(manifest.ProtocolVersion),
            Inputs = inputs,
            Credentials = payload,
        };
@@ -75,33 +77,58 @@ public sealed class PluginProcessRunner(PluginOptions options, CredentialStore c
        return outputs;
    }

-    private Dictionary<string, PluginCredentialPayload> ResolveCredentials(PluginManifest manifest, string? credentialId)
+    private Dictionary<string, PluginCredentialPayload> ResolveCredentials(
+        PluginManifest manifest,
+        string? credentialId,
+        IReadOnlyDictionary<string, string>? credentialBindings)
    {
        Dictionary<string, PluginCredentialPayload> map = new(StringComparer.OrdinalIgnoreCase);
        foreach (PluginCredentialNeed need in manifest.Credentials)
        {
-            if (need.Type is "openai-compatible" or "llm" || need.Name.Equals("llm", StringComparison.OrdinalIgnoreCase))
+            if (string.IsNullOrWhiteSpace(need.Type) && string.IsNullOrWhiteSpace(need.Name))
            {
-                CredentialRecord record = credentials.Resolve(credentialId);
-                if (need.Required && string.IsNullOrWhiteSpace(record.ApiKey))
+                continue;
+            }
+
+            string declaredType = string.IsNullOrWhiteSpace(need.Type) ? need.Name : need.Type;
+            string? preferredId = null;
+            if (credentialBindings is not null
+                && !string.IsNullOrWhiteSpace(need.Name)
+                && credentialBindings.TryGetValue(need.Name, out string? bound)
+                && !string.IsNullOrWhiteSpace(bound))
+            {
+                preferredId = bound;
+            }
+            else if (PluginCredentialTypes.IsLlm(declaredType) || need.Name.Equals("llm", StringComparison.OrdinalIgnoreCase))
+            {
+                preferredId = credentialId;
+            }
+
+            CredentialRecord? record = credentials.TryResolveForType(declaredType, preferredId);
+            if (record is null)
+            {
+                if (need.Required)
                {
                    throw new InvalidOperationException(
-                        $"插件 {manifest.Id} 需要 LLM 凭据，但 `{record.Id}` 没有 API Key。请在环境变量 OPENAI_API_KEY 或 appsettings.json 中配置。");
+                        $"插件 {manifest.Id} 需要类型 `{declaredType}` 的凭据 `{need.Name}`，但宿主 Credentials 里没有匹配项。");
                }

-                map[need.Name] = credentials.ToPayload(record);
+                continue;
            }
-        }

-        if (manifest.Credentials.Count == 0)
-        {
-            map["llm"] = credentials.ToPayload(credentials.Resolve(credentialId));
+            if (need.Required && PluginCredentialTypes.IsLlm(declaredType) && string.IsNullOrWhiteSpace(record.ApiKey))
+            {
+                throw new InvalidOperationException(
+                    $"插件 {manifest.Id} 需要 LLM 凭据，但 `{record.Id}` 没有 API Key。请在环境变量 OPENAI_API_KEY 或 appsettings.json 中配置。");
+            }
+
+            map[string.IsNullOrWhiteSpace(need.Name) ? declaredType : need.Name] = credentials.ToPayload(record);
        }

        return map;
    }

-    /// <summary>工作目录=插件文件夹；环境变量带上 OPENAI_* 和 MAF1_CONTENT_ROOT。</summary>
+    /// <summary>工作目录=插件文件夹。凭据写入子进程环境变量，不读宿主 appsettings 路径。</summary>
    private ProcessStartInfo CreateStartInfo(LoadedPlugin plugin, Dictionary<string, PluginCredentialPayload> payload)
    {
        string command = plugin.Manifest.Launch.Command;
@@ -132,32 +159,13 @@ public sealed class PluginProcessRunner(PluginOptions options, CredentialStore c
            start.ArgumentList.Add(arg);
        }

-        start.Environment["MAF1_CONTENT_ROOT"] = AppContext.BaseDirectory;
        ApplyDotEnv(plugin.FolderPath, start);
        foreach (KeyValuePair<string, string> pair in plugin.Manifest.Env)
        {
            start.Environment[pair.Key] = pair.Value;
        }

-        if (payload.TryGetValue("llm", out PluginCredentialPayload? llm) || payload.Count > 0)
-        {
-            llm ??= payload.Values.First();
-            if (!string.IsNullOrWhiteSpace(llm.ApiKey))
-            {
-                start.Environment["OPENAI_API_KEY"] = llm.ApiKey;
-            }
-
-            if (!string.IsNullOrWhiteSpace(llm.Endpoint))
-            {
-                start.Environment["OPENAI_ENDPOINT"] = llm.Endpoint;
-            }
-
-            if (!string.IsNullOrWhiteSpace(llm.Model))
-            {
-                start.Environment["OPENAI_CHAT_MODEL"] = llm.Model;
-            }
-        }
-
+        PluginStdio.ApplyCredentialsToEnvironment(payload, start.Environment);
        return start;
    }

@@ -76,6 +76,20 @@ public sealed class PluginScanner(PluginOptions options)
                continue;
            }

+            int protocol = PluginProtocol.Normalize(manifest.ProtocolVersion);
+            if (!PluginProtocol.IsSupported(manifest.ProtocolVersion))
+            {
+                issues.Add(new CatalogIssue
+                {
+                    Level = "error",
+                    Source = manifest.Id,
+                    Message = $"plugin.json 的 protocolVersion={protocol} 不受支持。当前宿主只接受 1（缺省视为 1）。",
+                });
+                continue;
+            }
+
+            manifest.ProtocolVersion = protocol;
+
            if (!ids.Add(manifest.Id))
            {
                issues.Add(new CatalogIssue