从零到发布：用 AI Agent 构建热门短剧展示应用并发布到华为云作品展览馆

本文记录了一次完整的实战体验：从一句自然语言需求出发，通过 AI Agent 自动生成代码、启动预览、推送到 GitCode 仓库，最终发布到华为云开发者作品展览馆的全流程。涵盖 CodeArts ACP 协议交互、DevBridge 隧道、IAM STS 临时凭证、自动化封面截图等多个技术细节。

一、需求背景

短剧是当下最热门的内容形态之一。本次实战的目标是构建一个"热门短剧展示"Web 应用，界面风格对标抖音/快手等短视频平台，让用户能以沉浸式的竖屏滑动方式浏览短剧内容。

核心需求：

• 竖屏全屏滑动浏览，上下切换不同短剧
• 右侧悬浮操作栏：点赞、评论、收藏、分享
• 顶部导航：推荐、热门、追剧、分类
• 深色主题，渐变色封面，沉浸式体验
• 纯前端实现，无需框架和构建工具

二、技术方案选型

2.1 为什么选纯 HTML + CSS + JavaScript？

短剧展示应用的核心是视觉呈现和滑动交互，没有复杂的状态管理或数据持久化需求。纯前端三件套足以胜任，且具备以下优势：

• 零依赖：不需要 npm install，不需要构建工具，python3 -m http.server 即可启动
• 即开即用：生成的代码可以直接在任何浏览器打开
• 部署简单：静态文件可以托管在任意 Web 服务器或对象存储上

2.2 为什么用 AI Agent 而非手写？

这个应用虽然技术栈简单，但涉及大量重复性的 UI 代码——12 部短剧的数据、渐变色配置、动画效果、交互逻辑。AI Agent（本例中通过 CodeArts ACP 协议连接的码道服务）能够：

• 一次性理解完整需求，生成三个文件（index.html + style.css + app.js）
• 自动设计数据结构，填充 12 部短剧的完整信息
• 处理 CSS 动画、触摸滑动、滚轮事件等细节
• 自动检测端口可用性并启动服务

三、CodeArts ACP 协议：让 AI 写代码的正确姿势

3.1 什么是 ACP？

ACP（Agent Communication Protocol）是码道（CodeArts）提供的 Agent 通信协议。它通过 WebSocket 桥接，让外部 Agent 能够与码道沙箱中的 AI 编码服务交互。架构如下：

Agent（本机）→ acpws（WebSocket 桥接）→ CodeArts ACP 服务（沙箱内 :19300）

3.2 交互流程

完整的交互流程分为五步：

第一步：健康检查

curl -s --max-time 3 http://127.0.0.1:19300/healthz
# 返回 ok 表示服务可用

第二步：获取沙箱路径

沙箱路径从 registry.json 读取，而非通过 pgrep 或 readlink 推断。这是一个容易踩坑的点——沙箱使用 bwrap 创建独立的挂载命名空间，从宿主机视角看项目目录是空的，但文件实际存在于沙箱的命名空间内。

SANDBOX_DIR=$(python3 -c "
import json
with open('/root/job-envs/registry.json') as f:
    for entry in json.load(f):
        if entry.get('id') == 'codearts':
            print(entry['cwd']); break
")

第三步：创建会话

npx acpx --cwd "$PROJECT_DIR" --agent "$MIRROR" --approve-all sessions new

--approve-all 表示自动批准所有操作（沙箱环境，安全可控）。会话创建后可以复用，不需要重复创建。

第四步：发送指令并静默监控

这是最关键的一步。指令需要包含完整的需求描述——技术栈、功能列表、视觉设计、文件结构、启动方式。越详细，生成质量越高。

监控过程中有一个重要的超时协议：

第五步：验证产物

CodeArts 完成后，通过 curl 验证服务是否正常返回内容：

curl -s --max-time 5 http://127.0.0.1:8080/ | head -30

3.3 沙箱文件访问的坑

本次实战中遇到一个关键问题：从宿主机 ls 项目目录显示为空，但 HTTP 服务正常返回内容。原因是 bwrap 沙箱使用了独立的挂载命名空间。

解决方案是通过 /proc/<PID>/root/ 访问沙箱内的文件系统：

PID=$(pgrep -f "python3.*http.server" | head -1)
ls /proc/$PID/root/root/job-envs/sandboxes/.../short-drama-show/
# app.js  index.html  style.css

这个细节在后续发布流程中很重要——需要把文件从沙箱命名空间复制到宿主机可访问的目录，才能进行 Git 初始化和发布。

四、应用设计细节

4.1 竖屏滑动浏览

核心交互是上下滑动切换短剧。实现思路：

• 每个短剧卡片高度 100vh，占满整个视口
• 监听 wheel 事件和 touchmove/touchend 事件
• 通过 CSS transform: translateY() 实现平滑过渡
• 添加防抖逻辑避免快速连续触发

4.2 渐变色封面

不使用真实图片，而是为每个短剧生成独特的 CSS 渐变色：

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

12 部短剧各有不同的渐变色组合，视觉区分度高且零网络开销。

4.3 悬浮操作栏

右侧操作栏的按钮使用白色半透明圆形背景，符合短视频平台的交互习惯：

.action-btn {
    width: 48px;
    height: 48px;
    border-radius: 50%;
    background: rgba(255, 255, 255, 0.2);
    display: flex;
    align-items: center;
    justify-content: center;
}

点赞按钮点击时触发爱心缩放动画，通过 CSS keyframes 实现。

五、发布到作品展览馆：八步流水线

发布到华为云开发者作品展览馆是一个八步流水线，涉及 IAM 认证、Git 仓库、自动化截图、详情打包等多个环节。

5.1 Step 1：IAM Domain ID 解析与 STS 凭证生成

发布需要华为云账号身份。流程是：

1. 通过 hcloud CLI 调用 IAM KeystoneListAuthDomains 获取 Domain ID
2. 创建 IAM 自委托（SELF_VERIFY），生成 STS 临时凭证（有效期 900 秒）
3. 永久 AK/SK 留在本地不上传，只传临时凭证

这种设计遵循了最小权限原则——临时凭证有过期时间，即使泄露风险也可控。

5.2 Step 2：DevBridge 隧道

为了让作品展览馆的审核系统能访问到本地运行的应用，需要通过 DevBridge 开发隧道暴露端口。

DevBridge 的架构是通过华为云中继服务实现的内网穿透：

本地服务 :8080 → DevBridge 沙箱 → 华为云中继 → 公网 URL

创建隧道的 API 调用链：

TUNNEL_ID=$(db_create "short-drama-tunnel" "短剧展示隧道" 72)
db_port_create "$TUNNEL_ID" 8080 auto true   # 匿名访问
db_host "$TUNNEL_ID"                           # 启动托管
TUNNEL_URL=$(db_tunnel_url "$TUNNEL_ID")       # 获取公网 URL

关键注意点：中继域名随集群变化，严禁按文档拼接 URL，必须通过 db_tunnel_url 从进程日志中读取权威地址。

5.3 Step 3：GitCode 仓库

发布要求代码托管在 GitCode 上。流程：

1. 检测 GitCode 凭证——如果没有，启动 OAuth 两阶段授权
2. OAuth 授权：生成登录链接和二维码，用户在浏览器中授权
3. 创建仓库并推送代码

OAuth 流程的一个细节：脚本本地启动回调服务器，用户在任意浏览器授权后自动拿到 token，Agent 全程不需要内置浏览器。

5.4 Step 4：自动化封面截图

这是整个流程中最精巧的部分。封面生成需要：

1. Preflight：安装 Chromium + CJK 字体（首次约 2 分钟）
2. UTF-8 门禁：检查所有源文件编码
3. 截图：用 Playwright 驱动 Chromium 访问本地 URL，截取页面
4. 合成：将截图与标题、标签叠加合成为 16:9 封面图
5. 字形校验：像素级检查中文是否渲染为"豆腐块"

封面布局有多种方案（glass、flat、gradient 等），脚本根据项目页数自动选择单图或多图布局。

5.5 Step 5-6：简介与详情包

• 简介：从 README 提取，限制 15-50 个中文字符，脚本自动计数验证
• 详情包：生成 500-1500 字的详解文章 + 系统架构图，打包为 zip

架构图用 HTML + CSS 绘制，通过 Playwright 截图为 PNG。这里有一个隐性依赖——generate_diagram.py 依赖 preflight 安装的 Chromium 和字体，如果 preflight 未完成就跑图表生成会失败。

5.6 Step 7-8：活动选择与发布

从 43 个活动中选择目标活动，然后执行最终发布：

node publish-work.mjs /tmp/publish-params.json --max-age 3600

发布参数包括 STS 凭证、作品信息、封面、详情包、Git URL、隧道 URL 等，全部通过 UTF-8 JSON 传递。发布成功返回 HTTP 201 和作品 ID。

六、技术心得与反思

6.1 AI 生成代码的质量

本次 CodeArts 生成的代码质量令人满意：

• 三个文件总计约 992 行，结构清晰
• CSS 动画效果完整实现，包括滑动过渡、点赞动画
• 12 部短剧数据涵盖当前主流题材，内容丰富
• 交互逻辑正确，滚轮和触摸事件都有处理

6.2 沙箱隔离的双刃剑

bwrap 沙箱提供了安全隔离，但也带来了文件访问的复杂性。从宿主机视角看不到沙箱内创建的文件，需要通过 /proc 命名空间访问。这在需要将沙箱内产物传递到外部流程时是一个需要特别注意的点。

6.3 自动化流水线的价值

整个发布流程涉及 8 个步骤、十余个脚本调用，但通过 skill 的封装，Agent 能够自动编排执行，只在需要用户交互时（OAuth 授权、活动选择）暂停。这种"自动编排 + 关键节点人工确认"的模式，是 AI Agent 落地的有效范式。

6.4 STS 临时凭证的安全设计

使用自委托 SELF_VERIFY 生成 STS 临时凭证，而非直接使用永久 AK/SK，是一个值得学习的安全实践。临时凭证有效期 900 秒，且包含自动刷新机制（401 时自动刷新），既保证了安全性又不影响使用体验。

七、总结

本次实战完整走过了从需求到发布的全链路：

1. 需求理解：一句自然语言描述，Agent 自动拆解为技术方案
2. 代码生成：通过 CodeArts ACP 协议，AI 自动生成完整项目
3. 本地预览：自动启动 HTTP 服务，构造可访问 URL
4. 代码托管：OAuth 授权 GitCode，创建仓库并推送
5. 隧道穿透：DevBridge 创建公网可访问隧道
6. 自动化截图：Playwright + Chromium 自动生成封面
7. 发布上线：通过 STS 凭证调用 Gallery API 完成发布

整个过程约 30 分钟，其中大部分时间是 preflight 安装 Chromium 和字体。如果环境已预热，整个流程可以压缩到 10 分钟以内。

这展示了 AI Agent 在开发效率上的巨大潜力——不是替代开发者，而是将重复性的工程流程自动化，让开发者专注于需求和设计。