paseo-plugin-chat-view 0.0.0-stage → 0.1.0

package/shared/enhance/enhance.test.ts

@@ -0,0 +1,188 @@
+import { expect, it, vi } from "vitest";
+import {
+  buildEnhanceMessages,
+  decideEnhancement,
+  derivePolicy,
+  ENHANCE_SYSTEM_PROMPT,
+  MAX_ENHANCED_CHARS,
+  normalizeRaw,
+  parseEnhanceOutput,
+  runEnhancement,
+  type EnhanceProvider,
+  type EnvironmentProfile,
+} from "./index";
+
+function profile(overrides: Partial<EnvironmentProfile> = {}): EnvironmentProfile {
+  return {
+    root: "/repo",
+    projectKind: "frontend",
+    languages: ["typescript"],
+    packageManagers: ["pnpm"],
+    frameworks: ["react"],
+    commands: { build: "pnpm build", test: "pnpm test" },
+    conventions: ["测试与源码同目录"],
+    constraints: ["Node >= 20"],
+    hotspots: [{ path: "shared/enhance", reason: "本次改动最相关" }],
+    references: [{ path: "README.md", excerpt: "插件通过公开 SDK 接入" }],
+    ...overrides,
+  };
+}
+
+const completion = (body: string): EnhanceProvider => ({ complete: vi.fn(async () => body) });
+
+const wrapped = (enhanced: string, delta = "补齐了验收标准", open = "无") =>
+  `<enhanced_prompt>${enhanced}</enhanced_prompt>` +
+  `<delta_summary>${delta}</delta_summary>` +
+  `<open_questions>${open}</open_questions>`;
+
+it("normalizes cosmetic noise while keeping markdown hard breaks", () => {
+  expect(normalizeRaw("　修复​ 登录\r\n\r\n\r\n结束")).toBe("修复 登录\n\n结束");
+  expect(normalizeRaw("  a  \n  b  ")).toBe("a  \n  b");
+});
+
+it("asks for expansion on a vague one-liner and keeps an already structured prompt", () => {
+  const vague = decideEnhancement("加个缓存");
+  expect(vague.enhance).toBe(true);
+  expect(vague.missing).toContain("acceptance");
+  const structured = decideEnhancement(
+    "在 shared/enhance/policy.ts 实现 monorepo 目标包映射，必须保持现有导出签名不变，验收运行 pnpm test",
+  );
+  expect(structured.enhance).toBe(false);
+  expect(structured.present).toContain("acceptance");
+  expect(decideEnhancement("ok").enhance).toBe(false);
+});
+
+it("derives environment focus and never invents a command the probe did not find", () => {
+  const frontend = derivePolicy(profile());
+  expect(frontend.focus.join()).toContain("交互状态");
+  expect(frontend.acceptance).toContain("`pnpm test`");
+  expect(frontend.constraints.join()).toContain("不引入新的 UI 依赖");
+  const library = derivePolicy(profile({ projectKind: "library" }));
+  expect(library.constraints.join()).toContain("不得破坏已导出的公开签名");
+  const bare = derivePolicy(profile({ projectKind: "unknown", commands: {} }));
+  expect(bare.focus).toEqual([]);
+  expect(bare.acceptance).toContain("人工核对");
+  expect(bare.acceptance).not.toContain("`");
+});
+
+it("keeps the system prompt byte-identical across differing environments", () => {
+  const first = buildEnhanceMessages({
+    raw: "a",
+    missing: [],
+    profile: profile(),
+    policy: derivePolicy(profile()),
+  });
+  const second = buildEnhanceMessages({
+    raw: "b",
+    missing: ["验收标准"],
+    profile: profile({ projectKind: "backend", root: "/other" }),
+    policy: derivePolicy(profile({ projectKind: "backend" })),
+  });
+  expect(first[0]).toEqual({ role: "system", content: ENHANCE_SYSTEM_PROMPT });
+  expect(second[0]).toEqual(first[0]);
+  expect(first[1]!.content).toContain("kind: frontend");
+  expect(second[1]!.content).toContain("kind: backend");
+  expect(second[1]!.content).toContain("验收标准");
+});
+
+it("parses a well-formed completion into an applied result", () => {
+  const result = parseEnhanceOutput(
+    wrapped("增强后的正文", "补了范围", "- 是否兼容旧版"),
+    "原文",
+    [],
+    "zh-CN",
+  );
+  expect(result).toMatchObject({ applied: true, degraded: false, enhanced: "增强后的正文" });
+  expect(result.openQuestions).toEqual(["是否兼容旧版"]);
+  expect(parseEnhanceOutput(wrapped("x"), "x", [], "zh-CN")).toMatchObject({
+    applied: false,
+    degraded: false,
+  });
+});
+
+it("degrades instead of throwing when the model misbehaves", () => {
+  expect(parseEnhanceOutput("没有标签的输出", "原文", ["验收标准"], "zh-CN")).toMatchObject({
+    enhanced: "原文",
+    applied: false,
+    degraded: true,
+    openQuestions: ["验收标准"],
+  });
+  expect(parseEnhanceOutput(wrapped("x", "x", "无"), "x", [], "zh-CN").openQuestions).toEqual([]);
+});
+
+it("caps the body at one flat ceiling regardless of input length", () => {
+  // The cap must not track the input: a 4-character prompt is the case that most needs expanding,
+  // and scaling the ceiling with the input is what used to return a 12-character stub.
+  expect(parseEnhanceOutput(wrapped("长".repeat(900)), "原文", [], "zh-CN").enhanced.length).toBe(
+    MAX_ENHANCED_CHARS,
+  );
+  // A body within the ceiling is delivered whole and carries no truncation notice.
+  const whole = parseEnhanceOutput(wrapped("长".repeat(120)), "原文", [], "zh-CN");
+  expect(whole.enhanced.length).toBe(120);
+  expect(whole.truncated).toBe(false);
+});
+
+it("flags a shortened body so the client can say so", () => {
+  const result = parseEnhanceOutput(wrapped("长".repeat(900), "补了范围"), "原文", [], "zh-CN");
+  expect(result.truncated).toBe(true);
+  // The notice is client-side wording in the reader's language, so the summary stays the model's.
+  expect(result.deltaSummary).toBe("补了范围");
+});
+
+it("leaves a prompt longer than the ceiling alone rather than returning less than was written", () => {
+  const long = "长".repeat(MAX_ENHANCED_CHARS + 40);
+  const decision = decideEnhancement(long);
+  expect(decision.enhance).toBe(false);
+  expect(decision.skip).toBe("tooLong");
+});
+
+it("runs the pipeline and swallows provider failures into a degraded result", async () => {
+  const provider = completion(wrapped("完整提示词：目标、范围、约束、验收"));
+  const applied = await runEnhancement({ raw: "加个缓存", profile: profile(), provider });
+  expect(applied.applied).toBe(true);
+  expect(provider.complete).toHaveBeenCalledOnce();
+
+  const failing: EnhanceProvider = {
+    complete: vi.fn(async () => {
+      throw new Error("连接超时");
+    }),
+  };
+  const degraded = await runEnhancement({ raw: "加个缓存", profile: profile(), provider: failing });
+  expect(degraded).toMatchObject({ enhanced: "加个缓存", applied: false, degraded: true });
+  expect(degraded.degradedReason).toContain("连接超时");
+  expect(degraded.openQuestions.length).toBeGreaterThan(0);
+});
+
+it("words its reasons in the caller's language", async () => {
+  const provider = completion(wrapped("不应被调用"));
+  const skipped = await runEnhancement({
+    raw: "ok",
+    profile: profile(),
+    provider,
+    locale: "en-US",
+  });
+  expect(skipped.degradedReason).toBe("The prompt is too short to expand");
+  const failing: EnhanceProvider = {
+    complete: vi.fn(async () => {
+      throw new Error("boom");
+    }),
+  };
+  const degraded = await runEnhancement({
+    raw: "加个缓存",
+    profile: profile(),
+    provider: failing,
+    locale: "en-US",
+  });
+  expect(degraded.degradedReason).toBe("Model call failed: boom");
+});
+
+it("skips the model entirely when the raw input is already executable", async () => {
+  const provider = completion(wrapped("不应被调用"));
+  const result = await runEnhancement({
+    raw: "在 shared/enhance/policy.ts 实现 monorepo 目标包映射，必须保持现有导出签名不变，验收运行 pnpm test",
+    profile: profile(),
+    provider,
+  });
+  expect(result.applied).toBe(false);
+  expect(provider.complete).not.toHaveBeenCalled();
+});

