feat(backend): AI 反问澄清预检端点——refine 侧结构化 clarify（WFW-9 M1，路线A 两阶段）

润色「再沟通」意见含糊时先反问给选项（路线A：问题走独立非流式 JSON 预检端点，正文仍走
既有 refine 一字不改）。新增：
- ClarifyDecision/ClarifyQuestion/ClarifyOption 结构化 schema（既有 output-schema 处，供
  producer 与端点共用）；clarify_refine.md 教条（含糊→need_clarification+≤1问+2–4锚定选项+
  自由输入；明确→verification 放行；防循环）；注册 clarify_refine_spec(analyst 档,#24)+
  SCHEMA_CATALOG + 重生成金标准。
- clarify_node：build_clarify_request 纯函数(缓存前缀不含易变) + run_clarify（gateway.run
  结构化，判别/校验失败确定性回退 need_clarification=false，只读不写库）。
- POST /projects/{id}/chapters/{no}/refine/clarify → ClarifyDecision（analyst 网关，404/503，
  末尾 commit 记账）。**既有 refine 端点/RefineRequest/Response 完全未改**。
门禁绿：ruff/mypy 227/pytest 900(+test_clarify_spec/_node/style clarify)/alembic 无漂移。

packages/core/tests/test_clarify_node.py

@@ -0,0 +1,127 @@
+"""WFW-9 M1 clarify 节点单测：build_clarify_request + run_clarify（路线A 两阶段）。
+
+注入 mock 网关（产 `ClarifyDecision` parsed），无真 LLM、无真 Postgres。clarify 是独立
+非流式预检（不在写章/审稿流水线），裸函数；只判不改、**不写库**（不变量 #3）。asyncio_mode=auto。
+"""
+
+from __future__ import annotations
+
+import uuid
+
+from fakes_orchestrator import FakeRunGateway
+from ww_agents import (
+    ClarifyDecision,
+    ClarifyOption,
+    ClarifyQuestion,
+    WorldGenResult,
+    clarify_refine_spec,
+)
+from ww_core.orchestrator import build_clarify_request, run_clarify
+
+PROJECT = uuid.UUID("00000000-0000-0000-0000-000000000001")
+USER = uuid.UUID("00000000-0000-0000-0000-0000000000aa")
+
+_NEED = ClarifyDecision(
+    need_clarification=True,
+    questions=[
+        ClarifyQuestion(
+            question="你想让这段更有张力，是指哪种方向？",
+            options=[
+                ClarifyOption(label="加快节奏", value="拆短句、压缩铺陈"),
+                ClarifyOption(label="加重冲突", value="强化人物对立"),
+            ],
+            allow_free_text=True,
+        )
+    ],
+)
+
+_CLEAR = ClarifyDecision(
+    need_clarification=False,
+    verification="我会把被字句改成主动句，其余不动，对吗？",
+)
+
+
+# ---- build_clarify_request：analyst 档 + 结构化 + 缓存前缀无易变 ----
+
+
+def test_build_clarify_request_declares_analyst_tier_and_schema() -> None:
+    req = build_clarify_request(
+        clarify_refine_spec,
+        context="## 待重写段落\n原段。\n\n## 改写指令\n再改改",
+        user_id=USER,
+        project_id=PROJECT,
+    )
+    # 不变量 #2：只声明 analyst 档，不传 model。
+    assert req.tier == "analyst"
+    # 结构化预检：非流式 + 带 ClarifyDecision output_schema。
+    assert req.stream is False
+    assert req.output_schema is ClarifyDecision
+    # 注入材料进 input（断点后）。
+    assert "再改改" in req.input
+
+
+def test_build_clarify_request_system_prefix_is_doctrine_only_cacheable() -> None:
+    # 不变量 #9：system 前缀只放教条、cache=True，无历史/时间戳/UUID（可缓存）。
+    req = build_clarify_request(
+        clarify_refine_spec, context="ctx", user_id=USER, project_id=PROJECT
+    )
+    assert len(req.system) == 1
+    block = req.system[0]
+    assert block.cache is True
+    assert block.text == clarify_refine_spec.system_prompt
+    # 易变值绝不进缓存前缀。
+    assert str(PROJECT) not in block.text
+    assert "ctx" not in block.text
+
+
+# ---- run_clarify：正常返回 + 校验失败确定性回退 ----
+
+
+async def test_run_clarify_returns_need_clarification_decision() -> None:
+    gateway = FakeRunGateway(_NEED)
+
+    result = await run_clarify(
+        clarify_refine_spec,
+        context="## 待重写段落\n原段。",
+        gateway=gateway,
+        user_id=USER,
+        project_id=PROJECT,
+    )
+
+    assert isinstance(result, ClarifyDecision)
+    assert result.need_clarification is True
+    assert len(result.questions) == 1
+    assert result.questions[0].options[0].label == "加快节奏"
+    assert gateway.call_count == 1
+
+
+async def test_run_clarify_returns_clear_decision() -> None:
+    gateway = FakeRunGateway(_CLEAR)
+
+    result = await run_clarify(
+        clarify_refine_spec,
+        context="ctx",
+        gateway=gateway,
+        user_id=USER,
+        project_id=PROJECT,
+    )
+
+    assert result.need_clarification is False
+    assert result.verification is not None
+
+
+async def test_run_clarify_falls_back_to_no_clarification_on_wrong_parsed() -> None:
+    # 判别/校验失败：网关返回非 ClarifyDecision（畸形/降级）→ 确定性回退不问、放行。
+    gateway = FakeRunGateway(WorldGenResult(entities=[]))
+
+    result = await run_clarify(
+        clarify_refine_spec,
+        context="ctx",
+        gateway=gateway,
+        user_id=USER,
+        project_id=PROJECT,
+    )
+
+    assert isinstance(result, ClarifyDecision)
+    assert result.need_clarification is False
+    assert result.questions == []

packages/core/ww_core/orchestrator/__init__.py

@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 from ._protocols import GatewayRun
+from .clarify_node import build_clarify_request, run_clarify
 from .collect import (
     CHARACTERIZATION,
     CONTINUITY,
@@ -119,6 +120,7 @@ __all__ = [
     "SseEvent",
     "build_brief_context",
     "build_character_gen_context",
+    "build_clarify_request",
     "build_continuation_context",
     "build_outline_chapter_context",
     "build_outline_request",
@@ -148,6 +150,7 @@ __all__ = [
     "pace_event",
     "precheck_generated_cards",
     "run_character_gen",
+    "run_clarify",
     "run_generator",
     "run_outline",
     "run_review",

packages/core/ww_core/orchestrator/clarify_node.py

@@ -0,0 +1,84 @@
+"""润色预检澄清节点（WFW-9 M1 · 路线A 两阶段之「问题」阶段）。
+
+`run_clarify` 是**独立非流式**预检——不在写章/审稿流水线（不接进 review 图），仿
+`run_generator`。润色端点在真正回炉改写前调它：判「作者这条意见清不清楚」，含糊则反问
+一个问题 + 给选项，清楚则确认理解、放行。正文改写仍走既有 refine 端点，本节点**不改稿**。
+
+确定性边界（CLAUDE.md「LangGraph」纪律）：节点逻辑无 LLM 非确定性——不确定性藏在网关后，
+节点只做 `AgentSpec + 上下文 → LlmRequest` 的纯构造 + 转发 `Gateway.run` 的 `parsed`。
+注入 mock 网关（产 `ClarifyDecision`）即可单测，无需图运行时、无需真 Postgres。
+
+不变量 #2：agent 只声明 `tier`（analyst），绝不传具体 model（spec.tier 透传）。
+不变量 #3：节点**只读、不写库**——只产澄清决策返回调用方，绝不改正文/写任何表。
+不变量 #9：`spec.system_prompt` 进缓存断点前块（cache=True）；注入材料进 `input`（断点后），
+system 前缀只放教条、无历史/时间戳/UUID。
+
+韧性降级：判别/校验失败（网关返回非 `ClarifyDecision`）**确定性回退**为
+`need_clarification=false`（不问、直接放行 refine），绝不阻塞润色主链路。网关本体的瞬时
+失败/回退/熔断/instructor 重试均归网关（§4.5），本节点只感知干净的最终 parsed。
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import structlog
+from ww_agents import AgentSpec, ClarifyDecision
+from ww_llm_gateway.types import Block, LlmRequest, Scope
+
+from ._protocols import GatewayRun
+
+log = structlog.get_logger(__name__)
+
+
+def build_clarify_request(
+    spec: AgentSpec,
+    *,
+    context: str,
+    user_id: uuid.UUID,
+    project_id: uuid.UUID | None,
+) -> LlmRequest:
+    """据 spec + 注入材料构造预检请求（纯函数）。
+
+    `spec.system_prompt` → `system` 缓存断点前块（cache=True，只放教条，不变量 #9）；
+    `context`（序列化的选段 + 再沟通意见）→ `input`（断点后，易变内容）。
+    预检要结构化产物（`ClarifyDecision`）、非流式正文——`stream=False`、带 `output_schema`。
+    """
+    return LlmRequest(
+        tier=spec.tier,  # 不变量 #2：只传档位，不传 model
+        system=[Block(text=spec.system_prompt, cache=True)],
+        input=context,
+        stream=False,
+        output_schema=spec.output_schema,
+        scope=Scope(user_id=user_id, project_id=project_id),
+    )
+
+
+async def run_clarify(
+    spec: AgentSpec,
+    *,
+    context: str,
+    gateway: GatewayRun,
+    user_id: uuid.UUID,
+    project_id: uuid.UUID | None = None,
+) -> ClarifyDecision:
+    """跑润色预检：构请求 → `gateway.run` → 校验 parsed 为 `ClarifyDecision`。
+
+    **判别/校验失败确定性回退**：网关返回非 `ClarifyDecision`（instructor 重试上限后仍
+    畸形 / None）时不上抛，降级为 `need_clarification=false`（不问、直接放行 refine），
+    守「clarify 是非关键预检、绝不阻塞润色」的产品语义。网关本体失败（瞬时/回退耗尽）
+    仍上抛给端点（映射 503，同 refine 记账/凭据纪律）。**只读、不写库**（不变量 #3）。
+    """
+    req = build_clarify_request(spec, context=context, user_id=user_id, project_id=project_id)
+    resp = await gateway.run(req)
+    parsed = resp.parsed
+    if not isinstance(parsed, ClarifyDecision):
+        # 判别失败：确定性回退不问、放行（不阻塞润色主链路）。
+        log.warning(
+            "clarify_node_fallback_no_clarification",
+            spec=spec.name,
+            project_id=str(project_id) if project_id else None,
+            parsed_type=type(parsed).__name__,
+        )
+        return ClarifyDecision(need_clarification=False)
+    return parsed