FCoP

FCoP — Protocolo de Coordenação Baseado em Arquivos

English · 简体中文

Mesmo quando o agente não está mais presente, o trabalho permanece.

Tarefas, entregas, problemas e decisões de revisão tornam-se arquivos duráveis que pessoas, ferramentas e o próximo agente podem inspecionar. Uma sessão pode terminar sem levar consigo o registro do trabalho.

Peça à IA para instalar · Referência manual · Série de arquitetura (中文) · Arquitetura · Artigos e citação

Versão estável: 4.0.3 — Lançamento 4.0.3. Este repositório contém o protocolo aberto, a implementação Python fcop e o adaptador opcional fcop-mcp. Python 3.10+; nenhuma chave de API de modelo é necessária para o exemplo local.

Peça à sua IA para instalar o FCoP

Cole isto no Cursor Agent, Codex ou outro agente de codificação com acesso a terminal e arquivos. O agente cuida da configuração e verifica o 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.

O guia de instalação com IA cobre dependências, configuração do cliente e uma verificação de tarefa real. Se o cliente precisar de aprovação ou recarga, o agente identificará essa etapa. Instruções manuais de Python/MCP permanecem abaixo para referência.

Quer ver uma transferência primeiro? Peça à IA para executar o exemplo de transferência de sessão: English · 简体中文. Crie uma tarefa e um relatório, feche a sessão e depois leia-os de uma nova sessão MCP. Nenhuma chave de API é necessária; o resultado permanece disponível para inspeção.

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

O FCoP suporta macOS tanto em Intel quanto em Apple silicon. Os wheels publicados são independentes de plataforma; Rosetta não é necessária. Use Python 3.10–3.13. A CLI funciona diretamente no Terminal, enquanto o MCP adicionalmente requer um cliente que suporte servidores stdio locais, como Codex ou Cursor.

Crie um ambiente dedicado e instale o par Core/MCP correspondente:

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"

Verifique a CLI e o 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

A CLI instalada fornece todos os nove comandos listados abaixo: init, status, inspect, validate, tools, doctor, version, spec e migrate. A configuração e inspeção da CLI não exigem um cliente de IA compatível com MCP.

Para MCP, configure o cliente com caminhos absolutos do macOS; não use ~ dentro da configuração do 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"
      }
    }
  }
}

Substitua YOUR_NAME e o caminho do projeto, depois reinicie ou reconecte o cliente MCP. FCOP_PROJECT_DIR aponta para o projeto que usará o FCoP, não para este repositório de origem.

Veja o resultado mínimo

O resultado visível não é apenas um pacote instalado: o trabalho formal torna-se arquivos inspecionáveis que outra sessão pode ler. O exemplo de transferência vinculado verifica esse resultado de ponta a ponta.

Por que colocar o trabalho fora do modelo?

“Eu terminei” é uma declaração em uma conversa. Um colega ainda precisa saber qual tarefa foi tentada, o que foi entregue, quem revisou e o que permanece sem solução. Manter esses fatos apenas em um chat faz com que uma transferência dependa da reconstrução desse chat.

O FCoP dá ao trabalho formal uma representação compartilhada: arquivos Markdown com metadados estruturados, identidades estáveis, relacionamentos explícitos e transições de estado registradas. Um agente pode escrevê-los, um humano pode abri-los e um script pode validá-los. A implementação de referência baseada em sistema de arquivos não precisa de banco de dados ou broker de mensagens.

A persistência torna uma reivindicação inspecionável; não torna a reivindicação verdadeira. O FCoP verifica relacionamentos e portões do protocolo. Revisores avaliam a substância do trabalho entregue, e o Runtime do host fornece execução, agendamento e permissões.

CLI — Configuração Local, Inspeção e Diagnóstico

CLI = Configuração + Observação + Diagnóstico; MCP = Trabalho.

Instalar e Verificar

Em um ambiente Python 3.10+ ativado:

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 o Catálogo de Ferramentas MCP opcional:

python -m pip install fcop-mcp

fcop tools
fcop tools merge_branches --json

Uma vez instalado, a CLI pode inicializar, inspecionar, validar e diagnosticar localmente e offline. doctor não acessa a rede nem modifica a configuração do Host. A instalação do pacote em si pode precisar de um índice de pacotes; a instalação offline requer pacotes disponíveis localmente. A CLI não executa operações de create_task, aprovação, Branch, merge ou autorização de trabalho; use MCP ou a API Python para essas operações. Instalar fcop não cria arquivos de instrução do Host. O estado normal do espaço de trabalho v4 pertence a <project>/fcop/, nunca em AGENTS.md, CLAUDE.md ou regras do Cursor na raiz do projeto. O staging de inicialização atômica existente e as evidências de inicialização com falha são preservados; arquivos do cliente nunca são limpos automaticamente. migrate é uma operação legada explícita separada, não uma etapa automática de atualização de pacote. tools requer o pacote MCP opcional e nunca inicia um servidor nem o instala automaticamente.

