sakthiveltofficial/dsh-shopify-plugins

dsh-shopify · 适用于 DeepSeek Harness 的 Shopify 插件

DSH-SHOPIFY — 适用于 DeepSeek Harness 的 Shopify 能力

License: MIT

一个完整、可用于生产环境的 DeepSeek Harness (DSH) 的 Shopify 插件。它为 agent 提供对 Shopify Admin REST + GraphQL API 的类型化、策略感知访问——210+ 个面向模型的工具，涵盖产品、订单、客户、集合、库存、履约、折扣、内容、元字段、webhook、主题、草稿订单、营销、礼品卡、账单、批量操作，以及一个通用的 GraphQL 逃生通道——并通过 DSH 的凭据服务解析 Admin API 访问令牌认证。

官方生态关键词： 这是一个 dsh-plugin——请为本仓库添加 dsh-plugin GitHub 主题。

来源说明： 工具面提炼自 Composio SHOPIFY 集成（407 个操作）。这 407 个中的大多数是已弃用的重复项和旧版 REST 别名；本插件为每项能力保留当前、未弃用的操作，并新增了 GraphQL 优先的接口（新产品模型、写入预设、批量操作），因此约 213 个工具即可覆盖相同的工作流，每个任务对应一个规范工具。

🤖 供 LLM 阅读的摘要

- 是什么： 一个单一的 Cordis 插件，通过 Shopify Admin API 为 DSH agent 扩展 210+ 个 shopify_ 工具。
- 安装： dsh plugin --profile web add github:sakthiveltofficial/dsh-shopify-plugins，然后向你的 profile patch（或 agent preset）添加一行——参见安装。
- 工具： shopify_list_products、shopify_get_order、shopify_list_orders、shopify_search_customers、shopify_set_inventory_level、shopify_create_fulfillment、shopify_create_price_rule、shopify_set_metafields、shopify_graphql_admin_execute、shopify_run_bulk_operation_query，以及另外 200 个——完整目录见工具表。
- 认证： Admin API 访问令牌（自定义应用）——无需 OAuth 重定向。凭据绝不存储在配置中：环境变量引用在每次操作时通过 ctx.credentials 解析（SHOPIFY_SHOP_DOMAIN + SHOPIFY_ADMIN_API_TOKEN，回退到 SHOPIFY_ACCESS_TOKEN）。
- 运行时要求： DeepSeek Harness、Node.js ≥ 20（全局 fetch），以及一个带有自定义应用的 Shopify 商店，该应用需具备你的工作流所需的 Admin API 权限范围。
- 安全性： 破坏性工具（shopify_delete_product、shopify_delete_order、shopify_delete_customer、shopify_delete_custom_collection、shopify_disable_gift_card 等）均有明确标注，并要求用户显式确认；agent 会被提示在不可逆操作前进行确认。
- 许可证： MIT。

✨ 功能

- 产品 — 列出/获取/创建/更新/删除产品和变体、产品图片、计数；GraphQL 产品模型预设（选项、媒体、发布）。
- 订单 — 获取/列出/计数/创建/更新/取消/关闭/删除订单、客户订单历史、交易、退款（计算 → 创建）、订单风险。
- 客户 — 列出/获取/搜索/计数/创建/更新/删除客户、地址（包括批量删除 + 设置默认）、账户激活 URL。
- 集合 — 自定义 + 智能集合的 CRUD 和计数、添加/移除产品（collects）、集合产品列表。
- 库存 — 地点、库存项目、库存水平（获取/设置/调整/连接/删除）。
- 履约 — 履约订单（获取、移动、暂停/释放、截止日期）、履约（创建/取消/跟踪）、履约事件、履约服务。
- 折扣 — 价格规则 CRUD + 计数、折扣码（CRUD、查找、计数、异步批处理）。
- 草稿订单 — 列出/获取/创建/更新/删除/完成、发送发票。
- 内容 — 博客、文章、评论、页面（完整 CRUD + 计数、审核）。
- 元字段和元对象 — 资源范围的元字段、metafieldsSet/metafieldsDelete（GraphQL）。
- Webhook — 列出/获取/创建/更新/删除/计数订阅 + GraphQL 预设。
- 主题 — 主题 CRUD、主题资源（获取/列出/更新插入/删除）。
- 营销 — 营销事件 CRUD、互动。
- 礼品卡 — 列出/获取/创建/更新/禁用/搜索。
- 重定向和脚本标签 — 完整 CRUD。
- 计费 — 应用订阅（创建/取消/更新行项目）、一次性应用费用。
- 商店和配置 — 商店详情（包括 iana_timezone）、政策、货币、配送区域、国家/省份、访问范围、GraphQL 商店查询。
- 强大工具 — shopify_graphql_admin_execute（任意 Admin GraphQL 文档）、shopify_graphql_write_operations（30 个精选变更预设）、批量查询操作（运行/获取/取消/列出/当前）。
- 弹性 — 对 429/5xx 进行有界指数退避、REST 桶感知自限流、结构化 ShopifyError 并保留 HTTP 状态 + Shopify 响应体、GraphQL userErrors 始终呈现。

