Windsurf

Поставщик: Devin Desktop (ранее Codeium Windsurf) Имя установки: windsurf Статус: GA Нативная конфигурация: <project>/.devin/rules/apothem-rules.md

Windsurf теперь называется Devin Desktop, и .devin/rules/ — предпочтительное расположение правил рабочей области (оно имеет приоритет над .windsurf/rules/).

УстановкаCopy Anchor Link

apothem install --harness windsurf --project /path/to/project

Адаптер записывает один файл правил Windsurf с областью действия проекта на основе общих правил Apothem и поверхности управления, записывает одиннадцать помощников Apothem как субагентов Devin Local в проекте (см. Субагенты) и регистрирует два хука Devin Local (см. Хуки).

Кроме того, он записывает навыки Apothem, а также правила и шаблоны, на которые они ссылаются, в ваш домашний каталог пользователя, прежде чем затронуть проект (см. Файлы за пределами проекта).

Записываемые файлы:

• <project>/.devin/rules/apothem-rules.md — файл правил.
• <project>/.devin/agents/<name>.md для одиннадцати помощников Apothem, в проекте.
• <project>/.devin/config.local.json — регистрация хуков, в проекте. Ваши собственные записи в нём сохраняются.
• <project>/.apothem/support/windsurf/hooks/ — скрипты хуков, в проекте.
• ~/.agents/skills/<name>/SKILL.md для каждого навыка и каждой команды Apothem, в вашем домашнем каталоге пользователя.
• ~/.config/apothem/rules/ и ~/.config/apothem/templates/, в вашем домашнем каталоге пользователя.

Файлы за пределами проектаCopy Anchor Link

Установка также записывает навыки Apothem в ваш домашний каталог пользователя, прежде чем что-либо изменить в проекте:

Эти папки являются общими. Они не принадлежат исключительно проекту:

• Каждый проект, в который вы устанавливаете windsurf, и каждая другая установка Apothem, указывающая эту папку, используют одну и ту же копию и записывают одни и те же файлы, поэтому порядок установки не имеет значения. ~/.agents/skills/ читают и несколько других инструментов; они перечислены в реестре окружений.
• --project выбирает, какой файл правил записать и к какому проекту относится установка. Он не меняет место, куда попадают навыки.
• Установка не добавляет в ваш репозиторий ни одного файла навыка или правила. Проект получает файл правил, файлы субагентов в .devin/agents/, регистрацию хуков в .devin/config.local.json, а также папку .apothem/, которую создаёт каждая установка в проект и в которой также лежат скрипты хуков.
• Папки в домашнем каталоге записываются первыми. Если это не удаётся, например потому что папка на пути является ссылкой, ведущей за пределы вашего домашнего каталога (ссылка, остающаяся внутри него, разрешается), или в неё нельзя записать, установка останавливается с ошибкой до того, как в проекте что-либо изменится.
• Папка навыка с именем навыка Apothem, которую Apothem не записывал, остаётся нетронутой, а установка выводит предупреждение с её именем. Переименуйте или переместите её, затем запустите apothem update. apothem verify завершается неудачей, пока это имя занято.
• В сумме файлы занимают несколько мегабайт.

Установка выводит примечание с названиями папок, которые она записывает за пределами --project, а --dry-run их перечисляет.

СубагентыCopy Anchor Link

Devin Local, в котором запускаются новые вкладки Devin Desktop, читает субагента из файла Markdown в <project>/.devin/agents/ согласно документации Devin по субагентам. В Cascade, более старом режиме, субагентов нет. Установка записывает в эту папку одиннадцать из четырнадцати помощников Apothem. Она выполняет установку только для проекта и не записывает папку субагентов уровня пользователя (~/.config/devin/agents/ в Linux и macOS, %APPDATA%\devin\agents\ в Windows).

Каждый файл сохраняет инструкции помощника без изменений и содержит следующие ключи фронтматтера:

В Devin нет ключа, запрещающего инструмент, поэтому разрешённые инструменты помощника за вычетом запрещённых образуют единый список allowed-tools. Bash помощника в Devin называется exec, а инструмент, для которого в Devin нет указанного имени, опускается. Помощники только для чтения получают read, glob и grep, а те, что выполняют команды, — ещё и exec, но никогда write или edit.

