qzl/social-app

Fork 0

Files

T

qzl 4d55df45ab refactor: unify skills+cli runtime and streamline ag-ui flow

2026-04-22 17:09:37 +08:00

31 KiB

Raw Blame History

AgentScope Skill + CLI Tool Protocol Refactor PRD

1. Goal

本次重构的目标不是发明一套新的 agent 工具体系，而是把当前项目的工具执行、skill 使用、UI 生成这三条链路收敛到一条一致的协议路径上：

以 AgentScope 原生 tools 和 skills 能力为基础。
将当前项目工具包装为符合 AgentScope 工具协议的 CLI 工具。
skill 不负责执行工具，而是负责向 agent 渐进式披露"有哪些能力、什么时候用、怎么用"。
CLI 工具的 runtime 认证边界以用户登录 token 为主，默认通过受控环境变量注入，而不是直接注入数据库 session / owner_id。
worker agent output 不再输出 ui_hints。
tool output 继续保留独立结构化协议对象，并可携带 ui_hints 给前端渲染使用。
worker 在 ReAct loop 中消费的工具信息应收敛为 tool message content，而不是完整 ToolAgentOutput 元数据对象。
message.content 继续保持文本投影，不升级为通用 schema 字段；结构化结果进入 ToolAgentOutput.result。
ToolResponse 只返回 result 文本投影；再由 tool 后处理器把 result 解析/补全为完整 ToolAgentOutput，包括 ui_hints 等字段。

本次改造的核心收益：

减少 worker 输出 token 成本
消除 UI 在 worker / backend compiler / frontend renderer 三处漂移
让工具边界对 AgentScope、skill、前端渲染都更稳定

2. Corrected Design Principles

以下原则是本 PRD 的前提，必须严格遵守：

