npm - @goodandready/dsh-kanban - Versions diffs - 0.1.15 → 0.1.17 - Mend

@goodandready/dsh-kanban 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,455 +1,173 @@
-# dsh-kanban
+# 📦 @goodandready/dsh-kanban
-Доска задач для [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): задачи из Gitea, колонки по реальному воркфлоу и отдельная сессия агента под каждую задачу.
+<div align="center">
-## Что умеет
+<h3>Visual Kanban Board & Task Agent Session Dispatcher for DeepSeek Harness</h3>
-- **Ставить задачи и следить за ними.** Свои задачи и задачи из Gitea на одной доске, порядок карточек переживает перезагрузку.
-- **Заводить задачу из issue.** Кнопка «+ Задача» показывает открытые issue выбранного репозитория; уже импортированные приглушены. Карточка заполняется заголовком, телом, метками и ссылкой.
-- **Запускать работу.** Выбрали модель, нажали «Начать» — поднимается отдельная сессия агента по этой задаче, карточка уезжает в «В работе».
-- **Выбирать, чем запускать.** Профиль агента и уровень доступа (`read-only`, `workspace-write`, `danger-full-access`) — списки приходят от харнесса, свои слова доска не выдумывает.
-- **Продолжать в том же чате.** У задачи ровно одна сессия на всю её жизнь. Как только сессия есть, кнопка становится «Продолжить» и открывает прежний чат, а не заводит новый. Перед отправкой видно заготовку сообщения — её можно переписать, уйдёт то, что осталось в поле.
-- **Запускать пачку.** Отметили несколько карточек — все уезжают в одну сессию и приходят агенту по очереди: первая в работе, остальные «в очереди» с номером. Отдельную задачу можно доложить в уже идущую сессию.
-- **Держать доску в порядке.** Счётчик ждущих ответа в шапке, сортировка по дате, отбор по автору, групповые действия над выбранными и остановка агента прямо с карточки.
-- **Показывать задачу в чате.** В сессии, поднятой с доски, в шапке виден чип задачи с текущей колонкой.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-kanban"><img src="https://img.shields.io/npm/v/@goodandready/dsh-kanban.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-kanban.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
-## Установка
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Author Projects"></a>
+</p>
-```bash
-dsh plugin --profile web add @goodandready/dsh-kanban
-```
-Из локальной рабочей копии:
-```bash
-dsh plugin --profile web add file:/путь/к/dsh-kanban
-```
-Перезапустите веб-интерфейс и обновите страницу с очисткой кэша.
-Других плагинов не требует: клиент Gitea у канбана свой. Пока адрес инстанса не задан, доска работает, а импорт честно объясняет, чего не хватает.
-## Настройка
-**Настройки → Плагины**, карточка **Канбан**.
-| Поле | Что задаёт |
-|---|---|
-| Адрес инстанса | `https://gitea.example.com`. Пусто — импорт недоступен. |
-| Имя учётной записи | ИМЯ учётной записи DSH с токеном, по умолчанию `GITEA_TOKEN`. Сам токен сюда не вводить. |
-| Корень проектов | Где лежат рабочие копии. Пусто — рабочая папка харнесса. |
-| Шаблон первого сообщения | Текст, с которого начинается сессия. Пусто — встроенный. Подстановки: `{repo}`, `{issueNumber}`, `{title}`, `{body}`, `{issueUrl}`. |
-| Пределы колонок | Предел числа карточек. Ноль — без предела. |
-Токен в настройках **не хранится**: там только ИМЯ учётной записи, а сам секрет лежит в хранилище учётных данных DSH. Наружу значение не отдаётся никогда, включая сообщения об ошибках. Если у вас уже настроен `GITEA_TOKEN` для других плагинов, достаточно вписать адрес инстанса.
-Все поля настроек скалярные. Это не упрощение, а требование: клиентский API настроек пишет только скаляры, и словарь или массив сделал бы карточку нередактируемой. Доски поэтому живут в хранилище задач, а не в настройках.
-## Колонки
-| Колонка | Признак входа |
-|---|---|
-| Backlog | issue есть, никто не взял |
-| В работе | сессия поднята, в issue есть стартовый комментарий с планом и веткой |
-| Ревью | PR снят с WIP, ревьюер даёт PASS/FAIL |
-| Deploy | PR влит в `main`, ждём согласованный deploy и production-проверку |
-| Cleanup | ветка в Gitea, worktree и локальная ветка ещё не удалены |
-| Done | issue закрыт **и** cleanup записан в итоговом комментарии |
-Колонка `cleanup` не лишняя: по воркфлоу задача не завершена, пока cleanup не сделан и не записан. Доска, отправляющая карточку в `done` по merge, врёт ровно там, где копятся забытые ветки.
-WIP PR **не** двигает карточку в «Ревью»: он открывается рано и означает «работа идёт», а не «смотрите».
-Превышение предела колонки подсвечивается, но перенос не запрещает: предел — ориентир, а не преграда.
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
-## Чего плагин не делает
+</div>
-- **Не создаёт ветки и worktree.** По воркфлоу агент сначала делает preflight — смотрит открытые ветки и worktree, проверяет рабочее дерево — и только потом заводит worktree от свежего `origin/main`. Ветка, созданная заранее, обессмысливает preflight.
-- **Не пишет стартовый комментарий в issue.** Его пишет агент после preflight, потому что до preflight ветка и план неизвестны.
-- **Не подсказывает имя ветки** в первом сообщении: его выбирает агент.
-- Ветка и worktree на карточке — **наблюдение**, а не намерение.
-- Не трогает Hermes Kanban. Это другая система.
+---
-## Хранилище
+## ⚡ Overview & Problem Solved
-`<DSH_HOME>/kanban/kanban.db`, где `DSH_HOME` — переменная окружения либо `~/.dsh`. SQLite через встроенный `node:sqlite`; внешних зависимостей нет.
+Managing concurrent software tasks across multiple autonomous AI agents easily leads to context drift, lost pull request handoffs, and untracked branch lifecycles. Without a dedicated visual board, users must manually juggle disparate chat windows and verify issue states on remote VCS trackers.
-Порядок карточек хранится дробным индексом: перетаскивание — всегда один `UPDATE` одной строки, сколько бы карточек ни было в колонке.
+**`@goodandready/dsh-kanban`** introduces an interactive **Kanban Board** embedded natively into DeepSeek Harness. Every card represents a concrete development task linked to its own **dedicated agent session**. Moving a card between workflow columns automatically dispatches lifecycle instructions directly to the agent (e.g. implementing, opening PRs, deploying, or cleaning up worktrees), with continuous **2-way Gitea/Forgejo synchronization**.
-## Автоперемещение
+---
-**Обратно в Gitea доска сообщает одно: закрытие issue**, когда карточка доходит до «Выполнено». Меток колонок она не ставит — стадия и так видна по ветке и pull request, а метка лишь пересказывала бы то, что уже написано рядом. Заодно доска не трогает чужую разметку вовсе.
+## 🏗️ Architecture
-Карточки двигаются сами. Три источника со строгим приоритетом — **Gitea > инструмент агента > жизненный цикл сессии**. Без приоритета «PR влит → deploy» через секунду перебивалось бы «ход завершился → в работе», и карточка прыгала бы.
+```mermaid
+graph LR
+    subgraph UI ["DeepSeek Harness Web UI"]
+        Board["Interactive Kanban Board<br/>(Backlog, In Progress, Review, Deploy, Cleanup, Done)"]
+        Intake["Task Intake Modal<br/>(Model Picker & Worktree Path)"]
+        HeaderChip["Kanban Header Chip<br/>(Active Tasks & Quick Jump)"]
+    end
-| Наблюдение в Gitea | Колонка |
-|---|---|
-| есть ветка по задаче | В работе |
-| PR открыт и снят с WIP | Ревью |
-| PR влит | Deploy |
-| issue закрыт, ветка ещё есть | Cleanup |
-| issue закрыт, ветки нет | Done |
+    subgraph Core ["dsh-kanban Engine"]
+        Dispatcher["Session Dispatcher<br/>(Dispatches commands via agent.followup)"]
+        Store["SQLite Task Store<br/>(State, History & Session Links)"]
+        SyncEngine["2-Way Sync Engine<br/>(Issues, PRs, Branches, Webhooks)"]
+    end
-Метки и заголовок доска забирает из Gitea при каждой сверке: переименовали issue или сменили `priority/high` на `priority/critical` — доска это увидит. **Тело не забирает** — его правит человек заметкой из чипа, и сверка, затирающая тело каждые две минуты, съедала бы заметки; тело обновляется по кнопке «обновить».
+    subgraph Agents ["Autonomous Agent Sessions"]
+        Agent1["Agent: Task #42<br/>(Coding in Worktree)"]
+        Agent2["Agent: Task #53<br/>(PR Review)"]
+    end
-Каждый переход попадает в журнал задачи с источником и пояснением: `Ревью ← gitea · PR #39 снят с WIP`. Когда доска однажды покажет не то, будет видно, кто её подвинул.
-### Две доски
-Досок ровно две, и обе заводятся сами при первом запуске.
-| Доска | Колонки | Для чего |
-|---|---|---|
-| Проектная | бэклог · в работе · ревью · deploy · cleanup · выполнено | задачи из issue |
-| Простая | бэклог · в работе · проверка · выполнено | свободные задачи |
-`review`, `deploy` и `cleanup` осмысленны только там, где за задачей стоит issue: у свободной заметки нет ни ветки, ни PR, и Gitea о ней ничего не скажет. Три колонки, которые никогда не заполнятся, — не запас на будущее, а помеха.
-Импорт issue на простую доску не предлагается и отвергается сервером. Вид доски — её явное свойство, а не вывод из содержимого: доска, меняющая число колонок от того, что на неё положили, ведёт себя непредсказуемо.
-Прежняя единственная доска СТАНОВИТСЯ проектной вместе со всеми задачами — вторая заводится рядом, а не вместо неё. Смены вида у доски с задачами пока нет: карточки из `deploy` и `cleanup` на простой доске девать некуда.
-### Чип задачи в чате
-В шапке чата, поднятого с доски, виден чип задачи с текущей колонкой. Он умеет три вещи:
-- **перенести в колонку** — то же, что перенос на доске, со всеми последствиями;
-- **перейти к карточке** — открывает доску и сразу окно этой задачи, переключая доску, если карточка лежит на другой;
-- **оставить заметку** — дописывает текст в тело задачи.
-Заметка меняет тело, а тело уходит агенту первым сообщением при запуске. Значит заметка, оставленная до запуска, попадёт в работу, а после запуска — нет; это написано подсказкой рядом с полем, иначе поведение выглядит случайным.
-Дописывает заметку сервер, а не браузер: чип держит копию задачи, и склейка у него потеряла бы всё, что тело нажило с момента её получения.
-### Создание задачи: проект или не проект
+    subgraph VCS ["Gitea / Forgejo Instance"]
+        GiteaIssues["Issues & Milestones"]
+        GiteaPRs["Pull Requests & Branches"]
+        Webhook["Event Webhook (/dsh-kanban/webhook)"]
+    end
+    Board -->|User Moves Card| Dispatcher
+    Dispatcher -->|Sends Stage Instruction| Agent1
+    Dispatcher -->|Cancels on Backlog| Agent2
+    Board <-->|CRUD State| Store
+    SyncEngine <-->|Polls / Webhooks| VCS
+    SyncEngine -->|Reconciles State| Store
+    Store -->|Updates UI Live| Board
 ```
-Новая задача
-  ○ Проект        → репозиторий: выбрать из Gitea либо ввести имя нового
-  ○ Не проект     → уходит на простую доску
-```
-**Проект** заводит issue в Gitea, и карточка сразу к нему привязана. Репозиторий выбирается из существующих либо создаётся: приватный и пустой, без README и заготовок. Создание репозитория необратимо, и окно говорит об этом до нажатия, а не после.
-**Не проект** — заметка, не относящаяся ни к какому репозиторию: живёт на простой доске и в Gitea не попадает.
-Правило без исключений: **есть issue — проектная доска, нет — простая.** Помнить, где вы её завели, не нужно.
-Порядок при создании неслучаен: сперва репозиторий, потом issue, потом карточка. Обрыв на середине не оставляет карточку привязанной к репозиторию без issue — лучше не завести её вовсе и сказать об этом. Созданный репозиторий при этом не удаляется: убирать чужое добро из-за своей неудачи хуже, чем оставить лишний пустой репозиторий.
-**Инструмента заведения issue у агента нет и не будет.** У соседнего плагина `dsh-gitea` уже есть `gitea_issue_create`, и второй способ делать то же самое разошёлся бы с первым. Агент зовёт свой инструмент, а карточка приезжает подхватом.
-### Задачи приезжают сами
+---
-Доска сама забирает открытые задачи **из всех репозиториев организации** и заводит карточки в бэклоге. Настраивать для этого ничего не нужно.
+## ✨ Full Feature Breakdown
-Опрашиваются только репозитории, где открытые задачи есть: их число приходит в общем списке, и отсев бесплатен — полсотни запросов впустую каждые две минуты это расточительство, а не осторожность. Заброшенные репозитории пропускаются.
+### 1. Interactive Visual Kanban Board in Web UI
-Организация определяется сама, пока у токена она одна; иначе её называют настройкой. Настройка «Сузить подхват до репозиториев» позволяет смотреть только на часть — пустая означает «все».
+* **Workflow Columns**:
+  * **Project Board Mode**: `Backlog` ➔ `In Progress` ➔ `Review` ➔ `Deploy` ➔ `Cleanup` ➔ `Done`.
+  * **Simple Board Mode**: `Backlog` ➔ `In Progress` ➔ `Review` ➔ `Done`.
+* **Drag-and-Drop Lifecycle Transitions**: Moving a card immediately executes the underlying stage trigger.
+* **Top Navigation Chip**: Live summary in the chat header showing active in-progress tasks with 1-click jump to board or active session.
+* **Rich Task Cards**: Shows task title, issue index (`#42`), assigned LLM model, target worktree, branch name, PR review status, and uncommitted diff markers.
-Не берутся: закрытые issue (это уже не работа), pull request-ы (это ход работы, а не сама работа), issue с уже заведённой карточкой и те, чью карточку вы **удалили** — удаление значит «видеть её здесь не хочу», и возвращать её каждый проход было бы спором с человеком каждые две минуты.
+---
-Вебхук зовёт подхват для того репозитория, о котором пришло событие: новый issue становится карточкой за секунды, а не ждёт таймера. Только по репозиторию события — полный обход при каждом чихе в любом из отслеживаемых означал бы обращение ко всем.
+### 2. Task-to-Agent Session Dispatcher
-Недоступный репозиторий не роняет остальные: он пропускается до следующего прохода, а причина попадает в состояние сверки в шапке.
+Unlike passive task boards, `dsh-kanban` actively drives the agents:
-### Архив
+| Column Moved To | Action Taken by Dispatcher | Instruction Sent to Agent Session |
+|:---|:---|:---|
+| **`Backlog`** | 🛑 **Stops Active Turn** | `agent.cancel({ kind: 'user' })` — stops agent execution immediately |
+| **`In Progress`** | ⚡ **Dispatches Turn** | *"Start or continue implementing this task according to standard workflow."* |
+| **`Review`** | 🔍 **Dispatches Turn** | *"Prepare work for review: mark PR ready and request human code inspection."* |
+| **`Deploy`** | 🚀 **Dispatches Turn** | *"Merge pull request and deploy. Moving card to Deploy is explicit user approval."* |
+| **`Cleanup`** | 🧹 **Dispatches Turn** | *"Clean up: delete remote/local branches, prune worktrees, log summary to issue."* |
+| **`Done`** | 🔒 **Human / VCS Only** | Closed automatically upon issue closure or user confirmation |
-Карточки, отстоявшие свой срок в «Выполнено», уезжают в архив — свой экран, а не колонка: колонка это стадия работы, а архив стадией не является. Срок в настройках, по умолчанию неделя, ноль отключает.
+---
-Возраст считается с попадания карточки в «Выполнено», а не по последнему изменению: сверка трогает задачу и после завершения, и по «изменено» архив откладывался бы бесконечно.
+### 3. Continuous 2-Way Gitea / Forgejo Sync
-**Архивируется только `done`.** Задача, застрявшая в ревью на месяц, — это сигнал, а не мусор, и прятать её нельзя.
+* **Bi-directional Reconciliation**: Polling and Webhook receiver (`/dsh-kanban/webhook`) sync issue descriptions, comments, PR status, labels, and closed states.
+* **Conflict Resolution**: Timestamp-based merge logic ensures manual edits in Gitea and board moves resolve cleanly without state clobbering.
+* **Automatic Issue Linking**: New tasks created on the board can automatically spawn corresponding issues and branch worktrees on Gitea.
-Ничего не удаляется: возвращённая карточка встаёт в ту же колонку, откуда ушла. Архив обязан быть обратимым, иначе им не станут пользоваться из страха.
+---
-### Перенос без мыши
+### 4. Agent Tools & Human Governance Safety
-На карточке — «перенести» со списком колонок её доски. Окно подтверждения и последствия те же, что при перетаскивании: путь другой, а результат один, и разойтись им нельзя. Карточка стала точкой табуляции — доска была мышиной целиком.
+| Tool Name | Scope | Purpose | Safety Rules |
+|:---|:---|:---|:---|
+| `board_move` | Board | Lets agent report progress and transition card to next stage | ⚠️ Cannot transition to `done` (closed by fact/human only) |
+| `board_plan` | Board | Saves structured step-by-step implementation plan to task card | - |
-Перетаскивание никуда не делось: речь о втором пути, а не о замене.
+---
-### Видно, как идёт сверка
+## 📦 Installation
-В шапке доски — состояние сверки с Gitea:
+Install via DeepSeek Harness CLI:
-| Что видно | Что значит |
-|---|---|
-| `сверено 2 мин назад` | всё в порядке; точное время в подсказке |
-| `сверяемся с Gitea…` | проход идёт прямо сейчас |
-| `сверки с Gitea ещё не было` | харнесс только поднялся |
-| **`сверка не проходит`** | выделено; в подсказке место, причина и время последней удачной сверки |
-Причина называется словами — «репозиторий не найден», «токен не подошёл», — а не прячется в журнал харнесса. Доска, переставшая обновляться, не имеет права молчать: отличить «ничего не изменилось» от «мы ослепли» иначе нечем.
-**Неудача не затирает время последнего успеха.** Иначе теряется ответ на главный вопрос: когда доска в последний раз видела правду.
-Состояние живёт в памяти процесса, а не в базе: это положение текущего запуска. После перезапуска честнее сказать «сверки ещё не было», чем показать вчерашний успех как сегодняшний.
-Повторных попыток и починки здесь нет — задача показать, а не вылечить.
-### Свои названия колонок
-Настройка «Свои названия колонок» — пары `идентификатор=Название` через запятую, например `backlog=Идеи, review=Проверка`. Пусто — обычные названия.
-Одно поле на все колонки, а не шесть отдельных: переименовывают их раз в жизни, а шесть полей засорили бы карточку настроек навсегда. Своё название приходит с сервера — там конфиг; перевод остаётся в браузере — там языки.
-### Как разложена колонка
-Внутри колонки задачи сгруппированы по проектам: заголовок со счётчиком, щелчок сворачивает группу. Крупные проекты идут первыми — с двадцатью задачами проект не должен теряться под однозадачными. Заголовки появляются, только когда проектов в колонке больше одного.
-Внутри группы наверх поднимается идущая работа: **сперва ждущие человека, затем идущие, затем остановившиеся**, дальше всё прочее в прежнем порядке. Ждущие впереди идущих намеренно: идущая работа идёт сама, а ждущая стоит из-за вас.
-Ручной порядок при этом не теряется — подъём работает поверх него, внутри каждой ступени порядок прежний.
-Порядок задаёт сервер, а браузер рисует заголовок при смене проекта: повторять правила во второй раз значило бы завести вторую их редакцию.
-### Языки
-Плагин несёт два словаря — английский и китайский: это встроенные локали ядра. Русский приезжает языковым пакетом `@goodandready/dsh-russian-lang`, который регистрирует `ru` для пространства `dsh-kanban` извне. Свой `ru` внутри плагина мешал бы пакету: повторная регистрация локали падает, и пакет такие пространства пропускает.
-Без службы локализации (например, до её появления в сборке) доска говорит по-английски — это запасной перевод, а не выбор.
-### Отбор видно
-Когда что-нибудь отобрано или введён поиск, рядом с отборами появляется «показано 12 из 81». На нетронутой доске этой строки нет — она была бы шумом. Без неё при восьмидесяти карточках легко решить, что отбор сломан, когда он просто строгий.
-### Что на карточке
-Шапка карточки отвечает на два вопроса раньше заголовка — чей это проект и что за работа:
-```
-memory-brain#1369   [type/feature]
-BudgetTracker concurrent reservations: детерминированный max-cost…
-3 из 7 · пишу тесты
-перенести · в работе · здесь 2 дн
+```bash
+dsh plugin --profile web add @goodandready/dsh-kanban
 ```
-Имя проекта и номер задачи разделены: имя плашкой, номер отдельно и приглушённее. Это две разные вещи — принадлежность и адрес, — и слипшимися они читаются как один непонятный идентификатор. **Номер ведёт на issue**: чаще всего ссылка нужна именно с карточки, а раньше пряталась в окне задачи. Щелчок по номеру карточку не открывает.
-Метки покрашены **цветами из Gitea** — теми же, что вы видите в самом issue. Цвет текста поверх выбирается по яркости фона, как это делает Gitea: иначе бледная метка на светлом становится нечитаемой.
-На карточке видна **дата заведения задачи**, а не время в колонке: «здесь 34 минуты» у задачи, приехавшей подхватом полчаса назад, не значит ничего — это возраст карточки на доске, а спрашивают про возраст задачи. Год показывается, только если он не нынешний.
-У задачи с сессией рядом с отметкой «в работе» стоит **переход в чат**: «идёт» без пути к тому, что идёт, — сведение, которым нельзя воспользоваться.
-Счётчик колонки — залитая плашка цвета своей колонки, а при превышении предела красная. Серым на сером он не читался.
+Restart DSH Web UI and perform a hard-refresh (`Ctrl+F5` or `Cmd+Shift+R`).
-Слева на карточке — полоса цвета `priority`. Критичное видно с другого конца экрана, не читая. Задача без срочности остаётся без полосы: пустая полоса читалась бы как «низкий приоритет», а это неправда.
+---
-«Перенести» показывается при наведении и при фокусе с клавиатуры — прятать ради компактности то, что делалось ради доступности, нельзя. Полный заголовок — в подсказке: на карточке он обрезан двумя строками.
+## ⚙️ Configuration
-Метка без цвета остаётся нейтральной. Цвета приезжают вместе с именами при импорте, подхвате и каждой сверке.
+Navigate to **Settings -> Plugins -> Kanban**:
-### Отборы
-В шапке доски — по одному списку на репозиторий и на каждое пространство меток:
-```
-[ репозиторий ▾ ] [ type ▾ ] [ priority ▾ ] [ status ▾ ] [ scope ▾ ] ...   [ поиск ]
+```yaml
+# config.yaml
+dsh-kanban:
+  boardKind: "project"
+  giteaUrl: "https://gitea.yourcompany.com"
+  giteaTokenEnv: "GITEA_TOKEN"
+  giteaOwner: "my-team"
+  giteaRepo: "main-app"
+  syncIntervalMs: 30000
+  webhookSecret: ""
 ```
