WebCull - Documentation - Compétence d'agent

Flux de travail

Explorer large d'abord, puis se concentrer

Les agents doivent utiliser la CLI WebCull dans un flux qui commence large puis se concentre. Commencez par des décomptes et de petites pages de résultats. Ne récupérez les métadonnées complètes des favoris qu'après avoir identifié les ID candidats. Les commandes d'écriture ne doivent être utilisées qu'après une demande explicite de l'utilisateur de créer ou mettre à jour des favoris.

Demander

Parler à vos favoris

Ce flux permet à un utilisateur de poser des questions naturelles sur ses favoris enregistrés. L'agent doit d'abord inviter l'utilisateur à choisir un dossier précis ou à utiliser tout le compte de favoris comme contexte, puis explorer large parmi les correspondances probables avant de resserrer progressivement vers les détails qui répondent à la question.

La conversation doit ressembler à un échange avec un bibliothécaire qui connaît le sujet et le contenu enregistré de l'utilisateur. L'agent doit d'abord créer des listes organisées depuis les métadonnées de favoris, puis utiliser la recherche directe, le contenu de snapshots ou les métadonnées de page récupérées lorsque le compte et les options de commande le permettent.

Choisir la portée

Demandez si l'utilisateur veut se concentrer sur un dossier ou utiliser tout le compte de favoris. Si l'utilisateur hésite, commencez large et signalez les thèmes les plus forts trouvés.

Explorer large d'abord

Vérifiez les noms de dossiers, tags, titres, domaines, notes et éléments récents sur un large ensemble de résultats avant de décider quels groupes de favoris méritent une inspection plus approfondie.

Commencer par les métadonnées

Utilisez titres, URL, dossiers, tags, notes, descriptions et dates de modification pour construire une première vue de ce que l'utilisateur a enregistré.

Resserrer progressivement

Passez des thèmes larges aux favoris précis, puis récupérez les enregistrements complets uniquement pour les éléments qui peuvent réellement améliorer la réponse.

Créer des listes organisées

Regroupez les favoris correspondants en listes utiles comme meilleures références, projets actifs, recherches non lues, outils à revoir ou divertissements à regarder plus tard.

Rechercher directement

Utilisez des requêtes bookmarks search ciblées lorsque l'utilisateur demande un sujet, outil, personne, domaine, projet, tag ou expression.

Utiliser le texte intégral lorsqu'il est disponible

Si l'utilisateur a créé des snapshots, utilisez le texte de snapshot et les métadonnées de page pour répondre à des questions plus profondes sur les pages enregistrées. Gardez les limites de résultats serrées et citez les favoris qui ont informé la réponse.

Récupérer le contexte manquant

Lorsque les métadonnées enregistrées n'incluent pas assez de contenu de page, récupérez de nouvelles métadonnées de page lorsque c'est autorisé, puis utilisez ce contexte pour améliorer la réponse.

Étendre depuis le même site

Pour les sites de documentation ou de référence, utilisez une recherche étroite sur le même site afin de trouver des pages enregistrées connexes de cette source et de continuer la conversation avec un contexte plus solide.

Répondre avec contexte

Expliquez pourquoi chaque favori apparaît dans la réponse, à quoi il semble utile, ce qui manque et ce que l'utilisateur pourrait demander ensuite.

Example prompt

Parlez à mes favoris au sujet des logiciels local-first. Demandez si je veux un dossier ou tout mon compte de favoris, explorez large parmi les correspondances probables, puis resserrez vers les métadonnées enregistrées, snapshots, métadonnées de page récupérées et documentation liée des mêmes sites.

Organiser

Organiser les favoris dans des dossiers plus clairs

Ce flux s'adresse aux utilisateurs qui veulent qu'un agent aide à transformer un compte de favoris désordonné en une structure de dossiers plus propre. L'agent doit d'abord inspecter les grands compteurs de dossiers, identifier les dossiers trop volumineux ou mélangés, puis proposer des catégories et sous-catégories avant tout changement.

Commencer par la structure

Utilisez bookmarks count et des appels bookmarks tree peu profonds pour trouver les dossiers avec beaucoup d'éléments, thèmes dupliqués ou sujets mélangés.

Proposer des catégories

