01-Prompt工程基本原则

// src/routes/chat.ts — 第 12 章的骨架
chatApp.post('/chat', authMiddleware, rateLimit, async (c) => {
  const body = await c.req.json()
  const { model, messages, stream, system_prompt } = body
 
  const context = buildContextWindow(messages, getModelContextLimit(model))
  if (system_prompt) context.unshift({ role: 'system', content: system_prompt })
 
  const result = await callModelAPI({ model, messages: context })
  // ...
})

// 文案思路的 Prompt ❌
const prompt = `
你是一个非常聪明的 AI 助手，拥有丰富的编程经验。
请用你的专业知识帮助用户解决编程问题，给出详细而有深度的回答。
记住，要尽可能帮助用户理解问题的本质。
`
 
// 任务说明书思路的 Prompt ✅
const prompt = `
你是一个 TypeScript 代码审查助手。
 
输入：用户提交的 TypeScript 代码片段。
 
你需要完成以下检查：
1. 类型安全问题（any 滥用、类型断言、空值未处理）
2. 逻辑错误（边界条件、循环终止、异步错误处理）
3. 性能问题（不必要的循环、内存泄漏风险）
 
输出格式：
- 如果没有问题，输出「代码审查通过，无需修改」
- 如果有问题，按严重程度排序，每个问题用以下格式：
  **[严重/警告/建议]** 问题描述
  代码位置：第 N 行
  修改方案：（代码块）
 
不要编造不存在的问题。如果代码量超过 200 行，只报告严重和警告级别的问题。
`

// 模糊 ❌
const prompt = '分析一下这段代码'
 
// 具体 ✅
const prompt = '检查以下 TypeScript 函数是否存在类型安全问题。只报告 any 类型滥用和未处理的 null/undefined 两种情况。'

// 缺少上下文 ❌
const prompt = '把这个字段名改成更合适的名字'
 
// 补全上下文 ✅
const prompt = `
以下是一个电商订单系统的 TypeScript 类型定义。
字段命名规范：
- 使用 camelCase
- 金额字段后缀 Amount，单位是分（integer）
- 时间字段后缀 At，使用 ISO 8601 字符串
- 布尔字段用 is/has/can 前缀
 
请根据以上规范，修改以下类型定义中的不规范字段名：
${typeDefinition}
`

// 不约束格式 ❌ — 模型可能输出散文、列表、带标题的 Markdown
const prompt = '列出这段代码的三个问题'
 
// 约束格式 ✅ — 下游 JSON.parse 能稳定执行
const prompt = `
列出这段代码的问题，以 JSON 数组输出，每个元素结构如下：
{
  "severity": "error" | "warning" | "suggestion",
  "line": number,
  "message": string,
  "fix": string | null
}
只输出 JSON，不要添加其他说明。
`

const prompt = `
将用户的自然语言需求翻译成 SQL 查询。
 
示例：
用户需求：「最近 7 天注册的用户数」
SQL：SELECT COUNT(*) FROM users WHERE created_at >= NOW() - INTERVAL '7 days'
 
用户需求：「订单金额超过 1000 元的用户」
SQL：SELECT DISTINCT user_id FROM orders WHERE amount > 100000
 
用户需求：${userRequirement}
SQL：
`

// src/services/prompt/code-review.ts
import { Hono } from 'hono'
 
// 把五条原则落到一个具体 Prompt 上
const CODE_REVIEW_PROMPT = `你是一个 TypeScript 代码审查助手。
 
## 输入
用户提交的 TypeScript 代码片段。
 
## 检查范围
按优先级排序：
1. 类型安全问题：any 滥用、未标注返回值类型、不安全的类型断言
2. 空值处理：未处理的 null/undefined、可选链缺失
3. 异步错误：await 缺少 try-catch、Promise 未处理 rejection
 
## 输出格式
JSON 数组，每个元素：
{
  "severity": "error" | "warning" | "suggestion",
  "line": number,
  "column": number | null,
  "message": string,
  "fix": string | null
}
 
## 约束
- 没有问题时输出空数组 []
- 不要编造不存在的问题
- 最多报告 10 个问题，按严重程度排序
- 只输出 JSON，不要 Markdown 代码块标记`
 
export type ReviewResult = {
  severity: 'error' | 'warning' | 'suggestion'
  line: number
  column: number | null
  message: string
  fix: string | null
}
 
export async function reviewCode(code: string): Promise<ReviewResult[]> {
  const messages = [
    { role: 'system', content: CODE_REVIEW_PROMPT },
    { role: 'user', content: code },
  ]
 
  const response = await callModelAPI({
    model: 'gpt-4o',
    messages,
    temperature: 0,  // 审查任务要确定性，不要随机性
    response_format: { type: 'json_object' },
  })
 
  // response_format 保证了输出是合法 JSON，但内容结构还要自己校验
  return parseReviewResult(response.choices[0].message.content)
}
 
function parseReviewResult(raw: string): ReviewResult[] {
  try {
    const parsed = JSON.parse(raw)
    if (!Array.isArray(parsed)) return []
    return parsed.filter(isValidReviewResult)
  } catch {
    return []
  }
}
 
function isValidReviewResult(item: unknown): item is ReviewResult {
  if (typeof item !== 'object' || item === null) return false
  const obj = item as Record<string, unknown>
  return (
    (obj.severity === 'error' || obj.severity === 'warning' || obj.severity === 'suggestion') &&
    typeof obj.line === 'number' &&
    typeof obj.message === 'string'
  )
}
 
// Hono 路由
const app = new Hono()
 
app.post('/review', async (c) => {
  const { code } = await c.req.json()
  if (typeof code !== 'string' || code.length === 0) {
    return c.json({ error: 'code is required' }, 400)
  }
  if (code.length > 5000) {
    return c.json({ error: 'code too long, max 5000 chars' }, 400)
  }
 
  const results = await reviewCode(code)
  return c.json({ results })
})
 
export default app