附录 H：Agent 框架的 CI/CD 与配置管理

// → System Prompt 的版本管理
const SYSTEM_PROMPTS = {
  "v1.0.0": {
    hash: "sha256:a3f2b1c...",
    content: "你是一个编程助手。",
    released: "2026-05-01",
  },
  "v1.1.0": {
    hash: "sha256:d4e5f6a...",
    content: "你是一个代码审查专家。先读代码再分析。",
    released: "2026-05-15",
  },
}

function getActivePrompt(): string {
  // 从配置中读取当前激活的版本
  const version = config.get("systemPromptVersion") ?? "v1.0.0"
  return SYSTEM_PROMPTS[version].content
}

// → A/B 测试分流
class PromptABTester {
  private variants: Map<string, { prompt: string; traffic: number }>

  constructor() {
    this.variants = new Map([
      ["A", { prompt: "你是一个编程助手。", traffic: 0.95 }],
      ["B", { prompt: "你是一个代码审查专家。先读再分析。", traffic: 0.05 }],
    ])
  }

  getVariant(sessionId: string): string {
    // 确定性分流：同一会话始终同一 variant
    const hash = this.hashString(sessionId)
    const roll = hash % 100 / 100  // 0-1

    let cumulative = 0
    for (const [name, variant] of this.variants) {
      cumulative += variant.traffic
      if (roll <= cumulative) return variant.prompt
    }

    return this.variants.get("A")!.prompt  // fallback
  }

  private hashString(s: string): number {
    let hash = 0
    for (let i = 0; i < s.length; i++) {
      hash = ((hash << 5) - hash) + s.charCodeAt(i)
      hash |= 0
    }
    return Math.abs(hash)
  }
}

// 使用
const tester = new PromptABTester()
const prompt = tester.getVariant(sessionId)

// → 自动回滚守卫
function shouldRollback(
  variantAMetrics: AgentMetrics,
  variantBMetrics: AgentMetrics,
): boolean {
  // 条件 1：任务完成率下降 > 5%
  if (variantBMetrics.taskSuccessRate < variantAMetrics.taskSuccessRate - 0.05) {
    console.error("ROLLBACK: 任务完成率下降 > 5%")
    return true
  }

  // 条件 2：Token 消耗增加 > 30%
  if (variantBMetrics.avgTokensPerTask > variantAMetrics.avgTokensPerTask * 1.3) {
    console.error("ROLLBACK: Token 消耗增加 > 30%")
    return true
  }

  // 条件 3：错误率翻倍
  if (variantBMetrics.errorRate > variantAMetrics.errorRate * 2) {
    console.error("ROLLBACK: 错误率翻倍")
    return true
  }

  return false
}

// → config/loader.ts
import { readFileSync } from "fs"

interface AgentConfig {
  model: string
  maxTokens: number
  maxTurns: number
  maxCostPerSession: number
  caching: boolean
  thinking: "off" | "adaptive" | { budget: number }
}

function loadConfig(): AgentConfig {
  const env = process.env.AGENT_ENV ?? "development"

  // 1. 基础配置
  const base: AgentConfig = {
    model: "claude-sonnet-4-6",
    maxTokens: 32_000,
    maxTurns: 25,
    maxCostPerSession: 5.00,
    caching: true,
    thinking: "adaptive",
  }

  // 2. 环境特定配置
  const envOverrides: Record<string, Partial<AgentConfig>> = {
    development: {
      maxCostPerSession: 0.50,    // 开发时省钱
      thinking: "off",             // 关掉 thinking 加速
    },
    staging: {
      model: "claude-haiku-4-5",  // staging 用便宜模型
      maxCostPerSession: 2.00,
    },
    production: {
      model: "claude-sonnet-4-6",
      maxCostPerSession: 10.00,
    },
  }

  // 3. 环境变量覆盖（最高优先级）
  const envOverrides2: Partial<AgentConfig> = {}
  if (process.env.AGENT_MODEL) envOverrides2.model = process.env.AGENT_MODEL
  if (process.env.AGENT_MAX_COST) envOverrides2.maxCostPerSession = parseFloat(process.env.AGENT_MAX_COST)

  return { ...base, ...envOverrides[env], ...envOverrides2 }
}

// → 配置迁移
const MIGRATIONS: Record<string, (old: any) => any> = {
  "config-v1→config-v2": (old) => ({
    ...old,
    maxTurns: old.maxTurns ?? 25,          // 新增字段，给默认值
    caching: old.caching ?? true,
    // 删除字段：old.debugMode (不再支持)
  }),
}

