FCoP

FCoP — Protocolo de Coordinación Basado en Archivos

English · 简体中文

Incluso cuando el agente ya no está, el trabajo permanece.

Las tareas, entregas, problemas y decisiones de revisión se convierten en archivos duraderos que las personas, las herramientas y el próximo agente pueden inspeccionar. Una sesión puede terminar sin llevarse consigo el registro del trabajo.

Pídele a la IA que lo instale · Referencia manual · Serie de arquitectura (中文) · Arquitectura · Documentos y citación

Versión estable: 4.0.3 — Lanzamiento 4.0.3. Este repositorio contiene el protocolo abierto, la implementación en Python de fcop y el adaptador opcional de fcop-mcp. Python 3.10+; no se necesita clave de API de modelo para el ejemplo local.

Pídele a tu IA que instale FCoP

Pega esto en Cursor Agent, Codex u otro agente de codificación con acceso a terminal y archivos. El agente gestiona la configuración y verifica el resultado.

Install FCoP for the coding client and project I am using. Follow:
https://github.com/joinwell52-AI/FCoP/blob/main/docs/ai-install.md
Run the environment checks, installation, configuration and verification yourself. Preserve my existing configuration and project state. Report what actually works; ask me only for a missing client/project choice or a required approval/reload.

La guía de instalación para IA cubre dependencias, configuración del cliente y una verificación con una tarea real. Si el cliente requiere aprobación o una recarga, el agente identificará ese paso. Las instrucciones manuales de Python/MCP se mantienen a continuación como referencia.

¿Quieres ver primero una transferencia? Pídele a la IA que ejecute el ejemplo de transferencia de sesión: English · 简体中文. Crea una tarea y un informe, cierra la sesión y luego léelos desde una nueva sesión de MCP. No se requiere clave de API; el resultado permanece disponible para inspección.

macOS (Intel y Apple silicon): instalar CLI y MCP

FCoP es compatible con macOS tanto en Intel como en Apple silicon. Los wheels publicados son independientes de la plataforma; no se requiere Rosetta. Usa Python 3.10–3.13. La CLI funciona directamente en Terminal, mientras que MCP requiere además un cliente que admita servidores stdio locales, como Codex o Cursor.

Crea un entorno dedicado e instala el par Core/MCP correspondiente:

python3 --version
python3 -m venv ~/.local/share/fcop/venv
~/.local/share/fcop/venv/bin/python -m pip install --upgrade \
  "fcop>=4.0.3,<4.1.0" \
  "fcop-mcp>=4.0.3,<4.1.0"

Verifica la CLI y el catálogo MCP instalado:

~/.local/share/fcop/venv/bin/fcop version
~/.local/share/fcop/venv/bin/fcop doctor
~/.local/share/fcop/venv/bin/fcop tools --json

La CLI instalada proporciona los nueve comandos que se enumeran a continuación: init, status, inspect, validate, tools, doctor, version, spec y migrate. La configuración e inspección de la CLI no requieren un cliente de IA compatible con MCP.

Para MCP, configura el cliente con rutas absolutas de macOS; no uses ~ dentro de la configuración del cliente:

{
  "mcpServers": {
    "fcop": {
      "command": "/Users/YOUR_NAME/.local/share/fcop/venv/bin/python",
      "args": ["-m", "fcop_mcp"],
      "env": {
        "FCOP_PROJECT_DIR": "/Users/YOUR_NAME/path/to/your-project"
      }
    }
  }
}

Reemplaza YOUR_NAME y la ruta del proyecto, luego reinicia o reconecta el cliente MCP. FCOP_PROJECT_DIR apunta al proyecto que usará FCoP, no a este repositorio fuente.

Ver el resultado mínimo

El resultado visible no es solo un paquete instalado: el trabajo formal se convierte en archivos inspeccionables que otra sesión puede leer. El ejemplo de transferencia vinculado verifica ese resultado de extremo a extremo.

¿Por qué poner el trabajo fuera del modelo?

