# 渐进式披露：如何用"少即是多"的理念改进 AI 产品的人机交互

> 在 AI 产品设计中，用户输入的质量往往决定了输出的质量。本文分享我们在 HagiCode 项目中实践的一套"渐进式披露"交互方案，通过分步引导、智能补全和即时反馈，将用户简短模糊的输入转化为结构化的技术提案，显著提升了人机交互效率。

## 背景

做 AI 产品的同学应该都遇到过这样的场景：用户打开你的应用，兴致勃勃地输入一行需求，结果 AI 返回的内容完全不搭边。不是 AI 不聪明，只是用户给的信息太少了，毕竟猜心这种事，谁也做不好。

这种现象在我们开发 HagiCode 的过程中尤为明显。HagiCode 是一个 AI 驱动的代码助手，用户通过自然语言描述需求来创建技术提案和会话。可在实际使用中，我们发现用户输入的内容往往存在这些问题：

- **输入质量参差不齐**：有的用户只输入几个字，比如"优化登录"、"修复 bug"，缺乏必要的上下文
- **技术术语不统一**：不同用户用不同的词说同一件事，有人说"前端"有人说"FE"
- **缺少结构化信息**：没有项目背景、没有仓库范围、没有影响范围这些关键信息
- **重复性问题**：相同类型的需求反复出现，每次都要从头解释

这些问题导致的直接后果就是：AI 理解困难、生成的提案质量不稳定、用户体验差。用户觉得"这 AI 不行啊"，我们也很委屈——你只给一句话，让我怎么猜你想要啥？

其实这也没办法，毕竟人和人之间的理解都需要时间，更何况是机器呢？

为了解决这些痛点，我们做了一个大胆的决定：引入"渐进式披露"的设计理念来改进人机交互。这个决定带来的变化，可能比你想象的还要大，只是当时我们也没想到会这么有效罢了。

## 关于 HagiCode

