概述
Excalidraw 子智能体委派技能的核心原则是：主智能体绝不直接读取 Excalidraw 文件，始终将操作委派给子智能体，以隔离上下文消耗。
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）；
- 单文件操作（隔离可防止上下文污染）；
- 修改操作（主上下文不需要完整格式理解）。
委派模式
主智能体职责
绝不：
- 对 *.excalidraw 文件使用 Read 工具；
- 在主上下文中解析 Excalidraw JSON；
- 加载多个图表进行比较；
- 检查文件以“理解格式”。
始终：
- 将所有 Excalidraw 操作委派给子智能体；
- 向子智能体提供清晰的任务描述；
- 请求纯文本摘要（而非原始 JSON）；
- 将图表分析与主工作隔离。
子智能体任务模板
读取/理解操作
任务：提取并解释 [file.excalidraw.json] 中的组件
方法：1. 读取 Excalidraw JSON；2. 仅提取文本元素（忽略定位/样式）；3. 识别组件之间的关系；4. 总结架构/流程。
返回：组件/服务列表及其描述；连接/依赖关系；关于架构的关键洞察；不要返回原始 JSON 或冗长的元素细节。
修改操作
任务：将 [component] 添加到 [file.excalidraw.json]，连接到 [existing-component]
方法：1. 读取文件以识别现有元素；2. 找到 [existing-component] 及其位置；3. 为 [component] 创建新元素 JSON；4. 添加箭头元素表示连接；5. 写入更新后的文件。
返回：所做更改的确认；新元素的位置；所创建元素的 ID。
创建操作
任务：创建新的 Excalidraw 图表，展示 [description]
方法：1. 为 [number] 个组件设计布局；2. 创建带文本标签的矩形元素；3. 添加表示关系的箭头；4. 使用一致的样式（颜色、字体）；5. 写入 [file.excalidraw.json]。
返回：文件已创建的确认；所包含组件的摘要；文件位置。
比较操作
任务：比较 [file1] 与 [file2] 中的架构方法
方法：1. 读取两个文件；2. 从每个文件中提取文本标签；3. 识别结构差异；4. 比较组件关系。
返回：架构中的关键差异；各自独有的组件；关系/流程差异；不要返回两个文件的完整元素细节。
常见借口（停止并改为委派）
- 借口“直接读取最高效”——实际上不必要地消耗 4k-22k token，应委派给子智能体；
- 借口“直接读取更省 token”——基线测试显示占用 9%-45% 预算，始终委派；
- 借口“这是一次性分析的最优方式”——“一次性”仍会污染主上下文，使用子智能体隔离；
- 借口“JSON 很直接”——简单不等于 token 高效，仍然委派；
- 借口“我需要理解格式”——主智能体不需要格式理解，子智能体处理格式；
- 借口“在合理范围内”（18k token）——“合理”是主观借口，硬性规则：委派；
- 借口“只是快速检查组件”——“快速检查”仍加载完整 JSON，通过子智能体提取文本；
- 借口“文件很小（16K）”——4k token 不算小，大小阈值无关紧要。
红色警报——停止并委派
当你发现自己即将：
- 对 .excalidraw 文件使用 Read 工具；
- “快速检查”存在哪些组件；
- 在修改前“理解结构”；
- 加载文件以“看看那里有什么”；
- 并排比较多个图表；
- 解析 JSON 以“仅提取文本”。
所有这些都意味着：改用 Task 工具配合子智能体。
快速参考
| 操作 | 主智能体动作 | 子智能体返回 |
|---|---|---|
| 理解图表 | 用“提取并解释”模板委派 | 组件列表 + 关系 |
| 修改图表 | 用“添加 [X] 连接到 [Y]”模板委派 | 确认 + 所做更改 |
| 创建图表 | 用“创建展示 [description]”模板委派 | 文件位置 + 摘要 |
| 比较图表 | 用“比较 [A] 与 [B]”模板委派 | 关键差异（非原始 JSON） |
Token 分析（为什么这很重要）
基线测试的真实数据：
| 场景 | 不委派 | 委派后 | 节省 |
|---|---|---|---|
| 单个大文件 | 22k token（45% 预算） | 约 500 token（子智能体摘要） | 98% |
| 双文件比较 | 18k token（9% 预算） | 约 800 token（差异摘要） | 96% |
| 修改任务 | 14k token（7% 预算） | 约 300 token（确认） | 98% |
上下文污染影响：
- 读取全部 7 个项目图表：67k token（200k 预算的 33%）；
- 使用委派：约 2k token（隔离在子智能体中）；
- 节省：保留 97% 的上下文预算。
实现示例
错误（直接读取）：
用户：“detailed-architecture.excalidraw.json 中展示了什么架构？” 智能体：让我读取那个文件……[将 22k token 读入主上下文]
正确（子智能体委派）：
用户：“detailed-architecture.excalidraw.json 中展示了什么架构？” 智能体：我将使用子智能体提取架构详情。
[使用 Task 工具分发 general-purpose 子智能体] 任务：提取并解释 .ryanquinn3/ticketing/detailed-architecture.excalidraw.json 中的组件
[收到约 500 token 的摘要，包含组件列表和关系] [向用户回复架构说明，主上下文得以保留]
为什么“直接了当的 JSON”无关紧要
智能体常辩解：“格式很简单，我可以直接读。”
问题不在于复杂度，而在于冗长：
- 简单结构，每个元素有 20 多个属性；
- 重复的元数据（seed、version、nonce、roughness）；
- 定位数据（x、y、width、height）在语义上无用；
- 视觉样式（strokeColor、opacity、fillStyle）与内容无关。
Token 成本来自体量，而非复杂度。
即使“直接了当”的 JSON 也会消耗 4k-22k token，因为：
- 79 个元素 × 约 280 token/元素 = 22k token；
- 大部分 token 是元数据噪声；
- 只有文本标签和关系重要（约内容的 10%）。
铁律
主智能体绝不读取 Excalidraw 文件。没有例外。
不适用于：
- “快速检查”；
- “小文件”；
- “理解格式”；
- “一次性分析”；
- “最优效率”。
始终委派。通过子智能体实现隔离是零成本的。