ask-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ask UI

把 Ask UI 当作展示与持久化适配器使用。问题的生成和推理仍留在调用方工作流里。

Use Ask UI as a presentation and persistence adapter. Question generation and reasoning remain in the caller's workflow.

判断是否使用 UI

Determine Whether to Use the UI

当前一轮包含至少两个用户当下就能回答的独立问题时，使用 UI。有依赖关系的问题留到后续轮次。只有一个问题时直接在对话里问。

对

grill-me

、

grill-with-docs

、头脑风暴，或其他确认与问题收集类工作流，只要一轮超过两个问题，一律使用 UI。

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

Use the UI when the current round contains at least two independent questions that the user can answer immediately. Questions with dependencies should be left for subsequent rounds. Ask directly in the conversation when there's only one question.

For

grill-me

grill-with-docs

, brainstorming, or other confirmation and question collection workflows, always use the UI when a round has more than two questions.

Fallback to the caller workflow's regular text format if the local service or browser cannot start.

提问并等待回答

Ask Questions and Wait for Responses

把包含本
```
SKILL.md
```
的目录解析为
```
ASK_UI_SKILL_DIR
```
。
创建 JSON 前先读 references/schema.md。
创建 QuestionSet JSON 文件。新任务省略
```
sessionId
```
；后续轮次复用当前活跃的
```
sessionId
```
并设置
```
basedOnRound
```
。一并写上上下文字段，让用户不看对话也能判断在问什么：Session 级
```
projectName
```
/
```
sessionSummary
```
/
```
sessionBackground
```
，Round 级
```
purpose
```
，需要单独交代前情的题写
```
background
```
。选择题没有「其他」选项。预设选项之外的答案由每题的补充说明承载，所以选项只列真正互斥的几种，不要凑「其他」。
运行前台命令，并保持该工具调用一直活跃直到它退出：
text
```
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
```
该命令把就绪信息、
```
ask-ui-session: <id>
```
标记和本地 URL 写入 stderr，打开表单并等待。不要结束 Agent 轮次，也不要让用户回复「已提交」。
用户提交后，解析 stdout 输出的那一个 JSON 结果，立即继续原工作流。
若还需要更多独立问题，用同一个
```
sessionId
```
再次调用
```
ask
```
，并把
```
basedOnRound
```
设为返回的轮次号。没有更多问题时，结束该 Session。

Resolve the directory containing this
```
SKILL.md
```
as
```
ASK_UI_SKILL_DIR
```
.
Read references/schema.md before creating JSON.
Create a QuestionSet JSON file. Omit
```
sessionId
```
for new tasks; reuse the currently active
```
sessionId
```
and set
```
basedOnRound
```
for subsequent rounds. Include context fields so users can understand the questions without viewing the conversation: Session-level
```
projectName
```
/
```
sessionSummary
```
/
```
sessionBackground
```
, Round-level
```
purpose
```
, and write
```
background
```
for questions that require separate context. Multiple-choice questions do not have an "Other" option. Answers outside the preset options are carried by the supplementary notes for each question, so only list truly mutually exclusive options and don't add "Other" to fill in.
Run the foreground command and keep this tool call active until it exits:
text
```
node <ASK_UI_SKILL_DIR>/scripts/ask-ui.mjs ask --input <questions.json>
```
This command writes readiness information, the
```
ask-ui-session: <id>
```
marker, and a local URL to stderr, opens the form, and waits. Do not end the Agent round, and do not ask the user to reply "submitted".
After the user submits, parse the single JSON result output to stdout and immediately continue the original workflow.
If more independent questions are needed, call
```
ask
```
again with the same
```
sessionId
```
and set
```
basedOnRound
```
to the returned round number. End the Session when there are no more questions.

命令被放到后台或中断时

When the Command is Put in the Background or Interrupted

ask

会一直阻塞到用户提交，容易被 harness 转到后台。转后台之后 stdout 和 stderr 混在同一个任务输出文件里，直接解析那个文件必然失败。

绝不要求用户回复「已提交」来推进
ask
。用户填完表单、页面自行关闭，

ask

进程随即退出，harness 会把后台任务完成通知推给你——那就是结果就绪的信号，不需要用户再说一遍。用户被要求汇报自己刚做完的事，是这条流程唯一不该出现的状态。

转后台后按这个顺序判断：

命令还在跑 → 结束本轮，等 harness 的任务完成通知。不要
```
sleep
```
轮询，不要催用户。
收到完成通知，或输出里出现
```
ask-ui-submitted: <id> round <n>
```
→ 结果已就绪。

拿 stderr 里的

ask-ui-session: <id>

取结果：

text

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

resume

status: "submitted"

时其中就是完整答案；返回

{"status":"waiting"}

说明进程还没退出，回到第 1 步继续等。不要去

tail

任务输出、不要手动拼

.ask-ui/

下的文件路径。

每一轮都会打开浏览器：页面在提交后自行关闭，所以下一轮必须重新打开。同一 Session 的各轮复用常驻服务和稳定 URL。

仅当浏览器打开由外部单独管理时才用

--no-open

。仅当必须固定 localhost 端口时才用

--port <number>

。

ask

blocks until the user submits, which can easily be moved to the background by the harness. After moving to the background, stdout and stderr are mixed in the same task output file, parsing that file directly will definitely fail.

Never ask the user to reply "submitted" to advance
ask
. After the user fills out the form, the page closes automatically, and the

