1. 项目简介

Agent Powerups 是一个面向编码智能体（coding agents）的可重用技能集合，采用与 Oh My Zsh 相似的设计理念。该项目旨在为各种编码智能体（如 Codex、Claude Code、 Gemini）提供标准化的技能、命令、配置和工作流扩展方案。

1.1 核心定位

1.2 主要交付物

项目当前版本包含以下核心交付物：

• 可复用技能（Skills）：23个预置技能，涵盖调试、代码审查、数据工程等领域
• CLI 工具（apx）：本地安全命令行工具，支持智能体检查和安装
• MCP 配置：本地优先的 GitHub MCP 配置及检查流程
• AGENTS.md 模板：5种项目类型的起始模板
• 命令包：2个预置命令包
• Hook 示例：3个钩子示例
• 17个插件包：3个稳定版、10个测试版、4个实验版
• 2个工作流：特性迭代和智能体中继

资料来源：[README.md:85-115]

2. 核心架构

2.1 系统架构图

graph TD
    A[用户/智能体] --> B[apx CLI 工具]
    B --> C[目录服务 CatalogService]
    C --> D[技能存储 skills/]
    C --> E[插件存储 plugins/]
    C --> F[命令存储 commands/]
    C --> G[Hook 存储 hooks/]
    C --> H[MCP 配置 mcp/]
    C --> I[AGENTS.md 模板 agents-md/]
    
    B --> J[setup 命令]
    B --> K[check 命令]
    B --> L[doctor 命令]
    B --> M[security-audit 命令]
    B --> N[plugins 命令]
    
    J --> O[目标智能体环境]
    K --> P[需求检查]
    M --> Q[安全扫描]

2.2 CLI 命令体系

apx 是项目的核心命令行工具，提供以下主要命令：

资料来源：[src/cli/apx.ts:1-30]

2.3 目录结构

agent-powerups/
├── skills/                    # 可复用技能目录
│   ├── systematic-debugging/
│   ├── writing-plans/
│   ├── dbt-preflight/
│   └── ... (23个技能)
├── agents-md/                 # AGENTS.md 模板
│   ├── typescript-app/
│   ├── python-library/
│   └── ...
├── commands/                   # 命令包
│   ├── ship-check/
│   └── using-powerups-command/
├── hooks/                     # 钩子示例
│   ├── no-secrets-preflight/
│   ├── handoff-summary/
│   └── validation-required/
├── mcp/                       # MCP 配置
│   └── github-local/
├── workflows/                 # 工作流
│   ├── feature-iteration/
│   └── agent-relay/
├── plugins/                   # 插件包 (17个)
│   ├── dev-vitals/           # 稳定版
│   ├── debugging-diagnostics/
│   ├── quality-gates/
│   └── ... (beta/experimental)
└── scripts/                   # 验证脚本
    ├── validate-skills.py
    ├── validate-catalog.py
    └── check-requirements.py

3. 技能系统

3.1 技能定义

技能是 Agent Powerups 的核心交付单元，每个技能是一个独立的工作流或方法论，通过 SKILL.md 文件定义。

graph LR
    A[SKILL.md] --> B[frontmatter 元数据]
    A --> C[技能说明]
    A --> D[使用步骤]
    A --> E[支持文件引用]
    
    B --> B1[name 名称]
    B --> B2[description 描述]
    B --> B3[tags 标签]
    B --> B4[requires 依赖]

资料来源：[src/cli/commands/doctor.ts:15-30]

3.2 预置技能分类

资料来源：[README.md:85-95]

3.3 技能验证机制

项目提供多层次的技能验证：

1. 结构验证：检查 SKILL.md 文件是否存在
2. 元数据验证：确保 frontmatter 包含必需的 name 和 description 字段
3. 引用验证：检查技能中引用的支持文件是否存在
4. 目录验证：确保技能目录下文件结构完整

// 验证逻辑伪代码
if (!frontmatter?.name || !frontmatter?.description) {
  issues.push(`${entry.name}: missing required frontmatter`);
}

for (const ref of referencedSupportFiles(content)) {
  if (!(await supportRefExists(skillDir, ref))) {
    issues.push(`${entry.name}: missing referenced support file ${ref}`);
  }
}

资料来源：[src/cli/commands/doctor.ts:20-40]

4. 插件系统

4.1 插件包结构

插件包采用多智能体兼容结构：

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json      # Claude Code 清单
├── .codex-plugin/
│   └── plugin.json      # Codex 清单
├── skills/
│   └── <skill-name>/
│       └── SKILL.md
├── agents/
│   └── <agent-name>.md
└── commands/
    └── <command-name>.md

资料来源：[plugins/README.md:20-35]

4.2 插件状态分类

资料来源：[README.md:110-120]

4.3 插件操作命令

apx plugins list                                    # 列出所有插件
apx plugins info <name>                             # 查看插件详情
apx plugins validate --all                          # 验证所有插件结构
apx plugins install <name> --target codex --dry-run # 预览安装
apx plugins install <name> --target claude-code     # 安装到 Claude Code

5. 安装与配置

5.1 安装模式

apx setup 命令支持三种安装模式：

资料来源：[src/cli/commands/setup.ts:15-50]

5.2 目标智能体支持

apx setup codex --mode recommended --yes      # 安装到 Codex
apx setup claude-code --mode recommended --yes # 安装到 Claude Code
apx setup gemini --mode recommended --yes     # 安装到 Gemini

5.3 安装流程

graph TD
    A[apx setup <target>] --> B{检查 AGENTS.md 存在?}
    B -->|存在| C[创建备份]
    B -->|不存在| D[写入 instructions/agent-powerups.md]
    C --> E[追加 agent-powerups 块]
    E --> F[复制资源到 agent-powerups/]
    F --> G[更新全局指令]
    D --> G
    G --> H[安装完成]

资料来源：[src/cli/commands/setup.ts:80-120]

6. 安全模型

6.1 安全扫描规则

apx security-audit 命令实现多层次安全扫描：

资料来源：[src/cli/commands/security-audit.ts:1-30]

6.2 安全检查范围

const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".worktrees", ".plugins"]);
const SCAN_EXTS = new Set([".json", ".toml", ".md", ".sh", ".ps1", ".yaml", ".yml"]);
const MAX_FILE_BYTES = 512 * 1024;

扫描跳过以下目录和文件：

• node_modules、dist、.git 等标准构建目录
• 单文件大小限制为 512KB
• 仅扫描特定扩展名文件

6.3 安全警告

⚠️ 重要提示：在将资源加载到受信任的智能体环境之前，务必审查所有资产。

- 技能可能指示智能体读取本地文件或执行命令

- 钩子可能在宿主智能体支持时执行代码

- MCP 配置可能扩展工具访问权限

- 安装命令可能修改本地环境

- 除非严格必要，否则不应将密钥粘贴到智能体上下文中

资料来源：[README.md:125-135]

7. 验证与诊断

7.1 doctor 命令检查项

apx doctor 提供全面的环境诊断：

资料来源：[src/cli/commands/doctor.ts:1-60]

7.2 check 命令功能

interface CheckResult {
  exitCode: number;        // 0=成功, 1=失败
  output: string;          // 输出信息
  warnings: string[];      // 警告列表
  actions: string[];       // 建议操作
}

check 命令支持：

• 批量检查多个资产
• 验证依赖项状态
• 自动安装缺失依赖（可选）

资料来源：[src/cli/commands/check.ts:1-30]

8. 兼容性矩阵

9. 快速开始

9.1 环境准备

# 安装依赖
npm install
npm run build
npm link

# 验证安装
apx doctor

9.2 基本工作流

# 1. 浏览目录
apx list
apx info markitdown-file-intake

