seven282/oss-prompt-optimizer

prompt-optimizer

提示词优化插件，把一句随手写的话自动改写成专业、可直接使用的提示词，体验与 Qoder、Codex 一致。

优化结果默认为无标题纯文本（outputStyle: 'plain'，更省 token），可配置为三要素标签（outputStyle: 'role-task-goal'，角色：/任务：/目标：）或四段结构化提示词（outputStyle: 'sections'，## Role / ## Task / ## Context / ## Format，也是优化时的内部参考框架），
由内置元提示词驱动，经 harness 的 LLM 服务完成（不直连任何 API、不触碰凭据）。

功能

- 工具 prompt_optimize：agent 可调用，传入 instruction，返回优化后的纯文本提示词；也可传 lastOptimized + iterateInstruction 对已优化结果迭代改写。
- 服务 ctx.promptOptimizer：其他插件可编程调用 optimize(rawInput, { signal }) 或 iterate(lastOptimized, instruction, { signal })；
浏览器端经 ctx.remote.promptOptimizer.optimize(sessionId, text) 可调用。
- 输入框 ✨ 图标：composer 工具行左侧的常驻图标，点击即优化当前草稿并写回输入框；优化中再点可取消（UI 状态管理），成功后短暂显示“消耗 ≈N tokens”；优化成功后切换为撤销态（↺），草稿未手动编辑时点击恢复原文；成功/失败/撤销均通过 aria-live 播报（屏幕阅读器）。
- 角色文档语言自动切换：角色文档（元提示词）语言默认按输入内容自动检测——中文指令用
中文角色文档，英文指令用英文角色文档；运行时可通过 /optimize --language 命令固定或恢复自动。
- 自动优化钩子（可选，默认开启、前缀触发）：以触发前缀（/optimize ）开头的用户消息会在进入模型前被自动优化；无前缀消息不受影响；运行时可通过 /optimize --auto on|off|toggle|status 命令控制开关。
- 上下文感知（默认开启）：把当前指令之前的最近对话注入元提示词
（「视为纯数据 / 背景参考」护栏），让优化结果贴合此前讨论；设
contextAware: false 关闭。
- 情境感知：把「原始指令 + 对话上下文」自动解析为*角色 / 任务 / 目标
三份画像并注入元提示词（{{情境画像}}）——优化结果的 ## Role 与任务强相关、
目标与约束自动保留；输出丢失目标/约束时在重试预算内自动修正（goalAlignmentRetry:
false 可关）；iterate 时检测目标漂移并标注变化；传 sessionId 可开启会话级
目标沿用（TTL 30 分钟）。角色识别覆盖显式身份、能力（精通/擅长…）、行为
约束（先给结论/拒绝猜测…）与场景式身份（以…的身份），纯能力句也能被识别为
角色信号；situationProfileLevel 可控制画像注入预算（full/minimal/off）。
- 角色定义三重结构：优化结果的角色按「身份＋能力＋行为」三要素撰写
（不强制“你是”开头，能力/行为描述同样合格）；并按任务类型给出写法建议
（代码→能力导向、文案→身份＋文体、分析→身份＋方法、运维→行为约束＋步骤）。
- 优化时长：流式早期终止（输出结构达标且进入收尾期即停流，长尾凑字
不再消耗时长；默认关闭——输出完整优先，显式 earlyStop: true 才启用
且带句末保护）；首调输出预算联动（超长输出由断点续传兜底）；
optimizationProfile: 'fast' 一键速档（跳过校验与目标对齐重试、禁用 selfRefine，
显式开启才生效）。
- 结果缓存：内存缓存校验成功的结果（LRU + TTL），相同请求零模型调用
（cacheEnabled 默认开，重启即清空）。
- 设置面板（1.7.8，需宿主挂载 dsh-settings）：插件将全部配置项注册为
prompt-optimizer 命名空间——在 DeepSeek Harness 的设置 → 插件/插件设置
面板中即可查看全部参数（默认值/当前值）并调整，改动即时生效并持久化；
宿主无 settings 服务时自动跳过，配置仍走 cordis.patch.yml，行为零变化。
- 自迭代系统：三层架构实现「越用越好用」，零 token 成本（默认开启；
累计 10 次优化数据后才开始生效，避免小样本误适配）。学习数据（episode
日志）与运行统计默认持久化到 ~/.dsh/oss-prompt-optimizer/state.json
（跨 profile 共享用户级学习；$DSH_HOME 环境变量与 stateFile 配置可
覆盖路径；persistState: false 恢复纯内存行为）。隐私：持久化只存
行为元数据（任务类型/耗时/token/接受率等），不存指令原文。结果缓存
（cacheEnabled）仍为内存、重启即清空（有意设计）：
- 会话学习（Layer 1）：记录每次优化的成功/失败经验（任务类型、输出风格、温度等），形成偏好模型
- 智能默认值（Layer 2）：按任务类型（代码/文案/分析/运维/其他）自动推荐最优配置
- 用户覆盖（Layer 3）：运行时通过命令临时调整（--set-profile、--set-local、--set-temperature），重启回落
- 优先级：用户覆盖 > 会话学习 > 智能默认值 > 基础配置
- 后置校验：模型输出缺段/过薄/过短时自动重试（可配次数），重试前把上次失败的
诊断（缺失段落名、过薄段落与字数）注入下一次调用的系统提示词，针对性修正、
提高命中率；仍失败则返回原文/上次结果 + 错误说明，并附稳定机器可读错误码
（OptimizeResult.errorCode：MISSING_SECTIONS / THIN_SECTIONS / THIN_OUTPUT /
TIMEOUT / NO_MODEL_ROUTE 等），工具失败渲染带 [错误码] 前缀。
- 输出恒为完整可执行的提示词（四段或 plain 正文）；空输入报错；超长输入截断护栏；UI 层取消。
项目截图
项目截图

