doc-to-cache

--- name: doc-to-cache description: "Конвертирует сырую документацию (MD/TXT файлы) из docs/documentation/ или любого пути в структурированные знания tech-research/cache/. Принимает файл или папку (рекурсивно). Триггеры: '/doc-to-cache', 'конвертировать документацию в кеш', 'обработать документацию', 'создать знания из файлов', 'загрузить доки в кеш', 'convert docs to cache', 'process documentation'. Параметр: путь к файлу или папке." --- # Doc-to-Cache: конвертер сырой документации в кеш знаний ## Обзор Превращает сырые файлы документации (MD, TXT) в структурированные записи кеша знаний `tech-research/cache/` по 7-категорийному шаблону. Принимает **файл** или **папку** (рекурсивно обходит вложенные). --- ## Вызов ``` /doc-to-cache <путь> ``` **Примеры:** ``` /doc-to-cache docs/documentation/Claude Code Docs /doc-to-cache docs/documentation/Lang Chain Docs/Lang Graph /doc-to-cache docs/documentation/Claude_Code_Hooks_Reference_RU.md ``` --- ## Алгоритм ### Шаг 1: Определение входа | Вход | Действие | |------|----------| | Файл (.md/.txt) | Обработать один файл | | Папка | Найти все .md/.txt рекурсивно, обработать каждый | | Папка с подпапками | Группировать файлы по подпапкам = одна тема на группу | **Группировка по темам:** - Файлы в одной подпапке объединяются в одну тему - Имя темы = нормализованное имя папки (lowercase, дефисы) - Одиночный файл = одна тема (имя из filename) ### Шаг 2: Определение темы и домена **Нормализация имени темы:** ``` "Claude Code Docs" → "claude-code" "Lang Chain Docs/Lang Graph" → "langgraph" "Протокол контекста модели (MCP)" → "mcp-protocol" "Language Server Protocol (LSP)" → "lsp-protocol" "Claude_Code_Hooks_Reference_RU.md" → "claude-code-hooks" ``` **Определение домена:** | Содержимое/путь | Домен | |-----------------|-------| | Claude Code, hooks, skills | `tools` | | LangChain, chains, prompts | `python` | | LangGraph, agents, state | `agents` | | MCP, protocol, server | `tools` | | LSP, language server | `tools` | | Qdrant, vector, FAISS | `vector-db` | | embeddings, sentence-transformers | `embeddings` | | RAG, retrieval, search | `rag` | | LLM, Claude API, model | `llm` | **Определение категории:** | Тип содержимого | Категория | |-----------------|-----------| | Библиотека/фреймворк | `library` | | Протокол/спецификация | `api` | | Концепция/подход | `concept` | | Инструмент | `tool` | | Алгоритм | `algorithm` | | Паттерн | `pattern` | ### Шаг 3: Чтение и анализ Для каждой группы файлов: 1. **Прочитать все файлы** группы (используй `Read` tool) 2. **Объединить содержимое** — устранить дубликаты между файлами 3. **Извлечь знания** по 7 категориям шаблона ### Шаг 4: Заполнение шаблона (7 категорий) Используй шаблон из `.claude/skills/tech-research/cache/_topic_template.md`. **Правила трансформации:** | Из сырого документа | В кеш знаний | |--------------------|--------------| | Вступление, история | **Убрать** | | Маркетинг, buzz-words | **Убрать** | | Описание "что это" | → **1. Идентификация** | | Команды установки | → **2. Установка** | | API/методы/классы | → **3. Core API** | | Примеры кода | → **4. Паттерны** | | Архитектура, схемы | → **5. Архитектура** | | Ошибки, FAQ | → **6. Диагностика** | | Ссылки, URL | → **7. Источники** | **Обязательные поля frontmatter:** ```yaml --- topic: "имя-темы" domain: "tools|python|agents|rag|embeddings|vector-db|llm|ml|search" category: "library|api|tool|concept|algorithm|pattern" created: "YYYY-MM-DD" last_verified: "YYYY-MM-DD" version: "если известна" source_urls: ["docs/documentation/путь/к/исходнику"] keywords: ["ключевое1", "ключевое2", ...] --- ``` ### Шаг 5: Сохранение 1. Записать файл: `.claude/skills/tech-research/cache/<имя-темы>.md` 2. Обновить `.claude/skills/tech-research/cache/_index.json`: ```json { "<имя-темы>": { "file": "<имя-темы>.md", "domain": "<домен>", "category": "<категория>", "created": "YYYY-MM-DD", "keywords": ["..."], "summary": "1-2 предложения" } } ``` ### Шаг 6: Отчёт После обработки всех файлов — вывести сводку: ``` Обработано: 5 тем из 28 файлов claude-code (tools) — 8 файлов → claude-code.md langgraph (agents) — 12 файлов → langgraph.md mcp-protocol (tools) — 6 файлов → mcp-protocol.md ... Кеш обновлён: .claude/skills/tech-research/cache/_index.json ``` --- ## Правила качества | Критерий | Проверка | |----------|----------| | Полнота | Все 7 категорий заполнены (хотя бы N/A если данных нет) | | Копируемость | Команды и код готовы к копированию | | Без воды | Нет маркетинга, истории, прозы | | Атрибуция | source_urls указывает на исходный файл | | Keywords | >= 5 ключевых слов для поиска | | Размер | Каждый topic-файл <= 500 строк | | Русский | Описания на русском, код/команды на английском | --- ## Обработка больших папок Если папка содержит > 30 файлов: 1. **Группировка первая** — покажи пользователю план группировки 2. **Батчевая обработка** — обрабатывай по 5-10 файлов за раз 3. **Прогресс** — показывай сколько обработано из скольки --- ## Обработка дубликатов Если тема уже есть в `_index.json`: 1. Прочитать существующий topic-файл 2. **Merge** — объединить новые данные с существующими 3. Обновить `last_verified` и `source_urls` 4. Сообщить: "Обновлена существующая тема: <имя>" --- ## Антипаттерны | Плохо | Почему | Как правильно | |-------|--------|---------------| | Копировать файл целиком | Не структурировано | Извлечь по 7 категориям | | Один topic на файл | Слишком гранулярно | Группировать по папкам | | Пропустить frontmatter | Индекс не обновится | Всегда заполнять YAML | | Игнорировать _index.json | Кеш не найдёт тему | Обновлять индекс | | Огромный topic (>500 строк) | Медленный lookup | Сжимать, выносить детали |