# 2. 验证资源
apx commands run ship-check
apx hooks run no-secrets-preflight --all

# 3. MCP 检查
apx mcp check github-local --target generic
apx mcp smoke github-local --json

# 4. 安装到智能体
apx setup codex --dry-run
apx setup codex --mode recommended --yes

9.3 本地智能体咨询

apx ask-codex "Return OK only" --json
apx ask-claude "Return OK only" --json
apx ask-gemini "Return OK only" --json

10. 总结

Agent Powerups 项目为编码智能体提供了一个标准化、可扩展的技能和工具集合。其核心价值包括：

• 模块化设计：技能、插件、命令独立存在，易于组合使用
• 多智能体支持：统一接口支持 Codex、Claude Code、 Gemini
• 本地优先：所有资源本地存储，保证数据隐私和安全
• 验证体系：完整的检查、诊断和审计机制
• 渐进式安装：支持 minimal、recommended、full 三种安装级别

该项目遵循类似 Oh My Zsh 的社区驱动模式，通过 npm 包分发 apx CLI 工具，用户可灵活选择安装哪些技能和插件到目标智能体环境中。

概述

Agent Powerups 是一个面向编程代理的 Oh My Zsh 风格工具集，提供了可复用的技能、命令、MCP 配置、钩子、AGENTS.md 模板和工作流。本指南将详细介绍如何在不同环境下安装和配置 Agent Powerups。

安装的核心目标是：将仓库中的资产（skills、plugins、commands、hooks 等）安全地部署到目标代理的工作目录中，同时保持灵活性和可控性。

系统要求

基础依赖

安装前请运行 apx doctor 命令检查环境配置是否满足要求。

安装方法

方法一：通过 npm 全局安装 apx CLI

apx 是 Agent Powerups 的命令行工具，提供资产发现、检验、安装和配置等功能。

npm install -g agent-powerups

安装完成后，验证安装：

apx doctor
apx --version

方法二：从源码构建

适用于需要自定义或参与开发的用户：

git clone https://github.com/yeaight7/agent-powerups.git
cd agent-powerups
npm install
npm run build
npm link

资料来源：examples/minimal/README.md

方法三：Docker 环境安装

如需在容器化环境中使用，请参考项目根目录下的 Dockerfile 或 docker-compose.yml 配置。

代理环境配置

Agent Powerups 支持多种编码代理的原生安装，包括 Codex、Claude Code 和 Gemini。不同的代理有不同的目录结构和配置方式。

支持的目标代理

Dry-Run 模式

在执行任何实际修改前，强烈建议先使用 dry-run 模式预览安装操作：

apx setup codex --dry-run
apx setup claude-code --dry-run
apx setup gemini --dry-run

这将显示将要执行的操作而不实际修改文件系统。

最小化安装（Bootstrap）

仅安装最基础的资产，适合首次试用或受限环境：

apx setup codex --mode minimal --yes
apx setup claude-code --mode minimal --yes
apx setup gemini --mode minimal --yes

资料来源：src/cli/apx.ts:1-100

推荐安装（Recommended）

安装推荐的技能和插件集合，适合大多数用户：

apx setup codex --mode recommended --yes
apx setup claude-code --mode recommended --yes
apx setup gemini --mode recommended --yes

完整安装（Full）

安装所有可用资产，包括完整的插件包和辅助资源：

apx setup codex --mode full --yes
apx setup claude-code --mode full --yes
apx setup gemini --mode full --yes

手动原生安装

基本手动安装

apx install <codex|claude|claude-code|gemini> [--verbose]

完整手动安装

apx install <codex|claude|claude-code|gemini> --full [--verbose]

默认手动安装行为：

• 根目录 skills/ → <agent-root>/skills/
• Codex/Claude 插件包 → <agent-root>/plugins/
• Gemini 插件包 → <agent-root>/extensions/

资料来源：README.md:quickstart

插件包安装

Agent Powerups 采用插件包（Plugin Bundles）架构管理相关技能和配置。

插件包状态分类

稳定版插件包

• dev-vitals - 开发健康指标
• debugging-diagnostics - 调试诊断
• quality-gates - 质量门禁

测试版插件包

• codebase-maintenance
• data-engineering
• documentation-systems
• machine-learning-ops
• codebase-intelligence
• spec-driven-development
• spec-quality-gates
• context-efficiency
• tool-integrations
• memory-optimization

实验版插件包

• software-engineering
• agentic-systems
• security-guardrails
• agent-evaluation-lab

插件包操作命令

# 列出所有插件包
apx plugins list

# 查看插件包详情
apx plugins info dev-vitals

# 验证插件包结构
apx plugins validate --all

# 安装插件包（dry-run）
apx plugins install dev-vitals --target codex --dry-run

# 实际安装插件包
apx plugins install dev-vitals --target codex

资料来源：README.md:plugin-bundles

MCP 配置安装

MCP（Model Context Protocol）配置用于扩展代理的工具访问能力。

MCP 配置命令

# 列出可用的 MCP 配置
apx mcp list

# 打印 MCP 配置内容
apx mcp print github-local --target claude-code

# 检查 MCP 配置
apx mcp check github-local --target claude-code --json

# 执行 MCP 配置冒烟测试
apx mcp smoke github-local --json

# 安装 MCP 配置
apx mcp install github-local --target codex --dry-run
apx mcp install github-local --target claude-code --dry-run

当前已打包的 MCP 配置

• github-local - 本地 GitHub MCP 配置，含检查、冒烟测试和显式安装命令

目录结构说明

标准安装后的目录结构

<agent-root>/
├── skills/                    # 可复用技能目录
│   ├── systematic-debugging/
│   ├── writing-plans/
│   └── ...
├── plugins/                   # 插件包目录（Codex/Claude）
│   ├── dev-vitals/
│   └── ...
├── extensions/               # 扩展目录（Gemini）
│   └── ...
├── agent-powerups/           # 资产根目录
│   ├── skills/               # 完整技能集
│   ├── commands/             # 命令包
│   ├── hooks/                # 钩子示例
│   ├── mcp/                  # MCP 配置
│   └── instructions/         # 指令文件
└── AGENTS.md / CLAUDE.md     # 代理配置文件

资料来源：examples/minimal/README.md

验证与检查

安装后验证

安装完成后，运行以下命令验证：

# 检查 apx 工具状态
apx doctor

# 列出已安装资产
apx list

# 查看特定技能详情
apx info using-powerups

# 检查技能完整性
apx check using-powerups

# 运行安全审计
apx security-audit

仓库验证脚本

python scripts/validate-skills.py
python scripts/validate-catalog.py
python scripts/check-requirements.py

配置检查

# 运行需求检查
apx check <asset-name>

# 安装缺失的依赖
apx check <asset-name> --install-missing --yes

# 查看需求详情
apx check <asset-name> --verbose

资料来源：src/cli/commands/check.ts

用户意图配置文件

用户意图配置文件（Profiles）提供预定义的能力组合，适合特定使用场景。

Profile 操作命令

# 列出所有配置文件
apx profiles list

# 查看配置文件详情
apx profiles info safe-core

内置配置文件

• safe-core - 安全核心配置，包含最基础的技能和检查

安装流程图

graph TD
    A[开始安装] --> B{安装方式选择}
    B -->|npm 全局安装| C[安装 apx CLI]
    B -->|源码构建| D[克隆仓库并构建]
    B -->|Docker| E[使用 Docker 镜像]
    
    C --> F{目标代理选择}
    D --> F
    E --> F
    
    F -->|Codex| G[apx install codex]
    F -->|Claude Code| H[apx install claude-code]
    F -->|Gemini| I[apx install gemini]
    
    G --> J[选择安装模式]
    H --> J
    I --> J
    
    J -->|minimal| K[Bootstrap 基础安装]
    J -->|recommended| L[推荐安装]
    J -->|full| M[完整安装]
    
    K --> N[安装后验证]
    L --> N
    M --> N
    
    N --> O{验证通过?}
    O -->|是| P[安装完成]
    O -->|否| Q[诊断问题]
    Q --> N