Referência da 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 uma reivindicação de entrega a um resultado aceito

Cada TASK segue um ciclo de vida ordenado. No 4.0, entrar em active inicia uma nova tentativa, e a submissão vincula o REPORT dessa tentativa. A aceitação então vincula a revisão e a autorização às evidências atuais.

active → done está ausente no 4.0. Reabrir através de reopen_task cria uma nova tentativa para tarefas comuns, bem como Branches. Um REPORT antigo não pode satisfazer o portão de submissão de uma nova tentativa. Veja o ciclo de vida completo e contratos C1–C8 · 中文规范.

Trabalho paralelo, com uma maneira explícita de terminar

Vários fluxos de trabalho ordenados podem avançar concorrentemente. Um Branch é uma TASK comum vinculada a uma Root por branch_of; Branches irmãos mantêm suas próprias tentativas, relatórios e revisões. Seu Runtime decide quem os executa e quando.

Antes que uma Root com Branches possa ser arquivada, o FCoP verifica Branches concluídos, seus REPORTs atuais, um family_digest correspondente, um REVIEW de convergência e autorização separada de arquivamento da Root. Um Branch reaberto ou REPORT alterado invalida a convergência obsoleta. Escritas relacionadas compartilham um curto limite de commit; os agentes não seguram esse bloqueio enquanto fazem seu trabalho. Isso fecha um conjunto de evidências; a integração de código permanece responsabilidade da aplicação.

Um pequeno protocolo dentro de um sistema de agente maior

Outra implementação deve ser capaz de preservar as mesmas semânticas de trabalho sem copiar uma biblioteca Python específica, lista de ferramentas MCP ou produto.

Leia a explicação do design: English · 简体中文. Ela desenvolve o raciocínio por trás de arquivos, entrega e aceitação separadas, trabalho paralelo e os limites entre FCoP, MCP e um Runtime.

Princípios de arquitetura: cinco ensaios completos em chinês, publicados em 10 de setembro de 2026 e revisados contra o 4.0:

1. Trabalho além do contexto do modelo: por que arquivos?
2. Extraindo o núcleo mínimo do FCoP
3. Separando Núcleo, Especificação, Kit de Ferramentas, Perfil e Runtime
4. Trabalho paralelo por meio de ciclos de vida de tarefas ordenados
5. Como FCoP, MCP, A2A e CodeFlowMu se encaixam

Guia da série (中文) · Todos os cinco ensaios (中文)

O 4.0.3 distribui nove módulos de regras bilíngues por meio de recursos do pacote e do MCP, com manifestos estritos e assemblies sequential, parallel e repository-development separados. Instale → conecte o MCP → inicialize o workspace → use o FCoP. O FCoP possui <project>/fcop/, não arquivos de instrução do Host na raiz do projeto. Projeção do Host, adoção, implantação e reversão foram descontinuadas; redeploy_rules é Legacy v1–v3 apenas e rejeita v4 com zero gravações. Os arquivos existentes dos clientes permanecem inalterados. Recursos de regras / 规则资源.

Artigos, evidências e citação

Esses recursos são diretamente acessíveis; a leitura da coleção de ensaios é opcional.

Escolha o arquivo correspondente à versão que você estudou. Os DOIs históricos acima não são identificadores para 4.0.0; use a versão e a especificação versionadas ao discutir o comportamento atual.

Três repositórios, três pontos de entrada

O FCoP é utilizável de forma independente sob a licença MIT. A distribuição do produto possui seu próprio licenciamento e cronograma de versões.

Marque o FCoP com estrela para salvar o protocolo e sua implementação. Para ajudar a melhorá-lo, compartilhe um problema de integração reproduzível, um exemplo do seu host ou um teste do comportamento público do protocolo por meio de Issues ou de um pull request.

Versões e instalações existentes

• 4.0.0: Notas de versão · Changelog · Decisões de arquitetura. A publicação seguiu o gate FCOP_4_STABLE_RELEASE_READY registrado; os usuários instalam o par estável do PyPI acima.
• Candidato a versão: 4.0.0rc1 — mantido como pré-lançamento histórico.
• Workspaces 3.x: mantêm sua semântica original até migração explícita. Especificação legada EN · ZH. finish_task e ferramentas de histórico legadas permanecem detectáveis, mas rejeitam workspaces v4.
• Prompts de instalação legados: EN · ZH, também disponíveis em fcop://prompt/install. Estes são materiais históricos de configuração; use o guia 4.0 acima para a versão atual.