@rsconcept/rstool 0.9.1 → 0.10.0

package/docs/PORTAL-API.md

@@ -14,6 +14,9 @@
 - `/rsforms/:id` в UI → `GET /api/rsforms/:id` для метаданных.
 - Полная КС → `GET /api/rsforms/:id/details`.
 - Версия КС → `GET /api/library/:id/versions/:version`.
+- Список доступных объектов → `GET /api/library/active`.
+- Поиск по тексту в схемах/ОСС/моделях → `GET /api/library/context-search?q=...`.
+- Метаданные объектов по id → `GET /api/library/by-ids?ids=856,1203`.
 - ОСС → `GET /api/oss/:id` и соседние routes viewset.
 - Модель → `GET /api/models/:id`.
 - OpenAPI JSON → `GET https://api.portal.acconcept.ru/schema`.
@@ -32,6 +35,144 @@ GET https://api.portal.acconcept.ru/api/rsforms/856/details
 - `access_policy: "public"` читается без авторизации.
 - Приватная схема или модель вернёт `403` и не предназначена для агентов.
 - Если нужны только `title`, `alias`, `description`, `owner`, `access_policy`, не запрашивай `/details`.
+- Авторизация Portal — session cookie (`SessionAuthentication`). Для curl с приватными объектами
+  пользователя передай cookie сессии (`-b "sessionid=..."`) после логина в UI или через тот же
+  механизм, что использует фронтенд. Без cookie видны только публичные объекты в `/S` и `/L`.
+
+## Список и контекстный поиск в библиотеке
+
+Чтобы найти схему по термину, формуле или названию, не перебирай все id подряд.
+Бэкенд и UI используют контекстный поиск по вложенным текстовым полям.
+
+### Полный список доступных объектов
+
+```text
+GET /api/library/active
+```
+
+Возвращает массив метаданных (`id`, `item_type`, `title`, `alias`, `description`, `location`,
+`access_policy`, `visible`, …) для объектов, доступных текущему пользователю: публичные в `/S` и
+`/L`, собственные и те, где пользователь редактор. Анониму — только публичные в общих разделах.
+
+Для агентов обычно достаточно `context-search`; полный `active` нужен, если требуется обойти
+все объекты без текстового фильтра.
+
+### Контекстный поиск
+
+```text
+GET /api/library/context-search?q=<текст>&search_fields=<поля>&location=<путь>&subfolders=0|1&item_type=<тип>&admin=0|1
+```
+
+Ответ: `{ "ids": [856, 1203, ...] }` — id объектов библиотеки (КС, ОСС, RSModel), у которых
+совпал хотя бы один из запрошенных текстовых фрагментов. Пустой или пробельный `q` → `ids: []`.
+Регистр не важен; кириллица поддерживается.
+
+| Параметр        | Обязателен | Описание                                                |
+| --------------- | ---------- | ------------------------------------------------------- |
+| `q`             | да\*       | Подстрока для поиска (\*пустой → пустой ответ)          |
+| `search_fields` | нет        | Список полей через запятую; по умолчанию — все          |
+| `location`      | нет        | Путь папки (`/S`, `/U/Проект`, …); см. ниже             |
+| `subfolders`    | нет        | `1`/`true` — включать вложенные папки; по умолчанию `0` |
+| `item_type`     | нет        | `rsform`, `oss` или `rsmodel` — ограничить тип объекта  |
+| `admin`         | нет        | `1`/`true` — искать по всей библиотеке (только staff)   |
+
+Допустимые значения `search_fields`:
+
+| Поле                | Где ищет                                          |
+| ------------------- | ------------------------------------------------- |
+| `alias`             | Шифр объекта и конституент                        |
+| `title`             | Название объекта                                  |
+| `description`       | Описание объекта                                  |
+| `term`              | Термин конституенты (`term_raw`, `term_resolved`) |
+| `definition_formal` | Формальное определение, ручная типизация          |
+| `definition_text`   | Текстовое определение конституенты                |
+| `convention`        | Соглашение конституенты                           |
+| `operation`         | Операции ОСС (alias, title, description)          |
+| `block`             | Блоки ОСС (title, description)                    |
+
+Для КС по термину или формуле обычно не указывай `search_fields` (все поля) или явно:
+`search_fields=term,definition_formal,title`.
+
+### Префиксы `location`
+
+Путь хранится в поле `location` каждого объекта. Корневые префиксы:
+
+| Префикс | Значение                                     |
+| ------- | -------------------------------------------- |
+| `/S`    | Общие (COMMON), публичные схемы для анонимов |
+| `/L`    | Библиотека (LIBRARY), staff                  |
+| `/U`    | Личное пространство пользователя             |
+| `/P`    | Проекты                                      |
+
+Вложенные папки: `/U/Мой проект/Подпапка`.
+
+- без `subfolders` (по умолчанию) — только объекты с точным совпадением `location`;
+- с `subfolders=1` — объекты в папке и во всех вложенных (`/U/Проект`, `/U/Проект/Подпапка`, …).
+
+Параметр `item_type` сужает поиск до КС (`rsform`), ОСС (`oss`) или моделей (`rsmodel`).
+Для поиска только концептуальных схем удобно: `item_type=rsform`.
+
+### Метаданные по списку id
+
+После `context-search` не нужно запрашивать всю библиотеку (`/active`) или каждый объект отдельно.
+
+```text
+GET /api/library/by-ids?ids=<id1>,<id2>,...
+```
+
+Ответ — массив метаданных в том же формате, что и `GET /api/library/active`:
+`id`, `item_type`, `title`, `alias`, `description`, `location`, `access_policy`, `visible`, …
+
+| Параметр | Описание                |
+| -------- | ----------------------- |
+| `ids`    | Список id через запятую |
+
+Правила доступа те же, что у `context-search` и `active`: недоступные id **пропускаются**
+(не ошибка, не `403` на весь запрос). Порядок элементов в ответе совпадает с порядком id
+в запросе. Пустой `ids` → `[]`.
+
+Для одной КС по-прежнему можно `GET /api/rsforms/:id`; для нескольких результатов поиска
+удобнее `by-ids`, затем `GET /api/rsforms/:id/details` только для выбранных КС.
+
+### Примеры curl
+
+Публичный поиск по термину (без авторизации):
+
+```bash
+curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=множество"
+```
+
+Только в названиях и шифрах:
+
+```bash
+curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=логика&search_fields=title,alias"
+```
+
+С сессией пользователя (приватные и личные объекты):
+
+```bash
+curl.exe -s -b "sessionid=ВАШ_SESSION_ID" ^
+  "https://api.portal.acconcept.ru/api/library/context-search?q=UniqueTermToken"
+```
+
+Только КС в общем разделе и подпапках:
+
+```bash
+curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=множество&location=/S&subfolders=1&item_type=rsform"
+```
+
+Типичный пайплайн агента — найти id, затем метаданные и при необходимости полную КС:
+
+```bash
+# 1. Поиск
+curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=множество"
+
+# 2. Метаданные найденных объектов (подставь ids из шага 1)
+curl.exe -s "https://api.portal.acconcept.ru/api/library/by-ids?ids=856,1203"
+
+# 3. Полная КС для переноса в rstool (только для выбранной схемы)
+curl.exe -s "https://api.portal.acconcept.ru/api/rsforms/856/details"
+```
 
 ## Формат `GET /api/rsforms/:id/details`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Agent-facing library for incremental RSForm construction, RSLang analysis, diagnostics, modeling, and evaluation. Wraps @rsconcept/domain with a deterministic session contract and stdio wrapper.",
   "license": "MIT",
   "author": "IRBorisov",

package/skills/rstool-helper/GUIDE.md

@@ -52,6 +52,8 @@
 не открывай SPA и не парси HTML. Преобразуй ссылку в REST API по правилам
 [PORTAL-API.md](../../docs/PORTAL-API.md): метаданные `GET /api/rsforms/:id`,
 полная КС `GET /api/rsforms/:id/details`, версия `GET /api/library/:id/versions/:version`.
+Если id неизвестен — контекстный поиск `GET /api/library/context-search?q=...`, затем
+метаданные по найденным id: `GET /api/library/by-ids?ids=...` (curl и поля поиска — в том же файле).
 
 Portal JSON из `/details` не является форматом `exportSession` и не передаётся в
 `importSession` напрямую. Создай `createSession({ title, alias, comment: description })`