执行摘要
- 一句话：新增运行时上下文架构技能文档
- 推荐动作：强烈建议阅读该技能文档，以深入理解 SGLang 运行时上下文的架构设计和开发者契约。该文档是理解 #30489-#30493 等重构 PR 的关键辅助材料。项目管理人员应确保代码实现堆栈先合入，再合并此 PR。
功能与动机
The runtime-context architecture now spans several tiers and CI guardrails; contributors (and coding agents) need one onboarding reference for how to read and mutate configuration, declare model-specific adjustments, and test against it.
实现拆解
该 PR 添加了一个 195 行的 Markdown 技能文档，位于 .claude/skills/sglang-runtime-context/SKILL.md，结构如下：
- 文档封面与元数据：声明技能名称、描述和加载前的提示。
- 五层架构表格：用表格列举 config、runtime flags、resources、per-forward、parallel 五个 tier 的访问器、持有内容和生命周期。
- Config 契约：详细说明 resolve-at-end 设计——
ServerArgs.__post_init__ 后字段不可变，ServerArgs.override() 是唯一受控变异入口，以及 SGLANG_STRICT_CONFIG_MUTATION 环境变量。
- Runtime flags、Resources、Per-forward、Parallel 各层说明：分别描述 override 方法、资源作用域、contextvar 机制等。
- 模型特定声明：通过 registry 和 pass 机制声明模型重写，区分加载时与 resolution 时。
- 测试惯用法：强调 override 原因而非效果，避免 patch import 绑定。
- CI 护栏：列出
SGLANG_STRICT_CONFIG_MUTATION、test_strict_writes、test_resources_teardown 等六个 guardrail 测试及其含义。
- 常见陷阱清单：列举六类常见错误及最佳实践。
关键文件：
.claude/skills/sglang-runtime-context/SKILL.md（模块 技能文档；类别 docs；类型 documentation）: 新增的技能文档，完整描述了 RuntimeContext 五层架构、开发者契约、CI 护栏和测试惯用法，是未来代码重构的 referrence，也是后续开发者的必读材料。
关键符号：未识别
评论区精华
- 文档描述的 API 在 main 上不存在：chatgpt-codex-connector 指出 per-forward 的
get_forward() 和 override_server_args() 方法在当前 main 上不存在，会导致误导。作者 ch-wan 回复称该技能文档有意描述了即将合入的代码堆栈（#30489-#30493），合并顺序是代码先、文档后，因此文档在合入后将是准确的。
- Graph-visible forward flags 的进程可见性：reviewer 指出
ForwardFlags 中的 _GRAPH_VISIBLE 字段实际是进程可见的（通过 _plain 字典），而文档描述为 contextvar-backed 且新线程见默认值，建议补充说明。此条未获作者公开回应，属于待处理的建议。
- 文档描述的 API 在 main 上不存在 (documentation): 作者 ch-wan 回应称技能文档有意描述了即将合入的代码堆栈（#30489-#30493），合并顺序是代码先、文档后，因此文档在合入后将是准确的。
- Graph-visible forward flags 的进程可见性 (documentation): 未获作者公开回应，属于待处理的建议，可能需后续更新。
风险与影响
- 风险：主要风险是依赖外部合并顺序：如果实现堆栈 #30489-#30493 未先合入，该技能文档将描述不存在的 API，导致开发者或 AI 代理混淆。但作者明确管理了合并顺序，风险可控。此外，文档中关于 per-forward 和 resources 的部分可能存在与未来实现细节不一致的微小偏差（如 EP buffer 归属）。需要确保文档在最终合并前同步代码状态。
- 影响：对开发者与 AI 编码代理的正面影响：提供统一的运行时上下文架构参考，降低入门门槛，规范配置变更和测试行为。与 CI 护栏配合后，有望减少误用 runtime state 导致的回归。影响范围限于 SGLang Python 运行时团队及贡献者。
- 风险标记：文档依赖后续代码合入顺序, 部分细节与当前 main 不一致
关联脉络
- PR #30489 : 文档提及的代码实现堆栈起始 PR，共同构成运行时上下文重构系列。
- PR #30490 : 代码实现堆栈之一，实现文档中描述的某些 API。
- PR #30491 : 代码实现堆栈之一，实现文档中描述的某些 API。
- PR #30492 : 代码实现堆栈之一，实现文档中描述的某些 API。
- PR #30493 : 代码实现堆栈终结 PR，与 #30349 一起验证整体效果。
- PR #30349 : 综合 diff 和 CI 验证 PR，确保整个堆栈的功能正确性。
参与讨论