Windsurf
Adaptador de harness do Apothem para o Windsurf (GA).
Fornecedor: Devin Desktop (antigo Codeium Windsurf)
Nome de instalação: windsurf
Status: GA
Configuração nativa: <project>/.devin/rules/apothem-rules.md
O Windsurf agora é o Devin Desktop, e .devin/rules/ é o local preferido para
as regras do workspace (ele tem precedência sobre .windsurf/rules/).
Instalação
apothem install --harness windsurf --project /path/to/projectO adaptador grava um arquivo de regras do Windsurf com escopo de projeto a partir da superfície compartilhada de regras e governança do Apothem, grava onze dos auxiliares do Apothem como subagentes do Devin Local no projeto (consulte Subagentes) e registra dois hooks do Devin Local (consulte Hooks).
Ele também grava as skills do Apothem, e as regras e templates que elas citam, no seu diretório pessoal, antes de tocar no projeto (consulte Arquivos fora do projeto).
Arquivos gravados:
<project>/.devin/rules/apothem-rules.md, o arquivo de regras.<project>/.devin/agents/<name>.mdpara onze auxiliares do Apothem, no projeto.<project>/.devin/config.local.json, o registro dos hooks, no projeto. Suas próprias entradas nele permanecem.<project>/.apothem/support/windsurf/hooks/, os scripts de hook, no projeto.~/.agents/skills/<name>/SKILL.mdpara cada skill e comando do Apothem, no seu diretório pessoal.~/.config/apothem/rules/e~/.config/apothem/templates/, no seu diretório pessoal.
Arquivos fora do projeto
A instalação também grava as skills do Apothem no seu diretório pessoal, antes de alterar qualquer coisa no projeto:
| Pasta | O que o Apothem grava ali |
|---|---|
~/.agents/skills/ | Uma pasta com um SKILL.md para cada skill do Apothem, e uma para cada comando do Apothem (um comando se torna uma skill de mesmo nome). |
~/.config/apothem/rules/, ~/.config/apothem/templates/ | As regras e os templates aos quais as skills e o arquivo de regras se referem. |
Essas pastas são compartilhadas. Elas não são privadas do projeto:
- Todo projeto em que você instala
windsurf, e toda outra instalação do Apothem que nomeia a pasta, usa a mesma cópia e grava os mesmos arquivos, então a ordem em que você instala não importa. Várias outras ferramentas também leem~/.agents/skills/; o registro de harnesses as lista. --projectescolhe o arquivo de regras a gravar e a qual projeto a instalação pertence. Ele não muda para onde vão as skills.- A instalação não adiciona nenhum arquivo de skill ou de regra ao seu repositório. O projeto
recebe o arquivo de regras, os arquivos de subagente em
.devin/agents/, o registro dos hooks em.devin/config.local.json, além da pasta.apothem/que toda instalação de projeto cria, que também guarda os scripts de hook. - As pastas do diretório pessoal são gravadas primeiro. Se isso falhar, por exemplo porque uma pasta no caminho é um link que sai do seu diretório pessoal (um link que permanece dentro dele é seguido) ou não pode ser gravada, a instalação para com o erro antes que qualquer coisa no projeto mude.
- Uma pasta de skill com o nome de uma skill do Apothem que o Apothem não gravou é
deixada intacta, e a instalação exibe um aviso que a nomeia. Renomeie-a ou mova-a
e depois execute
apothem update.apothem verifyfalha enquanto esse nome estiver ocupado. - Os arquivos somam alguns megabytes.
A instalação exibe uma nota que nomeia as pastas que ela grava fora de --project,
e --dry-run as lista.
Subagentes
O Devin Local, no qual as novas abas do Devin Desktop começam, lê um subagente de um
arquivo Markdown em <project>/.devin/agents/, conforme a
documentação de subagentes do Devin. O Cascade,
o modo mais antigo, não tem subagentes. A instalação grava onze dos
catorze auxiliares do Apothem nessa pasta. Ela instala apenas para o projeto e não grava
nenhuma pasta de subagentes de nível de usuário (~/.config/devin/agents/ no Linux e no macOS,
%APPDATA%\devin\agents\ no Windows).
Cada arquivo mantém as instruções do auxiliar inalteradas e traz estas chaves de frontmatter:
| Chave | O que o Apothem grava |
|---|---|
name, description | O nome e a descrição do auxiliar. |
allowed-tools | As ferramentas que o auxiliar pode usar, como uma lista de nomes de ferramentas do Devin: read, edit, grep, glob, exec (o Bash do auxiliar) e write. |
O Devin não tem nenhuma chave que negue uma ferramenta, então as ferramentas permitidas ao
auxiliar, menos as negadas, tornam-se a única lista allowed-tools. O Bash do auxiliar é
exec no Devin, e uma ferramenta para a qual o Devin não tem nome listado fica de fora. Os
auxiliares somente leitura recebem read, glob e grep, mais exec para os que executam
comandos, e nunca write nem edit.
Três auxiliares não são instalados: citation-auditor, fact-checker e
research-scout. Eles precisam de busca na web e de busca de páginas na web, e o Devin não
documenta nenhum nome de allowed-tools para nenhuma das duas, então a instalação os retém em
vez de gravar uma versão que não consegue pesquisar ou uma que tem todas as ferramentas. Um
arquivo seu em .devin/agents/ com um desses nomes nunca é tocado.
A instalação não grava nenhuma chave model. O Devin executa um subagente no seu próprio
modelo padrão de subagentes, que não é o modelo da sessão que o iniciou. Ela também
não grava max-nesting nem nenhuma das chaves maxTurns, version, updated e
portability do Apothem.
Pontos a saber:
- Os subagentes personalizados são experimentais. O Devin indica que o formato e as opções
estão sujeitos a mudanças, e o Devin Desktop tem uma opção Subagents (Preview) em Devin Settings
(a configuração
subagents_enabledda Devin CLI vem ativada por padrão). - Os arquivos de subagente são arquivos comuns do projeto. Faça commit deles com o projeto ou
liste
.devin/agents/no.gitignore; o Apothem não escolhe por você. - Um arquivo seu com o nome de um auxiliar do Apothem é salvo em
~/.apothem/backups/e depois substituído. A desinstalação não o restaura. Arquivos com outros nomes nunca são tocados. - O Devin também lê a pasta compartilhada
.agents/agents/, que o Apothem nunca grava, e a Devin CLI documenta uma importação de subagentes de uma pasta.claude/sem nomear o caminho. O Devin Local encontra seus arquivos do mesmo jeito que a Devin CLI, então essa importação também se aplica lá. - O Apothem não confirmou os nomes de
allowed-toolspara as ferramentas web, quais valoresmodelaceita, nem como uma listaallowed-toolsvazia é lida.
Hooks
O Devin Local executa hooks a partir da chave hooks dos seus arquivos de configuração, conforme a
documentação de hooks do Devin.
A instalação registra dois:
| Evento | O que é executado |
|---|---|
SessionStart | O bootstrap da sessão: metadados da sessão, o índice de skills, os resumos de memória e de plano e a postura permanente, adicionados ao contexto do modelo. |
PostToolUse (todas as ferramentas) | O rastreador de compactação proativa. Ele conta a atividade e, no máximo duas vezes por ciclo de compactação, diz ao modelo para salvar seu estado ou compactar. Caso contrário, fica em silêncio. |
Ambos adicionam contexto para o modelo. Nenhum deles bloqueia uma chamada de ferramenta ou uma sessão.
O Apothem não registra nenhuma proteção PreToolUse no Devin. A documentação do Devin lista
additionalContext (o campo pelo qual as proteções do Apothem se comunicam) para
UserPromptSubmit, SessionStart e PostToolUse, e lista apenas uma decisão e
uma reescrita da entrada para PreToolUse. Uma proteção registrada ali custaria o início de um
processo a cada chamada de ferramenta e talvez não entregasse nada, então as proteções de gravação,
edição e shell, a verificação de AskUserQuestion e o protocolo de fim de sessão permanecem nas
ferramentas que os entregam. O Apothem registrará uma proteção em um evento do Devin assim que a
documentação, ou uma sondagem, mostrar que ela chega ao modelo.
Estes são hooks do Devin Local. O modo Cascade, mais antigo, lê um formato de hook diferente
(.devin/hooks.json), que a instalação não grava.
Para onde vão os arquivos
| Arquivo | O que ele contém |
|---|---|
<project>/.devin/config.local.json | Os dois registros de hook, mesclados na chave hooks do arquivo. O Devin documenta este arquivo como a substituição local e ignorado pelo git, e exclui ele mesmo os arquivos de configuração locais do git por meio de .git/info/exclude. |
<project>/.apothem/support/windsurf/hooks/ | O script despachante, seus auxiliares e seus arquivos de mensagem. |
Cada comando registrado nomeia o interpretador que o Apothem encontrou quando foi executado e o
caminho absoluto do projeto, então ele é específico da máquina. É por isso que a instalação
grava o arquivo local e nunca o <project>/.devin/config.json compartilhado, o
.devin/hooks.v1.json independente nem as configurações de .claude/. A instalação não
edita o .gitignore. O Devin exclui ele mesmo seus arquivos de configuração locais do git (por meio de
.git/info/exclude), então o checkout de um colega de equipe não recebe comandos que
apontam para a sua máquina; verifique se o seu .gitignore lista .apothem/.
Caminhos que o shell leria errado. Um caminho de projeto ou de interpretador que contém
$, um acento grave, aspas duplas ou uma barra invertida é recusado antes que qualquer coisa seja
gravada: dentro do comando entre aspas ele executaria um arquivo diferente, ou quebraria o
JSON no qual o comando é gravado. O erro nomeia o caminho; mova ou renomeie o
projeto e execute a instalação novamente. Um espaço ou um apóstrofo em um caminho não causa problema.
Um comando tem esta aparência, com o seu interpretador e o caminho do seu projeto no lugar dos dois caminhos:
"/path/to/python" "/path/to/project/.apothem/support/windsurf/hooks/dispatch.py" --contract devin SessionStart--contract devin mapeia os nomes de ferramentas em minúsculas do Devin (exec, write, edit,
read, grep, glob) para os nomes que os manipuladores do Apothem testam, e deixa a
saída como o mesmo envelope que o Claude Code lê. Nenhum matcher é gravado: o matcher do Devin
é uma expressão regular, um matcher omitido corresponde a todas as ferramentas, e
SessionStart não tem ferramenta a corresponder.
Pontos a verificar após a instalação
- O Devin não executa nenhum hook enquanto o workspace está no Restricted Mode. Confie no workspace primeiro.
- Para ver se os hooks foram carregados, abra a aba Hooks em Customizations do Devin Local,
ou execute
/hooksna Devin CLI. Ambos listam cada hook com seu arquivo de origem. - A documentação do Devin não nomeia nenhum shell para os comandos de hook no Windows. Os comandos
usam a citação do
sh, que o PowerShell não analisaria sem um operador de chamada. O Apothem não confirmou o que o Devin Local executa no Windows; se os hooks não carregarem ali, informe isso em uma issue.
O Devin também executa os hooks que o Claude Code gravou. O Devin carrega os hooks em
~/.claude/settings.json, .claude/settings.json e
.claude/settings.local.json enquanto read_config_from.claude está ativado, que é o seu
padrão: o Devin Local encontra seus arquivos do mesmo jeito que a Devin CLI.
Se você também instalou o Apothem para o Claude Code, ambos os conjuntos de hooks podem
ser executados. O comando SessionStart aqui e a cópia dele do Claude Code compartilham um
marcador por sessão na pasta de estado dos hooks do Apothem, então o que for executado em segundo lugar fica
em silêncio e o bootstrap chega ao modelo uma vez; o Apothem identifica o Devin pela
variável DEVIN_PROJECT_DIR que o Devin define para seus hooks. O marcador cobre dez
segundos, então um início posterior da mesma sessão ainda entrega. O contador de tamanho de
contexto é executado nos dois lugares, então seus limites são atingidos mais cedo, e o Apothem
não desduplica os contadores. Para carregar apenas estes hooks, defina
"claude": false sob "read_config_from" na sua configuração de usuário
(~/.config/devin/config.json, ou %APPDATA%\devin\config.json no Windows) ou no
.devin/config.json do projeto; isso também impede que o Devin importe as
regras, skills, comandos e servidores MCP do Claude Code. A instalação exibe isso como uma nota.
Seus próprios hooks. O registro é mesclado no seu arquivo por chave. Os hooks e as
outras chaves que você gravou permanecem como estavam, um manipulador seu sob o mesmo evento
permanece ao lado do do Apothem, e uma atualização substitui apenas os manipuladores cujo comando executa
o despachante do Apothem (.apothem/support/windsurf/hooks/dispatch.py com
--contract devin, seja qual for o caminho de projeto sob o qual foi gravado). Um hook seu
que apenas compartilha o nome, ou que executa python -m apothem.conformity.gate, nunca é
tomado pelo do Apothem. Um arquivo com comentários ou outra sintaxe JSON5
não pode ser regravado sem perdê-los, então a instalação informa um erro
config.unparseable para esse arquivo, deixa-o intacto e para, com os
outros arquivos que havia começado a gravar removidos novamente: remova os comentários ou adicione
você mesmo as duas entradas.
Desativando os hooks. Defina APOTHEM_HOOKS_DISABLE=1 no ambiente do Devin para
silenciar os hooks do Apothem.
Mapeamento do perfil para a configuração nativa
O adaptador lê o perfil compartilhado do Apothem e renderiza o arquivo de regras
do projeto a cada execução de apothem install ou apothem update. O perfil
compartilhado é a fonte da verdade; as edições locais do projeto no arquivo
gerado recebem backup antes que a próxima sincronização substitua o conteúdo
gerenciado pelo Apothem.
O arquivo começa com seu frontmatter trigger: always_on, que define o modo de
ativação da regra. O bloco gerenciado pelo Apothem vem em seguida; o texto que
você adiciona depois do bloco é mantido a cada sincronização.
Notas de compatibilidade
A superfície de regras atual do Windsurf tem escopo de projeto sob
.devin/rules/ (o local preferido, que tem precedência sobre a alternativa de
compatibilidade retroativa .windsurf/rules/). Os fluxos de trabalho e as
memórias locais da máquina pertencem ao operador; o Apothem não os grava, nem o
arquivo de hooks do Cascade nem a configuração compartilhada do Devin. A
forma de arquivo único .windsurfrules intencionalmente não é gravada.
O Devin Desktop (Windsurf) descobre ~/.agents/skills/, então as skills que a
instalação grava aparecem sem configuração adicional. Sua importação do Claude Code,
ativada por padrão, lê skills apenas da pasta .claude/skills/ do projeto, então não está
documentado que as skills que uma instalação do Apothem para o Claude Code grava em
~/.claude/skills/ apareçam lá também. O Apothem não confirmou como o
Windsurf trata uma chave de cabeçalho de SKILL.md que ele não lista; as skills trazem
user-invocable, disable-model-invocation, allowed-tools, argument-hint
e um mapa metadata.
Verificação
apothem verify --harness windsurf --project /path/to/projectO comando verify confirma que:
- A configuração nativa existe no caminho esperado.
- Cada destino gerenciado existe, incluindo a pasta
.devin/agents/e o registro dos hooks.devin/config.local.json; os arquivos gerenciados não estão vazios, e as configurações JSON ou YAML podem ser analisadas. O arquivo de hooks deve conter um manipulador que executa o despachante do Apothem (a verificação não o executa), então um arquivo que foi revertido ou esvaziado deixa de ser verificado. Adicione--profile PATHpara também confirmar que os arquivos instalados correspondem a esse perfil. Para.devin/agents/a verificação é que a pasta existe, não que cada arquivo de auxiliar esteja nela; o comandoapothem diff --harness windsurf --project /path/to/projectlista os arquivos de auxiliar que estão ausentes ou desatualizados. - Toda pasta de skill do Apothem está no lugar com um
SKILL.md, seja qual for a instalação que a gravou, e nenhuma pasta de skill com um nome do Apothem pertence a algo que o Apothem não gravou. Uma verificação com falha nomeia as pastas ausentes ou alheias. - A rotina de verificação específica do adaptador informa sucesso.
Atualização
apothem update --harness windsurf --project /path/to/projectDeriva novamente o arquivo de regras do projeto a partir do estado atual do perfil compartilhado.
A atualização também regrava qualquer pasta de skill cujos arquivos difiram dos atuais.
Se você instalou com uma versão anterior que não gravava skills, a atualização as adiciona.
Ela regrava os arquivos de subagente que diferem dos atuais e adiciona os que estiverem ausentes.
Ela também atualiza os scripts de hook e os manipuladores do Apothem em
.devin/config.local.json, deixando suas próprias entradas intactas.
Desinstalação
apothem uninstall --harness windsurf --project /path/to/projectRemove o bloco do Apothem, e o frontmatter que o Apothem gravou acima dele, de
<project>/.devin/rules/apothem-rules.md e mantém qualquer outro texto nele. O
arquivo é excluído somente quando nada mais resta nele. Antes da alteração, uma
cópia do arquivo com carimbo de data e hora é salva em ~/.apothem/backups/;
nenhum arquivo de backup é deixado no projeto. O YAML do perfil compartilhado e
o motor do Apothem não são afetados.
A desinstalação também remove os arquivos de subagente que gravou em <project>/.devin/agents/
e mantém qualquer outro arquivo ali; a pasta é removida quando fica vazia.
Ela remove os manipuladores de hook do Apothem de <project>/.devin/config.local.json,
reconhecendo-os pelo caminho do despachante no seu comando, e mantém seus próprios hooks
e chaves. O arquivo é excluído somente quando o Apothem o criou e nada mais resta
nele. Os scripts de hook em <project>/.apothem/support/windsurf/hooks/ também são removidos.
Ela remove as pastas de skill que gravou em ~/.agents/skills/ e as
regras e templates em ~/.config/apothem/, mas somente quando nenhuma outra instalação do
Apothem ainda as usa. Outro projeto, ou outra ferramenta que compartilha a
pasta, pode usá-las. Nesse caso a desinstalação mantém as pastas, exibe qual instalação
as usa, e a última desinstalação as remove. Os arquivos que você adicionou a essas
pastas permanecem, e uma pasta que fica vazia é removida. Cada
pasta recebe backup em ~/.apothem/backups/ antes de ser removida.
Conformity gate
python -m apothem.conformity.gate --all .Solução de problemas
| Sintoma | Correção |
|---|---|
| Arquivo de configuração não encontrado | Execute novamente apothem install --harness windsurf --project /path/to/project |
| Falha na verificação | Execute apothem update --harness windsurf --project /path/to/project e depois verifique novamente |
| O Devin Local não lista nenhum dos auxiliares do Apothem | Execute apothem diff --harness windsurf --project /path/to/project. Uma linha pendente para a pasta .devin/agents significa que há arquivos de auxiliar ausentes ou desatualizados, então execute apothem update --harness windsurf --project /path/to/project. apothem verify não testa isso: ele passa quando .devin/agents/ existe, mesmo sem nenhum arquivo de auxiliar nela. Se o diff não informar nenhuma alteração pendente, verifique se a configuração Subagents (Preview) está ativada e se o projeto está aberto no modo Local do Devin Desktop e depois inicie uma nova aba |
| Os hooks do Apothem não são executados | O Devin não executa nenhum hook em um workspace no Restricted Mode: confie no workspace. Abra a aba Hooks em Customizations do Devin Local, ou execute /hooks na Devin CLI, para ver se as entradas do Apothem foram carregadas. No Windows, o Apothem não confirmou em qual shell o Devin executa os comandos de hook |
Uma instalação informa config.unparseable para config.local.json | O arquivo tem comentários ou outra sintaxe que uma regravação perderia. Remova os comentários e instale novamente, ou adicione você mesmo as duas entradas de hook do Apothem |
| O contexto do Apothem aparece duas vezes, ou o lembrete de tamanho de contexto chega cedo | O Devin também executa os hooks que a instalação do Claude Code gravou. Defina "claude": false sob "read_config_from" na sua configuração do Devin para carregar apenas os hooks em .devin/config.local.json |
apothem verify nomeia uma pasta de skill ausente | Execute apothem install --harness windsurf --project /path/to/project; ele restaura a pasta |
| Uma instalação ou atualização avisa que ignorou uma pasta de skill | Uma pasta com o nome de uma skill do Apothem já existe na pasta de skills e o Apothem não a gravou. Renomeie-a ou mova-a e depois execute apothem update |
| Uma instalação para antes de alterar o projeto | Uma gravação no seu diretório pessoal falhou. Leia o erro, corrija a pasta que ele nomeia (um link que sai do seu diretório pessoal, um arquivo onde deveria haver uma pasta ou uma pasta somente leitura) e instale novamente |
| Conteúdo de configuração inesperado | Verifique ~/.config/apothem/profile.yaml ou --profile PATH e depois execute novamente apothem update --harness windsurf --project /path/to/project |
Ajustes de configuração
| Sinalizador | Padrão | Descrição |
|---|---|---|
--dry-run | false | Pré-visualiza a instalação sem gravar arquivos. |
Veja também
- Todos os harnesses — o catálogo completo de ferramentas suportadas
- Guia de instalação — instale o Apothem neste harness
- Referência de
apothem harnesses— liste e inspecione adaptadores pela CLI