--- name: 1c-doc-research description: "Платформа 1С:Предприятие 8.3.27: объекты, механизмы, BSL. Триггеры: '1С', '1C', 'справочник', 'документ 1С', 'регистр', 'BSL', 'реквизит', 'табличная часть', 'подсистема', 'проведение', 'модуль', 'форма'. НЕ для RAG/ML/Python — используй tech-research." --- # 1C Doc Research — исследование с приоритетом документации 1С ## Обзор Исследовательский скилл для ответов по платформе 1С и технологиям фреймворка. **Документация 1С:Предприятие 8.3.27 — эталон.** Скилл ищет в индексированной документации (API), дополняет из внешних источников (its.1c.ru, infostart.ru, GitHub), верифицирует, атрибутирует каждый факт и кеширует результат для повторного использования. --- ## Быстрый справочник | Задача | Действие | |--------|----------| | Ответ по 1С-объекту | Фаза 0 (кеш) → Фаза 1 (POST /search/ask) → Фаза 2 (WebSearch) → Фаза 5 (кеш) | | Проверить кеш | Прочитать `cache/_index.json`, найти по keywords | | Поиск в документации | `POST http://127.0.0.1:8000/search/ask` strategy=hybrid, k=10, rerank=true | | Поиск на ИТС | `WebSearch: "site:its.1c.ru [тема]"` | | Поиск на Инфостарт | `WebSearch: "site:infostart.ru [тема 1С]"` | | Сохранить в кеш | Создать topic-файл по `cache/_topic_template.md` + обновить `_index.json` | | Проверить актуальность | `last_verified` < 7 дней = свежий, иначе quick verify через API | --- ## Индексированная документация **Документация 1С:Предприятие 8.3.27** — актуальная, регулярно обновляемая и дополняемая новыми главами. Это эталонный источник, приоритет над любыми внешними данными. Индексированная документация включает текстовые чанки и изображения (скриншоты палитры свойств, конструкторов, форм — описаны через Claude Vision). **Если API не вернул результатов по теме:** 1. Тема может быть ещё не проиндексирована — дополнить из внешних источников 2. Пометить: `[Не из индексированной документации — внешний источник]` --- ## Иерархия источников (СТРОГИЙ ПРИОРИТЕТ) ``` ПРИОРИТЕТ 1 — ЭТАЛОН (обязательный) │ ├─ Индексированная документация 1С:Предприятие 8.3.27 │ API: POST /search/ask, strategy=hybrid, k=10, rerank=true │ Включает: текст + описания скриншотов (палитры свойств, формы) │ ПРИОРИТЕТ 2 — ОФИЦИАЛЬНЫЕ ИСТОЧНИКИ ВЕНДОРА │ ├─ its.1c.ru — ИТС, методическая поддержка от 1С ├─ v8.1c.ru — официальный форум разработчиков 1С │ ПРИОРИТЕТ 3 — ЭКСПЕРТНОЕ СООБЩЕСТВО 1С │ ├─ infostart.ru — статьи экспертов, решения, библиотеки (проверенный источник) │ ПРИОРИТЕТ 4 — ТЕХНИЧЕСКИЕ ИСТОЧНИКИ (все технологии, включая 1С) │ ├─ GitHub 1С: 1c-syntax, bsl-language-server, oscript-library ├─ GitHub RAG/ML: langchain, qdrant, sentence-transformers ├─ Официальная документация библиотек ├─ Arxiv papers, HuggingFace model cards │ ПРИОРИТЕТ 5 — ДОПОЛНИТЕЛЬНЫЕ │ ├─ Stack Overflow (проверенные ответы) ├─ Технические блоги (с рабочим кодом) └─ Medium/Habr (с осторожностью — может быть устаревшим) ``` --- ## Процесс исследования ### Фаза 0: Проверка кеша знаний (ПЕРЕД ПОИСКОМ) Перед API-запросом проверь, есть ли кешированное знание по теме. 1. Прочитай `.claude/skills/1c-doc-research/cache/_index.json` 2. Найди topic по ключевым словам вопроса (fuzzy match по `keywords`) 3. **Если topic найден:** a. Прочитай topic-файл из `cache/` b. Проверь свежесть: - `last_verified` < 7 дней → **использовать как есть** (ответ из кеша) - `last_verified` >= 7 дней → **quick verify**: POST /search/ask по теме, сравнить результаты. Если совпадают — обновить `last_verified`, использовать кеш. Если изменились — перейти к Фазе 1 c. Если `last_reindex` в `_index.json` новее чем `last_verified` → **обязательно перепроверить** 4. **Если topic НЕ найден** → перейти к Фазе 1 **При использовании кеша** — пометить: `[Из кеша знаний, верифицировано ДАТА]` ### Фаза 1: Документация (ОБЯЗАТЕЛЬНО) **Всегда начинай с локальной документации.** Это эталон. ``` POST http://127.0.0.1:8000/search/ask { "question": "[вопрос пользователя]", "strategy": "hybrid", "k": 10, "rerank": true, "stream": false } ``` Из ответа API извлеки: - **Текст** — основа ответа - **Номера страниц** (`page_number` в метаданных) — для ссылки на PDF - **Номера разделов** (`section_title`) — для §-ссылок - **Изображения** — описания скриншотов могут содержать важную визуальную информацию (вкладки форм, палитры свойств, конструкторы) **Следуй перекрёстным ссылкам:** если §5.6 (общие свойства) ссылается на §5.8 (справочники), сделай дополнительный запрос к API по связанной теме. Если API недоступен — ищи в проекте: `docs/`, `MEMORY.md`. ### Фаза 2: Внешние источники (ДОПОЛНЕНИЕ) Запускай **параллельно** с Фазой 1. **Для 1С-тем:** ``` WebSearch: "site:its.1c.ru [тема]" WebSearch: "site:infostart.ru [тема 1С]" WebSearch: "[тема] 1С 8.3 [ключевые слова]" ``` **Для RAG/ML/Python:** ``` WebSearch: "site:github.com [тема] stars:>100" WebSearch: "[тема] official documentation 2025 OR 2026" ``` **GitHub-репозитории — проверяй качество:** | Критерий | Минимум | Идеально | |----------|---------|----------| | Stars | > 100 | > 1000 | | Последний коммит | < 6 мес | < 1 мес | | Issues ratio | < 50% open | < 20% open | ### Фаза 3: Верификация **КРИТИЧЕСКИ ВАЖНО:** 1. **Сверка с документацией** — внешний источник ПРОТИВОРЕЧИТ документации 1С? → Отбросить, верна документация 2. **Терминология** — внешний источник использует неофициальные термины? → Привести к терминологии документации: - "форма объекта" (блог) → **"форма элемента"** (документация) - "проводка" (обиходный) → **"проведение"** (документация) - "ТЧ" (жаргон) → **"табличная часть"** (документация) - "движения" (жаргон) → **"записи регистра"** (документация) 3. **Версия** — информация для 8.3.27? Отличия между версиями: - 8.1/8.2: обычные формы (толстый клиент) — устарело - 8.3: **управляемые формы** (тонкий клиент) — актуально - Если источник описывает обычные формы — пометить `[версия 8.2, может отличаться]` 4. **Перекрёстная проверка** — факт подтверждён >= 2 источниками? Если нет — пометить `[непроверено]` ### Фаза 4: Оформление результата Каждый факт ДОЛЖЕН иметь атрибуцию. ### Фаза 5: Кеширование знаний (ПОСЛЕ ОТВЕТА) После каждого полного исследования (Фазы 1-4) **сохрани результат в кеш**. 1. Определи нормализованное имя темы (lowercase, дефисы вместо пробелов): `справочники`, `ws-ссылки`, `регистры-накопления` 2. Создай topic-файл по шаблону `cache/_topic_template.md`: - Заполни **все 8 категорий знаний**: Идентификация, Создание/Настройка, Структура данных, Формы и модули, Паттерны, Связи, Диагностика, Источники - Frontmatter: `topic`, `created`, `last_verified` (= сегодня), `doc_version`, `source_sections`, `keywords` 3. Сохрани в `.claude/skills/1c-doc-research/cache/<имя-темы>.md` 4. Обнови `cache/_index.json`: добавь запись с `file`, `created`, `last_verified`, `keywords` **8 категорий знаний** (адаптированы под 1С-объекты): ``` 1. ИДЕНТИФИКАЦИЯ → Что это, для чего, тип объекта, раздел документации 2. СОЗДАНИЕ/НАСТРОЙКА → Именование, нумерация, подсистемы, роли, РИБ, функц. опции 3. СТРУКТУРА ДАННЫХ → Реквизиты, табличные части, измерения/ресурсы, иерархия 4. ФОРМЫ И МОДУЛИ → Типы форм, вкладки, модуль объекта/менеджера/формы, скриншоты 5. ПАТТЕРНЫ → BSL-код, проведение/движения, обработчики, запросы, интеграция 6. СВЯЗИ → Владелец/подчинённый, перекрёстные ссылки в документации 7. ДИАГНОСТИКА → Частые ошибки, антипаттерны, различия 8.2/8.3 8. ИСТОЧНИКИ → Полный список с атрибуцией [§X.Y, стр. N] ``` Полный шаблон: `cache/_topic_template.md` --- ## Формат ответа (ОБЯЗАТЕЛЬНЫЙ) ```markdown ## [Тема]: краткое резюме ### По документации 1С:Предприятие 8.3.27 <Основная информация из индексированной документации> <Каждый факт помечен: [Документация 8.3.27, §X.Y, стр. N]> <Описания скриншотов: [Документация 8.3.27, изображение стр. N]> ### Перекрёстные ссылки в документации [если есть] - §X.Y ссылается на §Z.W — <краткое описание связи> ### Дополнительно из внешних источников <Информация, которая ДОПОЛНЯЕТ документацию (не повторяет!)> <Каждый факт помечен: [its.1c.ru, URL], [infostart.ru, URL]> <Неофициальные термины заменены на официальные> ### Вне индексированной документации [если тема не найдена в API] <Информация из внешних источников по темам ещё не проиндексированным> <Пометка: "Не из индексированной документации — внешний источник"> ### Практическое применение <Конкретные шаги, BSL-код где применимо> ### Источники Все источники с указанием что из каждого взято: - **[Документация 8.3.27]** §X.Y, стр. N — [что взято] - **[its.1c.ru]** URL — [что взято] - **[infostart.ru]** URL — [что взято] ``` ### Правила атрибуции | Правило | Пример | |---------|--------| | Факт из документации | «Справочник имеет 5 типов форм [Документация 8.3.27, §5.8, стр. 45]» | | Скриншот из документации | «На скриншоте палитры свойств видно... [Документация 8.3.27, изображение стр. 46]» | | Дополнение извне | «Практика дизайна форм: ... [infostart.ru, URL]» | | Конфликт | «Документация: X [§5.6.9]. Источник Y утверждает Z — верна документация» | | Нет в индексированной документации | «В документации не найдено. По данным [its.1c.ru, URL]: ...» | | Неофициальный термин | «"Форма объекта" (так в блогах) = "форма элемента" в документации» | --- ## Специфика поиска по темам ### 1С-платформа / BSL ``` 1. POST /search/ask {"question": "[тема 1С]", ...} ← ОБЯЗАТЕЛЬНО ПЕРВЫМ 2. WebSearch: "site:its.1c.ru [тема]" 3. WebSearch: "site:infostart.ru [тема 1С]" 4. WebSearch: "1С Предприятие 8.3 [тема]" ``` Ключевые ресурсы: - **its.1c.ru** — ИТС, методическая поддержка (приоритет 2) - **infostart.ru** — статьи экспертов, решения (приоритет 3) - **v8.1c.ru** — форум разработчиков (приоритет 3) - **github.com/1c-syntax** — BSL Language Server, EDT - **github.com/oscript-library** — OneScript экосистема ### RAG / Embeddings / LLM ``` WebSearch: "[тема] RAG pipeline production 2025" WebSearch: "[тема] langchain langgraph implementation" WebSearch: "site:github.com [тема] rag stars:>200" ``` Ключевые репозитории: - `langchain-ai/langchain`, `qdrant/qdrant`, `UKPLab/sentence-transformers` --- ## Антипаттерны | Плохо | Почему | Как правильно | |-------|--------|---------------| | Пропустить запрос к локальной документации | Документация 8.3.27 — эталон | ВСЕГДА начинай с POST /search/ask | | Не указать что тема вне документации | Пользователь думает что ответ из документации | Явно писать "Не из индексированной документации, источник: ..." | | Факт без источника | Нельзя проверить точность | Каждый факт = [источник, §раздел, стр.] | | Внешний источник важнее документации | Документация вендора актуальнее | При конфликте верна документация 8.3.27 | | Использовать жаргон вместо терминов документации | Путает пользователя | "ТЧ" → "табличная часть", "движения" → "записи регистра" | | Не различать 8.2 и 8.3 | Обычные и управляемые формы — разные | Помечать версию: [8.2] или [8.3] | | Игнорировать описания скриншотов | Image-чанки содержат важную визуальную информацию | Включать: "На скриншоте видно..." | | Не следовать перекрёстным ссылкам | §5.6 → §5.8 → §5.13 — связанная информация | Делать доп. запрос по связанным разделам | | Не перечислить ВСЕ источники | Непрозрачность | Полный список с URL и что взято | | Не сохранить в кеш после исследования | Повторный поиск тратит время и API-вызовы | Фаза 5: всегда кешировать результат | | Использовать устаревший кеш без проверки | Документация могла обновиться | Проверять `last_verified` и `last_reindex` |