@rsconcept/rstool 0.6.0 → 0.6.1

package/docs/PORTAL-API.md

@@ -1,6 +1,8 @@
 # Portal REST API
 
-Справка только для чтения существующих КС, ОСС и RSModel. `rstool` сам не ходит в REST API: он работает с in-memory сессиями.
+Справка для чтения существующих КС, ОСС и RSModel из Portal и переноса КС в `rstool`.
+`rstool` сам не ходит в REST API: он работает с in-memory сессиями.
+Агент получает JSON Portal отдельно, затем переносит конституенты через контракт `rstool`.
 
 ## Хосты
 
@@ -16,17 +18,93 @@
 - Модель → `GET /api/models/:id`.
 - OpenAPI JSON → `GET https://api.portal.acconcept.ru/schema`.
 
+Для UI-ссылки `https://portal.acconcept.ru/rsforms/856` агент должен ходить на:
+
+```text
+GET https://api.portal.acconcept.ru/api/rsforms/856
+GET https://api.portal.acconcept.ru/api/rsforms/856/details
+```
+
+Не переноси UI query/hash вроде `?tab=editor`.
+
+## Доступ
+
+- `access_policy: "public"` читается без авторизации.
+- Приватная схема или модель вернёт `403` и не предназначена для агентов.
+- Если нужны только `title`, `alias`, `description`, `owner`, `access_policy`, не запрашивай `/details`.
+
+## Формат `GET /api/rsforms/:id/details`
+
+Ответ содержит метаданные объекта библиотеки и массив `items[]` с конституентами.
+Для анализа КС обычно нужны только корневые `title`, `alias`, `description` и поля каждой конституенты.
+
+| Portal JSON           | `rstool`                 | Примечание                                            |
+| --------------------- | ------------------------ | ----------------------------------------------------- |
+| `id`                  | `draft.id`               | Стабильный id внутри сессии                           |
+| `alias`               | `draft.alias`            | `X1`, `C1`, `S1`, `D1`, `F1`, `P1`, `A1`, `T1`        |
+| `cst_type`            | `draft.cstType`          | Значения совпадают с `CstType`                        |
+| `definition_formal`   | `draft.definitionFormal` | Пустая строка допустима только для `basic`/`constant` |
+| `term_raw`            | `draft.term`             | Для редактирования сохраняй raw, не resolved          |
+| `definition_raw`      | `draft.definitionText`   | Для редактирования сохраняй raw, не resolved          |
+| `convention`          | `draft.convention`       | Соглашение, не формальная проверка                    |
+| `term_resolved`       | не переносить            | Только отображение после resolver                     |
+| `definition_resolved` | не переносить            | Только отображение после resolver                     |
+| `typification_manual` | обычно не переносить     | Переопределение типизации                             |
+| `term_forms`          | обычно не переносить     | Словоформы термина                                    |
+| `crucial`             | обычно не переносить     | UI/Portal-флаг                                        |
+| `value_is_property`   | обычно не переносить     | Переопределение класса интерпретируемости             |
+
+`inheritance`, `attribution`, `oss`, `models`, `versions`, `editors` полезны для контекста Portal, но не нужны для базовой проверки RSLang в `rstool`.
+
 ## Как перенести КС в rstool
 
 1. Получи `GET /api/rsforms/:id/details`.
-2. Создай `createSession`.
-3. Перенеси конституенты через `addOrUpdateConstituenta`: `alias`, `cstType`, `definitionFormal`, `term`, `definitionText`, `convention`.
-4. Работай локально: анализ, правки, вычисления.
-5. Для передачи результата используй `exportSession`.
+2. Создай `createSession({ title, alias, comment: description })`.
+3. Иди по `items[]` в порядке ответа API.
+4. Для каждого элемента вызови `addOrUpdateConstituenta(sessionId, { draft })`.
+5. Проверь `listDiagnostics(sessionId)`.
+6. Работай локально: анализ, правки, вычисления, маленькая КМ.
+7. Для сохранения рабочей сессии используй `exportSession`.
+8. Для загрузки схемы обратно в Portal используй `exportPortalSchema`.
+
+Portal JSON из `/details` **не является** форматом `exportSession` и не передаётся
+в `importSession` напрямую. Его нужно перенести через `addOrUpdateConstituenta`
+или через отдельный адаптер, если он появится в контракте.
+
+Минимальный маппинг:
+
+```ts
+const session = tool.createSession({
+  title: portal.title,
+  alias: portal.alias,
+  comment: portal.description
+});
+
+for (const item of portal.items) {
+  tool.addOrUpdateConstituenta(session.sessionId, {
+    draft: {
+      id: item.id,
+      alias: item.alias,
+      cstType: item.cst_type,
+      definitionFormal: item.definition_formal ?? '',
+      term: item.term_raw ?? '',
+      definitionText: item.definition_raw ?? '',
+      convention: item.convention ?? ''
+    }
+  });
+}
+```
+
+## Практика для агентов
+
+- Запрашивай API host, а не UI host: `https://api.portal.acconcept.ru/api/...`.
+- Для больших схем используй увеличенный таймаут. В PowerShell вызывай `curl.exe`,
+  а не alias `curl` (`Invoke-WebRequest`), если нужен CLI-синтаксис curl.
+- Сначала бери метаданные, если нужно только название или доступность схемы.
 
 ## Не делай
 
 - Не парси HTML SPA.
-- Не переноси UI query/hash вроде `?tab=editor` в REST.
 - Не запрашивай UI напрямую, используй преобразованные API запросы.
+- Не передавай `/details` JSON в `importSession`.
 - Не запрашивай `/details`, если нужны только метаданные.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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

@@ -46,6 +46,21 @@
 9. Сохрани: `exportSession` / `importSession`.
 10. Для загрузки в Portal: `exportPortalSchema` (схема) или `exportPortalModel` (модель).
 
+### Оценка или правка КС из Portal
+
+Когда пользователь даёт UI-ссылку вида `https://portal.acconcept.ru/rsforms/:id`,
+не открывай 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`.
+
+Portal JSON из `/details` не является форматом `exportSession` и не передаётся в
+`importSession` напрямую. Создай `createSession({ title, alias, comment: description })`
+и перенеси `items[]` через `addOrUpdateConstituenta`, сохраняя raw-поля:
+`cst_type → cstType`, `definition_formal → definitionFormal`,
+`term_raw → term`, `definition_raw → definitionText`, `convention → convention`.
+После переноса запусти `listDiagnostics`; для результата в Portal используй
+`exportPortalSchema`, а для локального снапшота — `exportSession`.
+
 ### Концептуализация (КС из содержания источника)
 
 Когда нужно построить или существенно развить КС по тексту ПО, требованиям или предметному описанию. Правила редукции, слоёв и паттернов — [CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).

package/skills/rstool-helper/REFERENCE.md

@@ -186,6 +186,10 @@ interface AnalysisResult {
 - `state.model.items[]` — присутствует, если заданы значения интерпретации.
 - `diagnostics[]` — накопленные диагностики со смещениями и кодами.
 
+`importSession(payload)` принимает только этот формат `exportSession`. JSON Portal из
+`GET /api/rsforms/:id/details` сначала переноси в сессию через `createSession` и
+`addOrUpdateConstituenta`; поля и REST-пути описаны в `docs/PORTAL-API.md`.
+
 ## JSON импорта Portal
 
 Для **Load from JSON** на существующей схеме или модели Portal: