# @felan-ai/ext-ask-user 中文文档

规范地址：https://npmcn.com/package/%40felan-ai/ext-ask-user/

版本：0\.12\.1
npm 元数据更新时间：2026-11-13T12:30:44.543Z
中文译文更新时间：2026-11-14T13:55:49.848Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40felan-ai/ext-ask-user
原文对照：https://npmcn.com/package/%40felan-ai/ext-ask-user/?lang=original
项目主页：https://github.com/felan-ai/felan#readme
源码仓库：https://github.com/felan-ai/felan

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：102 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- peer 依赖：@felan-ai/agent-core ^0\.15\.0
- 首次发布：2026-08-06T14:52:45.809Z
- 最新版本发布：2026-11-13T12:30:43.830Z
- 近 30 天下载量：2845（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：33（近 12 个月 33 个）

## 中文简介

带有丰富的 Pi TUI 适配器的可移植 Felan 询问用户扩展

## 安装

```sh
npm install @felan-ai/ext-ask-user
```

也可以使用：`pnpm add @felan-ai/ext-ask-user`、`yarn add @felan-ai/ext-ask-user`、`bun add @felan-ai/ext-ask-user`

## README

# @ felan-ai/ ext- ask- user

便携式费兰 `ask_user` 使用通用UI表单的扩展名。 可选本地 渲染属于客户端,而不是这个软件包.

## 使用量

```ts
import askUser from '@felan-ai/ext-ask-user';

const extension = askUser;
```

默认根使用总是存在的 `pi.ui.request` API (英语). 它宣布没有服务 所需经费。 主机提供通用表格 交货、答复资格、取消和推迟交货。 扩展是 不检查客户类型或 `hasUI`选项 `ask-user.wizard` 版本 `2` 提示中包含常态问题 `data.questions` 用于客户端不进行渲染 改变形式字段或结果.

对于一个明确选择的宿主,命名的工厂仍然可以使用:

```ts
import { createAskUserExtension } from '@felan-ai/ext-ask-user';
const extension = createAskUserExtension(deliveryHost);
```

执行云或远程主机 `AskUserHost`。核心扩展拥有工具计划, 正常化、响应验证、顺序工具执行、进展细节和 代理处理结果文本 。 主办方拥有演示和交付. 主机结果是 `answered`, (中文(简体) ), `cancelled`,或 `deferred`; 延迟结果包含必要的互动 ID 这样远程主机就可以连接下一个用户回合 。 每个主机呼叫也收到 Pi工具呼叫ID和会话ID.

## 工具输入

`ask_user` 支持:

-   一个问题或一个 1-4 个问题向导
-   供应商安全 `{ title, description? }` 选项对象 遗留字符串选项和常用代理别名的运行时间兼容性
-   单选择、多选择和免费答案
-   关于结构选择的可选注释
-   可选本地适应器上线/内线模式、单选布局和快捷键
-   快速超时

顶级问题字段提供默认条目 `questions[]`. 收到的问题 稳定 `q1` 结束 `q4` 符合常态的要求的身份证和结构化的结果细节.

## 一般窗体适配器

单调产生一个 `form`,包括所有向导问题。 问题, 标题,上下文,选项标题,和描述出现时没有截取. 显示 Markdown 被从 HTML 、 链接和格式中跳出, 因为文本仍然是文字; 控制字符作为逃生序列显示。 选项标签为纯文本 .

字段使用稳定的问题ID(`q1`– 说吧 –`q4`)和后缀 `.mode`, (中文(简体) ), `.selection`, (中文(简体) ), `.text`, (中文(简体) ), 财务报告和审定财务报表 `.comment` 在适用的情况下。 选择值是 `option1`, (中文(简体) ), `option2`,等等, 说, 仅在验证后才被映射回原选项标题 。 当两个选择 并且有免费答案,需要明确的答案类型。 向导 也提供明确的跳过类型;至少必须回答一个问题。 还有 没有默认答案 。 非活动字段可能被省略; 空文本和多选择 字段也允许。 冲突非空域, 缺少答案, 未知 选项、重复选择、过多选择和对免费答案的评论 拒绝.

表格宣布提交和取消动作。 显示模式, 布局,快捷键不会改变通用形式行为。 工具的中止信号 并发送到 `pi.ui.request`; 推迟交互 ID 页:1 不支持的 UI 地图到不可用的取消 。 废物排出和 重新启动地图以中止信件中原有原因的取消 .

窗体提示所编码的JSON数据必须符合128 KiB. 书面答复和评论 各有32个KiB UTF-8限制. 多选择问题支持最多64个选项.

超过表格限制的请求在发送前返回一个明显的工具错误; 大小过大的答案也被拒绝。 内容和选项列表从不缩短 以适应。 这些界限适用于通用适配器,而不是自定义被命名的主机.

### 浏览器安全格式编码c

`@felan-ai/ext-ask-user/data` 输出问答合同, `normalizeAskUserOption`,并:

```ts
const ASK_USER_FORM_HINT = { id: 'ask-user.wizard', version: '2' };
readAskUserForm(form: UiForm): AskUserQuestion[] | null;
encodeAskUserFormAnswer(form: UiForm, answers: readonly AskUserQuestionAnswer[] | null): UiFormAnswer;
decodeAskUserFormAnswer(questions: readonly AskUserQuestion[], answer: UiFormAnswer): AskUserQuestionAnswer[] | null;
```

