飞书CLI-画板创作

# Feishu Workspace README 模板

这份 README 用于约束飞书 CLI 相关任务的入口方式。它适合作为团队或个人的工作台首页，用来告诉使用者：

- 这个目录是做什么的；
- 哪类任务先看哪份规则；
- 本地源文件和云端交付之间的关系；
- 文件应该放在哪里。

## 1. 快速约束

- 默认工作方式：先本地创作，再导入云端。
- 飞书云端默认位置：替换为个人的目标文件夹名称。
- 本地源文件只放在当前 workspace 内，不放到桌面、临时目录或其他项目目录。
- 本地文件名与飞书云端文档标题都遵循同一套排序规则：`YYYY-MM-DD_topic`。
- 本地文件保留扩展名，例如 `.md`、`.svg`；飞书云端文档标题不写扩展名。
- topic 使用英文小写、数字和下划线；不使用空格、中文或含义不明的缩写。
- 如果实际调用飞书 CLI，最后建议增加一条状态通知。

## 2. 任务路由

| 任务类型 | 先看哪里 | 产物位置 |
|---|---|---|
| 新建或编辑飞书文档 | `rules/feishu-cli-guideline.md` 第 3 节 | `drafts/` 与飞书云端 |
| 创建 SVG 或导入飞书画板 | `rules/feishu-cli-guideline.md` 第 4、5 节 | `assets/` 与飞书画板 |
| 验证 SVG 可编辑性 | `rules/feishu-cli-guideline.md` 第 4、6 节 | `svg-validation/` |
| 调用飞书 CLI 后收尾 | `rules/feishu-cli-guideline.md` 第 7 节 | 状态通知 |
| 修改工作规则 | 本文件与 `rules/feishu-cli-guideline.md` | `rules/` |

## 3. 目录说明

```text
feishu-workspace/
├── README.md            # 必读入口与任务路由
├── drafts/              # Markdown 草稿与文档源文件
├── assets/              # SVG 等可编辑视觉源文件
├── svg-validation/      # SVG/画板验证记录或辅助材料
└── rules/               # 完整工作规则
```

## 4. 推荐启动语

```text
请按 feishu-workspace/README.md 的规则创建一个 SVG，并导入飞书画板。
```

或：

```text
请参考 feishu-workspace 里的规则，创建一份飞书文档。
```

## 5. 需要替换的个人配置

```text
替换为个人的目标文件夹名称
替换为个人的飞书云端目录链接
替换为个人的飞书 folder token
替换为个人的通知应用名称
替换为个人的应用 app id
替换为个人的收件人 user id
```

# 飞书 CLI 文档与画板工作指南模板

> 这份模板面向需要通过飞书 CLI 创建、更新飞书文档、导入 SVG 到飞书画板的个人或团队。所有与个人身份、组织目录、机器人通知相关的信息，都必须替换成自己的配置。

## 1. 目的与默认工作方式

本指南用于约束后续通过飞书 CLI 创建、更新和交付飞书文档、画板与 SVG 的工作方式。

默认采用 **先本地创作，再导入云端** 的方式：本地 Markdown 与 SVG 是可审阅、可复用、可回退的源文件；飞书文档与画板是协作、发布和人工调整的最终载体。

直接在线写入只用于两种情况：

- 对既有飞书文档进行小范围、可定位的修改。
- 用户明确要求直接在飞书中创作，或本地源文件没有保留价值。

无论采用哪种方式，线上写入后都必须回读验证；不得把 PNG 或截图作为唯一的视觉交付。

## 2. 位置与边界

### 飞书云端位置

所有新建飞书文档默认创建到“替换为个人的目标文件夹名称”文件夹。

- 文件夹链接：`替换为个人的飞书云端目录链接`
- Folder token：`替换为个人的 folder token`
- 创建时必须显式指定：`--parent-token 替换为个人的 folder token`

不得将文档创建到“我的空间”根目录或其他未经指定的云盘位置。

### 本地源文件位置

本地工作根目录示例：

```text
feishu-workspace/
├── README.md           # 必读入口与任务路由
├── drafts/             # Markdown 草稿与可复用内容源
├── assets/             # SVG 等可编辑视觉源文件
├── svg-validation/     # SVG/画板验证记录或辅助材料
└── rules/              # 完整工作规则与参考规范
```

本地文件是源文件，不是飞书文档的最终位置。除上述目录外，不在桌面、临时目录或无关项目目录创建交付文件。

## 3. 文档工作规则

### 创建与导入

1. 先确认飞书 CLI 可用、已授权，并具备目标文件夹权限。
2. 优先在 `drafts/<project>/` 完成 Markdown 草稿；内容较短、无需保留本地源文件时，可直接在线创建。
3. 新建线上文档时，必须指定目标 folder token。
4. Markdown 导入或整段创建后，回读标题、关键段落、表格、链接与附件，确认内容完整且位置正确。

### 内容与命名

- 本地 Markdown 文件名：`YYYY-MM-DD_topic.md`。
- SVG 文件名：`YYYY-MM-DD_topic.svg`，与 Markdown 文档保持同一命名与排序规则。
- 飞书云端文档标题：`YYYY-MM-DD_topic`，不写 `.md`、`.svg` 等本地扩展名。
- 同一任务的本地源文件、飞书文档和飞书画板标题应使用同一个 `YYYY-MM-DD_topic` 前缀，确保本地与云端可以按名称对应。
- topic 使用英文小写、数字和下划线；不使用空格、中文或含义不明的缩写。
- 每篇 Markdown 仅保留一个一级标题；章节随内容选择，不强制套用固定模板。
- 事实、数字、日期和外部结论必须保留来源；信息不完整时写“待确认”，不补造。
- 导入前清理无意义的网页引用、HTML 残留和不可见控制字符；代码块内容保持原样。

