@wagemule/daemon 0.1.2 → 0.1.4

package/dist/skills/larksuite/lark-whiteboard/references/connectors.md

@@ -0,0 +1,102 @@
+# 连线系统
+
+## 连线策略
+
+| 连线数 | 策略 |
+|--------|------|
+| ≤8 | 逐条画 |
+| 9-15 | 代表性连线（每层选 1-2 个节点连到下一层）|
+| >15 | 层到层连线，或回退精简分组 |
+
+一个节点有 3+ 条连线时：入线从 top，出线从 bottom，同侧多条线用不同方向分散。
+
+---
+
+## connector 必须放根 nodes 数组
+
+```typescript
+// 错误：connector 放在 frame children 里
+{ type: 'frame', children: [
+  { type: 'connector', ... }  // 会导致 Schema 报错或无法连线！
+]}
+
+// 正确：connector 放在根 nodes 数组
+const doc: WBDocument = {
+  version: 2,
+  nodes: [
+    { type: 'frame', id: 'box', ... },
+    { type: 'connector', ... },  // 必须和顶层 frame 平级
+  ],
+};
+```
+
+---
+
+## 箭头默认值
+
+- `endArrow` 省略时默认为 `'arrow'`（即连线末端默认带箭头）。
+- `startArrow` 省略时默认为 `'none'`（即连线起始端默认无箭头）。
+
+---
+
+## 连线技巧
+
+```typescript
+// 自动绕线（推荐）：仅需指定节点 id（引擎可自动推断最优出线方向），并使用 polyline 或 rightAngle 形状
+// 只要不传 waypoints，引擎会尝试自动避开障碍物并生成折线。
+{ type: 'connector', connector: {
+  from: 'a', to: 'b', // fromAnchor 和 toAnchor 也可以省略，让引擎自己找最短路径
+  lineShape: 'polyline', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
+
+// 精确坐标（做注解箭头）
+{ type: 'connector', connector: {
+  from: { x: 150, y: 200 }, to: 'b', toAnchor: 'left',
+  lineShape: 'curve', lineColor: '#BBBFC4', lineWidth: 2,
+  lineStyle: 'dashed', endArrow: 'triangle' }}
+
+// 手动控制路径点 waypoints（仅在需要强制固定路线、或者自动路由不符合预期时使用）
+// 注意：一旦提供了 waypoints，引擎将严格尊重这些点，不再进行自动避障。
+{ type: 'connector', connector: {
+  from: { x: 300, y: 140 }, to: { x: 300, y: 340 },
+  waypoints: [{ x: 350, y: 140 }, { x: 350, y: 340 }],
+  lineShape: 'polyline', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
+
+// 绘制坐标轴/数轴（必须使用 straight，防止刻度文字触发自动避障导致线条弯曲）
+{ type: 'connector', connector: {
+  from: { x: 100, y: 400 }, to: { x: 600, y: 400 },
+  lineShape: 'straight', lineColor: '#000000', lineWidth: 2, endArrow: 'arrow' }}
+```
+
+> [!IMPORTANT]
+> **1. 形状选用要求（核心）**，需明确 `lineShape` 类型：
+> - **`'polyline'`（圆角折线）**：**默认首选**。适用于流程图、架构图等绝大多数场景。支持引擎的**自动绕线与避障**功能（只需指定 `from` 和 `to`）。
+> - **`'rightAngle'`（直角折线）**：适用于明确要求“总线/直角规约”、树状层级严格对齐的场景，同样支持**自动绕线与避障**。
+> - **`'straight'`（直线）**：不受自动避障机制的影响，适用于**坐标轴、数轴、几何图形边框、直接指向关系**等要求线条绝对笔直、不允许出现任何绕行或弯曲的场景。
+> - **`'curve'`（曲线）**：适用于优雅的跨层连线（S型弯）、自由发散的脑图分支、或做注解箭头时。
+> - **注意**：你需要根据当前绘制的图表类型和上下文语境，选择最合适的 `lineShape`。不要盲目全部使用 `polyline`，例如在绘制坐标系时必须主动切换为 `straight`。
+> **2. 间距要求**：有 connector 连线的卡片间 gap 需 ≥ 40，否则箭头挤在缝里看不清。
+> **3. 顶层约束**：`connector` 必须直接放在 `WBDocument.nodes`，**严禁**嵌套在 `children` 内。建议在数据末尾统一声明连线。
+>
+> [!TIP]
+> **自动绕线 vs 手动控制**
+> - **优先依赖自动绕线**：对于 `'polyline'` 和 `'rightAngle'`，引擎会自动规划路径并尝试避开障碍物（`fromAnchor` 和 `toAnchor` 也可省略，引擎会自动推断最优出线方向），这是最推荐的方式。
+> - **何时手动算 waypoints**：**仅在必要时**（例如自动路由不符合预期，或者必须强制走特定形状绕开特定元素时），才需要通过 `waypoints` 手动接管坐标序列。
+>
+> **连线标签**
+> - **连线文字说明**：需要文字说明时，可用 `label` 标注。
+
+---
+
+## 锚点方向规则
+
+锚点（top/right/bottom/left）表示连线从节点的哪个边出发，方向含义与 CSS border 四边相同。
+
+**注意：由于目前自动绕线功能支持省略锚点让引擎自动推断，以下规则主要适用于你想强制控制出线方向，或者使用直线/曲线时的场景。**
+
+选择锚点时根据两个节点的相对位置：目标在下方用 `fromAnchor: 'bottom'` + `toAnchor: 'top'`，目标在右侧用 `fromAnchor: 'right'` + `toAnchor: 'left'`。如果手动指定了锚点，必须与节点的实际相对位置匹配，否则可能导致连线反向绕行。
+
+**锚点绑定的常见范式**：
+- **同层横向推进**（目标在正右）：`fromAnchor: "right"` -> `toAnchor: "left"`
+- **垂直下沉推进**（目标在正下）：`fromAnchor: "bottom"` -> `toAnchor: "top"`
+- **跨层斜切推进**（目标在左下或右下）：首选 **`fromAnchor: "bottom"` -> `toAnchor: "top"`**。由于线段自身带有重力倾向，从底部出线再弯曲进入下一层顶部，完美契合流水线的 S 型大弯，能画出最优雅顺滑的跨层曲线。**避免**使用左右锚点互相跨接。
+- **逆流回捞**（底部发散回指顶部原点）：首选 **`fromAnchor: "top"` -> `toAnchor: "bottom"`** 配合 `lineStyle: "dashed"`。

