任务看板 jeremytenjo/dsh-plugin-backlog-md

面向 DeepSeek Harness 的 Backlog.md

在 DeepSeek Harness 里原生使用 Backlog.md 管理任务。插件在 Source Control 旁边加了一个 Backlog 启动器，在 Harness 原生右侧面板里渲染任务视图，并为当前工作区启动和管理官方 Backlog.md 本地服务器。

Backlog.md 始终是唯一数据源。插件不会另建一套任务数据库，也从不自己写任务 Markdown。

Harness 右侧面板里的 Backlog 任务表格

功能

- 原生启动器 —— Source Control 旁边一个 ListTodo 按钮，尺寸、悬停效果、提示、焦点环、面板开关行为都与原生一致。Backlog 激活时按钮高亮。
- 原生右侧面板 —— 注册为侧边栏标签页类型，因此沿用 Harness 的缩放、折叠、全屏、焦点和按会话持久化。聊天和智能体会话保持挂载。
- 零服务器配置 —— 自动识别工作区的 Backlog.md 项目，找到已安装的命令行，分配回环端口，按需启动 backlog browser，等待健康检查通过后连接。你永远不用手动跑 backlog browser。
- 安全复用与归属 —— 每个规范工作区只对应一个受管服务器，多个 Harness 会话共用它。不是插件启动的服务器，插件绝不终止。
- 只用官方 API —— 任务和里程碑的读写都走 Backlog.md 的 HTTP API。
- 实时同步 —— Host 订阅 Backlog.md 的 WebSocket 通知，把变更范围转发给面板，面板据此让 TanStack Query 缓存失效。不重复挂文件系统监听。
- 宽表格与紧凑列表 —— 同一个 TanStack Table 实例驱动两种呈现。CSS 容器查询按面板真实内容宽度切换，而不是视口宽度。筛选、排序、选择、展开、详情导航在切换后都保留。
- 完整任务工作流 —— 新建、编辑、改状态或优先级、指派、标签、里程碑、依赖、验收标准、Definition of Done、子任务、归档、永久删除。
- 冲突感知编辑 —— 未保存的编辑在后台刷新后仍在；保存前检测外部改动，明确让你选择重新加载或合并。绝不静默覆盖。
- 发送到聊天 —— 把可直接编辑的提示词放进当前 Harness 输入框。绝不自动发送消息。
- 对智能体友好 —— Backlog.md 命令行、MCP 服务器、Codex 或其他编辑器做的改动，都通过同一套 WebSocket 通知出现。智能体侧无需任何插件集成。

截图

| 完整表格 | 窄面板 |
| 任务表格 | 紧凑任务列表 |

| 任务详情 | 筛选后的表格 |
| 任务详情 | 筛选后的表格 |
启动器就放在编辑器的 Source Control 旁边：

Source Control 旁的 Backlog 启动器

环境要求

| 组件 | 支持情况 |
| DeepSeek Harness | 已在 0.2.1-rc.3 上测试。插件使用公开的 Cordis 生命周期，以及 slots、locale、sidebarRightTabs、sidebarRight、webServer、subprocess、sessions、workingDirectory 服务。 |
| Backlog.md | 已在 1.55.3 上测试；1.54.0 也在 Harness UI 中验证过。支持范围：>=1.30.0 <2.0.0。 |
| Node | Host 上需要 22 或更高版本。发布的插件没有运行时 npm 依赖。 |
| 操作系统 | 只要 Backlog.md 的原生命令行能运行，macOS、Linux、Windows 都可以。 |

Backlog.md 必须装在工作区里（node_modules/.bin/backlog），或者能在 PATH 上找到。工作区本地安装优先。还需要一个已初始化的 Backlog.md 项目；如果缺少项目，面板会显示具体的 backlog init 命令。

安装

桌面应用（推荐）

1. 打开 Settings → Plugins。
2. 选择 Add plugin，输入本地目录路径（或 GitHub 仓库）。
3. 确认插件已启用，然后刷新页面或重启 Host。

桌面配置档由 Electron 应用管理，所以在桌面端，Settings 流程就是受支持的安装方式。

命令行

克隆仓库，把它加到配置档里：

git clone https://github.com/jeremytenjo/dsh-plugin-backlog-md.git
dsh plugin --profile <profile> add ./dsh-plugin-backlog-md

也可以用 GitHub 地址：

dsh plugin --profile <profile> add github:jeremytenjo/dsh-plugin-backlog-md

用服务于你 Harness 实例的配置档（比如 web）。包内已附带构建好的 client.js，安装时不需要构建步骤。

首次运行

1. 把 Backlog.md 装到工作区里，或装到 PATH 上：

npm install --save-dev backlog.md
or: pnpm add -D backlog.md
or: npm install -g backlog.md

