Skip to content

docs: add Spanish README #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
webbrain-one wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add Spanish README #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 203 additions & 0 deletions README.es-ES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@


# ACLIx

Español | [简体中文](./README_zh.md)

---

<img src="./assets/logo.jpg" alt="ACLIx" style="zoom:50%;" />

<p align="center">
<a href="https://www.npmjs.com/package/@aliasjeff/acli">
<img src="https://img.shields.io/npm/v/@aliasjeff/acli.svg" alt="npm version">
</a>
<a href="https://nodejs.org">
<img src="https://img.shields.io/node/v/@aliasjeff/acli.svg" alt="Node.js Version">
</a>
<a href="https://opensource.org/licenses/MIT">
<img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
</a>
</p>

**ACLIx** es un asistente de interfaz de línea de comandos que utiliza modelos de lenguaje grande para ejecutar tareas y responder consultas dentro de un entorno de terminal. Opera como un agente autónomo capaz de interactuar con el sistema operativo anfitrión, el sistema de archivos local y servicios web externos.

## Demo

<img src="./assets/acli-intro.gif" alt="ACLIx-intro" style="zoom:80%;" />

<p align="center">acli-intro</p>

<img src="./assets/acli-task.gif" alt="ACLIx-task" style="zoom:80%;" />

<p align="center">acli-task</p>

## Características

- **Preguntas y Respuestas:** Procesa las consultas del usuario utilizando el contexto de archivos locales o búsquedas web en tiempo real.
- **Escritura y Edición de Código:** Lee, escribe y modifica archivos locales. Las ediciones de archivos utilizan un mecanismo de reemplazo de cadena exacta protegido por **Bloqueo Optimista (Lectura antes de Escritura)** para prevenir sobrescrituras alucinadas.
- **Ejecución de Comandos y Paginación de Salida:** Ejecuta comandos de shell y scripts de Python directamente en la máquina anfitriona. Las salidas largas se truncan y almacenan en caché automáticamente, permitiendo al agente leer registros completos bajo demanda sin contaminación del contexto.
- **Orquestación de Tareas Complejas:** Descompone tareas complejas en un **Grafo de Tareas Persistente (DAG)**.
- **Aislamiento de Espacios de Trabajo:** Genera subagentes en **sandboxes de Git Worktree** aislados para garantizar una ejecución paralela segura y sin conflictos.
- **Prompts de Seguridad:** Utiliza un evaluador basado en AST para evaluar los riesgos de los comandos de shell. Pausa la ejecución para solicitar la confirmación del usuario antes de ejecutar operaciones que modifiquen el estado del sistema o representen un riesgo de seguridad.

## Diseño Central

### Orquestación de Agentes

El sistema emplea un patrón de Orquestador Maestro combinado con la metodología **Re-Act**. Para tareas complejas, el agente principal mapea un **Grafo de Tareas Persistente (DAG)** respaldado por SQLite. Luego delega subobjetivos a **Subagentes** especializados y cargados dinámicamente (p. ej., Planificador, Explorador, Ejecutor).

Para prevenir conflictos de archivos y gestionar los límites de tokens de manera eficiente, los subagentes operan en **Sandboxes de Git Worktree** físicamente aislados. Esto permite una ejecución paralela real. Una vez completadas las subtareas, el Orquestador Maestro revisa y fusiona el worktree de vuelta a la rama principal.

### Herramientas

Las herramientas son funciones nativas proporcionadas al agente para interactuar con el entorno:

- `shell`: Ejecuta comandos del sistema operativo.
- `python`: Ejecuta scripts de Python o código inline.
- `file_read`: Lee el contenido de archivos con límites de paginación y devuelve un `FileHash` en tiempo real.
- `file_write`: Sobrescribe o crea nuevos archivos (requiere un `expectedHash` válido).
- `file_edit`: Modifica archivos existentes utilizando reemplazo de cadena exacto indiferente a espacios en blanco (requiere un `expectedHash` válido).
- `glob`: Localiza archivos basándose en patrones de nomenclatura, ignorando automáticamente directorios pesados.
- `grep`: Busca texto dentro de archivos.
- `ask_user`: Solicita entrada del usuario para contraseñas o parámetros faltantes.
- `web_search`: Busca información actual en la web utilizando la API de Tavily.
- `read_skill`: Carga las instrucciones de un flujo de trabajo o Procedimiento Operativo Estándar (SOP) específico.
- `read_tool_output`: Recupera registros completos paginados para salidas largas de herramientas truncadas almacenadas en caché en la base de datos.
- `manage_task`: Gestiona el estado del Grafo de Tareas Persistente (DAG) para planificación a largo plazo.
- `merge_worktree`: Fusiona los Git worktree aislados de los subagentes de vuelta a la rama principal.

### Sistema de Memoria Jerárquica

ACLIx gestiona el contexto a través de una arquitectura de memoria multicapa:

- **Memoria a Largo Plazo (LTM):** Estado persistente mantenido en archivos Markdown a nivel de usuario (`~/.aclix/ACLI.md`) y nivel de proyecto (`./ACLI.md`), dictando hechos permanentes, restricciones y preferencias.
- **Memoria a Corto Plazo (STM):** Historial de conversación basado en sesiones respaldado por una base de datos SQLite local, que permite la restauración de estado a través de sesiones REPL.
- **Memoria Comprimida (CM):** Un sistema automatizado de resumen incremental. Cuando los límites de tokens o el número de mensajes superan los umbrales de seguridad, el motor invoca al LLM para comprimir el contexto histórico en un resumen denso, descartando mensajes crudos más antiguos para ahorrar tokens.
- **Recuperación BM25:** Transición desde la inyección completa de LTM a un enfoque basado en recuperación local BM25. El sistema recuperará e inyectará selectivamente solo los 3 fragmentos de memoria más relevantes por consulta para optimizar aún más el uso de tokens y la relevancia del contexto.

