feat(b0): 注入透明可控版后端 — PUT override(pin/排除/recent_n) + 选择函数加参 + draft 同读

- selection.select_relevant_entities 加 pinned/excluded frozenset 入参；新理由 author_pin（末位） - assemble 加 override 关键字参（recent_n 覆盖回看章数 + pin/排除）；GET/PUT/draft 同读同一覆盖（不变量 #6 作者兜底） - 新 domain/injection_repo.py（InjectionOverride/EntityRef/SqlInjectionOverrideRepo，upsert 只 flush） - 新表 chapter_injection（迁移 ad2c4c663daf，唯一 project_id+chapter_no；复用 outline 行已否决） - PUT/GET injection 端点 + InjectionOverrideRequest/回显 pinned/excluded；recent_n 1..20 校验 422 - 单测：selection pin/排除/exclude>pin + assemble override + 端点 PUT/404/422；regen TS 客户端 - 门禁绿：ruff/format · mypy 163 · alembic 无漂移 · pytest 476 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 11:56:54 +02:00
parent e8cccf7389
commit 0d473e726e
16 changed files with 681 additions and 41 deletions
--- a/apps/api/tests/test_injection.py
+++ b/apps/api/tests/test_injection.py
@@ -12,6 +12,7 @@ import httpx
 import pytest
 from fakes_projects import FakeProjectRepo
 from ww_api.services.credentials import STUB_OWNER_ID
