install

从共享配置档案安装一个工具适配器配置。

概要Copy Anchor Link

apothem install --harness NAME|all [--profile PATH] [--dry-run]
                 [--clean|--fresh] [--yes] [--project PATH]
                 [--quiet|-q] [--verbose|-v]
                 [--format plain|json] [--json] [--no-color]

加载并校验共享配置档案，选择一个具名适配器或覆盖整个注册表的 all 集合，校验物化计划，然后写入工具原生配置以及支持集合。项目作用域的适配器需要 --project PATH。

连续式别名 apothem installing（也接受 apothem Installing）解析到同一个处理程序。

没有配置档案时的首次运行Copy Anchor Link

当省略 --profile 且默认路径（~/.config/apothem/profile.yaml）下不存在配置档案时，install 会先在该处写入起始配置档案，打印 Created a starter profile at <path>，然后继续执行。起始配置档案带有占位身份字段，因此安装还会打印占位身份说明；先将配置档案个性化，然后运行 update 以应用它。在 --json 下，这次创建会作为一个带有 "operation": "profile_created" 的 warnings 条目报告。

• --dry-run 绝不会写入配置档案：预览使用内存中的起始配置档案，并报告 "operation": "profile_scaffold_preview"。
• 显式指定但不存在的 --profile PATH 绝不会被创建；该命令以退出码 1 退出，并给出 profile.not_found。

影响范围预览Copy Anchor Link

install --harness all 会扇出到混合的作用域：项目作用域的适配器写入所提供的 --project 根目录之下，而用户作用域的适配器写入你的主目录之下——也就是该根目录之外。在安装写入任何文件之前，该命令会打印具体的目标，并按两个标题分组：位于项目根目录内的目标，以及位于你主目录下的目标。第三个标题列出项目作用域的适配器在 --project 之外写入的、你主目录中的共享文件夹：技能文件夹和 ~/.config/apothem/（见主目录中的文件夹）。唯一的例外是 --clean：其清空重来步骤早于此预览运行，它会写入备份并删除先前的目标，具体见下文。

当所选内容写入项目根目录之外时，无论是写入以主目录为根的适配器的文件夹，还是写入共享文件夹，交互式确认都会把守以主目录为根的写入。--yes、非交互式 shell（无 TTY）、--dry-run 和 --format json 各自都会在不提示的情况下继续。只有 --dry-run 不写入任何内容；--format json 会跳过预览和确认提示，但仍会执行写入。拒绝主目录提示会在安装写入之前中止。使用 --clean 时，清理步骤会先运行，并且有自己针对每个目标的确认：它会在 ~/.apothem/backups 下写入备份，并删除它所确认的目标。拒绝安装提示后，这些删除操作和备份仍然保留。

主目录中的文件夹Copy Anchor Link

有七个项目作用域的适配器会将 Apothem 的技能，以及这些技能引用的规则和模板，写入你用户主目录中的文件夹：

cursor, github-copilot, windsurf, zed  ->  ~/.agents/skills/ (codex writes it too)
codebuddy                               ->  ~/.codebuddy/skills/
kiro                                    ->  ~/.kiro/skills/
trae                                    ->  ~/.trae/skills/
all seven                               ->  ~/.config/apothem/rules/ and templates/ (codex uses them too)

