提示词优化器WestFox-AwA/dsh-prompt-optimizer

dsh-prompt-optimizer v0.5.0-beta.1 · 提示词优化器（DSH Web 插件）

本版由 SPEC.md（架构基线 v0.5）定义：优化器不是“提示词作家”，而是依据搬运工 + 缺口补齐器——把〔你的原话〕〔会话上下文〕〔项目文件〕里与这次请求相关的依据，补成一条下游一次做对的命令。

⚠️ 请务必注意：默认按 PTC 执行体给命令

下游执行体（在「优化模型」弹层里）默认 PTC——本插件就是为 PTC 优化的：命令按“一个程序一次做完”投影（清单优先、够用即止、不写工序与暂停点）；也可手动切「对话式」（阶段/步骤、篇幅不设限）或「自动」（看会话的 agent preset）。无论哪种，依据与深度一条不减。

0.5 是什么（一页看懂）

下游模型（v4.1-flash 这类）不主动、不猜、一次做完：你没写、它又推不出来的，就是必然缺失；你写了，它一定会照做。所以本插件只做一件事——补齐它无法自知的缺口，一句多余的都不写。
只补五类：① 指代与定位（“这个 bug”到底是哪个：文件/界面/症状）② 验收判据（什么算做完）③ 约束与边界（不能动什么、项目里实际存在的约定）④ 隐含决定（你没定的选项：有据按惯例，无据标「自由度」）⑤ 入口与锚点（从哪开始、做完看哪里、什么算过）。
每一条都带依据：事实只能来自这次实际读到的上下文或文件（只列过目录 ≠ 知道内容）；“这个 bug”这类指代，靠会话上下文落到具体对象——上下文读多少只由「回合／全文」决定，超预算时只压缩呈现、不改范围，并永远写明压缩了什么。
不写什么：下游的本行（通用写法、常规 API、最佳实践、教学）与没有具体指向的验证套话（“请充分验证”）——对这类模型，提示词不是建议而是指令集，多写一条就多一条硬约束。
四档＝依据预算：普通＝只用你的原话＋上下文（补①定位②判据）；高级＝按需读项目文件（五类全补）；极端＝深读交叉核对（五类全补 + 每条改动带出处 + 允许正向丰富）。三档都不写流程仪式（阶段闸门 / 打勾 / 贴证据）。

🌐 Read this in English →

跳到英文文档（英文文档顶部同样有回到中文的按钮）

中文 ｜ English

界面语言跟随 DSH：DSH 设成中文则全中文，设成英文则全英文（不再只支持中文）。当前版本适用于 dsh-0.1.6-alpha.1（0.1.5-rc.1 亦可运行）。

⚠️ 请先读这五点（作者郑重声明）

1. 本插件目的是优化提示词，节省因为书写提示词而消耗的时间，并帮助用户更准确地传达意思；本质上是让 AI 可以多一步自我规划、约束。
2. 本插件在 DeepSeek-V4.1-Flash 这种能力较强、但发挥受提示词影响严重的大模型上有明显作用。
3. 本人仅使用此插件测试过部分 OneShot 类型的任务。本 README 第七节给出的实测数字，都是特定测试题 + 特定评分卡上的结果，不代表你的任务也一定提升；建议对此插件的实际作用持保守意见。
4. 本插件完全开源，支持任何人、任何形式使用并修改此插件，也欢迎提出建议，以及各种测试。
5. 语言与兼容性：界面已支持中文与英文（跟随 DSH「设置 → 通用 → 语言」，zh / en 即时切换）；当前此插件版本（v0.4.3-beta.1）适用于 dsh-0.1.6-alpha.1。升级 DSH 前请先看 DSH-COMPAT.md；该文档记录了接口核对、升级步骤与升级后的逐项验收结果。

🆕 更新介绍（What's new）

v0.5.0-beta.1 —— 本版：架构基线 v0.5（依据搬运 + 缺口补齐）

