AI-Scarlett/build-dsh-plugin

Construir Plugin DSH

Usa este flujo de trabajo para convertir una idea de plugin DSH en un paquete estándar sin modificar ni ensombrecer el propio Harness.

Normalizar el resumen del usuario

Lee intake.md para cada nueva solicitud de plugin. Acepta lenguaje ordinario, el resumen mínimo en chino o la plantilla JSON estructurada en plugin-brief.template.json.

Requiere solo tres hechos semánticos antes de la generación del código fuente:

1. el problema actual del usuario;
2. el resultado esperado por el usuario;
3. al menos un criterio de aceptación observable.

Infiera nombres, IDs de paquetes, candidatos de arquitectura, clase de riesgo, estructura del proyecto, pruebas y valores predeterminados seguros. No pregunte al usuario que diseñe APIs de Host, entradas de Cordis, esquemas, herramientas de compilación o estrategias de prueba a menos que tengan una preferencia.

Cuando falten campos opcionales, por defecto se generará solo el código fuente, paquete DSH estándar, comportamiento de solo lectura, sin mutación real de Perfil, sin reinicio, sin red/process/cuenta/dispositivo externos, sin credenciales, exposición solo local, sin publicación y aceptación E3 desechable. Construye paquetes DSH reutilizables con estructura de paquete compatible con el marketplace por defecto, pero no infiera autorización para enviar o cambiar DSH STORE. Declara cada valor predeterminado como una suposición. Sin publicación es un valor predeterminado de autorización, no una prohibición permanente: una versión fija explícitamente autorizada, con licencia adecuada y internamente consistente puede distribuirse desde un sitio web o proponerse a un marketplace.

Haz solo preguntas cuyas respuestas cambien materialmente el resultado del producto o el límite de riesgo. La falta de problema, resultado o criterio de aceptación bloquea la generación. La falta de Perfil objetivo, alcance de mutación, propietario de credenciales, seguridad LAN/Internet o dispositivo/cuenta real bloquea solo la operación real correspondiente; no bloquea un andamio de código fuente seguro cuando las interfaces pueden permanecer abstractas.

Ejecuta el normalizador determinista cuando haya un resumen JSON disponible:

node scripts/normalize-brief.mjs /ruta/absoluta/hacia/plugin-brief.json
node scripts/normalize-brief.mjs /ruta/absoluta/hacia/plugin-brief.json --json

Si el estado normalizado es LISTO o LISTO_CON_SUPOSICIONES y el modo solicitado es generar-codigo-fuente, procede a través de las Fases 0–6 sin otra ronda de aclaración amplia. Detente antes del lanzamiento, mutación real de Perfil, reinicio, credenciales, dispositivo o exposición pública a menos que esté autorizado por separado y completamente especificado.

Establecer el contrato

Comienza en modo solo lectura. Inspecciona las instrucciones del repositorio, la versión objetivo de DSH, la documentación oficial de plugins, el Perfil activo solo cuando sea relevante y un ejemplo de plugin estándar actual. No asumas una API o contrato de paquete de un proyecto anterior.

Siempre aplica estas reglas:

