sync-service-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

# sync-service-docs

为指定服务生成或同步产品文档。

## 调用方式

```
/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/` |
| `payment` | `openapi/aitoearn-payment.yaml` | `apps/aitoearn-payment/src/` | `docs/payment/` |
| `task` | `openapi/aitoearn-task.yaml` | `apps/aitoearn-task/src/` | `docs/task/` |
| `admin` | `openapi/aitoearn-admin-server.yaml` | `apps/aitoearn-admin-server/src/` | `docs/admin/` |

---

## 执行流程

### Step 1 — 初始化

1. 校验 `service` 参数，不在配置表中则报错停止
2. 获取 `git rev-parse --short HEAD` → `<hash>` 和当前日期 → `<today>`
3. 检查文档目录是否存在且有 `.md` 文件：
   - **不存在或为空** → 执行 Step 2（首次建档）
   - **已存在** → 执行 Step 3（差异更新）

---

### Step 2 — 首次建档

#### 2a. 读取 OpenAPI 规范

读取对应 OpenAPI 文件，提取：
- 所有 `paths`：path + HTTP method + operationId + summary
- 按 `tags` 分组（每个唯一 tag → 一个 `.md` 文件）
- 每个接口的 `parameters`、`requestBody` schema、`responses` schema

**原则：请求/响应结构必须完全来自 OpenAPI 定义，不得猜测字段。**

#### 2b. 阅读源码（完整追踪业务流程）

对每个 tag 对应的模块，沿调用链路完整追踪：

```
Controller → Service → Helper/Util → Consumer/Processor → Repository
                 ↓
            libs/ 共享库方法（如被调用则跟进阅读）
```

**每个接口都要读完整调用链路中的所有方法**，按代码实际执行顺序记录每一步做了什么，包括但不限于：
- 参数校验、权限检查、资源存在性检查
- 数据查询、数据构建、数据转换
- 积分/计费操作（预扣/后扣、价格计算、退款机制）
- 异步队列投递与消费逻辑
- 日志记录（AiLog 创建/更新）
- 外部 API 调用
- 文件上传/存储操作
- 每个可能的错误分支及对应错误码

**原则：业务流程必须来自源码逐行追踪，任何步骤都不得省略或猜测。**

#### 2c. 大代码库分段处理

当模块数量 ≥ 4 或单模块接口数 ≥ 8 时，使用子代理（Agent tool）并行处理：

- **每个子代理**负责 1-2 个 tag/模块：阅读 OpenAPI 对应部分 + 追踪源码 + 生成该模块的 `.md` 文件内容
- **子代理 prompt 必须包含**：该模块的 OpenAPI paths 列表、源码路径、文档结构规范（从本 skill 复制）、约束条件
- **主流程**负责：初始化、拆分任务、汇总子代理输出、写入文件、生成 README.md

示例拆分方式：
```
子代理 1: chat 模块（5 个接口）
子代理 2: image 模块（14 个接口）
子代理 3: video + agent 模块（各 5-6 个接口）
```

#### 2d. 生成文档文件

按 tag 生成对应 `.md` 文件（格式见"文档结构规范"），同时生成 `README.md`（模块索引 + 通用约定）。

所有文件标题后紧跟：
```
> 最后更新时间：<today> &nbsp;|&nbsp; 代码基准：`<hash>`
```

---

### Step 3 — 差异更新

#### 3a. 读取各文档的代码基准

从每个已有文档的元信息行提取 `代码基准：\`<hash>\`` 中的 hash 值（`<doc_hash>`）。

#### 3b. 检测变更范围

对每个文档，检查 OpenAPI 和源码是否有变更：

```bash
git log <doc_hash>..HEAD --oneline -- <openapi_file> <source_path>
```

无输出则该文档跳过。有输出则继续分析。

#### 3c. 分析差异并更新

```bash
git diff <doc_hash>..HEAD -- <openapi_file> <source_path>
```

根据 diff 内容精准更新对应章节：

From Yusufkotavom/AiToEarn, MIT.

More from Yusufkotavom/AiToEarn