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）。
• 已落（T3.2, 2026-06-18，snake_case）— 伏笔登记/状态端点 + 验收后到期扫描（挂 foreshadow.router，prefix /projects，tag foreshadow，已注册）：
  • POST /projects/{id}/foreshadow ← ForeshadowRegisterRequest{code(min1),title(min1),planted_at?,content?,expected_close_from?,expected_close_to?,importance?} → 201 ForeshadowView{code,title,status,planted_at?,content?,expected_close_from?,expected_close_to?,importance?,links:list,progress:list}(status=OPEN)。重复 code(DB 唯一 (project_id,code))→ 422 VALIDATION+details{field:"code",code,reason:"duplicate"}。
  • PATCH /projects/{id}/foreshadow/{code} ← ForeshadowTransitionRequest{to_status?,progress_entry?} → 200 ForeshadowView。非法转移→422 VALIDATION+details{reason:"invalid_transition"}；二者都缺→422 empty_update；code 不存在→404 NOT_FOUND。先转移后追加进展，端点写后 commit()(repo 只 flush)。
  • 错误码取舍：重复/非法转移映射 VALIDATION(422) 非 409——现有唯一 409 码 CONFLICT_UNRESOLVED 语义专指未决冲突禁验收，不复用；未动 packages/shared/errors.py 契约。若 T3.5/前端需真 409 须先加专用码。
  • 验收后到期扫描：POST .../accept 单事务 commit 成功后经 BackgroundTasks 登记 run_overdue_scan(session_factory, project_id, chapter_no=刚验收章号)——自建独立 session(请求 session 已关闭)、应用 current_ch>expected_close_to AND status≠CLOSED→OVERDUE、有变更才 commit；日志 foreshadow_overdue_scan(带 request_id/overdue_count/codes)，失败吞不冒泡。§7.4 持久性局限(进程内/重启丢任务)原型接受、不引 jobs 表。
  • T3.5 续接：GET /projects/{id}/foreshadow?status= 看板加到本 foreshadow.router（注入 get_foreshadow_repo→list_by_status，建议响应包 {foreshadow:[...]}）；POST .../outline 落独立 routers/outline.py(别混进 foreshadow.py)，调 run_outline(C6 扩)+build_gateway_for_tier(...,"analyst")，逐章 upsert outline 表、端点末尾 commit。
  • @frontend 行动：T3.6 前 pnpm gen:api 纳入伏笔登记/状态端点（+ T3.5 看板/outline）。
• 已落（T3.5, 2026-06-18，snake_case）— 伏笔看板 + 大纲生成端点：
  • GET /projects/{id}/foreshadow?status=（tag foreshadow）：query status? ∈ OPEN|PARTIAL|CLOSED|OVERDUE(缺省=全部，非法→422 VALIDATION+details{field:"status",reason:"invalid_status"}) → 200 ForeshadowBoardResponse{foreshadow:list[ForeshadowView]}(按 code 升序)。
  • POST /projects/{id}/outline（tag outline，独立 routers/outline.py）← OutlineGenerateRequest{volume:int=1,ge=1}（M3 简单分卷：整批同卷）→ 200 OutlineResponse{chapters:list[OutlineChapterView{no,volume,beats:list[str],foreshadow_windows:list[ForeshadowWindowView{code,plant_chapter?,expected_close_from?,expected_close_to?}]}]}；项目不存在→404 NOT_FOUND；无凭据/网关失败→503 LLM_UNAVAILABLE(流前 JSON 信封)。调 run_outline(analyst 网关 get_outline_gateway)→逐章 upsert outline 表(写侧 SqlOutlineWriteRepo，只 flush)→端点末尾 commit()（含 1 条 usage_ledger）。
  • beats 存储形：DB outline.beats 是 JSONB dict→写侧包成 {"beats":[...]} 落库，API 出参 OutlineChapterView.beats 解包成裸 list[str]。
  • @frontend 行动：T3.6 pnpm gen:api 纳入看板/大纲端点。

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）裁决。

