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

4.3 KiB

Raw Blame History

图片准备 (Image Preparation)

本文件说明如何在画板 DSL 中使用图片节点。进入任何含图片的场景前，必须先完成图片准备流程。

概述

画板 DSL 支持 type: 'image' 节点，但图片不能直接使用 URL 或其他域的 token，必须先上传到目标画板获取 whiteboard 域 media token，然后在 DSL 中引用。

核心规则：不管图片从哪来（本地文件、URL、文档中的 docx_image token、其他域的 Drive token），都必须通过 docs +media-upload --parent-type whiteboard --parent-node <目标画板token> 上传，拿到画板专属的 media token 后才能在 DSL 中使用。直接使用非 whiteboard 域的 token 会导致画板 API 报 500（错误码 2891001）或图片在文档中消失。

Step 0：图片准备流程

1. 获取图片到本地

根据图片来源选择对应方式：

图片来源	获取方式
本地文件	直接使用
网络 URL	`curl -L -o photo.jpg "<URL>"`
文档中的图片 token	`lark-cli docs +media-download --token <token> --output ./photo.png`
其他域的 Drive token	`lark-cli docs +media-download --token <token> --output ./photo.png`

图片源选择（需要搜索图片时）：

图片源类型	说明
免费版权图库	支持按关键词搜索，图片无版权风险（CC0 或类似协议），图库种类丰富（人物/动物/风景/美食/建筑等），关键词能精准匹配图片内容
直接 URL	用户提供或已知的图片链接，最可靠

选择图库的必要条件：

版权合规：图片必须无版权纠纷风险，避免使用需要付费授权或有使用限制的图库
关键词搜索：支持按关键词搜索并返回相关图片，确保图片内容与主题匹配
内容丰富：图库图片种类多、数量大，能覆盖常见主题（宠物、美食、景点、产品等）

严禁使用随机占位图服务：某些图库仅提供随机占位图，URL 中的关键词参数不会影响返回的图片内容，下载的图片与主题完全无关。

2. 校验图片

ls -l *.jpg   # 确认每张文件大小不同；若大小相同则内容可能重复，需重新下载

图片内容审查（必须执行）：

下载完成后，确认文件是真实图片而非 HTML 错误页：若某张图片大小 < 1KB，很可能是下载失败返回了 HTML 错误页，需重新下载
图片内容正确性只能在渲染后验证：生成 DSL 并本地渲染 PNG 后，必须查看渲染结果，确认每张图片内容与主题相关（如宠物主题的图片确实是宠物，而非建筑/风景等不相关内容）
若发现图片内容与主题不符，必须用更精确的关键词重新下载并重新上传

3. 上传到目标画板

必须使用 docs +media-upload --parent-type whiteboard 上传：

lark-cli docs +media-upload --file ./photo1.jpg --parent-type whiteboard --parent-node <whiteboard_token>
# 响应: { "file_token": "<media_token>", ... }

逐张上传，收集每个 media token：

lark-cli docs +media-upload --file ./photo1.jpg --parent-type whiteboard --parent-node <whiteboard_token>  # → <media_token_1>
lark-cli docs +media-upload --file ./photo2.jpg --parent-type whiteboard --parent-node <whiteboard_token>  # → <media_token_2>
lark-cli docs +media-upload --file ./photo3.jpg --parent-type whiteboard --parent-node <whiteboard_token>  # → <media_token_3>

4. 在 DSL 中引用

{ "type": "image", "id": "img-1", "width": 240, "height": 160, "image": { "src": "<media_token_1>" } }

常见错误

错误现象	原因	解决
画板 API 返回 500（2891001）	使用了非 `whiteboard` 域 token（如 `docx_image`、Drive file token）	下载图片后用 `docs +media-upload --parent-type whiteboard` 重新上传
画板 API 返回 500	图片上传到了其他画板	重新上传到目标画板
画板在文档中图片消失	图片 token 的资源域与画板不匹配	确保图片通过 `--parent-type whiteboard --parent-node <画板token>` 上传
图片裂开/无法显示	token 无效或已过期	重新上传获取新 token
图片内容与主题无关	使用了随机占位图服务	改用免费版权图库服务

4.3 KiB Raw Blame History Unescape Escape