dsh-apis-plugin

通用接口管理插件（DeepSeek Harness / Cordis 双面插件）：把任意一套 HTTP 接口注册成 agent 可用的文档查询 + 请求调用双工具。

核心约定：api.cfg 是接口的唯一权威范围——agent 只能请求 api.cfg 中列出的接口，范围外一律拒绝。

安装

dsh plugin --profile web add dsh-apis-plugin

安装后重启 dsh web 生效。指定版本：

dsh plugin --profile web add dsh-apis-plugin@0.1.6

配置

建议把 api.cfg 和 api_doc.md 一起放在同一个目录下（如项目的 config/ 目录），然后在插件配置页把「API配置」指向该目录：

config/
├── api.cfg      # 接口清单
└── api_doc.md   # 接口文档

1. api.cfg（接口清单，必需）

key=value 行格式，# 注释，UTF-8 编码：

# 接口服务前缀：域名 + nginx 前缀 + 网关路由段
baseUrl=http://your-host/prod-api

# 接口列表：apis= 下面逐行一个接口
apis=
  /users/page
  /users/{id}
  /outline/page
  /outline/detailByNos

• baseUrl：请求时拼接在接口路径前（改文件即生效，无需重启）
• apis：接口白名单，支持 {param} 模板段（如 /users/{id}），agent 请求时填实际值
• 增删接口只改这个文件，改完点插件配置页的「扫描」（或重启）生效

2. api_doc.md（接口文档，建议提供）

与 api.cfg 放在一起。用 --- 分节，每节描述一个接口，节内用反引号标注接口路径：

## 通用说明

所有接口返回 JSON，需携带 token。

## 分页查询用户

- 路径：`/users/page`（GET）
- 参数：keyword（可选）、page、pageSize

## 用户详情

- 路径：`/users/{id}`（GET）

agent 调用 {prefix}_api_doc 时按路径命中对应小节返回。

3. 部署侧 cordis.patch.yml（可选覆盖）

- insert:
    - id: dsh-apis-plugin
      name: dsh-apis-plugin
      config:
        domain: "用户中心"        # 领域名：拼进工具描述 prompt
        toolPrefix: api           # 工具名前缀：生成 api_api_doc / api_api_request
        apiDir: ""                # api.cfg / api_doc.md 默认目录（留空则在 UI 里填）
        endpoints: []             # yml 侧额外固定接口
        baseUrl: ""               # 服务前缀兜底（api.cfg 优先）

使用

Web UI（设置 → 插件 → 插件配置）

操作	说明
API 配置	填 api.cfg / api_doc.md 所在目录，失焦或回车自动保存
扫描	重扫目录：接口列表严格等于当前 api.cfg 内容；目录留空点击则清空列表
接口列表	只读展示，增删请在 api.cfg 中操作

Agent 工具

插件向 agent 注册两个工具（{prefix} 默认 api）：

工具	用途
api_api_doc	查接口文档：传 path 返回该接口的参数与响应说明；不传返回通用说明和已配置接口目录
api_api_request	真正调用接口：path 必须在白名单内，GET 用 query，POST 用 body

超出 api.cfg 范围的请求会被直接拒绝，并提示可用接口列表。

排查

dsh 控制台日志：

[dsh-apis-plugin] loaded; endpoints=N, doc sections=M

• endpoints=0：检查 API 目录路径是否正确、api.cfg 是否与目录同级
• 加载后列表与 api.cfg 不一致：确认已在配置页点过「扫描」
• 提示未配置 baseUrl：在 api.cfg 写入 baseUrl=http://...

License

MIT