ask

process exits immediately. The harness will push a background task completion notification to you—that's the signal the result is ready, no need for the user to repeat it. Asking the user to report what they just did is the only state that should never occur in this flow.

Follow this order of judgment after moving to the background:

Command is still running → End this round and wait for the harness's task completion notification. Do not
```
sleep
```
to poll, do not urge the user.
Received completion notification, or
```
ask-ui-submitted: <id> round <n>
```
appears in the output → Result is ready.

Retrieve the result using the

ask-ui-session: <id>

from stderr:

text

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

When

resume

returns

status: "submitted"

, it contains the complete answer; when it returns

{"status":"waiting"}

, it means the process hasn't exited yet, go back to step 1 and continue waiting. Do not

tail

the task output, do not manually construct the file path under

.ask-ui/

The browser opens every round: the page closes automatically after submission, so the next round must reopen. All rounds of the same Session reuse the persistent service and stable URL.

Only use

--no-open

when browser opening is managed separately externally. Only use

--port <number>

when the localhost port must be fixed.

手动回退与恢复

Manual Fallback and Recovery

这是最后手段，只在

ask

确实用不了时才走——它是唯一需要用户回复「已提交」的路径。

ask

被转到后台不算用不了，那种情况按上一节等通知。

出现以下情况时走分离式（detached）流程：前台工具调用无法保持活跃、本地浏览器连不上临时服务、或需要恢复一个被中断的直连轮次：

text

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

解析返回的 JSON。在对话中同时给出它的 URL 和一个可见标记：

text

ask-ui-session: <sessionId>

告诉用户提交表单后只回复「已提交」。

create

命令会启动或复用一个分离式 localhost 服务并立即返回。

当用户说「已提交」「提交好了」「答完了」时：

从对话中最近一个
```
ask-ui-session
```
标记恢复
```
sessionId
```
。

运行：

text

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

若结果为
```
submitted
```
，用其中的问题和答案继续原工作流。
若还需要更多独立问题，优先回到前台
```
ask
```
命令，用同一
```
sessionId
```
并把
```
basedOnRound
```
设为刚处理的轮次。只有在仍然无法直连等待时才再次使用
```
create
```
。

若没有更多问题，运行：

text

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

若对话中拿不到该标记，运行不带

--session

的

resume

。返回多个候选时，依据当前话题、工作区、标题和提交时间推断最匹配的一个。只有在匹配确实无法判定时才去问用户。

重复的「已提交」消息不得创建重复轮次。只有在成功读到一个

submitted

轮次之后，才可以创建新轮次。

This is a last resort, only to be used when

ask

is truly unavailable—it's the only path that requires the user to reply "submitted".

ask

being moved to the background does not count as unavailable; follow the previous section to wait for notifications in that case.

Follow the detached process when: the foreground tool call cannot stay active, the local browser cannot connect to the temporary service, or an interrupted direct connection round needs to be restored:

text

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

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

text

ask-ui-session: <sessionId>

Tell the user to only reply "submitted" after submitting the form. The

create

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

When the user says "submitted", "done submitting", or "finished answering":

Retrieve the
```
sessionId
```
from the most recent
```
ask-ui-session
```
marker in the conversation.

Run:

text

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

If the result is
```
submitted
```
, use the questions and answers in it to continue the original workflow.
If more independent questions are needed, prioritize returning to the foreground
```
ask
```
command, using the same
```
sessionId
```
and setting
```
basedOnRound
```
to the round just processed. Only use
```
create
```
again if direct connection waiting is still impossible.

If there are no more questions, run:

text

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

If the marker cannot be obtained from the conversation, run

resume

without

--session

. When multiple candidates are returned, infer the most matching one based on the current topic, workspace, title, and submission time. Only ask the user if the match is truly undetermined.

Duplicate "submitted" messages must not create duplicate rounds. Only create a new round after successfully reading a

submitted

round.

保持 Session 连续性

Maintain Session Continuity

一个任务对应一个 Session。
每批问题对应一个 Round。
同一任务的所有轮次复用同一个
```
sessionId
```
。
绝不覆盖已提交的问题或答案。
更正和补充确认放进新的 Round。
只有新任务、任务已完成、或用户明确要求重启时，才开新 Session。

One task corresponds to one Session.
Each batch of questions corresponds to one Round.
All rounds of the same task reuse the same
```
sessionId
```
.
Never overwrite submitted questions or answers.
Corrections and supplementary confirmations are placed in new Rounds.
Only start a new Session for a new task, when the task is completed, or when the user explicitly requests a restart.

可选的主动唤醒

Optional Active Wake-Up

Ask UI 为 Claude Code 和 Codex App Server 支持可选的唤醒元数据。把它当增强项，不是必需项。

只有在用户同意后才启用自动唤醒。
Claude Code 需要一个已记录的 session id。
Codex 需要宿主提供的 thread id。绝不猜测 Codex thread id。
适配器失败时，保住答案并回到手动「已提交」流程。
直连
```
ask
```
模式永远不触发唤醒适配器，因为等待中的进程本身就是返回通道。

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

Only enable automatic wake-up after user consent.
Claude Code requires a recorded session id.
Codex requires a host-provided thread id. Never guess the Codex thread id.
When the adapter fails, preserve the answer and return to the manual "submitted" process.
Direct connection
```
ask
```
mode never triggers the wake-up adapter, as the waiting process itself is the return channel.

常用命令

Common 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