chrome-webstore-release-blueprint

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chrome Web Store Release Blueprint

Chrome Web Store 发布蓝图

Use this skill as a hands-on setup guide. The agent should lead the user step-by-step, ask for confirmations, and only automate the parts that can be done locally/in CI.

将此技能用作实操设置指南。Agent应逐步引导用户，请求确认，且仅自动化可在本地/CI中完成的部分。

What This Skill Is For

此技能的适用场景

Helping a user set up Chrome Web Store release automation from scratch.
Giving clear manual instructions for Google/CWS dashboard steps.
Implementing repo-side scripts/workflows after the user provides credentials.
Verifying submission state (
```
PUBLISHED
```
,
```
PENDING_REVIEW
```
, etc.).

帮助用户从零开始搭建Chrome Web Store发布自动化流程。
为Google/CWS控制台操作提供清晰的手动步骤说明。
在用户提供凭证后，实现代码仓库端的脚本/工作流。
验证提交状态（
```
PUBLISHED
```
、
```
PENDING_REVIEW
```
等）。

Agent Behavior Rules

Agent行为规则

Treat dashboard/OAuth tasks as user-driven; do not imply you performed them.
Give one clear step at a time and wait for confirmation before moving on.
Ask for exact values only when needed, and tell user where each value comes from.
Mask secrets in logs and never commit secret values to git.
If
```
gh
```
is available, offer secret upload automation; if not, provide manual fallback.

将控制台/OAuth操作视为用户主导的任务；不要暗示你已执行这些操作。
一次给出一个清晰的步骤，获得确认后再进行下一步。
仅在需要时索要准确值，并告知用户每个值的来源。
在日志中隐藏敏感信息，绝不要将敏感值提交到git。
如果
```
gh
```
工具可用，提供密钥上传自动化；否则，提供手动操作方案。

Step 1: Project Discovery (Before Any Credential Work)

步骤1：项目信息收集（凭证工作前）

Collect these inputs:

manifest path containing extension version
build command
zip/package command and output file name/path
CI platform (GitHub Actions by default)
release branch policy (
```
main
```
, tags, or manual dispatch)
local secret file convention (
```
.env
```
,
```
.env.local
```
, etc.)

Ask explicitly:

"Do you want CI to publish only when version changes?"
"Do you want me to wire GitHub secret upload via
```
gh
```
?"

收集以下输入信息：

包含扩展版本的manifest文件路径
构建命令
压缩/打包命令及输出文件名/路径
CI平台（默认使用GitHub Actions）
发布分支策略（
```
main
```
分支、标签或手动触发）
本地密钥文件约定（
```
.env
```
、
```
.env.local
```
等）

明确询问：

"是否希望CI仅在版本变更时执行发布？"
"是否需要我通过
```
gh
```
工具配置GitHub密钥上传自动化？"

Step 2: Detailed Credential Walkthrough (User + Agent)

步骤2：详细凭证配置流程（用户+Agent协作）

2.1 Enable API in Google Cloud

2.1 在Google Cloud中启用API

Tell user to open:

https://console.cloud.google.com/apis/library/chromewebstore.googleapis.com

User actions:

Select the intended Google Cloud project.
Click
```
Enable
```
for Chrome Web Store API.

Agent prompt example:

"When Chrome Web Store API shows as Enabled, tell me and I will move to OAuth setup."

告知用户打开以下链接：

https://console.cloud.google.com/apis/library/chromewebstore.googleapis.com

用户操作：

选择目标Google Cloud项目。
点击
```
Enable
```
启用Chrome Web Store API。

Agent提示示例：

"当Chrome Web Store API显示为已启用时，请告知我，我将进入OAuth配置步骤。"

2.2 Configure OAuth Consent Screen

2.2 配置OAuth同意屏幕

Tell user to open one of:

https://console.cloud.google.com/apis/credentials/consent

If UI redirects, continue in Google Auth Platform consent screen pages.

User actions:

Choose
```
External
```
user type (for non-Workspace internal apps).
Fill app name, support email, developer contact email.
Save and continue through scopes unless custom scopes are required.
Add your own Google account as a test user if app is in Testing mode.
Save.

Agent guidance:

If user wants stable long-lived refresh token behavior, recommend moving consent screen to Production when ready.

告知用户打开以下链接之一：

https://console.cloud.google.com/apis/credentials/consent

如果界面跳转，继续在Google认证平台同意屏幕页面操作。

用户操作：

