dsh-plugin-structured-prompt

dsh-plugin-structured-prompt

把 DSH 输入框切换成结构化提示词表单的插件，并接一个公开提示词库的检索入口。

在输入框底部的「结构化输入任务」，点开即弹出结构化提示词表单。填完后可以点「复制」把成稿取走，或点「发送」把它作为普通用户消息直接投递进当前会话 —— 没有「同步回输入框再编辑」这一步。旁边的「提示词库」按钮检索 prompts.chat 上的公开提示词，选中后预览原文、直接发送：这条路径不经过构建器（检索到的是别人的成品文本，不做字段校验）。

dsh plugin --profile desktop add github:YuChenLiao/dsh-plugin-structured-prompt
# 重启 DSH 生效（客户端插件的模块图在启动时建立）

仓库已包含构建好的 lib/，装完即可用；想改源码看下方[开发](#开发)。

定位说明

本插件是提示词构建器：DSH 的系统提示由主机每步组装，客户端插件没有「仅对单次对话注入 system prompt」的接口，因此产出的提示词以普通用户消息的形式投递进当前会话（或复制到剪贴板由你自行处置）。

同一个构建器还以工具的形式暴露给模型（见下节），因此"人来填表单"和"模型自己构建"得到的提示词是同一份实现、同一份产物。

本插件有两条产出路径，边界是 v0.3.0 定下的：表单与工具走构建器（同一份实现、同一份产物，产物由 tests/golden/ 的 25 条样本逐字锁住）；提示词库检索走旁路 —— 检索到的是别人写好的成品文本，不做字段校验、不进构建器，只被预览与发送。两条路径共用同一条发送链路（会话作用域的 conversation.send），产物互不干涉。

功能

• 输入框底部入口：入口按钮在输入框工具栏里（conversation.input.left，与计划/权限控件同一行），点开弹出表单。
• 弹窗表单：宽度固定（clamp(600px, 74vw, 900px)），高度由内容决定、最多占窗口 70%（max-height: 70vh）——不会占满屏幕；内容超出上限时在弹窗右侧出现滚动条（内容区需要 overflow-y: auto + flex: 1 1 auto + min-height: 0 才能正确收缩，scrollbar-gutter: stable 避免内容增减时左右跳动）。
• 弹窗分三段：标题栏（标题 + 必填提示 + 关闭）/ 可滚动内容区（套用模板时的场景条 + 四个分组）/ 底部操作栏（模板、导入、导出、清空在左，复制与发送在右）。滚轮只作用于内容区，标题栏与底部操作栏常驻。
• 复制：把构建好的提示词放进剪贴板（优先 navigator.clipboard，非安全上下文时降级到 execCommand('copy')），结果在按钮旁短暂提示。
• 发送：把成稿直接投递进当前会话（走会话作用域的 conversation.send(text)，消息正文就是成稿），发送后弹窗自动关闭。
• 点遮罩不关闭：遮罩不绑定点击处理器，避免误触丢失已填内容；关闭只经由标题栏的 × 或 Esc。
• 分组不裁剪内容：分组只用「标题 + 分隔线」，不用卡片包裹。卡片带来 overflow: hidden，会把需要更多高度的字段裁掉、也截断外层滚动——这正是"表单项展示不全"的根因。任何层级都不设 max-height 去限制字段。
• min-height: 0 只属于滚动容器：分组容器不写 min-height，保留默认的 min-height: auto 让它按内容撑高；若误写在分组上，分组会被压缩到内容高度以下、子元素互相压叠（症状是分组标题与上一个字段的输入框重叠）。这条与上一条一样由渲染测试直接断言。
• 表单字段不限高：多行文本域不写死行数，高度随内容自适应（field-sizing: content，不支持的浏览器由首挂载与 onChange 时的 JS 兜底）。
• 四组、默认只展开基础信息：基础信息展开，约束与规则 / 工具策略 / 输出与兜底默认折叠，展开哪组只看哪组。
• 工具策略自动或手动：
• 自动：交给模型自行判断，提示词里只写一句「由你根据任务需要自行判断并选择要调用的工具；不需要工具时直接回答。」
• 手动：由你直接填写要允许调用的工具名（可加一行用途），提示词生成「只允许调用下列已指定的工具，其余工具一律不要使用」+ 逐行清单。工具名与用途按原始索引配对：用途可留空（只写工具名），工具名留空的行整体忽略。
• 刻意不提供「从已安装清单里勾选」：DSH 的插件清单列的是自带插件而非用户安装的插件，skills 清单也不属于本插件的职责；工具检索在输入框的 / 菜单里。本插件因此不读 remote.、也不读插件与 skills 清单，inject 只有 slots（唯一触到主机的动作是发送链路：会话作用域上的 conversation.send）。
• 填完即走：要么点「复制」把成稿拿去别处用，要么点「发送」直接投递进当前会话。没有中间态。
• 实时预览与预算：表单底部可展开查看完整提示词；折叠标题给出字数与估算 token，展开后列出逐段占用（哪一段最吃上下文），便于发送前判断会不会太长。token 是估算（CJK 每字 1、其余每 4 字符 1），只用于判断量级。
• 模板与导入导出：内置八套模板 —— 4 套任务形态（探索调研、实现改动、故障定位、交接归档）与 4 套领域样例（告警研判（原始示例）、代码审查、数据提取、报告撰写）。模板数据是 src/shared/templates.json：表单下拉、工具的 template 枚举、黄金样本都从它取值，改模板不必碰代码。下拉选项里带每套模板的一句话场景；套用后表单顶部出现一条场景条，提醒把本次的具体任务写进「目标」—— 模板带的是形态化目标，不复述具体任务时产物会变泛。场景条是界面陈述：它由 store 里的 appliedTemplate 驱动，不参与提示词构建（成稿只由表单字段决定，改这个标记不会改产物一个字节）。同一会话内手改字段与关闭重开都不会清掉它，只有「清空」与「导入」会清本会话的标记 —— 注意表单状态本就按会话独立（store 实例按会话分开），切到别的会话看到的是那个会话自己的表单，自然也没有这条场景条；记的 id 解析不到时（例如来自已删除的模板）整条不渲染 —— 界面不声称一个说不出来源的来源。表单可导出为 JSON、从 JSON 导入，便于跨会话复用。导出文档带 schema 版本号；导入时只接受已知字段并逐字段校验形状 —— 未知键、类型不符、越界枚举会被丢弃并在界面上说明，旧版无版本号的文件仍可读。
• 提示词库检索（prompts.chat）：输入框底部第二个入口，「检索 → 预览 → 发送」。这条路径不经过构建器：检索到的是别人写好的成品文本，既不做字段校验、也不填进表单，发送的就是那段原文（界面写明「未经本插件整理」，按钮文案是「发送原始提示词」）。检索只按标题匹配；选中一条后再单独取全文，所以列表页不会把一屏全文带进来。留空查询则列出上游最新的一批 —— 注意那条路径走的是上游的列表端点，它每条都带全文，宿主取回后立即丢弃（只留标题、描述、作者与 id），因此那次响应本身并不小。发送走的是与表单成稿同一条链路（会话作用域的 conversation.send）。
• 提示词库的请求由宿主代发：上游不返回 CORS 头（预检返 204 却不回 Access-Control-Allow-Origin），浏览器直连会被拒。所以浏览器请求的是宿主注册的两条同源路由 —— /api/structured-prompt/library（检索）与 /api/structured-prompt/library/item（取全文），由宿主用全局 fetch 去取上游。副作用是好的：上游地址成了宿主侧配置（config.libraryBaseUrl，缺省 https://prompts.chat），要指向自托管实例只改配置、插件代码不动。三条边界由断言守着：基础地址只来自配置（不接受请求参数，否则这条路由就是任意 URL 代理）、记录 id 先校验再拼进上游路径（挡路径注入）、不向上游转发任何浏览器请求头。上游失败被归一成可读说明而不是把异常抛给浏览器：超时 → 504，网络错 → 502，上游 404 → 404（「记录没了」，只有取全文那条路会这样判），其余非 2xx → 502。
• 跟随主题：颜色与阴影全部走 DSH 主题 token（--dsw-alias-*、--dsw-elevation-prominent），深浅色主题自动切换。

表单项（17 项）

| 组 | 字段 | 必填 |

| --- | --- | --- |

| 基础信息 | 身份 / 目标 | 是 |

| 基础信息 | 背景与上下文 / 成功标准 | 否 |

| 约束与规则 | 硬性规则（逐条增删改序）/ 禁止行为（逐条） | 否 |

| 工具策略 | 调用工具策略（自动 / 手动 / 不指定） | 否 |

| 工具策略 | 可调用的工具（手动时：工具名 + 用途，配对填写） | 否 |

| 工具策略 | 工具使用策略（逐条）/ 工具失败时的处理 | 否 |

| 输出与兜底 | 输出格式类型（JSON / Markdown / 表格 / 纯文本） | 否 |

| 输出与兜底 | 输出格式说明 / 字段级说明（逐条）/ 语言与语气 | 否 |

| 输出与兜底 | 数据不足时的行为 / 少样本示例 | 否 |

生成的提示词结构

段落顺序与格式与插件自带的原始实现一致，扩写字段都并入既有段落，没有新增顶层段落：

# 身份                     ← 身份 + 背景与上下文
# 目标                     ← 目标 + 完成标准
# 硬性规则（必须遵守，优先于其他任何要求）   ← 逐条编号 + 禁止行为子块
# 工具使用策略             ← 策略引导语（自动）/ 点名工具清单（手动）+ 逐条策略 + 工具失败时
# 输出格式                 ← 格式说明（自定义优先，否则用所选格式的骨架）+ 字段说明 + 表达要求
# 数据不足时
# 示例

空段落整体省略，非空段落之间以单个空行连接。

「格式说明」是自定义优先、否则由格式类型生成骨架的二选一 —— 说明字段才是最终契约，

格式类型只是帮它填骨架。选格式类型时 applyFormatChoice 会同步更新说明里的骨架部分：

说明为空就整段填入；已在某套骨架基础上追加过内容就只换骨架、保留追加；完全手写的

说明不动。当说明与所选格式类型完全无关时（例如手写了一段 TOML 契约），界面会明确提示

「格式类型已不生效」，避免高亮的格式类型与实际产物静默分叉。这条规则由

tests/test-prompt.mjs 逐状态覆盖。

模型可调用的工具

host 半边注册一个工具 build_structured_prompt，让模型自己把模糊的委托变成精确提示词：

模型 → build_structured_prompt({ role, goal, rules: [...], output_format: 'json' })
     → 返回构建好的提示词
     → 模型把它作为 subagent 工具的 prompt 参数（或写进文件、用在自己身上）

模型 → build_structured_prompt({ role, goal, delegate: { label: 'review' } })
     → 构建后**直接投给子代理**（前台运行、收集结果、释放运行）
     → 提示词不进入主上下文，只回传子代理的输出
    → ⚠ 当前 DSH 版本不可用：`subagents.start` 未暴露给插件（见下文「delegate 走可选服务」）

| 项 | 说明 |

| --- | --- |

| 必填 | role（身份）、goal（目标）—— 与表单同一条规则；用 template 时这两项可以省略，内置模板都带它们 |

| 可选 | 表单其余字段（background / rules / forbidden / tool_policy / output_format / fallback …） |