本文分享的方案来自我们在 [HagiCode](https://hagicode.com) 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，旨在通过自然语言交互帮助开发者完成代码编写、技术提案生成、代码审查等任务。项目地址：[github.com/HagiCode-org/site](https://github.com/HagiCode-org/site)。

这套渐进式披露方案是我们在实际开发过程中，经过多次迭代和优化总结出来的。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下，毕竟好东西是值得分享的。

## 什么是渐进式披露

"渐进式披露"（Progressive Disclosure）是一个源自 HCI（人机交互）领域的设计原则，核心思想很简单：**不要一次性把所有信息和选项都展示给用户，而是根据用户的操作和需求，逐步展示必要的内容**。

这个原则特别适合 AI 产品，因为 AI 交互天然就是渐进式的——用户说一点，AI 理解一点，然后补充一点，再理解更多。就像人与人之间的交流一样，总得慢慢来，毕竟谁也不能一见面就把心掏出来不是？

具体到 HagiCode 的场景，我们从四个方面实施了渐进式披露：

### 1. 描述优化机制：让 AI 帮你把话说清楚

当用户输入简短描述时，我们不是直接让 AI 去理解，而是先触发一个"描述优化"流程。这个流程的核心是"结构化输出"——把用户的自由文本转化为标准格式。就像把散落一地的珍珠串成项链，看起来也就不那么乱了。

优化后的描述必须包含以下几个标准章节：

- **背景**：问题背景和上下文
- **分析**：技术分析和思考过程
- **解决**：解决方案和实施步骤
- **实践**：实际代码示例和注意事项

同时，我们还会自动生成一个 Markdown 表格，展示目标仓库、路径、编辑权限等信息，方便 AI 后续操作。毕竟有个清晰的目录，找起东西来也方便。

下面是实际的代码实现：

```csharp
// ProposalDescriptionMemoryService.cs 中的核心方法
public async Task<string> OptimizeDescriptionAsync(
    string title,
    string description,
    string locale = "zh-CN",
    DescriptionOptimizationMemoryContext? memoryContext = null,
    CancellationToken cancellationToken = default)
{
    // 构建查询参数
    var queryContext = BuildQueryContext(title, description);

    // 检索历史上下文
    var memoryContext = await RetrieveHistoricalContextAsync(queryContext, cancellationToken);

    // 生成结构化提示词
    var prompt = await BuildOptimizationPromptAsync(
        title,
        description,
        memoryContext,
        cancellationToken);

    // 调用 AI 进行优化
    return await _aiService.CompleteAsync(prompt, cancellationToken);
}
```

这个流程的关键在于"记忆注入"——我们会把项目惯例、相似案例、负面模式等历史上下文注入到提示词中，让 AI 在优化时能够参考过去的经验。毕竟吃一堑长一智，过去的经验总不能白白浪费了不是？

**注意事项**：
- 确保当前输入优先于历史记忆，避免覆盖用户显式指定的信息
- HagIndex 引用必须作为事实来源，不得被历史案例修改
- 低置信度的纠错建议不应作为强约束注入

### 2. 语音输入能力：说话比打字更自然

除了文本输入，我们还支持语音输入。这在描述复杂需求时特别有用——你想想，打一段技术需求可能要几分钟，但说可能几十秒就完事了，毕竟嘴总是比手快。

语音输入的设计重点是"状态管理"，用户必须清楚当前系统处于什么状态。我们定义了以下几种状态：

- **空闲**：系统就绪，可以开始录制
- **等待上游**：正在连接后端服务
- **录制中**：正在录制用户语音
- **处理中**：正在将语音转换为文本
- **错误**：发生错误，需要用户处理

前端的状态模型大概是这样的：

```typescript
interface VoiceInputState {
  status: 'idle' | 'waiting-upstream' | 'recording' | 'processing' | 'error';
  duration: number;
  error?: string;
  deletedSet: Set<string>; // 已删除结果的指纹集合
}

// 开始录制时的状态转换
const handleVoiceInputStart = async () => {
  // 先进入等待状态，显示加载动画
  setState({ status: 'waiting-upstream' });

  // 等待后端就绪确认
  const isReady = await waitForBackendReady();
  if (!isReady) {
    setState({ status: 'error', error: '后端服务未就绪' });
    return;
  }

  // 开始录制
  setState({ status: 'recording', startTime: Date.now() });
};

// 处理识别结果
const handleRecognitionResult = (result: RecognitionResult) => {
  const fingerprint = normalizeFingerprint(result.text);

  // 检查是否已被删除
  if (state.deletedSet.has(fingerprint)) {
    return; // 跳过已删除的内容
  }

  // 合并结果到文本框
  appendResult(result);
};
```

这里有个细节：我们用"指纹集合"来管理删除同步。当语音识别返回多条结果时，用户可能会删除其中一些。我们把已删除内容的指纹存起来，后续如果相同内容再出现就自动跳过。这就像记住了哪些菜不爱吃，下次就不会再点了，毕竟谁也不想被同样的问题困扰两次。

### 3. 提示词管理系统：把 AI 的"脑子"外置

HagiCode 有一个灵活的提示词管理系统，所有提示词都以文件形式存储：

```
prompts/
├── metadata/
│   ├── optimize-description.zh-CN.json
│   └── optimize-description.en-US.json
└── templates/
    ├── optimize-description.zh-CN.hbs
    └── optimize-description.en-US.hbs
```

每个提示词由两部分组成：
- **元数据文件（.json）**：定义提示词的场景、版本、参数等信息
- **模板文件（.hbs）**：使用 Handlebars 语法的实际提示词内容

元数据文件的格式是这样的：

```json
{
  "scenario": "optimize-description",
  "locale": "zh-CN",
  "version": "1.0.0",
  "syntax": "handlebars",
  "syntaxVersion": "1.0",
  "parameters": [
    {
      "name": "title",
      "type": "string",
      "required": true,
      "description": "提案标题"
    },
    {
      "name": "description",
      "type": "string",
      "required": true,
      "description": "原始描述"
    }
  ],
  "author": "HagiCode Team",
  "description": "优化用户输入的技术提案描述",
  "lastModified": "2026-04-05",
  "tags": ["optimization", "nlp"]
}
```

模板文件使用 Handlebars 语法，支持参数注入：

```handlebars
你是一个技术提案专家。

<task>
根据以下信息生成结构化的技术提案描述。
</task>

<input>
<title>{{title}}</title>
<description>{{description}}</description>
{{#if memoryContext}}
<memory_context>
{{memoryContext}}
</memory_context>
{{/if}}
</input>

<output_format>
## 背景
[描述问题背景和上下文，包括项目信息、仓库范围等]

## 分析
[技术分析和思考过程，说明为什么需要这个改动]

## 解决
[解决方案和实施步骤，列出关键代码位置]

## 实践
[实际代码示例和注意事项]
</output_format>
```

这种设计的好处是：
- 提示词可以像代码一样版本管理
- 支持多语言，根据用户偏好自动切换
- 参数化设计，可以动态注入上下文
- 启动时验证完备性，避免运行时出错

毕竟脑子里的东西不写下来，谁也不知道什么时候就忘了，与其到时候懊悔，不如一开始就做好记录罢了。

### 4. 渐进式向导：复杂任务拆成小步

对于复杂任务（比如首次安装配置），我们使用了多步骤向导的设计。每个步骤只请求必要信息，并提供清晰的进度指示。生活也是这样嘛，一口吃不成胖子，一步一步来反而更稳妥。

向导的状态模型：

```typescript
interface WizardState {
  currentStep: number;           // 0-3，对应 4 个步骤
  steps: WizardStep[];
  canGoNext: boolean;
  canGoBack: boolean;
  isLoading: boolean;
  error: string | null;
}

interface WizardStep {
  id: number;
  title: string;
  description: string;
  completed: boolean;
}

// 步骤导航逻辑
const goToNextStep = () => {
  if (wizardState.currentStep < wizardState.steps.length - 1) {
    // 验证当前步骤的输入
    if (validateCurrentStep()) {
      wizardState.currentStep++;
      wizardState.steps[wizardState.currentStep - 1].completed = true;
    }
  }
};

const goToPreviousStep = () => {
  if (wizardState.currentStep > 0) {
    wizardState.currentStep--;
  }
};
```

每个步骤都有独立的验证逻辑，已完成步骤会有清晰的视觉标记。取消操作会弹出确认对话框，防止用户误操作丢失进度。毕竟走错路可以回头，但如果把路都拆了，那就真的没辙了。

## 总结

回顾 HagiCode 的渐进式披露实践，我们可以总结出几个核心原则：

1. **分步引导**：把复杂任务拆成小步，每步只请求必要信息
2. **智能补全**：利用历史上下文和项目知识自动补全信息
3. **即时反馈**：每个操作都有清晰的视觉反馈和状态提示
4. **容错机制**：允许用户撤销、重置，避免错误造成不可逆损失
5. **输入多样化**：支持文本、语音等多种输入方式

这套方案在 HagiCode 中的实际效果是：用户输入的平均长度从不到 20 字提升到了结构化的 200-300 字，AI 生成的提案质量显著提高，用户满意度也跟着上来了。

其实这也不奇怪，毕竟你给的信息越多，AI 理解得越准确，返回的结果自然就越好，这和人与人之间的交流也没什么两样。

如果你也在做 AI 相关的产品，希望这些经验能给你带来一些启发。记住：用户不是不想给信息，而是你还没问对问题。渐进式披露的核心，就是找到问问题的最佳时机和方式，只是这个时机和方式，需要一点耐心去摸索罢了。

## 参考资料

- HagiCode 项目地址：[github.com/HagiCode-org/site](https://github.com/HagiCode-org/site)
- HagiCode 官网：[hagicode.com](https://hagicode.com)
- 渐进式披露设计原则：[Wikipedia - Progressive Disclosure](https://en.wikipedia.org/wiki/Progressive_disclosure)
- Handlebars 模板引擎：[handlebarsjs.com](https://handlebarsjs.com/)

---

如果本文对你有帮助，欢迎来 GitHub 给个 Star，关注 HagiCode 项目的后续发展。公测已经开始，现在安装即可体验完整功能：

- GitHub：[github.com/HagiCode-org/site](https://github.com/HagiCode-org/site)
- 官网：[hagicode.com](https://hagicode.com)
- 观看 30 分钟实战演示：[www.bilibili.com/video/BV1pirZBuEzq/](https://www.bilibili.com/video/BV1pirZBuEzq/)
- Docker Compose 一键安装：[docs.hagicode.com/installation/docker-compose](https://docs.hagicode.com/installation/docker-compose)
- Desktop 桌面端快速安装：[hagicode.com/desktop/](https://hagicode.com/desktop/)


## 原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。
- 本文作者: [newbe36524](https://www.newbe.pro)
- 原文链接: [https://docs.hagicode.com/go?platform=tencent-cloud-community&target=%2Fblog%2F2026-04-05-progressive-disclosure-hci%2F](https://docs.hagicode.com/go?platform=tencent-cloud-community&target=%2Fblog%2F2026-04-05-progressive-disclosure-hci%2F)
- 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!

在 AI 产品设计中，用户输入的质量往往决定了输出的质量。本文分享我们在 HagiCode 项目中实践的一套"渐进式披露"交互方案，通过分步引导、智能补全和即时反馈，将用户简短模糊的输入转化为结构化的技术提案，显著提升了人机交互效率。

渐进式披露：如何用少即是多的理念改进 AI 产品的人机交互

后端开发工程师

人工智能

前端

职业发展

渐进式披露设计提升AI交互效率：HagiCode项目实践分享如何通过分步引导、智能补全和即时反馈优化人机交互。文章详解了将简短输入转化为结构化技术提案的4种方法，包括描述优化机制、语音输入设计、提示词管理系统和渐进式向导，有效提升AI产品用户体验和输出质量。

语音识别

人机交互

Docker

GitHub

2026采购季 | AI焕新·智启新局

xiaowei

语音产品特惠新用户14.9元起


ai-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

渐进式披露：如何用少即是多的理念改进 AI 产品的人机交互-腾讯云开发者社区-腾讯云

渐进式披露：如何用少即是多的理念改进 AI 产品的人机交互

渐进式披露：如何用少即是多的理念改进 AI 产品的人机交互

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