Referencias

Los formatos de referencia que puede utilizar para señalar paquetes y pistas.

Cada vez que lees, actualizas o vinculas un paquete o track, lo identificas con una referencia. Los paquetes aceptan varios formularios de referencia porque están destinados a ser compartidos y reutilizados; Las pistas aceptan un conjunto más reducido porque representan un trabajo en vivo que debe permanecer inequívoco. Saber qué formulario utilizar le evita copiar UUID sin formato.

Referencias del paquete

Formulario	Ejemplo	Úselo cuando...
UUID	`8f3c…`	Ya tienes el ID exacto, p. de una respuesta anterior API
Alias	`@team-onboarding`	Quiere un nombre estable y legible; resuelve primero lo personal y luego el espacio de trabajo
Alias del propietario	`@hiroki/team-onboarding`	Estás leyendo un alias que pertenece a otro identificador
Compartir URL	`https://epismo.ai/share/<token>`	Alguien compartió un paquete privado contigo a través de un enlace
URL del centro	`https://epismo.ai/hub/workflows/<id>`	Estás sacando un paquete público del centro

Algunos detalles que vale la pena conocer:

Los Alias son la forma más amigable para los humanos. Son los que debe utilizar en solicitudes, runbooks y scripts de CI. Un @alias simple se resuelve primero en su espacio de nombres personal y vuelve al espacio de trabajo activo; pase --namespace / namespace para fijar un espacio de nombres. Consulte Aliases.
Las URL para compartir se producen bajo demanda con epismo pack get <reference> --share-url (o shareUrl: true en MCP). En un espacio de trabajo, pueden usar el subdominio del espacio de trabajo, p. https://acme.epismo.ai/share/<token>. Solicitar uno no hace público un paquete privado.
Las URL del centro apuntan a paquetes públicos y existen para ambos tipos de paquetes: …/hub/workflows/<id> y …/hub/contexts/<id>.

Las superficies de lectura y actualización de paquetes aceptan cualquiera de estos formularios siempre que esté documentado un reference, por lo que un ejemplo de CLI que funciona con un UUID también funciona con un alias o URL.

Dónde se utiliza `reference`

Epismo usa reference solo para paquetes y pistas:

Una referencia de paquete es un ID de paquete, un alias, una URL compartida o una URL central.
Una referencia de seguimiento es un UUID de tarea/objetivo o una URL que contiene ese UUID.

CLI y MCP usan el mismo nombre para sus superficies de paquete/pista compartidas: si un comando o herramienta apunta a un paquete o pista existente, la entrada externa se llama reference. Otros registros mantienen nombres en forma de ID porque no son recursos referenciables: suggestion id, logId, workspace-id, project-id, user-ids y agent-ids.

El CLI tiene comandos adicionales de espacio de trabajo, proyecto, agente, crédito y token que no están expuestos como herramientas MCP. Esos comandos se basan intencionalmente en ID y administran esos registros directamente.

Selección de espacio de nombres

Los alias simples son intencionalmente convenientes, pero eso significa que pueden ser ambiguos cuando su espacio de nombres personal y el espacio de trabajo activo definen el mismo nombre. La resolución es primero personal y luego el espacio de trabajo alternativo.

Utilice namespace: "personal"/namespace: "workspace" en llamadas API o MCP, o --namespace personal|workspace en comandos CLI, cuando la automatización siempre debe apuntar a un espacio de nombres. El formulario @handle/alias está dirigido al identificador público de otra cuenta y es de solo lectura desde su cuenta.

Seguimiento de referencias

Se hace referencia a las pistas solo mediante UUID o mediante una URL que contiene un UUID de tarea o objetivo. No hay alias de pistas. Esto es deliberado: las pistas conllevan estatus y propiedad, y una referencia ambigua al trabajo activo es más peligrosa que una inconveniente. Si necesita un identificador legible para algo, eso es una señal de que debería ser un paquete.

Regla práctica