# dsh-plan-switch 📋

[English](README.md) | [简体中文](README.zh-CN.md)

![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)

[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)

输入框**一键进/出 Plan 模式**按钮 —— DeepSeek Harness（dsh）web 插件（`/plan` 的快捷点击）。

*非官方项目：社区成员独立开发维护，非 DeepSeek 官方产品。*

## 截图

![dsh-plan-switch 输入框 Plan 按钮](assets/plan-button.png)

输入框工具行左侧的**清单图标按钮**（官方 dsw 设计风格，跟随深浅色主题）。

## 功能

- **一键进/出 Plan 模式**：输入框工具行左侧的清单图标按钮，点击执行官方 `/plan` 切换命令（快捷点击）。
- **Plan 模式中自动隐藏**：plan 进行中按钮隐藏自身，状态由官方 Plan 卡片接管显示——不会出现重复指示。
- **切换 pending 防反**：`/plan` 切换排队期间按钮禁用（语义等同官方 Plan 圆片的"切换中"），防止误点反向切换。
- **状态实时同步**：按钮通过官方投影实时读取 plan 状态，任何入口（`/plan` 命令、官方圆片、agent 运行中切换）的变化都即时反映。

## 安装

官方 bundle 一行安装：

```sh
# DSH 0.1.7 及以后：
dsh plugin --profile web add "github:a903067276-rgb/dsh-plan-switch#main"
# DSH 0.1.5 及更早（本版需要 0.1.7+）：
# dsh plugin --profile web add "github:a903067276-rgb/dsh-plan-switch#v0.3.2"
```

装完重启 `dsh web`（bundle 层在启动时合成）。需要 pnpm（`dsh plugin` 是 pnpm 转发器）。

手动兜底：详见 [docs/install.md](docs/install.md) —— 软链到
`~/.dsh/profiles/web/node_modules/` + `~/.dsh/cordis.patch.yml` 单 entry，重启生效。

## 用法

输入框工具行左侧的**清单图标按钮**（官方 dsw 设计风格，跟随深浅色主题），点击进入 plan 模式（等同 `/plan`）。plan 模式进行中按钮自动隐藏——状态由官方 Plan 卡片接管，不会出现重复指示；`/plan` 切换 pending 期间按钮禁用，防止再点反向切换。

## 平台支持

| 平台 | 状态 |
|---|---|
| macOS | ✅ 全功能实测（开发环境） |
| Linux | ⚠️ 预期可用（纯前端按钮，无平台依赖），未实测 |
| Windows | ⚠️ 预期可用（纯前端按钮，无平台依赖），未实测 |

## 环境要求

- DSH web（≥ 0.1.0-rc.6）（`dsh web` 运行）——代码自适应：先按 rc.8+ 的 3 参契约调用官方 `commands.execute`，rc.6/rc.7 上自动降级为 2 参
- **版本对照**：
  - ✅ **DSH 0.1.7 及以后——装本版（`v0.4.1`）**：它声明了 `peerDependencies: {"@deepseek-ai/dsh": "^0.1.7-rc.1 || ^0.2.0-rc.1"}`，宿主不匹配会明确拒绝加载并说明原因，不再静默出错。配置迁到 0.1.7 的插件 `Config`（`.volatile()` 字段可即时生效），改完不用重启。
  - ✅ **DSH 0.2.0-rc.1——已验证兼容**：peer 范围同时覆盖两条线（`^0.1.7-rc.1 || ^0.2.0-rc.1`），`dsh.compatibility.dshReleases` 矩阵新增 `"0.2.0-rc.1": "compatible"`——已在 0.2.0-rc.1 真机 + 影子实例验证。0.2 起宿主对 profile bundle 做 peer 门禁，范围不覆盖当前运行时会**整个跳过加载**，靠这个范围插件才会被加载。
  - ⚠️ **DSH 0.1.5 及更早——请装上一版 tag `v0.3.2`**：那条线保持原行为，不含任何 0.1.7 专用 API。
  - ⛔ **旧版本插件（≤ `v0.3.2`）在 0.1.7 上不受支持**——无已知行为回归，只是缺本地化元数据。插件要跟宿主一起升。
- **维护策略**：本插件将持续跟随 DSH 最新版本演进；对旧版 DSH 的兼容仅是尽力而为、不保证长期有效。

| 你的 DSH 版本 | 装这个 | 说明 |
|---|---|---|
| 0.1.0-rc.6 及以上（含 0.1.1-rc.1/rc.2） | `main`（v0.3.2+） | **尽力兼容**——3 参调用、rc.6/rc.7 自动降级 2 参（本地实测 rc.6/rc.8，不保证） |
| **0.1.5-rc.1** | `main`（v0.3.2+） | ✅ **实测**：官方 slot 目录核实 `conversation.input.left` 仍在（`occupants: []`、`replaceRisk: none`），无需迁移；官方 Plan 胶囊只负责「退出」，未激活入口官方 README 明文说不做（本插件补的正是这个位） |
| 0.1.0-rc.8 及以上（保守） | `v0.3.1` — `dsh plugin add github:a903067276-rgb/dsh-plan-switch#v0.3.1` | 无降级逻辑的最后一版 |
| 0.1.0-rc.6 – 0.1.0-rc.7（保守） | `v0.3.0` — `dsh plugin add github:a903067276-rgb/dsh-plan-switch#v0.3.0` | 2 参 `commands.execute` 契约 |

- 无需任何 host 侧配置：host 半为空实现——整个插件就是浏览器侧一个按钮，调用官方 `/plan` 命令，全平台无额外依赖

## 工作原理

- **Host**（`lib/index.js`）：无行为——纯 UI 插件；client 半通过 `package.json` 的 `dsh.client` 声明被发现（`exports["./client"]`）。
- **Client**（`lib/client.js`）：`conversation.input.left` 插槽注册清单图标按钮（官方 dsw 设计 token，跟随明暗主题）；通过 `useProjection("plan")` 实时读取 plan 状态；点击经 `ctx.remote.commands.execute(sessionId, "/plan", [])` 执行官方 `/plan` 命令——全流程走官方命令链。
- **状态处理**：有效 plan 状态照抄官方 PlanChip 算法（`pending ? !active : active`）。plan 模式进行中按钮返回 `null`（隐藏——指示归官方 Plan 卡片，不重复）；切换 pending 期间按钮禁用，防第二次点击反向；命令失败按钮变错误色，错误信息显示在 tooltip。

## 注意事项

- 纯 client 侧：无 host 路由、不写文件、不存数据。
- 安装/更新后重启 `dsh web`（bundle 层在启动时合成）；client 改动刷新页面即可生效。

## 开发

- 源码：`lib/index.js`（host 侧，空实现）、`lib/client.js`（web 端注入）
- 开发流程：本地改 → push main → `pnpm update` 验证安装

## 许可证

[MIT](LICENSE)