PerryLink/dsh-plugin-guide

Desarrollo de Plugins para DeepSeek Harness (dsh-plugin-guide)

Desarrolla plugins para DeepSeek Harness basándote en la documentación oficial. Esta habilidad es una lista de restricciones y flujo de trabajo; todos los detalles fácticos deben citar el texto original de la base de conocimiento, sin inventar nada de memoria. Todas las cláusulas de "debe/no debe" provienen del repositorio oficial AGENTS.md, docs/ y el sitio de documentación; en caso de conflicto, prevalecerá el texto oficial original.

Ubicación de la Base de Conocimiento (buscar en orden, usar la primera que exista)

Esta habilidad y la base de conocimiento se distribuyen en el mismo directorio (el directorio donde se encuentra este SKILL.md es la raíz de la base de conocimiento); las rutas son relativas. Si se copia este archivo solo sin las carpetas guide/, references/, se utilizarán las rutas de respaldo:

1. Mismo directorio que este archivo: ./guide/ (guía completa + tabla de referencia rápida + índice de enlaces de documentación), ./references/ (informes de investigación y copias completas de la documentación oficial references/official-docs/docs/), ./downloads/ (descargas originales, opcional)
2. Copia principal local: D:\deepseek-harness\Project\Plugins\dsh-plugin-guide\ (ruta de ejemplo, ajustar según la instalación real)
3. Checkout del repositorio oficial: D:\deepseek-harness\ (docs/, vendor/cordis/, packages/, examples/)
4. En línea: https://github.com/deepseek-ai/deepseek-harness , https://deepseek-harness.github.io/deepseek-harness/develop/basic/ , https://github.com/cordiverse/cordis

Las rutas relativas a continuación son relativas al punto 1 anterior (directorio donde se encuentra este archivo de habilidad).

Requisitos Previos de Desarrollo (Paso 1 Obligatorio)

1. Si aún no has leído los conceptos de Cordis: lee references/official-docs/docs/cordis-primer.md (5 conceptos, 5 minutos); cuando necesites practicar, ejecuta los tutoriales references/official-docs/docs/cordis-tutorial/ 01-07 (se pueden ejecutar sin API key).
2. Abre guide/quick-reference.md (contrato rápido) + guide/plugin-dev-guide.md (ruta completa). La correspondencia de URL de documentos oficiales/comunitarios está en guide/links.md.
3. Confirma los puntos de extensión objetivo: lee la tabla "Where new behavior goes" en references/official-docs/docs/architecture.md y la tabla feature→mechanism en references/official-docs/docs/cookbook/extension-cookbook.md — el nuevo comportamiento debe conectarse a un punto de extensión documentado; no está permitido modificar el agent-loop.

Contratos de Plugins Obligatorios (Líneas Rojas Oficiales, Verificar Una por Una)

• Plugin = exportación de módulo name + apply(ctx, config) (+ opcional inject: string[]); los servicios de los que depende están listos antes de apply; si un servicio dependiente desaparece, se desinstala automáticamente, y al recuperarse se recarga automáticamente.
• Registrar es efectuar: toda contribución pasa por ctx.effect() / ctx.on() / register() del servicio (devuelve un disposer); nunca se debe usar removeListener/clearInterval manual para la limpieza.
• Los listeners de waterfall deben llamar a next(); no llamarlo es un cortocircuito intencional (semántica de intercepción). Las semánticas de emit/waterfall/parallel/serial/bail están en la tabla de referencia rápida.
• Visible por el modelo ⟺ registrado: todo lo que entre en una solicitud del modelo debe poder reconstruirse desde los registros de la sesión; cualquier nueva entrada visible por el modelo debe agregar un nuevo evento de sesión SessionEventMap.
• Los eventos/servicios con seguridad de tipos usan declaration merging (declare module '@deepseek-ai/cordis'); la documentación de eventos debe anotar @mode.
• La configuración usa Schema<Config> de Schemastery (prohibidos objetos planos); las configuraciones inválidas fallan ruidosamente en tiempo de carga; no se permiten parámetros ajustables hardcodeados (criterio: ¿se puede cambiar desde cordis.yml?).
• Las herramientas usan defineTool: execute solo devuelve valores JSON estándar declarados en output.schema; respeta exec.signal; el contenido legible por humanos va en output.render; el presenter de la tarjeta UI es una función pura (prohibido I/O/temporizadores/aleatoriedad).
• Las capacidades reemplazables se diseñan con tres capas de juntas: Service Definition / Provider / Consumer; no descomponer prematuramente.
• Empaquetado: lista bundle "dsh":{"bundle":{"patch":"..."}}; la sobrescritura reemplaza toda la línea de config por id; !!js (doble signo de exclamación); la instalación desde git requiere script prepare y allowBuilds por parte del usuario; la publicación como npm/tarball no necesita permiso de compilación.

Rutas de Desarrollo por Tipo de Tarea

