182 lines
6.8 KiB
Markdown
182 lines
6.8 KiB
Markdown
# INSTALL — pi-new-project
|
|
|
|
Instalación del paquete/skill `new-project` en pi, en este ordenador o en
|
|
cualquier otro.
|
|
|
|
Repositorios:
|
|
|
|
- **Distribución** (para usarlo): <https://git.sargatxet.cloud/sargatxet/pi-new-project-dist>.
|
|
Solo contiene lo que pi necesita: `package.json`, `LICENSE`, `extensions/`,
|
|
`skills/` y un `README.md` mínimo. Se genera con `scripts/publicar-dist.sh`.
|
|
- **Desarrollo** (para modificarlo): <https://git.sargatxet.cloud/sargatxet/pi-new-project>.
|
|
|
|
## 1. Requisitos
|
|
|
|
| Componente | Versión mínima | Notas |
|
|
| --- | --- | --- |
|
|
| pi | 1.3.0 | Hace falta soporte de skills y de paquetes (`pi install`). |
|
|
| bash | 4.0 | El script usa arrays y `${var//}`. |
|
|
| git | cualquiera | Opcional: `--git` y autor por defecto. |
|
|
| shellcheck | opcional | Para validar el script (`shellcheck new-project.sh`). |
|
|
|
|
## 2. Opción A — instalarlo como paquete de pi desde git (recomendado)
|
|
|
|
pi clona el repositorio de distribución y lo instala directamente:
|
|
|
|
```bash
|
|
pi install git:git.sargatxet.cloud/sargatxet/pi-new-project-dist
|
|
# equivalente, con la URL completa:
|
|
pi install https://git.sargatxet.cloud/sargatxet/pi-new-project-dist
|
|
```
|
|
|
|
Para fijar una versión concreta, añade una etiqueta (`v0.3.0`, …) o un commit:
|
|
`pi install git:git.sargatxet.cloud/sargatxet/pi-new-project-dist@<etiqueta-o-commit>`.
|
|
Añade `-l` (`--local`) para declararlo solo en el proyecto actual
|
|
(`.pi/settings.json`) en lugar de en `~/.pi/agent/settings.json`.
|
|
|
|
Comprueba con `pi list` y arranca pi: la skill aparecerá como `new-project` y
|
|
estará disponible la orden `/modelo-proyecto`.
|
|
Para una prueba puntual sin instalarlo:
|
|
`pi -e git:git.sargatxet.cloud/sargatxet/pi-new-project-dist`.
|
|
|
|
> Si ya lo tenías instalado desde el repositorio de desarrollo
|
|
> (`git:git.sargatxet.cloud/sargatxet/pi-new-project`), pi lo considera otro
|
|
> paquete: quítalo antes con `pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project`
|
|
> para que la skill no se cargue dos veces.
|
|
|
|
### Desde una copia local del repositorio de desarrollo
|
|
|
|
Si vas a revisarlo o modificarlo:
|
|
|
|
```bash
|
|
git clone https://git.sargatxet.cloud/sargatxet/pi-new-project.git
|
|
pi install ./pi-new-project
|
|
```
|
|
|
|
Una instalación local se carga desde ese directorio sin copiarlo: los cambios
|
|
(o un `git pull`) se aplican en la siguiente sesión de pi.
|
|
|
|
## 3. Opción B — copiar la skill
|
|
|
|
Copia el directorio de la skill a una de las rutas que pi descubre:
|
|
|
|
```bash
|
|
mkdir -p ~/.agents/skills
|
|
cp -r pi-new-project/skills/new-project ~/.agents/skills/
|
|
```
|
|
|
|
o enlázalo para mantenerlo actualizado con el repositorio:
|
|
|
|
```bash
|
|
ln -s "$PWD/pi-new-project/skills/new-project" ~/.agents/skills/new-project
|
|
```
|
|
|
|
Rutas equivalentes: `~/.pi/agent/skills/` y, por proyecto, `.agents/skills/`.
|
|
|
|
En estos ejemplos, `pi-new-project/` es una copia del repositorio obtenida con
|
|
`git clone https://git.sargatxet.cloud/sargatxet/pi-new-project-dist.git pi-new-project`
|
|
(o del de desarrollo, `.../pi-new-project.git`; ambos tienen `skills/` y `extensions/`).
|
|
|
|
La skill sola no incluye la orden `/modelo-proyecto` ni la herramienta
|
|
`elegir_modelo_proyecto`; cópialas también (o la skill usará el plan B,
|
|
`pi --list-models` + `--modelo`):
|
|
|
|
```bash
|
|
mkdir -p ~/.pi/agent/extensions
|
|
cp pi-new-project/extensions/modelo-proyecto.ts ~/.pi/agent/extensions/
|
|
```
|
|
|
|
## 4. Opción C — exportar a otro ordenador sin acceso al repositorio
|
|
|
|
Si el ordenador destino tiene acceso a
|
|
<https://git.sargatxet.cloud/sargatxet/pi-new-project-dist>, basta con la opción A.
|
|
Si no, copia el directorio (mejor el de distribución, que solo trae lo necesario);
|
|
no tiene dependencias.
|
|
|
|
```bash
|
|
# en el ordenador origen
|
|
tar -czf pi-new-project-0.3.0.tar.gz pi-new-project/
|
|
|
|
# en el ordenador destino
|
|
tar -xzf pi-new-project-0.3.0.tar.gz
|
|
pi install ./pi-new-project # o la opción B
|
|
```
|
|
|
|
|
|
## 5. Verificación
|
|
|
|
```bash
|
|
bash -n pi-new-project/skills/new-project/scripts/new-project.sh
|
|
pi-new-project/skills/new-project/scripts/new-project.sh --dry-run --nombre Demo /tmp/demo
|
|
|
|
# prueba real en un directorio temporal
|
|
pi-new-project/skills/new-project/scripts/new-project.sh \
|
|
--nombre Demo --descripcion "Proyecto de prueba" --git /tmp/demo
|
|
ls -A /tmp/demo
|
|
```
|
|
|
|
Deben aparecer `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TODO.md`, `INSTALL.md`
|
|
y `.gitignore`, sin marcadores `{{...}}` pendientes.
|
|
|
|
Modelo por defecto:
|
|
|
|
```bash
|
|
pi-new-project/skills/new-project/scripts/new-project.sh \
|
|
--nombre Demo --modelo anthropic/claude-sonnet-4-5 /tmp/demo2
|
|
cat /tmp/demo2/.pi/settings.json
|
|
```
|
|
|
|
En pi, dentro de `/tmp/demo2`, `/modelo-proyecto` debe mostrar el selector de
|
|
modelos y actualizar `.pi/settings.json`.
|
|
|
|
## 6. Actualización
|
|
|
|
```bash
|
|
pi update --extensions # instalado desde git: actualiza el clon gestionado por pi
|
|
|
|
# instalado desde una copia local o copiado (opción B):
|
|
cd pi-new-project && git pull
|
|
```
|
|
|
|
Si se instaló con una etiqueta o un commit fijo (`@<ref>`), `pi update` no lo
|
|
mueve: reinstala con la nueva referencia.
|
|
|
|
## 7. Desinstalación
|
|
|
|
```bash
|
|
pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project-dist # paquete desde git
|
|
pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project # instalaciones antiguas
|
|
pi remove ./pi-new-project # paquete desde una copia local
|
|
rm -rf ~/.agents/skills/new-project # si se copió o enlazó
|
|
rm -f ~/.pi/agent/extensions/modelo-proyecto.ts
|
|
```
|
|
|
|
La skill no deja estado propio: no hay caché ni configuración que limpiar.
|
|
|
|
## Publicar una versión (mantenedores)
|
|
|
|
El repositorio de distribución se genera desde el de desarrollo; no se edita a
|
|
mano. Con los cambios ya commiteados y la versión subida en `package.json` y
|
|
`CHANGELOG.md`:
|
|
|
|
```bash
|
|
scripts/publicar-dist.sh --dry-run # prepara y muestra el contenido sin subir nada
|
|
scripts/publicar-dist.sh # commit + etiqueta vX.Y.Z en pi-new-project-dist
|
|
```
|
|
|
|
El script toma el contenido de `HEAD` (no del directorio de trabajo), se niega a
|
|
publicar si hay cambios sin commitear en lo que se publica o si la etiqueta ya
|
|
existe, y necesita permiso de escritura en el repositorio de distribución.
|
|
|
|
## 8. Resolución de problemas
|
|
|
|
| Síntoma | Causa probable | Solución |
|
|
| --- | --- | --- |
|
|
| La skill no aparece | Ruta no descubierta | Comprueba la ruta con `pi list` o colócala en `~/.agents/skills/`. |
|
|
| `no encuentro las plantillas` | Falta `templates/` | Reinstala el paquete completo, no solo el script. |
|
|
| `no puedo deducir el nombre` | Destino `.` o `/` | Pasa `--nombre`. |
|
|
| No sobreescribe mis ficheros | Protección por defecto | Usa `--force` tras revisar `--dry-run`. |
|
|
| El proyecto no arranca con su modelo | Proyecto no confiado: pi ignora `.pi/settings.json` | Ejecuta `/trust` en el proyecto. |
|
|
| `/modelo-proyecto` no existe | Solo se copió la skill | Instala el paquete o copia `extensions/modelo-proyecto.ts`. |
|
|
| El selector sale vacío | Ningún proveedor con credenciales | `/login` o configura la API key del proveedor. |
|