wsk/deerflow-code

0 Fork 0

Files

T

fengxiangdebaozi 5c553aae19 文档更新

2026-05-18 09:58:34 +08:00

17 KiB

Raw Blame History

AI 写作执行方案

1. 总体原则

本项目的最终落地原则：

前端继续基于当前 open-canvas 页面开发，不复制第二套页面
后端单独开 ai-writing-orchestrator 新路线，不侵入现有主链路
编排框架采用 LangGraph
写作工作流采用 Researcher -> Outliner -> Writer -> Editor -> Supervisor
Agent 间输出统一采用 JSON Schema / Pydantic
前后端通过 SSE 传递工作流事件
第一版只做最小闭环，不做过多花哨扩展

一句话说明：

用独立的新后端路线承载多 Agent 写作工作流，前端继续复用 open-canvas，实现上采用 LangGraph + A/B/C Agent + SSE 的最小闭环。

2. 项目边界

2.1 前端边界

继续使用当前页面：

前端做的事情：

左侧增加“写作工作流模式”
展示多 Agent 执行进度与中间产物
提供提纲确认和指定章节重写
将初稿、终稿同步到右侧 artifact

前端不做的事情：

不重写右侧编辑器
不重写现有普通 chat 流程
不把 workflow 状态散落在多个旧 context 里

2.2 后端边界

后端采用独立新路线：

推荐目录：

offline-backend-20260512/
  apps/
    ai_writing_orchestrator/
      api/
      application/
      domain/
      infrastructure/
      prompts/
      tests/

后端做的事情：

实现写作 workflow 状态机
实现 A/B/C Agent 与 Supervisor
接内网模型与内网检索
输出标准事件流和文章 artifact

后端不做的事情：

不直接改现有 DeerFlow 主流程
不把工作流逻辑塞到现有通用 thread 协议里

2.3 资料搜集边界

第一版处于互联网开发阶段，因此研究员的资料搜集先走互联网检索，不接内网检索服务。

第一版要求：

研究员可以调用互联网搜索能力收集公开资料
研究结果必须保留来源 URL、标题、摘要、抓取时间
检索层必须抽象成统一接口，不能把互联网搜索逻辑写死在 Agent prompt 或 graph 节点里

第二版预留：

后续替换或并行接入内网搜索接口
后续接入内部知识库、文档库、FAQ、项目复盘库
前端和工作流层不因检索源变化而改协议

统一设计要求：

Researcher 只依赖“检索接口”，不依赖具体是互联网还是内网
writing_graph 只读取标准化后的素材结果
API、事件流、artifact 结构不区分互联网资料和内网资料

推荐检索抽象：

infrastructure/
  retrieval/
    base.py
    internet_search_client.py
    intranet_search_client.py
    retriever_router.py

建议接口：

class RetrievalProvider(Protocol):
    def search(self, query: str, top_k: int) -> list[RetrievedDocument]: ...

class RetrievedDocument(BaseModel):
    title: str
    url: str | None
    source_type: str
    snippet: str
    published_at: str | None = None
    fetched_at: str
    reliability: str | None = None

第一版路由策略：

默认 internet
配置项预留 intranet、hybrid

例如：

retrieval:
  provider: internet
  top_k: 8
  timeout_seconds: 15

这样第一版先跑公网资料，后续切换内网时，只替换 retriever_router 和对应 provider，不改 workflow 主逻辑。

3. 第一版产品目标

用户在 open-canvas 中选择“写作工作流模式”后，可以完成以下流程：

输入主题、体裁、读者、风格、篇幅
研究员搜集资料并输出素材卡片
提纲 Agent 生成提纲
用户确认提纲
Writer 生成初稿
Editor 给出问题清单与评分
不达标则重写一次或两次
终稿写入右侧 artifact

第一版成功标准：

不是“生成得像最强模型一样好”
而是“明显优于单轮直出，并且流程可控、可回退、可人工介入”

