AlexXPZhu/save-papers-to-zotero

Guardar Artículos en Zotero

Completa solicitudes explícitas de importación a Zotero a través del servidor local de Connector de la aplicación de escritorio en 127.0.0.1:23119. No pidas al usuario que invoque la extensión del navegador Zotero Connector. Trata un elemento padre sin un PDF almacenado verificado como incompleto a menos que el usuario solicite una ejecución de prueba.

Resolver Rutas Empaquetadas

Resuelve el directorio que contiene este SKILL.md antes de ejecutar un importador. En Claude Code, usa ${CLAUDE_SKILL_DIR}. En Codex, usa el directorio del skill instalado proporcionado con el skill cargado. Reemplaza <skill-dir> a continuación con ese directorio absoluto, entrecomilla la ruta del script resultante y nunca asumas que el directorio de trabajo actual es el directorio del skill. Usa un ejecutable de Python 3.10+ disponible; los ejemplos usan python.

Elegir el Importador

• Usa <skill-dir>/scripts/zotero_connector_import.py para un artículo.
• Usa <skill-dir>/scripts/zotero_batch_import.py para dos o más artículos, una lista de DOI/artículos o la salida de una revisión bibliográfica.
• Lee <skill-dir>/references/batch-manifest.md antes de preparar un manifiesto por lotes.

Ambos importadores:

1. verifican la conectividad con Zotero y la colección destino exacta;
2. identifican posibles coincidencias existentes por DOI, arXiv ID y luego título normalizado;
3. informan esas coincidencias pero aún así crean el nuevo elemento solicitado;
4. guardan metadatos al estilo de un traductor de Zotero y notas secundarias opcionales, incluidos los Comments de arXiv;
5. asignan la colección solicitada, etiquetas ordinarias, la etiqueta predeterminada #status/to-read y etiquetas de prioridad opcionales;
6. suben los bytes del PDF como un archivo adjunto hijo almacenado; y
7. verifican que el elemento padre recién creado —no una coincidencia preexistente— esté en la colección con un PDF almacenado.

Nunca elimines, combines, reemplaces ni suprimas automáticamente un elemento porque exista una posible coincidencia. Devuelve possible_duplicate_count y possible_duplicate_keys para que el usuario pueda inspeccionar Zotero y decidir qué eliminar.

Preparar Entradas Fiables

Resuelve cada artículo en una página de destino canónica. Prefiere páginas de editor, registros DOI, PubMed Central, repositorios o páginas de preimpresiones a las que el usuario pueda acceder legítimamente. Completa todos los metadatos fiables que exponga la fuente, incluidos resumen, publicación, volumen, número, páginas, idioma, DOI, identificador arXiv y lista completa de creadores. No inventes valores faltantes.

Para un artículo de arXiv, copia el campo Comments de la fuente textualmente, excepto para la normalización de espacios en blanco. Pasa solo su valor; el importador crea una nota secundaria separada que comienza con Comment: . Conserva la información sobre sede, código, proyecto y publicación contenida allí. No sintetices un comentario de arXiv a partir del resumen, la cita o tu propio análisis, y omítelo cuando la fuente no tenga un campo Comments.

Usa etiquetas ordinarias de Zotero en los formatos #status/... y #priority/... reconocidos por el plugin Ethereal Style; no se requiere ningún campo o tipo de etiqueta especial de Zotero. Asigna por defecto a cada artículo recién importado la etiqueta #status/to-read a menos que se proporcione otro estado o una exclusión explícita:

• reading_status: to-read se convierte en #status/to-read;
• reading_status: reading se convierte en #status/reading;
• reading_status: none desactiva la asignación automática de estado; y
• priority: high, medium o low se convierte en #priority/high, #priority/medium o #priority/low.

Conserva una etiqueta #status/... explícita ya presente en el elemento o en las etiquetas solicitadas en lugar de reemplazarla con la predeterminada. Un estado semántico proporcionado reemplaza las etiquetas de estado conflictivas. Nunca infieras la prioridad del contenido del artículo; añádela solo a partir de un valor del usuario o una asignación explícita, como un nivel definido por el usuario.

Usa un objeto de elemento al estilo del traductor de Zotero:

{
  "itemType": "preprint",
  "title": "Artículo de Ejemplo",
  "creators": [
    {"firstName": "Ada", "lastName": "Lovelace", "creatorType": "author"}
  ],
  "date": "2026",
  "url": "https://example.org/paper",
  "DOI": "10.0000/example",
  "archiveID": "arXiv:2601.00001"
}

Obtén cada PDF de una de dos maneras:

• Pasa una URL de PDF pública directa y su página de destino como referente.
• Para un PDF disponible solo en la sesión de Chrome con sesión iniciada del usuario, usa la integración del navegador del anfitrión: usa el skill de control de Chrome en Codex, o Claude en Chrome desde una sesión de Claude Code iniciada con claude --chrome (o con Chrome habilitado por defecto). Descarga el PDF legítimo visible en un archivo temporal, luego pasa ese archivo con --pdf-file. Nunca inspecciones, exportes ni persistas cookies o almacenamiento de sesión.

Si la integración del navegador no está disponible, se deniega el permiso o la descarga no produce un PDF local válido, detente antes de la escritura en Zotero y pide al usuario que proporcione un PDF local obtenido legítimamente. No recurras a un espejo no confiable.

