客户展示版 | Project Architecture Showcase

# GEO 智能文章优化器

一个以事实卡为约束、以质量门禁为闭环的 AI 内容优化工作流。它不是普通改写器， 而是把“事实确认、内容优化、风险检查、定向修复、交付导出”串成可控流程的本地 MVP。

事实卡约束 多节点 Agent 工作流 QA 质量门禁 定向重写 Markdown / Word / JSON 导出
10 类内容质量门禁
2 轮失败项定向重写
3 种可下载交付物

Why It Matters

## 先解决客户最担心的内容风险

GEO 内容优化的核心不是“写得更像 AI”，而是让文章在事实、语气、结构和平台适配上更可靠。 当前项目把常见风险转成可执行的工作流节点和质量检查。

### 典型问题

- 行业漂移，文章越改越偏。
- 公司全称、简称、品牌名不一致。
- 图片主题与正文描述不匹配。
- 官方文章里出现第三方口吻。
- 平台语气和文章类型不匹配。
- 标题或正文语义不顺。
- 虚构资质、年限、案例或能力。
- 产品、服务、年限前后冲突。

### 解决路径

- 先从原文提取候选事实。
- 由用户确认或编辑事实卡。
- 所有优化都受已确认事实约束。
- 优化后运行结构化质量门禁。
- 只针对失败项进行定向重写。
- 硬性失败清除后再允许导出。

Workflow Architecture

## 从文章输入到可交付结果的闭环

项目内部拆成多个职责明确的节点。每个节点只处理自己的任务，最终由编排器串联成完整优化流程。

Article Input 标题、正文、图片、平台
→
InputNormalizer 规范化输入结构
→
FactExtractor 提取候选事实卡
→
UserConfirmedFactCard 用户确认硬约束
→
ArticleOptimizer 受约束内容优化
→
QualityInspector 执行 QA 门禁
→
TargetedRewriter 只修复失败项
→
Exporter 导出交付文件

当质量检查出现硬性失败时，TargetedRewriter 会把失败项送回 QualityInspector 复检，最多进行两轮定向修复，避免整篇文章被盲目重写。

Code Architecture

## 清晰分层，方便测试、替换与扩展

当前仓库不是把所有逻辑塞进页面，而是把 UI、API、领域模型、工作流、模型供应商和本地存储拆开。

`src/app`

Next.js 页面与 API 路由，负责创建任务、确认事实卡、触发优化和下载导出文件。

`src/components`

输入表单、事实卡编辑器、优化预览、QA 报告面板，各自专注一个用户界面区域。

`src/lib/domain`

共享 TypeScript 类型与 Zod 校验，统一文章输入、事实卡、优化结果和质量报告的数据契约。

`src/lib/workflow`

包含规范化、事实提取、文章优化、质量检查、定向重写、导出和编排器，是核心 Agent 流程层。

`src/lib/llm`

隔离 DeepSeek 与 OpenAI-compatible 模型调用，提供统一的文本生成、JSON 生成和供应商状态接口。

`src/lib/db`

本地 SQLite 连接、schema 和 repository，支持任务、事实卡、优化结果和导出记录持久化。

`tests`

Vitest 与 Playwright 覆盖领域校验、数据库、工作流、API 和 MVP 端到端行为。

Technical Highlights

## 让客户放心的关键设计

这些亮点都来自当前代码结构和产品流程，重点是降低幻觉风险、提高可控性，并保留后续扩展空间。

### 1事实先确认

候选事实不会自动成为真相。公司名、产品名、行业、年限和核心声明必须进入已确认事实卡后，才会约束后续优化。

### 2质量门禁结构化

检查结果统一为 `pass`、`warn`、`fail`，硬性失败会阻止导出，避免问题内容直接交付。

### 3失败项精准重写

标题问题改标题，公司名问题改事实一致性，图片问题提示确认；避免一次失败就重新生成整篇文章。

### 4模型供应商可替换

LLM 调用集中在 provider client，当前支持 DeepSeek 和 OpenAI-compatible 配置，后续可替换模型而不改工作流。

### 5本地可演示可测试

缺少 API Key 时仍有确定性本地 fallback，配合 SQLite 本地存储，适合内网演示、测试和客户评审。

### 6导出面向交付

通过 Markdown / Word / JSON 同时服务人工审稿、客户交付和系统集成，QA 报告也能作为质量依据留档。

Pass 可进入预览与导出。
Warn 允许导出，但提示人工复核。
Fail 触发重写或阻止导出。

MVP Boundary

## 边界清楚，才方便下一步投入

当前版本聚焦验证“事实约束 + QA 闭环”的主链路，不提前引入批量队列、权限系统或发布平台集成。

### 当前 MVP 边界

- 仅支持粘贴文本，不直接解析 .docx。
- 仅使用本地 SQLite 存储。
- 暂无账号权限与多人协作。
- 暂无发布平台 API 集成。
- 暂无批量队列。
- Word 导出为基础版式。

### 自然扩展方向

1. .docx 解析与模板化 Word 导出。
2. 多品牌事实卡库与复用策略。
3. 批量优化队列与任务看板。
4. 团队审稿、确认和发布审批流程。
5. 对接官网、媒体号或其他发布平台。
6. 行业专属质量门禁与规则包。

Customer Takeaway

## 这套架构的价值

它把 AI 内容生成从“不可控的一次性改写”变成“可确认、可检查、可修复、可交付”的工程化流程。

对客户来说，这意味着更低的事实风险、更清晰的质量依据和更稳定的交付结果。 对技术团队来说，这意味着每个节点都可以独立测试、替换和扩展，后续接入更多模型、更多规则和更多发布场景时， 不需要推翻当前主流程。