企业官网建设流程全解析

go-micro 官方示例指南：从服务、Agent 到工作流的完整生命周期路线图

【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro

本指南基于 examples/README.md 及其配套索引 examples/INDEX.md，系统梳理 go-micro（Go Agent harness and service framework）示例集的完整路线图。你将掌握"服务 → Agent → 工作流 → MCP 集成"的推荐学习路径、每个示例的定位与运行方式，以及如何从零开始贡献一个新的可运行示例。

示例集概览：一条贯穿服务生命周期的学习路线

examples/目录是 go-micro 的可运行示例集合，其设计目标是用真实可执行的代码带开发者走完整个 go-micro 生命周期：

1. 先写一个服务（Service）——掌握运行时基础；
2. 把服务暴露成 Agent 可用的能力（tool）——让 AI Agent 通过工具调用使用服务；
3. 用工作流（Workflow）协调更长周期的任务——把多个步骤组织成可检查点、可恢复的流程。

每个示例都可用go run .在其目录下直接运行（除非对应 README 另有说明）。示例的编排逻辑与配套文档（如 examples/INDEX.md）以及 CLI 输出保持同步，保证新开发者能沿着一条被持续验证的路径进入项目。

快速上手：两种推荐的进入方式

对于刚接触仓库的开发者，不建议按字母顺序通读目录，而应选择以下两种方式之一：

• 方式一（推荐）：先阅读 examples/INDEX.md（wayfinding 索引），它按"目标"组织，直接给出最短路径；
• 方式二：跟随下面这张"首个 Agent 推荐路径"表，它是仓库维护者认定的 canonical 路线。

此外，最短的 AI 工具桥接路径（MCP 方向）为：mcp/hello→mcp/crud→mcp/workflow；调试与生产加固则就近参考agent-wrap-tool、agent-durable和deployment。

所有命令默认都不需要 provider key（无需模型厂商 API Key），除非对应示例 README 另有说明。

生命周期第 1 阶段：Services——学习运行时基础

hello-world：0→1 的 RPC 服务最小示例

hello-world 是入门第一站，演示了 go-micro 服务的四个核心概念：

• 服务创建与注册（micro.NewService("greeter", micro.Address(":8080"))）；
• Handler 实现（Hello方法）；
• 客户端调用；
• 健康检查。

其核心代码非常精简（见 examples/hello-world/main.go）：定义Request/Response类型与Greeterhandler，main中依次完成服务创建、service.Init()、service.Handle(new(Greeter))注册、service.Run()启动。运行后即可用 curl 直接验证 RPC 端点：

cd hello-world go run . # 另一终端验证 curl -XPOST \ -H 'Content-Type: application/json' \ -H 'Micro-Endpoint: Greeter.Hello' \ -d '{"name": "Alice"}' \ http://localhost:8080

web-service：带服务发现的 HTTP Web 服务

web-service 在 hello-world 的基础上增加了 HTTP 层：

• HTTP handlers；
• 服务注册；
• 健康检查；
• JSON REST API。

cd web-service go run .

multi-service：模块化单体模式

multi-service 演示如何在单个二进制内运行多个服务。从源码看（examples/multi-service/main.go），关键设计是：

• 每个服务拥有独立隔离的 server、client、store 和 cache；
• 多个服务共享registry、broker 和 transport，因此能在同一进程内互相发现与调用；
• 通过micro.NewGroup(users, orders)协调生命周期——由service.Group统一处理信号，一个服务退出时停止全部服务。

cd multi-service go run .

这种"先单体后拆分"的模式适合在需要独立扩容前保持部署简单。

deployment：Docker Compose 生产化部署

deployment 提供一个接近生产的架构，一条命令即可拉起：

docker-compose up

其架构包含 MCP 网关（:3001）、Consul 注册中心（:8500）、Jaeger 分布式追踪（:16686）与业务服务（:9090），Agent（如 Claude）通过 MCP 协议发现并调用服务。对应端点与验证方式：

# 列出 MCP 工具 curl http://localhost:3001/mcp/tools | jq # 调用工具 curl -X POST http://localhost:3001/mcp/call \ -H 'Content-Type: application/json' \ -d '{"tool": "myservice.Handler.Method", "arguments": {"key": "value"}}'