• Construye un paquete DSH, no una aplicación de escritorio ni un fork de DSH.
• Nunca modifiques el árbol fuente de DSH ni ningún paquete @deepseek-ai/*.
• Nunca deshabilites, reemplaces o ensombrezcas el inventario oficial de plugins.
• Nunca llames a APIs de mutación de Loader/Fiber. Usa servicios públicos de Host y composición de paquetes.
• Usa la CLI oficial de DSH para cambios de paquetes. Pasa arrays de argumentos fijos; nunca construyas cadenas de comando de shell.
• Mantén las pruebas en hogares/perfiles desechables. Nunca escribas pruebas contra ~/.dsh real.
• No expongas credenciales, archivos completos de usuario, contexto inyectado de sistema/plugin, razonamiento del modelo o rutas privadas a través de registros o clientes.
• Mantén la planificación, finalización de código, lanzamiento de paquete, instalación de Perfil, aceptación de tiempo de ejecución y aceptación externa/dispositivo como estados separados.
• Mantén la preparación del plugin, preparación como candidato de catálogo, PR/CI de Registry, catálogo fusionado, visibilidad del marketplace público e instalación de Perfil como estados separados.
• Mantén la salida canónica de Tool, la representación orientada al modelo, la intención de tarjeta neutral del proveedor y la representación opcional del Cliente como contratos separados.

Lee boundaries.md antes de la implementación o instalación. Los bloqueadores difíciles en ese archivo anulan cualquier puntuación. Lee card-contract.md antes de implementar una Tool de modelo, presentCall, presentResult, presentationMeta o una tarjeta personalizada de Cliente.

Explicar cada decisión trascendental

No emitas una lista de reglas sin su lógica de decisión. Para cada decisión de arquitectura, permiso, mutación, lanzamiento o aceptación, registra:

1. Objetivo: el fallo o resultado que controla la decisión.
2. Justificación: por qué la mecánica de DSH o el modelo de amenazas actual lo requiere.
3. Beneficios: qué se vuelve más seguro, más simple, más compatible o más fácil de verificar.
4. Costos: carga de implementación, fricción UX, costo de rendimiento, pérdida de capacidad o retraso operativo.
5. Aplicabilidad: las condiciones bajo las cuales la decisión es apropiada.
6. Alternativas: opciones viables, por qué fueron rechazadas y cuándo reconsiderarlas.
7. Procedimiento: pasos concretos, propietario, entradas, salidas y comportamiento de reversión.
8. Puerta de evidencia: la prueba observable requerida para avanzar y la condición que detiene el trabajo.

Lee decision-guide.md al planificar, revisar o explicar un plugin. Usa sus tarjetas de decisión en lugar de copiar un patrón preferido sin análisis.

Ejecutar el flujo de trabajo

Sigue workflow.md para el proceso completo con etapas y artefactos requeridos. No te saltes una etapa solo porque un plugin similar la haya pasado previamente; las versiones de DSH, la composición de Perfiles, las dependencias y los servicios externos pueden variar.

1. Probar la idoneidad del host

Identifica el host objetivo, la costura de extensión, el resultado solicitado por el usuario, las mutaciones de estado, las dependencias externas y la superficie de aceptación.

Detente e informa de una falta de coincidencia de host cuando el proyecto apunte a Obsidian, VS Code, una extensión de navegador, solo MCP u otro tiempo de ejecución sin un contrato de paquete DSH probado. Ofrece el host compatible o un adaptador deliberadamente limitado. No te desvíes hacia un proyecto adyacente.

Produce un registro de contrato de host y una comparación de arquitectura. Puerta: compatible, requiere-adaptador o incompatible; nunca dejes esto como prosa implícita.

2. Clasificar el riesgo

Asigna una clase de scorecard.md:

• R0: metadatos/UI de solo lectura.
• R1: herramientas/servicios de Host o estado de plugin propiedad del usuario, sin escrituras en el ciclo de vida del Perfil.
• R2: proceso externo, red, credenciales o puente de dispositivo.
• R3: ciclo de vida del Perfil, reinicio, control remoto o gestión amplia.

Usa la clase superior cuando no estés seguro. Registra los no-objetivos y las superficies prohibidas antes de codificar.

Produce un registro de riesgos que nombre activos, actores, límites de confianza, superficies de escritura, impacto de fallo, nivel mínimo de evidencia y la razón para elegir la clase.

3. Seleccionar el patrón estándar

• Paquete solo-host: expone un servicio/herramienta pública de Cordis y contribuye una o más filas de parche únicas.
• Host + Cliente: mantén el código del Navegador separado; regístrate con window.__ModuleLoader__.load() y slots. El código del Navegador no debe importar módulos de Host/Node.
• Ruta Web opcional: retrasa el registro con ctx.inject(['webServer'], ...); los perfiles sin cabeza/sin Web aún deben arrancar.
• Adaptador de habilidad: monta archivos de Skill aislados; no instales silenciosamente el tiempo de ejecución externo, la extensión o las credenciales.
• Puente ApiProxy: adapta la superficie remota pública estrecha con una lista blanca, redacción, autenticación, análisis acotado y seguridad de transporte de cierre en fallo.
• Gestor de ciclo de vida: trata cada cambio de Perfil como una transacción R3 y usa el protocolo de mutación a continuación.
• Contrato de tarjeta de herramienta: prefiere intenciones de representación presentCall/presentResult neutrales al proveedor; usa una tarjeta personalizada del Slot del Cliente solo para una herramienta propiedad del plugin cuando el vocabulario incorporado inspeccionado no pueda expresar el resultado.

Crea un manifiesto de paquete con dsh.bundle.patch, un cordis.patch.yml resoluble por paquete, IDs de entrada únicas, archivos explícitos, versión, licencia y contrato de compilación. Recuerda que las capas de parche posteriores reemplazan el config completo de una fila; no lo fusionan en profundidad.

Compara al menos dos patrones plausibles cuando la elección afecte permisos, límites de proceso, comportamiento de instalación o experiencia de usuario. Registra beneficios y costos; no selecciones una arquitectura solo porque un proyecto anterior la usó.

4. Implementar el mínimo privilegio

Usa servicios públicos ya proporcionados por la versión inspeccionada de DSH. Si la costura requerida está ausente, detente y propón un adaptador o un cambio ascendente en lugar de parchear el núcleo.

Prefiere el descubrimiento de solo lectura y las APIs de vista previa/ensayo. Haz que las funciones de escritura se habiliten por separado. Valida esquemas y límites de tamaño antes de la lógica de negocio. Rechaza perfiles malformados, rutas ambiguas, componentes oficiales desconocidos, estado obsoleto, repetición, cambios concurrentes y evidencia faltante.

Para cada Tool de modelo, registra la salida canónica, el renderizador orientado al modelo, la tarjeta pendiente, la tarjeta completada, los metadatos de presentación duraderos, los límites/redacción, la alternativa genérica y la evidencia en vivo/repetida. Los presentadores deben ser deterministas y no realizar E/S, acceso a reloj/aleatorio, lecturas de sesión o trabajo adicional que conlleve permisos. Nunca pongas credenciales, archivos privados completos, razonamiento del modelo o argumentos no acotados en una tarjeta.

Para patrones de fallo recurrentes, lee problem-playbook.md.

Produce una matriz de permisos con cada fuente de datos/acción, lado propietario, llamante permitido, redacción, límite de tamaño/tasa, modo de fallo y prueba. Cualquier permiso sin un resultado de usuario y una prueba es eliminado.

5. Aplicar el protocolo de mutación

Para mutaciones de Perfil/paquete/reinicio, crea un nuevo plan escrito para exactamente una operación que contenga:

1. operación y Perfil objetivo;
2. identidad inmutable del paquete/fuente;
3. alcance exacto del archivo y hashes de condición previa esperados;
4. argv de comando y directorio de trabajo;
5. ubicación de copia de seguridad y procedimiento de reversión;
6. condición posterior y comprobaciones de salud;
7. una frase de confirmación exacta;
8. caducidad e identidad de un solo uso.

Muestra el plan y espera la confirmación exacta por operación. Invalídalo en caso de discrepancia, caducidad, cambio concurrente o uso previo. Haz una copia de seguridad antes de escribir, confirma atómicamente, ejecuta comprobaciones de salud de configuración y tiempo de ejecución, y revierte en caso de fallo. Un lanzamiento de repositorio nunca autoriza una actualización local de Perfil.

Trata la fricción de confirmación y la maquinaria de transacción como costos explícitos. Acepta esos costos para R3 porque la alternativa es una corrupción silenciosa y difícil de recuperar del estado del usuario. No impongas el protocolo de mutación en lecturas R0 puras.

6. Subir la escalera de evidencia

Avanza solo con evidencia actual:

• E0: idea o plan.
• E1: revisión de estructura/código fuente estático.
• E2: pruebas automatizadas unitarias/de contrato/fallos.
• E3: instalación de Perfil desechable, --dump-config, inicio y prueba de humo de API.
• E4: versión de Perfil real confirmada por separado, proceso/puerto, inventario/API oficial y lectura de vuelta de UI visible.
• E5: aceptación externa/pública/dispositivo más recuperación de fallos o evidencia de reversión.

Nunca infieras un nivel superior de uno inferior. Las capturas de pantalla de UI no prueban la reversión; HTTP 200 no prueba UI visible; el éxito de instalación no prueba salud de reinicio; la salida del simulador no prueba un dispositivo real.

Para tarjetas de Tool, E2 incluye presentador determinista, repetición malformada, redacción, límite, truncamiento y pruebas de alternativa genérica. E3 incluye paridad de repetición en vivo más persistida en un tiempo de ejecución de DSH aislado. El comportamiento visible de la tarjeta en el Perfil del usuario sigue siendo E4.

Produce una matriz de evidencia por capacidad. Incluye evidencia negativa y de recuperación, no solo el camino feliz. Una puntuación clasifica la preparación; nunca otorga autoridad ni reemplaza una puerta difícil.

7. Lanzar e instalar por separado

Antes del lanzamiento del repositorio, sincroniza la versión del paquete, README, entrada de catálogo, anclaje de instalación inmutable, pruebas y metadatos de código fuente fijos. Para fuentes Git, envía artefactos construidos o declara un script prepare autocontenido y divulga pnpm allowBuilds; fija un SHA de commit completo.

Ejecuta comprobaciones de repositorio, verificación de código fuente y ensayo de empaquetado. Verifica el commit remoto y los activos públicos después de la fusión. Luego, detente. Actualiza un Perfil real solo bajo un nuevo plan de mutación confirmado, reinícialo a través del mecanismo aprobado y lee la versión resuelta y el estado del tiempo de ejecución.

Produce dos informes separados: evidencia de lanzamiento de repositorio y evidencia de aceptación de Perfil/tiempo de ejecución. Cuando falte el segundo informe, declara Perfil sin cambios o Perfil no verificado.

8. Hacer que los plugins reutilizables estén listos para DSH STORE

Lee marketplace.md cada vez que construyas un plugin DSH reutilizable de terceros, evalúes un repositorio existente para DSH STORE o prepares una entrada de catálogo.

No esperes hasta el envío para descubrir incompatibilidad de listado. Desde el primer andamio, reserva IDs únicas de paquete/catálogo/entrada; declara repositorio, versión, licencia, dsh.bundle.patch seguro, Patch relativo al paquete, archivos de tiempo de ejecución/compilación, scripts de ciclo de vida, permisos, dependencias y evidencia de compatibilidad. Al inicio de cada evaluación de STORE, ejecuta node scripts/official-dsh-releases.mjs y usa su ventana oficial de las últimas tres versiones; no reutilices una ventana recordada. El resolvedor sigue el canal latest/alpha/beta/rc de npm activo más alto, excluye versiones solo next y obsoletas, y falla cerrado en autoridad no válida. La ventana observada de 2026-09-02 es 0.1.2-alpha.2, 0.1.2-alpha.3 y 0.1.2-alpha.4, pero es evidencia en lugar de una constante permanente. Mantén registros exactos de compatibility.dshReleases y compatibility.dshOperations coincidentes para instalar, iniciar, desinstalar y revertir en cada lanzamiento dentro de la ventana resuelta. Las claves históricas pueden permanecer, pero los metadatos desconocidos permanecen desconocidos en lugar de adivinarse.

Mantén el descubrimiento de STORE y la instalación confiable separados física y lógicamente. Un registro en registry/candidates.json es solo de descubrimiento, no lleva ningún contrato de paquete/instalación/permiso y debe normalizarse a installable: false sin acciones permitidas. Puede moverse a registry/catalog.json solo después de una revisión separada de fuente fija, paquete, licencia, permiso, compatibilidad y evidencia. La promoción, recomendación, patrocinio, Estrellas o pantalla...

[...truncado para traducción]