安装

Apothem 的安装用时不到两分钟，并可与你现有的工具配置并存。每条路径运行的都是同一个自包含引擎——源代码树携带其 vendored 依赖，可在系统 Python 3.10 或更新版本上从检出目录运行（参见自包含运行时）。

每条路径共有两个前置条件： PATH 上的系统 Python 3.10 或更新版本，且 click 和 rich 包可在该解释器下导入。npm 垫片（渠道 2）、VS Code 系扩展（渠道 4）以及命令行引导（渠道 5–7）还需要 Node.js 18 或更新版本 来运行 npx。Python 3.10 以及 Node.js 18 和 20 已过上游生命周期终止时间；它们仍受支持并经过测试，但更推荐使用更新的版本（参见前置条件一览）。下面每条渠道各自的小节会重复列出其确切的前置条件、一条可直接复制的命令和一个验证步骤。

选择一条渠道Copy Anchor Link

共有八条安装渠道可用。按你现有的工作方式来选择。

每条路径都是幂等的：重新运行是安全的，并会收敛到同一状态。

1. Claude Code 插件Copy Anchor Link

前置条件： Claude Code，以及 PATH 上的系统 Python 3.10+。

插件路径完全在 Claude Code 内部运行。它将 Apothem 引擎与其斜杠命令、委派工作者、技能、规则和钩子打包在一起，全部可从自包含的插件目录树中运行：

/plugin marketplace add ahmed-g-gad/apothem
/plugin install apothem@apothem

安装之后，Apothem 命令集、随附的委派工作者、技能以及四种输出样式（用 /output-style 或从 /config 中选择一种）在每个 Claude Code 会话中都可用。插件将每条命令作为一个技能发布：一个 SKILL.md，其按需加载的详细内容放在旁边的 references/ 文件夹中，因此 Claude Code 以插件的前缀调用它：/apothem:plan-spec、/apothem:security-audit 等。有两个名称已被 Claude Code 自身占用：/plan 进入计划模式，/code-review 运行内置的评审，因此要使用 Apothem 的命令，请输入 /apothem:plan 和 /apothem:code-review。当由 Apothem 引擎而非插件安装到 Claude Code 中时，同样的技能会被写入 ~/.claude/skills/，不带前缀，并且一个个人 code-review 技能会取代内置的 /code-review（其 /review 别名仍运行内置的那个）。有两个名称——projectify 和 workflow——也是原生技能；插件和引擎安装所发布的是原生技能，而不是由命令派生出的技能。命令如何拆分见 Claude Code，完整的命令目录见斜杠命令。

验证： 在 Claude Code 内运行 /plugin 并确认 apothem 显示为已安装，或从终端检查漂移报告：

npx @ahmed-g-gad/apothem verify --harness claude-code

2. npm 垫片（npx）Copy Anchor Link

前置条件： Node.js 18+（用于 npx）以及 PATH 上的系统 Python 3.10+。垫片会定位解释器，并将每条 CLI 命令转发给随附的引擎——不会在你的系统上永久放置任何内容。它依次尝试 python3、python，然后是 py -3；将 APOTHEM_PYTHON 设置为某个解释器路径，即可让垫片优先尝试该解释器——当 Python 已安装但不在 PATH 上，或者装有多个版本而你想使用特定的一个时，就需要这样做。你所指定的解释器仍须通过 Python 3.10+ 检查；未通过时，垫片会回退到依次尝试 python3、python，然后是 py -3。

npx @ahmed-g-gad/apothem install --harness claude-code

在没有配置档案的机器上，这第一次 install 会在 ~/.config/apothem/profile.yaml 创建起始配置档案，并告知这一点。它的身份字段是占位符：先将它们个性化（npx @ahmed-g-gad/apothem profile edit），再用 update 代替 install 重新运行该命令以应用它们。

它也可以直接从仓库运行：

npx github:ahmed-g-gad/apothem install --harness claude-code

CLI 参考中的每条命令都能以这种形式运行；用 npx @ahmed-g-gad/apothem 替换 apothem 即可。这也是 OpenCode 以及其他所有不提供独立插件或扩展注册表的工具的安装路径——Apothem 会将它们直接同步到其原生配置目录（npx @ahmed-g-gad/apothem install --harness opencode）。

验证：

npx @ahmed-g-gad/apothem --version
npx @ahmed-g-gad/apothem verify --harness claude-code

3. 一键安装器Copy Anchor Link

