企业官网建设流程全解析

• 人工智能
• AI Agent
• AI 应用
• 前端
• UI组件

A2UI（Agent-to-User Interface）是一个开源标准与库集合，允许 Agent 以声明式 JSON 描述 UI 意图，再由客户端渲染器映射为原生组件。本指南围绕 A2UI 仓库中的 python/README.md（Python SDKs 说明）展开，重点讲解"如何判断 PyPI 上已发布的 Python SDK 与仓库python/目录源码之间是否存在未发布变更"，并在此基础上深入解读 Python SDK 的包结构、核心模块、构建与发布流程，帮助你既能用一条命令追踪版本漂移，也能真正理解a2ui-core与a2ui-agent-sdk两个包在 A2UI 体系中的分工与实现。

读完本文，你将掌握：

• 用一段可复用的 shell 命令，基于 PyPI JSON API 与 GitHub Commits API 检测 Python SDK 是否有未发布的 commit；
• 看懂 A2UI Python SDK 的整体架构，包括a2ui-core的状态管理、消息处理、校验引擎，以及a2ui-agent-sdk的解析器、推理格式、ADK 扩展与 A2A 集成；
• 了解从源码构建、运行测试到发布到 PyPI 的完整工程化流程与版本管理约定。

一、为什么需要"检测未发布变更"：版本漂移的日常场景

A2UI 是一个持续演进的多语言仓库（Python、Dart、TypeScript、Swift、Kotlin 等），其中 Python 相关的代码集中在仓库根目录下的 python/ 目录。a2ui-core与a2ui-agent-sdk以独立版本发布到 PyPI，而仓库main分支上的代码可能领先于最近一次发布。

对于以下人群，检测未发布变更非常有用：

• SDK 使用方：依赖已发布版本，需要确认最新 release 是否已包含某个修复或新特性，决定是否升级或等待；
• SDK 维护者 / 贡献者：在合并 PR 前后确认python/目录下是否有尚未随 release 发布的改动，为发布决策提供依据；
• CI / 发布自动化：将检测命令接入流水线，避免"改了代码但忘了发布"或"发布了但代码未合入"的错位。

这个需求本质上是比较两个数据源：PyPI 上最后一次发布的时间与GitHub 上python/路径最近一次 commit 的时间。文档给出的命令正是围绕这两个数据源构建的。

二、核心命令：一行脚本对比 PyPI 发布时刻与仓库提交记录

python/README.md提供了完整的检测命令，我们逐段拆解其原理与可定制点：

# 第一步：从 PyPI 获取 a2ui-agent-sdk 最新版本的最近上传时间 export LAST_RELEASE_TIME=$(curl -s "https://pypi.org/pypi/a2ui-agent-sdk/json" | python3 -c " import sys, json d = json.load(sys.stdin) v = d['info']['version'] print(max(f['upload_time_iso_8601'] for f in d['releases'][v])) ") echo "LAST_RELEASE_TIME=$LAST_RELEASE_TIME" # 第二步：查询该时间之后 python/ 目录下的所有 commit curl -s "https://api.github.com/repos/a2ui-project/a2ui/commits?path=python&since=$LAST_RELEASE_TIME"

第一步的工作原理：

• curl拉取 PyPI 的 JSON API（https://pypi.org/pypi/a2ui-agent-sdk/json），该接口返回包的全部元数据，包括info.version（最新版本号）与releases（每个版本对应的发布文件列表）；
• python3内联脚本取出最新版本号v，再从releases[v]中提取每个发布文件的upload_time_iso_8601字段，取其中的最大值（ISO 8601 格式的 UTC 时间字符串，可直接用于 GitHub API 的since参数）；
• 之所以取最大值而非任意一个文件的上传时间，是因为一个版本可能包含多个 wheel/sdist 文件，发布流程存在先后，应以最后一个文件上传完成的时间为准。

第二步的工作原理：

• 调用 GitHub Commits API，path=python将查询范围限定在仓库python/路径下，since=$LAST_RELEASE_TIME只返回该时间点之后的 commit。

结果的解读规则（文档原文明确规定）：

• 若返回空列表[]，说明 Python SDK 自上次发布以来没有新的改动，源码与已发布版本一致；
• 若返回非空 commit 列表，说明python/目录下存在尚未发布的新变更，列表中的每条记录都包含 commit message、作者、时间戳等详细信息，可用于进一步核对变更内容。

这个机制与仓库的发布约定严格对应：python/README.md位于仓库根目录，而a2ui-core与a2ui-agent-sdk的源码、CHANGELOG 都在 python/ 下，因此path=python恰好覆盖全部 Python SDK 相关代码。如果你只关心某一个包，可以把参数改为path=python/a2ui_agent或path=python/a2ui_core，实现更细粒度的检测。

三、命令的可复用化：从一次性脚本到常驻检查

