夜雨聆风这份手册从 Harness Engineering 理论出发，整理了 Web 平台和 IDE 插件两种形态下的 UX 设计要点。
2026-04-14 ｜ 产品设计参考
一、核心设计哲学
1.1 基本原则
"好的 Harness 不消除人类介入，而是把介入引导到最关键的地方。"
— Birgitta Böckeler, Thoughtworks
1.2 五个设计维度
- 透明度
— 用户看得懂 AI 在干什么、为什么这么干 - 可控性
— 用户随时能插手，也能随时叫停 - 渐进披露
— 信息分层，需要的时候才展开 - 精准反馈
— 成功别吵，失败说清楚 - 边界清晰
— 能做什么、不能做什么，交代明白
二、通用设计要点
2.1 人在哪里介入
把介入分成四类，每一类对应不同的交互方式。
两个硬性约束：最多重试 2 轮（防止死循环）；失败时必须给替代方案，不能只报错。
2.2 反馈怎么做
好的反馈 = 快 + 成功别吵 + 失败说清楚
失败信息可以这样写：
问题：[一句话说清楚出了什么事]位置：[文件名:行号]建议：[怎么修]参考：[相关文档]操作：[自动修] [手动修] [看详情] [忽略]
2.3 上下文管理
用户应该能控制 AI "知道什么"。
AGENTS.md 的写法 — 系统提示是目录，不是百科全书：
核心原则写在提示里，控制在 200 行以内 详细内容放 docs/ 目录，用到再引用 上下文是稀缺资源，别往里塞东西
2.4 混合编排可视化
把确定性步骤和 AI 决策步骤区分开，用户才不会困惑。
确定性节点（自动跑）→ 等就行Agent 节点（AI 判断）→ 显示进度，可中断确认节点（人来做）→ 给出选项失败节点（交给人）→ 说原因 + 给出路
三、Web 平台
3.1 任务状态
3.2 会话持久化
刷新页面不丢状态 能回看历史任务、恢复中断的任务 多个任务并行时，上下文互不干扰
3.3 收集反馈
四、IDE 插件
4.1 别打扰开发者
一句话：随时能用，但别打扰。
4.2 上下文自动感知
给一个上下文状态指示器，让用户知道 AI 当前"看到了什么"。
4.3 行内反馈
代码问题用波浪线标出来（跟语法错误一个道理） 点开能看到建议修改的 Diff 可以应用、改了再应用、拒绝、或者以后都忽略 架构问题带上修复指引和文档链接
4.4 Diff 预览
对比视图看所有改动 全应用 / 逐个确认 / 全拒绝 / 改了再应用 逐个确认时，每个改动独立处理
4.5 渐进披露
Level 1：只显示 "3 个建议已就绪 [展开]"Level 2：展开后，每条建议一句话Level 3：再点，看到原因、风险、Diff、操作按钮
五、检查清单
5.1 通用
用户看得懂 AI 在干什么 用户理解 AI 的判断依据 能查看推理过程（可选） 随时能暂停 / 取消 关键决策有人确认 AI 建议可以挑着用 能快速给反馈 失败信息带修复建议 反馈能回流改进系统 能力边界说清楚 失败时给替代方案 最多重试 2 轮 上下文可查看、可管理 核心和可选上下文分开 上下文用量可视化
5.2 Web 额外
阶段进度清晰 区分自动 / Agent / 需确认节点 长任务有预估 刷新不丢状态 历史任务可回看 任务可恢复 并行任务互不干扰
5.3 IDE 额外
不挡代码 不强制打断 建议可以延后处理 自动识别文件和项目 自动加载项目规则 上下文状态可见 行内代码建议 行内问题提示 Diff 预览 + 选择性应用 快捷键 命令面板 右键菜单
六、优先级
七、理论来源
八、速查
Agent = Model + Harness
好的反馈 = 快 + 成功别吵 + 失败说清楚
介入点 = 必须确认 | 建议确认 | 可选介入 | 失败交回
渐进披露 = 最小 → 摘要 → 详情
混合编排 = 确定性 + Agent 循环 + 人工确认
