agent-package-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Package Manager

Procedures

操作流程

Step 1: Assess the repository and the requested APM outcome

Inspect the repository root for

apm.yml

apm.lock.yaml

.github/

.claude/

.cursor/

.opencode/

, and

apm_modules/

Execute
```
apm --version
```
and
```
apm config
```
to confirm the installed CLI and current configuration.
If
```
apm.yml
```
exists, read
```
references/manifest-and-lockfile.md
```
before changing dependencies, scripts, or compilation settings.
If the request is about package installation, updates, pruning, or removal, read
```
references/command-workflows.md
```
before executing APM commands.
If no
```
apm.yml
```
exists and the user wants APM in the repository, initialize the project with
```
apm init
```
or
```
apm init --yes
```
.
If the repository already uses another agent configuration flow and the user did not ask to migrate it, limit the change to the requested APM scope instead of replacing the existing setup.

Step 2: Shape or repair the manifest deliberately

Read
```
assets/apm.yml.template
```
when the repository needs a fresh or repaired manifest structure.
Keep
```
name
```
and
```
version
```
present at the top level; treat them as required contract fields.
Add APM package dependencies under
```
dependencies.apm
```
and MCP servers under
```
dependencies.mcp
```
.
Prefer canonical dependency forms in
```
apm.yml
```
after installation. Default to the repository shorthand
```
owner/repo/path
```
for GitHub-hosted skills and packages, for example
```
webmaxru/agent-skills/skills/webmcp
```
, and preserve explicit
```
path
```
,
```
ref
```
, and
```
alias
```
only when they are needed.
Use pinned refs for shared team packages when reproducibility matters more than automatic drift.
Keep local path dependencies only for active local development. Replace them with remote references before recommending bundle distribution.
If the request includes scripts, define them under
```
scripts
```
and verify that each script can be previewed or executed through
```
apm list
```
,
```
apm preview
```
, or
```
apm run
```
.

Step 3: Manage dependencies with verification, not guesswork

Preview risky changes with
```
apm install --dry-run
```
,
```
apm uninstall --dry-run
```
, or
```
apm prune --dry-run
```
when the repository already has installed packages.
Install or update packages with
```
apm install
```
,
```
apm install <package>
```
,
```
apm install --update
```
, or
```
apm deps update
```
according to the requested scope.
After running
```
apm install --update
```
or
```
apm deps update
```
, verify the lockfile
```
resolved_commit
```
actually changed. If packages were served from a stale cache, follow the "Stale packages after update" workflow in
```
references/troubleshooting.md
```
.
When the request is to install a single skill from a repository, provide the package path down to that skill directory instead of a vague repo-only placeholder, for example
```
apm install webmaxru/agent-skills/skills/webmcp
```
.
Verify the resolved state with
```
apm deps list
```
,
```
apm deps tree
```
, or
```
apm deps info <package>
```
after dependency changes.
Treat
```
apm.lock.yaml
```
as the source of truth for resolved commits and deployed files. Recommend committing it for team and CI reproducibility.
If the repository needs MCP discovery or selection, use
```
apm mcp list
```
,
```
apm mcp search <query>
```
, and
```
apm mcp show <server>
```
before editing MCP entries by hand.
If installation output reports collisions or skipped files, read
```
references/troubleshooting.md
```
before retrying with forceful options.
If the repository consumes packages from itself (self-referencing dependency), remind the user that changes must be committed and pushed before APM can fetch them. Read
```
references/troubleshooting.md
```
for the "Self-referencing dependencies" section.

Step 4: Compile and validate only when it adds value

Read
```
references/command-workflows.md
```
before changing compilation strategy or target selection.
Use
```
apm compile --validate
```
to validate primitives when the goal is correctness rather than output generation.
Use
```
apm compile --dry-run
```
before large compilation changes or when checking placement decisions.
Explain that
```
apm install
```
already deploys prompts, agents, skills, hooks, and MCP integrations for supported tools;
```
apm compile
```
mainly exists to generate instruction files such as
```
AGENTS.md
```
or
```
CLAUDE.md
```
.
Use explicit targets when the repository serves more than one runtime or tool family.
Keep
```
compilation.exclude
```
aligned with build and dependency directories so compilation does not re-scan generated output.
If the project needs continuous regeneration during authoring, use
```
apm compile --watch
```
only after the one-shot validation path is clean.

