docs: add plugin system design plan

docs/plugin-implementation-plan.md

@@ -0,0 +1,85 @@
+# 插件系统阶段实现计划
+
+本文以 [plugin-system-design.md](plugin-system-design.md) 作为最终目标设计文档，把插件系统拆分成多个可上线的实现阶段。每个阶段都必须在结束时保持 gateway 当前可用：可以启动、可以回滚、可以排障，且不会要求后续阶段补齐后才能恢复基本能力。
+
+## 拆分原则
+
+- 以可用的纵向切片拆分，而不是按数据库、API、UI、SDK 等横向模块拆分。
+- 每个阶段都必须有明确的启用路径、失败回退路径和最小运维证据。
+- 默认运行路径保持保守：先稳定 `go-plugin + upstream.connect/v1`，再增加源码包、治理、观测和未来 runtime。
+- 未来能力必须可关闭、可灰度或只做设计预留，不能破坏前一阶段的可用状态。
+- `plugin-system-design.md` 是目标状态；阶段文档只描述实现顺序和阶段边界。
+
+## 阶段总览
+
+| 阶段 | 文档 | 阶段结束时可用状态 |
+| --- | --- | --- |
+| 1 | [Managed Binary Plugin MVP](plugin-implementation-stages/phase-01-managed-binary-mvp.md) | 管理员可以上传二进制 `.mcgp`，通过 Admin API/CLI 加载、启用、禁用、删除可信插件；`upstream.connect/v1` dialer mode 可用 |
+| 2 | [Protocol Proxy MVP](plugin-implementation-stages/phase-02-protocol-proxy-mvp.md) | `upstream.connect/v1` protocol-proxy mode 可用，插件可以接管 MC 字节流并实现登录代理示例 |
+| 3 | [Source Package Builder](plugin-implementation-stages/phase-03-source-package-builder.md) | 管理员可以上传 source `.mcgp`，受控 builder 产出可加载 artifact，构建失败不影响当前插件 |
+| 4 | [Admin UI, Config, Secret, Rollback](plugin-implementation-stages/phase-04-admin-ui-config-secret-rollback.md) | 管理页具备可操作的插件管理闭环，支持配置 schema、secret、配置快照和回滚 |
+| 5 | [Governance And Release Gates](plugin-implementation-stages/phase-05-governance-release-gates.md) | 生产启用前有准入策略、review、冲突分析、preflight/self-test、性能门禁和安全公告处理 |
+| 6 | [Observability And Operations](plugin-implementation-stages/phase-06-observability-operations.md) | 插件 metrics、events、trace、日志、诊断、background task、plugin_data 和文件资源治理可用 |
+| 7 | [Extension Ecosystem](plugin-implementation-stages/phase-07-extension-ecosystem.md) | 在稳定主路径上增加 route/status/provider/event/rule/Admin auth 等扩展点和官方插件能力 |
+| 8 | [Future Runtimes And Distribution](plugin-implementation-stages/phase-08-future-runtimes-distribution.md) | 可选引入 `go-plugin-process`、sandbox/WASM、ingress service、仓库、签名和构建期增强；默认路径仍可运行 |
+
+## 功能到阶段映射
+
+下表用于确认 [plugin-system-design.md](plugin-system-design.md) 中的目标能力已经拆入某个阶段。一个能力可能在早期阶段先实现最小可用版本，后续阶段再补齐治理、UI 或生态扩展。
+
+| 目标能力 | 阶段 | 拆分说明 |
+| --- | --- | --- |
+| `.mcgp` binary artifact、manifest 静态校验、artifact 登记 | 1 | 先支持二进制可信 Go plugin，上传不执行代码 |
+| Plugin Manager、desired/runtime state、dispatch table、审计 | 1 | 建立正式管理路径，替代探索式 config 插件入口 |
+| `upstream.connect/v1` dialer mode | 1 | 第一条可用数据路径，覆盖 upstream rewrite、自定义拨号 |
+| `upstream.connect/v1` protocol-proxy mode 和 `net.Conn` 接管 | 2 | 支持完整 MC 字节流接管、initial data replay、draining |
+| MC 正版/三方登录插件、forwarding、登录后协议处理 | 2 | 由 protocol-proxy 插件实现，core 不消费认证结果 |
+| Minecraft capability manifest、protocol smoke fixture | 2 | 支撑管理页展示和后续发布门禁 |
+| source `.mcgp`、builder、构建 provenance | 3 | 源码包构建成 `plugin.so` 后复用阶段 1/2 加载路径 |
+| builder 隔离、Go/module/ABI 记录、source/build log GC | 3 | 构建失败不影响 active artifact |
+| Admin 页面基础管理闭环 | 4 | 上传、构建状态、加载、启用、禁用、删除、回滚 |
+| 配置 schema、配置快照、配置迁移入口 | 4 | 错误配置不切换 active artifact |
+| SecretStore、secret version、reload/rotation 基础 | 4 | secret 不在页面、日志、审计中明文展示 |
+| artifact rollback、config rollback | 4 | 回滚前重新执行当前基础门禁 |
+| admission policy、review、risk、warning override | 5 | 生产启用前可解释和可审计 |
+| composition conflict、scope overlap、dispatch plan | 5 | 阻断 protocol-proxy 重叠、provider 单例冲突等 |
+| preflight/self-test、benchmark release gate | 5 | 高风险插件启用前有证据 |
+| denylist、quarantine、revoke、安全公告 | 5 | 阻断受影响 artifact 的 enable/rollback |
+| metrics、custom metrics、business events、trace | 6 | 提供运行时观测和脱敏摘要 |
+| plugin logger、diagnostic package、Runbook 支撑 | 6 | 插件故障可定位、可降级、可导出摘要 |
+| background task、ExternalClient、外部依赖治理 | 6 | 周期同步、受控外联、熔断和健康状态 |
+| PluginDataStore、PluginFileStore、runtime file GC | 6 | 插件私有数据和文件资源受配额/retention 管理 |
+| route resolver/provider、route decision | 7 | 降低动态路由和外部 CMDB 集成成本 |
+| status ping、MOTD、维护模式 | 7 | 不必完整 protocol-proxy 即可定制状态响应 |
+| middleware、provider、event subscriber、rule/policy engine | 7 | 补齐 Hook 之外的生产扩展形态 |
+| Admin auth provider、外部身份绑定 | 7 | 只影响管理页登录，保留本地 break-glass |
+| `go-plugin-process` 服务启动模式、进程级卸载、fd/shm 迁移 | 8 | 未来可选，默认 `in-process` 路径仍可运行 |
+| sandbox-process、WASM、capability enforcement | 8 | 面向隔离、跨语言和轻量规则场景 |
+| `ingress.service/v1` 自定义入口服务 | 8 | 由 gateway/supervisor 管理 listener，不允许插件任意监听 |
+| 插件仓库、签名、SBOM 漏洞扫描、license policy | 8 | 仓库只导入本地 artifact，不自动启用 |
+| build-time instrumentation | 8 | 官方/组织 CI 能力，产物是 gateway binary，不是热加载插件 |
+| promotion、drift、DR drill | 4-6 | 阶段 4 建立回滚和快照，阶段 5/6 补齐门禁、diff、诊断和演练证据 |
+
+## 全阶段不变量
+
+这些规则从阶段 1 开始就不能被破坏：
+
+- 上传包校验不能执行插件代码。
+- 生产路径统一以 `.mcgp` artifact 为单位管理。
+- 插件管理写操作必须有审计日志。
+- 启用失败不能破坏旧 dispatch table。
+- 禁用插件后，新连接不能再进入该插件。
+- 已加载 Go plugin 不能承诺真正热卸载；只能逻辑禁用或未来通过 `go-plugin-process` 退出子进程回收。
+- MC 正版/三方登录、身份映射、forwarding 和后续协议处理属于 protocol-proxy 插件，不由 gateway core 拼装。
+- 玩家名、UUID、source IP、secret、token、session response 和 packet payload 默认不进入指标标签、审计明文或普通诊断输出。
+
+## 阶段推进规则
+
+进入下一阶段前必须满足：
+
+- 当前阶段文档中的验收项全部通过。
+- 已实现能力有最小自动化测试或可重复手动验证步骤。
+- 失败路径已验证：加载失败、启用失败、禁用、删除、重启恢复。
+- 文档已更新：用户怎么启用、怎么回滚、怎么排障。
+
+如果某阶段出现实现复杂度超出预期，允许拆出子阶段，但子阶段也必须保持“当前可用”。

