From 601ac021ef8331785362b1b5d4a5301d83d15596 Mon Sep 17 00:00:00 2001 From: Your Name Date: Tue, 16 Jun 2026 09:20:21 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=9D=E5=A7=8B=E5=8C=96GEO=E6=96=87?= =?UTF-8?q?=E7=AB=A0=E4=BC=98=E5=8C=96Agent=E8=AE=BE=E8=AE=A1=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 9 + ...6-16-geo-agent-article-optimizer-design.md | 413 ++++++++++++++++++ 2 files changed, 422 insertions(+) create mode 100644 .gitignore create mode 100644 docs/superpowers/specs/2026-06-16-geo-agent-article-optimizer-design.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..21df0ee --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +.superpowers/ +data/app.db +data/exports/ +node_modules/ +dist/ +build/ +.env +.env.* +*.log diff --git a/docs/superpowers/specs/2026-06-16-geo-agent-article-optimizer-design.md b/docs/superpowers/specs/2026-06-16-geo-agent-article-optimizer-design.md new file mode 100644 index 0000000..ff57e46 --- /dev/null +++ b/docs/superpowers/specs/2026-06-16-geo-agent-article-optimizer-design.md @@ -0,0 +1,413 @@ +# GEO Agent Article Optimizer MVP Design + +## Goal + +Build a lightweight internal web tool for optimizing pasted GEO-related articles while preventing the issues observed in `GEO生成文章改动点(0422).docx`: industry drift, image-text mismatch, third-party voice in official articles, platform mismatch, incomplete company names, title/body grammar issues, hallucinated claims, inconsistent claims, context-insensitive sensitive-word handling, and useless content. + +The first version validates the content quality loop before investing in batching, permissions, publishing integrations, or complex document parsing. + +## MVP Scope + +The MVP is a local web application: + +1. User pastes title, body, image descriptions or image links, and selects the target platform. +2. System extracts a candidate fact card. +3. User confirms or edits the fact card. +4. Confirmed fact card is saved as a reusable local brand template. +5. System optimizes the article under fact-card constraints. +6. System runs quality gates. +7. Failed checks trigger targeted rewriting for up to two rounds. +8. User previews optimized content and QA report. +9. User downloads Markdown and a basic Word document. + +## Explicitly Out Of Scope + +- Account permissions. +- Multi-user collaboration. +- Publishing platform APIs. +- Batch queues. +- Direct `.docx` upload parsing. +- Complex Word template layout. +- Automatic use of unconfirmed facts. + +## User Flow + +```mermaid +flowchart TD + A["Input Article"] --> B["Auto Analyze"] + B --> C["Confirm Fact Card"] + C --> D["Optimize Article"] + D --> E["Quality Check"] + E -->|Pass| F["Preview Result"] + E -->|Fail| G["Targeted Rewrite"] + G --> D + F --> H["Download Markdown / Word"] +``` + +## Page Areas + +### Article Input + +Fields: + +- Title. +- Body. +- Image description or image link. +- Target platform: official site, media article, comparison review, recommendation list. +- User instructions. + +The first version accepts pasted text instead of `.docx` upload to avoid early complexity around Word layout parsing. + +### Fact Card Confirmation + +The system extracts candidate facts, but they are not treated as truth until the user confirms them. + +Fields: + +- Company full name. +- Company short names. +- Brand names. +- Product names. +- Target industry. +- Target audience. +- Experience years. +- Core claims. +- Forbidden claims. +- Image topics. +- Uncertain items. + +The user must resolve uncertain items before optimization starts. + +### Optimized Result + +Display: + +- Optimized title. +- Summary. +- Optimized body. +- Image suggestions. +- Changed sections. + +The UI should mark content that needs user confirmation. + +### Quality Report + +Display each gate as pass, warn, or fail, with evidence, reason, suggested fix, and target rewrite module. + +### Export + +Downloads: + +- `optimized.md` +- `optimized.docx` +- `qa_report.json` + +## Internal Agent Nodes + +The product is delivered as a simple web app, but the internals are split into explicit workflow nodes. + +```mermaid +flowchart LR + A["InputNormalizer"] --> B["FactExtractor"] + B --> C["UserConfirmedFactCard"] + C --> D["ArticleOptimizer"] + D --> E["QualityInspector"] + E -->|fail| F["TargetedRewriter"] + F --> E + E -->|pass/warn| G["Exporter"] +``` + +### InputNormalizer + +Purpose: normalize page input into clean structured data. + +Input: + +- Title. +- Body. +- Image descriptions or links. +- Target platform. +- User instructions. + +Output: + +- `article_draft` +- `image_assets` +- `publish_context` + +This node does not optimize content. + +### FactExtractor + +Purpose: extract candidate facts from the source article. + +Output: + +- `company_full_name` +- `company_short_name` +- `brand_names` +- `product_names` +- `target_industry` +- `target_audience` +- `experience_years` +- `core_claims` +- `forbidden_claims` +- `image_topics` +- `uncertain_items` + +Low-confidence facts must go into `uncertain_items`. + +### UserConfirmedFactCard + +Purpose: provide hard constraints for all downstream nodes. + +Rules: + +- No downstream node may invent numbers, qualifications, clients, cases, or experience years outside the confirmed fact card. +- Company and product names must follow the fact card. +- Industry and audience must not drift from the fact card. +- Sensitive words must be handled by context, not removed mechanically. + +### ArticleOptimizer + +Purpose: improve title, summary, body, structure, and image suggestions under fact-card constraints. + +Allowed: + +- Improve fluency. +- Fix grammar. +- Adjust structure. +- Improve platform fit. +- Remove useless content. +- Improve transitions. + +Forbidden: + +- Invent claims. +- Change company or product names. +- Change industry. +- Add exaggerated marketing promises. + +### QualityInspector + +Purpose: convert the document's issue list into executable quality gates. + +Each check returns: + +- `status`: `pass`, `warn`, or `fail`. +- `evidence`: source or optimized text snippet. +- `reason`: why the check passed or failed. +- `suggested_fix`: how to fix it. +- `target_agent`: rewrite target when failed. + +### TargetedRewriter + +Purpose: fix only failed checks. + +Examples: + +- Rewrite only the title for title quality failures. +- Adjust only the affected paragraph for body quality failures. +- Normalize company names for fact consistency failures. +- Delete or mark unsupported claims for hallucination risk. +- Warn instead of rewriting when image-text confidence is low. + +## Quality Gates + +| Rule ID | Issue Prevented | First Version Behavior | +| --- | --- | --- | +| `industry_alignment` | Industry drift | Compare article against fact-card industry and audience. | +| `image_text_match` | Image-text mismatch | Compare image descriptions/topics with nearby article sections. | +| `voice_consistency` | Third-party voice in official articles | Enforce platform-specific tone. | +| `platform_fit` | Wrong article type for platform | Compare style and structure against target platform. | +| `company_name_integrity` | Incomplete company name | Compare against confirmed company full name and allowed short names. | +| `title_quality` | Title grammar issues | Detect awkward, keyword-stuffed, or semantically broken titles. | +| `body_quality` | Body grammar issues | Detect long sentences, unclear references, and broken logic. | +| `hallucination_risk` | Fabricated or misleading claims | Reject claims not traceable to the confirmed fact card. | +| `claim_consistency` | Inconsistent years/products/services | Scan and normalize repeated factual claims. | +| `context_sensitive_terms` | Blind sensitive-word deletion | Warn when wording needs context-aware handling. | + +### Hard Fail + +- Incomplete or inconsistent company name. +- New numbers, qualifications, customer cases, or other claims outside the fact card. +- Clear industry drift. +- Severe title grammar failure. +- Conflicting experience years, product names, or service names. + +### Warn + +- Low-confidence image-text match. +- Uncertain sensitive-word context. +- Weak platform fit. +- Overly promotional or low-density paragraphs. + +### Auto Fix + +- Body grammar. +- Useless content. +- Third-party voice when platform is official site. + +## Data Model + +The first version uses local SQLite plus an export folder. + +```text +data/ + app.db + exports/ + job_xxx/ + original.md + optimized.md + optimized.docx + qa_report.json +``` + +### `brand_template` + +Reusable confirmed brand facts. + +```json +{ + "id": "brand_xxx", + "brand_name": "Brand", + "company_full_name": "Company Ltd.", + "company_short_names": ["Company"], + "product_names": ["Product"], + "target_industries": ["GEO optimization"], + "target_audience": ["Marketing teams"], + "verified_claims": ["More than ten years of industry experience"], + "forbidden_claims": ["Do not claim industry first without proof"], + "tone_rules": { + "official_site": "brand first-person or official voice", + "media": "objective third-party voice" + }, + "updated_at": "2026-06-16T10:00:00+08:00" +} +``` + +### `article_job` + +One optimization task. + +```json +{ + "id": "job_xxx", + "brand_template_id": "brand_xxx", + "source_title": "Original title", + "source_body": "Original body", + "image_inputs": [ + { + "type": "description", + "content": "Product dashboard screenshot" + } + ], + "publish_platform": "official_site", + "status": "qa_failed", + "created_at": "2026-06-16T10:05:00+08:00" +} +``` + +### `fact_card` + +Confirmed facts for one job. + +```json +{ + "job_id": "job_xxx", + "source": "auto_extract_then_user_confirmed", + "company_full_name": "Company Ltd.", + "product_names": ["Product"], + "target_industry": "GEO optimization", + "publish_intent": "official article", + "locked_claims": ["More than ten years of industry experience"], + "uncertain_items": [], + "confirmed_by_user": true +} +``` + +### `optimized_article` + +One revision of optimized content. + +```json +{ + "job_id": "job_xxx", + "revision": 2, + "title": "Optimized title", + "summary": "Optimized summary", + "body_markdown": "Optimized body in Markdown", + "image_suggestions": [ + { + "source": "image_1", + "suggestion": "Use product dashboard screenshot; avoid unrelated people photos" + } + ], + "changed_sections": ["title", "first paragraph"] +} +``` + +### `qa_report` + +Quality checks for one revision. + +```json +{ + "job_id": "job_xxx", + "revision": 2, + "overall_status": "warn", + "checks": [ + { + "rule_id": "hallucination_risk", + "status": "pass", + "evidence": "No new unsupported factual claims found", + "reason": "All factual claims are traceable to the confirmed fact card", + "target_agent": null + } + ] +} +``` + +## Error Handling + +### Fact Extraction + +Optimization is disabled until the user resolves uncertain facts. + +Examples: + +- Only a company short name is found. +- Multiple product names appear. +- Multiple experience-year claims appear. +- Target industry is unclear. +- Image description is missing. + +### QA Failure + +Hard failures block export. Warnings allow export with visible confirmation prompts. + +Failed checks trigger targeted rewrite for up to two rounds. After two failed rounds, the app stops rewriting and shows manual review fields. + +## Acceptance Criteria + +The MVP is complete when: + +1. User can paste title, body, image descriptions, and target platform. +2. System can extract a fact card and require user confirmation. +3. Confirmed fact card can be saved and reused as a local brand template. +4. System can generate an optimized article without changing confirmed facts. +5. System can generate a structured QA report for the 10 quality gates. +6. Hard failures block export until fixed or manually reviewed. +7. User can download Markdown and a basic Word document. + +## Minimum Test Samples + +Prepare at least five sample articles: + +1. Industry drift sample. +2. Incorrect or incomplete company name sample. +3. Title grammar sample. +4. Conflicting experience-year sample. +5. Image-text mismatch sample. + +These samples cover the most important risks from the source document and keep the first validation loop focused.