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

6.9 KiB

Raw Blame History

base +field-update

前置条件： 先阅读 ../lark-shared/SKILL.md 了解认证、全局参数和安全规则。

更新一个已有字段。

参数

参数	必填	说明
`--base-token <token>`	是	Base Token
`--table-id <id_or_name>`	是	表 ID 或表名
`--field-id <id_or_name>`	是	字段 ID 或字段名
`--json <body>`	是	字段属性 JSON 对象
`--yes`	是	确认执行高风险字段更新

这是高风险写入操作。+field-update 使用 PUT 全量字段定义语义；改变字段类型或关键配置可能影响整列已有数据的解释、展示或可用性。CLI 层要求显式传 --yes；如果用户已经明确目标和期望更新，可直接执行并带上 --yes。

API 入参详情

HTTP 方法和路径：

PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id

JSON 值规范

--json 必须是 JSON 对象，顶层直接传字段定义。
更新语义是 PUT（全量字段配置更新），不要只传零散片段；至少显式包含 name、type，并补齐该类型所需关键配置。
所有字段类型都支持可选 description；支持纯文本，也支持 Markdown 链接。
select 更新时：options 仍按对象数组传，避免混入无效字段。
link 更新限制：
- 不能把非 link 字段改成 link，也不能把 link 改成非 link。
- 现有 link 字段的 bidirectional 不能改。

推荐更新示例

{
  "name": "状态",
  "type": "select",
  "multiple": false,
  "options": [
    { "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
    { "name": "Doing", "hue": "Orange", "lightness": "Light" },
    { "name": "Done", "hue": "Green", "lightness": "Light" }
  ]
}

字段说明示例

{
  "name": "负责人",
  "type": "user",
  "multiple": false,
  "description": "用于标记记录的直接负责人"
}

返回重点

返回 field 和 updated: true。

工作流

建议先用 +field-get 拉现状，再做最小化修改。
formula/lookup 类型更新前先阅读对应指南。
如果这次更新会改变字段 type 先按下方“字段类型变更规则”判断能否执行。如果不修改 type，大多数场景都相对安全。

字段类型变更规则

字段类型变更采用白名单机制：只允许白名单转换；未命中白名单时，不建议用 CLI 转换字段类型 除非用户明确知道风险并同意。

允许直接转换 type

先 +field-get / +field-list 看结构，再抽样读值；只有命中以下规则时，转换才是比较安全的。

相对安全

目标类型	允许的源类型	说明
`text`	`number`、`select`、`datetime`、`created_at`、`updated_at`、`location`（只保留 `full_address`）、`auto_number`、`checkbox`	保留字符串表示；丢失原类型语义和结构化能力
`number`	`text`、`number`、`datetime`、`created_at`、`updated_at`、`checkbox`	保留可解析的数字值；无法解析的值会变空，原文本格式会丢失
`datetime`	`text`、`number`、`datetime`、`created_at`、`updated_at`	保留可解析的时间字符串和时间戳；无法解析的值会变空，原文本格式会丢失
`select`	`text -> select`、`number -> select`、`single select -> multi select`	只有完全匹配目标选项名的值会转成对应选项；没匹配上的值会被丢弃

可执行但会截断 / 重算

select(multi) -> select(single): 只保留第一个值，其余值会被丢弃。
user(multi) -> user(single): 只保留第一个人员，其余值会被丢弃。
group_chat(multi) -> group_chat(single): 只保留第一个群，其余值会被丢弃。

无状态字段可直接转换

created_at、created_by、updated_at、updated_by、formula、lookup: 这类字段值由系统或计算逻辑生成，不承载独立存储数据；可以执行类型转换，不必担心破坏原始记录值，但仍要做下游读回验证。

一律不要用 CLI 转换

以下场景全部视为黑名单；默认要求用户改到 Web 页面手动完成，或改走“新建字段 + 数据迁移”。

any -> checkbox
any -> user
any -> group_chat
any -> attachment
any -> location
link 类型变更
任意涉及动态 / 静态选项来源切换的 select 类型变更

可例外继续执行的场景

只有在整列数据丢失可接受时，才允许对黑名单场景例外执行。

EmptyColumn: 该列为空
FreshTableInit: 新建空表初始化
PrimaryFieldBootstrap: 主列不能删，只能更新完成初始化
ExplicitLossAccepted: 用户明确接受整列数据丢失

不满足以上条件时，不要转换。

非白名单场景如何处理

命中白名单时：建议直接原地转换，再做读回验证。
未命中白名单时：先询问用户是否仍要执行转换，并明确说明风险：
- 无状态字段除外；这类字段可以直接转换
- 可能整列变空
- 可能只保留第一个值
- 可能只保留字符串表示，丢失原类型语义和结构化能力
- 可能影响视图 / 筛选 / 排序 / 公式 / lookup / 写入引用
如果用户不接受风险：不要执行转换。

完成态验证

FieldReadback: 读回字段结构，确认 type / multiple / style / options
ValueReadback: 抽样读回转换后的单元格值
DownstreamReadback: 若涉及看板 / 分组 / 排序 / lookup / 公式，继续读回结果
CompletionRule: 结构、值、下游能力都正确，才能回复“已完成”

坑点

⚠️ 这是全量字段属性更新语义，不是 patch。
⚠️ 这是高风险写入操作，执行时必须带 --yes。
⚠️ 当 type 是 formula 或 lookup 时，先阅读对应指南再执行。

参考

更新前读取当前字段，确认现有 type 和具体配置细节，再决定是原地更新还是新建字段迁移。
lark-base-field-json.md — 字段 JSON 规范（推荐）
formula-field-guide.md — formula 指南（更新公式前必读）
lookup-field-guide.md — lookup 指南（更新查找引用前必读）

6.9 KiB Raw Blame History Unescape Escape