Три помощника не устанавливаются: citation-auditor, fact-checker и research-scout. Им нужны веб-поиск и веб-загрузка, а Devin не документирует имя allowed-tools ни для одного из них, поэтому установка не записывает их, вместо того чтобы записать версию, которая не может проводить исследования, или версию со всеми инструментами. Ваш файл в .devin/agents/ с одним из этих имён никогда не затрагивается.

Установка не записывает ключ model. Devin запускает субагента на собственной модели субагентов по умолчанию, а не на модели сессии, которая его запустила. Также не записываются max-nesting и ключи Apothem maxTurns, version, updated и portability.

Что нужно знать:

• Пользовательские субагенты экспериментальны. Devin помечает формат и параметры как подлежащие изменению, а в Devin Desktop есть переключатель Subagents (Preview) в Devin Settings (настройка Devin CLI subagents_enabled включена по умолчанию).
• Файлы субагентов — обычные файлы проекта. Зафиксируйте их вместе с проектом или укажите .devin/agents/ в .gitignore; Apothem не делает этот выбор за вас.
• Ваш файл с именем помощника Apothem сохраняется в ~/.apothem/backups/, а затем заменяется. Удаление не возвращает его на место. Файлы с другими именами никогда не затрагиваются.
• Devin также читает общую папку .agents/agents/, в которую Apothem никогда не записывает, а Devin CLI документирует импорт субагентов из папки .claude/, не называя путь. Devin Local находит свои файлы так же, как Devin CLI, поэтому этот импорт действует и там.
• Apothem не подтвердил имена allowed-tools для веб-инструментов, какие значения принимает model и как читается пустой список allowed-tools.

ХукиCopy Anchor Link

Devin Local запускает хуки из ключа hooks своих файлов конфигурации согласно документации Devin по хукам. Установка регистрирует два:

Оба добавляют контекст для модели. Ни один не блокирует вызов инструмента или сессию.

Apothem не регистрирует защиту PreToolUse в Devin. Документация Devin указывает additionalContext (поле, через которое говорят защиты Apothem) для UserPromptSubmit, SessionStart и PostToolUse, а для PreToolUse — только решение и перезапись входных данных. Защита, зарегистрированная там, стоила бы запуска процесса при каждом вызове инструмента и могла бы ничего не доставить, поэтому защиты записи, редактирования и оболочки, проверка AskUserQuestion и протокол завершения сессии остаются в инструментах, которые их доставляют. Apothem зарегистрирует защиту на событии Devin, как только документация или проба покажет, что она доходит до модели.

Это хуки Devin Local. Более старый режим Cascade читает другой формат хуков (.devin/hooks.json), который установка не записывает.

Куда попадают файлы

Каждая зарегистрированная команда называет интерпретатор, который Apothem нашёл при запуске, и абсолютный путь проекта, поэтому она привязана к машине. Именно поэтому установка записывает локальный файл и никогда не записывает общий <project>/.devin/config.json, отдельный .devin/hooks.v1.json или настройки .claude/. Установка не редактирует .gitignore. Devin сам исключает свои локальные файлы конфигурации из git (через .git/info/exclude), поэтому checkout коллеги не получает команды, указывающие на вашу машину; проверьте, что ваш .gitignore перечисляет .apothem/.

Пути, которые оболочка прочитала бы неверно. Путь проекта или интерпретатора, содержащий $, обратную кавычку, двойную кавычку или обратную косую черту, отклоняется до того, как что-либо записано: внутри команды в кавычках он запустил бы другой файл или сломал бы JSON, в который записана команда. Ошибка называет путь; переместите или переименуйте проект и запустите установку снова. Пробел или апостроф в пути допустимы.

Команда выглядит так, с вашим интерпретатором и путём проекта на месте двух путей:

"/path/to/python" "/path/to/project/.apothem/support/windsurf/hooks/dispatch.py" --contract devin SessionStart

--contract devin сопоставляет имена инструментов Devin в нижнем регистре (exec, write, edit, read, grep, glob) с именами, которые проверяют обработчики Apothem, и оставляет вывод в том же конверте, который читает Claude Code. Сопоставитель не записывается: сопоставитель Devin — регулярное выражение, опущенный сопоставитель соответствует каждому инструменту, а у SessionStart нет инструмента для сопоставления.

