Claude Skill→Gemini Cli toml转换器（vibe coding题目）

这个vibe coding结果是可用的：https://ai.studio/apps/drive/1BiBKRsBom8zajmmHYmw1dnnaRVG_in6T
Claude Skill一般是一个目录，（如果是github中的，请下载该repo），然后将一个skill对应的目录打包成一个zip文件，再上传到此web应用即可。

软件设计文档: SkillCompiler (v1.1)

项目名称: SkillCompiler
版本: 1.1 (Web 应用版)
日期: 2025年10月24日
文档状态: 正式版

1. 概述

1.1 项目目标

SkillCompiler 是一个 Web 应用程序，其核心目标是“编译”为 Anthropic Claude 设计的 Skill，将其转换为 Google Gemini CLI 可以直接使用的自包含 .toml 自定义命令。

此工具通过自动化“提示词转换工程”来弥合两个 AI 生态系统之间的差距，允许用户将其为 Claude 构建的复杂、多文件的 Skill 工作流，一键迁移到 Gemini CLI 中。

1.2 核心技术

后端: Python (FastAPI/Flask) 或 Node.js (Express)
核心逻辑: Google Gemini API (通过 AI Studio 或 Vertex AI)
前端: 基础 HTML / CSS / JavaScript

2. 架构与组件定义

为了理解本软件的设计，必须首先理解源（Claude）和目标（Gemini）的结构差异。

2.1 源: Claude Skill 结构

Claude Skill 是一种基于目录的、声明式的结构。

形态: 一个包含多个文件的文件夹 (例如 my_skill/)。
核心指令 (SKILL.MD):
- 一个 Markdown 文件，作为 Skill 的“说明书”。
- 它使用自然语言定义 Skill 的角色、能力、工具以及执行步骤。
资源文件 (.js, .html, .json, .txt):
- SKILL.MD 会引用同一目录下的其他文件，这些文件是 Skill 执行所必需的“知识”或“工具”代码。
执行逻辑 (推测): 当用户调用 @my_skill 时，Claude 的后端会解析 SKILL.MD，并将其引用的所有资源文件内容自动加载到 LLM 的上下文中，形成一个完整的“超级提示词”。

2.2 目标: Gemini CLI TOML 结构

Gemini CLI 自定义命令是一种单一文件、内联式的结构。

形态: 一个单一的 .toml 文件 (例如 my_skill.toml)。
文件名即命令: my_skill.toml 会被注册为 /my_skill 命令。
核心字段:
- description = "...": 一个简短的字符串描述。
- prompt = """...""": 最核心的字段。这是一个多行字符串，包含了当用户调用命令时，发送给 Gemini 模型的完整系统提示词。
执行逻辑:
- 自包含: 与 Claude 不同，Gemini CLI 不会自动加载外部文件。因此，code.js、style.html 等文件的全部内容都必须被**预先内联（inline）**到这个 prompt 字符串内部。
- 参数: prompt 的末尾会自动附加用户在 CLI 中输入的任何额外参数。

3. 功能需求 (Functional Requirements, FRs)

FR1: 软件必须能够接受以下两种输入方式之一，来获取 Claude Skill 的源文件：
- FR1a: 一个指向包含 Skill 的公共 Git 仓库的 URL。
- FR1b: 一个包含 Skill 根目录的 .zip 压缩包上传。
FR2: 软件必须能够接受一个输出命令名（例如 /art）作为输入（通过网页上的一个文本框）。
FR3: 软件必须能够在获取的源文件中找到并读取 SKILL.MD。
FR4: 软件必须能够解析 SKILL.MD，并自动识别所有被引用的本地资源文件（如 .js, .html, .py 等）。
FR5: 软件必须能够读取所有被引用的资源文件的全部内容。
FR6: 软件必须将 SKILL.MD 的内容和所有资源文件的内容打包成一个结构化的“上下文包”（Context Blob）字符串。
FR7: 软件必须调用 Google Gemini API，将此“上下文包”作为输入，并请求 AI 将其**重构（Refactor）**为一个 Gemini CLI .toml 格式的字符串。
FR8: 软件必须能从 Gemini API 的响应中提取 description 和 prompt 的内容。
FR9: 软件必须生成一个 .zip 压缩包供用户下载。此压缩包必须包含：
- FR9a: 一个根据 FR2 命名的 .toml 文件（例如 art.toml）。
- FR9b: 一个 README.md 文件，向用户解释如何将此 .toml 文件安装到 Gemini CLI 中。

4. 公理设计分析 (FRs -> DPs 映射)

本设计采用解耦设计（Uncoupled Design），确保每个功能需求由一个独立的设计参数（模块）满足，形成清晰的数据流。

功能需求 (FR)	描述	设计参数 (DP) / 模块
FR1, FR2	接收 Web 输入 (URL/ZIP, 命令名)	DP1: M1 - Web 接口与输入处理器
(FR1a, FR1b)	从 URL 克隆或从 ZIP 解压源文件	DP1.1: M1.1 - 源文件获取器
FR3, FR4, FR5	查找、解析和读取 Skill 目录及文件	DP2: M2 - Skill 解析器
FR6	聚合所有文件内容	DP3: M3 - 上下文打包器
FR7, FR8	调用 AI API 完成核心转换	DP4: M4 - Gemini 转换引擎
FR9 (a, b)	生成包含 `.toml` 和 `README` 的 .zip 包	DP5: M5 - ZIP 包生成器

