# dashi-taskboard

> Integrate Codex Taskboard with DeepSeek Harness, add a task panel entry in the sidebar, and bridge to the Taskboard runtime managed by the local launcher.

## Metadata

- Author: [@chuspeeism](https://github.com/chuspeeism)
- Repo: <https://github.com/chuspeeism/dashi-taskboard.git>
- GitHub: [chuspeeism/dashi-taskboard](https://github.com/chuspeeism/dashi-taskboard)
- Stars: 2,407
- Language: JavaScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Topics: `claude-code`, `cli`, `codex`, `codex-app`, `codex-desktop`, `codex-plugin`, `dsh`, `dsh-plugin`, `skills`
- Forks: 314
- Open Issues: 34
- Last push: 2026-08-20T15:25:51.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:chuspeeism/dashi-taskboard/integrations/deepseek-harness
```

## Wiki

## 一句话定位
这是 Codex Taskboard 在 DeepSeek Harness 里的接入插件，它不内置任务面板本身，而是在 DSH 侧边栏添加一个"任务面板"按钮，把当前本地 Codex Taskboard 启动器的页面以内嵌网页的方式展开到 DSH 主区域里。

## 核心能力
- 在 DSH Web 端侧边栏底部新增"任务面板"按钮，点击后在主工作区右侧弹出侧边面板
- 面板内以 iframe 形式加载 Codex Taskboard 的运行页面，等价于在浏览器里直接打开本地 Taskboard
- 服务端在 DSH 内部注册一个跳转路由，把访问 `/integrations/codex-taskboard` 的请求 307 重定向到本地启动器当前报告的活动地址
- 通过读取启动器写入的运行时描述文件来发现活动地址，不依赖固定端口，启动器换端口后插件不需要改配置
- 面板提供"刷新"按钮，可在 Taskboard 服务重启后重新加载内容，提供"关闭"按钮收起面板
- 当运行时描述文件缺失或格式不正确时，跳转路由返回 503 与"Codex Taskboard is not running"文本提示，避免空白错误页

## 技术实现
- **语言**: 原生 JavaScript（ESM 模块，无构建步骤；`package.json` 中 `"type": "module"`，入口直接发布源码）
- **关键依赖**: `@deepseek-ai/dsh-client-ui-sidebar`（DSH 官方客户端包，被 manifest 声明注入）；`@deepseek-ai/cordis`（宿主注入框架，插件通过 `ctx.webServer.register` 注册路由、通过 `ctx.slots.inject` 注册侧边栏按钮）；`react`（客户端 UI 在 DSH 渲染层里用 `React.createElement` 直接构造，未使用 JSX）
- **架构模式**: 双端 Cordis 补丁插件。`cordis.patch.yml` 在宿主启动时插入名为 `codex-taskboard` 的服务节点；服务端 `index.js` 通过 `export const inject = ["webServer"]` 拿到 webServer 句柄后注册 307 重定向路由；客户端 `client.js` 通过 `window.__ModuleLoader__.load` 注册前端模块，注入到 `sidebar.footer.action` 槽位
- **入口文件**: `integrations/deepseek-harness/index.js`（服务端激活入口，导出 `name`、`inject`、`apply(ctx)`）；`integrations/deepseek-harness/client.js`（浏览器端激活入口，挂载 `apply(ctx)` 到 DSH 客户端运行时）

## 适用场景
已经在本机部署并使用 Codex Taskboard 的人，希望把任务列表从独立的浏览器标签或 App 收进 DSH 主窗口里、和对话流并排查看时，安装这个插件即可。它解决的问题是：DSH 默认不带任务管理 UI，而切换窗口来回看 Taskboard 打断思路。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | 未声明 | 插件 `package.json` 没有声明 `engines` 或 `peerDependencies`；通过 `dsh.bundle.patch` 与 `dsh.client` manifest 字段接入宿主 |
| Node.js | 未声明 | 插件本身无 `engines` 字段；宿主 DSH 启动 DSH 进程时负责 Node 版本 |
| 平台 | 跨平台 | 客户端注入 `platform: web`，服务端无原生模块；不过默认运行时文件路径是 macOS 风格（见下） |
| 原生模块 | 无 | 仅使用 `node:fs/promises`、`node:os`、`node:path` 三个 Node 内置模块 |
| 本地 Codex Taskboard | 任意可工作版本 | 插件只是一个跳转壳，真正的 Taskboard 服务来自本机启动器 |

## 安装方式
```bash
dsh plugin --profile web add github:chuspeeism/dashi-taskboard/integrations/deepseek-harness
```

## 配置项
本插件没有用户可配置的字段；只通过一个环境变量影响运行时文件路径：

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `CODEX_TASKBOARD_RUNTIME_FILE` | 环境变量 | Codex Taskboard 启动器写出的活动地址描述文件绝对路径；插件从这里读取当前 URL 并做跳转 | `~/Library/Application Support/Codex Taskboard/launcher-runtime.json`（macOS 默认） |

## 常见问题

**Q: 这个插件能不能独立使用?**

A: 不能。它只是一个 DSH 与 Codex Taskboard 之间的跳转桥；本机必须先有 Codex Taskboard 启动器跑起来，按钮才能跳转到真实页面。

**Q: 安装后侧边栏没出现"任务面板"按钮?**

A: 检查 DSH 是否按 Web profile 启动（`--profile web`），以及插件 manifest 声明的客户端平台是 `web`；非 web profile（如终端 profile）不会注入侧边栏 UI。

**Q: 点了按钮但面板提示"Codex Taskboard is not running"?**

A: 通常是启动器没跑或写入的描述文件路径不对；先启动 Codex Taskboard（`npm run codex` 或 macOS App），再点侧边栏按钮；也可以通过面板上的"刷新"按钮重试。

**Q: 默认的运行时文件路径能直接用在 Windows / Linux 上吗?**

A: 不能直接用。默认路径 `~/Library/Application Support/Codex Taskboard/launcher-runtime.json` 是 macOS 风格的，Windows 上 Taskboard 数据通常在 `%APPDATA%\Codex Taskboard`、Linux 上一般需要 `npm run codex` 自己指定；在 Windows / Linux 上需要先设置 `CODEX_TASKBOARD_RUNTIME_FILE` 环境变量指向正确的描述文件。

**Q: Taskboard 启动器换端口后插件需要改什么吗?**

A: 不需要。插件不依赖固定端口，启动器把当前 URL 写入运行时描述文件、插件读最新值做跳转。

**Q: 怎么卸载?**

A: 用 `dsh plugin --profile web remove` 移除本插件即可；插件本身不存储任何持久数据，移除后下次启动 DSH 不会再注入侧边栏按钮和路由。

**Q: 面板里的"刷新"按钮和"关闭"按钮各自做什么?**

A: "刷新"会递增 iframe 的 `key` 值，强制 iframe 重新加载，跳过浏览器缓存；"关闭"收起右侧面板，保留侧边栏按钮的展开状态直到下次点击。

## 上手难度
入门 — 只需安装插件并确保本地 Codex Taskboard 启动器在跑，没有任何需要填写的高级配置项。

## 已知问题与限制
- 默认运行时文件路径 `~/Library/Application Support/Codex Taskboard/launcher-runtime.json` 是 macOS 风格，在 Windows / Linux 上若不通过 `CODEX_TASKBOARD_RUNTIME_FILE` 覆盖，插件会找不到 Taskboard；本插件的 `package.json` 没有 `os` 字段做平台限制
- 运行时描述文件要求 `version === 1` 且 `url` 为字符串，否则插件直接抛错并返回 503；如果启动器升级到新版本描述格式，需要更新插件判断逻辑
- 跳转路由使用 307 临时重定向并设 `cache-control: no-store`，但浏览器对 iframe 内的跨源行为仍受宿主 CSP 与启动器自身策略约束
- 源码中没有 TODO / FIXME / HACK 注释，暂无显式标注的 bug

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dashi-taskboard](https://deepseek-plugin.org/plugins/chuspeeism/dashi-taskboard/integrations/deepseek-harness)
Wiki generated by AI (model: `MiniMax-M3`)