3.1 第一版研究员目标

第一版 Researcher 的核心职责，不是“写文章”，而是“给 Writer 准备可信、可引用、可筛选的素材”。

第一版输入：

用户主题
用户写作要求
检索源配置，第一版默认 internet

第一版输出至少包含：

material_cards
facts
quotes
examples
risks
source_refs

每条素材最少要带：

来源标题
来源 URL
摘要
可信度标签
被引用的原始片段或整理后的事实点

第一版 Researcher 的程序流程建议：

根据主题自动生成 3-5 个检索 query
调用互联网检索接口拿回候选文档
做去重、裁剪、初筛
让模型将结果整理成结构化素材卡片
将结构化结果返回给 Outliner 和 Writer

第一版先不做：

深度网页 crawling
多轮自动追问式深研究
内网知识库接入
复杂引用格式生成

4. 最终工作流

4.1 Agent 角色

`Researcher`

职责：

从配置的检索源检索信息
产出结构化素材卡片
标注来源、可信度、风险点

第一版说明：

默认走互联网公开资料检索
必须预留后续切换到内网检索源的接口
检索实现放在 infrastructure/retrieval/，不要写死在 prompt 中

第一版检索源字段建议：

source_type = "internet"
后续预留 source_type = "intranet" | "hybrid"

输出：

material_cards
facts
quotes
examples
risks
source_refs

`Outliner`

职责：

根据用户要求和研究结果生成提纲

输出：

title_candidates
outline_sections
key_points_per_section

`Writer`

职责：

基于提纲和素材写初稿
按章节写，不一次生成整篇长文

输出：

draft_sections
section_source_refs
full_draft_markdown

`Editor`

职责：

检查事实、结构、文风
给出评分与重写建议

输出：

issues
severity
score
rewrite_instructions
decision

`Supervisor`

职责：

负责流程调度
负责通过 / 重写 / 人工介入判断

4.2 状态机

第一版统一采用：

idle
collecting_materials
generating_outline
await_outline_confirmation
writing_draft
reviewing_draft
rewriting_draft
completed
failed
human_intervention_required

4.3 流程闭环

最小闭环固定为：

Research
Outline
HumanConfirmOutline
Draft
Review
RewriteIfNeeded
Complete

重试规则：

最多重写 2 次
达标则完成
超限则进入人工介入

4.4 LangGraph 推荐节点

第一版推荐节点：

load_input
build_search_queries
retrieve_materials
normalize_materials
generate_outline
wait_for_outline_confirmation
write_sections
merge_sections
review_draft
rewrite_sections
publish_final_artifact

其中和资料搜集直接相关的节点说明：

`build_search_queries`

职责：

根据用户主题和目标文章类型，生成 3-5 个检索 query

`retrieve_materials`

职责：

调用检索 provider 获取候选文档
第一版默认走 internet_search_client
后续可切到 intranet_search_client

`normalize_materials`

职责：

做去重
做摘要裁剪
做来源字段统一
输出标准 RetrievedDocument[]

5. 前端最终做法

5.1 目录建议

在现有 open-canvas 下新增：

frontend-web/src/open-canvas/
  workflow/
    api/
      writing-workflow.ts
    components/
      WritingWorkflowEntryForm.tsx
      WritingWorkflowTimeline.tsx
      WritingWorkflowEventList.tsx
      WritingWorkflowArtifactDrawer.tsx
      WritingWorkflowConfirmCard.tsx
      WritingWorkflowHeader.tsx
      CanvasWorkflowPanel.tsx
    contexts/
      WritingWorkflowContext.tsx
    hooks/
      useWritingWorkflow.ts
      useWritingWorkflowEvents.ts
    types/
      workflow.ts

5.2 左侧改造策略

CanvasChatPanel 只承担模式切换与容器职责：

chat 模式：沿用现有普通聊天
writing_pipeline 模式：渲染 CanvasWorkflowPanel

新面板负责：