No evites paywalls, CAPTCHAs, controles de acceso ni restricciones de licencia.

Importar un Artículo

Para una URL de PDF pública:

python -X utf8 "<skill-dir>/scripts/zotero_connector_import.py" \
  --item-json <item.json> \
  --collection <nombre exacto de la colección> \
  --source-url <URL de la página de destino> \
  --pdf-url <URL directa del PDF> \
  --referrer <URL de la página de destino>

Para un PDF descargado, reemplaza --pdf-url con --pdf-file <ruta>. Usa --pdf-source-url <URL> con --pdf-file o --pdf-url cuando la fuente registrada del adjunto deba diferir de la URL de descarga.

Usa --arxiv-comment <texto> para el valor Comments de arXiv de la fuente; el importador añade Comment: exactamente una vez. Repite --note para otras notas secundarias y --tag para etiquetas ordinarias. El estado de lectura predeterminado es to-read; usa --reading-status reading para sobrescribir o --reading-status none para excluirte. Usa --priority high|medium|low solo cuando se solicite explícitamente o se asigne a partir de niveles proporcionados por el usuario. Añade --target-id <id> solo cuando varios destinos de Connector escribibles tengan exactamente el nombre solicitado. Usa --dry-run para comprobaciones de conectividad, colección, entrada y posibles duplicados sin escribir.

Importar un Lote

Prepara y valida cada entrada del manifiesto antes de comenzar las escrituras. Luego ejecuta:

python -X utf8 "<skill-dir>/scripts/zotero_batch_import.py" \
  --manifest <papers.json> \
  --collection <nombre exacto de la colección> \
  --target-id <id> \
  --ledger <results.jsonl> \
  --summary-json <summary.json>

Omite la línea --target-id del ejemplo a menos que los destinos de Connector con el mismo nombre sean ambiguos. Cada entrada del manifiesto tiene por defecto #status/to-read; usa reading_status compartido o por artículo solo para seleccionar reading o none. Establece tags, notes y priority compartidos y por artículo en el manifiesto; establece el arxiv_comment de cada artículo a partir de su propia fuente de arXiv. La CLI del lote intencionalmente no tiene opciones --tag o --note. Añade --stop-on-error cuando no deba intentarse ningún artículo posterior después de la primera entrada incompleta.

El importador por lotes debe permanecer en serie. Vuelve a validar el destino exacto inmediatamente antes de cada escritura, añade y vacía un registro del libro mayor después de cada artículo, continúa después de fallos específicos de artículos de forma predeterminada y se detiene en fallos de conectividad o colección de Zotero. La reanudación está habilitada de forma predeterminada: volver a ejecutar el mismo manifiesto y libro mayor omite los registros saved_with_pdf anteriores. Usa --no-resume solo cuando el usuario quiera explícitamente que se vuelvan a escribir las solicitudes completadas anteriormente.

Nunca paralelicemos escrituras ni ejecutemos dos procesos contra el mismo libro mayor. El importador utiliza un bloqueo de asesoramiento del sistema operativo. Su archivo .lock puede permanecer en el disco después de una ejecución o un bloqueo; el archivo por sí solo no bloquea un lote futuro.

Los códigos de salida del lote son 0 cuando todas las solicitudes se completaron o se omitieron de forma segura, 3 cuando la ejecución finalizó con entradas incompletas y otro código distinto de cero para un error fatal de manifiesto, bloqueo, conexión o colección. El importador individual devuelve 0 en caso de éxito y un código distinto de cero en caso de fallo.

Interpretar Resultados

Trata el JSON del importador como autoritario:

• saved_with_pdf: nuevo padre y PDF almacenado verificados.
• skipped_completed: registro exitoso anterior del libro mayor conservado durante la reanudación.
• skipped_duplicate_in_manifest: entrada de manifiesto repetida omitida sin una segunda escritura.
• invalid_pdf, http_error u otro estado específico del artículo: continúa el lote e informa la fuente y el motivo.
• verification_failed: los metadatos pueden haberse guardado, pero no se pudo verificar el elemento recién creado o su PDF almacenado; no lo vuelvas a ejecutar a ciegas.
• not_attempted: un error fatal a nivel de lote detuvo las entradas posteriores.

possible_duplicate_count y possible_duplicate_keys son informativos. Se refieren solo a elementos que existían antes de esta solicitud; el importador aún escribe y verifica un nuevo padre. Preséntalos para revisión manual y nunca elimines ningún elemento sin una decisión explícita del usuario.

Cuando se proporciona, arxiv_comment informa el texto de la nota secundaria normalizada. workflow_tags informa la etiqueta #status/... predeterminada o explícita aplicada y cualquier etiqueta #priority/... solicitada. Inclúyelos en el informe de finalización para que el usuario pueda verificar los metadatos del flujo de trabajo sin abrir cada elemento.

Informar el Lote

Informa:

• total solicitado;
• recién guardados con PDFs verificados;
• omitidos por reanudación y duplicados de manifiesto;
• elementos recién guardados que tenían posibles coincidencias preexistentes, con sus claves;
• requiere acción del usuario;
• fallidos o no intentados; y
• el título, fuente, estado y motivo de cada artículo incompleto.

No claims éxito porque una fila de archivo adjunto o una URL sea visible. Requiere la verificación del archivo almacenado por parte del importador.