cristoferdomingues/BlackAgents

Modèles d'Application BlackAgents

Quand l'utiliser

À lire lors de l'implémentation d'une fonctionnalité ou d'une correction qui touche app/**, app/api/** ou lib/**. Les contraintes strictes se trouvent dans les règles typescript-strict et api-response-format ; ce fichier explique les couches et les recettes.

Architecture (respecter les couches)

UI (components/features/, client) ──fetch──▶ Routes API (app/api/**/route.ts)
                                                    │  { success, data | error }
                                              Domaine (lib/artifacts/, lib/standards/)
                                                    │  parse / serialize / graph
                                              Système de fichiers (lib/fs-service.ts)
                                                    │  resolveInWorkspace (pas d'échappement)
                                              Dossier Workspace (.cursor / .claude ...)

Règles de conduite :

• La logique pure et indépendante de la plateforme vit dans lib/artifacts/**. Elle n'importe jamais React ou next/server.
• Les préoccupations HTTP ne vivent que dans app/api/**/route.ts.
• Tout accès disque passe par lib/fs-service.ts ; n'appelez jamais node:fs directement depuis une route.

Conventions App Router

• Les pages sont des composants serveur par défaut ; ajoutez "use client" uniquement pour l'interactivité/l'état/les effets.
• Groupes de routes : /agents, /commands, /rules, /skills ont chacun une page de liste, une page d'édition [name] et une page new ; /new est l'assistant guidé. Autres routes : /graph, /standards, /export, /sync, /chat, /providers, /settings.
• Les composants de fonctionnalités côté client récupèrent les données via apiFetch (lib/api.ts) et lisent l'état du workspace actif depuis WorkspaceProvider — pas de fetch brut ni de lecture directe de la configuration côté client.

Recette des Routes API

import { ok, fail, handle } from "@/lib/api-response"
import { artifactInputSchema } from "@/lib/artifacts/schemas"

export async function POST(req: Request) {
  return handle(async () => {
    const parsed = artifactInputSchema.safeParse(await req.json())
    if (!parsed.success) return fail(parsed.error.issues[0].message, 400)
    // ...travail domaine via lib/artifacts + lib/fs-service...
    return ok({ /* données */ })
  })
}

• Retournez toujours via ok / fail ; enveloppez dans handle pour que les exceptions deviennent une enveloppe 500.
• Lisez la racine du workspace depuis la configuration (lib/config.ts), puis utilisez resolveInWorkspace(root, relPath).
• Lisez les secrets avec lib/secrets.ts côté serveur uniquement ; identifiants manquants → fail("...", 412).

Le Modèle du Domaine

lib/artifacts/ :

• types.ts — Artifact, ArtifactType, Platform, ArtifactFrontmatter (indépendant de l'outil).
• layout.ts — PLATFORM_LAYOUTS + artifactRelPath() / artifactDeletePath() ; le seul endroit qui connaît les dossiers/extensions d'une plateforme. ACTIVE_PLATFORMS = ["cursor", "claude"], défaut cursor.
• parser.ts — scanWorkspace(root) et parseArtifact (via gray-matter) ; les skills sont un dossier <name>/SKILL.md parcouru récursivement.
• serializer.ts — serializeArtifact(input) écrit le frontmatter + le corps ; les règles omettent name (identifié par le nom de fichier).
• schemas.ts — nameSchema (kebab-case), artifactInputSchema, normalizeExtra (frontmatter par type).
• graph.ts — extrait les références croisées des conventions de rédaction.

Conventions de Références Croisées (ce que le graphe lit)

De → Vers	Convention dans le corps
Commande → Agent	nom-agent (gras)
Agent → Règle	`nom-règle` règle
Agent → Skill	`nom-skill` skill
Règle → Règle	Règles liées : a, b.
Règle → Skill	Voir aussi : skill x.

Rédigez les corps avec ces conventions exactes pour que le graphe de relations et la détection de liens de l'assistant les prennent en compte.

Sécurité du Système de Fichiers

export function resolveInWorkspace(root: string, relativePath: string): string {
  // résout relativePath sous root et lève WorkspaceError s'il s'échappe
}

Chaque lecture/écriture doit être construite à partir d'un chemin relatif au workspace via cette fonction. Ne concaténez jamais de chemins absolus et n'acceptez pas de chemin absolu fourni par le client.

Persistance en Dehors du Workspace

• ~/.black-agents/config.json — workspaces sauvegardés + currentPath actif (lib/config.ts).
• ~/.black-agents/secrets.json — clés LLM, mode 0600, serveur uniquement (lib/secrets.ts).
• <workspace>/.black-agents/standards.md — surcharge des normes de rédaction par workspace.
• Surchargez le dossier de configuration avec BLACK_AGENTS_CONFIG_DIR (utile dans les tests).

Comment Utiliser

Référence uniquement. La personnalité et le flux de travail vivent dans l'agent feature-developer ; les garde-fous vivent dans les règles typescript-strict et api-response-format. Utilisez ce fichier pour placer la logique dans la bonne couche et copier la recette de route, puis confiez l'UI à l'agent uiux-designer et la couverture de tests à l'agent tester.