第 8 章 接入大模型 — 基础能力

// src/core/ai.ts
import OpenAI from 'openai'
 
export function createAIClient(config: RepoxConfig): OpenAI {
  const apiKey = config.ai.apiKey
  if (!apiKey) {
    throw new UserError(
      'AI API Key 未配置',
      '请执行 repox config set ai.apiKey <your-key> 或设置环境变量 REPOX_AI_API_KEY',
    )
  }
 
  return new OpenAI({
    apiKey,
    baseURL: config.ai.baseUrl,
  })
}

// src/core/config.ts — configSchema 定义
ai: z.object({
  apiKey: z.string().optional(),
  baseUrl: z.string().default('https://ark.cn-beijing.volces.com/api/v3'),
  model: z.string().default('doubao-1-5-pro-32k-250115'),
}).default({}),

# 使用 OpenAI
repox config set ai.baseUrl https://api.openai.com/v1
repox config set ai.model gpt-4o
 
# 使用 Claude（通过兼容层）
repox config set ai.baseUrl https://api.anthropic.com/v1
repox config set ai.model claude-sonnet-4-20250514
 
# 使用火山引擎豆包（默认）
repox config set ai.baseUrl https://ark.cn-beijing.volces.com/api/v3
repox config set ai.model doubao-1-5-pro-32k-250115

// src/core/ai.ts
export async function chat(
  client: OpenAI,
  model: string,
  messages: ChatCompletionMessageParam[],
): Promise<string> {
  logger.debug(`AI 请求: model=${model}, messages=${messages.length} 条`)
  const response = await client.chat.completions.create({
    model,
    messages,
  })
 
  const content = response.choices[0]?.message?.content
  if (!content) {
    throw new UserError('AI 返回了空内容')
  }
 
  logger.debug(`AI 响应: ${content.length} 字符`)
  return content
}

// src/core/ai.ts
export async function* chatStream(
  client: OpenAI,
  model: string,
  messages: ChatCompletionMessageParam[],
): AsyncGenerator<string, void, unknown> {
  logger.debug(`AI 流式请求: model=${model}, messages=${messages.length} 条`)
 
  const stream = await client.chat.completions.create({
    model,
    messages,
    stream: true,
  })
 
  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content
    if (content) {
      yield content
    }
  }
}

// src/core/ai.ts
export async function streamToStdout(
  client: OpenAI,
  model: string,
  messages: ChatCompletionMessageParam[],
): Promise<string> {
  let fullContent = ''
  for await (const chunk of chatStream(client, model, messages)) {
    process.stdout.write(chunk)
    fullContent += chunk
  }
  process.stdout.write('\n')
  return fullContent
}

// src/commands/review.ts
if (options.stream) {
  logger.title('Code Review')
  await streamToStdout(client, config.ai.model, messages)
} else {
  const spinner = ora('AI 正在审查代码...').start()
  const result = await chat(client, config.ai.model, messages)
  spinner.stop()
  logger.title('Code Review')
  logger.plain(result)
}

// src/commands/commit.ts
const messages = [
  {
    role: 'system' as const,
    content: `你是一个 Git commit message 生成专家。根据用户提供的 git diff，生成一条规范的 commit message。
要求：
- 使用 Conventional Commits 格式：<type>(<scope>): <description>
- type 从以下选择：feat, fix, docs, style, refactor, perf, test, chore
- scope 是可选的，表示影响范围
- description 用英文，首字母小写，不加句号
- 如果变更较复杂，可以加 body 说明（空一行后写）
- 只输出 commit message，不要其他解释文字`,
  },
  // ...
]

// src/commands/commit.ts
{
  role: 'user' as const,
  content: `变更文件: ${stagedFiles.join(', ')}\n\nDiff:\n${truncatedDiff}`,
}

const systemPrompt = `输出格式为 JSON:
{
  "summary": "总体评价",
  "issues": [
    { "severity": "critical|warning|info", "file": "文件名", "line": 42, "message": "问题描述" }
  ]
}
不要输出其他内容。`

根据以下 git diff 生成 commit message。

根据以下 git diff 生成 commit message。
使用 Conventional Commits 格式：<type>(<scope>): <description>

你是 Git commit message 生成专家。根据 diff 生成一条规范的 commit message。
要求：
- Conventional Commits 格式
- type 从 feat/fix/docs/style/refactor/perf/test/chore 中选择
- description 用英文，首字母小写，不加句号
- 只输出 commit message，不要解释