docs/plugin-implementation-stages/phase-01-managed-binary-mvp.md

@@ -0,0 +1,125 @@
+# 阶段 1：Managed Binary Plugin MVP
+
+## 目标
+
+交付最小可用的受管理插件系统：管理员可以上传二进制 `.mcgp`，gateway 能校验、登记、加载、启用、禁用和删除可信 Go plugin。第一阶段只要求 `upstream.connect/v1` 的 dialer mode 可用，用于替换上游拨号或实现简单 upstream rewrite。
+
+本阶段完成后，插件系统已经从探索代码进入 SQLite/Admin 管理路径，但不承诺源码包构建、完整 protocol-proxy、复杂治理和 Admin 完整页面。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- gateway 无插件时行为不变。
+- 管理员上传一个二进制 `.mcgp` 后，可以通过 Admin API 或 CLI inspect artifact。
+- 管理员可以加载并启用 `upstream-rewrite` 示例插件。
+- 命中插件 scope 的连接走插件返回的 upstream conn；不命中时走原默认 upstream。
+- 禁用插件后，新连接不再调用该插件。
+- 插件启用失败或 handler panic 不破坏旧 dispatch table。
+- 重启后，SQLite 中 enabled 的插件按 priority 恢复。
+
+## 范围
+
+### 包和 artifact
+
+- 支持 `.mcgp` zip 上传。
+- `artifact_type=binary`。
+- `runtime.type=go-plugin`。
+- 包内必须包含 `manifest.json` 和 `plugin.so`。
+- 上传阶段只解析 zip 和 manifest，不执行插件代码。
+- 记录 artifact sha256、plugin ID、version、Go version、GOOS/GOARCH、API version、extension points 和 capabilities 摘要。
+
+### 数据模型
+
+实现最小表：
+
+- `plugin_artifacts`
+- `plugins`
+- `plugin_operations`
+- `plugin_config_snapshots`
+- `audit_logs.metadata_json` 扩展或等价结构化审计字段
+
+字段必须能表达：
+
+- artifact 状态：uploaded、validated、loadable、loaded、rejected、deleted。
+- plugin desired state：enabled、disabled、deleted。
+- runtime state：not_loaded、loaded、enabled、failed、disabled。
+- desired generation 和 applied generation。
+- active artifact、desired artifact、loaded artifact 的差异。
+
+### Runtime 和 dispatch
+
+- 新增 Plugin Manager。
+- 保留现有 `api.Plugin` 和 `Gateway.Hook` 兼容层。
+- 将现有 `HookUpstream` 收敛为 `upstream.connect/v1` 注册路径。
+- dispatch table 使用只读快照，更新时整体替换。
+- handler 排序规则：priority 升序，priority 相同按 plugin ID。
+- handler 返回 `ErrPass` 时继续后续 handler；返回 `net.Conn` 时停止；返回普通 error 时本次连接失败。
+- handler 调用必须有 panic recover、timeout 和错误计数。
+
+### Admin API / CLI
+
+最小接口：
+
+- 上传 artifact。
+- 查看 artifact。
+- 创建或更新 plugin desired state。
+- load。
+- enable。
+- disable。
+- delete。
+- 查看 plugin runtime state。
+- 查看 dispatch plan 摘要。
+
+CLI 可以先作为开发工具，覆盖：
+
+- `plugin inspect`
+- `plugin validate`
+- `plugin compat`
+
+### 示例
+
+提供 `examples/plugins/upstream-rewrite`：
+
+- 读取 `match_host` 和 `upstream` 配置。
+- 注册 `upstream.connect/v1`。
+- 命中时 `net.Dial` 到 upstream 并返回连接。
+- 不命中时返回 pass。
+
+## 明确不做
+
+- 不支持 source `.mcgp` 构建。
+- 不支持 protocol-proxy mode。
+- 不支持 SecretStore。
+- 不支持完整 Admin 页面。
+- 不支持准入 review、SBOM、license 策略和仓库。
+- 不支持真正热卸载。
+- 不支持 sandbox、WASM 或 `go-plugin-process`。
+
+## 实现任务
+
+1. 增加 `.mcgp` 静态校验：zip slip、大小、manifest、runtime entry。
+2. 增加 manifest schema v1 的最小字段校验。
+3. 增加 Plugin Manager 和 runtime adapter 抽象，只实现 `go-plugin`。
+4. 增加 SQLite migration。
+5. 增加 desired state reconcile。
+6. 把连接路径接入 dispatch table snapshot。
+7. 实现 `upstream.connect/v1` dialer mode contract。
+8. 实现 load/enable/disable/delete API。
+9. 增加基础审计事件。
+10. 增加 upstream-rewrite 示例插件。
+
+## 验收
+
+- `upstream-rewrite` 能通过 `.mcgp` 上传、load、enable。
+- 启用后指定 host 连接到新 upstream。
+- disable 后新连接恢复默认 upstream。
+- plugin.Open 失败返回稳定错误，不影响其他插件和默认连接路径。
+- gateway 重启后 enabled 插件恢复。
+- `git diff --check` 和现有测试通过。
+
+## 回滚策略
+
+- 删除或 disable 插件即可恢复默认 upstream。
+- 如果 artifact 已加载，delete 后标记 pending cleanup，提示重启彻底清理。
+- 如果 Plugin Manager 初始化失败，gateway 应可在禁用插件系统配置下启动，并保留原有路由能力。

