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

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

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

背景

做 AI 产品的同学应该都遇到过这样的场景：用户打开你的应用，兴致勃勃地输入一行需求，结果 AI 返回的内容完全不搭边。不是 AI 不聪明，只是用户给的信息太少了，毕竟猜心这种事，谁也做不好。
这种现象在我们开发 HagiCode 的过程中尤为明显。HagiCode 是一个 AI 驱动的代码助手，用户通过自然语言描述需求来创建技术提案和会话。可在实际使用中，我们发现用户输入的内容往往存在这些问题：

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

这些问题导致的直接后果就是：AI 理解困难、生成的提案质量不稳定、用户体验差。用户觉得"这 AI 不行啊"，我们也很委屈——你只给一句话，让我怎么猜你想要啥？
其实这也没办法，毕竟人和人之间的理解都需要时间，更何况是机器呢？
为了解决这些痛点，我们做了一个大胆的决定：引入"渐进式披露"的设计理念来改进人机交互。这个决定带来的变化，可能比你想象的还要大，只是当时我们也没想到会这么有效罢了。
关于 HagiCode

本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个开源的 AI 代码助手项目，旨在通过自然语言交互帮助开发者完成代码编写、技术提案生成、代码审查等任务。项目地址：github.com/HagiCode-org/site。
这套渐进式披露方案是我们在实际开发过程中，经过多次迭代和优化总结出来的。如果你觉得这套方案有价值，说明我们的工程实力还不错——那么 HagiCode 本身也值得关注一下，毕竟好东西是值得分享的。
什么是渐进式披露

"渐进式披露"（Progressive Disclosure）是一个源自 HCI（人机交互）领域的设计原则，核心思想很简单：不要一次性把所有信息和选项都展示给用户，而是根据用户的操作和需求，逐步展示必要的内容。
这个原则特别适合 AI 产品，因为 AI 交互天然就是渐进式的——用户说一点，AI 理解一点，然后补充一点，再理解更多。就像人与人之间的交流一样，总得慢慢来，毕竟谁也不能一见面就把心掏出来不是？
具体到 HagiCode 的场景，我们从四个方面实施了渐进式披露：
1. 描述优化机制：让 AI 帮你把话说清楚

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

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

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

1. // ProposalDescriptionMemoryService.cs 中的核心方法
2. public async Task<string> OptimizeDescriptionAsync(
3.     string title,
4.     string description,
5.     string locale = "zh-CN",
6.     DescriptionOptimizationMemoryContext? memoryContext = null,
7.     CancellationToken cancellationToken = default)
8. {
9.     // 构建查询参数
10.     var queryContext = BuildQueryContext(title, description);
12.     // 检索历史上下文
13.     var memoryContext = await RetrieveHistoricalContextAsync(queryContext, cancellationToken);
15.     // 生成结构化提示词
16.     var prompt = await BuildOptimizationPromptAsync(
17.         title,
18.         description,
19.         memoryContext,
20.         cancellationToken);
22.     // 调用 AI 进行优化
23.     return await _aiService.CompleteAsync(prompt, cancellationToken);
24. }

复制代码

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

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

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

除了文本输入，我们还支持语音输入。这在描述复杂需求时特别有用——你想想，打一段技术需求可能要几分钟，但说可能几十秒就完事了，毕竟嘴总是比手快。
语音输入的设计重点是"状态管理"，用户必须清楚当前系统处于什么状态。我们定义了以下几种状态：

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

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

1. interface VoiceInputState {
2.   status: 'idle' | 'waiting-upstream' | 'recording' | 'processing' | 'error';
3.   duration: number;
4.   error?: string;
5.   deletedSet: Set<string>; // 已删除结果的指纹集合
6. }
8. // 开始录制时的状态转换
9. const handleVoiceInputStart = async () => {
10.   // 先进入等待状态，显示加载动画
11.   setState({ status: 'waiting-upstream' });
13.   // 等待后端就绪确认
14.   const isReady = await waitForBackendReady();
15.   if (!isReady) {
16.     setState({ status: 'error', error: '后端服务未就绪' });
17.     return;
18.   }
20.   // 开始录制
21.   setState({ status: 'recording', startTime: Date.now() });
22. };
24. // 处理识别结果
25. const handleRecognitionResult = (result: RecognitionResult) => {
26.   const fingerprint = normalizeFingerprint(result.text);
28.   // 检查是否已被删除
29.   if (state.deletedSet.has(fingerprint)) {
30.     return; // 跳过已删除的内容
31.   }
33.   // 合并结果到文本框
34.   appendResult(result);
35. };

