alibabacloud-wxz-website-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Category: service

AI Staff Website Builder (零号员工建站)

AI Staff 网站构建工具（零号员工建站）

Validation

验证

bash

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

Pass criteria: command exits 0 and

output/alibabacloud-wxz-website-builder/validate.txt

is generated.

bash

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 And Evidence

输出与证据

Save list/summarize outputs under

output/alibabacloud-wxz-website-builder/

Keep conversation IDs and event summaries in each evidence file.

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

Prerequisites

前置依赖

bash

pip install alibabacloud_tea_openapi>=0.4.4 alibabacloud_tea_util>=0.3.14

Credentials are resolved via the default credential chain (no explicit AK/SK needed).

bash

pip install alibabacloud_tea_openapi>=0.4.4 alibabacloud_tea_util>=0.3.14

通过默认凭证链解析凭证（无需显式配置AK/SK）。

Authentication

认证

This skill relies on the Alibaba Cloud default credential chain. Do NOT set AK/SK explicitly. The SDK automatically resolves credentials in the following order:

Environment variables:

ALIBABACLOUD_ACCESS_KEY_ID

ALIBABACLOUD_ACCESS_KEY_SECRET

Shared config file:
```
~/.alibabacloud/credentials
```
RAM role / ECS metadata service (when running on Alibaba Cloud instances)

Region:

ALIBABACLOUD_REGION_ID

defaults to

cn-hangzhou

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

环境变量：

ALIBABACLOUD_ACCESS_KEY_ID

ALIBABACLOUD_ACCESS_KEY_SECRET

共享配置文件：
```
~/.alibabacloud/credentials
```
RAM角色/ECS元数据服务（当运行在阿里云实例上时）

地域：

ALIBABACLOUD_REGION_ID

默认值为

cn-hangzhou

。

How to obtain AccessKey (if user doesn't have one)

如何获取AccessKey（若用户尚未拥有）

If the user has no AccessKey yet, guide them through these steps (see

references/ak-setup-guide.md

for full details):

Login: Open https://www.aliyun.com and log in (or register)
Create RAM user: Go to https://ram.console.aliyun.com/users → "Create User" → check "OpenAPI Access" → save the AK/SK immediately (Secret is only shown once!)

Grant permissions: Add a custom policy with the following Actions (least-privilege):

```
zero2staff:CreateAIStaffConversation
```
```
zero2staff:CreateAIStaffChat
```
```
zero2staff:ListAIStaffChatEvents
```
```
zero2staff:ListAIStaffChatMessages
```

Configure: Write to
```
~/.alibabacloud/credentials
```
or set environment variables

CRITICAL: When guiding the user, remind them:

Do NOT use root account AccessKey — always use RAM sub-user
Save the AccessKey Secret immediately — it's only shown once during creation
Never commit AccessKey to git

If the user encounters auth errors, refer to the troubleshooting table in

references/ak-setup-guide.md

如果用户尚未拥有AccessKey，请引导他们完成以下步骤（完整细节请查看

references/ak-setup-guide.md

）：

登录：打开https://www.aliyun.com并登录（或注册）
创建RAM用户：访问https://ram.console.aliyun.com/users → "创建用户" → 勾选"OpenAPI调用访问" → 立即保存AK/SK（Secret仅会显示一次！）

授予权限：添加包含以下操作的自定义策略（最小权限原则）：

```
zero2staff:CreateAIStaffConversation
```
```
zero2staff:CreateAIStaffChat
```
```
zero2staff:ListAIStaffChatEvents
```
```
zero2staff:ListAIStaffChatMessages
```

配置：写入
```
~/.alibabacloud/credentials
```
文件或设置环境变量

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

请勿使用根账号AccessKey — 务必使用RAM子用户
立即保存AccessKey Secret — 它仅在创建时显示一次
切勿将AccessKey提交至git仓库

如果用户遇到认证错误，请参考

references/ak-setup-guide.md

中的故障排查表。

Application Lifecycle

应用生命周期

The complete flow has 3 phases. Follow them sequentially.

IMPORTANT — Agent-driven polling: The

chat

command fires the request and returns immediately. The agent then drives the polling loop via the

poll

command. Between each poll, the agent MUST show the user a progress message so they know what's happening (use

progressDetail

for rich messages).

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 → Site ready

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

