用途
该技能用于诊断 Design Agent 在各类环节中出现的失败，包括初始设置、一次渲染、一次部署、Slack 集成或模型调用等。核心原则是：报告缺失的设置时只说明名称，绝不粘贴密钥、令牌或 .env 内容。
主要能力
- 自检：
uv run design-agent doctor（加--json便于解析）会检查每个模型角色、密钥、品牌配置、沙箱、MDA 声明、MCP 与 Paper，优先修复它指出的问题。 - 真实调用测试：
uv run design-agent test model、test sandbox、test paper、test slack、test db，每次会产生少量费用（几美分）。 - 日志：MDA 上用
uv run mda logs；自托管时用docker compose -f deploy/self-host/compose.yaml logs api。日志只包含异常类，不含提供方消息或密钥。 - 轨迹：每次运行都在 LangSmith 中留痕，MDA 部署的项目名为
<deployment>-production。可借助 langsmith-trace 技能，把一个出错的文件回溯到技能读取、工具调用与检查执行过程；API 运行会把交付文件附到轨迹上。已部署的智能体也能读取自己的轨迹（list_traces、read_trace），可直接在对话线程中询问它出了什么问题。 - 真实缺陷处理：先用一个失败的测试复现问题，再修改代码，并遵循 AGENTS.md。
常见症状与处理
- demo 需要沙箱：启动 Docker，然后执行
uv run design-agent sandbox build。 - 渲染缺少字体：执行
uv run design-agent fonts verify；fonts.toml 中的 family 必须是文件内部的名称。 - 配色不符合品牌或品牌检查失败：执行
uv run design-agent brand validate，再执行brand css。 - 提示“与模型的连接停滞”或“持续不可用”：检查提供方状态，然后在线程中回复 continue。
- MDA 上的后台新闻晚到一两分钟：属预期，MDA 调度落在下一分钟。
- 提示“重启可能停止了……”：部署或重启中断了辅助进程，请让智能体恢复它们。
- Paper“未连接”：Paper Desktop 已关闭或桥接不可用；看板仍可在沙箱中渲染。
mda deploy时沙箱烘焙磁盘不足：先执行uv run design-agent sandbox publish。- 提示“Context Hub 只接受 UTF-8 文本文件”：把技能中的二进制文件移到
skill-binaries/<skill>/。 - 提示“source archive … exceeds the 200 MB limit”：清理
workspace/out/中的旧渲染产物。 - MCP 服务缺失：启动日志会指出失败的那一个，其余服务继续工作。
适用场景与限制
适用于维护和排查 Design Agent 部署的人员。部分测试命令会产生实际调用费用；日志与轨迹的具体内容取决于部署配置，资料未提供更多细节。