# 使用指南

简体中文 · [English](guide.en.md)

[返回 README](../README.md) · [开发说明](development.md) · [验证记录](verification.md)

适用于提示词增强 0.2.6 与 DSH 0.2.1-rc.3。

## 增强与采用

在普通会话中输入草稿，点击输入框底部、模型选择器左侧的星光按钮。插件按已保存设置增强；处理期间再次点击同一按钮可取消。

| 采用方式 | 完成后发生什么 |
| --- | --- |
| 直接替换草稿 | 输入框直接更新为增强稿，不打开预览或设置弹窗 |
| 先预览，再决定 | 保持原草稿，打开对照预览；点击“替换草稿”后才采用 |

预览默认显示原文和增强稿，窄窗口中上下排列。取消勾选“对照原文”可只看增强稿；展开“实际参考来源”可查看实际使用的来源和片段。必要的来源缺失或裁剪提示会保留显示。

点击“保留原稿”或关闭预览不会修改输入。两种采用方式都不会自动发送聊天消息。

### 恢复原文

采用后，原增强按钮会切换为返回图标。点击它可恢复**本次增强前**的原文，随后按钮恢复为星光图标。

继续编辑、发送、更换附件、会话或有效模型后，旧撤销会失效，避免覆盖新的输入。它不是跨会话的草稿历史功能。

### 不能增强的情况

空草稿、命令草稿、子代理会话和不可编辑输入框不执行增强。插件没有右键、`Shift+F10` 或菜单键快捷菜单；设置统一从 DSH 设置进入。

## 选择合适的设置

打开 **DSH 设置 → 提示词增强**。页面分为增强偏好、参考范围和增强模型。

### 增强方式

- **适度增强**：整理表达、消除歧义和重复，清楚的原稿可能只做少量修改。
- **充分展开**：按问题规模补充必要结构和细节，不强制套用长模板。

两种方式都要求保留原语言、否定条件、数字、路径、代码和引用，不增加新的限制或审批要求；缺失事实标为待补充。明显的中文/拉丁字母语言漂移会被拒绝采用，但这不是完整的语言识别，仍需人工检查结果。

### 参考范围

| 选项 | 适用情况 | 会参考什么 |
| --- | --- | --- |
| 仅草稿 | 当前问题可以独立理解 | 只发送当前草稿 |
| 最近对话 | 草稿承接前面的讨论 | 最近 3 轮已完成的用户与助手正文 |
| 扩展上下文 | 问题需要结合项目和记忆 | 对话、个人及同项目记忆、当前项目片段 |

扩展上下文仅限宿主所有者使用。项目由当前会话所属工作区确定，不能指定任意目录；无项目的会话会显示没有读取项目记忆或文件的原因。

### 增强模型

默认跟随会话中当前选择的模型和推理档位。选择“指定专用模型”后，从 DSH 的可用模型目录选择，并设置该模型支持的推理档位，也可使用“模型默认”。

专用模型不可用时会明确失败，不自动回退到其他模型。推理档位由宿主验证，不自动转换别名或降档。预览采用前会再次检查模型目录和输入状态，过期结果不能覆盖新草稿。

### 保存与迁移

修改后显示“有未保存的修改”，点击“保存设置”生效；“取消”放弃未保存编辑。“刷新模型与设置”会保留尚未保存的编辑。下拉框支持原生键盘操作。

未修改、专用模型不可用或档位无效时不能保存，页面会提示原因。首次默认值为适度增强、直接替换、最近对话、跟随当前模型；升级保留已有设置，旧客户端的增强方式会在首次读取时迁移。

设置管理仅限宿主所有者。非所有者可使用默认最近对话和当前模型。设置文件位于 `$DSH_HOME/plugins/dsh-link-prompt-enhance/settings.json`，只保存这些选择，不保存模型密钥。

0.2.6 的新包名为 `dsh-prompt-improver`，上述设置路径及旧客户端的增强方式存储键有意保持不变，避免升级或回滚时丢失设置；不需要移动或删除这个目录。

## 数据与上下文

草稿及选定范围内的上下文会发送给增强模型，按该模型服务的规则计费。插件不会把背景材料中的指令当作新任务或执行授权。

### 读取范围和上限

以下预算按 UTF-16 字符计数，不等同于模型 Token 数。

