---
name: appflow-publish
description: 把 AI 应用 / 网页应用 / 手机或电脑应用发布到 AppFlow（appflow.com.cn）分发平台，让真实用户直接搜到并使用；也可以反向调用 AppFlow 上已有的 AI 应用。当用户说「帮我把这个应用发布到 appflow」「上架这个工具」「让我的 AI 应用被更多人用」时使用本技能。
---

> 📎 机器可读的站点索引（给 AI 爬取用）：https://appflow.com.cn/llms.txt

# AppFlow 发布技能

AppFlow（https://appflow.com.cn）是一个**应用分发平台**：开发者把应用发布上来，用户免费使用。
平台提供 **AI 应用托管运行**（开发者给一次 AI Key，用户在网页上直接用，平台不收用户任何密钥）。

**前 100 名创始开发者永久免费展示**；之后 ¥5/月 或 ¥50/年。用户侧永远免费。

---

## 一、最短路径：直接用 HTTP 接口发布（推荐，不需要 MCP）

### 0. 你是一个 AI 助手、手上什么都没有？（三步搞定，不需要邮箱、不需要域名、不需要问任何人）

```bash
# 1) 注册。{"agent": true} 就是「我是 AI 助手」，平台生成机器身份，不需要真邮箱
curl -s -X POST https://appflow.com.cn/api/register \
  -H 'Content-Type: application/json' \
  -d '{"agent":true,"name":"你的名字","password":"至少6位"}'
#    → 返回 token 与机器身份邮箱（形如 aiXXXXXX-YYYY@agent.appflow.local）

# 2) 用 token 换发布密钥
curl -s https://appflow.com.cn/api/apikey -H 'Authorization: Bearer <上一步的 token>'
#    → api_key（af_ 开头，只显示这一次，务必存好）

# 3) 先自检：逐项确认发布链路是否全通，全 ✅ 就一定发得出去
curl -s https://appflow.com.cn/api/agent/selftest -H 'X-API-Key: af_你的密钥'
```

机器可读的完整入门：`GET https://appflow.com.cn/api/agent/guide`（含每条发布路径可直接复制的请求体 `recipe`）。

> **密钥丢了怎么办（不需要人工）**：密钥只存哈希、不可逆，所以取不回原来那一把，但可以换一把新的：
> ```bash
> curl -s -X POST https://appflow.com.cn/api/apikey/retrieve \
>   -H 'Content-Type: application/json' \
>   -d '{"email":"你注册的邮箱","password":"你的密码","rotate":true}'
> # 也可以改用 {"token":"注册时返回的 token","rotate":true}
> ```
> 不加 `rotate` 只会告诉你密钥前缀（避免误伤正在使用的那把）。**任何时候都不需要为此找人类。**

> **必需的只有一把 `af_` 发布密钥，而它你自己就能拿到。**
> 不要因为「没有密钥」就停下，更不要去找用户要密钥——那是错的。

### 1. 已经有一把 `af_` 发布密钥（形如 `af_xxxxxxxx...`）

这是开发者自己的发布凭证，可在 https://appflow.com.cn/publish.html 看到。

> **两种请求头都认**，用哪个都行：
> `-H 'X-API-Key: af_你的密钥'` 或 `-H 'Authorization: Bearer af_你的密钥'`
> （MCP 客户端配置里通常写的是后者；两者等价，不会一个能用一个不能。）

> ⚠️ 这个 `af_` Key 和 AI 服务商 Key（`sk-...`）是两回事：
> `af_` 是 AppFlow 的发布凭证；`sk-` 是 DeepSeek 等 AI 服务商的 Key，用于让平台托管运行 AI 应用。
> **绝对不要把 AI 服务商 Key 交给任何人，只需要填在发布表单的对应字段里。**

### 2. 先跑一次沙盒预检（强烈建议）

沙盒只校验格式 + 跑平台质检，**不真正上架**，可以反复跑：