### Habilidades y Reglas Extensibles

La arquitectura del sistema es altamente modular, dependiendo de un modelo de plugins basado en sistema de archivos.

- **Habilidades:** Definidas por archivos `SKILL.md` (junto con scripts opcionales). Representan SOPs enchufables que el agente puede aprender y ejecutar.
- **Reglas:** Definidas por archivos `RULE.md`. Inyectan restricciones de comportamiento específicas en el prompt del sistema del agente dinámicamente basándose en el directorio de trabajo actual.
- **Revelación Progresiva:** Esta arquitectura aprovecha la tecnología de revelación progresiva. En lugar de inundar el prompt del sistema inicial con todas las instrucciones disponibles, el agente solo carga SOPs detalladas o conjuntos de reglas específicos cuando son activados por el contexto actual del usuario o la intención explícita.

### Seguridad e HITL

1. **Evaluación de Riesgo de Comandos:** Todos los comandos de shell son analizados en un **Árbol Sintáctico Abstracto (AST)** y asignados a un nivel de riesgo (bajo, medio, alto). Las operaciones destructivas (p. ej., rm -rf /, sed -i), los escalonamientos de privilegios y las bombas bifurcadas son marcados automáticamente. Los comandos de riesgo medio y alto requieren confirmación explícita del usuario antes de la ejecución.
2. **Bloqueo Optimista (CAS):** Las modificaciones de archivos aplican un mecanismo estricto de Compare-And-Swap. El agente debe leer un archivo para obtener su `FileHash` actual antes de editarlo. Esto elimina por completo las sobrescrituras obsoletas y las modificaciones de código alucinadas.
3. **Capturas de Archivo Automáticas:** Antes de modificar cualquier archivo, se crea una instantánea invisible de SQLite, habilitando una reversión con un clic a través de `/undo`. Esto asegura la recuperabilidad y previene la pérdida accidental de datos.
4. **Protección contra Inyección de Prompts y Sanitización de Datos:** Todas las entradas no confiables se envuelven en `<untrusted_data>` para prevenir ataques de inyección de prompts. La información sensible se sanitiza automáticamente antes del procesamiento o registro, preservando la privacidad de los datos.

## Uso

### Instalación

Requiere Node.js v23 o superior.

```bash
npm install -g @aliasjeff/acli
```

### Modos de Ejecución

- **Modo de Comando:** Se activa con `acli chat "<query>"`. Procesa una sola solicitud del usuario, ejecuta la tarea y sale del proceso al completarse.
- **Modo REPL:** Se activa ejecutando `acli` sin argumentos. Inicia una sesión de shell interactiva. Los usuarios pueden mantener el contexto conversacional y utilizar comandos con barra diagonal (p. ej., `/history`, `/compact`, `/rules`, `/skills`, `/config`, `/clear`, `/exit`).

### Comandos

**Inicialización:**

Establece el proveedor de LLM, selecciona un modelo e ingresa las claves API.

```bash
acli onboard
```

**Sesión Interactiva (Modo REPL):**

Inicia una conversación continua con retención de contexto.

```bash
acli
```

**Tarea Única (Modo de Comando):**

Ejecuta un único objetivo y sale.

```bash
acli chat "Crear un archivo de texto que contenga la fecha actual"
```

**Gestión de Configuración:**

Inspecciona o actualiza los parámetros de configuración actuales.

```bash
acli config
```

## Arquitectura y Estructura de Directorios

ACLIx está estructurado en capas distintas para separar la interfaz CLI, la lógica central del agente y los servicios externos.

```plaintext
+-----------------------------------------------------------+
| User Input |
+-----------------------------+-----------------------------+
|
v
+-----------------------------+-----------------------------+
| CLI / REPL Interface |
| (Session Management, Command Parsing, Terminal UI) |
+-----------------------------+-----------------------------+
|
v
+-----------------------------------------------------------+
| Master Orchestrator |
| (Persistent Task Graph) |
+----------------------+----------------------+-------------+
| Subagents | Security Check | Memory |
| (Worktree Isolation) | (AST / CAS Locks) | (LTM, STM) |
+----------------------+----------------------+-------------+
|
+------------------------+------------------------+
| | |
v v v
+-----------+ +---------------+ +--------------+
| LLM APIs | | Tools | | Extensibility|
| (OpenAI, | | (Shell, File, | | (Skills, |
| Anthropic)| | Web Search) | | Rules) |
+-----------+ +---------------+ +--------------+
|
v
+-------------------------------+
| Local OS & File System |
+-------------------------------+
```

### Árbol de Directorios

```plaintext
.
├── bin/ # Punto de entrada CLI
├── src/
│ ├── cli/ # Analizadores de comandos, middleware y manejo de interrupciones
│ ├── core/ # Lógica central del sistema
│ │ ├── agent/ # Flujo de trabajo de chat y generación de prompts
│ │ ├── context/ # Seguimiento de contexto en tiempo de ejecución
│ │ ├── memory/ # Conteo de tokens y compresión de contexto
│ │ ├── rules/ # Administrador de reglas
│ │ ├── security/ # Evaluador de riesgos de comandos shell y bloqueos CAS
│ │ ├── skills/ # Administrador de habilidades
│ │ ├── subagents/ # Orquestación de subagentes y aislamiento de worktree
│ │ └── tools/ # Definiciones de herramientas
│ ├── repl/ # Motor de sesión interactiva y registro de comandos con barra
│ ├── services/ # Interfaces de configuración, base de datos, ejecutor, proveedor LLM y registrador
│ ├── shared/ # Tipos, errores y constantes
│ └── ui/ # Prompts de terminal y componentes visuales
└── package.json
```