Agent 上下文注入原理与 Web 架构映射实战

2.3 上下文生命周期类比

SessionStore -> ToolInterceptor -> Controller -> 用户 SessionStore -> ToolInterceptor -> Controller -> 用户 "查询订单" preHandle() load(sessionId) 上下文快照 绑定 ThreadLocal proceed(execute(request)) AgentContext.current() 读取/修改上下文 响应结果 afterCompletion() save(context) 清理 ThreadLocal

关键设计原则：

• 线程绑定 = ThreadLocal + try-finally 保障
• 状态持久化 = Redis Session 存储 + TTL 自动清理
• 链路透传 = Trace ID + MDC 日志集成

3. 跨服务上下文传递实战

3.1 微服务间透传方案 (Feign 拦截器)

/**
 * Feign 上下文拦截器 (类比 OpenFeign RequestInterceptor)
 */
@Component
public class ContextFeignInterceptor implements RequestInterceptor {
    @Override
    public void apply(RequestTemplate template) {
        if (AgentContext.isContextActive()) {
            AgentContext context = AgentContext.current();

            // 1. 注入关键标识 (最小化传输)
            template.header("X-Context-Session", context.getSessionId());
            template.header("X-Trace-Id", context.getAttribute("traceId", String.class));

            // 2. 安全敏感数据处理 (类比 JWT Claims)
            ContextSnapshot snapshot = context.snapshot(Set.of("userId", "tenantId", "role")); // 仅传递必要字段
            template.header("X-Context-Token", encrypt(snapshot));
        }
    }

    private String encrypt(ContextSnapshot snapshot) {
        // 使用 AES 加密 (类比 JWT 签名)
        return AesUtils.encrypt(JSON.toJSONString(snapshot), secretKey);
    }
}

/**
 * 服务提供方上下文重建 (类比 Spring Cloud Gateway)
 */
@Component
public class ContextFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;

        // 1. 从 Header 重建上下文
        String token = httpRequest.getHeader("X-Context-Token");
        if (token != null) {
            ContextSnapshot snapshot = decrypt(token);
            AgentContext context = new AgentContext(snapshot.getSessionId());

            // 2. 恢复关键属性 (类比反序列化)
            snapshot.getAttributes().forEach(context::setAttribute);

            // 3. 绑定到当前线程 (核心!)
            AgentContext.setContext(context);
        }

        try {
            chain.doFilter(request, response);
        } finally {
            // 4. 清理上下文 (关键!)
            AgentContext.clear();
        }
    }
}

/**
 * 敏感数据脱敏组件 (类比 Spring Data REST)
 */
@Component
public class ContextSanitizer {
    private static final Set<String> SENSITIVE_KEYS = Set.of("password", "creditCard", "idNumber");

    public void sanitize(AgentContext context) {
        context.getAttributes().keySet().stream()
                .filter(SENSITIVE_KEYS::contains)
                .forEach(key -> context.setAttribute(key, "****REDACTED****"));
    }

    // 在 Interceptor 的 afterCompletion 中调用
    public void applySanitization() {
        if (AgentContext.isContextActive()) {
            sanitize(AgentContext.current());
        }
    }
}

3.2 前端上下文管理 (React Context API)

// contexts/AgentContext.jsx
import { createContext, useContext, useReducer } from 'react';

// 1. 定义上下文结构 (类比 Java POJO)
const AgentContext = createContext({
    sessionId: null,
    contextData: {},
    updateContext: () => {},
    clearContext: () => {}
});

// 2. 上下文 Reducer (类比 Redux)
function contextReducer(state, action) {
    switch (action.type) {
        case 'INIT':
            return { ...state, sessionId: action.payload.sessionId, contextData: action.payload.initialData };
        case 'UPDATE':
            return { ...state, contextData: { ...state.contextData, ...action.payload } };
        case 'CLEAR':
            return { sessionId: null, contextData: {} };
        default:
            return state;
    }
}

