diff --git a/docs/project-architecture-showcase.html b/docs/project-architecture-showcase.html new file mode 100644 index 0000000..6c6d928 --- /dev/null +++ b/docs/project-architecture-showcase.html @@ -0,0 +1,681 @@ + + + + + + GEO 智能文章优化器 | 项目架构展示 + + + +
+
+
+

客户展示版 | 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. +
  2. 多品牌事实卡库与复用策略。
    3. +
  3. 批量优化队列与任务看板。
    4. +
  4. 团队审稿、确认和发布审批流程。
    5. +
  5. 对接官网、媒体号或其他发布平台。
    6. +
  6. 行业专属质量门禁与规则包。
    7. +
+
+
+
+ +
+
+
+

Customer Takeaway

+

这套架构的价值

+
+

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

+
+
+

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

+
+
+
+ + + diff --git a/docs/superpowers/plans/2026-06-16-project-architecture-showcase-html.md b/docs/superpowers/plans/2026-06-16-project-architecture-showcase-html.md new file mode 100644 index 0000000..bc32ed3 --- /dev/null +++ b/docs/superpowers/plans/2026-06-16-project-architecture-showcase-html.md @@ -0,0 +1,104 @@ +# Project Architecture Showcase HTML Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Build a standalone Chinese HTML page that presents the GEO Agent Article Optimizer architecture, business value, technical highlights, MVP boundaries, and expansion paths for customer demonstrations. + +**Architecture:** Implement a single static HTML document under `docs/` with embedded CSS and no external dependencies. The document will use semantic sections, responsive CSS grid/flex layouts, and CSS-only diagrams to show the workflow and system layers. + +**Tech Stack:** HTML5, embedded CSS, no JavaScript required, no external assets. + +--- + +## File Structure + +- Create: `docs/project-architecture-showcase.html` + - Self-contained customer-facing presentation page. + - Includes all copy, layout, and responsive CSS in one file. + - Opens directly in a browser without Next.js, CDN assets, or network access. + +## Task 1: Create Static Showcase Page + +**Files:** + +- Create: `docs/project-architecture-showcase.html` + +- [ ] **Step 1: Create the standalone HTML skeleton** + + Add a complete HTML5 document with: + + - `lang="zh-CN"`. + - UTF-8 charset. + - Responsive viewport meta tag. + - Page title: `GEO 智能文章优化器 | 项目架构展示`. + - Embedded `