AI智能体开发：基于TypeScript构建技能与解释器驱动的工作流

1. 项目概述：为智能体构建技能与解释器驱动的工作流

最近在折腾AI智能体（Agents）开发，特别是围绕Claude Code、Cursor这类新一代AI编程工具，我发现一个核心痛点：如何让一个智能体不只是简单地调用API，而是能像一名真正的开发者一样，拥有连贯、可复用、可组合的“技能”（Skills），并基于这些技能执行复杂的工作流（Workflows）。这不仅仅是写几个提示词（Prompt）那么简单，它涉及到如何将自然语言指令结构化、如何让不同的技能模块化地协作、以及如何让智能体理解并执行多步骤任务。这正是“Building workflows for agents with Skills and Interpreters”这个主题要解决的核心问题。简单来说，它就是一套方法论和工具集，用于赋予AI智能体“工具箱”和“使用说明书”，让它们能自主或半自主地完成从需求分析、代码编写、测试到部署等一系列开发任务。

如果你正在使用TypeScript进行AI应用开发，或者对如何将大型语言模型（LLM）的能力更深度地集成到你的开发流程中感兴趣，那么理解技能与解释器驱动的智能体工作流，将是提升开发效率、构建更强大AI助手的关键。这不仅仅是Claude Code或Cursor用户的专属话题，任何希望利用AI自动化重复性编码任务、构建智能开发副驾的开发者，都能从中获得启发和可直接落地的实践方案。

2. 核心理念拆解：技能、解释器与工作流的三位一体

要构建一个强大的智能体，我们需要先厘清三个核心概念：技能（Skills）、解释器（Interpreters）和工作流（Workflows）。它们之间的关系，好比一个工匠（智能体）的工具箱（技能）、大脑（解释器）和施工图纸（工作流）。

2.1 技能：智能体的模块化工具箱

技能是智能体能够执行的最小可复用操作单元。它不是一个模糊的“写代码”指令，而是一个封装良好、功能明确的动作。例如：

• 一个文件操作技能：readFile(path: string): Promise<string>， 它封装了读取指定路径文件内容的所有逻辑。
• 一个代码分析技能：analyzeCodeComplexity(code: string): { cyclomaticComplexity: number, maintainabilityIndex: number }， 它调用特定的代码分析库（如typhonjs-escomplex）并返回结构化结果。
• 一个网络请求技能：fetchGitHubRepoInfo(owner: string, repo: string): Promise<RepoInfo>， 它处理GitHub API的认证、请求和错误重试。

技能的设计原则：

1. 单一职责：一个技能只做一件事，并且做好。这保证了技能的高内聚和易测试。
2. 明确接口：输入和输出必须是清晰、类型化的。在TypeScript中，这通过接口（Interface）或类型别名（Type Alias）来定义，这是与智能体“沟通”的契约。
3. 无状态性：理想情况下，技能本身不维护状态。状态应该由工作流或调用者管理。这使得技能可以在不同上下文中安全复用。
4. 可描述性：技能需要提供机器可读的描述（如名称、功能、输入参数说明、输出示例），以便智能体的“大脑”（解释器）能够理解在什么情况下调用它。

注意：不要将技能设计得过于庞大。一个“实现用户登录功能”的技能就过于复杂，它应该被拆分为“验证用户输入”、“查询数据库”、“生成JWT令牌”、“设置HTTP Cookie”等多个更细粒度的技能。

2.2 解释器：智能体的决策与调度中心

解释器是智能体的“大脑”。它的核心职责是：

1. 理解用户意图：将用户的自然语言指令（如“帮我在src/utils目录下创建一个格式化日期的函数”）解析为结构化任务。
2. 规划与调度：根据当前任务、可用技能和上下文，规划出一个或多个技能的执行序列（即工作流）。它需要决定先做什么，后做什么，以及如果某一步失败该如何处理（重试、回滚或报错）。
3. 技能调用与结果整合：按照规划，依次调用相应的技能，并将上一个技能的输出作为下一个技能的输入（如果需要），最终将整合后的结果返回给用户。

