@alpacachen/dsh-kanban 1.10.0 → 1.10.1

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.
package/README.md CHANGED
@@ -1,178 +1,88 @@
1
- <div align="center">
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(max-width: 600px)" srcset="docs/readme/cover-en-mobile.png">
4
+ <img src="docs/readme/cover-en.png" alt="dsh-kanban — Plan together. See work move. A shared board for you and your agent in DeepSeek Harness." width="100%">
5
+ </picture>
6
+ </p>
2
7
 
3
- # dsh-kanban
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/@alpacachen/dsh-kanban"><img src="https://img.shields.io/npm/v/@alpacachen/dsh-kanban?style=flat-square&color=3867e8&label=npm" alt="npm version"></a>
10
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3867e8?style=flat-square" alt="MIT license"></a>
11
+ <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
12
+ </p>
4
13
 
5
- ### Plan with AI. Move work forward visually.
14
+ <p align="center">
15
+ <a href="README.zh.md">简体中文</a> · <strong>English</strong><br>
16
+ <a href="#get-started">Get started</a> · <a href="docs/guide.md">User guide</a> · <a href="docs/guide.md#agent-tool-reference">Agent tools</a>
17
+ </p>
6
18
 
7
- A collaborative kanban board where you and your AI agent plan, organize, and ship work together—without leaving DeepSeek Harness.
19
+ <br>
8
20
 
