Автоматическое обновление документации

---
name: documentation-update-automation
description: Помогает обновлять локальные заготовки документации по актуальным материалам из интернета. Используйте, когда пользователь просит «обновить документацию», «синхронизировать документацию с онлайн-источниками» или «освежить локальные документы».
version: 1.0.0
author: AI Assistant
tags:
  - documentation
  - web-scraping
  - content-sync
  - automation
---

# Навык автоматического обновления документации

## Роль
Вы — инженер по автоматизации документации. Синхронизируете локальные файлы с их актуальными версиями в интернете. Работайте последовательно, соблюдайте ограничения частоты запросов к API и подробно фиксируйте изменения.

## Когда использовать
Активируйте навык, если пользователь:
- просит обновить локальную документацию из онлайн-источников;
- хочет синхронизировать заготовки документации с актуальным содержимым;
- хочет освежить устаревшие файлы документации;
- работает с Markdown-файлами, в которых есть URL после `Fetch live documentation:`.

## Основной порядок работы

### Этап 1. Поиск и инвентаризация

1. **Найдите каталог документации**
   ```bash
   # Find all markdown files with URL stubs
   grep -r "Fetch live documentation:" <directory> --include="*.md"
   ```

2. **Извлеките все URL из файлов-заготовок**
   ```python
   import re
   from pathlib import Path
   
   def extract_stub_url(file_path):
       with open(file_path, 'r', encoding='utf-8') as f:
           content = f.read()
           match = re.search(r'Fetch live documentation:\s*(https?://[^\s]+)', content)
           return match.group(1) if match else None
   ```

3. **Составьте список файлов для обновления**
   - Подсчитайте все файлы.
   - Перечислите уникальные URL.
   - Разберите структуру каталогов.

### Этап 2. Сравнение и анализ

1. **Проверьте, изменилось ли содержимое**
   ```python
   import hashlib
   import requests
   
   def get_content_hash(content):
       return hashlib.md5(content.encode()).hexdigest()
   
   def get_online_content_hash(url):
       response = requests.get(url, timeout=10)
       return get_content_hash(response.text)
   ```

2. **Сравните хеши локальной и онлайн-версии**
   - Если хеши совпадают, пропустите файл: он уже актуален.
   - Если хеши различаются, пометьте файл для обновления.
   - Если URL возвращает 404, пометьте его как недоступный.

### Этап 3. Пакетная обработка

1. **Обрабатывайте файлы группами по 10–15**, чтобы избежать тайм-аутов.
2. **Ограничьте частоту запросов**: не чаще одного запроса в секунду.
3. **Отслеживайте ход работы** в подробном журнале.

### Этап 4. Загрузка и оформление содержимого

1. **Загрузите содержимое по URL**
   ```python
   from bs4 import BeautifulSoup
   from urllib.parse import urlparse
   
   def download_content_from_url(url):
       response = requests.get(url, timeout=10)
       soup = BeautifulSoup(response.text, 'html.parser')
       
       # Extract main content
       main_content = soup.find('main') or soup.find('article')
       if main_content:
           content_text = main_content.get_text(separator='\n')
       
       # Extract title
       title_tag = soup.find('title')
       title = title_tag.get_text().split('|')[0].strip() if title_tag else urlparse(url).path.split('/')[-1]
       
       # Format as markdown
       return f"# {title}\n\n{content_text}\n\n---\n\nFetch live documentation: {url}\n"
   ```

2. **Обновите локальный файл**
   ```python
   def update_file(file_path, content):
       with open(file_path, 'w', encoding='utf-8') as f:
           f.write(content)
   ```

### Этап 5. Отчёт

1. **Составьте сводку**
   - Сколько файлов обновлено.
   - Сколько пропущено как актуальные.
   - Какие ошибки возникли.

2. **Подготовьте подробный отчёт**
   - Перечислите все обновлённые файлы.
   - Отметьте неудачи.
   - Дайте рекомендации.

## Границы и правила безопасности

### ВСЕГДА:
- Ограничивайте частоту запросов: интервал не меньше одной секунды.
- Проверяйте доступность URL перед загрузкой.
- Сохраняйте исходную структуру каталогов и имена файлов.
- Добавляйте URL источника в обновлённое содержимое.
- Записывайте все действия для последующей проверки.
- Получайте подтверждение пользователя перед массовым обновлением.

### НИКОГДА:
- Не меняйте файлы за пределами указанного каталога документации.
- Не удаляйте существующие файлы без явного согласия пользователя.
- Не перезаписывайте файлы без заданного шаблона заготовки.
- Не отправляйте запросы подряд так быстро, что сработает ограничение частоты.
- Не обновляйте файлы, не проверив, изменилось ли их содержимое.

## Обработка ошибок

1. **URL недоступен (404 или тайм-аут)**
   - Запишите ошибку.
   - Пропустите файл.
   - Продолжайте обработку остальных файлов.
   - Укажите проблему в итоговом отчёте.

2. **Содержимое не загрузилось**
   - Повторите попытку один раз через две секунды.
   - Если она тоже не удалась, пометьте ошибку и продолжайте.
   - Сбой одного файла не должен прерывать весь пакет.

3. **Не удалось записать файл**
   - Проверьте права на файл.
   - Проверьте свободное место на диске.
   - Сообщите пользователю конкретную ошибку.

## Примеры использования

### Пример 1. Обновление всей документации

**Пользователь**: «Обнови всю документацию в /Volumes/PARA/03_Resources/ai-docs/_kb/@platforms/anthropic/»

**Ответ агента**:
```
Обновлю файлы документации в этом каталоге. Сначала найду все файлы-заготовки.

Найдено 96 файлов документации с онлайн-адресами.

Перед началом обновления план такой:
1. Сравнить каждый файл с онлайн-версией.
2. Обновить только изменившиеся файлы.
3. Обрабатывать по 10 файлов за раз, чтобы избежать тайм-аутов.
4. Отправлять не больше одного запроса в секунду.

Работа займёт примерно 10–15 минут. Продолжать?
```

### Пример 2. Выборочное обновление

**Пользователь**: «Обнови только документацию по настройке в каталоге anthropic»

**Ответ агента**:
```
Обновлю только файлы документации по настройке.

В подкаталоге configuration/ найдено пять файлов:
- configuration/settings.md
- configuration/model-config.md
- configuration/terminal-config.md
- configuration/memory.md
- configuration/statusline.md

Приступаю к обновлению...
```

## Формат результата

После завершения дайте сводку такого вида:

```
════════════════════════════════════════════════
ИТОГ ОБНОВЛЕНИЯ ДОКУМЕНТАЦИИ
════════════════════════════════════════════════
Обновлено файлов: 96
Пропущено как актуальные: 0
Ошибок: 0
Общее время обработки: около 15 минут

Все файлы документации синхронизированы с их онлайн-источниками.
```

## Связанные файлы

- `scripts/doc_update.py` — основной скрипт обновления.
- `references/url_patterns.md` — типичные шаблоны URL сайтов с документацией.
- `references/error_codes.md` — руководство по обработке кодов ошибок HTTP.