+from ww_core.domain.injection_repo import InjectionOverride
 from ww_core.domain.project_repo import ProjectCreate
 from ww_core.domain.repositories import (
    CharacterView,
@@ -81,6 +82,22 @@ class _SpecRepo:
        return ProjectSpecView(title="测试作品", premise="测试前提")


+class _FakeInjectionRepo:
+    """内存注入覆盖 repo（按 (project_id, chapter_no) 存最后一次 upsert）。"""
+
+    def __init__(self) -> None:
+        self._store: dict[tuple[str, int], InjectionOverride] = {}
+
+    async def get(self, project_id: uuid.UUID, chapter_no: int) -> InjectionOverride | None:
+        return self._store.get((str(project_id), chapter_no))
+
+    async def upsert(
+        self, project_id: uuid.UUID, chapter_no: int, override: InjectionOverride
+    ) -> InjectionOverride:
+        self._store[(str(project_id), chapter_no)] = override
+        return override
+
+
 def _memory_repos(
    *,
    outline: dict[int, OutlineView] | None = None,
@@ -103,16 +120,25 @@ def _make_client(
    *,
    project_repo: FakeProjectRepo,
    memory_repos: MemoryRepos,
+    injection_repo: _FakeInjectionRepo | None = None,
 ) -> httpx.AsyncClient:
    import os

    os.environ.setdefault("CREDENTIAL_ENC_KEY", "x" * 44)
+    from fakes_projects import FakeSession
    from ww_api.main import create_app
-    from ww_api.services.project_deps import get_memory_repos, get_project_repo
+    from ww_api.services.project_deps import (
+        get_injection_repo,
+        get_memory_repos,
+        get_project_repo,
+    )
+    from ww_db import get_session

    app = create_app()
    app.dependency_overrides[get_project_repo] = lambda: project_repo
    app.dependency_overrides[get_memory_repos] = lambda: memory_repos
+    app.dependency_overrides[get_injection_repo] = lambda: injection_repo or _FakeInjectionRepo()
+    app.dependency_overrides[get_session] = lambda: FakeSession()
    transport = httpx.ASGITransport(app=app)
    return httpx.AsyncClient(transport=transport, base_url="http://test")

@@ -167,3 +193,68 @@ async def test_injection_no_outline_returns_empty() -> None:
        resp = await client.get(f"/projects/{pid}/chapters/9/injection")
    assert resp.status_code == 200
    assert resp.json()["selected"] == []
+
+
+@pytest.mark.asyncio
+async def test_injection_put_pin_excludes_and_reflects() -> None:
+    repo = FakeProjectRepo()
+    pid = await _create_project(repo)
+    memory = _memory_repos(
+        outline={3: OutlineView(volume=1, chapter_no=3, beats={})},
+        characters=[
+            CharacterView(name="林动", role="主角"),
+            CharacterView(name="路人乙", role="龙套"),
+        ],
+    )
+    injection = _FakeInjectionRepo()
+    client = _make_client(project_repo=repo, memory_repos=memory, injection_repo=injection)
+    async with client:
+        # pin 龙套路人乙（本无理由）、排除主角林动、近况回看设为 2。
+        put = await client.put(
+            f"/projects/{pid}/chapters/3/injection",
+            json={
+                "pinned": [{"kind": "character", "name": "路人乙"}],
+                "excluded": [{"kind": "character", "name": "林动"}],
+                "recent_n": 2,
+            },
+        )
+        assert put.status_code == 200
+        body = put.json()
+        by_name = {e["name"]: e for e in body["selected"]}
+        assert "路人乙" in by_name and "author_pin" in by_name["路人乙"]["reasons"]
+        assert "林动" not in by_name  # 排除生效
+        assert body["recent_n"] == 2
+        assert body["pinned"] == [{"kind": "character", "name": "路人乙"}]
+        assert body["excluded"] == [{"kind": "character", "name": "林动"}]
+
+        # 覆盖已落 fake repo → GET 回放同一结果（看到的=写章用的）。
+        got = await client.get(f"/projects/{pid}/chapters/3/injection")
+        assert got.status_code == 200
+        got_names = {e["name"] for e in got.json()["selected"]}
+        assert "路人乙" in got_names and "林动" not in got_names
+
+
+@pytest.mark.asyncio
+async def test_injection_put_unknown_project_404() -> None:
+    repo = FakeProjectRepo()
+    client = _make_client(project_repo=repo, memory_repos=_memory_repos())
+    async with client:
+        resp = await client.put(
+            f"/projects/{uuid.uuid4()}/chapters/1/injection",
+            json={"pinned": [], "excluded": [], "recent_n": None},
+        )
+    assert resp.status_code == 404
+    assert resp.json()["error"]["code"] == ErrorCode.NOT_FOUND
+
+
+@pytest.mark.asyncio
+async def test_injection_put_rejects_out_of_range_recent_n() -> None:
+    repo = FakeProjectRepo()
+    pid = await _create_project(repo)
+    client = _make_client(project_repo=repo, memory_repos=_memory_repos())
+    async with client:
+        resp = await client.put(
+            f"/projects/{pid}/chapters/1/injection",
+            json={"pinned": [], "excluded": [], "recent_n": 999},
+        )
+    assert resp.status_code == 422
--- a/apps/api/tests/test_projects.py
+++ b/apps/api/tests/test_projects.py
@@ -67,6 +67,13 @@ class _StubProjectSpecRepo:
        return ProjectSpecView(title="测试作品", premise="测试前提")


+class _NoInjectionRepo:
+    """空注入覆盖 stub：draft 端点读它得 None（纯自动选择），不打真 DB。"""
+
+    async def get(self, project_id: uuid.UUID, chapter_no: int) -> None:
+        return None
+
+
 def _empty_memory_repos() -> MemoryRepos:
    return MemoryRepos(
        outline=_EmptyOutlineRepo(),
@@ -92,6 +99,7 @@ def _make_client(
    from ww_api.main import create_app
    from ww_api.services.project_deps import (
        get_chapter_repo,
+        get_injection_repo,
        get_memory_repos,
        get_project_repo,
        get_writer_gateway,
@@ -106,6 +114,8 @@ def _make_client(
    app.dependency_overrides[get_chapter_repo] = lambda: chapter_repo
    app.dependency_overrides[get_memory_repos] = _empty_memory_repos
    app.dependency_overrides[get_writer_gateway] = lambda: gateway
+    # draft 端点现读注入覆盖：注空 stub，避免单测打真 DB（无覆盖 → 纯自动选择）。
+    app.dependency_overrides[get_injection_repo] = lambda: _NoInjectionRepo()
    transport = httpx.ASGITransport(app=app)
    client = httpx.AsyncClient(transport=transport, base_url="http://test")
    return client, project_repo, chapter_repo, gateway
--- a/apps/api/ww_api/routers/projects.py
+++ b/apps/api/ww_api/routers/projects.py
@@ -22,6 +22,7 @@ from fastapi.responses import StreamingResponse
 from sqlalchemy.ext.asyncio import AsyncSession
 from ww_core.domain.chapter_repo import ChapterRepo
 from ww_core.domain.digest_repo import DigestAppendRepo
+from ww_core.domain.injection_repo import EntityRef, InjectionOverride, InjectionOverrideRepo
 from ww_core.domain.project_repo import ProjectCreate, ProjectRepo
 from ww_core.domain.repositories import MemoryRepos
 from ww_core.domain.review_repo import ReviewRepo
@@ -41,7 +42,12 @@ from ww_llm_gateway import Gateway
 from ww_shared import AppError, ErrorCode

 from ww_api.logging_config import get_logger
-from ww_api.schemas.injection import InjectionEntity, InjectionResponse
+from ww_api.schemas.injection import (
+    InjectionEntity,
+    InjectionEntityRef,
+    InjectionOverrideRequest,
+    InjectionResponse,
+)
 from ww_api.schemas.projects import (
    AcceptRequest,
    AcceptResponse,
@@ -67,6 +73,7 @@ from ww_api.services.project_deps import (
    get_chapter_repo,
    get_digest_append_repo,
    get_digest_gateway,
+    get_injection_repo,
    get_memory_repos,
    get_project_repo,
    get_review_gateway,
@@ -85,6 +92,7 @@ GatewayDep = Annotated[Gateway, Depends(get_writer_gateway)]
 ReviewGatewayDep = Annotated[Gateway, Depends(get_review_gateway)]
 DigestGatewayDep = Annotated[Gateway, Depends(get_digest_gateway)]
 MemoryReposDep = Annotated[MemoryRepos, Depends(get_memory_repos)]
+InjectionRepoDep = Annotated[InjectionOverrideRepo, Depends(get_injection_repo)]
 ReviewRepoDep = Annotated[ReviewRepo, Depends(get_review_repo)]
 DigestRepoDep = Annotated[DigestAppendRepo, Depends(get_digest_append_repo)]

@@ -126,36 +134,95 @@ async def get_project(project_id: uuid.UUID, repo: ProjectRepoDep) -> ProjectRes
    return _to_response(view)


+async def _injection_response(
+    repos: MemoryRepos,
+    project_id: uuid.UUID,
+    chapter_no: int,
+    override: InjectionOverride | None,
+) -> InjectionResponse:
+    """组装注入响应：以作者覆盖跑确定性 assemble → selected + override 回显（GET/PUT 共用）。"""
+    context = await assemble(repos, project_id, chapter_no, override=override)
+    selected = [
+        InjectionEntity(kind=e.kind, name=e.name, reasons=list(e.reasons))
+        for e in context.selection.selected
+    ]
+    effective_n = override.recent_n if (override and override.recent_n) else RECENT_DIGEST_COUNT
+    return InjectionResponse(
+        project_id=project_id,
+        chapter_no=chapter_no,
+        selected=selected,
+        recent_n=effective_n,
+        pinned=[
+            InjectionEntityRef(kind=r.kind, name=r.name)
+            for r in (override.pinned if override else [])
+        ],
+        excluded=[
+            InjectionEntityRef(kind=r.kind, name=r.name)
+            for r in (override.excluded if override else [])
+        ],
+    )
+
+
@router.get("/{project_id}/chapters/{chapter_no}/injection")
 async def get_injection(
    project_id: uuid.UUID,
    chapter_no: int,
    repos: MemoryReposDep,
    project_repo: ProjectRepoDep,
+    injection_repo: InjectionRepoDep,
 ) -> InjectionResponse:
-    """本章注入透明（B0，读端点）：回放确定性 SelectionTrace。无 LLM、无 commit。
+    """本章注入透明（B0，读端点）：回放确定性 SelectionTrace + 作者覆盖。无 LLM、无 commit。

    项目不存在 → 404；无大纲 → selected: []（不报错）。看到的=写章用的（不变量 #6）。
    """
    if await project_repo.get(STUB_OWNER_ID, project_id) is None:
        raise AppError(ErrorCode.NOT_FOUND, f"project {project_id} not found")
-    context = await assemble(repos, project_id, chapter_no)
-    selected = [
-        InjectionEntity(kind=e.kind, name=e.name, reasons=list(e.reasons))
-        for e in context.selection.selected
-    ]
+    override = await injection_repo.get(project_id, chapter_no)
+    resp = await _injection_response(repos, project_id, chapter_no, override)
    log.info(
        "injection_read",
        project_id=str(project_id),
        chapter_no=chapter_no,
-        selected_count=len(selected),
+        selected_count=len(resp.selected),
+        pinned_count=len(resp.pinned),
+        excluded_count=len(resp.excluded),
    )
-    return InjectionResponse(
-        project_id=project_id,
+    return resp
+
+
+@router.put("/{project_id}/chapters/{chapter_no}/injection")
+async def save_injection(
+    project_id: uuid.UUID,
+    chapter_no: int,
+    body: InjectionOverrideRequest,
+    repos: MemoryReposDep,
+    project_repo: ProjectRepoDep,
+    injection_repo: InjectionRepoDep,
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> InjectionResponse:
+    """本章注入覆盖（B0 可控版，写端点）：存 pin/排除/recent_n → 回放新的确定性 selected。
+
+    项目不存在 → 404。upsert 只 flush，端点末尾 commit。覆盖是确定性输入，draft 端点同读，
+    故「看到的=写章用的」仍成立（不变量 #6 的作者兜底）。
+    """
+    if await project_repo.get(STUB_OWNER_ID, project_id) is None:
+        raise AppError(ErrorCode.NOT_FOUND, f"project {project_id} not found")
+    override = InjectionOverride(
+        pinned=[EntityRef(kind=r.kind, name=r.name) for r in body.pinned],
+        excluded=[EntityRef(kind=r.kind, name=r.name) for r in body.excluded],
+        recent_n=body.recent_n,
+    )
+    saved = await injection_repo.upsert(project_id, chapter_no, override)
+    await session.commit()
+    log.info(
+        "injection_saved",
+        project_id=str(project_id),
        chapter_no=chapter_no,
-        selected=selected,
-        recent_n=RECENT_DIGEST_COUNT,
+        pinned_count=len(saved.pinned),
+        excluded_count=len(saved.excluded),
+        recent_n=saved.recent_n,
    )
+    return await _injection_response(repos, project_id, chapter_no, saved)


 def _encode_sse(event: SseEvent) -> str:
@@ -171,11 +238,13 @@ async def stream_draft(
    request: Request,
    repos: MemoryReposDep,
    gateway: GatewayDep,
+    injection_repo: InjectionRepoDep,
    session: Annotated[AsyncSession, Depends(get_session)],
 ) -> StreamingResponse:
-    """流式写章草稿：组装记忆 → 网关流 → 归一为 SSE 事件 → text/event-stream。"""
+    """流式写章草稿：组装记忆（含作者注入覆盖）→ 网关流 → 归一为 SSE 事件 → text/event-stream。"""
    request_id = getattr(request.state, "request_id", None)
-    context = await assemble(repos, project_id, chapter_no)
+    override = await injection_repo.get(project_id, chapter_no)
+    context = await assemble(repos, project_id, chapter_no, override=override)
    log.info(
        "draft_stream_start",
        project_id=str(project_id),
--- a/apps/api/ww_api/schemas/injection.py
+++ b/apps/api/ww_api/schemas/injection.py
@@ -1,7 +1,9 @@
-"""本章注入透明（B0）的响应 schema（C 扩 / ARCH §3.4、§5.3）。
+"""本章注入透明（B0）的请求/响应 schema（C 扩 / ARCH §3.4、§5.3）。

 snake_case；前端经 OpenAPI 生成 TS 类型消费。改字段 → 前端必须 `pnpm gen:api`。
-读取无 LLM、无 commit——仅回放 assemble() 的确定性 SelectionTrace（不变量 #6）。
+读取无 LLM、无 commit——回放 assemble() 的确定性 SelectionTrace（不变量 #6）。
+可控版（PUT）存作者覆盖：pin 强制纳入 / excluded 强制剔除 / recent_n 覆盖回看章数，
+本身仍是确定性输入，故「看到的=写章用的」成立。
 """

 from __future__ import annotations
@@ -10,6 +12,10 @@ import uuid

 from pydantic import BaseModel, Field

+# recent_n 合法区间（回看近况摘要章数）——下限 1，上限防作者误填爆 token。
+RECENT_N_MIN = 1
+RECENT_N_MAX = 20
+

 class InjectionEntity(BaseModel):
    """一个被注入本章上下文的实体 + 入选理由（喂给透明面板的徽标）。"""
@@ -18,14 +24,39 @@ class InjectionEntity(BaseModel):
    name: str
    reasons: list[str] = Field(
        default_factory=list,
-        description="explicit_beat / main_character / recent_digest / foreshadow_window",
+        description="explicit_beat/main_character/recent_digest/foreshadow_window/author_pin",
    )


+class InjectionEntityRef(BaseModel):
+    """作者 pin/排除点名的实体引用（kind + name）。"""
+
+    kind: str = Field(description="character / world_entity")
+    name: str
+
+
+class InjectionOverrideRequest(BaseModel):
+    """PUT /projects/:id/chapters/:no/injection：作者对本章注入的覆盖。
+
+    pinned 强制纳入（加 author_pin 理由）；excluded 强制剔除；recent_n 覆盖近况回看章数
+    （None=用默认）。空覆盖 = 纯自动选择。
+    """
+
+    pinned: list[InjectionEntityRef] = Field(default_factory=list)
+    excluded: list[InjectionEntityRef] = Field(default_factory=list)
+    recent_n: int | None = Field(default=None, ge=RECENT_N_MIN, le=RECENT_N_MAX)
+
+
 class InjectionResponse(BaseModel):
-    """GET /projects/:id/chapters/:no/injection：本章确定性注入留痕。"""
+    """GET/PUT /projects/:id/chapters/:no/injection：本章注入留痕 + 作者覆盖回显。"""

    project_id: uuid.UUID
    chapter_no: int
    selected: list[InjectionEntity] = Field(default_factory=list)
-    recent_n: int = Field(description="近况摘要回看章数（确定性选择的默认参数）")
+    recent_n: int = Field(description="生效的近况回看章数（默认或被 override 覆盖后的值）")
+    pinned: list[InjectionEntityRef] = Field(
+        default_factory=list, description="作者强制纳入的实体（回显）"
+    )
+    excluded: list[InjectionEntityRef] = Field(
+        default_factory=list, description="作者强制剔除的实体（回显，供面板恢复）"
+    )
--- a/apps/api/ww_api/services/project_deps.py
+++ b/apps/api/ww_api/services/project_deps.py
@@ -20,6 +20,7 @@ from ww_core.domain import ForeshadowLedgerRepo, SqlForeshadowLedgerRepo
 from ww_core.domain.chapter_repo import ChapterRepo, SqlChapterRepo
 from ww_core.domain.character_repo import CharacterWriteRepo, SqlCharacterWriteRepo
 from ww_core.domain.digest_repo import DigestAppendRepo, SqlDigestAppendRepo
+from ww_core.domain.injection_repo import InjectionOverrideRepo, SqlInjectionOverrideRepo
 from ww_core.domain.job_repo import JobRepo, SqlJobRepo
 from ww_core.domain.outline_write_repo import OutlineWriteRepo, SqlOutlineWriteRepo
 from ww_core.domain.project_repo import ProjectRepo, SqlProjectRepo
@@ -102,6 +103,16 @@ def get_memory_repos(
    return sql_memory_repos(session)


+def get_injection_repo(
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> InjectionOverrideRepo:
+    """本章注入覆盖读/写 repo（B0 可控版 GET/PUT injection + draft 同读）。
+
+    upsert 只 flush，端点提交（与其它写侧一致）。测试经 `app.dependency_overrides` 注 fake。
+    """
+    return SqlInjectionOverrideRepo(session)
+
+
 def get_review_repo(
    session: Annotated[AsyncSession, Depends(get_session)],
 ) -> ReviewRepo:
--- a/apps/web/lib/api/schema.d.ts
+++ b/apps/web/lib/api/schema.d.ts
@@ -99,12 +99,19 @@ export interface paths {
        };
        /**
         * Get Injection
-         * @description 本章注入透明（B0，读端点）：回放确定性 SelectionTrace。无 LLM、无 commit。
+         * @description 本章注入透明（B0，读端点）：回放确定性 SelectionTrace + 作者覆盖。无 LLM、无 commit。
         *
         *     项目不存在 → 404；无大纲 → selected: []（不报错）。看到的=写章用的（不变量 #6）。
         */
        get: operations["get_injection_projects__project_id__chapters__chapter_no__injection_get"];
-        put?: never;
+        /**
+         * Save Injection
+         * @description 本章注入覆盖（B0 可控版，写端点）：存 pin/排除/recent_n → 回放新的确定性 selected。
+         *
+         *     项目不存在 → 404。upsert 只 flush，端点末尾 commit。覆盖是确定性输入，draft 端点同读，
+         *     故「看到的=写章用的」仍成立（不变量 #6 的作者兜底）。
+         */
+        put: operations["save_injection_projects__project_id__chapters__chapter_no__injection_put"];
        post?: never;
        delete?: never;
        options?: never;
@@ -135,7 +142,7 @@ export interface paths {
        put: operations["save_draft_projects__project_id__chapters__chapter_no__draft_put"];
        /**
         * Stream Draft
-         * @description 流式写章草稿：组装记忆 → 网关流 → 归一为 SSE 事件 → text/event-stream。
+         * @description 流式写章草稿：组装记忆（含作者注入覆盖）→ 网关流 → 归一为 SSE 事件 → text/event-stream。
         */
        post: operations["stream_draft_projects__project_id__chapters__chapter_no__draft_post"];
        delete?: never;
@@ -994,13 +1001,41 @@ export interface components {
            name: string;
            /**
             * Reasons
-             * @description explicit_beat / main_character / recent_digest / foreshadow_window
+             * @description explicit_beat/main_character/recent_digest/foreshadow_window/author_pin
             */
            reasons?: string[];
        };
+        /**
+         * InjectionEntityRef
+         * @description 作者 pin/排除点名的实体引用（kind + name）。
+         */
+        InjectionEntityRef: {
+            /**
+             * Kind
+             * @description character / world_entity
+             */
+            kind: string;
+            /** Name */
+            name: string;
+        };
+        /**
+         * InjectionOverrideRequest
+         * @description PUT /projects/:id/chapters/:no/injection：作者对本章注入的覆盖。
+         *
+         *     pinned 强制纳入（加 author_pin 理由）；excluded 强制剔除；recent_n 覆盖近况回看章数
+         *     （None=用默认）。空覆盖 = 纯自动选择。
+         */
+        InjectionOverrideRequest: {
+            /** Pinned */
+            pinned?: components["schemas"]["InjectionEntityRef"][];
+            /** Excluded */
+            excluded?: components["schemas"]["InjectionEntityRef"][];
+            /** Recent N */
+            recent_n?: number | null;
+        };
        /**
         * InjectionResponse
-         * @description GET /projects/:id/chapters/:no/injection：本章确定性注入留痕。
+         * @description GET/PUT /projects/:id/chapters/:no/injection：本章注入留痕 + 作者覆盖回显。
         */
        InjectionResponse: {
            /**
@@ -1014,9 +1049,19 @@ export interface components {
            selected?: components["schemas"]["InjectionEntity"][];
            /**
             * Recent N
-             * @description 近况摘要回看章数（确定性选择的默认参数）
+             * @description 生效的近况回看章数（默认或被 override 覆盖后的值）
             */
            recent_n: number;
+            /**
+             * Pinned
+             * @description 作者强制纳入的实体（回显）
+             */
+            pinned?: components["schemas"]["InjectionEntityRef"][];
+            /**
+             * Excluded
+             * @description 作者强制剔除的实体（回显，供面板恢复）
+             */
+            excluded?: components["schemas"]["InjectionEntityRef"][];
        };
        /**
         * OAuthDisconnectResponse
@@ -1689,6 +1734,42 @@ export interface operations {
            };
        };
    };
+    save_injection_projects__project_id__chapters__chapter_no__injection_put: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                project_id: string;
+                chapter_no: number;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["InjectionOverrideRequest"];
+            };
+        };
+        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;
--- a/apps/web/tsconfig.tsbuildinfo
+++ b/apps/web/tsconfig.tsbuildinfo
--- a/memory/contracts.md
+++ b/memory/contracts.md
@@ -302,4 +302,6 @@

 - [2026-06-20] @backend 扩 C3：新增 **`GET /projects/{project_id}/chapters/{chapter_no}/injection`**（本章注入透明，B0 读端点）→ `InjectionResponse{project_id, chapter_no, selected:[InjectionEntity{kind,name,reasons[]}], recent_n}`（`schemas/injection.py`，snake_case）。实现仅调既有 `assemble()` 回放确定性 `SelectionTrace`——**无 LLM、无 commit、无 DDL**；项目不存在→404，无大纲→`selected:[]`。reasons 取值同 `SelectionReason`（explicit_beat/main_character/recent_digest/foreshadow_window）。→ 影响 @frontend（已 `pnpm gen:api` + `ChapterAssistant` 消费）。**B0 可控版（PUT override + `select_relevant_entities` 加 pinned/excluded/recent_n + draft 端点同读 override + 持久化）尚未实现，届时再扩本契约。**

+- [2026-06-20] @backend 再扩 C3（B0 **可控版**，接上条）：新增 **`PUT /projects/{project_id}/chapters/{chapter_no}/injection`** ← `InjectionOverrideRequest{pinned:[{kind,name}], excluded:[{kind,name}], recent_n:int|null(1..20)}` → 返回 `InjectionResponse`（同上，**新增回显字段 `pinned`/`excluded`**，`selected[].reasons` 可含新值 **`author_pin`**）。语义：pin 强制纳入并加 `author_pin` 理由 / excluded 强制剔除（**优先于 pin**）/ recent_n 覆盖近况回看章数。GET injection 与 **draft 流式端点**均先读同一覆盖再 `assemble(override=...)`，故「看到的=写章用的」（不变量 #6 作者兜底）。持久化：**新表 `chapter_injection`**（迁移 `ad2c4c663daf`，唯一 `(project_id,chapter_no)`，复用 outline 行已否决）；`select_relevant_entities` 加 `pinned/excluded` frozenset 入参、`assemble` 加 `override` 关键字参；新 `domain/injection_repo.py`（`InjectionOverride`/`EntityRef`/`SqlInjectionOverrideRepo`，upsert 只 flush 端点 commit）。→ 影响 @frontend（已 `pnpm gen:api`；F1 加 pin/排除控件 + recent_n 步进器）。
+
 - [2026-06-18] @llm 改 C1：`Gateway.run()` 现消费 `LlmRequest.output_schema`——`OpenAICompatAdapter.complete` 在 schema 非空时经 **instructor**(`create_with_completion(response_model=...)`) 取已校验 Pydantic 实例并填 `LlmResponse.parsed`；无 schema 时 `parsed is None`、纯文本路径不变；记账仍 **1 条 usage_ledger**/调用（usage 从 raw completion 提取）。`ProviderResult` 新增 `parsed` 字段。结构化路径经可注入 `StructuredClient` Protocol 注 fake（测试不联网）。→ 影响 T2.2（续审节点可直接 `gateway.run(req).parsed`）、未来所有结构化输出 Agent。
--- a/packages/core/tests/test_memory.py
+++ b/packages/core/tests/test_memory.py
@@ -200,6 +200,99 @@ def test_union_dedups_reasons_sorted() -> None:
    ]


+# ---- author override: pin / exclude / recent_n (B0 可控版) ----
+
+
+def test_pin_forces_inclusion_with_author_pin_reason() -> None:
+    # 路人甲零自动理由——pin 强制纳入并加 author_pin。
+    outline = OutlineView(volume=1, chapter_no=1, beats={})
+    trace = select_relevant_entities(
+        outline=outline,
+        characters=[char("路人甲", role="配角")],
+        world_entities=[],
+        recent_digests=[],
+        pinned=frozenset({("character", "路人甲")}),
+    )
+    selected = [e for e in trace.selected if e.name == "路人甲"]
+    assert len(selected) == 1
+    assert selected[0].reasons == ["author_pin"]
+
+
+def test_pin_appends_author_pin_to_existing_reasons() -> None:
+    outline = OutlineView(volume=1, chapter_no=1, beats={})
+    trace = select_relevant_entities(
+        outline=outline,
+        characters=[char("林动", role="主角")],
+        world_entities=[],
+        recent_digests=[],
+        pinned=frozenset({("character", "林动")}),
+    )
+    main = next(e for e in trace.selected if e.name == "林动")
+    assert main.reasons == ["main_character", "author_pin"]  # 规范顺序，author_pin 末位
+
+
+def test_exclude_removes_auto_selected_entity() -> None:
+    # 主角林动本会自动入选——excluded 强制剔除。
+    outline = OutlineView(volume=1, chapter_no=1, beats={})
+    trace = select_relevant_entities(
+        outline=outline,
+        characters=[char("林动", role="主角")],
+        world_entities=[],
+        recent_digests=[],
+        excluded=frozenset({("character", "林动")}),
+    )
+    assert all(e.name != "林动" for e in trace.selected)
+
+
+def test_exclude_wins_over_pin() -> None:
+    # 同一实体同时 pin + exclude（前端不会，但防御）：排除优先。
+    outline = OutlineView(volume=1, chapter_no=1, beats={})
+    trace = select_relevant_entities(
+        outline=outline,
+        characters=[char("林动", role="主角")],
+        world_entities=[],
+        recent_digests=[],
+        pinned=frozenset({("character", "林动")}),
+        excluded=frozenset({("character", "林动")}),
+    )
+    assert all(e.name != "林动" for e in trace.selected)
+
+
+async def test_assemble_override_pins_and_excludes() -> None:
+    from ww_core.domain.injection_repo import EntityRef, InjectionOverride
+
+    repos = build_repos(
+        characters=[char("林动", role="主角"), char("路人乙", role="龙套")],
+        spec=ProjectSpecView(title="书"),
+    )
+    override = InjectionOverride(
+        pinned=[EntityRef(kind="character", name="路人乙")],
+        excluded=[EntityRef(kind="character", name="林动")],
+    )
+    ctx = await assemble(repos, PROJECT, 1, override=override)
+    names = {e.name for e in ctx.selection.selected}
+    assert "路人乙" in names  # pin 强制纳入
+    assert "林动" not in names  # exclude 强制剔除
+
+
+async def test_assemble_override_recent_n_limits_digests() -> None:
+    from ww_core.domain.injection_repo import InjectionOverride
+
+    digests = [DigestView(chapter_no=n, facts={"entities": [f"实体{n}"]}) for n in range(1, 6)]
+    world = [WorldEntityView(type="设定", name=f"实体{n}") for n in range(1, 6)]
+    repos = build_repos(
+        outline={10: OutlineView(volume=1, chapter_no=10, beats={})},
+        world=world,
+        digests=digests,
+        spec=ProjectSpecView(title="书"),
+    )
+    # recent_n=1 → 只回看最近一章（第5章）的实体5 命中 recent_digest。
+    ctx = await assemble(repos, PROJECT, 10, override=InjectionOverride(recent_n=1))
+    names = {e.name for e in ctx.selection.selected}
+    assert "实体5" in names
+    assert "实体1" not in names
+
+
 # ---- render_cards ----


--- a/packages/core/ww_core/domain/init.py
+++ b/packages/core/ww_core/domain/init.py
@@ -30,6 +30,12 @@ from ww_core.domain.foreshadow_state import (
    is_overdue,
    transition,
 )
+from ww_core.domain.injection_repo import (
+    EntityRef,
+    InjectionOverride,
+    InjectionOverrideRepo,
+    SqlInjectionOverrideRepo,
+)
 from ww_core.domain.job_repo import (
    JobRepo,
    JobView,
@@ -79,6 +85,10 @@ __all__ = [
    "SqlForeshadowLedgerRepo",
    "ForeshadowStatus",
    "InvalidTransition",
+    "EntityRef",
+    "InjectionOverride",
+    "InjectionOverrideRepo",
+    "SqlInjectionOverrideRepo",
    "JobRepo",
    "JobView",
    "SqlJobRepo",
--- a/packages/core/ww_core/domain/injection_repo.py
+++ b/packages/core/ww_core/domain/injection_repo.py
@@ -0,0 +1,123 @@
+"""本章注入覆盖（B0 可控版）的写/读 Repository（ARCH §3.4 作者手动 pin 兜底）。
+
+作者在「本章注入（透明）」面板里对确定性自动选择做微调——把某实体强制纳入（pin）、
+强制剔除（excluded）、或覆盖近况回看章数（recent_n）。这是不变量 #6「确定性选择」的
+**作者兜底**：override 本身是确定性输入的一部分（同一 (project_id, chapter_no) 存一行），
+故「看到的=写章用的」仍成立——draft 端点与注入读端点都读同一覆盖。
+
+**提交边界**：`upsert` 只 `flush()` 不 `commit()`——提交交端点（与 outline/rule 等写侧一致，
+见 memory/gotchas）。唯一约束 `(project_id, chapter_no)`：显式 read-modify-write upsert。
+
+**与 beats 隔离**：单独建 `chapter_injection` 表存覆盖，**不复用 outline 行**——复用会污染
+beats/prompt（已否决，见 memory/decisions）。
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Protocol
+
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from ww_db.models import ChapterInjection
+
+
+class EntityRef(BaseModel):
+    """一个被作者点名 pin/排除的实体引用（kind + name；frozen 便于入 set 去重）。"""
+
+    model_config = {"frozen": True}
+
+    kind: str
+    name: str
+
+
+class InjectionOverride(BaseModel):
+    """作者对本章确定性注入的覆盖（pin 强制纳入 / excluded 强制剔除 / recent_n 覆盖回看章数）。
+
+    全可选——空覆盖等价于「纯自动选择」。recent_n=None → 用默认 RECENT_DIGEST_COUNT。
+    """
+
+    model_config = {"frozen": True}
+
+    pinned: list[EntityRef] = Field(default_factory=list)
+    excluded: list[EntityRef] = Field(default_factory=list)
+    recent_n: int | None = None
+
+
+class InjectionOverrideRepo(Protocol):
+    """注入覆盖读/写接口（project_id 隔离；唯一 (project_id, chapter_no)；只 flush 不 commit）。"""
+
+    async def get(self, project_id: uuid.UUID, chapter_no: int) -> InjectionOverride | None: ...
+
+    async def upsert(
+        self, project_id: uuid.UUID, chapter_no: int, override: InjectionOverride
+    ) -> InjectionOverride: ...
+
+
+def _refs(raw: object) -> list[EntityRef]:
+    """JSONB list[{kind,name}] → list[EntityRef]（容错：跳过形不对的项，不抛）。"""
+    if not isinstance(raw, list):
+        return []
+    out: list[EntityRef] = []
+    for item in raw:
+        if isinstance(item, dict) and "kind" in item and "name" in item:
+            out.append(EntityRef(kind=str(item["kind"]), name=str(item["name"])))
+    return out
+
+
+def _to_override(row: ChapterInjection) -> InjectionOverride:
+    return InjectionOverride(
+        pinned=_refs(row.pinned),
+        excluded=_refs(row.excluded),
+        recent_n=row.recent_n,
+    )
+
+
+class SqlInjectionOverrideRepo:
+    """SQLAlchemy 实现：显式 read-modify-write upsert（只 flush 不 commit）。"""
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._s = session
+
+    async def get(self, project_id: uuid.UUID, chapter_no: int) -> InjectionOverride | None:
+        row = (
+            await self._s.execute(
+                select(ChapterInjection).where(
+                    ChapterInjection.project_id == project_id,
+                    ChapterInjection.chapter_no == chapter_no,
+                )
+            )
+        ).scalar_one_or_none()
+        return _to_override(row) if row is not None else None
+
+    async def upsert(
+        self, project_id: uuid.UUID, chapter_no: int, override: InjectionOverride
+    ) -> InjectionOverride:
+        # JSONB 写入建新对象重赋值（避免原地 mutate 不被 ORM 侦测，见 gotcha）。
+        pinned_payload = [r.model_dump() for r in override.pinned]
+        excluded_payload = [r.model_dump() for r in override.excluded]
+        row = (
+            await self._s.execute(
+                select(ChapterInjection).where(
+                    ChapterInjection.project_id == project_id,
+                    ChapterInjection.chapter_no == chapter_no,
+                )
+            )
+        ).scalar_one_or_none()
+        if row is None:
+            row = ChapterInjection(
+                project_id=project_id,
+                chapter_no=chapter_no,
+                pinned=pinned_payload,
+                excluded=excluded_payload,
+                recent_n=override.recent_n,
+            )
+            self._s.add(row)
+        else:
+            row.pinned = pinned_payload
+            row.excluded = excluded_payload
+            row.recent_n = override.recent_n
+        await self._s.flush()
+        await self._s.refresh(row)
+        return _to_override(row)
--- a/packages/core/ww_core/memory/assemble.py
+++ b/packages/core/ww_core/memory/assemble.py
@@ -11,6 +11,7 @@ import json
 import uuid
 from typing import Any

+from ww_core.domain.injection_repo import InjectionOverride
 from ww_core.domain.repositories import (
    CharacterView,
    DigestView,
@@ -24,8 +25,8 @@ from ww_core.domain.repositories import (
 )

 from .render import render_cards
-from .selection import MAIN_ROLES, RECENT_DIGEST_COUNT, select_relevant_entities
-from .types import AssembledContext
+from .selection import MAIN_ROLES, RECENT_DIGEST_COUNT, EntityKey, select_relevant_entities
+from .types import AssembledContext, EntityKind

 # 四级规则合并优先级：global → genre → style → project（越具体越靠后/越优先）
 _LEVEL_RANK: dict[str, int] = {"global": 0, "genre": 1, "style": 2, "project": 3}
@@ -35,6 +36,11 @@ def _ser(value: Any) -> str:
    return json.dumps(value, ensure_ascii=False, sort_keys=True)


+def _kind(raw: str) -> EntityKind:
+    """把覆盖里的字符串 kind 收敛成 EntityKind 字面量（未知值按 character 处理，不匹配亦无害）。"""
+    return "world_entity" if raw == "world_entity" else "character"
+
+
 def merge_rules(rules: list[RuleView]) -> list[RuleView]:
    """按 global→genre→style→project 排序（同级按内容排序，确定性）。"""
    return sorted(rules, key=lambda r: (_LEVEL_RANK.get(r.level, 99), r.level, r.content))
@@ -122,20 +128,37 @@ async def assemble(
    project_id: uuid.UUID,
    chapter_no: int,
    recent_k: int = RECENT_DIGEST_COUNT,
+    *,
+    override: InjectionOverride | None = None,
 ) -> AssembledContext:
-    """组装本章 prompt 上下文（确定性、可缓存）。"""
+    """组装本章 prompt 上下文（确定性、可缓存）。
+
+    `override`（B0 可控版作者覆盖）也是确定性输入：pin 强制纳入 / excluded 强制剔除 /
+    recent_n 覆盖近况回看章数。draft 与注入读端点传同一覆盖，故「看到的=写章用的」（不变量 #6）。
+    """
+    # recent_n 覆盖优先于默认 recent_k；非正值视为未设（守住至少回看若干章）。
+    effective_k = override.recent_n if (override and override.recent_n) else recent_k
+    pinned: frozenset[EntityKey] = (
+        frozenset((_kind(r.kind), r.name) for r in override.pinned) if override else frozenset()
+    )
+    excluded: frozenset[EntityKey] = (
+        frozenset((_kind(r.kind), r.name) for r in override.excluded) if override else frozenset()
+    )
+
    outline = await repos.outline.get(project_id, chapter_no) or OutlineView(
        volume=0, chapter_no=chapter_no
    )
    characters = await repos.character.list_for_project(project_id)
    world_entities = await repos.world_entity.list_for_project(project_id)
-    recent_digests = await repos.digest.recent(project_id, recent_k)
+    recent_digests = await repos.digest.recent(project_id, effective_k)

    selection = select_relevant_entities(
        outline=outline,
        characters=characters,
        world_entities=world_entities,
        recent_digests=recent_digests,
+        pinned=pinned,
+        excluded=excluded,
    )

    codes = [str(w["code"]) for w in outline.foreshadow_windows if w.get("code")]
--- a/packages/core/ww_core/memory/selection.py
+++ b/packages/core/ww_core/memory/selection.py
@@ -23,8 +23,12 @@ _REASON_RANK: dict[SelectionReason, int] = {
    "main_character": 1,
    "recent_digest": 2,
    "foreshadow_window": 3,
+    "author_pin": 4,
 }

+# 实体引用键（kind, name）——pin/排除集合用，确定性、可 hash。
+EntityKey = tuple[EntityKind, str]
+

 def _flatten_strings(obj: Any) -> list[str]:
    """递归收集任意 JSON 结构里的字符串叶子（确定性、用于按名匹配）。"""
@@ -78,8 +82,15 @@ def select_relevant_entities(
    characters: list[CharacterView],
    world_entities: list[WorldEntityView],
    recent_digests: list[DigestView],
+    pinned: frozenset[EntityKey] = frozenset(),
+    excluded: frozenset[EntityKey] = frozenset(),
 ) -> SelectionTrace:
-    """确定性并集选择 → SelectionTrace（每实体带去重、排序的入选理由）。"""
+    """确定性并集选择 → SelectionTrace（每实体带去重、排序的入选理由）。
+
+    作者覆盖（B0 可控版）：`excluded` 强制剔除（优先于一切，即便自动命中也不注入）；
+    `pinned` 强制纳入并加 `author_pin` 理由（即便零自动理由也注入）。excluded 优先于 pinned，
+    因为「显式排除」是更强的作者意图（同一实体不应同时出现在两个集合，前端保证）。
+    """
    beat_listed, beat_text = _explicit_names(outline.beats)
    digest_listed, digest_text = _digest_names(recent_digests)
    window_names = _window_entity_names(outline)
@@ -96,17 +107,23 @@ def select_relevant_entities(
            reasons.append("recent_digest")
        if name in window_names:
            reasons.append("foreshadow_window")
-        return sorted(set(reasons), key=lambda r: _REASON_RANK[r])
+        return reasons
+
+    def collect(kind: EntityKind, name: str, *, is_main: bool) -> None:
+        key: EntityKey = (kind, name)
+        if key in excluded:  # 显式排除优先于一切
+            return
+        reasons = reasons_for(name, is_main=is_main)
+        if key in pinned:
+            reasons.append("author_pin")
+        if reasons:
+            deduped = sorted(set(reasons), key=lambda r: _REASON_RANK[r])
+            selected.append(SelectedEntity(kind=kind, name=name, reasons=deduped))

    for c in characters:
-        reasons = reasons_for(c.name, is_main=(c.role or "") in MAIN_ROLES)
-        if reasons:
-            selected.append(SelectedEntity(kind="character", name=c.name, reasons=reasons))
-
+        collect("character", c.name, is_main=(c.role or "") in MAIN_ROLES)
    for w in world_entities:
-        reasons = reasons_for(w.name, is_main=False)
-        if reasons:
-            selected.append(SelectedEntity(kind="world_entity", name=w.name, reasons=reasons))
+        collect("world_entity", w.name, is_main=False)

    selected.sort(key=lambda e: (_KIND_RANK[e.kind], e.name))
    return SelectionTrace(selected=selected)
--- a/packages/core/ww_core/memory/types.py
+++ b/packages/core/ww_core/memory/types.py
@@ -17,14 +17,17 @@ SelectionReason = Literal[
    "main_character",  # 主角/核心常驻
    "recent_digest",  # 近 N 章摘要出现
    "foreshadow_window",  # 命中本章伏笔窗口
+    "author_pin",  # 作者手动置顶（B0 可控版 override 强制纳入）
 ]

-# 理由的规范排序（保证 SelectionTrace 确定性）
+# 理由的规范排序（保证 SelectionTrace 确定性）。author_pin 排末位：
+# 它是作者覆盖的来源，区别于前四个确定性来源（不变量 #6 的作者兜底，ARCH §10）。
 REASON_ORDER: tuple[SelectionReason, ...] = (
    "explicit_beat",
    "main_character",
    "recent_digest",
    "foreshadow_window",
+    "author_pin",
 )


--- a/packages/db/migrations/versions/ad2c4c663daf_t_b0_chapter_injection_override_table.py
+++ b/packages/db/migrations/versions/ad2c4c663daf_t_b0_chapter_injection_override_table.py
@@ -0,0 +1,58 @@
+"""T_B0 chapter_injection override table
+
+Revision ID: ad2c4c663daf
+Revises: 1f011c42bd4d
+Create Date: 2026-06-20 11:51:00.494169
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = "ad2c4c663daf"
+down_revision: str | None = "1f011c42bd4d"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "chapter_injection",
+        sa.Column("project_id", sa.Uuid(), nullable=False),
+        sa.Column("chapter_no", sa.Integer(), nullable=False),
+        sa.Column(
+            "pinned",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'[]'"),
+            nullable=False,
+        ),
+        sa.Column(
+            "excluded",
+            postgresql.JSONB(astext_type=sa.Text()),
+            server_default=sa.text("'[]'"),
+            nullable=False,
+        ),
+        sa.Column("recent_n", sa.Integer(), nullable=True),
+        sa.Column("id", sa.Uuid(), server_default=sa.text("gen_random_uuid()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), server_default=sa.text("now()"), nullable=False),
+        sa.Column("created_at", sa.DateTime(), server_default=sa.text("now()"), nullable=False),
+        sa.ForeignKeyConstraint(["project_id"], ["projects.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("project_id", "chapter_no"),
+    )
+    op.create_index(
+        op.f("ix_chapter_injection_project_id"), "chapter_injection", ["project_id"], unique=False
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f("ix_chapter_injection_project_id"), table_name="chapter_injection")
+    op.drop_table("chapter_injection")
+    # ### end Alembic commands ###
--- a/packages/db/ww_db/models.py
+++ b/packages/db/ww_db/models.py
@@ -152,6 +152,24 @@ class Chapter(UuidPk, CreatedAt, Base):
    version: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("1"))


+class ChapterInjection(UuidPk, TimestampedMixin, Base):
+    """本章注入覆盖（B0 可控版）：作者对确定性自动选择的微调，每章一行。
+
+    与 `outline.beats` 分表存放（复用 outline 行会污染 beats/prompt，已否决）。
+    pinned/excluded 为 JSONB list[{kind,name}]；recent_n 覆盖近况回看章数（NULL=用默认）。
+    """
+
+    __tablename__ = "chapter_injection"
+    __table_args__ = (UniqueConstraint("project_id", "chapter_no"),)
+    project_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    chapter_no: Mapped[int] = mapped_column(Integer, nullable=False)
+    pinned: Mapped[list[Any]] = mapped_column(JSONB, server_default=text("'[]'"))
+    excluded: Mapped[list[Any]] = mapped_column(JSONB, server_default=text("'[]'"))
+    recent_n: Mapped[int | None] = mapped_column(Integer)
+
+
 class ChapterReview(UuidPk, CreatedAt, Base):
    __tablename__ = "chapter_reviews"
    project_id: Mapped[uuid.UUID] = mapped_column(