写作任务表单
进度时间线
事件列表
中间产物抽屉
提纲确认卡片

5.3 右侧衔接策略

继续复用现有 CanvasArtifactPanel。

同步规则：

提纲：可选同步到右侧预览
初稿：同步到右侧
重写稿：覆盖当前草稿
终稿：作为最终 artifact

5.4 前端状态设计

新增：

workflowMode
workflowRunId
workflowStage
workflowStatus
workflowEvents
workflowArtifacts
workflowPendingAction

注意：

workflow 状态放进新的 WritingWorkflowContext
不塞进现有 CanvasGraphContext

5.5 前端显示的资料信息

第一版左侧至少要能展示研究员产出的资料摘要：

来源标题
来源域名或 URL
资料摘要
可信度标签
是否被提纲或正文引用

建议在 WritingWorkflowArtifactDrawer.tsx 中增加“素材卡片”视图。

注意：

第一版显示公开互联网来源即可
后续接内网时，这个展示层不变，只是来源字段从 URL 变成内网文档标识或内部链接

6. 后端最终做法

6.1 分层

推荐分层：

api/
application/
domain/
infrastructure/
prompts/
tests/

6.2 核心模块

建议核心文件：

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

6.3 检索层实现要求

第一版检索层必须独立成基础设施模块，不允许：

在 Agent prompt 中直接拼接“去网上找资料”
在 graph 节点中散落请求第三方搜索的代码
把互联网检索和内网检索混在一个无抽象的函数里

建议结构：

infrastructure/
  retrieval/
    base.py
    internet_search_client.py
    intranet_search_client.py
    retriever_router.py
    material_normalizer.py

建议职责：

internet_search_client.py
- 第一版实际使用
- 对接互联网搜索 API 或爬取网关
intranet_search_client.py
- 第一版只保留接口和空实现或 mock
- 后续接企业内部接口
retriever_router.py
- 根据配置选择 provider
material_normalizer.py
- 统一清洗和标准化结果

6.4 Prompt 管理

统一独立存放：

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

6.5 输出约束

每个 Agent 都必须：

优先输出 JSON / Pydantic schema
失败时允许轻量 repair 和一次重试
避免自由散文式输出

6.6 Researcher 的实现细则

Researcher 推荐由两部分组成：

程序化检索
模型化整理

推荐伪流程：

def run_research(topic: str, article_type: str, provider: RetrievalProvider):
    queries = build_queries(topic, article_type)
    raw_docs = []
    for query in queries:
        raw_docs.extend(provider.search(query=query, top_k=5))
    docs = normalize_materials(raw_docs)
    docs = dedupe_materials(docs)
    docs = rank_materials(docs)
    return llm_extract_material_cards(docs)

第一版建议：

先把 query 生成逻辑做简单
top_k 先控制在 5-10
先做轻量去重和摘要裁剪
不做很重的网页全文抓取

7. 前后端协议

7.1 API

第一版统一提供：

POST /api/ai-writing/workflows
POST /api/ai-writing/workflows/{id}/start
GET /api/ai-writing/workflows/{id}
GET /api/ai-writing/workflows/{id}/events
POST /api/ai-writing/workflows/{id}/confirm-outline
POST /api/ai-writing/workflows/{id}/rewrite-section
POST /api/ai-writing/workflows/{id}/approve-final

7.2 SSE 事件

统一事件类型：

workflow_started
stage_changed
agent_started
agent_output_chunk
artifact_generated
human_confirmation_required
retry_scheduled
workflow_completed
workflow_failed

第一版前端不需要消费复杂嵌套事件，只要先把这 9 类打通。

7.3 配置项补充

建议增加以下配置项：

retrieval:
  provider: internet
  top_k: 8
  timeout_seconds: 15
  enable_content_fetch: false

workflow:
  max_revisions: 2

models:
  researcher: your-default-model
  outliner: your-default-model
  writer: your-default-model
  editor: your-default-model

说明：

