ooodc a7883dbed9 refactor(todo): 重构待办事项管理逻辑及更新状态规则

- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段
- 强制每个任务都必须有唯一 id，且由用户负责生成
- 修改合并模式逻辑，merge=true 下保留未提及的旧任务
- 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress）
- 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled
- 优化状态转换校验，允许特定状态间合法切换
- 简化任务变更消息，移除详细的新增/更新/移除统计
- 更新文档和示例，明确 id 必须由用户生成和使用
- 修复和补充测试，增强状态转换和合并模式验证
- 调整任务时间戳生成逻辑，统一使用当前时间及索引
- 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性

2026-06-13 09:22:33 +08:00

23 KiB

Raw Blame History

base +dashboard-block-get-data

前置条件： 先阅读 lark-base-dashboard.md 了解 dashboard 整体工作流。

获取仪表盘图表组件（block）的最终计算结果，返回一份适合 AI 直接消费的图表协议 JSON。

这个命令适合以下场景：

读取柱状图 / 条形图 / 折线图 / 饼图 / 环形图 / 面积图 / 组合图 / 散点图 / 漏斗图 / 雷达图 / 词云 / 指标卡的实际计算结果；
把图表结果交给 AI 做后续总结、趋势解释、同比/环比说明、异常点提取；
在不读取原始记录的前提下，直接消费图表层已经聚合好的结果；
验证某个图表当前展示的数据是否符合预期。

Important

本命令返回的是图表结果协议，不是 block 元数据；

如果你需要 name、type、layout、data_config 等配置，请先用 +dashboard-block-get；

文本组件（text）不涉及计算，不适用本命令；

一句话理解

+dashboard-block-get-data = 拿图表“算出来的结果”，而不是拿图表“怎么配置的”。

支持的图表类型

当前支持以下图表类型的数据计算与返回：

二维图表（10 种）

柱状图
条形图
折线图
饼图
环形图
面积图
组合图
散点图
漏斗图
雷达图

特殊类型（2 种）

词云
指标卡（statistics）

Caution

文本组件虽然也属于 dashboard block，但它不产生可计算数据，因此不会返回本协议。

参数

参数	必填	说明
`--base-token <token>`	是	Base Token，标识目标多维表格
`--block-id <id>`	是	图表 Block ID，即目标组件的唯一标识
`--format <fmt>`	否	输出格式，遵循 CLI 全局输出格式规则
`--dry-run`	否	只预览 API 调用，不真正执行

Tip

这个命令不需要 --dashboard-id。只要 base_token + block_id 即可定位并读取图表结果。

返回结构总览

服务端响应外层仍然是标准 OpenAPI 包装：

{
  "code": 0,
  "msg": "success",
  "data": {
    "dimensions": [...],
    "measures": [...],
    "main_data": [...]
  }
}

其中 data 就是 CLI 图表协议本体。不同图表类型的 data 结构略有不同：

图表类型	一定有	可能有
二维图表	`dimensions` / `measures` / `main_data`	无
词云	`dimensions` / `measures` / `main_data`	无
指标卡	`dimensions` / `measures` / `main_data`	`comparison_data` / `trend_data`

协议字段说明

1) `dimensions`

维度定义数组，告诉你主结果里每个 dim_* key 代表什么字段。

[
  {
    "field_name": "文本",
    "alias": "dim_5bKp"
  }
]

字段含义：

字段	说明
`field_name`	维度字段显示名称
`alias`	维度别名，在 `main_data` / `trend_data` 中作为 key 使用

2) `measures`

指标定义数组，告诉你每个 me_* key 代表什么聚合指标。

[
  {
    "field_name": "Count",
    "aggregation": "count_all",
    "alias": "me_Y291bnRfYWxsX0NvdW50"
  }
]

字段含义：

字段	说明
`field_name`	统计该指标时所使用的字段名称；当 `aggregation = count_all` 时固定为 `Count`，表示统计记录总数
`aggregation`	聚合方式，常见值：`count_all` / `count` / `sum` / `avg` / `min` / `max`
`alias`	指标别名，在 `main_data` / `comparison_data` / `trend_data` 中作为 key 使用

例如：

如果统计“销售额”的求和，则 field_name = 销售额、aggregation = sum
如果统计记录总数，则 field_name = Count、aggregation = count_all

3) `main_data`

