Ant Design 列表页生成工作流

本 skill 定义列表页的生成流程，不包含组件 API 或代码规范细节。规范和模板由项目文件和组件 skill 承载。

触发词

生成列表页、新建表格页、增删改查页面、列表页开发

依赖

> 若依赖 skill 未安装，仅按项目规范文件生成，不猜测未知的组件属性。

文件位置约定

所有工作流产生的临时文件统一存放在项目根目录 .aicode/tmp/ 下，按类型分目录：

> .aicode/ 目录已在 .gitignore 中，不会提交到仓库。所有临时文件集中在 .aicode/tmp/ 下，方便整体清理。

工作流注册表

为什么需要注册表

.aicode/ 是隐藏目录，ExactSearch 和 RepoStruct 对隐藏目录索引支持差，无法可靠搜索其中的文件。因此需要一个已知路径的注册表文件，断点续接时直接用 ReadFile 读取，不依赖文件搜索。

此外，多个工作流可能同时运行（如列表页工作流、详情页工作流），注册表可以统一追踪所有工作流的进度。

注册表结构

文件路径：.aicode/tmp/workflow-registry.json

{
  "workflows": [
    {
      "id": "antd-list-page",
      "name": "Ant Design 列表页生成",
      "pages": [
        {
          "pageName": "DeptManagement",
          "displayName": "部门管理",
          "specPath": ".aicode/tmp/page-specs/DeptManagement.md",
          "step": 2,
          "stepStatus": "done",
          "updatedAt": "2026-05-11"
        }
      ]
    }
  ]
}

字段说明：

注册表操作规则

读取注册表：断点续接时，直接用 ReadFile 读取 .aicode/tmp/workflow-registry.json。

⚠️ 重要：由于 .aicode/ 是隐藏目录，禁止使用 ExactSearch 或 RepoStruct 搜索其中的文件。必须使用以下方式之一：
1. ReadFile 直接读取已知路径的文件（首选）
2. RunCommand + find 命令搜索（路径不确定时使用）

创建/更新注册表：
- 工作流首次启动时，若注册表文件不存在，创建并写入初始数据
- 若注册表已存在但无本工作流条目，追加到 workflows 数组
- 若注册表已存在且已有本工作流条目，更新对应 page 的 step、stepStatus、updatedAt
- 每次更新 spec 文件的 frontmatter 时，必须同步更新注册表

删除页面：当用户要求删除某个页面时，从注册表中移除对应 page 条目，同时删除对应的 spec 文件。

临时文件清理

所有临时文件集中在 .aicode/tmp/ 下，支持以下清理方式：

自动清理规则：
- 当工作流 Step 3 完成（代码已生成）后，spec 文件仍保留，作为代码生成的记录和回溯依据
- 用户可随时要求清理已完成或废弃的工作流文件
- 清理注册表条目时，必须同步删除对应的 spec 文件，避免孤儿文件

断点续接

Spec 文件元数据

每个页面描述文件（.aicode/tmp/page-specs/{PageName}.md）必须包含 YAML frontmatter 元数据，记录工作流状态：

---
workflow: antd-list-page
pageName: DeptManagement
displayName: 部门管理
step: 1
stepStatus: done
updatedAt: 2026-05-11
---

# {页面名称}

## 页面信息
...

字段说明：

状态流转：

续接触发规则

当用户提到某个页面名称时：
1. 用 ReadFile 读取 .aicode/tmp/workflow-registry.json
2. 在注册表中按 displayName 或 pageName 匹配页面
3. 根据 id 字段确认属于哪个工作流
4. 根据 step + stepStatus 判断续接点
5. 用 ReadFile 读取 specPath 指向的 spec 文件，获取完整页面描述
6. 向用户确认当前状态后继续执行

多工作流场景：如果注册表中有多个工作流的页面与用户描述匹配，列出所有匹配项让用户选择。

注册表不存在或页面未找到：视为新任务，从 Step 1 开始。

元数据更新规则

• Step 完成时：同步更新 spec 文件的 frontmatter 和注册表中对应 page 的 step、stepStatus、updatedAt
• Step 开始时：将 stepStatus 设为 in-progress，同步更新两处
• 用户确认后：将 stepStatus 设为 done，step 推进到下一步，同步更新两处
• 原则：spec frontmatter 和注册表必须保持一致，任何状态变更都双写

工作流

Step 1：需求解析

