excalidraw

Excalidraw 子 Agent 委派

概述

核心原则： 主 Agent 绝不直接读取 Excalidraw 文件。始终委派给子 Agent，以隔离上下文消耗。

Excalidraw 文件是 JSON，token 成本高但信息密度低。单个文件范围为 4k-22k token（最大的可能超出读取工具限制）。读取多个图表会迅速耗尽上下文预算（7 个文件 = 67k token = 预算的 33%）。

问题所在

Excalidraw JSON 结构：

• 每个形状有 20+ 个属性（x、y、width、height、strokeColor、seed、version 等）
• 大多数属性是视觉元数据（定位、样式、粗糙度）
• 实际内容：文本标签和元素关系（<文件的 10%）
• 信噪比极低

示例：14 个元素的图表 = 596 行，16K，约 4k token。79 个元素的图表 = 2,916 行，88K，约 22k token（超出读取限制）。

何时使用

以下任一情况即触发：

• 文件路径包含 .excalidraw 或 .excalidraw.json
• 用户请求：“解释/更新/创建图表”、“展示架构”、“可视化流程”
• 用户提及：“流程图”、“架构图”、“Excalidraw 文件”
• 涉及视觉产物的架构/设计文档任务

即使对于以下情况也要使用委派：

• “小”文件（最小的也有 4k token —— 仍然可观）
• “快速检查”（检查组件名称仍会加载完整 JSON）
• 单个文件操作（隔离可防止上下文污染）
• 修改（无需在主上下文中理解完整格式）

委派模式

主 Agent 职责

绝不：

• ❌ 对 *.excalidraw 文件使用 Read 工具
• ❌ 在主上下文中解析 Excalidraw JSON
• ❌ 加载多个图表进行比较
• ❌ 检查文件以“理解格式”

始终：

• ✅ 将所有 Excalidraw 操作委派给子 Agent
• ✅ 向子 Agent 提供清晰的任务描述
• ✅ 请求纯文本摘要（而非原始 JSON）
• ✅ 将图表分析与主工作隔离

子 Agent 任务模板

读取/理解操作

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: 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: 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: 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

常见合理化借口（停下来，改为委派）

借口	现实	该怎么做
“直接读取最高效”	不必要地消耗 4k-22k token	委派给子 Agent
“直接读取更省 token”	基线测试显示使用 9-45% 预算	始终委派
“这对一次性分析是最优的”	“一次性”仍会污染主上下文	子 Agent 隔离
“JSON 很直白”	简单 ≠ token 高效	无论如何都要委派
“我需要理解格式”	主 Agent 不需要理解格式	子 Agent 处理格式
“在合理范围内”（18k token）	“合理”是主观的合理化借口	硬性规则：委派
“只是快速检查组件”	“快速检查”仍会加载完整 JSON	通过子 Agent 提取文本
“文件很小（16K）”	4k token 并不算小	大小阈值无关紧要

危险信号 —— 停下来并委派

发现你自己即将：

• 对 .excalidraw 文件使用 Read 工具
• “快速检查”存在哪些组件
• 在修改前“理解结构”
• 加载文件以“看看里面有什么”
• 并排比较多个图表
• 解析 JSON 以“只提取文本”

所有这些都意味着：改用带子 Agent 的 Task 工具。

快速参考

操作	主 Agent 动作	子 Agent 返回
理解图表	用“提取并解释”模板委派	组件列表 + 关系
修改图表	用“添加连接到 [Y] 的 [X]”模板委派	确认 + 所做更改
创建图表	用“创建展示 [描述] 的图表”模板委派	文件位置 + 摘要
比较图表	用“比较 [A] 与 [B]”模板委派	关键差异（而非原始 JSON）

Token 分析（为什么这很重要）

基线测试的真实数据：

场景	不委托	委托	节省
单个大文件	22k tokens（45% 预算）	~500 tokens（子 Agent 摘要）	98%
双文件对比	18k tokens（9% 预算）	~800 tokens（diff 摘要）	96%
修改任务	14k tokens（7% 预算）	~300 tokens（确认）	98%

上下文污染的影响：

• 阅读全部 7 个项目图表：67k tokens（200k 预算的 33%）
• 委托后：~2k tokens（隔离在子 Agent 中）
• 节省：保留了 97% 的上下文预算

实现示例

❌ 错误（直接读取）：

User: "What architecture is shown in detailed-architecture.excalidraw.json?"
Agent: Let me read that file... [reads 22k tokens into main context]

✅ 正确（子 Agent 委托）：

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]

为什么“直白的 JSON”并不重要

Agent 常常自我辩解：“格式很简单，我直接读就行。”

问题不在于复杂度，而在于冗长程度：

• 简单结构，每个元素却有 20+ 个属性
• 重复的元数据（seed、version、nonce、roughness）
• 定位数据（x、y、width、height）在语义上没有用处
• 视觉样式（strokeColor、opacity、fillStyle）与内容无关

Token 成本来自数据量，而不是复杂度。

即使是“直白”的 JSON 也会消耗 4k-22k tokens，因为：

• 79 个元素 × 每个元素约 280 tokens = 22k tokens
• 大部分 token 都是元数据噪声
• 只有文本标签和关系才重要（约占内容的 10%）

铁律

主 Agent 绝不读取 Excalidraw 文件。没有例外。

不适用于：

• “快速检查”
• “小文件”
• “理解格式”
• “一次性分析”
• “最优效率”

始终委托。通过子 Agent 实现隔离是零成本的。