@sea-ecommerce/admin-mcp-server 0.1.0 → 0.1.1

package/dist/derlux-admin-mcp.js

@@ -21638,6 +21638,15 @@ var AuthManager = class {
 };
 
 // src/client.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "node:fs";
+function mimeOf(path) {
+  const ext = path.split(".").pop()?.toLowerCase() || "";
+  if (ext === "webp") return "image/webp";
+  if (ext === "png") return "image/png";
+  if (ext === "jpg" || ext === "jpeg") return "image/jpeg";
+  if (ext === "gif") return "image/gif";
+  return "application/octet-stream";
+}
 var MedusaAdminError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -21685,12 +21694,111 @@ var MedusaAdminClient = class {
   getProduct(id) {
     return this.request("GET", `/admin/products/${encodeURIComponent(id)}`);
   }
+  /** 列出销售渠道（用于默认渠道解析） */
+  listSalesChannels(params = {}) {
+    return this.request("GET", `/admin/sales-channels${buildQuery(params)}`);
+  }
   createProduct(body) {
     return this.request("POST", "/admin/products", body);
   }
   updateProduct(id, body) {
     return this.request("POST", `/admin/products/${encodeURIComponent(id)}`, body);
   }
+  /**
+   * 整体替换某变体的价格（多币种）。Medusa v2 价格挂在「变体」上，
+   * POST /admin/products/{id} 携带 variants:[{id, prices}] 即整体替换该变体价格（不会累加）。
+   * prices 数组形如 [{ currency_code, amount }, ...]，amount 为主货币单位（元），切勿 ×100。
+   */
+  updateProductPrices(productId, variantId, prices) {
+    return this.request("POST", `/admin/products/${encodeURIComponent(productId)}`, {
+      variants: [{ id: variantId, prices }]
+    });
+  }
+  /** 批量写入翻译（POST /admin/translations/batch）。reference 一般为 "product"。 */
+  async batchTranslations(create, update = []) {
+    return this.request("POST", "/admin/translations/batch", { create, update });
+  }
+  /**
+   * 把一组商品加入销售渠道（POST /admin/sales-channels/{id}/products）。
+   * ⚠️ 注意：Medusa v2 该端点挂在「渠道」下，不是商品下；body 为 { add:[productIds], remove:[] }。
+   * 商品只有挂到渠道，storefront（按 publishable key → 渠道）才能查到，否则详情页拉不到。
+   */
+  addProductsToSalesChannel(channelId, productIds) {
+    return this.request("POST", `/admin/sales-channels/${encodeURIComponent(channelId)}/products`, {
+      add: productIds,
+      remove: []
+    });
+  }
+  // ─── 商品详情页富内容（product_content 模块）───
+  /**
+   * 读取某商品某语言的富内容块（GET /admin/product-contents）。
+   * locale 用区域码：en-US / zh-CN / ms-MY / id-ID（与 storefront useProductContent 的 localeMap 一致）。
+   * 返回 { product_content: { id, product_id, locale, status, blocks(JSON 字符串) } | null }。
+   */
+  getProductContent(productId, locale = "en-US", status = "published") {
+    return this.request(
+      "GET",
+      `/admin/product-contents${buildQuery({ product_id: productId, locale, status })}`
+    );
+  }
+  /**
+   * 创建/更新某商品某语言的富内容块（POST /admin/product-contents）。
+   * body: { product_id, locale, status?, blocks }；blocks 为 ContentBlock[] 数组
+   * （type ∈ hero/richtext/image_gallery/video/faq/specs）。按 (product_id, locale) upsert。
+   */
+  createProductContent(body) {
+    return this.request("POST", "/admin/product-contents", body);
+  }
+  /**
+   * 上传一组文件到 Medusa 文件服务（POST /admin/uploads，multipart 字段名 files），
+   * 返回上传后的公开 URL 列表。
+   */
+  async uploadFiles(files) {
+    if (!files.length) return [];
+    const form = new FormData();
+    for (const f of files) {
+      form.append("files", new Blob([new Uint8Array(f.buffer)], { type: f.mimetype }), f.filename);
+    }
+    const doPost = async () => {
+      const res = await fetch(`${this.config.backendUrl}/admin/uploads`, {
+        method: "POST",
+        headers: this.auth.headers(),
+        body: form
+      });
+      if (res.status === 401) {
+        this.auth.clear();
+        await this.auth.login();
+        return doPost();
+      }
+      if (!res.ok) {
+        const text = await res.text();
+        throw new MedusaAdminError(res.status, text || res.statusText);
+      }
+      return await res.json();
+    };
+    const data = await doPost();
+    return (data.files || []).map((f) => f.url);
+  }
+  /**
+   * 把一组「本地文件路径 或 图片 URL」解析为可挂到商品的 URL：
+   * - http(s) URL 原样透传；
+   * - 本地路径读取后走 /admin/uploads 上传，返回 URL。
+   */
+  async uploadProductAssets(pathsOrUrls) {
+    const urls = [];
+    const toUpload = [];
+    for (const p of pathsOrUrls) {
+      if (/^https?:\/\//i.test(p)) {
+        urls.push(p);
+        continue;
+      }
+      if (!existsSync2(p)) throw new MedusaAdminError(0, `\u56FE\u7247\u6587\u4EF6\u4E0D\u5B58\u5728: ${p}`);
+      const buf = readFileSync2(p);
+      toUpload.push({ filename: p.split("/").pop() || "image", mimetype: mimeOf(p), buffer: buf });
+    }
+    if (toUpload.length) urls.push(...await this.uploadFiles(toUpload));
+    return urls;
+  }
   // ─── 仓库（StockLocation）/ 库存 ───
   listStockLocations(params = {}) {
     return this.request("GET", `/admin/stock-locations${buildQuery(params)}`);
@@ -21781,7 +21889,9 @@ var productTools = [
     description: `\u5728\u540E\u53F0\u589E\u52A0\u4E00\u4E2A\u5546\u54C1\u3002
 \u89C4\u5219\uFF08\xA716.1\uFF09\uFF1AHandle \u53EA\u80FD\u542B\u5C0F\u5199\u5B57\u6BCD\u3001\u6570\u5B57\u3001\u8FDE\u5B57\u7B26(-)\uFF0C\u5DE5\u5177\u4F1A\u81EA\u52A8\u5F52\u4E00\u5316\uFF0C\u975E\u6CD5\u5219\u62A5\u9519\u3002
 \u591A\u8BED\u8A00\uFF08\xA716.2\uFF09\uFF1Atranslations \u5FC5\u987B\u5305\u542B en/zh/ms/id \u56DB\u79CD\u8BED\u8A00\u7684 title\uFF1B\u7F3A\u5931\u65F6\u9700 confirm=true \u4E14 acknowledge_missing_languages=true\u3002
-\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u53EA\u8FD4\u56DE\u9884\u89C8\uFF0C\u4E0D\u771F\u6B63\u521B\u5EFA\u3002`,
+\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u53EA\u8FD4\u56DE\u9884\u89C8\uFF0C\u4E0D\u771F\u6B63\u521B\u5EFA\u3002
+\u56FE\u7247\uFF1Aimages \u53EF\u4F20\u672C\u5730\u6587\u4EF6\u8DEF\u5F84\uFF08\u81EA\u52A8\u4E0A\u4F20\u5230\u6587\u4EF6\u670D\u52A1\uFF09\u6216\u56FE\u7247 URL\uFF0C\u4EC5\u5728 confirm=true \u65F6\u624D\u771F\u6B63\u4E0A\u4F20/\u6302\u63A5\u3002
+SKU / \u89C4\u683C\uFF1Asku \u5199\u5165\u9ED8\u8BA4\u53D8\u4F53\uFF1Bmetadata \u53EF\u5B58\u4EFB\u610F\u952E\u503C\uFF08\u5982\u89C4\u683C\u53C2\u6570\u3001\u6765\u6E90\u94FE\u63A5\uFF09\u3002`,
     schema: {
       title: external_exports.string(),
       handle: external_exports.string().optional().describe("\u4E0D\u586B\u5219\u7528 title \u5F52\u4E00\u5316\u751F\u6210"),
@@ -21792,9 +21902,13 @@ var productTools = [
       // 并非最小单位（分）。官方 ESLint 规则 prices-in-major-units 明确：
       // "Medusa stores prices in major units"，期望 19.99 而非 1999。
       // 本项目 seed 与 storefront 均遵循此官方约定，故直接透传，不要 ×100。
-      price: external_exports.number().nonnegative().optional().describe("\u4E3B\u8D27\u5E01\u5355\u4F4D\u91D1\u989D\uFF0C\u5982 200.51 \u5373 RM200.51\uFF1BMedusa \u4EE5\u4E3B\u5355\u4F4D\u5B58\u50A8\uFF0C\u5207\u52FF\u6362\u7B97"),
+      price: external_exports.number().nonnegative().optional().describe("\u4E3B\u8D27\u5E01\u5355\u4F4D\u91D1\u989D\uFF0C\u5982 200.51 \u5373 RM200.51\uFF1BMedusa \u4EE5\u4E3B\u5355\u4F4D\u5B58\u50A8\uFF0C\u5207\u52FF\u6362\u7B97\u3002\u4E0E prices \u4E8C\u9009\u4E00\uFF0Cprices \u4F18\u5148"),
       currency_code: external_exports.string().default("MYR"),
+      prices: external_exports.array(external_exports.object({ currency_code: external_exports.string(), amount: external_exports.number().nonnegative() })).optional().describe('\u591A\u5E01\u79CD\u4EF7\u683C\uFF08\u4E3B\u8D27\u5E01\u5355\u4F4D\uFF09\uFF0C\u5982 [{currency_code:"myr",amount:420},{currency_code:"sgd",amount:127}]\u3002\u4E1C\u5357\u4E9A\u5E97\u901A\u5E38\u9700\u8986\u76D6 myr/sgd/idr/thb/php/cny\u3002\u4F18\u5148\u4E8E\u5355\u4E00 price'),
       translations: external_exports.record(external_exports.string(), translationShape).optional(),
+      images: external_exports.array(external_exports.string()).optional().describe("\u672C\u5730\u56FE\u7247\u8DEF\u5F84\u6216\u56FE\u7247 URL\uFF0Cconfirm=true \u65F6\u4E0A\u4F20\u5E76\u6302\u5230\u5546\u54C1"),
+      sku: external_exports.string().optional().describe("\u5199\u5165\u9ED8\u8BA4\u53D8\u4F53\u7684 SKU"),
+      metadata: external_exports.record(external_exports.string(), external_exports.string()).optional().describe("\u4EFB\u610F\u952E\u503C\uFF0C\u5982\u89C4\u683C\u53C2\u6570 / source_url"),
       confirm: external_exports.boolean().default(false),
       acknowledge_missing_languages: external_exports.boolean().default(false)
     },
@@ -21817,6 +21931,10 @@ var productTools = [
             status: input.status,
             price: input.price,
             currency_code: input.currency_code,
+            prices: input.prices,
+            sku: input.sku,
+            images: input.images,
+            metadata: input.metadata,
             missing_translations: missing
           },
           note: "\u672A confirm\uFF0C\u4EC5\u9884\u89C8\u3002\u786E\u8BA4\u8BF7\u8BBE confirm=true\u3002"
@@ -21825,25 +21943,54 @@ var productTools = [
       if (missing.length > 0 && !input.acknowledge_missing_languages) {
         return `\u9519\u8BEF\uFF1A\u7F3A\u5C11\u4EE5\u4E0B\u8BED\u8A00\u7684 title\uFF1A${missing.join(", ")}\u3002\u5982\u786E\u8BA4\u4ECD\u8981\u521B\u5EFA\uFF0C\u8BF7\u8BBE acknowledge_missing_languages=true\u3002`;
       }
+      let imageUrls = [];
+      if (input.images?.length) {
+        try {
+          imageUrls = await client2.uploadProductAssets(input.images);
+        } catch (e) {
+          return `\u9519\u8BEF\uFF1A\u56FE\u7247\u4E0A\u4F20\u5931\u8D25 \u2014\u2014 ${e?.message || e}`;
+        }
+      }
       const payload = {
         title: input.title,
         handle,
         status: input.status,
         subtitle: input.subtitle,
-        description: input.description
+        description: input.description,
+        options: [{ title: "Default", values: ["Default"] }]
       };
-      if (input.translations) payload.translations = input.translations;
-      if (input.price != null) {
-        payload.variants = [
-          {
-            title: "Default",
-            prices: [{ amount: input.price, currency_code: input.currency_code }],
-            manage_inventory: false
-          }
-        ];
+      if (input.metadata) payload.metadata = input.metadata;
+      if (imageUrls.length) payload.images = imageUrls.map((url) => ({ url }));
+      const variantPrices = input.prices && input.prices.length ? input.prices.map((p) => ({ amount: p.amount, currency_code: p.currency_code })) : input.price != null ? [{ amount: input.price, currency_code: input.currency_code }] : void 0;
+      if (variantPrices) {
+        const variant = {
+          title: "Default",
+          options: { Default: "Default" },
+          prices: variantPrices,
+          manage_inventory: false
+        };
+        if (input.sku) variant.sku = input.sku;
+        payload.variants = [variant];
       }
       const data = await client2.createProduct(payload);
-      return { created: data, warning_missing_languages: missing };
+      let translationResult = null;
+      if (input.translations && Object.keys(input.translations).length) {
+        const productId = data?.product?.id || data?.id;
+        if (productId) {
+          const create = Object.entries(input.translations).map(([locale, t]) => ({
+            reference: "product",
+            reference_id: productId,
+            locale_code: locale,
+            translations: { title: t?.title, description: t?.description }
+          }));
+          try {
+            translationResult = await client2.batchTranslations(create);
+          } catch (e) {
+            return { created: data, warning_translations: `\u7FFB\u8BD1\u5199\u5165\u5931\u8D25 \u2014\u2014 ${e?.message || e}` };
+          }
+        }
+      }
+      return { created: data, translations: translationResult, warning_missing_languages: missing };
     }
   },
   {
@@ -21870,9 +22017,58 @@ var productTools = [
       if (input.status) patch.status = input.status;
       if (input.subtitle) patch.subtitle = input.subtitle;
       if (input.description) patch.description = input.description;
-      if (input.translations) patch.translations = input.translations;
       if (!input.confirm) return { dry_run: true, will_update: patch };
-      return client2.updateProduct(input.id, patch);
+      const data = await client2.updateProduct(input.id, patch);
+      let translationResult = null;
+      if (input.translations && Object.keys(input.translations).length) {
+        const create = Object.entries(input.translations).map(([locale, t]) => ({
+          reference: "product",
+          reference_id: input.id,
+          locale_code: locale,
+          translations: { title: t?.title, description: t?.description }
+        }));
+        try {
+          translationResult = await client2.batchTranslations(create);
+        } catch (e) {
+          return { updated: data, warning_translations: `\u7FFB\u8BD1\u5199\u5165\u5931\u8D25 \u2014\u2014 ${e?.message || e}` };
+        }
+      }
+      return { updated: data, translations: translationResult };
+    }
+  },
+  {
+    name: "update_product_prices",
+    description: `\u8BBE\u7F6E/\u66FF\u6362\u67D0\u5546\u54C1\u7684\uFF08\u53D8\u4F53\uFF09\u4EF7\u683C\uFF0C\u652F\u6301\u591A\u5E01\u79CD\u3002Medusa \u4EF7\u683C\u6302\u5728\u300C\u53D8\u4F53\u300D\u4E0A\uFF0C\u5199\u5165\u5373\u6574\u4F53\u66FF\u6362\u8BE5\u53D8\u4F53\u7684\u5168\u90E8\u4EF7\u683C\uFF08\u4E0D\u4F1A\u7D2F\u52A0\u65E7\u4EF7\uFF09\u3002
+\u4EF7\u683C\u4EE5\u4E3B\u8D27\u5E01\u5355\u4F4D\uFF08\u5143\uFF09\u5B58\u50A8\uFF0C\u5207\u52FF \xD7100\u3002\u4E1C\u5357\u4E9A\u8DE8\u5883\u5E97\u901A\u5E38\u9700\u8986\u76D6 myr/sgd/idr/thb/php/cny\u3002
+\u4E0D\u6307\u5B9A variant_id \u65F6\u4F5C\u7528\u4E8E\u7B2C\u4E00\u4E2A\u53D8\u4F53\uFF08\u5355 SKU \u5546\u54C1\u5373\u552F\u4E00\u53D8\u4F53\uFF09\u3002\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\u3002`,
+    schema: {
+      product_id: external_exports.string(),
+      prices: external_exports.array(external_exports.object({ currency_code: external_exports.string(), amount: external_exports.number().nonnegative() })).describe('\u591A\u5E01\u79CD\u4EF7\u683C\u6570\u7EC4\uFF08\u4E3B\u8D27\u5E01\u5355\u4F4D\uFF09\uFF0C\u5982 [{currency_code:"myr",amount:420},{currency_code:"sgd",amount:127}]'),
+      variant_id: external_exports.string().optional().describe("\u76EE\u6807\u53D8\u4F53 id\uFF1B\u7701\u7565\u5219\u53D6\u7B2C\u4E00\u4E2A\u53D8\u4F53"),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, { client: client2 }) {
+      if (!input.confirm) {
+        return {
+          dry_run: true,
+          product_id: input.product_id,
+          will_set_prices: input.prices,
+          variant_id: input.variant_id || "(\u7B2C\u4E00\u4E2A\u53D8\u4F53)"
+        };
+      }
+      const prod = await client2.getProduct(input.product_id).catch(() => null);
+      const product = prod?.product ?? prod;
+      if (!product) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u5546\u54C1 ${input.product_id}`;
+      const variants = product.variants || [];
+      if (!variants.length) return `\u9519\u8BEF\uFF1A\u5546\u54C1\u6CA1\u6709\u53D8\u4F53\uFF0C\u65E0\u6CD5\u8BBE\u7F6E\u4EF7\u683C\u3002`;
+      const target = input.variant_id ? variants.find((v) => v.id === input.variant_id) : variants[0];
+      if (!target) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u76EE\u6807\u53D8\u4F53\uFF08\u6307\u5B9A ${input.variant_id} \u6216\u7B2C\u4E00\u4E2A\u53D8\u4F53\uFF09\u3002`;
+      const data = await client2.updateProductPrices(
+        input.product_id,
+        target.id,
+        input.prices.map((p) => ({ amount: p.amount, currency_code: p.currency_code }))
+      );
+      return { updated: data };
     }
   },
   {
@@ -21886,6 +22082,132 @@ var productTools = [
       if (!input.confirm) return { dry_run: true, will_set_status: "archived" };
       return client2.updateProduct(input.id, { status: "archived" });
     }
+  },
+  {
+    name: "upload_product_image",
+    description: `\u7ED9\u5DF2\u5B58\u5728\u7684\u5546\u54C1\u8FFD\u52A0\u56FE\u7247\u3002\u652F\u6301\u672C\u5730\u6587\u4EF6\u8DEF\u5F84\uFF08\u81EA\u52A8\u4E0A\u4F20\u5230\u6587\u4EF6\u670D\u52A1\uFF09\u6216\u56FE\u7247 URL\u3002
+\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\uFF1Bconfirm=true \u624D\u4E0A\u4F20\u5E76\u6302\u5230\u5546\u54C1\uFF08\u4E0E\u73B0\u6709\u56FE\u7247\u5408\u5E76\uFF0C\u4E0D\u4F1A\u8986\u76D6\u5DF2\u6709\u56FE\u7247\uFF09\u3002`,
+    schema: {
+      product_id: external_exports.string(),
+      images: external_exports.array(external_exports.string()).describe("\u672C\u5730\u56FE\u7247\u8DEF\u5F84\u6216\u56FE\u7247 URL"),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, { client: client2 }) {
+      if (!input.confirm) {
+        return { dry_run: true, product_id: input.product_id, will_upload: input.images };
+      }
+      let urls = [];
+      try {
+        urls = await client2.uploadProductAssets(input.images);
+      } catch (e) {
+        return `\u9519\u8BEF\uFF1A\u56FE\u7247\u4E0A\u4F20\u5931\u8D25 \u2014\u2014 ${e?.message || e}`;
+      }
+      const existing = await client2.getProduct(input.product_id).catch(() => null);
+      const prod = existing?.product ?? existing ?? {};
+      const existingUrls = (prod.images || []).map((i) => i.url).filter(Boolean);
+      const merged = Array.from(/* @__PURE__ */ new Set([...existingUrls, ...urls]));
+      const data = await client2.updateProduct(input.product_id, {
+        images: merged.map((u) => ({ url: u }))
+      });
+      return { updated: data };
+    }
+  },
+  {
+    name: "add_product_to_sales_channel",
+    description: `\u628A\u5546\u54C1\u52A0\u5165\u9500\u552E\u6E20\u9053\uFF0C\u4F7F\u5176\u5728\u524D\u7AEF\u5546\u57CE\uFF08\u6309 publishable key \u2192 \u6E20\u9053\u8FC7\u6EE4\uFF09\u53EF\u89C1\u3002
+\u26A0\uFE0F Medusa v2 \u7AEF\u70B9\u6302\u5728\u6E20\u9053\u4E0B\uFF1APOST /admin/sales-channels/{id}/products\uFF0C\u800C\u975E\u5546\u54C1\u4E0B\u3002
+\u4E0D\u6307\u5B9A channel_id \u65F6\u9ED8\u8BA4\u52A0\u5165\u7B2C\u4E00\u4E2A\u542F\u7528\u7684\u6E20\u9053\u3002\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\u3002`,
+    schema: {
+      product_ids: external_exports.array(external_exports.string()).describe("\u8981\u52A0\u5165\u6E20\u9053\u7684\u5546\u54C1 id \u5217\u8868"),
+      channel_id: external_exports.string().optional().describe("\u9500\u552E\u6E20\u9053 id\uFF1B\u7701\u7565\u5219\u53D6\u7B2C\u4E00\u4E2A\u542F\u7528\u7684\u6E20\u9053"),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, { client: client2, config: config3 }) {
+      if (!input.confirm) {
+        return { dry_run: true, will_add: input.product_ids, channel_id: input.channel_id || "(\u9ED8\u8BA4\u7B2C\u4E00\u4E2A\u542F\u7528\u6E20\u9053)" };
+      }
+      let channelId = input.channel_id;
+      if (!channelId) {
+        const ch = await client2.listSalesChannels?.();
+        const list = ch?.sales_channels || [];
+        const firstEnabled = list.find((c) => !c.is_disabled) || list[0];
+        if (!firstEnabled) return "\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u53EF\u7528\u7684\u9500\u552E\u6E20\u9053\u3002";
+        channelId = firstEnabled.id;
+      }
+      const data = await client2.addProductsToSalesChannel(channelId, input.product_ids);
+      return { added_to_channel: channelId, result: data };
+    }
+  },
+  {
+    name: "get_product_content",
+    description: `\u8BFB\u53D6\u5546\u54C1\u8BE6\u60C5\u9875\u5BCC\u5185\u5BB9\u5757\uFF08GET /admin/product-contents\uFF09\u3002
+locale \u7528\u533A\u57DF\u7801\uFF1Aen-US / zh-CN / ms-MY / id-ID\uFF08\u4E0E\u524D\u7AEF useProductContent \u7684 localeMap \u4E00\u81F4\uFF09\u3002
+\u8FD4\u56DE { product_content: { id, product_id, locale, status, blocks(\u5DF2\u89E3\u6790\u6570\u7EC4) } | null }\u3002`,
+    schema: {
+      product_id: external_exports.string(),
+      locale: external_exports.enum(["en-US", "zh-CN", "ms-MY", "id-ID"]).default("en-US"),
+      status: external_exports.enum(["draft", "published"]).default("published")
+    },
+    async run(input, { client: client2 }) {
+      const data = await client2.getProductContent(input.product_id, input.locale, input.status);
+      const pc = data?.product_content;
+      if (!pc) return { product_content: null };
+      let blocks = [];
+      try {
+        blocks = pc.blocks ? JSON.parse(pc.blocks) : [];
+      } catch {
+        blocks = [];
+      }
+      return { product_content: { ...pc, blocks } };
+    }
+  },
+  {
+    name: "create_product_content",
+    description: `\u521B\u5EFA/\u66F4\u65B0\u5546\u54C1\u8BE6\u60C5\u9875\u5BCC\u5185\u5BB9\u5757\uFF08POST /admin/product-contents\uFF0C\u6309 product_id+locale upsert\uFF09\u3002
+storefront \u8BE6\u60C5\u9875\u300C\u5BCC\u5185\u5BB9\u300D\u533A\u7531\u8FD9\u4E9B\u5757\u6E32\u67D3\u2014\u2014\u4EC5\u586B product.description \u4E0D\u4F1A\u663E\u793A\u5728\u8FD9\u91CC\uFF0C\u5FC5\u987B\u5EFA\u5185\u5BB9\u5757\uFF0C\u5426\u5219\u8BE6\u60C5\u9875\u4E3B\u4F53\u7A7A\u767D\u3002
+\u533A\u5757\u7C7B\u578B type \u2208 hero / richtext / image_gallery / video / faq / specs\uFF1A
+- richtext: data.{ html }\uFF08\u76F4\u63A5\u6E32\u67D3 HTML\uFF0C\u53EF\u542B <p>/<h2>/<ul> \u7B49\uFF09
+- image_gallery: data.{ images:string[], caption? }
+- hero: data.{ image?, title?, subtitle? }
+- video: data.{ url, poster? }\uFF08\u652F\u6301 YouTube\uFF09
+- faq: data.{ items: {question,answer}[] }
+- specs: data.{ rows: {label,value}[] }
+\u26A0\uFE0F locale \u5FC5\u987B\u7528\u533A\u57DF\u7801 en-US / zh-CN / ms-MY / id-ID\uFF08\u4E0E\u524D\u7AEF\u4E00\u81F4\uFF09\uFF1B\u5546\u54C1\u6807\u9898/\u63CF\u8FF0\u7684\u7FFB\u8BD1\u7528\u77ED\u7801 en/zh/ms/id\uFF0C\u4E8C\u8005\u4E0D\u540C\u3002
+\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\u3002`,
+    schema: {
+      product_id: external_exports.string(),
+      locale: external_exports.enum(["en-US", "zh-CN", "ms-MY", "id-ID"]).default("en-US"),
+      status: external_exports.enum(["draft", "published"]).default("published"),
+      blocks: external_exports.array(
+        external_exports.object({
+          id: external_exports.string().optional(),
+          type: external_exports.enum(["hero", "richtext", "image_gallery", "video", "faq", "specs"]),
+          data: external_exports.record(external_exports.string(), external_exports.any())
+        })
+      ).describe("ContentBlock[] \u6570\u7EC4"),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, { client: client2 }) {
+      if (!input.confirm) {
+        return {
+          dry_run: true,
+          will_create: {
+            product_id: input.product_id,
+            locale: input.locale,
+            status: input.status,
+            block_count: input.blocks.length,
+            types: input.blocks.map((b) => b.type)
+          }
+        };
+      }
+      const data = await client2.createProductContent({
+        product_id: input.product_id,
+        locale: input.locale,
+        status: input.status,
+        blocks: input.blocks
+      });
+      return { created: data };
+    }
   }
 ];
 
@@ -22012,11 +22334,11 @@ var opsTools = [
 ];
 
 // src/resources/docs.ts
-import { readdirSync, readFileSync as readFileSync2, existsSync as existsSync2, statSync } from "node:fs";
+import { readdirSync, readFileSync as readFileSync3, existsSync as existsSync3, statSync } from "node:fs";
 import { join as join2 } from "node:path";
 var cache = null;
 function walk(dir, out = []) {
-  if (!existsSync2(dir)) return out;
+  if (!existsSync3(dir)) return out;
   for (const entry of readdirSync(dir)) {
     const full = join2(dir, entry);
     try {
@@ -22028,7 +22350,7 @@ function walk(dir, out = []) {
   return out;
 }
 function parseFile(path) {
-  const raw = readFileSync2(path, "utf8");
+  const raw = readFileSync3(path, "utf8");
   const lines = raw.split("\n");
   const title = lines.find((l) => l.startsWith("# "))?.slice(2).trim() || path;
   const sections = [];
@@ -22139,7 +22461,7 @@ var config2 = loadConfig();
 var auth = new AuthManager(config2);
 var client = new MedusaAdminClient(config2, auth);
 var ctx = { client, config: config2 };
-var server = new McpServer({ name: "derlux-admin", version: "0.1.0" });
+var server = new McpServer({ name: "derlux-admin", version: "0.1.1" });
 for (const def of toolDefs) {
   server.tool(def.name, def.description, def.schema, async (args) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sea-ecommerce/admin-mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "description": "让运营同学用本地 AI agent（Codex / Workbuddy / Claude / Cursor / CodeBuddy）运营 Medusa 后台的 MCP server。",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skill"
   ],
   "scripts": {
     "dev": "tsx src/index.ts",

package/skill/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: derlux-admin-mcp-ops
+description: 运营使用本地 AI agent（derlux-admin MCP server）操作 DERLUX Store 后台的指南。覆盖商品创建/修改/下架、仓库与库存调整、订单/退货/仓库作业查询、后台使用问答。当用户要让 agent 创建、修改或下架商品、调整某仓库库存、查询订单或退货、或询问「后台怎么操作某功能」时使用。
+---
+
+# DERLUX 运营后台 MCP 操作指南（derlux-admin）
+
+> 本文件随 npm 包 `@sea-ecommerce/admin-mcp-server` 一同发布，运营/agent 可经 npm 公开文件链接读取，
+> 例如：`https://unpkg.com/@sea-ecommerce/admin-mcp-server/skill/SKILL.md`
+> 或 `https://cdn.jsdelivr.net/npm/@sea-ecommerce/admin-mcp-server/skill/SKILL.md`
+
+## 你是谁 / 这个 skill 是做什么的
+
+你已接入一个名为 **`derlux-admin`** 的 MCP server。它把 DERLUX Store（面向马来西亚/印尼的东南亚电商，法律主体「香港德樂仕股份有限公司」）Medusa 后台的运营动作封装成一批语义化工具（tool），由你直接调用，代替运营同学在后台界面手动点选。
+
+关键前提（务必记牢）：
+
+- **认证复用真实后台管理员账号**（须持有 `csr` 或 `super_admin` 角色），权限受现有 RBAC 约束。敏感动作若账号无权限，后端会直接拦截。
+- **所有写操作默认是「预览（dry_run）」**，只有显式设 `confirm=true` 才会真正落到后台。这是给运营的兜底保护，不要跳过预览。
+- 每次调用都会写入审计日志 `~/.derlux/mcp-audit.log`，操作可追溯。
+
+## ⚠️ 必须遵守的硬规则（每次调用写工具前自查）
+
+1. **预览优先，确认后执行**：任何写工具先以 `confirm=false`（默认）跑一次，把返回的预览读给运营确认；得到明确确认后，再用 `confirm=true` 真正执行。绝不在未确认时直接写库。
+2. **价格单位 = 主货币单位（元），不要 ×100**：金额直接透传主单位，例如 `200.51` 就是 RM200.51 / MYR200.51。Medusa v2.21 以主单位存储金额，**绝不要写成 20051**。
+3. **Handle 自动归一化**：商品 `handle` 会被自动转小写、空格/下划线/点→连字符、剔除其余非法字符。归一化后仍非法（空或全部被剔除）工具会直接报错，你无需手工处理，但应避免给无意义输入；未填时由 `title` 自动生成。
+4. **多语言必填**：`create_product` / `update_product` 的 `translations` 应覆盖 `en` / `zh` / `ms` / `id` 四种语言的 `title`（建议也带 `description`）。缺语言时：预览会告警；真正写入需 `confirm=true` **且** `acknowledge_missing_languages=true`。创建前主动提醒运营补全翻译，不要默默放行。工具会**自动**把翻译写入 Medusa v2.21 专用的 `/admin/translations/batch` 端点（商品创建体本身不接受 `translations` 字段），你无需手动调用该端点。
+5. **审计可追溯**：无需你处理，但要知道每次动作都在 `~/.derlux/mcp-audit.log` 留痕。
+6. **商品必须挂销售渠道才在前端可见**：新建商品默认**不在任何销售渠道**，storefront（按 publishable key → 渠道过滤）拉不到它，详情页表现成「空/404」。录入后用 `add_product_to_sales_channel`（`confirm=true`）把它加入渠道（默认第一个启用渠道；马来西亚站用 `sc_01M4K4F0D6HBHZ0NH6WB7H5KPT`「MY Storefront」）。
+7. **两套 locale 码，别混**：
+   - 商品标题/描述的**翻译**（`create_product` 的 `translations`、后端 `/admin/translations/batch`）：用**简码** `en` / `zh` / `ms` / `id`。store `/store/products?locale=zh` 即回退到 zh 翻译。
+   - 商品详情页**富内容块**（`create_product_content` 的 `locale`）：必须用**区域码** `en-US` / `zh-CN` / `ms-MY` / `id-ID`（与前端 `useProductContent` 的 localeMap 一致）。用简码会导致该语言详情页读不到内容。
+8. **详情页「富内容」区靠 `create_product_content`，不是 `description`**：storefront 详情页下方大块内容由 `product_content` 模块渲染（`richtext`/`specs`/`image_gallery` 等）。只填 `product.description` 不会显示在那里——录入完整商品时必须再建一份 `product_content`（建议每语言一份）。`get_product` 默认不含该字段，核对请用 `get_product_content`。
+
+## 工具速查表
+
+| 工具 | 类型 | 写库？ | 默认行为 |
+|---|---|---|---|
+| `list_products` | 读 | 否 | 直接返回 |
+| `get_product` | 读 | 否 | 直接返回 |
+| `list_stock_locations` | 读 | 否 | 直接返回 |
+| `get_inventory_levels` | 读 | 否 | 直接返回（按 location_id 列库存条目与水平）|
+| `list_orders` | 读 | 否 | 直接返回 |
+| `get_order` | 读 | 否 | 直接返回 |
+| `list_warehouse_tasks` | 读 | 否 | 直接返回（自定义端点）|
+| `list_return_requests` | 读 | 否 | 直接返回（自定义端点）|
+| `search_docs` | 读 | 否 | 检索后台知识库 |
+| `ask_usage` | 读 | 否 | 回答「后台怎么操作」类问题 |
+| `create_product` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+| `update_product` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+| `deactivate_product` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，置 `archived` |
+| `upload_product_image` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，给已有商品追加图片 |
+| `add_product_to_sales_channel` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，把商品加入销售渠道使其在前端可见 |
+| `create_product_content` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，写商品详情页富内容块（hero/richtext/image_gallery/video/faq/specs）|
+| `get_product_content` | 读 | 否 | 读取某商品某语言的富内容块 |
+| `create_stock_location` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+| `update_inventory_level` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+
+## 各工具参数与说明
+
+### 读 —— 商品
+- **`list_products`**：查询商品列表。
+  - `q`（string，可选）关键词；`status`（enum：`draft|published|proposed|rejected|archived`，可选）状态过滤；`handle`（string，可选）；`limit`（int 1–100，默认 20）。
+- **`get_product`**：按商品 id 或 handle 获取详情。
+  - `id_or_handle`（string，**必填**）。
+
+### 读 —— 仓库与库存
+- **`list_stock_locations`**：列出仓库（StockLocation）。
+  - `q`（string，可选）按名称过滤；`limit`（int 1–100，默认 50）。
+- **`get_inventory_levels`**：列出某仓库下的库存条目及库存水平。
+  - `location_id`（string，**必填**）；`q`（string，可选）；`limit`（int 1–100，默认 50）。
+
+### 读 —— 订单 / 履约 / 退货
+- **`list_orders`**：查询订单列表。
+  - `q`（string，可选）；`status`（string，可选）；`limit`（int 1–100，默认 20）。
+- **`get_order`**：按订单 id 或 `display_id` 获取详情。
+  - `id`（string，**必填**）。
+- **`list_warehouse_tasks`**：查询仓库作业任务（自定义端点 `/admin/warehouse-tasks`）。
+  - `order_id`（string，可选）；`stage`（string，可选）；`limit`（int 1–200，默认 200）。
+- **`list_return_requests`**：查询退货/售后请求（自定义端点 `/admin/return-requests`）。
+  - `status`（string，可选）；`limit`（int 1–100，默认 50）。
+
+### 读 —— 后台知识问答
+- **`search_docs`**：在知识库（docs）中检索相关段落，返回文件、章节与摘要。
+  - `query`（string，**必填**）；`limit`（int 1–20，默认 5）。
+- **`ask_usage`**：回答「后台怎么操作」类问题，返回最相关段落与出处文件。
+  - `question`（string，**必填**）；`limit`（int 1–10，默认 5）。若搜不到，提示运营换关键词或查后台手册。
+
+### 写 —— 商品
+- **`create_product`**：新增商品。
+  - `title`（string，**必填**）；`handle`（string，可选，缺省由 title 归一化）；`status`（enum，默认 `draft`）；`subtitle`（可选）；`description`（可选）；`price`（number ≥0，主货币单位，**切勿 ×100**）；`currency_code`（默认 `MYR`）；`translations`（`record<locale,{title?,description?}>`，建议覆盖 `en/zh/ms/id`）；`images`（string[]，可选，本地图片路径或图片 URL，工具自动上传并挂接）；`sku`（string，可选，写入默认变体 SKU）；`metadata`（`record<string,string>`，可选，存规格参数/来源链接等任意键值）；`confirm`（bool，默认 false）；`acknowledge_missing_languages`（bool，默认 false）。
+  - 行为：`confirm=false` 返回预览（含缺语言清单）；`confirm=true` 才真正创建；缺语言时须同时 `acknowledge_missing_languages=true`。创建时**自动**补上 Medusa v2 必需的 `options`（单一 Default）、把图片上传到文件服务并挂接、把 `sku` 写入默认变体、把 `translations` 写入 v2.21 专用的 `/admin/translations/batch` 端点。
+- **`update_product`**：修改商品字段（标题/handle/状态/描述/多语言）。
+  - `id`（string，**必填**）；`title`/`handle`/`status`/`subtitle`/`description`/`translations`（均可选）；`confirm`（默认 false）。`confirm=false` 返回预览。
+- **`deactivate_product`**：下架商品（status 置 `archived`）。
+  - `id`（string，**必填**）；`confirm`（默认 false）。`confirm=false` 返回预览。
+- **`upload_product_image`**：给**已存在**的商品追加图片（与已有图片合并，不覆盖）。
+  - `product_id`（string，**必填**）；`images`（string[]，本地图片路径或图片 URL）；`confirm`（默认 false）。`confirm=false` 仅预览；`confirm=true` 才上传并挂接。
+- **`add_product_to_sales_channel`**：把商品加入销售渠道，使其在前端商城可见。
+  - `product_ids`（string[]，**必填**，商品 id 列表）；`channel_id`（string，可选，省略则取第一个启用渠道）；`confirm`（默认 false）。`confirm=false` 仅预览。
+- **`get_product_content`**：读取商品详情页富内容块。
+  - `product_id`（string，**必填**）；`locale`（`en-US` / `zh-CN` / `ms-MY` / `id-ID`，默认 `en-US`）；`status`（`draft` / `published`，默认 `published`）。返回 `{ product_content: { id, product_id, locale, status, blocks(已解析数组) } | null }`。
+- **`create_product_content`**：创建/更新商品详情页富内容块（按 `product_id` + `locale` upsert）。**这是填充详情页主体内容的工具**——只填 `description` 详情页大块区域仍是空白。
+  - `product_id`（string，**必填**）；`locale`（区域码，默认 `en-US`，见硬规则 7）；`status`（默认 `published`）；`blocks`（ContentBlock[]，**必填**）；`confirm`（默认 false）。
+  - 区块 `type` 与 `data`：
+    - `richtext`：`data.{ html }`（直接渲染 HTML，可含 `<p>/<h2>/<ul>`）
+    - `image_gallery`：`data.{ images:string[], caption? }`
+    - `hero`：`data.{ image?, title?, subtitle? }`
+    - `video`：`data.{ url, poster? }`（支持 YouTube）
+    - `faq`：`data.{ items: {question,answer}[] }`
+    - `specs`：`data.{ rows: {label,value}[] }`
+  - `confirm=false` 返回预览（含块数量与类型）；`confirm=true` 才写入。
+
+### 写 —— 仓库与库存
+- **`create_stock_location`**：新增仓库（StockLocation）。
+  - `name`（string，**必填**）；`address`（可选：`{address_1?,address_2?,city?,country_code?,province?,postal_code?,phone?}`）；`metadata`（`record<string,string>`，可选）；`confirm`（默认 false）。
+- **`update_inventory_level`**：修改某库存条目在指定仓库的库存数量（`stocked_quantity`）。
+  - `inventory_item_id`（string，**必填**）；`location_id`（string，**必填**）；`stocked_quantity`（int ≥0，**必填**）；`confirm`（默认 false）。底层走 `POST /admin/inventory-items/{id}/location-levels`，字段/端点以 Medusa 2.21 契约为准。
+
+## 推荐操作流程（SOP）
+
+**创建商品**
+1. 先收集：标题、handle（或告知由标题生成）、价格（主单位）、四语言标题、状态、图片、规格、详情页富文本内容（按语言）。
+2. 调用 `create_product`（`confirm=false`）→ 展示预览与「缺语言」告警。
+3. 提醒运营补全缺失语言；确认无误后调用 `create_product`（`confirm=true`，必要时 `acknowledge_missing_languages=true`）。
+4. **`add_product_to_sales_channel`（`confirm=true`）** → 把商品加入销售渠道，否则前端看不到。
+5. **`create_product_content`（`confirm=true`，逐语言 `en-US/zh-CN/ms-MY/id-ID`）** → 写详情页富内容块（richtext 描述 + specs 规格 + image_gallery 图集）。否则详情页主体空白。
+6. 把返回的新商品 id/handle 告知运营。
+
+**修改 / 下架商品**
+1. `get_product` 或 `list_products` 确认目标 id。
+2. `update_product` / `deactivate_product`（`confirm=false`）→ 展示预览。
+3. 确认后同名工具 `confirm=true` 执行。
+
+**调整库存**
+1. `list_stock_locations` 拿到 `location_id`；`get_inventory_levels` 拿到 `inventory_item_id`。
+2. `update_inventory_level`（`confirm=false`）→ 展示将写入的数量。
+3. 确认后 `confirm=true` 执行。
+
+**查询类**：直接调用对应读工具即可，无需 `confirm`。
+
+## 常见任务示例（运营怎么说 / 你怎么调）
+
+- 「下架 handle 为 `summer-serum` 的商品」→ `get_product`(id_or_handle=`summer-serum`) 取 id → `deactivate_product`(id, confirm=false 预览 → 确认后 confirm=true)。
+- 「给马来西亚仓的 A 商品加 50 件库存」→ `list_stock_locations` 找 MY 仓 → `get_inventory_levels`(location_id) 找 A 的 inventory_item_id → `update_inventory_level`(confirm=false 预览 → 确认后 confirm=true)。
+- 「查一下最近 10 个待发货订单」→ `list_orders`(status=`pending`, limit=10)。
+- 「后台怎么新建优惠券」→ `ask_usage`(question=`如何新建优惠券`)。
+- 「列出所有退货请求」→ `list_return_requests`()。
+- 「把这份抓取的 Lazada 商品录入：标题 DR.CYJ Hair Filler、价格 420 MYR、4 张本地图 `/Users/fire/temp/images/product_1..4.webp`、SKU `4820...`、规格存 metadata、并补全中/马来/印尼语翻译」→ 先整理数据，再 `create_product`（`confirm=false` 看预览含 images/sku/metadata/缺语言清单 → 确认后 `confirm=true`，必要时 `acknowledge_missing_languages=true`）。工具会自动上传图片、写 SKU/metadata、并把四语言简码翻译写入翻译端点。随后 `add_product_to_sales_channel`(`confirm=true`) 让前端可见，再 `create_product_content`(`locale=en-US/zh-CN/ms-MY/id-ID`, `confirm=true`) 逐语言写富内容块（richtext 描述 + specs 规格 + image_gallery 图集）。
+- 「让这个商品在前端能搜到」→ `get_product` 取 id → `add_product_to_sales_channel`(`product_ids=[id]`, `confirm=true`)。
+- 「补全某商品中文详情页内容」→ `create_product_content`(`product_id`, `locale=zh-CN`, `blocks=[{type:'richtext',data:{html:'...'}},{type:'specs',data:{rows:[...]}}]`, `confirm=true`)。可用 `get_product_content` 先核对现状。
+
+## 给运营的一次性安装配置
+
+agent 客户端（Codex / Claude Desktop / Cursor / Workbuddy / CodeBuddy 等）的 MCP 配置里加一条即可（机器只需 Node ≥ 18，无需 clone 仓库、无需 build）：
+
+```json
+{
+  "mcpServers": {
+    "derlux-admin": {
+      "command": "npx",
+      "args": ["-y", "@sea-ecommerce/admin-mcp-server"],
+      "env": {
+        "MEDUSA_BACKEND_URL": "https://admin.internal.derlux.com",
+        "DERLUX_ADMIN_EMAIL": "你的后台账号",
+        "DERLUX_ADMIN_PASSWORD": "你的密码"
+      }
+    }
+  }
+}
+```
+
+### 环境变量说明
+
+| 变量 | 必填 | 默认 | 说明 |
+|---|---|---|---|
+| `MEDUSA_BACKEND_URL` | 否 | `http://localhost:9000` | 后端地址（生产填内部域名）|
+| `DERLUX_ADMIN_EMAIL` | **是** | — | 后台管理员账号（须持 `csr`/`super_admin`）|
+| `DERLUX_ADMIN_PASSWORD` | **是** | — | 该账号密码 |
+| `DERLUX_AUTH_PATH` | 否 | `/auth/user/emailpass` | 登录端点 |
+| `DERLUX_SESSION_FILE` | 否 | `~/.derlux/mcp-session` | 会话持久化文件（权限 0600）|
+| `DERLUX_AUDIT_FILE` | 否 | `~/.derlux/mcp-audit.log` | 审计日志 |
+| `DERLUX_DOCS_DIR` | 否 | `./docs` | 问答知识源目录（npx 形态下通常留默认或指向本地 docs 副本）|
+| `DERLUX_REQUIRED_LOCALES` | 否 | `en,zh,ms,id` | 商品必须覆盖的语言 |
+
+## 已知限制 / 注意事项
+
+- 本 MCP **不改动任何数据库 schema**，仅复用现有 `/admin/*` 接口；运营动作本身按既有逻辑写库。
+- 登录走**用户账号**而非 API Key（现有 RBAC 依赖 `user.metadata.rbac_roles`）。
+- 金额以**主货币单位**存储（见上「硬规则 2」），不要换算成分。
+- **Medusa v2.21 差异（重要）**：
+  - 有变体就必须有 product options，工具已自动补一个 `Default` 选项，你无需关心。
+  - 商品创建/更新体**不接受 `translations` 字段**；翻译由工具自动走 `/admin/translations/batch`。`get_product` 默认字段不含 `translations` 关系，想核对翻译请用 `ask_usage` 或后台「多语言」面板，不要凭 `get_product` 返回为空就误判没写入。
+  - 图片走 `/admin/uploads` 上传后再挂到商品（无独立 `/admin/products/{id}/images` 端点）。
+- 库存写入的端点/字段以 Medusa 2.21 契约为准；自定义端点 `warehouse-tasks` / `return-requests` 为本项目扩展。
+- 文档问答（`search_docs` / `ask_usage`）依赖知识源目录；npx 形态下默认 `./docs`，若问不到相关内容，提示运营换关键词或查后台手册。
+- 用受限的 `csr` 账号即可完成日常运营；敏感动作由后端 RBAC 拦截。