复制代码

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

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

1. prompts/
2. ├── metadata/
3. │   ├── optimize-description.zh-CN.json
4. │   └── optimize-description.en-US.json
5. └── templates/
6.     ├── optimize-description.zh-CN.hbs
7.     └── optimize-description.en-US.hbs

复制代码

每个提示词由两部分组成：

• 元数据文件（.json）：定义提示词的场景、版本、参数等信息
  
• 模板文件（.hbs）：使用 Handlebars 语法的实际提示词内容
  

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

1. {
2.   "scenario": "optimize-description",
3.   "locale": "zh-CN",
4.   "version": "1.0.0",
5.   "syntax": "handlebars",
6.   "syntaxVersion": "1.0",
7.   "parameters": [
8.     {
9.       "name": "title",
10.       "type": "string",
11.       "required": true,
12.       "description": "提案标题"
13.     },
14.     {
15.       "name": "description",
16.       "type": "string",
17.       "required": true,
18.       "description": "原始描述"
19.     }
20.   ],
21.   "author": "HagiCode Team",
22.   "description": "优化用户输入的技术提案描述",
23.   "lastModified": "2026-04-05",
24.   "tags": ["optimization", "nlp"]
25. }

复制代码

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

1. 你是一个技术提案专家。
3. <task>
4. 根据以下信息生成结构化的技术提案描述。
5. </task>
7. <input>
8. <title>{{title}}</title>
9. <description>{{description}}</description>
10. {{#if memoryContext}}
11. <memory_context>
12. {{memoryContext}}
13. </memory_context>
14. {{/if}}
15. </input>
17. <output_format>
18. ## 背景
19. [描述问题背景和上下文，包括项目信息、仓库范围等]
21. ## 分析
22. [技术分析和思考过程，说明为什么需要这个改动]
24. ## 解决
25. [解决方案和实施步骤，列出关键代码位置]
27. ## 实践
28. [实际代码示例和注意事项]
29. </output_format>

复制代码

这种设计的好处是：

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

毕竟脑子里的东西不写下来，谁也不知道什么时候就忘了，与其到时候懊悔，不如一开始就做好记录罢了。
4. 渐进式向导：复杂任务拆成小步

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

1. interface WizardState {
2.   currentStep: number;           // 0-3，对应 4 个步骤
3.   steps: WizardStep[];
4.   canGoNext: boolean;
5.   canGoBack: boolean;
6.   isLoading: boolean;
7.   error: string | null;
8. }
10. interface WizardStep {
11.   id: number;
12.   title: string;
13.   description: string;
14.   completed: boolean;
15. }
17. // 步骤导航逻辑
18. const goToNextStep = () => {
19.   if (wizardState.currentStep < wizardState.steps.length - 1) {
20.     // 验证当前步骤的输入
21.     if (validateCurrentStep()) {
22.       wizardState.currentStep++;
23.       wizardState.steps[wizardState.currentStep - 1].completed = true;
24.     }
25.   }
26. };
28. const goToPreviousStep = () => {
29.   if (wizardState.currentStep > 0) {
30.     wizardState.currentStep--;
31.   }
32. };

复制代码

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

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

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

这套方案在 HagiCode 中的实际效果是：用户输入的平均长度从不到 20 字提升到了结构化的 200-300 字，AI 生成的提案质量显著提高，用户满意度也跟着上来了。
其实这也不奇怪，毕竟你给的信息越多，AI 理解得越准确，返回的结果自然就越好，这和人与人之间的交流也没什么两样。
如果你也在做 AI 相关的产品，希望这些经验能给你带来一些启发。记住：用户不是不想给信息，而是你还没问对问题。渐进式披露的核心，就是找到问问题的最佳时机和方式，只是这个时机和方式，需要一点耐心去摸索罢了。
参考资料

• HagiCode 项目地址：github.com/HagiCode-org/site
  
• HagiCode 官网：hagicode.com
  
• 渐进式披露设计原则：Wikipedia - Progressive Disclosure
  
• Handlebars 模板引擎：handlebarsjs.com
  

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

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

原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524
  
• 原文链接: https://docs.hagicode.com/go?platform=cnblogs&target=%2Fblog%2F2026-04-05-progressive-disclosure-hci%2F
  
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

感谢分享