D
Datronis
Kanban Studio›Markdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

概述

每个看板都由纯文本 Markdown 文档支持，您可以阅读、编写、复制和版本控制。该文档有两个部分：一个机器可读的 结构化 块，以 JSON 形式保存棋盘数据，以及一个用于保存个人笔记的自由格式 自定义 块。

架构 v1JSON+Markdown干运行安全
💡

始终先进行空运行

单击“应用”之前，请使用“试运行”按钮来验证您的编辑。后端将报告错误和差异摘要，而无需修改您的主板。

文件结构

完整的看板 Markdown 文档由三部分组成：

  • 人类可读的标题（板标题、生成注释）
  • 结构化块 — HTML 注释标记之间的 JSON 数据
  • 自定义块 — 免费 Markdown（注释、美人鱼图、链接）
board.md
# My Project Board

Generated by Kanban Markdown schema v1.

<!-- KANBAN:STRUCTURED:START -->
```kanban-structured
{
  "version": 1,
  "board": {
    "id": "board-abc123",
    "title": "My Project Board"
  },
  "columns": [
    { "id": "col-1", "title": "Backlog",     "color": "#64748b", "order": 0 },
    { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
    { "id": "col-3", "title": "Done",        "color": "#10b981", "order": 2 }
  ],
  "tasks": [
    {
      "id": "task-1",
      "columnId": "col-2",
      "position": 0,
      "title": "Build authentication flow",
      "description": "Implement JWT login, register, and token refresh.",
      "priority": "high",
      "tags": ["backend", "security"],
      "assigneeIds": ["member-uuid-1"],
      "mentionMemberIds": ["member-uuid-2"],
      "estimatePoints": 5,
      "dueDate": "2025-03-15",
      "plannedStartAt": "2025-03-10",
      "plannedEndAt": "2025-03-15",
      "timeboxMinutes": 90,
      "isCompleted": false,
      "archivedAt": null,
      "checklist": [
        { "title": "Design DB schema",   "isDone": true  },
        { "title": "Write unit tests",   "isDone": false },
        { "title": "Deploy to staging",  "isDone": false }
      ]
    }
  ]
}
```
<!-- KANBAN:STRUCTURED:END -->

<!-- KANBAN:CUSTOM:START -->
## Team Notes

- Sprint ends Friday
- Backend review at 3 PM

```mermaid
flowchart LR
  A[Backlog] --> B[In Progress] --> C[Done]
```
<!-- KANBAN:CUSTOM:END -->
完整的董事会文件，所有部分均已注释
⚠️

不要删除评论标记

需要标记 <!-- KANBAN:STRUCTURED:START -->、<!-- KANBAN:STRUCTURED:END -->、<!-- KANBAN:CUSTOM:START --> 和 <!-- KANBAN:CUSTOM:END -->。删除它们会导致解析错误。

专栏

列定义了董事会的工作流程阶段。它们按照 order 值从左到右呈现。

JSON
"columns": [
  { "id": "col-1", "title": "To Do",       "color": "#64748b", "order": 0 },
  { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
  { "id": "col-3", "title": "Review",      "color": "#f59e0b", "order": 2 },
  { "id": "col-4", "title": "Done",        "color": "#10b981", "order": 3 }
]
示例：具有不同颜色的四列
FieldTypeRequiredDescription
idstringYes唯一的列标识符（UUID 或任何稳定的段）
titlestringYes板上显示的列标题
colorstringYes列强调色（十六进制）。显示为卡片的左边框
orderintegerYes从零开始的显示顺序（升序，从左到右）
ℹ️

Note

列 ID 在板内必须是唯一的。任务通过此 id 引用列。

任务

任务是工作的核心单元。每个任务都位于一列中（通过 columnId），并按该列中的 position 排序。

最小任务

JSON
{
  "id": "task-abc",
  "columnId": "col-1",
  "position": 0,
  "title": "Write release notes",
  "description": "",
  "priority": "medium",
  "tags": [],
  "assigneeIds": [],
  "mentionMemberIds": [],
  "estimatePoints": null,
  "dueDate": null,
  "plannedStartAt": null,
  "plannedEndAt": null,
  "timeboxMinutes": null,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": []
}
仅填写必填字段 - 所有可选字段均为空/空

包含所有字段的完整任务

JSON
{
  "id": "task-xyz",
  "columnId": "col-2",
  "position": 0,
  "title": "Redesign checkout page",
  "description": "Full UX overhaul based on user research findings.",
  "priority": "critical",
  "tags": ["ux", "frontend", "q1-goal"],
  "assigneeIds": ["member-alice", "member-bob"],
  "mentionMemberIds": ["member-pm"],
  "estimatePoints": 8,
  "dueDate": "2025-04-01",
  "plannedStartAt": "2025-03-20",
  "plannedEndAt": "2025-04-01",
  "timeboxMinutes": 120,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": [
    { "title": "User interviews",       "isDone": true  },
    { "title": "Wireframes approved",   "isDone": true  },
    { "title": "Implement components",  "isDone": false },
    { "title": "A/B test live",         "isDone": false }
  ]
}
具有优先级、标签、受让人、清单、时间跟踪的生产示例
FieldTypeRequiredDescription
idstringYes唯一的任务标识符（UUID 或稳定的 slug）
columnIdstringYes该任务所属列的ID
positionintegerYes列内从零开始的排序顺序
titlestringYes任务标题（1–280 个字符）
descriptionstringNo兼容 Markdown 的较长描述
priorityenum
"low""medium""high""critical"
No任务紧急程度
tagsstring[]No用于过滤和分组的自由格式标签字符串
assigneeIdsstring[]No分配给此任务的人员的成员 ID
mentionMemberIdsstring[]No此任务中提到（通知）的成员 ID
estimatePointsinteger|nullNo故事点估计（斐波那契：1、2、3、5、8、13…）
dueDatestring|nullNoISO 8601 日期字符串：YYYY-MM-DD
plannedStartAtstring|nullNoISO 8601 日期时间：计划开始
plannedEndAtstring|nullNoISO 8601 日期时间：计划结束
timeboxMinutesinteger|nullNo时间盒的焦点会议长度
isCompletedbooleanNo将任务标记为已完成（在 UI 中添加删除线）
archivedAtstring|nullNo任务存档时的 ISO 8601 日期时间。已归档的任务对看板隐藏
checklistobject[]No子任务清单项目（参见清单部分）

