feat(review): 人物塑造 advisory 审(第五审,仅建议不阻断验收)

写→审链新增第五审「人物塑造」(灵感③/D2):advisory 单维——仅建议、不阻断
验收(不进 conflicts、不碰 assert_conflicts_resolved、不入 REVIEW_RESERVED_NAMES);
只做人物塑造、不做氛围。

- SPEC characterization_spec(analyst,reads=("characters",),writes=())+
  prompts/characterization.md(只读、显式忽略文本长度与辞藻华丽度、引用逐字片段+置信度)
- schema CharacterizationReview{issues[...]}(全字段默认值守解析韧性)+ 注册 catalog
- 计数三处 22→23 + regen prompt_hashes.json(仅加一条)
- DB chapter_reviews 加 characterization JSONB nullable 列(迁移 f6a7b8c9d0e1)
- 接线:graph REVIEW_SPECS 追加 · chain ReviewRecordRepo · collect(extract/record) ·
  review_repo(Protocol/Sql/_to_view/ReviewView) · sse(event/factory/section) · normalize 自动纳入
- 契约 ReviewHistoryItem 加 characterization(gen:api 已重生成)
- 前端 sse/history/useReviewStream + CharacterizationPanel(只展示无裁决 UI、置信度降序+低置信折叠)+ ReviewReport 挂面板
- 测试 test_characterization_does_not_block_accept + 计数/golden + collect/normalize + 前端 reducer/normalize/parse

守不变量 #2/#3/#9;依赖 ⑧(motive/appearance 作客观锚点)。
This commit is contained in:
Yaojia Wang
2026-07-06 17:08:38 +02:00
parent 2a7a865e98
commit 72b3c81146
37 changed files with 1071 additions and 19 deletions

View File

@@ -0,0 +1,102 @@
"use client";
import { CheckCircle2, CircleDashed, UserRound } from "lucide-react";
import { Badge } from "@/components/ui/Badge";
import type { CharacterizationIssue, CharacterizationReport } from "@/lib/review/sse";
interface CharacterizationPanelProps {
characterization: CharacterizationReport | null;
incomplete: boolean;
}
// 高置信度阈值≥0.7 为主区常显,<0.7 折进「更多低置信度建议」抽屉(控作者注意力预算,灵感 §10
const HIGH_CONFIDENCE = 0.7;
// 人物塑造报告区(灵感③ advisory 单维):只读建议、**无裁决 UI**(不进 conflicts/不阻断验收)。
// 以人物卡 motive/appearance 为客观锚点;每条带逐字引用 + 置信度。按置信度降序,
// 低置信度折叠,避免维度噪声淹没作者。
export function CharacterizationPanel({
characterization,
incomplete,
}: CharacterizationPanelProps) {
if (incomplete) {
return (
<section>
<Badge variant="warning">
<CircleDashed className="h-3 w-3" aria-hidden="true" />
</Badge>
</section>
);
}
const issues = characterization?.issues ?? [];
if (characterization === null || issues.length === 0) {
return (
<section>
<Badge variant="success">
<CheckCircle2 className="h-3 w-3" aria-hidden="true" />
</Badge>
</section>
);
}
// 置信度降序(优先级合并);高/低分区。
const sorted = [...issues].sort((a, b) => b.confidence - a.confidence);
const high = sorted.filter((i) => i.confidence >= HIGH_CONFIDENCE);
const low = sorted.filter((i) => i.confidence < HIGH_CONFIDENCE);
return (
<section className="space-y-2 text-xs">
<p className="rounded border border-dashed border-line/70 bg-bg/40 px-3 py-1.5 text-[11px] text-ink-soft">
</p>
<ul className="space-y-2">
{(high.length > 0 ? high : sorted).map((issue, i) => (
<CharacterizationIssueCard key={i} issue={issue} />
))}
</ul>
{high.length > 0 && low.length > 0 ? (
<details className="group rounded border border-line/70 bg-bg/35 p-2">
<summary className="cursor-pointer list-none text-2xs font-semibold text-ink-soft">
{low.length}
</summary>
<ul className="mt-2 space-y-2">
{low.map((issue, i) => (
<CharacterizationIssueCard key={i} issue={issue} />
))}
</ul>
</details>
) : null}
</section>
);
}
function CharacterizationIssueCard({ issue }: { issue: CharacterizationIssue }) {
const pct = Math.round(Math.max(0, Math.min(1, issue.confidence)) * 100);
return (
<li className="rounded border border-line/70 bg-bg/35 p-2">
<div className="flex items-center justify-between gap-2">
<span className="flex items-center gap-1.5 font-semibold text-ink">
<UserRound className="h-3.5 w-3.5 text-ink-soft" aria-hidden="true" />
{issue.character || "(未归属角色)"}
{issue.aspect ? <Badge variant="accent">{issue.aspect}</Badge> : null}
</span>
<span className="shrink-0 font-mono text-2xs text-ink-soft" title="置信度">
{pct}%
</span>
</div>
{issue.where ? <p className="mt-1 text-ink-soft">{issue.where}</p> : null}
{issue.quote ? (
<blockquote className="mt-1 border-l-2 border-line pl-2 text-ink-soft italic">
{issue.quote}
</blockquote>
) : null}
{issue.diagnosis ? <p className="mt-1 text-ink">{issue.diagnosis}</p> : null}
{issue.suggestion ? (
<p className="mt-1 text-ink-soft">{issue.suggestion}</p>
) : null}
</li>
);
}