安全注意事项

在安装 Agent Powerups 时，请注意以下安全边界：

审查后再加载

警告：在将资产加载到受信任的代理环境前，请务必审查资产内容。

• 技能可能指示代理读取本地文件或运行命令
• 钩子可以在代理支持时执行代码
• MCP 配置可能扩展工具访问范围
• 安装命令可能修改本地环境
• 切勿将密钥粘贴到代理上下文中

安全审计命令

apx security-audit

此命令会扫描以下高风险模式：

资料来源：src/cli/commands/security-audit.ts

故障排除

常见问题

Q: apx 命令未找到

npm install -g agent-powerups
# 或
npm link  # 如果从源码安装

Q: 安装后代理无法识别技能 检查代理根目录下是否正确创建了 skills/ 目录，并确认 AGENTS.md 中包含了 agent-powerups 指令块。

Q: MCP 配置安装失败

apx mcp check github-local --target <agent> --json
apx mcp smoke github-local --json

完整回滚

如需完全移除安装的资产：

# 对于 Codex
Remove-Item <codex-root>\agent-powerups -Recurse -Force

# 对于 Claude Code
Remove-Item <claude-root>\agent-powerups -Recurse -Force

资料来源：examples/minimal/README.md

相关资源

• 快速开始指南
• 安全模型说明
• 兼容性矩阵
• 贡献指南
• API 文档

概述

apx 是 agent-powerups 项目的核心命令行工具，提供类似 Oh My Zsh 的体验，为编码代理（coding agents）提供可复用的技能、命令、工作流和配置管理能力。该工具以 TypeScript 开发，通过 npm 包发布，旨在标准化和简化各类编码代理的环境配置与日常操作。

apx 的设计理念强调本地优先（local-first）、安全审计（security-first）和渐进式配置（progressive setup），支持干运行（dry-run）、交互式确认和幂等操作。

核心功能模块

架构概览

graph TD
    A["用户终端"] --> B["apx CLI 入口<br/>src/cli/apx.ts"]
    B --> C{"命令路由"}
    C --> D["install"]
    C --> E["setup"]
    C --> F["mcp"]
    C --> G["check"]
    C --> H["ask-*"]
    C --> I["relay"]
    C --> J["plugins"]
    C --> K["profiles"]
    
    D --> L["技能安装逻辑"]
    E --> M["setup.ts<br/>代理托管式安装"]
    F --> N["MCP 配置管理"]
    G --> O["requirements.ts<br/>依赖检查"]
    H --> P["外部代理 API"]
    I --> Q["持久会话状态"]
    J --> R["插件bundles"]
    K --> S["用户意图配置"]
    
    L --> T["目标代理根目录<br/>codex / claude-code / gemini"]
    M --> T
    N --> U["github-local MCP"]
    O --> V["npm / pip / cargo<br/>依赖解析"]

命令速查表

安装与配置

查询与列表

执行与操作

验证与审计

详细命令说明

install - 资产安装

install 命令是 apx 的核心命令之一，用于将技能、插件和配置安装到指定代理的根目录。

graph LR
    A["输入: apx install codex"] --> B["解析 --target 参数"]
    B --> C{"INSTALL_TARGETS 检查"}
    C -->|通过| D["定位代理根目录"]
    C -->|失败| E["抛出错误"]
    D --> F["复制 skills/ 到目标"]
    F --> G["复制 plugins/ 到目标"]
    G --> H["可选: 复制 agent-powerups/ 资源"]
    H --> I["完成"]

安装模式对比：

命令示例：

# 干运行查看安装计划
apx install codex --dry-run

# 完整安装到 Codex
apx install codex --full --verbose

# 安装单个技能到 Claude Code
apx install markitdown-file-intake --target claude-code --dry-run

# 指定自定义代理根目录
apx install gemini --agent-root ~/.config/agent/gemini

资料来源：src/cli/apx.ts:45-80

setup - 代理托管式配置

setup 命令提供引导式配置体验，支持三种预设模式，自动生成配置指令。

graph TD
    A["apx setup <agent>"] --> B{"模式选择"}
    B -->|"minimal"| C["bootstrap 模式"]
    B -->|"recommended"| D["推荐模式"]
    B -->|"full"| E["完整模式"]
    
    C --> F["生成基础 AGENTS.md 块"]
    D --> G["生成技能 + 插件说明"]
    E --> H["生成全量功能说明"]
    
    F --> I{"目标文件存在?"}
    G --> I
    H --> I
    
    I -->|存在| J["追加到现有文件<br/>备份 .bak"]
    I -->|不存在| K["创建 agent-powerups.md"]
    J --> L["完成"]
    K --> L

配置模式说明：

资料来源：src/cli/commands/setup.ts:50-100

mcp - MCP 服务器配置

MCP（Model Context Protocol）配置管理提供本地 GitHub MCP 的检查、烟雾测试和安装能力。

工作流程：

graph LR
    A["mcp check"] --> B{"配置有效?"}
    B -->|是| C["mcp smoke"]
    B -->|否| D["报告错误"]
    C --> E{"烟雾测试通过?"}
    E -->|是| F["mcp install"]
    E -->|否| G["报告问题"]
    F --> H["完成"]

check - 依赖检查

check 命令验证技能所需工具是否已安装，支持自动安装缺失依赖。

graph TD
    A["apx check <skill>"] --> B["加载技能定义"]
    B --> C["解析 requires 字段"]
    C --> D["检测系统工具"]
    D --> E{"所有依赖满足?"}
    E -->|是| F["输出 OK 状态"]
    E -->|否| G{"--install-missing?"}
    G -->|是| H["调用 requirements.ts"]
    G -->|否| I["输出 MISSING 状态"]
    H --> J{"有支持的安装器?"}
    J -->|是| K["显示安装命令预览"]
    J -->|否| L["提示手动安装"]
    K --> M{"--dry-run?"}
    M -->|是| N["仅显示计划"]
    M -->|否| O["执行安装"]

依赖解析逻辑：

requirements.ts 中的 installMissingRequirements 函数负责解析缺失依赖，并调用对应的包管理器：

资料来源：src/cli/commands/check.ts:30-80

资料来源：src/cli/utils/requirements.ts:1-60

ask-* - 多代理咨询

ask-* 命令提供统一的接口向外部编码代理发送请求：

使用场景：

# 询问代码解释
apx ask-codex "Explain this code" --json

# 代码审查
apx ask-claude "Review this patch" --json

# 头脑风暴测试用例
apx ask-gemini "Brainstorm test cases" --json

relay - 持久中继会话

relay 命令维护跨轮次的持久会话，保持上下文状态，特别适合需要多轮协作的场景。

graph TD
    A["relay init <name>"] --> B["创建会话状态"]
    B --> C["relay start <name> --provider <gemini>"]
    C --> D["建立持久连接"]
    D --> E["relay ask <name> '<prompt>'"]
    E --> F["发送消息"]
    F --> G["接收响应"]
    G --> H{"需要继续?"}
    H -->|是| E
    H -->|否| I["relay stop <name>"]

中继会话管理：

security-audit - 安全审计

security-audit 命令扫描代码库中的常见安全风险，包括硬编码密钥、不安全的 shell 命令和不推荐的镜像标签。

支持的检测规则：

扫描范围：