package/dist/skills/larksuite/lark-whiteboard/references/content.md

@@ -0,0 +1,40 @@
+# 内容规划
+
+核心原则：**信息量匹配用户需求的详细程度。** 用户说"画一个简单架构图"就画简单的，说"画一个完整的微服务架构"才画复杂的。不要自作主张**过度展开**。
+
+**用户 prompt 简短/模糊时**（如"画个漏斗图"、"画个架构图"），不要只输出字面内容。应适当补充该领域合理的内容
+
+## 信息量参考
+
+| 用户需求 | 合理的信息量 |
+|---------|------------|
+| "画一个简单的 XX 架构图" | 3 层，每层 2-3 节点，无侧边栏 |
+| "画一个 XX 架构图"（普通请求） | 3-4 层，每层 3-4 节点 |
+| "画一个完整/详细的 XX 架构图" | 4-5 层，每层 4-6 节点，可加侧边栏（侧边栏最多 2-3 项）|
+| 流程图 | 6-10 步骤 + 1-2 个条件分支 |
+| 对比表 | 4-6 个维度，每格 1-2 行说明 |
+| 组织架构 | 3-4 层，每个父节点下 2-4 个子节点 |
+
+**节点文字**：标题 + 简短说明（如"用户服务\n注册登录和权限管理"），不要写长段落。说明 12 字以内为佳。
+
+## 分组
+
+每组 2-5 个节点。超过 5 个拆成子组。
+
+## 连线预判
+
+| 连线数 | 策略 |
+|--------|------|
+| ≤8 | 逐条画 |
+| 9-15 | 代表性连线 |
+| >15 | 层到层，或回退精简 |
+
+## 精简触发条件
+
+布局放不下时才精简：
+
+| 问题 | 精简方式 |
+|------|---------|
+| 节点文字放不下 | 缩短描述文字 |
+| 一行节点超过 5 个 | 拆成两排或合并同类 |
+| 连线交叉 | 减少连线数量 |