自定义时，将app服务的 build context 替换为你的服务目录，新增服务只需配置MICRO_REGISTRY: consul与MICRO_REGISTRY_ADDRESS: consul:8500环境变量，即可被 MCP 网关自动发现；如需 Redis 缓存，追加redis:7-alpine服务并设置MICRO_CACHE_ADDRESS=redis:6379即可。生产化建议包括为每个服务加健康检查、Consul 数据用命名卷持久化、网关配置限流、服务间启用 TLS 以及用 secrets 管理 API Key。

生命周期第 2 阶段：Agents——把服务变成会使用工具的队友

first-agent：无密钥运行的最小服务型 Agent

first-agent 是仓库内最小的可运行服务型 Agent，位于micro new helloworld与完整 0-to-hero 参考support之间。它使用确定性 mock 模型，因此不需要ANTHROPIC_API_KEY、OPENAI_API_KEY或任何 provider secret：

go run ./examples/first-agent

预期输出：

First agent (provider: mock, no API key) > Summarize my next steps [notes] listed starter notes assistant: Your first agent read the notes service and found three steps: install the CLI, run a service, then chat with an agent. ✓ service-backed agent completed without provider secrets

从源码（examples/first-agent/main.go）可以看到完整的服务→Agent 链路是如何被装配起来的：

• notes是一个普通 go-micro 服务，只有一个 RPC 方法List；
• assistant通过agent.Services("notes")把作用域限定到该服务；
• mock 模型通过正常的 agent tool handler 请求服务工具（m.opts.ToolHandler）；
• 一次assistant.Ask即完成"模型请求工具 → 服务执行 → 返回最终答复"的闭环。

这段链路可归纳为：服务暴露工具 → Agent 发现服务 → 模型请求调用工具 → Agent 返回最终答案。CI 用go test ./examples/first-agent持续保证该路径可运行。

脱离这个最小转录、进入长驻 Agent 后，可用以下 CLI 命令继续调试（详见 first-agent/README.md）：

micro run micro chat assistant --prompt "Summarize my next steps" micro inspect agent assistant micro agent doctor assistant

agent-demo：多服务项目管理应用 + MCP 集成

agent-demo 是一个单进程内注册三个服务的项目管理系统：ProjectService（Create/Get/List）、TaskService（Create/List/Update）、TeamService（Add/List/Get），自带种子数据（2 个项目、7 个任务、4 名团队成员），并集成了 agent playground。

go run main.go

运行后暴露的端点：MCP Gateway 位于http://localhost:3000，MCP Tools 位于http://localhost:3000/mcp/tools，WebSocket 位于ws://localhost:3000/mcp/ws。它演示了五件事：

1. 零配置 MCP——服务从 doc comments 自动变成 AI 工具；
2. 跨服务编排——Agent 在一次对话中同时查询项目、任务和团队；
3. 富工具描述——description结构体 tag 与@example注释引导 Agent；
4. 鉴权作用域——读、写操作拥有独立 scope；
5. WithMCP一行式——一个选项即可启动 MCP 网关。

与 Claude Code 集成时，只需在其 MCP 配置中声明：

{ "mcpServers": { "demo": { "command": "go", "args": ["run", "main.go"], "cwd": "examples/agent-demo" } } }

agent-plan-delegate：两大内置 Agent 能力

agent-plan-delegate 在一个小型多 Agent 系统中演示 go-micro 的两个内置能力——规划（plan）与委派（delegate）：

两者的关键设计是：plan和delegate自动附加到每个 Agent 上，无需配置 harness 或 graph——它们就是模型可以调用的普通工具，与任何服务端点无异。

运行需要 provider key（示例会自动检测 provider）：

export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY, GEMINI_API_KEY, ... go run main.go

也可用MICRO_AI_PROVIDER/MICRO_AI_API_KEY强制指定。delegate是混合式的：若to指向拥有相关服务的已注册 Agent，则通过 RPC（Agent.Chat）发送子任务；否则创建一个聚焦的临时子 Agent（fresh 隔离上下文，完成任务后销毁，且无内置工具、无法再次委派）。

agent-wrap-tool：Agent 工具执行中间件