• 文件扩展白名单：.json, .toml, .md, .sh, .ps1, .yaml, .yml
• 跳过目录：node_modules, dist, .git, .worktrees, .plugins
• 最大文件大小：512 KB

资料来源：src/cli/commands/security-audit.ts:1-50

phase - 阶段式工作流

phase 命令实现项目开发的阶段化工作流，支持讨论、计划、执行和验证阶段。

graph LR
    A["phase discuss"] --> B["需求澄清"]
    B --> C["phase plan"]
    C --> D["PRD 生成"]
    C --> E["MVP 规划"]
    D --> F["phase execute"]
    E --> F
    F --> G["按 wave 执行"]
    G --> H["phase verify"]
    H --> I{"验证通过?"}
    I -->|否| G
    I -->|是| J["完成"]

阶段子命令：

资料来源：src/cli/commands/phase-workflows.ts:1-40

代理目标

apx 支持多个编码代理平台作为安装目标：

安装时通过 --target <agent> 参数指定目标，未指定时使用对应代理的默认配置目录。

输出格式

大多数 apx 命令支持 JSON 输出，便于脚本集成和自动化处理：

# 获取 JSON 格式输出
apx list --json
apx check markitdown-file-intake --json
apx security-audit --all --json

# 干运行模式
apx install codex --dry-run

错误处理与安全

幂等性保证

apx 命令设计为幂等操作：

• install 重复执行不会重复复制已存在文件
• setup 在 AGENTS.md 存在时会创建备份 .bak
• --dry-run 选项允许预览行为而不实际修改

安全边界

apx 在以下方面保持安全边界：

• 外部工具：需要用户显式批准安装
• 密钥：内置 no-secrets-preflight 钩子检测
• Shell 配置：不自动修改 shell 启动文件
• MCP 服务器：需要显式启用确认

诊断工具

# 基础诊断
apx doctor

# 完整诊断（JSON）
apx doctor --full --json

# 仓库审计
apx audit repo --json

快速参考

首次使用

npm install
npm run build
npm link
apx doctor
apx list

常见工作流

部署到 Codex：

apx setup codex --mode recommended --yes

检查技能依赖：

apx check markitdown-file-intake
apx check defuddle --install-missing --dry-run

运行安全扫描：

apx security-audit --path ./src
apx hooks run no-secrets-preflight --all

多代理咨询：

apx ask-claude "Review this PR" --json
apx relay start second-opinion --provider gemini
apx relay ask second-opinion "Analyze this architecture" --json

概述

Agent Powerups 的资产目录系统是一个集中管理、可验证的资产清单，涵盖可复用的技能、工作流、命令模板、MCP 配置和 AGENTS.md 模板。该系统采用声明式 JSON 格式定义所有资产元数据，并通过自动化验证脚本确保目录内容的完整性和一致性。资产目录的核心价值在于为编码代理提供"Oh My Zsh 风格"的可插拔组件库，开发者可以通过 apx CLI 工具浏览、安装和验证这些资产。

目录架构

资产目录采用分层架构设计，将不同类型的资产分别归类管理：

graph TD
    A[agent-powerups 仓库] --> B[根级资产目录]
    A --> C[插件包 bundle]
    B --> D[skills/ 技能目录]
    B --> E[mcp/ MCP配置]
    B --> F[agents-md/ 模板]
    B --> G[commands/ 命令集]
    B --> H[hooks/ 钩子示例]
    B --> I[workflows/ 工作流]
    C --> J[17个插件包]
    C --> K[技能 + 代理 + 命令组合]

目录结构与资产类型的对应关系如下：

目录清单结构

技能资产 (Skills)

当前已发布的技能共 23 个，涵盖调试、规划、代码审查、数据工程等多个领域：

资料来源：README.md

插件包资产 (Plugin Bundles)

插件包是技能、代理和命令的组合，按成熟度分为三个等级：

#### 稳定版插件包 (Stable)

#### 测试版插件包 (Beta)

#### 实验版插件包 (Experimental)

每个插件遵循标准编码代理插件布局：

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json      # Claude Code 清单
├── .codex-plugin/
│   └── plugin.json      # Codex 清单
├── skills/
│   └── <skill-name>/
│       └── SKILL.md
├── agents/
│   └── <agent-name>.md
└── commands/
    └── <command-name>.md

资料来源：plugins/README.md

AGENTS.md 模板资产

命令资产 (Commands)

钩子示例资产 (Hooks)

工作流资产 (Workflows)

MCP 配置资产

目录验证机制

验证脚本体系

项目包含三个核心验证脚本，确保目录内容的有效性：

graph LR
    A[validate-skills.py] --> B[技能元数据检查]
    A --> C[SKILL.md 存在性]
    A --> D[支持文件引用]
    
    E[validate-catalog.py] --> F[catalog.json 格式]
    E --> G[资产完整性]
    E --> H[引用有效性]
    
    I[check-requirements.py] --> J[依赖检查]
    J --> K[可选自动安装]

#### 技能验证脚本 (validate-skills.py)

validate-skills.py 负责验证所有技能资产的结构完整性：

• 检查每个技能目录下是否存在 SKILL.md 文件
• 验证 frontmatter 中是否包含 name 和 description 必需字段
• 检查技能内容长度是否满足最小要求
• 验证支持文件的引用是否指向实际存在的文件

python scripts/validate-skills.py

资料来源：scripts/validate-skills.py

#### 目录验证脚本 (validate-catalog.py)

validate-catalog.py 验证整个目录清单的正确性：

• 验证 catalog.json 格式是否符合 schema
• 确保所有声明的资产在文件系统中实际存在
• 检查资产引用的完整性

python scripts/validate-catalog.py

资料来源：scripts/validate-catalog.py

#### 依赖检查脚本 (check-requirements.py)

check-requirements.py 检查运行技能所需的依赖项：

• 识别缺失的外部依赖
• 提供安装提示（installHint）
• 支持自动安装可用的依赖

python scripts/check-requirements.py

资料来源：src/cli/commands/check.ts

验证检查项

CLI 命令集成

目录浏览命令

# 浏览目录
apx list

# 查看特定技能
apx info markitdown-file-intake

# 运行命令检查
apx commands run ship-check

# 运行钩子检查
apx hooks run no-secrets-preflight --all

# MCP 配置检查
apx mcp check github-local --target generic
apx mcp smoke github-local --json

插件管理命令

apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target codex --dry-run

审计命令

apx audit 命令提供系统性的资产审计功能：

apx audit skills
apx audit plugins

审计输出格式：

audit skills: 5 pass, 2 warn, 0 fail
[OK] skill-frontmatter: all have name + description
[WARN] skill-content-length: 2 skill(s) under 500 chars

目录模式 (Catalog Schema)

目录采用 JSON Schema 定义资产元数据规范，核心字段包括：

{
  "name": "资产名称",
  "description": "资产描述",
  "path": "相对于仓库根的路径",
  "maturity": "stable|beta|experimental",
  "tags": ["标签1", "标签2"],
  "requires": {
    "skills": ["依赖技能"],
    "tools": ["依赖工具"]
  }
}

资料来源：docs/catalog-schema.md

安全考量

资产目录系统内置多层安全保护机制：

部署前检查

• 技能可指导代理读取本地文件或执行命令
• 钩子可在宿主代理支持时执行代码
• MCP 配置可扩展工具访问范围
• 安装命令可修改本地环境

安装保护

所有安装操作默认处于干运行模式，需要显式授权才能执行：

apx install codex --dry-run  # 预览不执行
apx install codex            # 实际执行

秘密管理

• 秘密绝不应粘贴到代理上下文，除非严格必要
• MCP 服务器需要显式用户批准
• 外部工具安装需要用户批准