package/dist/skills/larksuite/lark-whiteboard/references/image.md

@@ -0,0 +1,80 @@
+# 图片准备 (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. 校验图片
+
+```bash
+ls -l *.jpg   # 确认每张文件大小不同；若大小相同则内容可能重复，需重新下载
+```
+
+**图片内容审查（必须执行）**：
+- 下载完成后，确认文件是真实图片而非 HTML 错误页：若某张图片大小 < 1KB，很可能是下载失败返回了 HTML 错误页，需重新下载
+- **图片内容正确性只能在渲染后验证**：生成 DSL 并本地渲染 PNG 后，必须查看渲染结果，确认每张图片内容与主题相关（如宠物主题的图片确实是宠物，而非建筑/风景等不相关内容）
+- 若发现图片内容与主题不符，必须用更精确的关键词重新下载并重新上传
+
+### 3. 上传到目标画板
+
+**必须**使用 `docs +media-upload --parent-type whiteboard` 上传：
+
+```bash
+lark-cli docs +media-upload --file ./photo1.jpg --parent-type whiteboard --parent-node <whiteboard_token>
+# 响应: { "file_token": "<media_token>", ... }
+```
+
+逐张上传，收集每个 media token：
+
+```bash
+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 中引用
+
+```json
+{ "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 |
+| 图片内容与主题无关 | 使用了随机占位图服务 | 改用免费版权图库服务 |

package/dist/skills/larksuite/lark-whiteboard/references/lark-whiteboard-query.md

@@ -0,0 +1,49 @@
+# whiteboard +query（查询画板）
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询画板内容，支持导出为预览图片、提取 PlantUML/Mermaid 代码，或获取飞书 OpenAPI 原生画板节点格式。
+
+## 参数
+
+| 参数                   | 必填 | 说明                                                                     |
+|----------------------|----|------------------------------------------------------------------------|
+| `--whiteboard-token` | 是  | 画板 token，需要拥有画板的读权限                                                    |
+| `--output_as`        | 是  | 输出格式：`image`（预览图片）、`code`（PlantUML/Mermaid 代码）、`raw`（OpenAPI 原生画板节点格式） |
+| `--output`           | 否  | 输出路径。当 `--output_as image` 时必填；当 `--output_as code/raw` 时可选，不填则直接输出到终端 |
+| `--overwrite`        | 否  | 覆盖已存在的文件，默认为 false                                                     |
+
+## 输出格式
+
+- `image`：预览图片
+- `code`：PlantUML/Mermaid 代码。仅限画板内有且仅有一个 PlantUML/Mermaid 图时，才可导出代码，否则会在返回值中告知不存在/有多个节点。
+- `raw`：飞书 OpenAPI 原生画板节点格式。这一 json 格式不适合直接编辑复杂布局或内容，建议仅限于需要修改简单的文本内容/颜色等细节时使用。需要进行更复杂的设计/修改时，建议参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)。
+
+## 示例
+
+### 示例 1：导出画板为预览图片
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as image \
+  --output ./preview.png
+```
+
+### 示例 2：提取画板中的代码并直接输出
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as code
+```
+
+### 示例 3：导出画板原始节点结构到文件
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as raw \
+  --output ./nodes.json \
+  --overwrite
+```

package/dist/skills/larksuite/lark-whiteboard/references/lark-whiteboard-update.md

@@ -0,0 +1,100 @@
+# whiteboard +update（更新画板）
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+更新画板内容，支持三种输入格式：
+
+- `raw`：飞书 OpenAPI 原生画板节点格式，不推荐直接编辑。
+- `plantuml`：PlantUML 代码
+- `mermaid`：Mermaid 代码
+
+输入内容可以通过管道从 stdin 读取，或通过 `--source` 指定文件。
+
+## 参数
+
+| 参数                   | 必填 | 说明                                         |
+|----------------------|----|--------------------------------------------|
+| `--whiteboard-token` | 是  | 画板 token，需要拥有画板的编辑权限                       |
+| `--idempotent-token` | 否  | 幂等 token，确保更新操作幂等，最小长度 10 个字符              |
+| `--overwrite`        | 否  | 覆盖更新，在更新前删除所有现有内容，默认为 false                |
+| `--source`           | 是  | 输入画板内容，支持使用 `@path` 从文件读取，或 `-` 从 stdin 读取 |
+| `--input_format`     | 否  | 输入格式：`raw`、`plantuml`、`mermaid`，默认为 `raw`  |
+
+### 以 raw (OpenAPI 原生画板节点格式) 创作
+
+**不要以直接生成 json 语法的方式创作 raw 格式的飞书 OpenAPI 原生画板节点参数**
+
+思维导图，时序图，类图，饼图，流程图等图表推荐使用 Mermaid/PlantUML 语法绘制。
+
+而当需要绘制架构图，组织架构图，泳道图，对比图，鱼骨图，柱状图，折线图，树状图，漏斗图，金字塔图，循环/飞轮图，里程碑或其他较为复杂的图表时，推荐参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板) 使用 whiteboard-cli 工具创作。
+
+## 示例
+
+### 示例 1：使用 PlantUML 代码更新画板（从 stdin 读取）
+
+```bash
+# 编写 PlantUML 代码
+cat > diagram.puml << 'EOF'
+@startuml
+Alice -> Bob: Hello
+Bob -> Alice: Hi
+@enduml
+EOF
+
+# 通过管道传递给命令
+cat diagram.puml | lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --input_format plantuml --source -\
+  --overwrite --as user
+```
+
+### 示例 2：使用 Mermaid 代码更新画板（从文件读取）
+
+```bash
+# 编写 Mermaid 代码
+cat > diagram.mmd << 'EOF'
+graph TD
+    A[开始] --&gt; B{判断}
+    B --&gt;|是| C[处理]
+    B --&gt;|否| D[结束]
+    C --&gt; D
+EOF
+
+# 从文件读取并更新
+lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --input_format mermaid \
+  --source @./diagram.mmd \
+  --overwrite --as user
+```
+
+### 示例 3：使用 whiteboard-cli 生成 OpenAPI 格式并写入画板
+
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+
+```bash
+# 使用 whiteboard-cli 生成 OpenAPI 格式并通过管道传递
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <产物文件> --to openapi --format json \
+  | lark-cli whiteboard +update \
+    --whiteboard-token <画板Token> \
+    --source - --input_format raw \
+    --idempotent-token <10+字符唯一串> \
+    --as user
+```
+
+### 示例 4：先生成产物文件，再从文件读取更新
+
+whiteboard-cli 工具的具体用法请参考 [§ 渲染 & 写入画板](../SKILL.md#渲染--写入画板)
+
+```bash
+# 生成 OpenAPI 格式到文件
+npx -y @larksuite/whiteboard-cli@^0.2.11 -i <DSL 文件> --to openapi --format json -o ./temp.json
+
+# 从文件读取并更新
+lark-cli whiteboard +update \
+  --whiteboard-token <画板Token> \
+  --idempotent-token <10+字符唯一串> \
+  --input_format raw \
+  --source @./temp.json \
+  --overwrite --as user
+```