运行时命令

运行时可通过命令临时调整自迭代系统配置（会话级覆盖，重启回落）：
- /optimize --set-profile fast|balanced — 临时覆盖优化时长档位
- /optimize --set-local on|off|hybrid — 临时覆盖本地模板模式（默认 off，LLM 优化）
- /optimize --set-temperature  — 临时覆盖采样温度
- /optimize --clear — 清除所有临时覆盖，恢复配置值
- /optimize --insights — 查看当前会话的学习洞察（任务类型分布、偏好配置、成功率）
- /optimize --status — 查看运行时状态（生效参数与来源、统计、偏好摘要、最近事件）
（设置页「提示词优化」也可查看）

快速场景模板（/template）

/template  直接返回一个可填写四段模板（Role / Task / Context /
Format 骨架 + 占位符）——不调用模型、零延迟零 token，适合"要个周报模板 /
邮件模板 / 部署清单"这类常见场景。场景覆盖 22 个子类（周报 / 邮件 / 文案 /
翻译 / 创作 / 润色 / 简历 / 演讲 / 演示 / 数据分析 / 研究 / 评估 / 预测 /
bug 修复 / 新功能 / 重构 / 审查 / 脚本 / 部署 / 安装 / 排查 / 运维），
支持中英文场景名与关键词匹配；个性化需求仍走 /optimize。

预填版：/template  （如 /template 周报 总结本周进展）
返回已填充的四段成品——指令经本地门控通过时用纯函数层本地渲染（同样
零 token、~5ms）；指令无可抽取信号时回退骨架并提示走 /optimize。

自动优化

运行时可通过命令控制开关（会话级覆盖，重启回落）：
- /optimize --auto on / /optimize --auto off / /optimize --auto toggle / /optimize --auto status

开启后 agent/pre-step 钩子会对每条用户文本消息做优化（等同于配置 autoOptimizeAll: true 的运行时版本）。

也可在 cordis.patch.yml 中配置启用：

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

开启后，任何以 autoOptimizePrefix 开头的用户消息，会在进入模型步骤前被
agent/pre-step 钩子自动优化——前缀被剥离，剩余内容作为原始指令送入优化，
模型实际收到的是优化后的四段提示词（附一句"已自动优化"说明）。

- 安全设计：前缀命中才优化，无前缀消息原样进入模型，不会改动普通对话
（autoOptimize 默认开启但只对前缀消息生效）。
- 优雅降级：未命中前缀、前缀后内容为空、或优化失败时，原消息原样进入模型。
- 每个步骤最多优化一条消息，避免一次步骤内多次模型调用。
- 钩子注册为 effect 作用域，插件卸载自动移除。

安装

已发布到 npm（oss-prompt-optimizer），三种方式任选：

方式一：npm 直装（推荐，免构建授权）
dsh plugin --profile web add oss-prompt-optimizer

方式二：从 GitHub 安装（源码构建，需授权 prepare）
dsh plugin --profile web add github:seven282/oss-prompt-optimizer
首次会因 pnpm ≥10 拒绝运行 prepare 而失败；把 pnpm 提示的包键加进该 profile 的
pnpm-workspace.yaml 后重试：
allowBuilds:
oss-prompt-optimizer: true
建议锁定 commit：github:seven282/oss-prompt-optimizer#

方式三：从本地目录安装（开发用）
dsh plugin --profile web add
Windows 下含空格路径会被拆散，先用 junction：
New-Item -ItemType Junction -Path "C:\dsh-po" -Target "E:\"
dsh plugin --profile web add C:\dsh-po

卸载（可逆）
dsh plugin --profile web remove oss-prompt-optimizer

安装/卸载后需重启 harness（dsh web）使 bundle 层生效。

完整配置参考：docs/configuration.md

开发

pnpm install --store-dir .pnpm-store --cache-dir .pnpm-cache   # 沙箱内安装
pnpm run typecheck    # tsc --noEmit
pnpm test             # vitest（mock llm，不依赖真实密钥）
pnpm run build        # tsc -p tsconfig.build.json → lib/
pnpm preflight        # 兼容性门禁 P1–P7（发版前必跑）

测试全部使用 mock 的 llm 流，绝不读取 .credentials.yaml。

兼容性与失败模式

