Skip to content

Commit 46c8c3f

Browse files
AgentArcLabAgentArcLab
committed
docs(release): publish release workflow guide
1 parent 98311d4 commit 46c8c3f

5 files changed

Lines changed: 218 additions & 6 deletions

File tree

‎docs/public-release-workflow.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# KsADK 公开分支与发布流程
2+
3+
本文档定义内部 `master` 与 GitHub 公开 `main` 的长期维护方式。它是发布和公开同步的执行依据。
4+
5+
## 当前模型
6+
7+
`master` 是内部源主干，GitHub `main` 是公开发布主干。两者不应该长期维护两套功能代码或两套发布门禁。公开版本由内部 `master` 的已审核状态通过 clean export 生成，导出脚本只移除不适合公开的材料。
8+
9+
公开 `main` 应包含：
10+
11+
- 公开 SDK 源码：`ksadk/`、`ksadk_runtime_common/`。
12+
- 公开构建与发布门禁：`Makefile`、`scripts/open_source_audit.py`、`scripts/check_*`、`.github/workflows/*`。
13+
- 公开文档站：`docs-site/`。
14+
- 公开 README、CHANGELOG、LICENSE、CONTRIBUTING、AGENTS、CLAUDE。
15+
- 公开发布所需的最小测试集。
16+
17+
内部 `master` 可以额外包含：
18+
19+
- 内部 docs、archive、runbook、设计草稿和预览材料。
20+
- 内部 agent skills / operator playbooks。
21+
- 内部验证脚本、E2E、长任务和平台集成测试。
22+
- 内部部署资产、临时缓存、zread/site/build 产物等。
23+
24+
因此不能简单理解为“只差 docs 和 skills 两个目录”。准确说法是：**公开导出的源码和发布门禁必须与 `master` 的公开子集一致；非公开材料由导出脚本排除**。
25+
26+
## 硬性规则
27+
28+
1. 不直接 `merge master -> main`，也不把内部 `master` 直接 push 到 GitHub。
29+
2. 公开同步必须走 clean export candidate 或等价的公开候选分支。
30+
3. 公开候选必须先通过 `make public-preflight`。
31+
4. npm、PyPI、GitHub Pages 都必须由可信 GitHub workflow 发布；不使用本地 `npm publish`、本地 `twine upload` 或手工上传 Pages。
32+
5. GitHub Release、PyPI 包、Pages 文档必须能追溯到同一个已审核 GitHub `main` 提交。
33+
6. `.pypirc`、私有 registry 凭证、kubeconfig、真实 API key、临时 token 不得进入仓库。
34+
35+
## 准备 ksadk-web
36+
37+
`ksadk-web` 是共享 UI 源头。需要新 UI 时，先在 `agentengine/ksadk-web` 发 npm 版本，再让 `ksadk-python` 和 `agentengine-hosted-ui` 消费 registry 里的固定版本。
38+
39+
本地只做验证：
40+
41+
```bash
42+
cd agentengine/ksadk-web
43+
npm test
44+
node --test tests/*.test.mjs
45+
npm run build:all
46+
npm pack --dry-run --access public
47+
```
48+
49+
正式 npm 发布只走 GitHub workflow：
50+
51+
- 推送 `ksadk-web` 代码到 GitHub `main`。
52+
- 创建 GitHub Release 或手动触发 `publish-npm.yml`。
53+
- workflow 使用 `npm publish --provenance` 发布。
54+
- 发布后用 `npm view @kingsoftcloud/ksadk-web@<version>` 确认 registry 可见。
55+
56+
## 准备内部 master
57+
58+
在 `agentengine/ksadk-python` 内部主干完成代码、文档、版本和审批记录：
59+
60+
```bash
61+
git checkout master
62+
git status --short --branch
63+
uv run pytest <相关测试>
64+
git diff --check
65+
```
66+
67+
如果本次需要绑定新的 UI 版本，确认 `KSADK_WEB_VERSION` 默认值、README、docs-site、approval record 都引用同一个 npm 版本。
68+
69+
更新审批记录：
70+
71+
```bash
72+
uv run python scripts/check_approval_record.py \
73+
--expected-current-commit <reviewed-internal-master-commit>
74+
uv run pytest tests/test_check_approval_record.py tests/test_public_release_positioning.py -q
75+
```
76+
77+
审批记录必须写清：
78+
79+
- reviewed internal `ksadk-python` commit。
80+
- `ksadk-web` npm version 和 source commit。
81+
- 已执行的 public preflight / docs build / package audit 证据。
82+
- Maintainer、Security reviewer、Release owner sign-off。
83+
84+
## 生成公开候选
85+
86+
公开候选从内部 master clean export 生成：
87+
88+
```bash
89+
cd agentengine/ksadk-python
90+
rm -rf /tmp/ksadk-python-export-candidate-<version>
91+
python scripts/prepare_ksadk_python_export.py \
92+
--output-dir /tmp/ksadk-python-export-candidate-<version> \
93+
--summary
94+
python3 scripts/open_source_audit.py \
95+
--target public-repo \
96+
--root /tmp/ksadk-python-export-candidate-<version>
97+
```
98+
99+
同步到长期 public worktree：
100+
101+
```bash
102+
git fetch github main
103+
git worktree add .worktrees/public-main github/main # 首次需要
104+
rsync -a --delete --exclude .git \
105+
/tmp/ksadk-python-export-candidate-<version>/ \
106+
.worktrees/public-main/
107+
```
108+
109+
`.worktrees/public-main` 是公开候选工作区，不做日常内部开发。
110+
111+
## 公开候选门禁
112+
113+
在 public worktree 运行完整门禁：
114+
115+
```bash
116+
cd .worktrees/public-main
117+
make public-preflight
118+
```
119+
120+
该门禁至少覆盖：
121+
122+
- PyPI 版本未重复发布。
123+
- secret 和公开路径 audit。
124+
- 从 npm registry 同步 `@kingsoftcloud/ksadk-web` 静态资源。
125+
- 公开测试集。
126+
- `docs-site` Fumadocs 静态构建。
127+
- wheel/sdist 构建。
128+
- `twine check dist/*`。
129+
- wheel/sdist 文件列表 audit。
130+
131+
失败即停止，不创建 Release，不触发 PyPI，不部署 Pages。
132+
133+
## 同步 GitHub main
134+
135+
公开候选通过门禁后，通过 GitHub PR 或受保护 main 策略合入 GitHub `main`。推荐路径：
136+
137+
1. 在 `.worktrees/public-main` 提交候选。
138+
2. 推送到 GitHub release candidate 分支。
139+
3. 开 PR 到 GitHub `main`。
140+
4. 等 CI / release-check / docs-site build 通过并完成 review。
141+
5. 合并 PR，使 GitHub `main` 成为唯一公开发布源。
142+
143+
如果维护者明确选择 fast-forward 或直接更新 `main`，也必须满足同样门禁和 review 条件。不要从内部 `master` 创建公开 release 资产。
144+
145+
## Tag 与 GitHub Release
146+
147+
tag 必须指向 GitHub `main` 上已审核、已合入的公开提交：
148+
149+
```bash
150+
git fetch github main
151+
git checkout .worktrees/public-main
152+
git pull --ff-only github main
153+
make public-release-tag V=<version>
154+
git push github v<version>
155+
```
156+
157+
创建 GitHub Release 时使用该 tag。发布说明应引用：
158+
159+
- GitHub `main` commit。
160+
- tag。
161+
- `ksadk-web` npm version。
162+
- `make public-preflight` 结果。
163+
- PyPI/Pages workflow run。
164+
165+
## PyPI 与 GitHub Pages
166+
167+
正式发布只走 `.github/workflows/publish-pypi.yml`：
168+
169+
- 触发条件：GitHub Release `published` 或手动 `workflow_dispatch`。
170+
- 输入：`ksadk_web_version`、`approved_source_commit` 和 `publish_target`。
171+
- 正常发版使用 `publish_target=full`：workflow 会跑完整 `make public-preflight`，发布 `ksadk` 主包，构建并发布 `agentengine-sdk-python` 别名包，并部署 GitHub Pages。
172+
- 补发别名包使用 `publish_target=alias-only`：workflow 只跑公开审计、公开测试、别名包构建审计和 approval gate，只发布 `agentengine-sdk-python`，不重发 `ksadk`，也不部署 GitHub Pages。
173+
- workflow 先同步 npm registry 中的 UI 静态资源。
174+
- workflow 再按 `publish_target` 运行对应发布前检查。
175+
- workflow 再运行 `make public-publish-gate`，校验 approval record。
176+
- PyPI 上传使用 OIDC Trusted Publishing。
177+
- GitHub Pages 由同一个 workflow 构建 `docs-site` 并部署。
178+
179+
发布后核对：
180+
181+
```bash
182+
python scripts/check_publication_state.py --phase post-publish --version <version>
183+
npm view @kingsoftcloud/ksadk-web@<web-version> version
184+
python - <<'PY'
185+
import json, urllib.request
186+
for name in ["ksadk", "agentengine-sdk-python"]:
187+
with urllib.request.urlopen(f"https://pypi.org/pypi/{name}/json", timeout=20) as r:
188+
data = json.load(r)
189+
print(name, data["info"]["version"], data["info"].get("project_urls"))
190+
PY
191+
```
192+
193+
## 最短可执行清单
194+
195+
一次正常公开发布的最短路径是：
196+
197+
1. `ksadk-web` 合入 GitHub `main`，由 GitHub workflow 发布 npm。
198+
2. 内部 `ksadk-python/master` 记录版本、文档、approval evidence。
199+
3. 从内部 master 生成 clean export。
200+
4. 在 public candidate 运行 `make public-preflight`。
201+
5. public candidate 通过 GitHub PR 合入公开 `main`。
202+
6. 在公开 `main` commit 上打 `v<version>` tag。
203+
7. 创建 GitHub Release 或手动触发 `publish-pypi.yml`。
204+
8. workflow 发布 PyPI 并部署 GitHub Pages。
205+
9. 运行 post-publish publication check。
206+
207+
这不是“提交 PR 到 main 后手工打 tag 和 release 文件”就结束。PR 到 `main` 只是公开源码同步；真正的 npm、PyPI、Pages 发布必须由 GitHub workflow 完成并通过发布后核对。

