yawan-workbench/docs/DSH内容生产执行器架构-20260915.md

DSH 内容生产执行器架构（2026-09-15）

1. 职责边界

工作台（FastAPI）保留管理职责：任务创建、导图录入、任务单确认、Agent/知识分类配置、启动/暂停/停止、人工审查、重试/跳过、成稿下载、运行事件与审计展示。

DSH（独立 Worker）负责执行核心内容生产流水线：导图拆解、全量生成、逐段生成、人工打回重做、失败修复重试、最终一致性总检与 docx 组合。

2. 后端开关

• 默认 YAWAN_EXECUTION_BACKEND=inline：保持原行为，由 API 后台线程执行。
• 设置 YAWAN_EXECUTION_BACKEND=dsh：API 只写入 CampaignRun/业务状态和 TaskQueueItem，不启动内容生产线程。

启动 DSH：

bash scripts/start_dsh.sh
# 或
cd server && YAWAN_EXECUTION_BACKEND=dsh python -m app.dsh_worker

当前版本要求 API 和 DSH 共享同一个 YAWAN_DATA_DIR（SQLite、data/kb、data/chroma、data/artifacts、模型缓存）。

3. 队列任务

DSH 只领取 campaign-% 前缀，避免领取 training-map:* 等其他后台任务：

• campaign-run:{run_id}：全量/逐段生成，payload 中用 mode=full|step 区分。
• campaign-segment-redo:{segment_id}：人工打回重做。
• campaign-segment-fix:{segment_id}：工作台先应用修复配置，DSH 再执行 pending 段。
• campaign-parse:{campaign_id}：导图拆解和任务单生成。
• campaign-compose:{campaign_id}：五项跨段一致性总检和六色 docx 成稿。

队列表具备租约、心跳、退避重试、死信和幂等键。DSH 心跳定期续租；崩溃后的过期租约会被重新领取，并把孤儿 running 内容段恢复成可执行状态。

4. 进度与状态

• DSH 的进度事件写入 ProgressEvent，同时保留内存事件通道。
• SSE /api/events/progress 和轮询接口统一通过 progress.snapshot() 读取内存 + SQLite 事件。
• 前端新增 composing 状态，成稿组合期间自动轮询，完成后展示最终文稿或一致性问题。

5. 运维注意

1. 生产环境先启动工作台，再启动至少一个 DSH Worker。
2. 不要让 inline API 和 DSH 同时执行同一套生产数据；同一环境应统一配置后端模式。
3. DSH 需要与 API 使用相同 Python 依赖、模型密钥、Provider 配置、知识库和数据目录。
4. 死信任务可在工作台运维页面重放；死信会同步补偿 Run/Campaign/Segment 状态并发送通知。
5. 未来跨机器部署时，需要把队列升级为 HTTP Job API，并共享或同步 artifacts/向量索引。