dsh-taskboard 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 cloader
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,169 @@
+# dsh-taskboard
+
+DeepSeek Harness（DSH）的 **Agent 任务看板插件**：人把工作拆成卡片挂上看板，agent 会话通过 `taskboard_*` 工具认领、推进、评论、移交，人最终验收。双向协作，不是单向 todo 列表。
+
+```
+人在 GUI 建卡（选项目/紧急度/模型/执行方式）
+        │
+        ▼
+看板 ◄──SSE 实时刷新──┐
+        │              │ agent 会话内：
+   [手动执行/定时触发]  │ taskboard_get / comment_add / move
+        │              ▼
+        ▼           卡片 → in_progress →（实现+自验）→ in_review
+在任务项目里新建会话              agent 到此为止，永远到不了 done
+（指定模型，干净上下文）
+        │
+        ▼
+人在看板上确认 → done（唯一入口）
+```
+
+## 功能特性
+
+**Host 侧（agent 工具 + 台账 + 调度）**
+
+- **8 个 `taskboard_*` 工具**：任何会话中的 agent 都能查板、建卡、认领、移卡、评论、软删除
+- **任务挂项目**：项目直接映射 DSH workspace，零新实体；认领（todo→in_progress）校验调用会话归属，跨项目认领被拒
+- **紧急度三色**：urgent 红 / normal 紫 / relaxed 蓝，贯穿卡片、筛选、详情
+- **每任务可固定模型**：执行时创建会话即生效；未指定走部署默认模型
+- **两种执行方式**：认领制（项目内会话认领）或定时执行（host 侧 cron，关掉浏览器照样跑，错过窗口跳过不补跑）
+- **一键真实执行**：手动「执行」在任务项目内新建全新会话（干净上下文）提交任务 prompt，回合结算记入执行记录
+- **乐观并发**：所有写操作带 `ifVersion`，冲突返回 `version_conflict`
+- **完整归因**：每次变更记录 actor（user / agent+sessionId），评论区分作者
+- **host 权威台账**：`~/.dsh/dsh-taskboard.json` 原子持久化，全局 revision 单调递增，SSE 推送 + 断线全量对账
+
+**协议硬闸（代码级强制，不靠 prompt 自觉）**
+
+- agent 移卡到 `done` 一律 `forbidden` —— 完成只能由人在 GUI 确认
+- 认领要求会话 cwd 解析到任务所属 workspace（跨项目 = `workspace_mismatch`）
+- 任务被某 agent 会话持有期间，其他会话不可抢占（任何移动 `forbidden`）
+- agent 不可篡改任务的 model / execution 配置（归创建者/用户所有）
+
+**Client 侧（看板 UI）**
+
+- **五列看板**：待规划 / 待办 / 进行中 / 待验收 / 已完成；blocked 角标不占列；canceled / archived / 已删除收进「其它任务」页
+- **筛选栏**：项目下拉 + 紧急度三色 chip 多选
+- **任务卡片**：紧急度左缘色条、模型 / ⏰ 定时（下次运行时间）/ 受阻 / 最近执行结果角标、评论计数；backlog ↔ todo 拖拽
+- **新建 / 编辑任务弹窗**（`TaskFormModal`，新建与编辑共用）：
+  - 头部图标 + 副标题、双列网格表单、底部实时校验提示 + 操作按钮
+  - 紧急度色点卡片三选（各带副提示）、执行方式分段选择（认领制 / 定时）
+  - Cron 预设 chip 高亮选中，**实时校验**（非法表达式红框）+ **下次运行时间预览**（与 host 调度器同一套纯函数）
+  - 模型下拉读运行时已配置目录，「默认模型」为第一项
+  - Esc 关闭、自动聚焦标题、保存提示版本变化
+- **任务编辑**：详情面板「✎ 编辑」回填全部字段；GUI 作为 owner surface 可改标题 / 描述 / Prompt / 紧急度 / **项目改绑** / 执行方式 / 模型（含清除回默认）
+- **详情面板**：状态流转（done 二次确认）、受阻标记、用户/agent 气泡评论流、执行记录时间线（结果/耗时/会话短 id/错误摘要）、危险区（软删除→物理清除需确认）
+- **主题适配**：全部颜色走外壳 `--dsw-alias-*` 设计令牌，浅色 / 深色主题与皮肤自动跟随
+
+## 核心概念
+
+| 概念 | 说明 |
+|---|---|
+| 项目 | 直接映射 DSH workspace（无新实体）。任务创建时必须选一个 |
+| 紧急度 | `urgent` 红 / `normal` 紫 / `relaxed` 蓝，看板列内以色条区分，支持筛选 |
+| 状态机 | `backlog → todo → in_progress → in_review → done`，旁路 `canceled` / `archived`；`blocked` 是布尔标记不是状态 |
+| 执行方式 | `claim`（项目内会话认领）或 `scheduled`（host 侧 cron 定时触发） |
+| 模型 | 每任务可固定 `{provider, model}`；执行时应用到新建会话，未指定用部署默认模型 |
+| 乐观并发 | 所有写操作带 `ifVersion`，冲突返回 `version_conflict`（重读再试一次即可） |
+| 归因 | 每次变更记录 actor（user / agent+sessionId），评论挂 threadId |
+
+## Agent 工具（8 个）
+
+| 工具 | 作用 |
+|---|---|
+| `taskboard_list` | 按项目/状态/紧急度过滤列卡（开始工作前先看） |
+| `taskboard_get` | 读单卡全文（描述/prompt/评论/版本） |
+| `taskboard_create` | 建卡（需要 agent 身份） |
+| `taskboard_update` | 改标题/描述/prompt/紧急度/blocked（带 ifVersion） |
+| `taskboard_move` | 移动状态（带 ifVersion；**代码级拒绝 agent 移到 done**） |
+| `taskboard_comment_add` | 追加进度/报告评论 |
+| `taskboard_comments` | 列评论（先读再决定开工） |
+| `taskboard_delete` | 软删除（agent 只能标记，人在 GUI 清除） |
+
+Agent 工作流协议（随插件注入 system prompt）：开工先查板 → 先读后动 → 先认领再干活 → 冲突只重试一次 → 自验后移 in_review 留评论 → `done` 永远由人确认 → backlog 未授权不执行 → model/execution 只读。
+
+## 执行链路
+
+手动「执行」按钮或 cron 到期都走同一条路：
+
+1. 卡片置 `in_progress`，台账追加 execution 记录（`running`）；
+2. 在任务项目目录里新建全新会话（干净上下文），带任务固定模型或部署默认模型；
+3. 会话 attach 到 workspace（GUI 项目会话列表可见、可回链）；
+4. 任务 prompt 作为普通用户消息提交，消息头带任务 ID 与状态说明；
+5. 回合结算：成功 → `succeeded`；回合错误 → `failed`（错误入台账）。
+
+调度器每分钟 tick；到期任务先顺延 `nextRunAt` 再触发；错过超过 5 分钟的窗口跳过不补跑。
+
+## 安装
+
+**GitHub 源安装**（收录 [awesome-dsh-plugin 精选列表](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)后，dshmarket 市场里的一键安装走的也是这条路）：
+
+```bash
+dsh plugin --profile <name> add github:cloader/dsh-taskboard
+```
+
+> 构建产物 `lib/` 已随仓库提交：安装即用，无本地构建、无构建脚本授权（`allowBuilds`）。
+
+**npm 裸名安装**（需先将包发布到 npm；同样是预构建，免构建授权）：
+
+```bash
+dsh plugin --profile <name> add dsh-taskboard
+```
+
+本地 link 开发：profile 的 `package.json`：
+
+```json
+{
+  "dependencies": {
+    "dsh-taskboard": "link:D:/path/to/dsh-taskboard"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "@deepseek-ai/dsh-base",
+        "@deepseek-ai/dsh-web-app",
+        "dsh-taskboard"
+      ]
+    }
+  }
+}
+```
+
+然后 `dsh plugin --profile <name> add link:D:/path/to/dsh-taskboard`。
+
+> ⚠️ 官方 `@deepseek-ai/dsh-*` 包只写进 `bundles` 列表，**不要** `plugin add` 进 profile dependencies（会引发 SDK 双实例遮蔽，详见项目根 README 的踩坑记录）。
+
+host 侧改动需重启 `dsh web`；client 侧改动 rebuild 后刷新页面。
+
+## 开发
+
+```bash
+npm install
+npm run build        # tsdown 双构建：host ESM + client CJS（wrap-client.mjs 包装）
+npm test             # vitest 41 项（protocol/tools/execution/routes/client）
+npm run typecheck
+```
+
+## 架构
+
+```
+src/
+  shared/protocol.ts     # 状态机/紧急度/cron/记录类型（host+client 共享）
+  shared/api.ts          # HTTP/SSE 线上契约
+  host/
+    store.ts             # 台账：串行 mutate、原子持久化、订阅
+    tools.ts             # 8 个 taskboard_* 工具 + 代码级协议闸
+    sdk.ts               # SDK 兼容层（零运行时官方包 import）
+    protocol-text.ts     # agent 工作流协议 systemPrompt section
+    execution.ts         # 执行服务（新会话/模型/结算）
+    scheduler.ts         # host 侧 cron tick
+    routes.ts            # JSON + SSE HTTP 面
+  client/
+    index.ts             # 注入入口（connection）
+    api.ts controller.ts # fetch/SSE + useSyncExternalStore 状态源
+    board/*.tsx          # 看板视图（五列/筛选/卡片/详情/新建·编辑弹窗 TaskFormModal）
+    sidebar-entry.ts board-mount.tsx styles.ts
+tests/                   # vitest：protocol/tools/execution/routes/client + smoke-host
+  e2e/                  # dev-server 手工验证脚本（P0–P4，见 tests/e2e/README.md）
+```
+
+License: Apache-2.0

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-taskboard bundle patch: inserts the plugin row into the web
+# profile roster. Applied as a profile bundle layer (the `dsh.bundle.patch`
+# manifest field) over dsh-base; activate with
+# `dsh plugin --profile <name> add link:<path-to-this-package>`.
+#
+# The row is a bare plugin by package name: the node half (exports ".") runs
+# in the host process (tools, ledger, routes, scheduler, protocol section),
+# and the `dsh.client` declaration in package.json makes the browser half
+# (exports "./client", served at /plugins/<id>/client.js) load in the web GUI.
+- insert:
+    - id: dsh-taskboard
+      name: dsh-taskboard