@rsconcept/rstool 0.9.1 → 0.10.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/docs/PORTAL-API.md +158 -0
  2. package/package.json +1 -1
  3. package/skills/rstool-helper/GUIDE.md +3 -0
  4. package/skills/rstool-helper/SKILL.md +4 -0
package/docs/PORTAL-API.md CHANGED
@@ -4,6 +4,23 @@
4
4
  `rstool` сам не ходит в REST API: он работает с in-memory сессиями.
5
5
  Агент получает JSON Portal отдельно, затем переносит конституенты через контракт `rstool`.
6
6
 
7
+ ## Репозиторий Portal
8
+
9
+ Исходники приложения: [github.com/IRBorisov/ConceptPortal](https://github.com/IRBorisov/ConceptPortal)
10
+
11
+ Для работы с продакшен API клон не обязателен — достаточно этого файла и OpenAPI (`/schema`).
12
+ Если нужен исходный контекст, подгружай файлы из репозитория (Read в checkout, `git clone`, или просмотр на GitHub):
13
+
14
+ | Нужно | Путь в репозитории |
15
+ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
16
+ | Правила монорепо, UI→API | [`AGENTS.md`](https://github.com/IRBorisov/ConceptPortal/blob/main/AGENTS.md) |
17
+ | Обзор, локальная разработка | [`README.md`](https://github.com/IRBorisov/ConceptPortal/blob/main/README.md) |
18
+ | Библиотека, context-search, by-ids | [`rsconcept/backend/apps/library/`](https://github.com/IRBorisov/ConceptPortal/tree/main/rsconcept/backend/apps/library) |
19
+ | Правила и команды бэкенда | [`rsconcept/backend/AGENTS.md`](https://github.com/IRBorisov/ConceptPortal/blob/main/rsconcept/backend/AGENTS.md) |
20
+ | RSForm / КС API | [`rsconcept/backend/apps/rsform/`](https://github.com/IRBorisov/ConceptPortal/tree/main/rsconcept/backend/apps/rsform) |
21
+ | Хосты UI и API в проде | [`nginx/production.conf`](https://github.com/IRBorisov/ConceptPortal/blob/main/nginx/production.conf) |
22
+ | Справка rstool (этот файл в npm) | [`rsconcept/rstool/docs/PORTAL-API.md`](https://github.com/IRBorisov/ConceptPortal/blob/main/rsconcept/rstool/docs/PORTAL-API.md) |
23
+
7
24
  ## Хосты
8
25
 
9
26
  - UI: `https://portal.acconcept.ru/`
@@ -14,6 +31,9 @@
14
31
  - `/rsforms/:id` в UI → `GET /api/rsforms/:id` для метаданных.
15
32
  - Полная КС → `GET /api/rsforms/:id/details`.
16
33
  - Версия КС → `GET /api/library/:id/versions/:version`.
34
+ - Список доступных объектов → `GET /api/library/active`.
35
+ - Поиск по тексту в схемах/ОСС/моделях → `GET /api/library/context-search?q=...`.
36
+ - Метаданные объектов по id → `GET /api/library/by-ids?ids=856,1203`.
17
37
  - ОСС → `GET /api/oss/:id` и соседние routes viewset.
18
38
  - Модель → `GET /api/models/:id`.
19
39
  - OpenAPI JSON → `GET https://api.portal.acconcept.ru/schema`.
@@ -32,6 +52,144 @@ GET https://api.portal.acconcept.ru/api/rsforms/856/details
32
52
  - `access_policy: "public"` читается без авторизации.
33
53
  - Приватная схема или модель вернёт `403` и не предназначена для агентов.
34
54
  - Если нужны только `title`, `alias`, `description`, `owner`, `access_policy`, не запрашивай `/details`.
55
+ - Авторизация Portal — session cookie (`SessionAuthentication`). Для curl с приватными объектами
56
+ пользователя передай cookie сессии (`-b "sessionid=..."`) после логина в UI или через тот же
57
+ механизм, что использует фронтенд. Без cookie видны только публичные объекты в `/S` и `/L`.
58
+
59
+ ## Список и контекстный поиск в библиотеке
60
+
61
+ Чтобы найти схему по термину, формуле или названию, не перебирай все id подряд.
62
+ Бэкенд и UI используют контекстный поиск по вложенным текстовым полям.
63
+
64
+ ### Полный список доступных объектов
65
+
66
+ ```text
67
+ GET /api/library/active
68
+ ```
69
+
70
+ Возвращает массив метаданных (`id`, `item_type`, `title`, `alias`, `description`, `location`,
71
+ `access_policy`, `visible`, …) для объектов, доступных текущему пользователю: публичные в `/S` и
72
+ `/L`, собственные и те, где пользователь редактор. Анониму — только публичные в общих разделах.
73
+
74
+ Для агентов обычно достаточно `context-search`; полный `active` нужен, если требуется обойти
75
+ все объекты без текстового фильтра.
76
+
77
+ ### Контекстный поиск
78
+
79
+ ```text
80
+ GET /api/library/context-search?q=<текст>&search_fields=<поля>&location=<путь>&subfolders=0|1&item_type=<тип>&admin=0|1
81
+ ```
82
+
83
+ Ответ: `{ "ids": [856, 1203, ...] }` — id объектов библиотеки (КС, ОСС, RSModel), у которых
84
+ совпал хотя бы один из запрошенных текстовых фрагментов. Пустой или пробельный `q` → `ids: []`.
85
+ Регистр не важен; кириллица поддерживается.
86
+
87
+ | Параметр | Обязателен | Описание |
88
+ | --------------- | ---------- | ------------------------------------------------------- |
89
+ | `q` | да\* | Подстрока для поиска (\*пустой → пустой ответ) |
90
+ | `search_fields` | нет | Список полей через запятую; по умолчанию — все |
91
+ | `location` | нет | Путь папки (`/S`, `/U/Проект`, …); см. ниже |
92
+ | `subfolders` | нет | `1`/`true` — включать вложенные папки; по умолчанию `0` |
93
+ | `item_type` | нет | `rsform`, `oss` или `rsmodel` — ограничить тип объекта |
94
+ | `admin` | нет | `1`/`true` — искать по всей библиотеке (только staff) |
95
+
96
+ Допустимые значения `search_fields`:
97
+
98
+ | Поле | Где ищет |
99
+ | ------------------- | ------------------------------------------------- |
100
+ | `alias` | Шифр объекта и конституент |
101
+ | `title` | Название объекта |
102
+ | `description` | Описание объекта |
103
+ | `term` | Термин конституенты (`term_raw`, `term_resolved`) |
104
+ | `definition_formal` | Формальное определение, ручная типизация |
105
+ | `definition_text` | Текстовое определение конституенты |
106
+ | `convention` | Соглашение конституенты |
107
+ | `operation` | Операции ОСС (alias, title, description) |
108
+ | `block` | Блоки ОСС (title, description) |
109
+
110
+ Для КС по термину или формуле обычно не указывай `search_fields` (все поля) или явно:
111
+ `search_fields=term,definition_formal,title`.
112
+
113
+ ### Префиксы `location`
114
+
115
+ Путь хранится в поле `location` каждого объекта. Корневые префиксы:
116
+
117
+ | Префикс | Значение |
118
+ | ------- | -------------------------------------------- |
119
+ | `/S` | Общие (COMMON), публичные схемы для анонимов |
120
+ | `/L` | Библиотека (LIBRARY), staff |
121
+ | `/U` | Личное пространство пользователя |
122
+ | `/P` | Проекты |
123
+
124
+ Вложенные папки: `/U/Мой проект/Подпапка`.
125
+
126
+ - без `subfolders` (по умолчанию) — только объекты с точным совпадением `location`;
127
+ - с `subfolders=1` — объекты в папке и во всех вложенных (`/U/Проект`, `/U/Проект/Подпапка`, …).
128
+
129
+ Параметр `item_type` сужает поиск до КС (`rsform`), ОСС (`oss`) или моделей (`rsmodel`).
130
+ Для поиска только концептуальных схем удобно: `item_type=rsform`.
131
+
132
+ ### Метаданные по списку id
133
+
134
+ После `context-search` не нужно запрашивать всю библиотеку (`/active`) или каждый объект отдельно.
135
+
136
+ ```text
137
+ GET /api/library/by-ids?ids=<id1>,<id2>,...
138
+ ```
139
+
140
+ Ответ — массив метаданных в том же формате, что и `GET /api/library/active`:
141
+ `id`, `item_type`, `title`, `alias`, `description`, `location`, `access_policy`, `visible`, …
142
+
143
+ | Параметр | Описание |
144
+ | -------- | ----------------------- |
145
+ | `ids` | Список id через запятую |
146
+
147
+ Правила доступа те же, что у `context-search` и `active`: недоступные id **пропускаются**
148
+ (не ошибка, не `403` на весь запрос). Порядок элементов в ответе совпадает с порядком id
149
+ в запросе. Пустой `ids` → `[]`.
150
+
151
+ Для одной КС по-прежнему можно `GET /api/rsforms/:id`; для нескольких результатов поиска
152
+ удобнее `by-ids`, затем `GET /api/rsforms/:id/details` только для выбранных КС.
153
+
154
+ ### Примеры curl
155
+
156
+ Публичный поиск по термину (без авторизации):
157
+
158
+ ```bash
159
+ curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=множество"
160
+ ```
161
+
162
+ Только в названиях и шифрах:
163
+
164
+ ```bash
165
+ curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=логика&search_fields=title,alias"
166
+ ```
167
+
168
+ С сессией пользователя (приватные и личные объекты):
169
+
170
+ ```bash
171
+ curl.exe -s -b "sessionid=ВАШ_SESSION_ID" ^
172
+ "https://api.portal.acconcept.ru/api/library/context-search?q=UniqueTermToken"
173
+ ```
174
+
175
+ Только КС в общем разделе и подпапках:
176
+
177
+ ```bash
178
+ curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=множество&location=/S&subfolders=1&item_type=rsform"
179
+ ```
180
+
181
+ Типичный пайплайн агента — найти id, затем метаданные и при необходимости полную КС:
182
+
183
+ ```bash
184
+ # 1. Поиск
185
+ curl.exe -s "https://api.portal.acconcept.ru/api/library/context-search?q=множество"
186
+
187
+ # 2. Метаданные найденных объектов (подставь ids из шага 1)
188
+ curl.exe -s "https://api.portal.acconcept.ru/api/library/by-ids?ids=856,1203"
189
+
190
+ # 3. Полная КС для переноса в rstool (только для выбранной схемы)
191
+ curl.exe -s "https://api.portal.acconcept.ru/api/rsforms/856/details"
192
+ ```
35
193
 
36
194
  ## Формат `GET /api/rsforms/:id/details`
37
195
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rsconcept/rstool",
3
- "version": "0.9.1",
3
+ "version": "0.10.1",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "author": "IRBorisov",
package/skills/rstool-helper/GUIDE.md CHANGED
@@ -26,6 +26,7 @@
26
26
  - Диагностики: [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
27
27
  - Грамматика: [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md).
28
28
  - REST Portal: [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md).
29
+ - Репозиторий Portal (исходники, API, nginx): [ConceptPortal на GitHub](https://github.com/IRBorisov/ConceptPortal) — карта путей в [PORTAL-API.md](../../docs/PORTAL-API.md#репозиторий-portal).
29
30
 
30
31
  ## Воркфлоу
31
32
 
@@ -52,6 +53,8 @@
52
53
  не открывай SPA и не парси HTML. Преобразуй ссылку в REST API по правилам
53
54
  [PORTAL-API.md](../../docs/PORTAL-API.md): метаданные `GET /api/rsforms/:id`,
54
55
  полная КС `GET /api/rsforms/:id/details`, версия `GET /api/library/:id/versions/:version`.
56
+ Если id неизвестен — контекстный поиск `GET /api/library/context-search?q=...`, затем
57
+ метаданные по найденным id: `GET /api/library/by-ids?ids=...` (curl и поля поиска — в том же файле).
55
58
 
56
59
  Portal JSON из `/details` не является форматом `exportSession` и не передаётся в
57
60
  `importSession` напрямую. Создай `createSession({ title, alias, comment: description })`
package/skills/rstool-helper/SKILL.md CHANGED
@@ -26,6 +26,10 @@ Then continue with the canonical files below.
26
26
 
27
27
  Always open **GUIDE.md** first when starting a rstool task, then **REFERENCE.md** / **EXAMPLES.md** / relevant `docs/*.md` as needed.
28
28
 
29
+ ## Portal (приложение)
30
+
31
+ Репозиторий: [github.com/IRBorisov/ConceptPortal](https://github.com/IRBorisov/ConceptPortal). REST и curl — `node_modules/@rsconcept/rstool/docs/PORTAL-API.md`; карта путей в исходниках — раздел «Репозиторий Portal» в том же файле.
32
+
29
33
  ## Quick facts
30
34
 
31
35
  - Package: `@rsconcept/rstool`; wrapper: `npx rstool-wrapper`