2. 如果项目还没初始化，先初始化一次：

backlog init
or non-interactive defaults:
backlog init --defaults

3. 在该工作区打开 Harness 会话，点击 Source Control 旁的 Backlog。

面板会自己启动服务器，不需要 backlog browser 命令。

使用

启动器与面板

Backlog 按钮注册在编辑器的 conversation.input.right 槽位，顺序为 11，紧跟在 Source Control 触发器（顺序 10）之后。点击它会在原生右侧边栏打开 backlog-md 标签页。Backlog 已激活时再次点击，行为与 Harness 原生面板的切换一致。面板注册时带了 keepMounted: true，所以关闭再打开会保留原有状态。

筛选

列表上方的状态条会显示每个状态的数量，同时兼作状态筛选。搜索能进一步缩小范围；Exclude status、Priority、Milestone、Label、Assignee 都在 筛选器负责控制和组合，无需重新加载。头部显示筛选后的数量；清除筛选器会重置全部条件。筛选、排序、列可见性和每页条数按工作区保存在 localStorage 中；那里不存任何任务数据。

两种呈现方式都按关注度顺序打开：进行中在前，待办其次，已完成最后；同一状态内先按 Backlog.md 序号、再按自然 ID 排序。点击列头会覆盖当前工作区的这个默认顺序。

宽表格

列包括：ID、标题（含子任务进度）、状态、优先级、序号、标签、负责人、里程碑、创建时间和行操作。表格支持固定表头、紧凑行、悬停与聚焦状态、列排序、行选择（把选中的任务发送到输入框）、可展开子任务和可配置的列可见性。面板宽度较窄时，固定布局的列会离开 DOM，容器变宽后再重新出现。

紧凑列表

面板容器低于 640px 断点时，紧凑列表显示标题、ID、子任务进度、状态、优先级、负责人和相对创建时间。它永远不需要横向滚动。两种呈现方式读取同一个 TanStack Table 实例，所以切换宽度时筛选、排序、选择、展开、分页和详情处理函数都保持不变。

任务详情

点击某一行，会在同一面板内进入详情。头部有返回按钮、任务 ID、可编辑标题和操作。元数据包括状态、优先级、负责人、标签、里程碑、父任务、依赖链接、创建与更新日期，以及服务器归属/来源。内容包括 Markdown 描述源文、验收标准、完成定义清单、子任务和依赖。评论只读显示。

底部显示未保存状态，并提供保存/取消。详情视图：

- 后台重新拉取时保留本地编辑；
- 保存前检测外部变更；
- 提供重新加载最新版本或合并我的编辑，并逐字段说明；
- 绝不静默覆盖外部变更；
- 归档和永久删除前会确认。

发送到聊天

行菜单和详情菜单都包含发送到聊天。它会识别当前 Harness 会话，构造类似下面的提示词：

Implement TASK-20.4 "Wire real-time sync" using its Backlog.md task definition. Follow AGENTS.md,
update task status as work progresses, and verify all acceptance criteria.

然后调用官方输入框的 inputActions.setDraft(...)。它不会提交。发送前，完整提示词可见且可编辑。

外部智能体变更

编码智能体可以照常使用 Backlog.md 命令行或 MCP 服务器：

1. 命令行编辑 Markdown 文件。
2. Backlog.md 的 ContentStore 检测到变更。
3. Backlog.md 服务器广播 WebSocket 通知。
4. Host 中继收到通知，并把变更范围暴露给面板。
5. TanStack Query 让受影响的任务、里程碑、任务详情或配置查询失效。
6. 面板重新拉取数据并重新渲染。

短时间内的连续事件会做防抖处理。重新连接时请求一次全量同步，补回错过的事件。

架构

┌──────────────────────────── DeepSeek Harness ────────────────────────────┐
│ │
│ React panel (client.js) Host plugin (index.js) │
│ ┌────────────────────────┐ same-origin ┌──────────────────────────┐ │
│ │ BacklogPanel │ POST /__dsh/ │ BacklogBridge │ │
│ │ TanStack Query │ backlog-md │ session → workspace │ │
│ │ TanStack Table │ ─────────────► │ fixed action allowlist │ │
│ │ shadcn/ui + Tailwind │ ◄───────────── │ typed validation │ │
│ └────────────────────────┘ JSON + long └──────────┬───────────────┘ │
│ │ poll │ │
│ │ ▼ │
│ │ ┌──────────────────────────┐ │
│ │ │ BacklogServerManager │ │
│ │ │ one record per realpath │ │
│ │ │ port allocation │ │
│ │ │ health + version gate │ │
│ │ │ crash budget + cleanup │ │
│ │ └──────────┬───────────────┘ │
│ │ │ spawn │
│ │ ▼ │
│ │ ┌──────────────────────────┐ │
│ │ │ backlog browser │ │
│ │ │ 127.0.0.1:<dynamic port> │ │
│ │ └──────────┬───────────────┘ │
│ │ │ │
│ │ WebSocket notifications │ │
│ │ ┌──────────▼───────────────┐ │
│ └──────────────────────────────│ BacklogEventHub │ │
│ │ ring buffer + long poll │ │
│ └──────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘

Backlog.md Markdown files (single source of truth)

宿主侧的工作区解析

浏览器从不发送文件系统路径，只发送当前 Harness 会话 ID。宿主用 ctx.sessions.get 解析出会话，再用 ctx.workingDirectory.get，用 realpath 做规范化，再向上查找最近的 Backlog.md 项目（backlog/config.yml、.backlog/config.yml、backlog.config.yml 或 backlog.json）。规范化后的项目根目录就是服务器归属身份。

BacklogServerManager

- 用 net 分配一个空闲回环端口，再启动官方命令行：

backlog browser --port <port> --no-open

- 如果因为竞争，命令行选了另一个端口，管理器会解析它打印的 URL，改用实际端口。
- 轮询 GET /api/status 和 GET /api/version 直到健康，校验返回的 projectPath 与规范化工作区一致、版本在支持范围内。
- 复用健康的管理服务器。并发调用共享同一次进行中的启动。
- 检查项目配置的 default_port，看是否已有兼容服务器在运行；项目身份和版本都匹配时接管它，标记 owned: false。绝不终止它。
- 用有上限的重启预算跟踪崩溃，清理失效记录，让下一次面板请求启动新服务器。
- 服务器只绑定 127.0.0.1。动态端口绝不暴露给浏览器。
- 只在插件销毁和空闲清理时停止自己拥有的进程（默认 30 分钟）。

HTTP 桥

只有一条精确路由 POST /__dsh/backlog-md，是插件唯一面向浏览器的接口。它：

- 只接受 POST 和 application/json；
- 要求回环套接字和 Harness 源（ctx.webServer.getOrigin()），拒绝 Sec-Fetch-Site: cross-site；
- 请求体上限 512 KiB，响应上限 16 MiB；
- 从会话解析工作区，绝不从请求解析；
- 暴露固定动作集（status、tasks.list、tasks.get、tasks.create、tasks.update、tasks.archive、tasks.delete、tasks.reorder、milestones.list、milestones.create、search、server.restart、events）；
- 在信任边界校验任务 ID、数组、长度和类型；
- 从任务响应中剥掉 filePath 和 rawContent，从 /api/config 中剥掉 mcp、onStatusChange 以及其他携带命令的配置。

events 是基于 Host 的 WebSocket 中继的长轮询（等待窗口 12 秒）。这样浏览器始终走一条同源、经过校验的传输通道，也能穿过 Harness 的 Electron fetch 桥。

使用的 API 接口

| 用途 | 官方端点 |
| 项目身份 / 健康 | GET /api/status |
| 版本门禁 | GET /api/version |
| 配置 | GET /api/config |
| 状态 | GET /api/statuses |
| 列出任务 | GET /api/tasks |
| 任务详情 + 依赖图 | GET /api/task/:id |
| 创建任务 / 子任务 | POST /api/tasks |
| 更新任务 | PUT /api/tasks/:id |
| 归档任务 | POST /api/tasks/:id/archive |
| 重排任务 | POST /api/tasks/reorder |
| 里程碑 | GET /api/milestones、POST /api/milestones |
| 搜索 | GET /api/search |
Backlog.md 没有 HTTP 硬删除端点。永久删除走官方 API 归档，然后调用官方命令行（backlog task delete <id>），参数用 argv 数组传入，不经过 shell。默认的破坏性操作是归档，会保留 Markdown 记录、ID 和链接。

实时中继

BacklogEventHub 为每个受管服务器维护一个 WebSocket 客户端。它能识别当前服务器发布的消息：tasks-updated、milestones-updated、config-updated、loaded、加载状态 JSON 和 pong。事件存入一个 200 条容量的环形缓冲区，序号单调递增。游标比环形缓冲区更旧时返回 resync，每次重连也会请求一次完整 resync。等待方受超时和取消约束。React 钩子对失效做 150 ms 防抖，用有界指数退避重连（1 s 到 15 s），并在出现缺口后重新拉取所有受影响的缓存。

为什么浏览器从不直接连接 Backlog.md

Backlog.md 服务器是功能强大的本地 HTTP 服务，没有内置授权。把它的端口暴露给页面，任何本地脚本或浏览器源都能访问，还会绕过 Harness 的会话授权。桥接层让服务器只监听回环地址，只把面板需要的操作交给浏览器，且仅限当前 Harness 会话所属的工作区。

开发