主结果集。每一行都是一个对象，key 不是字段名本身，而是 dimensions / measures 中声明过的 alias。

[
  {
    "dim_5bKp": {"value": "A"},
    "me_Y291bnRfYWxsX0NvdW50": {"value": 3}
  }
]

4) `comparison_data`

仅指标卡可能返回。表示同/环比的两个值，顺序固定为：

当前周期值
对比周期值

Note

原始协议里通常不直接展示周期名称，只提供对应的值。因此解释“同比”还是“环比”、以及比较窗口具体是什么，通常要结合组件配置或 UI 上下文理解。

5) `trend_data`

仅指标卡可能返回。表示时间序列趋势，每一行通常包含一个时间维度和一个指标值。

alias 规则与读取方式

你不应该把 alias 当成人类可读字段名，而应把它视为结果表里的列 ID。

常见生成规则：

维度 alias：dim_ + base64(field_name)
指标 alias：me_ + base64(aggregation + "_" + field_name)

Note

为了便于阅读，本文档中的部分示例会使用简化后的 alias（例如 dim_xxx、me_xxx 或较短的示例值），不保证和真实返回值逐字符一致。在实际读取结果时，应始终以 dimensions / measures 中声明的 alias 为准，而不要假设所有示例都严格展开成完整编码值。

例如：

{
  "dimensions": [
    {"field_name": "文本", "alias": "dim_5bKp"}
  ],
  "measures": [
    {"field_name": "Count", "aggregation": "count_all", "alias": "me_xxx"}
  ],
  "main_data": [
    {
      "dim_5bKp": {"value": "A"},
      "me_xxx": {"value": 3}
    }
  ]
}

应解读为：

dim_5bKp 对应字段“文本”，取值是 A
me_xxx 对应指标 count_all(Count)，取值是 3

Tip

读取结果时，先看 dimensions / measures，再解 main_data。不要仅凭 alias 名字猜含义。

各图表类型的协议细节

一、二维图表

适用于：柱状图、条形图、折线图、饼图、环形图、面积图、组合图、散点图、漏斗图、雷达图。

结构特征

dimensions：通常有 1~2 个维度
- 不分组聚合时：通常 1 个维度
- 开启分组聚合时：通常 2 个维度
measures：指标定义数组
main_data：按“维度组合”展开后的行数据

这类数据代表什么

二维图表返回的本质上是一张聚合结果表：

每一行代表一个维度值，或一组维度组合；
每一个 measure 值代表该维度下算出来的指标结果；
如果图表开启了分组聚合，那么每一行表示“主维度 + 分组维度”的一个组合结果；
如果图表是折线图、面积图这类带时间轴的图，通常可以把第一维理解为横轴、把 measure 理解为纵轴数值；
如果图表是饼图、环形图这类占比图，通常可以把每一行理解为一个扇区对应的分类及其数值。

换句话说，AI 在读取这类结果时，可以把它当作“按某些维度聚合后的统计明细表”，适合进一步做排序、Top N、占比解释、分组对比和趋势总结。

示例 1：普通二维图表（无分组聚合）

{
  "dimensions": [
    {
      "field_name": "文本",
      "alias": "dim_5bKp"
    }
  ],
  "measures": [
    {
      "aggregation": "count_all",
      "field_name": "Count",
      "alias": "me_Y291bnRfYWxsX0NvdW50"
    }
  ],
  "main_data": [
    {
      "dim_5bKp": {"value": "A"},
      "me_Y291bnRfYWxsX0NvdW50": {"value": 3}
    },
    {
      "dim_5bKp": {"value": "B"},
      "me_Y291bnRfYWxsX0NvdW50": {"value": 2}
    },
    {
      "dim_5bKp": {"value": "C"},
      "me_Y291bnRfYWxsX0NvdW50": {"value": 2}
    }
  ]
}

可解读为：

维度字段是“文本”
指标是“按记录总数统计”
当“文本”字段为 A 时，对应的 Count 指标值是 3
当“文本”字段为 B 时，对应的 Count 指标值是 2
当“文本”字段为 C 时，对应的 Count 指标值是 2

示例 2：二维图表（开启分组聚合）

