writer-work-flow/memory/contracts.md

# 契约登记（解耦缝）

> 跨 agent 的契约——多 agent 靠它解耦并行。**契约先行**：定义方先在此登记并标 `稳定`，依赖方才动工；改契约必须在此记一笔 + 在 `PROGRESS.md` 通知依赖任务（前端要重生成 TS 客户端、依赖模块要重同步）。
> 状态：`待定义` → `草拟(@skill)` → `稳定` → `已变更(见日志)`。

---

## C1 · LLM 网关接口　owner @llm　状态: 稳定（T1.1, 2026-06-18）
- 来源：`ARCHITECTURE.md §4.1`（`LlmRequest` / `LlmResponse` / `Block` / `Usage`，**snake_case**）。
- 消费方：编排器、所有 Agent（经 `Gateway.run` / `Gateway.stream`）。
- 关键不变量：agent 只传 `tier`（writer/analyst/light），不传具体 model。
- **已实现（`packages/llm_gateway/ww_llm_gateway`）**：
  - 类型 `types.py`：`Block(text,cache=False)`、`Scope(user_id,project_id?)`、`LlmRequest(tier,input:str|list[Block],system:list[Block],stream,output_schema?,thinking,max_tokens?,scope)`、`Usage(provider,model,input_tokens,output_tokens,cache_read_tokens,cost_minor,currency)`、`ServedBy(provider,model,fell_back)`、`LlmResponse(text,parsed?,usage,served_by)`、`Delta(text)`、`Tier`。
  - `Gateway(adapters:dict[str,ProviderAdapter], ledger:LedgerSink, resolver=resolve_route)`：`async run(req)->LlmResponse`、`stream(req)->AsyncIterator[Delta]`。每次调用落 **1 条** `usage_ledger`（经 `LedgerSink`，可注入内存替身）。
  - 适配器 `ProviderAdapter`(Protocol)：`provider`、`capabilities()->Capabilities`、`async complete(req,model)->ProviderResult`、`stream(req,model)->AsyncIterator[StreamChunk]`。M1 实现 `OpenAICompatAdapter(provider, client:AsyncOpenAI)`（DeepSeek，注入 client 便于测试）。
  - 档位路由 `resolve_route(tier)->Route(provider,model)` 读 `config.tier_defaults`（M1 仅全局默认；回退/熔断属 M5/T5.4，**未实现**）。
  - 记账 `SqlAlchemyLedgerSink(session)` 写 `UsageLedger`（owner_id=scope.user_id 单用户 stub；列名 `cache_read`）。成本表 `pricing.py`（未知 provider/model→0）。

## C2 · DB schema（SQLAlchemy 模型）　owner @db　状态: 待定义
- 来源：`ARCHITECTURE.md §3.1` DDL（11 创作表 + chapter_reviews + 运营表；无向量列；users stub）。
- 消费方：`@backend`(Repository/记忆服务/验收)、`@llm`(Agent reads/writes)。

## C3 · API / OpenAPI 端点　owner @backend　状态: 稳定（M1 端点全落：T1.7 settings + T1.4 projects/chapters, 2026-06-18）
- 来源：`ARCHITECTURE.md §7.2` 端点清单（章节端点统一 `/projects/:id/chapters/:no/...`；含 `PUT .../draft`(自动保存)、`/refine`、`/jobs/:id`、`/reviews`）。
- 消费方：`@frontend`（经 OpenAPI→TS 客户端）。**改端点/字段 → 前端必须 `pnpm gen:api` 重生成客户端。**
- **已落（T1.7, 2026-06-18，snake_case，响应仅脱敏 key）**：
  - `GET /settings/providers` → `ProvidersResponse{ providers:[ProviderView{provider, masked_key}], tier_routing:[TierRoutingView{tier, provider, model, fallback:list[str]}] }`
  - `PUT /settings/providers` ← `ProvidersUpsertRequest{ credentials:[ProviderCredentialInput{provider, api_key}], tier_routing:[TierRoutingInput{tier, provider, model, fallback}] }` → `ProvidersResponse`(脱敏)
  - `POST /settings/providers/test` ← `TestConnectionRequest{provider}` → `TestConnectionResponse{provider, ok, capabilities:CapabilitiesView{structured_output, prefix_cache, thinking}}`
  - **明文 key 永不过边界**；probe 经可注入 `ProviderProbe`（测试用 fake，不联网）。
