planet/docs/plans/ai-prompt-settings-task-registry-plan.md

AI Prompt Settings and Task Registry Plan

Summary

Add an AI prompt settings tab under the operations AI settings page. Operators can select a business AI task from a dropdown, edit its prompt, save the override, and reset it back to the shipped default. Runtime LLM calls must resolve prompts through a task registry instead of embedding large prompt blocks at each call site.

Default prompts are shipped as versioned resource data, not scattered business-code literals. Business services reference stable task keys, and the runtime resolves the effective prompt from the database override first, then the shipped default resource.

Key Changes

• Add a backend task prompt registry with stable keys, labels, groups, versions, default system prompts, and default task prompts.
• Store operator overrides in the existing SystemSetting table under an ai_prompts category. Store only custom overrides; defaults remain in the versioned prompt resource.
• Add settings APIs:
  • GET /api/v1/settings/ai-prompts
  • PUT /api/v1/settings/ai-prompts/{task_key}
  • POST /api/v1/settings/ai-prompts/{task_key}/reset
• Migrate business LLM entrypoints to resolve prompts by task key. aiprovider remains a pure model adapter and does not inject business prompts.
• Add a “提示词” tab to /ai. The tab shows a grouped task dropdown, current/default prompt status, editable prompt fields, save, and reset-to-default controls.

Initial Tasks

• earth.news.enrich — Earth news localization and location enrichment.
• alerts.brief — system alert AI brief.
• alerts.situational.brief — situational alert AI brief.
• bgp.brief — BGP AI brief.
• location.factcheck.normalize — location factcheck normalization.
• location.factcheck.resolve — location factcheck fallback resolution.
• datasource.mapping — datasource mapping DSL generation.
• credential.guide — credential guide generation.
• ai.connection_test — AI provider connection test.

Playground and public free-form analyze endpoints stay caller-controlled and are not shown in the prompt settings dropdown.

Test Plan

• Backend uses uv:
  • uv run pytest tests/test_settings_ai_prompts.py
  • uv run pytest tests/test_earth_news.py
  • uv run pytest tests/test_api.py
• Frontend uses bun:
  • cd frontend && bun run build
• Manual checks:
  • Prompt dropdown switches task content correctly.
  • Save persists an override and runtime calls use it.
  • Reset deletes the override and restores the shipped default.
  • Alert prompts do not leak into news, BGP, datasource, or location tasks.

Assumptions

• This iteration does not add prompt history, approval workflows, A/B testing, or per-user prompt variants.
• Strict JSON tasks may fail validation if an operator edits away the output contract; existing task-specific failure and retry behavior remains responsible for recovery.
• The UI stays Chinese-only in this iteration.