pnpm install
pnpm typecheck # TypeScript, tests included
pnpm lint # Biome
pnpm test # 21 client tests + 20 host tests (real Backlog.md CLI)
pnpm build # regenerates client.js (Tailwind + esbuild bundle)
pnpm verify # lint, typecheck, test, build

src/client.tsx 是浏览器入口。src/server/** 是 Host 部分。client.js 是生成产物，已提交到仓库；客户端源码有改动时，用 pnpm build 更新它。

Host 集成测试会安装并使用固定版本的 backlog.md 开发依赖。测试会创建临时项目，在动态端口上启动真实服务器，验证复用、接管、崩溃恢复、端口冲突、工作区隔离，跑遍每个变更操作，检查 WebSocket 中继，并确认回环与来源防护生效。测试在 macOS 上使用 DeepSeek Harness 0.2.1-rc.3 和 Backlog.md 1.55.3 执行。

目录结构

index.js Host plugin entry: route + manager lifecycle
src/server/ workspace, CLI, API client, manager, event hub, bridge
src/client.tsx Cordis client registration
src/client/components/ panel, table, list, details, dialogs, shadcn/ui primitives
src/client/hooks/ TanStack Query hooks, connection relay, persisted UI state
src/client/api/bridge.ts typed bridge client
src/client/lib/ task tree, filters, formatting, utilities
test/ client (Vitest) and host (node:test) suites
docs/ screenshots

安全概要

- 受管服务器只绑定 127.0.0.1，不对外暴露 API。
- 浏览器操作只使用一条同源、仅限回环的 Host 路由。
- 请求从不提供工作区路径、服务器 URL、可执行文件或命令。
- 进程执行使用 argv 数组，从不经过 shell。调用 CLI 之前会先校验任务 ID。
- 响应体和任务 ID 都有长度上限；响应格式异常时按失败处理。
- 配置经过净化；MCP token 和命令字段永远不会进入浏览器。
- API 变更会保留未知的任务元数据（插件只发送改动的字段）。
- localStorage 里只存展示状态；没有任务缓存数据库。

故障排查

| 面板状态 | 操作 |
| Backlog.md is not installed | 在工作区或 PATH 中安装 backlog.md，然后按 Retry。 |
| Initialize Backlog.md | 在工作区运行 backlog init，然后按 Retry。 |
| Backlog.md needs an update | 安装 1.30.0 或更高版本的 1.x 发行版。 |
| Backlog.md is unavailable / crashed | 按 Retry 或 Restart server。Retry 还会重置崩溃预算。 |
| 服务器启动成功，但任务一直不同步 | 检查工作区是不是目标项目，以及防火墙是否拦截了回环。重新打开面板强制重新同步。 |
| 端口被占用 | 管理器会让 CLI 自动选择下一个空闲端口。 |

兼容性说明

- Backlog.md 1.54.0 的部分 HTTP 端点返回不带时区的 YYYY-MM-DD HH:mm 时间戳；UI 会按 UTC 解析。带 Z 的 ISO 时间戳按正常方式处理。
- Backlog.md 1.55.3 是锁定的测试版本。管理器会拒绝 2.x 以及低于 1.30.0 的版本，并给出可操作的错误提示。
- 插件不发布到 npm。请从本地检出或 GitHub 安装。
- 手动启动的服务器只有满足以下条件才会被复用：监听项目配置的 default_port，上报相同的规范化 projectPath，且版本受支持。不会扫描任意端口。

已知限制

- Markdown 只保留，不解析。 描述以 Markdown 源码形式显示和编辑，放在等宽文本域里。插件有意不引入第二个 Markdown 解析器。Harness 其他位置的渲染器仍负责富文本渲染。
- 永久删除需要 CLI。 Backlog.md 通过 HTTP 只提供归档，不提供硬删除。因此永久删除操作是归档加官方 backlog task delete CLI；如果任务还有子任务或链接，CLI 可能拒绝，面板会报告这次拒绝。
- 外部服务器发现范围有限。 管理器只能在项目配置的默认端口上验证已有服务器。不会探测任意端口上的服务器。
- 一个 Host，一个管理器。 同一个 Harness Host 内的会话共享服务器。不同的 DSH 进程各自管理自己的服务器；插件不跨进程协调。
- 不推断智能体活动。 面板显示任务状态，不会声称某个智能体
- 只因为任务状态是 In Progress 就继续做。
- Send to Chat 依赖输入框。 面板收到内容时，优先调用官方 inputActions.setDraft；如果调用不到，就回退到启动器事件。输入框不可用时，面板会提示无法连接。

许可证

MIT。见 LICENSE。

Backlog.md 是 Alex Gavrilescu 的独立项目，同样采用 MIT 许可证。本插件是独立集成，与 Backlog.md 维护者没有隶属关系。