Suggérez des noms de dossiers et des regroupements de sous-dossiers en langage simple. Expliquez pourquoi chaque regroupement aide l'utilisateur à parcourir plus vite.

Gérer les dossiers encombrés

Un dossier contenant trop d'éléments sans rapport indique qu'il faut le diviser en sous-dossiers, déplacer les éléments hors sujet ailleurs ou renommer le dossier selon son thème principal.

Écrire seulement après approbation

Utilisez d'abord des écritures en simulation, puis attendez que l'utilisateur approuve les créations ou mises à jour exactes avant d'enregistrer les changements.

Example prompt

Aidez-moi à organiser mes favoris. Commencez par trouver les dossiers trop larges ou encombrés, puis proposez une structure de dossiers et sous-dossiers plus claire avant de faire des changements.

Améliorer

Analyser les favoris pour améliorer les flux de travail

Ce flux est surtout axé sur la lecture. L'agent doit utiliser les favoris existants pour comprendre comment l'utilisateur travaille, puis suggérer des améliorations pratiques sans réorganiser immédiatement le compte.

Chercher des modèles

Examinez dossiers, titres, URL, tags et notes pour identifier outils répétés, projets actifs, zones obsolètes et sujets souvent revisités.

Trouver les frictions

Signalez les favoris qui semblent mal placés, les dossiers qui mélangent des flux sans rapport ou les sujets qui pourraient bénéficier de raccourcis, recherches enregistrées ou regroupements plus clairs.

Suggérer les prochaines actions

Renvoyez un petit ensemble de recommandations avec raisons. Gardez la sortie centrée sur la façon dont le compte de favoris peut mieux soutenir le travail de l'utilisateur.

Example prompt

Comment puis-je améliorer mes favoris pour aider mon flux de travail ? Lisez ce que j'ai, trouvez les frictions et proposez des changements utiles sans encore rien modifier.

Recommander

Déduire les centres d'intérêt et suggérer des découvertes utiles

Ce flux utilise les favoris de l'utilisateur comme contexte pour des recommandations. L'agent doit déduire les centres d'intérêt depuis les sujets, outils, créateurs, liens de divertissement et domaines de recherche enregistrés, puis suggérer ce que l'utilisateur pourrait explorer ensuite.

Déduire les centres d'intérêt

Regroupez les favoris par thèmes comme loisirs, médias, apprentissage, outils de travail, sujets de recherche et sites web récurrents.

Expliquer le signal

Reliez chaque recommandation à des modèles visibles dans les favoris afin que l'utilisateur puisse juger si la suggestion est pertinente.

Laisser le contrôle à l'utilisateur

Ne créez pas de favoris de recommandation sauf si l'utilisateur le demande. Présentez d'abord les idées, puis laissez l'utilisateur choisir ce qu'il veut enregistrer.

Example prompt

D'après mes favoris, quels sujets, outils, médias ou divertissements me recommanderiez-vous d'explorer ensuite ? Expliquez quels modèles de favoris ont mené à chaque suggestion.

Apprendre

Créer un parcours d'apprentissage depuis un dossier

Ce flux transforme un dossier en séquence guidée. L'agent doit déduire le sujet, inspecter le contenu enregistré, puis organiser les favoris dans un parcours qui aide l'utilisateur à passer de l'orientation à une étude plus approfondie.

Déduire le sujet

Utilisez les noms de dossiers, titres, tags, descriptions, notes et domaines pour identifier le vrai sujet du dossier.

Séquencer le contenu

Regroupez les favoris en ressources débutant, documents de référence, exemples, contenu avancé et éléments à revoir plus tard.

Expliquer l'ordre

Décrivez pourquoi chaque groupe se trouve à cet endroit et quels favoris doivent être lus en premier.

Trouver les lacunes

Signalez les éléments manquants comme tutoriels, documentation officielle, exemples, comparaisons ou références avancées qui renforceraient le parcours.

Example prompt

Transformez ce dossier en parcours d'apprentissage. Déduisez le sujet, triez mes favoris de débutant à avancé, et dites-moi ce qui manque.

Publier

Préparer un dossier pour une Collection publique

