Component Docs Batcher

概述

Component Docs Batcher 是一个自动化批量生成和维护前端组件库文档的工具。专为 Monorepo 架构的组件库设计，通过智能扫描主要组件文件，对比文档更新状态，生成规范化的组件文档，确保文档与代码保持同步。

核心功能

• 智能组件识别: 自动识别组件目录中的主要组件文件（如 button/button.tsx），跳过 index.ts、store、hooks 等辅助文件
• Git时间对比: 通过对比组件文件和文档的git最后提交时间，确定文档状态（比文件系统时间更准确）
• 任务清单生成: 自动生成结构化的todos.md任务清单
• 批量文档生成: 按照规范批量生成完整的组件文档
• 组件库优化: 针对 Monorepo 组件库结构优化，文档位于组件目录下的 index.zh-CN.md

工作流程

步骤1: 扫描组件

使用 scan-components.ts 脚本扫描组件库，识别需要处理的组件：

# 扫描指定组件库目录
npx ts-node .claude/skills/component-docs-batcher/scripts/scan-components.ts /path/to/packages/atom-ui-mobile/src/components

# 输出JSON格式（用于程序化处理）
npx ts-node .claude/skills/component-docs-batcher/scripts/scan-components.ts /path/to/components --json

组件识别规则:

• 扫描组件目录下的一级子目录（如 button/, alert/）
• 识别主要组件文件：与目录名同名的 .tsx 或 .jsx 文件（如 button/button.tsx）
• 自动跳过辅助文件：index.ts, *.store.ts, use*.ts 等
• 自动跳过辅助目录：styles/, __tests__/ 等

扫描结果分类:

• ❌ 文档缺失: 组件目录下没有 index.zh-CN.md 文档
• ⚠️ 文档过时: 组件文件的git最后提交时间晚于文档
• ✅ 文档最新: 组件和文档的git最后提交时间一致（不输出）

时间对比说明:

• 使用 git log -1 --format=%ct 获取文件的最后提交时间
• 如果文件没有git历史（新文件），则使用文件系统时间作为备选
• git时间比文件系统修改时间更准确，不受checkout、pull等操作影响

步骤2: 生成任务清单

使用 generate-todos.ts 生成详细的任务清单：

# 在当前目录生成todos.md
npx ts-node .claude/skills/component-docs-batcher/scripts/generate-todos.ts

# 在指定目录生成
npx ts-node .claude/skills/component-docs-batcher/scripts/generate-todos.ts /path/to/components /output/path/todos.md

生成的 todos.md 包含：

• 📊 统计信息（新增/更新数量）
• ✅ 任务列表（每个组件的详细任务）
• 📝 使用说明
• 📚 文档规范参考

步骤3: 分析组件结构

对于每个需要处理的组件，使用 analyze-component.ts 分析组件结构：

# 分析单个组件
npx ts-node .claude/skills/component-docs-batcher/scripts/analyze-component.ts /path/to/Component.tsx

# 输出JSON格式
npx ts-node .claude/skills/component-docs-batcher/scripts/analyze-component.ts /path/to/Component.tsx --json

分析内容包括:

• 组件类型（component/hook/util/type）
• Props接口（属性名、类型、默认值、必填性）
• TypeScript类型定义
• 导入依赖
• 代码示例（从注释提取）

步骤4: 批量生成文档

根据组件分析结果，为每个组件生成符合规范的文档：

1. 读取组件源码: 使用 Read 工具读取完整的组件文件
2. 理解组件逻辑: 不要依赖代码注释，独立理解组件实现
3. 提取关键信息:
   • Props接口及其所有属性
   • TypeScript类型定义
   • 组件的使用场景和交互逻辑
   • 依赖的第三方组件API（如 Ant Design Mobile）
4. 确定正确的导出名称: ⚠️ 重要！ 在生成文档前，必须检查 /packages/atom-ui-mobile/src/index.ts 确认组件的实际导出名称
   • 例如：qr-code 组件导出为 QrCode（不是 QRCode）
   • 例如：message 组件导出为小写的 message
   • 例如：time-select 直接导出为 TimeSelect（没有 default as）
5. 生成文档: 按照 文档格式规范 生成完整文档
6. 质量验证: 对照质量检查清单验证文档完整性

重要规则:

• 文档路径：组件目录下的 index.zh-CN.md（如 button/index.zh-CN.md）
• 独立理解组件，不复制代码注释
• 完整列出所有API，特别是继承的第三方组件API（如 Ant Design Mobile Button 的所有属性）
• 提供真实可用的代码示例
• 导出名称必须与 src/index.ts 中的定义完全一致（包括大小写）
• 引用方式示例：import { Button } from '@evanfang/atom-ui-mobile';

步骤5: 更新任务状态

完成每个组件文档后，在 todos.md 中标记任务为已完成：

1. [x] 读取组件源码
2. [x] 分析组件结构
3. [x] 创建/更新文档
4. [x] 验证文档格式
5. [x] 检查文档完整性

所有任务完成后，删除 todos.md 文件。

文档格式规范

所有组件文档必须遵循标准格式。详见 文档格式规范。

关键要求:

• 完整的API表格（属性名、类型、说明、默认值）
• TypeScript类型定义表格
• 真实可用的代码示例
• 主题变量列表或"无"的明确说明

使用场景

场景1: 定期批量更新

在项目迭代过程中，定期执行批量文档更新：

# 1. 扫描组件库
cd /Users/arwen/Desktop/Arwen/Demo/cc-system
npx ts-node .claude/skills/component-docs-batcher/scripts/scan-components.ts \
  /Users/arwen/Desktop/Arwen/evanfang/dp-design/packages/atom-ui-mobile/src/components

# 2. 生成任务清单
npx ts-node .claude/skills/component-docs-batcher/scripts/generate-todos.ts \
  /Users/arwen/Desktop/Arwen/evanfang/dp-design/packages/atom-ui-mobile/src/components

# 3. 按照生成的todos.md批量处理每个组件
# 4. 完成后删除todos.md

场景2: 单个组件维护

针对特定组件快速更新文档：

# 1. 分析组件结构
npx ts-node .claude/skills/component-docs-batcher/scripts/analyze-component.ts \
  /Users/arwen/Desktop/Arwen/evanfang/dp-design/packages/atom-ui-mobile/src/components/button/button.tsx

# 2. 根据分析结果生成/更新文档
# 文档位置: button/index.zh-CN.md

场景3: 新组件文档初始化

为新创建的组件快速生成文档：

# 1. 检查组件是否需要文档
npx ts-node .claude/skills/component-docs-batcher/scripts/scan-components.ts \
  /Users/arwen/Desktop/Arwen/evanfang/dp-design/packages/atom-ui-mobile/src/components

# 2. 新组件会在"文档缺失"列表中显示
# 3. 为新组件生成 index.zh-CN.md 文档

资源

scripts/

可执行的TypeScript脚本，提供扫描、分析和文档生成功能。

scan-components.ts: 组件文件扫描器

• 扫描指定目录下的组件文件
• 对比组件和文档的修改时间
• 输出需要更新或新增的组件列表
• 支持JSON格式输出

generate-todos.ts: 任务清单生成器

• 基于扫描结果生成todos.md
• 包含详细的任务步骤和统计信息
• 提供文档规范引用

analyze-component.ts: 组件结构分析器

• 分析组件源代码结构
• 提取Props、类型、依赖等信息
• 输出结构化的组件分析结果

references/

文档和参考资料，指导文档生成过程。

docs-format.md: 组件文档格式规范

• 标准文档模板
• 编写规则和质量检查清单
• 不同组件类型的特殊要求