docs(mcp): 存量英文注释中文化(仅注释,代码零字节改动)

- capability/mcp 整包 17 个文件核查:仅 config.go / registry.go 含英文注释(38 行)→ 全部中文化;
  其余 15 个文件本就全中文,零改动。
- 保留 YAML/Go/JSON 示例行与字符串字面量(非注释,禁止改动)。
- 验收:机械校验为空;gofmt -l 干净;go build/vet/test ./internal/capability/mcp/... 全绿。
This commit is contained in:
AskaEth committed 2026-10-04 16:58:01 +08:00
1 parent 2593765add
commit 5c2189efb0
2 files changed
+31 -38

No files matched your search

+19 -24
View File
@@ -10,8 +10,8 @@ import (
"git.yeij.top/AskaEth/Cyrene_v2/internal/capability/registry"
)
// Registry connects an MCP client and auto-registers its discovered tools into
// the shared capability registry, making them available to every character.
// Registry 连接一台 MCP 客户端,把自动发现的工具注册进共享的 capability
// registry,使所有角色都能使用。
type Registry struct {
reg *registry.Registry
mcp *Client
@@ -21,11 +21,10 @@ type Registry struct {
closed bool
}
// NewRegistry builds a Registry that registers cfg's tools into reg. Options
// apply to the underlying Client (logger, injected transport). It is named
// NewRegistry rather than New because this package already exports New for
// Client. A tool-list-changed handler is wired automatically so the registry
// re-syncs when the server announces tools/list_changed.
// NewRegistry 构建一个 Registry,把 cfg 的工具注册进 reg。opts 作用在底层
// Client 上(日志器、注入的传输)。之所以叫 NewRegistry 而不是 New,是因为
// 本包已为 Client 导出了 New。这里会自动接上工具清单变更回调,
// 服务器发 tools/list_changed 时 registry 会重新同步。
func NewRegistry(reg *registry.Registry, cfg MCPConfig, opts ...Option) *Registry {
r := &Registry{reg: reg}
opts = append(opts, WithToolListChangedHandler(r.refresh))
@@ -35,8 +34,7 @@ func NewRegistry(reg *registry.Registry, cfg MCPConfig, opts ...Option) *Registr
return r
}
// Register connects the MCP server, discovers its tools, and registers each one
// into the underlying registry.
// Register 连接 MCP 服务器、发现其工具,并把每把工具注册进底层 registry。
func (r *Registry) Register(ctx context.Context) error {
if r.reg == nil {
return fmt.Errorf("mcp registry: nil registry")
@@ -64,12 +62,10 @@ func (r *Registry) Register(ctx context.Context) error {
return nil
}
// refresh re-syncs the registered tool set with the server after a
// notifications/tools/list_changed notification. It re-discovers the current
// tools and applies only the diff: it removes names that are gone and registers
// newly appeared ones, so tools registered by other providers (which collide by
// name) are preserved. It is invoked (off the transport read path) by the
// client's tool-list-changed handler and coalesced by the client.
// refresh 在收到 notifications/tools/list_changed 通知后,把已注册工具集与
// 服务器重新对齐。它重新发现当前工具并只应用差异:移除已消失的名字、
// 注册新出现的名字,因此其它提供者注册的同名工具(名字冲突)会被保留。
// 它由客户端的工具清单变更回调调用(不在传输读路径上),并由客户端合并触发。
func (r *Registry) refresh() {
if r.reg == nil {
return
@@ -91,9 +87,8 @@ func (r *Registry) refresh() {
return
}
// Drop names the server no longer exposes. Tools registered by other
// providers were skipped at registration time and are not in r.names, so they
// are never removed here.
// 丢弃服务器不再暴露的名字。其它提供者注册的工具在注册时就被跳过、
// 不在 r.names 里,因此这里永远不会把它们删掉。
kept := r.names[:0]
for _, name := range r.names {
if !incoming[name] {
@@ -106,8 +101,8 @@ func (r *Registry) refresh() {
}
r.names = kept
// Register newly appeared tools. Skips names already present (own or
// foreign) so a name collision with another provider is not doubled.
// 注册新出现的工具。跳过已存在的名字(无论是自己的还是外来的),
// 避免与其它提供者同名时重复注册。
existing := make(map[string]bool, len(r.names))
for _, name := range r.names {
existing[name] = true
@@ -127,16 +122,16 @@ func (r *Registry) refresh() {
r.log.Info("mcp tools refreshed", "name", r.mcp.cfg.Name, "count", len(r.names))
}
// ToolNames returns a copy of the tool names this registry registered, in
// registration order. It is empty before Register succeeds.
// ToolNames 返回本 registry 注册过的工具名副本(按注册顺序)。
// Register 成功之前为空。
func (r *Registry) ToolNames() []string {
r.mu.Lock()
defer r.mu.Unlock()
return append([]string(nil), r.names...)
}
// Unregister removes every tool this registry previously registered and closes
// the underlying client. It is safe to call multiple times.
// Unregister 移除本 registry 之前注册的全部工具,并关闭底层客户端。
// 可安全重复调用。
func (r *Registry) Unregister(ctx context.Context) error {
r.mu.Lock()
names := r.names