初始化项目版本

2026-07-29 16:04:39 +08:00
commit 4305a1082b
2629 changed files with 760590 additions and 0 deletions
--- a/.agents/skills/stitch-manage-design-system/SKILL.md
+++ b/.agents/skills/stitch-manage-design-system/SKILL.md
@@ -0,0 +1,132 @@
+---
+name: stitch::manage-design-system
+description: >-
+  Manage design systems in Stitch using MCP tools. Includes retrieval of assets,
+  creating/updating design systems in Stitch, and applying them to screens.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+  - "web_fetch"
+---
+
+# Design-System
+
+Create a "source of truth" for your project's design language to ensure
+consistency across all future screens.
+
+> [!NOTE]
+> Refer to your system prompt for instruction on handling MCP tool prefixes for
+> all tools mentioned in this skill (e.g., `get_screen`,
+> `create_design_system_from_design_md`, `apply_design_system`).
+
+## 📥 Retrieval
+
+To analyze a Stitch project, you must retrieve metadata and assets using the
+Stitch MCP tools:
+
+1. **Project lookup**: Use `list_projects` to find the target `projectId`.
+2. **Screen lookup**: Use `list_screens` for that `projectId` to find
+   representative screens (e.g., "Home", "Main Dashboard").
+3. **Metadata fetch**: Call `get_screen` for the target screen to get
+   `screenshot.downloadUrl` and `htmlCode.downloadUrl`.
+4. **Asset download**: Use `read_url_content` to fetch the HTML code.
+
+## 🧠 Synthesis from Description
+
+If you need to extract a design system from existing screens, use the `design-md` skill (in the `stitch-utilities` plugin).
+
+If there are no existing screens (new project), or the user provides a direct description (e.g., "dark theme, blue and purple, rounded, Inter font"):
+
+1. Map the user's vague terms to precise values using the design mappings (see `design-md` skill in `stitch-utilities` or `generate-design` skill).
+2. Select concrete hex codes, font families, and roundness values.
+3. Generate the `DESIGN.md` file (refer to the `design-md` skill in `stitch-utilities` for structure).
+4. Proceed to the "Create or Update Design System in Stitch" step below.
+
+## 📝 Output Structure
+
+The `DESIGN.md` file should follow the structure defined in the `design-md` skill (in the `stitch-utilities` plugin).
+
+## 🚀 Create or Update Design System in Stitch
+
+After generating `.stitch/DESIGN.md`, make sure to also create or update the
+design system in Stitch.
+
+**Two-step design system creation:**
+
+> [!WARNING]
+> **Checkpoint — User Confirmation Required.**
+> Before uploading, you **MUST** pause and ask the user for
+> confirmation. Present a summary of the design system you are about to create
+> (display name, key colors, fonts, and roundness) and wait for explicit approval
+> before proceeding. Do **NOT** upload until the user confirms.
+
+1. **Upload `DESIGN.md`**:
+   - **Option A (Recommended - Uploader Script)**: Use the modified `upload-to-stitch` Python script which natively handles `.md` files. It base64-encodes the markdown file in-process and sends it to the `/v1/projects/{projectId}/screens:batchCreate` endpoint, bypassing output token limits.
+     ```bash
+     python3 stitch-skills/plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
+       --project-id <PROJECT_ID> \
+       --file-path /path/to/DESIGN.md \
+       --api-key <API_KEY> \
+       --generated-by <GENERATED_BY>
+     ```
+     Set `<GENERATED_BY>` to identify the skill or tool that produced the
+     `DESIGN.md`. Use the calling skill name when invoked from another skill
+     (e.g. `stitch::code-to-design`), or the agent/tool name for standalone
+     use (e.g. `Gemini`, `Claude Code`). If omitted, the script defaults to
+     `UserUploadedDesignMd`.
+
+     This returns the `sourceScreen` ID and the `screenInstance` ID.
+   - **Option B (Direct MCP Tool)**: If the `DESIGN.md` is small (under ~5KB), you can call the `upload_design_md` MCP tool directly, passing the base64-encoded design markdown content as `designMdBase64`.
+2. **Create Design System**: Call the `create_design_system_from_design_md` tool immediately after the upload, passing the `projectId` and the `selectedScreenInstance` (containing the `id` and `sourceScreen` returned from the upload step).
+
+Once the upload script and `create_design_system_from_design_md` have both completed,
+Stitch holds the design tokens at the project level — you do NOT need to repeat
+them in generation prompts.
+
+## 🎨 Apply Design System to Screens
+
+Use `apply_design_system` to apply a design system to existing screens.
+
+> [!IMPORTANT]
+> `selectedScreenInstances` must contain **only** `id` and `sourceScreen` — do
+> NOT include position/dimension fields (`x`, `y`, `width`, `height`) or the
+> request will fail with "invalid argument". Get the screen instance IDs from
+> `get_project`.
+
+```json
+{
+  "projectId": "...",
+  "assetId": "...",
+  "selectedScreenInstances": [
+    {
+      "id": "...",
+      "sourceScreen": "projects/.../screens/..."
+    }
+  ]
+}
+```
+
+**How to get the required IDs:**
+1. Call `get_project` to retrieve `screenInstances` — each has an `id` and
+   `sourceScreen`.
+2. Call `list_design_systems` to retrieve the design system `name` (format:
+   `assets/{assetId}`) — use the part after `assets/` as the `assetId`.
+3. Filter out any instances with `type: "DESIGN_SYSTEM_INSTANCE"` — only pass
+   real screens.
+
+## 📋 Update Project Metadata
+
+After writing `.stitch/DESIGN.md`, also create or update `.stitch/metadata.json`
+to track the `projectId`, `title`, all known screens, and design system summary.
+See [examples/metadata.json](examples/metadata.json) for the format.
+
+## Schema Reference
+
+See [reference/tool-schema.md](reference/tool-schema.md) for the full
+`designSystem` object schema with all available options.
+
+## 💡 Best Practices
+
+Refer to the `design-md` skill (in the `stitch-utilities` plugin) for best practices on describing design elements.