{
  "dimensions": [
    {
      "field_name": "文本",
      "alias": "dim_5bKp"
    },
    {
      "field_name": "单选",
      "alias": "dim_5aSl"
    }
  ],
  "measures": [
    {
      "aggregation": "count_all",
      "field_name": "Count",
      "alias": "me_YW91bnR"
    }
  ],
  "main_data": [
    {
      "dim_5bKp": {"value": "A"},
      "dim_5aSl": {"value": "a-1"},
      "me_YW91bnR": {"value": 2}
    },
    {
      "dim_5bKp": {"value": "A"},
      "dim_5aSl": {"value": "a-2"},
      "me_YW91bnR": {"value": 1}
    },
    {
      "dim_5bKp": {"value": "B"},
      "dim_5aSl": {"value": "b-1"},
      "me_YW91bnR": {"value": 1}
    },
    {
      "dim_5bKp": {"value": "C"},
      "dim_5aSl": {"value": "c-1"},
      "me_YW91bnR": {"value": 2}
    }
  ]
}

可解读为：

第一维是“文本”，第二维是“单选”，指标是“按记录总数统计”
当“文本”字段为 A、且“单选”字段为 a-1 时，对应的指标值是 2
当“文本”字段为 A、且“单选”字段为 a-2 时，对应的指标值是 1
当“文本”字段为 B、且“单选”字段为 b-1 时，对应的指标值是 1
当“文本”字段为 C、且“单选”字段为 c-1 时，对应的指标值是 2
如果按“文本”字段汇总，那么“文本”字段为 A 时总指标值是 3；为 B 时总指标值是 1；为 C 时总指标值是 2

二、词云

结构特征

词云协议仍然沿用 dimensions + measures + main_data 的结构，但语义稍有不同：

dimensions 对应被分词的字段；
main_data 每一行代表一个词；
measure 的 value 表示按该词分组后计算出来的统计值。

这类数据代表什么

词云返回的不是“原文列表”，而是按词分组后的聚合统计结果：

dimensions 定义的是被分词的来源字段；
measure 对应的是该词在当前图表统计范围内对应的统计值，具体含义取决于聚合方式和指标字段；
main_data 的每一行都可以理解成“某个词 + 该词对应的统计结果”，其中该维度的具体 value 就是拆分出来的词；
返回结果通常已经结合图表当前过滤条件、时间范围、数据权限等上下文计算完成。

因此，AI 读取词云数据时，更适合做“关键词排序”“热点词解释”“按词聚合结果分析”“主题归纳”，而不是把它当成逐条文本记录去理解。

示例

{
  "dimensions": [
    {
      "field_name": "文本",
      "alias": "dim_5bKp"
    }
  ],
  "measures": [
    {
      "aggregation": "count_all",
      "field_name": "Count",
      "alias": "me_YW91bnR"
    }
  ],
  "main_data": [
    {
      "dim_5bKp": {"value": "A"},
      "me_YW91bnR": {"value": 3}
    },
    {
      "dim_5bKp": {"value": "B"},
      "me_YW91bnR": {"value": 2}
    },
    {
      "dim_5bKp": {"value": "C"},
      "me_YW91bnR": {"value": 2}
    }
  ]
}

可解读为：

被统计的分词字段是“文本”
当前示例里的 measure 是 count_all(Count)，所以这里的统计值可以理解为“按词分组后的记录总数”
当分词结果为 A 时，对应的统计值是 3
当分词结果为 B 时，对应的统计值是 2
当分词结果为 C 时，对应的统计值是 2
按统计值排序，分词结果 A 对应的值最高
分词结果 B 和 C 的统计值相同，说明它们处于同一梯队

三、指标卡（statistics）

指标卡除了主值外，还可能包含同/环比与趋势结果，是本命令里结构最特殊的一类。

结构特征

measures：有且仅有一个指标
main_data：通常只有一行，表示总指标值
comparison_data：可选，表示当前周期值与对比周期值
trend_data：可选，表示趋势序列
dimensions：可能包含同/环比日期字段、趋势日期字段

这类数据代表什么

指标卡返回的核心是一个主指标摘要，外加可选的比较信息和趋势信息：

main_data 表示当前卡片最核心、最醒目的那个主值；它通常是某个表的记录总数，或某个字段的聚合值，本身不带时间周期概念；
comparison_data 表示用于同/环比展示的两个数值，通常是“当前周期值”和“对比周期值”；它们表示某个时间周期下的记录总数，或某个字段的聚合值；
trend_data 表示这个指标在一段时间内的变化轨迹，用来支持走势判断；
dimensions 在指标卡里通常不是拿来做主分组展示，而是给 trend_data 或同/环比相关日期字段提供语义说明。