Что проверить после установки

• Devin не запускает ни одного хука, пока рабочая область находится в Restricted Mode. Сначала отметьте рабочую область как доверенную.
• Чтобы увидеть, загрузились ли хуки, откройте вкладку Hooks в Customizations Devin Local или выполните /hooks в Devin CLI. Оба перечисляют каждый хук с его исходным файлом.
• Документация Devin не называет оболочку для команд хуков в Windows. Команды используют экранирование sh, которое PowerShell не разобрал бы без оператора вызова. Apothem не подтвердил, что именно Devin Local запускает в Windows; если хуки там не загружаются, сообщите об этом в issue.

Devin также запускает хуки, записанные для Claude Code. Devin загружает хуки из ~/.claude/settings.json, .claude/settings.json и .claude/settings.local.json, пока включено read_config_from.claude, что является значением по умолчанию: Devin Local находит свои файлы так же, как Devin CLI. Если вы также установили Apothem для Claude Code, могут запускаться оба набора хуков. Команда SessionStart здесь и её копия для Claude Code разделяют один маркер на сессию в папке состояния хуков Apothem, поэтому та, что запускается второй, молчит, и начальная загрузка доходит до модели один раз; Apothem распознаёт Devin по переменной DEVIN_PROJECT_DIR, которую Devin задаёт для своих хуков. Маркер действует десять секунд, поэтому более поздний запуск той же сессии всё равно доставляет контекст. Счётчик размера контекста работает в обоих местах, поэтому его пороги достигаются раньше, и Apothem не устраняет дублирование счётчиков. Чтобы загружать только эти хуки, задайте "claude": false в "read_config_from" в вашей пользовательской конфигурации (~/.config/devin/config.json или %APPDATA%\devin\config.json в Windows) или в .devin/config.json проекта; это также останавливает импорт Devin правил, навыков, команд и MCP-серверов Claude Code. Установка выводит это как примечание.

Ваши собственные хуки. Регистрация объединяется с вашим файлом по ключам. Хуки и другие ключи, которые вы записали, остаются как были, ваш обработчик на том же событии остаётся рядом с обработчиком Apothem, а обновление заменяет только обработчики, команда которых запускает диспетчер Apothem (.apothem/support/windsurf/hooks/dispatch.py с --contract devin, под каким бы путём проекта он ни был записан). Ваш хук, который лишь совпадает по имени или запускает python -m apothem.conformity.gate, никогда не принимается за хук Apothem. Файл с комментариями или другим синтаксисом JSON5 невозможно перезаписать, не потеряв их, поэтому установка сообщает об ошибке config.unparseable для этого файла, оставляет его нетронутым и останавливается, снова удалив другие файлы, которые начала записывать: удалите комментарии или добавьте две записи самостоятельно.

Отключение хуков. Задайте APOTHEM_HOOKS_DISABLE=1 в окружении Devin, чтобы заглушить хуки Apothem.

Сопоставление профиля с нативной конфигурациейCopy Anchor Link

Адаптер читает общий профиль Apothem и рендерит файл правил проекта при каждом запуске apothem install или apothem update. Общий профиль является источником истины; для локальных правок сгенерированного файла в проекте создаётся резервная копия, прежде чем следующая синхронизация заменит содержимое, управляемое Apothem.

Файл начинается с фронтматтера trigger: always_on, который задаёт режим активации правила. За ним следует управляемый Apothem блок; текст, который вы добавляете после блока, сохраняется при каждой синхронизации.

Заметки о совместимостиCopy Anchor Link

Текущая поверхность правил Windsurf имеет область действия проекта и находится в .devin/rules/ (предпочтительное расположение, которое имеет приоритет над резервным расположением .windsurf/rules/, сохранённым для обратной совместимости). Рабочие процессы и локальные для машины записи памяти принадлежат оператору; Apothem их не записывает, как и файл хуков Cascade и общую конфигурацию Devin. Однофайловая форма .windsurfrules намеренно не записывается.