重要说明 — 由Agent驱动的轮询：

chat

命令发送请求后立即返回。随后由Agent通过

poll

命令驱动轮询循环。每次轮询之间，Agent必须向用户显示进度消息，让用户了解当前状态（使用

progressDetail

生成丰富的消息内容）。

阶段1：创建对话
        ↓
阶段2：触发需求聊天 → 轮询 → HITL人工介入 → 触发恢复 → 轮询 → ... → PRD生成完成
        ↓
阶段3：触发代码生成 → 展示链接 → 带进度的轮询循环 → 网站就绪

Phase 0: Auth Setup

阶段0：认证配置

Ensure Alibaba Cloud credentials are configured via the default credential chain (see Authentication section above).

确保已通过默认凭证链配置阿里云凭证（请查看上文的认证部分）。

Phase 1: Create Conversation

阶段1：创建对话

MUST create a conversation before any chat operation:

bash

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

Returns flat JSON:

{ConversationId, SiteId, ChatId, SectionId, BotId, Title}

必须在执行任何聊天操作前创建对话：

bash

CONV=$(python scripts/aistaff_api.py create-conversation --text "做个popmart首页")
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}

。

Phase 2: Requirement Collection + PRD

阶段2：需求收集 + PRD生成

This phase collects requirements and generates a PRD. The platform may ask multiple HITL rounds (basic info → features → language, etc.). To keep things fast:

Only the first HITL round should be shown to the user (basic project info).
All subsequent HITL rounds must be auto-filled with the form's default/pre-selected values and resumed immediately — do NOT ask the user.

本阶段用于收集需求并生成PRD。平台可能会发起多轮HITL人工介入（基础信息 → 功能 → 语言等）。为提升效率：

仅第一轮HITL需要展示给用户（基础项目信息）。
后续所有HITL轮次必须自动填充表单的默认/预选值并立即恢复流程 — 请勿询问用户。

Step 1: Fire requirement collection

步骤1：触发需求收集

bash

python scripts/aistaff_api.py chat \
  --text "做个popmart首页" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID

Tell user: "正在分析您的需求，请稍候..."

bash

python scripts/aistaff_api.py chat \
  --text "做个popmart首页" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID

告知用户："正在分析您的需求，请稍候..."

Step 2: Poll until first HITL form arrives

步骤2：轮询直至第一轮HITL表单出现

Call

poll

every 5 seconds until

phase

waiting_for_input

bash

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

Between each poll, show the user a progress message based on

phase

```
processing
```
→ "需求分析进行中..."
```
fetching_reference
```
→ "正在获取参考网站信息..."
```
waiting_for_input
```
→ First HITL form arrived, proceed to Step 3.

每5秒调用一次

poll

，直到

phase

变为

waiting_for_input

：

bash

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。

Step 3: First HITL — collect answers from user

步骤3：第一轮HITL — 收集用户回答

Extract

questions

from the

metaData.arguments

of the

message.tool

event where

name: "AskUserQuestion"

. Present these questions to the user via the AskUserQuestion tool (typically: app name, business description, target users, reference site).

从

message.tool

事件的

metaData.arguments

中提取

questions

（该事件的

name

为"AskUserQuestion"）。通过AskUserQuestion工具将这些问题展示给用户（通常包括：应用名称、业务描述、目标用户、参考网站）。

Step 4: Fire resume with

--phase generate_prd

步骤4：触发恢复并传入

--phase generate_prd

CRITICAL: On the first HITL resume, always pass

--phase generate_prd --user-navigation generate_prd

bash

python scripts/aistaff_api.py chat \
  --text '{"应用名称": "POP MART 官网", "主营服务": "潮流玩具", "目标用户": "Z世代潮流青年", "参考网站": "无"}' \
  --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

The

--text

JSON keys MUST match the
header
values from the form.

Tell user: "已收到您的需求，正在生成产品方案..."

关键要求：在第一轮HITL恢复时，必须传入

--phase generate_prd --user-navigation generate_prd

。

bash

python scripts/aistaff_api.py chat \
  --text '{"应用名称": "POP MART 官网", "主营服务": "潮流玩具", "目标用户": "Z世代潮流青年", "参考网站": "无"}' \
  --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
值匹配。