清单项目

每个任务都支持清单项目的平面列表 - 轻量级子任务可以单独标记为已完成，而无需创建单独的任务。

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
三个清单项目：第一个完成，剩下两个
FieldTypeRequiredDescription
titlestringYes检查清单项目标签（1–255 个字符）
isDonebooleanYes该项是否被勾选

自定义注释部分

<!-- KANBAN:CUSTOM:START --> 和 <!-- KANBAN:CUSTOM:END --> 之间的所有内容都是您的暂存器。它支持完整的 Markdown 和 Mermaid 图。板引擎永远不会解析内容 - 它仅显示在“预览”选项卡中。

Markdown
<!-- KANBAN:CUSTOM:START -->
## Sprint Notes

- Daily standup at 10:00 AM
- Backend API freeze on Friday

```mermaid
gantt
  title Sprint 12
  section Tasks
  Auth flow     :done, 2025-03-10, 3d
  Dashboard UI  :active, 2025-03-13, 4d
  API docs      :2025-03-17, 2d
```

> Reminder: update JIRA tickets before end of day.
<!-- KANBAN:CUSTOM:END -->
带有美人鱼甘特图的笔记
💡

Tip

使用“自定义”部分来显示冲刺注释、团队链接、甘特图、架构图 - 您希望与看板数据一起显示的任何内容。

优先值

priority 字段仅接受四个值之一。每个都映射到 UI 中不同的徽章颜色：

FieldTypeRequiredDescription
lowenum valueNo紧迫性低。显示为石板色/灰色。
mediumenum valueNo默认。显示为琥珀色/黄色。省略优先级默认为此。
highenum valueNo重要。以橙色显示。
criticalenum valueNo阻塞。显示为红色/玫瑰色。

归档任务

要存档任务，请将其 archivedAt 字段设置为 ISO 日期时间字符串。存档的任务从活动看板视图中排除，但保留在历史记录中。

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
存档任务 - 从板上隐藏，保存在快照中
ℹ️

Note

将 archivedAt 设置为 null 取消归档任务。当应用对板上当前活动任务进行存档的 Markdown 快照时，差异摘要将显示tasksToArchive。

试运行和诊断

试运行功能可在不应用更改的情况下验证您的降价。后端返回一个 diffSummary （会发生变化的内容）和一个 diagnostics 数组，列出所有错误或警告。

成功的试运行响应

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: true 表示降价有效并且可以安全应用

试运行时出现错误

JSON
{
  "ok": false,
  "dryRun": true,
  "diagnostics": [
    {
      "code": "unknown_column_id",
      "message": "Task 'task-xyz' references unknown column 'col-999'.",
      "line": 42,
      "severity": "error"
    },
    {
      "code": "duplicate_task_id",
      "message": "Task ID 'task-abc' is used more than once.",
      "line": 67,
      "severity": "error"
    }
  ],
  "diffSummary": {
    "columnsCreated": 0,
    "columnsTouched": 0,
    "tasksCreated": 0,
    "tasksTouched": 0,
    "tasksToArchive": 0
  }
}
ok: false — 在应用之前修复错误
FieldTypeRequiredDescription
codestringYes机器可读的错误代码（例如unknown_column_id）
messagestringYes人类可读的问题描述
lineintegerYesMarkdown 文档中的大致行号
severityenum
"error""warning"
Yes“错误”（阻止应用）或“警告”（应用收益）
🚫

错误阻止应用

如果诊断包含任何严重性为“错误”的项目，则应用操作将拒绝继续。警告是建议性的，不会阻止。

推荐工作流程

通过 Markdown 编辑看板时请遵循以下流程：

  • 打开板上的 Markdown 面板
  • 在 结构化块 中编辑 JSON — 添加/修改列或任务
  • 单击试运行以在不更改任何内容的情况下进行验证
  • 修复诊断列表中显示的任何错误
  • 单击 应用 将更改提交到实时面板
  • 使用 Download 保存本地 .md 备份
💡

版本控制提示

由于该文档是纯文本，因此您可以将其粘贴到 Git 存储库中，比较版本，并通过重新应用旧快照来恢复以前的板状态。

Schema v1 · Updated September 2026