reviewable wiring
route 注册、中间件顺序和依赖入口都能直接在代码评审里看到
Agent 就绪
专为使用 AI 编码工具的团队设计。
这里讨论的是 AI 编码助手（Claude、Copilot、Cursor）——帮助写代码或评审代码的工具。这不是关于构建 AI agent 服务的内容；那是 x/ai 模块的范围。
Plumego 是第一个让这些编码助手在动手写代码之前就能精确定位变更归属的 Go HTTP 工具包。 机器可读规范、每模块 manifest 和显式边界规则，让 Agent 拥有和资深 reviewer 相同的任务路由信号。
specs/task-routing.yaml 将任务类型映射到所属模块 specs/dependency-rules.yaml 阻止 Agent 越过稳定根边界 AGENTS.md 定义人类与 AI 协作的共享协议 Plumego 使用的四个专有术语。
这些词在本仓库有精确含义，不是通用的 Go 术语。
术语 一行定义
stable root（稳定根） 具有长期 API 兼容承诺的模块，属于 v1 稳定根表面：
core、router、contract、middleware、security、store、health、log、metrics。 x/* family（x/* 家族）
x/ 目录下的可选能力模块，除非另有标注否则为 Experimental。应从所属家族入口进入，而不是直接使用下级 primitive。 control plane（控制面）
docs/、specs/、tasks/ 目录，存放人类可读规则和机器可读约束，供人类和 AI 编码助手使用。 canonical path（规范路径） 由
reference/standard-service 定义的默认服务布局——每个新服务都应以此为基准进行对比。 先用三个工程信号判断是否适配。
Plumego 的适配问题应该用可见证据回答，而不是用框架宣传回答。
shared baseline
新服务先从同一套参考形态起步，而不是各自发明 bootstrap
maturity signal
采用之前先区分稳定根、受支持参考路径和实验性扩展家族
agent-ready
机器可读规范、每模块 manifest 和标准化检查命令，为代码 Agent 提供清晰的操作模型
stdlib-first
handler 签名是 func(w http.ResponseWriter, r *http.Request)——无自定义 context，所有 net/http 中间件零改造复用
zero deps
稳定核心只导入 Go 标准库——内核层无任何传递性外部依赖风险
- route registration stays visible
- middleware order is reviewable
- reference app is the canonical service shape
- release posture limits adoption assumptions
- stdlib handler signature — no adapters needed
- zero external deps in the stable corePlumego 最强的场景在哪里。
当评审清晰度、显式归属感与一套默认服务形态，比框架托管的便利更重要时，Plumego 会更有说服力。
best fit
需要在代码里追踪请求链路的内部 API
当一次 PR 应该让你看清哪些路由被注册、哪些中间件按序执行、依赖由谁持有——而不需要阅读框架源码——Plumego 更合适。
- 路由注册必须在代码评审中保持可见
- handler 归属与中间件顺序必须显式
- 团队已经习惯在 net/http 心智下工作
best fit
多个团队共用一套服务骨架的平台服务
当多个团队需要从同一份参考结构起步建立新服务，并且你希望服务间的结构漂移保持在低位时，这套框架会最有效。
- 新服务应该沿用和现有服务一致的结构
- 评审者希望整个代码库遵循一套收敛的模式
- 共用骨架能降低团队轮换时的上手成本
best fit
需要清晰模块成熟度信号的仓库
当采用决策需要基于明确的成熟度证据——稳定、受支持或实验阶段——而不是从包是否存在来推断，Plumego 更有说服力。
- 稳定表面与实验表面必须容易区分
- 团队需要知道哪些可以依赖、哪些还可能变动
- 采用范围应该跟着已发布的证据走，而不仅仅是可用性
best fit
人类工程师与 AI 代码 Agent 共同维护的仓库
Plumego 专为 AI Agent 参与执行和评审的代码库设计。四个机器可读控制面——<code>docs/</code>、<code>specs/</code>、<code>tasks/</code> 和 <code>reference/</code>——给 Agent 提供确定性操作模型：任务如何分类、先读哪些文件、正确改动应该是什么样子、贡献落地前哪些检查必须通过。让人类评审更容易的结构，同样让 Agent 的贡献可被验证。
- specs/task-routing.yaml 在打开任何代码文件之前先将任务意图映射到归属模块
- specs/change-recipes/ 为 15 种常见修改类型定义了有序步骤和止步条件
- 每个 module/module.yaml 声明该包的改动范围、风险等级、测试命令和评审清单
- internal/checks/ 以程序化方式执行边界规则——本地运行与 CI 运行的检查完全相同
- make gates 在每次推送前提供 Agent 可执行的、等同于 CI 的验证循环
AI coding assistant 也能可靠地在这套仓库里工作。
这一节讨论的是 AI 编码助手（Copilot、Claude、Cursor）——帮助写代码或评审代码的工具。这不是关于构建 AI agent 服务的话题；那是 x/ai 模块的范围。
现在大多数团队的 review 流程里都有 AI 助手参与。关键区别在于：这些助手是在猜架构规则，还是在读机器可读的规则？
Plumego 的控制面——specs/、tasks/、docs/——被设计来给 agent 提供与人工评审相同的归属信号。
work routing
Agent 在改代码之前就能知道改动该落在哪个模块
specs/task-routing.yaml 把工作类型映射到所属模块。agent 在评估一次改动时读路由表，而不是靠猜测目录结构来推断归属。
boundary enforcement
Import 违规靠机器捕获，不靠评审者记忆
specs/dependency-rules.yaml 与 internal/checks/dependency-rules 配合，违反稳定根边界的 PR 会直接卡在 gate——无论改动来自人还是 agent。
change recipes
常见修改类型有定义好的路径，而不是一个开放的 prompt
specs/change-recipes/ 给 agent 提供已知改动类型的显式执行顺序：新建稳定模块、修复 bug、晋升扩展、废弃处理。
recipe 缩小了 hallucination 空间，让 agent 的输出能用与人工评审相同的规则来检验。
适合信号与谨慎信号。
这张对照表的目的，是帮助你做决定，而不是只欣赏架构。当你真正想知道 Plumego 的显式模型会不会改善眼前这个服务时，就看这里。
信号
适合
先放慢
团队姿态 你希望在代码库变得太宽、超过单人认知之前，先建立一套共用的服务结构。 你更希望每个团队自行优化各自的服务形态，不需要共同的参考模型。
代码评审预期 评审者应该能直接在代码里检查路由、中间件和依赖注入。 评审主要关注业务逻辑，并愿意把结构性决策交给框架来负责。
仓库结构 你希望文档、示例、发布和路线图共同强化同一套可见的采用模型。 你可以接受”包存在”就暗示成熟度，不需要公开的模块边界地图。
与 Gin、Echo、Chi 的横向对比。
四者都基于 net/http，差异在哲学和范围上，而不是性能。
选型依据应该是你希望在代码评审里看到什么，而不仅仅是 benchmark 数字。
工具包 优势 权衡
Gin / Echo 上手快，生态大，约定优先的路由风格。 自定义 context 类型（
gin.Context、echo.Context）替换了标准库 handler 签名——已有的 net/http 中间件需要适配器。 Chi 纯标准库路由，极简，高度可组合。 只提供路由——没有响应体封装、没有中间件目录、没有安全辅助工具，这些都需要自己组装。
Plumego ✦ 显式服务结构，标准库 handler 签名（
func(w http.ResponseWriter, r *http.Request)），结构化 contract 层，中间件目录，安全辅助工具。 比 chi 有更多结构意见，比 gin/echo 少一些自动约定。最适合那些更看重路由 ownership 可见性和评审清晰度，而不是框架便利性的团队。 router 开销
实测：相比 stdlib ServeMux 为 1.4×–4.3×——可知且有界
Plumego 的 trie 路由器在分发之上增加了 per-request context 注入、参数映射构建和中间件链接线。
相比 Go 1.22+ http.ServeMux 的开销区间从深路径参数的 1.4×
到单参数路由的 4.3×——绝对值为 110–1,036 ns。
对于典型的 I/O 耗时 1 ms–100 ms 的 handler，router 开销占请求总时间的 0.001%–0.1%。
在发布页查看完整 benchmark 表格 →
哪些情况下应该先暂停采用。
Plumego 并不是为了赢下每次比较。如果下面这些信号更接近你的团队目标，显式模型现在可能带来的摩擦大于价值。
not a fit
团队深度依赖 Gin 或 Echo 的插件生态
Gin 和 Echo 有大量围绕其自定义 context 类型（gin.Context / echo.Context）构建的中间件目录、认证插件和社区工具。如果团队依赖这套生态，切换 handler 签名的迁移代价是真实存在的，且收益不明显。
not a fit
你需要框架内置 ORM、依赖注入容器或自动注册机制
Plumego 不携带数据库访问、依赖注入或自动注册逻辑。如果团队期待框架提供或装配这些关注点，显式 DI 模式会像不必要的负担。请选择一个完整的应用框架。
not a fit
x/* 家族的成熟度风险是你组织的硬性阻断
9 个稳定根承载 v1 兼容性承诺。x/* 扩展家族属于 experimental 或 beta——在各自证据闭环前 API 仍可能变化。如果组织政策要求所有能力都具备稳定版本化 API，请只采用稳定根和已晋级 beta 的表面。
slow down
你希望框架约定自动处理服务结构
如果团队主要想把路由和依赖配置交给框架隐式处理，Plumego 可能会显得比预期更刻意。
slow down
每个服务都刻意采用独立的自定义结构
每个服务需要自己定义启动流程、路由逻辑和依赖模式的比例越高，共用参考基线能提供的价值就越少。
采用随时间的样貌。
Plumego 在入口处刻意保持窄口，扩展路径明确。以下是三个典型采用阶段的实际情况。
第 1 天
5 分钟内运行 canonical 参考服务
cd reference/standard-service
go run .
# → server started at :8080
# → GET /ping → {"data":{"message":"pong"}}
克隆仓库，运行参考服务，阅读 internal/app/routes.go。整条请求链路无需打开任何框架源码即可看清楚。
在深入评估之前，先从这里开始。
第 30 天
从 x/* 添加能力而不触碰稳定根
稳定根基线在服务中运行稳定之后，下一个决策点是：你是否需要 x/* 层的某项能力——WebSocket、多租户、AI 流式传输、边缘代理。
每个 x/* 家族都在传输层挂载，不修改稳定根。你用 go run ./internal/checks/dependency-rules 验证边界是否保持。
specs/task-routing.yaml 在你开始前就告诉你哪个 x/* 家族拥有新能力的归属。
扩展层按自己的节奏演进，稳定根保持不变。
第 90 天与发布证据
v1 打标签后，升级路径是确定性的
9 个稳定根承载 v1 兼容性承诺。v1 标签落地后，core、router、contract
等稳定根的升级路径是机械性的——无 handler 签名变更，无 response envelope 破坏性改动。
v1 后仍处于 experimental 的 x/* 家族将继续单独追踪，成熟度等级在发布矩阵中明确标注。 你只采用已达到 beta 或 stable 的能力，不需要接受整个扩展目录的风险。
正在从其他框架迁移？
Plumego 使用标准的 func(w http.ResponseWriter, r *http.Request) handler，
现有的 stdlib 兼容中间件无需适配器即可移植。迁移指南覆盖最常见的切换路径。
下一步。
适配判断已经完成。前往架构页浏览 x/* 能力家族和完整分层图，或直接进入实现路径。