- **已落（T1.4, 2026-06-18，snake_case）**：
  - `POST /projects` ← `ProjectCreateRequest{title, genre?, logline?, premise?, theme?, selling_points:list, structure?}` → 201 `ProjectResponse{id, title, genre?, logline?, premise?, theme?, selling_points, structure?}`
  - `GET /projects` → `ProjectListResponse{projects:[ProjectResponse]}`；`GET /projects/{id}` → `ProjectResponse`（404 `NOT_FOUND` 信封）
  - `POST /projects/{id}/chapters/{no}/draft` → **SSE** `text/event-stream`，帧 `event:<token|done|error>\ndata:<json>\n\n`（`token{text}`/`done{length}`/`error{code,message,request_id}`）；无凭据 → 流前 `LLM_UNAVAILABLE`(503) JSON 信封（非帧）。
  - `PUT /projects/{id}/chapters/{no}/draft` ← `DraftSaveRequest{text}` → 200 `DraftResponse{project_id, chapter_no, volume, status, version, length}`（幂等：version 固定 1、status='draft'）。
  - 网关注入缝 `get_writer_gateway`（从凭据构 `OpenAICompatAdapter`+`SqlAlchemyLedgerSink`）；测试经 `app.dependency_overrides` 注 mock 网关（只需 `.stream(req)`）。
