ask-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ask UI

Use Ask UI as a presentation and persistence adapter. Keep question generation and reasoning in the calling workflow.

将Ask UI用作展示和持久化适配器。将问题生成和推理逻辑保留在调用工作流中。

Decide whether to use the UI

判断是否使用UI

Use the UI when the current round contains at least two independent questions that the user can answer now. Keep dependent questions for a later round. Ask a single question directly in the conversation.

If the local server or browser cannot start, fall back to the calling workflow's normal text format.

当当前回合包含至少两个用户可立即回答的独立问题时，使用UI。将依赖问题留到后续回合处理。单个问题直接在对话中提出。

如果本地服务器或浏览器无法启动，则回退到调用工作流的常规文本格式。

Ask and wait for the answer

发起提问并等待答案

Resolve the directory containing this
```
SKILL.md
```
as
```
ASK_UI_SKILL_DIR
```
.
Read references/schema.md before creating JSON.
Create a QuestionSet JSON file. For a new task, omit
```
sessionId
```
; for follow-up rounds, reuse the active
```
sessionId
```
and set
```
basedOnRound
```
.
Run the foreground command and keep the tool call active until it exits:
text
```
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
```
The command writes readiness details and the local URL to stderr, opens the form, and waits. Do not end the Agent turn or ask the user to reply “已提交”.
After the user submits, parse the single JSON result written to stdout and continue the originating workflow immediately.
If more independent questions are needed, call
```
ask
```
again with the same
```
sessionId
```
and
```
basedOnRound
```
set to the returned round. When no further questions remain, complete the session.

Use

--no-open

only when browser opening is managed separately. Use

--port <number>

only when a fixed localhost port is required.

将包含此
```
SKILL.md
```
的目录解析为
```
ASK_UI_SKILL_DIR
```
。
在创建JSON之前阅读references/schema.md。
创建QuestionSet JSON文件。对于新任务，省略
```
sessionId
```
；对于后续回合，重用当前活跃的
```
sessionId
```
并设置
```
basedOnRound
```
。
运行前台命令并保持工具调用处于活跃状态，直到其退出：
text
```
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
```
该命令会将就绪详情和本地URL写入stderr，打开表单并等待。不要结束Agent回合，也不要要求用户回复“已提交”。
用户提交后，解析写入stdout的单个JSON结果，并立即继续原始工作流。
如果需要更多独立问题，再次调用
```
ask
```
命令，使用相同的
```
sessionId
```
并将
```
basedOnRound
```
设置为返回的回合数。当没有更多问题时，完成会话。

仅在浏览器打开由其他方式管理时使用

--no-open

参数。仅在需要固定本地端口时使用

--port <number>

参数。

Manual fallback and recovery

手动回退与恢复

Use the detached workflow when the foreground tool call cannot remain active, the local browser cannot reach the temporary server, or an interrupted direct round must be recovered:

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>

Parse the returned JSON. Include its URL and a visible marker in the conversation:

text

ask-ui-session: <sessionId>

Tell the user to submit the form and reply only with “已提交”. The

create

command starts or reuses a detached localhost server and returns immediately.

When the user says “已提交”, “提交好了”, or “答完了”:

Recover
```
sessionId
```
from the latest
```
ask-ui-session
```
marker in this conversation.

Run:

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs resume --session <sessionId>

If the result is
```
submitted
```
, use its questions and answers to continue the original workflow.
If more independent questions are needed, prefer returning to the foreground
```
ask
```
command with the same
```
sessionId
```
and
```
basedOnRound
```
set to the processed round. Use
```
create
```
again only when direct waiting remains unavailable.

If no further questions remain, run:

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>

If the conversation marker is unavailable, run

resume

without

--session

. When multiple candidates are returned, infer the best match from the current topic, workspace, title, and submission time. Ask the user only when the match is genuinely ambiguous.

Repeated “已提交” messages must not create duplicate rounds. A new round should only be created after successfully reading a

submitted

round.

当前台工具调用无法保持活跃、本地浏览器无法连接临时服务器，或者需要恢复中断的直接回合时，使用分离式工作流：

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>

解析返回的JSON。在对话中包含其URL和一个可见标记：

text

ask-ui-session: <sessionId>

告知用户提交表单后仅回复“已提交”。

create

命令会启动或重用一个分离的本地服务器并立即返回。

当用户说出“已提交”“提交好了”或“答完了”时：

从对话中最新的
```
ask-ui-session
```
标记中恢复
```
sessionId
```
。

运行：

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs resume --session <sessionId>

如果结果为
```
submitted
```
，使用其中的问题和答案继续原始工作流。
如果需要更多独立问题，优先使用相同的
```
sessionId
```
并将
```
basedOnRound
```
设置为已处理回合数，回到前台
```
ask
```
命令。仅当直接等待仍然不可用时，再次使用
```
create
```
命令。

如果没有更多问题，运行：

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>

如果对话标记不可用，不带

--session

参数运行

resume

。当返回多个候选会话时，根据当前主题、工作区、标题和提交时间推断最佳匹配。仅当匹配确实存在歧义时，才询问用户。

重复的“已提交”消息不得创建重复回合。仅在成功读取一个

submitted

回合后，才应创建新回合。

Preserve session continuity

保持会话连续性

One task is one Session.
Each batch of questions is one Round.
Reuse
```
sessionId
```
across all rounds of the same task.
Never overwrite submitted questions or answers.
Put corrections and additional confirmation in a new Round.
Start a new Session only for a new task, a completed task, or an explicit restart.

一个任务对应一个Session。
每一批问题对应一个Round。
在同一任务的所有回合中重用
```
sessionId
```
。
切勿覆盖已提交的问题或答案。
将修正和额外确认放在新的Round中。
仅在新任务、已完成任务或明确重启时，启动新的Session。

Optional active wake-up

可选主动唤醒

Ask UI supports optional wake metadata for Claude Code and Codex App Server. Treat it as an enhancement, not a requirement.

Enable automatic wake only with the user's consent.
Claude Code requires a recorded session id.
Codex requires a host-provided thread id. Never guess a Codex thread id.
On adapter failure, preserve the answer and return to the manual “已提交” workflow.
Direct
```
ask
```
mode never triggers wake adapters because the waiting process is already the return channel.

Ask UI支持针对Claude Code和Codex App Server的可选唤醒元数据。将其视为增强功能，而非必需项。

仅在用户同意的情况下启用自动唤醒。
Claude Code需要记录的会话ID。
Codex需要主机提供的线程ID。切勿猜测Codex线程ID。
适配器失败时，保留答案并回到手动“已提交”工作流。
直接
```
ask
```
模式永远不会触发唤醒适配器，因为等待进程本身就是返回通道。

Useful commands

实用命令

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs status --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs serve
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/self-test.mjs

text

node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs create --input <questions.json>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs status --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs serve
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs complete --session <sessionId>
node <ASK_UI_SKILL_DIR>/scripts/self-test.mjs