### 在线更新

- 修改既有文档前先读取目标内容与定位信息。
- 优先使用局部更新，不整篇覆盖；只有用户明确要求重建全文时才覆盖。
- 每次更新后回读受影响区域，确认没有重复标题、遗漏内容或失效链接。

## 4. SVG 与飞书画板工作规则

### 基本要求

- 默认画布为 `1920 × 1080`（16:9）；内容需要时可以调整，并在交付时说明。
- SVG 源文件直接保存到 `assets/`，并保留至交付后。
- 文字使用 SVG `<text>` 元素；模块、连线和标签尽量使用可被飞书画板识别的基础元素，例如 `<rect>`、`<circle>`、`<polyline>`、`<line>` 与 `<text>`。
- 避免滤镜、渐变、遮罩、裁剪路径、外部图片和远程资源，以免画板降级成不可编辑图片。
- 使用网格化布局、统一间距与清晰对齐；连线不穿过文字，元素不得重叠或被裁切。
- PNG 仅可作为内部预览；不能替代 SVG 源文件或画板交付。

### 画板导入与验证

1. 先在本地完成 SVG，并进行结构检查。
2. 在目标飞书文档中创建或定位画板，再导入 SVG。
3. 导入后查询画板节点：确认关键文字、形状和连接线被解析为独立节点。
4. 若 SVG 的解析结果不满足编辑需求，优先改用 Mermaid 或飞书画板原生节点结构；不以截图替代。
5. 交付时同时提供 SVG 本地路径、飞书文档或画板链接，以及验证结论。

## 5. SVG 视觉风格体系

### Style A：Apple 产品展示风格

适用于产品介绍、产品架构、发布会页面、用户体验展示和高端消费电子方案。

- 气质：极简、大量留白、高级感、清晰焦点、少量颜色。
- 布局：中心化，大尺寸核心元素，少量模块，强调视觉节奏。
- 颜色：白色或浅灰背景、黑色正文、灰色辅助、单一强调色。
- 字体：中文 `PingFang SC`；英文 `SF Pro Display`。
- 参考字号：标题 40–48px，分组标题 28–32px，正文 16–20px。

### Style B：McKinsey 咨询分析风格

适用于战略分析、商业模式、市场研究、产品规划与管理层汇报。

- 气质：专业、严谨、信息密度适中，突出逻辑、数据与关系。
- 布局：模块化网格、清晰标题层级，强调因果关系与结论。
- 颜色：白色背景、深蓝与灰色为主，少量强调色。
- 常用组件：Framework、Matrix、Pyramid、Timeline、2×2 Diagram、Business Model Canvas。
- 字体：中文 `PingFang SC`；英文 `Arial` 或 `Helvetica`。
- 参考字号：标题 32–36px，分组标题 22–28px，正文 14–18px。

### Style C：Information Graphic 信息图风格

适用于知识图谱、技术路线、科普解释、复杂系统展示与用户教育。

- 气质：图形化、易理解、信息丰富但不混乱。
- 布局：卡片化、分区展示、图文结合，信息层级明显。
- 颜色：可按模块分类，最多使用 5 种主题色。
- 组件：图标、标签、数据卡片和分区说明。
- 字体：中文 `PingFang SC`；英文 `Arial`。
- 参考字号：标题 36px，分组标题 24px，正文 14–16px。

## 6. 交付前检查

### 文档

- 文档已创建在“替换为个人的目标文件夹名称”文件夹。
- 标题、内容结构、表格、链接和附件已回读验证。
- 本地源文件命名正确、保存在规定位置。
- 所有待确认项均已明确标注。

### SVG 与画板

- SVG 为有效矢量文件，文字、模块和连线未重叠或裁切。
- SVG 源文件仍保留在 `assets/`。
- 飞书画板已回读验证，关键文字、形状和连接线可独立编辑。
- 已向用户返回源文件路径、飞书链接与验证结果。

## 7. 飞书 CLI 任务状态通知

每个实际调用飞书 CLI 的任务，在完成主任务后都建议由飞书应用机器人向自己发送一条状态消息。通知是任务的最后一个动作；通知命令本身不触发新的通知，避免循环发送。

### 发送配置

- 应用：`替换为个人的通知应用名称`
- App ID：`替换为个人的应用 app id`
- 发送身份：`bot`
- 收件人：`替换为个人的收件人 user id`
- 使用 CLI 发送纯文本消息

### 消息格式

消息必须使用中国时区的执行结束时间，格式如下：

```text
YYYY-MM-DD_HH-mm_任务名字：执行状态。
```

示例：

```text
2026-07-10_19-40_测试飞书CLI消息推送：执行成功。
```

任务名字使用用户可理解的中文短名称；执行状态至少使用“执行成功”“部分成功”或“执行失败”，必要时可在句末补充简短原因。

### 发送规则

1. 在主任务已得到明确结果后再发送通知；成功、部分成功和失败都要发送。
2. 每条消息带唯一且简短的 `--idempotency-key`，由时间与任务标识组成，避免重试产生重复消息；不要使用过长 key，以免触发字段校验失败。
3. 发送后检查返回值中的 `ok == true`，并在最终交付中说明通知是否发送成功。
4. 若通知发送失败，不改变主任务本身的执行结论；向用户明确说明通知未发出及原因。

### 必须替换的个人配置

```text
替换为个人的目标文件夹名称
替换为个人的飞书云端目录链接
替换为个人的 folder token
替换为个人的通知应用名称
替换为个人的应用 app id
替换为个人的收件人 user id
```