KsADK 0.8.1

公开发布时间：2026-08-13
变更记录冻结：2026-08-10

[0.8.1] 变更记录

亮点

• 首次交付 AgentKit Studio：0.8.0 尚未包含 Studio；0.8.1 新增 agentengine studio 本地 Agent 构建与运行控制台。首版直接采用单一 React shell，统一承载 Agent、会话、构建、部署、工程资源、可观测性、运行资源和任务编排页面；React 是首次交付时的前端选型，不是从既有 vanilla Studio 迁移而来。
• Agent 全生命周期在一个本地工作区闭环：支持快速创建、对话构建、YAML/Agent ZIP 导入、ADK/LangGraph 项目识别，以及 Agent 配置、能力绑定、校验、构建、运行、评估、部署、回滚和操作进度查询。根路径直接进入 Agent 工作区，不引入需要单独维护的 /chat 前端入口。
• 对话运行升级为可暂停、可继续的人机交互状态机：在 0.8.0 RuntimeEvent v1、AG-UI/A2UI 和 RuntimeAdapter 基础上，打通 Responses/SSE 增量输出、持久化事件回放、切换会话与刷新恢复、暂停/继续/取消、审批提交和结构化用户输入。ADK、LangGraph 与 Codex 共用运行状态和交互投影，不要求 Studio 为每个框架维护一套私有渲染协议。
• 本地可观测性成为 Studio 的一等能力：新增运行概览、趋势卡片、可分页筛选的 Trace 列表、Span 瀑布时间线、详情面板、Attributes/Events/Resource 浏览，以及格式化并高亮的 Raw OTLP 预览；会话运行详情可直接关联完整 Trace。
• 标准 OTLP 成为唯一远端 trace 通路：每个 Python Agent 进程使用一个 TracerProvider，由两个 OTLP/HTTP BatchSpanProcessor 将同一批 spans 写入 Langfuse 主路（标准 OTEL_EXPORTER_OTLP_*）和 CloudMonitor 次路（平台 CLOUD_MONITOR_OTLP_*），两端保持相同的 trace_id / span_id。不再部署 CallbackHandler、Langfuse SDK exporter、Collector、sidecar、额外容器或额外 Pod。
• 托管可观测性默认开启：agentengine deploy、agentengine launch 和 agentengine hermes deploy 默认请求平台可观测性；CLI 与控制台共用控制面开关，由平台注入主路和次路配置。只有显式选择 --no-observability 或在控制台关闭时才禁用。

新增

• 新增 Studio 本地控制面与版本化 API，覆盖 workspace、Agent、模板、资源目录、模型配置、凭证引用、构建、运行、会话、Trace、评估、部署和长操作；本地写请求使用随机 session token 与 CSRF 校验，凭证可从当前进程、全局配置或项目配置解析。
• 新增模型、Python Tool、MCP 与 Skill 资源管理。Python Tool 支持源码上传、只读检查、可复制示例和 schema 校验；Skill 支持候选扫描、逐项复核导入、冲突确认、文件树浏览以及 Markdown/代码高亮预览。
• 新增 Agent 外观配置和图标资源上传；Agent 本地标识默认使用带随机后缀的稳定 ID，表单统一标明必填、选填和自动生成字段，并提供文件拖放、多选、选择器、数据表、对话框与代码预览等共享 React 组件。
• 新增 Studio 会话工作区：单行紧凑会话列表、流式正文与思考/工具 activity、上下文窗口用量、附件入口、三档审批策略、/goal / /plan 命令和运行模式条。审批等级从下一轮实时生效，生成期间发送按钮切换为暂停/停止控制。
• 新增 A2UI surface 增量归并、持久化回放和交互回传，支持确认、单选、多选与自定义输入；无 A2UI surface 时，工具、审批和 RuntimeEvent 仍以克制的通用 activity 卡片展示。
• 新增运行资源与任务编排页面，将 Runtime、模型、Tool/MCP/Skill 绑定、路由约束和最近调度投影为可检查的 DAG；节点根据画布宽度自适应布局。
• 新增 AgentKit manifest、Codex Agent 构建与运行服务、资源/能力目录、操作事件流、Agent 头像资产以及本地 OTLP Trace 存储与查询能力。
• agentengine hermes deploy 新增可重复的 --env KEY=VALUE 与 --env-file（dotenv 或 JSON 对象），并可自动发现当前目录 .env；优先级为 --env > --env-file > 当前进程环境 > 自动 .env。显式环境参数会进入新建或更新 payload，未显式指定时更新已有 Hermes 不覆盖服务端环境配置。OpenClaw deploy 同步复用该解析规则并新增 --env-file 与自动 .env 加载。
• 新增 React Studio 专项 CI 门禁，覆盖协议归并、组件行为、TypeScript、生产构建、样式契约、桌面浏览器烟测和常见分辨率响应式烟测，并校验随 Python 包分发的静态产物与 React 源码一致。

