agent-package-manager

Agent Package Manager

操作流程

第 1 步：评估仓库和所需的 APM 结果

1. 检查仓库根目录中是否存在 apm.yml、apm.lock.yaml、.github/、.claude/、.cursor/、.opencode/ 和 apm_modules/。
2. 执行 apm --version 和 apm config，确认已安装的 CLI 和当前配置。
3. 如果存在 apm.yml，请在更改依赖项、脚本或编译设置前阅读 references/manifest-and-lockfile.md。
4. 如果请求涉及安装、更新、清理或移除软件包，请在执行 APM 命令前阅读 references/command-workflows.md。
5. 如果不存在 apm.yml，且用户希望在仓库中使用 APM，请通过 apm init 或 apm init --yes 初始化项目。
6. 如果仓库已使用其他 Agent 配置流程，且用户未要求迁移，请将更改限制在所请求的 APM 范围内，而不是替换现有设置。

第 2 步：有针对性地构建或修复清单

1. 如果仓库需要全新或修复后的清单结构，请阅读 assets/apm.yml.template。
2. 确保顶层包含 name 和 version；这两个字段是必需的约定字段。
3. 在 dependencies.apm 下添加 APM 软件包依赖项，在 dependencies.mcp 下添加 MCP 服务。
4. 安装后，优先在 apm.yml 中使用规范的依赖项格式。GitHub 托管的技能和软件包默认使用仓库简写 owner/repo/path，例如 webmaxru/agent-skills/skills/webmcp；仅在必要时保留显式的 path、ref 和 alias。
5. 如果可复现性比自动变更更重要，请为团队共享的软件包使用固定的 ref。
6. 仅在本地开发仍在进行时保留本地路径依赖。建议分发捆绑包前，请将其替换为远程引用。
7. 如果请求包含脚本，请在 scripts 下定义，并通过 apm list、apm preview 或 apm run 验证每个脚本均可预览或执行。

第 3 步：通过验证而非猜测来管理依赖项

1. 如果仓库已有已安装的软件包，请使用 apm install --dry-run、apm uninstall --dry-run 或 apm prune --dry-run 预览有风险的更改。
2. 根据请求范围，使用 apm install、apm install <package>、apm install --update 或 apm deps update 安装或更新软件包。
3. 运行 apm install --update 或 apm deps update 后，请确认锁文件中的 resolved_commit 确实发生了变化。如果软件包来自过期缓存，请按照 references/troubleshooting.md 中的“更新后软件包过期”工作流程操作。
4. 如果请求是从某个仓库安装单个技能，请将软件包路径指定到该技能目录，而不是使用含糊的仅含仓库名的占位符，例如 apm install webmaxru/agent-skills/skills/webmcp。
5. 更改依赖项后，使用 apm deps list、apm deps tree 或 apm deps info <package> 验证解析后的状态。
6. 将 apm.lock.yaml 视为已解析提交和已部署文件的唯一事实来源。建议提交该文件，以确保团队和 CI 的可复现性。
7. 如果仓库需要发现或选择 MCP 服务，请使用 apm mcp list、apm mcp search <query> 和 apm mcp show <server>，然后再手动编辑 MCP 条目。
8. 如果安装输出报告文件冲突或跳过了文件，请在使用强制选项重试前阅读 references/troubleshooting.md。
9. 如果仓库使用自身提供的软件包（自引用依赖），请提醒用户必须先提交并推送更改，APM 才能获取这些软件包。请阅读 references/troubleshooting.md 中的“自引用依赖”部分。 步骤 4：仅在有价值时编译和验证
10. 在更改编译策略或目标选择前，阅读 references/command-workflows.md。
11. 如果目标是确保正确性而非生成输出，使用 apm compile --validate 验证原语。
12. 在进行大规模编译更改前，或检查放置决策时，使用 apm compile --dry-run。
13. 说明 apm install 已经会为受支持的工具部署提示词、Agent、技能、钩子和 MCP 集成；apm compile 的主要用途是生成 AGENTS.md 或 CLAUDE.md 等指令文件。
14. 如果仓库服务于多个运行时或工具系列，请使用显式目标。
15. 让 compilation.exclude 与构建目录和依赖目录保持一致，以免编译重新扫描生成的输出。
16. 如果项目在编写期间需要持续重新生成，只有在一次性验证流程通过后才使用 apm compile --watch。

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

1. 调用脚本前，使用 apm list 列出项目脚本。
2. 在自动化或调试工作流中使用 apm run <script> -p key=value 前，先使用 apm preview <script> -p key=value 预览由提示词驱动的脚本。
3. 如果仓库依赖 APM 管理的运行时，请使用 apm runtime status、apm runtime list 和 apm runtime setup <runtime>。
4. 如果目标是 CI 扇出、隔离网络环境下的交付或发布可追溯性，请阅读 references/command-workflows.md，并且仅在成功安装并生成 apm.lock.yaml 和已部署文件后使用 apm pack。
5. 仅在需要增量提取之前打包的捆绑包时使用 apm unpack。不要将其说成是依赖项编写的替代方案。
6. 如果重复安装造成了本可避免的 CI 成本或网络风险，建议使用 apm-action 或预构建捆绑包。

错误处理

• 如果缺少 apm，请先安装或更新，然后在编辑项目文件前使用 apm --version 验证。
• 如果 apm install 报告身份验证失败，请阅读 references/troubleshooting.md，先修复主机身份验证，再重试。
• 如果 apm install 报告文件冲突，请检查诊断摘要；必要时使用 --verbose 重试，并且仅在明确需要覆盖本地文件时使用 --force。
• 如果用户的工具链不需要 apm compile，请避免将其作为无意义的额外工作；优先采用更轻量的仅安装流程。
• 如果 apm pack 因缺少 apm.lock.yaml 或缺少已部署文件而失败，请重新运行 apm install 后再重试。
• 如果仓库依赖本地路径包，在将这些依赖替换为远程引用前，不要建议使用 apm pack。