Publicación de plugins de DeepSeek Harness: npm / GitHub / tarball
La instalación local ya funciona; podemos distribuir el plugin para que otros lo usen.
Publicar en un registro no es obligatorio; hay tres vías: npm, tarball y Git.
Los tres tienen requisitos completamente distintos respecto al artefacto de compilación; elegir mal hará que el usuario tropiece.
Comparación de tres métodos de distribución
La documentación oficial presenta tres métodos de distribución; la diferencia clave está en si se distribuye el artefacto precompilado.
| Método | Comando de instalación del usuario | Qué se instala | ¿Requiere autorización de compilación? |
|---|---|---|---|
| Publicación en npm | dsh plugin add your-package | Precompiladolib/código | No |
| Entrega de tarball | dsh plugin add ./hello-plugin-0.1.0.tgz | pnpm packEl paquete generado | No |
| Instalación por Git | dsh plugin --profile demo add github:you/hello-plugin | Código fuente (no artefacto de compilación) | Sí (pnpm ≥ 10) |
Ni npm ni tarball requieren permisos de compilación; son adecuados para escenarios donde no se quiere que el usuario haga autorizaciones adicionales.
La instalación por Git es la más flexible, pero hay que superar el obstáculo del "script de compilación".
Instalación por git: el obstáculo del script de compilación
La instalación por Git obtiene el código fuente, no el artefacto de compilación.
Ningún paso ejecuta tu script de compilación, por lo que el paquete TypeScript llega sinlib/salida; la carga fallará.
Cada lado debe hacer una cosa.
Del lado del autor, se debe proporcionar unpreparescript.
pnpm lo ejecuta después de la instalación por git, construyendo el punto de entrada de publicación desde el código fuente.
Debe ser autocontenido: no puede asumir un contexto exclusivo del entorno de desarrollo, por ejemplo, tener un checkout del monorepo al lado.
turtle-uies un ejemplo utilizable: su prepare ejecuta una configuración dedicada de tsdown, que transcompila directamentesrc/, sin referencias de proyecto ni verificación de tipos.
Ejemplo
"name": "dsh-hello-plugin",
"scripts": {
"prepare": "tsdown -c tsdown.publish.ts"
}
}
El script prepare anterior debe ser autocontenido: transcompilar directamentesrc/, sin depender del checkout del monorepo al lado.
Del lado del usuario, se debe autorizar la compilación.
pnpm ≥ 10 rechaza ejecutar el script prepare de una dependencia git hasta que se le conceda permiso explícito, por lo que la primera vez que se ejecuta add falla.
dsh indicará la solución: copiar la clave de paquete exacta que imprime pnpm en elpnpm-workspace.yaml。
dsh plugin --profile demo add github:you/hello-plugin
El primer add fallará porque prepare no está autorizado; pnpm imprimirá la clave de paquete exacta.
Cópiala en el pnpm-workspace.yaml del perfil, como se muestra a continuación.
Ejemplo
# Copia la clave de paquete exacta que imprime pnpm aquí para permitir que ejecute prepare
allowBuilds:
dsh-hello-plugin: true
Luego vuelve a ejecutar add.
dsh plugin --profile demo add github:you/hello-plugin # 第二次通过
Considera esta autorización con honestidad: permite que el código de ese paquete se ejecute en tu máquina durante la instalación, y no dentro de ninguna sandbox donde se ejecute el agente.
Autoriza solo paquetes cuyo código fuente sea confiable, y fija el commit (
github:you/hello-plugin#<sha>), para que futuras subidas no puedan cambiar silenciosamente lo que realmente se ejecuta.
La forma de instalar fijando el commit es la siguiente.
dsh plugin --profile demo add github:you/hello-plugin#a1b2c3d # 锁定到具体 commit
npm y tarball: sin autorización de compilación
Si no quieres que el usuario haga autorizaciones, distribuye en su lugar el artefacto de compilación.
Ninguna de las dos formas siguientes requiere permisos de compilación.
Primera: publicar en npm.
Enpnpm publishCompílalo en el momento de publicarlib/, el usuariodsh plugin add your-packageinstala el código precompilado.
# 作者侧：先构建再发布 pnpm build pnpm publish # 用户侧：安装的是预构建代码，无需授权 dsh plugin add your-package
Segunda: entregar un tarball.
usarpnpm packEmpaquétalo, y el usuario ejecutadsh plugin add ./hello-plugin-0.1.0.tgz。
# 作者侧：打出 tgz pnpm pack # 用户侧：直接安装 tarball 文件 dsh plugin add ./hello-plugin-0.1.0.tgz
Recomendación: si el código fuente es confiable y quieres omitir el proceso de compilación, usa la instalación por git y fija el commit; para usuarios comunes, prioriza publicar en npm o entregar un tarball, de modo que el usuario instale directamente sin autorizaciones.
Resumen y autoevaluación
Los tres métodos de distribución se distinguen según si distribuyen el artefacto precompilado: npm y tarball no requieren autorización de compilación; la instalación por Git obtiene el código fuente y requiere un script prepare autocontenido por parte del autor y la autorización allowBuilds por parte del usuario.
Preguntas de autoevaluación:
- ¿Por qué la instalación por git falla para paquetes TypeScript? ¿Qué debe hacer el autor?
- Cuando el primer add falla para usuarios de pnpm ≥ 10, ¿cómo sugiere dsh corregirlo?
- ¿Por qué se recomienda fijar el commit sha?