// 为指定服务维护产品文档与代码的同步。文档不存在时以 OpenAPI 规范为基础从头生成；文档已存在时根据 git diff 更新受影响章节，并刷新最后更新时间和代码基准 hash。
| name | sync-service-docs |
| description | 为指定服务维护产品文档与代码的同步。文档不存在时以 OpenAPI 规范为基础从头生成；文档已存在时根据 git diff 更新受影响章节，并刷新最后更新时间和代码基准 hash。 |
| origin | custom |
为指定服务生成或同步产品文档。
/sync-service-docs [service]
不传 service 时，列出可用服务列表并停止。
| Service | OpenAPI 文件 | 源码路径 | 文档目录 |
|---|---|---|---|
ai | openapi/aitoearn-ai.yaml | apps/aitoearn-ai/src/core/ | docs/ai-service/ |
server | openapi/aitoearn-server.yaml | apps/aitoearn-server/src/ | docs/server/ |
service 参数，不在配置表中则报错停止git rev-parse --short HEAD → <hash> 和当前日期 → <today>.md 文件：
读取对应 OpenAPI 文件，提取：
paths：path + HTTP method + operationId + summarytags 分组（每个唯一 tag → 一个 .md 文件）parameters、requestBody schema、responses schema原则：请求/响应结构必须完全来自 OpenAPI 定义，不得猜测字段。
对每个 tag 对应的模块，沿调用链路完整追踪：
Controller → Service → Helper/Util → Consumer/Processor → Repository
↓
libs/ 共享库方法（如被调用则跟进阅读）
每个接口都要读完整调用链路中的所有方法，按代码实际执行顺序记录每一步做了什么，包括但不限于：
原则：业务流程必须来自源码逐行追踪，任何步骤都不得省略或猜测。
当模块数量 ≥ 4 或单模块接口数 ≥ 8 时，使用子代理（Agent tool）并行处理：
.md 文件内容示例拆分方式：
子代理 1: chat 模块（5 个接口）
子代理 2: image 模块（14 个接口）
子代理 3: video + agent 模块（各 5-6 个接口）
按 tag 生成对应 .md 文件（格式见"文档结构规范"），同时生成 README.md（模块索引 + 通用约定）。
所有文件标题后紧跟：
> 最后更新时间：<today> | 代码基准：`<hash>`
从每个已有文档的元信息行提取 代码基准：\` 中的 hash 值（<doc_hash>`）。
对每个文档，检查 OpenAPI 和源码是否有变更：
git log <doc_hash>..HEAD --oneline -- <openapi_file> <source_path>
无输出则该文档跳过。有输出则继续分析。
git diff <doc_hash>..HEAD -- <openapi_file> <source_path>
根据 diff 内容精准更新对应章节：
| 变更类型 | 文档操作 |
|---|---|
| 新增 path/method | 追踪源码，按规范格式新增接口章节 |
| 修改 requestBody/parameters/responses | 更新对应接口的请求/响应部分 |
| 源码业务逻辑变化 | 重新追踪该接口调用链路，更新业务流程 |
| 删除接口 | 移除对应文档章节，更新接口列表 |
原则：只更新有实际变化的章节，未变更章节保持原文不动（包括措辞和格式）。
将所有变更文档的日期和 hash 更新为当前值。
完成后输出变更摘要：
| 文档 | 动作 | 说明 |
|---|---|---|
image.md | 新建 | 14 个接口 |
video.md | 已更新 | 新增 Grok 视频生成章节 |
chat.md | 跳过 | 无代码变更 |
.md 文件）# <模块名称>
> 最后更新时间：2026-03-12 | 代码基准：`a7d3afb3`
## 概述
<1-2 句功能描述>
**相关源码：** `apps/<service>/src/core/<module>/`
---
## 接口列表
| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/...` | ... |
| GET | `/api/...` | ... |
---
## 1. <接口功能名>
### `<METHOD> <path>`
<1-2 句说明>
**请求体：**
```json
{ "field": "value" }
响应体：
{
"code": 0,
"data": { ... }
}
业务流程：
1. 校验参数/权限
└── 失败 → ErrorCode
2. 查询资源/计算价格
└── 不存在 → ResourceNotFound
3. 创建 AiLog（status=generating，记录预估用量/价格）
4. 投入异步队列（QueueName.Xxx）
5. 返回 { logId } 供前端轮询
── 异步阶段（Consumer） ──────────────────
6. 消费任务 → 调用外部 API
7a. 成功：
- 上传结果到 S3
- 更新 AiLog（status=success, response=...）
7b. 失败：
- 更新 AiLog（status=failed, errorMessage=...）
**关于业务流程的说明：**
- 上方模板仅为**异步队列**模式的示例，实际流程根据源码如实描述
- 同步模式：先调用 API → 从响应提取用量 → 写 AiLog
- 纯同步无用量记录：直接描述业务操作
- 流程中的每一步都应来自源码，按实际执行顺序排列
- 错误分支写在对应步骤的 `└──` 子行中，不单独设"错误码"节
### README.md 结构
```markdown
# <Service> 服务产品文档
> 最后更新时间：<date> | 代码基准：`<hash>`
## 模块索引
| 文档 | 功能描述 |
|------|---------|
| [chat.md](./chat.md) | AI 对话、流式输出 |
| ... | ... |
## 通用约定
### 认证
- 所有接口需携带 JWT Token（`Authorization: Bearer <token>`）
- `userId` / `userType` 由网关解析后注入
### 响应格式
```json
{ "code": 0, "message": "success", "data": { ... } }
code=0 表示成功，非 0 为业务错误码（定义在 libs/common/src/enums/response-code.enum.ts）。
<根据该服务的实际实现描述 AiLog、价格或 token 用量记录；没有则写“无”。>
---
## 约束
### 必须做
1. **请求/响应结构来自 OpenAPI** — 字段名、类型、必填状态以 OpenAPI schema 为准
2. **业务流程来自源码逐行追踪** — 沿 Controller → Service → Helper → Consumer 完整追踪，不省略任何步骤
3. **libs/ 共享库方法也要跟进阅读** — 当 Service 调用了 `libs/` 中的方法（如 queueService），必须读取其实现
4. **通用约定写在 README.md** — 认证、响应格式、用量记录等跨模块通用内容只在 README 中写一次
5. **更新模式先看 git diff** — 只更新有实际代码变化的章节，未变化章节保持原文不动
6. **所有文档统一使用当前 HEAD hash** — 不混用不同 hash
7. **中文描述，代码标识符保持英文** — 如 `AiLog`、`status=generating`
8. **大代码库使用子代理并行处理** — 模块多或代码量大时拆分给子代理，提高效率
### 禁止做
1. **不得生成测试要点** — 这是纯产品文档，不包含测试用例、测试要点、边界条件测试等内容
2. **不得单独设"计费流程"或"错误码"节** — 计费是业务流程的一个步骤，错误码写在流程的失败分支中
3. **不得在模块文档中重复通用约定** — 认证方式、响应格式等不在各模块文档中重复
4. **不得猜测字段或流程** — OpenAPI 中没有的字段不写，源码中没有的步骤不编
5. **不得修改未变更的章节** — 差异更新时，没有代码变化的章节保持原文（包括措辞和格式）
6. **不得遗漏业务步骤** — 源码中的每个操作（校验、查询、转换、计费、日志、上传、队列等）都要在流程中体现
Analyzes video content and extracts highlights. Use when user wants to analyze video, extract highlights, create video summary, generate video keywords, understand video content, find best moments, create trailer, extract exciting clips, get video insights, or identify viral moments. 视频分析、提取精彩片段、视频摘要、视频理解、精彩集锦、视频关键词、剪辑精华、内容分析、热门片段。
Combines multiple videos/images into a single video with optional background audio. Use when user wants to merge clips, concatenate videos, create slideshow from images, stitch videos together, combine media files, add background music to video, mix video with audio, create video montage, or join multiple video segments. 合并视频、拼接视频、图片合成视频、添加背景音乐、视频拼接、多图生成视频、视频混剪、素材合成。
Downloads and extracts content from social media platforms. Use when user wants to crawl, download, or extract videos/content from Bilibili, YouTube, TikTok, Douyin, Instagram, Twitter, Xiaohongshu. 下载视频、抓取视频、爬取内容、提取视频、下载B站视频、下载抖音视频、下载YouTube视频、视频采集。
Image editing using Sharp. Supports compositing (QR codes, logos, watermarks), resizing, cropping, rotating, flipping, brightness/contrast/saturation adjustment, blur, sharpen. 图片编辑、图片合成、添加二维码、添加Logo、添加水印、图片缩放、图片裁剪、图片旋转、图片翻转、亮度对比度饱和度调整、模糊、锐化。
Video editing using Volcengine Track structure. Supports cutting, trimming, adding text, stickers, audio, filters, effects, transitions, multi-clip compositions, speed adjustment, watermark removal. 视频剪辑、裁剪视频、添加文字、添加水印、添加音频、视频滤镜、视频特效、视频转场、多片段拼接、调整速度、去水印。
Extracts thumbnails from video URLs. Use when publishing video content that requires a cover image, when the user does not provide a cover/thumbnail, or before publishing to platforms that require cover images (Kwai, Bilibili, YouTube). 提取封面、视频封面、生成封面、缩略图提取、视频缩略图、截取封面。