feat(ux): B0 注入透明读端点 + F1 写作页右栏真面板

兑现「看到的=写章用的」信任牌(不变量 #6),替换写作页右栏过时假占位
(「M1 暂未接 / M2 开放」)。

后端:
- GET /projects/{id}/chapters/{no}/injection → InjectionResponse(selected
  实体 + 入选理由 + recent_n);调既有 assemble() 回放确定性 SelectionTrace,
  无 LLM / 无 commit / 无 DDL;项目不存在→404,无大纲→selected:[]。
- 新 schemas/injection.py;tests/test_injection.py(3 测)。

前端:
- gen:api 纳入端点;纯逻辑 lib/workbench/injection.ts(理由/类型→中文徽标
  + 4 vitest)+ useInjection 读 hook。
- ChapterAssistant 改 client 组件:列出选中实体 + 理由徽标 + 空/载/错三态,
  四审段指向审稿页;Workbench 传 projectId/chapterNo。

门禁:后端 ruff/format/mypy 159/alembic 无漂移/pytest 454;
前端 lint/typecheck/vitest 167/build。

B0 可控版(PUT override pin/排除/recent_n + selection 加参 + draft 同读
override + 持久化)+ F1 可控控件待后续。
This commit is contained in:
Yaojia Wang
2026-06-20 10:57:03 +02:00
parent 7e63534366
commit 8058cfb11a
12 changed files with 513 additions and 10 deletions

View File

@@ -1,6 +1,29 @@
"use client";
import Link from "next/link";
import {
kindLabel,
reasonLabel,
type InjectionEntity,
} from "@/lib/workbench/injection";
import { useInjection } from "@/lib/workbench/useInjection";
interface ChapterAssistantProps {
projectId: string;
chapterNo: number;
}
// 右栏「本章助手」UX §6.3)。
// M1 无端点暴露注入选择轨迹/四审结果 → 占位说明,不编造 API。
export function ChapterAssistant() {
// 「本章注入(透明)」读 B0 端点,列出确定性选中的设定/角色 + 入选理由徽标——
// 这是「看到的=写章用的」的信任牌(不变量 #6。「四审」指向审稿页入口。
export function ChapterAssistant({
projectId,
chapterNo,
}: ChapterAssistantProps) {
const injection = useInjection(projectId, chapterNo);
const selected = injection.data?.selected ?? [];
return (
<aside className="hidden border-l border-line bg-panel p-4 lg:block">
<h2 className="text-sm font-semibold text-ink"></h2>
@@ -9,19 +32,63 @@ export function ChapterAssistant() {
<h3 className="text-xs font-semibold uppercase tracking-wide text-ink-soft">
</h3>
<p className="mt-2 rounded border border-dashed border-line bg-bg p-3 text-xs text-ink-soft">
M1 /
</p>
{injection.loading ? (
<p className="mt-2 text-xs text-ink-soft"></p>
) : injection.error ? (
<p className="mt-2 rounded border border-dashed border-line bg-bg p-3 text-xs text-ink-soft">
{injection.error}
</p>
) : selected.length === 0 ? (
<p className="mt-2 rounded border border-dashed border-line bg-bg p-3 text-xs text-ink-soft">
/
</p>
) : (
<ul className="mt-2 space-y-2">
{selected.map((entity) => (
<EntityRow key={`${entity.kind}:${entity.name}`} entity={entity} />
))}
</ul>
)}
</section>
<section className="mt-4">
<section className="mt-6">
<h3 className="text-xs font-semibold uppercase tracking-wide text-ink-soft">
</h3>
<p className="mt-2 rounded border border-dashed border-line bg-bg p-3 text-xs text-ink-soft">
M2 / / /
<p className="mt-2 text-xs text-ink-soft">
/ / / 稿
</p>
<Link
href={`/projects/${projectId}/review?chapter=${chapterNo}`}
className="mt-2 inline-block rounded border border-cinnabar px-3 py-1.5 text-xs text-cinnabar hover:bg-[var(--color-cinnabar-wash)]"
>
稿
</Link>
</section>
</aside>
);
}
function EntityRow({ entity }: { entity: InjectionEntity }) {
return (
<li className="rounded border border-line bg-bg p-2">
<div className="flex items-center gap-2">
<span className="rounded bg-panel px-1.5 py-0.5 text-[10px] text-ink-soft">
{kindLabel(entity.kind)}
</span>
<span className="text-sm text-ink">{entity.name}</span>
</div>
<div className="mt-1.5 flex flex-wrap gap-1">
{(entity.reasons ?? []).map((reason) => (
<span
key={reason}
className="rounded bg-[var(--color-cinnabar-wash)] px-1.5 py-0.5 text-[10px] text-cinnabar"
>
{reasonLabel(reason)}
</span>
))}
</div>
</li>
);
}

View File

@@ -87,7 +87,7 @@ export function Workbench({ project, initialText = "" }: WorkbenchProps) {
/>
</section>
<ChapterAssistant />
<ChapterAssistant projectId={project.id} chapterNo={chapterNo} />
</div>
</AppShell>
);

View File

@@ -90,6 +90,28 @@ export interface paths {
patch?: never;
trace?: never;
};
"/projects/{project_id}/chapters/{chapter_no}/injection": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* Get Injection
* @description 本章注入透明B0读端点回放确定性 SelectionTrace。无 LLM、无 commit。
*
* 项目不存在 → 404无大纲 → selected: [](不报错)。看到的=写章用的(不变量 #6
*/
get: operations["get_injection_projects__project_id__chapters__chapter_no__injection_get"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/projects/{project_id}/chapters/{chapter_no}/draft": {
parameters: {
query?: never;
@@ -958,6 +980,44 @@ export interface components {
/** Detail */
detail?: components["schemas"]["ValidationError"][];
};
/**
* InjectionEntity
* @description 一个被注入本章上下文的实体 + 入选理由(喂给透明面板的徽标)。
*/
InjectionEntity: {
/**
* Kind
* @description character / world_entity
*/
kind: string;
/** Name */
name: string;
/**
* Reasons
* @description explicit_beat / main_character / recent_digest / foreshadow_window
*/
reasons?: string[];
};
/**
* InjectionResponse
* @description GET /projects/:id/chapters/:no/injection本章确定性注入留痕。
*/
InjectionResponse: {
/**
* Project Id
* Format: uuid
*/
project_id: string;
/** Chapter No */
chapter_no: number;
/** Selected */
selected?: components["schemas"]["InjectionEntity"][];
/**
* Recent N
* @description 近况摘要回看章数(确定性选择的默认参数)
*/
recent_n: number;
};
/**
* OAuthDisconnectResponse
* @description 断开:是否删到凭据行。
@@ -1597,6 +1657,38 @@ export interface operations {
};
};
};
get_injection_projects__project_id__chapters__chapter_no__injection_get: {
parameters: {
query?: never;
header?: never;
path: {
project_id: string;
chapter_no: number;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Successful Response */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["InjectionResponse"];
};
};
/** @description Validation Error */
422: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["HTTPValidationError"];
};
};
};
};
get_draft_projects__project_id__chapters__chapter_no__draft_get: {
parameters: {
query?: never;

View File

@@ -0,0 +1,27 @@
import { describe, expect, it } from "vitest";
import { kindLabel, reasonLabel } from "./injection";
describe("reasonLabel", () => {
it("maps each known selection reason to a Chinese badge", () => {
expect(reasonLabel("explicit_beat")).toBe("本章点名");
expect(reasonLabel("main_character")).toBe("主角常驻");
expect(reasonLabel("recent_digest")).toBe("近章出现");
expect(reasonLabel("foreshadow_window")).toBe("伏笔窗口");
});
it("falls back to the raw code for an unknown reason", () => {
expect(reasonLabel("future_reason")).toBe("future_reason");
});
});
describe("kindLabel", () => {
it("maps entity kinds to Chinese", () => {
expect(kindLabel("character")).toBe("角色");
expect(kindLabel("world_entity")).toBe("设定");
});
it("falls back to the raw kind when unknown", () => {
expect(kindLabel("mystery")).toBe("mystery");
});
});

View File

@@ -0,0 +1,30 @@
// 本章注入透明B0/F1纯逻辑入选理由 / 实体类型 → 中文徽标。
// 纯函数,便于 node 环境单测;渲染层只管样式。
import type { components } from "@/lib/api/schema";
export type InjectionResponse = components["schemas"]["InjectionResponse"];
export type InjectionEntity = components["schemas"]["InjectionEntity"];
// SelectionReason → 作者可读徽标(对齐 ARCH §3.4 的四来源)。
export const REASON_LABELS: Record<string, string> = {
explicit_beat: "本章点名",
main_character: "主角常驻",
recent_digest: "近章出现",
foreshadow_window: "伏笔窗口",
};
// EntityKind → 中文。
export const KIND_LABELS: Record<string, string> = {
character: "角色",
world_entity: "设定",
};
// 未知 code 时回退原值(不吞,便于发现新理由)。
export function reasonLabel(reason: string): string {
return REASON_LABELS[reason] ?? reason;
}
export function kindLabel(kind: string): string {
return KIND_LABELS[kind] ?? kind;
}

View File

@@ -0,0 +1,50 @@
"use client";
import { useEffect, useState } from "react";
import { api } from "@/lib/api/client";
import type { InjectionResponse } from "./injection";
export interface UseInjection {
data: InjectionResponse | null;
loading: boolean;
error: string | null;
}
// 本章注入透明B0 读端点):挂载时拉一次确定性 SelectionTrace。
// 只读、无 LLM、无 commit——展示「选了谁/为什么」。失败给可读文案不抛。
export function useInjection(
projectId: string,
chapterNo: number,
): UseInjection {
const [data, setData] = useState<InjectionResponse | null>(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
let cancelled = false;
setLoading(true);
setError(null);
void (async () => {
const { data: body, error: err } = await api.GET(
"/projects/{project_id}/chapters/{chapter_no}/injection",
{ params: { path: { project_id: projectId, chapter_no: chapterNo } } },
);
if (cancelled) return;
if (err || !body) {
setError("注入信息暂不可用");
setData(null);
} else {
setData(body);
}
setLoading(false);
})();
return () => {
cancelled = true;
};
}, [projectId, chapterNo]);
return { data, loading, error };
}

File diff suppressed because one or more lines are too long