AI 不聪明，只是用户给的信息太少了，毕竟猜心这种事，谁也做不好。

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

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

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

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

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

关于 HagiCode

本文分享的方案来

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

什么是渐进式披露

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

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

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

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

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

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

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

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

下面是实际的代码实现：

	// 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. 语音输入能力：说话比打字更自然

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

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

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

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

	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 语法的实际提示词内容

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

	{
	"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 语法，支持参数注入：

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

这种设计的好处是：

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

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

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

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

向导的状态模型：

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