🚀 安装

先决条件

DeepSeek Harness 正在运行（一个配置文件，例如默认的 web 配置文件）
Node.js >= 20（宿主机的 Node — 插件在进程内运行）
一个 Shopify 商店 + 一个带有 Admin API 访问令牌的自定义应用（参见“配置凭据”）

1. 从你的 GitHub 仓库安装包

dsh plugin --profile web add github:sakthiveltofficial/dsh-shopify-plugins

这会将 @shopify/dsh-shopify 插件包安装到配置文件中（仓库根目录就是包 — 无需构建步骤）。

2. 在组合中挂载插件

该插件不发布任何服务 — 它只将工具注册到宿主 tools 注册表中 — 因此它作为普通松散行挂载，不需要 isolate 领域。

选项 A — 配置文件补丁（宿主平面，工具对每个代理可见）。 追加到你的配置文件的 cordis.patch.yml：

- insert:
- id: shopify
name: '@shopify/dsh-shopify'
config:
shopDomainRef: SHOPIFY_SHOP_DOMAIN
accessTokenRef: SHOPIFY_ADMIN_API_TOKEN
apiVersion: '2025-01'
timeoutMs: 30000

选项 B — agent 预设（仅对该预设上的 agent 提供工具）。 将该行添加到预设的 agent.cordis.yml 中（参见 examples/agent.cordis.yml）：
yaml
- id: shopify
name: '@shopify/dsh-shopify'
config:
shopDomainRef: SHOPIFY_SHOP_DOMAIN
accessTokenRef: SHOPIFY_ADMIN_API_TOKEN

重启该 profile（或重启 DSH 进程）。

验证
sh
dsh --profile web --dump-config | grep -i shopify

然后询问 agent：“你有哪些 shopify 工具？”* —— 它应当列出 shopify_ 工具（总计 210+ 个）。

🔑 配置凭据（Admin API 访问令牌）

Shopify 的 Admin API 使用按店铺发放的访问令牌进行身份验证，该令牌通过 X-Shopify-Access-Token 请求头发送——插件本身无需 OAuth 重定向。配置中仅包含环境变量引用，绝不包含字面令牌；值在每次操作时通过 DSH 的凭据服务解析（进程环境变量 → provider 存储 → .env）。

| 环境变量 | 用途 |
| --- | --- |
| SHOPIFY_SHOP_DOMAIN | 你的店铺域名，例如 my-store.myshopify.com（或仅 my-store）——必填 |
| SHOPIFY_ADMIN_API_TOKEN | 来自你的自定义应用的 Admin API 访问令牌——必填 |
| SHOPIFY_ACCESS_TOKEN | 同一令牌的备用名称（当主引用未设置时读取） |

Shopify 设置（4 个步骤，约 5 分钟）

1. 创建自定义应用： Shopify 管理后台 → Settings → Apps and sales channels → Develop apps → Create an app（或者，如果你的店铺有开发者工具，则在 Develop apps* 下选择 Create an app）。为其命名（例如 dsh-agent），然后点击 Create app。
2. 授予 Admin API 权限范围： 在应用中，点击 Configure Admin API scopes，并选择你的工作流所需的范围，例如：

read_products, write_products, read_orders, write_orders, read_customers,
write_customers, read_inventory, write_inventory, read_locations,
read_fulfillments, write_fulfillments, read_price_rules, write_price_rules,
read_content, write_content, read_metafields, write_metafields, read_themes,
write_themes, read_webhooks, write_webhooks, read_marketing_events,
write_marketing_events, read_gift_cards, write_gift_cards, read_analytics,
read_shop_discounts, write_discounts, read_draft_orders, write_draft_orders,
read_script_tags, write_script_tags, read_redirects, write_redirects,
read_all_orders (if you need order data older than 60 days or beyond default)
然后点击 Install app 并确认。
3. 复制 Admin API 访问令牌： 返回应用页面 → Admin API access token → Install app → 复制令牌。它看起来像 shpat_...。
4. 导出它们（或为相同名称配置 ctx.credentials 来源）：
sh
export SHOPIFY_SHOP_DOMAIN='my-store.myshopify.com'
export SHOPIFY_ADMIN_API_TOKEN='shpat_xxxxxxxxxxxxxxxxxxxx'
订单读取时出现 403？ 令牌必须包含 read_all_orders（写入操作还需 write_orders）——参见故障排除。

