domain-expert-configuration

领域专家配置

领域专家配置 UI 会向用户展示复杂系统的参数，例如优化算法、规划引擎或模拟器，而这些用户虽然对问题领域有深入了解，却不了解系统的内部机制。

挑战在于：系统参数以技术术语定义（权重、阈值、标志、容差），而用户思考时使用的是领域术语（等待多久、何时重试、如何分组结果）。UI 必须在这两种词汇之间进行转换，并始终优先使用用户的语言。

---

核心原则：领域语言优先于技术语言

每个参数标签、工具提示和错误消息，都应描述参数在用户的世界中意味着什么，而不是它在系统内部的作用。

技术标签	领域标签
max_concurrent_jobs	同时运行的任务数上限
enable_auto_retry	自动重试失败的任务
batch_allocation_threshold	填充到（%）后开始新批次
request_timeout_ms	每次请求的最长等待时间（秒）
enable_fuzzy_matching	允许近似匹配

如果无法为某个参数编写领域标签，就要考虑是否应该向用户展示该参数。无法用领域术语解释的参数应放在开发者配置文件中，而非面向用户的 UI 中。

---

按领域概念分组

参数应根据其控制的现实问题方面进行分组，而不是按技术类别（例如将布尔值放在一起、数值放在一起），也不要按字母顺序排列。

处理工具可以按以下方式分组：

Processing limits
  └─ Maximum tasks at once
  └─ Maximum wait per request
  └─ Memory ceiling

Matching rules
  └─ Allow approximate matches
  └─ Case sensitivity
  └─ Required fields

Batching behaviour
  └─ Batch fill threshold
  └─ Maximum batches

每个分组都应有一个简短标题，描述它控制任务的哪个方面，而不是参数的类型。

---

合理的默认值

每个参数都必须有一个适用于大多数情况的默认值。用户应能使用所有默认值开始操作，并获得合理的结果。

显示默认值： 字段处于默认值时，应明确标示。用户将值改为非默认值后，应能轻松重置。

Maximum wait per request  [___30___ s]  ← custom value
                          [↺ Reset to default (15 s)]

Batch fill threshold  [_70_ %]  (default)  ← at default

为什么这很重要： 领域专家往往不知道不熟悉的参数该填什么值。如果字段为空且没有提示，他们要么跳过它（使系统处于未知状态），要么随意输入一个值。显示默认值能传达“除非你另有设置，否则系统会采用此值”。

---

根据领域语义选择输入类型

应根据参数意味着什么来选择输入类型，而不只是看它的数据类型。

参数性质	输入类型	示例
二元规则（开／关）	切换开关	“自动重试：[开关]”
有明确单位的受限数值	带单位标签的数字输入框	“最长等待时间：[___] 秒”
从命名选项中选择	下拉选择或单选组	“输出格式：[JSON ▾]”
百分比或比率	带数字输入框的滑块	“批次填充阈值：[━●━━] 70%”
自由文本标识符	文本输入框	“任务引用：[___]”

数值输入必须标明单位。 切勿显示不带单位的数字。单位标签应紧邻输入框（优先放在后缀位置：[___] cm，而不是 cm [___]）。

渐进式披露

并非所有参数都同样重要。应分层展示：

主要设置（始终可见）： 控制最常调整行为的参数。领域专家只调整这些参数，就应该能完成 80% 的任务。

高级设置（默认折叠）： 用于边缘情况、微调或较少见场景的参数。放在披露控件（“高级选项 ▾”）后面。需要这些参数的用户可以展开，不需要的用户则不会看到。

开发者／系统参数： 完全不在面向用户的 UI 中显示。将其放在配置文件或环境变量中。

不要把所有内容都塞进高级设置中。经常需要用到的参数应放在主要设置中。

---

已保存配置与会话配置

许多操作工具会区分：

• 已保存配置： 用户持久保存的偏好（常规处理设置、常用规则）。自动加载。
• 会话覆盖项： 针对特定运行的一次性调整，不应更改已保存的默认值。

在 UI 中明确体现这一区别。如果用户为某次运行调整参数，就不应该担心会破坏已保存的默认值。

┌─ Configuration ────────────────────────────┐
│  Maximum wait    [30 s]   ← session only    │
│  Retry on fail   [✓]      ← saved           │
│                                             │
│  [Save as default]   [Reset to saved]       │
└─────────────────────────────────────────────┘

---

验证与约束反馈

当值无效或与其他设置冲突时，应使用领域术语告知用户。

技术错误	领域错误
value out of range [0, 9999]	“等待时间必须介于 0 到 999 秒之间”
constraint conflict: retry=true, fail_fast=true	“不能同时启用自动重试和首次失败即停止”
threshold must be < 1.0	“批次填充阈值必须小于 100%”

在受影响的字段旁内联显示验证信息。不要等到用户提交后才报告冲突。

对于相互影响的设置，应说明其关系：“关闭自动重试后，最大尝试次数设置将不起作用。”这样可避免专家浪费时间调整未生效的参数。

---

模型提出的配置

模型将自由文本转换为配置时，应以相同的表单控件展示其解读结果，绝不要用散文形式呈现。

• 标记模型推断而非读取的每个值。用户更正字段后，该字段上的标记应清除。
• 编辑任意控件都会重新运行提议，让用户看到更正所带来的影响。
• 选择、排序和计数由代码完成。模型只负责措辞。模型整理的列表有时会丢弃、合并或错数条目。
• 在帮助文本中说明这项分工。

用散文呈现会迫使用户重新提示词来修改一个数字。标记字段只需一个操作即可修改。

---

审核清单

• 每个参数标签是否都使用领域语言，而非技术语言？
• 参数是否按其控制的领域概念分组，而非按类型或字母顺序分组？
• 每个参数是否都有可见的默认值？
• 是否有针对单个参数的“重置为默认值”操作？
• 所有数字输入是否都在字段旁显示单位？
• 输入类型是否符合领域语义（二元选项用开关，命名选项用选择框）？
• 高级参数是否默认隐藏在披露控件后面？
• 是否明确区分已保存配置与会话覆盖项？
• 验证信息是否以内联方式使用领域语言显示？
• 是否在 UI 中说明参数间的相互影响（冲突、依赖关系）？
• 模型推断的值是否显示为带标记且可编辑的字段，并由代码完成选择和计数？