# 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
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/向量索引。