dsh-one-click-polish 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-one-click-polish contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,292 @@
-# Temporary Holding Version
+# 一键润色 / 扩写 / 自动驾驶
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 DeepSeek Harness（dsh）桌面端的输入框加一组动作：**润色**、**扩写**、**自动驾驶**。所有模型调用都用**你当前会话正在用的那个模型**，结果直接写回输入框。
+
+- 润色：按三档深度重写草稿
+- 扩写：把一句话扩写成能直接开工的需求说明
+- 自动驾驶：让 AI 读对话、写下一步提示词、发给助手，一轮接一轮推进到你设定的目标
+
+装好之后，输入框左下角多一排按钮：
+
+```
+[+ 完全权限]  润色   深度   扩写   自动
+```
+
+---
+
+## 需要什么
+
+| 项 | 要求 |
+| --- | --- |
+| dsh | 桌面端（Web UI），带 `settings.section` / `conversation.input.left` 槽位 |
+| Node | ≥ 20 |
+| 模型 | 会话里能正常发消息即可；润色用的就是这个模型 |
+
+没有额外依赖，不需要 API key——插件借的是 dsh 已经配好的模型通道。
+
+## 安装
+
+### 界面里装（最省事）
+
+打开 dsh → 设置 → 插件 → 添加插件，在输入框里粘这个：
+
+```
+https://github.com/HTRP1486/dsh-one-click-polish
+```
+
+下面这些写法等价，都行：
+
+```
+https://github.com/HTRP1486/dsh-one-click-polish
+https://github.com/HTRP1486/dsh-one-click-polish.git
+github:HTRP1486/dsh-one-click-polish
+```
+
+**末尾不要加斜杠**。加了会报 `a URL must point at a git repository or a tarball` —— dsh 的判断规则是 `^https?://主机/用户/仓库(.git)?$`，最后一段不允许出现 `/`。
+
+### 命令行装
+
+```bash
+dsh plugin --profile <你的 profile 名> install github:HTRP1486/dsh-one-click-polish
+```
+
+不知道 profile 名的话，看你 `~/.dsh/profiles/` 下的目录名，常见的是 `desktop`。
+
+### 其他方式
+
+| 方式 | 做法 |
+| --- | --- |
+| 本地目录 | target 填仓库的**绝对路径**，如 `D:\Documents\dsh-one-click-polish`（相对路径会被拒绝） |
+| Release 包 | 从 [Releases](https://github.com/HTRP1486/dsh-one-click-polish/releases) 下 `.tgz`，target 填该文件的绝对路径 |
+
+装完**重启 dsh**。判断是否成功：输入框左下角出现 `润色 | 深度 | 扩写 | 自动`，设置里多出「润色 / 扩写」一页。
+
+### 装不上时
+
+| 报错 | 原因 |
+| --- | --- |
+| `a URL must point at a git repository or a tarball` | 地址末尾多了斜杠，或不是 `.tgz` 结尾 |
+| `a local path must be absolute` | 填了相对路径或 `./xxx` |
+| `unmet DSH version requirement` | 你的 dsh 版本低于插件要求 |
+| 装完没生效 | 没重启。改 profile 的 bundles 后必须重启，刷新页面不够 |
+
+## 用法
+
+### 润色
+
+打字 → 点 `润色` → 草稿被重写并写回。
+
+档位胶囊点一下循环 `轻度 → 标准 → 深度`（默认深度，记在浏览器本地）。它决定**动手前查多少资料**：
+
+| 档位 | 动手前 | 改写力度 |
+| --- | --- | --- |
+| 轻度 | 什么都不查 | 只改错别字、标点、语法 |
+| 标准 | AI 翻项目目录和 dsh 配置目录，找相关文件 | 改措辞和句式、去冗余 |
+| 深度 | 标准 + 联网检索（必应 / 百度 / GitHub） | 重组结构、拆长句、换精准用词 |
+
+检索不是关键词匹配：Host 把 `list_dir` / `read_file` / `search_files` / `search_content` / `web_search` 交给模型，由它自己决定查什么、要不要再追一轮。轮数、检索时长、改写时长都能在设置里调，默认 4 轮 / 45 秒 / 120 秒。**只读**，越出项目目录与 dsh 配置目录的路径会被拒绝。
+
+改动前后可以对比：草稿被覆盖，`Ctrl+Z` 能撤回。
+
+### 扩写
+
+输入一句粗需求，例如 `帮我写一个登录功能`，点 `扩写`。
+
+它先**判断你要的是哪一种**，再按那种形态写，第一行会说明它的判断：
+
+| 形态 | 什么时候 | 输出 |
+| --- | --- | --- |
+| 要造的 | 你打算做或让别人做 | 需求说明：做什么、边缘怎么表现、怎么算做完 |
+| 要货的 | 你想要成品本身 | 直接给成品（提示词 / 文案 / 模板 / 清单），不解释怎么设计 |
+| 要判断的 | 句子里藏着一个选择 | 摆出取舍 + 带条件的建议，不给方案书 |
+| 要问的 | 缺一个事实，说了也白说 | 只问那一个问题，不扩成问卷 |
+
+它**不会替你决定范围**——不会自己宣布「不做注册、不做找回密码」，而是把这类分叉摆出来、说清楚每个选择会改变什么。它会读完整的对话历史（最近的对话保留全文，更早的压缩成一行摘要），所以知道你在做什么产品、哪些决策已经定了。
+
+### 自动驾驶
+
+点 `自动` 弹出面板：
+
+```
+自动驾驶
+○ 循环几次结束      [ 5 ]
+☑ 限制运行时间      [ 0 ] 小时  [ 30 ] 分钟
+○ 直到达成目标结束
+
+目标（可选）：写清楚要达成什么，达成后自动停；不填就只看轮数
+[                                    ]
+
+[ 启动 ]
+```
+
+点启动 → 确认弹窗 → 才真正开始。运行中再点 `自动`：
+
+```
+运行中 3/5 · 已跑 12 分钟
+上下文：8 条消息 / 1300 字
+查看驱动 AI 读到的上下文
+
+[ 中断 ]  [ 结束循环 ]
+```
+
+- **中断**：掐掉当前这一轮，循环继续，它会重新判断再发一条
+- **结束循环**：整个关掉
+- 轮数用尽 / 时间到 / 目标达成 / 出错 / 你点停 —— 五种情况都会立刻停机
+
+停止条件可以叠加：`循环 5 次 + 填个目标` = 最多 5 轮，做完了提前收工。
+
+**它读到的对话你能看见**：面板里的「查看驱动 AI 读到的上下文」会显示这一轮实际传给驱动 AI 的对话全文。
+
+**它的思考和调用也能看见**：面板里的「查看思考与调用」会列出每一轮的推理、它调用了哪个工具、参数是什么、返回了什么，以及最终发给助手的那条消息。按类型上色：
+
+```
+思考 1      The draft is vague. I should look at the project directory…
+list_dir    - index.js  - client.js  d locale
+search_files  d dsh-one-click-polish  - cordis.patch.yml
+思考 2       Likely a DSH plugin. Let me check the config directory…
+已发送 1     请把这句话改得更正式：…
+```
+
+这份记录来自同一个任务表（`GET …/progress?id=autopilot-<sessionId>`），所以润色/扩写时那个进度窗也能看到同样的过程。
+
+**右侧贴边窗口**：点「在右侧显示」，思考窗会滑入屏幕右缘，跟着当前对话实时刷新（每 500ms 一轮），可以上下翻、折叠、关闭。切到别的对话时它会自己跟过去；那个对话没有记录时就是空的。
+
+**按钮会报告上一次怎么结束的**：
+
+| 按钮 | 含义 |
+| --- | --- |
+| 🔵 转圈 `自动 2/5` | 正在跑 |
+| 🟢 `已完成` | 跑满轮数，或驱动 AI 判断目标达成 |
+| 🔴 `出错` | 出错停下，点开能看到错误全文 |
+| 🟡 `意外停止` | 它自己停下了：想不出下一步、助手一直在忙、或到了时长上限 |
+| 🟡 `已中断` | 你手动停的 |
+
+点开按钮能看到为什么停、读了哪些文件、完整思考记录，底部有「从中断处继续」（停下的情况）或「重新开始」+「清除状态」。
+
+**设置页有每个对话的自动运行日志**：它读了哪些文件、调用了什么、发了什么，按会话归档，重启后仍在。长工具行和长思考行默认收起，点一下展开，收起时保留首行预览。
+
+## 换窗口 / 重启 会怎样
+
+| 场景 | 结果 |
+| --- | --- |
+| 切会话、切标签、最小化 | 继续跑（在 Host 进程里） |
+| 切走再回来 | 继续跑，按钮上轮数跟着涨 |
+| 重启 dsh | 不自动跑，面板里给「从中断处继续」按钮，点了才续 |
+
+每轮都会把进度写进 profile 目录的 `.one-click-polish-autopilot.json`，重启后据此提供恢复入口。正常结束会自动清掉。
+
+## 设置
+
+**设置 → 润色 / 扩写**：
+
+| 项 | 说明 |
+| --- | --- |
+| 模型来源 | `跟随当前对话`（默认）用输入框里选中的模型；`固定模型` 始终用指定那个 |
+| 模型 | 选 `固定模型` 后出现，带搜索的下拉框，按供应商分组 |
+| 思考程度 | 照 dsh 的 `Default / Low / High / Max` 做，**选项按该模型实际支持的档位生成**，不支持就整栏隐藏；换模型时旧档位自动回落 |
+| 等待助手完成上一轮的上限 | 自动驾驶要发下一条时助手仍在忙，等多久放弃。默认 5 分钟，可到 60 |
+| 检索预算 | 查资料总共能用多久、最多几轮。默认 45 秒 / 4 轮 |
+| 改写预算 | 模型写答案这一步最多等多久。默认 120 秒 |
+| 自动运行日志 | 每个对话的自动驾驶记录，按会话归档 |
+
+改动先留在页面上，点 `保存` 才写入 profile，`撤销修改` 回到上次保存的状态。
+
+## 配置
+
+在 profile 的 `cordis.patch.yml` 里覆盖本行 `config`：
+
+```yaml
+- id: one-click-polish
+  config:
+    modelSource: follow      # follow | fixed
+    provider: ''             # modelSource 为 fixed 时必填
+    model: ''
+    reasoningEffort: ''      # '' = 默认；否则必须是该模型支持的档位
+    defaultStrength: strong  # light | standard | strong
+    maxInputChars: 12000     # 单次输入字符上限
+    timeoutMs: 120000        # 单次改写预算
+    exploreMs: 45000         # 检索预算
+    exploreRounds: 4         # 最多检索几轮
+    idleWaitMs: 300000       # 等助手空下来的上限
+    instruction: ''          # 追加给模型的额外要求
+```
+
+## 原理
+
+- **模型解析**在 Host 侧：会话日志里最新的 `model/selection` → 最近一次 `request/header` → profile 默认模型。所以模型选择器切到哪个就用哪个，切了还没发消息也认得。
+- **润色 / 扩写**是手工构造的 `llm.stream()`：不写会话日志、不开 Turn、不动对话历史，只借一次模型能力。
+- **长任务用 202 + 轮询**：桌面 webview 会掐断长时间静默的请求，所以 `POST …/polish` 立刻返回 202，浏览器每 700ms 轮询 `GET …/progress` 取结果。
+- **自动驾驶**用 `agent.followup()` 往会话里追加用户消息并唤醒，用 `await agent.whenIdle()` 等这一轮跑完。每轮按 session id 重新取 agent，所以切换会话销毁重建 agent 也不影响。
+
+## HTTP 接口
+
+都在 `/plugins/dsh-one-click-polish` 下：
+
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| POST | `/polish` | 提交润色/扩写任务，返回 202 + requestId |
+| GET | `/progress?id=` | 轮询任务状态与结果 |
+| GET | `/settings` | 读/写设置与模型目录 |
+| GET | `/efforts?provider=&model=` | 某模型支持的思考档位 |
+| GET/POST | `/autopilot` | 读/写自动驾驶状态，`?resumable=1` 列可恢复的运行 |
+| GET | `/runs` | 按会话归档的自动运行日志；`?sessionId=` 取某会话 |
+| GET | `/status` | 当前会话解析到的模型 |
+| GET | `/diag` | 排查用：会话、目录、上下文快照 |
+
+## 文件
+
+| 文件 | 作用 |
+| --- | --- |
+| `index.js` | Host 半身：模型解析、检索、改写、轮询任务、自动驾驶驱动 |
+| `client.js` | 浏览器半身：工具栏按钮组、进度窗、右侧思考窗、设置页 |
+| `cordis.patch.yml` | 插件行声明 |
+| `locale/*.json` | 插件管理页的标题与描述 |
+| `TESTING.md` | 测试纪律：自动驾驶会真往会话里发消息，不能拿真实对话试 |
+
+## 出问题怎么查
+
+**按钮没出现**
+
+1. 确认插件真的加载了：设置 → 插件 里能看到 `dsh-one-click-polish`
+2. 重启 dsh（改 `package.json` 的 bundles 后必须重启，刷新页面不够）
+3. 打开 `http://127.0.0.1:<dsh 端口>/plugins/dsh-one-click-polish/status`，返回 `{"ok":true,...}` 就是活着
+
+**按钮出现了但点了没反应**
+
+打开同一端口下的 `/diag`，看 `processCwd` 和 `profileDir`。如果 `profileDir` 是空的，说明插件认不出 profile 目录（判断依据是那个目录里要有 `cordis.patch.yml`，且不含 `package.json` + `client.js`）。
+
+**润色一直转圈不结束**
+
+设置页把「检索预算」和「改写预算」调大。深度档要联网检索，网络慢的时候 45 秒不够。
+
+**自动驾驶自己停了**
+
+按钮颜色会告诉你原因，点开有全文：
+
+| 颜色 | 原因 |
+| --- | --- |
+| 🟡 意外停止 | 驱动 AI 想不出下一步 / 助手一直在忙（超过等待上限）/ 到了时长上限 |
+| 🟠 已中断 | 你自己点的 |
+| 🔴 出错 | 具体错误在面板里，红字 |
+| 🟢 已完成 | 跑满轮数或目标达成 |
+
+停下不等于失败：底部有「从中断处继续」，从已跑的轮数接着来。
+
+**想复盘它做了什么**
+
+设置 → 润色 / 扩写 → 自动运行日志，按会话列出每一次运行：读了哪些文件、调用了什么工具、发了什么消息。或者面板里点「查看思考与调用」。
+
+**看到的上下文不完整**
+
+长对话会被压缩：最近的保留全文，更早的压成一行摘要，中间放不下的丢掉并标注「中间省略了 N 条」。面板上会显示「压缩省略 N 条」。想让它看更多，就在目标里写得具体一点。
+
+## 隐私
+
+- 插件**只读**本地文件。越出项目工作目录和 dsh 配置目录的路径会被拒绝。
+- 敏感文件名和目录**一律不读不列**：cookie、凭据、`id_rsa`、`.env`、微信 / QQ 数据目录、`node_modules`、`.git` 等。
+- 自动驾驶每轮的推理、工具调用、发出的消息会写到 profile 目录下的 `.one-click-polish-log.json`，**按会话归档**。这个文件只在你的机器上，不会上传。不想要就删掉它。
+- 插件不会把运行时数据写进自己的源码目录。
+
+## 许可
+
+MIT