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.
@@ -117,6 +117,30 @@ flowchart LR
  E -->|pass/warn| G["Exporter"]
 ```

+### LLM Provider Integration
+
+Workflow nodes use a local LLM client abstraction instead of calling a vendor API directly. The first implementation uses DeepSeek by default, while keeping the provider boundary open for later OpenAI-compatible providers.
+
+Environment variables:
+
+```text
+LLM_PROVIDER=deepseek
+DEEPSEEK_API_KEY=
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+DEEPSEEK_MODEL=deepseek-v4-pro
+DEEPSEEK_THINKING=disabled
+```
+
+Rules:
+
+- `src/lib/llm/client.ts` exposes `generateText`, `generateJson<T>`, `isLlmConfigured`, and `getLlmProviderStatus`.
+- `LLM_PROVIDER` defaults to `deepseek` when unset.
+- DeepSeek is accessed through the OpenAI-compatible SDK with `baseURL` set to `https://api.deepseek.com`.
+- `generateJson<T>` must use JSON output mode and prompts that explicitly require valid JSON only.
+- Thinking mode is disabled by default for deterministic article rewrites and structured QA output.
+- Missing credentials use deterministic local fallbacks so the MVP remains testable and usable without a live API key.
+- Provider errors are normalized inside the LLM client before they reach workflow nodes or API routes.
+
 ### InputNormalizer

 Purpose: normalize page input into clean structured data.