# 使用指南

[返回首页](../README.zh.md) · [English](guide.md)

## 使用看板

| 操作 | 使用方式 |
| --- | --- |
| 查找任务 | 顶部搜索卡片 ID、标题、描述、评论；右侧三个按钮按优先级、标签、截止日期筛选。 |
| 管理看板 | 右上角**设置**菜单提供刷新、列编辑、标签编辑和「反馈与建议 · GitHub」。 |
| 推进任务 | 创建、编辑、删除卡片，拖动排序或移到其他列，添加彩色标签与 P0 / P1 / P2 优先级。 |
| 查看详情 | 可调整宽度的侧边抽屉，窄屏自动铺满；描述支持 Markdown 编辑与预览。 |
| 添加图片 | 文件选择、剪贴板粘贴、拖拽上传；卡片展示图片数量，详情中可预览、移除和重试。 |
| 跟踪时间 | 设置截止日期，查看今天到期或逾期任务；进入完成列后自动记录完成日期。 |
| 协作记录 | 与 Agent 互相评论，查看活动时间线，或将任务带入当前／新会话继续处理。 |

文字和 Markdown 描述编辑后点击**保存**；**完成编辑**只切回预览。筛选条件在工具栏下方显示，点击条件的 × 或在对应菜单选择「全部」即可清除。

### 从任意卡片继续与 Agent 协作

打开卡片并选择 **「与 Agent 聊一聊」**，dsh-kanban 会把卡片 ID、标题、标签、截止日期和备注带入当前会话或一个新会话。已保存的图片会一起加入目标聊天框，显示为可预览、可移除的附件。文字和图片都只进入草稿，由你确认后发送，不会自动提交；读取图片失败时会保留任务详情并提示重试。

<details>
<summary>较早版本的深色模式与 Markdown 任务详情</summary>

![查看深色模式与 Markdown 任务详情](screenshots/card-details-dark.png)

界面示意：截图为较早版本。

</details>

## 对话示例

从你正在做的事开始。把下面例子里的项目名称和背景换成自己的，就可以直接发给 Agent。

**把需求拆成可验收的任务**

> 下周要上线手机号登录。先看看已有卡片，再为缺少的接口、验证码、防刷、前端交互和测试工作建卡。写清依赖关系，并在描述里用 Markdown 列出实现步骤和验收标准。影响上线的任务标为 P0，其余排好优先级。

**接手一项正在做的工作**

> 接着处理「登录后跳回登录页」。先读完整描述和评论，梳理已有结论与下一步，移到 In Progress。推进过程和测试结果记到评论，完成后移到 Review 等我验收。

<details>
<summary>更多示例：阻塞跟进、周会与职业工作流</summary>

**跟进被外部依赖卡住的事项**

> 「支付联调」还在等对方提供测试账号。建一个 Blocked 列表（已有就复用），把任务移过去，并在评论里记录阻塞原因、待确认的联系人，以及拿到账号后的下一步。

**用现有看板准备周会**

> 根据当前卡片的状态、描述和评论，整理周会提纲：已完成什么、哪些工作还在推进、有哪些阻塞需要协调。引用相关卡片，给出接下来最值得推进的三件事；信息不全的地方列成待确认项。

**为自己的职业建立工作流**

> 我是一名律师，要同时跟进合同审查和案件材料准备。帮我整理适合的阶段列表与标签，把我下面提供的事项逐一建卡，在描述里记录交付要求、材料清单和约定时间；缺少材料的放到「等待补充」。

</details>

## 使用规则

<details>
<summary>搜索范围、图片限制与保存行为</summary>

### 搜索任务

搜索范围是当前工作区的卡片 ID、标题、完整描述和评论正文，按连续子串匹配，忽略大小写及首尾空格。搜索与所有已选筛选条件取交集，保留原有卡片顺序，切换工作区后清空。Agent 通过 `kanban_get` 的 `{"query":"登录"}` 参数使用相同规则。

### 添加与查看图片

支持 PNG、JPEG、WebP，每张最多 10 MiB，每张卡片最多 10 张；DSH Host 可进一步限制格式或大小。新建卡片时，选中的图片先保留在浏览器，点击**「保存」**成功创建任务后再上传。部分上传失败时，任务和成功的图片已保存，详情保留失败文件供重试，不会重复建卡。创建前取消不会上传。已有卡片的图片上传和移除立即保存，文字修改仍需点击**「保存」**。Host 不支持图片或工作区无法持久保存时，界面会提示无法上传。

点击缩略图打开 DSH 原生大图预览；按 Esc、点击关闭按钮或遮罩返回任务详情。图片不会加入文字搜索范围，暂不提供 OCR。

