Libros de jugadas y versiones

Un playbook es un contenedor lógico con un cuenta propietaria, visibility, editores explícitos, un alias oficial opcional, la última versión y estado de archivo. Su contenido real se encuentra en versiones inmutables, por lo que un título o un cambio de paso siempre crea un nuevo hecho histórico en lugar de reescribir la definición utilizada en trabajos anteriores.

Playbooks y Casos tienen una cuenta propietaria de Usuario o Espacio de trabajo (ownerId), que también paga su uso. El propietario personal tiene todos los derechos; los Owners y Admins actuales ejercen esos derechos para un Espacio de trabajo. Los demás miembros necesitan permisos explícitos de usuario o Equipo, o visibilidad pública para leer contenido publicado. La membresía por sí sola no concede acceso. Al eliminar un miembro, se revocan sus permisos directos sobre los recursos propiedad de ese Espacio, incluidos los completados y archivados. Si la eliminación dejara algún recurso sin editor explícito, añada primero otro usuario o equipo editor, incluidos los recursos completados o archivados. Se conservan los permisos sobre recursos personales y de otros Espacios. Los permisos de Equipo y administración dependen de la membresía actual. El SSO obligatorio se aplica a los miembros; los usuarios externos con permisos directos usan la autenticación normal de Epismo. El acceso de Equipo entre espacios verifica el SSO del espacio de participación. Los listados usan permisos explícitos y la visibilidad pública admitida; la propiedad por sí sola no incluye un recurso.

Omita ownerId al crear o copiar para usar el Espacio de trabajo activo, o su cuenta personal si no hay uno seleccionado. La selección explícita también requiere autorización. Cuando hay un Espacio seleccionado, incluido el predeterminado de la conexión, la creación requiere exactamente una opción: private: true, teamIds no vacío o access. En el espacio personal puede omitirse la configuración. El permiso de edición del Equipo cubre al creador sin añadir un permiso directo redundante; se conserva un permiso directo solicitado explícitamente. Mantener o tener asignado un recurso no sustituye los permisos.

Definición

Una versión contiene schemaVersion, título, descripción, una categoría, un esquema de entrada y una lista ordenada de pasos. Las categorías son productivity, programming, design, sales, marketing, operations y learning.

El esquema de entrada es JSON Schema Draft 2020-12 con una raíz de objeto. Describe la entrada de caso aceptada; no hace que Epismo ejecute el playbook.

Cada paso tiene:

Los pasos no tienen estado, asignados, transiciones, política de reintento, dependencias ni marcas de tiempo de finalización. Un agente puede omitirlos, combinarlos, reordenarlos o ampliarlos.

Editorial e identidad

La creación de un playbook crea el contenedor y la versión 1 de forma atómica. Para publicar otra versión se requiere baseVersionId. Si la última versión cambió, la publicación falla con un conflicto en lugar de sobrescribir el trabajo simultáneo.

El servidor normaliza una definición, almacena JSON canónico y calcula un resumen sha256:. El formato JSON o YAML equivalente produce la misma identidad de contenido. Un caso anclado a una versión almacena su ID de versión y su resumen, de modo que la guía con la que comenzó sigue siendo verificable.

Los nuevos pasos omiten las identificaciones; el servidor los asigna. Conserve una ID existente solo cuando el paso sea el mismo paso lógico. Las identificaciones eliminadas no se reutilizan.

Archivar versiones

Un administrador propietario puede archivar una versión histórica desde su página de detalles, la CLI, MCP o la API HTTP. Las versiones archivadas desaparecen de las listas normales, las lecturas directas y los nuevos inicios de casos. Sus números nunca se reutilizan: si se archiva la versión 2 después de publicar las versiones 1–3, el historial visible muestra las versiones 1 y 3, y la siguiente publicación es la versión 4.

La última versión no se puede archivar porque sigue siendo la definición actual del playbook y la base de los borradores y publicaciones futuras. Los casos existentes conservan la referencia a su versión fijada y siguen funcionando, pero el contenido de la versión archivada deja de exponerse mediante lecturas normales.

Borradores

Un playbook tiene como máximo un borrador: contenido mutable e inédito que cualquiera con acceso de edición puede guardar tantas veces como desee sin crear una versión. Cada guardado toma la última revisión leída (0 para un primer borrador); se rechaza una revisión obsoleta, la misma disciplina que un conflicto entre la versión base al publicarse.

