agent-package-manager

Agent Package Manager

流程

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

1. 检查仓库根目录中是否有 apm.yml、apm.lock.yaml、.github/、.claude/、.codex/、.cursor/、.gemini/、.grok/、.opencode/、.windsurf/、.kiro/ 和 apm_modules/。
2. 执行 apm --version 和 apm config，确认已安装的 CLI 和当前配置。
3. 如果存在 apm.yml，请先阅读 references/manifest-and-lockfile.md，再更改依赖项、脚本或编译设置。
4. 如果请求涉及安装、更新、清理或移除软件包，请先阅读 references/command-workflows.md，再执行 APM 命令。
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/web-ai-agent-skills/skills/webmcp；仅在必要时保留显式的 path、ref 和 alias。
5. 当可复现性比自动跟进更新更重要时，为团队共享的软件包使用固定的 ref。
6. 仅在本地开发仍在进行时保留本地路径依赖。建议分发捆绑包前，请将其替换为远程引用。
7. 如果请求包含脚本，请在 scripts 下定义，并通过 apm list、apm preview 或 apm run 验证每个脚本都可以预览或执行。 步骤 3：通过验证管理依赖，而非凭猜测
8. 如果仓库中已安装软件包，请使用 apm install --dry-run、apm uninstall --dry-run 或 apm prune --dry-run 预览有风险的更改。
9. 根据请求范围，使用 apm install、apm install <package>、apm install --update 或 apm deps update 安装或更新软件包。
10. 运行 apm install --update 或 apm deps update 后，请确认锁文件中的 resolved_commit 确实发生了变化。如果软件包来自过期缓存，请按照 references/troubleshooting.md 中的“更新后软件包过期”工作流处理。
11. 如果请求是从某个仓库安装单个 skill，请提供具体到该 skill 目录的软件包路径，而不是含糊的仅仓库占位符，例如 apm install webmaxru/web-ai-agent-skills/skills/webmcp。
12. 更改依赖后，使用 apm deps list、apm deps tree 或 apm deps info <package> 验证解析后的状态。
13. 将 apm.lock.yaml 视为已解析提交和已部署文件的事实来源。建议提交该文件，以确保团队和 CI 的可复现性。
14. 如果仓库需要发现或选择 MCP，请先使用 apm mcp list、apm mcp search <query> 和 apm mcp show <server>，再手动编辑 MCP 条目。
15. 如果安装输出报告冲突或跳过的文件，请先阅读 references/troubleshooting.md，再尝试使用强制选项重试。
16. 如果仓库使用来自自身的软件包（自引用依赖），请提醒用户，必须先提交并推送更改，APM 才能获取这些内容。请阅读 references/troubleshooting.md 中的“自引用依赖”部分。
17. 请注意，apm install 会在部署前扫描软件包中的安全威胁，包括隐藏 Unicode 字符和内容哈希验证。默认情况下，它还会阻止传递依赖中的 MCP 服务，除非这些服务已在 dependencies.mcp 中明确声明或受信任；无需选择加入。如果扫描发出警告或阻止安装，请处理被标记的内容，而不要绕过检查。
18. 如果仓库所属组织强制执行 apm-policy.yml，则会在安装时应用策略，并可在默认的传递依赖 MCP 阻止规则之上增加进一步限制，包括限制依赖来源。如果策略阻止了安装，请检查策略文件或联系组织管理员；不要尝试绕过强制执行。

步骤 4：仅在有帮助时编译和验证

1. 更改编译策略或目标选择之前，请阅读 references/command-workflows.md。
2. 如果目标是确保原语正确，而非生成输出，请使用 apm compile --validate 进行验证。
3. 进行大规模编译更改或检查放置决策时，请先使用 apm compile --dry-run。
4. 请说明，apm install 已会为受支持的工具部署提示词、Agent、skills、钩子和 MCP 集成；apm compile 主要用于生成 AGENTS.md 或 CLAUDE.md 等指令文件。
5. 如果仓库服务于多个运行时或工具系列，请使用明确的目标。
6. 让 compilation.exclude 与构建目录和依赖目录保持一致，避免编译时重新扫描生成的输出。
7. 如果项目在编写期间需要持续重新生成内容，只有在一次性验证流程通过后，才使用 apm compile --watch。 第 5 步：专业地运行脚本、管理运行时和分发流程
8. 在调用项目脚本前，先使用 apm list 列出脚本。
9. 在自动化或调试工作流中使用 apm run <script> -p key=value 前，先使用 apm preview <script> -p key=value 预览由提示词驱动的脚本。
10. 如果仓库依赖 APM 管理的运行时，请使用 apm runtime status、apm runtime list 和 apm runtime setup <runtime>。
11. 如果目标是 CI 扇出、气隙环境交付或发布可追溯性，请阅读 references/command-workflows.md；只有在成功安装并生成 apm.lock.yaml 和已部署文件后，才使用 apm pack。
12. 仅将 apm unpack 用于提取先前打包的内容，不要将其作为编写依赖的替代方案。
13. 如果重复安装造成了本可避免的 CI 成本或网络风险，请推荐 apm-action 或预构建包。

错误处理

• 如果缺少 apm，请先安装或更新，然后使用 apm --version 验证，再编辑项目文件。
• 如果组织策略（apm-policy.yml）阻止了 apm install，不要绕过策略；请报告阻止情况，并请求管理员调整策略或将该依赖加入允许列表。
• 如果 apm install 报告身份验证失败，请阅读 references/troubleshooting.md，修复主机身份验证后再重试。
• 如果 apm install 报告文件冲突，请检查诊断摘要；必要时使用 --verbose 重试，并且仅在明确需要覆盖本地文件时使用 --force。
• 如果用户的工具链不需要 apm compile，请避免将其作为无谓工作添加；优先采用更轻量的仅安装流程。
• 如果 apm pack 因缺少 apm.lock.yaml 或缺少已部署文件而失败，请重新运行 apm install 后再试。
• 如果仓库依赖本地路径包，在这些依赖被替换为远程引用之前，不要推荐 apm pack。