docs/plugin-implementation-stages/phase-02-protocol-proxy-mvp.md

@@ -0,0 +1,106 @@
+# 阶段 2：Protocol Proxy MVP
+
+## 目标
+
+在阶段 1 的管理和生命周期基础上，让 `upstream.connect/v1` 支持 protocol-proxy mode。插件可以返回自管 `net.Conn`，gateway 将已读取的 initial handshake bytes 回放给该连接，并把后续客户端字节转发给插件 endpoint。
+
+本阶段使 MC 正版/三方登录插件具备技术可行性：登录、身份映射、forwarding 和登录后的协议处理都由插件完成，gateway core 只负责连接交接和治理。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- dialer mode 仍可用。
+- protocol-proxy 插件可以接管完整 MC 字节流。
+- 初始 handshake 不丢失、不重复。
+- protocol-proxy 插件禁用后，新连接不再进入插件；已有连接进入 draining 或按管理员操作 force close。
+- `mc-auth-proxy` 示例至少能跑通一个登录失败响应或简单 session fixture。
+
+## 范围
+
+### `net.Conn` 接管契约
+
+实现：
+
+- `UpstreamConnectRequest.InitialData` 复制语义。
+- returned conn 初始写入 deadline。
+- 初始写入失败后的关闭和错误记录。
+- 双向 copy、half-close 退化、字节数统计、耗时统计。
+- active proxy connection 计数。
+- protocol-proxy 连接 draining 状态。
+
+### 请求字段
+
+补齐 request 字段：
+
+- connection ID。
+- trace ID。
+- source addr。
+- normalized server host 和 raw server host。
+- protocol version。
+- next state。
+- route ID、route tags、upstream raw/protocol/address。
+- transport、service name、listener port。
+
+字段新增必须只追加，不改变阶段 1 语义。
+
+### 示例插件
+
+提供 `examples/plugins/mc-auth-proxy` 初版：
+
+- 注册 `upstream.connect/v1`。
+- 使用 `net.Pipe` 或等价 endpoint。
+- 读取 handshake/login start。
+- 对不支持或 fixture 失败场景返回 login disconnect/kick。
+- 连接 backend 并做最小透明转发。
+- 通过事件或日志上报低基数失败原因。
+
+本阶段不要求完整生产级 Mojang/Yggdrasil 实现，但示例结构必须能承载后续认证源。
+
+### Minecraft 能力声明
+
+manifest 支持 `minecraft` 字段：
+
+- protocol versions。
+- states。
+- auth modes。
+- forwarding supported/default。
+- unsupported policy。
+- modded 声明。
+
+Admin API 可以先展示摘要，不要求完整 UI。
+
+## 明确不做
+
+- 不让 gateway core 解析 login/encryption/session。
+- 不让插件返回 `AuthResult` 给 core。
+- 不实现 `auth.provider/v1`。
+- 不做 play 阶段 packet filter。
+- 不做真实客户端大规模压测门禁。
+
+## 实现任务
+
+1. 定义 `UpstreamConnectRequest` 稳定 struct。
+2. 增加 `ErrPass`、`ErrBlocked` 和普通 error 行为。
+3. 实现 initial data replay。
+4. 实现 protocol-proxy connection lifecycle。
+5. 实现 draining 和 force close API。
+6. 增加 protocol-proxy metrics。
+7. 增加 Minecraft capability manifest schema。
+8. 增加 mc-auth-proxy 示例。
+9. 增加 protocol smoke test helper。
+
+## 验收
+
+- protocol-proxy 示例能读取 gateway 已解析前的完整 handshake bytes。
+- 初始包只被插件处理一次。
+- 插件返回不可读 conn 时，连接路径不会永久阻塞。
+- 插件 panic 只影响当前连接。
+- disable 后新连接不再进入插件。
+- 文档明确 MC 登录业务完全属于插件。
+
+## 回滚策略
+
+- disable protocol-proxy 插件恢复默认 upstream。
+- 对已有 protocol-proxy 连接，默认 drain；必要时 force close。
+- 如果 protocol-proxy 功能引发问题，可以保留阶段 1 dialer mode 插件能力。