上述命令可以直接复制使用，也可以改造成仓库级的发布检查脚本。几点实操建议：

1. 确定以哪个包为准：文档以a2ui-agent-sdk为检测对象。由于a2ui-agent-sdk依赖a2ui-core>=0.2.0,<0.3.0（见 python/a2ui_agent/pyproject.toml），且发布流程约定"两个包一起发布时先发布a2ui-core"（见 docs/contributing/release.md），所以用a2ui-agent-sdk的发布时间作为基准通常已经足够；需要单独核对 core 包时，将 URL 中的包名替换为a2ui-core即可。
2. GitHub API 的since参数要求 ISO 8601 时间格式，PyPI 返回的upload_time_iso_8601正好满足，无需额外转换。
3. 注意 API 速率限制：GitHub REST API 未认证时存在每小时请求数限制，脚本化高频调用时建议携带认证 token 或作为 CI 手动任务运行。
4. 判断基线：该命令检测的是"相对于 PyPI 最新发布的漂移"，而非相对于某个 git tag。若需对比具体 tag，可改用 GitHub 的 compare API（/compare/python/a2ui-agent-sdk/vX.Y.Z...main）。

四、A2UI Python SDK 全景：两个包的分工与目录结构

要正确解读"未发布变更"，需要先理解python/目录下到底有什么。仓库中的 Python SDK 自 0.3.0 起被拆分为两个独立包（见 python/a2ui_agent/CHANGELOG.md 中 "Splita2ui_coreanda2ui_agentinto separate packages"）：

两个包均要求 Python>=3.10（见 python/a2ui_agent/pyproject.toml 与 python/a2ui_core/pyproject.toml）。

4.1a2ui-core：协议的中立引擎

python/a2ui_core/README.md 对 core 库的定位是"framework-agnostic、logic-neutral"层，为服务端 Agent、渲染后端与一致性测试框架提供基础能力，且严格面向 A2UI 规范 v0.9 及以后版本（不支持 legacy v0.8）。其主要能力：

• 协议处理：对称处理 A2UI 规范的消息信封（CreateSurface、UpdateComponents、UpdateDataModel、DeleteSurface）；
• 响应式状态管理：基于自研Signal的响应式追踪，以及SurfaceGroupModel、SurfaceModel、SurfaceComponentsModel的分层模型；
• DataContext：数据绑定与函数执行环境，支持动态路径解析与自动依赖更新；
• 目录（Catalog）系统：ModelCatalog（结构化 Pydantic/对象类编译）与JsonCatalog（原始 JSON Schema 直接加载）两种目录实现；
• 校验与完整性：Pydantic 编译信封 + JSON Schema Draft 2020-12 动态目录校验，并附带循环布局检测、可达性分析、孤儿组件追踪、递归引用验证等完整性检查。

从源码结构看，core 的模块布局与客户端@a2ui/web_core引擎对称，这是为了"评估状态表示、解析动态布局值时保持精确对等"。其核心包划分如下（对应 python/a2ui_core/README.md 中的 Architecture 一节）：

• State Layer（a2ui/core/state）：Signal、DataModel、SurfaceComponentsModel、SurfaceModel、SurfaceGroupModel；
• Resolution Engine（a2ui/core/resolution）：DataContext、GenericBinder、ComponentContext；
• Message Processing（a2ui/core/processing）：无状态的MessageProcessor，将原始 A2UI 消息翻译为SurfaceGroupModel层的结构性变更；
• Catalogs（a2ui/core/catalog）：JsonCatalog与ModelCatalog；
• Basic Catalog（a2ui/core/basic_catalog）：TextComponent、ButtonComponent、CardComponent等开箱即用组件模型；
• Symmetrical Schemas（a2ui/core/schema）：编译后的 Pydantic 消息包装、A2uiMessage、信封与能力配置结构。

4.2a2ui-agent-sdk：让 Agent "说 UI"

python/a2ui_agent/README.md 说明 Agent SDK 位于python/a2ui_agent/src/a2ui，围绕 LLM 输出到 A2UI 载荷的全链路提供能力：

• Schema 管理：A2uiSchemaManager负责加载规范 Schema、管理目录、为 LLM 生成系统提示词；A2uiCatalog与CatalogConfig处理组件库，其中A2uiCatalog.validate_components借助a2ui-core的PayloadValidator校验组件。
• 解析器：parse_response同步解析、增量流式解析器（带自动 JSON 修复与校验）、payload_fixer自动纠正 LLM 输出的常见 JSON 问题。
• Basic Catalog：BasicCatalog提供 A2UI 基础组件处理。
• A2A 集成：extension.py管理 A2UI 扩展 URI 与激活逻辑；parts.py负责创建携带 A2UI 数据的 A2A Part。
• ADK 扩展：SendA2uiToClientToolset让 Agent 通过工具调用向客户端发送 UI。

