派 25 个 Explore 子代理 (5 批 × 5) 审计 23 个父命令.
产出 cmd-review/{cmd}.md (24 文件) + _summary.md.
关键发现:
- webapi 镜像使用率 < 30% (12+ 父命令 100% 绕 webapi)
- 30+ P0 必补新命令 (form update, log exception, di CRUD, role authorize 等)
- 3 处 P0 端点错误 (假 PASS):
* integration emailTest/smsTest
* msg templateCreate
- 用户关键修正: bigscreen → jnpf-web-datascreen-vue3 (独立子项目)
- 用户关键修正: report → jnpf-web-datareport (独立子项目)
下一步: Phase 2 按 P0 优先级执行 (修端点 + 新命令 + webapi 化)
Co-Authored-By: Claude <[email protected]>
3.3 KiB
3.3 KiB
dacli apis 命令审计报告 (2026-06-25)
1. 命令清单
| 子命令 | 格式 | 用途 |
|---|---|---|
dacli apis list |
[--tag=<t>] [--method=<m>] [--keyword=<k>] [--json] |
列 JNPF 平台所有 API (从 /v3/api-docs 拉取, 12h 缓存) |
dacli apis info |
<pathMethod> [--json] |
查单个 API 详情 + 递归解析 $ref (含 ActionResult.data 展开) |
dacli apis refresh |
— | 强制刷新 OpenAPI 缓存 (忽略 12h TTL) |
dacli apis status |
[--json] |
OpenAPI 缓存状态 (loaded/age/pathCount/openapiSize) |
2. web 端对应
apis 是元工具,没有对应的 web 页面。它直接调用 JNPF 后端端点:
GET /v3/api-docs— SpringDoc OpenAPI 标准端点,返回 1000+ API 完整定义- 备选:
http://127.0.0.1:30000/v3/api-docs(容器外 fallback)
3. 改/删/留 建议
[KEEP] 所有 4 个子命令
- list:高频 AI 排查入口,支持 tag/method/keyword 过滤
- info:杀手特性,递归展开
$ref+ ActionResult.data 展开 - refresh:JNPF 升级/新增 API 后强制重拉
- status:诊断"为什么看不到新 API"的标准命令
[REFACTOR-WEBAPI] 不适用
apis 不是业务 API 客户端,直接拉 SpringDoc OpenAPI。无 webapi 镜像对象。
[DEPRECATE] 无
所有 4 个子命令都有明确价值。
[NEW-CMD] 建议新增
dacli apis search --field=<f>(P0)
- 场景:AI 知道字段名(如
f_user_name),想知道哪些 API 返回/接受这个字段 - 实现:遍历 OpenAPI schema,匹配 properties 中字段名
- 价值:避免 AI 盲猜(盲点根因 B)
dacli apis tags(P1)
- 场景:AI 不知道 JNPF 有哪些业务 tag(
visualdev/system/workflow等) - 实现:解析 OpenAPI tags 字段,列出所有 tag + API 数
- 价值:作为
apis list --tag=X的引导
4. AI 痛点评估
痛点 1:缓存失效机制有盲区
- 12h TTL + PID 哈希(process.pid + 启动时间分钟)
- 问题:JNPF 容器重启后 API 可能已变,但 PID 哈希可能未变,AI 误以为缓存最新
- 建议:缓存 key 加入后端版本号(来自
/v3/api-docs的info.version)
痛点 2:缺少字段维度搜索
- AI 知道字段名
f_user_name,但--keyword只能搜 path/summary,搜不到 schema 内部 - 影响:AI 盲猜"哪个 API 接受
f_user_name",浪费 2-3 次试探 - 解决:
apis search --field=<name>
痛点 3:info 输出体积过大
--json输出 ~15KB(包含所有 schema 展开)- 影响:浪费 AI context token
- 建议:加
--summary(仅 method/path/summary)和--resolved-only(仅展开 schema)
痛点 4:status 缺少变化检测
- 只输出
pathCount,不显示与上一次拉取的差异 - 影响:AI 无法判断"JNPF 升级后是否有新 API"
- 建议:加
--diffflag,对比最近两次拉取
核心结论:apis 命令族设计简洁(4 子命令覆盖 90% 场景),但缺少字段级搜索和tag 引导两个高频 AI 痛点的支持。建议优先级:
- P0:
apis search --field=(解决字段盲猜) - P1:
apis tags(引导命令) - P2:
apis info --summary/--resolved-only(减 token) - P3:
apis status --diff(变化检测) - P3:缓存 key 加版本号(容器重启场景)