轻量 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 ToolT any { name: string; description: string; schema: z.ZodSchemaT; riskLevel: SAFE | DANGEROUS; execute: (params: T) Promiseany; } // 2. 核心调度引擎 export class LightweightAgent { private tools new Mapstring, Tool(); constructor(private callLlm: (prompt: string) Promisestring) {} public registerTool(tool: Tool) { this.tools.set(tool.name, tool); } public async run(goal: string): Promisestring { // 构造精简的系统 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)}; } }生产级落地三条金科玉律单步抽取优于长链循环把复杂逻辑用代码状态机串起来大模型只做单次结构化决策永远不要把 Shell 执行权直接交给模型最小权限原则工具必须具体化把 Token 预算作为核心考核指标通过重要性修剪单次对话严格控制在 3000 Token 以内。总结轻量不是简陋而是对复杂度的极致驯服。用最精炼的代码构建最高效可控的智能体让技术真正服务于业务价值。