Un borrador sigue el acceso de edición del playbook: los editores explícitos, el propietario del playbook y los propietarios y administradores del espacio de trabajo al que pertenece pueden leerlo y editarlo, mientras que los lectores públicos y los enlaces compartidos no pueden acceder a él. Al publicar un borrador se crea una nueva versión a partir de su contenido y se descarta el borrador en el mismo paso; descartarlo directamente deja intacta la versión publicada.

Descubrimiento y referencias

Busque playbooks legibles por texto y categoría, o explore el catálogo web por tipo de recurso y referencia de recurso normalizada. El catálogo agrupa las formas equivalentes de URL y de proveedor de GitHub y npm, y mantiene separados los tipos de recursos. El propietario de un playbook (o un administrador del espacio de trabajo propietario) puede definir un alias actual después de configurar un handle público. Compártalo como pb:handle/alias. Un alias nunca otorga acceso y siempre apunta al playbook lógico, no a una versión. Los pb:alias existentes siguen funcionando como referencias locales, pero no son adecuados para compartir. Los alias creados anteriormente por terceros siguen resolviéndose, aunque ya no pueden crearse nuevos.

Al transferir la propiedad, el alias del antiguo propietario sigue resolviéndose hasta que ese namespace reutilice el nombre para otro playbook o lo elimine. Si el destino tiene un handle público y el nombre está libre, se adopta automáticamente como alias actual. Los alias existentes en el destino nunca se sobrescriben. Solo el alias del nuevo propietario se muestra como referencia actual. Cambiar o eliminar un handle público hace que las referencias con el handle anterior dejen de apuntar a sus playbooks; si otra persona obtiene ese handle, podrían apuntar a otro playbook. El alias permanece guardado y puede volver a compartirse bajo un nuevo handle.

Las URL compartidas redirigen a la página del playbook; el acceso actual sigue aplicándose, por lo que la URL por sí sola no concede acceso de lectura. Los playbooks públicos exponen sus instrucciones y sugerencias de recursos, por lo que debe eliminar secretos, URL firmadas, referencias internas y datos personales antes de establecer visibility como public.

Copie una versión publicada legible para adaptarla de forma independiente. La copia tiene contenido y versiones propios; no hereda permisos, borradores, Casos, sugerencias, alias, estrellas ni historial, y las ediciones nunca se sincronizan. Elija los permisos explícitamente; omita ownerId para usar el Espacio activo o su cuenta personal. copiedFrom registra el origen inmediato y su versión inmutable; sourceAccessible indica si aún puede leerlo. Las listas muestran solo copias legibles. Copiar cuesta lo mismo que crear un Playbook.

Propiedad, responsabilidad y ciclo de vida

Los editores y propietarios pueden archivar y restaurar el Playbook. Liste los archivados sin consulta de texto con archived=true (playbook list --archived o epismo_playbook_search) y restaure con playbook restore o epismo_playbook_restore. Se conservan versiones, permisos y mantenimiento. Los propietarios pueden cambiar al responsable con playbook assign --assigned-to o epismo_playbook_assign, sin conceder acceso. Archivar versiones históricas sigue requiriendo propiedad; la última versión no se puede archivar.

En la vista web de Playbooks archivados, un propietario puede eliminar definitivamente un Playbook archivado solo si ningún Caso lo referencia (incluidos los completados o archivados) y ningún otro Playbook se copió de él. La operación es irreversible. Las operaciones de archivo y restauración de CLI y MCP no realizan una eliminación definitiva.

Las Sugerencias pertenecen al Playbook padre actual y no tienen propietario ni permisos históricos independientes. authorId identifica al creador y baseVersionId conserva la referencia de contenido inmutable para evaluar la mejora. La lectura requiere acceso actual al padre; archivarlo oculta sus Sugerencias hasta restaurarlo. Los autores pueden editar sus propuestas abiertas mientras mantengan acceso; los editores actuales del Playbook pueden adoptar o rechazar propuestas. Tras una transferencia, las propuestas existentes siguen los permisos actuales del padre. Publique el resultado antes de marcar la propuesta como aplicada.

La asignación de Playbooks usa assignedTo, como la de Casos, y mantiene assignedTo en las respuestas. Use epismo_playbook_assign, playbook assign <playbook-id> --assigned-to <user-id> o PATCH /v1/playbooks/{playbookId}/assignee. Requiere propiedad y edición previa para el destinatario.