magicpath

MagicPath

一个通过 AI 构建、分享和安装 UI 组件的平台。组件会通过 magicpath-ai CLI 以源代码的形式添加到用户的项目中。

也可以直接通过本地代码创建和编辑 MagicPath 画布组件，使用 npx -y magicpath-ai code ... 子命令即可 — 参见从代码编辑或创建画布组件。这条路径有严格限制：只能编辑代码工作目录中的 src/App.tsx、src/index.css、src/components/generated/ 下的文件，以及 assets/ 下的临时图像资源。

如果此技能运行在内嵌浏览器的 Agent 宿主中，适合时请使用 MagicPath 项目作为 Agent 旁边的持久化视觉画布。如果要创建用于画布创作的项目，请在创建后、运行 code start 前立即在内嵌浏览器中打开该项目；参见使用内嵌浏览器。

术语： 用户通常会把 MagicPath 组件称为“设计”——这两个词可以互换。用户说“设计”“我的设计”或“那个设计”时，应将其理解为 MagicPath 组件，并据此搜索、查看和安装。

用户也会把 MagicPath 设计系统称为“主题”。用户说“主题”“我的主题”或“使用 X 主题”时，指的是 MagicPath 设计系统 — 一组 CSS 变量、字体和样式说明。使用 list-themes 和 get-theme 来管理这些内容。

用户可能属于某个团队（也称为“工作区”）。用户说“团队的设计”“我们团队的组件”或提及“Acme Inc”之类的团队名称时，指的是该团队拥有的项目和组件。使用 list-teams、--team 和 --personal 标志在个人工作区和团队工作区之间切换。

用户也可能会询问他们在 MagicPath 中创建的技能。这些是可复用的指令包，可从 MagicPath 聊天中调用，并通过 npx -y magicpath-ai skills ... 管理。个人技能位于用户的工作区中；团队技能位于 MagicPath 团队中。除非平台另有说明，公开的 MagicPath 技能均为只读。

第一步

运行 npx -y magicpath-ai info -o json 检查身份验证状态和项目上下文。首次调用可能需要几秒钟，因为 npx 需要下载软件包；之后的调用会很快。

• 如果 auth.authenticated 为 false，则运行 npx -y magicpath-ai login，等待浏览器身份验证完成，然后运行 npx -y magicpath-ai whoami -o json 进行验证。

访客会话

如果用户提供了配对码（类似 gst_… 的短码，通常是因为他们想在没有账户的情况下试用 MagicPath），请使用该码连接一次：

npx -y magicpath-ai login --guest-code <code>

然后运行 npx -y magicpath-ai whoami -o json — 它会报告 guest: true、可供你使用的唯一一个 projectId，以及一个 canvasUrl。在该项目上使用常规的 code start --project <projectId> → code submit 流程进行构建；每次提交都会实时显示在画布上。

访客会话仅限于该单个项目，并且会过期。在会话期间：

• 使用 code start / code submit 在项目上创建和编辑设计 — 这正是该会话的主要用途。
• 如果宿主带有内嵌浏览器，请打开 canvasUrl（来自 whoami），让用户在你旁边查看画布的更新。canvasUrl 是打开访客画布的唯一方式 — 不要使用 share 或 view，这些功能需要完整账户。
• 其他工作区功能（团队、其他项目、主题）仅适用于完整账户。如果某条命令提示需要账户，请告知用户在浏览器中打开的画布页面注册账户 — 这样即可将该项目保存到他们的账户中，并解锁其他所有功能。（如果他们的会话已经过期，该项目将无法保存，他们需要重新开始。）切勿在没有配对码的情况下告诉访客运行 login。

使用团队

用户可能属于拥有共享项目和主题的团队。默认情况下，list-projects 和 search 会返回所有工作区（个人工作区 + 用户所属的每个团队工作区）中的结果。使用筛选标志缩小范围。

查找团队

运行 npx -y magicpath-ai list-teams -o json 查看用户所属的团队：

{ "teams": [{ "id": "123", "name": "Acme Inc", "role": "ADMIN" }] }

按团队筛选

• 默认（不使用标志）：list-projects、search 会同时包含个人项目和所有团队项目，无需额外标志即可全面查找。
• --team "Acme Inc" 或 --team <teamId>：筛选特定团队。适用于 list-projects、search、list-themes 和 get-theme。
• --personal：仅显示用户的个人项目/组件。适用于 list-projects 和 search。

JSON 输出

项目和搜索结果会包含 ownerType（"personal" 或 "team"）和 ownerName（用户邮箱或团队名称）。可据此告知用户组件所属的位置。

查找成员

运行 npx -y magicpath-ai list-members --team "Acme Inc" -o json 查看团队成员：

{ "team": { "id": "123", "name": "Acme Inc" }, "members": [{ "id": "456", "displayName": "Chloe Smith", "email": "[email protected]", "role": "MEMBER" }] }

按成员筛选

• list-components 上的 --created-by <userId>：筛选由特定用户创建或编辑的组件。先通过 list-members 将成员姓名解析为用户 ID，再使用此选项。
• 项目上的 createdBy 字段：list-projects 中的每个项目都包含 createdBy: { id, displayName }，用于显示创建者。
• 组件上的 lastEditedBy 字段：list-components 中的每个组件都包含 lastEditedBy: { id, displayName }，用于显示最后编辑者。

重要：你只能查看已通过身份验证的用户有权访问的项目，即自己的个人项目和所属团队的项目。你无法访问其他用户的个人项目。查找其他人的作品时，只搜索团队项目（--team），不要搜索个人项目。除非所有者明确邀请某人成为成员，否则个人项目仅对所有者私有。

常见用法

