fe-code2skill

扫描前端仓库页面逻辑，提炼业务场景，生成专业可执行的业务 Skill。

核心理念：不是翻译代码，而是读懂业务意图。

生成的 Skill 要像一个熟悉业务的同事写的操作手册，而不是接口文档的堆砌。

Step 1：确认 CLI 基础

生成的 Skill 必须基于已有的 CLI 工具，这是硬性前提。Skill 里的每一步操作都通过 CLI 命令执行，不内联 HTTP 请求。原因：

• CLI 已经处理好了鉴权、枚举翻译、错误处理，Skill 不需要重复实现
• CLI 命令可读性强，用户能看懂 Skill 在做什么
• 接口变更时只需更新 CLI，所有依赖它的 Skill 自动受益

首先确认用户是否已有 CLI：

> 你是否已经有可用的业务 CLI 工具？如果有，CLI 名称是什么？

情况 A：已有 CLI

确认 CLI 名称（如 my-shop-cli），运行 --help 看一下有哪些命令，进入 Step 2。

情况 B：没有 CLI

必须先生成 CLI，再来生成 Skill。 告知用户：

生成业务 Skill 需要先有对应的 CLI 工具。
请先生成 CLI（可通过分析前端 API 定义自动生成），完成后回来继续。

等用户生成完 CLI 并确认可用后，再继续 Step 2。不提供跳过选项。

Step 2：收集仓库信息 & 读取 CLI 命令清单

2.0 先读 CLI 的完整命令清单（必须）

在扫描仓库之前，先把 CLI 有哪些命令搞清楚。 生成的 Skill 里的每一步操作都要对应到真实存在的 CLI 命令，不能用不存在的命令。

# 查看所有顶层命令
<cli-name> --help

# 逐一查看每个子命令的参数
<cli-name> <domain> --help
<cli-name> <domain> <action> --help

如果 CLI 未安装，先安装再继续：

npm install -g <cli-name>      # Node.js CLI
pip3 install <cli-name>        # Python CLI

安装后重新运行 --help 确认可用。如果安装失败，告知用户并停止——不能在没有 CLI 命令清单的情况下继续生成 Skill。

读完 --help 后，整理出一张命令清单：

<cli-name> 可用命令：
  auth show / refresh
  product list   --status --type --page --page-size
  product get    <id>
  product create --name --type --start-date --end-date
  order list      --status --start-date --end-date
  order get       <id>

后续生成 Skill 时，只能使用这张清单里存在的命令和参数。

2.1 收集仓库信息

向用户确认（消息中已有则直接使用）：

• 仓库路径：前端仓库本地路径，可多个
• 重点业务方向（可选）：如"订单管理"、"用户中心"，没有则扫全部页面

Step 3：扫描仓库，提炼业务场景

> 核心原则：三层漏斗，以 CLI 为锚点。

> 不要完整读每个页面文件——一个页面 500~2000 行，真正有业务价值的不超过 20%。

> 第一层宽网扫出所有操作入口 → 第二层只精读有价值的 handler 函数体 → 第三层与 CLI 命令清单对齐。

3.1 第一层：宽网扫描，建立业务全貌

目标：不读完整文件，只用搜索工具快速拿到三类高密度信息。

① 路由文件（最高密度，必读）

路由文件几十行，直接告诉你所有页面、业务模块划分、页面层级关系。用 codebase_search 搜索 "route configuration" 或 glob_file_search 搜索 router./routes.，找到后完整读取。

读完路由后，整理出页面清单：

页面清单：
  /product/list     → 商品列表页
  /product/create   → 创建商品页
  /order/list       → 订单列表页
  /order/detail/:id → 订单详情页

② 事件处理函数名（操作入口）

函数名本身就是业务语言，handleCreateProduct 比读 200 行代码更直接。用 grep 工具搜索：

pattern: const handle[A-Z]|function handle[A-Z]|const on[A-Z]|async handle[A-Z]
glob: *.{tsx,vue,ts}

整理出操作清单（按页面分组）：

操作清单：
  商品管理页：
    handleQueryList       → 查询商品列表
    handleCreateProduct   → 创建商品
    handleUpdateStatus    → 修改商品状态
    handleDeleteProduct   → 删除商品

③ API 调用与函数调用顺序（步骤链路）

pattern: await.*api\.|await.*service\.
glob: *.{tsx,vue,ts}

3.2 第二层：读参数定义 + 读参数来源

子步骤 A：读 CLI --help，拿到参数完整定义

对每个操作逐一运行 CLI 子命令 --help，提取：参数名、是否必填、枚举值及含义、默认值。

子步骤 B：读 handler 函数体，搞清楚参数的值从哪来

用 grep 定位函数起始行，再用 read_file 精读那几十行。只关注五件事：