Step 5: Operate scripts, runtimes, and distribution flows professionally

List project scripts with
```
apm list
```
before invoking them.
Preview prompt-driven scripts with
```
apm preview <script> -p key=value
```
before using
```
apm run <script> -p key=value
```
in an automation or debugging workflow.
Use
```
apm runtime status
```
,
```
apm runtime list
```
, and
```
apm runtime setup <runtime>
```
when the repository depends on an APM-managed runtime.
If the goal is CI fan-out, air-gapped delivery, or release traceability, read
```
references/command-workflows.md
```
and use
```
apm pack
```
only after a successful install has produced
```
apm.lock.yaml
```
and deployed files.
Use
```
apm unpack
```
only for additive extraction of a previously packed bundle. Do not present it as a replacement for dependency authoring.
Recommend
```
apm-action
```
or a prebuilt bundle when repeated installs create avoidable CI cost or network risk.

步骤1：评估代码仓库和所需的APM操作目标

检查仓库根目录下是否存在

apm.yml

、

apm.lock.yaml

、

.github/

、

.claude/

、

.cursor/

、

.opencode/

和

apm_modules/

。

执行
```
apm --version
```
和
```
apm config
```
确认已安装的CLI版本和当前配置。
如果存在
```
apm.yml
```
，在修改依赖、脚本或编译设置前请先阅读
```
references/manifest-and-lockfile.md
```
。
如果需求是关于包的安装、更新、修剪或移除，在执行APM命令前请先阅读
```
references/command-workflows.md
```
。
如果不存在
```
apm.yml
```
且用户需要在仓库中使用APM，使用
```
apm init
```
或
```
apm init --yes
```
初始化项目。
如果仓库已经使用其他agent配置流程，且用户没有要求迁移，仅在请求的APM范围内进行修改，不要替换现有配置。

步骤2：谨慎构建或修复清单文件

当仓库需要全新的或修复后的清单结构时，参考
```
assets/apm.yml.template
```
。
顶层必须保留
```
name
```
和
```
version
```
字段，将其视为必填的协议字段。
在
```
dependencies.apm
```
下添加APM包依赖，在
```
dependencies.mcp
```
下添加MCP服务器依赖。
安装后优先使用
```
apm.yml
```
中的规范依赖格式。对于GitHub托管的skill和包，默认使用仓库简写形式
```
owner/repo/path
```
，例如
```
webmaxru/agent-skills/skills/webmcp
```
，仅在必要时保留显式的
```
path
```
、
```
ref
```
和
```
alias
```
。
当可复现性比自动更新更重要时，对团队共享的包使用固定的ref版本。
仅在活跃的本地开发阶段保留本地路径依赖，在推荐分发包之前将其替换为远程引用。
如果需求包含脚本，在
```
scripts
```
下定义它们，并验证每个脚本都可以通过
```
apm list
```
、
```
apm preview
```
或
```
apm run
```
预览或执行。

步骤3：通过验证而非猜测管理依赖

当仓库已经安装了包时，使用
```
apm install --dry-run
```
、
```
apm uninstall --dry-run
```
或
```
apm prune --dry-run
```
预览高风险变更。

根据需求范围，使用

apm install

、

apm install <package>

、

apm install --update

或

apm deps update

安装或更新包。

