KsADK

构建与打包

公开发布前要分别验证源码候选、文档、sdist、wheel 和干净环境安装。

常用命令

uv run --extra dev python -m twine check dist/*
make public-review

Web UI 产物

ksadk-python wheel 包含 ksadk/server/static 和 ksadk/studio/static，保证用户安装后无需 Node 也能打开两类本地 UI。

Hosted Web UI 的可编辑源码在 ksadk-web 仓库维护。公开 ksadk-python clean export 和 Python 制品只携带两套经过审计的生产静态产物，不发布 Studio 的 React / TypeScript 可编辑源码。

本地项目构建

普通 agent 项目先用本地校验起步：

agentengine run . -i
agentengine web . --no-open

云打包可能需要凭据、registry 访问、对象存储或审批后的部署目标。公开示例应把这些路径设为可选并提供本地回退。

make build-wheel 与发布构建会在结束时打印实际制品的 KsADK 版本、源码 commit、 工作树状态、wheel 文件名和 SHA-256。Code 构建也会打印打入该 zip 的版本、来源类型与 commit id；后续排障应以这段制品 provenance 为准，而不是以开发机当前安装版本推测。

Dry Run

支持处先用 dry-run 验证意图，不创建远端资源：

agentengine --dry-run build .
agentengine --dry-run deploy .

发布门禁

make public-build-check 是发布构建入口：它会生成两类前端产物，再执行 uv build、wheel/sdist 内容检查和 twine check dist/*，确保发布产物干净可用。

  1. clean-dist 清空旧 dist/
  2. sync-ksadk-web-static 拉取固定版本的 Web UI 静态产物
  3. build-studio-static 在完整源码工作区构建 Studio；在公开 clean export 中校验并复用经过审计的静态产物
  4. uv build 构建 sdist/wheel
  5. tests/test_runtime_common_packaging.py 校验 wheel 与 sdist 内容
  6. twine check dist/* 最终校验

该检查会断言：

  • wheel 不含旧 ksadk/server/web-ui/ 源码、构建产物与 node_modules/。
  • wheel 与 sdist 不含 ksadk/studio/react-ui/ 可编辑源码。
  • wheel 不含历史构建残留（如上一次 dist/ 残片、.zread/、.pypirc）。
  • wheel 含同步后的 ksadk/server/static/index.html 与生成的 ksadk/studio/static/index.html 及其 assets/ 入口，保证安装即可打开本地 UI。

本地门禁与正式发布一致

make public-preflight 在 public-build-check 之上追加 public-audit、public-test、docs-site-build，是推 GitHub/PyPI/Release 前必须通过的完整本地门禁。

Artifact 规则

发布产物禁止包含：

  • .env、.pypirc、kubeconfig、cookies、access key 或 token。
  • 私有 registry 名。
  • 内部 Helm values。
  • .agentengine/ 下的生成本地状态。
  • node_modules/。
  • Python wheel 内的 hosted-only UI bundle。
  • 客户数据、trace、日志或截图。

Python 包可包含 agentengine web 和 Studio 需要的静态 UI 产物；Hosted Web UI 源码属于 ksadk-web，Studio 可编辑源码不进入公开仓、sdist 或 wheel。

正式 PyPI 发布走 .github/workflows/publish-pypi.yml，由 GitHub Release published 事件或 workflow_dispatch 触发；workflow 执行 make public-preflight，其中会同步固定的已发布 @kingsoftcloud/ksadk-web@0.3.4（可通过 ksadk_web_version input 指定一个已发布版本），并校验 clean export 中经过审计的 Studio 静态产物，最后通过 OIDC Trusted Publishing 上传，不依赖长期 PyPI token。同步与校验会比较 npm tarball 中 dist-ksadk、ksadk/server/static 和 wheel 内静态文件的完整路径与内容哈希，并拒绝任何 Studio React / TypeScript 源码；任一不一致都会拒绝构建。

0.6.7 新增

Serverless 部署会在运行时 Pod 注入 UI 配置环境变量：KSADK_UI_PROFILE、KSADK_UI_PATH、KSADK_UI_URL、KSADK_UI_BUNDLE_PATH。Pod 内 ksadk.server.app 读取这些变量还原 UI 运行时配置，无需把本地 .agentengine/ 状态打包进镜像。

Python SDK 发布候选

维护者准备公开发布时，先跑开源门禁：

python3 scripts/audit_public_history_paths.py --json --allow-violations
git diff --check

该门禁覆盖：

  • 公开仓库审计。
  • ksadk-python 干净导出审计。
  • ksadk-web 干净导出审计。
  • 公开文档构建与审计。
  • Python 包构建。
  • 发布产物审计。
  • wheel 冒烟安装。
  • Web UI 候选测试与构建。
  • 用于发布策略的路径级 Git 历史审计证据。

历史路径审计有意只到路径级别。它用于判断首次公开导入应走 full history、clean export 还是审查过的 history rewrite，不替代内容级密钥扫描。

干净导出 vs 完整历史

首次公开导入，维护者需在三种策略中选一：

策略适用场景所需证据
clean export历史含内部路径或部署材料clean export manifest、tree digest、artifact audit、approval record
rewritten history保留公开历史重要且可行rewrite 流程、内容级历史密钥扫描、reviewer approval
full history仅当历史审计与内容扫描都干净路径级与内容级历史证据

若路径级审计报告存在 blocked 历史路径，不要直接导入 full history。除非维护者显式批准 history rewrite 与内容级扫描，否则走审查过的 clean export。

公开推送前的维护者审查

预期发布顺序：

  1. 把 review 分支推到私有维护者审查渠道。
  2. 完成维护者审查。
  3. 把审查过的源码导入 kingsoftcloud/ksadk-python。
  4. 把审查过的 UI 源码导入 kingsoftcloud/ksadk-web。
  5. 开启 GitHub Pages。
  6. 创建 GitHub Release。
  7. 发布 PyPI 或 TestPyPI 包。

不要跳过维护者审查步骤。PyPI 凭据、TestPyPI 凭据与 release token 必须留在 GitHub 源码之外。

Review Bundle

Review bundle 应包含：

  • 完整 diff。
  • 候选 export manifest。
  • clean-export SHA-256 tree digest。
  • 发布状态检查。
  • 路径级历史审计。
  • approval request。
  • final blocker list。

Reviewer 应能从 bundle 回答四个问题：

  • 哪些源码将变公开？
  • 有意移除了什么？
  • 发布前哪些命令通过了？
  • 批准了哪种 Git 历史策略？

本页导航

常用命令Web UI 产物本地项目构建Dry Run发布门禁Artifact 规则Python SDK 发布候选干净导出 vs 完整历史公开推送前的维护者审查Review Bundle