Back to Details

excalidraw

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Excalidraw Subagent Delegation

Excalidraw子代理委托机制

Overview

概述

Core principle: Main agents NEVER read Excalidraw files directly. Always delegate to subagents to isolate context consumption.
Excalidraw files are JSON with high token cost but low information density. Single files range from 4k-22k tokens (largest can exceed read tool limits). Reading multiple diagrams quickly exhausts context budget (7 files = 67k tokens = 33% of budget).
**核心原则：**主代理绝不直接读取Excalidraw文件。始终委托给子代理以隔离上下文消耗。
Excalidraw文件是高令牌成本但低信息密度的JSON文件。单个文件的令牌数范围为4k-22k（最大的文件可能超出读取工具限制）。读取多个图表会快速耗尽上下文预算（7个文件=67k tokens=预算的33%）。

The Problem

问题分析

Excalidraw JSON structure:
  • Each shape has 20+ properties (x, y, width, height, strokeColor, seed, version, etc.)
  • Most properties are visual metadata (positioning, styling, roughness)
  • Actual content: text labels and element relationships (<10% of file)
  • Signal-to-noise ratio is extremely low
Example: 14-element diagram = 596 lines, 16K, ~4k tokens. 79-element diagram = 2,916 lines, 88K, ~22k tokens (exceeds read limit).
Excalidraw JSON结构：
  • 每个图形包含20+个属性（x、y、宽度、高度、描边颜色、seed、版本等）
  • 大多数属性是视觉元数据（位置、样式、粗糙度）
  • 实际内容：文本标签和元素关系（占文件内容的<10%）
  • 信噪比极低
示例：14个元素的图表=596行，16K大小，约4k tokens。79个元素的图表=2916行，88K大小，约22k tokens（超出读取限制）。

When to Use

使用场景

Trigger on ANY of these:
  • File path contains 
    .excalidraw
    or 
    .excalidraw.json
  • User requests: "explain/update/create diagram", "show architecture", "visualize flow"
  • User mentions: "flowchart", "architecture diagram", "Excalidraw file"
  • Architecture/design documentation tasks involving visual artifacts
Use delegation even for:
  • "Small" files (smallest is 4k tokens - still significant)
  • "Quick checks" (checking component names still loads full JSON)
  • Single file operations (isolation prevents context pollution)
  • Modifications (don't need full format understanding in main context)
满足以下任一条件时触发：
  • 文件路径包含
    .excalidraw
    或
    .excalidraw.json
  • 用户请求：“解释/更新/创建图表”、“展示架构”、“可视化流程”
  • 用户提及：“流程图”、“架构图”、“Excalidraw文件”
  • 涉及视觉工件的架构/设计文档任务
即使是以下场景也需使用委托：
  • “小型”文件（最小的文件也有4k tokens - 仍占显著比例）
  • “快速检查”（检查组件名称仍会加载完整JSON）
  • 单个文件操作（隔离可防止上下文污染）
  • 修改操作（主上下文无需理解完整格式）

Delegation Pattern

委托模式

Main Agent Responsibilities

主代理职责

NEVER:
  • ❌ Use Read tool on *.excalidraw files
  • ❌ Parse Excalidraw JSON in main context
  • ❌ Load multiple diagrams for comparison
  • ❌ Inspect file to "understand the format"
ALWAYS:
  • ✅ Delegate ALL Excalidraw operations to subagents
  • ✅ Provide clear task description to subagent
  • ✅ Request text-only summaries (not raw JSON)
  • ✅ Keep diagram analysis isolated from main work
绝对禁止：
  • ❌ 对*.excalidraw文件使用读取工具
  • ❌ 在主上下文中解析Excalidraw JSON
  • ❌ 加载多个图表进行比较
  • ❌ 检查文件以“理解格式”
必须执行：
  • ✅ 将所有Excalidraw操作委托给子代理
  • ✅ 向子代理提供清晰的任务描述
  • ✅ 请求纯文本摘要（而非原始JSON）
  • ✅ 将图表分析与主要工作隔离开来

Subagent Task Templates

子代理任务模板

Read/Understand Operation

读取/理解操作

Task: Extract and explain the components in [file.excalidraw.json]

Approach:
1. Read the Excalidraw JSON
2. Extract only text elements (ignore positioning/styling)
3. Identify relationships between components
4. Summarize architecture/flow

Return:
- List of components/services with descriptions
- Connection/dependency relationships
- Key insights about the architecture
- DO NOT return raw JSON or verbose element details
Task: Extract and explain the components in [file.excalidraw.json]

Approach:
1. Read the Excalidraw JSON
2. Extract only text elements (ignore positioning/styling)
3. Identify relationships between components
4. Summarize architecture/flow

Return:
- List of components/services with descriptions
- Connection/dependency relationships
- Key insights about the architecture
- DO NOT return raw JSON or verbose element details

Modify Operation

修改操作

Task: Add [component] to [file.excalidraw.json], connected to [existing-component]

Approach:
1. Read file to identify existing elements
2. Find [existing-component] and its position
3. Create new element JSON for [component]
4. Add arrow elements for connections
5. Write updated file

Return:
- Confirmation of changes made
- Position of new element
- IDs of created elements
Task: Add [component] to [file.excalidraw.json], connected to [existing-component]

Approach:
1. Read file to identify existing elements
2. Find [existing-component] and its position
3. Create new element JSON for [component]
4. Add arrow elements for connections
5. Write updated file

Return:
- Confirmation of changes made
- Position of new element
- IDs of created elements

Create Operation

创建操作

Task: Create new Excalidraw diagram showing [description]

Approach:
1. Design layout for [number] components
2. Create rectangle elements with text labels
3. Add arrows showing relationships
4. Use consistent styling (colors, fonts)
5. Write to [file.excalidraw.json]

Return:
- Confirmation of file created
- Summary of components included
- File location
Task: Create new Excalidraw diagram showing [description]

Approach:
1. Design layout for [number] components
2. Create rectangle elements with text labels
3. Add arrows showing relationships
4. Use consistent styling (colors, fonts)
5. Write to [file.excalidraw.json]

Return:
- Confirmation of file created
- Summary of components included
- File location

Compare Operation

比较操作

Task: Compare architecture approaches in [file1] vs [file2]

Approach:
1. Read both files
2. Extract text labels from each
3. Identify structural differences
4. Compare component relationships

Return:
- Key differences in architecture
- Components unique to each approach
- Relationship/flow differences
- DO NOT return full element details from both files
Task: Compare architecture approaches in [file1] vs [file2]

Approach:
1. Read both files
2. Extract text labels from each
3. Identify structural differences
4. Compare component relationships

Return:
- Key differences in architecture
- Components unique to each approach
- Relationship/flow differences
- DO NOT return full element details from both files

Common Rationalizations (STOP and Delegate Instead)

常见自我合理化（停止这种想法，改用委托）

ExcuseRealityWhat to Do
"Direct reading is most efficient"Consumes 4k-22k tokens unnecessarilyDelegate to subagent
"It's token-efficient to read directly"Baseline tests showed 9-45% budget usedAlways delegate
"This is optimal for one-time analysis""One-time" still pollutes main contextSubagent isolation
"The JSON is straightforward"Simplicity ≠ token efficiencyDelegate anyway
"I need to understand the format"Format understanding not needed in main agentSubagent handles format
"Within reasonable bounds" (18k tokens)"Reasonable" is subjective rationalizationHard rule: delegate
"Just a quick check of components""Quick check" still loads full JSONExtract text via subagent
"File is small (16K)"4k tokens is NOT smallSize threshold doesn't matter
借口实际情况正确做法
"直接读取最有效率"会不必要地消耗4k-22k tokens委托给子代理
"直接读取令牌成本低"基准测试显示会消耗9-45%的预算始终委托
"一次性分析这样做最优""一次性"操作仍会污染主上下文子代理隔离
"这个JSON很简单"简单性≠令牌效率无论如何都要委托
"我需要理解格式"主代理无需理解格式由子代理处理格式
"在合理范围内"（18k tokens）"合理"是主观的自我合理化硬性规则：委托
"只是快速检查组件""快速检查"仍会加载完整JSON通过子代理提取文本
"文件很小（16K）"4k tokens并不小大小阈值无关紧要

Red Flags - STOP and Delegate

危险信号——停止操作并改用委托

Catch yourself about to:
  • Use Read tool on .excalidraw file
  • "Quickly check" what components exist
  • "Understand the structure" before modifying
  • Load file to "see what's there"
  • Compare multiple diagrams side-by-side
  • Parse JSON to "extract just the text"
All of these mean: Use Task tool with subagent instead.
当你准备做以下操作时，请立即停止：
  • 对.excalidraw文件使用读取工具
  • "快速查看"存在哪些组件
  • 修改前"理解结构"
  • 加载文件以"查看内容"
  • 并排比较多个图表
  • 解析JSON以"仅提取文本"
以上所有情况都意味着：改用子代理任务工具。

Quick Reference

快速参考

OperationMain Agent ActionSubagent Returns
Understand diagramDelegate with "Extract and explain" templateComponent list + relationships
Modify diagramDelegate with "Add [X] connected to [Y]" templateConfirmation + changes made
Create diagramDelegate with "Create showing [description]" templateFile location + summary
Compare diagramsDelegate with "Compare [A] vs [B]" templateKey differences (not raw JSON)
操作主代理操作子代理返回内容
理解图表使用"提取并解释"模板委托组件列表+关系
修改图表使用"添加[X]并连接到[Y]"模板委托确认信息+修改内容
创建图表使用"创建展示[描述]的图表"模板委托文件位置+摘要
比较图表使用"比较[A]与[B]"模板委托核心差异（非原始JSON）

Token Analysis (Why This Matters)

令牌分析（为什么这很重要）

Real data from baseline testing:
ScenarioWithout DelegationWith DelegationSavings
Single large file22k tokens (45% budget)~500 tokens (subagent summary)98%
Two-file comparison18k tokens (9% budget)~800 tokens (diff summary)96%
Modification task14k tokens (7% budget)~300 tokens (confirmation)98%
Context pollution impact:
  • Reading all 7 project diagrams: 67k tokens (33% of 200k budget)
  • With delegation: ~2k tokens (isolated in subagents)
  • Savings: 97% context budget preserved
基准测试的真实数据：
场景不使用委托使用委托节省比例
单个大文件22k tokens（45%预算）~500 tokens（子代理摘要）98%
双文件比较18k tokens（9%预算）~800 tokens（差异摘要）96%
修改任务14k tokens（7%预算）~300 tokens（确认信息）98%
上下文污染影响：
  • 读取所有7个项目图表：67k tokens（200k预算的33%）
  • 使用委托：~2k tokens（在子代理中隔离）
  • 节省：97%的上下文预算得以保留

Implementation Example

实现示例

❌ BAD (Direct Read):
User: "What architecture is shown in detailed-architecture.excalidraw.json?"
Agent: Let me read that file... [reads 22k tokens into main context]
✅ GOOD (Subagent Delegation):
User: "What architecture is shown in detailed-architecture.excalidraw.json?"
Agent: I'll use a subagent to extract the architecture details.

[Dispatches Task tool with general-purpose subagent]
Task: Extract and explain components in .ryanquinn3/ticketing/detailed-architecture.excalidraw.json

[Receives ~500 token summary with component list and relationships]
[Responds to user with architecture explanation, main context preserved]
❌ 错误做法（直接读取）：
用户："detailed-architecture.excalidraw.json中展示了什么架构？"
代理：让我读取这个文件... [将22k tokens加载到主上下文]
✅ 正确做法（子代理委托）：
用户："detailed-architecture.excalidraw.json中展示了什么架构？"
代理：我将使用子代理提取架构细节。

[通过任务工具分派给通用子代理]
Task: Extract and explain components in .ryanquinn3/ticketing/detailed-architecture.excalidraw.json

[收到约500 tokens的组件列表和关系摘要]
[向用户回复架构说明，主上下文得以保留]

Why "Straightforward JSON" Doesn't Matter

为什么“简单JSON”无关紧要

Agents often rationalize: "The format is simple, I can just read it."
The problem isn't complexity - it's verbosity:
  • Simple structure with 20+ properties per element
  • Repetitive metadata (seed, version, nonce, roughness)
  • Positioning data (x, y, width, height) not semantically useful
  • Visual styling (strokeColor, opacity, fillStyle) irrelevant to content
Token cost comes from volume, not complexity.
Even "straightforward" JSON consumes 4k-22k tokens because:
  • 79 elements × ~280 tokens/element = 22k tokens
  • Most tokens are metadata noise
  • Only text labels and relationships matter (~10% of content)
代理经常自我合理化：“格式很简单，我可以直接读取。”
问题不在于复杂性——而在于冗长性：
  • 简单结构但每个元素包含20+个属性
  • 重复的元数据（seed、版本、nonce、粗糙度）
  • 位置数据（x、y、宽度、高度）无语义价值
  • 视觉样式（描边颜色、透明度、填充样式）与内容无关
令牌成本来自体积，而非复杂性。
即使是“简单”的JSON也会消耗4k-22k tokens，原因如下：
  • 79个元素×约280 tokens/元素=22k tokens
  • 大多数令牌是元数据噪音
  • 只有文本标签和关系是关键内容（约占内容的10%）

The Iron Law

铁则

Main agents NEVER read Excalidraw files. No exceptions.
Not for:
  • "Quick checks"
  • "Small files"
  • "Understanding format"
  • "One-time analysis"
  • "Optimal efficiency"
Always delegate. Isolation is free via subagents.
主代理绝不读取Excalidraw文件。无例外。
即使是以下场景也不允许：
  • “快速检查”
  • “小型文件”
  • “理解格式”
  • “一次性分析”
  • “最优效率”
始终委托。通过子代理实现隔离毫无成本。