ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
86 lines
5.3 KiB
Markdown
86 lines
5.3 KiB
Markdown
# 文档样式指南
|
||
|
||
创建或编辑文档时，必须遵循本指南，使用结构化 block 提升可读性和视觉层次。
|
||
|
||
## 一、核心原则
|
||
|
||
1. **结构优于文字**：能用结构化 block 表达的信息，不用纯文本段落
|
||
2. **Front-load 结论**：文档以 `<callout>` 开头概括核心结论；每章节首段点明要旨
|
||
3. **视觉节奏**：连续纯文本不超过 3 段；不同主题章节间用 `<hr/>` 分隔
|
||
4. **风格一致**：同类信息使用同类元素，全篇风格统一
|
||
5. **重要信息画板化**：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达
|
||
|
||
## 二、元素选择指南
|
||
|
||
涉及图表需求时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图用 `<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](../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/>` |
|