-| Уровень | Правило |
-|---|---|
-| между пространствами | **и** — «срочные баги» это `priority/high` и `type/bug` |
-| внутри пространства | **или** — срочность у задачи одна, и «и» всегда давало бы пусто |
-Пространства собираются из меток, которые реально лежат на карточках: всё до первой `/` — пространство, всё после — значение. Список не зашит, поэтому заведённое в Gitea новое пространство появится само, без правки кода и без релиза. Порядок задан для известных, незнакомые дописываются в конец по алфавиту.
-Метки без пространства (`epic`, `hotfix`) своего отбора не получают — список из двух значений ради двух меток был бы мебелью. На карточках они видны и находятся поиском.
+### Settings Reference Table
-**Счётчик колонки считает отобранное, а поиск — нет.** Разница осмысленная: поиск временный, и предел «3 из 3» при одной найденной карточке врал бы; отбор постоянный, и на отборе по одному проекту «в работе 3 из 3» должно значить «по этому проекту».
+| Key | Type | Default | Description |
+|:---|:---|:---|:---|
+| `boardKind` | `string` | `"project"` | Board workflow mode: `"project"` (6 columns) or `"simple"` (4 columns) |
+| `giteaUrl` | `string` | `""` | Base URL of Gitea/Forgejo instance for task synchronization |
+| `giteaTokenEnv` | `string` | `"GITEA_TOKEN"` | DSH Credential name containing the Gitea API access token |
+| `giteaOwner` | `string` | `""` | Default organization or username for synced repositories |
+| `giteaRepo` | `string` | `""` | Default repository name for issue/task sync |
+| `syncIntervalMs` | `number` | `30000` | Background synchronization polling interval in milliseconds |
+| `webhookSecret` | `string` | `""` | Optional secret for validating incoming Gitea webhook signatures |
-Отборы держатся, пока открыт харнесс, и сбрасываются при смене доски: на другой доске те же значения могут не встречаться вовсе.
+---
-### Возврат в чат
+## 🧪 Testing & Verification
-В шапке доски слева — кнопка «В чат». Доска открывается на месте разговора, и до неё закрыть её можно было тремя неочевидными способами: клавишей Escape, повторным щелчком по строке в боковом списке и переходом в чужую сессию. Кнопка не заводит четвёртого механизма, а зовёт тот же самый: разойтись им негде.
-### Окно задачи
-```
-[memory-brain#1368] [type/feature]              [Закрыть]
-Same-turn memory write-back contract
-заведена 2 дня назад · изменена 5 мин назад · issue ↗
-<описание, размеченное>
-<план агента, если есть>
-<журнал, если есть>
-<запуск: провайдер, модель, сообщение>
-```
-**Описание разбирается разметкой**: заголовки, списки, выделение, `код`, блоки кода, цитаты и ссылки. Всё непонятое остаётся текстом как есть — полноценный markdown доска не тянет и не притворяется.
-Разбор идёт на сервере и приезжает **деревом**, а браузер собирает его элементами. Тело задачи пишет кто угодно, и вставлять его строкой HTML значило бы дать issue выполнить что угодно в вашем интерфейсе; при сборке элементами подстановка невозможна по построению, а не по бдительности. Ссылки открываются только `http` и `https` — `javascript:` в теле остаётся видимым текстом, а не превращается в ссылку.
-Пустые разделы не рисуются вовсе.
-### Карточка открывается окном
-Панель справа в 420 пикселей вмещала описание и журнал, но не план с отметками. Теперь карточка открывается окном поверх доски: описание, метки, ссылка на issue, план агента, журнал переходов, время, пусковая полоса. Закрывается крестиком, щелчком по затемнению и клавишей Escape.
-Окно живёт внутри экрана доски, а не поверх всего интерфейса: доска сама лежит в колонке разговора, и выход за её пределы наложился бы на чужие части оболочки. Снизу оставлен запас — поверх интерфейса висят плавающие виджеты соседних плагинов.
-### Время на доске
-| Где | Что видно |
-|---|---|
-| карточка | сколько стоит в этой колонке — `здесь 3 дн` |
-| карточка с сессией | когда её последний раз трогали; после порога молчания отметка становится тревожной |
-| окно задачи | когда заведена и когда менялась в последний раз |
-Формат относительный, потому что «третий день» читается мгновенно, а точная дата требует сравнения с сегодняшним числом; сама дата — в подсказке при наведении. Время в колонке считается по отметке, которую ставит перенос: перестановка внутри колонки её не сбрасывает, задача в ревью третий день там и остаётся.
-Порог молчания настраивается (`staleAfterMin`, по умолчанию час) и считается на хосте: отдавать браузеру ещё и порог значило бы отдавать ему решение. Отдельного опроса живости сессий нет — это был бы второй источник правды и лишняя нагрузка.
-**Открыть чат.** У задачи с сессией в окне есть кнопка возврата в её чат. Без неё задача, идущая вторые сутки, ищется в общем списке по имени вида `kanban-9e84cae6-…`.
-### Сворачивание колонок
-Шесть колонок по 220 пикселей не помещаются на ноутбуке. Поэтому пустая колонка сама сжимается до вертикальной полоски с названием, а щелчок по названию сворачивает и разворачивает любую, включая непустую. Решение человека сильнее автоматики в обе стороны: развёрнутая им пустая колонка не схлопнется у него на глазах.
-Свёрнутая показывает число карточек — колонка с работой, выглядящая пустой, хуже любой тесноты. Целью переноса она остаётся: карточку можно бросить в неё, не разворачивая.
-Колонки не прячутся совсем. `cleanup` пуст ровно до того момента, когда в нём появляется забытая ветка; спрятав его, мы спрятали бы тот самый сигнал, ради которого его завели.
-### Ручной перенос — это команда агенту
-Карточку двигают не ради учёта. Человек перетащил — значит просит запустить тот этап, куда перетащил, и команда уходит в чат задачи отдельным сообщением. При отпускании карточки доска показывает окно с описанием последствий; отмена оставляет карточку на месте.
-| Куда перенесли | Что происходит |
-|---|---|
-| Backlog | работа останавливается: идущий ход агента прерывается |
-| В работе | агент начинает или продолжает реализацию |
-| Ревью | агент снимает с PR пометку черновика и запрашивает проверку |
-| Deploy | агент вливает PR и выкатывает |
-| Cleanup | агент удаляет ветку, worktree и локальную ветку |
-| Done | завершение; сюда переносит только человек |
-**Перенос в Deploy и есть явное «ок» на выкатку.** Воркфлоу требует разрешения человека перед deploy, и это разрешение дано движением, а не словом в чате — второй раз агент не спрашивает.
-Инструменту агента переход в `done` закрыт и даже не предлагается в перечислении. Его путь к завершению — закрыть issue и удалить ветку; сверка с Gitea сама увидит закрытый issue без ветки. Карточка двигается фактом, а не заявлением.
-### План агента на карточке
-Агент публикует план своим инструментом `board_plan` — доска не разбирает его сообщения, потому что разбор это гадание, и не опирается на чужой `todo_list`, потому что это была бы зависимость от соседнего плагина.
-Список пунктов шлётся один раз, дальше агент двигает только номер текущего: гонять весь план ради одного числа незачем. Всё, что до текущего пункта, считается сделанным.
-На карточке видно `3 из 7 · пишу тесты`, в окне задачи — весь план: сделанное зачёркнуто, идущий пункт выделен. Плана из одного пункта и плана из двадцати это касается одинаково — на карточку едут только числа и текущий пункт.
-| Состояние | Откуда известно |
-|---|---|
-| в работе | у живого агента идёт ход |
-| ждёт пользователя | запрос разрешения или вопрос |
-| остановился | сессия у задачи записана, а живого агента за ней нет |
-«Остановился» — не догадка по тишине, а факт: так выглядит работа, прерванная перезапуском харнесса. Порога тишины в настройках нет и не будет: он был бы догадкой там, где есть точный признак.
-**Признак «нужен человек».** Колонки «Блокировано» в наборе нет, поэтому запрос разрешения или вопрос агента не двигают карточку, а поднимают на ней оранжевую точку. Признак снимается сам, когда ход возобновляется.
-**Инструмент агента** `board_move` выключен по умолчанию: скилл `gitea-project-workflow` пока запрещает этому CLI трогать канбан.
-Определение инструмента живёт в `lib/board-tool.js` отдельно от обвязки cordis и
-следует контракту `defineTool` из `@deepseek-ai/dsh-tools` **не ниже 0.1.0-rc.8**:
-`output` обязателен, а `parameters` — карта «имя -> схема значения», а не JSON
-Schema с корнем `type: 'object'`. Пропущенный `output` роняет не инструмент, а
-загрузку всего профиля, поэтому форма закреплена тестами `test/board-tool.test.mjs`.
-### Пачка задач одной сессией
-Флажок на карточке отмечает задачу, в шапке появляется «Выбрано N» и «Запустить выбранные». Вся пачка уезжает в **одну** сессию: провайдер и модель спрашиваются один раз, рабочая папка берётся у первой задачи и называется в окне подтверждения.
-Задачи приходят агенту **по очереди** — по сообщению на каждую, а не одним списком. Выбора «отдать разом» нет намеренно: правило выпуска релизов всё равно не даёт делать десять задач сразу, а десять карточек в «В работе», из которых делается одна, лгут о состоянии доски и лишают предел колонки смысла.
-В «В работе» переезжает только первая. Остальные остаются на месте с отметкой «в очереди · 2», «в очереди · 3» и так далее — номер считается по порядку постановки внутри сессии.
-Каждое сообщение называет свой номер и общее число: «Задача 2 из 5». Без этого агент, получив первую из пяти, объявит работу законченной и приберёт за собой — удалит ветку и закроет issue.
-**Инструменты при нескольких задачах в сессии.** `board_move` обязан назвать, какую карточку двигает; не назвал — отказ с перечислением, а не догадка: подвинутую не ту карточку заметят нескоро. При одной задаче называть нечего, поведение прежнее. `board_plan` пишет один план на сессию — это план работы над пачкой, — и кладёт его всем её задачам.
-### Очередь к идущей работе
-В меню карточки — «в очередь…»: выбор из **живых** сессий доски. Задача привязывается к выбранной сессии, сообщение уходит туда же, и агент возьмёт его, закончив текущий ход.
-Своей очереди плагин не заводит. Она уже есть у ядра: `followup` кладёт сообщение, агент забирает его на границе шага. Вторая очередь рядом с настоящей разошлась бы с ней при первой же заминке, и разбираться, какая права, пришлось бы человеку.
-Сессия без живого агента в список не попадает: предлагать её значило бы предлагать очередь, из которой никто ничего не возьмёт.
-«Снять с очереди» отвязывает задачу и пишет в её журнал, что **отозвать уже отданное сообщение нечем** — агент может дойти до задачи и увидеть карточку, которая его не ждёт.
-### Чем запускать: профиль агента и уровень доступа
-В окне задачи рядом с провайдером и моделью — **профиль агента** и **уровень доступа**. Оба списка приходят от харнесса: профили из `agentPresets`, уровни из `permissionPresets` (обычно `read-only`, `workspace-write`, `danger-full-access`). Свой словарь уровней доска не заводит и пояснения к ним берёт у ядра: собственные слова разошлись бы с тем, что уровень значит на самом деле.
-Профиль едет в создание сессии (`meta.agentPreset`) — это факт создания, у идущей сессии его не сменить. Поэтому при «Продолжить» поле профиля не показывается: показывать поле, которое ничего не меняет, значит врать.
-**Выбрали уровень доступа, а поставить его нечем — задача не запускается.** Сессия иначе пошла бы с правами по умолчанию, то есть, возможно, бо́льшими, чем просили; поднятая сессия при этом убирается за собой. Молчаливое расширение прав хуже отказа.
-Обе службы у ядра необязательны: если развёртывание их не собирает, списки приходят пустыми и поля не рисуются вовсе. Сломанный профиль в список не попадает — сессия на нём не соберётся, а отказ прилетел бы уже после запуска.
-При групповом запуске поля те же и стоят в том же окне: пачка идёт одной сессией, значит профиль и доступ у неё один.
-### Что видно в шапке доски
-**«Ждут ответа: 2»** — задачи, где агент задал вопрос или просит разрешения. Щелчок оставляет на доске только их, повторный снимает. Когда таких задач нет, счётчика нет вовсе: ноль в шапке — мебель, за которой перестают следить.
-**Порядок задач** — «как разложено» (ручной порядок плюс живое вперёд), «сначала старые», «сначала новые». Сортировка идёт в браузере поверх присланного порядка и ничего не записывает: это взгляд на доску, а не свойство задач. Группировку по проектам она не ломает — карточки переставляются внутри своего проекта, а идущая работа остаётся наверху группы.
-**Отбор по автору** стоит в одном ряду с метками. Задачи без автора — свои, заведённые на доске — собираются под значением `—`: «никто» тоже ответ на вопрос «кто завёл», и по нему тоже отбирают.
-### Остановить, не двигая карточку
-Раньше прервать агента можно было только перетащив карточку в «Бэклог», то есть отменив заодно и этап. В меню карточки есть «остановить»: прерывается ход, колонка остаётся. Пункт виден только у идущей задачи — останавливать нечего у того, кто не идёт.
-«Агент не работал» и «остановлено» — разные ответы, и доска не выдаёт второй за первый.
-### Пачку видно на карточках
-У карточки, чья сессия несёт больше одной задачи, стоит «пачка 2 из 5» — тот же порядок, в котором агент их берёт. Наведение подсвечивает остальные карточки той же сессии. Одиночная задача отметки не получает: «1 из 1» ничего не сообщает.
-### Групповые действия
-В полосе выбора кроме «Запустить выбранные» — «В архив», «Снять с очереди», «Перенести…». Отдельного группового маршрута нет: это те же действия, что для одной задачи, применённые по очереди.
-**Итог называется числом.** Часть задач может отказать — архивировать можно только из «Выполнено», снять с очереди можно только стоящую в ней, — и доска говорит «сделано у 7 из 10, остальные отказали». Молчаливо съеденный отказ означал бы карточку, про которую человек уверен, что она в архиве.
-### Доска помнит, чем запускали
-Провайдер, модель, профиль агента и уровень доступа подставляются те же, что в прошлый раз на этой доске. Память живёт в браузере у человека, а не в настройках плагина: это привычка одного, а не свойство доски.
-Подставляется только то, что ядро всё ещё предлагает: исчезнувшая модель или уровень доступа заменяются умолчанием. Тихо подставить несуществующий уровень значило бы запустить задачу не с теми правами.
-## Синхронизация
-**Gitea → канбан.** Опрос с настраиваемым промежутком плюс вебхук для мгновенной сверки. Вебхук — ускорение, а не замена: он может быть не настроен, недоступен снаружи или потерян, и опрос остаётся всегда.
-Маршрут вебхука `/dsh-kanban/webhook`, подпись проверяется общим секретом. **Без секрета вебхук не принимается вовсе** — иначе карточки двигал бы кто угодно снаружи.
-**Канбан → Gitea.** Доска сообщает Gitea ровно одно: **закрытие issue**, когда карточка доходит до «Выполнено». Меток колонок она не ставит — стадия и так видна по ветке и pull request, а метка лишь пересказывала бы то, что уже написано рядом. Заодно доска не трогает чужую разметку вовсе: `bug`, `feat`, `hotfix` принадлежат процессу, и стирать их доска права не имеет.
-Отправка идёт очередью: перенос карточки не ждёт сети, доска работает и при недоступном Gitea. Неудачная отправка повторяется, а исчерпав попытки — попадает в журнал задачи, а не исчезает.
-**Конфликты.** Если обе стороны изменились с последней сверки, побеждает более позднее изменение, а проигравшее **называется в журнале задачи**. Синхронизация, тихо отменяющая правку человека, хуже отсутствующей: расхождение остаётся, а узнать о нём неоткуда.
-До первой сверки «изменилось с прошлого раза» смысла не имеет — прошлого раза не было, — поэтому первая сверка принимает положение дел, а не спорит с ним.
-## Ограничения
-- Точного «работа идёт прямо сейчас» инстанс не знает. Порядок репозиториев и вывод колонок — приближение по открытым задачам, веткам и времени правки.
-- Клиент Gitea покрывает только нужное доске: issue, PR, ветки, метки, поиск репозиториев.
-- Неполное наблюдение считается отсутствующим: репозиторий, который не прочитался целиком, пропускается до следующей сверки. Иначе непрочитанные PR выглядели бы как их отсутствие и утаскивали карточку назад.
-## Разработка
+Run the comprehensive 520+ unit and integration test suite:
 ```bash
 npm test
 ```
