# @goodandready/dsh-kanban 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-kanban/

版本：0\.2\.43
npm 元数据更新时间：2026-11-14T15:46:20.787Z
中文译文更新时间：2026-11-16T19:13:32.174Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-kanban
原文对照：https://npmcn.com/package/%40goodandready/dsh-kanban/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-kanban#readme
源码仓库：https://github.com/GooDAnDReaDY/dsh-kanban

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：785 kB，59 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-llm \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0，@deepseek-ai/dsh-agent \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0，@deepseek-ai/dsh-tools \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0，@deepseek-ai/dsh-session \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0，@deepseek-ai/schemastery ^3\.18\.1，@deepseek-ai/dsh-settings \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0，@deepseek-ai/dsh-credentials \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0
- 首次发布：2026-08-31T18:24:01.073Z
- 最新版本发布：2026-11-14T15:46:20.628Z
- 近 30 天下载量：4143（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

面向DeepSeek Harness的可视 Kanban 板:由 Gitea 和 GitHub 支撑的任务,工作流程列,以及每个任务的专用代理会话.

## 安装

```sh
npm install @goodandready/dsh-kanban
```

也可以使用：`pnpm add @goodandready/dsh-kanban`、`yarn add @goodandready/dsh-kanban`、`bun add @goodandready/dsh-kanban`

## README

# 📦 @goodandready/dsh-kanban

