oss-prompt-optimizer

dsh plugin --profile web add oss-prompt-optimizer

oss-prompt-optimizer





[English](README.en.md) | 简体中文

把随手写的一句话改写成专业、可直接使用的提示词。

DeepSeek Harness 插件。由内置元提示词驱动，经 harness 的 LLM 服务完成 —— 不直连任何 API、不触碰凭据。

npm 包名与仓库名是 oss-prompt-optimizer；安装后在宿主里的条目 id 与设置命名空间是 prompt-optimizer。

目录

• [快速开始](#快速开始)
• [功能](#功能)
• [使用](#使用)
• [配置](#配置)
• [兼容性](#兼容性)
• [开发](#开发)
• [故障排查](#故障排查)
• [生命周期事件](#生命周期事件)
• [贡献](#贡献)
• [安全](#安全)
• [许可证](#许可证)

快速开始

dsh plugin --profile web add oss-prompt-optimizer

安装或卸载后需重启 harness（dsh web）使 bundle 层生效。然后任选一种用法：

用法 · 操作

输入框按钮 · 点 composer 工具行的 ✨ —— 优化当前草稿并写回输入框

命令 · /optimize 把这段需求改写成清晰的提示词

模板 · /template 周报 —— 零模型调用

agent 调用 · 工具 prompt_optimize，传 instruction

功能

调用入口

• 工具 prompt_optimize — agent 可调用；传 instruction 返回优化后的提示词，传 lastOptimized + iterateInstruction 迭代改写。
• 服务 ctx.promptOptimizer — 其他插件可编程调用 optimize(rawInput, { signal }) / iterate(last, instruction, { signal })；

浏览器端经 ctx.remote.promptOptimizer。

• 输入框 ✨ 按钮 — composer 工具行的常驻图标；优化中再点即取消；成功后短暂显示「消耗 ≈N tokens」并切换为撤销态（↺），草稿未手动编辑时可恢复原文；成功/失败/撤销均经 aria-live 播报。

输出形态

• 三种 outputStyle — 默认 plain（无标题纯文本，最省 token）、role-task-goal（角色：/任务：/目标： 三要素标签）、sections（## Role /

## Task / ## Context / ## Format 四段，也是优化时的内部参考框架）。

• 角色文档语言自动切换 — 中文指令用中文角色文档、英文指令用英文；/optimize --language 可固定或恢复自动检测。
• 角色定义三重结构 — 角色按「身份＋能力＋行为」三要素撰写（不强制「你是」开头）；并按任务类型给写法建议（代码→能力导向、文案→身份＋文体、分析→身份＋方法、运维→行为约束＋步骤）。

质量与度量

• 后置校验与重试 — 输出缺段 / 过薄 / 过短时自动重试，并把上次诊断（缺失段落名、过薄段落与字数）注入下一次调用的系统提示词；仍失败则返回原文或上次结果 + 错误说明 + 稳定错误码（MISSING_SECTIONS /

THIN_SECTIONS / THIN_OUTPUT / TIMEOUT / NO_MODEL_ROUTE）。

• 评测闭环 /optimize-eval — 三层指标从省到贵：结构门（与优化管线同一份校验函数，不是复刻）→ 逐例期望（必须/绝不能包含的子串）→ 加权判官评分（1–5 分维度，判官必须先写理由再给分）。

判回归时命令返回错误结果，便于脚本与 CI 直接分支。

• 择优 best-of-N — selectCandidates > 1 时并发生成多个候选（温度阶梯 base + i·0.35）并保留最好的一个。三条规则不可动摇：门控决定资格、分数只决定排序；必须赢过基线

selectMinGain 才换人；判官漏评维度即不计分。⚠️ 本地模板路径不产生候选。

• 宿主反馈信号 — 读宿主自带的 messageFeedback（人工点赞/点踩）折算成温度偏置（负面 ≥50% → +0.1，≤20% → −0.1，样本 <3 不生效）。它评判的是过去的回答，

所以只做偏置并如实标注原因，不冒充质量分。

性能与成本

• 结果缓存 — 内存 LRU + TTL，相同请求零模型调用；cacheEnabled 默认开，重启即清空。
• 优化时长控制 — 流式早停（默认关闭，显式 earlyStop: true 才启用且带句末保护）、首调输出预算联动（超长输出由断点续传兜底）、optimizationProfile: 'fast' 一键速档。
• 真实用量台账 — 读宿主 usage 块累计真实 token 并给出缓存命中率；provider 未上报时标注「启发式估算」，

不与实测值混在一起。见 /optimize --stats 与 --status。

• 模型与 OTel 信号 — --status 多一行「目标模型」，生命周期载荷带 route 与 OpenTelemetry GenAI 形状的 genAi（键为 OTel 规范属性名，可直接

span.setAttributes(payload.genAi)）。按 run 记：零模型调用后不报模型，也不报它没测到的 token。

感知与学习

• 上下文感知 — 把当前指令之前的最近对话注入元提示词，附「视为纯数据 / 背景参考」护栏；contextAware: false 关闭。
• 情境感知 — 把「原始指令 + 对话上下文」解析成角色 / 任务 / 目标三份画像注入元提示词，目标与约束丢失时在重试预算内自动修正；传 sessionId 开启会话级目标沿用（TTL 30 分钟）。

situationProfileLevel 控制注入预算。

• 自迭代系统 — 三层架构，零 token：会话学习 → 智能默认值 → 用户覆盖（优先级递增），累计 10 次优化后生效。数据持久化到

~/.dsh/oss-prompt-optimizer/state.json（$DSH_HOME 与 stateFile 可覆盖路径）。

• 本地模板 /template — 覆盖 22 个子类；/template <场景> <指令> 经纯函数层本地渲染成品，零 token、~5ms。

集成与运维

• 自动优化钩子 — 以 /optimize 开头的消息在进入模型前被自动优化（前缀剥离）；无前缀消息原样进入模型。/optimize --auto 控制开关。
• 设置面板 — 左下角「设置」→ 左侧栏「提示词优化」；8 个常用开关改动即时生效并持久化。宿主无设置服务或当前连接不可写时，面板降级为只读并写明原因。
• 客户端文案跟随界面语言 — 翻译器按调用现取（而非 apply() 时捕获），✨ 按钮的全部 title / aria-label 与播报文案一并进字典。
• 全部注册（工具 / 命令 / 钩子 / 设置项）均为 effect 作用域，插件卸载自动清理。

使用

命令 · 作用

/optimize <指令> · 优化一条原始指令

/template <场景> [指令] · 返回可填写的四段模板；带指令时本地渲染成品。22 个子类示例见 [docs/subcategory-examples.md](docs/subcategory-examples.md)

/optimize-eval <子命令> · 评测优化器自身的输出质量（跑一轮真花模型调用）

/optimize 的旗标：

旗标 · 作用

--language auto\ · 中文\ · 英文\ · status · 角色文档语言

--auto on\ · off\ · toggle\ · status · 自动优化开关

--set-profile fast\ · balanced · 临时覆盖优化时长档位

--set-local on\ · off\ · hybrid · 临时覆盖本地模板模式

--set-temperature <0-2> · 临时覆盖采样温度

--clear · 清除全部临时覆盖，恢复配置值

--status · 运行时状态：生效参数与来源、统计、真实用量、择优与宿主反馈、评测成绩、偏好摘要、最近事件

--stats · 用量统计，末行含机器可读的 MODEL: / PROVIDER: / EFFORT:

--select · 上次择优的候选数、胜者与分数（未开启时说明如何开启）

--feedback · 宿主反馈计数与温度偏置

--insights · 当前会话的学习洞察（任务类型分布、偏好配置、成功率）

--language / --auto / --set-* 都是会话级覆盖，重启回落配置值。

/optimize-eval 子命令：run [标签] [--all] [--mine]（默认跑金标集 core 子集 8 例）、baseline [标签]、show、list、rubric、cases。

典型用法：改模板或管线前先 run + baseline 固定基准，改完再 run，用末行的 DELTA 证明这次改动确实更好。

配置

设置面板只列需要用户决策的 8 个开关：

字段 · 默认 · 作用

outputStyle · plain · 输出形态（plain / role-task-goal / sections）

situationProfileLevel · full · 情境画像注入预算（full / minimal / off）

contextAware · true · 注入最近对话

cacheEnabled · true · 结果缓存

optimizationProfile · balanced · 优化时长档位（balanced / fast）

localTemplate · off · 本地模板模式（off / on / hybrid）

autoOptimize · true · 前缀触发的自动优化

autoAdapt · true · 自迭代适配

其余（温度 / 预算 / 模板 / 评测 / 择优…）默认已调优，写在 cordis.patch.yml：

- insert:
    - id: prompt-optimizer
      name: 'oss-prompt-optimizer'
      config:
        autoOptimize: true
        autoOptimizePrefix: '/optimize '
        outputStyle: sections

全部配置键、默认值与副作用：[docs/configuration.md](docs/configuration.md)

非法配置（类型错误、越界、未知键）在加载时响亮失败。

兼容性

本插件与 dsh 运行在同一个 Node 进程里，

…(truncated)