VeloxDev.Core.Extension 4.3.0

VeloxDev.Core.Extension

VeloxDev.Core.Extension 为 VeloxDev.Core 提供以下扩展能力：

• 通用 Agent 工具集（AgentObjectToolkit）：将任意 .NET 对象包装为 10 个 MAF AITool（属性读写、命令执行、方法调用），不限于工作流——适用于所有 .NET 项目。
• ViewModel JSON 序列化：基于 Newtonsoft.Json 的序列化/反序列化，保留运行时类型、处理对象引用并支持复杂字典。
• Workflow Agent 语义上下文：面向 Agent 的 Workflow 结构化文档（枚举、接口、组件），含预加载上下文机制。
• Workflow Agent 运行时接管（MAF Functions）：基于 Microsoft Agent Framework 的完整工具集（30+ 个 AITool），让 Agent 在单个 Tree 内自由查询、修改、连接、执行、克隆工作流组件；包含类型自省、JSON Patch、状态快照、批量操作等。

与 Core 的关系：Extension 中的反射操作（属性读写、命令发现执行、类型解析、上下文读取）委托给 VeloxDev.Core.AI 中的通用工具类。Extension 负责添加 JSON 序列化和 MAF AITool 封装。

目录

• 0) 通用 Agent 工具集（AgentObjectToolkit）
• 1) ViewModel JSON 序列化
• 2) Workflow Agent 架构与原理
• 3) 快速上手
• 4) Scope 配置 API
• 5) Prompt 系统
• 6) 完整 AITool 列表
• 7) 安全机制
• 8) 协议对象

0) 通用 Agent 工具集（AgentObjectToolkit）

AgentObjectToolkit 将 任意 .NET 对象 包装为 10 个 MAF AITool，使 Agent 可以通过 Function Calling 读写属性、执行命令、调用方法——不限于工作流组件。

快速使用

// 一行代码：把任何对象变成 Agent 工具集
var tools = myViewModel.AsAgentTools(AgentLanguages.Chinese);

// 或者带属性黑名单
var rejected = new HashSet<string> { "Parent", "InternalState" };
var tools = myViewModel.AsAgentTools(AgentLanguages.Chinese, rejected);

// 传入 Agent
var agent = client.AsAIAgent(
    instructions: "你是一个操作组件的助手。",
    tools: tools);

生成的 10 个工具

与 WorkflowAgentToolkit 的区别

1) ViewModel JSON 序列化

// 同步
var json = workflow.Serialize();
if (json.TryDeserialize<MyWorkflowTree>(out var tree)) { /* use */ }

// 异步
var jsonAsync = await workflow.SerializeAsync();
var (ok, tree2) = await jsonAsync.TryDeserializeAsync<MyWorkflowTree>();

// 流式
await using var ws = File.Create("wf.json");
await workflow.SerializeToStreamAsync(ws);

2) Workflow Agent 架构与原理

总体架构

VeloxDev.Core.AI (通用反射基础设施，零依赖)
  AgentPropertyAccessor / AgentMethodInvoker / AgentCommandDiscoverer
  AgentContextReader / AgentTypeResolver
  [AgentContext] / [AgentCommandParameter] 特性
        │
        ▼
IWorkflowTreeViewModel (业务层工作流)
        │
        ▼
 WorkflowAgentScope          ← 域：绑定一棵 Tree + 注册自定义类型
        │
        ├─► ProvideAllContexts()          → 完整语义 Prompt（框架+用户组件文档）
        ├─► ProvideProgressiveContextPrompt()  → 渐进式 Prompt（预加载组件描述 + 按需查询）
        │
        └─► ProvideTools() ──► WorkflowAgentToolkit
                                     │
                                     └─► 30+ 个 AITool（MAF Function Calling）
                                              │
                                              ▼
                                     ChatClientAgent / IChatClient

设计原则

1. Scope 隔离：每个 WorkflowAgentScope 绑定一棵 IWorkflowTreeViewModel，Agent 只能操作该 Tree 内的组件。
2. 命令优先（Command-First）：所有对工作流的变更必须通过 IVeloxCommand 管道执行，不可直接修改属性。命令负责 UI 线程调度、撤销/重做追踪与视图同步。
3. 渐进式上下文与预加载：支持两种 Prompt 策略——完整上下文（ProvideAllContexts）适合短任务，渐进上下文（ProvideProgressiveContextPrompt）将所有注册组件的 [AgentContext] 类级描述（含默认尺寸、属性语义等）直接嵌入 Prompt，Agent 从第一轮对话就拥有完整的组件知识，无需额外工具调用。对于详细属性表和命令参数，Agent 按需调用 GetComponentContext。
4. Token 压缩：所有 JSON 输出使用 Formatting.None，键名缩写（i/t/x/y/w/h），列表与详情分离。
5. ID 稳定性：通过 IWorkflowIdentifiable.RuntimeId 提供稳定标识，不因节点增删导致索引漂移。支持按索引和按 ID 两种寻址方式。
6. 三层安全保护：ComponentPatcher 拒绝修改框架管理属性、命令支撑属性和 Source Generator 管理的 Slot 属性。

