micro--go-micro/README.md

<!-- WEHUB_ZH_README -->
> [!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 [![Go.Dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/go-micro.dev/v6?tab=doc) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white&style=flat-square)](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 共享同一运行时，因为智能体本质上是一个分布式系统，构建智能体就是在构建服务。

## 赞助商

<a href="https://go-micro.dev/blog/3"><img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" height="26" /></a>
&nbsp;&nbsp;
<a href="https://go-micro.dev/blog/29"><img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" height="26" /></a>
&nbsp;&nbsp;
<a href="https://go-micro.dev/blog/8"><img src="https://www.atlascloud.ai/logo.svg" height="26" /></a>

**想支持 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 <name>` 恢复运行历史、记忆
   以及提供商检查，以应对首次对话出现意外行为的情况。
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