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