Community写作与编辑github.com

发布者技能

将 HTML 前端游戏项目发布到 AI Game MCP 平台,并可选择打包为 Android APK。

发布者技能 是什么?

此技能专为使用 Claude Code、Cursor、Codex 等 AI 智能体的开发者设计,用于将 HTML 前端游戏项目一键部署到 pushwebly.com 平台,并支持生成 Android APK 安装包。它提供了一个完整的状态机发布流程,从版本自检、账户注册/登录,到设置项目可见性和访问密码,最后执行发布或 APK 构建。技能通过 MCP 工具集或 curl HTTP API 与平台交互,智能处理令牌认证,并严格遵循用户输入驱动的流程,确保每次发布都安全可控。它适用于所有操作系统,并针对 Windows/PowerShell 环境提供了特设的 JSON 请求体处理方式。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add publisher-skill/publisher

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

发布者技能 是做什么的?

将 HTML 前端项目发布到发布平台,并可选择将其打包为 Android APK。

平台 URL:

https://pushwebly.com

在与用户沟通时使用“项目”一词。规范 API 路径是 /api/projects,规范工具名称是 project_*。已弃用的 game_* 别名和 gameId 响应字段可能仍然出现;请将 gameId 视为项目 id。

Codex 执行规则

  • 如果当前环境中已挂载 project_* MCP 工具,则优先使用它们。
  • 如果远程 MCP 工具未挂载,则使用带有 curl 的 HTTP API。
  • 不需要 Python。可选的脚本(如果存在)仅供 CLI/CI 用户使用。
  • 仅询问真正缺失的信息:凭证、zip 路径、项目名称、公开/私有可见性或私有访问密码偏好。
  • 切勿将凭证写入项目 zip 或存储库文件中。经用户同意后,仅将其存储在用户本地的 ~/.publisher/config.json 中。
  • 在 Windows/PowerShell 上,使用临时 JSON 文件作为请求体,而不是对行内 JSON 进行 shell 转义。

意图映射

用户意图操作需要询问的缺失信息
发布、上传、上线发布项目zip 路径,项目名称
制作可安装的手机应用、APK、Android 包发布并构建 APKzip 路径,项目名称
为已发布的项目构建 APK构建 APK项目 id;如果需要,可使用项目列表
将应用设为私有/公开,添加/移除访问密码更改可见性应用 URL,目标可见性(私有时可选的密码)
显示我的项目,列出已发布的项目列出项目如果令牌可用,则无需询问
登录、注册、账户设置登录/注册用户名和密码

如果意图不明确,请提出一个简短的问题:“只是发布它,还是发布它并同时构建 Android APK?”

发布对话流程

当用户表达诸如发布、部署、启动、分享应用、生成访问链接等意图时,必须进入此流程。

<硬性限制> 发布流程是一个阻塞的有限状态机。只要当前步骤缺乏用户输入,模型就必须停止推进,仅就当前步骤提出一个问题,并等待用户响应。 禁止根据上下文猜测答案。 禁止自动选择公开/私有。 禁止自动生成访问密码,除非用户明确选择让系统生成。 在完成所有必要步骤之前,禁止调用发布接口。 每次响应最多只能包含一个面向用户的问题。 </硬性限制>

有限状态机的一般原则

  • 进入流程时,首先运行 S-1(版本检查,非阻塞),然后按 S0 -> S1 -> S2 -> S3 -> S4 的顺序进行。
  • 不允许跳过步骤(S-1 除外)。
  • 不能在一次请求中询问多个字段。
  • 用户已明确提供的信息可以记录下来,无需重复询问。
  • 当用户响应模棱两可时,仅对当前字段进行一次追问。
  • 只有当前步骤完成后才能进入下一步。
  • 如果需要等待用户输入,则不要在响应末尾附加解释、建议或下一步的预览。

S-1:版本检查(发布流程的第一个节点,非阻塞)

进入发布流程时,在 S0 之前运行一次版本自检。此步骤不属于 <硬性限制> 阻塞规则的一部分:无论结果如何——即使端点不可达——始终继续。绝不因版本问题中断发布。

