dsh-apis-plugin
通用接口管理插件（DSH 插件）：把任意一套 HTTP 接口注册成 agent 可用的文档查询 + 请求调用双工具。
核心约定：api.cfg 是接口的唯一权威范围——范围外的请求一律拒绝。
版本兼容
需要 DSH >=0.1.7-rc.2（详情页徽章据此显示）。DSH 0.1.5 / 0.1.6 请用旧版 dsh-apis-plugin@0.2.3。
安装
dsh plugin --profile web add dsh-apis-plugin@0.3.1
配置
「API配置」指向一个集合父目录，插件递归扫描其下所有 *.cfg，每个 cfg 是一个集合（集合名取 cfg 的 host 字段）：
config/
├── site-a.example.com/
│ ├── api.cfg # host=site-a.example.com
│ └── api_doc.md # 该集合的接口文档
└── site-b.example.com/
├── api.cfg
└── api_doc.md
api.cfg（每个集合一份，必需）
# 集合标识（如域名），用于展示与「集合名/路径」消歧
host=site-a.example.com
# 集合用途说明（可选），展示在接口目录与手风琴中
title=xxx
# 该集合的接口服务前缀
baseUrl=http://your-host/api
# 接口白名单：逐行一个，支持 {param} 模板段
apis=
/users/page
/users/{id}
改 cfg 后点插件详情页的「扫描」（或重启）生效。
api_doc.md（接口文档，建议提供）
与 api.cfg 放在一起，用 --- 分节，每节描述一个接口，节内用反引号标注路径（如 `/users/page`）。agent 调用 {prefix}_api_doc 时按路径命中对应小节返回。
部署侧 cordis.patch.yml（可选）
- insert:
- id: dsh-apis-plugin
name: dsh-apis-plugin
config:
domain: "用户中心" # 领域名：拼进工具描述 prompt
toolPrefix: api # 工具名前缀：生成 api_api_doc / api_api_request
apiDir: "" # 集合父目录默认值（留空则在 UI 里填）
endpoints: [] # 额外固定接口（不随扫描回写）
baseUrl: "" # 服务前缀兜底（api.cfg 优先）
使用
Web UI（设置 → 接口管理）
| 操作 | 说明 |
|---|
| API配置 | 填集合父目录，失焦或回车自动保存 |
| 扫描 | 重扫目录；目录留空点击则清空列表 |
| 集合手风琴 | 展示集合名、用途、接口数、baseUrl 与接口列表（只读，增删请在 cfg 中操作） |
Agent 工具
| 工具 | 用途 |
|---|
api_api_doc | 查接口文档：传 path 返回该接口的参数与响应说明；不传返回全部接口目录 |
api_api_request | 调用接口：path 必须在白名单内，GET 用 query，POST 用 body |
- path 默认写接口路径（如
/users/page）；跨集合同名接口用「集合名/路径」消歧（如 site-a.example.com/users/page）
- 安全机制：
DELETE 需二次确认（首次只返回确认提示，确认后带 confirm=true 再调）；写操作返回结果附带警告块
排查
dsh 控制台日志：
[dsh-apis-plugin] loaded; apiDir=/path/to/config, endpoints=N, collections=a.com,b.com
endpoints=0：检查 apiDir 是否正确、其下是否有含 apis 的 *.cfg- 列表与 cfg 不一致：点「扫描」或重启
License
MIT
