# https://github.com/yeaight7/agent-powerups 项目说明书
生成时间：2026-05-13 03:27:06 UTC
## 目录
- [项目概览](#overview)
- [安装指南](#installation)
- [apx CLI 参考](#cli-reference)
- [资产目录系统](#catalog-system)
- [插件包系统](#plugin-bundles)
- [技能系统](#skills)
- [命令系统](#commands)
- [钩子系统](#hooks)
- [MCP 配置管理](#mcp-configs)
- [用户意图配置](#profiles)
## 项目概览
### 相关页面
相关主题：[安装指南](#installation), [资产目录系统](#catalog-system)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
# 项目概览
## 1. 项目简介
Agent Powerups 是一个面向编码智能体（coding agents）的可重用技能集合，采用与 Oh My Zsh 相似的设计理念。该项目旨在为各种编码智能体（如 Codex、Claude Code、 Gemini）提供标准化的技能、命令、配置和工作流扩展方案。
### 1.1 核心定位
| 维度 | 描述 |
|------|------|
| 项目性质 | 智能体扩展工具包 |
| 设计理念 | Oh My Zsh 风格的可复用组件集合 |
| 支持平台 | Codex、Claude Code、 Gemini |
| 安装方式 | npm 包本地安装（`apx` CLI） |
| 资料来源：[README.md:1-15] |
### 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 系统架构图
```mermaid
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` 是项目的核心命令行工具，提供以下主要命令：
| 命令 | 功能描述 |
|------|----------|
| `apx list` | 列出所有可用技能和资源 |
| `apx info ` | 查看特定技能/资源的详细信息 |
| `apx check ` | 验证技能或资源的配置状态 |
| `apx setup ` | 将 Agent Powerups 安装到指定智能体 |
| `apx doctor` | 运行诊断检查，验证环境完整性 |
| `apx security-audit` | 扫描安全风险模式 |
| `apx plugins list` | 列出所有插件包 |
| `apx plugins install` | 安装插件到目标智能体 |
| `apx commands run` | 执行命令包 |
| `apx hooks run` | 运行钩子脚本 |
| `apx mcp check/smoke/install` | MCP 服务器检查和安装 |
资料来源：[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` 文件定义。
```mermaid
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 预置技能分类
| 类别 | 技能列表 |
|------|----------|
| 调试分析 | `systematic-debugging`、`bug-hunt`、`safe-refactor` |
| 代码质量 | `no-fluff`、`quality-gates`、`sql-business-logic-review` |
| 规划协作 | `writing-plans`、`requesting-code-review`、`receiving-code-review`、`pr-triage` |
| 数据工程 | `bigquery-cost-audit`、`dbt-incremental-strategy-audit`、`dbt-preflight`、`dbt-strategy`、`data-quality`、`metric-impact-analyzer` |
| 智能体协作 | `ask-claude`、`ask-gemini`、`ask-codex`、`using-powerups`、`graphify` |
| 内容处理 | `ai-slop-cleaner`、`defuddle`、`markitdown-file-intake`、`repo-map` |
资料来源：[README.md:85-95]
### 3.3 技能验证机制
项目提供多层次的技能验证：
1. **结构验证**：检查 `SKILL.md` 文件是否存在
2. **元数据验证**：确保 frontmatter 包含必需的 `name` 和 `description` 字段
3. **引用验证**：检查技能中引用的支持文件是否存在
4. **目录验证**：确保技能目录下文件结构完整
```typescript
// 验证逻辑伪代码
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 插件包结构
插件包采用多智能体兼容结构：
```
/
├── .claude-plugin/
│ └── plugin.json # Claude Code 清单
├── .codex-plugin/
│ └── plugin.json # Codex 清单
├── skills/
│ └── /
│ └── SKILL.md
├── agents/
│ └── .md
└── commands/
└── .md
```
资料来源：[plugins/README.md:20-35]
### 4.2 插件状态分类
| 状态 | 数量 | 插件示例 |
|------|------|----------|
| 稳定版 | 3 | `dev-vitals`、`debugging-diagnostics`、`quality-gates` |
| 测试版 | 10 | `codebase-maintenance`、`data-engineering`、`documentation-systems` 等 |
| 实验版 | 4 | `software-engineering`、`agentic-systems`、`security-guardrails` 等 |
资料来源：[README.md:110-120]
### 4.3 插件操作命令
```sh
apx plugins list # 列出所有插件
apx plugins info # 查看插件详情
apx plugins validate --all # 验证所有插件结构
apx plugins install --target codex --dry-run # 预览安装
apx plugins install --target claude-code # 安装到 Claude Code
```
## 5. 安装与配置
### 5.1 安装模式
`apx setup` 命令支持三种安装模式：
| 模式 | 描述 | 覆盖范围 |
|------|------|----------|
| `minimal` | 引导模式 | 仅基础指令文件 |
| `recommended` | 推荐模式 | 技能、插件、命令等核心资源 |
| `full` | 完整模式 | 全部资源及支持文件 |
资料来源：[src/cli/commands/setup.ts:15-50]
### 5.2 目标智能体支持
```sh
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 安装流程
```mermaid
graph TD
A[apx setup ] --> 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` 命令实现多层次安全扫描：
| 规则名称 | 严重级别 | 检测模式 |
|----------|----------|----------|
| `broad-filesystem-write` | P1 | 递归删除或广泛文件写入 |
| `missing-dry-run` | P1 | install 命令缺少 --dry-run |
| `unpinned-latest-image` | P2 | CI 配置中使用 :latest 镜像 |
资料来源：[src/cli/commands/security-audit.ts:1-30]
### 6.2 安全检查范围
```typescript
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` 提供全面的环境诊断：
| 检查项 | 验证内容 |
|--------|----------|
| `apx` 二进制 | 验证 CLI 可执行文件 |
| 依赖项 | 检查所需工具是否安装 |
| 配置文件 | 验证配置完整性 |
| 技能文件 | 检查 SKILL.md 和元数据 |
| 外部检查 | 运行外部验证脚本 |
资料来源：[src/cli/commands/doctor.ts:1-60]
### 7.2 check 命令功能
```typescript
interface CheckResult {
exitCode: number; // 0=成功, 1=失败
output: string; // 输出信息
warnings: string[]; // 警告列表
actions: string[]; // 建议操作
}
```
check 命令支持：
- 批量检查多个资产
- 验证依赖项状态
- 自动安装缺失依赖（可选）
资料来源：[src/cli/commands/check.ts:1-30]
## 8. 兼容性矩阵
| 资产类别 | 当前状态 | 兼容性说明 |
|----------|----------|------------|
| 根 `skills/` | 已发布 | 通用文本技能，部分提及已知智能体 |
| `mcp/` | 已发布 | 本地优先 MCP 配置 |
| 插件包 | 已发布 | 按目标智能体分类 |
| 验证脚本 | 已发布 | Python 脚本 |
## 9. 快速开始
### 9.1 环境准备
```sh
# 安装依赖
npm install
npm run build
npm link
# 验证安装
apx doctor
```
### 9.2 基本工作流
```sh
# 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 本地智能体咨询
```sh
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 工具，用户可灵活选择安装哪些技能和插件到目标智能体环境中。
---
## 安装指南
### 相关页面
相关主题：[apx CLI 参考](#cli-reference), [用户意图配置](#profiles)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)
- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)
- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)
- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
# 安装指南
## 概述
Agent Powerups 是一个面向编程代理的 Oh My Zsh 风格工具集，提供了可复用的技能、命令、MCP 配置、钩子、AGENTS.md 模板和工作流。本指南将详细介绍如何在不同环境下安装和配置 Agent Powerups。
安装的核心目标是：将仓库中的资产（skills、plugins、commands、hooks 等）安全地部署到目标代理的工作目录中，同时保持灵活性和可控性。
## 系统要求
### 基础依赖
| 依赖项 | 版本要求 | 说明 |
|--------|----------|------|
| Node.js | 最新稳定版 | CLI 工具运行所需 |
| npm | 最新稳定版 | 用于安装 apx CLI |
| Python | 3.x | 部分验证脚本需要 |
| Git | 最新稳定版 | 用于仓库克隆和更新 |
安装前请运行 `apx doctor` 命令检查环境配置是否满足要求。
## 安装方法
### 方法一：通过 npm 全局安装 apx CLI
apx 是 Agent Powerups 的命令行工具，提供资产发现、检验、安装和配置等功能。
```sh
npm install -g agent-powerups
```
安装完成后，验证安装：
```sh
apx doctor
apx --version
```
### 方法二：从源码构建
适用于需要自定义或参与开发的用户：
```sh
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。不同的代理有不同的目录结构和配置方式。
### 支持的目标代理
| 代理类型 | 安装目标目录 | 配置说明 |
|----------|--------------|----------|
| codex | `/skills/` | 技能安装到代理根目录 |
| claude | `/plugins/` | Claude 插件安装 |
| claude-code | `/plugins/` | Claude Code 插件安装 |
| gemini | `/extensions/` | Gemini 扩展安装 |
### Dry-Run 模式
在执行任何实际修改前，强烈建议先使用 dry-run 模式预览安装操作：
```sh
apx setup codex --dry-run
apx setup claude-code --dry-run
apx setup gemini --dry-run
```
这将显示将要执行的操作而不实际修改文件系统。
### 最小化安装（Bootstrap）
仅安装最基础的资产，适合首次试用或受限环境：
```sh
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）
安装推荐的技能和插件集合，适合大多数用户：
```sh
apx setup codex --mode recommended --yes
apx setup claude-code --mode recommended --yes
apx setup gemini --mode recommended --yes
```
### 完整安装（Full）
安装所有可用资产，包括完整的插件包和辅助资源：
```sh
apx setup codex --mode full --yes
apx setup claude-code --mode full --yes
apx setup gemini --mode full --yes
```
## 手动原生安装
### 基本手动安装
```sh
apx install [--verbose]
```
### 完整手动安装
```sh
apx install --full [--verbose]
```
| 参数 | 说明 |
|------|------|
| `--verbose` | 显示每个文件的详细安装路径 |
| `--full` | 同时安装支持资产并更新全局指令 |
默认手动安装行为：
- 根目录 `skills/` → `/skills/`
- Codex/Claude 插件包 → `/plugins/`
- Gemini 插件包 → `/extensions/`
资料来源：[README.md:quickstart]()
## 插件包安装
Agent Powerups 采用插件包（Plugin Bundles）架构管理相关技能和配置。
### 插件包状态分类
| 状态 | 数量 | 说明 |
|------|------|------|
| Stable（稳定） | 3 个 | 经过充分测试，生产可用 |
| Beta（测试） | 10 个 | 功能完整，正在收尾稳定性 |
| Experimental（实验） | 4 个 | 早期功能，可能有变更 |
### 稳定版插件包
- `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`
### 插件包操作命令
```sh
# 列出所有插件包
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 配置命令
```sh
# 列出可用的 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 配置，含检查、冒烟测试和显式安装命令
## 目录结构说明
### 标准安装后的目录结构
```
/
├── 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]()
## 验证与检查
### 安装后验证
安装完成后，运行以下命令验证：
```sh
# 检查 apx 工具状态
apx doctor
# 列出已安装资产
apx list
# 查看特定技能详情
apx info using-powerups
# 检查技能完整性
apx check using-powerups
# 运行安全审计
apx security-audit
```
### 仓库验证脚本
```sh
python scripts/validate-skills.py
python scripts/validate-catalog.py
python scripts/check-requirements.py
```
### 配置检查
```sh
# 运行需求检查
apx check
# 安装缺失的依赖
apx check --install-missing --yes
# 查看需求详情
apx check --verbose
```
资料来源：[src/cli/commands/check.ts]()
## 用户意图配置文件
用户意图配置文件（Profiles）提供预定义的能力组合，适合特定使用场景。
### Profile 操作命令
```sh
# 列出所有配置文件
apx profiles list
# 查看配置文件详情
apx profiles info safe-core
```
### 内置配置文件
- `safe-core` - 安全核心配置，包含最基础的技能和检查
## 安装流程图
```mermaid
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 配置可能扩展工具访问范围
- 安装命令可能修改本地环境
- 切勿将密钥粘贴到代理上下文中
### 安全审计命令
```sh
apx security-audit
```
此命令会扫描以下高风险模式：
| 检查项 | 严重级别 | 说明 |
|--------|----------|------|
| `unpinned-latest-image` | P1 | CI 配置中使用未固定版本的 :latest 镜像 |
| `broad-filesystem-write` | P1 | 宽泛的文件系统写入或递归删除模式 |
| `missing-dry-run` | P1 | 安装命令缺少 --dry-run 保护 |
资料来源：[src/cli/commands/security-audit.ts]()
## 故障排除
### 常见问题
**Q: apx 命令未找到**
```sh
npm install -g agent-powerups
# 或
npm link # 如果从源码安装
```
**Q: 安装后代理无法识别技能**
检查代理根目录下是否正确创建了 skills/ 目录，并确认 AGENTS.md 中包含了 agent-powerups 指令块。
**Q: MCP 配置安装失败**
```sh
apx mcp check github-local --target --json
apx mcp smoke github-local --json
```
### 完整回滚
如需完全移除安装的资产：
```sh
# 对于 Codex
Remove-Item \agent-powerups -Recurse -Force
# 对于 Claude Code
Remove-Item \agent-powerups -Recurse -Force
```
资料来源：[examples/minimal/README.md]()
## 相关资源
- [快速开始指南](./README.md#quickstart)
- [安全模型说明](./docs/security-model.md)
- [兼容性矩阵](./docs/compatibility.md)
- [贡献指南](./CONTRIBUTING.md)
- [API 文档](../src/cli/apx.ts)
---
## apx CLI 参考
### 相关页面
相关主题：[安装指南](#installation), [资产目录系统](#catalog-system), [插件包系统](#plugin-bundles)
相关源码文件
以下源码文件用于生成本页说明：
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
- [src/cli/commands/phase-workflows.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/phase-workflows.ts)
- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)
# apx CLI 参考
## 概述
`apx` 是 agent-powerups 项目的核心命令行工具，提供类似 Oh My Zsh 的体验，为编码代理（coding agents）提供可复用的技能、命令、工作流和配置管理能力。该工具以 TypeScript 开发，通过 npm 包发布，旨在标准化和简化各类编码代理的环境配置与日常操作。
`apx` 的设计理念强调**本地优先（local-first）**、**安全审计（security-first）**和**渐进式配置（progressive setup）**，支持干运行（dry-run）、交互式确认和幂等操作。
## 核心功能模块
| 模块 | 功能描述 | 典型场景 |
|------|----------|----------|
| `install` | 安装技能和插件到指定代理根目录 | 快速部署一套完整的开发环境 |
| `setup` | 代理托管式配置，支持多模式 | 引导式安装，适合不熟悉命令行的用户 |
| `mcp` | MCP 服务器配置管理 | GitHub MCP 的本地检查、烟雾测试和安装 |
| `agents-md` | AGENTS.md 模板管理 | 初始化新项目的代理指令模板 |
| `commands` | 命令包管理和执行 | 自动化代码审查和发布检查 |
| `hooks` | 钩子脚本管理 | 代码提交前的安全预检 |
| `workflows` | 工作流编排 | 自动化项目迭代和部署流程 |
| `plugins` | 插件包管理 | 安装和管理第三方扩展插件 |
| `profiles` | 用户意图配置集 | 预定义的安全核心配置组合 |
| `check` | 依赖检查 | 验证技能所需工具是否满足 |
| `ask-*` | 多代理咨询 | 向 Codex/Claude/Gemini 发送请求 |
| `relay` | 持久化中继会话 | 跨轮次保持上下文状态 |
| `security-audit` | 安全审计 | 扫描代码库中的安全隐患 |
## 架构概览
```mermaid
graph TD
A["用户终端"] --> B["apx CLI 入口
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
代理托管式安装"]
F --> N["MCP 配置管理"]
G --> O["requirements.ts
依赖检查"]
H --> P["外部代理 API"]
I --> Q["持久会话状态"]
J --> R["插件bundles"]
K --> S["用户意图配置"]
L --> T["目标代理根目录
codex / claude-code / gemini"]
M --> T
N --> U["github-local MCP"]
O --> V["npm / pip / cargo
依赖解析"]
```
## 命令速查表
### 安装与配置
| 命令 | 说明 | 关键参数 |
|------|------|----------|
| `apx install ` | 安装到指定代理 | `--dry-run`, `--full`, `--verbose`, `--agent-root` |
| `apx install --target ` | 安装单个资产 | `--dry-run`, `--dest` |
| `apx setup --mode ` | 代理托管式配置 | `--mode minimal\|recommended\|full`, `--dry-run`, `--yes` |
| `apx mcp install --target ` | 安装 MCP 配置 | `--dry-run`, `--yes`, `--dest` |
### 查询与列表
| 命令 | 说明 | 关键参数 |
|------|------|----------|
| `apx list` | 列出所有可用技能 | - |
| `apx info ` | 查看技能详情 | - |
| `apx check ` | 检查技能依赖 | `--install-missing`, `--dry-run` |
| `apx mcp list` | 列出 MCP 配置 | - |
| `apx agents-md list` | 列出 AGENTS.md 模板 | - |
| `apx commands list` | 列出命令包 | - |
| `apx hooks list` | 列出钩子 | - |
| `apx workflows list` | 列出工作流 | - |
| `apx plugins list` | 列出插件包 | - |
| `apx profiles list` | 列出配置集 | - |
### 执行与操作
| 命令 | 说明 | 关键参数 |
|------|------|----------|
| `apx ask-codex ""` | 询问 Codex | `--json` |
| `apx ask-claude ""` | 询问 Claude | `--json` |
| `apx ask-gemini ""` | 询问 Gemini | `--json` |
| `apx relay init ` | 初始化中继会话 | - |
| `apx relay start --provider ` | 启动中继 | `--json` |
| `apx relay ask ""` | 通过中继询问 | `--json` |
| `apx commands run ship-check` | 运行发货检查 | `--full`, `--json` |
| `apx hooks run no-secrets-preflight` | 运行无密钥预检 | `--path`, `--all`, `--json` |
| `apx phase ` | 阶段式工作流 | `discuss`, `plan`, `execute`, `verify` |
### 验证与审计
| 命令 | 说明 | 关键参数 |
|------|------|----------|
| `apx doctor` | 诊断 apx 自身状态 | `--full`, `--json` |
| `apx mcp check ` | 检查 MCP 配置 | `--target`, `--json` |
| `apx mcp smoke ` | 烟雾测试 MCP | `--json` |
| `apx security-audit --path ` | 安全审计 | `--all`, `--json` |
| `apx audit repo` | 仓库审计 | `--json` |
| `apx plugin validate ` | 验证插件 | `--json` |
## 详细命令说明
### install - 资产安装
`install` 命令是 apx 的核心命令之一，用于将技能、插件和配置安装到指定代理的根目录。
```mermaid
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["完成"]
```
**安装模式对比：**
| 模式 | 说明 | 适用范围 |
|------|------|----------|
| 默认安装 | 仅复制 skills 和 plugins bundles | 常规使用 |
| `--full` | 完整安装，包含 support assets 和全局指令更新 | 深度集成 |
| `--verbose` | 显示每个文件的复制路径 | 调试排查 |
**命令示例：**
```bash
# 干运行查看安装计划
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` 命令提供引导式配置体验，支持三种预设模式，自动生成配置指令。
```mermaid
graph TD
A["apx setup "] --> 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["追加到现有文件
备份 .bak"]
I -->|不存在| K["创建 agent-powerups.md"]
J --> L["完成"]
K --> L
```
**配置模式说明：**
| 模式 | 内容 | 推荐场景 |
|------|------|----------|
| `minimal` | 引导用户读取 using-powerups、apx 使用说明、MCP 审批提示 | 新用户快速体验 |
| `recommended` | minimal + 技能路径说明 + 推荐命令提示 | 大多数用户的推荐选择 |
| `full` | 全功能说明和最佳实践 | 深度用户和自动化场景 |
资料来源：[src/cli/commands/setup.ts:50-100]()
### mcp - MCP 服务器配置
MCP（Model Context Protocol）配置管理提供本地 GitHub MCP 的检查、烟雾测试和安装能力。
| 子命令 | 功能 |
|--------|------|
| `apx mcp list` | 列出可用 MCP 配置 |
| `apx mcp print --target ` | 打印配置详情 |
| `apx mcp check --target ` | 验证配置有效性 |
| `apx mcp smoke ` | 执行烟雾测试 |
| `apx mcp install --target ` | 安装到目标代理 |
| `apx mcp write --target --dest ` | 导出配置到指定路径 |
**工作流程：**
```mermaid
graph LR
A["mcp check"] --> B{"配置有效?"}
B -->|是| C["mcp smoke"]
B -->|否| D["报告错误"]
C --> E{"烟雾测试通过?"}
E -->|是| F["mcp install"]
E -->|否| G["报告问题"]
F --> H["完成"]
```
### check - 依赖检查
`check` 命令验证技能所需工具是否已安装，支持自动安装缺失依赖。
```mermaid
graph TD
A["apx check "] --> 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` 函数负责解析缺失依赖，并调用对应的包管理器：
| 包管理器 | 探测命令 | 参数 |
|----------|----------|------|
| npm | `npm install` | `-g` 全局或本地 |
| pip | `pip install` | `-q` 静默模式 |
| cargo | `cargo install` | - |
| gem | `gem install` | `-N` 不生成文档 |
资料来源：[src/cli/commands/check.ts:30-80]()
资料来源：[src/cli/utils/requirements.ts:1-60]()
### ask-* - 多代理咨询
`ask-*` 命令提供统一的接口向外部编码代理发送请求：
| 命令 | 代理 | 输出格式 |
|------|------|----------|
| `apx ask-codex` | OpenAI Codex | JSON 或文本 |
| `apx ask-claude` | Anthropic Claude | JSON 或文本 |
| `apx ask-gemini` | Google Gemini | JSON 或文本 |
**使用场景：**
```bash
# 询问代码解释
apx ask-codex "Explain this code" --json
# 代码审查
apx ask-claude "Review this patch" --json
# 头脑风暴测试用例
apx ask-gemini "Brainstorm test cases" --json
```
### relay - 持久中继会话
`relay` 命令维护跨轮次的持久会话，保持上下文状态，特别适合需要多轮协作的场景。
```mermaid
graph TD
A["relay init "] --> B["创建会话状态"]
B --> C["relay start --provider "]
C --> D["建立持久连接"]
D --> E["relay ask ''"]
E --> F["发送消息"]
F --> G["接收响应"]
G --> H{"需要继续?"}
H -->|是| E
H -->|否| I["relay stop "]
```
**中继会话管理：**
| 子命令 | 说明 |
|--------|------|
| `relay init ` | 初始化新会话 |
| `relay start --provider ` | 启动会话 |
| `relay ask ""` | 发送消息 |
| `relay status ` | 查看状态 |
| `relay stop ` | 停止会话 |
### security-audit - 安全审计
`security-audit` 命令扫描代码库中的常见安全风险，包括硬编码密钥、不安全的 shell 命令和不推荐的镜像标签。
**支持的检测规则：**
| 规则名称 | 严重级别 | 检测模式 |
|----------|----------|----------|
| `api-key-detected` | P0 | 常见 API 密钥格式 |
| `private-key-detected` | P0 | RSA/ED25519 私钥 |
| `aws-access-key` | P0 | AWS 访问密钥 |
| `aws-secret-key` | P0 | AWS 密钥 ID |
| `github-token` | P0 | GitHub Token |
| `broad-filesystem-write` | P1 | 递归删除或通配符写 |
| `missing-dry-run` | P1 | 安装命令缺少 --dry-run |
**扫描范围：**
- 文件扩展白名单：`.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` 命令实现项目开发的阶段化工作流，支持讨论、计划、执行和验证阶段。
```mermaid
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["完成"]
```
**阶段子命令：**
| 子命令 | 说明 | 关键参数 |
|--------|------|----------|
| `phase discuss ` | 讨论指定阶段 | `--planning-root`, `--json` |
| `phase plan ` | 制定计划 | `--research`, `--prd`, `--mvp` |
| `phase execute ` | 执行计划 | `--wave`, `--interactive` |
| `phase verify ` | 验证结果 | - |
资料来源：[src/cli/commands/phase-workflows.ts:1-40]()
## 代理目标
apx 支持多个编码代理平台作为安装目标：
| 目标标识 | 代理产品 | 配置目录 |
|----------|----------|----------|
| `codex` | OpenAI Codex | `~/.codex/` |
| `claude-code` | Claude Code | `~/.claude/` |
| `gemini` | Google Gemini CLI | `~/.gemini/` |
| `generic` | 通用目标 | 用户指定 |
安装时通过 `--target ` 参数指定目标，未指定时使用对应代理的默认配置目录。
## 输出格式
大多数 apx 命令支持 JSON 输出，便于脚本集成和自动化处理：
```bash
# 获取 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 服务器**：需要显式启用确认
### 诊断工具
```bash
# 基础诊断
apx doctor
# 完整诊断（JSON）
apx doctor --full --json
# 仓库审计
apx audit repo --json
```
## 快速参考
### 首次使用
```bash
npm install
npm run build
npm link
apx doctor
apx list
```
### 常见工作流
**部署到 Codex：**
```bash
apx setup codex --mode recommended --yes
```
**检查技能依赖：**
```bash
apx check markitdown-file-intake
apx check defuddle --install-missing --dry-run
```
**运行安全扫描：**
```bash
apx security-audit --path ./src
apx hooks run no-secrets-preflight --all
```
**多代理咨询：**
```bash
apx ask-claude "Review this PR" --json
apx relay start second-opinion --provider gemini
apx relay ask second-opinion "Analyze this architecture" --json
---
## 资产目录系统
### 相关页面
相关主题：[技能系统](#skills), [apx CLI 参考](#cli-reference), [插件包系统](#plugin-bundles)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
- [catalog.json](https://github.com/yeaight7/agent-powerups/blob/main/catalog.json)
- [docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)
- [scripts/validate-skills.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-skills.py)
- [scripts/validate-catalog.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-catalog.py)
- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)
# 资产目录系统
## 概述
Agent Powerups 的资产目录系统是一个集中管理、可验证的资产清单，涵盖可复用的技能、工作流、命令模板、MCP 配置和 AGENTS.md 模板。该系统采用声明式 JSON 格式定义所有资产元数据，并通过自动化验证脚本确保目录内容的完整性和一致性。资产目录的核心价值在于为编码代理提供"Oh My Zsh 风格"的可插拔组件库，开发者可以通过 `apx` CLI 工具浏览、安装和验证这些资产。
## 目录架构
资产目录采用分层架构设计，将不同类型的资产分别归类管理：
```mermaid
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/` | 已发布 | 可复用代理工作流，如 `systematic-debugging`、`writing-plans` |
| `mcp/` | 已发布 | 本地优先 GitHub MCP 配置，含检查、冒烟测试和显式安装命令 |
| `agents-md/` | 已发布 | 启动器 AGENTS.md 模板 |
| `commands/` | 已发布 | 审查优先命令提示词及安全可运行检查 |
| `hooks/` | 已发布 | 钩子示例：preflight、summary、validation |
| `workflows/` | 已发布 | 工作流定义：feature-iteration、agent-relay |
| `plugins/` | 已发布 | 17个插件包（3个稳定版、10个测试版、4个实验版） |
## 目录清单结构
### 技能资产 (Skills)
当前已发布的技能共 23 个，涵盖调试、规划、代码审查、数据工程等多个领域：
| 技能名称 | 功能分类 |
|----------|----------|
| `systematic-debugging` | 调试 |
| `no-fluff` | 文档 |
| `writing-plans` | 规划 |
| `ai-slop-cleaner` | 文档 |
| `bigquery-cost-audit` | 数据工程 |
| `data-quality` | 数据工程 |
| `dbt-incremental-strategy-audit` | 数据工程 |
| `dbt-preflight` | 数据工程 |
| `dbt-strategy` | 数据工程 |
| `metric-impact-analyzer` | 分析 |
| `requesting-code-review` | 协作 |
| `receiving-code-review` | 协作 |
| `pr-triage` | 协作 |
| `repo-map` | 导航 |
| `bug-hunt` | 调试 |
| `safe-refactor` | 重构 |
| `sql-business-logic-review` | 审查 |
| `defuddle` | 工具 |
| `markitdown-file-intake` | 工具 |
| `graphify` | 可视化 |
| `ask-claude` | 集成 |
| `ask-gemini` | 集成 |
| `ask-codex` | 集成 |
| `using-powerups` | 入门 |
资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
### 插件包资产 (Plugin Bundles)
插件包是技能、代理和命令的组合，按成熟度分为三个等级：
#### 稳定版插件包 (Stable)
| 插件包名称 | 描述 |
|------------|------|
| `dev-vitals` | 开发健康指标 |
| `debugging-diagnostics` | 调试诊断 |
| `quality-gates` | 质量门禁 |
#### 测试版插件包 (Beta)
| 插件包名称 | 描述 |
|------------|------|
| `codebase-maintenance` | 代码库维护 |
| `data-engineering` | 数据工程 |
| `documentation-systems` | 文档系统 |
| `machine-learning-ops` | 机器学习运维 |
| `codebase-intelligence` | 代码库智能 |
| `spec-driven-development` | 规范驱动开发 |
| `spec-quality-gates` | 对抗性计划验证和结构化代码审查 |
| `context-efficiency` | 上下文高效调度路由 |
| `tool-integrations` | 工具集成 |
| `memory-optimization` | 内存优化 |
#### 实验版插件包 (Experimental)
| 插件包名称 | 描述 |
|------------|------|
| `software-engineering` | 软件工程 |
| `agentic-systems` | 代理系统 |
| `security-guardrails` | 安全护栏 |
| `agent-evaluation-lab` | 代理评估实验室 |
每个插件遵循标准编码代理插件布局：
```
/
├── .claude-plugin/
│ └── plugin.json # Claude Code 清单
├── .codex-plugin/
│ └── plugin.json # Codex 清单
├── skills/
│ └── /
│ └── SKILL.md
├── agents/
│ └── .md
└── commands/
└── .md
```
资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
### AGENTS.md 模板资产
| 模板名称 | 适用场景 |
|----------|----------|
| `typescript-app` | TypeScript 应用开发 |
| `python-library` | Python 库开发 |
| `dbt-project` | dbt 数据转换项目 |
| `ml-project` | 机器学习项目 |
| `open-source-maintainer` | 开源项目维护 |
### 命令资产 (Commands)
| 命令包名称 | 功能 |
|------------|------|
| `ship-check` | 发布前检查 |
| `using-powerups-command` | Powerups 使用指导 |
### 钩子示例资产 (Hooks)
| 钩子名称 | 触发场景 |
|----------|----------|
| `no-secrets-preflight` | 提交前秘密检查 |
| `handoff-summary` | 交接摘要生成 |
| `validation-required` | 验证必需触发 |
### 工作流资产 (Workflows)
| 工作流名称 | 用途 |
|------------|------|
| `feature-iteration` | 功能迭代流程 |
| `agent-relay` | 代理中继通信 |
### MCP 配置资产
| 配置名称 | 说明 |
|----------|------|
| `github-local` | 本地 GitHub MCP 配置，含检查、冒烟测试和显式安装命令 |
## 目录验证机制
### 验证脚本体系
项目包含三个核心验证脚本，确保目录内容的有效性：
```mermaid
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` 必需字段
- 检查技能内容长度是否满足最小要求
- 验证支持文件的引用是否指向实际存在的文件
```sh
python scripts/validate-skills.py
```
资料来源：[scripts/validate-skills.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-skills.py)
#### 目录验证脚本 (validate-catalog.py)
`validate-catalog.py` 验证整个目录清单的正确性：
- 验证 `catalog.json` 格式是否符合 schema
- 确保所有声明的资产在文件系统中实际存在
- 检查资产引用的完整性
```sh
python scripts/validate-catalog.py
```
资料来源：[scripts/validate-catalog.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-catalog.py)
#### 依赖检查脚本 (check-requirements.py)
`check-requirements.py` 检查运行技能所需的依赖项：
- 识别缺失的外部依赖
- 提供安装提示（`installHint`）
- 支持自动安装可用的依赖
```sh
python scripts/check-requirements.py
```
资料来源：[src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
### 验证检查项
| 检查项 | 描述 | 状态码 |
|--------|------|--------|
| `skill-files` | SKILL.md 文件存在性 | OK/WARNING |
| `skill-frontmatter` | 必需 frontmatter 字段 | OK/WARNING |
| `skill-content-length` | 内容长度最小值 | WARN/OK |
| `catalog-schema` | catalog.json schema 符合性 | PASS/FAIL |
| `asset-existence` | 资产文件实际存在 | PASS/FAIL |
## CLI 命令集成
### 目录浏览命令
| 命令 | 功能 |
|------|------|
| `apx list` | 列出所有可用资产 |
| `apx info ` | 显示资产详细信息 |
| `apx check ` | 检查资产完整性 |
| `apx commands run ` | 运行指定命令 |
```sh
# 浏览目录
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 ` | 显示插件详情 |
| `apx plugins validate --all` | 验证所有插件结构 |
| `apx plugins install --target ` | 安装插件 |
```sh
apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target codex --dry-run
```
### 审计命令
`apx audit` 命令提供系统性的资产审计功能：
```sh
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 定义资产元数据规范，核心字段包括：
```json
{
"name": "资产名称",
"description": "资产描述",
"path": "相对于仓库根的路径",
"maturity": "stable|beta|experimental",
"tags": ["标签1", "标签2"],
"requires": {
"skills": ["依赖技能"],
"tools": ["依赖工具"]
}
}
```
资料来源：[docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)
## 安全考量
资产目录系统内置多层安全保护机制：
### 部署前检查
- 技能可指导代理读取本地文件或执行命令
- 钩子可在宿主代理支持时执行代码
- MCP 配置可扩展工具访问范围
- 安装命令可修改本地环境
### 安装保护
所有安装操作默认处于干运行模式，需要显式授权才能执行：
```sh
apx install codex --dry-run # 预览不执行
apx install codex # 实际执行
```
### 秘密管理
- 秘密绝不应粘贴到代理上下文，除非严格必要
- MCP 服务器需要显式用户批准
- 外部工具安装需要用户批准
## 与代理的集成
### 代理兼容性矩阵
| 资产类别 | 当前状态 | 兼容性声明 |
|----------|----------|------------|
| 根 `skills/` | 是 | 通用文本技能；部分提及已知代理表面 |
| `mcp/` | 是 | 提供特定代理的 MCP 配置 |
资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
### 支持的代理平台
| 代理平台 | 配置路径 | 说明 |
|----------|----------|------|
| Codex | `.codex-plugin/plugin.json` | Codex 清单定义 |
| Claude Code | `.claude-plugin/plugin.json` | Claude Code 清单定义 |
| Gemini | `gemini-extension.json` + `GEMINI.md` | Gemini 插件包 |
## 维护工作流
仓库维护应持续运行验证检查：
```mermaid
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[提交更改]
```
建议的维护命令序列：
```sh
python scripts/validate-skills.py
python scripts/validate-catalog.py
python scripts/check-requirements.py
```
## 总结
资产目录系统是 Agent Powerups 的核心基础设施，提供了一套完整、可验证的资产管理体系。通过声明式清单、自动化验证和 CLI 工具集成，开发者可以安全地发现、安装和使用预构建的代理资源。该系统支持多代理平台（Codex、Claude Code、Gemini），并通过插件包机制实现了资产的分层组织和按需扩展。
---
## 插件包系统
### 相关页面
相关主题：[资产目录系统](#catalog-system), [apx CLI 参考](#cli-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)
- [.claude-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.claude-plugin/marketplace.json)
- [.codex-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.codex-plugin/marketplace.json)
- [docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)
# 插件包系统
## 概述
插件包系统（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](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
## 插件包结构
### 目录布局
每个插件遵循标准的 coding agent 插件目录结构：
```
/
├── .claude-plugin/
│ └── plugin.json # Claude Code 平台清单
├── .codex-plugin/
│ └── plugin.json # Codex 平台清单
├── skills/
│ └── /
│ └── SKILL.md # 技能定义文件
├── agents/
│ └── .md # 代理模板文件
└── commands/
└── .md # 命令定义文件
```
根级别的 skills 位于 `skills/` 目录，是通用型独立技能。插件内的 skills 是领域专用的，提供更深入的功能覆盖。同一主题的插件技能不得替代或覆盖根级别技能。
资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
### Manifest 文件
每个插件包含针对不同 agent 平台的 manifest 文件，定义了插件的元数据和资源引用。
**Claude Code Manifest 示例结构：**
```json
{
"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 示例结构：**
```json
{
"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 属性）。
## 成熟度等级
插件包根据功能稳定性和适用场景分为三个成熟度等级：
| 等级 | 说明 | 风险级别 | 适用场景 |
|------|------|----------|----------|
| **stable** | 稳定版本，经过充分测试 | 低 | 生产环境推荐使用 |
| **beta** | 测试版本，功能基本可用 | 中 | 评估新功能，探索性项目 |
| **experimental** | 实验性版本，可能有破坏性变更 | 高 | 高级用户尝鲜，不建议生产使用 |
资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
## 插件包清单
当前仓库包含 17 个插件包，分布如下：
### 稳定版插件（Stable）
| 插件名称 | 描述 | Maturity |
|----------|------|----------|
| `dev-vitals` | 开发健康指标与监控 | stable |
| `debugging-diagnostics` | 调试与诊断技能集 | stable |
| `quality-gates` | 质量门禁检查流程 | stable |
### Beta 版插件
| 插件名称 | 描述 | Maturity |
|----------|------|----------|
| `codebase-maintenance` | 代码库维护任务集 | beta |
| `data-engineering` | 数据工程相关技能 | beta |
| `documentation-systems` | 文档系统生成与管理 | beta |
| `machine-learning-ops` | ML 运维工作流 | beta |
| `codebase-intelligence` | 代码库智能分析 | beta |
| `spec-driven-development` | 规范驱动的开发流程 | beta |
| `spec-quality-gates` | 对抗性计划验证与结构化代码审查 | beta |
| `context-efficiency` | 上下文高效的调度路由 | beta |
| `tool-integrations` | 工具集成扩展 | beta |
| `memory-optimization` | 内存优化策略 | beta |
### 实验版插件（Experimental）
| 插件名称 | 描述 | Maturity |
|----------|------|----------|
| `software-engineering` | 软件工程最佳实践 | experimental |
| `agentic-systems` | 代理系统设计模式 | experimental |
| `security-guardrails` | 安全防护机制 | experimental |
| `agent-evaluation-lab` | 代理评估实验框架 | experimental |
资料来源：[plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)
## 插件包元数据模式
插件包的元数据定义在 `plugin-bundles.json` 中，每个插件条目包含以下字段：
| 字段 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `name` | string | 是 | 插件唯一标识符 |
| `description` | string | 是 | 插件功能描述 |
| `maturity` | string | 是 | 成熟度等级：stable/beta/experimental |
| `readme` | string | 否 | 文档相对路径 |
| `skills` | array | 否 | 包含的技能列表 |
| `agents` | array | 否 | 包含的代理模板列表 |
| `commands` | array | 否 | 包含的命令列表 |
| `templates` | array | 否 | 包含的模板列表 |
| `workflows` | array | 否 | 包含的工作流列表 |
资料来源：[docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)
### 技能条目结构
```json
{
"name": "skill-name",
"description": "技能描述",
"path": "skills/skill-name"
}
```
### 代理模板条目结构
```json
{
"name": "agent-name",
"description": "代理模板描述",
"path": "agents/agent-name.md"
}
```
## 工作流程
### 插件安装流程
以下流程图展示了使用 `apx` CLI 安装插件的标准流程：
```mermaid
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
```
### 插件发现与检查流程
```mermaid
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 命令参考
### 插件列表
```bash
apx plugins list
```
列出所有可用的插件包，显示名称、描述和成熟度等级。
### 插件详情
```bash
apx plugins info
```
查看单个插件的详细元数据，包括包含的 skills、agents、commands 和 templates。
### 插件验证
```bash
apx plugins validate --all
```
验证所有插件的 manifest 文件结构是否符合规范，检查必需字段和文件路径。
### 插件安装
```bash
# 模拟安装（预览）
apx plugins install --target codex --dry-run
# 实际安装
apx plugins install --target codex --yes
```
将插件安装到指定的 agent 平台。`--target` 参数支持 `codex`、`claude-code`、`gemini` 或 `generic`。
### 插件构建
```bash
apx plugins build --dest --dry-run
apx plugins build --dest --write
```
根据当前仓库中的插件定义生成打包输出。`--dry-run` 模式生成预览，`--write` 模式执行实际写入。
### 插件差异对比
```bash
apx plugin diff
```
比较插件的实际目录结构与 manifest 声明的差异，识别缺失或未声明的资源文件。
资料来源：[src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
## Marketplace 配置
Marketplace 配置文件定义了插件的市场元数据，用于插件市场的发现和展示。
### Claude Code Marketplace 配置
```json
{
"plugins": [
{
"name": "dev-vitals",
"version": "1.0.0",
"description": "Development health metrics and monitoring",
"categories": ["diagnostics", "quality"],
"tags": ["monitoring", "metrics", "vitals"]
}
]
}
```
### Codex Marketplace 配置
```json
{
"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](https://github.com/yeaight7/agent-powerups/blob/main/.claude-plugin/marketplace.json)、[.codex-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.codex-plugin/marketplace.json)
## 根级技能与插件技能的关系
Agent Powerups 采用分层技能架构：
```mermaid
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/`）：通用型技能，专注于通用工作流程
- **插件技能**：领域专用技能，提供更深入的功能实现
插件技能与根级别技能是互补关系而非替代关系。同一主题的插件技能不会覆盖或替代根级别技能。
## 完整安装与插件安装的区别
| 维度 | `apx install ` | `apx plugins install ` |
|------|------------------------|--------------------------------|
| 范围 | 安装所有根级技能和全部插件包 | 仅安装指定的单个插件包 |
| 目标 | 全量初始化 agent 环境 | 按需添加特定领域功能 |
| 适用场景 | 全新环境搭建 | 功能扩展 |
| 灵活性 | 低（全部安装） | 高（按需选择） |
## 安全注意事项
- 插件可以指示 agent 读取本地文件或执行命令
- MCP 配置可以扩展工具访问权限
- 安装命令可以修改本地环境
- 敏感信息（secrets）不应粘贴到 agent 上下文中
在加载插件到受信任的 agent 环境之前，请务必审查插件内容。
资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
## 最佳实践
1. **安装前验证**：使用 `--dry-run` 模式预览安装计划
2. **分阶段安装**：从 stable 版本开始，逐步评估 beta 版本
3. **定期更新**：使用 `apx plugins validate --all` 检查插件完整性
4. **环境隔离**：使用 `--agent-root` 指定隔离环境进行测试
5. **备份配置**：重要 agent 配置文件在安装前进行备份
---
## 技能系统
### 相关页面
相关主题：[资产目录系统](#catalog-system), [命令系统](#commands), [钩子系统](#hooks)
相关源码文件
以下源码文件用于生成本页说明：
- [skills/systematic-debugging/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/systematic-debugging/SKILL.md)
- [skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)
- [skills/using-powerups/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/using-powerups/SKILL.md)
- [skills/skill-authoring-guide/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/skill-authoring-guide/SKILL.md)
- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
- [src/cli/commands/audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)
- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
# 技能系统
## 概述
技能系统（Skill System）是 Agent Powerups 的核心组件，为编码智能体提供可复用的任务工作流集合。该系统借鉴了 Oh My Zsh 的插件理念，为智能体提供结构化的任务指导、能力扩展和标准化工作流程。技能系统使编码智能体能够执行系统化调试、计划撰写、代码审查、数据质量检查等复杂任务，同时保持行为一致性和可维护性。
技能系统包含 24 个已发布的根技能，涵盖调试、规划、代码审查、数据工程、文档处理等多个领域。技能以 Markdown 文件形式存储，部署时直接复制到智能体的 skills 目录中供其调用。
## 技能分类
### 按功能领域分类
| 技能名称 | 功能领域 | 状态 |
|----------|----------|------|
| systematic-debugging | 调试 | 已发布 |
| bug-hunt | 调试 | 已发布 |
| writing-plans | 规划 | 已发布 |
| requesting-code-review | 代码审查 | 已发布 |
| receiving-code-review | 代码审查 | 已发布 |
| pr-triage | 代码审查 | 已发布 |
| sql-business-logic-review | 代码审查 | 已发布 |
| data-quality | 数据工程 | 已发布 |
| bigquery-cost-audit | 数据工程 | 已发布 |
| dbt-preflight | 数据工程 | 已发布 |
| dbt-strategy | 数据工程 | 已发布 |
| dbt-incremental-strategy-audit | 数据工程 | 已发布 |
| metric-impact-analyzer | 数据工程 | 已发布 |
| defuddle | 文档处理 | 已发布 |
| markitdown-file-intake | 文档处理 | 已发布 |
| ai-slop-cleaner | 文档处理 | 已发布 |
| repo-map | 代码理解 | 已发布 |
| graphify | 代码理解 | 已发布 |
| safe-refactor | 重构 | 已发布 |
| no-fluff | 质量检查 | 已发布 |
| ask-claude | 智能体协作 | 已发布 |
| ask-gemini | 智能体协作 | 已发布 |
| ask-codex | 智能体协作 | 已发布 |
| using-powerups | 系统引导 | 已发布 |
资料来源：[README.md](./README.md)
### 按来源分类
根技能（Root Skills）位于仓库根目录的 `skills/` 文件夹中，属于通用目的、可独立使用的技能。插件技能（Plugin Skills）位于 `plugins/` 目录下的各插件子目录中，属于领域特定且深度专精的技能。插件技能可能与根技能覆盖相同主题，但不应替换或覆盖根技能。
资料来源：[plugins/README.md](./plugins/README.md)
## 技能结构
### 文件组织
每个技能遵循标准的目录结构：
```
skills/
└── /
└── SKILL.md # 技能定义文件（必需）
└── support/ # 支持文件目录（可选）
└── # 技能引用的辅助资源
```
### SKILL.md 格式规范
SKILL.md 是技能的核心定义文件，包含前置matter元数据和技能内容。文件必须包含以下前置matter字段：
| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| name | string | 是 | 技能的唯一标识名称 |
| description | string | 是 | 技能的简要功能描述 |
| version | string | 否 | 技能版本号 |
| tags | array | 否 | 技能标签分类 |
前置matter 示例：
```yaml
---
name: systematic-debugging
description: A structured approach to debugging issues systematically
version: 1.0.0
tags: [debugging, workflow, quality]
---
```
资料来源：[src/cli/commands/doctor.ts:45-58](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
### 技能内容要求
技能文件必须满足以下内容质量标准：
- 技能内容长度不得低于最小阈值（由验证脚本定义）
- 技能内容必须包含明确的任务指导步骤
- 技能引用的支持文件必须存在
资料来源：[src/cli/commands/audit.ts:35-50](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)
## 技能生命周期
### 技能创作流程
技能创作遵循以下标准流程：
```mermaid
graph TD
A[创建 SKILL.md] --> B[定义前置matter]
B --> C[编写技能内容]
C --> D[添加支持文件]
D --> E[运行本地验证]
E --> F{验证结果}
F -->|通过| G[提交到仓库]
F -->|失败| C
G --> H[自动 CI 检查]
H --> I[发布到目录]
```
### 技能创作指南
技能创作指南（skill-authoring-guide）提供以下指导：
- 如何设计有效的技能结构
- 如何编写清晰的任务描述
- 如何创建可复用的工作流程
- 如何维护技能与其他技能的兼容性
资料来源：[skills/skill-authoring-guide/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/skill-authoring-guide/SKILL.md)
## 技能验证机制
### 验证层级
技能验证在多个层级进行，确保质量和一致性：
#### 1. 前置matter 验证
医生命令（doctor）检查每个技能的必要字段：
```typescript
if (!frontmatter?.name || !frontmatter?.description) {
issues.push(`${entry.name}: missing required frontmatter`);
}
```
资料来源：[src/cli/commands/doctor.ts:50-52](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
#### 2. 支持文件验证
医生命令验证技能引用的支持文件是否存在：
```typescript
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:53-56](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)
#### 3. 审计检查
审计命令（audit）执行全面的技能质量检查：
| 检查项 | 说明 |
|--------|------|
| skill-frontmatter | 验证所有技能都有 name 和 description |
| skill-content-length | 验证技能内容长度符合最小要求 |
```typescript
if (missingFrontmatter > 0) {
checks.push(fail("skill-frontmatter", `${missingFrontmatter} skill(s) missing name/description`));
} else {
checks.push(pass("skill-frontmatter", "all have name + description"));
}
if (tooShort > 0) {
checks.push(warn("skill-content-length", `${tooShort} skill(s) under ${MIN_CONTENT_LENGTH} chars`));
} else {
checks.push(pass("skill-content-length", "all skills meet minimum length"));
}
```
资料来源：[src/cli/commands/audit.ts:40-50](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)
### 验证脚本
仓库提供三个核心验证脚本：
| 脚本 | 功能 |
|------|------|
| `scripts/validate-skills.py` | 验证技能文件结构和格式 |
| `scripts/validate-catalog.py` | 验证技能目录完整性 |
| `scripts/check-requirements.py` | 检查技能依赖要求 |
资料来源：[README.md](./README.md)
## 技能安装与部署
### 安装方式
#### 手动安装
使用 apx CLI 安装技能到指定智能体：
```bash
# 安装到 Codex
apx install codex
# 安装到 Claude Code
apx install claude-code
# 安装到 Gemini
apx install gemini
```
默认安装将根目录的 `skills/` 复制到智能体根目录的 `skills/` 子目录。
#### 交互式安装
```bash
apx setup codex --mode recommended --yes
```
安装模式说明：
| 模式 | 说明 |
|------|------|
| minimal | 仅安装引导文件 |
| recommended | 安装推荐的核心技能集 |
| full | 安装全部技能和支持资产 |
资料来源：[README.md](./README.md)
### 目录映射
技能安装时的标准目录映射关系：
```mermaid
graph LR
A[仓库根目录] --> B[技能安装目标]
A1[skills/] --> B1[/skills/]
A2[plugins/] --> B2[/plugins/]
A3[agents-md/] --> B3[/agent-powerups/agents-md/]
A4[hooks/] --> B4[/agent-powerups/hooks/]
A5[workflows/] --> B5[/agent-powerups/workflows/]
A6[commands/generic/] --> B6[/agent-powerups/commands/generic/]
A7[mcp/generic/] --> B7[/agent-powerups/mcp/generic/]
```
资料来源：[src/cli/commands/setup.ts:60-75](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
## 技能使用示例
### systematic-debugging 技能
系统化调试技能提供结构化的问题诊断和解决工作流：
```mermaid
graph TD
A[问题报告] --> B[收集环境信息]
B --> C[复现问题]
C --> D{复现成功?}
D -->|是| E[分析根因]
D -->|否| F[收集更多上下文]
F --> C
E --> G[提出修复方案]
G --> H[验证修复]
H --> I[记录经验教训]
```
### writing-plans 技能
计划撰写技能指导智能体创建结构化、可执行的项目计划：
- 目标定义
- 任务分解
- 优先级排序
- 依赖分析
- 时间估算
资料来源：[skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)
### using-powerups 技能
系统引导技能帮助用户和智能体了解 Agent Powerups 的使用方法：
- 技能发现和浏览
- 插件管理
- 命令执行
- 配置验证
资料来源：[skills/using-powerups/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/using-powerups/SKILL.md)
## 智能体集成
### 技能发现
智能体可以通过以下方式发现可用技能：
```bash
# 列出所有可用技能
apx list
# 查看特定技能详情
apx info
# 验证技能有效性
apx check
```
### 智能体配置文件
技能安装后，智能体配置文件（如 AGENTS.md、CLAUDE.md）会自动更新，包含指向技能的指令：
```markdown
## Agent Powerups
Agent Powerups assets are installed at `agent-powerups/`.
Use these local assets when relevant:
- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.
- Use `apx` commands to discover, inspect, validate, and extend setup.
- Skills are at `agent-powerups/skills/`. Plugin bundles are at `agent-powerups/plugins/`.
```
资料来源：[src/cli/commands/setup.ts:35-55](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
## 最佳实践
### 技能设计原则
1. **单一职责**：每个技能应专注于一个特定任务领域
2. **清晰输入输出**：明确定义技能的触发条件和预期结果
3. **可组合性**：技能应能与其他技能协同工作
4. **自包含**：技能应包含执行所需的所有信息
5. **版本控制**：使用语义化版本号管理技能演进
### 技能维护
| 维护任务 | 频率 | 执行方式 |
|----------|------|----------|
| 前置matter 验证 | 提交时 | 自动 CI |
| 内容长度检查 | 每次发布 | audit 命令 |
| 依赖检查 | 每次安装 | check 命令 |
| 整体验证 | 每周 | validate-skills.py |
## 相关命令参考
| 命令 | 功能 |
|------|------|
| `apx list` | 列出所有可用技能 |
| `apx info ` | 显示技能详细信息 |
| `apx check ` | 验证技能安装状态 |
| `apx doctor` | 运行全面健康检查 |
| `apx audit skills` | 审计所有技能质量 |
| `apx install ` | 安装技能到指定智能体 |
| `python scripts/validate-skills.py` | 验证技能文件结构 |
---
## 命令系统
### 相关页面
相关主题：[技能系统](#skills), [钩子系统](#hooks), [MCP 配置管理](#mcp-configs)
相关源码文件
以下源码文件用于生成本页说明：
- [commands/generic](https://github.com/yeaight7/agent-powerups/blob/main/commands/generic)
- [commands/claude-code](https://github.com/yeaight7/agent-powerups/blob/main/commands/claude-code)
- [commands/codex](https://github.com/yeaight7/agent-powerups/blob/main/commands/codex)
- [commands/bug-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/bug-check.md)
- [commands/security-audit.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/security-audit.md)
- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)
- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)
# 命令系统
## 概述
命令系统（Command System）是 Agent Powerups 的核心组件之一，为编码代理提供可复用的命令提示词和工作流指令。与传统固定命令不同，该系统采用 Markdown 文件格式存储命令模板，支持多目标代理（Codex、Claude Code、Gemini）的差异化适配，并可通过 `apx` CLI 工具进行发现、检查、验证和执行。
命令系统的设计理念是 **"review-first"（审查优先）**——在执行任何命令前，代理应先阅读并理解命令意图，而非盲目执行预设脚本。 资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## 架构设计
### 命令系统组件关系
```mermaid
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]
```
### 命令目录结构
每个命令目录遵循标准化布局：
| 层级 | 路径 | 说明 |
|------|------|------|
| 根命令目录 | `commands/` | 所有命令的顶层容器 |
| 通用命令 | `commands/generic/` | 跨平台通用命令 |
| Agent专用命令 | `commands/codex/` | Codex 特定命令 |
| Agent专用命令 | `commands/claude-code/` | Claude Code 特定命令 |
| 命令定义文件 | `commands/*.md` | 具体命令实现（Markdown格式） |
资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)
## 命令类型分类
### 按功能分类
| 命令类别 | 功能描述 | 典型用例 |
|----------|----------|----------|
| **检查类命令** | 代码质量与安全检查 | `bug-check.md`、`security-audit.md` |
| **发布前检查** | Ship前验证 | `ship-check` |
| **工作流命令** | 复杂任务编排 | `tri-review`、`parallel-work` |
| **引导命令** | 工具使用指导 | `using-powerups-command` |
### 按目标代理分类
| 目标代理 | 命令目录 | 适配说明 |
|----------|----------|----------|
| **通用** | `commands/generic/` | 所有代理均可使用 |
| **Codex** | `commands/codex/` | OpenAI Codex 专用 |
| **Claude Code** | `commands/claude-code/` | Anthropic Claude Code 专用 |
| **Gemini** | `commands/gemini/` | Google Gemini 专用 |
资料来源：[README.md - Catalog Overview](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## 内置命令详解
### 1. Bug Check 命令
`bug-check.md` 专注于系统性缺陷发现，为代理提供结构化的调试工作流。
**核心功能：**
- 系统性错误定位
- 根因分析引导
- 修复方案生成
**使用方式：**
```powershell
apx commands print bug-check --target
apx commands run bug-check
```
资料来源：[commands/bug-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/bug-check.md)
### 2. Security Audit 命令
`security-audit.md` 提供代码安全审计功能，包含自动化检测规则。
**检测规则示例：**
| 规则名称 | 严重级别 | 检测模式 |
|----------|----------|----------|
| `unpinned-latest-image` | P2 | CI配置中的 `:latest` 镜像标签 |
| `broad-filesystem-write` | P1 | 递归删除或通配符写入 |
| `missing-dry-run` | P1 | 未加 `--dry-run` 的安装命令 |
资料来源：[src/cli/commands/security-audit.ts:20-40](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
**扫描配置：**
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 扫描目录 | 排除 `node_modules`、`dist`、`.git`、`.worktrees`、`.plugins` | 敏感目录黑名单 |
| 扫描扩展 | `.json`、`.toml`、`.md`、`.sh`、`.ps1`、`.yaml`、`.yml` | 目标文件类型 |
| 单文件大小限制 | 512 KB | 防止大文件阻塞 |
资料来源：[src/cli/commands/security-audit.ts:41-43](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)
### 3. Ship Check 命令
`ship-check` 是发布前验证命令包，确保代码符合发布标准。
**命令执行：**
```powershell
apx commands run ship-check
```
资料来源：[README.md - Quickstart](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
### 4. 工作流命令组
系统提供一系列工作流编排命令：
| 命令 | 功能 | 使用场景 |
|------|------|----------|
| `tri-review` | 三方评审 | 关键代码审查 |
| `clarify-requirements` | 需求澄清 | 需求模糊时 |
| `parallel-work` | 并行工作 | 多任务处理 |
| `finish-loop` | 完成循环 | 收尾验证 |
资料来源：[src/cli/apx.ts:45-60](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
## apx CLI 命令接口
### 命令管理子命令
```mermaid
graph LR
A[apx commands] --> B[print]
A --> C[run]
A --> D[validate]
B --> B1[显示命令内容]
C --> C1[执行命令]
D --> D1[验证命令结构]
```
### 使用示例
```powershell
# 列出所有可用命令
apx commands list
# 打印命令内容到指定目标代理
apx commands print ship-check --target claude-code
# 执行本地命令检查
apx commands run ship-check
# 验证所有命令文件结构
apx commands validate --all
```
资料来源：[README.md - Quickstart](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## 生命周期命令
### Phase 命令组
Phase 命令提供结构化的任务生命周期管理：
```mermaid
graph TD
A[phase 命令] --> B[discuss]
A --> C[plan]
A --> D[execute]
A --> E[verify]
B --> B1[需求讨论]
C --> C1[任务规划]
D --> D1[执行实施]
E --> E1[结果验证]
```
**使用方式：**
```powershell
apx phase discuss
apx phase plan
apx phase execute
apx phase verify
```
资料来源：[src/cli/apx.ts:69-74](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
### Project 命令组
项目初始化命令：
```powershell
apx project init
```
资料来源：[src/cli/apx.ts:65-68](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
### Codebase 命令组
代码库分析命令：
```powershell
apx codebase map
```
资料来源：[src/cli/apx.ts:77-80](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
## 检查与验证
### 命令检查功能
`check.ts` 实现对命令资产的完整性验证：
**验证内容：**
- 命令文件存在性
- 必需的前置条件（requires）满足情况
- 缺失依赖的自动安装选项
```typescript
apx check [--install-missing] [--yes]
```
**输出格式：**
```
:status=[| install: ]
```
资料来源：[src/cli/commands/check.ts:10-30](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)
### 安全审计流程
```mermaid
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`）注入命令块：
**行为说明：**
| 场景 | 处理方式 |
|------|----------|
| 指令文件已存在 | 在 `` 和 `` 标记之间追加内容 |
| 指令文件不存在 | 创建 `agent-powerups/instructions/agent-powerups.md` 并报告手动步骤 |
| 已存在注入块 | 替换现有块内容 |
资料来源：[src/cli/commands/setup.ts:1-20](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
### 各代理的集成方式
**Codex 集成：**
```powershell
apx commands print ship-check --target codex
apx setup codex --mode recommended --yes
```
**Claude Code 集成：**
```powershell
apx commands print ship-check --target claude-code
apx setup claude-code --mode recommended --yes
```
资料来源：[examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)、[examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)
## 命令模板格式
命令文件采用 Markdown 格式，包含以下标准结构：
```markdown
---
name:
description:
requires:
-
---
# Command Content
[Agent instruction content in Markdown]
```
**字段说明：**
| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | 是 | 命令唯一标识符 |
| `description` | 是 | 命令功能简述 |
| `requires` | 否 | 前置依赖列表 |
## 安全注意事项
命令系统包含潜在风险的操作类型：
| 风险类型 | 级别 | 说明 |
|----------|------|------|
| 文件系统写入 | P1 | 递归删除、通配符写入 |
| 包安装 | P1 | 未加 `--dry-run` 的安装 |
| 镜像标签 | P2 | 使用 `:latest` 标签 |
> **警告**：在将命令加载到可信代理环境前，请务必审查命令内容。命令可能指示代理读取本地文件或执行命令。
资料来源：[README.md - Safety Warning](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## 最佳实践
### 命令使用准则
1. **审查优先**：执行命令前先使用 `print` 子命令查看内容
2. **dry-run 验证**：使用 `--dry-run` 选项预演效果
3. **渐进式采用**：从 minimal 模式开始，逐步扩展
4. **定期验证**：使用 `apx commands validate --all` 确保命令完整性
### 开发新命令
1. 在 `commands/` 下创建 Markdown 文件
2. 遵循标准模板格式
3. 添加必需的前置条件（requires）
4. 使用 `apx commands validate` 验证结构
5. 在 `plugin-bundles.json` 中注册
## 相关资源
- [安装指南](./docs/installation.md)
- [安全模型](./docs/security-model.md)
- [插件系统](./plugins/)
- [Catalog Schema](./docs/catalog-schema.md)
---
## 钩子系统
### 相关页面
相关主题：[技能系统](#skills), [命令系统](#commands)
相关源码文件
以下源码文件用于生成本页说明：
- [hooks/README.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/README.md)
- [hooks/no-secrets-preflight/HOOK.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/no-secrets-preflight/HOOK.md)
- [hooks/handoff-summary/HOOK.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/handoff-summary/HOOK.md)
- [hooks/validation-required/HOOK.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/validation-required/HOOK.md)
- [docs/security-model.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/security-model.md)
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [catalog.json](https://github.com/yeaight7/agent-powerups/blob/main/catalog.json)
# 钩子系统
## 概述
钩子系统（Hook System）是 Agent Powerups 框架中用于在特定执行节点触发自定义逻辑的扩展机制。该系统允许开发者和用户在 agent 工作流的关键时刻注入检查、转换、通知或验证行为，从而实现对 agent 行为的精细化控制。
钩子是可组合的、声明式的配置单元，支持 `pre-hook`（前置钩子）和 `post-hook`（后置钩子）两种模式。系统强调本地优先（local-first）的执行策略，所有钩子内容默认存储在仓库的 `hooks/` 目录下，并通过 `apx` CLI 工具进行管理和执行。资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
## 架构设计
### 核心组件
钩子系统由以下核心组件构成：
| 组件类型 | 说明 | 存储位置 |
|---------|------|---------|
| 钩子定义 | 包含执行逻辑的 Markdown 文件 | `hooks//HOOK.md` |
| 钩子清单 | 记录所有可用钩子的元数据 | `catalog.json` |
| 执行引擎 | 解析和运行钩子的 CLI 模块 | `src/cli/` |
| 安全边界 | 限制钩子可执行操作的沙箱机制 | `docs/security-model.md` |
### 工作流程
```mermaid
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](https://github.com/yeaight7/agent-powerups/blob/main/hooks/README.md)
## 钩子类型分类
### 按功能分类
Agent Powerups 当前支持三种主要钩子分类：
| 分类 | 用途 | 示例钩子 |
|------|------|---------|
| `productivity` | 提升工作效率的辅助钩子 | handoff-summary |
| `quality` | 代码质量和审查相关 | validation-required |
| `safety` | 安全检查和风险防控 | no-secrets-preflight |
### 内置钩子
#### 1. no-secrets-preflight（安全类）
**用途**：在 agent 处理敏感信息前执行预检查，防止密钥、凭证或私密数据意外泄露。
**触发场景**：
- 用户请求处理文件时
- Agent 准备写入外部服务时
- 涉及环境变量或配置文件的操作前
**安全模型约束**：该钩子严格遵循最小权限原则，任何涉及密钥的操作都需要显式确认。资料来源：[docs/security-model.md:1-50](https://github.com/yeaight7/agent-powerups/blob/main/docs/security-model.md)
#### 2. handoff-summary（效率类）
**用途**：在 agent 之间进行上下文交接时生成摘要信息，确保信息传递的完整性和连续性。
**输出内容**：
- 当前任务进度概述
- 已完成的检查点列表
- 待处理的依赖项
- 关键上下文引用
#### 3. validation-required（质量类）
**用途**：在关键操作执行前强制进行验证检查，确保符合预定义的质量标准。
**验证维度**：
- 代码格式规范
- 文档完整性
- 测试覆盖率
- 类型安全
## 钩子定义格式
每个钩子目录包含一个 `HOOK.md` 文件，遵循标准的前置元数据格式：
```markdown
---
name:
type:
trigger:
requires:
-
-
description:
version: 1.0.0
---
# Hook Execution Logic
[具体执行指令...]
```
### 必填字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 钩子唯一标识符 |
| `type` | enum | 钩子所属分类 |
| `trigger` | enum | 触发时机（pre/post） |
| `description` | string | 功能描述 |
### 可选字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `requires` | array | 运行时依赖列表 |
| `version` | string | 钩子版本号 |
| `timeout` | number | 最大执行时长（秒） |
资料来源：[catalog.json](https://github.com/yeaight7/agent-powerups/blob/main/catalog.json)
## CLI 命令接口
### 列出所有钩子
```sh
apx hooks list
```
该命令扫描 `hooks/` 目录并返回所有已注册的钩子及其状态。
### 查看钩子详情
```sh
apx hooks info
```
输出指定钩子的完整元数据和执行说明。
### 运行单个钩子
```sh
apx hooks run
```
在当前工作目录执行指定钩子的逻辑。
### 运行所有适用钩子
```sh
apx hooks run --all
```
遍历并执行所有符合条件的钩子。
### 验证钩子完整性
```sh
apx hooks validate
```
检查钩子定义文件的结构正确性和依赖可用性。
## 与安装系统的集成
### Setup 流程中的钩子处理
在 `apx setup` 执行过程中，钩子目录会被复制到目标 agent 的安装根目录：
```typescript
// 资料来源：src/cli/commands/setup.ts
const directories = [
{ source: path.join(service.repoRoot, "hooks"), dest: path.join(installRoot, "hooks") },
// ... 其他目录
];
```
### 目录结构
安装后的钩子布局如下：
```
/
└── agent-powerups/
└── hooks/
├── no-secrets-preflight/
│ └── HOOK.md
├── handoff-summary/
│ └── HOOK.md
└── validation-required/
└── HOOK.md
```
## 安全模型
钩子系统内置多层安全保护机制：
### 信任边界
根据 `docs/security-model.md` 的定义，钩子的信任边界遵循以下原则：
| 边界类型 | 限制内容 |
|---------|---------|
| 文件访问 | 仅允许读取项目目录内的文件 |
| 命令执行 | 需要显式用户批准 |
| 网络请求 | 禁止未经授权的外部调用 |
| 密钥暴露 | 严禁在钩子逻辑中输出敏感信息 |
### 沙箱执行
钩子在受限环境中执行，具有以下限制：
- 无法访问 `node_modules` 外部的模块
- 禁止修改系统配置
- 禁止创建持久化后台进程
- 网络请求被白名单机制控制
资料来源：[docs/security-model.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/security-model.md)
## 开发指南
### 创建新钩子
1. 在 `hooks/` 下创建新目录
2. 编写 `HOOK.md` 文件，包含完整的前置元数据
3. 实现具体的执行逻辑（Markdown 格式的指令）
4. 在 `catalog.json` 中注册钩子
5. 运行验证命令确保结构正确
### 钩子开发规范
| 规范项 | 要求 |
|-------|------|
| 命名 | 使用 kebab-case，如 `my-custom-hook` |
| 描述 | 必需提供清晰的 description |
| 测试 | 必须包含 `apx hooks validate` 通过 |
| 文档 | 需在 HOOK.md 中说明触发条件 |
## 最佳实践
### 1. 单一职责原则
每个钩子应专注于单一功能，避免将多个检查逻辑合并到同一个钩子中。这有助于提高可维护性和可测试性。
### 2. 失败处理
钩子执行失败时应：
- 返回有意义的错误消息
- 提供修复建议
- 避免阻塞主流程（除非是关键安全检查）
### 3. 性能考虑
- 避免在钩子中执行耗时操作
- 使用缓存机制减少重复计算
- 设置合理的超时时间
## 常见问题
**Q：钩子执行失败如何调试？**
使用 `--verbose` 标志运行命令获取详细日志输出：
```sh
apx hooks run --verbose
```
**Q：如何禁用特定钩子？**
在 `profiles.json` 中编辑对应 profile 的 `disabled-hooks` 列表。
**Q：钩子支持条件执行吗？**
支持。在 `HOOK.md` 的前置元数据中使用 `requires` 字段声明前置条件。
## 相关资源
- [安全模型文档](./docs/security-model.md)
- [CLI 命令参考](./src/cli/apx.ts)
- [Catalog Schema](./docs/catalog-schema.md)
- [贡献指南](./CONTRIBUTING.md)
---
## MCP 配置管理
### 相关页面
相关主题：[资产目录系统](#catalog-system), [apx CLI 参考](#cli-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/generic/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/generic/github-local.json)
- [mcp/claude-code/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/claude-code/github-local.json)
- [mcp/codex/github-local.toml](https://github.com/yeaight7/agent-powerups/blob/main/mcp/codex/github-local.toml)
- [docs/mcp-configs.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/mcp-configs.md)
- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)
- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)
# MCP 配置管理
## 概述
MCP（Model Context Protocol）配置管理是 Agent Powerups 项目的核心功能之一，提供本地优先的 GitHub MCP 配置管理能力。该系统支持配置的检查、冒烟测试和显式安装，确保编码代理能够安全地访问 MCP 服务器工具。
Agent Powerups 的 MCP 配置管理遵循**本地优先、安全优先**的设计原则，所有配置操作都需要用户显式授权，不会自动修改环境。
资料来源：[README.md:36]()
## 核心概念
### 什么是 MCP 配置
MCP 配置定义了编码代理（如 Claude Code、Codex）可用的 MCP 服务器连接信息。这些配置文件包含：
- MCP 服务器端点地址
- 认证令牌占位符
- 必需的环境变量
- 警告信息和使用提示
### 支持的代理类型
| 代理类型 | 配置文件格式 | 目标目录 |
|---------|-------------|---------|
| Claude Code | `.json` | `mcp/claude-code/` |
| Codex | `.toml` | `mcp/codex/` |
| 通用/通用模板 | `.json` | `mcp/generic/` |
资料来源：[docs/mcp-configs.md]()
## 架构设计
### 配置查找机制
MCP 配置采用分层查找策略，根据安装目标确定配置文件路径：
```mermaid
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）：**
```json
{
"mcpServers": {
"github-local": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
**Codex 格式（TOML）：**
```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 命令系统
### 可用命令列表
| 命令 | 功能 | 目标参数 |
|-----|------|---------|
| `apx mcp install` | 安装 MCP 配置 | `codex`、`claude-code`、`generic` |
| `apx mcp check` | 检查配置语法和完整性 | `codex`、`claude-code`、`generic` |
| `apx mcp smoke` | 冒烟测试 MCP 连接 | `codex`、`claude-code`、`generic` |
### check 命令
`check` 命令验证 MCP 配置的正确性，包括：
- 配置文件存在性检查
- 配置文件类型验证（必须是 `mcp-config` 类型）
- 环境变量检查（识别未设置必需的环境变量）
- GitHub Token 验证
```typescript
export async function runMcpCheckCommand(
service: CatalogService,
assetName: string,
target: InstallTarget,
env: NodeJS.ProcessEnv = process.env,
): Promise>
```
**返回数据结构：**
| 字段 | 类型 | 说明 |
|-----|------|-----|
| `exitCode` | `number` | 0 表示成功，1 表示失败 |
| `output` | `string` | 检查结果输出 |
| `data` | `McpCheckData` | 详细检查数据 |
资料来源：[src/cli/commands/mcp.ts:74-91]()
### install 命令
`install` 命令将 MCP 配置复制到代理配置目录。该命令支持干运行模式，允许用户预览安装效果。
```powershell
# 预览安装（不实际写入）
apx mcp install github-local --target codex --dry-run
# 执行安装
apx mcp install github-local --target codex
```
**安装流程：**
```mermaid
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` 字段定义：
```json
{
"mcp": {
"required_env": ["GITHUB_TOKEN"]
}
}
```
### 环境变量检查逻辑
`check` 命令会扫描所有配置，收集并验证环境变量设置状态：
```typescript
const requiredEnv = (asset.mcp?.required_env ?? []).map((name) => ({
name,
set: Boolean(env[name])
}));
```
**检查结果示例：**
| 环境变量 | 状态 | 说明 |
|---------|------|-----|
| `GITHUB_TOKEN` | 未设置 | 需要在本地配置真实令牌 |
| `GITHUB_PERSONAL_REPO` | 已设置 | 配置有效 |
资料来源：[src/cli/commands/mcp.ts:89-90]()
### 安全警告
安装过程中，系统会自动添加安全警告提示：
> **警告**：请将占位符（如 `${GITHUB_TOKEN}` 或 `YOUR_TOKEN_HERE`）替换为本地真实令牌，**不要提交真实令牌**到版本控制系统。
资料来源：[src/cli/commands/mcp.ts:58-60]()
## 资产管理
### 资产元数据结构
MCP 配置作为资产类型 `mcp-config` 在 `catalog.json` 中注册：
```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"]
}
}
```
**资产字段说明：**
| 字段 | 必需 | 说明 |
|-----|------|-----|
| `name` | 是 | 资产唯一标识 |
| `type` | 是 | 必须为 `mcp-config` |
| `path` | 是 | 默认配置文件路径 |
| `targets` | 否 | 按代理类型的目标路径映射 |
| `mcp.warning` | 否 | 安装警告信息 |
| `mcp.required_env` | 否 | 必需的环境变量列表 |
资料来源：[docs/mcp-configs.md]()
### 目标路径解析
当存在 `targets` 映射时，系统优先使用对应目标的值：
```typescript
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;
}
```
## 工作流程示例
### 完整配置流程
```mermaid
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**
```powershell
# 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**
```powershell
# 使用专用提示
apx mcp install github-local --target codex --dry-run
```
资料来源：[README.md:96-100]()
## 安全模型
### 安全边界
Agent Powerups 的 MCP 配置管理维护以下安全边界：
1. **本地优先**：所有配置文件优先从本地目录加载
2. **显式安装**：不自动修改任何配置文件
3. **占位符验证**：强制检查环境变量占位符
4. **预览优先**：所有写入操作支持 `--dry-run` 模式
### 风险缓解措施
| 风险 | 缓解措施 |
|-----|---------|
| 意外提交令牌 | 强制警告和占位符检测 |
| 未授权安装 | 要求显式 `--yes` 确认 |
| 错误的 MCP 配置 | check 和 smoke 命令验证 |
| 配置冲突 | 使用独立子目录避免覆盖 |
资料来源：[docs/security-model.md]()
## 命令参考
### 全局标志
| 标志 | 说明 |
|-----|------|
| `--dry-run` | 预览操作，不实际写入 |
| `--verbose` | 输出详细执行信息 |
| `--target ` | 指定目标代理类型 |
### 环境变量
| 变量 | 说明 |
|-----|------|
| `GITHUB_TOKEN` | GitHub 个人访问令牌（必需） |
| `APX_DOCTOR_NESTED` | 嵌套诊断模式标志 |
## 故障排除
### 常见问题
**Q: MCP 配置检查失败，提示类型错误？**
A: 确保资产在 `catalog.json` 中的 `type` 字段值为 `mcp-config`。
**Q: 环境变量已设置但仍显示未设置？**
A: 检查变量名是否完全匹配（包括大小写），并确保在运行 `apx` 命令的 shell 会话中变量已导出。
**Q: 目标路径未找到？**
A: 确认 `targets` 映射中存在对应的目标类型，或 `path` 字段指向的默认路径有效。
## 相关资源
- [MCP 配置文档](./docs/mcp-configs.md)
- [安全模型](./docs/security-model.md)
- [设置指南](./docs/setup/claude-code.md)
- [catalog.json 规范](./docs/catalog-schema.md)
---
## 用户意图配置
### 相关页面
相关主题：[安装指南](#installation), [资产目录系统](#catalog-system)
相关源码文件
以下源码文件用于生成本页说明：
- [profiles.json](https://github.com/yeaight7/agent-powerups/blob/main/profiles.json)
- [docs/profiles-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/profiles-schema.md)
- [src/cli/commands/profiles.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/profiles.ts)
- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)
- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)
- [package.json](https://github.com/yeaight7/agent-powerups/blob/main/package.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 提供了三种安装模式：
| 模式 | 说明 | 用途 |
|------|------|------|
| minimal | 最小引导集 | 仅安装核心技能用于初步验证 |
| recommended | 推荐配置 | 安装主流场景所需的技能和插件 |
| full | 完整配置 | 包含所有可选组件的广泛部署 |
资料来源：[src/cli/commands/setup.ts:21-35]()
## 架构设计
### 数据模型
```mermaid
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 类型定义
```typescript
type SetupAgent = "codex" | "claude" | "claude-code" | "gemini";
```
支持的编码代理类型：
| 代理标识符 | 显示名称 | 说明 |
|-----------|---------|------|
| codex | Codex | OpenAI Codex |
| claude | Claude | Anthropic Claude（基础版）|
| claude-code | Claude Code | Anthropic Claude Code |
| gemini | Gemini | Google Gemini CLI |
资料来源：[src/cli/commands/setup.ts:5-25]()
#### AgentProfile 完整配置
| 属性 | 类型 | 说明 | 示例 |
|------|------|------|------|
| agent | string | 代理唯一标识符 | "codex" |
| displayName | string | 用户友好的显示名称 | "Codex" |
| defaultRootEnv | string[] | 查找根目录的环境变量列表 | ["CODEX_HOME"] |
| defaultRootDir | string | 默认安装根目录 | "~/.codex" |
| instructionFileName | string | 代理指令文件名 | "AGENTS.md" |
| commandTargetDir | string | 命令目录目标 | "codex" |
| mcpTargetDir | string | MCP 配置目标目录 | "codex" |
资料来源：[src/cli/commands/setup.ts:37-58]()
## 配置数据结构
### profiles.json 文件结构
```json
{
"profiles": {
"": {
"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)
```typescript
const MINIMAL_SKILLS = [
"using-powerups", // 学会使用 powerups
"no-fluff", // 简洁输出
"repo-map", // 仓库地图
"writing-plans", // 编写计划
"verification-before-completion", // 完成前验证
"search-before-building", // 构建前搜索
] as const;
```
#### 推荐插件捆绑包 (RECOMMENDED_PLUGIN_BUNDLES)
```typescript
const RECOMMENDED_PLUGIN_BUNDLES = [
"dev-vitals", // 开发活力指标
"debugging-diagnostics", // 调试诊断
"quality-gates" // 质量门禁
] as const;
```
资料来源：[src/cli/commands/setup.ts:60-68]()
## 命令行接口
### apx profiles 命令
```bash
apx profiles list # 列出所有可用配置
apx profiles show # 显示指定配置详情
apx profiles validate # 验证配置语法
```
资料来源：[src/cli/apx.ts:28-32]()
### profiles.ts 命令实现
| 命令 | 功能 | 参数 |
|------|------|------|
| list | 列出所有配置 | 无 |
| show | 显示配置详情 | name: 配置名称 |
| validate | 验证配置有效性 | 无 |
```mermaid
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]()
## 使用场景
### 场景一：快速初始化新代理
```bash
# 列出可用配置
apx profiles list
# 使用推荐配置初始化 Claude Code
apx setup claude-code --mode recommended --yes
```
### 场景二：切换工作环境
```bash
# 为数据科学项目切换到 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 校验规则
配置文件必须满足以下规则：
| 规则 | 说明 | 验证方式 |
|------|------|---------|
| agent 有效性 | agent 必须是支持的代理类型 | 枚举校验 |
| 技能存在性 | 引用的技能必须存在于 catalog 中 | 引用校验 |
| 插件存在性 | 引用的插件必须存在于 plugin-bundles.json | 引用校验 |
| JSON 语法 | 必须是有效的 JSON 格式 | 语法校验 |
资料来源：[src/cli/commands/profiles.ts]()
### 验证命令
```bash
# 验证配置文件
apx profiles validate
# 验证并显示详细错误
apx profiles validate --verbose
```
## 扩展机制
### 自定义 Profile
用户可以通过在项目根目录创建 `profiles.local.json` 来扩展内置配置：
```json
{
"extends": "recommended",
"skills": ["additional-skill-1"],
"pluginBundles": ["custom-bundle"]
}
```
### Profile 继承
Profile 支持基础配置继承，允许用户基于现有配置创建变体：
```mermaid
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]
```
## 故障排查
### 常见问题
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 配置找不到 | profiles.json 格式错误 | 运行 `apx profiles validate` |
| 技能未安装 | 技能名拼写错误 | 检查 catalog.json 中的技能名 |
| 安装失败 | 权限不足 | 检查目标目录写入权限 |
### 诊断命令
```bash
# 医生检查
apx doctor
# 列出已安装配置
apx profiles list --installed
# 显示配置详细信息
apx profiles show --verbose
```
## 相关资源
- [安装文档](./installation.md)
- [安全模型](./security-model.md)
- [Setup 指南](./setup/index.md)
- [插件系统](../plugins/README.md)
- [技能目录](../skills/README.md)
---
---
## Doramagic 踩坑日志
项目：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