使用 TypeScript 构建终端 AI 代码生成 CLI：提示链、语法验证与本地 LLM 集成

在现代软件开发中，AI 驱动的代码生成工具正迅速成为提升生产力的关键，尤其是在终端环境中操作的 CLI 工具，能够无缝融入开发者的日常工作流。本文将聚焦于使用 TypeScript 构建这样一个 CLI 的工程实践，以 Codebuff 项目为灵感来源，深入探讨提示链（prompt chaining）的设计、语法验证的实现，以及与本地大语言模型（LLM）的集成，从而支持离线原型开发。这种方法不仅能减少对云服务的依赖，还能确保数据隐私和快速迭代。

为什么选择 TypeScript 构建 AI 终端 CLI？

TypeScript 的类型安全、现代 ECMAScript 支持和丰富的生态，使其成为构建复杂 CLI 的理想语言。相比纯 JavaScript，它能更好地处理 AI 响应中的动态数据结构，如 JSON 配置或代码片段。同时，TypeScript CLI 可以轻松集成 Node.js 的异步 I/O 操作，适合处理 LLM 的流式输出。

一个典型的 AI 代码生成 CLI 需要处理用户自然语言指令，调用 LLM 生成代码，并在终端中应用变更。Codebuff 作为一个开源示例，展示了如何通过多代理架构实现这一目标：文件探索代理扫描代码库，规划代理制定编辑计划，编辑代理执行变更，审查代理验证结果。这种代理协作本质上就是提示链的体现，避免了单一提示的上下文丢失问题。

在工程实践中，我们可以从 CLI 骨架入手，使用如 Commander.js 或 Oclif 等库快速搭建命令行接口。以下是核心工程要点。

提示链机制：从单一指令到多步协作

提示链是 AI 代码生成的核心，它将复杂任务分解为序列化的提示交互，确保每个步骤基于前一步的输出。不同于简单的单轮查询，提示链能模拟人类开发流程：理解需求 → 规划变更 → 生成代码 → 验证应用。

在 TypeScript 中实现提示链，可以通过一个状态机或链式函数来管理。假设我们使用一个 Agent 类来封装每个提示步骤：

interface AgentStep {
  input: string;
  output: string;
  next?: AgentStep;
}

class PromptChain {
  private steps: AgentStep[] = [];
  private llm: LLMClient; // 本地或远程 LLM 客户端

  async addStep(prompt: string, context?: string): Promise<AgentStep> {
    const response = await this.llm.generate(prompt + context);
    const step: AgentStep = { input: prompt, output: response };
    this.steps.push(step);
    return step;
  }

  async chain(prompts: string[]): Promise<string> {
    let context = '';
    for (const prompt of prompts) {
      const step = await this.addStep(prompt, context);
      context += step.output + '\n';
    }
    return this.steps[this.steps.length - 1].output;
  }
}

这个实现的关键参数包括：

• 最大上下文长度：设置为 4K-8K tokens，防止溢出（使用 TikToken 库估算）。
• 温度参数：对于规划步骤设为 0.3（低创造性，确保逻辑性）；生成代码时设为 0.7（适度多样）。
• 重试机制：如果响应无效，重试 2-3 次，间隔 500ms。

在 Codebuff 的多代理模型中，提示链扩展为代理间通信：文件探索代理的输出作为规划代理的输入。这种设计可落地为一个 YAML 配置清单：

• 步骤 1: 扫描代码库（工具: glob 文件匹配）。
• 步骤 2: 规划变更（提示: "基于以下文件结构，规划 {task} 的编辑"）。
• 步骤 3: 生成代码（提示: "在 {file} 中添加 {change}"）。
• 步骤 4: 审查（提示: "验证 {generated} 是否符合最佳实践"）。

通过这种链式处理，CLI 能处理如 "添加用户认证到 API" 的复杂指令，而非简单复制粘贴代码。

语法验证：确保 AI 生成代码的可靠性

AI 生成的代码往往存在语法错误、类型不匹配或安全隐患。工程一个可靠的 CLI，必须集成多层验证机制，防止直接应用破损变更。

在 TypeScript CLI 中，语法验证可以分为静态和动态两阶段：

1. 静态验证：使用 ESLint 和 TypeScript 编译器检查生成的代码片段。
2. 动态验证：运行单元测试或 lint 工具模拟执行。

