# dsh-workspace-promote

[English](README.md) | 中文

DeepSeek Harness（DSH）宿主层插件：**用户提交任务时**，把该任务所在的工作区顶到侧边栏第一位——**一次提交只排一次，任务执行期间绝不重排**。

一条命令装完，不需要改任何 patch——包自带 profile bundle patch：

```bash
dsh plugin --profile web add dsh-workspace-promote
```

装完重启 `dsh web`（宿主层插件在启动时挂载）。

## 它补的是哪个缺口

DSH 侧边栏对两层的处理完全不同：

| 层 | 原生行为 | 够用吗 |
|---|---|---|
| 工作区组内的**会话** | 视图选项默认 `orderBy: "updated"`，有新活动的会话会被提升到所属组顶部 | ✅ 原生就够，不需要插件 |
| **工作区**本身 | 顺序来自持久化的 `workspaceIds` 数组，即**手动拖拽顺序**，不会因为你正在哪个项目干活而变化 | ❌ 本插件 |

所以「我正在做的项目浮到最上面」这个需求，缺的只是工作区这一层——正好是本插件加的东西。

## 触发语义

插件只在**一个**条件下重排：`user/message` 事件且 `data.source.kind === "user"`，也就是**真人确实提交的那条 prompt**。

同一条 `user/message` 事件还承载另外两类内容，靠 `source.kind` 区分，本插件一律忽略：

| `source.kind` | 是什么 | 本插件 |
|---|---|---|
| `user` | 真人直接提交的 prompt | ✅ 置顶 |
| `plugin` | `agent.inject()` 合成上下文（文件变更通知、AGENTS.md、skill 内容、cron 通知）以及 goal 续跑轮次 | ❌ 忽略 |
| `tool` | 工具回执（`role` 同样是 `user`） | ❌ 忽略 |

执行期事件——`assistant/message`、`step/start`、`step/end`、`turn/start`、`turn/end`——同样全部无视。

**效果：一次提交 = 一次置顶。** 任务执行过程中侧边栏纹丝不动。

反过来，如果直接挂在原始的 `session/event` 事件流上（最直觉的第一版实现），侧边栏就会持续跳动——因为工具回执本身就是 `user` 角色的事件。

## 工作原理

- 命中后调用 `workspaceRegistry.insertBefore(id, currentFirst)`。
- 若该工作区已在第一位，或工作区不足 2 个，直接返回且**不产生任何写操作**，所以事件突发不会造成写盘风暴。
- 无状态文件：`insertBefore` 改的就是持久化的 `workspaceIds` 顺序，结果天然跨重启保留，也没有「重启后活动样本不足」的问题。
- 未分组（ungrouped）会话与子代理子会话不参与。
- 任何失败只写日志，绝不影响会话本身。

## 审计日志

`~/.dsh/workspace-promote.log`（尊重 `DSH_HOME`）。只追加，用来回答两个问题：当前进程跑的到底是哪个版本的行为、以及它究竟在什么时刻触发。

```
2026-09-15T09:31:44.809Z boot pid=49220 trigger=human-prompt-only
2026-09-15T09:33:11.770Z promote workspace=039cce9b-... session=session-1ee5c45f-... from=a6680e0c-...
```

`ctx.logger` 的输出去向没有保证，而这个文件是确定的。

## 已知取舍

实时排序会与手动拖拽争夺第一位：把工作区 B 拖到顶部后，只要你在 A 里提交任务，A 就会回到第一位。这是「动态排序」的固有语义，不是 bug。

## 与 `dsh-workspace-sort` 的区别

[`dsh-workspace-sort`](https://www.npmjs.com/package/dsh-workspace-sort) 同样按活动给工作区排序，但语义是**「每个日历日最多重排一次，之后锁死」**——早上看到的顺序反映的是截至昨天的活动。本插件的触发点是**用户的提交动作**，且不保留状态文件。

想要「侧边栏一整天都别动」就选 `dsh-workspace-sort`；想要「我正在做的项目在最上面」就选本插件。

## 验收

1. 在别的项目里提交一条任务 → 该项目跳到第一位。
2. 观察该任务执行过程（大量工具调用、多轮 step）→ 侧边栏**不应**再有任何移动。
3. `~/.dsh/workspace-promote.log` 里每次提交只应新增 **1 行** `promote`。

## 卸载

```bash
dsh plugin --profile web rm dsh-workspace-promote
```

然后重启 `dsh web`。如果你是手工写进 `cordis.patch.yml` 的，就删掉那行 `workspace-promote` 再重启。

> 注意：不要同时使用两种安装方式。如果你手工加过行、后来又把它作为 bundle 安装，同一个 row id 会被插入两次——先删掉其中一个。

## License

MIT