alibabacloud-wxz-website-builder

类别：服务

AI 员工网站构建器

验证

mkdir -p output/alibabacloud-wxz-website-builder
for f in skills/ai/service/alibabacloud-wxz-website-builder/scripts/*.py; do
  python3 -m py_compile "$f"
done
echo "py_compile_ok" > output/alibabacloud-wxz-website-builder/validate.txt

通过标准：命令以状态码 0 退出，并生成 output/alibabacloud-wxz-website-builder/validate.txt。

输出与证据

• 将列表/摘要输出保存在 output/alibabacloud-wxz-website-builder/ 下。
• 在每个证据文件中保留对话 ID 和事件摘要。

前提条件

pip install -r requirements.txt

• requirements.txt 中的所有依赖项都已固定为确切版本。
• 凭证通过默认凭证链解析（无需显式提供 AK/SK）。

身份验证

此技能依赖 Alibaba Cloud 默认凭证链。请勿显式设置 AK/SK。SDK 会按以下顺序自动解析凭证：

1. 环境变量：ALIBABACLOUD_ACCESS_KEY_ID / ALIBABACLOUD_ACCESS_KEY_SECRET
2. 共享配置文件：~/.alibabacloud/credentials
3. RAM 角色 / ECS 元数据服务（在 Alibaba Cloud 实例上运行时）

区域：ALIBABACLOUD_REGION_ID 默认值为 cn-hangzhou。

如何获取 AccessKey（如果用户还没有）

如果用户还没有 AccessKey，请引导其完成以下步骤（完整详情请参阅 references/ak-setup-guide.md）：

1. 登录：打开 https://www.aliyun.com 并登录（或注册）
2. 创建 RAM 用户：前往 https://ram.console.aliyun.com/users → “创建用户” → 勾选“OpenAPI 访问” → 立即保存 AK/SK（Secret 只会显示一次！）
3. 授予权限：添加自定义策略，并包含以下 Actions（遵循最小权限原则）：
   • zero2staff:CreateAIStaffConversation
   • zero2staff:CreateAIStaffChat
   • zero2staff:ListAIStaffChatEvents
   • zero2staff:ListAIStaffChatMessages
   • zero2staff:GetAIStaffPreviewUrl
4. 配置：写入 ~/.alibabacloud/credentials 或设置环境变量

重要：引导用户时，请提醒他们：

• 请勿使用根账户 AccessKey——始终使用 RAM 子用户
• 立即保存 AccessKey Secret——创建期间它只会显示一次
• 切勿将 AccessKey 提交到 git

如果用户遇到身份验证错误，请参阅 references/ak-setup-guide.md 中的故障排除表。

---

应用生命周期

完整流程分为 3 个阶段。请按顺序执行。

重要——由 Agent 驱动轮询：chat 命令会发起请求并立即返回。随后由 Agent 通过 poll 命令驱动轮询循环。每次轮询之间，Agent 必须向用户显示进度消息，让他们了解当前进展（使用 progressDetail 提供详细消息）。

Phase 1: Create Conversation
        ↓
Phase 2: Fire requirement chat → poll → HITL → Fire resume → poll → ... → PRD ready
        ↓
Phase 3: Fire code generation → Show link → poll loop with progress → Get preview URL → Done

阶段 0：身份验证设置

确保已通过默认凭证链配置 Alibaba Cloud 凭证（请参阅上方的“身份验证”部分）。

阶段 1：创建对话

任何聊天操作之前都必须先创建对话：

CONV=$(python scripts/aistaff_api.py create-conversation --text "build a popmart homepage")
CONV_ID=$(echo $CONV | jq -r '.ConversationId')
CHAT_ID=$(echo $CONV | jq -r '.ChatId')
SITE_ID=$(echo $CONV | jq -r '.SiteId')

返回扁平 JSON：{ConversationId, SiteId, ChatId, SectionId, BotId, Title}。

阶段 2：需求收集 + PRD

此阶段会收集需求并生成 PRD。平台可能会进行多轮 HITL（基本信息 → 功能 → 语言等）。为加快流程：

• 只向用户展示第一轮 HITL（项目基本信息）。
• 之后所有 HITL 轮次都必须使用表单中的默认值/预选值自动填写，并立即继续——请勿询问用户。

步骤 1：发起需求收集

python scripts/aistaff_api.py chat \
  --text "build a popmart homepage" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID

告知用户：“正在分析您的需求，请稍候……”

步骤 2：轮询，直到收到第一份 HITL 表单

每隔 5 秒调用一次 poll，直到 phase 为 waiting_for_input：

python scripts/aistaff_api.py poll \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --last-event-id 0

每次轮询之间，根据 phase 向用户显示进度消息：

• processing → “正在分析需求……”
• fetching_reference → “正在获取参考网站信息……”
• waiting_for_input → 已收到第一份 HITL 表单，继续执行步骤 3。

步骤 3：首次 HITL — 收集用户答案

从 name: "AskUserQuestion" 的 message.tool 事件的 metaData.arguments 中提取 questions。通过 AskUserQuestion 工具向用户展示这些问题（通常包括：应用名称、业务描述、目标用户、参考网站）。

步骤 4：使用 --phase generate_prd 触发恢复

重要：首次 HITL 恢复时，始终传入 --phase generate_prd --user-navigation generate_prd。

python scripts/aistaff_api.py chat \
  --text '{"App Name": "POP MART Official", "Main Service": "Trendy Toys", "Target Users": "Gen Z trendsetters", "Reference Site": "None"}' \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --chat-id $CHAT_ID \
  --chat-status interrupt \
  --phase generate_prd \
  --user-navigation generate_prd \
  --hidden --without-refer

--text 中的 JSON 键必须与表单中的 header 值一致。

告知用户：“已收到需求，正在生成产品计划……”

步骤 5：轮询循环 — 自动填写后续 HITL 轮次，直至 PRD 就绪

每 5 秒轮询一次。根据 phase / summary 采取相应操作：

• phase == "waiting_for_input"（另一个 HITL 问题）→ 使用 AskUserQuestion 事件中的 answers 字段立即自动填写，然后再次触发恢复。告知用户：“正在完善需求详情……”
• phase == "generating_prd" → 告知用户：“正在生成 PRD，请稍候……”
• phase == "fetching_reference" → 告知用户：“正在获取参考资料……”
• summary.chatStatus == "success" + summary.hasPrd == true → PRD 已就绪，继续进入阶段 3。
• summary.chatStatus == "fail" → 询问用户是否重试。

# Poll:
python scripts/aistaff_api.py poll \
  --conversation-id $CONV_ID --biz-id $SITE_ID --last-event-id $LAST_EVENT_ID

# Auto-fill (use the "answers" field from the AskUserQuestion event):
python scripts/aistaff_api.py chat \
  --text '{"Core Features": ["Product Showcase", "Brand Story", "News"]}' \
  --conversation-id $CONV_ID --biz-id $SITE_ID --chat-id $CHAT_ID \
  --chat-status interrupt --phase generate_prd \
  --user-navigation generate_prd --hidden --without-refer

关键规则：平台的 AskUserQuestion 事件始终包含一个 answers 字段，其中提供了合理的默认值。首次之后的轮次中，始终直接使用这些默认值，而不是询问用户。

阶段 3：代码生成

PRD 就绪后：

步骤 1：触发代码生成

python scripts/aistaff_api.py chat \
  --text "Confirm app generation" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --phase generate_code \
  --without-refer

步骤 2：立即显示站点链接

必须在代码生成前后都显示：

https://wanwang.aliyun.com/webdesign/home#/ai/manage/prd?conversationId=<CONV_ID>

告知用户：“代码生成已开始。通常需要 2–5 分钟。您可以通过上面的链接查看项目，我会继续跟踪进度……”

步骤 3：轮询循环并更新进度

每 10 秒轮询一次。每次轮询之间向用户展示进度：

python scripts/aistaff_api.py poll \
  --conversation-id $CONV_ID --biz-id $SITE_ID --last-event-id $LAST_EVENT_ID

进度消息（使用 progressDetail 展示详细消息）：

• phase == "processing" + 存在 latestFile → “正在生成代码……正在编写：{latestFile.semantic}（已生成 {filesWrittenCount} 个文件）”
• phase == "processing" + 不存在 latestFile → “正在生成代码……已处理 N 个事件”
• phase == "processing" + 存在 lastMessage → 同时展示助手的最新消息作为上下文
• phase == "success" → 站点已就绪！继续执行步骤 4。
• phase == "fail" → 询问用户是否重试。

步骤 4：获取预览 URL

代码生成完成后（summary.chatStatus == "success"），必须调用此项。它会启动预览沙盒并返回实时预览 URL。

PREVIEW=$(python scripts/aistaff_api.py get-preview-url --conversation-id $CONV_ID)
PREVIEW_URL=$(echo $PREVIEW | jq -r '.urlMap.https // .urlMap.http // empty')

告知用户：“站点已构建！正在获取预览 URL……”

沙盒启动时，首次调用可能需要几秒钟。如果预览 URL 尚不可用，请在 10 秒后重试（最多重试 3 次）。展示预览 URL：“预览 URL：{PREVIEW_URL}”

--restart：传入 --restart 可在沙盒中重启应用（例如，修改后）。初始构建时无需使用。

步骤 5：处理完成状态

• summary.chatStatus == "success" → 站点已就绪。展示站点链接和预览 URL。
• summary.chatStatus == "fail" 或 summary.hasError == true → 询问用户是否重试。不要自动重试。

初始生成后

• 使用带有 --conversation-id 的 chat 修改站点。
• 每次修改都使用相同的 chat + 轮询模式。
• 每次修改完成后，调用 get-preview-url --restart 刷新预览。
• 每次修改后再次展示站点链接和预览 URL。

---

决策表

summary.chatStatus	summary.hasPrd	阶段	操作
interrupt	—	2（第一轮）	解析 AskUserQuestion，从用户处收集答案，使用 --phase generate_prd 恢复
interrupt	—	2（后续轮次）	使用 AskUserQuestion 事件中的默认 answers 自动填充，立即恢复——不要询问用户
success	true	2	PRD 已就绪 → 继续阶段 3
success	false	3	站点已就绪 → 调用 get-preview-url → 显示链接和预览 URL
fail	—	任意	询问用户是否重试
unknown	—	任意	轮询超时 → 使用 list-messages 作为回退方案

---

可用命令

create-conversation

python scripts/aistaff_api.py create-conversation --text "user question"

返回：{ConversationId, SiteId, ChatId, SectionId, BotId, Title}。

chat

发送异步聊天消息并立即返回。发送前会自动清空旧的 SSE 事件。之后使用 poll 跟踪进度。

python scripts/aistaff_api.py chat --text "description" --conversation-id <ID> --biz-id <ID> [options]

关键参数：

• --text TEXT：消息文本或表单答案 JSON（必需）
• --conversation-id ID / --biz-id ID：必需的标识符
• --chat-id ID + --chat-status interrupt：用于 HITL 恢复
• --phase {requirement_collect,generate_prd,generate_code}：要进入的阶段
• --user-navigation TARGET：导航目标（使用 generate_prd，并搭配 --phase generate_prd）
• --hidden / --without-refer：隐藏消息 / 跳过参考上下文
• --verbose：显示调试信息

返回：{conversationId, chatId, status: "fired", error}。

poll

单次状态检查——仅获取一次新事件并检查消息状态，然后立即返回。专为由 Agent 驱动的轮询循环设计。

python scripts/aistaff_api.py poll --conversation-id <ID> --biz-id <ID> [--last-event-id N]

关键参数：

• --last-event-id N：上一次轮询的游标（默认值：0）。传入上一次 poll 结果中的 lastEventId。
• --max-output-events N：限制输出中的事件数量（默认值：10，0=不限制）

返回： {conversationId, lastEventId, newEvents, phase, summary, progressDetail, events}

summary 字段： chatStatus、hasError、errorMsg、hasPrd、toolsCalled

progressDetail 字段——使用这些字段生成清晰的进度消息：

• filesWrittenCount：目前已生成的文件总数
• activeTools：正在执行的工具（status=wait）。全部完成时为空
• latestFile：{path, semantic, status} — 最近正在写入的文件（向用户展示 semantic）
• allFiles：已写入文件的完整列表，每项包含 path 和 semantic
• lastMessage：助手最新的文本消息（截断为 200 个字符）
• toolProgress：各工具的状态列表，包含 name、status（wait/done）、semantic

建议的进度消息：

• latestFile.status == "wait"："正在生成：{latestFile.semantic}..."
• latestFile.status == "done" 且 activeTools 为空："{filesWrittenCount} 个文件已完成，等待下一步..."
• filesWrittenCount > 0 且 activeTools 不为空："正在生成代码... 已完成 {filesWrittenCount} 个文件，正在写入：{latestFile.semantic}"
• lastMessage 不为空：将其作为补充上下文显示

phase 的取值：

阶段	含义	建议的用户消息
processing	一般处理中	"正在处理..."
fetching_reference	正在获取参考站点	"正在获取参考站点信息..."
waiting_for_input	HITL 表单已就绪	（解析表单并处理）
generating_prd	正在生成 PRD	"正在生成 PRD..."
success	已成功完成	"完成！"
fail	失败	（询问用户是否重试）

list-messages

查询最新的聊天消息。返回最后 N 条消息（默认值：10）。

python scripts/aistaff_api.py list-messages --conversation-id <ID> [--tail 10]

主要用途：当 poll 没有显示进度时，用此命令检查最后一条消息的 ChatStatus。

get-preview-url

代码生成后获取实时预览 URL。如有需要，会启动沙箱。

python scripts/aistaff_api.py get-preview-url --conversation-id <ID> [--restart]

参数： --conversation-id ID（必需）、--restart（在沙箱中重启应用，修改后很有用）

返回： {urlMap: {https: "...", http: "...", sessionId: "..."}}

在第 3 阶段中，chatStatus == "success" 后必须调用。首次调用可能需要几秒钟（启动沙箱）。如果 URL 为空，10 秒后重试（最多重试 3 次）。

---

SSE 事件限制

• 每轮新的聊天都可能清除之前的 SSE 事件。chat 命令会在触发前自动清空旧事件。
• 使用 poll 时，传入上一次轮询结果中的 lastEventId，以避免重复处理事件。
• 代码生成期间，平台可能会自动触发多轮“magic fix”。poll 命令会通过事件摘要检测到这一情况。

---

错误处理

错误	操作
身份验证错误	确保已通过默认凭据链配置凭据（环境变量、配置文件或 RAM 角色）
summary.chatStatus == "fail"	询问用户是否重试。不要自动重试
轮询显示 5 分钟以上没有进展	使用 list-messages 检查实际状态