EINO_ADOPTION.md

@@ -13,6 +13,7 @@
 - [~] **Phase D · 状态化执行**：✅ 任务生命周期 FSM（已完成）/ ⬜ HITL 中断恢复 / ⬜ 多智能体（按场景）
 
 **组件化补完（A）**：检索 → `ragRetriever`(`components/retriever.Retriever`，`eino_components.go`)；提示词 → `buildMessages` 改用 `prompt.FromMessages`+`MessagesPlaceholder`；工具 → `mcpTool`(`InvokableTool`，模型自主调用)。至此终态架构 8 层中 模型/工具/检索/提示词/编排/智能体(单)/可观测 均已 Eino 组件化；剩 人机交互(中断恢复，按场景)。
+**自主 agent 工具集动态化**：agent 工具集不再硬编码——mcp-go 注册表(单一事实源)每个工具声明 `agent/params/inject`，`list_tools` 上报，dispatcher `agentTools()` 动态发现并建 `InvokableTool`、运行时注入 `user_id/session_id/kb`（不暴露给模型）。**加工具只改 mcp-go 注册表，dispatcher 零改动。** 当前暴露 4 个(wiki_search/recall_user_memory/remember_user_fact/history_get)；实测模型自主调用新暴露的 remember_user_fact 成功（参数自生成、user_id 服务端注入）。
 **性能注记**：compose 每任务编译实测 ~13µs（基准 BenchmarkComposeCompile），相对 LLM 秒级可忽略 → 编译图缓存判定为 premature optimization，暂不做；真正的并行效率已由 Phase C 的 DAG 调度（`AllPredecessor`）拿到。
 
 ---

sundynix-dispatcher/internal/eino/react_agent.go

@@ -85,42 +85,75 @@ func (m *mcpTool) InvokableRun(ctx context.Context, argsJSON string, _ ...tool.O
 	return res.Content, nil
 }
 