- 为什么改：前几轮加的全是“优化器自己该怎么表现”的规则（档位轴、形态投影、身份层、i18n、字数基线），验证也全是自证的（投影不变、条款在位、字数对得上）——没有一条在回答“下游一次能不能做对”。而真实失败是“一半概率连正常目标都做不到、坦克有渲染问题”，那是能力 + 一次性执行的问题。对这类模型，提示词不是建议，是指令集。
- 契约层重写（先砍）：V6_CORE 改为【前提／依据／只补这五类／范围／歧义／不要写／语言】。删掉“输出结构：目标 → 现状事实 → 步骤”这类形式模板、验收（≤3 条，可机器判定）与全部没有具体指向的验证套话。
- 档位 ＝ 依据预算：普通＝只用原话＋上下文（补①②）；高级＝按需读项目文件（五类全补）；极端＝深读交叉核对（五类全补 ＋ 每条改动带出处 ＋ 正向丰富）。模型、思考强度、上下文开关与档位解耦。
- 上下文（W1b）：只读你指定的那个会话；范围只由「回合／全文」决定（回合＝你一次 ＋ AI 一次，0 = 不读；全文＝与工作 AI 看到的一致的那份投影）；超预算只压缩呈现、不改范围并写明压缩了什么；解析不到会话完全不注入（删掉“回落到列表第一个会话”的隐式路径）；注入块始终声明旁观者身份。
- 依据索引：工具结果按依据类型分开——读到内容的文件、grep 命中（路径:行号）、只列过目录的文件（只能陈述“存在”，不得描述里面写了什么）。
- 一次交付可用率（唯一目标指标）：产出后迷你窗里的「成了 / 要返工」——记的是人给的裁决，不推断、不自评。
- 可证伪验证：上下文范围桩单测 13/13；audit-provenance.cjs（出处审计：产物引用的路径必须在依据索引里）；compare-referent.cjs（同题对照）；基线重冻必须带 --reason。
- 实测：真实场景 A/B/C 9/9；同题对照「修复这个 bug」有上下文 468 字 / 无上下文 578 字（两边都先声明“未找到指代来源”，再给一个最小发现动作），而改前同一题是 2201 / 1009 字的通用流程填充；真实任务出处审计：2344 字 / 22 条目 / 无出处的事实 0 处。

v0.4.6-beta.6 —— 本版：根治「假事实」（身份层 + 证据层 + 契约层）
- 病灶（真实项目实测）：只读工具读到了别的会话的目录（C:\Users\WestFox\.dsh，不是这次运行所属的会话），产出却把这处的所见写成「已核实的事实」（"工作目录下不存在任何工程文件…只有 attachments/v1/objects/ 二进制对象"），下游据此不再看真实项目；同一句原话三次还跑出互相冲突的硬约束*（一次"唯一允许的外部资源是 CDN three.js"、一次"不得出现 https://"＝要求从零手写 WebGL 渲染器，用户从没要求）。
- 身份层：会话 / 工作目录 / 下游形态只解析一次（按本次运行上报的 sessionId）；解析不到就不猜——不派工具、不注入观察者、形态回落对话式，退化成"纯需求重述"（0.4.3 行为），绝不产出假事实。判定可在 /runs 的 context / toolRoot 核对。
- 证据层：只有本次实际读到的路径与符号才允许写成"事实"（查证账本随工具结果一并注入）；只列过目录不等于知道内容；一次文件内容都没读到就不写"事实 / 现状"段。
- 契约层：新增【事实必须有出处】【只写下游无法自知的】，并把【歧义】改为「保守不得升级成新的硬约束」（用户没提 ≠ 禁止）。提示词变更可逐行审计（evidence/diff-v6-prompts.cjs），本轮差异只有这三条 + 歧义扩写。
- 止血杠杆：策略可运行时拨动（状态文件 strategy 或 DSH_PO_STRATEGY）；strategy=v5 即回到 0.4.3 的"纯需求重述"，便于同题对照与快速回退，不必改代码。
- 实测（你的原话 + 你的会话目录）：工具根 = 该会话目录 ✓（不再是 .dsh）；产出里假事实、"已核实"、事实段全部消失 ✓；不再禁止 https ✓；不给 sessionId 时 readTools=false、形态回落对话式、观察者写明原因 ✓；同题 v5 = 1428 字纯需求重述（对照）✓。

v0.4.6-beta.5 —— 本版：思考强度真正生效（含守卫与可证伪验证）

- 接线：正式优化路径此前从不发送 reasoningEffort（只有内部自检路径 streamOnce 会发），所以弹层里的档位一直是装饰品，/runs.effort 记的也只是配置值。现在真发，并新增 effortSent（实发值） 与 effortNote（未发原因）供核对。
- 守卫：只在该模型确实声明了该档位时才发——换过模型后残留的档位不会再让正式优化直接失败。七个分支有确定性单测（含本机跑不到的"模型声明了档位但缺 max"）。
- 实测（同一请求、各 4 次；evidence/effort-live.json）：off 组思考文本 0 / 0 / 0 / 0 字，max 组 3260 / 1974 / 2193 / 2274 字（中位 2234），两组 effortSent 分别是 "off" / "max" —— 类别级差异，证明该字段确实抵达了模型。
- 更正一条旧结论：v0.4.5 写的"off 均值 8745 / max 8300，行为层面的强度差异尚未被证实"——那三组当时实际发出去的东西完全一样，差异纯属噪声；README 对应历史条目已加更正注。
- 弹层提示补一句"该模型未声明所选档位时不会发送"。其余一切未动：delivery=chat 三档 system 仍逐字节不变（15/15），投影不变式与 i18n parity 回归全过。

v0.4.6-beta.4 —— 本版：下游形态投影（同一份档位定义，两种消费形态）

