dsh-agent-board 1.2.4 → 1.3.0

package/README.md

@@ -1,77 +1,206 @@
-# dsh-agent-board
+# Task Board Plugin for DeepSeek Harness
 
-[![npm version](https://img.shields.io/npm/v/dsh-agent-board.svg)](https://www.npmjs.com/package/dsh-agent-board)
+[![npm](https://img.shields.io/npm/v/dsh-agent-board)](https://www.npmjs.com/package/dsh-agent-board)
 [![npm downloads](https://img.shields.io/npm/dw/dsh-agent-board.svg)](https://www.npmjs.com/package/dsh-agent-board)
 [![node](https://img.shields.io/node/v/dsh-agent-board.svg)](https://www.npmjs.com/package/dsh-agent-board)
-[![license](https://img.shields.io/npm/l/dsh-agent-board.svg)](https://github.com/PPawnsir/task-board-plugin/blob/main/LICENSE)
+[![license](https://img.shields.io/npm/l/dsh-agent-board)](https://github.com/PPawnsir/task-board-plugin/blob/main/LICENSE)
 ![category](https://img.shields.io/badge/awesome--dsh--plugin-workflow-blue)
 
-DeepSeek Harness 智能看板 — 让主窗口把编码工作变成可追踪、可验收、可审计的任务，而不是一段做完就散的对话。
-
-## 背景与动机
-
-直接在会话里让 agent 干活，随着任务变多变复杂，会遇到四个典型问题：
-
-1. **长任务挤占对话** —— 一个改半小时的任务会让主窗口在这期间既不能干别的，也无法并行处理其他请求；多个任务只能排队串行。
-2. **干完没有验收** —— agent 说"完成了"就是完成了，改动是否真的可跑、是否满足要求，没有第二双眼睛独立复核过。
-3. **上下文反复调研** —— 每个新任务都从零读代码、查约定，主窗口调研过的结论和读过的文件无法带给执行者，时间都花在重复调研上。
-4. **过程不可见、结果不可审计** —— 任务散落在对话流里：谁做的、卡在哪、被驳回过几次、为什么这么做，事后无从回溯。
-
-看板针对这四点给出机制化的解法：
-
-| 问题 | 解法 |
-| --- | --- |
-| 挤占对话 | 每个任务派发给**一次性 Worker 子代理**独立执行，主窗口保持可交互；任务之间依赖调度、可并行 |
-| 没有验收 | **独立 Verifier 子代理**复核：Worker 必须实跑自测，Verifier 独立复跑验收脚本后给出结论；驳回自动重派，三次驳回升级人工 |
-| 重复调研 | 主窗口调研过的**结论/思路（contextNotes）和读过的文件（contextFiles）**随任务注入子代理的上下文注入区，子代理不必从零开始 |
-| 不可见不可审计 | 任务卡全程留痕：状态流转历史、每次验收结论、歧义上报与裁决、干预记录都在任务详情里；Worker/Verifier 会话可从详情页直达回看 |
-
-## 核心机制
-
-- **看板 UI**：会话标题栏「智能看板」按钮打开顶部抽屉（看板 / 团队 / 仪表盘三视图），拖拽流转，多选批量操作（带一步撤销），筛选（文本/优先级/标签）
-- **任务模型**：draft → pending → in-progress → verifying → resolved → archived，含 blocked/cancelled；优先级、标签、依赖（DFS 环检测）、流水线分档（full 执行+验证 / work 只做不验 / direct 主窗口直办）
-- **一次性派发**：每个任务 spawn 一个一次性子代理，做完即销毁——无常驻池、无状态残留；孤儿回收 + 看门狗卡死标记（不自动杀，裁决权在主窗口/用户）
-- **Team 模式**：开启后向主窗口注入提示词引导（实质性改动建议走看板派发，不硬拦截）；Worker 遇到歧义上报主窗口裁决（任何模式都通知）；任务完成/阻塞时主窗口收到批量聚合回执（等空闲再发，不打断对话）
-- **异构模型**：Worker/Verifier 均可下拉配置不同模型（避免同源盲点），默认空 = 继承父级模型；模型故障自动熔断回退父级
-- **手动/自动模式**：自动模式看板自动调度派发；手动模式主窗口自行 claim，详情页可「派发 / 派发验收」手动触发
+智能看板插件 — Agent 自主任务驱动开发：看板管理 + 一次性 Worker/Verifier 派发 + 依赖调度 + Team 模式。
 
 ## 安装
 
-> 宿主要求：Node ≥ 22；DSH ≥ `0.1.5-rc.1`（已通过 `peerDependencies` 声明，含预发布分支的版本范围见 package.json）
+### 前置条件
+
+- DeepSeek Harness（dsh）已安装并能正常启动：`dsh --profile web`
+- Node.js ≥ 22（与 dsh 运行时一致）
 
 ### 版本兼容性（先按宿主选插件版本）
 
 | 宿主 DSH 版本 | 应装插件版本 | 原因 |
 | --- | --- | --- |
-| **≥ 0.1.7**（含 rc） | **≥ 1.2.2（必须）** | 0.1.7 会话日志升级为 format v4：插件消息 `source.kind` 必须是生产者自有 kind。1.2.1 及更早会在**任务完成/阻塞回执**落盘时抛 `SessionFormatError: format v4 message requires a producer-owned source kind`，并连带使主窗口当前轮次失败（表现为「本轮运行失败」）；同时「跳转会话」因宿主移除 `sessions.open` 而失效（控制台 `sessionsSvc.open is not a function`），卡片活动心跳读不到 v4 日志（`session.v4.jsonl.zstd`） |
+| **≥ 0.2.0**（含 rc） | **≥ 1.3.0（必须）** | 0.2.0 起宿主在启动/安装时强制校验 peerDependencies，区间不含 0.2.0 的包**直接拒绝激活**（路由不挂载、面板不出现）。1.3.0 声明 `^0.1.7 \|\| 0.2.0-rc.2 \|\| ^0.2.0`——注意 semver 预发布不命中宽区间，`0.2.0-rc.2` 必须显式枚举。运行时 API（subagents/systemPrompt/agents/uiWorkspace.openSession/sessions/v4 日志格式）在 0.2.0 全部兼容，已过 0.2.0-rc.2 实测（E2E 23+8 断言全绿） |
+| **0.1.7 ~ 0.1.7-x**（含 rc） | **≥ 1.2.2（必须）** | 0.1.7 会话日志升级为 format v4：插件消息 `source.kind` 必须是生产者自有 kind。1.2.1 及更早会在**任务完成/阻塞回执**落盘时抛 `SessionFormatError: format v4 message requires a producer-owned source kind`，并连带使主窗口当前轮次失败（表现为「本轮运行失败」）；同时「跳转会话」因宿主移除 `sessions.open` 而失效（控制台 `sessionsSvc.open is not a function`），卡片活动心跳读不到 v4 日志（`session.v4.jsonl.zstd`） |
 | 0.1.5-rc.1 ~ 0.1.6 | ≤ 1.2.1 | 1.2.2 起按 0.1.7 协议编写（v4 source kind、`uiWorkspace.openSession` 跳转），旧宿主未做回归验证，建议停留 1.2.1 |
 
-指定版本安装：
-
 ```sh
-dsh plugin --profile web add dsh-agent-board@1.2.2   # 0.1.7+ 宿主
-dsh plugin --profile web add dsh-agent-board@1.2.1   # 0.1.5/0.1.6 宿主
+dsh plugin --profile web add dsh-agent-board@latest   # 0.1.7+/0.2.x 宿主（推荐）
+dsh plugin --profile web add dsh-agent-board@1.2.1    # 0.1.5/0.1.6 宿主
 ```
 
 > 从 ≤1.2.1 升到 ≥1.2.2 必须重启 DSH（host 端代码在启动时加载；1.2.2 之前的老版本还有一个路由残留 bug：禁用/启用热重载会撞 `duplicate exact route`，只能重启恢复，1.2.2 已修复）。
 
+### 从插件市场安装（推荐）
+
+已发布至 npm 官方 registry（[dsh-agent-board](https://www.npmjs.com/package/dsh-agent-board)）：
+
 ```sh
 dsh plugin --profile web add dsh-agent-board
+# 重启 dsh 生效
+dsh --profile web
+```
+
+### 从源码安装（开发/调试）
+
+```sh
+git clone https://github.com/PPawnsir/task-board-plugin.git
+dsh plugin --profile web add <本仓库绝对路径>/packages/dsh-agent-board
+# 重启 dsh
 ```
 
-重启 DSH 后生效。数据存于 `~/.dsh/tasks-<sessionId>.json`，卸载不删数据。
+### 验证安装
 
-## 升级
+1. 启动日志无 `plugin tree failed to load`
+2. 打开任意会话，标题栏出现 **智能看板** 按钮（Lucide 线性图标）
+3. RPC 路由可用：
 
 ```sh
+curl -X POST http://127.0.0.1:3080/dsh-agent-board \
+  -H "Content-Type: application/json" \
+  -d '{"method":"get-tasks","args":{"sessionId":"<sessionId>"}}'
+```
+
+返回 JSON 即正常；405 空 body 说明路由未挂载。
+
+### 升级
+
+```sh
+# 市场版
 dsh plugin --profile web add dsh-agent-board@latest
-# 重启 DSH
+# 源码版
+git pull
+# 两者都需重启 dsh
 ```
 
-## 源码与文档
+### 卸载
+
+```sh
+dsh plugin --profile web remove dsh-agent-board
+# 重启 dsh
+```
+
+> 看板数据存在 `~/.dsh/tasks-<sessionId>.json`，卸载不删数据。
+
+## 功能总览
+
+### 看板 UI
+
+- 会话标题栏「智能看板」按钮 → 顶部抽屉面板（看板 / 团队 / 仪表盘三视图）
+- 六列状态流：草稿 → 待办 → 进行中 → 验证中 → 已完成 → 阻塞
+- 拖拽流转、多选批量操作（带一步撤销）、文本/优先级/标签筛选
+- 归档区：时间倒序 + 排序选择器 + 纵向滚动
+- Esc 逐级关闭（详情 → 看板 → 面板）
+- 全部结构性图标为 Lucide 线性 SVG（`currentColor` 跟随主题，浅深色自适应）
+
+### 任务模型
+
+```
+draft → pending → in-progress → verifying → resolved → archived
+                     ↓              ↑
+                  blocked ←────── reject
+```
+
+- **草稿态（draft）**：创建时可先进草稿，补全描述/依赖后再发布，杜绝"半成品被派发"
+- **依赖调度**：`dependsOn` 声明依赖（DFS 环检测），依赖全部完成后才会被派发，串行链路自动编排
+- **管线分档**：`full`（执行+验证）/ `work`（只做不验）/ `direct`（不进池，主窗口直接处理），创建时按规则自动分类、可手动覆盖
+- **硬性验收**：`acceptance` 字段写验收脚本命令，Worker 必须实际运行、Verifier 必须独立复跑
+- **子任务**：父子层级 + 上下文继承 + 父任务自动流转 + 级联归档
+
+### 一次性派发（v74 去池化）
+
+- 每个任务 spawn 一个**一次性子代理**（Worker/Verifier），上下文全量注入 prompt，做完即销毁——无常驻池、无池化状态残留
+- **Worker/Verifier 均可配置异构模型**（⚙️ 弹出层下拉选择，空 = 继承父级），避免同源盲点；模型故障自动熔断回退父级模型
+- 孤儿回收：子代理 run 结束/丢失超 2 分钟 → 任务自动回待办重派
+- 看门狗：运行超时且事件流停滞 → 标记"疑似卡死"（不自动杀，裁决权交主窗口/用户）
+- 歧义上报：Worker 遇到歧义不猜测，上报等主窗口裁决（任何模式下都通知）；裁决后新 Worker 携带裁决答案接手
+- 手动派发：详情页「派发 / 派发验收」按钮可随时手动触发单任务派发（auto 模式补派、manual 模式主通道）
+- 会话隔离：看板按会话分桶，多会话互不干扰
+
+### 手动 / 自动派发模式
+
+| | 🤖 自动 | 👤 手动 |
+|---|---|---|
+| Worker 派发 | poolCycle 自动调度（并发上限可配） | 主窗口自行 claim 处理，或详情页手动「派发」 |
+| Verifier 派发 | 自动 | **自动**（主窗口手动做完的 full 档任务也会自动验收） |
+| 孤儿回收 | 开启 | 开启 |
+
+Team 模式开启时强制自动派发（防止"引导派发 + 手动模式"死锁组合）。
+
+### Team 模式
+
+开启后（Team 开关）：
+- 主窗口 system prompt 注入派发引导（提示词层面建议实质性改动走看板，不硬拦截）
+- 引导含**上下文书写提示**：子代理是全新会话、无会话记忆，description 写不够会自行调研跑偏
+- Worker 歧义自动上报主窗口聊天流，等待裁决
+- 任务完成/阻塞时主窗口收到**批量聚合回执**（45s 窗口或满 5 条聚合，等主窗口空闲再发，不打断对话）
+
+## 13 个 Agent 工具
+
+| 类别 | 工具 |
+|---|---|
+| 任务管理 | `task_create` / `task_list` / `task_context` / `task_update` / `task_claim` / `task_resolve` / `task_verify` / `task_archive` |
+| 池治理 | `task_terminate` / `task_intervene` / `task_arbitrate` |
+| 子代理上报 | `board_report` / `board_verdict` |
+
+> 管理工具仅主窗口可用（子代理调用会被拒绝）；`board_report`/`board_verdict` 是子代理的专用上报通道。
+
+## 仓库结构
+
+```
+└── packages/dsh-agent-board/     # 插件全部源码（直接维护，无构建步骤）
+│   ├── index.mjs                 #   host 端：IO 编排（工具/RPC/一次性派发引擎接线）
+│   ├── lib/core.mjs              #   纯逻辑核心：状态机/依赖/分类/prompt/解析（无 IO，可单测）
+│   ├── lib/client.js             #   client 端（ModuleLoader 包装，图标统一走 ICONS + ic()）
+│   ├── test/core.test.mjs        #   单元测试（node --test，30 例）
+│   ├── package.json              #   dsh.bundle.patch + dsh.client 元数据
+│   └── cordis.patch.yml          #   bundle 挂载行
+└── docs/
+    ├── PRD.md                    # 产品需求文档
+    ├── PACKAGING.md              # 打包/安装踩坑记录（link 依赖、单例隔离等）
+    ├── icon-style-guide.md       # 图标风格指南（Lucide 线性 SVG + emoji 分界）
+    └── REGRESSION-v59.md         # 端到端回归测试记录
+```
+
+> v68 起拆除了"动态源码 → 静态包"的转换层（build-pkg.cjs）：插件已稳定，
+> 双形态维护的复杂度大于收益，包内文件即唯一源码，改完重启 dsh 即生效。
+>
+> v74 起去池化（一次性派发）+ 纯逻辑抽到 `lib/core.mjs`，跑
+> `node --test packages/dsh-agent-board/test/` 即可验证状态机/依赖/派发决策，
+> 不用重启 dsh 人肉回归。
+
+## 文档
+
+- [docs/PRD.md](docs/PRD.md) — 完整产品需求文档
+- [docs/PACKAGING.md](docs/PACKAGING.md) — 正式安装（Bundle 打包）注意事项
+- [docs/icon-style-guide.md](docs/icon-style-guide.md) — 图标规范
+- [docs/REGRESSION-v59.md](docs/REGRESSION-v59.md) — 回归测试说明
+
+## 发布新版本（维护者）
+
+tag 驱动，GitHub Actions 自动发布到 npm（`.github/workflows/publish.yml`）。两种打 tag 方式都支持：
+
+**方式 1：命令行**
+
+```sh
+cd packages/dsh-agent-board
+npm version patch          # 或 minor / major——改 package.json
+git add -A && git commit -m 'release: vX.Y.Z' && git tag vX.Y.Z
+git push --follow-tags     # tag 推送触发流水线
+```
+
+**方式 2：GitHub 网页（Releases 页）**
+
+1. 先把 `packages/dsh-agent-board/package.json` 的 `version` 改成目标版本并合入 main（网页直接编辑即可）
+2. 仓库页 → **Releases** → **Draft a new release** → **Choose a tag** → 输入 `vX.Y.Z` 选 **Create new tag**（target 选 main）
+3. 点 **Publish release** —— 触发发布流水线
+
+- 流水线会拒绝与 tag 不一致的 `package.json` version（如 tag `v1.0.1` 但包里是 `1.0.0`），防止版本错位
+- **README 单一来源**：本文件（根 README）即唯一来源；发版前在 `packages/dsh-agent-board` 跑一次 `npm run sync-readme` 同步进包（npm 页面展示的是包内 README）
+- 需在仓库 **Settings → Secrets and variables → Actions** 配置 `NPM_TOKEN`
+  （npm granular access token：bypass 2FA + direct publish）
+- 日常 push / PR 有 `test.yml` 跑语法检查 + 30 例单测
+- 本地手动发布仍然可用：`npm publish --registry=https://registry.npmjs.org`（本机默认源是镜像时必须显式指定）
+
+## License
 
-- 仓库：<https://github.com/PPawnsir/task-board-plugin>
-- 本包即源码，直接维护（v68 起拆除了动态→静态转换层，v74 起去池化）
-- 单元测试：`npm test`（node --test，39 例纯逻辑用例）
-- E2E 回归：`npm run e2e -- --session <会话id>`（5 场景 21 断言，驱动真实实例）
-- 改源码后重启 DSH 生效（host）；`lib/client.js` 改动在 dsh ≥0.1.5-rc.2 下同样需重启（client bundle 启动时组合缓存）
+MIT

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "dsh-agent-board",
   "description": "DeepSeek Harness 智能看板：任务卡片 + 一次性 Worker/Verifier 派发 + 依赖调度 + 管线分档 + Team 模式（歧义上报主窗口裁决）",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "type": "module",
   "main": "./index.mjs",
   "scripts": {
     "test": "node --test test/core.test.mjs",
+    "sync-readme": "node -e \"require('fs').copyFileSync('../../README.md','README.md')\"",
     "prepublishOnly": "node --check index.mjs && node --check lib/client.js && node --check lib/core.mjs && npm test",
     "e2e": "node scripts/e2e.cjs"
   },
@@ -56,7 +57,7 @@
   },
   "peerDependencies": {
     "react": ">=18",
-    "@deepseek-ai/dsh": ">=0.1.5-rc.1 <0.2.0-0"
+    "@deepseek-ai/dsh": "^0.1.7 || 0.2.0-rc.2 || ^0.2.0"
   },
   "license": "MIT"
 }