先判断，再进入实现
如果你还没有完全确认适配度，就先回到“为什么选择 Plumego”；如果判断已经清楚，就从文档首页继续实现路径。
文档首页
注意： 本页中文版本与英文版可能存在差异，建议关键决策前参考英文版文档。
Plumego 是一个 stdlib-first 的 Go Web 工具包，用于构建显式、可审计的 HTTP 服务。它保持 net/http handler 签名不变，提供结构化的错误和响应合约，并将能力组织为稳定的内核加可选的扩展家族。
“stdlib-first”在实践中意味着什么： 你的 handler 就是普通的 func(http.ResponseWriter, *http.Request)，可以在 Plumego、http.ServeMux 以及任何导入了 net/http/httptest 的测试中直接使用——无需解包任何框架类型。
先从开始使用页进入，跑通参考服务，只有当问题变成”归谁负责”时才进入仓库边界。
v1.0.0： 稳定根 API 承载 v1 兼容性承诺。
x/*家族继续按成熟度标注，采用时应以支持矩阵为准。
你现在在哪个阶段？
Section titled “你现在在哪个阶段？”刚开始评估 — 还不确定 Plumego 是否适合？ → 先读 Why Plumego（适合度判断、与 Gin/Echo/Chi 的对比）。 再跑 开始使用 验证代码风格是否符合预期。
准备实现 — 评估完成，开始创建服务？ → 打开 开始使用 走最短可运行路径。 再从 参考应用 复制完整的规范目录结构。
寻找特定能力（AI、多租户、WebSocket、网关）？ → 浏览 扩展家族 (x/*) — 按成熟度分级的全部家族，含标签和手册链接。 或进入 模块总览 查看按工作类型分组的完整参考视图。
在代码库里使用 AI 编程助手？ → 阅读 Agent-First 工作流 — 机器可读规范如何在写代码前把 Agent 路由到正确模块。
正在从 Gin、Echo 或 Chi 迁移？ → 访问 迁移中心 — handler 差异、中间件适配、成本估算与逐步指南。
需要在引入依赖前确认稳定性？ → 阅读 发布策略 查看完整支持矩阵。
前 30 分钟路径
Section titled “前 30 分钟路径” 1 go get + go run 见开始使用
2 /healthz data.status 为 ok
3 /api/v1/greet {"data":{"message":"hello, Alice"}}
4 参考应用 启动、路由、处理器
5 下一页 请求流程或模块边界
1
安装并运行
见开始使用
2
验证存活
data.status 为 ok
3
验证路由
{"data":{"message":"hello, Alice"}}
4
检查形态
启动、路由、处理器
5
选择深度
请求流程或模块边界
→ 开始使用 — 安装、写一个 handler、运行。5 分钟内完成。
按问题选择入口
Section titled “按问题选择入口”| 当前问题 | 打开 | 得到什么 |
|---|---|---|
| 怎么最快跑起来一个示例？ | 开始使用 | 5 分钟内运行一个服务 |
| 应该从哪些文件复制结构？ | 参考应用 | 启动、应用接线、路由和处理器的文件级地图 |
| 仓库如何分层——稳定根、扩展家族、canonical 路径？ | 架构 | 三层边界地图：内核 / 扩展 / canonical 路径 |
| 一个请求如何流经 Plumego？ | 请求流程 | 从路由注册到 contract.WriteResponse 的可见路径 |
| 一项改动应该放在哪里？ | 仓库边界 | docs/specs/tasks 控制面的分工 |
| 应该打开哪个模块？ | 模块总览 | 按工作类型选择稳定根或 x/* 入口 |
| 有哪些 x/* 家族，成熟度如何？ | 扩展家族 | 卡片浏览器——全部家族含状态徽章和手册链接 |
| AI agent 怎样在代码库里导航？ | Agent 工作流 | 控制平面、任务路由、CI 等效验证循环 |
| 如何从 Gin、Echo 或 Chi 迁移？ | 迁移中心 | handler 差异、成本估算和逐框架指南 |
| 能不能长期依赖某个包？ | 发布策略 | 在采用或集成前确认支持姿态 |
| 如何连接数据库 / 添加认证 / 与 Gin 对比？ | 常见问题 | 直接回答常见问题 |
core.New 或 contract.WriteError 的准确函数签名是什么？ | API 快速参考 | 稳定模块的完整签名、类型和报文格式 |
| 错误类型 X 意味着什么，如何修复？ | 错误参考 | 所有 ErrorType 常量含触发场景和修复步骤 |
稳定表面速查
Section titled “稳定表面速查”| 表面 | 适合用于 | 不适合用于 |
|---|---|---|
| 稳定根 | 内核、路由、合约、中间件、安全、存储、健康、日志和指标基础能力 | 可选产品能力或协议型功能工作 |
reference/standard-service | 规范服务形态和可运行示例 | 仓库归属判断 |
x/* 家族 | 不应扩张稳定根的可选能力工作 | 每个服务都必须学习的默认路径 |
docs、specs、tasks | 人类意图、机器可读规则和执行范围 | 运行时包 API |
同步仓库事实
Section titled “同步仓库事实”模块事实
模块与边界
默认学习路径从稳定根开始，能力工作从主扩展家族开始。
稳定根
9
主扩展家族
14
发布事实
发布姿态
在假设长期兼容性之前，先看 README 同步过来的支持矩阵。
当前版本
v1.1.0
支持分组
6
路线图事实
当前方向
路线图摘要会在构建前从 docs/release/roadmap.md 自动同步。
进行中
1
计划中
0
这些摘要全部来自构建前同步的仓库事实，而不是站点专属副本。