@easbot/terminal 0.3.13 → 0.3.16

package/README.en.md

@@ -6,7 +6,7 @@
 
 ## Introduction
 
-`@easbot/terminal` is a terminal interaction toolkit for the EASBOT ecosystem. It encapsulates the common capabilities required by CLI / TUI scenarios: themed color output, ANSI handling, OSC-8 hyperlinks, table rendering, styled prompts, safe stream writes, progress-line management, terminal-state recovery, an interactive searchable multi-select prompt, a simple CLI input helper, and a lightweight markdown renderer. Every module auto-detects terminal capability (`NO_COLOR` / `FORCE_COLOR` / TTY) and degrades gracefully in non-TTY environments (pipes, redirected files, CI logs).
+`@easbot/terminal` is a terminal interaction toolkit for the EASBOT ecosystem. It encapsulates the common capabilities required by CLI / TUI scenarios: themed color output, ANSI handling, table rendering, command output formatting, styled prompts, JSON contract output, human-output helpers (`printHuman` / `renderLines`), a unified **interactive Prompt namespace**, an interactive searchable multi-select prompt, a readline-based CLI input helper, a lightweight markdown renderer, shared icon / status-symbol constants, a stateless Loader spinner, and terminal-state recovery. Every module auto-detects terminal capability (`NO_COLOR` / `FORCE_COLOR` / TTY) and degrades gracefully in non-TTY environments (pipes, redirected files, CI logs).
 
 The package is **vendor-neutral**: it does not hard-code any external doc site or vendor-specific configuration. Helper functions such as `formatRootedLink` / `formatRootLink` accept an explicit root URL, leaving integration choices to the caller.
 
@@ -19,15 +19,18 @@ The package is **vendor-neutral**: it does not hard-code any external doc site o
 - **OSC-8 hyperlinks** — cross-platform terminal hyperlinks with graceful fallback
 - **Table rendering** — `renderTable` with auto-fit columns, Unicode / ASCII / borderless styles, ANSI-safe wrapping
 - **Command output formatting** — success / error / warning / info / heading / key-value / command / list / status / count helpers
-- **Styled prompts** — styled wrappers around `@clack/prompts` (`selectStyled` / `note` / `stylePromptMessage` …)
+- **Styled prompts** — low-level styling wrappers (`selectStyled` / `note` / `stylePromptMessage` / `stylePromptTitle` / `stylePromptHint`)
+- **Unified Prompt namespace** — `Prompt.select / groupMultiselect / text / password / confirm / multiselect / intro / outro / cancel / Log.* / spinner` is the **recommended entry point** for any business code (see the "Prompt namespace" section)
 - **Searchable multi-select** — `Search.multiselect` is an interactive, real-time-filtered, multi-select prompt with full keyboard control, optional locked section, and graceful stdin / signal cleanup
 - **Loader** — `Loader.create()` returns a stateless spinner instance (no Component / TUI inheritance). Customizable frames, color, message; integrates with `MockTerminalIO` for tests
 - **Input** — `Input.readText` / `Input.readConfirm` / `Input.readPassword` are readline-based helpers for CLI prompts; inject `input` / `output` streams for test isolation
 - **Markdown** — `renderMarkdown` parses a minimal markdown subset (heading / list / code-block / bold / italic / link) without pulling in `marked`
+- **Human output helpers** — `printHuman(lines, { title, outro })` packages grouping + summary + outro into a single page; the canonical human-readable output for every CLI subcommand
+- **Icons / status symbols** — every `✓ / ✗ / ⚠ / ℹ / ◆ / ● / ○ / │ / ─ / � / • / ↡ / ⊘` literal lives **only** in `symbols.ts`; callers use `Symbol.statusIcon(...)` / `Symbol.colorize(...)`
+- **CLI JSON contract** — `emitJson / emitJsonOk / emitJsonError / wrapJson / wrapError` implement the EASBOT `--json` protocol (`{ ok, data, meta? }` / `{ ok: false, error: { code, message } }`)
 - **Safe stream writer** — `createSafeStreamWriter` swallows `EPIPE` / `EIO`, so a closed pipe never throws
 - **Progress line** — register / clear / unregister an active progress line (TTY-only)
 - **Terminal-state recovery** — `restoreTerminalState` resets cursor, mouse tracking, and bracketed paste on exit
-- **CLI JSON output** — `emitJsonOk` / `emitJsonError` implement the EASBOT CLI `--json` contract (`{ ok, data | error }`)
 - **Color discipline** — every styled output goes through `isRich()` + `colorize()`, and snapshot / non-TTY runs never leak ANSI sequences
 - **TTY injection for tests** — interactive components (e.g. `formatTerminalLink`, `Search.multiselect`, `Input.readText`) accept an optional `isTTY` parameter so unit tests can run without depending on `process.stdout.isTTY`
 