C4 扩展（T3.3, 2026-06-18）· 三审齐（foreshadow + pace 并入）

• REVIEW_SPECS = (continuity_spec, foreshadow_spec, pace_spec)；build_review_graph(..., review_specs=REVIEW_SPECS) 默认三审齐（文风第四审留 M4）。run_review/make_review_node 对 spec 泛型（按 req.output_schema 产 parsed）。
• collect 列映射（一次 review_repo.record(...) 落齐）：continuity→conflicts(list)；foreshadow→foreshadow_sug(list，把 planted/resolved 扁平成单 list、每条加 kind:"planted"|"resolved")；pace→pace(dict，整 {water,hook,beat_map} 入列)；style 留 M4。任一审 incomplete→该列空/None，不阻塞其余（§5.2）。
• normalize_review SSE（向后兼容，section/conflict 不变）新增：foreshadow{kind,code?,title,where?,note?}（每条建议一条）、pace{water:[{where,reason}],hook:bool,beat_map:[int]}（一条）。键按字典序确定性遍历（continuity<foreshadow<pace）。incomplete 审仅发 section 不发结果。
• 消费方：前端 T3.6（冲突就地标注 / 伏笔看板联动 / 节拍图 ▁▃▅）、E2E T3.7。

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-T3.3/M4 补入本契约。

C6 扩展（T3.4, 2026-06-18）· outliner Agent + 大纲/伏笔窗口 schema

• 位置：packages/agents/ww_agents/{schemas.py,specs.py}（经 ww_agents 导出）；节点在 packages/core/ww_core/orchestrator/outline_node.py（经 orchestrator 导出）。
• outliner_spec(frozen AgentSpec)：name="outliner"、tier="analyst"、reads=["projects","foreshadow","characters","world_entities"]、writes=["outline"](声明式，真写库经 T3.5，不变量#3)、input_schema=None、output_schema=OutlineResult。
• OutlineResult{chapters:list[OutlineChapter]}；OutlineChapter{no:int, beats:list[str], foreshadow_windows:list[ForeshadowWindow]}；ForeshadowWindow{code:str, plant_chapter?:int, expected_close_from?:int, expected_close_to?:int}（§6.2 关联章与伏笔）。
• 节点缝（沿用 review_node 的 GatewayRun Protocol .run(req)->LlmResponse）：build_outline_request(spec, *, context, user_id, project_id)->LlmRequest(output_schema=OutlineResult,stream=False) + async run_outline(spec, *, context, gateway, user_id, project_id)->OutlineResult(gateway.run().parsed；只读不写库；大纲独立生成、非并行审，网关失败直接上抛不隔离，parsed 违约抛 ValueError)。
• 消费方：T3.5 端点调 run_outline 拿 OutlineResult → 逐章 upsert outline 表（beats/foreshadow_windows 入 JSONB，volume 由端点分卷逻辑提供，schema 不含 volume）；analyst 网关复用 build_gateway_for_tier(session,store,"analyst")/get_review_gateway；记账闭环同 M2（端点末尾 commit()）。T3.6 前端大纲编辑器消费窗口。

C6 扩展（T3.3, 2026-06-18）· foreshadow-analyst + pace-checker spec

• foreshadow_spec(name="foreshadow", tier="analyst", reads=["foreshadow"], writes=[]只读, output=ForeshadowReview{planted:[ForeshadowSuggestion],resolved:[ForeshadowSuggestion]}；ForeshadowSuggestion{code?,title,where?,note?})。
• pace_spec(name="pace", tier="light", reads=["rules"], writes=[]只读, output=PaceReview{water:[PaceIssue{where,reason}],hook:bool,beat_map:[int]})。genre 模板 DSL = pace system_prompt 内描述黄金三章/章末钩子/爽点密度，genre 级模板经 review_context 规则合并(rules)注入，未新建表/repo。
• 三审只读，留痕经 collect→review_repo（写库 commit 归端点）。详细图/SSE 见上「C4 扩展（T3.3）」。

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。