选择
```
External
```
用户类型（适用于非Workspace内部应用）。
填写应用名称、支持邮箱、开发者联系邮箱。
保存并继续完成范围配置（除非需要自定义范围）。
如果应用处于测试模式，将你自己的Google账号添加为测试用户。
保存配置。

Agent指导说明：

如果用户需要稳定的长期刷新令牌，建议在准备就绪后将同意屏幕切换到生产模式。

2.3 Create OAuth Client

2.3 创建OAuth客户端

Tell user to open:

https://console.cloud.google.com/apis/credentials

User actions:

Click
```
Create Credentials
```
->
```
OAuth client ID
```
.
Choose application type
```
Web application
```
.
Add authorized redirect URI exactly:

https://developers.google.com/oauthplayground

Create client.

Capture values:

```
CWS_CLIENT_ID
```
```
CWS_CLIENT_SECRET
```

Agent prompt example:

"Paste
```
CWS_CLIENT_ID
```
and
```
CWS_CLIENT_SECRET
```
when ready (I will treat them as secrets)."

告知用户打开以下链接：

https://console.cloud.google.com/apis/credentials

用户操作：

点击
```
Create Credentials
```
->
```
OAuth client ID
```
。
选择应用类型为
```
Web application
```
。
准确添加授权重定向URI：

https://developers.google.com/oauthplayground

创建客户端。

记录以下值：

```
CWS_CLIENT_ID
```
```
CWS_CLIENT_SECRET
```

Agent提示示例：

"准备好后请粘贴
```
CWS_CLIENT_ID
```
和
```
CWS_CLIENT_SECRET
```
（我会将它们视为敏感信息）。"

2.4 Generate Refresh Token (OAuth Playground)

2.4 生成刷新令牌（使用OAuth Playground）

Tell user to open:

https://developers.google.com/oauthplayground/

User actions:

Click the settings gear icon.
Enable
```
Use your own OAuth credentials
```
.
Paste
```
CWS_CLIENT_ID
```
and
```
CWS_CLIENT_SECRET
```
.
In Step 1, enter scope:

https://www.googleapis.com/auth/chromewebstore

Click
```
Authorize APIs
```
.
Sign in with the same Google account that owns/publishes the extension.
Click
```
Exchange authorization code for tokens
```
.
Copy refresh token.

Capture value:

```
CWS_REFRESH_TOKEN
```

Agent prompt example:

"Paste
```
CWS_REFRESH_TOKEN
```
now. I will only place it in local secret storage/CI secrets."

告知用户打开以下链接：

https://developers.google.com/oauthplayground/

用户操作：

点击设置齿轮图标。
启用
```
Use your own OAuth credentials
```
选项。
粘贴
```
CWS_CLIENT_ID
```
和
```
CWS_CLIENT_SECRET
```
。
在步骤1中，输入权限范围：

https://www.googleapis.com/auth/chromewebstore

点击
```
Authorize APIs
```
。
使用拥有扩展发布权限的Google账号登录。
点击
```
Exchange authorization code for tokens
```
。
复制刷新令牌。

记录以下值：

```
CWS_REFRESH_TOKEN
```

Agent提示示例：

"现在请粘贴
```
CWS_REFRESH_TOKEN
```
。我只会将其存储在本地密钥文件/CI密钥中。"

2.5 Capture Store IDs

2.5 记录商店ID

Capture:

```
CWS_EXTENSION_ID
```
(the extension item ID from store/developer listing URL)
```
CWS_PUBLISHER_ID
```
(developer/publisher ID from Chrome Web Store developer account context)

Agent instruction:

If user is unsure, ask them to open the Chrome Web Store Developer Dashboard and copy IDs from item/account URLs or account details.

记录以下值：

```
CWS_EXTENSION_ID
```
（商店/开发者列表URL中的扩展项ID）
```
CWS_PUBLISHER_ID
```
（Chrome Web Store开发者账号中的开发者/发布者ID）

Agent说明：

如果用户不确定，告知他们打开Chrome Web Store开发者控制台，从项目/账号URL或账号详情中复制ID。

2.6 Credential Checklist

2.6 凭证检查清单

Do not proceed until all five exist:

```
CWS_CLIENT_ID
```
```
CWS_CLIENT_SECRET
```
```
CWS_REFRESH_TOKEN
```
```
CWS_PUBLISHER_ID
```
```
CWS_EXTENSION_ID
```

确保以下五个值全部存在后再继续：