从 python/a2ui_agent/src/a2ui/schema/manager.py 可以看到一个重要演进信号：A2uiSchemaManager已被标记为 deprecated 兼容重定向，实际继承自DirectJsonFormat（即a2ui.inference_formats.direct_json.format）。这说明 Agent SDK 的架构重心已迁移到**推理格式（Inference Format）**体系——direct_json、express、atom、elemental等格式统一通过InferenceFormat抽象组织（对应a2ui/inference_format.py），旧的A2uiSchemaManager仅为兼容保留。若你在旧文档中看到A2uiSchemaManager，新代码应改用DirectJsonFormat。

五、从 LLM 输出到客户端 UI：Agent SDK 的核心调用链

理解 Agent SDK 的"未发布变更"价值，最好结合一条真实调用链。以 ADK 集成路径为例（源码：python/a2ui_agent/src/a2ui/adk/send_a2ui_to_client_toolset.py）：

1. 工具注册：SendA2uiToClientToolset接受三个 provider：a2ui_enabled（是否启用 A2UI，可为 bool 或同步/异步 callable）、a2ui_catalog（目录，可为A2uiCatalog实例或 callable）、a2ui_examples（示例，可为字符串或 callable）。get_tools根据a2ui_enabled的解析结果决定是否暴露_SendA2uiJsonToClientTool。
2. 提示词注入：process_llm_request将目录渲染为 LLM 指令（render_as_llm_instructions，见 python/a2ui_agent/src/a2ui/schema/catalog.py），连同示例一起追加到系统指令中。
3. 工具执行与修复：LLM 调用sendA2uiJsonToClient工具并携带a2ui_json参数后，run_async首先通过parse_and_fix（python/a2ui_agent/src/a2ui/parser/payload_fixer.py）对原始 JSON 字符串做容错修复：
   • 将智能引号（弯引号）规范化为标准引号；
   • 解析失败时自动去除尾随逗号后重试；
   • 单个 JSON 对象会自动包装为列表以便统一校验；
   • 对反斜杠转义问题给出带行号/列号的诊断提示。 随后调用a2ui_catalog.validate_components(a2ui_json_payload)对载荷中的每个组件做 Schema 校验，校验通过后跳过二次 LLM 推理（skip_summarization = True），返回{A2UI_VALIDATED_JSON_KEY: payload}。
4. Part 转换与传输：get_part_converter返回配置好的A2uiPartConverter，将校验后的数据转换为 A2A Part 发送给客户端。A2A 侧的 MIME 类型定义在 python/a2ui_agent/src/a2ui/a2a/parts.py：v0.9+ 使用application/a2ui+json，v0.8/0.9 早期兼容路径使用已废弃的application/json+a2ui。

这条链路中，"解析修复 → 目录校验 → Part 封装"正是 Agent SDK 相对 core 的增量价值，也是 CHANGELOG 中频繁出现的改动区域。

六、其他推理格式与最新特性（0.7.0 预览）

从 python/a2ui_agent/src/a2ui/inference_formats/ 的目录结构可以看到，Agent SDK 除了direct_json标准格式，还包含多个实验性格式：

• express：基于 ANTLR 文法（specification/inference_formats/express/Express.g4）生成解析器的紧凑 DSL 格式，支持关键字参数、多版本输出（v0.9 / v0.9.1 / v1.0）以及顶层surface()/deleteSurface()指令；
• atom与elemental：位于experimental/下的实验格式，分别提供编译/反编译/解析/提示词生成组件。

0.7.0 版本（见 python/a2ui_agent/CHANGELOG.md）还引入了若干新能力，这些都在"未发布变更检测"的观察范围内：

• 类型安全的 Python Builder API（a2ui.builder），用嵌套对象构造组件树并序列化为协议消息；
• A2UI Macros API（a2ui.transformers.macros），通过@macro装饰器与MacroExpander将高阶复合组件降级为原始组件子树；
• SkillGeneratorAPI 与Skill/SkillSet领域模型，把推理格式规则与目录定义编译为标准化的SKILL.mdAgent 技能包；
• 同时包含多项BREAKING变更：移除了a2ui.validation.*、A2uiTemplateManager等旧模块，A2uiCatalog.validator改为返回单目录PayloadValidator实例，依赖升级为a2ui-core>=0.2.0,<0.3.0。

这些破坏性变更进一步凸显了检测未发布变更的价值：升级 SDK 前先查看python/目录的近期 commit 与 CHANGELOG 的Unreleased段落，可以提前评估破坏面。

七、构建、测试与发布：工程化约定

7.1 运行测试与构建

python/a2ui_agent/README.md与python/a2ui_core/README.md给出了标准的开发命令：