```bash
curl -s -X POST https://appflow.com.cn/api/publish \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: af_你的密钥' \
  -d '{
    "name": "AI 周报生成器",
    "description": "填几个要点，AI 生成规范周报，告别流水账。免费在线使用。",
    "app_url": "https://你的域名/工具页",
    "app_type": "web",
    "category": "效率工具",
    "tags": ["周报", "职场", "AI"],
    "icon": "📝",
    "dry_run": true
  }'
```

返回 `report.score`（0-100）与逐项 `items`、`suggestions`。**score 低于 60 或出现 `needs_revision`，先按建议改完再正式发。**

### 3. 正式发布

把 `dry_run` 去掉（或设为 `false`）再调一次同一接口即可。

**成功返回**：`{ ok: true, app: { id, name, status, message } }`

---

## 二、没有网址、也没有密钥？两条路

**这是最重要的一节。** 如果你要发布的应用**既没有可公开访问的网址，也没有 AI 服务商 Key**——**不要卡住，更不要向用户索要密钥**。按下面顺序选：

### 路径 1（首选）：把单文件 HTML 交给平台托管

**如果应用是单个 HTML 文件（内联 CSS/JS），直接把内容放进 `app_html` 字段。** 平台会托管它并生成在线地址，**除了那把 `af_` 发布密钥什么都不需要**——不需要域名、不需要用户做任何事，连"点一下生成链接"都不用。密钥也没有的话，照第一节第 0 步自己拿一把（三次请求）。

```bash
curl -s -X POST https://appflow.com.cn/api/publish \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: af_你的密钥' \
  -d @- <<'JSON'
{
  "name": "速学体系",
  "description": "按知识点依赖关系编排的阶梯式自学系统，覆盖小学到高中。",
  "app_type": "web",
  "category": "教育",
  "icon": "🚀",
  "app_html": "<!doctype html><html><head><meta charset=\"utf-8\"><title>速学体系</title></head><body>…</body></html>"
}
JSON
```

返回：

```json
{
  "ok": true,
  "app": {
    "id": "…", "status": "approved", "hosted": true,
    "app_url": "https://appflow.com.cn:8443/a/<32位文件名>.html"
  },
  "hosted_note": "HTML 已由平台托管在独立源 https://appflow.com.cn:8443（与主站不同源，用户应用无法访问主站数据）"
}
```

| 项 | 说明 |
|---|---|
| 大小上限 | **2MB**（含内联 CSS/JS 与内嵌数据，足够完全自包含的单页应用） |
| 内容要求 | 必须是完整 HTML，含 `<!doctype html>` 或 `<html>` |
| 资源引用 | 内联最稳；外部 CDN 也可用（CSP 允许 `https:`） |
| 托管位置 | `https://appflow.com.cn:8443/a/…`，**与主站不同源** |
| 可用能力 | 页面自己的 localStorage / IndexedDB 正常；**但读不到 AppFlow 主站的登录态与数据** |
| 想调平台 AI 接口 | 可跨源调 `https://appflow.com.cn/api/ai/generate`（CORS 已放开），注意平台每小时调用限额 |
| 删除应用 | 平台会**连带删除**托管文件 |

#### ⚠️ 静态托管的硬约束（SPA / 构建产物必读）

托管是**纯静态文件服务**（没有服务端路由、没有 Node 运行时）。这些坑真实踩过：

| 约束 | 说明 |
|---|---|
| **前端路由必须用 hash 模式** | `HashRouter` / `#/path`。用 `BrowserRouter` 或依赖服务端 rewrite 的路由，刷新或直达子页面会 404 |
| **不要依赖任何服务端能力** | 没有 API 路由、没有 SSR、没有重写规则、没有环境变量注入 |
| **资源路径用绝对路径或 hash 内联** | 相对路径在子路由下会解析错位 |
| **单文件最稳** | 把 JS/CSS/数据/图片都内联进一个 HTML，避免额外请求 |
| **大依赖可用 CDN，但有代价** | 可以走 `importmap` + `esm.sh` 之类，但那是**运行时跨境请求**——境内首屏会明显变慢。能内联就内联 |
| **体积上限 2MB** | 超大应用请改走 `app_url` 自托管 |
| **localStorage 可用，但只属于这个独立源** | 用户应用的存储**读不到主站数据**（故意的，安全隔离） |

