@amaster.ai/pi-lark 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -61,7 +61,7 @@
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.11"
+    "@amaster.ai/pi-shared": "0.1.13"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-base/references/lark-base-dashboard-block-config.md

@@ -17,6 +17,7 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档是 Dashboar
 | `funnel` | 漏斗图 |
 | `wordCloud` | 词云 |
 | `radar` | 雷达图 |
+| `ranking` | 排行榜 |
 | `statistics` | 指标卡 |
 | `text` | 文本（支持 Markdown） |
 
@@ -96,6 +97,18 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 
 如果表中行序就是业务顺序，首次创建 block 时就一次性设置 `sort:{"type":"view","order":"asc"}` 保留行序，避免创建后再二次更新排序条件。
 
+### ranking 排行榜专属契约
+
+排行榜只支持一个分组和一个指标，公开字段固定为 `table_name`、`series`/`count_all`、`group_by`、`filter`、`limit_size`：
+
+- `group_by` 必填且长度严格为 1；`mode` 仅支持 `integrated` / `enumerated`。
+- `series` 长度严格为 1，且与 `count_all:true` 二选一；`rollup` 仅支持 `SUM` / `MAX` / `MIN` / `AVERAGE`。
+- 排序只写在 `group_by[0].sort`，`type` 只能为 `value`，`order` 为 `asc` / `desc`。创建时省略排序默认按指标值降序。
+- `limit_size` 是 Top N，取值为 `1..500` 的整数，创建时省略默认 `10`。
+- 不支持顶层 `sort`、公开 `ranking` 对象或头像开关。
+
+更新 `ranking` 时，`data_config` 是顶层 patch：只传 `limit_size` 只改 Top N；只传 `group_by` 只替换唯一分组和排序；只传 `series` 或 `count_all:true` 只切换指标；只传 `filter` 只替换筛选。切换 `table_name` 时必须在同一 patch 提供新的 `group_by` 以及 `series` 或 `count_all:true`；未传 `filter` 保留原筛选，未传 `limit_size` 保留原 Top N。
+
 示例 — 柱状图按销售额降序：
 
 ```json
@@ -225,6 +238,7 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 - 看流程转化 → 漏斗图
 - 看多维度评分 → 雷达图
 - 显示单个指标 → 指标卡（统计数字或记录数）
+- 查看单维度 Top N → 排行榜
 
 最小柱状图：
 
@@ -354,6 +368,23 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 }
 ```
 
+排行榜（按销售额取 Top 10）：
+
+```json
+{
+  "table_name": "订单表",
+  "series": [{ "field_name": "金额", "rollup": "SUM" }],
+  "group_by": [{ "field_name": "负责人", "mode": "integrated", "sort": {"type":"value","order":"desc"} }],
+  "limit_size": 10
+}
+```
+
+排行榜只更新 Top N：
+
+```json
+{"limit_size": 20}
+```
+
 指标卡（统计数字）：
 
 ```json

package/skills/lark-base/references/lark-base-dashboard-block-get-data.md

@@ -6,7 +6,7 @@
 
 这个命令适合以下场景：
 
-1. 读取柱状图 / 条形图 / 折线图 / 饼图 / 环形图 / 面积图 / 组合图 / 散点图 / 漏斗图 / 雷达图 / 词云 / 指标卡的**实际计算结果**；
+1. 读取柱状图 / 条形图 / 折线图 / 饼图 / 环形图 / 面积图 / 组合图 / 散点图 / 漏斗图 / 雷达图 / 排行榜 / 词云 / 指标卡的**实际计算结果**；
 2. 把图表结果交给 AI 做后续总结、趋势解释、同比/环比说明、异常点提取；
 3. 在**不读取原始记录**的前提下，直接消费图表层已经聚合好的结果；
 4. 验证某个图表当前展示的数据是否符合预期。
@@ -26,7 +26,7 @@
 
 当前支持以下图表类型的数据计算与返回：
 
-### 二维图表（10 种）
+### 二维图表（11 种）
 
 - 柱状图
 - 条形图
@@ -38,6 +38,7 @@
 - 散点图
 - 漏斗图
 - 雷达图
+- 排行榜
 
 ### 特殊类型（2 种）
 
@@ -262,7 +263,9 @@ CLI 成功输出使用标准 `{ok, identity, data}` 信封：
 
 ### 一、二维图表
 
-适用于：柱状图、条形图、折线图、饼图、环形图、面积图、组合图、散点图、漏斗图、雷达图。
+适用于：柱状图、条形图、折线图、饼图、环形图、面积图、组合图、散点图、漏斗图、雷达图、排行榜。
+
+排行榜复用同一 `dimensions` / `measures` / `main_data` 协议，不增加专属响应字段。结果的条数和顺序由 block 配置中的 `limit_size` 与 `group_by[0].sort` 决定；消费返回时保持 `main_data` 的服务端顺序，不要再次反转或自行重排。
 
 #### 结构特征
 

package/skills/lark-base/references/lark-base-dashboard.md

@@ -60,7 +60,7 @@ lark-cli base +table-list --base-token xxx
 lark-cli base +field-list --base-token xxx --table-id <table_id>
 
 # 第 3 步：规划应该创建哪些组件（根据用户需求确定组件类型和数量）
-# 例如：总销售额（指标卡）、月度趋势（折线图）、品类占比（饼图）
+# 例如：总销售额（指标卡）、月度趋势（折线图）、负责人 Top N（排行榜）
 
 # 第 4 步：顺序创建每个组件（必须串行执行，不能并发）
 # 重要：创建组件前，先确定 dashboard_id、组件 name/type 和真实表字段
@@ -84,6 +84,14 @@ lark-cli base +dashboard-block-create \
 
 # 继续创建其他组件...
 
+# 排行榜组件：省略 limit_size 和 sort 时分别默认 10、value desc
+lark-cli base +dashboard-block-create \
+  --base-token xxx \
+  --dashboard-id blk_xxx \
+  --name "负责人销售额 Top 10" \
+  --type ranking \
+  --data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}],"group_by":[{"field_name":"负责人"}]}'
+
 # 第 5 步：组件创建完成后，可按需使用 arrange 智能重排（未使用 --position 时可选）
 # 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
 # 若任一组件使用了显式 --position，跳过此步骤；除非用户明确同意放弃精确布局
@@ -152,6 +160,13 @@ lark-cli base +dashboard-block-update \
   --data-config '{...}' \
   --position '{...}'   # 可选，只在需要调整布局时传
 
+# 排行榜只修改 Top N；不会覆盖分组、指标、筛选或排序
+lark-cli base +dashboard-block-update \
+  --base-token xxx \
+  --dashboard-id blk_xxx \
+  --block-id chtxxxxxxxx \
+  --data-config '{"limit_size":20}'
+
 ```
 
 ### 场景 4：重排仪表盘布局
