# AI 写作执行方案

## 1. 总体原则

本项目的最终落地原则：

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

一句话说明：

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

---

## 2. 项目边界

## 2.1 前端边界

继续使用当前页面：

- [CanvasResizableLayout.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/layout/CanvasResizableLayout.tsx)
- [CanvasChatPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/chat/CanvasChatPanel.tsx)
- [CanvasArtifactPanel.tsx](/F:/react/deeflow-code/deerflow-server-master/frontend-web/src/open-canvas/components/artifact/CanvasArtifactPanel.tsx)

前端做的事情：

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

前端不做的事情：

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

## 2.2 后端边界

后端采用独立新路线：

推荐目录：

```text
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 结构不区分互联网资料和内网资料

推荐检索抽象：

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

建议接口：

```python
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`

例如：

```yaml
retrieval:
  provider: internet
  top_k: 8
  timeout_seconds: 15
```

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

---

## 3. 第一版产品目标

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

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

第一版成功标准：

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

## 3.1 第一版研究员目标

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

第一版输入：

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

第一版输出至少包含：

- `material_cards`
- `facts`
- `quotes`
- `examples`
- `risks`
- `source_refs`

每条素材最少要带：

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

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

1. 根据主题自动生成 3-5 个检索 query
2. 调用互联网检索接口拿回候选文档
3. 做去重、裁剪、初筛
4. 让模型将结果整理成结构化素材卡片
5. 将结构化结果返回给 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 流程闭环

最小闭环固定为：

1. `Research`
2. `Outline`
3. `HumanConfirmOutline`
4. `Draft`
5. `Review`
6. `RewriteIfNeeded`
7. `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` 下新增：

```text
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 分层

推荐分层：

```text
api/
application/
domain/
infrastructure/
prompts/
tests/
```

## 6.2 核心模块

建议核心文件：

```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
```

## 6.3 检索层实现要求

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

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

建议结构：

```text
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 管理

统一独立存放：

```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
```

## 6.5 输出约束

每个 Agent 都必须：

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

## 6.6 Researcher 的实现细则

Researcher 推荐由两部分组成：

1. 程序化检索
2. 模型化整理

推荐伪流程：

```python
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 配置项补充

建议增加以下配置项：

```yaml
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，把研究、提纲、初稿、审稿重写这条最小闭环做稳。”