- 本质：PTC 惩罚的是工序，不是深度。原先"很细"与"分步骤"被写在同一个字段里，于是"更适配 PTC"看起来像"要削掉极端档"。拆开这两件事，就不必削。
- 改法：档位拆成五轴（grounding / depth / enrich + sequence / budget）；delivery=ptc 只投影后两轴——清单代替工序、够用即止代替不设限，depth / enrich / grounding 一字不动。
- 判定：读会话的 agent preset（自带预设 ptc）自动切换，也可在「优化模型」弹层手动指定（自动 / 对话式 / PTC）；只读诊断路由 /delivery 会回报"判成了什么、依据是什么"。
- 零回归：delivery=chat 时三档 system 与改前逐字节相同（3 档 × 5 组输入 = 15/15，evidence/snapshot-v6-prompts.cjs --compare）。
- 实测（同批 10 题、同档极端、无工具、两次独立采样）：稳健的——流程开销 0.4 / 0.2 → 0.1 / 0、逐步 0.4 / 0 → 0 / 0.2、验收判据 0.5 / 0.7 → 4.5 / 5.7（该指标噪声 sd 仅 0.75，差距 6–8 倍）、同批配对 8/10 题变好（均值 +5.8）。不稳健的——综合分与字数：该量尺跨批噪声大于效应（条目数 sd 9.85、综合分 ±3.2），ptc 9.9 / 6.12 与 chat 3.6 / 6.93 区间重叠，不作为结论。
- 档位次序仍在（投影没有把档位抹平）：ptc 形态内 条目数 极端 31.6 > 高级 22.3 > 普通 18.3。
- 顺带修一个真缺陷：产出预算改成"单一来源 + 停顿看门狗"（45s 无增量才收手；硬上限 240s）。原先按总时长 60s 一刀切，把还在稳定产出的请求砍成半截命令——改后累计 42 次运行 0 中断，其中一题跑到 10929 字 / 127 秒正常完成。
- 诚实边界：这个量尺的跨批噪声大于效应（同一份提示词两批之间条目数 sd = 9.85），所以结论一律取自"同批配对"或"逐字节相同"这类结构事实，不跨批比较。

v0.4.6-beta.3 —— 本版：修「高级/极端看不到思考过程」+ 问号面板文案对齐 + README 口径同步
- 修复（思考透传）：工具循环调用时漏传 onDelta、只回传思考字数计数、且工具分支把 reasoning 硬编码为空串——三处断点让高级/极端档的「思考」栏永远是空的（基础档不走工具循环所以一直正常）。现已把思考接回与不派工具时同一条透传通道；三档定义未动（grounding / decompose / enrich 与温度一字未改）。实测：思考字数 基础 3333、高级 0 → 2817、极端 0 → 7396；浏览器内实跑极端档，「思考」栏摘要 = — tok · 6497 字。
- 问号面板文案与行为对齐：原先那一节写的是 v0.2.1 / v5 时代的规则（"实质优先 / 流程长度 / 硬约束 / 防过度"），与 v6 的"不写流程仪式与通用教学"正好相反。现按三档定义重写：档位（并注明三档的思考过程都显示在「思考」栏）、只读权限（默认开启）、优化器会做什么（收件人 / 语言层 / 保真 / 歧义 / 产出即命令）、上下文（回合＝最近 0~10 回合双方全文、超限六级压缩并声明）。中英面板各 7 节 / 各 24 行，i18n-demo 自检中英各跑一次 pass: true。
- README 口径与实测同步：修掉 6 处过时描述（中英同改）——"不写步骤/不写验收清单"（与高级/极端档相反）、"系统提示词 515 字符 / 产出 422 字符"（实测 高级 2542 / 极端 2687 字符）、"组装是 RELAY_IDENTITY → … → PROCESS_RULES"（v4/v5 遗留）、"只发送输入文本 + 目录树摘要"（该机制在活路径从未注入）。
- 版本号：文档标题、安装示例的 tgz 文件名、面板落款三处已同步为 0.4.6-beta.3；releases/latest 别名链接始终指向最新版。

v0.4.6-beta.2 —— 本版：只读权限默认开 / 文案与位置 / 产出物收件人（治根）

- 只读权限默认开：状态文件里缺失该键 = 开，只有显式 false 才算关（已保存的显式值不被改写）。实测：删掉键后 /state → true；不传参数跑极端档 = 6 次真实工具调用；显式关 = 0 次调用且产出 4000 字。
- 文案与位置：标签改为「只读权限：」（en：Read-only access:），开关移到标签同一行的右侧，说明保留在下一行。真实 DOM 实测：sameLine=true / dy=0 / btnRightOfLabel=true / overflowRight=-25（不出界、不截断）。
- 产出物收件人（治根）：此前契约只规定"内容要像一条能发出去的命令"，从未规定产出物的收件人，于是模型会写出对老板说的话（"把下面这段整条发给工作 AI…"），直接转发会误导会话 AI。现在两层根治：契约层把收件人写进 system（全策略生效）；闸门层在唯一产出出口强制剥离首尾转交语与包装（正文里的"复制到/告诉我"不误伤；剥完不足 20 字整段回退，绝不返回空），done.text 成为定稿。
- 实测：用出问题的那句原话复现，产出 no-hit（转交语根本没生成）；闸门判官自检 13/13（坏标全拦、金标一字未动）；工具链强制失败时回落无工具路径、产出 3816 字非空。
- 硬约束：只读权限默认开启（覆盖上一版的"默认关闭"）；任何失败都降级且不会给你空结果。降级声明落在运行记录（/runs），不写进产出物——否则又变成对老板说话。