‎export-manifest.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
2-
"generatedAt": "2026-07-08T04:45:14.107433+00:00",
2+
"generatedAt": "2026-07-08T04:58:29.018956+00:00",
33
"targetRepository": "https://github.com/kingsoftcloud/ksadk-python",
44
"documentation": "https://kingsoftcloud.github.io/ksadk-python/",
5-
"exportPathCount": 556,
6-
"excludedPathCount": 201,
5+
"exportPathCount": 557,
6+
"excludedPathCount": 200,
77
"excludedPaths": [
88
"docs/Agent 开发者上下文接入指南.md",
99
"docs/DeepAgents说明.md",
@@ -47,7 +47,6 @@
4747
"docs/preview/images/claw_robot.png",
4848
"docs/preview/images/wps_support_group.jpg",
4949
"docs/prompt-driven-agent-creation-draft.md",
50-
"docs/public-release-workflow.md",
5150
"docs/reference/ksadk技术设计.md",
5251
"docs/reference/远程Agent运行时接口说明.md",
5352
"docs/superpowers/plans/2026-04-16-hosted-hermes-gateway.md",
@@ -244,7 +243,8 @@
244243
"ksadk_runtime_common/"
245244
],
246245
"curatedDocs": [
247-
"docs/maintainer-approval-record.md"
246+
"docs/maintainer-approval-record.md",
247+
"docs/public-release-workflow.md"
248248
],
249249
"curatedReferenceDocs": [
250250
"docs/reference/ksadk环境变量参考.md"

‎scripts/open_source_audit.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ def to_dict(self) -> dict[str, object]:
107107
prefixes=("docs/",),
108108
allowed_paths=(
109109
"docs/maintainer-approval-record.md",
110+
"docs/public-release-workflow.md",
110111
"docs/ksadk\u73af\u5883\u53d8\u91cf\u53c2\u8003.md",
111112
"docs/\u8fdc\u7a0bAgent\u8fd0\u884c\u65f6\u63a5\u53e3\u8bf4\u660e.md",
112113
"docs/reference/ksadk\u6280\u672f\u8bbe\u8ba1.md",

‎scripts/prepare_ksadk_python_export.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,10 @@
2727

2828
DEFAULT_OUTPUT_DIR = Path("/tmp/ksadk-python-export-candidate")
2929

30-
CURATED_DOCS: set[str] = {"docs/maintainer-approval-record.md"}
30+
CURATED_DOCS: set[str] = {
31+
"docs/maintainer-approval-record.md",
32+
"docs/public-release-workflow.md",
33+
}
3134
CURATED_REFERENCE_DOCS: set[str] = {"docs/reference/ksadk环境变量参考.md"}
3235

3336
ROOT_EXPORT_FILES = {

‎tests/test_open_source_audit.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,7 @@ def test_public_repo_audit_allows_curated_environment_reference_doc():
124124
"public-repo",
125125
[
126126
"docs/maintainer-approval-record.md",
127+
"docs/public-release-workflow.md",
127128
"docs/reference/ksadk环境变量参考.md",
128129
],
129130
)

0 commit comments

Comments
 (0)