72 lines
2.4 KiB
Markdown
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` 生成接口定义和调用代码。
|