- **@frontend 行动**：M1 端点已全在 OpenAPI → Wave D 前先 `cd apps/web && pnpm gen:api` 重生成 `lib/api/schema.d.ts`。
- **已落（T2.4+T2.5, 2026-06-18，snake_case，全部挂 `projects.router`、已在 OpenAPI）— M2 审/裁/验收三端点**：
  - `POST /projects/{id}/chapters/{no}/review` ← `ReviewRequest{draft?}`（空/缺→回退已存草稿；无草稿→404 `NOT_FOUND`）→ **SSE** `text/event-stream`，帧：`section{name,status:"done"|"incomplete"}`(每审一条，M2 仅 `continuity`) / `conflict{type,where,refs:list,suggestion}`(每冲突一条，形=C6 `Conflict` 五类) / `done{length=审项数}` / `error{code,message,request_id}`。无凭据→流前 `LLM_UNAVAILABLE`(503 JSON 信封)。续审网关 tier=analyst（`get_review_gateway`）。**端点流耗尽后 `session.commit()`**（网关 ledger + collect 均只 flush）。
  - `GET /projects/{id}/chapters/{no}/reviews` → `ReviewHistoryResponse{reviews:[ReviewHistoryItem{id,project_id,chapter_no,chapter_version?,conflicts:list,foreshadow_sug:list,style?,pace?,health_score?,decisions?}]}`（新→旧）。
  - `POST /projects/{id}/chapters/{no}/accept` ← `AcceptRequest{final_text(min1), decisions:[ConflictDecision{conflict_index:int>=0, verdict:"accept"|"ignore"|"manual", note?}]}` → `AcceptResponse{project_id,chapter_no,accepted_version:int,digest_added:bool,decisions_recorded:int,review_id?:uuid}`。**冲突 gate**：裁决的 `conflict_index` 集合须覆盖 `range(len(最近一条 review.conflicts))`，缺判→409 `CONFLICT_UNRESOLVED` + `details.missing_conflict_indices`/`conflict_count`；无留痕或零冲突→直通。digest 提炼 tier=light（`get_digest_gateway`）在事务外（R2），单事务 promote(R4)+digest.append(#4)+set_decisions 末尾一次 commit（R3）。
  - 注入缝：`build_gateway_for_tier(session, store, tier)`(原 `build_writer_gateway` 退化为 writer 特例) + `get_review_gateway`/`get_digest_gateway`/`get_review_repo`/`get_digest_append_repo`；测试经 `app.dependency_overrides` 注 mock。
  - **@frontend 行动**：`cd apps/web && pnpm gen:api` 重生成客户端含此三端点（T2.6）。

## C4 · 编排器接口（LangGraph 写章图）　owner @llm　状态: 稳定（M1/T1.3, 2026-06-18；M2 扩四审/验收）
- 来源：`ARCHITECTURE.md §5.2`（图）/ §7.3（SSE）。**M1 仅单 `write` 节点**；并行四审/collect/interrupt(accept) 属 M2。
- 位置：`packages/core/ww_core/orchestrator/`。
- 图状态 `ChapterState`(TypedDict, snake_case)：`{project_id:UUID, chapter_no:int, user_id:UUID, stable_core:str, volatile:str, draft:str}`——仅控制流+组装上下文+累积草稿（不变量#5）；resume 从领域表重读。
- 节点缝：
  - `build_write_request(*, stable_core, volatile, user_id, project_id) -> LlmRequest`（纯函数；`tier="writer"`，`system=[Block(stable_core,cache=True)]`，`input=volatile`，`stream=True`，`scope=Scope(user_id,project_id)`）。
  - `async stream_chapter_draft(gateway, *, stable_core, volatile, user_id, project_id) -> AsyncIterator[Delta]`——**T1.4 拿来喂 `normalize_deltas` 的底层流缝**。
  - `async write_node(state, *, gateway) -> {"draft":str}`——可直接单测（注入 mock 网关）。`GatewayStream` Protocol = 节点对网关最小依赖（只需 `.stream(req)`）。
- **SSE 归一缝（T1.4 消费）**：`async normalize_deltas(deltas, *, request_id=None) -> AsyncIterator[SseEvent]`；`SseEvent{event:str, data:dict}`；事件 `token{text}`/`done{length}`/`error{code,message,request_id}`（ARCH §7.3 子集，M2 加 section/conflict）。底层异常→发 `error` 事件后收尾（不上抛）；`AppError.code` 透传，未知→`INTERNAL`。HTTP event-stream 编码归 T1.4。
- 图工厂：`build_write_graph(gateway, *, checkpointer=None) -> CompiledStateGraph`（START→write→END）；单测传 `MemorySaver`。
- checkpointer setup 入口：`async setup_checkpointer(conn_string) -> None`——**只在 migrations/CI 调**（内部 `AsyncPostgresSaver.from_conn_string` 跑一次 `setup()` DDL；懒 import，绝不在 app-runtime 跑）。
- 不变量：agent 只传 tier；DB 唯一 agent 间通道；不可变更新；瞬时重试在网关不在节点。

### C4 扩展（T2.2, 2026-06-18）· 审稿子图 + review SSE
- 图工厂 `build_review_graph(gateway, review_repo, *, review_specs=(continuity_spec,), checkpointer=None) -> CompiledStateGraph`：`START →`各 review spec 并行节点`→ collect → END`。M2 默认仅 continuity，`review_specs` 可扩（M3/M4 加 foreshadow/style/pace）。**`build_write_graph` 保留不动**（draft 端点仍用它）。
- `ChapterState`(state.py) 新增 `review_context:str`、`reviews:Annotated[dict, merge_reviews]`（并行分支浅合并 reducer，返回新 dict）；TypedDict 改 `total=False`（按节点逐步填充）；仍仅控制流+组装上下文+产物句柄（不变量#5）。
- 节点缝：`run_review(spec, state, *, gateway)->{"reviews":{spec.name:{status,result}}}`（裸函数可单测）；`make_review_node(spec, gateway)`（绑 gateway 的公共缝，供 T2.5 跑单审）；审稿用 `gateway.run()`（非 stream），**只读不写库**（不变量#3）；任一审网关失败被隔离为 `{status:"incomplete",result:None}`（§5.2），不上抛、不毁图。`GatewayRun` Protocol=节点对网关最小依赖（`.run(req)->LlmResponse`）。
- collect 缝：`collect_reviews(state, *, review_repo)->{}`：抽 continuity 冲突 → `review_repo.record(project_id, chapter_no, chapter_version=None, conflicts=[...])` 落 `chapter_reviews` 留痕；**只 flush 不 commit**（提交归端点/T2.4 事务）。`ReviewRecorder` Protocol 形对齐 `domain.review_repo.ReviewRepo.record`。
- SSE 新增事件：`section{name,status}`（status ∈ started/done/incomplete）、`conflict{type,where,refs,suggestion}`（对齐 C6 `Conflict`）；新归一缝 `normalize_review(reviews, *, request_id=None)->AsyncIterator[SseEvent]`（每审一条 section + 每冲突一条 conflict + `done{length=审项数}`；异常→`error` 不上抛，同 `normalize_deltas` 纪律）。HTTP event-stream 编码归 T2.5。
- **accept 不在本图**：`interrupt_before=["accept"]`/accept 节点属 T2.4（确定性事务代码，从领域表重读，R3/不变量#5）。
- 消费方行动：T2.5 跑 review 子图 + `normalize_review` + 端点**流耗尽后 `await session.commit()`**（网关 ledger + collect 均只 flush，不提交则记账/留痕静默丢失，同 M1 draft 坑）；`GET .../reviews` 用 `review_repo.list_for_chapter`(新→旧)。T2.4 从 `review_repo.list_for_chapter` 读 collect 落的行（`decisions=None`）裁决。

## C5 · 记忆服务 `assemble` / `select_relevant_entities`　owner @backend　状态: 稳定（T1.2, 2026-06-18）
- 来源：`ARCHITECTURE.md §3.4 / §5.3`（确定性选择：显式+主角+近况；渲染卡片；缓存断点）。
- 位置：`packages/core/ww_core/memory/`（+ `domain/repositories.py`）。
- 输出（决策：中性文本，非 `LlmRequest`，见 decisions 2026-06-18）：
  - `AssembledContext{ stable_core:str, volatile:str, selection:SelectionTrace }`
    - `stable_core`：断点前（世界硬规则+定型主角(无 latest_state)+文风指纹+合并规则），已排序/无时间戳/无 UUID。
    - `volatile`：断点后（注入卡片(含 latest_state)+伏笔窗口+近况摘要+本章 beats）。
  - `SelectionTrace{ selected:list[SelectedEntity] }`；`SelectedEntity{ kind:"character"|"world_entity", name:str, reasons:list[SelectionReason] }`；`SelectionReason="explicit_beat"|"main_character"|"recent_digest"|"foreshadow_window"`。
- 入口：`async assemble(repos:MemoryRepos, project_id, chapter_no, recent_k=5)->AssembledContext`；纯函数 `select_relevant_entities(*, outline, characters, world_entities, recent_digests)->SelectionTrace`；`render_cards(selection, characters, world_entities)->str`；`merge_rules(rules)->list[RuleView]`（global→genre→style→project）。
- 依赖注入：`MemoryRepos` 捆绑 7 个 Protocol（Outline/Character/WorldEntity/Digest/Foreshadow/Style/Rules）；单测注入内存 fake，运行时 `sql_memory_repos(AsyncSession)`（**T1.4 注入点**）。
- 不变量：确定性选择(无向量 #6)；统一 project_id 过滤(§3.5)；latest_state 严格归 volatile(#9)。
- 消费方：**T1.3 write 节点** → 构造 `LlmRequest(system=[Block(stable_core, cache=True)], input=volatile)`。

## C6 · Agent 声明（AgentSpec）+ 续审 I/O schema　owner @llm　状态: 稳定（T2.1, 2026-06-18）
- 来源：`ARCHITECTURE.md §5.1 / §5.4 / §6.1`。位置：`packages/agents/ww_agents/`（`specs.py` / `schemas.py`，经 `ww_agents` 导出）。
- **`AgentSpec`**（frozen Pydantic，不可变）：`name:str`、`tier:Tier`(writer/analyst/light，复用 `ww_llm_gateway.types.Tier`——只声明档位不写 model，不变量#2)、`system_prompt:str`、`input_schema:type[BaseModel]|None`、`output_schema:type[BaseModel]|None`(writer 为 None=纯文本)、`reads:list[str]`、`writes:list[str]`、`genre:str|None=None`、`scope:str="builtin"`。
- **`continuity_spec`**：`tier="analyst"`、`reads=["chapter_digests","characters","world_entities"]`、`writes=[]`(只读，不变量#3)、`input_schema=None`(注入材料为序列化文本)、`output_schema=ContinuityReview`。
- **`ContinuityReview{ conflicts: list[Conflict] }`**（仅冲突；digest 不在审稿期产，不变量#4）。
- **`Conflict{ type: ConflictType, where:str, refs:list[str]=[], suggestion:str }`**；`ConflictType = Literal["性格漂移","能力不符","设定违例","地理矛盾","时间线倒错"]`（ARCH §6.1 五类）。
- 续审节点调法：`req = LlmRequest(tier="analyst", system=[Block(system_prompt, cache=True)], input=审稿上下文文本, output_schema=ContinuityReview, scope=...)` → `resp = await gateway.run(req)` → `resp.parsed` 为 `ContinuityReview` 实例（带 schema 时必非 None）。续审用 `run()` 非 `stream()`；只读+产冲突，不写库（写在 T2.4 验收事务）。
- 消费方：编排器(T2.2 续审/collect 节点)、技能运行时(M5)、前端审稿页(经 C3)。foreshadow/style/pace 三审 spec 待 M3/M4 补入本契约。

## C7 · 前端 ↔ 后端类型契约　owner @backend(产出 OpenAPI) / @frontend(生成)　状态: 待定义
- 机制：FastAPI OpenAPI → `apps/web/lib/api` TS 类型（openapi-typescript/orval）。
- 规则：后端 schema 任何变更 → 跑 `gen:api` 重生成；不手写共享类型。

---

## 契约变更日志（append-only）
> 格式：`- [date] @skill 改 Cx：<改了什么> → 影响 <依赖方/任务>`

- [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。