name: avocado-router
description: Use as the entry router when a user mentions avocado (the Figma-to-JSX CLI) or related antd tooling but their intent is ambiguous or spans multiple skills — e.g. "avocado 怎么用", "不知道选哪个 skill", "avocado 能干什么", "avocado 总览", "帮我看看 avocado", "avocado 有哪些能力", "先告诉我用哪个", "avocado 整体架构", "avocado workflow", "组件库组件怎么用", "antd", or any avocado/antd-related request that doesn't clearly map to a single sub-skill. Also triggers for first-time users asking "怎么开始 / 要配置什么 / 环境好了吗" (routes to path-config's environment checklist). Routes to the right one of: avocado-d2c (生成 JSX), avocado-path-config (路径/配置), avocado-component-adapter (组件库适配：preset + 插件). Also points to companion CLI antd (查询组件库 Props/demo/doc) when the question is about antd component library. If the user's intent is already specific (e.g. explicit "转 JSX" / "改 preset"), let the corresponding sub-skill trigger directly instead of this router.
avocado-router
avocado skill 群的总控路由。用户提到 avocado 但意图模糊时，用本 skill 判断该走哪个子 skill。
avocado 主包只提供 d2c（设计转代码）能力：avocado <figma-url> → JSX/CSS。
何时触发本 skill（路由器场景）
- 用户问"avocado 是什么 / 怎么用 / 能干什么 / 有哪些能力"
- 用户描述了问题但不知道对应哪个 skill（"我不确定该用哪个"）
- 用户的需求跨多个 skill（如"改 preset 后再生成验证"= avocado-component-adapter + d2c）
- 用户给一个模糊的 figma URL 说"帮我搞一下"
- 新用户开局问"我需要配置什么 / 环境好了吗 / 怎么开始"（路由到 path-config 的环境检查）
新用户开局流程（最常见的入口）
用户第一次接触 avocado 通常会问"我要配置什么？"。标准流程：
1. 环境就绪检查（path-config 的"环境检查清单"段）
✅ avocado CLI → avocado --version
✅ FIGMA_TOKEN → ~/.avocado/config.yaml 或 env
✅ ~/.avocado/ 目录 → 首次运行自动创建（ensure_user_dirs）
2. 冒烟测试
avocado "<figma-url>" -o /tmp/out.jsx
何时不触发（让子 skill 直接接）
明确意图的话术直接路由到子 skill，不要经总控：
| 用户原话（示例） | 直接路由到 |
|---|
| "把这个 Figma 转成代码" / "生成 JSX" / "导出" | avocado-d2c |
| "preset 放哪" / "找不到资源" / "改输出目录" | avocado-path-config |
| "加组件" / "antd.yaml" / "leaf 字段" / "blockNameMatch" / "写插件" | avocado-component-adapter |
3 个子 skill 导航
avocado-d2c — Figma URL → JSX 生成
核心职责：把 Figma URL 转成 JSX + CSS（avocado <url> 主命令）。
典型场景：
- 用户给 figma URL 想要 React / HTML / Tailwind 代码
- 选 flag 组合（format / css / layout / component-lib）
- preset 打包（
--preset designer HTML 预览 / --preset dev react+tailwind，组件库需显式 --component-lib）
- 处理 envelope error code
- 加速回归（cache/offline 模式）
关键约束：stdout 永远是 JSON envelope；error code 详见
avocado schema；输出必须确定性。
avocado-path-config — 路径与配置体系
核心职责：avocado 的资源路径解析（4 层查找）+ 用户配置（~/.avocado/）。
典型场景：
- 用户问"preset 放哪 / 怎么自定义"
- "file not found" for antd.yaml / var-maps/antd.yaml
- 改输出目录 / 自定义组件库预设
- 验证 wheel 资源完整
关键约束：4 层查找单一真相源；不要硬编码
Path(__file__).parents[N]；token 4 层查找（CLI > env > cwd/.avocado 项目级 > ~/.avocado 用户级）。
avocado-component-adapter — 组件库适配（preset + 插件）
核心职责：维护 antd.yaml 等组件映射文件 + 编写配套识别/提取插件。
典型场景：
- 加新组件到预设
- INSTANCE 识别不到（Figma name 不匹配 / compId 没收录）
- 加叶子组件（LabeledInput 等） / extractor
- blockNameMatch / variant / dynamicProps 字段问题
关键约束：ComponentMapping 9 字段（YAML camelCase ↔ Python snake_case）；blockNameMatch 数据驱动保护；leaf 字段判定（Button 不加，LabeledInput 加）；extractor 静默失败是合法降级。
路由决策树
用户请求
│
├─ 模糊/总览/跨多 skill？
│ → 停在本 skill，用上面的导航表给建议
│
├─ 提到 figma URL + "转代码/生成/导出"？
│ → avocado-d2c
│
├─ "preset/designer/dev/预览模式"？
│ → avocado-d2c
│
├─ "路径/放哪/找不到/preset 位置/wheel"？
│ → avocado-path-config
│
├─ "加组件/antd.yaml/识别不到/leaf/variant/写插件"？
│ → avocado-component-adapter
│
├─ "组件库组件怎么用 / Props / demo / 项目里用了哪些组件"？
│ → 直接查组件库官方文档；avocado 只负责 Figma → 代码映射
│
└─ 都不像？
→ 看下方"常见组合场景"，或者直接 `avocado schema` 自省 CLI 能力
常见组合场景（跨 skill 工作流）
场景 A：从零生成代码
- avocado-d2c → 生成 JSX（
avocado <url> -o out.jsx）
场景 B：加新组件到 组件库预设
- avocado-component-adapter → 编辑 antd.yaml + 加 extractor / 写插件
- avocado-d2c → 单页生成验证
场景 C：用户 pip install 后跑不起来
- avocado-path-config → 检查 4 层查找
- 若路径正常但仍报错 → 看 envelope error code（详见
avocado schema）
场景 D：查 组件库 Props / 示例
用户问"组件库 Button 有哪些 Props" / "LabeledInput 怎么用" / "项目里用了哪些 组件库组件" → 不要用 avocado skill：avocado 只做 Figma → 代码转换，不提供组件库文档。直接查阅组件库官方文档 / 源码。
共同约束（所有子 skill 都遵守）
envelope 契约
所有 avocado CLI 命令的 stdout 都是 JSON envelope：
{"ok": true, "data": {...}} / {"ok": false, "error": {"code", "message", "hint"}}
退出码：0=ok / 1=业务错误 / 2=参数错误。
输出确定性
d2c 输出必须确定性（同输入同输出）。改任何"迭代后决定 style 插入顺序"的集合用 tuple 不用 frozenset。
pipeline pass 实际顺序
── 5 个可选 style/structure pass ──
1. auto_group_variance → 2. inherit_promote → 3. strip_default_styles
→ 4. unwrap_single_child → 5. gap_to_margin
── always-on ──
6. semantic_tags
── 输出形态 ──
7. tailwind → 8. css_class → 9. reround
顺序不可乱（详见项目根 CLAUDE.md）。
路径解耦
所有资源路径走 avocado.paths.resolve_*() 4 层查找。不要硬编码 Path(__file__).parents[N]。
还是不确定？自省 CLI
如果用户的请求连总控都判断不了，让 agent 跑一次 schema 自省：
avocado schema
stdout 是 JSON envelope，含所有命令清单 + flags + error code 字典。这是 avocado CLI 能力的单一真相源（实现 in avocado/commands/schema.py:_SPEC）。
真相源
- 项目根
CLAUDE.md — 设计决策全貌
avocado schema 命令 — 自省 CLI 能力（envelope 格式 + error code 字典）docs/agent-integration.md — agent 调用 avocado 标准流程