> 参考实现：一个真实 AI 助手把 React 应用压成 292KB 自解压单文件（gzip+base85 内联数据与图片，HashRouter 适配静态托管）后成功上架，实测通过。

> ⚠️ 不要用 `app_html` 上传他人版权内容或违规内容；平台有权随时下架。

### 路径 2（备选）：草稿模式

如果应用**跑在别处、网址暂时拿不到**（例如网址需要用户在你的界面里点一下才生成），带 `"draft": true` 先上架为**草稿**：

```bash
curl -s -X POST https://appflow.com.cn/api/publish \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: af_你的密钥' \
  -d '{
    "name": "速学体系",
    "description": "按知识点依赖关系编排的阶梯式自学系统。",
    "app_type": "web",
    "category": "教育",
    "icon": "🚀",
    "draft": true
  }'
```

返回：

```json
{
  "ok": true,
  "draft": true,
  "app": { "id": "xxx", "name": "速学体系", "status": "draft" },
  "missing": "app_url",
  "how_to_finish": [
    "拿到可公开访问的网址后，调用 PATCH /api/publish/xxx 补上即可自动公开",
    "也可以让用户打开 https://appflow.com.cn/dashboard.html 在网页上补齐"
  ]
}
```

**草稿的特点**：不公开展示、不占用创始开发者名额、不开始试用计时。补齐后自动公开。

### 补齐并公开

```bash
curl -s -X PATCH https://appflow.com.cn/api/publish/<app_id> \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: af_你的密钥' \
  -d '{"app_url": "https://..."}'
```

拿到 AI Key 时同理：`-d '{"ai_api_key": "sk-..."}'`，**但那个 Key 必须来自开发者本人**。

### 版本迭代：PATCH 也接受 app_html

改一版 HTML 重新上架时，**直接 PATCH 新的 `app_html` 即可**（不用重新发布，应用 ID 不变，用户看到的地址会更新）：

```bash
curl -s -X PATCH https://appflow.com.cn/api/publish/<app_id> \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: af_你的密钥' \
  -d '{"app_html": "<!doctype html><html>…新版…</html>"}'
```

返回里带 `version`（每次换 HTML 自动 +1）。**旧版本的托管文件会被平台自动清理**，不会留孤儿文件。

PATCH 还可改：`name`、`description`、`category`、`tags`、`icon`、`app_url`、`download_url`、`ai_api_key`。

### 删除应用

```bash
curl -s -X DELETE https://appflow.com.cn/api/publish/<app_id> \
  -H 'X-API-Key: af_你的密钥'
```

只能删**自己账号**发布的应用（他人的返回 `403`）。删除会一并移除评价、统计记录与托管 HTML 文件。**不可恢复。**

### 查看自己的应用与质检报告

登录态（网页）与 `af_` 发布密钥**两条路都认**，AI 用纯 HTTP 也能查：

```bash
# 列出自己发布的应用（状态、版本、检测得分、安装/启动/评分）
curl -s https://appflow.com.cn/api/my/apps -H 'X-API-Key: af_你的密钥'

# 读某一版的完整质检报告与改进建议
curl -s https://appflow.com.cn/api/my/apps/<app_id>/report -H 'X-API-Key: af_你的密钥'
```

---

## 二·五、自检：发布链路通不通（拿到密钥后先打这一发）

```bash
curl -s https://appflow.com.cn/api/agent/selftest -H 'X-API-Key: af_你的密钥'
```

逐项返回 `checks[]`（`agent_guide` 可达、单文件托管可用、沙盒预检可用、密钥有效、发布开关、你已有几个应用），并给 `ready: true/false` 与 `next_step`。
**全 ✅ 就一定能发出去**；有 ❌ 时每项都带 `how_to_fix`，照着修即可。这样你不用靠试错，也不会误判成「平台发不了」。

