> **产品：** Knowledge Base Reliability Stack
> **版本：** v1
> **生成时间：** 2026-05-11 09:54
> **数据来源：** ai-customer-support-automation__scored-demand__20260511-0918.md（Score: 29/40 BUILD）

# PRD — Knowledge Base Reliability Stack

## 1. Problem & User

**Target User:** Support operations managers and support systems architects responsible for AI knowledge quality across help centers and internal documentation at SaaS companies.

**Core Problem:** AI support answers degrade silently when product changes aren't reflected in the knowledge base. Teams don't know which docs are stale, which retrieval queries are returning wrong results, or when a recent release broke their AI's answer accuracy. Manual QA is expensive and inconsistent; existing platforms (Zendesk, Intercom, Guru) don't offer standalone retrieval quality monitoring.

**User Quote:** "发现知识库维护是最大负担" (Maintaining the knowledge base is the biggest burden)

## 2. Target Outcome & KPIs

- **Primary:** Support ops teams catch stale/conflicting docs before AI quality degrades in production
- **KPIs:**
  - First stale doc alert delivered within 24 hours of onboarding
  - Retrieval test pass rate tracked and trending upward week-over-week
  - Activation: user defines first test query set within 10 minutes
  - Paywall trigger: 25 test queries exhausted

## 3. MVP Scope (In)

- Connect one knowledge source via sitemap URL or manual URL paste
- Daily cron: re-fetch pages, compute content hash diff, flag changed/stale pages
- Test query set: user defines 5–25 critical support questions mapped to expected doc URLs
- Scheduled retrieval test: nightly run checks if expected doc appears in top-3 results
- Alert dashboard: pass/fail per query, stale page list, conflict detection (two pages with contradicting answers on same topic)
- Changelog/release feed: optional RSS/Atom parser to flag likely impacted articles
- Stripe: free (1 KB + 25 queries), paid $49/mo (3 KBs + 100 queries)

## 4. Out of Scope

- Custom LLM or embedding model training
- Native integrations with Linear/Jira/GitHub (MVP: RSS/Atom feed parsing only)
- Multi-team or enterprise access controls
- Real-time monitoring (MVP: daily batch only)
- Auto-updating or rewriting stale docs

## 5. User Flow (Happy Path)

1. **Sign up** → empty workspace dashboard
2. **Add knowledge source:** paste sitemap URL (e.g., `help.myapp.com/sitemap.xml`) → system crawls and indexes pages (< 5 min for typical 50-page help center)
3. **Aha Moment (10 min):** Navigate to "Test Queries" → type a critical support question (e.g., "How do I reset my password?") → map to expected article URL → click "Run Test Now" → see PASS/FAIL with matched article and confidence rank
4. **Build query set:** Add 5–10 more critical questions → save
5. **Stale docs alert:** Next day, dashboard shows pages with content hash changes flagged in red → click to see diff summary
6. **Optional changelog sync:** Paste RSS feed URL from product changelog → system flags help articles likely impacted by recent release notes
7. **Paid wall trigger:** On 26th test query → upgrade banner + automated email sequence

## 6. Functional Requirements (P0)

| ID | Requirement |
|----|-------------|
| F1 | User can connect knowledge source via sitemap URL; system crawls and stores page content |
| F2 | Daily cron re-fetches pages and flags changed (hash diff) and stale (not updated in 30+ days) |
| F3 | User can define test queries (question → expected URL mapping), min 1, max 25 on free |
| F4 | On-demand and nightly retrieval test: checks if expected URL appears in top-3 pgvector results |
| F5 | Dashboard shows per-query PASS/FAIL history over last 7 days |
| F6 | Conflict detection: flag any two pages with high semantic overlap on same topic keyword |
| F7 | Optional RSS parser: ingest changelog feed, surface entries next to potentially affected pages |
| F8 | Stripe checkout + email trigger at 25-query limit |
| F9 | Onboarding empty states guide user through: source → test query → first run, no human needed |

## 7. Data Model (Minimal)

```
workspaces (id, name, owner_id, plan, query_count)
knowledge_sources (id, workspace_id, sitemap_url, last_crawled_at)
pages (id, source_id, url, title, content_hash, last_fetched_at, flagged_stale, chunks[])
test_queries (id, workspace_id, question, expected_url, embedding)
test_runs (id, query_id, run_at, top_results[], passed, confidence_rank)
changelog_feeds (id, workspace_id, rss_url, last_entry_at)
```

## 8. API / Integration Notes