与代理的集成

代理兼容性矩阵

资料来源：README.md

支持的代理平台

维护工作流

仓库维护应持续运行验证检查：

graph TD
    A[修改资产文件] --> B[运行 validate-skills.py]
    B --> C{检查通过?}
    C -->|是| D[运行 validate-catalog.py]
    C -->|否| E[修复问题]
    E --> B
    D --> F{检查通过?}
    F -->|是| G[运行 check-requirements.py]
    F -->|否| H[修复问题]
    H --> D
    G --> I[提交更改]

建议的维护命令序列：

python scripts/validate-skills.py
python scripts/validate-catalog.py
python scripts/check-requirements.py

总结

资产目录系统是 Agent Powerups 的核心基础设施，提供了一套完整、可验证的资产管理体系。通过声明式清单、自动化验证和 CLI 工具集成，开发者可以安全地发现、安装和使用预构建的代理资源。该系统支持多代理平台（Codex、Claude Code、Gemini），并通过插件包机制实现了资产的分层组织和按需扩展。

概述

插件包系统（Plugin Bundle System）是 Agent Powerups 项目中用于组织、发布和分发功能模块的核心机制。该系统借鉴了 "Oh My Zsh" 的插件管理模式，将相关的 skills（技能）、agents（代理模板）、commands（命令）和 templates（模板）打包成独立的插件单元，支持多 agent 平台的安装与同步。

插件包系统的主要职责包括：

• 模块化封装：将功能资源按领域分类，形成可独立管理的插件单元
• 跨平台兼容：通过统一的 manifest 定义，支持 Codex、Claude Code、Gemini 等多种 coding agent
• 生命周期管理：通过成熟度等级（maturity）区分实验性功能和稳定功能
• 标准化安装：提供 apx CLI 工具实现插件的发现、验证和安装

资料来源：plugins/README.md

插件包结构

目录布局

每个插件遵循标准的 coding agent 插件目录结构：

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json          # Claude Code 平台清单
├── .codex-plugin/
│   └── plugin.json          # Codex 平台清单
├── skills/
│   └── <skill-name>/
│       └── SKILL.md         # 技能定义文件
├── agents/
│   └── <agent-name>.md      # 代理模板文件
└── commands/
    └── <command-name>.md    # 命令定义文件

根级别的 skills 位于 skills/ 目录，是通用型独立技能。插件内的 skills 是领域专用的，提供更深入的功能覆盖。同一主题的插件技能不得替代或覆盖根级别技能。

资料来源：plugins/README.md

Manifest 文件

每个插件包含针对不同 agent 平台的 manifest 文件，定义了插件的元数据和资源引用。

Claude Code Manifest 示例结构：

{
  "name": "dev-vitals",
  "version": "1.0.0",
  "description": "Development health metrics and monitoring",
  "maturity": "stable",
  "skills": [
    { "name": "dev-vitals-check", "path": "skills/dev-vitals-check" }
  ],
  "commands": [
    { "name": "dev-vitals", "path": "commands/dev-vitals.md" }
  ]
}

Codex Manifest 示例结构：

{
  "name": "dev-vitals",
  "version": "1.0.0",
  "description": "Development health metrics and monitoring",
  "maturity": "stable",
  "skills": ["skills/dev-vitals-check"],
  "commands": ["commands/dev-vitals.md"]
}

两个平台的 manifest 格式略有差异：Codex 版本使用字符串路径数组，Claude Code 版本使用对象数组（包含 name 和 path 属性）。

成熟度等级

插件包根据功能稳定性和适用场景分为三个成熟度等级：

资料来源：plugins/README.md

插件包清单

当前仓库包含 17 个插件包，分布如下：

稳定版插件（Stable）

Beta 版插件

实验版插件（Experimental）

资料来源：plugin-bundles.json

插件包元数据模式

插件包的元数据定义在 plugin-bundles.json 中，每个插件条目包含以下字段：

资料来源：docs/plugin-bundles-schema.json

技能条目结构

{
  "name": "skill-name",
  "description": "技能描述",
  "path": "skills/skill-name"
}

代理模板条目结构

{
  "name": "agent-name",
  "description": "代理模板描述",
  "path": "agents/agent-name.md"
}

工作流程

插件安装流程

以下流程图展示了使用 apx CLI 安装插件的标准流程：

graph TD
    A[用户执行 apx plugins install] --> B[CLI 解析目标 agent 平台]
    B --> C{是否使用 --dry-run}
    C -->|是| D[生成模拟安装计划]
    C -->|否| E[检查插件目录存在性]
    E --> F{manifest 文件验证}
    F -->|通过| G[复制资源到目标目录]
    F -->|失败| H[输出验证错误]
    G --> I[更新 agent 配置文件]
    I --> J[安装完成]
    D --> J

插件发现与检查流程

graph TD
    A[用户执行 apx plugins list] --> B[读取 plugin-bundles.json]
    B --> C[扫描 plugins/ 目录]
    C --> D[合并清单数据]
    D --> E[格式化输出插件列表]
    
    F[用户执行 apx plugins info] --> G[定位指定插件]
    G --> H[读取插件 manifest]
    H --> I[输出详细元数据]
    
    J[用户执行 apx plugins validate] --> K[检查 manifest 格式]
    K --> L{符合 schema?}
    L -->|是| M[输出验证通过]
    L -->|否| N[输出验证错误列表]

CLI 命令参考

插件列表

apx plugins list

列出所有可用的插件包，显示名称、描述和成熟度等级。

插件详情

apx plugins info <plugin-name>

查看单个插件的详细元数据，包括包含的 skills、agents、commands 和 templates。

插件验证

apx plugins validate --all

验证所有插件的 manifest 文件结构是否符合规范，检查必需字段和文件路径。

插件安装

# 模拟安装（预览）
apx plugins install <plugin-name> --target codex --dry-run

# 实际安装
apx plugins install <plugin-name> --target codex --yes

将插件安装到指定的 agent 平台。--target 参数支持 codex、claude-code、gemini 或 generic。

插件构建

apx plugins build --dest <output-path> --dry-run
apx plugins build --dest <output-path> --write

根据当前仓库中的插件定义生成打包输出。--dry-run 模式生成预览，--write 模式执行实际写入。

插件差异对比

apx plugin diff <plugin-path>

比较插件的实际目录结构与 manifest 声明的差异，识别缺失或未声明的资源文件。

资料来源：src/cli/apx.ts

Marketplace 配置

Marketplace 配置文件定义了插件的市场元数据，用于插件市场的发现和展示。

Claude Code Marketplace 配置

{
  "plugins": [
    {
      "name": "dev-vitals",
      "version": "1.0.0",
      "description": "Development health metrics and monitoring",
      "categories": ["diagnostics", "quality"],
      "tags": ["monitoring", "metrics", "vitals"]
    }
  ]
}

Codex Marketplace 配置

{
  "plugins": [
    {
      "name": "dev-vitals",
      "version": "1.0.0",
      "description": "Development health metrics and monitoring",
      "categories": ["diagnostics", "quality"],
      "tags": ["monitoring", "metrics", "vitals"]
    }
  ]
}

两个平台的 marketplace 配置结构保持一致，确保跨平台插件发现的一致性体验。

资料来源：.claude-plugin/marketplace.json、.codex-plugin/marketplace.json

根级技能与插件技能的关系

Agent Powerups 采用分层技能架构：

graph BT
    subgraph "Root Level"
        R1[systematic-debugging]
        R2[writing-plans]
        R3[no-fluff]
    end
    
    subgraph "Plugin Level"
        P1[debugging-diagnostics/debug-tactics]
        P2[spec-driven-development/plan-generator]
        P3[quality-gates/review-check]
    end
    
    R1 -. "complementary" .-> P1
    R2 -. "complementary" .-> P2
    R3 -. "complementary" .-> P3

