code-ai-installer 3.0.0 → 4.0.0

package/domains/development/.agents/skills/n8n-pinecone-qdrant-supabase/agents/kimi.yaml

@@ -1,16 +1,16 @@
-name: "n8n-pinecone-qdrant-supabase"
-display_name: "Связка n8n, Pinecone/Qdrant и Supabase"
-description: "Паттерны интеграции n8n (автоматизация workflows) с векторными БД Pinecone и Qdrant и с Supabase (PostgreSQL + Auth + Storage + Realtime). Используй этот скилл при построении AI-пайплайнов, RAG-систем, автоматизации данных, работе с эмбеддингами, семантическом поиске, или любой оркестрации между этими инструментами. Активируй при вопросах про n8n workflows, векторный поиск, upsert эмбеддингов, Supabase RLS, или построение RAG поверх этого стека."
-default_prompt: "Используй $n8n-pinecone-qdrant-supabase, когда задача относится к навыку \"Связка n8n, Pinecone/Qdrant и Supabase\"."
-triggers:
-  - "n8n-pinecone-qdrant-supabase"
-  - "n8n pinecone qdrant supabase"
-  - "Связка n8n, Pinecone/Qdrant и Supabase"
-  - "Паттерны интеграции n8n (автоматизация workflows) с векторными БД Pinecone и Qdrant и с Supabase (PostgreSQL + Auth + Storage + Realtime)"
-capabilities:
-  - "n8n"
-  - "pinecone"
-  - "qdrant"
-  - "supabase"
-tools: []
-implicit_invocation: true
+name: "n8n-pinecone-qdrant-supabase"
+display_name: "Связка n8n, Pinecone/Qdrant и Supabase"
+description: "Паттерны интеграции n8n (автоматизация workflows) с векторными БД Pinecone и Qdrant и с Supabase (PostgreSQL + Auth + Storage + Realtime). Используй этот скилл при построении AI-пайплайнов, RAG-систем, автоматизации данных, работе с эмбеддингами, семантическом поиске, или любой оркестрации между этими инструментами. Активируй при вопросах про n8n workflows, векторный поиск, upsert эмбеддингов, Supabase RLS, или построение RAG поверх этого стека."
+default_prompt: "Используй $n8n-pinecone-qdrant-supabase, когда задача относится к навыку \"Связка n8n, Pinecone/Qdrant и Supabase\"."
+triggers:
+  - "n8n-pinecone-qdrant-supabase"
+  - "n8n pinecone qdrant supabase"
+  - "Связка n8n, Pinecone/Qdrant и Supabase"
+  - "Паттерны интеграции n8n (автоматизация workflows) с векторными БД Pinecone и Qdrant и с Supabase (PostgreSQL + Auth + Storage + Realtime)"
+capabilities:
+  - "n8n"
+  - "pinecone"
+  - "qdrant"
+  - "supabase"
+tools: []
+implicit_invocation: true

package/domains/development/.agents/skills/n8n-pinecone-qdrant-supabase-reference/SKILL.md