package/shared/enhance/failure.ts

@@ -0,0 +1,40 @@
+import { t, type SupportedLocale } from "../i18n";
+
+/**
+ * Why a completion request failed, as data rather than prose. The provider throws this without
+ * knowing who is reading, and the text is rendered where the language is known — which is also
+ * what lets the connection probe classify a failure without pattern-matching localized sentences.
+ */
+export type ProviderFailureKind = "http" | "timeout" | "truncatedOutput" | "emptyResponse";
+
+export class ProviderFailure extends Error {
+  readonly kind: ProviderFailureKind;
+  /** The raw detail: the endpoint's own body, or the timeout in milliseconds as a string. */
+  readonly detail: string;
+  readonly status?: number;
+
+  constructor(kind: ProviderFailureKind, detail: string, status?: number) {
+    super(detail ? `${kind}: ${detail}` : kind);
+    this.name = "ProviderFailure";
+    this.kind = kind;
+    this.detail = detail;
+    this.status = status;
+  }
+}
+
+/** The one place a provider failure becomes a sentence. */
+export function providerFailureMessage(locale: SupportedLocale, failure: ProviderFailure): string {
+  switch (failure.kind) {
+    case "http":
+      return t(locale, "enhance.failure.http", {
+        status: failure.status ?? "?",
+        detail: failure.detail,
+      });
+    case "timeout":
+      return t(locale, "enhance.failure.timeout", { ms: failure.detail });
+    case "truncatedOutput":
+      return t(locale, "enhance.failure.truncatedOutput");
+    case "emptyResponse":
+      return t(locale, "enhance.failure.emptyResponse");
+  }
+}

package/shared/enhance/index.ts

@@ -0,0 +1,8 @@
+export * from "./contract";
+export * from "./decide";
+export * from "./failure";
+export * from "./normalize";
+export * from "./parse";
+export * from "./policy";
+export * from "./prompt";
+export * from "./run";

package/shared/enhance/normalize.ts

@@ -0,0 +1,16 @@
+const ZERO_WIDTH = /[\u200B-\u200D\u2060\uFEFF]/g;
+const FULL_WIDTH_SPACE = /\u3000/g;
+const EXCESS_BLANK_LINES = /\n{3,}/g;
+
+/**
+ * Collapse cosmetic noise without rewriting wording. Trailing spaces are kept because two of
+ * them are a hard line break in Markdown.
+ */
+export function normalizeRaw(raw: string): string {
+  return raw
+    .replace(ZERO_WIDTH, "")
+    .replace(FULL_WIDTH_SPACE, " ")
+    .replace(/\r\n?/g, "\n")
+    .replace(EXCESS_BLANK_LINES, "\n\n")
+    .trim();
+}

package/shared/enhance/parse.ts

@@ -0,0 +1,79 @@
+import { t, type SupportedLocale } from "../i18n";
+import { MAX_ENHANCED_CHARS, type EnhanceResult } from "./contract";
+import { normalizeRaw } from "./normalize";
+
+const ENHANCED_BLOCK = /<enhanced_prompt>([\s\S]*?)<\/enhanced_prompt>/i;
+const DELTA_BLOCK = /<delta_summary>([\s\S]*?)<\/delta_summary>/i;
+const OPEN_BLOCK = /<open_questions>([\s\S]*?)<\/open_questions>/i;
+const NOTHING = /^(无|none|n\/a|无。|-)$/i;
+
+/** A failed enhancement must still land something usable in the composer, never an exception. */
+export function degradedResult(
+  original: string,
+  reason: string,
+  missing: string[] = [],
+): EnhanceResult {
+  return {
+    enhanced: original,
+    deltaSummary: "",
+    openQuestions: missing,
+    applied: false,
+    degraded: true,
+    degradedReason: reason,
+    truncated: false,
+  };
+}
+
+/** The pre-check already decided the raw input is executable; keep it byte-identical. */
+export function unchangedResult(original: string, reason: string): EnhanceResult {
+  return {
+    enhanced: original,
+    deltaSummary: "",
+    openQuestions: [],
+    applied: false,
+    degraded: false,
+    degradedReason: reason,
+    truncated: false,
+  };
+}
+
+/**
+ * `locale` only reaches the reason strings; the delivered text is the model's own. Callers that
+ * have a language to show must pass it, or a failure reads as Chinese to an English reader.
+ */
+export function parseEnhanceOutput(
+  raw: string,
+  original: string,
+  missing: string[],
+  locale: SupportedLocale,
+): EnhanceResult {
+  const enhanced = ENHANCED_BLOCK.exec(raw)?.[1]?.trim() ?? "";
+  if (!enhanced) return degradedResult(original, t(locale, "enhance.reason.noBody"), missing);
+  const limit = MAX_ENHANCED_CHARS;
+  const truncated = enhanced.length > limit;
+  const body = truncated ? truncate(enhanced, limit) : enhanced;
+  if (body === normalizeRaw(original))
+    return unchangedResult(original, t(locale, "enhance.reason.equivalent"));
+  return {
+    enhanced: body,
+    deltaSummary: DELTA_BLOCK.exec(raw)?.[1]?.trim() ?? "",
+    openQuestions: parseOpenQuestions(OPEN_BLOCK.exec(raw)?.[1] ?? ""),
+    applied: true,
+    degraded: false,
+    degradedReason: "",
+    truncated,
+  };
+}
+
+function parseOpenQuestions(block: string): string[] {
+  return block
+    .split("\n")
+    .map((line) => line.replace(/^\s*[-*\d.、]+\s*/, "").trim())
+    .filter((line) => line.length > 0 && !NOTHING.test(line));
+}
+
+function truncate(text: string, limit: number): string {
+  const kept = text.slice(0, limit);
+  const lastOpen = kept.lastIndexOf("<");
+  return lastOpen > limit - 40 ? kept.slice(0, lastOpen) : kept;
+}

package/shared/enhance/policy.ts

@@ -0,0 +1,48 @@
+import type { EnvironmentProfile, ProjectKind } from "./contract";
+
+export interface EnhancePolicy {
+  /** Environment-specific dimensions appended to the four required ones. */
+  focus: string[];
+  /** Acceptance guidance limited to commands the probe actually found. */
+  acceptance: string;
+  /** Environment-specific hard constraints passed through verbatim. */
+  constraints: string[];
+}
+
+const KIND_FOCUS: Record<ProjectKind, readonly string[]> = {
+  frontend: ["交互状态（空/加载/错误/边界）", "响应式断点", "可访问性", "视觉一致性"],
+  backend: ["输入校验与错误码", "幂等性", "数据迁移与向后兼容", "并发与超时"],
+  cli: ["命令与参数接口", "退出码", "--help 文案", "破坏性变更的确认提示"],
+  library: ["公开 API 稳定性与导出面", "副作用边界", "可运行示例"],
+  monorepo: ["明确目标包与路径", "跨包改动的影响面", "构建顺序与依赖约束"],
+  docs: ["目标读者与阅读路径", "章节结构与锚点", "示例可执行性"],
+  unknown: [],
+};
+
+const KIND_CONSTRAINTS: Record<ProjectKind, readonly string[]> = {
+  frontend: ["沿用现有组件库与样式体系，不引入新的 UI 依赖"],
+  backend: ["接口变更需保持向后兼容，或同时给出迁移方案"],
+  cli: ["不得静默改变既有退出码与参数解析"],
+  library: ["不得破坏已导出的公开签名"],
+  monorepo: ["变更需限定到具体包，避免影响其他包的构建产物"],
+  docs: [],
+  unknown: [],
+};
+
+const COMMAND_ORDER = ["build", "typecheck", "lint", "test"] as const;
+
+/** Read-only projection of the profile; the model receives evidence, not conclusions. */
+export function derivePolicy(profile: EnvironmentProfile): EnhancePolicy {
+  const focus = [...KIND_FOCUS[profile.projectKind]];
+  const constraints = [...KIND_CONSTRAINTS[profile.projectKind], ...profile.constraints];
+  const found = COMMAND_ORDER.filter((name) => profile.commands[name]).map(
+    (name) => `${name}: \`${profile.commands[name]}\``,
+  );
+  return {
+    focus,
+    acceptance: found.length
+      ? `验收只能引用这些已存在的命令：${found.join("、")}`
+      : "仓库未发现标准验证命令，验收标准改写为可人工核对的现象",
+    constraints,
+  };
+}

package/shared/enhance/prompt.ts