agent-wrap-tool 是client.CallWrapper/server.HandlerWrapper的工具侧对应物——围绕 Agent 工具执行的中间件。Agent 的每次工具调用都会流经ai.ToolHandler：

type ToolHandler func(ctx context.Context, call ai.ToolCall) ai.ToolResult type ToolWrapper func(ai.ToolHandler) ai.ToolHandler

WrapTool（对外暴露为micro.AgentWrapTool）注册一个包装器：它接收下一个 handler 并返回新 handler，next(...)之前的代码在工具执行前运行、之后的代码在执行后运行，这一个接缝即可覆盖完整生命周期——before/after 钩子、计时、指标、重试、结果检查。

示例包含一个易抖动的weather服务和一个带两个包装器的 Agent：

• observe——为每次调用计时并记录 per-tool 计数，携带 provider 传下来的关联 ID（call.ID）；只观察、不改变行为；
• retry——当调用结果出错时重试，最多 3 次；weather 服务首次必失败、随后成功，于是重试把一次瞬时故障变成模型永远看不到的成功。

包装器按最外层优先组合：observe先注册，因此它包裹retry，即使 retry 实际执行了两次工具，observe 也只看到一次逻辑调用。

micro.NewAgent("forecaster", micro.AgentServices("weather"), micro.AgentProvider(provider), micro.AgentAPIKey(apiKey), micro.AgentWrapTool(m.observe, retry(3)), )

与 guardrails 的关系：开发者包装器运行在内置 guardrails（MaxSteps、LoopLimit、ApproveTool）之外，能看到每次调用及其结果（包括 guardrail 的拒绝）；但 retry 包装器的next是完整的 guardrail 栈，因此每次重试也会被循环检测计数。建议让LoopLimit≥ 重试次数，或当包装器自己负责重复时设置AgentLoopLimit(0)。

agent-durable：可检查点、可恢复的 Agent 运行

agent-durable 是flow-durable的 Agent 侧对应物：Agent 运行使用与 flow 相同的Checkpoint接口进行检查点保存，中断后可恢复且不重复已完成副作用：

go run ./examples/agent-durable

示例中 mock 模型调用inventory.reserve后模拟进程崩溃。micro.AgentPending找到未完成运行，micro.AgentResume从保存的检查点继续；关键验证行是最后的tool executions: 1——恢复期间reserve工具没有被二次调用。

何时用 durable flow 而非可检查点 Agent：流程已知时（有序服务调用、重试、定时器、补偿、精确恢复阶段如reserve/charge）用 durable flow；路径开放、由模型动态选择工具时用可检查点 Agent 运行。二者可组合：确定性业务过程留在flow-durable，判断密集步骤交给可检查点 Agent，两者共用同一Checkpoint后端，检查与恢复可共享同一个运行历史存储。在服务启动时同样可用此模式恢复：

pending, _ := micro.AgentPending(ctx, agent) for _, run := range pending { _, _ = micro.AgentResume(ctx, agent, run.ID) }

注意：context.Context的取消与 deadline 在检查点加载/保存、模型调用、工具调用中依然生效；状态为done、canceled、expired的终结运行不会被AgentPending返回。在检查点保存前已成功的副作用仍可能重复（详见持久化契约文档）。

agent-human-input 与 agent-ollama

• agent-human-input：人机协同（human-in-the-loop）示例，用于需要在运行继续前得到明确人工决策的场景。
• agent-ollama：本地模型接线示例，适合用 Ollama 承载模型调用的开发者实验。

生命周期第 3 阶段：Workflows——协调更长周期的任务

support：0-to-hero 维护中的参考路径

examples/support 是 go-micro 生命周期的维护中 0-to-hero 参考：一个可运行文件 + 一个 CI 冒烟测试，保证参考路径随框架演进始终诚实可用。其路径为：

1. Scaffold 服务——customers、tickets、notify是普通类型化 go-micro 服务，其请求/响应结构体与方法注释成为 Agent 看到的工具契约；
2. 运行 harness——进程内启动内存版 registry、broker、client、store、服务、Agent 和 flow，默认运行无需外部依赖或 API Key；
3. 通过 Agent 聊天——supportAgent 把工单事件作为 prompt 接收，调用服务工具查询客户、分流工单、起草回复；
4. 检查工作流——intakeflow 记录事件驱动运行并打印 Agent 结果，展示 service → agent → workflow 在一个运行时内的完整生命周期。

