快速开始

安装 Apothem、编写配置档案、物化你的第一个工具并验证它——一份可复制粘贴的导览，附预期输出。

这是从零到一份经过验证的工具配置的快速路径：安装、编写共享配置档案、物化一个工具的原生配置、确认它，并完成你的第一次编辑。每条命令都是真实的，可以复制粘贴运行，每一步都会展示一次干净运行所打印的内容。安装本身在两分钟内完成；编辑配置档案是唯一一个耗时由你自己决定的环节。

读完本页，你将拥有一份由你自己编写的配置档案生成的可用工具配置——并且你会知道那一条把配置档案的变更推送回某一个工具或全部工具的命令。

想要节奏更慢、带讲解的版本？

入门教程覆盖同样的内容，并对每一步及其重要性给出更多解释。本页是简洁、以输出为先的导览。

你将使用 Claude Code 作为示例工具——它是安装器的默认值。在任意一步替换适配器名称，即可指向另一个工具；工具列表列出了每个受支持的名称。

1. 安装 Apothem

Apothem 以自包含运行时的形式发布——引擎携带 vendored 依赖，直接从其源码树运行。一条命令即可获取源码、放置引擎并物化你的第一个工具。它会先验证已签名的发布版本，因此请在首次安装前导入一次维护者签名密钥，并核对指纹是否为 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163：

macOS · Linux · WSL2 · BSD — import the key once

curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import
gpg --fingerprint 70396FED9C634163

Windows · PowerShell — import the key once

& "$env:ProgramFiles\Git\bin\bash.exe" -c 'curl -fsSL https://github.com/ahmed-g-gad.gpg | gpg --import && gpg --fingerprint 70396FED9C634163'

然后运行安装器：

macOS · Linux · WSL2

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

Windows · PowerShell 5.1+

irm https://apothem.ahmedgad.com/install.ps1 | iex

安装器要求系统中有 Python 3.10+，网络形式还需要 git 与 gpg。它会检查前置条件，并将引擎放置在 ~/.apothem 下。当缺少 click 或 rich 时，它会在你确认后安装该软件包，或者在传入 --yes（PowerShell 上为 -Yes）或设置 APOTHEM_AUTO_INSTALL_DEPS=1 时直接安装；否则会停止，并给出需要运行的 pip 命令（参见前置条件一览）。完成时它会打印一份后续步骤横幅；在 POSIX 上，当垫片所在的目录已在 PATH 中时，横幅如下所示：

Installation complete.

The 'apothem' command is on your PATH.

Recommended first step — the guided setup (profile -> preview -> install):

  apothem quickstart

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

如果你还没有配置档案，安装器会将示例配置档案复制到 ~/.config/apothem/profile.yaml 并继续执行：它会在同一次运行中物化你的第一个工具并验证它。示例中的身份字段是占位值，因此安装会打印一条提示。在第 2 步中将配置档案改成你自己的，然后按照第 5 步的做法，用 apothem update --harness <name> 应用它。

`apothem` 命令

安装器会将一个 apothem 垫片写入 $HOME/.local/bin（POSIX）或 %LOCALAPPDATA%\Microsoft\WindowsApps（Windows），并且绝不会修改你的 PATH。一旦该目录已加入 PATH，你就可以直接以 apothem <command> 的形式运行引擎。如果它尚未加入 PATH，横幅会打印一个自包含的回退方式——PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>——它无需垫片；请将你的横幅所打印的确切前缀加在每条命令之前。

安装指南介绍了其他安装路径——Claude Code 插件（先运行 /plugin marketplace add ahmed-g-gad/apothem，再运行 /plugin install apothem@apothem）；VS Code 系扩展以及其他工具原生扩展；以及按需运行的 npx 形式（npx @ahmed-g-gad/apothem <command>）——同时还介绍了各项环境变量选项。

2. 创建共享配置档案

apothem profile init 会将最小的、符合 schema 的配置档案写入 ~/.config/apothem/profile.yaml。如果该位置已经有一份配置档案，例如第 1 步中的安装器复制了示例的情况，init 会报错停止，并保持该文件不变；传入 --force 可覆盖它，或者保留该文件并按下文所示编辑它。当你将某个项目专用或 CI 专用的配置档案保存在别处时，传入 --profile PATH。

apothem profile init
apothem profile show --json