docs/plugin-implementation-stages/phase-03-source-package-builder.md

@@ -0,0 +1,112 @@
+# 阶段 3：Source Package Builder
+
+## 目标
+
+支持 source `.mcgp`。管理员可以上传源码包，由受控 builder 构建出最终 `plugin.so` artifact，再进入阶段 1/2 已经可用的加载和启用流程。
+
+本阶段解决开发者分发源码包、记录构建环境和产物 provenance 的问题。构建失败不得影响当前 active 插件。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- 上传 binary `.mcgp` 的路径不受影响。
+- 上传 source `.mcgp` 后创建 build job。
+- build 成功后生成新的 binary artifact，可 load/enable。
+- build 失败只记录错误和日志摘要，不改变当前 active artifact。
+- 管理员能看到 source sha256、builder、Go version、module list 和 artifact sha256。
+
+## 范围
+
+### Source 包格式
+
+source `.mcgp` 必须包含：
+
+- `manifest.json`
+- `go.mod`
+- build entry
+- 源码文件
+
+可选：
+
+- `go.sum`
+- `vendor/`
+- README、LICENSE、SBOM
+
+不执行包内任意 shell 脚本。构建命令由 gateway/builder 固定生成。
+
+### Builder
+
+支持两种 builder：
+
+- `local-process`：开发模式。
+- `container`：生产推荐。
+
+生产默认推荐 container builder 或外部 CI。gateway 主进程不得直接执行 `go build`。
+
+固定构建维度：
+
+- Go version。
+- GOOS/GOARCH/GOAMD64/GOARM64。
+- CGO。
+- build tags。
+- SDK module version。
+- GOPROXY/GONOSUMDB/GOPRIVATE 策略。
+- vendor required。
+
+### Provenance
+
+记录：
+
+- source package sha256。
+- artifact sha256。
+- builder type/image/version。
+- Go version。
+- `go list -m -json all` 摘要。
+- `go version -m` 摘要。
+- ABI fingerprint。
+- build log 摘要。
+- build start/end/duration。
+
+### GC
+
+实现：
+
+- source package 保留策略。
+- build log 保留策略。
+- artifact GC candidate。
+- active/desired/snapshot referenced artifact 不可被 GC。
+
+## 明确不做
+
+- 不把源码构建等同于运行时沙箱。
+- 不支持自定义构建脚本。
+- 不强制签名。
+- 不实现远程插件仓库。
+
+## 实现任务
+
+1. 扩展 `.mcgp` 校验支持 `artifact_type=source`。
+2. 增加 `plugin_builds` 状态机。
+3. 实现 build operation 和取消/重试。
+4. 实现 local-process builder。
+5. 实现 container builder 接口或预留适配。
+6. 构建后执行 metadata ABI 校验。
+7. 构建成功写入 `plugin_artifacts`。
+8. 构建失败保存脱敏日志摘要。
+9. 增加 build API/CLI。
+10. 更新示例插件，支持 source package。
+
+## 验收
+
+- source upstream-rewrite 能构建并启用。
+- source mc-auth-proxy 能构建或至少通过编译 fixture。
+- builder Go version 不匹配时阻断启用或构建。
+- 构建日志不包含 secret、环境 token 或完整私有路径。
+- 构建失败不影响 active artifact。
+
+## 回滚策略
+
+- 构建产物只有 enable 后才影响流量。
+- 构建失败或产物校验失败时保留旧 artifact。
+- 如 builder 配置异常，可关闭 source package 构建，继续支持 binary `.mcgp`。

docs/plugin-implementation-stages/phase-04-admin-ui-config-secret-rollback.md