| 参考范围 | 上限 |
| --- | --- |
| 仅草稿 | 不读取历史、记忆或项目文件 |
| 最近对话 | 最近 3 轮已完成对话，合计最多 12,000 字符 |
| 扩展上下文 | 对话最多 8,000 字符，记忆最多 4,000 字符，项目片段最多 4,000 字符 |

历史不包含运行中或中断轮次、思考内容、工具结果和附件正文。优先保留最近的完整轮次；最新一轮过长时优先保留用户要求，避免只留下助手回答。

历史读取失败会停止请求，可切换到“仅草稿”重新增强。记忆或项目内容缺失、失败、超时、被裁剪时会提示，并列入预览。记忆依赖可选的 memory 服务，插件不直接读写其存储。

项目检索遵守忽略规则，排除隐藏目录、凭据、依赖、缓存、构建产物和非文本文件；拒绝符号链接及目录联接，不跟随到项目外。最多检查 300 个文本文件，每文件至多 128 KB，检索超时 5 秒；最终最多采用 5 个文件、4,000 字符的片段。受到上限影响时会提示裁剪。

### 引用、附件与超时

结构化 `@引用` 的身份保留在客户端，发出前替换为随机占位符，返回后校验并恢复。引用丢失、重复或损坏时拒绝采用。附件身份保持不变，不为增强上传附件正文。

一次增强只有一次无工具辅助调用，不进入智能体执行循环、不新增聊天消息。模型适配器内部的网络重试由宿主管理；默认总超时为 120 秒，记忆召回至多 3 秒。

## 安装与回滚

### 准备