变更

• Runtime 启动路径收敛到显式的 factory、adapter 和 conversation execution 边界；CLI、Web、A2A、AG-UI 与 Studio 共用同一运行时装配逻辑，减少模块级全局 runner 和重复 SSE 实现。
• Codex 从旧 runner 路径收敛到 CodexRuntimeAdapter 与官方 app-server transport，补齐模型代理、HOME 隔离、审批/沙箱策略、全局凭证继承、结构化交互事件和中断后的流式 transport 回收。
• Responses 输入、会话历史、运行事件、tool/approval/A2UI activity 和 usage 在服务端统一投影；/v1/responses 保持主要会话接口，/v1/chat/completions 继续作为 OpenAI-compatible 协议入口，而不是 Studio 页面路由。
• Studio 前端源码位于 ksadk/studio/react-ui，Python 包中的 ksadk/studio/static 只保存其生产构建产物；首次交付不引入另一套 vanilla Studio 前端。
• Studio 桌面布局统一适配 MacBook 14 英寸及常见 2K/4K 视口；导航、DAG 画布、会话列表、Composer、深浅色主题和 Trace 详情共享设计令牌与响应式规则。手机竖屏不属于 0.8.1 支持范围。
• 删除 langfuse_exporter.py、runners/utils/langfuse.py、LANGFUSE_USE_CALLBACK 和 Langfuse SDK callback 路径；tracing extra 不再安装 langfuse，仅保留 OpenInference 自动插桩。
• 调整 Python 包依赖边界：langchain-openai 仅随 langchain、langgraph 和 deepagents framework extras 安装，不再由基础 ksadk wheel 强制安装。这样 Hermes 等不使用 LangChain OpenAI adapter 的运行时可保留其已验证的 OpenAI SDK 版本；选择这些框架的生成项目仍会声明并安装同一受支持版本范围。
• all extra 纳入 Codex 支持；Studio 运行与测试依赖补齐 MCP、Pillow 和 Playwright，wheel/sdist 继续只打包 React 生产静态资源而不包含 Node.js 源码依赖。
• agentengine hermes exec 增加显式 --agent 目标并改为 argv 原样透传，由远端 Pod 执行最终命令策略；普通 argv 不再被猜测为 Agent 名称，--session 业务会话 ID 会写入 terminal start frame。
• 用户显式调用 save_memory 时向 SDK 记忆后端发送 flush=True，保证本次数据完成抽取后再返回；自动轮次保存继续使用后端默认批处理语义。
• agentengine studio 默认继续仅监听 loopback，但端口调整为 8080；可用 --port 覆盖。Studio 前端源码开发代理也使用同一默认端口。

修复与性能

