SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssync-service-docs

sync-service-docs

Writing & research

View repository

Updated 10-16 09:35

About this skill

sync-service-docs

Generate or synchronize product documentation for the specified service.

How to invoke

/sync-service-docs [service]

When service is not passed, list the available services and stop.

Service configuration table

Service OpenAPI file Source code path Documentation directory
ai openapi/aitoearn-ai.yaml apps/aitoearn-ai/src/core/ docs/ai-service/
server openapi/aitoearn-server.yaml apps/aitoearn-server/src/ docs/server/

Execution flow

Step 1 — Initialization

  1. Validate the service parameter; if it is not in the configuration table, report an error and stop
  2. Get git rev-parse --short HEAD → <hash> and the current date → <today>
  3. Check whether the documentation directory exists and contains .md files:
    • Does not exist or is empty → execute Step 2 (initial documentation creation)
    • Already exists → execute Step 3 (diff update)

Step 2 — Initial documentation creation

2a. Read the OpenAPI specification

Read the corresponding OpenAPI file and extract:

  • All paths：path + HTTP method + operationId + summary
  • Grouped by tags (each unique tag → one .md file)
  • For each endpoint, the parameters、requestBody schema、responses schema

Principle: request/response structures must come entirely from the OpenAPI definition; fields must not be guessed.

2b. Read the source code (fully trace the business flow)

For the module corresponding to each tag, fully trace along the call chain:

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

For every endpoint, read all methods in the complete call chain, and record what each step does in the actual code execution order, including but not limited to:

  • Parameter validation, permission checks, resource existence checks
  • Data queries, data construction, data transformation
  • Price/usage calculation and logging (if present)
  • Asynchronous queue delivery and consumption logic
  • Logging (AiLog creation/update)
  • External API calls
  • File upload/storage operations
  • Every possible error branch and its corresponding error code

Principle: the business flow must come from line-by-line source code tracing; no step may be omitted or guessed.

2c. Segmented processing for large codebases

When the number of modules ≥ 4 or the number of endpoints in a single module ≥ 8, use sub-agents (Agent tool) for parallel processing:

  • Each sub-agentis responsible for 1-2 tags/modules: reading the corresponding part of the OpenAPI + tracing the source code + generating the contents of the .md file for that module
  • The sub-agent prompt must include: the list of OpenAPI paths for that module, the source code path, the documentation structure specification (copied from this skill), and constraint conditions
  • Main flowResponsible for: initialization, splitting tasks, aggregating sub-agent output, writing files, and generating README.md

Example splitting approach:

子代理 1: chat 模块（5 个接口）
子代理 2: image 模块（14 个接口）
子代理 3: video + agent 模块（各 5-6 个接口）

2d. Generate documentation files

Generate the corresponding .md file by tag (format see "Documentation structure specification"), and also generate README.md(module index + general conventions).

Immediately after the title of every file:

> 最后更新时间：<today> &nbsp;|&nbsp; 代码基准：`<hash>`

Step 3 — Diff update

3a. Read the code baseline of each document

Extract from the metadata line of each existing document 代码基准：\` 中的 hash 值（<doc_hash>`）。

3b. Detect change scope

For each document, check whether the OpenAPI and source code have changed:

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

If there is no output, skip that document. If there is output, continue the analysis.

3c. Analyze differences and update

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

Accurately update the corresponding sections based on the diff content:

Change type Document operation
Add path/method Trace the source code and add an interface section in the standard format
Modify requestBody/parameters/responses Update the request/response part of the corresponding interface
Source code business logic changes Re-trace the interface call chain and update the business process
Delete interface Remove the corresponding document section and update the interface list

Principle: only update sections with actual changes; keep unchanged sections as-is (including wording and formatting).

3d. Update document metadata

Update the date and hash of all changed documents to the current values.

Step 4 — Output summary

After completion, output a change summary:

Document Action Description
image.md Created 14 interfaces
video.md Updated Added Grok video generation section
chat.md Skipped No code changes

Document structure specification

Module document (one per tag .md file)

# <模块名称>

> 最后更新时间：2026-03-12 &nbsp;|&nbsp; 代码基准：`a7d3afb3`

## 概述

<1-2 句功能描述>

**相关源码：** `apps/<service>/src/core/<module>/`

---

## 接口列表

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/...` | ... |
| GET  | `/api/...` | ... |

---

## 1. <接口功能名>

### `<METHOD> <path>`

<1-2 句说明>

**请求体：**
```json
{ "field": "value" }

Response body:

{
  "code": 0,
  "data": { ... }
}

Business process:

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> &nbsp;|&nbsp; 代码基准：`<hash>`

## 模块索引

| 文档 | 功能描述 |
|------|---------|
| [chat.md](./chat.md) | AI 对话、流式输出 |
| ...                   | ... |

## 通用约定

### 认证
- 所有接口需携带 JWT Token（`Authorization: Bearer <token>`）
- `userId` / `userType` 由网关解析后注入

### 响应格式
```json
{ "code": 0, "message": "success", "data": { ... } }

code=0 indicates success, non-0 is a business error code (defined in libs/common/src/enums/response-code.enum.ts）。

Usage records

<Describe AiLog, price, or token usage records according to the actual implementation of the service; if none, write "None".>


---

## 约束

### 必须做

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. **不得遗漏业务步骤** — 源码中的每个操作（校验、查询、转换、计费、日志、上传、队列等）都要在流程中体现