feat: M2 — 写→审(一致性)→裁决→验收(事务)；未决冲突禁验收

- 续审 Agent 声明(AgentSpec) + 结构化输出契约(ContinuityReview/Conflict 五类)
- LangGraph 并行审子图(可扩四审) + collect 落 chapter_reviews 留痕 + review SSE(section/conflict)
- 验收-side Repository：章节 accepted 版本晋升 + digest append-only + 审稿留痕/裁决
- API：review(SSE) + reviews 历史 + accept(单原子事务：晋升 version + 终稿 digest + 裁决留痕)
- 冲突 gate：未决裁决拦截(CONFLICT_UNRESOLVED)；digest 从终稿提炼(不变量#4)
- 前端：审稿报告页 + 冲突就地标注 + 裁决(采纳/忽略/手改) + 未决禁验收 + 「本次将更新」清单
- M2 E2E：真实 DB + 多档位 mock 网关零 token 走通 写→审→裁决→验收→摘要入库
- 多 agent 协同台账(PROGRESS.md) + 共享记忆(memory/contracts·decisions·gotchas)

packages/agents/README.md

@@ -0,0 +1,2 @@
+# core (@llm/@backend) — 占位骨架
+领域核心(domain/状态机)、编排器(orchestrator/LangGraph 图)、记忆服务(memory)。Phase 1+ 由对应 owner 填充。

packages/agents/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "ww-agents"
+version = "0.0.0"
+requires-python = ">=3.12"
+dependencies = [
+  "pydantic>=2.7",
+  "ww-shared",
+  "ww-llm-gateway",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ww_agents"]
+
+[tool.uv.sources]
+ww-shared = { workspace = true }
+ww-llm-gateway = { workspace = true }

packages/agents/tests/test_specs.py

@@ -0,0 +1,95 @@
+"""T2.1 续审契约测试：ContinuityReview schema + continuity_spec 声明（C6）。
+
+契约测试——构造符合 schema 的 mock 响应，校验 type 枚举约束、conflicts 列表、
+四审只读（writes==[]）。不联网、无 DB。
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+from ww_agents import AgentSpec, Conflict, ContinuityReview, continuity_spec
+
+
+def test_continuity_review_parses_mock_response() -> None:
+    # Arrange：模拟网关 instructor 校验后的结构化产出
+    mock = {
+        "conflicts": [
+            {
+                "type": "性格漂移",
+                "where": "第 3 段，主角忽然示弱",
+                "refs": ["第 1 章人物卡：性格刚烈"],
+                "suggestion": "改为强硬回应，或补内心转折铺垫",
+            },
+            {
+                "type": "时间线倒错",
+                "where": "开篇提到三日后",
+                "refs": ["第 5 章 digest：事件发生在次日"],
+                "suggestion": "统一为次日",
+            },
+        ]
+    }
+
+    # Act
+    review = ContinuityReview.model_validate(mock)
+
+    # Assert
+    assert len(review.conflicts) == 2
+    assert review.conflicts[0].type == "性格漂移"
+    assert review.conflicts[1].refs == ["第 5 章 digest：事件发生在次日"]
+
+
+def test_continuity_review_allows_empty_conflicts() -> None:
+    review = ContinuityReview.model_validate({"conflicts": []})
+    assert review.conflicts == []
+
+
+def test_continuity_review_defaults_to_empty_conflicts() -> None:
+    review = ContinuityReview()
+    assert review.conflicts == []
+
+
+def test_conflict_type_rejects_unknown_value() -> None:
+    with pytest.raises(ValidationError):
+        Conflict.model_validate({"type": "排版错误", "where": "x", "refs": [], "suggestion": "y"})
+
+
+def test_conflict_refs_default_empty() -> None:
+    conflict = Conflict.model_validate(
+        {"type": "设定违例", "where": "战斗场景", "suggestion": "删去违例能力"}
+    )
+    assert conflict.refs == []
+
+
+def test_continuity_spec_is_analyst_tier() -> None:
+    assert continuity_spec.tier == "analyst"
+    assert continuity_spec.name == "continuity"
+
+
+def test_continuity_spec_is_read_only() -> None:
+    # 不变量 #3：四审只读
+    assert continuity_spec.writes == []
+
+
+def test_continuity_spec_declares_expected_reads() -> None:
+    assert continuity_spec.reads == ["chapter_digests", "characters", "world_entities"]
+
+
+def test_continuity_spec_output_schema_is_continuity_review() -> None:
+    assert continuity_spec.output_schema is ContinuityReview
+
+
+def test_continuity_spec_has_nonempty_system_prompt() -> None:
+    assert continuity_spec.system_prompt.strip()
+
+
+def test_agent_spec_is_immutable() -> None:
+    # frozen：加载后不得改动
+    with pytest.raises(ValidationError):
+        continuity_spec.tier = "writer"
+
+
+def test_agent_spec_writer_allows_none_output_schema() -> None:
+    writer = AgentSpec(name="writer", tier="writer", system_prompt="写")
+    assert writer.output_schema is None
+    assert writer.scope == "builtin"

packages/agents/ww_agents/__init__.py

@@ -0,0 +1,17 @@
+"""ww-agents：内置 Agent 声明（AgentSpec）+ 结构化输出 schema（C6）。
+
+对齐 ARCH §5.1（AgentSpec）/ §5.4（I/O 契约）/ §6.1（冲突分类）。
+"""
+
+from __future__ import annotations
+
+from .schemas import Conflict, ConflictType, ContinuityReview
+from .specs import AgentSpec, continuity_spec
+
+__all__ = [
+    "AgentSpec",
+    "Conflict",
+    "ConflictType",
+    "ContinuityReview",
+    "continuity_spec",
+]

packages/agents/ww_agents/schemas.py

@@ -0,0 +1,46 @@
+"""续审 Agent 的结构化输出 schema（ARCH §5.4 continuity 行 / §6.1 冲突分类）。
+
+snake_case，Pydantic v2。网关经 instructor 保证产出符合这些 schema（C1/§4.4）。
+
+不变量 #3：四审只读——审稿期只产**冲突清单**，不产 digest（digest 在验收时
+从终稿另提，见不变量 #4 / ARCH §5.5）。
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+# ARCH §6.1 五类冲突；受限枚举，便于前端就地裁决分类与统计。
+ConflictType = Literal[
+    "性格漂移",
+    "能力不符",
+    "设定违例",
+    "地理矛盾",
+    "时间线倒错",
+]
+
+
+class Conflict(BaseModel):
+    """单条一致性冲突（ARCH §6.1）。"""
+
+    type: ConflictType = Field(description="冲突分类（五类之一）")
+    where: str = Field(description="本章定位：哪一段/哪句触发冲突")
+    refs: list[str] = Field(
+        default_factory=list,
+        description="冲突来源引用：相关章节号、设定项或人物卡条目",
+    )
+    suggestion: str = Field(description="改法建议")
+
+
+class ContinuityReview(BaseModel):
+    """续审结构化产出：仅冲突清单（无 digest）。
+
+    digest 不在审稿期产——那是验收时从**终稿**另提（不变量 #4）。
+    """
+
+    conflicts: list[Conflict] = Field(
+        default_factory=list,
+        description="检出的一致性冲突；无冲突时为空列表",
+    )

packages/agents/ww_agents/specs.py

@@ -0,0 +1,65 @@
+"""Agent 声明式抽象（ARCH §5.1）+ 续审 Agent 实例。
+
+`AgentSpec` 是内置 Agent 与用户 Skill 的同构声明：一份只读声明，由编排器加载、
+经网关按 `tier` 执行。不变量 #2：agent 只声明 `tier`，**不**写具体 model。
+不变量 #3：四审 `writes=[]`（只读），任何 AI 产出入库必经验收事务。
+
+不可变：`AgentSpec` 为 frozen Pydantic 模型——加载后不得改动。
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+from ww_llm_gateway.types import Tier
+
+from .schemas import ContinuityReview
+
+
+class AgentSpec(BaseModel):
+    """单一 Agent / Skill 的声明（ARCH §5.1）。"""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    name: str
+    tier: Tier  # 能力档位（网关解析 provider+model）；不含具体 model
+    system_prompt: str
+    # 入/出参契约（Pydantic 模型类型）；writer 纯文本 → output_schema 可为 None
+    input_schema: type[BaseModel] | None = None
+    output_schema: type[BaseModel] | None = None
+    reads: list[str] = Field(default_factory=list)  # 声明式表读权限
+    writes: list[str] = Field(default_factory=list)  # 声明式表写权限（经验收才生效）
+    genre: str | None = None  # 题材适用（Skill 用）
+    scope: str = "builtin"  # builtin / custom / community
+
+
+CONTINUITY_SYSTEM_PROMPT = """你是长篇连载小说的「一致性续审」。你的唯一职责：把本章草稿与\
+作品的既有真相源逐项比对，找出一致性冲突，产出结构化冲突清单。
+
+比对依据（注入材料）：
+- 近况摘要（最近若干章的 chapter_digests）；
+- 相关人物卡（性格、能力、关系、最新状态 latest_state）；
+- 世界观硬规则（world_entities 的不可违背设定）。
+
+按以下五类判定冲突，每条给出本章定位、来源引用与改法建议：
+- 性格漂移：人物言行与其设定/既往表现不符；
+- 能力不符：超出或低于已建立的能力/力量体系边界；
+- 设定违例：违反世界观硬规则；
+- 地理矛盾：地点/距离/空间关系与既有设定冲突；
+- 时间线倒错：事件先后、时序与既有章节矛盾。
+
+纪律：
+- 你**只读、只报冲突**，不改稿、不写库、不产章节摘要（摘要在验收时从终稿另提）。
+- 只报有据可依的真冲突；无冲突则返回空列表，不要臆造。
+- 引用要具体（章节号、设定项、人物卡条目），便于作者就地裁决。"""
+
+
+continuity_spec = AgentSpec(
+    name="continuity",
+    tier="analyst",
+    system_prompt=CONTINUITY_SYSTEM_PROMPT,
+    input_schema=None,  # 注入材料为序列化文本（经记忆 assemble），非结构化入参
+    output_schema=ContinuityReview,
+    reads=["chapter_digests", "characters", "world_entities"],
+    writes=[],  # 只读（不变量 #3）
+    scope="builtin",
+)