# Agent Guide for QevosAgent Website

## Quick Start

You are an AI Agent accessing the QevosAgent website. This guide helps you navigate efficiently.

### Step 1: Discover
Start by reading `/agent-manifest.json` to understand the site structure and available endpoints.

### Step 2: Browse All Posts
Get the full blog index to see all available articles:
```
GET /api/agent/blog-index.json
```

This returns all posts with slug, title, date, summary, tags, and links to full content.

### Step 3: Search (Client-Side)
Get the search index and filter client-side:
```
GET /api/agent/search.json
```

This returns all posts with a `search_index` field containing normalized text for keyword matching.

**Example (client-side filtering):**
```javascript
// Fetch the search index
const index = await fetch('/api/agent/search.json').then(r => r.json());
// Filter by keyword
const results = index.posts.filter(p => 
  p.search_index.includes('qwen')
).slice(0, 10); // Limit to 10 results
```

**Note**: This is a static file. No query parameters are supported.

### Step 4: Read Full Article
Once you find a relevant article, get the full structured content with sections:
```
GET /api/agent/content/{slug}.json
```

Example:
```
GET /api/agent/content/2026-05-01-qwen-scope-analysis.json
```

**Response includes:**
- `slug`: Unique identifier
- `title`: Article title
- `title_zh`: Chinese title (if available)
- `date`: Publication date
- `summary`: Brief description
- `tags`: Topic tags
- `sections`: Array of `{id, heading, content}` parsed from Markdown ## headings
- `sections_zh`: Chinese sections (if available)
- `html_url`: Link to full HTML article

## Response Format

All API responses are JSON. Each blog post content includes:

| Field | Type | Description |
|---|---|---|
| slug | string | Unique article identifier |
| title | string | Article title |
| title_zh | string | Chinese title (optional) |
| date | string | Publication date (YYYY-MM-DD) |
| summary | string | Brief description |
| summary_zh | string | Chinese summary (optional) |
| tags | string[] | Topic tags |
| language | string | "en" or "zh" |
| sections | object[] | [{id, heading, content}] |
| sections_zh | object[] | Chinese sections (optional) |
| html_url | string | Link to HTML version |
| html_url_zh | string | Chinese HTML link (optional) |

## Rate Limits

- 100 requests per minute
- 1000 requests per hour
- Identify yourself with User-Agent header

## Error Handling

- **404**: Article not found. Check the slug.
- **429**: Rate limit exceeded. Wait before retrying.
- **500**: Server error. Try again later.

## Tips

1. **Use JSON endpoints** instead of parsing HTML - faster and more reliable
2. **Download the search index once** and filter client-side for multiple queries
3. **Cache results** - content doesn't change frequently
4. **Respect rate limits** - be a good citizen
5. **Use sections** - articles are structured into sections for easy navigation

## Contact

- GitHub Issues: https://github.com/HongyunQiu/QevosAgent/issues
- Discord: https://discord.gg/tX2BrQmeD7