核心组件

Core AI 基础设施（由 Extension 委托使用）

3) 快速上手

// 1. 创建 Scope：以一棵 Tree 作为 Agent 的操作域
var scope = tree.AsAgentScope()
    .WithComponents(AgentLanguages.English,
        typeof(NodeViewModel),
        typeof(ControllerViewModel),
        typeof(SlotViewModel),
        typeof(LinkViewModel),
        typeof(TreeViewModel))
    .WithEnums(AgentLanguages.English)
    .WithInterfaces(AgentLanguages.English);

// 2. 生成 Prompt（框架 + 自定义组件的结构化上下文）
var contextPrompt = scope.ProvideAllContexts(AgentLanguages.English);

// 3. 生成 MAF 工具集
var tools = scope.ProvideTools();

// 4. 传入 Agent
var agent = chatClient.AsAIAgent(
    instructions: contextPrompt,
    tools: tools);

var session = await agent.CreateSessionAsync();

完整示例参见 Examples/Workflow/Common/Lib/ViewModels/Workflow/Helper/AgentHelper.cs

4) Scope 配置 API

5) Prompt 系统

ProvideAllContexts（完整上下文）

生成完整的系统 Prompt，包含：

• ⚠️ 命令优先规则
• 🚫 禁止操作列表（框架管理属性 + Source Generator 管理的 Slot 属性）
• 框架类型文档（枚举、接口、基类的属性/方法/命令说明）
• 用户自定义组件文档

适用于：短任务、简单对话、Token 预算充足的场景。

ProvideProgressiveContextPrompt（渐进式上下文）

生成精简但信息完备的系统 Prompt，包含：

• 命令优先规则 + 禁止操作
• Token 节省技巧（BatchExecute、快照 Diff、列表/详情分离）
• 框架行为说明（删除级联、节点尺寸由视图决定）
• 📌 默认值解析协议：明确优先级——[AgentContext] 开发者指令 > GetComponentContext 完整属性表 > ❌ 永远不从运行时状态猜测
• 节点创建协议：从预加载的描述中提取默认尺寸，用户指令覆盖默认值
• 📋 预加载组件描述：所有注册的 Customer 组件的类级 [AgentContext]（含默认尺寸、属性语义）和带 [AgentContext] 标注的属性列表直接嵌入 Prompt
• 已注册的类型名列表（Agent 按需调用 GetComponentContext 查询完整属性表和命令参数）

适用于：长对话、复杂任务、Token 预算紧张的场景。Agent 从第一轮对话就知道每个组件的默认值和属性含义。

6) 完整 AITool 列表

📖 查询（Query）

🔍 渐进式上下文（Progressive Context）

📸 状态追踪（State Tracking / Diff）

✏️ 变更（Mutation）

⚡ 通用命令执行（Generic Command）

📦 批量操作（Batch）

🔀 克隆（Clone）

7) 安全机制

ComponentPatcher 实现三层防护，确保 Agent 不会破坏框架内部状态：

第一层：框架管理属性黑名单

以下属性被无条件拒绝修改：

第二层：命令支撑属性检测

如果某个属性存在同名的 IVeloxCommand（例如属性 Anchor 对应 SetAnchorCommand），则 Patch 被拒绝，Agent 必须使用对应的工具（如 SetNodePosition）。

第三层：Source Generator Slot 属性拒绝

如果属性类型实现了 IWorkflowSlotViewModel（例如 InputSlot、OutputSlot），则 Patch 被拒绝。这些 Slot 由 Source Generator 通过懒初始化 + CreateSlotCommand 自动创建和管理。

8) 协议对象

每个操作都有对应的可观察协议对象（INotifyPropertyChanged），可用于 UI 绑定或序列化：

using VeloxDev.AI.Workflow.Protocols;

var protocol = new MoveNodeProtocol { NodeIndex = 0, OffsetX = 100, OffsetY = -50 };
var json = protocol.Serialize(); // 使用 ComponentModelEx 序列化

协议类型包括：MoveNodeProtocol、SetNodePositionProtocol、ResizeNodeProtocol、DeleteNodeProtocol、ConnectSlotsProtocol、DisconnectSlotsProtocol、ExecuteWorkProtocol、PatchPropertiesProtocol、GetTypeSchemaProtocol、ExecuteCommandProtocol、ExecuteCommandByIdProtocol、CreateNodeProtocol、CreateSlotProtocol。