• 根级别技能（skills/）：通用型技能，专注于通用工作流程
• 插件技能：领域专用技能，提供更深入的功能实现

插件技能与根级别技能是互补关系而非替代关系。同一主题的插件技能不会覆盖或替代根级别技能。

完整安装与插件安装的区别

安全注意事项

• 插件可以指示 agent 读取本地文件或执行命令
• MCP 配置可以扩展工具访问权限
• 安装命令可以修改本地环境
• 敏感信息（secrets）不应粘贴到 agent 上下文中

在加载插件到受信任的 agent 环境之前，请务必审查插件内容。

资料来源：plugins/README.md

最佳实践

1. 安装前验证：使用 --dry-run 模式预览安装计划
2. 分阶段安装：从 stable 版本开始，逐步评估 beta 版本
3. 定期更新：使用 apx plugins validate --all 检查插件完整性
4. 环境隔离：使用 --agent-root 指定隔离环境进行测试
5. 备份配置：重要 agent 配置文件在安装前进行备份

概述

技能系统（Skill System）是 Agent Powerups 的核心组件，为编码智能体提供可复用的任务工作流集合。该系统借鉴了 Oh My Zsh 的插件理念，为智能体提供结构化的任务指导、能力扩展和标准化工作流程。技能系统使编码智能体能够执行系统化调试、计划撰写、代码审查、数据质量检查等复杂任务，同时保持行为一致性和可维护性。

技能系统包含 24 个已发布的根技能，涵盖调试、规划、代码审查、数据工程、文档处理等多个领域。技能以 Markdown 文件形式存储，部署时直接复制到智能体的 skills 目录中供其调用。

技能分类

按功能领域分类

资料来源：README.md

按来源分类

根技能（Root Skills）位于仓库根目录的 skills/ 文件夹中，属于通用目的、可独立使用的技能。插件技能（Plugin Skills）位于 plugins/ 目录下的各插件子目录中，属于领域特定且深度专精的技能。插件技能可能与根技能覆盖相同主题，但不应替换或覆盖根技能。

资料来源：plugins/README.md

技能结构

文件组织

每个技能遵循标准的目录结构：

skills/
└── <skill-name>/
    └── SKILL.md           # 技能定义文件（必需）
    └── support/           # 支持文件目录（可选）
        └── <file>         # 技能引用的辅助资源

SKILL.md 格式规范

SKILL.md 是技能的核心定义文件，包含前置matter元数据和技能内容。文件必须包含以下前置matter字段：

前置matter 示例：

概述

命令系统（Command System）是 Agent Powerups 的核心组件之一，为编码代理提供可复用的命令提示词和工作流指令。与传统固定命令不同，该系统采用 Markdown 文件格式存储命令模板，支持多目标代理（Codex、Claude Code、Gemini）的差异化适配，并可通过 apx CLI 工具进行发现、检查、验证和执行。

命令系统的设计理念是 "review-first"（审查优先）——在执行任何命令前，代理应先阅读并理解命令意图，而非盲目执行预设脚本。 资料来源：README.md

架构设计

命令系统组件关系

graph TD
    A[命令系统] --> B[通用命令 generic]
    A --> C[Agent特定命令]
    C --> C1[Codex命令]
    C --> C2[Claude Code命令]
    C --> C3[Gemini命令]
    
    A --> D[命令检查工具]
    D --> D1[bug-check]
    D --> D2[security-audit]
    D --> D3[ship-check]
    
    A --> E[apx CLI]
    E --> E1[commands print]
    E --> E2[commands run]
    E --> E3[commands validate]

命令目录结构

每个命令目录遵循标准化布局：

资料来源：plugins/README.md

命令类型分类

按功能分类

按目标代理分类

资料来源：README.md - Catalog Overview

内置命令详解

1. Bug Check 命令

bug-check.md 专注于系统性缺陷发现，为代理提供结构化的调试工作流。

核心功能：

• 系统性错误定位
• 根因分析引导
• 修复方案生成

使用方式：

apx commands print bug-check --target <agent>
apx commands run bug-check

资料来源：commands/bug-check.md

2. Security Audit 命令

security-audit.md 提供代码安全审计功能，包含自动化检测规则。

检测规则示例：

资料来源：src/cli/commands/security-audit.ts:20-40

扫描配置：

资料来源：src/cli/commands/security-audit.ts:41-43

3. Ship Check 命令

ship-check 是发布前验证命令包，确保代码符合发布标准。

命令执行：

apx commands run ship-check

资料来源：README.md - Quickstart

4. 工作流命令组

系统提供一系列工作流编排命令：

资料来源：src/cli/apx.ts:45-60

apx CLI 命令接口

命令管理子命令

graph LR
    A[apx commands] --> B[print]
    A --> C[run]
    A --> D[validate]
    
    B --> B1[显示命令内容]
    C --> C1[执行命令]
    D --> D1[验证命令结构]

使用示例

# 列出所有可用命令
apx commands list

# 打印命令内容到指定目标代理
apx commands print ship-check --target claude-code

# 执行本地命令检查
apx commands run ship-check

# 验证所有命令文件结构
apx commands validate --all

资料来源：README.md - Quickstart

生命周期命令

Phase 命令组

Phase 命令提供结构化的任务生命周期管理：

graph TD
    A[phase 命令] --> B[discuss]
    A --> C[plan]
    A --> D[execute]
    A --> E[verify]
    
    B --> B1[需求讨论]
    C --> C1[任务规划]
    D --> D1[执行实施]
    E --> E1[结果验证]

使用方式：

apx phase discuss <phase-name>
apx phase plan <phase-name>
apx phase execute <phase-name>
apx phase verify <phase-name>

资料来源：src/cli/apx.ts:69-74

Project 命令组

项目初始化命令：

apx project init

资料来源：src/cli/apx.ts:65-68

Codebase 命令组

代码库分析命令：

apx codebase map

资料来源：src/cli/apx.ts:77-80

检查与验证

命令检查功能

check.ts 实现对命令资产的完整性验证：

验证内容：

• 命令文件存在性
• 必需的前置条件（requires）满足情况
• 缺失依赖的自动安装选项

apx check <asset-name> [--install-missing] [--yes]

输出格式：

<asset-name>:status=<OK|WARN|MISSING>[| install: <hint>]

资料来源：src/cli/commands/check.ts:10-30

安全审计流程

flowchart LR
    A[启动安全审计] --> B[收集目标文件]
    B --> C{文件过滤}
    C -->|跳过大文件| D[跳过]
    C -->|扩展名匹配| E[模式匹配]
    E --> F[规则检测]
    F --> G{发现问题?}
    G -->|是| H[记录警告]
    G -->|否| I[继续扫描]
    H --> I
    I --> J{更多文件?}
    J -->|是| C
    J -->|否| K[输出报告]

与代理的集成

指令文件处理

命令系统支持向代理的指令文件（如 AGENTS.md、CLAUDE.md）注入命令块：

行为说明：

资料来源：src/cli/commands/setup.ts:1-20

各代理的集成方式

Codex 集成：

apx commands print ship-check --target codex
apx setup codex --mode recommended --yes

Claude Code 集成：

apx commands print ship-check --target claude-code
apx setup claude-code --mode recommended --yes

资料来源：examples/codex/README.md、examples/claude-code/README.md

命令模板格式

命令文件采用 Markdown 格式，包含以下标准结构：

概述

