optimize-shopify-alt-text

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Optimize Shopify Alt Text

优化Shopify图片Alt文本

Non-Negotiables

不可妥协的规则

Use Shopify Admin GraphQL only after verifying access with the bundled helper.
Preview proposed changes before asking for confirmation. Execute writes only after explicit user approval.
Never publish content, edit product copy, replace images, delete files, or change article body text other than inline image
```
alt
```
attributes.
Do not trust a model's self-report about image capability. Test whether the active model can inspect a local image before using the multimodal path.
If image understanding is unavailable, use context-only fallback and mark lower confidence. Do not pretend the model inspected pixels.
Downloading an image is not image inspection. The agent must actually open, attach, or view the local image through the host model's native image input or image-view tool before claiming visual understanding.
Never generate a
```
vision
```
alt text from product title, collection title, article title, filename, URL, or surrounding context alone. That is context-only fallback.
Do not create process notes, summary documents, ad hoc code files, or persistent JSON files in the user's working folder. Use stdout/stdin or the operating system temp directory, then delete temp files immediately.
Keep alt text concise: target 60-120 characters, keep 125 characters or fewer by default, and never exceed Shopify's 512-character maximum.
Prefer
```
fileUpdate
```
for product
```
MediaImage
```
alt text.
```
productUpdateMedia
```
is deprecated.
Preserve existing image URLs when updating collection featured images and article featured images.
Keep the user's working folder clean. The only expected local config file is
```
skill-hub.env
```
; all temporary downloaded images or machine-readable plans must live outside the working folder or be streamed through stdin, then be deleted immediately.
Never print or store access tokens, client secrets, short-lived tokens, session cookies, or real merchant data in public files.

Read

references/alt-text-rules.md

before generating or reviewing alt text candidates.

仅在通过捆绑助手验证访问权限后，才可使用Shopify Admin GraphQL。
在请求确认前预览拟议变更，仅在获得用户明确批准后执行写入操作。
除内联图片的
```
alt
```
属性外，不得发布内容、编辑产品文案、替换图片、删除文件或修改文章正文。
不要信任模型对图像能力的自我报告，在使用多模态路径前，需测试当前模型是否能识别本地图像。
如果无法进行图像识别，则采用仅上下文的备选方案并标记为低可信度，不得谎称模型已识别图像像素。
下载图像不等于图像识别，Agent必须通过宿主模型的原生图像输入或图像查看工具实际打开、附加或查看本地图像，才可声称具备视觉识别能力。
不得仅通过产品标题、集合标题、文章标题、文件名、URL或周边上下文生成
```
vision
```
类型的alt文本，此类情况属于仅上下文的备选方案。
不得在用户工作文件夹中创建流程笔记、摘要文档、临时代码文件或持久化JSON文件，使用stdout/stdin或操作系统临时目录，然后立即删除临时文件。
保持alt文本简洁：目标长度为60-120字符，默认不超过125字符，绝对不超过Shopify规定的512字符上限。
优先使用
```
fileUpdate
```
更新产品
```
MediaImage
```
的alt文本，
```
productUpdateMedia
```
已被弃用。
更新集合特色图和文章特色图时，保留现有图像URL。
保持用户工作文件夹整洁，唯一允许存在的本地配置文件为
```
skill-hub.env
```
；所有临时下载的图像或机器可读计划必须存储在工作文件夹之外，或通过stdin传输，然后立即删除。
不得在公共文件中打印或存储访问令牌、客户端密钥、短期令牌、会话Cookie或真实商家数据。

生成或审核alt文本候选前，请阅读

references/alt-text-rules.md

。

Beginner Onboarding First

先完成新手入门

Before asking any setup question, inspect the local environment first:

Identify the current working directory from the active terminal or host environment. This is the folder the user is working in, not the installed skill folder.
Look for the exact filename
```
skill-hub.env
```
in that current directory. Use whatever direct file check, directory listing, or direct file-read tool is reliable in the current host.
Do not rely on a broad search or glob result as the only evidence that the file is missing. If a search says "not found" but the user, file explorer, terminal, or direct path suggests the file exists, re-check by listing the current directory or reading the exact
```
skill-hub.env
```
path.
If it exists, read only the variable names and whether required values are present. Do not print secrets.

SKILL_HUB_SHOPIFY_ACCESS_METHOD

admin_custom_app