@@ -0,0 +1,134 @@
+import type { EnvironmentProfile } from "./contract";
+import type { EnhancePolicy } from "./policy";
+
+/**
+ * Byte-stable on purpose: every volatile detail (raw input, environment, policy) lives in the
+ * user message, so provider-side prefix caching keeps hitting across projects and runs.
+ * Edit the text and bump RULE_VERSION together — tests assert on rule ids, not on prose.
+ */
+export const ENHANCE_RULE_VERSION = 3;
+
+export const ENHANCE_SYSTEM_PROMPT = `你是一个提示词增强器。你不是编程助手，不回答用户的任务本身，只产出指令。
+
+# 唯一职责
+把 <raw> 改写为一份可以直接交给编码 AI 执行、无需追问即可开工的提示词。
+
+# 输入契约
+<raw> 用户原始诉求
+<missing> 原始诉求尚未覆盖的维度
+<context> 项目环境画像（可能为空，或 kind 为 unknown）
+<policy> 由环境推导出的补充维度、验收限制与硬约束
+缺失即未知，禁止假设；禁止编造文件路径、命令、依赖、版本。
+
+# 判定先行
+依据 <missing> 判断：
+- 缺 goal（未说明要做什么动作），或缺 2 项以上维度：执行增强。
+- 四个维度基本齐备：原样返回 raw，禁止同义改写造句。
+
+# 四个必填维度
+每项一行，冒号后直接给内容，不加解释、不举例：
+1 goal：目标与成功判据。
+2 scope：范围与边界，明确不做什么。
+3 constraints：约束，含技术栈、版本、性能、兼容、不可破坏项。
+4 acceptance：验收与验证方式。
+另按 <policy> 的 focus 补充环境相关维度；acceptance 只能引用 policy 限定的命令。
+
+# 环境适配规则
+- 必须使用 context 中出现的真实技术栈名与真实命令，不得替换为"你使用的框架"或"常用命令"。
+- 验收只能引用 policy.acceptance 列出的命令；不存在验证命令时不得编造命令名。
+- context 中的 constraints 视为硬约束，必须原样保留。
+- 优先用 context 的 hotspots 路径锚定范围。
+- context 的 kind 为 unknown 时不做环境偏置，并把"技术栈未知"列入 open_questions。
+- references 是项目自己的文档，与 context 一致；冲突时以 context 为准。
+
+# 硬约束
+不改变用户原意；不引入用户未要求的目标；不输出解决方案代码，只输出提示词正文；
+未知处写 {{待确认}} 并列入 open_questions；语言跟随用户原文语言；
+正文不超过 200 字。宁可少写一句，也要把四个维度都写全——写满 200 字但缺维度，等于没写。
+
+# 输出格式
+只输出以下结构，不加任何解释：
+<enhanced_prompt>增强后的提示词正文</enhanced_prompt>
+<delta_summary>一句话说明补了什么，50 字以内</delta_summary>
+<open_questions>每行一条待确认项，没有就写"无"</open_questions>
+
+# 静默自检
+输出前自查，不把自查过程写进产物：
+是否存在凭空事实？是否混入用户没要求的目标？能否独立执行无需追问？是否与 context 冲突？
+任一不过则重写后再输出。`;
+
+export interface EnhanceMessage {
+  role: "system" | "user";
+  content: string;
+}
+
+export interface EnhancePromptInput {
+  raw: string;
+  missing: string[];
+  profile: EnvironmentProfile;
+  policy: EnhancePolicy;
+}
+
+export function buildEnhanceMessages(input: EnhancePromptInput): EnhanceMessage[] {
+  return [
+    { role: "system", content: ENHANCE_SYSTEM_PROMPT },
+    { role: "user", content: renderUserBlock(input) },
+  ];
+}
+
+export function renderUserBlock(input: EnhancePromptInput): string {
+  return [
+    "<raw>",
+    input.raw,
+    "</raw>",
+    "",
+    "<missing>",
+    input.missing.length ? input.missing.join("、") : "无",
+    "</missing>",
+    "",
+    "<context>",
+    renderProfile(input.profile),
+    "</context>",
+    "",
+    "<policy>",
+    `focus: ${input.policy.focus.length ? input.policy.focus.join("；") : "无"}`,
+    `acceptance: ${input.policy.acceptance}`,
+    `constraints: ${input.policy.constraints.length ? input.policy.constraints.join("；") : "无"}`,
+    "</policy>",
+  ].join("\n");
+}
+
+/** Only fields the probe actually filled; an absent fact is reported as absent, not as a guess. */
+function renderProfile(profile: EnvironmentProfile): string {
+  const lines: string[] = [`kind: ${profile.projectKind}`, `root: ${profile.root}`];
+  pushList(lines, "languages", profile.languages);
+  pushList(lines, "packageManagers", profile.packageManagers);
+  pushList(lines, "frameworks", profile.frameworks);
+  const commands: string[] = [];
+  for (const [name, command] of Object.entries(profile.commands))
+    if (command) commands.push(`${name}=${command}`);
+  if (commands.length) lines.push(`commands: ${commands.join("; ")}`);
+  pushList(lines, "conventions", profile.conventions);
+  pushList(lines, "constraints", profile.constraints);
+  if (profile.hotspots.length)
+    lines.push(
+      `hotspots: ${profile.hotspots.map((hotspot) => `${hotspot.path} (${hotspot.reason})`).join("; ")}`,
+    );
+  if (profile.references.length) {
+    lines.push("references:");
+    for (const reference of profile.references)
+      lines.push(`- ${reference.path}\n${indent(reference.excerpt, "  ")}`);
+  }
+  return lines.join("\n");
+}
+
+function pushList(lines: string[], label: string, values: readonly string[]) {
+  if (values.length) lines.push(`${label}: ${values.join(", ")}`);
+}
+
+function indent(text: string, prefix: string): string {
+  return text
+    .split("\n")
+    .map((line) => `${prefix}${line}`)
+    .join("\n");
+}

