从 `specs/repo.yaml` 同步
稳定根9
contractcoreroutermiddlewaresecuritystorehealthlogmetrics
模块总览
Plumego 把长期稳定的公开包放在仓库根部，把可选能力与快速演进功能放在 x/*。这个拆分是有意的：它让稳定表面保持收敛，也让归属更容易判断，并避免默认学习路径被扩展能力重新定义。
| 层级 | 数量 | 采用建议 |
|---|---|---|
| 稳定（GA） | 9 个包 | 生产可用。v1 兼容性承诺适用。 |
| Beta | 7 个家族 | API 在连续次版本 release ref 之间冻结。可在生产中安全使用，升级前查看发布说明。 |
| 实验性 | 7 个主入口家族 | API 可能在无缓冲期的情况下变更。在稳定服务路径中使用前，建议用 app-local 接口包装依赖。 |
完整成熟度证据、扩展单包看板与发布矩阵：状态总览 →
同步模块清单
Section titled “同步模块清单”从 `specs/task-routing.yaml` 同步
主扩展家族14
x/tenantx/fileapix/messagingx/gatewayx/restx/websocketx/frontendx/observabilityx/openapix/resiliencex/rpcx/datax/aix/validate
这些列表由构建前同步脚本生成，而不是手工重复维护。
仓库层级地图
Section titled “仓库层级地图”1稳定根内核、路由、合约、中间件
2参考应用启动、路由接入、handler
3x/*可选家族，先从主入口开始
4docs/specs/tasks意图、机器规则、执行范围
1
默认服务路径
内核、路由、合约、中间件
2
可运行形态
启动、路由接入、handler
3
能力工作
可选家族，先从主入口开始
4
控制面
意图、机器规则、执行范围
稳定根 core router contract middleware security store health log metrics
x/* families 可选能力和协议表面
控制面 reference docs specs tasks module.yaml| 工作类型 | 从哪里开始 | 原因 |
|---|---|---|
| 内核、生命周期、路由结构、传输合约 或稳定中间件 | 稳定根 | 这是每个服务都应该理解的默认路径 |
| 能力、协议、租户、网关、数据拓扑或观测适配器工作 | x/* 家族 | 可选能力工作不应该扩张稳定根 |
| 应用本地启动和服务接线 | 参考应用 | 规范服务形态不属于运行时包归属问题 |
| 归属规则、routing taxonomy、import boundary 或执行范围 | 仓库边界 | 这些属于 docs/specs/tasks 控制面问题 |
扩展入口规则
Section titled “扩展入口规则”| 如果工作围绕 | 先从这里开始 | 什么时候再下钻 |
|---|---|---|
| messaging、queue、pubsub、scheduler 或 webhook | x/messaging |
任务已经明确属于 scheduler、webhook、pubsub 或 mq |
| 边缘传输、反向代理或负载均衡 | x/gateway |
任务已经明确属于 discovery 或 ipc |
| 可复用 resource-interface 工作 | x/rest |
已进入具体 CRUD/resource controller 问题 |
| 更高层观测适配器 | x/observability |
任务已经明确属于 ops 或 devtools |
| 数据拓扑、sharding、durable KV 或读写分离 | x/data |
任务已经明确属于 cache |
接下来应该打开哪些模块 primer
Section titled “接下来应该打开哪些模块 primer”当顶层问题已经明确后，就不要停留在总览页，而应该继续进入对应模块 primer。
稳定根 — ga
Section titled “稳定根 — ga”这些模块承载 v1 稳定根兼容性承诺，是推荐的第一个生产评估范围。
| 如果问题主要围绕 | 下一步打开的 primer | 为什么应该先读这里 |
|---|---|---|
| 应用构造、lifecycle 与 路由挂载 | Core Primer · 稳定 | core 拥有 HTTP 应用内核与规范生命周期路径 |
| HTTP 传输包装层、request ID、追踪、限流与访问日志 | Middleware Primer · 稳定 | middleware 负责保持顺序敏感的 HTTP 行为窄且显式 |
| 路由匹配、路径参数、route group 与反向路由 | Router Primer · 稳定 | router 拥有基于 trie 的路由匹配表面 |
| 请求/响应合约、错误模型、上下文助手与追踪元数据 | Contract Primer · 稳定 | contract 定义每个 handler 都使用的规范错误与响应形态 |
| 认证基础元语、JWT、密码助手、security header 与输入验证 | Security Primer · 稳定 | security 提供 fail-closed 认证与验证基础元语 |
| 存储合约、文件抽象、cache primitive 与 幂等合约 | Store Primer · 稳定 | store 定义了进入拓扑型数据问题之前的稳定持久化层 |
| 存活和就绪模型类型与健康聚合 | Health Primer · 稳定 | health 拥有组件检查器合约与就绪状态模型 |
| 基础日志合约与结构化 logger 接线 | Log Primer · 稳定 | log 定义扩展包与稳定根共享的日志表面 |
| 基础指标合约与 collector 注册 | Metrics Primer · 稳定 | metrics 定义指标表面，不拥有导出器或适配器行为 |
先从主家族入口进入，不要直接下钻到下级包。以成熟度层级作为采用信号。
API 在连续次版本 release ref 之间保持冻结。可在生产中安全使用；升级前查看发布说明。
| 如果问题主要围绕 | 下一步打开的 primer | 晋升版本 | 下级包 |
|---|---|---|---|
| 可复用 CRUD 传输与资源路由标准化 | x/rest Primer | v0.2.0 | — |
| 实时 WebSocket 连接生命周期、hub 管理或认证 | x/websocket Primer | v0.2.0 | — |
| 反向代理、gateway 路由、负载均衡或边缘传输 | x/gateway Primer | v0.2.0 | x/gateway/discovery · x/gateway/ipc（实验性） |
| Prometheus 导出器、OTel 接线、记录缓冲或 DB 分析 | x/observability Primer | v0.2.0 | x/observability/ops · x/observability/devtools（实验性） |
| 多租户解析、策略、配额、限流或 session | x/tenant Primer | v1.1.0 | resolve、policy、quota、ratelimit、session、store |
| 静态资源服务、嵌入式 FS 或 SPA fallback 路由 | x/frontend Primer | v1.1.0 | — |
| 应用侧 queue、pubsub、scheduler 或 webhook 编排 | x/messaging Primer | v1.1.0（应用层） | scheduler · webhook · pubsub · mq（下级原语仍为实验性） |
实验性家族中的 Beta 表面
Section titled “实验性家族中的 Beta 表面”父家族根仍为实验性，但这些子包在 v1.1.0 时获得了 release 背书的 API 稳定性。
| Beta 表面 | 父家族 primer | 说明 |
|---|---|---|
x/ai/provider · x/ai/session · x/ai/streaming · x/ai/tool |
x/ai Primer | 用这些子包做稳定的 AI 工作；其余子包和根家族仍为实验性 |
x/data/file · x/data/idempotency |
x/data Primer | 用这些子包做稳定的文件存储和幂等性工作；拓扑表面和 x/data/cache 仍为实验性 |
API 兼容性未冻结。采用前请先评估；在稳定服务路径中使用时建议用 app-local 接口封装依赖。
| 如果问题主要围绕 | 下一步打开的 primer | 下级包 |
|---|---|---|
| AI provider 适配器、session、流式传输或 tool 调用 | x/ai Primer | provider、session、streaming、tool 为 Beta 表面（见上方）；orchestration、semanticcache、distributed、resilience 仍为实验性 |
| 读写分离、分片、持久化 KV 或幂等性拓扑 | x/data Primer | x/data/cache；file 和 idempotency 为 Beta 表面（见上方） |
| 文件上传、下载或流式传输的 HTTP 传输层 | x/fileapi Primer | — |
| 跨扩展共享的熔断器、重试封装或弹性适配器 | x/resilience Primer | — |
| gRPC + HTTP 服务托管或出站 RPC 客户端池 | x/rpc Primer | — |
| 从已注册路由生成 OpenAPI 3.1 文档 | x/openapi Primer | — |
| 显式 JSON 绑定与调用方自有请求验证 | x/validate Primer | — |
这页希望你避免什么
Section titled “这页希望你避免什么”当前仓库会主动避免把 ai、tenant、rest、pubsub、frontend、utils、validator 这类宽泛或含糊的名字继续长成顶层根目录。只要一个名字听起来更像 feature catalog 或模糊大桶，它大概率就不是正确起点。
- API 快速参考 — core、contract、router 的完整函数签名
- 稳定根
- x/* 家族
- Core Primer
- x/rest Primer
- 仓库边界