前置条件： PATH 上的系统 Python 3.10+（安装器会提出为你添加 click / rich 前置依赖）；网络安装需要 git 与 gpg，它会克隆源码并验证其已签名的发布标签（Git for Windows 同时提供这两者）。

安装脚本会在一次运行中完成以下全部步骤：解析最新的已签名发布标签，验证其签名，将该标签处的 Apothem 源代码树放置到 ~/.apothem，在不存在配置档案时创建起始配置档案，物化你的第一个工具，并验证结果。起始配置档案带有占位的身份字段：编辑它，然后运行 apothem update --harness <name> 以应用你自己的身份字段。重新运行是幂等的：已有的目录树会被重新检出到解析出的标签，工具也会被重新物化。锁定标签且经过验证的安装是默认且推荐的路径。

请先导入一次维护者签名密钥。当该密钥不在你的密钥环中时，安装器会停止。请核对指纹是否为 5C89 98F9 F241 7204 45D3 F28B 7039 6FED 9C63 4163，即 SECURITY.md 中公布的值。在 Windows 上，git verify-tag 读取的是随 Git for Windows 一同提供的 gpg 的密钥环，因此导入需通过 Git 自带的 bash 执行：

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

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

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

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

同样的脚本也随检出目录附带在 scripts/installer/ 下——install、uninstall 和 update，各有 .sh、.ps1 和 .bat 形式——因此你可以在克隆后直接运行它们：

APOTHEM_HARNESS=claude-code sh scripts/installer/install.sh                                 # POSIX
$env:APOTHEM_HARNESS = 'claude-code'; pwsh -NoProfile -File scripts/installer/install.ps1   # Windows

信任模型Copy Anchor Link

未设置 APOTHEM_REF 时，安装器会解析最高的 vMAJOR.MINOR.PATCH 发布标签并检出该标签——绝不会检出会持续变动的 main 分支。在物化任何配置之前，会用 git verify-tag 验证所获取标签的签名；未签名、被篡改或无法验证的标签会在写入任何内容之前中止安装。若某个已签名标签的维护者公钥尚不在本地密钥环中，安装器会中止并改为给出密钥导入指引：按上文所示导入该密钥，将其指纹与 SECURITY.md 中公布的值进行核对，然后重新运行。用 APOTHEM_REF 锁定某个特定的发布：

APOTHEM_REF=vMAJOR.MINOR.PATCH sh -c "$(curl -fsSL https://apothem.ahmedgad.com/install.sh)"

将 vMAJOR.MINOR.PATCH 替换为发布页面上的某个标签。最早的发布标签是一个轻量标签，本身没有签名，因此即使其提交已签名，标签检查也会在它上面中止；此后的每个发布标签都是经过签名的附注标签。SECURITY.md 的发布签名部分列出了每个标签及其验证方法。

显式覆盖项会放宽默认行为。APOTHEM_ALLOW_UNVERIFIED=1 会把验证失败降级为警告并继续，适用于物理隔离网络或本地使用场景，或用于安装早于标签签名的发布版本。APOTHEM_REF=main 只有在同时设置 APOTHEM_ALLOW_UNVERIFIED=1 时，才会在不验证的情况下检出会持续变动的分支。仅设置 APOTHEM_REF=main 时，安装器会把 main 拉取到 APOTHEM_HOME，然后在物化任何配置之前中止，因为分支不是已签名的发布标签。通过 APOTHEM_SOURCE 使用本地检出时不会拉取任何内容，并会跳过验证。

APOTHEM_VERIFY=checksum 是为尚未持有维护者公钥的主机提供的折中路径：安装器不进行克隆，而是下载该发布的平台归档及其 SHA256SUMS，在解压任何内容之前若摘要不匹配即中止，并发出警告：摘要匹配只能证明该归档是发布所列出的那一个，而不能证明是谁发布了它。

随后引擎直接从放置好的目录树中运行。除 click 和 rich 之外的每个第三方依赖都 vendored 在源代码树内，并且入口点会自行将该 vendor 目录放到 sys.path 上：

PYTHONPATH="$HOME/.apothem/src" python -m apothem <command>

两个脚本读取相同的配置环境变量（APOTHEM_HOME、APOTHEM_REPO、APOTHEM_REF、APOTHEM_ALLOW_UNVERIFIED、APOTHEM_VERIFY、APOTHEM_RELEASE_BASE、APOTHEM_SOURCE、APOTHEM_HARNESS、APOTHEM_PROFILE、APOTHEM_SKIP_VERIFY、APOTHEM_AUTO_INSTALL_DEPS、APOTHEM_BIN_DIR）；完整表格见安装器环境变量，python -m 调用模型的工作方式见自包含运行时。

