> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/micro/go-micro) · [上游 README](https://github.com/micro/go-micro/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 # Go Micro [](https://pkg.go.dev/go-micro.dev/v6?tab=doc) [](https://discord.gg/G8Gk5j3uXr) Go Micro 是一个面向 Go 的 **agent harness（智能体运行时框架）** 与服务框架。 **社区：** 有问题、有想法，或想与我们一起构建？[加入 Discord](https://discord.gg/G8Gk5j3uXr). Harness 是围绕智能体的运行时：它能调用的工具、它保留的记忆、约束它的护栏、触发它的工作流、它依赖的服务，以及其他智能体与之通信所使用的协议。 Go Micro 以 Go 代码的形式提供该 harness。构建一个智能体即可获得模型、记忆、工具、规划、委派、护栏与服务发现；可通过 [MCP](https://modelcontextprotocol.io/) 和 [A2A](https://a2a-protocol.org). 被访问。编写服务后，每个端点都会成为 AI 可调用的工具。用持久化 flow 编排确定性部分。智能体、服务与 flow 共享同一运行时，因为智能体本质上是一个分布式系统，构建智能体就是在构建服务。 ## 赞助商       **想支持 Go Micro 并在此展示你的 logo？** [成为赞助商](https://discord.gg/G8Gk5j3uXr) — 可通过 Discord 联系。 ## 商业支持 要在生产环境运行 Go Micro，或基于它进行开发并需要帮助？可直接向维护者购买 **支持、咨询、培训与 retainer（长期服务）** — 这些也是项目得以持续维护的支撑。详见 [**Support**](SUPPORT.md) 中的层级说明，或 [提交请求](https://github.com/micro/go-micro/issues/new?template=commercial_support.md). ## 目录 - [快速开始](#quick-start) - [首个智能体入门路径](#first-agent-on-ramp) - [为何需要 Agent Harness](#why-an-agent-harness) - [编写服务](#writing-services) - [构建智能体](#building-agents) — [规划与委派](#plan--delegate)、[可插拔](#batteries-included-pluggable)、[付费工具 (x402)](#paid-tools-x402)、[A2A](#reachable-by-other-agents-a2a) - [功能特性](#features) - [CLI](#cli) - [自主改进循环](#autonomous-improvement-loop) - [多服务项目](#multi-service-projects) - [数据模型](#data-model) - [AI 提供商](#ai-providers) - [示例](#examples) - [商业支持](#commercial-support) - [文档](#docs) ## 快速开始 安装 CLI： ```bash # Binary (no Go required) curl -fsSL https://go-micro.dev/install.sh | sh # Or with Go go install go-micro.dev/v6/cmd/micro@latest ``` 如果安装或 `PATH` 检查失败，在搭建第一个服务之前，请先参阅 [安装故障排除指南](internal/website/docs/guides/install-troubleshooting.md)。 ### 最快上手 — 无需 API key 搭建服务、运行并调用： ```bash micro new helloworld cd helloworld micro run ``` 然后在另一个终端中： ```bash curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \ -H 'Content-Type: application/json' -d '{"name":"World"}' ``` 这条 安装 → 搭建 → 运行 → 调用 路径由无密钥 CI harness 覆盖。若要在无网络访问或提供商密钥的情况下，仅验证本地安装器与首次运行 CLI 边界，请使用： ```bash make install-smoke ``` 若要验证聚焦的 CLI 内循环契约 — 搭建 → 运行/聊天/检查 → 部署 dry-run — 请使用： ```bash make inner-loop ``` 若仅运行 CI 守护的有序 [0→hero 服务 → 智能体 → 工作流 脚本](internal/website/docs/guides/zero-to-hero.md)，请使用： ```bash make zero-to-hero-transcript ``` 若要运行更广泛的本地契约（包括该脚本、聊天/检查 CLI 边界以及部署 dry-run），请使用： ```bash make harness ``` ### 首个智能体入门路径 完成安装并进行首次 `micro new`/`micro run` 冒烟检查后，按以下顺序走可逐步跟进的智能体路径： 1. [安装故障排除](internal/website/docs/guides/install-troubleshooting.md) — 在开始智能体相关工作前，验证二进制安装器或 `go install`、`PATH`、`micro --version`，以及无密钥冒烟路径。 运行 `make docs-wayfinding` 以验证聚焦的无密钥 docs/CLI 契约，确保本 README 与网站命令与已安装的 CLI 保持一致。 2. `micro agent demo` — 从已安装的 CLI 打印无需提供商的首个智能体演示命令及后续文档步骤。 3. `micro agent quickcheck`（或 `micro agent debug`）— 当 搭建 → 运行 → 聊天 → 检查 流程卡住时，在深入完整调试指南前，先打印简短恢复路线图。 4. `micro examples` — 按可复制/粘贴顺序打印维护中的、无需提供商的可运行示例。 5. `micro zero-to-hero` — 打印维护中的一条命令无密钥生命周期 harness 与可运行示例。 6. [示例导航索引](examples/INDEX.md) — 从一张地图中选择最小的无密钥首个智能体示例、维护中的 [0→hero 支持参考](examples/support/)，以及后续互操作示例。 7. [最小首个智能体示例](examples/first-agent/) — 使用 mock 模型且无需提供商密钥，运行一个由服务支撑的智能体。 8. [无密钥首个智能体脚本](internal/website/docs/guides/no-secret-first-agent.md) — 使用 mock 模型运行维护中的支持智能体，在无密钥情况下见证 服务 → 智能体 → 工作流 成功。 9. [你的第一个智能体](internal/website/docs/guides/your-first-agent.md) — 构建一个由服务支撑的智能体，并通过 `micro chat` 与之对话。 10. [调试你的智能体](internal/website/docs/guides/debugging-agents.md) — 在 `micro run` 之前使用 `micro agent preflight`，在 `micro run` 之后使用 `micro agent doctor`， 然后使用 `micro chat` 和 `micro inspect agent ` 恢复运行历史、记忆 以及提供商检查，以应对首次对话出现意外行为的情况。 11. [0→hero 参考](internal/website/docs/guides/zero-to-hero.md) — 通过与服务维护 harness 一致的 搭建、运行、聊天、检查、flow 历史与部署 dry-run 命令，完成 服务 → 智能体 → 工作流 循环。 ### 自主改进循环 想将同样的 服务 → 智能体 → 工作流 生命周期应用到你的仓库？`micro loop` 会搭建 Go Micro 自身使用的自主改进循环：North Star、排序后的问题队列、角色提示词、GitHub Actions 工作流，以及面向 CI 门禁 PR 的验证。 ```bash micro loop init --roles all micro loop verify ``` 在启用定时任务之前，请配置 dispatch token，例如 `CODEX_TRIGGER_TOKEN`，用必需的 CI 检查保护默认分支 （对本仓库为 `go build ./...`、`go test ./...` 和 `golangci-lint run ./...`）， 并在每个增量中为 `.github/loop/PRIORITIES.md` 填入一个范围明确的问题。设置清单与运行模型请参阅 [`micro loop` 快速开始](internal/website/docs/guides/micro-loop.md)。 ### 通过提示词生成 — 需要 LLM key 设置提供商密钥，描述你的需求，AI 会设计服务、编写 handler、编译并启动它们： ```bash export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY, GEMINI_API_KEY, ... micro run --prompt "a task management system with categories" --provider anthropic ``` AI 设计架构，你进行评审，随后它会生成包含真实业务逻辑的 handler、编译并启动： ``` Services: ● task — Task management with status tracking ● project — Project organization Generate? [Y/n] Micro Services: ● task ● project Agents: ◆ agent ``` 然后在控制台中与你的服务对话： ``` > Create a project called Launch, then add three tasks to it → project_Project_Create({"name":"Launch"}) ← {"record":{"id":"p1..."},"success":true} → task_Task_Create({"title":"Design specs","project_id":"p1..."}) → task_Task_Create({"title":"Write code","project_id":"p1..."}) → task_Task_Create({"title":"Ship it","project_id":"p1..."}) Created project Launch and added three tasks to it. ``` 当你需要尚不存在的能力时，代理会在对话过程中生成一项新服务： ``` > I need to track shipping. Create a shipment for order 123 to London. ⚡ generating shipping service... ✓ shipping → shipping_Shipping_Create({"order_id":"123","destination":"London"}) ← {"record":{"id":"xyz...","status":"pending"}} Created shipment for order 123 going to London. ``` 你可以随时手动编辑生成的代码——重新运行会保留你的修改。[了解更多](https://go-micro.dev/blog/13). ## 为何需要 Agent Harness 第一波代理框架帮助开发者让模型进入循环。下一个问题是如何运营这个循环：将其连接到真实工具、限定可触及范围、保留状态、将工作路由给专家、从故障中恢复、观测发生了什么，并让其他代理调用它。这就是 harness 工作。 Go Micro 的答案是：让 harness 与你已部署的东西合二为一： - **工具即服务** — 端点元数据成为工具 schema；RPC 执行调用。 - **代理即服务** — 它们注册、发现、负载均衡，并暴露 `Agent.Chat`。 - **工作流即持久化代码路径** — 路径已知时使用 flows；未知时分派给代理。 - **安全落在执行层** — `MaxSteps`、`LoopLimit`、`ApproveTool` 以及工具包装器在动作发生处运行。 - **互操作内置** — 工具用 MCP，代理用 A2A，付费工具用 x402。 当代理需要操作系统而不仅是回答提示时，使用 Go Micro。 ## 编写服务 底层而言，服务是带方法的 struct。文档注释和 `@example` 标签会自动成为 AI 代理的工具描述。 ```go package main import ( "context" "go-micro.dev/v6" ) type Request struct { Name string `json:"name"` } type Response struct { Message string `json:"message"` } type Say struct{} // Hello greets a person by name. // @example {"name": "Alice"} func (h *Say) Hello(ctx context.Context, req *Request, rsp *Response) error { rsp.Message = "Hello " + req.Name return nil } func main() { service := micro.NewService("greeter") service.Handle(new(Say)) service.Run() } ``` 运行后一切皆可访问——REST、gRPC、MCP、agent playground： ```bash micro run # Dashboard: http://localhost:8080 # API: http://localhost:8080/api/{service}/{method} # Agent: http://localhost:8080/agent # MCP Tools: http://localhost:8080/mcp/tools ``` 你也可以从模板脚手架生成服务： ```bash micro new helloworld micro new contacts --template crud ``` ## 构建代理 代理是内置 LLM 的服务。它拥有 proto 定义的 `Agent.Chat` RPC 端点，在 registry 中注册，并可像任何服务一样被调用： ```go agent := micro.NewAgent("task-mgr", micro.AgentServices("task", "project"), micro.AgentPrompt("You manage tasks and projects. You understand deadlines and priorities."), micro.AgentProvider("anthropic"), ) agent.Run() ``` 代理从 registry 发现其服务，将工具限定到对应端点，并在 store 中维护对话记忆。它会自我注册，以便 `micro chat` 及其他代理能找到它。 ```go // Programmatic interaction resp, _ := agent.Ask(ctx, "What tasks are overdue?") fmt.Println(resp.Reply) ``` 多个代理通过 RPC 协调——每个都是带有 `Agent.Chat` 端点的服务。`micro chat` 会路由到正确的那一个。 ```bash micro agent list # list registered agents micro call task-mgr Agent.Chat '{"message": "What tasks are overdue?"}' ``` ### 规划与委托（Plan & Delegate） 每个代理都具备两种内置 harness 能力，以工具形式暴露——无需额外设置或独立的图运行时： - **`plan`** — 对于多步骤工作，代理在其 store 支撑的记忆中记录有序计划，并在多轮对话中保持方向。 - **`delegate`** — 代理将自包含的子任务交给另一个代理。若已注册的代理已拥有相关服务，则通过 RPC 交接给该代理；否则会为该子任务创建一个专注、短命的子代理，并配备独立隔离的上下文。 这让智能保持分布式：代理不必知道*如何*完成一切，只需知道*谁*来做。参见 [examples/agent-plan-delegate](examples/agent-plan-delegate/)。 ```go // A sub-agent is just an agent — created with New, talked to with Ask. // delegate-first: reuse a registered agent, or spin up a focused one. resp, _ := agent.Ask(ctx, "Plan the launch, create the tasks, and have comms notify the owner.") ``` ### 开箱即用，可插拔 正如服务组合可插拔抽象（registry、broker、store），代理组合 **model**、**memory** 和 **tools**——开箱即用的合理默认，每一项都可替换。 ```go agent := micro.NewAgent("assistant", micro.AgentProvider("anthropic"), // model — swap the provider micro.AgentCompactMemory(40, 12), // memory — durable, summarized, recallable micro.AgentTool("weather", "Get the weather for a city", map[string]any{"city": map[string]any{"type": "string"}}, func(ctx context.Context, in map[string]any) (string, error) { return getWeather(in["city"].(string)) // tools beyond your services — any function }), micro.AgentMaxSteps(8), // guardrails ) ``` **Memory（记忆）** 默认持久且由 store 支撑（Postgres、NATS KV 或 file），因此代理在重启后可从上次停下的地方继续——也可用 `AgentMemory` 提供你自己的实现。长期运行的代理可选用 `AgentCompactMemory(maxMessages, keepRecent)`：较早轮次被折叠为确定性摘要，最近轮次保持原文，相关归档轮次在未来请求时被召回，而无需重放整段对话。**Tools（工具）** 自动就是你的服务，加上你用 `AgentTool` 注册的任何函数。 ### 付费工具（x402） 每个端点都是 AI 可调用的工具——而且可以是*付费*工具。Go Micro 支持 [x402](https://x402.org), 面向代理的 HTTP 402 支付标准，因此工具可要求稳定币支付，代理可自主结算。这是可选功能，框架本身不携带加密货币逻辑：验证委托给可插拔的 facilitator（Coinbase、Alchemy、自托管），因此 Base 和 Solana 只是不同的 facilitator。 ```bash # Charge for tool calls at the MCP gateway (off unless you set a pay-to address) micro mcp serve --x402_pay_to 0xYourAddress --x402_network solana --x402_amount 10000 # Per-tool amounts via a config file micro mcp serve --x402_config x402.json ``` 参见 [Payments (x402) guide](internal/website/docs/guides/x402-payments.md)。 ### 可被其他代理访问（A2A） 在 Go Micro 系统内，代理通过 RPC 相互访问。要让*其他*框架上的代理也能访问它们，Go Micro 使用 [Agent2Agent (A2A) protocol](https://a2a-protocol.org). A2A 网关从 registry 发现你的代理，根据其元数据为每个代理生成 Agent Card——与 MCP 网关从服务端点派生工具的方式相同——并将传入的 A2A 任务翻译为代理的 `Agent.Chat` RPC。无需为每个代理编写代码：注册代理即可通过 A2A 访问。 ```bash micro a2a serve --address :4000 # gateway: expose every registered agent over A2A micro a2a list # agents and their Agent Card URLs ``` 或者完全跳过网关——代理可直接提供自己的 A2A 端点，在进程内处理任务： ```go micro.NewAgent("task-mgr", micro.AgentServices("task"), micro.AgentA2A(":4000")) ``` 双向皆可。要调用其他框架上的代理，`a2a.Client` 会接入两处交接工作的地方：作为工作流步骤的 `flow.A2A(url)`（跨框架的 `Dispatch`），以及从代理内部向 `http(s)` URL 发起的 `delegate`。 MCP 将你的服务暴露为工具；A2A 将你的代理暴露为代理。参见 [A2A guide](internal/website/docs/guides/a2a-protocol.md)。 ## 功能特性 ### AI | 功能 | 详情 | |---------|---------| | Agents（智能体） | `micro.NewAgent()` — 管理服务的智能层 | | Plan & delegate（规划与委派） | 内置 agent 工具 — 规划多步骤工作，将子任务委派给其他 agent | | Pluggable memory（可插拔记忆） | 默认基于持久化存储的对话记忆；可通过 `AgentMemory` 替换 | | Custom tools（自定义工具） | `AgentTool` — 为 agent 提供除服务之外的任意函数作为工具 | | Guardrails（护栏） | `MaxSteps`（按次数停止）、`LoopLimit`（停止重复的无进展调用）、`ApproveTool`（human-in-the-loop，人在回路） | | Tool middleware（工具中间件） | `AgentWrapTool` — 包装工具执行以实现日志、指标或重试（类似 client/server wrappers） | | Workflows（工作流） | `micro.NewFlow()` — 事件驱动；单步、有序持久化步骤，或触发 agent | | Durable execution（持久化执行） | 带检查点的流程步骤可在崩溃后存活并从停止处恢复；默认基于存储，后端可插拔 | | MCP gateway | 每个 endpoint 自动成为 AI 工具 | | A2A gateway | 每个 agent 均可通过 Agent2Agent 协议访问；卡片由 registry（`micro a2a`）生成 | | Payments (x402) | 通过 x402 标准按调用选择性为工具付费；facilitator 可插拔（Base、Solana 等） | | 9 个 LLM 提供商 | Anthropic、OpenAI、Gemini、Groq、Mistral、Together、Atlas Cloud、MiniMax、Ollama（本地 + 云端） | | Interactive console（交互式控制台） | `micro run` 包含与服务对话的聊天控制台 | | Service generation（服务生成） | `micro run --prompt` — 描述系统即可获得运行中的服务 | ### 框架 | 功能 | 详情 | |---------|---------| | Service registry（服务注册） | mDNS（默认）、Consul、etcd | | RPC client/server | gRPC 传输、负载均衡、流式传输 | | Pub/sub events（发布/订阅事件） | NATS、RabbitMQ、HTTP broker | | Key-value store（键值存储） | File (bbolt)、Postgres、NATS KV | | Typed model layer（类型化模型层） | CRUD + 查询，SQLite/Postgres 后端 | | Everything swappable（一切皆可替换） | 所有抽象均为 Go interface | ### 开发者体验与部署 | 功能 | 详情 | |---------|---------| | Hot reload（热重载） | `micro run` 监听文件变更并重新构建 | | Templates（模板） | `micro new --template crud/pubsub/api` | | One-command deploy（一键部署） | `micro deploy user@server` — SSH + systemd，无需 Docker | ## CLI | 命令 | 用途 | |---------|---------| | `micro run --prompt "..."` | 生成服务与 agent，并启动交互式控制台 | | `micro run` | 开发模式：热重载、gateway、交互式控制台 | | `micro run -d` | 分离模式（无控制台） | | `micro chat` | 独立聊天（未使用 micro run 时） | | `micro agent list` | 列出已注册的 agent | | `micro new myservice` | 脚手架生成服务 | | `micro call service endpoint '{}'` | 从 CLI 调用服务或 agent | | `micro build` | 编译生产二进制文件 | | `micro deploy user@server` | 通过 SSH + systemd 部署 | ## 多服务项目 同时运行多个服务： ```go users := micro.NewService("users", micro.Address(":9001")) orders := micro.NewService("orders", micro.Address(":9002")) users.Handle(new(Users)) orders.Handle(new(Orders)) g := micro.NewGroup(users, orders) g.Run() ``` 或使用 `micro.mu` 配置文件： ``` service users path ./users service orders path ./orders depends users ``` ## 数据模型 类型化持久化，支持 CRUD 与查询： ```go type User struct { ID string `json:"id" model:"key"` Name string `json:"name"` Email string `json:"email" model:"index"` } db := service.Model() db.Register(&User{}) db.Create(ctx, &User{ID: "1", Name: "Alice", Email: "alice@example.com"}) var results []*User db.List(ctx, &results, model.Where("email", "alice@example.com")) ``` 后端：memory（默认）、SQLite、Postgres。 ## AI 提供商 单次 import 即可切换提供商 — 各处使用相同 interface： | 提供商 | 默认模型 | |----------|---------------| | Anthropic | `claude-sonnet-4-20250514` | | OpenAI | `gpt-4o` | | Google Gemini | `gemini-2.5-flash` | | Groq | `llama-3.3-70b-versatile` | | Mistral | `mistral-large-latest` | | Together AI | `meta-llama/Llama-3.3-70B-Instruct-Turbo` | | Atlas Cloud | `deepseek-ai/DeepSeek-V3-0324` | | MiniMax | `MiniMax-M3` | | Ollama | `llama3.2` (local) | ```go m := ai.New("anthropic", ai.WithAPIKey(key)) resp, _ := m.Generate(ctx, &ai.Request{Prompt: "hello"}) ``` ## 示例 初次接触 agent？请跟随 [first-agent on-ramp](#first-agent-on-ramp)，然后使用 [examples index](examples/README.md) 查看完整的 services → agents → workflows 映射。 - [hello-world](examples/hello-world/) — 基础 RPC 服务 - [multi-service](examples/multi-service/) — 单个二进制文件中运行多个服务 - [mcp](examples/mcp/) — 与 AI agent 的 MCP 集成 - [first-agent](examples/first-agent/) — 最小化、无需 provider 的服务支撑型 agent - [agent-plan-delegate](examples/agent-plan-delegate/) — Agent 规划与多 agent 委派 - [agent-durable](examples/agent-durable/) — 检查点与恢复 agent 运行，无需重放已完成的工具副作用 - [grpc-interop](examples/grpc-interop/) — 从任意 gRPC 客户端调用 go-micro 查看 [all examples](examples/README.md)。 ## 文档 - [入门指南](internal/website/docs/getting-started.md) - [AI 集成](internal/website/docs/ai-integration.md) - [你的第一个 Agent](internal/website/docs/guides/your-first-agent.md) - [0→hero 参考](internal/website/docs/guides/zero-to-hero.md) - [Agent 与工作流](internal/website/docs/guides/agents-and-workflows.md) - [Agent 设计](internal/docs/AGENT_DESIGN.md) - [规划与委派](internal/website/docs/guides/plan-delegate.md) - [Agent 护栏](internal/website/docs/guides/agent-guardrails.md) - [支付（x402）](internal/website/docs/guides/x402-payments.md) - [MCP 与 AI Agent](internal/website/docs/mcp.md) - [数据模型](internal/website/docs/model.md) - [部署](internal/website/docs/deployment.md) - [插件](internal/website/docs/plugins.md) 包参考：https://pkg.go.dev/go-micro.dev/v6