dsh-apis-plugin 0.1.5 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +118 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1 +1,119 @@
|
|
|
1
1
|
# dsh-apis-plugin
|
|
2
|
+
|
|
3
|
+
通用接口管理插件（DeepSeek Harness / Cordis 双面插件）：把任意一套 HTTP 接口注册成 agent 可用的**文档查询 + 请求调用**双工具。
|
|
4
|
+
|
|
5
|
+
核心约定：**`api.cfg` 是接口的唯一权威范围**——agent 只能请求 api.cfg 中列出的接口，范围外一律拒绝。
|
|
6
|
+
|
|
7
|
+
## 安装
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
dsh plugin --profile web add dsh-apis-plugin
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
安装后重启 `dsh web` 生效。指定版本：
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
dsh plugin --profile web add dsh-apis-plugin@0.1.6
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## 配置
|
|
20
|
+
|
|
21
|
+
建议把 `api.cfg` 和 `api_doc.md` 一起放在同一个目录下（如项目的 `config/` 目录），然后在插件配置页把「API配置」指向该目录：
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
config/
|
|
25
|
+
├── api.cfg # 接口清单
|
|
26
|
+
└── api_doc.md # 接口文档
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### 1. api.cfg（接口清单，必需）
|
|
30
|
+
|
|
31
|
+
key=value 行格式，`#` 注释，UTF-8 编码：
|
|
32
|
+
|
|
33
|
+
```ini
|
|
34
|
+
# 接口服务前缀：域名 + nginx 前缀 + 网关路由段
|
|
35
|
+
baseUrl=http://your-host/prod-api
|
|
36
|
+
|
|
37
|
+
# 接口列表：apis= 下面逐行一个接口
|
|
38
|
+
apis=
|
|
39
|
+
/users/page
|
|
40
|
+
/users/{id}
|
|
41
|
+
/outline/page
|
|
42
|
+
/outline/detailByNos
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- `baseUrl`：请求时拼接在接口路径前（改文件即生效，无需重启）
|
|
46
|
+
- `apis`：接口白名单，支持 `{param}` 模板段（如 `/users/{id}`），agent 请求时填实际值
|
|
47
|
+
- **增删接口只改这个文件**，改完点插件配置页的「加载API」（或重启）生效
|
|
48
|
+
|
|
49
|
+
### 2. api_doc.md（接口文档，建议提供）
|
|
50
|
+
|
|
51
|
+
与 `api.cfg` 放在一起。用 `---` 分节，每节描述一个接口，节内用反引号标注接口路径：
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
## 通用说明
|
|
55
|
+
|
|
56
|
+
所有接口返回 JSON，需携带 token。
|
|
57
|
+
|
|
58
|
+
## 分页查询用户
|
|
59
|
+
|
|
60
|
+
- 路径：`/users/page`（GET）
|
|
61
|
+
- 参数：keyword（可选）、page、pageSize
|
|
62
|
+
|
|
63
|
+
## 用户详情
|
|
64
|
+
|
|
65
|
+
- 路径：`/users/{id}`（GET）
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
|
|
69
|
+
|
|
70
|
+
### 3. 部署侧 cordis.patch.yml（可选覆盖）
|
|
71
|
+
|
|
72
|
+
```yaml
|
|
73
|
+
- insert:
|
|
74
|
+
- id: dsh-apis-plugin
|
|
75
|
+
name: dsh-apis-plugin
|
|
76
|
+
config:
|
|
77
|
+
domain: "用户中心" # 领域名：拼进工具描述 prompt
|
|
78
|
+
toolPrefix: api # 工具名前缀：生成 api_api_doc / api_api_request
|
|
79
|
+
apiDir: "" # api.cfg / api_doc.md 默认目录（留空则在 UI 里填）
|
|
80
|
+
endpoints: [] # yml 侧额外固定接口
|
|
81
|
+
baseUrl: "" # 服务前缀兜底（api.cfg 优先）
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## 使用
|
|
85
|
+
|
|
86
|
+
### Web UI（设置 → 插件 → 插件配置）
|
|
87
|
+
|
|
88
|
+
| 操作 | 说明 |
|
|
89
|
+
|---|---|
|
|
90
|
+
| API 配置 | 填 api.cfg / api_doc.md 所在目录，**失焦或回车自动保存** |
|
|
91
|
+
| 加载API | 重扫目录：接口列表严格等于当前 api.cfg 内容 |
|
|
92
|
+
| 接口列表 | 只读展示，增删请在 api.cfg 中操作 |
|
|
93
|
+
|
|
94
|
+
### Agent 工具
|
|
95
|
+
|
|
96
|
+
插件向 agent 注册两个工具（`{prefix}` 默认 `api`）：
|
|
97
|
+
|
|
98
|
+
| 工具 | 用途 |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `api_api_doc` | 查接口文档：传 `path` 返回该接口的参数与响应说明；不传返回通用说明和已配置接口目录 |
|
|
101
|
+
| `api_api_request` | 真正调用接口：`path` 必须在白名单内，GET 用 `query`，POST 用 `body` |
|
|
102
|
+
|
|
103
|
+
超出 api.cfg 范围的请求会被直接拒绝，并提示可用接口列表。
|
|
104
|
+
|
|
105
|
+
## 排查
|
|
106
|
+
|
|
107
|
+
dsh 控制台日志：
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
[dsh-apis-plugin] loaded; endpoints=N, doc sections=M
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- `endpoints=0`：检查 API 目录路径是否正确、api.cfg 是否与目录同级
|
|
114
|
+
- 加载后列表与 api.cfg 不一致：确认已在配置页点过「加载API」
|
|
115
|
+
- 提示未配置 baseUrl：在 api.cfg 写入 `baseUrl=http://...`
|
|
116
|
+
|
|
117
|
+
## License
|
|
118
|
+
|
|
119
|
+
MIT
|