{ "canonical_name": "pea3nut/agent-add", "compilation_id": "pack_7f58adb80de246e3aaf38423de523349", "created_at": "2026-05-14T06:08:04.349487+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 `npx -y agent-add` 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": "npx -y agent-add", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_42702166d7c54a9d8b844f82a712ea33" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_9b12abce4417f6a9c55512a11e7a4543", "canonical_name": "pea3nut/agent-add", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/pea3nut/agent-add", "slug": "agent-add", "source_packet_id": "phit_36403cd08fb24db684cbb706adfb5626", "source_validation_id": "dval_3e340640c8434f42816f732f71099d5f" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 mcp_host的用户", "github_forks": null, "github_stars": null, "one_liner_en": "
", "one_liner_zh": "
", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:code, git" }, "target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户", "title_en": "agent-add", "title_zh": "agent-add 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "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": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Local-first", "label_zh": "本地优先", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-local-first", "type": "selection_signal" } ] }, "packet_id": "phit_36403cd08fb24db684cbb706adfb5626", "page_model": { "artifacts": { "artifact_slug": "agent-add", "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": "npx -y agent-add", "label": "Node.js / npx · 官方安装入口", "source": "https://github.com/pea3nut/agent-add#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "本地优先" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 mcp_host的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "
" }, { "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, cursor, chatgpt", "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": "I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...", "category": "安装坑", "evidence": [ "social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ..." ], "severity": "medium", "suggested_check": "Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。", "title": "社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...", "user_impact": "这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。" }, { "body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。", "category": "配置坑", "evidence": [ "capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt" ], "severity": "medium", "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。", "title": "可能修改宿主 AI 配置", "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": null, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": null }, "source_url": "https://github.com/pea3nut/agent-add", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "
", "title": "agent-add 能力包", "trial_prompt": "# agent-add - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-add 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code / Cursor\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- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p-home：项目首页。围绕“项目首页”模拟一次用户任务，不展示安装或运行结果。\n2. p-installation：安装与快速开始。围绕“安装与快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. p-usage：核心功能使用指南。围绕“核心功能使用指南”模拟一次用户任务，不展示安装或运行结果。\n4. p-arch：系统架构总览。围绕“系统架构总览”模拟一次用户任务，不展示安装或运行结果。\n5. p-host-system：Host 适配器系统。围绕“Host 适配器系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p-home\n输入：用户提供的“项目首页”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p-installation\n输入：用户提供的“安装与快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p-usage\n输入：用户提供的“核心功能使用指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p-arch\n输入：用户提供的“系统架构总览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p-host-system\n输入：用户提供的“Host 适配器系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p-home：Step 1 必须围绕“项目首页”形成一个小中间产物，并等待用户确认。\n- Step 2 / p-installation：Step 2 必须围绕“安装与快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / p-usage：Step 3 必须围绕“核心功能使用指南”形成一个小中间产物，并等待用户确认。\n- Step 4 / p-arch：Step 4 必须围绕“系统架构总览”形成一个小中间产物，并等待用户确认。\n- Step 5 / p-host-system：Step 5 必须围绕“Host 适配器系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/pea3nut/agent-add#readme\n- tests/fixtures/skill/my-skill/SKILL.md\n- README.md\n- package.json\n- bin/agent-add.js\n- src/cli.ts\n- src/installer.ts\n- src/hosts/index.ts\n- src/manifest/parser.ts\n- src/index.ts\n- tsup.config.ts\n- src/hosts/types.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-add 的核心服务。\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, reddit。github/github_release: v1.1.0（https://github.com/pea3nut/agent-add/releases/tag/1.1.0）；reddit: I built a CLI that installs MCP, skills, prompts, commands and sub ...（https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_release", "source": "github", "title": "v1.1.0", "url": "https://github.com/pea3nut/agent-add/releases/tag/1.1.0" }, { "kind": "searxng_indexed", "source": "reddit", "title": "I built a CLI that installs MCP, skills, prompts, commands and sub ...", "url": "https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/" } ], "status": "已收录 2 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "
", "effort": "安装已验证", "forks": null, "icon": "code", "name": "agent-add 能力包", "risk": "需复核", "slug": "agent-add", "stars": null, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "本地优先" ], "thumb": "gray", "type": "MCP 配置" }, "manual": { "markdown": "# https://github.com/pea3nut/agent-add 项目说明书\n\n生成时间：2026-05-14 05:41:02 UTC\n\n## 目录\n\n- [项目首页](#p-home)\n- [安装与快速开始](#p-installation)\n- [核心功能使用指南](#p-usage)\n- [源格式与名称推断](#p-source-formats)\n- [系统架构总览](#p-arch)\n- [Source 模块详解](#p-source-module)\n- [Host 适配器系统](#p-host-system)\n- [CLI 参考文档](#p-cli-ref)\n- [Pack Manifest 格式规范](#p-pack-manifest)\n- [资产开发者指南](#p-asset-dev)\n\n\n\n## 项目首页\n\n### 相关页面\n\n相关主题：[安装与快速开始](#p-installation), [核心功能使用指南](#p-usage), [系统架构总览](#p-arch)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n
\n\n# 项目首页\n\n## 项目概述\n\n**agent-add** 是一个跨平台的命令行工具，用于将 AI Agent 资产（MCP 服务器、Skills、Prompts、Commands、Sub-agents）安装到各种 AI 编程辅助工具中。该工具通过统一的接口屏蔽了不同宿主（Host）之间的差异，开发者只需一条命令即可将资产安装到指定的 AI 编程环境中。\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## 核心能力\n\n### 支持的资产类型\n\n| 资产类型 | 说明 | 安装方式 |\n|---------|------|---------|\n| MCP | Model Context Protocol 服务器配置 | JSON 配置合并 |\n| Skill | 可复用的 Agent 技能目录 | 目录递归复制 |\n| Prompt | 规则文件 / 系统提示词 | 追加写入或独立文件 |\n| Command | 斜杠命令定义 | 独立文件安装 |\n| Sub-agent | 子代理配置 | YAML + Markdown 混合格式 |\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n### 支持的宿主环境\n\nagent-add 目前支持 **18 种** AI 编程宿主：\n\n| 宿主 | 配置格式 | 说明 |\n|-----|---------|------|\n| `cursor` | AGENTS.md | Cursor IDE |\n| `claude-code` | CLAUDE.md | Anthropic Claude Code |\n| `claude-desktop` | JSON | Claude Desktop 应用 |\n| `windsurf` | 独立目录 | Windsurf AI IDE |\n| `github-copilot` | 配置文件 | GitHub Copilot |\n| `gemini` | 配置文件 | Google Gemini |\n| `roo-code` | 独立目录 | Roo Code |\n| `kilo-code` | 配置文件 | Kilo Code |\n| `qwen-code` | 配置文件 | 通义千问编码助手 |\n| `opencode` | 配置文件 | OpenCode |\n| `augment` | 配置文件 | Augment Code |\n| `kiro` | 配置文件 | Kiro AI |\n| `tabnine` | 配置文件 | Tabnine |\n| `kimi` | 配置文件 | Kimi 编程助手 |\n| `trae` | 配置文件 | Trae IDE |\n| `openclaw` | 配置文件 | OpenClaw |\n| `codex` | TOML | OpenAI Codex |\n| `vibe` | TOML | Vibe Coding 工具 |\n\n资料来源：[src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n\n## 系统架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[CLI 输入] --> B[显式标志能力检查]\n B --> C[资产描述符解析]\n C --> D[源解析器]\n D --> E[验证层]\n E --> F[安装处理器]\n F --> G[宿主适配器]\n G --> H[文件系统写入]\n \n D --> D1[MCP 处理器]\n D --> D2[Skill 处理器]\n D --> D3[Prompt 处理器]\n D --> D4[Command 处理器]\n D --> D5[Sub-agent 处理器]\n```\n\n### 核心模块\n\n| 模块 | 路径 | 职责 |\n|-----|------|-----|\n| CLI | `src/cli.ts` | 命令行参数解析、TTY 检测、交互式宿主选择 |\n| 安装器 | `src/installer.ts` | 编排核心：输入解析 → 能力检查 → 源解析 → 验证 → 处理器执行 → 汇总 |\n| 宿主适配层 | `src/hosts/` | 18 种宿主适配器，实现 HostAdapter 接口 |\n| 资产处理器 | `src/assets/` | 5 种资产类型处理器 |\n| 源解析器 | `src/source/` | 本地路径、Git URL、HTTP 文件、内联内容的统一解析 |\n| 清单解析器 | `src/manifest/parser.ts` | Pack Manifest JSON 格式验证与解析 |\n| 工具函数 | `helpers/utils.ts` | 通用辅助函数 |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## 安装流程\n\n### 命令行用法\n\n```bash\n# 安装 MCP 服务器\nnpx -y agent-add --host cursor --mcp ./mcp/playwright.json\n\n# 安装 Skill 目录\nnpx -y agent-add --host claude-code --skill ./skills/my-skill\n\n# 安装 Prompt 规则文件\nnpx -y agent-add --host windsurf --prompt ./rules/code-review.md\n\n# 从 Pack Manifest 批量安装\nnpx -y agent-add --host cursor --pack ./manifest.json\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### 数据流处理\n\n```mermaid\nflowchart LR\n subgraph 输入层\n A1[CLI 标志] --> A3[AssetDescriptor]\n A2[Pack Manifest] --> A3\n end\n \n subgraph 解析层\n A3 --> B1[ResolvedSource]\n B1 --> B2[安装作业队列]\n end\n \n subgraph 执行层\n B2 --> C1[MCP 处理器]\n B2 --> C2[Skill 处理器]\n B2 --> C3[Prompt 处理器]\n B2 --> C4[Command 处理器]\n B2 --> C5[Sub-agent 处理器]\n end\n \n subgraph 输出层\n C1 --> D1[InstallResult]\n C2 --> D1\n C3 --> D1\n C4 --> D1\n C5 --> D1\n D1 --> E[Summary 输出]\n end\n```\n\n### 状态与结果\n\n| 状态 | 说明 |\n|-----|------|\n| `written` | 资产已成功写入 |\n| `exists` | 资产已存在，无需更新 |\n| `updated` | 资产已更新 |\n| `conflict` | 存在冲突（手动解决） |\n| `skipped` | 宿主不支持该资产类型 |\n| `error` | 安装过程中发生错误 |\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 关键设计决策\n\n### 原子化 JSON 写入\n\nMCP 配置文件使用临时文件 + 重命名的原子写入策略，确保多进程并发写入时的数据一致性：\n\n```typescript\n// 临时文件写入 → 原子重命名\nconst tempPath = `${configPath}.tmp.${Date.now()}`;\nawait fs.promises.writeFile(tempPath, JSON.stringify(merged, null, 2));\nawait fs.promises.rename(tempPath, configPath);\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### 标记块追加策略\n\nPrompt 类型资产在追加模式下使用 HTML 注释标记实现幂等追加：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n重复安装时，工具会自动识别并更新对应标记块内容，而非重复追加。\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### 内联源支持\n\n| 源类型 | 格式特征 | 支持的资产 |\n|-------|---------|-----------|\n| 内联 JSON | 以 `{` 开头 | MCP |\n| 内联 Markdown | 包含 `\\n` | Prompt / Command / Sub-agent |\n| HTTP 文件 | URL 格式 | Skill 除外全部支持 |\n| 本地路径 | 相对/绝对路径 | 全部支持 |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n### 非 TTY 严格模式\n\nCI 环境必须显式指定 `--host` 参数，否则工具将退出并返回错误码 2：\n\n```typescript\n// 非 TTY 环境未指定 host\nif (!process.stdin.isTTY && !host) {\n process.stderr.write('agent-add error: --host flag required in non-TTY environment\\n');\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Pack Manifest 清单\n\n### 格式规范\n\n```json\n{\n \"name\": \"namespace/pack-name\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/...#path/to/config.json\" },\n { \"type\": \"skill\", \"source\": \"./local/skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/...\" },\n { \"type\": \"command\", \"source\": \"git@github.com:...#tools/security.md\" },\n { \"type\": \"subAgent\", \"source\": \"...#categories/backend.md\" }\n ]\n}\n```\n\n### 字段规格\n\n| 字段 | 必填 | 说明 |\n|-----|-----|------|\n| `name` | 是 | 格式：`namespace/pack-name`，仅允许 `[a-zA-Z0-9_-]` |\n| `assets` | 是 | 至少 1 个元素 |\n| `assets[].type` | 是 | `mcp` \\| `skill` \\| `prompt` \\| `command` \\| `subAgent` |\n| `assets[].source` | 是 | 资产来源（URL、路径、内联内容） |\n\n资料来源：[src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n\n## 项目技术栈\n\n| 组件 | 版本 | 用途 |\n|-----|------|-----|\n| TypeScript | ^5.9.3 | 类型安全开发 |\n| Commander | ^14.0.3 | 命令行参数解析 |\n| Vitest | ^4.1.0 | 单元测试框架 |\n| Zod | ^4.3.6 | 数据验证 |\n| smol-toml | ^1.6.1 | TOML 解析（Codex/Vibe） |\n| YAML | ^2.8.2 | YAML 前端解析 |\n| tsup | ^8.5.1 | 构建工具 |\n\n资料来源：[package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n\n## 宿主适配器接口\n\n```typescript\ninterface HostAdapter {\n id: string; // 唯一标识符\n name: string; // 宿主名称\n assets: AssetCapability; // 支持的资产类型映射\n mcpWriteStrategy: 'json' | 'toml'; // MCP 配置写入策略\n}\n\ninterface AssetCapability {\n mcp?: { supported: boolean; reason?: string };\n skill?: { supported: boolean; reason?: string };\n prompt?: { supported: boolean; reason?: string };\n command?: { supported: boolean; reason?: string };\n subAgent?: { supported: boolean; reason?: string };\n}\n```\n\n资料来源：[src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n\n## 快速开始\n\n### 开发环境搭建\n\n```bash\n# 克隆仓库\ngit clone https://github.com/pea3nut/agent-add.git\ncd agent-add\n\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 安装开发资产（scenario-test 等）\nnpm run install:vibe\n```\n\n### 运行测试\n\n| 命令 | 说明 |\n|-----|------|\n| `npm test` | 运行所有单元测试和集成测试 |\n| `npm run test:contract` | 仅运行 CLI 黑盒契约测试 |\n| `npx vitest run tests/unit/hosts/cursor.test.ts` | 运行单个测试文件 |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## 贡献指南\n\n### 场景测试\n\n场景测试使用 Gherkin `.feature` 文件定义，由 AI Agent 通过 [scenario-test](https://github.com/pea3nut/scenario-test) 执行：\n\n```\n/scenario-exec tests/features/core # 核心资产行为测试\n/scenario-exec tests/features/host # 跨宿主兼容性测试\n```\n\n每个场景在隔离的临时目录中运行，运行配置定义于 `tests/features/scenario-run-config.md`。\n\n### 添加新宿主\n\n1. 在 `src/hosts/` 下创建 `.ts` 实现 HostAdapter 接口\n2. 在 `src/hosts/README.md` 中更新宿主能力矩阵\n3. 在 `tests/unit/hosts/` 下创建对应的单元测试\n4. 在 `src/hosts/index.ts` 中注册新宿主\n\n> **重要**：adapter 实现必须与 README.md 中的字段值完全一致。\n\n---\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[核心功能使用指南](#p-usage), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n
\n\n# 安装与快速开始\n\n## 概述\n\n`agent-add` 是一个跨宿主 AI Agent 工具包安装器 CLI 工具，能够将 MCP（Model Context Protocol）、Skill、Prompt、Command、Sub-agent 等资产安装到不同的 AI Agent 宿主环境中。使用一条命令即可完成资产的安装、配置和管理。\n\n当前支持的宿主环境包括：Cursor、Claude Code、Claude Desktop、Windsurf、GitHub Copilot、Gemini、Roo Code、Kilo Code、Qwen Code、OpenCode、Augment、Kiro、Tabnine、Kimi、Trae、OpenClaw、Codex（TOML）、Vibe（TOML）等 18 种主流 AI 编程工具。\n\n资料来源：[src/hosts/README.md:1]()\n\n## 系统要求\n\n| 要求 | 说明 |\n|------|------|\n| Node.js 版本 | >= 18 |\n| 包管理器 | npm、yarn、pnpm 均可 |\n| 网络 | 需要访问 GitHub/GitLab 或相关资源 URL |\n| TTY 环境 | CI 环境需显式指定 `--host`，否则退出错误码 2 |\n\n资料来源：[package.json:28]()\n\n## 安装方式\n\n### 方式一：npx 免安装（推荐）\n\n最便捷的使用方式，无需预先安装，直接通过 `npx` 调用：\n\n```bash\nnpx -y agent-add --host cursor --mcp \n```\n\n`npx -y` 参数确保自动确认安装提示。\n\n资料来源：[README.md:1]()\n\n### 方式二：全局安装\n\n将工具安装到系统全局环境，随时可用：\n\n```bash\nnpm install -g agent-add\n```\n\n安装完成后可直接调用：\n\n```bash\nagent-add --host claude-code --mcp \n```\n\n### 方式三：本地项目安装\n\n将工具作为项目开发依赖安装：\n\n```bash\nnpm install --save-dev agent-add\n```\n\n在 `package.json` 中配置快捷脚本：\n\n```json\n{\n \"scripts\": {\n \"setup\": \"agent-add -- --pack vibe/manifest.json\"\n }\n}\n```\n\n资料来源：[package.json:41]()\n\n## 构建与开发\n\n如果从源码克隆项目，需要先构建：\n\n```bash\nnpm install\nnpm run build\n```\n\n构建完成后会生成单文件 CJS 捆绑包 `dist/index.js`。\n\n### 开发模式\n\n支持热重载开发模式：\n\n```bash\nnpm run dev # tsup --watch 监听模式\nnpm run install:vibe # 通过 pack manifest 安装开发资产\n```\n\n资料来源：[README.md:7]()\n\n## 基本使用流程\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[开始] --> B[指定宿主 --host]\n B --> C{资产来源类型}\n C -->|Git URL| D[解析 #path 提取资源]\n C -->|HTTP URL| E[下载远程文件]\n C -->|本地路径| F[访问本地文件/目录]\n C -->|内联内容| G[写入临时文件]\n D --> H[验证资产有效性]\n E --> H\n F --> H\n G --> H\n H --> I{资产类型}\n I -->|MCP| J[写入 JSON/TOML 配置]\n I -->|Skill| K[复制目录到 skills/]\n I -->|Prompt| L[追加或创建文件]\n I -->|Command| M[写入 commands/]\n I -->|Sub-agent| N[写入 subagents/]\n J --> O[完成安装]\n K --> O\n L --> O\n M --> O\n N --> O\n```\n\n### 核心参数说明\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--host ` | CI 环境必填 | 目标宿主标识符，如 `cursor`、`claude-code` |\n| `--mcp ` | 否 | MCP 配置文件来源 |\n| `--skill ` | 否 | Skill 技能包目录来源 |\n| `--prompt ` | 否 | Prompt 规则文件来源 |\n| `--command ` | 否 | Command 命令文件来源 |\n| `--sub-agent ` | 否 | Sub-agent 子代理来源 |\n| `--pack ` | 否 | Pack 清单文件（批量安装） |\n| `-V, --version` | 否 | 显示版本号 |\n| `-h, --help` | 否 | 显示帮助信息 |\n\n资料来源：[src/cli.ts:1]()\n\n### 宿主选择规则\n\n| 环境 | 行为 |\n|------|------|\n| TTY 交互环境 | 无 `--host` 时显示交互式选择菜单 |\n| CI/非 TTY 环境 | 必须显式指定 `--host`，否则退出码 2 |\n\n资料来源：[src/cli.ts:1]()\n\n## 资产安装示例\n\n### 安装 MCP 服务器\n\n```bash\n# 从 GitHub 仓库安装\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'\n\n# 从本地 JSON 文件安装\nnpx -y agent-add --host cursor --mcp './mcps/playwright.json'\n\n# 内联 JSON 安装（MCP 专用）\nnpx -y agent-add --host cursor --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}'\n```\n\n资料来源：[README.md:40]()\n\n### 安装 Skill 技能包\n\n```bash\n# 从 GitHub 仓库安装\nnpx -y agent-add --host cursor --skill 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n\n# 从本地目录安装\nnpx -y agent-add --host cursor --skill './my-skill'\n```\n\n> **注意**：Skill 必须指向目录来源，不支持内联内容或直接 HTTP URL。\n\n资料来源：[src/installer.ts:1]()\n\n### 安装 Prompt 规则文件\n\n```bash\n# 内联 Markdown（适用于 Claude Code）\nnpx -y agent-add --host claude-code \\\n --prompt $'# Code Review Rules\\n\\nAlways review for security issues first.'\n\n# 从 HTTP URL 安装\nnpx -y agent-add --host cursor \\\n --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'\n```\n\n资料来源：[README.md:50]()\n\n### 安装 Command 命令\n\n```bash\n# 从 GitHub 仓库安装\nnpx -y agent-add --host cursor \\\n --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### 安装 Sub-agent 子代理\n\n```bash\n# 从 VoltAgent 仓库安装\nnpx -y agent-add --host cursor \\\n --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'\n```\n\n### 批量安装（Pack 清单）\n\n```bash\n# 安装 Pack 清单中定义的所有资产\nnpx -y agent-add --host cursor --pack 'https://github.com/pea3nut/scenario-test.git'\n```\n\nPack 清单格式示例：\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/...\" },\n { \"type\": \"command\", \"source\": \"https://github.com/...#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/...#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n资料来源：[README.md:70]()\n\n## 资产名称推断规则\n\n`agent-add` 根据来源自动推断资产名称：\n\n| 来源类型 | 推断规则 | 示例 |\n|----------|----------|------|\n| 包含 `#path` | 使用 `#` 后的最后一段（去除扩展名） | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#` | 使用仓库名称（去除 `.git` 后缀） | `...playwright.git` → `playwright` |\n| 本地路径/HTTP | 使用文件名（去除扩展名） | `./mcps/playwright.json` → `playwright` |\n| 内联 JSON `{` 开头 | 提取顶层 key 作为名称 | `{\"playwright\":{...}}` → `playwright` |\n| 内联 Markdown 包含 `\\n` | 提取第一个 `# Heading` 并转 kebab-case | `# Code Review` → `code-review` |\n\n资料来源：[src/source/infer-name.ts:1]()\n\n## 输出状态说明\n\n每次安装操作后会显示摘要，包含以下状态：\n\n| 状态 | 含义 |\n|------|------|\n| `written` | 新资产已写入 |\n| `exists` | 资产已存在，无需更新 |\n| `updated` | 资产已更新 |\n| `conflict` | 存在冲突，需要手动处理 |\n| `skipped` | 宿主不支持该资产类型 |\n| `error` | 安装过程中发生错误 |\n\n安装结果包含冲突或错误时，CLI 退出码为 1；其他情况退出码为 0。\n\n资料来源：[src/cli.ts:1]()\n\n## 错误处理\n\n| 错误类型 | 退出码 | 说明 |\n|----------|--------|------|\n| 宿主不支持该资产类型 | 2 | 显式指定了不支持的资产类型 |\n| 资产来源无效 | 2 | 来源格式错误或无法解析 |\n| 缺少必需文件 | 2 | 如 Skill 目录缺少 `SKILL.md` |\n| CI 环境未指定宿主 | 2 | 非 TTY 环境必须 `--host` |\n| 冲突或错误 | 1 | 安装有冲突或错误 |\n\n资料来源：[src/installer.ts:1]()\n\n## 常见问题\n\n### Q: 安装 MCP 时报错 \"MCP 来源文件不存在\"\n\n确保 MCP 来源文件扩展名为 `.json`，且路径正确。agent-add 不支持其他格式的 MCP 配置。\n\n### Q: Skill 安装失败\n\n检查 Skill 目录中是否包含 `SKILL.md` 文件，这是必需的标识文件。\n\n### Q: 提示宿主不支持某资产类型\n\n查看 `src/hosts/README.md` 确认该宿主支持的功能列表，不同宿主支持的资产类型不同。\n\n### Q: CI 环境安装失败\n\n确保在 CI 环境中显式指定 `--host` 参数，否则程序会退出并提示错误。\n\n## 相关文档\n\n- [宿主适配器开发指南](./host-adapter-guide.md) - 如何添加新的宿主支持\n- [资产类型规范](./asset-specifications.md) - 各资产类型的详细格式说明\n- [Pack 清单规范](./pack-manifest.md) - Pack 清单文件格式详解\n- [测试指南](./testing.md) - 单元测试和集成测试说明\n\n---\n\n\n\n## 核心功能使用指南\n\n### 相关页面\n\n相关主题：[源格式与名称推断](#p-source-formats), [Host 适配器系统](#p-host-system), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n
\n\n# 核心功能使用指南\n\n## 概述\n\nagent-add 是一款用于向 AI 编码助手安装资产的命令行工具，支持 18 种主流开发环境。该工具通过统一的 CLI 接口简化了 MCP 服务器、Skill、Prompt、Command 和 Sub-agent 五类资产的安装流程。\n\n核心功能模块包括：**命令行解析** → **宿主检测** → **来源解析** → **资产验证** → **安装执行** → **结果汇总**。\n\n资料来源：[src/installer.ts:1-50]()\n\n## 安装流程架构\n\n### 数据流总览\n\n```mermaid\ngraph TD\n A[CLI 参数解析] --> B[显式标志能力检查]\n B --> C[AssetDescriptor 数组]\n C --> D[来源解析]\n D --> E[ResolvedSource 数组]\n E --> F[资产验证]\n F --> G[InstallJob 数组]\n G --> H[安装执行]\n H --> I[InstallResult 数组]\n I --> J[结果汇总输出]\n \n K[--pack 清单文件] -.-> C\n L[--mcp/skill/prompt/command/sub-agent 标志] -.-> C\n```\n\n### 核心数据类型\n\n| 类型名称 | 用途 | 关键字段 |\n|---------|------|---------|\n| `CliInput` | CLI 原始输入 | `host`, `pack[]`, `mcp[]`, `skill[]`, `prompt[]`, `command[]`, `subAgent[]` |\n| `AssetDescriptor` | 资产描述符 | `assetType`, `source`, `fromExplicitFlag` |\n| `ResolvedSource` | 已解析来源 | `type`, `originalSource`, `localPath`, `tempDir` |\n| `InstallJob` | 安装任务 | `assetType`, `assetName`, `resolvedSource`, `host` |\n| `InstallResult` | 安装结果 | `job`, `status`, `reason?` |\n\n资料来源：[src/installer.ts:20-45]()\n\n## 命令行接口\n\n### CLI 参数定义\n\nagent-add 采用 Commander.js 构建 CLI，定义了六类资产安装标志：\n\n```typescript\n.option('--pack ', 'Install an Agent Pack manifest', collect, [])\n.option('--mcp ', 'Install an MCP Server', collect, [])\n.option('--skill ', 'Install a Skill', collect, [])\n.option('--prompt ', 'Install a Prompt', collect, [])\n.option('--command ', 'Install a Command', collect, [])\n.option('--sub-agent ', 'Install a Sub-agent', collect, [])\n.option('--host ', 'Target host ID', collect, [])\n```\n\n所有资产标志均支持重复使用（多次安装同类型资产）并可自由组合。\n\n### 输入验证\n\n```typescript\nconst hasAssetFlags =\n cliInput.pack.length > 0 ||\n cliInput.mcp.length > 0 ||\n cliInput.skill.length > 0 ||\n cliInput.prompt.length > 0 ||\n cliInput.command.length > 0 ||\n cliInput.subAgent.length > 0;\n\nif (!hasAssetFlags) {\n process.stderr.write(\n 'agent-add error: No asset flags provided. Use --pack, --mcp, --skill, --prompt, --command, or --sub-agent.\\n',\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts:1-30]()\n\n## 宿主检测与选择\n\n### 宿主注册表\n\n宿主适配器通过注册表统一管理：\n\n```typescript\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['claude-desktop', new ClaudeDesktopAdapter()],\n // ... 共18种宿主\n]);\n```\n\n### 宿主选择逻辑\n\n| 场景 | 行为 |\n|------|------|\n| 显式指定 `--host` | 直接使用指定宿主 ID |\n| TTY 环境无 `--host` | 交互式选择宿主 |\n| 非 TTY 环境无 `--host` | 输出错误并退出（exit 2） |\n\n```typescript\nif (cliInput.host) {\n hostId = cliInput.host;\n} else if (!process.stdout.isTTY) {\n const validIds = getValidHostIds().join(', ');\n process.stderr.write(\n `agent-add error: Non-TTY environment requires explicit --host flag.\\n`\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/hosts/index.ts:1-25]()\n\n### 宿主能力矩阵\n\n每种宿主声明其支持的资产类型：\n\n```typescript\ninterface HostAdapter {\n id: string;\n displayName: string;\n docs: string;\n assets: {\n mcp: AssetCapability;\n skill: AssetCapability;\n prompt: AssetCapability;\n command: AssetCapability;\n subAgent: AssetCapability;\n };\n}\n\ninterface AssetCapability {\n supported: boolean;\n configFile?: string;\n installDir?: string;\n writeStrategy?: 'append' | 'standalone';\n reason?: string;\n}\n```\n\n资料来源：[src/hosts/types.ts:1-20]()\n\n## 来源解析系统\n\n### 支持的来源类型\n\n| 类型 | 格式 | 说明 |\n|------|------|------|\n| `local` | 绝对/相对路径 | 本地文件系统 |\n| `git` | Git URL + `#path` | Git 仓库文件/目录 |\n| `http-file` | HTTP(S) URL | 远程文件下载 |\n| `inline-json` | `{\"name\":{...}}` | 内联 JSON（MCP 专用） |\n| `inline-md` | 含换行符的 Markdown | 内联 Prompt/Command/Sub-agent |\n\n### 名称推断规则\n\n来源字符串到资产名称的转换规则：\n\n| 来源格式 | 推断逻辑 | 示例 |\n|----------|----------|------|\n| 内联 JSON | 提取顶层键名 | `{\"playwright\":{...}}` → `playwright` |\n| 内联 Markdown | 首行 `# 标题` 转 kebab-case | `# Code Review` → `code-review` |\n| Git URL + `#path` | path 最后段去扩展名 | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#` | 仓库名去 `.git` | `...playwright.git` → `playwright` |\n| 本地路径/HTTP | 文件名去扩展名 | `./mcps/playwright.json` → `playwright` |\n\n```typescript\nexport function inferName(source: string): string {\n const s = source.trim();\n \n // 内联 JSON：提取顶层键\n if (s.startsWith('{')) {\n const parsed = JSON.parse(s);\n const unwrapped = unwrapMcpServers(obj);\n if (unwrapped) return unwrapped.name;\n // ...\n }\n \n // 内联 Markdown：提取 # 标题\n if (s.includes('\\n')) {\n const match = s.match(/^#\\s+(.+)/m);\n if (match) return kebabCase(match[1]);\n }\n \n // Git URL / 本地路径 / HTTP\n // ...\n}\n```\n\n资料来源：[src/source/infer-name.ts:1-40]()\n\n### 来源解析流程\n\n```mermaid\ngraph LR\n A[来源字符串] --> B{是否内联 JSON?}\n B -->|是| C[创建临时文件]\n B -->|否| D{包含换行符?}\n D -->|是| E[内联 Markdown]\n D -->|否| F{Git URL?}\n F -->|是| G[克隆到临时目录]\n F -->|否| H{HTTP URL?}\n H -->|是| I[下载到临时目录]\n H -->|否| J[使用本地路径]\n \n C --> K[返回 ResolvedSource]\n E --> K\n G --> K\n I --> K\n J --> K\n```\n\n## 资产验证\n\n### 验证规则\n\n| 资产类型 | 验证项 | 错误信息 |\n|---------|--------|---------|\n| `skill` | 目录内必须包含 `SKILL.md` | `Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL` |\n| `skill` | 不支持 `http-file`/`inline-json`/`inline-md` 来源 | `Skill 目录内缺少 SKILL.md 文件` |\n| `mcp` | 文件必须存在且扩展名为 `.json` | `MCP 来源文件不存在` / `MCP 来源文件扩展名必须为 .json` |\n\n```typescript\nasync function validateAsset(\n assetType: AssetType,\n resolved: ResolvedSource,\n): Promise {\n if (assetType === 'skill') {\n if (resolved.type === 'http-file' || resolved.type === 'inline-json' || resolved.type === 'inline-md') {\n return 'Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL';\n }\n const skillMdPath = path.join(resolved.localPath, 'SKILL.md');\n try {\n await fs.promises.access(skillMdPath);\n } catch {\n return `Skill 目录内缺少 SKILL.md 文件（期望路径：${skillMdPath}）`;\n }\n return null;\n }\n // ...\n}\n```\n\n资料来源：[src/installer.ts:60-80]()\n\n## 安装执行\n\n### 资产处理器注册\n\n```typescript\nfunction getHandler(assetType: AssetType) {\n switch (assetType) {\n case 'mcp': return mcpHandler;\n case 'skill': return skillHandler;\n case 'prompt': return promptHandler;\n case 'command': return commandHandler;\n case 'subAgent': return subAgentHandler;\n }\n}\n```\n\n### 安装结果状态\n\n| 状态 | 含义 |\n|------|------|\n| `written` | 新资产写入成功 |\n| `exists` | 资产已存在，无变更 |\n| `updated` | 资产内容更新 |\n| `conflict` | 存在冲突需人工处理 |\n| `skipped` | 宿主不支持该资产类型 |\n| `error` | 安装过程出错 |\n\n### 跳过逻辑\n\n当宿主不支持某类资产时：\n\n```typescript\nconst capability = host.assets[item.assetType];\nif (!capability.supported) {\n skippedResults.push({\n job: { ... },\n status: 'skipped',\n reason: capability.reason ?? `Host ${host.id} 不支持 ${item.assetType} 类型资产`,\n });\n continue;\n}\n```\n\n资料来源：[src/installer.ts:85-95]()\n\n## 清单文件处理\n\n### 清单格式\n\n```json\n{\n \"name\": \"namespace/pack-name\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://...\" },\n { \"type\": \"skill\", \"source\": \"...\" }\n ]\n}\n```\n\n### 清单解析流程\n\n```mermaid\ngraph TD\n A[解析 --pack 清单] --> B[验证清单结构]\n B --> C[展平为 AssetDescriptor 数组]\n C --> D[合并到主输入]\n D --> E[继续标准安装流程]\n```\n\n### 字段规范\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| `name` | 是 | 格式 `namespace/pack-name`，仅允许 `[a-zA-Z0-9_-]` |\n| `assets` | 是 | 至少包含 1 项 |\n| `assets[].type` | 是 | `mcp` \\| `skill` \\| `prompt` \\| `command` \\| `subAgent` |\n| `assets[].source` | 是 | 资产来源字符串 |\n\n资料来源：[src/manifest/parser.ts:1-30]()\n\n## 环境变量\n\n| 变量名 | 用途 |\n|--------|------|\n| `AGENT_ADD_HOME` | 覆盖 `os.homedir()` 返回值，用于将 Claude Desktop / Codex 宿主安装路径重定向到临时目录，实现测试隔离 |\n\n资料来源：[vibe/system-prompt.md:1-5]()\n\n## 错误处理\n\n### 退出码规范\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 所有资产安装成功 |\n| `1` | 存在冲突（conflict）或错误（error） |\n| `2` | 参数错误、验证失败、来源无效 |\n\n```typescript\nconst hasConflicts = summary.results.some((r) => r.status === 'conflict');\nconst hasErrors = summary.results.some((r) => r.status === 'error');\n\nif (hasErrors || hasConflicts) {\n process.exit(1);\n}\n```\n\n资料来源：[src/cli.ts:35-45]()\n\n## 使用示例\n\n### 单资产安装\n\n```bash\n# 安装 MCP 服务器\nnpx -y agent-add --host cursor --mcp ./mcps/playwright.json\n\n# 安装 Skill\nnpx -y agent-add --host claude-code --skill ./skills/webapp-testing\n\n# 安装 Prompt\nnpx -y agent-add --host claude-code --prompt 'https://raw.githubusercontent.com/.../rules.md'\n```\n\n### 清单批量安装\n\n```bash\nnpx -y agent-add --host cursor --pack ./manifests/frontend.json\n```\n\n### 组合使用\n\n```bash\nnpx -y agent-add \\\n --host claude-code \\\n --mcp ./mcps/playwright.json \\\n --skill ./skills/webapp-testing \\\n --prompt '# Code Review Rules\\n\\nAlways review for security issues first.'\n\n---\n\n\n\n## 源格式与名称推断\n\n### 相关页面\n\n相关主题：[Source 模块详解](#p-source-module), [资产开发者指南](#p-asset-dev)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n- [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n- [src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n- [src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n
\n\n# 源格式与名称推断\n\n## 概述\n\n`agent-add` 项目中的源格式与名称推断模块负责将用户提供的各种来源标识符解析为统一的内部表示，并自动推断资产名称。该模块是整个安装流程的入口处理层，位于 `src/source/` 目录下。\n\n源解析系统的核心职责包括：\n\n- **识别源类型**：根据源字符串的特征（前缀、URL格式、内联内容格式）判断其类型\n- **解析源内容**：将源内容下载或读取到临时目录，供后续安装流程使用\n- **推断资产名称**：根据源的特征自动生成符合规范的资产名称\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## 源类型体系\n\n`agent-add` 支持多种源格式，通过检测源字符串的特征自动识别其类型。\n\n### 源类型分类\n\n| 源类型 | 识别规则 | 特征 | 支持的资产类型 |\n|--------|----------|------|----------------|\n| `inline-json` | 以 `{` 开头 | JSON 对象字面量 | 仅 MCP |\n| `inline-md` | 包含 `\\n` | Markdown 内容 | Prompt/Command/Sub-agent |\n| `git-ssh` | 以 `git@` 开头 | SSH 协议格式 | 所有类型 |\n| `git-https` | 以 `https://` 或 `http://` 开头，且包含 `.git` | HTTPS 协议 | 所有类型 |\n| `http-file` | 以 `https://` 或 `http://` 开头，且不包含 `.git` | HTTP 文件 URL | 除 Skill 外的所有类型 |\n| `local` | 其他情况 | 本地文件路径 | 所有类型 |\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n### 类型识别流程\n\n```mermaid\ngraph TD\n A[输入源字符串] --> B{以 `{` 开头?}\n B -->|是| C{包含 `\\n`?}\n B -->|否| D{以 `git@` 开头?}\n C -->|是| E[inline-md]\n C -->|否| F[inline-json]\n D -->|是| G[git-ssh]\n D -->|否| H{以 `http` 开头?}\n H -->|是| I{包含 `.git`?}\n I -->|是| J[git-https]\n I -->|否| K[http-file]\n H -->|否| L[local]\n \n style E fill:#90EE90\n style F fill:#87CEEB\n style G fill:#FFD700\n style J fill:#FFD700\n style K fill:#FFA500\n style L fill:#DDA0DD\n```\n\n## 名称推断规则\n\n名称推断模块 `infer-name.ts` 负责从源字符串中提取或生成资产名称。不同源类型遵循不同的命名规则。\n\n### 推断规则优先级\n\n| 优先级 | 条件 | 命名规则 | 示例 |\n|--------|------|----------|------|\n| 0 | 内联 JSON | 提取单个顶层键 | `{\"playwright\":{...}}` → `playwright` |\n| 0 | 内联 Markdown | 提取首个 `# Heading` 并转 kebab-case | `# Code Review` → `code-review` |\n| 1 | 包含 `#path` | 使用 `#` 后的路径段（去掉扩展名） | `...git#skills/pdf` → `pdf` |\n| 2 | Git URL 无 `#path` | 提取仓库名（去掉 `.git` 后缀） | `...playwright.git` → `playwright` |\n| 3 | 本地路径/HTTP 文件 | 提取文件名（去掉扩展名） | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n### 详细规则说明\n\n#### 内联 JSON（inline-json）\n\n当源以 `{` 开头时，系统将其解析为 JSON 对象。如果格式为 `{\"\":{...}}`，直接提取 `` 作为资产名称。\n\n```typescript\n// 有效的内联 JSON 格式\n{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}\n// 推断名称: playwright\n```\n\n如果 JSON 包含 `mcpServers` 包装格式，系统会自动展开后提取名称：\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n// 推断名称: playwright\n```\n\n资料来源：[src/source/infer-name.ts:14-35](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n#### 内联 Markdown（inline-md）\n\n当源包含换行符 `\\n` 时，系统将其识别为内联 Markdown。名称从首个 `# Heading` 提取，并转换为 kebab-case 格式：\n\n```typescript\n# Code Review Rules\n// 推断名称: code-review\n```\n\n**限制**：内联 Markdown 格式仅支持 Prompt、Command 和 Sub-agent 类型的资产，不支持 Skill 类型。资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n#### Git URL 路径引用（#path）\n\nGit 源支持 `#path` 语法指定仓库内的子路径。名称从 `#` 后的路径段提取，去掉文件扩展名：\n\n```bash\nhttps://github.com/anthropics/skills.git#skills/webapp-testing\n// 推断名称: webapp-testing\n```\n\n```bash\nhttps://github.com/modelcontextprotocol/servers.git#.mcp.json\n// 推断名称: mcp.json → mcp\n```\n\n资料来源：[src/source/infer-name.ts:36-40](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n#### Git URL 无路径引用\n\n如果 Git URL 不包含 `#path`，系统从仓库 URL 中提取名称：\n\n```bash\nhttps://github.com/anthropics/skills.git\n// 推断名称: skills\n```\n\n```bash\ngit@github.com:anthropics/claude-code-skills.git\n// 推断名称: claude-code-skills\n```\n\n#### 本地路径和 HTTP 文件\n\n对于本地文件路径或普通 HTTP 文件 URL，名称从文件名提取：\n\n```bash\n./mcps/playwright.json\n// 推断名称: playwright\n```\n\n```bash\nhttps://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs/.cursorrules\n// 推断名称: .cursorrules → cursorrules\n```\n\n## 源解析器实现\n\n### 模块结构\n\n```mermaid\ngraph LR\n A[src/source/index.ts] --> B[infer-name.ts]\n A --> C[git.ts]\n A --> D[http-file.ts]\n A --> E[local.ts]\n A --> F[inline.ts]\n \n C --> G[解析 Git 仓库]\n D --> H[下载 HTTP 文件]\n E --> I[读取本地文件]\n F --> J[写入临时文件]\n```\n\n### Git 解析器\n\n`git.ts` 负责处理 Git 仓库源的解析，支持稀疏检出（sparse checkout）功能。\n\n**核心功能**：\n\n- 支持 `git@` SSH 格式和 `https://` HTTP 格式\n- 支持 `#path` 语法指定子目录或文件\n- 使用 `git init` + `git remote add` + `git fetch` + `git checkout` 实现稀疏检出\n\n资料来源：[src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n\n### HTTP 文件解析器\n\n`http-file.ts` 负责从 HTTP/HTTPS URL 下载单个文件。\n\n**限制**：\n\n- 仅支持 Prompt、Command、Sub-agent 和 MCP 类型的资产\n- **不支持** Skill 类型资产（HTTP 源安装 Skill 会导致错误，退出码 2）\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts) 和 [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n\n### 本地路径解析器\n\n`local.ts` 负责读取本地文件系统中的源文件或目录。\n\n**功能**：\n\n- 支持单个文件路径\n- 支持目录路径（会递归处理目录内容）\n- 对于目录源，系统会遍历目录并将每个文件作为独立资产处理\n\n资料来源：[src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n\n### 内联内容解析器\n\n`inline.ts` 负责将内联内容写入临时文件，供后续处理流程使用。\n\n**处理流程**：\n\n1. 根据内容类型（JSON 或 Markdown）确定文件扩展名\n2. 在系统临时目录中创建唯一命名的临时文件\n3. 将内容写入临时文件\n4. 返回临时文件路径，供后续处理使用\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n\n## 错误处理\n\n### 内联 JSON 解析错误\n\n```typescript\n// 如果 JSON 格式错误\n内联 JSON 解析失败。格式应为 {\"\":{...}}，例如：{\"playwright\":{\"command\":\"npx\",\"args\":[\"-y\",\"@playwright/mcp\"]}}\n```\n\n### 内联类型不匹配\n\n```typescript\n// HTTP 源安装 Skill 时\nagent-add error: HTTP sources cannot install Skill assets\n```\n\n```typescript\n// 内联源安装 Skill 时\nagent-add error: Inline sources cannot install Skill assets\n```\n\n### 名称推断失败\n\n当无法从源字符串推断有效名称时，系统会报错并退出。\n\n## 与其他模块的交互\n\n源解析模块位于 `agent-add` 安装流程的前端，解析结果传递给后续模块：\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[源格式识别]\n B --> C{识别源类型}\n C --> D[名称推断]\n D --> E[解析源内容]\n E --> F[验证资产]\n F --> G[构建安装任务]\n G --> H[执行安装]\n \n D --> D1[infer-name.ts]\n E --> E1[git.ts / http-file.ts / local.ts / inline.ts]\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 最佳实践\n\n### 源格式选择建议\n\n| 场景 | 推荐格式 | 示例 |\n|------|----------|------|\n| MCP 服务器配置 | 内联 JSON | `{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}` |\n| 简单 Prompt | 内联 Markdown | `--prompt $'# Review Rules\\n\\nCheck for bugs...'` |\n| 复杂/可复用的资产 | Git URL | `https://github.com/org/skills.git#skills/pdf` |\n| 本地开发测试 | 本地路径 | `./my-skill/` |\n| 团队共享资源 | HTTP URL | `https://team.com/rules/code-review.md` |\n\n### 名称规范\n\n- 资产名称只能包含 `[a-zA-Z0-9_-]` 字符\n- MCP 类型：名称从配置文件键名推断\n- 其他类型：使用 kebab-case 格式\n\n---\n\n\n\n## 系统架构总览\n\n### 相关页面\n\n相关主题：[Source 模块详解](#p-source-module), [Host 适配器系统](#p-host-system), [核心功能使用指南](#p-usage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n
\n\n# 系统架构总览\n\n## 1. 项目概述\n\nagent-add 是一个跨主机（Host）的 AI 代理资产安装工具，用于将 MCP Servers、Skills、Prompts、Commands、Sub-agents 等资产统一安装到不同的 AI 编程工具中。\n\n项目核心目标是解决 AI 代理生态碎片化问题——每种 AI 工具（如 Cursor、Claude Code、Windsurf 等）都有自己独立的资产配置格式和存储路径，agent-add 通过抽象适配层实现了**一次定义，多端安装**的能力。\n\n## 2. 系统架构图\n\n```mermaid\ngraph TD\n subgraph CLI层\n A[CLI 入口] --> B[Commander 解析]\n B --> C[TTY 检测]\n C --> D{非 TTY 环境?}\n D -->|是| E[强制要求 --host 参数]\n D -->|否| F[交互式选择 Host]\n end\n\n subgraph 核心处理层\n G[CLI Input] --> H[显式标志能力检查]\n H --> I[Source 解析]\n I --> J[资产验证]\n J --> K[构建 InstallJob]\n K --> L[分发到对应 Handler]\n end\n\n subgraph 资产处理层\n L --> M[MCP Handler]\n L --> N[Skill Handler]\n L --> O[Prompt Handler]\n L --> P[Command Handler]\n L --> Q[Sub-agent Handler]\n end\n\n subgraph Host 适配层\n M --> R[Cursor Adapter]\n M --> S[Claude Code Adapter]\n M --> T[Codex Adapter]\n M --> U[Vibe Adapter]\n N --> R\n O --> R\n O --> S\n end\n\n R --> V[结果汇总]\n S --> V\n T --> V\n U --> V\n V --> W[Summary 输出]\n```\n\n## 3. 目录结构\n\n```\nagent-add/\n├── src/\n│ ├── index.ts # 程序入口，创建 Commander 实例\n│ ├── cli.ts # CLI 参数定义与解析\n│ ├── installer.ts # 核心编排逻辑\n│ ├── hosts/ # 主机适配层\n│ │ ├── types.ts # HostAdapter 接口定义\n│ │ ├── index.ts # 主机注册表\n│ │ ├── README.md # 能力矩阵（唯一信源）\n│ │ ├── cursor.ts\n│ │ ├── claude-code.ts\n│ │ ├── vibe.ts # TOML 格式支持\n│ │ └── ... # 其他 15 种主机适配器\n│ ├── assets/ # 资产处理器\n│ │ ├── mcp.ts # MCP 配置安装\n│ │ ├── skill.ts # Skill 目录安装\n│ │ ├── prompt.ts # Prompt 文件安装\n│ │ ├── command.ts # Command 文件安装\n│ │ └── sub-agent.ts # Sub-agent 文件安装\n│ ├── source/ # 源解析模块\n│ │ ├── resolve.ts # 源解析器\n│ │ └── infer-name.ts # 资产名称推断\n│ ├── utils/ # 工具函数\n│ │ └── unwrap-mcp-servers.js # MCP 配置解包\n│ └── summary.ts # 结果格式化输出\n├── tests/\n│ ├── unit/ # 单元测试\n│ └── features/ # Gherkin 场景测试\n└── bin/\n └── agent-add.js # 编译后的可执行文件\n```\n\n## 4. 核心数据流\n\n```mermaid\ngraph LR\n A[CLI Flags / --pack Manifest] --> B[AssetDescriptor]\n B --> C[ResolvedSource]\n C --> D[InstallJob]\n D --> E[InstallResult]\n E --> F[Summary]\n \n A1[显式标志能力检查] -.->|exit 2| A\n C1[验证失败] -.->|exit 2| C\n D1[不支持的资产] -.->|skip| D\n```\n\n### 4.1 数据模型\n\n| 模型 | 描述 | 字段 |\n|------|------|------|\n| `CliInput` | CLI 参数输入 | `pack`, `mcp`, `skill`, `prompt`, `command`, `subAgent`, `host` |\n| `AssetDescriptor` | 资产描述符 | `assetType`, `source`, `fromExplicitFlag` |\n| `ResolvedSource` | 解析后的源 | `type`, `localPath`, `tempDir`, `originalSource` |\n| `InstallJob` | 安装任务 | `assetType`, `assetName`, `resolvedSource`, `host` |\n| `InstallResult` | 安装结果 | `job`, `status`, `reason` |\n\n### 4.2 源类型（Source Types）\n\n| 类型 | 描述 | 格式示例 |\n|------|------|----------|\n| `local` | 本地文件系统路径 | `./mcps/playwright.json` |\n| `git` | Git 仓库 URL | `https://github.com/...#path/to/asset` |\n| `http-file` | HTTP/HTTPS 直接下载 | `https://example.com/config.json` |\n| `inline-json` | 内联 JSON（MCP 专用） | `{\"name\":{\"command\":\"npx\",\"args\":[...]}}` |\n| `inline-md` | 内联 Markdown（Prompt/Command/Sub-agent 专用） | `# Title\\n\\nContent...` |\n\n## 5. 模块详解\n\n### 5.1 CLI 层（src/cli.ts）\n\nCLI 层负责用户交互和参数验证：\n\n```typescript\n// 核心参数定义（资料来源：src/cli.ts）\n.option('--pack ', 'Install an Agent Pack manifest')\n.option('--mcp ', 'Install an MCP Server')\n.option('--skill ', 'Install a Skill directory')\n.option('--prompt ', 'Install a Prompt file')\n.option('--command ', 'Install a Command')\n.option('--sub-agent ', 'Install a Sub-agent')\n.option('--host ', 'Target host ID')\n```\n\n**TTY 检测逻辑**：\n\n- **TTY 环境**：用户可交互选择 Host\n- **非 TTY 环境（CI）**：必须显式指定 `--host`，否则退出并报错\n\n### 5.2 安装编排器（src/installer.ts）\n\n编排器是系统的核心，负责串联整个安装流程：\n\n| 阶段 | 函数 | 职责 |\n|------|------|------|\n| 1 | 解析输入 | 将 `CliInput` 转换为 `AssetDescriptor[]` |\n| 2 | 源解析 | 将源字符串解析为 `ResolvedSource[]` |\n| 3 | 验证 | 检查资产有效性（文件存在、格式正确） |\n| 4 | 作业构建 | 根据 Host 能力过滤，生成 `InstallJob[]` |\n| 5 | 处理器分发 | 调用对应的 `AssetHandler` |\n| 6 | 结果汇总 | 聚合所有安装结果并输出 |\n\n### 5.3 主机适配层（src/hosts/）\n\n```mermaid\nclassDiagram\n class HostAdapter {\n <>\n +id: string\n +displayName: string\n +docs: string\n +assets: Record~AssetType, AssetCapability~\n }\n \n class AssetCapability {\n +supported: boolean\n +writeStrategy: WriteStrategy\n +installDir?: string\n +configFile?: string\n +reason?: string\n }\n \n HostAdapter o-- AssetCapability\n \n CursorAdapter ..|> HostAdapter\n ClaudeCodeAdapter ..|> HostAdapter\n VibeAdapter ..|> HostAdapter\n```\n\n**当前支持的 18 种主机**：\n\n| 主机 ID | 配置文件格式 | 资产类型支持 |\n|---------|-------------|-------------|\n| `cursor` | JSON | MCP, Prompt, Command, Sub-agent |\n| `claude-code` | JSON | MCP, Prompt, Command, Sub-agent |\n| `claude-desktop` | JSON | MCP only |\n| `windsurf` | JSON | MCP, Prompt, Command |\n| `roo-code` | JSON | MCP, Prompt, Command |\n| `codex` | TOML | MCP, Prompt |\n| `vibe` | TOML | MCP, Prompt |\n| `kimi` | JSON | MCP, Prompt |\n| `trae` | JSON | MCP, Prompt |\n| `openclaw` | JSON | MCP, Prompt |\n| `gemini` | JSON | MCP, Prompt |\n| `github-copilot` | JSON | MCP, Prompt |\n| `kilo-code` | JSON | MCP, Prompt |\n| `qwen-code` | JSON | MCP, Prompt |\n| `opencode` | JSON | MCP, Prompt |\n| `augment` | JSON | MCP, Prompt |\n| `kiro` | JSON | MCP, Prompt |\n| `tabnine` | JSON | MCP, Prompt |\n\n### 5.4 资产处理器层（src/assets/）\n\n每种资产类型都有独立的处理器，统一实现 `AssetHandler` 接口：\n\n```mermaid\nflowchart LR\n subgraph AssetHandlers\n A[MCP Handler] -->|JSON shallow merge| A1[atomic write]\n B[Skill Handler] -->|directory copy| B1[SKILL.md validation]\n C[Prompt Handler] -->|marker append| C1[HTML 标记追加]\n D[Command Handler] -->|file write| D1[frontmatter parse]\n E[Sub-agent Handler] -->|host specialization| E1[agent-add/* 提升]\n end\n```\n\n| 处理器 | 写入策略 | 关键特性 |\n|--------|----------|---------|\n| `mcp.ts` | 原子写入 | JSON 浅合并、`.toml` 自动识别 |\n| `skill.ts` | 目录复制 | 递归复制、SKILL.md 存在性验证 |\n| `prompt.ts` | 追加或独立文件 | HTML 标记块（幂等追加） |\n| `command.ts` | 文件写入 | YAML frontmatter 解析 |\n| `sub-agent.ts` | 文件写入 | `agent-add//*` 主机专用字段提升 |\n\n## 6. 关键设计决策\n\n### 6.1 原子 JSON 写入\n\nMCP 配置文件使用临时文件 + 重命名的原子操作保证写入安全：\n\n```\n写入流程：config.json → .config.json.tmp → atomic rename → config.json\n```\n\n### 6.2 幂等追加策略\n\nPrompt 资产使用 HTML 注释标记实现幂等追加：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n### 6.3 TOML 格式自动识别\n\n`mcp.ts` 检测文件扩展名，`.toml` 文件自动路由到 TOML 处理路径：\n\n| 扩展名 | 解析方式 |\n|--------|----------|\n| `.json` | 标准 JSON 解析 |\n| `.toml` | smol-toml 库解析 |\n\n### 6.4 显式标志能力拒绝\n\n`installer.ts` 在构建作业前检查主机的显式标志能力声明：\n\n- `supported: false` → 输出错误信息 + README 链接，退出码 2\n- `--pack` 源跳过此检查\n\n## 7. 错误处理\n\n| 错误场景 | 退出码 | 处理方式 |\n|----------|--------|----------|\n| 非 TTY 环境未指定 `--host` | 2 | stderr 输出有效 Host 列表 |\n| 无效的资产标志 | 2 | stderr 提示有效选项 |\n| 源解析失败 | 2 | stderr 输出详细错误 |\n| 资产验证失败 | 2 | stderr 输出验证原因 |\n| 安装冲突 | 1 | 列出冲突项 |\n| 安装错误 | 1 | 列出错误详情 |\n\n## 8. 扩展指南\n\n### 8.1 添加新主机\n\n1. 创建 `src/hosts/.ts`，实现 `HostAdapter` 接口\n2. 在 `src/hosts/index.ts` 注册\n3. 更新 `src/hosts/README.md` 能力矩阵\n4. 创建 `tests/unit/hosts/.test.ts` 单元测试\n\n### 8.2 添加新资产类型\n\n1. 在 `src/assets/` 创建新处理器\n2. 实现 `AssetHandler` 接口\n3. 在 `src/installer.ts` 添加分发逻辑\n\n## 9. 相关文档\n\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md) - 项目主文档\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md) - 主机能力矩阵（唯一信源）\n- [vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md) - 系统设计提示\n\n---\n\n\n\n## Source 模块详解\n\n### 相关页面\n\n相关主题：[系统架构总览](#p-arch), [源格式与名称推断](#p-source-formats)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n- [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n- [src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n- [src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n- [src/source/expand-directory.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/expand-directory.ts)\n
\n\n# Source 模块详解\n\n## 模块概述\n\nSource 模块是 agent-add 项目的核心组件之一，负责将用户提供的资产来源（source）解析为可操作的本地文件路径。该模块支持多种来源类型，包括本地路径、Git 仓库、HTTP URL 以及内联内容，并为每种类型实现了专门的解析逻辑。\n\nSource 模块在整个安装流程中的位置至关重要：\n\n```\nCLI 输入（--mcp/--skill/--prompt/--command/--sub-agent/--pack）\n ↓\n[Source 模块] ← 资产来源解析\n ↓\nResolvedSource[]（包含 localPath 和 tempDir）\n ↓\n验证与安装\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 支持的来源类型\n\n根据源码分析，Source 模块支持以下六种来源类型：\n\n| 类型 | 标识 | 描述 |\n|------|------|------|\n| 本地路径 | `local` | 本地文件系统路径 |\n| Git SSH | `git-ssh` | `git@` 开头的 SSH 地址 |\n| Git HTTPS | `git-https` | `https://` 或 `http://` 开头的 Git 地址 |\n| HTTP 文件 | `http-file` | 直接的 HTTP/HTTPS 文件 URL |\n| 内联 JSON | `inline-json` | 以 `{` 开头的内联 JSON 字符串（仅限 MCP） |\n| 内联 Markdown | `inline-md` | 包含换行符的内联 Markdown（Prompt/Command/Sub-agent） |\n\n资料来源：[vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n## 模块架构\n\n### 目录结构\n\n```\nsrc/source/\n├── index.ts # 统一入口，类型检测与路由分发\n├── local.ts # 本地路径解析\n├── git.ts # Git 仓库解析（支持稀疏检出）\n├── http-file.ts # HTTP URL 下载解析\n├── inline.ts # 内联内容转临时文件\n└── expand-directory.ts # 目录展开（支持 glob 模式）\n```\n\n### 核心接口\n\nSource 模块的核心接口返回 `ResolvedSource` 数据结构：\n\n```typescript\ninterface ResolvedSource {\n type: SourceType; // 来源类型标识\n localPath: string; // 本地文件路径\n tempDir?: string; // 临时目录路径（内联内容专用）\n originalSource: string; // 原始输入字符串\n}\n```\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## 来源类型解析详解\n\n### 1. 本地路径解析\n\n本地路径解析器（`local.ts`）处理相对路径和绝对路径的本地文件系统引用。\n\n**工作流程：**\n\n```mermaid\ngraph TD\n A[输入 source] --> B{是否为绝对路径?}\n B -->|是| C[直接返回绝对路径]\n B -->|否| D[相对于 cwd 解析]\n D --> E{路径存在?}\n E -->|是| F[返回解析后路径]\n E -->|否| G[抛出错误: 文件不存在]\n```\n\n**关键约束：**\n- 路径必须存在且可访问\n- Skill 类型资产的本地路径必须包含 `SKILL.md` 文件\n\n资料来源：[src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n\n### 2. Git 仓库解析\n\nGit 解析器（`git.ts`）支持从 Git 仓库获取资产，支持稀疏检出（sparse checkout）语法。\n\n**Git URL 格式支持：**\n\n| 格式 | 示例 | 解析结果 |\n|------|------|----------|\n| SSH 格式 | `git@github.com:user/repo.git` | 仓库名 `repo` |\n| HTTPS 格式 | `https://github.com/user/repo.git` | 仓库名 `repo` |\n| 带路径引用 | `...git#path/to/asset` | 使用路径最后段作为名称 |\n\n**稀疏检出功能：**\n\n使用 `#` 语法可以只检出仓库中的特定路径：\n\n```bash\n# 检出仓库中的 skills/pdf 目录\nnpx -y agent-add --skill 'https://github.com/anthropics/skills.git#skills/pdf'\n```\n\nGit 解析器会自动执行稀疏检出，只下载指定路径的内容。\n\n资料来源：[src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n\n### 3. HTTP 文件解析\n\nHTTP 解析器（`http-file.ts`）从远程 URL 下载文件内容。\n\n**使用限制：**\n\n> ⚠️ **重要约束**：HTTP 来源类型**不支持** Skill 资产类型。尝试使用 HTTP URL 安装 Skill 会导致安装失败并返回错误码 2。\n\n```mermaid\ngraph TD\n A[HTTP URL] --> B{资产类型?}\n B -->|skill| C[返回错误: 不支持]\n B -->|其他类型| D[下载到临时文件]\n D --> E[返回 tempDir 路径]\n```\n\n资料来源：[src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts) \n资料来源：[vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n### 4. 内联内容解析\n\n内联解析器（`inline.ts`）将命令行中直接传入的内容写入临时文件。\n\n**两种内联格式：**\n\n| 格式 | 识别特征 | 适用资产 |\n|------|----------|----------|\n| 内联 JSON | 字符串以 `{` 开头 | MCP |\n| 内联 Markdown | 字符串包含 `\\n` 且无 JSON 特征 | Prompt/Command/Sub-agent |\n\n**内联 JSON 示例：**\n\n```bash\nnpx -y agent-add --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}'\n```\n\n解析后生成临时文件，资产名称从 JSON 对象的顶级键提取。\n\n**内联 Markdown 示例：**\n\n```bash\nnpx -y agent-add --prompt $'# Code Review\\n\\nAlways review for security issues first.'\n```\n\n解析后生成临时文件，资产名称从第一个 `# 标题` 提取并转换为 kebab-case。\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n\n### 5. 目录展开\n\nexpand-directory.ts 提供了目录批量展开功能，支持 glob 模式匹配。\n\n**典型应用场景：**\n\n当用户提供的 source 是包含多个资产的目录时，该模块负责：\n1. 扫描目录下的所有匹配文件\n2. 为每个匹配项生成独立的 `ResolvedSource`\n3. 保持目录结构在资产名称中（如 `dirName/assetName`）\n\n资料来源：[src/source/expand-directory.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/expand-directory.ts)\n\n## 资产名称推断\n\n`infer-name.ts` 模块负责从来源字符串推断资产名称，这是确保正确安装的关键步骤。\n\n### 推断规则优先级\n\n| 优先级 | 来源类型 | 推断规则 |\n|--------|----------|----------|\n| 0 | 内联 JSON | 提取单个顶级键作为名称 |\n| 0 | 内联 Markdown | 提取第一个 `# 标题` 并转为 kebab-case |\n| 1 | 带 `#` 路径 | 使用路径最后段（去除扩展名） |\n| 2 | Git URL | 使用仓库名（去除 `.git` 后缀） |\n| 3 | 本地路径/HTTP | 使用文件名（去除扩展名） |\n\n### 名称转换示例\n\n| 原始来源 | 推断名称 |\n|----------|----------|\n| `...git#skills/pdf` | `pdf` |\n| `...playwright.git` | `playwright` |\n| `./mcps/playwright.json` | `playwright` |\n| `# Code Review` → | `code-review` |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## 类型验证流程\n\n### 验证时机\n\n在 Source 模块解析完成后，`installer.ts` 会对每个 `ResolvedSource` 进行资产特定的验证：\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 输入\n participant Source as Source 模块\n participant Validator as 验证器\n participant Installer as 安装器\n\n CLI->>Source: 传入 source 字符串\n Source->>Source: 解析为 ResolvedSource\n Source->>Validator: 调用 validateAsset()\n Validator->>Validator: 根据资产类型验证\n alt 验证通过\n Validator-->>Installer: 返回 null\n else 验证失败\n Validator-->>Installer: 返回错误消息\n Installer->>Installer: 输出错误并 exit(2)\n end\n```\n\n### 各资产类型的验证规则\n\n| 资产类型 | 必需验证 | 失败条件 |\n|----------|----------|----------|\n| `skill` | SKILL.md 存在 | 目录内缺少 SKILL.md |\n| `mcp` | 文件存在 + 扩展名 | 文件不存在或非 .json 扩展名 |\n| `prompt` | 无特殊验证 | — |\n| `command` | 无特殊验证 | — |\n| `subAgent` | 无特殊验证 | — |\n\n**Skill 类型的额外限制：**\n\n```typescript\nif (assetType === 'skill') {\n if (resolved.type === 'http-file' || \n resolved.type === 'inline-json' || \n resolved.type === 'inline-md') {\n return 'Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL';\n }\n // 验证 SKILL.md 存在\n}\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 错误处理\n\nSource 模块的错误处理遵循统一的退出码规范：\n\n| 退出码 | 含义 | 触发场景 |\n|--------|------|----------|\n| 0 | 成功 | 所有资产安装成功 |\n| 1 | 部分成功 | 存在冲突或错误但可继续 |\n| 2 | 严重错误 | 参数错误、验证失败、不支持的配置 |\n\n**常见错误消息：**\n\n- `MCP 来源文件不存在：` — MCP 文件路径无效\n- `MCP 来源文件扩展名必须为 .json` — 文件类型错误\n- `Skill 目录内缺少 SKILL.md 文件` — Skill 目录结构不完整\n- `内联 JSON 解析失败` — JSON 格式错误\n\n## 与其他模块的集成\n\n### 数据流图\n\n```mermaid\ngraph LR\n subgraph Source模块\n A[local.ts] --> D[index.ts]\n B[git.ts] --> D\n C[http-file.ts] --> D\n E[inline.ts] --> D\n F[expand-directory.ts] --> D\n end\n\n subgraph Installer模块\n D --> G[validateAsset]\n G --> H[创建 InstallJob]\n end\n\n subgraph 资产处理器\n H --> I[mcp.ts]\n H --> J[skill.ts]\n H --> K[prompt.ts]\n end\n```\n\n### 关键集成点\n\n1. **CLI 层** (`src/cli.ts`)：接收用户输入，调用 `runInstaller()`\n2. **安装编排层** (`src/installer.ts`)：协调 Source 解析、验证、安装\n3. **资产处理层** (`src/assets/*.ts`)：消费 Source 模块的解析结果\n\n## 总结\n\nSource 模块是 agent-add 架构中负责来源抽象的关键层，它：\n\n- 提供了六种统一的来源类型抽象\n- 实现了健壮的错误处理和验证机制\n- 支持复杂的 Git 稀疏检出场景\n- 为内联内容提供了透明的临时文件机制\n\n理解 Source 模块的工作原理对于调试安装问题、扩展支持新的来源类型，以及深入理解整个 agent-add 系统都至关重要。\n\n---\n\n\n\n## Host 适配器系统\n\n### 相关页面\n\n相关主题：[系统架构总览](#p-arch), [核心功能使用指南](#p-usage), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/cursor.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/cursor.ts)\n- [src/hosts/claude-code.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/claude-code.ts)\n- [src/hosts/windsurf.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/windsurf.ts)\n- [src/hosts/codex.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/codex.ts)\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n- [src/utils/detect-hosts.ts](https://github.com/pea3nut/agent-add/blob/main/src/utils/detect-hosts.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n
\n\n# Host 适配器系统\n\n## 概述\n\nHost 适配器系统是 agent-add 的核心抽象层，负责将安装逻辑与具体的 AI 编程工具（Host）解耦。该系统定义了每种 Host 支持的资产类型、安装路径、写入策略等配置，使 agent-add 能够以统一的方式向不同 Host 安装 MCP Servers、Skills、Prompts、Commands 和 Sub-agents。\n\n系统当前支持 18 种主流 AI 编程工具，包括 Cursor、Claude Code、Windsurf、GitHub Copilot 等，形成了完整的主机适配矩阵。\n\n## 架构设计\n\n### 核心组件\n\n```mermaid\ngraph TD\n A[CLI 输入] --> B[installer.ts]\n B --> C[Host 注册表]\n C --> D{Host 检测?}\n D -->|是| E[detect-hosts.ts]\n D -->|否| F[使用 --host 参数]\n E --> G[返回 HostAdapter]\n F --> G\n G --> H[资产处理器]\n H --> I[MCP 处理器]\n H --> J[Skill 处理器]\n H --> K[Prompt 处理器]\n H --> L[Command 处理器]\n H --> M[Sub-agent 处理器]\n```\n\n### 目录结构\n\n```\nsrc/\n├── hosts/ # Host 适配器系统核心\n│ ├── index.ts # Host 注册表（Map）\n│ ├── types.ts # 核心类型定义\n│ ├── README.md # 主机能力矩阵（单一信息源）\n│ ├── cursor.ts # Cursor 适配器\n│ ├── claude-code.ts # Claude Code 适配器\n│ ├── windsurf.ts # Windsurf 适配器\n│ ├── codex.ts # Codex CLI 适配器\n│ └── .ts # 其他主机适配器\n└── utils/\n └── detect-hosts.ts # 自动检测当前环境中的 Host\n```\n\n## 核心类型定义\n\n### HostAdapter 接口\n\n`src/hosts/types.ts` 定义了 `HostAdapter` 接口，所有主机适配器必须实现此接口：\n\n```typescript\ninterface HostAdapter {\n readonly id: string; // 主机唯一标识符\n readonly displayName: string; // 显示名称\n readonly docs: string; // 官方文档链接\n readonly detection: HostDetection; // 检测配置\n readonly assets: Record; // 资产能力配置\n}\n```\n\n### 资产能力配置\n\n```typescript\ninterface AssetCapability {\n supported: boolean;\n reason?: string; // 不支持时说明原因\n configFile?: ConfigFilePaths; // 配置文件路径（支持多平台）\n configKey?: string; // 配置键名\n writeStrategy?: WriteStrategy; // 写入策略\n targetFile?: string; // 目标文件名\n installDir?: string; // 安装目录\n entryFile?: string; // 入口文件\n fileExtension?: string; // 文件扩展名\n}\n```\n\n### 资产类型枚举\n\n| 类型 | 说明 | 用途 |\n|------|------|------|\n| `mcp` | MCP Server 配置 | 安装 MCP 服务器 |\n| `skill` | Skill 目录 | 安装可复用技能包 |\n| `prompt` | 规则/系统提示 | 安装提示词规则 |\n| `command` | 斜杠命令 | 安装自定义命令 |\n| `subAgent` | 子代理配置 | 安装子代理 |\n\n### 写入策略\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| `inject-json-key` | 向 JSON 配置注入键值 | MCP JSON 配置 |\n| `toml-array` | 向 TOML 数组追加 | Codex/Vibe MCP TOML |\n| `append-with-marker` | 使用 HTML 注释标记追加 | Cursor AGENTS.md 等 |\n| `create-file-in-dir` | 在目录中创建文件 | Windsurf 规则文件 |\n| `copy-file` | 复制文件到目标目录 | Skill、Command 等 |\n\n## Host 注册表\n\n`src/hosts/index.ts` 维护着一个 `Map` 类型的注册表，所有适配器在此注册后即可被系统识别和使用。\n\n```mermaid\ngraph LR\n A[主机适配器文件] --> B[index.ts 注册]\n B --> C[hostRegistry Map]\n C --> D[installer.ts 查询]\n C --> E[detect-hosts.ts 检测]\n```\n\n注册表示例结构：\n\n```typescript\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['windsurf', new WindsurfAdapter()],\n ['codex', new CodexAdapter()],\n // ... 其他适配器\n]);\n```\n\n## 支持的主机列表\n\n根据 `src/hosts/README.md` 中的能力矩阵，当前支持以下 18 种主机：\n\n| 主机 ID | 显示名称 | MCP | Prompt | Skill | Command | Sub-agent |\n|---------|----------|-----|--------|-------|---------|-----------|\n| cursor | Cursor | ✅ | ✅ | ✅ | ✅ | ✅ |\n| claude-code | Claude Code | ✅ | ✅ | ✅ | ✅ | ✅ |\n| claude-desktop | Claude Desktop | ✅ | ❌ | ❌ | ❌ | ❌ |\n| windsurf | Windsurf | ✅ | ✅ | ❌ | ❌ | ❌ |\n| github-copilot | GitHub Copilot | ✅ | ✅ | ❌ | ❌ | ❌ |\n| gemini | Gemini Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| roo-code | Roo Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| kilo-code | Kilo Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| qwen-code | Qwen Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| opencode | OpenCode | ✅ | ✅ | ❌ | ❌ | ❌ |\n| augment | Augment Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| kiro | Kiro | ✅ | ✅ | ❌ | ❌ | ❌ |\n| tabnine | Tabnine | ✅ | ✅ | ❌ | ❌ | ❌ |\n| kimi | Kimi | ✅ | ✅ | ❌ | ❌ | ❌ |\n| trae | Trae | ✅ | ✅ | ❌ | ❌ | ❌ |\n| openclaw | OpenClaw | ✅ | ✅ | ❌ | ❌ | ❌ |\n| codex | Codex CLI | ✅ | ✅ | ✅ | ❌ | ✅ |\n| vibe | Vibe | ✅ | ❌ | ❌ | ❌ | ❌ |\n\n## 主机检测机制\n\n`src/utils/detect-hosts.ts` 实现了自动检测当前环境中已安装的 Host 功能。检测逻辑基于各主机的特征路径：\n\n```typescript\n// 检测配置示例\nconst detection = {\n paths: ['~/.cursor/', '.cursor/'] // Cursor 检测路径\n};\n```\n\n### 检测优先级\n\n1. **显式指定优先**：用户通过 `--host ` 参数显式指定主机\n2. **自动检测次之**：非 TTY 环境下（如 CI）必须显式指定，否则退出\n3. **交互选择兜底**：TTY 环境下提供交互式主机选择菜单\n\n## 适配器实现示例\n\n### Cursor 适配器 (`src/hosts/cursor.ts`)\n\n```typescript\nexport class CursorAdapter implements HostAdapter {\n readonly id = 'cursor';\n readonly displayName = 'Cursor';\n readonly docs = 'https://cursor.com';\n readonly detection = {\n paths: ['~/.cursor/', '.cursor/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: {\n darwin: '~/Library/Application Support/Cursor/User/globalStorage/sao-team.mcp-server-cli/hosts.json',\n linux: '~/.cursor/globalStorage/sao-team.mcp-server-cli/hosts.json',\n win32: '%APPDATA%\\\\Cursor\\\\User\\\\globalStorage\\\\sao-team.mcp-server-cli\\\\hosts.json',\n },\n writeStrategy: 'inject-json-key',\n },\n prompt: {\n supported: true,\n targetFile: 'AGENTS.md',\n writeStrategy: 'append-with-marker',\n },\n skill: {\n supported: true,\n installDir: '.cursor/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n },\n command: {\n supported: true,\n installDir: '.cursor/commands/',\n writeStrategy: 'copy-file',\n },\n subAgent: {\n supported: true,\n installDir: '.cursor/agents/',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n### Codex 适配器 (`src/hosts/codex.ts`)\n\nCodex 适配器展示了 TOML 配置的特殊处理：\n\n```typescript\nexport class CodexAdapter implements HostAdapter {\n readonly id = 'codex';\n readonly displayName = 'Codex CLI';\n readonly docs = 'https://github.com/openai/codex';\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: {\n darwin: '~/.codex/config.toml',\n linux: '~/.codex/config.toml',\n win32: '%USERPROFILE%\\\\.codex\\\\config.toml',\n },\n configKey: 'mcp_servers',\n writeStrategy: 'inject-json-key',\n },\n subAgent: {\n supported: true,\n installDir: '.codex/agents/',\n fileExtension: '.toml',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n## 新增主机适配器指南\n\n根据 `src/hosts/README.md` 的贡献指南，新增主机需要完成以下步骤：\n\n### 步骤 1：创建适配器文件\n\n在 `src/hosts/.ts` 中创建适配器类，实现 `HostAdapter` 接口：\n\n```typescript\nimport type { HostAdapter, AssetCapability, AssetType } from './types.js';\n\nconst NOT_SUPPORTED = (reason: string): AssetCapability => ({\n supported: false,\n reason,\n});\n\nexport class XxxAdapter implements HostAdapter {\n readonly id = 'xxx';\n readonly displayName = 'Xxx';\n readonly docs = 'https://xxx.com/docs';\n readonly detection = {\n paths: ['~/.xxx/'],\n };\n readonly assets: Record = {\n mcp: { /* 配置 */ },\n prompt: { /* 配置 */ },\n skill: { /* 配置 */ },\n command: { /* 配置 */ },\n subAgent: { /* 配置 */ },\n };\n}\n```\n\n### 步骤 2：注册到索引\n\n在 `src/hosts/index.ts` 的 `hostRegistry` Map 中添加新条目：\n\n```typescript\n['xxx', new XxxAdapter()]\n```\n\n### 步骤 3：更新能力矩阵\n\n在 `src/hosts/README.md` 中添加新主机的行和详细说明。\n\n### 步骤 4：添加单元测试\n\n创建 `tests/unit/hosts/.test.ts`，验证所有字段值与 README.md 完全一致。\n\n## 安装流程中的角色\n\n```mermaid\ngraph TD\n A[CLI flags / --pack Manifest] --> B[显式标志能力检查]\n B --> C[不支持则 exit 2]\n C --> D[AssetDescriptor[]]\n D --> E[源解析]\n E --> F[验证]\n F --> G[InstallJob[]]\n G --> H[跳过不支持的资产]\n H --> I[执行写入]\n I --> J[InstallResult[]]\n J --> K[Summary 输出]\n```\n\ninstaller.ts 中的关键逻辑会根据 host adapter 的配置决定：\n\n1. **能力检查**：验证目标主机是否支持该资产类型\n2. **路径解析**：根据 `configFile` 或 `installDir` 确定写入路径\n3. **策略选择**：根据 `writeStrategy` 选择对应的写入方式\n4. **结果记录**：返回 `skipped`/`written`/`exists`/`updated`/`conflict`/`error` 等状态\n\n## 不支持的资产处理\n\n当主机不支持特定资产类型时，适配器使用 `NOT_SUPPORTED(reason)` 辅助函数返回配置：\n\n```typescript\ncommand: NOT_SUPPORTED('Codex CLI does not support custom slash commands via files.')\n```\n\ninstaller.ts 会检测此配置并将相应资产标记为 `skipped`，同时输出原因说明。资料来源：[src/hosts/codex.ts:8-10]()\n\n## 关键设计决策\n\n| 决策 | 说明 | 来源 |\n|------|------|------|\n| 能力矩阵单一信息源 | `src/hosts/README.md` 是唯一的权威配置文档 | [src/hosts/README.md:1]() |\n| 原子写入 | MCP 配置使用临时文件+重命名确保安全 | [vibe/system-prompt.md:1]() |\n| 标记块追加 | Prompt 使用 HTML 注释实现幂等追加 | [vibe/system-prompt.md:1]() |\n| TOML 自动分发 | `.toml` 扩展名自动走 smol-toml 路径 | [src/hosts/codex.ts:1]() |\n| 非 TTY 严格模式 | CI 环境必须显式指定 --host | [src/hosts/README.md:1]() |\n\n## 总结\n\nHost 适配器系统通过统一的接口抽象，使 agent-add 能够以插件式架构支持多种 AI 编程工具。系统设计遵循以下原则：\n\n- **可扩展性**：新增主机只需实现 `HostAdapter` 接口并注册\n- **一致性**：能力矩阵作为单一信息源，确保文档与实现同步\n- **容错性**：不支持的资产优雅降级为 `skipped` 状态\n- **安全性**：原子写入操作避免配置损坏风险\n\n该系统已覆盖市场上主流的 18 种 AI 编程工具，并预留了完善的扩展机制以支持未来可能出现的新工具。\n\n---\n\n\n\n## CLI 参考文档\n\n### 相关页面\n\n相关主题：[核心功能使用指南](#p-usage), [安装与快速开始](#p-installation), [Pack Manifest 格式规范](#p-pack-manifest)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n
\n\n# CLI 参考文档\n\n## 概述\n\nagent-add 是一个跨宿主 AI Agent 资源安装 CLI 工具，支持将 MCP、Skill、Prompt、Command、Sub-agent 等资源安装到不同的 AI 代理宿主（如 Cursor、Claude Code、Claude Desktop 等）。CLI 模块是该工具的入口层，负责命令行参数解析、宿主检测和安装流程的编排。\n\nCLI 模块的核心职责包括：\n\n- 定义所有命令行选项和子命令\n- 检测运行环境（TTY / Non-TTY）\n- 提供交互式宿主选择功能\n- 收集用户输入并调用安装器核心逻辑\n- 输出安装结果摘要\n\n**源码位置**：`src/cli.ts` 资料来源：[src/cli.ts:1-1]()\n\n## 命令行接口架构\n\n### 入口流程\n\nCLI 模块采用 **Commander.js** 框架构建命令行界面。入口点为 `src/index.ts`，通过 `createProgram()` 创建程序实例并异步解析命令行参数。\n\n```mermaid\ngraph TD\n A[Node.js 进程启动] --> B[src/index.ts 入口]\n B --> C[createProgram 创建程序]\n C --> D[program.parseAsync 解析 argv]\n D --> E{是否有资产标志?}\n E -->|否| F[输出错误并退出 2]\n E -->|是| G{是否指定 --host?}\n G -->|是| H[使用指定宿主]\n G -->|否| I{是否为 TTY 环境?}\n I -->|否| J[输出错误并退出 2]\n I -->|是| K[交互式选择宿主]\n H --> L[runInstaller 执行安装]\n K --> L\n L --> M[printSummary 输出摘要]\n M --> N[是否存在冲突或错误?]\n N -->|是| O[exit 1]\n N -->|否| P[正常退出 0]\n```\n\n资料来源：[src/index.ts:1-10]()\n资料来源：[src/cli.ts:1-100]()\n\n### 核心数据结构\n\nCLI 模块使用 TypeScript 接口定义输入输出的数据结构：\n\n```typescript\ninterface CliInput {\n mcp: string[];\n skill: string[];\n prompt: string[];\n command: string[];\n subAgent: string[];\n pack: string[];\n host?: string;\n}\n```\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `mcp` | `string[]` | MCP 服务器配置源列表 |\n| `skill` | `string[]` | Skill 目录源列表 |\n| `prompt` | `string[]` | Prompt 文件源列表 |\n| `command` | `string[]` | Command 文件源列表 |\n| `subAgent` | `string[]` | Sub-agent 文件源列表 |\n| `pack` | `string[]` | Pack 清单文件源列表 |\n| `host` | `string \\| undefined` | 目标宿主 ID（可选） |\n\n资料来源：[src/cli.ts:30-50]()\n\n## 命令行选项\n\n### 资产安装选项\n\nagent-add 支持通过以下标志安装不同类型的资源，所有选项均支持重复使用以安装多个同类型资源：\n\n| 选项 | 说明 | 可重复 |\n|------|------|--------|\n| `--pack ` | 安装 Agent Pack 清单（批量安装） | ✅ |\n| `--mcp ` | 安装 MCP 服务器配置 | ✅ |\n| `--skill ` | 安装 Skill 目录 | ✅ |\n| `--prompt ` | 安装 Prompt 文件（系统提示词） | ✅ |\n| `--command ` | 安装 Command 文件（斜杠命令） | ✅ |\n| `--sub-agent ` | 安装 Sub-agent 文件 | ✅ |\n\n资料来源：[src/cli.ts:60-80]()\n\n### 宿主指定选项\n\n| 选项 | 说明 | 必需性 |\n|------|------|--------|\n| `--host ` | 指定目标宿主 ID | TTY 环境可选，CI 环境必填 |\n\n支持的宿主 ID 包括：`cursor`、`claude-code`、`claude-desktop`、`windsurf`、`github-copilot`、`gemini`、`roo-code`、`kilo-code`、`qwen-code`、`opencode`、`augment`、`kiro`、`tabnine`、`kimi`、`trae`、`openclaw`、`codex`、`vibe`。\n\n资料来源：[src/cli.ts:82]()\n资料来源：[src/hosts/README.md]()\n\n### 辅助选项\n\n| 选项 | 说明 |\n|------|------|\n| `-V, --version` | 显示版本号 |\n| `-h, --help` | 显示帮助信息 |\n\n## 输入验证规则\n\n### 资产标志检测\n\nCLI 模块在解析参数后首先检查是否提供了至少一个资产安装标志：\n\n```typescript\nconst hasAssetFlags =\n cliInput.pack.length > 0 ||\n cliInput.mcp.length > 0 ||\n cliInput.skill.length > 0 ||\n cliInput.prompt.length > 0 ||\n cliInput.command.length > 0 ||\n cliInput.subAgent.length > 0;\n\nif (!hasAssetFlags) {\n process.stderr.write(\n 'agent-add error: No asset flags provided. Use --pack, --mcp, --skill, --prompt, --command, or --sub-agent.\\n',\n );\n process.exit(2);\n}\n```\n\n**错误条件**：未提供任何资产安装标志时，程序输出错误信息并以退出码 2 终止。\n\n资料来源：[src/cli.ts:85-100]()\n\n### 宿主指定检测\n\n```mermaid\ngraph TD\n A[解析 CLI 参数] --> B{--host 是否指定?}\n B -->|是| C[使用指定 hostId]\n B -->|否| D{是否为 TTY?}\n D -->|否| E[输出错误: CI 环境必须指定 --host]\n D -->|是| F[进入交互式选择流程]\n E --> G[exit 2]\n F --> H[显示宿主选择列表]\n H --> I[用户选择宿主]\n I --> C\n```\n\nCLI 环境检测逻辑：\n\n```typescript\nif (cliInput.host) {\n hostId = cliInput.host;\n} else if (!process.stdout.isTTY) {\n const validIds = getValidHostIds().join(', ');\n process.stderr.write(\n `agent-add error: No host specified. In non-TTY environments, you must explicitly specify --host.\\n` +\n `Valid hosts: ${validIds}\\n`,\n );\n process.exit(2);\n}\n```\n\n**错误条件**：在非 TTY 环境下（如 CI/CD 流水线）未指定 `--host` 参数时，程序输出可用宿主列表并以退出码 2 终止。\n\n资料来源：[src/cli.ts:100-115]()\n\n## 宿主选择流程\n\n### 交互式选择\n\n当在 TTY 环境下未指定 `--host` 时，CLI 提供交互式宿主选择功能：\n\n```typescript\nconst hostSelection = await inquirer.createPromptModule()({\n type: 'select',\n message: 'Select a host to install to:',\n choices: getValidHostIds(),\n});\n\nhostId = hostSelection.host;\n```\n\n用户通过上下箭头选择目标宿主，按 Enter 确认。\n\n资料来源：[src/cli.ts:55-58]()\n\n### 有效宿主 ID 获取\n\n`getValidHostIds()` 函数从宿主注册表中获取所有已注册的有效宿主 ID：\n\n```typescript\nimport { hostRegistry } from './hosts/index.js';\n\nexport function getValidHostIds(): string[] {\n return [...hostRegistry.keys()];\n}\n```\n\n资料来源：[src/cli.ts:15-20]()\n\n## 安装流程编排\n\n### 安装执行\n\n选定宿主后，CLI 模块调用 `runInstaller()` 函数执行实际的安装逻辑：\n\n```typescript\nconst cwd = process.cwd();\nconst summary = await runInstaller(cliInput, host, cwd);\nprintSummary(summary);\n```\n\n- `cwd`：当前工作目录，作为相对路径解析的基准\n- `cliInput`：解析后的 CLI 输入参数\n- `host`：选定的宿主适配器实例\n\n资料来源：[src/cli.ts:120-123]()\n\n### 结果处理\n\n安装完成后，CLI 根据结果状态决定退出码：\n\n```mermaid\ngraph TD\n A[runInstaller 执行完成] --> B[printSummary 输出摘要]\n B --> C{是否有冲突?}\n B --> D{是否有错误?}\n C -->|是| E[exit 1]\n D -->|是| E\n C -->|否| F{是否有错误?}\n F -->|是| E\n F -->|否| G[正常退出 0]\n D -->|否| C\n```\n\n错误检测逻辑：\n\n```typescript\nconst hasConflicts = summary.results.some((r) => r.status === 'conflict');\nconst hasErrors = summary.results.some((r) => r.status === 'error');\n\nif (hasErrors || hasConflicts) {\n process.exit(1);\n}\n```\n\n| 退出码 | 条件 | 说明 |\n|--------|------|------|\n| 0 | 无冲突、无错误 | 安装全部成功或部分资源已存在 |\n| 1 | 存在冲突或错误 | 需用户介入解决 |\n| 2 | CLI 参数错误 | 无效参数或缺少必需参数 |\n\n资料来源：[src/cli.ts:125-132]()\n\n## 使用示例\n\n### 基本安装\n\n```bash\n# 安装 MCP 服务器\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#python/playwright'\n\n# 安装 Skill\nnpx -y agent-add --host claude-code --skill './my-skill'\n\n# 安装 Prompt（内联 Markdown）\nnpx -y agent-add --host cursor \\\n --prompt $'# Code Review Rules\\n\\nAlways review for security issues first.'\n\n# 安装 Command\nnpx -y agent-add --host cursor --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### 批量安装（Pack）\n\n```bash\n# 从 Pack 清单批量安装\nnpx -y agent-add --host cursor --pack 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n\n# 组合使用\nnpx -y agent-add --host cursor \\\n --pack 'https://github.com/my-team/packs.git#frontend' \\\n --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}'\n```\n\n### CI 环境使用\n\n```yaml\n# .github/workflows/install-agents.yml\n- name: Install Agent Assets\n run: |\n npx -y agent-add --host cursor --pack './configs/agent-pack.json'\n```\n\nCI 环境下**必须**显式指定 `--host` 参数。\n\n## 编译与运行\n\n### 项目脚本\n\n`package.json` 中定义了以下与 CLI 相关的脚本：\n\n| 脚本 | 说明 | 源码 |\n|------|------|------|\n| `npm run build` | 使用 tsup 构建，输出 `dist/index.js`（单文件 CJS bundle） | tsup 配置 |\n| `npm run dev` | tsup watch 开发模式 | - |\n| `npm test` | 运行 vitest 单元和集成测试 | - |\n| `npm run test:contract` | 仅运行 CLI 黑盒契约测试 | - |\n\n资料来源：[package.json:20-35]()\n\n### CLI 入口点\n\n项目通过 `bin/agent-add.js` 作为 CLI 入口：\n\n```json\n{\n \"bin\": {\n \"agent-add\": \"./dist/index.js\"\n }\n}\n```\n\n`dist/index.js` 是编译后的入口文件，定义了 shebang 和模块引用。\n\n资料来源：[package.json:8-11]()\n\n### 运行时依赖\n\nCLI 运行所需的依赖：\n\n| 依赖 | 版本 | 用途 |\n|------|------|------|\n| `commander` | ^14.0.3 | 命令行参数解析 |\n| `@inquirer/select` | ^5.1.2 | 交互式宿主选择 |\n| `yaml` | ^2.8.2 | YAML 文件解析（Skill/Command/Sub-agent） |\n| `zod` | ^4.3.6 | 配置验证 |\n| `smol-toml` | ^1.6.1 | TOML 文件读写（Codex/Vibe） |\n\n资料来源：[package.json:30-45]()\n\n## 模块关系图\n\n```mermaid\ngraph TD\n subgraph \"入口层\"\n A[bin/agent-add.js] --> B[src/index.ts]\n B --> C[src/cli.ts]\n end\n \n subgraph \"宿主层\"\n C --> D[src/hosts/index.ts]\n D --> E[src/hosts/cursor.ts]\n D --> F[src/hosts/claude-code.ts]\n D --> G[src/hosts/...其他宿主]\n end\n \n subgraph \"安装层\"\n C --> H[src/installer.ts]\n H --> I[src/assets/mcp.ts]\n H --> J[src/assets/skill.ts]\n H --> K[src/assets/prompt.ts]\n H --> L[src/assets/command.ts]\n H --> M[src/assets/sub-agent.ts]\n end\n \n subgraph \"工具层\"\n H --> N[src/source/resolve-source.ts]\n H --> O[src/source/infer-name.ts]\n H --> P[src/hosts/summary.ts]\n end\n \n C --> Q[@inquirer/select 交互选择]\n H --> R[fs 文件系统操作]\n```\n\n## 错误处理\n\n### CLI 层错误\n\n| 错误类型 | 错误信息 | 退出码 | 处理方式 |\n|----------|----------|--------|----------|\n| 无资产标志 | `agent-add error: No asset flags provided...` | 2 | 添加至少一个资产安装选项 |\n| Non-TTY 未指定宿主 | `agent-add error: No host specified...` | 2 | 添加 `--host ` 参数 |\n| 无效宿主 ID | 宿主验证失败 | 2 | 使用有效宿主 ID |\n| 安装器内部错误 | `agent-add error: ` | 2 | 检查错误信息并重试 |\n\n资料来源：[src/cli.ts:90-95]()\n资料来源：[src/cli.ts:105-110]()\n\n### 安装层错误\n\n安装器核心 (`src/installer.ts`) 负责处理以下错误：\n\n- 资源解析失败\n- 资产验证失败\n- 文件系统操作失败\n- 资产类型不支持\n\n安装层错误统一通过 `process.stderr.write()` 输出并以退出码 2 终止。\n\n资料来源：[src/installer.ts:1-50]()\n\n## 最佳实践\n\n1. **CI 环境**：始终显式指定 `--host` 参数，避免交互式选择导致的阻塞\n2. **批量安装**：优先使用 `--pack` 选项，通过清单文件管理多个资源\n3. **内联内容**：对于简单配置，可使用内联 JSON/Markdown 避免额外文件\n4. **版本管理**：使用 `npm run build` 确保最新代码编译后再执行\n5. **测试验证**：修改 CLI 代码后运行 `npm test` 验证兼容性\n\n---\n\n\n\n## Pack Manifest 格式规范\n\n### 相关页面\n\n相关主题：[资产开发者指南](#p-asset-dev), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n
\n\n# Pack Manifest 格式规范\n\n## 概述\n\nPack Manifest 是一种 JSON 格式的配置文件，用于捆绑和分发多个 agent-add 资产（Asset）。开发者可以将 MCP Server、Skill、Prompt、Command、Sub-agent 等多种类型的资产打包为单个 Manifest 文件，通过 `agent-add --pack ` 命令一次性安装全部资产。\n\nManifest 文件简化了资产分发流程，尤其适合团队共享或跨项目复用。接收方只需一条命令即可完成所有资产的安装。\n\n## 核心数据结构\n\n```json\n{\n \"name\": \"namespace/pack-name\",\n \"assets\": [\n { \"type\": \"\", \"source\": \"\" }\n ]\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `name` | string | 是 | 格式为 `namespace/pack-name`，命名空间与包名之间用斜杠分隔 |\n| `assets` | array | 是 | 资产数组，至少包含 1 个元素 |\n\n## name 字段规范\n\n### 格式要求\n\nManifest 的 `name` 字段必须符合 `namespace/pack-name` 格式，其中：\n\n- **命名空间（namespace）**：标识资产包的分发组织或作者\n- **包名（pack-name）**：标识具体的资产包\n\n### 字符限制\n\n`name` 字段仅允许使用以下字符：`[a-zA-Z0-9_-]`\n\n**示例：**\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [...]\n}\n```\n\n### 错误处理\n\n当 `name` 字段不符合规范时，agent-add 将输出错误信息并以退出码 2 终止：\n\n```\nagent-add error: Manifest name must match namespace/pack-name format\n```\n\n资料来源：[src/manifest/parser.ts:32-36]()\n\n## assets 数组规范\n\n### 资产类型\n\n`assets[].type` 字段定义资产类型，可选值如下：\n\n| type 值 | 说明 | 来源格式 |\n|---------|------|----------|\n| `mcp` | MCP Server 配置 | JSON 文件 |\n| `skill` | Skill 目录 | 包含 SKILL.md 的目录 |\n| `prompt` | Prompt/规则文件 | Markdown 文件 |\n| `command` | 命令文件 | Markdown 文件 |\n| `subAgent` | 子代理配置 | Markdown 文件 |\n\n### source 字段\n\n`source` 字段支持多种来源格式，agent-add 根据前缀自动识别来源类型：\n\n| 来源格式 | 类型标识 | 说明 |\n|----------|----------|------|\n| 本地目录路径 | `local-dir` | 本地文件系统目录 |\n| `https://` 开头 | `http-file` | HTTP/HTTPS URL 下载 |\n| `git@` 或 `.git` 结尾 | `git` | Git 仓库 URL |\n| `{` 开头 | `inline-json` | 内联 JSON（MCP 类型专用） |\n| 包含 `\\n` | `inline-md` | 内联 Markdown（Prompt/Command/Sub-agent 专用） |\n\n### 来源名称推断规则\n\n资产名称（asset name）根据 `source` 字段自动推断：\n\n```mermaid\ngraph TD\n A[source 输入] --> B{包含 `#` 路径锚点?}\n B -->|是| C[取 `#` 后的最后一段
移除扩展名]\n B -->|否| D{Git URL?}\n D -->|是| E[取仓库名
移除 `.git` 后缀]\n D -->|否| F[取文件名
移除扩展名]\n C --> G[推断为 asset name]\n E --> G\n F --> G\n```\n\n| 来源格式 | 推断规则 | 示例 |\n|----------|----------|------|\n| 带 `#path` | 取最后路径段，去扩展名 | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#` | 取仓库名，去 `.git` | `...playwright.git` → `playwright` |\n| 本地路径/HTTP | 取文件名，去扩展名 | `./mcps/playwright.json` → `playwright` |\n| 内联 JSON | 取顶层键名 | `{\"playwright\":{...}}` → `playwright` |\n| 内联 Markdown | 取首个 `#` 标题，转 kebab-case | `# Code Review` → `code-review` |\n\n资料来源：[src/source/infer-name.ts:1-53]()\n\n## 完整示例\n\n### 基础示例\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n### 实际使用示例\n\n以下示例来自 vibe 开发包：\n\n```json\n{\n \"name\": \"agent-add/vibe\",\n \"assets\": [\n { \"type\": \"subAgent\", \"source\": \"https://github.com/pea3nut/scenario-test.git#sub-agents/verify-host-readme\" },\n { \"type\": \"prompt\", \"source\": \"vibe/system-prompt.md\" },\n { \"type\": \"command\", \"source\": \"vibe/tasks/verify-host-readme.md\" }\n ]\n}\n```\n\n资料来源：[vibe/manifest.json]()\n\n## 安装流程\n\n### 处理流程\n\n```mermaid\ngraph TD\n A[--pack ] --> B[下载/读取 Manifest]\n B --> C[解析 JSON]\n C --> D{解析成功?}\n D -->|失败| E[输出 Zod 验证错误
exit 2]\n D -->|成功| F[遍历 assets 数组]\n F --> G[解析 source URI]\n G --> H{验证资产类型}\n H -->|无效| I[输出错误
exit 2]\n H -->|有效| J[推断 asset name]\n J --> K[分发至各资产处理器]\n```\n\n### 显式标志能力检查\n\n使用 `--pack` 安装时，Manifest 中的资产会被分发到对应的处理器。如果某些资产类型目标主机不支持，该资产会被**静默跳过**（skipped），而不是报错退出。\n\n这与显式标志（如 `--mcp`、`--skill`）的行为不同——显式标志会在主机不支持时直接报错退出。\n\n### 验证规则\n\n#### 资产类型验证\n\n不支持的 `type` 值会触发错误：\n\n```\nagent-add error: Unsupported asset type: ''. Supported: mcp, skill, prompt, command, subAgent\n```\n\n#### Skill 特殊限制\n\nSkill 类型的资产**不支持**以下来源格式：\n\n- `http-file`：HTTP/HTTPS URL\n- `inline-json`：内联 JSON\n- `inline-md`：内联 Markdown\n\nSkill 必须指向目录来源（本地路径或 Git URL）。\n\n#### MCP 特殊限制\n\nMCP 类型的资产**必须**满足以下条件：\n\n- 来源文件必须存在\n- 文件扩展名必须为 `.json`\n\n#### 缺失字段处理\n\n```typescript\nif (isTypeField) {\n // 输出不支持的类型错误\n} else if (isNameField && message.includes('namespace/pack-name')) {\n // 输出名称格式错误\n} else {\n // 输出缺失字段错误\n process.stderr.write(`agent-add error: Manifest missing required field: ${fieldPath || 'unknown'}\\n`);\n}\n```\n\n资料来源：[src/manifest/parser.ts:12-44]()\n\n## 字段验证规范\n\n### Zod Schema 验证\n\nManifest 使用 Zod 进行运行时验证，关键规则包括：\n\n| 规则 | 字段 | 错误信息 |\n|------|------|----------|\n| 必填 | `name` | Manifest missing required field: name |\n| 格式 | `name` | Manifest name must match namespace/pack-name format |\n| 必填 | `assets` | Manifest missing required field: assets |\n| 非空 | `assets` | 至少包含 1 个元素 |\n| 必填 | `assets[].type` | Manifest missing required field: assets[].type |\n| 枚举 | `assets[].type` | Unsupported asset type: '' |\n| 必填 | `assets[].source` | Manifest missing required field: assets[].source |\n\n### 错误信息输出格式\n\n所有错误均输出至 `stderr`，格式为：\n\n```\nagent-add error: <具体错误描述>\n <额外信息或修复建议>\n```\n\n## 与 CLI 参数的对比\n\n| 特性 | `--pack` | 显式标志 |\n|------|----------|----------|\n| 安装多个同类型资产 | ✓ | ✓ (多次使用) |\n| 组合不同类型资产 | ✓ | ✓ |\n| 不支持的资产处理 | 静默跳过 | 报错退出 (exit 2) |\n| 来源格式 | 仅目录/URL | 支持内联内容 |\n\n## 最佳实践\n\n1. **命名规范**：使用有意义的 `namespace`（如团队名、作者名），使包名具有描述性\n2. **来源可靠性**：优先使用稳定的 Git URL，避免直接引用可能失效的 HTTP URL\n3. **版本锁定**：Git 来源可使用 `#ref` 语法锁定特定版本或 commit\n4. **资产组织**：相关资产放在同一 Manifest 中，减少分发复杂度\n\n## 参考资料\n\n- [Manifest 解析器实现](src/manifest/parser.ts)\n- [Manifest Schema 定义](src/manifest/schema.ts)\n- [名称推断逻辑](src/source/infer-name.ts)\n- [安装器核心逻辑](src/installer.ts)\n- [vibe 开发包示例](vibe/manifest.json)\n\n---\n\n\n\n## 资产开发者指南\n\n### 相关页面\n\n相关主题：[Pack Manifest 格式规范](#p-pack-manifest), [源格式与名称推断](#p-source-formats)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/codex.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/codex.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n
\n\n# 资产开发者指南\n\n## 概述\n\n资产开发者指南是 agent-add 项目为第三方开发者提供的**文件格式规范文档**。该指南定义了 agent-add 所支持的五种资产类型的结构要求、命名规则和格式约束，使开发者能够创建可被 agent-add 正确安装和分发的 MCP 服务器、Skill、Prompt、Command 和 Sub-agent 资产。\n\nagent-add 作为跨主机的 AI 工具资产安装器，支持 18 种主流 AI 编程工具（包括 Cursor、Claude Code、Codex 等），资产开发者通过遵循本指南创建的资产，可实现一次编写、多端复用的分发目标。资料来源：[README.md:98-115]()\n\n## 资产类型概述\n\nagent-add 支持的资产类型及其核心特征如下：\n\n| 资产类型 | 用途 | 安装目标 | 写入策略 |\n|---------|------|---------|---------|\n| MCP | Model Context Protocol 服务器配置 | 主机 MCP 配置文件 | JSON 浅合并或 TOML 注入 |\n| Skill | 可复用的 Agent 技能包 | 技能目录 | 目录递归复制 |\n| Prompt | 规则文件/系统提示词 | AGENTS.md 或规则目录 | HTML 标记追加或独立文件 |\n| Command | 斜杠命令定义 | commands 目录 | 独立文件写入 |\n| Sub-agent | 子代理配置 | agents 目录 | TOML 文件写入 |\n\n## MCP 配置文件规范\n\n### 支持的 JSON 格式\n\nMCP 资产支持两种 JSON 格式，agent-add 会自动检测并解析：\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"],\n \"env\": {}\n}\n```\n\n格式 A 为**内层配置（单服务器）**，资产名称从文件名推断：`playwright.json` → 名称为 `playwright`。资料来源：[README.md:105-113]()\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n```\n\n格式 B 为**完整配置包装**，agent-add 自动解包 `mcpServers` 并提取内部服务器名称和配置。资料来源：[README.md:115-120]()\n\n### TOML 配置支持\n\nCodex 和 Vibe 等主机使用 TOML 格式存储 MCP 配置。agent-add 在检测到 `.toml` 扩展名时自动调度到 smol-toml 处理路径。资料来源：[vibe/system-prompt.md:17]()\n\n### 名称推断规则\n\n资产名称推断遵循以下优先级规则：\n\n| 场景 | 推断逻辑 | 示例 |\n|------|---------|------|\n| 源包含 `#path` | 取路径最后段（去除扩展名） | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#path` | 取仓库名（去除 `.git` 后缀） | `...playwright.git` → `playwright` |\n| 本地路径/HTTP URL | 取文件名（去除扩展名） | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts:1-40]()\n\n### 验证规则\n\nMCP 资产在安装前必须通过以下验证：\n\n1. **文件存在性检查**：MCP 来源文件必须存在于本地路径\n2. **扩展名验证**：文件扩展名必须为 `.json`\n3. **来源类型限制**：`http-file`、`inline-json`、`inline-md` 类型的来源不允许安装为 Skill 类型资产，但 MCP 允许 `inline-json`（格式为 `{\"name\":{...}}`，key 为资产名称）资料来源：[src/installer.ts:78-85]()\n\n## Skill 资产规范\n\n### 目录结构要求\n\nSkill 必须是一个完整的目录，目录内**必须包含** `SKILL.md` 文件作为入口点：\n\n```\nmy-skill/\n├── SKILL.md # 必需：技能元数据和描述\n├── helpers/\n│ └── utils.py # 可选：辅助脚本\n└── templates/\n └── report.md # 可选：模板文件\n```\n\n```markdown\n\n---\nname: my-skill\ndescription: A reusable agent skill.\n---\n\n# Skill: my-skill\n\nThis skill does something useful.\n```\n\n整个目录会被递归复制到主机的技能目录（如 `.cursor/skills/my-skill/`）。资料来源：[README.md:85-96]()\n\n### 验证规则\n\nSkill 资产具有最严格的来源限制：\n\n```typescript\nif (assetType === 'skill') {\n if (resolved.type === 'http-file' || resolved.type === 'inline-json' || resolved.type === 'inline-md') {\n return 'Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL';\n }\n const skillMdPath = path.join(resolved.localPath, 'SKILL.md');\n try {\n await fs.promises.access(skillMdPath);\n } catch {\n return `Skill 目录内缺少 SKILL.md 文件（期望路径：${skillMdPath}）`;\n }\n}\n```\n\nSkill 资产**必须**使用目录来源（本地路径或 Git URL），不支持内联内容或直接的 HTTP(S) URL 下载。资料来源：[src/installer.ts:56-65]()\n\n### 主机适配差异\n\n不同主机的 Skill 安装路径和策略不同：\n\n```typescript\nskill: {\n supported: true,\n installDir: '.codex/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n}\n```\n\nCodex 适配器将 Skill 安装到 `.codex/skills/` 目录，使用 `copy-file` 写入策略。资料来源：[src/hosts/codex.ts:28-31]()\n\n## Prompt 资产规范\n\n### 格式要求\n\nPrompt 是纯 Markdown 文件，无特殊格式要求：\n\n```markdown\n# Code Review Rules\n\nAlways review for security issues first.\nUse bullet points for lists.\n```\n\nagent-add 自动根据主机选择写入策略。资料来源：[README.md:98-103]()\n\n### 写入策略\n\n#### 追加模式\n\nCursor、Claude Code 等主机使用追加模式，Content 被包装在 HTML 注释标记中并追加到文件，确保幂等性：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n#### 独立文件模式\n\nWindsurf、Roo Code 等主机使用独立文件模式，在规则目录中创建 `.md` 文件：\n\n```typescript\nprompt: {\n supported: true,\n targetFile: 'AGENTS.md',\n writeStrategy: 'append-with-marker',\n}\n```\n\n资料来源：[src/hosts/codex.ts:22-25]()\n\n## Command 资产规范\n\n### 格式要求\n\nCommand 文件支持可选的 YAML frontmatter：\n\n```markdown\n---\ndescription: Run a comprehensive code review.\n---\n\n# code-review\n\nReview the current file for bugs, security issues, and style violations.\n```\n\n安装到主机的 commands 目录（如 `.cursor/commands/code-review.md`）。资料来源：[README.md:133-139]()\n\n## Sub-agent 资产规范\n\n### 格式要求\n\nSub-agent 文件使用 Markdown + YAML frontmatter 格式，支持 **`agent-add//` 主机特化语法**——单个文件可为不同主机提供不同的 frontmatter 字段值。资料来源：[README.md:141-154]()\n\n### 主机特化示例\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-add/cursor/model: fast\nagent-get/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n\nPlan and generate Playwright tests.\n```\n\n安装过程中 agent-add 会：\n1. **提升**匹配的 `agent-add//*` 值为顶层键\n2. **移除**所有 `agent-add/*` 前缀的键\n\n资料来源：[README.md:154-163]()\n\n## Pack 清单规范\n\n### 文件格式\n\nPack 是一个 JSON 文件，捆绑多个资产用于分发：\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n### 字段规范\n\n| 字段 | 必填 | 描述 |\n|------|------|------|\n| `name` | 是 | 格式 `namespace/pack-name`，仅允许 `[a-zA-Z0-9_-]` |\n| `assets` | 是 | 至少 1 个元素 |\n| `assets[].type` | 是 | `mcp` \\| `skill` \\| `prompt` \\| `command` \\| `subAgent` |\n| `assets[].source` | 是 | 来源路径、URL 或内联内容 |\n\n### CLI 安装方式\n\n```bash\nnpx -y agent-add --host cursor --pack 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n```\n\n多个 pack 可以与显式标志自由组合使用：\n\n```bash\nnpx -y agent-add --host cursor \\\n --pack './my-pack.json' \\\n --mcp './mcps/playwright.json'\n```\n\n资料来源：[src/cli.ts:22-33]()\n\n## 来源解析架构\n\n### 解析流程\n\n```mermaid\ngraph TD\n A[CLI 输入] --> B[显式标志能力检查]\n B --> C[AssetDescriptor 数组]\n C --> D[源解析器]\n D --> E[ResolvedSource 数组]\n E --> F[验证]\n F --> G[InstallJob 数组]\n G --> H[安装处理]\n H --> I[InstallResult 数组]\n I --> J[摘要输出]\n```\n\n### 解析类型判定\n\n| 源格式 | 检测规则 | 解析类型 |\n|--------|---------|---------|\n| 以 `{` 开头 | JSON 解析 | `inline-json` |\n| 包含 `\\n` | 非 JSON | `inline-md` |\n| Git URL 含 `#path` | 路径提取 | `git-file` 或 `git-dir` |\n| 本地路径 | 文件系统访问 | `local-file` 或 `local-dir` |\n| HTTP(S) URL | 网络请求 | `http-file` |\n\n`inline-json` 仅适用于 MCP 资产，`inline-md` 仅适用于 Prompt/Command/Sub-agent。资料来源：[vibe/system-prompt.md:22-24]()\n\n## 关键设计决策\n\n### 原子 JSON 写入\n\nMCP 配置使用临时文件 + 重命名的策略确保写入安全：\n\n```typescript\n// mcp.ts 使用 temp file + rename\nawait fs.promises.writeFile(tempPath, JSON.stringify(config, null, 2));\nawait fs.promises.rename(tempPath, configFile);\n```\n\n资料来源：[vibe/system-prompt.md:18]()\n\n### 标记块幂等追加\n\nPrompt 的 `append-with-marker` 策略使用 `` HTML 注释确保幂等性：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n重复安装不会导致内容重复追加。资料来源：[vibe/system-prompt.md:19]()\n\n### 显式标志拒绝\n\n`installer.ts` 在构建任务前检查显式标志能力声明。`supported: false` 会输出错误信息和 README 链接并以退出码 2 终止。`--pack` 来源不受此检查约束。资料来源：[vibe/system-prompt.md:21]()\n\n### 非 TTY 严格模式\n\nCI 环境必须显式指定 `--host`，否则以退出码 2 终止。这确保自动化环境中不会误用默认主机。资料来源：[vibe/system-prompt.md:23]()\n\n## 主机能力矩阵\n\n添加新主机适配器时，必须遵循以下贡献流程：\n\n1. **创建适配器文件**：`src/hosts/.ts`\n - 导出实现 `HostAdapter` 接口的类\n - 硬编码所有配置字段\n - 对不支持的资产类型使用 `NOT_SUPPORTED(reason)` 辅助函数\n\n2. **注册到 index.ts**：将 `['', new XxxAdapter()]` 添加到 `src/hosts/index.ts` 的 `hostRegistry` Map\n\n3. **更新 README**：在能力矩阵表中添加行，并在详情区添加新主机段\n\n4. **添加单元测试**：创建 `tests/unit/hosts/.test.ts`，验证每个字段值与 README 完全一致\n\n```typescript\nexport class CodexAdapter implements HostAdapter {\n readonly id = 'codex';\n readonly displayName = 'Codex CLI';\n readonly docs = 'https://github.com/openai/codex';\n readonly detection = { paths: ['~/.codex/'] };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: { darwin: '~/.codex/config.toml', ... },\n configKey: 'mcp_servers',\n writeStrategy: 'inject-json-key',\n },\n // ...\n };\n}\n```\n\n资料来源：[src/hosts/codex.ts:1-45](), [src/hosts/README.md:350-365]()\n\n## 快速参考\n\n### 常用安装命令\n\n```bash\n# MCP 服务器\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'\n\n# Skill 目录\nnpx -y agent-add --host cursor --skill 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n\n# Prompt 规则\nnpx -y agent-add --host claude-code --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'\n\n# 斜杠命令\nnpx -y agent-add --host cursor --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n\n# 子代理\nnpx -y agent-add --host cursor --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'\n```\n\n### 退出码规范\n\n| 退出码 | 含义 |\n|-------|------|\n| 0 | 安装成功，无冲突 |\n| 1 | 存在冲突或错误 |\n| 2 | 参数错误或不支持的资产类型 |\n\n资料来源：[src/cli.ts:41-46]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：pea3nut/agent-add\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...。\n\n## 1. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown\n\n\n", "markdown_key": "agent-add", "pages": "draft", "source_refs": [ { "evidence_id": "art_7871f43a97e049c0ba0df6fa5a5b6e88", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/pea3nut/agent-add#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "agent-add 说明书", "toc": [ "https://github.com/pea3nut/agent-add 项目说明书", "目录", "项目首页", "项目概述", "核心能力", "系统架构", "安装流程", "安装 MCP 服务器", "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": false, "repo_commit": null, "repo_inspection_error": null, "repo_inspection_files": [], "repo_inspection_verified": false, "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-add - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 agent-add 编译的 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_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx -y agent-add \\` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等\n- `npx -y agent-add --host claude-code --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx -y agent-add --host codex --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx -y agent-add --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx -y agent-add --host claude-code \\` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0010` supported 0.86\n- `npx -y agent-add --host cursor \\` 证据：`README.md` Claim：`clm_0007` supported 0.86, `clm_0011` supported 0.86\n- `npx -y agent-add [OPTIONS]` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `npx -y agent-add --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"-y\",\"@playwright/mcp\"]}}'` 证据：`README.md` Claim：`clm_0013` supported 0.86\n- `npx -y agent-add --mcp '{\"mcpServers\":{\"playwright\":{\"command\":\"npx\",\"args\":[\"-y\",\"@playwright/mcp\"]}}}'` 证据：`README.md` Claim：`clm_0014` 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_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` 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 的默认行为。 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\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_0016` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0017` 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 体验。 证据：`tests/fixtures/skill/my-skill/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：104\n- 重要文件覆盖：36/104\n- 证据索引条目：36\n- 角色 / Skill 条目：1\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-add 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 agent-add 当作安装前体验资产，而不是已安装工具或真实运行环境。\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-add 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **my-skill**（skill）：A test skill for scenario testing. 激活提示：当用户任务与“my-skill”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n\n## 证据索引\n\n- 共索引 36 条证据。\n\n- **agent-add**（documentation）：Install MCP, Skills, slash commands, sub-agents and more into any AI tool like Claude Code, Cursor, etc. 证据：`README.md`\n- **Host Capability Matrix**（documentation）：This file is the single source of truth for all host adapter configurations in agent-add . Every adapter in src/hosts/ .ts must match the paths and capabilities documented here. 证据：`src/hosts/README.md`\n- **bad-skill**（documentation）：This directory is intentionally missing a SKILL.md file. 证据：`tests/fixtures/skill/bad-skill/README.md`\n- **Package**（package_manifest）：{ \"name\": \"agent-add\", \"version\": \"1.1.0\", \"description\": \"Cross-host AI Agent Pack installer — install MCP, Skill, Prompt, Command, Sub-agent in one command\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/pea3nut/agent-add.git\" }, \"bugs\": { \"url\": \"https://github.com/pea3nut/agent-add/issues\" }, \"homepage\": \"https://github.com/pea3nut/agent-add\", \"bin\": { \"agent-add\": \"bin/agent-add.js\" }, \"files\": \"bin\", \"docs\", \"dist\" , \"scripts\": { \"build\": \"tsup\", \"dev\": \"tsup --watch\", \"prepublishOnly\": \"npm run build\", \"test\": \"vitest run tests/unit tests/integration\", \"test:contract\": \"vitest run tests/contract\", \"test:integration\": \"vitest run tests/integration\", \"lint\": \"tsc --noEmit\",… 证据：`package.json`\n- **Skill: my-skill**（skill_instruction）：This is a test skill used in scenario tests. 证据：`tests/fixtures/skill/my-skill/SKILL.md`\n- **License**（source_file）：Mozilla Public License Version 2.0 ================================== 证据：`LICENSE`\n- **agent-add**（documentation）：MCP、Skill、スラッシュコマンド、サブエージェントなどを Claude Code や Cursor などの AI ツールにワンコマンドでインストール 证据：`docs/README.ja.md`\n- **agent-add**（documentation）：一条命令，将 MCP、Skill、斜杆命令、子代理等安装到任意 AI 工具，如 Claude Code、Cursor 等 证据：`docs/README.zh-CN.md`\n- **agent-add**（documentation）：Cross-host AI Agent Pack installer CLI tool. Install MCP, Skill, Prompt, Command, Sub-agent assets into different AI agent hosts Cursor, Claude Code, Claude Desktop, etc. with a single command. 证据：`vibe/system-prompt.md`\n- **Scenario Run Config**（documentation）：config: The CLI binary is pre-built at bin/agent-add.js relative to the project root. Every feature file sets PROJECT ROOT=$ git rev-parse --show-toplevel in a Background block. Run each CLI step with: node \"$PROJECT ROOT/bin/agent-add.js\" 证据：`tests/features/scenario-run-config.md`\n- **Command A**（documentation）：Command A test batch command a 证据：`tests/fixtures/command/batch/cmd-a.md`\n- **Command B**（documentation）：Command B test batch command b 证据：`tests/fixtures/command/batch/cmd-b.md`\n- **Command C**（documentation）：Command C test batch command c 证据：`tests/fixtures/command/batch/cmd-c.md`\n- **my-command**（documentation）：This is a test command used in scenario tests. Run this command to perform a test action. 证据：`tests/fixtures/command/my-command.md`\n- **My Test Prompt v2**（documentation）：Always respond concisely and professionally. Use bullet points for lists. Include code examples when relevant. 证据：`tests/fixtures/prompt/my-prompt-v2.md`\n- **My Test Prompt**（documentation）：Always respond concisely. Use bullet points for lists. 证据：`tests/fixtures/prompt/my-prompt.md`\n- **Code Review Prompt**（documentation）：When reviewing code: - Check for security issues - Verify error handling 证据：`tests/fixtures/prompt/second-prompt.md`\n- **my-agent**（documentation）：This is a test sub-agent used in scenario tests. 证据：`tests/fixtures/sub-agent/my-agent.md`\n- **Task: Verify and Update src/hosts/README.md**（documentation）：Task: Verify and Update src/hosts/README.md 证据：`vibe/tasks/verify-host-readme.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"commonjs\", \"moduleResolution\": \"node\", \"lib\": \"ES2022\" , \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"outDir\": \"dist\", \"rootDir\": \"src\", \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"resolveJsonModule\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"tests\" } 证据：`tsconfig.json`\n- **Manifest**（structured_config）：{ \"name\": \"agent-add/dev-pack\", \"assets\": { \"type\": \"skill\", \"source\": \"https://github.com/pea3nut/scenario-test.git skills/scenario-test\" }, { \"type\": \"command\", \"source\": \"https://github.com/pea3nut/scenario-test.git commands/scenario-exec.md\" }, { \"type\": \"subAgent\", \"source\": \"https://github.com/pea3nut/scenario-test.git agents/scenario-case-runner.md\" }, { \"type\": \"command\", \"source\": \"./vibe/tasks/verify-host-readme.md\" }, { \"type\": \"prompt\", \"source\": \"./vibe/system-prompt.md\" } } 证据：`vibe/manifest.json`\n- **Svc A**（structured_config）：{\"svc-a\":{\"command\":\"echo\",\"args\": \"a\" }} 证据：`tests/fixtures/mcp/batch/svc-a.json`\n- **Svc B**（structured_config）：{\"svc-b\":{\"command\":\"echo\",\"args\": \"b\" }} 证据：`tests/fixtures/mcp/batch/svc-b.json`\n- **Filesystem**（structured_config）：{ \"command\": \"npx\", \"args\": \"@anthropic/mcp-filesystem@latest\", \"/tmp\" , \"env\": {} } 证据：`tests/fixtures/mcp/filesystem.json`\n- **Playwright With Env**（structured_config）：{ \"command\": \"npx\", \"args\": \"@playwright/mcp@latest\" , \"env\": { \"BROWSER\": \"chromium\", \"HEADLESS\": \"true\" } } 证据：`tests/fixtures/mcp/playwright-with-env.json`\n- **Playwright**（structured_config）：{ \"command\": \"npx\", \"args\": \"@playwright/mcp@latest\" , \"env\": {} } 证据：`tests/fixtures/mcp/playwright.json`\n- **Codex Manifest**（structured_config）：{ \"name\": \"test/codex-pack\", \"assets\": { \"type\": \"mcp\", \"source\": \"./fixtures/mcp/playwright.json\" }, { \"type\": \"prompt\", \"source\": \"./fixtures/prompt/my-prompt.md\" }, { \"type\": \"skill\", \"source\": \"./fixtures/skill/my-skill\" }, { \"type\": \"command\", \"source\": \"./fixtures/command/my-command.md\" }, { \"type\": \"subAgent\", \"source\": \"./fixtures/sub-agent/my-agent.md\" } } 证据：`tests/fixtures/pack/codex-manifest.json`\n- **Manifest**（structured_config）：{ \"name\": \"test/test-pack\", \"version\": \"0.1.0\", \"description\": \"A test pack covering all asset types for scenario testing\", \"assets\": { \"type\": \"mcp\", \"name\": \"playwright\", \"source\": \"./fixtures/mcp/playwright.json\" }, { \"type\": \"skill\", \"name\": \"my-skill\", \"source\": \"./fixtures/skill/my-skill\" }, { \"type\": \"prompt\", \"name\": \"my-prompt\", \"source\": \"./fixtures/prompt/my-prompt.md\" }, { \"type\": \"command\", \"name\": \"my-command\", \"source\": \"./fixtures/command/my-command.md\" }, { \"type\": \"subAgent\", \"name\": \"my-agent\", \"source\": \"./fixtures/sub-agent/my-agent.md\" } } 证据：`tests/fixtures/pack/manifest.json`\n- **Multi Source Manifest**（structured_config）：{ \"name\": \"test/multi-source-pack\", \"assets\": { \"type\": \"mcp\", \"source\": \"./fixtures/mcp/playwright.json\", \"./fixtures/mcp/filesystem.json\" }, { \"type\": \"prompt\", \"source\": \"./fixtures/prompt/my-prompt.md\", \"./fixtures/prompt/second-prompt.md\" } } 证据：`tests/fixtures/pack/multi-source-manifest.json`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log lerna-debug.log 证据：`.gitignore`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node require '../dist/index.js' ; 证据：`bin/agent-add.js`\n- **Install MCP from JSON config file**（source_file）：import { Command } from 'commander'; import select from '@inquirer/select'; import { getHost, getValidHostIds } from './hosts/index.js'; import { detectHosts, isHostDetected } from './utils/detect-hosts.js'; import { runInstaller } from './installer.js'; import { printSummary } from './utils/summary.js'; import type { CliInput } from './installer.js'; 证据：`src/cli.ts`\n- **Index**（source_file）：import { createProgram } from './cli.js'; 证据：`src/index.ts`\n- **Installer**（source_file）：import fs from 'fs'; import path from 'path'; import type { AssetType, HostConfig } from './hosts/types.js'; import type { AssetDescriptor } from './manifest/schema.js'; import type { InstallJob, InstallResult, ResolvedSource } from './assets/types.js'; import { resolveSource } from './source/index.js'; import { inferName } from './source/infer-name.js'; import { expandDirectory } from './source/expand-directory.js'; import { loadManifest } from './manifest/parser.js'; import { mcpHandler } from './assets/mcp.js'; import { skillHandler } from './assets/skill.js'; import { promptHandler } from './assets/prompt.js'; import { commandHandler } from './assets/command.js'; import { subAgentHandle… 证据：`src/installer.ts`\n- **Tsup.Config**（source_file）：import { defineConfig } from 'tsup'; 证据：`tsup.config.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from 'vitest/config'; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `src/hosts/README.md`, `tests/fixtures/skill/bad-skill/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `src/hosts/README.md`, `tests/fixtures/skill/bad-skill/README.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, package.json\n- **安装与快速开始**：importance `high`\n - source_paths: bin/agent-add.js, src/cli.ts, package.json\n- **核心功能使用指南**：importance `high`\n - source_paths: src/installer.ts, src/hosts/index.ts, src/manifest/parser.ts\n- **源格式与名称推断**：importance `medium`\n - source_paths: src/source/index.ts, src/source/infer-name.ts, src/source/git.ts, src/source/http-file.ts, src/source/local.ts\n- **系统架构总览**：importance `high`\n - source_paths: src/index.ts, src/cli.ts, src/installer.ts, tsup.config.ts\n- **Source 模块详解**：importance `medium`\n - source_paths: src/source/index.ts, src/source/git.ts, src/source/http-file.ts, src/source/local.ts, src/source/inline.ts\n- **Host 适配器系统**：importance `high`\n - source_paths: src/hosts/index.ts, src/hosts/types.ts, src/hosts/cursor.ts, src/hosts/claude-code.ts, src/hosts/windsurf.ts\n- **CLI 参考文档**：importance `high`\n - source_paths: src/cli.ts, bin/agent-add.js, package.json\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\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: 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- Trigger: I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- Host AI rule: Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- Why it matters: 这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- Evidence: social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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项目：pea3nut/agent-add\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, cursor, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...（medium）：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\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/pea3nut/agent-add 项目说明书\n\n生成时间：2026-05-14 05:41:02 UTC\n\n## 目录\n\n- [项目首页](#p-home)\n- [安装与快速开始](#p-installation)\n- [核心功能使用指南](#p-usage)\n- [源格式与名称推断](#p-source-formats)\n- [系统架构总览](#p-arch)\n- [Source 模块详解](#p-source-module)\n- [Host 适配器系统](#p-host-system)\n- [CLI 参考文档](#p-cli-ref)\n- [Pack Manifest 格式规范](#p-pack-manifest)\n- [资产开发者指南](#p-asset-dev)\n\n\n\n## 项目首页\n\n### 相关页面\n\n相关主题：[安装与快速开始](#p-installation), [核心功能使用指南](#p-usage), [系统架构总览](#p-arch)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n
\n\n# 项目首页\n\n## 项目概述\n\n**agent-add** 是一个跨平台的命令行工具，用于将 AI Agent 资产（MCP 服务器、Skills、Prompts、Commands、Sub-agents）安装到各种 AI 编程辅助工具中。该工具通过统一的接口屏蔽了不同宿主（Host）之间的差异，开发者只需一条命令即可将资产安装到指定的 AI 编程环境中。\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## 核心能力\n\n### 支持的资产类型\n\n| 资产类型 | 说明 | 安装方式 |\n|---------|------|---------|\n| MCP | Model Context Protocol 服务器配置 | JSON 配置合并 |\n| Skill | 可复用的 Agent 技能目录 | 目录递归复制 |\n| Prompt | 规则文件 / 系统提示词 | 追加写入或独立文件 |\n| Command | 斜杠命令定义 | 独立文件安装 |\n| Sub-agent | 子代理配置 | YAML + Markdown 混合格式 |\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n### 支持的宿主环境\n\nagent-add 目前支持 **18 种** AI 编程宿主：\n\n| 宿主 | 配置格式 | 说明 |\n|-----|---------|------|\n| `cursor` | AGENTS.md | Cursor IDE |\n| `claude-code` | CLAUDE.md | Anthropic Claude Code |\n| `claude-desktop` | JSON | Claude Desktop 应用 |\n| `windsurf` | 独立目录 | Windsurf AI IDE |\n| `github-copilot` | 配置文件 | GitHub Copilot |\n| `gemini` | 配置文件 | Google Gemini |\n| `roo-code` | 独立目录 | Roo Code |\n| `kilo-code` | 配置文件 | Kilo Code |\n| `qwen-code` | 配置文件 | 通义千问编码助手 |\n| `opencode` | 配置文件 | OpenCode |\n| `augment` | 配置文件 | Augment Code |\n| `kiro` | 配置文件 | Kiro AI |\n| `tabnine` | 配置文件 | Tabnine |\n| `kimi` | 配置文件 | Kimi 编程助手 |\n| `trae` | 配置文件 | Trae IDE |\n| `openclaw` | 配置文件 | OpenClaw |\n| `codex` | TOML | OpenAI Codex |\n| `vibe` | TOML | Vibe Coding 工具 |\n\n资料来源：[src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n\n## 系统架构\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[CLI 输入] --> B[显式标志能力检查]\n B --> C[资产描述符解析]\n C --> D[源解析器]\n D --> E[验证层]\n E --> F[安装处理器]\n F --> G[宿主适配器]\n G --> H[文件系统写入]\n \n D --> D1[MCP 处理器]\n D --> D2[Skill 处理器]\n D --> D3[Prompt 处理器]\n D --> D4[Command 处理器]\n D --> D5[Sub-agent 处理器]\n```\n\n### 核心模块\n\n| 模块 | 路径 | 职责 |\n|-----|------|-----|\n| CLI | `src/cli.ts` | 命令行参数解析、TTY 检测、交互式宿主选择 |\n| 安装器 | `src/installer.ts` | 编排核心：输入解析 → 能力检查 → 源解析 → 验证 → 处理器执行 → 汇总 |\n| 宿主适配层 | `src/hosts/` | 18 种宿主适配器，实现 HostAdapter 接口 |\n| 资产处理器 | `src/assets/` | 5 种资产类型处理器 |\n| 源解析器 | `src/source/` | 本地路径、Git URL、HTTP 文件、内联内容的统一解析 |\n| 清单解析器 | `src/manifest/parser.ts` | Pack Manifest JSON 格式验证与解析 |\n| 工具函数 | `helpers/utils.ts` | 通用辅助函数 |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## 安装流程\n\n### 命令行用法\n\n```bash\n# 安装 MCP 服务器\nnpx -y agent-add --host cursor --mcp ./mcp/playwright.json\n\n# 安装 Skill 目录\nnpx -y agent-add --host claude-code --skill ./skills/my-skill\n\n# 安装 Prompt 规则文件\nnpx -y agent-add --host windsurf --prompt ./rules/code-review.md\n\n# 从 Pack Manifest 批量安装\nnpx -y agent-add --host cursor --pack ./manifest.json\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### 数据流处理\n\n```mermaid\nflowchart LR\n subgraph 输入层\n A1[CLI 标志] --> A3[AssetDescriptor]\n A2[Pack Manifest] --> A3\n end\n \n subgraph 解析层\n A3 --> B1[ResolvedSource]\n B1 --> B2[安装作业队列]\n end\n \n subgraph 执行层\n B2 --> C1[MCP 处理器]\n B2 --> C2[Skill 处理器]\n B2 --> C3[Prompt 处理器]\n B2 --> C4[Command 处理器]\n B2 --> C5[Sub-agent 处理器]\n end\n \n subgraph 输出层\n C1 --> D1[InstallResult]\n C2 --> D1\n C3 --> D1\n C4 --> D1\n C5 --> D1\n D1 --> E[Summary 输出]\n end\n```\n\n### 状态与结果\n\n| 状态 | 说明 |\n|-----|------|\n| `written` | 资产已成功写入 |\n| `exists` | 资产已存在，无需更新 |\n| `updated` | 资产已更新 |\n| `conflict` | 存在冲突（手动解决） |\n| `skipped` | 宿主不支持该资产类型 |\n| `error` | 安装过程中发生错误 |\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 关键设计决策\n\n### 原子化 JSON 写入\n\nMCP 配置文件使用临时文件 + 重命名的原子写入策略，确保多进程并发写入时的数据一致性：\n\n```typescript\n// 临时文件写入 → 原子重命名\nconst tempPath = `${configPath}.tmp.${Date.now()}`;\nawait fs.promises.writeFile(tempPath, JSON.stringify(merged, null, 2));\nawait fs.promises.rename(tempPath, configPath);\n```\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### 标记块追加策略\n\nPrompt 类型资产在追加模式下使用 HTML 注释标记实现幂等追加：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n重复安装时，工具会自动识别并更新对应标记块内容，而非重复追加。\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n### 内联源支持\n\n| 源类型 | 格式特征 | 支持的资产 |\n|-------|---------|-----------|\n| 内联 JSON | 以 `{` 开头 | MCP |\n| 内联 Markdown | 包含 `\\n` | Prompt / Command / Sub-agent |\n| HTTP 文件 | URL 格式 | Skill 除外全部支持 |\n| 本地路径 | 相对/绝对路径 | 全部支持 |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n### 非 TTY 严格模式\n\nCI 环境必须显式指定 `--host` 参数，否则工具将退出并返回错误码 2：\n\n```typescript\n// 非 TTY 环境未指定 host\nif (!process.stdin.isTTY && !host) {\n process.stderr.write('agent-add error: --host flag required in non-TTY environment\\n');\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n\n## Pack Manifest 清单\n\n### 格式规范\n\n```json\n{\n \"name\": \"namespace/pack-name\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/...#path/to/config.json\" },\n { \"type\": \"skill\", \"source\": \"./local/skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/...\" },\n { \"type\": \"command\", \"source\": \"git@github.com:...#tools/security.md\" },\n { \"type\": \"subAgent\", \"source\": \"...#categories/backend.md\" }\n ]\n}\n```\n\n### 字段规格\n\n| 字段 | 必填 | 说明 |\n|-----|-----|------|\n| `name` | 是 | 格式：`namespace/pack-name`，仅允许 `[a-zA-Z0-9_-]` |\n| `assets` | 是 | 至少 1 个元素 |\n| `assets[].type` | 是 | `mcp` \\| `skill` \\| `prompt` \\| `command` \\| `subAgent` |\n| `assets[].source` | 是 | 资产来源（URL、路径、内联内容） |\n\n资料来源：[src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n\n## 项目技术栈\n\n| 组件 | 版本 | 用途 |\n|-----|------|-----|\n| TypeScript | ^5.9.3 | 类型安全开发 |\n| Commander | ^14.0.3 | 命令行参数解析 |\n| Vitest | ^4.1.0 | 单元测试框架 |\n| Zod | ^4.3.6 | 数据验证 |\n| smol-toml | ^1.6.1 | TOML 解析（Codex/Vibe） |\n| YAML | ^2.8.2 | YAML 前端解析 |\n| tsup | ^8.5.1 | 构建工具 |\n\n资料来源：[package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n\n## 宿主适配器接口\n\n```typescript\ninterface HostAdapter {\n id: string; // 唯一标识符\n name: string; // 宿主名称\n assets: AssetCapability; // 支持的资产类型映射\n mcpWriteStrategy: 'json' | 'toml'; // MCP 配置写入策略\n}\n\ninterface AssetCapability {\n mcp?: { supported: boolean; reason?: string };\n skill?: { supported: boolean; reason?: string };\n prompt?: { supported: boolean; reason?: string };\n command?: { supported: boolean; reason?: string };\n subAgent?: { supported: boolean; reason?: string };\n}\n```\n\n资料来源：[src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n\n## 快速开始\n\n### 开发环境搭建\n\n```bash\n# 克隆仓库\ngit clone https://github.com/pea3nut/agent-add.git\ncd agent-add\n\n# 安装依赖\nnpm install\n\n# 构建项目\nnpm run build\n\n# 安装开发资产（scenario-test 等）\nnpm run install:vibe\n```\n\n### 运行测试\n\n| 命令 | 说明 |\n|-----|------|\n| `npm test` | 运行所有单元测试和集成测试 |\n| `npm run test:contract` | 仅运行 CLI 黑盒契约测试 |\n| `npx vitest run tests/unit/hosts/cursor.test.ts` | 运行单个测试文件 |\n\n资料来源：[README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n\n## 贡献指南\n\n### 场景测试\n\n场景测试使用 Gherkin `.feature` 文件定义，由 AI Agent 通过 [scenario-test](https://github.com/pea3nut/scenario-test) 执行：\n\n```\n/scenario-exec tests/features/core # 核心资产行为测试\n/scenario-exec tests/features/host # 跨宿主兼容性测试\n```\n\n每个场景在隔离的临时目录中运行，运行配置定义于 `tests/features/scenario-run-config.md`。\n\n### 添加新宿主\n\n1. 在 `src/hosts/` 下创建 `.ts` 实现 HostAdapter 接口\n2. 在 `src/hosts/README.md` 中更新宿主能力矩阵\n3. 在 `tests/unit/hosts/` 下创建对应的单元测试\n4. 在 `src/hosts/index.ts` 中注册新宿主\n\n> **重要**：adapter 实现必须与 README.md 中的字段值完全一致。\n\n---\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[核心功能使用指南](#p-usage), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n
\n\n# 安装与快速开始\n\n## 概述\n\n`agent-add` 是一个跨宿主 AI Agent 工具包安装器 CLI 工具，能够将 MCP（Model Context Protocol）、Skill、Prompt、Command、Sub-agent 等资产安装到不同的 AI Agent 宿主环境中。使用一条命令即可完成资产的安装、配置和管理。\n\n当前支持的宿主环境包括：Cursor、Claude Code、Claude Desktop、Windsurf、GitHub Copilot、Gemini、Roo Code、Kilo Code、Qwen Code、OpenCode、Augment、Kiro、Tabnine、Kimi、Trae、OpenClaw、Codex（TOML）、Vibe（TOML）等 18 种主流 AI 编程工具。\n\n资料来源：[src/hosts/README.md:1]()\n\n## 系统要求\n\n| 要求 | 说明 |\n|------|------|\n| Node.js 版本 | >= 18 |\n| 包管理器 | npm、yarn、pnpm 均可 |\n| 网络 | 需要访问 GitHub/GitLab 或相关资源 URL |\n| TTY 环境 | CI 环境需显式指定 `--host`，否则退出错误码 2 |\n\n资料来源：[package.json:28]()\n\n## 安装方式\n\n### 方式一：npx 免安装（推荐）\n\n最便捷的使用方式，无需预先安装，直接通过 `npx` 调用：\n\n```bash\nnpx -y agent-add --host cursor --mcp \n```\n\n`npx -y` 参数确保自动确认安装提示。\n\n资料来源：[README.md:1]()\n\n### 方式二：全局安装\n\n将工具安装到系统全局环境，随时可用：\n\n```bash\nnpm install -g agent-add\n```\n\n安装完成后可直接调用：\n\n```bash\nagent-add --host claude-code --mcp \n```\n\n### 方式三：本地项目安装\n\n将工具作为项目开发依赖安装：\n\n```bash\nnpm install --save-dev agent-add\n```\n\n在 `package.json` 中配置快捷脚本：\n\n```json\n{\n \"scripts\": {\n \"setup\": \"agent-add -- --pack vibe/manifest.json\"\n }\n}\n```\n\n资料来源：[package.json:41]()\n\n## 构建与开发\n\n如果从源码克隆项目，需要先构建：\n\n```bash\nnpm install\nnpm run build\n```\n\n构建完成后会生成单文件 CJS 捆绑包 `dist/index.js`。\n\n### 开发模式\n\n支持热重载开发模式：\n\n```bash\nnpm run dev # tsup --watch 监听模式\nnpm run install:vibe # 通过 pack manifest 安装开发资产\n```\n\n资料来源：[README.md:7]()\n\n## 基本使用流程\n\n### 工作流程图\n\n```mermaid\ngraph TD\n A[开始] --> B[指定宿主 --host]\n B --> C{资产来源类型}\n C -->|Git URL| D[解析 #path 提取资源]\n C -->|HTTP URL| E[下载远程文件]\n C -->|本地路径| F[访问本地文件/目录]\n C -->|内联内容| G[写入临时文件]\n D --> H[验证资产有效性]\n E --> H\n F --> H\n G --> H\n H --> I{资产类型}\n I -->|MCP| J[写入 JSON/TOML 配置]\n I -->|Skill| K[复制目录到 skills/]\n I -->|Prompt| L[追加或创建文件]\n I -->|Command| M[写入 commands/]\n I -->|Sub-agent| N[写入 subagents/]\n J --> O[完成安装]\n K --> O\n L --> O\n M --> O\n N --> O\n```\n\n### 核心参数说明\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--host ` | CI 环境必填 | 目标宿主标识符，如 `cursor`、`claude-code` |\n| `--mcp ` | 否 | MCP 配置文件来源 |\n| `--skill ` | 否 | Skill 技能包目录来源 |\n| `--prompt ` | 否 | Prompt 规则文件来源 |\n| `--command ` | 否 | Command 命令文件来源 |\n| `--sub-agent ` | 否 | Sub-agent 子代理来源 |\n| `--pack ` | 否 | Pack 清单文件（批量安装） |\n| `-V, --version` | 否 | 显示版本号 |\n| `-h, --help` | 否 | 显示帮助信息 |\n\n资料来源：[src/cli.ts:1]()\n\n### 宿主选择规则\n\n| 环境 | 行为 |\n|------|------|\n| TTY 交互环境 | 无 `--host` 时显示交互式选择菜单 |\n| CI/非 TTY 环境 | 必须显式指定 `--host`，否则退出码 2 |\n\n资料来源：[src/cli.ts:1]()\n\n## 资产安装示例\n\n### 安装 MCP 服务器\n\n```bash\n# 从 GitHub 仓库安装\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'\n\n# 从本地 JSON 文件安装\nnpx -y agent-add --host cursor --mcp './mcps/playwright.json'\n\n# 内联 JSON 安装（MCP 专用）\nnpx -y agent-add --host cursor --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}'\n```\n\n资料来源：[README.md:40]()\n\n### 安装 Skill 技能包\n\n```bash\n# 从 GitHub 仓库安装\nnpx -y agent-add --host cursor --skill 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n\n# 从本地目录安装\nnpx -y agent-add --host cursor --skill './my-skill'\n```\n\n> **注意**：Skill 必须指向目录来源，不支持内联内容或直接 HTTP URL。\n\n资料来源：[src/installer.ts:1]()\n\n### 安装 Prompt 规则文件\n\n```bash\n# 内联 Markdown（适用于 Claude Code）\nnpx -y agent-add --host claude-code \\\n --prompt $'# Code Review Rules\\n\\nAlways review for security issues first.'\n\n# 从 HTTP URL 安装\nnpx -y agent-add --host cursor \\\n --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'\n```\n\n资料来源：[README.md:50]()\n\n### 安装 Command 命令\n\n```bash\n# 从 GitHub 仓库安装\nnpx -y agent-add --host cursor \\\n --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### 安装 Sub-agent 子代理\n\n```bash\n# 从 VoltAgent 仓库安装\nnpx -y agent-add --host cursor \\\n --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'\n```\n\n### 批量安装（Pack 清单）\n\n```bash\n# 安装 Pack 清单中定义的所有资产\nnpx -y agent-add --host cursor --pack 'https://github.com/pea3nut/scenario-test.git'\n```\n\nPack 清单格式示例：\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/...\" },\n { \"type\": \"command\", \"source\": \"https://github.com/...#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/...#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n资料来源：[README.md:70]()\n\n## 资产名称推断规则\n\n`agent-add` 根据来源自动推断资产名称：\n\n| 来源类型 | 推断规则 | 示例 |\n|----------|----------|------|\n| 包含 `#path` | 使用 `#` 后的最后一段（去除扩展名） | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#` | 使用仓库名称（去除 `.git` 后缀） | `...playwright.git` → `playwright` |\n| 本地路径/HTTP | 使用文件名（去除扩展名） | `./mcps/playwright.json` → `playwright` |\n| 内联 JSON `{` 开头 | 提取顶层 key 作为名称 | `{\"playwright\":{...}}` → `playwright` |\n| 内联 Markdown 包含 `\\n` | 提取第一个 `# Heading` 并转 kebab-case | `# Code Review` → `code-review` |\n\n资料来源：[src/source/infer-name.ts:1]()\n\n## 输出状态说明\n\n每次安装操作后会显示摘要，包含以下状态：\n\n| 状态 | 含义 |\n|------|------|\n| `written` | 新资产已写入 |\n| `exists` | 资产已存在，无需更新 |\n| `updated` | 资产已更新 |\n| `conflict` | 存在冲突，需要手动处理 |\n| `skipped` | 宿主不支持该资产类型 |\n| `error` | 安装过程中发生错误 |\n\n安装结果包含冲突或错误时，CLI 退出码为 1；其他情况退出码为 0。\n\n资料来源：[src/cli.ts:1]()\n\n## 错误处理\n\n| 错误类型 | 退出码 | 说明 |\n|----------|--------|------|\n| 宿主不支持该资产类型 | 2 | 显式指定了不支持的资产类型 |\n| 资产来源无效 | 2 | 来源格式错误或无法解析 |\n| 缺少必需文件 | 2 | 如 Skill 目录缺少 `SKILL.md` |\n| CI 环境未指定宿主 | 2 | 非 TTY 环境必须 `--host` |\n| 冲突或错误 | 1 | 安装有冲突或错误 |\n\n资料来源：[src/installer.ts:1]()\n\n## 常见问题\n\n### Q: 安装 MCP 时报错 \"MCP 来源文件不存在\"\n\n确保 MCP 来源文件扩展名为 `.json`，且路径正确。agent-add 不支持其他格式的 MCP 配置。\n\n### Q: Skill 安装失败\n\n检查 Skill 目录中是否包含 `SKILL.md` 文件，这是必需的标识文件。\n\n### Q: 提示宿主不支持某资产类型\n\n查看 `src/hosts/README.md` 确认该宿主支持的功能列表，不同宿主支持的资产类型不同。\n\n### Q: CI 环境安装失败\n\n确保在 CI 环境中显式指定 `--host` 参数，否则程序会退出并提示错误。\n\n## 相关文档\n\n- [宿主适配器开发指南](./host-adapter-guide.md) - 如何添加新的宿主支持\n- [资产类型规范](./asset-specifications.md) - 各资产类型的详细格式说明\n- [Pack 清单规范](./pack-manifest.md) - Pack 清单文件格式详解\n- [测试指南](./testing.md) - 单元测试和集成测试说明\n\n---\n\n\n\n## 核心功能使用指南\n\n### 相关页面\n\n相关主题：[源格式与名称推断](#p-source-formats), [Host 适配器系统](#p-host-system), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n
\n\n# 核心功能使用指南\n\n## 概述\n\nagent-add 是一款用于向 AI 编码助手安装资产的命令行工具，支持 18 种主流开发环境。该工具通过统一的 CLI 接口简化了 MCP 服务器、Skill、Prompt、Command 和 Sub-agent 五类资产的安装流程。\n\n核心功能模块包括：**命令行解析** → **宿主检测** → **来源解析** → **资产验证** → **安装执行** → **结果汇总**。\n\n资料来源：[src/installer.ts:1-50]()\n\n## 安装流程架构\n\n### 数据流总览\n\n```mermaid\ngraph TD\n A[CLI 参数解析] --> B[显式标志能力检查]\n B --> C[AssetDescriptor 数组]\n C --> D[来源解析]\n D --> E[ResolvedSource 数组]\n E --> F[资产验证]\n F --> G[InstallJob 数组]\n G --> H[安装执行]\n H --> I[InstallResult 数组]\n I --> J[结果汇总输出]\n \n K[--pack 清单文件] -.-> C\n L[--mcp/skill/prompt/command/sub-agent 标志] -.-> C\n```\n\n### 核心数据类型\n\n| 类型名称 | 用途 | 关键字段 |\n|---------|------|---------|\n| `CliInput` | CLI 原始输入 | `host`, `pack[]`, `mcp[]`, `skill[]`, `prompt[]`, `command[]`, `subAgent[]` |\n| `AssetDescriptor` | 资产描述符 | `assetType`, `source`, `fromExplicitFlag` |\n| `ResolvedSource` | 已解析来源 | `type`, `originalSource`, `localPath`, `tempDir` |\n| `InstallJob` | 安装任务 | `assetType`, `assetName`, `resolvedSource`, `host` |\n| `InstallResult` | 安装结果 | `job`, `status`, `reason?` |\n\n资料来源：[src/installer.ts:20-45]()\n\n## 命令行接口\n\n### CLI 参数定义\n\nagent-add 采用 Commander.js 构建 CLI，定义了六类资产安装标志：\n\n```typescript\n.option('--pack ', 'Install an Agent Pack manifest', collect, [])\n.option('--mcp ', 'Install an MCP Server', collect, [])\n.option('--skill ', 'Install a Skill', collect, [])\n.option('--prompt ', 'Install a Prompt', collect, [])\n.option('--command ', 'Install a Command', collect, [])\n.option('--sub-agent ', 'Install a Sub-agent', collect, [])\n.option('--host ', 'Target host ID', collect, [])\n```\n\n所有资产标志均支持重复使用（多次安装同类型资产）并可自由组合。\n\n### 输入验证\n\n```typescript\nconst hasAssetFlags =\n cliInput.pack.length > 0 ||\n cliInput.mcp.length > 0 ||\n cliInput.skill.length > 0 ||\n cliInput.prompt.length > 0 ||\n cliInput.command.length > 0 ||\n cliInput.subAgent.length > 0;\n\nif (!hasAssetFlags) {\n process.stderr.write(\n 'agent-add error: No asset flags provided. Use --pack, --mcp, --skill, --prompt, --command, or --sub-agent.\\n',\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/cli.ts:1-30]()\n\n## 宿主检测与选择\n\n### 宿主注册表\n\n宿主适配器通过注册表统一管理：\n\n```typescript\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['claude-desktop', new ClaudeDesktopAdapter()],\n // ... 共18种宿主\n]);\n```\n\n### 宿主选择逻辑\n\n| 场景 | 行为 |\n|------|------|\n| 显式指定 `--host` | 直接使用指定宿主 ID |\n| TTY 环境无 `--host` | 交互式选择宿主 |\n| 非 TTY 环境无 `--host` | 输出错误并退出（exit 2） |\n\n```typescript\nif (cliInput.host) {\n hostId = cliInput.host;\n} else if (!process.stdout.isTTY) {\n const validIds = getValidHostIds().join(', ');\n process.stderr.write(\n `agent-add error: Non-TTY environment requires explicit --host flag.\\n`\n );\n process.exit(2);\n}\n```\n\n资料来源：[src/hosts/index.ts:1-25]()\n\n### 宿主能力矩阵\n\n每种宿主声明其支持的资产类型：\n\n```typescript\ninterface HostAdapter {\n id: string;\n displayName: string;\n docs: string;\n assets: {\n mcp: AssetCapability;\n skill: AssetCapability;\n prompt: AssetCapability;\n command: AssetCapability;\n subAgent: AssetCapability;\n };\n}\n\ninterface AssetCapability {\n supported: boolean;\n configFile?: string;\n installDir?: string;\n writeStrategy?: 'append' | 'standalone';\n reason?: string;\n}\n```\n\n资料来源：[src/hosts/types.ts:1-20]()\n\n## 来源解析系统\n\n### 支持的来源类型\n\n| 类型 | 格式 | 说明 |\n|------|------|------|\n| `local` | 绝对/相对路径 | 本地文件系统 |\n| `git` | Git URL + `#path` | Git 仓库文件/目录 |\n| `http-file` | HTTP(S) URL | 远程文件下载 |\n| `inline-json` | `{\"name\":{...}}` | 内联 JSON（MCP 专用） |\n| `inline-md` | 含换行符的 Markdown | 内联 Prompt/Command/Sub-agent |\n\n### 名称推断规则\n\n来源字符串到资产名称的转换规则：\n\n| 来源格式 | 推断逻辑 | 示例 |\n|----------|----------|------|\n| 内联 JSON | 提取顶层键名 | `{\"playwright\":{...}}` → `playwright` |\n| 内联 Markdown | 首行 `# 标题` 转 kebab-case | `# Code Review` → `code-review` |\n| Git URL + `#path` | path 最后段去扩展名 | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#` | 仓库名去 `.git` | `...playwright.git` → `playwright` |\n| 本地路径/HTTP | 文件名去扩展名 | `./mcps/playwright.json` → `playwright` |\n\n```typescript\nexport function inferName(source: string): string {\n const s = source.trim();\n \n // 内联 JSON：提取顶层键\n if (s.startsWith('{')) {\n const parsed = JSON.parse(s);\n const unwrapped = unwrapMcpServers(obj);\n if (unwrapped) return unwrapped.name;\n // ...\n }\n \n // 内联 Markdown：提取 # 标题\n if (s.includes('\\n')) {\n const match = s.match(/^#\\s+(.+)/m);\n if (match) return kebabCase(match[1]);\n }\n \n // Git URL / 本地路径 / HTTP\n // ...\n}\n```\n\n资料来源：[src/source/infer-name.ts:1-40]()\n\n### 来源解析流程\n\n```mermaid\ngraph LR\n A[来源字符串] --> B{是否内联 JSON?}\n B -->|是| C[创建临时文件]\n B -->|否| D{包含换行符?}\n D -->|是| E[内联 Markdown]\n D -->|否| F{Git URL?}\n F -->|是| G[克隆到临时目录]\n F -->|否| H{HTTP URL?}\n H -->|是| I[下载到临时目录]\n H -->|否| J[使用本地路径]\n \n C --> K[返回 ResolvedSource]\n E --> K\n G --> K\n I --> K\n J --> K\n```\n\n## 资产验证\n\n### 验证规则\n\n| 资产类型 | 验证项 | 错误信息 |\n|---------|--------|---------|\n| `skill` | 目录内必须包含 `SKILL.md` | `Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL` |\n| `skill` | 不支持 `http-file`/`inline-json`/`inline-md` 来源 | `Skill 目录内缺少 SKILL.md 文件` |\n| `mcp` | 文件必须存在且扩展名为 `.json` | `MCP 来源文件不存在` / `MCP 来源文件扩展名必须为 .json` |\n\n```typescript\nasync function validateAsset(\n assetType: AssetType,\n resolved: ResolvedSource,\n): Promise {\n if (assetType === 'skill') {\n if (resolved.type === 'http-file' || resolved.type === 'inline-json' || resolved.type === 'inline-md') {\n return 'Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL';\n }\n const skillMdPath = path.join(resolved.localPath, 'SKILL.md');\n try {\n await fs.promises.access(skillMdPath);\n } catch {\n return `Skill 目录内缺少 SKILL.md 文件（期望路径：${skillMdPath}）`;\n }\n return null;\n }\n // ...\n}\n```\n\n资料来源：[src/installer.ts:60-80]()\n\n## 安装执行\n\n### 资产处理器注册\n\n```typescript\nfunction getHandler(assetType: AssetType) {\n switch (assetType) {\n case 'mcp': return mcpHandler;\n case 'skill': return skillHandler;\n case 'prompt': return promptHandler;\n case 'command': return commandHandler;\n case 'subAgent': return subAgentHandler;\n }\n}\n```\n\n### 安装结果状态\n\n| 状态 | 含义 |\n|------|------|\n| `written` | 新资产写入成功 |\n| `exists` | 资产已存在，无变更 |\n| `updated` | 资产内容更新 |\n| `conflict` | 存在冲突需人工处理 |\n| `skipped` | 宿主不支持该资产类型 |\n| `error` | 安装过程出错 |\n\n### 跳过逻辑\n\n当宿主不支持某类资产时：\n\n```typescript\nconst capability = host.assets[item.assetType];\nif (!capability.supported) {\n skippedResults.push({\n job: { ... },\n status: 'skipped',\n reason: capability.reason ?? `Host ${host.id} 不支持 ${item.assetType} 类型资产`,\n });\n continue;\n}\n```\n\n资料来源：[src/installer.ts:85-95]()\n\n## 清单文件处理\n\n### 清单格式\n\n```json\n{\n \"name\": \"namespace/pack-name\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://...\" },\n { \"type\": \"skill\", \"source\": \"...\" }\n ]\n}\n```\n\n### 清单解析流程\n\n```mermaid\ngraph TD\n A[解析 --pack 清单] --> B[验证清单结构]\n B --> C[展平为 AssetDescriptor 数组]\n C --> D[合并到主输入]\n D --> E[继续标准安装流程]\n```\n\n### 字段规范\n\n| 字段 | 必填 | 说明 |\n|------|------|------|\n| `name` | 是 | 格式 `namespace/pack-name`，仅允许 `[a-zA-Z0-9_-]` |\n| `assets` | 是 | 至少包含 1 项 |\n| `assets[].type` | 是 | `mcp` \\| `skill` \\| `prompt` \\| `command` \\| `subAgent` |\n| `assets[].source` | 是 | 资产来源字符串 |\n\n资料来源：[src/manifest/parser.ts:1-30]()\n\n## 环境变量\n\n| 变量名 | 用途 |\n|--------|------|\n| `AGENT_ADD_HOME` | 覆盖 `os.homedir()` 返回值，用于将 Claude Desktop / Codex 宿主安装路径重定向到临时目录，实现测试隔离 |\n\n资料来源：[vibe/system-prompt.md:1-5]()\n\n## 错误处理\n\n### 退出码规范\n\n| 退出码 | 含义 |\n|--------|------|\n| `0` | 所有资产安装成功 |\n| `1` | 存在冲突（conflict）或错误（error） |\n| `2` | 参数错误、验证失败、来源无效 |\n\n```typescript\nconst hasConflicts = summary.results.some((r) => r.status === 'conflict');\nconst hasErrors = summary.results.some((r) => r.status === 'error');\n\nif (hasErrors || hasConflicts) {\n process.exit(1);\n}\n```\n\n资料来源：[src/cli.ts:35-45]()\n\n## 使用示例\n\n### 单资产安装\n\n```bash\n# 安装 MCP 服务器\nnpx -y agent-add --host cursor --mcp ./mcps/playwright.json\n\n# 安装 Skill\nnpx -y agent-add --host claude-code --skill ./skills/webapp-testing\n\n# 安装 Prompt\nnpx -y agent-add --host claude-code --prompt 'https://raw.githubusercontent.com/.../rules.md'\n```\n\n### 清单批量安装\n\n```bash\nnpx -y agent-add --host cursor --pack ./manifests/frontend.json\n```\n\n### 组合使用\n\n```bash\nnpx -y agent-add \\\n --host claude-code \\\n --mcp ./mcps/playwright.json \\\n --skill ./skills/webapp-testing \\\n --prompt '# Code Review Rules\\n\\nAlways review for security issues first.'\n\n---\n\n\n\n## 源格式与名称推断\n\n### 相关页面\n\n相关主题：[Source 模块详解](#p-source-module), [资产开发者指南](#p-asset-dev)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n- [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n- [src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n- [src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n
\n\n# 源格式与名称推断\n\n## 概述\n\n`agent-add` 项目中的源格式与名称推断模块负责将用户提供的各种来源标识符解析为统一的内部表示，并自动推断资产名称。该模块是整个安装流程的入口处理层，位于 `src/source/` 目录下。\n\n源解析系统的核心职责包括：\n\n- **识别源类型**：根据源字符串的特征（前缀、URL格式、内联内容格式）判断其类型\n- **解析源内容**：将源内容下载或读取到临时目录，供后续安装流程使用\n- **推断资产名称**：根据源的特征自动生成符合规范的资产名称\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## 源类型体系\n\n`agent-add` 支持多种源格式，通过检测源字符串的特征自动识别其类型。\n\n### 源类型分类\n\n| 源类型 | 识别规则 | 特征 | 支持的资产类型 |\n|--------|----------|------|----------------|\n| `inline-json` | 以 `{` 开头 | JSON 对象字面量 | 仅 MCP |\n| `inline-md` | 包含 `\\n` | Markdown 内容 | Prompt/Command/Sub-agent |\n| `git-ssh` | 以 `git@` 开头 | SSH 协议格式 | 所有类型 |\n| `git-https` | 以 `https://` 或 `http://` 开头，且包含 `.git` | HTTPS 协议 | 所有类型 |\n| `http-file` | 以 `https://` 或 `http://` 开头，且不包含 `.git` | HTTP 文件 URL | 除 Skill 外的所有类型 |\n| `local` | 其他情况 | 本地文件路径 | 所有类型 |\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n### 类型识别流程\n\n```mermaid\ngraph TD\n A[输入源字符串] --> B{以 `{` 开头?}\n B -->|是| C{包含 `\\n`?}\n B -->|否| D{以 `git@` 开头?}\n C -->|是| E[inline-md]\n C -->|否| F[inline-json]\n D -->|是| G[git-ssh]\n D -->|否| H{以 `http` 开头?}\n H -->|是| I{包含 `.git`?}\n I -->|是| J[git-https]\n I -->|否| K[http-file]\n H -->|否| L[local]\n \n style E fill:#90EE90\n style F fill:#87CEEB\n style G fill:#FFD700\n style J fill:#FFD700\n style K fill:#FFA500\n style L fill:#DDA0DD\n```\n\n## 名称推断规则\n\n名称推断模块 `infer-name.ts` 负责从源字符串中提取或生成资产名称。不同源类型遵循不同的命名规则。\n\n### 推断规则优先级\n\n| 优先级 | 条件 | 命名规则 | 示例 |\n|--------|------|----------|------|\n| 0 | 内联 JSON | 提取单个顶层键 | `{\"playwright\":{...}}` → `playwright` |\n| 0 | 内联 Markdown | 提取首个 `# Heading` 并转 kebab-case | `# Code Review` → `code-review` |\n| 1 | 包含 `#path` | 使用 `#` 后的路径段（去掉扩展名） | `...git#skills/pdf` → `pdf` |\n| 2 | Git URL 无 `#path` | 提取仓库名（去掉 `.git` 后缀） | `...playwright.git` → `playwright` |\n| 3 | 本地路径/HTTP 文件 | 提取文件名（去掉扩展名） | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n### 详细规则说明\n\n#### 内联 JSON（inline-json）\n\n当源以 `{` 开头时，系统将其解析为 JSON 对象。如果格式为 `{\"\":{...}}`，直接提取 `` 作为资产名称。\n\n```typescript\n// 有效的内联 JSON 格式\n{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp@latest\"]}}\n// 推断名称: playwright\n```\n\n如果 JSON 包含 `mcpServers` 包装格式，系统会自动展开后提取名称：\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n// 推断名称: playwright\n```\n\n资料来源：[src/source/infer-name.ts:14-35](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n#### 内联 Markdown（inline-md）\n\n当源包含换行符 `\\n` 时，系统将其识别为内联 Markdown。名称从首个 `# Heading` 提取，并转换为 kebab-case 格式：\n\n```typescript\n# Code Review Rules\n// 推断名称: code-review\n```\n\n**限制**：内联 Markdown 格式仅支持 Prompt、Command 和 Sub-agent 类型的资产，不支持 Skill 类型。资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n#### Git URL 路径引用（#path）\n\nGit 源支持 `#path` 语法指定仓库内的子路径。名称从 `#` 后的路径段提取，去掉文件扩展名：\n\n```bash\nhttps://github.com/anthropics/skills.git#skills/webapp-testing\n// 推断名称: webapp-testing\n```\n\n```bash\nhttps://github.com/modelcontextprotocol/servers.git#.mcp.json\n// 推断名称: mcp.json → mcp\n```\n\n资料来源：[src/source/infer-name.ts:36-40](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n#### Git URL 无路径引用\n\n如果 Git URL 不包含 `#path`，系统从仓库 URL 中提取名称：\n\n```bash\nhttps://github.com/anthropics/skills.git\n// 推断名称: skills\n```\n\n```bash\ngit@github.com:anthropics/claude-code-skills.git\n// 推断名称: claude-code-skills\n```\n\n#### 本地路径和 HTTP 文件\n\n对于本地文件路径或普通 HTTP 文件 URL，名称从文件名提取：\n\n```bash\n./mcps/playwright.json\n// 推断名称: playwright\n```\n\n```bash\nhttps://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs/.cursorrules\n// 推断名称: .cursorrules → cursorrules\n```\n\n## 源解析器实现\n\n### 模块结构\n\n```mermaid\ngraph LR\n A[src/source/index.ts] --> B[infer-name.ts]\n A --> C[git.ts]\n A --> D[http-file.ts]\n A --> E[local.ts]\n A --> F[inline.ts]\n \n C --> G[解析 Git 仓库]\n D --> H[下载 HTTP 文件]\n E --> I[读取本地文件]\n F --> J[写入临时文件]\n```\n\n### Git 解析器\n\n`git.ts` 负责处理 Git 仓库源的解析，支持稀疏检出（sparse checkout）功能。\n\n**核心功能**：\n\n- 支持 `git@` SSH 格式和 `https://` HTTP 格式\n- 支持 `#path` 语法指定子目录或文件\n- 使用 `git init` + `git remote add` + `git fetch` + `git checkout` 实现稀疏检出\n\n资料来源：[src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n\n### HTTP 文件解析器\n\n`http-file.ts` 负责从 HTTP/HTTPS URL 下载单个文件。\n\n**限制**：\n\n- 仅支持 Prompt、Command、Sub-agent 和 MCP 类型的资产\n- **不支持** Skill 类型资产（HTTP 源安装 Skill 会导致错误，退出码 2）\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts) 和 [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n\n### 本地路径解析器\n\n`local.ts` 负责读取本地文件系统中的源文件或目录。\n\n**功能**：\n\n- 支持单个文件路径\n- 支持目录路径（会递归处理目录内容）\n- 对于目录源，系统会遍历目录并将每个文件作为独立资产处理\n\n资料来源：[src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n\n### 内联内容解析器\n\n`inline.ts` 负责将内联内容写入临时文件，供后续处理流程使用。\n\n**处理流程**：\n\n1. 根据内容类型（JSON 或 Markdown）确定文件扩展名\n2. 在系统临时目录中创建唯一命名的临时文件\n3. 将内容写入临时文件\n4. 返回临时文件路径，供后续处理使用\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n\n## 错误处理\n\n### 内联 JSON 解析错误\n\n```typescript\n// 如果 JSON 格式错误\n内联 JSON 解析失败。格式应为 {\"\":{...}}，例如：{\"playwright\":{\"command\":\"npx\",\"args\":[\"-y\",\"@playwright/mcp\"]}}\n```\n\n### 内联类型不匹配\n\n```typescript\n// HTTP 源安装 Skill 时\nagent-add error: HTTP sources cannot install Skill assets\n```\n\n```typescript\n// 内联源安装 Skill 时\nagent-add error: Inline sources cannot install Skill assets\n```\n\n### 名称推断失败\n\n当无法从源字符串推断有效名称时，系统会报错并退出。\n\n## 与其他模块的交互\n\n源解析模块位于 `agent-add` 安装流程的前端，解析结果传递给后续模块：\n\n```mermaid\ngraph TD\n A[CLI 入口] --> B[源格式识别]\n B --> C{识别源类型}\n C --> D[名称推断]\n D --> E[解析源内容]\n E --> F[验证资产]\n F --> G[构建安装任务]\n G --> H[执行安装]\n \n D --> D1[infer-name.ts]\n E --> E1[git.ts / http-file.ts / local.ts / inline.ts]\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 最佳实践\n\n### 源格式选择建议\n\n| 场景 | 推荐格式 | 示例 |\n|------|----------|------|\n| MCP 服务器配置 | 内联 JSON | `{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}` |\n| 简单 Prompt | 内联 Markdown | `--prompt $'# Review Rules\\n\\nCheck for bugs...'` |\n| 复杂/可复用的资产 | Git URL | `https://github.com/org/skills.git#skills/pdf` |\n| 本地开发测试 | 本地路径 | `./my-skill/` |\n| 团队共享资源 | HTTP URL | `https://team.com/rules/code-review.md` |\n\n### 名称规范\n\n- 资产名称只能包含 `[a-zA-Z0-9_-]` 字符\n- MCP 类型：名称从配置文件键名推断\n- 其他类型：使用 kebab-case 格式\n\n---\n\n\n\n## 系统架构总览\n\n### 相关页面\n\n相关主题：[Source 模块详解](#p-source-module), [Host 适配器系统](#p-host-system), [核心功能使用指南](#p-usage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/assets/mcp.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/mcp.ts)\n- [src/assets/skill.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/skill.ts)\n- [src/assets/prompt.ts](https://github.com/pea3nut/agent-add/blob/main/src/assets/prompt.ts)\n
\n\n# 系统架构总览\n\n## 1. 项目概述\n\nagent-add 是一个跨主机（Host）的 AI 代理资产安装工具，用于将 MCP Servers、Skills、Prompts、Commands、Sub-agents 等资产统一安装到不同的 AI 编程工具中。\n\n项目核心目标是解决 AI 代理生态碎片化问题——每种 AI 工具（如 Cursor、Claude Code、Windsurf 等）都有自己独立的资产配置格式和存储路径，agent-add 通过抽象适配层实现了**一次定义，多端安装**的能力。\n\n## 2. 系统架构图\n\n```mermaid\ngraph TD\n subgraph CLI层\n A[CLI 入口] --> B[Commander 解析]\n B --> C[TTY 检测]\n C --> D{非 TTY 环境?}\n D -->|是| E[强制要求 --host 参数]\n D -->|否| F[交互式选择 Host]\n end\n\n subgraph 核心处理层\n G[CLI Input] --> H[显式标志能力检查]\n H --> I[Source 解析]\n I --> J[资产验证]\n J --> K[构建 InstallJob]\n K --> L[分发到对应 Handler]\n end\n\n subgraph 资产处理层\n L --> M[MCP Handler]\n L --> N[Skill Handler]\n L --> O[Prompt Handler]\n L --> P[Command Handler]\n L --> Q[Sub-agent Handler]\n end\n\n subgraph Host 适配层\n M --> R[Cursor Adapter]\n M --> S[Claude Code Adapter]\n M --> T[Codex Adapter]\n M --> U[Vibe Adapter]\n N --> R\n O --> R\n O --> S\n end\n\n R --> V[结果汇总]\n S --> V\n T --> V\n U --> V\n V --> W[Summary 输出]\n```\n\n## 3. 目录结构\n\n```\nagent-add/\n├── src/\n│ ├── index.ts # 程序入口，创建 Commander 实例\n│ ├── cli.ts # CLI 参数定义与解析\n│ ├── installer.ts # 核心编排逻辑\n│ ├── hosts/ # 主机适配层\n│ │ ├── types.ts # HostAdapter 接口定义\n│ │ ├── index.ts # 主机注册表\n│ │ ├── README.md # 能力矩阵（唯一信源）\n│ │ ├── cursor.ts\n│ │ ├── claude-code.ts\n│ │ ├── vibe.ts # TOML 格式支持\n│ │ └── ... # 其他 15 种主机适配器\n│ ├── assets/ # 资产处理器\n│ │ ├── mcp.ts # MCP 配置安装\n│ │ ├── skill.ts # Skill 目录安装\n│ │ ├── prompt.ts # Prompt 文件安装\n│ │ ├── command.ts # Command 文件安装\n│ │ └── sub-agent.ts # Sub-agent 文件安装\n│ ├── source/ # 源解析模块\n│ │ ├── resolve.ts # 源解析器\n│ │ └── infer-name.ts # 资产名称推断\n│ ├── utils/ # 工具函数\n│ │ └── unwrap-mcp-servers.js # MCP 配置解包\n│ └── summary.ts # 结果格式化输出\n├── tests/\n│ ├── unit/ # 单元测试\n│ └── features/ # Gherkin 场景测试\n└── bin/\n └── agent-add.js # 编译后的可执行文件\n```\n\n## 4. 核心数据流\n\n```mermaid\ngraph LR\n A[CLI Flags / --pack Manifest] --> B[AssetDescriptor]\n B --> C[ResolvedSource]\n C --> D[InstallJob]\n D --> E[InstallResult]\n E --> F[Summary]\n \n A1[显式标志能力检查] -.->|exit 2| A\n C1[验证失败] -.->|exit 2| C\n D1[不支持的资产] -.->|skip| D\n```\n\n### 4.1 数据模型\n\n| 模型 | 描述 | 字段 |\n|------|------|------|\n| `CliInput` | CLI 参数输入 | `pack`, `mcp`, `skill`, `prompt`, `command`, `subAgent`, `host` |\n| `AssetDescriptor` | 资产描述符 | `assetType`, `source`, `fromExplicitFlag` |\n| `ResolvedSource` | 解析后的源 | `type`, `localPath`, `tempDir`, `originalSource` |\n| `InstallJob` | 安装任务 | `assetType`, `assetName`, `resolvedSource`, `host` |\n| `InstallResult` | 安装结果 | `job`, `status`, `reason` |\n\n### 4.2 源类型（Source Types）\n\n| 类型 | 描述 | 格式示例 |\n|------|------|----------|\n| `local` | 本地文件系统路径 | `./mcps/playwright.json` |\n| `git` | Git 仓库 URL | `https://github.com/...#path/to/asset` |\n| `http-file` | HTTP/HTTPS 直接下载 | `https://example.com/config.json` |\n| `inline-json` | 内联 JSON（MCP 专用） | `{\"name\":{\"command\":\"npx\",\"args\":[...]}}` |\n| `inline-md` | 内联 Markdown（Prompt/Command/Sub-agent 专用） | `# Title\\n\\nContent...` |\n\n## 5. 模块详解\n\n### 5.1 CLI 层（src/cli.ts）\n\nCLI 层负责用户交互和参数验证：\n\n```typescript\n// 核心参数定义（资料来源：src/cli.ts）\n.option('--pack ', 'Install an Agent Pack manifest')\n.option('--mcp ', 'Install an MCP Server')\n.option('--skill ', 'Install a Skill directory')\n.option('--prompt ', 'Install a Prompt file')\n.option('--command ', 'Install a Command')\n.option('--sub-agent ', 'Install a Sub-agent')\n.option('--host ', 'Target host ID')\n```\n\n**TTY 检测逻辑**：\n\n- **TTY 环境**：用户可交互选择 Host\n- **非 TTY 环境（CI）**：必须显式指定 `--host`，否则退出并报错\n\n### 5.2 安装编排器（src/installer.ts）\n\n编排器是系统的核心，负责串联整个安装流程：\n\n| 阶段 | 函数 | 职责 |\n|------|------|------|\n| 1 | 解析输入 | 将 `CliInput` 转换为 `AssetDescriptor[]` |\n| 2 | 源解析 | 将源字符串解析为 `ResolvedSource[]` |\n| 3 | 验证 | 检查资产有效性（文件存在、格式正确） |\n| 4 | 作业构建 | 根据 Host 能力过滤，生成 `InstallJob[]` |\n| 5 | 处理器分发 | 调用对应的 `AssetHandler` |\n| 6 | 结果汇总 | 聚合所有安装结果并输出 |\n\n### 5.3 主机适配层（src/hosts/）\n\n```mermaid\nclassDiagram\n class HostAdapter {\n <>\n +id: string\n +displayName: string\n +docs: string\n +assets: Record~AssetType, AssetCapability~\n }\n \n class AssetCapability {\n +supported: boolean\n +writeStrategy: WriteStrategy\n +installDir?: string\n +configFile?: string\n +reason?: string\n }\n \n HostAdapter o-- AssetCapability\n \n CursorAdapter ..|> HostAdapter\n ClaudeCodeAdapter ..|> HostAdapter\n VibeAdapter ..|> HostAdapter\n```\n\n**当前支持的 18 种主机**：\n\n| 主机 ID | 配置文件格式 | 资产类型支持 |\n|---------|-------------|-------------|\n| `cursor` | JSON | MCP, Prompt, Command, Sub-agent |\n| `claude-code` | JSON | MCP, Prompt, Command, Sub-agent |\n| `claude-desktop` | JSON | MCP only |\n| `windsurf` | JSON | MCP, Prompt, Command |\n| `roo-code` | JSON | MCP, Prompt, Command |\n| `codex` | TOML | MCP, Prompt |\n| `vibe` | TOML | MCP, Prompt |\n| `kimi` | JSON | MCP, Prompt |\n| `trae` | JSON | MCP, Prompt |\n| `openclaw` | JSON | MCP, Prompt |\n| `gemini` | JSON | MCP, Prompt |\n| `github-copilot` | JSON | MCP, Prompt |\n| `kilo-code` | JSON | MCP, Prompt |\n| `qwen-code` | JSON | MCP, Prompt |\n| `opencode` | JSON | MCP, Prompt |\n| `augment` | JSON | MCP, Prompt |\n| `kiro` | JSON | MCP, Prompt |\n| `tabnine` | JSON | MCP, Prompt |\n\n### 5.4 资产处理器层（src/assets/）\n\n每种资产类型都有独立的处理器，统一实现 `AssetHandler` 接口：\n\n```mermaid\nflowchart LR\n subgraph AssetHandlers\n A[MCP Handler] -->|JSON shallow merge| A1[atomic write]\n B[Skill Handler] -->|directory copy| B1[SKILL.md validation]\n C[Prompt Handler] -->|marker append| C1[HTML 标记追加]\n D[Command Handler] -->|file write| D1[frontmatter parse]\n E[Sub-agent Handler] -->|host specialization| E1[agent-add/* 提升]\n end\n```\n\n| 处理器 | 写入策略 | 关键特性 |\n|--------|----------|---------|\n| `mcp.ts` | 原子写入 | JSON 浅合并、`.toml` 自动识别 |\n| `skill.ts` | 目录复制 | 递归复制、SKILL.md 存在性验证 |\n| `prompt.ts` | 追加或独立文件 | HTML 标记块（幂等追加） |\n| `command.ts` | 文件写入 | YAML frontmatter 解析 |\n| `sub-agent.ts` | 文件写入 | `agent-add//*` 主机专用字段提升 |\n\n## 6. 关键设计决策\n\n### 6.1 原子 JSON 写入\n\nMCP 配置文件使用临时文件 + 重命名的原子操作保证写入安全：\n\n```\n写入流程：config.json → .config.json.tmp → atomic rename → config.json\n```\n\n### 6.2 幂等追加策略\n\nPrompt 资产使用 HTML 注释标记实现幂等追加：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n### 6.3 TOML 格式自动识别\n\n`mcp.ts` 检测文件扩展名，`.toml` 文件自动路由到 TOML 处理路径：\n\n| 扩展名 | 解析方式 |\n|--------|----------|\n| `.json` | 标准 JSON 解析 |\n| `.toml` | smol-toml 库解析 |\n\n### 6.4 显式标志能力拒绝\n\n`installer.ts` 在构建作业前检查主机的显式标志能力声明：\n\n- `supported: false` → 输出错误信息 + README 链接，退出码 2\n- `--pack` 源跳过此检查\n\n## 7. 错误处理\n\n| 错误场景 | 退出码 | 处理方式 |\n|----------|--------|----------|\n| 非 TTY 环境未指定 `--host` | 2 | stderr 输出有效 Host 列表 |\n| 无效的资产标志 | 2 | stderr 提示有效选项 |\n| 源解析失败 | 2 | stderr 输出详细错误 |\n| 资产验证失败 | 2 | stderr 输出验证原因 |\n| 安装冲突 | 1 | 列出冲突项 |\n| 安装错误 | 1 | 列出错误详情 |\n\n## 8. 扩展指南\n\n### 8.1 添加新主机\n\n1. 创建 `src/hosts/.ts`，实现 `HostAdapter` 接口\n2. 在 `src/hosts/index.ts` 注册\n3. 更新 `src/hosts/README.md` 能力矩阵\n4. 创建 `tests/unit/hosts/.test.ts` 单元测试\n\n### 8.2 添加新资产类型\n\n1. 在 `src/assets/` 创建新处理器\n2. 实现 `AssetHandler` 接口\n3. 在 `src/installer.ts` 添加分发逻辑\n\n## 9. 相关文档\n\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md) - 项目主文档\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md) - 主机能力矩阵（唯一信源）\n- [vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md) - 系统设计提示\n\n---\n\n\n\n## Source 模块详解\n\n### 相关页面\n\n相关主题：[系统架构总览](#p-arch), [源格式与名称推断](#p-source-formats)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n- [src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n- [src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts)\n- [src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n- [src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n- [src/source/expand-directory.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/expand-directory.ts)\n
\n\n# Source 模块详解\n\n## 模块概述\n\nSource 模块是 agent-add 项目的核心组件之一，负责将用户提供的资产来源（source）解析为可操作的本地文件路径。该模块支持多种来源类型，包括本地路径、Git 仓库、HTTP URL 以及内联内容，并为每种类型实现了专门的解析逻辑。\n\nSource 模块在整个安装流程中的位置至关重要：\n\n```\nCLI 输入（--mcp/--skill/--prompt/--command/--sub-agent/--pack）\n ↓\n[Source 模块] ← 资产来源解析\n ↓\nResolvedSource[]（包含 localPath 和 tempDir）\n ↓\n验证与安装\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 支持的来源类型\n\n根据源码分析，Source 模块支持以下六种来源类型：\n\n| 类型 | 标识 | 描述 |\n|------|------|------|\n| 本地路径 | `local` | 本地文件系统路径 |\n| Git SSH | `git-ssh` | `git@` 开头的 SSH 地址 |\n| Git HTTPS | `git-https` | `https://` 或 `http://` 开头的 Git 地址 |\n| HTTP 文件 | `http-file` | 直接的 HTTP/HTTPS 文件 URL |\n| 内联 JSON | `inline-json` | 以 `{` 开头的内联 JSON 字符串（仅限 MCP） |\n| 内联 Markdown | `inline-md` | 包含换行符的内联 Markdown（Prompt/Command/Sub-agent） |\n\n资料来源：[vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n## 模块架构\n\n### 目录结构\n\n```\nsrc/source/\n├── index.ts # 统一入口，类型检测与路由分发\n├── local.ts # 本地路径解析\n├── git.ts # Git 仓库解析（支持稀疏检出）\n├── http-file.ts # HTTP URL 下载解析\n├── inline.ts # 内联内容转临时文件\n└── expand-directory.ts # 目录展开（支持 glob 模式）\n```\n\n### 核心接口\n\nSource 模块的核心接口返回 `ResolvedSource` 数据结构：\n\n```typescript\ninterface ResolvedSource {\n type: SourceType; // 来源类型标识\n localPath: string; // 本地文件路径\n tempDir?: string; // 临时目录路径（内联内容专用）\n originalSource: string; // 原始输入字符串\n}\n```\n\n资料来源：[src/source/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/index.ts)\n\n## 来源类型解析详解\n\n### 1. 本地路径解析\n\n本地路径解析器（`local.ts`）处理相对路径和绝对路径的本地文件系统引用。\n\n**工作流程：**\n\n```mermaid\ngraph TD\n A[输入 source] --> B{是否为绝对路径?}\n B -->|是| C[直接返回绝对路径]\n B -->|否| D[相对于 cwd 解析]\n D --> E{路径存在?}\n E -->|是| F[返回解析后路径]\n E -->|否| G[抛出错误: 文件不存在]\n```\n\n**关键约束：**\n- 路径必须存在且可访问\n- Skill 类型资产的本地路径必须包含 `SKILL.md` 文件\n\n资料来源：[src/source/local.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/local.ts)\n\n### 2. Git 仓库解析\n\nGit 解析器（`git.ts`）支持从 Git 仓库获取资产，支持稀疏检出（sparse checkout）语法。\n\n**Git URL 格式支持：**\n\n| 格式 | 示例 | 解析结果 |\n|------|------|----------|\n| SSH 格式 | `git@github.com:user/repo.git` | 仓库名 `repo` |\n| HTTPS 格式 | `https://github.com/user/repo.git` | 仓库名 `repo` |\n| 带路径引用 | `...git#path/to/asset` | 使用路径最后段作为名称 |\n\n**稀疏检出功能：**\n\n使用 `#` 语法可以只检出仓库中的特定路径：\n\n```bash\n# 检出仓库中的 skills/pdf 目录\nnpx -y agent-add --skill 'https://github.com/anthropics/skills.git#skills/pdf'\n```\n\nGit 解析器会自动执行稀疏检出，只下载指定路径的内容。\n\n资料来源：[src/source/git.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/git.ts)\n\n### 3. HTTP 文件解析\n\nHTTP 解析器（`http-file.ts`）从远程 URL 下载文件内容。\n\n**使用限制：**\n\n> ⚠️ **重要约束**：HTTP 来源类型**不支持** Skill 资产类型。尝试使用 HTTP URL 安装 Skill 会导致安装失败并返回错误码 2。\n\n```mermaid\ngraph TD\n A[HTTP URL] --> B{资产类型?}\n B -->|skill| C[返回错误: 不支持]\n B -->|其他类型| D[下载到临时文件]\n D --> E[返回 tempDir 路径]\n```\n\n资料来源：[src/source/http-file.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/http-file.ts) \n资料来源：[vibe/system-prompt.md](https://github.com/pea3nut/agent-add/blob/main/vibe/system-prompt.md)\n\n### 4. 内联内容解析\n\n内联解析器（`inline.ts`）将命令行中直接传入的内容写入临时文件。\n\n**两种内联格式：**\n\n| 格式 | 识别特征 | 适用资产 |\n|------|----------|----------|\n| 内联 JSON | 字符串以 `{` 开头 | MCP |\n| 内联 Markdown | 字符串包含 `\\n` 且无 JSON 特征 | Prompt/Command/Sub-agent |\n\n**内联 JSON 示例：**\n\n```bash\nnpx -y agent-add --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}'\n```\n\n解析后生成临时文件，资产名称从 JSON 对象的顶级键提取。\n\n**内联 Markdown 示例：**\n\n```bash\nnpx -y agent-add --prompt $'# Code Review\\n\\nAlways review for security issues first.'\n```\n\n解析后生成临时文件，资产名称从第一个 `# 标题` 提取并转换为 kebab-case。\n\n资料来源：[src/source/inline.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/inline.ts)\n\n### 5. 目录展开\n\nexpand-directory.ts 提供了目录批量展开功能，支持 glob 模式匹配。\n\n**典型应用场景：**\n\n当用户提供的 source 是包含多个资产的目录时，该模块负责：\n1. 扫描目录下的所有匹配文件\n2. 为每个匹配项生成独立的 `ResolvedSource`\n3. 保持目录结构在资产名称中（如 `dirName/assetName`）\n\n资料来源：[src/source/expand-directory.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/expand-directory.ts)\n\n## 资产名称推断\n\n`infer-name.ts` 模块负责从来源字符串推断资产名称，这是确保正确安装的关键步骤。\n\n### 推断规则优先级\n\n| 优先级 | 来源类型 | 推断规则 |\n|--------|----------|----------|\n| 0 | 内联 JSON | 提取单个顶级键作为名称 |\n| 0 | 内联 Markdown | 提取第一个 `# 标题` 并转为 kebab-case |\n| 1 | 带 `#` 路径 | 使用路径最后段（去除扩展名） |\n| 2 | Git URL | 使用仓库名（去除 `.git` 后缀） |\n| 3 | 本地路径/HTTP | 使用文件名（去除扩展名） |\n\n### 名称转换示例\n\n| 原始来源 | 推断名称 |\n|----------|----------|\n| `...git#skills/pdf` | `pdf` |\n| `...playwright.git` | `playwright` |\n| `./mcps/playwright.json` | `playwright` |\n| `# Code Review` → | `code-review` |\n\n资料来源：[src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n\n## 类型验证流程\n\n### 验证时机\n\n在 Source 模块解析完成后，`installer.ts` 会对每个 `ResolvedSource` 进行资产特定的验证：\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI 输入\n participant Source as Source 模块\n participant Validator as 验证器\n participant Installer as 安装器\n\n CLI->>Source: 传入 source 字符串\n Source->>Source: 解析为 ResolvedSource\n Source->>Validator: 调用 validateAsset()\n Validator->>Validator: 根据资产类型验证\n alt 验证通过\n Validator-->>Installer: 返回 null\n else 验证失败\n Validator-->>Installer: 返回错误消息\n Installer->>Installer: 输出错误并 exit(2)\n end\n```\n\n### 各资产类型的验证规则\n\n| 资产类型 | 必需验证 | 失败条件 |\n|----------|----------|----------|\n| `skill` | SKILL.md 存在 | 目录内缺少 SKILL.md |\n| `mcp` | 文件存在 + 扩展名 | 文件不存在或非 .json 扩展名 |\n| `prompt` | 无特殊验证 | — |\n| `command` | 无特殊验证 | — |\n| `subAgent` | 无特殊验证 | — |\n\n**Skill 类型的额外限制：**\n\n```typescript\nif (assetType === 'skill') {\n if (resolved.type === 'http-file' || \n resolved.type === 'inline-json' || \n resolved.type === 'inline-md') {\n return 'Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL';\n }\n // 验证 SKILL.md 存在\n}\n```\n\n资料来源：[src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n\n## 错误处理\n\nSource 模块的错误处理遵循统一的退出码规范：\n\n| 退出码 | 含义 | 触发场景 |\n|--------|------|----------|\n| 0 | 成功 | 所有资产安装成功 |\n| 1 | 部分成功 | 存在冲突或错误但可继续 |\n| 2 | 严重错误 | 参数错误、验证失败、不支持的配置 |\n\n**常见错误消息：**\n\n- `MCP 来源文件不存在：` — MCP 文件路径无效\n- `MCP 来源文件扩展名必须为 .json` — 文件类型错误\n- `Skill 目录内缺少 SKILL.md 文件` — Skill 目录结构不完整\n- `内联 JSON 解析失败` — JSON 格式错误\n\n## 与其他模块的集成\n\n### 数据流图\n\n```mermaid\ngraph LR\n subgraph Source模块\n A[local.ts] --> D[index.ts]\n B[git.ts] --> D\n C[http-file.ts] --> D\n E[inline.ts] --> D\n F[expand-directory.ts] --> D\n end\n\n subgraph Installer模块\n D --> G[validateAsset]\n G --> H[创建 InstallJob]\n end\n\n subgraph 资产处理器\n H --> I[mcp.ts]\n H --> J[skill.ts]\n H --> K[prompt.ts]\n end\n```\n\n### 关键集成点\n\n1. **CLI 层** (`src/cli.ts`)：接收用户输入，调用 `runInstaller()`\n2. **安装编排层** (`src/installer.ts`)：协调 Source 解析、验证、安装\n3. **资产处理层** (`src/assets/*.ts`)：消费 Source 模块的解析结果\n\n## 总结\n\nSource 模块是 agent-add 架构中负责来源抽象的关键层，它：\n\n- 提供了六种统一的来源类型抽象\n- 实现了健壮的错误处理和验证机制\n- 支持复杂的 Git 稀疏检出场景\n- 为内联内容提供了透明的临时文件机制\n\n理解 Source 模块的工作原理对于调试安装问题、扩展支持新的来源类型，以及深入理解整个 agent-add 系统都至关重要。\n\n---\n\n\n\n## Host 适配器系统\n\n### 相关页面\n\n相关主题：[系统架构总览](#p-arch), [核心功能使用指南](#p-usage), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/hosts/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/index.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/cursor.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/cursor.ts)\n- [src/hosts/claude-code.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/claude-code.ts)\n- [src/hosts/windsurf.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/windsurf.ts)\n- [src/hosts/codex.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/codex.ts)\n- [src/hosts/README.md](https://github.com/pea3nut/agent-add/blob/main/src/hosts/README.md)\n- [src/utils/detect-hosts.ts](https://github.com/pea3nut/agent-add/blob/main/src/utils/detect-hosts.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n
\n\n# Host 适配器系统\n\n## 概述\n\nHost 适配器系统是 agent-add 的核心抽象层，负责将安装逻辑与具体的 AI 编程工具（Host）解耦。该系统定义了每种 Host 支持的资产类型、安装路径、写入策略等配置，使 agent-add 能够以统一的方式向不同 Host 安装 MCP Servers、Skills、Prompts、Commands 和 Sub-agents。\n\n系统当前支持 18 种主流 AI 编程工具，包括 Cursor、Claude Code、Windsurf、GitHub Copilot 等，形成了完整的主机适配矩阵。\n\n## 架构设计\n\n### 核心组件\n\n```mermaid\ngraph TD\n A[CLI 输入] --> B[installer.ts]\n B --> C[Host 注册表]\n C --> D{Host 检测?}\n D -->|是| E[detect-hosts.ts]\n D -->|否| F[使用 --host 参数]\n E --> G[返回 HostAdapter]\n F --> G\n G --> H[资产处理器]\n H --> I[MCP 处理器]\n H --> J[Skill 处理器]\n H --> K[Prompt 处理器]\n H --> L[Command 处理器]\n H --> M[Sub-agent 处理器]\n```\n\n### 目录结构\n\n```\nsrc/\n├── hosts/ # Host 适配器系统核心\n│ ├── index.ts # Host 注册表（Map）\n│ ├── types.ts # 核心类型定义\n│ ├── README.md # 主机能力矩阵（单一信息源）\n│ ├── cursor.ts # Cursor 适配器\n│ ├── claude-code.ts # Claude Code 适配器\n│ ├── windsurf.ts # Windsurf 适配器\n│ ├── codex.ts # Codex CLI 适配器\n│ └── .ts # 其他主机适配器\n└── utils/\n └── detect-hosts.ts # 自动检测当前环境中的 Host\n```\n\n## 核心类型定义\n\n### HostAdapter 接口\n\n`src/hosts/types.ts` 定义了 `HostAdapter` 接口，所有主机适配器必须实现此接口：\n\n```typescript\ninterface HostAdapter {\n readonly id: string; // 主机唯一标识符\n readonly displayName: string; // 显示名称\n readonly docs: string; // 官方文档链接\n readonly detection: HostDetection; // 检测配置\n readonly assets: Record; // 资产能力配置\n}\n```\n\n### 资产能力配置\n\n```typescript\ninterface AssetCapability {\n supported: boolean;\n reason?: string; // 不支持时说明原因\n configFile?: ConfigFilePaths; // 配置文件路径（支持多平台）\n configKey?: string; // 配置键名\n writeStrategy?: WriteStrategy; // 写入策略\n targetFile?: string; // 目标文件名\n installDir?: string; // 安装目录\n entryFile?: string; // 入口文件\n fileExtension?: string; // 文件扩展名\n}\n```\n\n### 资产类型枚举\n\n| 类型 | 说明 | 用途 |\n|------|------|------|\n| `mcp` | MCP Server 配置 | 安装 MCP 服务器 |\n| `skill` | Skill 目录 | 安装可复用技能包 |\n| `prompt` | 规则/系统提示 | 安装提示词规则 |\n| `command` | 斜杠命令 | 安装自定义命令 |\n| `subAgent` | 子代理配置 | 安装子代理 |\n\n### 写入策略\n\n| 策略 | 说明 | 适用场景 |\n|------|------|----------|\n| `inject-json-key` | 向 JSON 配置注入键值 | MCP JSON 配置 |\n| `toml-array` | 向 TOML 数组追加 | Codex/Vibe MCP TOML |\n| `append-with-marker` | 使用 HTML 注释标记追加 | Cursor AGENTS.md 等 |\n| `create-file-in-dir` | 在目录中创建文件 | Windsurf 规则文件 |\n| `copy-file` | 复制文件到目标目录 | Skill、Command 等 |\n\n## Host 注册表\n\n`src/hosts/index.ts` 维护着一个 `Map` 类型的注册表，所有适配器在此注册后即可被系统识别和使用。\n\n```mermaid\ngraph LR\n A[主机适配器文件] --> B[index.ts 注册]\n B --> C[hostRegistry Map]\n C --> D[installer.ts 查询]\n C --> E[detect-hosts.ts 检测]\n```\n\n注册表示例结构：\n\n```typescript\nconst hostRegistry = new Map([\n ['cursor', new CursorAdapter()],\n ['claude-code', new ClaudeCodeAdapter()],\n ['windsurf', new WindsurfAdapter()],\n ['codex', new CodexAdapter()],\n // ... 其他适配器\n]);\n```\n\n## 支持的主机列表\n\n根据 `src/hosts/README.md` 中的能力矩阵，当前支持以下 18 种主机：\n\n| 主机 ID | 显示名称 | MCP | Prompt | Skill | Command | Sub-agent |\n|---------|----------|-----|--------|-------|---------|-----------|\n| cursor | Cursor | ✅ | ✅ | ✅ | ✅ | ✅ |\n| claude-code | Claude Code | ✅ | ✅ | ✅ | ✅ | ✅ |\n| claude-desktop | Claude Desktop | ✅ | ❌ | ❌ | ❌ | ❌ |\n| windsurf | Windsurf | ✅ | ✅ | ❌ | ❌ | ❌ |\n| github-copilot | GitHub Copilot | ✅ | ✅ | ❌ | ❌ | ❌ |\n| gemini | Gemini Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| roo-code | Roo Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| kilo-code | Kilo Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| qwen-code | Qwen Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| opencode | OpenCode | ✅ | ✅ | ❌ | ❌ | ❌ |\n| augment | Augment Code | ✅ | ✅ | ❌ | ❌ | ❌ |\n| kiro | Kiro | ✅ | ✅ | ❌ | ❌ | ❌ |\n| tabnine | Tabnine | ✅ | ✅ | ❌ | ❌ | ❌ |\n| kimi | Kimi | ✅ | ✅ | ❌ | ❌ | ❌ |\n| trae | Trae | ✅ | ✅ | ❌ | ❌ | ❌ |\n| openclaw | OpenClaw | ✅ | ✅ | ❌ | ❌ | ❌ |\n| codex | Codex CLI | ✅ | ✅ | ✅ | ❌ | ✅ |\n| vibe | Vibe | ✅ | ❌ | ❌ | ❌ | ❌ |\n\n## 主机检测机制\n\n`src/utils/detect-hosts.ts` 实现了自动检测当前环境中已安装的 Host 功能。检测逻辑基于各主机的特征路径：\n\n```typescript\n// 检测配置示例\nconst detection = {\n paths: ['~/.cursor/', '.cursor/'] // Cursor 检测路径\n};\n```\n\n### 检测优先级\n\n1. **显式指定优先**：用户通过 `--host ` 参数显式指定主机\n2. **自动检测次之**：非 TTY 环境下（如 CI）必须显式指定，否则退出\n3. **交互选择兜底**：TTY 环境下提供交互式主机选择菜单\n\n## 适配器实现示例\n\n### Cursor 适配器 (`src/hosts/cursor.ts`)\n\n```typescript\nexport class CursorAdapter implements HostAdapter {\n readonly id = 'cursor';\n readonly displayName = 'Cursor';\n readonly docs = 'https://cursor.com';\n readonly detection = {\n paths: ['~/.cursor/', '.cursor/'],\n };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: {\n darwin: '~/Library/Application Support/Cursor/User/globalStorage/sao-team.mcp-server-cli/hosts.json',\n linux: '~/.cursor/globalStorage/sao-team.mcp-server-cli/hosts.json',\n win32: '%APPDATA%\\\\Cursor\\\\User\\\\globalStorage\\\\sao-team.mcp-server-cli\\\\hosts.json',\n },\n writeStrategy: 'inject-json-key',\n },\n prompt: {\n supported: true,\n targetFile: 'AGENTS.md',\n writeStrategy: 'append-with-marker',\n },\n skill: {\n supported: true,\n installDir: '.cursor/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n },\n command: {\n supported: true,\n installDir: '.cursor/commands/',\n writeStrategy: 'copy-file',\n },\n subAgent: {\n supported: true,\n installDir: '.cursor/agents/',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n### Codex 适配器 (`src/hosts/codex.ts`)\n\nCodex 适配器展示了 TOML 配置的特殊处理：\n\n```typescript\nexport class CodexAdapter implements HostAdapter {\n readonly id = 'codex';\n readonly displayName = 'Codex CLI';\n readonly docs = 'https://github.com/openai/codex';\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: {\n darwin: '~/.codex/config.toml',\n linux: '~/.codex/config.toml',\n win32: '%USERPROFILE%\\\\.codex\\\\config.toml',\n },\n configKey: 'mcp_servers',\n writeStrategy: 'inject-json-key',\n },\n subAgent: {\n supported: true,\n installDir: '.codex/agents/',\n fileExtension: '.toml',\n writeStrategy: 'copy-file',\n },\n };\n}\n```\n\n## 新增主机适配器指南\n\n根据 `src/hosts/README.md` 的贡献指南，新增主机需要完成以下步骤：\n\n### 步骤 1：创建适配器文件\n\n在 `src/hosts/.ts` 中创建适配器类，实现 `HostAdapter` 接口：\n\n```typescript\nimport type { HostAdapter, AssetCapability, AssetType } from './types.js';\n\nconst NOT_SUPPORTED = (reason: string): AssetCapability => ({\n supported: false,\n reason,\n});\n\nexport class XxxAdapter implements HostAdapter {\n readonly id = 'xxx';\n readonly displayName = 'Xxx';\n readonly docs = 'https://xxx.com/docs';\n readonly detection = {\n paths: ['~/.xxx/'],\n };\n readonly assets: Record = {\n mcp: { /* 配置 */ },\n prompt: { /* 配置 */ },\n skill: { /* 配置 */ },\n command: { /* 配置 */ },\n subAgent: { /* 配置 */ },\n };\n}\n```\n\n### 步骤 2：注册到索引\n\n在 `src/hosts/index.ts` 的 `hostRegistry` Map 中添加新条目：\n\n```typescript\n['xxx', new XxxAdapter()]\n```\n\n### 步骤 3：更新能力矩阵\n\n在 `src/hosts/README.md` 中添加新主机的行和详细说明。\n\n### 步骤 4：添加单元测试\n\n创建 `tests/unit/hosts/.test.ts`，验证所有字段值与 README.md 完全一致。\n\n## 安装流程中的角色\n\n```mermaid\ngraph TD\n A[CLI flags / --pack Manifest] --> B[显式标志能力检查]\n B --> C[不支持则 exit 2]\n C --> D[AssetDescriptor[]]\n D --> E[源解析]\n E --> F[验证]\n F --> G[InstallJob[]]\n G --> H[跳过不支持的资产]\n H --> I[执行写入]\n I --> J[InstallResult[]]\n J --> K[Summary 输出]\n```\n\ninstaller.ts 中的关键逻辑会根据 host adapter 的配置决定：\n\n1. **能力检查**：验证目标主机是否支持该资产类型\n2. **路径解析**：根据 `configFile` 或 `installDir` 确定写入路径\n3. **策略选择**：根据 `writeStrategy` 选择对应的写入方式\n4. **结果记录**：返回 `skipped`/`written`/`exists`/`updated`/`conflict`/`error` 等状态\n\n## 不支持的资产处理\n\n当主机不支持特定资产类型时，适配器使用 `NOT_SUPPORTED(reason)` 辅助函数返回配置：\n\n```typescript\ncommand: NOT_SUPPORTED('Codex CLI does not support custom slash commands via files.')\n```\n\ninstaller.ts 会检测此配置并将相应资产标记为 `skipped`，同时输出原因说明。资料来源：[src/hosts/codex.ts:8-10]()\n\n## 关键设计决策\n\n| 决策 | 说明 | 来源 |\n|------|------|------|\n| 能力矩阵单一信息源 | `src/hosts/README.md` 是唯一的权威配置文档 | [src/hosts/README.md:1]() |\n| 原子写入 | MCP 配置使用临时文件+重命名确保安全 | [vibe/system-prompt.md:1]() |\n| 标记块追加 | Prompt 使用 HTML 注释实现幂等追加 | [vibe/system-prompt.md:1]() |\n| TOML 自动分发 | `.toml` 扩展名自动走 smol-toml 路径 | [src/hosts/codex.ts:1]() |\n| 非 TTY 严格模式 | CI 环境必须显式指定 --host | [src/hosts/README.md:1]() |\n\n## 总结\n\nHost 适配器系统通过统一的接口抽象，使 agent-add 能够以插件式架构支持多种 AI 编程工具。系统设计遵循以下原则：\n\n- **可扩展性**：新增主机只需实现 `HostAdapter` 接口并注册\n- **一致性**：能力矩阵作为单一信息源，确保文档与实现同步\n- **容错性**：不支持的资产优雅降级为 `skipped` 状态\n- **安全性**：原子写入操作避免配置损坏风险\n\n该系统已覆盖市场上主流的 18 种 AI 编程工具，并预留了完善的扩展机制以支持未来可能出现的新工具。\n\n---\n\n\n\n## CLI 参考文档\n\n### 相关页面\n\n相关主题：[核心功能使用指南](#p-usage), [安装与快速开始](#p-installation), [Pack Manifest 格式规范](#p-pack-manifest)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [src/index.ts](https://github.com/pea3nut/agent-add/blob/main/src/index.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [package.json](https://github.com/pea3nut/agent-add/blob/main/package.json)\n
\n\n# CLI 参考文档\n\n## 概述\n\nagent-add 是一个跨宿主 AI Agent 资源安装 CLI 工具，支持将 MCP、Skill、Prompt、Command、Sub-agent 等资源安装到不同的 AI 代理宿主（如 Cursor、Claude Code、Claude Desktop 等）。CLI 模块是该工具的入口层，负责命令行参数解析、宿主检测和安装流程的编排。\n\nCLI 模块的核心职责包括：\n\n- 定义所有命令行选项和子命令\n- 检测运行环境（TTY / Non-TTY）\n- 提供交互式宿主选择功能\n- 收集用户输入并调用安装器核心逻辑\n- 输出安装结果摘要\n\n**源码位置**：`src/cli.ts` 资料来源：[src/cli.ts:1-1]()\n\n## 命令行接口架构\n\n### 入口流程\n\nCLI 模块采用 **Commander.js** 框架构建命令行界面。入口点为 `src/index.ts`，通过 `createProgram()` 创建程序实例并异步解析命令行参数。\n\n```mermaid\ngraph TD\n A[Node.js 进程启动] --> B[src/index.ts 入口]\n B --> C[createProgram 创建程序]\n C --> D[program.parseAsync 解析 argv]\n D --> E{是否有资产标志?}\n E -->|否| F[输出错误并退出 2]\n E -->|是| G{是否指定 --host?}\n G -->|是| H[使用指定宿主]\n G -->|否| I{是否为 TTY 环境?}\n I -->|否| J[输出错误并退出 2]\n I -->|是| K[交互式选择宿主]\n H --> L[runInstaller 执行安装]\n K --> L\n L --> M[printSummary 输出摘要]\n M --> N[是否存在冲突或错误?]\n N -->|是| O[exit 1]\n N -->|否| P[正常退出 0]\n```\n\n资料来源：[src/index.ts:1-10]()\n资料来源：[src/cli.ts:1-100]()\n\n### 核心数据结构\n\nCLI 模块使用 TypeScript 接口定义输入输出的数据结构：\n\n```typescript\ninterface CliInput {\n mcp: string[];\n skill: string[];\n prompt: string[];\n command: string[];\n subAgent: string[];\n pack: string[];\n host?: string;\n}\n```\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `mcp` | `string[]` | MCP 服务器配置源列表 |\n| `skill` | `string[]` | Skill 目录源列表 |\n| `prompt` | `string[]` | Prompt 文件源列表 |\n| `command` | `string[]` | Command 文件源列表 |\n| `subAgent` | `string[]` | Sub-agent 文件源列表 |\n| `pack` | `string[]` | Pack 清单文件源列表 |\n| `host` | `string \\| undefined` | 目标宿主 ID（可选） |\n\n资料来源：[src/cli.ts:30-50]()\n\n## 命令行选项\n\n### 资产安装选项\n\nagent-add 支持通过以下标志安装不同类型的资源，所有选项均支持重复使用以安装多个同类型资源：\n\n| 选项 | 说明 | 可重复 |\n|------|------|--------|\n| `--pack ` | 安装 Agent Pack 清单（批量安装） | ✅ |\n| `--mcp ` | 安装 MCP 服务器配置 | ✅ |\n| `--skill ` | 安装 Skill 目录 | ✅ |\n| `--prompt ` | 安装 Prompt 文件（系统提示词） | ✅ |\n| `--command ` | 安装 Command 文件（斜杠命令） | ✅ |\n| `--sub-agent ` | 安装 Sub-agent 文件 | ✅ |\n\n资料来源：[src/cli.ts:60-80]()\n\n### 宿主指定选项\n\n| 选项 | 说明 | 必需性 |\n|------|------|--------|\n| `--host ` | 指定目标宿主 ID | TTY 环境可选，CI 环境必填 |\n\n支持的宿主 ID 包括：`cursor`、`claude-code`、`claude-desktop`、`windsurf`、`github-copilot`、`gemini`、`roo-code`、`kilo-code`、`qwen-code`、`opencode`、`augment`、`kiro`、`tabnine`、`kimi`、`trae`、`openclaw`、`codex`、`vibe`。\n\n资料来源：[src/cli.ts:82]()\n资料来源：[src/hosts/README.md]()\n\n### 辅助选项\n\n| 选项 | 说明 |\n|------|------|\n| `-V, --version` | 显示版本号 |\n| `-h, --help` | 显示帮助信息 |\n\n## 输入验证规则\n\n### 资产标志检测\n\nCLI 模块在解析参数后首先检查是否提供了至少一个资产安装标志：\n\n```typescript\nconst hasAssetFlags =\n cliInput.pack.length > 0 ||\n cliInput.mcp.length > 0 ||\n cliInput.skill.length > 0 ||\n cliInput.prompt.length > 0 ||\n cliInput.command.length > 0 ||\n cliInput.subAgent.length > 0;\n\nif (!hasAssetFlags) {\n process.stderr.write(\n 'agent-add error: No asset flags provided. Use --pack, --mcp, --skill, --prompt, --command, or --sub-agent.\\n',\n );\n process.exit(2);\n}\n```\n\n**错误条件**：未提供任何资产安装标志时，程序输出错误信息并以退出码 2 终止。\n\n资料来源：[src/cli.ts:85-100]()\n\n### 宿主指定检测\n\n```mermaid\ngraph TD\n A[解析 CLI 参数] --> B{--host 是否指定?}\n B -->|是| C[使用指定 hostId]\n B -->|否| D{是否为 TTY?}\n D -->|否| E[输出错误: CI 环境必须指定 --host]\n D -->|是| F[进入交互式选择流程]\n E --> G[exit 2]\n F --> H[显示宿主选择列表]\n H --> I[用户选择宿主]\n I --> C\n```\n\nCLI 环境检测逻辑：\n\n```typescript\nif (cliInput.host) {\n hostId = cliInput.host;\n} else if (!process.stdout.isTTY) {\n const validIds = getValidHostIds().join(', ');\n process.stderr.write(\n `agent-add error: No host specified. In non-TTY environments, you must explicitly specify --host.\\n` +\n `Valid hosts: ${validIds}\\n`,\n );\n process.exit(2);\n}\n```\n\n**错误条件**：在非 TTY 环境下（如 CI/CD 流水线）未指定 `--host` 参数时，程序输出可用宿主列表并以退出码 2 终止。\n\n资料来源：[src/cli.ts:100-115]()\n\n## 宿主选择流程\n\n### 交互式选择\n\n当在 TTY 环境下未指定 `--host` 时，CLI 提供交互式宿主选择功能：\n\n```typescript\nconst hostSelection = await inquirer.createPromptModule()({\n type: 'select',\n message: 'Select a host to install to:',\n choices: getValidHostIds(),\n});\n\nhostId = hostSelection.host;\n```\n\n用户通过上下箭头选择目标宿主，按 Enter 确认。\n\n资料来源：[src/cli.ts:55-58]()\n\n### 有效宿主 ID 获取\n\n`getValidHostIds()` 函数从宿主注册表中获取所有已注册的有效宿主 ID：\n\n```typescript\nimport { hostRegistry } from './hosts/index.js';\n\nexport function getValidHostIds(): string[] {\n return [...hostRegistry.keys()];\n}\n```\n\n资料来源：[src/cli.ts:15-20]()\n\n## 安装流程编排\n\n### 安装执行\n\n选定宿主后，CLI 模块调用 `runInstaller()` 函数执行实际的安装逻辑：\n\n```typescript\nconst cwd = process.cwd();\nconst summary = await runInstaller(cliInput, host, cwd);\nprintSummary(summary);\n```\n\n- `cwd`：当前工作目录，作为相对路径解析的基准\n- `cliInput`：解析后的 CLI 输入参数\n- `host`：选定的宿主适配器实例\n\n资料来源：[src/cli.ts:120-123]()\n\n### 结果处理\n\n安装完成后，CLI 根据结果状态决定退出码：\n\n```mermaid\ngraph TD\n A[runInstaller 执行完成] --> B[printSummary 输出摘要]\n B --> C{是否有冲突?}\n B --> D{是否有错误?}\n C -->|是| E[exit 1]\n D -->|是| E\n C -->|否| F{是否有错误?}\n F -->|是| E\n F -->|否| G[正常退出 0]\n D -->|否| C\n```\n\n错误检测逻辑：\n\n```typescript\nconst hasConflicts = summary.results.some((r) => r.status === 'conflict');\nconst hasErrors = summary.results.some((r) => r.status === 'error');\n\nif (hasErrors || hasConflicts) {\n process.exit(1);\n}\n```\n\n| 退出码 | 条件 | 说明 |\n|--------|------|------|\n| 0 | 无冲突、无错误 | 安装全部成功或部分资源已存在 |\n| 1 | 存在冲突或错误 | 需用户介入解决 |\n| 2 | CLI 参数错误 | 无效参数或缺少必需参数 |\n\n资料来源：[src/cli.ts:125-132]()\n\n## 使用示例\n\n### 基本安装\n\n```bash\n# 安装 MCP 服务器\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#python/playwright'\n\n# 安装 Skill\nnpx -y agent-add --host claude-code --skill './my-skill'\n\n# 安装 Prompt（内联 Markdown）\nnpx -y agent-add --host cursor \\\n --prompt $'# Code Review Rules\\n\\nAlways review for security issues first.'\n\n# 安装 Command\nnpx -y agent-add --host cursor --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n```\n\n### 批量安装（Pack）\n\n```bash\n# 从 Pack 清单批量安装\nnpx -y agent-add --host cursor --pack 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n\n# 组合使用\nnpx -y agent-add --host cursor \\\n --pack 'https://github.com/my-team/packs.git#frontend' \\\n --mcp '{\"playwright\":{\"command\":\"npx\",\"args\":[\"@playwright/mcp\"]}}'\n```\n\n### CI 环境使用\n\n```yaml\n# .github/workflows/install-agents.yml\n- name: Install Agent Assets\n run: |\n npx -y agent-add --host cursor --pack './configs/agent-pack.json'\n```\n\nCI 环境下**必须**显式指定 `--host` 参数。\n\n## 编译与运行\n\n### 项目脚本\n\n`package.json` 中定义了以下与 CLI 相关的脚本：\n\n| 脚本 | 说明 | 源码 |\n|------|------|------|\n| `npm run build` | 使用 tsup 构建，输出 `dist/index.js`（单文件 CJS bundle） | tsup 配置 |\n| `npm run dev` | tsup watch 开发模式 | - |\n| `npm test` | 运行 vitest 单元和集成测试 | - |\n| `npm run test:contract` | 仅运行 CLI 黑盒契约测试 | - |\n\n资料来源：[package.json:20-35]()\n\n### CLI 入口点\n\n项目通过 `bin/agent-add.js` 作为 CLI 入口：\n\n```json\n{\n \"bin\": {\n \"agent-add\": \"./dist/index.js\"\n }\n}\n```\n\n`dist/index.js` 是编译后的入口文件，定义了 shebang 和模块引用。\n\n资料来源：[package.json:8-11]()\n\n### 运行时依赖\n\nCLI 运行所需的依赖：\n\n| 依赖 | 版本 | 用途 |\n|------|------|------|\n| `commander` | ^14.0.3 | 命令行参数解析 |\n| `@inquirer/select` | ^5.1.2 | 交互式宿主选择 |\n| `yaml` | ^2.8.2 | YAML 文件解析（Skill/Command/Sub-agent） |\n| `zod` | ^4.3.6 | 配置验证 |\n| `smol-toml` | ^1.6.1 | TOML 文件读写（Codex/Vibe） |\n\n资料来源：[package.json:30-45]()\n\n## 模块关系图\n\n```mermaid\ngraph TD\n subgraph \"入口层\"\n A[bin/agent-add.js] --> B[src/index.ts]\n B --> C[src/cli.ts]\n end\n \n subgraph \"宿主层\"\n C --> D[src/hosts/index.ts]\n D --> E[src/hosts/cursor.ts]\n D --> F[src/hosts/claude-code.ts]\n D --> G[src/hosts/...其他宿主]\n end\n \n subgraph \"安装层\"\n C --> H[src/installer.ts]\n H --> I[src/assets/mcp.ts]\n H --> J[src/assets/skill.ts]\n H --> K[src/assets/prompt.ts]\n H --> L[src/assets/command.ts]\n H --> M[src/assets/sub-agent.ts]\n end\n \n subgraph \"工具层\"\n H --> N[src/source/resolve-source.ts]\n H --> O[src/source/infer-name.ts]\n H --> P[src/hosts/summary.ts]\n end\n \n C --> Q[@inquirer/select 交互选择]\n H --> R[fs 文件系统操作]\n```\n\n## 错误处理\n\n### CLI 层错误\n\n| 错误类型 | 错误信息 | 退出码 | 处理方式 |\n|----------|----------|--------|----------|\n| 无资产标志 | `agent-add error: No asset flags provided...` | 2 | 添加至少一个资产安装选项 |\n| Non-TTY 未指定宿主 | `agent-add error: No host specified...` | 2 | 添加 `--host ` 参数 |\n| 无效宿主 ID | 宿主验证失败 | 2 | 使用有效宿主 ID |\n| 安装器内部错误 | `agent-add error: ` | 2 | 检查错误信息并重试 |\n\n资料来源：[src/cli.ts:90-95]()\n资料来源：[src/cli.ts:105-110]()\n\n### 安装层错误\n\n安装器核心 (`src/installer.ts`) 负责处理以下错误：\n\n- 资源解析失败\n- 资产验证失败\n- 文件系统操作失败\n- 资产类型不支持\n\n安装层错误统一通过 `process.stderr.write()` 输出并以退出码 2 终止。\n\n资料来源：[src/installer.ts:1-50]()\n\n## 最佳实践\n\n1. **CI 环境**：始终显式指定 `--host` 参数，避免交互式选择导致的阻塞\n2. **批量安装**：优先使用 `--pack` 选项，通过清单文件管理多个资源\n3. **内联内容**：对于简单配置，可使用内联 JSON/Markdown 避免额外文件\n4. **版本管理**：使用 `npm run build` 确保最新代码编译后再执行\n5. **测试验证**：修改 CLI 代码后运行 `npm test` 验证兼容性\n\n---\n\n\n\n## Pack Manifest 格式规范\n\n### 相关页面\n\n相关主题：[资产开发者指南](#p-asset-dev), [CLI 参考文档](#p-cli-ref)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/manifest/parser.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/parser.ts)\n- [src/manifest/schema.ts](https://github.com/pea3nut/agent-add/blob/main/src/manifest/schema.ts)\n- [vibe/manifest.json](https://github.com/pea3nut/agent-add/blob/main/vibe/manifest.json)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n
\n\n# Pack Manifest 格式规范\n\n## 概述\n\nPack Manifest 是一种 JSON 格式的配置文件，用于捆绑和分发多个 agent-add 资产（Asset）。开发者可以将 MCP Server、Skill、Prompt、Command、Sub-agent 等多种类型的资产打包为单个 Manifest 文件，通过 `agent-add --pack ` 命令一次性安装全部资产。\n\nManifest 文件简化了资产分发流程，尤其适合团队共享或跨项目复用。接收方只需一条命令即可完成所有资产的安装。\n\n## 核心数据结构\n\n```json\n{\n \"name\": \"namespace/pack-name\",\n \"assets\": [\n { \"type\": \"\", \"source\": \"\" }\n ]\n}\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `name` | string | 是 | 格式为 `namespace/pack-name`，命名空间与包名之间用斜杠分隔 |\n| `assets` | array | 是 | 资产数组，至少包含 1 个元素 |\n\n## name 字段规范\n\n### 格式要求\n\nManifest 的 `name` 字段必须符合 `namespace/pack-name` 格式，其中：\n\n- **命名空间（namespace）**：标识资产包的分发组织或作者\n- **包名（pack-name）**：标识具体的资产包\n\n### 字符限制\n\n`name` 字段仅允许使用以下字符：`[a-zA-Z0-9_-]`\n\n**示例：**\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [...]\n}\n```\n\n### 错误处理\n\n当 `name` 字段不符合规范时，agent-add 将输出错误信息并以退出码 2 终止：\n\n```\nagent-add error: Manifest name must match namespace/pack-name format\n```\n\n资料来源：[src/manifest/parser.ts:32-36]()\n\n## assets 数组规范\n\n### 资产类型\n\n`assets[].type` 字段定义资产类型，可选值如下：\n\n| type 值 | 说明 | 来源格式 |\n|---------|------|----------|\n| `mcp` | MCP Server 配置 | JSON 文件 |\n| `skill` | Skill 目录 | 包含 SKILL.md 的目录 |\n| `prompt` | Prompt/规则文件 | Markdown 文件 |\n| `command` | 命令文件 | Markdown 文件 |\n| `subAgent` | 子代理配置 | Markdown 文件 |\n\n### source 字段\n\n`source` 字段支持多种来源格式，agent-add 根据前缀自动识别来源类型：\n\n| 来源格式 | 类型标识 | 说明 |\n|----------|----------|------|\n| 本地目录路径 | `local-dir` | 本地文件系统目录 |\n| `https://` 开头 | `http-file` | HTTP/HTTPS URL 下载 |\n| `git@` 或 `.git` 结尾 | `git` | Git 仓库 URL |\n| `{` 开头 | `inline-json` | 内联 JSON（MCP 类型专用） |\n| 包含 `\\n` | `inline-md` | 内联 Markdown（Prompt/Command/Sub-agent 专用） |\n\n### 来源名称推断规则\n\n资产名称（asset name）根据 `source` 字段自动推断：\n\n```mermaid\ngraph TD\n A[source 输入] --> B{包含 `#` 路径锚点?}\n B -->|是| C[取 `#` 后的最后一段
移除扩展名]\n B -->|否| D{Git URL?}\n D -->|是| E[取仓库名
移除 `.git` 后缀]\n D -->|否| F[取文件名
移除扩展名]\n C --> G[推断为 asset name]\n E --> G\n F --> G\n```\n\n| 来源格式 | 推断规则 | 示例 |\n|----------|----------|------|\n| 带 `#path` | 取最后路径段，去扩展名 | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#` | 取仓库名，去 `.git` | `...playwright.git` → `playwright` |\n| 本地路径/HTTP | 取文件名，去扩展名 | `./mcps/playwright.json` → `playwright` |\n| 内联 JSON | 取顶层键名 | `{\"playwright\":{...}}` → `playwright` |\n| 内联 Markdown | 取首个 `#` 标题，转 kebab-case | `# Code Review` → `code-review` |\n\n资料来源：[src/source/infer-name.ts:1-53]()\n\n## 完整示例\n\n### 基础示例\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n### 实际使用示例\n\n以下示例来自 vibe 开发包：\n\n```json\n{\n \"name\": \"agent-add/vibe\",\n \"assets\": [\n { \"type\": \"subAgent\", \"source\": \"https://github.com/pea3nut/scenario-test.git#sub-agents/verify-host-readme\" },\n { \"type\": \"prompt\", \"source\": \"vibe/system-prompt.md\" },\n { \"type\": \"command\", \"source\": \"vibe/tasks/verify-host-readme.md\" }\n ]\n}\n```\n\n资料来源：[vibe/manifest.json]()\n\n## 安装流程\n\n### 处理流程\n\n```mermaid\ngraph TD\n A[--pack ] --> B[下载/读取 Manifest]\n B --> C[解析 JSON]\n C --> D{解析成功?}\n D -->|失败| E[输出 Zod 验证错误
exit 2]\n D -->|成功| F[遍历 assets 数组]\n F --> G[解析 source URI]\n G --> H{验证资产类型}\n H -->|无效| I[输出错误
exit 2]\n H -->|有效| J[推断 asset name]\n J --> K[分发至各资产处理器]\n```\n\n### 显式标志能力检查\n\n使用 `--pack` 安装时，Manifest 中的资产会被分发到对应的处理器。如果某些资产类型目标主机不支持，该资产会被**静默跳过**（skipped），而不是报错退出。\n\n这与显式标志（如 `--mcp`、`--skill`）的行为不同——显式标志会在主机不支持时直接报错退出。\n\n### 验证规则\n\n#### 资产类型验证\n\n不支持的 `type` 值会触发错误：\n\n```\nagent-add error: Unsupported asset type: ''. Supported: mcp, skill, prompt, command, subAgent\n```\n\n#### Skill 特殊限制\n\nSkill 类型的资产**不支持**以下来源格式：\n\n- `http-file`：HTTP/HTTPS URL\n- `inline-json`：内联 JSON\n- `inline-md`：内联 Markdown\n\nSkill 必须指向目录来源（本地路径或 Git URL）。\n\n#### MCP 特殊限制\n\nMCP 类型的资产**必须**满足以下条件：\n\n- 来源文件必须存在\n- 文件扩展名必须为 `.json`\n\n#### 缺失字段处理\n\n```typescript\nif (isTypeField) {\n // 输出不支持的类型错误\n} else if (isNameField && message.includes('namespace/pack-name')) {\n // 输出名称格式错误\n} else {\n // 输出缺失字段错误\n process.stderr.write(`agent-add error: Manifest missing required field: ${fieldPath || 'unknown'}\\n`);\n}\n```\n\n资料来源：[src/manifest/parser.ts:12-44]()\n\n## 字段验证规范\n\n### Zod Schema 验证\n\nManifest 使用 Zod 进行运行时验证，关键规则包括：\n\n| 规则 | 字段 | 错误信息 |\n|------|------|----------|\n| 必填 | `name` | Manifest missing required field: name |\n| 格式 | `name` | Manifest name must match namespace/pack-name format |\n| 必填 | `assets` | Manifest missing required field: assets |\n| 非空 | `assets` | 至少包含 1 个元素 |\n| 必填 | `assets[].type` | Manifest missing required field: assets[].type |\n| 枚举 | `assets[].type` | Unsupported asset type: '' |\n| 必填 | `assets[].source` | Manifest missing required field: assets[].source |\n\n### 错误信息输出格式\n\n所有错误均输出至 `stderr`，格式为：\n\n```\nagent-add error: <具体错误描述>\n <额外信息或修复建议>\n```\n\n## 与 CLI 参数的对比\n\n| 特性 | `--pack` | 显式标志 |\n|------|----------|----------|\n| 安装多个同类型资产 | ✓ | ✓ (多次使用) |\n| 组合不同类型资产 | ✓ | ✓ |\n| 不支持的资产处理 | 静默跳过 | 报错退出 (exit 2) |\n| 来源格式 | 仅目录/URL | 支持内联内容 |\n\n## 最佳实践\n\n1. **命名规范**：使用有意义的 `namespace`（如团队名、作者名），使包名具有描述性\n2. **来源可靠性**：优先使用稳定的 Git URL，避免直接引用可能失效的 HTTP URL\n3. **版本锁定**：Git 来源可使用 `#ref` 语法锁定特定版本或 commit\n4. **资产组织**：相关资产放在同一 Manifest 中，减少分发复杂度\n\n## 参考资料\n\n- [Manifest 解析器实现](src/manifest/parser.ts)\n- [Manifest Schema 定义](src/manifest/schema.ts)\n- [名称推断逻辑](src/source/infer-name.ts)\n- [安装器核心逻辑](src/installer.ts)\n- [vibe 开发包示例](vibe/manifest.json)\n\n---\n\n\n\n## 资产开发者指南\n\n### 相关页面\n\n相关主题：[Pack Manifest 格式规范](#p-pack-manifest), [源格式与名称推断](#p-source-formats)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/source/infer-name.ts](https://github.com/pea3nut/agent-add/blob/main/src/source/infer-name.ts)\n- [src/installer.ts](https://github.com/pea3nut/agent-add/blob/main/src/installer.ts)\n- [src/hosts/types.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/types.ts)\n- [src/hosts/codex.ts](https://github.com/pea3nut/agent-add/blob/main/src/hosts/codex.ts)\n- [src/cli.ts](https://github.com/pea3nut/agent-add/blob/main/src/cli.ts)\n- [README.md](https://github.com/pea3nut/agent-add/blob/main/README.md)\n
\n\n# 资产开发者指南\n\n## 概述\n\n资产开发者指南是 agent-add 项目为第三方开发者提供的**文件格式规范文档**。该指南定义了 agent-add 所支持的五种资产类型的结构要求、命名规则和格式约束，使开发者能够创建可被 agent-add 正确安装和分发的 MCP 服务器、Skill、Prompt、Command 和 Sub-agent 资产。\n\nagent-add 作为跨主机的 AI 工具资产安装器，支持 18 种主流 AI 编程工具（包括 Cursor、Claude Code、Codex 等），资产开发者通过遵循本指南创建的资产，可实现一次编写、多端复用的分发目标。资料来源：[README.md:98-115]()\n\n## 资产类型概述\n\nagent-add 支持的资产类型及其核心特征如下：\n\n| 资产类型 | 用途 | 安装目标 | 写入策略 |\n|---------|------|---------|---------|\n| MCP | Model Context Protocol 服务器配置 | 主机 MCP 配置文件 | JSON 浅合并或 TOML 注入 |\n| Skill | 可复用的 Agent 技能包 | 技能目录 | 目录递归复制 |\n| Prompt | 规则文件/系统提示词 | AGENTS.md 或规则目录 | HTML 标记追加或独立文件 |\n| Command | 斜杠命令定义 | commands 目录 | 独立文件写入 |\n| Sub-agent | 子代理配置 | agents 目录 | TOML 文件写入 |\n\n## MCP 配置文件规范\n\n### 支持的 JSON 格式\n\nMCP 资产支持两种 JSON 格式，agent-add 会自动检测并解析：\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"],\n \"env\": {}\n}\n```\n\n格式 A 为**内层配置（单服务器）**，资产名称从文件名推断：`playwright.json` → 名称为 `playwright`。资料来源：[README.md:105-113]()\n\n```json\n{\n \"mcpServers\": {\n \"playwright\": {\n \"command\": \"npx\",\n \"args\": [\"@playwright/mcp@latest\"]\n }\n }\n}\n```\n\n格式 B 为**完整配置包装**，agent-add 自动解包 `mcpServers` 并提取内部服务器名称和配置。资料来源：[README.md:115-120]()\n\n### TOML 配置支持\n\nCodex 和 Vibe 等主机使用 TOML 格式存储 MCP 配置。agent-add 在检测到 `.toml` 扩展名时自动调度到 smol-toml 处理路径。资料来源：[vibe/system-prompt.md:17]()\n\n### 名称推断规则\n\n资产名称推断遵循以下优先级规则：\n\n| 场景 | 推断逻辑 | 示例 |\n|------|---------|------|\n| 源包含 `#path` | 取路径最后段（去除扩展名） | `...git#skills/pdf` → `pdf` |\n| Git URL 无 `#path` | 取仓库名（去除 `.git` 后缀） | `...playwright.git` → `playwright` |\n| 本地路径/HTTP URL | 取文件名（去除扩展名） | `./mcps/playwright.json` → `playwright` |\n\n资料来源：[src/source/infer-name.ts:1-40]()\n\n### 验证规则\n\nMCP 资产在安装前必须通过以下验证：\n\n1. **文件存在性检查**：MCP 来源文件必须存在于本地路径\n2. **扩展名验证**：文件扩展名必须为 `.json`\n3. **来源类型限制**：`http-file`、`inline-json`、`inline-md` 类型的来源不允许安装为 Skill 类型资产，但 MCP 允许 `inline-json`（格式为 `{\"name\":{...}}`，key 为资产名称）资料来源：[src/installer.ts:78-85]()\n\n## Skill 资产规范\n\n### 目录结构要求\n\nSkill 必须是一个完整的目录，目录内**必须包含** `SKILL.md` 文件作为入口点：\n\n```\nmy-skill/\n├── SKILL.md # 必需：技能元数据和描述\n├── helpers/\n│ └── utils.py # 可选：辅助脚本\n└── templates/\n └── report.md # 可选：模板文件\n```\n\n```markdown\n\n---\nname: my-skill\ndescription: A reusable agent skill.\n---\n\n# Skill: my-skill\n\nThis skill does something useful.\n```\n\n整个目录会被递归复制到主机的技能目录（如 `.cursor/skills/my-skill/`）。资料来源：[README.md:85-96]()\n\n### 验证规则\n\nSkill 资产具有最严格的来源限制：\n\n```typescript\nif (assetType === 'skill') {\n if (resolved.type === 'http-file' || resolved.type === 'inline-json' || resolved.type === 'inline-md') {\n return 'Skill 资产必须指向目录来源（本地路径或 Git URL），不支持内联内容或直接 HTTP(S) URL';\n }\n const skillMdPath = path.join(resolved.localPath, 'SKILL.md');\n try {\n await fs.promises.access(skillMdPath);\n } catch {\n return `Skill 目录内缺少 SKILL.md 文件（期望路径：${skillMdPath}）`;\n }\n}\n```\n\nSkill 资产**必须**使用目录来源（本地路径或 Git URL），不支持内联内容或直接的 HTTP(S) URL 下载。资料来源：[src/installer.ts:56-65]()\n\n### 主机适配差异\n\n不同主机的 Skill 安装路径和策略不同：\n\n```typescript\nskill: {\n supported: true,\n installDir: '.codex/skills/',\n entryFile: 'SKILL.md',\n writeStrategy: 'copy-file',\n}\n```\n\nCodex 适配器将 Skill 安装到 `.codex/skills/` 目录，使用 `copy-file` 写入策略。资料来源：[src/hosts/codex.ts:28-31]()\n\n## Prompt 资产规范\n\n### 格式要求\n\nPrompt 是纯 Markdown 文件，无特殊格式要求：\n\n```markdown\n# Code Review Rules\n\nAlways review for security issues first.\nUse bullet points for lists.\n```\n\nagent-add 自动根据主机选择写入策略。资料来源：[README.md:98-103]()\n\n### 写入策略\n\n#### 追加模式\n\nCursor、Claude Code 等主机使用追加模式，Content 被包装在 HTML 注释标记中并追加到文件，确保幂等性：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n#### 独立文件模式\n\nWindsurf、Roo Code 等主机使用独立文件模式，在规则目录中创建 `.md` 文件：\n\n```typescript\nprompt: {\n supported: true,\n targetFile: 'AGENTS.md',\n writeStrategy: 'append-with-marker',\n}\n```\n\n资料来源：[src/hosts/codex.ts:22-25]()\n\n## Command 资产规范\n\n### 格式要求\n\nCommand 文件支持可选的 YAML frontmatter：\n\n```markdown\n---\ndescription: Run a comprehensive code review.\n---\n\n# code-review\n\nReview the current file for bugs, security issues, and style violations.\n```\n\n安装到主机的 commands 目录（如 `.cursor/commands/code-review.md`）。资料来源：[README.md:133-139]()\n\n## Sub-agent 资产规范\n\n### 格式要求\n\nSub-agent 文件使用 Markdown + YAML frontmatter 格式，支持 **`agent-add//` 主机特化语法**——单个文件可为不同主机提供不同的 frontmatter 字段值。资料来源：[README.md:141-154]()\n\n### 主机特化示例\n\n```markdown\n---\nname: playwright-tester\ndescription: A playwright testing agent.\nagent-add/cursor/model: fast\nagent-get/claude-code/model: haiku\n---\n\n# Playwright Test Agent\n\nPlan and generate Playwright tests.\n```\n\n安装过程中 agent-add 会：\n1. **提升**匹配的 `agent-add//*` 值为顶层键\n2. **移除**所有 `agent-add/*` 前缀的键\n\n资料来源：[README.md:154-163]()\n\n## Pack 清单规范\n\n### 文件格式\n\nPack 是一个 JSON 文件，捆绑多个资产用于分发：\n\n```json\n{\n \"name\": \"my-team/frontend-pack\",\n \"assets\": [\n { \"type\": \"mcp\", \"source\": \"https://github.com/modelcontextprotocol/servers.git#.mcp.json\" },\n { \"type\": \"skill\", \"source\": \"https://github.com/anthropics/skills.git#skills/pdf\" },\n { \"type\": \"prompt\", \"source\": \"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules\" },\n { \"type\": \"command\", \"source\": \"https://github.com/wshobson/commands.git#tools/security-scan.md\" },\n { \"type\": \"subAgent\", \"source\": \"https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md\" }\n ]\n}\n```\n\n### 字段规范\n\n| 字段 | 必填 | 描述 |\n|------|------|------|\n| `name` | 是 | 格式 `namespace/pack-name`，仅允许 `[a-zA-Z0-9_-]` |\n| `assets` | 是 | 至少 1 个元素 |\n| `assets[].type` | 是 | `mcp` \\| `skill` \\| `prompt` \\| `command` \\| `subAgent` |\n| `assets[].source` | 是 | 来源路径、URL 或内联内容 |\n\n### CLI 安装方式\n\n```bash\nnpx -y agent-add --host cursor --pack 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n```\n\n多个 pack 可以与显式标志自由组合使用：\n\n```bash\nnpx -y agent-add --host cursor \\\n --pack './my-pack.json' \\\n --mcp './mcps/playwright.json'\n```\n\n资料来源：[src/cli.ts:22-33]()\n\n## 来源解析架构\n\n### 解析流程\n\n```mermaid\ngraph TD\n A[CLI 输入] --> B[显式标志能力检查]\n B --> C[AssetDescriptor 数组]\n C --> D[源解析器]\n D --> E[ResolvedSource 数组]\n E --> F[验证]\n F --> G[InstallJob 数组]\n G --> H[安装处理]\n H --> I[InstallResult 数组]\n I --> J[摘要输出]\n```\n\n### 解析类型判定\n\n| 源格式 | 检测规则 | 解析类型 |\n|--------|---------|---------|\n| 以 `{` 开头 | JSON 解析 | `inline-json` |\n| 包含 `\\n` | 非 JSON | `inline-md` |\n| Git URL 含 `#path` | 路径提取 | `git-file` 或 `git-dir` |\n| 本地路径 | 文件系统访问 | `local-file` 或 `local-dir` |\n| HTTP(S) URL | 网络请求 | `http-file` |\n\n`inline-json` 仅适用于 MCP 资产，`inline-md` 仅适用于 Prompt/Command/Sub-agent。资料来源：[vibe/system-prompt.md:22-24]()\n\n## 关键设计决策\n\n### 原子 JSON 写入\n\nMCP 配置使用临时文件 + 重命名的策略确保写入安全：\n\n```typescript\n// mcp.ts 使用 temp file + rename\nawait fs.promises.writeFile(tempPath, JSON.stringify(config, null, 2));\nawait fs.promises.rename(tempPath, configFile);\n```\n\n资料来源：[vibe/system-prompt.md:18]()\n\n### 标记块幂等追加\n\nPrompt 的 `append-with-marker` 策略使用 `` HTML 注释确保幂等性：\n\n```html\n\n# Code Review Rules\n...\n\n```\n\n重复安装不会导致内容重复追加。资料来源：[vibe/system-prompt.md:19]()\n\n### 显式标志拒绝\n\n`installer.ts` 在构建任务前检查显式标志能力声明。`supported: false` 会输出错误信息和 README 链接并以退出码 2 终止。`--pack` 来源不受此检查约束。资料来源：[vibe/system-prompt.md:21]()\n\n### 非 TTY 严格模式\n\nCI 环境必须显式指定 `--host`，否则以退出码 2 终止。这确保自动化环境中不会误用默认主机。资料来源：[vibe/system-prompt.md:23]()\n\n## 主机能力矩阵\n\n添加新主机适配器时，必须遵循以下贡献流程：\n\n1. **创建适配器文件**：`src/hosts/.ts`\n - 导出实现 `HostAdapter` 接口的类\n - 硬编码所有配置字段\n - 对不支持的资产类型使用 `NOT_SUPPORTED(reason)` 辅助函数\n\n2. **注册到 index.ts**：将 `['', new XxxAdapter()]` 添加到 `src/hosts/index.ts` 的 `hostRegistry` Map\n\n3. **更新 README**：在能力矩阵表中添加行，并在详情区添加新主机段\n\n4. **添加单元测试**：创建 `tests/unit/hosts/.test.ts`，验证每个字段值与 README 完全一致\n\n```typescript\nexport class CodexAdapter implements HostAdapter {\n readonly id = 'codex';\n readonly displayName = 'Codex CLI';\n readonly docs = 'https://github.com/openai/codex';\n readonly detection = { paths: ['~/.codex/'] };\n readonly assets: Record = {\n mcp: {\n supported: true,\n configFile: { darwin: '~/.codex/config.toml', ... },\n configKey: 'mcp_servers',\n writeStrategy: 'inject-json-key',\n },\n // ...\n };\n}\n```\n\n资料来源：[src/hosts/codex.ts:1-45](), [src/hosts/README.md:350-365]()\n\n## 快速参考\n\n### 常用安装命令\n\n```bash\n# MCP 服务器\nnpx -y agent-add --host cursor --mcp 'https://github.com/modelcontextprotocol/servers.git#.mcp.json'\n\n# Skill 目录\nnpx -y agent-add --host cursor --skill 'https://github.com/anthropics/skills.git#skills/webapp-testing'\n\n# Prompt 规则\nnpx -y agent-add --host claude-code --prompt 'https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/nextjs-react-tailwind/.cursorrules'\n\n# 斜杠命令\nnpx -y agent-add --host cursor --command 'https://github.com/wshobson/commands.git#tools/security-scan.md'\n\n# 子代理\nnpx -y agent-add --host cursor --sub-agent 'https://github.com/VoltAgent/awesome-claude-code-subagents.git#categories/01-core-development/backend-developer.md'\n```\n\n### 退出码规范\n\n| 退出码 | 含义 |\n|-------|------|\n| 0 | 安装成功，无冲突 |\n| 1 | 存在冲突或错误 |\n| 2 | 参数错误或不支持的资产类型 |\n\n资料来源：[src/cli.ts:41-46]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：pea3nut/agent-add\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...。\n\n## 1. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：pea3nut/agent-add\n\n摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...。\n\n## 1. 安装坑 · 社区讨论暴露的待验证问题：I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：I built a CLI that installs MCP, skills, prompts, commands and sub ... 6 Apr 2026 · Project & Supported Tools. The source code is hosted on GitHub: https://github.com/pea3nut/agent-add ... r/mcp - I built a tool that auto- ...\n- 对用户的影响：这类外部讨论可能代表真实用户在安装、配置、升级或生产使用时遇到阻力；发布前不能只依赖官方 README。\n- 建议检查：Pack Agent 需要打开来源链接，确认问题是否仍然存在，并把验证结论写入说明书和边界卡。\n- 证据：social_signal:reddit | ssig_6d54ef81557a451081be71b052d0e31b | https://www.reddit.com/r/ClaudeAI/comments/1sdrk6k/i_built_a_cli_that_installs_mcp_skills_prompts/ | I built a CLI that installs MCP, skills, prompts, commands and sub ...\n\n## 2. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | no_demo; severity=medium\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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | 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 | art_7871f43a97e049c0ba0df6fa5a5b6e88 | https://github.com/pea3nut/agent-add#readme | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# agent-add - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-add 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code / Cursor\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- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p-home：项目首页。围绕“项目首页”模拟一次用户任务，不展示安装或运行结果。\n2. p-installation：安装与快速开始。围绕“安装与快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. p-usage：核心功能使用指南。围绕“核心功能使用指南”模拟一次用户任务，不展示安装或运行结果。\n4. p-arch：系统架构总览。围绕“系统架构总览”模拟一次用户任务，不展示安装或运行结果。\n5. p-host-system：Host 适配器系统。围绕“Host 适配器系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p-home\n输入：用户提供的“项目首页”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p-installation\n输入：用户提供的“安装与快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p-usage\n输入：用户提供的“核心功能使用指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p-arch\n输入：用户提供的“系统架构总览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p-host-system\n输入：用户提供的“Host 适配器系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p-home：Step 1 必须围绕“项目首页”形成一个小中间产物，并等待用户确认。\n- Step 2 / p-installation：Step 2 必须围绕“安装与快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / p-usage：Step 3 必须围绕“核心功能使用指南”形成一个小中间产物，并等待用户确认。\n- Step 4 / p-arch：Step 4 必须围绕“系统架构总览”形成一个小中间产物，并等待用户确认。\n- Step 5 / p-host-system：Step 5 必须围绕“Host 适配器系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/pea3nut/agent-add#readme\n- tests/fixtures/skill/my-skill/SKILL.md\n- README.md\n- package.json\n- bin/agent-add.js\n- src/cli.ts\n- src/installer.ts\n- src/hosts/index.ts\n- src/manifest/parser.ts\n- src/index.ts\n- tsup.config.ts\n- src/hosts/types.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-add 的核心服务。\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", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：pea3nut/agent-add\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx -y agent-add\n```\n\n来源：https://github.com/pea3nut/agent-add#readme\n\n## 来源\n\n- docs: https://github.com/pea3nut/agent-add#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_3e340640c8434f42816f732f71099d5f" }