{
"canonical_name": "yeaight7/agent-powerups",
"compilation_id": "pack_1d24e12fbe5b4f4e94f005feb182607a",
"created_at": "2026-05-13T04:06:56.055425+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install markitdown` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install markitdown",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_d90e80de2dca46afa236e228cedd7728"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_ceb60fe2fa1323e2f024fff027828339",
"canonical_name": "yeaight7/agent-powerups",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/yeaight7/agent-powerups",
"slug": "agent-powerups",
"source_packet_id": "phit_c5745398d684433eb2d00c82003f72bf",
"source_validation_id": "dval_46a15f0d1ac6497ebd20b0b26688a543"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 4,
"one_liner_en": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"one_liner_zh": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:code, coding, git"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "agent-powerups",
"title_zh": "agent-powerups 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_c5745398d684433eb2d00c82003f72bf",
"page_model": {
"artifacts": {
"artifact_slug": "agent-powerups",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install markitdown",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/yeaight7/agent-powerups#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "仓库名 `agent-powerups` 与安装入口 `markitdown` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.1.4",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 4,
"open_issues": 0,
"pushed_at": null
},
"source_url": "https://github.com/yeaight7/agent-powerups",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"title": "agent-powerups 能力包",
"trial_prompt": "# agent-powerups - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-powerups 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. writing-plans：拆成计划。把目标拆成可执行步骤和检查点。\n2. systematic-debugging：先找根因。先调查症状和证据，再提出修复路径。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. writing-plans\n输入：已确认的目标、边界和推荐方案。\n服务动作：拆成可执行步骤，去掉 TODO、TBD、模糊动作和跳步。\n中间产物：3-5 步计划草案，每步都有检查点。\n\n2. systematic-debugging\n输入：故障描述或异常现象。\n服务动作：先收集症状、复现路径和证据，再提出根因假设。\n中间产物：根因调查卡。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- writing-plans：计划必须可执行、可检查、可拆分；不允许 TODO、TBD、模糊步骤或“稍后处理”。\n- systematic-debugging：先收集症状、证据和复现路径；不要在根因不清楚时给修复方案。\n\n【每一步的服务约束】\n- Step 1 / writing-plans：进入计划步骤前必须复述已确认目标；产出应是 3-5 步计划草案，并等待用户确认。\n- Step 2 / systematic-debugging：进入调试步骤时必须先收集症状和证据；不要直接给修复方案。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/yeaight7/agent-powerups\n- https://github.com/yeaight7/agent-powerups#readme\n- plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md\n- plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md\n- plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md\n- plugins/agentic-systems/skills/agent-harness-design/SKILL.md\n- plugins/agentic-systems/skills/canonical-advisor-routing/SKILL.md\n- plugins/agentic-systems/skills/context-retrieval-loop/SKILL.md\n- plugins/agentic-systems/skills/model-routing/SKILL.md\n- plugins/agentic-systems/skills/tri-model-review/SKILL.md\n- plugins/codebase-intelligence/skills/context-retrieval-loop/SKILL.md\n- plugins/codebase-intelligence/skills/local-rag-mcp/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-powerups 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v0.1.4（https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4）；github/github_release: v0.1.2（https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.2）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v0.1.4",
"url": "https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.1.2",
"url": "https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.2"
}
],
"status": "已收录 2 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Curated power-ups for coding agents: skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for serious software engineering. Claude Code, Codex, Gemini CLI and more",
"effort": "安装已验证",
"forks": 0,
"icon": "code",
"name": "agent-powerups 能力包",
"risk": "需复核",
"slug": "agent-powerups",
"stars": 4,
"tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/yeaight7/agent-powerups 项目说明书\n\n生成时间：2026-05-13 03:27:06 UTC\n\n## 目录\n\n- [项目概览](#overview)\n- [安装指南](#installation)\n- [apx CLI 参考](#cli-reference)\n- [资产目录系统](#catalog-system)\n- [插件包系统](#plugin-bundles)\n- [技能系统](#skills)\n- [命令系统](#commands)\n- [钩子系统](#hooks)\n- [MCP 配置管理](#mcp-configs)\n- [用户意图配置](#profiles)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [资产目录系统](#catalog-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n \n\n# 项目概览\n\n## 1. 项目简介\n\nAgent Powerups 是一个面向编码智能体（coding agents）的可重用技能集合，采用与 Oh My Zsh 相似的设计理念。该项目旨在为各种编码智能体（如 Codex、Claude Code、 Gemini）提供标准化的技能、命令、配置和工作流扩展方案。\n\n### 1.1 核心定位\n\n| 维度 | 描述 |\n|------|------|\n| 项目性质 | 智能体扩展工具包 |\n| 设计理念 | Oh My Zsh 风格的可复用组件集合 |\n| 支持平台 | Codex、Claude Code、 Gemini |\n| 安装方式 | npm 包本地安装（`apx` CLI） |\n| 资料来源：[README.md:1-15] |\n\n### 1.2 主要交付物\n\n项目当前版本包含以下核心交付物：\n\n- **可复用技能（Skills）**：23个预置技能，涵盖调试、代码审查、数据工程等领域\n- **CLI 工具（`apx`）**：本地安全命令行工具，支持智能体检查和安装\n- **MCP 配置**：本地优先的 GitHub MCP 配置及检查流程\n- **AGENTS.md 模板**：5种项目类型的起始模板\n- **命令包**：2个预置命令包\n- **Hook 示例**：3个钩子示例\n- **17个插件包**：3个稳定版、10个测试版、4个实验版\n- **2个工作流**：特性迭代和智能体中继\n\n资料来源：[README.md:85-115]\n\n## 2. 核心架构\n\n### 2.1 系统架构图\n\n```mermaid\ngraph TD\n A[用户/智能体] --> B[apx CLI 工具]\n B --> C[目录服务 CatalogService]\n C --> D[技能存储 skills/]\n C --> E[插件存储 plugins/]\n C --> F[命令存储 commands/]\n C --> G[Hook 存储 hooks/]\n C --> H[MCP 配置 mcp/]\n C --> I[AGENTS.md 模板 agents-md/]\n \n B --> J[setup 命令]\n B --> K[check 命令]\n B --> L[doctor 命令]\n B --> M[security-audit 命令]\n B --> N[plugins 命令]\n \n J --> O[目标智能体环境]\n K --> P[需求检查]\n M --> Q[安全扫描]\n```\n\n### 2.2 CLI 命令体系\n\n`apx` 是项目的核心命令行工具，提供以下主要命令：\n\n| 命令 | 功能描述 |\n|------|----------|\n| `apx list` | 列出所有可用技能和资源 |\n| `apx info ` | 查看特定技能/资源的详细信息 |\n| `apx check ` | 验证技能或资源的配置状态 |\n| `apx setup ` | 将 Agent Powerups 安装到指定智能体 |\n| `apx doctor` | 运行诊断检查，验证环境完整性 |\n| `apx security-audit` | 扫描安全风险模式 |\n| `apx plugins list` | 列出所有插件包 |\n| `apx plugins install` | 安装插件到目标智能体 |\n| `apx commands run` | 执行命令包 |\n| `apx hooks run` | 运行钩子脚本 |\n| `apx mcp check/smoke/install` | MCP 服务器检查和安装 |\n\n资料来源：[src/cli/apx.ts:1-30]\n\n### 2.3 目录结构\n\n```\nagent-powerups/\n├── skills/ # 可复用技能目录\n│ ├── systematic-debugging/\n│ ├── writing-plans/\n│ ├── dbt-preflight/\n│ └── ... (23个技能)\n├── agents-md/ # AGENTS.md 模板\n│ ├── typescript-app/\n│ ├── python-library/\n│ └── ...\n├── commands/ # 命令包\n│ ├── ship-check/\n│ └── using-powerups-command/\n├── hooks/ # 钩子示例\n│ ├── no-secrets-preflight/\n│ ├── handoff-summary/\n│ └── validation-required/\n├── mcp/ # MCP 配置\n│ └── github-local/\n├── workflows/ # 工作流\n│ ├── feature-iteration/\n│ └── agent-relay/\n├── plugins/ # 插件包 (17个)\n│ ├── dev-vitals/ # 稳定版\n│ ├── debugging-diagnostics/\n│ ├── quality-gates/\n│ └── ... (beta/experimental)\n└── scripts/ # 验证脚本\n ├── validate-skills.py\n ├── validate-catalog.py\n └── check-requirements.py\n```\n\n## 3. 技能系统\n\n### 3.1 技能定义\n\n技能是 Agent Powerups 的核心交付单元，每个技能是一个独立的工作流或方法论，通过 `SKILL.md` 文件定义。\n\n```mermaid\ngraph LR\n A[SKILL.md] --> B[frontmatter 元数据]\n A --> C[技能说明]\n A --> D[使用步骤]\n A --> E[支持文件引用]\n \n B --> B1[name 名称]\n B --> B2[description 描述]\n B --> B3[tags 标签]\n B --> B4[requires 依赖]\n```\n\n资料来源：[src/cli/commands/doctor.ts:15-30]\n\n### 3.2 预置技能分类\n\n| 类别 | 技能列表 |\n|------|----------|\n| 调试分析 | `systematic-debugging`、`bug-hunt`、`safe-refactor` |\n| 代码质量 | `no-fluff`、`quality-gates`、`sql-business-logic-review` |\n| 规划协作 | `writing-plans`、`requesting-code-review`、`receiving-code-review`、`pr-triage` |\n| 数据工程 | `bigquery-cost-audit`、`dbt-incremental-strategy-audit`、`dbt-preflight`、`dbt-strategy`、`data-quality`、`metric-impact-analyzer` |\n| 智能体协作 | `ask-claude`、`ask-gemini`、`ask-codex`、`using-powerups`、`graphify` |\n| 内容处理 | `ai-slop-cleaner`、`defuddle`、`markitdown-file-intake`、`repo-map` |\n\n资料来源：[README.md:85-95]\n\n### 3.3 技能验证机制\n\n项目提供多层次的技能验证：\n\n1. **结构验证**：检查 `SKILL.md` 文件是否存在\n2. **元数据验证**：确保 frontmatter 包含必需的 `name` 和 `description` 字段\n3. **引用验证**：检查技能中引用的支持文件是否存在\n4. **目录验证**：确保技能目录下文件结构完整\n\n```typescript\n// 验证逻辑伪代码\nif (!frontmatter?.name || !frontmatter?.description) {\n issues.push(`${entry.name}: missing required frontmatter`);\n}\n\nfor (const ref of referencedSupportFiles(content)) {\n if (!(await supportRefExists(skillDir, ref))) {\n issues.push(`${entry.name}: missing referenced support file ${ref}`);\n }\n}\n```\n\n资料来源：[src/cli/commands/doctor.ts:20-40]\n\n## 4. 插件系统\n\n### 4.1 插件包结构\n\n插件包采用多智能体兼容结构：\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code 清单\n├── .codex-plugin/\n│ └── plugin.json # Codex 清单\n├── skills/\n│ └── /\n│ └── SKILL.md\n├── agents/\n│ └── .md\n└── commands/\n └── .md\n```\n\n资料来源：[plugins/README.md:20-35]\n\n### 4.2 插件状态分类\n\n| 状态 | 数量 | 插件示例 |\n|------|------|----------|\n| 稳定版 | 3 | `dev-vitals`、`debugging-diagnostics`、`quality-gates` |\n| 测试版 | 10 | `codebase-maintenance`、`data-engineering`、`documentation-systems` 等 |\n| 实验版 | 4 | `software-engineering`、`agentic-systems`、`security-guardrails` 等 |\n\n资料来源：[README.md:110-120]\n\n### 4.3 插件操作命令\n\n```sh\napx plugins list # 列出所有插件\napx plugins info # 查看插件详情\napx plugins validate --all # 验证所有插件结构\napx plugins install --target codex --dry-run # 预览安装\napx plugins install --target claude-code # 安装到 Claude Code\n```\n\n## 5. 安装与配置\n\n### 5.1 安装模式\n\n`apx setup` 命令支持三种安装模式：\n\n| 模式 | 描述 | 覆盖范围 |\n|------|------|----------|\n| `minimal` | 引导模式 | 仅基础指令文件 |\n| `recommended` | 推荐模式 | 技能、插件、命令等核心资源 |\n| `full` | 完整模式 | 全部资源及支持文件 |\n\n资料来源：[src/cli/commands/setup.ts:15-50]\n\n### 5.2 目标智能体支持\n\n```sh\napx setup codex --mode recommended --yes # 安装到 Codex\napx setup claude-code --mode recommended --yes # 安装到 Claude Code\napx setup gemini --mode recommended --yes # 安装到 Gemini\n```\n\n### 5.3 安装流程\n\n```mermaid\ngraph TD\n A[apx setup ] --> B{检查 AGENTS.md 存在?}\n B -->|存在| C[创建备份]\n B -->|不存在| D[写入 instructions/agent-powerups.md]\n C --> E[追加 agent-powerups 块]\n E --> F[复制资源到 agent-powerups/]\n F --> G[更新全局指令]\n D --> G\n G --> H[安装完成]\n```\n\n资料来源：[src/cli/commands/setup.ts:80-120]\n\n## 6. 安全模型\n\n### 6.1 安全扫描规则\n\n`apx security-audit` 命令实现多层次安全扫描：\n\n| 规则名称 | 严重级别 | 检测模式 |\n|----------|----------|----------|\n| `broad-filesystem-write` | P1 | 递归删除或广泛文件写入 |\n| `missing-dry-run` | P1 | install 命令缺少 --dry-run |\n| `unpinned-latest-image` | P2 | CI 配置中使用 :latest 镜像 |\n\n资料来源：[src/cli/commands/security-audit.ts:1-30]\n\n### 6.2 安全检查范围\n\n```typescript\nconst SKIP_DIRS = new Set([\"node_modules\", \"dist\", \".git\", \".worktrees\", \".plugins\"]);\nconst SCAN_EXTS = new Set([\".json\", \".toml\", \".md\", \".sh\", \".ps1\", \".yaml\", \".yml\"]);\nconst MAX_FILE_BYTES = 512 * 1024;\n```\n\n扫描跳过以下目录和文件：\n- `node_modules`、`dist`、`.git` 等标准构建目录\n- 单文件大小限制为 512KB\n- 仅扫描特定扩展名文件\n\n### 6.3 安全警告\n\n> ⚠️ **重要提示**：在将资源加载到受信任的智能体环境之前，务必审查所有资产。\n>\n> - 技能可能指示智能体读取本地文件或执行命令\n> - 钩子可能在宿主智能体支持时执行代码\n> - MCP 配置可能扩展工具访问权限\n> - 安装命令可能修改本地环境\n> - 除非严格必要，否则不应将密钥粘贴到智能体上下文中\n\n资料来源：[README.md:125-135]\n\n## 7. 验证与诊断\n\n### 7.1 doctor 命令检查项\n\n`apx doctor` 提供全面的环境诊断：\n\n| 检查项 | 验证内容 |\n|--------|----------|\n| `apx` 二进制 | 验证 CLI 可执行文件 |\n| 依赖项 | 检查所需工具是否安装 |\n| 配置文件 | 验证配置完整性 |\n| 技能文件 | 检查 SKILL.md 和元数据 |\n| 外部检查 | 运行外部验证脚本 |\n\n资料来源：[src/cli/commands/doctor.ts:1-60]\n\n### 7.2 check 命令功能\n\n```typescript\ninterface CheckResult {\n exitCode: number; // 0=成功, 1=失败\n output: string; // 输出信息\n warnings: string[]; // 警告列表\n actions: string[]; // 建议操作\n}\n```\n\ncheck 命令支持：\n- 批量检查多个资产\n- 验证依赖项状态\n- 自动安装缺失依赖（可选）\n\n资料来源：[src/cli/commands/check.ts:1-30]\n\n## 8. 兼容性矩阵\n\n| 资产类别 | 当前状态 | 兼容性说明 |\n|----------|----------|------------|\n| 根 `skills/` | 已发布 | 通用文本技能，部分提及已知智能体 |\n| `mcp/` | 已发布 | 本地优先 MCP 配置 |\n| 插件包 | 已发布 | 按目标智能体分类 |\n| 验证脚本 | 已发布 | Python 脚本 |\n\n## 9. 快速开始\n\n### 9.1 环境准备\n\n```sh\n# 安装依赖\nnpm install\nnpm run build\nnpm link\n\n# 验证安装\napx doctor\n```\n\n### 9.2 基本工作流\n\n```sh\n# 1. 浏览目录\napx list\napx info markitdown-file-intake\n\n# 2. 验证资源\napx commands run ship-check\napx hooks run no-secrets-preflight --all\n\n# 3. MCP 检查\napx mcp check github-local --target generic\napx mcp smoke github-local --json\n\n# 4. 安装到智能体\napx setup codex --dry-run\napx setup codex --mode recommended --yes\n```\n\n### 9.3 本地智能体咨询\n\n```sh\napx ask-codex \"Return OK only\" --json\napx ask-claude \"Return OK only\" --json\napx ask-gemini \"Return OK only\" --json\n```\n\n## 10. 总结\n\nAgent Powerups 项目为编码智能体提供了一个标准化、可扩展的技能和工具集合。其核心价值包括：\n\n- **模块化设计**：技能、插件、命令独立存在，易于组合使用\n- **多智能体支持**：统一接口支持 Codex、Claude Code、 Gemini\n- **本地优先**：所有资源本地存储，保证数据隐私和安全\n- **验证体系**：完整的检查、诊断和审计机制\n- **渐进式安装**：支持 minimal、recommended、full 三种安装级别\n\n该项目遵循类似 Oh My Zsh 的社区驱动模式，通过 npm 包分发 `apx` CLI 工具，用户可灵活选择安装哪些技能和插件到目标智能体环境中。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[apx CLI 参考](#cli-reference), [用户意图配置](#profiles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)\n- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)\n- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n \n\n# 安装指南\n\n## 概述\n\nAgent Powerups 是一个面向编程代理的 Oh My Zsh 风格工具集，提供了可复用的技能、命令、MCP 配置、钩子、AGENTS.md 模板和工作流。本指南将详细介绍如何在不同环境下安装和配置 Agent Powerups。\n\n安装的核心目标是：将仓库中的资产（skills、plugins、commands、hooks 等）安全地部署到目标代理的工作目录中，同时保持灵活性和可控性。\n\n## 系统要求\n\n### 基础依赖\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Node.js | 最新稳定版 | CLI 工具运行所需 |\n| npm | 最新稳定版 | 用于安装 apx CLI |\n| Python | 3.x | 部分验证脚本需要 |\n| Git | 最新稳定版 | 用于仓库克隆和更新 |\n\n安装前请运行 `apx doctor` 命令检查环境配置是否满足要求。\n\n## 安装方法\n\n### 方法一：通过 npm 全局安装 apx CLI\n\napx 是 Agent Powerups 的命令行工具，提供资产发现、检验、安装和配置等功能。\n\n```sh\nnpm install -g agent-powerups\n```\n\n安装完成后，验证安装：\n\n```sh\napx doctor\napx --version\n```\n\n### 方法二：从源码构建\n\n适用于需要自定义或参与开发的用户：\n\n```sh\ngit clone https://github.com/yeaight7/agent-powerups.git\ncd agent-powerups\nnpm install\nnpm run build\nnpm link\n```\n\n资料来源：[examples/minimal/README.md]()\n\n### 方法三：Docker 环境安装\n\n如需在容器化环境中使用，请参考项目根目录下的 Dockerfile 或 docker-compose.yml 配置。\n\n## 代理环境配置\n\nAgent Powerups 支持多种编码代理的原生安装，包括 Codex、Claude Code 和 Gemini。不同的代理有不同的目录结构和配置方式。\n\n### 支持的目标代理\n\n| 代理类型 | 安装目标目录 | 配置说明 |\n|----------|--------------|----------|\n| codex | `/skills/` | 技能安装到代理根目录 |\n| claude | `/plugins/` | Claude 插件安装 |\n| claude-code | `/plugins/` | Claude Code 插件安装 |\n| gemini | `/extensions/` | Gemini 扩展安装 |\n\n### Dry-Run 模式\n\n在执行任何实际修改前，强烈建议先使用 dry-run 模式预览安装操作：\n\n```sh\napx setup codex --dry-run\napx setup claude-code --dry-run\napx setup gemini --dry-run\n```\n\n这将显示将要执行的操作而不实际修改文件系统。\n\n### 最小化安装（Bootstrap）\n\n仅安装最基础的资产，适合首次试用或受限环境：\n\n```sh\napx setup codex --mode minimal --yes\napx setup claude-code --mode minimal --yes\napx setup gemini --mode minimal --yes\n```\n\n资料来源：[src/cli/apx.ts:1-100]()\n\n### 推荐安装（Recommended）\n\n安装推荐的技能和插件集合，适合大多数用户：\n\n```sh\napx setup codex --mode recommended --yes\napx setup claude-code --mode recommended --yes\napx setup gemini --mode recommended --yes\n```\n\n### 完整安装（Full）\n\n安装所有可用资产，包括完整的插件包和辅助资源：\n\n```sh\napx setup codex --mode full --yes\napx setup claude-code --mode full --yes\napx setup gemini --mode full --yes\n```\n\n## 手动原生安装\n\n### 基本手动安装\n\n```sh\napx install [--verbose]\n```\n\n### 完整手动安装\n\n```sh\napx install --full [--verbose]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `--verbose` | 显示每个文件的详细安装路径 |\n| `--full` | 同时安装支持资产并更新全局指令 |\n\n默认手动安装行为：\n\n- 根目录 `skills/` → `/skills/`\n- Codex/Claude 插件包 → `/plugins/`\n- Gemini 插件包 → `/extensions/`\n\n资料来源：[README.md:quickstart]()\n\n## 插件包安装\n\nAgent Powerups 采用插件包（Plugin Bundles）架构管理相关技能和配置。\n\n### 插件包状态分类\n\n| 状态 | 数量 | 说明 |\n|------|------|------|\n| Stable（稳定） | 3 个 | 经过充分测试，生产可用 |\n| Beta（测试） | 10 个 | 功能完整，正在收尾稳定性 |\n| Experimental（实验） | 4 个 | 早期功能，可能有变更 |\n\n### 稳定版插件包\n\n- `dev-vitals` - 开发健康指标\n- `debugging-diagnostics` - 调试诊断\n- `quality-gates` - 质量门禁\n\n### 测试版插件包\n\n- `codebase-maintenance`\n- `data-engineering`\n- `documentation-systems`\n- `machine-learning-ops`\n- `codebase-intelligence`\n- `spec-driven-development`\n- `spec-quality-gates`\n- `context-efficiency`\n- `tool-integrations`\n- `memory-optimization`\n\n### 实验版插件包\n\n- `software-engineering`\n- `agentic-systems`\n- `security-guardrails`\n- `agent-evaluation-lab`\n\n### 插件包操作命令\n\n```sh\n# 列出所有插件包\napx plugins list\n\n# 查看插件包详情\napx plugins info dev-vitals\n\n# 验证插件包结构\napx plugins validate --all\n\n# 安装插件包（dry-run）\napx plugins install dev-vitals --target codex --dry-run\n\n# 实际安装插件包\napx plugins install dev-vitals --target codex\n```\n\n资料来源：[README.md:plugin-bundles]()\n\n## MCP 配置安装\n\nMCP（Model Context Protocol）配置用于扩展代理的工具访问能力。\n\n### MCP 配置命令\n\n```sh\n# 列出可用的 MCP 配置\napx mcp list\n\n# 打印 MCP 配置内容\napx mcp print github-local --target claude-code\n\n# 检查 MCP 配置\napx mcp check github-local --target claude-code --json\n\n# 执行 MCP 配置冒烟测试\napx mcp smoke github-local --json\n\n# 安装 MCP 配置\napx mcp install github-local --target codex --dry-run\napx mcp install github-local --target claude-code --dry-run\n```\n\n### 当前已打包的 MCP 配置\n\n- `github-local` - 本地 GitHub MCP 配置，含检查、冒烟测试和显式安装命令\n\n## 目录结构说明\n\n### 标准安装后的目录结构\n\n```\n/\n├── skills/ # 可复用技能目录\n│ ├── systematic-debugging/\n│ ├── writing-plans/\n│ └── ...\n├── plugins/ # 插件包目录（Codex/Claude）\n│ ├── dev-vitals/\n│ └── ...\n├── extensions/ # 扩展目录（Gemini）\n│ └── ...\n├── agent-powerups/ # 资产根目录\n│ ├── skills/ # 完整技能集\n│ ├── commands/ # 命令包\n│ ├── hooks/ # 钩子示例\n│ ├── mcp/ # MCP 配置\n│ └── instructions/ # 指令文件\n└── AGENTS.md / CLAUDE.md # 代理配置文件\n```\n\n资料来源：[examples/minimal/README.md]()\n\n## 验证与检查\n\n### 安装后验证\n\n安装完成后，运行以下命令验证：\n\n```sh\n# 检查 apx 工具状态\napx doctor\n\n# 列出已安装资产\napx list\n\n# 查看特定技能详情\napx info using-powerups\n\n# 检查技能完整性\napx check using-powerups\n\n# 运行安全审计\napx security-audit\n```\n\n### 仓库验证脚本\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\npython scripts/check-requirements.py\n```\n\n### 配置检查\n\n```sh\n# 运行需求检查\napx check \n\n# 安装缺失的依赖\napx check --install-missing --yes\n\n# 查看需求详情\napx check --verbose\n```\n\n资料来源：[src/cli/commands/check.ts]()\n\n## 用户意图配置文件\n\n用户意图配置文件（Profiles）提供预定义的能力组合，适合特定使用场景。\n\n### Profile 操作命令\n\n```sh\n# 列出所有配置文件\napx profiles list\n\n# 查看配置文件详情\napx profiles info safe-core\n```\n\n### 内置配置文件\n\n- `safe-core` - 安全核心配置，包含最基础的技能和检查\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{安装方式选择}\n B -->|npm 全局安装| C[安装 apx CLI]\n B -->|源码构建| D[克隆仓库并构建]\n B -->|Docker| E[使用 Docker 镜像]\n \n C --> F{目标代理选择}\n D --> F\n E --> F\n \n F -->|Codex| G[apx install codex]\n F -->|Claude Code| H[apx install claude-code]\n F -->|Gemini| I[apx install gemini]\n \n G --> J[选择安装模式]\n H --> J\n I --> J\n \n J -->|minimal| K[Bootstrap 基础安装]\n J -->|recommended| L[推荐安装]\n J -->|full| M[完整安装]\n \n K --> N[安装后验证]\n L --> N\n M --> N\n \n N --> O{验证通过?}\n O -->|是| P[安装完成]\n O -->|否| Q[诊断问题]\n Q --> N\n```\n\n## 安全注意事项\n\n在安装 Agent Powerups 时，请注意以下安全边界：\n\n### 审查后再加载\n\n> **警告**：在将资产加载到受信任的代理环境前，请务必审查资产内容。\n\n- 技能可能指示代理读取本地文件或运行命令\n- 钩子可以在代理支持时执行代码\n- MCP 配置可能扩展工具访问范围\n- 安装命令可能修改本地环境\n- 切勿将密钥粘贴到代理上下文中\n\n### 安全审计命令\n\n```sh\napx security-audit\n```\n\n此命令会扫描以下高风险模式：\n\n| 检查项 | 严重级别 | 说明 |\n|--------|----------|------|\n| `unpinned-latest-image` | P1 | CI 配置中使用未固定版本的 :latest 镜像 |\n| `broad-filesystem-write` | P1 | 宽泛的文件系统写入或递归删除模式 |\n| `missing-dry-run` | P1 | 安装命令缺少 --dry-run 保护 |\n\n资料来源：[src/cli/commands/security-audit.ts]()\n\n## 故障排除\n\n### 常见问题\n\n**Q: apx 命令未找到**\n```sh\nnpm install -g agent-powerups\n# 或\nnpm link # 如果从源码安装\n```\n\n**Q: 安装后代理无法识别技能**\n检查代理根目录下是否正确创建了 skills/ 目录，并确认 AGENTS.md 中包含了 agent-powerups 指令块。\n\n**Q: MCP 配置安装失败**\n```sh\napx mcp check github-local --target --json\napx mcp smoke github-local --json\n```\n\n### 完整回滚\n\n如需完全移除安装的资产：\n\n```sh\n# 对于 Codex\nRemove-Item \\agent-powerups -Recurse -Force\n\n# 对于 Claude Code\nRemove-Item \\agent-powerups -Recurse -Force\n```\n\n资料来源：[examples/minimal/README.md]()\n\n## 相关资源\n\n- [快速开始指南](./README.md#quickstart)\n- [安全模型说明](./docs/security-model.md)\n- [兼容性矩阵](./docs/compatibility.md)\n- [贡献指南](./CONTRIBUTING.md)\n- [API 文档](../src/cli/apx.ts)\n\n---\n\n\n\n## apx CLI 参考\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [资产目录系统](#catalog-system), [插件包系统](#plugin-bundles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/commands/phase-workflows.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/phase-workflows.ts)\n- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)\n \n\n# apx CLI 参考\n\n## 概述\n\n`apx` 是 agent-powerups 项目的核心命令行工具，提供类似 Oh My Zsh 的体验，为编码代理（coding agents）提供可复用的技能、命令、工作流和配置管理能力。该工具以 TypeScript 开发，通过 npm 包发布，旨在标准化和简化各类编码代理的环境配置与日常操作。\n\n`apx` 的设计理念强调**本地优先（local-first）**、**安全审计（security-first）**和**渐进式配置（progressive setup）**，支持干运行（dry-run）、交互式确认和幂等操作。\n\n## 核心功能模块\n\n| 模块 | 功能描述 | 典型场景 |\n|------|----------|----------|\n| `install` | 安装技能和插件到指定代理根目录 | 快速部署一套完整的开发环境 |\n| `setup` | 代理托管式配置，支持多模式 | 引导式安装，适合不熟悉命令行的用户 |\n| `mcp` | MCP 服务器配置管理 | GitHub MCP 的本地检查、烟雾测试和安装 |\n| `agents-md` | AGENTS.md 模板管理 | 初始化新项目的代理指令模板 |\n| `commands` | 命令包管理和执行 | 自动化代码审查和发布检查 |\n| `hooks` | 钩子脚本管理 | 代码提交前的安全预检 |\n| `workflows` | 工作流编排 | 自动化项目迭代和部署流程 |\n| `plugins` | 插件包管理 | 安装和管理第三方扩展插件 |\n| `profiles` | 用户意图配置集 | 预定义的安全核心配置组合 |\n| `check` | 依赖检查 | 验证技能所需工具是否满足 |\n| `ask-*` | 多代理咨询 | 向 Codex/Claude/Gemini 发送请求 |\n| `relay` | 持久化中继会话 | 跨轮次保持上下文状态 |\n| `security-audit` | 安全审计 | 扫描代码库中的安全隐患 |\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[\"用户终端\"] --> B[\"apx CLI 入口
src/cli/apx.ts\"]\n B --> C{\"命令路由\"}\n C --> D[\"install\"]\n C --> E[\"setup\"]\n C --> F[\"mcp\"]\n C --> G[\"check\"]\n C --> H[\"ask-*\"]\n C --> I[\"relay\"]\n C --> J[\"plugins\"]\n C --> K[\"profiles\"]\n \n D --> L[\"技能安装逻辑\"]\n E --> M[\"setup.ts
代理托管式安装\"]\n F --> N[\"MCP 配置管理\"]\n G --> O[\"requirements.ts
依赖检查\"]\n H --> P[\"外部代理 API\"]\n I --> Q[\"持久会话状态\"]\n J --> R[\"插件bundles\"]\n K --> S[\"用户意图配置\"]\n \n L --> T[\"目标代理根目录
codex / claude-code / gemini\"]\n M --> T\n N --> U[\"github-local MCP\"]\n O --> V[\"npm / pip / cargo
依赖解析\"]\n```\n\n## 命令速查表\n\n### 安装与配置\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx install ` | 安装到指定代理 | `--dry-run`, `--full`, `--verbose`, `--agent-root` |\n| `apx install --target ` | 安装单个资产 | `--dry-run`, `--dest` |\n| `apx setup --mode ` | 代理托管式配置 | `--mode minimal\\|recommended\\|full`, `--dry-run`, `--yes` |\n| `apx mcp install --target ` | 安装 MCP 配置 | `--dry-run`, `--yes`, `--dest` |\n\n### 查询与列表\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx list` | 列出所有可用技能 | - |\n| `apx info ` | 查看技能详情 | - |\n| `apx check ` | 检查技能依赖 | `--install-missing`, `--dry-run` |\n| `apx mcp list` | 列出 MCP 配置 | - |\n| `apx agents-md list` | 列出 AGENTS.md 模板 | - |\n| `apx commands list` | 列出命令包 | - |\n| `apx hooks list` | 列出钩子 | - |\n| `apx workflows list` | 列出工作流 | - |\n| `apx plugins list` | 列出插件包 | - |\n| `apx profiles list` | 列出配置集 | - |\n\n### 执行与操作\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx ask-codex \"\"` | 询问 Codex | `--json` |\n| `apx ask-claude \"\"` | 询问 Claude | `--json` |\n| `apx ask-gemini \"\"` | 询问 Gemini | `--json` |\n| `apx relay init ` | 初始化中继会话 | - |\n| `apx relay start --provider ` | 启动中继 | `--json` |\n| `apx relay ask \"\"` | 通过中继询问 | `--json` |\n| `apx commands run ship-check` | 运行发货检查 | `--full`, `--json` |\n| `apx hooks run no-secrets-preflight` | 运行无密钥预检 | `--path`, `--all`, `--json` |\n| `apx phase ` | 阶段式工作流 | `discuss`, `plan`, `execute`, `verify` |\n\n### 验证与审计\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx doctor` | 诊断 apx 自身状态 | `--full`, `--json` |\n| `apx mcp check ` | 检查 MCP 配置 | `--target`, `--json` |\n| `apx mcp smoke ` | 烟雾测试 MCP | `--json` |\n| `apx security-audit --path ` | 安全审计 | `--all`, `--json` |\n| `apx audit repo` | 仓库审计 | `--json` |\n| `apx plugin validate ` | 验证插件 | `--json` |\n\n## 详细命令说明\n\n### install - 资产安装\n\n`install` 命令是 apx 的核心命令之一，用于将技能、插件和配置安装到指定代理的根目录。\n\n```mermaid\ngraph LR\n A[\"输入: apx install codex\"] --> B[\"解析 --target 参数\"]\n B --> C{\"INSTALL_TARGETS 检查\"}\n C -->|通过| D[\"定位代理根目录\"]\n C -->|失败| E[\"抛出错误\"]\n D --> F[\"复制 skills/ 到目标\"]\n F --> G[\"复制 plugins/ 到目标\"]\n G --> H[\"可选: 复制 agent-powerups/ 资源\"]\n H --> I[\"完成\"]\n```\n\n**安装模式对比：**\n\n| 模式 | 说明 | 适用范围 |\n|------|------|----------|\n| 默认安装 | 仅复制 skills 和 plugins bundles | 常规使用 |\n| `--full` | 完整安装，包含 support assets 和全局指令更新 | 深度集成 |\n| `--verbose` | 显示每个文件的复制路径 | 调试排查 |\n\n**命令示例：**\n\n```bash\n# 干运行查看安装计划\napx install codex --dry-run\n\n# 完整安装到 Codex\napx install codex --full --verbose\n\n# 安装单个技能到 Claude Code\napx install markitdown-file-intake --target claude-code --dry-run\n\n# 指定自定义代理根目录\napx install gemini --agent-root ~/.config/agent/gemini\n```\n\n资料来源：[src/cli/apx.ts:45-80]()\n\n### setup - 代理托管式配置\n\n`setup` 命令提供引导式配置体验，支持三种预设模式，自动生成配置指令。\n\n```mermaid\ngraph TD\n A[\"apx setup \"] --> B{\"模式选择\"}\n B -->|\"minimal\"| C[\"bootstrap 模式\"]\n B -->|\"recommended\"| D[\"推荐模式\"]\n B -->|\"full\"| E[\"完整模式\"]\n \n C --> F[\"生成基础 AGENTS.md 块\"]\n D --> G[\"生成技能 + 插件说明\"]\n E --> H[\"生成全量功能说明\"]\n \n F --> I{\"目标文件存在?\"}\n G --> I\n H --> I\n \n I -->|存在| J[\"追加到现有文件
备份 .bak\"]\n I -->|不存在| K[\"创建 agent-powerups.md\"]\n J --> L[\"完成\"]\n K --> L\n```\n\n**配置模式说明：**\n\n| 模式 | 内容 | 推荐场景 |\n|------|------|----------|\n| `minimal` | 引导用户读取 using-powerups、apx 使用说明、MCP 审批提示 | 新用户快速体验 |\n| `recommended` | minimal + 技能路径说明 + 推荐命令提示 | 大多数用户的推荐选择 |\n| `full` | 全功能说明和最佳实践 | 深度用户和自动化场景 |\n\n资料来源：[src/cli/commands/setup.ts:50-100]()\n\n### mcp - MCP 服务器配置\n\nMCP（Model Context Protocol）配置管理提供本地 GitHub MCP 的检查、烟雾测试和安装能力。\n\n| 子命令 | 功能 |\n|--------|------|\n| `apx mcp list` | 列出可用 MCP 配置 |\n| `apx mcp print --target ` | 打印配置详情 |\n| `apx mcp check --target ` | 验证配置有效性 |\n| `apx mcp smoke ` | 执行烟雾测试 |\n| `apx mcp install --target ` | 安装到目标代理 |\n| `apx mcp write --target --dest ` | 导出配置到指定路径 |\n\n**工作流程：**\n\n```mermaid\ngraph LR\n A[\"mcp check\"] --> B{\"配置有效?\"}\n B -->|是| C[\"mcp smoke\"]\n B -->|否| D[\"报告错误\"]\n C --> E{\"烟雾测试通过?\"}\n E -->|是| F[\"mcp install\"]\n E -->|否| G[\"报告问题\"]\n F --> H[\"完成\"]\n```\n\n### check - 依赖检查\n\n`check` 命令验证技能所需工具是否已安装，支持自动安装缺失依赖。\n\n```mermaid\ngraph TD\n A[\"apx check \"] --> B[\"加载技能定义\"]\n B --> C[\"解析 requires 字段\"]\n C --> D[\"检测系统工具\"]\n D --> E{\"所有依赖满足?\"}\n E -->|是| F[\"输出 OK 状态\"]\n E -->|否| G{\"--install-missing?\"}\n G -->|是| H[\"调用 requirements.ts\"]\n G -->|否| I[\"输出 MISSING 状态\"]\n H --> J{\"有支持的安装器?\"}\n J -->|是| K[\"显示安装命令预览\"]\n J -->|否| L[\"提示手动安装\"]\n K --> M{\"--dry-run?\"}\n M -->|是| N[\"仅显示计划\"]\n M -->|否| O[\"执行安装\"]\n```\n\n**依赖解析逻辑：**\n\n`requirements.ts` 中的 `installMissingRequirements` 函数负责解析缺失依赖，并调用对应的包管理器：\n\n| 包管理器 | 探测命令 | 参数 |\n|----------|----------|------|\n| npm | `npm install` | `-g` 全局或本地 |\n| pip | `pip install` | `-q` 静默模式 |\n| cargo | `cargo install` | - |\n| gem | `gem install` | `-N` 不生成文档 |\n\n资料来源：[src/cli/commands/check.ts:30-80]()\n\n资料来源：[src/cli/utils/requirements.ts:1-60]()\n\n### ask-* - 多代理咨询\n\n`ask-*` 命令提供统一的接口向外部编码代理发送请求：\n\n| 命令 | 代理 | 输出格式 |\n|------|------|----------|\n| `apx ask-codex` | OpenAI Codex | JSON 或文本 |\n| `apx ask-claude` | Anthropic Claude | JSON 或文本 |\n| `apx ask-gemini` | Google Gemini | JSON 或文本 |\n\n**使用场景：**\n\n```bash\n# 询问代码解释\napx ask-codex \"Explain this code\" --json\n\n# 代码审查\napx ask-claude \"Review this patch\" --json\n\n# 头脑风暴测试用例\napx ask-gemini \"Brainstorm test cases\" --json\n```\n\n### relay - 持久中继会话\n\n`relay` 命令维护跨轮次的持久会话，保持上下文状态，特别适合需要多轮协作的场景。\n\n```mermaid\ngraph TD\n A[\"relay init \"] --> B[\"创建会话状态\"]\n B --> C[\"relay start --provider \"]\n C --> D[\"建立持久连接\"]\n D --> E[\"relay ask ''\"]\n E --> F[\"发送消息\"]\n F --> G[\"接收响应\"]\n G --> H{\"需要继续?\"}\n H -->|是| E\n H -->|否| I[\"relay stop \"]\n```\n\n**中继会话管理：**\n\n| 子命令 | 说明 |\n|--------|------|\n| `relay init ` | 初始化新会话 |\n| `relay start --provider ` | 启动会话 |\n| `relay ask \"\"` | 发送消息 |\n| `relay status ` | 查看状态 |\n| `relay stop ` | 停止会话 |\n\n### security-audit - 安全审计\n\n`security-audit` 命令扫描代码库中的常见安全风险，包括硬编码密钥、不安全的 shell 命令和不推荐的镜像标签。\n\n**支持的检测规则：**\n\n| 规则名称 | 严重级别 | 检测模式 |\n|----------|----------|----------|\n| `api-key-detected` | P0 | 常见 API 密钥格式 |\n| `private-key-detected` | P0 | RSA/ED25519 私钥 |\n| `aws-access-key` | P0 | AWS 访问密钥 |\n| `aws-secret-key` | P0 | AWS 密钥 ID |\n| `github-token` | P0 | GitHub Token |\n| `broad-filesystem-write` | P1 | 递归删除或通配符写 |\n| `missing-dry-run` | P1 | 安装命令缺少 --dry-run |\n\n**扫描范围：**\n\n- 文件扩展白名单：`.json`, `.toml`, `.md`, `.sh`, `.ps1`, `.yaml`, `.yml`\n- 跳过目录：`node_modules`, `dist`, `.git`, `.worktrees`, `.plugins`\n- 最大文件大小：512 KB\n\n资料来源：[src/cli/commands/security-audit.ts:1-50]()\n\n### phase - 阶段式工作流\n\n`phase` 命令实现项目开发的阶段化工作流，支持讨论、计划、执行和验证阶段。\n\n```mermaid\ngraph LR\n A[\"phase discuss\"] --> B[\"需求澄清\"]\n B --> C[\"phase plan\"]\n C --> D[\"PRD 生成\"]\n C --> E[\"MVP 规划\"]\n D --> F[\"phase execute\"]\n E --> F\n F --> G[\"按 wave 执行\"]\n G --> H[\"phase verify\"]\n H --> I{\"验证通过?\"}\n I -->|否| G\n I -->|是| J[\"完成\"]\n```\n\n**阶段子命令：**\n\n| 子命令 | 说明 | 关键参数 |\n|--------|------|----------|\n| `phase discuss ` | 讨论指定阶段 | `--planning-root`, `--json` |\n| `phase plan ` | 制定计划 | `--research`, `--prd`, `--mvp` |\n| `phase execute ` | 执行计划 | `--wave`, `--interactive` |\n| `phase verify ` | 验证结果 | - |\n\n资料来源：[src/cli/commands/phase-workflows.ts:1-40]()\n\n## 代理目标\n\napx 支持多个编码代理平台作为安装目标：\n\n| 目标标识 | 代理产品 | 配置目录 |\n|----------|----------|----------|\n| `codex` | OpenAI Codex | `~/.codex/` |\n| `claude-code` | Claude Code | `~/.claude/` |\n| `gemini` | Google Gemini CLI | `~/.gemini/` |\n| `generic` | 通用目标 | 用户指定 |\n\n安装时通过 `--target ` 参数指定目标，未指定时使用对应代理的默认配置目录。\n\n## 输出格式\n\n大多数 apx 命令支持 JSON 输出，便于脚本集成和自动化处理：\n\n```bash\n# 获取 JSON 格式输出\napx list --json\napx check markitdown-file-intake --json\napx security-audit --all --json\n\n# 干运行模式\napx install codex --dry-run\n```\n\n## 错误处理与安全\n\n### 幂等性保证\n\napx 命令设计为幂等操作：\n\n- `install` 重复执行不会重复复制已存在文件\n- `setup` 在 AGENTS.md 存在时会创建备份 `.bak`\n- `--dry-run` 选项允许预览行为而不实际修改\n\n### 安全边界\n\napx 在以下方面保持安全边界：\n\n- **外部工具**：需要用户显式批准安装\n- **密钥**：内置 `no-secrets-preflight` 钩子检测\n- **Shell 配置**：不自动修改 shell 启动文件\n- **MCP 服务器**：需要显式启用确认\n\n### 诊断工具\n\n```bash\n# 基础诊断\napx doctor\n\n# 完整诊断（JSON）\napx doctor --full --json\n\n# 仓库审计\napx audit repo --json\n```\n\n## 快速参考\n\n### 首次使用\n\n```bash\nnpm install\nnpm run build\nnpm link\napx doctor\napx list\n```\n\n### 常见工作流\n\n**部署到 Codex：**\n\n```bash\napx setup codex --mode recommended --yes\n```\n\n**检查技能依赖：**\n\n```bash\napx check markitdown-file-intake\napx check defuddle --install-missing --dry-run\n```\n\n**运行安全扫描：**\n\n```bash\napx security-audit --path ./src\napx hooks run no-secrets-preflight --all\n```\n\n**多代理咨询：**\n\n```bash\napx ask-claude \"Review this PR\" --json\napx relay start second-opinion --provider gemini\napx relay ask second-opinion \"Analyze this architecture\" --json\n\n---\n\n\n\n## 资产目录系统\n\n### 相关页面\n\n相关主题：[技能系统](#skills), [apx CLI 参考](#cli-reference), [插件包系统](#plugin-bundles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [catalog.json](https://github.com/yeaight7/agent-powerups/blob/main/catalog.json)\n- [docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)\n- [scripts/validate-skills.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-skills.py)\n- [scripts/validate-catalog.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-catalog.py)\n- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)\n \n\n# 资产目录系统\n\n## 概述\n\nAgent Powerups 的资产目录系统是一个集中管理、可验证的资产清单，涵盖可复用的技能、工作流、命令模板、MCP 配置和 AGENTS.md 模板。该系统采用声明式 JSON 格式定义所有资产元数据，并通过自动化验证脚本确保目录内容的完整性和一致性。资产目录的核心价值在于为编码代理提供\"Oh My Zsh 风格\"的可插拔组件库，开发者可以通过 `apx` CLI 工具浏览、安装和验证这些资产。\n\n## 目录架构\n\n资产目录采用分层架构设计，将不同类型的资产分别归类管理：\n\n```mermaid\ngraph TD\n A[agent-powerups 仓库] --> B[根级资产目录]\n A --> C[插件包 bundle]\n B --> D[skills/ 技能目录]\n B --> E[mcp/ MCP配置]\n B --> F[agents-md/ 模板]\n B --> G[commands/ 命令集]\n B --> H[hooks/ 钩子示例]\n B --> I[workflows/ 工作流]\n C --> J[17个插件包]\n C --> K[技能 + 代理 + 命令组合]\n```\n\n目录结构与资产类型的对应关系如下：\n\n| 路径 | 状态 | 说明 |\n|------|------|------|\n| `skills/` | 已发布 | 可复用代理工作流，如 `systematic-debugging`、`writing-plans` |\n| `mcp/` | 已发布 | 本地优先 GitHub MCP 配置，含检查、冒烟测试和显式安装命令 |\n| `agents-md/` | 已发布 | 启动器 AGENTS.md 模板 |\n| `commands/` | 已发布 | 审查优先命令提示词及安全可运行检查 |\n| `hooks/` | 已发布 | 钩子示例：preflight、summary、validation |\n| `workflows/` | 已发布 | 工作流定义：feature-iteration、agent-relay |\n| `plugins/` | 已发布 | 17个插件包（3个稳定版、10个测试版、4个实验版） |\n\n## 目录清单结构\n\n### 技能资产 (Skills)\n\n当前已发布的技能共 23 个，涵盖调试、规划、代码审查、数据工程等多个领域：\n\n| 技能名称 | 功能分类 |\n|----------|----------|\n| `systematic-debugging` | 调试 |\n| `no-fluff` | 文档 |\n| `writing-plans` | 规划 |\n| `ai-slop-cleaner` | 文档 |\n| `bigquery-cost-audit` | 数据工程 |\n| `data-quality` | 数据工程 |\n| `dbt-incremental-strategy-audit` | 数据工程 |\n| `dbt-preflight` | 数据工程 |\n| `dbt-strategy` | 数据工程 |\n| `metric-impact-analyzer` | 分析 |\n| `requesting-code-review` | 协作 |\n| `receiving-code-review` | 协作 |\n| `pr-triage` | 协作 |\n| `repo-map` | 导航 |\n| `bug-hunt` | 调试 |\n| `safe-refactor` | 重构 |\n| `sql-business-logic-review` | 审查 |\n| `defuddle` | 工具 |\n| `markitdown-file-intake` | 工具 |\n| `graphify` | 可视化 |\n| `ask-claude` | 集成 |\n| `ask-gemini` | 集成 |\n| `ask-codex` | 集成 |\n| `using-powerups` | 入门 |\n\n资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n### 插件包资产 (Plugin Bundles)\n\n插件包是技能、代理和命令的组合，按成熟度分为三个等级：\n\n#### 稳定版插件包 (Stable)\n\n| 插件包名称 | 描述 |\n|------------|------|\n| `dev-vitals` | 开发健康指标 |\n| `debugging-diagnostics` | 调试诊断 |\n| `quality-gates` | 质量门禁 |\n\n#### 测试版插件包 (Beta)\n\n| 插件包名称 | 描述 |\n|------------|------|\n| `codebase-maintenance` | 代码库维护 |\n| `data-engineering` | 数据工程 |\n| `documentation-systems` | 文档系统 |\n| `machine-learning-ops` | 机器学习运维 |\n| `codebase-intelligence` | 代码库智能 |\n| `spec-driven-development` | 规范驱动开发 |\n| `spec-quality-gates` | 对抗性计划验证和结构化代码审查 |\n| `context-efficiency` | 上下文高效调度路由 |\n| `tool-integrations` | 工具集成 |\n| `memory-optimization` | 内存优化 |\n\n#### 实验版插件包 (Experimental)\n\n| 插件包名称 | 描述 |\n|------------|------|\n| `software-engineering` | 软件工程 |\n| `agentic-systems` | 代理系统 |\n| `security-guardrails` | 安全护栏 |\n| `agent-evaluation-lab` | 代理评估实验室 |\n\n每个插件遵循标准编码代理插件布局：\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code 清单\n├── .codex-plugin/\n│ └── plugin.json # Codex 清单\n├── skills/\n│ └── /\n│ └── SKILL.md\n├── agents/\n│ └── .md\n└── commands/\n └── .md\n```\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n### AGENTS.md 模板资产\n\n| 模板名称 | 适用场景 |\n|----------|----------|\n| `typescript-app` | TypeScript 应用开发 |\n| `python-library` | Python 库开发 |\n| `dbt-project` | dbt 数据转换项目 |\n| `ml-project` | 机器学习项目 |\n| `open-source-maintainer` | 开源项目维护 |\n\n### 命令资产 (Commands)\n\n| 命令包名称 | 功能 |\n|------------|------|\n| `ship-check` | 发布前检查 |\n| `using-powerups-command` | Powerups 使用指导 |\n\n### 钩子示例资产 (Hooks)\n\n| 钩子名称 | 触发场景 |\n|----------|----------|\n| `no-secrets-preflight` | 提交前秘密检查 |\n| `handoff-summary` | 交接摘要生成 |\n| `validation-required` | 验证必需触发 |\n\n### 工作流资产 (Workflows)\n\n| 工作流名称 | 用途 |\n|------------|------|\n| `feature-iteration` | 功能迭代流程 |\n| `agent-relay` | 代理中继通信 |\n\n### MCP 配置资产\n\n| 配置名称 | 说明 |\n|----------|------|\n| `github-local` | 本地 GitHub MCP 配置，含检查、冒烟测试和显式安装命令 |\n\n## 目录验证机制\n\n### 验证脚本体系\n\n项目包含三个核心验证脚本，确保目录内容的有效性：\n\n```mermaid\ngraph LR\n A[validate-skills.py] --> B[技能元数据检查]\n A --> C[SKILL.md 存在性]\n A --> D[支持文件引用]\n \n E[validate-catalog.py] --> F[catalog.json 格式]\n E --> G[资产完整性]\n E --> H[引用有效性]\n \n I[check-requirements.py] --> J[依赖检查]\n J --> K[可选自动安装]\n```\n\n#### 技能验证脚本 (validate-skills.py)\n\n`validate-skills.py` 负责验证所有技能资产的结构完整性：\n\n- 检查每个技能目录下是否存在 `SKILL.md` 文件\n- 验证 frontmatter 中是否包含 `name` 和 `description` 必需字段\n- 检查技能内容长度是否满足最小要求\n- 验证支持文件的引用是否指向实际存在的文件\n\n```sh\npython scripts/validate-skills.py\n```\n\n资料来源：[scripts/validate-skills.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-skills.py)\n\n#### 目录验证脚本 (validate-catalog.py)\n\n`validate-catalog.py` 验证整个目录清单的正确性：\n\n- 验证 `catalog.json` 格式是否符合 schema\n- 确保所有声明的资产在文件系统中实际存在\n- 检查资产引用的完整性\n\n```sh\npython scripts/validate-catalog.py\n```\n\n资料来源：[scripts/validate-catalog.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-catalog.py)\n\n#### 依赖检查脚本 (check-requirements.py)\n\n`check-requirements.py` 检查运行技能所需的依赖项：\n\n- 识别缺失的外部依赖\n- 提供安装提示（`installHint`）\n- 支持自动安装可用的依赖\n\n```sh\npython scripts/check-requirements.py\n```\n\n资料来源：[src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n\n### 验证检查项\n\n| 检查项 | 描述 | 状态码 |\n|--------|------|--------|\n| `skill-files` | SKILL.md 文件存在性 | OK/WARNING |\n| `skill-frontmatter` | 必需 frontmatter 字段 | OK/WARNING |\n| `skill-content-length` | 内容长度最小值 | WARN/OK |\n| `catalog-schema` | catalog.json schema 符合性 | PASS/FAIL |\n| `asset-existence` | 资产文件实际存在 | PASS/FAIL |\n\n## CLI 命令集成\n\n### 目录浏览命令\n\n| 命令 | 功能 |\n|------|------|\n| `apx list` | 列出所有可用资产 |\n| `apx info ` | 显示资产详细信息 |\n| `apx check ` | 检查资产完整性 |\n| `apx commands run ` | 运行指定命令 |\n\n```sh\n# 浏览目录\napx list\n\n# 查看特定技能\napx info markitdown-file-intake\n\n# 运行命令检查\napx commands run ship-check\n\n# 运行钩子检查\napx hooks run no-secrets-preflight --all\n\n# MCP 配置检查\napx mcp check github-local --target generic\napx mcp smoke github-local --json\n```\n\n### 插件管理命令\n\n| 命令 | 功能 |\n|------|------|\n| `apx plugins list` | 列出所有插件包 |\n| `apx plugins info ` | 显示插件详情 |\n| `apx plugins validate --all` | 验证所有插件结构 |\n| `apx plugins install --target ` | 安装插件 |\n\n```sh\napx plugins list\napx plugins info dev-vitals\napx plugins validate --all\napx plugins install dev-vitals --target codex --dry-run\n```\n\n### 审计命令\n\n`apx audit` 命令提供系统性的资产审计功能：\n\n```sh\napx audit skills\napx audit plugins\n```\n\n审计输出格式：\n\n```\naudit skills: 5 pass, 2 warn, 0 fail\n[OK] skill-frontmatter: all have name + description\n[WARN] skill-content-length: 2 skill(s) under 500 chars\n```\n\n## 目录模式 (Catalog Schema)\n\n目录采用 JSON Schema 定义资产元数据规范，核心字段包括：\n\n```json\n{\n \"name\": \"资产名称\",\n \"description\": \"资产描述\",\n \"path\": \"相对于仓库根的路径\",\n \"maturity\": \"stable|beta|experimental\",\n \"tags\": [\"标签1\", \"标签2\"],\n \"requires\": {\n \"skills\": [\"依赖技能\"],\n \"tools\": [\"依赖工具\"]\n }\n}\n```\n\n资料来源：[docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)\n\n## 安全考量\n\n资产目录系统内置多层安全保护机制：\n\n### 部署前检查\n\n- 技能可指导代理读取本地文件或执行命令\n- 钩子可在宿主代理支持时执行代码\n- MCP 配置可扩展工具访问范围\n- 安装命令可修改本地环境\n\n### 安装保护\n\n所有安装操作默认处于干运行模式，需要显式授权才能执行：\n\n```sh\napx install codex --dry-run # 预览不执行\napx install codex # 实际执行\n```\n\n### 秘密管理\n\n- 秘密绝不应粘贴到代理上下文，除非严格必要\n- MCP 服务器需要显式用户批准\n- 外部工具安装需要用户批准\n\n## 与代理的集成\n\n### 代理兼容性矩阵\n\n| 资产类别 | 当前状态 | 兼容性声明 |\n|----------|----------|------------|\n| 根 `skills/` | 是 | 通用文本技能；部分提及已知代理表面 |\n| `mcp/` | 是 | 提供特定代理的 MCP 配置 |\n\n资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n### 支持的代理平台\n\n| 代理平台 | 配置路径 | 说明 |\n|----------|----------|------|\n| Codex | `.codex-plugin/plugin.json` | Codex 清单定义 |\n| Claude Code | `.claude-plugin/plugin.json` | Claude Code 清单定义 |\n| Gemini | `gemini-extension.json` + `GEMINI.md` | Gemini 插件包 |\n\n## 维护工作流\n\n仓库维护应持续运行验证检查：\n\n```mermaid\ngraph TD\n A[修改资产文件] --> B[运行 validate-skills.py]\n B --> C{检查通过?}\n C -->|是| D[运行 validate-catalog.py]\n C -->|否| E[修复问题]\n E --> B\n D --> F{检查通过?}\n F -->|是| G[运行 check-requirements.py]\n F -->|否| H[修复问题]\n H --> D\n G --> I[提交更改]\n```\n\n建议的维护命令序列：\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\npython scripts/check-requirements.py\n```\n\n## 总结\n\n资产目录系统是 Agent Powerups 的核心基础设施，提供了一套完整、可验证的资产管理体系。通过声明式清单、自动化验证和 CLI 工具集成，开发者可以安全地发现、安装和使用预构建的代理资源。该系统支持多代理平台（Codex、Claude Code、Gemini），并通过插件包机制实现了资产的分层组织和按需扩展。\n\n---\n\n\n\n## 插件包系统\n\n### 相关页面\n\n相关主题：[资产目录系统](#catalog-system), [apx CLI 参考](#cli-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)\n- [.claude-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.claude-plugin/marketplace.json)\n- [.codex-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.codex-plugin/marketplace.json)\n- [docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)\n \n\n# 插件包系统\n\n## 概述\n\n插件包系统（Plugin Bundle System）是 Agent Powerups 项目中用于组织、发布和分发功能模块的核心机制。该系统借鉴了 \"Oh My Zsh\" 的插件管理模式，将相关的 skills（技能）、agents（代理模板）、commands（命令）和 templates（模板）打包成独立的插件单元，支持多 agent 平台的安装与同步。\n\n插件包系统的主要职责包括：\n\n- **模块化封装**：将功能资源按领域分类，形成可独立管理的插件单元\n- **跨平台兼容**：通过统一的 manifest 定义，支持 Codex、Claude Code、Gemini 等多种 coding agent\n- **生命周期管理**：通过成熟度等级（maturity）区分实验性功能和稳定功能\n- **标准化安装**：提供 `apx` CLI 工具实现插件的发现、验证和安装\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## 插件包结构\n\n### 目录布局\n\n每个插件遵循标准的 coding agent 插件目录结构：\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code 平台清单\n├── .codex-plugin/\n│ └── plugin.json # Codex 平台清单\n├── skills/\n│ └── /\n│ └── SKILL.md # 技能定义文件\n├── agents/\n│ └── .md # 代理模板文件\n└── commands/\n └── .md # 命令定义文件\n```\n\n根级别的 skills 位于 `skills/` 目录，是通用型独立技能。插件内的 skills 是领域专用的，提供更深入的功能覆盖。同一主题的插件技能不得替代或覆盖根级别技能。\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n### Manifest 文件\n\n每个插件包含针对不同 agent 平台的 manifest 文件，定义了插件的元数据和资源引用。\n\n**Claude Code Manifest 示例结构：**\n\n```json\n{\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"maturity\": \"stable\",\n \"skills\": [\n { \"name\": \"dev-vitals-check\", \"path\": \"skills/dev-vitals-check\" }\n ],\n \"commands\": [\n { \"name\": \"dev-vitals\", \"path\": \"commands/dev-vitals.md\" }\n ]\n}\n```\n\n**Codex Manifest 示例结构：**\n\n```json\n{\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"maturity\": \"stable\",\n \"skills\": [\"skills/dev-vitals-check\"],\n \"commands\": [\"commands/dev-vitals.md\"]\n}\n```\n\n两个平台的 manifest 格式略有差异：Codex 版本使用字符串路径数组，Claude Code 版本使用对象数组（包含 name 和 path 属性）。\n\n## 成熟度等级\n\n插件包根据功能稳定性和适用场景分为三个成熟度等级：\n\n| 等级 | 说明 | 风险级别 | 适用场景 |\n|------|------|----------|----------|\n| **stable** | 稳定版本，经过充分测试 | 低 | 生产环境推荐使用 |\n| **beta** | 测试版本，功能基本可用 | 中 | 评估新功能，探索性项目 |\n| **experimental** | 实验性版本，可能有破坏性变更 | 高 | 高级用户尝鲜，不建议生产使用 |\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## 插件包清单\n\n当前仓库包含 17 个插件包，分布如下：\n\n### 稳定版插件（Stable）\n\n| 插件名称 | 描述 | Maturity |\n|----------|------|----------|\n| `dev-vitals` | 开发健康指标与监控 | stable |\n| `debugging-diagnostics` | 调试与诊断技能集 | stable |\n| `quality-gates` | 质量门禁检查流程 | stable |\n\n### Beta 版插件\n\n| 插件名称 | 描述 | Maturity |\n|----------|------|----------|\n| `codebase-maintenance` | 代码库维护任务集 | beta |\n| `data-engineering` | 数据工程相关技能 | beta |\n| `documentation-systems` | 文档系统生成与管理 | beta |\n| `machine-learning-ops` | ML 运维工作流 | beta |\n| `codebase-intelligence` | 代码库智能分析 | beta |\n| `spec-driven-development` | 规范驱动的开发流程 | beta |\n| `spec-quality-gates` | 对抗性计划验证与结构化代码审查 | beta |\n| `context-efficiency` | 上下文高效的调度路由 | beta |\n| `tool-integrations` | 工具集成扩展 | beta |\n| `memory-optimization` | 内存优化策略 | beta |\n\n### 实验版插件（Experimental）\n\n| 插件名称 | 描述 | Maturity |\n|----------|------|----------|\n| `software-engineering` | 软件工程最佳实践 | experimental |\n| `agentic-systems` | 代理系统设计模式 | experimental |\n| `security-guardrails` | 安全防护机制 | experimental |\n| `agent-evaluation-lab` | 代理评估实验框架 | experimental |\n\n资料来源：[plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)\n\n## 插件包元数据模式\n\n插件包的元数据定义在 `plugin-bundles.json` 中，每个插件条目包含以下字段：\n\n| 字段 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `name` | string | 是 | 插件唯一标识符 |\n| `description` | string | 是 | 插件功能描述 |\n| `maturity` | string | 是 | 成熟度等级：stable/beta/experimental |\n| `readme` | string | 否 | 文档相对路径 |\n| `skills` | array | 否 | 包含的技能列表 |\n| `agents` | array | 否 | 包含的代理模板列表 |\n| `commands` | array | 否 | 包含的命令列表 |\n| `templates` | array | 否 | 包含的模板列表 |\n| `workflows` | array | 否 | 包含的工作流列表 |\n\n资料来源：[docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)\n\n### 技能条目结构\n\n```json\n{\n \"name\": \"skill-name\",\n \"description\": \"技能描述\",\n \"path\": \"skills/skill-name\"\n}\n```\n\n### 代理模板条目结构\n\n```json\n{\n \"name\": \"agent-name\",\n \"description\": \"代理模板描述\",\n \"path\": \"agents/agent-name.md\"\n}\n```\n\n## 工作流程\n\n### 插件安装流程\n\n以下流程图展示了使用 `apx` CLI 安装插件的标准流程：\n\n```mermaid\ngraph TD\n A[用户执行 apx plugins install] --> B[CLI 解析目标 agent 平台]\n B --> C{是否使用 --dry-run}\n C -->|是| D[生成模拟安装计划]\n C -->|否| E[检查插件目录存在性]\n E --> F{manifest 文件验证}\n F -->|通过| G[复制资源到目标目录]\n F -->|失败| H[输出验证错误]\n G --> I[更新 agent 配置文件]\n I --> J[安装完成]\n D --> J\n```\n\n### 插件发现与检查流程\n\n```mermaid\ngraph TD\n A[用户执行 apx plugins list] --> B[读取 plugin-bundles.json]\n B --> C[扫描 plugins/ 目录]\n C --> D[合并清单数据]\n D --> E[格式化输出插件列表]\n \n F[用户执行 apx plugins info] --> G[定位指定插件]\n G --> H[读取插件 manifest]\n H --> I[输出详细元数据]\n \n J[用户执行 apx plugins validate] --> K[检查 manifest 格式]\n K --> L{符合 schema?}\n L -->|是| M[输出验证通过]\n L -->|否| N[输出验证错误列表]\n```\n\n## CLI 命令参考\n\n### 插件列表\n\n```bash\napx plugins list\n```\n\n列出所有可用的插件包，显示名称、描述和成熟度等级。\n\n### 插件详情\n\n```bash\napx plugins info \n```\n\n查看单个插件的详细元数据，包括包含的 skills、agents、commands 和 templates。\n\n### 插件验证\n\n```bash\napx plugins validate --all\n```\n\n验证所有插件的 manifest 文件结构是否符合规范，检查必需字段和文件路径。\n\n### 插件安装\n\n```bash\n# 模拟安装（预览）\napx plugins install --target codex --dry-run\n\n# 实际安装\napx plugins install --target codex --yes\n```\n\n将插件安装到指定的 agent 平台。`--target` 参数支持 `codex`、`claude-code`、`gemini` 或 `generic`。\n\n### 插件构建\n\n```bash\napx plugins build --dest --dry-run\napx plugins build --dest --write\n```\n\n根据当前仓库中的插件定义生成打包输出。`--dry-run` 模式生成预览，`--write` 模式执行实际写入。\n\n### 插件差异对比\n\n```bash\napx plugin diff \n```\n\n比较插件的实际目录结构与 manifest 声明的差异，识别缺失或未声明的资源文件。\n\n资料来源：[src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n## Marketplace 配置\n\nMarketplace 配置文件定义了插件的市场元数据，用于插件市场的发现和展示。\n\n### Claude Code Marketplace 配置\n\n```json\n{\n \"plugins\": [\n {\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"categories\": [\"diagnostics\", \"quality\"],\n \"tags\": [\"monitoring\", \"metrics\", \"vitals\"]\n }\n ]\n}\n```\n\n### Codex Marketplace 配置\n\n```json\n{\n \"plugins\": [\n {\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"categories\": [\"diagnostics\", \"quality\"],\n \"tags\": [\"monitoring\", \"metrics\", \"vitals\"]\n }\n ]\n}\n```\n\n两个平台的 marketplace 配置结构保持一致，确保跨平台插件发现的一致性体验。\n\n资料来源：[.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)\n\n## 根级技能与插件技能的关系\n\nAgent Powerups 采用分层技能架构：\n\n```mermaid\ngraph BT\n subgraph \"Root Level\"\n R1[systematic-debugging]\n R2[writing-plans]\n R3[no-fluff]\n end\n \n subgraph \"Plugin Level\"\n P1[debugging-diagnostics/debug-tactics]\n P2[spec-driven-development/plan-generator]\n P3[quality-gates/review-check]\n end\n \n R1 -. \"complementary\" .-> P1\n R2 -. \"complementary\" .-> P2\n R3 -. \"complementary\" .-> P3\n```\n\n- **根级别技能**（`skills/`）：通用型技能，专注于通用工作流程\n- **插件技能**：领域专用技能，提供更深入的功能实现\n\n插件技能与根级别技能是互补关系而非替代关系。同一主题的插件技能不会覆盖或替代根级别技能。\n\n## 完整安装与插件安装的区别\n\n| 维度 | `apx install ` | `apx plugins install ` |\n|------|------------------------|--------------------------------|\n| 范围 | 安装所有根级技能和全部插件包 | 仅安装指定的单个插件包 |\n| 目标 | 全量初始化 agent 环境 | 按需添加特定领域功能 |\n| 适用场景 | 全新环境搭建 | 功能扩展 |\n| 灵活性 | 低（全部安装） | 高（按需选择） |\n\n## 安全注意事项\n\n- 插件可以指示 agent 读取本地文件或执行命令\n- MCP 配置可以扩展工具访问权限\n- 安装命令可以修改本地环境\n- 敏感信息（secrets）不应粘贴到 agent 上下文中\n\n在加载插件到受信任的 agent 环境之前，请务必审查插件内容。\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## 最佳实践\n\n1. **安装前验证**：使用 `--dry-run` 模式预览安装计划\n2. **分阶段安装**：从 stable 版本开始，逐步评估 beta 版本\n3. **定期更新**：使用 `apx plugins validate --all` 检查插件完整性\n4. **环境隔离**：使用 `--agent-root` 指定隔离环境进行测试\n5. **备份配置**：重要 agent 配置文件在安装前进行备份\n\n---\n\n\n\n## 技能系统\n\n### 相关页面\n\n相关主题：[资产目录系统](#catalog-system), [命令系统](#commands), [钩子系统](#hooks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [skills/systematic-debugging/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/systematic-debugging/SKILL.md)\n- [skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)\n- [skills/using-powerups/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/using-powerups/SKILL.md)\n- [skills/skill-authoring-guide/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/skill-authoring-guide/SKILL.md)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [src/cli/commands/audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n \n\n# 技能系统\n\n## 概述\n\n技能系统（Skill System）是 Agent Powerups 的核心组件，为编码智能体提供可复用的任务工作流集合。该系统借鉴了 Oh My Zsh 的插件理念，为智能体提供结构化的任务指导、能力扩展和标准化工作流程。技能系统使编码智能体能够执行系统化调试、计划撰写、代码审查、数据质量检查等复杂任务，同时保持行为一致性和可维护性。\n\n技能系统包含 24 个已发布的根技能，涵盖调试、规划、代码审查、数据工程、文档处理等多个领域。技能以 Markdown 文件形式存储，部署时直接复制到智能体的 skills 目录中供其调用。\n\n## 技能分类\n\n### 按功能领域分类\n\n| 技能名称 | 功能领域 | 状态 |\n|----------|----------|------|\n| systematic-debugging | 调试 | 已发布 |\n| bug-hunt | 调试 | 已发布 |\n| writing-plans | 规划 | 已发布 |\n| requesting-code-review | 代码审查 | 已发布 |\n| receiving-code-review | 代码审查 | 已发布 |\n| pr-triage | 代码审查 | 已发布 |\n| sql-business-logic-review | 代码审查 | 已发布 |\n| data-quality | 数据工程 | 已发布 |\n| bigquery-cost-audit | 数据工程 | 已发布 |\n| dbt-preflight | 数据工程 | 已发布 |\n| dbt-strategy | 数据工程 | 已发布 |\n| dbt-incremental-strategy-audit | 数据工程 | 已发布 |\n| metric-impact-analyzer | 数据工程 | 已发布 |\n| defuddle | 文档处理 | 已发布 |\n| markitdown-file-intake | 文档处理 | 已发布 |\n| ai-slop-cleaner | 文档处理 | 已发布 |\n| repo-map | 代码理解 | 已发布 |\n| graphify | 代码理解 | 已发布 |\n| safe-refactor | 重构 | 已发布 |\n| no-fluff | 质量检查 | 已发布 |\n| ask-claude | 智能体协作 | 已发布 |\n| ask-gemini | 智能体协作 | 已发布 |\n| ask-codex | 智能体协作 | 已发布 |\n| using-powerups | 系统引导 | 已发布 |\n\n资料来源：[README.md](./README.md)\n\n### 按来源分类\n\n根技能（Root Skills）位于仓库根目录的 `skills/` 文件夹中，属于通用目的、可独立使用的技能。插件技能（Plugin Skills）位于 `plugins/` 目录下的各插件子目录中，属于领域特定且深度专精的技能。插件技能可能与根技能覆盖相同主题，但不应替换或覆盖根技能。\n\n资料来源：[plugins/README.md](./plugins/README.md)\n\n## 技能结构\n\n### 文件组织\n\n每个技能遵循标准的目录结构：\n\n```\nskills/\n└── /\n └── SKILL.md # 技能定义文件（必需）\n └── support/ # 支持文件目录（可选）\n └── # 技能引用的辅助资源\n```\n\n### SKILL.md 格式规范\n\nSKILL.md 是技能的核心定义文件，包含前置matter元数据和技能内容。文件必须包含以下前置matter字段：\n\n| 字段 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 技能的唯一标识名称 |\n| description | string | 是 | 技能的简要功能描述 |\n| version | string | 否 | 技能版本号 |\n| tags | array | 否 | 技能标签分类 |\n\n前置matter 示例：\n\n```yaml\n---\nname: systematic-debugging\ndescription: A structured approach to debugging issues systematically\nversion: 1.0.0\ntags: [debugging, workflow, quality]\n---\n```\n\n资料来源：[src/cli/commands/doctor.ts:45-58](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n### 技能内容要求\n\n技能文件必须满足以下内容质量标准：\n\n- 技能内容长度不得低于最小阈值（由验证脚本定义）\n- 技能内容必须包含明确的任务指导步骤\n- 技能引用的支持文件必须存在\n\n资料来源：[src/cli/commands/audit.ts:35-50](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n\n## 技能生命周期\n\n### 技能创作流程\n\n技能创作遵循以下标准流程：\n\n```mermaid\ngraph TD\n A[创建 SKILL.md] --> B[定义前置matter]\n B --> C[编写技能内容]\n C --> D[添加支持文件]\n D --> E[运行本地验证]\n E --> F{验证结果}\n F -->|通过| G[提交到仓库]\n F -->|失败| C\n G --> H[自动 CI 检查]\n H --> I[发布到目录]\n```\n\n### 技能创作指南\n\n技能创作指南（skill-authoring-guide）提供以下指导：\n\n- 如何设计有效的技能结构\n- 如何编写清晰的任务描述\n- 如何创建可复用的工作流程\n- 如何维护技能与其他技能的兼容性\n\n资料来源：[skills/skill-authoring-guide/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/skill-authoring-guide/SKILL.md)\n\n## 技能验证机制\n\n### 验证层级\n\n技能验证在多个层级进行，确保质量和一致性：\n\n#### 1. 前置matter 验证\n\n医生命令（doctor）检查每个技能的必要字段：\n\n```typescript\nif (!frontmatter?.name || !frontmatter?.description) {\n issues.push(`${entry.name}: missing required frontmatter`);\n}\n```\n\n资料来源：[src/cli/commands/doctor.ts:50-52](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n#### 2. 支持文件验证\n\n医生命令验证技能引用的支持文件是否存在：\n\n```typescript\nfor (const ref of referencedSupportFiles(content)) {\n if (!(await supportRefExists(skillDir, ref))) {\n issues.push(`${entry.name}: missing referenced support file ${ref}`);\n }\n}\n```\n\n资料来源：[src/cli/commands/doctor.ts:53-56](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n#### 3. 审计检查\n\n审计命令（audit）执行全面的技能质量检查：\n\n| 检查项 | 说明 |\n|--------|------|\n| skill-frontmatter | 验证所有技能都有 name 和 description |\n| skill-content-length | 验证技能内容长度符合最小要求 |\n\n```typescript\nif (missingFrontmatter > 0) {\n checks.push(fail(\"skill-frontmatter\", `${missingFrontmatter} skill(s) missing name/description`));\n} else {\n checks.push(pass(\"skill-frontmatter\", \"all have name + description\"));\n}\n\nif (tooShort > 0) {\n checks.push(warn(\"skill-content-length\", `${tooShort} skill(s) under ${MIN_CONTENT_LENGTH} chars`));\n} else {\n checks.push(pass(\"skill-content-length\", \"all skills meet minimum length\"));\n}\n```\n\n资料来源：[src/cli/commands/audit.ts:40-50](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n\n### 验证脚本\n\n仓库提供三个核心验证脚本：\n\n| 脚本 | 功能 |\n|------|------|\n| `scripts/validate-skills.py` | 验证技能文件结构和格式 |\n| `scripts/validate-catalog.py` | 验证技能目录完整性 |\n| `scripts/check-requirements.py` | 检查技能依赖要求 |\n\n资料来源：[README.md](./README.md)\n\n## 技能安装与部署\n\n### 安装方式\n\n#### 手动安装\n\n使用 apx CLI 安装技能到指定智能体：\n\n```bash\n# 安装到 Codex\napx install codex\n\n# 安装到 Claude Code\napx install claude-code\n\n# 安装到 Gemini\napx install gemini\n```\n\n默认安装将根目录的 `skills/` 复制到智能体根目录的 `skills/` 子目录。\n\n#### 交互式安装\n\n```bash\napx setup codex --mode recommended --yes\n```\n\n安装模式说明：\n\n| 模式 | 说明 |\n|------|------|\n| minimal | 仅安装引导文件 |\n| recommended | 安装推荐的核心技能集 |\n| full | 安装全部技能和支持资产 |\n\n资料来源：[README.md](./README.md)\n\n### 目录映射\n\n技能安装时的标准目录映射关系：\n\n```mermaid\ngraph LR\n A[仓库根目录] --> B[技能安装目标]\n A1[skills/] --> B1[/skills/]\n A2[plugins/] --> B2[/plugins/]\n A3[agents-md/] --> B3[/agent-powerups/agents-md/]\n A4[hooks/] --> B4[/agent-powerups/hooks/]\n A5[workflows/] --> B5[/agent-powerups/workflows/]\n A6[commands/generic/] --> B6[/agent-powerups/commands/generic/]\n A7[mcp/generic/] --> B7[/agent-powerups/mcp/generic/]\n```\n\n资料来源：[src/cli/commands/setup.ts:60-75](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n\n## 技能使用示例\n\n### systematic-debugging 技能\n\n系统化调试技能提供结构化的问题诊断和解决工作流：\n\n```mermaid\ngraph TD\n A[问题报告] --> B[收集环境信息]\n B --> C[复现问题]\n C --> D{复现成功?}\n D -->|是| E[分析根因]\n D -->|否| F[收集更多上下文]\n F --> C\n E --> G[提出修复方案]\n G --> H[验证修复]\n H --> I[记录经验教训]\n```\n\n### writing-plans 技能\n\n计划撰写技能指导智能体创建结构化、可执行的项目计划：\n\n- 目标定义\n- 任务分解\n- 优先级排序\n- 依赖分析\n- 时间估算\n\n资料来源：[skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)\n\n### using-powerups 技能\n\n系统引导技能帮助用户和智能体了解 Agent Powerups 的使用方法：\n\n- 技能发现和浏览\n- 插件管理\n- 命令执行\n- 配置验证\n\n资料来源：[skills/using-powerups/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/using-powerups/SKILL.md)\n\n## 智能体集成\n\n### 技能发现\n\n智能体可以通过以下方式发现可用技能：\n\n```bash\n# 列出所有可用技能\napx list\n\n# 查看特定技能详情\napx info \n\n# 验证技能有效性\napx check \n```\n\n### 智能体配置文件\n\n技能安装后，智能体配置文件（如 AGENTS.md、CLAUDE.md）会自动更新，包含指向技能的指令：\n\n```markdown\n## Agent Powerups\n\nAgent Powerups assets are installed at `agent-powerups/`.\n\nUse these local assets when relevant:\n- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.\n- Use `apx` commands to discover, inspect, validate, and extend setup.\n- Skills are at `agent-powerups/skills/`. Plugin bundles are at `agent-powerups/plugins/`.\n```\n\n资料来源：[src/cli/commands/setup.ts:35-55](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n\n## 最佳实践\n\n### 技能设计原则\n\n1. **单一职责**：每个技能应专注于一个特定任务领域\n2. **清晰输入输出**：明确定义技能的触发条件和预期结果\n3. **可组合性**：技能应能与其他技能协同工作\n4. **自包含**：技能应包含执行所需的所有信息\n5. **版本控制**：使用语义化版本号管理技能演进\n\n### 技能维护\n\n| 维护任务 | 频率 | 执行方式 |\n|----------|------|----------|\n| 前置matter 验证 | 提交时 | 自动 CI |\n| 内容长度检查 | 每次发布 | audit 命令 |\n| 依赖检查 | 每次安装 | check 命令 |\n| 整体验证 | 每周 | validate-skills.py |\n\n## 相关命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `apx list` | 列出所有可用技能 |\n| `apx info ` | 显示技能详细信息 |\n| `apx check ` | 验证技能安装状态 |\n| `apx doctor` | 运行全面健康检查 |\n| `apx audit skills` | 审计所有技能质量 |\n| `apx install ` | 安装技能到指定智能体 |\n| `python scripts/validate-skills.py` | 验证技能文件结构 |\n\n---\n\n\n\n## 命令系统\n\n### 相关页面\n\n相关主题：[技能系统](#skills), [钩子系统](#hooks), [MCP 配置管理](#mcp-configs)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [commands/generic](https://github.com/yeaight7/agent-powerups/blob/main/commands/generic)\n- [commands/claude-code](https://github.com/yeaight7/agent-powerups/blob/main/commands/claude-code)\n- [commands/codex](https://github.com/yeaight7/agent-powerups/blob/main/commands/codex)\n- [commands/bug-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/bug-check.md)\n- [commands/security-audit.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/security-audit.md)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)\n- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)\n \n\n# 命令系统\n\n## 概述\n\n命令系统（Command System）是 Agent Powerups 的核心组件之一，为编码代理提供可复用的命令提示词和工作流指令。与传统固定命令不同，该系统采用 Markdown 文件格式存储命令模板，支持多目标代理（Codex、Claude Code、Gemini）的差异化适配，并可通过 `apx` CLI 工具进行发现、检查、验证和执行。\n\n命令系统的设计理念是 **\"review-first\"（审查优先）**——在执行任何命令前，代理应先阅读并理解命令意图，而非盲目执行预设脚本。 资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## 架构设计\n\n### 命令系统组件关系\n\n```mermaid\ngraph TD\n A[命令系统] --> B[通用命令 generic]\n A --> C[Agent特定命令]\n C --> C1[Codex命令]\n C --> C2[Claude Code命令]\n C --> C3[Gemini命令]\n \n A --> D[命令检查工具]\n D --> D1[bug-check]\n D --> D2[security-audit]\n D --> D3[ship-check]\n \n A --> E[apx CLI]\n E --> E1[commands print]\n E --> E2[commands run]\n E --> E3[commands validate]\n```\n\n### 命令目录结构\n\n每个命令目录遵循标准化布局：\n\n| 层级 | 路径 | 说明 |\n|------|------|------|\n| 根命令目录 | `commands/` | 所有命令的顶层容器 |\n| 通用命令 | `commands/generic/` | 跨平台通用命令 |\n| Agent专用命令 | `commands/codex/` | Codex 特定命令 |\n| Agent专用命令 | `commands/claude-code/` | Claude Code 特定命令 |\n| 命令定义文件 | `commands/*.md` | 具体命令实现（Markdown格式） |\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## 命令类型分类\n\n### 按功能分类\n\n| 命令类别 | 功能描述 | 典型用例 |\n|----------|----------|----------|\n| **检查类命令** | 代码质量与安全检查 | `bug-check.md`、`security-audit.md` |\n| **发布前检查** | Ship前验证 | `ship-check` |\n| **工作流命令** | 复杂任务编排 | `tri-review`、`parallel-work` |\n| **引导命令** | 工具使用指导 | `using-powerups-command` |\n\n### 按目标代理分类\n\n| 目标代理 | 命令目录 | 适配说明 |\n|----------|----------|----------|\n| **通用** | `commands/generic/` | 所有代理均可使用 |\n| **Codex** | `commands/codex/` | OpenAI Codex 专用 |\n| **Claude Code** | `commands/claude-code/` | Anthropic Claude Code 专用 |\n| **Gemini** | `commands/gemini/` | Google Gemini 专用 |\n\n资料来源：[README.md - Catalog Overview](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## 内置命令详解\n\n### 1. Bug Check 命令\n\n`bug-check.md` 专注于系统性缺陷发现，为代理提供结构化的调试工作流。\n\n**核心功能：**\n- 系统性错误定位\n- 根因分析引导\n- 修复方案生成\n\n**使用方式：**\n```powershell\napx commands print bug-check --target \napx commands run bug-check\n```\n\n资料来源：[commands/bug-check.md](https://github.com/yeaight7/agent-powerups/blob/main/commands/bug-check.md)\n\n### 2. Security Audit 命令\n\n`security-audit.md` 提供代码安全审计功能，包含自动化检测规则。\n\n**检测规则示例：**\n\n| 规则名称 | 严重级别 | 检测模式 |\n|----------|----------|----------|\n| `unpinned-latest-image` | P2 | CI配置中的 `:latest` 镜像标签 |\n| `broad-filesystem-write` | P1 | 递归删除或通配符写入 |\n| `missing-dry-run` | P1 | 未加 `--dry-run` 的安装命令 |\n\n资料来源：[src/cli/commands/security-audit.ts:20-40](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n\n**扫描配置：**\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| 扫描目录 | 排除 `node_modules`、`dist`、`.git`、`.worktrees`、`.plugins` | 敏感目录黑名单 |\n| 扫描扩展 | `.json`、`.toml`、`.md`、`.sh`、`.ps1`、`.yaml`、`.yml` | 目标文件类型 |\n| 单文件大小限制 | 512 KB | 防止大文件阻塞 |\n\n资料来源：[src/cli/commands/security-audit.ts:41-43](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n\n### 3. Ship Check 命令\n\n`ship-check` 是发布前验证命令包，确保代码符合发布标准。\n\n**命令执行：**\n```powershell\napx commands run ship-check\n```\n\n资料来源：[README.md - Quickstart](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n### 4. 工作流命令组\n\n系统提供一系列工作流编排命令：\n\n| 命令 | 功能 | 使用场景 |\n|------|------|----------|\n| `tri-review` | 三方评审 | 关键代码审查 |\n| `clarify-requirements` | 需求澄清 | 需求模糊时 |\n| `parallel-work` | 并行工作 | 多任务处理 |\n| `finish-loop` | 完成循环 | 收尾验证 |\n\n资料来源：[src/cli/apx.ts:45-60](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n## apx CLI 命令接口\n\n### 命令管理子命令\n\n```mermaid\ngraph LR\n A[apx commands] --> B[print]\n A --> C[run]\n A --> D[validate]\n \n B --> B1[显示命令内容]\n C --> C1[执行命令]\n D --> D1[验证命令结构]\n```\n\n### 使用示例\n\n```powershell\n# 列出所有可用命令\napx commands list\n\n# 打印命令内容到指定目标代理\napx commands print ship-check --target claude-code\n\n# 执行本地命令检查\napx commands run ship-check\n\n# 验证所有命令文件结构\napx commands validate --all\n```\n\n资料来源：[README.md - Quickstart](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## 生命周期命令\n\n### Phase 命令组\n\nPhase 命令提供结构化的任务生命周期管理：\n\n```mermaid\ngraph TD\n A[phase 命令] --> B[discuss]\n A --> C[plan]\n A --> D[execute]\n A --> E[verify]\n \n B --> B1[需求讨论]\n C --> C1[任务规划]\n D --> D1[执行实施]\n E --> E1[结果验证]\n```\n\n**使用方式：**\n```powershell\napx phase discuss \napx phase plan \napx phase execute \napx phase verify \n```\n\n资料来源：[src/cli/apx.ts:69-74](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n### Project 命令组\n\n项目初始化命令：\n\n```powershell\napx project init\n```\n\n资料来源：[src/cli/apx.ts:65-68](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n### Codebase 命令组\n\n代码库分析命令：\n\n```powershell\napx codebase map\n```\n\n资料来源：[src/cli/apx.ts:77-80](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n## 检查与验证\n\n### 命令检查功能\n\n`check.ts` 实现对命令资产的完整性验证：\n\n**验证内容：**\n- 命令文件存在性\n- 必需的前置条件（requires）满足情况\n- 缺失依赖的自动安装选项\n\n```typescript\napx check [--install-missing] [--yes]\n```\n\n**输出格式：**\n```\n:status=[| install: ]\n```\n\n资料来源：[src/cli/commands/check.ts:10-30](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n\n### 安全审计流程\n\n```mermaid\nflowchart LR\n A[启动安全审计] --> B[收集目标文件]\n B --> C{文件过滤}\n C -->|跳过大文件| D[跳过]\n C -->|扩展名匹配| E[模式匹配]\n E --> F[规则检测]\n F --> G{发现问题?}\n G -->|是| H[记录警告]\n G -->|否| I[继续扫描]\n H --> I\n I --> J{更多文件?}\n J -->|是| C\n J -->|否| K[输出报告]\n```\n\n## 与代理的集成\n\n### 指令文件处理\n\n命令系统支持向代理的指令文件（如 `AGENTS.md`、`CLAUDE.md`）注入命令块：\n\n**行为说明：**\n\n| 场景 | 处理方式 |\n|------|----------|\n| 指令文件已存在 | 在 `` 和 `` 标记之间追加内容 |\n| 指令文件不存在 | 创建 `agent-powerups/instructions/agent-powerups.md` 并报告手动步骤 |\n| 已存在注入块 | 替换现有块内容 |\n\n资料来源：[src/cli/commands/setup.ts:1-20](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n\n### 各代理的集成方式\n\n**Codex 集成：**\n```powershell\napx commands print ship-check --target codex\napx setup codex --mode recommended --yes\n```\n\n**Claude Code 集成：**\n```powershell\napx commands print ship-check --target claude-code\napx setup claude-code --mode recommended --yes\n```\n\n资料来源：[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)\n\n## 命令模板格式\n\n命令文件采用 Markdown 格式，包含以下标准结构：\n\n```markdown\n---\nname: \ndescription: \nrequires:\n - \n---\n\n# Command Content\n\n[Agent instruction content in Markdown]\n```\n\n**字段说明：**\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| `name` | 是 | 命令唯一标识符 |\n| `description` | 是 | 命令功能简述 |\n| `requires` | 否 | 前置依赖列表 |\n\n## 安全注意事项\n\n命令系统包含潜在风险的操作类型：\n\n| 风险类型 | 级别 | 说明 |\n|----------|------|------|\n| 文件系统写入 | P1 | 递归删除、通配符写入 |\n| 包安装 | P1 | 未加 `--dry-run` 的安装 |\n| 镜像标签 | P2 | 使用 `:latest` 标签 |\n\n> **警告**：在将命令加载到可信代理环境前，请务必审查命令内容。命令可能指示代理读取本地文件或执行命令。\n\n资料来源：[README.md - Safety Warning](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## 最佳实践\n\n### 命令使用准则\n\n1. **审查优先**：执行命令前先使用 `print` 子命令查看内容\n2. **dry-run 验证**：使用 `--dry-run` 选项预演效果\n3. **渐进式采用**：从 minimal 模式开始，逐步扩展\n4. **定期验证**：使用 `apx commands validate --all` 确保命令完整性\n\n### 开发新命令\n\n1. 在 `commands/` 下创建 Markdown 文件\n2. 遵循标准模板格式\n3. 添加必需的前置条件（requires）\n4. 使用 `apx commands validate` 验证结构\n5. 在 `plugin-bundles.json` 中注册\n\n## 相关资源\n\n- [安装指南](./docs/installation.md)\n- [安全模型](./docs/security-model.md)\n- [插件系统](./plugins/)\n- [Catalog Schema](./docs/catalog-schema.md)\n\n---\n\n\n\n## 钩子系统\n\n### 相关页面\n\n相关主题：[技能系统](#skills), [命令系统](#commands)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [hooks/README.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/README.md)\n- [hooks/no-secrets-preflight/HOOK.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/no-secrets-preflight/HOOK.md)\n- [hooks/handoff-summary/HOOK.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/handoff-summary/HOOK.md)\n- [hooks/validation-required/HOOK.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/validation-required/HOOK.md)\n- [docs/security-model.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/security-model.md)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [catalog.json](https://github.com/yeaight7/agent-powerups/blob/main/catalog.json)\n \n\n# 钩子系统\n\n## 概述\n\n钩子系统（Hook System）是 Agent Powerups 框架中用于在特定执行节点触发自定义逻辑的扩展机制。该系统允许开发者和用户在 agent 工作流的关键时刻注入检查、转换、通知或验证行为，从而实现对 agent 行为的精细化控制。\n\n钩子是可组合的、声明式的配置单元，支持 `pre-hook`（前置钩子）和 `post-hook`（后置钩子）两种模式。系统强调本地优先（local-first）的执行策略，所有钩子内容默认存储在仓库的 `hooks/` 目录下，并通过 `apx` CLI 工具进行管理和执行。资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n## 架构设计\n\n### 核心组件\n\n钩子系统由以下核心组件构成：\n\n| 组件类型 | 说明 | 存储位置 |\n|---------|------|---------|\n| 钩子定义 | 包含执行逻辑的 Markdown 文件 | `hooks//HOOK.md` |\n| 钩子清单 | 记录所有可用钩子的元数据 | `catalog.json` |\n| 执行引擎 | 解析和运行钩子的 CLI 模块 | `src/cli/` |\n| 安全边界 | 限制钩子可执行操作的沙箱机制 | `docs/security-model.md` |\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[用户触发钩子执行] --> B{apx hooks run}\n B --> C[加载 catalog.json]\n C --> D[定位目标钩子目录]\n D --> E[解析 HOOK.md 元数据]\n E --> F[检查前置条件 requires]\n F --> G{条件满足?}\n G -->|否| H[跳过或警告]\n G -->|是| I[执行钩子逻辑]\n I --> J[记录执行结果]\n J --> K[返回状态和输出]\n```\n\n钩子执行遵循以下顺序：\n\n1. **发现阶段**：通过 `apx hooks list` 枚举所有可用钩子\n2. **验证阶段**：检查钩子定义文件的完整性和依赖\n3. **执行阶段**：根据钩子类型运行相应逻辑\n4. **报告阶段**：输出执行结果和潜在问题\n\n资料来源：[hooks/README.md](https://github.com/yeaight7/agent-powerups/blob/main/hooks/README.md)\n\n## 钩子类型分类\n\n### 按功能分类\n\nAgent Powerups 当前支持三种主要钩子分类：\n\n| 分类 | 用途 | 示例钩子 |\n|------|------|---------|\n| `productivity` | 提升工作效率的辅助钩子 | handoff-summary |\n| `quality` | 代码质量和审查相关 | validation-required |\n| `safety` | 安全检查和风险防控 | no-secrets-preflight |\n\n### 内置钩子\n\n#### 1. no-secrets-preflight（安全类）\n\n**用途**：在 agent 处理敏感信息前执行预检查，防止密钥、凭证或私密数据意外泄露。\n\n**触发场景**：\n\n- 用户请求处理文件时\n- Agent 准备写入外部服务时\n- 涉及环境变量或配置文件的操作前\n\n**安全模型约束**：该钩子严格遵循最小权限原则，任何涉及密钥的操作都需要显式确认。资料来源：[docs/security-model.md:1-50](https://github.com/yeaight7/agent-powerups/blob/main/docs/security-model.md)\n\n#### 2. handoff-summary（效率类）\n\n**用途**：在 agent 之间进行上下文交接时生成摘要信息，确保信息传递的完整性和连续性。\n\n**输出内容**：\n\n- 当前任务进度概述\n- 已完成的检查点列表\n- 待处理的依赖项\n- 关键上下文引用\n\n#### 3. validation-required（质量类）\n\n**用途**：在关键操作执行前强制进行验证检查，确保符合预定义的质量标准。\n\n**验证维度**：\n\n- 代码格式规范\n- 文档完整性\n- 测试覆盖率\n- 类型安全\n\n## 钩子定义格式\n\n每个钩子目录包含一个 `HOOK.md` 文件，遵循标准的前置元数据格式：\n\n```markdown\n---\nname: \ntype: \ntrigger: \nrequires:\n - \n - \ndescription: \nversion: 1.0.0\n---\n\n# Hook Execution Logic\n\n[具体执行指令...]\n```\n\n### 必填字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | string | 钩子唯一标识符 |\n| `type` | enum | 钩子所属分类 |\n| `trigger` | enum | 触发时机（pre/post） |\n| `description` | string | 功能描述 |\n\n### 可选字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `requires` | array | 运行时依赖列表 |\n| `version` | string | 钩子版本号 |\n| `timeout` | number | 最大执行时长（秒） |\n\n资料来源：[catalog.json](https://github.com/yeaight7/agent-powerups/blob/main/catalog.json)\n\n## CLI 命令接口\n\n### 列出所有钩子\n\n```sh\napx hooks list\n```\n\n该命令扫描 `hooks/` 目录并返回所有已注册的钩子及其状态。\n\n### 查看钩子详情\n\n```sh\napx hooks info \n```\n\n输出指定钩子的完整元数据和执行说明。\n\n### 运行单个钩子\n\n```sh\napx hooks run \n```\n\n在当前工作目录执行指定钩子的逻辑。\n\n### 运行所有适用钩子\n\n```sh\napx hooks run --all\n```\n\n遍历并执行所有符合条件的钩子。\n\n### 验证钩子完整性\n\n```sh\napx hooks validate \n```\n\n检查钩子定义文件的结构正确性和依赖可用性。\n\n## 与安装系统的集成\n\n### Setup 流程中的钩子处理\n\n在 `apx setup` 执行过程中，钩子目录会被复制到目标 agent 的安装根目录：\n\n```typescript\n// 资料来源：src/cli/commands/setup.ts\nconst directories = [\n { source: path.join(service.repoRoot, \"hooks\"), dest: path.join(installRoot, \"hooks\") },\n // ... 其他目录\n];\n```\n\n### 目录结构\n\n安装后的钩子布局如下：\n\n```\n/\n└── agent-powerups/\n └── hooks/\n ├── no-secrets-preflight/\n │ └── HOOK.md\n ├── handoff-summary/\n │ └── HOOK.md\n └── validation-required/\n └── HOOK.md\n```\n\n## 安全模型\n\n钩子系统内置多层安全保护机制：\n\n### 信任边界\n\n根据 `docs/security-model.md` 的定义，钩子的信任边界遵循以下原则：\n\n| 边界类型 | 限制内容 |\n|---------|---------|\n| 文件访问 | 仅允许读取项目目录内的文件 |\n| 命令执行 | 需要显式用户批准 |\n| 网络请求 | 禁止未经授权的外部调用 |\n| 密钥暴露 | 严禁在钩子逻辑中输出敏感信息 |\n\n### 沙箱执行\n\n钩子在受限环境中执行，具有以下限制：\n\n- 无法访问 `node_modules` 外部的模块\n- 禁止修改系统配置\n- 禁止创建持久化后台进程\n- 网络请求被白名单机制控制\n\n资料来源：[docs/security-model.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/security-model.md)\n\n## 开发指南\n\n### 创建新钩子\n\n1. 在 `hooks/` 下创建新目录\n2. 编写 `HOOK.md` 文件，包含完整的前置元数据\n3. 实现具体的执行逻辑（Markdown 格式的指令）\n4. 在 `catalog.json` 中注册钩子\n5. 运行验证命令确保结构正确\n\n### 钩子开发规范\n\n| 规范项 | 要求 |\n|-------|------|\n| 命名 | 使用 kebab-case，如 `my-custom-hook` |\n| 描述 | 必需提供清晰的 description |\n| 测试 | 必须包含 `apx hooks validate` 通过 |\n| 文档 | 需在 HOOK.md 中说明触发条件 |\n\n## 最佳实践\n\n### 1. 单一职责原则\n\n每个钩子应专注于单一功能，避免将多个检查逻辑合并到同一个钩子中。这有助于提高可维护性和可测试性。\n\n### 2. 失败处理\n\n钩子执行失败时应：\n\n- 返回有意义的错误消息\n- 提供修复建议\n- 避免阻塞主流程（除非是关键安全检查）\n\n### 3. 性能考虑\n\n- 避免在钩子中执行耗时操作\n- 使用缓存机制减少重复计算\n- 设置合理的超时时间\n\n## 常见问题\n\n**Q：钩子执行失败如何调试？**\n\n使用 `--verbose` 标志运行命令获取详细日志输出：\n\n```sh\napx hooks run --verbose\n```\n\n**Q：如何禁用特定钩子？**\n\n在 `profiles.json` 中编辑对应 profile 的 `disabled-hooks` 列表。\n\n**Q：钩子支持条件执行吗？**\n\n支持。在 `HOOK.md` 的前置元数据中使用 `requires` 字段声明前置条件。\n\n## 相关资源\n\n- [安全模型文档](./docs/security-model.md)\n- [CLI 命令参考](./src/cli/apx.ts)\n- [Catalog Schema](./docs/catalog-schema.md)\n- [贡献指南](./CONTRIBUTING.md)\n\n---\n\n\n\n## MCP 配置管理\n\n### 相关页面\n\n相关主题：[资产目录系统](#catalog-system), [apx CLI 参考](#cli-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp/generic/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/generic/github-local.json)\n- [mcp/claude-code/github-local.json](https://github.com/yeaight7/agent-powerups/blob/main/mcp/claude-code/github-local.json)\n- [mcp/codex/github-local.toml](https://github.com/yeaight7/agent-powerups/blob/main/mcp/codex/github-local.toml)\n- [docs/mcp-configs.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/mcp-configs.md)\n- [src/cli/commands/mcp.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/mcp.ts)\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n \n\n# MCP 配置管理\n\n## 概述\n\nMCP（Model Context Protocol）配置管理是 Agent Powerups 项目的核心功能之一，提供本地优先的 GitHub MCP 配置管理能力。该系统支持配置的检查、冒烟测试和显式安装，确保编码代理能够安全地访问 MCP 服务器工具。\n\nAgent Powerups 的 MCP 配置管理遵循**本地优先、安全优先**的设计原则，所有配置操作都需要用户显式授权，不会自动修改环境。\n\n资料来源：[README.md:36]()\n\n## 核心概念\n\n### 什么是 MCP 配置\n\nMCP 配置定义了编码代理（如 Claude Code、Codex）可用的 MCP 服务器连接信息。这些配置文件包含：\n\n- MCP 服务器端点地址\n- 认证令牌占位符\n- 必需的环境变量\n- 警告信息和使用提示\n\n### 支持的代理类型\n\n| 代理类型 | 配置文件格式 | 目标目录 |\n|---------|-------------|---------|\n| Claude Code | `.json` | `mcp/claude-code/` |\n| Codex | `.toml` | `mcp/codex/` |\n| 通用/通用模板 | `.json` | `mcp/generic/` |\n\n资料来源：[docs/mcp-configs.md]()\n\n## 架构设计\n\n### 配置查找机制\n\nMCP 配置采用分层查找策略，根据安装目标确定配置文件路径：\n\n```mermaid\ngraph TD\n A[请求 MCP 配置] --> B{安装目标类型}\n B -->|codex| C[mcp/codex/]\n B -->|claude-code| D[mcp/claude-code/]\n B -->|generic| E[mcp/generic/]\n C --> F[查找目标特定配置]\n D --> F\n E --> F\n F --> G{是否有 targets 映射}\n G -->|是| H[使用 targets 中的路径]\n G -->|否| I[使用默认 path 字段]\n```\n\n资料来源：[src/cli/commands/mcp.ts:67-72]()\n\n### 配置文件结构\n\n每种代理类型的配置文件遵循各自的格式规范：\n\n**Claude Code 格式（JSON）：**\n```json\n{\n \"mcpServers\": {\n \"github-local\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\"\n }\n }\n }\n}\n```\n\n**Codex 格式（TOML）：**\n```toml\n[[mcp_servers]]\nname = \"github-local\"\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-github\"]\n[env]\nGITHUB_TOKEN = \"${GITHUB_TOKEN}\"\n```\n\n资料来源：[mcp/claude-code/github-local.json]()、[mcp/codex/github-local.toml]()\n\n## MCP 命令系统\n\n### 可用命令列表\n\n| 命令 | 功能 | 目标参数 |\n|-----|------|---------|\n| `apx mcp install` | 安装 MCP 配置 | `codex`、`claude-code`、`generic` |\n| `apx mcp check` | 检查配置语法和完整性 | `codex`、`claude-code`、`generic` |\n| `apx mcp smoke` | 冒烟测试 MCP 连接 | `codex`、`claude-code`、`generic` |\n\n### check 命令\n\n`check` 命令验证 MCP 配置的正确性，包括：\n\n- 配置文件存在性检查\n- 配置文件类型验证（必须是 `mcp-config` 类型）\n- 环境变量检查（识别未设置必需的环境变量）\n- GitHub Token 验证\n\n```typescript\nexport async function runMcpCheckCommand(\n service: CatalogService,\n assetName: string,\n target: InstallTarget,\n env: NodeJS.ProcessEnv = process.env,\n): Promise>\n```\n\n**返回数据结构：**\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `exitCode` | `number` | 0 表示成功，1 表示失败 |\n| `output` | `string` | 检查结果输出 |\n| `data` | `McpCheckData` | 详细检查数据 |\n\n资料来源：[src/cli/commands/mcp.ts:74-91]()\n\n### install 命令\n\n`install` 命令将 MCP 配置复制到代理配置目录。该命令支持干运行模式，允许用户预览安装效果。\n\n```powershell\n# 预览安装（不实际写入）\napx mcp install github-local --target codex --dry-run\n\n# 执行安装\napx mcp install github-local --target codex\n```\n\n**安装流程：**\n\n```mermaid\ngraph LR\n A[apx mcp install] --> B{是否 --dry-run}\n B -->|是| C[仅显示预览信息]\n B -->|否| D{是否有警告}\n D -->|是| E[显示警告信息]\n D -->|否| F[执行安装]\n E --> F\n F --> G[复制配置文件]\n G --> H[替换环境变量占位符]\n```\n\n资料来源：[README.md:95]()\n\n### 冒烟测试命令\n\n`smoke` 命令执行 MCP 服务器的连接测试，验证配置是否能正常工作。\n\n## 环境变量管理\n\n### 必需环境变量\n\nMCP 配置中声明的必需环境变量通过 `required_env` 字段定义：\n\n```json\n{\n \"mcp\": {\n \"required_env\": [\"GITHUB_TOKEN\"]\n }\n}\n```\n\n### 环境变量检查逻辑\n\n`check` 命令会扫描所有配置，收集并验证环境变量设置状态：\n\n```typescript\nconst requiredEnv = (asset.mcp?.required_env ?? []).map((name) => ({\n name,\n set: Boolean(env[name])\n}));\n```\n\n**检查结果示例：**\n\n| 环境变量 | 状态 | 说明 |\n|---------|------|-----|\n| `GITHUB_TOKEN` | 未设置 | 需要在本地配置真实令牌 |\n| `GITHUB_PERSONAL_REPO` | 已设置 | 配置有效 |\n\n资料来源：[src/cli/commands/mcp.ts:89-90]()\n\n### 安全警告\n\n安装过程中，系统会自动添加安全警告提示：\n\n> **警告**：请将占位符（如 `${GITHUB_TOKEN}` 或 `YOUR_TOKEN_HERE`）替换为本地真实令牌，**不要提交真实令牌**到版本控制系统。\n\n资料来源：[src/cli/commands/mcp.ts:58-60]()\n\n## 资产管理\n\n### 资产元数据结构\n\nMCP 配置作为资产类型 `mcp-config` 在 `catalog.json` 中注册：\n\n```json\n{\n \"name\": \"github-local\",\n \"type\": \"mcp-config\",\n \"path\": \"mcp/generic/github-local.json\",\n \"targets\": {\n \"claude-code\": \"mcp/claude-code/github-local.json\",\n \"codex\": \"mcp/codex/github-local.toml\"\n },\n \"mcp\": {\n \"warning\": \"MCP 服务器启用需要显式用户批准\",\n \"required_env\": [\"GITHUB_TOKEN\"]\n }\n}\n```\n\n**资产字段说明：**\n\n| 字段 | 必需 | 说明 |\n|-----|------|-----|\n| `name` | 是 | 资产唯一标识 |\n| `type` | 是 | 必须为 `mcp-config` |\n| `path` | 是 | 默认配置文件路径 |\n| `targets` | 否 | 按代理类型的目标路径映射 |\n| `mcp.warning` | 否 | 安装警告信息 |\n| `mcp.required_env` | 否 | 必需的环境变量列表 |\n\n资料来源：[docs/mcp-configs.md]()\n\n### 目标路径解析\n\n当存在 `targets` 映射时，系统优先使用对应目标的值：\n\n```typescript\nfunction mcpTargetPath(\n service: CatalogService,\n assetName: string,\n target: InstallTarget\n): string {\n const asset = service.getAsset(assetName);\n if (asset.type !== \"mcp-config\") {\n throw new Error(`${assetName} is not an mcp-config asset`);\n }\n return asset.targets?.[target] ?? asset.path;\n}\n```\n\n## 工作流程示例\n\n### 完整配置流程\n\n```mermaid\ngraph TD\n A[开始] --> B[apx mcp check github-local]\n B --> C{配置有效?}\n C -->|否| D[修复配置问题]\n C -->|是| E[apx mcp smoke github-local]\n E --> F{连接成功?}\n F -->|否| G[检查 MCP 服务器]\n F -->|是| H[apx mcp install github-local --target claude-code --dry-run]\n H --> I{预览正确?}\n I -->|否| J[调整配置]\n I -->|是| K[apx mcp install github-local --target claude-code]\n K --> L[配置完成]\n D --> B\n J --> H\n```\n\n### 典型使用场景\n\n**场景 1：Claude Code 用户配置 GitHub MCP**\n\n```powershell\n# 1. 检查配置\napx mcp check github-local --target claude-code\n\n# 2. 冒烟测试\napx mcp smoke github-local --target claude-code\n\n# 3. 预览安装\napx mcp install github-local --target claude-code --dry-run\n\n# 4. 执行安装\napx mcp install github-local --target claude-code\n```\n\n**场景 2：Codex 用户配置 GitHub MCP**\n\n```powershell\n# 使用专用提示\napx mcp install github-local --target codex --dry-run\n```\n\n资料来源：[README.md:96-100]()\n\n## 安全模型\n\n### 安全边界\n\nAgent Powerups 的 MCP 配置管理维护以下安全边界：\n\n1. **本地优先**：所有配置文件优先从本地目录加载\n2. **显式安装**：不自动修改任何配置文件\n3. **占位符验证**：强制检查环境变量占位符\n4. **预览优先**：所有写入操作支持 `--dry-run` 模式\n\n### 风险缓解措施\n\n| 风险 | 缓解措施 |\n|-----|---------|\n| 意外提交令牌 | 强制警告和占位符检测 |\n| 未授权安装 | 要求显式 `--yes` 确认 |\n| 错误的 MCP 配置 | check 和 smoke 命令验证 |\n| 配置冲突 | 使用独立子目录避免覆盖 |\n\n资料来源：[docs/security-model.md]()\n\n## 命令参考\n\n### 全局标志\n\n| 标志 | 说明 |\n|-----|------|\n| `--dry-run` | 预览操作，不实际写入 |\n| `--verbose` | 输出详细执行信息 |\n| `--target ` | 指定目标代理类型 |\n\n### 环境变量\n\n| 变量 | 说明 |\n|-----|------|\n| `GITHUB_TOKEN` | GitHub 个人访问令牌（必需） |\n| `APX_DOCTOR_NESTED` | 嵌套诊断模式标志 |\n\n## 故障排除\n\n### 常见问题\n\n**Q: MCP 配置检查失败，提示类型错误？**\n\nA: 确保资产在 `catalog.json` 中的 `type` 字段值为 `mcp-config`。\n\n**Q: 环境变量已设置但仍显示未设置？**\n\nA: 检查变量名是否完全匹配（包括大小写），并确保在运行 `apx` 命令的 shell 会话中变量已导出。\n\n**Q: 目标路径未找到？**\n\nA: 确认 `targets` 映射中存在对应的目标类型，或 `path` 字段指向的默认路径有效。\n\n## 相关资源\n\n- [MCP 配置文档](./docs/mcp-configs.md)\n- [安全模型](./docs/security-model.md)\n- [设置指南](./docs/setup/claude-code.md)\n- [catalog.json 规范](./docs/catalog-schema.md)\n\n---\n\n\n\n## 用户意图配置\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [资产目录系统](#catalog-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [profiles.json](https://github.com/yeaight7/agent-powerups/blob/main/profiles.json)\n- [docs/profiles-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/profiles-schema.md)\n- [src/cli/commands/profiles.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/profiles.ts)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [package.json](https://github.com/yeaight7/agent-powerups/blob/main/package.json)\n \n\n# 用户意图配置\n\n## 概述\n\n用户意图配置（Profiles）是 Agent Powerups 框架中用于管理不同编码代理（coding agent）环境设置的配置系统。它允许用户为 Codex、Claude Code 和 Gemini 等主流编码代理定义和管理特定的技能集、插件包和安装参数。\n\nProfiles 的核心作用是为每种代理提供一套经过策划（curated）的技能和插件组合，使用户能够根据不同的工作场景快速切换代理配置。资料来源：[src/cli/apx.ts:28-32]()\n\n## 核心概念\n\n### 什么是用户意图配置\n\n用户意图配置是一种声明式的配置格式，它定义了：\n\n- 代理的类型和识别信息\n- 默认的根目录和环境变量\n- 指令文件的命名规则\n- 目标目录的映射关系\n- 推荐的技能列表\n- 推荐的命令包\n- 推荐的插件捆绑包\n\n资料来源：[src/cli/commands/setup.ts:37-58]()\n\n### 配置与 Setup 的关系\n\nSetup 流程使用 Profile 配置来执行智能安装。Profile 提供了三种安装模式：\n\n| 模式 | 说明 | 用途 |\n|------|------|------|\n| minimal | 最小引导集 | 仅安装核心技能用于初步验证 |\n| recommended | 推荐配置 | 安装主流场景所需的技能和插件 |\n| full | 完整配置 | 包含所有可选组件的广泛部署 |\n\n资料来源：[src/cli/commands/setup.ts:21-35]()\n\n## 架构设计\n\n### 数据模型\n\n```mermaid\ngraph TD\n A[用户意图配置 Profile] --> B[SetupAgent 代理类型]\n A --> C[AgentProfile 配置属性]\n B --> D[codex]\n B --> E[claude-code]\n B --> F[gemini]\n C --> G[agent 标识符]\n C --> H[displayName 显示名称]\n C --> I[defaultRootEnv 默认环境变量]\n C --> J[defaultRootDir 默认根目录]\n C --> K[instructionFileName 指令文件名]\n C --> L[commandTargetDir 命令目标目录]\n C --> M[mcpTargetDir MCP目标目录]\n```\n\n### 配置属性详解\n\n#### SetupAgent 类型定义\n\n```typescript\ntype SetupAgent = \"codex\" | \"claude\" | \"claude-code\" | \"gemini\";\n```\n\n支持的编码代理类型：\n\n| 代理标识符 | 显示名称 | 说明 |\n|-----------|---------|------|\n| codex | Codex | OpenAI Codex |\n| claude | Claude | Anthropic Claude（基础版）|\n| claude-code | Claude Code | Anthropic Claude Code |\n| gemini | Gemini | Google Gemini CLI |\n\n资料来源：[src/cli/commands/setup.ts:5-25]()\n\n#### AgentProfile 完整配置\n\n| 属性 | 类型 | 说明 | 示例 |\n|------|------|------|------|\n| agent | string | 代理唯一标识符 | \"codex\" |\n| displayName | string | 用户友好的显示名称 | \"Codex\" |\n| defaultRootEnv | string[] | 查找根目录的环境变量列表 | [\"CODEX_HOME\"] |\n| defaultRootDir | string | 默认安装根目录 | \"~/.codex\" |\n| instructionFileName | string | 代理指令文件名 | \"AGENTS.md\" |\n| commandTargetDir | string | 命令目录目标 | \"codex\" |\n| mcpTargetDir | string | MCP 配置目标目录 | \"codex\" |\n\n资料来源：[src/cli/commands/setup.ts:37-58]()\n\n## 配置数据结构\n\n### profiles.json 文件结构\n\n```json\n{\n \"profiles\": {\n \"\": {\n \"agent\": \"codex|claude|claude-code|gemini\",\n \"displayName\": \"Human Readable Name\",\n \"description\": \"Profile description\",\n \"skills\": [\"skill-name-1\", \"skill-name-2\"],\n \"commands\": [\"command-name-1\", \"command-name-2\"],\n \"pluginBundles\": [\"bundle-name-1\", \"bundle-name-2\"],\n \"mcpServers\": [\"mcp-server-name-1\"]\n }\n }\n}\n```\n\n资料来源：[docs/profiles-schema.md]()\n\n### 内置 Profile 配置\n\n#### 最小技能集 (MINIMAL_SKILLS)\n\n```typescript\nconst MINIMAL_SKILLS = [\n \"using-powerups\", // 学会使用 powerups\n \"no-fluff\", // 简洁输出\n \"repo-map\", // 仓库地图\n \"writing-plans\", // 编写计划\n \"verification-before-completion\", // 完成前验证\n \"search-before-building\", // 构建前搜索\n] as const;\n```\n\n#### 推荐插件捆绑包 (RECOMMENDED_PLUGIN_BUNDLES)\n\n```typescript\nconst RECOMMENDED_PLUGIN_BUNDLES = [\n \"dev-vitals\", // 开发活力指标\n \"debugging-diagnostics\", // 调试诊断\n \"quality-gates\" // 质量门禁\n] as const;\n```\n\n资料来源：[src/cli/commands/setup.ts:60-68]()\n\n## 命令行接口\n\n### apx profiles 命令\n\n```bash\napx profiles list # 列出所有可用配置\napx profiles show # 显示指定配置详情\napx profiles validate # 验证配置语法\n```\n\n资料来源：[src/cli/apx.ts:28-32]()\n\n### profiles.ts 命令实现\n\n| 命令 | 功能 | 参数 |\n|------|------|------|\n| list | 列出所有配置 | 无 |\n| show | 显示配置详情 | name: 配置名称 |\n| validate | 验证配置有效性 | 无 |\n\n```mermaid\ngraph LR\n A[apx profiles] --> B{子命令}\n B --> C[list 列出]\n B --> D[show 显示]\n B --> E[validate 验证]\n C --> F[读取 profiles.json]\n D --> G[解析指定配置]\n E --> H[Schema 校验]\n```\n\n资料来源：[src/cli/commands/profiles.ts]()\n\n## 使用场景\n\n### 场景一：快速初始化新代理\n\n```bash\n# 列出可用配置\napx profiles list\n\n# 使用推荐配置初始化 Claude Code\napx setup claude-code --mode recommended --yes\n```\n\n### 场景二：切换工作环境\n\n```bash\n# 为数据科学项目切换到 ML 配置\napx profiles set ml-project\n\n# 为开源维护切换配置\napx profiles set open-source-maintainer\n```\n\n### 场景三：自定义配置创建\n\n1. 读取现有配置模板\n2. 修改技能和插件列表\n3. 验证配置语法\n4. 应用新配置\n\n## 安全模型\n\n用户意图配置遵循 Agent Powerups 的安全边界：\n\n- 配置仅定义技能和插件的引用，不包含敏感信息\n- 实际的工具安装需要用户显式批准\n- MCP 服务器启用需要独立确认\n- 外部工具安装受 dry-run 模式保护\n\n资料来源：[docs/security-model.md]()\n\n## 配置验证\n\n### Schema 校验规则\n\n配置文件必须满足以下规则：\n\n| 规则 | 说明 | 验证方式 |\n|------|------|---------|\n| agent 有效性 | agent 必须是支持的代理类型 | 枚举校验 |\n| 技能存在性 | 引用的技能必须存在于 catalog 中 | 引用校验 |\n| 插件存在性 | 引用的插件必须存在于 plugin-bundles.json | 引用校验 |\n| JSON 语法 | 必须是有效的 JSON 格式 | 语法校验 |\n\n资料来源：[src/cli/commands/profiles.ts]()\n\n### 验证命令\n\n```bash\n# 验证配置文件\napx profiles validate\n\n# 验证并显示详细错误\napx profiles validate --verbose\n```\n\n## 扩展机制\n\n### 自定义 Profile\n\n用户可以通过在项目根目录创建 `profiles.local.json` 来扩展内置配置：\n\n```json\n{\n \"extends\": \"recommended\",\n \"skills\": [\"additional-skill-1\"],\n \"pluginBundles\": [\"custom-bundle\"]\n}\n```\n\n### Profile 继承\n\nProfile 支持基础配置继承，允许用户基于现有配置创建变体：\n\n```mermaid\ngraph TD\n A[base-profile] --> B[recommended]\n A --> C[minimal]\n B --> D[codex-recommended]\n B --> E[claude-recommended]\n C --> F[codex-minimal]\n C --> G[claude-minimal]\n```\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 原因 | 解决方案 |\n|------|------|---------|\n| 配置找不到 | profiles.json 格式错误 | 运行 `apx profiles validate` |\n| 技能未安装 | 技能名拼写错误 | 检查 catalog.json 中的技能名 |\n| 安装失败 | 权限不足 | 检查目标目录写入权限 |\n\n### 诊断命令\n\n```bash\n# 医生检查\napx doctor\n\n# 列出已安装配置\napx profiles list --installed\n\n# 显示配置详细信息\napx profiles show --verbose\n```\n\n## 相关资源\n\n- [安装文档](./installation.md)\n- [安全模型](./security-model.md)\n- [Setup 指南](./setup/index.md)\n- [插件系统](../plugins/README.md)\n- [技能目录](../skills/README.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：yeaight7/agent-powerups\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `agent-powerups` 与安装入口 `markitdown` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`pip install markitdown`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 来源证据：v0.1.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 8. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown\n\n## 9. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown\n\n\n",
"markdown_key": "agent-powerups",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1222971895",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/yeaight7/agent-powerups"
},
{
"evidence_id": "art_a5cf4f252a384e469fdfbc17a984c5ad",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/yeaight7/agent-powerups#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "agent-powerups 说明书",
"toc": [
"https://github.com/yeaight7/agent-powerups 项目说明书",
"目录",
"项目概览",
"1. 项目简介",
"2. 核心架构",
"3. 技能系统",
"4. 插件系统",
"5. 安装与配置",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "a73f89c13e78d5fe30f46c7c1a8c03bf350e9429",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"docs/philosophy.md",
"docs/release-checklist-v0.1.0.md",
"docs/security-model.md",
"docs/roadmap.md",
"docs/release-checklist-v0.1.1.md",
"docs/profiles-schema.md",
"docs/plugin-bundles-schema.json",
"docs/installation.md",
"docs/catalog-schema.md",
"docs/compatibility.md",
"docs/authoring-guide.md",
"docs/tool-requirements.md",
"docs/mcp-configs.md",
"docs/setup/gemini.md",
"docs/setup/codex.md",
"docs/setup/claude-code.md",
"examples/minimal/README.md",
"examples/codex/README.md",
"examples/claude-code/README.md",
"src/index.ts",
"src/cli/apx.ts",
"src/cli/utils/requirements.ts",
"src/cli/utils/paths.ts",
"src/cli/utils/catalog.ts",
"src/cli/utils/result.ts",
"src/cli/utils/profiles.ts",
"src/cli/utils/args.ts",
"src/cli/utils/plugins.ts",
"src/cli/utils/copy.ts",
"src/cli/utils/formatting.ts",
"src/cli/commands/hooks.ts",
"src/cli/commands/check.ts",
"src/cli/commands/assets.ts",
"src/cli/commands/doctor.ts",
"src/cli/commands/plugin.ts",
"src/cli/commands/validate.ts",
"src/cli/commands/setup.ts",
"src/cli/commands/run-command.ts"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# agent-powerups - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agent-powerups 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等 Claim：`clm_0002` unverified 0.25\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `git clone https://github.com/yeaight7/agent-powerups.git` 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `AGENTS.md`, `CLAUDE.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `AGENTS.md`, `CLAUDE.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `README.md`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0007` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`, `plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`, `plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`, `plugins/agentic-systems/skills/agent-harness-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json`, `.codex-plugin/marketplace.json`, `plugins/agent-evaluation-lab/.claude-plugin/plugin.json`, `plugins/agent-evaluation-lab/.codex-plugin/plugin.json` 等\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：709\n- 重要文件覆盖：40/709\n- 证据索引条目：180\n- 角色 / Skill 条目：203\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 agent-powerups 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agent-powerups 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 agent-powerups 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 203 个角色 / Skill / 项目文档条目。\n\n- **prompt-evaluation-runner**（skill）：Use when evaluating prompts, LLM outputs, red-team suites, or model behavior with local eval configs and safe provider/cost controls. 激活提示：当用户任务与“prompt-evaluation-runner”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`\n- **red-team-eval-authoring**（skill）：Use when creating or reviewing red-team eval plugins, attack templates, grader rubrics, safety fixtures, or model-risk test metadata. 激活提示：当用户任务与“red-team-eval-authoring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`\n- **skill-evaluation-workbench**（skill）：Use when designing, running, debugging, or hardening deterministic eval suites for agent skills, prompts, tool workflows, or MCP-backed cases. 激活提示：当用户任务与“skill-evaluation-workbench”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`\n- **agent-harness-design**（skill）：Design agent tool sets with stable names, narrow schemas, deterministic output shapes, and explicit error paths. No catch-all tools unless unavoidable. 激活提示：当用户任务与“agent-harness-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/agent-harness-design/SKILL.md`\n- **canonical-advisor-routing**（skill）：Process-first advisor routing with artifact capture 激活提示：当用户任务与“canonical-advisor-routing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/canonical-advisor-routing/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before acting. Broad search → exact source and tests → target-specific docs and setup. Stop after enough context or report what is still missing. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/context-retrieval-loop/SKILL.md`\n- **model-routing**（skill）：Vendor-neutral routing guide for choosing the right model tier by task type. Mechanical work uses a smaller/faster model; implementation uses a standard model; architecture, security, and release audit use the most capable model. 激活提示：当用户任务与“model-routing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/model-routing/SKILL.md`\n- **tri-model-review**（skill）：Multi-model orchestration — route to two external advisors, then synthesize 激活提示：当用户任务与“tri-model-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/agentic-systems/skills/tri-model-review/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before acting. Broad search → exact source and tests → target-specific docs and setup. Stop after enough context or report what is still missing. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/context-retrieval-loop/SKILL.md`\n- **local-rag-mcp**（skill）：Use when querying, ingesting, or maintaining a local RAG MCP corpus for semantic document retrieval with privacy controls. 激活提示：当用户任务与“local-rag-mcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/local-rag-mcp/SKILL.md`\n- **managed-codebase-context**（skill）：Use when connecting to a managed codebase-context MCP/session service, checking stale maps, or safely using MCP-provided repository context. 激活提示：当用户任务与“managed-codebase-context”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/managed-codebase-context/SKILL.md`\n- **search-before-building**（skill）：Check existing repo capability, external libraries, MCP options, and maintenance risk before writing custom code. Decide adopt/wrap/build with explicit criteria. 激活提示：当用户任务与“search-before-building”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/search-before-building/SKILL.md`\n- **structured-code-search-mcp**（skill）：Use when designing or using MCP-backed structured code search with search, AST query, symbol inventory, and bounded extraction workflows. 激活提示：当用户任务与“structured-code-search-mcp”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-intelligence/skills/structured-code-search-mcp/SKILL.md`\n- **ai-slop-cleaner**（skill）：Run an anti-slop cleanup workflow on AI-generated code — regression-tests-first, smell-by-smell, behavior preserved. 激活提示：当用户任务与“ai-slop-cleaner”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/ai-slop-cleaner/SKILL.md`\n- **architecture-simplification**（skill）：Use to collapse over-engineered abstractions, remove unnecessary layers, or consolidate redundant logic. 激活提示：当用户任务与“architecture-simplification”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/architecture-simplification/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before refactoring or maintenance work. Broad search → exact source and tests → config and build setup. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/context-retrieval-loop/SKILL.md`\n- **dead-code-removal**（skill）：Use to identify and safely delete unused functions, classes, exports, and files. 激活提示：当用户任务与“dead-code-removal”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/dead-code-removal/SKILL.md`\n- **dependency-cleanup**（skill）：Use to audit and remove unused or redundant third-party dependencies from package manifests. 激活提示：当用户任务与“dependency-cleanup”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/dependency-cleanup/SKILL.md`\n- **incremental-migration**（skill）：Use when migrating APIs, libraries, or patterns across a large codebase. Ensures safe, step-by-step progress rather than risky mega-commits. 激活提示：当用户任务与“incremental-migration”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/incremental-migration/SKILL.md`\n- **naming-and-structure-cleanup**（skill）：Use to enforce consistent naming conventions and file structures across a project without changing business logic. 激活提示：当用户任务与“naming-and-structure-cleanup”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/naming-and-structure-cleanup/SKILL.md`\n- **safe-refactor**（skill）：Use when code needs restructuring without changing observable behavior. 激活提示：当用户任务与“safe-refactor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/safe-refactor/SKILL.md`\n- **test-preserving-refactor**（skill）：Use to restructure code while guaranteeing that all existing tests continue to pass. 激活提示：当用户任务与“test-preserving-refactor”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/codebase-maintenance/skills/test-preserving-refactor/SKILL.md`\n- **deploy-pipeline-runbook**（skill）：Coordinate multi-system deployment steps as a review-first runbook with explicit approval before any external write or promotion action. 激活提示：当用户任务与“deploy-pipeline-runbook”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/connected-apps/skills/deploy-pipeline-runbook/SKILL.md`\n- **bigquery-cost-audit**（skill）：Analyze BigQuery usage, identify cost hotspots, repeated failures, and practical optimization opportunities. 激活提示：当用户任务与“bigquery-cost-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/bigquery-cost-audit/SKILL.md`\n- **data-quality**（skill）：Use when adding or reviewing data quality tests for dbt models in warehouse-backed analytics projects. Covers dbt generic tests, singular tests assert .sql , accepted-values macros, dbt utils patterns, cross-system consistency tests, and warehouse-oriented validation. Use when writing data tests, creating assert .sql files, testing business logic, or validating referential integrity. 激活提示：当用户任务与“data-quality”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/data-quality/SKILL.md`\n- **dbt-incremental-strategy-audit**（skill）：Audit whether a dbt incremental model uses the right incremental strategy for the repo, the data shape, and the operational constraints. 激活提示：当用户任务与“dbt-incremental-strategy-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/dbt-incremental-strategy-audit/SKILL.md`\n- **dbt-preflight**（skill）：Inspect changed dbt assets, estimate blast radius, identify missing tests, and recommend the narrowest safe validation plan. 激活提示：当用户任务与“dbt-preflight”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/dbt-preflight/SKILL.md`\n- **dbt-strategy**（skill）：Use when creating or modifying dimensional dbt models in warehouse-backed analytics projects. Covers a four-layer warehouse architecture sources/staging/core/marts , naming conventions, no-alias SQL rule, surrogate-key and missing-record patterns, incremental strategies, deduplication, and common project macros. Use when building fact tables, dimension tables, staging models, writing SQL, or designing tests. 激活提示：当用户任务与“dbt-strategy”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/dbt-strategy/SKILL.md`\n- **metric-impact-analyzer**（skill）：Evaluate metric and semantic model changes for BI/reporting breakage and business meaning drift. 激活提示：当用户任务与“metric-impact-analyzer”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/metric-impact-analyzer/SKILL.md`\n- **semantic-layer-change-review**（skill）：Use when modifying dbt metrics or semantic models to ensure mathematical correctness and backwards compatibility. 激活提示：当用户任务与“semantic-layer-change-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/semantic-layer-change-review/SKILL.md`\n- **sql-business-logic-review**（skill）：Review SQL for business logic correctness, semantic drift, aggregation risk, and silent definition changes. 激活提示：当用户任务与“sql-business-logic-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/data-engineering/skills/sql-business-logic-review/SKILL.md`\n- **bug-hunt**（skill）：Use when reproducing, isolating, and fixing a bug with the smallest safe change. 激活提示：当用户任务与“bug-hunt”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/bug-hunt/SKILL.md`\n- **failure-triage**（skill）：Use when confronted with an unknown failure in CI or production to rapidly categorize the issue before deep debugging. 激活提示：当用户任务与“failure-triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/failure-triage/SKILL.md`\n- **flaky-test-investigation**（skill）：Use to diagnose tests that pass and fail intermittently without code changes. 激活提示：当用户任务与“flaky-test-investigation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/flaky-test-investigation/SKILL.md`\n- **incident-readout**（skill）：Use after fixing a bug to generate a blameless post-mortem summary for human review. 激活提示：当用户任务与“incident-readout”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/incident-readout/SKILL.md`\n- **log-driven-diagnosis**（skill）：Use when debugging complex runtime failures, distributed systems, or issues where a local debugger cannot be attached. 激活提示：当用户任务与“log-driven-diagnosis”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/log-driven-diagnosis/SKILL.md`\n- **minimal-reproduction**（skill）：Use to isolate a bug from a large application into a standalone, runnable script or single test case. 激活提示：当用户任务与“minimal-reproduction”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/minimal-reproduction/SKILL.md`\n- **regression-bisecting**（skill）：Use when a bug was recently introduced but you don't know which commit caused it. 激活提示：当用户任务与“regression-bisecting”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/regression-bisecting/SKILL.md`\n- **systematic-debugging**（skill）：Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. 激活提示：当用户任务与“systematic-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/debugging-diagnostics/skills/systematic-debugging/SKILL.md`\n- **agent-harness-design**（skill）：Design agent tool sets with stable names, narrow schemas, deterministic output shapes, and explicit error paths. No catch-all tools unless unavoidable. 激活提示：当用户任务与“agent-harness-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/agent-harness-design/SKILL.md`\n- **agent-runtime-patterns**（skill）：Use when optimizing agent runtime loops, card packs, MCP session lifecycle, tool-call count, or multi-agent orchestration patterns. 激活提示：当用户任务与“agent-runtime-patterns”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/agent-runtime-patterns/SKILL.md`\n- **agent-session-forensics**（skill）：Use when diagnosing agent session history, interrupted tool loops, missing tool results, timing bottlenecks, or subagent trace correlation. 激活提示：当用户任务与“agent-session-forensics”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/agent-session-forensics/SKILL.md`\n- **brainstorming**（skill）：You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. 激活提示：当用户任务与“brainstorming”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/brainstorming/SKILL.md`\n- **context-compression**（skill）：Use when conversation context is bloated, constraints are being forgotten, or a compact handoff is needed before continuing work. 激活提示：当用户任务与“context-compression”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/context-compression/SKILL.md`\n- **context-minimization**（skill）：Use continuously during long tasks. Teaches how to read less, output less, and keep the LLM context window lean and fast. 激活提示：当用户任务与“context-minimization”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/context-minimization/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering codebase context before acting. Broad search → exact source and tests → target-specific docs and setup. Stop after enough context or report what is still missing. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/context-retrieval-loop/SKILL.md`\n- **dispatching-parallel-agents**（skill）：Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies 激活提示：当用户任务与“dispatching-parallel-agents”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/dispatching-parallel-agents/SKILL.md`\n- **handoff-discipline**（skill）：Use when completing a task or running out of context limit. Ensures the next session or human engineer has exactly what they need to resume work instantly. 激活提示：当用户任务与“handoff-discipline”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/handoff-discipline/SKILL.md`\n- **no-fluff**（skill）：Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use when user says \"no fluff\", \"be concise\", \"use less tokens\", or similar. 激活提示：当用户任务与“no-fluff”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/no-fluff/SKILL.md`\n- **repo-map**（skill）：Use when the task is to understand an unfamiliar codebase, locate key entry points, or summarize architecture before editing. 激活提示：当用户任务与“repo-map”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/repo-map/SKILL.md`\n- **strategic-context-compaction**（skill）：Compact context at logical phase boundaries — after research, after planning, after debugging — rather than mid-task. Preserves useful state while clearing noise. 激活提示：当用户任务与“strategic-context-compaction”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/strategic-context-compaction/SKILL.md`\n- **task-intake**（skill）：Use at the beginning of a new task. Ensures you fully understand the requirements, boundaries, and acceptance criteria before writing code. 激活提示：当用户任务与“task-intake”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/task-intake/SKILL.md`\n- **using-powerups**（skill）：Use when starting work in a repository with Agent Powerups installed, when a task may match a reusable local skill, command, workflow, hook recipe, AGENTS.md template, or MCP feature. 激活提示：当用户任务与“using-powerups”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/using-powerups/SKILL.md`\n- **verification-before-completion**（skill）：Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always 激活提示：当用户任务与“verification-before-completion”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/verification-before-completion/SKILL.md`\n- **writing-plans**（skill）：Use when you have a spec or requirements for a multi-step task, before touching code. 激活提示：当用户任务与“writing-plans”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/dev-vitals/skills/writing-plans/SKILL.md`\n- **agent-readable-docs**（skill）：Use when writing technical documentation that needs to be readable by both humans and AI models, converting existing docs to HADS format, validating a HADS document, or optimizing documentation for token-efficient AI consumption. 激活提示：当用户任务与“agent-readable-docs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/agent-readable-docs/SKILL.md`\n- **api-doc-review**（skill）：Verify that API endpoints match their OpenAPI/Swagger specifications. 激活提示：当用户任务与“api-doc-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/api-doc-review/SKILL.md`\n- **architecture-decision-records**（skill）：Record why an architectural choice was made to prevent agents or humans from unintentionally reverting it. 激活提示：当用户任务与“architecture-decision-records”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/architecture-decision-records/SKILL.md`\n- **context-docs**（skill）：Maintain short, focused Markdown files per subsystem to provide agents with isolated context. 激活提示：当用户任务与“context-docs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/context-docs/SKILL.md`\n- **context-retrieval-loop**（skill）：Deterministic 3-cycle loop for gathering documentation context before writing or updating docs. Broad search → exact source and existing docs → project conventions and setup. 激活提示：当用户任务与“context-retrieval-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/context-retrieval-loop/SKILL.md`\n- **doc-consistency-check**（skill）：Audit documentation for broken file paths, outdated commands, and renamed variables. 激活提示：当用户任务与“doc-consistency-check”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/doc-consistency-check/SKILL.md`\n- **handoff-documentation**（skill）：Write state-restoration documents for passing tasks between agents or engineers. 激活提示：当用户任务与“handoff-documentation”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/handoff-documentation/SKILL.md`\n- **readme-hardening**（skill）：Ensure the project README provides immediate, exact commands for setup, testing, and deployment to help agents and humans bootstrap quickly. 激活提示：当用户任务与“readme-hardening”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/readme-hardening/SKILL.md`\n- **review-comment-style-mining**（skill）：Use when mining PR review comments and text diffs for reusable writing, documentation, tone, and editorial improvement patterns. 激活提示：当用户任务与“review-comment-style-mining”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/documentation-systems/skills/review-comment-style-mining/SKILL.md`\n- **gh-address-comments**（skill）：Address actionable GitHub pull request review feedback. Use when the user wants to inspect unresolved review threads, requested changes, or inline review comments on a PR, then implement selected fixes. 激活提示：当用户任务与“gh-address-comments”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/github-ops/skills/gh-address-comments/SKILL.md`\n- **github-ci-failure-triage**（skill）：Inspect GitHub PR checks, fetch actionable failure logs, summarize the breakage, and propose a local fix plan before changing code. 激活提示：当用户任务与“github-ci-failure-triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/github-ops/skills/github-ci-failure-triage/SKILL.md`\n- **pr-review-ci-loop**（skill）：Run a review and CI loop around a pull request with explicit approval gates for code changes, remote writes, and follow-up actions. 激活提示：当用户任务与“pr-review-ci-loop”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/github-ops/skills/pr-review-ci-loop/SKILL.md`\n- **baseline-comparison-review**（skill）：Ensure that new complex models actually outperform simple, naive baselines. 激活提示：当用户任务与“baseline-comparison-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/baseline-comparison-review/SKILL.md`\n- **dataset-split-review**（skill）：Audit the methodology used to split data into train, validation, and test sets. 激活提示：当用户任务与“dataset-split-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/dataset-split-review/SKILL.md`\n- **experiment-tracking-review**（skill）：Verify that all hyperparameters, metrics, and data references are properly logged. 激活提示：当用户任务与“experiment-tracking-review”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/experiment-tracking-review/SKILL.md`\n- **ml-leakage-check**（skill）：Identify and prevent target leakage in ML preprocessing pipelines. 激活提示：当用户任务与“ml-leakage-check”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/ml-leakage-check/SKILL.md`\n- **model-evaluation-reporting**（skill）：Standardize the reporting of model metrics to ensure statistical rigor and business relevance. 激活提示：当用户任务与“model-evaluation-reporting”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/model-evaluation-reporting/SKILL.md`\n- **reproducible-training-runs**（skill）：Analyzes ML training scripts to enforce seed setting, deterministic operations, and environment tracking for exact reproducibility. 激活提示：当用户任务与“reproducible-training-runs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/reproducible-training-runs/SKILL.md`\n- **training-pipeline-debugging**（skill）：Diagnose NaN losses, out-of-memory errors, and shape mismatches in deep learning or ML pipelines. 激活提示：当用户任务与“training-pipeline-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/machine-learning-ops/skills/training-pipeline-debugging/SKILL.md`\n- **mcp-server-builder**（skill）：Design high-quality MCP servers around workflows, narrow schemas, context-aware outputs, and actionable errors. Use when building or reviewing MCP tools for real agent tasks. 激活提示：当用户任务与“mcp-server-builder”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/mcp-development/skills/mcp-server-builder/SKILL.md`\n- **defuddle**（skill）：Use when the user provides a URL to a standard web page and clean Markdown extraction with Defuddle would reduce clutter and token cost. 激活提示：当用户任务与“defuddle”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/defuddle/SKILL.md`\n- **graphify**（skill）：any input code, docs, papers, images → knowledge graph → clustered communities → HTML + JSON + audit report. Use when the user wants to build, inspect, or query a cross-file knowledge graph from code, docs, papers, images, or videos with upstream graphify. 激活提示：当用户任务与“graphify”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/graphify/SKILL.md`\n- **markitdown-file-intake**（skill）：Use when the user provides a MarkItDown-supported file or URL and converting it to Markdown first will make inspection easier, cheaper, or more reliable. 激活提示：当用户任务与“markitdown-file-intake”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/markitdown-file-intake/SKILL.md`\n- **memory-build-workflow**（skill）：Use when a user needs to build or refresh persistent graph memory from a mixed corpus and the right path may include graphify, incremental update, or helper conversion before ingestion. 激活提示：当用户任务与“memory-build-workflow”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/memory-build-workflow/SKILL.md`\n- **memory-optimization-workflow**（skill）：Use when deciding the lowest-cost context path for a mixed corpus, especially when choosing among direct reading, helper conversion, graph build, graph update, or graph query. 激活提示：当用户任务与“memory-optimization-workflow”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/memory-optimization/skills/memory-optimization-workflow/SKILL.md`\n- 其余 123 个条目见 `AI_CONTEXT_PACK.json`。\n\n## 证据索引\n\n- 共索引 180 条证据。\n\n- **Gemini Setup**（documentation）：Status: compatibility and agent-curated setup path. For manual install, prefer apx install gemini or apx install gemini --full . This document describes what apx setup gemini still does; it is not an official Gemini CLI integration claim. 证据：`docs/setup/gemini.md`\n- **Repository Guidelines**（documentation）：Project Structure & Module Organization Agent Powerups is a Node.js/TypeScript CLI plus a catalog of agent assets. Core CLI code lives in src/cli/ , with command handlers in src/cli/commands/ and shared helpers in src/cli/utils/ . Tests live in test/ as .test.ts . 证据：`AGENTS.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **Project Overview**（documentation）：Agent Powerups is an \"Oh My Zsh-style\" collection of reusable skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for coding agents. It provides a local-first CLI tool apx for browsing, validating, running, and explicitly installing these agent powerups. 证据：`GEMINI.md`\n- **What Is Here**（documentation）：Quickstart · Plugin Bundles · Installation · Security Model · Contributing 证据：`README.md`\n- **Plugins**（documentation）：Domain-specific plugin bundles for Agent Powerups. Each plugin extends the base powerups with deeper, specialized skills, agents, and commands for a particular engineering domain. 证据：`plugins/README.md`\n- **AGENTS.md**（documentation）：- Inspect model lineage before changing SQL. - Keep metric and semantic changes explicit. - Do not change warehouse credentials or profiles. 证据：`agents-md/dbt-project/AGENTS.md`\n- **AGENTS.md**（documentation）：- Preserve seeds, splits, metrics, and experiment tracking unless requested. - Treat data changes as high-risk. - Keep model comparisons reproducible. 证据：`agents-md/ml-project/AGENTS.md`\n- **AGENTS.md**（documentation）：- Preserve public APIs and contributor workflows. - Read issue or PR context before editing. - Keep changelog, docs, and tests aligned with user-visible changes. 证据：`agents-md/open-source-maintainer/AGENTS.md`\n- **AGENTS.md**（documentation）：- Read package metadata and tests before editing. - Prefer small API-compatible changes. - Do not add dependencies or publishing config unless requested. 证据：`agents-md/python-library/AGENTS.md`\n- **AGENTS.md**（documentation）：- Read the smallest relevant set of files before editing. - Prefer minimal diffs. - Preserve the existing package manager, lint, test, and build flows. - Run the narrowest meaningful validation before claiming completion. - Do not add dependencies, secrets, or global config changes unless explicitly requested. 证据：`agents-md/typescript-app/AGENTS.md`\n- **Claude Code Setup Example**（documentation）：Goal: stage Agent Powerups for Claude Code review. 证据：`examples/claude-code/README.md`\n- **Codex Setup Example**（documentation）：Goal: stage Agent Powerups for Codex review. 证据：`examples/codex/README.md`\n- **Minimal Setup Example**（documentation）：Goal: inspect Agent Powerups without mutating an agent's global config. 证据：`examples/minimal/README.md`\n- **agent-evaluation-lab**（documentation）：Prompt, skill, red-team, and agent behavior evaluation workflows. 证据：`plugins/agent-evaluation-lab/GEMINI.md`\n- **agentic-systems**（documentation）：Multi-model orchestration and advisor routing: tri-model review and canonical advisor routing. 证据：`plugins/agentic-systems/GEMINI.md`\n- **Agents**（documentation）：Agents Experimental agentic-systems agents. 证据：`plugins/agentic-systems/agents/README.md`\n- **Commands**（documentation）：Commands Experimental agentic-systems commands. 证据：`plugins/agentic-systems/commands/README.md`\n- **codebase-intelligence**（documentation）：Search-first codebase understanding, context retrieval, mapping, pattern detection, and living project intelligence. 证据：`plugins/codebase-intelligence/GEMINI.md`\n- **codebase-maintenance**（documentation）：Safe refactoring, dead-code removal, legacy modernization, and dependency hygiene. 证据：`plugins/codebase-maintenance/GEMINI.md`\n- **connected-apps**（documentation）：Review-first runbooks for connected-app workflows and multi-system deployment sequencing. 证据：`plugins/connected-apps/GEMINI.md`\n- **context-efficiency**（documentation）：Context-efficient routing: dispatch tables for workflow, review, and codebase-intelligence commands. 证据：`plugins/context-efficiency/GEMINI.md`\n- **data-engineering**（documentation）：Analytics engineering, dbt patterns, BigQuery optimization, data quality, and pipeline workflows. 证据：`plugins/data-engineering/GEMINI.md`\n- **debugging-diagnostics**（documentation）：Error diagnosis, fault isolation, log forensics, and incident investigation. 证据：`plugins/debugging-diagnostics/GEMINI.md`\n- **dev-vitals**（documentation）：Core developer workflow skills: planning, execution, communication, and powerup discovery. 证据：`plugins/dev-vitals/GEMINI.md`\n- **documentation-systems**（documentation）：Documentation architecture, API reference authoring, ADR writing, readme hardening, and doc quality. 证据：`plugins/documentation-systems/GEMINI.md`\n- **github-ops**（documentation）：GitHub review, comment handling, and CI triage workflows with approval-gated write actions. 证据：`plugins/github-ops/GEMINI.md`\n- **machine-learning-ops**（documentation）：ML pipeline design, experiment tracking, model evaluation, training debugging, and reproducibility. 证据：`plugins/machine-learning-ops/GEMINI.md`\n- **mcp-development**（documentation）：Workflow-first MCP server design with schema-first tools, context-aware outputs, and evaluation discipline. 证据：`plugins/mcp-development/GEMINI.md`\n- **memory-optimization**（documentation）：Graph-backed memory and context optimization bundle with graphify as the primary engine and document-conversion helpers used only when they reduce noise or reread cost. 证据：`plugins/memory-optimization/GEMINI.md`\n- **CLAUDE.md stub**（documentation）：This is a stub reference file. The graphify skill references CLAUDE.md as a documentation source in the target repository. 证据：`plugins/memory-optimization/skills/graphify/references/CLAUDE.md`\n- **quality-gates**（documentation）：Quality enforcement: TDD discipline, code review workflows, release verification, and CI failure analysis. 证据：`plugins/quality-gates/GEMINI.md`\n- **security-guardrails**（documentation）：Security vulnerability detection: OWASP Top 10 analysis, secrets scanning, dependency audits. 证据：`plugins/security-guardrails/GEMINI.md`\n- **Commands**（documentation）：Commands Experimental security-guardrails commands. 证据：`plugins/security-guardrails/commands/README.md`\n- **skill-authoring**（documentation）：Skill creation and extraction workflows for reusable agent guidance. 证据：`plugins/skill-authoring/GEMINI.md`\n- **software-engineering**（documentation）：Subagent orchestration, wave execution, worktree isolation, persistent completion, autonomous delivery, and migration batching. 证据：`plugins/software-engineering/GEMINI.md`\n- **Commands**（documentation）：Commands Experimental software-engineering commands. 证据：`plugins/software-engineering/commands/README.md`\n- **spec-driven-development**（documentation）：Requirements clarification, phase planning, workstreams, and wave-based execution for reviewable delivery. 证据：`plugins/spec-driven-development/GEMINI.md`\n- **spec-quality-gates**（documentation）：Quality gates for spec-driven development: adversarial plan verification and structured code review. 证据：`plugins/spec-quality-gates/GEMINI.md`\n- **tool-integrations**（documentation）：Browser, MCP, retrieval, and agent runtime integration skills with conservative setup and safety boundaries. 证据：`plugins/tool-integrations/GEMINI.md`\n- **CLAUDE.md stub**（documentation）：This is a stub reference file. The graphify skill references CLAUDE.md as a documentation source in the target repository. 证据：`skills/graphify/references/CLAUDE.md`\n- **Core Agent Tools - Refactored Assets**（documentation）：Core Agent Tools - Refactored Assets 证据：`staging/refactor/core-agent-tools/README.md`\n- **Package**（package_manifest）：{ \"name\": \"agent-powerups\", \"version\": \"0.3.0\", \"description\": \"Local-first CLI for browsing, validating, running, and explicitly writing agent powerups.\", \"license\": \"Apache-2.0\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/yeaight7/agent-powerups.git\" }, \"bugs\": { \"url\": \"https://github.com/yeaight7/agent-powerups/issues\" }, \"homepage\": \"https://github.com/yeaight7/agent-powerups\", \"keywords\": \"claude-code\", \"codex\", \"ai-agents\", \"skills\", \"mcp\", \"developer-tools\", \"cli\", \"gemini-cli\", \"gemini\", \"skill-pack\", \"plugin\" , \"bin\": { \"apx\": \"dist/cli/apx.js\" }, \"engines\": { \"node\": \" =20\" }, \"files\": \"dist/\", \"!dist/test/\", \"skills/\", \"!skills/graphify/refer… 证据：`package.json`\n- **Contributing to Agent Powerups**（documentation）：Keep contributions small, explicit, and portable. 证据：`CONTRIBUTING.md`\n- **Prompt Evaluation Runner**（skill_instruction）：When to use Use this skill when you need to evaluate an LLM app, test a prompt, or run red-teaming/vulnerability scans against a target model or application. 证据：`plugins/agent-evaluation-lab/skills/prompt-evaluation-runner/SKILL.md`\n- **Red-Team Eval Authoring**（skill_instruction）：When To Use - Adding a new red-team plugin or grader. - Editing attack templates, rubric tags, or plugin metadata. - Reviewing multimodal or tool-use safety evals for false positives/negatives. 证据：`plugins/agent-evaluation-lab/skills/red-team-eval-authoring/SKILL.md`\n- **Skill Evaluation Workbench**（skill_instruction）：When To Use - A skill or prompt needs repeatable quality checks across models. - A workflow needs file-based graders, command traces, or local artifact checks. - A tool/MCP skill needs a hidden service fixture or sandboxed test workspace. - A previous agent attempt failed and you need trace-driven diagnosis before editing instructions. 证据：`plugins/agent-evaluation-lab/skills/skill-evaluation-workbench/SKILL.md`\n- **Agent Harness Design**（skill_instruction）：Use when designing or improving how an agent invokes tools, handles errors, and decides when to stop. 证据：`plugins/agentic-systems/skills/agent-harness-design/SKILL.md`\n- **Canonical Advisor Routing**（skill_instruction）：Route a prompt through a local provider CLI and persist the result as an artifact. 证据：`plugins/agentic-systems/skills/canonical-advisor-routing/SKILL.md`\n- **Context Retrieval Loop**（skill_instruction）：Gather the right codebase context before making changes or spawning subagents. Prevents acting on incomplete information. 证据：`plugins/agentic-systems/skills/context-retrieval-loop/SKILL.md`\n- **Model Routing**（skill_instruction）：Choose the right model tier before starting a task. Overusing a capable model wastes cost and context. Underusing it produces lower quality on complex work. 证据：`plugins/agentic-systems/skills/model-routing/SKILL.md`\n- **Tri-Model Review**（skill_instruction）：Tri-model review routes through two external advisor CLIs, then synthesizes both outputs into one answer. 证据：`plugins/agentic-systems/skills/tri-model-review/SKILL.md`\n- **Context Retrieval Loop**（skill_instruction）：Gather the right codebase context before making changes or spawning subagents. Prevents acting on incomplete information. 证据：`plugins/codebase-intelligence/skills/context-retrieval-loop/SKILL.md`\n- **Local RAG MCP**（skill_instruction）：When to use Use when the task requires semantic search, document ingestion, or querying a local vector database for context retrieval, and an appropriate MCP server is available. 证据：`plugins/codebase-intelligence/skills/local-rag-mcp/SKILL.md`\n- **Managed Codebase Context**（skill_instruction）：When to use Use when managing persistent sessions, dynamic codebase mappings, or managed context states using a dedicated codebase-context MCP server. 证据：`plugins/codebase-intelligence/skills/managed-codebase-context/SKILL.md`\n- **Search Before Building**（skill_instruction）：Before implementing new functionality, verify it does not already exist and that the best option has been considered. 证据：`plugins/codebase-intelligence/skills/search-before-building/SKILL.md`\n- **Structured Code Search MCP**（skill_instruction）：When to use Use when developing a new MCP server, debugging an MCP connection, or integrating an agent with standard MCP protocols. 证据：`plugins/codebase-intelligence/skills/structured-code-search-mcp/SKILL.md`\n- **Purpose**（skill_instruction）：Reduce AI-generated code bloat through systematic, smell-by-smell cleanup that preserves existing behavior and raises signal quality. 证据：`plugins/codebase-maintenance/skills/ai-slop-cleaner/SKILL.md`\n- **Architecture Simplification**（skill_instruction）：Over time, codebases accumulate \"just in case\" abstractions. This skill guides the safe removal of unnecessary complexity. 证据：`plugins/codebase-maintenance/skills/architecture-simplification/SKILL.md`\n- **Context Retrieval Loop Codebase Maintenance**（skill_instruction）：Context Retrieval Loop Codebase Maintenance 证据：`plugins/codebase-maintenance/skills/context-retrieval-loop/SKILL.md`\n- 其余 120 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/setup/gemini.md`, `AGENTS.md`, `CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/setup/gemini.md`, `AGENTS.md`, `CLAUDE.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概览**：importance `high`\n - source_paths: README.md, SECURITY.md, catalog.json, package.json\n- **安装指南**：importance `high`\n - source_paths: docs/installation.md, docs/compatibility.md, src/index.ts, tsconfig.json\n- **apx CLI 参考**：importance `high`\n - source_paths: src/cli/apx.ts, src/cli/commands, src/cli/utils\n- **资产目录系统**：importance `high`\n - source_paths: catalog.json, docs/catalog-schema.md, scripts/validate-skills.py, scripts/validate-catalog.py\n- **插件包系统**：importance `high`\n - source_paths: plugins/README.md, plugin-bundles.json, .claude-plugin/marketplace.json, .codex-plugin/marketplace.json, docs/plugin-bundles-schema.json\n- **技能系统**：importance `high`\n - source_paths: skills/systematic-debugging/SKILL.md, skills/writing-plans/SKILL.md, skills/using-powerups/SKILL.md, skills/skill-authoring-guide/SKILL.md\n- **命令系统**：importance `medium`\n - source_paths: commands/generic, commands/claude-code, commands/codex, commands/bug-check.md, commands/security-audit.md\n- **钩子系统**：importance `medium`\n - source_paths: hooks/productivity, hooks/quality, hooks/safety, docs/security-model.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `a73f89c13e78d5fe30f46c7c1a8c03bf350e9429`\n- inspected_files: `package.json`, `README.md`, `docs/philosophy.md`, `docs/release-checklist-v0.1.0.md`, `docs/security-model.md`, `docs/roadmap.md`, `docs/release-checklist-v0.1.1.md`, `docs/profiles-schema.md`, `docs/plugin-bundles-schema.json`, `docs/installation.md`, `docs/catalog-schema.md`, `docs/compatibility.md`, `docs/authoring-guide.md`, `docs/tool-requirements.md`, `docs/mcp-configs.md`, `docs/setup/gemini.md`, `docs/setup/codex.md`, `docs/setup/claude-code.md`, `examples/minimal/README.md`, `examples/codex/README.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `agent-powerups` 与安装入口 `markitdown` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.1.4\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.1.4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ee1d355f496c46158442305fd9ed9206 | https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：yeaight7/agent-powerups\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/yeaight7/agent-powerups 项目说明书\n\n生成时间：2026-05-13 03:27:06 UTC\n\n## 目录\n\n- [项目概览](#overview)\n- [安装指南](#installation)\n- [apx CLI 参考](#cli-reference)\n- [资产目录系统](#catalog-system)\n- [插件包系统](#plugin-bundles)\n- [技能系统](#skills)\n- [命令系统](#commands)\n- [钩子系统](#hooks)\n- [MCP 配置管理](#mcp-configs)\n- [用户意图配置](#profiles)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [资产目录系统](#catalog-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n \n\n# 项目概览\n\n## 1. 项目简介\n\nAgent Powerups 是一个面向编码智能体（coding agents）的可重用技能集合，采用与 Oh My Zsh 相似的设计理念。该项目旨在为各种编码智能体（如 Codex、Claude Code、 Gemini）提供标准化的技能、命令、配置和工作流扩展方案。\n\n### 1.1 核心定位\n\n| 维度 | 描述 |\n|------|------|\n| 项目性质 | 智能体扩展工具包 |\n| 设计理念 | Oh My Zsh 风格的可复用组件集合 |\n| 支持平台 | Codex、Claude Code、 Gemini |\n| 安装方式 | npm 包本地安装（`apx` CLI） |\n| 资料来源：[README.md:1-15] |\n\n### 1.2 主要交付物\n\n项目当前版本包含以下核心交付物：\n\n- **可复用技能（Skills）**：23个预置技能，涵盖调试、代码审查、数据工程等领域\n- **CLI 工具（`apx`）**：本地安全命令行工具，支持智能体检查和安装\n- **MCP 配置**：本地优先的 GitHub MCP 配置及检查流程\n- **AGENTS.md 模板**：5种项目类型的起始模板\n- **命令包**：2个预置命令包\n- **Hook 示例**：3个钩子示例\n- **17个插件包**：3个稳定版、10个测试版、4个实验版\n- **2个工作流**：特性迭代和智能体中继\n\n资料来源：[README.md:85-115]\n\n## 2. 核心架构\n\n### 2.1 系统架构图\n\n```mermaid\ngraph TD\n A[用户/智能体] --> B[apx CLI 工具]\n B --> C[目录服务 CatalogService]\n C --> D[技能存储 skills/]\n C --> E[插件存储 plugins/]\n C --> F[命令存储 commands/]\n C --> G[Hook 存储 hooks/]\n C --> H[MCP 配置 mcp/]\n C --> I[AGENTS.md 模板 agents-md/]\n \n B --> J[setup 命令]\n B --> K[check 命令]\n B --> L[doctor 命令]\n B --> M[security-audit 命令]\n B --> N[plugins 命令]\n \n J --> O[目标智能体环境]\n K --> P[需求检查]\n M --> Q[安全扫描]\n```\n\n### 2.2 CLI 命令体系\n\n`apx` 是项目的核心命令行工具，提供以下主要命令：\n\n| 命令 | 功能描述 |\n|------|----------|\n| `apx list` | 列出所有可用技能和资源 |\n| `apx info ` | 查看特定技能/资源的详细信息 |\n| `apx check ` | 验证技能或资源的配置状态 |\n| `apx setup ` | 将 Agent Powerups 安装到指定智能体 |\n| `apx doctor` | 运行诊断检查，验证环境完整性 |\n| `apx security-audit` | 扫描安全风险模式 |\n| `apx plugins list` | 列出所有插件包 |\n| `apx plugins install` | 安装插件到目标智能体 |\n| `apx commands run` | 执行命令包 |\n| `apx hooks run` | 运行钩子脚本 |\n| `apx mcp check/smoke/install` | MCP 服务器检查和安装 |\n\n资料来源：[src/cli/apx.ts:1-30]\n\n### 2.3 目录结构\n\n```\nagent-powerups/\n├── skills/ # 可复用技能目录\n│ ├── systematic-debugging/\n│ ├── writing-plans/\n│ ├── dbt-preflight/\n│ └── ... (23个技能)\n├── agents-md/ # AGENTS.md 模板\n│ ├── typescript-app/\n│ ├── python-library/\n│ └── ...\n├── commands/ # 命令包\n│ ├── ship-check/\n│ └── using-powerups-command/\n├── hooks/ # 钩子示例\n│ ├── no-secrets-preflight/\n│ ├── handoff-summary/\n│ └── validation-required/\n├── mcp/ # MCP 配置\n│ └── github-local/\n├── workflows/ # 工作流\n│ ├── feature-iteration/\n│ └── agent-relay/\n├── plugins/ # 插件包 (17个)\n│ ├── dev-vitals/ # 稳定版\n│ ├── debugging-diagnostics/\n│ ├── quality-gates/\n│ └── ... (beta/experimental)\n└── scripts/ # 验证脚本\n ├── validate-skills.py\n ├── validate-catalog.py\n └── check-requirements.py\n```\n\n## 3. 技能系统\n\n### 3.1 技能定义\n\n技能是 Agent Powerups 的核心交付单元，每个技能是一个独立的工作流或方法论，通过 `SKILL.md` 文件定义。\n\n```mermaid\ngraph LR\n A[SKILL.md] --> B[frontmatter 元数据]\n A --> C[技能说明]\n A --> D[使用步骤]\n A --> E[支持文件引用]\n \n B --> B1[name 名称]\n B --> B2[description 描述]\n B --> B3[tags 标签]\n B --> B4[requires 依赖]\n```\n\n资料来源：[src/cli/commands/doctor.ts:15-30]\n\n### 3.2 预置技能分类\n\n| 类别 | 技能列表 |\n|------|----------|\n| 调试分析 | `systematic-debugging`、`bug-hunt`、`safe-refactor` |\n| 代码质量 | `no-fluff`、`quality-gates`、`sql-business-logic-review` |\n| 规划协作 | `writing-plans`、`requesting-code-review`、`receiving-code-review`、`pr-triage` |\n| 数据工程 | `bigquery-cost-audit`、`dbt-incremental-strategy-audit`、`dbt-preflight`、`dbt-strategy`、`data-quality`、`metric-impact-analyzer` |\n| 智能体协作 | `ask-claude`、`ask-gemini`、`ask-codex`、`using-powerups`、`graphify` |\n| 内容处理 | `ai-slop-cleaner`、`defuddle`、`markitdown-file-intake`、`repo-map` |\n\n资料来源：[README.md:85-95]\n\n### 3.3 技能验证机制\n\n项目提供多层次的技能验证：\n\n1. **结构验证**：检查 `SKILL.md` 文件是否存在\n2. **元数据验证**：确保 frontmatter 包含必需的 `name` 和 `description` 字段\n3. **引用验证**：检查技能中引用的支持文件是否存在\n4. **目录验证**：确保技能目录下文件结构完整\n\n```typescript\n// 验证逻辑伪代码\nif (!frontmatter?.name || !frontmatter?.description) {\n issues.push(`${entry.name}: missing required frontmatter`);\n}\n\nfor (const ref of referencedSupportFiles(content)) {\n if (!(await supportRefExists(skillDir, ref))) {\n issues.push(`${entry.name}: missing referenced support file ${ref}`);\n }\n}\n```\n\n资料来源：[src/cli/commands/doctor.ts:20-40]\n\n## 4. 插件系统\n\n### 4.1 插件包结构\n\n插件包采用多智能体兼容结构：\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code 清单\n├── .codex-plugin/\n│ └── plugin.json # Codex 清单\n├── skills/\n│ └── /\n│ └── SKILL.md\n├── agents/\n│ └── .md\n└── commands/\n └── .md\n```\n\n资料来源：[plugins/README.md:20-35]\n\n### 4.2 插件状态分类\n\n| 状态 | 数量 | 插件示例 |\n|------|------|----------|\n| 稳定版 | 3 | `dev-vitals`、`debugging-diagnostics`、`quality-gates` |\n| 测试版 | 10 | `codebase-maintenance`、`data-engineering`、`documentation-systems` 等 |\n| 实验版 | 4 | `software-engineering`、`agentic-systems`、`security-guardrails` 等 |\n\n资料来源：[README.md:110-120]\n\n### 4.3 插件操作命令\n\n```sh\napx plugins list # 列出所有插件\napx plugins info # 查看插件详情\napx plugins validate --all # 验证所有插件结构\napx plugins install --target codex --dry-run # 预览安装\napx plugins install --target claude-code # 安装到 Claude Code\n```\n\n## 5. 安装与配置\n\n### 5.1 安装模式\n\n`apx setup` 命令支持三种安装模式：\n\n| 模式 | 描述 | 覆盖范围 |\n|------|------|----------|\n| `minimal` | 引导模式 | 仅基础指令文件 |\n| `recommended` | 推荐模式 | 技能、插件、命令等核心资源 |\n| `full` | 完整模式 | 全部资源及支持文件 |\n\n资料来源：[src/cli/commands/setup.ts:15-50]\n\n### 5.2 目标智能体支持\n\n```sh\napx setup codex --mode recommended --yes # 安装到 Codex\napx setup claude-code --mode recommended --yes # 安装到 Claude Code\napx setup gemini --mode recommended --yes # 安装到 Gemini\n```\n\n### 5.3 安装流程\n\n```mermaid\ngraph TD\n A[apx setup ] --> B{检查 AGENTS.md 存在?}\n B -->|存在| C[创建备份]\n B -->|不存在| D[写入 instructions/agent-powerups.md]\n C --> E[追加 agent-powerups 块]\n E --> F[复制资源到 agent-powerups/]\n F --> G[更新全局指令]\n D --> G\n G --> H[安装完成]\n```\n\n资料来源：[src/cli/commands/setup.ts:80-120]\n\n## 6. 安全模型\n\n### 6.1 安全扫描规则\n\n`apx security-audit` 命令实现多层次安全扫描：\n\n| 规则名称 | 严重级别 | 检测模式 |\n|----------|----------|----------|\n| `broad-filesystem-write` | P1 | 递归删除或广泛文件写入 |\n| `missing-dry-run` | P1 | install 命令缺少 --dry-run |\n| `unpinned-latest-image` | P2 | CI 配置中使用 :latest 镜像 |\n\n资料来源：[src/cli/commands/security-audit.ts:1-30]\n\n### 6.2 安全检查范围\n\n```typescript\nconst SKIP_DIRS = new Set([\"node_modules\", \"dist\", \".git\", \".worktrees\", \".plugins\"]);\nconst SCAN_EXTS = new Set([\".json\", \".toml\", \".md\", \".sh\", \".ps1\", \".yaml\", \".yml\"]);\nconst MAX_FILE_BYTES = 512 * 1024;\n```\n\n扫描跳过以下目录和文件：\n- `node_modules`、`dist`、`.git` 等标准构建目录\n- 单文件大小限制为 512KB\n- 仅扫描特定扩展名文件\n\n### 6.3 安全警告\n\n> ⚠️ **重要提示**：在将资源加载到受信任的智能体环境之前，务必审查所有资产。\n>\n> - 技能可能指示智能体读取本地文件或执行命令\n> - 钩子可能在宿主智能体支持时执行代码\n> - MCP 配置可能扩展工具访问权限\n> - 安装命令可能修改本地环境\n> - 除非严格必要，否则不应将密钥粘贴到智能体上下文中\n\n资料来源：[README.md:125-135]\n\n## 7. 验证与诊断\n\n### 7.1 doctor 命令检查项\n\n`apx doctor` 提供全面的环境诊断：\n\n| 检查项 | 验证内容 |\n|--------|----------|\n| `apx` 二进制 | 验证 CLI 可执行文件 |\n| 依赖项 | 检查所需工具是否安装 |\n| 配置文件 | 验证配置完整性 |\n| 技能文件 | 检查 SKILL.md 和元数据 |\n| 外部检查 | 运行外部验证脚本 |\n\n资料来源：[src/cli/commands/doctor.ts:1-60]\n\n### 7.2 check 命令功能\n\n```typescript\ninterface CheckResult {\n exitCode: number; // 0=成功, 1=失败\n output: string; // 输出信息\n warnings: string[]; // 警告列表\n actions: string[]; // 建议操作\n}\n```\n\ncheck 命令支持：\n- 批量检查多个资产\n- 验证依赖项状态\n- 自动安装缺失依赖（可选）\n\n资料来源：[src/cli/commands/check.ts:1-30]\n\n## 8. 兼容性矩阵\n\n| 资产类别 | 当前状态 | 兼容性说明 |\n|----------|----------|------------|\n| 根 `skills/` | 已发布 | 通用文本技能，部分提及已知智能体 |\n| `mcp/` | 已发布 | 本地优先 MCP 配置 |\n| 插件包 | 已发布 | 按目标智能体分类 |\n| 验证脚本 | 已发布 | Python 脚本 |\n\n## 9. 快速开始\n\n### 9.1 环境准备\n\n```sh\n# 安装依赖\nnpm install\nnpm run build\nnpm link\n\n# 验证安装\napx doctor\n```\n\n### 9.2 基本工作流\n\n```sh\n# 1. 浏览目录\napx list\napx info markitdown-file-intake\n\n# 2. 验证资源\napx commands run ship-check\napx hooks run no-secrets-preflight --all\n\n# 3. MCP 检查\napx mcp check github-local --target generic\napx mcp smoke github-local --json\n\n# 4. 安装到智能体\napx setup codex --dry-run\napx setup codex --mode recommended --yes\n```\n\n### 9.3 本地智能体咨询\n\n```sh\napx ask-codex \"Return OK only\" --json\napx ask-claude \"Return OK only\" --json\napx ask-gemini \"Return OK only\" --json\n```\n\n## 10. 总结\n\nAgent Powerups 项目为编码智能体提供了一个标准化、可扩展的技能和工具集合。其核心价值包括：\n\n- **模块化设计**：技能、插件、命令独立存在，易于组合使用\n- **多智能体支持**：统一接口支持 Codex、Claude Code、 Gemini\n- **本地优先**：所有资源本地存储，保证数据隐私和安全\n- **验证体系**：完整的检查、诊断和审计机制\n- **渐进式安装**：支持 minimal、recommended、full 三种安装级别\n\n该项目遵循类似 Oh My Zsh 的社区驱动模式，通过 npm 包分发 `apx` CLI 工具，用户可灵活选择安装哪些技能和插件到目标智能体环境中。\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[apx CLI 参考](#cli-reference), [用户意图配置](#profiles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [examples/minimal/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/minimal/README.md)\n- [examples/codex/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/codex/README.md)\n- [examples/claude-code/README.md](https://github.com/yeaight7/agent-powerups/blob/main/examples/claude-code/README.md)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n \n\n# 安装指南\n\n## 概述\n\nAgent Powerups 是一个面向编程代理的 Oh My Zsh 风格工具集，提供了可复用的技能、命令、MCP 配置、钩子、AGENTS.md 模板和工作流。本指南将详细介绍如何在不同环境下安装和配置 Agent Powerups。\n\n安装的核心目标是：将仓库中的资产（skills、plugins、commands、hooks 等）安全地部署到目标代理的工作目录中，同时保持灵活性和可控性。\n\n## 系统要求\n\n### 基础依赖\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Node.js | 最新稳定版 | CLI 工具运行所需 |\n| npm | 最新稳定版 | 用于安装 apx CLI |\n| Python | 3.x | 部分验证脚本需要 |\n| Git | 最新稳定版 | 用于仓库克隆和更新 |\n\n安装前请运行 `apx doctor` 命令检查环境配置是否满足要求。\n\n## 安装方法\n\n### 方法一：通过 npm 全局安装 apx CLI\n\napx 是 Agent Powerups 的命令行工具，提供资产发现、检验、安装和配置等功能。\n\n```sh\nnpm install -g agent-powerups\n```\n\n安装完成后，验证安装：\n\n```sh\napx doctor\napx --version\n```\n\n### 方法二：从源码构建\n\n适用于需要自定义或参与开发的用户：\n\n```sh\ngit clone https://github.com/yeaight7/agent-powerups.git\ncd agent-powerups\nnpm install\nnpm run build\nnpm link\n```\n\n资料来源：[examples/minimal/README.md]()\n\n### 方法三：Docker 环境安装\n\n如需在容器化环境中使用，请参考项目根目录下的 Dockerfile 或 docker-compose.yml 配置。\n\n## 代理环境配置\n\nAgent Powerups 支持多种编码代理的原生安装，包括 Codex、Claude Code 和 Gemini。不同的代理有不同的目录结构和配置方式。\n\n### 支持的目标代理\n\n| 代理类型 | 安装目标目录 | 配置说明 |\n|----------|--------------|----------|\n| codex | `/skills/` | 技能安装到代理根目录 |\n| claude | `/plugins/` | Claude 插件安装 |\n| claude-code | `/plugins/` | Claude Code 插件安装 |\n| gemini | `/extensions/` | Gemini 扩展安装 |\n\n### Dry-Run 模式\n\n在执行任何实际修改前，强烈建议先使用 dry-run 模式预览安装操作：\n\n```sh\napx setup codex --dry-run\napx setup claude-code --dry-run\napx setup gemini --dry-run\n```\n\n这将显示将要执行的操作而不实际修改文件系统。\n\n### 最小化安装（Bootstrap）\n\n仅安装最基础的资产，适合首次试用或受限环境：\n\n```sh\napx setup codex --mode minimal --yes\napx setup claude-code --mode minimal --yes\napx setup gemini --mode minimal --yes\n```\n\n资料来源：[src/cli/apx.ts:1-100]()\n\n### 推荐安装（Recommended）\n\n安装推荐的技能和插件集合，适合大多数用户：\n\n```sh\napx setup codex --mode recommended --yes\napx setup claude-code --mode recommended --yes\napx setup gemini --mode recommended --yes\n```\n\n### 完整安装（Full）\n\n安装所有可用资产，包括完整的插件包和辅助资源：\n\n```sh\napx setup codex --mode full --yes\napx setup claude-code --mode full --yes\napx setup gemini --mode full --yes\n```\n\n## 手动原生安装\n\n### 基本手动安装\n\n```sh\napx install [--verbose]\n```\n\n### 完整手动安装\n\n```sh\napx install --full [--verbose]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `--verbose` | 显示每个文件的详细安装路径 |\n| `--full` | 同时安装支持资产并更新全局指令 |\n\n默认手动安装行为：\n\n- 根目录 `skills/` → `/skills/`\n- Codex/Claude 插件包 → `/plugins/`\n- Gemini 插件包 → `/extensions/`\n\n资料来源：[README.md:quickstart]()\n\n## 插件包安装\n\nAgent Powerups 采用插件包（Plugin Bundles）架构管理相关技能和配置。\n\n### 插件包状态分类\n\n| 状态 | 数量 | 说明 |\n|------|------|------|\n| Stable（稳定） | 3 个 | 经过充分测试，生产可用 |\n| Beta（测试） | 10 个 | 功能完整，正在收尾稳定性 |\n| Experimental（实验） | 4 个 | 早期功能，可能有变更 |\n\n### 稳定版插件包\n\n- `dev-vitals` - 开发健康指标\n- `debugging-diagnostics` - 调试诊断\n- `quality-gates` - 质量门禁\n\n### 测试版插件包\n\n- `codebase-maintenance`\n- `data-engineering`\n- `documentation-systems`\n- `machine-learning-ops`\n- `codebase-intelligence`\n- `spec-driven-development`\n- `spec-quality-gates`\n- `context-efficiency`\n- `tool-integrations`\n- `memory-optimization`\n\n### 实验版插件包\n\n- `software-engineering`\n- `agentic-systems`\n- `security-guardrails`\n- `agent-evaluation-lab`\n\n### 插件包操作命令\n\n```sh\n# 列出所有插件包\napx plugins list\n\n# 查看插件包详情\napx plugins info dev-vitals\n\n# 验证插件包结构\napx plugins validate --all\n\n# 安装插件包（dry-run）\napx plugins install dev-vitals --target codex --dry-run\n\n# 实际安装插件包\napx plugins install dev-vitals --target codex\n```\n\n资料来源：[README.md:plugin-bundles]()\n\n## MCP 配置安装\n\nMCP（Model Context Protocol）配置用于扩展代理的工具访问能力。\n\n### MCP 配置命令\n\n```sh\n# 列出可用的 MCP 配置\napx mcp list\n\n# 打印 MCP 配置内容\napx mcp print github-local --target claude-code\n\n# 检查 MCP 配置\napx mcp check github-local --target claude-code --json\n\n# 执行 MCP 配置冒烟测试\napx mcp smoke github-local --json\n\n# 安装 MCP 配置\napx mcp install github-local --target codex --dry-run\napx mcp install github-local --target claude-code --dry-run\n```\n\n### 当前已打包的 MCP 配置\n\n- `github-local` - 本地 GitHub MCP 配置，含检查、冒烟测试和显式安装命令\n\n## 目录结构说明\n\n### 标准安装后的目录结构\n\n```\n/\n├── skills/ # 可复用技能目录\n│ ├── systematic-debugging/\n│ ├── writing-plans/\n│ └── ...\n├── plugins/ # 插件包目录（Codex/Claude）\n│ ├── dev-vitals/\n│ └── ...\n├── extensions/ # 扩展目录（Gemini）\n│ └── ...\n├── agent-powerups/ # 资产根目录\n│ ├── skills/ # 完整技能集\n│ ├── commands/ # 命令包\n│ ├── hooks/ # 钩子示例\n│ ├── mcp/ # MCP 配置\n│ └── instructions/ # 指令文件\n└── AGENTS.md / CLAUDE.md # 代理配置文件\n```\n\n资料来源：[examples/minimal/README.md]()\n\n## 验证与检查\n\n### 安装后验证\n\n安装完成后，运行以下命令验证：\n\n```sh\n# 检查 apx 工具状态\napx doctor\n\n# 列出已安装资产\napx list\n\n# 查看特定技能详情\napx info using-powerups\n\n# 检查技能完整性\napx check using-powerups\n\n# 运行安全审计\napx security-audit\n```\n\n### 仓库验证脚本\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\npython scripts/check-requirements.py\n```\n\n### 配置检查\n\n```sh\n# 运行需求检查\napx check \n\n# 安装缺失的依赖\napx check --install-missing --yes\n\n# 查看需求详情\napx check --verbose\n```\n\n资料来源：[src/cli/commands/check.ts]()\n\n## 用户意图配置文件\n\n用户意图配置文件（Profiles）提供预定义的能力组合，适合特定使用场景。\n\n### Profile 操作命令\n\n```sh\n# 列出所有配置文件\napx profiles list\n\n# 查看配置文件详情\napx profiles info safe-core\n```\n\n### 内置配置文件\n\n- `safe-core` - 安全核心配置，包含最基础的技能和检查\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{安装方式选择}\n B -->|npm 全局安装| C[安装 apx CLI]\n B -->|源码构建| D[克隆仓库并构建]\n B -->|Docker| E[使用 Docker 镜像]\n \n C --> F{目标代理选择}\n D --> F\n E --> F\n \n F -->|Codex| G[apx install codex]\n F -->|Claude Code| H[apx install claude-code]\n F -->|Gemini| I[apx install gemini]\n \n G --> J[选择安装模式]\n H --> J\n I --> J\n \n J -->|minimal| K[Bootstrap 基础安装]\n J -->|recommended| L[推荐安装]\n J -->|full| M[完整安装]\n \n K --> N[安装后验证]\n L --> N\n M --> N\n \n N --> O{验证通过?}\n O -->|是| P[安装完成]\n O -->|否| Q[诊断问题]\n Q --> N\n```\n\n## 安全注意事项\n\n在安装 Agent Powerups 时，请注意以下安全边界：\n\n### 审查后再加载\n\n> **警告**：在将资产加载到受信任的代理环境前，请务必审查资产内容。\n\n- 技能可能指示代理读取本地文件或运行命令\n- 钩子可以在代理支持时执行代码\n- MCP 配置可能扩展工具访问范围\n- 安装命令可能修改本地环境\n- 切勿将密钥粘贴到代理上下文中\n\n### 安全审计命令\n\n```sh\napx security-audit\n```\n\n此命令会扫描以下高风险模式：\n\n| 检查项 | 严重级别 | 说明 |\n|--------|----------|------|\n| `unpinned-latest-image` | P1 | CI 配置中使用未固定版本的 :latest 镜像 |\n| `broad-filesystem-write` | P1 | 宽泛的文件系统写入或递归删除模式 |\n| `missing-dry-run` | P1 | 安装命令缺少 --dry-run 保护 |\n\n资料来源：[src/cli/commands/security-audit.ts]()\n\n## 故障排除\n\n### 常见问题\n\n**Q: apx 命令未找到**\n```sh\nnpm install -g agent-powerups\n# 或\nnpm link # 如果从源码安装\n```\n\n**Q: 安装后代理无法识别技能**\n检查代理根目录下是否正确创建了 skills/ 目录，并确认 AGENTS.md 中包含了 agent-powerups 指令块。\n\n**Q: MCP 配置安装失败**\n```sh\napx mcp check github-local --target --json\napx mcp smoke github-local --json\n```\n\n### 完整回滚\n\n如需完全移除安装的资产：\n\n```sh\n# 对于 Codex\nRemove-Item \\agent-powerups -Recurse -Force\n\n# 对于 Claude Code\nRemove-Item \\agent-powerups -Recurse -Force\n```\n\n资料来源：[examples/minimal/README.md]()\n\n## 相关资源\n\n- [快速开始指南](./README.md#quickstart)\n- [安全模型说明](./docs/security-model.md)\n- [兼容性矩阵](./docs/compatibility.md)\n- [贡献指南](./CONTRIBUTING.md)\n- [API 文档](../src/cli/apx.ts)\n\n---\n\n\n\n## apx CLI 参考\n\n### 相关页面\n\n相关主题：[安装指南](#installation), [资产目录系统](#catalog-system), [插件包系统](#plugin-bundles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n- [src/cli/commands/setup.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/setup.ts)\n- [src/cli/commands/security-audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/security-audit.ts)\n- [src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n- [src/cli/commands/phase-workflows.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/phase-workflows.ts)\n- [src/cli/utils/requirements.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/utils/requirements.ts)\n \n\n# apx CLI 参考\n\n## 概述\n\n`apx` 是 agent-powerups 项目的核心命令行工具，提供类似 Oh My Zsh 的体验，为编码代理（coding agents）提供可复用的技能、命令、工作流和配置管理能力。该工具以 TypeScript 开发，通过 npm 包发布，旨在标准化和简化各类编码代理的环境配置与日常操作。\n\n`apx` 的设计理念强调**本地优先（local-first）**、**安全审计（security-first）**和**渐进式配置（progressive setup）**，支持干运行（dry-run）、交互式确认和幂等操作。\n\n## 核心功能模块\n\n| 模块 | 功能描述 | 典型场景 |\n|------|----------|----------|\n| `install` | 安装技能和插件到指定代理根目录 | 快速部署一套完整的开发环境 |\n| `setup` | 代理托管式配置，支持多模式 | 引导式安装，适合不熟悉命令行的用户 |\n| `mcp` | MCP 服务器配置管理 | GitHub MCP 的本地检查、烟雾测试和安装 |\n| `agents-md` | AGENTS.md 模板管理 | 初始化新项目的代理指令模板 |\n| `commands` | 命令包管理和执行 | 自动化代码审查和发布检查 |\n| `hooks` | 钩子脚本管理 | 代码提交前的安全预检 |\n| `workflows` | 工作流编排 | 自动化项目迭代和部署流程 |\n| `plugins` | 插件包管理 | 安装和管理第三方扩展插件 |\n| `profiles` | 用户意图配置集 | 预定义的安全核心配置组合 |\n| `check` | 依赖检查 | 验证技能所需工具是否满足 |\n| `ask-*` | 多代理咨询 | 向 Codex/Claude/Gemini 发送请求 |\n| `relay` | 持久化中继会话 | 跨轮次保持上下文状态 |\n| `security-audit` | 安全审计 | 扫描代码库中的安全隐患 |\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[\"用户终端\"] --> B[\"apx CLI 入口
src/cli/apx.ts\"]\n B --> C{\"命令路由\"}\n C --> D[\"install\"]\n C --> E[\"setup\"]\n C --> F[\"mcp\"]\n C --> G[\"check\"]\n C --> H[\"ask-*\"]\n C --> I[\"relay\"]\n C --> J[\"plugins\"]\n C --> K[\"profiles\"]\n \n D --> L[\"技能安装逻辑\"]\n E --> M[\"setup.ts
代理托管式安装\"]\n F --> N[\"MCP 配置管理\"]\n G --> O[\"requirements.ts
依赖检查\"]\n H --> P[\"外部代理 API\"]\n I --> Q[\"持久会话状态\"]\n J --> R[\"插件bundles\"]\n K --> S[\"用户意图配置\"]\n \n L --> T[\"目标代理根目录
codex / claude-code / gemini\"]\n M --> T\n N --> U[\"github-local MCP\"]\n O --> V[\"npm / pip / cargo
依赖解析\"]\n```\n\n## 命令速查表\n\n### 安装与配置\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx install ` | 安装到指定代理 | `--dry-run`, `--full`, `--verbose`, `--agent-root` |\n| `apx install --target ` | 安装单个资产 | `--dry-run`, `--dest` |\n| `apx setup --mode ` | 代理托管式配置 | `--mode minimal\\|recommended\\|full`, `--dry-run`, `--yes` |\n| `apx mcp install --target ` | 安装 MCP 配置 | `--dry-run`, `--yes`, `--dest` |\n\n### 查询与列表\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx list` | 列出所有可用技能 | - |\n| `apx info ` | 查看技能详情 | - |\n| `apx check ` | 检查技能依赖 | `--install-missing`, `--dry-run` |\n| `apx mcp list` | 列出 MCP 配置 | - |\n| `apx agents-md list` | 列出 AGENTS.md 模板 | - |\n| `apx commands list` | 列出命令包 | - |\n| `apx hooks list` | 列出钩子 | - |\n| `apx workflows list` | 列出工作流 | - |\n| `apx plugins list` | 列出插件包 | - |\n| `apx profiles list` | 列出配置集 | - |\n\n### 执行与操作\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx ask-codex \"\"` | 询问 Codex | `--json` |\n| `apx ask-claude \"\"` | 询问 Claude | `--json` |\n| `apx ask-gemini \"\"` | 询问 Gemini | `--json` |\n| `apx relay init ` | 初始化中继会话 | - |\n| `apx relay start --provider ` | 启动中继 | `--json` |\n| `apx relay ask \"\"` | 通过中继询问 | `--json` |\n| `apx commands run ship-check` | 运行发货检查 | `--full`, `--json` |\n| `apx hooks run no-secrets-preflight` | 运行无密钥预检 | `--path`, `--all`, `--json` |\n| `apx phase ` | 阶段式工作流 | `discuss`, `plan`, `execute`, `verify` |\n\n### 验证与审计\n\n| 命令 | 说明 | 关键参数 |\n|------|------|----------|\n| `apx doctor` | 诊断 apx 自身状态 | `--full`, `--json` |\n| `apx mcp check ` | 检查 MCP 配置 | `--target`, `--json` |\n| `apx mcp smoke ` | 烟雾测试 MCP | `--json` |\n| `apx security-audit --path ` | 安全审计 | `--all`, `--json` |\n| `apx audit repo` | 仓库审计 | `--json` |\n| `apx plugin validate ` | 验证插件 | `--json` |\n\n## 详细命令说明\n\n### install - 资产安装\n\n`install` 命令是 apx 的核心命令之一，用于将技能、插件和配置安装到指定代理的根目录。\n\n```mermaid\ngraph LR\n A[\"输入: apx install codex\"] --> B[\"解析 --target 参数\"]\n B --> C{\"INSTALL_TARGETS 检查\"}\n C -->|通过| D[\"定位代理根目录\"]\n C -->|失败| E[\"抛出错误\"]\n D --> F[\"复制 skills/ 到目标\"]\n F --> G[\"复制 plugins/ 到目标\"]\n G --> H[\"可选: 复制 agent-powerups/ 资源\"]\n H --> I[\"完成\"]\n```\n\n**安装模式对比：**\n\n| 模式 | 说明 | 适用范围 |\n|------|------|----------|\n| 默认安装 | 仅复制 skills 和 plugins bundles | 常规使用 |\n| `--full` | 完整安装，包含 support assets 和全局指令更新 | 深度集成 |\n| `--verbose` | 显示每个文件的复制路径 | 调试排查 |\n\n**命令示例：**\n\n```bash\n# 干运行查看安装计划\napx install codex --dry-run\n\n# 完整安装到 Codex\napx install codex --full --verbose\n\n# 安装单个技能到 Claude Code\napx install markitdown-file-intake --target claude-code --dry-run\n\n# 指定自定义代理根目录\napx install gemini --agent-root ~/.config/agent/gemini\n```\n\n资料来源：[src/cli/apx.ts:45-80]()\n\n### setup - 代理托管式配置\n\n`setup` 命令提供引导式配置体验，支持三种预设模式，自动生成配置指令。\n\n```mermaid\ngraph TD\n A[\"apx setup \"] --> B{\"模式选择\"}\n B -->|\"minimal\"| C[\"bootstrap 模式\"]\n B -->|\"recommended\"| D[\"推荐模式\"]\n B -->|\"full\"| E[\"完整模式\"]\n \n C --> F[\"生成基础 AGENTS.md 块\"]\n D --> G[\"生成技能 + 插件说明\"]\n E --> H[\"生成全量功能说明\"]\n \n F --> I{\"目标文件存在?\"}\n G --> I\n H --> I\n \n I -->|存在| J[\"追加到现有文件
备份 .bak\"]\n I -->|不存在| K[\"创建 agent-powerups.md\"]\n J --> L[\"完成\"]\n K --> L\n```\n\n**配置模式说明：**\n\n| 模式 | 内容 | 推荐场景 |\n|------|------|----------|\n| `minimal` | 引导用户读取 using-powerups、apx 使用说明、MCP 审批提示 | 新用户快速体验 |\n| `recommended` | minimal + 技能路径说明 + 推荐命令提示 | 大多数用户的推荐选择 |\n| `full` | 全功能说明和最佳实践 | 深度用户和自动化场景 |\n\n资料来源：[src/cli/commands/setup.ts:50-100]()\n\n### mcp - MCP 服务器配置\n\nMCP（Model Context Protocol）配置管理提供本地 GitHub MCP 的检查、烟雾测试和安装能力。\n\n| 子命令 | 功能 |\n|--------|------|\n| `apx mcp list` | 列出可用 MCP 配置 |\n| `apx mcp print --target ` | 打印配置详情 |\n| `apx mcp check --target ` | 验证配置有效性 |\n| `apx mcp smoke ` | 执行烟雾测试 |\n| `apx mcp install --target ` | 安装到目标代理 |\n| `apx mcp write --target --dest ` | 导出配置到指定路径 |\n\n**工作流程：**\n\n```mermaid\ngraph LR\n A[\"mcp check\"] --> B{\"配置有效?\"}\n B -->|是| C[\"mcp smoke\"]\n B -->|否| D[\"报告错误\"]\n C --> E{\"烟雾测试通过?\"}\n E -->|是| F[\"mcp install\"]\n E -->|否| G[\"报告问题\"]\n F --> H[\"完成\"]\n```\n\n### check - 依赖检查\n\n`check` 命令验证技能所需工具是否已安装，支持自动安装缺失依赖。\n\n```mermaid\ngraph TD\n A[\"apx check \"] --> B[\"加载技能定义\"]\n B --> C[\"解析 requires 字段\"]\n C --> D[\"检测系统工具\"]\n D --> E{\"所有依赖满足?\"}\n E -->|是| F[\"输出 OK 状态\"]\n E -->|否| G{\"--install-missing?\"}\n G -->|是| H[\"调用 requirements.ts\"]\n G -->|否| I[\"输出 MISSING 状态\"]\n H --> J{\"有支持的安装器?\"}\n J -->|是| K[\"显示安装命令预览\"]\n J -->|否| L[\"提示手动安装\"]\n K --> M{\"--dry-run?\"}\n M -->|是| N[\"仅显示计划\"]\n M -->|否| O[\"执行安装\"]\n```\n\n**依赖解析逻辑：**\n\n`requirements.ts` 中的 `installMissingRequirements` 函数负责解析缺失依赖，并调用对应的包管理器：\n\n| 包管理器 | 探测命令 | 参数 |\n|----------|----------|------|\n| npm | `npm install` | `-g` 全局或本地 |\n| pip | `pip install` | `-q` 静默模式 |\n| cargo | `cargo install` | - |\n| gem | `gem install` | `-N` 不生成文档 |\n\n资料来源：[src/cli/commands/check.ts:30-80]()\n\n资料来源：[src/cli/utils/requirements.ts:1-60]()\n\n### ask-* - 多代理咨询\n\n`ask-*` 命令提供统一的接口向外部编码代理发送请求：\n\n| 命令 | 代理 | 输出格式 |\n|------|------|----------|\n| `apx ask-codex` | OpenAI Codex | JSON 或文本 |\n| `apx ask-claude` | Anthropic Claude | JSON 或文本 |\n| `apx ask-gemini` | Google Gemini | JSON 或文本 |\n\n**使用场景：**\n\n```bash\n# 询问代码解释\napx ask-codex \"Explain this code\" --json\n\n# 代码审查\napx ask-claude \"Review this patch\" --json\n\n# 头脑风暴测试用例\napx ask-gemini \"Brainstorm test cases\" --json\n```\n\n### relay - 持久中继会话\n\n`relay` 命令维护跨轮次的持久会话，保持上下文状态，特别适合需要多轮协作的场景。\n\n```mermaid\ngraph TD\n A[\"relay init \"] --> B[\"创建会话状态\"]\n B --> C[\"relay start --provider \"]\n C --> D[\"建立持久连接\"]\n D --> E[\"relay ask ''\"]\n E --> F[\"发送消息\"]\n F --> G[\"接收响应\"]\n G --> H{\"需要继续?\"}\n H -->|是| E\n H -->|否| I[\"relay stop \"]\n```\n\n**中继会话管理：**\n\n| 子命令 | 说明 |\n|--------|------|\n| `relay init ` | 初始化新会话 |\n| `relay start --provider ` | 启动会话 |\n| `relay ask \"\"` | 发送消息 |\n| `relay status ` | 查看状态 |\n| `relay stop ` | 停止会话 |\n\n### security-audit - 安全审计\n\n`security-audit` 命令扫描代码库中的常见安全风险，包括硬编码密钥、不安全的 shell 命令和不推荐的镜像标签。\n\n**支持的检测规则：**\n\n| 规则名称 | 严重级别 | 检测模式 |\n|----------|----------|----------|\n| `api-key-detected` | P0 | 常见 API 密钥格式 |\n| `private-key-detected` | P0 | RSA/ED25519 私钥 |\n| `aws-access-key` | P0 | AWS 访问密钥 |\n| `aws-secret-key` | P0 | AWS 密钥 ID |\n| `github-token` | P0 | GitHub Token |\n| `broad-filesystem-write` | P1 | 递归删除或通配符写 |\n| `missing-dry-run` | P1 | 安装命令缺少 --dry-run |\n\n**扫描范围：**\n\n- 文件扩展白名单：`.json`, `.toml`, `.md`, `.sh`, `.ps1`, `.yaml`, `.yml`\n- 跳过目录：`node_modules`, `dist`, `.git`, `.worktrees`, `.plugins`\n- 最大文件大小：512 KB\n\n资料来源：[src/cli/commands/security-audit.ts:1-50]()\n\n### phase - 阶段式工作流\n\n`phase` 命令实现项目开发的阶段化工作流，支持讨论、计划、执行和验证阶段。\n\n```mermaid\ngraph LR\n A[\"phase discuss\"] --> B[\"需求澄清\"]\n B --> C[\"phase plan\"]\n C --> D[\"PRD 生成\"]\n C --> E[\"MVP 规划\"]\n D --> F[\"phase execute\"]\n E --> F\n F --> G[\"按 wave 执行\"]\n G --> H[\"phase verify\"]\n H --> I{\"验证通过?\"}\n I -->|否| G\n I -->|是| J[\"完成\"]\n```\n\n**阶段子命令：**\n\n| 子命令 | 说明 | 关键参数 |\n|--------|------|----------|\n| `phase discuss ` | 讨论指定阶段 | `--planning-root`, `--json` |\n| `phase plan ` | 制定计划 | `--research`, `--prd`, `--mvp` |\n| `phase execute ` | 执行计划 | `--wave`, `--interactive` |\n| `phase verify ` | 验证结果 | - |\n\n资料来源：[src/cli/commands/phase-workflows.ts:1-40]()\n\n## 代理目标\n\napx 支持多个编码代理平台作为安装目标：\n\n| 目标标识 | 代理产品 | 配置目录 |\n|----------|----------|----------|\n| `codex` | OpenAI Codex | `~/.codex/` |\n| `claude-code` | Claude Code | `~/.claude/` |\n| `gemini` | Google Gemini CLI | `~/.gemini/` |\n| `generic` | 通用目标 | 用户指定 |\n\n安装时通过 `--target ` 参数指定目标，未指定时使用对应代理的默认配置目录。\n\n## 输出格式\n\n大多数 apx 命令支持 JSON 输出，便于脚本集成和自动化处理：\n\n```bash\n# 获取 JSON 格式输出\napx list --json\napx check markitdown-file-intake --json\napx security-audit --all --json\n\n# 干运行模式\napx install codex --dry-run\n```\n\n## 错误处理与安全\n\n### 幂等性保证\n\napx 命令设计为幂等操作：\n\n- `install` 重复执行不会重复复制已存在文件\n- `setup` 在 AGENTS.md 存在时会创建备份 `.bak`\n- `--dry-run` 选项允许预览行为而不实际修改\n\n### 安全边界\n\napx 在以下方面保持安全边界：\n\n- **外部工具**：需要用户显式批准安装\n- **密钥**：内置 `no-secrets-preflight` 钩子检测\n- **Shell 配置**：不自动修改 shell 启动文件\n- **MCP 服务器**：需要显式启用确认\n\n### 诊断工具\n\n```bash\n# 基础诊断\napx doctor\n\n# 完整诊断（JSON）\napx doctor --full --json\n\n# 仓库审计\napx audit repo --json\n```\n\n## 快速参考\n\n### 首次使用\n\n```bash\nnpm install\nnpm run build\nnpm link\napx doctor\napx list\n```\n\n### 常见工作流\n\n**部署到 Codex：**\n\n```bash\napx setup codex --mode recommended --yes\n```\n\n**检查技能依赖：**\n\n```bash\napx check markitdown-file-intake\napx check defuddle --install-missing --dry-run\n```\n\n**运行安全扫描：**\n\n```bash\napx security-audit --path ./src\napx hooks run no-secrets-preflight --all\n```\n\n**多代理咨询：**\n\n```bash\napx ask-claude \"Review this PR\" --json\napx relay start second-opinion --provider gemini\napx relay ask second-opinion \"Analyze this architecture\" --json\n\n---\n\n\n\n## 资产目录系统\n\n### 相关页面\n\n相关主题：[技能系统](#skills), [apx CLI 参考](#cli-reference), [插件包系统](#plugin-bundles)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n- [catalog.json](https://github.com/yeaight7/agent-powerups/blob/main/catalog.json)\n- [docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)\n- [scripts/validate-skills.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-skills.py)\n- [scripts/validate-catalog.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-catalog.py)\n- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)\n \n\n# 资产目录系统\n\n## 概述\n\nAgent Powerups 的资产目录系统是一个集中管理、可验证的资产清单，涵盖可复用的技能、工作流、命令模板、MCP 配置和 AGENTS.md 模板。该系统采用声明式 JSON 格式定义所有资产元数据，并通过自动化验证脚本确保目录内容的完整性和一致性。资产目录的核心价值在于为编码代理提供\"Oh My Zsh 风格\"的可插拔组件库，开发者可以通过 `apx` CLI 工具浏览、安装和验证这些资产。\n\n## 目录架构\n\n资产目录采用分层架构设计，将不同类型的资产分别归类管理：\n\n```mermaid\ngraph TD\n A[agent-powerups 仓库] --> B[根级资产目录]\n A --> C[插件包 bundle]\n B --> D[skills/ 技能目录]\n B --> E[mcp/ MCP配置]\n B --> F[agents-md/ 模板]\n B --> G[commands/ 命令集]\n B --> H[hooks/ 钩子示例]\n B --> I[workflows/ 工作流]\n C --> J[17个插件包]\n C --> K[技能 + 代理 + 命令组合]\n```\n\n目录结构与资产类型的对应关系如下：\n\n| 路径 | 状态 | 说明 |\n|------|------|------|\n| `skills/` | 已发布 | 可复用代理工作流，如 `systematic-debugging`、`writing-plans` |\n| `mcp/` | 已发布 | 本地优先 GitHub MCP 配置，含检查、冒烟测试和显式安装命令 |\n| `agents-md/` | 已发布 | 启动器 AGENTS.md 模板 |\n| `commands/` | 已发布 | 审查优先命令提示词及安全可运行检查 |\n| `hooks/` | 已发布 | 钩子示例：preflight、summary、validation |\n| `workflows/` | 已发布 | 工作流定义：feature-iteration、agent-relay |\n| `plugins/` | 已发布 | 17个插件包（3个稳定版、10个测试版、4个实验版） |\n\n## 目录清单结构\n\n### 技能资产 (Skills)\n\n当前已发布的技能共 23 个，涵盖调试、规划、代码审查、数据工程等多个领域：\n\n| 技能名称 | 功能分类 |\n|----------|----------|\n| `systematic-debugging` | 调试 |\n| `no-fluff` | 文档 |\n| `writing-plans` | 规划 |\n| `ai-slop-cleaner` | 文档 |\n| `bigquery-cost-audit` | 数据工程 |\n| `data-quality` | 数据工程 |\n| `dbt-incremental-strategy-audit` | 数据工程 |\n| `dbt-preflight` | 数据工程 |\n| `dbt-strategy` | 数据工程 |\n| `metric-impact-analyzer` | 分析 |\n| `requesting-code-review` | 协作 |\n| `receiving-code-review` | 协作 |\n| `pr-triage` | 协作 |\n| `repo-map` | 导航 |\n| `bug-hunt` | 调试 |\n| `safe-refactor` | 重构 |\n| `sql-business-logic-review` | 审查 |\n| `defuddle` | 工具 |\n| `markitdown-file-intake` | 工具 |\n| `graphify` | 可视化 |\n| `ask-claude` | 集成 |\n| `ask-gemini` | 集成 |\n| `ask-codex` | 集成 |\n| `using-powerups` | 入门 |\n\n资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n### 插件包资产 (Plugin Bundles)\n\n插件包是技能、代理和命令的组合，按成熟度分为三个等级：\n\n#### 稳定版插件包 (Stable)\n\n| 插件包名称 | 描述 |\n|------------|------|\n| `dev-vitals` | 开发健康指标 |\n| `debugging-diagnostics` | 调试诊断 |\n| `quality-gates` | 质量门禁 |\n\n#### 测试版插件包 (Beta)\n\n| 插件包名称 | 描述 |\n|------------|------|\n| `codebase-maintenance` | 代码库维护 |\n| `data-engineering` | 数据工程 |\n| `documentation-systems` | 文档系统 |\n| `machine-learning-ops` | 机器学习运维 |\n| `codebase-intelligence` | 代码库智能 |\n| `spec-driven-development` | 规范驱动开发 |\n| `spec-quality-gates` | 对抗性计划验证和结构化代码审查 |\n| `context-efficiency` | 上下文高效调度路由 |\n| `tool-integrations` | 工具集成 |\n| `memory-optimization` | 内存优化 |\n\n#### 实验版插件包 (Experimental)\n\n| 插件包名称 | 描述 |\n|------------|------|\n| `software-engineering` | 软件工程 |\n| `agentic-systems` | 代理系统 |\n| `security-guardrails` | 安全护栏 |\n| `agent-evaluation-lab` | 代理评估实验室 |\n\n每个插件遵循标准编码代理插件布局：\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code 清单\n├── .codex-plugin/\n│ └── plugin.json # Codex 清单\n├── skills/\n│ └── /\n│ └── SKILL.md\n├── agents/\n│ └── .md\n└── commands/\n └── .md\n```\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n### AGENTS.md 模板资产\n\n| 模板名称 | 适用场景 |\n|----------|----------|\n| `typescript-app` | TypeScript 应用开发 |\n| `python-library` | Python 库开发 |\n| `dbt-project` | dbt 数据转换项目 |\n| `ml-project` | 机器学习项目 |\n| `open-source-maintainer` | 开源项目维护 |\n\n### 命令资产 (Commands)\n\n| 命令包名称 | 功能 |\n|------------|------|\n| `ship-check` | 发布前检查 |\n| `using-powerups-command` | Powerups 使用指导 |\n\n### 钩子示例资产 (Hooks)\n\n| 钩子名称 | 触发场景 |\n|----------|----------|\n| `no-secrets-preflight` | 提交前秘密检查 |\n| `handoff-summary` | 交接摘要生成 |\n| `validation-required` | 验证必需触发 |\n\n### 工作流资产 (Workflows)\n\n| 工作流名称 | 用途 |\n|------------|------|\n| `feature-iteration` | 功能迭代流程 |\n| `agent-relay` | 代理中继通信 |\n\n### MCP 配置资产\n\n| 配置名称 | 说明 |\n|----------|------|\n| `github-local` | 本地 GitHub MCP 配置，含检查、冒烟测试和显式安装命令 |\n\n## 目录验证机制\n\n### 验证脚本体系\n\n项目包含三个核心验证脚本，确保目录内容的有效性：\n\n```mermaid\ngraph LR\n A[validate-skills.py] --> B[技能元数据检查]\n A --> C[SKILL.md 存在性]\n A --> D[支持文件引用]\n \n E[validate-catalog.py] --> F[catalog.json 格式]\n E --> G[资产完整性]\n E --> H[引用有效性]\n \n I[check-requirements.py] --> J[依赖检查]\n J --> K[可选自动安装]\n```\n\n#### 技能验证脚本 (validate-skills.py)\n\n`validate-skills.py` 负责验证所有技能资产的结构完整性：\n\n- 检查每个技能目录下是否存在 `SKILL.md` 文件\n- 验证 frontmatter 中是否包含 `name` 和 `description` 必需字段\n- 检查技能内容长度是否满足最小要求\n- 验证支持文件的引用是否指向实际存在的文件\n\n```sh\npython scripts/validate-skills.py\n```\n\n资料来源：[scripts/validate-skills.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-skills.py)\n\n#### 目录验证脚本 (validate-catalog.py)\n\n`validate-catalog.py` 验证整个目录清单的正确性：\n\n- 验证 `catalog.json` 格式是否符合 schema\n- 确保所有声明的资产在文件系统中实际存在\n- 检查资产引用的完整性\n\n```sh\npython scripts/validate-catalog.py\n```\n\n资料来源：[scripts/validate-catalog.py](https://github.com/yeaight7/agent-powerups/blob/main/scripts/validate-catalog.py)\n\n#### 依赖检查脚本 (check-requirements.py)\n\n`check-requirements.py` 检查运行技能所需的依赖项：\n\n- 识别缺失的外部依赖\n- 提供安装提示（`installHint`）\n- 支持自动安装可用的依赖\n\n```sh\npython scripts/check-requirements.py\n```\n\n资料来源：[src/cli/commands/check.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/check.ts)\n\n### 验证检查项\n\n| 检查项 | 描述 | 状态码 |\n|--------|------|--------|\n| `skill-files` | SKILL.md 文件存在性 | OK/WARNING |\n| `skill-frontmatter` | 必需 frontmatter 字段 | OK/WARNING |\n| `skill-content-length` | 内容长度最小值 | WARN/OK |\n| `catalog-schema` | catalog.json schema 符合性 | PASS/FAIL |\n| `asset-existence` | 资产文件实际存在 | PASS/FAIL |\n\n## CLI 命令集成\n\n### 目录浏览命令\n\n| 命令 | 功能 |\n|------|------|\n| `apx list` | 列出所有可用资产 |\n| `apx info ` | 显示资产详细信息 |\n| `apx check ` | 检查资产完整性 |\n| `apx commands run ` | 运行指定命令 |\n\n```sh\n# 浏览目录\napx list\n\n# 查看特定技能\napx info markitdown-file-intake\n\n# 运行命令检查\napx commands run ship-check\n\n# 运行钩子检查\napx hooks run no-secrets-preflight --all\n\n# MCP 配置检查\napx mcp check github-local --target generic\napx mcp smoke github-local --json\n```\n\n### 插件管理命令\n\n| 命令 | 功能 |\n|------|------|\n| `apx plugins list` | 列出所有插件包 |\n| `apx plugins info ` | 显示插件详情 |\n| `apx plugins validate --all` | 验证所有插件结构 |\n| `apx plugins install --target ` | 安装插件 |\n\n```sh\napx plugins list\napx plugins info dev-vitals\napx plugins validate --all\napx plugins install dev-vitals --target codex --dry-run\n```\n\n### 审计命令\n\n`apx audit` 命令提供系统性的资产审计功能：\n\n```sh\napx audit skills\napx audit plugins\n```\n\n审计输出格式：\n\n```\naudit skills: 5 pass, 2 warn, 0 fail\n[OK] skill-frontmatter: all have name + description\n[WARN] skill-content-length: 2 skill(s) under 500 chars\n```\n\n## 目录模式 (Catalog Schema)\n\n目录采用 JSON Schema 定义资产元数据规范，核心字段包括：\n\n```json\n{\n \"name\": \"资产名称\",\n \"description\": \"资产描述\",\n \"path\": \"相对于仓库根的路径\",\n \"maturity\": \"stable|beta|experimental\",\n \"tags\": [\"标签1\", \"标签2\"],\n \"requires\": {\n \"skills\": [\"依赖技能\"],\n \"tools\": [\"依赖工具\"]\n }\n}\n```\n\n资料来源：[docs/catalog-schema.md](https://github.com/yeaight7/agent-powerups/blob/main/docs/catalog-schema.md)\n\n## 安全考量\n\n资产目录系统内置多层安全保护机制：\n\n### 部署前检查\n\n- 技能可指导代理读取本地文件或执行命令\n- 钩子可在宿主代理支持时执行代码\n- MCP 配置可扩展工具访问范围\n- 安装命令可修改本地环境\n\n### 安装保护\n\n所有安装操作默认处于干运行模式，需要显式授权才能执行：\n\n```sh\napx install codex --dry-run # 预览不执行\napx install codex # 实际执行\n```\n\n### 秘密管理\n\n- 秘密绝不应粘贴到代理上下文，除非严格必要\n- MCP 服务器需要显式用户批准\n- 外部工具安装需要用户批准\n\n## 与代理的集成\n\n### 代理兼容性矩阵\n\n| 资产类别 | 当前状态 | 兼容性声明 |\n|----------|----------|------------|\n| 根 `skills/` | 是 | 通用文本技能；部分提及已知代理表面 |\n| `mcp/` | 是 | 提供特定代理的 MCP 配置 |\n\n资料来源：[README.md](https://github.com/yeaight7/agent-powerups/blob/main/README.md)\n\n### 支持的代理平台\n\n| 代理平台 | 配置路径 | 说明 |\n|----------|----------|------|\n| Codex | `.codex-plugin/plugin.json` | Codex 清单定义 |\n| Claude Code | `.claude-plugin/plugin.json` | Claude Code 清单定义 |\n| Gemini | `gemini-extension.json` + `GEMINI.md` | Gemini 插件包 |\n\n## 维护工作流\n\n仓库维护应持续运行验证检查：\n\n```mermaid\ngraph TD\n A[修改资产文件] --> B[运行 validate-skills.py]\n B --> C{检查通过?}\n C -->|是| D[运行 validate-catalog.py]\n C -->|否| E[修复问题]\n E --> B\n D --> F{检查通过?}\n F -->|是| G[运行 check-requirements.py]\n F -->|否| H[修复问题]\n H --> D\n G --> I[提交更改]\n```\n\n建议的维护命令序列：\n\n```sh\npython scripts/validate-skills.py\npython scripts/validate-catalog.py\npython scripts/check-requirements.py\n```\n\n## 总结\n\n资产目录系统是 Agent Powerups 的核心基础设施，提供了一套完整、可验证的资产管理体系。通过声明式清单、自动化验证和 CLI 工具集成，开发者可以安全地发现、安装和使用预构建的代理资源。该系统支持多代理平台（Codex、Claude Code、Gemini），并通过插件包机制实现了资产的分层组织和按需扩展。\n\n---\n\n\n\n## 插件包系统\n\n### 相关页面\n\n相关主题：[资产目录系统](#catalog-system), [apx CLI 参考](#cli-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n- [plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)\n- [.claude-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.claude-plugin/marketplace.json)\n- [.codex-plugin/marketplace.json](https://github.com/yeaight7/agent-powerups/blob/main/.codex-plugin/marketplace.json)\n- [docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)\n \n\n# 插件包系统\n\n## 概述\n\n插件包系统（Plugin Bundle System）是 Agent Powerups 项目中用于组织、发布和分发功能模块的核心机制。该系统借鉴了 \"Oh My Zsh\" 的插件管理模式，将相关的 skills（技能）、agents（代理模板）、commands（命令）和 templates（模板）打包成独立的插件单元，支持多 agent 平台的安装与同步。\n\n插件包系统的主要职责包括：\n\n- **模块化封装**：将功能资源按领域分类，形成可独立管理的插件单元\n- **跨平台兼容**：通过统一的 manifest 定义，支持 Codex、Claude Code、Gemini 等多种 coding agent\n- **生命周期管理**：通过成熟度等级（maturity）区分实验性功能和稳定功能\n- **标准化安装**：提供 `apx` CLI 工具实现插件的发现、验证和安装\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## 插件包结构\n\n### 目录布局\n\n每个插件遵循标准的 coding agent 插件目录结构：\n\n```\n/\n├── .claude-plugin/\n│ └── plugin.json # Claude Code 平台清单\n├── .codex-plugin/\n│ └── plugin.json # Codex 平台清单\n├── skills/\n│ └── /\n│ └── SKILL.md # 技能定义文件\n├── agents/\n│ └── .md # 代理模板文件\n└── commands/\n └── .md # 命令定义文件\n```\n\n根级别的 skills 位于 `skills/` 目录，是通用型独立技能。插件内的 skills 是领域专用的，提供更深入的功能覆盖。同一主题的插件技能不得替代或覆盖根级别技能。\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n### Manifest 文件\n\n每个插件包含针对不同 agent 平台的 manifest 文件，定义了插件的元数据和资源引用。\n\n**Claude Code Manifest 示例结构：**\n\n```json\n{\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"maturity\": \"stable\",\n \"skills\": [\n { \"name\": \"dev-vitals-check\", \"path\": \"skills/dev-vitals-check\" }\n ],\n \"commands\": [\n { \"name\": \"dev-vitals\", \"path\": \"commands/dev-vitals.md\" }\n ]\n}\n```\n\n**Codex Manifest 示例结构：**\n\n```json\n{\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"maturity\": \"stable\",\n \"skills\": [\"skills/dev-vitals-check\"],\n \"commands\": [\"commands/dev-vitals.md\"]\n}\n```\n\n两个平台的 manifest 格式略有差异：Codex 版本使用字符串路径数组，Claude Code 版本使用对象数组（包含 name 和 path 属性）。\n\n## 成熟度等级\n\n插件包根据功能稳定性和适用场景分为三个成熟度等级：\n\n| 等级 | 说明 | 风险级别 | 适用场景 |\n|------|------|----------|----------|\n| **stable** | 稳定版本，经过充分测试 | 低 | 生产环境推荐使用 |\n| **beta** | 测试版本，功能基本可用 | 中 | 评估新功能，探索性项目 |\n| **experimental** | 实验性版本，可能有破坏性变更 | 高 | 高级用户尝鲜，不建议生产使用 |\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## 插件包清单\n\n当前仓库包含 17 个插件包，分布如下：\n\n### 稳定版插件（Stable）\n\n| 插件名称 | 描述 | Maturity |\n|----------|------|----------|\n| `dev-vitals` | 开发健康指标与监控 | stable |\n| `debugging-diagnostics` | 调试与诊断技能集 | stable |\n| `quality-gates` | 质量门禁检查流程 | stable |\n\n### Beta 版插件\n\n| 插件名称 | 描述 | Maturity |\n|----------|------|----------|\n| `codebase-maintenance` | 代码库维护任务集 | beta |\n| `data-engineering` | 数据工程相关技能 | beta |\n| `documentation-systems` | 文档系统生成与管理 | beta |\n| `machine-learning-ops` | ML 运维工作流 | beta |\n| `codebase-intelligence` | 代码库智能分析 | beta |\n| `spec-driven-development` | 规范驱动的开发流程 | beta |\n| `spec-quality-gates` | 对抗性计划验证与结构化代码审查 | beta |\n| `context-efficiency` | 上下文高效的调度路由 | beta |\n| `tool-integrations` | 工具集成扩展 | beta |\n| `memory-optimization` | 内存优化策略 | beta |\n\n### 实验版插件（Experimental）\n\n| 插件名称 | 描述 | Maturity |\n|----------|------|----------|\n| `software-engineering` | 软件工程最佳实践 | experimental |\n| `agentic-systems` | 代理系统设计模式 | experimental |\n| `security-guardrails` | 安全防护机制 | experimental |\n| `agent-evaluation-lab` | 代理评估实验框架 | experimental |\n\n资料来源：[plugin-bundles.json](https://github.com/yeaight7/agent-powerups/blob/main/plugin-bundles.json)\n\n## 插件包元数据模式\n\n插件包的元数据定义在 `plugin-bundles.json` 中，每个插件条目包含以下字段：\n\n| 字段 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| `name` | string | 是 | 插件唯一标识符 |\n| `description` | string | 是 | 插件功能描述 |\n| `maturity` | string | 是 | 成熟度等级：stable/beta/experimental |\n| `readme` | string | 否 | 文档相对路径 |\n| `skills` | array | 否 | 包含的技能列表 |\n| `agents` | array | 否 | 包含的代理模板列表 |\n| `commands` | array | 否 | 包含的命令列表 |\n| `templates` | array | 否 | 包含的模板列表 |\n| `workflows` | array | 否 | 包含的工作流列表 |\n\n资料来源：[docs/plugin-bundles-schema.json](https://github.com/yeaight7/agent-powerups/blob/main/docs/plugin-bundles-schema.json)\n\n### 技能条目结构\n\n```json\n{\n \"name\": \"skill-name\",\n \"description\": \"技能描述\",\n \"path\": \"skills/skill-name\"\n}\n```\n\n### 代理模板条目结构\n\n```json\n{\n \"name\": \"agent-name\",\n \"description\": \"代理模板描述\",\n \"path\": \"agents/agent-name.md\"\n}\n```\n\n## 工作流程\n\n### 插件安装流程\n\n以下流程图展示了使用 `apx` CLI 安装插件的标准流程：\n\n```mermaid\ngraph TD\n A[用户执行 apx plugins install] --> B[CLI 解析目标 agent 平台]\n B --> C{是否使用 --dry-run}\n C -->|是| D[生成模拟安装计划]\n C -->|否| E[检查插件目录存在性]\n E --> F{manifest 文件验证}\n F -->|通过| G[复制资源到目标目录]\n F -->|失败| H[输出验证错误]\n G --> I[更新 agent 配置文件]\n I --> J[安装完成]\n D --> J\n```\n\n### 插件发现与检查流程\n\n```mermaid\ngraph TD\n A[用户执行 apx plugins list] --> B[读取 plugin-bundles.json]\n B --> C[扫描 plugins/ 目录]\n C --> D[合并清单数据]\n D --> E[格式化输出插件列表]\n \n F[用户执行 apx plugins info] --> G[定位指定插件]\n G --> H[读取插件 manifest]\n H --> I[输出详细元数据]\n \n J[用户执行 apx plugins validate] --> K[检查 manifest 格式]\n K --> L{符合 schema?}\n L -->|是| M[输出验证通过]\n L -->|否| N[输出验证错误列表]\n```\n\n## CLI 命令参考\n\n### 插件列表\n\n```bash\napx plugins list\n```\n\n列出所有可用的插件包，显示名称、描述和成熟度等级。\n\n### 插件详情\n\n```bash\napx plugins info \n```\n\n查看单个插件的详细元数据，包括包含的 skills、agents、commands 和 templates。\n\n### 插件验证\n\n```bash\napx plugins validate --all\n```\n\n验证所有插件的 manifest 文件结构是否符合规范，检查必需字段和文件路径。\n\n### 插件安装\n\n```bash\n# 模拟安装（预览）\napx plugins install --target codex --dry-run\n\n# 实际安装\napx plugins install --target codex --yes\n```\n\n将插件安装到指定的 agent 平台。`--target` 参数支持 `codex`、`claude-code`、`gemini` 或 `generic`。\n\n### 插件构建\n\n```bash\napx plugins build --dest --dry-run\napx plugins build --dest --write\n```\n\n根据当前仓库中的插件定义生成打包输出。`--dry-run` 模式生成预览，`--write` 模式执行实际写入。\n\n### 插件差异对比\n\n```bash\napx plugin diff \n```\n\n比较插件的实际目录结构与 manifest 声明的差异，识别缺失或未声明的资源文件。\n\n资料来源：[src/cli/apx.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/apx.ts)\n\n## Marketplace 配置\n\nMarketplace 配置文件定义了插件的市场元数据，用于插件市场的发现和展示。\n\n### Claude Code Marketplace 配置\n\n```json\n{\n \"plugins\": [\n {\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"categories\": [\"diagnostics\", \"quality\"],\n \"tags\": [\"monitoring\", \"metrics\", \"vitals\"]\n }\n ]\n}\n```\n\n### Codex Marketplace 配置\n\n```json\n{\n \"plugins\": [\n {\n \"name\": \"dev-vitals\",\n \"version\": \"1.0.0\",\n \"description\": \"Development health metrics and monitoring\",\n \"categories\": [\"diagnostics\", \"quality\"],\n \"tags\": [\"monitoring\", \"metrics\", \"vitals\"]\n }\n ]\n}\n```\n\n两个平台的 marketplace 配置结构保持一致，确保跨平台插件发现的一致性体验。\n\n资料来源：[.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)\n\n## 根级技能与插件技能的关系\n\nAgent Powerups 采用分层技能架构：\n\n```mermaid\ngraph BT\n subgraph \"Root Level\"\n R1[systematic-debugging]\n R2[writing-plans]\n R3[no-fluff]\n end\n \n subgraph \"Plugin Level\"\n P1[debugging-diagnostics/debug-tactics]\n P2[spec-driven-development/plan-generator]\n P3[quality-gates/review-check]\n end\n \n R1 -. \"complementary\" .-> P1\n R2 -. \"complementary\" .-> P2\n R3 -. \"complementary\" .-> P3\n```\n\n- **根级别技能**（`skills/`）：通用型技能，专注于通用工作流程\n- **插件技能**：领域专用技能，提供更深入的功能实现\n\n插件技能与根级别技能是互补关系而非替代关系。同一主题的插件技能不会覆盖或替代根级别技能。\n\n## 完整安装与插件安装的区别\n\n| 维度 | `apx install ` | `apx plugins install ` |\n|------|------------------------|--------------------------------|\n| 范围 | 安装所有根级技能和全部插件包 | 仅安装指定的单个插件包 |\n| 目标 | 全量初始化 agent 环境 | 按需添加特定领域功能 |\n| 适用场景 | 全新环境搭建 | 功能扩展 |\n| 灵活性 | 低（全部安装） | 高（按需选择） |\n\n## 安全注意事项\n\n- 插件可以指示 agent 读取本地文件或执行命令\n- MCP 配置可以扩展工具访问权限\n- 安装命令可以修改本地环境\n- 敏感信息（secrets）不应粘贴到 agent 上下文中\n\n在加载插件到受信任的 agent 环境之前，请务必审查插件内容。\n\n资料来源：[plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n\n## 最佳实践\n\n1. **安装前验证**：使用 `--dry-run` 模式预览安装计划\n2. **分阶段安装**：从 stable 版本开始，逐步评估 beta 版本\n3. **定期更新**：使用 `apx plugins validate --all` 检查插件完整性\n4. **环境隔离**：使用 `--agent-root` 指定隔离环境进行测试\n5. **备份配置**：重要 agent 配置文件在安装前进行备份\n\n---\n\n\n\n## 技能系统\n\n### 相关页面\n\n相关主题：[资产目录系统](#catalog-system), [命令系统](#commands), [钩子系统](#hooks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [skills/systematic-debugging/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/systematic-debugging/SKILL.md)\n- [skills/writing-plans/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/writing-plans/SKILL.md)\n- [skills/using-powerups/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/using-powerups/SKILL.md)\n- [skills/skill-authoring-guide/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/skill-authoring-guide/SKILL.md)\n- [src/cli/commands/doctor.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n- [src/cli/commands/audit.ts](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n- [plugins/README.md](https://github.com/yeaight7/agent-powerups/blob/main/plugins/README.md)\n \n\n# 技能系统\n\n## 概述\n\n技能系统（Skill System）是 Agent Powerups 的核心组件，为编码智能体提供可复用的任务工作流集合。该系统借鉴了 Oh My Zsh 的插件理念，为智能体提供结构化的任务指导、能力扩展和标准化工作流程。技能系统使编码智能体能够执行系统化调试、计划撰写、代码审查、数据质量检查等复杂任务，同时保持行为一致性和可维护性。\n\n技能系统包含 24 个已发布的根技能，涵盖调试、规划、代码审查、数据工程、文档处理等多个领域。技能以 Markdown 文件形式存储，部署时直接复制到智能体的 skills 目录中供其调用。\n\n## 技能分类\n\n### 按功能领域分类\n\n| 技能名称 | 功能领域 | 状态 |\n|----------|----------|------|\n| systematic-debugging | 调试 | 已发布 |\n| bug-hunt | 调试 | 已发布 |\n| writing-plans | 规划 | 已发布 |\n| requesting-code-review | 代码审查 | 已发布 |\n| receiving-code-review | 代码审查 | 已发布 |\n| pr-triage | 代码审查 | 已发布 |\n| sql-business-logic-review | 代码审查 | 已发布 |\n| data-quality | 数据工程 | 已发布 |\n| bigquery-cost-audit | 数据工程 | 已发布 |\n| dbt-preflight | 数据工程 | 已发布 |\n| dbt-strategy | 数据工程 | 已发布 |\n| dbt-incremental-strategy-audit | 数据工程 | 已发布 |\n| metric-impact-analyzer | 数据工程 | 已发布 |\n| defuddle | 文档处理 | 已发布 |\n| markitdown-file-intake | 文档处理 | 已发布 |\n| ai-slop-cleaner | 文档处理 | 已发布 |\n| repo-map | 代码理解 | 已发布 |\n| graphify | 代码理解 | 已发布 |\n| safe-refactor | 重构 | 已发布 |\n| no-fluff | 质量检查 | 已发布 |\n| ask-claude | 智能体协作 | 已发布 |\n| ask-gemini | 智能体协作 | 已发布 |\n| ask-codex | 智能体协作 | 已发布 |\n| using-powerups | 系统引导 | 已发布 |\n\n资料来源：[README.md](./README.md)\n\n### 按来源分类\n\n根技能（Root Skills）位于仓库根目录的 `skills/` 文件夹中，属于通用目的、可独立使用的技能。插件技能（Plugin Skills）位于 `plugins/` 目录下的各插件子目录中，属于领域特定且深度专精的技能。插件技能可能与根技能覆盖相同主题，但不应替换或覆盖根技能。\n\n资料来源：[plugins/README.md](./plugins/README.md)\n\n## 技能结构\n\n### 文件组织\n\n每个技能遵循标准的目录结构：\n\n```\nskills/\n└── /\n └── SKILL.md # 技能定义文件（必需）\n └── support/ # 支持文件目录（可选）\n └── # 技能引用的辅助资源\n```\n\n### SKILL.md 格式规范\n\nSKILL.md 是技能的核心定义文件，包含前置matter元数据和技能内容。文件必须包含以下前置matter字段：\n\n| 字段 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 技能的唯一标识名称 |\n| description | string | 是 | 技能的简要功能描述 |\n| version | string | 否 | 技能版本号 |\n| tags | array | 否 | 技能标签分类 |\n\n前置matter 示例：\n\n```yaml\n---\nname: systematic-debugging\ndescription: A structured approach to debugging issues systematically\nversion: 1.0.0\ntags: [debugging, workflow, quality]\n---\n```\n\n资料来源：[src/cli/commands/doctor.ts:45-58](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n### 技能内容要求\n\n技能文件必须满足以下内容质量标准：\n\n- 技能内容长度不得低于最小阈值（由验证脚本定义）\n- 技能内容必须包含明确的任务指导步骤\n- 技能引用的支持文件必须存在\n\n资料来源：[src/cli/commands/audit.ts:35-50](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n\n## 技能生命周期\n\n### 技能创作流程\n\n技能创作遵循以下标准流程：\n\n```mermaid\ngraph TD\n A[创建 SKILL.md] --> B[定义前置matter]\n B --> C[编写技能内容]\n C --> D[添加支持文件]\n D --> E[运行本地验证]\n E --> F{验证结果}\n F -->|通过| G[提交到仓库]\n F -->|失败| C\n G --> H[自动 CI 检查]\n H --> I[发布到目录]\n```\n\n### 技能创作指南\n\n技能创作指南（skill-authoring-guide）提供以下指导：\n\n- 如何设计有效的技能结构\n- 如何编写清晰的任务描述\n- 如何创建可复用的工作流程\n- 如何维护技能与其他技能的兼容性\n\n资料来源：[skills/skill-authoring-guide/SKILL.md](https://github.com/yeaight7/agent-powerups/blob/main/skills/skill-authoring-guide/SKILL.md)\n\n## 技能验证机制\n\n### 验证层级\n\n技能验证在多个层级进行，确保质量和一致性：\n\n#### 1. 前置matter 验证\n\n医生命令（doctor）检查每个技能的必要字段：\n\n```typescript\nif (!frontmatter?.name || !frontmatter?.description) {\n issues.push(`${entry.name}: missing required frontmatter`);\n}\n```\n\n资料来源：[src/cli/commands/doctor.ts:50-52](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n#### 2. 支持文件验证\n\n医生命令验证技能引用的支持文件是否存在：\n\n```typescript\nfor (const ref of referencedSupportFiles(content)) {\n if (!(await supportRefExists(skillDir, ref))) {\n issues.push(`${entry.name}: missing referenced support file ${ref}`);\n }\n}\n```\n\n资料来源：[src/cli/commands/doctor.ts:53-56](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/doctor.ts)\n\n#### 3. 审计检查\n\n审计命令（audit）执行全面的技能质量检查：\n\n| 检查项 | 说明 |\n|--------|------|\n| skill-frontmatter | 验证所有技能都有 name 和 description |\n| skill-content-length | 验证技能内容长度符合最小要求 |\n\n```typescript\nif (missingFrontmatter > 0) {\n checks.push(fail(\"skill-frontmatter\", `${missingFrontmatter} skill(s) missing name/description`));\n} else {\n checks.push(pass(\"skill-frontmatter\", \"all have name + description\"));\n}\n\nif (tooShort > 0) {\n checks.push(warn(\"skill-content-length\", `${tooShort} skill(s) under ${MIN_CONTENT_LENGTH} chars`));\n} else {\n checks.push(pass(\"skill-content-length\", \"all skills meet minimum length\"));\n}\n```\n\n资料来源：[src/cli/commands/audit.ts:40-50](https://github.com/yeaight7/agent-powerups/blob/main/src/cli/commands/audit.ts)\n\n### 验证脚本\n\n仓库提供三个核心验证脚本：\n\n| 脚本 | 功能 |\n|------|------|\n| `scripts/validate-skills.py` | 验证技能文件结构和格式 |\n| `scripts/validate-catalog.py` | 验证技能目录完整性 |\n| `scripts/check-requirements.py` | 检查技能依赖要求 |\n\n资料来源：[README.md](./README.md)\n\n## 技能安装与部署\n\n### 安装方式\n\n#### 手动安装\n\n使用 apx CLI 安装技能到指定智能体：\n\n```bash\n# 安装到 Codex\napx install codex\n\n# 安装到 Claude Code\napx install claude-code\n\n# 安装到 Gemini\napx install gemini\n```\n\n默认安装将根目录的 `skills/` 复制到智能体根目录的 `skills/` 子目录。\n\n#### 交互式安装\n\n```bash\napx setup codex --mode recommended --yes\n```\n\n安装模式说明：\n\n| 模式 | 说明 |\n|------|------|\n| minimal | 仅安装引导文件 |\n| recommended | 安装推荐的核心技能集 |\n| full | 安装全部技能和支持资产 |\n\n资料来源：[README.md](./README.md)\n\n### 目录映射\n\n技能安装时的标准目录映射关系：\n\n```mermaid\ngraph LR\n A[仓库根目录] --> B[技能安装目标]\n A1[skills/] --> B1[/skills/]\n A2[plugins/] --> B2[/plugins/]\n A3[agents-md/] --> B3[/agent-powerups/agents-md/]\n A4[hooks/] --> B4[/agent-powerups/hooks/]\n A5[workflows/] --> B5[/agent-powerups/workflows/]\n A6[commands/generic/] --> B6[/agent-powerups/commands/generic/]\n A7[mcp/generic/] --> B7[