and the store domain plus Admin API token are present, run

connection-check

SKILL_HUB_SHOPIFY_ACCESS_METHOD

dev_dashboard_app

and the

.myshopify.com

store domain plus Client ID are present, run

connection-check

If
```
connection-check
```
succeeds, continue directly to scan and vision probe. Do not ask where the app was created.
If the user says "already configured", "B is configured", or similar, treat that as a request to inspect
```
skill-hub.env
```
, not as an A/B answer.

Ask the setup question only when

skill-hub.env

is missing, incomplete, placeholder-only, or the access method cannot be determined:

text

Where did you create your Shopify app?

A - Shopify store Settings custom app (Legacy Custom App)
B - Dev Dashboard app

Then create or update one private shared file in the current working directory:

text

skill-hub.env

Immediately ensure

.gitignore

contains

skill-hub.env

. Do not ask the user to create the env file or update

.gitignore

manually.

在询问任何设置问题前，先检查本地环境：

从活动终端或宿主环境识别当前工作目录，即用户正在操作的文件夹，而非已安装技能的文件夹。
在该当前目录中查找确切文件名
```
skill-hub.env
```
，使用当前宿主环境中可靠的直接文件检查、目录列表或直接文件读取工具。
不要仅依赖宽泛搜索或通配符结果作为文件缺失的唯一证据。如果搜索显示“未找到”，但用户、文件资源管理器、终端或直接路径表明文件存在，请重新检查当前目录列表或读取确切的
```
skill-hub.env
```
路径。
如果文件存在，仅读取变量名称及所需值是否存在，不得打印机密信息。

如果

SKILL_HUB_SHOPIFY_ACCESS_METHOD

为

admin_custom_app

且商店域名和Admin API令牌已存在，运行

connection-check

。

如果

SKILL_HUB_SHOPIFY_ACCESS_METHOD

为

dev_dashboard_app

且

.myshopify.com

商店域名和客户端ID已存在，运行

connection-check

。

如果
```
connection-check
```
成功，直接继续进行扫描和视觉探测，无需询问应用创建位置。
如果用户表示“已配置”“B已配置”或类似表述，将其视为检查
```
skill-hub.env
```
的请求，而非A/B选择题的答案。

仅当

skill-hub.env

缺失、不完整、仅含占位符或无法确定访问方式时，才询问设置问题：

text

您在哪里创建的Shopify应用？

A - Shopify商店设置自定义应用（传统自定义应用）
B - 开发者仪表板应用

然后在当前工作目录中创建或更新一个私有共享文件：

text

skill-hub.env

立即确保

.gitignore

包含

skill-hub.env

，无需让用户手动创建环境文件或更新

.gitignore

。

Path A: Shopify Store Settings Custom App (Legacy Custom App)

路径A：Shopify商店设置自定义应用（传统自定义应用）

Create the env file with:

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method admin_custom_app --env skill-hub.env

Ask the user to fill only:

SKILL_HUB_SHOPIFY_STORE_DOMAIN

: the store domain the merchant knows, such as

example.com

example.myshopify.com

```
SKILL_HUB_SHOPIFY_ADMIN_API_ACCESS_TOKEN
```
: the Admin API token from the Shopify custom app.

Required scopes:

text

read_products,write_products,read_content,write_content,read_files,write_files

使用以下命令创建环境文件：

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method admin_custom_app --env skill-hub.env

仅要求用户填写以下内容：

SKILL_HUB_SHOPIFY_STORE_DOMAIN

：商家已知的商店域名，例如

example.com

或

example.myshopify.com

。

```
SKILL_HUB_SHOPIFY_ADMIN_API_ACCESS_TOKEN
```
：Shopify自定义应用的Admin API令牌。

所需权限范围：

text

read_products,write_products,read_content,write_content,read_files,write_files

Path B: Dev Dashboard App

路径B：开发者仪表板应用

Create the env file with:

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method dev_dashboard_app --env skill-hub.env

Ask the user to fill only:

SKILL_HUB_SHOPIFY_STORE_DOMAIN

: the store's exact

.myshopify.com

domain.

```
SKILL_HUB_SHOPIFY_CLIENT_ID
```
: the app Client ID from Dev Dashboard settings. This is used for Shopify CLI config link and deploy.

Do not ask for the Client secret for this workflow unless a future helper explicitly implements client credential token exchange. The bundled helper uses Shopify CLI store authorization after deploy.

