Architecture

La version courte

Il n’y a qu’une seule source de vérité — un corpus de fichiers Markdown dans git — et tout le reste en est généré ou le lit : le site web en sept langues, les fichiers pour agents, l’assistant Ask Jenks, l’API REST, les serveurs MCP et la CLI.

Le corpus

content/corpus/ contient un fichier Markdown par expérience, projet, rôle communautaire et entrée de formation, chacun avec du frontmatter YAML (dates, tags, lentilles de rôle, résultats clés, compétences, liens de preuve) et un corps long. À côté se trouvent le profil principal, les capacités, les justificatifs, les talks, la vision du monde, les lentilles de rôle et les compétences de l’assistant. Les faits ont été rassemblés à partir des CV de Jenks, de LinkedIn, de Linktree et de sa page d’orateur, avec des conflits résolus de manière prudente.

Garder le corpus dans git signifie que chaque modification est un commit : révisable, attribuable et réversible.

Le compilateur

scripts/build-corpus.mjs lit le corpus, valide chaque fichier contre un schéma unique (scripts/corpus-schema.mjs) et le compile en un corpus JSON unique plus les fichiers d’agent /llms-full.txt et /experience.json. Des tags ou lentilles inconnus, des dates erronées, des images manquantes ou une section manquante arrêtent la construction. L’API d’administration exécute la même validation avant de valider un commit, de sorte qu’une mauvaise édition — par une personne ou une IA — est refusée avant qu’elle ne puisse casser quoi que ce soit.

Le site web

Le site est une exportation statique Next.js servie par Cloudflare Workers Static Assets. Un petit Worker en amont gère les redirections (jenksguo.com et les hôtes www → jenksguo.xyz), les en-têtes de sécurité et les API. L’anglais vit à / ; les six autres langues à /zh, /zh-hant, /ja, /fr, /es et /eo. Chaque entrée a sa propre page dans chaque langue.

L’assistant Ask Jenks

L’assistant est un agent utilisant des outils plutôt qu’une longue invite. Son invite système ne contient que le profil principal et un index en une ligne de chaque entrée, lentille et compétence. Lorsqu’il a besoin de détails, il appelle des outils :

• load_skill — un playbook pour le type de question (adéquation au rôle, cadrage de conseil, transformation IA, histoires STAR, gouvernance, navigation de carrière…),
• get_entries — exposés complets par slug,
• list_entries — filtrés par tag, lentille ou type,
• search_corpus — recherche par mots-clés.

Cette divulgation progressive maintient les réponses ancrées dans l’ensemble du corpus sans une énorme invite. Les modèles sont joints via OpenRouter.

Une seule spécification, quatre surfaces

src/spec.js définit chaque outil public et admin une seule fois : nom, description, schéma d’entrée, route REST et commande CLI. De là proviennent :

• les serveurs MCP distants (/mcp, /mcp/admin),
• l’API REST (/api/v1/*, /api/admin/*),
• la CLI jenks et son mode MCP local (jenks mcp),
• la documentation de référence et /openapi.json.

Modifiez un outil à un seul endroit et chaque surface suit, de sorte que la documentation ne peut pas diverger du comportement.

Pipeline de publication

Les modifications d’admin sont des commits effectués via l’API GitHub. Chaque push exécute l’intégration continue :

1. compiler et valider le corpus,
2. retraduire seulement les entrées qui ont changé dans les six autres langues (les traductions sont mises en cache par un hash de leur source anglaise ; un glossaire fixe définit les intitulés de rubriques et les noms de lentilles),
3. construire le site et les fichiers d’agent,
4. déployer — main vers https://jenksguo.xyz, dev vers https://dev.jenksguo.xyz (non indexé).

Les binaires CLI pour macOS, Linux et Windows sont publiés sous /downloads.

Pourquoi c’est conçu ainsi

Un site personnel est petit, mais il est lu par des personnes, des moteurs de recherche et, de plus en plus, par des agents, en plusieurs langues, et modifié par une IA aussi souvent qu’à la main. Une source unique validée avec des surfaces générées est la conception la plus simple qui maintienne tout cela cohérent.