解释器通常由一个大语言模型（LLM）驱动，例如通过OpenAI的GPT、Anthropic的Claude或本地的开源模型。我们通过精心设计的系统提示词（System Prompt）和上下文管理，来“教导”LLM如何扮演好这个调度员的角色。在TypeScript实现中，解释器可能是一个封装了LLM调用、上下文管理和技能路由的类。

2.3 工作流：技能执行的蓝图

工作流是解释器规划出的、由一系列技能按特定逻辑顺序（顺序、并行、条件分支、循环）组成的执行蓝图。它是动态生成的，而不是静态定义的。例如，针对“创建格式化日期函数”的指令，一个可能的工作流是：

1. 技能A：分析现有代码结构-> 确定src/utils目录是否存在，以及日期相关函数的命名惯例。
2. 技能B：读取相关模板或示例-> 从知识库或指定路径读取日期格式化函数的通用模板。
3. 技能C：生成函数代码-> 结合模板和具体需求（如需要支持YYYY-MM-DD和ISO格式），生成TypeScript函数代码。
4. 技能D：代码风格检查-> 调用ESLint或Prettier技能对生成的代码进行格式化。
5. 技能E：写入文件-> 将最终代码写入src/utils/dateFormatter.ts。

这个工作流在运行时才被解释器动态创建出来。更高级的工作流可能包含错误处理分支：如果技能D检查失败，则触发“代码修正”技能，然后重新检查。

3. 基于TypeScript的实战架构设计

理解了理念之后，我们来看如何用TypeScript构建这样一个系统。下面是一个高内聚、低耦合的参考架构。

3.1 核心模块定义

我们将系统分为以下几个核心模块，并使用TypeScript接口来定义契约：

// 1. 技能接口定义 interface Skill { name: string; // 技能唯一标识，如 "file.read" description: string; // 给LLM看的自然语言描述 inputSchema: JSONSchema; // 输入参数JSON Schema，用于验证和提示LLM outputSchema: JSONSchema; // 输出结构JSON Schema execute: (params: any, context: AgentContext) => Promise<any>; // 执行函数 } // 2. 技能注册表 class SkillRegistry { private skills: Map<string, Skill> = new Map(); register(skill: Skill): void { this.skills.set(skill.name, skill); } getSkill(name: string): Skill | undefined { return this.skills.get(name); } getAllSkillDescriptions(): Array<{name: string, description: string, inputSchema: JSONSchema}> { // 返回所有技能的描述，用于构造给LLM的提示词 return Array.from(this.skills.values()).map(s => ({ name: s.name, description: s.description, inputSchema: s.inputSchema })); } } // 3. 解释器核心 class Interpreter { constructor( private llmClient: LLMClient, // LLM客户端（如OpenAI, Anthropic） private skillRegistry: SkillRegistry ) {} async interpret(userInput: string, context: AgentContext): Promise<Workflow> { // 步骤1：构造提示词，包含可用技能列表和当前上下文 const prompt = this.constructPlanningPrompt(userInput, context); // 步骤2：调用LLM，让其生成一个规划（JSON格式） const llmResponse = await this.llmClient.createChatCompletion({ messages: [{ role: 'system', content: prompt }], temperature: 0.1, // 低随机性，保证规划稳定性 }); // 步骤3：解析LLM返回的JSON，将其转换为Workflow对象 const plan = JSON.parse(llmResponse.content); return this.parsePlanToWorkflow(plan); } private constructPlanningPrompt(userInput: string, context: AgentContext): string { const skillDescriptions = this.skillRegistry.getAllSkillDescriptions(); // 这里构建一个详细的提示词，指导LLM如何规划 return ` 你是一个智能开发助手。你的任务是将用户请求分解为一系列可执行的步骤（技能）。 以下是你可以调用的技能列表： ${JSON.stringify(skillDescriptions, null, 2)} 当前上下文： - 工作目录：${context.cwd} - 已打开文件：${context.openFiles.join(', ')} 用户请求：${userInput} 请以JSON格式输出你的计划，格式如下： { "thought": "你的推理过程", "steps": [ { "skill": "skill.name", "params": { ... }, "reason": "为什么使用这个技能" }, ... ] } `; } } // 4. 工作流执行引擎 class WorkflowEngine { async execute(workflow: Workflow, context: AgentContext): Promise<WorkflowResult> { const results: any[] = []; for (const step of workflow.steps) { const skill = this.skillRegistry.getSkill(step.skill); if (!skill) { throw new Error(`Skill ${step.skill} not found`); } try { // 执行技能，并将上一步的结果（如果有）注入参数 const params = this.injectPreviousResult(step.params, results); const result = await skill.execute(params, context); results.push(result); context.log(`Step ${step.skill} completed.`); } catch (error) { // 错误处理：可以重试、回滚或终止工作流 context.error(`Step ${step.skill} failed: ${error.message}`); // 这里可以触发一个“错误处理”工作流 throw new WorkflowExecutionError(step.skill, error); } } return { success: true, outputs: results }; } }