将产品策划/需求文档转为结构化的页面描述，输出为 Markdown 文件。

输入：用户提供的策划内容（文字、截图、文档链接等）

输出：.aicode/tmp/page-specs/{PageName}.md，包含以下结构：

> ⚠️ Spec 格式权威声明：下方模板定义的 spec 格式为本工作流的权威格式。page-spec-parser skill 的 page-spec-schema.md 仅作为解析阶段的参考（字段语义、推断规则、标注规范等），最终产出物的表格结构、列定义必须严格对齐下方模板，不得混用其他格式。

---
workflow: antd-list-page
pageName: {PageName}
displayName: {页面中文名}
step: 1
stepStatus: in-progress
updatedAt: 2026-05-11
---

# {页面名称}

## 页面信息
- 模块：
- 路由路径：
- 主键字段：

## 表格列

| 字段 | 标题 | valueType | 搜索 | width | 备注 |
|------|------|-----------|------|-------|------|

## 弹窗字段

| 字段 | 标题 | valueType | 必填 | width | 备注 |
|------|------|-----------|------|-------|------|

## 操作

| 类型 | 操作名 | 触发位置 | 关联接口 |
|------|--------|---------|---------|

## 接口

| 操作 | 接口路径 | 请求方式 | 备注 |
|------|---------|---------|------|

规则：
- valueType 根据字段语义推断（文本→text，状态→select，时间→dateTime，数字→digit 等）
- 搜索列标记 ✅ 或 ❌
- 弹窗字段与表格列有重叠时，分别描述，可能搜索可见性不同
- 输出后必须让用户确认，确认后将 stepStatus 更新为 done，再进入下一步

Step 2：接口采集

从 YApi 采集接口定义，补充 Step 1 中的接口信息。

核心原则：接口信息以 YApi 采集结果为准，覆盖 Step 1 中的推断内容。

Step 1（策划解析）的输出完全以策划文档为主，接口路径等可能为空或标注"待接口采集"。
Step 2（接口采集）的输出完全以 YApi 实际接口为准，用真实数据替换所有推断和占位内容。

输入：Step 1 输出的页面描述 + YApi 接口 URL 或关键词

输出：更新 .aicode/tmp/page-specs/{PageName}.md 中的接口表、字段名、操作关联等

2.1 接口清单推导

根据 spec 中的字段和操作，推导页面所需的完整接口清单，包含显式接口和隐式接口。

显式接口：spec 接口表中已列出的接口（如列表、保存、状态切换）。

隐式接口推导决策清单：

按以下顺序逐项检查 spec，每项命中则执行对应动作：

清单 A：弹窗字段检查（遍历每个弹窗字段）

对于每个弹窗字段:
  if valueType == 'select' 或 'radio':
    if 备注含"远程请求"或"数据来源":
      → 推导下拉数据源接口，备注记录来源（如"负责人 → 用户列表下拉接口"）
    elif 备注含明确枚举值（如"0-禁用，1-启用"）:
      → 无需额外接口，枚举前端写死
    else:
      → 标记「需确认」：枚举前端写死 or 拉字典接口？

  if valueType == 'select' 且 fieldProps 含 mode: 'multiple':
    → 同上 select 逻辑，不影响推导规则

  if 字段有联动说明（如"选择省后加载市"）:
    → 推导每级联动的数据源接口

清单 B：操作检查（遍历每个操作）

对于每个操作:
  if 操作名 == '编辑':
    if 列表接口响应字段已包含弹窗所需全部字段:
      → 不需要详情接口
    else:
      → 推导详情接口（编辑回填用）

  if 操作名 == '删除' 且 接口表中无删除接口:
    → 推导删除接口

  if 操作名 == '导出' 且 接口表中无导出接口:
    → 推导导出接口

  if 操作名 == '导入' 且 接口表中无导入接口:
    → 推导导入接口 + 模板下载接口

清单 C：表格列检查（遍历每个表格列）

对于每个表格列:
  if valueType == 'select' 或 'radio':
    if 备注含明确枚举值:
      → 无需额外接口
    elif 弹窗字段中已有同字段的下拉数据源推导:
      → 复用，不重复推导
    else:
      → 标记「需确认」：枚举前端写死 or 拉字典接口？

推导边界：
- 只推导列表页自身需要的接口，不推导关联页面的接口
- 已在清单 A 推导过的下拉数据源，清单 C 中复用，不重复推导