// 3. 上下文 Provider (核心!)
export function AgentContextProvider({ children }) {
    const [state, dispatch] = useReducer(contextReducer, { sessionId: null, contextData: {} });

    // 4. 初始化上下文 (类比 Spring @PostConstruct)
    useEffect(() => {
        const sessionId = getOrCreateSession();
        const initialData = loadInitialContext(sessionId);
        dispatch({ type: 'INIT', payload: { sessionId, initialData } });

        // 5. 会话心跳保活 (类比 WebSocket ping)
        const heartbeat = setInterval(() => {
            fetch(`/api/context/heartbeat?sessionId=${sessionId}`);
        }, 30000);

        return () => clearInterval(heartbeat);
    }, []);

    // 6. 暴露更新方法 (类比 Service 方法)
    const updateContext = useCallback((updates) => {
        dispatch({ type: 'UPDATE', payload: updates });
        // 持久化到后端 (类比自动保存)
        fetch('/api/context/update', {
            method: 'POST',
            body: JSON.stringify({ sessionId: state.sessionId, updates })
        });
    }, [state.sessionId]);

    return (
        <AgentContext.Provider value={{
            sessionId: state.sessionId,
            contextData: state.contextData,
            updateContext,
            clearContext: () => dispatch({ type: 'CLEAR' })
        }}>
            {children}
        </AgentContext.Provider>
    );
}

// 7. 自定义 Hook (类比@Auth)
export function useAgentContext() {
    const context = useContext(AgentContext);
    if (!context.sessionId) {
        throw new Error('AgentContext must be used within AgentContextProvider');
    }
    return context;
}

// 8. 组件使用示例
function OrderHistory() {
    const { contextData, updateContext } = useAgentContext();
    const [orders, setOrders] = useState([]);

    useEffect(() => {
        // 9. 从上下文获取用户 ID (零 API 调用)
        const userId = contextData.userId;
        if (userId) {
            fetch(`/api/orders?userId=${userId}`)
                .then(res => res.json())
                .then(data => {
                    setOrders(data);
                    // 10. 更新上下文 (类比 Session.setAttribute)
                    updateContext({ lastViewedOrders: Date.now() });
                });
        }
    }, [contextData.userId]);

    return (
        <div>
            <h2>历史订单 ({contextData.tenantName})</h2>
            {orders.map(order => (
                <OrderCard key={order.id} order={order} />
            ))}
        </div>
    );
}

4. 上下文安全与性能优化

4.1 内存泄漏防护方案

/**
 * 上下文生命周期管理器 (类比 Tomcat 内存泄漏防护)
 */
@Component
public class ContextLifecycleManager implements ApplicationListener<ContextRefreshedEvent> {
    private static final long MAX_CONTEXT_AGE = 30 * 60 * 1000; // 30 分钟
    private final ScheduledExecutorService cleanupScheduler = Executors.newSingleThreadScheduledExecutor();

    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        // 启动清理任务 (类比 Spring @Scheduled)
        cleanupScheduler.scheduleAtFixedRate(this::cleanExpiredContexts, 0, 5, TimeUnit.MINUTES);
    }

    private void cleanExpiredContexts() {
        // 1. 识别过期上下文 (类比 Session 超时)
        long now = System.currentTimeMillis();
        List<String> expiredSessions = contextStore.findExpiredSessions(now - MAX_CONTEXT_AGE);

        // 2. 安全清理 (避免锁竞争)
        expiredSessions.forEach(sessionId -> {
            try {
                AgentContext context = contextStore.load(sessionId);
                if (context != null && now - context.getCreateTime() > MAX_CONTEXT_AGE) {
                    // 3. 触发清理回调 (类比 HttpSessionListener)
                    eventPublisher.publishEvent(new ContextExpiredEvent(sessionId));
                    contextStore.delete(sessionId);
                }
            } catch (Exception e) {
                log.error("清理上下文失败：{}", sessionId, e);
            }
        });
    }

    // 4. 异步线程上下文传递 (类比 TransmittableThreadLocal)
    public <T> CompletableFuture<T> executeWithContext(Supplier<T> task) {
        AgentContext snapshot = AgentContext.current().snapshot();
        return CompletableFuture.supplyAsync(() -> {
            try {
                // 在新线程重建上下文
                AgentContext.setContext(snapshot.restore());
                return task.get();
            } finally {
                AgentContext.clear(); // 必须清理!
            }
        }, asyncExecutor);
    }
}

// 使用示例 (异步场景)
@Service
public class AsyncNotificationService {
    @Autowired
    private ContextLifecycleManager lifecycleManager;

    public void sendPaymentAlert(Order order) {
        // 安全传递上下文到异步线程
        lifecycleManager.executeWithContext(() -> {
            AgentContext context = AgentContext.current();
            User user = context.getAttribute("user", User.class);
            notificationService.send(
                user.getPhone(),
                "支付成功：" + order.getAmount() + "元"
            );
            return null;
        });
    }
}

4.2 性能优化关键点