-// agentTools 构建 ReAct 可用的工具集（按当前任务上下文绑定 uid/kb）。
-// 工具名是给"模型看"的语义名；mcpName 是实际 NATS 调用名。context 参数（user_id）服务端注入，不暴露给模型。
+// toolCatalogEntry 是 MCP list_tools 上报的一条工具元信息（与 mcp-go listTools 输出对齐）。
+type toolCatalogEntry struct {
+	Name      string `json:"name"`
+	CN        string `json:"cn"`
+	Desc      string `json:"desc"`
+	Agent     bool   `json:"agent_exposed"`
+	AgentName string `json:"agent_name"`
+	Params    []struct {
+		Name     string `json:"name"`
+		Type     string `json:"type"`
+		Desc     string `json:"desc"`
+		Required bool   `json:"required"`
+	} `json:"params"`
+	Inject []string `json:"inject"`
+}
+
+// agentTools 动态构建 ReAct 可用的工具集：调 MCP list_tools 自描述目录 → 取 agent_exposed 的工具
+// → 用上报的参数 schema 建 InvokableTool；inject 参数（user_id/session_id/kb/task_id）服务端运行时
+// 绑定、不暴露给模型。新增工具只需在 mcp-go 注册表标 agent，无需改这里（杜绝硬编码）。
 func (o *Orchestrator) agentTools(b *board, taskID string, tr *execTracer) []tool.BaseTool {
 	if o.tools == nil {
 		return nil
 	}
-	kbBind := map[string]any{}
-	if b.kb != "" {
-		kbBind["kb"] = b.kb
+	cctx, cancel := context.WithTimeout(context.Background(), toolCallTimeout)
+	defer cancel()
+	res, err := o.tools.CallTool(cctx, contract.ToolSubjectGo("list_tools"), &contract.ToolCall{Tool: "list_tools"})
+	if err != nil || res == nil || !res.OK {
+		return nil
 	}
-	return []tool.BaseTool{
-		&mcpTool{
-			mcpName: "wiki_search",
+	var cat struct {
+		Tools []toolCatalogEntry `json:"tools"`
+	}
+	if json.Unmarshal([]byte(res.Content), &cat) != nil {
+		return nil
+	}
+	// inject 参数名 → 本任务的运行时值（不进模型菜单）。
+	injectVal := map[string]any{"user_id": b.uid, "session_id": b.sid, "task_id": taskID, "kb": b.kb}
+
+	var out []tool.BaseTool
+	for _, e := range cat.Tools {
+		if !e.Agent {
+			continue
+		}
+		params := map[string]*schema.ParameterInfo{}
+		for _, p := range e.Params {
+			params[p.Name] = &schema.ParameterInfo{Type: schema.DataType(p.Type), Desc: p.Desc, Required: p.Required}
+		}
+		bind := map[string]any{}
+		for _, inj := range e.Inject {
+			if v, ok := injectVal[inj]; ok && v != "" {
+				bind[inj] = v
+			}
+		}
+		name := e.AgentName
+		if name == "" {
+			name = e.Name
+		}
+		out = append(out, &mcpTool{
+			mcpName: e.Name,
 			subject: contract.ToolSubjectGo,
 			caller:  o.tools, taskID: taskID, tr: tr,
-			bind: kbBind,
+			bind: bind,
 			info: &schema.ToolInfo{
-				Name: "wiki_search",
-				Desc: "检索知识库，返回与查询最相关的资料片段。需要外部知识/事实依据时调用。",
-				ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
-					"q": {Type: schema.String, Desc: "检索查询语句", Required: true},
-				}),
+				Name: name, Desc: e.Desc,
+				ParamsOneOf: schema.NewParamsOneOfByParams(params),
 			},
-		},
-		&mcpTool{
-			mcpName: "memory_get",
-			subject: contract.ToolSubjectGo,
-			caller:  o.tools, taskID: taskID, tr: tr,
-			bind: map[string]any{"user_id": b.uid},
-			info: &schema.ToolInfo{
-				Name: "recall_user_memory",
-				Desc: "召回当前用户的长期画像与偏好（称呼/职业/回答偏好等）。需要个性化、了解“我是谁”时调用。",
-				ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{}),
-			},
-		},
+		})
 	}
+	return out
 }
 
 // runReactAgent 执行带"自主工具"的 agent 节点：模型在 ReAct 循环里自行决定调哪些 MCP 工具。

sundynix-mcp-go/internal/mcp/gateway.go

@@ -32,11 +32,25 @@ type Gateway struct {
 	tools   map[string]toolDef // 工具注册表：唯一事实源，dispatch 与 list_tools 共用，杜绝漂移
 }
 
