# dsh-web-ui

> DSH Web GUI with multi-column task board, Host authoritative ledger for task management, real DSH session execution, 5-field cron scheduling, and optional cross-platform idle sleep protection.

## Metadata

- Author: [@zhu1090093659](https://github.com/zhu1090093659)
- Repo: <https://github.com/zhu1090093659/dsh-web-ui.git>
- GitHub: [zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui)
- Stars: 5,127
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://gallery.dsh-market.com>
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`, `web-ui`
- Forks: 311
- Open Issues: 50
- Last push: 2026-08-20T14:37:38.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-task-board
```

## Wiki

## 一句话定位
DSH Web GUI 的多列任务看板插件，把任务、计划与执行记录托管在 Host 端权威账本里，让你能用真实 DSH 会话定时跑任务，并在长任务期间阻止电脑进入系统睡眠。

## 核心能力
- 在 DSH Web 侧边栏提供五列看板、搜索、任务详情、归档/恢复、执行历史和执行会话跳转
- 以 Host 端 `$DSH_HOME/task-board/ledger-v2.json` 为单一事实源，浏览器动作只有经 Host 确认后才会成为 UI 状态
- 每次运行创建独立 DSH 会话，先钉住工作区、agent 预设和 `/permission <id>` 再发送任务 Prompt，钉子缺失即关闭
- 支持本地时区的 5 段 cron（`*`、`*/n`、范围、逗号列表、周日 `0/7`、日期/星期 OR 语义），重启后能确定性地观察或取消运行中的执行
- 通过 SSE 推送 revision、scheduler、power 变化，变更接口始终返回完整 revisioned snapshot，跨标签页与重连后保持一致
- 可选的跨平台空闲睡眠保护：macOS 用 caffeinate、Windows 用 SetThreadExecutionState、Linux 用 systemd-inhibit，全部走固定可执行路径和 `shell: false`

## 技术实现
- **语言**: TypeScript（ES Module，`type: "module"`）
- **关键依赖**: schemastery（配置 schema 校验）、`@deepseek-ai/dsh-host-apiproxy` 与 `@deepseek-ai/dsh-host-webserver`（Host 半区路由挂载）、`@deepseek-ai/dsh-agent` + `@deepseek-ai/dsh-commands`（真实会话执行）、`react ^18.2`（浏览器侧 UI）
- **架构模式**: 典型 cordis 双面插件（host + client 半区分层），通过 `cordis.patch.yml` 以 profile bundle 层挂载，不修改 DSH 源码；host 进程负责账本/cron/runner/power 状态机，浏览器进程负责异步展示与提交动作
- **入口文件**: `src/index.ts`（host loader）、`src/client/index.ts`（client apply）、`src/host-service.ts`（编排核心）、`src/host-ledger.ts`（账本持久化）、`src/power-inhibitor.ts`（跨平台电源保护）

## 适用场景
需要把一组重复性或长时任务从手动会话里抽出来、定时交给 DSH agent 自动跑的人，比如每晚汇总报告、定时抓取数据、定时跑分析任务等。看板让任务列表可视化、定时规则可读、执行结果有据可查；可选的电源保护让跑长任务时电脑不会因空闲睡眠而中断。如果你只是想用一次性的会话和 agent 内置的 todo 计划，这个插件属于过度工程。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH（@deepseek-ai/dsh-agent / dsh-commands） | >=0.1.0-rc.8 | 来自 peerDependencies，运行时由宿主注入 |
| Node | ^22.19 或 >=24 | 来自 monorepo packages/AGENTS.md 约定；本包未声明 engines |
| React | >=18.2.0 | peerDependency，浏览器半区构建需要 |
| 平台 | macOS / Windows / Linux | 跨平台电源保护各走原生固定 helper；其他平台电源保护报 `unsupported`，任务本体仍可正常使用 |
| 原生模块 | 无 | 仅使用 `node:child_process` / `node:crypto` / `node:fs` / `node:path` 等内置模块 |

## 安装方式
```bash
dsh plugin --profile web add github:zhu1090093659/dsh-web-ui/packages/dsh-task-board
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `enabled` | boolean | 总开关：关闭后同时停用 Host 服务、浏览器看板和 agent 宣告 | `true` |
| `announceToAgent` | boolean | 是否在 agent 系统提示词里追加任务看板说明（不影响看板本身的使用） | `true` |
| `preventIdleSleep` | boolean | 任意 DSH 会话在跑、任一已启用 schedule 或会话状态未知时，阻止系统因空闲进入睡眠（允许显示器熄灭与锁屏） | `false` |
| `trustedProxyHosts` | string[] | 通过已认证反向代理放行的 `host[:port]` 列表；空数组 = 仅 DSH loopback origin 直连 | `[]` |
| `proxyTokenEnv` | string | 保存反向代理 token 的环境变量名，token 本身不会被写入插件配置 | `DSH_TASK_BOARD_PROXY_TOKEN` |

## 常见问题

**Q: 关闭浏览器页面后任务还会继续执行吗？**

A: 会。任务真正运行在 Host 进程里，浏览器只是异步视图；关闭页面、切走标签页或断网都不会中断已经在跑的会话，也不会错过 cron 触发。

**Q: 任务和会话数据存在哪里？会同步到云端吗？**

A: 数据落在 Host 端本地文件 `$DSH_HOME/task-board/ledger-v2.json`，POSIX 权限 0600，Windows 继承用户目录 ACL；不会上传到任何远端。旧版浏览器 localStorage 中的 v1 数据会在首次升级后按 source/request id 一次性导入并保留为只读回滚副本。

**Q: 错过了一次 cron 触发点（比如电脑睡眠了一晚），第二天会补跑吗？**

A: 不会。Host 启动或长暂停后的过期出现全部跳过，`nextRunAt` 直接从当前 Host 时间向后滚动；插件刻意不做 catch-up，避免补跑风暴。

**Q: 这个插件能阻止电脑进入睡眠吗？能唤醒已经睡着的电脑吗？**

A: 仅能阻止「系统因空闲进入睡眠」这一种情况（macOS caffeinate / Windows ES_CONTINUOUS+ES_SYSTEM_REQUIRED / Linux systemd-inhibit idle 锁），而且不会触碰显示器睡眠与锁屏。合盖、手动睡眠、休眠、低电量强制睡眠和企业电源策略不在保证范围内；插件不会创建唤醒定时器，已经睡着的电脑无法被它叫醒。

**Q: 任务执行需要额外付费吗？会消耗 API 额度吗？**

A: 每次执行都创建一个全新的 DSH agent 会话，消耗与普通会话相同的 API 配额；插件本身不收费。

**Q: Linux 上为什么显示 unsupported？**

A: 电源保护依赖 systemd-logind 的 idle block lock，且要求当前用户被允许取得该锁；容器、WSL、无 system bus 或非 systemd 系统会显示 `unsupported`，不启用桌面替代方案。任务本体（看板/cron/执行）不受影响，仅电源保护不可用。

**Q: 想通过反向代理对外暴露怎么配？**

A: 把 DSH Web 绑定到 loopback，给 `trustedProxyHosts` 填好允许的代理 host[:port]，把高熵 token 放进 `proxyTokenEnv` 指向的环境变量里，让反向代理完成认证后用服务端注入的 token 替换请求头 `X-Dsh-Task-Board-Proxy-Token`（不要透传客户端送来的），修改后重启 Host 生效。

**Q: 怎么完全卸载？**

A: `dsh plugin --profile web remove @linxin666/dsh-client-ui-task-board`，然后重启 `dsh web`。插件不会自动删除账本文件，如需清空请手动删除 `$DSH_HOME/task-board/`。

## 上手难度
进阶 — 需要理解 DSH 的 workspace / agent preset / permission 概念以及 cron 表达式；如果只是建几个手动任务则很快上手，但要用好定时、长任务与电源保护需要先读一遍 Host 账本和电源 helper 的安全约束。

## 已知问题与限制
- Host 停机、系统睡眠或长暂停期间错过的 cron 触发点全部跳过，从不补跑；这是显式行为，不是 bug
- 同一任务已在运行时，到期触发点会被跳过并滚动到下一匹配点，任务运行从不并发也从不排队
- DST 采用 Host 本地墙上时钟语义：春季跳时中不存在的分钟会跳过，秋季回拨中重复的分钟不会执行第二次
- 电源保护仅拦截空闲系统睡眠，明确允许显示器睡眠与锁屏；合盖、手动睡眠、休眠、关机、低电量强制睡眠和企业电源策略不在保证范围内
- 插件不创建唤醒定时器，无法唤醒已睡眠的电脑
- 已启用 schedule 会从未来触发点之前就开始持锁，长时间挂着会消耗更多电池电量
- 反向代理配置（`trustedProxyHosts` / `proxyTokenEnv`）修改后必须重启 Host 才生效
- 损坏的 v2 账本会被改名为 `ledger-v2.json.corrupt-*` 并隔离，Host 以空账本加可见 scheduler 错误启动，损坏字节不会被覆盖

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-web-ui](https://deepseek-plugin.org/plugins/zhu1090093659/dsh-web-ui/packages/dsh-task-board)
Wiki generated by AI (model: `MiniMax-M3`)