🧠 Agent 使用约定（即“技能”）

当插件挂载时，这些约定会被注入到 agent 的系统提示中；它们也是任何使用 Shopify 提示 agent 的人的基本规则：

- ID： REST 工具接受数字资源 ID（例如 product_id: '8313381814466'）；GraphQL 工具接受 GID（gid://shopify/Product/123）。跨用时，通过 GraphQL 的 legacyResourceId 进行转换。
- 分页： REST 列表工具返回 next_page_info——用 page_info 循环，直到它为 null；切勿静默截断。GraphQL 列表：请求 pageInfo { hasNextPage endCursor }，并用 after 进行分页。
- 速率限制： REST 桶约为每分钟 40 次 GET / 约 20 次写入调用；GraphQL 约为每分钟 1000 个成本点（约每秒补充 50 个）。遇到 429 / THROTTLED / X-Shopify-Shop-Api-Call-Limit 桶已满时，进行退避（1s、2s、4s）并降低并发。优先使用 limit: 50–100，而不是巨大的分页。
- userErrors： mutation 会在 payload 的 userErrors 数组中返回验证失败，且 HTTP 状态码为 200——务必检查它们。顶层 GraphQL errors 也是验证失败，而非传输失败。
- 已弃用的 REST 端点： REST Admin API 是旧版；对于新的产品模型工作（选项、媒体、发布）以及 REST 未暴露的任何内容，优先使用 shopify_graphql_ 工具。
- 退款： 始终先调用 shopify_calculate_refund，然后在 shopify_create_refund 之前将交易 kind 从 'suggested_refund' 改为 'refund'。
- 金额： 金额是十进制字符串（'19.99'）；始终传入店铺货币（来自 shopify_get_shop_details / shopify_query_shop），切勿假设为美元。
- 时区： Shopify 以 UTC 存储时间戳，但日期过滤器按店铺的本地时区（来自 shopify_get_shop_details 的 iana_timezone）进行计算——请调整边界日期的查询。
- 破坏性操作（shopify_delete_、shopify_disable_gift_card）不可逆：执行前请与用户确认。

🧰 工具目录

所有工具都以 shopify_ 为前缀，并按领域分组：