9
- [![npm version](https://img.shields.io/npm/v/@alpacachen/dsh-kanban?color=5b8def&label=npm)](https://www.npmjs.com/package/@alpacachen/dsh-kanban)
10
- ![DeepSeek Harness Plugin](https://img.shields.io/badge/DeepSeek%20Harness-Plugin-7c5cff)
11
- [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
12
- ![License](https://img.shields.io/badge/license-MIT-22c55e)
21
+ Turn plans from your conversations into tasks you can move forward. You and your agent share one board for planning, context, and progress, all inside DeepSeek Harness.
13
22
 
14
- [Simplified Chinese](README.zh.md) · **English**
23
+ ![Kanban board with search and filters above tasks in Todo, In progress, Review, and Done](docs/readme/board-en.png)
15
24
 
16
- </div>
25
+ <p align="center"><sub>Current plugin UI · Isolated demo data · A separate board for every workspace</sub></p>
17
26
 
18
- <table>
19
- <tr>
20
- <td width="50%"><img src="./image.png" alt="Full dsh-kanban board in light mode with English tasks, labels and priorities" width="100%"></td>
21
- <td width="50%"><img src="./docs/screenshots/card-details-dark.png" alt="Full dsh-kanban board in dark mode with an open task drawer showing a Markdown description" width="100%"></td>
22
- </tr>
23
- </table>
27
+ ## From a conversation to the next step
24
28
 
25
- ## 1.10: search, images, and conversation attachments
29
+ ### Describe the goal. Let your agent create the tasks.
26
30
 
27
- - Search tasks at the top, then filter by **priority, label, or due date** beside the search field. Other actions live in **Settings** on the right.
28
- - Upload, paste, or drop images into a task and open them in DSH's native image preview.
29
- - Choose **Chat with agent** to place the task text and saved images in the composer for review before sending.
30
- - Agents can attach workspace files or current-session images and read the image contents.
31
+ Ask your agent to break down a requirement, write implementation steps and acceptance criteria, and assign labels and priorities. With 19 built-in tools, the plan goes straight onto the board.
31
32
 
32
- ## 💡 Things to ask your agent
33
+ > Break phone sign-in into testable tasks. Check existing cards first to avoid duplicates. Write implementation steps and acceptance criteria for each card, and mark launch blockers as P0.
33
34
 
34
- Start with work you actually need to move forward. Replace the project names and context below with your own, then send the prompt to your agent.
35
+ ### See the progress. Take over at any time.
35
36
 
36
- **Turn a requirement into tasks with clear acceptance criteria**
37
+ Drag cards between stages, then use search and filters to find the next task. Markdown descriptions, comments, and activity history keep the work's context in one place.
37
38
 
38
- > We need to ship phone-number sign-in next week. Check the existing cards, then create tasks for any missing API, verification code, abuse prevention, UI, and testing work. Record dependencies and use Markdown descriptions for implementation steps and acceptance criteria. Mark launch blockers as P0 and prioritize the remaining work.
39
-
40
- **Pick up work already in progress**
41
-
42
- > Continue “Redirected back to login after signing in.” Read the full description and comments, summarize what we know and the next step, and move it to In Progress. Record progress and test results in comments, then move it to Review for me to verify.
43
-
44
- **Track work blocked on someone else**
45
-
46
- > “Payment integration” is waiting for a test account from the provider. Create a Blocked list if needed and move the card there. Add a comment with the blocker, the contact we still need to confirm, and what to do once the account arrives.
47
-
48
- **Prepare a weekly meeting from the board**
49
-
50
- > Use the current card statuses, descriptions, and comments to prepare our meeting notes: completed work, work in progress, and blockers that need coordination. Reference the relevant cards and suggest the three most useful next actions. Flag missing information as questions to resolve.
51
-
52
- **Build a workflow for your profession**
53
-
54
- > I'm a lawyer handling contract reviews and case preparation. Set up suitable stages and labels, then create cards for the matters I provide below. Record deliverables, required documents, and agreed dates in each description. Put matters with missing documents in “Waiting for documents.”
55
-
56
- ## ✨ From conversation to action
57
-
58
- Stop copying AI-generated plans into a separate project tracker. Tell your agent what you want to build, and watch it turn the plan into cards, priorities, labels, and workflow updates on the **Board** tab.
59
-
60
- You can take over at any time—drag a card, refine a note, reorder a list—and the agent immediately works from the same board.
39
+ | What matters | How to find it |
40
+ | --- | --- |
41
+ | Important work | P0 / P1 / P2 priorities and custom labels |
42
+ | Upcoming deadlines | Due dates, due-today and overdue filters |
43
+ | Existing decisions | Search card IDs, titles, full descriptions, and comments |
61
44
 
62
- | 💬 Plan naturally | 🧭 Stay in control | ⚡ Start instantly |
63
- | --- | --- | --- |
64
- | Manage the board with 19 built-in `kanban_*` tools. | Edit, comment, drag, search, filter, and attach images from the UI. | Install the prebuilt plugin—no frontend setup required. |
65
- | **🗂️ Keep work separate** | **🌓 Feel at home** | **🤝 Share one source of truth** |
66
- | Every DSH workspace gets its own board. | Follows your DSH language, theme, and dark mode. | You and the agent always see the same tasks and status. |
45
+ ### Bring the context back into conversation.
67
46
 
68
- ## 🚀 Get started
47
+ Paste or drop screenshots into a task, then choose **Chat with agent** to bring its text and saved images into the current conversation or a new one. Everything starts as an editable draft for you to review and send.
69
48
 
70
- ### 1. Install
49
+ [Image and saving rules →](docs/guide.md#usage-details) · [More prompt examples →](docs/guide.md#prompt-examples)
71
50
 
72
- Verified with Web Host **0.2.0-rc.2** and desktop **0.2.1-rc.3**. Version 1.10 uses DSH's newer preview and conversation-attachment APIs; upgrade DSH first if you are on 0.1.5.
51
+ ## Get started
73
52
 
74
- **Desktop:** open **Plugins**, add `@alpacachen/dsh-kanban`, and enable it. The desktop app manages installation.
53
+ **Desktop** — Open **Plugins**, add `@alpacachen/dsh-kanban`, and enable it.
75
54
 
76
- **Web:**
55
+ **Web** — Run the command below, then restart `dsh web` to load the plugin.
77
56
 
78
57
  ```sh
79
58
  dsh plugin --profile web add @alpacachen/dsh-kanban
80
59
  ```
81
60
 
82
- Restart `dsh web` so the plugin bundle is loaded. You can confirm the installation with:
83
-
84
- ```sh
85
- dsh --profile web --dump-config
86
- ```
87
-
88
- Look for a `dsh-kanban` layer in the output.
89
-
90
- ### 2. Open your board
91
-
92
- Enter any workspace and choose the **Board** tab beside the conversation views. A fresh board starts with four familiar stages:
93
-
94
- `Todo` → `In Progress` → `Review` → `Done`
95
-
96
- ### 3. Ask your agent to plan
97
-
98
- Try this:
99
-
100
- > Break the authentication feature into implementation tasks, create one card per step, and mark the security review as P0.
101
-
102
- The cards appear directly on your board. Continue in conversation, or switch to the Board tab and shape the plan by hand.
61
+ Enter a workspace and open the **Board** tab beside the conversation views. Start with four default stages:
103
62
 
104
- ## 🧩 Everything you need to keep work moving
63
+ **Todo → In Progress → Review → Done**
105
64
 
106
- ### On the Board
65
+ Declared compatibility: DSH **0.2.0-rc.2 / 0.2.1-rc.3**, on Web and desktop. Version 1.10 uses newer image-preview and conversation-attachment APIs; upgrade DSH first if you use 0.1.5.
107
66
 
108
- | Action | How it works |
109
- | --- | --- |
110
- | Find tasks | Search card IDs, titles, descriptions, and comments; the three adjacent buttons filter by priority, label, and due date. |
111
- | Manage the board | **Settings** at the top right contains refresh, column editing, label editing, and **Feedback · GitHub**. |
112
- | Move work forward | Create, edit, delete, and drag cards; add color-coded labels and P0 / P1 / P2 priorities. |
113
- | Read task details | A resizable side drawer remembers its width and fills narrow screens; descriptions support Markdown editing and preview. |
114
- | Attach images | Choose files, paste from the clipboard, or drag images in; see counts on cards and preview, remove, or retry in task details. |
115
- | Track dates | Set due dates, find tasks due today or overdue, and record completion dates automatically when cards enter the completion column. |
116
- | Collaborate | Exchange comments, inspect the activity timeline, or continue a task in the current conversation or a new one. |
117
-
118
- Click **Save** to apply text and Markdown edits; **Done editing** only switches back to preview. Active filters appear below the toolbar. Remove a filter with its × button or choose **All** in its menu.
119
-
120
- ### Continue any card with your agent
121
-
122
- Open a card and choose **Chat with agent**. dsh-kanban carries its ID, title, label, due date, and notes into either the current conversation or a fresh one. Saved images are also added to the target composer as previewable, removable attachments. Text and images remain an editable draft until you choose to send it. An image-read failure keeps the task dialog open with an error for retry.
123
-
124
- ### Search tasks
125
-
126
- Search covers the current workspace's card ID, title, complete description, and comment text. It matches a literal substring, ignores case and surrounding whitespace, and combines with all active filters using AND. It preserves card order and resets when switching workspaces. The agent uses the same search through `kanban_get` with `{"query":"login"}`.
127
-
128
- ### Add and preview images
129
-
130
- Images support PNG, JPEG, and WebP, up to 10 MiB each and 10 images per card; the DSH Host can impose stricter format or size limits. In a new card, selected images stay in the browser until **Save** creates the card. If an upload fails, the created card and successful images remain saved, and the drawer keeps failed files for retry without creating another card. Canceling before creation uploads nothing. For an existing card, image uploads and removals save immediately; text edits still require **Save**. Unsupported Hosts or workspaces that cannot persist data show an upload-unavailable message.
131
-
132
- Click a thumbnail to open DSH's native full-size preview. Escape, the close button, or the backdrop returns to task details. Image contents are not included in text search; OCR is not supported.
133
-
134
- ### Data and backups
135
-
136
- Each card has an `images` array containing only `attachmentId`, `mediaType`, `bytes`, `width`, and `height` per image. Names and captions are not saved. Schema v6 adds `images: []` to existing cards and backs up the old board file before migration. The workspace's `.dsh-kanban.json` holds image references; image files live in DSH's native attachment store under its DSH home, shared independently of a particular workspace or conversation. Back up both the board file and the DSH attachment store to preserve images. Removing an image or card removes the association, not the shared image object.
137
-
138
- ### In conversation
67
+ <details>
68
+ <summary>Check the Web plugin configuration</summary>
139
69
 
140
- The plugin automatically gives the agent these tools in every workspace:
141
-
142
- | Area | Tools |
143
- | --- | --- |
144
- | **Board** | `kanban_get`, `kanban_set_completed_column` |
145
- | **Cards** | `kanban_get_card`, `kanban_add_comment`, `kanban_add_card`, `kanban_update_card`, `kanban_delete_card`, `kanban_move_card` |
146
- | **Images** | `kanban_add_image`, `kanban_read_image`, `kanban_remove_image` |
147
- | **Lists** | `kanban_add_column`, `kanban_rename_column`, `kanban_delete_column`, `kanban_move_column` |
148
- | **Labels** | `kanban_get_label`, `kanban_add_label`, `kanban_update_label`, `kanban_delete_label` |
149
-
150
- For images, create the card first and use the returned `cardId` as `id`. Call `kanban_add_image` with one of these argument objects:
151
-
152
- ```json
153
- {"id":"k1","source":{"kind":"workspace_file","path":"screenshots/login.png"}}
154
- ```
155
-
156
- ```json
157
- {"id":"k1","source":{"kind":"session_attachment","attachmentId":"sha256:<actual attachment hash>"}}
70
+ ```sh
71
+ dsh --profile web --dump-config
158
72
  ```
159
73
 
160
- The file path must be relative to the current workspace and stay inside it. A session attachment must actually belong to the executing agent's current session; use its real ID, not a fabricated hash. Do not pass base64 or a remote URL. Repeating the same image does not create another association. `kanban_get` returns image counts; `kanban_get_card` returns the five-field references. Use `kanban_read_image` with `{"id":"k1","attachmentId":"sha256:<actual attachment hash>"}` to inspect pixels, or `kanban_remove_image` with the same arguments to detach it. Both verify that the image belongs to that card in the current workspace.
161
-
162
- For `kanban_add_card` and `kanban_update_card`, the task description uses the existing `note` field: send raw Markdown with line breaks, not HTML. Headings, lists, tables and fenced code blocks are rendered in task details. Keep the source within 2,000 characters, including Markdown syntax and newlines; longer input is truncated with a warning. Before editing a description, read `kanban_get_card` for its complete Markdown source (`kanban_get` only returns a summary). Updating `note` replaces the whole description; omit it to preserve the current text, or pass an empty string to clear it. Comments remain plain text.
163
-
164
- For due dates, `kanban_add_card` and `kanban_update_card` accept `dueDate` as a real calendar date in `YYYY-MM-DD` format. Omit it to keep the current date (new cards default to none); use `null` or an empty string to clear it. Dates have no time or timezone: a task due today becomes overdue the next local calendar day. Resolve phrases such as “this Friday” against the user's local date and confirm the concrete date instead of sending relative text or a UTC timestamp. Both `kanban_get` and `kanban_get_card` return the date and the board's `completedColumnId`.
165
-
166
- Completion dates are recorded automatically when a card enters the configured completion list (including creation there). Reopening clears the date; completing again records a new timestamp. Edits, comments, same-list sorting, and column renames/reordering preserve it. Card details show the local completion time next to the due date; it is read-only. Both read tools return `completedAt` as a UTC ISO timestamp, or `null`. A completed card with `null` has an unknown completion time. Changing or clearing the completion list resets completion dates; existing cards in the newly selected list have unknown dates. Deleting a list applies the same completion rules to its automatic card moves. When upgrading from a schema older than v5, historical completion times remain unknown rather than being inferred from the activity log.
167
-
168
- Use `kanban_set_completed_column` with an existing `columnId` to designate the finished stage, or `null` to clear it. New boards use their default Done column; existing boards need an explicit choice. Completion follows the column ID through renames and reordering, and deleting that column clears the setting. Cards in the completion column keep their dates but are excluded from **Due today** and **Overdue** filters; moving them out resumes date checks. There are no automatic reminders or date-based reordering.
74
+ Look for a `dsh-kanban` layer. Its presence confirms the configuration, not that the running service has loaded it; restart the Web service after installation.
169
75
 
170
- > Set the payment integration task's due date to this Friday, then show me unfinished tasks that are due today or overdue so I can decide what to tackle first.
76
+ </details>
171
77
 
172
- ## Development
78
+ ## Explore further
173
79
 
174
- Use Node.js 26 and pnpm 11.8.0. See [validation instructions](docs/testing-images.md) for builds, regression tests, and isolated image integration checks.
80
+ - [User guide](docs/guide.md) — Editing, search, images, and collaboration.
81
+ - [Agent tool reference](docs/guide.md#agent-tool-reference) — All 19 tools, arguments, and completion rules.
82
+ - [Data and backups](docs/guide.md#data-and-backups) — Keep both the board file and the DSH attachment store to preserve images.
83
+ - [Development and validation](docs/testing-images.md) — Node.js 26, pnpm 11.8.0, builds, and tests.
84
+ - [Issues and ideas](https://github.com/alpacachen/dsh-kanban/issues) — Report a problem or share feedback.
175
85
 
176
- ## License
86
+ ---
177
87
 
178
- MIT
88
+ [MIT](LICENSE) · Built for DeepSeek Harness
package/README.zh.md CHANGED
@@ -1,178 +1,88 @@
1
- <div align="center">
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(max-width: 600px)" srcset="docs/readme/cover-zh-mobile.png">
4
+ <img src="docs/readme/cover-zh.png" alt="dsh-kanban — 一起规划,让进展可见。你与 Agent 共用的 DeepSeek Harness 看板。" width="100%">
5
+ </picture>
6
+ </p>
2
7
 
3
- # dsh-kanban
8
+ <p align="center">
9
+ <a href="https://www.npmjs.com/package/@alpacachen/dsh-kanban"><img src="https://img.shields.io/npm/v/@alpacachen/dsh-kanban?style=flat-square&color=3867e8&label=npm" alt="npm 版本"></a>
10
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3867e8?style=flat-square" alt="MIT 许可"></a>
11
+ <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
12
+ </p>
4
13
 
5
- ### 和 AI 一起规划,让每一步进展清晰可见。
14
+ <p align="center">
15
+ <strong>简体中文</strong> · <a href="README.md">English</a><br>
16
+ <a href="#开始使用">开始使用</a> · <a href="docs/guide.zh.md">使用指南</a> · <a href="docs/guide.zh.md#agent-工具参考">Agent 工具</a>
17
+ </p>
6
18
 
7
- 一块真正由你和 AI Agent 共同维护的项目看板——从想法、任务拆解到推进交付,全程无需离开 DeepSeek Harness。
19
+ <br>
8
20
 
9
- [![npm version](https://img.shields.io/npm/v/@alpacachen/dsh-kanban?color=5b8def&label=npm)](https://www.npmjs.com/package/@alpacachen/dsh-kanban)
10
- ![DeepSeek Harness Plugin](https://img.shields.io/badge/DeepSeek%20Harness-Plugin-7c5cff)
11
- [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
12
- ![License](https://img.shields.io/badge/license-MIT-22c55e)
21
+ 把对话里的计划变成可推进的任务。你和 Agent 在同一块看板上拆解工作、补充上下文、更新进度,始终留在 DeepSeek Harness 中。
13
22
 
14
- **简体中文** · [English](README.md)
23
+ ![Kanban 看板:顶部搜索与筛选,下方展示待办、进行中、待验收和已完成四列任务](docs/readme/board-zh.png)
15
24
 
16
- </div>
25
+ <p align="center"><sub>当前插件界面 · 隔离示例数据 · 每个工作区独立保存</sub></p>
17
26
 
18
- <table>
19
- <tr>
20
- <td width="50%"><img src="./image.png" alt="浅色模式下的完整 dsh-kanban 看板,展示英文任务、标签与优先级" width="100%"></td>
21
- <td width="50%"><img src="./docs/screenshots/card-details-dark.png" alt="深色模式下的完整 dsh-kanban 看板,打开的任务详情抽屉展示 Markdown 描述" width="100%"></td>
22
- </tr>
23
- </table>
27
+ ## 从一句话,到下一步行动
24
28
 
25
- ## 1.10:搜索、图片与对话附件
29
+ ### 说清目标,Agent 来建卡
26
30
 
27
- - 在顶部搜索任务,紧接搜索框按**优先级、标签、截止日期**筛选;其余操作集中在右侧**设置**菜单。
28
- - 在任务中上传、粘贴或拖入图片,使用 DSH 原生图片预览查看大图。
29
- - 点击「与 Agent 聊一聊」,把任务文字和已保存的图片一起带入聊天框,确认后再发送。
30
- - Agent 可从工作区文件或当前会话附件添加图片,也能读取图片内容。
31
+ 让 Agent 拆解需求,写下实现步骤与验收标准,安排标签和优先级。19 个内置工具,让规划直接落到看板上。
31
32
 
32
- ## 💡 你可以直接这样说
33
+ > 把手机号登录拆成可验收的任务,先检查已有卡片,避免重复。每张卡写清实现步骤和验收标准,把上线阻塞项标为 P0。
33
34
 
34
- 从你正在做的事开始。把下面例子里的项目名称和背景换成自己的,就可以直接发给 Agent。
35
+ ### 看清进展,随时接手
35
36
 
36
- **把需求拆成可验收的任务**
37
+ 拖动卡片调整阶段,用搜索和筛选找到下一件事。任务描述支持 Markdown,评论和活动记录留下推进过程。
37
38
 
38
- > 下周要上线手机号登录。先看看已有卡片,再为缺少的接口、验证码、防刷、前端交互和测试工作建卡。写清依赖关系,并在描述里用 Markdown 列出实现步骤和验收标准。影响上线的任务标为 P0,其余排好优先级。
39
-
40
- **接手一项正在做的工作**
41
-
42
- > 接着处理「登录后跳回登录页」。先读完整描述和评论,梳理已有结论与下一步,移到 In Progress。推进过程和测试结果记到评论,完成后移到 Review 等我验收。
43
-
44
- **跟进被外部依赖卡住的事项**
45
-
46
- > 「支付联调」还在等对方提供测试账号。建一个 Blocked 列表(已有就复用),把任务移过去,并在评论里记录阻塞原因、待确认的联系人,以及拿到账号后的下一步。
47
-
48
- **用现有看板准备周会**
49
-
50
- > 根据当前卡片的状态、描述和评论,整理周会提纲:已完成什么、哪些工作还在推进、有哪些阻塞需要协调。引用相关卡片,给出接下来最值得推进的三件事;信息不全的地方列成待确认项。
51
-
52
- **为自己的职业建立工作流**
53
-
54
- > 我是一名律师,要同时跟进合同审查和案件材料准备。帮我整理适合的阶段列表与标签,把我下面提供的事项逐一建卡,在描述里记录交付要求、材料清单和约定时间;缺少材料的放到「等待补充」。
55
-
56
- ## ✨ 从一句话,到一块能执行的看板
57
-
58
- 不必再把 AI 生成的计划手动搬进项目管理工具。告诉 Agent 你想完成什么,它就能在 **「看板」** 标签页中拆分任务、创建卡片、设置优先级和更新进度。
59
-
60
- 你也可以随时接手:拖动卡片、补充备注、调整列表。你和 Agent 始终面对同一块看板、同一份进度。
39
+ | 关注什么 | 怎么找到 |
40
+ | --- | --- |
41
+ | 重要的事 | P0 / P1 / P2 优先级与自定义标签 |
42
+ | 快到期的事 | 截止日期、今天到期与逾期筛选 |
43
+ | 已有的结论 | 搜索卡片 ID、标题、完整描述和评论 |
61
44
 
62
- | 💬 自然对话 | 🧭 随时掌控 | ⚡ 开箱即用 |
63
- | --- | --- | --- |
64
- | 通过 19 个 `kanban_*` 工具直接管理任务。 | 在界面中编辑、评论、拖拽、搜索、筛选和添加图片。 | 浏览器端已预构建,无需配置前端环境。 |
65
- | **🗂️ 项目隔离** | **🌓 原生体验** | **🤝 实时协作** |
66
- | 每个 DSH 工作区都有自己的独立看板。 | 自动跟随 DSH 的语言、主题与暗色模式。 | 你做的调整,Agent 立即可见;反之亦然。 |
45
+ ### 带上上下文,继续对话
67
46
 
68
- ## 🚀 三步开始使用
47
+ 把截图粘贴或拖进任务,点击「与 Agent 聊一聊」,将任务文字和已保存的图片一起带到当前或新会话。内容先进入可编辑草稿,由你确认发送。
69
48
 
70
- ### 1. 安装
49
+ [查看图片与保存规则 →](docs/guide.zh.md#使用规则) · [更多对话示例 →](docs/guide.zh.md#对话示例)
71
50
 
72
- 已验证:Web Host **0.2.0-rc.2**、桌面端 **0.2.1-rc.3**。1.10 使用新版 DSH 原生预览和对话附件接口;旧版 0.1.5 用户应先升级 DSH。
51
+ ## 开始使用
73
52
 
74
- **桌面端:**打开「插件」,添加 `@alpacachen/dsh-kanban` 并启用,由桌面端管理安装。
53
+ **桌面端** — 打开「插件」,添加并启用 `@alpacachen/dsh-kanban`。
75
54
 
76
- **Web:**
55
+ **Web** — 运行以下命令,安装后重启 `dsh web` 以加载插件。
77
56
 
78
57
  ```sh
79
58
  dsh plugin --profile web add @alpacachen/dsh-kanban
80
59
  ```
81
60
 
82
- 安装后重启 `dsh web`,让插件 bundle 完成加载。你可以用下面的命令确认安装结果:
83
-
84
- ```sh
85
- dsh --profile web --dump-config
86
- ```
87
-
88
- 如果输出中包含 `dsh-kanban` 配置层,就说明安装成功。
89
-
90
- ### 2. 打开看板
91
-
92
- 进入任意工作区,点击会话视图旁的 **「看板」** 标签页。新看板已经准备好四个常用阶段:
93
-
94
- `Todo` → `In Progress` → `Review` → `Done`
95
-
96
- ### 3. 让 Agent 开始规划
97
-
98
- 试试这样说:
99
-
100
- > 把登录功能拆成具体的实现任务,每一步创建一张卡片,并把安全审查标为 P0。
101
-
102
- 任务会直接出现在看板中。你可以继续通过对话推进,也可以切换到看板,用拖拽和编辑完善计划。
61
+ 进入工作区,打开会话视图旁的 **「看板」**,即可从四个默认阶段开始:
103
62
 
104
- ## 🧩 推进工作需要的能力,都在这里
63
+ **Todo → In Progress → Review → Done**
105
64
 
106
- ### 在「看板」标签页中
65
+ 兼容声明:DSH **0.2.0-rc.2 / 0.2.1-rc.3**,支持 Web 与桌面端。1.10 依赖新版图片预览与对话附件接口,0.1.5 用户需先升级。
107
66
 
108
- | 操作 | 使用方式 |
109
- | --- | --- |
110
- | 查找任务 | 顶部搜索卡片 ID、标题、描述、评论;右侧三个按钮按优先级、标签、截止日期筛选。 |
111
- | 管理看板 | 右上角**设置**菜单提供刷新、列编辑、标签编辑和「反馈与建议 · GitHub」。 |
112
- | 推进任务 | 创建、编辑、删除卡片,拖动排序或移到其他列,添加彩色标签与 P0 / P1 / P2 优先级。 |
113
- | 查看详情 | 可调整宽度的侧边抽屉,窄屏自动铺满;描述支持 Markdown 编辑与预览。 |
114
- | 添加图片 | 文件选择、剪贴板粘贴、拖拽上传;卡片展示图片数量,详情中可预览、移除和重试。 |
115
- | 跟踪时间 | 设置截止日期,查看今天到期或逾期任务;进入完成列后自动记录完成日期。 |
116
- | 协作记录 | 与 Agent 互相评论,查看活动时间线,或将任务带入当前/新会话继续处理。 |
117
-
118
- 文字和 Markdown 描述编辑后点击**保存**;**完成编辑**只切回预览。筛选条件在工具栏下方显示,点击条件的 × 或在对应菜单选择「全部」即可清除。
119
-
120
- ### 从任意卡片继续与 Agent 协作
121
-
122
- 打开卡片并选择 **「与 Agent 聊一聊」**,dsh-kanban 会把卡片 ID、标题、标签、截止日期和备注带入当前会话或一个新会话。已保存的图片会一起加入目标聊天框,显示为可预览、可移除的附件。文字和图片都只进入草稿,由你确认后发送,不会自动提交;读取图片失败时会保留任务详情并提示重试。
123
-
124
- ### 搜索任务
125
-
126
- 搜索范围是当前工作区的卡片 ID、标题、完整描述和评论正文,按连续子串匹配,忽略大小写及首尾空格。搜索与所有已选筛选条件取交集,保留原有卡片顺序,切换工作区后清空。Agent 通过 `kanban_get` 的 `{"query":"登录"}` 参数使用相同规则。
127
-
128
- ### 添加与查看图片
129
-
130
- 支持 PNG、JPEG、WebP,每张最多 10 MiB,每张卡片最多 10 张;DSH Host 可进一步限制格式或大小。新建卡片时,选中的图片先保留在浏览器,点击**「保存」**成功创建任务后再上传。部分上传失败时,任务和成功的图片已保存,详情保留失败文件供重试,不会重复建卡。创建前取消不会上传。已有卡片的图片上传和移除立即保存,文字修改仍需点击**「保存」**。Host 不支持图片或工作区无法持久保存时,界面会提示无法上传。
131
-
132
- 点击缩略图打开 DSH 原生大图预览;按 Esc、点击关闭按钮或遮罩返回任务详情。图片不会加入文字搜索范围,暂不提供 OCR。
133
-
134
- ### 数据与备份
135
-
136
- 卡片的 `images` 数组中,每张图片只保存 `attachmentId`、`mediaType`、`bytes`、`width`、`height` 五个字段,不保存文件名和说明。数据格式 v6 为旧卡片补充 `images: []`,迁移前备份原看板文件。工作区的 `.dsh-kanban.json` 只保存引用,图片文件保存在 DSH home 下的原生附件存储中,独立于具体工作区或会话,可被复用。备份时需要同时保留看板文件与 DSH 附件存储。移除图片或删除卡片只解除关联,不物理删除共享图片。
137
-
138
- ### 在对话中
67
+ <details>
68
+ <summary>确认 Web 插件配置</summary>
139
69
 
140
- 插件会自动为每个工作区中的 Agent 提供以下工具:
141
-
142
- | 范围 | 工具 |
143
- | --- | --- |
144
- | **看板** | `kanban_get`、`kanban_set_completed_column` |
145
- | **卡片** | `kanban_get_card`、`kanban_add_comment`、`kanban_add_card`、`kanban_update_card`、`kanban_delete_card`、`kanban_move_card` |
146
- | **图片** | `kanban_add_image`、`kanban_read_image`、`kanban_remove_image` |
147
- | **列表** | `kanban_add_column`、`kanban_rename_column`、`kanban_delete_column`、`kanban_move_column` |
148
- | **标签** | `kanban_get_label`、`kanban_add_label`、`kanban_update_label`、`kanban_delete_label` |
149
-
150
- Agent 添加图片时,先创建卡片,再把返回的 `cardId` 作为 `id`。调用 `kanban_add_image`,参数任选一种来源:
151
-
152
- ```json
153
- {"id":"k1","source":{"kind":"workspace_file","path":"screenshots/login.png"}}
154
- ```
155
-
156
- ```json
157
- {"id":"k1","source":{"kind":"session_attachment","attachmentId":"sha256:<实际附件哈希>"}}
70
+ ```sh
71
+ dsh --profile web --dump-config
158
72
  ```
159
73
 
160
- 文件路径必须相对于当前工作区,且不能越过工作区边界。会话附件必须真实存在于执行 Agent 的当前会话中,使用真实 ID,不猜测哈希;不传 base64 或远程 URL。重复添加同一图片不会重复关联。`kanban_get` 返回图片数量,`kanban_get_card` 返回五字段图片引用。查看图片时调用 `kanban_read_image`,参数为 `{"id":"k1","attachmentId":"sha256:<实际附件哈希>"}`;移除时用相同参数调用 `kanban_remove_image`。两者都会校验图片属于当前工作区的指定卡片。
161
-
162
- `kanban_add_card` 和 `kanban_update_card` 的任务描述仍使用 `note` 字段,传入保留换行的 Markdown 原文,不传 HTML。任务详情会渲染标题、列表、表格和代码块。原文最多 2,000 字符,Markdown 标记和换行也计入长度,超出会截断并返回警告。修改已有描述前,应先调用 `kanban_get_card` 读取完整原文(`kanban_get` 只返回摘要)。传入 `note` 会替换整段描述;省略则保留原文,传空字符串则清空。评论仍为纯文本。
163
-
164
- 完成日期在卡片进入完成列时自动记录(包括直接在完成列创建),移出时清空,再次完成时记录新时间。修改内容、评论、同列排序和列改名/排序不影响完成日期。卡片详情在截止日期旁以本地时区只读展示;两个读取工具均返回 UTC ISO 时间戳 `completedAt` 或 `null`,已完成卡片的 `null` 表示时间未知。更换或清除完成列会重置完成时间,新完成列中已有卡片显示未知;删除列引发自动移动时也遵循进入/离开完成状态的规则。从 v5 之前的数据升级时,历史完成时间保留未知,不根据活动日志推测。
165
-
166
- `kanban_add_card` 和 `kanban_update_card` 可通过 `dueDate` 设置截止日期,值为真实有效的 `YYYY-MM-DD` 日期。省略则保留原日期(新卡片默认为无日期),传 `null` 或空字符串则清空。日期不含时间和时区:今天到期的任务到本地次日才算逾期。「本周五」等相对日期应由 Agent 按用户本地日期换算,并向用户确认具体日期,不要直接传相对文本或 UTC 时间戳。`kanban_get` 和 `kanban_get_card` 都会返回截止日期与看板的 `completedColumnId`。
167
-
168
- 使用 `kanban_set_completed_column`,传已有的 `columnId` 指定完成列,传 `null` 清除设置。新看板默认使用 Done,已有看板需要明确选择一次。设置跟随列 ID,改名和排序不影响;删除完成列会清除设置。完成列中的卡片保留日期,但不计入「今天到期」和「已逾期」筛选,移回其他列后恢复判断。暂不包含自动提醒和按日期自动排序。
74
+ 输出中应包含 `dsh-kanban` 配置层。配置存在不代表当前服务已加载,安装后仍需重启 Web 服务。
169
75
 
170
- > 把「支付联调」的截止日期设为本周五,再列出今天到期和已经逾期的未完成任务,方便我安排先做哪几件事。
76
+ </details>
171
77
 
172
- ## 开发与验证
78
+ ## 继续了解
173
79
 
174
- 使用 Node.js 26 与 pnpm 11.8.0。构建、回归测试及隔离图片集成检查见[验证说明](docs/testing-images.md)。
80
+ - [使用指南](docs/guide.zh.md) — 编辑、搜索、图片与协作。
81
+ - [Agent 工具参考](docs/guide.zh.md#agent-工具参考) — 全部 19 个工具、参数与完成状态规则。
82
+ - [数据与备份](docs/guide.zh.md#数据与备份) — 图片备份需同时保留看板文件和 DSH 附件存储。
83
+ - [开发与验证](docs/testing-images.md) — Node.js 26、pnpm 11.8.0,构建和测试说明。
84
+ - [问题与建议](https://github.com/alpacachen/dsh-kanban/issues) — 提交问题或分享使用反馈。
175
85
 
176
- ## 开源许可
86
+ ---
177
87
 
178
- MIT
88
+ [MIT](LICENSE) · 为 DeepSeek Harness 构建
package/docs/guide.md ADDED
@@ -0,0 +1,125 @@
1
+ # User guide
2
+
3
+ [Back to README](../README.md) · [简体中文](guide.zh.md)
4
+
5
+ ## Using the board
6
+
7
+ | Action | How it works |
8
+ | --- | --- |
9
+ | Find tasks | Search card IDs, titles, descriptions, and comments; the three adjacent buttons filter by priority, label, and due date. |
10
+ | Manage the board | **Settings** at the top right contains refresh, column editing, label editing, and **Feedback · GitHub**. |
11
+ | Move work forward | Create, edit, delete, and drag cards; add color-coded labels and P0 / P1 / P2 priorities. |
12
+ | Read task details | A resizable side drawer remembers its width and fills narrow screens; descriptions support Markdown editing and preview. |
13
+ | Attach images | Choose files, paste from the clipboard, or drag images in; see counts on cards and preview, remove, or retry in task details. |
14
+ | Track dates | Set due dates, find tasks due today or overdue, and record completion dates automatically when cards enter the completion column. |
15
+ | Collaborate | Exchange comments, inspect the activity timeline, or continue a task in the current conversation or a new one. |
16
+
17
+ Click **Save** to apply text and Markdown edits; **Done editing** only switches back to preview. Active filters appear below the toolbar. Remove a filter with its × button or choose **All** in its menu.
18
+
19
+ ### Continue any card with your agent
20
+
21
+ Open a card and choose **Chat with agent**. dsh-kanban carries its ID, title, label, due date, and notes into either the current conversation or a fresh one. Saved images are also added to the target composer as previewable, removable attachments. Text and images remain an editable draft until you choose to send it. An image-read failure keeps the task dialog open with an error for retry.
22
+
23
+ <details>
24
+ <summary>Earlier dark-mode and Markdown task details</summary>
25
+
26
+ ![View dark mode and Markdown task details](screenshots/card-details-dark.png)
27
+
28
+ Interface example captured in an earlier version.
29
+
30
+ </details>
31
+
32
+ ## Prompt examples
33
+
34
+ Start with work you actually need to move forward. Replace the project names and context below with your own, then send the prompt to your agent.
35
+
36
+ **Turn a requirement into tasks with clear acceptance criteria**
37
+
38
+ > We need to ship phone-number sign-in next week. Check the existing cards, then create tasks for any missing API, verification code, abuse prevention, UI, and testing work. Record dependencies and use Markdown descriptions for implementation steps and acceptance criteria. Mark launch blockers as P0 and prioritize the remaining work.
39
+
40
+ **Pick up work already in progress**
41
+
42
+ > Continue “Redirected back to login after signing in.” Read the full description and comments, summarize what we know and the next step, and move it to In Progress. Record progress and test results in comments, then move it to Review for me to verify.
43
+
44
+ <details>
45
+ <summary>More examples: blockers, weekly meetings, and custom workflows</summary>
46
+
47
+ **Track work blocked on someone else**
48
+
49
+ > “Payment integration” is waiting for a test account from the provider. Create a Blocked list if needed and move the card there. Add a comment with the blocker, the contact we still need to confirm, and what to do once the account arrives.
50
+
51
+ **Prepare a weekly meeting from the board**
52
+
53
+ > Use the current card statuses, descriptions, and comments to prepare our meeting notes: completed work, work in progress, and blockers that need coordination. Reference the relevant cards and suggest the three most useful next actions. Flag missing information as questions to resolve.
54
+
55
+ **Build a workflow for your profession**
56
+
57
+ > I'm a lawyer handling contract reviews and case preparation. Set up suitable stages and labels, then create cards for the matters I provide below. Record deliverables, required documents, and agreed dates in each description. Put matters with missing documents in “Waiting for documents.”
58
+
59
+ </details>
60
+
61
+ ## Usage details
62
+
63
+ <details>
64
+ <summary>Search scope, image limits, and saving behavior</summary>
65
+
66
+ ### Search tasks
67
+
68
+ Search covers the current workspace's card ID, title, complete description, and comment text. It matches a literal substring, ignores case and surrounding whitespace, and combines with all active filters using AND. It preserves card order and resets when switching workspaces. The agent uses the same search through `kanban_get` with `{"query":"login"}`.
69
+
70
+ ### Add and preview images
71
+
72
+ Images support PNG, JPEG, and WebP, up to 10 MiB each and 10 images per card; the DSH Host can impose stricter format or size limits. In a new card, selected images stay in the browser until **Save** creates the card. If an upload fails, the created card and successful images remain saved, and the drawer keeps failed files for retry without creating another card. Canceling before creation uploads nothing. For an existing card, image uploads and removals save immediately; text edits still require **Save**. Unsupported Hosts or workspaces that cannot persist data show an upload-unavailable message.
73
+
74
+ Click a thumbnail to open DSH's native full-size preview. Escape, the close button, or the backdrop returns to task details. Image contents are not included in text search; OCR is not supported.
75
+
76
+ </details>
77
+
78
+ ## Data and backups
79
+
80
+ Each card has an `images` array containing only `attachmentId`, `mediaType`, `bytes`, `width`, and `height` per image. Names and captions are not saved. Schema v6 adds `images: []` to existing cards and backs up the old board file before migration. The workspace's `.dsh-kanban.json` holds image references; image files live in DSH's native attachment store under its DSH home, shared independently of a particular workspace or conversation. Back up both the board file and the DSH attachment store to preserve images. Removing an image or card removes the association, not the shared image object.
81
+
82
+ ## Agent tool reference
83
+
84
+ The plugin gives the agent 19 tools in every workspace:
85
+
86
+ | Area | Tools |
87
+ | --- | --- |
88
+ | **Board** | `kanban_get`, `kanban_set_completed_column` |
89
+ | **Cards** | `kanban_get_card`, `kanban_add_comment`, `kanban_add_card`, `kanban_update_card`, `kanban_delete_card`, `kanban_move_card` |
90
+ | **Images** | `kanban_add_image`, `kanban_read_image`, `kanban_remove_image` |
91
+ | **Lists** | `kanban_add_column`, `kanban_rename_column`, `kanban_delete_column`, `kanban_move_column` |
92
+ | **Labels** | `kanban_get_label`, `kanban_add_label`, `kanban_update_label`, `kanban_delete_label` |
93
+
94
+ <details>
95
+ <summary>Image arguments and access scope</summary>
96
+
97
+ For images, create the card first and use the returned `cardId` as `id`. Call `kanban_add_image` with one of these argument objects:
98
+
99
+ ```json
100
+ {"id":"k1","source":{"kind":"workspace_file","path":"screenshots/login.png"}}
101
+ ```
102
+
103
+ ```json
104
+ {"id":"k1","source":{"kind":"session_attachment","attachmentId":"sha256:<actual attachment hash>"}}
105
+ ```
106
+
107
+ The file path must be relative to the current workspace and stay inside it. A session attachment must actually belong to the executing agent's current session; use its real ID, not a fabricated hash. Do not pass base64 or a remote URL. Repeating the same image does not create another association. `kanban_get` returns image counts; `kanban_get_card` returns the five-field references. Use `kanban_read_image` with `{"id":"k1","attachmentId":"sha256:<actual attachment hash>"}` to inspect pixels, or `kanban_remove_image` with the same arguments to detach it. Both verify that the image belongs to that card in the current workspace.
108
+
109
+ </details>
110
+
111
+ <details>
112
+ <summary>Markdown descriptions, due dates, and completion</summary>
113
+
114
+ For `kanban_add_card` and `kanban_update_card`, the task description uses the existing `note` field: send raw Markdown with line breaks, not HTML. Headings, lists, tables and fenced code blocks are rendered in task details. Keep the source within 2,000 characters, including Markdown syntax and newlines; longer input is truncated with a warning. Before editing a description, read `kanban_get_card` for its complete Markdown source (`kanban_get` only returns a summary). Updating `note` replaces the whole description; omit it to preserve the current text, or pass an empty string to clear it. Comments remain plain text.
115
+
116
+ For due dates, `kanban_add_card` and `kanban_update_card` accept `dueDate` as a real calendar date in `YYYY-MM-DD` format. Omit it to keep the current date (new cards default to none); use `null` or an empty string to clear it. Dates have no time or timezone: a task due today becomes overdue the next local calendar day. Resolve phrases such as “this Friday” against the user's local date and confirm the concrete date instead of sending relative text or a UTC timestamp. Both `kanban_get` and `kanban_get_card` return the date and the board's `completedColumnId`.
117
+
118
+ Completion dates are recorded automatically when a card enters the configured completion list (including creation there). Reopening clears the date; completing again records a new timestamp. Edits, comments, same-list sorting, and column renames/reordering preserve it. Card details show the local completion time next to the due date; it is read-only. Both read tools return `completedAt` as a UTC ISO timestamp, or `null`. A completed card with `null` has an unknown completion time. Changing or clearing the completion list resets completion dates; existing cards in the newly selected list have unknown dates. Deleting a list applies the same completion rules to its automatic card moves. When upgrading from a schema older than v5, historical completion times remain unknown rather than being inferred from the activity log.
119
+
120
+ Use `kanban_set_completed_column` with an existing `columnId` to designate the finished stage, or `null` to clear it. New boards use their default Done column; existing boards need an explicit choice. Completion follows the column ID through renames and reordering, and deleting that column clears the setting. Cards in the completion column keep their dates but are excluded from **Due today** and **Overdue** filters; moving them out resumes date checks. There are no automatic reminders or date-based reordering.
121
+
122
+ > Set the payment integration task's due date to this Friday, then show me unfinished tasks that are due today or overdue so I can decide what to tackle first.
123
+
124
+ </details>
125
+
@@ -0,0 +1,125 @@
1
+ # 使用指南
2
+
3
+ [返回首页](../README.zh.md) · [English](guide.md)
4
+
5
+ ## 使用看板
6
+
7
+ | 操作 | 使用方式 |
8
+ | --- | --- |
9
+ | 查找任务 | 顶部搜索卡片 ID、标题、描述、评论;右侧三个按钮按优先级、标签、截止日期筛选。 |
10
+ | 管理看板 | 右上角**设置**菜单提供刷新、列编辑、标签编辑和「反馈与建议 · GitHub」。 |
11
+ | 推进任务 | 创建、编辑、删除卡片,拖动排序或移到其他列,添加彩色标签与 P0 / P1 / P2 优先级。 |
12
+ | 查看详情 | 可调整宽度的侧边抽屉,窄屏自动铺满;描述支持 Markdown 编辑与预览。 |
13
+ | 添加图片 | 文件选择、剪贴板粘贴、拖拽上传;卡片展示图片数量,详情中可预览、移除和重试。 |
14
+ | 跟踪时间 | 设置截止日期,查看今天到期或逾期任务;进入完成列后自动记录完成日期。 |
15
+ | 协作记录 | 与 Agent 互相评论,查看活动时间线,或将任务带入当前/新会话继续处理。 |
16
+
17
+ 文字和 Markdown 描述编辑后点击**保存**;**完成编辑**只切回预览。筛选条件在工具栏下方显示,点击条件的 × 或在对应菜单选择「全部」即可清除。
18
+
19
+ ### 从任意卡片继续与 Agent 协作
20
+
21
+ 打开卡片并选择 **「与 Agent 聊一聊」**,dsh-kanban 会把卡片 ID、标题、标签、截止日期和备注带入当前会话或一个新会话。已保存的图片会一起加入目标聊天框,显示为可预览、可移除的附件。文字和图片都只进入草稿,由你确认后发送,不会自动提交;读取图片失败时会保留任务详情并提示重试。
22
+
23
+ <details>
24
+ <summary>较早版本的深色模式与 Markdown 任务详情</summary>
25
+
26
+ ![查看深色模式与 Markdown 任务详情](screenshots/card-details-dark.png)
27
+
28
+ 界面示意:截图为较早版本。
29
+
30
+ </details>
31
+
32
+ ## 对话示例
33
+
34
+ 从你正在做的事开始。把下面例子里的项目名称和背景换成自己的,就可以直接发给 Agent。
35
+
36
+ **把需求拆成可验收的任务**
37
+
38
+ > 下周要上线手机号登录。先看看已有卡片,再为缺少的接口、验证码、防刷、前端交互和测试工作建卡。写清依赖关系,并在描述里用 Markdown 列出实现步骤和验收标准。影响上线的任务标为 P0,其余排好优先级。
39
+
40
+ **接手一项正在做的工作**
41
+
42
+ > 接着处理「登录后跳回登录页」。先读完整描述和评论,梳理已有结论与下一步,移到 In Progress。推进过程和测试结果记到评论,完成后移到 Review 等我验收。
43
+
44
+ <details>
45
+ <summary>更多示例:阻塞跟进、周会与职业工作流</summary>
46
+
47
+ **跟进被外部依赖卡住的事项**
48
+
49
+ > 「支付联调」还在等对方提供测试账号。建一个 Blocked 列表(已有就复用),把任务移过去,并在评论里记录阻塞原因、待确认的联系人,以及拿到账号后的下一步。
50
+
51
+ **用现有看板准备周会**
52
+
53
+ > 根据当前卡片的状态、描述和评论,整理周会提纲:已完成什么、哪些工作还在推进、有哪些阻塞需要协调。引用相关卡片,给出接下来最值得推进的三件事;信息不全的地方列成待确认项。
54
+
55
+ **为自己的职业建立工作流**
56
+
57
+ > 我是一名律师,要同时跟进合同审查和案件材料准备。帮我整理适合的阶段列表与标签,把我下面提供的事项逐一建卡,在描述里记录交付要求、材料清单和约定时间;缺少材料的放到「等待补充」。
58
+
59
+ </details>
60
+
61
+ ## 使用规则
62
+
63
+ <details>
64
+ <summary>搜索范围、图片限制与保存行为</summary>
65
+
66
+ ### 搜索任务
67
+
68
+ 搜索范围是当前工作区的卡片 ID、标题、完整描述和评论正文,按连续子串匹配,忽略大小写及首尾空格。搜索与所有已选筛选条件取交集,保留原有卡片顺序,切换工作区后清空。Agent 通过 `kanban_get` 的 `{"query":"登录"}` 参数使用相同规则。
69
+
70
+ ### 添加与查看图片
71
+
72
+ 支持 PNG、JPEG、WebP,每张最多 10 MiB,每张卡片最多 10 张;DSH Host 可进一步限制格式或大小。新建卡片时,选中的图片先保留在浏览器,点击**「保存」**成功创建任务后再上传。部分上传失败时,任务和成功的图片已保存,详情保留失败文件供重试,不会重复建卡。创建前取消不会上传。已有卡片的图片上传和移除立即保存,文字修改仍需点击**「保存」**。Host 不支持图片或工作区无法持久保存时,界面会提示无法上传。
73
+
74
+ 点击缩略图打开 DSH 原生大图预览;按 Esc、点击关闭按钮或遮罩返回任务详情。图片不会加入文字搜索范围,暂不提供 OCR。
75
+
76
+ </details>
77
+
78
+ ## 数据与备份
79
+
80
+ 卡片的 `images` 数组中,每张图片只保存 `attachmentId`、`mediaType`、`bytes`、`width`、`height` 五个字段,不保存文件名和说明。数据格式 v6 为旧卡片补充 `images: []`,迁移前备份原看板文件。工作区的 `.dsh-kanban.json` 只保存引用,图片文件保存在 DSH home 下的原生附件存储中,独立于具体工作区或会话,可被复用。备份时需要同时保留看板文件与 DSH 附件存储。移除图片或删除卡片只解除关联,不物理删除共享图片。
81
+
82
+ ## Agent 工具参考
83
+
84
+ 插件为每个工作区中的 Agent 提供 19 个工具:
85
+
86
+ | 范围 | 工具 |
87
+ | --- | --- |
88
+ | **看板** | `kanban_get`、`kanban_set_completed_column` |
89
+ | **卡片** | `kanban_get_card`、`kanban_add_comment`、`kanban_add_card`、`kanban_update_card`、`kanban_delete_card`、`kanban_move_card` |
90
+ | **图片** | `kanban_add_image`、`kanban_read_image`、`kanban_remove_image` |
91
+ | **列表** | `kanban_add_column`、`kanban_rename_column`、`kanban_delete_column`、`kanban_move_column` |
92
+ | **标签** | `kanban_get_label`、`kanban_add_label`、`kanban_update_label`、`kanban_delete_label` |
93
+
94
+ <details>
95
+ <summary>图片参数与访问范围</summary>
96
+
97
+ Agent 添加图片时,先创建卡片,再把返回的 `cardId` 作为 `id`。调用 `kanban_add_image`,参数任选一种来源:
98
+
99
+ ```json
100
+ {"id":"k1","source":{"kind":"workspace_file","path":"screenshots/login.png"}}
101
+ ```
102
+
103
+ ```json
104
+ {"id":"k1","source":{"kind":"session_attachment","attachmentId":"sha256:<实际附件哈希>"}}
105
+ ```
106
+
107
+ 文件路径必须相对于当前工作区,且不能越过工作区边界。会话附件必须真实存在于执行 Agent 的当前会话中,使用真实 ID,不猜测哈希;不传 base64 或远程 URL。重复添加同一图片不会重复关联。`kanban_get` 返回图片数量,`kanban_get_card` 返回五字段图片引用。查看图片时调用 `kanban_read_image`,参数为 `{"id":"k1","attachmentId":"sha256:<实际附件哈希>"}`;移除时用相同参数调用 `kanban_remove_image`。两者都会校验图片属于当前工作区的指定卡片。
108
+
109
+ </details>
110
+
111
+ <details>
112
+ <summary>Markdown 描述、截止日期与完成状态</summary>
113
+
114
+ `kanban_add_card` 和 `kanban_update_card` 的任务描述仍使用 `note` 字段,传入保留换行的 Markdown 原文,不传 HTML。任务详情会渲染标题、列表、表格和代码块。原文最多 2,000 字符,Markdown 标记和换行也计入长度,超出会截断并返回警告。修改已有描述前,应先调用 `kanban_get_card` 读取完整原文(`kanban_get` 只返回摘要)。传入 `note` 会替换整段描述;省略则保留原文,传空字符串则清空。评论仍为纯文本。
115
+
116
+ 完成日期在卡片进入完成列时自动记录(包括直接在完成列创建),移出时清空,再次完成时记录新时间。修改内容、评论、同列排序和列改名/排序不影响完成日期。卡片详情在截止日期旁以本地时区只读展示;两个读取工具均返回 UTC ISO 时间戳 `completedAt` 或 `null`,已完成卡片的 `null` 表示时间未知。更换或清除完成列会重置完成时间,新完成列中已有卡片显示未知;删除列引发自动移动时也遵循进入/离开完成状态的规则。从 v5 之前的数据升级时,历史完成时间保留未知,不根据活动日志推测。
117
+
118
+ `kanban_add_card` 和 `kanban_update_card` 可通过 `dueDate` 设置截止日期,值为真实有效的 `YYYY-MM-DD` 日期。省略则保留原日期(新卡片默认为无日期),传 `null` 或空字符串则清空。日期不含时间和时区:今天到期的任务到本地次日才算逾期。「本周五」等相对日期应由 Agent 按用户本地日期换算,并向用户确认具体日期,不要直接传相对文本或 UTC 时间戳。`kanban_get` 和 `kanban_get_card` 都会返回截止日期与看板的 `completedColumnId`。
119
+
120
+ 使用 `kanban_set_completed_column`,传已有的 `columnId` 指定完成列,传 `null` 清除设置。新看板默认使用 Done,已有看板需要明确选择一次。设置跟随列 ID,改名和排序不影响;删除完成列会清除设置。完成列中的卡片保留日期,但不计入「今天到期」和「已逾期」筛选,移回其他列后恢复判断。暂不包含自动提醒和按日期自动排序。
121
+
122
+ > 把「支付联调」的截止日期设为本周五,再列出今天到期和已经逾期的未完成任务,方便我安排先做哪几件事。
123
+
124
+ </details>
125
+
Binary file
Binary file
Binary file
Binary file
Binary file
Binary file
package/lib/client.js CHANGED
@@ -1784,7 +1784,7 @@ lucide-react/dist/esm/icons/trash.mjs:
1784
1784
  lucide-react/dist/esm/icons/x.mjs:
1785
1785
  lucide-react/dist/esm/lucide-react.mjs:
1786
1786
  (**
1787
- * @license lucide-react v1.59.0 - ISC
1787
+ * @license lucide-react v1.61.0 - ISC
1788
1788
  *
1789
1789
  * This source code is licensed under the ISC license.
1790
1790
  * See the LICENSE file in the root directory of this source tree.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alpacachen/dsh-kanban",
3
- "version": "1.10.0",
3
+ "version": "1.10.1",
4
4
  "description": "A collaborative kanban board for DeepSeek Harness with text search, native image attachments, due dates, comments and 19 agent tools.",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -20,6 +20,9 @@
20
20
  "image.png",
21
21
  "docs/screenshots/card-details-dark.png",
22
22
  "docs/testing-images.md",
23
+ "docs/guide.md",
24
+ "docs/guide.zh.md",
25
+ "docs/readme/*.png",
23
26
  "LICENSE"
24
27
  ],
25
28
  "scripts": {