《互联网产品的 AI 架构·模型接入与能力边界》1.3 ai-lab：从需求到能力契约

// file: src/core/capability-spec.ts
// tier: L1
// verify: node --test test/core/capability-spec.test.ts

import type { QualityTier } from "./types.ts";

/** 能力失败时产品的处理方式，必须在契约里写死，不能留给调用方猜。 */
export type FailureMode = "fail-fast" | "degrade" | "queue" | "silent-skip";

export interface CapabilitySpec {
  /** 形如 "chat.reply" 的稳定标识，发布后不得复用。 */
  id: string;
  title: string;
  inputs: string[];
  outputs: string[];
  qualityTier: QualityTier;
  /** 端到端 P95 预算，毫秒（案例假设值）。 */
  latencyBudgetMs: number;
  /** 单次请求成本上限，微元（案例假设值）。 */
  costCeilingMicros: number;
  /** 评测集通过率下限，0..1（案例假设值）。 */
  minPassRate: number;
  onFailure: FailureMode;
  /** 降级路径；能力标识或 "template:xxx" 模板，按优先级排列。 */
  fallbacks: string[];
}

export interface SpecIssue {
  capability: string;
  field: string;
  message: string;
}

/** 「回声」本卷的五个能力，后续章节都围绕这份清单展开。 */
export const echoCapabilities: CapabilitySpec[] = [
  {
    id: "chat.reply",
    title: "私信智能回复草稿",
    inputs: ["thread.messages", "user.tone-profile"],
    outputs: ["reply.draft"],
    qualityTier: "standard",
    latencyBudgetMs: 2_500,
    costCeilingMicros: 1_200,
    minPassRate: 0.82,
    onFailure: "degrade",
    fallbacks: ["template:quick-replies"],
  },
  {
    id: "search.rerank",
    title: "内容搜索重排",
    inputs: ["query.text", "candidates.top50"],
    outputs: ["ranking.ids"],
    qualityTier: "standard",
    latencyBudgetMs: 300,
    costCeilingMicros: 400,
    minPassRate: 0.9,
    onFailure: "degrade",
    fallbacks: ["template:bm25-order"],
  },
  {
    id: "content.summarize",
    title: "长文摘要",
    inputs: ["article.body", "summary.length"],
    outputs: ["summary.text"],
    qualityTier: "standard",
    latencyBudgetMs: 6_000,
    costCeilingMicros: 3_000,
    minPassRate: 0.8,
    onFailure: "degrade",
    fallbacks: ["template:first-paragraph"],
  },
  {
    id: "moderation.classify",
    title: "内容审核分类",
    inputs: ["content.text", "content.images"],
    outputs: ["moderation.labels", "moderation.score"],
    qualityTier: "economy",
    latencyBudgetMs: 400,
    costCeilingMicros: 100,
    minPassRate: 0.95,
    onFailure: "fail-fast",
    fallbacks: [],
  },
  {
    id: "support.assist",
    title: "客服辅助回答",
    inputs: ["ticket.text", "faq.corpus"],
    outputs: ["answer.draft", "citations"],
    qualityTier: "frontier",
    latencyBudgetMs: 1_800,
    costCeilingMicros: 4_500,
    minPassRate: 0.85,
    onFailure: "degrade",
    fallbacks: ["chat.reply", "template:faq-snippet"],
  },
];

const CAPABILITY_ID = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/;

function issue(capability: string, field: string, message: string): SpecIssue {
  return { capability, field, message };
}

function hasDuplicates(values: string[]): boolean {
  return new Set(values).size !== values.length;
}

/**
 * 校验能力清单。返回空数组表示可以发布。
 * 校验只读，不修改输入，便于在 CI 里对同一份清单反复运行。
 */
