Primero explorar en amplitud, luego enfocarse
Los agentes deberían usar la CLI de WebCull con un flujo de explorar en amplitud y luego enfocarse. Empiece con conteos y páginas pequeñas de resultados. Obtenga metadatos completos de marcadores solo después de conocer los ID candidatos. Los comandos de escritura solo deben usarse cuando el usuario pida explícitamente crear o actualizar marcadores.
Habla con tus marcadores
Este flujo permite que un usuario haga preguntas naturales sobre sus marcadores guardados. El agente primero debería invitar al usuario a elegir una carpeta específica o usar toda la cuenta de marcadores como contexto, luego explorar coincidencias probables antes de reducir progresivamente a los detalles que responden la pregunta.
La conversación debería sentirse como hablar con un bibliotecario que conoce el tema y el material guardado del usuario. El agente debería crear primero listas curadas desde metadatos de marcadores y luego usar búsqueda directa, contenido de snapshots o metadatos de página obtenidos cuando la cuenta y las opciones de comando lo permitan.
bookmarks search dirigidas cuando el usuario pregunte por un tema, herramienta, persona, dominio, proyecto, etiqueta o frase.Example prompt
Habla con mis marcadores sobre software local-first. Pregunta si quiero una carpeta o toda mi cuenta de marcadores, explora en amplitud entre coincidencias probables y luego reduce a metadatos guardados, snapshots, metadatos de página obtenidos y documentación relacionada de los mismos sitios.
Organizar marcadores en carpetas más claras
Este flujo es para usuarios que quieren que un agente ayude a convertir una cuenta de marcadores desordenada en una estructura de carpetas más limpia. El agente debería inspeccionar primero conteos amplios de carpetas, identificar carpetas demasiado grandes o mezcladas y luego proponer categorías y subcategorías antes de hacer cambios.
bookmarks count y bookmarks tree superficiales para encontrar carpetas con muchos elementos, temas duplicados o temas mezclados.Example prompt
Ayúdame a organizar mis marcadores. Empieza encontrando carpetas demasiado amplias o saturadas, luego sugiere una estructura más limpia de carpetas y subcarpetas antes de hacer cambios.
Analizar marcadores para mejorar flujos de trabajo
Este flujo es intensivo en lectura. El agente debería usar los marcadores existentes para entender cómo trabaja el usuario, luego sugerir mejoras prácticas sin reorganizar inmediatamente la cuenta.
Example prompt
¿Cómo puedo mejorar mis marcadores para ayudar a mi flujo de trabajo? Lee lo que tengo, encuentra fricción y sugiere cambios útiles sin editar nada todavía.
Inferir intereses y sugerir descubrimientos útiles
Este flujo usa los marcadores del usuario como contexto para recomendaciones. El agente debería inferir intereses desde temas guardados, herramientas, creadores, enlaces de entretenimiento y áreas de investigación, y luego sugerir cosas que el usuario podría querer explorar después.
Example prompt
Según mis marcadores, ¿qué temas, herramientas, medios o entretenimiento recomendarías que explore después? Explica qué patrones de marcadores llevaron a cada sugerencia.
Crear una ruta de aprendizaje desde una carpeta
Este flujo convierte una carpeta en una secuencia guiada. El agente debería inferir el tema, inspeccionar el material guardado y luego ordenar marcadores en una ruta que ayude al usuario a pasar de la orientación al estudio más profundo.
Example prompt
Convierte esta carpeta en una ruta de aprendizaje. Infiere el tema, ordena mis marcadores de principiante a avanzado y dime qué falta.
Preparar una carpeta para una Collection pública
Este flujo revisa una carpeta antes de que el usuario la haga pública. El agente debería buscar cualquier cosa que haga que la Collection sea poco clara, incompleta, privada o difícil de escanear para los visitantes.
Example prompt
Revisa esta carpeta antes de hacerla pública. Encuentra enlaces privados, títulos débiles, descripciones faltantes, iconos malos, nombres de carpetas poco claros y cualquier cosa que deba reordenarse.
Mantener cada solicitud intencionalmente pequeña
Use --max-chars, --limit, --page, --fields y --max-metadata-chars en cada comando de marcador. Al buscar sin contexto, empiece con bookmarks count o bookmarks tree --limit 25 --max-chars 8000.
Cuando el resultado sea demasiado amplio, reduzca primero los campos, luego los caracteres de metadatos y luego pagine los resultados. No solicite notas completas ni todos los metadatos hasta que los ID objetivo estén acotados.
Ejecutar llamadas de CLI secuencialmente
No ejecute llamadas de la CLI de WebCull en paralelo. Espere al menos 1 segundo entre llamadas de CLI, al menos 2 segundos después de llamadas de árbol o búsqueda, y al menos 2 segundos entre páginas. Use webcull limits con moderación porque está limitado a 7 llamadas por minuto. Si la API devuelve throttled, espere al menos 60 segundos y reduzca la siguiente solicitud.
Los comandos de lectura permiten 60 solicitudes por minuto, 600 por hora y 3000 por día para cada token de CLI. Los comandos de escritura son más estrictos: 10 por minuto, 100 por hora y 500 por día. También pueden aplicarse límites de cuenta y red.
Escribir solo cuando el usuario pide crear o actualizar marcadores
Use webcull bookmarks create o webcull bookmarks update <id> solo cuando el usuario pida explícitamente una escritura. No use la CLI para escrituras por lotes, escrituras recursivas, organización implícita, conversión de tipos, carga de iconos o cambios de estado de cuenta E2EE.
Prefiera --dry-run antes de una escritura real al validar ubicación de padre, propiedad o estado E2EE. Preserve campos no editados enviando solo el campo que el usuario pidió cambiar.
Nunca exponga frases de contraseña de cuentas cifradas
Nunca proporcione una frase de contraseña E2EE mediante argumentos de CLI, variables de entorno, configuración, stdin, registros o ejemplos. La CLI solo pide mediante entrada interactiva oculta en la terminal.
En cuentas cifradas, la búsqueda de texto de marcadores usa automáticamente búsqueda local descifrada y acotada cuando hace falta. Mantenga ajustados límites como --limit y --max-scan-rows. Si la conversión E2EE está en curso, no fuerce una escritura. Pida al usuario que termine la conversión en la app.
Secuencia de comandos de ejemplo
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