• 修复 LangGraph 回调将 ToolGateway 结果序列化为 JSON 文本时，工具审批未被识别为可恢复交互的问题；Responses 客户端现在会收到标准审批项，批准后可继续原工具调用并执行真实副作用。
• 修复 LangGraph 中 ToolGateway 审批完成后向已结束图发送原生 resume、导致副作用虽已执行却没有后续回复的问题；现在会基于已持久化的真实工具结果继续生成最终回答，同时保留原生 interrupt() 的 resume 语义。
• 修复 Studio 快速创建向导与模板编排 API 的请求契约，并将 ADK/LangGraph 的源码路径和入口变量完全交由服务端生成；“创建后立即构建并打开会话”现在会实际提交 Build、等待成功后再进入会话。Codex、ADK、LangGraph 三种 Runtime 均按同一流程创建和构建。
• 修复 Codex RuntimeAdapter 事件信封丢失调用方 agent_id / user_id / invocation_id 的问题，避免通过 /v1/responses 运行时因作用域校验不一致返回 500。
• 修复通用 Agent 创建与更新部署 payload 未标记敏感环境变量的问题；模型 API Key、Token、Secret 等现在按统一规则写入 IsSensitive，避免控制面将其按普通变量处理。
• 修复 Codex ManagedRuntime 的本地声明构建与请求组装：部署/--dry-run 会加载项目 YAML、计算 manifest SHA-256 并传给控制面，而不把部署参数误当作 Agent manifest。
• 修复 Codex 中断后 SDK transport 残留后台等待任务，避免事件循环退出阶段挂起。
• CloudMonitor traces 专用 endpoint、protocol 和 headers 分别优先于通用配置；CLOUD_MONITOR_OTLP_TRACES_HEADERS 与 CLOUD_MONITOR_OTLP_HEADERS 都支持 RFC 3986 percent-encoded values。
• CLOUD_MONITOR_APP_KEY 降级为一个版本的过渡 fallback：仅当 traces 和通用 headers 环境变量都整体缺失时才翻译为 Ksc-Appkey。任一 headers 变量已提供但无有效 Ksc-Appkey 时 fail closed，不混入旧 AppKey。
• AgentEngine 托管 runtime 在模块级 ksadk.server.app:app 与 BaseRunner.run_server() 两个真实入口都按 KSADK_A2A_RUNTIME_ID 挂载 discovery-only /.well-known/agent-card.json；卡片明确声明 streaming=false，不开放 JSON-RPC、REST Task 或其他 A2A 数据面路由。
• A2ASpaceClient.from_env() 优先读取 KSADK_A2A_SPACE_ID，并保留对单元素 KSADK_A2A_SPACE_IDS JSON 数组的兼容读取。
• A2A 核心依赖改为 a2a-sdk[fastapi]；PostgreSQL TaskStore 支持移到可选 ksadk[a2a-postgres]，discovery-only runtime 不再因 A2A 被强制安装 PostgreSQL adapter。会话系统既有 asyncpg 依赖保持不变。

兼容性、迁移与评审边界

• 0.8.1 是 AgentKit Studio 的首次交付，不存在从 0.8.0 Studio 或 vanilla Studio 迁移的问题。Studio 只有一个 React 前端入口；自研 UI 仍可直接消费 Responses/SSE、RuntimeEvent、AG-UI/A2UI 和运行控制 API，不要求使用 React。
• RuntimeEvent schema 继续保持 v1 additive 兼容；新增交互和运行控制通过追加事件类型与控制 API 表达，不修改既有事件字段语义。
• 旧 LANGFUSE_* 凭证不再创建 SDK callback/exporter。迁移时把 Langfuse OTLP endpoint 与 Authorization header 配置到标准 OTEL_EXPORTER_OTLP_*。
• 新部署使用 CLOUD_MONITOR_OTLP_TRACES_HEADERS 或 CLOUD_MONITOR_OTLP_HEADERS 提供 Ksc-Appkey；CLOUD_MONITOR_APP_KEY 仅用于旧控制面的短期兼容。
• A2A 环境变量明确区分部署期 KSADK_A2A_RUNTIME_ID 与注册后 KSADK_A2A_AGENT_ID；v1 discovery card 只依赖前者。
• Codex ksadk init 的本地 web/Responses 运行与 ManagedRuntime 请求组装已验证；真实云端部署仍依赖服务端发布 Runtime catalog、对应 Linux runtime image 和内联 manifest 的公开控制面契约。该服务端能力未在本次 SDK 发布中宣称可用，SDK 不会把 Codex 静默降级为 Code 部署。

文档

• 同步中英文 README、Studio CLI、可观测性、环境变量、知识库与记忆库指南；新增可从左侧导航进入的 AgentKit Local Studio 指南，补充首次 Studio 交付、React 源码/构建产物边界、运行控制与交互协议、默认 OTLP 双写、显式关闭、header 优先级、旧 AppKey 边界以及 Hermes session 语义。

发布记录

• Python：ksadk==0.8.1
• 内置 Web UI：@kingsoftcloud/ksadk-web@0.3.1（source b4e9f938828ef669347dadb7f0eb3f0a01747a6a）
• AgentKit Studio：首次交付，React 单一前端随 Python wheel 分发生产构建产物
• 当前状态：公开发布；相对 0.8.0 的 Studio、Runtime、Codex、可观测性、CLI、依赖与文档变更均记录于本节
• 本地发版验证：Studio 快速创建、构建和会话入口已覆盖 Codex、ADK、LangGraph；ksadk init -f <codex|adk|langgraph> 生成的三套模板均已通过 ksadk web、/v1/responses 本地对话和 ksadk deploy --dry-run 请求规划验证。ADK、LangGraph 另已完成隔离环境中的真实部署和调用；Codex 真实云端部署待上述服务端 Runtime 上线后复验。
• PyPI、tag、GitHub Release 与公开文档站通过受信 workflow 发布