# deepseek-harness-desktop

> Adds multi-column task board to DSH Web GUI with sidebar entry for one-click switching. Tasks execute through Host real session and write back status. Five-segment cron timing is maintained by Host with browser fallback.

## Metadata

- Author: [@ningbainb](https://github.com/ningbainb)
- Repo: <https://github.com/ningbainb/deepseek-harness-desktop.git>
- GitHub: [ningbainb/deepseek-harness-desktop](https://github.com/ningbainb/deepseek-harness-desktop)
- Stars: 156
- Language: TypeScript
- License: [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)
- Homepage: <https://ningbainb.github.io/deepseek-harness-desktop/>
- Topics: `ai-agent`, `ai-coding-assistant`, `codex`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `electron-app`, `gui`, `open-source`, `plugin-system`, `plugins`, `remote-access`, `skills`, `ssh-client`, `windows`, `windows-desktop`
- Forks: 5
- Open Issues: 6
- Last push: 2026-08-20T05:29:52.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-task-board
```

## Wiki

## 一句话定位
这个插件为 DSH Web 界面新增一个「任务看板」入口，切换后中间列变成多列卡片板，任务可以即时执行（驱动真实 agent 会话）或按 cron 定时执行，结果实时回写到卡片。

## 核心能力
- 侧边栏「新会话」下方注入「任务看板」入口行（宽栏显示图标+文字，折叠 rail 仅显示图标），点击后中间列整体切换为五列看板
- 五列视图：待规划 / 待办 / 进行中 / 已完成 / 已失败；卡片显示标题、描述、状态、更新时间、执行次数；顶部支持搜索、新建任务、返回对话
- 点击卡片打开详情（标题/描述/执行 Prompt/执行记录），一点不会立刻执行；详情提供「执行/重新执行」「删除（带确认）」「查看会话（跳转到真实 transcript）」
- 真实执行：点击「执行」后通过客户端 runtime 连接工作区会话（复用空白会话或 host 新建），把任务标题设为会话名，以任务 Prompt 调用 session.prompt 驱动真实 agent；订阅会话快照直到本轮结束，把卡片置为已完成/已失败并记录结果
- 定时任务：详情面板可启用 5 段 cron 表达式（分 时 日 月 周，支持 `*` / `*/n` / `a-b` / 逗号列表）与常用预设（每天 09:00、每小时、每 10 分钟、每周一 09:00）；启用即计算并持久化「下次运行时间」，卡片显示定时标识
- Host 文件持久化：权威 v3 台账保存到 Host 端 profile 隔离路径，存储 Project、紧凑 Task Run、派生 Evidence 与可选的持久调度状态；写入串行并原子发布，损坏文件保留，v2 文档迁移前先复制备份
- 系统提示词注入：host 半边通过 SystemPrompt.section 注册 `plugin:task-board` 段（order 200），向每个 agent 声明本插件存在、能力与限制，卸载后该段落自动消失

## 技术实现
- **语言**: TypeScript（ESM，host + client 双半区）
- **关键依赖**: `@deepseek-ai/cordis`（cordis 插件骨架）、`@deepseek-ai/dsh-client-runtime` / `dsh-client-connection` / `dsh-client-ui-settings`（客户端运行时服务）、`@deepseek-ai/dsh-host-webserver` + `dsh-system-prompt`（Host 路由与系统提示词注入）、`schemastery`（配置 Schema）
- **架构模式**: 官方 cordis bundle 形态，patch.yml 把 `ui-task-board` 行插入 web profile；host 半区在 dsh host 进程跑（SystemPrompt + 文件存储 + 固定路由），client 半区在浏览器跑（runtime 服务接线 + DOM 挂载），两侧通过 cordis inject 互相依赖
- **入口文件**: `src/index.ts`（host loader）+ `src/client/index.ts`（client apply），打包产物 `lib/index.js` / `lib/client.js`

## 适用场景
用户需要把 DSH 里零散的 agent 任务从「临时会话」提升为「可追踪、可管理、可定时自动化」的工作流。典型场景：运维同学需要在固定时间点跑同一组提示词（数据巡检、日报生成）、团队需要把任务执行状态沉淀到 Host 端做审计、个人希望把灵感异步跑成可复现的 DSH 会话。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH runtime | >=0.1.0-rc.7 <0.2.0 | package.json#dsh.compatibility.runtime 显式声明 |
| DSH Desktop | >=2.7.0 <3.0.0 | package.json#dsh.compatibility.desktop 显式声明，2.6 任务支持 Worktree 模式 |
| Python Native API | ^1.2.0 | package.json#dsh.compatibility.desktop.api 声明 |
| Node | ^22.19 \|\| >=24 | 源码未声明 engines，遵循 monorepo 约定；devDependencies 含 @types/node ^22.20.0 |
| React | ^18.2.0 | peerDependencies 声明，client 半区是 React 应用 |
| 平台 | 跨平台 | 纯 JS/TS 实现，无原生模块依赖 |

## 安装方式
```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-task-board
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| enabled | 开关 | 插件总开关。关闭后不再向 agent 注入系统提示词，看板入口也不再挂载 | true |
| announceToAgent | 开关 | 是否在每个 agent 的系统提示词里宣布「任务看板」插件存在。关闭后 agent 只能从用户口中得知本插件 | true |
| profileName | 字符串 | Host 端 ledger 归属于哪个 DSH profile 目录；不指定则取 `DSH_PROFILE` 环境变量，未设置时为 `web` | 运行时 `DSH_PROFILE` 或 `web` |

> 配置项在 Web GUI 的「插件设置」面板里展示，按 `task-board` 命名空间持久化；保存后立即生效，无需重启。

## 常见问题

**Q: 这个插件能干什么？**

A: 在 DSH Web 界面侧边栏新增「任务看板」入口；点击后中间列切换为多列卡片板（待规划/待办/进行中/已完成/已失败），可以创建任务、立即执行（驱动真实 agent 会话）、按 5 段 cron 表达式自动调度。

**Q: 任务执行会消耗 API 额度吗？**

A: 会。每次执行都通过客户端 runtime 创建真实工作区会话并以 session.prompt 驱动 agent，消耗与普通会话相同的 API 配额。

**Q: 任务数据存在哪里？**

A: 权威 v3 台账在 Host 端 `DSH_HOME/profiles/<profile>/state/task-board/tasks-v3.json`；profile 默认取运行时 `DSH_PROFILE` 或 `web`。Host 端点不可用时回退到 v2 Host 路径或浏览器 localStorage v1。

**Q: 定时任务必须一直打开看板吗？**

A: 不一定。Desktop 2.7 在用户明确开启后台自动化且 Runtime Provider 提供 host-job 适配器时，Host 会以租约、时区 cron 和确定性 TaskRun 认领到期槽位（关闭浏览器也能跑）。其他情况（旧 Web Host、状态格式异常、没有 adapter）由浏览器标签页的 ticker 兜底，需要标签页保持打开，错过即跳过不排队。

**Q: 错过了 cron 触发点会补跑吗？**

A: 默认 skip。睡眠/重启期间错过的触发点全部跳过，`nextRunAt` 从当前时间向后滚动。显式 `run-once` 最多合并补跑一个槽位，`queue-next` 在任务运行中最多保留一个待执行槽位。

**Q: 卸载后任务数据会丢失吗？**

A: 不会。卸载仅移除 profile 里的插件注册行并恢复 GUI 原状，ledger 文件保留在 Host 端 state/task-board 目录。

**Q: 安装后还需要做什么？**

A: 需重启 `dsh web` 进程。profile 层（bundle 行、dsh.client 元数据）只在进程启动时读取，单纯页面刷新不会让入口生效。

**Q: Worktree 审核模式是什么？**

A: Desktop 2.6 任务可选择 shared-workspace 或 Git Worktree。Runtime Provider 提供 workspace/session 观察能力时 Host 创建受控 Worktree，详情展示有界 Evidence 并提供 Commit / Merge / Keep / 二次确认 Discard；缺少能力时明确回退到 shared-workspace，不伪造隔离状态。

**Q: 怎么阻止插件向 agent 暴露自己？**

A: 在 Web GUI 插件设置里把 `announceToAgent` 关闭即可，保存后 `plugin:task-board` 段会从系统提示词里实时撤掉。

## 上手难度
入门 — 安装一行命令、重启 GUI 后即可看到入口；配置只暴露 3 个开关/字符串字段，全程图形化操作；执行与调度都走 DSH 自身的会话机制，不需要写代码。

## 已知问题与限制
- 持久 Host Scheduler 仅在 Desktop Runtime Provider 有意提供 host-job adapter 时启用（通常以用户明确开启后台自动化为前提）；其余运行时（旧的 Web Host、状态路由不可用或格式错误）保留浏览器调度回退
- 应用完全退出后不承诺调度继续执行；持有可执行归属的 Host 进程停止后到期任务会被跳过
- Host 在派发前推进 `nextRunAt` 并写入确定性 TaskRun；旧 owner 租约过期后，只会以原确定性 key 重派尚未记录会话身份的已认领运行
- Worktree 执行依赖可选 Runtime Provider 能力；缺少能力时使用 shared-workspace，不会伪造隔离状态
- 浏览器侧 scheduler 是 60s 心跳 + 标签页恢复即时补 tick；正在运行的任务到点会被 runTask guard 拒绝，落到下一次 cron
- 多个同源浏览器标签页共享同一份台账（Host 通过 SSE 同步），删除任务不会从其他标签页的陈旧副本中被写回复活

---

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