输出：一份完整的接口清单，标注每个接口的来源（显式/隐式推导），供用户确认。

2.2 用户确认清单

将推导出的接口清单展示给用户，包含：
- 显式接口（来自 spec 接口表）
- 隐式接口（来自推导规则）
- 需要用户确认的歧义项（如枚举前端写死 or 字典接口）

用户确认后才能继续。用户可以：
- 删除不需要的接口
- 补充遗漏的接口
- 确认歧义项的处理方式

2.3 检查本地已有接口文档

在搜索 YApi 之前，先检查 .aicode/tmp/api-docs/ 下是否已有相关接口文档。

检查方式：
1. 列出 .aicode/tmp/api-docs/ 下所有 .md 文件
2. 读取文件内容，检查是否包含清单中的接口（按接口路径或标题匹配）
3. 已存在的接口标记为"已采集"，跳过 YApi 搜索

复用规则：
- 已采集的接口直接复用，不重新采集
- 若用户要求刷新，则重新采集覆盖

2.4 YApi 搜索采集

按接口清单逐个搜索 YApi，使用 api-doc-scraper skill 的 yapi-search.js 脚本。

搜索关键词推导：

每个接口需要推导一组搜索关键词，按优先级排列：

搜索策略（单接口最多 3 轮）：

第 1 轮：优先级 1+2 的中文关键词
  → 搜到唯一结果 → 直接使用
  → 搜到多个结果 → 进入歧义消解
  → 搜到 0 个结果 → 进入第 2 轮

第 2 轮：优先级 3 的路径关键词
  → 搜到唯一结果 → 直接使用
  → 搜到多个结果 → 进入歧义消解
  → 搜到 0 个结果 → 进入第 3 轮

第 3 轮：优先级 4+5 的补充关键词
  → 搜到结果 → 使用
  → 搜到 0 个结果 → 标记为"未找到"，不再搜索

歧义消解：

当搜索返回多个候选接口时，按以下规则排序选择：

歧义消解后仍无法确定唯一接口时，列出 Top 3 候选供用户选择。

跨项目依赖处理：

当接口在当前 YApi 项目中搜不到时（如用户下拉接口可能在用户管理项目中）：
1. 在搜索结果中标注"当前项目未找到"
2. 询问用户：该接口是否在其他 YApi 项目中？如果是，提供项目 ID
3. 如果用户无法提供，标记为"待确认"，继续后续流程

2.5 汇总报告

所有接口搜索完成后，输出汇总报告：

状态说明：
- ✅ 已找到：唯一匹配或歧义消解后确定
- ⚠️ 歧义/跨项目：需要用户确认
- ❌ 未找到：3 轮搜索均无结果

2.6 用户确认差异

将汇总报告展示给用户，用户可以：
- 为 ⚠️ 状态的接口选择正确候选或提供其他项目信息
- 为 ❌ 状态的接口提供 YApi URL 或手动补充接口信息
- 确认缺失接口可以暂不处理（代码生成时按 spec 推断处理）

2.7 更新 spec 文件

根据采集结果更新 .aicode/tmp/page-specs/{PageName}.md：

对齐规则（接口信息覆盖策划推断）：
1. 接口路径：以 YApi 实际路径为准，替换 Step 1 中的推断路径或空值
2. 字段名：以 YApi 请求/响应中的字段名为准，替换 Step 1 中的推断字段名（如 memberCount → userCount）
3. 请求方式：以 YApi 定义为准
4. 请求参数：以 YApi 定义为准，补充 Step 1 中缺失的参数
5. 响应字段：以 YApi 定义为准，补充 Step 1 中缺失的字段
6. 操作关联：将作表中关联接口列填入接口表中该接口的 YApi 编号（ID），作为两张表的精确交叉引用；禁止填写 service 函数名，函数名在代码生成阶段按项目规范生成
7. 必填/选填：以 YApi 定义为准，覆盖 Step 1 中留空的必填标注
8. 枚举值：以 YApi 定义为准，覆盖 Step 1 中的推断枚举

差异处理：
- 当 YApi 字段与 Step 1 推断不一致时，以 YApi 为准，在备注中记录差异（如"YApi 字段名为 userCount（非 memberCount）"）
- 当 YApi 缺少 Step 1 中策划明确要求的字段时，保留策划字段，备注"YApi 未定义，保留策划需求"
- 当 YApi 有 Step 1 中未提及的接口（如下拉数据源），新增到接口表

