@reglow/reui-mcp 0.1.0

package/skills/reui-components/WORKFLOWS.md

@@ -0,0 +1,264 @@
+# ReUI MCP 工作流（WORKFLOWS）
+
+> 本文件说明如何用 reui-mcp 的 7 个工具**确定性地**拿到 ReUI 组件的真实文档与代码，并给出 5 个可直接照做的完整任务示例。
+> 事实来源：`reui/guide.md`、`reui/package.json`、各组件 `README.md`，以及 `reglow-docs/content/components-library/1.reui/`。
+
+## 1. MCP 工具概览
+
+| 工具                     | 用途                               | 关键参数                                                                                                                | 典型返回                                                         |
+| ------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `get_reui_document`      | 取组件完整文档                     | `component`（可选，不传返回按分类的组件总览）、`category`（过滤分类）、`version`、`source`（`auto` / `local` / `site`） | README 正文、API 表格、示例说明；不传 `component` 时返回分类总览 |
+| `get_reui_code_examples` | 提取可直接复制的 Vue/TS 示例       | `component`、序号（第 N 个）、类型过滤、`version`                                                                       | 代码块 + 所在示例标题                                            |
+| `list_component_files`   | 列组件源码文件清单                 | `component`、`version`                                                                                                  | 路径 / 行数 / 大小                                               |
+| `get_file_code`          | 读具体文件内容                     | `component`、文件路径、行号区间、`version`                                                                              | 源码片段                                                         |
+| `get_function_code`      | 取某个函数/常量/组件定义的完整实现 | `component`、符号名、`version`                                                                                          | 实现代码；找不到时返回该文件可用符号清单                         |
+| `search_reui_docs`       | 跨文档与源码关键词检索             | 关键词（支持多个）、`category`、`limit`、`version`                                                                      | `组件/文件:行号` + 上下文片段 + 文档链接                         |
+| `get_reui_guide`         | 库级指南                           | `topic`：`overview` / `install` / `theme` / `i18n` / `nuxt` / `build` / `conventions`                                   | 库级说明                                                         |
+
+**共同参数 `version`**：不传 = 项目本地已安装版本；传值则取该 npm 版本的知识，无网络时降级。
+**兜底行为**：某版本包内缺少源码文档时，工具返回官网文档站（https://reglow.huoli.tech/components-library/reui ）内容，**回复中必须标明来源与版本**。
+
+## 2. 基础查询流程（四步走）
+
+```
+① 定位   get_reui_document（可带 category）        → 确认组件存在、拿到组件名
+② 详情   get_reui_document { component }           → README + API 表格 + slot/event
+③ 示例   get_reui_code_examples { component }      → 可复制代码
+④ 下钻   list_component_files → get_file_code      → 实现细节（仅②③不够时）
+         get_function_code
+```
+
+每一步的**判断标准**：
+
+| 步骤   | 结果够用的标准                                          | 不够时的动作                                                                 |
+| ------ | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| ① 定位 | 目标组件出现在总览中，且有中文说明                      | 换关键词走 `search_reui_docs`；仍无 → 判定「该组件不存在」，不要造名字       |
+| ② 详情 | 找到目标 prop/event/slot 的**表格行**（含类型与默认值） | 文档没有该项 → 走 ④ 读源码确认，而不是猜测                                   |
+| ③ 示例 | 有与本需求同场景的示例（如"受控模式"）                  | 取最接近的示例 + 用 ② 的 API 表格自行拼装；拼装时刻意只使用文档中出现的 prop |
+| ④ 下钻 | 在源码中找到该行为的分支实现                            | 用 `get_function_code` 取整段函数；仍无 → 说明该行为未实现                   |
+
+**查询用语建议**：组件名用目录名（`splitter` / `date-picker` / `code-editor`），与 `components/reui/<name>/` 一致；
+中文名（"面板分割"）留给 `search_reui_docs`。
+
+## 3. 完整任务示例
+
+### 示例 1：给后台详情页做左右分栏（Splitter 基础 + 受控 + 折叠）
+
+| 步骤 | 调用                     | 参数                                              | 判断                                                                                                                                |
+| ---- | ------------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | `get_reui_document`      | `{ component: "splitter" }`                       | 确认 `Splitter` / `SplitterPanel` 两个导出、`orientation`（对齐 `vertical`）、`lazy`、`collapsible`、`destroyOnHidden` 等 prop 存在 |
+| 2    | `get_reui_code_examples` | `{ component: "splitter" }`                       | 需要"受控模式"与"可折叠示例"两段，判断 `@resize` 回调参数为 `PanelSize[]`                                                           |
+| 3    | `get_reui_document`      | `{ component: "splitter" }`                       | 核对 `SplitterPanel` 的 `defaultSize` / `size` / `min` / `max` / `collapsible` 类型                                                 |
+| 4    | `get_function_code`      | `{ component: "splitter", name: "handleResize" }` | 仅在需要确认"折叠后 size 为 0"这类细节时调用                                                                                        |
+
+产出（来自 `components/reui/splitter/README.md`，消费方把导入改成 `@reglow/reui`）：
+
+```vue
+<script setup>
+import { ref } from "vue";
+import { Splitter, SplitterPanel } from "@reglow/reui";
+
+const sizes = ref(["30%", "70%"]);
+</script>
+
+<template>
+  <Splitter class="h-[400px]" @resize="(s) => (sizes = s)">
+    <SplitterPanel :size="sizes[0]" :min="200" collapsible>
+      <div class="p-4">左：列表</div>
+    </SplitterPanel>
+    <SplitterPanel :size="sizes[1]">
+      <div class="p-4">右：详情</div>
+    </SplitterPanel>
+  </Splitter>
+</template>
+```
+
+> 注意：`resize` 事件的回调参数类型是 `PanelSize[]`（`number | string`，数字为 px、字符串支持 `"50%"`）。
+
+### 示例 2：列表页表格（PageTable：分页 + 搜索 + 行操作）
+
+| 步骤 | 调用                     | 参数                                                 | 判断                                                                                                                            |
+| ---- | ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | `get_reui_document`      | `{ component: "table" }`                             | 确认导出名是 **`PageTable`**（组件目录名 `table`，聚合清单里写作"Table（PageTable）"）                                          |
+| 2    | `get_reui_code_examples` | `{ component: "table" }`                             | 取"基本用法""分页""搜索""行操作"四段                                                                                            |
+| 3    | `get_reui_document`      | `{ component: "table" }`                             | 核对 `rowActions` 的 `RowAction` 结构（`key/label/variant/confirm/onClick/show/tooltip`）与 `v-model:page`、`v-model:page-size` |
+| 4    | `search_reui_docs`       | `{ keywords: ["rowActions", "confirm"], limit: 10 }` | 确认删除二次确认是 `confirm: { title, description? }`                                                                           |
+
+产出（来自 `components/reui/table/README.md`）：
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { PageTable } from "@reglow/reui";
+import type { RowAction } from "@reglow/reui";
+import type { ColumnDef } from "@tanstack/vue-table";
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+const columns: ColumnDef<User>[] = [
+  { accessorKey: "name", header: "姓名" },
+  { accessorKey: "email", header: "邮箱" },
+];
+const data = ref<User[]>([]);
+const page = ref(1);
+const pageSize = ref(20);
+const search = ref("");
+const rowSelection = ref({});
+
+const rowActions: RowAction<User>[] = [
+  { key: "edit", label: "编辑", onClick: (row) => console.log(row) },
+  {
+    key: "delete",
+    label: "删除",
+    variant: "destructive",
+    confirm: { title: "确认删除？", description: "此操作不可撤销" },
+    onClick: (row) => console.log("删除", row),
+  },
+];
+</script>
+
+<template>
+  <PageTable
+    :columns="columns"
+    :data="data"
+    :total="100"
+    v-model:page="page"
+    v-model:page-size="pageSize"
+    searchable
+    search-placeholder="搜索..."
+    v-model:search="search"
+    :search-keys="['name', 'email']"
+    selectable
+    v-model:row-selection="rowSelection"
+    :row-actions="rowActions"
+  />
+</template>
+```
+
+### 示例 3：全局统一语言与主题（ConfigProvider / createReui）
+
+| 步骤 | 调用                | 参数                                                   | 判断                                                                                                                                                       |
+| ---- | ------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | `get_reui_guide`    | `{ topic: "theme" }`                                   | 拿到 `ThemeConfig` 全部字段、17 个主色、7 个中性色、圆角取值、持久化 key                                                                                   |
+| 2    | `get_reui_guide`    | `{ topic: "i18n" }`                                    | 拿到 `setLocale` / `addLocale` / `t` / `tm` 语义与内置三语言                                                                                               |
+| 3    | `get_reui_document` | `{ component: "config-provider" }`                     | 核对 `ConfigProvider` 的 props（`locale` / `direction` / `componentSize` / `theme` / `namespace` / `getPopupContainer` / `componentConfig`）与嵌套覆盖规则 |
+| 4    | `get_reui_document` | `{ component: "config-provider", category: "others" }` | 确认文档的分类归属（others），便于回链文档页                                                                                                               |
+
+产出（来自 `guide.md` §4.4 / §5 与 `config-provider/README.md`）：
+
+```vue
+<script setup lang="ts">
+import { ConfigProvider } from "@reglow/reui";
+</script>
+
+<template>
+  <ConfigProvider
+    locale="zh-TW"
+    :theme="{ mode: 'dark', primaryColor: 'emerald', radius: '0.5' }"
+  >
+    <App />
+  </ConfigProvider>
+</template>
+```
+
+```ts
+// 命令式：仅当前会话 / 持久化 / 启动恢复
+import { applyTheme, saveTheme, loadAndApplyTheme } from "@reglow/reui/theme";
+
+applyTheme({
+  mode: "dark",
+  baseColor: "zinc",
+  primaryColor: "emerald",
+  radius: "0.5",
+});
+saveTheme({
+  mode: "dark",
+  baseColor: "zinc",
+  primaryColor: "emerald",
+  radius: "0.5",
+});
+loadAndApplyTheme(); // main.ts 中 mount 前调用，避免白屏闪烁
+```
+
+### 示例 4：新增语言包 + 组件级文案覆盖（i18n）
+
+| 步骤 | 调用                | 参数                                                   | 判断                                                            |
+| ---- | ------------------- | ------------------------------------------------------ | --------------------------------------------------------------- |
+| 1    | `get_reui_guide`    | `{ topic: "i18n" }`                                    | 确认 `addLocale(locale, messages)` 支持新增语言与**深合并覆盖** |
+| 2    | `get_reui_document` | `{ component: "date-picker" }`                         | 找到文案类 prop（`placeholder` 等）与默认值来源                 |
+| 3    | `get_file_code`     | `{ component: "date-picker", file: "DatePicker.vue" }` | 需要确认 key 路径（如 `reui.datePicker.*`）时读源码             |
+| 4    | `get_reui_guide`    | `{ topic: "conventions" }`                             | 若要把新语言提交回组件库，确认三语言同步与响应式铁律            |
+
+产出（来自 `i18n/index.ts` 与 `reglow-docs/.../5.i18n.md`）：
+
+```ts
+import { addLocale } from "@reglow/reui";
+
+// 新增日语（key 结构：common.* + reui.<component>.*）
+addLocale("ja-JP", {
+  common: { confirm: "確認", cancel: "キャンセル" },
+  reui: { modal: { ok: "OK" } },
+});
+
+// 覆盖内置英文部分文案（深合并，不丢其它 key）
+addLocale("en-US", { common: { confirm: "OK" } });
+```
+
+```vue
+<!-- prop 优先于 i18n 默认值 -->
+<DatePicker placeholder="Pick a date" />
+<Transfer :title-text="['Source', 'Target']" />
+```
+
+### 示例 5：Nuxt 项目接入 + SSR 排障
+
+| 步骤 | 调用                | 参数                                                           | 判断                                                                                   |
+| ---- | ------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| 1    | `get_reui_guide`    | `{ topic: "nuxt" }`                                            | 拿到 `modules: ["@reglow/reui/nuxt"]`、`reui: { locale, theme, prefix, injectStyles }` |
+| 2    | `get_reui_guide`    | `{ topic: "install" }`                                         | 确认 Vue >= 3.5、Tailwind CSS 4、`@reglow/reui/style.css` 引入时机                     |
+| 3    | `get_reui_document` | `{ component: "modal" }`                                       | 核对命令式 API（`Modal.confirm` 等）用法                                               |
+| 4    | `search_reui_docs`  | `{ keywords: ["window", "document", "onMounted"], limit: 20 }` | 定位 SSR 不安全代码，产出"仅客户端调用"的整改建议                                      |
+
+产出（来自 `guide.md` §6 / §7 与 `reglow-docs/.../3.usage-nuxt.md`）：
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@reglow/reui/nuxt"],
+  reui: {
+    prefix: "R", // <Button> → <RButton>，避免与宿主组件重名
+    locale: "zh-CN",
+    theme: { mode: "light", primaryColor: "blue", radius: "0.5" },
+    injectStyles: true, // 宿主已有 Tailwind 时设 false（仅注入 components.css）
+  },
+  // file:/软链安装时避免 vue 双实例
+  vite: { resolve: { dedupe: ["vue"] } },
+});
+```
+
+SSR 注意：`Cropper`、`SlideCaptcha`、`QRCode`、`AudioPlayer`、`VideoPlayer`、`Editor`、`Tour`、`Affix`、`BackTop`、`Watermark`、`MasonryGrid` 服务端只渲染占位、客户端水合后激活；`Modal.info/confirm`、`useNotification`、`useToast` 只能在客户端调用。
+
+### 示例 6：文档没写清时的源码下钻（通用兜底套路）
+
+以"CodeEditor 的语言下拉可选项怎么配"为例：
+
+| 步骤 | 调用                   | 参数                                                                               | 判断                                                                               |
+| ---- | ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| 1    | `get_reui_document`    | `{ component: "code-editor" }`                                                     | 拿到 `language` / `languages` / `readonly` / `wrap` / `tabSize` / `height` 等 prop |
+| 2    | `list_component_files` | `{ component: "code-editor" }`                                                     | 看到文件清单（`CodeEditor.vue` / `highlight.ts` / `index.ts`）                     |
+| 3    | `get_file_code`        | `{ component: "code-editor", file: "CodeEditor.vue", startLine: 1, endLine: 120 }` | 看到 props 声明与工具栏渲染分支                                                    |
+| 4    | `get_function_code`    | `{ component: "code-editor", name: "highlightCode" }`                              | 取到独立可用的高亮函数实现与返回结构                                               |
+
+下钻时若 `get_function_code` 报"未找到"，**直接使用返回的可用符号清单**重新挑一个符号名再调，而不是换工具瞎猜。
+
+## 4. 反模式（不要这样做）
+
+1. 跳过 `get_reui_document` 直接凭记忆写 `props`——ReUI 大量组件对齐 antd 命名（`defaultSize`、`activeKey`、`rowActions`），与 shadcn/reka-ui 原始命名不同。
+2. 用 `get_reui_document` 拿总览后，把"组件存在于总览"当成"API 已知"——分类总览不含 props。
+3. 文档缺某行为时，用"应该支持"来补——必须用 `get_file_code` 验证，验证不了就说明未实现。
+4. 忽略版本：跨版本回答时未声明 `version`，导致 API 与实际安装版本不符。
+5. 兜底内容不标来源：工具从官网站点返回内容时必须写明来源与版本。