告知用户："已收到您的需求，正在生成产品方案..."

Step 5: Poll loop — auto-fill subsequent HITL rounds until PRD is ready

步骤5：轮询循环 — 自动填充后续HITL轮次直至PRD生成完成

Poll every 5 seconds. Based on

phase

summary

, take action:

```
phase == "waiting_for_input"
```
(another HITL question) → Auto-fill immediately using the
```
answers
```
field from the
```
AskUserQuestion
```
event, then fire resume again. Tell user: "正在完善需求细节..."
```
phase == "generating_prd"
```
→ Tell user: "PRD 方案生成中，请稍候..."
```
phase == "fetching_reference"
```
→ Tell user: "正在获取参考资料..."

summary.chatStatus == "success"

summary.hasPrd == true

→ PRD ready, proceed to Phase 3.

```
summary.chatStatus == "fail"
```
→ Ask user whether to retry.

bash

undefined

每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"
```
→ 询问用户是否重试。

bash

undefined

Poll example:

轮询示例:

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

Auto-fill example (use the "answers" field from the AskUserQuestion event):

自动填充示例（使用AskUserQuestion事件中的"answers"字段）:

python scripts/aistaff_api.py chat
--text '{"核心功能": ["商品展示", "品牌故事", "新闻资讯"]}'
--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


**Key rule**: The platform's `AskUserQuestion` event always includes an `answers` field with sensible defaults. For rounds after the first, always use these defaults directly instead of prompting the user.


**核心规则**：平台的AskUserQuestion事件始终包含带有合理默认值的`answers`字段。对于第一轮之后的轮次，请直接使用这些默认值，无需提示用户。

Phase 3: Code Generation

阶段3：代码生成

When PRD is ready:

当PRD生成完成后：

Step 1: Fire code generation

步骤1：触发代码生成

bash

python scripts/aistaff_api.py chat \
  --text "确认生成应用" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --phase generate_code \
  --without-refer

bash

python scripts/aistaff_api.py chat \
  --text "确认生成应用" \
  --conversation-id $CONV_ID \
  --biz-id $SITE_ID \
  --phase generate_code \
  --without-refer

Step 2: Show site link immediately

步骤2：立即展示网站链接

MUST show before and after code generation:

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

Tell user: "代码生成已启动，通常需要 2-5 分钟。您可以先通过上面的链接查看项目，我会持续跟踪进度..."

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

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

告知用户："代码生成已启动，通常需要 2-5 分钟。您可以先通过上面的链接查看项目，我会持续跟踪进度..."

Step 3: Poll loop with progress updates

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

Poll every 10 seconds. Show the user progress between each poll:

bash

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

Progress messages to show (use

progressDetail

for rich messages):

```
phase == "processing"
```
+
```
progressDetail.latestFile
```
exists → "代码生成中...正在写入: {latestFile.semantic}（已生成 {filesWrittenCount} 个文件）"
```
phase == "processing"
```
+ no
```
latestFile
```
→ "代码生成中...已处理 N 个事件"
```
phase == "processing"
```
+
```
progressDetail.lastMessage
```
exists → Also show the assistant's latest message as context
```
phase == "success"
```
→ Site is ready! Show link again.
```
phase == "fail"
```
→ Ask user whether to retry.

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

bash

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

需展示的进度消息（使用

progressDetail

生成丰富内容）：

```
phase == "processing"
```
+
```
progressDetail.latestFile
```
存在 → "代码生成中...正在写入: {latestFile.semantic}（已生成 {filesWrittenCount} 个文件）"
```
phase == "processing"
```
+ 无
```
latestFile
```
→ "代码生成中...已处理 N 个事件"
```
phase == "processing"
```
+
```
progressDetail.lastMessage
```
存在 → 同时展示助手的最新消息作为上下文
```
phase == "success"
```
→ 网站就绪！再次展示链接。
```
phase == "fail"
```
→ 询问用户是否重试。

Step 4: Handle completion

步骤4：处理完成状态

```
summary.chatStatus == "success"
```
→ Site is ready. Show site link again.

summary.chatStatus == "fail"

summary.hasError == true

→ Ask user whether to retry. Do NOT auto-retry.

```
summary.chatStatus == "success"
```
→ 网站就绪。再次展示网站链接。
```
summary.chatStatus == "fail"
```
或
```
summary.hasError == true
```
→ 询问用户是否重试。请勿自动重试。

After Initial Generation

初始生成后操作

Use
```
chat
```
with
```
--conversation-id
```
to modify the site.
Each modification uses the same chat + poll pattern.
Show the site link again after each modification.

使用带有
```
--conversation-id
```
参数的
```
chat
```
命令修改网站。
每次修改都遵循相同的聊天+轮询模式。
每次修改后再次展示网站链接。

Decision Table

决策表

`summary.chatStatus`	`summary.hasPrd`	Phase	Action
`interrupt`	—	2 (first round)	Parse AskUserQuestion, collect answers from user, resume with `--phase generate_prd`
`interrupt`	—	2 (subsequent)	Auto-fill with default `answers` from the AskUserQuestion event, resume immediately — do NOT ask user
`success`	`true`	2	PRD ready → proceed to Phase 3
`success`	`false`	3	Site is ready → show link
`fail`	—	any	Ask user whether to retry
`unknown`	—	any	Poll timed out → use `list-messages` fallback

`summary.chatStatus`	`summary.hasPrd`	阶段	操作
`interrupt`	—	2（第一轮）	解析AskUserQuestion，从用户处收集答案，传入 `--phase generate_prd` 恢复流程
`interrupt`	—	2（后续轮次）	自动填充AskUserQuestion事件中的默认 `answers` ，立即恢复流程 — 请勿询问用户
`success`	`true`	2	PRD生成完成 → 进入阶段3
`success`	`false`	3	网站就绪 → 展示链接
`fail`	—	任意	询问用户是否重试
`unknown`	—	任意	轮询超时 → 使用 `list-messages` 作为备选方案

Available Commands

可用命令

create-conversation

bash

python scripts/aistaff_api.py create-conversation --text "用户问题"

Returns flat JSON:

{ConversationId, SiteId, ChatId, SectionId, BotId, Title}

bash

python scripts/aistaff_api.py create-conversation --text "用户问题"

返回扁平JSON格式：

{ConversationId, SiteId, ChatId, SectionId, BotId, Title}

chat

Fire an async chat message and return immediately. Automatically drains old SSE events before firing. Use

poll

afterwards to track progress.

bash

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

Key parameters:

```
--text TEXT
```
: Message text or form answers JSON (required)
```
--conversation-id ID
```
/
```
--biz-id ID
```
: Required identifiers
```
--chat-id ID
```
+
```
--chat-status interrupt
```
: For HITL resume

--phase {requirement_collect,generate_prd,generate_code}

: Phase to enter

--user-navigation TARGET

: Navigation target (use

generate_prd

with

--phase generate_prd

)

```
--hidden
```
/
```
--without-refer
```
: Hide message / skip reference context
```
--verbose
```
: Show debug info

Returns JSON:

json

{
  "conversationId": "conv-xxx",
  "chatId": "chat-xxx",
  "status": "fired",
  "error": null
}

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

poll

跟踪进度。

bash

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

: 导航目标（与

--phase generate_prd

一起使用时传入

generate_prd

）

```
--hidden
```
/
```
--without-refer
```
: 隐藏消息 / 跳过参考上下文
```
--verbose
```
: 显示调试信息

返回JSON:

json

{
  "conversationId": "conv-xxx",
  "chatId": "chat-xxx",
  "status": "fired",
  "error": null
}

poll

Single-shot status check — fetches new events once + checks message status, then returns immediately. Designed for agent-driven polling loops where the agent controls the pace and shows progress to the user between calls.

bash

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

Key parameters:

```
--last-event-id N
```
: Cursor from previous poll (default: 0). Pass the
```
lastEventId
```
from the previous
```
poll
```
result to get only new events.
```
--max-output-events N
```
: Limit events in output (default: 10, 0=unlimited)

Returns JSON:

json

{
  "conversationId": "conv-xxx",
  "lastEventId": 45,
  "newEvents": 3,
  "phase": "generating_prd",
  "summary": {
    "chatStatus": "processing",
    "hasError": false,
    "errorMsg": "",
    "hasPrd": false,
    "toolsCalled": ["FetchWebsiteInfo"]
  },
  "progressDetail": {
    "filesWrittenCount": 5,
    "activeTools": ["Write"],
    "latestFile": {
      "path": "/home/wuying/workspace/src/components/Hero.tsx",
      "semantic": "首页 Hero 轮播组件",
      "status": "wait"
    },
    "allFiles": [
      {"path": "/home/wuying/workspace/src/types/order.ts", "semantic": "订单类型定义"},
      {"path": "/home/wuying/workspace/src/components/Hero.tsx", "semantic": "首页 Hero 轮播组件"}
    ],
    "lastMessage": "好的，正在为您生成首页组件...",
    "toolProgress": [
      {"name": "Write", "status": "done", "semantic": "订单类型定义"},
      {"name": "Write", "status": "wait", "semantic": "首页 Hero 轮播组件"}
    ]
  },
  "events": ["(last 10 events)"]
}

progressDetail
fields — use these to build informative progress messages:

```
filesWrittenCount
```
: Total number of files generated so far.
```
activeTools
```
: Tools currently in progress (status=
```
wait
```
). Empty when all tools have completed.
```
latestFile
```
: The most recent file being written — show
```
semantic
```
to the user (e.g. "正在生成: 首页 Hero 轮播组件").
```
allFiles
```
: Complete list of files written, each with
```
path
```
and
```
semantic
```
.
```
lastMessage
```
: Latest assistant text message (truncated to 200 chars).
```
toolProgress
```
: Per-tool status list with
```
name
```
,
```
status
```
(
```
wait
```
/
```
done
```
), and
```
semantic
```
.

Suggested progress messages based on
progressDetail
:

If
```
latestFile
```
has
```
status == "wait"
```
: "正在生成: {latestFile.semantic}..."
If
```
latestFile
```
has
```
status == "done"
```
and
```
activeTools
```
is empty: "已完成 {filesWrittenCount} 个文件，等待下一步..."
If
```
filesWrittenCount > 0
```
and
```
activeTools
```
is not empty: "代码生成中...已生成 {filesWrittenCount} 个文件，正在写入: {latestFile.semantic}"
If
```
lastMessage
```
is not empty: Show it as additional context.

phase
values:

Phase	Meaning	Suggested user message
`processing`	General processing	"处理中..."
`fetching_reference`	Fetching reference site	"正在获取参考网站信息..."
`waiting_for_input`	HITL form ready	(parse form and handle)
`generating_prd`	PRD generation in progress	"PRD 方案生成中..."
`success`	Completed successfully	"完成!"
`fail`	Failed	(ask user whether to retry)

单次状态检查 — 获取一次新事件并检查消息状态，然后立即返回。专为Agent驱动的轮询循环设计，由Agent控制轮询节奏，并在调用之间向用户展示进度。

bash

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=无限制）

返回JSON:

json

{
  "conversationId": "conv-xxx",
  "lastEventId": 45,
  "newEvents": 3,
  "phase": "generating_prd",
  "summary": {
    "chatStatus": "processing",
    "hasError": false,
    "errorMsg": "",
    "hasPrd": false,
    "toolsCalled": ["FetchWebsiteInfo"]
  },
  "progressDetail": {
    "filesWrittenCount": 5,
    "activeTools": ["Write"],
    "latestFile": {
      "path": "/home/wuying/workspace/src/components/Hero.tsx",
      "semantic": "首页 Hero 轮播组件",
      "status": "wait"
    },
    "allFiles": [
      {"path": "/home/wuying/workspace/src/types/order.ts", "semantic": "订单类型定义"},
      {"path": "/home/wuying/workspace/src/components/Hero.tsx", "semantic": "首页 Hero 轮播组件"}
    ],
    "lastMessage": "好的，正在为您生成首页组件...",
    "toolProgress": [
      {"name": "Write", "status": "done", "semantic": "订单类型定义"},
      {"name": "Write", "status": "wait", "semantic": "首页 Hero 轮播组件"}
    ]
  },
  "events": ["(last 10 events)"]
}

progressDetail
字段 — 用于构建信息量丰富的进度消息：

```
filesWrittenCount
```
: 截至目前已生成的文件总数。
```
activeTools
```
: 当前正在执行的工具（status=
```
wait
```
）。所有工具完成后为空。
```
latestFile
```
: 最近正在写入的文件 — 向用户展示
```
semantic
```
（例如："正在生成: 首页 Hero 轮播组件"）。
```
allFiles
```
: 已写入文件的完整列表，每个文件包含
```
path
```
和
```
semantic
```
。
```
lastMessage
```
: 助手的最新文本消息（截断至200字符）。
```
toolProgress
```
: 按工具分类的状态列表，包含
```
name
```
、
```
status
```
（
```
wait
```
/
```
done
```
）和
```
semantic
```
。

基于
progressDetail
的建议进度消息:

如果
```
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

