docs: add local mvp runbook

2026-06-21 23:42:37 +08:00
parent 97485aa4e9
commit 489f6604bb
2 changed files with 96 additions and 0 deletions
@@ -0,0 +1,72 @@
+# GEO Agent Article Optimizer
+
+Local MVP for optimizing pasted GEO-related articles while preserving confirmed
+brand facts. The app extracts a fact card, requires user confirmation, rewrites
+under those constraints, runs QA gates, and exports Markdown, Word, and JSON.
+
+## Setup
+
+```bash
+npm install
+cp .env.example .env.local
+npm run dev
+```
+
+Open `http://localhost:3000`.
+
+## Environment
+
+Required for live model calls:
+
+```text
+LLM_PROVIDER=deepseek
+DEEPSEEK_API_KEY=
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DEEPSEEK_MODEL=deepseek-v4-pro
+DEEPSEEK_THINKING=disabled
+APP_DATA_DIR=./data
+```
+
+OpenAI-compatible fallback keys are also accepted:
+
+```text
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4.1-mini
+```
+
+When no API key is configured, deterministic local fallbacks keep the workflow
+usable for tests and local review.
+
+## Commands
+
+```bash
+npm test
+npm run build
+npx playwright test
+```
+
+## Exports
+
+Generated files are written under:
+
+```text
+data/exports/<job_id>/
+```
+
+Each passing or warning-only QA run can produce:
+
+- `optimized.md`
+- `optimized.docx`
+- `qa_report.json`
+
+Hard QA failures block export.
+
+## MVP Limits
+
+- Pasted text only; no direct `.docx` parsing.
+- Local SQLite storage only.
+- No account permissions or collaboration.
+- No publishing platform APIs.
+- No batch queue.
+- Basic Word export layout only.
+- Unconfirmed facts are never used as truth.