Cursor

Поставщик: Anysphere Имя установки: cursor Статус: GA Нативная конфигурация: .cursor/rules/ в корне проекта

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

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

Адаптер рендерит единый файл правил .mdc в области проекта на основе общей поверхности правил и управления Apothem, записывает помощников Apothem как субагентов Cursor в проекте (см. Субагенты) и добавляет один хук в hooks.json проекта (см. Хуки).

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

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

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

Файл правил кратко излагает дисциплины и называет эти папки, чтобы модель могла открыть навык или файл правила, когда этого требует задача.

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

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

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

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

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

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

Cursor читает субагента из файла Markdown в <project>/.cursor/agents/ согласно документации Cursor по субагентам. Установка записывает в эту папку по одному файлу на каждого помощника Apothem. Она выполняет установку только для проекта и не записывает папку ~/.cursor/agents/.

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

В Cursor нет ключа, который перечисляет или запрещает инструменты: субагент наследует каждый инструмент своего родителя. Единственное ограничение, которое он может обеспечить, — readonly: true, которое не допускает правок файлов и команд оболочки, изменяющих состояние. Поэтому строки tools и disallowedTools помощника не записываются, а ограничение сохраняется только в виде этого флага:

• Пять помощников выше работают только для чтения и не имеют Bash, поэтому получают readonly: true и сохраняют формулировку «только для чтения» в своих описаниях.
• Семь помощников работают только для чтения, но выполняют команды (codebase-explorer, dependency-auditor, design-critic, prompt-evaluator, quality-gate, security-scanner и test-runner). readonly: true остановило бы и их запуски тестов и линтеров, поэтому они не получают флага, а из их описаний убирается метка «только для чтения», которую Cursor не стал бы обеспечивать. Меняется только описание: инструкции копируются без изменений, поэтому они по-прежнему называют помощника работающим только для чтения и упоминают ограничение инструментов, которого у файла Cursor нет. Модель следует этому тексту, но Cursor его не обеспечивает, и помощник работает со всеми инструментами, которые есть у родителя.
• mcp-builder и refactor-surgeon записывают файлы и не изменяются.

Установка не записывает ключ model, поэтому помощник работает на модели, которую использует родитель, а также не записывает ни is_background, ни ограничение числа ходов, ни ключи Apothem version, updated и portability.

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

• Файлы субагентов — обычные файлы проекта. Зафиксируйте их вместе с проектом или укажите .cursor/agents/ в .gitignore; Apothem не делает этот выбор за вас.
• Cursor также загружает папки помощников, записанные для других инструментов, среди них .claude/agents/ в проекте и ~/.claude/agents/ в вашем домашнем каталоге (остальные перечислены в реестре окружений). При конфликте имён проект побеждает домашнюю папку, а .cursor/ побеждает остальные, поэтому в проекте с этой установкой нативные файлы заменяют копии Claude Code, которые Cursor импортировал бы из ~/.claude/agents/. Документация Cursor не сообщает, загружает ли он обе копии или отбрасывает менее приоритетную, а также применяет ли он строки tools и disallowedTools импортируемого файла Claude Code.
• Ваш файл с именем помощника Apothem сохраняется в ~/.apothem/backups/, а затем заменяется. Удаление не возвращает его на место. Файлы с другими именами никогда не затрагиваются.
• Apothem не подтвердил, читает ли Cursor файлы TOML, которые другой инструмент записывает в импортируемые им папки, отключает ли настройка Third-Party Imports эти импортируемые папки и читает ли он расширения, отличные от .md, или вложенные папки в .cursor/agents/.

ХукиCopy Anchor Link

Cursor запускает хуки из файлов hooks.json согласно документации Cursor по хукам. Установка добавляет одну запись в <project>/.cursor/hooks.json:

Хук добавляет контекст для модели. Он ничего не блокирует, и Cursor не ждёт хука sessionStart.

Эта первая версия больше ничего не регистрирует. Документация Cursor указывает additional_context также для postToolUse, и Apothem зарегистрирует там счётчик размера контекста, как только проба покажет, что контекст доходит до модели. Он не регистрирует защиту preToolUse: Cursor документирует agent_message, поле, через которое говорила бы защита, только для действия, которое он запрещает, а защиты Apothem никогда не запрещают. Защиты записи, редактирования и оболочки, проверка AskUserQuestion и протокол завершения сессии остаются в инструментах, которые их доставляют.

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

hooks.json — ваш файл, и Cursor документирует хуки проекта как фиксируемые в системе контроля версий. Установка добавляет запись Apothem после ваших и оставляет ваши записи и другие ключи как были; обновление заменяет только запись, команда которой запускает диспетчер Apothem (.apothem/support/cursor/hooks/dispatch.py с --contract cursor, под каким бы путём проекта он ни был записан), а удаление удаляет только эту запись. Ваш хук, который лишь совпадает по имени, например tools/hooks/dispatch.py в вашем проекте, или запускает python -m apothem.conformity.gate, никогда не принимается за хук Apothem. Удаление удаляет файл, когда в нём не остаётся ничего другого, предварительно сохранив копию в ~/.apothem/backups/. Файл с комментариями, висячей запятой или значением hooks неверной формы невозможно перезаписать, ничего не потеряв, поэтому установка сообщает об ошибке config.unparseable для этого файла, оставляет его нетронутым и останавливается, снова удалив другие файлы, которые начала записывать: исправьте файл или добавьте запись самостоятельно.

Зафиксированный файл называет вашу машину. Команда записи содержит интерпретатор, который Apothem нашёл при запуске, и абсолютный путь проекта, поэтому коллега, который получит файл при checkout, получит команду, указывающую на вашу машину. Cursor сообщает о команде, которую не может найти, как о неудавшейся, и сессия продолжается, поэтому ничего не ломается, но хук там ничего не делает. Фиксируйте файл, только если ваша команда использует такую же структуру. Cursor не документирует нефиксируемый вариант файла хуков проекта. Папка .apothem/ — место, где находятся скрипты, и фрагмент .gitignore проекта исключает её из системы контроля версий.

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

"/path/to/python" "/path/to/project/.apothem/support/cursor/hooks/dispatch.py" --contract cursor sessionStart

На хосте Windows команда начинается с & , оператора вызова PowerShell, потому что настольное приложение Cursor запускает команды хуков через PowerShell, где строка, начинающаяся с пути программы в кавычках, не является вызовом. sh читает начальный & как синтаксическую ошибку, поэтому ни один другой хост его не получает. Документация называет оболочку, но не экранирование, поэтому это прочтение синтаксиса PowerShell со стороны Apothem.

--contract cursor читает conversation_id и workspace_roots Cursor и отвечает {"additional_context": ...} и ничем больше.

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

Cursor также запускает хуки, записанные для Claude Code. Cursor загружает хуки из ~/.claude/settings.json, .claude/settings.json и .claude/settings.local.json, пока включена настройка «Include Third-Party Plugins, Skills, and Other Configs» (в Cursor Settings, в разделе Third-Party Imports), что является значением по умолчанию, и запускает каждый подходящий хук из каждого источника. Если вы также установили Apothem для Claude Code, могут запускаться оба набора хуков. Команда sessionStart здесь и её копия для Claude Code разделяют один маркер на сессию в папке состояния хуков Apothem, поэтому та, что запускается второй, молчит, и начальная загрузка доходит до модели один раз; Apothem распознаёт Cursor по переменным CURSOR_PROJECT_DIR и CURSOR_VERSION, которые Cursor задаёт для своих хуков. Маркер действует десять секунд, поэтому более поздний запуск той же сессии, например второе сжатие, всё равно доставляет контекст. Счётчик размера контекста из копии для Claude Code работает дополнительно, и Apothem не устраняет дублирование счётчиков. Чтобы запускать только здешний хук, отключите эту настройку; это также останавливает импорт Cursor сторонних плагинов, навыков и других конфигураций. Установка выводит это как примечание.

Что нужно знать. Cursor перезагружает hooks.json при его сохранении, поэтому перезапуск не нужен. Хуки проекта запускаются в доверенных рабочих областях. Облако Cursor запускает хуки проекта репозитория, но откладывает sessionStart, поэтому запись там не срабатывает. Задайте APOTHEM_HOOKS_DISABLE=1 в окружении Cursor, чтобы заглушить хук Apothem.

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

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

Файл начинается со своего YAML-фронтматтера (description, globs, alwaysApply: true), потому что Cursor считывает тип правила только из фронтматтера в начале файла. За ним следует блок, управляемый Apothem; текст, который вы добавляете после блока, сохраняется при каждой синхронизации.

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

Cursor 0.45+ поддерживает инструкции на уровне проекта через .cursor/rules/. Адаптер по умолчанию записывает в каталог .cursor/rules/ в области проекта; в Cursor нет документированного файлового пути для глобальных пользовательских правил, которым мог бы управлять этот адаптер.

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

ПроверкаCopy Anchor Link

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

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

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

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

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

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

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

УдалениеCopy Anchor Link

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

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

Удаление также удаляет файлы субагентов, которые оно записало в <project>/.cursor/agents/, и сохраняет любой другой файл там; папка удаляется, если остаётся пустой. Оно удаляет запись Apothem из <project>/.cursor/hooks.json, распознавая её по пути диспетчера в её команде, и сохраняет ваши собственные записи и ключи. Файл удаляется, только когда в нём не остаётся ничего другого. Скрипты хуков в <project>/.apothem/support/cursor/hooks/ тоже удаляются. Если в файле есть комментарии, которые удаление не может прочитать, оно оставляет этот файл как есть и сообщает о записи как о пропущенной, с причиной; удалите запись Apothem вручную. Оно удаляет папки навыков, которые записало в ~/.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