前言¶
在 DSH 的插件化方式下，agent 工作流中的具体能力可以做成独立插件。对提示词生成来说，一个常见问题是原始指令往往很短，例如“写个排查 502 的步骤”，直接交给模型容易得到泛化输出。oss-prompt-optimizer 处理这个环节：把简短指令改写成专业、可直接使用的提示词，输出面向 Role / Task / Context / Format 这类结构化表达。优化通过 harness 的 LLM 服务完成，不直连 API，也不触碰凭据。
这是什么¶
oss-prompt-optimizer 是 DSH 插件 bundle，npm 包名为 oss-prompt-optimizer，许可证为 MIT。仓库地址是 https://github.com/seven282/oss-prompt-optimizer。它解决的是提示词质量与复用问题：既给 agent 提供可调用工具，也给其他插件提供编程接口，还可以在 composer 输入框中直接优化当前草稿。
核心功能¶
面向 agent 的优化工具¶
插件提供工具 prompt_optimize。agent 可传入 instruction 获取优化结果，也可传入 lastOptimized 与 iterateInstruction 对已有优化结果做迭代改写。
面向其他插件的服务接口¶
插件提供服务 ctx.promptOptimizer，支持 optimize 与 iterate。其他插件可调用：
ctx.promptOptimizer.optimize(rawInput, { signal })
或：
ctx.promptOptimizer.iterate(lastOptimized, instruction, { signal })
浏览器端可通过远端接口调用：
ctx.remote.promptOptimizer.optimize(sessionId, text)
composer 输入框优化¶
composer 输入框提供常驻优化图标。点击后会优化当前草稿并写回输入框；优化中可取消，成功后可撤销。
自动优化¶
自动优化钩子可对 /optimize 前缀消息在进入模型前优化。运行时可用：
/optimize --auto on
/optimize --auto off
/optimize --auto toggle
/optimize --auto status
控制开关。自动优化默认开启，但只对 autoOptimizePrefix（/optimize）前缀消息生效；无前缀消息原样进入模型。每个步骤最多优化一条消息；未命中前缀、前缀后内容为空或优化失败时，原消息原样进入模型。
上下文、情境感知与角色定义¶
上下文感知默认开启，可把最近对话作为背景参考注入元提示词；也可通过配置关闭：
contextAware: false
情境感知可将指令与上下文解析为角色、任务、目标画像，并注入元提示词，支持目标对齐重试与会话级目标沿用。
角色定义按身份、能力、行为三要素撰写，并按代码、文案、分析、运维等任务类型给出写法建议。
角色文档语言可按输入内容自动切换中文或英文，并可通过 /optimize --language 固定或恢复自动。
输出、校验、缓存与时长控制¶
输出保持完整可执行提示词。空输入会报错；超长输入有截断护栏；支持 UI 层取消。
后置校验可在输出缺段、过薄、过短时自动重试，并返回机器可读错误码。
优化时长控制方面，流式早期终止默认关闭；可使用速档：
optimizationProfile: fast
结果缓存采用 LRU + TTL，相同请求可零模型调用；缓存默认开启且为内存缓存，重启即清空。
自迭代与设置面板¶
自迭代系统默认开启，包含会话学习、智能默认值与用户覆盖；累计 10 次优化数据后开始生效。学习数据默认持久化到：
~/.dsh/oss-prompt-optimizer/state.json
持久化仅保存行为元数据，不保存指令原文。
插件在 DeepSeek Harness 设置面板注册 prompt-optimizer 命名空间，可查看和调整配置项。宿主无 settings 服务时自动跳过设置面板，配置仍走 cordis.patch.yml。
运行时命令与模板¶
支持运行时命令临时覆盖 profile、local、temperature，并可查看 insights、status 和清除覆盖：
/optimize --set-profile fast|balanced
/optimize --set-local on|off|hybrid
/optimize --set-temperature <0-2>
/optimize --clear
/optimize --insights
/optimize --status
提供 /template 场景模板，直接返回可填写四段模板或本地渲染预填版，不调用模型。例如：
/template 周报
/template 周报 总结本周进展
事件订阅¶
插件通过事件总线发布以下事件，供其他插件订阅：
optimize:start
optimize:success
optimize:failure
安装与启用¶
使用 npm 安装¶
在目标 profile 中安装 npm 包：
dsh plugin --profile web add oss-prompt-optimizer
使用 GitHub 安装¶
从 GitHub 源码构建安装：
dsh plugin --profile web add github:seven282/oss-prompt-optimizer
GitHub 安装需要授权 prepare。在 pnpm ≥10 场景，可能需要允许构建：
allowBuilds:
oss-prompt-optimizer: true
建议锁定 commit，例如：
github:seven282/oss-prompt-optimizer#<sha>
卸载¶
dsh plugin --profile web remove oss-prompt-optimizer
重启 harness¶
安装或卸载后需重启 harness，使 bundle 层生效：
dsh web
配置自动优化¶
在 cordis.patch.yml 中可配置：
autoOptimize: true
autoOptimizePrefix: '/optimize '
配置后，以 /optimize 前缀开头的消息会进入自动优化流程；无前缀消息保持原样。
典型用法¶
agent 工作流中调用¶
当 agent 收到一条需要优化为提示词的原始指令时，可调用 prompt_optimize，传入 instruction。如果已经有一版优化结果，并希望继续修改，可传入 lastOptimized 与 iterateInstruction 做迭代。
其他插件中调用¶
其他 DSH 插件可通过 ctx.promptOptimizer 使用统一入口，避免各自实现一套提示词改写逻辑。
const result = await ctx.promptOptimizer.optimize(rawInput, { signal })
若要对上一轮结果继续调整：
const next = await ctx.promptOptimizer.iterate(lastOptimized, instruction, { signal })
浏览器端可调用：
ctx.remote.promptOptimizer.optimize(sessionId, text)
在会话中临时调整参数¶
/optimize --set-profile fast|balanced
/optimize --set-local on|off|hybrid
/optimize --set-temperature <0-2>
/optimize --clear
/optimize --insights
/optimize --status
这些命令适合在单次会话中试验不同参数，无需改全局配置。
用模板快速起草¶
当只需要一个可填写骨架，不希望调用模型时，可使用：
/template 周报
如果需要本地预填版：
/template 周报 总结本周进展
适用场景与注意¶
适合以下场景：
- agent 工作流需要把短指令变成更完整、可执行的提示词。
- 其他 DSH 插件需要统一调用提示词优化能力。
- composer 输入框需要快速优化当前草稿。
- 只需要场景模板骨架，不想每次都走模型调用。
- 需要在会话中临时试验
profile、local、temperature等参数。
使用前注意：
- 插件以当前
dsh进程权限运行；安装前应检查源码、许可证与依赖。 - 许可证为 MIT，可自由使用、修改与分发，包括商业用途。
- 优化经 harness 的 LLM 服务完成，不直连任何 API、不触碰凭据。
- 自动优化默认只对
/optimize前缀消息生效，不会改动普通对话。 - 结果缓存是内存缓存，重启即清空；自迭代默认开启，累计 10 次优化数据后开始生效，持久化仅保存行为元数据。
package.json的peerDependencies要求@deepseek-ai/cordis ^4.0.1及多个dsh-*rc 包；已核实资料中该列表截断，完整列表以仓库package.json为准。- 空输入会报错；超长输入有截断护栏；自动优化失败时原消息原样进入模型。
结尾¶
oss-prompt-optimizer 把提示词优化放到 DSH 插件生态中作为独立能力：它可以给 agent 提供工具，给其他插件提供服务，也可以在输入框中优化草稿。若准备引入，先确认 profile 依赖与 MIT 许可，再安装并重启 harness。
GitHub：https://github.com/seven282/oss-prompt-optimizer
插件目录页：已核实资料未提供目录页 URL，可按 npm 包名 oss-prompt-optimizer 在 DSH 插件目录中查找。