场景：客户提交工单，ticket.created事件触发 support Agent：(1) 查询客户（customers）；(2) 设置工单优先级（tickets）；(3) 起草并发送邮件回复（notify）——但必须通过审批门：

> event: events.ticket.created {"customer":"alice@acme.com","id":"ticket-1","subject":"Can't log in"} [customers] looked up Alice (pro plan) [tickets] ticket-1 → priority=high status=in_progress ▣ approval gate notify_NotifyService_Send(alice@acme.com) — approved [notify] 📨 to=alice@acme.com: "Hi Alice — thanks for reaching out. We've bumped this to high priority and are on it." support agent: Triaged ticket-1 for Alice and sent a reply. inspect transcript: micro inspect flow intake flow: intake runs=1 latest.reply="Triaged ticket-1 for Alice and sent a reply." micro agent history support agent: support runs=1 latest.status=completed ✓ ticket triaged and the customer was replied to — triggered by an event

四大组成：

• 服务（customers/tickets/notify）——普通 go-micro 服务，Agent 自动将其端点发现为工具；
• Agent（support）——micro.NewAgent关联这三个服务，推理工单并调用工具；
• Flow（intake）——由events.ticket.created触发并把事件交给 Agent：事件即 prompt，无需人工输入；
• Guardrail（ApproveTool）——Agent 可自由读取与分流，但给客户发邮件（notify.Send）必须经过门控；返回false则挂起等待人工或策略，示例中选择批准并记录。

运行与验证（mock 模型确定性执行，无需 API Key）：

go run main.go # mock 模型 — 确定性，无 API Key go test ./examples/support

连接真实模型时，Agent 将自行推理工单而非跟随脚本：

export ANTHROPIC_API_KEY=sk-ant-... # 或 OPENAI_API_KEY, GEMINI_API_KEY, ... go run main.go -provider anthropic

后续演化方向：让ApproveTool对计费动作返回false或转人工；用agent.WithA2A(":4000")将 Agent 暴露给其他团队的 Agent；新增kb（知识库）服务让 Agent 回复前先检索。

flow-durable：崩溃后从断点恢复的工作流

flow-durable 演示"flow 是有序步骤列表（带阶段的任务）"而非单次 LLM 轮次。每一步通过可插拔的Checkpoint（默认 store 支持）在前后持久化，进程中途死亡后从停止的步骤恢复，不重跑已成功检查点的步骤。

核心代码（examples/flow-durable）：

