# dsh-workspace-status-badge · 工作区状态徽标

<div align="center">
  <b>中文</b> · <a href="README.en.md">English</a>
</div>

> **把工作区收起后，文件夹名字前的状态一眼可见。**
> 左侧边栏的会话任务自带"进行中 / 已完成"小圆点，但工作区文件夹一旦折叠，点就全藏起来了——本插件把该工作区下的任务状态**聚合成一个点**，标在折叠文件夹的图标与名称之间。

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)](https://github.com/AFAP/dsh-workspace-status-badge/releases)

无需任何配置。

## 1. 它解决了什么问题

DeepSeek Harness 的左侧边栏按工作区（Workspace）分组展示会话任务，会话行前有状态点：

| 状态 | 颜色 | 含义 |
|:---:|:---:|---|
| 等待处理 | 琥珀 | 需要你批准 / 审阅计划 / 回答问题 |
| 进行中 | 蓝 | 会话或它的子代理正在运行 |
| 已完成 | 绿 | 跑完了但还没打开看过 |

但**状态点只画在会话行上**：工作区折叠后，会话行全部隐藏，文件夹行本身只有图标和名字，工作区里有没有任务在跑、有没有等你处理的，完全看不到——每次都得展开一个个工作区去翻。

本插件把状态**聚合**到工作区这一层：

```
折叠前（原版）                         折叠后（本插件）
████ 工作区A ▾                        ████ 工作区A   ◉  ← 琥珀：有任务等你
  ● 任务1（进行中）                      工作区B   ◦  ← 蓝色：有任务在跑
  ● 任务2（等待审批）...
```

状态优先级与单任务行完全一致：**等待处理 > 进行中 > 已完成**。

## 2. 功能特性

- ✅ 工作区折叠时，文件夹图标与名称之间显示**聚合状态点**（与官方状态点同款颜色与"进行中"脉动动画）
- ✅ 工作区有任务在执行时，**文件夹图标本身染成淡蓝色**（展开、折叠都可见）
- ✅ 悬停显示明细工具提示：「2 个任务等待处理 · 1 个任务进行中 …」
- ✅ **点击状态点 = 点击文件夹行**，直接展开/收起该工作区
- ✅ 纯客户端响应式：状态实时跟随（任务开始/结束/等你处理都会即时更新）
- ✅ 子代理也算数：某个会话的子代理还在跑，工作区同样显示"进行中"
- ✅ 未分组（Ungrouped）桶同样支持
- ✅ 语言跟随界面（简体中文 / English）

## 3. 目录结构

```
dsh-workspace-status-badge/      # 仓库根 = npm 包根
├── package.json                 # dsh.bundle.patch（配置补丁层）+ dsh.client（浏览器端声明）
├── cordis.patch.yml             # 组合行：加入 web profile 的浏览器插件名册
├── LICENSE                      # MIT
├── README.md / README.en.md     # 双语文档
└── lib/
    ├── index.js                 # 宿主半部：刻意空操作（本插件无需任何后端）
    └── client.js                # 浏览器 bundle：聚合逻辑 + shell.overlay 叠加层
```

## 4. 快速开始（GitHub）

```powershell
dsh plugin --profile web add github:AFAP/dsh-workspace-status-badge
```

然后**重启 `dsh web`** 生效。

> 安装后插件位于 `$DSH_HOME\profiles\web\node_modules\dsh-workspace-status-badge`，与源码仓库位置无关。
>
> 升级：`dsh plugin --profile web update dsh-workspace-status-badge`
>
> 卸载：`dsh plugin --profile web remove dsh-workspace-status-badge`

### 从源码目录手动安装（等价验证用）

```powershell
dsh plugin --profile web add "D:\path\to\dsh-workspace-status-badge"
```

### 验证是否加载成功

左侧边栏任意**折叠**一个工作区——如果里面有任务，文件夹图标与名称之间就会出现状态点（琥珀 / 蓝 / 绿），悬停可见明细，点击可展开。

## 5. 使用与状态含义

状态点颜色与官方会话行一致：

| 显示 | 含义（聚合整个工作区的所有会话） |
|---|---|
| <span style="color:#E6A23C">●</span> 琥珀（等待处理） | 至少一个会话在等待你：批准 / 计划审阅 / 回答问题 |
| <span style="color:#3B82F6">▦</span> 蓝色脉动（进行中） | 至少一个会话在运行，或有运行中的子代理链 |
| <span style="color:#22C55E">●</span> 绿色（已完成） | 至少一个会话跑完、你还没打开看过 |
| 不显示 | 该工作区所有会话都空闲（与单任务行隐藏"空闲"点的行为一致） |

- 优先级：等待处理 > 进行中 > 已完成，与官方单任务行完全一致。
- 状态点只在**折叠**时显示；展开后每个任务自带状态点，不重复显示。
- 子代理会话不单独占一行，但它运行时会算进所属工作区的"进行中"。

## 6. 已知边界

| 场景 | 表现 |
|---|---|
| 「单列表」视图（In one list） | 没有工作区文件夹行，不显示状态点（正常） |
| 侧边栏收起成窄条（rail） | 会话树不可见，不显示状态点（正常） |
| 搜索模式 | 树被搜索结果替换，不显示状态点（正常） |
| 极窄窗口 | 状态点跟随折叠文件夹位置，视口内可见 |

工作原理：插件挂载在框架的 `shell.overlay` 全局面板上，通过语义锚点
`[role="treeitem"][aria-expanded]` 定位工作区文件夹行（会话行用的是
`aria-selected`，不会误匹配），按渲染顺序一一对应；用 MutationObserver +
滚动/窗口尺寸监听保持位置实时同步。若 DSH 官方版本改动了行结构与顺序，
行数对不上时插件**自动隐藏**而不是画错位置。

## 7. 安全与合规

- **零后端**：宿主半部是空模块，不暴露任何 HTTP 路由；
- **只读快照**：所有数据来自浏览器端 `useSessions` / `useWorkspaces` 框架钩子
  （Harness 自己的运行时快照），**不读写、不修改任何会话日志或文件**；
- **无凭证、无网络**：不调用外部接口，不上传任何数据；
- **无配置项**：无需提供密钥或路径。

## 8. FAQ

**Q：状态点会不会和官方任务行的点搞混？**
A：颜色、形状、动画与官方 `StateDot` 完全一致（"进行中"同样是用 3×3 追逐方格动画），
唯一的区别是它出现在**折叠后**文件夹的图标与名称之间，语义就是"这堆任务里最要紧的状态"。

**Q：为什么展开时不显示？**
A：展开后每个任务行自带状态点，文件夹再放一个点是重复信息。设计上只在折叠态显示。

**Q：子代理（subagent）会影响状态吗？**
A：会。子代理会话不占工作区的一行，但它运行中会把所属工作区标为"进行中"——
与官方会话行把子代理计入状态的逻辑一致。

**Q：升级 DSH 后状态点不见了？**
A：行结构大改版时插件会自我隐藏（行数对不上即停用）。一般升级无需处理；
若确实不可用，提一个 issue 即可修复。

## 9. License

MIT © AFAP