1. 参数来源：用户输入 / 路由参数 / 上一步返回值 / 全局状态 / 场景标识参数（最容易漏——同一接口被多场景复用时，后端靠此参数区分，如 queryScene: 'MANAGE'）。发现场景标识必须核查 CLI 是否已固定写入。
2. 前置条件：函数开头的 if 判断 → Skill 的前置检查步骤
3. 调用顺序：多个 await 的先后关系 → Skill 的步骤编排
4. 用户确认点：Modal.confirm、Dialog、confirm() → Skill 的确认步骤
5. 错误处理：catch 块里的 message.error(...) → Skill 的错误处理说明

跳过：JSX/template 渲染、CSS、loading 状态、UI 组件 props。

合并输出参数表：

操作：创建商品（handleCreateProduct）
CLI 命令：<cli-name> product create

参数表：
  --name       必填  用户输入（formData.name）
  --type       必填  用户选择（枚举：1=实体 2=虚拟）
  --shop-id    可选  自动读取全局状态，不需要问用户

前置条件：必须已选店铺
用户确认：有（Modal.confirm "确认创建商品？"）
错误处理：商品名称重复时提示"商品名称已存在"

3.3 第三层：与 CLI 命令清单对齐（关键）

把操作清单和 CLI 命令清单做映射：

• ✅ 有对应 CLI 命令 → 正常生成 Skill 步骤
• ❌ CLI 没有对应命令 → 不生成该步骤，在 Step 4 方案里标注"CLI 暂不支持"

3.4 业务语义提炼 & Skill 类型判断

整理每个页面的业务语义：页面名称、业务场景、用户角色、可执行操作列表（只列有 CLI 对应的）、操作间依赖。

根据操作特征判断 Skill 类型：

3.5 Skill 粒度决策：一个 Skill = 一个用户意图

核心原则：以用户会说什么话来划分，而不是以页面模块或接口来划分。

❌ 错误（按接口分组太细）：用户说"查商品"，AI 不知道触发哪个
✅ 正确（按用户意图分组）：一个"商品查询" Skill 覆盖多个子查询维度

经验值：3~5 个 Skill 覆盖一个业务模块。

Step 4：输出 Skill 生成方案，等用户确认

列出将要生成的所有 Skill：

📋 发现以下业务场景：

页面：商品管理（src/pages/product/）
  ✅ [查询型] 查看商品列表     → <cli-name> product list
  ✅ [操作型] 创建商品         → <cli-name> product create
  ✅ [分析型] 分析销售效果     → <cli-name> product stats
  ✅ [流程型] 商品全流程       → create → update --status active

🚫 CLI 暂不支持：
  - 删除商品（handleDeleteProduct）→ CLI 缺少 product delete 命令

将生成 N 个 Skill，是否继续？

Step 5：生成 Skill MD 文档

5.1 文件命名规范

~/.catpaw/skills/<cli-name>-<domain>-<action>/SKILL.md

5.2 生成质量原则

1. 不写模板，写具体内容：不能有任何占位符（<参数>、<值>），每行必须是真实内容
2. 触发词精确，避免互相干扰：包含动作 + 业务对象 + 限定词，并注明"不适用于"哪些场景
3. Skill 头部必须有自描述："我能做什么 / 我不能做什么 / 前提条件"
4. 参数收集要有业务语境：用自然语言询问，带枚举选项说明，不罗列技术类型
5. 错误处理说人话：给出具体修复命令，不写 | 401 | run auth refresh |
6. 成功后给出具体下一步命令：不泛泛说"可以修改"，而说"修改命令： update "
7. 字段含义必须代码+页面双重验证：不能靠字段名猜，要从渲染逻辑和真实数据两方面确认

5.3 四种 Skill 模板

四种类型（查询型 / 操作型 / 分析型 / 流程型）的完整模板见 templates.md。

生成时，按对应模板填充具体业务内容，确保：

• 前置条件部分根据 CLI 实际能力调整（如不需要认证则去掉登录检查）
• 参数收集部分用真实枚举值和业务语言
• 错误处理部分用 CLI 实际会返回的错误信息

Step 6：保存 Skill 文件

mkdir -p ~/.catpaw/skills/<skill-name>
# 写入 ~/.catpaw/skills/<skill-name>/SKILL.md

输出汇总：

✅ 已生成 N 个 Skill：
  ~/.catpaw/skills/my-shop-product-create/SKILL.md
  ~/.catpaw/skills/my-shop-product-analysis/SKILL.md

附：AI 读代码的正确姿势

重点读：函数名、API 调用顺序、if/else 业务判断、注释、TypeScript 类型定义

跳过：CSS 类名、组件渲染逻辑、纯 UI 状态（isLoading）、第三方组件 props