- **Crawler:** Node.js `cheerio` for sitemap parsing + page fetch; respect `robots.txt`
- **Embeddings:** OpenAI `text-embedding-3-small`; stored in Supabase pgvector
- **Retrieval:** pgvector cosine similarity; PASS if expected URL in top-3 results at cosine ≥ 0.75
- **Conflict detection:** flag page pairs with cosine > 0.92 on same keyword cluster
- **Cron:** Vercel Cron or Supabase pg_cron for daily batch (00:00 UTC)
- **RSS parser:** `rss-parser` npm package; store entries in Supabase; match by keyword overlap to pages
- **Auth:** Supabase Auth
- **Payments:** Stripe Checkout; webhook updates `workspaces.plan`
- **Email:** Resend for paywall + weekly digest of stale/failed alerts

## 9. Acceptance Criteria

- [ ] Sitemap of 50 pages crawled and indexed in < 5 minutes
- [ ] `POST /api/test-queries/{id}/run` returns `{passed, rank, top_results[3]}` in < 3 seconds
- [ ] Daily cron correctly identifies pages with changed content hash (verified with a test page edit)
- [ ] Conflict detection surfaces pages with > 90% semantic overlap in UI
- [ ] Stripe checkout flow completes; plan upgrades immediately on `customer.subscription.created` webhook
- [ ] 26th test query blocked on free tier with upgrade prompt visible
- [ ] Onboarding completed end-to-end without external documentation

## 10. Delivery Plan

### Milestone 1 — Crawl + Index + Test Core (Hours 1–8)
**Files:**
- `lib/crawler.ts` — sitemap fetch, page scraping, content hash computation
- `lib/embeddings.ts` — OpenAI embedding wrapper with batching
- `supabase/migrations/001_schema.sql` — all tables
- `app/api/sources/route.ts` — CRUD for knowledge sources + trigger crawl
- `app/api/test-queries/route.ts` — CRUD for test query definitions
- `app/api/test-queries/[id]/run/route.ts` — on-demand retrieval test runner

**Rationale:** The crawl-index-test loop is the entire product value prop; must be solid before adding dashboards.

**Exit Criteria:** `POST /api/test-queries/{id}/run` returns correct PASS/FAIL against a real help center URL; pgvector returns expected doc in top-3 when query is semantically related.

### Milestone 2 — Monitoring Dashboard + Alerts (Hours 9–15)
**Files:**
- `app/dashboard/page.tsx` — stale pages list, conflict flags, query health overview
- `app/queries/page.tsx` — test query management with PASS/FAIL history chart
- `app/api/cron/daily-check/route.ts` — batch re-fetch + hash diff + retrieval test runner
- `lib/conflict-detector.ts` — pairwise cosine similarity for conflict detection
- `lib/rss-parser.ts` — RSS/Atom changelog ingestion
- `app/api/changelogs/route.ts` — changelog feed CRUD

**Rationale:** Dashboard turns raw data into actionable ops workflow; conflict detection and changelog sync are the key differentiators.

**Exit Criteria:** Daily cron correctly flags edited pages as changed; dashboard shows stale pages in red; conflict detection surfaces at least one overlapping page pair in a test knowledge base.

### Milestone 3 — Monetization & Onboarding (Hours 16–20)
**Files:**
- `app/api/stripe/webhook/route.ts` — plan sync
- `app/billing/page.tsx` — upgrade flow
- `app/onboarding/page.tsx` — step-by-step wizard (source → query → run)
- `lib/email.ts` — Resend: paywall email, weekly stale alert digest

**Rationale:** Paywall and onboarding must ship before launch to capture revenue signal immediately.

**Exit Criteria:** Free tier blocks 26th query with upgrade prompt; Stripe test checkout completes and plan updates; weekly digest email renders correctly in test inbox.

## 11. Risks & Mitigations

| Risk | Mitigation |
|------|-----------|
| Help center sites block crawlers | Add configurable User-Agent + crawl delay; allow manual URL paste as fallback |
| Conflict detection has too many false positives | Start with high threshold (> 0.92); let user dismiss false positives |
| Cron job misses runs on Vercel free tier | Use Supabase pg_cron as fallback; log every run with status |
| Small knowledge bases make product feel less valuable | Show "coverage score" even for small KBs — always surface actionable next step |

## 12. Chargeability Rationale

**Free:** 1 knowledge base + 25 test queries — enough to prove retrieval quality monitoring value for a small help center.

**Paid ($49/mo):** 3 knowledge bases + 100 test queries + changelog feed integrations + 90-day history retention + weekly digest email.

**Paywall Trigger:** 26th test query definition — user has built a meaningful monitoring suite and is operationally dependent on it.

**Why teams pay:** A stale knowledge base causing wrong AI support answers costs more in churn and agent escalation time than $49/month. This is pure cost avoidance ROI.