dsh-apis-plugin 0.1.9 → 0.1.11
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 +6 -1
- package/api-tools.js +30 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -102,7 +102,12 @@ agent 调用 `{prefix}_api_doc` 时按路径命中对应小节返回。
|
|
|
102
102
|
| `api_api_doc` | 查接口文档:传 `path` 返回该接口的参数与响应说明;不传返回通用说明和已配置接口目录 |
|
|
103
103
|
| `api_api_request` | 真正调用接口:`path` 必须在白名单内,GET 用 `query`,POST 用 `body` |
|
|
104
104
|
|
|
105
|
-
超出 api.cfg
|
|
105
|
+
超出 api.cfg 范围的请求(无论查文档还是发请求)会被直接拒绝,并提示可用接口列表。
|
|
106
|
+
|
|
107
|
+
安全机制:
|
|
108
|
+
|
|
109
|
+
- **删除接口二次确认**:调用 `DELETE` 时首次只返回确认提示,不会执行;需携带 `confirm=true` 再次调用才会真正执行
|
|
110
|
+
- **写操作警告**:`POST` / `PUT` / `PATCH` 的返回结果前会附带警告块,明示将执行的接口、完整地址与参数
|
|
106
111
|
|
|
107
112
|
## 排查
|
|
108
113
|
|
package/api-tools.js
CHANGED
|
@@ -164,6 +164,9 @@ export function defineApiPlugin(options) {
|
|
|
164
164
|
return bootEndpoints
|
|
165
165
|
}
|
|
166
166
|
|
|
167
|
+
// 删除操作的待确认记录(key: "DELETE <完整地址>"):只有先收到过确认提示,confirm=true 才会放行
|
|
168
|
+
const pendingDeletes = new Set()
|
|
169
|
+
|
|
167
170
|
// 工具 1:查接口文档,让模型了解每个接口的参数与响应(prompt 按领域名拼接)
|
|
168
171
|
ctx.tools.register({
|
|
169
172
|
name: `${prefix}_api_doc`,
|
|
@@ -178,6 +181,10 @@ export function defineApiPlugin(options) {
|
|
|
178
181
|
return '【通用说明】\n' + (docSections[0] ?? '') + '\n\n【已配置接口目录】\n' + list.join('\n')
|
|
179
182
|
}
|
|
180
183
|
const norm = ('/' + args.path.trim().replace(/^\/+/, '')).split('?')[0]
|
|
184
|
+
// 查询范围严格限制在已配置列表内:列表外的接口一律拒绝
|
|
185
|
+
if (!list.some((e) => matchEndpoint(norm, e))) {
|
|
186
|
+
return `接口 ${norm} 不在已配置列表中,已拒绝查询。可用接口:\n` + list.join('\n')
|
|
187
|
+
}
|
|
181
188
|
const hit = docSections.filter((s) => s.includes('`' + norm + '`'))
|
|
182
189
|
if (hit.length) return hit.join('\n\n---\n\n')
|
|
183
190
|
return `文档中未找到 ${norm}。已配置接口目录:\n` + list.join('\n')
|
|
@@ -187,12 +194,13 @@ export function defineApiPlugin(options) {
|
|
|
187
194
|
// 工具 2:真正调用接口拿数据(prompt 按领域名拼接)
|
|
188
195
|
ctx.tools.register({
|
|
189
196
|
name: `${prefix}_api_request`,
|
|
190
|
-
description: `调用${domainName}接口并返回 JSON 数据。path 必须是已配置的接口(支持 /orders/{id} 这类模板路径,模板段填实际值);GET 用 query 传参,POST 用 body 传 JSON
|
|
197
|
+
description: `调用${domainName}接口并返回 JSON 数据。path 必须是已配置的接口(支持 /orders/{id} 这类模板路径,模板段填实际值);GET 用 query 传参,POST 用 body 传 JSON。安全规则:① DELETE 属于危险操作,首次调用只返回确认提示不会执行,必须先向用户二次确认,用户明确同意后才能携带 confirm=true 再次调用;② 返回结果若以 ⚠️ 开头(写操作警告/危险操作确认),必须在回复中原样向用户展示警告块内容(含接口、方法、完整地址与参数),不得省略、转述或只报结果。请依据 ${prefix}_api_doc 返回的文档构造请求,文档即权威,无需从源码核实接口行为。`,
|
|
191
198
|
parameters: {
|
|
192
199
|
path: { type: 'string', required: true, description: '接口路径,如 /users/detail 或 /orders/123' },
|
|
193
200
|
method: { type: 'string', description: 'HTTP 方法,默认 GET' },
|
|
194
201
|
query: { type: 'json', description: 'query 参数对象,如 { "keyword": "abc" }' },
|
|
195
202
|
body: { type: 'json', description: 'POST 请求体(JSON 对象)' },
|
|
203
|
+
confirm: { type: 'boolean', description: '删除操作的二次确认标记:仅在与用户确认且收到过确认提示后才能传 true;未经确认提示不得传' },
|
|
196
204
|
},
|
|
197
205
|
output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
|
|
198
206
|
async execute(args) {
|
|
@@ -215,6 +223,24 @@ export function defineApiPlugin(options) {
|
|
|
215
223
|
url.searchParams.set(k, String(v))
|
|
216
224
|
}
|
|
217
225
|
|
|
226
|
+
// 删除操作:两段式确认。首次调用只返回确认提示并记录待确认项;
|
|
227
|
+
// 即使模型首次就带 confirm=true,只要没有对应的待确认记录也一律拒绝执行
|
|
228
|
+
if (method === 'DELETE') {
|
|
229
|
+
const key = method + ' ' + url.toString()
|
|
230
|
+
if (args.confirm === true && pendingDeletes.has(key)) {
|
|
231
|
+
pendingDeletes.delete(key)
|
|
232
|
+
} else {
|
|
233
|
+
pendingDeletes.add(key)
|
|
234
|
+
return `⚠️【危险操作确认】本次将执行删除接口:\n ${method} ${url.toString()}\n` +
|
|
235
|
+
'该操作可能不可恢复。请先向用户二次确认;用户同意后,携带 confirm=true 重新调用本工具才会真正执行。'
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
// 写操作:在结果前向用户明示将执行哪个接口
|
|
240
|
+
const writeWarn = ['POST', 'PUT', 'PATCH'].includes(method)
|
|
241
|
+
? `⚠️【写操作警告】本次请求将执行接口:${method} ${url.toString()}(query: ${JSON.stringify(args.query ?? {})};body: ${JSON.stringify(args.body ?? null)})\n\n`
|
|
242
|
+
: ''
|
|
243
|
+
|
|
218
244
|
const response = await fetch(url, {
|
|
219
245
|
method,
|
|
220
246
|
headers: { Accept: 'application/json', ...(args.body != null ? { 'Content-Type': 'application/json' } : {}) },
|
|
@@ -223,10 +249,11 @@ export function defineApiPlugin(options) {
|
|
|
223
249
|
const text = await response.text()
|
|
224
250
|
|
|
225
251
|
if (!response.ok) {
|
|
226
|
-
return `HTTP ${response.status} ${response.statusText}\n` + text.slice(0, 4000)
|
|
252
|
+
return writeWarn + `HTTP ${response.status} ${response.statusText}\n` + text.slice(0, 4000)
|
|
227
253
|
}
|
|
228
254
|
// 非文件流接口直接返回 JSON 文本,超长截断
|
|
229
|
-
|
|
255
|
+
const result = text.length > 30000 ? text.slice(0, 30000) + '\n…(超长截断)' : text
|
|
256
|
+
return writeWarn + result
|
|
230
257
|
},
|
|
231
258
|
})
|
|
232
259
|
|