```
CWS_CLIENT_ID
```
```
CWS_CLIENT_SECRET
```
```
CWS_REFRESH_TOKEN
```
```
CWS_PUBLISHER_ID
```
```
CWS_EXTENSION_ID
```

Step 3: Local Secret File and CI Secret Setup

步骤3：本地密钥文件与CI密钥配置

Create a local template file (no real values committed):

env

CWS_CLIENT_ID=
CWS_CLIENT_SECRET=
CWS_REFRESH_TOKEN=
CWS_PUBLISHER_ID=
CWS_EXTENSION_ID=

Ensure real secret file path is gitignored.

If using GitHub Actions, ask user if

gh

automation is desired.

If yes, verify:

bash

gh --version
gh auth status

gh

auth is missing, tell user to run:

```
gh auth login
```

Then implement a helper script that:

reads secret values from local env file
validates all required keys are present
supports
```
--dry-run
```
masks values in dry-run output
uploads with
```
gh secret set ... --repo ...
```
fails fast on missing keys/auth

If user declines

gh

, provide manual secret entry checklist for repository settings.

创建本地模板文件（不包含真实值，不提交到git）：

env

CWS_CLIENT_ID=
CWS_CLIENT_SECRET=
CWS_REFRESH_TOKEN=
CWS_PUBLISHER_ID=
CWS_EXTENSION_ID=

确保真实密钥文件的路径已添加到.gitignore中。

如果使用GitHub Actions，询问用户是否需要

gh

工具的自动化配置。

如果需要，验证以下命令：

bash

gh --version
gh auth status

如果

gh

未授权，告知用户运行以下命令：

```
gh auth login
```

然后实现一个辅助脚本，该脚本需具备以下功能：

从本地环境文件读取密钥值
验证所有必填密钥是否存在
支持
```
--dry-run
```
参数
在dry-run输出中隐藏敏感值
使用
```
gh secret set ... --repo ...
```
上传密钥
若缺少密钥或授权失败则立即终止

如果用户拒绝使用

gh

，提供仓库设置中的手动密钥输入检查清单。

Step 4: Release Workflow Blueprint (Version-Triggered)

步骤4：发布工作流蓝图（版本触发）

Design the CI workflow around this logic:

Read local manifest version.
Optionally compare with a secondary version file and fail on mismatch.
Exchange refresh token for access token:

POST https://oauth2.googleapis.com/token

Fetch CWS status:

GET https://chromewebstore.googleapis.com/v2/publishers/<publisherId>/items/<extensionId>:fetchStatus

Extract current published version from:

publishedItemRevisionStatus.distributionChannels[0].crxVersion

If local version == published version, skip publish.
If version changed:

build package zip

upload zip:

POST https://chromewebstore.googleapis.com/upload/v2/publishers/<publisherId>/items/<extensionId>:upload

handle async upload state with polling when needed

publish:

POST https://chromewebstore.googleapis.com/v2/publishers/<publisherId>/items/<extensionId>:publish

Treat these publish states as successful submission:

```
PENDING_REVIEW
```
```
PUBLISHED
```
```
PUBLISHED_TO_TESTERS
```
```
STAGED
```

围绕以下逻辑设计CI工作流：

读取本地manifest文件中的版本。
可选：与备用版本文件进行对比，若版本不匹配则终止流程。
使用刷新令牌换取访问令牌：

POST https://oauth2.googleapis.com/token

获取CWS状态：

GET https://chromewebstore.googleapis.com/v2/publishers/<publisherId>/items/<extensionId>:fetchStatus

从以下路径提取当前已发布版本：

publishedItemRevisionStatus.distributionChannels[0].crxVersion

如果本地版本与已发布版本相同，跳过发布。
如果版本已变更：

构建扩展包zip文件

上传zip文件：

POST https://chromewebstore.googleapis.com/upload/v2/publishers/<publisherId>/items/<extensionId>:upload

必要时通过轮询处理异步上传状态

执行发布：

POST https://chromewebstore.googleapis.com/v2/publishers/<publisherId>/items/<extensionId>:publish

将以下发布状态视为提交成功：

```
PENDING_REVIEW
```
```
PUBLISHED
```
```
PUBLISHED_TO_TESTERS
```
```
STAGED
```

Step 5: Submission Status Checker Blueprint

步骤5：提交状态检查脚本蓝图

Create a script dedicated to "what is the latest submission state?".

Required behavior:

accepts env values (and optional
```
--env-file
```
)
optionally accepts
```
--manifest
```
for local version comparison
supports
```
--json
```
calls token endpoint +
```
fetchStatus
```

outputs normalized fields:

```
itemId
```
```
localVersion
```
```
publishedVersion
```
```
publishedState
```
```
submittedVersion
```
```
submittedState
```
```
upToDate
```
```
pendingReview
```

exits non-zero on auth/API/input errors

Helpful checks to include:

flag version mismatch between manifest and package metadata
show whether uploaded version is pending review but not yet published
print concise human summary when
```
--json
```
is not used

创建一个专门用于查询“最新提交状态”的脚本。

必备功能：

支持读取环境变量（可选支持
```
--env-file
```
参数）
可选支持
```
--manifest
```
参数用于本地版本对比
支持
```
--json
```
输出格式
调用令牌接口 +
```
fetchStatus
```
接口

输出标准化字段：

```
itemId
```
```
localVersion
```
```
publishedVersion
```
```
publishedState
```
```
submittedVersion
```
```
submittedState
```
```
upToDate
```
```
pendingReview
```

若出现授权/API/输入错误，返回非零退出码

建议包含的检查项：

标记manifest文件与扩展包元数据之间的版本不匹配
显示已上传版本是否处于待审核状态但尚未发布
当未使用
```
--json
```
参数时，输出简洁的人类可读摘要

Step 6: Guided Verification Flow

步骤6：引导式验证流程

Run this with the user:

Confirm status checker runs successfully before release.
Bump extension version (patch) in all version sources.
Push branch and trigger workflow.
Confirm workflow either:

skips (if no version change), or
uploads and submits publish.

Re-run status checker:

expect
```
PENDING_REVIEW
```
first in many cases
later expect published channel to match local version

与用户共同执行以下步骤：

在发布前确认状态检查脚本可正常运行。
在所有版本源文件中升级扩展版本（补丁版本即可）。
推送分支并触发工作流。
确认工作流：

若版本未变更则跳过发布，或
完成扩展包上传并提交发布。

重新运行状态检查脚本：

多数情况下初始状态应为
```
PENDING_REVIEW
```
后续应显示已发布渠道的版本与本地版本一致

Troubleshooting Script (What Agent Should Say)

故障排查说明（Agent应告知用户的内容）

```
invalid_grant
```
:
likely wrong/expired refresh token, wrong OAuth client, or wrong account
```
403
```
from CWS endpoint:
account lacks publisher permissions for that extension
workflow no-op:
local version equals published version by design
upload failure:
inspect API response and packaged zip structure/manifest validity
version mismatch guard failure:
align all declared version files before publishing

```
invalid_grant
```
错误：
可能是刷新令牌无效/过期、OAuth客户端错误或账号权限问题
CWS接口返回
```
403
```
错误：
当前账号无该扩展的发布权限
工作流无操作：
根据设计，当本地版本与已发布版本相同时会跳过发布
上传失败：
检查API响应及扩展包zip结构/manifest文件的有效性
版本不匹配检查失败：
发布前需统一所有声明版本的文件

Practical Links (Share During Guidance)

实用链接（指导过程中可分享）

Chrome Web Store API overview:

https://developer.chrome.com/docs/webstore/using-api

Publish endpoint:

https://developer.chrome.com/docs/webstore/publish

OAuth Playground:

https://developers.google.com/oauthplayground/

API enablement page:

https://console.cloud.google.com/apis/library/chromewebstore.googleapis.com

Credentials page:

https://console.cloud.google.com/apis/credentials

Chrome Web Store API概述：

https://developer.chrome.com/docs/webstore/using-api

发布接口文档：

https://developer.chrome.com/docs/webstore/publish

OAuth Playground：

https://developers.google.com/oauthplayground/

API启用页面：

https://console.cloud.google.com/apis/library/chromewebstore.googleapis.com

凭证配置页面：

https://console.cloud.google.com/apis/credentials

Guardrails

注意事项

Never commit credentials.
Never hardcode secrets in workflow YAML.
Never auto-publish every push without version comparison.
Keep setup instructions explicit and user-confirmed at each manual step.
Prefer repeatable helper scripts over ad-hoc one-off commands.

绝不要提交凭证到git。
绝不要在工作流YAML中硬编码敏感信息。
绝不要在每次推送时自动发布，必须加入版本对比校验。
保持设置说明清晰明确，每个手动步骤都需用户确认。
优先使用可重复执行的辅助脚本，而非临时命令。