钩子系统（Hook System）是 Agent Powerups 框架中用于在特定执行节点触发自定义逻辑的扩展机制。该系统允许开发者和用户在 agent 工作流的关键时刻注入检查、转换、通知或验证行为，从而实现对 agent 行为的精细化控制。

钩子是可组合的、声明式的配置单元，支持 pre-hook（前置钩子）和 post-hook（后置钩子）两种模式。系统强调本地优先（local-first）的执行策略，所有钩子内容默认存储在仓库的 hooks/ 目录下，并通过 apx CLI 工具进行管理和执行。资料来源：README.md

架构设计

核心组件

钩子系统由以下核心组件构成：

工作流程

graph TD
    A[用户触发钩子执行] --> B{apx hooks run}
    B --> C[加载 catalog.json]
    C --> D[定位目标钩子目录]
    D --> E[解析 HOOK.md 元数据]
    E --> F[检查前置条件 requires]
    F --> G{条件满足?}
    G -->|否| H[跳过或警告]
    G -->|是| I[执行钩子逻辑]
    I --> J[记录执行结果]
    J --> K[返回状态和输出]

钩子执行遵循以下顺序：

1. 发现阶段：通过 apx hooks list 枚举所有可用钩子
2. 验证阶段：检查钩子定义文件的完整性和依赖
3. 执行阶段：根据钩子类型运行相应逻辑
4. 报告阶段：输出执行结果和潜在问题

资料来源：hooks/README.md

钩子类型分类

按功能分类

Agent Powerups 当前支持三种主要钩子分类：

内置钩子

#### 1. no-secrets-preflight（安全类）

用途：在 agent 处理敏感信息前执行预检查，防止密钥、凭证或私密数据意外泄露。

触发场景：

• 用户请求处理文件时
• Agent 准备写入外部服务时
• 涉及环境变量或配置文件的操作前

安全模型约束：该钩子严格遵循最小权限原则，任何涉及密钥的操作都需要显式确认。资料来源：docs/security-model.md:1-50

#### 2. handoff-summary（效率类）

用途：在 agent 之间进行上下文交接时生成摘要信息，确保信息传递的完整性和连续性。

输出内容：

• 当前任务进度概述
• 已完成的检查点列表
• 待处理的依赖项
• 关键上下文引用

#### 3. validation-required（质量类）

用途：在关键操作执行前强制进行验证检查，确保符合预定义的质量标准。

验证维度：

• 代码格式规范
• 文档完整性
• 测试覆盖率
• 类型安全

钩子定义格式

每个钩子目录包含一个 HOOK.md 文件，遵循标准的前置元数据格式：

概述

MCP（Model Context Protocol）配置管理是 Agent Powerups 项目的核心功能之一，提供本地优先的 GitHub MCP 配置管理能力。该系统支持配置的检查、冒烟测试和显式安装，确保编码代理能够安全地访问 MCP 服务器工具。

Agent Powerups 的 MCP 配置管理遵循本地优先、安全优先的设计原则，所有配置操作都需要用户显式授权，不会自动修改环境。

资料来源：README.md:36

核心概念

什么是 MCP 配置

MCP 配置定义了编码代理（如 Claude Code、Codex）可用的 MCP 服务器连接信息。这些配置文件包含：

• MCP 服务器端点地址
• 认证令牌占位符
• 必需的环境变量
• 警告信息和使用提示

支持的代理类型

资料来源：docs/mcp-configs.md

架构设计

配置查找机制

MCP 配置采用分层查找策略，根据安装目标确定配置文件路径：

graph TD
    A[请求 MCP 配置] --> B{安装目标类型}
    B -->|codex| C[mcp/codex/]
    B -->|claude-code| D[mcp/claude-code/]
    B -->|generic| E[mcp/generic/]
    C --> F[查找目标特定配置]
    D --> F
    E --> F
    F --> G{是否有 targets 映射}
    G -->|是| H[使用 targets 中的路径]
    G -->|否| I[使用默认 path 字段]

资料来源：src/cli/commands/mcp.ts:67-72

配置文件结构

每种代理类型的配置文件遵循各自的格式规范：

Claude Code 格式（JSON）：

