企业官网建设流程全解析

• 后端
• 微服务
• AI Agent
• RPC框架

导读

本篇文章以 Go Micro 仓库中的 0→hero CI harness 为核心，剖析其如何在不依赖任何外部服务与模型 API Key 的前提下，用一条脚本 + 一组确定性测试，把「服务脚手架 → 首个 Agent → 运行/聊天 → 检查/调试 → 部署边界」这条完整的新手进阶路径固化成一个可被 CI 在每次推送时验证的契约。读完本文，你将理解make harness、make zero-to-hero-transcript、make inner-loop等本地入口的执行链条，掌握run.sh七个步骤对应的测试边界，以及micro deploy --dry-run的部署检查原理，并能在自己的项目里复刻这套"无密钥、可离线、防漂移"的验收思路。

一、0→hero CI harness 是什么：无密钥的参考场景

internal/harness/zero-to-hero-ci/目录在仓库中承担一个独特职责：拥有（owns）Go Micro 的 "services → agents → workflows 生命周期" 无密钥参考场景。所谓"拥有"，意味着该目录不是一次性的临时脚本，而是：

• 被刻意保持小巧且脚本化，让 CI 可以在每次 push 时运行，不需要外部服务、不需要模型密钥；
• 是文档契约的裁判，所有面向新手的文档（README、CLI 输出、网站指南）声称能跑的命令，都由它逐一验证。

目录内只有三个文件，结构非常精简：

关键设计决策是：确定性（deterministic）场景使用真实的 Go Micro 运行时，只 mock LLM 提供方（见 run.sh 中first-agent app与flow history步骤的注释）。也就是说，Agent、Workflow、store 支持的 run history、plan/delegate、A2A 全部以真实代码路径启动，仅将模型响应替换为固定输出，从而在无密钥环境下依然能覆盖框架的核心行为。

二、run.sh：一条脚本串起六段契约

run.sh 以set -euo pipefail严格模式开头，先切换到仓库根目录，再通过一个run_step辅助函数打印可读的分步标签后执行命令：

run_step() { local name=$1 shift printf '\n==> %s\n' "$name" printf '+ %q' "$@" printf '\n' "$@" }

脚本注释说明了标签的命名哲学：步骤名镜像文档化的 install → scaffold → run/chat → inspect → deploy-dry-run 接缝，一旦失败，报错信息能直接定位到上手契约中被破坏的环节。

脚本整体执行 7 个run_step，对应关系如下：

2.1 六大契约边界的含义

README 将脚本要守护的完整 first-agent 0→hero 契约归纳为六点，与上述步骤一一对应：

1. Scaffold（脚手架）——维护中的micro new0→1 契约仍能从干净工作区创建可运行服务；
2. First agent（首个 Agent）——micro agent demo、micro examples、micro agent preflight、micro run、micro chat、micro inspect agent <name>仍是文档化的首 Agent 走查路径；
3. Run（运行）——micro run仍是本地开发入口；
4. Chat（聊天）——micro chat仍是交互式 Agent 入口；
5. Inspect/debugging（检查/调试）——micro inspect agent <name>、micro agent history <name>、micro inspect flow <name>保持可用；无密钥调试冒烟会预置（seed）持久化的 Agent run history 与记忆，然后在不带 provider 凭据的情况下运行文档化的 inspect/history 命令；micro flow runs则守护持久化工作流历史检查能力；
6. Deploy（部署）——micro deploy --dry-run <target>作为部署边界检查点保持可用。

三、deploy --dry-run：不触碰远端基础设施的部署边界

第六条契约是 0→hero 路径中唯一的"部署"环节，其实现细节值得单独展开。cmd/micro/cli/deploy/deploy.go 中，Deploy函数先解析 target（命令行参数或--ssh标志），再从micro.mu配置加载命名部署目标：

• 若未指定 target 但配置中存在命名目标，打印可用目标列表（showDeployTargets）；
• 若指定了 target，通过resolveDeployTarget解析出 SSH 地址与远端路径（未配置时默认/opt/micro，见defaultRemotePath常量）；
• 当--dry-run标志为真时，直接调用printDeployPlan返回，绝不进入deploySSH（见 deploy.go#L45-L50）。

printDeployPlan输出的计划包含四步：构建 linux/amd64 服务二进制、复制二进制到远端bin/目录、启用并重启micro@<service>systemd 单元、检查服务健康。最关键的是结尾明确声明：

No SSH, rsync, systemd, or remote deployment was performed.

即 dry-run不构建二进制、不打开 SSH 连接、不运行 rsync、不触碰远端基础设施——这是它被选为 CI 契约的根本原因。测试 deploy_test.go#L123-L162 验证了TestDeployDryRunPlansConfiguredTargetWithoutRemoteSideEffects（无远端副作用地规划配置目标）与TestDeployDryRunValidatesRequestedService（校验--service指定的服务名是否存在于配置）两个行为。

