Harden skill runtime and extraction workflow

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  offline-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check shell syntax
+        run: bash -n scripts/*.sh tests/*.sh
+      - name: Run offline tests
+        run: |
+          for test in tests/*.sh; do
+            echo "== $test"
+            bash "$test"
+          done

README.md

@@ -10,7 +10,7 @@
 
 ## Зависимости
 
-Требует доступ к [TasK API](https://task.ai-aid.pro) ([документация](https://docs.ai-aid.pro/redocly)). Для получения доступа — [напишите команде](https://task.ai-aid.pro/ru/team).
+Требует `bash`, `curl`, `jq`, GNU `realpath` и доступ к [TasK API](https://task.ai-aid.pro) ([документация](https://docs.ai-aid.pro/redocly)). Для получения доступа — [напишите команде](https://task.ai-aid.pro/ru/team).
 
 ## Установка
 
@@ -28,7 +28,19 @@ git clone https://github.com/prikotov/knowledge-extraction.git .agents/skills/kn
 }
 ```
 
-Скрипты ищут его, поднимаясь от своего расположения вверх по дереву папок до первого совпадения.
+Разместите `.task_token.json` в рабочем проекте, из которого запускаете Skill.
+Скрипты используют текущий каталог (`$PWD`) как начальную точку и ищут токен
+в нём и родительских каталогах. Для явного выбора каталога можно задать
+`KNOWLEDGE_EXTRACTION_WORKSPACE=/path/to/project`.
+
+Необязательный `.task_config.json` — конфигурация Skill. Сейчас он поддерживает
+переопределение адреса API:
+
+```json
+{
+  "api_url": "https://api.ai-aid.pro/v1"
+}
+```
 
 ## Как работает
 
@@ -89,24 +101,28 @@ Skill использует методы TasK API:
 
 ### Напрямую через скрипты
 
+Команды выполняются из корня рабочего проекта. После установки, показанной выше,
+путь к скриптам будет `.agents/skills/knowledge-extraction/scripts/`:
+
 ```bash
+
 # Загрузить материал
-./scripts/ingest.sh --source-url https://habr.com/ru/articles/1061876/
+.agents/skills/knowledge-extraction/scripts/ingest.sh --source-url https://habr.com/ru/articles/1061876/
 
 # Загрузить локальный файл (PDF, видео, аудио и т. п.)
-./scripts/ingest.sh --source-file "/path/to/video.mp4"
+.agents/skills/knowledge-extraction/scripts/ingest.sh --source-file "/path/to/video.mp4"
 
 # Начать диалог
-./scripts/chat.sh --source-url https://habr.com/ru/articles/1061876/
+.agents/skills/knowledge-extraction/scripts/chat.sh --source-url https://habr.com/ru/articles/1061876/
 
 # Продолжить диалог
-./scripts/chat.sh --chat <UUID> --question "Какие убеждения разбирает автор?"
+.agents/skills/knowledge-extraction/scripts/chat.sh --chat <UUID> --question "Какие убеждения разбирает автор?"
 
 # Поиск по чанкам
-./scripts/search.sh --source-url https://habr.com/ru/articles/1061876/ --query "локус контроля"
+.agents/skills/knowledge-extraction/scripts/search.sh --source-url https://habr.com/ru/articles/1061876/ --query "локус контроля"
 
 # Проверить статус обработки
-./scripts/ingest.sh --check
+.agents/skills/knowledge-extraction/scripts/ingest.sh --check
 
 # При ошибке API chat.sh завершится с ошибкой и напечатает, например:
 # HTTP 422: Need to top up balance.
@@ -121,7 +137,3 @@ Skill использует методы TasK API:
 ## Лицензия
 
 MIT
-
----
-
-> Постановка задачи, ревью — [Dmitry Prikotov](https://prikotov.pro/), реализация — deepseek-v4-pro в [pi](https://pi.dev) (интересно было посмотреть как deepseek-v4-pro справится с написанием скила, я страдал)

SKILL.md

@@ -1,19 +1,15 @@
 ---
 name: knowledge-extraction
 description: >-
-  Извлекает структурированные знания из любых внешних материалов (статьи,видео, документы).
-  Используй когда пользователь просит: изучить материал, дать резюме,
-  собрать саммари, сделать обзор, рассказать о чём статья/видео, разобрать
-  статью, найти цитаты или тезисы, подготовить краткое содержание,
-  поговорить с документом.
+  Извлекает структурированные знания из URL и локальных файлов без помещения всего
+  материала в контекст. Используй для статей, видео, аудио и документов,
+  когда пользователь просит изучить материал, сделать резюме или обзор, найти
+  подтверждённые цитаты и тезисы, поговорить с документом или работать с набором
+  связанных материалов как с единым контекстом.
 ---
 
 # Knowledge Extraction
 
-## Когда использовать
-
-- Убедись, что на уровне статьи есть `.task_token.json` и `.task_config.json` (доступ к TasK API).
-
 ## Как использовать
 
 ```text
@@ -25,13 +21,13 @@ ingest → chat   (поговорить с документом — приори
 
 ```bash
 # Загрузить один источник (ждёт готовности)
-./scripts/ingest.sh --source-url <URL>
+scripts/ingest.sh --source-url <URL>
 
 # Загрузить локальный файл (multipart/form-data)
-./scripts/ingest.sh --source-file "/path/to/video.mp4"
+scripts/ingest.sh --source-file "/path/to/video.mp4"
 
 # Проверить статусы всех источников (без ожидания)
-./scripts/ingest.sh --check
+scripts/ingest.sh --check
 ```
 
 Опции:
@@ -55,16 +51,16 @@ YouTube обрабатывается дольше — транскрибация
 
 ```bash
 # Новый диалог — вернёт chat_uuid=... первой строкой
-./scripts/chat.sh --source <UUID>
+scripts/chat.sh --source <UUID>
 
 # Или с несколькими источниками
-./scripts/chat.sh --source <UUID1> --source <UUID2>
+scripts/chat.sh --source <UUID1> --source <UUID2>
 
 # Или без источников — используются все source'ы проекта
-./scripts/chat.sh
+scripts/chat.sh
 
 # Продолжить диалог — указать chat_uuid из вывода предыдущего вызова
-./scripts/chat.sh --chat <UUID> --question "..."
+scripts/chat.sh --chat <UUID> --question "..."
 ```
 
 Опции:
@@ -78,11 +74,14 @@ YouTube обрабатывается дольше — транскрибация
 | `--title` | Нет | Заголовок первого source или «Диалог с материалом» |
 | `--project` | Нет | Из `.task_project.json` |
 
+Если вопрос относится ко всему набору материалов, не передавай `--source`: чат
+использует все sources проекта и сам подберёт релевантные фрагменты.
+
 Агент ведёт диалог, а не кидает все вопросы разом:
 
-1. `./scripts/chat.sh --source-url ... --title "Дороничев — прыжок веры"` — первый вопрос с осмысленным именем чата
+1. `scripts/chat.sh --source-url ... --title "Дороничев — прыжок веры"` — первый вопрос с осмысленным именем чата
 2. Читает ответ, видит пробелы или интересные нити
-3. `./scripts/chat.sh --chat <UUID> --question "..."` — уточняющий вопрос в том же чате
+3. `scripts/chat.sh --chat <UUID> --question "..."` — уточняющий вопрос в том же чате
 4. Повторяет, пока не извлечёт нужное
 
 **Не создавай новый чат без необходимости.** Если диалог уже начат — продолжай его через `--chat <UUID>`. Новый чат — только для нового материала или новой темы.
@@ -109,10 +108,10 @@ YouTube обрабатывается дольше — транскрибация
 
 ```bash
 # Один запрос — один вызов
-./scripts/search.sh --source <UUID> --query "запрос"
+scripts/search.sh --source <UUID> --query "запрос"
 
 # Прочитал результат, видишь пробел — следующий запрос
-./scripts/search.sh --source <UUID> --query "уточняющий запрос"
+scripts/search.sh --source <UUID> --query "уточняющий запрос"
 ```
 
 Опции:
@@ -126,9 +125,9 @@ YouTube обрабатывается дольше — транскрибация
 
 Агент ведёт поиск итеративно, как диалог:
 
-1. `./scripts/search.sh --query "основной тезис"` — первый запрос
+1. `scripts/search.sh --query "основной тезис"` — первый запрос
 2. Читает чанки, видит пробелы
-3. `./scripts/search.sh --query "уточнение по теме X"` — следующий запрос
+3. `scripts/search.sh --query "уточнение по теме X"` — следующий запрос
 4. Повторяет, пока не соберёт достаточно фактов
 
 ### Шаг 3: Оформить результат
@@ -138,41 +137,48 @@ YouTube обрабатывается дольше — транскрибация
 - **Саммари** — суть + ключевые тезисы с цитатами
 - **Факты** — утверждения автора с подтверждающими фрагментами
 - **Рекомендации** — выводы и практические следствия из материала
-- **Дайджест-карточка** — добавить авторский отклик и связи, сохранить в `research/саммари/`
+
+Соблюдай достоверность:
+
+- Отделяй утверждения автора от собственных выводов.
+- Не выдавай пересказ за точную цитату.
+- Для точной цитаты найди исходный чанк через `search.sh` и сверь формулировку.
+- Ссылайся на исходный URL или имя локального файла.
+- Если материал не подтверждает ответ или источники противоречат друг другу, скажи об этом явно.
 
 ### Примеры
 
-**Полный цикл для дайджеста:**
+**Полный цикл извлечения:**
 
 ```bash
 # 1. Загрузить
-./scripts/ingest.sh --source-url "https://habr.com/ru/articles/1061876/"
+scripts/ingest.sh --source-url "https://habr.com/ru/articles/1061876/"
 
 # 2. Начать диалог (вернёт chat_uuid=...)
-./scripts/chat.sh --source-url "https://habr.com/ru/articles/1061876/"
+scripts/chat.sh --source-url "https://habr.com/ru/articles/1061876/"
 
 # 3. Уточнить
-./scripts/chat.sh --chat <UUID> --question "Какие 4 убеждения разбирает автор?"
+scripts/chat.sh --chat <UUID> --question "Какие 4 убеждения разбирает автор?"
 
-# 4. Сохранить ответы, добавить отклик и связи
+# 4. Оформить подтверждённый материалом ответ
 ```
 
-**Диалог (без дайджеста):**
+**Диалог:**
 
 ```bash
-./scripts/ingest.sh --source-url "https://habr.com/ru/articles/1061876/"
-./scripts/chat.sh --source-url "https://habr.com/ru/articles/1061876/"
+scripts/ingest.sh --source-url "https://habr.com/ru/articles/1061876/"
+scripts/chat.sh --source-url "https://habr.com/ru/articles/1061876/"
 # → читаем ответ, задаём уточняющие вопросы через --chat <UUID>
 ```
 
 **Поиск чанков (запасной режим):**
 
 ```bash
-./scripts/search.sh --source-url "https://habr.com/ru/articles/1061876/" \
+scripts/search.sh --source-url "https://habr.com/ru/articles/1061876/" \
   --query "теория локуса контроля Роттера"
 
 # → читаем чанки, видим что не раскрыта тема таланта
-./scripts/search.sh --source-url "https://habr.com/ru/articles/1061876/" \
+scripts/search.sh --source-url "https://habr.com/ru/articles/1061876/" \
   --query "талант врождённый или приобретённый"
 ```
 
@@ -184,18 +190,16 @@ YouTube обрабатывается дольше — транскрибация
 
 **`search.sh`** — чанки с номерами и текстом в markdown.
 
-Для дайджест-карточки агент добавляет к выводу `chat.sh` или `search.sh` поля «Что откликнулось» и «Связи» и сохраняет в `research/саммари/<порядковый-номер>-<slug>.md`.
-
 ## Локальные файлы
 
-Один файл на уровне статьи — `.task_project.json`. Хранит UUID проекта, маппинг URL → source UUID и статус каждого источника (`pending` / `processing` / `ready` / `failed`). Создаётся автоматически при первом запуске `ingest.sh`.
+Один файл на уровне рабочего проекта — `.task_project.json`. Хранит UUID проекта, маппинг URL → source UUID и статус каждого источника (`pending` / `processing` / `ready` / `failed`). Создаётся автоматически при первом запуске `ingest.sh`.
 
 Статусы обновляются:
 - При загрузке — `ingest.sh` сохраняет актуальный статус после ожидания
 - Без ожидания — `ingest.sh --check` сверяет кеш с API и показывает изменения
 
 ```bash
-$ ./scripts/ingest.sh --check
+$ scripts/ingest.sh --check
 youtube.com/watch?v=... → processing ✦
 github.com/.../wsff.md → ready
 Изменений: 1