ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
5.3 KiB
5.3 KiB
文档样式指南
创建或编辑文档时，必须遵循本指南，使用结构化 block 提升可读性和视觉层次。
一、核心原则
- 结构优于文字：能用结构化 block 表达的信息，不用纯文本段落
- Front-load 结论：文档以
<callout>开头概括核心结论；每章节首段点明要旨 - 视觉节奏：连续纯文本不超过 3 段；不同主题章节间用
<hr/>分隔 - 风格一致：同类信息使用同类元素，全篇风格统一
- 重要信息画板化：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达
二、元素选择指南
涉及图表需求时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图用 <whiteboard type="mermaid"> 直接内嵌；其他新图表启动 SubAgent 插入 <whiteboard type="svg">完整 SVG</whiteboard>；只有编辑已有画板时才调用 lark-whiteboard skill。
| 场景 | 推荐方案 |
|---|---|
| 核心结论 / 摘要 / 注意事项 | <callout> + emoji + 背景色 |
| 重要方案对比 / 优劣势 / Before vs After | <grid> 2 列分栏；SVG SubAgent |
| 简短低风险对比 | <grid> 2 列分栏 |
| 3+ 属性的结构化数据 / 指标表 | <table> + 表头背景色 |
| 任务清单 / 检查项 | <checkbox> |
| 代码片段 | <pre lang="x" caption="说明"> |
| 引用 / 公式 | <blockquote> / <latex> |
| 操作入口 / 跳转链接 | <button> / <a type="url-preview"> |
| 流程图 / 时间线 / 示意图 / 自定义图形 / 架构图 / 数据图 / 思维导图等 | 画板图表 |
画板意图识别
撰写或审查每个段落/章节时，必须判断该内容是否适合用图表达。满足以下任一特征时，应使用画板而非纯文本；如果该内容承载章节核心结论、关键决策或主要论据，即使结构较简单也优先画板化：
| 内容特征 | 信号词 / 模式 | 推荐画板类型 |
|---|---|---|
| 多步骤的操作流程或决策路径 | "先…然后…最后"、"步骤 1/2/3"、"如果…则…否则" | 流程图 / 泳道图 |
| 系统或模块间的依赖与交互 | "调用"、"依赖"、"上游/下游"、"请求→响应" | 架构图 |
| 上下级或从属关系 | "汇报给"、"下属"、"隶属"、"团队结构" | 组织架构图 |
| 时间线或阶段演进 | "Q1/Q2"、"里程碑"、"阶段一→阶段二"、日期序列 | 时间线 / 里程碑 |
| 因果分析或问题归因 | "根因"、"原因"、"导致"、"影响因素" | 鱼骨图 |
| 两个及以上方案/对象的多维度对比 | "vs"、"方案 A/B"、"优劣"、"对比" | 对比图 |
| 层级递进或优先级排序 | "基础→进阶→高级"、"L1/L2/L3"、"核心→外围" | 金字塔图 |
| 数值趋势或周期变化 | 带数字的时间序列、"增长/下降"、百分比变化 | 折线图 / 柱状图 |
| 漏斗或转化率 | "转化率"、"漏斗"、"从…到…留存" | 漏斗图 |
| 发散或归纳的思维结构 | "要点"、"维度"、"分支"、多层嵌套列表 | 思维导图 |
| 循环或飞轮效应 | "正循环"、"飞轮"、"闭环"、"A 驱动 B 驱动 C" | 飞轮图 |
| 占比分布 | "占比"、"份额"、"分布"、百分比加总 ≈100% | 饼图 / 树状图 |
判断规则：
- 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本
- 低重要度、局部辅助信息才用
<table>/<grid>/<callout>承载 - 确定需要插入哪些图表后，参照 lark-doc-whiteboard.md 中的方式，插入图表画板。
三、颜色语义
全篇保持语义一致，同一语义必须使用同一颜色：
| 语义 | emoji 前缀 | callout 背景色 | 文字色 |
|---|---|---|---|
| 信息、说明 | ℹ️ "说明：" | light-blue |
blue |
| 成功、推荐 | ✅ "推荐：" | light-green |
green |
| 警告 / 错误 / 风险 | ⚠️❌ | light-red |
red |
| 注意、待确认 | ❗"注意：" | light-yellow |
yellow |
| 中性、辅助 | — | light-gray |
— |
- 表头统一
background-color="light-gray" - 关键指标用
<span text-color="green/red">突出，必须同时用 ↑↓ 或 +/- 标注方向（色觉无障碍）
四、排版规范
- 标题层级 ≤ 4 层，段落单段 ≤ 5 行，列表嵌套 ≤ 2 层，Grid ≤ 3 列
- 文档开头用
<callout>front-load 结论。
五、丰富度自检
生成内容后必须自检，未达标时主动优化：
| 指标 | 达标标准 |
|---|---|
| 富 block 密度 | ≥ 40%（非纯文本 block 数 ÷ 总 block 数） |
| 元素多样性 | ≥ 3 种不同 block 类型 |
| 连续纯文本 | ≤ 3 段连续 <p> |
| 章节丰富度 | 每 h1/h2 ≥ 1 个非纯文本 block |
| 开头 callout | 必须 |
| 视觉节奏 | 不同主题章节间有 <hr/> |