// src/commands/commit.ts
const maxDiffLength = 8000
const truncatedDiff = diff.length > maxDiffLength
  ? diff.slice(0, maxDiffLength) + '\n\n... (diff 过长，已截断)'
  : diff

function truncateDiff(diff: string, maxLength: number): string {
  if (diff.length <= maxLength) return diff
 
  // 按文件分割 diff
  const fileDiffs = diff.split(/^diff --git/m).filter(Boolean)
 
  let result = ''
  let remaining = maxLength
 
  for (const fileDiff of fileDiffs) {
    const chunk = 'diff --git' + fileDiff
    if (chunk.length <= remaining) {
      result += chunk
      remaining -= chunk.length
    } else {
      result += `\n\n... (${fileDiffs.length - result.split('diff --git').length + 1} 个文件的 diff 已省略)`
      break
    }
  }
 
  return result
}

// 概念性示例
const MODEL_MAP = {
  commit: 'doubao-lite-128k',    // 轻量模型，生成 commit message 足够
  explain: 'doubao-1-5-pro-32k-250115', // 标准模型，代码解读
  review: 'doubao-1-5-pro-32k-250115',  // 标准模型，code review 需要深度理解
}

// src/commands/explain.ts
program
  .command('explain <file>')
  .description('AI 解读指定文件的代码')
  .option('--no-stream', '关闭流式输出')
  .option('-l, --language <lang>', '输出语言', 'zh')

// src/commands/explain.ts
const filePath = path.resolve(file)
 
if (!fs.existsSync(filePath)) {
  throw new UserError(`文件不存在: ${filePath}`)
}
 
const stat = fs.statSync(filePath)
if (stat.size > 100 * 1024) {
  throw new UserError('文件过大（超过 100KB），请指定一个更小的文件')
}

// src/commands/explain.ts
const messages = [
  {
    role: 'system' as const,
    content: `你是一个资深的代码审查专家。用户会给你一段代码，请你解读这段代码的功能、设计思路和关键实现细节。${langInstruction}
要求：
- 先用一句话总结这段代码的核心作用
- 再逐段分析关键逻辑
- 指出值得关注的设计模式或技巧
- 如果有潜在问题或改进空间，也一并指出
保持简洁，不要重复代码。`,
  },
  {
    role: 'user' as const,
    content: `请解读以下代码：\n\n文件: ${file}\n\n\`\`\`${ext.replace('.', '')}\n${content}\n\`\`\``,
  },
]

$ repox explain src/core/api-client.ts
 
代码解读: src/core/api-client.ts
 
这是一个基于中间件模式的 HTTP 客户端，支持认证注入、自动重试和请求日志。
 
核心设计采用了中间件链（Middleware Chain）模式。Middleware 类型定义了
(url, options, next) => Promise<Response> 的签名，每个中间件可以在
调用 next 前后插入自定义逻辑...

// src/commands/commit.ts
const stagedFiles = getStagedFiles()
if (stagedFiles.length === 0) {
  throw new UserError(
    '暂存区没有文件',
    '请先使用 git add 添加要提交的文件',
  )
}

// src/commands/commit.ts
const diff = getStagedDiff()
const maxDiffLength = 8000
const truncatedDiff = diff.length > maxDiffLength
  ? diff.slice(0, maxDiffLength) + '\n\n... (diff 过长，已截断)'
  : diff

// src/commands/commit.ts
const spinner = ora('AI 正在分析变更...').start()
const commitMessage = await chat(client, config.ai.model, messages)
spinner.stop()

// src/commands/commit.ts
const action = await confirm({
  message: '使用这条 commit message 提交？',
  default: true,
})
 
if (!action) {
  const edited = await input({
    message: '输入你的 commit message（留空取消）',
    default: commitMessage,
  })
  if (!edited) {
    logger.info('已取消')
    return
  }
  finalMessage = edited
}

// src/commands/commit.ts
createCommit(finalMessage)
logger.success('提交成功')

$ repox commit --dry-run
暂存区有 3 个文件待提交:
  + src/core/api-client.ts
  + src/core/error.ts
  + src/commands/deps.ts
 
生成的 commit message:
 
  feat(core): add middleware-based API client with retry and auth support
 
(dry-run 模式，不会执行 commit)

const useStream = options.stream && process.stdout.isTTY

try {
  for await (const chunk of chatStream(client, model, messages)) {
    process.stdout.write(chunk)
  }
} catch (error) {
  if (error.name === 'AbortError') {
    process.stdout.write('\n')
    // 用户中断，静默退出
    return
  }
  throw error
}