该脚手架使用虚构的占位身份数据，在你安装任何工具输出之前编辑它是安全的。show --json 会将其读回并报告经过校验的配置档案，所有默认值均已填入，首项为 schema_version。该命令将其打印在一行上；此处为展开后的形式：

{
  "schema_version": 1,
  "identity": {
    "name": "Example User",
    "role": "senior software engineer",
    "email": "[email protected]",
    "github": "example-user"
  },
  "preferences": {
    "language": "python",
    "style": "concise"
  },
  "rules": [],
  "seriousness": "PERSONAL_USE",
  "enforcement": {
    "sprints": false,
    "agent_teams": false,
    "multitasking": false,
    "continuous_execution": false,
    "learning_loop": false
  },
  "mcp_servers": {},
  "agent_mcp_servers": {},
  "harnesses": {},
  "exclude_harnesses": [],
  "workspace": {
    "directory_name": ".apothem",
    "scope": "project-local"
  }
}

格式错误的编辑也会在这里暴露出来——如果 YAML 无效，show 会在此处报告，早于任何工具配置被写入。使用 apothem profile edit（在你的编辑器中打开它）将配置档案改成你自己的，或者就地设置单个键：

apothem profile set identity.name "Your Name"

3. 安装工具适配器

物化你的主要工具所对应的适配器。这会读取你的配置档案，并写入该工具的原生配置：

apothem install --harness claude-code

✓ Installed claude-code -> /home/you/.claude/settings.json

项目作用域的适配器将其规则文件写入项目内部，因此它们需要一个 --project PATH；其中七个还会将技能和共享规则写入你主目录中的文件夹，而 --project 不会改变这些内容的写入位置。使用 --dry-run 可以预览任意安装而不写入文件：

apothem install --harness cursor --project . --dry-run
apothem install --harness cursor --project .

使用 --harness all 一次性安装由注册表支撑的整个集合。由于该选择会同时写入项目作用域和用户作用域的文件，命令会按位置分组打印具体目标。在交互式终端中，它会在写入项目根目录之外的位置之前询问确认。没有终端的运行、带 --yes 的运行或带 --format json 的运行会直接写入而不询问；--dry-run 则不写入任何内容。运行完整集合的命令如下：

apothem install --harness all --project .

每个受支持的名称见完整工具列表，完整的选项集见 install 参考。

4. 验证

物化只完成了一半的工作——verify 会确认该工具预期的配置文件已经落地，并且内容有效：

apothem verify --harness claude-code

✓ claude-code is verified at /home/you/.claude/settings.json

如果受管目标缺失、受管文件为空，或 JSON 或 YAML 配置无法解析，verify 会以非零状态退出。添加 --profile PATH 后，若已安装的文件与该配置档案不同，verify 也会失败，此时它就成为一项漂移检查；未添加时，过期的配置仍会通过验证。这个非零退出码使 verify 可以在配置脚本中充当闸门。要对每个已注册的适配器进行整机健康检查，请运行：

apothem doctor

doctor 会检查每个已安装的工具：它必须通过验证，并且其安装所注册的每条钩子命令都必须能够启动。你尚未安装的工具会被列出，但不算失败，因此只要没有任何检查失败，doctor 就以 0 退出，即使只安装了一个工具。

5. 你的第一次运行

打开你刚配置好的工具——本例中是 Claude Code——并在任意项目中启动一个会话。你在第 2 步中设置的配置档案，现在已成为该工具行为的一部分。这就是一次可用的首次运行：一份配置档案，塑造一次真实的会话。

之后修改配置档案时，无需重新安装即可重新应用它：

apothem update --harness claude-code

指定另一个适配器，即可将配置档案重新应用到那个工具（对于项目作用域的适配器，需添加 --project PATH），或者传入 --harness all --project .，将其重新应用到每个受支持的工具。

后续步骤

添加更多工具——针对每个工具重复第 3 步。
编写你的第一条规则——每个工具都会继承的单元。
编写一个计划——通过确定性的计划流水线推进一整项任务。
CLI 参考——每个命令、标志和退出码。

1. 安装 ApothemCopy Anchor Link

2. 创建共享配置档案Copy Anchor Link

3. 安装工具适配器Copy Anchor Link

4. 验证Copy Anchor Link

5. 你的第一次运行Copy Anchor Link