@@ -105,8 +108,8 @@ console.log(
       { key: 'status', header: 'Status', align: 'center' },
     ],
     rows: [
-      { name: '@easbot/terminal', version: '0.3.11', status: '✓' },
-      { name: '@easbot/note', version: '0.3.11', status: '✓' },
+      { name: '@easbot/terminal', version: '0.3.13', status: '✓' },
+      { name: '@easbot/note', version: '0.3.13', status: '✓' },
     ],
     width: 80,
     border: 'unicode',
@@ -114,7 +117,100 @@ console.log(
 );
 ```
 
-### Styled prompts
+### Human output helpers (`printHuman`)
+
+```typescript
+import { printHuman, renderLines } from '@easbot/terminal';
+
+// The canonical "grouped detail + summary + outro" page
+printHuman(
+  ['  ✓ eas-agent-creation', '  ✓ eas-agent-evolution', '  ✗ eas-legacy-tool'],
+  {
+    title: 'Project Skills Update',
+    outro: 'Run `easbot skills list` to see current state.',
+    empty: 'No skills tracked in lock file.',
+  },
+);
+
+// renderLines: build a grouped tree (list / find / store-list style)
+const lines = renderLines({
+  title: 'Project Skills (3)',
+  groups: [
+    { key: 'universal (.agents/skills)', rows: ['  ✓ foo', '  ✓ bar'] },
+    { key: 'claude-code', rows: ['  ✓ baz'] },
+  ],
+});
+```
+
+### Prompt namespace (the unified entry point)
+
+`Prompt` is the unified interactive namespace provided by `@easbot/terminal` — **the only recommended entry point for business code**. Internally it follows the B+A hybrid model:
+
+- `select / groupMultiselect / text / password / confirm`: thin wrappers around `@clack/prompts` (battle-tested raw mode / signal / cancel)
+- `multiselect`: custom implementation backed by `Search.multiselect` (fuzzy + locked section + pagination)
+- `intro / outro / cancel / Log.* / spinner`: custom implementation (chalk + theme), colors unified to the terminal `theme`
+
+```typescript
+import { Prompt } from '@easbot/terminal';
+
+// Single-select
+const choice = await Prompt.select({
+  message: 'Choose install scope',
+  options: [
+    { value: 'project', label: 'Project', hint: 'Current directory' },
+    { value: 'global', label: 'Global', hint: 'Home directory' },
+  ],
+});
+if (Prompt.isCancel(choice)) Prompt.cancel('Cancelled by user');
+
+// Multi-select
+const selected = await Prompt.multiselect({
+  message: 'Pick the agents to enable',
+  options: [
+    { value: 'claude-code', label: 'Claude Code' },
+    { value: 'easbot', label: 'EASBot' },
+  ],
+  initialValues: ['easbot'], // pre-select
+  required: true,
+});
+
+// Grouped multi-select
+const skills = await Prompt.groupMultiselect({
+  message: 'Pick the skills to install',
+  options: {
+    General: [{ value: 'foo', label: 'foo' }, { value: 'bar', label: 'bar' }],
+    'Advanced Plugins': [{ value: 'baz', label: 'baz' }],
+  },
+});
+
+// Flow skeleton
+Prompt.intro(' skills ');
+// ... do something ...
+Prompt.outro('Done!');
+
+// Cancellation: Prompt.cancel returns `never` and calls process.exit(0) internally
+if (Prompt.isCancel(selected)) Prompt.cancel('Cancelled by user');
+
+// Status logging (colors unified to terminal theme)
+Prompt.Log.info('Operation succeeded');
+Prompt.Log.warn('Warning');
+Prompt.Log.error('Error');
+Prompt.Log.step('Step');
+Prompt.Log.message('Plain message (no prefix)');
+
+// Spinner
+const spinner = Prompt.spinner();
+spinner.start('Parsing source...');
+spinner.stop(`Found ${count} skill(s)`);
+```
+
+**Cancellation contract:**
+
+- `Prompt.cancelSymbol` — the single sentinel (same reference as `Search.cancelSymbol`)
+- `Prompt.isCancel(value)` — type guard, also accepts clack's `Symbol('')`
+- `Prompt.cancel(message?)` — `never` return + `process.exit(0)`
+
+### Styled prompts (low-level helpers)
 
 ```typescript
 import { selectStyled, note, wrapNoteMessage } from '@easbot/terminal';