### 面向 DeepSeek Harness 的可视化看板与任务智能体独立会话调度引擎

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-kanban.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-kanban) [![license](https://img.shields.io/github/license/GooDAnDReaDY/dsh-kanban.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-kanban/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![作者全部项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E5%85%A8%E9%83%A8%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-kanban/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-kanban/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-kanban/README.zh.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

## ⚡ 核心定位与解决痛点

当多个自主 AI 智能体并行执行复杂研发任务时，极易发生上下文混乱、PR 审查脱节及分支生命周期失控。若缺少统一的可视化看板，开发者只能在数十个聊天窗口与代码托管平台之间来回切换与人工对齐状态。

**`@goodandready/dsh-kanban`** 为 DeepSeek Harness 提供了原生集成的**交互式看板系统**。看板上的每张卡片均绑定**专属独立的智能体执行会话**。卡片在工作流泳道之间的拖拽移动会自动向智能体派发针对性的阶段指令（如开始编码、提交审查、部署上线或清理环境），并全程与 **Gitea / Forgejo 保持毫秒级双向同步**。

* * *

## 🏗️ 架构设计

```mermaid
graph LR
    subgraph UI ["DeepSeek Harness Web UI 界面"]
        Board["交互式看板<br/>(Backlog, In Progress, Review, Deploy, Cleanup, Done)"]
        Intake["任务创建弹窗<br/>(LLM 模型与 Worktree 选择)"]
        HeaderChip["聊天头部状态胶囊<br/>(活跃任务计数与快速直达)"]
    end

    subgraph Core ["dsh-kanban 核心引擎"]
        Dispatcher["会话调度派发器<br/>(通过 agent.followup 发送阶段指令)"]
        Store["SQLite 任务存储库<br/>(状态机、流转日志与会话关联)"]
        SyncEngine["双向同步引擎<br/>(Issue、PR、分支与 Webhook)"]
    end

    subgraph Agents ["智能体独立执行会话"]
        Agent1["智能体: 任务 #42<br/>(Worktree 编码开发)"]
        Agent2["智能体: 任务 #53<br/>(PR 审查中)"]
    end

    subgraph VCS ["私有 Gitea / Forgejo 实例"]
        GiteaIssues["Issue 任务与里程碑"]
        GiteaPRs["Pull Request 与分支"]
        Webhook["事件通知 (/dsh-kanban/webhook)"]
    end

    Board -->|用户拖拽卡片| Dispatcher
    Dispatcher -->|派发阶段指令| Agent1
    Dispatcher -->|移回 Backlog 时安全取消| Agent2
    Board <-->|CRUD 读写| Store
    SyncEngine <-->|轮询 / Webhook| VCS
    SyncEngine -->|状态对齐| Store
    Store -->|实时刷新 UI| Board
```

* * *

## ✨ 核心特性深度解析

### 1\. Web UI 原生交互式看板

-   **两种工作流模式**：
    -   **Project 专业模式（6 泳道）**：`Backlog` ➔ `In Progress` ➔ `Review` ➔ `Deploy` ➔ `Cleanup` ➔ `Done`。
    -   **Simple 敏捷模式（4 泳道）**：`Backlog` ➔ `In Progress` ➔ `Review` ➔ `Done`。
-   **拖拽即触发工作流**：卡片拖入新列立即触发底层智能体的对应阶段任务。
-   **顶部导航状态胶囊**：在聊天头部实时展示正在进行的任务数，支持一键呼出看板或跳转专属会话。
-   **信息高密度卡片**：展示关联 Issue 编号（`#42`）、所用模型、绑定 Worktree 路径、Git 分支及未提交代码变更。

* * *

### 2\. 任务到智能体专属会话调度器

看板不仅是视觉展示，更是智能体的指令调度中枢：

| 目标泳道 | 调度器触发动作 | 发送给智能体专属会话的指令 |
| :-- | :-- | :-- |
| **`Backlog`** | 🛑 **停止当前轮次** | `agent.cancel({ kind: 'user' })` — 优雅暂停智能体执行，保留上下文 |
| **`In Progress`** | ⚡ **启动开发** | _“按照标准流程开始或继续该任务的编码实现。”_ |
| **`Review`** | 🔍 **请求代码审查** | _“将工作推进至审查阶段：解除 PR 草稿状态并请求人工复核。”_ |
| **`Deploy`** | 🚀 **合并部署上线** | _“合并 Pull Request 并上线。移入 Deploy 泳道即代表用户明确许可。”_ |
| **`Cleanup`** | 🧹 **清理分支环境** | _“清理任务环境：删除远端与本地分支、移除 Worktree，并在 Issue 记录总结。”_ |
| **`Done`** | 🔒 **仅人工 / 事实关闭** | 在 Gitea Issue 关闭后自动归档完成 |

* * *

### 3\. 与 Gitea / Forgejo 持续双向同步

-   **实时对齐机制**：后台定时轮询与 Webhook 接收器（`/dsh-kanban/webhook`）无缝同步 Issue 标题、标签、PR 状态及关闭事件。
-   **时间戳冲突解决**：精准的时间戳仲裁逻辑，杜绝在网页端与代码仓库同时编辑时的状态覆盖问题。
-   **一键生成关联任务**：在看板新建任务可自动在 Gitea 创建 Issue 与独立的 Git Worktree 隔离分支。

* * *

### 4\. 智能体专属工具与安全防护

| 工具名称 | 作用域 | 功能描述 | 安全约束 |
| :-- | :-- | :-- | :-- |
| `board_move` | 看板 | 允许智能体自主汇报进度并推进卡片至下一阶段 | ⚠️ 严禁移动至 `done`（必须由人工或事实关闭） |
| `board_plan` | 看板 | 将结构化分步实施计划持久化写入任务卡片 | \- |

* * *

## 📦 快速安装

通过 DeepSeek Harness 命令行一键安装：

```bash
dsh plugin --profile web add @goodandready/dsh-kanban
```

重启 DSH Web UI 并强制刷新浏览器页面（`Ctrl+F5` 或 `Cmd+Shift+R`）。

* * *

## ⚙️ 配置指南

在 Web UI 中打开 **设置 -> 插件 -> Kanban**：

```yaml
# config.yaml
dsh-kanban:
  boardKind: "project"
  giteaUrl: "https://gitea.yourcompany.com"
  giteaTokenEnv: "GITEA_TOKEN"
  giteaOwner: "my-team"
  giteaRepo: "main-app"
  syncIntervalMs: 30000
  webhookSecret: ""
```

### 配置参数速查表

| 配置项 | 数据类型 | 默认值 | 功能说明 |
| :-- | :-- | :-- | :-- |
| `boardKind` | `string` | `"project"` | 看板模式：`"project"`（6 泳道）或 `"simple"`（4 泳道） |
| `gitProvider` | `string` | `"auto"` | 活动 Git 平台：`"auto"`（按凭证自动检测）、`"gitea"` 或 `"github"` |
| `githubTokenRef` | `string` | `""` | 包含 GitHub PAT 或应用令牌的 DSH 凭证名称 |
| `githubOwner` | `string` | `""` | 默认监听的 GitHub 组织或用户名 |
| `githubWebhookSecretRef` | `string` | `""` | 包含 GitHub Webhook 密钥的 DSH 凭证名称 |
| `giteaUrl` | `string` | `""` | 用于同步任务的 Gitea / Forgejo 实例基础地址 |
| `giteaTokenEnv` | `string` | `"GITEA_TOKEN"` | 存储 Gitea API Token 的 DSH 凭据键名 |
| `giteaOwner` | `string` | `""` | 默认同步的仓库所属组织或用户名 |
| `giteaRepo` | `string` | `""` | 默认绑定的代码仓库名称 |
| `syncIntervalMs` | `number` | `30000` | 后台轮询同步的时间间隔（毫秒） |
| `webhookSecret` | `string` | `""` | 用于校验 Gitea Webhook 请求签名的可选密钥 |

* * *

## 🧪 测试与校验

运行超过 520 个完整的单元测试与集成测试：

```bash
npm test
```

* * *

## 📄 开源许可证

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## 公共组合服务

服务器端暴露可选的 dshKanban 组合服务。其 createTask({ title, body, board, column, labels, owner, repo, issueNumber, issueUrl, externalRef }) 方法校验目标看板和列，通过现有的 SQLite 存储路径 保存任务，并返回 { ok, task, taskId, alreadyExists }。重复的 externalRef 会返回原有卡片，重启后仍然有效。

该服务只创建卡片，不启动代理、不创建分支或 worktree，也不接受调用方传入的 凭据。任务供应的规范消费者契约是 dsh-drives.task-provision.v1。

## 常见问题

### @goodandready/dsh-kanban 是什么？

面向DeepSeek Harness的可视 Kanban 板:由 Gitea 和 GitHub 支撑的任务,工作流程列,以及每个任务的专用代理会话\.

### 如何安装 @goodandready/dsh-kanban？

在项目目录运行 npm install @goodandready/dsh-kanban，或使用 pnpm add / yarn add / bun add。

### @goodandready/dsh-kanban 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-kanban 是否存在。

### @goodandready/dsh-kanban 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-kanban 可以商用吗？

@goodandready/dsh-kanban 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-kanban 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-kanban 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,143 次，日均约 138 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-kanban 还在维护吗？

最新版本 0\.2\.43 发布于 2026/11/14（2 天前）；至今共发布 62 个版本，其中过去 12 个月发布了 62 个；首次发布于 2026/09/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