v0.4.6-beta.1 —— 本版：只读查证 / 观察者上下文 / 预算与压缩（三步改造）

- 只读查证：弹层开关（高级/极端档生效）打开后，优化 AI 会真的读项目再写要求。修复了一个接线缺陷——把消息数组当字符串传进工具循环，导致 provider 报 messages[0].content: invalid type: sequence。实测 ON = 10 次真实工具调用且产出含真实目录结构；读了没找到时如实说明，不编造。
- 观察者上下文：优化 AI 现在能像旁观者一样看这段会话——数据走会话投影（会话 AI 真正看到的消息），不是事件重放；turns = 最近 10 回合双方全文，full = 整个投影，off = 关闭。注入方式是结构参数进 system，不污染你的原话。
- 预算与压缩：上下文超预算时分级压缩并在注入文本里写明压缩了什么（例："仅保留最近 4 个回合、助手截断 600 字"），绝不静默丢内容。实测 24672 → 2860 字符、35232 → 2855 字符，压缩后仍能引用真实历史。
- 硬约束：只读开关默认关闭；任何异常都降级（工具路径失败回落到正常优化、观察者取不到就不注入），不会给你空结果。

v0.4.5-beta.2 —— 本版：思考强度文字溢出修复

- 修复（UI）：弹层里的「优化 AI 思考强度」一行原先复用 .dpo-pop-foot（无 flex-wrap）+ .dpo-btn（flex:1），五个档位把文字挤出弹层。现改用专用样式 .dpo-effort-row / .dpo-effort-btn：可换行 + 省略号 + max-width:100%，档位标签只留档位名（"（模型默认档）"移入悬停提示），并在上方单独一行给出"不选则用模型默认：x"。
- 结构验证：text-overflow:ellipsis 命中 8 处、max-width:100% 命中、dpo-effort-btn 标记已替换、旧的 dpo-pop-foot+effort-row 写法残留 0。
- 功能重新验证：每档真跑 2 次，/runs 记录的 effort 与设置逐次一致（off/off、max/max、未设置为空）⇒ 修复未影响设置链路。
- 行为层（思考字数）仍受噪声主导（off 均值 8745 / max 8300 / 未设置 2788），仍不下结论；该 provider 不上报 reasoning tokens。

v0.4.5-beta.1 —— 本版：优化 AI 思考强度可选（适配所有模型）

- 新增：优化模型弹层里多了一个「优化 AI 思考强度」选择行，档位来自模型自己声明的能力（llm.resolveModelInfo → reasoning.efforts / defaultEffort），不硬编码；模型没声明档位时显示"保持模型默认"。
- 取值语义：模型默认 = 不显式设置（交给适配器默认，实测 deepseek-flash 为 high）；其余为显式档位。换到不支持所选档位的模型时自动回落为“模型默认”，避免下一次调用被拒。
- 落到调用的方式：llm.stream({ provider, model, reasoningEffort, ... })；未选时不传该字段（保持历史行为不变）。每次运行的 /runs 记录新增 effort 字段，用于核对“设置是否真的生效”。
- 验证（evidence/verify-effort.cjs）：9 次真实调用中，/runs 记录的 effort 与设置值逐次一致（off/off/off、max/max/max、未设置为空）；适配器层 resolveCallConfig 对 off/low/high/max 原样保留、对非法值明确报错 ⇒ 设置确实进入模型调用。
- 如实说明：该 provider 不上报 reasoning tokens，且单次“思考字数”噪声很大（同档位内 1956–10377 波动），因此行为层面的强度差异尚未被证实；要测量需更多次数或换用上报 reasoning tokens 的 provider。

更正（2026/09/18 · 0.4.6-beta.5）：上面“落到调用的方式”与“设置确实进入模型调用”两条当时并未成立——正式优化路径（streamWithTools）从不发送该字段，只有内部自检路径 streamOnce 会发；/runs 记录的 effort 也只是配置值，不是实发值。
因此紧随其后的那条观测（off 均值 8745 / max 8300 / 未设置 2788）对比的其实是三组发出去完全一样的样本，差异纯属噪声——“行为层面的强度差异尚未被证实”这个结论的前提不成立。
0.4.6-beta.5 已真正接上（/runs 新增 effortSent 实发值 / effortNote 未发原因），并以同题 off vs max 对照证实：off 组 4 次全部 0 字，max 组中位 2234 字；“模型未声明该档位时不发”的守卫也改为服务端强制（单测 7/7）。

v0.4.4-beta.1 —— 本版：修两个已上报缺陷（issue #9 / #8），策略未变