View File

@@ -32,6 +32,7 @@ import {
} from "@/lib/review/decisions";
import {
latestReview,
normalizeCharacterization,
normalizeConflicts,
normalizeForeshadowSug,
normalizePace,
@@ -56,6 +57,7 @@ import { useToast } from "@/components/Toast";
import { ThinkingIndicator } from "@/components/ThinkingIndicator";
import { AcceptPanel } from "./AcceptPanel";
import { AnnotatedText } from "./AnnotatedText";
import { CharacterizationPanel } from "./CharacterizationPanel";
import { ConflictCard } from "./ConflictCard";
import { ForeshadowSuggestions } from "./ForeshadowSuggestions";
import { PacePanel } from "./PacePanel";
@@ -128,6 +130,10 @@ export function ReviewReport({
() => normalizeStyleDrift(initialReview),
[initialReview],
);
const seededCharacterization = useMemo(
() => normalizeCharacterization(initialReview),
[initialReview],
);
useEffect(() => {
if (seededRef.current) return;
seededRef.current = true;
@@ -135,22 +141,32 @@ export function ReviewReport({
seededConflicts.length > 0 ||
seededForeshadow.length > 0 ||
seededPace !== null ||
seededStyle !== null;
seededStyle !== null ||
seededCharacterization !== null;
if (hasSeed) {
review.seed({
conflicts: seededConflicts,
foreshadow: seededForeshadow,
pace: seededPace,
style: seededStyle,
characterization: seededCharacterization,
});
}
}, [review, seededConflicts, seededForeshadow, seededPace, seededStyle]);
}, [
review,
seededConflicts,
seededForeshadow,
seededPace,
seededStyle,
seededCharacterization,
]);
// 当前生效冲突 = 流状态(重审后即时更新,否则种入的历史)。
const conflicts: ReviewConflict[] = review.state.conflicts;
const foreshadow = review.state.foreshadow;
const pace = review.state.pace;
const style = review.state.style;
const characterization = review.state.characterization;
// 伏笔徽标/验收预览统一用「仍待处理数」(随登记/回收递减);未上报前回退原始建议数。
const foreshadowOpen = foreshadowRemaining ?? foreshadow.length;
const sectionStatus = (name: string): string | undefined =>
@@ -359,7 +375,7 @@ export function ReviewReport({
const fresh = normalizeConflicts(latestReview(data?.reviews));
setMissing(new Set(outcome.missingIndices));
if (fresh.length > 0) {
review.seed({ conflicts: fresh, foreshadow, pace, style });
review.seed({ conflicts: fresh, foreshadow, pace, style, characterization });
setDrafts(emptyDecisions(fresh.length));
toast("审稿报告已刷新:检测到未裁决冲突,请裁决后再验收", "error");
} else {
@@ -405,7 +421,8 @@ export function ReviewReport({
seededConflicts.length > 0 ||
foreshadow.length > 0 ||
pace !== null ||
style !== null;
style !== null ||
characterization !== null;
return (
<AppShell
@@ -671,6 +688,35 @@ export function ReviewReport({
onRefine={onRefineSegment}
/>
</ReviewSectionPanel>
<ReviewSectionPanel
title="人物塑造"
statusLabel={
sectionStatus("characterization") === "incomplete"
? "未完成"
: characterization && characterization.issues.length > 0
? `${characterization.issues.length} 建议`
: characterization
? "无明显问题"
: "无报告"
}
statusVariant={
sectionStatus("characterization") === "incomplete"
? "warning"
: characterization && characterization.issues.length > 0
? "accent"
: characterization
? "success"
: "neutral"
}
defaultOpen={
characterization !== null && characterization.issues.length > 0
}
>
<CharacterizationPanel
characterization={characterization}
incomplete={sectionStatus("characterization") === "incomplete"}
/>
</ReviewSectionPanel>
{refineText !== null ? (
<RefineView
projectId={project.id}

View File

@@ -1828,6 +1828,10 @@ export interface components {
pace?: {
[key: string]: unknown;
} | null;
/** Characterization */
characterization?: {
[key: string]: unknown;
} | null;
/** Health Score */
health_score?: number | null;
/** Decisions */

View File

@@ -0,0 +1,108 @@
import { describe, expect, it } from "vitest";
import {
initialReviewState,
parseReviewBlock,
reduceReview,
type ReviewSseEvent,
} from "./sse";
const FULL_ISSUE = {
character: "沈砚",
aspect: "动机一致性",
where: "第3段",
quote: "他忽然转身。",
diagnosis: "动机断裂",
suggestion: "扣回护妹动机",
confidence: 0.82,
};
describe("parseReviewBlock — characterization (灵感③ advisory)", () => {
it("parses a characterization frame with a full issue", () => {
const evt = parseReviewBlock(
`event:characterization\ndata:{"issues":[${JSON.stringify(FULL_ISSUE)}]}`,
);
expect(evt).toEqual({
event: "characterization",
data: { issues: [FULL_ISSUE] },
});
});
it("defaults missing issue fields (advisory 韧性)", () => {
const evt = parseReviewBlock(
'event:characterization\ndata:{"issues":[{"character":"阿黎"}]}',
);
expect(evt).toEqual({
event: "characterization",
data: {
issues: [
{
character: "阿黎",
aspect: "",
where: "",
quote: "",
diagnosis: "",
suggestion: "",
confidence: 0,
},
],
},
});
});
it("parses an empty issues frame (无明显问题降级)", () => {
expect(
parseReviewBlock('event:characterization\ndata:{"issues":[]}'),
).toEqual({ event: "characterization", data: { issues: [] } });
});
it("drops non-record issues without dropping the whole frame", () => {
const evt = parseReviewBlock(
'event:characterization\ndata:{"issues":["junk",{"character":"沈砚"}]}',
);
expect(evt?.event).toBe("characterization");
if (evt?.event === "characterization") {
expect(evt.data.issues).toHaveLength(1);
expect(evt.data.issues[0]?.character).toBe("沈砚");
}
});
});
describe("reduceReview — characterization (replace-style like pace)", () => {
it("sets characterization report and marks reviewing", () => {
const evt: ReviewSseEvent = {
event: "characterization",
data: { issues: [FULL_ISSUE] },
};
const out = reduceReview(initialReviewState, evt);
expect(out.phase).toBe("reviewing");
expect(out.characterization).toEqual({ issues: [FULL_ISSUE] });
});
it("replaces (not accumulates) the characterization report", () => {
const first = reduceReview(initialReviewState, {
event: "characterization",
data: { issues: [FULL_ISSUE] },
});
const second = reduceReview(first, {
event: "characterization",
data: { issues: [] },
});
expect(second.characterization).toEqual({ issues: [] });
});
it("leaves characterization untouched on a section event", () => {
const seeded = reduceReview(initialReviewState, {
event: "characterization",
data: { issues: [FULL_ISSUE] },
});
const out = reduceReview(seeded, {
event: "section",
data: { name: "characterization", status: "done" },
});
expect(out.characterization).toEqual({ issues: [FULL_ISSUE] });
expect(out.sections).toEqual([
{ name: "characterization", status: "done" },
]);
});
});

View File

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
import type { ReviewConflictView, ReviewHistoryItem } from "@/lib/api/types";
import {
latestReview,
normalizeCharacterization,
normalizeConflicts,
normalizeForeshadowSug,
normalizePace,
@@ -121,6 +122,62 @@ describe("normalizePace", () => {
});
});
describe("normalizeCharacterization", () => {
it("tightens dict into CharacterizationReport with field defaults", () => {
const out = normalizeCharacterization({
...item([]),
characterization: {
issues: [
{
character: "沈砚",
aspect: "动机一致性",
where: "第3段",
quote: "他忽然转身。",
diagnosis: "动机断裂",
suggestion: "扣回护妹动机",
confidence: 0.82,
},
// 缺字段的畸形条目:安全默认,不丢整条
{ character: "阿黎" },
],
},
});
expect(out).toEqual({
issues: [
{
character: "沈砚",
aspect: "动机一致性",
where: "第3段",
quote: "他忽然转身。",
diagnosis: "动机断裂",
suggestion: "扣回护妹动机",
confidence: 0.82,
},
{
character: "阿黎",
aspect: "",
where: "",
quote: "",
diagnosis: "",
suggestion: "",
confidence: 0,
},
],
});
});
it("returns empty issues when characterization is present but issues missing", () => {
expect(
normalizeCharacterization({ ...item([]), characterization: {} }),
).toEqual({ issues: [] });
});
it("returns null when characterization is missing or not a dict", () => {
expect(normalizeCharacterization(item([]))).toBeNull();
expect(normalizeCharacterization(undefined)).toBeNull();
});
});
describe("latestReview", () => {
it("returns first item (history is newest-first)", () => {
const a = item([]);

View File

@@ -2,7 +2,9 @@
// 纯逻辑可单测schema 把 conflicts 标成 {[k]:unknown}[],这里安全收窄。
import type { ReviewHistoryItem } from "@/lib/api/types";
import { asCharacterizationIssues } from "./sse";
import type {
CharacterizationReport,
ForeshadowKind,
ForeshadowSuggestion,
PaceIssue,
@@ -80,6 +82,17 @@ export function normalizePace(
};
}
// 把一条留痕的 characterizationdict收紧成人物塑造报告缺失/非 dict → null不渲染
// advisory只展示、无裁决 UI灵感 D2
export function normalizeCharacterization(
item: ReviewHistoryItem | undefined,
): CharacterizationReport | null {
const raw = item?.characterization;
if (typeof raw !== "object" || raw === null) return null;
const dict = raw as Record<string, unknown>;
return { issues: asCharacterizationIssues(dict["issues"]) };
}
// 最近一条留痕GET .../reviews 已按新→旧排序)。
export function latestReview(
items: readonly ReviewHistoryItem[] | undefined,

View File

@@ -60,6 +60,22 @@ export interface StyleDriftReport {
segments: StyleDriftSegment[];
}
// 人物塑造(灵感③ advisory 单维):只读建议,不阻断验收(无裁决 UI
// 以人物卡 motive/appearance 为客观锚点;每条带逐字引用 quote + 置信度 confidence。
export interface CharacterizationIssue {
character: string;
aspect: string;
where: string;
quote: string;
diagnosis: string;
suggestion: string;
confidence: number;
}
export interface CharacterizationReport {
issues: CharacterizationIssue[];
}
export interface SectionEvent {
event: "section";
data: { name: string; status: SectionStatus };
@@ -98,6 +114,10 @@ export interface StyleEvent {
}[];
};
}
export interface CharacterizationEvent {
event: "characterization";
data: { issues: CharacterizationIssue[] };
}
export interface DoneEvent {
event: "done";
data: { length: number };
@@ -112,6 +132,7 @@ export type ReviewSseEvent =
| ForeshadowEvent
| PaceEvent
| StyleEvent
| CharacterizationEvent
| DoneEvent
| ErrorEvent;
@@ -121,6 +142,7 @@ const KNOWN_EVENTS = new Set([
"foreshadow",
"pace",
"style",
"characterization",
"done",
"error",
]);
@@ -176,6 +198,34 @@ function asPaceIssues(v: unknown): PaceIssue[] {
);
}
function asNumber(v: unknown, fallback = 0): number {
return typeof v === "number" && Number.isFinite(v) ? v : fallback;
}
function asStringField(v: unknown): string {
return typeof v === "string" ? v : "";
}
// 收窄人物塑造 issues每字段安全默认advisory 韧性;缺字段不丢整条)。
export function asCharacterizationIssues(v: unknown): CharacterizationIssue[] {
if (!Array.isArray(v)) return [];
return v.flatMap((x) =>
isRecord(x)
? [
{
character: asStringField(x.character),
aspect: asStringField(x.aspect),
where: asStringField(x.where),
quote: asStringField(x.quote),
diagnosis: asStringField(x.diagnosis),
suggestion: asStringField(x.suggestion),
confidence: asNumber(x.confidence),
},
]
: [],
);
}
function asStyleSegments(v: unknown): StyleEvent["data"]["segments"] {
if (!Array.isArray(v)) return [];
return v.flatMap((x) =>
@@ -248,6 +298,11 @@ function narrowReviewEvent(event: string, data: unknown): ReviewSseEvent | null
},
}
: null;
case "characterization":
return {
event: "characterization",
data: { issues: asCharacterizationIssues(data.issues) },
};
case "done":
return typeof data.length === "number"
? { event: "done", data: { length: data.length } }
@@ -320,6 +375,7 @@ export interface ReviewStreamState {
foreshadow: ForeshadowSuggestion[];
pace: PaceReport | null;
style: StyleDriftReport | null;
characterization: CharacterizationReport | null;
error: { code: string; message: string; request_id?: string | null } | null;
}
@@ -330,6 +386,7 @@ export const initialReviewState: ReviewStreamState = {
foreshadow: [],
pace: null,
style: null,
characterization: null,
error: null,
};
@@ -377,6 +434,12 @@ export function reduceReview(
})),
},
};
case "characterization":
return {
...state,
phase: "reviewing",
characterization: { issues: event.data.issues.map((i) => ({ ...i })) },
};
case "done":
return { ...state, phase: "done" };
case "error":

View File

@@ -222,6 +222,19 @@ describe("useReviewStream", () => {
foreshadow: [{ kind: "resolved" as const, title: "旧伏笔" }],
pace: { water: [], hook: false, beat_map: [1] },
style: { score: 0.9, segments: [] },
characterization: {
issues: [
{
character: "沈砚",
aspect: "动机一致性",
where: "第3段",
quote: "他忽然转身。",
diagnosis: "动机断裂",
suggestion: "扣回护妹动机",
confidence: 0.8,
},
],
},
};
act(() => result.current.seed(seedData));
@@ -230,6 +243,9 @@ describe("useReviewStream", () => {
expect(result.current.state.foreshadow).toEqual(seedData.foreshadow);
expect(result.current.state.pace).toEqual(seedData.pace);
expect(result.current.state.style).toEqual(seedData.style);
expect(result.current.state.characterization).toEqual(
seedData.characterization,
);
expect(result.current.state.phase).toBe("idle");
});
});

View File

@@ -7,6 +7,7 @@ import {
ReviewFrameBuffer,
initialReviewState,
reduceReview,
type CharacterizationReport,
type ForeshadowSuggestion,
type PaceReport,
type ReviewConflict,
@@ -19,6 +20,7 @@ export interface ReviewSeed {
foreshadow: ForeshadowSuggestion[];
pace: PaceReport | null;
style: StyleDriftReport | null;
characterization: CharacterizationReport | null;
}
type Action =
@@ -49,6 +51,7 @@ function reducer(state: ReviewStreamState, action: Action): ReviewStreamState {
foreshadow: action.seed.foreshadow,
pace: action.seed.pace,
style: action.seed.style,
characterization: action.seed.characterization,
};
default:
return state;