create-component-document

UI2 组件文档生成

为 core/ui2-components/ 下的组件生成技术文档，同时同步到飞书知识库和本地 markdown 文件（AGENTS.md）。

执行步骤

1. 确定目标组件

• 如果通过参数或用户消息指定了组件名，直接处理该组件
• 如果用户说"最近修改的"，通过 git diff 检测 core/ui2-components/ 下的变更
• 如果没有指定，列出所有组件让用户选择

2. 阅读组件代码

按优先级阅读组件目录下的文件：

1. types.ts / type/*.ts — 类型定义和 JSDoc 是最重要的文档来源
2. ui2-*.vue — 主组件，关注 defineProps / defineEmits / defineExpose / slot
3. composable.ts — 组件对外的编程接口（如 usePrettyRank）
4. const.ts / config.ts — 默认值和常量
5. index.ts — 导出内容
6. components/*.vue — 子组件，辅助理解 Slot

3. 搜索使用示例

在 apps/ 目录下搜索组件的实际使用：

• 搜索组件标签名（如 ui2-pretty-rank、<PrettyRank）
• 搜索 Composable 名称（如 usePrettyRank）
• 选取 1-2 个有代表性的示例

4. 生成文档内容

根据组件代码和使用示例，生成符合团队模板的文档内容。

文档结构必须遵循以下顺序：

1. 基础信息
2. 示例（图优先于文字）
3. 说明
4. 注意
5. pageCenter 示例
6. 使用方式
7. API（uiMeta / Props / Slots / Events / Methods / 其他）
8. 后续维护计划

详细的文档结构规范见：docs/doc-template.md

5. 同步到飞书

根据组件 readme.md 中的 feishu_url 判断是创建还是更新文档。

• 章节存在且 feishu_url 非空 → 更新文档
• 章节不存在或 feishu_url 为空 → 创建文档，并回填 URL

详细的飞书同步流程见：docs/feishu-sync-guide.md

6. 生成本地文档

在同步飞书的同时，生成本地 markdown 格式的文档：

• 单组件目录：生成 AGENTS.md（与飞书内容对应，但使用标准 markdown 格式）
• 多组件目录：每个组件生成 docs/组件名.md，同时生成 AGENTS.md 作为索引文件引用各子文档

格式差异：

• 飞书：使用 <lark-table> 格式
• 本地：使用标准 markdown 表格 | col1 | col2 |

详细的本地文档规范见：docs/local-doc-guide.md

7. 处理图片（优先级很高）

• 图片优先级很高：有图片时必须上传/展示，不能省略。示例章节、pageCenter 切图表等能配图的地方必须配图。
• 优先使用图片 URL：<image url="..."/> 飞书会自动转换为 token
• lark-table 中的图片：必须遵守特殊格式（前后空行，同时设置 width/height）
• URL 拉图失败时：降级为文本链接或使用上传脚本，确保读者能看到图或链接

详细的图片处理指南见：docs/image-handling.md

项目约定

• a-section / a-position / a-img 是框架布局组件（类似 div）
• uiMeta 是配置平台注入的 Props，通过深度合并覆盖组件默认配置
• 组件命名格式：ui2-{name}
• Props 信息提取优先级：TypeScript Interface + JSDoc > defineProps 对象 > defineProps 数组

质量要求

• 图片优先级很高：有图片时必须上传/展示，示例、pageCenter 等能配图处必须配图，不能省略。
• 图优先于文字：能配图的地方尽量配图，文字作补充说明
• 表格内切图不拉伸：lark-table 中的 <image> 必须同时设置正确比例的 width 和 height
• uiMeta 需细致：uiMeta 及其下各对象（如 props.images、props.styles、props.text、props.request 等）的一级字段必须全部列出，用表格逐项写清参数/说明/类型/默认值/备注；嵌套对象用子标题+表格展开，不省略字段。例外：props.components 下的子组件配置（如 ui-input-control、ui2-dialog 等）可简化说明或引用其组件文档。
• Props / Events / Slots 必须来自代码，不要臆造
• 保持 TypeScript 类型原样
• 优先使用代码中的 JSDoc 注释作为说明
• 示例优先使用项目中搜索到的真实用法
• 中文撰写

相关文档

• 飞书同步详细说明 - 创建/更新文档流程、授权说明
• 本地文档生成规范 - 本地 markdown 文档格式、AGENTS.md 索引结构
• 图片处理最佳实践 - URL/token 使用、表格图片格式、上传脚本
• 文档结构模板 - 章节顺序、格式要点、表格示例（飞书格式）
• readme 格式规范 - readme.md 的结构和字段说明
• 示例参考 - 标准组件文档示例

示例参考

标准示例：任务列表组件（ui-task-group）

详见：docs/examples.md