Release Workflows
这一页说明 Agently 公开 release 信息怎样组织。它面向使用者和贡献者，帮助大家理解：一次 framework release 不只是版本号变化，还包括 release notes、compatibility manifest、README、示例、官网文档和包发布状态。
用户应该看哪些信号
| 想确认 | 看 |
|---|---|
| 当前推荐能力和用法 | 官网文档主路径 |
| 某个版本改了什么 | Release Notes |
| 兼容线和 companion 建议 | Compatibility manifest |
| PyPI 安装包描述 | README.md / package metadata |
| 示例是否仍按当前 API | examples/ 和官网案例 |
release notes 记录“这一版交付了什么”。主路径文档记录“今天应该怎么用”。两者都需要，但用途不同。
release 前后会同步哪些材料
一次公开 release 通常会同步这些公开面：
- package version 和 package metadata
- release notes
- README / README_CN
- compatibility manifest
- examples
- 官网文档
- Agently-Skills / DevTools 等配套项目的兼容说明
官网文档不会把仓库 docs 原样镜像出来。release 事实进入官网后，还要按读者路径重新整理，避免把内部验收记录、维护者备注或旧 API 推荐给新用户。
compatibility manifest 的作用
Compatibility manifest 用来回答两个问题：
- 这个 Agently framework 版本推荐或兼容哪些配套包。
- runtime event、protocol、DevTools、Skills 等边界有没有变化。
应用开发者通常不需要手动读 manifest。遇到 DevTools、Skills、runtime protocol 相关问题时，它可以帮助判断“版本范围不匹配”还是“代码本身有问题”。
clean install smoke
release 验证会在干净环境中安装 release candidate，跑最小启动脚本。这个检查用于确认：
- 普通 import 和最小 Agent / TriggerFlow 路径可用。
- 受 LazyImport 保护的可选依赖缺失时，错误提示是面向用户的。
- 不会因为 DevTools、ChromaDB、FastMCP、SQLModel、Playwright 等可选包没安装，导致普通路径启动失败。
这类 smoke 不能证明全部业务场景正确，但能抓住打包和可选依赖边界问题。
PyPI 发布怎么触发
Agently 的 PyPI 发布由版本变化驱动。公开包页面里的 summary 来自 package metadata，项目详情页主要来自 README。已经上传到 PyPI 的旧版本元数据不能指望原地变化；需要公开元数据更新时，会通过新版本发布。
使用者安装时仍然按标准 Python 包方式：
pip install -U agently需要某个可选集成时，再安装对应依赖或 companion package。
官网文档怎么跟 release 联动
官网文档更新遵循这个顺序：
- 先确认 release notes、examples、compatibility manifest 里的事实。
- 找出受影响的公开文档页。
- 按读者路径改写文档，而不是直接同步仓库文件。
- 构建并用浏览器检查关键页面。
- 保留版本线说明，避免把历史 release note 当成当前推荐路径。
如果某页只刷新了资料来源但还没经过重写和校对，它不应该作为“已更新文档”对外宣称。