| 模块 | 工具 |
| --- | --- |
| products（15） | list_products、get_product、create_product、update_product、delete_product、count_products、list_product_variants、get_product_variant、create_product_variant、update_product_variant、delete_product_variant、list_product_images、create_product_image、update_product_image、delete_product_image |
| collections（15） | list_custom_collections、get_custom_collection、create_custom_collection、update_custom_collection、delete_custom_collection、count_custom_collections、list_smart_collections、get_smart_collection、create_smart_collection、update_smart_collection、delete_smart_collection、count_smart_collections、add_product_to_custom_collection、get_collects、remove_product_from_collection |
| orders (19) | get_order、list_orders、count_orders、create_order、update_order、cancel_order、close_order、reopen_closed_order、delete_order、get_customer_orders、list_transactions、get_transaction、create_order_transaction、calculate_refund、create_refund、list_order_refunds、get_order_refund_by_id、get_order_risks、create_order_risk |
| draft_orders (7) | list_draft_orders、get_draft_order、create_draft_order、update_draft_order、delete_draft_order、complete_draft_order、send_draft_order_invoice |
| customers (15) | list_customers、get_customer、search_customers、count_customers、create_customer、update_customer、delete_customer、get_customer_addresses、get_customer_address、create_customer_address、update_customer_address、delete_customer_address、set_default_customer_address、bulk_delete_customer_addresses、create_customer_account_activation_url |
| shop (9) | get_shop_details、get_policies、list_currencies、get_shipping_zones、list_countries、get_country、get_country_provinces、get_access_scopes、query_shop |
| inventory (12) | list_locations、get_location、get_locations_count、get_inventory_items、get_inventory_item、update_inventory_item、get_inventory_levels、get_inventory_levels_for_location、set_inventory_level、adjust_inventory_level、connect_inventory_level、delete_inventory_level |
| fulfillments (15) | get_fulfillment_orders_for_order、get_fulfillment_order、get_fulfillment_order_locations_for_move、move_fulfillment_order、apply_fulfillment_hold、release_fulfillment_hold、set_fulfillment_orders_deadline、create_fulfillment、cancel_fulfillment、update_fulfillment_tracking、list_order_fulfillments、get_fulfillment、list_fulfillment_events、create_fulfillment_event、list_fulfillment_services |
| discounts (16) | list_price_rules、get_price_rule、create_price_rule、update_price_rule、delete_price_rule、count_price_rules、list_discount_codes、get_discount_code、create_discount_code、update_discount_code、delete_discount_code、lookup_discount_code、count_discount_codes、create_discount_code_batch、get_discount_code_batch_job、get_batch_discount_codes |
| content (25) | list_blogs、get_blog、create_blog、update_blog、delete_blog、count_blogs、list_blog_articles、get_article、create_article、update_article、delete_article、count_articles、list_article_tags、list_comments、create_article_comment、approve_comment、remove_comment、mark_comment_as_spam、mark_comment_as_not_spam、list_pages、get_page、create_page、update_page、delete_page、count_pages |
| metafields (8) | get_metafields、get_metafield、create_metafield、update_metafield、delete_metafield、get_resource_metafields、set_metafields、bulk_delete_metafields |
| webhooks (7) | list_webhook_subscriptions、get_webhook_subscription、create_webhook_subscription、update_webhook_subscription、delete_webhook_subscription、count_webhook_subscriptions、graphql_webhooks |
| themes (9) | list_themes、get_theme、create_theme、update_theme、delete_theme、list_theme_assets、get_theme_asset、create_or_update_theme_asset、delete_theme_asset |
| marketing (6) | list_marketing_events、get_marketing_event、create_marketing_event、update_marketing_event、delete_marketing_event、create_marketing_engagements |
| gift_cards (6) | list_gift_cards、get_gift_card、create_gift_card、update_gift_card、disable_gift_card、search_gift_cards |
| redirects (5) | list_redirects、get_redirect、create_redirect、update_redirect、delete_redirect |
| script_tags (5) | list_script_tags、get_script_tag、create_script_tag、update_script_tag、delete_script_tag |
| billing (6) | create_app_subscription、cancel_app_subscription、update_app_subscription_line_item、create_one_time_charge、get_application_charges、get_application_charge_by_id |
| misc (6) | create_resource_feedback、list_resource_feedbacks、list_storefront_access_tokens、create_storefront_access_token、delete_storefront_access_token、trigger_shopify_flow |
| graphql (2) | graphql_admin_execute、graphql_write_operations |
| bulk (5) | run_bulk_operation_query、get_bulk_operation、list_bulk_operations、cancel_bulk_operation、query_current_bulk_operation |

🛟 故障排查

| 症状 | 原因 / 修复方法 |
| --- | --- |
| SHOPIFY_AUTH_FAILED | SHOPIFY_SHOP_DOMAIN 或 SHOPIFY_ADMIN_API_TOKEN 未设置，或令牌已被撤销。重新导出并重启；确认自定义应用仍处于已安装状态。 |
| 读取/更新订单时出现 403 | 令牌缺少 read_all_orders / write_orders 权限。使用这些权限范围重新创建令牌（超出默认 60 天窗口需要 read_all_orders）。 |
| 429 / SHOPIFY_RATE_LIMITED | REST 桶（约 40/分钟）或 GraphQL 成本（约 1000 点/分钟）已耗尽。退避（1 秒、2 秒、4 秒），缩小分页大小，降低并发。插件在桶使用率 ≥85% 时会自动限流。 |
| 变更“成功”但没有任何变化 | 验证失败会以 HTTP 200 返回在 userErrors 中——始终检查返回的 userErrors 数组。 |
| 产品/变体 422 错误 | SKU 重复、handle 无效，或变体负载过于复杂。从最小字段（title、price）开始，逐步添加。 |
| 客户创建“失败” | 邮箱重复等会返回 HTTP 422 并带有 errors 对象——从抛出错误的 body 中读取它。 |
| 使用 OAuth 时出现“App not found” | 该插件使用 Admin API 令牌（不需要 OAuth 应用）。如果你改用 OAuth 安装的应用令牌，请确保该应用已安装到店铺。 |
| 受保护的客户数据（地址、电子邮件） | Shopify 对某些客户字段要求获得 受保护的客户数据 批准——当你的应用需要时，请在合作伙伴仪表板中申请。 |

🧪 开发
sh
对每个模块进行语法检查
node --check lib/index.js && for f in lib/tools/*.js; do node --check "$f"; done

加载 + 冒烟测试（无网络；使用打桩的 fetch）
node test/load-test.mjs

该插件是纯 ESM JavaScript——无需构建步骤。docs/DEVELOPER.md 记录了用于添加新工具的模块契约。

📄 许可证

MIT