| name | fexd-mobile-maintainer |
| description | 维护 @fexd/mobile 发布 skill 的文档质量工具。扫描组件源码变更、清洗 dumi 语法、 生成/更新 references/*.md 组件文档、执行质量审查。 触发词:检查组件 skill、更新组件文档、生成组件文档、审查组件文档。 |
fexd-mobile 文档维护 Skill
维护 packages/mobile/skills/fexd-mobile/ 中的发布 skill 文档,确保与组件源码同步。
关键路径
| 用途 | 路径 |
|---|
| 组件源码 | packages/mobile/src/exports/{NAME}/ |
| 发布 skill | packages/mobile/skills/fexd-mobile/ |
| 组件文档输出 | packages/mobile/skills/fexd-mobile/references/{NAME}.md |
| 变更追踪 | .cursor/skills/fexd-mobile-maintainer/.doc-tracker.json |
| 主索引入口 | packages/mobile/src/index.ts |
工作流程
流程 A:变更检测(日常维护)
用户说「检查组件 skill」或「哪些组件文档需要更新」时:
- 运行
node .cursor/skills/fexd-mobile-maintainer/scripts/detect-changes.js
- 展示需要更新/新建/删除的组件列表
- 等待用户确认执行范围
- 按「单组件处理步骤」逐个处理
流程 B:指定组件(单个更新)
用户说「更新 Button 的组件文档」时:
- 直接按「单组件处理步骤」处理指定组件
- 处理完成后更新
.doc-tracker.json
流程 C:全量初始化(首次或重建)
用户说「全量初始化组件文档」或「生成所有组件文档」时:
- 运行
node .cursor/skills/fexd-mobile-maintainer/scripts/scan-exports.js
- 从输出 JSON 中筛选
exported: true 且 developing: false 的组件
- 分批派发子 agent 处理(每批 5-8 个并行)
- 每批完成后更新
.doc-tracker.json
- 全部完成后执行「索引同步」
流程 D:质量审查
用户说「审查组件文档」或「检查文档质量」时:
- 列出所有
references/*.md 文件
- 分批派发子 agent 审查(每批 3-5 个,需更细致)
- 每个子 agent 按「审查维度」逐项检查
- 汇总审查报告,对 NEEDS_FIX 的组件直接修复
- 修复后必须重新审查修复后的文件,直到全部 PASS
- 单组件最多重审 2 轮,第 3 轮仍有问题需报告人工介入
- 更新
.doc-tracker.json 中的 reviewStatus
单组件处理步骤
对每个组件 {NAME}:
- 读取源码文档
packages/mobile/src/exports/{NAME}/index.zh.md
- 如果不存在,仅生成基于 type.tsx 的最小文档
- 读取类型定义
packages/mobile/src/exports/{NAME}/type.tsx
- 提取所有 exported interface/type,转为 Props 表格
- 特别注意
DOC_* 前缀的导出(StyleVars 类型)
- 可选读取示例
packages/mobile/src/exports/{NAME}/demos/*.tsx
- 清洗 dumi 语法 — 参照 dumi-patterns.md
- 按模板输出 — 参照 output-template.md
- 判断拆分:
- 预估超过 300 行 → 拆为
{NAME}.md + {NAME}-advanced.md
- 简单组件 → 单文件
- 判断 design.md:
- Modal/Form/IO 系统、有复杂 DOM 层级或继承关系的组件 → 需要
{NAME}-design.md
- 简单展示/工具组件 → 不需要
- 写入
packages/mobile/skills/fexd-mobile/references/{NAME}.md
- 更新 tracker
.doc-tracker.json
审查维度
每个组件文档必须通过以下 9 项检查:
- Props 准确性:与 type.tsx 逐字段比对,字段名/类型/默认值/必选标记一致
- 代码片段可靠性:import 路径、组件名、prop 名正确,用法符合实际 API
- dumi 语法零残留:不得出现
<ImportCost>、<code src=>、<API>、 | pure
- 信息完整度:关键用例、注意事项、坑点未遗漏
- 样式定制点:有 style.less 或 StyleVars 时必须包含样式定制说明
- 拆分合理性:超 300 行应拆分,已拆分的边界合理
- design.md 质量(仅复杂组件):DOM 层级描述准确,设计思路有助理解
- frontmatter 完整性:name 和 description 字段齐全,description 准确概括组件用途
- 源码溯源:文件末尾 HTML 注释包含正确的源码路径
审查报告格式:
- PASS:文档准确完整
- NEEDS_FIX:附具体问题清单(字段缺失/类型错误/信息遗漏等)
索引同步
所有组件文档处理完毕后,更新以下索引文件:
packages/mobile/skills/fexd-mobile/catalog.md — 为每个组件补充 references 链接
packages/mobile/skills/fexd-mobile/SKILL.md — 更新任务路由表,并将 frontmatter 中 metadata.version 更新为当前日期(格式 YYYY.MM.DD)
packages/mobile/AGENTS.md — 更新文档索引表
子 agent 调度规范
派发子 agent 时必须在 prompt 中包含:
- 要处理的组件名称列表
- 组件源码路径
packages/mobile/src/exports/{NAME}/
- 输出路径
packages/mobile/skills/fexd-mobile/references/{NAME}.md
- 完整的 output-template.md 内容(或指引其读取路径)
- 完整的 dumi-patterns.md 内容(或指引其读取路径)
- 明确的质量要求:Props 必须从 type.tsx 提取,不可编造
不可处理组件(开发中黑名单)
以下组件有 .developing 标记,不在 index.ts 中导出,禁止生成文档:
Breadcrumb, Calendar, Card, Cascader, CountDown, CountTo, Drag, Drawer, Dropdown, Elevator, Footer, Gallery, ImagePicker, List, Marquee, Menu, NoticeBar, NumberKeyboard, Pagination, Search, SegmentedControl, ShareSheet, Skeleton, Sticky, SwipeAction, Table, Tag, Tips, TreeSelect, Video, Waterfall