function migrateConfig(config: any, from: string, to: string): any {
  const key = `${from}→${to}`
  const migration = MIGRATIONS[key]
  if (!migration) throw new Error(`未知的迁移路径: ${key}`)
  return migration(config)
}

// → src/my-agent/shutdown.ts
class GracefulShutdown {
  private shuttingDown = false
  private activeTasks = new Set<string>()

  constructor(private agent: AgentLoop) {
    // 监听 SIGTERM / SIGINT
    process.on("SIGTERM", () => this.handleShutdown("SIGTERM"))
    process.on("SIGINT", () => this.handleShutdown("SIGINT"))
  }

  private async handleShutdown(signal: string): Promise<void> {
    if (this.shuttingDown) {
      console.warn(`收到第二次 ${signal}，强制退出`)
      process.exit(1)  // 第二次信号直接退出
    }

    this.shuttingDown = true
    console.log(`收到 ${signal}，等待 ${this.activeTasks.size} 个活跃任务完成...`)

    // 1. 停止接收新请求
    server.close()

    // 2. 等待当前 turn 完成（最多 25 秒）
    const timeout = setTimeout(() => {
      console.error("优雅关闭超时，强制退出")
      process.exit(1)
    }, 25_000)

    // 3. 保存当前状态
    await this.agent.saveSnapshot()
    console.log("状态已保存")

    clearTimeout(timeout)
    process.exit(0)
  }

  // 每个工具调用前后更新活跃任务计数
  trackTask(taskId: string): () => void {
    this.activeTasks.add(taskId)
    return () => this.activeTasks.delete(taskId)  // 返回清理函数
  }
}

// 使用
const shutdown = new GracefulShutdown(agent)
const done = shutdown.trackTask("read-auth")
// ... 执行工具 ...
done()  // 标记完成

// → 健康检查：K8s liveness / readiness probe
import express from "express"

const app = express()

// Liveness：进程活着
app.get("/health", (_, res) => {
  res.json({ status: "ok", uptime: process.uptime() })
})

// Readiness：能处理请求
app.get("/ready", async (_, res) => {
  const checks = await Promise.all([
    checkApiKey().then(() => "api").catch(() => null),
    checkMcpConnections().then(() => "mcp").catch(() => null),
    checkModelAccess().then(() => "model").catch(() => null),
  ])

  const failed = checks.filter(c => c === null)
  if (failed.length > 0) {
    res.status(503).json({
      status: "not_ready",
      failed: checks.map((c, i) => c === null ? ["api","mcp","model"][i] : null).filter(Boolean),
    })
    return
  }

  res.json({ status: "ready" })
})

// 健康检查实现
async function checkApiKey(): Promise<void> {
  // 发一个 max_tokens=0 的空请求（等同缓存预热）
  await client.createMessage({
    model: "claude-haiku-4-5",
    max_tokens: 0,
    messages: [{ role: "user", content: "ping" }],
  })
}

async function checkMcpConnections(): Promise<void> {
  for (const [name, mcp] of mcpClients) {
    await mcp.ping()  // 每个 MCP 连接发心跳
  }
}

// → src/my-agent/circuit-breaker.ts
type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN"

class CircuitBreaker {
  private state: CircuitState = "CLOSED"
  private failures = 0
  private lastFailureTime = 0

  constructor(
    private threshold = 5,        // 连续 5 次失败 → 熔断
    private resetTimeout = 30_000, // 30 秒后尝试半开
  ) {}

  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === "OPEN") {
      if (Date.now() - this.lastFailureTime < this.resetTimeout) {
        throw new CircuitOpenError("熔断器已打开，拒绝请求")
      }
      this.state = "HALF_OPEN"  // 超时了，试试半开
    }

    try {
      const result = await fn()
      this.onSuccess()
      return result
    } catch (err) {
      this.onFailure()
      throw err
    }
  }

  private onSuccess(): void {
    this.failures = 0
    this.state = "CLOSED"
  }

  private onFailure(): void {
    this.failures++
    this.lastFailureTime = Date.now()
    if (this.failures >= this.threshold) {
      this.state = "OPEN"
      console.error(`熔断器打开：连续 ${this.failures} 次失败`)
    }
  }
}

class CircuitOpenError extends Error {
  constructor(msg: string) { super(msg) }
}

// 集成到 ApiClient
const breaker = new CircuitBreaker(5, 30_000)

async function safeApiCall(params: MessageCreateParams): Promise<MessageResponse> {
  return breaker.call(() => client.createMessage(params))
}