例如：

main_data = 7 可以理解为当前卡片展示的主数据，比如某张表当前总记录数是 7；
comparison_data[0] = 6 则表示某个比较周期下的当前值，比如“本月记录总数 = 6”；
因此，main_data 与 comparison_data[0] 不一定相等，因为两者表达的口径并不完全相同。

因此，AI 在解读指标卡时，应该优先回答这几个问题：

当前主值是多少；
和对比周期相比是上升、下降还是持平；
趋势整体是增长、波动还是下滑；
是否存在明显的异常峰值或低谷。

Note

当指标卡同时指定同/环比和趋势时，dimensions 中日期维度的顺序是固定的：

第一个元素是趋势对应的日期维度；

第二个元素是同/环比对应的日期维度。

另外要注意：comparison_data 自身通常不直接携带日期字段，它只给出“当前周期值 / 对比周期值”。 dimensions 中的第一个日期维度会直接出现在 trend_data 中，作为趋势序列的时间列；第二个日期维度则主要用于补充“该卡片配置了哪类比较相关日期字段”的语义。

示例

{
  "dimensions": [
    {
      "field_name": "日期",
      "alias": "dim_ZGF0ZQ"
    },
    {
      "field_name": "日期2",
      "alias": "dim_ZGF0ZTI"
    }
  ],
  "measures": [
    {
      "aggregation": "count_all",
      "field_name": "Count",
      "alias": "me_YW91b"
    }
  ],
  "main_data": [
    {
      "me_YW91b": {"value": 7}
    }
  ],
  "comparison_data": [
    {
      "me_YW91b": {"value": 6}
    },
    {
      "me_YW91b": {"value": 0}
    }
  ],
  "trend_data": [
    {
      "dim_ZGF0ZQ": {"value": "2026-01-15"},
      "me_YW91b": {"value": 1}
    },
    {
      "dim_ZGF0ZQ": {"value": "2026-01-17"},
      "me_YW91b": {"value": 1}
    },
    {
      "dim_ZGF0ZQ": {"value": "2026-03-22"},
      "me_YW91b": {"value": 1}
    },
    {
      "dim_ZGF0ZQ": {"value": "2026-04-24"},
      "me_YW91b": {"value": 2}
    },
    {
      "dim_ZGF0ZQ": {"value": "2026-05-01"},
      "me_YW91b": {"value": 1}
    }
  ]
}

可解读为：

当前主指标值 = 7
当前主指标值不带时间周期概念，可理解为当前卡片主数据
comparison_data[0] = 当前周期值 6，例如某个时间周期（如本月）下的统计值
comparison_data[1] = 对比周期值 0
dimensions[0] 对应趋势日期维度，因此实际出现在 trend_data 里
dimensions[1] 对应同/环比相关的日期维度，用来补充比较语义
trend_data 展示该指标随时间的变化序列
从 comparison_data 看，当前周期相较对比周期是上升的，并且对比周期值为 0
从 trend_data 看，这个指标并不是每天都有值，而是在若干离散日期出现
趋势序列里的最高点出现在 2026-04-24，值为 2
其余出现的日期大多为 1，说明整体上有波动，但暂时没有持续快速增长的趋势

Note

comparison_data 只告诉你“当前值 / 对比值”，不额外标出日期区间文本。如果用户需要完整说明“和上周比”还是“和上月比”，通常要结合组件配置或界面上下文进一步判断。

如何正确解读返回值

建议按下面顺序阅读：

先看 dimensions：确认每个 dim_* alias 对应哪个字段；
再看 measures：确认每个 me_* alias 是什么聚合方式；
最后读 main_data / comparison_data / trend_data：把 alias 还原成“字段名 + 指标名”再做解释。

常见工作流

场景 1：用户要“拿这个图表当前展示的数据”

# 如果已知 block_id，直接读结果
lark-cli base +dashboard-block-get-data \
  --base-token xxx \
  --block-id chtxxxxxxxx

场景 2：用户说“帮我分析这个图表”，但你还不知道它是什么组件