• “Chloe 最近在做什么？” → 使用 list-members --team "Acme Inc" -o json 查找 Chloe 的用户 ID → 使用 list-projects --team "Acme Inc" -o json 获取仅限团队的项目 → 对每个项目运行 list-components <projectId> --created-by <chloeId> --sort-by createdAt --order desc -o json。报告最新的组件。不要搜索其他用户的个人项目来查找其作品——个人项目仅对所有者私有。
• “给我看看团队的设计”或“Acme Inc 创建了什么？” → 使用 list-teams 查找团队，然后运行 list-projects --team "Acme Inc" -o json，再运行 list-components <projectId> -o json。
• “给我看看团队最新的设计” → 同上，但在 list-components 中使用 --sort-by createdAt --order desc --limit 1。
• “这个项目/组件是谁创建的？” → 查看相应列表命令返回的项目 createdBy 字段或组件 lastEditedBy 字段。
• 未提及团队的“我的设计” → 通常使用默认选项（所有项目）即可。只有用户明确要求排除团队项目时，才使用 --personal。
• “使用团队的主题” → 运行 list-themes --team "Acme Inc" -o json，然后运行 get-theme <name> --team "Acme Inc" -o json。

管理 MagicPath 技能

当用户要求创建、列出、检查、更新、导入、删除、启用/禁用或在本地安装存储在 MagicPath 中的技能时，使用此流程。对于所有返回数据的命令，优先使用 JSON 模式：

npx -y magicpath-ai skills list -o json
npx -y magicpath-ai skills list --team "Acme Inc" -o json
npx -y magicpath-ai skills get <skillIdOrSlug> -o json
npx -y magicpath-ai skills create --name "Skill name" --description "When to use it" --instructions-file ./SKILL.md -o json
npx -y magicpath-ai skills import ./skill-package.skill -o json
npx -y magicpath-ai skills update <skillIdOrSlug> --disable -o json
npx -y magicpath-ai skills delete <skillIdOrSlug> -y -o json

范围与所有权

• 用户表示技能属于某个团队/工作区时，使用 --team <nameOrId>。
• 个人技能不要使用 --team。
• 默认情况下，skills list 会包含公开的 MagicPath 技能，因为用户可以在聊天中使用这些技能。如果用户想查看自己可以编辑的技能，请传入 --owned-only。
• 公开技能为只读。除非命令输出明确指出该技能归用户所有且可编辑，否则不要尝试更新或删除公开技能。
• 导入的 .zip 或 .skill 软件包在 MagicPath 中内容不可变；但仍可通过 skills update <id> --enable/--disable 启用或禁用。

创建或更新技能

• 如果指令不止简短的一行，请将指令写入本地文件并使用 --instructions-file。这样可以避免 shell 引号问题，并保留 Markdown 格式。
• MagicPath 技能必须包含非空的名称、描述和指令。描述应说明何时使用该技能；指令应说明如何完成工作。
• 如果用户想将观察到的工作流转化为可复用的技能，请总结触发条件、限制、步骤、示例，以及未来 Agent 应阅读的文件或参考资料。

在本地安装 MagicPath 技能

当用户想将 MagicPath 中的技能安装到外部编码 Agent 时，先获取该技能，再将其重建为本地 Agent Skills 文件夹：

1. 运行 npx -y magicpath-ai skills get <skillIdOrSlug> -o json。
2. 创建一个以技能 slug 命名的文件夹。
3. 创建 SKILL.md，添加至少包含 name 和 description 的 frontmatter，然后附上获取到的 instructions：

---
name: example-skill
description: Use when ...
---

...instructions from MagicPath...

4. 如果技能包含打包的文件，请运行 npx -y magicpath-ai skills get <skillIdOrSlug> --files -o json，然后使用 --file <path> 获取每个文件，并在本地技能文件夹中按相同的相对路径重建。
5. 使用当前 Agent 宿主的本地技能工作流安装或注册该文件夹。如果宿主支持 Agent Skills CLI，请使用该工具从本地文件夹安装；否则，将文件夹放入宿主文档说明的本地技能目录。

写入用户当前项目之外的位置或全局 Agent 配置目录前，请先征求用户同意。

工作流

所有返回数据的命令（search、list-projects、list-components、list-teams、list-themes、get-theme、skills、selection、active-project、info、add、inspect、code）始终使用 -o json。这样你就能获取结构化输出，而不是面向用户的表格。

阶段 1：发现