实现示例：

import * as ts from 'typescript';
import { ESLint } from 'eslint';

async function validateCode(code: string, filePath: string): Promise<{ valid: boolean; errors: string[] }> {
  // TypeScript 检查
  const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest);
  const diagnostics = ts.getPreEmitDiagnostics(sourceFile);
  if (diagnostics.length > 0) {
    return { valid: false, errors: diagnostics.map(d => d.messageText as string) };
  }

  // ESLint 检查
  const eslint = new ESLint({ fix: false });
  const results = await eslint.lintText(code, { filePath });
  const errors = results?.flatMap(r => r.messages.map(m => m.message)) || [];

  return { valid: errors.length === 0, errors };
}

关键参数与清单：

• 验证阈值：错误数 > 5 时拒绝应用；警告数 > 10 时提示用户确认。
• 集成工具：Prettier 自动格式化，ESLint 配置为 Airbnb 或自定义规则集（强调安全，如 no-eval）。
• 回滚策略：变更前 git stash，验证失败时自动恢复。监控点：验证通过率 > 90%，否则调整提示模板。
• AI 辅助验证：如果静态失败，将错误反馈给 LLM 重新生成（提示: "修复以下错误: {errors}"）。

Codebuff 的审查代理正是这一机制的体现，它在应用变更前运行测试，确保无回归。这种验证不仅提升可靠性，还为用户提供可解释性：CLI 输出 "验证通过，3 个警告已修复"。

与本地 LLM 的集成：实现离线原型开发

云 LLM 如 OpenAI 虽强大，但依赖网络且有隐私风险。对于离线原型，集成本地 LLM（如使用 Ollama 运行 Llama 3 或 CodeLlama）是关键。TypeScript CLI 可以桥接本地模型，实现零延迟生成。

集成步骤：

1. 安装 Ollama：CLI 启动时检查 ollama --version，若无则引导安装。
2. 客户端封装：使用 ollama-js 库调用本地 API。

import { Ollama } from 'ollama';

class LocalLLMClient {
  private ollama = new Ollama({ host: 'http://localhost:11434' });

  async generate(prompt: string, options: { model: string; temperature: number } = { model: 'codellama', temperature: 0.7 }) {
    const response = await this.ollama.generate({
      model: options.model,
      prompt,
      stream: false, // 对于 CLI，批量生成更高效
    });
    return response.response;
  }
}

落地参数：

• 模型选择：CodeLlama-7B 用于代码任务，Phi-3-mini 用于轻量规划。下载大小控制在 4-8GB。
• 硬件要求：最低 8GB RAM，GPU 加速（NVIDIA CUDA）可选。监控 GPU 利用率 < 80% 以防过热。
• 离线 fallback：若本地模型负载高，切换到缓存提示（预生成常见模板）。
• 安全清单：沙箱执行生成的代码（使用 vm2 库），限制网络访问；定期更新模型以修复漏洞。

这种集成允许开发者在无网环境中原型化：例如，运行 codegen --offline "生成 React 组件"，CLI 使用本地 LLM 链式生成并验证代码。相比云服务，本地方案的响应时间可降至 2-5 秒，适合快速迭代。

工程挑战与优化策略

构建此类 CLI 时，常见风险包括提示漂移（输出不一致）和性能瓶颈（链式调用慢）。缓解措施：

• 缓存机制：使用 Redis 或文件缓存常见提示响应，命中率目标 70%。
• 监控与日志：集成 Winston 日志，追踪链步成功率；Prometheus 指标如生成延迟 < 10s。
• 测试驱动开发：单元测试覆盖 80% 代码，使用 Jest 模拟 LLM 响应。
• 部署清单：npm 打包，支持 npx 运行；Docker 容器化本地 LLM 环境。

通过这些实践，我们能打造一个高效、可靠的 AI 终端 CLI。Codebuff 的开源代码提供了宝贵参考，其代理框架可直接 fork 并扩展本地支持。最终，这种工具将 AI 从浏览器拉回终端，重塑开发范式。

（字数约 1250）

参考：

• Codebuff GitHub: https://github.com/CodebuffAI/codebuff （多代理架构与 CLI 实现）。
• Ollama 文档: https://ollama.com （本地 LLM 集成指南）。