步骤:

  1. 读取本地技能版本:此文件 frontmatter 中的 version 字段。

  2. 查询最新的平台版本(无需登录):

    curl -s https://ai-pub.pushwebly.com/api/skill/latest-version
    

    响应 data 包含:version(最新版本)、downloadUrl(跨平台文档包,解压即用)、downloadUrlWindows(Windows 安装程序 .exe)和 downloadUrlMac(macOS 安装程序 .zip)。

  3. 比较本地 version 和返回的 version。

    比较规则:版本格式为 major.minor.patch。从左到右逐段按整数比较——先比较 major,然后 minor,最后 patch;缺失的段补 0(1.1 视作 1.1.0)。作为整数比较,而不是字符串:1.10.0 大于 1.9.0(第二段 10 > 9);字符串比较会出错。升序示例:1.0.0 < 1.0.9 < 1.1.0 < 1.2.0 < 1.10.0 < 2.0.0。

    • 本地版本更旧(本地的整数段序列小于返回的序列):你必须在继续之前向用户输出更新通知,并且通知必须包含实际的下载 URL(这不阻止发布,但通知不可省略)。根据用户的操作系统选择下载 URL:

      • Windows → 使用 downloadUrlWindows
      • macOS → 使用 downloadUrlMac
      • 操作系统未知,或匹配的字段为空 → 回退到通用 downloadUrl

      通知文本(以用户当前对话的语言输出——如果他们写中文就用中文,用英文就用英文;不要硬编码一种语言;下面的示例仅作模板;将 URL 替换为实际选择的 URL;将下载 URL 写成可点击的 Markdown 链接 [URL](URL)——不要用反引号将其包裹为行内代码,否则用户无法点击;切勿留占位符,切勿只说“有新版本存在”而不提供链接):

      注意:有新的 Publisher 技能版本 <version> 可用(你当前使用的是 <local version>)。下载地址:https://ai-pub.pushwebly.com/downloads/AI_Publisher_skill.exe(更新不影响当前发布)。

    • 本地版本等于或更新:保持静默并继续。

    • 请求失败/超时/无法解析:静默跳过,直接转到 S0,不要显示错误。

  4. 在所有情况下,下一步继续到 S0。因为此步骤仅通知(无输入,不阻塞),所以“每次回复最多一个面向用户的问题”的规则不适用于它——版本通知可以与第一个 S0 问题共享同一次回复。


S0:检查账户状态

首先,检查是否已有可用的令牌/本地凭证。

  • 如果已有账户凭证:转到 S2。
  • 如果没有账户凭证:进入 S1_用户名。
  • 如果无法检查账户状态:询问用户是否已有发布账户。

向用户提问:

我需要先确认发布账户:你是否已有可用的账户或令牌?

用户回答:

  • 是:要求用户提供或确认令牌/登录凭证,然后转到 S2。
  • 否:进入 S1_用户名。

S1:注册和登录流程

S1_用户名:收集注册用户名

如果没有用户名,仅询问:

请提供要注册的用户名。

收到用户名后,将其记录为 username 并进入 S1_密码。

S1_密码:收集注册密码

如果没有密码,仅询问:

请提供注册密码。

收到密码后,将其记录为 password 并进入 S1_验证。

S1_验证:联合验证

只有同时拥有 username 和 password 后,才能调用后端接口进行联合验证。

验证通过:

  • 创建账户
  • 完成登录
  • 提示:注册并登录成功
  • 进入 S2

验证失败:

  • 显示后端返回的具体错误原因
  • 仅询问需要更正的项目
  • 不终止注册流程

S2:询问应用可见性

如果公开或私有状态尚未明确,仅询问:

这个应用是公开的吗?公开意味着任何人都可以通过链接访问;私有则需要一个 6 位访问密码。

用户回答:

  • 公开 / 是 / public:记录 visibility=public,进入 S4
  • 私有 / 否 / private:记录 visibility=private,进入 S3
  • 不清楚:继续仅询问此项目

S3:私有访问密码

如果 visibility=private,需要询问是否自定义密码,仅询问:

你想自定义一个 6 位访问密码吗?也可以回复“系统生成”。

用户回答:

  • 提供密码:必须验证为 6 位数字或字母;通过后,记录 accessPassword=<用户密码> 并进入 S4
  • 回复系统生成 / 不需要 / 随机:不传递 accessPassword,让后端生成,并进入 S4
  • 密码格式错误:仅提示格式要求并重新询问密码

S4:执行发布

仅在满足以下条件之一时才能调用发布接口:

  • visibility=public
  • visibility=private 并且用户已选择自定义密码或系统生成的密码

发布参数:

公开应用:

{
  "visibility": "public"
}

私有应用,自定义密码:

{
  "visibility": "private",
  "access_password": "a1b2c3"
}

如果 visibility=private 且 access_password 未指定,则让后端自动生成。

如果用户未指定可见性,则默认为 public。私有访问密码必须匹配 ^[A-Za-z0-9]{6}$;否则请询问有效的密码或让后端生成一个。

令牌处理

所有发布 API 都需要 Bearer 令牌。