{
  "mcpServers": {
    "github-local": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Codex 格式（TOML）：

[[mcp_servers]]
name = "github-local"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
[env]
GITHUB_TOKEN = "${GITHUB_TOKEN}"

资料来源：mcp/claude-code/github-local.json、mcp/codex/github-local.toml

MCP 命令系统

可用命令列表

check 命令

check 命令验证 MCP 配置的正确性，包括：

• 配置文件存在性检查
• 配置文件类型验证（必须是 mcp-config 类型）
• 环境变量检查（识别未设置必需的环境变量）
• GitHub Token 验证

export async function runMcpCheckCommand(
  service: CatalogService,
  assetName: string,
  target: InstallTarget,
  env: NodeJS.ProcessEnv = process.env,
): Promise<ExecutionResult<McpCheckData>>

返回数据结构：

资料来源：src/cli/commands/mcp.ts:74-91

install 命令

install 命令将 MCP 配置复制到代理配置目录。该命令支持干运行模式，允许用户预览安装效果。

# 预览安装（不实际写入）
apx mcp install github-local --target codex --dry-run

# 执行安装
apx mcp install github-local --target codex

安装流程：

graph LR
    A[apx mcp install] --> B{是否 --dry-run}
    B -->|是| C[仅显示预览信息]
    B -->|否| D{是否有警告}
    D -->|是| E[显示警告信息]
    D -->|否| F[执行安装]
    E --> F
    F --> G[复制配置文件]
    G --> H[替换环境变量占位符]

资料来源：README.md:95

冒烟测试命令

smoke 命令执行 MCP 服务器的连接测试，验证配置是否能正常工作。

环境变量管理

必需环境变量

MCP 配置中声明的必需环境变量通过 required_env 字段定义：

{
  "mcp": {
    "required_env": ["GITHUB_TOKEN"]
  }
}

环境变量检查逻辑

check 命令会扫描所有配置，收集并验证环境变量设置状态：

const requiredEnv = (asset.mcp?.required_env ?? []).map((name) => ({
  name,
  set: Boolean(env[name])
}));

检查结果示例：

资料来源：src/cli/commands/mcp.ts:89-90

安全警告

安装过程中，系统会自动添加安全警告提示：

警告：请将占位符（如 ${GITHUB_TOKEN} 或 YOUR_TOKEN_HERE）替换为本地真实令牌，不要提交真实令牌到版本控制系统。

资料来源：src/cli/commands/mcp.ts:58-60

资产管理

资产元数据结构

MCP 配置作为资产类型 mcp-config 在 catalog.json 中注册：

{
  "name": "github-local",
  "type": "mcp-config",
  "path": "mcp/generic/github-local.json",
  "targets": {
    "claude-code": "mcp/claude-code/github-local.json",
    "codex": "mcp/codex/github-local.toml"
  },
  "mcp": {
    "warning": "MCP 服务器启用需要显式用户批准",
    "required_env": ["GITHUB_TOKEN"]
  }
}

资产字段说明：

资料来源：docs/mcp-configs.md

目标路径解析

当存在 targets 映射时，系统优先使用对应目标的值：

function mcpTargetPath(
  service: CatalogService,
  assetName: string,
  target: InstallTarget
): string {
  const asset = service.getAsset(assetName);
  if (asset.type !== "mcp-config") {
    throw new Error(`${assetName} is not an mcp-config asset`);
  }
  return asset.targets?.[target] ?? asset.path;
}

工作流程示例

完整配置流程

graph TD
    A[开始] --> B[apx mcp check github-local]
    B --> C{配置有效?}
    C -->|否| D[修复配置问题]
    C -->|是| E[apx mcp smoke github-local]
    E --> F{连接成功?}
    F -->|否| G[检查 MCP 服务器]
    F -->|是| H[apx mcp install github-local --target claude-code --dry-run]
    H --> I{预览正确?}
    I -->|否| J[调整配置]
    I -->|是| K[apx mcp install github-local --target claude-code]
    K --> L[配置完成]
    D --> B
    J --> H

典型使用场景

场景 1：Claude Code 用户配置 GitHub MCP

# 1. 检查配置
apx mcp check github-local --target claude-code

# 2. 冒烟测试
apx mcp smoke github-local --target claude-code

# 3. 预览安装
apx mcp install github-local --target claude-code --dry-run

# 4. 执行安装
apx mcp install github-local --target claude-code

场景 2：Codex 用户配置 GitHub MCP

# 使用专用提示
apx mcp install github-local --target codex --dry-run

资料来源：README.md:96-100

安全模型

安全边界

Agent Powerups 的 MCP 配置管理维护以下安全边界：

1. 本地优先：所有配置文件优先从本地目录加载
2. 显式安装：不自动修改任何配置文件
3. 占位符验证：强制检查环境变量占位符
4. 预览优先：所有写入操作支持 --dry-run 模式

风险缓解措施

资料来源：docs/security-model.md

命令参考

全局标志

环境变量

故障排除

常见问题

Q: MCP 配置检查失败，提示类型错误？

A: 确保资产在 catalog.json 中的 type 字段值为 mcp-config。

Q: 环境变量已设置但仍显示未设置？

A: 检查变量名是否完全匹配（包括大小写），并确保在运行 apx 命令的 shell 会话中变量已导出。

Q: 目标路径未找到？

A: 确认 targets 映射中存在对应的目标类型，或 path 字段指向的默认路径有效。

相关资源

• MCP 配置文档
• 安全模型
• 设置指南
• catalog.json 规范

概述

用户意图配置（Profiles）是 Agent Powerups 框架中用于管理不同编码代理（coding agent）环境设置的配置系统。它允许用户为 Codex、Claude Code 和 Gemini 等主流编码代理定义和管理特定的技能集、插件包和安装参数。

Profiles 的核心作用是为每种代理提供一套经过策划（curated）的技能和插件组合，使用户能够根据不同的工作场景快速切换代理配置。资料来源：src/cli/apx.ts:28-32

核心概念

什么是用户意图配置

用户意图配置是一种声明式的配置格式，它定义了：

• 代理的类型和识别信息
• 默认的根目录和环境变量
• 指令文件的命名规则
• 目标目录的映射关系
• 推荐的技能列表
• 推荐的命令包
• 推荐的插件捆绑包

资料来源：src/cli/commands/setup.ts:37-58

配置与 Setup 的关系

Setup 流程使用 Profile 配置来执行智能安装。Profile 提供了三种安装模式：

资料来源：src/cli/commands/setup.ts:21-35

架构设计

数据模型

graph TD
    A[用户意图配置 Profile] --> B[SetupAgent 代理类型]
    A --> C[AgentProfile 配置属性]
    B --> D[codex]
    B --> E[claude-code]
    B --> F[gemini]
    C --> G[agent 标识符]
    C --> H[displayName 显示名称]
    C --> I[defaultRootEnv 默认环境变量]
    C --> J[defaultRootDir 默认根目录]
    C --> K[instructionFileName 指令文件名]
    C --> L[commandTargetDir 命令目标目录]
    C --> M[mcpTargetDir MCP目标目录]

配置属性详解

#### SetupAgent 类型定义

type SetupAgent = "codex" | "claude" | "claude-code" | "gemini";

支持的编码代理类型：

资料来源：src/cli/commands/setup.ts:5-25

#### AgentProfile 完整配置

资料来源：src/cli/commands/setup.ts:37-58

配置数据结构

profiles.json 文件结构

{
  "profiles": {
    "<profile-name>": {
      "agent": "codex|claude|claude-code|gemini",
      "displayName": "Human Readable Name",
      "description": "Profile description",
      "skills": ["skill-name-1", "skill-name-2"],
      "commands": ["command-name-1", "command-name-2"],
      "pluginBundles": ["bundle-name-1", "bundle-name-2"],
      "mcpServers": ["mcp-server-name-1"]
    }
  }
}

资料来源：docs/profiles-schema.md

内置 Profile 配置

#### 最小技能集 (MINIMAL_SKILLS)

const MINIMAL_SKILLS = [
  "using-powerups",           // 学会使用 powerups
  "no-fluff",                 // 简洁输出
  "repo-map",                 // 仓库地图
  "writing-plans",            // 编写计划
  "verification-before-completion",  // 完成前验证
  "search-before-building",   // 构建前搜索
] as const;

#### 推荐插件捆绑包 (RECOMMENDED_PLUGIN_BUNDLES)

const RECOMMENDED_PLUGIN_BUNDLES = [
  "dev-vitals",           // 开发活力指标
  "debugging-diagnostics", // 调试诊断
  "quality-gates"         // 质量门禁
] as const;

资料来源：src/cli/commands/setup.ts:60-68

命令行接口

apx profiles 命令

apx profiles list              # 列出所有可用配置
apx profiles show <name>       # 显示指定配置详情
apx profiles validate          # 验证配置语法

资料来源：src/cli/apx.ts:28-32

profiles.ts 命令实现

graph LR
    A[apx profiles] --> B{子命令}
    B --> C[list 列出]
    B --> D[show 显示]
    B --> E[validate 验证]
    C --> F[读取 profiles.json]
    D --> G[解析指定配置]
    E --> H[Schema 校验]

资料来源：src/cli/commands/profiles.ts

使用场景

场景一：快速初始化新代理

# 列出可用配置
apx profiles list

# 使用推荐配置初始化 Claude Code
apx setup claude-code --mode recommended --yes

场景二：切换工作环境

# 为数据科学项目切换到 ML 配置
apx profiles set ml-project

# 为开源维护切换配置
apx profiles set open-source-maintainer

场景三：自定义配置创建

1. 读取现有配置模板
2. 修改技能和插件列表
3. 验证配置语法
4. 应用新配置

安全模型

用户意图配置遵循 Agent Powerups 的安全边界：

• 配置仅定义技能和插件的引用，不包含敏感信息
• 实际的工具安装需要用户显式批准
• MCP 服务器启用需要独立确认
• 外部工具安装受 dry-run 模式保护

资料来源：docs/security-model.md

配置验证

Schema 校验规则

配置文件必须满足以下规则：

资料来源：src/cli/commands/profiles.ts

验证命令

# 验证配置文件
apx profiles validate

# 验证并显示详细错误
apx profiles validate --verbose

扩展机制

自定义 Profile

用户可以通过在项目根目录创建 profiles.local.json 来扩展内置配置：

{
  "extends": "recommended",
  "skills": ["additional-skill-1"],
  "pluginBundles": ["custom-bundle"]
}

Profile 继承

Profile 支持基础配置继承，允许用户基于现有配置创建变体：

graph TD
    A[base-profile] --> B[recommended]
    A --> C[minimal]
    B --> D[codex-recommended]
    B --> E[claude-recommended]
    C --> F[codex-minimal]
    C --> G[claude-minimal]

故障排查

常见问题

诊断命令

# 医生检查
apx doctor

# 列出已安装配置
apx profiles list --installed

# 显示配置详细信息
apx profiles show <name> --verbose

相关资源

• 安装文档
• 安全模型
• Setup 指南
• 插件系统
• 技能目录

Pitfall Log / 踩坑日志

项目：yeaight7/agent-powerups

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 agent-powerups 与安装入口 markitdown 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：pip install markitdown
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown

2. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：v0.1.4

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown