diff --git a/frontend/src/components/characters/CharacterAvatar.tsx b/frontend/src/components/characters/CharacterAvatar.tsx
index 0b62999..9df5ff3 100644
--- a/frontend/src/components/characters/CharacterAvatar.tsx
+++ b/frontend/src/components/characters/CharacterAvatar.tsx
@@ -1,113 +1,27 @@
"use client";
-import { useRef, useState } from "react";
-import { useRouter } from "next/navigation";
-import Image from "next/image";
-
import { BronzeMirror } from "@/components/ui/BronzeMirror";
-import { describeError } from "@/lib/utils/error";
/**
- * 角色头像组件：展示头像图片（优先）或铜镜占位，hover 显示上传按钮。
- * 上传后调用 API 更新，成功后 refresh 页面。
+ * 人物头像呈现位：形仪主仪（仅定相 adopted；候选不进呈现位）。
+ * 头像变更走形仪工坊的候选定相流程，本组件不再提供直传。
*/
export function CharacterAvatar({
- characterId,
- avatarUrl,
+ mediaRef,
name,
}: {
- characterId: string;
- avatarUrl?: string | null;
+ mediaRef?: string | null;
name: string;
}) {
- const router = useRouter();
- const inputRef = useRef
(null);
- const [uploading, setUploading] = useState(false);
- const [error, setError] = useState(null);
-
- async function handleFile(e: React.ChangeEvent) {
- const file = e.target.files?.[0];
- if (!file) return;
-
- // 客户端校验
- const allowed = ["image/jpeg", "image/png", "image/webp"];
- if (!allowed.includes(file.type)) {
- setError("仅支持 JPG / PNG / WebP 格式");
- return;
- }
- if (file.size > 5 * 1024 * 1024) {
- setError("文件不能超过 5MB");
- return;
- }
-
- setUploading(true);
- setError(null);
-
- try {
- const formData = new FormData();
- formData.append("file", file);
-
- const res = await fetch(
- `/api/proxy/v1/characters/${characterId}/avatar`,
- { method: "POST", body: formData },
- );
- if (!res.ok) {
- const body = await res.json().catch(() => ({}));
- throw new Error(body?.error?.message || `上传失败 (${res.status})`);
- }
- router.refresh();
- } catch (err) {
- setError(describeError(err));
- } finally {
- setUploading(false);
- // 重置 input 允许重复选同一文件
- if (inputRef.current) inputRef.current.value = "";
- }
+ if (!mediaRef) {
+ return ;
}
-
return (
-
- {/* 头像 */}
-
- {avatarUrl ? (
-
- ) : (
-
- )}
-
-
- {/* Hover 上传遮罩 */}
-
-
-
-
- {error && (
-
- {error}
-
- )}
-
);
}
diff --git a/frontend/src/components/characters/CharacterIdentityCard.tsx b/frontend/src/components/characters/CharacterIdentityCard.tsx
index aa6dd27..ae305c4 100644
--- a/frontend/src/components/characters/CharacterIdentityCard.tsx
+++ b/frontend/src/components/characters/CharacterIdentityCard.tsx
@@ -8,7 +8,13 @@ import { formatDateTime } from "@/lib/utils/format";
* 角色卡 —— 人物详情页顶部的视觉化身份卡片。
* 展示头像（图片或铜镜占位）、名称、状态、关键档案字段与背景故事。
*/
-export function CharacterIdentityCard({ character }: { character: Character }) {
+export function CharacterIdentityCard({
+ character,
+ primaryMediaRef,
+}: {
+ character: Character;
+ primaryMediaRef?: string | null;
+}) {
const profile = character.profile ?? {};
const mood = character.current_mood;
@@ -21,8 +27,7 @@ export function CharacterIdentityCard({ character }: { character: Character }) {
{/* 头像（叠在横幅边界） */}
diff --git a/frontend/src/components/ui/Icons.tsx b/frontend/src/components/ui/Icons.tsx
index b6f5b7a..0a542c9 100644
--- a/frontend/src/components/ui/Icons.tsx
+++ b/frontend/src/components/ui/Icons.tsx
@@ -1048,3 +1048,133 @@ export function HeartHandshakeIcon(props: IconProps) {
);
}
+
+/** 锚点（Lucide Anchor） */
+export function AnchorIcon(props: IconProps) {
+ return (
+
+ );
+}
+
+/** 调色（Lucide Palette） */
+export function PaletteIcon(props: IconProps) {
+ return (
+
+ );
+}
+
+/** 声波（Lucide AudioLines） */
+export function AudioLinesIcon(props: IconProps) {
+ return (
+
+ );
+}
+
+/** 叉（Lucide X） */
+export function XIcon(props: IconProps) {
+ return (
+
+ );
+}
diff --git a/frontend/src/components/xingyi/FormStudio.test.tsx b/frontend/src/components/xingyi/FormStudio.test.tsx
new file mode 100644
index 0000000..7691058
--- /dev/null
+++ b/frontend/src/components/xingyi/FormStudio.test.tsx
@@ -0,0 +1,147 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { FormStudio } from "./FormStudio";
+import { xingyiApi } from "@/lib/api";
+import type {
+ FormData,
+ FormAnchorData,
+ VoiceProfileData,
+} from "@/lib/api/xingyi";
+
+vi.mock("@/lib/api", () => ({
+ xingyiApi: {
+ upsertFormAnchor: vi.fn(),
+ createForm: vi.fn(),
+ adoptForm: vi.fn(),
+ discardForm: vi.fn(),
+ createVoice: vi.fn(),
+ revokeVoiceGrant: vi.fn(),
+ listForms: vi.fn(),
+ listVoices: vi.fn(),
+ },
+}));
+
+const anchor: FormAnchorData = {
+ character_id: "character_1",
+ features: { 发色: "月白" },
+ age_presentation: "adult",
+ permissions: {},
+ mutable_scope: {},
+};
+
+const forms: FormData[] = [
+ {
+ id: "form_1",
+ character_id: "character_1",
+ kind: "primary",
+ status: "candidate",
+ source: "image_gen",
+ description: "立绘候选",
+ media_ref: null,
+ live2d: {},
+ created_at: "2026-08-27T10:00:00Z",
+ adopted_at: null,
+ },
+];
+
+const voices: VoiceProfileData[] = [
+ {
+ id: "voice_1",
+ character_id: "character_1",
+ source: "authorized_clone",
+ name: "授权声线",
+ params: {},
+ grant_purpose: "人物语音消息",
+ grant_expires_at: null,
+ grant_distribution: "仅本镜域私用",
+ grant_revoked_at: null,
+ is_active: true,
+ },
+];
+
+function renderStudio() {
+ return render(
+ ,
+ );
+}
+
+describe("FormStudio（形仪工坊）", () => {
+ it("三区渲染：锚点 / 形仪候选（未定相标记）/ 声音档案授权信息", () => {
+ renderStudio();
+ expect(screen.getByText("真形锚点")).toBeInTheDocument();
+ expect(screen.getByText("主仪与化仪")).toBeInTheDocument();
+ expect(screen.getByText("声音档案")).toBeInTheDocument();
+ expect(screen.getByText("候选")).toBeInTheDocument();
+ expect(screen.getByText(/用途：人物语音消息/)).toBeInTheDocument();
+ });
+
+ it("定相走 adopt 并刷新清单", async () => {
+ const user = userEvent.setup();
+ vi.mocked(xingyiApi.adoptForm).mockResolvedValue({} as FormData);
+ vi.mocked(xingyiApi.listForms).mockResolvedValue([
+ { ...forms[0], status: "adopted" },
+ ]);
+ vi.mocked(xingyiApi.listVoices).mockResolvedValue(voices);
+ renderStudio();
+ await user.click(screen.getByRole("button", { name: /定相/ }));
+ await waitFor(() =>
+ expect(xingyiApi.adoptForm).toHaveBeenCalledWith("character_1", "form_1"),
+ );
+ await waitFor(() =>
+ expect(xingyiApi.listForms).toHaveBeenCalledWith("character_1"),
+ );
+ });
+
+ it("登记候选必填描述；授权克隆必填用途", async () => {
+ const user = userEvent.setup();
+ renderStudio();
+ await user.click(screen.getByRole("button", { name: /登记候选/ }));
+ expect(await screen.findByText(/形仪描述不能为空/)).toBeInTheDocument();
+
+ // 切到授权克隆，不填用途
+ const voiceSelect = screen
+ .getAllByRole("combobox")
+ .find((el) => (el as HTMLSelectElement).value === "synthesis_preset");
+ expect(voiceSelect).toBeTruthy();
+ await user.selectOptions(voiceSelect!, "authorized_clone");
+ await user.type(screen.getByPlaceholderText("声音名称"), "测试声线");
+ await user.click(screen.getByRole("button", { name: /建立声音档案/ }));
+ expect(await screen.findByText(/必须声明用途/)).toBeInTheDocument();
+ expect(xingyiApi.createVoice).not.toHaveBeenCalled();
+ });
+
+ it("撤回克隆授权立即生效提示", async () => {
+ const user = userEvent.setup();
+ vi.mocked(xingyiApi.revokeVoiceGrant).mockResolvedValue({
+ voice_id: "voice_1",
+ grant_revoked: true,
+ effective: "immediate",
+ });
+ vi.mocked(xingyiApi.listForms).mockResolvedValue(forms);
+ vi.mocked(xingyiApi.listVoices).mockResolvedValue([
+ {
+ ...voices[0],
+ is_active: false,
+ grant_revoked_at: "2026-08-27T12:00:00Z",
+ },
+ ]);
+ renderStudio();
+ await user.click(screen.getByRole("button", { name: /撤回授权/ }));
+ await waitFor(() =>
+ expect(xingyiApi.revokeVoiceGrant).toHaveBeenCalledWith(
+ "character_1",
+ "voice_1",
+ ),
+ );
+ await waitFor(() =>
+ expect(screen.getByText(/克隆授权已撤回/)).toBeInTheDocument(),
+ );
+ });
+});
diff --git a/frontend/src/components/xingyi/FormStudio.tsx b/frontend/src/components/xingyi/FormStudio.tsx
new file mode 100644
index 0000000..dfb3ca9
--- /dev/null
+++ b/frontend/src/components/xingyi/FormStudio.tsx
@@ -0,0 +1,417 @@
+"use client";
+
+import { useState } from "react";
+import {
+ AnchorIcon,
+ AudioLinesIcon,
+ CheckIcon,
+ PaletteIcon,
+ XIcon,
+} from "@/components/ui/Icons";
+
+import { Button } from "@/components/ui/Button";
+import type {
+ FormData,
+ FormAnchorData,
+ VoiceProfileData,
+} from "@/lib/api/xingyi";
+
+import { xingyiApi } from "@/lib/api";
+import { cn } from "@/lib/utils/cn";
+
+interface Props {
+ characterId: string;
+ initialAnchor: FormAnchorData;
+ initialForms: FormData[];
+ initialVoices: VoiceProfileData[];
+}
+
+const KIND_LABEL: Record = {
+ primary: "主仪",
+ costume: "化仪",
+ text: "文字形仪",
+};
+const SOURCE_LABEL: Record = {
+ image_gen: "生成",
+ upload: "上传",
+ live2d: "Live2D",
+ text: "文字",
+};
+const VOICE_SOURCE_LABEL: Record = {
+ synthesis_preset: "合成预设",
+ original_design: "原创设计",
+ authorized_clone: "授权克隆",
+};
+
+/**
+ * 形仪工坊：真形锚点 / 主仪化仪（候选定相）/ 声音档案（克隆授权治理）。
+ * 候选不进呈现位——定相（adopt）才成为正式形仪；主仪唯一。
+ */
+export function FormStudio({
+ characterId,
+ initialAnchor,
+ initialForms,
+ initialVoices,
+}: Props) {
+ const [anchor, setAnchor] = useState(initialAnchor);
+ const [featuresText, setFeaturesText] = useState(
+ Object.entries(initialAnchor.features)
+ .map(([k, v]) => `${k}：${v}`)
+ .join("\n"),
+ );
+ const [forms, setForms] = useState(initialForms);
+ const [voices, setVoices] = useState(initialVoices);
+ const [desc, setDesc] = useState("");
+ const [kind, setKind] = useState("primary");
+ const [voiceName, setVoiceName] = useState("");
+ const [voiceSource, setVoiceSource] = useState("synthesis_preset");
+ const [grantPurpose, setGrantPurpose] = useState("");
+ const [busy, setBusy] = useState(false);
+ const [notice, setNotice] = useState(null);
+
+ async function refresh() {
+ setForms(await xingyiApi.listForms(characterId));
+ setVoices(await xingyiApi.listVoices(characterId));
+ }
+
+ async function saveAnchor() {
+ setBusy(true);
+ try {
+ const features: Record = {};
+ for (const line of featuresText.split("\n")) {
+ const idx = line.indexOf("：");
+ if (idx > 0) {
+ features[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+ }
+ }
+ const saved = await xingyiApi.upsertFormAnchor(characterId, {
+ features,
+ age_presentation: anchor.age_presentation,
+ });
+ setAnchor(saved);
+ setNotice("真形锚点已保存（生成内容不可覆盖锚点约束）。");
+ } catch (e) {
+ setNotice(e instanceof Error ? e.message : "保存失败");
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ async function submitCandidate() {
+ if (!desc.trim()) {
+ setNotice("形仪描述不能为空。");
+ return;
+ }
+ setBusy(true);
+ try {
+ await xingyiApi.createForm(characterId, {
+ kind,
+ source: "upload",
+ description: desc.trim(),
+ });
+ setDesc("");
+ await refresh();
+ setNotice("候选已登记（未定相不进呈现位）。");
+ } catch (e) {
+ setNotice(e instanceof Error ? e.message : "登记失败");
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ async function adopt(form: FormData) {
+ setBusy(true);
+ try {
+ await xingyiApi.adoptForm(characterId, form.id);
+ await refresh();
+ setNotice(`已定相：${KIND_LABEL[form.kind] ?? form.kind}。`);
+ } catch (e) {
+ setNotice(e instanceof Error ? e.message : "定相失败");
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ async function discard(form: FormData) {
+ setBusy(true);
+ try {
+ await xingyiApi.discardForm(characterId, form.id);
+ await refresh();
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ async function addVoice() {
+ if (!voiceName.trim()) {
+ setNotice("声音名称不能为空。");
+ return;
+ }
+ if (voiceSource === "authorized_clone" && !grantPurpose.trim()) {
+ setNotice("授权克隆必须声明用途。");
+ return;
+ }
+ setBusy(true);
+ try {
+ await xingyiApi.createVoice(characterId, {
+ source: voiceSource,
+ name: voiceName.trim(),
+ grant_purpose:
+ voiceSource === "authorized_clone" ? grantPurpose.trim() : null,
+ grant_distribution:
+ voiceSource === "authorized_clone" ? "仅本镜域私用" : null,
+ });
+ setVoiceName("");
+ setGrantPurpose("");
+ await refresh();
+ setNotice("声音档案已建立。");
+ } catch (e) {
+ setNotice(e instanceof Error ? e.message : "建立失败");
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ async function revoke(voice: VoiceProfileData) {
+ setBusy(true);
+ try {
+ await xingyiApi.revokeVoiceGrant(characterId, voice.id);
+ await refresh();
+ setNotice("克隆授权已撤回（立即生效）。");
+ } finally {
+ setBusy(false);
+ }
+ }
+
+ return (
+
+ {notice && (
+
+ {notice}
+
+ )}
+
+ {/* ═══ 真形锚点 ═══ */}
+
+
+
+ 稳定辨识特征与许可禁忌；生成内容不得静默覆盖锚点约束。
+
+