Query the latest chat messages. Returns the last N messages (default: 10).

bash

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

Key usage: Use this to check

ChatStatus

of the last message when poll shows no progress.

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

bash

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

核心用途: 当轮询无进度时，使用此命令检查最后一条消息的

ChatStatus

。

SSE Event Constraints

SSE事件约束

Each new chat round may wipe previous SSE events. The
```
chat
```
command automatically drains old events before firing.
When using
```
poll
```
, pass the
```
lastEventId
```
from the previous poll result to avoid re-processing events.
During code generation, the platform may auto-trigger multiple "magic fix" rounds. The
```
poll
```
command detects this via event summary.

每一轮新的聊天可能会清除之前的SSE事件。
```
chat
```
命令会自动清空旧事件后再发送请求。
使用
```
poll
```
时，传入上一次轮询结果中的
```
lastEventId
```
以避免重复处理事件。
代码生成期间，平台可能会自动触发多轮"魔法修复"。
```
poll
```
命令会通过事件摘要检测到这一点。

Error Handling

错误处理

Error	Action
Auth error	Ensure credentials are configured via default credential chain (env vars, config file, or RAM role)
`summary.chatStatus == "fail"`	Ask user whether to retry. Do NOT auto-retry
Poll shows no progress for 5+ minutes	Use `list-messages` to check actual status