"He terminado" es una afirmación en una conversación. Un compañero de equipo aún necesita saber qué asignación se intentó, qué se entregó, quién la revisó y qué queda sin resolver. Mantener esos hechos solo en un chat hace que una transferencia dependa de reconstruir ese chat.

FCoP le da al trabajo formal una representación compartida: archivos Markdown con metadatos estructurados, identidades estables, relaciones explícitas y transiciones de estado registradas. Un agente puede escribirlos, un humano puede abrirlos y un script puede validarlos. La implementación de referencia basada en el sistema de archivos no necesita base de datos ni intermediario de mensajes.

La persistencia hace que una reclamación sea inspeccionable; no hace que la reclamación sea verdadera. FCoP verifica las relaciones y compuertas del protocolo. Los revisores evalúan la sustancia del trabajo entregado, y el Runtime del host proporciona ejecución, programación y permisos.

CLI — Configuración local, inspección y diagnóstico

CLI = Configuración + Observación + Diagnóstico; MCP = Trabajo.

Instalar y verificar

En un entorno Python 3.10+ activado:

python -m pip install fcop

fcop version
fcop doctor
fcop init --root ./my-project
fcop status --root ./my-project
fcop validate --root ./my-project

Para el catálogo de herramientas MCP opcional:

python -m pip install fcop-mcp

fcop tools
fcop tools merge_branches --json

Una vez instalado, la CLI puede inicializar, inspeccionar, validar y diagnosticar localmente y sin conexión. doctor no accede a la red ni modifica la configuración del Host. La instalación del paquete en sí puede necesitar un índice de paquetes; la instalación sin conexión requiere paquetes disponibles localmente. La CLI no realiza create_task, aprobación, Branch, fusión ni operaciones de trabajo de autorización; usa MCP o la API de Python para esas operaciones. Instalar fcop no crea archivos de instrucciones del Host. El estado normal del espacio de trabajo v4 pertenece a <project>/fcop/, nunca en la raíz del proyecto AGENTS.md, CLAUDE.md ni reglas de Cursor. Se preservan la preparación atómica de inicialización existente y la evidencia de inicialización fallida; los archivos del cliente nunca se limpian automáticamente. migrate es una operación heredada explícita separada, no un paso automático de actualización de paquetes. tools requiere el paquete MCP opcional y nunca inicia un servidor ni lo instala automáticamente.

Referencia CLI · 中文 CLI 参考.

python -m pip install "fcop==4.0.3"

from pathlib import Path
from tempfile import TemporaryDirectory

from fcop import Project

with TemporaryDirectory(prefix="fcop-demo-") as directory:
    root = Path(directory) / "workspace"
    project = Project(root)
    workspace = project.create_workspace(protocol_version="4.0")
    request = dict(
        workspace_id=workspace["workspace_id"],
        operation_id="demo-create-1",
        sender="ME", recipient="ME",
        subject="Inspect this handoff",
        body="Read the task and check the evidence before accepting delivery.",
    )
    first = project.create_task(**request)

    next_client = Project(root)
    state = next_client.inspect_state(task_id=first["task_id"])
    retry = next_client.create_task(**request)

    assert Path(state["path"]).is_file()
    assert retry["existing"] and retry["task_id"] == first["task_id"]
    print("State read from disk:", state["stage"])
    print("Same task after retry:", retry["task_id"] == first["task_id"])

State read from disk: inbox
Same task after retry: True

python -m pip install "fcop==4.0.3" "fcop-mcp==4.0.3"

{
  "mcpServers": {
    "fcop": {
      "command": "/absolute/path/to/.venv/bin/fcop-mcp",
      "env": {"FCOP_PROJECT_DIR": "/absolute/path/to/new-workspace"}
    }
  }
}

De una reclamación de entrega a un resultado aceptado

Cada TASK sigue un ciclo de vida ordenado. En 4.0, entrar en active inicia un nuevo intento, y el envío vincula el REPORT de ese intento. La aceptación luego vincula la revisión y la autorización a la evidencia actual.

active → done está ausente en 4.0. La reapertura a través de reopen_task crea un nuevo intento tanto para tareas ordinarias como para Branches. Un REPORT antiguo no puede satisfacer la compuerta de envío de un nuevo intento. Consulta el ciclo de vida completo y los contratos C1–C8 · 中文规范.