export function validateCapabilitySpec(specs: CapabilitySpec[]): SpecIssue[] {
  const issues: SpecIssue[] = [];
  const ids = new Set<string>();

  if (specs.length === 0) {
    issues.push(issue("*", "spec", "能力清单不能为空"));
    return issues;
  }

  for (const spec of specs) {
    if (!CAPABILITY_ID.test(spec.id)) {
      issues.push(issue(spec.id || "*", "id", "能力标识必须形如 domain.action"));
    }
    if (ids.has(spec.id)) {
      issues.push(issue(spec.id, "id", "能力标识重复，发布后不得复用"));
    }
    ids.add(spec.id);

    if (spec.title.trim() === "") {
      issues.push(issue(spec.id, "title", "能力必须有面向产品的标题"));
    }
    if (spec.inputs.length === 0) {
      issues.push(issue(spec.id, "inputs", "输入契约不能为空"));
    }
    if (spec.outputs.length === 0) {
      issues.push(issue(spec.id, "outputs", "输出契约不能为空"));
    }
    if (hasDuplicates(spec.inputs) || hasDuplicates(spec.outputs)) {
      issues.push(issue(spec.id, "io", "输入或输出存在重复字段"));
    }
    if (spec.latencyBudgetMs <= 0) {
      issues.push(issue(spec.id, "latencyBudgetMs", "延迟预算必须为正"));
    }
    if (spec.costCeilingMicros <= 0) {
      issues.push(issue(spec.id, "costCeilingMicros", "成本上限必须为正"));
    }
    if (spec.minPassRate <= 0 || spec.minPassRate > 1) {
      issues.push(issue(spec.id, "minPassRate", "通过率下限必须落在 (0, 1]"));
    }
    if (spec.onFailure === "degrade" && spec.fallbacks.length === 0) {
      issues.push(issue(spec.id, "fallbacks", "degrade 必须给出至少一条降级路径"));
    }
    if (spec.onFailure === "fail-fast" && spec.fallbacks.length > 0) {
      issues.push(issue(spec.id, "fallbacks", "fail-fast 不应声明降级路径"));
    }
    if (spec.onFailure === "queue" && spec.latencyBudgetMs < 3_000) {
      issues.push(issue(spec.id, "latencyBudgetMs", "queue 模式需要至少 3000ms 的等待预算"));
    }
    if (spec.onFailure === "silent-skip") {
      issues.push(issue(spec.id, "onFailure", "silent-skip 会让调用方拿到空结果，不能作为能力失败模式"));
    }
    if (spec.fallbacks.includes(spec.id)) {
      issues.push(issue(spec.id, "fallbacks", "降级路径不能指向自身"));
    }
  }

  for (const spec of specs) {
    for (const fallback of spec.fallbacks) {
      if (fallback.startsWith("template:")) {
        continue;
      }
      if (!ids.has(fallback)) {
        issues.push(issue(spec.id, "fallbacks", `降级目标 ${fallback} 不在能力清单内`));
      }
    }
  }

  return issues;
}

/** 按标识取能力；调用方拿不到时应视为配置错误，而不是静默跳过。 */
export function findCapability(specs: CapabilitySpec[], id: string): CapabilitySpec | undefined {
  return specs.find((spec) => spec.id === id);
}

node --test test/core/capability-spec.test.ts

✔ 回声的五个能力通过契约校验 (0.951833ms)
✔ 能力标识必须符合 domain.action 且不可重复 (0.259625ms)
✔ degrade 必须给出降级路径 (0.474833ms)
✔ fail-fast 不允许声明降级路径 (0.117583ms)
✔ 降级目标必须存在或使用 template 前缀 (0.105584ms)
✔ 通过率、延迟与成本必须落在合法区间 (0.103417ms)
✔ queue 模式需要足够的等待预算 (0.089041ms)
✔ silent-skip 不能作为能力失败模式 (0.073041ms)
✔ findCapability 按标识查找，未知标识返回 undefined (0.082458ms)
ℹ tests 9
ℹ suites 0
ℹ pass 9
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 179.688292