-Тесты идут без харнесса, без сети и без установленных зависимостей: чистая логика вынесена в модули без импортов, а браузерная половина проверяется через `node:vm` с заглушкой загрузчика.
-Тестовая матрица — в [index.md](index.md). План выпуска — в [docs/plans](docs/plans).
+---
-## Лицензия
+## 📄 License
-MIT
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.ru.md ADDED Viewed

@@ -0,0 +1,173 @@
+# 📦 @goodandready/dsh-kanban
+<div align="center">
+<h3>Интерактивная Канбан-доска и диспетчер сессий агентов для DeepSeek Harness</h3>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-kanban"><img src="https://img.shields.io/npm/v/@goodandready/dsh-kanban.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-kanban.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+</div>
+---
+## ⚡ Обзор и решаемая проблема
+При ведении параллельной разработки силами нескольких автономных AI-агентов легко потерять контроль над статусом задач, проверкой пулл-реквестов (PR) и ветками в репозитории. Без наглядной доски разработчику приходится переключаться между десятками вкладок чата и вручную сверять тикеты в трекере.
+**`@goodandready/dsh-kanban`** встраивает полноценную **Канбан-доску** прямо в Web UI DeepSeek Harness. Каждая карточка на доске связана со своей **выделенной сессией агента**. Перемещение карточки между колонками автоматически отправляет агенту целевую инструкцию (разработка, передача на ревью, деплой или очистка воркдеревьев), поддерживая непрерывную **двустороннюю синхронизацию с Gitea / Forgejo**.
+---
+## 🏗️ Архитектура
+```mermaid
+graph LR
+    subgraph UI ["Интерфейс DSH Web UI"]
+        Board["Канбан-доска<br/>(Backlog, In Progress, Review, Deploy, Cleanup, Done)"]
+        Intake["Форма создания задачи<br/>(Выбор модели и Worktree)"]
+        HeaderChip["Чип в шапке чата<br/>(Счётчик активных задач)"]
+    end
+    subgraph Core ["Ядро dsh-kanban"]
+        Dispatcher["Диспетчер сессий<br/>(Команды через agent.followup)"]
+        Store["База SQLite задач<br/>(История переходов и связи)"]
+        SyncEngine["Двусторонняя сверка<br/>(Issues, PR, Ветки, Webhooks)"]
+    end
+    subgraph Agents ["Сессии агентов"]
+        Agent1["Агент: Задача #42<br/>(Кодинг в Worktree)"]
+        Agent2["Агент: Задача #53<br/>(Ревью PR)"]
+    end
+    subgraph VCS ["Сервер Gitea / Forgejo"]
+        GiteaIssues["Задачи и Вехи"]
+        GiteaPRs["Пулл-реквесты и Ветки"]
+        Webhook["Вебхук-приёмник (/dsh-kanban/webhook)"]
+    end
+    Board -->|Перенос карточки| Dispatcher
+    Dispatcher -->|Инструкция по этапу| Agent1
+    Dispatcher -->|Отмена при переносе в бэклог| Agent2
+    Board <-->|CRUD операции| Store
+    SyncEngine <-->|Опрос / Вебхуки| VCS
+    SyncEngine -->|Сверка статусов| Store
+    Store -->|Обновление интерфейса| Board
+```
+---
+## ✨ Исчерпывающий разбор возможностей
+### 1. Интерактивная Канбан-доска в Web UI
+* **Режимы колонок**:
+  * **Режим Project (6 колонок)**: `Backlog` ➔ `In Progress` ➔ `Review` ➔ `Deploy` ➔ `Cleanup` ➔ `Done`.
+  * **Режим Simple (4 колонки)**: `Backlog` ➔ `In Progress` ➔ `Review` ➔ `Done`.
+* **Drag-and-Drop управление этапами**: простое перетаскивание карточки мгновенно запускает соответствующий рабочий шаг.
+* **Чип в шапке чата**: живой индикатор текущих задач с переходом на доску или сразу в чат задачи в 1 клик.
+* **Информативные карточки**: отображение номера тикета (`#42`), выбранной LLM-модели, ветки Git, статуса PR и незакоммиченных правок.
+---
+### 2. Диспетчер команд и сессий агентов
+Доска не просто отображает задачи, а напрямую управляет исполнением агентов:
+| Колонка назначения | Действие диспетчера | Инструкция в чат задачи |
+|:---|:---|:---|
+| **`Backlog`** | 🛑 **Остановка хода** | `agent.cancel({ kind: 'user' })` — прерывает работу агента без потери контекста |
+| **`In Progress`** | ⚡ **Запуск разработки** | *«Начни или продолжи реализацию этой задачи по стандартному воркфлоу.»* |
+| **`Review`** | 🔍 **Запрос проверки** | *«Доведи работу до ревью: сними с PR пометку черновика и запроси проверку.»* |
+| **`Deploy`** | 🚀 **Деплой и слияние** | *«Влей pull request и выкати. Перенос в Deploy — это явное согласие на выкатку.»* |
+| **`Cleanup`** | 🧹 **Очистка окружения** | *«Прибери за задачей: удали ветку в Gitea, worktree и локальную ветку, запиши итог.»* |
+| **`Done`** | 🔒 **Только человек / факт** | Автоматически закрывается по факту закрытия issue в Gitea |
+---
+### 3. Непрерывная 2-сторонняя синхронизация с Gitea / Forgejo
+* **Двусторонняя сверка**: фоновый опрос и вебхуки (`/dsh-kanban/webhook`) синхронизируют заголовки, метки, PR и закрытие тикетов.
+* **Разрешение конфликтов**: алгоритм с учётом таймстемпов предотвращает перезапись изменений при одновременных правках на сервере и доске.
+* **Автосоздание задач**: новая карточка на доске может автоматически создавать задачу и ветку воркдерева в репозитории.
+---
+### 4. Инструменты агента и безопасность
+| Инструмент | Категория | Назначение | Контроль безопасности |
+|:---|:---|:---|:---|
+| `board_move` | Доска | Перемещение карточки на следующий этап | ⚠️ Перевод в `done` агенту запрещён (закрывается только по факту) |
+| `board_plan` | Доска | Сохранение структурированного плана реализации на карточку | - |
+---
+## 📦 Установка
+Установка через консольный клиент DeepSeek Harness:
+```bash
+dsh plugin --profile web add @goodandready/dsh-kanban
+```
+Перезапустите Web UI DSH и обновите вкладку в браузере с очисткой кэша (`Ctrl+F5` или `Cmd+Shift+R`).
+---
+## ⚙️ Конфигурация
+Откройте **Настройки -> Плагины -> 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 колонки) |
+| `giteaUrl` | `string` | `""` | URL инстанса Gitea/Forgejo для синхронизации задач |
+| `giteaTokenEnv` | `string` | `"GITEA_TOKEN"` | Имя DSH Credential с токеном доступа к Gitea API |
+| `giteaOwner` | `string` | `""` | Организация или логин владельца репозитория |
+| `giteaRepo` | `string` | `""` | Имя репозитория для связки задач |
+| `syncIntervalMs` | `number` | `30000` | Интервал фоновой периодической сверки (мс) |
+| `webhookSecret` | `string` | `""` | Секретный ключ для проверки входящих вебхуков от Gitea |
+---
+## 🧪 Тестирование и верификация
+Запуск полного набора из более чем 520 юнит- и интеграционных тестов:
+```bash
+npm test
+```
+---
+## 📄 Лицензия
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.zh.md ADDED Viewed

@@ -0,0 +1,173 @@
+# 📦 @goodandready/dsh-kanban
+<div align="center">
+<h3>面向 DeepSeek Harness 的可视化看板与任务智能体独立会话调度引擎</h3>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-kanban"><img src="https://img.shields.io/npm/v/@goodandready/dsh-kanban.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-kanban.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/作者全部项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="作者全部项目"></a>
+</p>
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+</div>
+---
+## ⚡ 核心定位与解决痛点
+当多个自主 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 泳道） |
+| `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)

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@goodandready/dsh-kanban",
-  "version": "0.1.15",
-  "description": "Kanban board for DeepSeek Harness: Gitea-backed tasks, workflow columns, and a dedicated agent session per task.",
+  "version": "0.1.17",
+  "description": "Visual Kanban board for DeepSeek Harness: Gitea-backed tasks, workflow columns, and a dedicated agent session per task.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -24,7 +24,9 @@
     "dsh-plugin",
     "kanban",
     "gitea",
-    "tasks"
+    "tasks",
+    "agents",
+    "deepseek-harness"
   ],
   "repository": {
     "type": "git",