1652ad9d20
润色「再沟通」意见含糊时先反问给选项（路线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 无漂移。
300 lines
12 KiB
Python
300 lines
12 KiB
Python
"""文风端点：学文风（异步长任务）+ 回炉 + 最新指纹读取
|
||
（C3 扩 / ARCH §5.4 style-auditor 提取轨 / §7.2 / §7.4 jobs / UX §6.9 / §8.3）。
|
||
|
||
独立 router（仿 outline.py），挂 `app.include_router`。三端点：
|
||
|
||
- `POST /projects/{id}/style` → 202 `{job_id}`：学文风走 jobs（M4-c）。立即写一行 job
|
||
返 202，提取经 BackgroundTask `run_job` 跑（**自建独立 session**，请求 session 已关闭）。
|
||
无凭据 → 流前 `LLM_UNAVAILABLE`（503，在调度 job 之前拦下，避免凭空写注定失败的 job）。
|
||
- `POST /projects/{id}/chapters/{no}/refine` → 200 `{original, refined}`：同步回炉，writer
|
||
网关纯文本重写选中段；不写库（不变量 #3，作者采纳经既有 draft 自动保存合入）；末尾
|
||
`commit()` 让 usage_ledger 落库（网关 ledger add-only，同 draft/review 纪律）。
|
||
- `GET /projects/{id}/style` → 200 最新指纹（完整 16 维 + 证据 + 版本，UX §6.9）。
|
||
|
||
不变量 #2：经 `get_*_gateway`（analyst/writer 档）注入，spec 只声明档位不传 model。
|
||
不变量 #3：提取/回炉 agent 只读不写其它表；文风指纹落库经此作者发起的学文风路径。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import uuid
|
||
from typing import Annotated, Any
|
||
|
||
from fastapi import APIRouter, BackgroundTasks, Depends, Request, Response
|
||
from sqlalchemy.ext.asyncio import AsyncSession
|
||
from ww_agents import ClarifyDecision, clarify_refine_spec, refiner_spec, style_extract_spec
|
||
from ww_core.domain import JobRepo, ProjectRepo, StyleFingerprintWriteRepo
|
||
from ww_core.domain.style_repo import SqlStyleFingerprintWriteRepo
|
||
from ww_core.orchestrator import run_clarify, run_style_extraction
|
||
from ww_db import get_session
|
||
from ww_llm_gateway import Gateway
|
||
from ww_llm_gateway.types import Block, LlmRequest, Scope
|
||
from ww_shared import AppError, ErrorCode, ErrorEnvelope
|
||
|
||
from ww_api.logging_config import get_logger
|
||
from ww_api.schemas.style import (
|
||
DimensionEntry,
|
||
RefineClarifyRequest,
|
||
RefineRequest,
|
||
RefineResponse,
|
||
StyleFingerprintResponse,
|
||
StyleLearnRequest,
|
||
StyleLearnResponse,
|
||
)
|
||
from ww_api.services.credentials import STUB_OWNER_ID, SqlCredentialStore
|
||
from ww_api.services.foreshadow_scan import SessionFactory
|
||
from ww_api.services.job_runner import run_job
|
||
from ww_api.services.project_deps import (
|
||
build_gateway_for_tier,
|
||
get_clarify_gateway,
|
||
get_job_repo,
|
||
get_project_repo,
|
||
get_refine_gateway,
|
||
get_session_factory,
|
||
get_style_extract_gateway,
|
||
get_style_write_repo,
|
||
)
|
||
|
||
log = get_logger("ww.api.style")
|
||
|
||
router = APIRouter(prefix="/projects", tags=["style"])
|
||
|
||
ProjectRepoDep = Annotated[ProjectRepo, Depends(get_project_repo)]
|
||
JobRepoDep = Annotated[JobRepo, Depends(get_job_repo)]
|
||
StyleWriteRepoDep = Annotated[StyleFingerprintWriteRepo, Depends(get_style_write_repo)]
|
||
StyleExtractGatewayDep = Annotated[Gateway, Depends(get_style_extract_gateway)]
|
||
RefineGatewayDep = Annotated[Gateway, Depends(get_refine_gateway)]
|
||
ClarifyGatewayDep = Annotated[Gateway, Depends(get_clarify_gateway)]
|
||
SessionDep = Annotated[AsyncSession, Depends(get_session)]
|
||
SessionFactoryDep = Annotated[SessionFactory, Depends(get_session_factory)]
|
||
|
||
_JOB_KIND_STYLE_LEARN = "style_learn"
|
||
|
||
|
||
def _split_fingerprint(result: Any) -> tuple[dict[str, str], dict[str, list[str]]]:
|
||
"""把 `StyleFingerprintResult` 拆成 DB 两列：`{name:value}` + `{name:[evidence]}`。"""
|
||
dimensions = {dim.name: dim.value for dim in result.dimensions}
|
||
evidence = {dim.name: list(dim.evidence) for dim in result.dimensions}
|
||
return dimensions, evidence
|
||
|
||
|
||
def _make_style_learn_work(project_id: uuid.UUID, samples_text: str) -> Any:
|
||
"""构造学文风后台工作闭包：在 `run_job` 自建的独立 session 上跑提取 + 落库。
|
||
|
||
`work(session)` 自建 analyst 网关（从凭据）+ 写侧 repo（用 `run_job` 传入的独立
|
||
session）→ `run_style_extraction` → 拆指纹 → `append`（版本化）→ 返回 result 摘要
|
||
`{version, dims_count}`。提交归 `run_job`（业务写 + job done 同一事务一次 commit）。
|
||
"""
|
||
|
||
async def work(session: AsyncSession) -> dict[str, Any]:
|
||
store = SqlCredentialStore(session)
|
||
gateway = await build_gateway_for_tier(session, store, "analyst")
|
||
result = await run_style_extraction(
|
||
style_extract_spec,
|
||
samples_text=samples_text,
|
||
gateway=gateway,
|
||
user_id=STUB_OWNER_ID,
|
||
project_id=project_id,
|
||
)
|
||
dimensions, evidence = _split_fingerprint(result)
|
||
repo = SqlStyleFingerprintWriteRepo(session)
|
||
version = await repo.append(project_id, dimensions_json=dimensions, evidence_json=evidence)
|
||
return {"version": version, "dims_count": len(dimensions)}
|
||
|
||
return work
|
||
|
||
|
||
@router.post("/{project_id}/style", status_code=202)
|
||
async def learn_style(
|
||
project_id: uuid.UUID,
|
||
body: StyleLearnRequest,
|
||
request: Request,
|
||
response: Response,
|
||
background_tasks: BackgroundTasks,
|
||
project_repo: ProjectRepoDep,
|
||
job_repo: JobRepoDep,
|
||
gateway: StyleExtractGatewayDep, # 凭据探测（无凭据 → dep 解析阶段 503）
|
||
session: SessionDep,
|
||
session_factory: SessionFactoryDep,
|
||
) -> StyleLearnResponse:
|
||
"""学文风：写一行 job 返 202，提取经 BackgroundTask 异步跑。
|
||
|
||
项目不存在 → 404；无凭据 → 503（在调度 job 前拦下）。`mode` 不影响落库逻辑
|
||
（写侧始终 append 新版本，version+1 自动），仅供前端区分首学/更新语义。
|
||
"""
|
||
request_id = getattr(request.state, "request_id", None)
|
||
|
||
project = await project_repo.get(STUB_OWNER_ID, project_id)
|
||
if project is None:
|
||
raise AppError(ErrorCode.NOT_FOUND, f"project not found: {project_id}")
|
||
|
||
# `gateway` 已在 dep 解析阶段验过凭据（无凭据 → 503）；提取本体在 BackgroundTask
|
||
# 里用独立 session 重新构网关跑，此处不复用它（请求 session 即将关闭）。
|
||
samples_text = "\n\n".join(body.samples)
|
||
|
||
job = await job_repo.create(project_id, _JOB_KIND_STYLE_LEARN)
|
||
await session.commit() # job 行需在 202 返回前持久化（供前端立即轮询）。
|
||
|
||
background_tasks.add_task(
|
||
run_job,
|
||
session_factory,
|
||
job.id,
|
||
_make_style_learn_work(project_id, samples_text),
|
||
request_id=request_id,
|
||
)
|
||
|
||
log.info(
|
||
"style_learn_scheduled",
|
||
project_id=str(project_id),
|
||
request_id=request_id,
|
||
job_id=str(job.id),
|
||
sample_count=len(body.samples),
|
||
mode=body.mode,
|
||
)
|
||
response.status_code = 202
|
||
return StyleLearnResponse(job_id=job.id)
|
||
|
||
|
||
def _merge_dimensions(dimensions: dict[str, Any], evidence: dict[str, Any]) -> list[DimensionEntry]:
|
||
"""把 DB 两列并行 dict 合并为 `list[DimensionEntry]`（按维度名稳定排序，便于前端展示）。"""
|
||
return [
|
||
DimensionEntry(
|
||
name=name,
|
||
value=str(dimensions[name]),
|
||
evidence=[str(e) for e in (evidence.get(name) or [])],
|
||
)
|
||
for name in sorted(dimensions)
|
||
]
|
||
|
||
|
||
@router.get(
|
||
"/{project_id}/style",
|
||
responses={404: {"model": ErrorEnvelope, "description": "项目或指纹不存在"}},
|
||
)
|
||
async def get_style(
|
||
project_id: uuid.UUID,
|
||
project_repo: ProjectRepoDep,
|
||
style_repo: StyleWriteRepoDep,
|
||
) -> StyleFingerprintResponse:
|
||
"""取最新文风指纹（完整 16 维 + 证据 + 版本）。项目不存在 → 404；无指纹 → 404。"""
|
||
project = await project_repo.get(STUB_OWNER_ID, project_id)
|
||
if project is None:
|
||
raise AppError(ErrorCode.NOT_FOUND, f"project not found: {project_id}")
|
||
|
||
latest = await style_repo.latest(project_id)
|
||
if latest is None:
|
||
raise AppError(ErrorCode.NOT_FOUND, f"no style fingerprint for project: {project_id}")
|
||
return StyleFingerprintResponse(
|
||
dimensions=_merge_dimensions(latest.dimensions, latest.evidence),
|
||
version=latest.version,
|
||
)
|
||
|
||
|
||
def _build_refine_input(segment: str, instruction: str | None) -> str:
|
||
"""组回炉输入：待重写段 + 可选指令（保留上下文语气，只重写该段）。"""
|
||
parts = [f"【待重写段落】\n{segment}"]
|
||
if instruction:
|
||
parts.append(f"【改写指令】\n{instruction}")
|
||
return "\n\n".join(parts)
|
||
|
||
|
||
@router.post("/{project_id}/chapters/{chapter_no}/refine")
|
||
async def refine_segment(
|
||
project_id: uuid.UUID,
|
||
chapter_no: int,
|
||
body: RefineRequest,
|
||
request: Request,
|
||
project_repo: ProjectRepoDep,
|
||
gateway: RefineGatewayDep,
|
||
session: SessionDep,
|
||
) -> RefineResponse:
|
||
"""同步回炉：writer 网关纯文本重写选中段，返回 {original, refined}。
|
||
|
||
项目不存在 → 404；无凭据 → 503。不写库（不变量 #3）；末尾 `commit()` 让网关
|
||
usage_ledger 落库（add-only，否则记账静默丢失，同 draft/review 纪律）。
|
||
"""
|
||
request_id = getattr(request.state, "request_id", None)
|
||
|
||
project = await project_repo.get(STUB_OWNER_ID, project_id)
|
||
if project is None:
|
||
raise AppError(ErrorCode.NOT_FOUND, f"project not found: {project_id}")
|
||
|
||
req = LlmRequest(
|
||
tier=refiner_spec.tier, # 不变量 #2：writer 档，不传 model
|
||
system=[Block(text=refiner_spec.system_prompt, cache=True)],
|
||
input=_build_refine_input(body.segment, body.instruction),
|
||
output_schema=None, # refiner 纯文本（无结构化 schema）
|
||
scope=Scope(user_id=STUB_OWNER_ID, project_id=project_id),
|
||
)
|
||
resp = await gateway.run(req)
|
||
|
||
# 提交边界：网关 ledger add-only → 端点末尾 commit（否则记账静默丢失，见 gotcha）。
|
||
await session.commit()
|
||
|
||
log.info(
|
||
"refine_done",
|
||
project_id=str(project_id),
|
||
chapter_no=chapter_no,
|
||
request_id=request_id,
|
||
segment_len=len(body.segment),
|
||
refined_len=len(resp.text),
|
||
has_instruction=body.instruction is not None,
|
||
)
|
||
return RefineResponse(original=body.segment, refined=resp.text)
|
||
|
||
|
||
@router.post(
|
||
"/{project_id}/chapters/{chapter_no}/refine/clarify",
|
||
responses={
|
||
404: {"model": ErrorEnvelope, "description": "项目不存在"},
|
||
503: {"model": ErrorEnvelope, "description": "LLM 不可用"},
|
||
},
|
||
)
|
||
async def clarify_refine(
|
||
project_id: uuid.UUID,
|
||
chapter_no: int,
|
||
body: RefineClarifyRequest,
|
||
request: Request,
|
||
project_repo: ProjectRepoDep,
|
||
gateway: ClarifyGatewayDep,
|
||
session: SessionDep,
|
||
) -> ClarifyDecision:
|
||
"""润色预检澄清（WFW-9 M1 路线A 两阶段之「问题」阶段）：非流式 JSON，只判不改。
|
||
|
||
独立于既有 refine 端点——只判「作者这条再沟通意见清不清楚」，含糊则反问 1 问 + 给选项，
|
||
清楚则给确认语放行；**绝不改正文**（正文仍走 refine 端点）。analyst 档（不变量 #2）。
|
||
|
||
项目不存在 → 404；无凭据 → 503（dep 解析阶段拦下）。**只读不写库**（不变量 #3）；
|
||
末尾 `commit()` 让网关 usage_ledger 落库（add-only，否则记账静默丢失，同 refine 纪律）。
|
||
判别/校验失败在 `run_clarify` 内确定性回退 `need_clarification=false`（不阻塞润色）。
|
||
"""
|
||
request_id = getattr(request.state, "request_id", None)
|
||
|
||
project = await project_repo.get(STUB_OWNER_ID, project_id)
|
||
if project is None:
|
||
raise AppError(ErrorCode.NOT_FOUND, f"project not found: {project_id}")
|
||
|
||
context = _build_refine_input(body.segment, body.instruction or None)
|
||
decision = await run_clarify(
|
||
clarify_refine_spec, # 不变量 #2：analyst 档，不传 model
|
||
context=context,
|
||
gateway=gateway,
|
||
user_id=STUB_OWNER_ID,
|
||
project_id=project_id,
|
||
)
|
||
|
||
# 提交边界：只读不写业务表，但网关 ledger add-only → 端点末尾 commit（否则记账丢失）。
|
||
await session.commit()
|
||
|
||
log.info(
|
||
"refine_clarify_done",
|
||
project_id=str(project_id),
|
||
chapter_no=chapter_no,
|
||
request_id=request_id,
|
||
segment_len=len(body.segment),
|
||
instruction_len=len(body.instruction),
|
||
need_clarification=decision.need_clarification,
|
||
question_count=len(decision.questions),
|
||
)
|
||
return decision
|