AgentScope 原生支持 skills。
- 官方 README 明确列出 built-in support for tools, skills
- 官方示例提供 toolkit.register_agent_skill(...)
skill 是给 agent 的能力说明与工作流知识，不是业务执行 transport。
如果工具改成 CLI，CLI 仍然必须服从 AgentScope 的工具协议，而不是项目自己随意定义。
preset/runtime 参数应该以认证凭证为边界，当前项目应使用 Bearer token，并默认通过受控环境变量注入 CLI 执行环境，而不是把 DB session 直接暴露给工具调用接口。
worker output 和 tool output 的协议职责必须分离，不能混成同一套字段语义。
协议文档先行，docs/protocols/** 仍是项目单一协议真源。
本项目的"CLI"是受限命令行工具，不是通用 bash/shell 执行能力。

3. Confirmed External Facts

3.1 AgentScope 对 Skills 的官方支持

已确认的外部事实：

AgentScope 官方 README 明确写有 built-in support for skills
官方示例 examples/functionality/agent_skill/main.py 使用：
- toolkit.register_agent_skill(...)
官方示例同时说明：
- 使用 agent skill 时，agent 需要具备查看文本文件等基础工具能力
- skill 目录通过 SKILL.md 进行渐进式披露

已确认的 skill 示例结构：

SKILL.md 包含 frontmatter：name、description
skill 内容描述：
- 适用场景
- 推荐工作流
- 需要执行的脚本/命令
- 何时读取补充材料

结论：本项目不应绕开 AgentScope skill 能力自行设计一套"伪 skill"机制。

3.2 AgentScope 工具协议的确认边界

已确认的 AgentScope 工具使用方式：

Toolkit.register_tool_function(...) 注册 callable function
tool 返回 ToolResponse
ToolResponse.content 可承载 TextBlock
toolkit 支持 preset_kwargs

这意味着如果本项目改成 CLI 路径，落点应是：

对 agent 来说，固定暴露为单一 AgentScope tool：project_cli
对 tool 的内部实现来说，它可以调用 CLI
CLI 的输入输出要能被稳定转换为 AgentScope ToolResponse

4. Confirmed Repository Facts

4.1 当前工具执行方式

当前项目仍然是 Python 函数直接注册多个工具：

backend/src/core/agentscope/tools/toolkit.py
- TOOL_FUNCTIONS 直接绑定：
  - calendar_read
  - calendar_write
  - calendar_share
  - user_lookup
  - memory_write
  - memory_forget
- build_toolkit() 通过 toolkit.register_tool_function(...) 注册这些函数
backend/src/core/agentscope/tools/tool_config.py
- 现统一使用 enabled_skills（calendar|contacts|memory）做能力白名单
backend/src/core/agentscope/runtime/runner.py
- _build_toolkit() 根据 enabled_skills 选择技能白名单

结论：当前实现尚未接入 AgentScope skill，也尚未接入 CLI 工具边界。

4.2 当前项目中的认证边界

当前项目已有明确的 Bearer token 用户解析路径：

backend/src/v1/users/dependencies.py
- get_current_user() 从 Authorization: Bearer <token> 解析 token
- 先走 JWT verifier，再 fallback 到 Supabase user lookup
- 最终产出 CurrentUser
backend/src/core/auth/models.py
- CurrentUser 当前字段：id、phone、role

结论：如果工具改为 CLI，runtime 的合理边界应是 token 或 auth credential，而不是 DB session / owner_id。token 默认通过受控环境变量注入 CLI 运行环境，CLI 内部再根据 token 推导用户身份和数据访问上下文。

补充约束：

不能仅凭 owner_id 直接构造用户 Bearer token；owner_id 不是签名凭证。
automation 场景由当前 Bearer token 的签发方负责基于 automation_jobs.owner_id 签发短期受控凭证；若现有签发链路不支持，则补一个服务端签发函数。
当前假设该签发方与用户登录 Bearer token 的签发体系一致；现有若仅支持"邮箱 + 验证码"登录签发，则在同一信任边界下新增 automation 凭证签发能力。
automation 受控凭证生命周期目标为 5-10 分钟，只覆盖 agent 调用工具所需窗口。
该凭证的签发方式、有效期、权限边界和审计规则必须在协议文档中写清。

4.3 当前 worker output 与 UI 路径

当前 worker output 仍然包含 UI 描述：

backend/src/schemas/agent/runtime_models.py
- WorkerAgentOutputRich.ui_hints

当前 runtime 会把 ui_hints 带入最终文本事件：

backend/src/core/agentscope/runtime/stage_emitter.py
- emit_final_text_end() 将 ui_hints 写入 payload

当前对外 AG-UI payload 会把 ui_hints 编译为 ui_schema：

backend/src/core/agentscope/events/agui_codec.py
- TEXT_MESSAGE_END 上执行 compile_ui_hints(...)

当前 history 回放同样依赖 ui_hints -> ui_schema：

backend/src/v1/agent/utils.py
backend/src/v1/agent/schemas.py

结论：当前 ui_schema 的真源是 worker 自身输出的 ui_hints。本次改造将把 ui_hints 的来源从 worker output 改为 tool output，ui_hints → ui_schema 的编译链路保持不变。

4.4 当前前端消费方式

前端当前消费的是后端下发的编译后 ui_schema：

apps/lib/core/chat/ag_ui_event.dart
apps/lib/core/chat/chat_history_repository.dart
apps/lib/shared/widgets/ui_schema/ui_schema_renderer.dart
apps/lib/features/home/presentation/widgets/home_chat_item_renderer.dart

结论：前端目前理解的是后端已编译好的 ui_schema。本次改造目标不是改变前端消费方式，而是改变 ui_hints 的来源（从 worker 改为 tool），ui_hints → ui_schema 编译链路保持不变。

4.5 当前 tool result 结构

当前 tool result 已经走 machine-oriented 路线，但结构还不完整：

backend/src/core/agentscope/tools/utils/tool_response_builder.py
- tool 最终返回 ToolResponse
- 当前 ToolResponse 中仍混入完整 tool 结构，不符合目标边界
backend/src/core/agentscope/utils/parsing.py
- 从 ToolResponse text block 中恢复 ToolAgentOutput
backend/src/core/agentscope/runtime/stage_emitter.py
- TOOL_CALL_RESULT payload 包含 tool_name、tool_call_args、status、result

当前仓库已经存在"给 agent 的文本内容"和"给事件/持久化的完整结构化对象"分离的模式：

backend/src/core/agentscope/events/store.py
- tool 消息持久化时：content = tool_output.result
- 完整结构化对象进入 metadata.tool_agent_output
backend/tests/unit/core/agentscope/events/test_store.py
- 明确校验 tool message content 等于文本结果
- 同时完整 tool_agent_output 保存在 metadata 中

结论：当前仓库已经证明一个正确的职责分层：

worker/上下文消费的应是 tool message content
AG-UI 事件、持久化和前端渲染可以保留完整 ToolAgentOutput

但当前仍有三个缺口：

ToolAgentOutput 还没有承载前端所需 ui_hints
ToolAgentOutput.result 仍是字符串，还没有升级为结构化对象字段
ToolResponse 还没有收敛为只承载 result 文本投影，再交给 tool 后处理器生成完整 ToolAgentOutput

此外，history/replay 的正确恢复方向也已经比较明确：

可以像 worker output 一样，从 message.metadata 中恢复结构化对象
对 tool 来说，恢复源应是 metadata.tool_agent_output.ui_hints

5. Problem Statement

当前实现存在 5 个核心问题：

工具实现直接耦合在 Python runtime 函数注册层，缺少独立协议边界。
skill 尚未成为 agent 的原生能力入口，工具知识仍主要依赖 prompt 和函数 docstring。
worker 仍承担 UI 描述职责，导致 ui_hints 占 token，且与前后端实现容易漂移。
tool result 已经拥有独立结构化对象，但没有成为 UI 渲染主路径。
当前 tool output 协议没有明确区分"给 worker 推理的 content"和"给前端渲染的完整结构化输出"。
当前 CLI 工具边界尚未定义为受限命令行工具，容易和通用 shell 执行概念混淆。

6. Target Architecture

6.1 总体方向

目标架构应遵循下面的职责分层：

AgentScope skill
- 负责告诉 agent：
  - 有哪些工具能力
  - 什么时候调用
  - 调用前后如何决策
- 不直接承担业务执行
AgentScope tool
- agent 固定只看到一个工具入口：project_cli
- 内部执行方式为结构化 command + subcommand + args -> 调用项目 CLI -> 适配回 ToolResponse
CLI tool
- 是业务执行边界
- 输入输出必须稳定、结构化、可验证
- 采用经典命令树：command + subcommand + args
- 不按 skill + action 建模 CLI
- 必须符合 AgentScope 工具协议适配需要
- 必须是受限项目命令行工具，不提供通用 bash/shell 能力
Tool output protocol
- 保留独立的 ToolAgentOutput 类协议对象
- 对 AG-UI 事件、持久化元数据、前端渲染负责
- 可包含 ui_hints 这类前端渲染字段
UI contract
- 由 tool output 中的 ui_hints 编译生成 ui_schema
- ui_schema 成为前端渲染的输入
- worker output 不再输出 ui_hints

6.2 Token / 受控凭证作为 runtime 注入参数

本项目要求将 Bearer token 或受控服务端凭证作为 tool runtime 注入参数，而不是 DB 级参数。

目标边界：

AgentScope tool 被调用时，runtime 将认证 token 或受控服务端凭证注入 CLI 执行环境
CLI 接收到 token 后：
- 验证 token
- 解析用户身份
- 推导可访问数据范围
- 再进入 service / repository / DB 层

禁止继续扩大的错误边界：

不应把 AsyncSession 直接暴露到 CLI 工具调用边界
不应把 owner_id 当作唯一可信的输入
不应让 agent 直接控制数据库上下文对象

当前优先方案：

token 不作为模型可见的业务参数字段进入 tool args schema
token 由 runtime 以默认环境变量方式注入到 CLI 子进程
CLI 只读取受控环境变量，不从自然语言或 tool args 中接受任意 token 字符串
automation 不直接伪造用户 Bearer token；由当前 token 签发方基于 automation_jobs.owner_id 获取或签发 5-10 分钟短期受控凭证后注入

6.3 ToolResponse 与 ToolAgentOutput 的边界

本次协议边界明确如下：

CLI/Tool 原始执行结果先产出结构化 result
AgentScope ToolResponse 只承载给 agent 使用的 result 文本投影
不再把完整 ToolAgentOutput 直接塞进 ToolResponse.content
runtime 内增加 tool 后处理器：基于 result 解析/补全完整 ToolAgentOutput
该后处理器负责补齐：
- tool_name
- tool_call_id
- tool_call_args
- status
- result
- error
- ui_hints

这样职责分层固定为：

agent 只看到 message.content / ToolResponse 中的 result 文本投影
runtime / SSE / history / persistence 使用完整 ToolAgentOutput

6.4 Worker 与 Tool 输出职责分离

根据当前仓库已存在的运行时与持久化逻辑，本次重构必须明确保持以下分层：

worker output
- 面向 worker 最终回答
- 不再包含 ui_hints
tool output
- 使用 ToolAgentOutput 作为结构化协议对象
- 面向 AG-UI 事件、历史持久化、前端渲染
- 可以包含 ui_hints
tool message content
- 面向 agent ReAct loop 上下文
- 应是工具结构化结果的稳定文本投影
- 不应把完整 ToolAgentOutput 字段直接作为下一轮 worker 输入上下文

当前仓库中的支持证据：

backend/src/core/agentscope/events/store.py
- tool message content = tool_output.result
- metadata 保留完整 tool_agent_output

因此正确方向不是删除 ToolAgentOutput，而是：

保留 ToolAgentOutput 作为独立 tool 协议对象
只让 worker 主要消费 tool message content

6.4 `message.content` 字段策略

本次不建议把 message.content 从文本改成通用 schema 字段。

原因：

AgentScope/Msg 本身是通用消息抽象，不同 role 的 content 类型已经存在差异，但当前项目的 worker 推理、历史持久化、事件处理都默认把文本内容当作主信息载体。
当前仓库已经有一条可工作的分层：

message.content 给 worker 推理
metadata.tool_agent_output 给结构化消费

若把 message.content 直接升级为 schema，会把：
- ReAct loop
- memory/context assembly
- event store
- history replay
- frontend parsing 一起拉进大范围协议改动，收益不成比例。

因此推荐策略是：

message.content 继续保持文本
文本内容由 ToolAgentOutput.result 结构化对象稳定投影生成
结构化真源放在 ToolAgentOutput.result

也就是说，后续语义应变成：

message.content: 给 worker 的完整 JSON 文本投影
ToolAgentOutput.result: 给系统使用的结构化对象真源

6.5 UI 真源迁移方向

本次改造的目标不是"前端直接裸渲染任意 CLI 参数 schema"，而是：

先把 tool output 协议收敛为稳定的结构化 schema
在 tool output 协议中保留前端所需 ui_hints
再从该协议导出 AG-UI / history / frontend 统一 contract
AG-UI 传输时：后端 codec 将 ui_hints 编译为 ui_schema 后传输
前端渲染 ui_schema（复用现有 UiSchemaRenderer）

关键设计决策：

ui_hints 是 tool 输出的描述性 UI 表示（真源）
ui_schema 是编译后的渲染性 UI 表示（传输格式）
编译链路 ui_hints → ui_schema 保持不变，仅改变 ui_hints 的来源
前端继续使用现有 UiSchemaRenderer 渲染 ui_schema

因此本次必须避免两个错误方向：

继续保留 worker -> ui_hints -> ui_schema（应改为 tool -> ui_hints -> ui_schema）
让前端直接绑定 ui_hints 而不是 ui_schema
把完整 ToolAgentOutput 直接塞回 worker 推理输入，而不是让 worker 主要消费 tool message content
把"项目 CLI"实现成可执行任意 shell 的通用命令入口

7. Required Refactor Requirements

7.1 Skill 接入要求

必须：

基于 AgentScope 原生 register_agent_skill(...) 接入 skill
提供项目内 skill 目录与 SKILL.md
skill 内容必须包含：
- 工具能力说明
- 何时调用哪个工具
- 参数构造规则
- 组合调用规则
- 失败后的恢复策略

不允许：

用单纯 prompt 文本替代 skill
自定义一套与 AgentScope skill 不兼容的 skill 机制

7.2 CLI Tool Protocol 要求

CLI 工具必须满足：

能被 AgentScope tool wrapper 稳定调用
输入参数可从当前 AgentScope tool schema 映射得到
输出结果可稳定映射回 ToolResponse
输出至少包含：
- 状态
- 结构化结果
- 错误信息
- 前端渲染所需的稳定字段

CLI 输出在进入 AgentScope tool wrapper 后，最终需要映射成两层信息：

message.content
- 给 worker ReAct loop 使用
- 应为结构化 result 的稳定文本投影
- 由结构化 result 稳定投影生成
- 默认保留完整 JSON 文本投影，不做阉割式摘要裁剪
ToolAgentOutput
- 给 AG-UI 事件、持久化、前端渲染使用
- 至少包含 tool_name、tool_call_id、tool_call_args、status、result、error
- 本次应扩展支持 ui_hints

这里的实现约束已经确定：

ToolResponse 只返回 result 文本投影
完整 ToolAgentOutput 由 tool 后处理器在 runtime 内生成
ui_hints 由 tool 后处理器生成并写入 ToolAgentOutput
ui_hints 经后端 codec 编译为 ui_schema 后传输给前端
worker 不参与 tool UI 生成

需要显式设计：

stdin / argv / env 何者承载输入
token 放在哪个输入通道
stdout 返回 JSON 的格式
非 0 exit code 的错误语义

当前已确认的输入通道策略：

CLI 输入通道采用"两者结合"
默认以 argv 为主、stdin 为辅
token 继续通过受控环境变量注入，不进入模型可控参数

7.3 Tool Configuration 保留要求

以下配置能力必须保留：

enabled_skills from system agents config
enabled_skills from automation jobs config

允许变化的部分：

enabled_skills 不再映射到 Python 函数名
改为映射到 CLI-backed tool capability

7.4 Worker Output 精简要求

worker output 必须移除：

ui_hints

worker output 保留：

status
answer
suggested_actions
error

是否增加新的结构化字段，必须以协议文档先定义为前提；禁止再次引入新的"隐式 UI 描述字段"。

7.5 Tool Output 协议重构要求

ToolAgentOutput 不应被删除，而应被重构为更完整的 tool 协议对象。

至少应满足：

保留当前已有字段：
- tool_name
- tool_call_id
- tool_call_args
- status
- result
- error
扩展支持：
- ui_hints

其中 result 应升级为结构化对象字段，不再以字符串为真源。

同时需要新增一条投影规则：

从结构化 result 生成稳定文本投影，写入 tool message content
默认使用完整 JSON 投影，保持与 result 信息量一致，避免因摘要裁剪削弱模型对结构化数据的读取能力

同时需要固定 tool 后处理规则：

后处理器以 tool 原始 result 为真源
根据 result 解析/补齐 ToolAgentOutput
ui_hints 由后处理器生成并写入 ToolAgentOutput
worker 不参与 tool UI 生成

这样可以满足两条不同消费链路：

worker 继续消费由 result 投影生成的 message.content
AG-UI / history / frontend 消费完整 ToolAgentOutput

7.6 UI Contract 重构要求

必须完成：

TEXT_MESSAGE_END 不再依赖 worker ui_hints 编译
history assistant message 不再依赖 metadata.agent_output.ui_hints 编译
tool result 成为 UI 合约的主要输入之一
TOOL_CALL_RESULT / tool metadata / history replay 能保留 tool ui_hints

AG-UI 传递策略调整为：

tool 事件内部携带 ui_hints
后端 codec 将 ui_hints 编译为 ui_schema
AG-UI 对前端传输 ui_schema
前端继续复用现有 UI 渲染器渲染 ui_schema
history 恢复时优先从 message.metadata.tool_agent_output.ui_hints 读取并编译为 ui_schema 后渲染

这里的设计结论已经确定：

ui_hints 是 tool 输出的 UI 描述（真源）
ui_schema 是编译后的渲染格式（传输格式）
编译链路 ui_hints → ui_schema 保持不变
前端继续使用现有 UiSchemaRenderer 渲染 ui_schema

8. Scope Of Changes

8.1 Protocol Docs

必须更新：

docs/protocols/ui/ui-schema.md
docs/protocols/ui/data-flow.md
docs/protocols/agent/sse-events.md
docs/protocols/agent/run-agent-input.md
docs/protocols/agent/api-endpoints.md

建议新增：

一个工具协议文档，明确：
- CLI 输入输出约定
- token preset 约定
- tool result 到 UI contract 的映射边界

8.2 Backend

主要改动点：

backend/src/core/agentscope/tools/toolkit.py
backend/src/core/agentscope/tools/tool_config.py
backend/src/core/agentscope/runtime/runner.py
backend/src/core/agentscope/runtime/stage_emitter.py
backend/src/core/agentscope/events/agui_codec.py
backend/src/core/agentscope/events/store.py
backend/src/core/agentscope/runtime/tasks.py
backend/src/core/agentscope/utils/parsing.py
backend/src/schemas/agent/runtime_models.py
backend/src/v1/agent/utils.py
backend/src/v1/agent/schemas.py
新增 skill 资产与 CLI adapter
新增 Python console entrypoint 与内嵌 command router

skill 资产目录精确落点：

backend/src/core/agentscope/tools/custom

skill 部署方式：

参考 AgentScope skill 提供的原生装载/注册方法进入运行时与部署产物
现有 custom/*.py 不再保留为最终工具实现，后续由 CLI handler / router 重写替换

8.3 Cleanup / 收尾清理

本次改造完成后，必须明确收尾清理以下代码与路径，避免旧协议残留：

删除或下线 worker ui_hints 主路径
- backend/src/schemas/agent/runtime_models.py 中 worker rich output 的旧定义
- backend/src/core/agentscope/runtime/stage_emitter.py 中向 TEXT_MESSAGE_END 写入 worker ui_hints 的逻辑
- backend/src/core/agentscope/events/agui_codec.py 中 TEXT_MESSAGE_END 的 compile_ui_hints(...) 主路径
- backend/src/v1/agent/utils.py 中 assistant history 读取 worker ui_hints 并编译的逻辑
清理旧文档语义
- docs/protocols/ui/data-flow.md 中"worker ui_hints 是 UI 真源"的描述
- docs/protocols/ui/ui-schema.md 中把 UI compiler 绑定到 worker ui_hints 的描述
- docs/protocols/agent/sse-events.md / api-endpoints.md / run-agent-input.md 中与旧 worker UI 路径冲突的描述
清理测试中的旧假设
- 依赖 worker ui_hints 的 runtime/event/history 单测
- 依赖 ToolAgentOutput.result 为字符串真源的测试
清理旧前端假设
- 只接受 assistant ui_schema 而不理解 tool ui_schema 的渲染逻辑
- 历史/事件解析中把 assistant UI 当唯一 UI 来源的路径
清理旧工具调用边界
- 继续把 Python runtime 函数当作唯一稳定工具边界的 registry 代码
- 任何会把 DB session / owner_id 直接注入到 CLI 边界的适配代码
- 旧 custom/*.py 直接工具实现
清理第二条 runtime 冷路径
- backend/src/core/agentscope/runtime/tasks.py 中与新 tool output/context rebuild 不一致的旧序列化路径
- 所有会导致热路径、冷路径看到不同 tool 上下文的兼容逻辑

8.4 Frontend