Devin Desktop (Windsurf) обнаруживает ~/.agents/skills/, поэтому навыки, которые записывает установка, появляются без дополнительной настройки. Его импорт из Claude Code, включённый по умолчанию, читает навыки только из папки .claude/skills/ проекта, поэтому не задокументировано, что навыки, которые установка Apothem для Claude Code записывает в ~/.claude/skills/, появляются и там. Apothem не подтвердил, как Windsurf обрабатывает ключ заголовка SKILL.md, который в документации не указан; навыки содержат user-invocable, disable-model-invocation, allowed-tools, argument-hint и карту metadata.

ПроверкаCopy Anchor Link

apothem verify --harness windsurf --project /path/to/project

Команда verify подтверждает, что:

1. Нативная конфигурация существует по ожидаемому пути.
2. Каждая управляемая цель существует, включая папку .devin/agents/ и регистрацию хуков .devin/config.local.json; управляемые файлы не пусты, а конфигурации JSON или YAML разбираются. Файл хуков должен содержать обработчик, запускающий диспетчер Apothem (проверка его не запускает), поэтому файл, который был откачен или опустошён, больше не проходит проверку. Добавьте --profile PATH, чтобы дополнительно подтвердить, что установленные файлы соответствуют этому профилю. Для .devin/agents/ проверяется, что папка существует, а не что в ней есть файл каждого помощника; команда apothem diff --harness windsurf --project /path/to/project перечисляет файлы помощников, которые отсутствуют или устарели.
3. Каждая папка навыка Apothem на месте и содержит SKILL.md, какая бы установка её ни записала, и ни одна папка навыка с именем Apothem не принадлежит тому, что Apothem не записывал. Неудачная проверка называет отсутствующие или чужие папки.
4. Процедура проверки, специфичная для адаптера, сообщает об успехе.

ОбновлениеCopy Anchor Link

apothem update --harness windsurf --project /path/to/project

Повторно выводит файл правил проекта из текущего состояния общего профиля.

Обновление также перезаписывает каждую папку навыка, файлы которой отличаются от текущих. Если вы устанавливали более ранним выпуском, который не записывал навыки, обновление их добавляет. Оно перезаписывает файлы субагентов, которые отличаются от текущих, и добавляет отсутствующие. Оно также обновляет скрипты хуков и обработчики Apothem в .devin/config.local.json, не затрагивая ваши собственные записи.

УдалениеCopy Anchor Link

apothem uninstall --harness windsurf --project /path/to/project

Удаляет блок Apothem и фронтматтер, который Apothem записал над ним, из <project>/.devin/rules/apothem-rules.md и сохраняет любой другой текст в нём. Файл удаляется только тогда, когда в нём не остаётся ничего другого. Перед изменением копия файла с временной меткой сохраняется в ~/.apothem/backups/; в проекте резервный файл не остаётся. YAML общего профиля и движок Apothem не затрагиваются.

Удаление также удаляет файлы субагентов, которые оно записало в <project>/.devin/agents/, и сохраняет любой другой файл там; папка удаляется, если остаётся пустой. Оно удаляет обработчики хуков Apothem из <project>/.devin/config.local.json, распознавая их по пути диспетчера в их команде, и сохраняет ваши собственные хуки и ключи. Файл удаляется, только если его создал Apothem и в нём не осталось ничего другого. Скрипты хуков в <project>/.apothem/support/windsurf/hooks/ тоже удаляются. Оно удаляет папки навыков, которые записало в ~/.agents/skills/, а также правила и шаблоны в ~/.config/apothem/, но только когда никакая другая установка Apothem их больше не использует. Их может использовать другой проект или другой инструмент, разделяющий эту папку. В таком случае удаление сохраняет папки, выводит, какая установка их использует, и их удаляет последнее удаление. Файлы, которые вы добавили в эти папки, остаются, а папка, оставшаяся пустой, удаляется. Перед удалением каждая папка сохраняется в резервную копию в ~/.apothem/backups/.

Шлюз соответствияCopy Anchor Link

python -m apothem.conformity.gate --all .

Устранение неполадокCopy Anchor Link

Параметры конфигурацииCopy Anchor Link

См. такжеCopy Anchor Link

• Все окружения — полный каталог поддерживаемых инструментов
• Руководство по установке — установка Apothem в это окружение
• Справочник по apothem harnesses — вывод списка и просмотр адаптеров из CLI