# @hyzyn/dsh-prompt

中文 | [English](README.en.md)

> DSH 的「Prompt 管理」卡片：可视化编辑 systemPrompt，带版本管理与 A/B 测试。配置存在 `~/.dsh/prompts.yml`（可用 `DSH_PROMPT_FILE` 覆盖）。

## 特性

- **Prompt 与版本两级模型**：一个 Prompt 存多份版本，存为新版本 / 回滚各一步，旧版本完整保留。
- **A/B 按比例随机分流**：按比例命中 A/B 版本，用真实流量验证提示词改动。
- **启用即作为 systemPrompt section 注入**：选中即注入，保存即热生效。
- **可导出、可导入**：导出 `json` / `markdown`，导入 JSON，亦可一键复制分享。

![Prompt 管理卡片：可视化编辑 / 版本管理 / A/B 测试](https://cdn.jsdelivr.net/gh/hyzyn/dsh-plugin-kit@main/docs/dsh-plugin-kit-prompt.png)

## 路由

仅限 loopback + 同源访问：

- `GET /api/dsh-prompt/list` —— 列出全部 Prompt 与激活状态
- `POST /api/dsh-prompt/save` —— 新建 / 整体保存 Prompt
- `POST /api/dsh-prompt/activate` —— 启用某个 Prompt（可指定激活版本；`promptId` 为空表示停用）
- `POST /api/dsh-prompt/abtest` —— 配置 A/B 测试
- `POST /api/dsh-prompt/delete` —— 删除 Prompt
- `GET /api/dsh-prompt/active` —— 查看当前注入 systemPrompt 的文本与命中版本
- `GET /api/dsh-prompt/export?format=json|markdown&promptId=...` —— 导出
- `POST /api/dsh-prompt/import` —— 导入 JSON

## 安装

```bash
pnpm --filter @hyzyn/dsh-prompt build
dsh plugin --profile web add link:$(pwd)/packages/prompt
```

插件自身行由 `cordis.patch.yml` 的 `insert: { id: prompt-manager, name: '@hyzyn/dsh-prompt' }` 挂载；保存 Prompt 后宿主会立即刷新 systemPrompt section，无需重启。

## 配置

设置面在宿主里的位置随 DSH 版本变，但**始终是同一份表单**——各代际的落点与四条注册契约的唯一归宿在
[conventions.md § 客户端设置面](../../docs/conventions.md#客户端设置面内联优先)。

```ts
interface Config {
  /** 关闭整个插件。默认 false。 */
  enabled?: boolean
  /** 是否向 agent 注入插件能力公告。默认 true。 */
  announceToAgent?: boolean
  /** 是否把启用的 Prompt 注入 systemPrompt。默认 true。 */
  applyToSystemPrompt?: boolean
}
```

## 说明

- 托管区块以 `# --- dsh-prompt-manager managed ...` 标记，插件只改写该区块，其余内容原样保留。
- 每个 Prompt 至少需要一个版本；版本内容最大 500KB。
- 注入另有**每轮上限**：启用的 Prompt 正文每轮只注入前 8000 字符，注入文本里会注明「完整内容请在设置 → 插件配置 → Prompt 管理 里查看」。这是每轮请求成本的保护，不是保存限制——版本内容仍可存到 500KB；保存响应在正文超过每轮上限时带 `warning` 字段，卡片可据此提示。
- A/B 测试的随机选择发生在 systemPrompt 刷新时（保存/启用/启动），适合快速对比不同 system prompt 文案；如需按会话粒度分流，可在上层接入实验平台。
- 浏览器半体依赖核心 `slots` 服务，只有 `dsh-web-app` 的官方设置面板才提供该插槽。