release: bump version to 0.28.1

2026-04-20 15:14:53 +08:00
parent 4c21973197
commit 75cb214f23
42 changed files with 8556 additions and 89 deletions
--- a/docs/agents/agent-architecture-plan.md
+++ b/docs/agents/agent-architecture-plan.md
@@ -0,0 +1,647 @@
+# Agent Architecture Plan
+
+## Overview
+
+This document defines the agent architecture for Planet.
+
+The architecture is intentionally broader than datasource health checking.
+
+It is designed to support both:
+
+- datasource health governance
+- future situational-awareness workflows
+
+The core idea is to avoid building a one-off "repair broken API links" agent.
+
+Instead, Planet should grow a reusable agent runtime that can:
+
+- collect evidence
+- evaluate signals
+- reason over incomplete information
+- generate proposals
+- produce assessments
+- execute limited actions under policy
+
+
+## Design Goal
+
+Build an agent foundation that can evolve in this order:
+
+1. datasource health checks
+2. datasource repair proposals
+3. signal correlation
+4. situational assessments
+5. controlled runtime actions
+
+This means the architecture should treat datasource health as one use case of the larger agent system, not as the whole system.
+
+
+## Core Principles
+
+1. Separate evidence from reasoning
+
+- raw signals should be gathered first
+- deterministic checks should run before LLM reasoning
+
+2. Agents do not own the defaults
+
+- repository defaults remain human-owned
+- agents operate on runtime state, proposals, and overrides
+
+3. Reasoning and action are different responsibilities
+
+- many agents should be read-only or propose-only
+- only tightly controlled flows may apply changes
+
+4. Shared runtime, specialized roles
+
+- multiple agent roles should share the same object model and orchestration patterns
+- health and situational-awareness agents should not invent incompatible payloads
+
+5. Auditability is mandatory
+
+- every proposal, assessment, and applied action should be attributable
+
+
+## System Layers
+
+Planet agent architecture should be split into four layers.
+
+### 1. Signal Layer
+
+Purpose:
+
+- gather raw evidence from internal and external systems
+
+Example sources:
+
+- collector outputs
+- datasource health checks
+- logs
+- snapshots
+- alerts
+- web search results
+- scraped pages
+- external APIs
+- operator inputs
+
+Responsibilities:
+
+- fetch
+- normalize
+- timestamp
+- tag with source and trust level
+
+This layer should not make high-level judgments.
+
+
+### 2. Evaluation Layer
+
+Purpose:
+
+- perform deterministic analysis
+
+Examples:
+
+- reachability checks
+- schema validation
+- threshold checks
+- time-window comparisons
+- anomaly counters
+- completeness checks
+
+Responsibilities:
+
+- classify signals into machine-readable findings
+- attach deterministic evidence
+
+This layer should avoid LLM dependency whenever possible.
+
+
+### 3. Reasoning Layer
+
+Purpose:
+
+- use LLMs when semantic interpretation or incomplete-information reasoning is needed
+
+Examples:
+
+- endpoint migration inference
+- multi-source event correlation
+- causality hypotheses
+- ambiguity reduction
+- assessment narrative generation
+- action recommendation generation
+
+Responsibilities:
+
+- synthesize evidence
+- produce hypotheses
+- rank confidence
+- explain reasoning boundaries
+
+This is the main place where `aiprovider` and web search are used.
+
+
+### 4. Action Layer
+
+Purpose:
+
+- convert proposals or assessments into controlled system actions
+
+Examples:
+
+- create runtime override
+- create proposal
+- publish alert
+- update operator task queue
+- generate summary artifact
+- trigger follow-up verification
+
+Responsibilities:
+
+- enforce policy
+- enforce approval requirements
+- verify post-action outcomes
+- record audit trails
+
+
+## Architecture Sketch
+
+```mermaid
+flowchart TD
+    A["Collectors / Logs / Snapshots / External APIs"] --> B["Signal Layer"]
+    W["Web Search / Page Fetch / Docs"] --> B
+    B --> C["Evaluation Layer"]
+    C --> D["Findings"]
+    D --> E["Reasoning Layer (LLM + Tools)"]
+    E --> F["Proposals"]
+    E --> G["Assessments"]
+    F --> H["Action Layer"]
+    H --> I["Runtime Overrides / Alerts / Tasks"]
+    H --> J["Verification Loop"]
+    J --> B
+
+    K["Policy Engine"] --> H
+    L["Audit / History Store"] --> H
+    L --> E
+    L --> C
+```
+
+
+## Agent Roles
+
+The first version should define these logical roles.
+
+### 1. Health Agent
+
+Primary use case:
+
+- datasource health governance
+
+Inputs:
+
+- datasource metadata
+- current endpoint
+- latest health records
+- latest failures
+- deterministic findings
+
+Outputs:
+
+- health interpretation
+- repair proposal
+- confidence
+- evidence references
+
+Typical action level:
+
+- propose-only
+
+
+### 2. Correlation Agent
+
+Primary use case:
+
+- identify whether multiple signals describe the same event or related events
+
+Inputs:
+
+- findings from multiple collectors
+- time windows
+- region / ASN / prefix / cable relationships
+- prior incidents
+
+Outputs:
+
+- grouped event candidates
+- correlation rationale
+- confidence per relationship
+
+Typical action level:
+
+- read-only
+
+
+### 3. Assessment Agent
+
+Primary use case:
+
+- produce situational-awareness outputs
+
+Inputs:
+
+- grouped events
+- findings
+- current context
+- historical context
+- operator constraints
+
+Outputs:
+
+- structured assessment
+- risk summary
+- evidence-backed recommendations
+- missing-information list
+
+Typical action level:
+
+- read-only or propose-only
+
+
+### 4. Recovery Agent
+
+Primary use case:
+
+- carry low-risk proposals into controlled runtime actions
+
+Inputs:
+
+- approved proposal
+- policy constraints
+- trusted-domain rules
+- verification checks
+
+Outputs:
+
+- applied override
+- failed application
+- rollback request
+
+Typical action level:
+
+- apply-limited
+
+
+## Shared Object Model
+
+All agents should work on a shared object model.
+
+That prevents the health subsystem and situational-awareness subsystem from drifting into incompatible payloads.
+
+### Signal
+
+Represents a raw observed fact.
+
+Examples:
+
+- a datasource returned HTTP 404
+- a collector returned empty results
+- BGP updates spiked in one region
+- a known endpoint now redirects elsewhere
+
+Suggested shape:
+
+```json
+{
+  "id": "sig_123",
+  "type": "datasource.http_failure",
+  "source": "ris_live_bgp",
+  "occurred_at": "2026-04-08T10:00:00Z",
+  "severity": "medium",
+  "payload": {},
+  "trust": 0.95
+}
+```
+
+
+### Finding
+
+Represents a deterministic or semi-deterministic interpretation of one or more signals.
+
+Examples:
+
+- `schema_changed`
+- `endpoint_unreachable`
+- `data_volume_abnormally_low`
+- `event_cluster_detected`
+
+Suggested shape:
+
+```json
+{
+  "id": "find_123",
+  "type": "datasource.schema_changed",
+  "source_ids": ["sig_123"],
+  "confidence": 0.92,
+  "evidence": [],
+  "details": {}
+}
+```
+
+
+### Proposal
+
+Represents a recommended action, not an already-applied action.
+
+Examples:
+
+- switch endpoint to new URL
+- disable bad override
+- escalate issue for manual review
+
+Suggested shape:
+
+```json
+{
+  "id": "prop_123",
+  "kind": "endpoint_override",
+  "target": "telegeography_cables",
+  "confidence": 0.84,
+  "reason": "Official docs now point to a new API path",
+  "payload": {},
+  "evidence_urls": [],
+  "status": "proposed"
+}
+```
+
+
+### Assessment
+
+Represents a structured situational-awareness output for operators or downstream systems.
+
+Examples:
+
+- current network posture summary
+- incident impact assessment
+- risk and response recommendations
+
+Suggested shape:
+
+```json
+{
+  "id": "assess_123",
+  "scope": "regional-network",
+  "risk_level": "high",
+  "summary": "Regional routing instability is increasing.",
+  "key_risks": [],
+  "evidence": [],
+  "recommendations": [],
+  "missing_data": []
+}
+```
+
+
+## State Machine
+
+The shared orchestration flow should look like this:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Collect
+    Collect --> Validate
+    Validate --> Classify
+    Classify --> Reason
+    Reason --> Propose
+    Reason --> Assess
+    Propose --> Review
+    Review --> Apply
+    Apply --> Verify
+    Verify --> Archive
+    Assess --> Archive
+    Archive --> [*]
+```
+
+Definitions:
+
+- `Collect`: gather signals
+- `Validate`: run deterministic checks
+- `Classify`: create findings
+- `Reason`: invoke LLM reasoning when needed
+- `Propose`: create change proposals
+- `Review`: policy or human approval
+- `Apply`: perform limited runtime action
+- `Verify`: confirm action effect
+- `Archive`: store artifacts and decisions
+
+
+## Permission Model
+
+Each agent role should be assigned one of these action levels.
+
+### `read-only`
+
+Allowed:
+
+- read signals
+- search web
+- fetch pages
+- read internal state
+- generate findings and assessments
+
+Not allowed:
+
+- mutate config
+- write overrides
+- change live runtime behavior
+
+
+### `propose-only`
+
+Allowed:
+
+- everything in `read-only`
+- create proposals
+- create review tasks
+
+Not allowed:
+
+- apply live changes
+
+
+### `apply-limited`
+
+Allowed:
+
+- everything in `propose-only`
+- write approved runtime overrides
+- trigger verification checks
+
+Not allowed:
+
+- mutate repository defaults
+- make destructive data changes
+- bypass policy engine
+
+
+## Runtime Components
+
+The first durable architecture should introduce these components.
+
+### 1. Signal Store
+
+Stores normalized evidence and health outputs.
+
+
+### 2. Finding Store
+
+Stores deterministic classifications that can be reused by multiple agents.
+
+
+### 3. Proposal Store
+
+Stores recommended actions with evidence and confidence.
+
+
+### 4. Assessment Store
+
+Stores structured situational-awareness outputs.
+
+
+### 5. Policy Engine
+
+Decides:
+
+- whether agent may run
+- whether proposal requires review
+- whether proposal may auto-apply
+- whether post-apply verification passed
+
+
+### 6. Override Store
+
+Stores runtime-only configuration changes.
+
+This is where endpoint repairs should live.
+
+
+## Relation To `aiprovider`
+
+`aiprovider` should remain the model gateway.
+
+It should not become the full agent runtime.
+
+Recommended split:
+
+- `aiprovider`
+  - provider adaptation
+  - prompt transport
+  - model execution
+  - protocol compatibility
+
+- agent runtime
+  - orchestration
+  - signal handling
+  - tool selection
+  - proposal generation
+  - policy and audit
+
+This keeps provider concerns and agent behavior concerns separate.
+
+
+## Relation To Datasource Health
+
+Datasource health becomes one vertical slice of this architecture.
+
+Mapping:
+
+- signal:
+  - endpoint unreachable
+  - schema mismatch
+  - bad content type
+- finding:
+  - `failed`
+  - `schema_changed`
+  - `moved_endpoint_suspected`
+- proposal:
+  - runtime override suggestion
+- assessment:
+  - datasource health summary for operators
+
+
+## Relation To Situational Awareness
+
+Future situational-awareness capabilities should reuse the same flow:
+
+- raw telemetry becomes signals
+- anomaly detection becomes findings
+- LLM correlation becomes reasoning
+- operator-facing output becomes assessments
+- policy-approved mitigations become actions
+
+This lets the platform evolve from operational health governance into broader cyber/network posture workflows without changing the architecture.
+
+
+## Suggested Delivery Sequence
+
+### Phase A
+
+- finalize shared object model
+- implement health-oriented signal and finding storage
+
+### Phase B
+
+- implement Health Agent
+- generate proposals only
+
+### Phase C
+
+- implement Assessment Agent
+- expose structured assessments via API
+
+### Phase D
+
+- implement Correlation Agent
+- support multi-source incident grouping
+
+### Phase E
+
+- implement Recovery Agent with policy-gated runtime actions
+
+
+## Recommended First Build
+
+The first build should not try to implement every agent role.
+
+Recommended initial slice:
+
+- shared object model
+- health signals
+- health findings
+- Health Agent
+- proposal generation only
+
+This gives immediate value while preserving the longer-term architecture.
+
+
+## Non-Goals For The First Iteration
+
+- repository YAML auto-rewrites
+- unrestricted autonomous action
+- full incident graph reasoning
+- automatic large-scale remediation
+- agent-owned configuration source of truth
+
+
+## Summary
+
+Planet should treat agents as a reusable runtime for evidence, reasoning, proposals, and assessments.
+
+The datasource health use case is the first practical entrypoint, but the architecture should already assume future situational-awareness expansion.
+
+The safest path is:
+
+- deterministic checks first
+- agent reasoning second
+- proposals before actions
+- runtime overrides instead of default mutation
--- a/docs/agents/agent-runtime-roadmap.md
+++ b/docs/agents/agent-runtime-roadmap.md
@@ -0,0 +1,346 @@
+# Agent Runtime Roadmap
+
+## Overview
+
+This document connects three existing planning threads into one implementation roadmap:
+
+- `aiprovider` as the model gateway
+- datasource health governance as the first practical agent use case
+- situational awareness as the broader long-term target
+
+Related documents:
+
+- [aiprovider](/home/ray/dev/linkong/planet/docs/agents/aiprovider.md)
+- [datasource-health-plan](/home/ray/dev/linkong/planet/docs/agents/datasource-health-plan.md)
+- [agent-architecture-plan](/home/ray/dev/linkong/planet/docs/agents/agent-architecture-plan.md)
+
+
+## Big Picture
+
+Planet should evolve in layers:
+
+1. stable model gateway
+2. deterministic health and evidence collection
+3. agent runtime for reasoning and proposal generation
+4. situational-awareness assessments and controlled actions
+
+This prevents the system from collapsing into a single giant "AI feature" with unclear boundaries.
+
+
+## Architecture Overview
+
+```mermaid
+flowchart TD
+    U["Frontend / Backend APIs / Operators"] --> B["Planet Backend"]
+    B --> H["Datasource Health Services"]
+    B --> R["Agent Runtime"]
+    R --> P["aiprovider"]
+    P --> M["OpenAI / Anthropic / MiniMax / Ollama / Local Models"]
+
+    C["Collectors / Snapshots / Logs / Alerts / BGP Signals"] --> S["Signal Store"]
+    H --> S
+    S --> E["Evaluation Layer"]
+    E --> F["Findings"]
+    F --> R
+
+    W["Web Search / Page Fetch / Docs Fetch"] --> R
+    R --> PR["Proposals"]
+    R --> AS["Assessments"]
+
+    PR --> O["Runtime Overrides / Review Queue / Tasks"]
+    AS --> SA["Situational Awareness APIs / UI"]
+
+    O --> V["Verification Loop"]
+    V --> S
+```
+
+
+## Role Boundaries
+
+### `aiprovider`
+
+Responsibilities:
+
+- provider compatibility
+- protocol adaptation
+- auth and model transport
+- request/response normalization
+
+Not responsible for:
+
+- agent orchestration
+- business workflows
+- datasource repair policy
+- situational-awareness domain logic
+
+
+### Backend
+
+Responsibilities:
+
+- stable business APIs
+- auth and permissions
+- task orchestration
+- health records
+- proposal and override persistence
+- assessment exposure
+
+
+### Agent Runtime
+
+Responsibilities:
+
+- consume findings and context
+- invoke LLMs via `aiprovider`
+- invoke tools such as web search
+- create proposals
+- create assessments
+- route to policy-controlled action paths
+
+
+## Delivery Sequence
+
+## Stage 1: Gateway Foundation
+
+Status:
+
+- already in place
+
+Delivered by current work:
+
+- `aiprovider`
+- multi-provider compatibility
+- backend AI facade
+- MiniMax / Anthropic-compatible support
+- request-id propagation
+
+Primary outcome:
+
+- the system already has a stable way to call models
+
+
+## Stage 2: Datasource Health MVP
+
+Goal:
+
+- establish deterministic health observability
+
+Key work:
+
+- health check task runner
+- health result table
+- datasource health APIs
+- UI visibility
+- collector endpoint override precedence cleanup
+
+Primary outcome:
+
+- Planet knows which collectors are healthy before asking an LLM anything
+
+
+## Stage 3: Health Agent
+
+Goal:
+
+- let the first agent role operate on health failures
+
+Key work:
+
+- convert health failures into signals/findings
+- invoke agent only for failed or suspicious cases
+- produce repair proposals with evidence and confidence
+
+Primary outcome:
+
+- Planet can suggest endpoint repairs without mutating defaults
+
+
+## Stage 4: Runtime Repair Application
+
+Goal:
+
+- safely apply approved datasource repair proposals
+
+Key work:
+
+- override storage
+- policy-gated apply flow
+- verification after apply
+- rollback path
+
+Primary outcome:
+
+- datasource repair becomes operationally useful without polluting repository defaults
+
+
+## Stage 5: Situational Awareness Assessments
+
+Goal:
+
+- reuse the same runtime for broader operator-facing assessment
+
+Key work:
+
+- normalize telemetry and incident evidence into signals/findings
+- build Assessment Agent
+- expose structured assessments through backend APIs and UI
+
+Primary outcome:
+
+- LLM output becomes evidence-backed situational summary, not just ad hoc chat output
+
+
+## Stage 6: Correlation and Controlled Actions
+
+Goal:
+
+- connect multiple sources into higher-level posture and event groupings
+
+Key work:
+
+- event correlation
+- incident grouping
+- recommendation scoring
+- controlled action routing
+
+Primary outcome:
+
+- Planet becomes a true agent-assisted situational-awareness system
+
+
+## Implementation Tracks
+
+These tracks can progress in parallel, but they should stay loosely coupled.
+
+### Track A: Config and Runtime Resolution
+
+Scope:
+
+- datasource defaults
+- overrides
+- runtime precedence
+- audit trails
+
+First milestone:
+
+- health-safe override layer
+
+
+### Track B: Health and Evidence
+
+Scope:
+
+- deterministic checks
+- failure categorization
+- signal and finding persistence
+
+First milestone:
+
+- datasource health record system
+
+
+### Track C: Agent Runtime
+
+Scope:
+
+- shared object model
+- orchestration flow
+- prompt/tool pipeline
+- policy integration
+
+First milestone:
+
+- Health Agent proposal pipeline
+
+
+### Track D: Situational Awareness
+
+Scope:
+
+- assessment schema
+- multi-source context assembly
+- operator-facing outputs
+
+First milestone:
+
+- structured assessment API
+
+
+## Shared Artifacts
+
+To avoid fragmentation, these artifacts should be shared across all future agent work.
+
+### Shared object model
+
+- `Signal`
+- `Finding`
+- `Proposal`
+- `Assessment`
+
+### Shared orchestration flow
+
+- collect
+- validate
+- classify
+- reason
+- propose or assess
+- review or apply
+- verify
+- archive
+
+### Shared policy model
+
+- read-only
+- propose-only
+- apply-limited
+
+
+## Recommended Next Concrete Steps
+
+1. Build Stage 2 first
+
+- datasource health records
+- deterministic checks
+- no automatic repair
+
+2. Then build Stage 3
+
+- Health Agent
+- proposal generation only
+
+3. Then Stage 4
+
+- override apply flow
+- rollback and verification
+
+4. Only after that start Stage 5
+
+- broader situational-awareness assessment workflows
+
+
+## Why This Order
+
+Because situational-awareness quality depends on reliable upstream data.
+
+If datasource health is weak:
+
+- agent reasoning quality will degrade
+- false explanations will increase
+- assessment trust will drop
+
+So datasource health is not a side task.
+
+It is the first operational foundation for the later situational-awareness system.
+
+
+## Summary
+
+Planet should be built as:
+
+- `aiprovider` for model access
+- backend services for orchestration and persistence
+- datasource health as the first evidence-governance layer
+- agent runtime as the reusable reasoning core
+- situational awareness as the long-term application layer
+
+That path keeps the architecture coherent and lets each phase produce useful functionality without forcing a rewrite later.
--- a/docs/agents/aiprovider.md
+++ b/docs/agents/aiprovider.md
@@ -0,0 +1,333 @@
+# AI Provider Guide
+
+## Overview
+
+`aiprovider` is the model-adapter service for Planet.
+
+It isolates model-vendor details from the main backend so the rest of the system can call a stable business API:
+
+- Caller service -> `planet backend`
+- `planet backend` -> `aiprovider`
+- `aiprovider` -> concrete model provider
+
+The recommended default is:
+
+- External and cross-service callers use `planet backend`
+- Only infrastructure-grade internal jobs call `aiprovider` directly
+
+## Responsibilities
+
+`backend` is responsible for:
+
+- authentication and authorization
+- business-level request shaping
+- stable `/api/v1/ai/...` endpoints
+- internal service-to-service authentication toward `aiprovider`
+
+`aiprovider` is responsible for:
+
+- model protocol adaptation
+- provider selection by `.env`
+- timeout and lightweight retry
+- request tracing via `X-Request-ID`
+
+This now follows an OpenClaw-like seam:
+
+- `AI_PROVIDER` identifies the vendor or logical provider
+- `AI_PROVIDER_API` identifies the wire adapter
+
+That split makes MiniMax, Claude-compatible gateways, and self-hosted OpenAI-compatible services easier to model without overloading one config field.
+
+## Supported Providers
+
+`aiprovider` currently supports these provider identities:
+
+- `openai`
+- `anthropic`
+- `minimax`
+- `ollama`
+
+Supported request adapters:
+
+- `openai-completions`
+- `anthropic-messages`
+- `ollama-generate`
+
+Backward-compatible aliases still accepted:
+
+- `openai_compatible`
+- `anthropic_compatible`
+- `claude_compatible`
+
+Provider mapping:
+
+- `vLLM`, `LM Studio`, `One API`: `AI_PROVIDER=openai`, `AI_PROVIDER_API=openai-completions`
+- `MiniMax`: `AI_PROVIDER=minimax`, `AI_PROVIDER_API=anthropic-messages`
+- Claude-compatible gateways: `AI_PROVIDER=anthropic`, `AI_PROVIDER_API=anthropic-messages`
+- `Ollama`: `AI_PROVIDER=ollama`, `AI_PROVIDER_API=ollama-generate`
+
+## API Surfaces
+
+### Main backend API
+
+Preferred stable entrypoints:
+
+- `GET /api/v1/ai/provider/status`
+- `POST /api/v1/ai/situational-awareness/analyze`
+
+Authentication:
+
+- `Authorization: Bearer <jwt>`
+
+Optional tracing header:
+
+- `X-Request-ID: <caller-generated-id>`
+
+The backend will propagate `X-Request-ID` to `aiprovider` and return the same header in the response.
+
+### AI provider internal API
+
+Internal-only endpoints:
+
+- `GET /v1/provider/status`
+- `POST /v1/analyze`
+
+Authentication:
+
+- `X-Provider-Token: <shared-secret>`
+
+Optional tracing header:
+
+- `X-Request-ID: <caller-generated-id>`
+
+## Request Example
+
+### Call through backend
+
+```bash
+curl -X POST http://localhost:8000/api/v1/ai/situational-awareness/analyze \
+  -H "Authorization: Bearer <access_token>" \
+  -H "X-Request-ID: bgp-incident-20260407-001" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "BGP异常研判",
+    "objective": "总结当前风险并给出处置建议",
+    "observations": [
+      "collector A 在 5 分钟内出现多次 origin 变更",
+      "异常集中在同一地区前缀"
+    ],
+    "constraints": [
+      "不要编造不存在的数据",
+      "区分事实和推断"
+    ],
+    "context": {
+      "source": "bgp-monitor",
+      "severity": "high"
+    }
+  }'
+```
+
+### Call `aiprovider` directly
+
+```bash
+curl -X POST http://localhost:8010/v1/analyze \
+  -H "X-Provider-Token: change_me" \
+  -H "X-Request-ID: ai-batch-job-001" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "链路波动分析",
+    "objective": "给出简要态势摘要和下一步建议",
+    "observations": [
+      "多个节点出现延迟上升"
+    ],
+    "constraints": [
+      "不要假设根因已经确认"
+    ],
+    "context": {
+      "region": "APAC"
+    }
+  }'
+```
+
+## Response Shape
+
+Both backend and `aiprovider` return the same payload shape:
+
+```json
+{
+  "provider": "minimax",
+  "api": "anthropic-messages",
+  "model": "MiniMax-M2.7",
+  "content": "1) 态势摘要 ...",
+  "content_blocks": [],
+  "text_blocks": [],
+  "thinking_blocks": [],
+  "raw_response": {}
+}
+```
+
+Both services also return:
+
+- `X-Request-ID: <id>`
+
+## Configuration
+
+### Backend
+
+Recommended backend `.env`:
+
+```env
+AI_PROVIDER_SERVICE_URL=http://localhost:8010
+AI_PROVIDER_SERVICE_TOKEN=change_me
+AI_PROVIDER_TIMEOUT_SECONDS=60
+AI_PROVIDER_RETRY_ATTEMPTS=2
+```
+
+Reference file:
+
+- [backend/.env.example](/home/ray/dev/linkong/planet/backend/.env.example)
+
+### AI Provider
+
+Reference file:
+
+- [aiprovider/.env.example](/home/ray/dev/linkong/planet/aiprovider/.env.example)
+
+Frontend local reference:
+
+- [frontend/.env.example](/home/ray/dev/linkong/planet/frontend/.env.example)
+
+Common settings:
+
+```env
+SERVICE_NAME=planet-ai-provider
+SERVICE_VERSION=0.1.0
+AI_PROVIDER_SERVICE_TOKEN=change_me
+AI_TIMEOUT_SECONDS=60
+AI_HTTP_RETRY_ATTEMPTS=2
+AI_ANALYSIS_SYSTEM_PROMPT=你是态势感知分析助手。请基于输入的上下文、观测与约束，输出结构化、克制、可执行的分析。
+```
+
+### OpenAI-compatible example
+
+```env
+AI_PROVIDER=openai
+AI_PROVIDER_API=openai-completions
+AI_BASE_URL=http://127.0.0.1:8001/v1
+AI_API_KEY=local-key
+AI_MODEL=your-local-model
+```
+
+### MiniMax CN example
+
+```env
+AI_PROVIDER=minimax
+AI_PROVIDER_API=anthropic-messages
+AI_BASE_URL=https://api.minimaxi.com/anthropic
+AI_API_KEY=sk-cp-xxxxx
+AI_MODEL=MiniMax-M2.7
+AI_MAX_TOKENS=1200
+AI_ANTHROPIC_VERSION=2023-06-01
+```
+
+MiniMax note:
+
+- This follows the same Anthropic Messages request shape as the official MiniMax examples.
+- For MiniMax, `aiprovider` now disables `thinking` by default unless the caller explicitly passes a `thinking` object.
+- This mirrors OpenClaw's caution around MiniMax Anthropic-compatible behavior.
+
+### Anthropic-compatible example
+
+```env
+AI_PROVIDER=anthropic
+AI_PROVIDER_API=anthropic-messages
+AI_BASE_URL=https://your-claude-compatible-endpoint.example.com/anthropic
+AI_API_KEY=your_api_key
+AI_MODEL=your-model
+AI_MAX_TOKENS=1200
+AI_ANTHROPIC_VERSION=2023-06-01
+```
+
+### Ollama example
+
+```env
+AI_PROVIDER=ollama
+AI_PROVIDER_API=ollama-generate
+AI_BASE_URL=http://127.0.0.1:11434
+AI_API_KEY=
+AI_MODEL=qwen2.5:7b
+```
+
+## Deployment Modes
+
+### Single machine
+
+Recommended local flow:
+
+- `backend` on `localhost:8000`
+- `aiprovider` on `localhost:8010`
+- local model gateway on `localhost:11434` or another local port
+
+Helpers already included:
+
+- [planet.sh](/home/ray/dev/linkong/planet/planet.sh)
+- [docker-compose.local-model.yml](/home/ray/dev/linkong/planet/docker-compose.local-model.yml)
+
+### Multi-machine
+
+Example topology:
+
+- app machine: `backend`
+- AI gateway machine: `aiprovider`
+- model machine: local model service or cloud proxy
+
+In that case, this becomes service-to-service HTTP RPC:
+
+- caller -> backend
+- backend -> `http://10.0.0.12:8010`
+- `aiprovider` -> model endpoint
+
+Recommended cross-machine backend config:
+
+```env
+AI_PROVIDER_SERVICE_URL=http://10.0.0.12:8010
+AI_PROVIDER_SERVICE_TOKEN=change_me
+AI_PROVIDER_TIMEOUT_SECONDS=60
+AI_PROVIDER_RETRY_ATTEMPTS=2
+```
+
+Recommended operating rules:
+
+- keep `aiprovider` on a private network
+- protect it with `X-Provider-Token` at minimum
+- always send `X-Request-ID`
+- keep callers on the backend API unless they are infrastructure jobs
+
+## Retry And Failure Behavior
+
+`backend -> aiprovider`:
+
+- retries lightweight network / 5xx failures
+- returns `502` when the provider service is unavailable
+
+`aiprovider -> model provider`:
+
+- retries lightweight network / 5xx failures
+- returns `502` when the model provider is unavailable
+
+This is intentionally conservative. It avoids masking persistent errors while still absorbing short hiccups.
+
+## Operational Notes
+
+- `./planet.sh start` now starts `aiprovider` automatically
+- `./planet.sh restart -a` restarts only `aiprovider`
+- `./planet.sh log -a` tails `aiprovider` logs
+- `./planet.sh health` reports `aiprovider` health
+
+## Recommended Calling Policy
+
+- Frontend and application services: call `backend`
+- Scheduled infra jobs and diagnostics: optionally call `aiprovider`
+- Do not let multiple business services integrate model vendors independently
+
+That keeps provider switching centralized and avoids model-specific drift across the system.
--- a/docs/agents/datasource-health-plan.md
+++ b/docs/agents/datasource-health-plan.md
@@ -0,0 +1,486 @@
+# Datasource Health Plan
+
+## Overview
+
+This document defines a phased plan for datasource health governance.
+
+The goal is to make collectors observable, diagnosable, and recoverable when upstream APIs change, while avoiding unsafe automatic mutation of repository defaults.
+
+The key principle is:
+
+- do not let runtime automation rewrite repository default config
+
+Instead, split responsibilities across:
+
+- default config
+- runtime overrides
+- health check records
+- agent-generated repair proposals
+
+
+## Problem Statement
+
+Collectors currently depend on third-party APIs, data downloads, mirrored JSON files, archive links, and web pages.
+
+These upstream dependencies can fail in several ways:
+
+- endpoint becomes unreachable
+- endpoint still responds but schema changes
+- content-type changes
+- website shuts down or moves
+- mirror link disappears
+- HTML structure changes and scraping fails
+- endpoint requires a new path or new host
+
+We want a system that can:
+
+- detect datasource health degradation early
+- identify likely cause
+- search for updated endpoints when reasonable
+- apply safe runtime fixes without polluting default repo config
+- preserve auditability and rollback
+
+
+## Design Principles
+
+1. Default config is stable
+
+- `backend/app/core/data_sources.yaml` remains the repository baseline.
+- It should be changed intentionally through normal development flow, not by autonomous runtime agents.
+
+2. Runtime fixes are isolated
+
+- Emergency or adaptive fixes should live in a runtime override layer.
+- Overrides should be reversible and auditable.
+
+3. Deterministic checks come first
+
+- Use normal programmatic health checks before using LLMs.
+- Only call an agent when deterministic checks indicate a meaningful failure.
+
+4. Agents suggest before they mutate
+
+- Agents should produce proposals with evidence and confidence.
+- Application of a proposal should be controlled by policy.
+
+5. Every repair is attributable
+
+- Store what changed, why, who or what suggested it, and when it was applied.
+
+
+## Configuration Layers
+
+Recommended runtime precedence:
+
+1. datasource endpoint override
+2. datasource DB endpoint override
+3. repository default YAML
+4. collector internal fallback logic
+
+Definitions:
+
+- repository default YAML:
+  - `backend/app/core/data_sources.yaml`
+  - versioned baseline
+- datasource DB endpoint override:
+  - existing `DataSourceConfig.endpoint`
+  - current runtime override entrypoint
+- datasource endpoint override:
+  - a dedicated new override table
+  - used for health-repair and proposal application
+- collector internal fallback logic:
+  - final defensive fallback
+  - should be minimized over time
+
+
+## Recommended Architecture
+
+### 1. Deterministic Health Checks
+
+Each collector gets a health profile with checks such as:
+
+- endpoint resolves
+- HTTP request succeeds
+- status code is acceptable
+- content-type is expected
+- body parses successfully
+- minimum structural fields exist
+- sample item count is plausible
+- latency is within threshold
+
+Output states:
+
+- `healthy`
+- `degraded`
+- `failed`
+- `schema_changed`
+- `rate_limited`
+- `auth_required`
+
+
+### 2. Agent-Assisted Repair Discovery
+
+Only triggered when deterministic health checks fail or return suspicious structure.
+
+Agent responsibilities:
+
+- search for current official endpoint or replacement path
+- inspect likely upstream documentation or landing pages
+- compare candidate endpoint output to collector expectations
+- produce a repair proposal with confidence and evidence
+
+Agent should not directly modify repository defaults.
+
+
+### 3. Safe Runtime Repair Application
+
+Repair proposals can be:
+
+- reviewed manually
+- auto-applied only under strict low-risk policy
+
+Auto-apply should be limited to cases like:
+
+- same trusted domain
+- highly similar response structure
+- repeated successful verification
+- confidence above threshold
+
+
+## Phased Delivery Plan
+
+## Phase 1: Deterministic Health MVP
+
+Goal:
+
+- build health observability without automated repair
+
+Scope:
+
+- datasource health check task runner
+- datasource health result persistence
+- endpoint reachability + parse checks
+- dashboard or API visibility into health status
+
+Deliverables:
+
+- health check service
+- health check record table
+- status endpoint
+- scheduled or manual check trigger
+
+No agent usage yet.
+
+
+## Phase 2: Agent Repair Proposals
+
+Goal:
+
+- let agent investigate failing sources and propose updated endpoints
+
+Scope:
+
+- invoke agent only when datasource health is `failed` or `schema_changed`
+- web search + page inspection
+- candidate endpoint extraction
+- proposal persistence
+
+Deliverables:
+
+- repair proposal schema
+- proposal generation pipeline
+- confidence and evidence model
+- operator review view or API
+
+Still no automatic config mutation.
+
+
+## Phase 3: Runtime Overrides
+
+Goal:
+
+- allow approved proposals to take effect safely at runtime
+
+Scope:
+
+- add dedicated override storage
+- runtime resolution prefers override over default config
+- proposal application writes override only
+
+Deliverables:
+
+- endpoint override table
+- override-aware resolution logic
+- apply/reject endpoints
+- rollback endpoint
+
+Repository default YAML remains untouched.
+
+
+## Phase 4: Limited Auto-Apply
+
+Goal:
+
+- safely automate a narrow slice of low-risk repairs
+
+Scope:
+
+- policy engine for auto-apply
+- same-domain or trusted-domain checks
+- structure validation
+- staged verification after apply
+
+Deliverables:
+
+- auto-apply rules
+- audit logs
+- automatic post-apply health verification
+- auto-disable or rollback on regression
+
+
+## Data Model Draft
+
+### datasource_health_checks
+
+Purpose:
+
+- store each health evaluation result
+
+Suggested fields:
+
+- `id`
+- `datasource_id`
+- `collector_name`
+- `endpoint_checked`
+- `status`
+- `http_status`
+- `content_type`
+- `latency_ms`
+- `sample_count`
+- `error_message`
+- `details`
+- `checked_at`
+
+`details` can store structured diagnostic data such as:
+
+- parsed fields
+- schema mismatch summary
+- retry count
+- exception class
+
+
+### datasource_repair_proposals
+
+Purpose:
+
+- store agent-generated repair suggestions
+
+Suggested fields:
+
+- `id`
+- `datasource_id`
+- `collector_name`
+- `old_endpoint`
+- `candidate_endpoint`
+- `reason`
+- `confidence`
+- `evidence_urls`
+- `evidence_summary`
+- `status`
+- `created_by`
+- `created_at`
+- `reviewed_at`
+
+Suggested `status` values:
+
+- `proposed`
+- `approved`
+- `rejected`
+- `applied`
+- `expired`
+
+
+### datasource_endpoint_overrides
+
+Purpose:
+
+- runtime endpoint override layer
+
+Suggested fields:
+
+- `id`
+- `datasource_id`
+- `collector_name`
+- `endpoint`
+- `reason`
+- `source`
+- `proposal_id`
+- `enabled`
+- `created_at`
+- `updated_at`
+
+Suggested `source` values:
+
+- `manual`
+- `health-agent`
+- `migration`
+
+
+## API Draft
+
+### Health
+
+- `GET /api/v1/datasources/health`
+- `GET /api/v1/datasources/{id}/health`
+- `POST /api/v1/datasources/{id}/health-check`
+- `POST /api/v1/datasources/health-check-all`
+
+### Repair proposals
+
+- `GET /api/v1/datasources/{id}/repair-proposals`
+- `POST /api/v1/datasources/{id}/repair-proposals/generate`
+- `POST /api/v1/datasources/{id}/repair-proposals/{proposal_id}/approve`
+- `POST /api/v1/datasources/{id}/repair-proposals/{proposal_id}/reject`
+- `POST /api/v1/datasources/{id}/repair-proposals/{proposal_id}/apply`
+
+### Overrides
+
+- `GET /api/v1/datasources/{id}/overrides`
+- `POST /api/v1/datasources/{id}/overrides`
+- `PUT /api/v1/datasources/{id}/overrides/{override_id}`
+- `DELETE /api/v1/datasources/{id}/overrides/{override_id}`
+
+
+## Agent Contract Draft
+
+When deterministic health fails, the agent should receive:
+
+- datasource name
+- collector name
+- current endpoint
+- current failure mode
+- expected response shape summary
+- known trusted domains
+
+Expected output:
+
+```json
+{
+  "status": "proposal",
+  "candidate_endpoint": "https://example.com/api/v2/data",
+  "confidence": 0.86,
+  "reason": "Official docs now point to v2 endpoint",
+  "evidence_urls": [
+    "https://example.com/docs/api",
+    "https://example.com/changelog"
+  ],
+  "notes": "Response shape appears compatible after light field remapping"
+}
+```
+
+The agent should never output "rewrite the default yaml" as its primary action.
+
+
+## Risk Analysis
+
+### Risk: wrong endpoint chosen by agent
+
+Mitigation:
+
+- use trusted-domain allowlists
+- require evidence URLs
+- require confidence threshold
+- add manual review for medium-risk sources
+
+
+### Risk: endpoint responds but schema silently changed
+
+Mitigation:
+
+- deterministic schema checks
+- parse and sample validation
+- content-type checks
+- collector-specific required fields
+
+
+### Risk: automatic runtime override causes hidden drift
+
+Mitigation:
+
+- store all overrides explicitly
+- mark source of override
+- keep default YAML unchanged
+- expose active overrides in API/UI
+
+
+### Risk: persistent bad override breaks data collection
+
+Mitigation:
+
+- allow rollback
+- keep parent/default endpoint visible
+- re-run verification after apply
+- auto-disable override on repeated failure
+
+
+## Operational Policy Recommendations
+
+1. Do not auto-apply for high-value or high-fragility sources initially.
+
+2. Use manual approval for:
+
+- scraped HTML sources
+- unofficial mirrors
+- sources with auth or rate-limit complexity
+- sources with legal or trust ambiguity
+
+3. Allow auto-apply only for:
+
+- same-domain version bumps
+- obvious official migration paths
+- repeated passing verification
+
+4. Expose health + proposal + override state together in one operator view.
+
+
+## Suggested Implementation Order
+
+1. Phase 1
+- health result table
+- deterministic checks
+- API and UI visibility
+
+2. Phase 2
+- proposal table
+- agent prompt/output contract
+- proposal generation job
+
+3. Phase 3
+- runtime override table
+- resolver precedence update
+- apply/reject endpoints
+
+4. Phase 4
+- auto-apply rules
+- rollback policy
+- operator automation
+
+
+## Out Of Scope For The First Iteration
+
+- direct automatic mutation of repository default YAML
+- automatic git commits by repair agents
+- unrestricted autonomous endpoint replacement
+- fully generalized schema remapping engine
+
+
+## Recommended First Milestone
+
+The first milestone should be:
+
+- deterministic datasource health checks
+- persisted results
+- manual visibility
+- no automatic repair
+
+This gives immediate operational value with low risk, and prepares clean inputs for the later agent phase.
--- a/docs/agents/datasource-health-stage2-tasks.md
+++ b/docs/agents/datasource-health-stage2-tasks.md
@@ -0,0 +1,478 @@
+# Datasource Health Stage 2 Tasks
+
+## Goal
+
+Stage 2 focuses on the first practical operational layer:
+
+- deterministic datasource health checks
+- persisted health results
+- health visibility through API and UI
+- no agent-assisted repair yet
+
+This stage should make Planet capable of answering:
+
+- which collectors are healthy
+- which collectors are degraded
+- which collectors are failing
+- why they are failing at a basic deterministic level
+
+
+## Scope
+
+Included:
+
+- datasource health data model
+- deterministic health check service
+- manual and scheduled health check triggers
+- health result APIs
+- frontend visibility
+
+Excluded:
+
+- LLM reasoning
+- web-search-based repair proposals
+- automatic endpoint rewriting
+- runtime override application
+
+
+## Delivery Target
+
+At the end of Stage 2, an operator should be able to:
+
+1. see health status for each collector
+2. trigger a health check manually
+3. inspect the latest failure reason
+4. inspect the last checked endpoint
+5. understand whether the problem is:
+   - unreachable
+   - auth-related
+   - rate-limit-related
+   - schema-related
+   - empty-data-related
+
+
+## Work Breakdown
+
+## A. Data Model
+
+### A1. Add datasource health record table
+
+Create a new model, for example:
+
+- `backend/app/models/datasource_health_check.py`
+
+Suggested fields:
+
+- `id`
+- `datasource_id`
+- `collector_name`
+- `endpoint_checked`
+- `status`
+- `http_status`
+- `content_type`
+- `latency_ms`
+- `sample_count`
+- `error_message`
+- `details`
+- `checked_at`
+
+Suggested status enum values:
+
+- `healthy`
+- `degraded`
+- `failed`
+- `schema_changed`
+- `rate_limited`
+- `auth_required`
+- `empty_result`
+
+
+### A2. Add datasource health summary fields
+
+Option A:
+
+- keep summary only in the health check table
+
+Option B:
+
+- also add summary fields on `data_sources`
+
+Recommended first step:
+
+- do not mutate `data_sources` schema yet
+- derive summary from the latest health record
+
+
+### A3. Migration task
+
+Add migration for the health table.
+
+Deliverables:
+
+- migration file
+- model registration
+
+
+## B. Health Check Engine
+
+### B1. Define health check service
+
+Add a new service module, for example:
+
+- `backend/app/services/datasource_health.py`
+
+Responsibilities:
+
+- resolve effective endpoint
+- execute deterministic check
+- classify result
+- persist health record
+
+
+### B2. Define shared result schema
+
+Create a typed result object, for example:
+
+- `HealthCheckResult`
+
+Suggested fields:
+
+- `status`
+- `endpoint_checked`
+- `http_status`
+- `content_type`
+- `latency_ms`
+- `sample_count`
+- `error_message`
+- `details`
+
+
+### B3. Implement base deterministic checks
+
+Every datasource should go through a minimal baseline check:
+
+1. resolve endpoint
+2. perform request
+3. measure latency
+4. inspect status code
+5. inspect content type
+6. inspect body shape
+
+Classification rules:
+
+- network error -> `failed`
+- HTTP 401/403 -> `auth_required`
+- HTTP 429 -> `rate_limited`
+- HTTP 404/410 -> `failed`
+- parse failure -> `schema_changed`
+- zero or suspiciously empty results -> `empty_result` or `degraded`
+- valid parse -> `healthy`
+
+
+### B4. Add collector-aware adapters
+
+Some collectors do not use the same fetch semantics.
+
+Add adapter profiles such as:
+
+- `http_json`
+- `http_csv`
+- `html_scrape`
+- `stream_probe`
+- `auth_session_http`
+
+Initial mapping suggestion:
+
+- `huggingface`, `peeringdb`, `cloudflare` -> `http_json`
+- `fao` -> `http_csv`
+- `top500`, `epoch_ai`, `telegeography live_map` -> `html_scrape`
+- `ris_live` -> `stream_probe`
+- `spacetrack` -> `auth_session_http`
+
+
+### B5. Add sample validation hooks
+
+For each adapter, add a lightweight validation rule.
+
+Examples:
+
+- JSON array length > 0
+- CSV rows > 1
+- HTML page contains expected table or script patterns
+- stream source yields at least one valid event within timeout
+
+
+## C. Persistence and Query Layer
+
+### C1. Save every check run
+
+Each health check should insert a record.
+
+Do not overwrite history in Stage 2.
+
+
+### C2. Add latest-health query helpers
+
+Add helper functions to fetch:
+
+- latest health record by datasource
+- latest failed health record
+- recent health history
+
+
+### C3. Optional retention policy
+
+For Stage 2, retention can be deferred.
+
+If desired, keep only:
+
+- last N records per datasource
+
+
+## D. API Layer
+
+### D1. Add health list endpoint
+
+Suggested endpoint:
+
+- `GET /api/v1/datasources/health`
+
+Returns:
+
+- datasource id
+- collector name
+- current endpoint
+- latest health status
+- last checked time
+- short reason
+
+
+### D2. Add per-datasource health detail endpoint
+
+Suggested endpoint:
+
+- `GET /api/v1/datasources/{id}/health`
+
+Returns:
+
+- latest record
+- recent history
+- detailed classification fields
+
+
+### D3. Add manual health trigger endpoint
+
+Suggested endpoint:
+
+- `POST /api/v1/datasources/{id}/health-check`
+
+Behavior:
+
+- run a health check now
+- persist the result
+- return the new record
+
+
+### D4. Add bulk health trigger endpoint
+
+Suggested endpoint:
+
+- `POST /api/v1/datasources/health-check-all`
+
+Behavior:
+
+- enqueue or run health checks for all active datasources
+
+
+## E. Scheduling
+
+### E1. Add health scheduler task
+
+Decide scheduling strategy.
+
+Recommended first version:
+
+- run collector jobs and health checks separately
+- health checks run on a lower frequency
+
+Suggested frequency:
+
+- every 6h or 12h for most datasources
+- optionally on-demand only in the very first cut
+
+
+### E2. Prevent health check collision with collection
+
+Rules:
+
+- health checks should not disrupt active collection
+- they should use light requests
+- if a collector is currently running, health check may:
+  - skip
+  - or use a lightweight endpoint probe only
+
+
+## F. Frontend
+
+### F1. Add health columns to datasource list
+
+Update:
+
+- `frontend/src/pages/DataSources/DataSources.tsx`
+
+Suggested new columns:
+
+- health status
+- last checked
+- reason summary
+
+
+### F2. Add manual health check action
+
+Per datasource:
+
+- button or dropdown action:
+  - `健康检查`
+
+
+### F3. Add health detail drawer or modal
+
+Show:
+
+- endpoint checked
+- status
+- HTTP status
+- content type
+- sample count
+- error message
+- last few results
+
+
+### F4. Add basic visual language
+
+Suggested colors:
+
+- green -> healthy
+- yellow -> degraded
+- orange -> rate-limited / auth-required
+- red -> failed / schema-changed
+
+
+## G. Observability
+
+### G1. Structured logging
+
+Every health check should log:
+
+- datasource id
+- collector name
+- endpoint
+- status
+- latency
+- failure class
+
+
+### G2. Optional metrics
+
+If metrics are added later, useful counters include:
+
+- health checks total
+- health checks failed
+- schema changes detected
+- rate limited checks
+
+
+## H. Tests
+
+### H1. Unit tests
+
+Add tests for:
+
+- status classification
+- content type classification
+- adapter behavior
+- latest-health query helpers
+
+
+### H2. API tests
+
+Add tests for:
+
+- health endpoints require auth
+- manual trigger endpoint works
+- list endpoint returns latest status
+
+
+### H3. Failure-path tests
+
+Add coverage for:
+
+- HTTP 404
+- HTTP 429
+- invalid JSON
+- empty response
+- parse mismatch
+
+
+## Suggested File Plan
+
+Possible implementation files:
+
+- `backend/app/models/datasource_health_check.py`
+- `backend/app/services/datasource_health.py`
+- `backend/app/schemas/datasource_health.py`
+- `backend/app/api/v1/datasource_health.py`
+- migration file under the project migration system
+
+Likely touched existing files:
+
+- `backend/app/api/main.py`
+- `frontend/src/pages/DataSources/DataSources.tsx`
+- `backend/tests/test_api.py`
+
+
+## Suggested Execution Order
+
+1. Add model and migration
+2. Add service and result schema
+3. Add deterministic adapters
+4. Add manual trigger API
+5. Add list/detail API
+6. Add frontend visibility
+7. Add scheduled checks
+8. Expand tests
+
+
+## Minimal First Milestone
+
+If we want the fastest useful slice, do this first:
+
+1. health table
+2. deterministic check service
+3. manual per-datasource health check API
+4. latest health list API
+5. frontend status badge column
+
+That is enough to start operating the system and will provide the input layer for Stage 3.
+
+
+## Dependency On Later Stages
+
+Stage 2 outputs become direct inputs for Stage 3.
+
+Specifically:
+
+- failed or schema-changed health records become agent triggers
+- health history becomes repair context
+- endpoint_checked becomes proposal baseline
+
+
+## Success Criteria
+
+Stage 2 is done when:
+
+- every active datasource can be health-checked deterministically
+- the latest health state is visible in API and UI
+- operators can manually trigger checks
+- failures are categorized into stable machine-readable statuses
+- no LLM is required for core health visibility
--- a/docs/agents/situational-awareness-foundation-plan.md
+++ b/docs/agents/situational-awareness-foundation-plan.md
@@ -0,0 +1,309 @@
+# Situational Awareness Foundation Plan
+
+## 定位
+
+当前这套 AI 能力应被视为 `态势感知服务底座`，而不是完整的态势感知产品。
+
+也就是说，现阶段的目标不是：
+
+- 做一个“什么都能分析”的万能 AI 页面
+- 让模型在证据不足时替代人工研判
+- 过早把页面做成完整指挥大屏
+
+现阶段真正要做的是：
+
+- 先把 `model gateway / backend facade / evidence injection / page-specific brief` 这几层边界搭稳
+- 让系统能够在已有证据上稳定地产出“可读、可回看、可扩展”的摘要
+- 为后续更强的数据联动、agent 推理和 assessment 结构化输出预留好接口与数据模型
+
+## 当前现实约束
+
+### 1. 数据维度不足
+
+目前系统能提供的主要证据仍集中在：
+
+- BGP incidents / anomalies / events
+- collector coverage
+- datasource health / platform alerts
+- prefix geography 的部分归属信息
+
+当前明显还缺：
+
+- 流量异常与业务指标
+- 电商、支付、物流等业务侧指标
+- 更丰富的资产、链路、区域、行业画像
+- 外部舆情、公告、运营商状态、基础设施事件等背景信息
+
+这意味着：
+
+- 模型现在可以做“基于现有证据的摘要与归纳”
+- 但还不能可靠地做“跨维度因果研判”
+
+### 2. 维度之间联动还弱
+
+目前不同模块之间更多是“并列展示”，还不是“强关联分析”：
+
+- 系统告警和 BGP 事件还没有统一事件模型
+- collector bias 与真实区域热度还没有完全剥离
+- datasource health 与 BGP 风险、业务影响之间还没有稳定映射
+
+这意味着：
+
+- 当前更适合做 `brief / overview / operator notes`
+- 还不适合过度承诺“自动态势判断”
+
+### 3. 结构化 assessment 还未成为主输出
+
+虽然已经有 BGP brief、系统告警 brief、态势告警 brief，但目前主输出仍偏向：
+
+- 文本摘要
+- facts/context 附带证据
+
+后续真正要服务态势感知，需要更稳定的结构化输出，例如：
+
+- summary
+- key risks
+- evidence
+- confidence
+- recommendations
+- missing data
+
+## 当前基座已经具备的能力
+
+### 1. AI 调用边界已经明确
+
+- `aiprovider` 负责模型协议与 provider 兼容
+- `backend` 负责业务 API、证据整合和鉴权
+- `frontend` 负责页面入口与结果展示
+
+### 2. 页面级 AI 入口已经开始成型
+
+当前已经有或正在收口的入口：
+
+- `Playground`
+  - 用于链路验证与 provider 诊断
+- `BGP AI 简报`
+  - 用于 BGP 事实摘要和区域风险归纳
+- `Alerts`
+  - 用于系统告警、BGP 告警、态势告警三类入口
+
+### 3. 证据优先的方向已经建立
+
+已经不再只依赖人工在 Playground 中手填 prompt，系统开始具备：
+
+- 从真实业务数据生成事实输入
+- 保存 facts/context 快照
+- 回看 AI 输出时同时回看证据
+
+这一步非常关键，因为它决定后面能否从“玩具 demo”走向“有运维价值的系统”。
+
+## 近期收尾建议
+
+这些事情都属于“底座收口”，值得做，但不应该再继续重产品包装。
+
+### 1. 统一 Alerts 页面
+
+已采用：
+
+- 一个 `Alerts` 页面
+- 三个 tab：
+  - `系统告警`
+  - `BGP 告警`
+  - `态势告警`
+
+收尾重点：
+
+- 保持 tab 的文案、摘要卡和 AI 简报交互一致
+- 不额外扩展成多个独立二级页面
+
+### 2. 保持 Playground 为测试台
+
+原则：
+
+- Playground 只承担链路验证、provider 状态诊断、请求结果观察
+- 不继续堆“万能业务分析器”式交互
+
+### 3. 把 brief 能力当服务能力而不是页面特效
+
+页面现在能看到按钮和结果，这很好，但更重要的是：
+
+- 后端接口稳定
+- facts/context 可追踪
+- 输出结构后续可升级
+
+### 4. 导航结构先收口，不继续平铺一级菜单
+
+随着后续能力扩展，系统很可能继续新增：
+
+- 海缆
+- 算力中心
+- 战争信息
+- 电商分析
+- 其他专题观测页
+
+如果继续把这些入口全部平铺在左侧一级菜单中，会带来两个问题：
+
+- 一级菜单过长，用户难以判断先进入哪个上下文
+- `观测页 / 告警页 / 研判页 / 运维页` 的职责边界会被混在一起
+
+因此近期应明确采用分组导航，而不是继续扩展平铺菜单。
+
+推荐的导航分组如下：
+
+- `总览`
+  - 仪表盘
+  - Earth
+- `专题观测`
+  - BGP 观测
+  - 采集数据
+  - 后续可扩展：海缆、算力中心、战争信息、电商分析
+- `告警与研判`
+  - Alerts
+- `运维与配置`
+  - 数据源
+  - AI Playground
+  - 用户管理
+  - 系统配置
+
+这套结构的含义是：
+
+- `专题观测` 页面负责看某个维度本身
+- `Alerts` 负责跨模块风险与值班工作台
+- `Playground` 保持为测试台，不挤占业务导航语义
+
+短期收尾时，应优先重组现有入口，而不是继续增加新的一级菜单。
+
+## 后续路线
+
+## Phase 1：服务底座稳固
+
+目标：
+
+- 不追求“更炫的 AI 页面”
+- 先把当前接口、证据、存储和页面入口收稳
+
+工作项：
+
+- 统一页面级 AI 入口模式
+- 统一 brief response schema
+- 保证 facts/context 在前后端都可回看
+- 继续清理 mock 和临时分支逻辑
+
+完成标准：
+
+- 每个 AI 入口都是真实链路
+- 每个 AI 结果都能追溯到证据输入
+
+## Phase 2：Evidence-first Assessment
+
+目标：
+
+- 从“文本摘要”升级成“结构化 assessment”
+
+工作项：
+
+- 为 brief/assessment 定义统一 schema
+- 固化：
+  - summary
+  - key_risks
+  - evidence
+  - confidence
+  - recommendations
+  - missing_data
+- 页面以结构化区块展示，而不只是大段文本
+
+完成标准：
+
+- AI 输出可持久化、可比较、可审计
+
+## Phase 3：多维证据接入
+
+目标：
+
+- 让“态势感知”真正拥有更多维度，而不是只靠 BGP 与系统告警
+
+优先接入方向：
+
+- datasource health findings
+- 流量或业务指标
+- 区域/资产/链路映射
+- 外部事件与公告
+- 业务垂直数据，例如电商分析相关指标
+
+完成标准：
+
+- AI 能基于多个维度做交叉说明
+- 不再只围绕单一模块自说自话
+
+## Phase 4：Correlation Layer
+
+目标：
+
+- 不同来源的信号不再只是并列，而是形成统一的事件关联
+
+工作项：
+
+- 统一 signal/finding 模型
+- 跨模块事件聚合
+- 证据来源权重
+- collector bias 与真实热度分离
+
+完成标准：
+
+- 系统能回答“这些异常是不是同一件事”
+- 系统能回答“哪些结论只是观测偏差”
+
+## Phase 5：Agent-assisted Situational Awareness
+
+目标：
+
+- 在证据足够的前提下，再让 agent 负责更复杂的推理与建议
+
+工作项：
+
+- 复用现有 agent runtime 规划
+- 引入 web search / docs fetch / repair proposal 等能力
+- 但始终坚持：
+  - evidence first
+  - proposal before action
+  - no silent mutation of defaults
+
+完成标准：
+
+- agent 成为证据驱动的分析层
+- 而不是一个“万能猜测层”
+
+## 设计原则
+
+### 1. 先底座，后产品化
+
+先把服务链路和证据模型做好，再做更大的页面表达。
+
+### 2. 先证据，后判断
+
+事实输入应先稳定，再让模型做归纳。
+
+### 3. 先专用 brief，后统一态势层
+
+先让各业务页有各自可信的 AI 入口，再考虑统一态势页。
+
+### 4. 先 proposal，后自动动作
+
+涉及修复、覆盖、写配置、调任务的动作，都应经过 proposal 和审计。
+
+## 当前建议结论
+
+对现在这个项目，最合理的定位是：
+
+- `Playground` 是测试台
+- `BGP / Alerts` 是第一批业务 AI 入口
+- `aiprovider + backend AI facade + evidence snapshots` 是核心服务底座
+
+现阶段不需要追求“已经具备完整态势感知能力”。
+
+现阶段真正的成功标准是：
+
+- 这套底座可用
+- 可回看
+- 可扩展
+- 不自欺欺人