3.2 技能的具体实现示例

让我们实现两个具体的技能，感受一下细节：

// 文件读取技能 const readFileSkill: Skill = { name: "fs.readFile", description: "读取指定路径文件的内容。", inputSchema: { type: "object", properties: { path: { type: "string", description: "文件的相对或绝对路径" } }, required: ["path"] }, outputSchema: { type: "object", properties: { content: { type: "string", description: "文件内容" }, exists: { type: "boolean" } } }, async execute(params: { path: string }, context: AgentContext) { const fs = await import('fs/promises'); const path = await import('path'); const fullPath = path.resolve(context.cwd, params.path); try { const content = await fs.readFile(fullPath, 'utf-8'); return { content, exists: true }; } catch (error: any) { if (error.code === 'ENOENT') { return { content: '', exists: false }; } throw error; // 其他错误向上抛出 } } }; // 代码生成技能（调用LLM） const generateCodeSkill: Skill = { name: "code.generate", description: "根据描述和上下文生成代码片段。", inputSchema: { type: "object", properties: { instruction: { type: "string", description: "代码生成指令" }, contextCode: { type: "string", description: "相关的上下文代码", default: "" } }, required: ["instruction"] }, outputSchema: { type: "object", properties: { code: { type: "string", description: "生成的代码" }, explanation: { type: "string", description: "对生成代码的简要说明" } } }, async execute(params: { instruction: string; contextCode?: string }, context: AgentContext) { // 调用LLM生成代码 const prompt = ` 你是一个TypeScript专家。请根据以下指令生成代码。 指令：${params.instruction} ${params.contextCode ? `相关上下文代码：\n\`\`\`typescript\n${params.contextCode}\n\`\`\`` : ''} 请只输出代码块，如果需要解释，请在代码块后的注释中简要说明。 `; const response = await context.llmClient.chat([{ role: 'user', content: prompt }]); // 简单地从响应中提取代码块（实际应用需要更健壮的解析） const code = this.extractCodeBlock(response); return { code, explanation: 'Generated based on instruction.' }; } };

实操心得：在实现generateCodeSkill时，最关键的是设计好给LLM的提示词。指令必须清晰，上下文要相关且简洁。一个常见的技巧是，在提示词中明确指定输出格式，例如“请输出一个完整的TypeScript函数，函数名为formatDate”，这能极大提高生成代码的可用性，减少后续修正的工作量。

4. 工作流动态规划与执行的深入解析

解释器生成的工作流是动态的，这意味着同样的用户指令在不同上下文中可能产生不同的执行计划。这是智能体“智能”的体现。

4.1 规划提示词工程

