a2ui-ask

Files (36)

• ci.yml · .github/workflows/
• publish.yml · .github/workflows/
• .gitignore
• LICENSE
• README.ZH.md
• README.md
• SKILL.md
• a2ui-ask-site.png
• controls-gallery.png · docs/
• mermaid-editor.png · docs/
• rich-options.png · docs/
• web-ui.png · docs/
• deployment-architecture.defaults.json · examples/
• deployment-architecture.schema.json · examples/
• ecommerce-main-image.defaults.json · examples/
• ecommerce-main-image.schema.json · examples/
• env-defaults.json · examples/
• env-schema.json · examples/
• feature-brief.defaults.json · examples/
• feature-brief.schema.json · examples/
• invoice-reimbursement.defaults.json · examples/
• invoice-reimbursement.schema.json · examples/
• seo-diagnosis.defaults.json · examples/
• seo-diagnosis.schema.json · examples/
• web-research-brief.defaults.json · examples/
• web-research-brief.schema.json · examples/
• install.md
• package.json
• ask-user.prompt.md · prompts/
• ask.prompt.md · prompts/
• ask.ps1 · scripts/
• ask.py · scripts/
• ask.sh · scripts/
• install.ps1 · scripts/
• install.sh · scripts/
• test_ask.py · tests/

SKILL.md (first lines)

# a2ui-ask — collect user input via a browser form (file output)

Interactive UI for AI agents: turn structured questions into browser forms. The
rendering engine is the `schemaui` binary (`schemaui web`) from
[YuniqueUnic/schemaui](https://github.com/YuniqueUnic/schemaui); this skill
wraps it with scripts that handle binding, browser wakeup, timeout, and the
file-output contract.

## Prerequisite: the schemaui engine

Check for the binary first: `command -v schemaui` (or just run the ask script —
it exits with code 3 when the engine is missing).

If missing, offer to install it — you can do this yourself, unattended:

```bash
bash scripts/install.sh        # macOS / Linux / FreeBSD: auto-detect & install
pwsh scripts/install.ps1       # Windows / PowerShell 7+
```

Both default to a prebuilt-binary download (no toolchain needed) and support
`--dry-run` / `-DryRun` to preview. They fetch from GitHub first and fall back
to the [Gitee mirror](https://gitee.com/Credhat/schemaui) — same tags, same
asset names — which is what makes them work from mainland China. If a user
reports a stalled or failed install, re-run with the mirror pinned rather than
retrying GitHub:

```bash
bash scripts/install.sh --source gitee
pwsh scripts/install.ps1 -Source gitee
```

The brew / scoop / winget manifests still hardcode GitHub download URLs, so on a
blocked network prefer `--source gitee` or `cargo install schemaui-cli`. Full
channel list: see `install.md` in this repository.

## Non-negotiables

1. Web form only, via `schemaui web`. Terminal prompts are forbidden — your
   process has no TTY, so a TUI renders nowhere and blocks forever.
2. Bind `0.0.0.0` so the form is reachable from localhost, LAN, SSH tunnels, and
   port-forwards.
3. Output to a FILE under `.schemaui/answers/` — stdout-only is forbidden.
4. Tell the user the URL and the answer file path in your response, in the same
   turn as the tool call.
5. Block on the subprocess; read the answer file when it exits.
6. Fall back to plain text on any failure — never abort the task.
7. `-o` is greedy: every other flag goes BEFORE `-o`; extra destinations are
   space-separated in the same `-o` (`-o answer.json -`), never repeated.

## Asking well (grill-me discipline, form edition)

- **Explore before asking.** If the codebase, git history, or
  `.schemaui/answers/` can answer the question, answer it yourself. The form is
  for decisions only the user can make.
- **One form per decision cluster.** Batch the questions of one topic (e.g.
  "deployment config") into a single form; do not spawn ten forms for ten
  questions, and do not interrogate serially in chat either.
- **Every question ships a recommended answer.** Put your recommendation in the
  field's `default` so the user can confirm with one click instead of typing.
  Say in chat what you recommended and why.
- **Keep the recommendation out of the option label.** `default` is the one
  place the recommendation lives; the label is what lands in the answer file.
  Suffixing options with `（推荐）` / `(recommended)` duplicates the hint and
  then leaks it into the data, so every downstream consumer has to strip it.
  Explain the recommendation in the field's `description` instead ("推荐
  X：因为…"), where it stays readable without contaminating the value.
- **Speak the user's language.** Write every `title` and `description` in the
  language the user is chatting in, and say in the description what the answer
  changes downstream ("drives whether we need rate limiting").
- **Pick the control, don't settle for text boxes.** A slider for a scale, a
  two-handle range for a window, a colour picker for a colour, a segmented
  control for a handful of short options, `x-visible-when` for anything that
  only matters sometimes. Choosing from the gallery is what makes the form
  pleasant to fill in — see
  [Picking the control](#picking-the-control-use-the-gallery).
- **Always leave an escape hatch, and keep it out of the way.** Your options and
  defaults are guesses, so every select gets an `其他`/`other` option plus a
  sibling `<field>_custom` text input. Gate that input with `x-visible-when` so
  it only shows up once the user actually picks the escape option — a
  permanently visible empty box reads as a question they still owe you an answer
  to:

  ```json
  "delivery_form": { "enum": ["单个 HTML 文件", "其他"], "default": "单个 HTML 文件" },
  "delivery_form_custom": {
    "type": "string",
    "title": "交付形式 · 自定义说明",
    "description": "选了「其他」时填写:你想要的交付形式。",
    "x-visible-when": { "field": "delivery_form", "op": "equals", "value": "其他" }
  }
  ```

  Use `"op": "contains"` when the controlling field is a multi-select (the
  option list has to _contain_ the escape value). The rule must name a sibling
  of the same object: a typo is rejected when the form loads rather than hiding
  the field forever. The controlling field's `default` must not be the escape
  value, or the input would be visible from the start.

## Grilling: which interview skill to use

Open-ended designs sometimes need a relentless interview before they become a
form. When the user asks to be grilled (or a plan needs stress-testing before
you can draft the schema), use an existing grilling skill if the user named or
installed one — check their skills directory for something like `grill-me`,
`grilling`, or a skill they explicitly referenced, and defer to it. Only when
none exists, fall back to the one bundled here:
[`skills/grill-with-docs/SKILL.md`](./skills/grill-with-docs/SKILL.md) — the
same one-question-at-a-time, recommend-then-ask discipline, plus a rule to
ground every question in the project's docs and the galleries referenced above,
and to end by turning the settled decisions into a form. The bundled skill is a
convenience so a fresh install works out of the box; it never overrides a
grilling skill the user chose themselves.

## Question type → schema cheat sheet

| You need               | Schema shape                                                                                                                     | Renders as                                          |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| short text input       | `{"type": "string", "minLength": …, "pattern": …}`                                                                               | inline text field                                   |

From YuniqueUnic/a2ui-ask, MIT.

More from YuniqueUnic/a2ui-ask