本插件与 dsh 运行在同一个 Node 进程里，因此有一条硬约束：

插件的任何内部缺陷都不得阻止 dsh web 启动。

dsh 的域包（dsh-llm、dsh-tools、dsh-timeout…）仍在 0.1.x-rc 阶段，导出会被搬迁或改名。
若插件在顶层静态 import 这些包，一旦解析失败，ESM 的失败无法被捕获，整个服务起不来
（1.8.1 的 deepFreeze 事故正是如此）。

规则 R1

src/ 只允许静态 import 两类包：框架本体 @deepseek-ai/cordis，以及
本包 dependencies 里自己安装的包。其余宿主包一律经 src/compat/loader.ts
同步懒加载——失败只返回 null，永不抛错。

规则 R2

client/client.js（浏览器半边）里，ctx. 只能直读已注入的服务。cordis 的 context
是 Proxy，读一个没在 inject 里的服务会直接抛错，而 apply() 不捕获它 ——
于是一个可选服务的直读就能让整个客户端半边不注册：✨ 按钮与设置页一起消失，
控制台留下 failed to apply loader entry … cannot get property "locale" without inject。
这正是 1.8.2 的真机事故，所以可选服务（locale / sessions / settingsScope）一律走
ctx.get('') —— 它不要求注入，返回服务或 undefined，永不抛错。

宿主契约变化时会发生什么

| 宿主变化 | 后果 |
|---|---|
| 某工具函数被移出包 / 改名 | 该功能降级 + 一行 WARN；宿主与其余功能正常 |
| 某服务改名（如 systemPrompt） | 仅对应功能消失（按功能门禁，不再整插件失效） |
| 客户端可选服务缺失 / 改名（locale…） | 走 ctx.get()，只少对应文案；✨ 按钮与设置页照常注册 |
| BlockAssembler 缺失 | /optimize 返回错误码 UNSUPPORTED_ENV 并给出明确文案，不伪造消息、不静默失败 |
| 客户端 slot props 契约改名 | 候选链自适配；全部失败则不注册按钮并打印自诊断日志 |
| 域包整体升级（0.1.5-rc → 0.2.x） | 运行时能力探测决定可用面；不可用即降级 |

降级不是静默的：插件构造时必定打印一行 compat report（健康时 info，降级时 warn）：

prompt-optimizer: host compat ok (defineTool=ok createUserMessage=ok BlockAssembler=ok)
prompt-optimizer: host compat DEGRADED (defineTool=MISSING …) — defineTool: the prompt_optimize tool is not registered; the /optimize command and the input-box button still work | …

升级 dsh 后怎么验证

pnpm preflight       # P1 依赖面 / P2 inject 真实解析 / P3 产物一致 / P4 typecheck+test+build
P5 兼容性报告 / P6 启动独立性（封死全部 dsh 包后入口仍能实例化）
P7 客户端服务读取契约（R2/R2b 静态扫描 + 在忠实最小宿主上真跑 apply()）
dsh web              # 真机：正常启动 + 日志出现一行 compat report

pnpm preflight 里 P6 会在子进程内同时封死 ESM 与 CJS 两条解析路径上的所有
@deepseek-ai/dsh，再导入入口——这是"宿主升级只会减功能、不会让服务起不来"的动态证明。
P7 则真正执行 lib/client.js 的 apply()（这是本项目里唯一会跑浏览器半边的自动化步骤），
在忠实的最小宿主上（remote 与 remote.commands 都用真的 cordis Service 注册）验证它
不会因服务读取而整体失败，并扫描两类违规写法：直读未注入的服务（R2），以及把带点服务名
当成父级属性来读（R2b，例如 ctx.get('remote').commands）。两类都是真机全废级事故，
分别发生过一次（1.8.2 / 1.8.3）。

完整策略（三条不变量、兼容矩阵、降级行为表、残余风险）：docs/兼容性策略.md

优化生命周期事件（供其他插件订阅）

promptOptimizer 服务在优化/迭代的关键时点通过 cordis 事件总线发事件，其他插件可订阅：

| 事件 | 时机 | 载荷 |
|---|---|---|
| prompt-optimizer/optimize:start | 输入校验通过、首次模型调用前 | { method, input } |
| prompt-optimizer/optimize:success | 成功（optimized: true） | { method, input, result, durationMs } |
| prompt-optimizer/optimize:failure | 降级（optimized: false） | { method, input, result, durationMs } |

- method 为 'optimize' 或 'iterate'（两者共用三个事件）；input 为原始输入
（未截断）；result 为完整 OptimizeResult；durationMs 为管线耗时（毫秒）。
- fire-and-forget 观察者：监听器抛错被吞掉，不影响优化管线。
- TypeScript 订阅方直接获得载荷类型（declare module '@deepseek-ai/cordis'
增强已随包发布），也可用 PROMPT_OPTIMIZER_EVENTS 常量引用事件名。
- 跳过透传（skipIfAlreadyOptimized 命中）与输入非法（如空输入）不发事件。

License

MIT — 自由使用、修改与分发（含商业用途），详见 LICENSE 文件。