gybson63gybson63/1c-oData-skill/skills/conf-doc/SKILL.md

conf-doc

Skill8 starsChanged 5 months agoMITView on GitHub

Семантический поиск и drill-down по документации конфигурации 1С через MCP 1c-conf-doc или HTTP API. Используй для метаданных (реквизиты, регистры, связи) и источников данных отчётов (запросы СКД) перед OData-запросами. Короткие keyword-запросы; odata_fields на top-1; финальные имена полей — из OData $metadata.

In this repository9 other files it gives its agents.
- .cursor/rules/analyst.mdcCursor rule
- .cursor/rules/development-workflow.mdcCursor rule
- .cursor/rules/git-commit-push.mdcCursor rule
- 1cconfinfoSkill
- analyst-conf-docSkill
- analyst-domainSkill
- analyst-mcpSkill
- analystSkill
- odataSkill

The file

Create a free account to mount

Files

SKILL.md

conf-doc — поиск по метаданным конфигурации 1С

Инструмент: 1c-conf-doc (HTTP :8050 или MCP conf_doc_*). Индекс SQLite + FAISS + markdown на сервере — не читай output/, metadata.db, CLI с диска клиента.

Связка с OData: conf-doc → объект, смысл полей, регистры из отчётов; OData $metadata / fetch → фактические имена полей и данные.

MCP-инструменты

MCP	HTTP	Назначение
`conf_doc_health`	GET `/health`	Доступность
`conf_doc_list_configurations`	GET `/configurations`	Имена проиндексированных конфигураций
`conf_doc_search`	POST `/search`	Семантический поиск (+ `odata_fields` для top-1)
`conf_doc_list_objects`	GET `/objects`	Поиск по имени в SQLite
`conf_doc_get_object`	GET `/objects/{type}/{name}`	Карточка: счётчики, чанки, help
`conf_doc_get_object_chunk`	GET `.../chunks/{N}`	Полный текст фрагмента
`conf_doc_query`	POST `/query`	RAG (только если LLM включён на сервере)

OpenAPI: {CONF_DOC_API_URL}/docs

Переменные окружения MCP

Переменная	Описание
`CONF_DOC_API_URL`	URL backend без `/` (например `http://localhost:8050`)
`CONF_DOC_CONFIGURATION`	Поле `name` из `/configurations` (ЗУП 3.1: `ЗарплатаИУправлениеПерсоналомКОРП`)

См. mcp.example.json.

Двухшаговая модель

Обзор — conf_doc_search / POST /search: топ объектов, один лучший чанк на объект.
Детали — conf_doc_get_object → conf_doc_get_object_chunk или уточнённый search.

По умолчанию /search обрезает text до 800 символов. Передай "full": true для полного текста. Поле odata_fields не обрезается — для top-1 возвращается JSON реквизитов из индекса.

Как формулировать query (критично)

Семантический поиск плохо работает на длинных вопросах. Не передавай целиком: «Покажи 10 штатных сотрудников: ФИО, должность».

Делай	Не делай
Короткие ключевые слова: `отпуск`, `увольнение`, `Сотрудники`	Полный текст вопроса с глаголами и числами
Точное имя объекта: `КадроваяИсторияСотрудников`	Размытые фразы: `Catalog Сотрудники`
Несколько узких запросов + выбор лучшего	Один длинный запрос «на всё»
Фильтр `object_type`: `Document`, `InformationRegister`	Ожидать, что Role подскажет OData-entity

Доменные доп. запросы (ЗУП)

Тема	Дополнительные query
Сотрудники, ФИО, должность	`Сотрудники`, `КадроваяИсторияСотрудников`
Отпуск, остаток отпуска	`отпуск`, `остатки отпусков`, `АналитикаОстатковОтпусков`, `ОстаткиОтпусков`
Начисление зарплаты	`НачислениеЗарплаты`, `начисление зарплаты`
Увольнение	`увольнение`, `Увольнение`

Приоритет типов для OData-entity

Предпочитай: Catalog, Document, InformationRegister, AccumulationRegister, CalculationRegister. Report не даёт OData-entity, но его чанки «Запрос СКД» показывают реальные регистры-источники отчёта — читай их для выбора register entity.

Чанки объектов

chunk	Содержимое
`0`	Overview (справка, формы)
`1+`	Реквизиты шапки, табличные части

Report: дополнительно ## Модуль объекта (BSL) и ## Запрос СКД: {набор} — полный текст запроса из основной СКД. Для анализа источников данных читай чанки с «Запрос СКД», не только overview.

Пример (остатки отпусков):

search("остатки отпусков") → Report.ОстаткиОтпусков (семантика) + InformationRegister.АналитикаОстатковОтпусков (прямой OData)
get_object(Report, ОстаткиОтпусков) → список чанков
get_object_chunk(..., N) где в тексте Запрос СКД → регистры: НачальныеОстаткиОтпусков, ФактическиеОтпуска, …
OData: для готового остатка — InformationRegister_АналитикаОстатковОтпусков + поле ОстатокДней; имена — из $metadata

conf-doc + OData: два слоя правды

Слой	Источник	Что даёт
Объект и смысл полей	conf-doc	`Document.Отпуск`, реквизиты, запросы отчётов
Имена полей в запросе к базе	OData `$metadata`	Фактические `Property` публикации

odata_fields строится из XML конфигурации, не из OData-публикации. Перед $select / $filter сверяй с $metadata.

Workflow для агента

Структура конфигурации

- [ ] conf_doc_health
- [ ] conf_doc_list_configurations
- [ ] conf_doc_search — короткий query (+ odata_fields top-1)
- [ ] conf_doc_get_object_chunk — реквизиты / справка

Перед OData-запросом к данным

- [ ] conf_doc_search — keyword-запросы (см. таблицу ЗУП)
- [ ] Выбрать Catalog/Document/Register из top-k
- [ ] Для отчётных тем — drill-down Report → чанки «Запрос СКД»
- [ ] odata_fields или chunk с реквизитами
- [ ] OData $metadata — финальные имена полей
- [ ] fetch / OData

Маппинг типов → OData-префиксы

Тип conf-doc	Префикс OData	Пример
Catalog	`Catalog_`	`Catalog_Сотрудники`
Document	`Document_`	`Document_Отпуск`
InformationRegister	`InformationRegister_`	`InformationRegister_АналитикаОстатковОтпусков`
AccumulationRegister	`AccumulationRegister_`	`AccumulationRegister_ФактическиеОтпуска`
CalculationRegister	`CalculationRegister_`	`CalculationRegister_...`

Имя configuration — поле name из /configurations, не синоним «ЗУП».

Ограничения

Нет прямого чтения .md / SQLite с клиента.
odata_fields ≠ гарантия имён в OData публикации.
Виртуальные таблицы OData (/Balance(), /Turnovers()) в conf-doc не описаны — см. OData skill.
После обновления chunker (Report+СКД) нужен index на сервере conf-doc для ZUP.

Ошибки

Симптом	Действие
Connection refused	`docker compose up -d` в 1c-conf-doc
Report — только 1 короткий chunk	Переиндекс ZUP (`index --force` или смена CHUNKER_VERSION)
503 на `conf_doc_query`	LLM отключён — search + chunks
OData 400 code 6	Сверить с `$metadata`, не только conf-doc

Настройка

Backend: проект 1c-conf-doc, порт 8050. Оценка пользы: docs/conf-doc-evaluation-checklist.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free