前言¶

在 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 週報 總結本週進展

適用場景與注意¶

適合以下場景：

1. agent 工作流需要把短指令變成更完整、可執行的提示詞。
2. 其他 DSH 插件需要統一調用提示詞優化能力。
3. composer 輸入框需要快速優化當前草稿。
4. 只需要場景模板骨架，不想每次都走模型調用。
5. 需要在會話中臨時試驗 profile、local、temperature 等參數。

使用前注意：

1. 插件以當前 dsh 進程權限運行；安裝前應檢查源碼、許可證與依賴。
2. 許可證爲 MIT，可自由使用、修改與分發，包括商業用途。
3. 優化經 harness 的 LLM 服務完成，不直連任何 API、不觸碰憑據。
4. 自動優化默認只對 /optimize 前綴消息生效，不會改動普通對話。
5. 結果緩存是內存緩存，重啓即清空；自迭代默認開啓，累計 10 次優化數據後開始生效，持久化僅保存行爲元數據。
6. package.json 的 peerDependencies 要求 @deepseek-ai/cordis ^4.0.1 及多個 dsh-* rc 包；已覈實資料中該列表截斷，完整列表以倉庫 package.json 爲準。
7. 空輸入會報錯；超長輸入有截斷護欄；自動優化失敗時原消息原樣進入模型。

結尾¶

oss-prompt-optimizer 把提示詞優化放到 DSH 插件生態中作爲獨立能力：它可以給 agent 提供工具，給其他插件提供服務，也可以在輸入框中優化草稿。若準備引入，先確認 profile 依賴與 MIT 許可，再安裝並重啓 harness。

GitHub：https://github.com/seven282/oss-prompt-optimizer
插件目錄頁：已覈實資料未提供目錄頁 URL，可按 npm 包名 oss-prompt-optimizer 在 DSH 插件目錄中查找。