</details>

## 数据与备份

卡片的 `images` 数组中，每张图片只保存 `attachmentId`、`mediaType`、`bytes`、`width`、`height` 五个字段，不保存文件名和说明。数据格式 v6 为旧卡片补充 `images: []`，迁移前备份原看板文件。工作区的 `.dsh-kanban.json` 只保存引用，图片文件保存在 DSH home 下的原生附件存储中，独立于具体工作区或会话，可被复用。备份时需要同时保留看板文件与 DSH 附件存储。移除图片或删除卡片只解除关联，不物理删除共享图片。

## Agent 工具参考

插件为每个工作区中的 Agent 提供 19 个工具：

| 范围 | 工具 |
| --- | --- |
| **看板** | `kanban_get`、`kanban_set_completed_column` |
| **卡片** | `kanban_get_card`、`kanban_add_comment`、`kanban_add_card`、`kanban_update_card`、`kanban_delete_card`、`kanban_move_card` |
| **图片** | `kanban_add_image`、`kanban_read_image`、`kanban_remove_image` |
| **列表** | `kanban_add_column`、`kanban_rename_column`、`kanban_delete_column`、`kanban_move_column` |
| **标签** | `kanban_get_label`、`kanban_add_label`、`kanban_update_label`、`kanban_delete_label` |

<details>
<summary>图片参数与访问范围</summary>

Agent 添加图片时，先创建卡片，再把返回的 `cardId` 作为 `id`。调用 `kanban_add_image`，参数任选一种来源：

```json
{"id":"k1","source":{"kind":"workspace_file","path":"screenshots/login.png"}}
```

```json
{"id":"k1","source":{"kind":"session_attachment","attachmentId":"sha256:<实际附件哈希>"}}
```

文件路径必须相对于当前工作区，且不能越过工作区边界。会话附件必须真实存在于执行 Agent 的当前会话中，使用真实 ID，不猜测哈希；不传 base64 或远程 URL。重复添加同一图片不会重复关联。`kanban_get` 返回图片数量，`kanban_get_card` 返回五字段图片引用。查看图片时调用 `kanban_read_image`，参数为 `{"id":"k1","attachmentId":"sha256:<实际附件哈希>"}`；移除时用相同参数调用 `kanban_remove_image`。两者都会校验图片属于当前工作区的指定卡片。

</details>

<details>
<summary>Markdown 描述、截止日期与完成状态</summary>

`kanban_add_card` 和 `kanban_update_card` 的任务描述仍使用 `note` 字段，传入保留换行的 Markdown 原文，不传 HTML。任务详情会渲染标题、列表、表格和代码块。原文最多 2,000 字符，Markdown 标记和换行也计入长度，超出会截断并返回警告。修改已有描述前，应先调用 `kanban_get_card` 读取完整原文（`kanban_get` 只返回摘要）。传入 `note` 会替换整段描述；省略则保留原文，传空字符串则清空。评论仍为纯文本。

完成日期在卡片进入完成列时自动记录（包括直接在完成列创建），移出时清空，再次完成时记录新时间。修改内容、评论、同列排序和列改名／排序不影响完成日期。卡片详情在截止日期旁以本地时区只读展示；两个读取工具均返回 UTC ISO 时间戳 `completedAt` 或 `null`，已完成卡片的 `null` 表示时间未知。更换或清除完成列会重置完成时间，新完成列中已有卡片显示未知；删除列引发自动移动时也遵循进入／离开完成状态的规则。从 v5 之前的数据升级时，历史完成时间保留未知，不根据活动日志推测。

`kanban_add_card` 和 `kanban_update_card` 可通过 `dueDate` 设置截止日期，值为真实有效的 `YYYY-MM-DD` 日期。省略则保留原日期（新卡片默认为无日期），传 `null` 或空字符串则清空。日期不含时间和时区：今天到期的任务到本地次日才算逾期。「本周五」等相对日期应由 Agent 按用户本地日期换算，并向用户确认具体日期，不要直接传相对文本或 UTC 时间戳。`kanban_get` 和 `kanban_get_card` 都会返回截止日期与看板的 `completedColumnId`。

使用 `kanban_set_completed_column`，传已有的 `columnId` 指定完成列，传 `null` 清除设置。新看板默认使用 Done，已有看板需要明确选择一次。设置跟随列 ID，改名和排序不影响；删除完成列会清除设置。完成列中的卡片保留日期，但不计入「今天到期」和「已逾期」筛选，移回其他列后恢复判断。暂不包含自动提醒和按日期自动排序。

> 把「支付联调」的截止日期设为本周五，再列出今天到期和已经逾期的未完成任务，方便我安排先做哪几件事。

</details>