@@ -0,0 +1,110 @@
+# 阶段 4：Admin UI、配置、Secret 和回滚
+
+## 目标
+
+把阶段 1 到 3 的能力做成管理员可用的管理闭环。管理页支持上传、构建状态、加载、启用、禁用、删除、配置编辑、secret 配置、配置快照和 artifact 回滚。
+
+阶段结束时，普通运维不需要直接调用底层 API 才能完成插件日常管理。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- 管理员能在页面看到插件列表、artifact、runtime state 和最近错误。
+- 管理员能上传 binary/source `.mcgp`。
+- 管理员能编辑配置并执行 dry-run 校验。
+- 管理员能配置插件 secret ref，不看到 secret 明文。
+- 管理员能禁用、删除、切换 artifact 和回滚配置快照。
+- 配置错误不会切换 active artifact。
+
+## 范围
+
+### Admin 页面
+
+列表展示：
+
+- plugin ID、name、version。
+- artifact type。
+- runtime state。
+- desired state。
+- active/desired/loaded artifact。
+- extension points。
+- priority。
+- scope/rollout。
+- restart required。
+- health/最近错误。
+
+详情页展示：
+
+- manifest metadata。
+- Go/API/ABI 兼容信息。
+- capabilities 摘要。
+- Minecraft capability 摘要。
+- build 历史和日志摘要。
+- current config。
+- secret 状态。
+- dispatch plan。
+- active proxy connections。
+
+### 配置
+
+- 支持 JSON 编辑器兜底。
+- 支持 JSON Schema 基础校验。
+- 支持 `ReloadConfig()` dry-run。
+- 支持 sensitive 字段脱敏 diff。
+- 支持 config snapshot。
+- 支持 config-only rollback 和 full desired rollback。
+
+### Secret
+
+实现最小 SecretStore：
+
+- 创建/更新 secret。
+- secret ref 校验。
+- 当前/previous version。
+- reload required/hot reload 标记。
+- secret 不进入日志、审计明文和 API 响应。
+
+### 回滚
+
+支持：
+
+- artifact rollback。
+- config snapshot rollback。
+- rollback 前重新执行兼容性和当前基础门禁。
+- rollback 写审计。
+
+## 明确不做
+
+- 不做完整准入审批。
+- 不做 SBOM/license 阻断。
+- 不做外部 KMS。
+- 不做复杂声明式 UI，自定义 HTML/JS 不支持。
+- 不做 promotion bundle。
+
+## 实现任务
+
+1. 实现插件列表和详情页。
+2. 实现上传和构建状态 UI。
+3. 实现配置编辑、schema 校验和 dry-run。
+4. 实现 secret 状态和编辑流程。
+5. 实现 artifact rollback UI/API。
+6. 实现 config snapshot diff/rollback。
+7. 实现 restart required 展示。
+8. 实现基础 permission key 映射到 admin/member/guest。
+9. 所有写操作写审计。
+
+## 验收
+
+- 管理员可在 UI 上传并启用 upstream-rewrite。
+- 管理员可在 UI 上传 source package 并查看 build result。
+- 修改错误配置不会影响当前运行插件。
+- secret 在页面和审计里不显示明文。
+- rollback 到旧 artifact 后新连接使用旧版本。
+- member 只能查看状态，不能执行写操作。
+
+## 回滚策略
+
+- UI 出问题时保留 Admin API/CLI 操作路径。
+- 配置保存失败不改变 desired generation。
+- 回滚失败不改变当前 active state。

docs/plugin-implementation-stages/phase-05-governance-release-gates.md

@@ -0,0 +1,116 @@
+# 阶段 5：Governance And Release Gates
+
+## 目标
+
+把插件从“能运行”提升到“可安全进入生产”。本阶段实现准入策略、review、风险分级、冲突分析、发布门禁、preflight/self-test、benchmark 结果和安全公告响应。
+
+阶段结束后，管理员可以解释一个插件为什么能启用、为什么被阻断、启用会影响哪些流量，以及如何回滚。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- 高风险插件启用前需要 review。
+- protocol-proxy scope 重叠会阻断启用。
+- 必需 secret、依赖、feature 缺失会阻断启用。
+- preflight/self-test 失败会阻断或进入 warning。
+- benchmark 结果超过阈值会进入 warning/blocking。
+- denylist/advisory 命中后不能 rollback 到受影响 artifact。
+
+## 范围
+
+### 准入策略
+
+实现：
+
+- dev/staging/prod profile。
+- risk level。
+- policy snapshot hash。
+- warning override TTL。
+- review 记录绑定 artifact/config/scope/rollout/runtime limits/features/policy hash。
+- denylist、quarantine、revoke。
+
+### 冲突分析
+
+实现：
+
+- scope overlap。
+- protocol-proxy singleton 冲突。
+- provider singleton 冲突。
+- middleware ordering cycle。
+- shadowed handler warning。
+- dispatch plan API/UI。
+
+### Preflight 和 SelfTest
+
+实现通用门禁：
+
+- config。
+- secret。
+- external dependency 声明。
+- runtime limits。
+- scope/rollout。
+- Minecraft capability。
+- backend forwarding warning。
+
+插件实现 `PreflightChecker` 或 `SelfTester` 时复用结果。
+
+### 性能门禁
+
+记录：
+
+- benchmark profile。
+- P95/P99。
+- error rate。
+- active proxy capacity。
+- baseline diff。
+
+默认策略：
+
+- 退化超过 20% warning。
+- 退化超过 50% 或超过 runtime limit blocking。
+
+### 安全公告
+
+支持本地 advisory：
+
+- artifact sha256 match。
+- plugin/version range match。
+- SBOM dependency match。
+- recommended action。
+- fixed version。
+- mitigation status。
+
+## 明确不做
+
+- 不强制签名。
+- 不接外部漏洞库作为强依赖。
+- 不做双人审批。
+- 不自动升级或自动启用仓库版本。
+
+## 实现任务
+
+1. 实现 policy engine。
+2. 实现 review API/UI。
+3. 实现 denylist/quarantine/revoke。
+4. 实现 conflict check。
+5. 实现 preflight API 和结果存储。
+6. 实现 self-test profile。
+7. 实现 benchmark result 存储和门禁。
+8. 实现 security advisory import/rescan/ack。
+9. 将门禁接入 enable、rollback、promotion import apply。
+
+## 验收
+
+- 未 review 的高风险 protocol-proxy 插件不能在 prod profile 启用。
+- 两个同 scope protocol-proxy 插件不能同时启用。
+- required feature 缺失返回 `feature_missing`。
+- secret 缺失阻断启用。
+- advisory revoke 后不能 rollback 到受影响 artifact。
+- warning override 过期后重新阻断相关操作。
+
+## 回滚策略
+
+- policy 变更不应立即删除运行中插件；先标记 drift/review_required 或 quarantine。
+- quarantine 从 dispatch table 移除插件，新连接不进入；已有 protocol-proxy 连接按策略 drain/force close。
+- 管理员可以回滚到未受阻断的旧 artifact。

docs/plugin-implementation-stages/phase-06-observability-operations.md

@@ -0,0 +1,123 @@
+# 阶段 6：Observability And Operations
+
+## 目标
+
+补齐生产运行所需的观测和运维能力：metrics、业务事件、trace、日志、诊断包、后台任务、plugin_data、PluginFileStore、外部依赖治理、GC 和 Runbook。
+
+阶段结束后，插件出问题时管理员能定位、降级、清理和恢复，而不是只能查看 gateway 日志。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- 管理员能看到 handler calls、duration、panic、timeout、active proxy connections。
+- 插件可以上报脱敏业务事件和自定义指标。
+- trace 能关联 connection、plugin handler、external dependency、backend dial。
+- 插件能注册 interval/manual background task。
+- 插件能使用 PluginDataStore 和 PluginFileStore，并受配额限制。
+- 管理员能执行 plugin_data/file/log/artifact GC dry-run 和清理。
+
+## 范围
+
+### Metrics
+
+实现：
+
+- plugin handler calls。
+- duration histogram。
+- errors/panic/timeout。
+- active calls。
+- active proxy connections。
+- build duration/failures。
+- external dependency requests/duration/inflight/circuit state。
+- event delivery queue/drop/dead letter。
+
+### Events 和 custom metrics
+
+- 插件 manifest 声明 event schema。
+- `EmitEvent` 接收低基数字段。
+- 未声明或高基数字段拒绝或 drop。
+- 最近事件摘要保留。
+- custom metric schema 和低基数 label 限制。
+
+### Tracing
+
+- gateway 生成 connection ID 和 trace ID。
+- SDK 通过 context 传递。
+- 日志带 trace/connection ID。
+- trace 摘要脱敏。
+- 默认不向第三方依赖注入 `traceparent`，除非策略允许。
+
+### Background Task
+
+- interval/manual。
+- run-on-start。
+- jitter。
+- timeout。
+- non-reentrant。
+- manual trigger 权限和 confirm token。
+- last/next run、skipped、consecutive failures。
+
+### Data 和 files
+
+PluginDataStore：
+
+- schema version。
+- data class。
+- quota。
+- retention。
+- exportable 标记。
+- GC。
+
+PluginFileStore：
+
+- resources readonly。
+- runtime data/cache/tmp/log/diagnostic。
+- path traversal 防护。
+- quota。
+- retention。
+- orphaned dir 检测。
+
+### External dependencies
+
+- endpoint、purpose、required、timeout、retry、fail policy。
+- `ExternalClient` 受控 HTTP/TCP 调用。
+- health check。
+- circuit breaker。
+- data classes。
+- 最近错误摘要。
+
+## 明确不做
+
+- 不承诺 native plugin 无法绕过 ExternalClient。
+- 不默认开启 Prometheus/OTel exporter 的完整外部集成。
+- 不保存完整 packet payload、secret、token、session response。
+
+## 实现任务
+
+1. 实现 metrics 内部模型和 Admin API。
+2. 实现 business event/custom metric SDK。
+3. 实现 trace summary。
+4. 实现 plugin logger 和日志摘要。
+5. 实现 background task 注册和状态。
+6. 实现 PluginDataStore。
+7. 实现 PluginFileStore。
+8. 实现 ExternalClient。
+9. 实现 diagnostic package。
+10. 实现 GC APIs 和 Runbook。
+
+## 验收
+
+- mc-auth-proxy 示例能上报 `auth.success`/`auth.failure` 摘要。
+- session server 调用通过 ExternalClient 记录 latency 和错误。
+- background task 超时不会阻塞连接路径。
+- plugin_data 超配额时写入失败且不会无限增长 SQLite。
+- 诊断包不包含 secret 明文和完整 packet。
+- GC dry-run 能展示将清理的对象和大小。
+
+## 回滚策略
+
+- exporter 失败不能影响连接路径。
+- event 队列满默认 drop，不阻塞主流程。
+- background task 可取消；disable 插件时任务停止。
+- plugin_data/file GC 先 dry-run，清理操作写审计。

docs/plugin-implementation-stages/phase-07-extension-ecosystem.md

@@ -0,0 +1,116 @@
+# 阶段 7：Extension Ecosystem
+
+## 目标
+
+在稳定的插件主路径上扩展生态能力：route resolver、status ping、event subscriber、provider、middleware、rule/policy engine、Admin auth provider 和更多官方示例插件。
+
+阶段结束后，用户可以不写完整 protocol-proxy，也能用更低成本 extension point 完成常见运维需求。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- 官方 rule/policy 插件能完成 host rewrite、IP 黑白名单、简单限流或维护模式。
+- route provider 能从外部源或缓存产生可解释 route decision。
+- status ping 插件能自定义 MOTD/版本提示。
+- event subscriber 能异步投递审计或插件事件。
+- Admin auth provider 如果启用，不影响 MC 连接路径，本地 admin break-glass 保留。
+
+## 范围
+
+### Route
+
+- `route.resolve/v1`
+- `route.resolver/v1`
+- route decision schema。
+- provider cache。
+- SQLite fallback。
+- refresh action。
+
+### Status
+
+- `status.ping/v1`
+- MOTD。
+- favicon。
+- online/max players。
+- version text。
+- maintenance window。
+
+### Middleware
+
+预留并选择性实现：
+
+- `connection.filter/v1`
+- `handshake.filter/v1`
+
+必须有确定顺序、timeout、panic recover 和 fail policy。
+
+### Provider
+
+- provider singleton。
+- priority/fallback。
+- plugin dependencies。
+- `auth.provider/v1` 只作为插件间认证来源复用，不给 gateway core 组装 MC 登录流程。
+
+### Event subscriber
+
+- best_effort。
+- at_least_once。
+- queue。
+- retry。
+- dead letter。
+- replay/drop action。
+
+### Rule / Policy Engine
+
+官方插件形式提供：
+
+- host rewrite。
+- source CIDR allow/deny。
+- simple rate limit。
+- maintenance mode。
+- upstream rewrite。
+
+### Admin Auth Provider
+
+预留或实现：
+
+- OIDC。
+- LDAP。
+- external identity binding。
+- break-glass local admin。
+- gateway-issued session。
+
+## 明确不做
+
+- 不开放 play 阶段 packet filter 作为默认生产能力。
+- 不让 `auth.provider/v1` 进入 gateway core MC 登录流水线。
+- 不允许插件自定义 Admin 权限绕过 gateway 权限模型。
+- 不允许插件注入 Admin 自定义 HTML/JS。
+
+## 实现任务
+
+1. 实现 route decision 模型。
+2. 实现 route provider cache 和 refresh action。
+3. 实现 status ping extension point。
+4. 实现 event subscriber delivery。
+5. 实现 provider registry。
+6. 实现 rule/policy 官方插件。
+7. 预留或实现 Admin auth provider。
+8. 增加示例插件和 conformance fixture。
+
+## 验收
+
+- route provider 返回 override/fallback/reject/pass 都能在 Admin 解释。
+- 外部 route source 不可用时能使用 cache 或 SQLite fallback。
+- status 插件能按 host 返回不同 MOTD。
+- event subscriber 失败不影响连接路径。
+- rule 插件配置错误不会破坏默认路由。
+- Admin auth provider 不可用时，本地 admin 仍可登录。
+
+## 回滚策略
+
+- route provider disable 后恢复 SQLite route snapshot。
+- status 插件 disable 后恢复默认 status。
+- event subscriber disable 后只停止外部投递，不删除本地审计。
+- rule 插件冲突时通过 priority/scope 修复或禁用。

docs/plugin-implementation-stages/phase-08-future-runtimes-distribution.md

@@ -0,0 +1,180 @@
+# 阶段 8：Future Runtimes And Distribution
+
+## 目标
+
+引入最终设计中的未来能力，同时保持前七个阶段的默认路径可用。包括 `go-plugin-process`、sandbox-process、WASM、ingress service、插件仓库、签名、SBOM 漏洞扫描、许可证策略和 build-time instrumentation。
+
+本阶段由多个可选子阶段组成。每个子阶段都必须可以单独启用或回滚，不能要求一次性切换所有 runtime。
+
+## 可用性检查点
+
+阶段结束时必须能做到：
+
+- 默认 `in-process go-plugin` 路径仍然可用。
+- 管理后台可以配置插件服务启动模式 desired value，并明确 restart required。
+- `go-plugin-process` 至少支持 drain-only。
+- sandbox-process/WASM 如果启用，capabilities 能被强制或阻断启用。
+- 仓库导入只生成本地 artifact，不自动启用生产流量。
+- 签名、SBOM、license 和 advisory 策略能参与准入结果。
+
+## 子阶段 A：go-plugin-process
+
+实现：
+
+- gateway 插件服务启动模式：`in-process`、`go-plugin-process`、`sandbox-process`。
+- Admin 系统配置项 `plugin_service.desired_mode`。
+- 启动时读取 desired mode，校验后写入 `plugin_service.active_mode` 和 `applied_at`。
+- `restart_required` 由 desired/active 差异推导。
+- 环境级连接迁移开关：`drain-only`、`fd-live`、`fd-live-shm`。
+- plugin-host supervisor。
+- 子进程 lifecycle。
+- UDS control channel。
+- `drain-only` 进程级卸载。
+- 可选 `fd-live`。
+- 可选 `fd-live-shm`。
+- shared memory state schema。
+- `quiesce/snapshot/restore` conformance。
+
+默认：
+
+- `in-process`。
+- `active_mode` 只由 gateway 启动流程写入。
+- `go-plugin-process` 切换需要重启。
+- live migration 默认关闭。
+- 迁移默认模式为 `drain-only`。
+
+验收：
+
+- Admin 修改 `plugin_service.desired_mode` 后不立即切换当前进程，页面展示 restart required。
+- 重启后 gateway 按 desired mode 创建对应 RuntimeAdapter 或 plugin-host supervisor，并更新 active mode。
+- `go-plugin-process` 模式下启用 upstream-rewrite。
+- disable 后旧 plugin-host drain 并退出。
+- 子进程退出后 `.so` 和 Go heap 被 OS 回收。
+- crash loop 不影响 Admin 主进程。
+
+## 子阶段 B：sandbox-process
+
+实现：
+
+- control RPC。
+- supervisor。
+- crash loop policy。
+- secret RPC/handle。
+- filesystem/network/env/cpu/memory capability enforcement。
+- stream relay 或 `stream.proxy/v1`。
+
+验收：
+
+- sandbox 插件崩溃不导致 gateway 崩溃。
+- 无法强制 required capability 时阻断启用。
+- secret 不通过长期环境变量注入。
+
+## 子阶段 C：WASM
+
+实现：
+
+- WASM host ABI。
+- route/rule/config validate extension point。
+- memory/time limits。
+- no file/no network 默认策略。
+
+验收：
+
+- WASM rule 插件可以返回 allow/deny/rewrite。
+- 超时或内存超限只影响当前调用。
+- WASM 插件不能访问未授权 secret/network。
+
+## 子阶段 D：ingress service
+
+实现：
+
+- `ingress.service/v1` schema。
+- service supervisor。
+- listener ownership by gateway。
+- port conflict check。
+- TLS/secret refs。
+- health and drain。
+
+验收：
+
+- 插件声明入口服务后，由 gateway 创建 listener。
+- disable 后停止接收新连接并 drain。
+- 端口冲突阻断启用。
+
+## 子阶段 E：repository and supply chain
+
+实现：
+
+- official/internal/file/url repository index。
+- repository trust policy。
+- artifact download to local store。
+- signature verification。
+- SBOM vulnerability scan。
+- license allowlist/denylist。
+- advisory feed sync。
+- update availability。
+
+验收：
+
+- 仓库候选版本导入后仍需本地 review。
+- 仓库删除版本不删除本地 artifact。
+- denylist/advisory 仍阻断 rollback 和 promotion apply。
+
+## 子阶段 F：build-time instrumentation
+
+实现：
+
+- instrumentation manifest。
+- official/organization CI profile。
+- generated diff hash。
+- provenance。
+- conformance/benchmark/smoke gate。
+
+验收：
+
+- 插桩产物作为 gateway binary 发布，不进入 plugin artifact hot-load lifecycle。
+- Admin 展示 instrumentation metadata。
+- 插桩影响连接路径时 Runbook 说明回滚方式。
+
+## 明确不做
+
+- 不把 `go-plugin-process` 当成不可信 sandbox。
+- 不把 fd 迁移当成跨平台通用能力。
+- 不把 WASM 用于完整 MC protocol-proxy。
+- 不让仓库自动启用生产插件。
+- 不允许普通上传包携带插桩规则直接改 gateway binary。
+
+## 实现任务
+
+本阶段按子阶段逐个实施。每个子阶段都必须满足：
+
+1. 默认 `in-process go-plugin` 路径不回归。
+2. 新 runtime 或供应链能力可通过 feature flag、service mode 或 policy profile 关闭。
+3. Admin/API 能展示当前 active 状态、desired 状态和失败原因。
+4. promotion import 不能自动启用目标环境不支持的 runtime 或策略。
+5. conformance 覆盖新增 manifest 字段、feature key、错误码和回滚路径。
+
+建议顺序：
+
+1. 先实现 service mode 数据模型和 Admin 展示。
+2. 再实现 `go-plugin-process` 的 `drain-only`。
+3. 再评估 `fd-live` 和 `fd-live-shm`。
+4. 然后引入 sandbox-process 和 WASM。
+5. 最后引入仓库、签名、SBOM 扫描和 build-time instrumentation。
+
+## 验收
+
+- 未开启任何 future runtime 时，阶段 1 到阶段 7 的插件能力仍通过回归验证。
+- service mode 从 `in-process` 切换到 `go-plugin-process` 时明确提示 restart required。
+- `go-plugin-process` 子进程 crash 不导致 Admin 主进程退出，并能展示 crash loop 状态。
+- sandbox-process required capability 无法强制时，启用被阻断而不是降级为只审计。
+- WASM 插件超时、panic 或内存超限只影响当前调用。
+- repository import 只生成本地 artifact，并重新进入本地准入、review、enable 流程。
+- build-time instrumentation 产物不会出现在 runtime plugin enable/disable 列表中。
+
+## 回滚策略
+
+- runtime mode 切换失败时回到 `in-process`。
+- sandbox/WASM 插件失败时禁用对应 plugin，不影响 `go-plugin` 插件。
+- repository 功能失败不影响本地 artifact。
+- build-time instrumentation 回滚到上一 gateway binary。