@@ -0,0 +1,594 @@
+---
+name: n8n-pinecone-qdrant-supabase-reference
+description: Канонический справочник шаблонов для стека n8n + Pinecone + Qdrant + Supabase + RAG — n8n Code-нодные templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Растущая библиотека reference templates для ARCH+DEV гейтов.
+type: reference
+domain: development
+owners:
+  - architect
+  - senior_full_stack
+gates:
+  - ARCH
+  - DEV
+tech:
+  - n8n
+topic:
+  - architecture
+  - general
+triggers:
+  - n8n Code transform пример
+  - Pinecone upsert batch
+  - Qdrant collection setup
+  - Supabase pgvector match_documents
+  - RAG prompt builder
+  - hybrid_search RRF
+related:
+  - n8n-pinecone-qdrant-supabase
+  - architecture-doc-reference
+  - api-contracts-reference
+  - security-baseline-dev
+  - observability-plan
+  - data-model
+budget_lines: 650
+schema_version: 1
+---
+
+
+# Skill: n8n + Pinecone + Qdrant + Supabase — Reference
+
+Канонические шаблоны для стека. Workflow rules + DO/DON'T + Output Template → `$n8n-pinecone-qdrant-supabase`.
+
+**Разделы:**
+1. [n8n Code templates](#1-n8n-code)
+2. [Pinecone JSON](#2-pinecone)
+3. [Qdrant JSON](#3-qdrant)
+4. [Supabase SQL+REST](#4-supabase)
+5. [RAG templates](#5-rag)
+6. [n8n + Supabase JS](#6-n8n-supabase)
+7. [Growing library](#7-growing)
+
+---
+
+## 1. n8n Code templates
+
+### 1.1 Transform all items с ранней валидацией
+
+```js
+// n8n Code node — обрабатывает все items
+const results = [];
+
+for (const item of $input.all()) {
+  const { text, sourceId, metadata } = item.json;
+
+  // ✅ Ранняя проверка — пропускаем невалидные items
+  if (!text || typeof text !== "string") {
+    continue; // или: throw new Error(`Item ${sourceId}: missing text`);
+  }
+
+  results.push({
+    json: {
+      id:       sourceId,
+      content:  text.trim().slice(0, 8000), // ✅ обрезаем до лимита эмбеддинга
+      metadata: {
+        ...metadata,
+        processedAt: new Date().toISOString(),
+      },
+    },
+  });
+}
+
+return results;
+```
+
+### 1.2 Chunking с overlap
+
+```js
+// Code node: chunking с overlap
+function chunkText(text, chunkSize = 1000, overlap = 200) {
+  const chunks = [];
+  let start = 0;
+
+  while (start < text.length) {
+    const end = Math.min(start + chunkSize, text.length);
+    chunks.push({
+      text:       text.slice(start, end),
+      chunkIndex: chunks.length,
+      startChar:  start,
+      endChar:    end,
+    });
+    start += chunkSize - overlap; // ✅ overlap сохраняет контекст на стыках
+  }
+
+  return chunks;
+}
+
+const { content, docId, metadata } = $input.first().json;
+const chunks = chunkText(content);
+
+return chunks.map((chunk, i) => ({
+  json: {
+    id:      `${docId}_chunk_${i}`,
+    text:    chunk.text,
+    metadata: { ...metadata, docId, chunkIndex: i, totalChunks: chunks.length },
+  },
+}));
+```
+
+### 1.3 Error-workflow setup
+
+```
+1. Settings → Error Workflow → указать отдельный error-workflow
+2. В error-workflow: получаем $execution.error → логируем в Supabase/Slack
+3. Для HTTP Request нод: включай "Continue on Fail" + проверяй статус в следующей ноде
+```
+
+### 1.4 HTTP response checker
+
+```js
+// Code node: проверка ответа HTTP Request
+const response = $input.first().json;
+
+if (response.error || response.statusCode >= 400) {
+  throw new Error(`API error: ${response.statusCode} — ${JSON.stringify(response.error)}`);
+}
+
+return [{ json: response }];
+```
+
+---
+
+## 2. Pinecone JSON
+
+### 2.1 Upsert batch (Code prep + HTTP body)
+
+```js
+// Code node: подготовка батча для Pinecone upsert
+const items = $input.all();
+
+const vectors = items.map(item => ({
+  id:       item.json.id,          // уникальный string ID
+  values:   item.json.embedding,   // float[] от модели эмбеддинга
+  metadata: {
+    // ✅ Только примитивы: string, number, boolean, string[]
+    text:       item.json.text.slice(0, 1000), // Pinecone лимит metadata ~40KB
+    sourceUrl:  item.json.sourceUrl,
+    docId:      item.json.docId,
+    chunkIndex: item.json.chunkIndex,
+    updatedAt:  new Date().toISOString(),
+  },
+}));
+
+// Батч по 100 (лимит Pinecone upsert)
+const batchSize = 100;
+const batches = [];
+for (let i = 0; i < vectors.length; i += batchSize) {
+  batches.push({ json: { vectors: vectors.slice(i, i + batchSize) } });
+}
+
+return batches;
+```
+
+```
+HTTP Request: POST https://YOUR_INDEX.svc.YOUR_ENV.pinecone.io/vectors/upsert
+Headers: Api-Key: {{ $vars.PINECONE_API_KEY }}, Content-Type: application/json
+Body: { "vectors": {{ $json.vectors }}, "namespace": "docs_product" }
+```
+
+### 2.2 Query с фильтрами
+
+```json
+{
+  "vector":          "{{ $json.queryEmbedding }}",
+  "topK":            10,
+  "namespace":       "docs_product",
+  "includeMetadata": true,
+  "filter": {
+    "docId":     { "$eq": "manual_v2" },
+    "updatedAt": { "$gte": "2024-01-01" }
+  }
+}
+```
+
+```js
+// Code node: обработка результатов поиска
+const matches = $input.first().json.matches ?? [];
+
+// ✅ Фильтруем по score — отсекаем слабые совпадения
+const relevant = matches
+  .filter(m => m.score >= 0.75)
+  .map(m => ({
+    text:      m.metadata.text,
+    score:     m.score,
+    sourceUrl: m.metadata.sourceUrl,
+    chunkIndex: m.metadata.chunkIndex,
+  }));
+
+return [{ json: { matches: relevant, count: relevant.length } }];
+```
+
+### 2.3 Delete by filter
+
+```json
+{
+  "filter":    { "docId": { "$eq": "manual_v1" } },
+  "namespace": "docs_product",
+  "deleteAll": false
+}
+```
+
+---
+
+## 3. Qdrant JSON
+
+### 3.1 Collection setup
+
+```json
+{
+  "vectors": {
+    "size":     1536,
+    "distance": "Cosine"
+  },
+  "optimizers_config": {
+    "default_segment_number": 2
+  },
+  "replication_factor": 1
+}
+```
+
+### 3.2 Upsert points
+
+```js
+// Code node: подготовка для Qdrant upsert
+const points = $input.all().map(item => ({
+  id:      item.json.id,         // ✅ uint64 или UUID string
+  vector:  item.json.embedding,
+  payload: {
+    text:       item.json.text,
+    docId:      item.json.docId,
+    chunkIndex: item.json.chunkIndex,
+    sourceUrl:  item.json.sourceUrl,
+    language:   item.json.language ?? "ru",
+    createdAt:  Math.floor(Date.now() / 1000), // ✅ unix timestamp для range-фильтров
+  },
+}));
+
+return [{ json: { points } }];
+```
+
+```
+PUT /collections/documents/points
+Body: { "points": {{ $json.points }} }
+```
+
+### 3.3 Search с payload-фильтрами
+
+```json
+{
+  "vector":       "{{ $json.queryEmbedding }}",
+  "limit":        10,
+  "with_payload": true,
+  "filter": {
+    "must": [
+      { "key": "language", "match": { "value": "ru" } },
+      { "key": "createdAt", "range": { "gte": 1704067200 } }
+    ],
+    "must_not": [
+      { "key": "docId", "match": { "value": "draft_123" } }
+    ]
+  },
+  "score_threshold": 0.70
+}
+```
+
+### 3.4 Scroll (export / batch update)
+
+```json
+{
+  "limit":        100,
+  "with_payload": true,
+  "with_vector":  false,
+  "filter": {
+    "must": [{ "key": "docId", "match": { "value": "manual_v1" } }]
+  },
+  "offset": null
+}
+```
+
+Следующая страница: `"offset": last_result.next_page_offset`.
+
+### 3.5 Named vectors (multi-modal)
+
+```json
+{
+  "vectors": {
+    "text":  { "size": 1536, "distance": "Cosine" },
+    "image": { "size": 512,  "distance": "Cosine" }
+  }
+}
+```
+
+Поиск только по text-вектору:
+```json
+{ "vector": { "name": "text", "vector": [...] }, "limit": 5 }
+```
+
+---
+
+## 4. Supabase SQL+REST
+
+### 4.1 pgvector setup + HNSW index + match_documents
+
+```sql
+-- Включить расширение (один раз)
+create extension if not exists vector;
+
+-- Таблица с эмбеддингами
+create table documents (
+  id          uuid primary key default gen_random_uuid(),
+  content     text        not null,
+  embedding   vector(1536),          -- размер под модель
+  metadata    jsonb        default '{}',
+  user_id     uuid         references auth.users(id),
+  created_at  timestamptz  default now()
+);
+
+-- ✅ HNSW индекс — быстрее IVFFlat для большинства случаев
+create index on documents
+  using hnsw (embedding vector_cosine_ops)
+  with (m = 16, ef_construction = 64);
+
+-- Функция семантического поиска
+create or replace function match_documents(
+  query_embedding vector(1536),
+  match_threshold float  default 0.75,
+  match_count     int    default 10,
+  filter_user_id  uuid   default null
+)
+returns table (
+  id         uuid,
+  content    text,
+  metadata   jsonb,
+  similarity float
+)
+language sql stable
+as $$
+  select
+    id,
+    content,
+    metadata,
+    1 - (embedding <=> query_embedding) as similarity
+  from documents
+  where
+    (filter_user_id is null or user_id = filter_user_id)
+    and 1 - (embedding <=> query_embedding) > match_threshold
+  order by embedding <=> query_embedding
+  limit match_count;
+$$;
+```
+
+### 4.2 RLS policies
+
+```sql
+-- ✅ Включить RLS на таблице
+alter table documents enable row level security;
+
+-- Пользователь видит только свои документы
+create policy "users_own_documents"
+  on documents for all
+  using (auth.uid() = user_id)
+  with check (auth.uid() = user_id);
+
+-- service_role обходит RLS — используй только на бэкенде/n8n
+-- anon/authenticated подчиняется RLS — используй на клиенте
+```
+
+### 4.3 REST: вызов match_documents из n8n
+
+```
+POST https://YOUR_PROJECT.supabase.co/rest/v1/rpc/match_documents
+Headers:
+  apikey: {{ $vars.SUPABASE_SERVICE_KEY }}
+  Authorization: Bearer {{ $vars.SUPABASE_SERVICE_KEY }}
+  Content-Type: application/json
+```
+
+```json
+{
+  "query_embedding":  "{{ $json.embedding }}",
+  "match_threshold":  0.75,
+  "match_count":      10,
+  "filter_user_id":   null
+}
+```
+
+### 4.4 Realtime webhook setup
+
+```
+Supabase → Database Webhooks → при INSERT/UPDATE в таблицу → POST на n8n Webhook URL
+
+Настройка в Supabase Dashboard:
+  Database → Webhooks → Create Webhook
+    Table:  documents
+    Events: INSERT
+    URL:    https://YOUR_N8N.com/webhook/process-document
+    HTTP Method: POST
+```
+
+### 4.5 Storage upload
+
+```
+POST https://YOUR_PROJECT.supabase.co/storage/v1/object/documents/{{ $json.fileName }}
+Headers: apikey, Authorization, Content-Type: application/octet-stream
+Body: бинарный файл
+```
+
+После загрузки — сохранить метаданные:
+```json
+// POST /rest/v1/document_metadata
+{
+  "file_path":   "documents/{{ $json.fileName }}",
+  "bucket":      "documents",
+  "size_bytes":  "{{ $json.fileSize }}",
+  "mime_type":   "{{ $json.mimeType }}",
+  "uploaded_by": "{{ $json.userId }}"
+}
+```
+
+---
+
+## 5. RAG templates
+
+### 5.1 RAG prompt builder
+
+```js
+// Code нода: построение RAG-промпта
+const question = $input.first().json.question;
+const chunks   = $input.first().json.matches; // из vector search
+
+const context = chunks
+  .map((c, i) => `[${i + 1}] ${c.text}`)
+  .join("\n\n");
+
+const messages = [
+  {
+    role: "system",
+    content: `Ты помощник. Отвечай ТОЛЬКО на основе предоставленного контекста.
+Если ответа нет в контексте — скажи "Информация не найдена".
+Контекст:
+${context}`,
+  },
+  {
+    role: "user",
+    content: question,
+  },
+];
+
+return [{ json: { messages } }];
+```
+
+### 5.2 hybrid_search RRF (Supabase)
+
+```sql
+-- Supabase: vector + full-text Reciprocal Rank Fusion
+create or replace function hybrid_search(
+  query_text      text,
+  query_embedding vector(1536),
+  match_count     int default 10
+)
+returns table (id uuid, content text, score float)
+language sql stable as $$
+  with semantic as (
+    select id, content,
+           1 - (embedding <=> query_embedding) as score,
+           row_number() over (order by embedding <=> query_embedding) as rank
+    from documents
+    limit 50
+  ),
+  fulltext as (
+    select id, content,
+           ts_rank(to_tsvector('russian', content), plainto_tsquery('russian', query_text)) as score,
+           row_number() over (order by score desc) as rank
+    from documents
+    where to_tsvector('russian', content) @@ plainto_tsquery('russian', query_text)
+    limit 50
+  )
+  select
+    coalesce(s.id, f.id) as id,
+    coalesce(s.content, f.content) as content,
+    coalesce(1.0/(60 + s.rank), 0) + coalesce(1.0/(60 + f.rank), 0) as score
+  from semantic s
+  full outer join fulltext f on s.id = f.id
+  order by score desc
+  limit match_count;
+$$;
+```
+
+---
+
+## 6. n8n + Supabase JS
+
+### 6.1 PostgREST query builder
+
+```js
+// Code нода: построение запроса с фильтрами
+const { userId, status, limit = 20, offset = 0 } = $input.first().json;
+
+// ✅ Supabase PostgREST фильтры
+const params = new URLSearchParams({
+  user_id: `eq.${userId}`,
+  ...(status && { status: `eq.${status}` }),
+  order:  "created_at.desc",
+  limit:  limit.toString(),
+  offset: offset.toString(),
+});
+
+return [{ json: { queryString: params.toString() } }];
+```
+
+```
+HTTP Request: GET /rest/v1/documents?{{ $json.queryString }}
+Headers: apikey, Authorization, Range: 0-19 (для пагинации)
+✅ Prefer: count=exact — вернёт Content-Range заголовок с total count
+```
+
+### 6.2 Upsert с conflict resolution
+
+```
+POST /rest/v1/documents
+Headers: Prefer: resolution=merge-duplicates
+```
+
+```json
+{
+  "id":         "{{ $json.docId }}",
+  "content":   "{{ $json.content }}",
+  "updated_at": "{{ $now }}"
+}
+```
+
+`merge-duplicates` обновит существующий, создаст новый если нет. `ignore-duplicates` пропустит если уже есть.
+
+### 6.3 Error handler
+
+```js
+// Code нода после HTTP Request к Supabase
+const { statusCode, body } = $input.first().json;
+
+if (statusCode === 409) {
+  // Конфликт — запись уже существует, это OK
+  return [{ json: { status: "already_exists", ...body } }];
+}
+
+if (statusCode >= 400) {
+  // ✅ Кидаем с деталями — попадёт в error workflow
+  throw new Error(`Supabase error ${statusCode}: ${JSON.stringify(body)}`);
+}
+
+return [{ json: { status: "ok", data: body } }];
+```
+
+---
+
+## 7. Growing library
+
+Канонические шаблоны добавляются через `update_skill` MCP-инструмент по мере появления потребности. Кандидаты:
+
+- **Cost tracking** — Supabase table `embedding_costs` + n8n Code node для tally tokens × price
+- **Embedding cache** — Redis/Supabase lookup before OpenAI call, hash(text) → embedding
+- **Dimension migration helpers** — re-embed + re-upsert workflow при смене модели
+- **Weaviate templates** — schema, hybrid search, multi-tenancy
+- **Chroma templates** — collection, query, persistence
+- **Milvus templates** — collection, index types (IVF/HNSW), partition keys
+- **Retrieval re-ranking** — Cohere Rerank / cross-encoder integration
+- **n8n sub-workflow throttling** — рекурсивные workflow с rate-limit
+- **Embedding model variants** — Cohere / Voyage / sentence-transformers
+- **Vector dimension reduction** — Matryoshka embeddings (OpenAI dimensions param)
+
+---
+
+## См. также
+- `$n8n-pinecone-qdrant-supabase` — workflow rules + DO/DON'T + RAG ASCII + Output Template
+- `$architecture-doc-reference` — canonical разделы architecture doc
+- `$api-contracts-reference` — REST endpoint templates
+- `$security-baseline-dev` — secrets management
+- `$observability-plan` — логирование, метрики
+- `$data-model` — vector dimensions, schema

package/domains/development/.agents/skills/n8n-pinecone-qdrant-supabase-reference/agents/claude.json

@@ -0,0 +1,21 @@
+{
+  "name": "n8n-pinecone-qdrant-supabase-reference",
+  "display_name": "Справочник шаблонов n8n + Pinecone/Qdrant + Supabase",
+  "description": "Канонический справочник шаблонов для стека n8n + Pinecone + Qdrant + Supabase + RAG — n8n Code-нодные templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Растущая библиотека reference templates для ARCH+DEV гейтов.",
+  "default_prompt": "Используй $n8n-pinecone-qdrant-supabase-reference, когда задача относится к навыку \"Справочник шаблонов n8n + Pinecone/Qdrant + Supabase\".",
+  "triggers": [
+    "n8n-pinecone-qdrant-supabase-reference",
+    "n8n pinecone qdrant supabase reference",
+    "Справочник шаблонов n8n + Pinecone/Qdrant + Supabase",
+    "Паттерны интеграции n8n (автоматизация workflows) с векторными БД Pinecone и Qdrant и с Supabase (PostgreSQL + Auth + Storage + Realtime)"
+  ],
+  "capabilities": [
+    "n8n",
+    "pinecone",
+    "qdrant",
+    "supabase",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/n8n-pinecone-qdrant-supabase-reference/agents/copilot.json

@@ -0,0 +1,21 @@
+{
+  "name": "n8n-pinecone-qdrant-supabase-reference",
+  "display_name": "Справочник шаблонов n8n + Pinecone/Qdrant + Supabase",
+  "description": "Канонический справочник шаблонов для стека n8n + Pinecone + Qdrant + Supabase + RAG — n8n Code-нодные templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Растущая библиотека reference templates для ARCH+DEV гейтов.",
+  "default_prompt": "Используй $n8n-pinecone-qdrant-supabase-reference, когда задача относится к навыку \"Справочник шаблонов n8n + Pinecone/Qdrant + Supabase\".",
+  "triggers": [
+    "n8n-pinecone-qdrant-supabase-reference",
+    "n8n pinecone qdrant supabase reference",
+    "Справочник шаблонов n8n + Pinecone/Qdrant + Supabase",
+    "Паттерны интеграции n8n (автоматизация workflows) с векторными БД Pinecone и Qdrant и с Supabase (PostgreSQL + Auth + Storage + Realtime)"
+  ],
+  "capabilities": [
+    "n8n",
+    "pinecone",
+    "qdrant",
+    "supabase",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/.agents/skills/n8n-pinecone-qdrant-supabase-reference/agents/gemini.json

@@ -0,0 +1,21 @@
+{
+  "name": "n8n-pinecone-qdrant-supabase-reference",
+  "display_name": "Справочник шаблонов n8n + Pinecone/Qdrant + Supabase",
+  "description": "Канонический справочник шаблонов для стека n8n + Pinecone + Qdrant + Supabase + RAG — n8n Code-нодные templates, Pinecone/Qdrant JSON HTTP bodies, Supabase pgvector/RLS/match_documents SQL, REST endpoints, RAG prompt builder, hybrid_search RRF. Растущая библиотека reference templates для ARCH+DEV гейтов.",
+  "default_prompt": "Используй $n8n-pinecone-qdrant-supabase-reference, когда задача относится к навыку \"Справочник шаблонов n8n + Pinecone/Qdrant + Supabase\".",
+  "triggers": [
+    "n8n-pinecone-qdrant-supabase-reference",
+    "n8n pinecone qdrant supabase reference",
+    "Справочник шаблонов n8n + Pinecone/Qdrant + Supabase",
+    "Паттерны интеграции n8n (автоматизация workflows) с векторными БД Pinecone и Qdrant и с Supabase (PostgreSQL + Auth + Storage + Realtime)"
+  ],
+  "capabilities": [
+    "n8n",
+    "pinecone",
+    "qdrant",
+    "supabase",
+    "reference"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}