• --project 选择规则文件以及该安装所属的项目。它不会改变技能的去处：一次使用 --project A 的安装和一次使用 --project B 的安装会写入相同的文件夹。
• 每个指定某个文件夹的安装都写入相同的文件。第二次安装会发现它们并报告 unchanged，而且安装的顺序无关紧要。
• 主目录中的文件夹会先于项目中的任何内容写入。如果在那里的写入失败，该适配器的安装会带着该错误停止，而项目保持不变。该错误会指出挡路的路径，例如位于文件夹应在之处的一个名为 ~/.agents 的文件。
• 每个技能文件夹都会先写入其旁边一个隐藏的 .<name>.apothem-staging 文件夹，完成后再重命名到位，因此失败或中断的写入绝不会以最终名称留下一个写了一半的技能文件夹。再次运行安装即可完成；它会替换遗留的暂存文件夹。
• 位于这些文件夹之一或其上层的符号链接（例如 dotfile 管理器为 ~/.config 或 ~/.agents 创建的链接），在它通向你主目录之内的某处时会被跟随。离开你主目录的链接会使安装以 target escapes the allowed materialization root 停止，技能文件夹内部的链接也是如此。
• 安装不会向你的仓库添加任何技能或规则文件。项目得到的是该适配器的规则文件，以及每次项目安装都会创建的 .apothem/ 数据文件夹。
• 与某个 Apothem 技能同名、但并非由 Apothem 写入的技能文件夹会被跳过。安装会打印一条 Warning: 行，而 --format json 信封会携带一个带有 "outcome": "warning" 和 "operation": "skill_conflict" 的 warnings 条目，指出该文件夹。将该文件夹重命名或移走，然后运行 update。
• 每一次这样的安装、更新和试运行都会打印一条 Note:，指出它在 --project 之外写入的文件夹。在 JSON 信封中，它是一个带有 "operation": "user_level_write" 和 paths 列表的 warnings 条目。

能力说明Copy Anchor Link

每个适配器只投射其工具原生支持的能力；没有原生表面的能力会被报告，而不是被无声地丢弃。在纯文本模式下，这表现为每个工具一条分组说明（例如 Note: <harness> - 9 capabilities not projected; pass --verbose for detail）；在 --verbose 下，每项能力都会打印自己的理由行。在纯文本模式下，任何其他适配器警告同样会打印在单独的 Warning: 行上，例如 Zed 的那条警告，它会指出被新的 .rules 遮蔽的指令文件。无论详细程度如何，--format json 信封始终携带完整的 warnings 数组。

安装和更新还会以 Note: 行的形式打印建议性提示。建议性提示绝不会改变安装所写入的内容。当一次安装写入一个共享根目录（一个其他工具也会加载的路径，例如技能文件夹 ~/.agents/skills/）时，该说明会指出那些工具，并将仅在某个条件下才加载该路径的工具放在括号中，例如 Open-Claw (only under its default state directory)。一次写入其他安装也会写入的文件夹的安装（holder 角色）会说明，该文件夹会一直保留，直到使用它的最后一个 Apothem 安装被卸载为止，并指出当前使用它的安装。当一次安装的目标工具已经从另一次安装的共享根目录加载 Apothem 内容时，该说明会指出放置它的那次安装：在注册所有者仍使用该文件夹时为注册所有者，否则为使用它的最早的安装。在 --format json 信封中，每条建议性提示都是一个带有 "outcome": "advisory" 和 "operation": "shared_root" 的 warnings 条目；其 role 为 owner、holder 或 reader，holders 列出使用该文件夹的安装，owner_of_record 指出记录在案的所有者。

注册钩子的安装还会打印有关钩子文件的说明。hook_review 建议性提示会指出工具在运行这些钩子之前所需的步骤（重启并审查，或信任该工作区），或者指出一个由仓库提交、且写有本机解释器的钩子文件所带来的风险。对于同样会运行 Claude Code 设置文件（例如 Apothem 为 Claude Code 所做的安装写入的那些文件）中钩子的工具，会出现 hook_import 建议性提示，它会指出该工具自身用于关闭这种导入的开关，以及该开关还会停止什么。每条都是一个 warnings 条目，带有 "outcome": "advisory"、harness、钩子文件的 path 和一个 message。

钩子命令会将项目路径和解释器路径放在双引号内，sh、Git Bash 和 PowerShell 都能读取这种形式。包含 $、反引号、双引号或反斜杠的路径会使该命令运行另一个文件，因此安装（以及 --dry-run）会以一个指出该路径的错误停止，并且不写入任何内容；请移动或重命名项目后再次运行。路径中的空格或撇号没有问题。

配置档案中的 MCP 服务器会得到三条建议性提示，每条都会指出相应的配置档案字段：

凭据提示绝不会打印它所发现的值。包含 ${...} 引用的值绝不会被标记。

带注释的操作者配置Copy Anchor Link

某些工具配置是你也会编辑的文件，例如 settings.json、opencode.json（可能是 JSONC）、openclaw.json（JSON5）和 config.yaml。安装会将自己的键合并到这些文件中，并保留你添加的每个键。

合并会将文件重写为纯 JSON 或 YAML，这会丢弃注释、尾随逗号和 JSON5 语法。因此：

• 当合并不会改变任何值时（例如，你已经自己添加了 Apothem 的键），该文件会逐字节保持原样。
• 当合并必须更改一个带有注释或 JSON5 语法的文件中的值，或一个根本无法解析的文件中的值时，安装不会为该工具写入任何内容，并以退出码 1 退出，错误码为 config.unparseable。fix 字段会指出安装将要添加的键，因此你可以将该文件转换为纯 JSON 或 YAML，或者手动添加这些键后重新运行。
• 当安装要用映射或列表填充的某个键（例如 config.yaml 中的 skills.external_dirs）在你的文件中持有一个标量值或另一种容器形态时，安装不会为该工具写入任何内容，并以退出码 1 退出，错误码相同，因为填充该键会丢弃你的值。该错误会指出这个键；将它改为错误所指出的形态，或将其移除，然后重新运行。你留空的键（skills: 下面什么都没有）会被填充。

选项Copy Anchor Link

JSON 输出Copy Anchor Link

当提供 --json（或 --format json）时，会向 stdout 写入单个 JSON 文档：

{
  "schema_version": 1,
  "status": "success",
  "command": "install",
  "action": "installed",
  "harness": "claude-code",
  "profile_path": "C:\\Users\\Example\\.config\\apothem\\profile.yaml",
  "project": null,
  "files_written": ["C:\\Users\\Example\\.claude\\settings.json"],
  "results": [],
  "warnings": [],
  "error": null,
  "output_path": "C:\\Users\\Example\\.claude\\settings.json"
}

对于 --dry-run，不会写入任何内容，results 会列出安装将要写入的每个路径，每个路径都带有它将得到的结果（created、updated 或 unchanged），对于你也会编辑的文件，还会在 detail.diff 中带有统一差异——与 apothem diff 所显示的计划相同：

{
  "schema_version": 1,
  "status": "dry_run",
  "command": "install",
  "action": "dry_run",
  "harness": "claude-code",
  "files_written": [],
  "results": [
    {
      "harness": "claude-code",
      "outcome": "created",
      "operation": "write_text",
      "path": "C:\\Users\\Example\\.claude\\settings.json",
      "message": "dry run: no filesystem changes made"
    }
  ],
  "warnings": [],
  "error": null
}

当提供 --clean 时，信封还会额外携带一个描述移除阶段的 clean 对象——逐目标的处置列表、本次运行是否为预览，以及带时间戳的备份目录（试运行中为 null）：

{
  "clean": {
    "dry_run": true,
    "backup_dir": null,
    "targets": [
      {
        "path": "C:\\Users\\Example\\.claude",
        "present": true,
        "removed": false,
        "skipped_reason": null
      }
    ]
  }
}

一次全新安装的试运行会在一个文档中预览两个阶段：clean 下的移除预览，以及 results 下的全新写入预览。

预期内的校验错误使用相同的信封，并包含一个错误对象：

{
  "schema_version": 1,
  "status": "error",
  "command": "install",
  "harness": "all",
  "files_written": [],
  "error": {
    "code": "project.required",
    "field": "project",
    "reason": "project-scope harnesses require --project: cursor, gemini-cli, github-copilot, kimi-code, windsurf, codebuddy, kiro, trae, zed, glm.",
    "fix": "Pass --project PATH or select only user-scope harnesses."
  }
}

示例Copy Anchor Link

apothem install --harness claude-code
apothem install --harness claude-code --dry-run
apothem install --harness cursor --project . --profile ~/profile.yaml --json
apothem install --harness all --project . --dry-run --json
apothem installing --harness claude-code   # continuous-form alias
apothem Installing --harness claude-code   # capitalized variant

退出码Copy Anchor Link

另请参阅Copy Anchor Link

• apothem installing——此命令的连续式别名（在此处记录；CLI 接受两种形式）
• apothem update——将当前配置档案重新应用到一个工具
• apothem verify——确认适配器已生效
• 入门——完整安装指南