KsADK

构建与打包

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

常用命令

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

Web UI 产物

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

可编辑 UI 源码不进入 ksadk-python，只在 ksadk-web 仓库维护。

本地项目构建

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

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

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

Dry Run

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

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

发布门禁

make public-build-check 在 uv build 与 twine check dist/* 之间执行 wheel 内容检查，确保发布产物干净可用。

  1. clean-dist 清空旧 dist/
  2. sync-ksadk-web-static 拉取最新 UI 静态产物
  3. uv build 构建 sdist/wheel
  4. tests/test_runtime_common_packaging.py 校验 wheel 内容
  5. twine check dist/* 最终校验

该检查会断言：

  • wheel 不含旧 ksadk/server/web-ui/ 源码、构建产物与 node_modules/。
  • wheel 不含历史构建残留（如上一次 dist/ 残片、.zread/、.pypirc）。
  • wheel 含同步后的 ksadk/server/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 需要的静态 UI 产物；可编辑 UI 源码属于 ksadk-web。

正式 PyPI 发布走 .github/workflows/publish-pypi.yml，由 GitHub Release published 事件或 workflow_dispatch 触发；workflow 先 make sync-ksadk-web-static（默认拉取 @kingsoftcloud/ksadk-web@latest，可通过 ksadk_web_version input 指定版本），再 make public-preflight，最后通过 OIDC Trusted Publishing 上传，不依赖长期 PyPI token。

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