feat(web): 角色群像按定位配比生成（role_mix 缩减版）

- 契约: CharacterGenerateRequest 加 role_mix{定位:数量}，model_validator 归一
  count=各值之和（每项≥1、总和≤12），缺省退回单一 role+count
- @llm: build_character_gen_context/run_character_gen 加 role_mix 参并注入配比块
  （确定性、无时间戳，守 assemble 纯函数）；router 穿参
- character-gen.md 加"按配比严格分配 role"纪律 + regen prompt_hashes 金标准
- 前端: sanitizeRoleMix/roleMixTotal + buildCharacterGenerateRequest 第4参 +
  useCharacterGen 穿参 + RoleMixEditor + CharacterGenerator 单一/配比双模

apps/web/lib/api/schema.d.ts

@@ -997,6 +997,10 @@ export interface components {
         /**
          * CharacterGenerateRequest
          * @description POST /projects/:id/characters/generate：据需求生成角色卡（预览，群像防雷同）。
+         *
+         *     `role_mix`（⑦ 群像按定位配比）与 `count` 的关系：`role_mix` 在场时 `count` 取各值之和
+         *     （忽略客户端显式 count），每项数量须 ≥ 1、总和须 ≤ `MAX_GENERATE_COUNT`；缺省则退回
+         *     单一 `role` + `count` 语义。
          */
         CharacterGenerateRequest: {
             /**
@@ -1006,7 +1010,7 @@ export interface components {
             brief: string;
             /**
              * Count
-             * @description 生成数量
+             * @description 生成数量（role_mix 在场时取各值之和）
              * @default 1
              */
             count: number;
@@ -1015,6 +1019,13 @@ export interface components {
              * @description 角色定位（主角/CP/对手/导师/工具人 等）
              */
             role?: string | null;
+            /**
+             * Role Mix
+             * @description 按定位配比生成 {定位: 数量}；在场时 count=各值之和（每项≥1、总和≤12）
+             */
+            role_mix?: {
+                [key: string]: number;
+            } | null;
         };
         /**
          * CharacterIngestRequest

apps/web/lib/generation/cards.test.ts

@@ -16,6 +16,8 @@ import {
   mergeCharacterCards,
   mergeWorldEntities,
   MIN_CHARACTER_COUNT,
+  roleMixTotal,
+  sanitizeRoleMix,
   updateCard,
   worldEntityRules,
 } from "./cards";
@@ -62,6 +64,62 @@ describe("buildCharacterGenerateRequest", () => {
       role: "对手",
     });
   });
+
+  it("uses role_mix (count=sum, no single role) when a mix is supplied", () => {
+    expect(
+      buildCharacterGenerateRequest("群像", 1, "忽略", {
+        主角: 1,
+        对手: 2,
+        配角: 3,
+      }),
+    ).toEqual({
+      brief: "群像",
+      count: 6,
+      role_mix: { 主角: 1, 对手: 2, 配角: 3 },
+    });
+  });
+
+  it("falls back to count/role when role_mix is empty", () => {
+    expect(buildCharacterGenerateRequest("群像", 4, "主角", {})).toEqual({
+      brief: "群像",
+      count: 4,
+      role: "主角",
+    });
+  });
+});
+
+describe("sanitizeRoleMix", () => {
+  it("trims roles, drops blanks, clamps counts to >=1, dedups", () => {
+    expect(
+      sanitizeRoleMix([
+        { role: "  主角  ", count: 2 },
+        { role: "", count: 3 }, // 空定位丢弃
+        { role: "对手", count: 0 }, // clamp 到 1
+        { role: "主角", count: 5 }, // 重复定位丢弃（先到先得）
+      ]),
+    ).toEqual({ 主角: 2, 对手: 1 });
+  });
+
+  it("caps the running total at MAX_CHARACTER_COUNT", () => {
+    const out = sanitizeRoleMix([
+      { role: "主角", count: 10 },
+      { role: "对手", count: 5 }, // 只剩 2 额度
+      { role: "配角", count: 3 }, // 无额度，丢弃
+    ]);
+    expect(out).toEqual({ 主角: 10, 对手: 2 });
+    expect(roleMixTotal(out)).toBe(MAX_CHARACTER_COUNT);
+  });
+
+  it("returns empty object when no valid rows", () => {
+    expect(sanitizeRoleMix([{ role: "  ", count: 3 }])).toEqual({});
+  });
+});
+
+describe("roleMixTotal", () => {
+  it("sums counts", () => {
+    expect(roleMixTotal({ 主角: 1, 对手: 2 })).toBe(3);
+    expect(roleMixTotal({})).toBe(0);
+  });
 });
 
 describe("buildCharacterIngestRequest", () => {

apps/web/lib/generation/useCharacterGen.test.ts

@@ -53,6 +53,24 @@ describe("useCharacterGen", () => {
     expect(toast).not.toHaveBeenCalled();
   });
 
+  it("按定位配比生成：请求体带 role_mix、count 取各值之和", async () => {
+    post.mockResolvedValue({ data: { cards: [] }, error: null });
+    const { result } = renderHook(() => useCharacterGen());
+    await act(async () => {
+      await result.current.generate({
+        projectId: "p1",
+        brief: "群像",
+        count: 1,
+        role: "忽略",
+        roleMix: { 主角: 1, 对手: 2 },
+      });
+    });
+    const body = post.mock.calls[0]?.[1]?.body;
+    expect(body.role_mix).toEqual({ 主角: 1, 对手: 2 });
+    expect(body.count).toBe(3);
+    expect(body.role).toBeUndefined();
+  });
+
   it("生成成功但 cards 缺失：回退为空数组", async () => {
     post.mockResolvedValue({ data: { cards: null }, error: null });
     const { result } = renderHook(() => useCharacterGen());

apps/web/lib/generation/useCharacterGen.ts

@@ -21,6 +21,8 @@ export interface CharacterGenInput {
   brief: string;
   count: number;
   role?: string | null;
+  // 群像按定位配比（⑦）；在场时后端把 count 定为各值之和，忽略 count/role。
+  roleMix?: Readonly<Record<string, number>> | null;
 }
 
 export interface UseCharacterGen {
@@ -50,7 +52,7 @@ export function useCharacterGen(): UseCharacterGen {
   const toast = useToast();
 
   const generate = useCallback<UseCharacterGen["generate"]>(
-    async ({ projectId, brief, count, role }) => {
+    async ({ projectId, brief, count, role, roleMix }) => {
       setGenStatus("generating");
       setCards([]);
       setConflicts(null);
@@ -60,7 +62,7 @@ export function useCharacterGen(): UseCharacterGen {
           "/projects/{project_id}/characters/generate",
           {
             params: { path: { project_id: projectId } },
-            body: buildCharacterGenerateRequest(brief, count, role),
+            body: buildCharacterGenerateRequest(brief, count, role, roleMix),
           },
         );
         if (error || !data) {