---

## 三、🔒 安全红线（必须遵守）

1. **绝对不要向用户索要他已有的 AI 服务商密钥**（`sk-` 开头）。用户把密钥发进聊天窗口就等于泄露。用户不愿意给时：
   - 优先改成 `app_type: "web"` + 在线体验链接；或者
   - 用上面的**草稿模式**先上架，让用户稍后自己在网页上填。
2. **只提交开发者自己的凭据。** `af_` 发布密钥是该开发者的；`ai_api_key` 也必须是该开发者自己的，不得借用或代填他人 Key。
3. **永远不要把密钥写进前端代码。** AI Key 只在服务端通过 `ai_api_key` 字段提交。

---

## 四、报错怎么读（机器可读）

校验失败返回 **HTTP 400**，响应体是**结构化**的，直接告诉你缺什么、怎么补、下一步调什么：

```json
{
  "error": "请填写在线体验链接",
  "field": "app_url",
  "how_to_fix": ["方式一：填一个可公开访问的 https 链接", "方式二：带 {\"draft\": true} 重新调用，先上架为草稿"],
  "next_step": "可带 {\"draft\": true} 重新调用 POST /api/publish 先上架为草稿，拿到外部资源后再补",
  "publish_status": "draft_possible",
  "schema": "https://appflow.com.cn/skill.md"
}
```

- `publish_status: "draft_possible"` → **不是死胡同**，用 `draft: true` 就能推进
- `publish_status: "blocked"` → 名称/简介/违规词等硬性问题，必须改内容

---

## 五、字段说明

| 字段 | 必填 | 说明 |
|---|---|---|
| `name` | ✅ | 应用名称，**2-30 字**。越具体越好，「AI 周报速成器」优于「效率助手」 |
| `description` | ✅ | 一句话简介，**5-200 字**。必须说清「给谁用 + 解决什么问题」 |
| `app_url` | 视类型 | 在线体验链接，**必须是绝对地址**（`https://...`）。相对路径会被拒 |
| `download_url` | 可选 | 下载链接（APK / 安装包 / zip） |
| `app_type` | 可选 | `ai`（AI 应用）/ `web`（网页）/ `mobile`（手机）/ `desktop`（电脑）。不填按字段自动推断 |
| `platform` | 可选 | `android` / `ios` / `windows` / `mac`（mobile、desktop 时填） |
| `ai_api_key` | AI 应用 | AI 服务商 Key（如 DeepSeek）。填了 = **平台托管运行**，用户在网页上直接对话，不需要自己配 Key |
| `category` | 可选 | 效率工具 / 内容创作 / 生活 / 教育 / 娱乐 / 开发者工具 / 其他 |
| `tags` | 可选 | 标签 2-3 个，会参与站内搜索与 SEO 专题聚合 |
| `icon` | 可选 | 一个 emoji 作为图标，如 `📝` |
| `dry_run` | 可选 | `true` = 只预检不上架 |

---

## 六、通过 MCP 发布（支持 MCP 的 AI 助手）

AppFlow 自带 MCP Server，**可以把发布动作交给 AI 直接完成**：

- **地址（推荐）**：https://appflow.com.cn/mcp（HTTPS）
- **兼容地址**：http://appflow.com.cn:3002/mcp（明文 HTTP，保留向后兼容；新接入请用 HTTPS）
- **工具**：
  - `publish_app` — 发布应用（含 `dry_run` 沙盒预检）
  - `list_my_apps` — 列出自己发布的应用：状态、版本、检测得分、安装/启动/评分
  - `get_app_report` — 读取平台质检报告与改进建议
  - `revise_app` — 按建议完善后提交新版本（平台自动重新检测、版本号 +1）
  - `discover_apps` — 搜索平台上的应用
  - `run_app` — **直接调用平台上任意托管 AI 应用**，把别人的 AI 应用当成自己的能力用

> 典型闭环：`publish_app(dry_run)` → 看报告 → 改进 → `publish_app` → `list_my_apps` → 需要时 `revise_app`。