Trabajo paralelo, con una forma explícita de terminar

Múltiples flujos de trabajo ordenados pueden avanzar de forma concurrente. Un Branch es una TASK ordinaria vinculada a una Root por branch_of; los Branches hermanos mantienen sus propios intentos, informes y revisiones. Tu Runtime decide quién los ejecuta y cuándo.

Antes de que una Root con Branches pueda archivarse, FCoP verifica los Branches completados, sus REPORT actuales, un family_digest coincidente, una REVIEW de convergencia y autorización separada de archivado de Root. Un Branch reabierto o un REPORT cambiado invalida la convergencia obsoleta. Las escrituras relacionadas comparten un límite de confirmación corto; los agentes no mantienen ese bloqueo mientras hacen su trabajo. Esto cierra un conjunto de evidencia; la integración de código sigue siendo responsabilidad de la aplicación.

Un protocolo pequeño dentro de un sistema de agentes más grande

Otra implementación debería poder preservar las mismas semánticas de trabajo sin copiar una biblioteca de Python particular, una lista de herramientas MCP o un producto.

Lee la explicación del diseño: English · 简体中文. Desarrolla el razonamiento detrás de los archivos, la entrega y aceptación separadas, el trabajo paralelo y los límites entre FCoP, MCP y un Runtime.

Principios de arquitectura: cinco ensayos completos en chino, publicados el 10 de septiembre de 2026 y revisados contra 4.0:

1. Trabajo más allá del contexto del modelo: ¿por qué archivos?
2. Extrayendo el núcleo mínimo de FCoP
3. Separando Núcleo, Especificación, Toolkit, Perfil y Runtime
4. Trabajo paralelo mediante ciclos de vida de tareas ordenados
5. Cómo encajan FCoP, MCP, A2A y CodeFlowMu

Guía de la serie (中文) · Los cinco ensayos (中文)

4.0.3 distribuye nueve módulos de reglas bilingües a través de recursos propiedad del paquete y de MCP, con manifiestos estrictos y ensamblados sequential, parallel y repository-development separados. Instalar → conectar MCP → inicializar el espacio de trabajo → usar FCoP. FCoP posee <project>/fcop/, no los archivos de instrucciones del Host en la raíz del proyecto. La proyección del Host, la adopción, el despliegue y la reversión están retirados; redeploy_rules es solo para Legacy v1–v3 y rechaza v4 con cero escrituras. Los archivos de clientes existentes permanecen sin cambios. Recursos de reglas / 规则资源.

Documentos, evidencia y citación

Estos recursos son directamente accesibles; leer la colección de ensayos es opcional.

Elige el archivo que coincida con la versión que estudiaste. Los DOIs históricos anteriores no son identificadores para 4.0.0; usa la versión publicada y la especificación al discutir el comportamiento actual.

Tres repositorios, tres puntos de entrada

FCoP es usable de forma independiente bajo la licencia MIT. La distribución del producto tiene su propia licencia y calendario de versiones.

Marca FCoP con una estrella para guardar el protocolo y su implementación. Para ayudar a mejorarlo, comparte un problema de integración reproducible, un ejemplo de tu host o una prueba del comportamiento público del protocolo a través de Issues o una solicitud de extracción.

Versiones e instalaciones existentes

• 4.0.0: Notas de versión · Registro de cambios · Decisiones de arquitectura. La publicación siguió la puerta FCOP_4_STABLE_RELEASE_READY registrada; los usuarios instalan el par estable de PyPI mencionado arriba.
• Candidato de versión: 4.0.0rc1 — conservado como prelanzamiento histórico.
• Espacios de trabajo 3.x: conservan su semántica original hasta la migración explícita. Especificación heredada EN · ZH. finish_task y las herramientas de historial heredadas permanecen detectables pero rechazan espacios de trabajo v4.
• Indicaciones de instalación heredadas: EN · ZH, también disponibles en fcop://prompt/install. Estos son materiales de configuración históricos; usa la guía 4.0 anterior para la versión actual.