dsh-optimized-prompt
v0.1.0
Published
DSH Web composer prompt optimizer: a sparkle button beside the send action rewrites the current draft into a structured eight-section prompt and fills it back into the input box
Readme
dsh-optimized-prompt
中文 | English
DSH Web 界面的提示词优化按钮:在会话输入框的工具行里加一个闪光图标按钮, 点一下就把当前草稿改写为含八个板块的结构化提示词并回填输入框。
- 位置:
conversation.input.right槽位,order = 97,即 ⚡️ 技能按钮的左侧、额度环的右侧。 - 图标:直接复用宿主的
IconSparkle16(@deepseek-ai/dsh-client-ui-primitives),与宿主图标族同一实例。 - 模型:复用宿主已注册的模型路由,不需要任何 API Key 或凭据配置。
- 零侵入:不修改任何随部署分发的宿主机文件,全部能力经公开扩展点提供。
它产出什么
固定八个板块,顺序即输出顺序:
| # | 板块 | 要求 | |---|------|------| | 1 | 角色定位 | 具体的专业角色与经验层级,不写"你是一个 AI 助手" | | 2 | 任务目标 | 一句话说清可验证的结果,多目标拆编号 | | 3 | 输入材料 | 列出已提供/所需材料;缺口写成待补充项而非编造 | | 4 | 输出格式与结构 | 交付物形态与长度量级 | | 5 | 内容要求 | 必须覆盖的要点与深度(最需要写实的板块) | | 6 | 风格语气 | 语言与表达密度 | | 7 | 约束与排除项 | 具体可判定的禁止项与边界 | | 8 | 成功标准 | 可自查的验收条件 |
语言与草稿一致(中文进中文出);草稿本身已是结构化提示词时在其内部精炼,不再套一层。
同一份改写能力也以宿主工具 optimize_prompt 暴露,界面按钮与工具共用同一个执行体
(src/optimize.ts),两者结果结构不会漂移。
安装
前置条件
装好 Trae 客户端并登录(插件复用它存在本机的登录态,从不索要密码)。 多账号 = 在客户端里换着登几次。
方式一:从 npm 安装(发布后可用)
dsh plugin --profile web add dsh-optimized-prompt方式二:从本地源码安装(开发者)
# 先构建插件
cd /path/to/dsh-optimized-prompt
npm run build
# 再安装到 DSH
dsh plugin --profile web add link:./dsh-optimized-prompt该命令会代劳三处改动:
- 在
$DSH_HOME/profiles/web/package.json的dependencies加入插件 - 在同文件
dsh.profile.bundles数组加入插件名 - 在
$DSH_HOME/profiles/web/node_modules/下建软链
方式三:从 Git 仓库安装
dsh plugin --profile web add git+https://github.com/DragonHorizon-xtihc/dsh-optimized-prompt.git构建产物
安装前需先构建:
cd /path/to/dsh-optimized-prompt
npm run build # 等价于:link-deps → tsc 宿主半 → tsc 客户端半(仅检查)→ tsdown产物:
lib/types/**—— 宿主半(package.json的main指向lib/types/index.js)lib/client.js—— 浏览器半,window.__ModuleLoader__.load({ id: "dsh-optimized-prompt", factory })闭包工厂
配置
全部配置项写在 cordis.patch.yml 的 config 下(改 profile 同名文件可覆盖):
| 键 | 默认 | 说明 |
|----|------|------|
| enabled | true | 关掉后只注册工具、不注册按钮端点,适合 headless 部署 |
| provider | '' | 专用优化模型的 provider;与 model 同时非空才生效 |
| model | '' | 专用优化模型的 id |
| maxTokens | 8192 | 生成长度上限(兜底)。真正的输出上界由模板里的长度契约(整篇 ≤1200 字)控制。注意:推理模型的思维链同样占用这份预算,所以这个值必须留足(2048/4096 都实测被截断过) |
| temperature | 0.3 | 改写任务要稳定,取偏低值 |
| timeoutMs | 60000 | 单次优化超时;超时中止上游调用并保留原草稿 |
| maxInputChars | 8000 | 草稿字符数上限,超过即拒绝、不截断 |
| minOutputChars | 120 | 保真闸:结果字数下限,低于此值视为不合格、不覆盖草稿 |
| requiredSections | 4 | 保真闸:结果必须命中的板块标题数(0–8) |
| cacheEnabled | true | 结果缓存。命中条件是「同一模型 + 同一生成参数 + 同一草稿」,命中时直接返回上次已通过保真闸的结果,不再调用模型 |
| cacheMaxEntries | 20 | 缓存最大条目数(LRU 淘汰);<= 0 等于关闭 |
| cacheTtlMs | 600000 | 缓存条目存活 10 分钟;<= 0 等于关闭。缓存只在进程内,重启即清空 |
模型回落顺序:provider+model → 当前会话所选模型(Agent.session.requestHeader().config)
→ 全局默认模型(ctx.agentDefaultModel.currentSelection())。三级都拿不到时返回可读的
no_model 失败,草稿不动。
想用更便宜的模型只做优化,配这两行即可:
provider: deepseek-official
model: deepseek-v4-flash数据流
[浏览器] 输入框草稿 ──useInput / inputActions.setDraft
│
├─ 点击按钮 → OptimizeFlow.start()
│ · 已空/在途直接返回(零请求)
│ · 记录 baseline{rev, text}
│
└─ POST /optimized-prompt/optimize { draft, sessionId }
│ ← 走宿主鉴权栅栏(同源 + dsh-auth Cookie)
▼
[宿主] 输入闸 → 模型解析 → ctx.llm.stream + BlockAssembler → 截断判定 → 保真闸
│
└─ 200 { ok:true, prompt, model } | 200 { ok:false, code, message }
▼
[浏览器] 比对 draftRev:没变 → 回填 + 建立撤回快照;变了 → 放弃回填并提示改写内容是唯一输入材料:不附带会话历史、工作区文件或其他会话数据。
开发
npm run typecheck # 宿主半 + 客户端半 + 测试 三程序类型检查(零错误为准)
npm test # 单元套件(9 文件 / 162 用例)
npm run test:integration # 集成套件(真实 cordis 装载,1 文件 / 15 用例)
node scripts/smoke-host.mjs # 构建产物冒烟:导出面 + 配置默认值为什么单元与集成分开跑:合并跑时全量用例都会通过,但 vitest 进程在收尾阶段不退出
(资源阈值特征,不是某个文件的缺陷——去掉集成文件或单独跑都能以 0 退出)。因此
vitest.config.ts 默认排除 *.integration.spec.ts,集成套件由 vitest.integration.config.ts
单独驱动,两个命令都能干净退出。
测试全部隔离:不启动 DSH、不监听端口、不发起真实模型调用、不读写任何真实数据。 模型端口在两个套件里都是注入的假实现。
隔离验证(不污染真实 profile)
宿主半:dsh --dump-config 会组合 profile 插件树并退出,不启动服务,是验证
"bundle 能否被 loader 解析、patch 行是否正确"的最强离线手段。
npm run verify # 安装产物校验(16 项)+ 宿主产物冒烟(14 项)scripts/verify-install.mjs 会从宿主权威源码 packages/client/web/src/platform.ts
现场读出 PLATFORM_MODULES 基线,再断言客户端产物的全部模块请求都落在基线内 ——
宿主改了基线本脚本立刻失败,不会悄悄漂移。
排查
| 现象 | 原因 | 处理 |
|------|------|------|
| 点按钮提示"无法连接到优化服务" | 插件没装好,或路由未注册 | 确认 profile 的 bundles 里有本插件、enabled 不是 false,然后重启界面 |
| 提示"未通过宿主鉴权(可能是页面来源不被信任)" | 鉴权栅栏按设计拒绝了请求(跨源 / 无 dsh-auth Cookie) | 用正常页面访问;不要用第三方页面或直连脚本调这个端点 |
| 提示"宿主的鉴权门禁当前不可用" | connection 服务未就绪,栅栏失败关闭返回 503 | 检查 profile 装配顺序,确认 connection 已挂载 |
| 按钮完全不出现 | 槽位注册被拒(宿主槽位改名),或客户端 bundle 未加载 | 看浏览器控制台是否有 Require 失败;确认 lib/client.js 已构建;本插件的注册是 try/catch 的,失败只降级不报错 |
| 按钮位置不对 | 同槽位其它插件的 order 与预期不同 | 本插件用 BUTTON_ORDER = 97(客户端常量)。先确认占位者的 order,再改该常量并重建客户端产物 |
| 提示"没有可用的模型" | 三级回退全空 | 在工作台选一个模型,或在上面的配置里指定 provider + model |
| 提示"优化结果在生成长度上限被截断" | 模型写到 maxTokens 仍未结束 | 先看报错给出的诊断数据再动手,按下表分诊 |
如何读懂截断报错
报错里会给出三样东西,它们决定该往哪个方向修:
模型 <provider>/<model>;实际产出 N 字,命中 M/8 个板块。| 观察到的 N(产出字数) | 说明 | 该做什么 |
|---|---|---|
| N 远小于预算应有的字数(如 8192 预算只产出几百字) | 预算被推理模型的思维链吃掉了 | 继续调大 maxTokens,或改用非推理模型 |
| N 接近或超过 1200 字契约 | 模型没遵守长度契约(常见于很长的草稿被复述) | 精简草稿;调大 maxTokens 只能缓解 |
| M 接近 8 | 只差结尾一点点 | 调大一点点即可 |
| M 远小于 8 | 模型在前面的板块就写嗨了 | 精简草稿,让诉求更聚焦 |
改配置的位置:cordis.patch.yml 的 config.maxTokens。改动源码后需 npm run build 并重启界面。
| 提示"未达到可回填标准" | 模型没按板块写,或结果过短 | 换一个能力更强的模型;或按需调低 requiredSections / minOutputChars(不建议调到能放过明显残次品) |
| 返回 401 / 403 / 503 | 鉴权栅栏按设计拒绝 | 见上文"排查"对应行 |
| 返回 400 | 请求体不是合法 JSON,或 draft / sessionId 类型不对 | 客户端契约问题,检查调用方 |
| 返回 413 | 请求体超过 4 MiB | 草稿过大,先精简 |
已知限制(实测确认,非猜测)
- 无法真正"锁定"输入框。宿主没有向第三方槽位暴露锁定编辑器的公开 API
(
InputActions只有setDraft/addAttachments/removeAttachment/pruneAttachments/submit;SessionInput另有beginCommand/insertReference/notify;contract/input.ts内 greplock零命中)。 字面实现需要改宿主分发文件,违反本项目的宪法原则 I 与 FR-017。因此改为语义等价的三重保护: 在途期间按钮禁用 + 结果返回时比对draftRev发现用户改动就放弃回填 + 覆盖前过保真闸。 该取舍已在需求澄清阶段与需求方确认。 - 按钮次序是编译期常量,不是宿主配置。宿主
DshClientManifest只有platform/inject/immediately/external四个字段(无配置通道),客户端半也拿不到 宿主插件的 Config,且槽位order必须在注册那一刻确定。放在宿主 Config 里只会造出 "改了不生效"的假配置项。改位置请改src/client/index.tsx的BUTTON_ORDER并重建客户端产物。 - 这次模型调用在成本与遥测里与普通会话请求同类。
GenerateOptions.purpose的类型是封闭 联合'compaction' | 'session-title',不接受自定义分类,因此本插件不设该字段。宿主契约限制, 插件无法绕过。 - 不解析草稿里附件与引用标记的语义,只把它们当作原文的一部分保留。
- 只服务 Web 界面。其他界面形态(TUI)下没有按钮;但
optimize_prompt工具仍然可用 (把enabled设为false就是明确的"只要工具"模式)。 - 不做流式逐字预览,一次返回完整结果。
与同类插件的差异(基于代码事实)
- 与本仓库先例
@deepseek-ai/dsh-cli-agents一致:都走"宿主 HTTP 路由 +connection鉴权栅栏", 而不是 Typert Remote(后者需要代码生成产物,对本地插件过重)。 - 与
dsh-skill-picker(占据同一槽位的 ⚡️ 按钮)一致:都从ctx.sessions取当前会话, 因为槽位 props 不含会话 id。 - 本插件独有的两点:① 界面按钮与宿主工具共用同一个执行体,杜绝两处实现漂移; ② 覆盖草稿前有保真闸,且失败路径一律不写入草稿。
健壮性设计(借鉴同类插件的事故)
分析同类开源插件 oss-prompt-optimizer 时发现其 1.8.1 版因静态 import 了一个宿主内部函数
deepFreeze,宿主升级改名后,整个 dsh web 启动失败——它随后专门做了 src/compat/loader.ts
把该 import 改成"同步惰性加载、永不抛"。我们据此把可有可无的宿主依赖也改成同样的惰性、
非致命加载(src/host-deps.ts):
| 宿主依赖 | 缺失时的降级行为(而非整体崩溃) |
|---|---|
| dsh-tools 的 defineTool | 只失去"agent 可调用 optimize_prompt 工具"这一项能力;按钮与 HTTP 路由照常 |
| dsh-timeout 的 deadline | timeoutMs 退化为"无协作式超时"(仍可用 AbortController 取消),不再整体失败 |
| dsh-llm 的 BlockAssembler / 消息构造器 | 改写执行体取不到时,按钮与工具都返回可读的 model_error,但不拖垮 dsh web |
关键事实(读 loader 源码确认):loader 的
_init()本就用 try/catch 包住插件模块 import (vendor/loader/src/config/entry.ts:175-189),且本插件不在requiredStartupEntryIds中, 所以即使静态 import 失败也只跳过本插件、不拖垮整个 profile。我们进一步把"缺依赖"变成 能力降级而非"插件消失",这样即使defineTool暂时取不到,按钮与 HTTP 路由仍可用。
其它借鉴来的加固:
- 服务暴露:插件在 cordis 上
provide('optimized-prompt-service', …),把唯一改写执行体暴露给 其它插件复用(不必各自再写一份改写逻辑,也不必走 HTTP)。 - 生命周期事件:
optimized-prompt.start/.success/.failure三个事件仅用于观测; 订阅方抛错不影响改写主流程(事件派发全部 try/catch)。 - 在途可取消:按钮 running 时变为"取消"按钮,取消会 abort 请求并丢弃后续到达的结果,草稿不动。
- 结果缓存:
同一模型 + 同一生成参数 + 同一草稿命中时直接返回上次已通过保真闸的结果, 省额度、秒回;只缓存合格结果,坏结果绝对不入缓存。cordis.patch.yml的cacheEnabled/cacheMaxEntries/cacheTtlMs可调。
规格与计划文档
Speckit 工作流产出的文档在 specs/001-prompt-optimize-button/:
spec.md 构建什么、为什么构建(含澄清记录与实现阶段修正)
research.md 全部宿主 API 结论及代码出处(含 8 项实现阶段复核)
plan.md 技术方案、宪法检查、结构决策、关键取舍
contracts/ HTTP 路由 / 宿主工具 / UI 槽位 三份接口契约
tasks.md 原子任务分解
checklists/ 规格质量校验License
MIT