而在 docs_test.go 的TestZeroToHeroDeployDryRunCommandSmoke中，测试会真实构建micro二进制，在一个临时工作区写入micro.mu配置：

service api path ./api deploy prod ssh deploy@prod.example.com path /srv/micro

然后以MICRO_CONFIG_FILE环境变量指向该配置，执行micro deploy --dry-run prod，并断言输出包含Target、deploy@prod.example.com、Remote path、/srv/micro、Services、api以及那句"No SSH, rsync..."声明。这同时守护了配置语法、目标解析与输出格式三层契约。

四、本地与 CI 入口点：从单测到全量 harness

README 列出了多层可选的执行入口，粒度从"一个单测"到"全量 harness"逐级递增：

4.1 最细粒度：单个调试冒烟单测

go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentDebuggingSmoke -count=1

这个测试（docs_test.go#L998 起）的运作方式很具代表性：它在一个临时 HOME 下用store.NewFileStore创建一个真实的文件存储，通过seedNoSecretAgentDebuggingState向agent/assistant作用域写入三个RunEvent（run → model → done，含 TraceID 与时间戳），再写入agent.NewMemory记忆（user/assistant两条消息），然后构建micro二进制逐一验证：

测试环境通过microCLIEnv显式清空MICRO_AI_API_KEY、OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY，从机制上保证"无 provider 凭据也能跑"。

4.2 聚焦文档一致性：make docs-wayfinding

make docs-wayfinding

对应 Makefile 中的目标，执行：

go test ./internal/harness/zero-to-hero-ci -run 'TestFirstAgentWayfinding' -count=1 go test ./cmd/micro -run 'TestFirstAgentDocsMatchCLIOutput|TestFirstAgentWalkthroughCLIBoundaries' -count=1

README 明确说明：只要 README 或网站的首 Agent 面包屑、micro agent demo、micro examples、micro zero-to-hero发生变化，开发者就应运行它。该检查无需 provider，一旦文档化的命令名、指南链接或维护的无密钥示例路径与 CLI 输出发生漂移，测试即失败。

4.3 安装冒烟：make install-smoke

make install-smoke

执行./internal/harness/install-smoke/run.sh，只验证已安装 CLI 的首次运行接缝，不需要 provider 密钥或网络。

4.4 聚焦 CLI 内环：make inner-loop

make inner-loop

在 Makefile 中被描述为"专注的、无 provider 的 CLI 内环契约"：脚手架服务、保持 run/chat/inspect 命令可发现、证明 deploy dry-run 到达文档化边界且无远端副作用。适用场景是"担心 README/文档/CLI 漂移，而完整运行时 harness 超出需要"时。它执行四个测试组，包括TestZeroToOne、TestFirstAgentWalkthroughCLIBoundaries、TestZeroToHeroCLIBoundaries、TestZeroToHeroDeployDryRunCommandSmoke、TestNoSecretFirstAgentDebuggingSmoke、TestYourFirstAgentTutorialSmoke。

4.5 全量本地验收：make harness

README 明确说明make harness的目标构成：刻意覆盖首 Agent 文档 wayfinding 守卫、安装脚本冒烟路径、两种 0→1 脚手架变体、0→hero 场景、事件驱动的 agent-flow harness 以及 mock provider conformance，从而让公开的 scaffold → run/chat → inspect → deploy 生命周期在 CI 之外也能完整执行。对应 Makefile：

harness: $(MAKE) cli-wayfinding $(MAKE) inner-loop $(MAKE) zero-to-hero-transcript go run ./internal/harness/agent-flow $(MAKE) provider-conformance-mock

其中make cli-wayfinding守护已安装 CLI 的首 Agent 入口命令（micro agent demo、micro examples、micro zero-to-hero）作为 CI 契约；make zero-to-hero-transcript即直接执行./internal/harness/zero-to-hero-ci/run.sh。

4.6 需要真密钥的分离路径：make provider-conformance

README 特别强调：live provider 检查保持独立，且由配置的 API Key 门控（make provider-conformance或定时/手动 CI job）。这确保了默认 CI 路径永远无密钥可跑，而真实的模型语义验证则交给按需触发的另一条路径。

五、文档一致性守护：docs_test.go 的多层校验

internal/harness/zero-to-hero-ci/docs_test.go 是这套契约防漂移的"裁判所"，其中几个测试设计思路值得借鉴：

• TestZeroToHeroReferenceDocs：断言 0→hero 指南internal/website/content/en/docs/guides/zero-to-hero.md必须包含make harness、make zero-to-hero-transcript、make inner-loop及若干go test命令；同时断言run.sh必须包含全部生命周期命令与可调试边界标签（scaffold:、run/chat/inspect:、deploy dry-run:等）；还要求根 README.md 指向 canonical 0→hero 指南、暴露make zero-to-hero-transcript与make inner-loop，网站导航 navigation.yml 必须暴露0→hero Reference。