- #9 控件自愈每 1.2 秒抛 pageerror：slot 注册按 id 去重，自愈却用同一个 id 再注册 → 抛 already has an entry with id "prompt-optimizer"（改 order 绕不开）。
修复：重挂前先释放上一次的重挂（保存并调用 ctx.slots.inject(...) 的 disposer，定时器清理时一并释放）；shell.overlay 自愈同构、一并修；重挂失败改为记 beacon。
- #8 本会话拦截次数显示为真值两倍：同一次发送走两条路径（keydown-enter + 随之触发的 click-send），每次记两行。
修复：互补路径标 coalesced（遥测行保留），新增 interceptCount() 供显示使用；自检与遥测仍用原始行数。
- 发布流程：新增 gh-api publish 一键发布（版本化资产 + 版本无关别名资产 + 标记 latest + 回读校验）；新增 fix-tags.cjs 保证 tag 内的 package.json 版本与 tag 名一致（此前 v0.4.1~v0.4.3 均不一致，已全部纠偏并复核）。

v0.4.3-beta.1 —— 本版：需求补全器（0.4 系列）

- 策略换代：从“改写器”（0.1）改为“需求补全器”（0.4）——把用户一句 10–200 字的请求，补成一份完整具体的要求说明（对象、结果、使用情形、边界、范围）。
- 不写流程：不写步骤、不写验收清单、不写验证纪律、不写禁令——这些是下游 AI 自己的能力；写进去只会占它的注意力预算、收束它的解法空间。
- 体量：系统提示词按档位组装，实测（含观察者上下文块 1654 字符）高级 2542 / 极端 2687 字符（0.4.3 时代为 515）；同一句请求的产出 普通 306 / 高级 2008 / 极端 3954 字符，流程仪式类管理文字全 0。
- 推导与实测见 evidence/ARCHITECTURE-v5.md；更早版本的逐项变更见 CHANGELOG.md。

作者：啃轮胎的西狐 · 版本 0.4.6-beta.6 · 版本日期 2026/09/18（插件内 ? 面板最底部也有同样署名）

📦 下载：本仓库的 Releases 提供可安装的 .tgz 包（npm pack 产物，安装方式见下一节）。

一、安装

方式 A：像安装其它 DSH 插件一样（推荐）

两步：先把包装进 profile，再把包名登记为 bundle 层。

1) 装包（GitHub 仓库 / tarball / 本地目录都行）
推荐用 releases/latest 链接：它永远指向当前最新版（旧的预发布版不会顶掉它）
dsh plugin --profile web add https://github.com/WestFox-AwA/dsh-prompt-optimizer/releases/latest/download/dsh-external-dsh-prompt-optimizer.tgz
或指定版本（把  换成 v0.4.3 之类）
dsh plugin --profile web add github:WestFox-AwA/dsh-prompt-optimizer#
dsh plugin --profile web add ./dsh-external-dsh-prompt-optimizer-0.4.6-beta.6.tgz

2) 在 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 里加一行：
"@dsh-external/dsh-prompt-optimizer"

下载页： —— 这一页永远是当前最新版；
要旧版请到 releases 列表里按 tag 找。

重启 DSH 即生效。为什么还要改 bundles：dsh plugin 只是把参数转发给 pnpm（只负责安装），而"哪些包作为 bundle 层参与装配"由 profile 的 dsh.profile.bundles 决定。本插件自带 cordis.patch.yml，会在装配时把自己的 entry 插进根条目表 —— 与 @dsh-external/dsh-super-injector、@dsh-external/dsh-graded-mode 完全同一写法。

方式 B：不动 bundles，用 profile patch 插入

不想改 dsh.profile.bundles 时，也可以直接在 profile 的补丁层插一条 entry：

~/.dsh/profiles/web/cordis.patch.yml （顶层 YAML 数组）
- insert:
- id: prompt-optimizer
name: '@dsh-external/dsh-prompt-optimizer'
config: {}

包本身仍需可解析（dsh plugin add 装好，或手工放好 node_modules 软链/junction）。

⚠️ 方式 A 与方式 B 只能选一种：两种都做会让同一条 entry 插入两次，启动时报 duplicate loader entry id。

验证安装

dsh --dump-config --profile web | grep -A2 'id: prompt-optimizer'   # 装配树里有它，且只有一条
node -e "console.log(require.resolve('@dsh-external/dsh-prompt-optimizer',{paths:['']}))"

运行要求

- DSH Web（dsh web；本插件只在 web 平台提供 UI）。
- 至少一条可用的 LLM 路由（优化默认跟随当前会话模型；也可在插件的模型胶囊里单独指定）。
- 插件本身零运行时依赖、无需构建（lib/ 里就是可直接运行的 JavaScript）。

二、30 秒上手

1. 在输入框正常打字，按 Enter（或点发送）。
2. 消息被拦下，右下角弹出迷你窗，里面有两栏：思考（优化 AI 的推理过程，带本次思考 token 数）与产出（给你要发的那条命令）。
3. 权限为 需要审查 时：可以直接编辑产出文本 → 点 确认提交 发出；不满意就 重新生成（会让你先填一个方向）。
4. 权限为 自动输出 时：优化一完成就自动发出，无需操作。
5. 不想优化了：点 ‹ 回退（停优化 + 关窗 + 不发消息 + 原文留在输入框），或点 放行本条 直接按原文发出。