错误	操作
认证错误	确保已通过默认凭证链配置凭证（环境变量、配置文件或RAM角色）
`summary.chatStatus == "fail"`	询问用户是否重试。请勿自动重试
轮询5分钟以上无进度	使用 `list-messages` 检查实际状态

Complete Workflow Example

完整工作流示例

bash

cd skills/ai/service/alibabacloud-wxz-website-builder

bash

cd skills/ai/service/alibabacloud-wxz-website-builder

Phase 1: Create conversation

阶段1：创建对话

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

Phase 2 Step 1: Fire requirement collection

阶段2 步骤1：触发需求收集

python scripts/aistaff_api.py chat
--text "做个popmart首页"
--conversation-id $CONV_ID
--biz-id $SITE_ID

→ Tell user: "正在分析您的需求，请稍候..."

→ 告知用户: "正在分析您的需求，请稍候..."

Phase 2 Step 2: Poll until first HITL form arrives

阶段2 步骤2：轮询直至第一轮HITL表单出现

(agent calls this every ~5s, shows progress between calls)

(Agent每约5秒调用一次，调用之间展示进度)

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

→ Check phase: "waiting_for_input" means form is ready

→ 检查phase: "waiting_for_input"表示表单已就绪

Phase 2 Step 3: Parse AskUserQuestion → collect from user (FIRST round only)

