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

2.4 KiB

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

运行

npm run apiagent -- <method>

示例:

npm run apiagent -- storage.receiving.bindStore

查看当前可用脚本:

npm run apiagent -- --script list

执行指定脚本(可扩展):

npm run apiagent -- --script interface storage.receiving.bindStore

执行 API 列表更新(生成模块与接口总览):

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 生成接口定义和调用代码。