Menu
SKSPIOT 智慧园区物联网平台专用 OpenAPI 3.1 导出。仅手动触发；当用户要把 Service 暴露接口整理为可导入 Apifox 的 OpenAPI 3.1 JSON 文件时，使用这个 skill。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
分析 Git 改动并生成规范提交信息。
问题诊断：定位报错与异常根因，按需并行取证，并在用户确认后执行最小修复与验证。
面向软件工程师生成代码结构图、调用链图和业务映射图，并按需导出 Mermaid 图文件。
代码审查：无参数时自动审查 git diff，支持按 git revision 审查指定提交，并在确认整改范围后生成执行计划。
按已确认计划实施改动并完成最小验证。
扫描项目结构并生成 CLAUDE.md 上下文文档。
| name | ac-api |
| description | SKSPIOT 智慧园区物联网平台专用 OpenAPI 3.1 导出。仅手动触发；当用户要把 Service 暴露接口整理为可导入 Apifox 的 OpenAPI 3.1 JSON 文件时，使用这个 skill。 |
| disable-model-invocation | true |
将 SKSPIOT 项目中“无 Controller、直接暴露 Service 接口”的能力整理为 OpenAPI 3.1 JSON 文件，供用户手动导入 Apifox。
不要再尝试通过 apifox MCP 直接创建或更新接口。 当前流程的目标只有一个：快速、稳定地生成可导入文件。
/ac-api <需求描述>
典型输入：
/ac-api 把充电桩概况接口导出成 Apifox 可导入的 OpenAPI 文件/ac-api 根据 BusinessCenter4EVChargingStation 的 overviewEVChargingStation 生成 OpenAPI 3.1 JSON/ac-api 扫描这个模块，按接口逐个导出 OpenAPI 文件| 项 | 默认值 |
|---|---|
| 输出根目录 | .claude/OpenAPI |
| 日期目录 | YYYY-MM-DD |
| 文件名 | HH-MM_BusinessCenter.method.openapi.json |
| OpenAPI 版本 | 3.1.0 |
| 请求地址 | http://127.0.0.1:8888 |
| 请求路径 | /json-adapter |
| HTTP Method | POST |
| Content-Type | application/json |
| 导出粒度 | 单接口单文件 |
注意：
POST /json-adapter只用于 SKSPIOT 智慧园区物联网平台，并且必须符合以下接口约定：
@BusinessCenterDescriptor@BusinessDescriptorPOSTContent-Type 固定为 application/json{
"bid": "<Service全限定名>.<业务方法名>",
"params": {
"<参数名>": {}
},
"passport": "{{access_token}}"
}
如果当前项目不符合这套规则：
bid、不猜参数名、不猜返回结构AskUserQuestion 先问清楚data 内字段说明优先取字段注解（如 @Schema / @ApiModelProperty）和字段 Javadoc/注释，不要把自动补全文本冒充成真实字段说明{ "code": "success", "success": true, "data": <返回实体>, "msg": "操作成功" }，其中 data 基于接口真实返回实体推导generate_openapi.py、export_openapi_from_java.py，也不要在生成后再回读 .openapi.json / .metadata.json；只有在调试 skill 本身时才允许这样做遇到以下情况，先提问，不要直接执行：
| 场景 | 必须确认的问题 |
|---|---|
| 用户只说“导出接口” | 要导出哪个 Service、哪个方法、哪个模块？ |
| 用户要批量导出 | 是逐个方法分别生成多个文件，还是先只导出其中几个关键接口？ |
@BusinessDescriptor.name 与方法名不一致 | bid 最后一级到底取哪个？ |
优先定位类或接口上的 @BusinessCenterDescriptor，确认这是对外暴露的业务中心。
在业务中心内定位方法上的 @BusinessDescriptor，至少提取以下信息：
| 字段 | 来源 |
|---|---|
| 业务中心类/接口全限定名 | Java 声明位置 |
| 业务中心短名 | 类名或接口名 |
| 方法名 | Java 方法签名 |
| 业务方法名 | @BusinessDescriptor.name，若缺失再回退到方法名 |
| 接口说明 | @BusinessDescriptor.desc |
| 返回说明 | @BusinessDescriptor.returnDesc |
| 参数列表 | Java 方法参数名 + 参数类型 |
| 返回类型 | Java 方法返回类型 |
| 字段中文说明 | 字段注解 > 字段注释/Javadoc；无证据时明确标记缺口，不把自动补全当成真实说明 |
| 证据 | file_path:line_number |
bid 生成规则bid 由两段组成：
格式：
<serviceFqcn>.<businessMethod>
示例：
base.business.energy.service.BusinessCenter4EVChargingStation.overviewEVChargingStation
注意：
@BusinessDescriptor.name@BusinessDescriptor.name 缺失，再使用 Java 方法名请求统一使用：
POSThttp://127.0.0.1:8888/json-adapterContent-Type: application/json请求体固定外层结构：
{
"bid": "<serviceFqcn>.<businessMethod>",
"params": {
"<参数名>": {}
},
"passport": "{{access_token}}"
}
params 的规则：
{}统一使用本地脚本：
python skills/ac-api/scripts/generate_openapi.py --input <metadata.json>
python skills/ac-api/scripts/export_openapi_from_java.py --source <Java文件或目录> --save-metadata
也支持 stdin + 自动落 metadata：
python skills/ac-api/scripts/generate_openapi.py --input - --save-metadata <<'EOF'
{
"serviceFqcn": "base.business.energy.service.BusinessCenter4EVChargingStation",
"serviceName": "BusinessCenter4EVChargingStation",
"methodName": "overviewEVChargingStation",
"businessMethod": "overviewEVChargingStation",
"summary": "充电桩概况",
"description": "充电桩概况",
"returnType": "EVOverviewEVChargingStationDTO",
"returnDesc": "EvChargingStationPowerDataStatistics",
"parameters": [
{
"name": "vo",
"type": "EVSPageRspVO",
"example": {
"projectId": 1
}
}
],
"responseExample": {},
"evidence": [
"src/main/java/.../BusinessCenter4EVChargingStation.java:42"
]
}
EOF
开启 --save-metadata 后，脚本会在同目录额外写出一个 .metadata.json，方便追溯来源。
在调用脚本前，先整理一个小型元数据 JSON，再交给脚本生成最终 OpenAPI 文件。
最小示例：
{
"serviceFqcn": "base.business.energy.service.BusinessCenter4EVChargingStation",
"serviceName": "BusinessCenter4EVChargingStation",
"methodName": "overviewEVChargingStation",
"businessMethod": "overviewEVChargingStation",
"summary": "充电桩概况",
"description": "充电桩概况",
"returnType": "EVOverviewEVChargingStationDTO",
"returnDesc": "EvChargingStationPowerDataStatistics",
"parameters": [
{
"name": "vo",
"type": "EVSPageRspVO",
"example": {
"projectId": 1
}
}
],
"responseExample": {},
"evidence": [
"src/main/java/.../BusinessCenter4EVChargingStation.java:42"
]
}
脚本会自动生成：
| 项 | 规则 |
|---|---|
| 输出目录 | .claude/OpenAPI/YYYY-MM-DD/ |
| 文件名 | HH-MM_BusinessCenter.method.openapi.json |
| metadata 文件 | HH-MM_BusinessCenter.method.metadata.json（仅 --save-metadata 时生成） |
openapi | 3.1.0 |
servers[0].url | http://127.0.0.1:8888 |
paths | 只生成一个 /json-adapter |
operationId | BusinessCenter.method |
如果用户明确要求时间戳一致，可在同一轮导出时复用同一个分钟值。
先确认目标是哪个 Service、哪个方法、哪个模块。
只读取当前接口生成所必需的代码证据：
@BusinessCenterDescriptor 所在类/接口@BusinessDescriptor 所在方法约束：
整理最小 metadata 后，直接调用脚本生成，不做额外往返检查。
最小 metadata 至少包含：
| 项 | 内容 |
|---|---|
serviceFqcn | Service 全限定名 |
serviceName | Service 短名 |
methodName | Java 方法名 |
businessMethod | @BusinessDescriptor.name 或方法名 |
summary | 业务描述 |
description | 业务描述或补充说明 |
returnType | Java 返回类型 |
returnDesc | @BusinessDescriptor.returnDesc |
parameters | 参数名、类型、示例 |
responseExample / responseSchema | 有则提供 |
evidence | file_path:line_number |
推荐命令：
python skills/ac-api/scripts/generate_openapi.py --input <metadata.json> --save-metadata
或：
python skills/ac-api/scripts/generate_openapi.py --input - --save-metadata
仅当用户明确要求“直接从 Java 一条龙导出”时，才使用：
python skills/ac-api/scripts/export_openapi_from_java.py --source <Java文件或目录> --save-metadata
执行脚本后，直接返回：
bid不要做这些事：
generate_openapi.py / export_openapi_from_java.py.openapi.json / .metadata.json只有在调试 skill 本身或脚本报错排查时，才允许例外。
先给出结果摘要表：
| 项目 | 内容 |
|---|---|
| 输出文件 | <实际文件路径> |
| OpenAPI 版本 | 3.1.0 |
| 请求地址 | http://127.0.0.1:8888/json-adapter |
| 接口名称 | <summary> |
bid | <serviceFqcn>.<businessMethod> |
| 证据 | file_path:line_number |
然后补充：
file_path:line_number）@BusinessCenterDescriptor：告诉用户当前代码不符合 SKSPIOT 规则，或需补充目标位置@BusinessDescriptor：告诉用户未发现可暴露的方法，并给出已检查的位置bid：列出冲突点并提问