Check Node.js, npm, and Shopify CLI:

powershell

node -v
npm -v
shopify version
shopify store --help

If Shopify CLI is missing or too old for

shopify store

, run:

powershell

npm install -g @shopify/cli@latest

Then configure scopes through Shopify CLI. Do not ask the user to manually enter scopes in Dev Dashboard.

Do not run

shopify store list

shopify auth status

; these are not valid diagnostics for this workflow in current Shopify CLI. Do not repeatedly run manual

shopify store execute

commands for scan or write work.

powershell

$tmp = Join-Path $env:TEMP ("skill-hub-shopify-app-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $tmp | Out-Null
shopify app config link --client-id <client-id> --path $tmp --no-color

Edit only

$tmp\shopify.app.toml

toml

[access_scopes]
scopes = "read_products,write_products,read_content,write_content,read_files,write_files"

Then run:

powershell

shopify app config validate --path $tmp --no-color
shopify app deploy --client-id <client-id> --path $tmp --allow-updates --no-color

After deployment, do not send the user to Dev Dashboard to look for a manual approval button. Instead, run Shopify CLI store authorization with the required scopes. Tell the user before running it: "A Shopify permission authorization page may open next. Please review the scopes and click authorize."

powershell

shopify store auth --store <store>.myshopify.com --scopes read_products,write_products,read_content,write_content,read_files,write_files --json --no-color

Verify after the browser authorization:

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs connection-check --env skill-hub.env

Always remove the temporary CLI app config directory after setup succeeds or fails.

使用以下命令创建环境文件：

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method dev_dashboard_app --env skill-hub.env

仅要求用户填写以下内容：

SKILL_HUB_SHOPIFY_STORE_DOMAIN

：商店的确切

.myshopify.com

域名。

```
SKILL_HUB_SHOPIFY_CLIENT_ID
```
：开发者仪表板设置中的应用客户端ID，用于Shopify CLI配置链接和部署。

除非未来助手明确实现客户端凭证令牌交换，否则在此工作流中不要询问客户端密钥。捆绑助手在部署后使用Shopify CLI商店授权。

检查Node.js、npm和Shopify CLI：

powershell

node -v
npm -v
shopify version
shopify store --help

如果Shopify CLI缺失或版本过旧无法支持

shopify store

，运行：

powershell

npm install -g @shopify/cli@latest

然后通过Shopify CLI配置权限范围，无需让用户在开发者仪表板中手动输入权限范围。

不要运行

shopify store list

或

shopify auth status

，这些命令在当前Shopify CLI中不适用于此工作流的诊断。不要反复运行手动

shopify store execute

命令进行扫描或写入操作。

powershell

$tmp = Join-Path $env:TEMP ("skill-hub-shopify-app-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $tmp | Out-Null
shopify app config link --client-id <client-id> --path $tmp --no-color

仅编辑

$tmp\shopify.app.toml

：

toml

[access_scopes]
scopes = "read_products,write_products,read_content,write_content,read_files,write_files"

然后运行：

powershell

shopify app config validate --path $tmp --no-color
shopify app deploy --client-id <client-id> --path $tmp --allow-updates --no-color

部署完成后，不要让用户前往开发者仪表板寻找手动批准按钮，而是使用所需权限范围运行Shopify CLI商店授权。运行前告知用户：“接下来可能会打开Shopify权限授权页面，请查看权限范围并点击授权。”

powershell

shopify store auth --store <store>.myshopify.com --scopes read_products,write_products,read_content,write_content,read_files,write_files --json --no-color

浏览器授权完成后进行验证：

powershell

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs connection-check --env skill-hub.env

无论设置成功或失败，始终删除临时CLI应用配置目录。

Shopify Surfaces

Shopify扫描范围

This skill scans and writes only these surfaces:

Product media images: read products and
```
MediaImage
```
; write alt text with
```
fileUpdate
```
.
Collection featured images: read
```
collection.image
```
; write
```
collectionUpdate(input.image.altText)
```
while preserving the current image URL.
Article featured images: read
```
article.image
```
; write
```
articleUpdate(article.image.altText)
```
while preserving the current image URL.
Article inline images: read
```
article.body
```
; update only
```
<img alt="...">
```
attributes inside the body HTML with
```
articleUpdate(article.body)
```
.

本技能仅扫描和写入以下范围：

产品媒体图：读取产品和
```
MediaImage
```
；使用
```
fileUpdate
```
写入alt文本。
集合特色图：读取
```
collection.image
```
；在保留当前图像URL的同时，写入
```
collectionUpdate(input.image.altText)
```
。
文章特色图：读取
```
article.image
```
；在保留当前图像URL的同时，写入
```
articleUpdate(article.image.altText)
```
。
文章内联图：读取
```
article.body
```
；使用
```
articleUpdate(article.body)
```
仅更新正文HTML中的
```
<img alt="...">
```
属性。

Vision Capability Probe

视觉能力探测

Before generating multimodal alt text, test the active model on a known local image.

The probe must force real image input. Use the host environment's native image mechanism, for example a local image attachment, a file-view image tool, or another explicit multimodal image input. A shell command such as

curl

dir

Get-Item

, metadata extraction, OCR library, filename parsing, or product-title lookup does not count.

Use a prompt like:

text

Tell me what is visible in this local image: <absolute image path>.
Answer from the image pixels only. Do not use OCR libraries, filenames, metadata, surrounding text, or guesses.
Return VISION_UNAVAILABLE if you cannot inspect the image directly.

Evaluate the answer against expected visual facts for the test image. Do not ask "are you multimodal?" and do not trust a yes/no self-report.

The answer must include at least three visual facts that are not inferable from filename, URL, product title, collection title, article title, or nearby text. Examples: object type, color, layout, background, visible text, material, shape, or scene. If the answer only restates Shopify context, product names, filenames, or generic ecommerce assumptions, the probe failed.

Before using context-only fallback, the agent must download at least one real image from the current Shopify scan, open the local file with the host-native image input path, and report at least three pixel-derived facts. If that succeeds, use Strategy A for every reasonably downloadable image in the current batch. If it fails, report exactly which layer failed: download, local image open, or pixel interpretation.

If the active model passes the probe, use Strategy A. If image download or host-native image opening fails, use Strategy B only for the affected item or batch.

生成多模态alt文本前，使用已知本地图像测试当前模型。

探测必须强制使用真实图像输入，使用宿主环境的原生图像机制，例如本地图像附件、文件查看图像工具或其他明确的多模态图像输入。

curl

、

dir

、

Get-Item

等shell命令、元数据提取、OCR库、文件名解析或产品标题查询均不算作图像识别。

使用如下提示词：

text

告诉我这张本地图像中的内容：<绝对图像路径>。
仅根据图像像素回答，不得使用OCR库、文件名、元数据、周边文本或猜测。
如果无法直接识别图像，请返回VISION_UNAVAILABLE。

将答案与测试图像的预期视觉事实进行对比。不要询问“您是否支持多模态？”，也不要信任是/否的自我报告。

答案必须包含至少三个无法从文件名、URL、产品标题、集合标题、文章标题或周边文本推断出的视觉事实，例如：物体类型、颜色、布局、背景、可见文本、材质、形状或场景。如果答案仅重述Shopify上下文、产品名称、文件名或通用电商假设，则探测失败。

在使用仅上下文的备选方案前，Agent必须从当前Shopify扫描中下载至少一张真实图像，通过宿主原生图像输入路径打开本地文件，并报告至少三个基于像素的事实。如果成功，则对当前批次中所有可合理下载的图像使用策略A；如果失败，则准确报告哪一层失败：下载、本地图像打开或像素解读。

如果当前模型通过探测，使用策略A；如果图像下载或宿主原生图像打开失败，则对受影响的项目或批次仅使用策略B。

Strategy A: Multimodal Image Understanding

策略A：多模态图像理解

Scan Shopify images.
Download only the current batch of image URLs to a temporary folder outside the working directory.
Open or attach each local image through the model's real image input before generating any visual description.
Ask for a visual description first, not the final alt text.
Require the visual description to include concrete pixel-derived facts. If the model mentions only product context, reject the result and retry with the actual image attached.
Generate final alt text from visual description plus Shopify page context.
Validate length, uniqueness, and confidence.
Delete downloaded images after the batch is reviewed.

If the model cannot inspect a downloaded image, mark that item as

vision_unavailable

and switch that item to context-only fallback.

Do not label an item

source: "vision"

unless the agent has actually inspected the downloaded/local image and can state pixel-derived evidence. If an item was inferred from title or fields, label it

source: "context_only"

even if an image URL was downloaded.

扫描Shopify图像。
仅将当前批次的图像URL下载到工作目录之外的临时文件夹。
在生成任何视觉描述前，通过模型的真实图像输入打开或附加每张本地图像。
先请求视觉描述，而非最终的alt文本。
要求视觉描述包含具体的基于像素的事实。如果模型仅提及产品上下文，则拒绝结果并重新尝试附加实际图像。
根据视觉描述和Shopify页面上下文生成最终alt文本。
验证长度、唯一性和可信度。
批次审核完成后删除下载的图像。

如果模型无法识别下载的图像，将该项目标记为

vision_unavailable

并切换为仅上下文的备选方案。

除非Agent实际识别了下载/本地图像并能陈述基于像素的证据，否则不得将项目标记为

source: "vision"

。如果项目是从标题或字段推断而来，即使已下载图像URL，也需标记为

source: "context_only"

。

Strategy B: Context-Only Fallback

策略B：仅上下文的备选方案

Use this when the active model cannot inspect images.

Generate candidates only from Shopify fields and nearby context. Mark each candidate with:

```
source: "context_only"
```
```
confidence: "high" | "medium" | "low"
```
```
reason
```

Context-only candidates are review-only by default. Do not mark context-only candidates as directly applicable with medium confidence. To apply a context-only candidate after explicit user approval, include

action: "approved_context_only"

in the apply plan.

当前模型无法识别图像时使用此策略。

仅从Shopify字段和周边上下文生成候选内容，并为每个候选标记：

```
source: "context_only"
```
```
confidence: "high" | "medium" | "low"
```
```
reason
```

仅上下文的候选内容默认仅用于审核，不得将中等可信度的仅上下文候选标记为直接适用。如果获得用户明确批准后应用仅上下文候选，需在应用计划中包含

action: "approved_context_only"

。

Required Order

必须遵循的步骤

Create or verify
```
skill-hub.env
```
.
Run Shopify connection check.
Run a full scan and inventory count before generating alt text.
Run
```
vision-sample
```
, open at least one downloaded local image through the host-native image input path, and decide Strategy A or Strategy B from pixel evidence.
Build a batch plan. Default to 20-50 images per batch depending on user tolerance and model context.
Generate alt text candidates for the first batch.
Validate each candidate against
```
references/alt-text-rules.md
```
.
Show a concise preview plan.
Ask for explicit approval.
Apply only approved changes with
```
--execute
```
.
Verify by rescanning or reading changed resources.
Clean up temporary images and any operating-system temp files. Do not leave process JSON, generated scripts, or summary documents in the working folder.

创建或验证
```
skill-hub.env
```
。
运行Shopify连接检查。
生成alt文本前，先进行全面扫描和库存统计。
运行
```
vision-sample
```
，通过宿主原生图像输入路径打开至少一张下载的本地图像，根据像素证据决定使用策略A还是策略B。
构建批次计划，默认根据用户容忍度和模型上下文，每批次处理20-50张图像。
为第一批次生成alt文本候选。
根据
```
references/alt-text-rules.md
```
验证每个候选。
显示简洁的预览计划。
请求明确批准。
使用
```
--execute
```
仅应用已批准的变更。
通过重新扫描或读取已变更资源进行验证。
清理临时图像和任何操作系统临时文件，不得在工作文件夹中留下流程JSON、生成的脚本或摘要文档。

Bundled Script

捆绑脚本

Use the bundled native Node.js helper. It uses only Node.js built-ins.

text

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method admin_custom_app --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method dev_dashboard_app --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs connection-check --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs scan --env skill-hub.env --page-size 50
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs vision-sample --env skill-hub.env --limit 3
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input -
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input - --execute

The

apply

command previews by default. Use

--execute

only after explicit user approval.

Do not use

shopify store execute

directly for scanning images or updating alt text, except for narrow troubleshooting. Direct terminal mutations are easy to run one image at a time, can stall in some IDE terminals, and bypass the helper's pagination, batching, duplicate checks, and cleanup rules. The helper internally uses Shopify CLI store auth when Path B is selected, runs Shopify CLI through its JavaScript entrypoint, uses query/output files, and cleans temporary CLI files.

The

vision-sample

command downloads 1-3 real Shopify images to an operating-system temp directory and prints their local paths. The agent must open those files with the host-native image input path, such as Read or an image-view tool, report at least 3 pixel-derived facts, and delete the temp folder after the probe.

使用捆绑的原生Node.js助手，它仅依赖Node.js内置模块。

text

node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method admin_custom_app --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs init-env --method dev_dashboard_app --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs connection-check --env skill-hub.env
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs scan --env skill-hub.env --page-size 50
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs vision-sample --env skill-hub.env --limit 3
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input -
node skills/optimize-shopify-alt-text/scripts/shopify-alt-text-admin.mjs apply --env skill-hub.env --input - --execute

apply

命令默认仅预览，仅在获得用户明确批准后使用

--execute

。

不要直接使用

shopify store execute

扫描图像或更新alt文本，除非用于 narrow troubleshooting。直接终端突变容易一次仅处理一张图像，在某些IDE终端中可能停滞，且会绕过助手的分页、批量处理、重复检查和清理规则。当选择路径B时，助手内部使用Shopify CLI商店授权，通过其JavaScript入口点运行Shopify CLI，使用查询/输出文件，并清理临时CLI文件。

vision-sample

命令将1-3张真实Shopify图像下载到操作系统临时目录并打印其本地路径。Agent必须通过宿主原生图像输入路径（如Read或图像查看工具）打开这些文件，报告至少3个基于像素的事实，并在探测完成后删除临时文件夹。

Plan Input Contract

计划输入协议

Prefer piping the approved plan JSON to

apply --input -

through stdin. Do not create

alt-text-plan.json

or other persistent process files in the user's working folder unless the user explicitly asks for a file artifact. If a temporary file is unavoidable, create it in the operating system temp directory and delete it immediately after the command returns.

json

{
  "batch": 1,
  "strategy": "multimodal",
  "changes": [
    {
      "type": "product_media",
      "id": "gid://shopify/MediaImage/...",
      "alt": "Black leather tote bag with gold zipper on a white background",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Black tote bag, gold zipper, white background.",
      "reason": "The alt text is based on pixel-derived visual evidence plus product context.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "collection_featured_image",
      "id": "gid://shopify/Collection/...",
      "alt": "Minimal skincare collection arranged on a bathroom counter",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Skincare bottles, bathroom counter, neutral tile background.",
      "reason": "Preserves collection image URL and updates only altText.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "article_featured_image",
      "id": "gid://shopify/Article/...",
      "alt": "Checkout optimization dashboard with conversion metrics",
      "source": "context_only",
      "confidence": "medium",
      "action": "approved_context_only",
      "reason": "Based on article title, summary, and filename.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "article_inline_image",
      "id": "gid://shopify/Article/...#inline-0",
      "articleId": "gid://shopify/Article/...",
      "inlineIndex": 0,
      "alt": "Screenshot of a Shopify product media settings panel",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Shopify product media settings panel, image thumbnail grid, white admin interface.",
      "reason": "Updates only the inline img alt attribute."
    }
  ]
}

Every

alt

must be non-empty and at most 512 characters.

优先通过stdin将已批准的计划JSON管道传输至

apply --input -

，除非用户明确要求文件工件，否则不要在用户工作文件夹中创建

alt-text-plan.json

或其他持久化流程文件。如果必须使用临时文件，请在操作系统临时目录中创建，并在命令返回后立即删除。

json

{
  "batch": 1,
  "strategy": "multimodal",
  "changes": [
    {
      "type": "product_media",
      "id": "gid://shopify/MediaImage/...",
      "alt": "Black leather tote bag with gold zipper on a white background",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Black tote bag, gold zipper, white background.",
      "reason": "The alt text is based on pixel-derived visual evidence plus product context.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "collection_featured_image",
      "id": "gid://shopify/Collection/...",
      "alt": "Minimal skincare collection arranged on a bathroom counter",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Skincare bottles, bathroom counter, neutral tile background.",
      "reason": "Preserves collection image URL and updates only altText.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "article_featured_image",
      "id": "gid://shopify/Article/...",
      "alt": "Checkout optimization dashboard with conversion metrics",
      "source": "context_only",
      "confidence": "medium",
      "action": "approved_context_only",
      "reason": "Based on article title, summary, and filename.",
      "url": "https://cdn.shopify.com/..."
    },
    {
      "type": "article_inline_image",
      "id": "gid://shopify/Article/...#inline-0",
      "articleId": "gid://shopify/Article/...",
      "inlineIndex": 0,
      "alt": "Screenshot of a Shopify product media settings panel",
      "source": "vision",
      "confidence": "high",
      "visualEvidence": "Shopify product media settings panel, image thumbnail grid, white admin interface.",
      "reason": "Updates only the inline img alt attribute."
    }
  ]
}

每个

alt

必须非空且长度不超过512字符。

Inventory And Batching

库存与批量处理

Always scan before writing. The scan output reports:

product count and product media image count
collection count and collection featured image count
article count, article featured image count, and article inline image count
how many images need optimization
shared product files that may affect multiple products if updated
whether the scan paginated through all products, collections, and articles

--page-size

is a page size, not a maximum. The helper keeps paging until Shopify reports no next page. Do not stop after the first page or after the first batch unless the user explicitly asks to pause.

Sort each batch by value and safety:

Missing product primary image alt.
Missing collection featured image alt.
Missing article featured image alt.
Missing article inline image alt.
Existing alt over the soft limit.
Repetitive or low-quality existing alt.
Lower-confidence context-only items.

If the scan finds more than one batch of work, do not try to optimize everything at once. Show the total count, estimated number of batches, and the first batch. After each approved batch, continue to the next batch or explicitly ask the user whether to pause. Do not silently stop after a partial batch.

写入前始终先扫描，扫描输出报告：

产品数量和产品媒体图数量
集合数量和集合特色图数量
文章数量、文章特色图数量和文章内联图数量
需要优化的图像数量
可能影响多个产品的共享产品文件
扫描是否已分页遍历所有产品、集合和文章

--page-size

是页面大小，而非最大值，助手会持续分页直到Shopify报告没有下一页，除非用户明确要求暂停，否则不要在第一页或第一批次后停止。

按价值和安全性对每个批次排序：

缺失产品主图alt文本
缺失集合特色图alt文本
缺失文章特色图alt文本
缺失文章内联图alt文本
现有alt文本超过软限制
现有alt文本重复或质量低下
可信度较低的仅上下文项目

如果扫描发现需要处理的内容超过一个批次，不要尝试一次性优化所有内容，显示总数量、估计批次数和第一批次内容。每完成一个已批准的批次后，继续下一批次或明确询问用户是否暂停，不得在完成部分批次后静默停止。

Duplicate And Quality Gate

重复与质量检查

Before preview:

Reject alt text above 512 characters.
Rewrite alt text above 125 characters unless there is a strong accessibility reason.
Check duplicates within the same product, collection, or article.
Check generic patterns like repeated product title, comma-separated keyword lists, and "image of".
Reject any
```
source: "vision"
```
candidate that does not include concrete
```
visualEvidence
```
.
Mark all context-only items as review-only unless the exact candidate has explicit user approval and
```
action: "approved_context_only"
```
.
For shared product files, explain that a
```
fileUpdate
```
can affect every reference.

预览前：

拒绝长度超过512字符的alt文本
除非有充分的无障碍理由，否则重写长度超过125字符的alt文本
检查同一产品、集合或文章内的重复内容
检查重复产品标题、逗号分隔的关键词列表、“image of”等通用模式
拒绝任何未包含具体
```
visualEvidence
```
的
```
source: "vision"
```
候选
所有仅上下文项目标记为仅审核，除非候选获得明确用户批准且包含
```
action: "approved_context_only"
```
对于共享产品文件，说明
```
fileUpdate
```
会影响所有引用该文件的项目

Safe Parallel Work

安全并行工作

Use sub-agents only when the host environment supports them and only for independent read-only tasks.

Main agent only:

Create or edit
```
skill-hub.env
```
.
Handle credentials or tokens.
Validate Shopify access.
Download and delete temporary images.
Ask for approval.
Run
```
apply --execute
```
.
Verify writes.
Final cleanup.

Safe read-only sub-agent tasks:

Product media review: inspect product image candidates and propose alt text.
Collection image review: inspect collection featured images and propose alt text.
Article image review: inspect featured and inline images and propose alt text.
Duplicate/quality audit: compare proposed alt text for repetition and overlong copy.

Dependency order:

Main agent validates access and runs scan.
After scan, read-only image/context review can run in parallel by surface or batch.
Main agent merges results, validates limits, and shows one preview plan.
Main agent applies approved writes sequentially and verifies.

Do not parallelize Shopify writes. Do not let sub-agents handle secrets, create local scripts, create summary documents, write process JSON into the working folder, delete files, or perform final verification.

仅当宿主环境支持时，才使用子Agent，且仅用于独立的只读任务。

主Agent仅负责：

创建或编辑
```
skill-hub.env
```
处理凭据或令牌
验证Shopify访问权限
下载和删除临时图像
请求批准
运行
```
apply --execute
```
验证写入操作
最终清理

安全的只读子Agent任务：

产品媒体审核：检查产品图像候选并提出alt文本建议
集合图像审核：检查集合特色图并提出alt文本建议
文章图像审核：检查特色图和内联图并提出alt文本建议
重复/质量审计：对比拟议的alt文本是否重复或过长

依赖顺序：

主Agent验证访问权限并运行扫描
扫描完成后，可按范围或批次并行运行只读图像/上下文审核
主Agent合并结果、验证限制并显示一个预览计划
主Agent按顺序应用已批准的写入操作并验证

不要并行执行Shopify写入操作，不要让子Agent处理机密信息、创建本地脚本、创建摘要文档、在工作文件夹中写入流程JSON、删除文件或执行最终验证。

Preview Approval

预览与批准

Before any write, show:

target store
vision strategy: multimodal or context-only fallback
total inventory and selected batch size
proposed changes grouped by product, collection, and article
current alt and proposed alt
confidence and reason
visual evidence for every candidate marked
```
source: "vision"
```
character count for proposed alt
shared-file warnings
article body HTML warnings for inline image changes

Ask for explicit approval to apply the exact batch.

任何写入操作前，需显示：

目标商店
视觉策略：多模态或仅上下文备选方案
总库存和所选批次大小
按产品、集合和文章分组的拟议变更
当前alt文本和拟议alt文本
可信度和理由
每个标记为
```
source: "vision"
```
的候选的视觉证据
拟议alt文本的字符数
共享文件警告
文章内联图变更的正文HTML警告

请求明确批准以应用该确切批次的变更。

Verification And Cleanup

验证与清理

After writes:

Re-run
```
scan
```
or read the changed resources.
Confirm expected alt text exists.
Confirm article inline image
```
src
```
values were not changed.
Confirm no alt text exceeds 512 characters.
Confirm every
```
source: "vision"
```
change has visual evidence that came from actual image inspection.
Confirm low-confidence review-only items were not written unless approved.
Delete temporary image folders and downloaded images.
Confirm the working folder contains no process JSON, generated scripts, summary documents, or one-off helper files created during the run.

If cleanup fails, report the exact path that still needs removal.

写入操作完成后：

重新运行
```
scan
```
或读取已变更资源
确认预期的alt文本已存在
确认文章内联图的
```
src
```
值未被更改
确认所有alt文本未超过512字符
确认每个
```
source: "vision"
```
的变更均包含来自实际图像识别的视觉证据
确认低可信度的仅审核项目未被写入（除非已获批准）
删除临时图像文件夹和下载的图像
确认工作文件夹中没有运行期间创建的流程JSON、生成的脚本、摘要文档或临时辅助文件

如果清理失败，报告仍需删除的确切路径。

Shopify API References

Shopify API参考

Verify current Shopify Admin GraphQL shapes before changing helper queries or mutations:

products

query:

https://shopify.dev/docs/api/admin-graphql/latest/queries/products

files

query:

https://shopify.dev/docs/api/admin-graphql/latest/queries/files

fileUpdate

https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileUpdate

collectionUpdate

https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUpdate

articles

query:

https://shopify.dev/docs/api/admin-graphql/latest/queries/articles

articleUpdate

https://shopify.dev/docs/api/admin-graphql/latest/mutations/articleUpdate

修改助手查询或变更前，验证当前Shopify Admin GraphQL结构：

products

查询：

https://shopify.dev/docs/api/admin-graphql/latest/queries/products

files

查询：

https://shopify.dev/docs/api/admin-graphql/latest/queries/files

fileUpdate

：

https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileUpdate

collectionUpdate

：

https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUpdate

articles

查询：

https://shopify.dev/docs/api/admin-graphql/latest/queries/articles

articleUpdate

：

https://shopify.dev/docs/api/admin-graphql/latest/mutations/articleUpdate