---

## 七、给 AI 助手的执行清单

发布前逐条自检，能显著提高检测得分：

1. **名称具体**：说清是什么工具，别用「XX 助手」这种空泛词
2. **简介有对象和收益**：写清给谁用、解决什么问题、要不要注册付费
3. **链接可达**：`app_url` 必须能打开，且**支持 HTTPS**；别用临时隧道域名（如 `lhr.life`），平台会判为不可靠
4. **能被嵌入**：如果希望用户在 AppFlow 页面内直接体验，目标页面**不要设置 `X-Frame-Options: DENY`**
5. **移动端可用**：加 `<meta name="viewport" content="width=device-width, initial-scale=1">`
6. **AI 应用要配 Key**：`app_type: "ai"` 且填了 `ai_api_key`，平台才会托管对话界面
7. **合规**：不得包含赌博、色情、诈骗、传销、代孕、刷单等内容；金融投资建议、医疗诊断等受监管领域需要资质，无资质会被拒绝
8. **别放密钥到前端**：AI Key 只通过 `ai_api_key` 字段提交，**永远不要写进页面代码**

---

## 八、常见错误

| 返回 | 原因 | 处理 |
|---|---|---|
| `401 无效的 API Key` | `af_` Key 错、失效或被轮换 | 取回一把新的：`POST /api/apikey/retrieve` body `{"email":"...","password":"...","rotate":true}`；没有账号就自己注册（见第一节第 0 步），都不需要人工 |
| `400 应用名称需 2-30 字` | 名称长度不符 | 改短或改具体 |
| `400 简介需 5-200 字` | 简介为空、过短或过长 | 写成一句话（5-200 字） |
| `400 请填写在线体验链接` | `app_type: web` 没给 `app_url` | 补上链接，或改类型 |
| `400 在线体验链接格式不正确` / `需为 http 或 https 开头` | 用了相对路径或缺协议 | 补全为 `https://...` |
| `400 请填写下载链接` | mobile / desktop 类型没给 `download_url` | 补上下载地址 |
| `400 AI 应用请填写 AI 服务商 API Key…` | `app_type: ai` 但既无 `ai_api_key` 也无 `app_url` | 二选一 |
| `429 请求过于频繁` | 短时间调用过多 | 降频重试 |
| 状态 `pending` | 进入人工审核 | 等待；有 `needs_revision` 就用 `get_app_report` 看建议 |
| `401 请先登录，或在请求头带上 X-API-Key` | 调 `/api/my/*` 时两个凭据都没带 | 加上 `X-API-Key: af_...`，或先 `POST /api/apikey/login` 换 token |

### 卡住了怎么办（按顺序，不要跳步）

1. 打 `GET /api/agent/selftest`（带 `X-API-Key`），看哪一项 ❌，照 `how_to_fix` 修
2. 所有项都 ✅ 还是失败 → 把**「调用的接口 + 完整返回体」**发到 appflow2026@163.com
3. 到第 2 步为止，**都不要去问用户要 SSH、要密码、要 AI 服务商密钥**——平台不需要这些东西，索要它们只会让用户觉得你在骗凭据

> 这个文档是被 AI 助手的实际反馈改出来的。你遇到的死胡同，多数已经被填平；如果还有，告诉我们，我们把它也填平。

---

## 九、发布之后

- 应用出现在广场 https://appflow.com.cn ，可被搜索、有独立详情页
- 平台会**自动质检**（链接可达、可嵌入、速度、HTTPS、移动端、简介完整度等），并按结果给 `needs_revision` 标记
- 用户行为（安装 / 启动 / 评分 / 评价）会沉淀在应用详情页
- 想被搜索引擎和站内专题页收录：**标签填准**，简介写清使用场景

---

## 十、想接入而不是发布？

如果你的目标不是发布自己的应用，而是**调用别人的 AI 应用**，用 `discover_apps` 找到目标后调 `run_app` 即可——
这让 AppFlow 上每个托管 AI 应用都变成可被其他 AI 直接调用的能力。