代码实现：

/**
 * 分层存储上下文 (性能优化核心)
 */
public class TieredContextStore implements ContextStore {
    // 1. 本地缓存 (高频访问)
    private final LoadingCache<String, AgentContext> localCache = Caffeine.newBuilder()
            .maximumSize(1000)
            .expireAfterWrite(5, TimeUnit.MINUTES)
            .build(this::loadFromRemote);

    // 2. 远程存储 (持久化)
    private final RedisTemplate<String, AgentContext> redisTemplate;

    @Override
    public AgentContext load(String sessionId) {
        // 3. 优先读本地缓存 (类比 L1 Cache)
        return localCache.get(sessionId);
    }

    private AgentContext loadFromRemote(String sessionId) {
        try {
            // 4. 读 Redis (类比 DB)
            String json = redisTemplate.opsForValue().get("context:" + sessionId);
            if (json != null) {
                AgentContext context = JSON.parseObject(json, AgentContext.class);
                // 5. 懒加载大对象 (类比 Hibernate LazyLoad)
                context.setAttribute("largeData", new LazyReference<>(() -> loadLargeData(sessionId)));
                return context;
            }
        } catch (Exception e) {
            log.warn("Redis 加载失败，降级到本地", e);
        }
        return new AgentContext(sessionId);
    }

    @Override
    public void save(AgentContext context) {
        // 6. 异步持久化 (类比写缓冲)
        asyncExecutor.execute(() -> {
            String json = JSON.toJSONString(context, SerializerFeature.PrettyFormat, SerializerFeature.IgnoreNonFieldGetter);
            redisTemplate.opsForValue().set("context:" + context.getSessionId(), json, 30, TimeUnit.DAYS); // 30 天 TTL
        });

        // 7. 本地缓存更新 (保证一致性)
        localCache.put(context.getSessionId(), context);
    }
}

// 懒加载代理 (优化大对象)
public class LazyReference<T> implements Supplier<T> {
    private final Supplier<T> loader;
    private volatile T value;

    public LazyReference(Supplier<T> loader) {
        this.loader = loader;
    }

    @Override
    public T get() {
        if (value == null) {
            synchronized (this) {
                if (value == null) {
                    value = loader.get();
                }
            }
        }
        return value;
    }
}

5. Web 开发者转型 AI 架构师行动指南

5.1 上下文注入核心价值

5.2 三阶段落地路径

1. 基础集成阶段（1 周）
   • 核心动作：在 Spring Boot 项目中添加上下文拦截器
   • 验证指标：上下文传递成功率 >99.9%
2. 深度优化阶段（2 周）
   • 核心任务：实现分层存储 + 懒加载
   • 架构重点：
     • 用 Caffeine 构建本地缓存（性能提升 10 倍）
     • 通过 Redis Hash 结构存储大对象（内存减少 70%）
     • 实现上下文差分更新（网络传输减少 80%）
3. 智能演进阶段（持续）
   • 核心能力：上下文自优化
   • 技术方案：高频字段大对象访问模式异常访问上下文使用频率 AI 分析引擎自动提升缓存层级预测加载策略安全熔断动态配置中心
   • 工程实践：
     • 上下文健康度监控大盘（Prometheus + Grafana）
     • 基于用户行为的上下文预热机制
     • 敏感数据自动识别与加密

压测方案：

# 模拟 1000 并发会话
k6 run -e SESSION_COUNT=1000 -e DURATION=30m context_load_test.js

代码改造：

// 0 侵入改造现有 Controller
@RestController
public class LegacyController {
    // 无需修改！通过 Interceptor 自动注入上下文
    @GetMapping("/orders")
    public List<Order> getOrders() {
        // 从上下文获取用户 (替代原 Session 获取)
        User user = AgentContext.current().getAttribute("user", User.class);
        return orderService.findByUser(user.getId());
    }
}

终极建议：不要被"AI 上下文"的概念吓倒。作为 Web 开发者，你早已掌握：用 ThreadLocal 管理请求链路 → 转化为 Agent 上下文载体用 JWT 实现跨服务认证 → 转化为上下文安全透传用 Redis 存储 Session → 转化为上下文持久化方案

真正的 AI 工程化，是把 Web 开发的最佳实践，用在智能系统构建中。当你能在 React 组件中 useAgentContext() 获取对话状态，或在 Spring Service 中 AgentContext.current() 获取用户意图时，你已站在 Web 与 AI 融合的最前沿。