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

7.7 KiB

Raw Blame History

lark-doc 画板处理指南

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

两个 Skill 的职责边界

Skill	核心职责	约束
`lark-doc`	识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板	主 Agent 不直接创作画板内容；
`lark-whiteboard`	查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板	仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取

画板优先规则

写文档时，重要信息优先画板化。遇到核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，不要只用段落或表格承载；除非内容只是一次性补充说明，否则应规划为画板。

同一篇文档可以有多个画板。优先设计多个聚焦画板，而不是把所有信息塞进一张大图。

文档与画板协同流程

步骤 1：识别画板机会

场景	入口
文档中需要思维导图、时序图、类图、饼图、甘特图	步骤 2A:使用 mermaid 插入图表
文档中需要插入其他图表/自定义图形	步骤 2B: 使用 SVG 插入图表
已有画板需要更新内容	先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3B
只查看 / 下载已有画板	切换至 `lark-whiteboard`，不走本流程

Important

⚠️ 分别对每个图表进行决策

如果有多个位置需要插入图表，你需要根据每个图表的内容分别决定采用步骤 2A 还是 2B 中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动 SubAgent 插入 SVG。

建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表

步骤 2A: 使用 mermaid 插入图表


<whiteboard type="mermaid">
    mermaid 代码...
</whiteboard>

步骤 2B: SubAgent 使用 SVG 插入图表

主 Agent 启动 SubAgent，让它用 docs +create --api-version v2 / docs +update --api-version v2 插入：


<whiteboard type="svg">
    <svg...>...
    </svg>
</whiteboard>

Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：

doc token、插入位置（标题 / block_id / command）
图表目标、受众、源段落或数据
要求读取 lark-doc-xml.md；不需要读取 lark-whiteboard
SVG 必须完整自包含：包含 <svg> 根节点和 viewBox，不引用外部图片、脚本、远程资源

画板 SVG 设计指南

使用 SVG 插入画板时，最终交付是画板跨越重排渲染的节点(你写 SVG → 画板解析) 核心心智纠正 (重要)：

大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 <rect> 的方正卡片网格, 极其死板单调, * 这将被视为不及格！*
SVG 给你了完全的设计自由, 请大胆使用你脑内的图标路径 (<path>), 连接指引 (流畅的 <path>), 各种环境氛围点缀, 大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！

SVG 设计 Workflow

1. 想清楚要画什么

核心信息是什么？ 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
内容充实度：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
视觉层级与隐喻：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构

2. 写 SVG

Important

布局, 配色, 信息密度, 装饰物——全部由你判断, 打破单调的 <rect> 牢笼, 严禁通篇用矩形和文字应付用户操作边界约束：

语言跟随用户：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
文字用 <text>(不是 <path>), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
连线使用正交折线替代斜直线(<polyline> 带水平/垂直折点)视觉效果更好
可自由使用 translate, rotate, scale但请尽量避免使用 skewX / skewY / matrix(...) 发生空间级扭曲

画板怎么处理 SVG

画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但 <radialGradient> / <filter> / <clipPath> 等装饰特性画板完全不支持，会导致渲染问题（见下方⚠️） 不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮

可识别的元素

形状：<rect> / <circle> / <ellipse> / <polygon>
连线：<line> / <polyline> / <path>(自动识别为直线 / 折线 / 曲线)
文本：<text> / <tspan> 画板硬编码 Noto Sans SC 文字必须用 <text>
分组：<g> / <a> / <use> 引用 <symbol>
变换：translate / rotate / scale 正常；skewX / skewY / matrix(...) 降级

Important

⚠️ ** 不支持的装饰特性**

<radialGradient> / <filter> / <pattern> / <clipPath> / <mask> → 画板都不支持，**请避免使用，否则会导致画板渲染问题 **

3.插入后审查

插入画板后，可以从返回值使用 lark-cli 指令，将画板内容导出为 png 图片。若是对设计不满意，可以修改后，删除原来的画板再重新插入，或是调用 ../../lark-whiteboard/SKILL.md 编辑。

lark-cli whiteboard +query \
  --whiteboard-token "wbcnxxxxxxxx" \
  --output_as image \
  --output ./preview.png

步骤 3B：编辑已有画板 — 启动 lark-whiteboard SubAgent

复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 lark-whiteboard 的渲染和写入流程。

复杂图 SubAgent 的最小上下文：

board_token
图表目标、推荐画板类型、受众
与图表直接相关的源段落或数据
要求读取 ../../lark-whiteboard/SKILL.md，按其完整流程写入该 board_token

多个画板互不依赖时，可并行启动多个 SubAgent；每个 SubAgent 只负责一个画板或一个 SVG 插入点，不要互相复用上下文。

步骤 4：完成校验

Mermaid: 确认插入的是 <whiteboard type="mermaid">，且内容 mermaid 语法完整
SVG: 确认插入的是 <whiteboard type="svg">，且内容是完整 <svg ...>...</svg>
不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成

关联参考

画板查询/创作/修改/渲染写入：../../lark-whiteboard/SKILL.md

7.7 KiB Raw Blame History Unescape Escape