发布者技能 是做什么的?
将 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 包 | 发布并构建 APK | zip 路径,项目名称 |
| 为已发布的项目构建 APK | 构建 APK | 项目 id;如果需要,可使用项目列表 |
| 将应用设为私有/公开,添加/移除访问密码 | 更改可见性 | 应用 URL,目标可见性(私有时可选的密码) |
| 显示我的项目,列出已发布的项目 | 列出项目 | 如果令牌可用,则无需询问 |
| 登录、注册、账户设置 | 登录/注册 | 用户名和密码 |
如果意图不明确,请提出一个简短的问题:“只是发布它,还是发布它并同时构建 Android APK?”
发布对话流程
当用户表达诸如发布、部署、启动、分享应用、生成访问链接等意图时,必须进入此流程。
<硬性限制> 发布流程是一个阻塞的有限状态机。只要当前步骤缺乏用户输入,模型就必须停止推进,仅就当前步骤提出一个问题,并等待用户响应。 禁止根据上下文猜测答案。 禁止自动选择公开/私有。 禁止自动生成访问密码,除非用户明确选择让系统生成。 在完成所有必要步骤之前,禁止调用发布接口。 每次响应最多只能包含一个面向用户的问题。 </硬性限制>
有限状态机的一般原则
- 进入流程时,首先运行
S-1(版本检查,非阻塞),然后按S0 -> S1 -> S2 -> S3 -> S4的顺序进行。 - 不允许跳过步骤(
S-1除外)。 - 不能在一次请求中询问多个字段。
- 用户已明确提供的信息可以记录下来,无需重复询问。
- 当用户响应模棱两可时,仅对当前字段进行一次追问。
- 只有当前步骤完成后才能进入下一步。
- 如果需要等待用户输入,则不要在响应末尾附加解释、建议或下一步的预览。
S-1:版本检查(发布流程的第一个节点,非阻塞)
进入发布流程时,在 S0 之前运行一次版本自检。此步骤不属于 <硬性限制> 阻塞规则的一部分:无论结果如何——即使端点不可达——始终继续。绝不因版本问题中断发布。
步骤:
-
读取本地技能版本:此文件 frontmatter 中的
version字段。 -
查询最新的平台版本(无需登录):
curl -s https://ai-pub.pushwebly.com/api/skill/latest-version响应
data包含:version(最新版本)、downloadUrl(跨平台文档包,解压即用)、downloadUrlWindows(Windows 安装程序 .exe)和downloadUrlMac(macOS 安装程序 .zip)。 -
比较本地
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(更新不影响当前发布)。 - Windows → 使用
-
本地版本等于或更新:保持静默并继续。
-
请求失败/超时/无法解析:静默跳过,直接转到
S0,不要显示错误。
-
-
在所有情况下,下一步继续到
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=publicvisibility=private并且用户已选择自定义密码或系统生成的密码
发布参数:
公开应用:
{
"visibility": "public"
}
私有应用,自定义密码:
{
"visibility": "private",
"access_password": "a1b2c3"
}
如果 visibility=private 且 access_password 未指定,则让后端自动生成。
如果用户未指定可见性,则默认为 public。私有访问密码必须匹配 ^[A-Za-z0-9]{6}$;否则请询问有效的密码或让后端生成一个。
令牌处理
所有发布 API 都需要 Bearer 令牌。
使用以下顺序:
- 如果用户在对话中提供了令牌,则直接使用。
- 如果
~/.publisher/config.json存在,读取存储的用户名/密码并重新登录以刷新令牌。 - 否则询问用户名和密码。登录端点会自动注册新账户。
登录/注册端点:
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>"
发布前检查
发布前:
- 确认文件存在且具有
.zip扩展名。 - 确认 zip 文件中包含
index.html或index.htm。 - 如果 zip 文件包含嵌套目录,请确认可以定位到入口文件。
- 确认项目名称非空。
- 确认有有效的令牌可用。
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),请包含状态码和来自响应的消息。网络超时应提示用户稍后重试。