提问增强器 Query Clarifier
1. 概述
本技能是一个不重新训练模型的运行时增强层，定位在模型作答之前。它把用户的
"原始提问"作为待处理对象，在真正回答前执行一条 6 步流水线，产出一道约束清晰、可验收、
自包含、直接可答的增强提问（sharpened query），再交给下游模型或 answer-selfcheck 使用。
解决的问题（对应四类典型缺陷）：
| 缺陷 | 流水线拦截点 |
|---|---|
| 需求模糊（"给点建议""写个好的"） | S2 缺口检测 → S4 重写 |
| 约束缺失（没说数量/格式/对象） | S2 缺口检测 → S3 补全 |
| 歧义阻塞（对象完全未知） | S2 歧义检测 → S3 追问 |
| 约束冲突（又要中文又要英文） | S2 冲突检测 → S3 消解 |
核心契约：
- 默认仅输出增强提问。Normal 模式下交付的只是"一道更清楚、可直接作答"的问题，
不得出现"经增强""根据拆解""第 N 步"等任何元语言。
- 与 answer-selfcheck 互补：本技能管"进"（把问题问清楚），answer-selfcheck 管"出"
（把答案改干净）。本技能产出的约束清单可直接作为 answer-selfcheck 的 system_rules 输入。
- 调试模式可回放。开启 debug 时输出结构化拆解（意图/要素/缺口/假设）+ 增强提问。
2. 何时使用
- 收到用户提问，但问题含糊、缺约束、或可作出多种解读，直接作答易跑偏。
- 作为"第一道质量关卡"，在模型生成草稿前先把需求钉死，降低后续返工与幻觉概率。
- 需要可审计（debug）能力来打磨约束模板与重写规则。
不可用于：用户已给出完全明确、结构化、无可补全空间的问题（此时可直接透传或仅做轻量规整）。
3. 入参表
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
raw_query |
string | 是 | 用户原始提问，保留其全部表述（含口语、模糊词）。 |
context |
object | 否 | 可选上下文：{domain, audience, background}，用于补全默认约束（如受众决定语气）。 |
system_rules |
array<string> | 否 | 系统规则约束列表。可带 [HARD]/[SOFT] 前缀；缺省默认 HARD。会并入增强提问的约束。 |
switches.ask_if_ambiguous |
bool | 否 | 遇阻塞性歧义是否反问。默认 true。false 时用合理默认补全。 |
switches.hide_internal_log |
bool | 否 | 是否对用户隐藏内部拆解痕迹。默认 true。 |
debug |
bool | 否 | 调试模式。默认 false。true 时输出结构化拆解 + 增强提问。 |
> ask_if_ambiguous 与 debug 的分工：ask_if_ambiguous 控制"阻塞时反问还是硬补"；
> debug 控制"是否额外导出拆解日志"。Normal 模式两者均不向用户泄露元语言。
4. 开关与模式
- Normal 模式：
debug=false且hide_internal_log=true→ 仅输出干净增强提问，不含任何元语言。 - Ask 模式：
ask_if_ambiguous=true且 S2 检出 blocker 级歧义 → 输出 ≤3 条针对性反问，
不产出最终增强提问（待用户补充后重跑）。 - Debug 模式：
debug=true→ 先输出结构化拆解（第 7 节结构），再输出增强提问。 - ask_if_ambiguous=false：跳过追问，所有缺失/歧义用合理默认补全（仍记录 assumptions）。
5. 完整执行流程（6 步流水线）
严格按顺序执行 S1→S2→S3→S4→S5→S6。S3 命中 blocker 且 ask_if_ambiguous=true 时
进入 Ask 分支（S6 只输出反问）；否则继续 S4→S5→S6。
S1 意图与要素解析
- 解析
raw_query（结合context），拆出四类：
- 核心意图（用户到底想达成什么）
- 显式需求（直接要求做的事）
- 隐式需求（合理隐含，如"给方案"隐含"可执行"）
- 约束维度：数量、范围、格式、对象、时间、排除项、语言、语气 - 为每条约束生成可验证判据（如何判定已满足）。
- 输出
checklist（每条：id + 约束 + 判据 + 当前状态占位）。
S2 缺口与歧义检测
- 逐维度判定状态：
present（已明确）/ambiguous（有表述但可多解）/missing（完全没提）。 - 分级：
- blocker（阻塞性）：缺它就无法作答或会大面积跑偏（如对象完全未知、意图不清）。
- fillable（可补全）：有合理默认可填（如语气默认中性、格式默认自然段落）。 - 检测约束冲突（同一维度出现互斥要求，如中文+英文、国内+海外）。
- 失败分支 B-contra（冲突）：记录冲突项，进入 S3 消解。
S3 追问 / 补全决策
- B-ask（阻塞性歧义）：若
ask_if_ambiguous=true且存在 blocker → 产出 ≤3 条
针对性反问（见references/pipeline.md追问模板），进入 S6 的 Ask 分支，不产出增强提问。 - B-fill（可补全缺失）：
missing/ambiguous且 fillable → 用合理默认补全，记录assumptions。 - B-contra（冲突消解）：默认取更稳妥/更常见的解释；若
ask_if_ambiguous=true且冲突影响大，
把取舍并入反问；否则在假设中标注"按 X 理解"。
S4 重写增强
- 将核心意图 + 全部约束（含 S3 补全的默认）+ 隐含需求，显式写进一句/一段自包含增强提问。
- 替换模糊词为可度量表述（"一些"→"3 条"、"合适"→明确标准）；消除指代词歧义；
不偷换用户原意，不为"看起来清楚"而加戏。 - 若
system_rules存在，将相关约束一并写进增强提问（作为可验收条件）。
S5 可答性校验
- 运行
scripts/check_vague.py做确定性校验：
- 禁语（模糊词）扫描；
- 可度量判据检查（是否含数字/量化词）；
- 自包含性检查（是否残留无指代的"上面/那个"）；
- 约束冲突初检。 - 失败分支 B-vague（残留模糊）：命中即回到 S4 重写，直至
clean=true或诚实标注残余。
S6 结果输出
- Normal：仅输出增强提问。若
hide_internal_log=true，剔除一切元语言。 - Ask：仅输出 ≤3 条反问，等待用户补充（不产出增强提问）。
- Debug：先输出结构化拆解（第 7 节），再输出增强提问。
- 失败分支 B6（不可解）：问题本身无法在不臆测前提下补全 → 输出"最小可答版本 + 需补充项"，
并在 debug 日志中说明受阻原因。
6. 失败分支速查
| 分支 | 触发 | 动作 | 是否阻断增强提问 |
|---|---|---|---|
| B-ask | blocker 歧义且 ask=true | 输出 ≤3 条反问 | 是（进 Ask 分支） |
| B-fill | 可补全缺失/歧义 | 用默认补全 + 记假设 | 否 |
| B-contra | 约束冲突 | 取稳妥解释 / 并入反问 | 视影响 |
| B-vague | 重写后仍模糊 | 回 S4 重写至 clean | 否 |
| B6 | 不可解 | 最小可答版 + 需补充项 | 否 |
7. 拆解日志结构（Debug）
debug=true 时，在增强提问之前输出如下结构的 JSON（或等价 Markdown 表格）：
{
"pipeline": "query-clarifier",
"mode": "debug",
"intent": "……（核心意图）",
"steps": [
{"step": 1, "name": "意图与要素解析", "pass": true, "checklist": ["..."]},
{"step": 2, "name": "缺口与歧义检测", "pass": true, "missing": [], "ambiguous": [], "blockers": [], "conflicts": []},
{"step": 3, "name": "追问/补全决策", "pass": true, "assumptions": ["..."], "questions": []},
{"step": 4, "name": "重写增强", "pass": true, "rewritten": "……"},
{"step": 5, "name": "可答性校验", "pass": false, "vague_hits": ["..."], "measurable_ok": false},
{"step": 6, "name": "结果输出", "pass": true, "mode": "normal"}
],
"sharpened_query": "……（干净增强提问）"
}
任一 pass=false 的步骤须在其字段中给出具体问题文本与所采取的修正动作。
8. 调用 JSON 示例
示例 A：Normal 模式（模糊 → 清晰）
{
"raw_query": "帮我写点 Python 学习建议，给新手看的。",
"context": {"audience": "编程新手"},
"system_rules": ["[HARD] 必须使用中文", "[SOFT] 建议应具体可执行"],
"switches": { "ask_if_ambiguous": true, "hide_internal_log": true },
"debug": false
}
预期：S2 命中"数量缺失/模糊词'点'/'建议'不具体" → S3 用默认补全（如 3 条、具体可执行）；
S4 重写为"请用中文给 3 条适合编程新手、每条可立即执行的具体 Python 学习建议"；
S5 校验通过；仅输出该增强提问。
示例 B：Ask 模式（阻塞性歧义 → 反问）
{
"raw_query": "帮我分析一下那个项目靠不靠谱。",
"switches": { "ask_if_ambiguous": true, "hide_internal_log": true },
"debug": false
}
预期：S2 命中 blocker（"那个项目"无指代、分析维度未知）→ S3 B-ask 输出 ≤3 条反问，
如"①你指的是哪个项目（名称/链接）？②你关心'靠不靠谱'的哪些维度（技术/商业/团队）？"；
不产出增强提问。
示例 C：Debug 模式（导出拆解）
{
"raw_query": "写个好点的产品介绍，中文，别太长。",
"switches": { "ask_if_ambiguous": true, "hide_internal_log": true },
"debug": true
}
预期：S2 命中"好点（模糊）""别太长（缺量化）"；S3 补全默认（如"突出 3 个核心卖点、
≤150 字"）；S4 重写；S5 校验；输出拆解日志 + 增强提问。
9. 文件导航
references/pipeline.md：约束维度清单、缺口/歧义分级细则、追问模板、重写规则（模糊词替换表）、
约束冲突处理、以及check_vague.py的调用方式。references/templates.md：各步内部提示词模板，供执行时套用。scripts/check_vague.py：S5 的确定性模糊词/可度量/自包含/冲突校验脚本。
10. 执行纪律（硬性）
- 任何情况下，Normal 模式可见增强提问中不得出现"增强""拆解""流水线""步骤 N""debug"等元语言。
- 补全默认时显式记录假设，绝不假装用户说过没说的话；Ask 模式须如实指出"缺什么"而非臆测。
- 重写必须忠于用户原意，不为通过校验而偷换问题、擅自加范围或加戏。
- 增强提问应自包含，避免"上面/那个/它"等无指代表述，确保下游模型无需回看原文即可作答。