输入框左侧的控件，从左到右是：优化档位（滑块）、优化权限（滑块）、上下文（滑块 + 右侧贴着「回合 / 全文」转化按钮）、优化模型（胶囊），再右边是 使用帮助（?）。点 ? 有同样的简明教程 + 署名。

三、控件怎么选

| 控件 | 取值 | 说明 |
|---|---|---|
| 优化档位 | 关闭 / 普通 / 高级 / 极端（英文界面：Off / Low / High / Ultra） | 档位 = 依据预算。关闭＝完全不拦截；普通＝只用你的原话＋上下文（补①指代定位 ②验收判据，不读项目）；高级＝按需读项目文件核实（五类缺口全补，每条改动可核对）＋锚点；极端＝深读交叉核对（每条改动都带出处），允许在不违背你意图的前提下正向丰富 |
| 优化权限 | 需要审查 / 自动输出 | 审查＝产出可编辑，点「确认提交」才发；自动＝优化完成即自动发出（失败也会按原文发出，绝不静默吞消息） |
| 上下文 | 回合 0~10 ／ 全文 关 / 开 | 滑块右侧那枚按钮点一下换一态：回合＝读最近 0~10 回合（你一次 ＋ AI 一次 = 1 回合；0 = 不读）；全文＝把工作 AI 现在看到的那一份上下文（会话投影，双方全文）交给优化模型。读多少只由这里决定：超预算时只压缩呈现（先截断助手回复 → 再省略助手 → 再逐条截断），范围不变；只有最简形式仍放不下，才由远及近丢回合并写明丢了几条。注入块始终以旁观者视角呈现（"你是旁观者与指挥者，不是执行者"）——否则优化 AI 会以为自己是干活的那个 |
| 优化模型 | 任意 provider/模型 | 只影响优化，不动对话模型；弹层里会标出「会话当前」模型；某家 provider 连不上会被标注「不可达」，不会拖慢整张列表 |
| 界面语言 | 中文 / English | 跟随 DSH 设置里的语言，插件内不单独设置 |

想要发挥插件所有能力且自动化，建议【极端】+【自动】。

上下文要用哪种？平时用「回合 3~10」（长迭代里"修复这个 bug"这类指代就靠它落地）；需要它对齐"工作 AI 现在看到的全部"时切「全文 → 开」（代价是每次多花几万字符）。不想让它读上下文就拨到 0——此时它必须明说"未找到指代来源"，而不是替你猜一个 bug。

四、迷你窗

- 可拖动：按住标题栏拖。
- 可改尺寸：拖右下角手柄，尺寸会记住（下次开窗沿用）。
- 不会跑丢：窗口缩小/切换会话后再打开，会自动夹回可见区域。
- 按会话隔离：窗口属于触发它的那个会话。
- 关键按钮永不消失：底部是常驻操作栏（确认提交 / 重新生成 / 回退 / 放行 / 重试），不随内容滚动，窗口再小也点得到；窗口很矮时会自动压缩内容区。
- 思考 token 计数：状态行显示本次总用量（如 Σ 1.1k tok），「思考」标题右侧显示思考消耗的 token（provider 不上报时显示 — tok），「产出」标题右侧显示输出 token，旁边还有字数。

五、常见问题

| 现象 | 原因 / 处理 |
|---|---|
| 按回车没反应，消息也没发出去 | 说明已进入优化流程，看迷你窗的进度；若窗口不在视野，切到该会话即会出现 |
| 优化很慢 | 高级/极端档需要 20 秒左右（极端档还会读项目结构）。想快就用普通档 |
| 提示“优化模型不可用 → 已按原文发出” | 所选模型连不上（例如本机 ollama 未启动）。插件会自动回退到会话默认模型，下次用默认模型 |
| 想临时不用 | 把档位滑块拉到最左「关闭」 |
| 弹层里某家模型标「不可达」 | 该 provider 当前不可用（未启动/无权限），不影响其它模型 |
| 界面能换英文吗 | 能。跟随 DSH「设置 → 通用 → 语言」：选中文则全中文，选英文则全英文，切换即时生效（v0.2.2-beta.1 起） |
| 点了「放行本条」/「确定回退」，消息却又自动发出了一条（在会话里显示成「排队发送」） | 这是 0.1.9 修掉的缺陷：放行/回退后，迟到的“优化完成”事件仍会走自动发送，补发了第二条。现在运行一旦被用户终结（放行/回退）就带终态标记，autoSend 与 done 分支都会跳过；放行时还会同时中止后端运行。请升级到 0.1.9beta1 及以上 |
| 命令里老是让我先建 goal / 列 todo，太啰嗦 | 这是按难度判定的结果：只有多点改动或命中高危信号才会要求建目标/分阶段；单点小改应当只给一句命令 + 一句完成标志。若简单任务被过度编排，请把该条输出发我 —— 判定用例与规则见 PROMPT-OPTIMIZATION.md |
| 命令里反问我“请确认用哪个文件”，明明它自己查得到 | 这是 v0.2.1-beta.2 修掉的缺陷（把“项目事实未知”误写成“停下等用户确认”）。请升级；若仍出现，把该条输出发我 |

