2026-04-15 21:01:12 +08:00

72 lines
2.4 KiB
Markdown

# API Doc Agent Workflow
该工作流面向 Agent 编程场景:直接基于 `api-doc-system/module` 的最新接口信息判断可用性,再在可用时返回该接口的 `params/response` 结构用于编码。
## 目录结构
- `run.mjs`: API Agent 统一入口,负责脚本路由与执行。
- `scripts/`: 所有脚本目录,每个脚本独立管理自己的代码与数据。
- `config/`: 公共配置目录(占位:`接口.md`、`新增模块和接口.md`)。
- `docs/`: 公共文档目录(占位:`接口.md`、`新增模块和接口.md`)。
当前内置脚本:
- `scripts/interface-availability/`: 接口可用性测试脚本(`npm run apiagent -- <method>`)。
- `scripts/api-list-update/`: 扫描 `src/api` 并回写 `接口.md` 文档(`npm run apiagent -- --script api-list-update`)。
## 可用性规则
- 仅当接口状态满足以下条件才判定可用:
- `isUsed = true`
- `isPlaceholder = false`
## 运行
```bash
npm run apiagent -- <method>
```
示例:
```bash
npm run apiagent -- storage.receiving.bindStore
```
查看当前可用脚本:
```bash
npm run apiagent -- --script list
```
执行指定脚本(可扩展):
```bash
npm run apiagent -- --script interface storage.receiving.bindStore
```
执行 API 列表更新(生成模块与接口总览):
```bash
npm run apiagent -- --script api-list-update
```
## 输出
- 终端打印 JSON 结果,包含:
- `available`: 是否可用于编码
- `check`: `isUsed` / `isPlaceholder` 判断结果
- `interfaceSpec`: 可用时提供 `endpoint`、`params`、`response` 等接口结构
- 同时会写入脚本私有结果文件:
- `workflows/api-doc-agent/scripts/interface-availability/results/YYYYMMDD/<method>.json`
- 仅扫描 `module` 中生命周期为 `active` 的模块快照;已标记删除模块不会参与可用性判断。
- `api-list-update` 会扫描 `src/api` 下所有接口模块与 API 文件,并更新:
- `workflows/api-doc-agent/docs/接口.md`
- `workflows/api-doc-agent/config/接口.md`
- 输出结果归档:`workflows/api-doc-agent/results/YYYYMMDD/api-list-update.json`
## 使用建议
1. 先执行 `npm run apiconfig` 更新 `module` 最新接口数据。
2. 再执行 `npm run apiagent -- <method>` 判断接口可用性。
3. 若 `available=true`,可直接用 `interfaceSpec.params/response` 生成接口定义和调用代码。