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

12 KiB

Raw Blame History

Lark Sheet Pivot Table

真对象硬约束

当用户要求"透视表 / 分组汇总 / 交叉分析 / 按 X 统计 Y"时，必须通过 +pivot-{create|update|delete} 创建真实的透视表对象。禁止用 SUMIFS / COUNTIFS 等普通公式 + +cells-set 在原表中拼一张"看起来像透视表的汇总表"来代替。判断标准：交付后 +pivot-list 必须能返回该对象。

使用场景

读写透视表对象。本 reference 覆盖 4 个 shortcut：

操作需求	使用工具	说明
查看已有透视表	`+pivot-list`	获取透视表的结构、数据源和配置
创建/更新/删除透视表	`+pivot-{create	update

典型工作流：先读取现有透视表了解配置 → 执行创建/更新/删除 → 必须再次读取验证结果。

行/值字段映射（创建前必做）

创建透视表前先识别用户需求中的分组维度和聚合指标，不要搞反：

rows（行字段） = 分组维度，即"按什么分组"。例：部门、地区、医生、产品类别
values（值字段） = 聚合指标，即"统计什么数值"。例：销售额（聚合方式 sum）、订单数（聚合方式 count）
columns（列字段） = 交叉维度（可选），即"再按什么横向展开"。例：月份、性别

用户说	rows	values	columns
"按部门统计人数"	部门	姓名（`summarize_by: "count"`）	—
"按医生统计费用和结余"	主管医生	费用（`"sum"`）、结余（`"sum"`）	—
"各部门男女人数"	部门	姓名（`"count"`）	性别

常见配置错误（必须注意）：

数据源范围必须精确：透视表的数据源范围必须包含表头行，且精确覆盖全部数据行列。范围过大（包含空行/空列）或过小（遗漏数据列）都会导致透视表结果错误
行列字段选择要匹配用户意图：用户说"按商品统计金额"→ 行字段=商品，值字段=金额（summarize_by: "sum"）。不要把行列字段搞反
聚合类型要匹配：用户说"统计数量"→ summarize_by: "count"；"统计总额"→ "sum"；"统计平均"→ "average"。完整合法值：sum / count / average / max / min / product / countNums / stdDev / stdDevp / var / varp / distinct / median。默认不要用 count 替代 sum
参数长度限制：如果透视表配置 JSON 过长（数据源范围跨越大量行列），可能导致工具调用失败。此时应先确认数据范围的精确边界，避免传入过大的 range
创建后必须验证：调用 +pivot-list 确认透视表结构正确

Shortcuts

Shortcut	Risk	分组
`+pivot-list`	read	对象
`+pivot-create`	write	对象
`+pivot-update`	write	对象
`+pivot-delete`	high-risk-write	对象

Flags

`+pivot-list`

公共四件套 · 系统：--dry-run

Flag	Type	必填	说明
`--pivot-table-id`	string	optional	按 id 过滤

`+pivot-create`

公共：URL/token（无 sheet 定位） · 系统：--dry-run

Flag	Type	必填	说明
`--properties`	string + File + Stdin（复合 JSON）	required	JSON：{"rows":[...],"columns":[...],"values":[...],"filters":[...],"show_row_grand_total":true,"show_col_grand_total":true}（数据源走 --source，不要再放进 properties.source）
`--target-position`	string	optional	透视表落点子表内的起始 cell（A1 格式，如 `A1`），映射到顶层 `target_position`，默认 `A1`（值为 A1 时不下发）。它与 `--range` 都表达落点但落在不同 wire 字段，避免两者同时给冲突值
`--target-sheet-id`	string	xor	透视表落点目标子表的 reference_id（与 `--target-sheet-name` 互斥，优先于 --target-sheet-name；都不传时自动新建一张子表放置透视表——推荐）。与数据源 sheet 区分：数据源 sheet 写在 --source 的 A1 引用里（带 sheet 前缀，形如 `'Sheet1'!A1:D100`）。
`--target-sheet-name`	string	xor	透视表落点目标子表的名称（与 `--target-sheet-id` 互斥；都不传时自动新建一张子表放置透视表——推荐）。与数据源 sheet 区分：数据源 sheet 写在 --source 的 A1 引用里（带 sheet 前缀，形如 `'Sheet1'!A1:D100`）。
`--source`	string	required	透视表源数据区域（A1 表示法，格式 `'SheetName'!StartCell:EndCell`，如 `'Sheet1'!A1:D100`）
`--range`	string	optional	透视表左上角放置位置（A1 单值，如 `F1`，仅 create 生效），映射到 `properties.range`；省略时放在落点子表（默认新建子表）的左上角。它与 `--target-position` 都表达落点但落在不同 wire 字段，避免两者同时给冲突值

`+pivot-update`

公共四件套 · 系统：--dry-run

Flag	Type	必填	说明
`--pivot-table-id`	string	required	目标透视表 id
`--properties`	string + File + Stdin（复合 JSON）	required	完整或足够完整的配置（先 `+pivot-list --pivot-table-id <id>` 回读再 patch）

`+pivot-delete`

公共四件套 · 系统：--yes、--dry-run

Flag	Type	必填	说明
`--pivot-table-id`	string	required	目标透视表 id

Schemas

复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方 ## Examples，或用 --print-schema 读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。

`+pivot-create` `--properties` / `+pivot-update` `--properties`

创建/更新的透视表属性

顶层字段：

range (string?) — 放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效） — ⚠️ 已拎为独立 flag --range，请勿在此 JSON 内重复填写（同名以独立 flag 为准）
source (string?) — 源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'） — ⚠️ 已拎为独立 flag --source，请勿在此 JSON 内重复填写（同名以独立 flag 为准）
rows (array

12 KiB Raw Blame History Unescape Escape