六、卸载

dsh plugin --profile web remove @dsh-external/dsh-prompt-optimizer

若用“方式 B”安装，请同时删除 cordis.patch.yml 里那条 insert。插件设置存在 ~/.dsh/prompt-optimizer.json（档位/权限/模型/上下文模式/迷你窗尺寸/按会话设置），如需彻底清理可一并删除。

七、实测数据与证明（不吹嘘）

测量方式（全部为宿主内一次性测量台，不进产品代码；脚本在 evidence/，可复现）：

题目（用户原话） --relay 优化--> 命令 --solve 执行--> 执行 AI 的回答 --judge 评分--> 分数

- 固定执行 AI 与固定评分卡，每道题跑同一批条件；判分时不给评分员看条件标签（盲评）。
- 命令侧：优化器产出的命令本身注入了多少实质要求，每题满分 5 分。
- 答案侧：执行 AI 回答质量，每题满分 10 分（严格 0/1/2 逐点评分）。
- 单格噪声实测 ±1 分（命令侧）/ ±2 分（答案侧），所以关键结论用重复采样（n=2~4）并如实标注落在噪声内的差异。

命令侧（4 道题，满分 20）

| 条件 | 高级档 | 极端档 |
|---|---|---|
| 无优化（对照） | 4 | ≈4 |
| 0.1.1 旧提示词 | 19 | 18.7（n=2~3） |
| 0.1.9 退化版 | 16 | 15.3（n=2~4） |
| 0.2.1 修复后（现版基线） | 18 | 18 |

- 退化是真实存在的（极端档 18.7 → 15.3），不是主观感受；修复后回到 0.1.1 水平或更好：极端档在 10/10 次配对比较中 ≥ 退化版（符号检验 p≈0.001）。
- 四档都测过：关闭＝无优化对照（4/20，说明优化确实带来变化）；普通＝按设计只做语言层修复、不新增需求，故不参与“实质注入”比较。

答案侧（3 道硬题，满分 10）

| 条件 | T5 条件概率陷阱 | T6 物理量级估算 | T4 工程题 |
|---|---|---|---|
| 无优化 | 8 | 4~5 | 9 |
| 0.1.1 旧 | 10 | 9 / 7 | 9 |
| 0.1.9 退化版 | 8 / 10 | 9 / 9 | 4 |
| 0.2.1-beta.1 | 10 / 10 | 10 / 9 | 4 |
| 0.3.1（先防后查） | 93.9% | 169/180 | 9 胜 0 负 1 平 |

必须一起读的四条限制（否则会高估这些数字）：

1. 极端档 T4 的低分（1~6/10）是测量台局限，不是提示词缺陷：台里的执行 AI 没有文件系统/命令工具，而命令要求它“先扫工作目录”，于是它只能停下。该命令本身经逐字检查是全场质量最高的，因此这一格不计入结论。
2. 答案侧在强模型上会饱和：不少格“无优化”也能拿高分（例如 T4 的 9/10），所以答案侧的区分力弱于命令侧。
3. 样本量有限：多数格 n=1~3，单格 1~2 分的差异属于噪声；本文只把“方向一致 + 活跃路径可见”的差异当作结论。
4. 以上数字来自特定 4~7 道题（条件概率陷阱、量级估算、工程改造等），不能外推到你自己的任务。

复现入口：evidence/prompt-snapshot.cjs（导出任意版本的三档提示词快照）、evidence/prompt-invariants.cjs（约束闸门：30 条正向 + 4 条反向断言，含 v0.2.2 新增的「输出语言跟随用户原话」）、evidence/lab-build.cjs / lab-ans.cjs（测量台）、evidence/lab-ship.cjs（结果汇总）。改提示词前先跑闸门，失败即回退。

产物级验证（单文件 HTML，独立审计，不依赖浏览器）：H1 法线盒体 / H2 操控 / H3 审计并修复反向面，两条件各 7 份产物 —— 发布版 5/7 = 71.4% · v0.3 5/7 = 71.4%（打平）；H1、H2 两条件全部通过（独立审计 inwardFaces 全为 0），H3 各 2/4，四份失败全是“接口未暴露到全局”（属执行 AI 的接口一致性，命令侧 4/4 都已要求）。产物级目前不区分两个条件，有区分度的是命令侧。验证器自证：正确夹具 15/15 PASS、绕序反转夹具 FAIL 且 inwardFaces=12。一键复跑：node evidence/artifact-check.cjs。
产出语言跟随你（真跑实测，非模拟）：走宿主生产路径各跑一条 —— 英文输入 Add a rate limiter to the login endpoint. → 产出全文 3511 字符、中日韩字符 0、首行 First locate the login endpoint: …；中文输入 给登录接口加一个限流。 → 1353 字符、中日韩 1037（占 0.766）、首行 任务：给登录接口加限流。（evidence/lang-probe.cjs + lang-probe.json，统计基于全文快照而非 4000 字截断）。

