Web UI 仓库
KsADK Web UI 源码属于独立仓库 kingsoftcloud/ksadk-web，并以 npm 包
@kingsoftcloud/ksadk-web 发布。ksadk-python 通过 make sync-ksadk-web-static
从 npm 包的 dist-ksadk 目录同步静态产物到 ksadk/server/static，供本地
agentengine web 使用。Studio 生产静态产物位于 ksadk/studio/static；公开
clean export 保存 Studio React / TypeScript 源码和依赖锁，不包含生成的静态资源。
构建时从固定 npm 版本同步 Web 并编译 Studio；sdist 与 wheel 携带经过审计的静态资源。
边界
| 仓库 / 包 | 职责 |
|---|---|
kingsoftcloud/ksadk-web | 可编辑 React/Vite 源码、测试、Pages demo、npm 发布 |
@kingsoftcloud/ksadk-web (npm) | 构建产物 dist-ksadk / dist-hosted 的分发渠道 |
ksadk-python 公开仓 | Python SDK、CLI、runner、本地 server 与 Studio 源码和依赖锁 |
| Python 制品 | SDK 和编译后的 server/static、studio/static，不含前端开发依赖 |
| hosted UI | 生产部署壳、网关、镜像和环境注入，同样从 npm 包消费 |
ksadk-python 的公开 clean export 不包含 ksadk/server/web-ui 源码，也不包含
node_modules、dist/、dist-hosted/ 等 UI 仓库中间产物。Hosted Web UI 源码在
kingsoftcloud/ksadk-web 仓库维护；Studio 源码进入公开 export；静态产物仅在构建时生成并进入 Python 制品。
同步规则
make sync-ksadk-web-static 负责把 npm 包 @kingsoftcloud/ksadk-web 的
dist-ksadk 同步到 ksadk/server/static：
# 默认拉已验证的 npm 版本
make sync-ksadk-web-static
# 0.8.4 候选固定具体版本
make sync-ksadk-web-static KSADK_WEB_VERSION=0.3.7不要在 wheel 构建时实时拉 GitHub latest release
latest 不可复现，会引入网络和供应链风险，也无法保证 wheel 内容与发布记录一致。
发布候选必须固定 KSADK_WEB_VERSION 到具体版本。如需在受限网络环境兜底，请使用
KSADK_WEB_RELEASE_URL 指定一个已审计的 tarball。
受控包构建
make build 与 make build-wheel 会先同步固定版本的 ksadk-web，从依赖锁构建
React Studio，再构建 wheel。内部与公开 Git 源码使用同一路径：
make build-wheel KSADK_WEB_VERSION=0.3.7安装 wheel 的用户无需构建前端。该通用 wheel 不包含框架依赖和原生工具链； 完全断网安装需另外准备相应依赖的 wheelhouse。
同步变量
| 变量 | 默认值 | 说明 |
|---|---|---|
KSADK_WEB_VERSION | 0.3.7 | 已发布的 npm 包版本；发布候选必须固定为具体版本 |
KSADK_WEB_PACKAGE | @kingsoftcloud/ksadk-web | npm 包名 |
KSADK_WEB_TARBALL_NAME | kingsoftcloud-ksadk-web-<version>.tgz | tarball 文件名，由版本推导 |
KSADK_WEB_RELEASE_URL | 空 | 显式指定 tarball URL 兜底，优先级高于 npm pack |
KSADK_WEB_CACHE_DIR | .cache/ksadk-web | 本地解包缓存目录 |
KSADK_WEB_REGISTRY | https://registry.npmjs.org | npm registry，仅在无 npm CLI 时用于解析 tarball URL |
sync 优先级：KSADK_WEB_RELEASE_URL 显式 tarball > npm pack > registry 解析。
无论走哪条路径，最终都会校验 dist-ksadk 目录存在，再覆盖到 ksadk/server/static。
发布记录
每次 ksadk-python release note 应记录：
ksadk-python版本（如0.8.4）。KSADK_WEB_VERSION/ npm 包版本（如0.8.4对应@kingsoftcloud/ksadk-web@0.3.7）。- 受控构建命令（如
make build-frontend KSADK_WEB_VERSION=0.3.7）。 - wheel / sdist 审计结果（
make public-build-check/twine check dist/*）。
0.8.4 候选记录示例
ksadk-python:0.8.4- npm 包:
@kingsoftcloud/ksadk-web@0.3.7 - 前端构建:
make build-frontend KSADK_WEB_VERSION=0.3.7 - 审计:
make public-build-check通过，twine check dist/*通过