apothem 命令。 安装成功后，安装器会写入一个转发给随附引擎的 apothem 垫片——在 POSIX 上写入 $HOME/.local/bin，在 Windows 上写入 %LOCALAPPDATA%\Microsoft\WindowsApps（一个默认已在 Windows PATH 上的用户目录）。安装器绝不编辑你的 PATH。一旦该目录位于 PATH 上，你就可以直接运行 apothem <command>，无需手动设置 PYTHONPATH。

验证：

apothem verify --harness claude-code

# or, before the shim is on PATH, from the bundled source:
PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

4. VS Code 系扩展Copy Anchor Link

前置条件： VS Code、Node.js 18+，以及 PATH 上的系统 Python 3.10+。

Apothem for VS Code 扩展已上架于 Visual Studio Marketplace，标识符为 ahmed-g-gad.apothem-vscode：可从扩展视图安装，或运行 code --install-extension ahmed-g-gad.apothem-vscode。它也可以通过 apothem.vsix 包安装：运行 code --install-extension apothem.vsix，或使用编辑器的 Install from VSIX… 命令。发布工作流会为该包签名，并将其附加到每个 GitHub Release。在该工作流开始打包扩展之前就已发布的各个版本不含 .vsix；当最新的发布版本缺少它时，请使用锁定在 tools/vsce/ 中的 vsce 版本从检出目录构建该包（该 vsce 版本需要 Node.js 22 或更高版本）：先运行 npm ci --prefix tools/vsce --ignore-scripts，然后运行 cd vscode-extension && ../tools/vsce/node_modules/.bin/vsce package --no-dependencies --out apothem.vsix。通过较早的 apothem.vsix 安装的副本，标识符为 ahmed-g-gad.apothem；请将其卸载（code --uninstall-extension ahmed-g-gad.apothem），以免两个副本同时注册相同的命令。一个扩展即可覆盖 VS Code 系的各个编辑器。它的命令面板命令（Apothem: Install、Verify、Update、Uninstall、Doctor）通过所配置的运行器运行同一个引擎（默认为 npx @ahmed-g-gad/apothem@<extension version>，因此扩展运行的是它随附发布的引擎版本；将用户设置 apothem.runner 指向本地检出即可从源码运行）。Install、Verify、Update 和 Uninstall 会询问要作用于哪个工具，并优先提供编辑器自身对应的工具；all 是一个选项，但绝不是默认值。apothem.runner 设置的作用域为机器级，因此工作区无法更改它，并且该扩展只在受信任的工作区中运行。

验证： 从编辑器的命令面板运行 Apothem: Verify 命令，或从终端运行：

npx @ahmed-g-gad/apothem verify --harness claude-code

5. 命令行引导（扩展宿主）Copy Anchor Link

前置条件： 其宿主命令行工具、Node.js 18+，以及 PATH 上的系统 Python 3.10+。

直接从仓库将 Apothem 作为扩展安装——该命令带有确切的宿主和工具 slug：

gemini extensions install https://github.com/ahmed-g-gad/apothem

该扩展是一个引导入口，其本身并不是完整安装：它加载一个 Apothem 上下文文件，并添加一个通过 shell 调用引擎（npx @ahmed-g-gad/apothem）的 /apothem 命令。通过它运行安装来物化完整工具配置：

npx @ahmed-g-gad/apothem install --harness gemini-cli --project .

验证：

npx @ahmed-g-gad/apothem verify --harness gemini-cli --project .

6. 命令行引导（qwen-code 宿主）Copy Anchor Link

前置条件： 其宿主命令行工具、Node.js 18+，以及 PATH 上的系统 Python 3.10+。

直接从仓库将 Apothem 作为 --harness qwen-code 扩展安装：

qwen extensions install ahmed-g-gad/apothem

与渠道 5 的扩展一样，这是一个引导入口：它加载一个 Apothem 上下文文件，并通过 shell 调用引擎。通过它运行安装来物化完整工具配置：

npx @ahmed-g-gad/apothem install --harness qwen-code

验证：

npx @ahmed-g-gad/apothem verify --harness qwen-code

7. 命令行引导（插件宿主）Copy Anchor Link

