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/agents/tests/fixtures/prompt_hashes.json

@@ -4,6 +4,7 @@
   "brainstorm": "f670dc77e3d9bd4a1df2b8cb29b51edb8b229d214148907d4b05519492364ada",
   "character-gen": "e0f97a5d7bb622fdd7582cdeef85ba13b3f434b2633f4d22a8c6daeba48636bf",
   "characterization": "643988cb899a66472acb3e18709f3299d2025f9bda132c774ee26c589266b51f",
+  "clarify_refine": "c2ed53c3a2d6c414c4ae5c92ead45634a56c47cd363a44f83ec1e020099480af",
   "continue": "f1ce02be3b186fc966c89cf0d54ea57a400e91d435ea91f5722cb17e43d11763",
   "continuity": "1bdf9799bad9076e54de2023433ec7da7b559509d986392a0563dc1ee20cf4a1",
   "de-ai": "9ce3020cdd4b223cc4d13c289babd2811bbfece4b392711dcba4fd0301c87249",

packages/agents/tests/test_clarify_spec.py

@@ -0,0 +1,125 @@
+"""WFW-9 M1 clarify_refine 契约测试：schema + spec 声明（路线A 两阶段之「问题」阶段）。
+
+契约测试——构造符合 schema 的 mock 响应，校验字段/默认值/tier/读写权限。
+ClarifyDecision：`{need_clarification, questions[≤1], verification?}`；
+analyst 档、reads=()、writes=()。全字段带默认值守解析韧性（LLM 漏产字段降级为
+need_clarification=false，不阻塞润色）。不联网、无 DB。
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+from ww_agents import (
+    AgentSpec,
+    ClarifyDecision,
+    ClarifyOption,
+    ClarifyQuestion,
+    clarify_refine_spec,
+)
+
+# ---- ClarifyDecision / ClarifyQuestion / ClarifyOption schema ----
+
+
+def test_clarify_decision_parses_need_clarification_with_one_question() -> None:
+    # Arrange：含糊 → 反问 1 问 + 3 个锚定选项 + 自由输入兜底
+    mock = {
+        "need_clarification": True,
+        "questions": [
+            {
+                "question": "你想让这段更有张力，是指哪种方向？",
+                "options": [
+                    {"label": "加快节奏", "value": "把长句拆短，压缩铺陈，加快推进"},
+                    {"label": "加重冲突", "value": "强化人物对立，增加正面交锋"},
+                    {"label": "收紧对白", "value": "删掉旁白，让张力靠对话推进"},
+                ],
+                "allow_free_text": True,
+            }
+        ],
+        "verification": None,
+    }
+
+    # Act
+    decision = ClarifyDecision.model_validate(mock)
+
+    # Assert
+    assert decision.need_clarification is True
+    assert len(decision.questions) == 1
+    q = decision.questions[0]
+    assert q.question.startswith("你想让这段")
+    assert len(q.options) == 3
+    assert q.options[0].label == "加快节奏"
+    assert q.options[0].value.startswith("把长句拆短")
+    assert q.allow_free_text is True
+    assert decision.verification is None
+
+
+def test_clarify_decision_parses_clear_with_verification() -> None:
+    # 明确 → 不问、给确认语
+    mock = {
+        "need_clarification": False,
+        "questions": [],
+        "verification": "我会把第二句的被字句改成主动句，其余不动，对吗？",
+    }
+    decision = ClarifyDecision.model_validate(mock)
+    assert decision.need_clarification is False
+    assert decision.questions == []
+    assert decision.verification is not None
+
+
+def test_clarify_decision_all_fields_default_for_resilience() -> None:
+    # 全字段默认值守解析韧性：空对象降级为 need_clarification=false（不问、放行）。
+    decision = ClarifyDecision.model_validate({})
+    assert decision.need_clarification is False
+    assert decision.questions == []
+    assert decision.verification is None
+
+
+def test_clarify_question_options_default_empty_and_free_text_true() -> None:
+    # 凑不出具体选项 → 空 options + 常驻自由输入兜底
+    q = ClarifyQuestion.model_validate({"question": "你具体想改哪里？"})
+    assert q.options == []
+    assert q.allow_free_text is True
+
+
+def test_clarify_option_requires_label_and_value() -> None:
+    with pytest.raises(ValidationError):
+        ClarifyOption.model_validate({"label": "加快节奏"})
+
+
+def test_clarify_question_requires_question_text() -> None:
+    with pytest.raises(ValidationError):
+        ClarifyQuestion.model_validate({"options": []})
+
+
+# ---- clarify_refine_spec 声明 ----
+
+
+def test_clarify_refine_spec_is_analyst_tier() -> None:
+    # 不变量 #2：含糊判别 + 反问构造用分析档，只声明 tier
+    assert clarify_refine_spec.tier == "analyst"
+    assert clarify_refine_spec.name == "clarify_refine"
+
+
+def test_clarify_refine_spec_is_read_only() -> None:
+    # 不变量 #3：只读——不读库真相源（材料端点注入）、不写任何表
+    assert clarify_refine_spec.reads == ()
+    assert clarify_refine_spec.writes == ()
+
+
+def test_clarify_refine_spec_output_schema() -> None:
+    assert clarify_refine_spec.output_schema is ClarifyDecision
+
+
+def test_clarify_refine_spec_prompt_documents_at_most_one_question() -> None:
+    # v1 硬上限 1 问 + 自由输入兜底须在教条里显式约束
+    prompt = clarify_refine_spec.system_prompt
+    assert "1 问" in prompt
+    assert "自由输入" in prompt
+    assert "防循环" in prompt
+
+
+def test_clarify_refine_spec_is_agent_spec_and_immutable() -> None:
+    assert isinstance(clarify_refine_spec, AgentSpec)
+    with pytest.raises(ValidationError):
+        clarify_refine_spec.tier = "writer"

packages/agents/tests/test_prompt_loader.py

@@ -52,8 +52,8 @@ def test_load_prompt_matches_golden(name: str) -> None:
 
 
 # ---- #1 注册表唯一性 ----
-def test_specs_registry_len_is_23() -> None:
-    assert len(SPECS) == 23
+def test_specs_registry_len_is_24() -> None:
+    assert len(SPECS) == 24
     # name 即 key，dict 已去重；逐项确认 key == spec.name（无错位）
     assert all(key == spec.name for key, spec in SPECS.items())
 

packages/agents/ww_agents/__init__.py

@@ -16,6 +16,9 @@ from .schemas import (
     CharacterizationIssue,
     CharacterizationReview,
     CharacterRelation,
+    ClarifyDecision,
+    ClarifyOption,
+    ClarifyQuestion,
     Conflict,
     ConflictType,
     ContinuationResult,
@@ -60,6 +63,7 @@ from .specs import (
     brainstorm_spec,
     character_gen_spec,
     characterization_spec,
+    clarify_refine_spec,
     continue_spec,
     continuity_spec,
     de_ai_spec,
@@ -93,6 +97,9 @@ __all__ = [
     "CharacterizationIssue",
     "CharacterizationReview",
     "CharacterRelation",
+    "ClarifyDecision",
+    "ClarifyOption",
+    "ClarifyQuestion",
     "Conflict",
     "ConflictType",
     "ContinuationResult",
@@ -133,6 +140,7 @@ __all__ = [
     "brainstorm_spec",
     "character_gen_spec",
     "characterization_spec",
+    "clarify_refine_spec",
     "continue_spec",
     "continuity_spec",
     "de_ai_spec",

packages/agents/ww_agents/prompts/clarify_refine.md

@@ -0,0 +1,50 @@
+你是长篇连载小说润色环节的「预检澄清器」（clarify-refine）——一位懂网文、会揣摩作者意图的资深责编。作者选中了正文里的一个段落想要「再沟通/润色」，但他给出的意见可能含糊、可能指向多种改法。你的唯一职责：在真正动笔改写**之前**，判断「这条意见清不清楚」，含糊就反问一个最关键的问题并给出几种具体走法供作者点选，清楚就确认理解、直接放行。
+
+你不是改写器（绝不输出改后的正文），不是审校（不输出问题清单/评分），不写库。你只做一件事：产出一个结构化的「澄清决策」。
+
+## 输入
+
+注入材料为序列化文本，可能包含：
+- **待润色的段落正文**（必有）；
+- **作者的再沟通意见/指令**（可选；如「改得更燃一点」「这里不对」「换个写法」，也可能为空）；
+- **周边上下文/文风线索**（可选）。
+
+## 判断：要不要反问
+
+先想清楚——作者这条意见，能不能让改写器**无歧义地**动笔？
+
+**判定为「明确」（need_clarification=false）** 当且仅当满足其一：
+- 意见具体、单一走法（如「把第二句的『被』字句改成主动句」「删掉这段景物描写」「口语化一点」）；
+- 意见虽简短但结合本段只有一种合理改法；
+- **历史里已经澄清过**（材料中已出现作者此前的选择/补充）——此时几乎永远不要再问，避免反复兜圈子。
+
+**判定为「含糊」（need_clarification=true）** 当且仅当：
+- 意见空缺或极短、无法定位要改什么（如「再改改」「不满意」）；
+- 存在多种明显不同的改法方向，选哪个会显著改变结果（如「更有张力」既可以是加快节奏、也可以是加重冲突、还可以是收紧对白）。
+
+拿不准时**倾向于放行**（need_clarification=false）——反问的成本是打断作者，只有真含糊才值得问。
+
+## 产出纪律（硬约束）
+
+### 明确时（need_clarification=false）
+- `questions` 留空列表；
+- `verification` 给**一句**「我这样理解对吗」式确认语，用你自己的话复述你打算怎么改（让作者一眼看出理解是否到位）。不要复述原文，不要输出改后正文。
+
+### 含糊时（need_clarification=true）
+- `questions` **恰好 1 问**（硬上限，绝不超过一个问题）；
+- `question`：一句话，直指本段的那个分歧点；
+- `options`：给 **2–4 个**锚定**本段/本章**的**具体、可区分**走法。每个选项：
+  - `label` 是作者看到的简短文案；
+  - `value` 是选中后要落实的具体走法描述（会被折进改写指令，供改写器执行）——写成可直接照做的一句话，别写空泛的形容词。
+  - 选项之间必须**互斥、方向不同**，覆盖作者最可能想要的几种真实意图；不要凑数、不要近义重复。
+- **凑不出**具体可区分的选项时（比如信息实在太少），把 `options` 留空列表，突出让作者自由输入——不要硬编三个含糊选项充数。
+- `allow_free_text` 一律为 `true`：无论有没有选项，自由输入永远兜底（作者可以都不选、自己写）。
+- `verification` 可留空（`null`）——含糊阶段还没到确认的时候。
+
+## 防循环
+
+如果注入材料里已经能看到作者此前的澄清选择或补充说明，说明这一轮沟通已经完成，**不要再问同样或类似的问题**——直接 `need_clarification=false`，用 `verification` 复述你综合后的理解，放行改写。反复反问是最糟的体验。
+
+## 产出格式（严格）
+
+只产出符合结构化 schema 的决策对象（`need_clarification` / `questions` / `verification`）。不要输出任何正文、解释、markdown 包裹或额外文字。选项要具体锚定本段，问题要短、要准、只问一个。

packages/agents/ww_agents/schema_catalog.py

@@ -18,6 +18,7 @@ from .schemas import (
     BookTeardownResult,
     CharacterGenResult,
     CharacterizationReview,
+    ClarifyDecision,
     ContinuationResult,
     ContinuityReview,
     DeAiResult,
@@ -63,6 +64,7 @@ SCHEMA_CATALOG: Final[dict[str, type[BaseModel] | None]] = {
     "de-ai": DeAiResult,
     "teardown": BookTeardownResult,
     "project-plan": ProjectPlanResult,
+    "clarify_refine": ClarifyDecision,
 }
 
 

packages/agents/ww_agents/schemas.py

@@ -674,3 +674,58 @@ class ProjectPlanResult(BaseModel):
     )
     ending_design: str = Field(default="", description="结局设计（收束方向与情绪落点）；缺则空串")
     tone: str = Field(default="", description="基调（全书情绪底色与阅读质感）；缺则空串")
+
+
+# ---- M1 refine · 预检澄清（clarify-refine；analyst；纯只读 writes=()）----
+
+
+class ClarifyOption(BaseModel):
+    """单个澄清选项：展示文案 + 选中回填值（锚定本段/本章的一种具体走法）。
+
+    `value` = 作者选中后折进 refine instruction 字符串的内容（零迁移，不落库）。
+    凑不出具体可区分选项时退化为空 options（`ClarifyQuestion.options=[]`），突出自由输入。
+    """
+
+    label: str = Field(description="展示文案（作者看到的选项标签）")
+    value: str = Field(description="选中后回填/折进 instruction 的具体走法内容")
+
+
+class ClarifyQuestion(BaseModel):
+    """单条澄清反问：问题 + 2–4 个锚定选项 + 自由输入兜底。
+
+    `options` 常规 2–4 个（锚定本段/本章的具体走法）；凑不出具体可区分选项时留空列表，
+    退化为纯自由输入。`allow_free_text` 常驻 True——自由输入永远兜底（作者可不选任一项）。
+    """
+
+    question: str = Field(description="反问的澄清问题（一句话，指向本段的分歧点）")
+    options: list[ClarifyOption] = Field(
+        default_factory=list,
+        description="2–4 个锚定本段/本章的具体走法选项；凑不出具体选项时为空列表",
+    )
+    allow_free_text: bool = Field(default=True, description="是否允许自由输入（常驻兜底）")
+
+
+class ClarifyDecision(BaseModel):
+    """润色预检澄清决策（结构化 LLM 输出 + API 响应）。
+
+    路线A 两阶段之「问题」阶段：仅判定「要不要反问」并给选项，**不改正文**（正文仍走
+    既有 refine 端点）。纯只读（`clarify_refine_spec.writes=()`，不变量 #3）。
+
+    **全字段给默认值守解析韧性**（仿 `StyleDriftReview` 降级范式）：LLM 漏产/畸形时
+    降级为 `need_clarification=false`（不问、直接放行 refine），绝不阻塞润色主链路。
+
+    - `need_clarification=false` → `questions` 为空、可给一句 `verification` 确认语；
+    - `need_clarification=true` → `questions` 恰 1 问（v1 硬上限）、`verification` 可空。
+    """
+
+    need_clarification: bool = Field(
+        default=False, description="是否需要向作者反问澄清（含糊/多走法→true；明确→false）"
+    )
+    questions: list[ClarifyQuestion] = Field(
+        default_factory=list,
+        description="反问清单（need_clarification=false 时为空；v1 硬上限 1 问）",
+    )
+    verification: str | None = Field(
+        default=None,
+        description="明确时的一句『我这样理解对吗』确认语（need_clarification=false 时给，可空）",
+    )

packages/agents/ww_agents/specs.py

@@ -31,6 +31,7 @@ __all__ = [
     "brainstorm_spec",
     "character_gen_spec",
     "characterization_spec",
+    "clarify_refine_spec",
     "continue_spec",
     "continuity_spec",
     "de_ai_spec",
@@ -326,6 +327,18 @@ project_plan_spec = AgentSpec(
     scope="builtin",
 )
 
+# ---- clarify_refine（润色预检澄清；分析档；纯只读 writes=()，WFW-9 M1 路线A 两阶段）----
+clarify_refine_spec = AgentSpec(
+    name="clarify_refine",
+    tier="analyst",  # 不变量 #2：只声明档位，不写 model（含糊判别 + 反问构造用分析档）
+    system_prompt=load_prompt("clarify_refine"),
+    input_schema=None,  # 注入材料为序列化文本（选段 + 再沟通指令），非结构化入参
+    output_schema=SCHEMA_CATALOG["clarify_refine"],
+    reads=(),  # 只判本段是否含糊；材料经端点序列化注入，不直读库
+    writes=(),  # 只读——只产问题/确认语，不改正文、不写库（不变量 #3）
+    scope="builtin",
+)
+
 
 # 集中注册表：name → spec（同一实例，兼容期 *_spec 与 SPECS[name] 为同对象，不变量）
 # MappingProxyType：只读视图，运行时 `SPECS[x] = ...` / `del SPECS[x]` 抛 TypeError
@@ -356,9 +369,10 @@ _SPECS_BY_NAME: dict[str, AgentSpec] = {
         de_ai_spec,
         teardown_spec,
         project_plan_spec,
+        clarify_refine_spec,
     )
 }
-assert len(_SPECS_BY_NAME) == 23, "SPECS name 冲突或缺失"  # 唯一性 + 数量自检（import 期）
+assert len(_SPECS_BY_NAME) == 24, "SPECS name 冲突或缺失"  # 唯一性 + 数量自检（import 期）
 SPECS: Final[Mapping[str, AgentSpec]] = MappingProxyType(_SPECS_BY_NAME)
 
 # 四审受信保留名 —— 独立显式白名单（安全边界锚在此，不依附派生集合）