# PR #32586 完整报告

- 仓库：`sgl-project/sglang`
- 标题：docs(cookbook): mark every Kimi-K3 cell in-progress; land Playground "Switch base" on the configurator
- 合并时间：2026-07-28 09:59
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/32586

---

## 执行摘要

为 Kimi-K3 部署表格引入三态验证徽标（已验证 / 终验中 / 未验证），所有 45 个单元格标记为“终验进行中”，同时修复 Playground 中“↑ Switch base”返回按钮的滚动目标，使其直接定位到配置器组件而非标题。纯文档与 UI 调整，无运行时代码变更。

## 功能与动机

Kimi-K3 页面原先所有单元格标记为 Not Verified，与“无人验证过”同义。但实际上这些配置运行无误，只是最终权重和服务验证过程尚未完结。两状态（verified/unverified）无法区分“从未验证”和“正在验证”。Playground 的“Switch base”按钮跳转到 `## Deployment` 标题，在 Kimi-K3 页面上距配置器 10316 像素，用户点击后看不到目标面板。

## 实现拆解

1. **三态验证引擎 **（`_deployment.jsx`）：新增 `verifyStatusOf` 和 `cellVerifyStatus` 辅助函数，将布尔 `verified` 扩展为三态字符串（`verified` / `in-progress` / `unverified`）。`badge` 和 `badgeDot` 样式函数改为通过状态查表获取颜色，并增加 `whiteSpace: nowrap` 防止长文本换行。
2. **模型配置数据 **（`kimi-k3.jsx`）：在每个单元格中添加 `verificationStatus: "in-progress"` 字段，并留下注释说明后续如何升级回 `verified: true`。
3. **Playground 跳转修复 **（`_playground.jsx`）：镜像定义 `DEPLOYMENT_COMPONENT_ID = "deployment-configurator"`，将按钮的 `getElementById` 目标优先改为该 id，再回退到旧 heading slug。
4. **页面文案更新 **（`Kimi-K3.mdx`）：Note 中将“Not Verified”改为“Final Verification In Progress”，并限定范围到 Deploy 面板。

### `docs_new/src/snippets/_deployment.jsx`

核心引擎文件，新增三态验证状态逻辑和 lookup 表，修改 badge 渲染函数，是本次变更的核心。

```jsx
// 三态验证：扩展布尔 verified 为字符串状态，提供 look-up 标签和颜色
const VERIFY_LABEL = {
  verified: "Verified",
  "in-progress": "Final Verification In Progress",
  unverified: "Not Verified",
};

// 将任何状态输入归一化为合法的三态 id
const verifyStatusOf = (status) => {
  // 布尔 true → verified；合法字符串原样返回；其余一律当作 unverified（包括 typo 如 "in_progress"）
  if (status === true) return "verified";
  if (status === "verified" || status === "in-progress" || status === "unverified") return status;
  return "unverified";
};

// 从 cell 对象中提取验证状态：优先使用 verificationStatus，否则回退到 verified
const cellVerifyStatus = (cell) =>
  cell.verificationStatus !== undefined
    ? verifyStatusOf(cell.verificationStatus)
    : verifyStatusOf(cell.verified);

// badge 样式函数：根据归一化后的状态选择背景和文字颜色，whiteSpace: nowrap 防止长标签折行
badge: (status) => ({
  display: "inline-flex",
  alignItems: "center",
  gap: "6px",
  padding: "2px 8px",
  borderRadius: "10px",
  background: {
    verified: isDark ? "#064e3b" : "#d1fae5",
    "in-progress": isDark ? "#1e3a8a" : "#dbeafe",
    unverified: isDark ? "#78350f" : "#fef3c7",
  }[verifyStatusOf(status)],
  color: {
    verified: isDark ? "#a7f3d0" : "#065f46",
    "in-progress": isDark ? "#bfdbfe" : "#1e40af",
    unverified: isDark ? "#fde68a" : "#92400e",
  }[verifyStatusOf(status)],
  fontSize: "11px",
  fontWeight: 600,
  whiteSpace: "nowrap",
}),

```

### `docs_new/src/snippets/_playground.jsx`

Playground 组件，修复“Switch base”按钮滚动目标，使其跳转到配置器组件而非标题。

```jsx
// 在文件开头的常量区域添加（与 _deployment.jsx 保持一致的镜像定义）
// ==== MIRROR of DEPLOYMENT_COMPONENT_ID in _deployment.jsx — keep identical ====
// Snippets cannot import each other. The Deploy panel puts this id on its
// root (carrying its own scrollMarginTop), which is what "jump to the base"
// should land on.
const DEPLOYMENT_COMPONENT_ID = "deployment-configurator";

// 在按钮 onClick 中替换硬编码 id
onClick={() => {
  // 优先跳转到配置器本身，回退到 heading slug
  const el = document.getElementById(DEPLOYMENT_COMPONENT_ID)
    || document.getElementById("deployment")
    || document.getElementById("deploy");
  if (el) el.scrollIntoView({ behavior: "smooth", block: "start" });
}}

```

## 评论区精华

无 review 讨论，PR 直接通过。

## 风险与影响

低风险。仅影响文档页面前端展示逻辑，无运行时代码。防御性回退确保未识别的 status 值解析为 unverified，不会误显示通过。Playground 按钮回退链确保非配置器页面行为不变。

影响 Kimi-K3 页面所有单元格显示蓝色“Final Verification In Progress”徽标（原黄色“Not Verified”）。影响所有包含 Playground 组件的 cookbook 页面：返回按钮跳转到 `#deployment-configurator` 而非 `## Deployment` 标题。

## 关联脉络

本 PR 是 #32542（Kimi-K3 cookbook 引入）的后续改进，是在该页面初次发布后根据体验反馈做的两项独立修复。后续维护者可参考注释中的流程将已验证的单元格升级为 `verified: true`。