需要 DSH 0.2.1-rc.3，并能访问 GitHub 和 npm 依赖源。[v0.2.6 Release](https://github.com/Yocaihua8/dsh-prompt-improver/releases/tag/v0.2.6) 提供 `.tgz` 安装包和 `SHA256SUMS`。也可通过 DSH 从 GitHub 标签安装；两种方式均包含预构建的 `lib`，无需安装开发工具。修改源码和重新构建前请阅读[工作区前提](development.md#工作区前提)。

升级前，备份旧插件安装包、插件设置，以及 desktop profile 的 `package.json`、`pnpm-lock.yaml`、`pnpm-workspace.yaml`、`cordis.yml` 和 `cordis.patch.yml`。记录备份对应的插件和宿主版本，保留旧包原路径。

### 从 GitHub 安装

如果已经安装旧包 `dsh-link-prompt-enhance`，先完成下方[改名迁移](#从旧包名迁移)，不要同时加载两个包。

等待当前任务结束，从应用正常退出 DSH，并确认相关进程已经退出。使用 Desktop 自带的 CLI，替换下面的占位路径后执行：

```powershell
$dshCli = '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd'
& $dshCli plugin --profile desktop add 'github:Yocaihua8/dsh-prompt-improver#v0.2.6'
```

Desktop 自带 CLI 支持该保留 profile 的插件访问；不能假定另一套系统 CLI 具有同样能力。独立 CLI 使用已有的 Web profile（需包含工作区和会话服务；新建空 profile 不足以运行本插件）：

```powershell
dsh plugin --profile <你的配置名称> add 'github:Yocaihua8/dsh-prompt-improver#v0.2.6'
```

以上固定安装 0.2.6。需要测试默认分支时可去掉 `#v0.2.6`；也可改为 `#<完整提交 SHA>`。更新时重新执行添加命令，并按当时 README 核对宿主兼容版本。Release 自动生成的 Source code ZIP 用于源码开发，不是插件安装包；安装请下载 Assets 中的 `.tgz` 或使用上述命令。

重新启动后，在专用测试会话检查增强按钮、设置页、预览和恢复原文，再次重启确认设置保留。使用无敏感内容的草稿，检查其他插件和原有数据是否正常。

### 安装 Release 安装包

下载 Release 中的 `dsh-prompt-improver-0.2.6.tgz` 和 `SHA256SUMS`，先核对校验值，再按同样的备份和退出步骤安装：

```powershell
$pluginPackage = '<安装包目录>\dsh-prompt-improver-0.2.6.tgz'
Get-FileHash -Algorithm SHA256 $pluginPackage
# 将 Hash 与 SHA256SUMS 中该文件对应的值核对一致后再安装
& $dshCli plugin --profile desktop add $pluginPackage
```

不要用新包覆盖已经安装的同路径 `.tgz`。安装后按上述步骤检查界面和设置。

### 从旧包名迁移

0.2.5 及更早版本使用 `dsh-link-prompt-enhance`；0.2.6 起使用 `dsh-prompt-improver`。这是安装包身份变更，重新添加新包不会自动移除旧包。先按“准备”一节备份并退出 DSH，再使用同一 CLI、同一 profile 执行：

```powershell
$dshCli = '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd'
& $dshCli plugin --profile desktop remove dsh-link-prompt-enhance
if ($LASTEXITCODE -ne 0) { throw '旧包移除失败，请检查输出后再继续。' }
& $dshCli plugin --profile desktop add 'github:Yocaihua8/dsh-prompt-improver#v0.2.6'
if ($LASTEXITCODE -ne 0) { throw '新包安装失败，请恢复备份的旧安装包后再启动 DSH。' }
```

独立 CLI 用户替换为实际 Web profile。使用下载的安装包时，将第二条命令的 GitHub 来源替换为 `dsh-prompt-improver-0.2.6.tgz` 的路径。

如果曾在 home 或 profile 的 `cordis.patch.yml` 手动配置本插件，或通过市场保存了本插件的启停覆盖，检查其中指向旧插件的 `id` / `name` / `target`：把对应的 `dsh-link-prompt-enhance` 改为 `dsh-prompt-improver`，保留原 `disabled` 和 `config` 内容。只处理本插件的引用；没有这些条目就无需修改。不要批量替换设置存储路径。

重新启动后检查只出现一个增强按钮和一个设置入口，原增强方式、参考范围及专用模型选择仍在。若安装失败，恢复备份中的旧包；两个包不要同时启用。

### 回滚

先正常退出 DSH。若回滚到 0.2.5 或更早版本，先移除新包，再用同一 Desktop CLI 添加对应的旧安装包：

```powershell
$previousPackage = '<备份目录>\<对应版本的旧插件包>.tgz'
& $dshCli plugin --profile desktop remove dsh-prompt-improver
if ($LASTEXITCODE -ne 0) { throw '新包移除失败，请检查输出后再继续。' }
& $dshCli plugin --profile desktop add $previousPackage
```

如果迁移时修改了本插件的 Cordis 覆盖项，回滚时将这些引用恢复为旧包名，保留其配置及启停状态。回滚到仍叫 `dsh-prompt-improver` 的版本时，无需先移除，直接添加对应包即可。

若先前从 GitHub 安装，也可添加保留了完整 `lib` 的已验证旧提交：`& $dshCli plugin --profile desktop add 'github:Yocaihua8/dsh-prompt-improver#<旧提交 SHA>'`。本次加入预构建产物之前的提交不具备这一直接安装条件。

如果需要恢复备份的 profile 配置与锁文件，先确认其中的其他依赖变更也需要撤销，再执行 `plugin --profile desktop install --frozen-lockfile`。仅在设置发生变化且确需回退时恢复对应插件设置。

不要恢复整个 DSH_HOME，也不要覆盖新增会话、附件、记忆或用量数据。回滚包仍须兼容当前宿主；旧版本曾经运行过，不代表它可以在当前宿主加载。各次历史安装的路径和结果见[验证记录](verification.md)。

## 常见问题

| 问题 | 处理方式 |
| --- | --- |
| 为什么增强后没有弹窗？ | 默认采用方式是直接替换；需要比较结果时改为“先预览，再决定” |
| 为什么增强前后变化很少？ | 适度增强允许保留已经清楚的表达；需要结构和细节时可尝试充分展开 |
| 为什么没有读取记忆或项目？ | 检查参考范围、所有者权限、可选记忆服务和会话工作区；以实际来源提示为准 |
| 为什么不能保存模型设置？ | 所选模型或推理档位可能已不可用；刷新目录后重新选择 |
| 为什么不能恢复上一次原文？ | 编辑、发送或切换附件、会话、有效模型后，旧撤销会失效 |
| 为什么增强失败或结果没被采用？ | 按错误提示检查历史读取、模型可用性、超时、引用完整性，以及输入是否已变化 |

仍有问题时，可提交 [Issue](https://github.com/Yocaihua8/dsh-prompt-improver/issues)，提供插件及 DSH 版本、复现步骤、脱敏后的错误或截图。不要附密钥、个人会话和未脱敏日志。