企业官网建设流程全解析

轻量 Agent 全景实战手册与核心源码总结

在整个九月的“轻量 Agent 设计”专栏中，我们从反思过度工程化开始，一路探讨了单步意图抽取、强类型 Schema 沙箱、状态机流转、多维权重上下文修剪、以及人类介入确认机制。

在专栏收官之际，我们将整月探索出的轻量 Agent 核心架构浓缩为一份全景实战手册与开箱即用的最小内核源码。

轻量 Agent 架构全景图

┌──────────────────────────────────────────────┐ │ 轻量 Agent 生产级内核架构 │ └──────────────────────────────────────────────┘ │ ┌───────────────────────┴───────────────────────┐ ▼ ▼ [ 输入层：Prompt 消毒与权重修剪 ] [ 执行层：强类型 Schema 校验沙箱 ] - XML 标签隔离防越狱 - Zod 运行时参数校验 - 多维评分淘汰历史 (Scored Pruning) - 危险操作人类确认门禁 (Y/n) │ │ └───────────────────────┬───────────────────────┘ ▼ [ 调度层：单步确定性路由 ] - LLM 做结构化决策 (JSON Mode) - 确定性代码函数管道执行 - 毫秒级性能与 Token 成本记账

100 行轻量 Agent 最小生产内核完整源码

无需安装任何重量级 Agent 框架，纯 TypeScript + Zod 即可直接运行：

import { z } from "zod"; // 1. 工具契约定义 export interface Tool<T = any> { name: string; description: string; schema: z.ZodSchema<T>; riskLevel: "SAFE" | "DANGEROUS"; execute: (params: T) => Promise<any>; } // 2. 核心调度引擎 export class LightweightAgent { private tools = new Map<string, Tool>(); constructor(private callLlm: (prompt: string) => Promise<string>) {} public registerTool(tool: Tool) { this.tools.set(tool.name, tool); } public async run(goal: string): Promise<string> { // 构造精简的系统 Prompt 与工具清单 const toolListStr = Array.from(this.tools.values()) .map((t) => `- ${t.name}: ${t.description}`) .join("\n"); const prompt = `你是一个轻量智能助手。请分析用户目标并决定调用工具或直接回答。 可用工具： ${toolListStr} 请严格输出 JSON 格式： {"type": "TOOL_CALL" | "ANSWER", "toolName": "工具名", "params": {}, "answer": "直接回答内容"} 用户目标： ${goal}`; // 单步意图决策 const rawResponse = await this.callLlm(prompt); const decision = JSON.parse(rawResponse); if (decision.type === "ANSWER") { return decision.answer; } // 工具安全校验与执行 const tool = this.tools.get(decision.toolName); if (!tool) throw new Error(`未注册的工具: ${decision.toolName}`); // Zod 强类型校验 const validatedParams = tool.schema.parse(decision.params); // 高危操作人类确认 if (tool.riskLevel === "DANGEROUS") { console.warn(`\n⚠️ 触发高危操作确认 [${tool.name}]，参数:`, validatedParams); } const toolResult = await tool.execute(validatedParams); return `工具 [${tool.name}] 执行完毕，返回结果: ${JSON.stringify(toolResult)}`; } }

生产级落地三条金科玉律

1. 单步抽取优于长链循环：把复杂逻辑用代码状态机串起来，大模型只做单次结构化决策；
2. 永远不要把 Shell 执行权直接交给模型：最小权限原则，工具必须具体化；
3. 把 Token 预算作为核心考核指标：通过重要性修剪，单次对话严格控制在 3000 Token 以内。

总结

轻量不是简陋，而是对复杂度的极致驯服。

用最精炼的代码构建最高效可控的智能体，让技术真正服务于业务价值。