.NET 诊断技巧 | 日志框架原理、手写日志框架学习炼
一、 什么是 AI Skills：从工具级到框架级的演化
AI Skills（AI 技能） 的概念最早在 Claude Code 等前沿 Agent 实践中被强化。最初，Skills 被视为“工具级”的增强，如简单的文件读写或终端操作，方便用户快速实现各种操作。
然而，在以 Solon AI 为代表的现代应用开发框架中，AI Skills 已演化为一种更高维度的封装，用于智能体应用开发。
工具级（Tool-level）：解决的是“手”的问题，是具体的执行函数。
框架级（Framework-level）：解决的是“脑”的问题。它是工具（Tools）、指令（Instruction）与元数据（Metadata）的聚合体。它不仅包含执行逻辑，还包含了准入检查、指令增强及工具染色能力。
二、 AI Skills 应有的核心特性
为了解决传统 Tool 模式下的上下文噪音、权限真空和行为失控，一个成熟的 AI Skill 必须具备以下特质：
智能准入（isSupported）： 只有满足特定意图、租户或环境条件时（可称为提示词上下文），技能才会被激活。避免无效工具对模型上下文的干扰，和 Token 浪费。
指令注入（getInstruction）： 根据当前上下文为模型提供“行为准则”，解决模型“该怎么做”的问题。
工具路由（getTools）： 根据当前上下文动态分发工具
高度自治： 技能内部闭环处理特定领域的逻辑，对外部输出标准化的结果。
三、 MCP：AI 时代的万维网协议
随着技能需求的爆发，MCP（Model Context Protocol，模型上下文协议） 应运而生。它是连接 AI 模型与外部数据/工具的标准协议。
MCP 之于 AI，正如 HTTP 之于万维网。
在互联网时代，HTTP 协议让任何浏览器都能访问任何服务器上的资源；在 AI 时代，MCP 协议让任何智能体都能无缝调用分布在不同物理位置、由不同厂商提供的技能。这种标准化彻底打破了“智能体”与“外部世界”之间的硬编码枷锁。
四、 Tool 的分布式进化：MCP Tool 的诞生
Tool 的形态正在经历本质的变化：从本地单体进化为 MCP Tool（分布式 Tool）。它具有物理位置透明性，不再是内存中的一个函数，而是一个个独立的分布式能力节点。这种“能力节点化”是 AI 走向微服务架构的第一步。
传统 Tool： 代码级耦合，运行在 Agent 进程内部，难以跨语言、跨环境复用。
MCP Tool（分布式 Tool）： 通过 MCP 协议暴露，具有物理位置透明性。它不再是内存中的一个函数，而是一个个独立的分布式能力节点。
五、 架构映射：从分布式的 MCP Tool 到 MCP Skills
Tool 的分布式化为 AI Skills 的分布式化提供了自然的路径参考。当我们将一组具备业务逻辑、指令指导和工具集的 Skill 借助 MCP 协议进行发布时，它便进化成了 MCP Skills。
我们可以将 AI Agent 的分布式蓝图清晰地映射为传统架构：
MCP 相当于 RPC（远程过程调用）： 它定义了模型与能力节点之间如何通信，是智能体世界的底座管道。
MCP Skills 相当于微服务（Microservices）： 每个 Skill 就是一个独立的、具备业务语义的业务单元。
题外之话：Distributed AI Skills，也可以借助传统 RPC 体系实现（做的工作会更多些）。
六、 如何实现 MCP Skills：Client 与 Server 的协同？
实现 MCP Skills 的核心在于将 Skill 的生命周期语义映射到 MCP 协议的端点上。
1. McpSkillClient（远程技能的本地代理）
McpSkillClient 作为本地代理，其职责是与远程服务握手，并将网络调用包装成 Skill 接口。
感知元数据：通过约定路径同步远程元数据。
动态映射：在运行时，将本地的 isSupported 或 getInstruction 调用转化为远程 MCP Tool 调用。
工具过滤：自动剔除标记为 hide 的管理类工具，只给 LLM 呈现此时该看的业务工具。
应用示例：
// 1. 构建 MCP 客户端提供者（负责协议通信与 Schema 缓存）
McpClientProvider mcpClient = McpClientProvider.builder()
.channel(McpChannel.STREAMABLE)
.url("http://localhost:8081/skill/order")
.build();
// 2. 将 MCP 客户端进化为 Skill 代理
McpSkillClient skillClient = new McpSkillClient(mcpClient);
// 3. 构建带有业务上下文的 Prompt
Prompt prompt = Prompt.of("这个订单：A001，请查询订单详情。")
.attrPut("tenant_id", "1") // 注入租户上下文
.attrPut("user_role", "admin"); // 注入角色权限
// 4. 调用大模型，技能将根据 Prompt 自动完成：远程准入、指令获取、工具过滤
chatModel.prompt(prompt)
.options(o -> o.skillAdd(skillClient))
.call();
2. McpSkillServer（具备感知的技能服务端）
通过继承 McpSkillServer，开发者可以将本地业务逻辑导出为远程技能。
生命周期暴露：利用 @ToolMapping 和 @ResourceMapping 将 isSupported、getInstruction 等逻辑导出。
智能感知：服务端能通过传入的 Prompt 状态感知意图。例如，根据角色权限决定 getToolsName 返回哪些工具。
安全标记：通过给管理端点添加 hide:1 标记，确保系统级指令不会泄露给模型。
应用示例：
@McpServerEndpoint(channel = McpChannel.STREAMABLE_STATELESS, mcpEndpoint = "/skill/order")
public class OrderManagerSkillServer extends McpSkillServer {
@Override
public String description() {
return "提供订单查询与取消的专业技能";
}
//智能准入：根据 Prompt 内容与属性决定是否响应
@Override
public boolean isSupported(Prompt prompt) {
// 语义检查：意图是否相关
boolean isOrderTask = prompt.getUserContent().contains("订单");
// 安全检查：必须有租户 ID
boolean hasTenant = prompt.attr("tenant_id") != null;
return isOrderTask && hasTenant;
}
//动态指令：根据上下文为大模型注入实时“行为准则”
@Override
public String getInstruction(Prompt prompt) {
String tenantName = prompt.attrOrDefault("tenant_name", "未知租户");
return "你现在是[" + tenantName + "]的订单主管。请只处理该租户下的订单数据，禁止跨租户查询。";
}
//挂载钩子：技能被激活时触发，可用于注入初始化消息或记录日志
@Override
public void onAttach(Prompt prompt) {
// 可以在此处通过 prompt.addMessage() 注入 Few-shot 或背景知识
System.out.println("订单技能已挂载，当前租户：" + prompt.attr("tenant_id"));
}
/**
* 动态能力发现：根据用户权限决定暴露哪些工具
* @return null 表示暴露所有业务工具；Empty 表示禁用所有工具；List 表示精准暴露。
*/
@Override
public List getToolsName(Prompt prompt) {
List tools = new ArrayList<>();
// 基础权限：所有合规用户可见
tools.add("OrderQueryTool");
// 细粒度权限：仅 ADMIN 角色可见“取消订单”工具
if ("ADMIN".equals(prompt.attr("user_role"))) {
tools.add("OrderCancelTool");
}
return tools;
}
@ToolMapping(description = "根据订单号查询详情")
public String OrderQueryTool(String orderId) {
return "订单 " + orderId + " 状态：已发货";
}
@ToolMapping(description = "取消指定订单")
public String OrderCancelTool(String orderId) {
return "订单 " + orderId + " 已成功取消";
}
}
七、 必然性总结
AI Skills 走分布式道路是不可逆转的：
解耦与复用： 复杂技能（如法律审计、专业代码重构）不再需要在每个项目中重写，而是作为服务独立存在。
安全边界： 敏感数据处理技能可以部署在专用的、受保护的内网环境中，仅通过受控的 MCP 协议与公网 Agent 通信。
异构生态： 不同语言、不同算力环境下的能力，都可以通过统一的 MCP 接口连接，形成一个真正的“智能体微服务网络”。上补繁靖