@@ -130,6 +226,30 @@ const choice = await selectStyled({
 note(wrapNoteMessage('Config file saved to ~/.config/app/config.json'), 'Success');
 ```
 
+### Icons / Symbols (the unified source of truth)
+
+Business code **must not** write `✓ ✗ ⚠ ℹ ◆ ● ○ │ ─ •` as string literals. All icons must come from the `Symbol` namespace.
+
+```typescript
+import { Symbol as Glyph } from '@easbot/terminal';
+
+// Status icons (themed)
+console.log(`${Glyph.statusIcon('success')} Operation succeeded`); // ✓ green
+console.log(`${Glyph.statusIcon('error')} Operation failed`); // ✗ red
+console.log(`${Glyph.statusIcon('warning')} Warning`); // ⚠ yellow
+console.log(`${Glyph.statusIcon('info')} Info`); // ℹ blue
+console.log(`${Glyph.statusIcon('active')} In progress`); // ◆ accent
+console.log(`${Glyph.statusIcon('skipped')} Skipped`); // ↡ muted
+console.log(`${Glyph.statusIcon('blocked')} Blocked`); // ⊘ error
+
+// Decoration glyphs
+console.log(Glyph.bar.vertical); // │
+console.log(Glyph.bar.bullet); // •
+
+// Wrap any character with a theme color
+console.log(Glyph.colorize('custom', 'success'));
+```
+
 ### Loader (CLI spinner)
 
 ```typescript
@@ -168,12 +288,12 @@ const pw = await Input.readPassword({ message: 'Password:' });
 ```typescript
 import { renderMarkdown } from '@easbot/terminal';
 
-console.log(renderMarkdown('# Title\n\nHello **world**.', { stripAnsi: true }).join('\n'));
+console.log(renderMarkdown('# Title\n\nHello **world**.', opts).join('\n'));
 ```
 
-Supports `# / ## / ###` headings, `-` / `*` / `1.` lists, fenced code blocks, and inline `**bold**` / `*italic*` / `` `code` `` / `[text](url)`. Does not depend on `marked` — keeps the bundle small for CLI output.
+Supports `# / ## / ###` headings, `---` horizontal rules, `-` / `*` / `1.` lists, fenced code blocks, and inline `**bold**` / `*italic*` / `` `code` `` / `[text](url)`. Does not depend on `marked` — keeps the bundle small for CLI output.
 
-### Searchable multi-select
+### Searchable multi-select (`Search.multiselect`)
 
 ```typescript
 import { Search, cancelSymbol } from '@easbot/terminal';
@@ -220,13 +340,29 @@ writer.write('second\n');
 ### CLI `--json` contract
 
 ```typescript
-import { emitJsonOk, emitJsonError } from '@easbot/terminal';
+import { emitJson, emitJsonOk, emitJsonError, wrapJson, wrapError } from '@easbot/terminal';
 
+// Low-level: build envelopes
+const env = wrapJson({ items: [{ id: 1 }] }, { count: 1 });
+// { ok: true, data: { items: [{ id: 1 }] }, meta: { count: 1 } }
+const err = wrapError({ reason: 'not found' });
+// { ok: false, data: { reason: 'not found' } }
+
+// High-level: emit straight to stdout
 emitJsonOk({ items: [{ id: 1 }, { id: 2 }] }, { count: 2 });
-// {"ok":true,"data":{"items":[{"id":1},{"id":2}]},"meta":{"count":2}}
+// stdout:
+// {
+//   "ok": true,
+//   "data": { "items": [{ "id": 1 }, { "id": 2 }] },
+//   "meta": { "count": 2 }
+// }
 
 emitJsonError('E_NOT_FOUND', 'Resource not found');
-// {"ok":false,"error":{"code":"E_NOT_FOUND","message":"Resource not found"}}
+// stdout:
+// {
+//   "ok": false,
+//   "error": { "code": "E_NOT_FOUND", "message": "Resource not found" }
+// }
 ```
 
 ## API Overview
@@ -240,7 +376,7 @@ emitJsonError('E_NOT_FOUND', 'Resource not found');
 
 ### ANSI utilities
 
-- `stripAnsi(input)` — strip SGR / OSC-8 sequences from a string
+- `stripAnsi(input)` — strip ANSI SGR / OSC-8 sequences from a string
 - `visibleWidth(input)` — visible character width after stripping ANSI
 
 ### Paths & display
@@ -266,26 +402,50 @@ emitJsonError('E_NOT_FOUND', 'Resource not found');
 - `TableColumn` / `RenderTableOptions` — column and render-option types
 - `renderTable(opts)` — render a table string
 
-### Styled prompts
+### Human output helpers
+
+- `PrintHumanOptions` / `RenderLinesGroup` / `RenderLinesOptions` — types
+- `printHuman(lines, opts)` — render `lines` + `title` + `outro` as a single page (boxed variant goes through `note()`)
+- `formatPrintHuman(lines, opts)` — same as `printHuman` but returns the string (for embedding)
+- `renderLines(opts)` — build a grouped tree (list / find / store-list style)
+- `printRenderLines(opts)` — same as `renderLines` but prints directly
+- `formatListTruncated(items, maxShow?)` / `formatList(items, maxShow?)` — truncate long lists to ≤N with a `"+K more"` suffix
+
+### Styled prompts (low-level)
 
 - `stylePromptMessage` / `stylePromptTitle` / `stylePromptHint` — prompt text styling
 - `selectStyled<T>(params)` — themed select prompt
 - `note(message, title?, options?)` — themed note box (supports `columns` / `maxWidth` injection)
 - `wrapNoteMessage(message, options?)` — auto-wrap a note's message
 
-### Interactive multi-select
-
-- `Search.multiselect<T>(options)` — searchable, real-time-filtered multi-select prompt
-  - `options.message` — prompt message
-  - `options.items` — selectable items
-  - `options.maxVisible?` — page size
-  - `options.initialSelected?` — pre-selected values (deduplicated)
-  - `options.required?` — reject empty submission
-  - `options.lockedSection?` — always-included partition
-  - `options.isTTY?` — explicit TTY state (test / embedded injection)
-- `Search.cancelSymbol` — sentinel returned on cancel / stdin end
-- `Search.approxStringWidth` / `Search.visualRowsForLine` / `Search.countVisualRowsForLines` — display-width helpers
-- `cancelSymbol` — top-level re-export of `Search.cancelSymbol` (kept for backwards compatibility)
+### **Prompt namespace (unified entry point)**
+
+The single recommended entry point for business code. Details in the "Prompt namespace" section above:
+
+- `Prompt.select<T>(opts)` — single-select
+- `Prompt.groupMultiselect<T>(opts)` — grouped multi-select
+- `Prompt.multiselect<T>(opts)` — searchable multi-select (fuzzy + locked section + pagination)
+- `Prompt.text(opts)` — text input
+- `Prompt.password(opts)` — hidden input
+- `Prompt.confirm(opts)` — y/n confirmation
+- `Prompt.intro(title)` — flow header (heading + decoration line)
+- `Prompt.outro(message?, { success? })` — flow footer (success/error themed)
+- `Prompt.cancel(message?)` — `never`, internal `process.exit(0)`
+- `Prompt.cancelSymbol` — single sentinel (same reference as `Search.cancelSymbol`)
+- `Prompt.isCancel(value)` — type guard
+- `Prompt.spinner(opts?)` — thin wrapper over `Loader.create`, returns `SpinnerInstance`
+- `Prompt.SpinnerInstance` — `{ start, stop, update, line }`
+- `Prompt.Log.info / warn / error / success / step / message(msg, detail?)` — status log
+
+### Icons / Symbols (unified source of truth)
+
+- `Symbol` namespace:
+  - `Symbol.icons: Record<SymbolKind, string>` — status icon literals (`success/error/warning/info/accent/muted/heading/active/submit/cancel/locked/pending/radioActive/radioInactive/skipped/blocked/cursor`)
+  - `Symbol.bar.{ vertical, horizontal, cornerBottom, cornerBottomRight, teeRight, stepActive, bullet }`
+  - `Symbol.colorize(char, kind)` — wrap any character with a theme color
+  - `Symbol.statusIcon(kind)` — return `Symbol.icons[kind]` themed
+  - `Symbol.prefixed(kind, text)` — `"<icon> <text>"` format
+- `SymbolKind` type
 
 ### Loader (CLI spinner)
 
@@ -309,19 +469,24 @@ emitJsonError('E_NOT_FOUND', 'Resource not found');
 `Input` is a **namespace** with three stateless helpers. Pass `input` / `output` to swap in a mock stream for tests.
 
 - `Input.readText(options)` — read a single line. Options: `message`, `hint?`, `defaultValue?`, `hidden?`, `messageColor?`, `hintColor?`, `input?`, `output?`
-- `Input.readConfirm(options)` — yes/no prompt; recursively re-prompts on invalid input. Options: `message`, `hint?`, `defaultValue?` (default `true`)
+- `Input.readConfirm(options)` — yes/no prompt; recursively re-prompts on invalid input. Options: `message`, `hint?`, `defaultValue?` (default `true`), `messageColor?`, `hintColor?`, `input?`, `output?`
 - `Input.readPassword(options)` — alias for `readText` with `hidden: true`
 
 ### Markdown (minimal subset)
 
 - `renderMarkdown(md, opts?)` → `string[]` (one entry per logical line)
-  - Supports: `# / ## / ###` headings, `---` horizontal rules, `- / * / 1.` lists, fenced code blocks (` ``` `), inline `**bold**` / `*italic*` / `` `code` `` / `[text](url)`
+  - Supports: `# / ## / ###` headings, `---` horizontal rules, `-` / `*` / `1.` lists, fenced code blocks (` ``` `), inline `**bold**` / `*italic*` / `` `code` `` / `[text](url)`
   - `opts.headingColor?` / `boldColor?` / `italicColor?` / `codeColor?` / `linkColor?` — color functions to override the default theme
 
-### CLI JSON output
+### JSON contract output
 
-- `emitJsonOk(data, meta?)` — emit `{ ok: true, data, meta? }`
-- `emitJsonError(code, message)` — emit `{ ok: false, error: { code, message } }`
+- `wrapJson<T>(data, meta?, ok?)` → `JsonEnvelope<T>` (build envelope; `ok` defaults to `true`)
+- `wrapError<T>(data, meta?)` → `JsonEnvelope<T>` (`ok:false` error variant)
+- `emitJson(envelope, indent?)` — serialize + `console.log`
+- `emitCommandJson(envelope)` — same as above with fixed `indent=2`
+- `emitJsonOk(data, meta?)` — emit `{ ok: true, data, meta? }` directly
+- `emitJsonError(code, message)` — emit `{ ok: false, error: { code, message } }` directly
+- `JsonEnvelope<T>` — `{ ok: boolean; data: T; meta?: Record<string, unknown> }`
 
 ### Streams & state
 

package/README.md

@@ -2,11 +2,11 @@
 
 # @easbot/terminal
 
-> 终端交互工具库 — 为 EASBOT 生态提供统一的终端输出、格式化、提示与状态恢复能力。
+> 终端交互工具库 — 为 EASBOT 生态提供统一的终端输出、格式化、提示、Prompt 与状态恢复能力。
 
 ## 简介
 
-`@easbot/terminal` 是一个面向 EASBOT 生态的终端交互工具库，封装了命令行 / TUI 场景下常用的能力：终端主题色、ANSI 处理、超链接、表格渲染、提示样式、安全流写入、进度行管理、终端状态恢复、一个**可搜索的多选交互 prompt**、一个**CLI 输入 helper** 以及一个**轻量级 markdown 渲染器**。所有能力都基于终端能力自动检测（`NO_COLOR` / `FORCE_COLOR` / TTY）进行降级，可在管道、文件重定向等非 TTY 场景下安全使用。
+`@easbot/terminal` 是一个面向 EASBOT 生态的终端交互工具库，封装了命令行 / TUI 场景下常用的能力：终端主题色、ANSI 处理、表格渲染、命令输出格式化、提示样式化、JSON 规范输出、人类输出统一封装（`printHuman` / `renderLines`）、一个**统一的交互式 Prompt namespace**、一个**可搜索的多选交互 prompt**、一个**CLI 输入 helper**、一个**轻量级 markdown 渲染器**、图标 / 状态符号统一常量、Loader 旋转动画、终端状态恢复等。所有能力都基于终端能力自动检测（`NO_COLOR` / `FORCE_COLOR` / TTY）进行降级，可在管道、文件重定向等非 TTY 场景下安全使用。
 
 本包**完全 vendor-neutral**：不绑定任何外部文档站或 vendor-specific 配置。`formatRootedLink` / `formatRootLink` 等 helper 显式接受 `root` 参数，由调用方决定集成方式。
 
@@ -19,15 +19,18 @@
 - **OSC-8 超链接**：跨平台终端超链接，自动检测终端能力，提供降级文本
 - **表格渲染**：`renderTable` 支持自适应列宽、Unicode / ASCII / 无边框三种样式、文本换行、ANSI 样式保持
 - **命令输出格式化**：成功 / 错误 / 警告 / 信息 / 标题 / 键值对 / 命令示例 / 列表项 / 进度状态 / 计数等
-- **提示样式化**：`@clack/prompts` 的样式化封装（`selectStyled` / `note` / `stylePromptMessage` 等）
+- **提示样式化**：纯样式化封装（`selectStyled` / `note` / `stylePromptMessage` / `stylePromptTitle` / `stylePromptHint`）
+- **统一交互 Prompt namespace**：`Prompt.select / groupMultiselect / text / password / confirm / multiselect / intro / outro / cancel / Log.* / spinner` —— 业务方**唯一**交互入口（详见"Prompt namespace"节）
 - **可搜索多选 prompt**：`Search.multiselect` 是交互式、实时过滤的多选 prompt，支持完整键盘控制、可选锁定分区、对 stdin / 信号优雅清理
 - **Loader 旋转动画**：`Loader.create()` 返回**stateless** spinner 实例（不继承 tui 组件模型），可定制帧 / 颜色 / 消息
 - **Input CLI 输入**：`Input.readText` / `Input.readConfirm` / `Input.readPassword` 是 readline 薄包装的 CLI prompt；支持注入 `input` / `output` 用于测试隔离
 - **Markdown 渲染**：`renderMarkdown` 解析极简 markdown 子集（标题 / 列表 / 代码块 / 加粗 / 斜体 / 链接），**不引 `marked`**，保持 CLI 包体小
+- **人类输出统一封装**：`printHuman(lines, { title, outro })` 把分组细节 + 总结 + outro 收尾一页搞定，所有 CLI 子命令默认人类输出走这条
+- **图标 / 状态符号统一**：所有 `✓ / ✗ / ⚠ / ℹ / ◆ / ● / ○ / │ / ─ / ┘ / • / ↡ / ⊘` 等图标硬编码仅出现在 `symbols.ts`，业务方通过 `Symbol.statusIcon(...)` / `Symbol.colorize(...)` 调用
+- **JSON 规范输出**：`emitJson / emitJsonOk / emitJsonError / wrapJson / wrapError` 实现 CLI `--json` 规范的 `{ ok, data, meta? }` / `{ ok, false, error: { code, message } }` 协议
 - **安全流写入**：`createSafeStreamWriter` 自动处理 `EPIPE` / `EIO`，流关闭后静默忽略后续写入
 - **进度行管理**：注册 / 清除 / 注销活动进度行，仅在 TTY 下生效
 - **终端状态恢复**：`restoreTerminalState` 在退出 / 异常时重置光标、鼠标跟踪、括号粘贴模式
-- **JSON 规范输出**：`emitJsonOk` / `emitJsonError` 实现 CLI `--json` 规范的 `{ ok, data | error }` 协议
 - **色彩一致性**：所有样式化输出统一经过 `isRich()` + `colorize()`，快照 / 非 TTY 场景不会泄漏 ANSI 转义
 - **TTY 注入**：交互组件（`formatTerminalLink`、`Search.multiselect`、`Input.readText` 等）接受可选 `isTTY` 参数，单元测试不再依赖 `process.stdout.isTTY`
 
@@ -105,8 +108,8 @@ console.log(
       { key: 'status', header: '状态', align: 'center' },
     ],
     rows: [
-      { name: '@easbot/terminal', version: '0.3.11', status: '✓' },
-      { name: '@easbot/note', version: '0.3.11', status: '✓' },
+      { name: '@easbot/terminal', version: '0.3.13', status: '✓' },
+      { name: '@easbot/note', version: '0.3.13', status: '✓' },
     ],
     width: 80,
     border: 'unicode',
@@ -114,7 +117,99 @@ console.log(
 );
 ```
 
-### 样式化提示
+### 人类输出统一封装（printHuman）
+
+```typescript
+import { printHuman, renderLines } from '@easbot/terminal';
+
+// 业务侧常见的"分组细节 + 总结 + outro"一页输出
+printHuman(
+  ['  ✓ eas-agent-creation', '  ✓ eas-agent-evolution', '  ✗ eas-legacy-tool'],
+  {
+    title: 'Project Skills Update',
+    outro: 'Run `easbot skills list` to see current state.',
+    empty: 'No skills tracked in lock file.',
+  },
+);
+
+// renderLines：构造 list / find 风格的分组树状
+const lines = renderLines({
+  title: 'Project Skills (3)',
+  groups: [
+    { key: 'universal (.agents/skills)', rows: ['  ✓ foo', '  ✓ bar'] },
+    { key: 'claude-code', rows: ['  ✓ baz'] },
+  ],
+});
+```
+
+### Prompt namespace（**统一交互入口**）
+
+`Prompt` 是 `@easbot/terminal` 提供的统一交互 namespace —— **业务方唯一推荐的交互入口**。内部按 B+A 混合方案封装：
+
+- `select / groupMultiselect / text / password / confirm`：薄包 `@clack/prompts`（多年踩坑调优过的 raw mode / 信号 / 取消）
+- `multiselect`：自实现，调用本包 `Search.multiselect`（fuzzy + 锁定分区 + 翻页）
+- `intro / outro / cancel / Log.* / spinner`：自实现（chalk + theme），统一配色到本包 `theme`
+
+```typescript
+import { Prompt } from '@easbot/terminal';
+
+// 单选
+const choice = await Prompt.select({
+  message: '选择安装范围',
+  options: [
+    { value: 'project', label: 'Project', hint: '当前目录' },
+    { value: 'global', label: 'Global', hint: '主目录' },
+  ],
+});
+if (Prompt.isCancel(choice)) Prompt.cancel('用户已取消');
+
+// 多选
+const selected = await Prompt.multiselect({
+  message: '选择要启用的 Agent',
+  options: [
+    { value: 'claude-code', label: 'Claude Code' },
+    { value: 'easbot', label: 'EASBot' },
+  ],
+  initialValues: ['easbot'], // 预选
+  required: true,
+});
+
+// 分组多选
+const skills = await Prompt.groupMultiselect({
+  message: '选择要安装的技能',
+  options: {
+    General: [{ value: 'foo', label: 'foo' }, { value: 'bar', label: 'bar' }],
+    'Advanced Plugins': [{ value: 'baz', label: 'baz' }],
+  },
+});
+
+// 流程骨架
+Prompt.intro(' skills ');
+// ... do something ...
+Prompt.outro(pc.green('Done!'));
+
+// 取消：Prompt.cancel 是 `never`，内置 process.exit(0)
+if (Prompt.isCancel(selected)) Prompt.cancel('用户已取消');
+
+// 状态流（统一配色到 terminal theme）
+Prompt.Log.info('操作成功');
+Prompt.Log.warn('警告');
+Prompt.Log.error('错误');
+Prompt.Log.step('步骤');
+Prompt.Log.message('普通消息（无前缀）');
+
+// Spinner
+const spinner = Prompt.spinner();
+spinner.start('解析源...');
+spinner.stop(`Found ${count} skill(s)`);
+```
+
+**取消语义收口**：
+- `Prompt.cancelSymbol` —— 唯一 sentinel（与 `Search.cancelSymbol` 同引用）
+- `Prompt.isCancel(value)` —— 类型守卫，同时识别 `Prompt.cancelSymbol` 与 clack 的 `Symbol('')`
+- `Prompt.cancel(message?)` —— `never` 返回 + 内置 `process.exit(0)`
+
+### 样式化提示（低阶辅助）
 
 ```typescript
 import { selectStyled, note, wrapNoteMessage } from '@easbot/terminal';
@@ -130,6 +225,30 @@ const choice = await selectStyled({
 note(wrapNoteMessage('配置文件已成功保存到 ~/.config/app/config.json'), '成功');
 ```
 
+### 图标 / 符号（**统一硬编码源**）
+
+业务方**禁止**直接写 `✓ ✗ ⚠ ℹ ◆ ● ○ │ ─ •` 等字面量。所有图标必须通过 `Symbol` namespace 取得。
+
+```typescript
+import { Symbol as Glyph } from '@easbot/terminal';
+
+// 状态图标（自带主题色）
+console.log(`${Glyph.statusIcon('success')} 操作成功`); // ✓ 绿色
+console.log(`${Glyph.statusIcon('error')} 操作失败`); // ✗ 红色
+console.log(`${Glyph.statusIcon('warning')} 警告`); // ⚠ 黄色
+console.log(`${Glyph.statusIcon('info')} 提示`); // ℹ 蓝色
+console.log(`${Glyph.statusIcon('active')} 进行中`); // ◆ 强调色
+console.log(`${Glyph.statusIcon('skipped')} 已跳过`); // ↡ 灰色
+console.log(`${Glyph.statusIcon('blocked')} 已拦截`); // ⊘ 红色
+
+// 装饰条
+console.log(Glyph.bar.vertical); // │
+console.log(Glyph.bar.bullet); // •
+
+// 任意字符套上主题色
+console.log(Glyph.colorize('自定义字符', 'success'));
+```
+
 ### Loader 旋转动画
 
 ```typescript
@@ -220,13 +339,20 @@ writer.write('second\n');
 ### CLI `--json` 规范输出
 
 ```typescript
-import { emitJsonOk, emitJsonError } from '@easbot/terminal';
+import { emitJson, emitJsonOk, emitJsonError, wrapJson, wrapError } from '@easbot/terminal';
 
+// 低阶：构造 envelope
+const env = wrapJson({ items: [{ id: 1 }] }, { count: 1 });
+// { ok: true, data: { items: [{ id: 1 }] }, meta: { count: 1 } }
+const err = wrapError({ reason: 'not found' });
+// { ok: false, data: { reason: 'not found' } }
+
+// 高阶：直接 emit 到 stdout
 emitJsonOk({ items: [{ id: 1 }, { id: 2 }] }, { count: 2 });
-// {"ok":true,"data":{"items":[{"id":1},{"id":2}]},"meta":{"count":2}}
+// stdout: { "ok": true, "data": { "items": [...] }, "meta": { "count": 2 } }
 
 emitJsonError('E_NOT_FOUND', '资源不存在');
-// {"ok":false,"error":{"code":"E_NOT_FOUND","message":"资源不存在"}}
+// stdout: { "ok": false, "error": { "code": "E_NOT_FOUND", "message": "资源不存在" } }
 ```
 
 ## API 总览
@@ -266,26 +392,50 @@ emitJsonError('E_NOT_FOUND', '资源不存在');
 - `TableColumn` / `RenderTableOptions` — 表格列配置与渲染选项类型
 - `renderTable(opts)` — 渲染表格字符串
 
-### 提示样式化
+### 人类输出统一封装
+
+- `PrintHumanOptions` / `RenderLinesGroup` / `RenderLinesOptions` — 类型
+- `printHuman(lines, opts)` — `lines` + `title` + `outro` 一页输出（boxed 走 `note()`）
+- `formatPrintHuman(lines, opts)` — 返回字符串而非直接打印（用于嵌入更大输出）
+- `renderLines(opts)` — 构造分组树状行（list / find / store list 风格）
+- `printRenderLines(opts)` — 同上但直接打印
+- `formatListTruncated(items, maxShow?)` / `formatList(items, maxShow?)` — 截断列表（≤N 全显 + "N more" 提示）
+
+### 提示样式化（低阶）
 
 - `stylePromptMessage` / `stylePromptTitle` / `stylePromptHint` — 提示文本样式化
 - `selectStyled<T>(params)` — 样式化的选择提示
 - `note(message, title?, options?)` — 样式化的注释框（支持 `columns` / `maxWidth` 注入）
 - `wrapNoteMessage(message, options?)` — 注释消息自动换行
 
-### 交互式多选
-
-- `Search.multiselect<T>(options)` — 可搜索、实时过滤的多选 prompt
-  - `options.message` — 提示信息
-  - `options.items` — 候选项列表
-  - `options.maxVisible?` — 每页显示条数
-  - `options.initialSelected?` — 预选值集合（去重）
-  - `options.required?` — 是否强制至少选一项
-  - `options.lockedSection?` — 始终包含的锁定分区
-  - `options.isTTY?` — 显式 TTY 状态（测试 / 嵌入式注入）
-- `Search.cancelSymbol` — 用户取消或 stdin 关闭时返回的哨兵值
-- `Search.approxStringWidth` / `Search.visualRowsForLine` / `Search.countVisualRowsForLines` — 渲染器用到的显示宽度辅助
-- `cancelSymbol` — 顶层再导出，等价于 `Search.cancelSymbol`（保留旧调用点无需改动）
+### **Prompt namespace（统一交互入口）**
+
+业务方**唯一推荐的交互入口**。细节见上文"Prompt namespace"节：
+
+- `Prompt.select<T>(opts)` — 单选
+- `Prompt.groupMultiselect<T>(opts)` — 分组多选
+- `Prompt.multiselect<T>(opts)` — 搜索多选（带 fuzzy + 锁定分区 + 翻页）
+- `Prompt.text(opts)` — 文本输入
+- `Prompt.password(opts)` — 隐藏输入
+- `Prompt.confirm(opts)` — y/n 确认
+- `Prompt.intro(title)` — 流程开篇（heading + 装饰线）
+- `Prompt.outro(message?, { success? })` — 流程收尾（success/error 主题色）
+- `Prompt.cancel(message?)` — `never`，内置 `process.exit(0)`
+- `Prompt.cancelSymbol` — 唯一 sentinel（与 `Search.cancelSymbol` 同引用）
+- `Prompt.isCancel(value)` — 类型守卫
+- `Prompt.spinner(opts?)` — Loader.create 薄包装，返回 `SpinnerInstance`
+- `Prompt.SpinnerInstance` — `{ start, stop, update, line }`
+- `Prompt.Log.info / warn / error / success / step / message(msg, detail?)` — 状态流
+
+### 图标 / 符号（统一硬编码源）
+
+- `Symbol` namespace：
+  - `Symbol.icons: Record<SymbolKind, string>` — 状态图标裸字符（`success/error/warning/info/accent/muted/heading/active/submit/cancel/locked/pending/radioActive/radioInactive/skipped/blocked/cursor`）
+  - `Symbol.bar.{ vertical, horizontal, cornerBottom, cornerBottomRight, teeRight, stepActive, bullet }`
+  - `Symbol.colorize(char, kind)` — 任意字符套上主题色
+  - `Symbol.statusIcon(kind)` — 返回 `Symbol.icons[kind]` + 主题色
+  - `Symbol.prefixed(kind, text)` — `"<icon> <text>"` 形式前缀
+- `SymbolKind` 类型
 
 ### Loader 旋转动画
 
@@ -309,7 +459,7 @@ emitJsonError('E_NOT_FOUND', '资源不存在');
 `Input` 是 **namespace**，含 3 个 stateless helper。测试时通过 `input` / `output` 注入 mock stream。
 
 - `Input.readText(options)` — 读单行。Options: `message` / `hint?` / `defaultValue?` / `hidden?` / `messageColor?` / `hintColor?` / `input?` / `output?`
-- `Input.readConfirm(options)` — y/n 确认，无效输入会递归重试。Options: `message` / `hint?` / `defaultValue?`（默认 `true`）
+- `Input.readConfirm(options)` — y/n 确认，无效输入会递归重试。Options: `message` / `hint?` / `defaultValue?`（默认 `true`）/ `messageColor?` / `hintColor?` / `input?` / `output?`
 - `Input.readPassword(options)` — `readText` 的 `hidden: true` 别名
 
 ### Markdown 渲染
@@ -320,8 +470,13 @@ emitJsonError('E_NOT_FOUND', '资源不存在');
 
 ### JSON 规范输出
 
-- `emitJsonOk(data, meta?)` — 输出 `{ ok: true, data, meta? }` JSON 响应
-- `emitJsonError(code, message)` — 输出 `{ ok: false, error: { code, message } }` JSON 响应
+- `wrapJson<T>(data, meta?, ok?)` → `JsonEnvelope<T>`（构造 envelope；ok 默认 true）
+- `wrapError<T>(data, meta?)` → `JsonEnvelope<T>`（ok:false 错误态）
+- `emitJson(envelope, indent?)` → 序列化 + console.log
+- `emitCommandJson(envelope)` — 同上固定 indent=2
+- `emitJsonOk(data, meta?)` — 直接 emit `{ ok: true, data, meta? }`
+- `emitJsonError(code, message)` — 直接 emit `{ ok: false, error: { code, message } }`
+- `JsonEnvelope<T>` — `{ ok: boolean; data: T; meta?: Record<string, unknown> }`
 
 ### 流与状态