前置条件： 其宿主命令行工具、Node.js 18+，以及 PATH 上的系统 Python 3.10+。

将仓库添加为插件市场，然后安装插件——该命令带有确切的宿主和工具 slug：

codex plugin marketplace add ahmed-g-gad/apothem --sparse .agents/plugins --sparse plugins/apothem
codex plugin add apothem@apothem

这两个 --sparse 路径只获取插件市场清单和插件本身，而不是整个仓库；在较慢的磁盘上（例如 WSL 下的 Windows 驱动器），完整克隆可能超出宿主 30 秒的克隆时限。

与渠道 5 和渠道 6 的扩展一样，这是一个通过 shell 调用引擎的引导入口。该插件随附一个入口技能；其清单是根目录下的 plugin.json，插件宿主的工具页面介绍了其布局以及插件留给引擎处理的部分。通过它运行安装来物化完整工具配置：

npx @ahmed-g-gad/apothem install --harness codex

验证：

npx @ahmed-g-gad/apothem verify --harness codex

8. 直接引擎（python -m apothem）Copy Anchor Link

前置条件： 系统 Python 3.10+，且 click 和 rich 包可导入，外加该仓库的一份检出。不需要 Node.js。

直接从克隆中运行引擎。入口点会将 vendored 依赖（src/apothem/_vendor）放到 sys.path 上，因此只要 click 和 rich 可导入，PYTHONPATH=src 就是全部的设置：

git clone https://github.com/ahmed-g-gad/apothem
cd apothem
PYTHONPATH=src python -m apothem install --harness claude-code

与 npm 垫片一样，在没有配置档案的机器上，第一次 install 会在 ~/.config/apothem/profile.yaml 创建起始配置档案并继续执行。

验证：

PYTHONPATH=src python -m apothem verify --harness claude-code

验证任何安装Copy Anchor Link

上面每条渠道都指明了自己的验证命令。两种通用形式是：

PYTHONPATH="$HOME/.apothem/src" python -m apothem verify --harness claude-code

npx @ahmed-g-gad/apothem verify --harness claude-code

将工具名称替换为你所安装的适配器；所有受支持的名称见工具列表。要一次检查每个已安装的适配器（其验证及其钩子命令），请在你上面所用的同一种形式中，将 verify --harness NAME 换成 doctor 来运行：apothem doctor、PYTHONPATH="$HOME/.apothem/src" python -m apothem doctor 或 npx @ahmed-g-gad/apothem doctor。对于插件路径，在 Claude Code 内运行 /plugin 并确认 apothem 显示为已安装。

前置条件一览Copy Anchor Link

• Python 3.10 或更高版本——负责查找它的各条路径都是按名称查找的，而且名称因路径而异。npm 垫片依次尝试 python3、python，然后是 py -3。安装器会尝试 python3、python，以及带版本号的名称，从 python3.14 一直到 python3.10。
• click 和 rich 可导入（在该解释器下）——这是引擎没有 vendor 的两个面向终端的依赖。安装器会检查这两者，指出任何缺失项，并提出为你安装——经你确认后安装，或通过 --yes（在 PowerShell 上为 -Yes）或 APOTHEM_AUTO_INSTALL_DEPS=1 自动安装。在其他每条渠道上，缺失的包会使引擎以一个错误停止（退出码 1），该错误会针对它找到的解释器给出确切的命令，并附带 Apothem 经过测试的版本约束（<interpreter> -m pip install "click==…" "rich>=…"）；使用 --json 时，同一错误会以代码为 runtime.dependency_missing 的 JSON 信封形式返回。
• Node.js 18 或更高版本——仅限运行 npx 的路径：npm 垫片（2）、VS Code 系扩展（4）以及命令行引导（5–7）。
• 生命周期已终止的运行时。 Python 3.10 于 2026-10-01 到达上游生命周期终止，Node.js 18 和 20 分别于 2025-04-30 和 2026-04-30 到达。Apothem 仍将它们作为其声明的下限予以支持，并在 CI 中逐一测试，但它们不再获得上游安全修复，因此请优先选用 Python 3.11 或更新版本以及 Node.js 22 或更新版本。运行时下限策略说明了下限如何提高。
• Git——仅安装器路径需要，且仅用于网络形式（脚本会克隆源码；本地检出无需克隆）。
• Claude Code——仅插件路径需要。VS Code 以及每个命令行引导各自的宿主工具，仅在其各自的渠道（4–7）中需要。

后续指南Copy Anchor Link