YApi 信息不完整的备注规则：
YApi 接口文档经常信息不完整（字段类型为 null、缺少参数、接口状态为"未完成"等），不视为阻断问题。YApi 没有定义的内容不加、不补、不猜，只做备注：

> 原则：信息不完整不阻断流程，YApi 没有的不加，策划有的保留，备注清楚即可。具体代码生成时结合项目规范和模板处理。

更新元数据：将 step 更新为 2，stepStatus 更新为 done，updatedAt 更新为当前日期。

> 此步骤可选。若用户跳过，直接使用 Step 1 的描述生成代码（接口信息可能不完整）。

Step 3：代码生成

根据页面描述 + 项目规范 + 组件 API 生成列表页代码。

输入：
- Step 1/2 输出的页面描述
- docs/list-page-convention.md（项目规范）
- pro-table / modal-form skill（组件 API）

输出：
- src/pages/{Module}/{PageName}/index.jsx（页面代码）
- src/services/{module}.js（接口函数，追加到已有文件）
- src/routes/index.jsx（路由配置，追加到已有文件）

流程：

阶段一：读取规范
1. 读取 docs/list-page-convention.md 获取规范和模板
2. 读取 docs/route-convention.md 获取路由规范
3. 读取 docs/service-convention.md 获取接口定义规范
4. 检查 available_skills 中是否有 pro-table 和 modal-form skill，有则必须在同一轮对话中依次激活（先 pro-table 再 modal-form），获取组件 API 和字段使用技巧。激活后 skill 内容会在上下文中累积，无需分两轮加载

阶段二：接口函数（先于页面生成）
5. 读取 src/services/{module}.js，根据 spec 接口表 + docs/service-convention.md 规范，追加接口函数
6. 向用户输出追加的接口函数清单，等待确认

阶段三：路由配置
7. 读取 src/routes/index.jsx，根据 docs/route-convention.md 规范，追加路由配置
8. 向用户输出路由变更，等待确认

阶段四：页面代码
9. 根据页面描述填充模板，生成页面代码
10. 向用户输出页面代码 + 问题清单（需要补充的细节、拿不准的点），等待确认后再写入文件

问题清单格式：

使用编号表格，用户按编号回复即可：

• 类别：字段 / 接口 / 交互 / 样式 / 其他，方便用户快速定位
• 选项 / 说明：提供可选方案时列出选项，开放性问题写说明
• 用户回复格式：1-A, 2-是, 3-需要，因为...

阶段五：规范合规检查

11. 代码写入文件后，对照以下检查清单逐项验证，输出合规报告：

ProTable 检查：

ModalForm 检查：

Service 检查：

路由检查：

导入路径检查：

输出格式：

• 全部 ✅ → 直接进入阶段六
• 有 ❌ → 修复后重新检查，最多 3 轮；3 轮后仍有问题则列出剩余项让用户决定

阶段六：收尾
12. 用户确认所有代码后，将 spec 文件的 step 更新为 3，stepStatus 更新为 done，同步更新注册表

> 核心原则：每个阶段输出后都向用户反馈，遇到问题不闷头自己找方案，而是列出问题让用户决定。

代码生成参考策略：

• 直接用模板 + 规范 + skill 生成代码，不主动去读项目中已有的页面作为参考
• 遇到拿不准的点（模板未覆盖的模式、规范未明确的细节），列在问题清单中让用户拿主意，不自行翻老页面找答案
• 若认为参考某个已有页面会有帮助，向用户提出建议，由用户决定是否提供参考页面及参考哪个页面
• 禁止自行选择参考页面：已有页面的实现质量未知，参考不当反而引入错误模式

路由配置规则：
- 必须读取 docs/route-convention.md，按规范确定路由归属和配置格式
- 根据 spec 中的模块和路由路径，判断页面归属哪个一级分组
- 若一级分组已存在，在其 routes 下追加；若不存在，按规范新建一级分组
- 禁止自行推断一级分组归属，无法确定时必须向用户确认

Skill 使用策略（有则必用，无则降级）：

为什么已安装时必须激活：
- Skill 中包含组件 API 的细节和字段使用技巧（如 search={false} 关闭搜索栏、valueEnum 与 options 的选择、fieldProps 配置等），仅参考项目规范和模板可能遗漏
- 激活 skill 后，以 skill 中的 API 为准，项目规范为框架约束，模板为结构参考，三者结合生成代码