Ce flux examine un dossier avant que l'utilisateur le rende public. L'agent doit chercher tout ce qui rendrait la Collection peu claire, incomplète, privée ou difficile à parcourir pour les visiteurs.

Vérifier la confidentialité

Signalez les liens privés, pages de compte, pages d'administration, documents personnels, URL de staging et autres favoris qui ne devraient pas être exposés publiquement.

Améliorer la présentation

Signalez les titres faibles, descriptions manquantes, mauvaises icônes, noms de dossiers peu clairs et éléments qui pourraient troubler les visiteurs publics.

Vérifier l'ordre

Suggérez quels favoris devraient apparaître en premier, quels dossiers doivent être renommés et quels éléments devraient être regroupés ou déplacés avant publication.

Rester consultatif

Renvoyez une liste de changements à faire approuver par l'utilisateur avant de modifier titres, descriptions, icônes, dossiers ou ordre.

Example prompt

Vérifiez ce dossier avant que je le rende public. Trouvez les liens privés, titres faibles, descriptions manquantes, mauvaises icônes, noms de dossiers peu clairs et tout ce qui devrait être réordonné.

Limites

Garder chaque demande volontairement petite

Utilisez --max-chars, --limit, --page, --fields et --max-metadata-chars sur chaque commande de favori. Lors d'une recherche à l'aveugle, commencez par bookmarks count ou bookmarks tree --limit 25 --max-chars 8000.

Lorsque le résultat est trop large, réduisez d'abord les champs, puis les caractères de métadonnées, puis parcourez les pages de résultats. Ne demandez pas les notes complètes ou toutes les métadonnées avant que les ID cibles soient resserrés.

Cadence

Exécuter les appels CLI séquentiellement

N'exécutez pas les appels CLI WebCull en parallèle. Attendez au moins 1 seconde entre les appels CLI, au moins 2 secondes après les appels tree ou search, et au moins 2 secondes entre les pages. Utilisez webcull limits avec parcimonie car il est limité à 7 appels par minute. Si l'API renvoie throttled, attendez au moins 60 secondes et resserrez la demande suivante.

Les commandes de lecture autorisent 60 requêtes par minute, 600 par heure et 3000 par jour pour chaque jeton CLI. Les commandes d'écriture sont plus strictes : 10 par minute, 100 par heure et 500 par jour. Des limites de compte et de réseau peuvent aussi s'appliquer.

Écritures

Écrire uniquement lorsque l'utilisateur demande de créer ou mettre à jour des favoris

Utilisez webcull bookmarks create ou webcull bookmarks update <id> uniquement lorsque l'utilisateur demande explicitement une écriture. N'utilisez pas la CLI pour des écritures groupées, écritures récursives, organisation implicite, conversion de type, téléversement d'icône ou changements d'état de compte E2EE.

Préférez --dry-run avant une vraie écriture lors de la validation du placement parent, de la propriété ou de l'état E2EE. Préservez les champs non modifiés en envoyant uniquement le champ que l'utilisateur a demandé de changer.

E2EE

Ne jamais exposer les phrases secrètes de comptes chiffrés

Ne fournissez jamais une phrase secrète E2EE via des arguments CLI, variables d'environnement, configuration, stdin, journaux ou exemples. La CLI demande uniquement via une saisie interactive masquée dans le terminal.

Pour les comptes chiffrés, la recherche de texte de favoris utilise automatiquement une recherche locale déchiffrée bornée lorsque nécessaire. Gardez des limites comme --limit et --max-scan-rows serrées. Si la conversion E2EE est en cours, ne forcez pas une écriture. Demandez à l'utilisateur de terminer la conversion dans l'app.

Exemples

Séquence de commandes d'exemple

webcull bookmarks count --path /
webcull bookmarks tree --path / --max-depth 1 --limit 25 --max-chars 8000 --fields id,type,title,modified
webcull bookmarks search --query 'github api' --limit 20 --max-chars 8000 --fields id,title,url,parent_id
webcull bookmarks search --query 'github api' --limit 20 --max-scan-rows 500
webcull bookmarks get --ids 123,456 --fields id,title,url,notes --max-metadata-chars 1500
webcull bookmarks create --url https://example.com --title Example --dry-run
webcull bookmarks update 456 --title "New title" --dry-run