(Las siguientes rutas están en references/official-docs/, copias completas de la documentación oficial)

• Nueva herramienta: docs/user/develop/basic/tool.md (tutorial) → docs/cookbook/adding-a-tool.md (contrato completo: validación de parámetros, valores estándar, tareas en segundo plano ctx.jobs, hooks de estrategia, Code Mode, tarjetas UI) → implementación de referencia packages/shell/tool-bash (checkout local).
• Nuevo servicio/capacidad: docs/user/develop/framework/service.md + docs/user/develop/practice/ (código completo de descomposición en tres capas).
• Intercepción/estrategia/hook: docs/cookbook/extension-cookbook.md (ejemplo permission-gate) + docs/event-producer-consumer.md (matriz de eventos completa).
• Nuevo proveedor de LLM: docs/user/develop/practice/llm-adapter.md (protocolo StreamChunk).
• Nodo de UI/sesión: docs/cookbook/adding-a-conversation-node.md + docs/subsystems/session.md, client-modules.md.
• Empaquetado/publicación: docs/user/develop/basic/publish.md (bundle/profile, orden de capas, problemas de instalación desde git).
• Consultar firma exacta de servicios/eventos: docs/subsystems/*.md y área de API de Cordis generativa + docs/cordis-api/*; no crear una segunda lista estática. La correspondencia de URL del sitio con la copia local está en guide/links.md; la lista completa de enlaces comunitarios está en references/community-ecosystem.md.
• Referencia de implementaciones comunitarias y problemas medidos: references/community-ecosystem.md, references/community-repo-deep-dive.md (lectura profunda de 15 repositorios de desarrollo), downloads/community-repos/ (copias completas del código fuente, generadas ejecutando primero scripts/download-community-repos.ps1). Los cambios de mecanismo confirmados por la comunidad (como la eliminación de repository-plugin en agosto de 2021, el doble canal bundle vs cordis puro) y 20 problemas medidos (copia dual de cordis/conjunto de tres archivos tsconfig/zstd multiframe/junction de Windows, etc.) están en guide/plugin-dev-guide.md §7.

Verificación (Antes de la Entrega)

• Verificación de carga: dsh --profile <nombre> --dump-config para comprobar si la línea de patch está activa; el registro de inicio no debe mostrar FAILED.
• Verificación de comportamiento: probar con Web UI o dsh --profile headless "…"; la salida de la herramienta/texto visible por el modelo es el comportamiento; cualquier cambio debe volver a probarse.
• Los cambios dentro del repositorio requieren adicionalmente: comprobación de tipos, pruebas del paquete objetivo, snapshot sin clave (el comportamiento visible del modelo/producto debe tener un snapshot de transcripción después del montaje), documentación bilingüe emparejada, Agent Note (en el mismo PR para cambios no triviales).
• Paquete de plugin independiente: después de pnpm pack, probar la instalación en un perfil limpio (incluyendo el artefacto de compilación lib/).

Mantenimiento de la Base de Conocimiento (Cuando Sea Necesario)

• Sincronizar copia de la documentación oficial: pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <checkout de deepseek-harness>] — solo sincroniza archivos rastreados por git (los borradores no rastreados y las confirmaciones no enviadas no se incluyen) y actualiza references/official-docs/SNAPSHOT.md; la fecha de "última verificación" y el hash de confirmación en el README deben referenciar SNAPSHOT.md, no se deben modificar manualmente. Verificación de deriva: pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>.
• Actualizar materiales en línea: pwsh -File ./scripts/download-sources.ps1; actualizar repositorios comunitarios: pwsh -File ./scripts/download-community-repos.ps1 (ambos scripts son idempotentes, los resultados van a ./downloads/). Recuento de listas de temas: pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <dir> -MaxPages 20 (GitHub Search API q=topic:dsh-plugin; límite superior de paginación 1000 elementos; tanto el recuento desduplicado como el total_count de la API deben registrarse en sources.md §D.2).
• Instalar/actualizar copia de la habilidad de agente: pwsh -File ./scripts/install-skill.ps1 -Target <directorio de skill> (omite downloads/ y .github/, verifica byte a byte).
• Resolución de conflictos: en caso de conflicto con la documentación oficial, prevalece references/official-docs/ (texto original del repositorio oficial).

Límites

• Esta habilidad es una "guía + restricciones + índice de recursos", no una ejecución mecánica de scripts/listas; la API precisa se basa en la referencia generativa.
• No está permitido modificar archivos del repositorio harness fuera de la base de conocimiento, a menos que el usuario lo solicite explícitamente; vendor/ y .agents/notes/archived/ son de solo lectura.
• Antes de referenciar contenido de downloads/, verificar que exista (este directorio no está en git; debe generarse con los scripts anteriores); el archivo de awesome-dsh-plugins es solo para referencia local, no se puede redistribuir con el repositorio (su declaración de uso interno tiene restricciones, ver NOTICE.md).