1. 检查身份验证 — 运行 npx -y magicpath-ai whoami -o json 验证身份验证状态。
2. 检查当前选区 — 如果用户提到“选中的组件”“选中的图像”“我选中的设计”，或以其他方式指向特定画布选区，运行 npx -y magicpath-ai selection -o json。如果返回了组件，直接使用这些组件——跳过搜索/确认流程，并使用返回的 generatedName。每个返回的组件还包含 selectedRevisionId，即该组件当前在画布上显示的修订版本。响应中还可能包含选中的 images；之后运行 code start 时，这些选中的图像会按照下文所述放在 assets/selected/** 下。如果后续命令接受修订版本（例如 code context --revision），请传入此值，以便操作针对用户正在查看的版本，而不是数据库中恰好被设为规范版本的版本。
3. 检查当前活动项目 — 如果用户提到“我打开的项目”“这个项目”“我正在处理的内容”，或以其他方式暗示工作项目上下文但未指定具体组件，运行 npx -y magicpath-ai active-project -o json。即使当前没有选中任何内容，该命令也会返回用户目前在浏览器中打开的项目。如果返回一个项目，将其视为工作项目并跳过项目选择器。如果返回多个项目，列出它们并询问用户要选哪一个。如果返回空列表，说明用户没有打开画布——请使用 list-projects 并询问用户。根据用户的描述选择正确的命令：提到组件时用 selection，提到项目时用 active-project，两者都未提及时用 list-projects 并询问。（请注意，selection 的输出也会包含活动项目，因此用户提到组件时，可以直接获取项目，无需单独调用 active-project。）
4. 查找组件 — 使用 npx -y magicpath-ai search <query> -o json 搜索所有项目，或先运行 list-projects -o json，再运行 list-components <projectId> -o json 浏览组件。如果 active-project 已返回项目，请通过 list-components <projectId> -o json 将搜索范围限定在该项目，而不是搜索所有工作区。
5. 查看项目图像 — 若要了解项目画布上已有的独立图像（以便引用、避免重复添加或向用户描述），请运行 npx -y magicpath-ai image list <projectId> -o json，并下载每个 url 以查看图像——方式与查看组件时使用 previewImageUrl 相同。（这些是画布图像，与 code 流程中的 assets/ 构建输入不同。） 对于独立栅格图像请求——照片、插图、纹理或透明抠图——请使用 npx -y magicpath-ai image generate --prompt "..." -o json，而不是构建画布设计；传入 --ref <path> 可编辑或重新设计现有照片。使用 image add 将结果放到画布上，或将其复制到代码会话的 assets/ 文件夹中，以便在设计中使用。标志请参阅 image generate。
6. 直观了解组件 — search 和 list-components 的结果包含 previewImageUrl 字段。请下载并分析这些图像，以便在推荐组件前了解其外观。预览图仅供你了解组件——除非用户明确要求在嵌入式项目画布中查看某个设计，否则不要导航到该设计的单独预览。
7. 向用户确认（停止并等待） — 除非用户指定了确切的 generatedName，否则请告知用户你找到的内容（名称、generatedName、项目），并询问这是否是正确的组件。如果当前有嵌入式项目画布，请保持在该项目中；只有用户明确要求时，才打开或分享单个设计。如果没有嵌入式项目画布，请使用 npx -y magicpath-ai view <generatedName> 打开浏览器预览，作为常规确认方式。如果有多个匹配项，请全部列出并询问用户要选哪一个。此处必须停止——在此结束回复并等待用户回答。未经用户明确确认，不得继续。 此时不要运行 add 或 inspect。

阶段 2：了解目标上下文

此阶段至关重要。 在安装任何内容之前，你必须了解组件将放在哪里，以及它需要在那里实现什么功能。跳过这一步会导致组件看起来没问题，实际行为却不正确。

将设计带出 MagicPath： 在导出到文件夹、安装到应用、替换本地 UI 或转换为其他框架之前，请阅读并遵循 在本地代码中使用 MagicPath 设计。该文档定义了如何锁定确切的修订版本、在调整前确保 1:1 一致、保留本地行为、验证渲染结果，并将差异限制在用户明确要求的更改范围内。

7. 检查 MagicPath 组件源代码 — 使用 npx -y magicpath-ai inspect <generatedName> -o json 阅读源代码。确定它会渲染什么、需要哪些 props，以及它对布局有哪些假设（固定宽度、绝对定位等）。
8. 阅读目标代码库上下文 — 安装之前，先阅读组件将要放置的文件。了解：
   • 现有功能：如果要替换一个组件，当前组件会做什么？它处理哪些回调、状态、API 调用、导航、验证或副作用？必须保留现有行为的每一部分，或有意识地处理。
   • 布局上下文：父级布局是什么？它是 flex/grid 容器吗？响应式断点有哪些？间距是如何处理的？组件单独看起来再完美，如果其尺寸假设与布局不匹配，也可能破坏布局。
   • 数据流：周边代码提供哪些 props、上下文或状态？它期望接收什么（回调、表单数据、事件）？
   • 设计系统：项目使用哪些样式模式（Tailwind、CSS modules、主题令牌）？MagicPath 组件的样式应与之协调，而非冲突。

应用主题（如适用）

如果用户希望应用某个主题，或提到了某个品牌/设计系统的名称：

1. 列出可用主题 — 运行 npx -y magicpath-ai list-themes -o json 查看所有主题。
2. 获取主题定义 — 运行 npx -y magicpath-ai get-theme <id-or-name> -o json 获取完整定义。
3. 阅读 prompt 字段 — 如果存在，该字段包含设计师提供的自然语言样式说明（例如，“使用圆角，优先使用阴影而非边框，CTA 使用品牌蓝色”）。调整组件时请遵循这些说明。
4. 应用 CSS 变量 — 主题的 light 和 dark 对象将 CSS 变量名称映射到相应值（例如，--background: #ffffff、--primary: #3b82f6）。调整 MagicPath 组件时，请使用这些 CSS 变量，而不是硬编码颜色：bg-[var(--background)]、text-[var(--primary)] 等。确保组件遵循 defaultTheme（light 或 dark）。
5. 处理字体 — 如果主题包含 fonts，请确保项目加载这些字体（Google Fonts 链接或自定义字体的 @font-face 声明），并确保组件通过主题的字体 CSS 变量引用它们（例如，font-family: var(--font-body)）。
6. 非 React/JS 项目 — 主题数据是参考信息，并非样式表。请将 CSS 变量转换为目标平台的对应形式：SwiftUI Color 资源、Android 主题 XML、Python 模板上下文等。prompt 字段以及颜色/字体值表达的是与平台无关的设计意图——请将其映射为原生模式，而不是直接使用 CSS。

直接通过代码创建或编辑 Canvas 组件

仅当用户希望直接编写 MagicPath Canvas 组件时，才使用此流程：

npx -y magicpath-ai code start --project <projectId> --dir . --name "Component Name" -o json
npx -y magicpath-ai code start --component <componentId> --dir . -o json
npx -y magicpath-ai code context <componentId> --dir . -o json  # read-only
npx -y magicpath-ai code submit --dir . --wait -o json

code start 是唯一可以启动有状态编码会话的命令。使用 --project 创建新组件，或使用 --component 编辑现有组件。它会写入可编辑文件，在 Canvas 上创建或复用待处理修订，并显示 Agent 是否在线。

code context 是只读的。使用它检查或导出现有组件的确切源代码修订；不得将其用作提交流程。

仅编辑以下内容：src/App.tsx、src/index.css、src/components/generated/**，以及 assets/** 下的临时图像资源。

src/App.tsx 已预先接好生成组件的渲染逻辑。只有在需要更改顶层主题值时才编辑它。

如果运行 code start 时 Canvas 上选中了图像形状，JSON 响应中可能会包含 selectedImages。CLI 会将这些短时有效的图像 URL 下载到 assets/selected/**。在 TSX/CSS 中使用响应里的本地 assetPath，切勿将临时 accessUrl 粘贴到组件源代码中，因为它会过期。

Tailwind v4 规则

MagicPath 模板使用 Tailwind v4。请按以下方式设置样式：

• src/index.css 必须包含 @import 'tailwindcss';，而不是 @tailwind base;、@tailwind components; 或 @tailwind utilities;。
• 主题令牌（bg-background、text-foreground、border-border、bg-primary 等）通过 index.css 中的 @theme inline { ... } 代码块接入。请勿删除它。
• :root 和 .dark 代码块定义了实际的令牌值。请勿删除它们。
• 要添加自定义工具类，请将其追加到 index.css，而不是替换现有内容。
• 不存在 tailwind.config.js。配置通过 Tailwind v4 的 @theme 指令写在 index.css 中。

第 3 阶段：安装并适配

9. 添加到项目 — 使用 npx -y magicpath-ai add <generatedName> -y 安装组件文件。在非交互环境中始终传入 -y。如果这是一个非 React 项目（Swift、Python 等），不要运行 add——请使用 npx -y magicpath-ai inspect <generatedName> -o json 读取源代码作为参考，然后用目标语言和框架重新创建组件。
10. 将组件适配为可用于生产环境 — MagicPath 组件是设计产物：它们体现了视觉意图和结构，但通常无法开箱即用于生产环境。添加后，必须编辑组件文件，以便：

• 使其支持响应式布局：将任何硬编码的宽度/高度（例如 w-[300px]）替换为响应式工具类（w-full max-w-sm、md:w-64 lg:w-80 等响应式断点）。设计可能只展示单一视口；你的任务是让它适用于所有视口。
• 添加真实交互：将静态/占位内容替换为实际的 props、状态和事件处理器。MagicPath 中显示“提交”的按钮需要 onClick prop 和加载状态。表单需要验证和 onSubmit。
• 接入数据流：将组件连接到应用的实际数据——来自父组件的 props、上下文提供程序、API 调用、路由器状态。不要保留模拟数据。
• 保留现有功能：替换现有组件时，检查旧组件提供的每项功能（表单提交、错误处理、加载状态、无障碍支持、键盘导航、分析事件），并确保新组件都能处理。
• 遵循项目惯例，但不要重新设计：使用相同的状态管理和错误处理方式。仅在计算结果能够保留 MagicPath 设计时才复用样式抽象；不要用仅仅相似的本地令牌或基元替换精确值。

第 4 阶段：集成到页面

11. 导入并渲染 — 使用添加命令输出中的 importStatement 导入组件。传入你定义的属性。
12. 确认布局契合 — 放置组件后，检查父级布局，确保它能自然融入。检查组件是否溢出、产生意外间距或破坏页面的响应式布局。

面向生产的设计思维

MagicPath 是一款设计工具。 MagicPath 生成的组件呈现了某个元素应有的外观和结构——它们是以代码形式表达的设计规范。但设计稿和生产环境中的组件并不是一回事：

设计产物	作为 Agent，你的任务
固定宽度 w-[400px]	使其具有响应性：w-full max-w-md 或基于断点设置
静态文本 "John Doe"	替换为动态属性：{user.name}
占位用的 onClick={() => {}}	接入真实处理函数：onClick={handleSubmit}
硬编码的 3 项列表	遍历真实数据：{items.map(…)}
没有错误/加载状态	添加加载指示器、错误边界和空状态
没有无障碍属性	添加 aria-label、role、键盘处理函数和焦点管理
仅适用于桌面端的布局	添加响应式断点和移动端导航模式
src="/photo.jpg" 的装饰性图片	使用真实资源或项目提供的合适占位内容

黄金法则：MagicPath 组件告诉你要构建什么。你的任务是让它真正可用——具备响应式布局、无障碍支持，并完整接入应用。

常见场景

替换现有组件（例如，用 MagicPath 设计替换旧的登录表单）：

1. 彻底阅读旧组件——列出所有属性、回调、验证规则和副作用
2. 使用 npx -y magicpath-ai inspect <generatedName> -o json 检查 MagicPath 组件源码
3. 使用 npx -y magicpath-ai add <generatedName> -y 安装 MagicPath 组件
4. 编辑 MagicPath 组件，使其接受所有相同的属性/回调
5. 确保新组件包含旧组件的所有功能
6. 在父组件中替换导入——父组件代码应几乎不需要改动

根据 MagicPath 设计库构建新页面：

1. 使用 list-components 浏览项目中的组件
2. 先规划页面布局——确定哪些 MagicPath 组件对应哪些区块
3. 使用 npx -y magicpath-ai add <generatedName> -y 一次安装一个所需组件
4. 构建页面布局，并导入各个组件
5. 调整每个组件：响应式尺寸、真实数据、适当的路由和状态管理
6. 确保所有组件的间距、字体排印和颜色使用保持一致

将单个 MagicPath 组件用作灵感来源：

1. 使用 npx -y magicpath-ai inspect <generatedName> -o json 检查源码
2. 理解设计意图——颜色、间距、布局结构和字体排印
3. 安装并调整该组件，或将其用作参考，构建遵循相同设计语言的自定义内容

关键规则

• add 表示安装后使用。 只有在打算导入并渲染已安装的组件时才运行 add。如果只想阅读源代码，请改用 inspect。
• 运行 add 后，务必导入组件。 add 的目的就是获取源文件，供你随后导入。切勿添加组件后再将其样式或标记复制到其他文件中——应直接导入并渲染该组件。
• MagicPath 组件的源代码归你所有。 运行 add 后，组件文件会位于项目中的 src/components/magicpath/<name>/。你可以也应该直接编辑这些文件，以添加 props、更改行为、调整样式或将其接入应用状态。
• 组件需要接入时：（1）运行 add 添加组件，（2）编辑组件文件，使其接收所需的 props（例如 onSubmit、placeholder、className），（3）在父组件中导入它并传入这些 props。不要将组件的 JSX/样式复制到父文件中。
• 切勿直接放入组件了事。 务必阅读周边代码，了解布局限制，并调整组件以适配。未经调整就放入 MagicPath 组件，不是功能，而是缺陷。
• inspect 为只读操作。 它会显示完整源代码，但不会写入任何文件。在决定组件是否符合需求、尚未确定安装之前，请使用此命令。
• add 仅适用于 React/TypeScript 项目。 add 命令会将 .tsx 文件写入 src/components/magicpath/，并安装 npm 依赖。只在 JavaScript/TypeScript 项目中使用 add。对于非 JS 项目（Swift、Python 等），请使用 inspect 阅读组件源代码，然后用项目所用的语言和框架实现其设计和行为。
• 切勿并行运行 view 命令。 view 命令会为用户打开浏览器窗口。一次只打开一个目标。
• 在项目画布中保留嵌入式浏览器。 除非用户明确要求，否则不要将其导航到单个设计预览；如果设计分享链接已足够，请改为返回该链接。
• 开始编写新建项目的内容前，先打开该项目。 当嵌入式浏览器可用，且请求涉及在新项目中进行操作时，请在 create-project 之后、code start 或 code submit 之前，立即显示项目画布。

创建项目

项目是用于存放设计/组件的工作区。只有在用户明确要求创建项目（“新建一个名为……的项目”“为……创建一个项目”），或者用户要求创建新设计但尚无项目上下文，且新项目是合适的归属地时，才使用此功能。

选择工作区

创建之前，请判断项目属于个人还是团队：

• 如果用户指定了团队（“在 Acme Inc 中创建一个项目”），请找到该团队并传入。
• 如果用户说“创建个人项目”，或者没有提及团队且没有任何团队，则默认选择个人工作区。
• 如果用户的意思不明确，且属于一个或多个团队，请运行 npx -y magicpath-ai list-teams -o json 并询问使用哪个工作区——个人工作区还是某个团队工作区。不要猜测。停止操作并等待用户回复。

运行命令

npx -y magicpath-ai create-project --name "My Stuff" -o json                       # personal
npx -y magicpath-ai create-project --name "My Stuff" --team "Acme Inc" -o json     # team

• --name 是可选项。省略时，项目会使用自动生成的占位名称。如果用户告诉你项目名称，务必传入 --name。
• --team 接受团队名称或团队 ID。请根据用户意图，从 list-teams 返回的团队中选择。
• JSON 输出：{ project: { id, name, ownerType, ownerName, ... } }。后续命令需要使用其中的 id。

项目创建完成后

如果用户还要求在新项目中进行设计，请从响应中获取 id，并按照从代码编辑或创建画布组件中所述的画布组件创建流程继续（code start --project <id> --name "..."，填写生成的脚手架文件，然后运行 code submit --wait）。不要为每项设计重新创建项目——一个项目可以包含多个组件。

如果任务包括在新创建的项目中创建或编辑设计，请将该项目视为画布。在嵌入式浏览器宿主中，必须按以下顺序操作：create-project 返回 id 后，立即运行 npx -y magicpath-ai share <projectId> -o json，在嵌入式浏览器中打开返回的项目 URL，然后才开始运行 code start 或 code submit。工作期间让该项目画布保持可见；提交后不要导航到生成的设计预览，除非用户明确要求只查看该设计。如果没有嵌入式浏览器，则在需要面向用户进行导航时使用 npx -y magicpath-ai view <projectId>。

有嵌入式画布时，将 MagicPath 项目用作嵌入式画布

某些 Agent 宿主（包括 Codex 和某些 Cursor 工作流）可以提供嵌入式或应用内浏览器。如果有此功能，MagicPath 项目可以作为持久画布保持在 Agent 旁边打开：Agent 根据本地代码和上下文开展工作，同时用户可以在画布上查看并选择内容。

可将此功能用于打开新创建的项目、重新连接到用户当前的项目，或在命名项目中开始画布创作。不要自动将嵌入式浏览器导航到单个设计或组件；只有在用户明确要求打开特定设计时，才在其中显示该设计。

在嵌入式浏览器宿主中打开项目时，不要先调用 view：view 会打开操作系统浏览器。应改为运行 npx -y magicpath-ai share <projectId> -o json 获取项目 URL（不会打开窗口），然后将宿主的嵌入式浏览器导航到返回的 url。如果没有嵌入式浏览器、无法可靠地控制它，或用户明确希望使用常规浏览器，则使用 view <projectId>。

CLI 身份验证与嵌入式浏览器身份验证相互独立。whoami 或 create-project 命令成功，并不意味着可见的浏览器窗格已登录 MagicPath。如果打开返回的 /files/<projectId> URL 后跳转到主页或登录页面，请让任务继续围绕该项目进行：告诉用户在嵌入式浏览器中登录 MagicPath，然后登录后返回同一个项目 URL。不要仅仅因为公开的单个设计预览无需项目画布会话即可加载，就用它来替代项目画布。

对于后台工作，例如 info、whoami、列出或搜索数据、获取主题、检查源代码，或将组件安装到应用中，不要自动打开项目。完整的决策指南和操作方案见使用嵌入式浏览器。

将现有仓库导入 MagicPath

当用户想要将在 Git 仓库中已有的 UI（本地或在线）复现在 MagicPath 画布上时（例如“把我的应用侧边栏导入 MagicPath”“在 MagicPath 中渲染这个项目”“在这里重建我的落地页”），请通过 code start → code submit 流程将其重建为画布组件。

这是 add/inspect 的逆向流程：源内容是用户的仓库，目标位置是画布。请勿为此使用 add、inspect 或 code context。简要步骤如下：

1. 获取代码 — 直接读取本地路径，或将在线仓库 git clone --depth 1 <url> 到临时目录（与 --dir 指定的目录分开）。私有仓库需要用户凭据——请询问，不要猜测。
2. 先了解设计基础 — 全局 CSS（globals.css/index.css/app.css）、设计令牌（tailwind.config.*、CSS 变量、令牌文件）、字体、主题策略和共享 UI 基础组件。这些决定了复现能否忠于原设计，而非仅仅近似。
3. 确定目标 — 如果是单个元素（例如侧边栏），打开其文件并追踪所有导入项（子组件、图标、样式、数据），以及决定其尺寸和位置的布局父组件。如果是整个页面/项目，找出入口，并决定使用单个可交互画布还是每个屏幕分别使用一个画布（设计默认规则 5）——如有歧义，请询问并停下等待。
4. 在画布上重建 — 执行 code start --project <id> --dir <workdir> --name "..." --width <px> --height <px>，忠实填写 src/components/generated/<Name>.tsx（将仓库使用的框架和样式转换为 React + Tailwind v4），精确匹配颜色/间距/排版，接入实际交互，在本地模拟数据，然后执行 code submit --wait。遵循设计默认规范（响应式、居中、无设备样机、单屏、完全可交互）。
5. 验证 将结果与源应用进行对照，使用 view。

完整的分步指南——包括样式转换表、边缘情况（monorepo、非 React 源码、服务端组件、Tailwind v3→v4）以及“把我的应用侧边栏导入”和“渲染这个项目”的快速方案——请参阅使用仓库。

通过代码编辑或创建画布组件

当用户希望你直接编写或修改 MagicPath 画布组件本身，而不是将现有组件安装到另一个应用中时，请使用此工作流。code 子命令会操作一个工作目录和一个小型清单文件（magicpath-code.json），该文件会记录此目录对应的组件和修订版本。

在 MagicPath 画布上编写组件时，你是一位专家级设计工程师，负责构建精美且实用、可交互的 React 组件。 你在画布上创建的组件（通过 code start / code submit）应当是真正可用的小型应用，而非静态设计稿：由状态驱动，接好悬停 / 焦点 / 激活状态，让按钮能执行操作，让表单能验证，并让过渡效果自然有意。外观漂亮却毫无生气的组件就是失败的组件。（此角色仅适用于 code 流程——通过 add/inspect 将组件安装到用户项目时，请遵循从设计到生产的思维方式。）

非常重要——设计默认规范

除非用户在请求中明确另有要求，否则你使用 code 子命令创建或编辑的每个画布组件都必须遵循这些规则。这些规则不适用于 add/inspect 安装流程——相关要求请参阅从设计到生产的思维方式。对于画布创作，这些规则优先于本技能中的其他所有内容。

1. 绝不添加设备模型框

不要将组件放进 iPhone、Android、笔记本电脑、桌面端或浏览器框架、状态栏、刘海、主屏幕指示条、地址栏或任何其他设备外壳中。只有当用户明确提出要求（“把它显示在手机框架内”“把它放进 iPhone 模型框里”“让它看起来像 Mac 窗口”）时，才添加设备模型框。针对移动端视口进行设计，不代表用户要求添加模型框——画布本身就是设备框架。绝不要在里面再画第二个设备。

2. 所有内容始终要自适应

每个组件都必须适应任意宽度，包括按钮、输入框、徽章和卡片等小型基础元素。使用 w-full、max-w-*、百分比宽度、flex/grid 尺寸设置和断点工具类（sm:、md:、lg:）。不要对外层容器设置固定的像素宽度/高度。唯一的例外是固有尺寸固定的元素（头像、图标、固定尺寸的媒体）。

3. 始终在画布内居中

组件根元素应在其框架内水平居中；当设计内容较少时，还应垂直居中。可在根元素上使用 min-h-screen flex items-center justify-center、mx-auto 或网格居中。画布大于内容时，设计绝不能贴在角落；画布小于内容时，设计也绝不能溢出。

4. 画布尺寸 ≠ 设备模型框

你可以（也应该）向 code start / code submit 传入 --width/--height，以反映目标设备，例如移动端设计使用 --width 390 --height 844，桌面端设计使用 --width 1440 --height 900。这就是表明“这是移动端设计”的方式。但其中的内容必须保持流动自适应：如果之后将同一组件放入更宽或更窄的容器，它应能适配，而不是锁定在原始像素尺寸上。

5. 绝不在一个框架中堆叠多个屏幕

MagicPath 组件是一个框架。不要在单个画布中并排、垂直堆叠或以幻灯片形式绘制“屏幕 1 / 屏幕 2 / 屏幕 3”。这种输出是有问题的——它无法渲染、无法导航，还浪费用户的画布。

当用户需要跨多个视图的内容时，请从以下两种模式中选择一种，并始终遵循该模式：

A. 在一个框架中构建自包含应用（当多个视图属于同一流程时优先采用）。 单个组件可以通过 React 状态、条件渲染、选项卡组件、客户端路由或 useState 驱动的视图切换，包含多个视图、屏幕、模态框、选项卡、步骤或路由。登录 → 注册 → 忘记密码流程、多步骤向导、带选项卡导航的设置页面、带滑出式详情面板的仪表板——这些都应放在一个带内部状态的组件中，而不是拼接多个框架。

B. 使用多个框架（当屏幕彼此真正独立时，每个屏幕对应一个组件）。 如果用户要求的是不同的交付内容——“设计登录屏幕、仪表板和设置页面”——那么每个页面都应是独立的 MagicPath 组件。分别创建 code start --name "..." 会话，每个会话都使用自己的 --dir（共享工作目录的并行会话会互相覆盖对方的 magicpath-code.json）。并发构建这些组件——如果你的环境支持并行子 Agent，就为每个框架启动一个；否则就用运行器允许的方式并行运行会话。不要为了“节省时间”而尝试在一个画布中渲染所有页面——这样会生成有问题的产物。

如果不确定该采用哪种模式，请询问用户：“这是要做成一个带内部导航的交互式组件，还是每个屏幕都做成独立框架？”——然后停下来等待答复。

6. 构建交互式组件，而不是静态标记

你是工程师，不是截图生成器。每个画布组件都必须完全交互——按钮触发实际操作，输入框受控，表单可提交并验证，悬停／聚焦／激活／禁用状态都经过样式设计，模态框可以打开和关闭，选项卡可以切换，抽屉可以滑入滑出，下拉菜单可以展开，开关可以切换，折叠面板可以收起。使用 useState / useReducer 管理本地状态，使用真实事件处理器（onClick、onChange、onSubmit、onKeyDown、onBlur），使用 aria-* 属性确保无障碍，并在能提升质感时添加有意义的过渡效果（Tailwind transition-*、Framer Motion 或 CSS 动画）。如果组件保留了占位的 onClick={() => {}}，或只是交互界面的静态标记，就还没有完成——在执行 code submit 前，先接好交互。如果组件代表多视图流程，请通过状态实现视图间的导航（参见规则 5.A）。

可编辑文件范围。 code API 仅接受以下文件的完整替换：

• src/App.tsx
• src/index.css
• src/components/generated/**
• assets/**（仅限临时图片资源）

切勿编辑或提交 package.json、vite.config.*、src/main.tsx、锁文件或任何其他文件——这些文件会被拒绝。

图片资源。 将本地图片文件放在 <workdir>/assets/ 中，并在代码或 CSS 中引用，例如 ../../../assets/hero.png、/assets/hero.png 或 url("../../assets/hero.png")。MagicPath 会上传这些临时资源，将引用改写为稳定的公开资源 URL，并在构建前移除 assets/ 暂存目录。不要内联 data:image/...;base64,...；如果遇到 base64 图片数据，请将其移入资源文件。

已选中的画布图片。 如果用户在执行 code start 前已在画布上选中图片图形，CLI 会将它们包含在 selectedImages 中，并使用短时有效的访问 URL 将每张图片下载到 assets/selected/**。在导入语句或 CSS 中使用下载的 assetPath。不要直接使用 accessUrl，因为它会过期。

编辑模式支持删除和重命名源文件。 要删除可编辑的源文件，只需从 <workdir> 中移除它——code submit 会检测到删除并同步应用。重命名即是在同一次提交中先删除再写入。资源是临时暂存输入，从本地移除文件不会将其从服务器删除。在创建模式下，没有文件可供删除；只需不要写入该文件。

此工作流中不要使用 add 或 inspect。 add / inspect 用于将可复用的注册表组件安装到其他应用中。code ... 用于编辑用户 MagicPath 画布上的组件；它们是彼此独立的流程，不得混用。

编辑现有组件

1. 运行 npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json。这会创建或复用一个待处理的编辑修订版，在画布上显示 Agent 状态，写入可编辑文件，并将 magicpath-code.json 写入 <workdir>。默认情况下，CLI 从组件当前选定的修订版开始。若要从特定修订版开始，请传入 --revision <revisionId>——当用户查看或引用的不是当前修订版时（例如，从 npx -y magicpath-ai selection 传入的值），此选项很有用。
2. 在 <workdir> 中编辑、添加或删除允许的文件（参见上文的边界说明）。将新图片放在 <workdir>/assets/ 下，并在生成的组件或 CSS 中引用它们。移除子组件文件的最后一个用法时，也要删除其源文件——不要在修订版中留下孤立文件。重命名操作等同于先删除再写入。
3. 运行 npx -y magicpath-ai code submit --dir <workdir> --wait -o json。如果编辑会更改画布的预期尺寸，请在提交时同时传入 --width <px> 和 --height <px>。
4. 如果任务结果为 failed，请阅读返回的已净化诊断信息，仅修复允许的文件，然后重新提交。不要为了绕过构建失败而创建新组件。
5. 如果提交报告冲突或基准状态过期，请再次运行 npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json，以刷新有状态的编辑会话，然后重新应用编辑。

创建新组件

重要的体验规则： 始终先运行 code start，再编写组件文件。这样会在画布上注册待处理组件，让用户看到你正在进行中的工作，而不是一个悄无声息的 Agent。

预期文件结构。 MagicPath 组件的 src/App.tsx 应保持精简，导入并渲染 src/components/generated/ 中的顶层组件。实际实现位于 src/components/generated/<ComponentName>.tsx（PascalCase 文件名，命名导出）中。较大的组件应拆分到 src/components/generated/ 下的其他同级文件中，每个文件按需导入依赖。这是所有现有 MagicPath 组件采用的结构——可以对照 code context 返回的任意现有组件。

CLI 会在运行 code start 时为你搭建此结构。 code start 返回后，工作目录中已包含预先接线的 src/App.tsx 和一个存根文件 src/components/generated/<ComponentName>.tsx。组件文件名与 --name 的 PascalCase 形式一致（例如，--name "Hero Card" → HeroCard.tsx）。你的任务是填充存根——不要重写 App.tsx，它已经正确无误。只有在需要更改顶部的 theme（'light'/'dark'）值时，才编辑 App.tsx。

步骤：

1. 运行 npx -y magicpath-ai code start --project <projectId> --dir <workdir> --name "Component Name" --width <px> --height <px> -o json。选择适合计划构建的组件的尺寸，不要依赖默认画布尺寸。此命令会创建待处理组件，搭建精简的 App.tsx 和存根，并写入 magicpath-code.json。提醒：组件必须具有响应式布局、居中显示、不含设备模型、为单个屏幕（多视图流程请使用内部状态，或通过并行的 code start 会话创建多个独立屏幕），并且完全可交互（真实的处理程序、受控输入、由状态驱动的视图、悬停/聚焦/激活状态）。请参阅上方的设计默认规范。
2. 在 <workdir>/src/components/generated/<ComponentName>.tsx 中填入组件实现。如果组件较复杂，可拆分到同一目录下的其他文件中。
3. 可选择编辑 <workdir>/src/index.css 来添加自定义样式。将图像文件放入 <workdir>/assets/，并在 TSX 或 CSS 中引用，而不要嵌入 base64。
4. 运行 npx -y magicpath-ai code submit --dir <workdir> --wait -o json。如果最终实现需要的画布尺寸与开始时选择的不同，请在此处同时传入 --width <px> 和 --height <px>。
5. 如果构建失败，请修复组件文件，然后重新运行 code submit --wait。除非用户明确提出要求，否则不要开始创建第二个组件。

code create 命令可将 start 和 submit 合并为一次调用。优先使用明确的两步流程——这样在编写文件时，用户能在画布上看到你的进度，你也可以从搭建好的初始结构开始工作。

单独轮询任务

如果需要事后检查任务状态（例如，在未使用 --wait 的情况下提交后），请使用 npx -y magicpath-ai code status <jobId> -o json。它会返回 pending、processing、completed、failed 或 cancelled 之一。

快速参考

# Auth
npx -y magicpath-ai login                    # one-click browser login
npx -y magicpath-ai whoami -o json           # check auth status
npx -y magicpath-ai info -o json             # full project context

# Teams and people
npx -y magicpath-ai list-teams -o json                  # list teams you belong to
npx -y magicpath-ai list-members --team "Acme" -o json  # list members of a team

# Create a new project
npx -y magicpath-ai create-project --name "My Stuff" -o json                    # personal
npx -y magicpath-ai create-project --name "My Stuff" --team "Acme" -o json      # team

# Find components (always use -o json)
npx -y magicpath-ai search "input box" -o json          # search across all workspaces
npx -y magicpath-ai search "button" --team "Acme" -o json   # search within a team
npx -y magicpath-ai list-projects -o json               # list all projects (personal + team)
npx -y magicpath-ai list-projects --team "Acme" -o json     # list only team projects
npx -y magicpath-ai list-projects --personal -o json        # list only personal projects
npx -y magicpath-ai list-components <id> -o json      # list components in a project
npx -y magicpath-ai list-components <id> --created-by <userId> -o json  # filter by person

# Inspect / open components and projects
npx -y magicpath-ai view <generatedName>              # open a component preview in browser
npx -y magicpath-ai view <projectId>                  # open a project in browser
npx -y magicpath-ai share <generatedName> -o json     # print a shareable URL for a component (no browser open)
npx -y magicpath-ai share <projectId> -o json         # print a shareable URL for a project (no browser open)
npx -y magicpath-ai inspect <generatedName> -o json   # show source code (no install)
npx -y magicpath-ai add <generatedName> --dry-run     # show what would be installed

# Install and use components
npx -y magicpath-ai add <generatedName> -y         # add to project (no prompts)

# Themes (design systems)
npx -y magicpath-ai list-themes -o json                 # list personal themes
npx -y magicpath-ai list-themes --team "Acme" -o json   # list team themes
npx -y magicpath-ai get-theme <id-or-name> -o json    # get theme CSS vars, fonts, prompt

# Current canvas context
npx -y magicpath-ai selection -o json                 # get currently selected component(s)
npx -y magicpath-ai active-project -o json            # get the project(s) the user has open

# Project canvas images
npx -y magicpath-ai image list <projectId> -o json            # list images on the project canvas (download each `url` to see it)
npx -y magicpath-ai image add <projectId> ./hero.png -o json  # add a local image (or an http(s) URL) to the canvas
npx -y magicpath-ai image generate --prompt "..." [--aspect-ratio 16:9] [--ref ./photo.jpg] [--out ./img.png] -o json  # AI-generate (or edit via --ref) a raster image; returns local path + hosted URL

# Author/edit canvas components from code (external-agent)
npx -y magicpath-ai code start --project <projectId> --dir <workdir> --name "Name" --width <px> --height <px> -o json # start a new pending component with chosen canvas size
npx -y magicpath-ai code start --component <componentId> --dir <workdir> -o json                 # start editing an existing component
npx -y magicpath-ai code start --component <componentId> --revision <revisionId> --dir <workdir> -o json # start editing a specific revision
npx -y magicpath-ai code context <componentId> --dir <workdir> -o json                           # read-only source fetch/export; not for submit
npx -y magicpath-ai code submit --dir <workdir> --width <px> --height <px> --wait -o json         # submit edits/size + wait for build
npx -y magicpath-ai code status <jobId> -o json                                                  # poll a build job

核心概念

• 每个组件都有一个 generatedName（例如，wispy-river-5234），这是所有操作的标识符。
• 组件会以源代码的形式添加到 src/components/magicpath/<name>/。
• add 命令会返回 importStatement 和 usage，请在代码中使用它们。
• 使用 inspect 检查源代码，无需安装；不要为了读取代码而使用 add。
• MagicPath 组件是 React/TypeScript 源代码：在 JS/TS 项目中使用 add，在其他语言中使用 inspect 并进行转换。
• Themes（设计系统）包含 CSS 变量（light/dark 映射）、可选的 fonts，以及供 Agent 使用、包含样式说明的可选 prompt。“Theme”和“design system”可互换使用。使用 list-themes 浏览，使用 get-theme 获取完整定义。
• 使用 code start + code submit 将源代码编辑发布回 MagicPath 画布。code context 是只读的精确版本检索功能，也可以提供用于导出的源代码快照。add/inspect 仍是安装和检查注册表组件的方式。

当前项目上下文

!`npx -y magicpath-ai info -o json 2>/dev/null || echo '{"error": "Could not run magicpath-ai via npx. Ensure Node.js is installed and the registry is reachable."}'`

以上 JSON 包含身份验证状态、项目和 CLI 版本。如果 auth.authenticated 为 false，用户需要先登录才能执行其他操作。

参考资料

• CLI 参考
• 在本地代码中使用 MagicPath 设计 — 导出精确的组件或版本、替换本地 UI，或转换 MagicPath 设计，同时保留 1:1 的还原度和明确要求的差异
• 使用代码仓库 — 将现有本地或在线 Git 代码仓库的 UI 引入 MagicPath 画布（例如“在 MagicPath 中渲染此项目”“将我的应用侧边栏引入 MagicPath”）
• 使用嵌入式浏览器 — 将 MagicPath 项目用作 Codex、Cursor 或其他带应用内浏览器的宿主中的持久画布