入门：从零到一个可用的工具
从一台空白机器到一份已物化、已验证的工具配置的端到端演练。
本教程带你完整走完第一次 Apothem 设置。你从未安装任何东西开始，最终得到一份真实的工具配置——由你自己编写的配置档案生成、经过验证，并已确认可用。预计用时约十五分钟。下面的每条命令都是真实的，可以复制粘贴运行。
已经设置好了？
如果你只想要一份关于四个核心命令的简洁参考，请参阅核心工作流。本页是带引导的、从零到首次运行的导览。
完成本教程后，你将已经：
- 通过脚本安装器安装了 Apothem。
- 编辑了驱动每个工具的共享配置档案。
- 物化了一个工具的原生配置。
- 验证了该配置，并确认了一次可用的首次运行。
我们将全程使用 Claude Code 作为示例工具，因为它是安装器的默认值。同样的步骤适用于任何受支持的工具——当你看到工具列表时替换名称即可。
你首先需要准备什么
- 类 Unix 的 shell（macOS、Linux 或 WSL）。PowerShell 安装程序覆盖 Windows；本教程展示
bash路径。 PATH上的 Python 3.10 或更高版本。使用python3 --version检查。- 引擎从你的解释器中导入的两个运行时库：
click和rich。技术栈的其余部分（pyyaml、jsonschema）已内置（vendored）到源码树中，因此只需要这两个库可以被导入。如果缺少click或rich，安装程序会停止并打印安装命令。单行命令会把脚本通过管道交给 bash，因此无法提示；请设置APOTHEM_AUTO_INSTALL_DEPS=1（例如curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash），或者先安装这两个包。
Apothem 以捆绑的源码树形式发布，而不是以已发布的软件包形式发布——没有 pip install 步骤。安装器会克隆该源码树，并直接从中运行引擎。
第 1 步——安装 Apothem
运行网络安装器：
curl -fsSL https://apothem.ahmedgad.com/install.sh | bash安装器执行以下步骤：
- 前置条件检查。 安装程序会找到真正的 Python 3.10+ 解释器，并确认两个运行时库（
click和rich）可以被导入。如果缺少其中之一，它会指出缺失的库并停止，同时打印安装命令；设置APOTHEM_AUTO_INSTALL_DEPS=1可以不经提示直接安装，因为通过管道运行时无法提示。 - 源码放置。 随附的源码树会被克隆到
~/.apothem（可通过APOTHEM_HOME环境变量覆盖）。重新运行时会在已有的克隆中检出发布标签，而不是重复复制。 - 配置档案引导。 如果你还没有配置档案，安装程序会将示例配置档案复制到
~/.config/apothem/profile.yaml，并在同一次运行中据此安装并验证 Claude Code，同时警告身份字段是占位内容。
你可以通过环境变量来引导安装。你最可能用到的几个：
# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
APOTHEM_HARNESS=codex \
APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
bash安装器只安装用户作用域的工具。之后再安装项目作用域的工具，并指明项目：
apothem install --harness cursor --project /path/to/project其他可识别的变量包括 APOTHEM_REPO 和 APOTHEM_REF（克隆哪个远程仓库，以及检出哪个 git ref：未设置时会解析并验证最新的已签名发布标签；设置为某个标签可将其固定，设置为 main 则跟随会持续变动的分支（分支不是已签名的标签，因此还需要 APOTHEM_ALLOW_UNVERIFIED=1））、APOTHEM_ALLOW_UNVERIFIED=1（将标签签名验证失败降级为警告，并允许 main 这类非标签 ref）、APOTHEM_SOURCE（使用现有的本地检出，而不是克隆），以及 APOTHEM_SKIP_VERIFY=1（跳过安装后的验证；我们希望运行该验证，因此请保持它未设置）。
当安装器完成一次完整运行时，它会打印一个横幅，展示如何调用引擎。它会在你的 PATH 上放置一个 apothem 垫片（POSIX：$HOME/.local/bin；Windows：%LOCALAPPDATA%\Microsoft\WindowsApps），因此一旦该目录加入 PATH，你就可以直接运行引擎：
apothem <command>如果垫片无法放置——或者其所在目录尚未加入 PATH——横幅会打印一个无需垫片的自包含回退方式：
PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>本教程的其余部分都写作 apothem <command>；如果你使用的是回退形式，请在命令前加上你的安装器横幅所打印的确切前缀。
第 2 步——将配置档案改成你自己的
位于 ~/.config/apothem/profile.yaml 的共享配置档案是唯一的事实来源。每个工具适配器都会读取它，并从中派生该工具的原生配置。编辑一次，你安装的每个工具就会保持一致。
在引擎的编辑器中打开它，或者在任意文本编辑器中打开：
apothem profile edit一份最小的有效配置档案如下所示：
identity:
name: "Example User"
preferences:
style: "concise"
rules:
- "Validate external input before writing files."将占位的 name 替换为你自己的名字，并添加任何你希望每个工具都强制执行的规则。示例值请保持为虚构值——配置档案的设计初衷就是可以安全地共享。
确认引擎能够干净地读回你的编辑：
apothem profile show --json如果 YAML 格式错误，你会在这里看到——修复后重新运行，再继续下一步。
第 3 步——物化一份工具配置
如果第 1 步的运行创建了配置档案，它已经根据占位身份安装了 Claude Code。请在第 2 步中编辑配置档案，然后运行以下命令应用你的身份：
apothem update --harness claude-codeapothem install --harness claude-code这会读取你的配置档案，并写入 Claude Code 的原生配置。要查看你可以指向的每个工具：
apothem harnesses list有些工具是项目作用域的，而不是用户作用域的，这些工具需要一个 --project 路径，以便适配器知道应写入何处：
apothem install --harness cursor --project .第 4 步——验证并确认首次运行
物化只完成了一半。现在确认配置已正确落地：
apothem verify --harness claude-codeverify 会检查该工具受管理的配置文件是否存在并且可以解析。加上 --profile PATH 后，当某个已安装的文件偏离了该配置档案本应生成的内容时，它也会失败。一次干净的运行意味着物化成功。
要对每个已注册的适配器进行一次全机健康检查，运行：
apothem doctordoctor 会检查每个已安装的工具（它必须通过验证，并且其注册的钩子命令必须能够启动），并在任何检查失败时以非零状态退出。你尚未安装的工具会被列出，但不会导致它失败，因此它在配置脚本中是一个有用的闸门。
你的第一次运行。 打开你刚配置好的工具——在我们的示例中是 Claude Code——并在任意项目中启动一个会话。你写入配置档案的规则和偏好，现在已成为该工具行为的一部分。这就是一次可用的首次运行：你在第 2 步中编辑的配置档案正在塑造一次真实的会话。
你构建了什么
从一台空白机器开始，你安装了 Apothem，编写了一份共享配置档案，从中物化了一个工具的原生配置，验证了结果，并确认了它可用。配置档案是持久的产物——修改它一次，然后重新运行 apothem update --harness <name>，即可将变更推送到任意工具。
接下来去哪里
- 添加另一个工具。 工具列表涵盖每个受支持的平台及其适配器名称。使用一个新的
--harness重复第 3 步。 - 深入某一项任务。 操作方案涵盖添加工具、编辑配置档案以及驱动安装器。使用指南涵盖编写规则、编写计划以及运行合规闸门。
- 查阅具体细节。 参考记录每个产物类别以及配置档案 schema，CLI 参考涵盖每条命令。每个适配器在工具下都有自己的页面。
- 规划比单个会话更长久的工作。 可恢复的规划解释 Apothem 如何将长时间运行的工作外置到项目本地的
.apothem/plans/套件中，使任何机器上的新会话都能就地恢复它。
推荐的下一步
运行 apothem doctor 来检查你的设置——它会报告每个已注册适配器的状态，因此你刚安装的工具会显示为健康，其余的则显示为尚未安装——然后再着手添加更多工具。