docs(gateway): gateway 剩余文件注释改中文（逐行 1:1，代码零字节改动）

主人 2026-10-03 拍板「注释一律中文」；gateway 至此整包注释中文化完成（本会话共 3 批：已推库 16 个文件 + 本批剩余文件）。校验：机械校验（非注释改动行）= 空；剥注释后代码文本逐行比对全等（不一致文件数 0）；全树 go test ./... 58 包 ok / 0 FAIL；交叉编译绿。
2026-10-03 22:28:25 +08:00
1 parent 91e8d7a029
commit 074ffc4ebf
@@ -1,13 +1,13 @@
 package gateway

-// Admin plugin install/uninstall and the installed-plugin listing. A runtime
-// "plugin" in v1 is an external MCP server: install connects it, hot-registers
-// its tools into the capability registry (so they are injected into the next
-// model request without a restart), persists its config to the gitignored
-// plugins.json, and holds the live server for a later refresh/uninstall
-// (design/09 插件生态 §1). Installing a compiled Go plugin is impossible in a
-// single static binary, so it is not offered. Writes are owner-only and audited;
-// an API key is persisted but never returned or logged verbatim.
+// 管理侧插件安装/卸载与已安装插件列表。v1 中的运行时
+// 「插件」是一个外部 MCP server：安装即连接它、把它的
+// 工具热注册进能力注册表（从而无需重启就注入下一次
+// 模型请求），把其配置持久化到被 gitignore 的
+// plugins.json，并持有活着的 server 以便之后刷新/卸载
+// （design/09 插件生态 §1）。在单静态二进制中安装编译好的 Go 插件
+// 不可能，因此不提供该方式。写操作仅 owner 且带审计；
+// API key 会被持久化，但绝不返回，也绝不原样记日志。

 import (
 	"context"
@@ -24,28 +24,28 @@ import (
 	apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors"
 )

-// pluginInstallTimeout bounds the connect+discover handshake the install request
-// waits for. The plugin manager applies its own per-server timeout inside it.
+// pluginInstallTimeout 限定安装请求所等待的 connect+discover 握手
+// 时长。插件管理器在其中施加自己的每 server 超时。
 const pluginInstallTimeout = 20 * time.Second

-// pluginActionRequest is the POST /api/v1/admin/plugins/uninstall body.
+// pluginActionRequest 是 POST /api/v1/admin/plugins/uninstall 的请求体。
 type pluginActionRequest struct {
 	Name string `json:"name"`
 	Kind string `json:"kind"`
 }

-// pluginInstallRequest is the POST /api/v1/admin/plugins/install body. Config
-// carries the MCP server connection fields; the top-level name/kind are kept
-// separate so the request reads like the other admin writes.
+// pluginInstallRequest 是 POST /api/v1/admin/plugins/install 的请求体。Config
+// 承载 MCP server 连接字段；顶层的 name/kind 被单独
+// 保留，使该请求读起来与其他管理写一致。
 type pluginInstallRequest struct {
 	Kind   string              `json:"kind"`
 	Name   string              `json:"name"`
 	Config pluginInstallConfig `json:"config"`
 }

-// pluginInstallConfig is the MCP server connection block. Endpoint is the URL
-// for http/sse; url is accepted as an alias. APIKey/Env are persisted but never
-// echoed back.
+// pluginInstallConfig 是 MCP server 连接块。Endpoint 是 http/sse
+// 的 URL；url 作为别名被接受。APIKey/Env 会被持久化，但绝不
+// 回显。
 type pluginInstallConfig struct {
 	Transport string            `json:"transport"`
 	Endpoint  string            `json:"endpoint"`
@@ -56,8 +56,8 @@ type pluginInstallConfig struct {
 	Env       map[string]string `json:"env"`
 }

-// AdminInstalledPlugin is the wire shape of one installed plugin in the admin
-// list. The API key and any sensitive env values are masked.
+// AdminInstalledPlugin 是管理列表中一个已安装插件的线上
+// 结构。API key 与任何敏感 env 值都会脱敏。
 type AdminInstalledPlugin struct {
 	ID        string            `json:"id"`
 	Name      string            `json:"name"`
@@ -69,16 +69,16 @@ type AdminInstalledPlugin struct {
 	APIKey    string            `json:"apiKey,omitempty"`
 	Env       map[string]string `json:"env,omitempty"`
 	CreatedAt string            `json:"createdAt,omitempty"`
-	// Live reports whether the MCP server is connected and its tools registered.
+	// Live 报告 MCP server 是否已连接、其工具是否已注册。
 	Live bool `json:"live"`
-	// ToolCount is the number of tools the live server registered.
+	// ToolCount 是活着的 server 已注册的工具数。
 	ToolCount int `json:"toolCount"`
 }

-// adminPluginInstall installs (or refreshes) an MCP server plugin: it validates
-// the request, connects and discovers the server's tools, then persists the
-// config. A connect/discover/register failure returns 502 and persists nothing,
-// so a plugin is never half-installed.
+// adminPluginInstall 安装（或刷新）一个 MCP server 插件：它校验
+// 请求、连接并发现该 server 的工具，然后持久化配置。
+// connect/discover/register 失败会返回 502 且不持久化任何东西，
+// 因此插件绝不会处于半安装状态。
 func (s *Server) adminPluginInstall(w http.ResponseWriter, r *http.Request) {
 	var req pluginInstallRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
@@ -145,10 +145,10 @@ func (s *Server) adminPluginInstall(w http.ResponseWriter, r *http.Request) {
 	})
 }

-// adminPluginUninstall uninstalls a plugin. An installed MCP server is closed and
-// its tools removed through the plugin manager, then its config is deleted from
-// plugins.json; any other name falls back to removing the capability from the
-// registry, preserving the pre-existing behavior.
+// adminPluginUninstall 卸载一个插件。已安装的 MCP server 会被关闭、
+// 其工具经插件管理器移除，随后其配置从 plugins.json 删除；
+// 其他任何名字回退为把该能力从注册表移除，
+// 保持既有行为。
 func (s *Server) adminPluginUninstall(w http.ResponseWriter, r *http.Request) {
 	var req pluginActionRequest
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
@@ -194,9 +194,9 @@ func (s *Server) adminPluginUninstall(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{"name": name, "uninstalled": true})
 }

-// adminListInstalledPlugins lists the runtime-installed plugins with their
-// masked config and per-server tool count. It is a read endpoint (owner/admin)
-// and never returns an API key or a sensitive env value verbatim.
+// adminListInstalledPlugins 列出运行时安装的插件，附其脱敏配置
+// 与每 server 工具数。它是读端点（owner/admin），
+// 绝不原样返回 API key 或敏感 env 值。
 func (s *Server) adminListInstalledPlugins(w http.ResponseWriter, r *http.Request) {
 	out := make([]AdminInstalledPlugin, 0)
 	if s.plugins != nil {
@@ -207,7 +207,7 @@ func (s *Server) adminListInstalledPlugins(w http.ResponseWriter, r *http.Reques
 	writeJSON(w, http.StatusOK, out)
 }

-// adminInstalledPluginOf maps an installed plugin to its masked wire shape.
+// adminInstalledPluginOf 把已安装插件映射为其脱敏后的线上结构。
 func adminInstalledPluginOf(it pluginmgr.Installed) AdminInstalledPlugin {
 	cfg := runtimeconfig.MaskedPlugin(it.Config)
 	return AdminInstalledPlugin{
@@ -226,8 +226,8 @@ func adminInstalledPluginOf(it pluginmgr.Installed) AdminInstalledPlugin {
 	}
 }

-// firstNonEmpty returns the first non-blank value, so an install body may send
-// either endpoint or url for the server address.
+// firstNonEmpty 返回首个非空值，因此安装请求体可用 endpoint
+// 或 url 任一字段给出 server 地址。
 func firstNonEmpty(values ...string) string {
 	for _, v := range values {
 		if strings.TrimSpace(v) != "" {