阶段2 步骤3：解析AskUserQuestion → 从用户处收集答案（仅第一轮）

Phase 2 Step 4: Fire resume with user answers

阶段2 步骤4：传入用户答案触发恢复

python scripts/aistaff_api.py chat
--text '{"应用名称": "POP MART 官网", "主营服务": "潮流玩具", "目标用户": "Z世代潮流青年", "参考网站": "无"}'
--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

→ Tell user: "已收到您的需求，正在生成产品方案..."

→ 告知用户: "已收到您的需求，正在生成产品方案..."

Phase 2 Step 5: Poll loop (agent-driven, ~5s interval)

阶段2 步骤5：轮询循环（Agent驱动，约5秒间隔）

- phase="waiting_for_input" → auto-fill with defaults, fire resume

- phase="waiting_for_input" → 使用默认值自动填充，触发恢复

→ Tell user: "正在完善需求细节..."

→ 告知用户: "正在完善需求细节..."

- phase="generating_prd" → Tell user: "PRD 方案生成中..."

- phase="generating_prd" → 告知用户: "PRD 方案生成中..."

- summary.chatStatus="success" + summary.hasPrd=true → PRD ready, proceed

- summary.chatStatus="success" + summary.hasPrd=true → PRD生成完成，进入下一阶段

Phase 3 Step 1: Fire code generation