八、实现要点（给想改代码的人）

- 两个半边：lib/index.js（宿主：提示词部件化组装与传话框架、只读工具循环、SSE 流式运行、模型目录、状态落盘、HTTP 路由）＋ lib/client.js（浏览器：控件行、模型/帮助弹层、迷你窗、捕获阶段拦截回车与发送按钮）。
- 提示词是部件化组装的：V6_CORE → 档位正文（由轴渲染：grounding / depth / sequence / budget） → 观察者上下文块 → 下游形态声明块（delivery=ptc 时） → 产出收件人契约（OUTPUT_ADDRESSEE_CONTRACT），由 buildSystem(tier, { historyMode, observerBlock, delivery }) 统一组装（工具路径下另有依据索引 renderEvidenceLedger，随工具结果注入）——同一句规则只有一份，改一处全局生效。
不变式（SPEC 铁律 6）：delivery 只投影 sequence（工序↔清单）与 budget（不设限↔够用即止），绝不动 grounding / depth / enrich；档位＝依据预算（depth：precise / grounded / exhaustive），模型与 effort、上下文开关都与档位解耦。
护栏：evidence/snapshot-v6-prompts.cjs --compare 逐字节比对三档基线——重冻基线必须带 --reason（防止悄悄改判据）；本轮基线为 SPEC v0.5，旧基线存档 evidence/v6-prompt-baseline-beta6.json，逐行差异见 evidence/diff-v6-prompts.cjs。当前长度（chat 形态、无观察者块）：普通 1541 / 高级 1681 / 极端 1794 字符。
- 上下文只有一条注入路径（SPEC W1b）：renderObserverBlock 读会话投影 derived，范围只由 UI「回合／全文」决定（回合＝用户一次＋AI 一次，0＝不读）；预算不足只降详细度、不改范围；解析不到会话不注入（绝不回落到"列表里第一个会话"）。单测：evidence/verify-context-scope.cjs（13/13）。
- 验收（SPEC §7）：① evidence/audit-provenance.cjs 出处审计（产物引用的路径必须在依据索引里；无出处的事实性断言＝缺陷）② evidence/compare-referent.cjs 同题对照（"修复这个 bug"有／无上下文）③ 一次交付可用率（人工记录）。
- i18n 实现：客户端读取 DSH 的 locale 服务（getSnapshot().active 为 zh / en）并订阅变化；文案表 EN_TEXT 以中文原文为键（179 条），查不到即原样返回中文，因此漏翻只会显示中文、不会显示空白；语言服务不可用时按中文兜底。
- 拦截是捕获阶段在 window 上做的（早于 React 与编辑器自身处理）：Shift+Enter 换行、/ 命令、空草稿、仅附件、输入卡片之外的回车一律放行。
- 不改动官方发送链路：确认发送时用官方 inputActions.setDraft() + submit()，与手动发送完全同一条路。
- 自检：evidence/ 下有可复现的自检（range-demo 滑块、help-demo 帮助面板在视口内、i18n-demo 强制 en/zh 双语断言）；ACCEPTANCE.md 是逐格验收清单；evidence/.jsonl 是机器留痕（客户端 beacon、遥测、对照数据）。

九、隐私与边界

- 优化请求发送你的输入文本与按你的设置读入的会话上下文（回合 / 全文，见下条）；只读权限开启时（默认开启），高级/极端档还会用 read/glob/grep 读项目文件——限定在本次运行所属会话的工作目录内、不写盘、不执行命令；基础档始终不读项目。
身份层：会话 / 工作目录 / 下游形态只解析一次，且解析不到就不猜——不派工具、不注入观察者（形态不受影响：默认 PTC），退化成"纯需求重述"，绝不会把别的会话目录里的现状当成你的项目事实。判定结果可在 /runs 的 context / toolRoot 里核对。
依据索引：只有本次实际读到的路径与符号才允许被写成"事实"（索引随工具结果一并注入，并给出可引用的 路径:行号）；只列过目录不等于知道内容；一次都没读到就不写"事实 / 现状"段。
- 上下文只读你指定的那个会话（指不到就不读）：回合＝最近 0~10 回合的双方全文（0＝不读）；全文＝与工作 AI 现在看到的一致的那份投影；超预算只压缩呈现、不改范围，且永远写明压缩了什么。注入块以旁观者视角呈现（明确声明"你不是执行者"），避免优化 AI 把自己当成干活的那个。
- 迷你窗默认不发送任何消息：只有「确认提交」/「自动输出」/「放行本条」三条路径会把内容交回官方发送链路。
- 本插件为客户端 + 宿主本地插件，不引入任何第三方服务。

十、许可与协作

BSD-3-Clause。完全开源：任何人、任何形式使用与修改都欢迎；也欢迎提 Issue、提 PR、以及各种测试反馈。见 LICENSE 与 CHANGELOG.md。