Promotion de contenu

Le contenu atteint un domaine de base de connaissances organisationnelle via le broker de plateforme — une surface client unique (plugin @scrydon/better-auth-orgkb) que toutes les applications utilisent à la place de clients api-ontology construits manuellement. Il existe deux chemins de finalisation et un chemin initié par l'utilisateur.

Le client broker — deux niveaux

Le broker expose deux niveaux. Choisissez le bon selon qu'il y a ou non une session utilisateur en cours.

Niveau session — lectures et actions initiées par l'utilisateur

Utilisez getClientWithAuth({ headers }) pour toute action effectuée par un utilisateur : parcourir les lignes promues, soumettre une promotion manuelle, examiner une demande en attente, gérer les marquages.

import { getClientWithAuth } from "@scrydon/multi-tenancy/auth/client";

// In a server function or route handler that holds the user's request headers.
const client = getClientWithAuth({ headers });

// List promoted rows from a governed domain.
const { data } = await client.orgKb.partitionRows({
  organizationId,
  partitionSlug: "learnings",
});

// Review a pending promotion request.
await client.orgKb.reviewPromotion({
  organizationId,
  promotionRequestId,
  decision: "approve",
  reason: "Verified — correct insight, no PII.",
});

Méthodes disponibles au niveau session : listPartitions, listPartitionObjectTypes, resolvePromotionTarget, listPromotions, reviewPromotion, cancelPromotion, promote, partitionRows, query, rowHistory, revokeRow, listMarkings, createMarking, deleteDomain, exportAuditBundle, resolveTable.

Niveau admin M2M — opérations système

Utilisez getAdminClient().orgKb.admin.* pour les opérations initiées par le système : la condensation des apprentissages, la mise en file d'attente de mutations depuis un job en arrière-plan, ou toute opération sans session utilisateur en cours.

import { getAdminClient } from "@scrydon/multi-tenancy/auth/client";

// Trigger the learnings condense. Pass all pages of the linked workspace KB.
const { data, error } = await getAdminClient().orgKb.admin.promoteLearnings({
  organizationId,         // Always server-derived — never from the client.
  workspaceId,
  workspaceEnvironmentId,
  knowledgeBaseId,
  partitionSlug,          // e.g. "learnings"
  objectTypeSlug,         // e.g. "ProjectLearning"
  pages,                  // { pageId, title, path, body }[]
});
if (error) throw new Error(error.message ?? `promoteLearnings failed (${error.status})`);

Méthodes disponibles au niveau admin : promoteLearnings, enqueueMutation.

Chemin de finalisation A — action d'approbation avec promoteToOrgKb

Déclarez le déclencheur de finalisation dans le manifeste du process flow. Ajoutez promoteToOrgKb: true aux métadonnées d'une action approval :

import { defineAction } from "@scrydon/sdk-authoring/process-flows";

defineAction({
  name: "Sign off on project review",
  actionType: "approval",
  isRequired: true,
  metadata: {
    persona: "knowledge-lead",
    promoteToOrgKb: true,   // Triggers learnings condense on approval completion.
  },
})

Quand l'étape contenant cette tâche se termine (l'approbation est accordée), la plateforme automatiquement :

1. Rassemble toutes les pages de la KB de l'espace de travail liée à cette instance de process.
2. Effectue un scan DLP sur le corpus de pages.
3. Exécute un seul passage LLM sur l'ensemble de la KB pour extraire un ensemble discret et dédupliqué d'enregistrements d'apprentissage typés, conformes au schéma de propriétés du type d'objet cible.
4. Effectue un scan DLP sur les apprentissages produits.
5. Met en file d'attente chaque apprentissage via getAdminClient().orgKb.admin.enqueueMutation(...).

L'approbation EST la porte de vérification humaine — aucune action de promotion séparée n'est nécessaire.

Chemin de finalisation B — bouton manuel Workspace-Admin

Un bouton Promouvoir les apprentissages apparaît dans l'en-tête de la KB de l'espace de travail pour les utilisateurs ayant le rôle Workspace Admin. Cliquer dessus déclenche la même condensation que le chemin A.

Ce chemin est utile pour la promotion itérative pendant un travail actif — avant qu'un process se finalise formellement, ou pour des KB d'espace de travail autonomes non liées à un process flow.

La route est réservée aux Workspace Admins uniquement. Les non-admins ne voient pas le bouton, et la route sous-jacente retourne 403 pour les non-admins quel que soit le cas.

Comment fonctionne la condensation

Les deux chemins appellent en fin de compte getAdminClient().orgKb.admin.promoteLearnings(...). Le broker de plateforme :

1. Effectue un scan DLP sur le corpus de pages (avant que le LLM ne le voie).
2. Appelle resolvePromotionTarget pour récupérer le schéma de propriétés du type d'objet cible depuis api-ontology.
3. Exécute un seul passage LLM sur l'ensemble du corpus KB (via getPlatformCapabilityRuntime().completeLlm), produisant un ensemble d'enregistrements d'apprentissage discrets dont le contenu est déterminé — fusionner les doublons, un enregistrement par insight durable, sans compte fixe.
4. Effectue un scan DLP sur les apprentissages produits.
5. Met en file d'attente chaque apprentissage via getAdminClient().orgKb.admin.enqueueMutation(...) → org_kb_mutation_queue api-ontology → consommateur existant → promotion_request → Revue → matérialiseur.

Sécurité par défaut : si le LLM n'est pas configuré ou si sa sortie ne peut pas être analysée, zéro apprentissage est mis en file d'attente. Le contenu non extrait n'est jamais écrit dans un domaine typé.

Identité de ligne et idempotence

Chaque apprentissage a une identité de ligne stable :

rowId = "kblearning:" + sha256(canonicalTitle + "|" + objectTypeSlug)

où canonicalTitle = title.toLowerCase().trim().replace(/\s+/g, " ").

Refinaliser la même KB de l'espace de travail met à jour les apprentissages dont le contenu a changé, ajoute de nouveaux apprentissages, et ne fait rien pour les apprentissages dont le contenu est identique. Vous n'accumulerez pas d'éléments de Revue dupliqués lors de refinalisations répétées.

Références — liens vers les pages source

Chaque apprentissage porte automatiquement un champ references :

references: Array<{ pageId: string; title: string; path: string }>

Les références listent les pages KB de l'espace de travail dont l'apprentissage a été dérivé. Elles sont assemblées par promoteLearnings avant le passage LLM — pas devinées par le modèle. partitionRows et query retournent references avec les autres propriétés de chaque ligne promue.

references est une colonne système réservée sur chaque table de domaine org-KB. Les auteurs de packs n'ont pas besoin de la déclarer ; le provisionneur la crée automatiquement sur chaque table de domaine.

Supprimer un domaine

Un administrateur de l'organisation peut supprimer un domaine depuis Settings → Organization → Knowledgebase → Domains : ouvrez le menu ⋯ du domaine et choisissez Supprimer le domaine…. Cela supprime définitivement le domaine — son contenu, sa table gérée dans le stockage, et sa piste d'audit de promotion/révocation signée. Comme l'action est irréversible, le bouton de confirmation reste désactivé jusqu'à ce que vous saisissiez le slug du domaine.

Les domaines provisionnés par un pack seront recréés si le pack est re-synchronisé ou mis à niveau. Pour supprimer définitivement un domaine provisionné par un pack, désinstallez également le pack. Seuls les administrateurs de l'organisation peuvent supprimer un domaine.