解释器的核心能力很大程度上取决于我们如何构造给LLM的规划提示词（Planning Prompt）。上面示例中是一个基础版本，一个成熟的提示词应该包含更多细节：

1. 约束条件：明确告诉LLM什么不能做。例如：“你不能直接修改node_modules目录下的文件”、“所有文件操作必须基于context.cwd指定的工作目录”。
2. 最佳实践指引：例如：“创建新文件时，优先检查是否已存在同名文件”、“生成代码后，应自动调用代码格式化技能”。
3. 上下文丰富化：不仅传递当前目录和打开的文件，还可以传递项目类型（如“Next.js”, “React Native”）、包管理器（npm/yarn/pnpm）、以及最近的操作历史。
4. 输出格式强化：严格要求LLM输出指定格式的JSON，并可以提供多个示例（Few-shot Learning），让LLM更好地模仿。

一个增强版的提示词开头可能是这样的：

你是一个经验丰富的软件开发助手。你的目标是将用户请求安全、高效地转化为一系列原子操作（技能）。 **安全规则**： 1. 绝不执行任何可能破坏系统或数据的操作（如`rm -rf /`）。 2. 所有文件路径必须是相对于当前工作目录(`${context.cwd}`)的。 3. 在覆盖任何现有文件前，必须通过`fs.readFile`技能检查其内容。 **可用的技能是你唯一能执行的操作**。你必须从以下列表中选择并组合它们来完成用户请求： [技能列表JSON] **输出格式必须严格遵循此JSON Schema**： { "thought": "...", "steps": [{"skill": "...", "params": {...}, "reason": "..."}] } **示例1**： 用户请求：“看看src/index.ts里有什么” 输出：{ "thought": "用户想查看文件内容，我需要使用文件读取技能。", "steps": [ {"skill": "fs.readFile", "params": {"path": "src/index.ts"}, "reason": "读取指定路径的文件内容"} ] } 现在，请处理以下请求： 用户请求：`${userInput}` 当前上下文：${JSON.stringify(context)}

4.2 工作流的执行与状态管理

工作流引擎在执行时，需要妥善管理状态和依赖。

• 参数注入：后一个技能的输入可能依赖于前一个技能的输出。引擎需要提供一种方式，让技能参数可以引用之前步骤的结果。一种常见的方法是使用模板语法，例如在参数中写{{steps[0].output.content}}，引擎在执行前将其替换为实际值。
• 错误处理与重试：不是所有错误都需要终止整个工作流。对于网络波动等临时性错误，可以配置自动重试。对于技能执行失败，可以设计备选路径。例如，如果code.generate生成的代码无法通过code.lint检查，可以触发一个code.fix技能尝试自动修复，修复后再重新检查。
• 并行执行优化：如果工作流中的某些步骤之间没有依赖关系，引擎可以尝试并行执行它们以提高效率。例如，在初始化一个新项目时，“安装依赖”和“创建配置文件”可能可以同时进行。这需要解释器在规划时就能识别出这种并行可能性，或者引擎在执行时进行动态分析。

// 一个支持简单参数注入的执行步骤示例 class WorkflowEngine { private injectPreviousResult(params: any, previousResults: any[]): any { const paramString = JSON.stringify(params); // 简单的模板替换，例如将 {{steps[0].output.filePath}} 替换为实际值 const injectedParamString = paramString.replace( /\{\{steps\[(\d+)\]\.output\.(\w+)\}\}/g, (match, stepIndex, key) => { const result = previousResults[parseInt(stepIndex)]; return result ? result[key] : match; } ); return JSON.parse(injectedParamString); } }

5. 高级主题：技能组合、测试与调试

5.1 复合技能与技能链

基础技能是原子操作，但我们可以组合它们形成更高级的“复合技能”或“技能链”。这类似于编程中的函数组合。

• 显式组合：创建一个新的技能，在其execute方法内部按顺序调用其他技能。这种方式逻辑清晰，但灵活性较差。

  const createReactComponentSkill: Skill = { name: "react.createComponent", async execute(params, context) { // 1. 生成组件代码 const codeResult = await generateCodeSkill.execute({ instruction: `创建一个名为${params.name}的React函数组件，使用TypeScript，包含props类型定义。` }, context); // 2. 格式化代码 const formattedCode = await formatCodeSkill.execute({ code: codeResult.code }, context); // 3. 写入文件 await writeFileSkill.execute({ path: `src/components/${params.name}.tsx`, content: formattedCode.code }, context); return { success: true, filePath: `src/components/${params.name}.tsx` }; } };

• 动态组合：更优雅的方式是，让解释器在规划阶段就识别出常见的模式，并自动应用。这需要更强大的LLM和更丰富的上下文。例如，当用户请求“创建一个新的React组件并添加样式”时，解释器应该能自动规划出“生成TSX代码” -> “生成CSS/SASS代码” -> “创建文件” -> “更新导出索引”这一连串技能。

5.2 技能的测试策略

技能作为原子操作，必须易于测试。由于它们通常是纯函数或接近纯函数（依赖注入外部服务），我们可以为每个技能编写单元测试。

// 使用Jest测试readFileSkill import { readFileSkill } from './skills/filesystem'; import { AgentContext } from './types'; describe('readFileSkill', () => { let mockContext: AgentContext; beforeEach(() => { mockContext = { cwd: '/test', log: jest.fn(), error: jest.fn() }; // 可以mock fs模块，避免真实IO }); it('should read file content successfully', async () => { // 假设我们mock了fs.readFile返回'hello world' const result = await readFileSkill.execute({ path: 'test.txt' }, mockContext); expect(result.content).toBe('hello world'); expect(result.exists).toBe(true); }); it('should handle non-existent file gracefully', async () => { // 假设我们mock了fs.readFile抛出ENOENT错误 const result = await readFileSkill.execute({ path: 'nonexistent.txt' }, mockContext); expect(result.content).toBe(''); expect(result.exists).toBe(false); }); it('should validate input parameters', () => { // 可以使用ajv等库根据inputSchema进行验证测试 const invalidInput = {}; expect(() => someValidationFunction(invalidInput, readFileSkill.inputSchema)).toThrow(); }); });

对于解释器和工作流引擎，则需要更复杂的集成测试或端到端测试，模拟用户输入，验证最终输出的正确性。

5.3 调试与可观测性

当智能体行为不符合预期时，强大的调试工具至关重要。

1. 详细日志：在每个技能执行前后、解释器规划前后，记录详细的日志，包括输入、输出、耗时和可能发生的错误。这些日志应该结构化（如JSON格式），方便查询和分析。
2. 工作流可视化：将解释器生成的Workflow对象可视化，展示技能执行的顺序、状态（等待、执行中、成功、失败）和中间结果。这对于理解复杂任务的执行路径非常有帮助。
3. 思维链追溯：保存并展示解释器在规划时产生的“thought”字段。这是理解LLM决策过程的关键，如果规划出错，可以首先检查这里的推理逻辑是否合理。
4. 交互式修正：当某一步骤失败时，不应总是让整个工作流产。可以提供一种“交互式修复”模式，将错误和上下文反馈给用户或一个更高级的“修复智能体”，由它来决定是重试、跳过还是手动介入。

6. 常见问题与实战避坑指南

在实际构建和使用这类系统时，你会遇到一些典型问题。以下是我从多个项目中总结出的经验。

6.1 规划失败：LLM不按格式输出或逻辑混乱

• 问题：解释器调用LLM后，返回的不是有效的JSON，或者规划的步骤完全不合理（比如试图用fs.readFile技能去安装npm包）。
• 排查与解决：
  1. 强化提示词：在提示词中更严厉地强调输出格式，并使用JSON Schema来描述要求的格式。可以提供2-3个非常清晰的示例（Few-shot）。
  2. 降低Temperature：将LLM调用的temperature参数设低（如0.1），减少随机性，使输出更稳定。
  3. 后处理与重试：在代码中捕获JSON解析错误。如果解析失败，可以将错误信息和原始提示再次发送给LLM，要求它修正。通常设置1-2次重试就能解决大部分格式问题。
  4. 使用结构化输出：如果使用的LLM API支持（如OpenAI的JSON Mode，或Anthropic的Claude有相应功能），务必开启。这能从根本上保证输出格式。

6.2 技能执行错误：权限、依赖或环境问题

• 问题：技能本身逻辑正确，但在特定环境下执行失败（如文件权限不足、网络请求超时、缺少某个命令行工具）。
• 排查与解决：
  1. 技能设计要健壮：技能内部应有完善的错误处理，区分“预期内错误”（如文件不存在）和“意外错误”（如权限拒绝），并抛出带有明确类型的错误。
  2. 上下文注入环境信息：在AgentContext中提供环境信息，如操作系统、Node.js版本、当前用户权限等。技能可以根据这些信息调整行为或提前报出友好错误。
  3. 依赖检查技能：创建一个system.checkDependency技能，在工作流开始前，检查必要的命令行工具、环境变量或网络连通性。
  4. 实施重试与回退机制：在工作流引擎层，对网络类技能配置指数退避重试。对于某些操作，可以提供“回退”技能，比如git.reset技能可以在文件操作失败后尝试恢复。

6.3 性能问题：工作流执行缓慢

• 问题：涉及多个LLM调用的复杂工作流（如规划一次，生成代码又调用一次）耗时很长。
• 排查与解决：
  1. 技能缓存：对于纯函数且输入相同的技能（如代码格式化、静态分析），可以对其结果进行缓存。
  2. 并行化：如前所述，分析工作流步骤间的依赖关系，对无依赖的步骤进行并行执行。
  3. LLM调用优化：考虑使用更快的模型、配置更低的max_tokens（如果不需要长输出）、或使用流式响应（streaming）让用户感知更快。对于非关键路径的LLM调用（如生成解释文本），可以尝试使用更小、更快的模型。
  4. 异步与超时：确保所有技能调用和LLM请求都是异步的，并设置合理的超时时间，避免单个步骤卡死整个流程。

6.4 安全风险：任意代码执行与数据泄露

• 问题：这是最危险的一类问题。智能体如果拥有文件读写、命令执行等强大技能，可能被恶意提示词诱导执行危险操作。
• 排查与解决：
  1. 技能权限隔离：实现一个权限系统。为每个技能标记所需的权限级别（如read,write,exec）。在解释器规划阶段或引擎执行阶段进行权限检查。一个处理用户消息的聊天智能体，绝不应该被赋予exec权限。
  2. 输入验证与净化：对所有从用户输入或LLM规划中产生的参数进行严格的验证和净化。特别是传递给exec类技能的命令行参数，必须进行白名单过滤或转义。
  3. 沙箱环境：对于执行不确定代码（如运行生成的代码片段）的技能，必须在安全的沙箱环境（如Docker容器、vm2模块）中运行，并严格限制资源（CPU、内存、网络）。
  4. 审计日志：所有技能的调用，特别是高危操作，必须记录不可篡改的审计日志，包括操作者、时间、参数和结果。

构建一个由技能和解释器驱动的智能体工作流系统，是一个迭代和演化的过程。从实现几个核心技能开始，逐步完善解释器的提示词和规划逻辑，再根据实际使用反馈增加更多的技能和更健壮的错误处理。这套架构的核心优势在于其模块化和可扩展性——每增加一个新的技能，就相当于为你的智能体增加了一种新的“超能力”。随着技能库的丰富，你的智能体能够自动化处理的任务会变得越来越复杂，最终成为一个真正理解你项目和编码习惯的强力助手。