package/shared/enhance/run.ts

@@ -0,0 +1,84 @@
+import { t, type SupportedLocale } from "../i18n";
+import { MAX_ENHANCED_CHARS, type EnhanceResult, type EnvironmentProfile } from "./contract";
+import {
+  DIMENSION_KEYS,
+  DIMENSION_LABELS,
+  decideEnhancement,
+  type EnhanceDecision,
+} from "./decide";
+import { providerFailureMessage, ProviderFailure } from "./failure";
+import { normalizeRaw } from "./normalize";
+import { derivePolicy } from "./policy";
+import { degradedResult, parseEnhanceOutput, unchangedResult } from "./parse";
+import { buildEnhanceMessages, type EnhanceMessage } from "./prompt";
+
+/** The single seam the outside world plugs into: swap this and the core stays untouched. */
+export interface EnhanceProvider {
+  complete(messages: EnhanceMessage[]): Promise<string>;
+}
+
+export interface EnhanceRunInput {
+  raw: string;
+  profile: EnvironmentProfile;
+  provider: EnhanceProvider;
+  /** The reader's language; only the reasons depend on it. Defaults to Chinese. */
+  locale?: SupportedLocale;
+}
+
+export async function runEnhancement(input: EnhanceRunInput): Promise<EnhanceResult> {
+  const locale = input.locale ?? "zh-CN";
+  const original = normalizeRaw(input.raw);
+  const decision = decideEnhancement(original);
+  const missing = decision.missing.map((dimension) => DIMENSION_LABELS[dimension]);
+  if (!decision.enhance) return unchangedResult(original, describeSkip(locale, decision));
+  const policy = derivePolicy(input.profile);
+  let completion: string;
+  try {
+    const messages = buildEnhanceMessages({
+      raw: original,
+      missing,
+      profile: input.profile,
+      policy,
+    });
+    completion = await input.provider.complete(messages);
+  } catch (error) {
+    return degradedResult(original, describeFailure(locale, error), missing);
+  }
+  return parseEnhanceOutput(completion, original, missing, locale);
+}
+
+/** The pre-check's verdict, worded for the reader: which dimensions it found and which it missed. */
+function describeSkip(locale: SupportedLocale, decision: EnhanceDecision): string {
+  switch (decision.skip) {
+    case "tooShort":
+      return t(locale, "enhance.skip.tooShort");
+    case "alreadyStructured":
+      return t(locale, "enhance.skip.alreadyStructured");
+    case "missingDimensions":
+      return t(locale, "enhance.skip.missingDimensions", {
+        items: decision.missing
+          .map((dimension) => t(locale, DIMENSION_KEYS[dimension]))
+          .join(locale === "zh-CN" ? "、" : ", "),
+      });
+    case "tooLong":
+      return t(locale, "enhance.skip.tooLong", { limit: MAX_ENHANCED_CHARS });
+    default:
+      return t(locale, "enhance.unchanged");
+  }
+}
+
+function describeFailure(locale: SupportedLocale, error: unknown): string {
+  if (error instanceof ProviderFailure) return providerFailureMessage(locale, error);
+  return t(locale, "enhance.reason.providerFailed", { detail: describeError(error) });
+}
+
+/** Missing credentials are a configuration problem, not a model failure; keep the raw text. */
+export function notConfiguredResult(raw: string, locale: SupportedLocale): EnhanceResult {
+  const original = normalizeRaw(raw);
+  return degradedResult(original, t(locale, "enhance.reason.notConfigured"));
+}
+
+export function describeError(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}