package/skills.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * reui-skills：把 ReUI 的 Skills 知识包安装到项目中的 AI 工具目录
+ *
+ * 知识包内容（`skills/reui-components/`）：
+ * - SKILL.md            技能入口（何时使用 + 工具速查 + 硬性规则 + 文件导航）
+ * - WORKFLOWS.md        MCP 工具工作流与完整任务示例
+ * - BEST_PRACTICES.md   引入方式、主题、i18n、Nuxt、扩展与常见陷阱
+ * - COMPONENTS.md       按分类的组件选型清单（含官网文档链接）
+ *
+ * 用法：
+ *   npx -y -p @reglow/reui-mcp reui-skills                          # 默认装到 .trae/skills
+ *   npx -y -p @reglow/reui-mcp reui-skills --target cursor          # 装到 .cursor/skills
+ *   npx -y -p @reglow/reui-mcp reui-skills --target .my/skills      # 自定义目录
+ *   npx -y -p @reglow/reui-mcp reui-skills --all                    # 装到全部已知工具目录
+ *   npx -y -p @reglow/reui-mcp reui-skills --list                   # 查看可用目标
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isEntryModule } from "./cli-utils.mjs";
+import { skillTargetsFromIntegrations } from "./integrations.mjs";
+
+const PACKAGE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_SOURCE = path.join(PACKAGE_DIR, "skills");
+const SKILL_NAME = "reui-components";
+
+/**
+ * 各 AI 编程工具的 Skills 目录约定
+ *
+ * 主流工具（Trae / CodeBuddy / Qoder / Cursor / Claude）的目录来自 `integrations.mjs`
+ * 中的官方规格；Qwen Code 与 OpenAI Codex CLI 仅提供 Skills 目标。
+ */
+export const SKILL_TARGETS = {
+  ...skillTargetsFromIntegrations(),
+  qwen: { dir: ".qwen/skills", label: "Qwen Code" },
+  codex: { dir: ".codex/skills", label: "OpenAI Codex CLI" },
+};
+
+/** MCP 配置片段（写入客户端配置的 `mcpServers`） */
+export function mcpConfigSnippet() {
+  return {
+    mcpServers: {
+      "reui-mcp": {
+        command: "npx",
+        args: ["-y", "@reglow/reui-mcp"],
+      },
+    },
+  };
+}
+
+function listSkillFiles(dir, base = dir) {
+  const result = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) result.push(...listSkillFiles(full, base));
+    else if (entry.isFile()) result.push(path.relative(base, full));
+  }
+  return result;
+}
+
+/**
+ * 安装 Skills 知识包
+ *
+ * @param {{ cwd?: string, targets?: string[], force?: boolean, dryRun?: boolean, logger?: (m: string) => void }} options
+ * @returns {{ installed: { target: string, dir: string, files: string[], skipped: string[] }[] }}
+ */
+export function installSkills(options = {}) {
+  const logger = options.logger ?? ((message) => console.log(message));
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const force = options.force ?? false;
+  const dryRun = options.dryRun ?? false;
+  const requested = options.targets?.length ? options.targets : ["trae"];
+
+  if (!fs.existsSync(SKILL_SOURCE)) {
+    throw new Error(`未找到内置 Skills 目录：${SKILL_SOURCE}`);
+  }
+  // 以技能目录为基准计算相对路径，避免安装后出现 `reui-components/reui-components/` 的重复层级
+  const contentDir = path.join(SKILL_SOURCE, SKILL_NAME);
+  if (!fs.existsSync(contentDir)) {
+    throw new Error(`未找到内置技能目录：${contentDir}`);
+  }
+  const sourceFiles = listSkillFiles(contentDir);
+  const installed = [];
+
+  for (const requestedTarget of requested) {
+    const preset = SKILL_TARGETS[requestedTarget];
+    const relativeDir = preset ? preset.dir : requestedTarget;
+    const targetRoot = path.resolve(cwd, relativeDir);
+    const targetDir = path.join(targetRoot, SKILL_NAME);
+    const files = [];
+    const skipped = [];
+
+    for (const file of sourceFiles) {
+      const destination = path.join(targetDir, file);
+      if (fs.existsSync(destination) && !force) {
+        skipped.push(file);
+        continue;
+      }
+      if (!dryRun) {
+        fs.mkdirSync(path.dirname(destination), { recursive: true });
+        fs.copyFileSync(path.join(contentDir, file), destination);
+      }
+      files.push(file);
+    }
+
+    installed.push({ target: requestedTarget, dir: targetDir, files, skipped });
+    logger(
+      `${dryRun ? "[dry-run] " : ""}${preset?.label ?? requestedTarget} → ${path.relative(cwd, targetDir) || targetDir}` +
+      `（写入 ${files.length} 个文件${skipped.length ? `，跳过已存在 ${skipped.length} 个（--force 可覆盖）` : ""}）`,
+    );
+  }
+
+  return { installed };
+}
+
+/** CLI 入口 */
+export function runSkillsCli(argv = process.argv.slice(2)) {
+  if (argv.includes("--list")) {
+    console.log("可用目标（--target 支持预设名或自定义目录）：");
+    for (const [key, value] of Object.entries(SKILL_TARGETS)) {
+      console.log(`  ${key.padEnd(10)} ${value.dir.padEnd(18)} ${value.label}`);
+    }
+    console.log("\n示例：npx -y -p @reglow/reui-mcp reui-skills --target trae");
+    console.log(
+      "需要同时写 MCP 配置：npx -y -p @reglow/reui-mcp reui-setup --tools trae,codebuddy,qoder",
+    );
+    return 0;
+  }
+
+  const values = { target: undefined, cwd: undefined };
+  const flags = { all: false, force: false, dryRun: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--all") flags.all = true;
+    else if (arg === "--force") flags.force = true;
+    else if (arg === "--dry-run") flags.dryRun = true;
+    else if (arg === "--target" || arg === "-t") values.target = argv[++i];
+    else if (arg.startsWith("--target="))
+      values.target = arg.slice("--target=".length);
+    else if (arg === "--cwd") values.cwd = argv[++i];
+    else if (arg.startsWith("--cwd=")) values.cwd = arg.slice("--cwd=".length);
+    else if (arg === "--help" || arg === "-h") {
+      console.log(
+        [
+          "reui-skills —— 安装 ReUI 的 Agent Skills 知识包",
+          "",
+          "用法：npx -y -p @reglow/reui-mcp reui-skills [选项]",
+          "",
+          "选项：",
+          "  -t, --target <name|dir>  安装目标：预设名（trae/codebuddy/qoder/cursor/claude/qwen/codex/generic）或自定义目录，默认 trae",
+          "      --all                安装到全部预设目录",
+          "      --cwd <dir>          项目根目录，默认当前目录",
+          "      --force              覆盖已存在的文件",
+          "      --dry-run            只打印将要写入的文件",
+          "      --list               列出可用目标",
+          "  -h, --help               显示帮助",
+          "",
+          "提示：需要同时写入 MCP 配置时，用 reui-setup（等价于 reui-mcp --setup）。",
+        ].join("\n"),
+      );
+      return 0;
+    }
+  }
+
+  const targets = flags.all
+    ? Object.keys(SKILL_TARGETS)
+    : [values.target ?? "trae"];
+  const result = installSkills({
+    cwd: values.cwd,
+    targets,
+    force: flags.force,
+    dryRun: flags.dryRun,
+  });
+
+  const total = result.installed.reduce(
+    (sum, item) => sum + item.files.length,
+    0,
+  );
+  console.log(`\n已安装 ReUI Skills：${SKILL_NAME}（${total} 个文件）`);
+  console.log("\n配套的 MCP 客户端配置（mcpServers）：");
+  console.log(JSON.stringify(mcpConfigSnippet(), null, 2));
+  console.log(
+    "\n提示：Skills 负责「怎么用」，MCP 负责「查得到」——建议两者一起配置。",
+  );
+  return 0;
+}
+
+if (isEntryModule(import.meta.url)) {
+  try {
+    process.exitCode = runSkillsCli();
+  } catch (error) {
+    console.error(`[reui-skills] 安装失败：${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/tar.mjs

@@ -0,0 +1,115 @@
+/**
+ * 极简 tar 解包（零依赖，仅支持 npm 包发布用的 tar 格式）
+ *
+ * 用途：把 npm registry 下载的 `<pkg>.tgz` 解包到本地缓存目录，
+ * 以便按指定版本查询组件文档与源码。
+ *
+ * 支持：普通文件、目录、PAX 扩展头（path 覆盖）、GNU 长文件名（L）、
+ * 长链接名（K）—— 覆盖 npm 打包产物的全部形态；其余类型直接跳过。
+ */
+
+import { gunzipSync } from "node:zlib";
+
+const BLOCK = 512;
+
+/** 读取 tar 头中的字符串字段 */
+function readString(block, offset, length) {
+  const slice = block.subarray(offset, offset + length);
+  const end = slice.indexOf(0);
+  return slice.subarray(0, end === -1 ? slice.length : end).toString("utf8").trim();
+}
+
+/** 读取八进制数值字段 */
+function readNumber(block, offset, length) {
+  const raw = readString(block, offset, length).replace(/\0/g, "").trim();
+  if (!raw) return 0;
+  const value = Number.parseInt(raw, 8);
+  return Number.isFinite(value) ? value : 0;
+}
+
+/** 解析 PAX 扩展头内容（`<len> <key>=<value>\n` 重复） */
+function parsePax(text) {
+  const result = {};
+  let index = 0;
+  while (index < text.length) {
+    const space = text.indexOf(" ", index);
+    if (space === -1) break;
+    const length = Number.parseInt(text.slice(index, space), 10);
+    if (!Number.isFinite(length) || length <= 0) break;
+    const record = text.slice(space + 1, index + length - 1);
+    const eq = record.indexOf("=");
+    if (eq > 0) result[record.slice(0, eq)] = record.slice(eq + 1);
+    index += length;
+  }
+  return result;
+}
+
+/**
+ * 解包 tar 数据（未压缩）
+ *
+ * @param {Buffer} buffer tar 字节
+ * @param {(entry: { path: string, type: string, data: Buffer }) => void} [onEntry] 逐条回调
+ * @returns {{ path: string, type: string, data: Buffer }[]} 文件条目（不含目录）
+ */
+export function extractTar(buffer, onEntry) {
+  const files = [];
+  let offset = 0;
+  let pendingPax = null;
+  let pendingLongName = null;
+
+  while (offset + BLOCK <= buffer.length) {
+    const header = buffer.subarray(offset, offset + BLOCK);
+    // 连续两个全零块表示归档结束
+    if (header.every((byte) => byte === 0)) {
+      offset += BLOCK;
+      const next = buffer.subarray(offset, offset + BLOCK);
+      if (next.length === 0 || next.every((byte) => byte === 0)) break;
+      continue;
+    }
+
+    const size = readNumber(header, 124, 12);
+    const typeFlag = String.fromCharCode(header[156] || 48);
+    let name = readString(header, 0, 100);
+    const prefix = readString(header, 345, 155);
+    if (prefix) name = `${prefix}/${name}`;
+    const dataStart = offset + BLOCK;
+    const data = buffer.subarray(dataStart, dataStart + size);
+    offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+
+    if (typeFlag === "x" || typeFlag === "X") {
+      pendingPax = parsePax(data.toString("utf8"));
+      continue;
+    }
+    if (typeFlag === "L") {
+      pendingLongName = data.toString("utf8").replace(/\0+$/, "");
+      continue;
+    }
+    if (typeFlag === "K" || typeFlag === "g") continue;
+
+    if (pendingPax?.path) name = pendingPax.path;
+    if (pendingLongName) {
+      name = pendingLongName;
+      pendingLongName = null;
+    }
+    const pax = pendingPax;
+    pendingPax = null;
+
+    if (typeFlag === "0" || typeFlag === "\0" || typeFlag === "7" || typeFlag === "") {
+      const entry = { path: name.replace(/^\.\//, ""), type: "file", data, mode: pax?.mode };
+      files.push(entry);
+      onEntry?.(entry);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * 解包 .tgz 数据
+ *
+ * @param {Buffer} buffer gzip 压缩的 tar
+ * @param {(entry: { path: string, type: string, data: Buffer }) => void} [onEntry]
+ */
+export function extractTarball(buffer, onEntry) {
+  return extractTar(gunzipSync(buffer), onEntry);
+}