阶段3 步骤1：触发代码生成

python scripts/aistaff_api.py chat
--text "确认生成应用"
--conversation-id $CONV_ID
--biz-id $SITE_ID
--phase generate_code
--without-refer

Phase 3 Step 2: Show link immediately

阶段3 步骤2：立即展示链接

echo "Link: https://wanwang.aliyun.com/webdesign/home#/ai/manage/prd?conversationId=$CONV_ID"

→ Tell user: "代码生成已启动，通常需要 2-5 分钟..."

→ 告知用户: "代码生成已启动，通常需要 2-5 分钟..."

Phase 3 Step 3: Poll loop with progress (~10s interval)

阶段3 步骤3：带进度的轮询循环（约10秒间隔）

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

→ Use progressDetail.latestFile.semantic for rich messages

→ 使用progressDetail.latestFile.semantic生成丰富消息

→ phase="success" → show link again, done!

→ phase="success" → 再次展示链接，完成!

Modify site (optional, same chat+poll pattern)

修改网站（可选，遵循相同的聊天+轮询模式）

python scripts/aistaff_api.py chat
--text "首页title改下"
--conversation-id $CONV_ID
--biz-id $SITE_ID

→ poll loop...

→ 轮询循环...

undefined

undefined

alibabacloud-wxz-website-builder

Original

Translation

AI Staff Website Builder (零号员工建站)

AI Staff 网站构建工具（零号员工建站）

Validation

验证

Output And Evidence

输出与证据

Prerequisites

前置依赖

Authentication

认证

How to obtain AccessKey (if user doesn't have one)

如何获取AccessKey（若用户尚未拥有）

Application Lifecycle

应用生命周期

Phase 0: Auth Setup

阶段0：认证配置

Phase 1: Create Conversation

阶段1：创建对话

Phase 2: Requirement Collection + PRD

阶段2：需求收集 + PRD生成

Step 1: Fire requirement collection

步骤1：触发需求收集

Step 2: Poll until first HITL form arrives

步骤2：轮询直至第一轮HITL表单出现

Step 3: First HITL — collect answers from user

步骤3：第一轮HITL — 收集用户回答

Step 4: Fire resume with --phase generate_prd

步骤4：触发恢复并传入--phase generate_prd

Step 5: Poll loop — auto-fill subsequent HITL rounds until PRD is ready

步骤5：轮询循环 — 自动填充后续HITL轮次直至PRD生成完成

Poll example:

轮询示例:

Auto-fill example (use the "answers" field from the AskUserQuestion event):

自动填充示例（使用AskUserQuestion事件中的"answers"字段）:

Phase 3: Code Generation

阶段3：代码生成

Step 1: Fire code generation

步骤1：触发代码生成

Step 2: Show site link immediately

步骤2：立即展示网站链接

Step 3: Poll loop with progress updates

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

Step 4: Handle completion

步骤4：处理完成状态

After Initial Generation

初始生成后操作

Decision Table

决策表

Available Commands

可用命令

create-conversation

create-conversation

chat

chat

poll

poll

list-messages

list-messages

SSE Event Constraints

SSE事件约束

Error Handling

错误处理

Complete Workflow Example

完整工作流示例

Phase 1: Create conversation

阶段1：创建对话

Phase 2 Step 1: Fire requirement collection

阶段2 步骤1：触发需求收集

→ Tell user: "正在分析您的需求，请稍候..."

→ 告知用户: "正在分析您的需求，请稍候..."

Phase 2 Step 2: Poll until first HITL form arrives

阶段2 步骤2：轮询直至第一轮HITL表单出现

(agent calls this every ~5s, shows progress between calls)

(Agent每约5秒调用一次，调用之间展示进度)

→ Check phase: "waiting_for_input" means form is ready

→ 检查phase: "waiting_for_input"表示表单已就绪

Phase 2 Step 3: Parse AskUserQuestion → collect from user (FIRST round only)

Step 4: Fire resume with
`--phase generate_prd`

步骤4：触发恢复并传入
`--phase generate_prd`