prompt-polish

Readme

# ✨ prompt-polish — dsh 提示词优化助手

> A [dsh](https://github.com/deepseek-ai/deepseek-harness) plugin that polishes, completes and expands your prompt **before you send it**, using a dedicated prompt-engineering agent. Supports rewrite, multi-round rewriting and undo. Loads automatically when the harness starts — no per-session setup.

在输入命令之前，调用一个专门的「提示词工程专家」agent，对你的原始草稿进行**补全、消歧、扩写、结构化**，使其符合提示词工程规范、效力更高。插件随 harness 启动自动加载并持久生效，无需每次手动启用。

## ✨ 功能特性

- **一键润色**：侧边栏底部「✨ 润色」按钮（排在「📋 日志」上方），专门的 agent 立即改写你的草稿：
  - 补全缺失要素（目标、对象、范围、约束、输出格式、验收标准）
  - 消除歧义，把含糊表述改写为明确指令
  - 按提示词工程最佳实践组织结构（角色 / 任务 / 步骤 / 输出格式 / 质量约束）
  - 保持原始意图与语言，只输出优化后的命令正文
- **自动写入输入框**：润色完成后结果直接填入输入框，可直接回车发送
- **重写 / 多轮改写**：面板内可再优化一轮（🔄），或自动迭代 3 轮（⏩），每轮结果都进入历史
- **撤回 / 版本回溯**：逐步回退上一版本（↩），或点击版本标签（原文 / v1 / v2…）跳回任意历史版本
- **手动微调**：面板内结果可自由编辑后再应用
- **应用并发送**：一步完成「写入输入框 + 直接发送」
- **内置日志系统**：侧边栏底部「📋 日志」按钮打开浮层面板，host/client 双侧诊断日志 + 健康状态（接口状态、模型路由、最近错误），问题可自排查
- **自定义 API 配置**：支持配置任意 OpenAI 兼容 API（OpenAI / DeepSeek / Azure OpenAI / Ollama / vLLM / LM Studio 等），自定义 API 地址、密钥、模型名，不再绑定 dsh 内置模型路由
- **零构建**：client 端为手写 `window.__ModuleLoader__` bundle，无需任何构建工具链

## 🧩 工作原理

```
┌───────────────────────────── 浏览器 ─────────────────────────────┐
│ sidebar.footer.action        「✨ 润色」按钮（上）、「📋 日志」按钮（下）  │
│ conversation.input.dock      优化面板（版本历史/撤回/重写/应用）    │
│ sidebar.footer.action        「📋 日志」按钮                       │
│ shell.overlay                日志浮层                              │
│         │  fetch (同源)                                           │
└─────────┼────────────────────────────────────────────────────────┘
          ▼
┌───────────────────────────── Host ──────────────────────────────┐
│ POST /pp-api/polish   调用 llm.stream 跑「提示词优化专家」agent    │
│                       模型路由：agentDefaultModel 当前默认选择     │
│                       （如 opencode-go / deepseek-v4-flash）      │
│ POST /pp-api/config   保存/读取自定义 API 配置（OpenAI 兼容）      │
│ GET  /pp-api/config   返回当前配置（apiKey 脱敏）                  │
│ GET  /pp-api/logs     返回日志缓冲 + 健康诊断                      │
└──────────────────────────────────────────────────────────────────┘
```

- **Host 半**（`index.js`）：普通 Cordis 插件，通过 `webServer.register` 暴露两个同源 HTTP 接口（避开 `/api` 前缀）；`llm.stream` 调用支持多轮迭代（每轮基于上一轮结果），带 120s 超时保护。
- **Client 半**（`client.js`）：手写 `window.__ModuleLoader__.load({ id, factory })` 格式的浏览器 bundle（与 dsh 产品级 client 插件同构），通过 `package.json` 的 `dsh.client` 声明被 `dsh-client-modules` 扫描并 serve（`/plugins/prompt-polish/client.js`），无需构建。
- **持久化**：插件自带 `dsh.bundle` 声明（`cordis.patch.yml`），`dsh plugin add` 后自动注册为 profile 组合中的一行，harness 启动即挂载；区别于动态 Cordis 插件，重启后依然存在。

## 📦 安装

### 环境要求

- dsh（DeepSeek Harness）**web 模式**（`dsh --profile web`）≥ 0.1.1-rc.2
- Node.js（dsh 运行环境自带）
- 一个可用的 LLM 模型路由（插件自动使用你在 dsh 中配置的**默认模型**，无需单独配置）

### 一键安装（推荐）

插件自带 `dsh.bundle` 声明（`cordis.patch.yml`），`dsh plugin add` 会自动安装并把 host 半注册进 profile 组合，**无需手动编辑任何配置文件**：

```bash
dsh plugin --profile web add github:JOJO666888888/prompt-polish
```

安装完成后重启 dsh 并刷新浏览器即可：

1. 重启 dsh（`dsh --profile web`）
2. 浏览器 **Ctrl + Shift + R** 硬刷新页面

完成后：侧边栏底部出现「✨ 润色」和「📋 日志」两个按钮（润色在上）。

> **原理**：`dsh plugin add` 把参数转发给 pnpm（`github:user/repo` 是 pnpm 原生 spec），pnpm 拉取仓库并装进 profile 的 `node_modules`；随后 dsh 检测到本包声明了 `dsh.bundle.patch`，自动把它加入 `dsh.profile.bundles` 层栈。下次启动时，profile 加载本包的 `cordis.patch.yml` 插入 host 插件行（`/pp-api/*` 路由 + 提示词 agent），同时本包的 `dsh.client` 声明让浏览器半（`client.js`）被自动编排进启动图。

### 本地开发安装

开发时直接用本地路径，改完代码 `dsh plugin --profile web add ~/prompt-polish` 即可热更新（也可指向 `.`，dsh 会锚定到调用目录）：

```bash
dsh plugin --profile web add ~/prompt-polish
# 或在仓库目录内：
dsh plugin --profile web add .
```

### 验证安装

```bash
# 已加入 profile 的 bundle 层栈（看到 prompt-polish 即成功）
node -p "require(process.env.HOME+'/.dsh/profiles/web/package.json').dsh.profile.bundles"
# 或查看 profile 依赖来源
grep prompt-polish ~/.dsh/profiles/web/package.json
# 接口自检（把端口换成你 dsh web 实际监听的端口）
curl -s http://127.0.0.1:3080/pp-api/config
```

## 🚀 使用

1. 在输入框输入草稿（哪怕不完整，例如「优化一下我的代码」）
2. 点击侧边栏底部的 **「✨ 润色」**（输入为空时按钮自动禁用）
3. 等待约 20~30 秒（模型调用中，输入框上方面板显示「⏳ 优化中…」）
4. 完成后：
   - 输入框**自动填入**润色后的完整提示词，可直接回车发送
   - 优化面板保留：**↩ 撤回**、**🔄 重写**、**⏩ 多轮改写 ×3**、**✓ 应用到输入框**、**✈ 应用并发送**
   - 点击版本标签（原文 / v1 / v2…）可跳回任意历史版本

### 日志与排障

点击侧边栏底部 **「📋 日志」**（或优化面板头部的 📋 按钮）打开日志面板：

- 合并显示 host / client 双侧日志（按时间倒序，错误红色高亮）
- 健康状态区：接口状态、成功/失败计数、默认模型、LLM providers、自定义 API 状态、最近错误
- 「🔄 刷新」重新拉取 host 日志，「🗑 清空」清空 client 侧记录

### ⚙️ 自定义 API 配置

有两种方式配置自定义 API：

**方式一：dsh 设置面板（推荐）**

打开侧边栏的 **⚙️ 设置** → 左侧导航找到 **「✨ 提示词优化」** 分区，直接配置 API 参数。配置保存在 `~/.dsh/plugins/prompt-polish.json`，保存后立即生效，无需重启。

设置面板内提供快速预设按钮（OpenAI / DeepSeek / Ollama / vLLM / LM Studio 等），一键填入对应的 API 地址和模型名。

**方式二：润色面板内快捷设置**

点击优化面板头部的 **「⚙️ 设置」** 按钮，可在润色时快速修改配置（同样引导至设置面板）。

**配置字段说明**：

| 字段 | 说明 | 示例 |
| --- | --- | --- |
| 启用 | 开关：启用自定义 API / 回退到 dsh 内置路由 | ✅ 已启用自定义 API |
| API 地址 | OpenAI 兼容 API 的 base URL（自动拼接 `/chat/completions`） | `https://api.openai.com/v1` |
| API Key | Bearer Token 认证密钥（Ollama 等本地服务可留空） | `sk-...` |
| 模型名称 | 模型 ID | `gpt-4o`、`deepseek-chat`、`llama3.1` |
| 最大 Tokens | 输出上限 | `8192` |

**常见 API 配置示例**：

| 服务 | API 地址 | 模型名称 |
| --- | --- | --- |
| OpenAI | `https://api.openai.com/v1` | `gpt-4o` / `gpt-4o-mini` |
| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` / `deepseek-reasoner` |
| Azure OpenAI | `https://{resource}.openai.azure.com/openai/deployments/{deployment}` | `{deployment-name}` |
| Ollama (本地) | `http://localhost:11434/v1` | `llama3.1` / `qwen2.5` |
| vLLM (本地) | `http://localhost:8000/v1` | `{model-id}` |
| LM Studio | `http://localhost:1234/v1` | `{loaded-model}` |

操作按钮：
- **💾 保存配置**：保存到 `~/.dsh/plugins/prompt-polish.json`，立即生效，无需重启
- **🧪 保存并测试**：保存后自动用一段测试文本触发润色，验证 API 是否可用

> 配置文件路径：`~/.dsh/plugins/prompt-polish.json`
>
> 未启用自定义 API 时，插件自动回退到 dsh 内置模型路由（`agentDefaultModel`），完全向后兼容。

常见问题：

| 现象 | 原因 / 处理 |
| --- | --- |
| 没有「✨ 润色」按钮 | 未刷新浏览器（Ctrl+Shift+R）；或未加入 bundle 层栈（运行 `dsh plugin --profile web add github:JOJO666888888/prompt-polish` 后重启 dsh） |
| 按钮置灰不可点 | 输入框为空 |
| 点击后无反应 | 打开日志面板查看错误；确认 `/pp-api/polish` 接口可访问（见下） |
| 提示「无法解析可用的模型路由」 | dsh 未配置默认模型，在 Models 设置页选择模型后重试；或启用自定义 API 配置 |
| 自定义 API 报错 HTTP 401/403 | API Key 不正确，检查设置面板中的密钥 |
| 自定义 API 报错 HTTP 404 | API 地址或模型名称不正确，确认 base URL 和 model ID |
| 自定义 API 连接超时 | 检查 API 地址是否可达、网络代理设置、防火墙 |

接口自检（把 `:3080` 换成你 dsh web 实际监听的端口，可用 `dsh --profile web --help` 或 webserver 配置查看）：

```bash
curl -X POST http://127.0.0.1:3080/pp-api/polish -H "content-type: application/json" -d "{}"
# 期望返回 500 + {"error":"prompt-polish: 输入文本为空"}（说明接口已注册）
curl http://127.0.0.1:3080/pp-api/logs
# 期望返回 {"logs":[...],"health":{...}}
curl http://127.0.0.1:3080/pp-api/config
# 期望返回 {"customApi":{"enabled":false,"baseUrl":"https://api.openai.com/v1","apiKey":"","hasApiKey":false,"model":"gpt-4o","maxTokens":8192}}
```

## 🗑 卸载

```bash
dsh plugin --profile web remove prompt-polish
```

这会从 profile 依赖和 `dsh.profile.bundles` 层栈中一并移除（dsh 自动 reconcile），重启 dsh 即彻底卸载。自定义 API 配置残留在 `~/.dsh/plugins/prompt-polish.json`，需要时可手动删除。

## ⚙️ 模型路由

插件优先使用 `agentDefaultModel`（dsh 的默认模型选择，即 Models 设置页/`$DSH_HOME/settings.yaml` 中 `agent-default-model` 配置）；若不可用则回退到第一个已注册 provider 的首个模型。每次请求读取，无需重启。

## 📄 许可证

[MIT](./LICENSE)

---

*本项目与 DeepSeek 官方无关联，是 dsh 生态的社区插件。*