运行
```
apm install --update
```
或
```
apm deps update
```
后，验证锁文件中的
```
resolved_commit
```
确实发生了变更。如果包是从过期缓存中拉取的，按照
```
references/troubleshooting.md
```
中的“更新后包过期”流程处理。
如果需求是从仓库安装单个skill，提供到该skill目录的完整包路径，而不是模糊的仅仓库占位符，例如
```
apm install webmaxru/agent-skills/skills/webmcp
```
。
依赖变更后，使用
```
apm deps list
```
、
```
apm deps tree
```
或
```
apm deps info <package>
```
验证解析后的状态。
将
```
apm.lock.yaml
```
视为已解析提交和部署文件的事实来源，建议提交该文件以保证团队和CI环境的可复现性。
如果仓库需要发现或选择MCP，在手动编辑MCP条目之前，使用
```
apm mcp list
```
、
```
apm mcp search <query>
```
和
```
apm mcp show <server>
```
操作。
如果安装输出报告冲突或跳过文件，在使用强制选项重试前阅读
```
references/troubleshooting.md
```
。
如果仓库引用自身的包（自引用依赖），提醒用户必须先提交并推送变更，APM才能拉取到这些变更。可阅读
```
references/troubleshooting.md
```
中的“自引用依赖”部分。

步骤4：仅在有价值时进行编译和校验

在修改编译策略或目标选择前阅读
```
references/command-workflows.md
```
。
当目标是校验正确性而非生成输出时，使用
```
apm compile --validate
```
校验基础资源。
在进行大的编译变更或检查文件放置规则前，使用
```
apm compile --dry-run
```
。
说明
```
apm install
```
已经为支持的工具部署了提示词、agents、skills、钩子和MCP集成；
```
apm compile
```
主要用于生成说明文件，例如
```
AGENTS.md
```
或
```
CLAUDE.md
```
。
当仓库支持多个运行时或工具家族时，使用显式目标。
保持
```
compilation.exclude
```
与构建和依赖目录对齐，避免编译过程重复扫描生成的输出文件。
如果项目在编写过程中需要持续重新生成，仅在单次校验路径无问题后再使用
```
apm compile --watch
```
。

步骤5：专业运维脚本、运行时和分发流程

调用项目脚本前，使用
```
apm list
```
列出所有脚本。
在自动化或调试工作流中使用
```
apm run <script> -p key=value
```
前，使用
```
apm preview <script> -p key=value
```
预览提示词驱动的脚本。

当仓库依赖APM管理的运行时时，使用

apm runtime status

、

apm runtime list

和

apm runtime setup <runtime>

。

如果目标是CI分流、离线交付或发布可追溯性，阅读
```
references/command-workflows.md
```
，仅在成功安装生成
```
apm.lock.yaml
```
和部署文件后再使用
```
apm pack
```
。
仅对之前打包的bundle进行增量提取时使用
```
apm unpack
```
，不要将其作为依赖编写的替代方案。
当重复安装会产生不必要的CI成本或网络风险时，推荐使用
```
apm-action
```
或预构建的bundle。

Error Handling

错误处理

If
```
apm
```
is missing, install or update it first, then verify with
```
apm --version
```
before editing project files.
If
```
apm install
```
reports authentication failures, read
```
references/troubleshooting.md
```
and fix host authentication before retrying.
If
```
apm install
```
reports file collisions, inspect the diagnostic summary, retry with
```
--verbose
```
when needed, and use
```
--force
```
only when overwriting local files is clearly intended.
If
```
apm compile
```
is unnecessary for the user’s toolchain, avoid adding it as busywork; prefer the lighter install-only path.
If
```
apm pack
```
fails because
```
apm.lock.yaml
```
is missing or deployed files are absent, rerun
```
apm install
```
before retrying.
If the repository depends on local path packages, do not recommend
```
apm pack
```
until those dependencies are replaced with remote references.

如果缺少
```
apm
```
，先安装或更新它，然后用
```
apm --version
```
验证后再编辑项目文件。
如果
```
apm install
```
报告认证失败，阅读
```
references/troubleshooting.md
```
，修复主机认证后再重试。
如果
```
apm install
```
报告文件冲突，检查诊断摘要，必要时使用
```
--verbose
```
重试，仅在明确要覆盖本地文件时才使用
```
--force
```
。
如果用户的工具链不需要
```
apm compile
```
，不要增加多余的操作，优先使用更轻量的仅安装路径。
如果因为缺少
```
apm.lock.yaml
```
或部署文件导致
```
apm pack
```
失败，重新运行
```
apm install
```
后再重试。
如果仓库依赖本地路径包，在将这些依赖替换为远程引用之前，不要推荐使用
```
apm pack
```
。