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，即规则文件。
• 每个 Apothem 辅助器对应一个 <project>/.codebuddy/agents/<name>.md，位于项目中。
• <project>/.codebuddy/settings.local.json，即钩子注册，位于项目中。你自己在其中的条目会保留。
• <project>/.apothem/support/hooks/，即钩子脚本，位于项目中。
• 每个 Apothem 技能和命令对应一个 ~/.codebuddy/skills/<name>/SKILL.md，位于你的用户主目录中。
• ~/.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 子代理文档，CodeBuddy 从 <project>/.codebuddy/agents/（项目代理）或 ~/.codebuddy/agents/（用户代理）中的 Markdown 文件读取子代理。安装只为每个 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 键。

需要了解的事项：

• 子代理文件是普通的项目文件。将它们随项目一起提交，或者在 .gitignore 中列出 .codebuddy/agents/；Apothem 不替你做选择。
• CodeBuddy 会在下一个会话开始时加载手动添加的子代理文件，因此请在安装后开始一个新会话。
• 你自己的、与某个 Apothem 辅助器同名的文件会先保存到 ~/.apothem/backups/ 下，然后被替换。卸载不会将其放回。其他名称的文件绝不会被触碰。
• CodeBuddy 的 IDE Subagents 页面展示了 CLI 页面未列出的键，并且 Apothem 尚未确认 IDE 是否接受 disallowedTools 或 maxTurns。

钩子Copy Anchor Link

根据 CodeBuddy 钩子文档，CodeBuddy 运行其设置文件 hooks 键中的钩子，该文档将钩子标记为 Beta。安装会注册两个钩子：

两者都为模型添加上下文。两者都不会阻止工具调用或会话。

Apothem 不在 CodeBuddy 上注册 PreToolUse 守卫。CodeBuddy 的文档为 SessionStart、UserPromptSubmit 和 PostToolUse 列出了 additionalContext（Apothem 的守卫借以传达的字段），而为 PreToolUse 只列出了权限和输入字段。在那里注册的守卫会在每次工具调用时付出一次进程启动的代价，却可能什么也传达不了，因此写入、编辑和 shell 守卫、AskUserQuestion 检查以及会话结束协议都保留在能够传达它们的工具上。一旦文档或探测表明守卫能够到达模型，Apothem 就会在相应的 CodeBuddy 事件上注册它。

文件的写入位置

每条注册的命令都包含 Apothem 运行时找到的解释器以及项目的绝对路径，因此它是特定于机器的。这就是安装写入本地文件、而从不写入提交的 <project>/.codebuddy/settings.json 的原因。安装不会编辑 .gitignore：请检查你的忽略文件是否列出了 .codebuddy/settings.local.json 和 .apothem/，这样队友的检出就不会收到指向你机器的命令。

shell 会误读的路径。 包含 $、反引号、双引号或反斜杠的项目路径或解释器路径会在写入任何内容之前被拒绝：在带引号的命令内部，它会运行一个不同的文件，或者破坏写入该命令的 JSON。错误信息会指出该路径；移动或重命名项目，然后再次运行安装。路径中的空格或撇号没有问题。

命令看起来如下所示，其中的两个路径会替换为你的解释器和项目路径：

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

--contract codebuddy 对输出不起作用：CodeBuddy 读取的信封与 Claude Code 相同。CodeBuddy 通过你的 shell 运行钩子命令，在 Windows 上则通过 Git Bash 运行（它既不支持 cmd.exe，也不支持 PowerShell），因此这些命令使用 bash 引号规则和正斜杠形式的解释器路径。如果 CodeBuddy 要求，请安装 Git for Windows。

安装运行后请审查钩子。 CodeBuddy 在启动时为其设置拍摄快照，不会热加载另一个工具写入的设置文件，并且只有在你于其 /hooks 面板中审查之后，才会应用从外部添加的钩子。在 apothem install 之后（以及在更改钩子的更新之后），请重启 CodeBuddy 并在 /hooks 中确认 Apothem 条目。安装会将此作为一条说明打印出来。文档没有说明每次更改后是否需要重新审查，因此请在更新后再次打开 /hooks。

你自己的钩子。 注册按键合并到你的文件中。你编写的钩子和其他键保持原样，你在同一事件和匹配器下的处理程序会与 Apothem 的处理程序并存，更新只替换其命令运行 Apothem 分发器的处理程序（带有 --contract codebuddy 的 .apothem/support/hooks/dispatch.py，无论它是写在哪个项目路径下的）。你自己的钩子如果只是名称相同（例如你项目中的 tools/hooks/dispatch.py），或者运行的是 python -m apothem.conformity.gate，绝不会被当作 Apothem 的钩子。带有注释或其他 JSON5 语法的文件无法在不丢失这些内容的情况下被重写，因此安装会针对该文件报告 config.unparseable 错误并保持该文件不变：移除注释，或者自己添加这两个条目。

关闭钩子。 在 CodeBuddy 的环境中设置 APOTHEM_HOOKS_DISABLE=1 即可让 Apothem 钩子静默，或者设置 CodeBuddy 自己的 disableAllHooks 设置来禁用所有钩子。

配置档案到原生配置的映射Copy Anchor Link

适配器在每次运行 apothem install 或 apothem update 时读取 Apothem 的共享配置档案，并渲染项目规则文件。按照 CodeBuddy Rules 文档，CodeBuddy 将 .codebuddy/rules/ 下的每个 *.md 文件读取为带有可选 YAML 前置元数据（alwaysApply、paths、enabled）的 Markdown；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 是幂等的——重新运行会用最新渲染的内容覆盖受管文件。

更新还会重写其文件与当前文件不同的任何技能文件夹。如果你使用的是一个不写入技能的早期版本进行安装，更新会添加这些技能。它会重写与当前文件不同的子代理文件，并添加任何缺失的子代理文件。它还会刷新钩子脚本以及 .codebuddy/settings.local.json 中的 Apothem 处理程序，而不触碰你自己的条目；之后请重启 CodeBuddy 并再次检查 /hooks。

卸载Copy Anchor Link

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

移除 apothem-rules.md 中的 Apothem 块，并保留其中的其他文本。只有当文件中已无其他内容时才会删除该文件。在变更之前，会在 ~/.apothem/backups/ 下保存一份带时间戳的文件副本；项目中不会留下备份文件。共享配置档案 YAML 与 Apothem 引擎不受影响。

卸载还会移除它在 <project>/.codebuddy/agents/ 中写入的子代理文件，并保留其中的其他任何文件；该文件夹变空时会被移除。它会从 <project>/.codebuddy/settings.local.json 中移除 Apothem 钩子处理程序（通过其命令中的分发器路径识别它们），并保留你自己的钩子和键。仅当该文件由 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 列出并检查适配器