第一版 provider=internet
第二版可切成 intranet 或 hybrid

8. 必须做 / 延后做 / 不建议现在做

8.1 必须做

架构

独立后端路线 ai-writing-orchestrator
前端独立 workflow/ 目录
LangGraph 状态机
Researcher / Outliner / Writer / Editor / Supervisor
独立检索抽象层，第一版先落互联网 provider

协议

标准 workflow 状态枚举
标准 SSE 事件枚举
标准 artifact 结构
JSON / Pydantic 输出约束

功能

启动写作任务
研究阶段
提纲阶段
提纲确认
初稿生成
审稿与最多 2 次重写
终稿同步到右侧
素材卡片展示
来源 URL、标题、摘要、可信度落库或挂在 artifact metadata

UI

模式切换
时间线
事件列表
提纲确认卡片
右侧终稿显示
左侧素材卡片视图

8.2 延后做

章节级精准重写
初稿多版本树
FactChecker
StyleEditor
ComplianceReviewer
自动评分看板
素材引用可视化高亮
更复杂的人机协作节点
内网知识库正式接入
混合检索 hybrid
网页全文抓取与深摘要

8.3 不建议现在做

直接接入现有 DeerFlow 主 agent 包
同时试 MetaGPT、CrewAI、AutoGen 多套底座
一开始就做 5 个以上 Agent
一开始就做很复杂的文章版本管理
一开始就把评分阈值和 prompt 写死得非常细

9. 最终开发顺序

Step 1：先定契约

先一起拍板：

stage 枚举
event 枚举
artifact 结构
confirm / rewrite 的 payload
retrieval provider 接口
RetrievedDocument 结构

Step 2：先做 fake workflow

后端先不接真实模型，只吐 mock SSE 事件，前端把左侧工作台跑通。

Step 3：先接互联网版 Researcher + Outliner

优先打磨“研究 + 提纲”，这是弱模型提升最大的部分。

这一阶段要求：

Researcher 先走互联网检索
retriever_router 可配置
intranet_search_client 先留接口空壳

Step 4：接 Writer + Editor

再补初稿与审稿重写闭环。

Step 5：接右侧 artifact

把初稿和终稿稳定写入右侧。

Step 6：补生产化

缓存
日志
错误回放
配置化 prompt

10. 推荐任务拆分

前端

CanvasChatPanel 模式切换
workflow/ 目录与类型
时间线 / 事件列表 / 确认卡片
SSE 订阅 hook
右侧 artifact 映射
素材卡片列表展示
来源字段展示规范

后端

workflow API
LangGraph graph
5 个 Agent 模块
Prompt 目录
SSE 输出
仓储与日志
RetrievalProvider 抽象
internet_search_client
intranet_search_client 预留接口
material_normalizer

Prompt / 算法

Researcher prompt
Outliner prompt
Writer prompt
Editor prompt
JSON schema
失败样本回归

联调

mock SSE
真模型接入
artifact 同步校验
提纲确认链路验证
互联网资料来源字段联调
素材卡片到提纲引用链路联调

11. 开发过程中的约束

开发过程中统一采用下面这套口径：

产品形态：当前 open-canvas 页面上的“写作工作流模式”
技术底座：LangGraph
核心模式：Researcher -> Outliner -> Writer -> Editor -> Supervisor
后端方式：独立 ai-writing-orchestrator
检索方式：第一版 internet，接口预留 intranet
通信方式：SSE
输出方式：JSON Schema / Pydantic
第一版目标：先做最小闭环，不追求角色数量和复杂度

给开发团队的统一口径：

“我们在 open-canvas 上开发写作工作流模式，后端单开 ai-writing-orchestrator，第一版先用互联网资料检索，保留内网检索接入口，用 LangGraph 编排 Researcher、Outliner、Writer、Editor、Supervisor，把研究、提纲、初稿、审稿重写这条最小闭环做稳。”

17 KiB Raw Blame History