使用以下顺序:

  1. 如果用户在对话中提供了令牌,则直接使用。
  2. 如果 ~/.publisher/config.json 存在,读取存储的用户名/密码并重新登录以刷新令牌。
  3. 否则询问用户名和密码。登录端点会自动注册新账户。

登录/注册端点:

curl -s -X POST https://ai-pub.pushwebly.com/api/auth/login-or-register \
  -H "Content-Type: application/json" \
  -d @login.json

将 login.json 写为:

{"username":"alice","password":"plain-text-password"}

使用响应中的 data.token 作为:

Authorization: Bearer <TOKEN>

使用后删除临时登录文件。

可选的本地凭证文件:

{
  "baseUrl": "https://ai-pub.pushwebly.com",
  "username": "alice",
  "password": "plain-text-password",
  "authorization": "Bearer <TOKEN>",
  "userId": 1
}

在 Linux/macOS 上,写入后设置模式 600。遇到 401 错误时,通过重新登录刷新令牌一次,然后重试失败的操作一次。

验证令牌:

curl -s https://ai-pub.pushwebly.com/api/auth/verify-token \
  -H "Authorization: Bearer <TOKEN>"

发布前检查

发布前:

  1. 确认文件存在且具有 .zip 扩展名。
  2. 确认 zip 文件中包含 index.html 或 index.htm。
  3. 如果 zip 文件包含嵌套目录,请确认可以定位到入口文件。
  4. 确认项目名称非空。
  5. 确认有有效的令牌可用。

HTTP 操作

发布项目

公开:

curl -s -X POST https://ai-pub.pushwebly.com/api/projects/publish \
  -H "Authorization: Bearer <TOKEN>" \
  -F "project_name=demo" \
  -F "[email protected]"

私有(可选的密码):

curl -s -X POST https://ai-pub.pushwebly.com/api/projects/publish \
  -H "Authorization: Bearer <TOKEN>" \
  -F "project_name=demo" \
  -F "[email protected]" \
  -F "visibility=private" \
  -F "access_password=a1b2c3"

对于私有应用,省略 access_password 可让后端生成密码。始终将响应中的最终 accessPassword 告知用户。

列出项目

curl -s https://ai-pub.pushwebly.com/api/projects/my \
  -H "Authorization: Bearer <TOKEN>"

更改可见性(公开 <-> 私有)

在已发布的应用之间切换公开和私有状态。输入是应用 URL;后端从其中解析出应用标识符并验证该应用属于当前用户——你只能更改自己的应用,不能更改他人的。

curl -s -X PATCH https://ai-pub.pushwebly.com/api/projects/visibility \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d @visibility.json

将 visibility.json 写入(更改为私有):

{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"private","accessPassword":"a1b2c3"}

或更改为公开(无需密码;旧密码将被清除):

{"url":"https://ai-pub.pushwebly.com/play/aB3xYz/","visibility":"public"}

accessPassword 是可选的,仅在切换到私有时使用(6位数字或字母;省略则自动生成)。响应 data 包含最终的 visibility、url,以及当为私有时包含 accessPassword。请分别告知用户私有应用的 URL 和密码,切勿与 ?pwd= 一起给出。如果未找到应用、应用已被删除或属于其他用户,请说明具体原因,并指出只能更改自己的应用。

为已有项目构建 APK

curl -s -X POST https://ai-pub.pushwebly.com/api/apk/build \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d @build-apk.json

将 build-apk.json 写为:

{"projectId":12}

使用响应中的 data.apkUrl 作为 APK 下载 URL。

发布并构建 APK

当用户想要一个可安装的 Android 应用时,这是推荐的操作。

curl -s -X POST https://ai-pub.pushwebly.com/api/apk/publish-and-build \
  -H "Authorization: Bearer <TOKEN>" \
  -F "project_name=airplane-war" \
  -F "[email protected]"

对于私有应用,添加:

-F "visibility=private" -F "access_password=a1b2c3"

省略 access_password 以自动生成。

预期的响应字段可能包括:

{
  "gameId": 12,
  "projectName": "airplane-war",
  "playUrl": "https://ai-pub.pushwebly.com/play/aB3xYz/",
  "status": "enabled",
  "apkUrl": "https://ai-pub.pushwebly.com/api/apk/download/airplane-war_aB3xYz.apk",
  "apkFileNa"
}

本地配置文件

凭证存储在 ~/.publisher/config.json 中。

错误处理

如果 API 返回错误,请向用户显示可读的错误消息。对于 HTTP 错误(4xx、5xx),请包含状态码和来自响应的消息。网络超时应提示用户稍后重试。

相关技能