CodeBuddy

Поставщик: Tencent Имя установки: codebuddy Статус: GA Нативная конфигурация: <project>/.codebuddy/rules/apothem-rules.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Записываются только названия инструментов, которые показывает документация CodeBuddy. Её страница Settings перечисляет инструменты, а страница о субагентах называет ещё один инструмент, который включён в список ниже:

Read, Grep, Glob, Bash, Edit, Write, MultiEdit, NotebookEdit, WebFetch, WebSearch,
Agent, Task, TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate,
AskUserQuestion, ExitPlanMode, LSP, Skill, SlashCommand

Инструмент, который указан в источнике, но отсутствует в этом списке (например PowerShell или TodoWrite), не попадает ни в одно из полей. Инструмент с шаблоном, такой как Bash(rm *), невозможно выразить в списке через запятую: как разрешённый инструмент он опускается, а как запрещённый — запрещает инструмент целиком. Помощник, который не может редактировать файлы, сохраняет это ограничение: он не перечисляет Write или Edit среди своих инструментов и запрещает оба. Установка не записывает ключ model, поэтому помощник использует модель, которую выбирает CodeBuddy, а также не записывает ключи permissionMode и hooks.

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

• Файлы субагентов — обычные файлы проекта. Зафиксируйте их вместе с проектом или укажите .codebuddy/agents/ в .gitignore; Apothem не делает этот выбор за вас.
• CodeBuddy загружает файлы субагентов, добавленные вручную, в начале следующей сессии, поэтому после установки начните новую сессию.
• Ваш файл с именем помощника Apothem сохраняется в ~/.apothem/backups/, а затем заменяется. Удаление не возвращает его на место. Файлы с другими именами никогда не затрагиваются.
• Страница Subagents для IDE CodeBuddy показывает ключи, которых нет на странице CLI, и Apothem не подтвердил, что IDE принимает disallowedTools или maxTurns.

ХукиCopy Anchor Link

CodeBuddy запускает хуки из ключа hooks своих файлов настроек согласно документации CodeBuddy по хукам, которая помечает хуки как бета-функцию. Установка регистрирует два:

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

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

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

Каждая зарегистрированная команда называет интерпретатор, который Apothem нашёл при запуске, и абсолютный путь проекта, поэтому она привязана к машине. Именно поэтому установка записывает локальный файл и никогда не записывает фиксируемый в репозитории <project>/.codebuddy/settings.json. Установка не редактирует .gitignore: проверьте, что ваш перечисляет .codebuddy/settings.local.json и .apothem/, чтобы checkout коллеги не получил команды, указывающие на вашу машину.

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

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

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

--contract codebuddy не влияет на вывод: CodeBuddy читает тот же конверт, что и Claude Code. CodeBuddy запускает команды хуков через вашу оболочку, а в Windows — через Git Bash (CodeBuddy не поддерживает ни cmd.exe, ни PowerShell), поэтому команды используют экранирование bash и путь интерпретатора с прямыми косыми чертами. Установите Git for Windows, если CodeBuddy его запросит.

Проверьте хуки после установки. CodeBuddy делает снимок своих настроек при запуске, не подгружает на лету файл настроек, записанный другим инструментом, и применяет добавленные извне хуки только после того, как вы проверите их на своей панели /hooks. После apothem install (и после обновления, которое меняет хуки) перезапустите CodeBuddy и подтвердите записи Apothem в /hooks. Установка выводит это как примечание. Документация не сообщает, повторяется ли проверка после каждого изменения, поэтому после обновления снова откройте /hooks.

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

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

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

Адаптер читает общий профиль Apothem и рендерит файл правил проекта при каждом запуске apothem install или apothem update. CodeBuddy читает каждый файл *.md в .codebuddy/rules/ как Markdown с необязательным YAML-фронтматтером (alwaysApply, paths, enabled) согласно документации CodeBuddy по правилам; файл Apothem содержит alwaysApply: true, поэтому поверхность управления применяется при каждом взаимодействии. Фронтматтер — это первое содержимое файла, а за ним следует блок, управляемый Apothem; текст, который вы добавляете после блока, сохраняется при каждой синхронизации. Общий профиль является источником истины; для локальных правок сгенерированного файла в проекте создаётся резервная копия, прежде чем следующая синхронизация заменит содержимое, управляемое Apothem.

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

Поверхность правил CodeBuddy ограничена областью проекта в .codebuddy/rules/. Адаптер записывает выделенный файл apothem-rules.md, который сосуществует с любыми файлами правил, созданными оператором в том же каталоге. Файл памяти проекта CODEBUDDY.md, фиксируемый в репозитории .codebuddy/settings.json и файл проекта .mcp.json (серверы MCP) принадлежат оператору; Apothem их не записывает. CodeBuddy также документирует слэш-команды; адаптер их не записывает и вместо этого ссылается на соответствующие дисциплины внутри файла правил. Зато он записывает субагентов и два хука в проект (см. Субагенты и Хуки), а также навыки и команды Apothem в виде навыков в вашу папку пользователя (см. Файлы за пределами проекта). Когда в проекте нет CODEBUDDY.md, CodeBuddy Code читает AGENTS.md как память проекта, поэтому AGENTS.md, записанный другим адаптером, также доходит до CodeBuddy. Соглашения поверхности поставщика, на которые опирается адаптер, зафиксированы в src/apothem/harnesses/codebuddy/STANDARD-CONVENTION-PIN.md в виде снимка актуальной документации CodeBuddy.

CodeBuddy документирует ~/.codebuddy/skills/ для пользовательских навыков и не упоминает ~/.agents/skills/, поэтому установка записывает папку CodeBuddy, а не общую для инструментов. Эту папку читает только CodeBuddy. Его страница о навыках перечисляет disable-model-invocation, user-invocable и allowed-tools и не указывает ключи metadata или argument-hint; Apothem не подтвердил, что CodeBuddy их принимает.

ПроверкаCopy Anchor Link

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

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

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

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

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

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

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

УдалениеCopy Anchor Link

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

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

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