# 进入包目录后运行全部测试（含单元、conformance、结构完整性测试） cd python/a2ui_agent && uv run pytest cd python/a2ui_core && uv run pytest # 在 python/ 目录下同步虚拟环境与依赖 uv sync # 代码格式化 cd python && uv run pyink .

构建 SDK 有一个特殊前置条件：uv build会从specification/inference_formats/express/Express.g4重新生成 Express 解析器，该步骤运行 ANTLR，需要PATH中存在 JRE 11 或更高版本的 Java 运行时（见 python/a2ui_agent/README.md）。

7.2 版本号来自 git tag，不要手工编辑

两个包的版本管理遵循同一套约定（详见 docs/contributing/release.md 与 python/a2ui_agent/pyproject.toml）：

• 版本由 hatch-vcs 在构建时从 git tag 推导：a2ui-agent-sdk使用python/a2ui-agent-sdk/v*tag 系列，a2ui-core使用python/a2ui-core/v*tag 系列；
• 没有 tag 的检出（例如浅克隆的 CI）回退到pyproject.toml中的fallback-version（分别为 0.6.0 与 0.1.1），并剥离本地版本段（+g<hash>），因为 PyPI 拒绝此类版本；
• 源码中的 python/a2ui_agent/src/a2ui/version.py 只从已安装的发行版元数据读取版本（通过importlib.metadata），未安装时返回0.0.0+unknown——所以不要在任何文件中手写版本字符串。

7.3 发布流程

Python SDK 的发布通过 GitHub Actions 工作流完成（.github/workflows/release-pypi.yml），每 1～2 周一个发布周期，无需本地脚本：

1. 检查python/a2ui_agent/CHANGELOG.md与python/a2ui_core/CHANGELOG.md的Unreleased段落，为空则无需发布；
2. 运行 Release Python SDKs 工作流，选择包与 bump 级别，首次以dry_run: true试运行（只暂存构建产物并移除，不推送任何东西）；
3. 检查 dry run 输出后，关闭dry_run正式发布；
4. 打开并合并工作流生成的 changelog PR（工作流只推送 tag，不直接推main，因为main受 ruleset 保护）。

发布前的前置检查（.github/scripts/release_version.py）会在以下情况让运行失败：Unreleased段落为空、目标版本已有 tag、或提议的a2ui-core版本超出a2ui-agent-sdk的 pin 范围。最后一个约束意味着a2ui-core的 minor 升级必须同时放宽 python/a2ui_agent/pyproject.toml 中的依赖区间。两个包一起发布时，a2ui-core先发布（因为 agent 包依赖它）。

发布完成后，.github/workflows/release-verify-pypi.yml 每小时校验 PyPI 是否出现对应版本。这与第一节的检测命令形成了闭环：发布侧用 PyPI 时间戳做校验，使用侧用 PyPI 时间戳做漂移检测，二者共享同一事实来源。

八、安全边界：把外部 Agent 的输出视为不可信输入

最后必须强调，这与"检测未发布变更"看似无关，实则是使用 Python SDK 时不可省略的工程前提。python/a2ui_agent/README.md 的 Disclaimer 明确指出：任何在你直接控制之外的 Agent 都应视为潜在不可信实体，其 AgentCard、消息、工件与任务状态都应作为不可信输入处理，否则可能引入：

• 提示注入：恶意 Agent 在name、skills.description等字段中构造数据，未经清洗用于 LLM 提示词构造；
• UI 冒充与 XSS：伪造合法界面诱导用户（钓鱼），或在属性值中注入恶意脚本；
• DoS：生成过度的布局复杂度拖垮客户端性能。

因此，开发者有责任实现输入清洗、内容安全策略（CSP）、对可选内嵌内容（iframe/webview）的严格隔离，以及安全的凭据处理。SDK 的校验链（parse_and_fix+validate_components）能拦截格式与 Schema 层面的错误，但业务层的信任边界仍需应用方自行约束。

九、小结：把检测命令用起来

回到本文的主题。要确认 A2UI Python SDK 是否有未发布变更，只需三步：

1. 从 PyPI 获取a2ui-agent-sdk最新版本的最近上传时间；
2. 调用 GitHub Commits API 查询python/路径在该时间之后的 commit；
3. 空列表 = 源码与已发布版本一致；非空列表 = 存在待发布改动，进一步查看 commit 与 python/a2ui_agent/CHANGELOG.md、python/a2ui_core/CHANGELOG.md 的Unreleased段核对变更内容。

结合本文对包结构、调用链、构建发布约定的解读，你可以把这条命令从"一次性脚本"升级为"版本漂移监控"与"升级前风险评估"的日常工具，始终清楚自己使用的是哪个版本的 A2UI Python SDK、以及仓库里还藏着哪些即将到来的变化。

• 人工智能
• AI Agent
• AI 应用
• 前端
• UI组件