646 lines
9.9 KiB
Markdown
646 lines
9.9 KiB
Markdown
# AI 写作后端新路线设计草案
|
|
|
|
## 1. 目标
|
|
|
|
为“弱模型多 Agent 写作工作流”建设一条独立后端路线,满足以下要求:
|
|
|
|
- 不影响现有同事正在开发的功能
|
|
- 不强耦合现有 DeerFlow 通用对话主链路
|
|
- 可独立部署、独立调试、独立回滚
|
|
- 支持多阶段写作编排、人工介入、失败重试、流式事件输出
|
|
|
|
---
|
|
|
|
## 2. 推荐建设方式
|
|
|
|
优先建议:
|
|
|
|
- 在 `offline-backend-20260512` 下新建独立应用或独立模块
|
|
|
|
建议目录:
|
|
|
|
```text
|
|
offline-backend-20260512/
|
|
apps/
|
|
ai_writing_orchestrator/
|
|
api/
|
|
application/
|
|
domain/
|
|
infrastructure/
|
|
prompts/
|
|
tests/
|
|
```
|
|
|
|
如果当前后端没有 `apps/` 结构,也可以采用:
|
|
|
|
```text
|
|
offline-backend-20260512/
|
|
ai-writing-orchestrator/
|
|
api/
|
|
application/
|
|
domain/
|
|
infrastructure/
|
|
prompts/
|
|
tests/
|
|
```
|
|
|
|
重点不是目录名字,而是一定要把“多 Agent 写作编排”与现有通用聊天能力隔离开。
|
|
|
|
---
|
|
|
|
## 3. 技术路线建议
|
|
|
|
推荐组合:
|
|
|
|
- 编排框架:`LangGraph`
|
|
- 模型调用:接你们内网模型网关
|
|
- 检索层:接内网知识库 / 文档库 / 搜索服务
|
|
- 状态存储:先用数据库或 Redis + DB,后续再演进
|
|
- 事件输出:SSE 或流式 HTTP
|
|
|
|
推荐原因:
|
|
|
|
- `LangGraph` 适合状态机和多节点回退
|
|
- 对弱模型最关键的是“强流程控制”,不是“自由 Agent 对话”
|
|
- 后续加人工确认节点和 checkpoint 会更自然
|
|
|
|
---
|
|
|
|
## 4. 分层设计
|
|
|
|
建议按四层拆分。
|
|
|
|
## 4.1 API 层
|
|
|
|
职责:
|
|
|
|
- 接收前端请求
|
|
- 鉴权
|
|
- 参数校验
|
|
- 返回 workflow 信息
|
|
- 提供事件流出口
|
|
|
|
建议文件:
|
|
|
|
```text
|
|
api/
|
|
routes/
|
|
workflows.py
|
|
workflow_events.py
|
|
schemas/
|
|
workflow_request.py
|
|
workflow_response.py
|
|
```
|
|
|
|
## 4.2 Application 层
|
|
|
|
职责:
|
|
|
|
- 组织用例
|
|
- 调度 workflow service
|
|
- 管理人工确认动作
|
|
- 处理重试和终止逻辑
|
|
|
|
建议文件:
|
|
|
|
```text
|
|
application/
|
|
services/
|
|
workflow_service.py
|
|
workflow_event_service.py
|
|
human_action_service.py
|
|
use_cases/
|
|
create_workflow.py
|
|
start_workflow.py
|
|
confirm_outline.py
|
|
rewrite_section.py
|
|
approve_final.py
|
|
```
|
|
|
|
## 4.3 Domain 层
|
|
|
|
职责:
|
|
|
|
- 定义工作流状态机
|
|
- 定义 Agent 输入输出协议
|
|
- 定义 artifact 与评分模型
|
|
|
|
建议文件:
|
|
|
|
```text
|
|
domain/
|
|
models/
|
|
workflow.py
|
|
workflow_stage.py
|
|
workflow_event.py
|
|
artifact.py
|
|
review_result.py
|
|
agents/
|
|
researcher.py
|
|
outliner.py
|
|
writer.py
|
|
editor.py
|
|
supervisor.py
|
|
graphs/
|
|
writing_graph.py
|
|
policies/
|
|
retry_policy.py
|
|
quality_policy.py
|
|
```
|
|
|
|
## 4.4 Infrastructure 层
|
|
|
|
职责:
|
|
|
|
- 访问模型网关
|
|
- 访问检索服务
|
|
- 访问数据库
|
|
- 发送事件
|
|
- 缓存与日志
|
|
|
|
建议文件:
|
|
|
|
```text
|
|
infrastructure/
|
|
llm/
|
|
model_client.py
|
|
retrieval/
|
|
intranet_search_client.py
|
|
knowledge_base_client.py
|
|
persistence/
|
|
workflow_repository.py
|
|
artifact_repository.py
|
|
streaming/
|
|
sse_publisher.py
|
|
logging/
|
|
workflow_logger.py
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 工作流最小闭环
|
|
|
|
第一版建议只做如下状态机:
|
|
|
|
1. `collect_materials`
|
|
2. `generate_outline`
|
|
3. `await_outline_confirmation`
|
|
4. `write_draft`
|
|
5. `review_draft`
|
|
6. `rewrite_if_needed`
|
|
7. `complete`
|
|
|
|
终止规则:
|
|
|
|
- 编辑评分达标则完成
|
|
- 否则进入重写
|
|
- 最多重写 2 次
|
|
- 超过次数则标记 `human_intervention_required`
|
|
|
|
---
|
|
|
|
## 6. Agent 模块设计
|
|
|
|
## 6.1 Researcher
|
|
|
|
输入:
|
|
|
|
- 主题
|
|
- 用户要求
|
|
- 检索范围
|
|
- 可用资料源
|
|
|
|
输出:
|
|
|
|
- `material_cards`
|
|
- `facts`
|
|
- `quotes`
|
|
- `examples`
|
|
- `risks`
|
|
- `source_refs`
|
|
|
|
程序职责:
|
|
|
|
- 先做检索
|
|
- 再把检索结果裁剪后送给模型
|
|
- 输出必须结构化
|
|
|
|
## 6.2 Outliner
|
|
|
|
输入:
|
|
|
|
- 用户要求
|
|
- 研究结果
|
|
|
|
输出:
|
|
|
|
- `title_candidates`
|
|
- `outline_sections`
|
|
- `key_points_per_section`
|
|
|
|
约束:
|
|
|
|
- 提纲优先,不写正文
|
|
|
|
## 6.3 Writer
|
|
|
|
输入:
|
|
|
|
- 已确认提纲
|
|
- 素材卡片
|
|
- 风格要求
|
|
|
|
输出:
|
|
|
|
- `draft_sections`
|
|
- `section_source_refs`
|
|
- `full_draft_markdown`
|
|
|
|
建议:
|
|
|
|
- 按章节分段生成,不要一次长文直出
|
|
|
|
## 6.4 Editor
|
|
|
|
输入:
|
|
|
|
- 初稿
|
|
- 提纲
|
|
- 素材
|
|
- 用户要求
|
|
|
|
输出:
|
|
|
|
- `issues`
|
|
- `severity`
|
|
- `score`
|
|
- `rewrite_instructions`
|
|
- `decision`
|
|
|
|
规则:
|
|
|
|
- 先查事实,再查结构,再查文风
|
|
|
|
## 6.5 Supervisor
|
|
|
|
输入:
|
|
|
|
- 各阶段结果
|
|
- 重试计数
|
|
- 评分结果
|
|
|
|
输出:
|
|
|
|
- 下一跳节点
|
|
- 是否需要人工确认
|
|
- 是否结束
|
|
|
|
---
|
|
|
|
## 7. Prompt 组织建议
|
|
|
|
建议为每个 Agent 分开管理 prompt,不要写成一个超级 prompt。
|
|
|
|
建议目录:
|
|
|
|
```text
|
|
prompts/
|
|
researcher/
|
|
system.txt
|
|
output_schema.json
|
|
outliner/
|
|
system.txt
|
|
output_schema.json
|
|
writer/
|
|
system.txt
|
|
output_schema.json
|
|
editor/
|
|
system.txt
|
|
output_schema.json
|
|
supervisor/
|
|
system.txt
|
|
```
|
|
|
|
原则:
|
|
|
|
- 每个 Agent 一套职责
|
|
- 每个 Agent 一套输出 schema
|
|
- Prompt 版本可管理
|
|
- 后续支持 A/B 调参
|
|
|
|
---
|
|
|
|
## 8. 弱模型适配策略
|
|
|
|
## 8.1 先检索后生成
|
|
|
|
不要让模型自己“想资料”,程序先检索、裁剪、去重后再喂给模型。
|
|
|
|
## 8.2 短上下文任务化
|
|
|
|
每个节点只给弱模型一小段明确任务:
|
|
|
|
- 研究归纳
|
|
- 提纲整理
|
|
- 单章节写作
|
|
- 单章节审稿
|
|
|
|
## 8.3 结构化输出
|
|
|
|
优先 JSON 或 Pydantic schema,不要放任自然语言自由返回。
|
|
|
|
## 8.4 章节级重写
|
|
|
|
不要整篇回炉。编辑指出第 2 节有问题,就只重写第 2 节。
|
|
|
|
## 8.5 程序接管质量门槛
|
|
|
|
例如:
|
|
|
|
- 资料引用数不足,不进入下一步
|
|
- 提纲章节数过少,直接重生
|
|
- 编辑评分低于阈值,自动重写
|
|
|
|
---
|
|
|
|
## 9. 数据模型建议
|
|
|
|
## 9.1 Workflow
|
|
|
|
建议字段:
|
|
|
|
- `id`
|
|
- `status`
|
|
- `current_stage`
|
|
- `user_id`
|
|
- `thread_id`
|
|
- `input_payload`
|
|
- `current_artifact_id`
|
|
- `retry_count`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
## 9.2 Workflow Artifact
|
|
|
|
建议字段:
|
|
|
|
- `id`
|
|
- `workflow_id`
|
|
- `artifact_type`
|
|
- `stage`
|
|
- `version`
|
|
- `title`
|
|
- `content`
|
|
- `metadata`
|
|
|
|
## 9.3 Workflow Event
|
|
|
|
建议字段:
|
|
|
|
- `id`
|
|
- `workflow_id`
|
|
- `event_type`
|
|
- `stage`
|
|
- `agent_name`
|
|
- `payload`
|
|
- `created_at`
|
|
|
|
## 9.4 Human Action
|
|
|
|
建议字段:
|
|
|
|
- `workflow_id`
|
|
- `action_type`
|
|
- `payload`
|
|
- `operator`
|
|
- `created_at`
|
|
|
|
---
|
|
|
|
## 10. API 草案
|
|
|
|
## 10.1 创建任务
|
|
|
|
`POST /api/ai-writing/workflows`
|
|
|
|
请求:
|
|
|
|
```json
|
|
{
|
|
"topic": "主题",
|
|
"articleType": "行业分析",
|
|
"audience": "管理层",
|
|
"tone": "专业克制",
|
|
"targetLength": 3000,
|
|
"constraints": ["避免口语化"],
|
|
"referenceScope": ["内网知识库", "项目复盘文档"]
|
|
}
|
|
```
|
|
|
|
返回:
|
|
|
|
```json
|
|
{
|
|
"workflowId": "wf_xxx",
|
|
"status": "idle"
|
|
}
|
|
```
|
|
|
|
## 10.2 启动任务
|
|
|
|
`POST /api/ai-writing/workflows/{id}/start`
|
|
|
|
## 10.3 查询任务
|
|
|
|
`GET /api/ai-writing/workflows/{id}`
|
|
|
|
## 10.4 订阅事件
|
|
|
|
`GET /api/ai-writing/workflows/{id}/events`
|
|
|
|
返回事件流示例:
|
|
|
|
```json
|
|
{
|
|
"type": "stage_changed",
|
|
"stage": "generating_outline",
|
|
"message": "正在生成提纲"
|
|
}
|
|
```
|
|
|
|
## 10.5 确认提纲
|
|
|
|
`POST /api/ai-writing/workflows/{id}/confirm-outline`
|
|
|
|
## 10.6 指定章节重写
|
|
|
|
`POST /api/ai-writing/workflows/{id}/rewrite-section`
|
|
|
|
## 10.7 确认终稿
|
|
|
|
`POST /api/ai-writing/workflows/{id}/approve-final`
|
|
|
|
---
|
|
|
|
## 11. LangGraph 实现建议
|
|
|
|
## 11.1 推荐 graph 节点
|
|
|
|
- `load_input`
|
|
- `retrieve_materials`
|
|
- `normalize_materials`
|
|
- `generate_outline`
|
|
- `wait_for_outline_confirmation`
|
|
- `write_sections`
|
|
- `merge_sections`
|
|
- `review_draft`
|
|
- `rewrite_sections`
|
|
- `publish_final_artifact`
|
|
|
|
## 11.2 推荐 state
|
|
|
|
建议 state 字段:
|
|
|
|
- `workflow_id`
|
|
- `input_payload`
|
|
- `materials`
|
|
- `outline`
|
|
- `outline_confirmed`
|
|
- `draft_sections`
|
|
- `merged_draft`
|
|
- `review_result`
|
|
- `rewrite_targets`
|
|
- `final_article`
|
|
- `retry_count`
|
|
- `events`
|
|
|
|
## 11.3 条件边
|
|
|
|
建议条件边逻辑:
|
|
|
|
- 提纲未确认 -> 等待用户
|
|
- 编辑通过 -> 完成
|
|
- 编辑不通过且可重试 -> 重写
|
|
- 编辑不通过且超限 -> 人工介入
|
|
|
|
---
|
|
|
|
## 12. 可观测性要求
|
|
|
|
第一版就建议带上以下能力:
|
|
|
|
- 每个 workflow 的事件日志
|
|
- 每个 Agent 的输入输出摘要
|
|
- 每次重试原因
|
|
- 每个阶段耗时
|
|
- 每次模型调用 token 与错误日志
|
|
|
|
后续排问题会非常依赖这些数据。
|
|
|
|
---
|
|
|
|
## 13. 测试建议
|
|
|
|
## 13.1 单元测试
|
|
|
|
覆盖:
|
|
|
|
- stage 流转
|
|
- retry policy
|
|
- quality policy
|
|
- 事件构造
|
|
|
|
## 13.2 集成测试
|
|
|
|
覆盖:
|
|
|
|
- 创建任务到完成的主链路
|
|
- 提纲确认链路
|
|
- 审稿失败后重写链路
|
|
- 人工介入链路
|
|
|
|
## 13.3 Prompt 回归集
|
|
|
|
建议建立 10-20 个固定写作样例,做回归:
|
|
|
|
- 短文
|
|
- 长文
|
|
- 事实密集型文章
|
|
- 宣传型文章
|
|
- 分析型文章
|
|
|
|
---
|
|
|
|
## 14. 开发顺序建议
|
|
|
|
## Step 1:先做 domain 与 API 契约
|
|
|
|
先定:
|
|
|
|
- stage 枚举
|
|
- event 枚举
|
|
- artifact 结构
|
|
- human action payload
|
|
|
|
## Step 2:先做 fake orchestrator
|
|
|
|
先不接真实模型,只模拟事件流,把前后端联调跑通。
|
|
|
|
## Step 3:接 Researcher + Outliner
|
|
|
|
优先把“研究 + 提纲”做出来,因为这是弱模型提升最大的环节。
|
|
|
|
## Step 4:接 Writer + Editor
|
|
|
|
再接初稿和审稿重写。
|
|
|
|
## Step 5:接可观测性和缓存
|
|
|
|
最后再补生产化能力。
|
|
|
|
---
|
|
|
|
## 15. 风险控制建议
|
|
|
|
### 风险 1:直接复用现有线程流,导致协议污染
|
|
|
|
建议:
|
|
|
|
- workflow 用独立 route 和独立 event schema
|
|
|
|
### 风险 2:写作结果与右侧 artifact 模型不兼容
|
|
|
|
建议:
|
|
|
|
- 后端统一输出标准 markdown artifact
|
|
|
|
### 风险 3:弱模型频繁输出不合法 JSON
|
|
|
|
建议:
|
|
|
|
- 每个节点加 schema repair
|
|
- 加轻量重试
|
|
- 尽量减少复杂嵌套输出
|
|
|
|
### 风险 4:研究资料太多导致上下文爆炸
|
|
|
|
建议:
|
|
|
|
- 检索后先裁剪、摘要、分桶
|
|
|
|
---
|
|
|
|
## 16. 最终建议
|
|
|
|
后端第一版最重要的是把“状态机、事件流、人工确认、章节重写”这四件事做对,而不是一开始就追求很多花哨 Agent。
|
|
|
|
建议 MVP 只保留:
|
|
|
|
1. Researcher
|
|
2. Outliner
|
|
3. Writer
|
|
4. Editor
|
|
5. Supervisor
|
|
|
|
当这条链路稳定后,再继续扩展 fact-checker、style editor、compliance reviewer。
|