@iola_adm/iola-cli 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iola_adm/iola-cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "CLI и AI-агент городского округа Йошкар-Ола.",
   "license": "MIT",
   "homepage": "https://github.com/adm-iola/iola-cli#readme",

package/src/cli.js

@@ -10,6 +10,7 @@ import readline from "node:readline/promises";
 import { Readable } from "node:stream";
 import { stdin as input, stdout as output } from "node:process";
 import { DatabaseSync } from "node:sqlite";
+import tls from "node:tls";
 import { fileURLToPath } from "node:url";
 import { inflateRawSync, inflateSync } from "node:zlib";
 
@@ -6695,7 +6696,7 @@ async function aiAsk(args, context = {}) {
   const historyEnabled = !options.bare && !options["no-history"] && isFeatureEnabled("sqlite-history");
   const sessionId = historyEnabled && isFeatureEnabled("sessions") ? ensureSessionForAsk(options, providerConfig, question) : null;
   const history = context.history || (sessionId ? getSessionAiHistory(sessionId) : []);
-  const directAnswer = buildDirectDataAnswer(question, dataContext);
+  const directAnswer = await buildDirectDataAnswer(question, dataContext);
   if (directAnswer) {
     if (historyEnabled) {
       recordAskHistory({ question, answer: directAnswer, providerConfig, dataContext, error: "", sessionId });
@@ -6758,10 +6759,12 @@ async function aiAsk(args, context = {}) {
   return answer;
 }
 
-function buildDirectDataAnswer(question, dataContext) {
+async function buildDirectDataAnswer(question, dataContext) {
   const normalized = question.toLocaleLowerCase("ru-RU");
   const requestedFields = detectDirectDataFields(normalized);
   if (requestedFields.length === 0) return "";
+  const educationAnswer = await buildDeterministicEducationAnswer(question, requestedFields);
+  if (educationAnswer) return educationAnswer;
   const rows = [
     ...dataContext.schools.map((item) => ({ layer: "schools", layerName: "школы", ...item })),
     ...dataContext.kindergartens.map((item) => ({ layer: "kindergartens", layerName: "детские сады", ...item })),
@@ -6791,6 +6794,140 @@ function detectDirectDataFields(normalizedQuestion) {
   return [...new Set(fields)];
 }
 
+async function buildDeterministicEducationAnswer(question, requestedFields) {
+  const normalized = String(question || "").toLocaleLowerCase("ru-RU");
+  const layer = /(сад|детсад|детск\w*\s+сад|садик)/iu.test(normalized)
+    ? "kindergartens"
+    : /(школ|сош|лице|гимнази)/iu.test(normalized)
+      ? "schools"
+      : "";
+  if (!layer) return "";
+
+  const requests = extractEducationFactRequests(question, requestedFields, layer);
+  if (requests.length === 0) return "";
+
+  const items = normalizeItems(await fetchAllApiItems(`${await getApiBaseUrl()}/${DATASETS[layer].endpoint}`))
+    .map((item) => ({ layer, layerName: layer === "schools" ? "школы" : "детские сады", ...selectPublicSummary(item) }));
+  const answers = [];
+
+  for (const request of requests) {
+    const answer = resolveEducationFactRequest(request, items, layer);
+    if (answer) answers.push(answer);
+  }
+
+  return answers.filter(Boolean).join("\n");
+}
+
+function extractEducationFactRequests(question, requestedFields, layer) {
+  const normalized = String(question || "").toLocaleLowerCase("ru-RU");
+  const segments = splitEducationQuestionSegments(question);
+  const requests = [];
+
+  for (const segment of segments) {
+    const segmentFields = detectDirectDataFields(segment.toLocaleLowerCase("ru-RU"));
+    const fields = segmentFields.length > 0 ? segmentFields : (segments.length === 1 ? requestedFields : []);
+    if (fields.length === 0) continue;
+    const place = detectEducationPlace(segment) || detectEducationPlace(question);
+    const number = extractEntityNumberFromQuestion(segment, layer)
+      || (segments.length === 1 ? extractEntityNumberFromQuestion(question, layer) : "");
+    const hasEntitySignal = Boolean(number || place || /(школ|сош|лице|гимнази|сад|детсад|детск\w*\s+сад|садик)/iu.test(segment));
+    if (!hasEntitySignal) continue;
+    requests.push({ segment, fields, number, place });
+  }
+
+  if (requests.length === 0 && requestedFields.length > 0 && /(школ|сош|лице|гимнази|сад|детсад|детск\w*\s+сад|садик)/iu.test(normalized)) {
+    requests.push({
+      segment: question,
+      fields: requestedFields,
+      number: extractEntityNumberFromQuestion(question, layer),
+      place: detectEducationPlace(question),
+    });
+  }
+
+  return requests;
+}
+
+function splitEducationQuestionSegments(question) {
+  const text = String(question || "").trim();
+  if (!text) return [];
+  return text
+    .split(/\s+(?:и|а также|,|;)\s+(?=(?:кто|какой|какая|адрес|телефон|инн|сайт|почт|email|директ|руковод|завед|где))/iu)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function detectEducationPlace(text) {
+  const normalized = normalizeEntityText(text || "");
+  if (/(козьмодемьянск|козьмодемьянск[аеуом]?|козьмодемьянск\w*)/iu.test(normalized)) {
+    return { id: "kozmodemyansk", label: "Козьмодемьянск", locative: "Козьмодемьянске", supported: false, aliases: ["козьмодемьянск", "козмодемьянск"] };
+  }
+  if (/(семеновк|семёновк)/iu.test(normalized)) {
+    return { id: "semenovka", label: "Семёновка", locative: "Семёновке", supported: true, aliases: ["семеновк", "семёновк"] };
+  }
+  if (/(йошкар|йошкар-ола|йошкар ола)/iu.test(normalized)) {
+    return { id: "yoshkar_ola", label: "Йошкар-Ола", locative: "Йошкар-Оле", supported: true, aliases: ["йошкар", "йошкар-ола", "йошкар ола"] };
+  }
+  return null;
+}
+
+function resolveEducationFactRequest(request, items, layer) {
+  const entityLabel = layer === "schools" ? "школу" : "детский сад";
+  if (request.place && !request.place.supported) {
+    return `В текущих открытых данных iola-cli есть данные городского округа Йошкар-Ола. Данных по ${request.place.locative || request.place.label} в этом слое нет, поэтому ответить по этому объекту не могу.`;
+  }
+
+  let candidates = items;
+  if (request.place) {
+    candidates = candidates.filter((item) => itemMatchesPlace(item, request.place));
+  }
+
+  if (request.number) {
+    const exactByNumber = candidates.filter((item) => itemNameHasNumber(item, request.number));
+    if (exactByNumber.length === 0) {
+      if (request.place && candidates.length > 0) {
+        return [
+          `Точную ${entityLabel} № ${request.number} в ${request.place.locative || request.place.label} в открытом слое не нашел.`,
+          `В ${request.place.locative || request.place.label} есть:`,
+          ...candidates.slice(0, 5).map((item) => `- ${getDirectDataItemName(item)}${item.address ? `; адрес: ${item.address}` : ""}${item.inn ? `; ИНН ${item.inn}` : ""}`),
+        ].join("\n");
+      }
+      return `В открытом слое не нашел ${entityLabel} № ${request.number}.`;
+    }
+    candidates = exactByNumber;
+  }
+
+  if (candidates.length === 0) {
+    const placeText = request.place ? ` в ${request.place.locative || request.place.label}` : "";
+    return `В открытом слое не нашел ${entityLabel}${placeText}.`;
+  }
+
+  if (candidates.length > 1 && !request.number) {
+    return [
+      `Нашел несколько подходящих записей${request.place ? ` для ${request.place.locative || request.place.label}` : ""}:`,
+      ...candidates.slice(0, 5).flatMap((item) => [
+        `- ${getDirectDataItemName(item)}`,
+        ...request.fields.map((field) => `  ${formatDirectDataField(field, item)}`).filter(Boolean),
+        `  Источник: слой ${item.layer}, ИНН ${item.inn || "-"}.`,
+      ]),
+    ].join("\n");
+  }
+
+  const item = candidates[0];
+  const lines = request.fields.map((field) => formatDirectDataField(field, item)).filter(Boolean);
+  if (lines.length === 0) return "";
+  return [
+    ...lines,
+    `Источник: слой ${item.layer}, ${getDirectDataItemName(item)}, ИНН ${item.inn || "-"}.`,
+  ].join("\n");
+}
+
+function itemMatchesPlace(item, place) {
+  if (!place) return true;
+  const text = normalizeEntityText(`${item.name || ""} ${item.address || ""} ${item.legal_address || ""} ${item.fns_full_name || ""} ${item.fns_short_name || ""}`);
+  if (place.id === "yoshkar_ola") return /йошкар|йошкар-ола|йошкар ола/u.test(text) && !/семеновк/u.test(text);
+  return place.aliases.some((alias) => text.includes(normalizeEntityText(alias)));
+}
+
 function pickDirectDataItem(question, dataContext, rows) {
   const patterns = dataContext.query?.patterns || extractStructuredPatterns(question);
   const targetLayers = patterns.targetLayers || [];
@@ -8667,18 +8804,23 @@ async function callGigaChat(config, messages) {
   }
 
   const token = await getGigaChatAccessToken(config, authKey);
-  const response = await fetch(`${String(config.baseUrl || "https://gigachat.devices.sberbank.ru/api/v1").replace(/\/+$/, "")}/chat/completions`, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${token}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({
-      model: config.model || "GigaChat-2",
-      messages,
-      temperature: Number(config.temperature ?? 0.2),
-    }),
-  });
+  let response;
+  try {
+    response = await fetch(`${String(config.baseUrl || "https://gigachat.devices.sberbank.ru/api/v1").replace(/\/+$/, "")}/chat/completions`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model: config.model || "GigaChat-2",
+        messages,
+        temperature: Number(config.temperature ?? 0.2),
+      }),
+    });
+  } catch (error) {
+    throw new Error(formatProviderFetchError("GigaChat", error));
+  }
 
   if (!response.ok) {
     const text = await response.text();
@@ -8690,17 +8832,23 @@ async function callGigaChat(config, messages) {
 }
 
 async function getGigaChatAccessToken(config, authKey) {
+  enableSystemCaForGigaChat();
   const secrets = await loadSecrets();
   const scope = process.env.GIGACHAT_SCOPE || secrets.gigachat?.scope || config.scope || "GIGACHAT_API_PERS";
-  const response = await fetch(config.authUrl || "https://ngw.devices.sberbank.ru:9443/api/v2/oauth", {
-    method: "POST",
-    headers: {
-      authorization: `Basic ${authKey}`,
-      "content-type": "application/x-www-form-urlencoded",
-      RqUID: randomUUID(),
-    },
-    body: new URLSearchParams({ scope }).toString(),
-  });
+  let response;
+  try {
+    response = await fetch(config.authUrl || "https://ngw.devices.sberbank.ru:9443/api/v2/oauth", {
+      method: "POST",
+      headers: {
+        authorization: `Basic ${authKey}`,
+        "content-type": "application/x-www-form-urlencoded",
+        RqUID: randomUUID(),
+      },
+      body: new URLSearchParams({ scope }).toString(),
+    });
+  } catch (error) {
+    throw new Error(formatProviderFetchError("GigaChat OAuth", error));
+  }
 
   if (!response.ok) {
     const text = await response.text();
@@ -8712,6 +8860,37 @@ async function getGigaChatAccessToken(config, authKey) {
   return payload.access_token;
 }
 
+let systemCaForGigaChatEnabled = false;
+
+function enableSystemCaForGigaChat() {
+  if (systemCaForGigaChatEnabled || process.env.GIGACHAT_DISABLE_SYSTEM_CA === "1") return;
+  systemCaForGigaChatEnabled = true;
+
+  try {
+    if (typeof tls.getCACertificates !== "function" || typeof tls.setDefaultCACertificates !== "function") return;
+    const certificates = [
+      ...tls.getCACertificates("system"),
+      ...tls.getCACertificates("bundled"),
+      ...tls.getCACertificates("extra"),
+    ];
+    if (certificates.length > 0) tls.setDefaultCACertificates([...new Set(certificates)]);
+  } catch {
+    // Older Node builds may not expose system CA management. The fetch error below
+    // will include the concrete TLS/network cause and the manual workaround.
+  }
+}
+
+function formatProviderFetchError(provider, error) {
+  const cause = error?.cause;
+  const causeCode = cause?.code ? `${cause.code}: ` : "";
+  const causeMessage = cause?.message || "";
+  const details = `${error?.message || "fetch failed"}${causeMessage ? ` (${causeCode}${causeMessage})` : ""}`;
+  if (/SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_GET_ISSUER_CERT|CERT_/i.test(`${cause?.code || ""} ${causeMessage}`)) {
+    return `${provider} network error: ${details}\nNode не доверяет цепочке сертификатов провайдера. CLI пробует использовать системные сертификаты ОС автоматически; если ошибка повторяется, обновите Node.js или запустите CLI с NODE_OPTIONS=--use-system-ca.`;
+  }
+  return `${provider} network error: ${details}`;
+}
+
 function getAiNetworkMode(config = {}) {
   return validateAiNetworkMode(AI_NETWORK_MODE || config.networkMode || "gateway");
 }

package/test/smoke-test.js

@@ -84,4 +84,18 @@ if (deletePlan.willKeep.includes("npm package files")) {
   throw new Error("delete dry-run should not keep npm package files");
 }
 
+const multiSchoolAnswer = await runCli(["ask", "Кто директор школы № 2 и адрес школы № 7?", "--profile", "yandexgpt", "--no-history"]);
+assertIncludes(multiSchoolAnswer, "Адамова Наталья Васильевна", "multi school answer");
+assertIncludes(multiSchoolAnswer, "улица Первомайская, дом 89", "multi school answer");
+assertNotIncludes(multiSchoolAnswer, "улица Осипенко, дом 46\nИсточник: слой schools, МБОУ \"Средняя общеобразовательная школа № 7", "multi school answer");
+
+const externalTownAnswer = await runCli(["ask", "Адрес школы № 1 Козьмодемьянска", "--profile", "yandexgpt", "--no-history"]);
+assertIncludes(externalTownAnswer, "Данных по Козьмодемьянске", "external town answer");
+assertNotIncludes(externalTownAnswer, "улица Петрова, дом 15", "external town answer");
+
+const semenovkaAnswer = await runCli(["ask", "Адрес школы № 1 Семеновки", "--profile", "yandexgpt", "--no-history"]);
+assertIncludes(semenovkaAnswer, "Точную школу № 1 в Семёновке", "semenovka answer");
+assertIncludes(semenovkaAnswer, "село Семёновка", "semenovka answer");
+assertNotIncludes(semenovkaAnswer, "улица Петрова, дом 15", "semenovka answer");
+
 console.log("smoke tests passed");

package/wiki/AI-/320/277/321/200/320/276/321/204/320/270/320/273/320/270.md

@@ -29,40 +29,139 @@ iola ask "найди школы на Петрова"
 
 ### YandexGPT
 
-Официальные страницы:
+Для CLI нужны две вещи: API key и ID каталога Yandex Cloud.
+
+Пошаговая настройка:
+
+1. Откройте консоль Yandex Cloud: `https://console.yandex.cloud/`.
+2. Войдите в аккаунт Яндекса.
+3. Если Yandex Cloud попросит создать облако, создайте облако. Название может быть любым, например `iola-cli`.
+4. Откройте каталог внутри облака. Если каталога нет, создайте каталог. Название может быть любым, например `default`.
+5. На верхней панели страницы каталога найдите название каталога и его идентификатор. В нашем примере рядом с `default` был показан ID вида `b1g8...`.
+6. Нажмите кнопку `Копировать` рядом с идентификатором каталога. Это значение будет `YANDEXGPT_FOLDER_ID`.
+7. В левом меню или через поиск сервисов откройте `Identity and Access Management`.
+8. Внутри `Identity and Access Management` откройте раздел `Сервисные аккаунты`.
+9. Нажмите `Создать сервисный аккаунт`.
+10. В поле `Имя` введите понятное имя, например `iola-cli`.
+11. В поле `Описание` можно написать `API-доступ iola-cli к YandexGPT`.
+12. В блоке `Роли в каталоге` нажмите `Добавить роль`.
+13. В поле поиска роли введите `ai.languageModels.user`.
+14. В найденной группе `ai.languageModels` выберите роль `user`. В форме должна появиться роль `ai.languageModels.user`.
+15. Нажмите `Создать`.
+16. После создания откройте созданный сервисный аккаунт `iola-cli`.
+17. На странице сервисного аккаунта нажмите кнопку `Создать новый ключ`.
+18. В выпадающем меню выберите `Создать API-ключ`. Не выбирайте `Создать статический ключ доступа` и не выбирайте `Создать авторизованный ключ`.
+19. В поле `Описание` напишите, например, `iola-cli YandexGPT API key`.
+20. В поле `Область действия` выберите `yc.ai.foundationModels.execute`. Если список пустой, начните вводить это значение в поле фильтра и выберите найденный вариант.
+21. Поле `Срок действия` можно оставить пустым или выбрать дату окончания действия ключа по вашей политике безопасности.
+22. Нажмите `Создать`.
+23. Yandex Cloud покажет `Идентификатор ключа` и `Ваш секретный ключ`. Секретный ключ показывается только один раз.
+24. Скопируйте `Ваш секретный ключ` и сохраните его локально. Это значение будет `YANDEXGPT_API_KEY`.
+25. Сохраните ключ в CLI:
 
-- документация Foundation Models: `https://yandex.cloud/ru/docs/foundation-models/`;
-- аутентификация API: `https://yandex.cloud/ru/docs/ai-studio/api-ref/authentication`;
-- тарифы: `https://yandex.cloud/ru/docs/foundation-models/pricing`.
+```bash
+iola ai key set yandexgpt
+```
+
+CLI попросит ввести:
 
-Для CLI нужны API key и ID каталога Yandex Cloud:
+- `YANDEXGPT_API_KEY` - API-ключ сервисного аккаунта;
+- `YANDEXGPT_FOLDER_ID` - ID каталога Yandex Cloud.
+
+Важно: `Идентификатор ключа` - это не API-ключ для CLI. Для CLI нужен именно `Ваш секретный ключ`. Если закрыть окно создания ключа, секретный ключ больше нельзя посмотреть. В этом случае удалите старый API-ключ и создайте новый.
+
+После сохранения ключа выберите профиль и модель:
 
 ```bash
-iola ai key set yandexgpt
 iola ai setup yandexgpt --model yandexgpt-lite/latest
 ```
 
+Через интерактивное меню:
+
+```text
+/model
+2. Российские AI (YandexGPT/GigaChat)
+1. YandexGPT API
+```
+
+Доступные модели в CLI:
+
+- `yandexgpt-lite/latest` - быстрый и более дешевый вариант;
+- `yandexgpt/latest` - YandexGPT Pro latest;
+- `yandexgpt/rc` - release candidate.
+
 CLI также понимает env-переменные `YANDEXGPT_API_KEY` или `YANDEX_CLOUD_API_KEY`, а для каталога - `YANDEXGPT_FOLDER_ID` или `YANDEX_CLOUD_FOLDER_ID`.
 
 ### GigaChat
 
-Официальные страницы:
+Для CLI нужен authorization key. Это не одноразовый OAuth access token: CLI сам получает OAuth-токен перед запросом, используя сохраненный authorization key.
+
+Пошаговая настройка:
+
+1. Перейдите на портал разработчиков Сбера: `https://developers.sber.ru/`.
+2. Войдите в аккаунт. Если вход еще не выполнен, портал откроет страницу авторизации: `https://developers.sber.ru/studio/login`.
+3. Откройте страницу GigaChat API. Прямой путь: `https://developers.sber.ru/studio/workspaces/my-space/get/gigachat-api`.
+4. Нажмите кнопку подключения или `Попробовать`. После входа откроется форма создания проекта.
+5. В форме `Почти готово` заполните `Название проекта`. Можно оставить предложенное название `Мой GigaChat API` или указать `iola-cli`.
+6. В блоке `Группа проекта` нажмите `Выбрать группу`.
+7. Если есть вариант `Без группы`, выберите его. Если создание проекта после этого недоступно, выберите `Создать группу`, задайте понятное имя, например `iola-cli`, и сохраните группу.
+8. Нажмите `Создать проект`.
+9. После создания проекта откроется страница GigaChat API. В верхней части будет название проекта, например `Мой GigaChat API`.
+10. На странице проекта нажмите `Настроить API`. Если кнопки не видно, откройте раздел настроек проекта GigaChat API в левом меню.
+11. На странице `Настройка API` найдите блок `Данные для авторизации запросов к API`.
+12. Проверьте поле `Scope`. Для личного Freemium-доступа обычно указан `GIGACHAT_API_PERS`. Это значение понадобится CLI.
+13. В блоке `Ключ авторизации` нажмите `Получить ключ`.
+14. Откроется окно `Сохраните ваш Authorization Key`. Не закрывайте его, пока не сохраните данные.
+15. Скопируйте поле `Authorization Key`. Это и есть значение `GIGACHAT_AUTH_KEY` для CLI.
+16. При желании также сохраните `Client ID` и `Client Secret`, но CLI они не нужны, если вы уже скопировали `Authorization Key`.
+17. Нажмите `Готово` только после сохранения ключа.
+18. Сохраните ключ локально в CLI:
+
+```bash
+iola ai key set gigachat
+```
+
+CLI попросит ввести:
 
-- документация GigaChat: `https://developers.sber.ru/docs/ru/gigachat/overview`;
-- получение OAuth-токена: `https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/post-token`;
-- тарифы: `https://developers.sber.ru/docs/ru/gigachat/tariffs`.
+- `GIGACHAT_AUTH_KEY` - authorization key;
+- `scope` - по умолчанию `GIGACHAT_API_PERS` для персонального доступа.
 
-Для CLI нужен authorization key:
+Важно: `Authorization Key` показывается один раз. Если закрыть окно и не сохранить ключ, его нельзя посмотреть повторно. В этом случае нажмите `Получить новый ключ` и сохраните новое значение. `Authorization Key` - это уже готовая строка для заголовка `Authorization: Basic ...`; вручную кодировать `Client ID:Client Secret` в base64 не нужно.
+
+После сохранения ключа выберите профиль и модель:
 
 ```bash
-iola ai key set gigachat
 iola ai setup gigachat --model GigaChat-2
 ```
 
+Через интерактивное меню:
+
+```text
+/model
+2. Российские AI (YandexGPT/GigaChat)
+2. GigaChat API
+```
+
+Доступные модели в CLI:
+
+- `GigaChat-2` - основная модель;
+- `GigaChat-2-Pro` - повышенное качество;
+- `GigaChat-2-Max` - максимальное качество;
+- `GigaChat` - legacy/fallback.
+
 CLI также понимает env-переменные `GIGACHAT_AUTH_KEY` или `GIGACHAT_API_KEY`. По умолчанию используется scope `GIGACHAT_API_PERS`; при необходимости его можно задать через `GIGACHAT_SCOPE`.
 
 По тарифам: у GigaChat для физических лиц есть Freemium-лимит на токены; для больших объемов используются платные пакеты. У YandexGPT тарификация идет через Yandex Cloud по токенам и квотам аккаунта, поэтому актуальные бесплатные гранты или лимиты нужно проверять в консоли Yandex Cloud.
 
+Официальная документация:
+
+- Yandex Foundation Models: `https://yandex.cloud/ru/docs/foundation-models/`;
+- Yandex AI Studio authentication: `https://yandex.cloud/ru/docs/ai-studio/api-ref/authentication`;
+- Yandex Foundation Models pricing: `https://yandex.cloud/ru/docs/foundation-models/pricing`;
+- GigaChat overview: `https://developers.sber.ru/docs/ru/gigachat/overview`;
+- GigaChat OAuth token: `https://developers.sber.ru/docs/ru/gigachat/api/reference/rest/post-token`;
+- GigaChat tariffs: `https://developers.sber.ru/docs/ru/gigachat/tariffs`.
+
 ## OpenAI
 
 Получение ключа OpenAI Platform: