1DesignTool 里的大多数问题归结到少数几个原因——agent 缺失或没登 录、run 停滞、预览不渲染、门禁 FAIL,或额度用尽。这一页是每种情 况先看的地方。
agent 不在选择器里
应用在 PATH 上找支持的 CLI——和终端找的方式一样。
- 装了吗? 在终端里按名字跑那个 CLI(
claude、codex……) ——shell 找得到,应用就该找得到。 - 登录了吗? 选择器显示登录状态;缺登录是 CLI 自己的认证,不是 应用的。在 CLI 那边登录后重开。
- 在名单上吗? 16 个支持的 CLI 列在 支持的编码 agent——不在名单上 的 CLI 没法接进来。
run 停滞或失败
- 查 agent 的配额 ——轮次计在你 CLI 的账户上;用尽或过期的账户 会在 transcript 里明显地让 run 失败。
- 读 transcript ——agent 自己的输出在那儿;CLI 侧的错误以它本 来的样子显示,不是笼统的失败。
- 重试一次 ——CLI 的临时故障有时重试就好。持续失败的, transcript 会点名原因。
预览不渲染
- 预览默认拒绝 ——分类器不提供的文件类型渲染为空白而不是不安 全。这是安全底线,不是 bug。
- worktree 过期 ——在 codebase 项目上,预览读
1design/<slug>worktree;分支状态看起来怪时,先评审分支条的 diff 再怀疑渲染。 - 刷新面板 ——预览栏上的重载按钮重读文件夹;写了一半的文件 通常下一次绘制就好。
门禁 FAIL 清不掉
- 按该宽度修 ——FAIL 发现的修复按钮把恰好那个问题作为一行 brief 发回给 agent;发现点名宽度和元素,修复通常是机械操作。
- 按该宽度查 ——发现说明哪个视口坏了;先在那个宽度看结果,再 假定是规则错了。
- 有些发现是有意的 ——已知的取舍可以接受;门禁是建议,不是拦 截。见 design-kit 门禁。
额度拒绝 run
1design:limit: 拒绝会点名用尽的额度——免费档的轮次、渲染、版
本、variant 或设计系统。Settings → Usage 显示全部计量,归档
一个版本可以不带许可证就腾出槽位。额度是终身计数器;Pro 移除
它们。见 Free 与 Pro 对比。
Windows 上:EISDIR 报错(已知问题)
在 1.7.0 的 Windows 上,design-kit 脚本可能以 EISDIR 失败——
会弄坏 Knowledge、轮后检查、视频导出和 Build mode。这是已知 bug,
下个版本已修;macOS 上同样的流程不受影响。
MCP 客户端连不上
- 查访问面板 ——Settings → MCP access 显示端点、token 和 允许客户端列表;被拒的客户端通常不在列表上。
- 查 token ——面板里的 token 是客户端要发的;过期或错误的 token 会被拒。
- 查活动日志 ——日志显示什么到达了 server、什么没到。
先看哪里
- Transcript 面板 ——agent 的输出,逐字
- 分支条 ——在 codebase 项目上,这一轮实际改了什么
- Settings → Usage ——哪个计量用尽
- 活动日志 ——MCP 客户端实际做了什么
Tip: transcript 永远是第一读——agent 自己的输出是事情真相, 大多数"应用坏了"其实是"CLI 说了句什么,UI 翻译得太软"。