• TestZeroToHeroTranscriptTargetStaysOrdered：不仅检查 Makefile 中存在zero-to-hero-transcript:目标并调用run.sh，还用assertOrderedMarkers强制 7 个run_step标签在脚本中保持严格顺序——顺序本身也是契约。

• TestZeroToHeroDeployDryRunCommandSmoke：真实构建 micro 二进制、写micro.mu、执行micro deploy --dry-run prod（见第三节）。

• TestYourFirstAgentTutorialSmoke：从your-first-agent.md指南中提取main.go代码块，放入临时工作区，写go.mod（replace go-micro.dev/v6 => <仓库根>），执行go mod tidy与go test ./...——直接验证文档中的代码在干净环境下可编译可测试。它还要求指南包含micro agent preflight、micro run、micro call task TaskService.Create、micro chat assistant、micro inspect agent assistant等可复制边界。

• TestFirstAgentWayfindingDocs/TestFirstAgentWayfindingCanonicalTrailStaysInSync/TestFirstAgentWayfindingLinkTargetsResolve：对根 README、cmd/micro/README.md、examples/README.md、examples/INDEX.md以及网站多份指南，逐一校验"first-agent on-ramp"段落中的链接存在、顺序正确、目标文件真实可解析，形成 no-secret → first-agent → debugging → 0→hero 的固定指引链。

• TestFirstAgentCLIChatInspectFixture：构建一个内嵌mockModel的 fixture 服务（注册到ai.Register("first-agent-cli-fixture", newMock)），真实启动 notes 服务与assistantAgent（store 落盘到$HOME/micro/store），随后用micro chat --prompt "Summarize my first-agent next steps" assistant触发对话，再micro inspect agent assistant --limit 1验证 run history——全程 API Key 为空。

六、被守护的可运行示例：first-agent 与 support

CI 步骤中直接引用了两个"维护中（maintained）"的示例应用，它们是 0→hero 路径的活体标本：

• examples/first-agent：无 provider 的首个 Agent 示例。其 main_test.go 中的TestRunFirstAgent将程序实际输出与 READMEExpected transcript:代码块逐字符比对，任何输出漂移都直接失败；TestReadmeDocumentsNextBreadcrumbs则要求 README 的下一步面包屑包含micro run、micro chat assistant --prompt "Summarize my next steps"、micro inspect agent assistant、micro agent doctor assistant及对应指南链接。

• examples/support：0→hero 生命周期示例（事件驱动的工单客服场景）。其 main_test.go 中的TestZeroToHeroInspectTranscript断言完整 transcript，例如> event: events.ticket.created {...}、[customers] looked up Alice (pro plan)、审批门approval gate notify_NotifyService_Send(alice@acme.com) — approved，以及结尾的flow: intake runs=1 latest.reply="Triaged ticket-1 for Alice and sent a reply."和agent: support runs=1 latest.status=completed，并同步要求 README 中Expected inspect transcript段落与之匹配。

这两个示例被固定在 CI 路径中，就是为了保证其文档化的 run/chat/inspect 旅程不能与框架漂移——它们是框架行为与文档之间最直接的对照物。

七、设计要点总结与适用前提

回顾整套 0→hero CI harness，可以提炼出四条可复用的设计原则：

1. 无密钥优先：所有默认路径显式清空模型 API Key 环境变量，只 mock LLM，换取 CI 的稳定与可离线运行；
2. 真实运行时：mock 的只是模型，Agent/服务/工作流/store 全部走真实代码路径，验证价值不打折；
3. 命令即契约：文档中的每个命令都变成测试断言（strings.Contains检查 + 真实执行），文档漂移即 CI 失败；
4. 分级入口：从单测（go test ... -run TestNoSecretFirstAgentDebuggingSmoke）到内环（make inner-loop）再到全量（make harness），让开发者按需选择验证深度；live provider 检查独立于默认 CI，按密钥门控。

需要说明的适用前提：以上所有命令均以当前仓库（Go Micro 模块路径go-micro.dev/v6）的实际实现为准；运行make harness等目标需要本地具备 Go 工具链，且默认路径不要求网络与模型密钥。若你的目的是验证真实模型语义或接入外部服务，则应使用独立门控的make provider-conformance路径。

从 "0→1 脚手架" 到 "0→hero 全生命周期"，这套 harness 用最小的脚本体量，把新手文档中每一句"你可以这样跑"都变成了机器可验证的硬性承诺——这正是它被放在internal/harness/zero-to-hero-ci/目录里、并在每次 push 和 PR 上运行的价值所在。

• 后端
• 微服务
• AI Agent
• RPC框架