# 先看组件配置，确认它是不是支持计算的图表类型
lark-cli base +dashboard-block-get \
  --base-token xxx \
  --dashboard-id blk_xxx \
  --block-id chtxxxxxxxx

# 再读最终计算结果
lark-cli base +dashboard-block-get-data \
  --base-token xxx \
  --block-id chtxxxxxxxx

场景 3：用户要找“仪表盘里哪个图的结果异常”

# 先列组件
lark-cli base +dashboard-block-list \
  --base-token xxx \
  --dashboard-id blk_xxx

# 再针对可疑 block 逐个取结果
lark-cli base +dashboard-block-get-data \
  --base-token xxx \
  --block-id chtxxxxxxxx

何时优先用这个命令

用户说“帮我拿这个图表算出来的数据 / 结果 / 指标”
用户已经知道 block_id，目标是读取结果而不是看配置
用户后续还要让 AI 对图表结果做解释、归纳、比较、总结
你只关心图表层的聚合产出，不需要回到底表逐条读记录

何时不要误用

想看 block 的 data_config、名称、类型、布局 → 用 +dashboard-block-get
想列出仪表盘里有哪些组件 → 用 +dashboard-block-list
想修改或新建组件 → 用 +dashboard-block-update / +dashboard-block-create
想看原始记录明细，而不是图表聚合结果 → 回到 record-*
目标是文本组件 → 本命令不适用

常见误区

误区 1：把这个命令当成“获取 block 详情”

不是。这个命令不返回：

block 名称
block 类型
layout
data_config
所属 dashboard 信息

这些都应该通过 +dashboard-block-get 获取。

误区 2：以为它返回的是原始记录

不是。它返回的是图表聚合后的最终结果。如果图表本身做了过滤、分组、聚合、时间窗口限制，返回值反映的是图表视角，不是原始表全量明细。

误区 3：直接把 alias 当真实字段名读

不应该。alias 只是协议里的键，必须结合 dimensions / measures 还原语义。

误区 4：看到指标卡的 `comparison_data` 就以为已经知道“同比/环比周期文本”

不一定。它只给出比较值，不一定给出周期标签。若要精确解释比较窗口，通常还需要组件配置或 UI 上下文。

dry-run 用途

可用来确认最终会调用的接口路径：

lark-cli base +dashboard-block-get-data \
  --base-token bascn_example_token \
  --block-id chtxxxxxxxx \
  --dry-run \
  --format pretty

你应能看到类似：

GET /open-apis/base/v3/bases/bascn_example_token/dashboards/blocks/chtxxxxxxxx/data

适合在以下场景使用：

校验 base_token / block_id 是否传对；
调试 agent 生成的命令；
编写自动化测试时确认请求结构。

参考

lark-base-dashboard.md — dashboard 模块总指引
+dashboard-block-get — 获取 block 元数据
dashboard-block-data-config.md — data_config 结构和组件类型说明

23 KiB Raw Blame History Unescape Escape

base +dashboard-block-get-data

一句话理解

支持的图表类型

二维图表（10 种）

特殊类型（2 种）

推荐命令

参数

返回结构总览

协议字段说明

1) dimensions

2) measures

3) main_data

4) comparison_data

5) trend_data

alias 规则与读取方式

各图表类型的协议细节

一、二维图表

结构特征

这类数据代表什么

示例 1：普通二维图表（无分组聚合）

示例 2：二维图表（开启分组聚合）

二、词云

结构特征

这类数据代表什么

示例

三、指标卡（statistics）

结构特征

这类数据代表什么

示例

如何正确解读返回值

推荐解释模板

常见工作流

场景 1：用户要“拿这个图表当前展示的数据”

场景 2：用户说“帮我分析这个图表”，但你还不知道它是什么组件

场景 3：用户要找“仪表盘里哪个图的结果异常”

何时优先用这个命令

何时不要误用

常见误区

误区 1：把这个命令当成“获取 block 详情”

误区 2：以为它返回的是原始记录

误区 3：直接把 alias 当真实字段名读

误区 4：看到指标卡的 comparison_data 就以为已经知道“同比/环比周期文本”

dry-run 用途

参考

23 KiB

Raw Blame History

1) `dimensions`

2) `measures`

3) `main_data`

4) `comparison_data`

5) `trend_data`

误区 4：看到指标卡的 `comparison_data` 就以为已经知道“同比/环比周期文本”