`readAskUserForm` 验证提示、问题、匹配字段定义和 提交/撤销动作。 它回来了 `null` 不支持的提示(包括版本) `1`、无效的有效载荷或不一致的表格;客户应制作这些表格 而不是一般地分析他们的马克倒数。 问题背景和选项 描述是纯文本,不可信 HTML 或 Markdown .

编码器映射选项标题以形成选项ID并省略向导问题到 明确跳过。 它拒绝空洞或矛盾的答案 并验证结果 对面的表格。 通过 `null` 编码取消。 解码器验证 通用答案和返回 `null` 用于取消; 至少一个向导问题 否则必须回答。 数据条目对Agent Core没有运行时间依赖性 或节点API并可用于浏览器捆绑.

## 客户端渲染

Felan的TUI使可选的向导提示. 内入 问题使用两个全宽水平分隔符; 覆盖问题使用完整 四边框. TUI 模式提供可搜索的选项描述, 分割页预览 在宽阔的终端上, 多选择、自由格式和评论编辑器、向导导航和评论、覆盖隐藏、, 中止处理和超时处理 。 长的上下文开始崩溃,所以选择仍然存在 可见; 按 `ctrl+e` 以扩张或崩溃。 多选择的取景口以 转换行并保持活动选择的可见度。 其他客户使用相同的通用 窗体; 没有交互式窗体支持的客户端返回一个不可用的结果.

关于与更古老的文字记录和计划管理代理的兼容性,运行时间选项 常态还接受字符串、数字和布尔条目及对象密钥 `label`, (中文(简体) ), `text`, (中文(简体) ), `value`, (中文(简体) ), `name`,以及 `option`。无法使用的条目返回验证 错误而不是悄悄地倒回自由形式提示 .

Felan TUI 默认生活在以下 `presentation.askUser` 内 `$FELAN_AGENT_DIR/tui/settings.json`,通过 `/settings`,或者通过 TUI 唯一的 CLI 选项:

```json
{
  "presentation": {
    "askUser": {
      "displayMode": "inline",
      "singleSelectLayout": "auto",
      "overlayToggleKey": "alt+o",
      "commentToggleKey": "ctrl+g"
    }
  }
}
```

默认是 `inline`, (中文(简体) ), `auto`, (中文(简体) ), `alt+o`,以及 `ctrl+g`分别是: 使用 `off`, (中文(简体) ), `none`, (中文(简体) ), `disabled`,或者一个可以禁用快捷键的空值。 逐个调用的工具提示仍然可选,并不加修改地传递给被命名的主机. 一般情况 形式适配器忽略它们; Felan TUI使用自己的偏好. 遗产 `extensionConfig.askUser` 只有在没有本地偏好时才读取值。 生成的 CLI 名称为 `--ask-user-display-mode`, (中文(简体) ), `--ask-user-single-select-layout`, (中文(简体) ), `--ask-user-overlay-toggle-key`,以及 `--ask-user-comment-toggle-key`。 。 。 .

## 归属

本地界面从 `pi-ask-user` 由恩佐·卢克切西所著. 见 `NOTICE` 财务报告和审定财务报表 `LICENSE` 关于来源和许可证的细节.

## 一揽子边界和要求

便携式软件包拥有工具图案, 正常化, 验证, 通用格式 绘图、进展和结果文本。 主机自己通过 `pi.ui` 或明示 `AskUserHost`。软件包需要兼容 `@felan-ai/agent-core` 端点, 会话协议和类型框 。 它没有出口TUI入站点.

## 发展

资料来源: `packages/ext-ask-user` 内 [https://github.com/felan-ai/felan 页面存档备份,存于互联网档案馆](https://github.com/felan-ai/felan)。 。 。 .

```sh
corepack enable
pnpm install --frozen-lockfile
pnpm --filter @felan-ai/ext-ask-user build
pnpm --filter @felan-ai/ext-ask-user type-check
pnpm --filter @felan-ai/ext-ask-user test
```

## 相关文件

-   [命令和快捷键](https://npmcn.com/package/docs/user-guide/commands-and-shortcuts.md)
-   [扩展目录](https://npmcn.com/package/docs/reference/extension-catalog.md)
-   [建筑](https://npmcn.com/package/docs/concepts/architecture.md)

## 常见问题

### @felan-ai/ext-ask-user 是什么？

带有丰富的 Pi TUI 适配器的可移植 Felan 询问用户扩展

### 如何安装 @felan-ai/ext-ask-user？

在项目目录运行 npm install @felan-ai/ext-ask-user，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@felan-ai/agent-core（^0\.15\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @felan-ai/ext-ask-user 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @felan-ai/ext-ask-user 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @felan-ai/ext-ask-user 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @felan-ai/ext-ask-user 可以商用吗？

@felan-ai/ext-ask-user 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @felan-ai/ext-ask-user 的下载量有多少？

根据 npm 官方下载统计，@felan-ai/ext-ask-user 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,845 次，日均约 95 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @felan-ai/ext-ask-user 还在维护吗？

最新版本 0\.12\.1 发布于 2026/11/13（1 天前）；至今共发布 33 个版本，其中过去 12 个月发布了 33 个；首次发布于 2026/08/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。