-// toolDef 是一个注册工具的元信息（中文名 / 作用）+ 处理函数。
+// paramSpec 是一个工具参数的声明（供自主 agent 据此生成调用入参）。
+type paramSpec struct {
+	Name     string `json:"name"`
+	Type     string `json:"type"` // string / number / integer / boolean / object / array
+	Desc     string `json:"desc"`
+	Required bool   `json:"required"`
+}
+
+// toolDef 是一个注册工具的元信息 + 处理函数。新增 agent 暴露元信息，让自主 agent 能动态发现工具：
+// agent=是否给模型自主调用；agentName=模型可见名（空=注册键）；params=模型可填参数；
+// inject=服务端运行时注入、不暴露给模型的参数名（如 user_id / session_id / kb / task_id）。
 type toolDef struct {
-	cn      string // 中文名
-	desc    string // 作用简述
-	handler func(context.Context, *contract.ToolCall) *contract.ToolResult
+	cn        string
+	desc      string
+	agent     bool
+	agentName string
+	params    []paramSpec
+	inject    []string
+	handler   func(context.Context, *contract.ToolCall) *contract.ToolResult
 }
 
 func NewGateway(b *sharedbus.Bus, s *search.Hybrid, m *memory.Store, h *history.Store, r *rag.Engine) *Gateway {
@@ -60,29 +74,53 @@ func (g *Gateway) Serve(ctx context.Context) error {
 
 // buildRegistry 注册 mcp-go 全部工具：名称 → (中文名, 作用, 处理函数)。
 // 这是工具的唯一事实源——dispatch 据此路由、list_tools 据此上报，二者永不漂移。
+// 想让某工具能被自主 agent 调用：把 agent 设 true，写清 params（模型可填）与 inject（服务端注入）。
+// 加新工具只改这一处——dispatcher 经 list_tools 动态发现，无需改调度代码。
 func (g *Gateway) buildRegistry() map[string]toolDef {
 	return map[string]toolDef{
-		"wiki_search":    {"知识检索", "向量检索知识库（Milvus），返回最相关片段", g.wikiSearch},
-		"kb_ingest":      {"知识入库", "文本切块 → 向量化 → 写入 Milvus / Bleve", g.kbIngest},
-		"kb_search":      {"检索台查询", "结构化返回命中内容与相似度分数", g.kbSearch},
-		"kb_graph":       {"知识图谱", "取某库的实体关系三元组（Neo4j）", g.kbGraph},
-		"report_render":  {"报告渲染", "把结构化报告渲染为 Word（.docx）", g.reportRender},
-		"report_store":   {"报告存源", "暂存报告源数据，供导出时按需渲染", g.reportStore},
-		"report_export":  {"报告导出", "按需把已存报告导出为 Word / Markdown", g.reportExport},
-		"external_api":   {"外部接口", "受控调用第三方 HTTP API（带 SSRF 校验）", g.externalAPI},
-		"memory_get":     {"记忆召回", "取用户长期画像（已按打分排序）", g.memoryGet},
-		"memory_upsert":  {"记忆写入", "新增 / 更新一条用户偏好（带重要度）", g.memoryUpsert},
-		"memory_delete":  {"记忆删除", "软删一条偏好（对账判定过时 / 矛盾时）", g.memoryDelete},
-		"memory_list":    {"记忆列表", "列出用户全部偏好（供管理面板查看）", g.memoryList},
-		"history_get":    {"历史召回", "取会话最近多轮对话", g.historyGet},
-		"history_append": {"历史追加", "往会话写入一条消息", g.historyAppend},
-		"health": {"健康检查", "上报 Milvus / Neo4j / embedding 就绪情况",
-			func(_ context.Context, _ *contract.ToolCall) *contract.ToolResult {
+		// —— 暴露给自主 agent 的工具（带参数 schema / 注入声明）——
+		"wiki_search": {
+			cn: "知识检索", desc: "检索知识库，返回与查询最相关的资料片段。需要外部知识/事实依据时调用。",
+			agent: true,
+			params: []paramSpec{{Name: "q", Type: "string", Desc: "检索查询语句", Required: true}},
+			inject: []string{"kb"}, handler: g.wikiSearch,
+		},
+		"memory_get": {
+			cn: "记忆召回", desc: "召回当前用户的长期画像与偏好（称呼/职业/回答偏好等）。需要个性化、了解“我是谁”时调用。",
+			agent: true, agentName: "recall_user_memory", inject: []string{"user_id"}, handler: g.memoryGet,
+		},
+		"memory_upsert": {
+			cn: "记忆写入", desc: "把关于用户的一条事实/偏好长期记住（如称呼、职业、回答偏好）。",
+			agent: true, agentName: "remember_user_fact",
+			params: []paramSpec{
+				{Name: "key", Type: "string", Desc: "记忆条目的键，如 称呼/职业/回答偏好", Required: true},
+				{Name: "value", Type: "string", Desc: "记忆条目的值", Required: true},
+			},
+			inject: []string{"user_id"}, handler: g.memoryUpsert,
+		},
+		"history_get": {
+			cn: "历史召回", desc: "取当前会话最近多轮对话，用于理解上下文。",
+			agent: true, inject: []string{"session_id"}, handler: g.historyGet,
+		},
+
+		// —— 仅内部/流水线/管理用，不暴露给自主 agent ——
+		"kb_ingest":      {cn: "知识入库", desc: "文本切块 → 向量化 → 写入 Milvus / Bleve", handler: g.kbIngest},
+		"kb_search":      {cn: "检索台查询", desc: "结构化返回命中内容与相似度分数", handler: g.kbSearch},
+		"kb_graph":       {cn: "知识图谱", desc: "取某库的实体关系三元组（Neo4j）", handler: g.kbGraph},
+		"report_render":  {cn: "报告渲染", desc: "把结构化报告渲染为 Word（.docx）", handler: g.reportRender},
+		"report_store":   {cn: "报告存源", desc: "暂存报告源数据，供导出时按需渲染", handler: g.reportStore},
+		"report_export":  {cn: "报告导出", desc: "按需把已存报告导出为 Word / Markdown", handler: g.reportExport},
+		"external_api":   {cn: "外部接口", desc: "受控调用第三方 HTTP API（带 SSRF 校验）", handler: g.externalAPI},
+		"memory_delete":  {cn: "记忆删除", desc: "软删一条偏好（对账判定过时 / 矛盾时）", handler: g.memoryDelete},
+		"memory_list":    {cn: "记忆列表", desc: "列出用户全部偏好（供管理面板查看）", handler: g.memoryList},
+		"history_append": {cn: "历史追加", desc: "往会话写入一条消息", handler: g.historyAppend},
+		"health": {cn: "健康检查", desc: "上报 Milvus / Neo4j / embedding 就绪情况",
+			handler: func(_ context.Context, _ *contract.ToolCall) *contract.ToolResult {
 				data, _ := json.Marshal(g.rag.Status())
 				return &contract.ToolResult{OK: true, Content: string(data)}
 			}},
-		"echo": {"回显", "原样返回入参（调试用）",
-			func(_ context.Context, call *contract.ToolCall) *contract.ToolResult {
+		"echo": {cn: "回显", desc: "原样返回入参（调试用）",
+			handler: func(_ context.Context, call *contract.ToolCall) *contract.ToolResult {
 				return &contract.ToolResult{OK: true, Content: fmt.Sprint(call.Args["text"])}
 			}},
 	}
@@ -102,16 +140,24 @@ func (g *Gateway) dispatch(ctx context.Context, call *contract.ToolCall) *contra
 	return td.handler(ctx, call)
 }
 
-// listTools 自省：上报本服务注册的工具清单（名称 + 中文名 + 作用），供管理端展示。
+// listTools 自省：上报本服务注册的工具清单（名称 + 中文名 + 作用 + agent 暴露元信息），
+// 供管理端展示 & dispatcher 动态构建自主 agent 工具集（加工具只改注册表，无需改调度代码）。
 func (g *Gateway) listTools() *contract.ToolResult {
 	type info struct {
-		Name string `json:"name"`
-		CN   string `json:"cn"`
-		Desc string `json:"desc"`
+		Name      string      `json:"name"`
+		CN        string      `json:"cn"`
+		Desc      string      `json:"desc"`
+		Agent     bool        `json:"agent_exposed"`       // 是否给自主 agent
+		AgentName string      `json:"agent_name,omitempty"`// 模型可见名（空=name）
+		Params    []paramSpec `json:"params,omitempty"`    // 模型可填参数
+		Inject    []string    `json:"inject,omitempty"`    // 服务端注入参数（不暴露给模型）
 	}
 	out := make([]info, 0, len(g.tools))
 	for name, td := range g.tools {
-		out = append(out, info{Name: name, CN: td.cn, Desc: td.desc})
+		out = append(out, info{
+			Name: name, CN: td.cn, Desc: td.desc,
+			Agent: td.agent, AgentName: td.agentName, Params: td.params, Inject: td.inject,
+		})
 	}
 	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name }) // map 无序 → 稳定输出
 	data, _ := json.Marshal(map[string]any{"service": "mcp-go", "tools": out})