f := micro.NewFlow("checkout", micro.FlowSteps( micro.FlowStep{Name: "reserve", Run: reserve}, micro.FlowStep{Name: "charge", Run: charge}, micro.FlowStep{Name: "confirm", Run: confirm}, ), micro.FlowWithCheckpoint(micro.StoreCheckpoint(nil, "checkout")), // nil store = 默认；"checkout" = key scope ) f.Execute(ctx, `{}`) // 运行；在 charge 处崩溃 pending, _ := f.Pending(ctx) // 运行被检查点在 "charge" f.Resume(ctx, pending[0].ID) // 从 charge 继续到结束

State携带类型化 payload（Set/Scan）与Stage标记（恢复点）；Checkpoint持久化每次Run，内置实现以 store 为后端，通过store.Scope把每个 flow 的运行放进独立 store 表（数据库flow、表checkout），不同 flow 之间、以及 flow 与 agent/service 状态之间互不共享表。真实的步骤可以是flow.Call(service, endpoint)（RPC）、flow.Dispatch(agent)（交给 Agent）或flow.LLM(prompt)（一次模型轮次）；此处用普通函数仅为单独展示持久化。

go run main.go

无需 LLM Key。注意：Checkpoint本身不提供外部引擎适配器或 exactly-once 执行；默认文件 store 在文件保留的前提下可跨进程重启存活。

flow-loop：循环工作流

flow-loop 用于重复工作流步骤的循环型 flow 示例，适合需要反复执行固定步骤的场景。

第 4 阶段：MCP 与 Agent 集成示例

MCP（Model Context Protocol）示例目录 examples/mcp/ 提供五个递进式示例：

MCP 接入只需三步（examples/mcp/README.md）：

1. 为 handler 方法写 Go doc 注释（自动抽取为工具描述）：

// SayHello greets a person by name. Returns a friendly greeting message. // // @example {"name": "Alice"} func (g *Greeter) SayHello(ctx context.Context, req *HelloRequest, rsp *HelloResponse) error { rsp.Message = "Hello " + req.Name + "!" return nil } type HelloRequest struct { Name string `json:"name" description:"Person's name to greet"` }

2. 注册 handler（自动抽取文档）：

handler := service.Server().NewHandler(new(Greeter)) service.Server().Handle(handler)

3. 启动 MCP 网关：

go mcp.ListenAndServe(":3000", mcp.Options{ Registry: service.Options().Registry, })

特性包括：自动文档抽取（Go doc 注释→工具描述、@exampletag→示例输入、struct tag→参数描述）、多传输（Stdio 用于 Claude Code、HTTP/SSE 用于 Web 端 Agent）、零配置（无需手动注册工具、无需 API wrapper、无需代码生成）、per-tool 鉴权 scope，以及网关层的限流与审计日志：

mcp.Serve(mcp.Options{ Registry: reg, Auth: authProvider, RateLimit: &mcp.RateLimitConfig{ RequestsPerSecond: 10, Burst: 20, }, AuditFunc: func(r mcp.AuditRecord) { log.Printf("[audit] trace=%s tool=%s account=%s allowed=%v", r.TraceID, r.Tool, r.AccountID, r.Allowed) }, })

MCP 命令行同样完整（micro mcp serve启动 Stdio/HTTP 服务、micro mcp list列出工具、micro mcp test <tool> '{"k":"v"}'测试工具、micro mcp docs生成文档、micro mcp export langchain|openapi|json导出不同格式）。网关侧实现细节可继续阅读 gateway/mcp/。

其他示例

• auth：认证与授权示例（含 client、server 与 proto 定义）。

• graceful-stop：长驻服务的优雅停机行为。

• grpc：go-micro v6 作为标准 gRPC 兼容服务器（开启反射），可用 grpcurl 或任意标准 gRPC 客户端调用：

  grpcurl -plaintext localhost:8080 list grpcurl -plaintext -d '{"name":"World"}' localhost:8080 helloworld.Say.Hello

• grpc-interop：gRPC 互操作性示例（client/server 双端）。

外部依赖与前置条件

部分示例需要外部基础设施，按需用 Docker 启动：

# NATS（事件/消息） docker run -p 4222:4222 nats:latest # Consul（服务注册） docker run -p 8500:8500 consul:latest agent -dev -ui -client=0.0.0.0 # Redis（缓存） docker run -p 6379:6379 redis:latest

例如broker/nats、registry/consul相关的示例均依赖上述服务；而first-agent、support等示例使用内存版 registry/broker/store，无需任何外部依赖。

即将推出

• pubsub-events——基于 NATS 的事件驱动架构示例。

贡献新示例的规范

若你希望向示例集贡献新示例，examples/README.md 给出了明确流程：

1. 创建新目录；
2. 添加带说明的 README.md；
3. 包含带注释的可运行代码；
4. 按其支持的生命周期阶段加入 examples/README.md 索引（或 examples/INDEX.md 的目标表格）；
5. 确保能通过go run .运行。

保持 README、示例索引与micro examplesCLI 输出三者同步，是新开发者能从一个文档化入口找到examples/first-agent与examples/support的前提。CLI 侧同样打印这条路径：

micro examples micro agent demo micro zero-to-hero

小结

go-micro 的示例集按"服务 → Agent → 工作流"的生命周期精心编排：hello-world教你写第一个 RPC 服务，first-agent用无密钥的 mock 模型打通服务到 Agent 的闭环，support把类型化服务、Agent 聊天循环、事件驱动 flow 与审批门整合成一个维护中的 0-to-hero 参考，flow-durable与agent-durable则提供可检查点、可恢复的长周期执行能力。无论你是想跑通第一个 Agent、把既有微服务暴露给 AI 客户端，还是构建带审批门控的持久化工作流，都可以从这张路线图出发，逐级深入对应源码与测试。

【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro