文档地图
本文说明 Shield 文档的阅读顺序、权威优先级和当前状态口径。遇到不同文档说法不一致时，按本页的优先级判断。
文档状态
| 状态 | 含义 |
|---|---|
| 权威契约 | 用户和实现都应遵守的稳定边界。代码、测试和示例应向这些文档收敛。 |
| 运行时语义 | 某个 runtime 子系统的细化规则。若与总纲冲突，以总纲为准；若与示例冲突，以语义文档为准。 |
| 参考文档 | 插件、部署、开发、运维等操作性说明。它应反映当前实现，不定义跨模块架构原则。 |
| 草案/归档 | 设计方向、业务模式或未来工具链。不能当作当前 runtime 已实现能力。 |
权威优先级
- 架构总纲：模块边界、依赖方向、核心非目标和扩展原则。
- Lua API 契约、配置运行时语义、错误码参考：用户可见 API、配置和错误。
- 插件系统 v1、插件参考：插件包、实例、binding、ABI 和官方插件。
- 各
runtime-*.md：服务、消息、定时器、Lua VM、网络、数据、日志、启动、安全等子系统语义。 - 路线图 和 Decision Log：当前阶段、已关闭决策和后续范围。
推荐阅读路径
新用户先读：
框架开发者先读：
插件作者先读：
- 插件系统 v1
- 插件参考
- Protocol Codec Plugins（仅协议 codec provider 作者需要）
- 目标接口头文件对应的官方插件参考页
运维和部署先读：
当前口径
Shield 当前口径是单节点优先、Lua-first、插件化后端能力。核心 runtime 和插件系统 v1 已进入当前实现路径；shield_cluster、shield_global、shield_player、shield_server、shield_ops 等官方可选模块按路线图推进。
旧 DI/IoC、annotations、conditions、events、middleware chain、旧插件 v0、旧 discovery/metrics/health core 集成不再作为兼容目标。相关历史文档若仍出现旧口径，以本页、架构总纲 和 路线图 为准。
文档分区
| 分区 | 用途 |
|---|---|
| 入门与状态 | 快速上手、路线图、FAQ、部署和开发入口。 |
| 权威契约 | 总纲、Lua API、配置、错误码、插件系统和测试矩阵。 |
| 核心运行时 | 服务、消息、定时器、Lua VM、网络、数据、日志、启动、安全和 gateway。 |
| 插件参考 | 官方插件和第三方插件开发说明。 |
| 官方可选模块 | cluster/global/player/server/ops 等不属于 core 的扩展语义，含 cluster 实现方案（已落地实施记录）。 |
| 工程参考 | 目录结构、CMake、CAF 映射、性能、最佳实践和教程，含引擎 SDK 设计（已评审拍板）。 |
| 草案与归档 | schema 工具链、xmldef toolchain、xmldef descriptor/compiler/runtime spec、Unity generator spec、基础组件/运行时适配边界、实体模式、持久化与回档等未来方向或业务模式参考。 |
当前 xmldef 专项草案建议阅读顺序：
- Xmldef Toolchain Design
- Xmldef Descriptor Spec
- Xmldef Phase 1 Implementation Plan
- Xmldef Compiler / Runtime MVP
- Xmldef Unity Generator Spec
协议分层术语、ProtocolProfile 模型和当前支持矩阵，以 Protocol Routing Design 为专项入口。协议 codec 插件 ABI、默认内置边界和 protobuf 优先落地范围见 Protocol Codec Plugins。
DB 使用纪律见 DB 使用纪律（异步入口落地后规则 1/2 已降级为推荐，3–6 仍硬）；协程恢复式异步入口的设计与里程碑状态以 DB 异步入口 为专项入口（已实现，M1–M4）。
客户端面 TLS（network.tls 配置面、握手/超时语义、证书加载与热更新取舍）以 TLS 设计 为专项入口（已实现 v1），运行时使用口径见 网络运行时语义 的 TLS 一节。
崩溃采集（Crashpad 选型、handler 初始化点、dump 落盘、符号分离、上传留位默认关）以 崩溃采集 为专项入口。
如果后续需要讨论 Lua primitives、cosocket 风格出站 I/O、CAF adapter 复用边界与 auth-first 的否定结论，可参考后置草案 基础组件与运行时适配边界。