@@ -225,6 +240,7 @@ lark-cli base +dashboard-block-get-data --base-token xxx --block-id chtxxxxxxxx
 | 类别比较（谁高谁低） | column | 柱状图组件 |
 | 占比分布（各部分比例） | pie | 饼图组件 |
 | 单个关键指标 | statistics | 指标卡组件 |
+| 单维度 Top N 排名 | ranking | 排行榜组件，单分组、单指标 |
 | 富文本说明/标题/注释 | text | 文本组件（支持 Markdown） |
 
 详细组件类型和 data_config 完整规则：[Dashboard Block 配置](lark-base-dashboard-block-config.md)

package/skills/lark-doc/references/lark-doc-create-workflow.md

@@ -116,6 +116,6 @@ lark-cli docs +script --command init-draft --presentation-decision '<上方完
 1. 只有最新 release candidate 完成 Draft Profile Check 和 XML 规则复查后，才读取 [`lark-doc-create.md`](lark-doc-create.md)，使用同一个 `draft_path` 创建文档。
 2. 创建结果存在 warning、局部资源失败或回查发现局部问题时，不得再次新建文档；读取 [`lark-doc-update.md`](lark-doc-update.md)，对已创建文档做最小范围修复，并按 update 流程 fetch 验证。
 
-### Step 8：清理并交付。
+### Step 8：交付。
 
-无论创建成功、失败或被阻塞，只要 Step 4 已返回 `work_dir`，就先离开该目录，再使用当前运行时的文件删除能力精确删除整个 `work_dir`；不要使用通配符，也不要删除目录外的用户原始文件。最终只交付用户需要的结果，并说明必要来源、未关闭缺口、异常、失败或阻塞原因，以及文档 URL 或 token。
+保留 Step 4 返回的 `work_dir` 及其中的创作草稿。最终只交付用户需要的结果，并说明必要来源、未关闭缺口、异常、失败或阻塞原因，以及文档 URL 或 token。

package/skills/lark-doc/references/lark-doc-script.md

@@ -38,7 +38,7 @@ lark-cli docs +script --command init-draft \
 - 决策必须是单个 JSON 对象，包含 `audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode` 和 `visual_plan`。`presentation_mode` 取 `formal|normal|rich`；`genre_contract`、`adapter` 使用固定短名、`"none"` 或 `null`。
 - `visual_plan` 包含非空 `reason` 和 `blocks` 数组；每项为 `{type,min_count,purpose}`，`type` 不重复，`min_count` 为正整数。按本 Skill 创建文档时，`blocks` 只对 `whiteboard`、`img`、`html5-block` 设置最低数量，其他表达按内容需要使用但不设数量约束；三类均无需约束时写 `[]`。CLI 为外部决策兼容 `type: "list"`，检查时将 `<ul>` 与 `<ol>` 的数量相加。仅有字数要求时添加 `word_count: {min,max}`；未指定的一侧写 `null`，至少一侧为正整数，且 `min <= max`。
 - 返回 `data.workspace`（已创建的随机工作区）、`data.draft_path`（可直接写入的 XML 路径）和英文操作提示 `data.tip`。工作区及其中的 `.presentation-decision.json` 已存在，但 XML 尚不存在；遵循提示直接使用文件创建/写入能力在 `draft_path` 写入完整 XML，首次写入前不要读取该路径。
-- 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；使用完后精确删除 `workspace`。
+- 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；保留 `workspace` 及其中的创作草稿。
 
 ## `parse`