5. 模块设计 (Detailed Specification)

M1: Web 接口与输入处理器

技术: FastAPI (Python) 或 Express (Node.js)。
接口: POST /api/v1/compile (使用 multipart/form-data 编码)。
逻辑:
1. 解析 POST 请求体。
2. 提取 output_name (表单字段)。
3. 提取 skill_url (表单字段) 或 skill_zip_file (文件上传)。
4. 调用 M1.1 (源文件获取器)，传入 URL 或 ZIP 文件对象。
5. M1.1 返回一个临时的服务器目录路径 (temp_skill_dir)。
6. 将 temp_skill_dir 和 output_name 传递给 M2。
7. 清理: 在整个请求-响应周期结束时（无论成功或失败），必须使用 try...finally 块确保 temp_skill_dir 被安全删除。

M1.1: 源文件获取器 (M1 的子模块)

输入: URL 字符串或 ZIP 文件对象。
逻辑 (FR1a - URL):
1. 创建一个唯一的临时目录（例如 temp/[UUID]/）。
2. 使用 subprocess.run 安全地执行 git clone --depth 1 [URL] [temp_dir]。
3. 处理 Git 克隆失败和安全注入（例如 command injection）异常。
逻辑 (FR1b - ZIP):
1. 创建一个唯一的临时目录。
2. 使用 zipfile (Python) 库安全地解压上传的 ZIP 文件到该临时目录。
3. 安全: 必须检查“路径遍历攻击”（Zip Slip），确保所有文件都解压到目标目录内。
输出: temp_skill_dir (临时目录的路径)。

M2: Skill 解析器

输入: temp_skill_dir 路径。
逻辑:
1. 在 temp_skill_dir 中搜索 SKILL.MD (不区分大小写)。
2. 若未找到，则向用户返回 400 Bad Request 错误。
3. 读取 SKILL.MD 的全部内容。
4. 使用正则表达式（例如 (./[^\s)]+) 或 href="([^"]+)"）搜索 SKILL.MD 中所有本地文件引用。
输出:
- skill_md_content (字符串)
- referenced_files_paths (文件路径列表)

M3: 上下文打包器

输入: skill_md_content 和 referenced_files_paths。
逻辑:
1. 初始化一个大型字符串 context_blob。
2. 将 skill_md_content 添加到 context_blob，并用分隔符包裹。
3. 遍历 referenced_files_paths 列表：
  - 读取每个文件的全部内容（使用 UTF-8 编码）。
  - 将文件内容（连同文件名）添加到 context_blob，并用分隔符包裹。

输出: context_blob (一个大型字符串)。

示例 context_blob 字符串:

--- BEGIN FILE: SKILL.MD ---
你是一个算法艺术家... 你可以使用 code.js 和 style.html ...
--- END FILE: SKILL.MD ---

--- BEGIN FILE: code.js ---
function drawCircle(ctx) { ... }
--- END FILE: code.js ---

--- BEGIN FILE: style.html ---
<canvas id="myCanvas"></canvas>
--- END FILE: style.html ---

M4: Gemini 转换引擎 (核心模块)

输入: context_blob 字符串。
技术: google-generativeai (Gemini API 客户端)。
逻辑: 调用 Gemini API (例如 gemini-1.5-pro)，并使用以下精心设计的“元提示词” (Meta-Prompt) 来执行转换任务。

--- [Meta-Prompt for Gemini] ---

你是一个专家级 AI 软件工程师，精通 Claude Skill 和 Gemini CLI。
你的任务是将一个 Claude Skill 的全部上下文，转换（编译）为一个 Gemini CLI 的 .toml 自定义命令文件。

Claude Skill 结构 (输入):
我将为你提供一个 "上下文包" (Context Blob)，它用 --- BEGIN FILE: [filename] --- 这样的分隔符来打包 Skill 的所有文件。SKILL.MD 是主指令，其他文件是它引用的资源。

Gemini CLI TOML 结构 (输出):
你必须生成一个 .toml 文件格式的字符串，它必须包含：
1. description = "...": 一句简短的描述，从 SKILL.MD 的意图中提炼。
2. prompt = """...""": 一个单一的、完整的提示词。
转换规则:
1. 内联所有内容: 你必须将 SKILL.MD 的指令和所有资源文件（.js, .html 等）的全部内容都**内联（inline）**到这个单一的 prompt 字段中。
2. 重构指令: 将 SKILL.MD 中对人类的描述（“这是一个 Skill...”）改写为对 Gemini 模型的直接指令（例如：“你是一个算法艺术家...”）。
3. 提供上下文: 在 prompt 中，必须明确告诉 Gemini：“你将使用以下代码：...[粘贴 code.js 内容]... 你将使用以下 HTML 结构：...[粘贴 style.html 内容]...”。
4. 处理参数: prompt 的最后必须包含一个占位符，用于接收用户在 CLI 中输入的参数。例如：“现在，请根据用户的以下请求执行任务：”
5. 格式: 你的输出必须且只能是 TOML 格式的原始文本，以 description = 开头。不要包含任何“好的，这是您的文件”之类的寒暄语。
[输入] 上下文包:
```
{{context_blob}}
```
[输出] TOML 文件内容:

--- [End of Meta-Prompt] ---
输出: 一个包含 .toml 内容的字符串。

M5: ZIP 包生成器

输入: toml_string (来自 M4) 和 output_name (来自 M1, 例如 /art)。
技术: io.BytesIO 和 zipfile.ZipFile (Python)，用于在内存中创建 ZIP 文件。
逻辑:
1. 从 output_name 中提取文件名（例如 art）。toml_filename 将是 art.toml。
2. 在内存中创建一个 ZIP 文件。
3. (FR9a) 将 M4 提供的 toml_string 写入内存中的 zip 包，文件名为 [toml_filename]。
4. (FR9b) 生成 README.md 文件的内容（见下方模板）。
5. 将 README.md 字符串写入内存中的 zip 包。
输出: 一个包含 .zip 文件数据的字节流 (bytes stream)，准备通过 HTTP 响应发送给用户。

README.md 模板:

# Gemini CLI Skill: [output_name]

感谢您使用 SkillCompiler！

## 1. 安装

1.  将本压缩包中的 `[toml_filename]` 文件复制到您的 Gemini CLI 命令目录中。
2.  在 macOS / Linux 上，该目录通常位于：`~/.gemini/commands/`
3.  在 Windows 上，该目录通常位于：`%APPDATA%\gemini\commands\`

**macOS / Linux 快速命令:**
(请在解压本包后，在同一目录中运行)
```bash
mkdir -p ~/.gemini/commands/
cp [toml_filename] ~/.gemini/commands/

2. 使用

重启您的 Gemini CLI（如果它正在运行）。您现在可以使用新的斜杠命令：

gemini [output_name] [您的参数...]


---

### 6. 工程化实施规划

**阶段 1: V0.1 - 核心功能验证 (Meta-Prompt Engineering)**
* **目标:** 验证 M4 (Gemini 转换引擎) 的“元提示词”是否有效。
* **任务:**
    * **手动**执行 M2 和 M3：选择 3-5 个不同复杂度的 Claude Skill 示例。
    * **手动**组合 `context_blob`。
    * **手动**打开 Google AI Studio 网页。
    * 将 M4 中的“元提示词”粘贴到 AI Studio 中，并附加 `context_blob`。
    * **迭代:** 反复调整“元提示词”，直到输出的 `.toml` 稳定、正确且高效。

**阶段 2: V0.2 - 自动化脚本 (本地原型)**
* **目标:** 将 V0.1 的手动流程脚本化。
* **任务:**
    * 编写 M2, M3, M4, M5 的 Python/Node.js 脚本。
    * 使用本地文件路径作为输入（代替 Web 界面）。
    * **验收标准:** 脚本可以运行，并成功在本地生成一个包含 `.toml` 和 `README.md` 的 `.zip` 文件。

**阶段 3: V1.0 - Web 应用后端 (MVP)**
* **目标:** 搭建 Web 服务器并集成所有模块。
* **任务:**
    * 实现 **M1 (Web 接口)**，使用 FastAPI。
    * 实现 **M1.1 (获取器)**，确保 `git clone` 和 `zipfile` 的安全性和临时文件清理（使用 `try...finally` 和 `tempfile` 库）。
    * 将 V0.2 的脚本逻辑集成到 `POST /api/v1/compile` 路由中。
    * **验收标准:** API 端点可以被 Postman 或 cURL 成功调用，并返回一个可下载的 `.zip` 文件。

**阶段 4: V1.1 - 前端界面 (公开发布)**
* **目标:** 创建一个简单的用户界面。
* **任务:**
    * 创建 `index.html`, `style.css`, `app.js` 静态文件。
    * 页面包含：
        * 一个“输入命令名”的文本框 (FR2)。
        * 一个“Git URL”的文本框 (FR1a)。
        * 一个“上传 ZIP 文件”的按钮 (FR1b)。
        * 一个“转换”按钮，并在点击后显示加载中状态。
    * 使用 JavaScript `fetch` API 调用 V1.0 的后端端点，并处理返回的 ZIP 文件下载。

**阶段 5: V2.0 - 健壮性与增强 (未来规划)**
* **任务:**
    * **缓存:** 实现基于 Git 提交哈希 (commit hash) 或 ZIP 文件哈希 (MD5/SHA256) 的缓存，避免对未更改的 Skill 重复调用昂贵的 Gemini API。
    * **批量转换:** 支持包含多个 Skill 子目录的 Git 仓库或 ZIP 文件。
    * **错误处理:** 向前端返回更友好的 JSON 错误信息（例如：“未在 ZIP 中找到 SKILL.MD”）。